@eigenpal/cli 0.23.3 → 0.23.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -20,7 +20,7 @@
20
20
  "title": "Changelog",
21
21
  "description": "Production release history for the EigenPal platform.",
22
22
  "source": "public",
23
- "content": "---\ntitle: Changelog\ndescription: Production release history for the EigenPal platform.\n---\n\nEigenPal ships on a unified platform version. Each production release updates Studio, the public API, infrastructure, and (when applicable) the CLI and SDKs together.\n\n{/* GENERATED:CHANGELOG_INDEX START */}\n\n## 0.23.3 (2026-11-10)\n\n### Platform (Studio)\n\n- Add Claude Fable 5.2 for workflow steps, structured extraction, vision, judges and agents, with every reasoning effort level from low to max. It costs less per token than Fable 5.1 and replaces it as the recommended Fable model. Existing default model selections and workflows that name Fable 5.1 stay unchanged.\n\n### CLI\n\n- The bundled self-hosting docs in `eigenpal docs` now describe the install preflight check and how to run it on its own.\n\n### Infrastructure & processing\n\n- Self-hosted installs now run a read-only preflight check before migrations. It confirms that every Secret value is present, that CA bundles and client certificates are valid (with an optional expected certificate name), and that the database, object storage, model gateway, OCR, sign-in and file source services are reachable over TLS. It prints one result per check with a fix for each failure, never prints a secret value, and stops an install or Argo CD sync before anything changes. It can also be run on its own the day before an install.\n\n---\n\n## 0.23.2 (2026-11-09)\n\n### Platform (Studio)\n\n- The Monitoring page now uses the searchable automation picker, which lists workflows and agents together, sorted by name and marked by icon. The same list now appears on the Trigger, Reviews and Connect pages. The rolling window control no longer cuts off its slider labels.\n\n---\n\n## 0.23.1 (2026-11-09)\n\n### Platform (Studio)\n\n- On self-hosted installs, the admin set by `EIGENPAL_ADMIN_EMAIL` is now always an owner. Changing that email used to create the new account as a plain member when the organization already had an owner. The previous owner keeps its role until someone removes it.\n- Every section on the Environments page now opens and closes from its header, which keeps its count. Sections that need someone (awaiting approval, needs attention, in progress) start open; Ready to promote and History start closed so a long list no longer pushes active releases down. Each person's choice is remembered in their browser. Links to a section, and filtering by a workflow, open the sections they point into.\n- The published OpenAPI document lists `tree` on the folder list route as `true` or `false`.\n- Environments: each workflow's environment panel now shows what an environment runs apart from the release on its way into it, with that release's version, its status and a link to its merge request. Only the environment the current release goes into shows it as under way; an older release still waiting elsewhere is named with its version. Statuses read the same in the panel, on the Environments page and in each environment's comment on the request (\"Ready to release, waiting for approval and a merge in Git\"), and amber now only marks what needs a look. The panel's release list also includes releases still on their way, so a version live in some environments no longer disappears from it.\n- Buttons and form controls use consistent heights and corners across Studio, making actions easier to scan and use together.\n\n### Public API\n\n- `GET /api/v1/folders` now rejects a `tree` value other than `true` or `false` with a 400. Any other value used to be silently treated as `false`.\n\n### SDK\n\n- `folders.list` types `tree` as `'true' | 'false'` to match the API, which now rejects any other value.\n\n---\n\n## 0.23.0 (2026-11-06)\n\n### Platform (Studio)\n\n- Anyone with Editor access can again move a workflow or folder out of an open top-level folder. Moving something out of a private top-level folder still needs Manager access on that folder.\n- Share any folder or workflow inside a folder with more people, as narrowly as needed: a grant on one workflow opens just that workflow (with its runs, files and reviews), and a grant on a subfolder opens just that subfolder. Grants only add to what an item inherits; only top-level folders and workflows can be private, and inside a folder a grant goes up to Editor and is for named people and groups. Folders around a shared item stay hidden: people find it under **Shared with you**, and the path above shows as \"Private folder\". The access panel of an item inside a folder shows what it inherits, naming the folder each grant comes from, and lets you add people under **Also shared with**. Moves keep an item's own grants and show, person by person, who gains, loses or drops a level before you confirm. Check access says where a grant is set.\n- **Breaking (promotion config):** workflow promotion is configured with `promotion.repositories`, and the previous shape no longer loads. Declare each Git repository once by a short name (`project`, `branch`, optional `provider` and `apiUrl`), give every environment the `repository` it is kept in and the `bot` it writes as there (required, and unique per environment), use `acceptsFrom` where the environment before writes from another repository, and `releasedWith: &lt;env&gt;` for an environment released by the same request as the one before it. Each installation holds one token per repository, `secrets.promotionTokens.&lt;repository&gt;` in Helm (`repositories.&lt;name&gt;.token` in the app config), with the same keys in every installation. `promotion.git`, `environments[].git`, `gitIdentity`, `requestsFrom`, `withPrevious`, `approvers`, `secrets.promotionToken` and `secrets.promotionAppKey` are removed: a config that still uses them fails at startup and in `helm template` with how to migrate it. Releases can cross into a Git repository another team owns. The environment before opens the release there with its token for that repository, carrying the version's files, its rollout and its Git LFS dataset files. Several environments can be released by one request: each checks it, reports its own status, and all of them go live once it merges. An environment whose token may not merge into its branch, such as a GitLab Developer on a branch only Maintainers merge, never tries: it reports its status and goes live once someone merges it in Git. Every installation shows the status of every environment it holds a read token for; without one, those environments show as not visible from here. The setup check lists every repository with the token used, the user it writes as, and whether its rights match what the installation needs there: write in its own repository and the next environment's, read elsewhere. The promotion webhook takes one secret per installation (Helm default: Secret `eigenpal-promotion`, key `webhook-secret`, next to the token keys) and matches each event to its repository by project path.\n- Workflow cards no longer overflow: long names wrap at underscores and dashes, the version and API badges sit on their own line, and the step dots are replaced by a step count. The workflow menu uses the newer dropdown with grouped actions, a Connect (API) link, and copyable workflow ID and API target. In the editor, workflow settings (General, Model, Retries, Triggers, Variables, Access) sit in a floating bar at the top right of the canvas that expands into the side panel, the Access icon shows whether the workflow is private, shared or open to everyone, and the header keeps only Run, Save / Save version and the actions menu. Everything clickable shows a pointer. Config-defined file sources show a lock and explain that they are edited in the deployment configuration.\n\n### Public API\n\n- `GET /api/v1/automations` and `GET /api/v1/automations/:id` no longer name folders the caller cannot open. For a workflow shared with you inside such a folder, `folderId` is `null`, and `folderPath` is `null` whenever any folder on the path is hidden from you.\n\n---\n\n## 0.22.8 (2026-11-06)\n\n### Platform (Studio)\n\n- Reviewers can work their human review queue again: opening, editing, approving and rejecting review tasks no longer needs workflow permissions, which the Reviewer role does not have. Viewers see review tasks read-only, without Approve, Reject or field edits the API would refuse, and roles that cannot cancel runs no longer see Cancel on a review. Organization-level role checks now come from one capability map shared by the API and the dashboard (`requireCapability` and `useCan`), so settings, members, invites, service accounts, billing, promotion and webhook controls show exactly what the API allows. Admins can no longer sign out another admin or an owner everywhere; owners can sign out anyone, and anyone can sign themselves out. Dataset reviews are read-only for viewers, matching the API. `/api/v1/files` answers 404 for files of workflows you cannot open and needs editor access to delete them. In OpenParser Studio, receipts and payment methods are for owners and admins, while members can still add funds.\n- Dataset example files whose names contain spaces, accents or parentheses open, download, rename and delete again from the examples list and from dataset reviews. Before, their preview showed \"Failed to fetch file: 400 Bad Request\" (and dataset reviews showed the file as missing), even though running the example worked.\n- Let owners and admins delete the Studio copy of a file source that the deployment configuration overrides from its detail panel, not only from the row menu. Deleting a name that only the deployment configuration defines now answers 409 instead of reporting success, an unknown name answers 404, and the delete dialog shows the server's reason when a delete fails.\n- Organization admins can set a monthly spend cap for Pro pay-as-you-go usage. Track the remaining cap in Settings and stop extra charges at your chosen limit.\n\n### Public API\n\n- Example and dataset review file endpoints under `/api/v1/automations/:id` now serve, rename, delete and upload files whose names contain spaces, accents or parentheses, instead of answering 400 or 404.\n\n---\n\n## 0.22.7 (2026-11-05)\n\n- Internal improvements.\n\n---\n\n## 0.22.6 (2026-11-05)\n\n### Platform (Studio)\n\n- Group promotion dataset comparisons into expandable examples with change indicators. Keep comparison tabs and icon controls for diff layout and line wrapping in the fixed sheet header, and remove redundant explanatory text. Show existing environment variables as compact resolved rows and protect global and shared values from accidental edits. Existing secrets remain hidden and need no replacement. Automatically connect a released workflow to an existing variable used by its declared sharing partners, while keeping unrelated variables separate and preserving existing values.\n- Show first workflow releases awaiting checks or approval in the receiving environment, even before that workflow first goes live. Keep open request reports, counts, and links consistent across release views.\n- Fix releases held for missing settings: a request names everything that is still missing and why a file source that exists cannot be used (turned off or invalid), and it is checked again on every pull as the list changes. A held older version no longer hides the release form for a newer one, and the release button names the next environment.\n- Show a release request that a newer version replaced as \"Superseded by vX\" and one closed without merging as \"Cancelled\", stop reporting its stopped checks as failed, list each release only under In progress or in the History, and link running checks to their live evaluation. Improve environment and promotion navigation on desktop and narrow screens, distinguish saved versions from promotions, compare the complete release package, and connect release checks to their batch and run evidence. Surface blocked incoming releases with recovery links, preserve historical live-version context, and clarify Git-managed configuration, status refresh failures and approval requirements. Explain release-check failures directly in run details with recorded evaluator mismatches and expected versus actual JSON from the immutable release snapshot. Keep trigger labels consistent and evaluation requirements readable on narrow screens. Unify release rows around aligned environment pipelines, remove duplicate listings, and resolve missing variables or file sources directly from the release page. Recognize dashboard-managed file sources, retry failed checks without losing earlier runs or changing the release URL, and publish evaluation progress through durable completion notifications. Simplify the promotion sheet and open it directly from Environments. Treat valid enabled file source connections from deployment configuration and Studio equally, remove the redundant FILE_SOURCE_INTEGRATIONS switch, and show Config or Studio origin badges while keeping configuration entries read-only. Existing deployments can remove the obsolete switch. Compare workflow, dataset, evaluator and settings contents in tabbed Pierre views, including unchanged files, with inline or side-by-side diffs and a compact promotion form. Reuse existing environment variables safely without replacing concurrent workflow bindings, and keep release navigation unfiltered.\n\n### Public API\n\n- Run lists now show the workflow's name for release-check runs instead of an internal identifier.\n\n### CLI\n\n- Bundled self-hosting documentation describes the per-value Secret references and the optional External Secrets support of the Helm chart.\n\n### Infrastructure & processing\n\n- Self-hosted Helm installations name each secret value on its own: a Secret and a key per value, so credentials can be grouped into Secrets however your platform team prefers, or filled from Vault through the External Secrets Operator, which the chart can now configure. Storage location, owner email and other settings that are not secret move into plain chart values, and a missing value stops the install with a message naming it. Existing values files need the new keys; see the Helm values reference.\n\n---\n\n## 0.22.5 (2026-11-05)\n\n- Internal improvements.\n\n---\n\n## 0.22.4 (2026-11-04)\n\n### Platform (Studio)\n\n- Honor merged workflow releases even when checks fail, record overridden failures, and show queued checks accurately.\n\n### CLI\n\n- Bundled self-hosting documentation now covers OCI chart mirroring and Argo CD multi-source installations with environment values stored in Git.\n\n### Infrastructure & processing\n\n- Self-hosted installations can pull versioned Helm charts from an OCI registry, mirror them into an internal registry, pin app and worker images by digest, and use existing TLS certificate Secrets for OpenShift Routes.\n\n---\n\n## 0.22.3 (2026-11-04)\n\n### Platform (Studio)\n\n- Apply published per-request long-context credit rates to GPT-6 Astra, GPT-6.1 Sol and GPT-6 Luna. Above 272,000 input tokens including cache reads and writes, input/cache rates double and output rates increase by 50%. Existing ledger entries are unchanged.\n- Promotion fixes found in the first on-prem rollout: release checks work on self-managed GitLab versions that answer 500 to the merge request diffs endpoint with `per_page=100` (the file list is read at the endpoint's page size, falls back to comparing the two commits, and refuses to pass a cut-off list); a request that cannot be checked is shown on the Environments page instead of only in the log; admins get a \"Check now\" button; the Environments page marks the current environment and links to other environments' Environments page; the approval-rules note is advisory; the helm chart's cron jobs run from the worker image with Bun (no wget or utility image needed), and app and worker accept extra volumes.\n\n### Infrastructure & processing\n\n- Apply published per-request long-context credit rates to GPT-6 Astra, GPT-6.1 Sol and GPT-6 Luna. Above 272,000 input tokens including cache reads and writes, input/cache rates double and output rates increase by 50%. Existing ledger entries are unchanged.\n\n---\n\n## 0.22.2 (2026-11-03)\n\n### Platform (Studio)\n\n- Environments no longer record anything outside the pull or merge request that moves a version into them. The `eigenpal/reports` branch (GitLab) and the deployment reports (GitHub) are gone, and so is the inventory every environment published for the others. Each environment keeps one comment on the request, with the state of the release hidden in it for the first environment to read: how its checks went, where the release ended up, what it lacks. What each environment runs is its pin on the main branch. The release screen shows a held release with what is missing and links \"Define in T\" with the variable's type and sharing filled in. The Variables page no longer shows later environments (nothing about them is read ahead of a release). The next environment accepts a release request only from the previous environment's own Git identity, and `gitIdentity` is now the username a token writes as (a GitLab bot user, a GitHub login) rather than a commit email. The setup page checks that identity. GitHub credentials no longer need the Deployments permission.\n\n---\n\n## 0.22.1 (2026-11-03)\n\n### Platform (Studio)\n\n- Releasing workflows between environments can now keep each workflow's dataset files in the release repository with Git LFS, next to the workflow they belong to. Environments then need nothing beyond access to the repository: no shared bucket, no shared storage credentials, and dataset changes are reviewed in the same request as the workflow change. Set `promotion.artifactStore.git: true` (a shared bucket or directory remains available). What a release replaces in an environment is now kept in that environment's own storage instead of a shared one. A release lists the variables a workflow needs in its own `envVars` list, with their type and whether each is an organization variable, one of the workflow's own, or one shared with other workflows (so a higher environment can set it up the same way); environments no longer publish their file sources to each other, and an environment's setup page shows when it last checked Git. The release manifest restarts at format 1 and releases written by earlier builds are no longer read: release again after upgrading every environment.\n- Editing a variable that is shared by several workflows from the workflow editor no longer removes it from the other workflows, and taking a workflow off a variable now asks for confirmation first. The Workflow variables list on the Variables page can now be searched and filtered by workflow.\n- Choosing workflows for a variable (and any other long multi-select list) now has a search box, and the list scrolls instead of running off the screen.\n\n---\n\n## 0.22.0 (2026-11-03)\n\n#### Upgrading self-hosted installations\n\nThis release tightens the self-hosted deployment contract. Back up the database, object storage, repository volumes and persisted secrets, then render or start the new release with your existing configuration and fix each reported validation error.\n\n**Every installation**\n\n- Configure a model registry (`config.models` in Helm, `models:` in `eigenpal.config.yaml`). There is no default cloud model.\n- Agent builder storage mounts need a scoped credential issuer: `SANDBOX_STORAGE_STS_ROLE_ARN`, or `SANDBOX_STORAGE_R2_ACCOUNT_ID` with `SANDBOX_STORAGE_R2_API_TOKEN`. With static storage keys, the STS role must trust the IAM user that owns `S3_ACCESS_KEY`. Remove `SANDBOX_STORAGE_REQUIRE_SCOPED_CREDENTIALS`. The credential lifetime now defaults to 3600 seconds.\n- End existing builder sessions and rotate the storage credentials they received.\n- Remote sandboxes need matching random tokens of at least 32 characters in `SIDECAR_AUTH_TOKEN` and `SANDBOX_REMOTE_AUTH_TOKEN`, an upgraded sidecar with session leases, and `EIGENPAL_TENANT_MODE=single-tenant`.\n- Agents need a Git server (`AGENT_GIT_BASE_URL`). Set `EIGENPAL_AGENTS_ENABLED=false` where you do not operate one; it hides the Agents area, returns not found for agent API calls and refuses agent runs, and leaves workflows untouched. The default is true.\n- A missing file at `EIGENPAL_CONFIG_PATH` now stops startup.\n- The audit action `sandbox.unscoped_credentials_issued` is no longer emitted; retire alerts keyed on it.\n\n**Helm**\n\n- Install the versioned chart attached to the release; it defaults app and worker images to that release. `image.registry` defaults to the EigenPal registry; set your mirror or `''` for fully qualified repositories. `latest` image tags are rejected.\n- Set `secrets.cron.existingSecret` to a Secret holding `CRON_SECRET`, or set `maintenance.enabled: false` when your own scheduler calls housekeeping.\n- The chart does not install a Git server, so it now defaults `agents.enabled` to `false`. If you run agents against your own Git server, set `agents.enabled: true` and supply `AGENT_GIT_BASE_URL` and `AGENT_GIT_ADMIN_TOKEN` to app and worker through `extraEnv`.\n- Remove `worker.keda` and `sandboxStorage.requireScoped`. Unknown fields and duplicate environment variables fail validation.\n\n[View full release notes →](/releases/0.22.0)\n\n---\n\n## 0.21.0 (2026-11-02)\n\n### Platform (Studio)\n\n- Git-based environment management: run each of a customer's environments (named and ordered in Helm) as a separate installation and release workflows between them through a GitHub or GitLab repository that records which version runs where and who approved it. Each release opens a pull request (or merge request) per environment. That environment runs the workflow's checks on it, with the version's own dataset from Git and without touching what runs there, reports a commit status that approval rules can require, and keeps a comment on it up to date from \"Running checks\" to \"Live\". Both link to the release's Acceptance page, which shows every check and its result. The release goes live once the request is approved and merged. Triggers and the dataset travel with the version. Outbound webhook endpoints, their subscriptions, secrets and sharing stay local to each environment and are managed in the UI. Workflow access and groups stay local too: administrators configure each installation's folder and workflow sharing independently, directory-group membership comes from SSO, and EigenPal-defined groups keep local membership. New imported top-level folders and standalone workflows start private; updates preserve existing local access. Each environment supplies its own file-source connections. On GitHub and GitHub Enterprise Server, EigenPal can sign in as a GitHub App, so it comments and merges as a bot (`&lt;app&gt;[bot]`); on GitLab, a project or group access token does the same. After the first environment, workflows, their datasets and evaluators are read-only, with a link to edit them in the first. The Environments page shows what is in progress and the release history by workflow, and the release panel on each workflow links to it and lists its recent releases. A release that fails says why, naming the fields that did not match, and keeps saying so after a newer release replaces it. Repository notifications from GitHub or GitLab can start reconciliation promptly, with 15-minute fallback polling. Release intent is stored under `rollouts/`. Missing rollout intent or a closed promotion request shows why propagation has paused while preserving the version already live.\n- Service accounts: give each integration its own identity under **Settings → Service accounts**. A service account has a role and groups like a person but never signs in, and its calls appear in the audit log under its own name instead of the person who issued the key. Its keys keep working when that person leaves the organization. Create its keys from the service account or from **Developers → API keys**, with an expiry of up to a year or none.\n\n### Public API\n\n- In an installation whose workflows are released through Git-based environment management (every environment after the first), requests that change a workflow, its versions, evaluators or dataset answer 403 with a message naming the environment to make the change in. Reads and runs work as before; agents are not affected.\n\n### CLI\n\n- The CLI service account guide explains how to preserve key access during rotation and who can revoke admin service account keys.\n\n---\n\n## 0.20.99 (2026-10-29)\n\n### Platform (Studio)\n\n- OpenParser Studio opens faster: your organization is resolved on the server so pages no longer wait on a full-screen \"Loading organization\" step, switching organizations no longer reloads the page, and every page shows a skeleton of its layout while it loads. Billing, API keys and Organization arrive with their data already filled in.\n- Connect and workflow-specific OpenAPI and Swagger documentation list configured business rejections alongside successful results, technical failures, and cancellation. Each rejection includes its code, step, conditions, and message template. Resolvable subworkflow outcomes are included, and unresolved calls are marked explicitly. Business codes are documented inside HTTP 200 run responses. Contextual links make it easier to move between Connect, Swagger, workflow editors, selected subworkflows, and step documentation. Steps inheriting a retry policy can open the workflow's retry settings directly. Failed-run Output views and exports preserve the structured public error payload. Connect and scoped Swagger include individual standard processing failure examples and schemas and examples for documented HTTP request errors. Run-start OpenAPI declares conflict responses; rerun declares credit and conflict refusals so generated clients accept their documented envelopes.\n\n### Public API\n\n- Run errors include the configured business rejection code and step alongside a machine-readable failure code, message, and retryability. Read error.message instead of the previous string error. A successful API request can still report a failed run; business codes such as 422 are in error.statusCode, independently of the HTTP response status. The new Errors and recovery guide explains both kinds of outcome, available codes, and recovery behavior.\n- Connect and workflow-specific OpenAPI and Swagger documentation list configured business rejections alongside successful results, technical failures, and cancellation. Each rejection includes its code, step, conditions, and message template. Resolvable subworkflow outcomes are included, and unresolved calls are marked explicitly. Business codes are documented inside HTTP 200 run responses. Contextual links make it easier to move between Connect, Swagger, workflow editors, selected subworkflows, and step documentation. Steps inheriting a retry policy can open the workflow's retry settings directly. Failed-run Output views and exports preserve the structured public error payload. Connect and scoped Swagger include individual standard processing failure examples and schemas and examples for documented HTTP request errors. Run-start OpenAPI declares conflict responses; rerun declares credit and conflict refusals so generated clients accept their documented envelopes.\n\n### CLI\n\n- Run responses expose structured errors with a machine-readable code, message, retryability, and the configured business status code and step for workflow rejections. Update consumers of the previous string error to read error.message. HTTP success remains independent of the processing outcome.\n\n### SDK\n\n- Run responses expose structured errors with a machine-readable code, message, retryability, and the configured business status code and step for workflow rejections. Update consumers of the previous string error to read error.message. HTTP success remains independent of the processing outcome.\n\n---\n\n## 0.20.98 (2026-10-28)\n\n### Platform (Studio)\n\n- Workflow builder: a new Set Value step now starts with a field the step can run, filled from the step before it, instead of settings it ignored. A Merge step added after another step now merges that step's output instead of nothing, and the Merge docs list its `input` setting.\n- Summary agent reports: reviewer repairs are now applied before publication, the writer and reviewers work from a period-locked bank baseline read from the IBM workbook, the coverage reviewer checks every \"not available\" claim against the sources, and the writer spends part of its evidence pass on the narrative originals.\n\n---\n\n## 0.20.97 (2026-10-28)\n\n### Platform (Studio)\n\n- Workflow builder: the Add step menu is now a searchable picker with category tabs, keyboard navigation and a blurred backdrop. It suggests up to seven relevant next steps for each kind of step, including the first step of a workflow, and suggested loops and switches now come pre-filled from the step before them. Opening an Extract Data step no longer rewrites its schema (dropping settings such as fixed values) or marks the workflow unsaved, and undoing back to the saved version reads as saved again without a false \"Unsaved changes\" prompt. In Evals, the workflow name is shown read-only.\n- Security: fix sign-in vulnerabilities that could allow account takeover or bypass rate limits. On-prem OIDC administrators must register `/api/auth/callback/&lt;provider&gt;` with their identity provider before upgrading and restart pending sign-ins. Password sign-in and User Auth Service callback URLs are unchanged.\n- OpenParser Studio has a new Usage page: spend, pages and jobs by day for the last 7 days, 30 days or month to date, split into parsing and extraction, with a breakdown by model, pipeline and type. Each job in Jobs now shows what it cost, and a job's page breaks the charge down into parsing pages and extraction tokens.\n- Return the captured workflow version label and version ID in async run-start and rerun responses, including responses when a synchronous wait expires.\n- Workflow builder: the Extract Data and Inspect Pages schema editors now follow undo and redo instead of showing the previous fields, and editing a schema keeps enums exactly as written (numeric values stay numbers). Reverting an edit by hand reads as saved again, and the first step inside a loop or branch no longer suggests start-of-workflow steps.\n- Summary Agent: report runs no longer stop for recoverable reasons that needed a manual Continue. - A report writer no longer pauses with \"Context compaction did not complete\" when a background context summary fails while its history still fits, and it no longer summarizes away a draft it is correcting inside its save reserve. - A reviewer whose final reply comes back empty retries once within its allowance instead of pausing. - Re-publishing the already-published report is a no-op that tells the coordinator to finish, and a coordinator stuck on repeated tool errors after publication finishes instead of pausing. - Worksheet citations missing their `sheet:` prefix, such as `[D07 Financial Statement - manual]`, are saved under the exact sheet locator.\n\n### Public API\n\n- Return the captured workflow version label and version ID in async run-start and rerun responses, including responses when a synchronous wait expires.\n\n---\n\n## 0.20.96 (2026-10-28)\n\n### Platform (Studio)\n\n- Summary Agent: a report writer near the end of its allowance keeps enough requests to correct a rejected save instead of pausing after one attempt, figure links missing only their source prefix are saved under the exact figure ID, page lists such as `[D02 p12 p13]` are split into separate citations, and a paused run states why it paused. Clicking a citation in the report now highlights the cited passage in PDFs and web sources and the cited cells in workbooks, matching the sentence's figures across units (€ millions against EUR thousands) and locale formats. Elapsed times appear under written messages only.\n\n---\n\n## 0.20.95 (2026-10-27)\n\n### Platform (Studio)\n\n- Improve security of document processing, input validation and page configuration handling.\n- Summary Agent: reports finish reliably on the first run. The coordinator no longer audits sources itself; it applies reviewer repairs within a fixed allowance and then publishes instead of pausing. Research, writing and review have larger allowances, and source and document tools accept common argument variations instead of rejecting them. Edits that match are applied even when others in the same batch do not. The activity view is simpler: one orb for running work, flat grouped steps, quiet retry counts instead of error walls, no source index row, and elapsed time under each message that keeps counting across Continue.\n\n### Infrastructure & processing\n\n- Improve security of document processing, input validation and page configuration handling.\n\n---\n\n## 0.20.94 (2026-10-27)\n\n### Platform (Studio)\n\n- Add GPT-6.1 Terra for structured extraction, vision and agents, including its reasoning settings and published token prices. Existing default model selections stay unchanged.\n- Summary Agent: limit repetitive repair searches and provide clearer guidance when document edits cannot be applied. Research activity now groups queries and source links in a live, collapsible timeline, with named document updates, change previews and visible errors. Retry temporary model provider failures automatically for up to 30 minutes with a visible countdown. Preserve saved drafts and completed research when continuing interrupted reports, and allow longer model responses without consuming successful work allowances on connection failures.\n\n### CLI\n\n- Document how to select GPT-6.1 Terra for structured extraction, including reasoning settings and token prices.\n\n### Infrastructure & processing\n\n- Add GPT-6.1 Terra for structured extraction, vision and agents, including its reasoning settings and published token prices. Existing default model selections stay unchanged.\n\n---\n\n## 0.20.93 (2026-10-27)\n\n### Platform (Studio)\n\n- Show clear LLM provider connection errors with a Retry action that resumes saved work. Replace repeat generation with Start again, copying original inputs and report settings into an independent new session.\n\n---\n\n## 0.20.92 (2026-10-26)\n\n### Platform (Studio)\n\n- Report generation now prepares one complete draft for financial and coverage review, reducing repeated research and writing. The website displays the saved draft while review is in progress and updates it as supported corrections are applied. Public market research uses a bounded work allowance and saves supported findings with explicit evidence gaps. Unavailable source images are rejected before a draft is saved, and storage failures provide clearer diagnostics.\n\n---\n\n## 0.20.91 (2026-10-26)\n\n### Platform (Studio)\n\n- Public market research now uses a bounded work allowance and saves its supported findings with explicit evidence gaps, helping report generation proceed without an extended source-reading loop. Delegate financial chapters directly instead of requiring a shared baseline agent. Reject empty original-source scopes before evidence agents start, support Qwen thinking-mode tool calls, and allow the admitted report to finish within its existing lifetime request allowance without an artificial Continue boundary.\n- Keep PDF previews compatible with the updated document viewer.\n- Update cached editor folder breadcrumbs after moving a workflow through drag and drop or the Move dialog, without requiring a page refresh.\n- Workflow navigation now includes parent folders in the browser, Editor, and Evals, with a menu for deeper paths. Long conditions wrap within workflow cards so filter chains remain readable without spilling outside the card.\n\n### CLI\n\n- Refresh CLI dependencies for continued compatibility and maintenance.\n- Refresh CLI and SDK dependencies for continued compatibility and maintenance.\n\n### SDK\n\n- Refresh CLI and SDK dependencies for continued compatibility and maintenance.\n\n---\n\n## 0.20.90 (2026-10-25)\n\n### Platform (Studio)\n\n- Report citations use the text beside the clicked reference to locate a distinctive original passage instead of highlighting the start of every cited page. References without a reliable passage match open the page without a misleading highlight. Normal chat uses readable report labels instead of internal file and version codes, and newly published credit proposals omit the internal compaction label from their titles.\n\n---\n\n## 0.20.89 (2026-10-25)\n\n### Platform (Studio)\n\n- Workflow builder: script outputs typed `T | null` (for example `string | null`) now keep their type in autocomplete, the variable picker, the builder agent, API docs and generated SDK types instead of showing as `unknown`. Nullable objects stay navigable, so you can pick their nested fields.\n\n---\n\n## 0.20.88 (2026-10-25)\n\n### Platform (Studio)\n\n- Report generation hides redundant waiting activity when the specialist cards already show progress. Clearer rejection messages help the report assistant use each specialist's permitted capabilities and recover from invalid requests. Invalid illustration links are caught before publication so the assistant can correct them during the same run. Word preparation failures now return repairable errors instead of blocking the report as an unconfirmed publication; genuinely unconfirmed writes remain protected. Continuing a saved report can recover the known invalid-figure publication failure after verifying that no output was written. Completed chapters, reviews and saved work are retained.\n\n---\n\n## 0.20.87 (2026-10-25)\n\n### Platform (Studio)\n\n- Extraction: `ai.extract` and `ai.vision` no longer fail when a field the document does not contain comes back empty. Fields not listed in `required` may now be `null`, matching what the model is asked to return; required fields still must be present. The workflow builder shows these fields as `string | null`, and the builder agent keeps nullable values, identifiers and step settings correctly typed.\n\n### CLI\n\n- `eigenpal workflow validate` and `push` now warn about step settings that are silently ignored (for example `strategy` on a parse step or `outputSchema` on a script) and suggest the closest supported setting. The \"add an enum\" hint no longer fires on open-ended fields such as VINs, names, years and ids.\n\n### Infrastructure & processing\n\n- Extraction: `ai.extract` and `ai.vision` no longer fail when a field the document does not contain comes back empty. Fields not listed in `required` may now be `null`, matching what the model is asked to return; required fields still must be present. The workflow builder shows these fields as `string | null`, and the builder agent keeps nullable values, identifiers and step settings correctly typed.\n- Updated the email library (nodemailer) to a release that fixes how recipient addresses with comments, quoted text or `;` are parsed.\n\n---\n\n## 0.20.86 (2026-10-25)\n\n### Platform (Studio)\n\n- Updated the schema validation library (zod) to a release with a security fix. Email server settings keep their specific validation messages, such as rejecting SMTP credentials when security is set to none.\n\n### CLI\n\n- Refreshed the bundled skill reference so its schemas match the current validation rules.\n\n### SDK\n\n- An agent input or output schema that carries `.meta(\\{ id })` compiles again. With the updated validation library, its JSON Schema root came back as a reference instead of the object, and compiling failed with \"Root schema type must be object\".\n- Regenerated the SDK models from the API specification. Nullable fields are now described as a list of types instead of a choice of single types, with no change in accepted values. The email server update model documents that `transport` is left out of a name or enabled-only update.\n\n### Infrastructure & processing\n\n- Updated the schema validation library (zod) to a release with a security fix. Email server settings keep their specific validation messages, such as rejecting SMTP credentials when security is set to none.\n\n---\n\n## 0.20.85 (2026-10-25)\n\n### Platform (Studio)\n\n- Continuing an interrupted report grants fresh processing time while preserving completed chapters and saved work. Paused threads now show consistent agent statuses and hide redundant successful delegation rows.\n\n---\n\n## 0.20.84 (2026-10-25)\n\n- Internal improvements.\n\n---\n\n## 0.20.83 (2026-10-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.82 (2026-10-24)\n\n### Platform (Studio)\n\n- Report research now returns a compact source catalog while keeping original pages available for targeted reading. Generation can continue when a proactive summary is unhelpful but the existing conversation still fits, and paused agents display the actual reason for stopping.\n\n---\n\n## 0.20.81 (2026-10-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.80 (2026-10-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.79 (2026-10-24)\n\n### Platform (Studio)\n\n- Public market research receives only the company, industry and public research brief supplied by the analyst, without inheriting uploaded-file context or report instructions. Improve subagent task-input handling and remove duplicate report loading text. Accept grouped page citations without repeated document-write failures, while continuing to reject unknown pages and providing actionable correction messages.\n- Report agents now compact long conversations before reaching model limits, preserve accepted work when recovering from interruptions, and pause repeated identical tool errors instead of retrying indefinitely. Preserve the original task and evidence when compacting conversations, and improve tool-call compatibility with model gateways.\n\n---\n\n## 0.20.78 (2026-10-23)\n\n### Platform (Studio)\n\n- Security: updated Next.js to 16.4.1 and DOMPurify to 3.4.17, and container images now pick up operating system security updates daily.\n\n---\n\n## 0.20.77 (2026-10-23)\n\n### Platform (Studio)\n\n- Billing: OpenParser top-ups appear in checkout and on receipts as \"OpenParser credits\" with the OpenParser logo, and checkout starts with your account email already filled in.\n\n---\n\n## 0.20.76 (2026-10-23)\n\n### Platform (Studio)\n\n- Webhooks: rotate an endpoint's signing secret from the endpoint page and choose when the current secret expires. Keep it for 24 hours or 1 hour, and every delivery is signed with both secrets so you can update your receiver without rejecting events, or expire it now if it leaked.\n\n### Infrastructure & processing\n\n- Webhook signatures now follow Standard Webhooks, so any Standard Webhooks library can verify EigenPal events. **Action required if you verify signatures with your own code:** each signature is now `v1,&lt;base64&gt;` keyed by the base64-decoded secret (previously hex keyed by the secret text), and the `webhook-signature` header can carry more than one signature. Your secret is unchanged; the dashboard now shows it in standard base64. See the webhook receiver reference for the updated verification steps, then redeliver any events your receiver rejected before the update.\n\n---\n\n## 0.20.75 (2026-10-22)\n\n- Internal improvements.\n\n---\n\n## 0.20.74 (2026-10-22)\n\n### Platform (Studio)\n\n- Agents and workflows can continue with any positive credit balance without setting credits aside for estimated costs. Actual usage may take the balance below zero; further paid work stops once credits are exhausted, unless pay-as-you-go is enabled. Agent model credit limits also use actual usage and stop subsequent model requests once reached.\n- Company reports retain detailed analysis behind a compact, cited draft. Public research runs before chapter analysis, and follow-up conversations can answer questions or make focused Word edits without regenerating completed chapters. Report activity shows actual tool calls and subagent results, with saved progress available after reloading or continuing an interrupted run.\n\n### CLI\n\n- The bundled agent authoring reference now explains that credit checks use actual usage without reservations, including how an agent stops after reaching its model credit limit.\n\n### Infrastructure & processing\n\n- Platform updates can ship while OCR continues using its last validated version when a newer OCR version is not ready. New OCR versions still require successful staging validation before deployment.\n\n---\n\n## 0.20.73 (2026-10-22)\n\n### Platform (Studio)\n\n- Agents stay available on deployments without a sandbox. Self-hosted operators who previously turned agents off with `EIGENPAL_AGENTS_ENABLED=false` should set `EIGENPAL_SANDBOX_ENABLED=false` on both the app and worker instead: agents without a filesystem keep running, while filesystem agents and sandbox training are unavailable until a sandbox is enabled.\n\n### CLI\n\n- Bundle the public agent authoring guides, including callback capabilities, shared resources, filesystem options and typed evaluations. Clarify the distinction between the authoring SDK and API clients.\n\n### SDK\n\n- Allow immutable filesystem variants after evaluator and pass registration, preserve inferred evaluator and output types, and reject async/generator evaluation callbacks early. Document callback capabilities, limits and authoring checks.\n\n---\n\n## 0.20.72 (2026-10-22)\n\n### Platform (Studio)\n\n- Ship Node.js 22.23.4 in the self-hosted app, summary agent and single-node images, and Node.js 24.22.1 in agent sandboxes, fixing the October 2026 Node.js security release CVEs (including the Brotli decoder and TLS hostname verification issues).\n\n---\n\n## 0.20.71 (2026-10-21)\n\n### Platform (Studio)\n\n- Studio displays typed agent evaluation rules and weighted or custom pass decisions. Agent trigger edits update the draft and take effect when it is released.\n\n### Public API\n\n- The evaluator API reports typed agent evaluation rules and their weighted or custom pass decision from the requested agent source version. Agent evaluation changes take effect when the updated agent is released.\n\n### CLI\n\n- Evaluate individual agent examples with the same versioned evaluation rules and pass decision used by batch runs.\n\n### SDK\n\n- Define agents with inline or file instructions, immutable .withFilesystem() variants with bounded seed files and exact sandbox packages, custom typed tools, working directories, and composable execution guards. Define knowledge, rules, templates and directory skills as imported TypeScript resources. Portable resource text works in both agent modes; skills require filesystem access. Capture resources at the agent release commit instead of maintaining unchecked version strings.\n\n---\n\n## 0.20.70 (2026-10-21)\n\n### Platform (Studio)\n\n- Training sessions wait longer when agent preparation is busy, reducing temporary connection failures.\n\n---\n\n## 0.20.69 (2026-10-21)\n\n### Platform (Studio)\n\n- Updated dependencies improve protection against command injection, cross-site scripting, credential disclosure, and excessive resource usage.\n- Report merging and review now display their actual tool calls in the main agent transcript, and retain those calls when reopening a completed report. Reports recover from oversized model responses with smaller batches and let you retry a failed merge or review without rerunning successful chapters. Accepted edits are retained for recovery. Merge and review stages that reach their execution budgets pause with a Continue action instead of a generic failure. Report merging and review preserve completed sections while making targeted edits, and stop repeated unchanged source reads from consuming the remaining execution budget.\n\n### SDK\n\n- The Python SDK now requires an updated certificate trust store that excludes compromised certificate authorities, improving HTTPS connection security.\n\n---\n\n## 0.20.68 (2026-10-21)\n\n- Internal improvements.\n\n---\n\n## 0.20.67 (2026-10-20)\n\n### Platform (Studio)\n\n- Runs now show clearer file source errors to help diagnose input failures. Run lists and details remain readable on smaller screens, including long error messages and execution timelines.\n\n---\n\n## 0.20.66 (2026-10-20)\n\n### Platform (Studio)\n\n- Configure selectable Summary Agent model aliases and readable labels through SUMMARY_MODELS rather than gateway discovery. Allow the isolated public researcher to pursue focused evidence gaps beyond the initial six searches, retain original sources for downstream citations, and display public search calls with a globe icon.\n- Summary reports support direct OpenAI Luna tool calls with compatible request parameters. Public web research can use separate credentials, keeping report credentials confined to their configured provider.\n- Support explicit per-model reasoning controls in SUMMARY_MODELS for configured gateways. Reject reasoning-only output-token exhaustion with a useful diagnostic rather than replaying identical requests, and never accept token-truncated reports or execute truncated tool calls. A nonempty truncated response receives one bounded complete-draft retry.\n- Queued report follow-ups now wait for the completed Word document. The editor mounts each new version with its matching file bytes, preventing edits or exports of a temporary generation placeholder.\n- Avoid false reconciliation failures when an explicitly unreconciled bank/issuer gap is followed by a separate operating explanation. Financial writers can request targeted model corrections to a source-cited draft without regenerating unaffected paragraphs, while all existing source and numerical checks remain enforced. Preserve concrete chapter failure reasons and distinguish empty model replies from invalid reporting sections. Keep the targeted-edit instruction active during the final drafting reserve, and resolve exact bare worksheet names to canonical source-unit IDs for follow-up evidence reads.\n\n---\n\n## 0.20.65 (2026-10-20)\n\n### Platform (Studio)\n\n- Connect is easier to read with a compact setup bar, larger request field descriptions, and code examples that adapt to the available space. Required inputs appear first, while optional fields and request options expand when needed.\n- Allow file sources to declare additional workflow input fields with validated schemas. Preserve fetched fields with the file across retries, and support per-document metadata selection in run and dataset forms.\n\n### Infrastructure & processing\n\n- OpenParser can process more cloud OCR requests concurrently, reducing queueing during bursts of document uploads.\n- Allow file sources to declare additional workflow input fields with validated schemas. Preserve fetched fields with the file across retries, and support per-document metadata selection in run and dataset forms.\n\n---\n\n## 0.20.64 (2026-10-20)\n\n### Platform (Studio)\n\n- Summary reports retry temporary public search failures and show unsuccessful searches with clear error details. Changing the report model no longer changes the web retrieval model. Word follow-up edits accept unused empty tool fields and support expanding one paragraph into several paragraphs without editor errors. The model picker uses the shared dropdown beside report actions and in the follow-up composer. The composer no longer covers report settings or shows a scrollbar for short messages. Public searches use an independent retrieval default, avoid concurrent request bursts, and allow throttled providers time to recover.\n\n---\n\n## 0.20.63 (2026-10-20)\n\n### Platform (Studio)\n\n- Model defaults and examples use current provider models. Existing workflows and agents keep their explicitly selected models.\n- Improve compatibility with configured models during summary generation. Research and chapter analysis can recover from an incomplete first response instead of failing immediately, while retaining original-source verification. Keep the approved report subject and public research handoff through every writer, merge and review stage. Reject unrelated namesake companies instead of mixing their public financials into the borrower report. Preserve native assistant tool calls and matching tool-result messages during source inspection and calculation, rather than presenting tool output as a user instruction.\n\n### CLI\n\n- Workflow examples use current model IDs, and evaluation guidance covers reasoning settings and checks when changing models.\n\n### Infrastructure & processing\n\n- Improve compatibility with current Claude, GPT, and Gemini models, including reasoning controls and structured extraction. Gemini usage includes billable thinking tokens and cached input. New self-hosted configurations use current model defaults.\n\n---\n\n## 0.20.62 (2026-10-20)\n\n### Platform (Studio)\n\n- Run the latest saved workflow without creating a release. The editor now separates Save changes from Create release, with a clearer release dialog and help on demand. Missing versions fall back to the latest version, duplicate run submissions are prevented, and release errors stay visible so you can retry.\n- Workers now respect EIGENPAL_AGENTS_ENABLED=false when discovering agent sandboxes, preventing repeated E2B connection warnings in deployments with agents disabled. Cleanup of known stale sandbox executions remains active.\n- Summary Agent preserves spreadsheet formula errors instead of treating them as financial amounts, refreshes affected spreadsheet sources in older sessions, and checks table units before accepting financial prose. New report runs perform fresh research and analysis, with original-source inspection and clearer activity history.\n- Workflow Pal now uses available workflow inputs, file sources, and permitted subworkflows to prepare more reliable edits. Review proposed changes in a clearer editor panel, jump directly to the first change, and keep manual edits protected while a proposal is prepared.\n\n---\n\n## 0.20.61 (2026-10-19)\n\n### Platform (Studio)\n\n- Summary Agent now supports model selection, clearer failure details and more reliable report review and follow-up messages. Reports complete internet research first, then financial analysis, then the remaining chapters before merging and reviewing the final document.\n\n---\n\n## 0.20.60 (2026-10-19)\n\n### Platform (Studio)\n\n- On-premises deployments can configure additional file source integrations and certificate authentication.\n\n---\n\n## 0.20.59 (2026-10-19)\n\n### Platform (Studio)\n\n- Ship the nine-chapter credit-report prompt pack, including new market summary and peer analysis chapters, shared analyst writing guidance and fictional examples. Add bounded provider retries, resumable source-checked stages, a model merge with one independent review, native Word tables and source figures, and LiteLLM model routing for on-prem deployments. New sessions use the shipped prompts while restored sessions retain their selected version. Follow-up chat can edit the current Word document, preserving analyst changes, and request approved public research. Update DOCX editor packages to 2.31.0 and add sector-specific first-pass research guidance.\n- Keep document editing available consistently across the application and credit-report follow-up chat.\n\n---\n\n## 0.20.58 (2026-10-18)\n\n- Internal improvements.\n\n---\n\n## 0.20.57 (2026-10-18)\n\n- Internal improvements.\n\n---\n\n## 0.20.56 (2026-10-17)\n\n- Internal improvements.\n\n---\n\n## 0.20.55 (2026-10-16)\n\n- Internal improvements.\n\n---\n\n## 0.20.54 (2026-10-16)\n\n### Infrastructure & processing\n\n- Agent definitions now load reliably when starting runs.\n\n---\n\n## 0.20.53 (2026-10-16)\n\n### Platform (Studio)\n\n- Experimental agents now use their TypeScript definitions consistently when running and resuming, with more reliable definition validation and preserved version history.\n\n### Public API\n\n- Agent metadata now follows the released definition consistently across agent listings and runs.\n\n### CLI\n\n- Agent packages now use TypeScript for configuration and schemas. Frozen installs require captured definitions so resumed runs continue using the same version.\n\n---\n\n## 0.20.52 (2026-10-16)\n\n### Platform (Studio)\n\n- Agent validation and run preparation retry once after a temporary timeout.\n\n---\n\n## 0.20.51 (2026-10-16)\n\n### Infrastructure & processing\n\n- Improve OCR update reliability when spare processing capacity is available.\n- OpenParser prioritizes organizations that have purchased credits within regular and batch request queues. Regular requests still precede batches, and long-waiting requests retain protection against starvation.\n\n---\n\n## 0.20.50 (2026-10-16)\n\n- Internal improvements.\n\n---\n\n## 0.20.49 (2026-10-16)\n\n### Platform (Studio)\n\n- Support TypeScript agent definitions in authoring, releases and execution while preserving existing agents and interrupted runs. New agents use typed configuration and schemas.\n\n### Public API\n\n- Agent endpoints support typed agent definitions and validate inputs against the selected release's schemas while preserving existing agent releases.\n\n### CLI\n\n- Create, validate and release agents with typed TypeScript configuration and schemas. Existing agents remain supported, and dataset validation checks the agent's declared schemas.\n\n---\n\n## 0.20.48 (2026-10-15)\n\n### SDK\n\n- Preserve special JSON Schema keys during compilation without changing schema data.\n- The open-source TypeScript authoring SDK provides `createAgent`, typed input/output schemas, and a compiler for agent configuration. Existing agents continue running unchanged; TypeScript source integration follows separately.\n\n---\n\n## 0.20.47 (2026-10-15)\n\n### CLI\n\n- Git authentication keeps working after runtime upgrades when running the CLI from source.\n\n---\n\n## 0.20.46 (2026-10-15)\n\n### Platform (Studio)\n\n- Training conversations show saved messages while the agent prepares in the background. Messages submitted during preparation wait safely until the agent is ready, and connection errors leave conversation history readable.\n\n---\n\n## 0.20.45 (2026-10-14)\n\n### Platform (Studio)\n\n- Human review now displays confidence scores for nested fields even when lineage evidence is unavailable. Run rows also keep review and duration badges from overlapping in narrower lists.\n- Dataset tab in Studio no longer shows \"No runs yet\" for examples that have run. Agent experiment batches now point each example's `latestRunId` at the new run (the workflow path already did), and the examples list falls back to the newest run by example id when that pointer is missing or stale — the same source the example detail pane's Run Activity reads — so the list and detail can no longer disagree about whether an example has ever run.\n- Fix the caret jumping to the end of the \"Note on this example\" field on every keystroke in the dataset-review Resolve panel. The textarea now edits a local draft that stays fresh through React's controlled-state restoration, while still lifting each keystroke to the session draft.\n- Public research now uses the approved company search when its initial query is left blank, avoiding an unnecessary error at the start of research. Model connection failures now include a diagnostic error code when available, helping distinguish timeouts, refused connections and certificate problems.\n- Fix duplicate nested workflow timeline rows and missing start times that leave running leaf-step timers at zero.\n\n### Public API\n\n- Start workflow runs with a bare workflow ID such as `wf_abc` in the `target` field, for JSON and multipart requests. Existing `workflows.&lt;id-or-slug&gt;` targets remain supported.\n\n### CLI\n\n- Clarify how to flag specific dataset review fields and attach field comments with current workflow values. Agent guidance now keeps expected outputs aligned with the full intended workflow output and leaves comparison rules to evaluators.\n\n### Infrastructure & processing\n\n- Grounded extraction now preserves confidence for scalar fields inside nested objects and arrays, so review routing and confidence displays remain complete for structured outputs.\n- Fix duplicate nested workflow timeline rows and missing start times that leave running leaf-step timers at zero.\n\n---\n\n## 0.20.44 (2026-10-14)\n\n- Internal improvements.\n\n---\n\n## 0.20.43 (2026-10-13)\n\n### Platform (Studio)\n\n- GPT-6.1 Sol is available for agents, with lower cached-input pricing than GPT-6 Sol.\n- Organization admins can choose a default runtime model for agents in Model settings. Agents can inherit that choice or select a specific model. Changing the organization default applies to new runs; existing runs keep their selected model.\n- Pro includes 5,000 credits each month. Organization admins can enable optional pay-as-you-go at $1 per 100 additional credits, billed with the monthly subscription. Billing now clearly shows available, used, and reserved credits, the renewal date, and outstanding additional usage.\n\n### Public API\n\n- Agent responses expose their runtime model override. New agent runs resolve an organization default when unpinned and snapshot the model selected from the requested source version and runtime policy.\n\n---\n\n## 0.20.42 (2026-10-13)\n\n### Platform (Studio)\n\n- Apply operating system security updates to application and processing container images.\n- Rerun with changes now preserves the original workflow version and its input fields, including older releases and saved drafts. If that version cannot be loaded, the form shows an error instead of running a newer version.\n- Run details: input values can now be selected and copied, with a copy button on each value. The Rerun menu adds \"Rerun with changes\", which opens the Trigger page pre-filled with the run's inputs and tags so you can edit them before running. Uploaded files need to be added again.\n- Workflow builder: step outputs that are files (such as the merged PDF from Merge Documents) now show as `file` in reference pills and the variable browser, matching file inputs. Start node inputs that come from an external file source show the source name as a badge.\n\n### Public API\n\n- Webhook events now include the run's tags in `data.run.tags`. Tags stay in the event even when a large `output` is omitted, so you can tag a run with your own identifiers in `POST /api/v1/runs` and match every webhook back to your records without an extra API call.\n\n### CLI\n\n- Updated workflow guidance to explain how waiting for child runs frees processing capacity and how to start a child without waiting for its result.\n\n### SDK\n\n- The `tags` option when starting a run now documents that tags are returned in every webhook event as `data.run.tags`, for correlating events with your own records.\n\n### Infrastructure & processing\n\n[View full release notes →](/releases/0.20.42)\n\n---\n\n## 0.20.41 (2026-10-13)\n\n### Platform (Studio)\n\n- Workflow canvas, for large workflows with conditions, switches, loops and parallel steps: - Nested blocks stay inside their branch. - Fork and join lines meet every branch. - Short branches no longer stretch into empty panes. - Containers show their description and can be collapsed to a one-line summary. - Loops say what they repeat over. - \"Fit to screen\" shows the whole workflow. - \"Add step\" buttons appear on hover inside branches and in longer workflows.\n- Workflow editor and Evals fixes: - Undo now takes one step back per change, including the first change after an undo. - Undoing a newly added step also closes its settings panel. - Cmd+S saves from inside a field, including edits you haven't left the field for yet. - Leaving with unsaved changes offers Save & Leave. - The unsaved-changes marker is a labelled \"Unsaved\" status. It no longer appears on Evals right after saving. - New steps describe missing settings by name (\"Input is required\") instead of raw validation text. - The run panel opens the output when a run finishes. - Experiments that no evaluator scored show \"Not scored\" instead of 0%. - Evaluator names are formatted as you type, and save errors read as plain sentences. - A new dataset example opens on its Input tab. - The toast for starting an experiment from Dataset has a View link to the results.\n- Workflow editor and Evals: the canvas is calmer, with Start and End matching the step cards, Run inside the Start card, neutral connectors, quieter step containers and a subtle response on hover and click. Switching between Editor and Evals, and between Experiments, Dataset and Evaluators, now responds the moment you click, and the workflow version stays visible on both views. Experiments are listed by their example count with a short id instead of a long raw id, \"Run all dataset examples\" shows progress while it starts, an empty time range shows a single clear message instead of empty charts, and experiments without evaluators point you to adding one. Workflow Pal always builds with the current Parse Document and explains that the previous version is kept only for existing workflows.\n- Workflow editor: - The canvas has Undo and Redo buttons. - Renaming a step, a workflow input, or a Set Value or Extract Data field updates every reference to it. - The run panel shows the run's status and duration first. - Step types are named as on the canvas (\"Set Value\"). - When a run input is missing, the form highlights the field and moves the cursor to it. Evals: the pass threshold is set in the evaluator config and saved with it, with a single \"Save evaluators\" button.\n- Grafana dashboard: the Deployment target now defaults to All and panels merge targets, so the dashboard keeps working after an app pod restart changes the scrape target's IP instead of showing NO TARGET until someone picks the new one.\n- Workflows: new Merge Documents step combines several uploaded files (PDFs, scans, phone photos, Word, PowerPoint and OpenDocument files) into one PDF, so Parse, Label Pages, Split and Inspect Pages number pages continuously across every file. Its output lists which pages came from which upload, and the run view shows that page map. In the step picker, Parse Document is now the only parser offered for new steps; existing steps on the previous parser show as Parse Document v1 and offer a one-click switch. Run views now preview the right document when a step reads a file produced earlier in the run, and output files show their real names.\n- Prometheus: a new `eigenpal_automation_ocr_pages_total\\{automation_id}` counter reports the OCR pages each workflow processed. The Grafana dashboard now shows total OCR pages for the selected range, an OCR pages by workflow table, and a pages-per-minute chart of the top 10 workflows.\n- SSO: API keys owned by an SSO user no longer stop working 24 hours after the owner's last sign-in when EigenPal cannot re-check them with the identity provider. Scrapers and integrations keep running; keys still stop when the identity provider refuses the owner, the owner is removed or demoted, or the key is revoked. Refused keys now log a reason (`owner_refused_by_directory`, `owner_without_access`) instead of failing silently.\n\n### Public API\n\n- Starting a run with a single file for an input declared as a list of files now works: the file is treated as a one-item list instead of being rejected.\n- `GET /api/v1/runs` accepts `hasExample=true` to return only runs linked to a dataset example, so evaluation views no longer have to page through production runs to find them.\n\n### SDK\n\n- Listing runs accepts a `hasExample` filter (`has_example` in Python) that returns only runs linked to a dataset example.\n\n[View full release notes →](/releases/0.20.41)\n\n---\n\n## 0.20.40 (2026-10-11)\n\n### Platform (Studio)\n\n- Security hardening: people join an organization only by accepting an invite (the direct \"add existing user\" endpoint is gone), only owners can grant the admin role, members can revoke only their own API keys, API keys can no longer manage keys, members, invites, organization settings, sharing or billing, and demoting someone to viewer or reviewer revokes their API keys. Agent training only reads this session's uploads, email triggers accept a sender only when DMARC passes for the From domain or, for domains without DMARC, SPF passes for that domain, and workflow templates cannot read files from the worker.\n\n### Public API\n\n- Listing workflow executions only resolves file names for files in your own organization.\n\n---\n\n## 0.20.39 (2026-10-10)\n\n### Platform (Studio)\n\n- File source connections support multiple-file inputs. Callers supply a list of file references, and the workflow receives the fetched files in order.\n- Run form: lists are easier to fill in. Execution tags, and inputs that take a list of text or numbers, now use a chip input: type a value and press Enter, or paste a whole column or row at once. A value that doesn't fit, such as text in a number list, is marked before the run starts. Inputs with a fixed set of allowed values show every option as a chip you can toggle.\n\n### CLI\n\n- The workflow reference now documents `source` on file-list inputs (`type: array`, `items: \\{ type: file }`), which take one file reference per file.\n\n### Infrastructure & processing\n\n- Pushes and fetches of workflow source that are in progress during a platform update now finish instead of being cut off.\n\n---\n\n## 0.20.38 (2026-10-09)\n\n- Internal improvements.\n\n---\n\n## 0.20.37 (2026-10-09)\n\n### Platform (Studio)\n\n- Error reports sent from the browser now scrub tokens, secrets and sensitive URL parts before they leave the page, the same way server error reports already did.\n- Runs started from the CLI keep showing a plain \"CLI\" trigger in run details, without an extra SDK badge, now that the CLI identifies itself on API requests.\n- Grafana dashboard: a new \"Worker slots online\" tile shows how many jobs your workers can run at once, next to \"Workers online\". Slot panels and the worker table now say \"worker slots\" so a worker (one process) is never confused with its job slots.\n\n### CLI\n\n- The CLI now identifies itself on every API request with a `User-Agent: eigenpal-cli/&lt;version&gt; (&lt;runtime&gt;; &lt;os&gt;)` header and the same `X-Eigenpal-Sdk-*` headers the SDKs send, so CLI traffic and errors can be told apart from SDK and browser traffic. Runs started from the CLI record the CLI version in their trigger metadata.\n\n### Infrastructure & processing\n\n- When an AI extraction or vision step returns output that does not match its schema, the run now fails as a schema mismatch in the model output instead of a generic platform error, so failure reports and metrics point at the step's schema or model rather than at the platform.\n\n---\n\n## 0.20.36 (2026-10-09)\n\n- Internal improvements.\n\n---\n\n## 0.20.35 (2026-10-09)\n\n### Platform (Studio)\n\n- Monitoring: the Prometheus metrics endpoint now counts failed runs by cause (`eigenpal_execution_failures_total`), so input problems and deliberate workflow rejections no longer look like platform errors. A run stopped by a workflow's `control.fail` step now reports the `workflow_rejected` failure code.\n\n### Infrastructure & processing\n\n- Monitoring: the Prometheus metrics endpoint now counts failed runs by cause (`eigenpal_execution_failures_total`), so input problems and deliberate workflow rejections no longer look like platform errors. A run stopped by a workflow's `control.fail` step now reports the `workflow_rejected` failure code.\n\n---\n\n## 0.20.34 (2026-10-08)\n\n### Platform (Studio)\n\n- Monitoring: the Prometheus metrics endpoint now reports registered organizations and users, organizations active in the last 7 and 30 days, and paying organizations, so operators can follow adoption next to processing health.\n\n---\n\n## 0.20.33 (2026-10-08)\n\n### Platform (Studio)\n\n- Monitoring: our team now tracks run volume, outcomes and timing across EigenPal Cloud in real time, so slowdowns and failures are spotted and fixed sooner.\n\n---\n\n## 0.20.32 (2026-10-08)\n\n### Platform (Studio)\n\n- Billing: our team is now notified as soon as a payment, renewal, failed payment, refund or dispute happens, so billing problems on your account get followed up faster.\n\n---\n\n## 0.20.31 (2026-10-08)\n\n### Platform (Studio)\n\n- Monitoring: the Webhooks section of the EigenPal Grafana dashboard now shows events delivered alongside events not delivered, with a donut of delivery outcomes for the selected range and a per-minute chart of delivered versus not delivered.\n- Summary research now saves valid claims together while identifying only those needing correction. Clearer review guidance and more reliable document access reduce repeated failed attempts before completing financial chapters.\n- Public research claim details now show the full sentence, acceptance status and supporting evidence, including earlier claims that were subsequently revised.\n- Webhooks: endpoints can now be shared like workflows. A Manager of an endpoint (and any owner or admin) shares it with people and groups as Viewer, Editor or Manager, and members can create their own endpoints. An endpoint receives either every run (owners and admins only) or runs of selected workflows, and nobody can point one at runs of a workflow they cannot open. Existing endpoints stay private to owners and admins.\n\n---\n\n## 0.20.30 (2026-10-08)\n\n### Platform (Studio)\n\n- Fixed run cancellation and research approvals being rejected behind HTTPS reverse proxies while retaining browser origin checks. Improved public research with relevant source excerpts, a source-checked driver brief, and an independent editing pass. Chapter agents can investigate material public evidence gaps with human-approved searches and record their research decisions. Source pickers now emphasize filenames with file types underneath.\n\n---\n\n## 0.20.29 (2026-10-08)\n\n### Platform (Studio)\n\n- Settings, File Sources supports named connections for Amazon S3 and Azure Blob Storage. Administrators can configure multiple connections, manage stored secrets, and view deployment-managed connections as read-only.\n- Monitoring: the Prometheus metrics endpoint now reports webhook delivery attempts with their outcome and failure reason, events that were never delivered, delivery backlog and the oldest due delivery, and receiver response times. The EigenPal Grafana dashboard has a new \"Webhooks\" section, and the metrics guide includes ready-to-use alert rules for failing receivers, undelivered events and stalled delivery.\n- Webhooks: a new **Delivery settings** panel sets the retry policy, the request timeout and, on self-hosted deployments, whether endpoints may resolve to private network addresses. Settings pinned by the deployment show a lock. Each failed delivery now explains why it failed (for example, blocked private address, TLS handshake failure or connection refused), right in the delivery list, and links to the setting that fixes it. Deliveries waiting to retry show when the next attempt runs, and unsaved endpoint changes collect in a save bar that no longer shifts the page.\n\n### Public API\n\n- File source inputs accept structured references such as `\\{ \"bucket\": \"...\", \"key\": \"...\" }` for Amazon S3 and `\\{ \"container\": \"...\", \"blobName\": \"...\" }` for Azure Blob Storage. Reference fields are validated against the connection type.\n\n### CLI\n\n- The bundled webhooks guide and reference now cover delivery settings, the retry schedule, and how to ask for a retry while your receiver is still storing a run.\n- The bundled Prometheus metrics guide now documents webhook delivery metrics and example alert rules.\n\n### Infrastructure & processing\n\n- Settings, File Sources supports named connections for Amazon S3 and Azure Blob Storage. Administrators can configure multiple connections, manage stored secrets, and view deployment-managed connections as read-only.\n- Self-hosted deployments now deliver webhooks to endpoints on the private network by default, matching file sources and telemetry export. Previously these deliveries were refused without sending a request. Loopback, link-local and cloud metadata addresses stay blocked on every deployment, so a webhook can never reach the worker itself or node credentials.\n\n---\n\n## 0.20.28 (2026-10-07)\n\n### Platform (Studio)\n\n- Parse native and scanned documents automatically with the new Parse Document step. It preserves usable native PDF pages, recovers unread content with configured OCR or vision, and reports the source and completeness of each page. Advanced controls let you choose providers, restrict backends, require layout evidence, and tune vision processing. Existing parser steps keep their behavior. New workflows use automatic parsing, and you can review an explicit migration before publishing an updated workflow. The CLI and SDKs also provide a parsing configuration readiness check to help prepare deployments for scanned documents.\n- Preserve workbook-aware XLS/XLSX display formatting, trim empty trailing sheet extent before conversion limits, and expose optional original cell evidence for mixed date/identifier extraction. Forward sheet metadata through workflow execution and document how agents should use source evidence.\n\n### Public API\n\n- Inspect configured document-reading capabilities and provider selection through the authenticated parsing readiness endpoint. The response reports native/OCR/vision configuration and does not claim live endpoint verification.\n\n### CLI\n\n- Review document-parser migrations before publishing them with the new parser migration command. Updated workflow templates and agent guidance use automatic parsing by default. Inspect parsing configuration readiness through the CLI and SDKs to check whether your deployment has providers for scanned documents.\n\n### SDK\n\n- Review document-parser migrations before publishing them with the new parser migration command. Updated workflow templates and agent guidance use automatic parsing by default. Inspect parsing configuration readiness through the CLI and SDKs to check whether your deployment has providers for scanned documents.\n\n---\n\n## 0.20.27 (2026-10-07)\n\n### Platform (Studio)\n\n- Restore the PDF embedding, employment verification, Hacker News digest, and slow pipeline templates in the workflow template picker.\n- Financial summaries now investigate the drivers behind material changes across reporting periods. Other chapters wait for completed financial analysis and use it as additional context; incomplete financial chapters can be retried before the rest of the summary proceeds.\n- Monitoring: the Prometheus metrics endpoint now reports LLM token usage and finished runs for each workflow and agent, and the EigenPal Grafana dashboard has a new \"Usage by workflow\" section showing tokens, share of total, runs, and tokens per run per workflow, plus a chart of the top 10 consumers and a workflow filter.\n- Strengthened document image processing and mathematical expression rendering security.\n- Workflow access control: share workflows and folders with specific people or groups at four levels (Viewer, Runner, Editor, Manager). Access is set on top-level folders, the way a shared drive is run: everything inside a folder has that folder's access, so there is one place to check and change it. Making a folder private limits it to the people and groups you choose. Groups come straight from your identity provider (Keycloak, Entra ID, Okta, or a corporate sign-in service) and stay managed there, or can be created in EigenPal for password users. Each folder says at the top who can open it, with a Manage access button, and right-clicking a folder or workflow offers Manage access too. The access panel shows everyone who can open an item and why, and says who gains or loses access before you save. Moving something into a folder with different access asks first and shows the access before and after. Settings gains an Access control page: check whether a person can open a folder or workflow and see exactly why, see each person's groups and what your identity provider reports for them, and manage groups. A per-person access review sits on each member. Every sharing and group change is recorded in the audit log. Directory changes apply within minutes, and disabling someone at the identity provider signs them out of EigenPal. Admins can make every new top-level folder and workflow start private, and export who can open what as a CSV for access reviews. When an owner or admin opens a private item only their role lets them see, that is recorded too. Run history of a deleted workflow is visible to owners and admins only. Nothing changes for an organization until it makes something private.\n- Faster folder navigation for workflows. A folder tree now sits beside the workflow list: open any folder in one click, keep your place as you move around, and use the arrow keys to browse it. Long folder paths fold their middle into a menu so the path stays readable. Organize by dragging. Drop a workflow or folder onto a folder in the list, in the tree, or in the path above the list to move it there. Folders in the tree open when you hover over them while dragging, so you can move items several levels deep in one go. A preview follows the pointer and names where the item will land, only valid folders light up, and every move can be undone from the confirmation. Top-level folders and workflows show who they are shared with. Hover the avatars to see each person and group with their access level, or click them to manage sharing.\n\n### Public API\n\n- Automations, runs, datasets, experiments, evaluators, versions, folders, files and review endpoints now honor workflow access control. A workflow the caller cannot open answers `404`, exactly like one that does not exist, and is left out of every list. A workflow the caller can open but not change answers `403` for the change. Starting a run needs Runner access. API keys act with the access of the person who created them.\n\n### CLI\n\n- Simplify the bundled Prometheus metrics guide to bearer API key authentication and the metrics reference.\n\n### SDK\n\n- Strengthened Python SDK generation security while preserving Python 3.10 compatibility.\n\n[View full release notes →](/releases/0.20.27)\n\n---\n\n## 0.20.26 (2026-10-06)\n\n### Infrastructure & processing\n\n- Applied security updates to the GPU hosts that run document recognition and to a logging dependency used by the processing services.\n\n---\n\n## 0.20.25 (2026-10-06)\n\n### Platform (Studio)\n\n- Workflow Pal now honors configured authentication and custom headers for private model gateways, matching workflow execution and preventing chat failures on gateways requiring additional credentials.\n\n---\n\n## 0.20.24 (2026-10-06)\n\n### Platform (Studio)\n\n- Workflow and agent Swagger exports now include the run's `execution` object, documenting status and execution details consistently with API responses.\n\n---\n\n## 0.20.23 (2026-10-05)\n\n### Platform (Studio)\n\n- API keys: choose an access level when you create a key. **Full access** works with the API, CLI, and SDKs, as every existing key does. **Observability (read-only)**, available to owners and admins, can only read the Prometheus metrics endpoint, so monitoring systems no longer need a key that can run automations or read your data. On self-hosted deployments the Prometheus endpoint is now on by default and authenticates with an observability key, so monitoring needs no server configuration.\n- Monitoring: the Prometheus metrics endpoint for self-hosted deployments now reports LLM token usage by model, execution throughput and failure counts, execution, queue-wait, step, and LLM call latency histograms, OCR page volume, human-review outcomes, and per-worker process health (memory, CPU, event loop lag, and busy slots) alongside live queue depth. Counters stay accurate across restarts and data retention, a single scrape target covers the whole deployment, and collectors that request OpenMetrics (including Prometheus 3) receive it. Metric names follow Prometheus naming conventions, and the new Prometheus metrics documentation covers every metric. Owners and admins can turn the endpoint off in Settings > Monitoring, which also links to a prefilled form for creating an observability API key.\n\n### Public API\n\n- API keys now have an access level. Every API endpoint requires a **Full access** key, which is what all existing keys have, so existing integrations keep working. An **Observability (read-only)** key is refused with `403` by every endpoint except `GET /v1/auth/check`, which reports the key's own identity and scopes so you can verify a key before using it.\n\n---\n\n## 0.20.22 (2026-10-05)\n\n### Platform (Studio)\n\n- Workflow validation now accepts dynamic child-workflow targets with a runtime-check warning, explains why dynamic inline targets are unsupported, and rejects review selectors that a known schema proves cannot select a scalar field.\n- Downloaded API specs for a single workflow or agent now report that automation's own version instead of the platform release number, so upgrading Studio no longer looks like an API change to generated clients. The platform release is still included in the spec as `x-eigenpal-platform-version`. Self-hosted installs behind a proxy or OpenShift route also get the correct public server URL in the spec, and the spec no longer lists an unreachable server address when the public hostname cannot be determined.\n- Studio picks up the latest security fixes in its web framework.\n\n### Public API\n\n- Run input failures now report specific causes and include the input location and run correlation ID in debug diagnostics, without exposing document contents or storage paths.\n\n### CLI\n\n- Evaluation summaries now distinguish execution success from evaluator verdicts. Existing success-count fields remain available, and online validation warnings no longer cause a failed validation exit.\n\n### Infrastructure & processing\n\n- Child workflows now start only after their input files are available, improving reliability when forwarding files nested inside other inputs. File preparation failures now identify missing files and invalid references more clearly.\n\n---\n\n## 0.20.21 (2026-10-02)\n\n### Platform (Studio)\n\n- Assign dynamic tags to child workflow runs, filter run history by an exact tag, and open matching runs from their tag labels. Retries and reruns retain the original tags. Set tags on the Trigger page and generate tagged REST and SDK examples on Connect.\n\n### Public API\n\n- Workflow and agent run requests accept `tags` as a string or a list of strings. Run responses include tags, and `GET /api/v1/runs?tag=...` finds runs with an exact, case-sensitive tag.\n\n### CLI\n\n- Use `eigenpal runs list --tag &lt;tag&gt;` to find runs with an exact tag, such as a request ID. Start an ad-hoc workflow or agent run with `eigenpal run &lt;target&gt; --tag &lt;tag&gt;`. Repeat `--tag` for multiple tags.\n\n### SDK\n\n- Pass execution tags when starting workflow or agent runs with the TypeScript and Python SDKs, including runs with file inputs. Filter run history by tag using the runs client.\n\n---\n\n## 0.20.20 (2026-10-02)\n\n### Platform (Studio)\n\n- Summary builder: invalid claim registration input now shows a clear error instead of a misleading claim count.\n- Settings: each settings page now shows a loading placeholder shaped like the page itself, instead of a generic one that repeated the settings navigation and title.\n\n### Infrastructure & processing\n\n- Strengthen security protections for document extraction.\n\n---\n\n## 0.20.19 (2026-10-01)\n\n### Platform (Studio)\n\n- The Agents page and agent detail views load faster, especially for organizations with many agents. Opening one agent now reads only that agent instead of the whole organization, and source lookups for one organization no longer slow down other organizations.\n- Dashboard pages respond faster. Every page load and live refresh in EigenPal now does less work before returning data, and pages that hit a permission error show it right away instead of retrying first.\n- Pages and live status updates in EigenPal Studio respond faster, because signed-in requests no longer wait on an account profile lookup every time. A change to your account email still takes effect within a minute, and invitations are always matched against your current verified addresses.\n- Hardened sign-in account linking: signing in with an email address no longer connects you to an existing EigenPal account that belongs to a different sign-in. If your previous sign-in account was deleted, signing up again with the same email still restores access to your existing account.\n- The Workflows and Runs pages load faster, especially in organizations with many workflows or a long run history. The Workflows page now fetches only what its cards and rows show, folder previews load alongside the folder list, and the Runs page stops refreshing in the background while its tab is hidden, then catches up as soon as you return. The \"Triggered by\" filter on the Runs page now lists people who started runs in the last 90 days unless you pick a date range.\n\n### Public API\n\n- `GET /api/v1/agents` responds faster, including single-agent lookups with `?slug=`. The new optional `includeExampleCount=false` query parameter omits `stats.exampleCount` for callers that do not need it.\n- `GET /api/v1/runs` and `GET /api/v1/runs/:id` respond faster when runs belong to large workflows. Responses are unchanged.\n- Rate limits for requests made from a signed-in EigenPal dashboard session now count reads separately from writes, so browsing and live-refreshing pages no longer use up the allowance for starting runs. File downloads, artifact archives, traces, dataset and experiment exports, session transcripts, and run event streams still count toward the shared allowance. Limits for API key requests, including those from the CLI and SDKs, are unchanged.\n- When a signed-in session cannot be connected to an existing EigenPal account, API requests now return `403` with a message explaining how to get help, instead of a generic authentication or server error.\n\n---\n\n## 0.20.18 (2026-10-01)\n\n### Platform (Studio)\n\n- Downloaded API specs for a single workflow or agent now report that automation's own version instead of the platform release number, so upgrading Studio no longer looks like an API change to generated clients. The platform release is still included in the spec as `x-eigenpal-platform-version`. Self-hosted installs behind a proxy or OpenShift route also get the correct public server URL in the spec, and the spec no longer lists an unreachable server address when the public hostname cannot be determined.\n- Strengthen security protections for image generation, document previews, and telemetry transport.\n- Studio pages feel faster. Pages without a code editor or PDF preview load less up front, opening a workflow, agent, template, review queue, or developer page now shows a placeholder shaped like that page, and workflow links open the editor directly. On the Evals page, the side panels appear right away, changing the date range keeps the current results visible until the new ones arrive, and the runs list and overview no longer show each other's data. The agent editor keeps its files and instructions on screen while a conversation resumes, and opening a workflow folder link on a later page keeps that page.\n- Run details open faster. Selecting a run shows its name, status, and actions right away, and each section fills in on its own as it loads instead of the whole pane waiting on a skeleton. Inputs, outputs, and the step trace load side by side, long traces load their pages in parallel, and sections no longer go blank for a moment when a run finishes. Switching between the timeline and the raw trace reuses what is already loaded. Workflows, runs, and agents also start loading their details when you hover over or focus them in a list, so opening one feels quicker.\n- Pages load faster after signing in and when opening a link directly. Your organization is ready as soon as the page appears, so lists, agents, and run details start loading right away instead of waiting a moment first.\n- Usage: a new \"LLM usage by workflow\" table shows the tokens each workflow and agent consumed in the selected range, with run count, average tokens per run, cached input, and share of total, so teams can see which automations drive their LLM spend.\n\n---\n\n## 0.20.17 (2026-09-30)\n\n- Internal improvements.\n\n---\n\n## 0.20.16 (2026-09-29)\n\n### Platform (Studio)\n\n- Run reviews now preview input files with the same document viewer as dataset reviews. Multi-file runs get one-click previous/next switching with a position indicator, PDFs and images get full zoom controls, and the file picker lives in the viewer header instead of a separate bar. Field-evidence highlights and the approval workflow are unchanged.\n\n---\n\n## 0.20.15 (2026-09-29)\n\n- Internal improvements.\n\n---\n\n## 0.20.14 (2026-09-29)\n\n- Internal improvements.\n\n---\n\n## 0.20.13 (2026-09-29)\n\n### Platform (Studio)\n\n- Dataset reviews in Studio: filter the field queue to flagged-only (document order preserved), return to the Datasets list on close without pre-selecting the last automation, show the requester's note read-only above the reviewer note box, remove the approve-all-fields flow (untouched fields are assumed error-free), and rename user-facing Approve labels to Submit.\n- Apply security updates to sign-in, workflow execution and document processing.\n\n### CLI\n\n- Apply security updates to workflow validation dependencies.\n\n### Infrastructure & processing\n\n- Apply security updates to sign-in, workflow execution and document processing.\n\n---\n\n## 0.20.12 (2026-09-28)\n\n- Internal improvements.\n\n---\n\n## 0.20.11 (2026-09-25)\n\n### CLI\n\n- `eigenpal auth login` now opens the dashboard in your browser without routing the URL through a shell, so an unusual server address can never be interpreted as a command.\n\n---\n\n## 0.20.10 (2026-09-24)\n\n### Platform (Studio)\n\n- Studio model picker: add GPT 6 Sol, GPT 6 Luna, and Claude Opus 5.5 as selectable models for workflow steps and agents. The recommended list now surfaces the new generation; Opus 5 and the 5.6 Sol/Terra/Luna models remain available via search.\n- Dataset review: the fields queue now follows the output in document order. Flagged fields keep their highlight where they appear and removed fields stay in place with their removed styling, instead of being sorted to the top or bottom.\n\n---\n\n## 0.20.9 (2026-09-24)\n\n### Platform (Studio)\n\n- Reviews → Datasets: requesting a review is now fast even for many examples with large files — snapshotting downloads input files in parallel and no longer re-downloads them for the response. Reviews can also be cancelled (a frozen state like closed, reopenable back to open), and Studio lets reviewers close a review with undecided examples still in it: closing locks the review and only decided examples count as submitted.\n\n### Public API\n\n- Reviews → Datasets: requesting a review is now fast even for many examples with large files — snapshotting downloads input files in parallel and no longer re-downloads them for the response. Reviews can also be cancelled (a frozen state like closed, reopenable back to open), and Studio lets reviewers close a review with undecided examples still in it: closing locks the review and only decided examples count as submitted.\n\n### CLI\n\n- Reviews → Datasets: dataset review requests gain a `cancelled` lifecycle status. The CLI accepts `update --status cancelled` (and shows it in `list --status` filters), and the TypeScript/Python SDK status enums include the new value.\n\n### SDK\n\n- Reviews → Datasets: dataset review requests gain a `cancelled` lifecycle status. The CLI accepts `update --status cancelled` (and shows it in `list --status` filters), and the TypeScript/Python SDK status enums include the new value.\n\n---\n\n## 0.20.8 (2026-09-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.7 (2026-09-24)\n\n### Platform (Studio)\n\n- Members: on self-hosted deployments with password sign-in, owners and admins can reset a member's password from Settings → Members. The admin sets a temporary password, the member is signed out on every device, and the next time they sign in they have to choose a new password before they can use the app.\n\n---\n\n## 0.20.6 (2026-09-24)\n\n### Platform (Studio)\n\n- Dataset review: add missing fields and line items without leaving the review, confirm object and array values, and approve every unreviewed field at once from the queue. Newly added fields now survive saves and refreshes until confirmed.\n- Reviews → Datasets: reviewers can open the dataset review inbox without workflow access. Studio loads the queue from `GET /api/v1/dataset-review-requests` (gated by `dataset_review:read`) instead of listing automations first, so reviewers see their requests rather than a permission error.\n\n### Public API\n\n- Reviews → Datasets: reviewers can open the dataset review inbox without workflow access. Studio loads the queue from `GET /api/v1/dataset-review-requests` (gated by `dataset_review:read`) instead of listing automations first, so reviewers see their requests rather than a permission error.\n\n### SDK\n\n- Reviews → Datasets: the TypeScript and Python SDKs expose the tenant-wide dataset review inbox as `client.datasetReviewRequests.list()` / `client.dataset_review_requests.list()`, with the same status filter and pagination as the Studio queue.\n\n### Infrastructure & processing\n\n- Document OCR stays up under rapid bursts of complex pages. The GPU inference server now uses smaller recognition batches and leaner memory allocation, so back-to-back multi-region documents no longer risk an out-of-memory restart — and the one-minute engine-failure alert from the last release still watches for any recurrence.\n\n---\n\n## 0.20.5 (2026-09-23)\n\n### Platform (Studio)\n\n- Dataset review now walks you to the finish: deciding an example advances to the next pending one and opens a completion sheet when nothing remains. The header shows an `n/m reviewed` pill that opens the same sheet, with Approved / Removed / Corrected counts, a Close review button (disabled until every example is decided), and the pull command for handing snapshots to an agent. The Resolve button stays green for pending, edited, and approved examples — only removed stays red.\n- Dataset review: text, spreadsheet, and other non-PDF input files now show the same header as PDFs and images, so reviewers can switch back to the other inputs from every file type.\n- Dataset review: clicking a field now reveals it in the Output JSON tree even when it sits inside a collapsed list item, scrolling it into view with its highlight.\n\n### Public API\n\n- Dataset review item decisions now use `removed` instead of `rejected` across progress counts, field/file decisions, and update actions. Callers that previously sent `action: \"reject\"` or `decision: \"rejected\"` should switch to `remove` / `removed`.\n\n### CLI\n\n- `eigenpal auth status` (alias `whoami`) shows the active profile, server URL, and whether the credential validates, with `--json` support for scripting.\n- `--json` output is now safe to pipe: status chatter stays off stderr so `2>&1 | jq` parses, and re-pushing identical YAML with `workflow push --file X --json` reports `\\{ unchanged: true }` instead of an error.\n- `eigenpal reviews` dataset-review actions and decisions now use `remove` / `removed` instead of `reject` / `rejected`, matching the public API rename.\n\n### SDK\n\n- Dataset review SDK types and helpers now expose `removed` instead of `rejected` for item status, progress, field/file decisions, and update actions.\n\n---\n\n## 0.20.4 (2026-09-23)\n\n- Internal improvements.\n\n---\n\n## 0.20.3 (2026-09-23)\n\n### Platform (Studio)\n\n- Expected-output files now review the same way fields do, on the right side of the dataset review panel: preview or edit text, Office, and spreadsheet files in place, upload corrected or brand-new versions, and record per-file approvals with notes. The review queue header lives in the breadcrumb bar with a status filter, so finished requests stay findable.\n\n### Public API\n\n- Dataset review items now cover expected-output files, not just fields: record per-file approve/reject decisions with notes, upload corrected bytes for an existing file or a brand-new one (50MB cap), and download the reviewer-corrected version with `kind=expected` on the item file endpoint. Closing a finished review still never auto-applies — reconcile corrected files into the live dataset by hand.\n- Dataset review file actions now accept the `expected/`-prefixed file path form (for example `expected/report/report.docx`) wherever a per-file decision or correction is recorded. It resolves to the same manifest-relative entry reviewers see, so paths copied from `$file` references in `expected.json` no longer fail with `unknown expected file`.\n\n### CLI\n\n- Expected-output files are first-class reviewable units: `pull --out &lt;dir&gt;` downloads per-example expected files (reviewer-corrected when the item has an overlay entry, else the snapshot) alongside `item.json`; `item --action edit-file` uploads corrected bytes (`--file-path` fixes an existing file, `--new-path` uploads a brand-new one, 50MB cap); `item --action file-decision` records per-file approve/reject with notes (`--comment` alone is a note and needs an existing decision); `get`/`items` show per-file decision summaries. Reconcile corrected files into the live dataset by hand — reviewers can err.\n\n### SDK\n\n- Expected-output files are covered too: items carry `currentExpectedFiles` (null means pristine snapshot) and `fileDecisions`; `getItemFile` / `get_item_file` accept `kind: 'expected'` to download reviewer-corrected bytes (default stays `input`); `recordItemFileDecision` / `record_item_file_decision` records per-file approve/reject or notes (`decision: null` clears); `editItemFile` / `edit_item_file` uploads corrected bytes for an existing path or a brand-new upload (50MB cap).\n\n---\n\n## 0.20.2 (2026-09-23)\n\n### Infrastructure & processing\n\n- Document OCR is now more resilient under heavy load. Back-to-back parsing bursts no longer risk taking the whole OCR fleet offline at once — jobs queue briefly and resume automatically — and monitoring catches GPU inference failures within a minute instead of several.\n\n---\n\n## 0.20.1 (2026-09-23)\n\n### Platform (Studio)\n\n- Credit limits now apply consistently across the product. Agent runs, the workflow builder assistant, and the expression generator are checked against your remaining balance before they start, and the assistant and expression generator now record their usage on your usage page instead of being invisible. A cancelled agent run is billed for the work it actually completed rather than dropping off your usage entirely. Organization creation is capped per account, both by how many you own at once and by how many you create over a rolling window, so one account cannot spin up unlimited free trials. A very long builder conversation is now refused with a message asking you to start a new chat, rather than being sent to the model in full. Deleting an organization now removes its stored files before the organization itself disappears. A large organization can take more than one pass, and the dialog now says accurately what happens: files are removed immediately and clear backups within 7 days.\n\n### Public API\n\n- Starting a run now returns `402 insufficient_credits` when your organization has spent its credit allowance. The check happens before the request body is read, so no files are uploaded and no work begins on a run that cannot be paid for. File uploads return the same status for the same reason, and both are now described in the API reference. The API reference also documents `503`, which endpoints return when request accounting is briefly unavailable. It means the request was not processed and is safe to retry; it is not a rate-limit rejection.\n\n---\n\n## 0.20.0 (2026-09-22)\n\n### Platform (Studio)\n\n- Datasets can now be sent for client review without exporting files. Create a review request from a dataset, highlight the fields that need attention, mark others as not required, and invite client teammates with the new reviewer role. They walk examples from a dropdown, inspect the fields, leave notes, record per-field decisions, and approve or reject each row. Closing a finished review does not auto-apply changes — reconcile expected outputs manually. The Reviews queue keeps finished requests visible with a status filter so old approvals stay findable. Reviewers see the same Studio shell with permission-aware empty states.\n\n### Public API\n\n- New dataset review endpoints under `/api/v1/automations/:id/dataset-review-requests`: create a review from dataset examples with reviewer `instructions`, `focusFields` (paths plus optional reasons), `ignoredFields` for paths reviewers can skip, and optional `itemNotes`. Approve, edit, reject, reopen, comment, or record a `field-decision` on each example (including clearing a decision with `decision: null`), then poll `progress.complete` and close the request with `PATCH` status. Dataset reconciliation stays manual — nothing is deleted by reject. A new `reviewer` organization role can read review queues and submit item decisions but cannot edit workflows.\n\n### CLI\n\n- `eigenpal workflow dataset review-request` (and the `eigenpal agents dataset` mirror) is the agent-friendly review loop: create a request with reviewer instructions, `--focus` / `--focus-reason` paths, `--ignore` paths reviewers can skip, and per-example `--item-note` / `--field-note` comments; `list`/`get`/`events` expose `progress.complete`, `fieldDecisions`, and `inputDrifted`; `item --action` records approve/reject/comment/edit plus per-field `field-decision` (clear with `--clear` / `--decision null`); `update --status closed` finishes the request. There is no auto-apply — pull and reconcile examples manually. Reject is recommendation-only; nothing is deleted.\n\n### SDK\n\n- `client.automations.datasetReviewRequests` (`dataset_review_requests` in Python) covers the full dataset review lifecycle: list and get with `progress`, `focusFields`, `ignoredFields`, `fieldDecisions`, and `inputDrifted`; create with reviewer instructions and per-field notes; update request metadata or close with status; update items including `field-decision` (pass `decision: null` to clear); and the per-user activity trail. Dataset write-back stays manual — there is no lock endpoint.\n\n### Infrastructure & processing\n\n- Replace the eagerly constructed `eigenpalAjv` singleton with a lazy `getEigenpalAjv()` accessor. Ajv compiles schemas with `new Function`, which the Studio Content-Security-Policy forbids — constructing at import time crashed every page whose client bundle transitively imported `@eigenpal/types` validation (including all review surfaces, which never validate client-side). Server-side call sites are unchanged apart from the accessor.\n\n---\n\n## 0.19.1 (2026-09-21)\n\n- Internal improvements.\n\n---\n\n## 0.19.0 (2026-09-21)\n\n### Platform (Studio)\n\n- Agent builder sessions can now be given storage credentials limited to their own session folder instead of the whole storage account. Set a Cloudflare account id and API token, or an AWS role, and each training sandbox receives a short-lived key that can only read and write its own files. Deployments that do not configure this keep working exactly as before and log a warning, and a new setting makes the platform refuse to start a sandbox unless scoped credentials are available.\n- Studio security hardening. Parsed document text shown in run traces and grounding views is now sanitized before rendering, so a crafted document can no longer inject active content into the page. Observability settings now require administrator access to view, and the values of any authorization headers you configure are masked once saved, so they are never sent back to the browser. Saving a renamed header now asks you to retype its value instead of quietly clearing the configuration. Outbound observability destinations are validated to reject internal and unencrypted endpoints on hosted plans. Editor assets are now served from Eigenpal's own domain instead of a public content network. Self-hosted deployments that use password sign-in no longer accept open self-registration. Creating the first account still works, and anyone holding an invitation can still create their account, but an uninvited visitor can no longer join an existing workspace. Set `EIGENPAL_ALLOW_OPEN_SIGNUP=true` to restore the previous behavior. Agent training and email trigger surfaces are now scoped more tightly. Email alias changes are accepted only through the agent that owns the alias, so editing or revoking one from a different agent's page now reports not found. Opening a training session that belongs to a different workspace or a different agent is refused instead of returning a server error. Each agent workspace now runs with credentials valid only for its own session, so a workspace can no longer act on any session but its own. Sign-in and account safety. Changing your password now signs out your other sessions, so a password change ends access from a device you no longer control. Accepting an invitation now requires the invitation link itself rather than just the invited address, so knowing that someone was invited is no longer enough to create an account in their name. Requests that arrive from another site are refused, which closes cross-site request forgery against pages you are signed in to. Set `EIGENPAL_TRUSTED_ORIGINS` if you serve Eigenpal on more than one hostname.\n\n### Public API\n\n- Agent endpoints that accept an agent id now resolve it strictly within the calling organization. Requesting an id belonging to another organization returns not found instead of reading or modifying it. Run and step endpoints apply the same organization check to execution ids. Uploads that omit a declared length are now measured while they stream and return 413 once they exceed the request limit, rather than being read into memory first. Operator source tokens are accepted only on the source and authentication check endpoints they are documented for. Webhook endpoints are now checked when you save them, not only when a delivery is attempted. A destination the platform cannot deliver to is rejected with a validation error at creation and update time, instead of being accepted and then failing silently on every send. Self-hosted deployments that deliver to their own internal network are unaffected. Every endpoint that starts a new run now honours the automation's trigger settings, the same way `POST /api/v1/runs` already did. That covers rerunning a run, starting an experiment, and running a single dataset example, including their streaming variants. An API key calling one of these on an automation whose API trigger is turned off now receives `403 api_trigger_disabled`, and a dashboard session calling one on an API-only automation receives `403 manual_trigger_disabled`. If an existing integration starts returning 403, turn the API trigger back on for that automation.\n- Self-hosted Prometheus scrapes now require the dedicated scrape token in every deployment. An organization API key is no longer enough to read the cluster snapshot. A deployment without `EIGENPAL_METRICS_SCRAPE_TOKEN` returns 404 on the metrics route, so set the token before upgrading if you scrape today with an API key. The headless workflow server no longer serves a network address without an API token. If you set `HOST` yourself, the server now exits at startup unless you also set `HEADLESS_API_TOKEN` or `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1`. If you never set `HOST`, the bind address changes from `0.0.0.0` to `127.0.0.1`, which inside a container means a published port stops accepting connections while the container still reports healthy. Either set `HEADLESS_API_TOKEN` (16 characters or more) together with `HOST=0.0.0.0`, or set `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1` to keep the previous behaviour. Members can no longer pull decrypted agent environment secrets. Use an owner or admin key, or decrypt a secret for a specific run.\n\n### Infrastructure & processing\n\n- Self-hosted Prometheus scrapes now require the dedicated scrape token in every deployment. An organization API key is no longer enough to read the cluster snapshot. A deployment without `EIGENPAL_METRICS_SCRAPE_TOKEN` returns 404 on the metrics route, so set the token before upgrading if you scrape today with an API key. The headless workflow server no longer serves a network address without an API token. If you set `HOST` yourself, the server now exits at startup unless you also set `HEADLESS_API_TOKEN` or `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1`. If you never set `HOST`, the bind address changes from `0.0.0.0` to `127.0.0.1`, which inside a container means a published port stops accepting connections while the container still reports healthy. Either set `HEADLESS_API_TOKEN` (16 characters or more) together with `HOST=0.0.0.0`, or set `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1` to keep the previous behaviour. Members can no longer pull decrypted agent environment secrets. Use an owner or admin key, or decrypt a secret for a specific run.\n- Document and archive processing is more resilient to malformed or hostile input. Dataset archive imports now apply a limit on entry count and hold far less memory while expanding, so a small archive can no longer exhaust a request. Office documents are checked against their real expanded size rather than the size recorded inside the file, which blocks highly compressed payloads that previously passed inspection. PDF page rendering moved to a newer engine that removes a document driven code execution path. Script transform steps have a shorter maximum run time that is now capped relative to worker health checks, so a long running script cannot stall other work. With stock settings the ceiling drops from 30 seconds to 15 seconds; self-hosted deployments that need more can raise `HEALTH_LIVENESS_STALE_MS`, since the ceiling is half that value. Workflow processing is more resilient to hostile input. Template rendering now has time and memory ceilings, so a crafted template can no longer stall a worker and delay other runs. Deep merges in the combine transform can no longer be steered into altering shared state. External file sources reject addresses that are not plain HTTP endpoints.\n\n---\n\n## 0.18.0 (2026-09-21)\n\n### Platform (Studio)\n\n- Workflows can crop normalized regions from PDFs and images into JPEG artifacts with the new `transform.crop-regions` step — pair it with parse output and script steps to build figure or layout evidence pipelines without a figure-specific step type. Turn on optional **`cache: true`** on **`ai.parse`** to reuse prior parse output for the same file bytes and parse settings across runs (stored in tenant blob storage; no expiry yet).\n\n---\n\n## 0.17.5 (2026-09-21)\n\n### Platform (Studio)\n\n- Summary Agent: spreadsheet uploads now use a hardened parser that prevents crafted workbook content from causing excessive processing or modifying object prototypes.\n\n### CLI\n\n- CLI skill reference documents the new `ai.figure-crops` workflow step for cropping and captioning figures from parsed PDFs.\n\n### SDK\n\n- Python SDK: installs now require `anyio` 4.14.2 or newer. Earlier versions encoded host names with IDNA 2003 when opening a TLS connection, so a crafted host name could be matched against the wrong certificate. The TypeScript SDK is unaffected.\n\n---\n\n## 0.17.4 (2026-09-18)\n\n### Platform (Studio)\n\n- Strengthen organization access controls so role permissions, API-key scopes, and member removal apply consistently across Studio and the API. Webhook configuration and signing secrets are restricted to organization owners and admins. Service credentials cannot exceed member permissions, while members retain file and review editing through the API.\n- Organization owners can invite new users directly as owners. Owner invitations can only be created and managed by existing owners.\n\n### Public API\n\n- Strengthen organization access controls so role permissions, API-key scopes, and member removal apply consistently across Studio and the API. Webhook configuration and signing secrets are restricted to organization owners and admins. Service credentials cannot exceed member permissions, while members retain file and review editing through the API.\n\n### Infrastructure & processing\n\n- Cloud workflow HTTP and website-reader actions now restrict requests to public HTTP/S destinations, verify TLS for HTTPS requests, and reject HTTPS-to-HTTP redirects. Responses are limited to 20 MiB and requests to 120 seconds. Single-tenant installations retain private-network integration support.\n\n---\n\n## 0.17.3 (2026-09-18)\n\n### Public API\n\n- Large PDF parses are now more reliable under parallel load. The OCR service paces concurrent pages per document so multi-page jobs no longer exhaust inference memory and retry, which previously stalled big documents behind repeated restarts.\n\n---\n\n## 0.17.2 (2026-09-17)\n\n### Platform (Studio)\n\n- Settings gains a Data retention section for workspace admins: see how much file storage past and present runs consume, choose how long eval and other runs are kept, preview what falls past the horizon, and delete those runs in capped passes until clear. Runs that are still active are always kept. Enforcement offers two modes: purge input files only (run history and outputs stay, freeing the bulky source documents while keeping the audit trail) or delete full runs. Storage usage splits run inputs from outputs so admins can see what input-only cleanup would free.\n\n### Public API\n\n- Rerunning a run whose input files were removed by data retention now returns a clear `409 inputs-purged` error instead of failing while copying the missing files. Run history and outputs remain available.\n\n---\n\n## 0.17.1 (2026-09-15)\n\n- Internal improvements.\n\n---\n\n## 0.17.0 (2026-09-15)\n\n### Platform (Studio)\n\n- Studio can connect to a live agent inference session even when that session runs in a local sandbox instead of the hosted cloud environment.\n\n### Infrastructure & processing\n\n- Agent inference can now run in a local container sandbox, so on-prem and air-gapped deployments no longer need a cloud sandbox provider.\n- Agent runs can now execute in customer-hosted sandbox environments instead of only the Eigenpal cloud, and local Docker sandboxes connect reliably on plain localhost setups.\n\n---\n\n## 0.16.13 (2026-09-14)\n\n- Internal improvements.\n\n---\n\n## 0.16.12 (2026-09-14)\n\n### Platform (Studio)\n\n- Studio can import large dataset ZIP archives without taking the app down, including archives whose paths use Windows-style backslashes. Opening a long-running workflow no longer pulls every step’s full input and output at once. Run pages stay available, still show the steps timeline when phase data is missing, and keep the last loaded view if a refresh fails — with a retry control instead of a blank error page.\n\n### Public API\n\n- `GET /api/v1/runs/\\{id}?expand=execution` and `GET /api/v1/runs/\\{id}/steps` now return slim step rows (identity, status, timing, and a capped error excerpt) instead of inlining every step’s input and output. Inspect one step’s full payloads with the new `GET /api/v1/runs/\\{id}/steps/\\{stepExecutionId}` endpoint.\n\n### CLI\n\n- `eigenpal runs get` lists slim step rows by default. Pass `--include input,output` or `--step` to fetch full payloads for the steps you care about.\n\n### SDK\n\n- The TypeScript and Python SDKs now include `GET /api/v1/runs/\\{id}/steps/\\{stepExecutionId}` so you can load one step’s full input and output after listing slim run steps.\n\n---\n\n## 0.16.11 (2026-09-11)\n\n### Platform (Studio)\n\n- Studio: organization switching and other labeled menus now open reliably without a client-side error.\n\n---\n\n## 0.16.10 (2026-09-10)\n\n### Infrastructure & processing\n\n- OCR processing now distinguishes temporary host availability issues from true processing timeouts, keeps redundant production capacity warm, and pages only when unfinished work is affected. Short self-healing interruptions remain visible for diagnosis without generating misleading recovery alerts.\n\n---\n\n## 0.16.9 (2026-09-10)\n\n### Platform (Studio)\n\n- Harden web image handling, document image processing, and email delivery against crafted inputs that could cause remote code execution, excessive resource use, or recipient-validation bypasses.\n\n### Infrastructure & processing\n\n- Harden web image handling, document image processing, and email delivery against crafted inputs that could cause remote code execution, excessive resource use, or recipient-validation bypasses.\n\n---\n\n## 0.16.8 (2026-09-10)\n\n### Platform (Studio)\n\n- Files are easier to recognize throughout Studio with refreshed Office logos, dedicated PDF, archive, text, JSON, and code treatments, plus image thumbnails. File inputs now use a clearer rounded drag-and-drop experience with consistent selected-file previews.\n\n---\n\n## 0.16.7 (2026-09-10)\n\n### Platform (Studio)\n\n- File uploads now infer supported document media types from the filename when clients provide an empty or generic content type, allowing original Outlook messages and macro-enabled workbooks to upload without conversion.\n\n### Public API\n\n- File uploads now infer supported document media types from the filename when clients provide an empty or generic content type, allowing original Outlook messages and macro-enabled workbooks to upload without conversion.\n\n### CLI\n\n- The CLI now uploads macro-enabled Excel workbooks with the correct media type, so original `.xlsm` workflow inputs work without manual conversion.\n\n### SDK\n\n- TypeScript SDK file helpers now infer the correct media types for `.xlsm` workbooks and `.msg` Outlook messages.\n\n### Infrastructure & processing\n\n- Document parsing now reads Excel, legacy Excel, and macro-enabled workbooks directly, preserving every non-empty sheet and its cell evidence without executing formulas or macros. Large single-page extractions are also split into bounded AI context windows instead of failing at the model limit.\n\n---\n\n## 0.16.6 (2026-09-09)\n\n### Infrastructure & processing\n\n- Template processing now enforces memory limits when joining large collections, preventing crafted templates from exhausting worker memory.\n\n---\n\n## 0.16.5 (2026-09-08)\n\n### Platform (Studio)\n\n- Human review is now available in production, including workflow authoring and review queues.\n\n### Public API\n\n- Human review API endpoints are now available in every production organization for listing tasks, confirming fields, and completing reviews.\n\n### Infrastructure & processing\n\n- Workflow and agent runs can now request human review in every production organization.\n\n---\n\n## 0.16.4 (2026-09-08)\n\n### Platform (Studio)\n\n- Studio adds List Archive and Extract Archive File steps for ZIP workflow inputs. Enumerate archive contents, wire `\\{\\{ item.path }}` through foreach, and pass extracted files straight into Parse, Vision, or Search Files without leaving the builder.\n- Studio now finishes multi-GB file uploads with resumable multipart transfers, retrying individual parts without restarting the whole file.\n- Studio workflows now include Search Files: ask a question about a ZIP archive and get a cited answer plus the files the step inspected. Scope the search to a folder inside the archive and use the same model and reasoning controls as other AI steps.\n\n### Public API\n\n- Upload ZIP archives as reusable workflow inputs through the Files API. Archives can be much larger than single documents, so teams can pass bundled evidence, exports, or multi-file drops into the same runs that already accept PDFs and Office files.\n- File uploads can now negotiate a resumable multipart session for multi-GB objects, with on-demand part URLs, authoritative resume listing, and safe completion that never overwrites a finished file.\n- Starting a run from a reusable file id now keeps a private run-owned reference to the original bytes instead of duplicating large uploads. Deleting the reusable file leaves past runs readable until those runs themselves are deleted.\n\n### CLI\n\n- Dataset import and export now keep a single `/api/v1` prefix when the CLI base URL already includes `/api/v1`, so those commands reach the dataset API instead of a doubled `/v1/v1` path.\n- The CLI now uploads large run files with resumable, storage-direct transfers, so multi-GB inputs stream from disk instead of loading into memory or a single request.\n- The CLI now recognizes `.zip` files when uploading reusable workflow inputs, so archive uploads get the correct content type without extra flags.\n\n### SDK\n\n[View full release notes →](/releases/0.16.4)\n\n---\n\n## 0.16.3 (2026-09-08)\n\n### Platform (Studio)\n\n- Human review: open pending reviews directly from run details and confirm unchanged fields inline from the field list.\n\n### Public API\n\n- Human review field confirmations now preserve valid JSON `null` values and return clear validation errors when a reviewed value does not match its schema.\n\n---\n\n## 0.16.2 (2026-09-08)\n\n### Platform (Studio)\n\n- Human review: pause workflows and agents only when selected fields need attention, inspect source files beside structured output with spatial citation highlights when lineage is available, correct and confirm values, then approve the same run to continue. Confidence thresholds, explicit field selection, required-field progress, rejection, and cancellation keep exception review focused instead of forcing teams to recheck every field.\n\n### Public API\n\n- Human review APIs now list pending tasks, return review data and source-file references, persist field corrections and confirmations, and approve or reject paused runs with optimistic concurrency protection. Task detail may also include resolved lineage and parsed-document context when an upstream grounded extract produced sidecars.\n\n### CLI\n\n- Workflow authoring now includes human-review guidance and ready-to-use templates for confidence-based exception review and explicit approval of critical fields.\n\n### SDK\n\n- TypeScript and Python SDKs now expose human-review resources for listing and retrieving tasks, confirming corrected fields, downloading attached source files, and approving or rejecting paused runs.\n\n### Infrastructure & processing\n\n- Grounded extraction now runs the same shared algorithm locally when a parse step supplies a valid structured document and your provider supports strict structured output. Step JSON stays schema-shaped with `_grounding` metadata; lineage and the parsed document graph are stored as optional sidecars for review and audit, not mixed into workflow output. Text-only inputs and unsupported providers continue to use the existing text grounding path with clear degraded markers when the shared path is unavailable.\n\n---\n\n## 0.16.1 (2026-09-07)\n\n### Platform (Studio)\n\n- GPT-6 Astra is available across workflows, agents, evaluations, and vision tasks, with configurable reasoning and current token pricing.\n- Self-hosted PaddleOCR models now appear with clear provider identity in Studio model selectors and settings.\n- Archive imports now reject malformed ZIP64 data safely instead of risking an unbounded processing loop.\n\n### CLI\n\n- CLI archive handling now rejects malformed ZIP64 data safely instead of risking an unbounded processing loop.\n\n### Infrastructure & processing\n\n- GPT-6 Astra is available across workflows, agents, evaluations, and vision tasks, with configurable reasoning and current token pricing.\n- Self-hosted deployments can connect directly to PaddleOCR-VL for high-quality document parsing, with bounded concurrency and long-running PDF support built in.\n\n---\n\n## 0.16.0 (2026-09-07)\n\n### Platform (Studio)\n\n- Agent model pickers are now compact, searchable, grouped by provider, and ordered from the most capable model to the least without changing configured defaults.\n- Send Email is now a first-class workflow action. Add Resend or SMTP servers in Settings → Email servers, then pick a stable `ems_…` server on the step — including generated files from the same run as attachments. Cloud and on-prem share this Settings surface; there is no default server. Secrets stay encrypted, and reads never show credentials. Changing an SMTP host, username, or provider asks you to re-enter the password so a stored secret cannot follow a new destination.\n\n### Public API\n\n- The public API now manages organization email servers at `/v1/email-servers`: list, create, inspect, update, delete, and send a connectivity test. Each server is an `ems_…` resource with a Resend or SMTP transport. Secrets are encrypted and never returned; disabled servers reject tests, and names must be unique among live servers. Updating SMTP to a different host or username requires a new password or explicitly clearing authentication — the previous password is never reused against a new destination.\n\n### CLI\n\n- Manage organization email servers with `eigenpal email-servers`: list and inspect `ems_…` servers, create or update Resend and SMTP providers (including an optional SMTP CA PEM), delete servers, and send a live test message with `--to`. Secrets are read from stdin, a file, or a secure prompt — never from command-line flags.\n\n### SDK\n\n- TypeScript and Python SDKs now manage organization email servers: list, create, inspect, update, delete, and send a connectivity test. Stored credentials are never returned.\n\n### Infrastructure & processing\n\n- Send Email delivers through the organization server selected on the step. There is no fallback: a missing, deleted, or disabled server fails the run. Evaluation runs skip delivery, including workflows invoked from an eval. Cancelling a run aborts an in-flight send. Multi-tenant SMTP servers must resolve to public addresses, while single-tenant deployments can use internal relays. Partial SMTP acceptance reports which recipients were delivered or rejected so operators can avoid duplicate reruns. SMTP may still deliver twice if a worker stops after the relay accepts the message; Resend deduplicates the same step attempt.\n\n---\n\n## 0.15.1 (2026-09-04)\n\n### Infrastructure & processing\n\n- OpenParser OCR capacity now recovers cleanly after failed updates, avoiding unnecessary warm resources while preserving active document processing.\n\n---\n\n## 0.15.0 (2026-09-04)\n\n### Platform (Studio)\n\n- Workflow validation now explains when a catalog model belongs in `provider` instead of the raw `model` override, and reruns preserve clean original filenames in generated outputs and citations.\n- Make document inputs uploaded in Studio datasets available to experiment runs, including examples saved by earlier releases.\n\n### Public API\n\n- Experiment result responses and JSON exports now include evaluator-specific structured details, so clients can identify the exact JSON path, expected value, and actual value behind a failed comparison. CSV exports retain their existing stable columns.\n\n### CLI\n\n- Experiment analysis is now built into the CLI for workflows and agents: summarize pass, fail, error, and score totals; filter failures by evaluator; inspect structured discrepancy paths; and compare actual outputs between batches. Run payloads can be projected with `--select`, and repository-level validation discovers nested workflow projects automatically. Polling commands also expose consistent wait limits and reject flag combinations that cannot produce a reliable verdict. Waiting commands now keep human output concise by default; pass `--json` whenever scripts need the terminal payload.\n- `eigenpal docs` now lists, searches, and reads the complete release-matched platform documentation offline, including detailed evaluator syntax, workflow step guides, CLI reference, and the OpenAPI contract.\n- CLI file uploads now send valid content types for Outlook and unknown files, cancellation confirms the asynchronous request clearly, and run comparisons show every repeated workflow step by branch and iteration path.\n\n### Infrastructure & processing\n\n- Make document inputs uploaded in Studio datasets available to experiment runs, including examples saved by earlier releases.\n- Exact-diff evaluators can exclude volatile fields with `ignore: true`, including nested fields inside a selected object or array. This keeps golden outputs readable while scoring only stable business data such as identities, names, and classifications.\n- Script steps now bind inputs by parameter name, so workflows behave consistently after storage even when JSON key order differs from the authored YAML.\n\n[View full release notes →](/releases/0.15.0)\n\n---\n\n## 0.14.3 (2026-09-04)\n\n### Platform (Studio)\n\n- Model selection now includes the GPT 5.6 Sol, Terra, and Luna lineup plus Claude Fable 5, Fable 5.1, Opus 5, and Sonnet 5. Reasoning effort can be configured for supported workflow steps, agent training and runs, workflow-building chat, and LLM judges; existing choices keep their current provider defaults when the setting is omitted.\n\n### CLI\n\n- Workflow YAML can configure model-aware reasoning effort on AI steps and LLM judges. Omit the setting to preserve each model's current default.\n\n### Infrastructure & processing\n\n- AI processing supports the latest GPT and Claude request formats, including reliable structured extraction with Claude Fable 5 and Fable 5.1. Workflow and agent execution can pass an optional model-aware reasoning effort while preserving previous defaults, and agent sandboxes can use GPT 5.6, Claude Fable 5, Fable 5.1, Opus 5, and Sonnet 5.\n\n---\n\n## 0.14.2 (2026-09-02)\n\n### Infrastructure & processing\n\n- Single-node deployments can now upgrade installations with large legacy datasets without startup failures or loss of trigger configuration.\n\n---\n\n## 0.14.1 (2026-09-02)\n\n### Infrastructure & processing\n\n- Single-node deployments can now upgrade installations with legacy run review data without startup failures.\n\n---\n\n## 0.14.0 (2026-09-02)\n\nThis release gives document teams more control over structured-data quality.\nExact-diff evaluators can express field-specific matching rules, PDF parsing can\npreserve visual layout, and spreadsheet conversion can retain the rows, columns,\nand displayed values that matter to downstream workflows.\n\nCLI authoring guidance makes these capabilities easier to discover and safer to\nautomate, with non-interactive commands failing clearly instead of waiting on\nunavailable prompts.\n\n### Platform (Studio)\n\n- `ai.parse` adds `outputFormat: layout` for native PDF extraction. It returns fixed-width plain text that preserves columns, spacing, and line breaks for multi-column forms and tables that lose meaning when flattened. This PDF-only format must be selected explicitly with `parseMode: native` or `parseMode: native-or-ocr`: native mode fails closed if layout extraction cannot complete, while hybrid mode keeps accepted layout pages and substitutes OCR markdown only for suspect or empty pages. Existing formats and defaults are unchanged.\n- Spreadsheet to JSON now handles `.xls` and `.xlsx` workbooks with configurable headerless input or an explicit header row, named or positional column projection, rectangular ranges, and raw or displayed cell values. Displayed values preserve formatted text such as dates, leading zeros, punctuation, diacritics, and embedded newlines. Blank-cell and blank-row policies make sparse sheets predictable, while optional sheet metadata and diagnostics explain the selected range and non-fatal issues. Existing zero-config output remains `rows`, plus `fileId` when CSV output is enabled; zero-config CSV keeps the full selected sheet, and configured CSV follows the same projection. File, row, column, and cell limits reject unsafe workloads before conversion.\n- Exact-diff evaluators add composable per-field rules for extraction outputs. Choose ordered or unordered comparison independently from `items: at-least | at-most | exactly`, set numeric tolerances, and reject unexpected object fields where strict output shapes matter. Ordered arrays retain prefix-compatible matching, while unordered arrays find the best one-to-one structural pairing instead of depending on row order. Unordered object arrays can also use typed `matchBy` identities such as `sku` or `[country, sku]` for predictable single- or composite-key matching. Studio now provides a rule editor with path-aware validation. Grounding metadata is excluded from scoring, oversized comparison workloads fail safely with bounded diagnostics, and existing evaluator configurations keep their historical behavior.\n\n### Public API\n\n- Template creation now accepts reusable file references correctly, restoring CLI template uploads and workflow pushes that use local DOCX or XLSX files.\n\n### CLI\n\n[View full release notes →](/releases/0.14.0)\n\n---\n\n## 0.13.2 (2026-09-01)\n\n### CLI\n\n- CLI installation no longer downloads packages already included in its self-contained executable, reducing install overhead and improving compatibility with restricted enterprise networks.\n\n---\n\n## 0.13.1 (2026-08-31)\n\n### Platform (Studio)\n\n- Workflows can turn JSON rows into a downloadable Excel workbook with a new JSON to XLSX step. Pick ordered columns, map an array of objects, and get a `.xlsx` run output — including multi-sheet workbooks — without filling a template.\n- Studio now uses the shared theme provider, so system / light / dark stays aligned with OpenParser instead of drifting independently.\n- Publishing a workflow that still has a local `template: ./file.xlsx` path now fails with a clear error. Use `eigenpal workflow push` to upload the file, or set `templateId` to a `tmpl_…` id first.\n- Studio template uploads and replacements now create immutable, checksum-backed revisions and discover tokens consistently across DOCX and XLSX files. Deleting a logical template preserves revision content used by pinned workflows.\n- Fill Template (`transform.template`) now documents workspace `tmpl_...` templates separately from Git agent templates, and Studio copy covers DOCX and XLSX. XLSX files use `\\{placeholder}` and `\\{table:array.prop}` in the spreadsheet; `\\{\\{placeholder}}` in an uploaded sheet warns on upload and fails at fill instead of leaving leftover braces. `templateId` must be a workspace `tmpl_...` ID, not a file ID. Filled values that look like formulas stay text; formulas already in the template stay formulas.\n- Studio now blocks crafted HTML from retaining executable content during sanitization.\n\n### Public API\n\n- Workflow push can fully remove a template it uploaded if publishing then fails. Deleting a template that workflows already pin still keeps those revisions runnable.\n- The public API now lists the text, vision, and OCR models configured for your environment. `GET /v1/models` is a cheap catalog inventory for the current tenant: it reports whether each model is configured and which capability it is the default for, without probing live providers or exposing secrets.\n- The public API now supports the full lifecycle for tenant-scoped DOCX and XLSX templates: upload, inspect, list, download, replace, and delete, with direct-upload support for larger files. Every replacement creates a checksum-backed immutable revision; deleting the logical `tmpl_…` resource preserves revisions already pinned by workflows.\n\n### CLI\n\n- `workflow versions create --file` now resolves local `template:` paths the same way as `workflow push`, and `workflow templates smoke --data` help documents the JSON fixture file path.\n- `eigenpal workflow push` keeps local Office templates inside the workflow project, including when a path uses `../` or a symlink. Files outside that directory need `--allow-external-templates`. Push validates the workflow and version before uploading, creates new template resources instead of moving shared `tmpl_…` pointers, and fully removes those unpublished uploads if publish does not succeed.\n- When resolving a workflow by `wf_…` id, connection failures, auth errors, and server outages now surface their normal CLI messages instead of being misreported as \"workflow not found.\"\n\n[View full release notes →](/releases/0.13.1)\n\n---\n\n## 0.13.0 (2026-08-25)\n\n### Platform (Studio)\n\n- API reference for listing dataset examples now documents `include=metadata`, so you can page through example ids, names, and file refs without loading every payload.\n- Local Studio development no longer keeps a growing on-disk compiler cache that can exhaust memory during long `bun dev` sessions.\n- Studio's sidebar theme picker now supports keyboard navigation across system, light, and dark.\n- Studio dashboard sessions continue to authenticate `/api/v1` calls. Token-based `/api/v1` and `/v1` requests still work without a browser login, and the dedicated API hostname keeps its public routing and CORS behavior.\n- Studio save-as-release still publishes a tagged version as the live workflow. Publishing from an existing snapshot creates a new tagged release instead of rewriting the original tag, so earlier releases stay intact. Connect API docs version pickers follow the public version list, so after restore the current untagged version shows as latest while tagged releases stay selectable.\n\n### Public API\n\n- List dataset examples without pulling every payload. `GET /api/v1/automations/:id/examples` now accepts `include=metadata`, which returns ids, names, annotations, and expected file refs while leaving input and expected JSON unloaded. Keep the default `include=full` when you still need the complete example bodies.\n- You can now create, promote, and restore workflow versions through the public API. Create a tagged candidate with `activate: false` to test it without changing live traffic, then promote that exact version after it qualifies. You can also publish from YAML, copy an existing version into a new release without changing its original tag, or restore an earlier snapshot. Name-conflict errors include `conflictingWorkflowId` so you can see which workflow already owns the name.\n\n### CLI\n\n- `eigenpal workflow versions` can now create, promote, and restore YAML workflow versions through the public API. Tag a candidate from a YAML file or an existing snapshot with an explicit semver, keep it off live traffic with `--no-activate`, then promote that exact version when it qualifies. Restoring still rolls a workflow back by copying a snapshot into a new current version — lists now show that untagged HEAD clearly instead of hiding it. `workflow versions list --limit` and `--offset` page that full public list locally. `--json` prints the sliced `\\{ data, total, limit, offset }` envelope (`total` is the unsliced count), not the raw server payload.\n\n### SDK\n\n- TypeScript and Python SDKs can list dataset examples with `include: \"metadata\"`. That returns ids, names, annotations, and expected file refs without loading each example's input and expected JSON. The default remains a full payload, so existing list calls stay unchanged.\n\n[View full release notes →](/releases/0.13.0)\n\n---\n\n## 0.12.2 (2026-08-21)\n\n### Platform (Studio)\n\n- Document editing: the DOCX editor used for templates, run file review, and Office file previews now follows your light or dark theme, and Save (including Cmd/Ctrl+S) writes back to the document you opened instead of downloading a copy. Documents that fail to open now report the reason instead of showing an empty editor. Placeholder highlighting in DOCX templates is temporarily unavailable.\n- Connect: a workflow that wraps another workflow now documents the full response shape. Its OpenAPI spec, Swagger UI preview, and the response examples and generated types on the Connect page show the nested objects and arrays returned by the workflow it calls, instead of leaving those fields untyped.\n\n---\n\n## 0.12.1 (2026-08-19)\n\n### Platform (Studio)\n\n- Connect: download an OpenAPI spec (swagger.json) and preview it in Swagger UI directly from the Connect page. Selecting a workflow or agent produces a spec for just that automation: the five endpoints needed to integrate it (start a run, poll it, cancel it, list and download artifacts), with the request body documenting its exact input fields and file uploads and run responses typed with its actual output schema. With no selection you get the full platform API spec. Swagger UI is bundled with the product, so the preview also works in on-prem installs without internet access.\n\n---\n\n## 0.12.0 (2026-08-18)\n\n### Platform (Studio)\n\n- The workflow builder chat honors the new `disableTemperature: true` model configuration option, so models that reject a sampling temperature work from the first request.\n- Object-typed workflow inputs can now declare a nested schema. In the workflow builder, choosing the Object type (or an array of objects) opens a property editor where you define each field with its type, description, allowed enum values, and required flag, including nested objects and arrays up to five levels deep. Declared fields are enforced when a run starts: missing required fields and type mismatches are rejected with precise field paths. Downstream steps get full autocomplete and type resolution for nested references such as `\\{\\{ input.metadata.vendor.name }}`, and the declared shape appears in the scope browser and in generated API documentation. The builder flags expressions that reference undeclared nested fields, the run form and evaluation input editor pre-fill the declared required fields, and the AI expression generator sees the nested shape when suggesting expressions. The headless execution server now enforces declared inputs with the same validator, so its API documentation and runtime behavior agree.\n- Grounded OpenParser extraction results can now carry complete field lineage through the Eigenpal web runtime, preserving source evidence and confidence metadata for downstream review experiences.\n\n### Public API\n\n- Object-typed workflow inputs can now declare a nested schema. In the workflow builder, choosing the Object type (or an array of objects) opens a property editor where you define each field with its type, description, allowed enum values, and required flag, including nested objects and arrays up to five levels deep. Declared fields are enforced when a run starts: missing required fields and type mismatches are rejected with precise field paths. Downstream steps get full autocomplete and type resolution for nested references such as `\\{\\{ input.metadata.vendor.name }}`, and the declared shape appears in the scope browser and in generated API documentation. The builder flags expressions that reference undeclared nested fields, the run form and evaluation input editor pre-fill the declared required fields, and the AI expression generator sees the nested shape when suggesting expressions. The headless execution server now enforces declared inputs with the same validator, so its API documentation and runtime behavior agree.\n- Listing runs with `sinceLastClosed=true` works again. Once a review had been closed, asking for the runs recorded since then returned an error instead of the runs, so review tooling that polls for new work had no way to ask \"what has arrived since I last signed off\". The filter now returns those runs.\n\n### Infrastructure & processing\n\n- Model entries in the deployment configuration can now set `disableTemperature: true`. Workflow steps then never send a sampling temperature to that model, which lets reasoning models (and gateways in front of them) that reject the parameter run without a first-call retry.\n- Object-typed workflow inputs can now declare a nested schema. In the workflow builder, choosing the Object type (or an array of objects) opens a property editor where you define each field with its type, description, allowed enum values, and required flag, including nested objects and arrays up to five levels deep. Declared fields are enforced when a run starts: missing required fields and type mismatches are rejected with precise field paths. Downstream steps get full autocomplete and type resolution for nested references such as `\\{\\{ input.metadata.vendor.name }}`, and the declared shape appears in the scope browser and in generated API documentation. The builder flags expressions that reference undeclared nested fields, the run form and evaluation input editor pre-fill the declared required fields, and the AI expression generator sees the nested shape when suggesting expressions. The headless execution server now enforces declared inputs with the same validator, so its API documentation and runtime behavior agree.\n\n---\n\n## 0.11.3 (2026-08-13)\n\n### Platform (Studio)\n\n- API reference pages for starting and reading runs now show complete examples, including `output` and `execution.status`.\n\n### Public API\n\n- Run API: completed-run examples now include `type`, `execution.status`, `output`, `files`, and `error`, instead of a shared async/completed union that dropped those fields. Default GET and list responses populate `execution.retry.nextRun` when a retry exists, and `expand=execution` keeps `schemaValid` instead of clearing it. Child invoke-workflow runs document `parentExecutionId` and `childExecutions`.\n\n### SDK\n\n- Generated run types now distinguish a completed run from the async accepted envelope (`RunAccepted`), and include `parentExecutionId` for child invoke-workflow runs.\n\n---\n\n## 0.11.2 (2026-08-07)\n\n- Internal improvements.\n\n---\n\n## 0.11.1 (2026-08-07)\n\n### Platform (Studio)\n\n- Document and image processing now runs on updated imaging components that carry upstream security fixes.\n\n### Infrastructure & processing\n\n- Document and image processing now runs on updated imaging components that carry upstream security fixes.\n\n---\n\n## 0.11.0 (2026-08-06)\n\n### Platform (Studio)\n\n- Workflow builder chat now works with reasoning models served through a self-hosted `openai-compatible` gateway, instead of failing with a \"temperature is not supported\" error. On models that only accept their own default temperature setting, replies can vary between attempts on the same question.\n- Canonical API hostnames now consistently expose only supported API and operational routes, returning a clear 404 for unsupported discovery paths.\n- Agent Builder attachments now negotiate multipart or storage-direct transfer, so large PDFs and archives can reach the active sandbox without crossing cloud payload limits. Large downloads use the same secure dual path. Self-hosted operators can set `deployment.multipartMaxBytes` in `eigenpal.config.yaml`; the supplied on-prem deployments keep files on multipart and streamed downloads by default.\n- Canonical API hostnames now serve API routes and discovery endpoints reliably without Studio sign-in handling intercepting requests.\n\n### Public API\n\n- Upload and download reusable files up to 100 MiB through one negotiated API: files within the deployment body limit use multipart, while larger cloud transfers use verified storage-direct uploads and short-lived authenticated download links. Retry-safe temporary run and Builder files expire after 24 hours. Existing multipart routes and `studio.eigenpal.com/api/v1` remain compatible, and new integrations can use `api.eigenpal.com/v1`.\n\n### CLI\n\n- The CLI now uses `api.eigenpal.com` as the default cloud API origin and automatically pre-uploads run files that exceed the multipart request limit. Self-hosted users can keep custom API origins and set `EIGENPAL_MULTIPART_MAX_BYTES` to their proxy limit, or `none` to keep all files on multipart.\n\n### SDK\n\n- The TypeScript and Python SDKs now transparently upload large run inputs without crossing cloud request limits, follow secure storage-direct downloads, and default cloud calls to `api.eigenpal.com`. Set `multipartMaxBytes` / `multipart_max_bytes`, or `EIGENPAL_MULTIPART_MAX_BYTES`, to match a self-hosted proxy; use `null` / `None` to keep every run file on multipart. Explicit `files.upload` files remain reusable until deleted.\n- TypeScript file uploads now follow the server-negotiated multipart endpoint, improving compatibility across hosted and self-managed route layouts.\n\n[View full release notes →](/releases/0.11.0)\n\n---\n\n## 0.10.56 (2026-08-05)\n\n### Platform (Studio)\n\n- Agent Builder training chat now shows Pierre file diffs for edit/write, a Pierre syntax-highlighted file view for Read file, secure request-secret password cards (encrypted into the draft; the agent only sees configured/skipped), and a quiet timeline note when you release an agent version from the dashboard.\n\n### Infrastructure & processing\n\n- Production releases that do not change document processing finish faster by reusing verified OCR provider checks from the last successful release, while still re-checking providers when processing code or infrastructure changes.\n\n---\n\n## 0.10.55 (2026-08-05)\n\n### Platform (Studio)\n\n- Agent Builder now resumes your latest draft, clearly distinguishes unsaved edits from saved changes that are not live, and provides direct Save and Release actions. Releases show the current and next version and let you choose a patch, minor, or major update. Dashboard save and release actions remain available to the builder as private context, so it can accurately answer what is live without guessing. Starting a separate draft is explicit, attachments remain available when beginning a conversation, stopped sandboxes can be restarted without losing the draft, and test runs reliably receive JSON-only inputs.\n\n### Public API\n\n- Agent Builder releases now complete live automation synchronization reliably, so a successful release is immediately available without a separate recovery step.\n\n### Infrastructure & processing\n\n- OCR and LLM model catalogs keep loading when the service adds new optional fields, so Studio and Eigenpal no longer fall back to stale model lists during catalog updates.\n- Cloud document processing providers that are already available stay online during routine production updates when their identity is unchanged. New or changed providers stay unavailable until they pass live verification, so customers keep working providers instead of a full outage window.\n\n---\n\n## 0.10.54 (2026-08-04)\n\n### Platform (Studio)\n\n- Workflow Studio now shows each OpenParser OCR model with its actual provider logo, keeps narrow step configuration panels contained, and places settings, theme, and sidebar controls together in a cleaner navigation footer.\n\n---\n\n## 0.10.53 (2026-08-04)\n\n### Platform (Studio)\n\n- OpenParser Studio now visualizes the `openparser@1` document graph directly, including typed elements, figures, tables, relationships, and element-level extraction citations.\n\n### Public API\n\n- OpenParser parse responses now return the unified `openparser@1` document graph, with plain text, canonical Markdown, pages, typed elements, relations, annotations, assets, geometry, confidence, and provider provenance in one predictable contract.\n\n---\n\n## 0.10.52 (2026-08-04)\n\n### Platform (Studio)\n\n- Agent Builder: improve connection recovery so interrupted sessions resume reliably, stale environments are replaced safely, and approval prompts remain retryable when delivery fails.\n\n---\n\n## 0.10.51 (2026-08-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.50 (2026-08-03)\n\n### Platform (Studio)\n\n- OpenParser Studio: pipeline creation no longer reports a duplicate-name error after a successful save, and edits now save reliably from the browser.\n\n---\n\n## 0.10.49 (2026-08-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.48 (2026-07-30)\n\n### Platform (Studio)\n\n- OpenParser Studio now displays canonical OpenParser JSON with readable indentation, including large document results.\n\n---\n\n## 0.10.47 (2026-07-30)\n\n### Platform (Studio)\n\n- OpenParser Studio now keeps large document results responsive, renders OCR markdown with clearer structure, and provides consistent copy and download actions for Markdown and JSON output. Documentation links now reliably open the generated API reference.\n\n### Infrastructure & processing\n\n- OpenParser jobs now recover more safely when document processing capacity becomes unavailable. Retryable failures pause new dispatches, retry without duplicate charges, and bound large-document processing so one document cannot overwhelm the service.\n\n---\n\n## 0.10.46 (2026-07-30)\n\n### Platform (Studio)\n\n- Team settings: bring back the invitation link. Creating an invitation now shows its link straight away whenever no invitation email was delivered, and administrators can pull up the link again at any time from the invitations table. This unblocks onboarding on deployments without email delivery, where handing over the link is the only way to get someone into the workspace.\n- Run details: field grounding now labels flagged fields by what the extraction actually reports, showing \"3 with low confidence\" instead of \"3 to review\". The count is a confidence signal, not an assigned task.\n\n---\n\n## 0.10.45 (2026-07-29)\n\n### Platform (Studio)\n\n- Parse Document setup now clearly separates OCR from Vision AI, automatically offers available OpenParser OCR models, shows each model's per-page price, displays only the controls that affect the selected method, and surfaces structured layout data with tables, figures, polygons, and bounding boxes for downstream workflow steps.\n\n### CLI\n\n- The workflow authoring reference now covers explicit OCR and Vision AI parse modes, optional figure-caption models, and structured layout output.\n\n### Infrastructure & processing\n\n- Document parsing now defaults to higher-fidelity OCR, preserves canonical structured layout alongside Markdown, and automatically supports available OCR models with provider-specific per-page pricing. Other OCR providers retain their existing rates.\n\n---\n\n## 0.10.44 (2026-07-28)\n\n- Internal improvements.\n\n---\n\n## 0.10.43 (2026-07-27)\n\n- Internal improvements.\n\n---\n\n## 0.10.42 (2026-07-27)\n\n- Internal improvements.\n\n---\n\n## 0.10.41 (2026-07-27)\n\n### Platform (Studio)\n\n- Run traces now show each attempt of an AI request. A request that timed out and was retried used to appear as a single long bar, so a step that spent three timeouts on one page looked identical to one slow call. The raw trace now has one bar per try, labelled with the try number, and the run timeline marks a retried call with how many times it was sent. Retried requests also record how long they waited for a free slot, which distinguishes a slow model from a queue backed up behind its own in-flight requests. For documents parsed page by page, each split retry records the pages it covered and how deep the split went.\n- Runs and Experiments improvements: - An experiment run now shows the same input and output panels as the main run view, including input file downloads, per-step output files, and inline field-level output review. - Scored runs show their eval score in the runs list and in the run header, so an experiment's results can be compared without opening each run. - A run that came from an experiment or a dataset example now links straight to that run in the Evals view. - The Live and Experiments toggles on Runs are remembered between visits. - Field grounding: a wide document no longer overflows the panel. Wide tables and long unbroken text scroll inside the document card.\n\n---\n\n## 0.10.40 (2026-07-25)\n\n### Infrastructure & processing\n\n- Processing reliability on busy deployments: health checks are now served independently of document processing, so the service stays responsive to them even while working through a heavy document. It is no longer restarted mid-run just because it is under load, so long-running document runs complete more reliably.\n- Document processing is more resilient on CPU- and memory-constrained deployments. Page rasterization for vision and OCR now runs in isolation, so a single large or malformed document can no longer stall the processing service or cause it to restart mid-run. Runs on big scanned documents that previously failed partway through with \"the worker stopped before this attempt recorded a terminal result\" now complete reliably.\n\n---\n\n## 0.10.39 (2026-07-25)\n\n### Platform (Studio)\n\n- Label Pages runs: the page preview now shows the classified document in the full viewer instead of small thumbnails. PDFs render page-by-page with zoom and navigation and each page's labels shown beside it; Word and other Office documents open in their own preview next to a per-page label list. Filter by a label to focus on just the pages that carry it.\n\n---\n\n## 0.10.38 (2026-07-24)\n\n### Platform (Studio)\n\n- OpenParser Studio: manage extraction pipelines from a dedicated workspace — create, edit, run, duplicate, and delete saved configurations. Jobs show the pipeline and version that produced each result, and you can save a new pipeline from job settings.\n- OpenParser Studio: clearer progress while documents upload, parse, and extract, with live elapsed timing at each stage. Job history and the playground share a unified header with breadcrumbs, improved document and Markdown output viewers, and a cleaner parse sidebar. Choose light or dark theme and manage your account from the sidebar; model selectors and in-product copy are simpler throughout the workspace.\n- Members provisioned through SSO are now read-only in workspace member settings. Their role and access come from your identity provider's groups, so admins can no longer change or remove them by hand, and each SSO member is clearly labeled. Accounts created with a username and password stay fully manageable by admins.\n\n### Public API\n\n- **Breaking:** OpenParser API resource identifiers now use consistent prefixed ids. Parse, extract, and batch jobs return `opj_…` ids instead of UUIDs. Saved extraction pipelines use `oppl_…` instead of `oep_…`. New parse output writes figure image ids as `opfig_…` instead of `ocrfig_…`. Existing jobs and pipelines are remapped automatically on upgrade when the OCR queue is idle enough for migration preflight. Prefer the new formats in job URLs, `parse_job_id`, `pipeline_id`, and batch child `job_id` fields. During the transition, previously issued UUID job ids, `oep_…` pipeline ids, and UUID list cursors remain readable; responses continue to return the preferred `opj_…` / `oppl_…` forms. Historical parse artifacts and `result_json` may still embed legacy `ocrfig_…` figure paths; `GET /files/\\{id}` accepts both `opfig_…` and `ocrfig_…`.\n\n### Infrastructure & processing\n\n- Hardened AI-powered document processing against prompt-injection attempts hidden inside uploaded documents. Instructions embedded in a document can no longer steer extraction, classification, or vision results away from the requested schema, or coax the model into disclosing its own configuration.\n- AI vision step results no longer include internal document storage references in their metadata. The step's `_vision` provenance now records only which pages were inspected and how many were merged, keeping internal storage paths out of workflow output.\n\n---\n\n## 0.10.37 (2026-07-24)\n\n### Platform (Studio)\n\n- New **Label Pages** step tags each page of a document with zero or more labels (multi-label) using AI, and groups the results into a label-to-pages map. Unlike section splitting — which produces one contiguous range per section — this collects pages of the same kind wherever they appear, so scattered pages (for example every signature or photo page throughout a report) can be gathered in one place. The page-inspection step can now take an explicit list of page indices, so you can route the pages for a given label straight into a visual inspection without hand-listing them.\n\n---\n\n## 0.10.36 (2026-07-23)\n\n### Platform (Studio)\n\n- OpenParser Job History now reports the real end-to-end duration for completed parse and extraction jobs instead of showing a zero or unavailable measurement.\n- Running OpenParser jobs now show the document scanning animation from the playground while results are being prepared.\n- Parse and Extract now use consistent operation icons across OpenParser Studio and documentation.\n\n---\n\n## 0.10.35 (2026-07-23)\n\n### Platform (Studio)\n\n- OpenParser sign-in and account creation now redirect directly to the branded authentication flow without an intermediate confirmation page.\n- OpenParser parse jobs now retain both `raw` and `openparser@1` results. Retrieve either representation with `GET /jobs/\\{id}/result?format=...`, switch formats in the Studio Output tab, and start extraction from a raw-format parse job without running OCR again.\n\n### Public API\n\n- OpenParser parse jobs now retain both `raw` and `openparser@1` results. Retrieve either representation with `GET /jobs/\\{id}/result?format=...`, switch formats in the Studio Output tab, and start extraction from a raw-format parse job without running OCR again.\n- OpenParser now keeps recognized text aligned with its original bounding box by default. Set `ocr_options.merge_layout_blocks` to `true` per parse, extraction, batch item, or saved pipeline when merged recognition is preferred over one-to-one text geometry.\n\n---\n\n## 0.10.34 (2026-07-23)\n\n### Platform (Studio)\n\n- OpenParser sign-in and account creation now keep OpenParser branding throughout the authentication experience.\n- OpenParser Studio: uploads and sample documents now open their Job History detail immediately, so browser back and forward navigation follows each run naturally while extraction and result review stay in one place.\n- Run detail now shows clean, readable file names for inputs and outputs instead of internal storage identifiers, and long file names no longer overlap the preview and download buttons.\n\n### Public API\n\n- OpenParser parsing now preserves every detected layout region—including empty title, header, and figure boxes—so document overlays remain complete. The obsolete `figure_assets` option is removed because figure regions are now always retained.\n- OpenParser can now process documents beyond 25 pages and admit batches of up to 100 documents, while retaining per-page safety limits.\n- OpenParser jobs can now stream their retained source documents with `GET /jobs/\\{id}/source`, making it easier to build durable review experiences around past runs.\n- `POST /suggest-schema` now returns the suggested schema inline as a convenience response instead of creating a job that clients must poll.\n\n### Infrastructure & processing\n\n- Documents uploaded without a declared file type are now recognized from their contents, so PDFs, RTF, and Office files parse reliably instead of failing with an \"unsupported file type\" error. This most often helped uploads coming from automated integrations that omit the file type.\n\n---\n\n## 0.10.33 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser Studio: make Playground the home page, add shareable social previews, clarify job status and pipeline empty states, and tidy the OCR model selector copy.\n\n### Public API\n\n- OpenParser suggested extraction model catalog (`GET /models/llm` in suggested mode) now surfaces up to 20 recommended models instead of 12, so more current options appear before you need to search.\n\n---\n\n## 0.10.32 (2026-07-22)\n\n- Internal improvements.\n\n---\n\n## 0.10.31 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser Studio production sign-in no longer auto-redirects to Eigenpal when you are signed out. Choose **Continue to sign in** on the local OpenParser page to authenticate with your Eigenpal account; sign-out stays on OpenParser.\n\n---\n\n## 0.10.30 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser production sign-in now shares Eigenpal sessions across its dedicated domain and returns users to their original OpenParser destination after authentication.\n- OpenParser Playground: remove the doubled border and rounded corners around the document workspace.\n\n### Infrastructure & processing\n\n- OpenParser: restore schema suggestions, use GPT-5.6 Terra as the default extraction model with GPT-4.1 Mini as a certified fallback, tighten compatibility checks, and provide clearer failure guidance.\n\n---\n\n## 0.10.29 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser Studio sign-in and sign-up now load the shared identity UI correctly for signed-out visitors.\n\n---\n\n## 0.10.28 (2026-07-22)\n\n### Platform (Studio)\n\n- API keys: keep usable credentials in the primary list and move revoked or expired credentials into a collapsed history section for faster scanning.\n- OpenParser Studio sign-in and sign-up now show OpenParser product copy and logo while retaining the shared Eigenpal identity.\n\n### Public API\n\n- OpenParser model discovery (`GET /models/llm`) now refreshes the live compatible catalog on the API service instead of falling back to a short emergency list when the catalog credential is missing from that process.\n\n### Infrastructure & processing\n\n- OpenParser document processing now bounds source downloads and retries transient storage failures, preventing stalled jobs from running indefinitely.\n\n---\n\n## 0.10.27 (2026-07-21)\n\n### Platform (Studio)\n\n- New Inspect Pages (Vision) step lets a workflow look at the actual page images of a document and return structured results, for details that only exist in the pixels rather than the text. Use it to check whether a document is signed, rate embedded photos, or spot stamps and logos. It works on PDFs, images, and Office documents, and you can point it at a specific page range (for example the section found by a Split step) so it only reviews the pages that matter. The run trace shows the pages it inspected next to the results.\n- Parsing can now describe the figures on a page as text. Enable \"describe figures\" on a Parse step and the images on each page (property photos, charts, stamps) are detected and captioned inline, so later steps that work on text, like Split, can find image-only pages. This is especially useful for scanned documents, where the photo pages carry almost no text on their own. You can provide custom instructions for how figures should be described.\n- Split step results are now also available keyed by section name. A later step can point at one section directly, for example `\\{\\{ steps.split.output.sections.photos.page_range }}`, instead of filtering the full list. This makes wiring a Split step into a downstream step much simpler.\n- The Inspect Pages (Vision) step now takes a Page From / Page To range instead of a single page-range expression, and both are optional. Leave them blank to inspect the whole document, which is processed in chunks and the results merged automatically. This makes it much easier to point the step at a range (for example the start and end of a Split section) or to scan an entire document without writing a range expression.\n\n---\n\n## 0.10.26 (2026-07-21)\n\n### Platform (Studio)\n\n- Wildcard API keys can use the OpenParser OCR API consistently with every other platform capability. Keys can also be restricted to the dedicated `ocr:full` scope when OCR-only access is preferred.\n- Run traces now include a Grounding panel for extract steps: every extracted value is highlighted in the input text, tinted by confidence, and clicking a field or a highlight jumps between them. Grounded fields also show inline context previews of the exact source passage, both in the panel and in the expanded step row. Split steps gain the same visual page-range panel the segmenter uses, with page thumbnails and per-section preview. The workflow builder reflects that grounding is on by default and lets you pick any configured provider as the grounding model, and capturing expected output from a run no longer snapshots volatile grounding metadata into evals.\n\n### Public API\n\n- Wildcard API keys can use the OpenParser OCR API consistently with every other platform capability. Keys can also be restricted to the dedicated `ocr:full` scope when OCR-only access is preferred.\n- OpenParser: completed extraction jobs can now be retrieved reliably with their attempt and usage metadata.\n\n### CLI\n\n- The step catalog now documents grounded extraction as the default: extract steps ship per-field confidence and source spans under the `_grounding` output key unless `grounded: false` is set.\n\n### Infrastructure & processing\n\n- Data extraction now verifies itself by default. Every extract step traces each extracted field back to its exact location in the source text and attaches a confidence level (high, medium, or low) plus a needs-review flag under a reserved `_grounding` output key, so downstream steps and evaluators can route uncertain values to a human. The verification pass runs on your workspace model (any configured provider), chunks long documents automatically, and falls back to deterministic text matching instead of failing the run when no model is available. Set `grounded: false` on a step to opt out.\n\n---\n\n## 0.10.25 (2026-07-20)\n\n### Platform (Studio)\n\n- Failed single sign-on attempts now return to the sign-in page with a clear, actionable message (for example, when an account's email domain isn't authorized or the account hasn't been granted access) instead of a blank error page.\n\n---\n\n## 0.10.24 (2026-07-15)\n\n### Platform (Studio)\n\n- Agent runs graded by configured evaluators now record a weighted score and pass/fail result, visible in the runs feed and run detail responses. Previously only workflow runs carried an evaluator verdict.\n- Email addresses for a workflow are unique across your whole organization, not just the workflow you are editing. Picking one that is already taken used to fail with a server error. It now tells you which workflow already receives email at that address, or that the workflow you are editing already has it, so you know what to do next. Duplicate folder names and duplicate workspace invites also report clearly instead of failing.\n- `ai.extract` with `grounded: true` no longer succeeds silently without producing grounding. When the grounding pass cannot run (missing OpenAI credentials on the worker, or a grounding model that is not an OpenAI model) the step now fails with an error that names the exact misconfiguration. When the pass runs but produces no field grounding, the output carries an explicit degraded marker instead of nothing. The grounding model picker in the workflow builder now only offers OpenAI models, matching what the grounding pass supports.\n- Agent training: when a training session fails to open, the dashboard now shows what went wrong instead of a generic error. The message names the setup step that failed, and a session blocked by secrets that cannot be decrypted says so and points at the agent settings. A session whose setup fails partway through no longer opens on an incomplete workspace.\n- Self-hosted deployments can now sign users in through corporate single sign-on services that use a redirect-and-token flow instead of OIDC. The new protocol supports mutual TLS for the server-to-server exchange, maps directory groups to EigenPal roles (admin, member, viewer) on every SSO sign-in so the directory stays the source of truth, and links existing password accounts by email so nobody loses access when SSO is turned on. Startup validation rejects unsafe callback origins and provider identifiers, while malformed or oversized identity responses fail closed.\n\n### Public API\n\n- Syncing an automation immediately after a release no longer fails with HTTP 500 while the new release tag propagates. The sync endpoint now reports a retryable status with a clear message when the Git source is momentarily unavailable.\n- Fixed single-experiment results export returning HTTP 400 whenever the `includeTrace` query flag was omitted. `workflow experiment results` and the auto-pull at the end of `workflow experiment watch` now download per-evaluator results in JSON and CSV again.\n- Creating an email trigger address that is already in use now returns 409 with a message naming the workflow in your organization that already uses it, instead of 500.\n\n### CLI\n\n- Agent example runs now report a real evaluator verdict in the CLI: `eigenpal run agents.&lt;name&gt; --example &lt;name&gt; --wait` waits for the verdict, prints the weighted score and pass/fail result, and `--fail-on-mismatch` exits non-zero when the run fails its evaluators, matching the existing workflow behavior. When no evaluators are configured, the CLI says so instead of silently reporting nothing.\n- `agents secrets` is now one command group with `list`, `set`, `unset`, `import`, and `export` subcommands (`agents secret` remains as an alias). The new `agents secrets list` shows the secret names and descriptions declared in the package without ever printing values. Previously `set` and `unset` lived under a separate singular command and `secrets list` failed with an argument error.\n- `agents sync` retries automatically with a short backoff when the server reports the Git source as temporarily unavailable, so the sync right after `agents release` succeeds without manual retries.\n- `agents dataset validate` now checks the same layout the server accepts on `agents dataset push`: example folders under `examples/`, file inputs referenced from `input.json` with `\\{ \"$file\": \"input/...\" }`, and `expected.json` optional. Previously the local validator demanded a different layout that push would then reject, so no dataset could satisfy both. Validation errors now point at the exact rule that failed, including a hint when example folders sit at the dataset root instead of under `examples/`. When the agent package carries an input schema, each example's full input object is validated against it (required fields, unknown keys, and value types, with `\\{ \"$file\": ... }` references accepted for file fields), so inputs that would fail at run start are caught locally. Failure-expected examples (`expected.json` with `$error`) are rejected for agent datasets, since agent runs are evaluated only when they complete.\n\n[View full release notes →](/releases/0.10.24)\n\n---\n\n## 0.10.23 (2026-07-15)\n\n- Internal improvements.\n\n---\n\n## 0.10.22 (2026-07-14)\n\n### Platform (Studio)\n\n- Organization members can now configure, test, and manage outbound webhooks from Studio.\n\n---\n\n## 0.10.21 (2026-07-14)\n\n### Platform (Studio)\n\n- Webhooks: notify external systems when workflow or agent runs are created or change status, with signed delivery, custom headers, retry history, testing, and manual redelivery from Studio.\n- Webhook signing secrets are now easier to copy securely from endpoint setup and details, with clearer event selection defaults.\n- Webhook setup now keeps failed submissions actionable with clear inline error feedback.\n\n### Public API\n\n- Run creation and rerun requests now publish signed lifecycle webhooks only after inputs are ready, so API-triggered automations never emit events for runs that fail during setup.\n\n### Infrastructure & processing\n\n- Improved staging worker deployment reliability when compute capacity is fully allocated.\n\n---\n\n## 0.10.20 (2026-07-12)\n\n### Platform (Studio)\n\n- Workflows: configure automatic retries from Studio at the workflow level or override them for individual HTTP GET/HEAD and Website Reader steps.\n\n### CLI\n\n- The bundled workflow reference now documents durable retry policies, inheritance, supported step types, and retry safety limits.\n\n### Infrastructure & processing\n\n- Workflow runs can recover replay-safe network steps from transient failures without restarting completed work, using bounded backoff and durable retry state. Retry behavior is now step-scoped. Legacy whole-run retry settings no longer restart a failed workflow; configure durable retries on eligible steps or through the workflow retry default instead.\n\n---\n\n## 0.10.19 (2026-07-09)\n\n### Platform (Studio)\n\n- Workflow composition is unified on `action.invoke-workflow`: use `execution: inline` (default) to run a target workflow's steps inside the parent run, or `execution: child` for a separate child run. Reusable blocks (`control.block`, `kind: block`) are removed — migrate to inline invoke with `workflow: &lt;name-or-id&gt;`.\n\n### Public API\n\n- Workflow run endpoints now preserve inline invoke snapshots across initial runs, reruns, and dataset executions so composed workflows remain reproducible after target workflows change.\n\n### CLI\n\n- Workflow YAML reference docs now describe `action.invoke-workflow` as the single composition primitive, including inline and child execution modes.\n\n---\n\n## 0.10.18 (2026-07-08)\n\n### Infrastructure & processing\n\n- On-prem deployments: improve OpenShift compatibility so migration and processing jobs can start reliably under random-user security policies.\n\n---\n\n## 0.10.17 (2026-07-08)\n\n### Platform (Studio)\n\n- Document parser: vision parsing can now render PDF pages at higher resolution and image quality for documents where small text or compression artifacts hurt OCR accuracy.\n\n### Infrastructure & processing\n\n- Document parser: vision parsing can now render PDF pages at higher resolution and image quality for documents where small text or compression artifacts hurt OCR accuracy.\n\n---\n\n## 0.10.16 (2026-07-07)\n\n### Platform (Studio)\n\n- Workflow experiment results now preserve evaluator error details alongside each per-evaluator score, so example grading views and tools can distinguish failed judges from unknown results instead of treating them as passing.\n\n### CLI\n\n- `eigenpal run &lt;workflow&gt; --example &lt;name&gt;` now actually grades the example instead of printing `PASS` whenever the run merely finished. It runs the workflow's current published version on the server's stored dataset example, so configured evaluators run automatically and the CLI surfaces the real weighted score and per-evaluator pass/fail. Workflows with no evaluators fall back to a structural diff of the output against the example's stored expected output. The summary reports two separate signals: execution health (`ok`/`errored`) and accuracy. Add `--fail-on-mismatch` to exit non-zero when a graded example fails. Because the run uses the server-side example, push your latest dataset and evaluators (`eigenpal workflow dataset push`, `eigenpal workflow evaluators push`) before running `--example`.\n\n---\n\n## 0.10.15 (2026-07-06)\n\n### Platform (Studio)\n\n- Experiments: make result review easier in Studio with trace exports, clickable score bars, calmer live refreshes, developer-view defaults, and clearer separation between below-threshold results and run errors.\n\n### Public API\n\n- Experiment export endpoints now support JSON exports with full run trace details for deeper debugging and audit review.\n\n### SDK\n\n- SDK clients now expose the trace-inclusive experiment export option for deeper debugging and audit review.\n\n---\n\n## 0.10.14 (2026-07-06)\n\n### Platform (Studio)\n\n- Evaluations: expected workflow failures now report cleaner scores when a run is supposed to stop early. Studio marks non-applicable quality judges as skipped, so successful rejection examples can receive a full score from the structured failure checks that actually apply.\n\n---\n\n## 0.10.13 (2026-07-06)\n\n- Internal improvements.\n\n---\n\n## 0.10.12 (2026-07-06)\n\n- Internal improvements.\n\n---\n\n## 0.10.11 (2026-07-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.10 (2026-07-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.9 (2026-07-02)\n\n### Platform (Studio)\n\n- Build document-processing workflows that split, route, and verify a mixed batch: - **Document separation** detects the boundaries and types of the documents inside one large scan, so a single upload can be broken into its individual documents and each sent to its own extraction pipeline — even for batches hundreds of pages long. - **Multi-way routing** sends each detected document to the right branch by its type, and stays readable on the canvas even with many branches. - **Grounded extraction** attaches a confidence level and source location to each extracted field, flagging values that aren't found verbatim in the document so reviewers know where to look. - The run view now lets you open the detected documents and preview their pages, and inspect the OCR layout with bounding boxes drawn over the page (with a toggle to the extracted text) — right from the step timeline.\n\n### CLI\n\n- The workflow step catalog now lists the new document-separation and multi-way routing steps, plus the grounded-extraction options, so authoring and validating workflows from the CLI stays in step with what the platform supports.\n\n### Infrastructure & processing\n\n- Self-hosted (on-prem) deployments can now run official EigenPal release images, with access provisioned per customer. Images are published only after a release ships and are signed so you can verify their authenticity before deploying.\n\n---\n\n## 0.10.8 (2026-07-01)\n\n### Platform (Studio)\n\n- Single-file workflow inputs now display correctly after a dataset import. Previously an input that takes one file could show an empty file slot; imported examples now match each file to the workflow's declared input shape.\n- Evaluator scoring now uses a single pass threshold for the whole workflow. The score-by-example chart's cutoff line and every evaluator's pass/fail are measured against that one threshold, so the chart, the per-evaluator results, and the run gate always agree. Experiment scores are shown in two states — passing (green) or below threshold (amber).\n- The LLM judge evaluator now requires evaluation criteria. Without them the model invents its own scoring rubric, so the editor marks the field required, renames it to \"Evaluation criteria\" with a worked example, and blocks saving until it is filled in.\n- Workflow folders can now be reorganized. A new \"Move to folder\" action in each folder's menu lets you move a folder (and everything inside it) into another folder or back to the top level, so you can restructure your workspace without recreating folders. Destinations that would nest a folder inside itself are blocked, with a tooltip explaining why.\n- Nested sub-workflows now display and resolve correctly across runs, the workflow builder, and the CLI. In the Runs list, a run that invokes a sub-workflow which itself invokes another sub-workflow now nests every level under its parent, instead of stopping at the first level. In the workflow builder, an \"Invoke Workflow\" step that targets a workflow built from other invoked workflows now shows the real output field types instead of \"unknown\", so you can reference those fields with autocomplete; referencing one of those fields no longer triggers a false \"field not found\" warning. The same resolution now applies when validating and publishing workflows (including via the CLI), so deeply nested invoke chains validate against their real output fields. All of this resolves through arbitrarily deep chains with a safety limit that prevents looping on workflows that invoke each other.\n- Runs: add a simplified review mode with developer-view toggle, review status badges, and inline output review for JSON fields and generated files.\n- New debugging and control primitives for runs. You can now cancel an in-progress run through the API, experiment results report when a batch has fully finished, steps skipped by a condition or an empty loop are reported as skipped rather than succeeded, and each step records the exact configuration it ran with so failures are easier to diagnose.\n- Run detail responses are leaner and more explicit: you choose exactly which sections to expand, and the public run schema now exposes the workflow version, cancellation-request time, and trace, retry, and email-trigger details.\n\n### CLI\n\n- `eigenpal workflow validate` now tells you when a workflow contains Invoke Workflow steps that local validation cannot fully check. Because those steps reference other workflows that live on the server, the command prints a short note pointing you to `validate --online` (or push) to verify the invoke targets, input types, and cycles. The skill guidance now shows the `--online` step in the validate-then-push flow as well.\n- The evaluator configuration reference now reflects the single workflow-level pass threshold. A per-evaluator `passThreshold` is documented as legacy — pass/fail is decided by the one workflow-level threshold — and that workflow-level threshold no longer shows a fixed default, since it is derived when omitted.\n\n### SDK\n\n- The Python SDK now requires Python 3.10 or newer. Python 3.9 has reached the end of its support window, and dropping it keeps the SDK on current, actively maintained dependencies. If you are still on Python 3.9, upgrade to 3.10+ to continue receiving SDK updates.\n\n[View full release notes →](/releases/0.10.8)\n\n---\n\n## 0.10.7 (2026-06-30)\n\n### Platform (Studio)\n\n- Faster dashboard navigation. Lists keep their contents on screen while filters and folders refresh instead of flashing a loading state, document and image previews are cached so they no longer re-download on every navigation, and heavy viewers (PDF, charts, rich text) load on demand for a quicker first paint.\n- Workflows that invoke another workflow now pass file inputs through to the sub-workflow, so file-backed sub-workflow runs no longer fail before they start.\n\n### CLI\n\n- `eigenpal --help` now groups `run`, `rerun`, and `runs` under a dedicated \"Run\" section instead of the catch-all \"Other\" bucket, so starting a run and reading its output is easy to find.\n\n---\n\n## 0.10.6 (2026-06-30)\n\nThis release contains maintenance and reliability improvements with no customer-facing changes.\n\n---\n\n## 0.10.5 (2026-06-29)\n\nThis release makes EigenPal's public changelog a reliable product record. Each release now has a dedicated docs page that explains what changed for Studio, the public API, the CLI, SDKs, and document processing in one place.\n\nThat means teams can follow platform improvements without piecing together GitHub activity or package-specific notes. The changelog is organized around customer-facing product areas, so it is easier to see which changes affect app users, API integrations, developer tools, and processing behavior.\n\n### Platform (Studio)\n\n- Invoke Workflow steps are now typed end to end. Pick a target workflow and map each input it declares to a value, then reference the workflow's output fields and any files it generates from downstream steps with autocomplete. Inputs and outputs are checked when you save and when the step runs, so mismatches surface early instead of failing mid-run.\n- Runs that invoke another workflow now appear nested under their parent run in both the runs feed and the run timeline, and link straight to the sub-workflow's own run and trace.\n- You can view a workflow's inferred output schema (the fields and files it returns, typed from its own steps) without running it.\n- File inputs are preserved consistently across runs, reruns, reviewed examples, and dataset experiments, so reused runs and examples no longer lose or mispoint their files.\n- Creating new organizations and other Git-backed source operations stay reliable even during Git provider outages.\n\n### Public API\n\n- Run file inputs now use a consistent artifact model. Callers provide reusable files with `$fileId` or inline files with `$inline`, and EigenPal materializes them into run-owned artifacts before execution, reruns, promotion, and dataset workflows.\n- A new endpoint returns a workflow's inferred output schema without running it, as JSON Schema or as a TypeScript or Python type.\n\n### CLI\n\n- `eigenpal workflow schema <workflow>` prints a workflow's inferred output schema as JSON Schema, or as a TypeScript or Python type with `--format`.\n\n[View full release notes →](/releases/0.10.5)\n\n---\n\n## 0.10.4 (2026-06-25)\n\n### Platform (Studio)\n\n- Unify file list review surfaces\n\n---\n\n## 0.10.3 (2026-06-24)\n\n### SDK\n\n#### Patch Changes\n\n- e48cb81: Remove `fileVerdict` from run review correction types; file correction intent is encoded via `correctedArtifactPath`.\n\n---\n\n## 0.10.2 (2026-06-24)\n\n### CLI\n\n#### Patch Changes\n\n- Single-tenant workflow file inputs can reference a named external file source. The worker retrieves and stores each file before executing the workflow.\n\n---\n\n## 0.10.1 (2026-06-23)\n\n### Public API\n\n- Polish reviews pages and group API reference nav\n\n### Infrastructure & processing\n\n- Client-shareable deployment architecture PDFs\n\n---\n\n## 0.10.0 (2026-06-23)\n\n### Platform (Studio)\n\n- Add simple runs review mode\n\n### Infrastructure & processing\n\n- Autogenerate chart architecture diagram from helm template\n- AWS/GCP/Azure Terraform examples with architecture diagrams\n- Helm chart + local kind for single-tenant on-prem\n\n---\n\n## 0.9.0 (2026-06-22)\n\n### CLI\n\n#### Minor Changes\n\n- c35d5d4: Clean up the public runs and evaluation API surface: move workflow eval operations onto automations, expose run scores/artifacts through the unified runs API, and update CLI/SDK helpers to use the canonical routes.\n\n Breaking: `runs.evalResults` and `GET /api/v1/runs/\\{id}/eval-results` are replaced by `runs.scores` and `GET /api/v1/runs/\\{id}/scores`.\n\n#### Patch Changes\n\n- c35d5d4: Clarify `--max-wait` help text so timeout exit behavior reads naturally.\n\n### SDK\n\n#### Minor Changes\n\n- c35d5d4: Clean up the public runs and evaluation API surface: move workflow eval operations onto automations, expose run scores/artifacts through the unified runs API, and update CLI/SDK helpers to use the canonical routes.\n\n Breaking: `runs.evalResults` and `GET /api/v1/runs/\\{id}/eval-results` are replaced by `runs.scores` and `GET /api/v1/runs/\\{id}/scores`.\n\n[View full release notes →](/releases/0.9.0)\n\n---\n\n## 0.8.0 (2026-06-18)\n\n### CLI\n\n#### Minor Changes\n\n- d620a00: Expose the clean public automation API around automations, runs, files/artifacts, datasets, evaluators, experiments, evaluation results, and run promotion. This intentionally breaks the pre-v1 SDK/CLI surface that exposed workflow- and agent-specific top-level resources outside the explicit legacy compatibility routes.\n\n > [!WARNING]\n > **Breaking change (pre-v1).** The workflow- and agent-specific top-level\n > resources have been removed in favor of a single automation-centric surface.\n > These packages are still 0.x, so this breaking redesign ships as a `minor`\n > bump. Update your integration before upgrading.\n\n #### Removed\n - Top-level workflow resources, e.g. `client.workflows.*`, including\n `client.workflows.executions.runAndWait(...)` and the rest of the\n `client.workflows.executions.*` tree.\n - Top-level agent resources, e.g. `client.agents.*` (runs, reviews, traces,\n files, expected artifacts).\n - Top-level source/git resources, e.g. `client.sources.*`.\n\n[View full release notes →](/releases/0.8.0)\n\n---\n\n## 0.7.2 (2026-06-13)\n\n### SDK\n\n#### Minor Changes\n\n- c5a709c: Public workflow list/detail responses include `apiEnabled` and `triggers`; run definition docs note workflow-only scope.\n\n---\n\n## 0.7.1 (2026-06-13)\n\n### SDK\n\n#### Patch Changes\n\n- 9db3f01: Expose `apiEnabled` and `triggers` on `AgentSummary` for runtime trigger projection.\n\n---\n\n## 0.7.0 (2026-06-12)\n\n### CLI\n\n#### Minor Changes\n\n- 963fd6c: Unify run detail on `GET /api/v1/runs/\\{id}`: return the canonical Run object directly (no `\\{ run: ... }` envelope) and merge expanded fields in-place via documented `expand` tokens. Remove the session-only `expand=internal` dashboard escape hatch; SDKs and CLI now use explicit expand lists.\n\n#### Patch Changes\n\n- 963fd6c: Update runs commands for the grouped run API shape and four expand tokens.\n\n### SDK\n\n#### Minor Changes\n\n- 963fd6c: Unify run detail on `GET /api/v1/runs/\\{id}`: return the canonical Run object directly (no `\\{ run: ... }` envelope) and merge expanded fields in-place via documented `expand` tokens. Remove the session-only `expand=internal` dashboard escape hatch; SDKs and CLI now use explicit expand lists.\n\n#### Patch Changes\n\n- 12c00d8: Docs: clearer wording in the file-input and TypeScript-runtime sections. No API or behavior changes.\n\n---\n\n## 0.6.17 (2026-06-12)\n\n### SDK\n\n#### Patch Changes\n\n- 716c3cf: Update the hosted default API base URL and API-key guidance from `app.eigenpal.com` to `studio.eigenpal.com`.\n\n---\n\n## 0.6.16 (2026-06-12)\n\n### CLI\n\n#### Patch Changes\n\n- 75dd64c: Internal refactor: move the skill tool registry into its own module so other tooling can import it. No change to any command, flag, argument, or output.\n\n---\n\n## 0.6.15 (2026-06-10)\n\n### CLI\n\n#### Minor Changes\n\n- ca87265: Unify workflow and agent run starts behind the canonical `/api/v1/run/\\{target}` endpoint, root `eigenpal run` / `eigenpal rerun` commands, and root SDK `client.run()` / `client.rerun()` methods.\n\n The old nested CLI commands and SDK resource methods for starting workflow or agent runs have been removed.\n\n#### Patch Changes\n\n- 5ea0bb5: `workflow dataset pull` gains `--example-id &lt;id&gt;` (repeatable) to export a single example or a selected subset of a dataset, instead of always pulling the whole dataset. The subset ZIP uses the same archive layout as a full pull, so it re-imports into any dataset via `dataset push --mode append`. Requesting an example id that does not exist for the workflow exits non-zero.\n\n### SDK\n\n#### Minor Changes\n\n- ca87265: Unify workflow and agent run starts behind the canonical `/api/v1/run/\\{target}` endpoint, root `eigenpal run` / `eigenpal rerun` commands, and root SDK `client.run()` / `client.rerun()` methods.\n\n The old nested CLI commands and SDK resource methods for starting workflow or agent runs have been removed.\n\n---\n\n## 0.6.10 (2026-06-08)\n\n### CLI\n\n#### Patch Changes\n\n- 99ca1b4: Unify agent and workflow run commands and SDK helpers on the shared `/api/v1/runs` API, including the public `client.runs` facade and regenerated SDK reference docs.\n\n### SDK\n\n#### Patch Changes\n\n- 99ca1b4: Unify agent and workflow run commands and SDK helpers on the shared `/api/v1/runs` API, including the public `client.runs` facade and regenerated SDK reference docs.\n\n---\n\n## 0.6.9 (2026-06-04)\n\n### SDK\n\n#### Minor Changes\n\n- 5e7c051: Add `observability` (phase timeline + structured failure) to workflow execution and agent run status API responses.\n\n---\n\n## 0.6.6 (2026-06-03)\n\n### CLI\n\n#### Patch Changes\n\n- 245f347: Clean up the agent CLI surface by removing obsolete compatibility commands, moving reruns to `agents rerun`, and replacing run pulls with canonical artifact fetching.\n- 5ab00ee: Tighten permissions on `~/.config/eigenpal/credentials.json` and its parent directory to owner-only (0600 / 0700). Previously the file was written 0600 but the parent directory inherited the user's umask (typically 0755), allowing other local users to list the directory and stat the file. The CLI now also re-tightens permissions on every write, so installs created with older versions are corrected on the next `auth login` / `auth use`.\n\n---\n\n## 0.6.4 (2026-06-03)\n\n### CLI\n\n#### Patch Changes\n\n- c3486a5: Fix agent git cutover QA findings: dashboard runs now navigate to the created run, inbound email aliases preserve mixed-case organization qualifiers, sandbox source materializes under `/workspace/agent`, run artifact downloads use direct paths like `/files/eigenpal.lock`, wait-for-completion responses include source provenance, and CLI wait/watch commands exit nonzero for failed or cancelled runs.\n\n### SDK\n\n#### Patch Changes\n\n- c3486a5: Fix agent git cutover QA findings: dashboard runs now navigate to the created run, inbound email aliases preserve mixed-case organization qualifiers, sandbox source materializes under `/workspace/agent`, run artifact downloads use direct paths like `/files/eigenpal.lock`, wait-for-completion responses include source provenance, and CLI wait/watch commands exit nonzero for failed or cancelled runs.\n\n---\n\n## 0.6.2 (2026-06-02)\n\n### CLI\n\n#### Patch Changes\n\n- d2202b6: List all agent runs for unqualified targets, and reserve source-ref filtering for explicit `@ref` targets.\n\n---\n\n## 0.6.0 (2026-06-02)\n\n### CLI\n\n#### Minor Changes\n\n- 2aeeaf2: Add native source `git save` and branch-aware `git release` flows for Git-backed builder workspaces.\n\n#### Patch Changes\n\n- 2aeeaf2: Complete the agent Git cutover with pluralized agent CLI commands, source-ref run support, lockfile metadata, and regenerated SDK/docs surfaces.\n- 2aeeaf2: Expose Git-backed agent source refs and public source automation APIs consistently across CLI docs and SDK facades.\n\n### SDK\n\n#### Patch Changes\n\n- 2aeeaf2: Complete the agent Git cutover with pluralized agent CLI commands, source-ref run support, lockfile metadata, and regenerated SDK/docs surfaces.\n- 2aeeaf2: Expose Git-backed agent source refs and public source automation APIs consistently across CLI docs and SDK facades.\n\n---\n\n## 0.5.12 (2026-06-02)\n\n### CLI\n\n#### Minor Changes\n\n- d3b0768: Add `control.fail` and `ai.classify` step types, plus the `expected/error.json` dataset assertion format.\n - `control.fail` terminates a workflow with a typed status code + message envelope. Optional `condition` template gates the fail. Compose with `ai.classify` to reject documents that match an undesired label.\n - `ai.classify` runs single-label closed-set classification through the existing extract LLM pipeline. Output is `\\{ label, confidence, reason }`, where `label` is constrained to the configured names.\n - `examples/&lt;name&gt;/expected/error.json` (mutually exclusive with `output.json`) lets eval examples assert that a workflow should fail with a specific `\\{ code, messageContains, step }`. The exact-diff evaluator scores 1 on match, 0 otherwise.\n - `eigenpal workflow validate` now catches `expected/error.json` shape issues and per-step config violations (e.g. `ai.classify` with fewer than two labels) at push time instead of deferring to runtime.\n\n Skill reference docs (`step-types.md`, `dataset-format.md`, `evaluators.md`, `workflow-yaml.md`) updated.\n\n#### Patch Changes\n\n- 99cad97: Skill reference (auto-generated from `WorkflowDefinitionSchema`) now documents the new `values` row for enum inputs, alongside the existing `items` row used by array inputs. Output-only doc refresh — no CLI behavior change.\n- d70f697: Document the `control.parallel`, `control.parallel_map`, `control.foreach`, `control.if`, and `control.block` step types in the bundled skill reference. The auto-generated catalog cannot render nested step shapes, so the YAML form, output access paths (e.g. `steps.&lt;parallel&gt;.output.&lt;branch&gt;.&lt;inner&gt;.&lt;field&gt;`), and scoping rules now live as hand-written prose. Also documents the multi-step iteration hazard: only the LAST inner step's output is keyed into each `items[i]` for `parallel_map` / `foreach` — end the body with a `transform.script` if you need to preserve intermediate fields.\n- ed2cde6: Fix `eigenpal workflow pull` writing a 0-byte file. The v1 single-workflow endpoint now returns the current YAML at the top level (`yamlContent`) via a new `WorkflowDetail` response shape, and the CLI throws a clear error instead of silently writing empty output when no version has been published. Also fixes adjacent regressions caused by the same picker: `workflow list` now shows the workflow name and version columns (previously always `-`), `workflow push --bump` reads the server's current version correctly, the \"did you mean?\" suggestion on a slug typo lists candidates again, and `workflow execution list` shows a duration column computed from the run start/end timestamps.\n\n---\n\n## 0.5.11 (2026-05-26)\n\n### CLI\n\n#### Patch Changes\n\n- 2958f4d: Fix Git-backed source smoke-test polish: hidden `git show` and `git sync` now accept bare agent slugs, and workflow scaffolds use the current `triggerMethods` YAML shape.\n\n---\n\n## 0.5.10 (2026-05-26)\n\n### CLI\n\n#### Patch Changes\n\n- aee7e0c: Add hidden Git source commands for editing trigger policy and encrypted secrets.\n\n---\n\n## 0.5.9 (2026-05-26)\n\n### CLI\n\n#### Major Changes\n\n- fadb59b: CLI command tree reorganized around the data model. Top-level surface is now\n `workflow`, `agent` (reserved), and `skill`; everything that operates on a\n workflow lives under `workflow`, grouped by sub-entity.\n\n Renames (clean break — no aliases):\n - `eigenpal exec &lt;slug&gt;` → `eigenpal workflow execution run &lt;slug&gt;`\n - `eigenpal clear` → `eigenpal workflow clear`\n - `eigenpal install-skill` → `eigenpal skill` (same interactive multiselect UX)\n - `eigenpal execution \\{get,list,watch,compare}` → `eigenpal workflow execution \\{…}`\n - `eigenpal workflow set-definition` → `eigenpal workflow push`\n - `eigenpal workflow get-definition` → `eigenpal workflow pull`\n - `eigenpal workflow set-evaluators` / `get-evaluators` → `workflow evaluators \\{push,pull}`\n - `eigenpal workflow set-dataset` / `get-dataset` / `list-examples` → `workflow dataset \\{push,pull,list}`\n - `eigenpal workflow run-experiment` / `get-experiment-status` / `get-experiment-results` /\n `get-eval-results` / `list-executions` → `workflow experiment \\{run,status,results,eval-results,list}`\n - `eigenpal workflow list-versions` / `restore-version` → `workflow version \\{list,restore}`\n\n[View full release notes →](/releases/0.5.9)\n\n{/* GENERATED:CHANGELOG_INDEX END */}\n"
23
+ "content": "---\ntitle: Changelog\ndescription: Production release history for the EigenPal platform.\n---\n\nEigenPal ships on a unified platform version. Each production release updates Studio, the public API, infrastructure, and (when applicable) the CLI and SDKs together.\n\n{/* GENERATED:CHANGELOG_INDEX START */}\n\n## 0.23.6 (2026-11-10)\n\n### CLI\n\n- Bundled self-hosting documentation explains every Helm value and environment variable.\n\n---\n\n## 0.23.5 (2026-11-10)\n\n- Internal improvements.\n\n---\n\n## 0.23.4 (2026-11-10)\n\n### Platform (Studio)\n\n- The Document layout view on a run now works for Word and PowerPoint files (and other paginated office formats such as RTF, ODT and ODP). It shows each page as it was laid out during parsing, with a box around every word that lines up with the page. Parse steps on these files now also report word coordinates, so `ai.parse-v2` steps that require them succeed for office inputs. Runs processed before this update show a note instead of a preview.\n- PowerPoint decks (.pptx) now open in the built-in file preview, in dataset review and in human review, with slide thumbnails for navigation, instead of showing \"Preview not available\". Charts on slides render too (bar, column, line, area, pie, doughnut, scatter and radar), along with shape effects such as glow, reflection and 3-D. Word document previews also pick up the latest rendering improvements.\n- Review tasks no longer tell owners and admins that their role is read-only while the page is still loading; the page waits until your role is known. The workflow Editor and Evals switch now always highlights the view you are looking at.\n\n### Public API\n\n- `GET /api/v1/automations/\\{id}/experiments/\\{experimentId}` reports the experiment as `running` until every finished run has its evaluator verdict, and its passed, failed, errored, pending and ungraded counts always add up to the run count. A run still without a verdict 15 minutes after it ends counts as ungraded and is left out of the pass rate, so a stuck run cannot hold an experiment open.\n\n### CLI\n\n- The CLI now retries rate-limited requests a few times, waiting as long as the server asks, and reports a request that is still rate limited as a rate limit with how long to wait, instead of as a validation failure.\n- `eigenpal workflow step-type get &lt;type&gt;` now accepts `--json`, like the other commands. Its output was already JSON.\n- `eigenpal workflow push --json` now prints the same shape on create and update, `\\{ id, name, version, versionId, created }`, so `jq -r .id` always gives the workflow id. `eigenpal workflow list` shows each workflow's name and version again, and its `--json` rows include `name`, `description` and `version`. New `eigenpal workflow get &lt;id-or-slug&gt;` shows one workflow's name, version, folder and your access, with `--json` for the full record. `workflow push --bump` now reads the current version correctly.\n- `eigenpal workflow experiment run --wait` now returns only after every run has finished and been graded, so its pass rate matches `workflow experiment results`. Previously it could return while the last runs were still being scored and report a pass rate that was too low.\n- The bundled step reference in `eigenpal docs` now covers OCR word confidence in extraction grounding and the `lineageFrom` option on human review.\n\n### Infrastructure & processing\n\n[View full release notes →](/releases/0.23.4)\n\n---\n\n## 0.23.3 (2026-11-10)\n\n### Platform (Studio)\n\n- Add Claude Fable 5.2 for workflow steps, structured extraction, vision, judges and agents, with every reasoning effort level from low to max. It costs less per token than Fable 5.1 and replaces it as the recommended Fable model. Existing default model selections and workflows that name Fable 5.1 stay unchanged.\n\n### CLI\n\n- The bundled self-hosting docs in `eigenpal docs` now describe the install preflight check and how to run it on its own.\n\n### Infrastructure & processing\n\n- Self-hosted installs now run a read-only preflight check before migrations. It confirms that every Secret value is present, that CA bundles and client certificates are valid (with an optional expected certificate name), and that the database, object storage, model gateway, OCR, sign-in and file source services are reachable over TLS. It prints one result per check with a fix for each failure, never prints a secret value, and stops an install or Argo CD sync before anything changes. It can also be run on its own the day before an install.\n\n---\n\n## 0.23.2 (2026-11-09)\n\n### Platform (Studio)\n\n- The Monitoring page now uses the searchable automation picker, which lists workflows and agents together, sorted by name and marked by icon. The same list now appears on the Trigger, Reviews and Connect pages. The rolling window control no longer cuts off its slider labels.\n\n---\n\n## 0.23.1 (2026-11-09)\n\n### Platform (Studio)\n\n- On self-hosted installs, the admin set by `EIGENPAL_ADMIN_EMAIL` is now always an owner. Changing that email used to create the new account as a plain member when the organization already had an owner. The previous owner keeps its role until someone removes it.\n- Every section on the Environments page now opens and closes from its header, which keeps its count. Sections that need someone (awaiting approval, needs attention, in progress) start open; Ready to promote and History start closed so a long list no longer pushes active releases down. Each person's choice is remembered in their browser. Links to a section, and filtering by a workflow, open the sections they point into.\n- The published OpenAPI document lists `tree` on the folder list route as `true` or `false`.\n- Environments: each workflow's environment panel now shows what an environment runs apart from the release on its way into it, with that release's version, its status and a link to its merge request. Only the environment the current release goes into shows it as under way; an older release still waiting elsewhere is named with its version. Statuses read the same in the panel, on the Environments page and in each environment's comment on the request (\"Ready to release, waiting for approval and a merge in Git\"), and amber now only marks what needs a look. The panel's release list also includes releases still on their way, so a version live in some environments no longer disappears from it.\n- Buttons and form controls use consistent heights and corners across Studio, making actions easier to scan and use together.\n\n### Public API\n\n- `GET /api/v1/folders` now rejects a `tree` value other than `true` or `false` with a 400. Any other value used to be silently treated as `false`.\n\n### SDK\n\n- `folders.list` types `tree` as `'true' | 'false'` to match the API, which now rejects any other value.\n\n---\n\n## 0.23.0 (2026-11-06)\n\n### Platform (Studio)\n\n- Anyone with Editor access can again move a workflow or folder out of an open top-level folder. Moving something out of a private top-level folder still needs Manager access on that folder.\n- Share any folder or workflow inside a folder with more people, as narrowly as needed: a grant on one workflow opens just that workflow (with its runs, files and reviews), and a grant on a subfolder opens just that subfolder. Grants only add to what an item inherits; only top-level folders and workflows can be private, and inside a folder a grant goes up to Editor and is for named people and groups. Folders around a shared item stay hidden: people find it under **Shared with you**, and the path above shows as \"Private folder\". The access panel of an item inside a folder shows what it inherits, naming the folder each grant comes from, and lets you add people under **Also shared with**. Moves keep an item's own grants and show, person by person, who gains, loses or drops a level before you confirm. Check access says where a grant is set.\n- **Breaking (promotion config):** workflow promotion is configured with `promotion.repositories`, and the previous shape no longer loads. Declare each Git repository once by a short name (`project`, `branch`, optional `provider` and `apiUrl`), give every environment the `repository` it is kept in and the `bot` it writes as there (required, and unique per environment), use `acceptsFrom` where the environment before writes from another repository, and `releasedWith: &lt;env&gt;` for an environment released by the same request as the one before it. Each installation holds one token per repository, `secrets.promotionTokens.&lt;repository&gt;` in Helm (`repositories.&lt;name&gt;.token` in the app config), with the same keys in every installation. `promotion.git`, `environments[].git`, `gitIdentity`, `requestsFrom`, `withPrevious`, `approvers`, `secrets.promotionToken` and `secrets.promotionAppKey` are removed: a config that still uses them fails at startup and in `helm template` with how to migrate it. Releases can cross into a Git repository another team owns. The environment before opens the release there with its token for that repository, carrying the version's files, its rollout and its Git LFS dataset files. Several environments can be released by one request: each checks it, reports its own status, and all of them go live once it merges. An environment whose token may not merge into its branch, such as a GitLab Developer on a branch only Maintainers merge, never tries: it reports its status and goes live once someone merges it in Git. Every installation shows the status of every environment it holds a read token for; without one, those environments show as not visible from here. The setup check lists every repository with the token used, the user it writes as, and whether its rights match what the installation needs there: write in its own repository and the next environment's, read elsewhere. The promotion webhook takes one secret per installation (Helm default: Secret `eigenpal-promotion`, key `webhook-secret`, next to the token keys) and matches each event to its repository by project path.\n- Workflow cards no longer overflow: long names wrap at underscores and dashes, the version and API badges sit on their own line, and the step dots are replaced by a step count. The workflow menu uses the newer dropdown with grouped actions, a Connect (API) link, and copyable workflow ID and API target. In the editor, workflow settings (General, Model, Retries, Triggers, Variables, Access) sit in a floating bar at the top right of the canvas that expands into the side panel, the Access icon shows whether the workflow is private, shared or open to everyone, and the header keeps only Run, Save / Save version and the actions menu. Everything clickable shows a pointer. Config-defined file sources show a lock and explain that they are edited in the deployment configuration.\n\n### Public API\n\n- `GET /api/v1/automations` and `GET /api/v1/automations/:id` no longer name folders the caller cannot open. For a workflow shared with you inside such a folder, `folderId` is `null`, and `folderPath` is `null` whenever any folder on the path is hidden from you.\n\n---\n\n## 0.22.8 (2026-11-06)\n\n### Platform (Studio)\n\n- Reviewers can work their human review queue again: opening, editing, approving and rejecting review tasks no longer needs workflow permissions, which the Reviewer role does not have. Viewers see review tasks read-only, without Approve, Reject or field edits the API would refuse, and roles that cannot cancel runs no longer see Cancel on a review. Organization-level role checks now come from one capability map shared by the API and the dashboard (`requireCapability` and `useCan`), so settings, members, invites, service accounts, billing, promotion and webhook controls show exactly what the API allows. Admins can no longer sign out another admin or an owner everywhere; owners can sign out anyone, and anyone can sign themselves out. Dataset reviews are read-only for viewers, matching the API. `/api/v1/files` answers 404 for files of workflows you cannot open and needs editor access to delete them. In OpenParser Studio, receipts and payment methods are for owners and admins, while members can still add funds.\n- Dataset example files whose names contain spaces, accents or parentheses open, download, rename and delete again from the examples list and from dataset reviews. Before, their preview showed \"Failed to fetch file: 400 Bad Request\" (and dataset reviews showed the file as missing), even though running the example worked.\n- Let owners and admins delete the Studio copy of a file source that the deployment configuration overrides from its detail panel, not only from the row menu. Deleting a name that only the deployment configuration defines now answers 409 instead of reporting success, an unknown name answers 404, and the delete dialog shows the server's reason when a delete fails.\n- Organization admins can set a monthly spend cap for Pro pay-as-you-go usage. Track the remaining cap in Settings and stop extra charges at your chosen limit.\n\n### Public API\n\n- Example and dataset review file endpoints under `/api/v1/automations/:id` now serve, rename, delete and upload files whose names contain spaces, accents or parentheses, instead of answering 400 or 404.\n\n---\n\n## 0.22.7 (2026-11-05)\n\n- Internal improvements.\n\n---\n\n## 0.22.6 (2026-11-05)\n\n### Platform (Studio)\n\n- Group promotion dataset comparisons into expandable examples with change indicators. Keep comparison tabs and icon controls for diff layout and line wrapping in the fixed sheet header, and remove redundant explanatory text. Show existing environment variables as compact resolved rows and protect global and shared values from accidental edits. Existing secrets remain hidden and need no replacement. Automatically connect a released workflow to an existing variable used by its declared sharing partners, while keeping unrelated variables separate and preserving existing values.\n- Show first workflow releases awaiting checks or approval in the receiving environment, even before that workflow first goes live. Keep open request reports, counts, and links consistent across release views.\n- Fix releases held for missing settings: a request names everything that is still missing and why a file source that exists cannot be used (turned off or invalid), and it is checked again on every pull as the list changes. A held older version no longer hides the release form for a newer one, and the release button names the next environment.\n- Show a release request that a newer version replaced as \"Superseded by vX\" and one closed without merging as \"Cancelled\", stop reporting its stopped checks as failed, list each release only under In progress or in the History, and link running checks to their live evaluation. Improve environment and promotion navigation on desktop and narrow screens, distinguish saved versions from promotions, compare the complete release package, and connect release checks to their batch and run evidence. Surface blocked incoming releases with recovery links, preserve historical live-version context, and clarify Git-managed configuration, status refresh failures and approval requirements. Explain release-check failures directly in run details with recorded evaluator mismatches and expected versus actual JSON from the immutable release snapshot. Keep trigger labels consistent and evaluation requirements readable on narrow screens. Unify release rows around aligned environment pipelines, remove duplicate listings, and resolve missing variables or file sources directly from the release page. Recognize dashboard-managed file sources, retry failed checks without losing earlier runs or changing the release URL, and publish evaluation progress through durable completion notifications. Simplify the promotion sheet and open it directly from Environments. Treat valid enabled file source connections from deployment configuration and Studio equally, remove the redundant FILE_SOURCE_INTEGRATIONS switch, and show Config or Studio origin badges while keeping configuration entries read-only. Existing deployments can remove the obsolete switch. Compare workflow, dataset, evaluator and settings contents in tabbed Pierre views, including unchanged files, with inline or side-by-side diffs and a compact promotion form. Reuse existing environment variables safely without replacing concurrent workflow bindings, and keep release navigation unfiltered.\n\n### Public API\n\n- Run lists now show the workflow's name for release-check runs instead of an internal identifier.\n\n### CLI\n\n- Bundled self-hosting documentation describes the per-value Secret references and the optional External Secrets support of the Helm chart.\n\n### Infrastructure & processing\n\n- Self-hosted Helm installations name each secret value on its own: a Secret and a key per value, so credentials can be grouped into Secrets however your platform team prefers, or filled from Vault through the External Secrets Operator, which the chart can now configure. Storage location, owner email and other settings that are not secret move into plain chart values, and a missing value stops the install with a message naming it. Existing values files need the new keys; see the Helm values reference.\n\n---\n\n## 0.22.5 (2026-11-05)\n\n- Internal improvements.\n\n---\n\n## 0.22.4 (2026-11-04)\n\n### Platform (Studio)\n\n- Honor merged workflow releases even when checks fail, record overridden failures, and show queued checks accurately.\n\n### CLI\n\n- Bundled self-hosting documentation now covers OCI chart mirroring and Argo CD multi-source installations with environment values stored in Git.\n\n### Infrastructure & processing\n\n- Self-hosted installations can pull versioned Helm charts from an OCI registry, mirror them into an internal registry, pin app and worker images by digest, and use existing TLS certificate Secrets for OpenShift Routes.\n\n---\n\n## 0.22.3 (2026-11-04)\n\n### Platform (Studio)\n\n- Apply published per-request long-context credit rates to GPT-6 Astra, GPT-6.1 Sol and GPT-6 Luna. Above 272,000 input tokens including cache reads and writes, input/cache rates double and output rates increase by 50%. Existing ledger entries are unchanged.\n- Promotion fixes found in the first on-prem rollout: release checks work on self-managed GitLab versions that answer 500 to the merge request diffs endpoint with `per_page=100` (the file list is read at the endpoint's page size, falls back to comparing the two commits, and refuses to pass a cut-off list); a request that cannot be checked is shown on the Environments page instead of only in the log; admins get a \"Check now\" button; the Environments page marks the current environment and links to other environments' Environments page; the approval-rules note is advisory; the helm chart's cron jobs run from the worker image with Bun (no wget or utility image needed), and app and worker accept extra volumes.\n\n### Infrastructure & processing\n\n- Apply published per-request long-context credit rates to GPT-6 Astra, GPT-6.1 Sol and GPT-6 Luna. Above 272,000 input tokens including cache reads and writes, input/cache rates double and output rates increase by 50%. Existing ledger entries are unchanged.\n\n---\n\n## 0.22.2 (2026-11-03)\n\n### Platform (Studio)\n\n- Environments no longer record anything outside the pull or merge request that moves a version into them. The `eigenpal/reports` branch (GitLab) and the deployment reports (GitHub) are gone, and so is the inventory every environment published for the others. Each environment keeps one comment on the request, with the state of the release hidden in it for the first environment to read: how its checks went, where the release ended up, what it lacks. What each environment runs is its pin on the main branch. The release screen shows a held release with what is missing and links \"Define in T\" with the variable's type and sharing filled in. The Variables page no longer shows later environments (nothing about them is read ahead of a release). The next environment accepts a release request only from the previous environment's own Git identity, and `gitIdentity` is now the username a token writes as (a GitLab bot user, a GitHub login) rather than a commit email. The setup page checks that identity. GitHub credentials no longer need the Deployments permission.\n\n---\n\n## 0.22.1 (2026-11-03)\n\n### Platform (Studio)\n\n- Releasing workflows between environments can now keep each workflow's dataset files in the release repository with Git LFS, next to the workflow they belong to. Environments then need nothing beyond access to the repository: no shared bucket, no shared storage credentials, and dataset changes are reviewed in the same request as the workflow change. Set `promotion.artifactStore.git: true` (a shared bucket or directory remains available). What a release replaces in an environment is now kept in that environment's own storage instead of a shared one. A release lists the variables a workflow needs in its own `envVars` list, with their type and whether each is an organization variable, one of the workflow's own, or one shared with other workflows (so a higher environment can set it up the same way); environments no longer publish their file sources to each other, and an environment's setup page shows when it last checked Git. The release manifest restarts at format 1 and releases written by earlier builds are no longer read: release again after upgrading every environment.\n- Editing a variable that is shared by several workflows from the workflow editor no longer removes it from the other workflows, and taking a workflow off a variable now asks for confirmation first. The Workflow variables list on the Variables page can now be searched and filtered by workflow.\n- Choosing workflows for a variable (and any other long multi-select list) now has a search box, and the list scrolls instead of running off the screen.\n\n---\n\n## 0.22.0 (2026-11-03)\n\n#### Upgrading self-hosted installations\n\nThis release tightens the self-hosted deployment contract. Back up the database, object storage, repository volumes and persisted secrets, then render or start the new release with your existing configuration and fix each reported validation error.\n\n**Every installation**\n\n- Configure a model registry (`config.models` in Helm, `models:` in `eigenpal.config.yaml`). There is no default cloud model.\n- Agent builder storage mounts need a scoped credential issuer: `SANDBOX_STORAGE_STS_ROLE_ARN`, or `SANDBOX_STORAGE_R2_ACCOUNT_ID` with `SANDBOX_STORAGE_R2_API_TOKEN`. With static storage keys, the STS role must trust the IAM user that owns `S3_ACCESS_KEY`. Remove `SANDBOX_STORAGE_REQUIRE_SCOPED_CREDENTIALS`. The credential lifetime now defaults to 3600 seconds.\n- End existing builder sessions and rotate the storage credentials they received.\n- Remote sandboxes need matching random tokens of at least 32 characters in `SIDECAR_AUTH_TOKEN` and `SANDBOX_REMOTE_AUTH_TOKEN`, an upgraded sidecar with session leases, and `EIGENPAL_TENANT_MODE=single-tenant`.\n- Agents need a Git server (`AGENT_GIT_BASE_URL`). Set `EIGENPAL_AGENTS_ENABLED=false` where you do not operate one; it hides the Agents area, returns not found for agent API calls and refuses agent runs, and leaves workflows untouched. The default is true.\n- A missing file at `EIGENPAL_CONFIG_PATH` now stops startup.\n- The audit action `sandbox.unscoped_credentials_issued` is no longer emitted; retire alerts keyed on it.\n\n**Helm**\n\n- Install the versioned chart attached to the release; it defaults app and worker images to that release. `image.registry` defaults to the EigenPal registry; set your mirror or `''` for fully qualified repositories. `latest` image tags are rejected.\n- Set `secrets.cron.existingSecret` to a Secret holding `CRON_SECRET`, or set `maintenance.enabled: false` when your own scheduler calls housekeeping.\n- The chart does not install a Git server, so it now defaults `agents.enabled` to `false`. If you run agents against your own Git server, set `agents.enabled: true` and supply `AGENT_GIT_BASE_URL` and `AGENT_GIT_ADMIN_TOKEN` to app and worker through `extraEnv`.\n- Remove `worker.keda` and `sandboxStorage.requireScoped`. Unknown fields and duplicate environment variables fail validation.\n\n[View full release notes →](/releases/0.22.0)\n\n---\n\n## 0.21.0 (2026-11-02)\n\n### Platform (Studio)\n\n- Git-based environment management: run each of a customer's environments (named and ordered in Helm) as a separate installation and release workflows between them through a GitHub or GitLab repository that records which version runs where and who approved it. Each release opens a pull request (or merge request) per environment. That environment runs the workflow's checks on it, with the version's own dataset from Git and without touching what runs there, reports a commit status that approval rules can require, and keeps a comment on it up to date from \"Running checks\" to \"Live\". Both link to the release's Acceptance page, which shows every check and its result. The release goes live once the request is approved and merged. Triggers and the dataset travel with the version. Outbound webhook endpoints, their subscriptions, secrets and sharing stay local to each environment and are managed in the UI. Workflow access and groups stay local too: administrators configure each installation's folder and workflow sharing independently, directory-group membership comes from SSO, and EigenPal-defined groups keep local membership. New imported top-level folders and standalone workflows start private; updates preserve existing local access. Each environment supplies its own file-source connections. On GitHub and GitHub Enterprise Server, EigenPal can sign in as a GitHub App, so it comments and merges as a bot (`&lt;app&gt;[bot]`); on GitLab, a project or group access token does the same. After the first environment, workflows, their datasets and evaluators are read-only, with a link to edit them in the first. The Environments page shows what is in progress and the release history by workflow, and the release panel on each workflow links to it and lists its recent releases. A release that fails says why, naming the fields that did not match, and keeps saying so after a newer release replaces it. Repository notifications from GitHub or GitLab can start reconciliation promptly, with 15-minute fallback polling. Release intent is stored under `rollouts/`. Missing rollout intent or a closed promotion request shows why propagation has paused while preserving the version already live.\n- Service accounts: give each integration its own identity under **Settings → Service accounts**. A service account has a role and groups like a person but never signs in, and its calls appear in the audit log under its own name instead of the person who issued the key. Its keys keep working when that person leaves the organization. Create its keys from the service account or from **Developers → API keys**, with an expiry of up to a year or none.\n\n### Public API\n\n- In an installation whose workflows are released through Git-based environment management (every environment after the first), requests that change a workflow, its versions, evaluators or dataset answer 403 with a message naming the environment to make the change in. Reads and runs work as before; agents are not affected.\n\n### CLI\n\n- The CLI service account guide explains how to preserve key access during rotation and who can revoke admin service account keys.\n\n---\n\n## 0.20.99 (2026-10-29)\n\n### Platform (Studio)\n\n- OpenParser Studio opens faster: your organization is resolved on the server so pages no longer wait on a full-screen \"Loading organization\" step, switching organizations no longer reloads the page, and every page shows a skeleton of its layout while it loads. Billing, API keys and Organization arrive with their data already filled in.\n- Connect and workflow-specific OpenAPI and Swagger documentation list configured business rejections alongside successful results, technical failures, and cancellation. Each rejection includes its code, step, conditions, and message template. Resolvable subworkflow outcomes are included, and unresolved calls are marked explicitly. Business codes are documented inside HTTP 200 run responses. Contextual links make it easier to move between Connect, Swagger, workflow editors, selected subworkflows, and step documentation. Steps inheriting a retry policy can open the workflow's retry settings directly. Failed-run Output views and exports preserve the structured public error payload. Connect and scoped Swagger include individual standard processing failure examples and schemas and examples for documented HTTP request errors. Run-start OpenAPI declares conflict responses; rerun declares credit and conflict refusals so generated clients accept their documented envelopes.\n\n### Public API\n\n- Run errors include the configured business rejection code and step alongside a machine-readable failure code, message, and retryability. Read error.message instead of the previous string error. A successful API request can still report a failed run; business codes such as 422 are in error.statusCode, independently of the HTTP response status. The new Errors and recovery guide explains both kinds of outcome, available codes, and recovery behavior.\n- Connect and workflow-specific OpenAPI and Swagger documentation list configured business rejections alongside successful results, technical failures, and cancellation. Each rejection includes its code, step, conditions, and message template. Resolvable subworkflow outcomes are included, and unresolved calls are marked explicitly. Business codes are documented inside HTTP 200 run responses. Contextual links make it easier to move between Connect, Swagger, workflow editors, selected subworkflows, and step documentation. Steps inheriting a retry policy can open the workflow's retry settings directly. Failed-run Output views and exports preserve the structured public error payload. Connect and scoped Swagger include individual standard processing failure examples and schemas and examples for documented HTTP request errors. Run-start OpenAPI declares conflict responses; rerun declares credit and conflict refusals so generated clients accept their documented envelopes.\n\n### CLI\n\n- Run responses expose structured errors with a machine-readable code, message, retryability, and the configured business status code and step for workflow rejections. Update consumers of the previous string error to read error.message. HTTP success remains independent of the processing outcome.\n\n### SDK\n\n- Run responses expose structured errors with a machine-readable code, message, retryability, and the configured business status code and step for workflow rejections. Update consumers of the previous string error to read error.message. HTTP success remains independent of the processing outcome.\n\n---\n\n## 0.20.98 (2026-10-28)\n\n### Platform (Studio)\n\n- Workflow builder: a new Set Value step now starts with a field the step can run, filled from the step before it, instead of settings it ignored. A Merge step added after another step now merges that step's output instead of nothing, and the Merge docs list its `input` setting.\n- Summary agent reports: reviewer repairs are now applied before publication, the writer and reviewers work from a period-locked bank baseline read from the IBM workbook, the coverage reviewer checks every \"not available\" claim against the sources, and the writer spends part of its evidence pass on the narrative originals.\n\n---\n\n## 0.20.97 (2026-10-28)\n\n### Platform (Studio)\n\n- Workflow builder: the Add step menu is now a searchable picker with category tabs, keyboard navigation and a blurred backdrop. It suggests up to seven relevant next steps for each kind of step, including the first step of a workflow, and suggested loops and switches now come pre-filled from the step before them. Opening an Extract Data step no longer rewrites its schema (dropping settings such as fixed values) or marks the workflow unsaved, and undoing back to the saved version reads as saved again without a false \"Unsaved changes\" prompt. In Evals, the workflow name is shown read-only.\n- Security: fix sign-in vulnerabilities that could allow account takeover or bypass rate limits. On-prem OIDC administrators must register `/api/auth/callback/&lt;provider&gt;` with their identity provider before upgrading and restart pending sign-ins. Password sign-in and User Auth Service callback URLs are unchanged.\n- OpenParser Studio has a new Usage page: spend, pages and jobs by day for the last 7 days, 30 days or month to date, split into parsing and extraction, with a breakdown by model, pipeline and type. Each job in Jobs now shows what it cost, and a job's page breaks the charge down into parsing pages and extraction tokens.\n- Return the captured workflow version label and version ID in async run-start and rerun responses, including responses when a synchronous wait expires.\n- Workflow builder: the Extract Data and Inspect Pages schema editors now follow undo and redo instead of showing the previous fields, and editing a schema keeps enums exactly as written (numeric values stay numbers). Reverting an edit by hand reads as saved again, and the first step inside a loop or branch no longer suggests start-of-workflow steps.\n- Summary Agent: report runs no longer stop for recoverable reasons that needed a manual Continue. - A report writer no longer pauses with \"Context compaction did not complete\" when a background context summary fails while its history still fits, and it no longer summarizes away a draft it is correcting inside its save reserve. - A reviewer whose final reply comes back empty retries once within its allowance instead of pausing. - Re-publishing the already-published report is a no-op that tells the coordinator to finish, and a coordinator stuck on repeated tool errors after publication finishes instead of pausing. - Worksheet citations missing their `sheet:` prefix, such as `[D07 Financial Statement - manual]`, are saved under the exact sheet locator.\n\n### Public API\n\n- Return the captured workflow version label and version ID in async run-start and rerun responses, including responses when a synchronous wait expires.\n\n---\n\n## 0.20.96 (2026-10-28)\n\n### Platform (Studio)\n\n- Summary Agent: a report writer near the end of its allowance keeps enough requests to correct a rejected save instead of pausing after one attempt, figure links missing only their source prefix are saved under the exact figure ID, page lists such as `[D02 p12 p13]` are split into separate citations, and a paused run states why it paused. Clicking a citation in the report now highlights the cited passage in PDFs and web sources and the cited cells in workbooks, matching the sentence's figures across units (€ millions against EUR thousands) and locale formats. Elapsed times appear under written messages only.\n\n---\n\n## 0.20.95 (2026-10-27)\n\n### Platform (Studio)\n\n- Improve security of document processing, input validation and page configuration handling.\n- Summary Agent: reports finish reliably on the first run. The coordinator no longer audits sources itself; it applies reviewer repairs within a fixed allowance and then publishes instead of pausing. Research, writing and review have larger allowances, and source and document tools accept common argument variations instead of rejecting them. Edits that match are applied even when others in the same batch do not. The activity view is simpler: one orb for running work, flat grouped steps, quiet retry counts instead of error walls, no source index row, and elapsed time under each message that keeps counting across Continue.\n\n### Infrastructure & processing\n\n- Improve security of document processing, input validation and page configuration handling.\n\n---\n\n## 0.20.94 (2026-10-27)\n\n### Platform (Studio)\n\n- Add GPT-6.1 Terra for structured extraction, vision and agents, including its reasoning settings and published token prices. Existing default model selections stay unchanged.\n- Summary Agent: limit repetitive repair searches and provide clearer guidance when document edits cannot be applied. Research activity now groups queries and source links in a live, collapsible timeline, with named document updates, change previews and visible errors. Retry temporary model provider failures automatically for up to 30 minutes with a visible countdown. Preserve saved drafts and completed research when continuing interrupted reports, and allow longer model responses without consuming successful work allowances on connection failures.\n\n### CLI\n\n- Document how to select GPT-6.1 Terra for structured extraction, including reasoning settings and token prices.\n\n### Infrastructure & processing\n\n- Add GPT-6.1 Terra for structured extraction, vision and agents, including its reasoning settings and published token prices. Existing default model selections stay unchanged.\n\n---\n\n## 0.20.93 (2026-10-27)\n\n### Platform (Studio)\n\n- Show clear LLM provider connection errors with a Retry action that resumes saved work. Replace repeat generation with Start again, copying original inputs and report settings into an independent new session.\n\n---\n\n## 0.20.92 (2026-10-26)\n\n### Platform (Studio)\n\n- Report generation now prepares one complete draft for financial and coverage review, reducing repeated research and writing. The website displays the saved draft while review is in progress and updates it as supported corrections are applied. Public market research uses a bounded work allowance and saves supported findings with explicit evidence gaps. Unavailable source images are rejected before a draft is saved, and storage failures provide clearer diagnostics.\n\n---\n\n## 0.20.91 (2026-10-26)\n\n### Platform (Studio)\n\n- Public market research now uses a bounded work allowance and saves its supported findings with explicit evidence gaps, helping report generation proceed without an extended source-reading loop. Delegate financial chapters directly instead of requiring a shared baseline agent. Reject empty original-source scopes before evidence agents start, support Qwen thinking-mode tool calls, and allow the admitted report to finish within its existing lifetime request allowance without an artificial Continue boundary.\n- Keep PDF previews compatible with the updated document viewer.\n- Update cached editor folder breadcrumbs after moving a workflow through drag and drop or the Move dialog, without requiring a page refresh.\n- Workflow navigation now includes parent folders in the browser, Editor, and Evals, with a menu for deeper paths. Long conditions wrap within workflow cards so filter chains remain readable without spilling outside the card.\n\n### CLI\n\n- Refresh CLI dependencies for continued compatibility and maintenance.\n- Refresh CLI and SDK dependencies for continued compatibility and maintenance.\n\n### SDK\n\n- Refresh CLI and SDK dependencies for continued compatibility and maintenance.\n\n---\n\n## 0.20.90 (2026-10-25)\n\n### Platform (Studio)\n\n- Report citations use the text beside the clicked reference to locate a distinctive original passage instead of highlighting the start of every cited page. References without a reliable passage match open the page without a misleading highlight. Normal chat uses readable report labels instead of internal file and version codes, and newly published credit proposals omit the internal compaction label from their titles.\n\n---\n\n## 0.20.89 (2026-10-25)\n\n### Platform (Studio)\n\n- Workflow builder: script outputs typed `T | null` (for example `string | null`) now keep their type in autocomplete, the variable picker, the builder agent, API docs and generated SDK types instead of showing as `unknown`. Nullable objects stay navigable, so you can pick their nested fields.\n\n---\n\n## 0.20.88 (2026-10-25)\n\n### Platform (Studio)\n\n- Report generation hides redundant waiting activity when the specialist cards already show progress. Clearer rejection messages help the report assistant use each specialist's permitted capabilities and recover from invalid requests. Invalid illustration links are caught before publication so the assistant can correct them during the same run. Word preparation failures now return repairable errors instead of blocking the report as an unconfirmed publication; genuinely unconfirmed writes remain protected. Continuing a saved report can recover the known invalid-figure publication failure after verifying that no output was written. Completed chapters, reviews and saved work are retained.\n\n---\n\n## 0.20.87 (2026-10-25)\n\n### Platform (Studio)\n\n- Extraction: `ai.extract` and `ai.vision` no longer fail when a field the document does not contain comes back empty. Fields not listed in `required` may now be `null`, matching what the model is asked to return; required fields still must be present. The workflow builder shows these fields as `string | null`, and the builder agent keeps nullable values, identifiers and step settings correctly typed.\n\n### CLI\n\n- `eigenpal workflow validate` and `push` now warn about step settings that are silently ignored (for example `strategy` on a parse step or `outputSchema` on a script) and suggest the closest supported setting. The \"add an enum\" hint no longer fires on open-ended fields such as VINs, names, years and ids.\n\n### Infrastructure & processing\n\n- Extraction: `ai.extract` and `ai.vision` no longer fail when a field the document does not contain comes back empty. Fields not listed in `required` may now be `null`, matching what the model is asked to return; required fields still must be present. The workflow builder shows these fields as `string | null`, and the builder agent keeps nullable values, identifiers and step settings correctly typed.\n- Updated the email library (nodemailer) to a release that fixes how recipient addresses with comments, quoted text or `;` are parsed.\n\n---\n\n## 0.20.86 (2026-10-25)\n\n### Platform (Studio)\n\n- Updated the schema validation library (zod) to a release with a security fix. Email server settings keep their specific validation messages, such as rejecting SMTP credentials when security is set to none.\n\n### CLI\n\n- Refreshed the bundled skill reference so its schemas match the current validation rules.\n\n### SDK\n\n- An agent input or output schema that carries `.meta(\\{ id })` compiles again. With the updated validation library, its JSON Schema root came back as a reference instead of the object, and compiling failed with \"Root schema type must be object\".\n- Regenerated the SDK models from the API specification. Nullable fields are now described as a list of types instead of a choice of single types, with no change in accepted values. The email server update model documents that `transport` is left out of a name or enabled-only update.\n\n### Infrastructure & processing\n\n- Updated the schema validation library (zod) to a release with a security fix. Email server settings keep their specific validation messages, such as rejecting SMTP credentials when security is set to none.\n\n---\n\n## 0.20.85 (2026-10-25)\n\n### Platform (Studio)\n\n- Continuing an interrupted report grants fresh processing time while preserving completed chapters and saved work. Paused threads now show consistent agent statuses and hide redundant successful delegation rows.\n\n---\n\n## 0.20.84 (2026-10-25)\n\n- Internal improvements.\n\n---\n\n## 0.20.83 (2026-10-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.82 (2026-10-24)\n\n### Platform (Studio)\n\n- Report research now returns a compact source catalog while keeping original pages available for targeted reading. Generation can continue when a proactive summary is unhelpful but the existing conversation still fits, and paused agents display the actual reason for stopping.\n\n---\n\n## 0.20.81 (2026-10-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.80 (2026-10-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.79 (2026-10-24)\n\n### Platform (Studio)\n\n- Public market research receives only the company, industry and public research brief supplied by the analyst, without inheriting uploaded-file context or report instructions. Improve subagent task-input handling and remove duplicate report loading text. Accept grouped page citations without repeated document-write failures, while continuing to reject unknown pages and providing actionable correction messages.\n- Report agents now compact long conversations before reaching model limits, preserve accepted work when recovering from interruptions, and pause repeated identical tool errors instead of retrying indefinitely. Preserve the original task and evidence when compacting conversations, and improve tool-call compatibility with model gateways.\n\n---\n\n## 0.20.78 (2026-10-23)\n\n### Platform (Studio)\n\n- Security: updated Next.js to 16.4.1 and DOMPurify to 3.4.17, and container images now pick up operating system security updates daily.\n\n---\n\n## 0.20.77 (2026-10-23)\n\n### Platform (Studio)\n\n- Billing: OpenParser top-ups appear in checkout and on receipts as \"OpenParser credits\" with the OpenParser logo, and checkout starts with your account email already filled in.\n\n---\n\n## 0.20.76 (2026-10-23)\n\n### Platform (Studio)\n\n- Webhooks: rotate an endpoint's signing secret from the endpoint page and choose when the current secret expires. Keep it for 24 hours or 1 hour, and every delivery is signed with both secrets so you can update your receiver without rejecting events, or expire it now if it leaked.\n\n### Infrastructure & processing\n\n- Webhook signatures now follow Standard Webhooks, so any Standard Webhooks library can verify EigenPal events. **Action required if you verify signatures with your own code:** each signature is now `v1,&lt;base64&gt;` keyed by the base64-decoded secret (previously hex keyed by the secret text), and the `webhook-signature` header can carry more than one signature. Your secret is unchanged; the dashboard now shows it in standard base64. See the webhook receiver reference for the updated verification steps, then redeliver any events your receiver rejected before the update.\n\n---\n\n## 0.20.75 (2026-10-22)\n\n- Internal improvements.\n\n---\n\n## 0.20.74 (2026-10-22)\n\n### Platform (Studio)\n\n- Agents and workflows can continue with any positive credit balance without setting credits aside for estimated costs. Actual usage may take the balance below zero; further paid work stops once credits are exhausted, unless pay-as-you-go is enabled. Agent model credit limits also use actual usage and stop subsequent model requests once reached.\n- Company reports retain detailed analysis behind a compact, cited draft. Public research runs before chapter analysis, and follow-up conversations can answer questions or make focused Word edits without regenerating completed chapters. Report activity shows actual tool calls and subagent results, with saved progress available after reloading or continuing an interrupted run.\n\n### CLI\n\n- The bundled agent authoring reference now explains that credit checks use actual usage without reservations, including how an agent stops after reaching its model credit limit.\n\n### Infrastructure & processing\n\n- Platform updates can ship while OCR continues using its last validated version when a newer OCR version is not ready. New OCR versions still require successful staging validation before deployment.\n\n---\n\n## 0.20.73 (2026-10-22)\n\n### Platform (Studio)\n\n- Agents stay available on deployments without a sandbox. Self-hosted operators who previously turned agents off with `EIGENPAL_AGENTS_ENABLED=false` should set `EIGENPAL_SANDBOX_ENABLED=false` on both the app and worker instead: agents without a filesystem keep running, while filesystem agents and sandbox training are unavailable until a sandbox is enabled.\n\n### CLI\n\n- Bundle the public agent authoring guides, including callback capabilities, shared resources, filesystem options and typed evaluations. Clarify the distinction between the authoring SDK and API clients.\n\n### SDK\n\n- Allow immutable filesystem variants after evaluator and pass registration, preserve inferred evaluator and output types, and reject async/generator evaluation callbacks early. Document callback capabilities, limits and authoring checks.\n\n---\n\n## 0.20.72 (2026-10-22)\n\n### Platform (Studio)\n\n- Ship Node.js 22.23.4 in the self-hosted app, summary agent and single-node images, and Node.js 24.22.1 in agent sandboxes, fixing the October 2026 Node.js security release CVEs (including the Brotli decoder and TLS hostname verification issues).\n\n---\n\n## 0.20.71 (2026-10-21)\n\n### Platform (Studio)\n\n- Studio displays typed agent evaluation rules and weighted or custom pass decisions. Agent trigger edits update the draft and take effect when it is released.\n\n### Public API\n\n- The evaluator API reports typed agent evaluation rules and their weighted or custom pass decision from the requested agent source version. Agent evaluation changes take effect when the updated agent is released.\n\n### CLI\n\n- Evaluate individual agent examples with the same versioned evaluation rules and pass decision used by batch runs.\n\n### SDK\n\n- Define agents with inline or file instructions, immutable .withFilesystem() variants with bounded seed files and exact sandbox packages, custom typed tools, working directories, and composable execution guards. Define knowledge, rules, templates and directory skills as imported TypeScript resources. Portable resource text works in both agent modes; skills require filesystem access. Capture resources at the agent release commit instead of maintaining unchecked version strings.\n\n---\n\n## 0.20.70 (2026-10-21)\n\n### Platform (Studio)\n\n- Training sessions wait longer when agent preparation is busy, reducing temporary connection failures.\n\n---\n\n## 0.20.69 (2026-10-21)\n\n### Platform (Studio)\n\n- Updated dependencies improve protection against command injection, cross-site scripting, credential disclosure, and excessive resource usage.\n- Report merging and review now display their actual tool calls in the main agent transcript, and retain those calls when reopening a completed report. Reports recover from oversized model responses with smaller batches and let you retry a failed merge or review without rerunning successful chapters. Accepted edits are retained for recovery. Merge and review stages that reach their execution budgets pause with a Continue action instead of a generic failure. Report merging and review preserve completed sections while making targeted edits, and stop repeated unchanged source reads from consuming the remaining execution budget.\n\n### SDK\n\n- The Python SDK now requires an updated certificate trust store that excludes compromised certificate authorities, improving HTTPS connection security.\n\n---\n\n## 0.20.68 (2026-10-21)\n\n- Internal improvements.\n\n---\n\n## 0.20.67 (2026-10-20)\n\n### Platform (Studio)\n\n- Runs now show clearer file source errors to help diagnose input failures. Run lists and details remain readable on smaller screens, including long error messages and execution timelines.\n\n---\n\n## 0.20.66 (2026-10-20)\n\n### Platform (Studio)\n\n- Configure selectable Summary Agent model aliases and readable labels through SUMMARY_MODELS rather than gateway discovery. Allow the isolated public researcher to pursue focused evidence gaps beyond the initial six searches, retain original sources for downstream citations, and display public search calls with a globe icon.\n- Summary reports support direct OpenAI Luna tool calls with compatible request parameters. Public web research can use separate credentials, keeping report credentials confined to their configured provider.\n- Support explicit per-model reasoning controls in SUMMARY_MODELS for configured gateways. Reject reasoning-only output-token exhaustion with a useful diagnostic rather than replaying identical requests, and never accept token-truncated reports or execute truncated tool calls. A nonempty truncated response receives one bounded complete-draft retry.\n- Queued report follow-ups now wait for the completed Word document. The editor mounts each new version with its matching file bytes, preventing edits or exports of a temporary generation placeholder.\n- Avoid false reconciliation failures when an explicitly unreconciled bank/issuer gap is followed by a separate operating explanation. Financial writers can request targeted model corrections to a source-cited draft without regenerating unaffected paragraphs, while all existing source and numerical checks remain enforced. Preserve concrete chapter failure reasons and distinguish empty model replies from invalid reporting sections. Keep the targeted-edit instruction active during the final drafting reserve, and resolve exact bare worksheet names to canonical source-unit IDs for follow-up evidence reads.\n\n---\n\n## 0.20.65 (2026-10-20)\n\n### Platform (Studio)\n\n- Connect is easier to read with a compact setup bar, larger request field descriptions, and code examples that adapt to the available space. Required inputs appear first, while optional fields and request options expand when needed.\n- Allow file sources to declare additional workflow input fields with validated schemas. Preserve fetched fields with the file across retries, and support per-document metadata selection in run and dataset forms.\n\n### Infrastructure & processing\n\n- OpenParser can process more cloud OCR requests concurrently, reducing queueing during bursts of document uploads.\n- Allow file sources to declare additional workflow input fields with validated schemas. Preserve fetched fields with the file across retries, and support per-document metadata selection in run and dataset forms.\n\n---\n\n## 0.20.64 (2026-10-20)\n\n### Platform (Studio)\n\n- Summary reports retry temporary public search failures and show unsuccessful searches with clear error details. Changing the report model no longer changes the web retrieval model. Word follow-up edits accept unused empty tool fields and support expanding one paragraph into several paragraphs without editor errors. The model picker uses the shared dropdown beside report actions and in the follow-up composer. The composer no longer covers report settings or shows a scrollbar for short messages. Public searches use an independent retrieval default, avoid concurrent request bursts, and allow throttled providers time to recover.\n\n---\n\n## 0.20.63 (2026-10-20)\n\n### Platform (Studio)\n\n- Model defaults and examples use current provider models. Existing workflows and agents keep their explicitly selected models.\n- Improve compatibility with configured models during summary generation. Research and chapter analysis can recover from an incomplete first response instead of failing immediately, while retaining original-source verification. Keep the approved report subject and public research handoff through every writer, merge and review stage. Reject unrelated namesake companies instead of mixing their public financials into the borrower report. Preserve native assistant tool calls and matching tool-result messages during source inspection and calculation, rather than presenting tool output as a user instruction.\n\n### CLI\n\n- Workflow examples use current model IDs, and evaluation guidance covers reasoning settings and checks when changing models.\n\n### Infrastructure & processing\n\n- Improve compatibility with current Claude, GPT, and Gemini models, including reasoning controls and structured extraction. Gemini usage includes billable thinking tokens and cached input. New self-hosted configurations use current model defaults.\n\n---\n\n## 0.20.62 (2026-10-20)\n\n### Platform (Studio)\n\n- Run the latest saved workflow without creating a release. The editor now separates Save changes from Create release, with a clearer release dialog and help on demand. Missing versions fall back to the latest version, duplicate run submissions are prevented, and release errors stay visible so you can retry.\n- Workers now respect EIGENPAL_AGENTS_ENABLED=false when discovering agent sandboxes, preventing repeated E2B connection warnings in deployments with agents disabled. Cleanup of known stale sandbox executions remains active.\n- Summary Agent preserves spreadsheet formula errors instead of treating them as financial amounts, refreshes affected spreadsheet sources in older sessions, and checks table units before accepting financial prose. New report runs perform fresh research and analysis, with original-source inspection and clearer activity history.\n- Workflow Pal now uses available workflow inputs, file sources, and permitted subworkflows to prepare more reliable edits. Review proposed changes in a clearer editor panel, jump directly to the first change, and keep manual edits protected while a proposal is prepared.\n\n---\n\n## 0.20.61 (2026-10-19)\n\n### Platform (Studio)\n\n- Summary Agent now supports model selection, clearer failure details and more reliable report review and follow-up messages. Reports complete internet research first, then financial analysis, then the remaining chapters before merging and reviewing the final document.\n\n---\n\n## 0.20.60 (2026-10-19)\n\n### Platform (Studio)\n\n- On-premises deployments can configure additional file source integrations and certificate authentication.\n\n---\n\n## 0.20.59 (2026-10-19)\n\n### Platform (Studio)\n\n- Ship the nine-chapter credit-report prompt pack, including new market summary and peer analysis chapters, shared analyst writing guidance and fictional examples. Add bounded provider retries, resumable source-checked stages, a model merge with one independent review, native Word tables and source figures, and LiteLLM model routing for on-prem deployments. New sessions use the shipped prompts while restored sessions retain their selected version. Follow-up chat can edit the current Word document, preserving analyst changes, and request approved public research. Update DOCX editor packages to 2.31.0 and add sector-specific first-pass research guidance.\n- Keep document editing available consistently across the application and credit-report follow-up chat.\n\n---\n\n## 0.20.58 (2026-10-18)\n\n- Internal improvements.\n\n---\n\n## 0.20.57 (2026-10-18)\n\n- Internal improvements.\n\n---\n\n## 0.20.56 (2026-10-17)\n\n- Internal improvements.\n\n---\n\n## 0.20.55 (2026-10-16)\n\n- Internal improvements.\n\n---\n\n## 0.20.54 (2026-10-16)\n\n### Infrastructure & processing\n\n- Agent definitions now load reliably when starting runs.\n\n---\n\n## 0.20.53 (2026-10-16)\n\n### Platform (Studio)\n\n- Experimental agents now use their TypeScript definitions consistently when running and resuming, with more reliable definition validation and preserved version history.\n\n### Public API\n\n- Agent metadata now follows the released definition consistently across agent listings and runs.\n\n### CLI\n\n- Agent packages now use TypeScript for configuration and schemas. Frozen installs require captured definitions so resumed runs continue using the same version.\n\n---\n\n## 0.20.52 (2026-10-16)\n\n### Platform (Studio)\n\n- Agent validation and run preparation retry once after a temporary timeout.\n\n---\n\n## 0.20.51 (2026-10-16)\n\n### Infrastructure & processing\n\n- Improve OCR update reliability when spare processing capacity is available.\n- OpenParser prioritizes organizations that have purchased credits within regular and batch request queues. Regular requests still precede batches, and long-waiting requests retain protection against starvation.\n\n---\n\n## 0.20.50 (2026-10-16)\n\n- Internal improvements.\n\n---\n\n## 0.20.49 (2026-10-16)\n\n### Platform (Studio)\n\n- Support TypeScript agent definitions in authoring, releases and execution while preserving existing agents and interrupted runs. New agents use typed configuration and schemas.\n\n### Public API\n\n- Agent endpoints support typed agent definitions and validate inputs against the selected release's schemas while preserving existing agent releases.\n\n### CLI\n\n- Create, validate and release agents with typed TypeScript configuration and schemas. Existing agents remain supported, and dataset validation checks the agent's declared schemas.\n\n---\n\n## 0.20.48 (2026-10-15)\n\n### SDK\n\n- Preserve special JSON Schema keys during compilation without changing schema data.\n- The open-source TypeScript authoring SDK provides `createAgent`, typed input/output schemas, and a compiler for agent configuration. Existing agents continue running unchanged; TypeScript source integration follows separately.\n\n---\n\n## 0.20.47 (2026-10-15)\n\n### CLI\n\n- Git authentication keeps working after runtime upgrades when running the CLI from source.\n\n---\n\n## 0.20.46 (2026-10-15)\n\n### Platform (Studio)\n\n- Training conversations show saved messages while the agent prepares in the background. Messages submitted during preparation wait safely until the agent is ready, and connection errors leave conversation history readable.\n\n---\n\n## 0.20.45 (2026-10-14)\n\n### Platform (Studio)\n\n- Human review now displays confidence scores for nested fields even when lineage evidence is unavailable. Run rows also keep review and duration badges from overlapping in narrower lists.\n- Dataset tab in Studio no longer shows \"No runs yet\" for examples that have run. Agent experiment batches now point each example's `latestRunId` at the new run (the workflow path already did), and the examples list falls back to the newest run by example id when that pointer is missing or stale — the same source the example detail pane's Run Activity reads — so the list and detail can no longer disagree about whether an example has ever run.\n- Fix the caret jumping to the end of the \"Note on this example\" field on every keystroke in the dataset-review Resolve panel. The textarea now edits a local draft that stays fresh through React's controlled-state restoration, while still lifting each keystroke to the session draft.\n- Public research now uses the approved company search when its initial query is left blank, avoiding an unnecessary error at the start of research. Model connection failures now include a diagnostic error code when available, helping distinguish timeouts, refused connections and certificate problems.\n- Fix duplicate nested workflow timeline rows and missing start times that leave running leaf-step timers at zero.\n\n### Public API\n\n- Start workflow runs with a bare workflow ID such as `wf_abc` in the `target` field, for JSON and multipart requests. Existing `workflows.&lt;id-or-slug&gt;` targets remain supported.\n\n### CLI\n\n- Clarify how to flag specific dataset review fields and attach field comments with current workflow values. Agent guidance now keeps expected outputs aligned with the full intended workflow output and leaves comparison rules to evaluators.\n\n### Infrastructure & processing\n\n- Grounded extraction now preserves confidence for scalar fields inside nested objects and arrays, so review routing and confidence displays remain complete for structured outputs.\n- Fix duplicate nested workflow timeline rows and missing start times that leave running leaf-step timers at zero.\n\n---\n\n## 0.20.44 (2026-10-14)\n\n- Internal improvements.\n\n---\n\n## 0.20.43 (2026-10-13)\n\n### Platform (Studio)\n\n- GPT-6.1 Sol is available for agents, with lower cached-input pricing than GPT-6 Sol.\n- Organization admins can choose a default runtime model for agents in Model settings. Agents can inherit that choice or select a specific model. Changing the organization default applies to new runs; existing runs keep their selected model.\n- Pro includes 5,000 credits each month. Organization admins can enable optional pay-as-you-go at $1 per 100 additional credits, billed with the monthly subscription. Billing now clearly shows available, used, and reserved credits, the renewal date, and outstanding additional usage.\n\n### Public API\n\n- Agent responses expose their runtime model override. New agent runs resolve an organization default when unpinned and snapshot the model selected from the requested source version and runtime policy.\n\n---\n\n## 0.20.42 (2026-10-13)\n\n### Platform (Studio)\n\n- Apply operating system security updates to application and processing container images.\n- Rerun with changes now preserves the original workflow version and its input fields, including older releases and saved drafts. If that version cannot be loaded, the form shows an error instead of running a newer version.\n- Run details: input values can now be selected and copied, with a copy button on each value. The Rerun menu adds \"Rerun with changes\", which opens the Trigger page pre-filled with the run's inputs and tags so you can edit them before running. Uploaded files need to be added again.\n- Workflow builder: step outputs that are files (such as the merged PDF from Merge Documents) now show as `file` in reference pills and the variable browser, matching file inputs. Start node inputs that come from an external file source show the source name as a badge.\n\n### Public API\n\n- Webhook events now include the run's tags in `data.run.tags`. Tags stay in the event even when a large `output` is omitted, so you can tag a run with your own identifiers in `POST /api/v1/runs` and match every webhook back to your records without an extra API call.\n\n### CLI\n\n- Updated workflow guidance to explain how waiting for child runs frees processing capacity and how to start a child without waiting for its result.\n\n### SDK\n\n- The `tags` option when starting a run now documents that tags are returned in every webhook event as `data.run.tags`, for correlating events with your own records.\n\n### Infrastructure & processing\n\n[View full release notes →](/releases/0.20.42)\n\n---\n\n## 0.20.41 (2026-10-13)\n\n### Platform (Studio)\n\n- Workflow canvas, for large workflows with conditions, switches, loops and parallel steps: - Nested blocks stay inside their branch. - Fork and join lines meet every branch. - Short branches no longer stretch into empty panes. - Containers show their description and can be collapsed to a one-line summary. - Loops say what they repeat over. - \"Fit to screen\" shows the whole workflow. - \"Add step\" buttons appear on hover inside branches and in longer workflows.\n- Workflow editor and Evals fixes: - Undo now takes one step back per change, including the first change after an undo. - Undoing a newly added step also closes its settings panel. - Cmd+S saves from inside a field, including edits you haven't left the field for yet. - Leaving with unsaved changes offers Save & Leave. - The unsaved-changes marker is a labelled \"Unsaved\" status. It no longer appears on Evals right after saving. - New steps describe missing settings by name (\"Input is required\") instead of raw validation text. - The run panel opens the output when a run finishes. - Experiments that no evaluator scored show \"Not scored\" instead of 0%. - Evaluator names are formatted as you type, and save errors read as plain sentences. - A new dataset example opens on its Input tab. - The toast for starting an experiment from Dataset has a View link to the results.\n- Workflow editor and Evals: the canvas is calmer, with Start and End matching the step cards, Run inside the Start card, neutral connectors, quieter step containers and a subtle response on hover and click. Switching between Editor and Evals, and between Experiments, Dataset and Evaluators, now responds the moment you click, and the workflow version stays visible on both views. Experiments are listed by their example count with a short id instead of a long raw id, \"Run all dataset examples\" shows progress while it starts, an empty time range shows a single clear message instead of empty charts, and experiments without evaluators point you to adding one. Workflow Pal always builds with the current Parse Document and explains that the previous version is kept only for existing workflows.\n- Workflow editor: - The canvas has Undo and Redo buttons. - Renaming a step, a workflow input, or a Set Value or Extract Data field updates every reference to it. - The run panel shows the run's status and duration first. - Step types are named as on the canvas (\"Set Value\"). - When a run input is missing, the form highlights the field and moves the cursor to it. Evals: the pass threshold is set in the evaluator config and saved with it, with a single \"Save evaluators\" button.\n- Grafana dashboard: the Deployment target now defaults to All and panels merge targets, so the dashboard keeps working after an app pod restart changes the scrape target's IP instead of showing NO TARGET until someone picks the new one.\n- Workflows: new Merge Documents step combines several uploaded files (PDFs, scans, phone photos, Word, PowerPoint and OpenDocument files) into one PDF, so Parse, Label Pages, Split and Inspect Pages number pages continuously across every file. Its output lists which pages came from which upload, and the run view shows that page map. In the step picker, Parse Document is now the only parser offered for new steps; existing steps on the previous parser show as Parse Document v1 and offer a one-click switch. Run views now preview the right document when a step reads a file produced earlier in the run, and output files show their real names.\n- Prometheus: a new `eigenpal_automation_ocr_pages_total\\{automation_id}` counter reports the OCR pages each workflow processed. The Grafana dashboard now shows total OCR pages for the selected range, an OCR pages by workflow table, and a pages-per-minute chart of the top 10 workflows.\n- SSO: API keys owned by an SSO user no longer stop working 24 hours after the owner's last sign-in when EigenPal cannot re-check them with the identity provider. Scrapers and integrations keep running; keys still stop when the identity provider refuses the owner, the owner is removed or demoted, or the key is revoked. Refused keys now log a reason (`owner_refused_by_directory`, `owner_without_access`) instead of failing silently.\n\n### Public API\n\n- Starting a run with a single file for an input declared as a list of files now works: the file is treated as a one-item list instead of being rejected.\n- `GET /api/v1/runs` accepts `hasExample=true` to return only runs linked to a dataset example, so evaluation views no longer have to page through production runs to find them.\n\n### SDK\n\n- Listing runs accepts a `hasExample` filter (`has_example` in Python) that returns only runs linked to a dataset example.\n\n[View full release notes →](/releases/0.20.41)\n\n---\n\n## 0.20.40 (2026-10-11)\n\n### Platform (Studio)\n\n- Security hardening: people join an organization only by accepting an invite (the direct \"add existing user\" endpoint is gone), only owners can grant the admin role, members can revoke only their own API keys, API keys can no longer manage keys, members, invites, organization settings, sharing or billing, and demoting someone to viewer or reviewer revokes their API keys. Agent training only reads this session's uploads, email triggers accept a sender only when DMARC passes for the From domain or, for domains without DMARC, SPF passes for that domain, and workflow templates cannot read files from the worker.\n\n### Public API\n\n- Listing workflow executions only resolves file names for files in your own organization.\n\n---\n\n## 0.20.39 (2026-10-10)\n\n### Platform (Studio)\n\n- File source connections support multiple-file inputs. Callers supply a list of file references, and the workflow receives the fetched files in order.\n- Run form: lists are easier to fill in. Execution tags, and inputs that take a list of text or numbers, now use a chip input: type a value and press Enter, or paste a whole column or row at once. A value that doesn't fit, such as text in a number list, is marked before the run starts. Inputs with a fixed set of allowed values show every option as a chip you can toggle.\n\n### CLI\n\n- The workflow reference now documents `source` on file-list inputs (`type: array`, `items: \\{ type: file }`), which take one file reference per file.\n\n### Infrastructure & processing\n\n- Pushes and fetches of workflow source that are in progress during a platform update now finish instead of being cut off.\n\n---\n\n## 0.20.38 (2026-10-09)\n\n- Internal improvements.\n\n---\n\n## 0.20.37 (2026-10-09)\n\n### Platform (Studio)\n\n- Error reports sent from the browser now scrub tokens, secrets and sensitive URL parts before they leave the page, the same way server error reports already did.\n- Runs started from the CLI keep showing a plain \"CLI\" trigger in run details, without an extra SDK badge, now that the CLI identifies itself on API requests.\n- Grafana dashboard: a new \"Worker slots online\" tile shows how many jobs your workers can run at once, next to \"Workers online\". Slot panels and the worker table now say \"worker slots\" so a worker (one process) is never confused with its job slots.\n\n### CLI\n\n- The CLI now identifies itself on every API request with a `User-Agent: eigenpal-cli/&lt;version&gt; (&lt;runtime&gt;; &lt;os&gt;)` header and the same `X-Eigenpal-Sdk-*` headers the SDKs send, so CLI traffic and errors can be told apart from SDK and browser traffic. Runs started from the CLI record the CLI version in their trigger metadata.\n\n### Infrastructure & processing\n\n- When an AI extraction or vision step returns output that does not match its schema, the run now fails as a schema mismatch in the model output instead of a generic platform error, so failure reports and metrics point at the step's schema or model rather than at the platform.\n\n---\n\n## 0.20.36 (2026-10-09)\n\n- Internal improvements.\n\n---\n\n## 0.20.35 (2026-10-09)\n\n### Platform (Studio)\n\n- Monitoring: the Prometheus metrics endpoint now counts failed runs by cause (`eigenpal_execution_failures_total`), so input problems and deliberate workflow rejections no longer look like platform errors. A run stopped by a workflow's `control.fail` step now reports the `workflow_rejected` failure code.\n\n### Infrastructure & processing\n\n- Monitoring: the Prometheus metrics endpoint now counts failed runs by cause (`eigenpal_execution_failures_total`), so input problems and deliberate workflow rejections no longer look like platform errors. A run stopped by a workflow's `control.fail` step now reports the `workflow_rejected` failure code.\n\n---\n\n## 0.20.34 (2026-10-08)\n\n### Platform (Studio)\n\n- Monitoring: the Prometheus metrics endpoint now reports registered organizations and users, organizations active in the last 7 and 30 days, and paying organizations, so operators can follow adoption next to processing health.\n\n---\n\n## 0.20.33 (2026-10-08)\n\n### Platform (Studio)\n\n- Monitoring: our team now tracks run volume, outcomes and timing across EigenPal Cloud in real time, so slowdowns and failures are spotted and fixed sooner.\n\n---\n\n## 0.20.32 (2026-10-08)\n\n### Platform (Studio)\n\n- Billing: our team is now notified as soon as a payment, renewal, failed payment, refund or dispute happens, so billing problems on your account get followed up faster.\n\n---\n\n## 0.20.31 (2026-10-08)\n\n### Platform (Studio)\n\n- Monitoring: the Webhooks section of the EigenPal Grafana dashboard now shows events delivered alongside events not delivered, with a donut of delivery outcomes for the selected range and a per-minute chart of delivered versus not delivered.\n- Summary research now saves valid claims together while identifying only those needing correction. Clearer review guidance and more reliable document access reduce repeated failed attempts before completing financial chapters.\n- Public research claim details now show the full sentence, acceptance status and supporting evidence, including earlier claims that were subsequently revised.\n- Webhooks: endpoints can now be shared like workflows. A Manager of an endpoint (and any owner or admin) shares it with people and groups as Viewer, Editor or Manager, and members can create their own endpoints. An endpoint receives either every run (owners and admins only) or runs of selected workflows, and nobody can point one at runs of a workflow they cannot open. Existing endpoints stay private to owners and admins.\n\n---\n\n## 0.20.30 (2026-10-08)\n\n### Platform (Studio)\n\n- Fixed run cancellation and research approvals being rejected behind HTTPS reverse proxies while retaining browser origin checks. Improved public research with relevant source excerpts, a source-checked driver brief, and an independent editing pass. Chapter agents can investigate material public evidence gaps with human-approved searches and record their research decisions. Source pickers now emphasize filenames with file types underneath.\n\n---\n\n## 0.20.29 (2026-10-08)\n\n### Platform (Studio)\n\n- Settings, File Sources supports named connections for Amazon S3 and Azure Blob Storage. Administrators can configure multiple connections, manage stored secrets, and view deployment-managed connections as read-only.\n- Monitoring: the Prometheus metrics endpoint now reports webhook delivery attempts with their outcome and failure reason, events that were never delivered, delivery backlog and the oldest due delivery, and receiver response times. The EigenPal Grafana dashboard has a new \"Webhooks\" section, and the metrics guide includes ready-to-use alert rules for failing receivers, undelivered events and stalled delivery.\n- Webhooks: a new **Delivery settings** panel sets the retry policy, the request timeout and, on self-hosted deployments, whether endpoints may resolve to private network addresses. Settings pinned by the deployment show a lock. Each failed delivery now explains why it failed (for example, blocked private address, TLS handshake failure or connection refused), right in the delivery list, and links to the setting that fixes it. Deliveries waiting to retry show when the next attempt runs, and unsaved endpoint changes collect in a save bar that no longer shifts the page.\n\n### Public API\n\n- File source inputs accept structured references such as `\\{ \"bucket\": \"...\", \"key\": \"...\" }` for Amazon S3 and `\\{ \"container\": \"...\", \"blobName\": \"...\" }` for Azure Blob Storage. Reference fields are validated against the connection type.\n\n### CLI\n\n- The bundled webhooks guide and reference now cover delivery settings, the retry schedule, and how to ask for a retry while your receiver is still storing a run.\n- The bundled Prometheus metrics guide now documents webhook delivery metrics and example alert rules.\n\n### Infrastructure & processing\n\n- Settings, File Sources supports named connections for Amazon S3 and Azure Blob Storage. Administrators can configure multiple connections, manage stored secrets, and view deployment-managed connections as read-only.\n- Self-hosted deployments now deliver webhooks to endpoints on the private network by default, matching file sources and telemetry export. Previously these deliveries were refused without sending a request. Loopback, link-local and cloud metadata addresses stay blocked on every deployment, so a webhook can never reach the worker itself or node credentials.\n\n---\n\n## 0.20.28 (2026-10-07)\n\n### Platform (Studio)\n\n- Parse native and scanned documents automatically with the new Parse Document step. It preserves usable native PDF pages, recovers unread content with configured OCR or vision, and reports the source and completeness of each page. Advanced controls let you choose providers, restrict backends, require layout evidence, and tune vision processing. Existing parser steps keep their behavior. New workflows use automatic parsing, and you can review an explicit migration before publishing an updated workflow. The CLI and SDKs also provide a parsing configuration readiness check to help prepare deployments for scanned documents.\n- Preserve workbook-aware XLS/XLSX display formatting, trim empty trailing sheet extent before conversion limits, and expose optional original cell evidence for mixed date/identifier extraction. Forward sheet metadata through workflow execution and document how agents should use source evidence.\n\n### Public API\n\n- Inspect configured document-reading capabilities and provider selection through the authenticated parsing readiness endpoint. The response reports native/OCR/vision configuration and does not claim live endpoint verification.\n\n### CLI\n\n- Review document-parser migrations before publishing them with the new parser migration command. Updated workflow templates and agent guidance use automatic parsing by default. Inspect parsing configuration readiness through the CLI and SDKs to check whether your deployment has providers for scanned documents.\n\n### SDK\n\n- Review document-parser migrations before publishing them with the new parser migration command. Updated workflow templates and agent guidance use automatic parsing by default. Inspect parsing configuration readiness through the CLI and SDKs to check whether your deployment has providers for scanned documents.\n\n---\n\n## 0.20.27 (2026-10-07)\n\n### Platform (Studio)\n\n- Restore the PDF embedding, employment verification, Hacker News digest, and slow pipeline templates in the workflow template picker.\n- Financial summaries now investigate the drivers behind material changes across reporting periods. Other chapters wait for completed financial analysis and use it as additional context; incomplete financial chapters can be retried before the rest of the summary proceeds.\n- Monitoring: the Prometheus metrics endpoint now reports LLM token usage and finished runs for each workflow and agent, and the EigenPal Grafana dashboard has a new \"Usage by workflow\" section showing tokens, share of total, runs, and tokens per run per workflow, plus a chart of the top 10 consumers and a workflow filter.\n- Strengthened document image processing and mathematical expression rendering security.\n- Workflow access control: share workflows and folders with specific people or groups at four levels (Viewer, Runner, Editor, Manager). Access is set on top-level folders, the way a shared drive is run: everything inside a folder has that folder's access, so there is one place to check and change it. Making a folder private limits it to the people and groups you choose. Groups come straight from your identity provider (Keycloak, Entra ID, Okta, or a corporate sign-in service) and stay managed there, or can be created in EigenPal for password users. Each folder says at the top who can open it, with a Manage access button, and right-clicking a folder or workflow offers Manage access too. The access panel shows everyone who can open an item and why, and says who gains or loses access before you save. Moving something into a folder with different access asks first and shows the access before and after. Settings gains an Access control page: check whether a person can open a folder or workflow and see exactly why, see each person's groups and what your identity provider reports for them, and manage groups. A per-person access review sits on each member. Every sharing and group change is recorded in the audit log. Directory changes apply within minutes, and disabling someone at the identity provider signs them out of EigenPal. Admins can make every new top-level folder and workflow start private, and export who can open what as a CSV for access reviews. When an owner or admin opens a private item only their role lets them see, that is recorded too. Run history of a deleted workflow is visible to owners and admins only. Nothing changes for an organization until it makes something private.\n- Faster folder navigation for workflows. A folder tree now sits beside the workflow list: open any folder in one click, keep your place as you move around, and use the arrow keys to browse it. Long folder paths fold their middle into a menu so the path stays readable. Organize by dragging. Drop a workflow or folder onto a folder in the list, in the tree, or in the path above the list to move it there. Folders in the tree open when you hover over them while dragging, so you can move items several levels deep in one go. A preview follows the pointer and names where the item will land, only valid folders light up, and every move can be undone from the confirmation. Top-level folders and workflows show who they are shared with. Hover the avatars to see each person and group with their access level, or click them to manage sharing.\n\n### Public API\n\n- Automations, runs, datasets, experiments, evaluators, versions, folders, files and review endpoints now honor workflow access control. A workflow the caller cannot open answers `404`, exactly like one that does not exist, and is left out of every list. A workflow the caller can open but not change answers `403` for the change. Starting a run needs Runner access. API keys act with the access of the person who created them.\n\n### CLI\n\n- Simplify the bundled Prometheus metrics guide to bearer API key authentication and the metrics reference.\n\n### SDK\n\n- Strengthened Python SDK generation security while preserving Python 3.10 compatibility.\n\n[View full release notes →](/releases/0.20.27)\n\n---\n\n## 0.20.26 (2026-10-06)\n\n### Infrastructure & processing\n\n- Applied security updates to the GPU hosts that run document recognition and to a logging dependency used by the processing services.\n\n---\n\n## 0.20.25 (2026-10-06)\n\n### Platform (Studio)\n\n- Workflow Pal now honors configured authentication and custom headers for private model gateways, matching workflow execution and preventing chat failures on gateways requiring additional credentials.\n\n---\n\n## 0.20.24 (2026-10-06)\n\n### Platform (Studio)\n\n- Workflow and agent Swagger exports now include the run's `execution` object, documenting status and execution details consistently with API responses.\n\n---\n\n## 0.20.23 (2026-10-05)\n\n### Platform (Studio)\n\n- API keys: choose an access level when you create a key. **Full access** works with the API, CLI, and SDKs, as every existing key does. **Observability (read-only)**, available to owners and admins, can only read the Prometheus metrics endpoint, so monitoring systems no longer need a key that can run automations or read your data. On self-hosted deployments the Prometheus endpoint is now on by default and authenticates with an observability key, so monitoring needs no server configuration.\n- Monitoring: the Prometheus metrics endpoint for self-hosted deployments now reports LLM token usage by model, execution throughput and failure counts, execution, queue-wait, step, and LLM call latency histograms, OCR page volume, human-review outcomes, and per-worker process health (memory, CPU, event loop lag, and busy slots) alongside live queue depth. Counters stay accurate across restarts and data retention, a single scrape target covers the whole deployment, and collectors that request OpenMetrics (including Prometheus 3) receive it. Metric names follow Prometheus naming conventions, and the new Prometheus metrics documentation covers every metric. Owners and admins can turn the endpoint off in Settings > Monitoring, which also links to a prefilled form for creating an observability API key.\n\n### Public API\n\n- API keys now have an access level. Every API endpoint requires a **Full access** key, which is what all existing keys have, so existing integrations keep working. An **Observability (read-only)** key is refused with `403` by every endpoint except `GET /v1/auth/check`, which reports the key's own identity and scopes so you can verify a key before using it.\n\n---\n\n## 0.20.22 (2026-10-05)\n\n### Platform (Studio)\n\n- Workflow validation now accepts dynamic child-workflow targets with a runtime-check warning, explains why dynamic inline targets are unsupported, and rejects review selectors that a known schema proves cannot select a scalar field.\n- Downloaded API specs for a single workflow or agent now report that automation's own version instead of the platform release number, so upgrading Studio no longer looks like an API change to generated clients. The platform release is still included in the spec as `x-eigenpal-platform-version`. Self-hosted installs behind a proxy or OpenShift route also get the correct public server URL in the spec, and the spec no longer lists an unreachable server address when the public hostname cannot be determined.\n- Studio picks up the latest security fixes in its web framework.\n\n### Public API\n\n- Run input failures now report specific causes and include the input location and run correlation ID in debug diagnostics, without exposing document contents or storage paths.\n\n### CLI\n\n- Evaluation summaries now distinguish execution success from evaluator verdicts. Existing success-count fields remain available, and online validation warnings no longer cause a failed validation exit.\n\n### Infrastructure & processing\n\n- Child workflows now start only after their input files are available, improving reliability when forwarding files nested inside other inputs. File preparation failures now identify missing files and invalid references more clearly.\n\n---\n\n## 0.20.21 (2026-10-02)\n\n### Platform (Studio)\n\n- Assign dynamic tags to child workflow runs, filter run history by an exact tag, and open matching runs from their tag labels. Retries and reruns retain the original tags. Set tags on the Trigger page and generate tagged REST and SDK examples on Connect.\n\n### Public API\n\n- Workflow and agent run requests accept `tags` as a string or a list of strings. Run responses include tags, and `GET /api/v1/runs?tag=...` finds runs with an exact, case-sensitive tag.\n\n### CLI\n\n- Use `eigenpal runs list --tag &lt;tag&gt;` to find runs with an exact tag, such as a request ID. Start an ad-hoc workflow or agent run with `eigenpal run &lt;target&gt; --tag &lt;tag&gt;`. Repeat `--tag` for multiple tags.\n\n### SDK\n\n- Pass execution tags when starting workflow or agent runs with the TypeScript and Python SDKs, including runs with file inputs. Filter run history by tag using the runs client.\n\n---\n\n## 0.20.20 (2026-10-02)\n\n### Platform (Studio)\n\n- Summary builder: invalid claim registration input now shows a clear error instead of a misleading claim count.\n- Settings: each settings page now shows a loading placeholder shaped like the page itself, instead of a generic one that repeated the settings navigation and title.\n\n### Infrastructure & processing\n\n- Strengthen security protections for document extraction.\n\n---\n\n## 0.20.19 (2026-10-01)\n\n### Platform (Studio)\n\n- The Agents page and agent detail views load faster, especially for organizations with many agents. Opening one agent now reads only that agent instead of the whole organization, and source lookups for one organization no longer slow down other organizations.\n- Dashboard pages respond faster. Every page load and live refresh in EigenPal now does less work before returning data, and pages that hit a permission error show it right away instead of retrying first.\n- Pages and live status updates in EigenPal Studio respond faster, because signed-in requests no longer wait on an account profile lookup every time. A change to your account email still takes effect within a minute, and invitations are always matched against your current verified addresses.\n- Hardened sign-in account linking: signing in with an email address no longer connects you to an existing EigenPal account that belongs to a different sign-in. If your previous sign-in account was deleted, signing up again with the same email still restores access to your existing account.\n- The Workflows and Runs pages load faster, especially in organizations with many workflows or a long run history. The Workflows page now fetches only what its cards and rows show, folder previews load alongside the folder list, and the Runs page stops refreshing in the background while its tab is hidden, then catches up as soon as you return. The \"Triggered by\" filter on the Runs page now lists people who started runs in the last 90 days unless you pick a date range.\n\n### Public API\n\n- `GET /api/v1/agents` responds faster, including single-agent lookups with `?slug=`. The new optional `includeExampleCount=false` query parameter omits `stats.exampleCount` for callers that do not need it.\n- `GET /api/v1/runs` and `GET /api/v1/runs/:id` respond faster when runs belong to large workflows. Responses are unchanged.\n- Rate limits for requests made from a signed-in EigenPal dashboard session now count reads separately from writes, so browsing and live-refreshing pages no longer use up the allowance for starting runs. File downloads, artifact archives, traces, dataset and experiment exports, session transcripts, and run event streams still count toward the shared allowance. Limits for API key requests, including those from the CLI and SDKs, are unchanged.\n- When a signed-in session cannot be connected to an existing EigenPal account, API requests now return `403` with a message explaining how to get help, instead of a generic authentication or server error.\n\n---\n\n## 0.20.18 (2026-10-01)\n\n### Platform (Studio)\n\n- Downloaded API specs for a single workflow or agent now report that automation's own version instead of the platform release number, so upgrading Studio no longer looks like an API change to generated clients. The platform release is still included in the spec as `x-eigenpal-platform-version`. Self-hosted installs behind a proxy or OpenShift route also get the correct public server URL in the spec, and the spec no longer lists an unreachable server address when the public hostname cannot be determined.\n- Strengthen security protections for image generation, document previews, and telemetry transport.\n- Studio pages feel faster. Pages without a code editor or PDF preview load less up front, opening a workflow, agent, template, review queue, or developer page now shows a placeholder shaped like that page, and workflow links open the editor directly. On the Evals page, the side panels appear right away, changing the date range keeps the current results visible until the new ones arrive, and the runs list and overview no longer show each other's data. The agent editor keeps its files and instructions on screen while a conversation resumes, and opening a workflow folder link on a later page keeps that page.\n- Run details open faster. Selecting a run shows its name, status, and actions right away, and each section fills in on its own as it loads instead of the whole pane waiting on a skeleton. Inputs, outputs, and the step trace load side by side, long traces load their pages in parallel, and sections no longer go blank for a moment when a run finishes. Switching between the timeline and the raw trace reuses what is already loaded. Workflows, runs, and agents also start loading their details when you hover over or focus them in a list, so opening one feels quicker.\n- Pages load faster after signing in and when opening a link directly. Your organization is ready as soon as the page appears, so lists, agents, and run details start loading right away instead of waiting a moment first.\n- Usage: a new \"LLM usage by workflow\" table shows the tokens each workflow and agent consumed in the selected range, with run count, average tokens per run, cached input, and share of total, so teams can see which automations drive their LLM spend.\n\n---\n\n## 0.20.17 (2026-09-30)\n\n- Internal improvements.\n\n---\n\n## 0.20.16 (2026-09-29)\n\n### Platform (Studio)\n\n- Run reviews now preview input files with the same document viewer as dataset reviews. Multi-file runs get one-click previous/next switching with a position indicator, PDFs and images get full zoom controls, and the file picker lives in the viewer header instead of a separate bar. Field-evidence highlights and the approval workflow are unchanged.\n\n---\n\n## 0.20.15 (2026-09-29)\n\n- Internal improvements.\n\n---\n\n## 0.20.14 (2026-09-29)\n\n- Internal improvements.\n\n---\n\n## 0.20.13 (2026-09-29)\n\n### Platform (Studio)\n\n- Dataset reviews in Studio: filter the field queue to flagged-only (document order preserved), return to the Datasets list on close without pre-selecting the last automation, show the requester's note read-only above the reviewer note box, remove the approve-all-fields flow (untouched fields are assumed error-free), and rename user-facing Approve labels to Submit.\n- Apply security updates to sign-in, workflow execution and document processing.\n\n### CLI\n\n- Apply security updates to workflow validation dependencies.\n\n### Infrastructure & processing\n\n- Apply security updates to sign-in, workflow execution and document processing.\n\n---\n\n## 0.20.12 (2026-09-28)\n\n- Internal improvements.\n\n---\n\n## 0.20.11 (2026-09-25)\n\n### CLI\n\n- `eigenpal auth login` now opens the dashboard in your browser without routing the URL through a shell, so an unusual server address can never be interpreted as a command.\n\n---\n\n## 0.20.10 (2026-09-24)\n\n### Platform (Studio)\n\n- Studio model picker: add GPT 6 Sol, GPT 6 Luna, and Claude Opus 5.5 as selectable models for workflow steps and agents. The recommended list now surfaces the new generation; Opus 5 and the 5.6 Sol/Terra/Luna models remain available via search.\n- Dataset review: the fields queue now follows the output in document order. Flagged fields keep their highlight where they appear and removed fields stay in place with their removed styling, instead of being sorted to the top or bottom.\n\n---\n\n## 0.20.9 (2026-09-24)\n\n### Platform (Studio)\n\n- Reviews → Datasets: requesting a review is now fast even for many examples with large files — snapshotting downloads input files in parallel and no longer re-downloads them for the response. Reviews can also be cancelled (a frozen state like closed, reopenable back to open), and Studio lets reviewers close a review with undecided examples still in it: closing locks the review and only decided examples count as submitted.\n\n### Public API\n\n- Reviews → Datasets: requesting a review is now fast even for many examples with large files — snapshotting downloads input files in parallel and no longer re-downloads them for the response. Reviews can also be cancelled (a frozen state like closed, reopenable back to open), and Studio lets reviewers close a review with undecided examples still in it: closing locks the review and only decided examples count as submitted.\n\n### CLI\n\n- Reviews → Datasets: dataset review requests gain a `cancelled` lifecycle status. The CLI accepts `update --status cancelled` (and shows it in `list --status` filters), and the TypeScript/Python SDK status enums include the new value.\n\n### SDK\n\n- Reviews → Datasets: dataset review requests gain a `cancelled` lifecycle status. The CLI accepts `update --status cancelled` (and shows it in `list --status` filters), and the TypeScript/Python SDK status enums include the new value.\n\n---\n\n## 0.20.8 (2026-09-24)\n\n- Internal improvements.\n\n---\n\n## 0.20.7 (2026-09-24)\n\n### Platform (Studio)\n\n- Members: on self-hosted deployments with password sign-in, owners and admins can reset a member's password from Settings → Members. The admin sets a temporary password, the member is signed out on every device, and the next time they sign in they have to choose a new password before they can use the app.\n\n---\n\n## 0.20.6 (2026-09-24)\n\n### Platform (Studio)\n\n- Dataset review: add missing fields and line items without leaving the review, confirm object and array values, and approve every unreviewed field at once from the queue. Newly added fields now survive saves and refreshes until confirmed.\n- Reviews → Datasets: reviewers can open the dataset review inbox without workflow access. Studio loads the queue from `GET /api/v1/dataset-review-requests` (gated by `dataset_review:read`) instead of listing automations first, so reviewers see their requests rather than a permission error.\n\n### Public API\n\n- Reviews → Datasets: reviewers can open the dataset review inbox without workflow access. Studio loads the queue from `GET /api/v1/dataset-review-requests` (gated by `dataset_review:read`) instead of listing automations first, so reviewers see their requests rather than a permission error.\n\n### SDK\n\n- Reviews → Datasets: the TypeScript and Python SDKs expose the tenant-wide dataset review inbox as `client.datasetReviewRequests.list()` / `client.dataset_review_requests.list()`, with the same status filter and pagination as the Studio queue.\n\n### Infrastructure & processing\n\n- Document OCR stays up under rapid bursts of complex pages. The GPU inference server now uses smaller recognition batches and leaner memory allocation, so back-to-back multi-region documents no longer risk an out-of-memory restart — and the one-minute engine-failure alert from the last release still watches for any recurrence.\n\n---\n\n## 0.20.5 (2026-09-23)\n\n### Platform (Studio)\n\n- Dataset review now walks you to the finish: deciding an example advances to the next pending one and opens a completion sheet when nothing remains. The header shows an `n/m reviewed` pill that opens the same sheet, with Approved / Removed / Corrected counts, a Close review button (disabled until every example is decided), and the pull command for handing snapshots to an agent. The Resolve button stays green for pending, edited, and approved examples — only removed stays red.\n- Dataset review: text, spreadsheet, and other non-PDF input files now show the same header as PDFs and images, so reviewers can switch back to the other inputs from every file type.\n- Dataset review: clicking a field now reveals it in the Output JSON tree even when it sits inside a collapsed list item, scrolling it into view with its highlight.\n\n### Public API\n\n- Dataset review item decisions now use `removed` instead of `rejected` across progress counts, field/file decisions, and update actions. Callers that previously sent `action: \"reject\"` or `decision: \"rejected\"` should switch to `remove` / `removed`.\n\n### CLI\n\n- `eigenpal auth status` (alias `whoami`) shows the active profile, server URL, and whether the credential validates, with `--json` support for scripting.\n- `--json` output is now safe to pipe: status chatter stays off stderr so `2>&1 | jq` parses, and re-pushing identical YAML with `workflow push --file X --json` reports `\\{ unchanged: true }` instead of an error.\n- `eigenpal reviews` dataset-review actions and decisions now use `remove` / `removed` instead of `reject` / `rejected`, matching the public API rename.\n\n### SDK\n\n- Dataset review SDK types and helpers now expose `removed` instead of `rejected` for item status, progress, field/file decisions, and update actions.\n\n---\n\n## 0.20.4 (2026-09-23)\n\n- Internal improvements.\n\n---\n\n## 0.20.3 (2026-09-23)\n\n### Platform (Studio)\n\n- Expected-output files now review the same way fields do, on the right side of the dataset review panel: preview or edit text, Office, and spreadsheet files in place, upload corrected or brand-new versions, and record per-file approvals with notes. The review queue header lives in the breadcrumb bar with a status filter, so finished requests stay findable.\n\n### Public API\n\n- Dataset review items now cover expected-output files, not just fields: record per-file approve/reject decisions with notes, upload corrected bytes for an existing file or a brand-new one (50MB cap), and download the reviewer-corrected version with `kind=expected` on the item file endpoint. Closing a finished review still never auto-applies — reconcile corrected files into the live dataset by hand.\n- Dataset review file actions now accept the `expected/`-prefixed file path form (for example `expected/report/report.docx`) wherever a per-file decision or correction is recorded. It resolves to the same manifest-relative entry reviewers see, so paths copied from `$file` references in `expected.json` no longer fail with `unknown expected file`.\n\n### CLI\n\n- Expected-output files are first-class reviewable units: `pull --out &lt;dir&gt;` downloads per-example expected files (reviewer-corrected when the item has an overlay entry, else the snapshot) alongside `item.json`; `item --action edit-file` uploads corrected bytes (`--file-path` fixes an existing file, `--new-path` uploads a brand-new one, 50MB cap); `item --action file-decision` records per-file approve/reject with notes (`--comment` alone is a note and needs an existing decision); `get`/`items` show per-file decision summaries. Reconcile corrected files into the live dataset by hand — reviewers can err.\n\n### SDK\n\n- Expected-output files are covered too: items carry `currentExpectedFiles` (null means pristine snapshot) and `fileDecisions`; `getItemFile` / `get_item_file` accept `kind: 'expected'` to download reviewer-corrected bytes (default stays `input`); `recordItemFileDecision` / `record_item_file_decision` records per-file approve/reject or notes (`decision: null` clears); `editItemFile` / `edit_item_file` uploads corrected bytes for an existing path or a brand-new upload (50MB cap).\n\n---\n\n## 0.20.2 (2026-09-23)\n\n### Infrastructure & processing\n\n- Document OCR is now more resilient under heavy load. Back-to-back parsing bursts no longer risk taking the whole OCR fleet offline at once — jobs queue briefly and resume automatically — and monitoring catches GPU inference failures within a minute instead of several.\n\n---\n\n## 0.20.1 (2026-09-23)\n\n### Platform (Studio)\n\n- Credit limits now apply consistently across the product. Agent runs, the workflow builder assistant, and the expression generator are checked against your remaining balance before they start, and the assistant and expression generator now record their usage on your usage page instead of being invisible. A cancelled agent run is billed for the work it actually completed rather than dropping off your usage entirely. Organization creation is capped per account, both by how many you own at once and by how many you create over a rolling window, so one account cannot spin up unlimited free trials. A very long builder conversation is now refused with a message asking you to start a new chat, rather than being sent to the model in full. Deleting an organization now removes its stored files before the organization itself disappears. A large organization can take more than one pass, and the dialog now says accurately what happens: files are removed immediately and clear backups within 7 days.\n\n### Public API\n\n- Starting a run now returns `402 insufficient_credits` when your organization has spent its credit allowance. The check happens before the request body is read, so no files are uploaded and no work begins on a run that cannot be paid for. File uploads return the same status for the same reason, and both are now described in the API reference. The API reference also documents `503`, which endpoints return when request accounting is briefly unavailable. It means the request was not processed and is safe to retry; it is not a rate-limit rejection.\n\n---\n\n## 0.20.0 (2026-09-22)\n\n### Platform (Studio)\n\n- Datasets can now be sent for client review without exporting files. Create a review request from a dataset, highlight the fields that need attention, mark others as not required, and invite client teammates with the new reviewer role. They walk examples from a dropdown, inspect the fields, leave notes, record per-field decisions, and approve or reject each row. Closing a finished review does not auto-apply changes — reconcile expected outputs manually. The Reviews queue keeps finished requests visible with a status filter so old approvals stay findable. Reviewers see the same Studio shell with permission-aware empty states.\n\n### Public API\n\n- New dataset review endpoints under `/api/v1/automations/:id/dataset-review-requests`: create a review from dataset examples with reviewer `instructions`, `focusFields` (paths plus optional reasons), `ignoredFields` for paths reviewers can skip, and optional `itemNotes`. Approve, edit, reject, reopen, comment, or record a `field-decision` on each example (including clearing a decision with `decision: null`), then poll `progress.complete` and close the request with `PATCH` status. Dataset reconciliation stays manual — nothing is deleted by reject. A new `reviewer` organization role can read review queues and submit item decisions but cannot edit workflows.\n\n### CLI\n\n- `eigenpal workflow dataset review-request` (and the `eigenpal agents dataset` mirror) is the agent-friendly review loop: create a request with reviewer instructions, `--focus` / `--focus-reason` paths, `--ignore` paths reviewers can skip, and per-example `--item-note` / `--field-note` comments; `list`/`get`/`events` expose `progress.complete`, `fieldDecisions`, and `inputDrifted`; `item --action` records approve/reject/comment/edit plus per-field `field-decision` (clear with `--clear` / `--decision null`); `update --status closed` finishes the request. There is no auto-apply — pull and reconcile examples manually. Reject is recommendation-only; nothing is deleted.\n\n### SDK\n\n- `client.automations.datasetReviewRequests` (`dataset_review_requests` in Python) covers the full dataset review lifecycle: list and get with `progress`, `focusFields`, `ignoredFields`, `fieldDecisions`, and `inputDrifted`; create with reviewer instructions and per-field notes; update request metadata or close with status; update items including `field-decision` (pass `decision: null` to clear); and the per-user activity trail. Dataset write-back stays manual — there is no lock endpoint.\n\n### Infrastructure & processing\n\n- Replace the eagerly constructed `eigenpalAjv` singleton with a lazy `getEigenpalAjv()` accessor. Ajv compiles schemas with `new Function`, which the Studio Content-Security-Policy forbids — constructing at import time crashed every page whose client bundle transitively imported `@eigenpal/types` validation (including all review surfaces, which never validate client-side). Server-side call sites are unchanged apart from the accessor.\n\n---\n\n## 0.19.1 (2026-09-21)\n\n- Internal improvements.\n\n---\n\n## 0.19.0 (2026-09-21)\n\n### Platform (Studio)\n\n- Agent builder sessions can now be given storage credentials limited to their own session folder instead of the whole storage account. Set a Cloudflare account id and API token, or an AWS role, and each training sandbox receives a short-lived key that can only read and write its own files. Deployments that do not configure this keep working exactly as before and log a warning, and a new setting makes the platform refuse to start a sandbox unless scoped credentials are available.\n- Studio security hardening. Parsed document text shown in run traces and grounding views is now sanitized before rendering, so a crafted document can no longer inject active content into the page. Observability settings now require administrator access to view, and the values of any authorization headers you configure are masked once saved, so they are never sent back to the browser. Saving a renamed header now asks you to retype its value instead of quietly clearing the configuration. Outbound observability destinations are validated to reject internal and unencrypted endpoints on hosted plans. Editor assets are now served from Eigenpal's own domain instead of a public content network. Self-hosted deployments that use password sign-in no longer accept open self-registration. Creating the first account still works, and anyone holding an invitation can still create their account, but an uninvited visitor can no longer join an existing workspace. Set `EIGENPAL_ALLOW_OPEN_SIGNUP=true` to restore the previous behavior. Agent training and email trigger surfaces are now scoped more tightly. Email alias changes are accepted only through the agent that owns the alias, so editing or revoking one from a different agent's page now reports not found. Opening a training session that belongs to a different workspace or a different agent is refused instead of returning a server error. Each agent workspace now runs with credentials valid only for its own session, so a workspace can no longer act on any session but its own. Sign-in and account safety. Changing your password now signs out your other sessions, so a password change ends access from a device you no longer control. Accepting an invitation now requires the invitation link itself rather than just the invited address, so knowing that someone was invited is no longer enough to create an account in their name. Requests that arrive from another site are refused, which closes cross-site request forgery against pages you are signed in to. Set `EIGENPAL_TRUSTED_ORIGINS` if you serve Eigenpal on more than one hostname.\n\n### Public API\n\n- Agent endpoints that accept an agent id now resolve it strictly within the calling organization. Requesting an id belonging to another organization returns not found instead of reading or modifying it. Run and step endpoints apply the same organization check to execution ids. Uploads that omit a declared length are now measured while they stream and return 413 once they exceed the request limit, rather than being read into memory first. Operator source tokens are accepted only on the source and authentication check endpoints they are documented for. Webhook endpoints are now checked when you save them, not only when a delivery is attempted. A destination the platform cannot deliver to is rejected with a validation error at creation and update time, instead of being accepted and then failing silently on every send. Self-hosted deployments that deliver to their own internal network are unaffected. Every endpoint that starts a new run now honours the automation's trigger settings, the same way `POST /api/v1/runs` already did. That covers rerunning a run, starting an experiment, and running a single dataset example, including their streaming variants. An API key calling one of these on an automation whose API trigger is turned off now receives `403 api_trigger_disabled`, and a dashboard session calling one on an API-only automation receives `403 manual_trigger_disabled`. If an existing integration starts returning 403, turn the API trigger back on for that automation.\n- Self-hosted Prometheus scrapes now require the dedicated scrape token in every deployment. An organization API key is no longer enough to read the cluster snapshot. A deployment without `EIGENPAL_METRICS_SCRAPE_TOKEN` returns 404 on the metrics route, so set the token before upgrading if you scrape today with an API key. The headless workflow server no longer serves a network address without an API token. If you set `HOST` yourself, the server now exits at startup unless you also set `HEADLESS_API_TOKEN` or `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1`. If you never set `HOST`, the bind address changes from `0.0.0.0` to `127.0.0.1`, which inside a container means a published port stops accepting connections while the container still reports healthy. Either set `HEADLESS_API_TOKEN` (16 characters or more) together with `HOST=0.0.0.0`, or set `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1` to keep the previous behaviour. Members can no longer pull decrypted agent environment secrets. Use an owner or admin key, or decrypt a secret for a specific run.\n\n### Infrastructure & processing\n\n- Self-hosted Prometheus scrapes now require the dedicated scrape token in every deployment. An organization API key is no longer enough to read the cluster snapshot. A deployment without `EIGENPAL_METRICS_SCRAPE_TOKEN` returns 404 on the metrics route, so set the token before upgrading if you scrape today with an API key. The headless workflow server no longer serves a network address without an API token. If you set `HOST` yourself, the server now exits at startup unless you also set `HEADLESS_API_TOKEN` or `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1`. If you never set `HOST`, the bind address changes from `0.0.0.0` to `127.0.0.1`, which inside a container means a published port stops accepting connections while the container still reports healthy. Either set `HEADLESS_API_TOKEN` (16 characters or more) together with `HOST=0.0.0.0`, or set `HEADLESS_ALLOW_UNAUTHENTICATED_BIND=1` to keep the previous behaviour. Members can no longer pull decrypted agent environment secrets. Use an owner or admin key, or decrypt a secret for a specific run.\n- Document and archive processing is more resilient to malformed or hostile input. Dataset archive imports now apply a limit on entry count and hold far less memory while expanding, so a small archive can no longer exhaust a request. Office documents are checked against their real expanded size rather than the size recorded inside the file, which blocks highly compressed payloads that previously passed inspection. PDF page rendering moved to a newer engine that removes a document driven code execution path. Script transform steps have a shorter maximum run time that is now capped relative to worker health checks, so a long running script cannot stall other work. With stock settings the ceiling drops from 30 seconds to 15 seconds; self-hosted deployments that need more can raise `HEALTH_LIVENESS_STALE_MS`, since the ceiling is half that value. Workflow processing is more resilient to hostile input. Template rendering now has time and memory ceilings, so a crafted template can no longer stall a worker and delay other runs. Deep merges in the combine transform can no longer be steered into altering shared state. External file sources reject addresses that are not plain HTTP endpoints.\n\n---\n\n## 0.18.0 (2026-09-21)\n\n### Platform (Studio)\n\n- Workflows can crop normalized regions from PDFs and images into JPEG artifacts with the new `transform.crop-regions` step — pair it with parse output and script steps to build figure or layout evidence pipelines without a figure-specific step type. Turn on optional **`cache: true`** on **`ai.parse`** to reuse prior parse output for the same file bytes and parse settings across runs (stored in tenant blob storage; no expiry yet).\n\n---\n\n## 0.17.5 (2026-09-21)\n\n### Platform (Studio)\n\n- Summary Agent: spreadsheet uploads now use a hardened parser that prevents crafted workbook content from causing excessive processing or modifying object prototypes.\n\n### CLI\n\n- CLI skill reference documents the new `ai.figure-crops` workflow step for cropping and captioning figures from parsed PDFs.\n\n### SDK\n\n- Python SDK: installs now require `anyio` 4.14.2 or newer. Earlier versions encoded host names with IDNA 2003 when opening a TLS connection, so a crafted host name could be matched against the wrong certificate. The TypeScript SDK is unaffected.\n\n---\n\n## 0.17.4 (2026-09-18)\n\n### Platform (Studio)\n\n- Strengthen organization access controls so role permissions, API-key scopes, and member removal apply consistently across Studio and the API. Webhook configuration and signing secrets are restricted to organization owners and admins. Service credentials cannot exceed member permissions, while members retain file and review editing through the API.\n- Organization owners can invite new users directly as owners. Owner invitations can only be created and managed by existing owners.\n\n### Public API\n\n- Strengthen organization access controls so role permissions, API-key scopes, and member removal apply consistently across Studio and the API. Webhook configuration and signing secrets are restricted to organization owners and admins. Service credentials cannot exceed member permissions, while members retain file and review editing through the API.\n\n### Infrastructure & processing\n\n- Cloud workflow HTTP and website-reader actions now restrict requests to public HTTP/S destinations, verify TLS for HTTPS requests, and reject HTTPS-to-HTTP redirects. Responses are limited to 20 MiB and requests to 120 seconds. Single-tenant installations retain private-network integration support.\n\n---\n\n## 0.17.3 (2026-09-18)\n\n### Public API\n\n- Large PDF parses are now more reliable under parallel load. The OCR service paces concurrent pages per document so multi-page jobs no longer exhaust inference memory and retry, which previously stalled big documents behind repeated restarts.\n\n---\n\n## 0.17.2 (2026-09-17)\n\n### Platform (Studio)\n\n- Settings gains a Data retention section for workspace admins: see how much file storage past and present runs consume, choose how long eval and other runs are kept, preview what falls past the horizon, and delete those runs in capped passes until clear. Runs that are still active are always kept. Enforcement offers two modes: purge input files only (run history and outputs stay, freeing the bulky source documents while keeping the audit trail) or delete full runs. Storage usage splits run inputs from outputs so admins can see what input-only cleanup would free.\n\n### Public API\n\n- Rerunning a run whose input files were removed by data retention now returns a clear `409 inputs-purged` error instead of failing while copying the missing files. Run history and outputs remain available.\n\n---\n\n## 0.17.1 (2026-09-15)\n\n- Internal improvements.\n\n---\n\n## 0.17.0 (2026-09-15)\n\n### Platform (Studio)\n\n- Studio can connect to a live agent inference session even when that session runs in a local sandbox instead of the hosted cloud environment.\n\n### Infrastructure & processing\n\n- Agent inference can now run in a local container sandbox, so on-prem and air-gapped deployments no longer need a cloud sandbox provider.\n- Agent runs can now execute in customer-hosted sandbox environments instead of only the Eigenpal cloud, and local Docker sandboxes connect reliably on plain localhost setups.\n\n---\n\n## 0.16.13 (2026-09-14)\n\n- Internal improvements.\n\n---\n\n## 0.16.12 (2026-09-14)\n\n### Platform (Studio)\n\n- Studio can import large dataset ZIP archives without taking the app down, including archives whose paths use Windows-style backslashes. Opening a long-running workflow no longer pulls every step’s full input and output at once. Run pages stay available, still show the steps timeline when phase data is missing, and keep the last loaded view if a refresh fails — with a retry control instead of a blank error page.\n\n### Public API\n\n- `GET /api/v1/runs/\\{id}?expand=execution` and `GET /api/v1/runs/\\{id}/steps` now return slim step rows (identity, status, timing, and a capped error excerpt) instead of inlining every step’s input and output. Inspect one step’s full payloads with the new `GET /api/v1/runs/\\{id}/steps/\\{stepExecutionId}` endpoint.\n\n### CLI\n\n- `eigenpal runs get` lists slim step rows by default. Pass `--include input,output` or `--step` to fetch full payloads for the steps you care about.\n\n### SDK\n\n- The TypeScript and Python SDKs now include `GET /api/v1/runs/\\{id}/steps/\\{stepExecutionId}` so you can load one step’s full input and output after listing slim run steps.\n\n---\n\n## 0.16.11 (2026-09-11)\n\n### Platform (Studio)\n\n- Studio: organization switching and other labeled menus now open reliably without a client-side error.\n\n---\n\n## 0.16.10 (2026-09-10)\n\n### Infrastructure & processing\n\n- OCR processing now distinguishes temporary host availability issues from true processing timeouts, keeps redundant production capacity warm, and pages only when unfinished work is affected. Short self-healing interruptions remain visible for diagnosis without generating misleading recovery alerts.\n\n---\n\n## 0.16.9 (2026-09-10)\n\n### Platform (Studio)\n\n- Harden web image handling, document image processing, and email delivery against crafted inputs that could cause remote code execution, excessive resource use, or recipient-validation bypasses.\n\n### Infrastructure & processing\n\n- Harden web image handling, document image processing, and email delivery against crafted inputs that could cause remote code execution, excessive resource use, or recipient-validation bypasses.\n\n---\n\n## 0.16.8 (2026-09-10)\n\n### Platform (Studio)\n\n- Files are easier to recognize throughout Studio with refreshed Office logos, dedicated PDF, archive, text, JSON, and code treatments, plus image thumbnails. File inputs now use a clearer rounded drag-and-drop experience with consistent selected-file previews.\n\n---\n\n## 0.16.7 (2026-09-10)\n\n### Platform (Studio)\n\n- File uploads now infer supported document media types from the filename when clients provide an empty or generic content type, allowing original Outlook messages and macro-enabled workbooks to upload without conversion.\n\n### Public API\n\n- File uploads now infer supported document media types from the filename when clients provide an empty or generic content type, allowing original Outlook messages and macro-enabled workbooks to upload without conversion.\n\n### CLI\n\n- The CLI now uploads macro-enabled Excel workbooks with the correct media type, so original `.xlsm` workflow inputs work without manual conversion.\n\n### SDK\n\n- TypeScript SDK file helpers now infer the correct media types for `.xlsm` workbooks and `.msg` Outlook messages.\n\n### Infrastructure & processing\n\n- Document parsing now reads Excel, legacy Excel, and macro-enabled workbooks directly, preserving every non-empty sheet and its cell evidence without executing formulas or macros. Large single-page extractions are also split into bounded AI context windows instead of failing at the model limit.\n\n---\n\n## 0.16.6 (2026-09-09)\n\n### Infrastructure & processing\n\n- Template processing now enforces memory limits when joining large collections, preventing crafted templates from exhausting worker memory.\n\n---\n\n## 0.16.5 (2026-09-08)\n\n### Platform (Studio)\n\n- Human review is now available in production, including workflow authoring and review queues.\n\n### Public API\n\n- Human review API endpoints are now available in every production organization for listing tasks, confirming fields, and completing reviews.\n\n### Infrastructure & processing\n\n- Workflow and agent runs can now request human review in every production organization.\n\n---\n\n## 0.16.4 (2026-09-08)\n\n### Platform (Studio)\n\n- Studio adds List Archive and Extract Archive File steps for ZIP workflow inputs. Enumerate archive contents, wire `\\{\\{ item.path }}` through foreach, and pass extracted files straight into Parse, Vision, or Search Files without leaving the builder.\n- Studio now finishes multi-GB file uploads with resumable multipart transfers, retrying individual parts without restarting the whole file.\n- Studio workflows now include Search Files: ask a question about a ZIP archive and get a cited answer plus the files the step inspected. Scope the search to a folder inside the archive and use the same model and reasoning controls as other AI steps.\n\n### Public API\n\n- Upload ZIP archives as reusable workflow inputs through the Files API. Archives can be much larger than single documents, so teams can pass bundled evidence, exports, or multi-file drops into the same runs that already accept PDFs and Office files.\n- File uploads can now negotiate a resumable multipart session for multi-GB objects, with on-demand part URLs, authoritative resume listing, and safe completion that never overwrites a finished file.\n- Starting a run from a reusable file id now keeps a private run-owned reference to the original bytes instead of duplicating large uploads. Deleting the reusable file leaves past runs readable until those runs themselves are deleted.\n\n### CLI\n\n- Dataset import and export now keep a single `/api/v1` prefix when the CLI base URL already includes `/api/v1`, so those commands reach the dataset API instead of a doubled `/v1/v1` path.\n- The CLI now uploads large run files with resumable, storage-direct transfers, so multi-GB inputs stream from disk instead of loading into memory or a single request.\n- The CLI now recognizes `.zip` files when uploading reusable workflow inputs, so archive uploads get the correct content type without extra flags.\n\n### SDK\n\n[View full release notes →](/releases/0.16.4)\n\n---\n\n## 0.16.3 (2026-09-08)\n\n### Platform (Studio)\n\n- Human review: open pending reviews directly from run details and confirm unchanged fields inline from the field list.\n\n### Public API\n\n- Human review field confirmations now preserve valid JSON `null` values and return clear validation errors when a reviewed value does not match its schema.\n\n---\n\n## 0.16.2 (2026-09-08)\n\n### Platform (Studio)\n\n- Human review: pause workflows and agents only when selected fields need attention, inspect source files beside structured output with spatial citation highlights when lineage is available, correct and confirm values, then approve the same run to continue. Confidence thresholds, explicit field selection, required-field progress, rejection, and cancellation keep exception review focused instead of forcing teams to recheck every field.\n\n### Public API\n\n- Human review APIs now list pending tasks, return review data and source-file references, persist field corrections and confirmations, and approve or reject paused runs with optimistic concurrency protection. Task detail may also include resolved lineage and parsed-document context when an upstream grounded extract produced sidecars.\n\n### CLI\n\n- Workflow authoring now includes human-review guidance and ready-to-use templates for confidence-based exception review and explicit approval of critical fields.\n\n### SDK\n\n- TypeScript and Python SDKs now expose human-review resources for listing and retrieving tasks, confirming corrected fields, downloading attached source files, and approving or rejecting paused runs.\n\n### Infrastructure & processing\n\n- Grounded extraction now runs the same shared algorithm locally when a parse step supplies a valid structured document and your provider supports strict structured output. Step JSON stays schema-shaped with `_grounding` metadata; lineage and the parsed document graph are stored as optional sidecars for review and audit, not mixed into workflow output. Text-only inputs and unsupported providers continue to use the existing text grounding path with clear degraded markers when the shared path is unavailable.\n\n---\n\n## 0.16.1 (2026-09-07)\n\n### Platform (Studio)\n\n- GPT-6 Astra is available across workflows, agents, evaluations, and vision tasks, with configurable reasoning and current token pricing.\n- Self-hosted PaddleOCR models now appear with clear provider identity in Studio model selectors and settings.\n- Archive imports now reject malformed ZIP64 data safely instead of risking an unbounded processing loop.\n\n### CLI\n\n- CLI archive handling now rejects malformed ZIP64 data safely instead of risking an unbounded processing loop.\n\n### Infrastructure & processing\n\n- GPT-6 Astra is available across workflows, agents, evaluations, and vision tasks, with configurable reasoning and current token pricing.\n- Self-hosted deployments can connect directly to PaddleOCR-VL for high-quality document parsing, with bounded concurrency and long-running PDF support built in.\n\n---\n\n## 0.16.0 (2026-09-07)\n\n### Platform (Studio)\n\n- Agent model pickers are now compact, searchable, grouped by provider, and ordered from the most capable model to the least without changing configured defaults.\n- Send Email is now a first-class workflow action. Add Resend or SMTP servers in Settings → Email servers, then pick a stable `ems_…` server on the step — including generated files from the same run as attachments. Cloud and on-prem share this Settings surface; there is no default server. Secrets stay encrypted, and reads never show credentials. Changing an SMTP host, username, or provider asks you to re-enter the password so a stored secret cannot follow a new destination.\n\n### Public API\n\n- The public API now manages organization email servers at `/v1/email-servers`: list, create, inspect, update, delete, and send a connectivity test. Each server is an `ems_…` resource with a Resend or SMTP transport. Secrets are encrypted and never returned; disabled servers reject tests, and names must be unique among live servers. Updating SMTP to a different host or username requires a new password or explicitly clearing authentication — the previous password is never reused against a new destination.\n\n### CLI\n\n- Manage organization email servers with `eigenpal email-servers`: list and inspect `ems_…` servers, create or update Resend and SMTP providers (including an optional SMTP CA PEM), delete servers, and send a live test message with `--to`. Secrets are read from stdin, a file, or a secure prompt — never from command-line flags.\n\n### SDK\n\n- TypeScript and Python SDKs now manage organization email servers: list, create, inspect, update, delete, and send a connectivity test. Stored credentials are never returned.\n\n### Infrastructure & processing\n\n- Send Email delivers through the organization server selected on the step. There is no fallback: a missing, deleted, or disabled server fails the run. Evaluation runs skip delivery, including workflows invoked from an eval. Cancelling a run aborts an in-flight send. Multi-tenant SMTP servers must resolve to public addresses, while single-tenant deployments can use internal relays. Partial SMTP acceptance reports which recipients were delivered or rejected so operators can avoid duplicate reruns. SMTP may still deliver twice if a worker stops after the relay accepts the message; Resend deduplicates the same step attempt.\n\n---\n\n## 0.15.1 (2026-09-04)\n\n### Infrastructure & processing\n\n- OpenParser OCR capacity now recovers cleanly after failed updates, avoiding unnecessary warm resources while preserving active document processing.\n\n---\n\n## 0.15.0 (2026-09-04)\n\n### Platform (Studio)\n\n- Workflow validation now explains when a catalog model belongs in `provider` instead of the raw `model` override, and reruns preserve clean original filenames in generated outputs and citations.\n- Make document inputs uploaded in Studio datasets available to experiment runs, including examples saved by earlier releases.\n\n### Public API\n\n- Experiment result responses and JSON exports now include evaluator-specific structured details, so clients can identify the exact JSON path, expected value, and actual value behind a failed comparison. CSV exports retain their existing stable columns.\n\n### CLI\n\n- Experiment analysis is now built into the CLI for workflows and agents: summarize pass, fail, error, and score totals; filter failures by evaluator; inspect structured discrepancy paths; and compare actual outputs between batches. Run payloads can be projected with `--select`, and repository-level validation discovers nested workflow projects automatically. Polling commands also expose consistent wait limits and reject flag combinations that cannot produce a reliable verdict. Waiting commands now keep human output concise by default; pass `--json` whenever scripts need the terminal payload.\n- `eigenpal docs` now lists, searches, and reads the complete release-matched platform documentation offline, including detailed evaluator syntax, workflow step guides, CLI reference, and the OpenAPI contract.\n- CLI file uploads now send valid content types for Outlook and unknown files, cancellation confirms the asynchronous request clearly, and run comparisons show every repeated workflow step by branch and iteration path.\n\n### Infrastructure & processing\n\n- Make document inputs uploaded in Studio datasets available to experiment runs, including examples saved by earlier releases.\n- Exact-diff evaluators can exclude volatile fields with `ignore: true`, including nested fields inside a selected object or array. This keeps golden outputs readable while scoring only stable business data such as identities, names, and classifications.\n- Script steps now bind inputs by parameter name, so workflows behave consistently after storage even when JSON key order differs from the authored YAML.\n\n[View full release notes →](/releases/0.15.0)\n\n---\n\n## 0.14.3 (2026-09-04)\n\n### Platform (Studio)\n\n- Model selection now includes the GPT 5.6 Sol, Terra, and Luna lineup plus Claude Fable 5, Fable 5.1, Opus 5, and Sonnet 5. Reasoning effort can be configured for supported workflow steps, agent training and runs, workflow-building chat, and LLM judges; existing choices keep their current provider defaults when the setting is omitted.\n\n### CLI\n\n- Workflow YAML can configure model-aware reasoning effort on AI steps and LLM judges. Omit the setting to preserve each model's current default.\n\n### Infrastructure & processing\n\n- AI processing supports the latest GPT and Claude request formats, including reliable structured extraction with Claude Fable 5 and Fable 5.1. Workflow and agent execution can pass an optional model-aware reasoning effort while preserving previous defaults, and agent sandboxes can use GPT 5.6, Claude Fable 5, Fable 5.1, Opus 5, and Sonnet 5.\n\n---\n\n## 0.14.2 (2026-09-02)\n\n### Infrastructure & processing\n\n- Single-node deployments can now upgrade installations with large legacy datasets without startup failures or loss of trigger configuration.\n\n---\n\n## 0.14.1 (2026-09-02)\n\n### Infrastructure & processing\n\n- Single-node deployments can now upgrade installations with legacy run review data without startup failures.\n\n---\n\n## 0.14.0 (2026-09-02)\n\nThis release gives document teams more control over structured-data quality.\nExact-diff evaluators can express field-specific matching rules, PDF parsing can\npreserve visual layout, and spreadsheet conversion can retain the rows, columns,\nand displayed values that matter to downstream workflows.\n\nCLI authoring guidance makes these capabilities easier to discover and safer to\nautomate, with non-interactive commands failing clearly instead of waiting on\nunavailable prompts.\n\n### Platform (Studio)\n\n- `ai.parse` adds `outputFormat: layout` for native PDF extraction. It returns fixed-width plain text that preserves columns, spacing, and line breaks for multi-column forms and tables that lose meaning when flattened. This PDF-only format must be selected explicitly with `parseMode: native` or `parseMode: native-or-ocr`: native mode fails closed if layout extraction cannot complete, while hybrid mode keeps accepted layout pages and substitutes OCR markdown only for suspect or empty pages. Existing formats and defaults are unchanged.\n- Spreadsheet to JSON now handles `.xls` and `.xlsx` workbooks with configurable headerless input or an explicit header row, named or positional column projection, rectangular ranges, and raw or displayed cell values. Displayed values preserve formatted text such as dates, leading zeros, punctuation, diacritics, and embedded newlines. Blank-cell and blank-row policies make sparse sheets predictable, while optional sheet metadata and diagnostics explain the selected range and non-fatal issues. Existing zero-config output remains `rows`, plus `fileId` when CSV output is enabled; zero-config CSV keeps the full selected sheet, and configured CSV follows the same projection. File, row, column, and cell limits reject unsafe workloads before conversion.\n- Exact-diff evaluators add composable per-field rules for extraction outputs. Choose ordered or unordered comparison independently from `items: at-least | at-most | exactly`, set numeric tolerances, and reject unexpected object fields where strict output shapes matter. Ordered arrays retain prefix-compatible matching, while unordered arrays find the best one-to-one structural pairing instead of depending on row order. Unordered object arrays can also use typed `matchBy` identities such as `sku` or `[country, sku]` for predictable single- or composite-key matching. Studio now provides a rule editor with path-aware validation. Grounding metadata is excluded from scoring, oversized comparison workloads fail safely with bounded diagnostics, and existing evaluator configurations keep their historical behavior.\n\n### Public API\n\n- Template creation now accepts reusable file references correctly, restoring CLI template uploads and workflow pushes that use local DOCX or XLSX files.\n\n### CLI\n\n[View full release notes →](/releases/0.14.0)\n\n---\n\n## 0.13.2 (2026-09-01)\n\n### CLI\n\n- CLI installation no longer downloads packages already included in its self-contained executable, reducing install overhead and improving compatibility with restricted enterprise networks.\n\n---\n\n## 0.13.1 (2026-08-31)\n\n### Platform (Studio)\n\n- Workflows can turn JSON rows into a downloadable Excel workbook with a new JSON to XLSX step. Pick ordered columns, map an array of objects, and get a `.xlsx` run output — including multi-sheet workbooks — without filling a template.\n- Studio now uses the shared theme provider, so system / light / dark stays aligned with OpenParser instead of drifting independently.\n- Publishing a workflow that still has a local `template: ./file.xlsx` path now fails with a clear error. Use `eigenpal workflow push` to upload the file, or set `templateId` to a `tmpl_…` id first.\n- Studio template uploads and replacements now create immutable, checksum-backed revisions and discover tokens consistently across DOCX and XLSX files. Deleting a logical template preserves revision content used by pinned workflows.\n- Fill Template (`transform.template`) now documents workspace `tmpl_...` templates separately from Git agent templates, and Studio copy covers DOCX and XLSX. XLSX files use `\\{placeholder}` and `\\{table:array.prop}` in the spreadsheet; `\\{\\{placeholder}}` in an uploaded sheet warns on upload and fails at fill instead of leaving leftover braces. `templateId` must be a workspace `tmpl_...` ID, not a file ID. Filled values that look like formulas stay text; formulas already in the template stay formulas.\n- Studio now blocks crafted HTML from retaining executable content during sanitization.\n\n### Public API\n\n- Workflow push can fully remove a template it uploaded if publishing then fails. Deleting a template that workflows already pin still keeps those revisions runnable.\n- The public API now lists the text, vision, and OCR models configured for your environment. `GET /v1/models` is a cheap catalog inventory for the current tenant: it reports whether each model is configured and which capability it is the default for, without probing live providers or exposing secrets.\n- The public API now supports the full lifecycle for tenant-scoped DOCX and XLSX templates: upload, inspect, list, download, replace, and delete, with direct-upload support for larger files. Every replacement creates a checksum-backed immutable revision; deleting the logical `tmpl_…` resource preserves revisions already pinned by workflows.\n\n### CLI\n\n- `workflow versions create --file` now resolves local `template:` paths the same way as `workflow push`, and `workflow templates smoke --data` help documents the JSON fixture file path.\n- `eigenpal workflow push` keeps local Office templates inside the workflow project, including when a path uses `../` or a symlink. Files outside that directory need `--allow-external-templates`. Push validates the workflow and version before uploading, creates new template resources instead of moving shared `tmpl_…` pointers, and fully removes those unpublished uploads if publish does not succeed.\n- When resolving a workflow by `wf_…` id, connection failures, auth errors, and server outages now surface their normal CLI messages instead of being misreported as \"workflow not found.\"\n\n[View full release notes →](/releases/0.13.1)\n\n---\n\n## 0.13.0 (2026-08-25)\n\n### Platform (Studio)\n\n- API reference for listing dataset examples now documents `include=metadata`, so you can page through example ids, names, and file refs without loading every payload.\n- Local Studio development no longer keeps a growing on-disk compiler cache that can exhaust memory during long `bun dev` sessions.\n- Studio's sidebar theme picker now supports keyboard navigation across system, light, and dark.\n- Studio dashboard sessions continue to authenticate `/api/v1` calls. Token-based `/api/v1` and `/v1` requests still work without a browser login, and the dedicated API hostname keeps its public routing and CORS behavior.\n- Studio save-as-release still publishes a tagged version as the live workflow. Publishing from an existing snapshot creates a new tagged release instead of rewriting the original tag, so earlier releases stay intact. Connect API docs version pickers follow the public version list, so after restore the current untagged version shows as latest while tagged releases stay selectable.\n\n### Public API\n\n- List dataset examples without pulling every payload. `GET /api/v1/automations/:id/examples` now accepts `include=metadata`, which returns ids, names, annotations, and expected file refs while leaving input and expected JSON unloaded. Keep the default `include=full` when you still need the complete example bodies.\n- You can now create, promote, and restore workflow versions through the public API. Create a tagged candidate with `activate: false` to test it without changing live traffic, then promote that exact version after it qualifies. You can also publish from YAML, copy an existing version into a new release without changing its original tag, or restore an earlier snapshot. Name-conflict errors include `conflictingWorkflowId` so you can see which workflow already owns the name.\n\n### CLI\n\n- `eigenpal workflow versions` can now create, promote, and restore YAML workflow versions through the public API. Tag a candidate from a YAML file or an existing snapshot with an explicit semver, keep it off live traffic with `--no-activate`, then promote that exact version when it qualifies. Restoring still rolls a workflow back by copying a snapshot into a new current version — lists now show that untagged HEAD clearly instead of hiding it. `workflow versions list --limit` and `--offset` page that full public list locally. `--json` prints the sliced `\\{ data, total, limit, offset }` envelope (`total` is the unsliced count), not the raw server payload.\n\n### SDK\n\n- TypeScript and Python SDKs can list dataset examples with `include: \"metadata\"`. That returns ids, names, annotations, and expected file refs without loading each example's input and expected JSON. The default remains a full payload, so existing list calls stay unchanged.\n\n[View full release notes →](/releases/0.13.0)\n\n---\n\n## 0.12.2 (2026-08-21)\n\n### Platform (Studio)\n\n- Document editing: the DOCX editor used for templates, run file review, and Office file previews now follows your light or dark theme, and Save (including Cmd/Ctrl+S) writes back to the document you opened instead of downloading a copy. Documents that fail to open now report the reason instead of showing an empty editor. Placeholder highlighting in DOCX templates is temporarily unavailable.\n- Connect: a workflow that wraps another workflow now documents the full response shape. Its OpenAPI spec, Swagger UI preview, and the response examples and generated types on the Connect page show the nested objects and arrays returned by the workflow it calls, instead of leaving those fields untyped.\n\n---\n\n## 0.12.1 (2026-08-19)\n\n### Platform (Studio)\n\n- Connect: download an OpenAPI spec (swagger.json) and preview it in Swagger UI directly from the Connect page. Selecting a workflow or agent produces a spec for just that automation: the five endpoints needed to integrate it (start a run, poll it, cancel it, list and download artifacts), with the request body documenting its exact input fields and file uploads and run responses typed with its actual output schema. With no selection you get the full platform API spec. Swagger UI is bundled with the product, so the preview also works in on-prem installs without internet access.\n\n---\n\n## 0.12.0 (2026-08-18)\n\n### Platform (Studio)\n\n- The workflow builder chat honors the new `disableTemperature: true` model configuration option, so models that reject a sampling temperature work from the first request.\n- Object-typed workflow inputs can now declare a nested schema. In the workflow builder, choosing the Object type (or an array of objects) opens a property editor where you define each field with its type, description, allowed enum values, and required flag, including nested objects and arrays up to five levels deep. Declared fields are enforced when a run starts: missing required fields and type mismatches are rejected with precise field paths. Downstream steps get full autocomplete and type resolution for nested references such as `\\{\\{ input.metadata.vendor.name }}`, and the declared shape appears in the scope browser and in generated API documentation. The builder flags expressions that reference undeclared nested fields, the run form and evaluation input editor pre-fill the declared required fields, and the AI expression generator sees the nested shape when suggesting expressions. The headless execution server now enforces declared inputs with the same validator, so its API documentation and runtime behavior agree.\n- Grounded OpenParser extraction results can now carry complete field lineage through the Eigenpal web runtime, preserving source evidence and confidence metadata for downstream review experiences.\n\n### Public API\n\n- Object-typed workflow inputs can now declare a nested schema. In the workflow builder, choosing the Object type (or an array of objects) opens a property editor where you define each field with its type, description, allowed enum values, and required flag, including nested objects and arrays up to five levels deep. Declared fields are enforced when a run starts: missing required fields and type mismatches are rejected with precise field paths. Downstream steps get full autocomplete and type resolution for nested references such as `\\{\\{ input.metadata.vendor.name }}`, and the declared shape appears in the scope browser and in generated API documentation. The builder flags expressions that reference undeclared nested fields, the run form and evaluation input editor pre-fill the declared required fields, and the AI expression generator sees the nested shape when suggesting expressions. The headless execution server now enforces declared inputs with the same validator, so its API documentation and runtime behavior agree.\n- Listing runs with `sinceLastClosed=true` works again. Once a review had been closed, asking for the runs recorded since then returned an error instead of the runs, so review tooling that polls for new work had no way to ask \"what has arrived since I last signed off\". The filter now returns those runs.\n\n### Infrastructure & processing\n\n- Model entries in the deployment configuration can now set `disableTemperature: true`. Workflow steps then never send a sampling temperature to that model, which lets reasoning models (and gateways in front of them) that reject the parameter run without a first-call retry.\n- Object-typed workflow inputs can now declare a nested schema. In the workflow builder, choosing the Object type (or an array of objects) opens a property editor where you define each field with its type, description, allowed enum values, and required flag, including nested objects and arrays up to five levels deep. Declared fields are enforced when a run starts: missing required fields and type mismatches are rejected with precise field paths. Downstream steps get full autocomplete and type resolution for nested references such as `\\{\\{ input.metadata.vendor.name }}`, and the declared shape appears in the scope browser and in generated API documentation. The builder flags expressions that reference undeclared nested fields, the run form and evaluation input editor pre-fill the declared required fields, and the AI expression generator sees the nested shape when suggesting expressions. The headless execution server now enforces declared inputs with the same validator, so its API documentation and runtime behavior agree.\n\n---\n\n## 0.11.3 (2026-08-13)\n\n### Platform (Studio)\n\n- API reference pages for starting and reading runs now show complete examples, including `output` and `execution.status`.\n\n### Public API\n\n- Run API: completed-run examples now include `type`, `execution.status`, `output`, `files`, and `error`, instead of a shared async/completed union that dropped those fields. Default GET and list responses populate `execution.retry.nextRun` when a retry exists, and `expand=execution` keeps `schemaValid` instead of clearing it. Child invoke-workflow runs document `parentExecutionId` and `childExecutions`.\n\n### SDK\n\n- Generated run types now distinguish a completed run from the async accepted envelope (`RunAccepted`), and include `parentExecutionId` for child invoke-workflow runs.\n\n---\n\n## 0.11.2 (2026-08-07)\n\n- Internal improvements.\n\n---\n\n## 0.11.1 (2026-08-07)\n\n### Platform (Studio)\n\n- Document and image processing now runs on updated imaging components that carry upstream security fixes.\n\n### Infrastructure & processing\n\n- Document and image processing now runs on updated imaging components that carry upstream security fixes.\n\n---\n\n## 0.11.0 (2026-08-06)\n\n### Platform (Studio)\n\n- Workflow builder chat now works with reasoning models served through a self-hosted `openai-compatible` gateway, instead of failing with a \"temperature is not supported\" error. On models that only accept their own default temperature setting, replies can vary between attempts on the same question.\n- Canonical API hostnames now consistently expose only supported API and operational routes, returning a clear 404 for unsupported discovery paths.\n- Agent Builder attachments now negotiate multipart or storage-direct transfer, so large PDFs and archives can reach the active sandbox without crossing cloud payload limits. Large downloads use the same secure dual path. Self-hosted operators can set `deployment.multipartMaxBytes` in `eigenpal.config.yaml`; the supplied on-prem deployments keep files on multipart and streamed downloads by default.\n- Canonical API hostnames now serve API routes and discovery endpoints reliably without Studio sign-in handling intercepting requests.\n\n### Public API\n\n- Upload and download reusable files up to 100 MiB through one negotiated API: files within the deployment body limit use multipart, while larger cloud transfers use verified storage-direct uploads and short-lived authenticated download links. Retry-safe temporary run and Builder files expire after 24 hours. Existing multipart routes and `studio.eigenpal.com/api/v1` remain compatible, and new integrations can use `api.eigenpal.com/v1`.\n\n### CLI\n\n- The CLI now uses `api.eigenpal.com` as the default cloud API origin and automatically pre-uploads run files that exceed the multipart request limit. Self-hosted users can keep custom API origins and set `EIGENPAL_MULTIPART_MAX_BYTES` to their proxy limit, or `none` to keep all files on multipart.\n\n### SDK\n\n- The TypeScript and Python SDKs now transparently upload large run inputs without crossing cloud request limits, follow secure storage-direct downloads, and default cloud calls to `api.eigenpal.com`. Set `multipartMaxBytes` / `multipart_max_bytes`, or `EIGENPAL_MULTIPART_MAX_BYTES`, to match a self-hosted proxy; use `null` / `None` to keep every run file on multipart. Explicit `files.upload` files remain reusable until deleted.\n- TypeScript file uploads now follow the server-negotiated multipart endpoint, improving compatibility across hosted and self-managed route layouts.\n\n[View full release notes →](/releases/0.11.0)\n\n---\n\n## 0.10.56 (2026-08-05)\n\n### Platform (Studio)\n\n- Agent Builder training chat now shows Pierre file diffs for edit/write, a Pierre syntax-highlighted file view for Read file, secure request-secret password cards (encrypted into the draft; the agent only sees configured/skipped), and a quiet timeline note when you release an agent version from the dashboard.\n\n### Infrastructure & processing\n\n- Production releases that do not change document processing finish faster by reusing verified OCR provider checks from the last successful release, while still re-checking providers when processing code or infrastructure changes.\n\n---\n\n## 0.10.55 (2026-08-05)\n\n### Platform (Studio)\n\n- Agent Builder now resumes your latest draft, clearly distinguishes unsaved edits from saved changes that are not live, and provides direct Save and Release actions. Releases show the current and next version and let you choose a patch, minor, or major update. Dashboard save and release actions remain available to the builder as private context, so it can accurately answer what is live without guessing. Starting a separate draft is explicit, attachments remain available when beginning a conversation, stopped sandboxes can be restarted without losing the draft, and test runs reliably receive JSON-only inputs.\n\n### Public API\n\n- Agent Builder releases now complete live automation synchronization reliably, so a successful release is immediately available without a separate recovery step.\n\n### Infrastructure & processing\n\n- OCR and LLM model catalogs keep loading when the service adds new optional fields, so Studio and Eigenpal no longer fall back to stale model lists during catalog updates.\n- Cloud document processing providers that are already available stay online during routine production updates when their identity is unchanged. New or changed providers stay unavailable until they pass live verification, so customers keep working providers instead of a full outage window.\n\n---\n\n## 0.10.54 (2026-08-04)\n\n### Platform (Studio)\n\n- Workflow Studio now shows each OpenParser OCR model with its actual provider logo, keeps narrow step configuration panels contained, and places settings, theme, and sidebar controls together in a cleaner navigation footer.\n\n---\n\n## 0.10.53 (2026-08-04)\n\n### Platform (Studio)\n\n- OpenParser Studio now visualizes the `openparser@1` document graph directly, including typed elements, figures, tables, relationships, and element-level extraction citations.\n\n### Public API\n\n- OpenParser parse responses now return the unified `openparser@1` document graph, with plain text, canonical Markdown, pages, typed elements, relations, annotations, assets, geometry, confidence, and provider provenance in one predictable contract.\n\n---\n\n## 0.10.52 (2026-08-04)\n\n### Platform (Studio)\n\n- Agent Builder: improve connection recovery so interrupted sessions resume reliably, stale environments are replaced safely, and approval prompts remain retryable when delivery fails.\n\n---\n\n## 0.10.51 (2026-08-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.50 (2026-08-03)\n\n### Platform (Studio)\n\n- OpenParser Studio: pipeline creation no longer reports a duplicate-name error after a successful save, and edits now save reliably from the browser.\n\n---\n\n## 0.10.49 (2026-08-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.48 (2026-07-30)\n\n### Platform (Studio)\n\n- OpenParser Studio now displays canonical OpenParser JSON with readable indentation, including large document results.\n\n---\n\n## 0.10.47 (2026-07-30)\n\n### Platform (Studio)\n\n- OpenParser Studio now keeps large document results responsive, renders OCR markdown with clearer structure, and provides consistent copy and download actions for Markdown and JSON output. Documentation links now reliably open the generated API reference.\n\n### Infrastructure & processing\n\n- OpenParser jobs now recover more safely when document processing capacity becomes unavailable. Retryable failures pause new dispatches, retry without duplicate charges, and bound large-document processing so one document cannot overwhelm the service.\n\n---\n\n## 0.10.46 (2026-07-30)\n\n### Platform (Studio)\n\n- Team settings: bring back the invitation link. Creating an invitation now shows its link straight away whenever no invitation email was delivered, and administrators can pull up the link again at any time from the invitations table. This unblocks onboarding on deployments without email delivery, where handing over the link is the only way to get someone into the workspace.\n- Run details: field grounding now labels flagged fields by what the extraction actually reports, showing \"3 with low confidence\" instead of \"3 to review\". The count is a confidence signal, not an assigned task.\n\n---\n\n## 0.10.45 (2026-07-29)\n\n### Platform (Studio)\n\n- Parse Document setup now clearly separates OCR from Vision AI, automatically offers available OpenParser OCR models, shows each model's per-page price, displays only the controls that affect the selected method, and surfaces structured layout data with tables, figures, polygons, and bounding boxes for downstream workflow steps.\n\n### CLI\n\n- The workflow authoring reference now covers explicit OCR and Vision AI parse modes, optional figure-caption models, and structured layout output.\n\n### Infrastructure & processing\n\n- Document parsing now defaults to higher-fidelity OCR, preserves canonical structured layout alongside Markdown, and automatically supports available OCR models with provider-specific per-page pricing. Other OCR providers retain their existing rates.\n\n---\n\n## 0.10.44 (2026-07-28)\n\n- Internal improvements.\n\n---\n\n## 0.10.43 (2026-07-27)\n\n- Internal improvements.\n\n---\n\n## 0.10.42 (2026-07-27)\n\n- Internal improvements.\n\n---\n\n## 0.10.41 (2026-07-27)\n\n### Platform (Studio)\n\n- Run traces now show each attempt of an AI request. A request that timed out and was retried used to appear as a single long bar, so a step that spent three timeouts on one page looked identical to one slow call. The raw trace now has one bar per try, labelled with the try number, and the run timeline marks a retried call with how many times it was sent. Retried requests also record how long they waited for a free slot, which distinguishes a slow model from a queue backed up behind its own in-flight requests. For documents parsed page by page, each split retry records the pages it covered and how deep the split went.\n- Runs and Experiments improvements: - An experiment run now shows the same input and output panels as the main run view, including input file downloads, per-step output files, and inline field-level output review. - Scored runs show their eval score in the runs list and in the run header, so an experiment's results can be compared without opening each run. - A run that came from an experiment or a dataset example now links straight to that run in the Evals view. - The Live and Experiments toggles on Runs are remembered between visits. - Field grounding: a wide document no longer overflows the panel. Wide tables and long unbroken text scroll inside the document card.\n\n---\n\n## 0.10.40 (2026-07-25)\n\n### Infrastructure & processing\n\n- Processing reliability on busy deployments: health checks are now served independently of document processing, so the service stays responsive to them even while working through a heavy document. It is no longer restarted mid-run just because it is under load, so long-running document runs complete more reliably.\n- Document processing is more resilient on CPU- and memory-constrained deployments. Page rasterization for vision and OCR now runs in isolation, so a single large or malformed document can no longer stall the processing service or cause it to restart mid-run. Runs on big scanned documents that previously failed partway through with \"the worker stopped before this attempt recorded a terminal result\" now complete reliably.\n\n---\n\n## 0.10.39 (2026-07-25)\n\n### Platform (Studio)\n\n- Label Pages runs: the page preview now shows the classified document in the full viewer instead of small thumbnails. PDFs render page-by-page with zoom and navigation and each page's labels shown beside it; Word and other Office documents open in their own preview next to a per-page label list. Filter by a label to focus on just the pages that carry it.\n\n---\n\n## 0.10.38 (2026-07-24)\n\n### Platform (Studio)\n\n- OpenParser Studio: manage extraction pipelines from a dedicated workspace — create, edit, run, duplicate, and delete saved configurations. Jobs show the pipeline and version that produced each result, and you can save a new pipeline from job settings.\n- OpenParser Studio: clearer progress while documents upload, parse, and extract, with live elapsed timing at each stage. Job history and the playground share a unified header with breadcrumbs, improved document and Markdown output viewers, and a cleaner parse sidebar. Choose light or dark theme and manage your account from the sidebar; model selectors and in-product copy are simpler throughout the workspace.\n- Members provisioned through SSO are now read-only in workspace member settings. Their role and access come from your identity provider's groups, so admins can no longer change or remove them by hand, and each SSO member is clearly labeled. Accounts created with a username and password stay fully manageable by admins.\n\n### Public API\n\n- **Breaking:** OpenParser API resource identifiers now use consistent prefixed ids. Parse, extract, and batch jobs return `opj_…` ids instead of UUIDs. Saved extraction pipelines use `oppl_…` instead of `oep_…`. New parse output writes figure image ids as `opfig_…` instead of `ocrfig_…`. Existing jobs and pipelines are remapped automatically on upgrade when the OCR queue is idle enough for migration preflight. Prefer the new formats in job URLs, `parse_job_id`, `pipeline_id`, and batch child `job_id` fields. During the transition, previously issued UUID job ids, `oep_…` pipeline ids, and UUID list cursors remain readable; responses continue to return the preferred `opj_…` / `oppl_…` forms. Historical parse artifacts and `result_json` may still embed legacy `ocrfig_…` figure paths; `GET /files/\\{id}` accepts both `opfig_…` and `ocrfig_…`.\n\n### Infrastructure & processing\n\n- Hardened AI-powered document processing against prompt-injection attempts hidden inside uploaded documents. Instructions embedded in a document can no longer steer extraction, classification, or vision results away from the requested schema, or coax the model into disclosing its own configuration.\n- AI vision step results no longer include internal document storage references in their metadata. The step's `_vision` provenance now records only which pages were inspected and how many were merged, keeping internal storage paths out of workflow output.\n\n---\n\n## 0.10.37 (2026-07-24)\n\n### Platform (Studio)\n\n- New **Label Pages** step tags each page of a document with zero or more labels (multi-label) using AI, and groups the results into a label-to-pages map. Unlike section splitting — which produces one contiguous range per section — this collects pages of the same kind wherever they appear, so scattered pages (for example every signature or photo page throughout a report) can be gathered in one place. The page-inspection step can now take an explicit list of page indices, so you can route the pages for a given label straight into a visual inspection without hand-listing them.\n\n---\n\n## 0.10.36 (2026-07-23)\n\n### Platform (Studio)\n\n- OpenParser Job History now reports the real end-to-end duration for completed parse and extraction jobs instead of showing a zero or unavailable measurement.\n- Running OpenParser jobs now show the document scanning animation from the playground while results are being prepared.\n- Parse and Extract now use consistent operation icons across OpenParser Studio and documentation.\n\n---\n\n## 0.10.35 (2026-07-23)\n\n### Platform (Studio)\n\n- OpenParser sign-in and account creation now redirect directly to the branded authentication flow without an intermediate confirmation page.\n- OpenParser parse jobs now retain both `raw` and `openparser@1` results. Retrieve either representation with `GET /jobs/\\{id}/result?format=...`, switch formats in the Studio Output tab, and start extraction from a raw-format parse job without running OCR again.\n\n### Public API\n\n- OpenParser parse jobs now retain both `raw` and `openparser@1` results. Retrieve either representation with `GET /jobs/\\{id}/result?format=...`, switch formats in the Studio Output tab, and start extraction from a raw-format parse job without running OCR again.\n- OpenParser now keeps recognized text aligned with its original bounding box by default. Set `ocr_options.merge_layout_blocks` to `true` per parse, extraction, batch item, or saved pipeline when merged recognition is preferred over one-to-one text geometry.\n\n---\n\n## 0.10.34 (2026-07-23)\n\n### Platform (Studio)\n\n- OpenParser sign-in and account creation now keep OpenParser branding throughout the authentication experience.\n- OpenParser Studio: uploads and sample documents now open their Job History detail immediately, so browser back and forward navigation follows each run naturally while extraction and result review stay in one place.\n- Run detail now shows clean, readable file names for inputs and outputs instead of internal storage identifiers, and long file names no longer overlap the preview and download buttons.\n\n### Public API\n\n- OpenParser parsing now preserves every detected layout region—including empty title, header, and figure boxes—so document overlays remain complete. The obsolete `figure_assets` option is removed because figure regions are now always retained.\n- OpenParser can now process documents beyond 25 pages and admit batches of up to 100 documents, while retaining per-page safety limits.\n- OpenParser jobs can now stream their retained source documents with `GET /jobs/\\{id}/source`, making it easier to build durable review experiences around past runs.\n- `POST /suggest-schema` now returns the suggested schema inline as a convenience response instead of creating a job that clients must poll.\n\n### Infrastructure & processing\n\n- Documents uploaded without a declared file type are now recognized from their contents, so PDFs, RTF, and Office files parse reliably instead of failing with an \"unsupported file type\" error. This most often helped uploads coming from automated integrations that omit the file type.\n\n---\n\n## 0.10.33 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser Studio: make Playground the home page, add shareable social previews, clarify job status and pipeline empty states, and tidy the OCR model selector copy.\n\n### Public API\n\n- OpenParser suggested extraction model catalog (`GET /models/llm` in suggested mode) now surfaces up to 20 recommended models instead of 12, so more current options appear before you need to search.\n\n---\n\n## 0.10.32 (2026-07-22)\n\n- Internal improvements.\n\n---\n\n## 0.10.31 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser Studio production sign-in no longer auto-redirects to Eigenpal when you are signed out. Choose **Continue to sign in** on the local OpenParser page to authenticate with your Eigenpal account; sign-out stays on OpenParser.\n\n---\n\n## 0.10.30 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser production sign-in now shares Eigenpal sessions across its dedicated domain and returns users to their original OpenParser destination after authentication.\n- OpenParser Playground: remove the doubled border and rounded corners around the document workspace.\n\n### Infrastructure & processing\n\n- OpenParser: restore schema suggestions, use GPT-5.6 Terra as the default extraction model with GPT-4.1 Mini as a certified fallback, tighten compatibility checks, and provide clearer failure guidance.\n\n---\n\n## 0.10.29 (2026-07-22)\n\n### Platform (Studio)\n\n- OpenParser Studio sign-in and sign-up now load the shared identity UI correctly for signed-out visitors.\n\n---\n\n## 0.10.28 (2026-07-22)\n\n### Platform (Studio)\n\n- API keys: keep usable credentials in the primary list and move revoked or expired credentials into a collapsed history section for faster scanning.\n- OpenParser Studio sign-in and sign-up now show OpenParser product copy and logo while retaining the shared Eigenpal identity.\n\n### Public API\n\n- OpenParser model discovery (`GET /models/llm`) now refreshes the live compatible catalog on the API service instead of falling back to a short emergency list when the catalog credential is missing from that process.\n\n### Infrastructure & processing\n\n- OpenParser document processing now bounds source downloads and retries transient storage failures, preventing stalled jobs from running indefinitely.\n\n---\n\n## 0.10.27 (2026-07-21)\n\n### Platform (Studio)\n\n- New Inspect Pages (Vision) step lets a workflow look at the actual page images of a document and return structured results, for details that only exist in the pixels rather than the text. Use it to check whether a document is signed, rate embedded photos, or spot stamps and logos. It works on PDFs, images, and Office documents, and you can point it at a specific page range (for example the section found by a Split step) so it only reviews the pages that matter. The run trace shows the pages it inspected next to the results.\n- Parsing can now describe the figures on a page as text. Enable \"describe figures\" on a Parse step and the images on each page (property photos, charts, stamps) are detected and captioned inline, so later steps that work on text, like Split, can find image-only pages. This is especially useful for scanned documents, where the photo pages carry almost no text on their own. You can provide custom instructions for how figures should be described.\n- Split step results are now also available keyed by section name. A later step can point at one section directly, for example `\\{\\{ steps.split.output.sections.photos.page_range }}`, instead of filtering the full list. This makes wiring a Split step into a downstream step much simpler.\n- The Inspect Pages (Vision) step now takes a Page From / Page To range instead of a single page-range expression, and both are optional. Leave them blank to inspect the whole document, which is processed in chunks and the results merged automatically. This makes it much easier to point the step at a range (for example the start and end of a Split section) or to scan an entire document without writing a range expression.\n\n---\n\n## 0.10.26 (2026-07-21)\n\n### Platform (Studio)\n\n- Wildcard API keys can use the OpenParser OCR API consistently with every other platform capability. Keys can also be restricted to the dedicated `ocr:full` scope when OCR-only access is preferred.\n- Run traces now include a Grounding panel for extract steps: every extracted value is highlighted in the input text, tinted by confidence, and clicking a field or a highlight jumps between them. Grounded fields also show inline context previews of the exact source passage, both in the panel and in the expanded step row. Split steps gain the same visual page-range panel the segmenter uses, with page thumbnails and per-section preview. The workflow builder reflects that grounding is on by default and lets you pick any configured provider as the grounding model, and capturing expected output from a run no longer snapshots volatile grounding metadata into evals.\n\n### Public API\n\n- Wildcard API keys can use the OpenParser OCR API consistently with every other platform capability. Keys can also be restricted to the dedicated `ocr:full` scope when OCR-only access is preferred.\n- OpenParser: completed extraction jobs can now be retrieved reliably with their attempt and usage metadata.\n\n### CLI\n\n- The step catalog now documents grounded extraction as the default: extract steps ship per-field confidence and source spans under the `_grounding` output key unless `grounded: false` is set.\n\n### Infrastructure & processing\n\n- Data extraction now verifies itself by default. Every extract step traces each extracted field back to its exact location in the source text and attaches a confidence level (high, medium, or low) plus a needs-review flag under a reserved `_grounding` output key, so downstream steps and evaluators can route uncertain values to a human. The verification pass runs on your workspace model (any configured provider), chunks long documents automatically, and falls back to deterministic text matching instead of failing the run when no model is available. Set `grounded: false` on a step to opt out.\n\n---\n\n## 0.10.25 (2026-07-20)\n\n### Platform (Studio)\n\n- Failed single sign-on attempts now return to the sign-in page with a clear, actionable message (for example, when an account's email domain isn't authorized or the account hasn't been granted access) instead of a blank error page.\n\n---\n\n## 0.10.24 (2026-07-15)\n\n### Platform (Studio)\n\n- Agent runs graded by configured evaluators now record a weighted score and pass/fail result, visible in the runs feed and run detail responses. Previously only workflow runs carried an evaluator verdict.\n- Email addresses for a workflow are unique across your whole organization, not just the workflow you are editing. Picking one that is already taken used to fail with a server error. It now tells you which workflow already receives email at that address, or that the workflow you are editing already has it, so you know what to do next. Duplicate folder names and duplicate workspace invites also report clearly instead of failing.\n- `ai.extract` with `grounded: true` no longer succeeds silently without producing grounding. When the grounding pass cannot run (missing OpenAI credentials on the worker, or a grounding model that is not an OpenAI model) the step now fails with an error that names the exact misconfiguration. When the pass runs but produces no field grounding, the output carries an explicit degraded marker instead of nothing. The grounding model picker in the workflow builder now only offers OpenAI models, matching what the grounding pass supports.\n- Agent training: when a training session fails to open, the dashboard now shows what went wrong instead of a generic error. The message names the setup step that failed, and a session blocked by secrets that cannot be decrypted says so and points at the agent settings. A session whose setup fails partway through no longer opens on an incomplete workspace.\n- Self-hosted deployments can now sign users in through corporate single sign-on services that use a redirect-and-token flow instead of OIDC. The new protocol supports mutual TLS for the server-to-server exchange, maps directory groups to EigenPal roles (admin, member, viewer) on every SSO sign-in so the directory stays the source of truth, and links existing password accounts by email so nobody loses access when SSO is turned on. Startup validation rejects unsafe callback origins and provider identifiers, while malformed or oversized identity responses fail closed.\n\n### Public API\n\n- Syncing an automation immediately after a release no longer fails with HTTP 500 while the new release tag propagates. The sync endpoint now reports a retryable status with a clear message when the Git source is momentarily unavailable.\n- Fixed single-experiment results export returning HTTP 400 whenever the `includeTrace` query flag was omitted. `workflow experiment results` and the auto-pull at the end of `workflow experiment watch` now download per-evaluator results in JSON and CSV again.\n- Creating an email trigger address that is already in use now returns 409 with a message naming the workflow in your organization that already uses it, instead of 500.\n\n### CLI\n\n- Agent example runs now report a real evaluator verdict in the CLI: `eigenpal run agents.&lt;name&gt; --example &lt;name&gt; --wait` waits for the verdict, prints the weighted score and pass/fail result, and `--fail-on-mismatch` exits non-zero when the run fails its evaluators, matching the existing workflow behavior. When no evaluators are configured, the CLI says so instead of silently reporting nothing.\n- `agents secrets` is now one command group with `list`, `set`, `unset`, `import`, and `export` subcommands (`agents secret` remains as an alias). The new `agents secrets list` shows the secret names and descriptions declared in the package without ever printing values. Previously `set` and `unset` lived under a separate singular command and `secrets list` failed with an argument error.\n- `agents sync` retries automatically with a short backoff when the server reports the Git source as temporarily unavailable, so the sync right after `agents release` succeeds without manual retries.\n- `agents dataset validate` now checks the same layout the server accepts on `agents dataset push`: example folders under `examples/`, file inputs referenced from `input.json` with `\\{ \"$file\": \"input/...\" }`, and `expected.json` optional. Previously the local validator demanded a different layout that push would then reject, so no dataset could satisfy both. Validation errors now point at the exact rule that failed, including a hint when example folders sit at the dataset root instead of under `examples/`. When the agent package carries an input schema, each example's full input object is validated against it (required fields, unknown keys, and value types, with `\\{ \"$file\": ... }` references accepted for file fields), so inputs that would fail at run start are caught locally. Failure-expected examples (`expected.json` with `$error`) are rejected for agent datasets, since agent runs are evaluated only when they complete.\n\n[View full release notes →](/releases/0.10.24)\n\n---\n\n## 0.10.23 (2026-07-15)\n\n- Internal improvements.\n\n---\n\n## 0.10.22 (2026-07-14)\n\n### Platform (Studio)\n\n- Organization members can now configure, test, and manage outbound webhooks from Studio.\n\n---\n\n## 0.10.21 (2026-07-14)\n\n### Platform (Studio)\n\n- Webhooks: notify external systems when workflow or agent runs are created or change status, with signed delivery, custom headers, retry history, testing, and manual redelivery from Studio.\n- Webhook signing secrets are now easier to copy securely from endpoint setup and details, with clearer event selection defaults.\n- Webhook setup now keeps failed submissions actionable with clear inline error feedback.\n\n### Public API\n\n- Run creation and rerun requests now publish signed lifecycle webhooks only after inputs are ready, so API-triggered automations never emit events for runs that fail during setup.\n\n### Infrastructure & processing\n\n- Improved staging worker deployment reliability when compute capacity is fully allocated.\n\n---\n\n## 0.10.20 (2026-07-12)\n\n### Platform (Studio)\n\n- Workflows: configure automatic retries from Studio at the workflow level or override them for individual HTTP GET/HEAD and Website Reader steps.\n\n### CLI\n\n- The bundled workflow reference now documents durable retry policies, inheritance, supported step types, and retry safety limits.\n\n### Infrastructure & processing\n\n- Workflow runs can recover replay-safe network steps from transient failures without restarting completed work, using bounded backoff and durable retry state. Retry behavior is now step-scoped. Legacy whole-run retry settings no longer restart a failed workflow; configure durable retries on eligible steps or through the workflow retry default instead.\n\n---\n\n## 0.10.19 (2026-07-09)\n\n### Platform (Studio)\n\n- Workflow composition is unified on `action.invoke-workflow`: use `execution: inline` (default) to run a target workflow's steps inside the parent run, or `execution: child` for a separate child run. Reusable blocks (`control.block`, `kind: block`) are removed — migrate to inline invoke with `workflow: &lt;name-or-id&gt;`.\n\n### Public API\n\n- Workflow run endpoints now preserve inline invoke snapshots across initial runs, reruns, and dataset executions so composed workflows remain reproducible after target workflows change.\n\n### CLI\n\n- Workflow YAML reference docs now describe `action.invoke-workflow` as the single composition primitive, including inline and child execution modes.\n\n---\n\n## 0.10.18 (2026-07-08)\n\n### Infrastructure & processing\n\n- On-prem deployments: improve OpenShift compatibility so migration and processing jobs can start reliably under random-user security policies.\n\n---\n\n## 0.10.17 (2026-07-08)\n\n### Platform (Studio)\n\n- Document parser: vision parsing can now render PDF pages at higher resolution and image quality for documents where small text or compression artifacts hurt OCR accuracy.\n\n### Infrastructure & processing\n\n- Document parser: vision parsing can now render PDF pages at higher resolution and image quality for documents where small text or compression artifacts hurt OCR accuracy.\n\n---\n\n## 0.10.16 (2026-07-07)\n\n### Platform (Studio)\n\n- Workflow experiment results now preserve evaluator error details alongside each per-evaluator score, so example grading views and tools can distinguish failed judges from unknown results instead of treating them as passing.\n\n### CLI\n\n- `eigenpal run &lt;workflow&gt; --example &lt;name&gt;` now actually grades the example instead of printing `PASS` whenever the run merely finished. It runs the workflow's current published version on the server's stored dataset example, so configured evaluators run automatically and the CLI surfaces the real weighted score and per-evaluator pass/fail. Workflows with no evaluators fall back to a structural diff of the output against the example's stored expected output. The summary reports two separate signals: execution health (`ok`/`errored`) and accuracy. Add `--fail-on-mismatch` to exit non-zero when a graded example fails. Because the run uses the server-side example, push your latest dataset and evaluators (`eigenpal workflow dataset push`, `eigenpal workflow evaluators push`) before running `--example`.\n\n---\n\n## 0.10.15 (2026-07-06)\n\n### Platform (Studio)\n\n- Experiments: make result review easier in Studio with trace exports, clickable score bars, calmer live refreshes, developer-view defaults, and clearer separation between below-threshold results and run errors.\n\n### Public API\n\n- Experiment export endpoints now support JSON exports with full run trace details for deeper debugging and audit review.\n\n### SDK\n\n- SDK clients now expose the trace-inclusive experiment export option for deeper debugging and audit review.\n\n---\n\n## 0.10.14 (2026-07-06)\n\n### Platform (Studio)\n\n- Evaluations: expected workflow failures now report cleaner scores when a run is supposed to stop early. Studio marks non-applicable quality judges as skipped, so successful rejection examples can receive a full score from the structured failure checks that actually apply.\n\n---\n\n## 0.10.13 (2026-07-06)\n\n- Internal improvements.\n\n---\n\n## 0.10.12 (2026-07-06)\n\n- Internal improvements.\n\n---\n\n## 0.10.11 (2026-07-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.10 (2026-07-03)\n\n- Internal improvements.\n\n---\n\n## 0.10.9 (2026-07-02)\n\n### Platform (Studio)\n\n- Build document-processing workflows that split, route, and verify a mixed batch: - **Document separation** detects the boundaries and types of the documents inside one large scan, so a single upload can be broken into its individual documents and each sent to its own extraction pipeline — even for batches hundreds of pages long. - **Multi-way routing** sends each detected document to the right branch by its type, and stays readable on the canvas even with many branches. - **Grounded extraction** attaches a confidence level and source location to each extracted field, flagging values that aren't found verbatim in the document so reviewers know where to look. - The run view now lets you open the detected documents and preview their pages, and inspect the OCR layout with bounding boxes drawn over the page (with a toggle to the extracted text) — right from the step timeline.\n\n### CLI\n\n- The workflow step catalog now lists the new document-separation and multi-way routing steps, plus the grounded-extraction options, so authoring and validating workflows from the CLI stays in step with what the platform supports.\n\n### Infrastructure & processing\n\n- Self-hosted (on-prem) deployments can now run official EigenPal release images, with access provisioned per customer. Images are published only after a release ships and are signed so you can verify their authenticity before deploying.\n\n---\n\n## 0.10.8 (2026-07-01)\n\n### Platform (Studio)\n\n- Single-file workflow inputs now display correctly after a dataset import. Previously an input that takes one file could show an empty file slot; imported examples now match each file to the workflow's declared input shape.\n- Evaluator scoring now uses a single pass threshold for the whole workflow. The score-by-example chart's cutoff line and every evaluator's pass/fail are measured against that one threshold, so the chart, the per-evaluator results, and the run gate always agree. Experiment scores are shown in two states — passing (green) or below threshold (amber).\n- The LLM judge evaluator now requires evaluation criteria. Without them the model invents its own scoring rubric, so the editor marks the field required, renames it to \"Evaluation criteria\" with a worked example, and blocks saving until it is filled in.\n- Workflow folders can now be reorganized. A new \"Move to folder\" action in each folder's menu lets you move a folder (and everything inside it) into another folder or back to the top level, so you can restructure your workspace without recreating folders. Destinations that would nest a folder inside itself are blocked, with a tooltip explaining why.\n- Nested sub-workflows now display and resolve correctly across runs, the workflow builder, and the CLI. In the Runs list, a run that invokes a sub-workflow which itself invokes another sub-workflow now nests every level under its parent, instead of stopping at the first level. In the workflow builder, an \"Invoke Workflow\" step that targets a workflow built from other invoked workflows now shows the real output field types instead of \"unknown\", so you can reference those fields with autocomplete; referencing one of those fields no longer triggers a false \"field not found\" warning. The same resolution now applies when validating and publishing workflows (including via the CLI), so deeply nested invoke chains validate against their real output fields. All of this resolves through arbitrarily deep chains with a safety limit that prevents looping on workflows that invoke each other.\n- Runs: add a simplified review mode with developer-view toggle, review status badges, and inline output review for JSON fields and generated files.\n- New debugging and control primitives for runs. You can now cancel an in-progress run through the API, experiment results report when a batch has fully finished, steps skipped by a condition or an empty loop are reported as skipped rather than succeeded, and each step records the exact configuration it ran with so failures are easier to diagnose.\n- Run detail responses are leaner and more explicit: you choose exactly which sections to expand, and the public run schema now exposes the workflow version, cancellation-request time, and trace, retry, and email-trigger details.\n\n### CLI\n\n- `eigenpal workflow validate` now tells you when a workflow contains Invoke Workflow steps that local validation cannot fully check. Because those steps reference other workflows that live on the server, the command prints a short note pointing you to `validate --online` (or push) to verify the invoke targets, input types, and cycles. The skill guidance now shows the `--online` step in the validate-then-push flow as well.\n- The evaluator configuration reference now reflects the single workflow-level pass threshold. A per-evaluator `passThreshold` is documented as legacy — pass/fail is decided by the one workflow-level threshold — and that workflow-level threshold no longer shows a fixed default, since it is derived when omitted.\n\n### SDK\n\n- The Python SDK now requires Python 3.10 or newer. Python 3.9 has reached the end of its support window, and dropping it keeps the SDK on current, actively maintained dependencies. If you are still on Python 3.9, upgrade to 3.10+ to continue receiving SDK updates.\n\n[View full release notes →](/releases/0.10.8)\n\n---\n\n## 0.10.7 (2026-06-30)\n\n### Platform (Studio)\n\n- Faster dashboard navigation. Lists keep their contents on screen while filters and folders refresh instead of flashing a loading state, document and image previews are cached so they no longer re-download on every navigation, and heavy viewers (PDF, charts, rich text) load on demand for a quicker first paint.\n- Workflows that invoke another workflow now pass file inputs through to the sub-workflow, so file-backed sub-workflow runs no longer fail before they start.\n\n### CLI\n\n- `eigenpal --help` now groups `run`, `rerun`, and `runs` under a dedicated \"Run\" section instead of the catch-all \"Other\" bucket, so starting a run and reading its output is easy to find.\n\n---\n\n## 0.10.6 (2026-06-30)\n\nThis release contains maintenance and reliability improvements with no customer-facing changes.\n\n---\n\n## 0.10.5 (2026-06-29)\n\nThis release makes EigenPal's public changelog a reliable product record. Each release now has a dedicated docs page that explains what changed for Studio, the public API, the CLI, SDKs, and document processing in one place.\n\nThat means teams can follow platform improvements without piecing together GitHub activity or package-specific notes. The changelog is organized around customer-facing product areas, so it is easier to see which changes affect app users, API integrations, developer tools, and processing behavior.\n\n### Platform (Studio)\n\n- Invoke Workflow steps are now typed end to end. Pick a target workflow and map each input it declares to a value, then reference the workflow's output fields and any files it generates from downstream steps with autocomplete. Inputs and outputs are checked when you save and when the step runs, so mismatches surface early instead of failing mid-run.\n- Runs that invoke another workflow now appear nested under their parent run in both the runs feed and the run timeline, and link straight to the sub-workflow's own run and trace.\n- You can view a workflow's inferred output schema (the fields and files it returns, typed from its own steps) without running it.\n- File inputs are preserved consistently across runs, reruns, reviewed examples, and dataset experiments, so reused runs and examples no longer lose or mispoint their files.\n- Creating new organizations and other Git-backed source operations stay reliable even during Git provider outages.\n\n### Public API\n\n- Run file inputs now use a consistent artifact model. Callers provide reusable files with `$fileId` or inline files with `$inline`, and EigenPal materializes them into run-owned artifacts before execution, reruns, promotion, and dataset workflows.\n- A new endpoint returns a workflow's inferred output schema without running it, as JSON Schema or as a TypeScript or Python type.\n\n### CLI\n\n- `eigenpal workflow schema <workflow>` prints a workflow's inferred output schema as JSON Schema, or as a TypeScript or Python type with `--format`.\n\n[View full release notes →](/releases/0.10.5)\n\n---\n\n## 0.10.4 (2026-06-25)\n\n### Platform (Studio)\n\n- Unify file list review surfaces\n\n---\n\n## 0.10.3 (2026-06-24)\n\n### SDK\n\n#### Patch Changes\n\n- e48cb81: Remove `fileVerdict` from run review correction types; file correction intent is encoded via `correctedArtifactPath`.\n\n---\n\n## 0.10.2 (2026-06-24)\n\n### CLI\n\n#### Patch Changes\n\n- Single-tenant workflow file inputs can reference a named external file source. The worker retrieves and stores each file before executing the workflow.\n\n---\n\n## 0.10.1 (2026-06-23)\n\n### Public API\n\n- Polish reviews pages and group API reference nav\n\n### Infrastructure & processing\n\n- Client-shareable deployment architecture PDFs\n\n---\n\n## 0.10.0 (2026-06-23)\n\n### Platform (Studio)\n\n- Add simple runs review mode\n\n### Infrastructure & processing\n\n- Autogenerate chart architecture diagram from helm template\n- AWS/GCP/Azure Terraform examples with architecture diagrams\n- Helm chart + local kind for single-tenant on-prem\n\n---\n\n## 0.9.0 (2026-06-22)\n\n### CLI\n\n#### Minor Changes\n\n- c35d5d4: Clean up the public runs and evaluation API surface: move workflow eval operations onto automations, expose run scores/artifacts through the unified runs API, and update CLI/SDK helpers to use the canonical routes.\n\n Breaking: `runs.evalResults` and `GET /api/v1/runs/\\{id}/eval-results` are replaced by `runs.scores` and `GET /api/v1/runs/\\{id}/scores`.\n\n#### Patch Changes\n\n- c35d5d4: Clarify `--max-wait` help text so timeout exit behavior reads naturally.\n\n### SDK\n\n#### Minor Changes\n\n- c35d5d4: Clean up the public runs and evaluation API surface: move workflow eval operations onto automations, expose run scores/artifacts through the unified runs API, and update CLI/SDK helpers to use the canonical routes.\n\n Breaking: `runs.evalResults` and `GET /api/v1/runs/\\{id}/eval-results` are replaced by `runs.scores` and `GET /api/v1/runs/\\{id}/scores`.\n\n[View full release notes →](/releases/0.9.0)\n\n---\n\n## 0.8.0 (2026-06-18)\n\n### CLI\n\n#### Minor Changes\n\n- d620a00: Expose the clean public automation API around automations, runs, files/artifacts, datasets, evaluators, experiments, evaluation results, and run promotion. This intentionally breaks the pre-v1 SDK/CLI surface that exposed workflow- and agent-specific top-level resources outside the explicit legacy compatibility routes.\n\n > [!WARNING]\n > **Breaking change (pre-v1).** The workflow- and agent-specific top-level\n > resources have been removed in favor of a single automation-centric surface.\n > These packages are still 0.x, so this breaking redesign ships as a `minor`\n > bump. Update your integration before upgrading.\n\n #### Removed\n - Top-level workflow resources, e.g. `client.workflows.*`, including\n `client.workflows.executions.runAndWait(...)` and the rest of the\n `client.workflows.executions.*` tree.\n - Top-level agent resources, e.g. `client.agents.*` (runs, reviews, traces,\n files, expected artifacts).\n - Top-level source/git resources, e.g. `client.sources.*`.\n\n[View full release notes →](/releases/0.8.0)\n\n---\n\n## 0.7.2 (2026-06-13)\n\n### SDK\n\n#### Minor Changes\n\n- c5a709c: Public workflow list/detail responses include `apiEnabled` and `triggers`; run definition docs note workflow-only scope.\n\n---\n\n## 0.7.1 (2026-06-13)\n\n### SDK\n\n#### Patch Changes\n\n- 9db3f01: Expose `apiEnabled` and `triggers` on `AgentSummary` for runtime trigger projection.\n\n---\n\n## 0.7.0 (2026-06-12)\n\n### CLI\n\n#### Minor Changes\n\n- 963fd6c: Unify run detail on `GET /api/v1/runs/\\{id}`: return the canonical Run object directly (no `\\{ run: ... }` envelope) and merge expanded fields in-place via documented `expand` tokens. Remove the session-only `expand=internal` dashboard escape hatch; SDKs and CLI now use explicit expand lists.\n\n#### Patch Changes\n\n- 963fd6c: Update runs commands for the grouped run API shape and four expand tokens.\n\n### SDK\n\n#### Minor Changes\n\n- 963fd6c: Unify run detail on `GET /api/v1/runs/\\{id}`: return the canonical Run object directly (no `\\{ run: ... }` envelope) and merge expanded fields in-place via documented `expand` tokens. Remove the session-only `expand=internal` dashboard escape hatch; SDKs and CLI now use explicit expand lists.\n\n#### Patch Changes\n\n- 12c00d8: Docs: clearer wording in the file-input and TypeScript-runtime sections. No API or behavior changes.\n\n---\n\n## 0.6.17 (2026-06-12)\n\n### SDK\n\n#### Patch Changes\n\n- 716c3cf: Update the hosted default API base URL and API-key guidance from `app.eigenpal.com` to `studio.eigenpal.com`.\n\n---\n\n## 0.6.16 (2026-06-12)\n\n### CLI\n\n#### Patch Changes\n\n- 75dd64c: Internal refactor: move the skill tool registry into its own module so other tooling can import it. No change to any command, flag, argument, or output.\n\n---\n\n## 0.6.15 (2026-06-10)\n\n### CLI\n\n#### Minor Changes\n\n- ca87265: Unify workflow and agent run starts behind the canonical `/api/v1/run/\\{target}` endpoint, root `eigenpal run` / `eigenpal rerun` commands, and root SDK `client.run()` / `client.rerun()` methods.\n\n The old nested CLI commands and SDK resource methods for starting workflow or agent runs have been removed.\n\n#### Patch Changes\n\n- 5ea0bb5: `workflow dataset pull` gains `--example-id &lt;id&gt;` (repeatable) to export a single example or a selected subset of a dataset, instead of always pulling the whole dataset. The subset ZIP uses the same archive layout as a full pull, so it re-imports into any dataset via `dataset push --mode append`. Requesting an example id that does not exist for the workflow exits non-zero.\n\n### SDK\n\n#### Minor Changes\n\n- ca87265: Unify workflow and agent run starts behind the canonical `/api/v1/run/\\{target}` endpoint, root `eigenpal run` / `eigenpal rerun` commands, and root SDK `client.run()` / `client.rerun()` methods.\n\n The old nested CLI commands and SDK resource methods for starting workflow or agent runs have been removed.\n\n---\n\n## 0.6.10 (2026-06-08)\n\n### CLI\n\n#### Patch Changes\n\n- 99ca1b4: Unify agent and workflow run commands and SDK helpers on the shared `/api/v1/runs` API, including the public `client.runs` facade and regenerated SDK reference docs.\n\n### SDK\n\n#### Patch Changes\n\n- 99ca1b4: Unify agent and workflow run commands and SDK helpers on the shared `/api/v1/runs` API, including the public `client.runs` facade and regenerated SDK reference docs.\n\n---\n\n## 0.6.9 (2026-06-04)\n\n### SDK\n\n#### Minor Changes\n\n- 5e7c051: Add `observability` (phase timeline + structured failure) to workflow execution and agent run status API responses.\n\n---\n\n## 0.6.6 (2026-06-03)\n\n### CLI\n\n#### Patch Changes\n\n- 245f347: Clean up the agent CLI surface by removing obsolete compatibility commands, moving reruns to `agents rerun`, and replacing run pulls with canonical artifact fetching.\n- 5ab00ee: Tighten permissions on `~/.config/eigenpal/credentials.json` and its parent directory to owner-only (0600 / 0700). Previously the file was written 0600 but the parent directory inherited the user's umask (typically 0755), allowing other local users to list the directory and stat the file. The CLI now also re-tightens permissions on every write, so installs created with older versions are corrected on the next `auth login` / `auth use`.\n\n---\n\n## 0.6.4 (2026-06-03)\n\n### CLI\n\n#### Patch Changes\n\n- c3486a5: Fix agent git cutover QA findings: dashboard runs now navigate to the created run, inbound email aliases preserve mixed-case organization qualifiers, sandbox source materializes under `/workspace/agent`, run artifact downloads use direct paths like `/files/eigenpal.lock`, wait-for-completion responses include source provenance, and CLI wait/watch commands exit nonzero for failed or cancelled runs.\n\n### SDK\n\n#### Patch Changes\n\n- c3486a5: Fix agent git cutover QA findings: dashboard runs now navigate to the created run, inbound email aliases preserve mixed-case organization qualifiers, sandbox source materializes under `/workspace/agent`, run artifact downloads use direct paths like `/files/eigenpal.lock`, wait-for-completion responses include source provenance, and CLI wait/watch commands exit nonzero for failed or cancelled runs.\n\n---\n\n## 0.6.2 (2026-06-02)\n\n### CLI\n\n#### Patch Changes\n\n- d2202b6: List all agent runs for unqualified targets, and reserve source-ref filtering for explicit `@ref` targets.\n\n---\n\n## 0.6.0 (2026-06-02)\n\n### CLI\n\n#### Minor Changes\n\n- 2aeeaf2: Add native source `git save` and branch-aware `git release` flows for Git-backed builder workspaces.\n\n#### Patch Changes\n\n- 2aeeaf2: Complete the agent Git cutover with pluralized agent CLI commands, source-ref run support, lockfile metadata, and regenerated SDK/docs surfaces.\n- 2aeeaf2: Expose Git-backed agent source refs and public source automation APIs consistently across CLI docs and SDK facades.\n\n### SDK\n\n#### Patch Changes\n\n- 2aeeaf2: Complete the agent Git cutover with pluralized agent CLI commands, source-ref run support, lockfile metadata, and regenerated SDK/docs surfaces.\n- 2aeeaf2: Expose Git-backed agent source refs and public source automation APIs consistently across CLI docs and SDK facades.\n\n---\n\n## 0.5.12 (2026-06-02)\n\n### CLI\n\n#### Minor Changes\n\n- d3b0768: Add `control.fail` and `ai.classify` step types, plus the `expected/error.json` dataset assertion format.\n - `control.fail` terminates a workflow with a typed status code + message envelope. Optional `condition` template gates the fail. Compose with `ai.classify` to reject documents that match an undesired label.\n - `ai.classify` runs single-label closed-set classification through the existing extract LLM pipeline. Output is `\\{ label, confidence, reason }`, where `label` is constrained to the configured names.\n - `examples/&lt;name&gt;/expected/error.json` (mutually exclusive with `output.json`) lets eval examples assert that a workflow should fail with a specific `\\{ code, messageContains, step }`. The exact-diff evaluator scores 1 on match, 0 otherwise.\n - `eigenpal workflow validate` now catches `expected/error.json` shape issues and per-step config violations (e.g. `ai.classify` with fewer than two labels) at push time instead of deferring to runtime.\n\n Skill reference docs (`step-types.md`, `dataset-format.md`, `evaluators.md`, `workflow-yaml.md`) updated.\n\n#### Patch Changes\n\n- 99cad97: Skill reference (auto-generated from `WorkflowDefinitionSchema`) now documents the new `values` row for enum inputs, alongside the existing `items` row used by array inputs. Output-only doc refresh — no CLI behavior change.\n- d70f697: Document the `control.parallel`, `control.parallel_map`, `control.foreach`, `control.if`, and `control.block` step types in the bundled skill reference. The auto-generated catalog cannot render nested step shapes, so the YAML form, output access paths (e.g. `steps.&lt;parallel&gt;.output.&lt;branch&gt;.&lt;inner&gt;.&lt;field&gt;`), and scoping rules now live as hand-written prose. Also documents the multi-step iteration hazard: only the LAST inner step's output is keyed into each `items[i]` for `parallel_map` / `foreach` — end the body with a `transform.script` if you need to preserve intermediate fields.\n- ed2cde6: Fix `eigenpal workflow pull` writing a 0-byte file. The v1 single-workflow endpoint now returns the current YAML at the top level (`yamlContent`) via a new `WorkflowDetail` response shape, and the CLI throws a clear error instead of silently writing empty output when no version has been published. Also fixes adjacent regressions caused by the same picker: `workflow list` now shows the workflow name and version columns (previously always `-`), `workflow push --bump` reads the server's current version correctly, the \"did you mean?\" suggestion on a slug typo lists candidates again, and `workflow execution list` shows a duration column computed from the run start/end timestamps.\n\n---\n\n## 0.5.11 (2026-05-26)\n\n### CLI\n\n#### Patch Changes\n\n- 2958f4d: Fix Git-backed source smoke-test polish: hidden `git show` and `git sync` now accept bare agent slugs, and workflow scaffolds use the current `triggerMethods` YAML shape.\n\n---\n\n## 0.5.10 (2026-05-26)\n\n### CLI\n\n#### Patch Changes\n\n- aee7e0c: Add hidden Git source commands for editing trigger policy and encrypted secrets.\n\n---\n\n## 0.5.9 (2026-05-26)\n\n### CLI\n\n#### Major Changes\n\n- fadb59b: CLI command tree reorganized around the data model. Top-level surface is now\n `workflow`, `agent` (reserved), and `skill`; everything that operates on a\n workflow lives under `workflow`, grouped by sub-entity.\n\n Renames (clean break — no aliases):\n - `eigenpal exec &lt;slug&gt;` → `eigenpal workflow execution run &lt;slug&gt;`\n - `eigenpal clear` → `eigenpal workflow clear`\n - `eigenpal install-skill` → `eigenpal skill` (same interactive multiselect UX)\n - `eigenpal execution \\{get,list,watch,compare}` → `eigenpal workflow execution \\{…}`\n - `eigenpal workflow set-definition` → `eigenpal workflow push`\n - `eigenpal workflow get-definition` → `eigenpal workflow pull`\n - `eigenpal workflow set-evaluators` / `get-evaluators` → `workflow evaluators \\{push,pull}`\n - `eigenpal workflow set-dataset` / `get-dataset` / `list-examples` → `workflow dataset \\{push,pull,list}`\n - `eigenpal workflow run-experiment` / `get-experiment-status` / `get-experiment-results` /\n `get-eval-results` / `list-executions` → `workflow experiment \\{run,status,results,eval-results,list}`\n - `eigenpal workflow list-versions` / `restore-version` → `workflow version \\{list,restore}`\n\n[View full release notes →](/releases/0.5.9)\n\n{/* GENERATED:CHANGELOG_INDEX END */}\n"
24
24
  },
25
25
  {
26
26
  "topic": "cli/agents",
@@ -118,7 +118,7 @@
118
118
  "title": "Workflow",
119
119
  "description": "Manage workflows: push, pull, and evaluate.",
120
120
  "source": "public",
121
- "content": "---\ntitle: \"Workflow\"\ndescription: \"Manage workflows: push, pull, and evaluate.\"\n---\n## Commands\n\n### Core\n\n| Command | Description |\n| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow list\\|ls [options]` | List workflows the caller can read. |\n| `eigenpal workflow pull [options] <workflow-id>` | Download the YAML definition of the workflow at its current version. |\n| `eigenpal workflow schema [options] <workflow-id>` | Show the inferred output schema for a workflow (what it returns). |\n| `eigenpal workflow push [options]` | Create or update a workflow from a YAML file. |\n| `eigenpal workflow move [options] <workflow-id>` | Move a workflow to a folder path, creating folders as needed |\n| `eigenpal workflow delete [options] <workflow-id>` | Delete a workflow definition while preserving past runs. |\n| `eigenpal workflow migrate-parser [options] <file>` | Write a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source. |\n| `eigenpal workflow validate [options] [path]` | Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/&lt;slug>/ or workflows/&lt;slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`. |\n| `eigenpal workflow clear-local [options] [examples...]` | Delete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default. |\n\n### Folders\n\n| Command | Description |\n| --------------------------------------------------------- | ----------------------------------------------------------- |\n| `eigenpal workflow folders list\\|ls [options]` | List workflow folders. |\n| `eigenpal workflow folders create [options] <path>` | Create a folder path, creating any missing parent segments. |\n| `eigenpal workflow folders rename [options] <path-or-id>` | Rename a workflow folder. |\n| `eigenpal workflow folders delete [options] <path-or-id>` | Delete a workflow folder. |\n\n### Evaluators\n\n| Command | Description |\n| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluators pull [options] <workflow-id>` | Download the workflow's evaluators YAML. |\n| `eigenpal workflow evaluators push [options] <workflow-id>` | Overwrite the workflow's evaluator config from a YAML file. |\n| `eigenpal workflow evaluators validate [options] [path]` | Validate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml. |\n\n### Dataset\n\n| Command | Description |\n| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow dataset list\\|ls [options] <workflow-id>` | List eval examples for the workflow. |\n| `eigenpal workflow dataset pull [options] <workflow-id>` | Download the workflow's dataset as a ZIP archive. |\n| `eigenpal workflow dataset push [options] <workflow-id>` | Replace or extend the workflow's dataset from a ZIP or folder. |\n| `eigenpal workflow dataset example create [options] <workflow-id>` | Create one eval example without re-uploading the dataset. |\n| `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>` | Patch one eval example. Omitted flags are left alone. |\n| `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>` | Delete one eval example by id. Non-TTY shells require --yes. |\n| `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>` | Fetch one eval example with full triggerInput, expectedOutput, and metadata. |\n| `eigenpal workflow dataset validate [options] [path]` | Validate a dataset folder against the examples/&lt;name>/&#123;input,expected,meta} convention. Defaults to ./dataset/. |\n| `eigenpal workflow dataset review-request list\\|ls [options] <automation-id>` | |\n| `eigenpal workflow dataset review-request create [options] <automation-id>` | Request human review of dataset ground truth. Snapshot examples and poll progress until review is complete. |\n| `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>` | Fetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events. |\n| `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>` | Update review metadata or lifecycle status. Set --status closed when review is finished. |\n| `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>` | List snapshotted review items and their statuses. |\n| `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>` | List review activity, including example and field notes. |\n| `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>` | Approve, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file. |\n| `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>` | Download review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON. |\n\n### Templates\n\n| Command | Description |\n| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow templates upload [options] <file>` | Upload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision. |\n| `eigenpal workflow templates list\\|ls [options]` | List workspace templates. |\n| `eigenpal workflow templates get\\|inspect [options] <template-id>` | Inspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar. |\n| `eigenpal workflow templates download [options] <template-id>` | Download current (or pinned) template bytes. |\n| `eigenpal workflow templates replace [options] <template-id> <file>` | Append an immutable revision and advance the tmpl\\_… pointer. |\n| `eigenpal workflow templates delete [options] <template-id>` | Delete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run. |\n| `eigenpal workflow templates smoke [options] <template>` | Fill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server. |\n\n### Experiment\n\n| Command | Description |\n| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| `eigenpal workflow experiment\\|exp list\\|ls [options] <workflow-id>` | List executions for the workflow, newest first. |\n| `eigenpal workflow experiment\\|exp run [options] <workflow-id>` | Start a batch eval against the workflow's dataset. |\n| `eigenpal workflow experiment\\|exp status [options] <workflow-id> <batchId>` | Aggregate progress for a batch by `batchId`. |\n| `eigenpal workflow experiment\\|exp cancel [options] <workflow-id> <batchId>` | Cancel every execution in a batch. Idempotent. |\n| `eigenpal workflow experiment\\|exp results [options] <workflow-id> [batchId]` | Download eval results in CSV or JSON. |\n| `eigenpal workflow experiment\\|exp compare\\|diff [options] <batchIdA> <batchIdB>` | Compare evaluator scores or actual outputs between two experiment batches. |\n| `eigenpal workflow experiment\\|exp watch [options] <workflow-id> <batchId>` | Poll until terminal, then auto-pull results, replaces `status --watch` + `results --out`. |\n\n### Versions\n\n| Command | Description |\n| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow versions list\\|ls [options] <workflow-id>` | List tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first. |\n| `eigenpal workflow versions create [options] <workflow-id>` | Create a tagged workflow version from YAML or by copying an existing snapshot. |\n| `eigenpal workflow versions promote [options] <workflow-id> <versionId>` | Make an existing tagged workflow version current without creating another snapshot. |\n| `eigenpal workflow versions restore [options] <workflow-id> <versionId>` | Restore a previous snapshot as a new untagged current version. Does not retag the source. |\n\n### Step-type\n\n| Command | Description |\n| -------------------------------------------------- | ------------------------------------------------------------- |\n| `eigenpal workflow step-type list\\|ls [options]` | List every step type the deployment supports. |\n| `eigenpal workflow step-type get [options] <type>` | Return the full schema and behavioral docs for one step type. |\n\n### Evaluator-type\n\n| Command | Description |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluator-type list\\|ls [options]` | List every evaluator type with a one-line description. |\n| `eigenpal workflow evaluator-type get [options] <type>` | Fetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields. |\n\n### Step\n\n| Command | Description |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow step exec [options] <type>` | DISABLED, local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead. |\n\n## Details\n\n### `eigenpal workflow list|ls [options]`\n\nList workflows the caller can read.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by name |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow pull [options] <workflow-id>`\n\nDownload the YAML definition of the workflow at its current version.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow schema [options] <workflow-id>`\n\nShow the inferred output schema for a workflow (what it returns).\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | -------- | ------------------------------- |\n| `--format <format>` | no | `\"json\"` | json \\| typescript \\| python |\n| `--out <path>` | no | | Write to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow push [options]`\n\nCreate or update a workflow from a YAML file.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to YAML file |\n| `--workflow-id <id>` | no | | Update existing workflow (default: create new) |\n| `--bump <level>` | no | | Auto-bump from the server's current version: patch \\| minor \\| major. Mutually exclusive with `--version` and with a top-level `version:` in the YAML. |\n| `--set-version <semver>` | no | | Push at this exact semver (e.g. 1.4.0). Mutually exclusive with `--bump` and with a top-level `version:` in the YAML. (Named `--set-version` to avoid the global `-v, --version` flag.) |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow move [options] <workflow-id>`\n\nMove a workflow to a folder path, creating folders as needed\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--folder <path>` | yes | | Target folder path (`/` for root) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow delete [options] <workflow-id>`\n\nDelete a workflow definition while preserving past runs.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow migrate-parser [options] <file>`\n\nWrite a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--policy <policy>` | yes | | preserve backend restrictions, or auto to adopt automatic native/OCR/vision parsing |\n| `--out <file>` | yes | | New YAML output file (must not already exist) |\n| `--json` | no | | Emit migration summary as JSON |\n\n### `eigenpal workflow validate [options] [path]`\n\nLocal-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/&lt;slug>/ or workflows/&lt;slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--dir <path>` | no | | Project root (defaults to cwd; resolves the three default paths from here) |\n| `--online` | no | | Authenticate and also validate action.invoke-workflow targets, transform.template tmpl\\_… references, and explicitly selected OCR/vision/text models against this tenant environment (existence, format, revision pairing, tokens vs data, XLSX &#123;&#123; }} mistakes, configured catalog). Local template: paths are inspected on disk with or without this flag. Model checks use the configured catalog only, they do not probe live provider health. |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow clear-local [options] [examples...]`\n\nDelete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `examples` | no | yes | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------- | -------- | ------- | ---------------------------------------------------------- |\n| `--dir <dir>` | no | | Local eigenpal directory |\n| `--all` | no | `false` | Remove all artifacts, including the latest kept by default |\n\n### `eigenpal workflow folders list|ls [options]`\n\nList workflow folders.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--tree` | no | | Render folders as an indented tree |\n\n### `eigenpal workflow folders create [options] <path>`\n\nCreate a folder path, creating any missing parent segments.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow folders rename [options] <path-or-id>`\n\nRename a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--name <name>` | yes | | New folder name |\n\n### `eigenpal workflow folders delete [options] <path-or-id>`\n\nDelete a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n\n### `eigenpal workflow evaluators pull [options] <workflow-id>`\n\nDownload the workflow's evaluators YAML.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow evaluators push [options] <workflow-id>`\n\nOverwrite the workflow's evaluator config from a YAML file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--file <yaml>` | yes | | Path to evaluators YAML file |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluators validate [options] [path]`\n\nValidate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset list|ls [options] <workflow-id>`\n\nList eval examples for the workflow.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `100` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset pull [options] <workflow-id>`\n\nDownload the workflow's dataset as a ZIP archive.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--out <zip>` | no | | Write the dataset ZIP to this path. When omitted, the binary streams to stdout. |\n| `--example-id <id>` | no | `[]` | Export only this example (repeatable). When omitted, the whole dataset is exported. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow dataset push [options] <workflow-id>`\n\nReplace or extend the workflow's dataset from a ZIP or folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------ |\n| `--file <path>` | yes | | Path to a dataset ZIP file or a dataset/ folder (folder is zipped in memory before upload) |\n| `--mode <append\\|replace>` | no | `\"append\"` | Import mode (default: append) |\n| `--yes` | no | `false` | Skip the destructive confirmation prompt for --mode replace (use in CI) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example create [options] <workflow-id>`\n\nCreate one eval example without re-uploading the dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | --------------------------------------------------- |\n| `--name <name>` | yes | | Example name (1–64 chars) |\n| `--input-json <json>` | no | | Trigger input as a JSON literal |\n| `--input-file <path>` | no | | Trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Expected output as a JSON literal |\n| `--expected-file <path>` | no | | Expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Free-form annotation |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>`\n\nPatch one eval example. Omitted flags are left alone.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | ----------------------------------------------------------- |\n| `--name <name>` | no | | Rename the example (1–64 chars) |\n| `--input-json <json>` | no | | Replace trigger input with this JSON literal |\n| `--input-file <path>` | no | | Replace trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Replace expected output with this JSON literal |\n| `--expected-file <path>` | no | | Replace expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Replace annotation; pass empty string to clear |\n| `--row-order <n>` | no | | Reorder the row (0-based) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>`\n\nDelete one eval example by id. Non-TTY shells require --yes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--yes` | no | `false` | Required for non-TTY shells; explicit acknowledgment that this is destructive |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>`\n\nFetch one eval example with full triggerInput, expectedOutput, and metadata.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset validate [options] [path]`\n\nValidate a dataset folder against the examples/&lt;name>/&#123;input,expected,meta} convention. Defaults to ./dataset/.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset review-request list|ls [options] <automation-id>`\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--status <csv>` | no | | Filter by review status (comma-separated: draft,open,paused,closed,cancelled) |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request create [options] <automation-id>`\n\nRequest human review of dataset ground truth. Snapshot examples and poll progress until review is complete.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | yes | | Review request title |\n| `--example-name <name>` | yes | `[]` | Example folder name to include (repeatable) |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Expected-output leaf path to flag across selected examples; parent paths flag every descendant (repeatable) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--ignore <path>` | no | `[]` | Expected-output path reviewers can skip (repeatable) |\n| `--item-note <spec>` | no | `[]` | Example-level note seeded at create time, as exampleName=comment (repeatable) |\n| `--field-note <spec>` | no | `[]` | Field comment only, as exampleName.path=comment; does not flag the field (repeatable) |\n| `--focus-json <json>` | no | | JSON array of &#123; path, reason? } focus fields |\n| `--notes-json <json>` | no | | JSON array of &#123; exampleName, comment?, fields?: [&#123; path, comment }] } |\n| `--status <draft\\|open\\|paused>` | no | | Initial lifecycle status (default: draft) |\n\n### `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>`\n\nFetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>`\n\nUpdate review metadata or lifecycle status. Set --status closed when review is finished.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | no | | New review request title |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Replace focus paths (repeatable; use with --focus-reason / --focus-json) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--focus-json <json>` | no | | JSON array of &#123; path, reason? } focus fields (replaces focus) |\n| `--ignore <path>` | no | | Replace ignored paths (repeatable) |\n| `--status <draft\\|open\\|paused\\|closed\\|cancelled>` | no | | Lifecycle status |\n\n### `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>`\n\nList snapshotted review items and their statuses.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--status <csv>` | no | | Filter by item status (pending,approved,edited,removed) |\n\n### `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>`\n\nList review activity, including example and field notes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>`\n\nApprove, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n| `item-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--action <approve\\|remove\\|reopen\\|comment\\|edit\\|field-decision\\|file-decision\\|edit-file>` | yes | | Item action |\n| `--expected-updated-at <iso>` | yes | | Item updatedAt the client last observed (optimistic concurrency) |\n| `--comment <text>` | no | | Note stored on the item, field, or file |\n| `--field-path <path>` | no | | Dotted expected-output path for comment or field-decision |\n| `--file-path <path>` | no | | Expected-file path for file-decision or edit-file (correct) |\n| `--new-path <path>` | no | | Expected-file path for edit-file uploads of brand-new reviewer files |\n| `--file <local path>` | no | | Local file bytes to upload when --action edit-file |\n| `--decision <approved\\|removed\\|null>` | no | | Field or file decision for --action field-decision or file-decision (null/clear removes it) |\n| `--clear` | no | `false` | Clear a field or file decision (sends decision: null) |\n| `--expected-json <json>` | no | | Replacement expected JSON when --action edit |\n\n### `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>`\n\nDownload review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ---------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--out <dir>` | yes | | Local directory to materialize the review into |\n\n### `eigenpal workflow templates upload [options] <file>`\n\nUpload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------------------------------- |\n| `--name <name>` | no | | Display name (defaults to the filename without extension) |\n| `--description <text>` | no | | Optional description |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates list|ls [options]`\n\nList workspace templates.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates get|inspect [options] <template-id>`\n\nInspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates download [options] <template-id>`\n\nDownload current (or pinned) template bytes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------- |\n| `--out <path>` | no | | Write to this file (required) |\n| `--revision-id <tmpr>` | no | | Pin an immutable tmpr\\_… revision |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow templates replace [options] <template-id> <file>`\n\nAppend an immutable revision and advance the tmpl\\_… pointer.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates delete [options] <template-id>`\n\nDelete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--yes` | no | `false` | Required for non-TTY shells |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates smoke [options] <template>`\n\nFill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `template` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ------------------------------------------------------------ |\n| `--data <file>` | yes | | Path to a JSON fixture file (object with template data keys) |\n| `--out <path>` | yes | | Filled DOCX/XLSX output path |\n| `--revision-id <tmpr>` | no | | When &lt;template> is a tmpl\\_… id, pin this revision |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp list|ls [options] <workflow-id>`\n\nList executions for the workflow, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--batch-id <id>` | no | | Filter by batch |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp run [options] <workflow-id>`\n\nStart a batch eval against the workflow's dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------- |\n| `--example-id <id>` | no | `[]` | Run only this example (repeatable) |\n| `--wait` | no | `false` | Poll until terminal; non-zero exit on passRate &lt; 1.0 |\n| `--interval <n>` | no | `10` | Polling interval in seconds (default 10) |\n| `--max-wait <seconds>` | no | `1800` | Maximum wait before exit code 2 (default 1800) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp status [options] <workflow-id> <batchId>`\n\nAggregate progress for a batch by `batchId`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--watch` | no | `false` | Poll until every execution reaches a terminal state (completed/failed/cancelled/rejected), then exit |\n| `--short` | no | `false` | Single-line plain-text summary on stdout (e.g. `6/6 done failed=0 cancelled=0 rejected=0`). Pipe-friendly for monitoring loops; mutually exclusive with --watch. |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds when --watch is set (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling for --watch in seconds (default 1800 = 30 min) |\n| `--include <kinds>` | no | `\"\"` | Comma-separated extras to attach when --watch terminates: payload (full per-execution snapshot, can be hundreds of KB) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp cancel [options] <workflow-id> <batchId>`\n\nCancel every execution in a batch. Idempotent.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------- |\n| `--yes` | no | | Required for non-TTY shells (CI, pipes). Acts immediately, no prompt. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp results [options] <workflow-id> [batchId]`\n\nDownload eval results in CSV or JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | -------- | ---------------------------------------------------------------------------------------- |\n| `--format <csv\\|json>` | no | `\"json\"` | Output format (default json) |\n| `--out <path>` | no | | Output file. When omitted, the binary streams to stdout. |\n| `--summary` | no | | Show total/pass/fail/error counts, average score, and evaluator rollups |\n| `--failed-only` | no | | Keep only failed or errored evaluator results |\n| `--evaluator <name>` | no | | Keep only results from this evaluator |\n| `--select <path>` | no | | Print only a nested JSON value (for example summary.byEvaluator or discrepancies[].path) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp compare|diff [options] <batchIdA> <batchIdB>`\n\nCompare evaluator scores or actual outputs between two experiment batches.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `batchIdA` | yes | no | |\n| `batchIdB` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------------------------------------ | -------- | ------------------ | ------------------------------------------------------ |\n| `--outputs` | no | | Compare actual run outputs instead of evaluator scores |\n| `--sort <abs-delta-desc\\|delta-asc\\|delta-desc\\|name>` | no | `\"abs-delta-desc\"` | Row sort order (default: biggest movers first) |\n| `--regression-threshold <n>` | no | `0.05` | Δ below this is flagged as a regression (default 0.05) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp watch [options] <workflow-id> <batchId>`\n\nPoll until terminal, then auto-pull results, replaces `status --watch` + `results --out`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------- | -------- | -------- | ----------------------------------------------------------------------- |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling in seconds (default 1800 = 30 min) |\n| `--pull-on-complete <path>` | no | | Destination for the results file. Default: ./results-&lt;batchId>.&lt;format> |\n| `--format <csv\\|json>` | no | `\"json\"` | Results export format (default json) |\n| `--no-pull` | no | | Skip auto-pulling results on terminal (watch only) |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow versions list|ls [options] <workflow-id>`\n\nList tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------- |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Print the sliced &#123; data, total, limit, offset } envelope as JSON (not the raw server payload) |\n\n### `eigenpal workflow versions create [options] <workflow-id>`\n\nCreate a tagged workflow version from YAML or by copying an existing snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to workflow YAML. Mutually exclusive with --from. |\n| `--allow-external-templates` | no | | Allow local template paths outside the workflow project. Use only for trusted YAML. |\n| `--from <version-id>` | no | | Existing version id to copy into a new tagged snapshot. Leaves the source tag unchanged. Mutually exclusive with --file. |\n| `--set-version <semver>` | no | | Bare semver tag such as 1.4.0. Required when copying with --from. For --file, omit this flag if the YAML already has a top-level version: field. (Named --set-version to avoid the global -v, --version flag.) |\n| `--no-activate` | no | | Keep the tagged version off live traffic until you promote it. Default is to make it current. Requires an existing current version. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions promote [options] <workflow-id> <versionId>`\n\nMake an existing tagged workflow version current without creating another snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions restore [options] <workflow-id> <versionId>`\n\nRestore a previous snapshot as a new untagged current version. Does not retag the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------ |\n| `--message <text>` | no | | Optional restore note stored on the new snapshot |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type list|ls [options]`\n\nList every step type the deployment supports.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type get [options] <type>`\n\nReturn the full schema and behavioral docs for one step type.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------- |\n| `--out <path>` | no | | Write to file |\n\n### `eigenpal workflow evaluator-type list|ls [options]`\n\nList every evaluator type with a one-line description.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by type, name, or description |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluator-type get [options] <type>`\n\nFetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------- |\n| `--out <path>` | no | | Write to file |\n\n### `eigenpal workflow step exec [options] <type>`\n\nDISABLED, local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | -------------------------------------- |\n| `--config-json <json>` | no | | (unused; kept for back-compat parsing) |\n| `--config-file <path>` | no | | (unused) |\n| `--inputs <pairs...>` | no | | (unused) |\n| `--output-schema <path>` | no | | (unused) |\n"
121
+ "content": "---\ntitle: \"Workflow\"\ndescription: \"Manage workflows: push, pull, and evaluate.\"\n---\n## Commands\n\n### Core\n\n| Command | Description |\n| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow list\\|ls [options]` | List workflows the caller can read. |\n| `eigenpal workflow get [options] <workflow-id>` | Show one workflow: name, current version, folder and your access level. |\n| `eigenpal workflow pull [options] <workflow-id>` | Download the YAML definition of the workflow at its current version. |\n| `eigenpal workflow schema [options] <workflow-id>` | Show the inferred output schema for a workflow (what it returns). |\n| `eigenpal workflow push [options]` | Create or update a workflow from a YAML file. |\n| `eigenpal workflow move [options] <workflow-id>` | Move a workflow to a folder path, creating folders as needed |\n| `eigenpal workflow delete [options] <workflow-id>` | Delete a workflow definition while preserving past runs. |\n| `eigenpal workflow migrate-parser [options] <file>` | Write a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source. |\n| `eigenpal workflow validate [options] [path]` | Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/&lt;slug>/ or workflows/&lt;slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`. |\n| `eigenpal workflow clear-local [options] [examples...]` | Delete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default. |\n\n### Folders\n\n| Command | Description |\n| --------------------------------------------------------- | ----------------------------------------------------------- |\n| `eigenpal workflow folders list\\|ls [options]` | List workflow folders. |\n| `eigenpal workflow folders create [options] <path>` | Create a folder path, creating any missing parent segments. |\n| `eigenpal workflow folders rename [options] <path-or-id>` | Rename a workflow folder. |\n| `eigenpal workflow folders delete [options] <path-or-id>` | Delete a workflow folder. |\n\n### Evaluators\n\n| Command | Description |\n| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluators pull [options] <workflow-id>` | Download the workflow's evaluators YAML. |\n| `eigenpal workflow evaluators push [options] <workflow-id>` | Overwrite the workflow's evaluator config from a YAML file. |\n| `eigenpal workflow evaluators validate [options] [path]` | Validate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml. |\n\n### Dataset\n\n| Command | Description |\n| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow dataset list\\|ls [options] <workflow-id>` | List eval examples for the workflow. |\n| `eigenpal workflow dataset pull [options] <workflow-id>` | Download the workflow's dataset as a ZIP archive. |\n| `eigenpal workflow dataset push [options] <workflow-id>` | Replace or extend the workflow's dataset from a ZIP or folder. |\n| `eigenpal workflow dataset example create [options] <workflow-id>` | Create one eval example without re-uploading the dataset. |\n| `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>` | Patch one eval example. Omitted flags are left alone. |\n| `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>` | Delete one eval example by id. Non-TTY shells require --yes. |\n| `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>` | Fetch one eval example with full triggerInput, expectedOutput, and metadata. |\n| `eigenpal workflow dataset validate [options] [path]` | Validate a dataset folder against the examples/&lt;name>/&#123;input,expected,meta} convention. Defaults to ./dataset/. |\n| `eigenpal workflow dataset review-request list\\|ls [options] <automation-id>` | |\n| `eigenpal workflow dataset review-request create [options] <automation-id>` | Request human review of dataset ground truth. Snapshot examples and poll progress until review is complete. |\n| `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>` | Fetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events. |\n| `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>` | Update review metadata or lifecycle status. Set --status closed when review is finished. |\n| `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>` | List snapshotted review items and their statuses. |\n| `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>` | List review activity, including example and field notes. |\n| `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>` | Approve, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file. |\n| `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>` | Download review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON. |\n\n### Templates\n\n| Command | Description |\n| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow templates upload [options] <file>` | Upload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision. |\n| `eigenpal workflow templates list\\|ls [options]` | List workspace templates. |\n| `eigenpal workflow templates get\\|inspect [options] <template-id>` | Inspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar. |\n| `eigenpal workflow templates download [options] <template-id>` | Download current (or pinned) template bytes. |\n| `eigenpal workflow templates replace [options] <template-id> <file>` | Append an immutable revision and advance the tmpl\\_… pointer. |\n| `eigenpal workflow templates delete [options] <template-id>` | Delete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run. |\n| `eigenpal workflow templates smoke [options] <template>` | Fill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server. |\n\n### Experiment\n\n| Command | Description |\n| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| `eigenpal workflow experiment\\|exp list\\|ls [options] <workflow-id>` | List executions for the workflow, newest first. |\n| `eigenpal workflow experiment\\|exp run [options] <workflow-id>` | Start a batch eval against the workflow's dataset. |\n| `eigenpal workflow experiment\\|exp status [options] <workflow-id> <batchId>` | Aggregate progress for a batch by `batchId`. |\n| `eigenpal workflow experiment\\|exp cancel [options] <workflow-id> <batchId>` | Cancel every execution in a batch. Idempotent. |\n| `eigenpal workflow experiment\\|exp results [options] <workflow-id> [batchId]` | Download eval results in CSV or JSON. |\n| `eigenpal workflow experiment\\|exp compare\\|diff [options] <batchIdA> <batchIdB>` | Compare evaluator scores or actual outputs between two experiment batches. |\n| `eigenpal workflow experiment\\|exp watch [options] <workflow-id> <batchId>` | Poll until terminal, then auto-pull results, replaces `status --watch` + `results --out`. |\n\n### Versions\n\n| Command | Description |\n| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow versions list\\|ls [options] <workflow-id>` | List tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first. |\n| `eigenpal workflow versions create [options] <workflow-id>` | Create a tagged workflow version from YAML or by copying an existing snapshot. |\n| `eigenpal workflow versions promote [options] <workflow-id> <versionId>` | Make an existing tagged workflow version current without creating another snapshot. |\n| `eigenpal workflow versions restore [options] <workflow-id> <versionId>` | Restore a previous snapshot as a new untagged current version. Does not retag the source. |\n\n### Step-type\n\n| Command | Description |\n| -------------------------------------------------- | ------------------------------------------------------------- |\n| `eigenpal workflow step-type list\\|ls [options]` | List every step type the deployment supports. |\n| `eigenpal workflow step-type get [options] <type>` | Return the full schema and behavioral docs for one step type. |\n\n### Evaluator-type\n\n| Command | Description |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluator-type list\\|ls [options]` | List every evaluator type with a one-line description. |\n| `eigenpal workflow evaluator-type get [options] <type>` | Fetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields. |\n\n### Step\n\n| Command | Description |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow step exec [options] <type>` | DISABLED, local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead. |\n\n## Details\n\n### `eigenpal workflow list|ls [options]`\n\nList workflows the caller can read.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by name |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow get [options] <workflow-id>`\n\nShow one workflow: name, current version, folder and your access level.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow pull [options] <workflow-id>`\n\nDownload the YAML definition of the workflow at its current version.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow schema [options] <workflow-id>`\n\nShow the inferred output schema for a workflow (what it returns).\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | -------- | ------------------------------- |\n| `--format <format>` | no | `\"json\"` | json \\| typescript \\| python |\n| `--out <path>` | no | | Write to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow push [options]`\n\nCreate or update a workflow from a YAML file.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to YAML file |\n| `--workflow-id <id>` | no | | Update existing workflow (default: create new) |\n| `--bump <level>` | no | | Auto-bump from the server's current version: patch \\| minor \\| major. Mutually exclusive with `--version` and with a top-level `version:` in the YAML. |\n| `--set-version <semver>` | no | | Push at this exact semver (e.g. 1.4.0). Mutually exclusive with `--bump` and with a top-level `version:` in the YAML. (Named `--set-version` to avoid the global `-v, --version` flag.) |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow move [options] <workflow-id>`\n\nMove a workflow to a folder path, creating folders as needed\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--folder <path>` | yes | | Target folder path (`/` for root) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow delete [options] <workflow-id>`\n\nDelete a workflow definition while preserving past runs.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow migrate-parser [options] <file>`\n\nWrite a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--policy <policy>` | yes | | preserve backend restrictions, or auto to adopt automatic native/OCR/vision parsing |\n| `--out <file>` | yes | | New YAML output file (must not already exist) |\n| `--json` | no | | Emit migration summary as JSON |\n\n### `eigenpal workflow validate [options] [path]`\n\nLocal-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/&lt;slug>/ or workflows/&lt;slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--dir <path>` | no | | Project root (defaults to cwd; resolves the three default paths from here) |\n| `--online` | no | | Authenticate and also validate action.invoke-workflow targets, transform.template tmpl\\_… references, and explicitly selected OCR/vision/text models against this tenant environment (existence, format, revision pairing, tokens vs data, XLSX &#123;&#123; }} mistakes, configured catalog). Local template: paths are inspected on disk with or without this flag. Model checks use the configured catalog only, they do not probe live provider health. |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow clear-local [options] [examples...]`\n\nDelete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `examples` | no | yes | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------- | -------- | ------- | ---------------------------------------------------------- |\n| `--dir <dir>` | no | | Local eigenpal directory |\n| `--all` | no | `false` | Remove all artifacts, including the latest kept by default |\n\n### `eigenpal workflow folders list|ls [options]`\n\nList workflow folders.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--tree` | no | | Render folders as an indented tree |\n\n### `eigenpal workflow folders create [options] <path>`\n\nCreate a folder path, creating any missing parent segments.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow folders rename [options] <path-or-id>`\n\nRename a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--name <name>` | yes | | New folder name |\n\n### `eigenpal workflow folders delete [options] <path-or-id>`\n\nDelete a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n\n### `eigenpal workflow evaluators pull [options] <workflow-id>`\n\nDownload the workflow's evaluators YAML.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow evaluators push [options] <workflow-id>`\n\nOverwrite the workflow's evaluator config from a YAML file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--file <yaml>` | yes | | Path to evaluators YAML file |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluators validate [options] [path]`\n\nValidate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset list|ls [options] <workflow-id>`\n\nList eval examples for the workflow.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `100` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset pull [options] <workflow-id>`\n\nDownload the workflow's dataset as a ZIP archive.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--out <zip>` | no | | Write the dataset ZIP to this path. When omitted, the binary streams to stdout. |\n| `--example-id <id>` | no | `[]` | Export only this example (repeatable). When omitted, the whole dataset is exported. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow dataset push [options] <workflow-id>`\n\nReplace or extend the workflow's dataset from a ZIP or folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------ |\n| `--file <path>` | yes | | Path to a dataset ZIP file or a dataset/ folder (folder is zipped in memory before upload) |\n| `--mode <append\\|replace>` | no | `\"append\"` | Import mode (default: append) |\n| `--yes` | no | `false` | Skip the destructive confirmation prompt for --mode replace (use in CI) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example create [options] <workflow-id>`\n\nCreate one eval example without re-uploading the dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | --------------------------------------------------- |\n| `--name <name>` | yes | | Example name (1–64 chars) |\n| `--input-json <json>` | no | | Trigger input as a JSON literal |\n| `--input-file <path>` | no | | Trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Expected output as a JSON literal |\n| `--expected-file <path>` | no | | Expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Free-form annotation |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>`\n\nPatch one eval example. Omitted flags are left alone.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | ----------------------------------------------------------- |\n| `--name <name>` | no | | Rename the example (1–64 chars) |\n| `--input-json <json>` | no | | Replace trigger input with this JSON literal |\n| `--input-file <path>` | no | | Replace trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Replace expected output with this JSON literal |\n| `--expected-file <path>` | no | | Replace expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Replace annotation; pass empty string to clear |\n| `--row-order <n>` | no | | Reorder the row (0-based) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>`\n\nDelete one eval example by id. Non-TTY shells require --yes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--yes` | no | `false` | Required for non-TTY shells; explicit acknowledgment that this is destructive |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>`\n\nFetch one eval example with full triggerInput, expectedOutput, and metadata.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset validate [options] [path]`\n\nValidate a dataset folder against the examples/&lt;name>/&#123;input,expected,meta} convention. Defaults to ./dataset/.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset review-request list|ls [options] <automation-id>`\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--status <csv>` | no | | Filter by review status (comma-separated: draft,open,paused,closed,cancelled) |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request create [options] <automation-id>`\n\nRequest human review of dataset ground truth. Snapshot examples and poll progress until review is complete.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | yes | | Review request title |\n| `--example-name <name>` | yes | `[]` | Example folder name to include (repeatable) |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Expected-output leaf path to flag across selected examples; parent paths flag every descendant (repeatable) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--ignore <path>` | no | `[]` | Expected-output path reviewers can skip (repeatable) |\n| `--item-note <spec>` | no | `[]` | Example-level note seeded at create time, as exampleName=comment (repeatable) |\n| `--field-note <spec>` | no | `[]` | Field comment only, as exampleName.path=comment; does not flag the field (repeatable) |\n| `--focus-json <json>` | no | | JSON array of &#123; path, reason? } focus fields |\n| `--notes-json <json>` | no | | JSON array of &#123; exampleName, comment?, fields?: [&#123; path, comment }] } |\n| `--status <draft\\|open\\|paused>` | no | | Initial lifecycle status (default: draft) |\n\n### `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>`\n\nFetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>`\n\nUpdate review metadata or lifecycle status. Set --status closed when review is finished.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | no | | New review request title |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Replace focus paths (repeatable; use with --focus-reason / --focus-json) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--focus-json <json>` | no | | JSON array of &#123; path, reason? } focus fields (replaces focus) |\n| `--ignore <path>` | no | | Replace ignored paths (repeatable) |\n| `--status <draft\\|open\\|paused\\|closed\\|cancelled>` | no | | Lifecycle status |\n\n### `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>`\n\nList snapshotted review items and their statuses.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--status <csv>` | no | | Filter by item status (pending,approved,edited,removed) |\n\n### `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>`\n\nList review activity, including example and field notes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>`\n\nApprove, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n| `item-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--action <approve\\|remove\\|reopen\\|comment\\|edit\\|field-decision\\|file-decision\\|edit-file>` | yes | | Item action |\n| `--expected-updated-at <iso>` | yes | | Item updatedAt the client last observed (optimistic concurrency) |\n| `--comment <text>` | no | | Note stored on the item, field, or file |\n| `--field-path <path>` | no | | Dotted expected-output path for comment or field-decision |\n| `--file-path <path>` | no | | Expected-file path for file-decision or edit-file (correct) |\n| `--new-path <path>` | no | | Expected-file path for edit-file uploads of brand-new reviewer files |\n| `--file <local path>` | no | | Local file bytes to upload when --action edit-file |\n| `--decision <approved\\|removed\\|null>` | no | | Field or file decision for --action field-decision or file-decision (null/clear removes it) |\n| `--clear` | no | `false` | Clear a field or file decision (sends decision: null) |\n| `--expected-json <json>` | no | | Replacement expected JSON when --action edit |\n\n### `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>`\n\nDownload review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ---------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--out <dir>` | yes | | Local directory to materialize the review into |\n\n### `eigenpal workflow templates upload [options] <file>`\n\nUpload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------------------------------- |\n| `--name <name>` | no | | Display name (defaults to the filename without extension) |\n| `--description <text>` | no | | Optional description |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates list|ls [options]`\n\nList workspace templates.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates get|inspect [options] <template-id>`\n\nInspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates download [options] <template-id>`\n\nDownload current (or pinned) template bytes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------- |\n| `--out <path>` | no | | Write to this file (required) |\n| `--revision-id <tmpr>` | no | | Pin an immutable tmpr\\_… revision |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow templates replace [options] <template-id> <file>`\n\nAppend an immutable revision and advance the tmpl\\_… pointer.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates delete [options] <template-id>`\n\nDelete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--yes` | no | `false` | Required for non-TTY shells |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates smoke [options] <template>`\n\nFill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `template` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ------------------------------------------------------------ |\n| `--data <file>` | yes | | Path to a JSON fixture file (object with template data keys) |\n| `--out <path>` | yes | | Filled DOCX/XLSX output path |\n| `--revision-id <tmpr>` | no | | When &lt;template> is a tmpl\\_… id, pin this revision |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp list|ls [options] <workflow-id>`\n\nList executions for the workflow, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--batch-id <id>` | no | | Filter by batch |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp run [options] <workflow-id>`\n\nStart a batch eval against the workflow's dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------- |\n| `--example-id <id>` | no | `[]` | Run only this example (repeatable) |\n| `--wait` | no | `false` | Poll until terminal; non-zero exit on passRate &lt; 1.0 |\n| `--interval <n>` | no | `10` | Polling interval in seconds (default 10) |\n| `--max-wait <seconds>` | no | `1800` | Maximum wait before exit code 2 (default 1800) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp status [options] <workflow-id> <batchId>`\n\nAggregate progress for a batch by `batchId`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--watch` | no | `false` | Poll until every execution reaches a terminal state (completed/failed/cancelled/rejected), then exit |\n| `--short` | no | `false` | Single-line plain-text summary on stdout (e.g. `6/6 done failed=0 cancelled=0 rejected=0`). Pipe-friendly for monitoring loops; mutually exclusive with --watch. |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds when --watch is set (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling for --watch in seconds (default 1800 = 30 min) |\n| `--include <kinds>` | no | `\"\"` | Comma-separated extras to attach when --watch terminates: payload (full per-execution snapshot, can be hundreds of KB) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp cancel [options] <workflow-id> <batchId>`\n\nCancel every execution in a batch. Idempotent.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------- |\n| `--yes` | no | | Required for non-TTY shells (CI, pipes). Acts immediately, no prompt. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp results [options] <workflow-id> [batchId]`\n\nDownload eval results in CSV or JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | -------- | ---------------------------------------------------------------------------------------- |\n| `--format <csv\\|json>` | no | `\"json\"` | Output format (default json) |\n| `--out <path>` | no | | Output file. When omitted, the binary streams to stdout. |\n| `--summary` | no | | Show total/pass/fail/error counts, average score, and evaluator rollups |\n| `--failed-only` | no | | Keep only failed or errored evaluator results |\n| `--evaluator <name>` | no | | Keep only results from this evaluator |\n| `--select <path>` | no | | Print only a nested JSON value (for example summary.byEvaluator or discrepancies[].path) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp compare|diff [options] <batchIdA> <batchIdB>`\n\nCompare evaluator scores or actual outputs between two experiment batches.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `batchIdA` | yes | no | |\n| `batchIdB` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------------------------------------ | -------- | ------------------ | ------------------------------------------------------ |\n| `--outputs` | no | | Compare actual run outputs instead of evaluator scores |\n| `--sort <abs-delta-desc\\|delta-asc\\|delta-desc\\|name>` | no | `\"abs-delta-desc\"` | Row sort order (default: biggest movers first) |\n| `--regression-threshold <n>` | no | `0.05` | Δ below this is flagged as a regression (default 0.05) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp watch [options] <workflow-id> <batchId>`\n\nPoll until terminal, then auto-pull results, replaces `status --watch` + `results --out`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------- | -------- | -------- | ----------------------------------------------------------------------- |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling in seconds (default 1800 = 30 min) |\n| `--pull-on-complete <path>` | no | | Destination for the results file. Default: ./results-&lt;batchId>.&lt;format> |\n| `--format <csv\\|json>` | no | `\"json\"` | Results export format (default json) |\n| `--no-pull` | no | | Skip auto-pulling results on terminal (watch only) |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow versions list|ls [options] <workflow-id>`\n\nList tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------- |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Print the sliced &#123; data, total, limit, offset } envelope as JSON (not the raw server payload) |\n\n### `eigenpal workflow versions create [options] <workflow-id>`\n\nCreate a tagged workflow version from YAML or by copying an existing snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to workflow YAML. Mutually exclusive with --from. |\n| `--allow-external-templates` | no | | Allow local template paths outside the workflow project. Use only for trusted YAML. |\n| `--from <version-id>` | no | | Existing version id to copy into a new tagged snapshot. Leaves the source tag unchanged. Mutually exclusive with --file. |\n| `--set-version <semver>` | no | | Bare semver tag such as 1.4.0. Required when copying with --from. For --file, omit this flag if the YAML already has a top-level version: field. (Named --set-version to avoid the global -v, --version flag.) |\n| `--no-activate` | no | | Keep the tagged version off live traffic until you promote it. Default is to make it current. Requires an existing current version. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions promote [options] <workflow-id> <versionId>`\n\nMake an existing tagged workflow version current without creating another snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions restore [options] <workflow-id> <versionId>`\n\nRestore a previous snapshot as a new untagged current version. Does not retag the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------ |\n| `--message <text>` | no | | Optional restore note stored on the new snapshot |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type list|ls [options]`\n\nList every step type the deployment supports.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type get [options] <type>`\n\nReturn the full schema and behavioral docs for one step type.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write to file |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluator-type list|ls [options]`\n\nList every evaluator type with a one-line description.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by type, name, or description |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluator-type get [options] <type>`\n\nFetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------- |\n| `--out <path>` | no | | Write to file |\n\n### `eigenpal workflow step exec [options] <type>`\n\nDISABLED, local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | -------------------------------------- |\n| `--config-json <json>` | no | | (unused; kept for back-compat parsing) |\n| `--config-file <path>` | no | | (unused) |\n| `--inputs <pairs...>` | no | | (unused) |\n| `--output-schema <path>` | no | | (unused) |\n"
122
122
  },
123
123
  {
124
124
  "topic": "concepts/agents",
@@ -412,14 +412,14 @@
412
412
  "title": "eigenpal CLI surface",
413
413
  "description": "Detailed agent reference bundled with the Eigenpal CLI.",
414
414
  "source": "agent-reference",
415
- "content": "# eigenpal CLI surface\n\nGenerated from the live Commander command tree in `packages/cli/src/cli.ts`. Do not edit this file by hand; run `bun run --cwd packages/cli generate`.\n\n```\neigenpal\n├── status\n├── init [name]\n│ └── workflow <name>\n├── auth\n│ ├── login\n│ ├── logout [profile]\n│ ├── list|ls\n│ ├── use [profile]\n│ └── status|whoami\n├── workflow\n│ ├── list|ls\n│ ├── pull <workflow-id>\n│ ├── schema <workflow-id>\n│ ├── push\n│ ├── move <workflow-id>\n│ ├── delete <workflow-id>\n│ ├── migrate-parser <file>\n│ ├── folders\n│ │ ├── list|ls\n│ │ ├── create <path>\n│ │ ├── rename <path-or-id>\n│ │ └── delete <path-or-id>\n│ ├── evaluators\n│ │ ├── pull <workflow-id>\n│ │ ├── push <workflow-id>\n│ │ └── validate [path]\n│ ├── dataset\n│ │ ├── list|ls <workflow-id>\n│ │ ├── pull <workflow-id>\n│ │ ├── push <workflow-id>\n│ │ ├── example\n│ │ │ ├── create <workflow-id>\n│ │ │ ├── update <workflow-id> <exampleId>\n│ │ │ ├── delete <workflow-id> <exampleId>\n│ │ │ └── get <workflow-id> <exampleId>\n│ │ ├── validate [path]\n│ │ └── review-request\n│ │ ├── list|ls <automation-id>\n│ │ ├── create <automation-id>\n│ │ ├── get <automation-id> <review-id>\n│ │ ├── update <automation-id> <review-id>\n│ │ ├── items <automation-id> <review-id>\n│ │ ├── events <automation-id> <review-id>\n│ │ ├── item <automation-id> <review-id> <item-id>\n│ │ └── pull <automation-id> <review-id>\n│ ├── templates\n│ │ ├── upload <file>\n│ │ ├── list|ls\n│ │ ├── get|inspect <template-id>\n│ │ ├── download <template-id>\n│ │ ├── replace <template-id> <file>\n│ │ ├── delete <template-id>\n│ │ └── smoke <template>\n│ ├── experiment|exp\n│ │ ├── list|ls <workflow-id>\n│ │ ├── run <workflow-id>\n│ │ ├── status <workflow-id> <batchId>\n│ │ ├── cancel <workflow-id> <batchId>\n│ │ ├── results <workflow-id> [batchId]\n│ │ ├── compare|diff <batchIdA> <batchIdB>\n│ │ └── watch <workflow-id> <batchId>\n│ ├── versions\n│ │ ├── list|ls <workflow-id>\n│ │ ├── create <workflow-id>\n│ │ ├── promote <workflow-id> <versionId>\n│ │ └── restore <workflow-id> <versionId>\n│ ├── step-type\n│ │ ├── list|ls\n│ │ └── get <type>\n│ ├── evaluator-type\n│ │ ├── list|ls\n│ │ └── get <type>\n│ ├── validate [path]\n│ ├── clear-local [examples...]\n│ └── step\n│ └── exec <type>\n├── agents\n│ ├── list|ls\n│ ├── delete <agent-id-or-slug>\n│ ├── file\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── get <agent-id-or-slug> <remote-path>\n│ │ └── diff <agent-id-or-slug> <remote-path> <local-path>\n│ ├── validate [dir]\n│ ├── clone\n│ ├── install [packageRef]\n│ ├── init <name>\n│ ├── pull\n│ ├── commit\n│ ├── save\n│ ├── push\n│ ├── upgrade\n│ ├── doctor\n│ ├── status\n│ ├── deps\n│ ├── clean\n│ ├── show <automation>\n│ ├── versions <package>\n│ ├── release <version> [dir]\n│ ├── sync [automation]\n│ ├── secrets|secret\n│ │ ├── list|ls\n│ │ ├── set <name>\n│ │ ├── unset <name>\n│ │ ├── import <env-file>\n│ │ └── export [target]\n│ ├── dataset\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── push <agent-id-or-slug>\n│ │ ├── pull <agent-id-or-slug>\n│ │ ├── validate [path]\n│ │ └── review-request\n│ │ ├── list|ls <automation-id>\n│ │ ├── create <automation-id>\n│ │ ├── get <automation-id> <review-id>\n│ │ ├── update <automation-id> <review-id>\n│ │ ├── items <automation-id> <review-id>\n│ │ ├── events <automation-id> <review-id>\n│ │ ├── item <automation-id> <review-id> <item-id>\n│ │ └── pull <automation-id> <review-id>\n│ ├── experiment|exp\n│ │ ├── run <agent-id-or-slug>\n│ │ ├── status <agent-id-or-slug> <batch-id>\n│ │ ├── results <agent-id-or-slug> [batch-id]\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── compare|diff <batch-id-a> <batch-id-b>\n│ │ └── cancel <agent-id-or-slug> <batch-id>\n│ ├── session\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── get <session-id>\n│ │ ├── start <agent-id-or-slug>\n│ │ ├── message <session-id>\n│ │ └── stop <session-id>\n│ └── env\n│ └── pull [target]\n├── models\n│ ├── parser-readiness\n│ └── list|ls\n├── email-servers|email-server\n│ ├── list|ls\n│ ├── get <id>\n│ ├── create\n│ ├── update <id>\n│ ├── delete <id>\n│ └── test <id>\n├── run <target>\n├── rerun <run-id>\n├── runs\n│ ├── list|ls [source]\n│ ├── get <run-id>\n│ ├── compare|diff <reference-run-id> <run-id>\n│ ├── rerun <run-id>\n│ ├── promote <run-id>\n│ ├── artifacts|artifact\n│ │ ├── list|ls <run-id>\n│ │ ├── fetch <run-id>\n│ │ └── inspect [run-id] [artifact-path]\n│ ├── trace <run-id>\n│ ├── reviews|rv\n│ │ ├── update <run-id>\n│ │ ├── close <run-id>\n│ │ └── clear <run-id>\n│ ├── expected\n│ │ ├── list|ls <run-id>\n│ │ ├── pull <run-id>\n│ │ ├── upload <run-id> <file>\n│ │ ├── copy-output <run-id> <output-file>\n│ │ ├── rename <run-id> <old-name> <new-name>\n│ │ └── delete <run-id> <name>\n│ ├── watch <run-id>\n│ └── cancel <run-id>\n├── reviews|rv\n│ ├── list|ls\n│ ├── get <task-id>\n│ ├── confirm <task-id>\n│ ├── approve <task-id>\n│ ├── reject <task-id>\n│ └── download <task-id> <file-id>\n├── docs\n│ ├── list|ls [prefix]\n│ ├── search <query>\n│ └── read <topic>\n└── skill\n ├── install\n ├── uninstall [toolIds...]\n └── list|ls\n```\n"
415
+ "content": "# eigenpal CLI surface\n\nGenerated from the live Commander command tree in `packages/cli/src/cli.ts`. Do not edit this file by hand; run `bun run --cwd packages/cli generate`.\n\n```\neigenpal\n├── status\n├── init [name]\n│ └── workflow <name>\n├── auth\n│ ├── login\n│ ├── logout [profile]\n│ ├── list|ls\n│ ├── use [profile]\n│ └── status|whoami\n├── workflow\n│ ├── list|ls\n│ ├── get <workflow-id>\n│ ├── pull <workflow-id>\n│ ├── schema <workflow-id>\n│ ├── push\n│ ├── move <workflow-id>\n│ ├── delete <workflow-id>\n│ ├── migrate-parser <file>\n│ ├── folders\n│ │ ├── list|ls\n│ │ ├── create <path>\n│ │ ├── rename <path-or-id>\n│ │ └── delete <path-or-id>\n│ ├── evaluators\n│ │ ├── pull <workflow-id>\n│ │ ├── push <workflow-id>\n│ │ └── validate [path]\n│ ├── dataset\n│ │ ├── list|ls <workflow-id>\n│ │ ├── pull <workflow-id>\n│ │ ├── push <workflow-id>\n│ │ ├── example\n│ │ │ ├── create <workflow-id>\n│ │ │ ├── update <workflow-id> <exampleId>\n│ │ │ ├── delete <workflow-id> <exampleId>\n│ │ │ └── get <workflow-id> <exampleId>\n│ │ ├── validate [path]\n│ │ └── review-request\n│ │ ├── list|ls <automation-id>\n│ │ ├── create <automation-id>\n│ │ ├── get <automation-id> <review-id>\n│ │ ├── update <automation-id> <review-id>\n│ │ ├── items <automation-id> <review-id>\n│ │ ├── events <automation-id> <review-id>\n│ │ ├── item <automation-id> <review-id> <item-id>\n│ │ └── pull <automation-id> <review-id>\n│ ├── templates\n│ │ ├── upload <file>\n│ │ ├── list|ls\n│ │ ├── get|inspect <template-id>\n│ │ ├── download <template-id>\n│ │ ├── replace <template-id> <file>\n│ │ ├── delete <template-id>\n│ │ └── smoke <template>\n│ ├── experiment|exp\n│ │ ├── list|ls <workflow-id>\n│ │ ├── run <workflow-id>\n│ │ ├── status <workflow-id> <batchId>\n│ │ ├── cancel <workflow-id> <batchId>\n│ │ ├── results <workflow-id> [batchId]\n│ │ ├── compare|diff <batchIdA> <batchIdB>\n│ │ └── watch <workflow-id> <batchId>\n│ ├── versions\n│ │ ├── list|ls <workflow-id>\n│ │ ├── create <workflow-id>\n│ │ ├── promote <workflow-id> <versionId>\n│ │ └── restore <workflow-id> <versionId>\n│ ├── step-type\n│ │ ├── list|ls\n│ │ └── get <type>\n│ ├── evaluator-type\n│ │ ├── list|ls\n│ │ └── get <type>\n│ ├── validate [path]\n│ ├── clear-local [examples...]\n│ └── step\n│ └── exec <type>\n├── agents\n│ ├── list|ls\n│ ├── delete <agent-id-or-slug>\n│ ├── file\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── get <agent-id-or-slug> <remote-path>\n│ │ └── diff <agent-id-or-slug> <remote-path> <local-path>\n│ ├── validate [dir]\n│ ├── clone\n│ ├── install [packageRef]\n│ ├── init <name>\n│ ├── pull\n│ ├── commit\n│ ├── save\n│ ├── push\n│ ├── upgrade\n│ ├── doctor\n│ ├── status\n│ ├── deps\n│ ├── clean\n│ ├── show <automation>\n│ ├── versions <package>\n│ ├── release <version> [dir]\n│ ├── sync [automation]\n│ ├── secrets|secret\n│ │ ├── list|ls\n│ │ ├── set <name>\n│ │ ├── unset <name>\n│ │ ├── import <env-file>\n│ │ └── export [target]\n│ ├── dataset\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── push <agent-id-or-slug>\n│ │ ├── pull <agent-id-or-slug>\n│ │ ├── validate [path]\n│ │ └── review-request\n│ │ ├── list|ls <automation-id>\n│ │ ├── create <automation-id>\n│ │ ├── get <automation-id> <review-id>\n│ │ ├── update <automation-id> <review-id>\n│ │ ├── items <automation-id> <review-id>\n│ │ ├── events <automation-id> <review-id>\n│ │ ├── item <automation-id> <review-id> <item-id>\n│ │ └── pull <automation-id> <review-id>\n│ ├── experiment|exp\n│ │ ├── run <agent-id-or-slug>\n│ │ ├── status <agent-id-or-slug> <batch-id>\n│ │ ├── results <agent-id-or-slug> [batch-id]\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── compare|diff <batch-id-a> <batch-id-b>\n│ │ └── cancel <agent-id-or-slug> <batch-id>\n│ ├── session\n│ │ ├── list|ls <agent-id-or-slug>\n│ │ ├── get <session-id>\n│ │ ├── start <agent-id-or-slug>\n│ │ ├── message <session-id>\n│ │ └── stop <session-id>\n│ └── env\n│ └── pull [target]\n├── models\n│ ├── parser-readiness\n│ └── list|ls\n├── email-servers|email-server\n│ ├── list|ls\n│ ├── get <id>\n│ ├── create\n│ ├── update <id>\n│ ├── delete <id>\n│ └── test <id>\n├── run <target>\n├── rerun <run-id>\n├── runs\n│ ├── list|ls [source]\n│ ├── get <run-id>\n│ ├── compare|diff <reference-run-id> <run-id>\n│ ├── rerun <run-id>\n│ ├── promote <run-id>\n│ ├── artifacts|artifact\n│ │ ├── list|ls <run-id>\n│ │ ├── fetch <run-id>\n│ │ └── inspect [run-id] [artifact-path]\n│ ├── trace <run-id>\n│ ├── reviews|rv\n│ │ ├── update <run-id>\n│ │ ├── close <run-id>\n│ │ └── clear <run-id>\n│ ├── expected\n│ │ ├── list|ls <run-id>\n│ │ ├── pull <run-id>\n│ │ ├── upload <run-id> <file>\n│ │ ├── copy-output <run-id> <output-file>\n│ │ ├── rename <run-id> <old-name> <new-name>\n│ │ └── delete <run-id> <name>\n│ ├── watch <run-id>\n│ └── cancel <run-id>\n├── reviews|rv\n│ ├── list|ls\n│ ├── get <task-id>\n│ ├── confirm <task-id>\n│ ├── approve <task-id>\n│ ├── reject <task-id>\n│ └── download <task-id> <file-id>\n├── docs\n│ ├── list|ls [prefix]\n│ ├── search <query>\n│ └── read <topic>\n└── skill\n ├── install\n ├── uninstall [toolIds...]\n └── list|ls\n```\n"
416
416
  },
417
417
  {
418
418
  "topic": "reference/cli/workflow",
419
419
  "title": "eigenpal workflow",
420
420
  "description": "Detailed agent reference bundled with the Eigenpal CLI.",
421
421
  "source": "agent-reference",
422
- "content": "# eigenpal workflow\n\nManage workflows: push, pull, and evaluate.\n\n## Contents\n\n- [Surface](#surface)\n- [Commands](#commands)\n - [Core](#core)\n - [Folders](#folders)\n - [Evaluators](#evaluators)\n - [Dataset](#dataset)\n - [Templates](#templates)\n - [Experiment](#experiment)\n - [Versions](#versions)\n - [Step-type](#step-type)\n - [Evaluator-type](#evaluator-type)\n - [Step](#step)\n- [Details](#details)\n - [`eigenpal workflow list|ls [options]`](#eigenpal-workflow-listls-options)\n - [`eigenpal workflow pull [options] <workflow-id>`](#eigenpal-workflow-pull-options-workflow-id)\n - [`eigenpal workflow schema [options] <workflow-id>`](#eigenpal-workflow-schema-options-workflow-id)\n - [`eigenpal workflow push [options]`](#eigenpal-workflow-push-options)\n - [`eigenpal workflow move [options] <workflow-id>`](#eigenpal-workflow-move-options-workflow-id)\n - [`eigenpal workflow delete [options] <workflow-id>`](#eigenpal-workflow-delete-options-workflow-id)\n - [`eigenpal workflow migrate-parser [options] <file>`](#eigenpal-workflow-migrate-parser-options-file)\n - [`eigenpal workflow validate [options] [path]`](#eigenpal-workflow-validate-options-path)\n - [`eigenpal workflow clear-local [options] [examples...]`](#eigenpal-workflow-clear-local-options-examples)\n - [`eigenpal workflow folders list|ls [options]`](#eigenpal-workflow-folders-listls-options)\n - [`eigenpal workflow folders create [options] <path>`](#eigenpal-workflow-folders-create-options-path)\n - [`eigenpal workflow folders rename [options] <path-or-id>`](#eigenpal-workflow-folders-rename-options-path-or-id)\n - [`eigenpal workflow folders delete [options] <path-or-id>`](#eigenpal-workflow-folders-delete-options-path-or-id)\n - [`eigenpal workflow evaluators pull [options] <workflow-id>`](#eigenpal-workflow-evaluators-pull-options-workflow-id)\n - [`eigenpal workflow evaluators push [options] <workflow-id>`](#eigenpal-workflow-evaluators-push-options-workflow-id)\n - [`eigenpal workflow evaluators validate [options] [path]`](#eigenpal-workflow-evaluators-validate-options-path)\n - [`eigenpal workflow dataset list|ls [options] <workflow-id>`](#eigenpal-workflow-dataset-listls-options-workflow-id)\n - [`eigenpal workflow dataset pull [options] <workflow-id>`](#eigenpal-workflow-dataset-pull-options-workflow-id)\n - [`eigenpal workflow dataset push [options] <workflow-id>`](#eigenpal-workflow-dataset-push-options-workflow-id)\n - [`eigenpal workflow dataset example create [options] <workflow-id>`](#eigenpal-workflow-dataset-example-create-options-workflow-id)\n - [`eigenpal workflow dataset example update [options] <workflow-id> <exampleId>`](#eigenpal-workflow-dataset-example-update-options-workflow-id-exampleid)\n - [`eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>`](#eigenpal-workflow-dataset-example-delete-options-workflow-id-exampleid)\n - [`eigenpal workflow dataset example get [options] <workflow-id> <exampleId>`](#eigenpal-workflow-dataset-example-get-options-workflow-id-exampleid)\n - [`eigenpal workflow dataset validate [options] [path]`](#eigenpal-workflow-dataset-validate-options-path)\n - [`eigenpal workflow dataset review-request list|ls [options] <automation-id>`](#eigenpal-workflow-dataset-review-request-listls-options-automation-id)\n - [`eigenpal workflow dataset review-request create [options] <automation-id>`](#eigenpal-workflow-dataset-review-request-create-options-automation-id)\n - [`eigenpal workflow dataset review-request get [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-get-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request update [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-update-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request items [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-items-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request events [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-events-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>`](#eigenpal-workflow-dataset-review-request-item-options-automation-id-review-id-item-id)\n - [`eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-pull-options-automation-id-review-id)\n - [`eigenpal workflow templates upload [options] <file>`](#eigenpal-workflow-templates-upload-options-file)\n - [`eigenpal workflow templates list|ls [options]`](#eigenpal-workflow-templates-listls-options)\n - [`eigenpal workflow templates get|inspect [options] <template-id>`](#eigenpal-workflow-templates-getinspect-options-template-id)\n - [`eigenpal workflow templates download [options] <template-id>`](#eigenpal-workflow-templates-download-options-template-id)\n - [`eigenpal workflow templates replace [options] <template-id> <file>`](#eigenpal-workflow-templates-replace-options-template-id-file)\n - [`eigenpal workflow templates delete [options] <template-id>`](#eigenpal-workflow-templates-delete-options-template-id)\n - [`eigenpal workflow templates smoke [options] <template>`](#eigenpal-workflow-templates-smoke-options-template)\n - [`eigenpal workflow experiment|exp list|ls [options] <workflow-id>`](#eigenpal-workflow-experimentexp-listls-options-workflow-id)\n - [`eigenpal workflow experiment|exp run [options] <workflow-id>`](#eigenpal-workflow-experimentexp-run-options-workflow-id)\n - [`eigenpal workflow experiment|exp status [options] <workflow-id> <batchId>`](#eigenpal-workflow-experimentexp-status-options-workflow-id-batchid)\n - [`eigenpal workflow experiment|exp cancel [options] <workflow-id> <batchId>`](#eigenpal-workflow-experimentexp-cancel-options-workflow-id-batchid)\n - [`eigenpal workflow experiment|exp results [options] <workflow-id> [batchId]`](#eigenpal-workflow-experimentexp-results-options-workflow-id-batchid)\n - [`eigenpal workflow experiment|exp compare|diff [options] <batchIdA> <batchIdB>`](#eigenpal-workflow-experimentexp-comparediff-options-batchida-batchidb)\n - [`eigenpal workflow experiment|exp watch [options] <workflow-id> <batchId>`](#eigenpal-workflow-experimentexp-watch-options-workflow-id-batchid)\n - [`eigenpal workflow versions list|ls [options] <workflow-id>`](#eigenpal-workflow-versions-listls-options-workflow-id)\n - [`eigenpal workflow versions create [options] <workflow-id>`](#eigenpal-workflow-versions-create-options-workflow-id)\n - [`eigenpal workflow versions promote [options] <workflow-id> <versionId>`](#eigenpal-workflow-versions-promote-options-workflow-id-versionid)\n - [`eigenpal workflow versions restore [options] <workflow-id> <versionId>`](#eigenpal-workflow-versions-restore-options-workflow-id-versionid)\n - [`eigenpal workflow step-type list|ls [options]`](#eigenpal-workflow-step-type-listls-options)\n - [`eigenpal workflow step-type get [options] <type>`](#eigenpal-workflow-step-type-get-options-type)\n - [`eigenpal workflow evaluator-type list|ls [options]`](#eigenpal-workflow-evaluator-type-listls-options)\n - [`eigenpal workflow evaluator-type get [options] <type>`](#eigenpal-workflow-evaluator-type-get-options-type)\n - [`eigenpal workflow step exec [options] <type>`](#eigenpal-workflow-step-exec-options-type)\n\n## Surface\n\n```\nworkflow\n├── list|ls\n├── pull <workflow-id>\n├── schema <workflow-id>\n├── push\n├── move <workflow-id>\n├── delete <workflow-id>\n├── migrate-parser <file>\n├── folders\n│ ├── list|ls\n│ ├── create <path>\n│ ├── rename <path-or-id>\n│ └── delete <path-or-id>\n├── evaluators\n│ ├── pull <workflow-id>\n│ ├── push <workflow-id>\n│ └── validate [path]\n├── dataset\n│ ├── list|ls <workflow-id>\n│ ├── pull <workflow-id>\n│ ├── push <workflow-id>\n│ ├── example\n│ │ ├── create <workflow-id>\n│ │ ├── update <workflow-id> <exampleId>\n│ │ ├── delete <workflow-id> <exampleId>\n│ │ └── get <workflow-id> <exampleId>\n│ ├── validate [path]\n│ └── review-request\n│ ├── list|ls <automation-id>\n│ ├── create <automation-id>\n│ ├── get <automation-id> <review-id>\n│ ├── update <automation-id> <review-id>\n│ ├── items <automation-id> <review-id>\n│ ├── events <automation-id> <review-id>\n│ ├── item <automation-id> <review-id> <item-id>\n│ └── pull <automation-id> <review-id>\n├── templates\n│ ├── upload <file>\n│ ├── list|ls\n│ ├── get|inspect <template-id>\n│ ├── download <template-id>\n│ ├── replace <template-id> <file>\n│ ├── delete <template-id>\n│ └── smoke <template>\n├── experiment|exp\n│ ├── list|ls <workflow-id>\n│ ├── run <workflow-id>\n│ ├── status <workflow-id> <batchId>\n│ ├── cancel <workflow-id> <batchId>\n│ ├── results <workflow-id> [batchId]\n│ ├── compare|diff <batchIdA> <batchIdB>\n│ └── watch <workflow-id> <batchId>\n├── versions\n│ ├── list|ls <workflow-id>\n│ ├── create <workflow-id>\n│ ├── promote <workflow-id> <versionId>\n│ └── restore <workflow-id> <versionId>\n├── step-type\n│ ├── list|ls\n│ └── get <type>\n├── evaluator-type\n│ ├── list|ls\n│ └── get <type>\n├── validate [path]\n├── clear-local [examples...]\n└── step\n └── exec <type>\n```\n\n## Commands\n\n### Core\n\n| Command | Description |\n| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow list\\|ls [options]` | List workflows the caller can read. |\n| `eigenpal workflow pull [options] <workflow-id>` | Download the YAML definition of the workflow at its current version. |\n| `eigenpal workflow schema [options] <workflow-id>` | Show the inferred output schema for a workflow (what it returns). |\n| `eigenpal workflow push [options]` | Create or update a workflow from a YAML file. |\n| `eigenpal workflow move [options] <workflow-id>` | Move a workflow to a folder path, creating folders as needed |\n| `eigenpal workflow delete [options] <workflow-id>` | Delete a workflow definition while preserving past runs. |\n| `eigenpal workflow migrate-parser [options] <file>` | Write a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source. |\n| `eigenpal workflow validate [options] [path]` | Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/<slug>/ or workflows/<slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`. |\n| `eigenpal workflow clear-local [options] [examples...]` | Delete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default. |\n\n### Folders\n\n| Command | Description |\n| --------------------------------------------------------- | ----------------------------------------------------------- |\n| `eigenpal workflow folders list\\|ls [options]` | List workflow folders. |\n| `eigenpal workflow folders create [options] <path>` | Create a folder path, creating any missing parent segments. |\n| `eigenpal workflow folders rename [options] <path-or-id>` | Rename a workflow folder. |\n| `eigenpal workflow folders delete [options] <path-or-id>` | Delete a workflow folder. |\n\n### Evaluators\n\n| Command | Description |\n| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluators pull [options] <workflow-id>` | Download the workflow's evaluators YAML. |\n| `eigenpal workflow evaluators push [options] <workflow-id>` | Overwrite the workflow's evaluator config from a YAML file. |\n| `eigenpal workflow evaluators validate [options] [path]` | Validate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml. |\n\n### Dataset\n\n| Command | Description |\n| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow dataset list\\|ls [options] <workflow-id>` | List eval examples for the workflow. |\n| `eigenpal workflow dataset pull [options] <workflow-id>` | Download the workflow's dataset as a ZIP archive. |\n| `eigenpal workflow dataset push [options] <workflow-id>` | Replace or extend the workflow's dataset from a ZIP or folder. |\n| `eigenpal workflow dataset example create [options] <workflow-id>` | Create one eval example without re-uploading the dataset. |\n| `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>` | Patch one eval example. Omitted flags are left alone. |\n| `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>` | Delete one eval example by id. Non-TTY shells require --yes. |\n| `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>` | Fetch one eval example with full triggerInput, expectedOutput, and metadata. |\n| `eigenpal workflow dataset validate [options] [path]` | Validate a dataset folder against the examples/<name>/{input,expected,meta} convention. Defaults to ./dataset/. |\n| `eigenpal workflow dataset review-request list\\|ls [options] <automation-id>` | |\n| `eigenpal workflow dataset review-request create [options] <automation-id>` | Request human review of dataset ground truth. Snapshot examples and poll progress until review is complete. |\n| `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>` | Fetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events. |\n| `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>` | Update review metadata or lifecycle status. Set --status closed when review is finished. |\n| `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>` | List snapshotted review items and their statuses. |\n| `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>` | List review activity, including example and field notes. |\n| `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>` | Approve, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file. |\n| `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>` | Download review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON. |\n\n### Templates\n\n| Command | Description |\n| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow templates upload [options] <file>` | Upload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision. |\n| `eigenpal workflow templates list\\|ls [options]` | List workspace templates. |\n| `eigenpal workflow templates get\\|inspect [options] <template-id>` | Inspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar. |\n| `eigenpal workflow templates download [options] <template-id>` | Download current (or pinned) template bytes. |\n| `eigenpal workflow templates replace [options] <template-id> <file>` | Append an immutable revision and advance the tmpl\\_… pointer. |\n| `eigenpal workflow templates delete [options] <template-id>` | Delete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run. |\n| `eigenpal workflow templates smoke [options] <template>` | Fill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server. |\n\n### Experiment\n\n| Command | Description |\n| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| `eigenpal workflow experiment\\|exp list\\|ls [options] <workflow-id>` | List executions for the workflow, newest first. |\n| `eigenpal workflow experiment\\|exp run [options] <workflow-id>` | Start a batch eval against the workflow's dataset. |\n| `eigenpal workflow experiment\\|exp status [options] <workflow-id> <batchId>` | Aggregate progress for a batch by `batchId`. |\n| `eigenpal workflow experiment\\|exp cancel [options] <workflow-id> <batchId>` | Cancel every execution in a batch. Idempotent. |\n| `eigenpal workflow experiment\\|exp results [options] <workflow-id> [batchId]` | Download eval results in CSV or JSON. |\n| `eigenpal workflow experiment\\|exp compare\\|diff [options] <batchIdA> <batchIdB>` | Compare evaluator scores or actual outputs between two experiment batches. |\n| `eigenpal workflow experiment\\|exp watch [options] <workflow-id> <batchId>` | Poll until terminal, then auto-pull results — replaces `status --watch` + `results --out`. |\n\n### Versions\n\n| Command | Description |\n| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow versions list\\|ls [options] <workflow-id>` | List tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first. |\n| `eigenpal workflow versions create [options] <workflow-id>` | Create a tagged workflow version from YAML or by copying an existing snapshot. |\n| `eigenpal workflow versions promote [options] <workflow-id> <versionId>` | Make an existing tagged workflow version current without creating another snapshot. |\n| `eigenpal workflow versions restore [options] <workflow-id> <versionId>` | Restore a previous snapshot as a new untagged current version. Does not retag the source. |\n\n### Step-type\n\n| Command | Description |\n| -------------------------------------------------- | ------------------------------------------------------------- |\n| `eigenpal workflow step-type list\\|ls [options]` | List every step type the deployment supports. |\n| `eigenpal workflow step-type get [options] <type>` | Return the full schema and behavioral docs for one step type. |\n\n### Evaluator-type\n\n| Command | Description |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluator-type list\\|ls [options]` | List every evaluator type with a one-line description. |\n| `eigenpal workflow evaluator-type get [options] <type>` | Fetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields. |\n\n### Step\n\n| Command | Description |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow step exec [options] <type>` | DISABLED — local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead. |\n\n## Details\n\n### `eigenpal workflow list|ls [options]`\n\nList workflows the caller can read.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by name |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow pull [options] <workflow-id>`\n\nDownload the YAML definition of the workflow at its current version.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow schema [options] <workflow-id>`\n\nShow the inferred output schema for a workflow (what it returns).\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | -------- | ------------------------------- |\n| `--format <format>` | no | `\"json\"` | json \\| typescript \\| python |\n| `--out <path>` | no | | Write to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow push [options]`\n\nCreate or update a workflow from a YAML file.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to YAML file |\n| `--workflow-id <id>` | no | | Update existing workflow (default: create new) |\n| `--bump <level>` | no | | Auto-bump from the server's current version: patch \\| minor \\| major. Mutually exclusive with `--version` and with a top-level `version:` in the YAML. |\n| `--set-version <semver>` | no | | Push at this exact semver (e.g. 1.4.0). Mutually exclusive with `--bump` and with a top-level `version:` in the YAML. (Named `--set-version` to avoid the global `-v, --version` flag.) |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow move [options] <workflow-id>`\n\nMove a workflow to a folder path, creating folders as needed\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--folder <path>` | yes | | Target folder path (`/` for root) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow delete [options] <workflow-id>`\n\nDelete a workflow definition while preserving past runs.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow migrate-parser [options] <file>`\n\nWrite a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--policy <policy>` | yes | | preserve backend restrictions, or auto to adopt automatic native/OCR/vision parsing |\n| `--out <file>` | yes | | New YAML output file (must not already exist) |\n| `--json` | no | | Emit migration summary as JSON |\n\n### `eigenpal workflow validate [options] [path]`\n\nLocal-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/<slug>/ or workflows/<slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--dir <path>` | no | | Project root (defaults to cwd; resolves the three default paths from here) |\n| `--online` | no | | Authenticate and also validate action.invoke-workflow targets, transform.template tmpl\\_… references, and explicitly selected OCR/vision/text models against this tenant environment (existence, format, revision pairing, tokens vs data, XLSX {{ }} mistakes, configured catalog). Local template: paths are inspected on disk with or without this flag. Model checks use the configured catalog only — they do not probe live provider health. |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow clear-local [options] [examples...]`\n\nDelete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `examples` | no | yes | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------- | -------- | ------- | ---------------------------------------------------------- |\n| `--dir <dir>` | no | | Local eigenpal directory |\n| `--all` | no | `false` | Remove all artifacts, including the latest kept by default |\n\n### `eigenpal workflow folders list|ls [options]`\n\nList workflow folders.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--tree` | no | | Render folders as an indented tree |\n\n### `eigenpal workflow folders create [options] <path>`\n\nCreate a folder path, creating any missing parent segments.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow folders rename [options] <path-or-id>`\n\nRename a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--name <name>` | yes | | New folder name |\n\n### `eigenpal workflow folders delete [options] <path-or-id>`\n\nDelete a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n\n### `eigenpal workflow evaluators pull [options] <workflow-id>`\n\nDownload the workflow's evaluators YAML.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow evaluators push [options] <workflow-id>`\n\nOverwrite the workflow's evaluator config from a YAML file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--file <yaml>` | yes | | Path to evaluators YAML file |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluators validate [options] [path]`\n\nValidate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset list|ls [options] <workflow-id>`\n\nList eval examples for the workflow.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `100` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset pull [options] <workflow-id>`\n\nDownload the workflow's dataset as a ZIP archive.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--out <zip>` | no | | Write the dataset ZIP to this path. When omitted, the binary streams to stdout. |\n| `--example-id <id>` | no | `[]` | Export only this example (repeatable). When omitted, the whole dataset is exported. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow dataset push [options] <workflow-id>`\n\nReplace or extend the workflow's dataset from a ZIP or folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------ |\n| `--file <path>` | yes | | Path to a dataset ZIP file or a dataset/ folder (folder is zipped in memory before upload) |\n| `--mode <append\\|replace>` | no | `\"append\"` | Import mode (default: append) |\n| `--yes` | no | `false` | Skip the destructive confirmation prompt for --mode replace (use in CI) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example create [options] <workflow-id>`\n\nCreate one eval example without re-uploading the dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | --------------------------------------------------- |\n| `--name <name>` | yes | | Example name (1–64 chars) |\n| `--input-json <json>` | no | | Trigger input as a JSON literal |\n| `--input-file <path>` | no | | Trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Expected output as a JSON literal |\n| `--expected-file <path>` | no | | Expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Free-form annotation |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>`\n\nPatch one eval example. Omitted flags are left alone.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | ----------------------------------------------------------- |\n| `--name <name>` | no | | Rename the example (1–64 chars) |\n| `--input-json <json>` | no | | Replace trigger input with this JSON literal |\n| `--input-file <path>` | no | | Replace trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Replace expected output with this JSON literal |\n| `--expected-file <path>` | no | | Replace expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Replace annotation; pass empty string to clear |\n| `--row-order <n>` | no | | Reorder the row (0-based) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>`\n\nDelete one eval example by id. Non-TTY shells require --yes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--yes` | no | `false` | Required for non-TTY shells; explicit acknowledgment that this is destructive |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>`\n\nFetch one eval example with full triggerInput, expectedOutput, and metadata.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset validate [options] [path]`\n\nValidate a dataset folder against the examples/<name>/{input,expected,meta} convention. Defaults to ./dataset/.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset review-request list|ls [options] <automation-id>`\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--status <csv>` | no | | Filter by review status (comma-separated: draft,open,paused,closed,cancelled) |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request create [options] <automation-id>`\n\nRequest human review of dataset ground truth. Snapshot examples and poll progress until review is complete.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | yes | | Review request title |\n| `--example-name <name>` | yes | `[]` | Example folder name to include (repeatable) |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Expected-output leaf path to flag across selected examples; parent paths flag every descendant (repeatable) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--ignore <path>` | no | `[]` | Expected-output path reviewers can skip (repeatable) |\n| `--item-note <spec>` | no | `[]` | Example-level note seeded at create time, as exampleName=comment (repeatable) |\n| `--field-note <spec>` | no | `[]` | Field comment only, as exampleName.path=comment; does not flag the field (repeatable) |\n| `--focus-json <json>` | no | | JSON array of { path, reason? } focus fields |\n| `--notes-json <json>` | no | | JSON array of { exampleName, comment?, fields?: [{ path, comment }] } |\n| `--status <draft\\|open\\|paused>` | no | | Initial lifecycle status (default: draft) |\n\n### `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>`\n\nFetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>`\n\nUpdate review metadata or lifecycle status. Set --status closed when review is finished.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | no | | New review request title |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Replace focus paths (repeatable; use with --focus-reason / --focus-json) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--focus-json <json>` | no | | JSON array of { path, reason? } focus fields (replaces focus) |\n| `--ignore <path>` | no | | Replace ignored paths (repeatable) |\n| `--status <draft\\|open\\|paused\\|closed\\|cancelled>` | no | | Lifecycle status |\n\n### `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>`\n\nList snapshotted review items and their statuses.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--status <csv>` | no | | Filter by item status (pending,approved,edited,removed) |\n\n### `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>`\n\nList review activity, including example and field notes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>`\n\nApprove, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n| `item-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--action <approve\\|remove\\|reopen\\|comment\\|edit\\|field-decision\\|file-decision\\|edit-file>` | yes | | Item action |\n| `--expected-updated-at <iso>` | yes | | Item updatedAt the client last observed (optimistic concurrency) |\n| `--comment <text>` | no | | Note stored on the item, field, or file |\n| `--field-path <path>` | no | | Dotted expected-output path for comment or field-decision |\n| `--file-path <path>` | no | | Expected-file path for file-decision or edit-file (correct) |\n| `--new-path <path>` | no | | Expected-file path for edit-file uploads of brand-new reviewer files |\n| `--file <local path>` | no | | Local file bytes to upload when --action edit-file |\n| `--decision <approved\\|removed\\|null>` | no | | Field or file decision for --action field-decision or file-decision (null/clear removes it) |\n| `--clear` | no | `false` | Clear a field or file decision (sends decision: null) |\n| `--expected-json <json>` | no | | Replacement expected JSON when --action edit |\n\n### `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>`\n\nDownload review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ---------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--out <dir>` | yes | | Local directory to materialize the review into |\n\n### `eigenpal workflow templates upload [options] <file>`\n\nUpload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------------------------------- |\n| `--name <name>` | no | | Display name (defaults to the filename without extension) |\n| `--description <text>` | no | | Optional description |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates list|ls [options]`\n\nList workspace templates.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates get|inspect [options] <template-id>`\n\nInspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates download [options] <template-id>`\n\nDownload current (or pinned) template bytes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------- |\n| `--out <path>` | no | | Write to this file (required) |\n| `--revision-id <tmpr>` | no | | Pin an immutable tmpr\\_… revision |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow templates replace [options] <template-id> <file>`\n\nAppend an immutable revision and advance the tmpl\\_… pointer.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates delete [options] <template-id>`\n\nDelete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--yes` | no | `false` | Required for non-TTY shells |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates smoke [options] <template>`\n\nFill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `template` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ------------------------------------------------------------ |\n| `--data <file>` | yes | | Path to a JSON fixture file (object with template data keys) |\n| `--out <path>` | yes | | Filled DOCX/XLSX output path |\n| `--revision-id <tmpr>` | no | | When <template> is a tmpl\\_… id, pin this revision |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp list|ls [options] <workflow-id>`\n\nList executions for the workflow, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--batch-id <id>` | no | | Filter by batch |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp run [options] <workflow-id>`\n\nStart a batch eval against the workflow's dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------- |\n| `--example-id <id>` | no | `[]` | Run only this example (repeatable) |\n| `--wait` | no | `false` | Poll until terminal; non-zero exit on passRate < 1.0 |\n| `--interval <n>` | no | `10` | Polling interval in seconds (default 10) |\n| `--max-wait <seconds>` | no | `1800` | Maximum wait before exit code 2 (default 1800) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp status [options] <workflow-id> <batchId>`\n\nAggregate progress for a batch by `batchId`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--watch` | no | `false` | Poll until every execution reaches a terminal state (completed/failed/cancelled/rejected), then exit |\n| `--short` | no | `false` | Single-line plain-text summary on stdout (e.g. `6/6 done failed=0 cancelled=0 rejected=0`). Pipe-friendly for monitoring loops; mutually exclusive with --watch. |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds when --watch is set (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling for --watch in seconds (default 1800 = 30 min) |\n| `--include <kinds>` | no | `\"\"` | Comma-separated extras to attach when --watch terminates: payload (full per-execution snapshot, can be hundreds of KB) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp cancel [options] <workflow-id> <batchId>`\n\nCancel every execution in a batch. Idempotent.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------- |\n| `--yes` | no | | Required for non-TTY shells (CI, pipes). Acts immediately, no prompt. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp results [options] <workflow-id> [batchId]`\n\nDownload eval results in CSV or JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | -------- | ---------------------------------------------------------------------------------------- |\n| `--format <csv\\|json>` | no | `\"json\"` | Output format (default json) |\n| `--out <path>` | no | | Output file. When omitted, the binary streams to stdout. |\n| `--summary` | no | | Show total/pass/fail/error counts, average score, and evaluator rollups |\n| `--failed-only` | no | | Keep only failed or errored evaluator results |\n| `--evaluator <name>` | no | | Keep only results from this evaluator |\n| `--select <path>` | no | | Print only a nested JSON value (for example summary.byEvaluator or discrepancies[].path) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp compare|diff [options] <batchIdA> <batchIdB>`\n\nCompare evaluator scores or actual outputs between two experiment batches.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `batchIdA` | yes | no | |\n| `batchIdB` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------------------------------------ | -------- | ------------------ | ------------------------------------------------------ |\n| `--outputs` | no | | Compare actual run outputs instead of evaluator scores |\n| `--sort <abs-delta-desc\\|delta-asc\\|delta-desc\\|name>` | no | `\"abs-delta-desc\"` | Row sort order (default: biggest movers first) |\n| `--regression-threshold <n>` | no | `0.05` | Δ below this is flagged as a regression (default 0.05) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp watch [options] <workflow-id> <batchId>`\n\nPoll until terminal, then auto-pull results — replaces `status --watch` + `results --out`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------- | -------- | -------- | ----------------------------------------------------------------------- |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling in seconds (default 1800 = 30 min) |\n| `--pull-on-complete <path>` | no | | Destination for the results file. Default: ./results-<batchId>.<format> |\n| `--format <csv\\|json>` | no | `\"json\"` | Results export format (default json) |\n| `--no-pull` | no | | Skip auto-pulling results on terminal (watch only) |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow versions list|ls [options] <workflow-id>`\n\nList tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------- |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Print the sliced { data, total, limit, offset } envelope as JSON (not the raw server payload) |\n\n### `eigenpal workflow versions create [options] <workflow-id>`\n\nCreate a tagged workflow version from YAML or by copying an existing snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to workflow YAML. Mutually exclusive with --from. |\n| `--allow-external-templates` | no | | Allow local template paths outside the workflow project. Use only for trusted YAML. |\n| `--from <version-id>` | no | | Existing version id to copy into a new tagged snapshot. Leaves the source tag unchanged. Mutually exclusive with --file. |\n| `--set-version <semver>` | no | | Bare semver tag such as 1.4.0. Required when copying with --from. For --file, omit this flag if the YAML already has a top-level version: field. (Named --set-version to avoid the global -v, --version flag.) |\n| `--no-activate` | no | | Keep the tagged version off live traffic until you promote it. Default is to make it current. Requires an existing current version. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions promote [options] <workflow-id> <versionId>`\n\nMake an existing tagged workflow version current without creating another snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions restore [options] <workflow-id> <versionId>`\n\nRestore a previous snapshot as a new untagged current version. Does not retag the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------ |\n| `--message <text>` | no | | Optional restore note stored on the new snapshot |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type list|ls [options]`\n\nList every step type the deployment supports.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type get [options] <type>`\n\nReturn the full schema and behavioral docs for one step type.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------- |\n| `--out <path>` | no | | Write to file |\n\n### `eigenpal workflow evaluator-type list|ls [options]`\n\nList every evaluator type with a one-line description.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by type, name, or description |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluator-type get [options] <type>`\n\nFetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------- |\n| `--out <path>` | no | | Write to file |\n\n### `eigenpal workflow step exec [options] <type>`\n\nDISABLED — local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | -------------------------------------- |\n| `--config-json <json>` | no | | (unused; kept for back-compat parsing) |\n| `--config-file <path>` | no | | (unused) |\n| `--inputs <pairs...>` | no | | (unused) |\n| `--output-schema <path>` | no | | (unused) |\n"
422
+ "content": "# eigenpal workflow\n\nManage workflows: push, pull, and evaluate.\n\n## Contents\n\n- [Surface](#surface)\n- [Commands](#commands)\n - [Core](#core)\n - [Folders](#folders)\n - [Evaluators](#evaluators)\n - [Dataset](#dataset)\n - [Templates](#templates)\n - [Experiment](#experiment)\n - [Versions](#versions)\n - [Step-type](#step-type)\n - [Evaluator-type](#evaluator-type)\n - [Step](#step)\n- [Details](#details)\n - [`eigenpal workflow list|ls [options]`](#eigenpal-workflow-listls-options)\n - [`eigenpal workflow get [options] <workflow-id>`](#eigenpal-workflow-get-options-workflow-id)\n - [`eigenpal workflow pull [options] <workflow-id>`](#eigenpal-workflow-pull-options-workflow-id)\n - [`eigenpal workflow schema [options] <workflow-id>`](#eigenpal-workflow-schema-options-workflow-id)\n - [`eigenpal workflow push [options]`](#eigenpal-workflow-push-options)\n - [`eigenpal workflow move [options] <workflow-id>`](#eigenpal-workflow-move-options-workflow-id)\n - [`eigenpal workflow delete [options] <workflow-id>`](#eigenpal-workflow-delete-options-workflow-id)\n - [`eigenpal workflow migrate-parser [options] <file>`](#eigenpal-workflow-migrate-parser-options-file)\n - [`eigenpal workflow validate [options] [path]`](#eigenpal-workflow-validate-options-path)\n - [`eigenpal workflow clear-local [options] [examples...]`](#eigenpal-workflow-clear-local-options-examples)\n - [`eigenpal workflow folders list|ls [options]`](#eigenpal-workflow-folders-listls-options)\n - [`eigenpal workflow folders create [options] <path>`](#eigenpal-workflow-folders-create-options-path)\n - [`eigenpal workflow folders rename [options] <path-or-id>`](#eigenpal-workflow-folders-rename-options-path-or-id)\n - [`eigenpal workflow folders delete [options] <path-or-id>`](#eigenpal-workflow-folders-delete-options-path-or-id)\n - [`eigenpal workflow evaluators pull [options] <workflow-id>`](#eigenpal-workflow-evaluators-pull-options-workflow-id)\n - [`eigenpal workflow evaluators push [options] <workflow-id>`](#eigenpal-workflow-evaluators-push-options-workflow-id)\n - [`eigenpal workflow evaluators validate [options] [path]`](#eigenpal-workflow-evaluators-validate-options-path)\n - [`eigenpal workflow dataset list|ls [options] <workflow-id>`](#eigenpal-workflow-dataset-listls-options-workflow-id)\n - [`eigenpal workflow dataset pull [options] <workflow-id>`](#eigenpal-workflow-dataset-pull-options-workflow-id)\n - [`eigenpal workflow dataset push [options] <workflow-id>`](#eigenpal-workflow-dataset-push-options-workflow-id)\n - [`eigenpal workflow dataset example create [options] <workflow-id>`](#eigenpal-workflow-dataset-example-create-options-workflow-id)\n - [`eigenpal workflow dataset example update [options] <workflow-id> <exampleId>`](#eigenpal-workflow-dataset-example-update-options-workflow-id-exampleid)\n - [`eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>`](#eigenpal-workflow-dataset-example-delete-options-workflow-id-exampleid)\n - [`eigenpal workflow dataset example get [options] <workflow-id> <exampleId>`](#eigenpal-workflow-dataset-example-get-options-workflow-id-exampleid)\n - [`eigenpal workflow dataset validate [options] [path]`](#eigenpal-workflow-dataset-validate-options-path)\n - [`eigenpal workflow dataset review-request list|ls [options] <automation-id>`](#eigenpal-workflow-dataset-review-request-listls-options-automation-id)\n - [`eigenpal workflow dataset review-request create [options] <automation-id>`](#eigenpal-workflow-dataset-review-request-create-options-automation-id)\n - [`eigenpal workflow dataset review-request get [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-get-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request update [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-update-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request items [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-items-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request events [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-events-options-automation-id-review-id)\n - [`eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>`](#eigenpal-workflow-dataset-review-request-item-options-automation-id-review-id-item-id)\n - [`eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>`](#eigenpal-workflow-dataset-review-request-pull-options-automation-id-review-id)\n - [`eigenpal workflow templates upload [options] <file>`](#eigenpal-workflow-templates-upload-options-file)\n - [`eigenpal workflow templates list|ls [options]`](#eigenpal-workflow-templates-listls-options)\n - [`eigenpal workflow templates get|inspect [options] <template-id>`](#eigenpal-workflow-templates-getinspect-options-template-id)\n - [`eigenpal workflow templates download [options] <template-id>`](#eigenpal-workflow-templates-download-options-template-id)\n - [`eigenpal workflow templates replace [options] <template-id> <file>`](#eigenpal-workflow-templates-replace-options-template-id-file)\n - [`eigenpal workflow templates delete [options] <template-id>`](#eigenpal-workflow-templates-delete-options-template-id)\n - [`eigenpal workflow templates smoke [options] <template>`](#eigenpal-workflow-templates-smoke-options-template)\n - [`eigenpal workflow experiment|exp list|ls [options] <workflow-id>`](#eigenpal-workflow-experimentexp-listls-options-workflow-id)\n - [`eigenpal workflow experiment|exp run [options] <workflow-id>`](#eigenpal-workflow-experimentexp-run-options-workflow-id)\n - [`eigenpal workflow experiment|exp status [options] <workflow-id> <batchId>`](#eigenpal-workflow-experimentexp-status-options-workflow-id-batchid)\n - [`eigenpal workflow experiment|exp cancel [options] <workflow-id> <batchId>`](#eigenpal-workflow-experimentexp-cancel-options-workflow-id-batchid)\n - [`eigenpal workflow experiment|exp results [options] <workflow-id> [batchId]`](#eigenpal-workflow-experimentexp-results-options-workflow-id-batchid)\n - [`eigenpal workflow experiment|exp compare|diff [options] <batchIdA> <batchIdB>`](#eigenpal-workflow-experimentexp-comparediff-options-batchida-batchidb)\n - [`eigenpal workflow experiment|exp watch [options] <workflow-id> <batchId>`](#eigenpal-workflow-experimentexp-watch-options-workflow-id-batchid)\n - [`eigenpal workflow versions list|ls [options] <workflow-id>`](#eigenpal-workflow-versions-listls-options-workflow-id)\n - [`eigenpal workflow versions create [options] <workflow-id>`](#eigenpal-workflow-versions-create-options-workflow-id)\n - [`eigenpal workflow versions promote [options] <workflow-id> <versionId>`](#eigenpal-workflow-versions-promote-options-workflow-id-versionid)\n - [`eigenpal workflow versions restore [options] <workflow-id> <versionId>`](#eigenpal-workflow-versions-restore-options-workflow-id-versionid)\n - [`eigenpal workflow step-type list|ls [options]`](#eigenpal-workflow-step-type-listls-options)\n - [`eigenpal workflow step-type get [options] <type>`](#eigenpal-workflow-step-type-get-options-type)\n - [`eigenpal workflow evaluator-type list|ls [options]`](#eigenpal-workflow-evaluator-type-listls-options)\n - [`eigenpal workflow evaluator-type get [options] <type>`](#eigenpal-workflow-evaluator-type-get-options-type)\n - [`eigenpal workflow step exec [options] <type>`](#eigenpal-workflow-step-exec-options-type)\n\n## Surface\n\n```\nworkflow\n├── list|ls\n├── get <workflow-id>\n├── pull <workflow-id>\n├── schema <workflow-id>\n├── push\n├── move <workflow-id>\n├── delete <workflow-id>\n├── migrate-parser <file>\n├── folders\n│ ├── list|ls\n│ ├── create <path>\n│ ├── rename <path-or-id>\n│ └── delete <path-or-id>\n├── evaluators\n│ ├── pull <workflow-id>\n│ ├── push <workflow-id>\n│ └── validate [path]\n├── dataset\n│ ├── list|ls <workflow-id>\n│ ├── pull <workflow-id>\n│ ├── push <workflow-id>\n│ ├── example\n│ │ ├── create <workflow-id>\n│ │ ├── update <workflow-id> <exampleId>\n│ │ ├── delete <workflow-id> <exampleId>\n│ │ └── get <workflow-id> <exampleId>\n│ ├── validate [path]\n│ └── review-request\n│ ├── list|ls <automation-id>\n│ ├── create <automation-id>\n│ ├── get <automation-id> <review-id>\n│ ├── update <automation-id> <review-id>\n│ ├── items <automation-id> <review-id>\n│ ├── events <automation-id> <review-id>\n│ ├── item <automation-id> <review-id> <item-id>\n│ └── pull <automation-id> <review-id>\n├── templates\n│ ├── upload <file>\n│ ├── list|ls\n│ ├── get|inspect <template-id>\n│ ├── download <template-id>\n│ ├── replace <template-id> <file>\n│ ├── delete <template-id>\n│ └── smoke <template>\n├── experiment|exp\n│ ├── list|ls <workflow-id>\n│ ├── run <workflow-id>\n│ ├── status <workflow-id> <batchId>\n│ ├── cancel <workflow-id> <batchId>\n│ ├── results <workflow-id> [batchId]\n│ ├── compare|diff <batchIdA> <batchIdB>\n│ └── watch <workflow-id> <batchId>\n├── versions\n│ ├── list|ls <workflow-id>\n│ ├── create <workflow-id>\n│ ├── promote <workflow-id> <versionId>\n│ └── restore <workflow-id> <versionId>\n├── step-type\n│ ├── list|ls\n│ └── get <type>\n├── evaluator-type\n│ ├── list|ls\n│ └── get <type>\n├── validate [path]\n├── clear-local [examples...]\n└── step\n └── exec <type>\n```\n\n## Commands\n\n### Core\n\n| Command | Description |\n| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow list\\|ls [options]` | List workflows the caller can read. |\n| `eigenpal workflow get [options] <workflow-id>` | Show one workflow: name, current version, folder and your access level. |\n| `eigenpal workflow pull [options] <workflow-id>` | Download the YAML definition of the workflow at its current version. |\n| `eigenpal workflow schema [options] <workflow-id>` | Show the inferred output schema for a workflow (what it returns). |\n| `eigenpal workflow push [options]` | Create or update a workflow from a YAML file. |\n| `eigenpal workflow move [options] <workflow-id>` | Move a workflow to a folder path, creating folders as needed |\n| `eigenpal workflow delete [options] <workflow-id>` | Delete a workflow definition while preserving past runs. |\n| `eigenpal workflow migrate-parser [options] <file>` | Write a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source. |\n| `eigenpal workflow validate [options] [path]` | Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/<slug>/ or workflows/<slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`. |\n| `eigenpal workflow clear-local [options] [examples...]` | Delete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default. |\n\n### Folders\n\n| Command | Description |\n| --------------------------------------------------------- | ----------------------------------------------------------- |\n| `eigenpal workflow folders list\\|ls [options]` | List workflow folders. |\n| `eigenpal workflow folders create [options] <path>` | Create a folder path, creating any missing parent segments. |\n| `eigenpal workflow folders rename [options] <path-or-id>` | Rename a workflow folder. |\n| `eigenpal workflow folders delete [options] <path-or-id>` | Delete a workflow folder. |\n\n### Evaluators\n\n| Command | Description |\n| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluators pull [options] <workflow-id>` | Download the workflow's evaluators YAML. |\n| `eigenpal workflow evaluators push [options] <workflow-id>` | Overwrite the workflow's evaluator config from a YAML file. |\n| `eigenpal workflow evaluators validate [options] [path]` | Validate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml. |\n\n### Dataset\n\n| Command | Description |\n| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow dataset list\\|ls [options] <workflow-id>` | List eval examples for the workflow. |\n| `eigenpal workflow dataset pull [options] <workflow-id>` | Download the workflow's dataset as a ZIP archive. |\n| `eigenpal workflow dataset push [options] <workflow-id>` | Replace or extend the workflow's dataset from a ZIP or folder. |\n| `eigenpal workflow dataset example create [options] <workflow-id>` | Create one eval example without re-uploading the dataset. |\n| `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>` | Patch one eval example. Omitted flags are left alone. |\n| `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>` | Delete one eval example by id. Non-TTY shells require --yes. |\n| `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>` | Fetch one eval example with full triggerInput, expectedOutput, and metadata. |\n| `eigenpal workflow dataset validate [options] [path]` | Validate a dataset folder against the examples/<name>/{input,expected,meta} convention. Defaults to ./dataset/. |\n| `eigenpal workflow dataset review-request list\\|ls [options] <automation-id>` | |\n| `eigenpal workflow dataset review-request create [options] <automation-id>` | Request human review of dataset ground truth. Snapshot examples and poll progress until review is complete. |\n| `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>` | Fetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events. |\n| `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>` | Update review metadata or lifecycle status. Set --status closed when review is finished. |\n| `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>` | List snapshotted review items and their statuses. |\n| `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>` | List review activity, including example and field notes. |\n| `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>` | Approve, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file. |\n| `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>` | Download review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON. |\n\n### Templates\n\n| Command | Description |\n| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow templates upload [options] <file>` | Upload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision. |\n| `eigenpal workflow templates list\\|ls [options]` | List workspace templates. |\n| `eigenpal workflow templates get\\|inspect [options] <template-id>` | Inspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar. |\n| `eigenpal workflow templates download [options] <template-id>` | Download current (or pinned) template bytes. |\n| `eigenpal workflow templates replace [options] <template-id> <file>` | Append an immutable revision and advance the tmpl\\_… pointer. |\n| `eigenpal workflow templates delete [options] <template-id>` | Delete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run. |\n| `eigenpal workflow templates smoke [options] <template>` | Fill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server. |\n\n### Experiment\n\n| Command | Description |\n| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |\n| `eigenpal workflow experiment\\|exp list\\|ls [options] <workflow-id>` | List executions for the workflow, newest first. |\n| `eigenpal workflow experiment\\|exp run [options] <workflow-id>` | Start a batch eval against the workflow's dataset. |\n| `eigenpal workflow experiment\\|exp status [options] <workflow-id> <batchId>` | Aggregate progress for a batch by `batchId`. |\n| `eigenpal workflow experiment\\|exp cancel [options] <workflow-id> <batchId>` | Cancel every execution in a batch. Idempotent. |\n| `eigenpal workflow experiment\\|exp results [options] <workflow-id> [batchId]` | Download eval results in CSV or JSON. |\n| `eigenpal workflow experiment\\|exp compare\\|diff [options] <batchIdA> <batchIdB>` | Compare evaluator scores or actual outputs between two experiment batches. |\n| `eigenpal workflow experiment\\|exp watch [options] <workflow-id> <batchId>` | Poll until terminal, then auto-pull results — replaces `status --watch` + `results --out`. |\n\n### Versions\n\n| Command | Description |\n| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |\n| `eigenpal workflow versions list\\|ls [options] <workflow-id>` | List tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first. |\n| `eigenpal workflow versions create [options] <workflow-id>` | Create a tagged workflow version from YAML or by copying an existing snapshot. |\n| `eigenpal workflow versions promote [options] <workflow-id> <versionId>` | Make an existing tagged workflow version current without creating another snapshot. |\n| `eigenpal workflow versions restore [options] <workflow-id> <versionId>` | Restore a previous snapshot as a new untagged current version. Does not retag the source. |\n\n### Step-type\n\n| Command | Description |\n| -------------------------------------------------- | ------------------------------------------------------------- |\n| `eigenpal workflow step-type list\\|ls [options]` | List every step type the deployment supports. |\n| `eigenpal workflow step-type get [options] <type>` | Return the full schema and behavioral docs for one step type. |\n\n### Evaluator-type\n\n| Command | Description |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `eigenpal workflow evaluator-type list\\|ls [options]` | List every evaluator type with a one-line description. |\n| `eigenpal workflow evaluator-type get [options] <type>` | Fetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields. |\n\n### Step\n\n| Command | Description |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `eigenpal workflow step exec [options] <type>` | DISABLED — local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead. |\n\n## Details\n\n### `eigenpal workflow list|ls [options]`\n\nList workflows the caller can read.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by name |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow get [options] <workflow-id>`\n\nShow one workflow: name, current version, folder and your access level.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow pull [options] <workflow-id>`\n\nDownload the YAML definition of the workflow at its current version.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow schema [options] <workflow-id>`\n\nShow the inferred output schema for a workflow (what it returns).\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | -------- | ------------------------------- |\n| `--format <format>` | no | `\"json\"` | json \\| typescript \\| python |\n| `--out <path>` | no | | Write to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow push [options]`\n\nCreate or update a workflow from a YAML file.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to YAML file |\n| `--workflow-id <id>` | no | | Update existing workflow (default: create new) |\n| `--bump <level>` | no | | Auto-bump from the server's current version: patch \\| minor \\| major. Mutually exclusive with `--version` and with a top-level `version:` in the YAML. |\n| `--set-version <semver>` | no | | Push at this exact semver (e.g. 1.4.0). Mutually exclusive with `--bump` and with a top-level `version:` in the YAML. (Named `--set-version` to avoid the global `-v, --version` flag.) |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow move [options] <workflow-id>`\n\nMove a workflow to a folder path, creating folders as needed\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--folder <path>` | yes | | Target folder path (`/` for root) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow delete [options] <workflow-id>`\n\nDelete a workflow definition while preserving past runs.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow migrate-parser [options] <file>`\n\nWrite a reviewable ai.parse-v2 workflow migration to a new file. Never pushes or changes the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--policy <policy>` | yes | | preserve backend restrictions, or auto to adopt automatic native/OCR/vision parsing |\n| `--out <file>` | yes | | New YAML output file (must not already exist) |\n| `--json` | no | | Emit migration summary as JSON |\n\n### `eigenpal workflow validate [options] [path]`\n\nLocal-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/<slug>/ or workflows/<slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--dir <path>` | no | | Project root (defaults to cwd; resolves the three default paths from here) |\n| `--online` | no | | Authenticate and also validate action.invoke-workflow targets, transform.template tmpl\\_… references, and explicitly selected OCR/vision/text models against this tenant environment (existence, format, revision pairing, tokens vs data, XLSX {{ }} mistakes, configured catalog). Local template: paths are inspected on disk with or without this flag. Model checks use the configured catalog only — they do not probe live provider health. |\n| `--allow-external-templates` | no | | Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow clear-local [options] [examples...]`\n\nDelete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `examples` | no | yes | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------- | -------- | ------- | ---------------------------------------------------------- |\n| `--dir <dir>` | no | | Local eigenpal directory |\n| `--all` | no | `false` | Remove all artifacts, including the latest kept by default |\n\n### `eigenpal workflow folders list|ls [options]`\n\nList workflow folders.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--tree` | no | | Render folders as an indented tree |\n\n### `eigenpal workflow folders create [options] <path>`\n\nCreate a folder path, creating any missing parent segments.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow folders rename [options] <path-or-id>`\n\nRename a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--name <name>` | yes | | New folder name |\n\n### `eigenpal workflow folders delete [options] <path-or-id>`\n\nDelete a workflow folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------ | -------- | -------- | ----------- |\n| `path-or-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--yes` | no | | Skip typed-id confirmation (required in CI / agent terminals without a TTY) |\n\n### `eigenpal workflow evaluators pull [options] <workflow-id>`\n\nDownload the workflow's evaluators YAML.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write YAML to file instead of stdout |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow evaluators push [options] <workflow-id>`\n\nOverwrite the workflow's evaluator config from a YAML file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--file <yaml>` | yes | | Path to evaluators YAML file |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluators validate [options] [path]`\n\nValidate an evaluators YAML file against the EvalConfig schema. Defaults to ./evaluators.yaml.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset list|ls [options] <workflow-id>`\n\nList eval examples for the workflow.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `100` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset pull [options] <workflow-id>`\n\nDownload the workflow's dataset as a ZIP archive.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------- | -------- | ------- | ----------------------------------------------------------------------------------- |\n| `--out <zip>` | no | | Write the dataset ZIP to this path. When omitted, the binary streams to stdout. |\n| `--example-id <id>` | no | `[]` | Export only this example (repeatable). When omitted, the whole dataset is exported. |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow dataset push [options] <workflow-id>`\n\nReplace or extend the workflow's dataset from a ZIP or folder.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------ |\n| `--file <path>` | yes | | Path to a dataset ZIP file or a dataset/ folder (folder is zipped in memory before upload) |\n| `--mode <append\\|replace>` | no | `\"append\"` | Import mode (default: append) |\n| `--yes` | no | `false` | Skip the destructive confirmation prompt for --mode replace (use in CI) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example create [options] <workflow-id>`\n\nCreate one eval example without re-uploading the dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | --------------------------------------------------- |\n| `--name <name>` | yes | | Example name (1–64 chars) |\n| `--input-json <json>` | no | | Trigger input as a JSON literal |\n| `--input-file <path>` | no | | Trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Expected output as a JSON literal |\n| `--expected-file <path>` | no | | Expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Free-form annotation |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example update [options] <workflow-id> <exampleId>`\n\nPatch one eval example. Omitted flags are left alone.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | ----------------------------------------------------------- |\n| `--name <name>` | no | | Rename the example (1–64 chars) |\n| `--input-json <json>` | no | | Replace trigger input with this JSON literal |\n| `--input-file <path>` | no | | Replace trigger input from a JSON file (or `-` for stdin) |\n| `--expected-json <json>` | no | | Replace expected output with this JSON literal |\n| `--expected-file <path>` | no | | Replace expected output from a JSON file (or `-` for stdin) |\n| `--annotation <text>` | no | | Replace annotation; pass empty string to clear |\n| `--row-order <n>` | no | | Reorder the row (0-based) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example delete [options] <workflow-id> <exampleId>`\n\nDelete one eval example by id. Non-TTY shells require --yes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--yes` | no | `false` | Required for non-TTY shells; explicit acknowledgment that this is destructive |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset example get [options] <workflow-id> <exampleId>`\n\nFetch one eval example with full triggerInput, expectedOutput, and metadata.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `exampleId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset validate [options] [path]`\n\nValidate a dataset folder against the examples/<name>/{input,expected,meta} convention. Defaults to ./dataset/.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `path` | no | no | |\n\n### `eigenpal workflow dataset review-request list|ls [options] <automation-id>`\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--status <csv>` | no | | Filter by review status (comma-separated: draft,open,paused,closed,cancelled) |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request create [options] <automation-id>`\n\nRequest human review of dataset ground truth. Snapshot examples and poll progress until review is complete.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | yes | | Review request title |\n| `--example-name <name>` | yes | `[]` | Example folder name to include (repeatable) |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Expected-output leaf path to flag across selected examples; parent paths flag every descendant (repeatable) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--ignore <path>` | no | `[]` | Expected-output path reviewers can skip (repeatable) |\n| `--item-note <spec>` | no | `[]` | Example-level note seeded at create time, as exampleName=comment (repeatable) |\n| `--field-note <spec>` | no | `[]` | Field comment only, as exampleName.path=comment; does not flag the field (repeatable) |\n| `--focus-json <json>` | no | | JSON array of { path, reason? } focus fields |\n| `--notes-json <json>` | no | | JSON array of { exampleName, comment?, fields?: [{ path, comment }] } |\n| `--status <draft\\|open\\|paused>` | no | | Initial lifecycle status (default: draft) |\n\n### `eigenpal workflow dataset review-request get [options] <automation-id> <review-id>`\n\nFetch one dataset review request with items, progress, focus fields, ignored fields, expected files, file decisions, and events.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request update [options] <automation-id> <review-id>`\n\nUpdate review metadata or lifecycle status. Set --status closed when review is finished.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--title <title>` | no | | New review request title |\n| `--instructions <text>` | no | | Note shown to the reviewer for the whole request |\n| `--focus <path>` | no | `[]` | Replace focus paths (repeatable; use with --focus-reason / --focus-json) |\n| `--focus-reason <spec>` | no | `[]` | Reason a focus path needs review, as path=reason (repeatable) |\n| `--focus-json <json>` | no | | JSON array of { path, reason? } focus fields (replaces focus) |\n| `--ignore <path>` | no | | Replace ignored paths (repeatable) |\n| `--status <draft\\|open\\|paused\\|closed\\|cancelled>` | no | | Lifecycle status |\n\n### `eigenpal workflow dataset review-request items [options] <automation-id> <review-id>`\n\nList snapshotted review items and their statuses.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--status <csv>` | no | | Filter by item status (pending,approved,edited,removed) |\n\n### `eigenpal workflow dataset review-request events [options] <automation-id> <review-id>`\n\nList review activity, including example and field notes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow dataset review-request item [options] <automation-id> <review-id> <item-id>`\n\nApprove, remove, reopen, comment, edit, or record a field- or file-decision on one review item. Upload corrected expected-file bytes with edit-file.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n| `item-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--action <approve\\|remove\\|reopen\\|comment\\|edit\\|field-decision\\|file-decision\\|edit-file>` | yes | | Item action |\n| `--expected-updated-at <iso>` | yes | | Item updatedAt the client last observed (optimistic concurrency) |\n| `--comment <text>` | no | | Note stored on the item, field, or file |\n| `--field-path <path>` | no | | Dotted expected-output path for comment or field-decision |\n| `--file-path <path>` | no | | Expected-file path for file-decision or edit-file (correct) |\n| `--new-path <path>` | no | | Expected-file path for edit-file uploads of brand-new reviewer files |\n| `--file <local path>` | no | | Local file bytes to upload when --action edit-file |\n| `--decision <approved\\|removed\\|null>` | no | | Field or file decision for --action field-decision or file-decision (null/clear removes it) |\n| `--clear` | no | `false` | Clear a field or file decision (sends decision: null) |\n| `--expected-json <json>` | no | | Replacement expected JSON when --action edit |\n\n### `eigenpal workflow dataset review-request pull [options] <automation-id> <review-id>`\n\nDownload review snapshots: per-example expected files (snapshot or reviewer-corrected) plus item JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| --------------- | -------- | -------- | ----------- |\n| `automation-id` | yes | no | |\n| `review-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ---------------------------------------------- |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n| `--out <dir>` | yes | | Local directory to materialize the review into |\n\n### `eigenpal workflow templates upload [options] <file>`\n\nUpload a DOCX or XLSX file as a new tmpl*… resource with an immutable tmpr*… revision.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------------------------------- |\n| `--name <name>` | no | | Display name (defaults to the filename without extension) |\n| `--description <text>` | no | | Optional description |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates list|ls [options]`\n\nList workspace templates.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates get|inspect [options] <template-id>`\n\nInspect a tmpl*… resource: current tmpr*…, format, checksum, tokens, grammar.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates download [options] <template-id>`\n\nDownload current (or pinned) template bytes.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | --------------------------------- |\n| `--out <path>` | no | | Write to this file (required) |\n| `--revision-id <tmpr>` | no | | Pin an immutable tmpr\\_… revision |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow templates replace [options] <template-id> <file>`\n\nAppend an immutable revision and advance the tmpl\\_… pointer.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n| `file` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates delete [options] <template-id>`\n\nDelete the mutable tmpl*… pointer. Pinned tmpr*… revisions remain so workflows that set templateRevisionId still run.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `template-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--yes` | no | `false` | Required for non-TTY shells |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow templates smoke [options] <template>`\n\nFill a local Office file or a tmpl\\_… resource with a JSON fixture and write the result. Local files never contact the server.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `template` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ------------------------------------------------------------ |\n| `--data <file>` | yes | | Path to a JSON fixture file (object with template data keys) |\n| `--out <path>` | yes | | Filled DOCX/XLSX output path |\n| `--revision-id <tmpr>` | no | | When <template> is a tmpl\\_… id, pin this revision |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp list|ls [options] <workflow-id>`\n\nList executions for the workflow, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--batch-id <id>` | no | | Filter by batch |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp run [options] <workflow-id>`\n\nStart a batch eval against the workflow's dataset.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------- |\n| `--example-id <id>` | no | `[]` | Run only this example (repeatable) |\n| `--wait` | no | `false` | Poll until terminal; non-zero exit on passRate < 1.0 |\n| `--interval <n>` | no | `10` | Polling interval in seconds (default 10) |\n| `--max-wait <seconds>` | no | `1800` | Maximum wait before exit code 2 (default 1800) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp status [options] <workflow-id> <batchId>`\n\nAggregate progress for a batch by `batchId`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--watch` | no | `false` | Poll until every execution reaches a terminal state (completed/failed/cancelled/rejected), then exit |\n| `--short` | no | `false` | Single-line plain-text summary on stdout (e.g. `6/6 done failed=0 cancelled=0 rejected=0`). Pipe-friendly for monitoring loops; mutually exclusive with --watch. |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds when --watch is set (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling for --watch in seconds (default 1800 = 30 min) |\n| `--include <kinds>` | no | `\"\"` | Comma-separated extras to attach when --watch terminates: payload (full per-execution snapshot, can be hundreds of KB) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp cancel [options] <workflow-id> <batchId>`\n\nCancel every execution in a batch. Idempotent.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------- |\n| `--yes` | no | | Required for non-TTY shells (CI, pipes). Acts immediately, no prompt. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp results [options] <workflow-id> [batchId]`\n\nDownload eval results in CSV or JSON.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | no | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------- | -------- | -------- | ---------------------------------------------------------------------------------------- |\n| `--format <csv\\|json>` | no | `\"json\"` | Output format (default json) |\n| `--out <path>` | no | | Output file. When omitted, the binary streams to stdout. |\n| `--summary` | no | | Show total/pass/fail/error counts, average score, and evaluator rollups |\n| `--failed-only` | no | | Keep only failed or errored evaluator results |\n| `--evaluator <name>` | no | | Keep only results from this evaluator |\n| `--select <path>` | no | | Print only a nested JSON value (for example summary.byEvaluator or discrepancies[].path) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp compare|diff [options] <batchIdA> <batchIdB>`\n\nCompare evaluator scores or actual outputs between two experiment batches.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ---------- | -------- | -------- | ----------- |\n| `batchIdA` | yes | no | |\n| `batchIdB` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------------------------------------ | -------- | ------------------ | ------------------------------------------------------ |\n| `--outputs` | no | | Compare actual run outputs instead of evaluator scores |\n| `--sort <abs-delta-desc\\|delta-asc\\|delta-desc\\|name>` | no | `\"abs-delta-desc\"` | Row sort order (default: biggest movers first) |\n| `--regression-threshold <n>` | no | `0.05` | Δ below this is flagged as a regression (default 0.05) |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow experiment|exp watch [options] <workflow-id> <batchId>`\n\nPoll until terminal, then auto-pull results — replaces `status --watch` + `results --out`.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `batchId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| --------------------------- | -------- | -------- | ----------------------------------------------------------------------- |\n| `--interval <seconds>` | no | `5` | Poll interval in seconds (default 5) |\n| `--max-wait <seconds>` | no | `1800` | Hard ceiling in seconds (default 1800 = 30 min) |\n| `--pull-on-complete <path>` | no | | Destination for the results file. Default: ./results-<batchId>.<format> |\n| `--format <csv\\|json>` | no | `\"json\"` | Results export format (default json) |\n| `--no-pull` | no | | Skip auto-pulling results on terminal (watch only) |\n| `--base-url <url>` | no | | Server base URL |\n\n### `eigenpal workflow versions list|ls [options] <workflow-id>`\n\nList tagged workflow versions plus the current untagged snapshot when HEAD is untagged, newest first.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------- |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Print the sliced { data, total, limit, offset } envelope as JSON (not the raw server payload) |\n\n### `eigenpal workflow versions create [options] <workflow-id>`\n\nCreate a tagged workflow version from YAML or by copying an existing snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--file <yaml>` | no | | Path to workflow YAML. Mutually exclusive with --from. |\n| `--allow-external-templates` | no | | Allow local template paths outside the workflow project. Use only for trusted YAML. |\n| `--from <version-id>` | no | | Existing version id to copy into a new tagged snapshot. Leaves the source tag unchanged. Mutually exclusive with --file. |\n| `--set-version <semver>` | no | | Bare semver tag such as 1.4.0. Required when copying with --from. For --file, omit this flag if the YAML already has a top-level version: field. (Named --set-version to avoid the global -v, --version flag.) |\n| `--no-activate` | no | | Keep the tagged version off live traffic until you promote it. Default is to make it current. Requires an existing current version. |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions promote [options] <workflow-id> <versionId>`\n\nMake an existing tagged workflow version current without creating another snapshot.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow versions restore [options] <workflow-id> <versionId>`\n\nRestore a previous snapshot as a new untagged current version. Does not retag the source.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------------- | -------- | -------- | ----------- |\n| `workflow-id` | yes | no | |\n| `versionId` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------------------ |\n| `--message <text>` | no | | Optional restore note stored on the new snapshot |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type list|ls [options]`\n\nList every step type the deployment supports.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow step-type get [options] <type>`\n\nReturn the full schema and behavioral docs for one step type.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------------------------------ |\n| `--out <path>` | no | | Write to file |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluator-type list|ls [options]`\n\nList every evaluator type with a one-line description.\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------ | -------- | ------- | ------------------------------------ |\n| `--search <q>` | no | | Filter by type, name, or description |\n| `--limit <n>` | no | `50` | Page size |\n| `--offset <n>` | no | `0` | Page offset |\n| `--base-url <url>` | no | | Server base URL |\n| `--json` | no | | Emit machine-readable JSON on stdout |\n\n### `eigenpal workflow evaluator-type get [options] <type>`\n\nFetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect specific fields.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| -------------- | -------- | ------- | ------------- |\n| `--out <path>` | no | | Write to file |\n\n### `eigenpal workflow step exec [options] <type>`\n\nDISABLED — local mimic runners removed pending server-side redesign (EIG-104). Use `run` or `workflow experiment run` instead.\n\n### Arguments\n\n| Name | Required | Variadic | Description |\n| ------ | -------- | -------- | ----------- |\n| `type` | yes | no | |\n\n### Options\n\n| Flag | Required | Default | Description |\n| ------------------------ | -------- | ------- | -------------------------------------- |\n| `--config-json <json>` | no | | (unused; kept for back-compat parsing) |\n| `--config-file <path>` | no | | (unused) |\n| `--inputs <pairs...>` | no | | (unused) |\n| `--output-schema <path>` | no | | (unused) |\n"
423
423
  },
424
424
  {
425
425
  "topic": "reference/dataset-format",
@@ -440,7 +440,7 @@
440
440
  "title": "evaluators.yaml — required schema",
441
441
  "description": "Detailed agent reference bundled with the Eigenpal CLI.",
442
442
  "source": "agent-reference",
443
- "content": "# evaluators.yaml — required schema\n\nEvaluators run after a workflow execution to grade its output. They\nattach to a workflow via `workflow evaluators push` and run in batch via\n`workflow experiment run`. The full Zod schema is\n`EvalConfigYamlSchema` in `@eigenpal/types/src/eval/evaluator-config.ts`;\nthis is the agent-facing summary.\n\nEvaluator config does not control dashboard folder placement. Workflow\norganization is managed with `workflow move --folder`;\n`workflow evaluators push` leaves the workflow's folder unchanged.\n\n## Top-level shape\n\n```yaml\nevaluators: # array of evaluator definitions, ≥1 entry\n - name: ... # required, unique within this file, [a-z0-9][a-z0-9-_]*\n description: ... # optional, ≤500 chars; one-sentence business explanation (see below)\n type: ... # required, one of: exact-diff | llm-judge | custom-script\n config: # required, shape depends on `type`\n passThreshold: 0.95 # 0..1, optional (default 1.0)\n ...\n\n# OPTIONAL workflow-level pass threshold. A run passes when its weighted-mean\n# score across evaluators clears this number. Defaults to 0.7.\npassThreshold: 0.7\n```\n\n## Writing descriptions for stakeholders\n\nEvery evaluator entry takes an optional `description`. Always set it. The\ndashboard surfaces this string to non-technical reviewers (legal, ops,\nfinance) who never see the YAML or the judge prompt. Write it for them:\n\n- One short sentence, plain language.\n- Name what the evaluator measures and why a business reader should care.\n- Skip implementation detail (model names, thresholds, dot-paths). Those\n belong in `config`.\n- Keep it under ~120 characters when you can; the schema caps it at 500.\n\n```yaml\n# Good. A non-technical reviewer immediately grasps the intent.\n- name: covenants-recall\n description: Checks every covenant from the contract appears in the extraction.\n type: llm-judge\n config: ...\n\n# Bad. Restates the config; teaches a stakeholder nothing.\n- name: covenants-recall\n description: llm-judge with passThreshold 0.85 over the covenants array.\n type: llm-judge\n config: ...\n```\n\n## Evaluator types\n\n### `exact-diff` — JSON deep-diff against `expected.json`\n\nAuthor comparison with a per-field `rules` map. Each key is a path into the\nworkflow output (the `.data` object). Use `$` to target the full output.\nAn ancestor rule covers its whole subtree; more specific descendants override\ninherited settings. `{}` selects a path with inherited platform defaults.\n\n```yaml\n- name: invoice-fields\n type: exact-diff\n config:\n rules:\n invoiceNumber: {}\n total:\n numericTolerance: 0.01\n lineItems:\n order: unordered\n items: exactly\n matchBy: sku\n lineItems[]:\n allowExtraFields: false\n lineItems[].unitPrice:\n numericTolerance: 0.01\n lineItems[].evidence:\n ignore: true\n```\n\n- `rules` — map of path → comparison settings. Only listed paths (and their\n descendants, unless a descendant adds its own rule) are scored. Omit a path\n to ignore it, or set `$: {}` to compare the entire output with defaults.\n- `numericTolerance` — maximum absolute difference between expected and actual\n numeric values at this path. Use `0` for exact integers; `0.01` is typical\n for currency. When omitted, numeric comparison keeps the historical relative\n epsilon.\n- `order: unordered` — on an array path, match items by value instead of\n position. Matches always use distinct item slots; whether missing expected\n items fail is controlled independently by `items`.\n- `matchBy` — optional identity for unordered arrays of objects. Requires\n `order: unordered` on the same rule. Set on the array path (`lineItems`),\n not the item path (`lineItems[]`). A relative field (`sku`) or unique\n fields (`[country, sku]`) inside each item. Expected and actual objects are\n paired by exact identity first, then the paired objects are compared with\n inherited nested rules, so a matching SKU with the wrong amount reports\n `lineItems[i].amount` instead of \"no matching item\". Applies only at the\n array path where it is set and is not inherited. Identity type and value\n must both match: numeric `10` differs from string `'10'`; no coercion or\n numeric tolerance. With `items: at-least`, extra actual items may omit or\n duplicate identities; with `at-most`, missing expected identities are\n allowed but every actual item being checked needs a unique valid identity;\n `exactly` validates both sides. Omit `matchBy` to keep structural matching,\n which still allows legitimate duplicate objects.\n- `items: at-least` — require every expected item while allowing additional\n actual items (the default). Use `at-most` to permit a subset of expected\n items but reject unexpected actual items, or `exactly` to permit neither.\n- `order` is independent. Ordered arrays use positional prefix matching:\n `at-least` requires expected to match actual from index 0 (trailing actual\n extras only); `at-most` requires actual to match expected from index 0\n (trailing expected extras only); `exactly` is equal-length positional.\n `unordered` ignores positions. Set `order`, `items`, and `matchBy` on\n `lineItems`, not `lineItems[]`.\n- `allowExtraFields: false` — on an object path (often `someArray[]`), reject\n object keys present in actual but absent from expected.\n- `ignore: true` — remove that path and every descendant from both expected and\n actual output. This is useful for volatile evidence, citations, and timestamps\n under an otherwise selected parent. It cannot share a rule with other\n settings. An ignore-only rules map means full output minus those paths.\n\nPath syntax: `lineItems` targets the array; `lineItems[]` targets each element;\n`lineItems[].unitPrice` targets a field inside every element. Nested unordered\nlists use paths such as `groups[].members` with `order: unordered` on that path.\n\nExtract steps may attach `_grounding` metadata under output fields. Exact-diff\nstrips that metadata before comparison, so you do not need a rule to exclude it.\n\nConfigs authored before per-field rules used other top-level `exact-diff`\noptions. Those configs keep working unchanged. Do not mix legacy options with\n`rules` in the same evaluator; validation rejects mixed configs.\n\n`exact-diff` branches on the example's expected shape: success-expected\nexamples (`expected.json`) are diffed against the workflow's actual output, and\nfailure-expected examples (`expected.json` with `$error`, see\n`reference/dataset-format.md`) are matched against the `control.fail`\nenvelope persisted to `executions.error`. The same evaluator handles both\npaths; you do not need a separate evaluator for failure cases.\n\n### `llm-judge` — LLM-as-judge scoring\n\n```yaml\n- name: covenants-recall\n type: llm-judge\n config:\n model: gpt-6-luna # Optional, falls back to the workspace default LLM provider\n mode: continuous # continuous | discrete (default: continuous)\n passThreshold: 0.85\n docLabel: extraction # what the judge calls the workflow output (default: \"output\")\n promptExtension: |\n Score how well the actual output captures every covenant in the\n expected output. Penalise missing covenants; do not penalise\n over-extraction. Be strict on covenants that change loan economics.\n\n# discrete mode — the judge picks a label and the score table maps to a number\n- name: tone-check\n type: llm-judge\n config:\n mode: discrete\n passThreshold: 0.7\n labels:\n excellent: 1.0\n acceptable: 0.7\n off-tone: 0.0\n promptExtension: |\n Pick the label that best matches the tone of the response.\n```\n\n`promptExtension` is the only required field — it is appended to the harness\nprompt and tells the judge what \"good\" looks like for this workflow. The\nharness handles JSON parsing, retries, and feeds the judge `actual`,\n`expected`, and example metadata. In `discrete` mode the judge MUST return\none of the keys in `labels`; the harness then looks up the score.\n\n### `custom-script` — JavaScript in the sandbox\n\n```yaml\n- name: total-with-tolerance\n type: custom-script\n config:\n passThreshold: 1.0\n function: |\n type WorkflowData = {\n totalAmount: number;\n };\n type WorkflowOutput = { data: WorkflowData };\n type Expected = WorkflowOutput;\n type Actual = WorkflowOutput;\n\n function scoreScript(expected: WorkflowOutput, actual: WorkflowOutput): number {\n const a = actual.data.totalAmount ?? 0;\n const e = expected.data.totalAmount ?? 0;\n return Math.abs(a - e) <= 0.01 ? 1 : 0;\n }\n```\n\nSame WASM sandbox as `transform.script` (5s wall clock, 10 MB heap, no\nnetwork). The YAML stores the **whole** typed score source (optional\n`type` aliases plus `function scoreScript(expected, actual): number { ... }`)\nverbatim, same text the dashboard editor shows. The `: number` return-type annotation is required and\nenforced at parse time. The dashboard seeds new evaluators with a\n`WorkflowOutput` type alias derived from the workflow's `output:`\ndeclaration, plus `Expected` / `Actual` aliases for compatibility. Plain\n`unknown` works too if you do not want a typed signature.\n\nBoth arguments are envelopes. Read workflow fields from `expected.data` and\n`actual.data`; the actual envelope may also include `files`.\n\nThe signature shape is **locked**:\n\n- Function name MUST be `scoreScript`.\n- Parameters MUST be `(expected, actual)` in that order. Swapping them\n would silently invert every score.\n- Body MUST `return` a number in `[0, 1]`, or `throw` (which is caught\n and scored as 0).\n\n`workflow validate` and `workflow evaluators validate` flag YAML where\nthe function fails to parse, the signature does not match, or the body\ncontains neither `return` nor `throw` — so a hand-edited config errors\nbefore it reaches the worker.\n\n## Pass / fail vs score\n\nEvery evaluator emits both:\n\n- `score` — numeric, typically `[0, 1]`\n- `passed` — boolean, derived from `score >= passThreshold`\n\nThe batch pass-rate counts examples where **every** evaluator on the\nworkflow passed. A failing single evaluator is enough to fail the\nexample overall.\n\n## Per-example overrides\n\nMost useful for skipping steps that need external state. Example's\n`meta.json`:\n\n```json\n{\n \"overrides\": {\n \"steps\": {\n \"enrich_company\": {\n \"companyName\": \"Acme Corp\",\n \"registeredAt\": \"2020-01-01\"\n }\n }\n }\n}\n```\n\nWhen the workflow runs against this example, `enrich_company` is\nshort-circuited and the override JSON is used as the step's output.\nThe execution row records `overrideMode: 'skipped'` so you can audit\nwhich steps were faked. See `dataset-format.md` for the full meta.json\nschema.\n\n## Validate before pushing\n\n```bash\neigenpal workflow evaluators validate ./evaluators.yaml\n```\n\nReports field-level issues:\n\n```\n✗ evaluators (./evaluators.yaml) — 1 issue\n evaluators.0.config.passThreshold Number must be less than or equal to 1\n```\n\n## Push + run\n\n```bash\n# Push the evaluators (overwrites the workflow's existing config).\neigenpal workflow evaluators push <workflow-id> --file evaluators.yaml\n\n# Kick off a server-side batch eval over the whole pushed dataset.\n# Returns { batchId, total }.\neigenpal workflow experiment run <workflow-id>\n\n# Or restrict to a single example:\neigenpal workflow experiment run <workflow-id> --example-id evx_…\n\n# Watch progress.\neigenpal workflow experiment status <workflow-id> <batch-id>\n\n# Pull results when done.\neigenpal workflow experiment results <workflow-id> <batch-id> \\\n --format csv --out results.csv\n```\n\nThe signed-URL pattern means large result sets do not go through the CLI\nprocess — `--out` writes the file directly from the server's storage.\n\n## Stabilizing flaky judges\n\nLLM-judge scores have variance. To reduce flake:\n\n- Select a current model (`openai/gpt-6.1-sol`) and keep its reasoning effort fixed.\n Re-run representative evaluations when changing models or when the provider updates it.\n- Keep `promptExtension` narrow — score one dimension per evaluator. Use\n multiple judges instead of one omnibus prompt.\n- Prefer `mode: discrete` with a small label set when the judgement is\n categorical (good / acceptable / bad) — it eliminates the model's\n free-form numeric drift.\n- For high-stakes thresholds, run the experiment ≥3 times and average.\n\n<!-- GENERATED:EVALUATOR_CATALOG START -->\n## Evaluator types — full reference\n\n_Generated from `EvalConfigYamlSchema` in `@eigenpal/types/src/eval/evaluator-config.ts`. Do not hand-edit between the GENERATED fences — run `bun run --cwd packages/cli generate:skill`._\n\n### Top-level `evaluators.yaml`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `evaluators` | array<object> | no | `[]` | Evaluator entries run after each experiment execution. |\n| `passThreshold` | number | no | | Workflow-level pass threshold for the weighted mean score. When omitted, legacy evaluator thresholds are combined for compatibility, otherwise the platform default is 0.7. |\n\n### Evaluator entry envelope\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `name` | string | yes | | Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall. |\n| `description` | string | no | | One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`. |\n| `weight` | number | no | `1` | Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall. |\n\n- `type` — required discriminator: `exact-diff`, `llm-judge`, `custom-script`.\n- `config` — required object whose fields are defined by the selected evaluator type below.\n\n### `exact-diff` — JSON deep-diff against expected output\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `rules` | record<string, object> | no | | Per-path comparison rules. Non-ignored keys select compared paths (`$` = full output); an ignore-only map means full output minus those paths. More-specific keys inherit then override parent rules. `{}` selects a path using inherited platform defaults; `{ ignore: true }` excludes it. Do not mix with legacy `paths`, `unorderedPaths`, `numericTolerance`, or `allowExtraFields`. |\n| `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. |\n| `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. |\n| `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. |\n| `paths` | array<string> | no | | Legacy scoped paths. Prefer selecting those paths as `rules` keys. Syntax: `header.id`, `lineItems[].total`, `lineItems[0].sku`. |\n| `unorderedPaths` | array<string> | no | | Legacy unordered array paths. Prefer `rules.<path>.order: unordered`. Name the array field itself (`subjects`, not `subjects[]`). |\n\n#### Per-path `rules` fields\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `ignore` | `true` | no | | Exclude this path and every descendant from comparison. Cannot be combined with other settings on the same rule. |\n| `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. |\n| `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). |\n| `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. |\n| `allowExtraFields` | boolean | no | | When false, extra actual keys at this object fail the diff. When omitted, extra keys are allowed. Applies only to objects. |\n| `numericTolerance` | number | no | | Maximum absolute difference for numeric leaves at or under this path. Omitted = inherit, then historical relative epsilon. Explicit `0` is exact. |\n\n\n### `llm-judge` — LLM-as-judge scoring\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `model` | string | no | | Which LLM grades the output. Falls back to the workspace's default LLM provider when unset. |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `mode` | `\"continuous\"` \\| `\"discrete\"` | no | `\"continuous\"` | Continuous = the LLM returns a free-form score in [0, 1]. Discrete = the LLM picks one of your labels and the score is looked up from the table. |\n| `labels` | record<string, number> | no | | Allowed labels and the score each maps to. Required in discrete mode. The judge MUST return one of these labels; each score must be in [0, 1]. |\n| `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. |\n| `promptExtension` | string | yes | | Required. Evaluation criteria appended to the judge prompt — describe what makes a good answer for this workflow (tone, completeness, edge cases). Cannot be empty: an empty prompt yields the model inventing its own criteria. |\n| `docLabel` | string | no | `\"output\"` | Name the judge uses to refer to the output in its prompt (e.g. 'invoice', 'extraction'). Default is 'output'. |\n\n\n### `custom-script` — JavaScript in the sandbox\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `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. |\n| `timeoutMs` | integer | no | `5000` | Maximum wall-clock time the script can run before it is killed and the run is marked failed. |\n| `memoryLimitMb` | integer | no | `10` | Maximum memory the sandbox may allocate. Increase if the script processes large arrays or strings. |\n| `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. |\n\n\n### Complete machine-readable `evaluators.yaml` schema\n\nGenerated from the same discriminated union used by evaluator validation; YAML keys and nesting are identical.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"evaluators\": {\n \"default\": [],\n \"description\": \"Evaluator entries run after each experiment execution.\",\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 64,\n \"pattern\": \"^[a-z0-9-]+$\",\n \"description\": \"Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall.\"\n },\n \"description\": {\n \"description\": \"One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`.\",\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"weight\": {\n \"default\": 1,\n \"description\": \"Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"type\": {\n \"type\": \"string\",\n \"const\": \"exact-diff\",\n \"description\": \"Deterministic structured-output comparison.\"\n },\n \"config\": {\n \"default\": {},\n \"description\": \"Configuration for exact-diff.\",\n \"type\": \"object\",\n \"properties\": {\n \"rules\": {\n \"description\": \"Per-path comparison rules. Non-ignored keys select compared paths (`$` = full output); an ignore-only map means full output minus those paths. More-specific keys inherit then override parent rules. `{}` selects a path using inherited platform defaults; `{ ignore: true }` excludes it. Do not mix with legacy `paths`, `unorderedPaths`, `numericTolerance`, or `allowExtraFields`.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"ignore\": {\n \"description\": \"Exclude this path and every descendant from comparison. Cannot be combined with other settings on the same rule.\",\n \"type\": \"boolean\",\n \"const\": true\n },\n \"order\": {\n \"description\": \"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.\",\n \"type\": \"string\",\n \"enum\": [\n \"ordered\",\n \"unordered\"\n ]\n },\n \"items\": {\n \"description\": \"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).\",\n \"type\": \"string\",\n \"enum\": [\n \"at-least\",\n \"at-most\",\n \"exactly\"\n ]\n },\n \"matchBy\": {\n \"description\": \"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.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[^.[\\\\]\\\\s$,]+(?:\\\\.[^.[\\\\]\\\\s$,]+)*$\"\n },\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[^.[\\\\]\\\\s$,]+(?:\\\\.[^.[\\\\]\\\\s$,]+)*$\"\n }\n }\n ]\n },\n \"allowExtraFields\": {\n \"description\": \"When false, extra actual keys at this object fail the diff. When omitted, extra keys are allowed. Applies only to objects.\",\n \"type\": \"boolean\"\n },\n \"numericTolerance\": {\n \"description\": \"Maximum absolute difference for numeric leaves at or under this path. Omitted = inherit, then historical relative epsilon. Explicit `0` is exact.\",\n \"type\": \"number\",\n \"minimum\": 0\n }\n },\n \"additionalProperties\": false\n }\n },\n \"numericTolerance\": {\n \"description\": \"Legacy global numeric tolerance (absolute). When omitted, comparison uses historical relative epsilon. Prefer `rules.<path>.numericTolerance`. Accepted only when `rules` is omitted.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"allowExtraFields\": {\n \"description\": \"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.\",\n \"type\": \"boolean\"\n },\n \"passThreshold\": {\n \"description\": \"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.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"paths\": {\n \"description\": \"Legacy scoped paths. Prefer selecting those paths as `rules` keys. Syntax: `header.id`, `lineItems[].total`, `lineItems[0].sku`.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"unorderedPaths\": {\n \"description\": \"Legacy unordered array paths. Prefer `rules.<path>.order: unordered`. Name the array field itself (`subjects`, not `subjects[]`).\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[^.[\\\\]\\\\s]+(?:(?:\\\\[\\\\])?\\\\.[^.[\\\\]\\\\s]+)*$\"\n }\n }\n },\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"name\",\n \"weight\",\n \"type\",\n \"config\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 64,\n \"pattern\": \"^[a-z0-9-]+$\",\n \"description\": \"Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall.\"\n },\n \"description\": {\n \"description\": \"One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`.\",\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"weight\": {\n \"default\": 1,\n \"description\": \"Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"type\": {\n \"type\": \"string\",\n \"const\": \"llm-judge\",\n \"description\": \"Model-graded semantic comparison.\"\n },\n \"config\": {\n \"type\": \"object\",\n \"properties\": {\n \"model\": {\n \"description\": \"Which LLM grades the output. Falls back to the workspace's default LLM provider when unset.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"mode\": {\n \"default\": \"continuous\",\n \"description\": \"Continuous = the LLM returns a free-form score in [0, 1]. Discrete = the LLM picks one of your labels and the score is looked up from the table.\",\n \"type\": \"string\",\n \"enum\": [\n \"continuous\",\n \"discrete\"\n ]\n },\n \"labels\": {\n \"description\": \"Allowed labels and the score each maps to. Required in discrete mode. The judge MUST return one of these labels; each score must be in [0, 1].\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"additionalProperties\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"passThreshold\": {\n \"description\": \"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.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"promptExtension\": {\n \"type\": \"string\",\n \"minLength\": 10,\n \"description\": \"Required. Evaluation criteria appended to the judge prompt — describe what makes a good answer for this workflow (tone, completeness, edge cases). Cannot be empty: an empty prompt yields the model inventing its own criteria.\"\n },\n \"docLabel\": {\n \"default\": \"output\",\n \"description\": \"Name the judge uses to refer to the output in its prompt (e.g. 'invoice', 'extraction'). Default is 'output'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"mode\",\n \"promptExtension\",\n \"docLabel\"\n ],\n \"additionalProperties\": false,\n \"description\": \"Configuration for llm-judge.\"\n }\n },\n \"required\": [\n \"name\",\n \"weight\",\n \"type\",\n \"config\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 64,\n \"pattern\": \"^[a-z0-9-]+$\",\n \"description\": \"Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall.\"\n },\n \"description\": {\n \"description\": \"One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`.\",\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"weight\": {\n \"default\": 1,\n \"description\": \"Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"type\": {\n \"type\": \"string\",\n \"const\": \"custom-script\",\n \"description\": \"Typed deterministic scoring script.\"\n },\n \"config\": {\n \"type\": \"object\",\n \"properties\": {\n \"function\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 10000,\n \"description\": \"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.\"\n },\n \"timeoutMs\": {\n \"default\": 5000,\n \"description\": \"Maximum wall-clock time the script can run before it is killed and the run is marked failed.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 30000\n },\n \"memoryLimitMb\": {\n \"default\": 10,\n \"description\": \"Maximum memory the sandbox may allocate. Increase if the script processes large arrays or strings.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 50\n },\n \"passThreshold\": {\n \"description\": \"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.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"required\": [\n \"function\",\n \"timeoutMs\",\n \"memoryLimitMb\"\n ],\n \"additionalProperties\": false,\n \"description\": \"Configuration for custom-script.\"\n }\n },\n \"required\": [\n \"name\",\n \"weight\",\n \"type\",\n \"config\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"passThreshold\": {\n \"description\": \"Workflow-level pass threshold for the weighted mean score. When omitted, legacy evaluator thresholds are combined for compatibility, otherwise the platform default is 0.7.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"required\": [\n \"evaluators\"\n ],\n \"additionalProperties\": false\n}\n```\n<!-- GENERATED:EVALUATOR_CATALOG END -->\n"
443
+ "content": "# evaluators.yaml — required schema\n\nEvaluators run after a workflow execution to grade its output. They\nattach to a workflow via `workflow evaluators push` and run in batch via\n`workflow experiment run`. The full Zod schema is\n`EvalConfigYamlSchema` in `@eigenpal/types/src/eval/evaluator-config.ts`;\nthis is the agent-facing summary.\n\nEvaluator config does not control dashboard folder placement. Workflow\norganization is managed with `workflow move --folder`;\n`workflow evaluators push` leaves the workflow's folder unchanged.\n\n## Top-level shape\n\n```yaml\nevaluators: # array of evaluator definitions, ≥1 entry\n - name: ... # required, unique within this file, [a-z0-9][a-z0-9-_]*\n description: ... # optional, ≤500 chars; one-sentence business explanation (see below)\n type: ... # required, one of: exact-diff | llm-judge | custom-script\n config: # required, shape depends on `type`\n passThreshold: 0.95 # 0..1, optional (default 1.0)\n ...\n\n# OPTIONAL workflow-level pass threshold. A run passes when its weighted-mean\n# score across evaluators clears this number. Defaults to 0.7.\npassThreshold: 0.7\n```\n\n## Writing descriptions for stakeholders\n\nEvery evaluator entry takes an optional `description`. Always set it. The\ndashboard surfaces this string to non-technical reviewers (legal, ops,\nfinance) who never see the YAML or the judge prompt. Write it for them:\n\n- One short sentence, plain language.\n- Name what the evaluator measures and why a business reader should care.\n- Skip implementation detail (model names, thresholds, dot-paths). Those\n belong in `config`.\n- Keep it under ~120 characters when you can; the schema caps it at 500.\n\n```yaml\n# Good. A non-technical reviewer immediately grasps the intent.\n- name: covenants-recall\n description: Checks every covenant from the contract appears in the extraction.\n type: llm-judge\n config: ...\n\n# Bad. Restates the config; teaches a stakeholder nothing.\n- name: covenants-recall\n description: llm-judge with passThreshold 0.85 over the covenants array.\n type: llm-judge\n config: ...\n```\n\n## Evaluator types\n\n### `exact-diff` — JSON deep-diff against `expected.json`\n\nAuthor comparison with a per-field `rules` map. Each key is a path into the\nworkflow output (the `.data` object). Use `$` to target the full output.\nAn ancestor rule covers its whole subtree; more specific descendants override\ninherited settings. `{}` selects a path with inherited platform defaults.\n\n```yaml\n- name: invoice-fields\n type: exact-diff\n config:\n rules:\n invoiceNumber: {}\n total:\n numericTolerance: 0.01\n lineItems:\n order: unordered\n items: exactly\n matchBy: sku\n lineItems[]:\n allowExtraFields: false\n lineItems[].unitPrice:\n numericTolerance: 0.01\n lineItems[].evidence:\n ignore: true\n```\n\n- `rules` — map of path → comparison settings. Only listed paths (and their\n descendants, unless a descendant adds its own rule) are scored. Omit a path\n to ignore it, or set `$: {}` to compare the entire output with defaults.\n- `numericTolerance` — maximum absolute difference between expected and actual\n numeric values at this path. Use `0` for exact integers; `0.01` is typical\n for currency. When omitted, numeric comparison keeps the historical relative\n epsilon.\n- `order: unordered` — on an array path, match items by value instead of\n position. Matches always use distinct item slots; whether missing expected\n items fail is controlled independently by `items`.\n- `matchBy` — optional identity for unordered arrays of objects. Requires\n `order: unordered` on the same rule. Set on the array path (`lineItems`),\n not the item path (`lineItems[]`). A relative field (`sku`) or unique\n fields (`[country, sku]`) inside each item. Expected and actual objects are\n paired by exact identity first, then the paired objects are compared with\n inherited nested rules, so a matching SKU with the wrong amount reports\n `lineItems[i].amount` instead of \"no matching item\". Applies only at the\n array path where it is set and is not inherited. Identity type and value\n must both match: numeric `10` differs from string `'10'`; no coercion or\n numeric tolerance. With `items: at-least`, extra actual items may omit or\n duplicate identities; with `at-most`, missing expected identities are\n allowed but every actual item being checked needs a unique valid identity;\n `exactly` validates both sides. Omit `matchBy` to keep structural matching,\n which still allows legitimate duplicate objects.\n- `items: at-least` — require every expected item while allowing additional\n actual items (the default). Use `at-most` to permit a subset of expected\n items but reject unexpected actual items, or `exactly` to permit neither.\n- `order` is independent. Ordered arrays use positional prefix matching:\n `at-least` requires expected to match actual from index 0 (trailing actual\n extras only); `at-most` requires actual to match expected from index 0\n (trailing expected extras only); `exactly` is equal-length positional.\n `unordered` ignores positions. Set `order`, `items`, and `matchBy` on\n `lineItems`, not `lineItems[]`.\n- `allowExtraFields: false` — on an object path (often `someArray[]`), reject\n object keys present in actual but absent from expected.\n- `ignore: true` — remove that path and every descendant from both expected and\n actual output. This is useful for volatile evidence, citations, and timestamps\n under an otherwise selected parent. It cannot share a rule with other\n settings. An ignore-only rules map means full output minus those paths.\n- Expected `null` and `\"\"` are real expectations, not blanks: `null` passes\n only when the output is `null` or leaves the field out, and `\"\"` only when\n the output is `\"\"`. To skip a field, use `ignore: true` or the `__any__`\n wildcard instead.\n\nPath syntax: `lineItems` targets the array; `lineItems[]` targets each element;\n`lineItems[].unitPrice` targets a field inside every element. Nested unordered\nlists use paths such as `groups[].members` with `order: unordered` on that path.\n\nExtract steps may attach `_grounding` metadata under output fields. Exact-diff\nstrips that metadata before comparison, so you do not need a rule to exclude it.\n\nConfigs authored before per-field rules used other top-level `exact-diff`\noptions. Those configs keep working unchanged. Do not mix legacy options with\n`rules` in the same evaluator; validation rejects mixed configs.\n\n`exact-diff` branches on the example's expected shape: success-expected\nexamples (`expected.json`) are diffed against the workflow's actual output, and\nfailure-expected examples (`expected.json` with `$error`, see\n`reference/dataset-format.md`) are matched against the `control.fail`\nenvelope persisted to `executions.error`. The same evaluator handles both\npaths; you do not need a separate evaluator for failure cases.\n\n### `llm-judge` — LLM-as-judge scoring\n\n```yaml\n- name: covenants-recall\n type: llm-judge\n config:\n model: gpt-6-luna # Optional, falls back to the workspace default LLM provider\n mode: continuous # continuous | discrete (default: continuous)\n passThreshold: 0.85\n docLabel: extraction # what the judge calls the workflow output (default: \"output\")\n promptExtension: |\n Score how well the actual output captures every covenant in the\n expected output. Penalise missing covenants; do not penalise\n over-extraction. Be strict on covenants that change loan economics.\n\n# discrete mode — the judge picks a label and the score table maps to a number\n- name: tone-check\n type: llm-judge\n config:\n mode: discrete\n passThreshold: 0.7\n labels:\n excellent: 1.0\n acceptable: 0.7\n off-tone: 0.0\n promptExtension: |\n Pick the label that best matches the tone of the response.\n```\n\n`promptExtension` is the only required field — it is appended to the harness\nprompt and tells the judge what \"good\" looks like for this workflow. The\nharness handles JSON parsing, retries, and feeds the judge `actual`,\n`expected`, and example metadata. In `discrete` mode the judge MUST return\none of the keys in `labels`; the harness then looks up the score.\n\n### `custom-script` — JavaScript in the sandbox\n\n```yaml\n- name: total-with-tolerance\n type: custom-script\n config:\n passThreshold: 1.0\n function: |\n type WorkflowData = {\n totalAmount: number;\n };\n type WorkflowOutput = { data: WorkflowData };\n type Expected = WorkflowOutput;\n type Actual = WorkflowOutput;\n\n function scoreScript(expected: WorkflowOutput, actual: WorkflowOutput): number {\n const a = actual.data.totalAmount ?? 0;\n const e = expected.data.totalAmount ?? 0;\n return Math.abs(a - e) <= 0.01 ? 1 : 0;\n }\n```\n\nSame WASM sandbox as `transform.script` (5s wall clock, 10 MB heap, no\nnetwork). The YAML stores the **whole** typed score source (optional\n`type` aliases plus `function scoreScript(expected, actual): number { ... }`)\nverbatim, same text the dashboard editor shows. The `: number` return-type annotation is required and\nenforced at parse time. The dashboard seeds new evaluators with a\n`WorkflowOutput` type alias derived from the workflow's `output:`\ndeclaration, plus `Expected` / `Actual` aliases for compatibility. Plain\n`unknown` works too if you do not want a typed signature.\n\nBoth arguments are envelopes. Read workflow fields from `expected.data` and\n`actual.data`; the actual envelope may also include `files`.\n\nThe signature shape is **locked**:\n\n- Function name MUST be `scoreScript`.\n- Parameters MUST be `(expected, actual)` in that order. Swapping them\n would silently invert every score.\n- Body MUST `return` a number in `[0, 1]`, or `throw` (which is caught\n and scored as 0).\n\n`workflow validate` and `workflow evaluators validate` flag YAML where\nthe function fails to parse, the signature does not match, or the body\ncontains neither `return` nor `throw` — so a hand-edited config errors\nbefore it reaches the worker.\n\n## Pass / fail vs score\n\nEvery evaluator emits both:\n\n- `score` — numeric, typically `[0, 1]`\n- `passed` — boolean, derived from `score >= passThreshold`\n\nThe batch pass-rate counts examples where **every** evaluator on the\nworkflow passed. A failing single evaluator is enough to fail the\nexample overall.\n\n## Per-example overrides\n\nMost useful for skipping steps that need external state. Example's\n`meta.json`:\n\n```json\n{\n \"overrides\": {\n \"steps\": {\n \"enrich_company\": {\n \"companyName\": \"Acme Corp\",\n \"registeredAt\": \"2020-01-01\"\n }\n }\n }\n}\n```\n\nWhen the workflow runs against this example, `enrich_company` is\nshort-circuited and the override JSON is used as the step's output.\nThe execution row records `overrideMode: 'skipped'` so you can audit\nwhich steps were faked. See `dataset-format.md` for the full meta.json\nschema.\n\n## Validate before pushing\n\n```bash\neigenpal workflow evaluators validate ./evaluators.yaml\n```\n\nReports field-level issues:\n\n```\n✗ evaluators (./evaluators.yaml) — 1 issue\n evaluators.0.config.passThreshold Number must be less than or equal to 1\n```\n\n## Push + run\n\n```bash\n# Push the evaluators (overwrites the workflow's existing config).\neigenpal workflow evaluators push <workflow-id> --file evaluators.yaml\n\n# Kick off a server-side batch eval over the whole pushed dataset.\n# Returns { batchId, total }.\neigenpal workflow experiment run <workflow-id>\n\n# Or restrict to a single example:\neigenpal workflow experiment run <workflow-id> --example-id evx_…\n\n# Watch progress.\neigenpal workflow experiment status <workflow-id> <batch-id>\n\n# Pull results when done.\neigenpal workflow experiment results <workflow-id> <batch-id> \\\n --format csv --out results.csv\n```\n\nThe signed-URL pattern means large result sets do not go through the CLI\nprocess — `--out` writes the file directly from the server's storage.\n\n## Stabilizing flaky judges\n\nLLM-judge scores have variance. To reduce flake:\n\n- Select a current model (`openai/gpt-6.1-sol`) and keep its reasoning effort fixed.\n Re-run representative evaluations when changing models or when the provider updates it.\n- Keep `promptExtension` narrow — score one dimension per evaluator. Use\n multiple judges instead of one omnibus prompt.\n- Prefer `mode: discrete` with a small label set when the judgement is\n categorical (good / acceptable / bad) — it eliminates the model's\n free-form numeric drift.\n- For high-stakes thresholds, run the experiment ≥3 times and average.\n\n<!-- GENERATED:EVALUATOR_CATALOG START -->\n## Evaluator types — full reference\n\n_Generated from `EvalConfigYamlSchema` in `@eigenpal/types/src/eval/evaluator-config.ts`. Do not hand-edit between the GENERATED fences — run `bun run --cwd packages/cli generate:skill`._\n\n### Top-level `evaluators.yaml`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `evaluators` | array<object> | no | `[]` | Evaluator entries run after each experiment execution. |\n| `passThreshold` | number | no | | Workflow-level pass threshold for the weighted mean score. When omitted, legacy evaluator thresholds are combined for compatibility, otherwise the platform default is 0.7. |\n\n### Evaluator entry envelope\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `name` | string | yes | | Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall. |\n| `description` | string | no | | One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`. |\n| `weight` | number | no | `1` | Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall. |\n\n- `type` — required discriminator: `exact-diff`, `llm-judge`, `custom-script`.\n- `config` — required object whose fields are defined by the selected evaluator type below.\n\n### `exact-diff` — JSON deep-diff against expected output\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `rules` | record<string, object> | no | | Per-path comparison rules. Non-ignored keys select compared paths (`$` = full output); an ignore-only map means full output minus those paths. More-specific keys inherit then override parent rules. `{}` selects a path using inherited platform defaults; `{ ignore: true }` excludes it. Do not mix with legacy `paths`, `unorderedPaths`, `numericTolerance`, or `allowExtraFields`. |\n| `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. |\n| `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. |\n| `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. |\n| `paths` | array<string> | no | | Legacy scoped paths. Prefer selecting those paths as `rules` keys. Syntax: `header.id`, `lineItems[].total`, `lineItems[0].sku`. |\n| `unorderedPaths` | array<string> | no | | Legacy unordered array paths. Prefer `rules.<path>.order: unordered`. Name the array field itself (`subjects`, not `subjects[]`). |\n\n#### Per-path `rules` fields\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `ignore` | `true` | no | | Exclude this path and every descendant from comparison. Cannot be combined with other settings on the same rule. |\n| `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. |\n| `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). |\n| `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. |\n| `allowExtraFields` | boolean | no | | When false, extra actual keys at this object fail the diff. When omitted, extra keys are allowed. Applies only to objects. |\n| `numericTolerance` | number | no | | Maximum absolute difference for numeric leaves at or under this path. Omitted = inherit, then historical relative epsilon. Explicit `0` is exact. |\n\n\n### `llm-judge` — LLM-as-judge scoring\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `model` | string | no | | Which LLM grades the output. Falls back to the workspace's default LLM provider when unset. |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `mode` | `\"continuous\"` \\| `\"discrete\"` | no | `\"continuous\"` | Continuous = the LLM returns a free-form score in [0, 1]. Discrete = the LLM picks one of your labels and the score is looked up from the table. |\n| `labels` | record<string, number> | no | | Allowed labels and the score each maps to. Required in discrete mode. The judge MUST return one of these labels; each score must be in [0, 1]. |\n| `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. |\n| `promptExtension` | string | yes | | Required. Evaluation criteria appended to the judge prompt — describe what makes a good answer for this workflow (tone, completeness, edge cases). Cannot be empty: an empty prompt yields the model inventing its own criteria. |\n| `docLabel` | string | no | `\"output\"` | Name the judge uses to refer to the output in its prompt (e.g. 'invoice', 'extraction'). Default is 'output'. |\n\n\n### `custom-script` — JavaScript in the sandbox\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `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. |\n| `timeoutMs` | integer | no | `5000` | Maximum wall-clock time the script can run before it is killed and the run is marked failed. |\n| `memoryLimitMb` | integer | no | `10` | Maximum memory the sandbox may allocate. Increase if the script processes large arrays or strings. |\n| `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. |\n\n\n### Complete machine-readable `evaluators.yaml` schema\n\nGenerated from the same discriminated union used by evaluator validation; YAML keys and nesting are identical.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"evaluators\": {\n \"default\": [],\n \"description\": \"Evaluator entries run after each experiment execution.\",\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 64,\n \"pattern\": \"^[a-z0-9-]+$\",\n \"description\": \"Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall.\"\n },\n \"description\": {\n \"description\": \"One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`.\",\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"weight\": {\n \"default\": 1,\n \"description\": \"Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"type\": {\n \"type\": \"string\",\n \"const\": \"exact-diff\",\n \"description\": \"Deterministic structured-output comparison.\"\n },\n \"config\": {\n \"default\": {},\n \"description\": \"Configuration for exact-diff.\",\n \"type\": \"object\",\n \"properties\": {\n \"rules\": {\n \"description\": \"Per-path comparison rules. Non-ignored keys select compared paths (`$` = full output); an ignore-only map means full output minus those paths. More-specific keys inherit then override parent rules. `{}` selects a path using inherited platform defaults; `{ ignore: true }` excludes it. Do not mix with legacy `paths`, `unorderedPaths`, `numericTolerance`, or `allowExtraFields`.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"ignore\": {\n \"description\": \"Exclude this path and every descendant from comparison. Cannot be combined with other settings on the same rule.\",\n \"type\": \"boolean\",\n \"const\": true\n },\n \"order\": {\n \"description\": \"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.\",\n \"type\": \"string\",\n \"enum\": [\n \"ordered\",\n \"unordered\"\n ]\n },\n \"items\": {\n \"description\": \"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).\",\n \"type\": \"string\",\n \"enum\": [\n \"at-least\",\n \"at-most\",\n \"exactly\"\n ]\n },\n \"matchBy\": {\n \"description\": \"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.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[^.[\\\\]\\\\s$,]+(?:\\\\.[^.[\\\\]\\\\s$,]+)*$\"\n },\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[^.[\\\\]\\\\s$,]+(?:\\\\.[^.[\\\\]\\\\s$,]+)*$\"\n }\n }\n ]\n },\n \"allowExtraFields\": {\n \"description\": \"When false, extra actual keys at this object fail the diff. When omitted, extra keys are allowed. Applies only to objects.\",\n \"type\": \"boolean\"\n },\n \"numericTolerance\": {\n \"description\": \"Maximum absolute difference for numeric leaves at or under this path. Omitted = inherit, then historical relative epsilon. Explicit `0` is exact.\",\n \"type\": \"number\",\n \"minimum\": 0\n }\n },\n \"additionalProperties\": false\n }\n },\n \"numericTolerance\": {\n \"description\": \"Legacy global numeric tolerance (absolute). When omitted, comparison uses historical relative epsilon. Prefer `rules.<path>.numericTolerance`. Accepted only when `rules` is omitted.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"allowExtraFields\": {\n \"description\": \"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.\",\n \"type\": \"boolean\"\n },\n \"passThreshold\": {\n \"description\": \"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.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"paths\": {\n \"description\": \"Legacy scoped paths. Prefer selecting those paths as `rules` keys. Syntax: `header.id`, `lineItems[].total`, `lineItems[0].sku`.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"unorderedPaths\": {\n \"description\": \"Legacy unordered array paths. Prefer `rules.<path>.order: unordered`. Name the array field itself (`subjects`, not `subjects[]`).\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"pattern\": \"^[^.[\\\\]\\\\s]+(?:(?:\\\\[\\\\])?\\\\.[^.[\\\\]\\\\s]+)*$\"\n }\n }\n },\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"name\",\n \"weight\",\n \"type\",\n \"config\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 64,\n \"pattern\": \"^[a-z0-9-]+$\",\n \"description\": \"Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall.\"\n },\n \"description\": {\n \"description\": \"One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`.\",\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"weight\": {\n \"default\": 1,\n \"description\": \"Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"type\": {\n \"type\": \"string\",\n \"const\": \"llm-judge\",\n \"description\": \"Model-graded semantic comparison.\"\n },\n \"config\": {\n \"type\": \"object\",\n \"properties\": {\n \"model\": {\n \"description\": \"Which LLM grades the output. Falls back to the workspace's default LLM provider when unset.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"mode\": {\n \"default\": \"continuous\",\n \"description\": \"Continuous = the LLM returns a free-form score in [0, 1]. Discrete = the LLM picks one of your labels and the score is looked up from the table.\",\n \"type\": \"string\",\n \"enum\": [\n \"continuous\",\n \"discrete\"\n ]\n },\n \"labels\": {\n \"description\": \"Allowed labels and the score each maps to. Required in discrete mode. The judge MUST return one of these labels; each score must be in [0, 1].\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"additionalProperties\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"passThreshold\": {\n \"description\": \"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.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"promptExtension\": {\n \"type\": \"string\",\n \"minLength\": 10,\n \"description\": \"Required. Evaluation criteria appended to the judge prompt — describe what makes a good answer for this workflow (tone, completeness, edge cases). Cannot be empty: an empty prompt yields the model inventing its own criteria.\"\n },\n \"docLabel\": {\n \"default\": \"output\",\n \"description\": \"Name the judge uses to refer to the output in its prompt (e.g. 'invoice', 'extraction'). Default is 'output'.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"mode\",\n \"promptExtension\",\n \"docLabel\"\n ],\n \"additionalProperties\": false,\n \"description\": \"Configuration for llm-judge.\"\n }\n },\n \"required\": [\n \"name\",\n \"weight\",\n \"type\",\n \"config\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 64,\n \"pattern\": \"^[a-z0-9-]+$\",\n \"description\": \"Identifier used in eval results and the weighted-mean formula. Use a short kebab-case slug like header-exact or covenants-recall.\"\n },\n \"description\": {\n \"description\": \"One-sentence explanation, in business language, of what this evaluator measures and why a stakeholder should care. Shown in the dashboard to non-technical reviewers (legal, ops, finance) who never see the YAML or judge prompt. Skip implementation detail (model names, thresholds, dot-paths); those live in `config`.\",\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"weight\": {\n \"default\": 1,\n \"description\": \"Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall.\",\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"type\": {\n \"type\": \"string\",\n \"const\": \"custom-script\",\n \"description\": \"Typed deterministic scoring script.\"\n },\n \"config\": {\n \"type\": \"object\",\n \"properties\": {\n \"function\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 10000,\n \"description\": \"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.\"\n },\n \"timeoutMs\": {\n \"default\": 5000,\n \"description\": \"Maximum wall-clock time the script can run before it is killed and the run is marked failed.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 30000\n },\n \"memoryLimitMb\": {\n \"default\": 10,\n \"description\": \"Maximum memory the sandbox may allocate. Increase if the script processes large arrays or strings.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 50\n },\n \"passThreshold\": {\n \"description\": \"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.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"required\": [\n \"function\",\n \"timeoutMs\",\n \"memoryLimitMb\"\n ],\n \"additionalProperties\": false,\n \"description\": \"Configuration for custom-script.\"\n }\n },\n \"required\": [\n \"name\",\n \"weight\",\n \"type\",\n \"config\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"passThreshold\": {\n \"description\": \"Workflow-level pass threshold for the weighted mean score. When omitted, legacy evaluator thresholds are combined for compatibility, otherwise the platform default is 0.7.\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"required\": [\n \"evaluators\"\n ],\n \"additionalProperties\": false\n}\n```\n<!-- GENERATED:EVALUATOR_CATALOG END -->\n"
444
444
  },
445
445
  {
446
446
  "topic": "reference/step-exec",
@@ -454,7 +454,7 @@
454
454
  "title": "Step types",
455
455
  "description": "Detailed agent reference bundled with the Eigenpal CLI.",
456
456
  "source": "agent-reference",
457
- "content": "# Step types\n\nThe catalog is generated from `STEP_SCHEMAS` in\n`@eigenpal/types/src/workflow/step-configs.ts`. **Do not memorize fields\n— introspect.** The CLI reads the live schema:\n\n```bash\n# List every step type with a one-line description\neigenpal workflow step-type list\n\n# Filter by keyword\neigenpal workflow step-type list --search extract\n\n# Full JSON Schema for one type's `config` + `output` + behavioral docs\neigenpal workflow step-type get ai.extract\n```\n\nThe output of `step-type get` is the **authoritative source** for which\nfields each step takes, what shapes they accept, and what behavior they\nimplement at runtime. Server-side validation errors point you here.\n\n## Categories (high-level map)\n\n- `ai.*` — model-backed processing (parse, extract, classify). Cost + latency depend on the model.\n- `transform.*` — deterministic data transforms (set, remove, combine, split, merge,\n script, template, pdf-embed, xlsx-to-json, json-to-xlsx). WASM sandboxed where applicable.\n- `action.*` — external side effects (HTTP, invoke another workflow, website reader).\n- `control.*` — flow control (if, foreach, parallel, parallel_map, wait, human_review, fail).\n\nThe full per-type catalog with field tables is auto-generated below from\n`STEP_SCHEMAS`. The high-level map above tells you which family you want;\nthe catalog tells you what fields it takes.\n\n## When to reach for what\n\n| Use case | Step |\n| --------------------------------- | ------------------------------------------------- |\n| Read a PDF / DOCX / image | `ai.parse-v2` with defaults (automatic native/OCR/vision) |\n| Restrict document reading | `ai.parse-v2` with `policy.native` and `policy.imageReading.order` |\n| Pull a typed object from text | `ai.extract` with `config.schema` |\n| Pick one label from a fixed set | `ai.classify` with `config.labels` |\n| Reject bad inputs with a 4xx code | `control.fail` (often after `ai.classify`) |\n| Pause for human field review | `control.human_review` (top-level only; see below) |\n| Sum / filter / regex | `transform.script` (NOT Liquid) |\n| Render a DOCX or XLSX template (YAML workflow) | `transform.template` with `tmpl_...` or `./file.xlsx` |\n| Fill a DOCX or XLSX template (runtime agent) | fill-template platform skill |\n| Convert XLSX to JSON | `transform.xlsx-to-json` |\n| Convert JSON rows to XLSX | `transform.json-to-xlsx` |\n| Merge or combine objects | `transform.combine` / `transform.merge` |\n| Conditional execution | `if:` on the step (Liquid) or `control.if` |\n| Map over an input array | `forEach:` on the step or `control.foreach` |\n| Concurrent map over an array | `control.parallel_map` |\n| Independent parallel branches | `control.parallel` |\n| External HTTP call | `action.http` |\n| Call another workflow | `action.invoke-workflow` |\n| Fetch a webpage as markdown | `action.website-reader` |\n\n## Workspace vs Git templates\n\nTwo separate template systems share DOCX/XLSX placeholder syntax but not\nreferences:\n\n| Goal | Mechanism |\n| --- | --- |\n| YAML workflow produces a filled DOCX/XLSX | `transform.template` with `templateId: tmpl_...` or `template: ./templates/foo.xlsx` (CLI push uploads) |\n| Runtime agent produces a filled DOCX/XLSX | fill-template platform skill against Git templates |\n\nGit templates (`agents/<agent>/templates/<slug>/`, shared\n`resources/templates/<slug>/`) never receive a `tmpl_...` ID and cannot be\nused in `transform.template`. Manage Git templates through the agent source\nloop — see the eigenpal skill's **Agent templates (Git source)** section.\n\nWorkspace templates are tenant-scoped `tmpl_...` resources with immutable\n`tmpr_...` revisions. Manage them from the CLI (preferred) or Studio:\n\n```bash\neigenpal workflow templates upload ./templates/roster.xlsx --json\neigenpal workflow templates list --json\neigenpal workflow templates get tmpl_... --json\neigenpal workflow templates smoke ./templates/roster.xlsx --data ./fixture.json --out ./filled.xlsx\neigenpal workflow validate ./workflow.yaml --online\neigenpal workflow push --file workflow.yaml\n```\n\nAuthor YAML with either a live id or a source-controlled path. Push uploads\nthe file (skipped when the SHA-256 still matches) and sends `templateId` +\ncurrent `templateRevisionId` to the server without rewriting the file on disk.\n\n`templateId` must be `tmpl_...` when not using a local path; file IDs\n(`file_...`) are rejected at validate/push.\n\nIn the Office file itself use `{placeholder}` and, for XLSX row expansion,\n`{table:array.prop}`. `{{placeholder}}` is Liquid for YAML `data` mapping\nonly — putting it in an XLSX file fails at fill. Example prototype row:\n\n```yaml\n- name: fill-roster\n type: transform.template\n with:\n templateId: tmpl_...\n data:\n report_title: \"{{ steps.extract.output.title }}\"\n subjects: \"{{ steps.extract.output.subjects }}\"\n```\n\nSpreadsheet cells: `{report_title}`, `{table:subjects.first_name}`,\n`{table:subjects.last_name}`. Null/blank cells stay empty; numbers and\nbooleans keep spreadsheet types; every sheet is filled; existing formulas\nstay formulas.\n\n## Liquid vs `transform.script`\n\n| Logic shape | Use |\n| -------------------------- | -------------------------------- |\n| `steps.x.output.field` | Liquid `{{ ... }}` |\n| `value \\| default: 0` | Liquid |\n| `price \\| times: quantity` | Liquid |\n| array `reduce` / `filter` | `transform.script` |\n| multi-step calc | `transform.script` |\n| conditional branches | `transform.script` or `if:` |\n| date arithmetic | `transform.script` |\n| regex | `transform.script` |\n\n`transform.script` advantages over Liquid:\n\n- Explicit `inputs:` declaration; the validator knows the data deps\n- Typed return annotation drives downstream autocomplete + runtime validation\n- Real JS/TS (`Array.prototype.reduce`, `JSON.parse`, etc.)\n- Sandbox limits prevent infinite loops from blowing up an execution\n\n> The function is **TypeScript**. Each `inputs:` key becomes a parameter\n> in declaration order: `inputs: { items, taxRate }` ⇒\n> `function script(items: ..., taxRate: ...): R { ... }`. The return-type\n> annotation `R` is **required** and IS this step's output schema; there\n> is no separate `outputSchema:` field. Describe what your function\n> actually returns: downstream steps reference its fields via\n> `{{ steps.<this>.output.<field> }}`, so a too-loose annotation (e.g.\n> `unknown`) makes those references unresolvable. The function must\n> `return` (or `throw`) a value.\n\n## Reference / output paths\n\nAfter a step runs, its output is reachable via\n`{{ steps.<name>.output.<field> }}`. The exact field set per type comes\nfrom `step-type get`'s `outputSchema`. Example for `ai.extract`:\n\n```bash\n$ eigenpal workflow step-type get ai.extract | jq '.outputSchema'\n{\n \"type\": \"object\",\n \"properties\": {\n \"extracted\": { /* matches the user-supplied config.schema */ },\n \"rawResponse\": { \"type\": \"string\" },\n \"tokensUsed\": { \"type\": \"number\" }\n }\n}\n```\n\nReference user-supplied schema fields the same way:\n`{{ steps.extract.output.extracted.invoiceNumber }}`.\n\n## Human review — top-level gate only\n\n`control.human_review` pauses the run until a reviewer confirms or corrects\nselected scalar fields, then resumes with the reviewed object or array. Place\nit as a **top-level sequential step** only — nested placement inside\n`control.if`, `control.foreach`, `control.parallel`, `control.parallel_map`, or\n`control.switch` is rejected at publish time.\n\nConfig lives in `step.with` (unlike most other `control.*` steps). Wire data\nfrom an upstream extract or transform, choose a selection mode, and attach run\nfiles for context:\n\n```yaml\n- name: review-invoice\n type: control.human_review\n with:\n data: '{{ steps.extract.output }}'\n metadataFrom: ai.extract\n instructions: Confirm vendor and total before posting.\n selection:\n mode: confidence\n threshold: medium\n missingConfidence: review\n fields:\n /vendor:\n review: always\n /total:\n threshold: high\n fieldMetadata:\n /vendor:\n label: Vendor name\n /total:\n label: Invoice total\n files:\n includeRunInputs: true\n attachments:\n - '{{ steps.render.output.files[0] }}'\n```\n\nWhen `metadataFrom: ai.extract` is set and `data` is the whole extract output\n(`{{ steps.<name>.output }}`), the step strips the reserved `_grounding` key,\nderives categorical confidence (`low`, `medium`, `high`) per field, and reuses\nthe extract schema when `schema` is omitted.\n\n**Selection:** three modes — `confidence` (review fields below threshold),\n`explicit` (review matched include/exclude paths), and `all` (every scalar\nleaf). Thresholds accept numeric `0`–`1` or categorical `low|medium|high`;\nequality auto-approves. Per-path overrides live under `selection.fields` with\n`review: always|never|skip` and optional per-field `threshold`. Prefer\n`selection.fields` over the legacy `fieldMetadata.review`.\n\n**Output:** the complete reviewed data in the same shape as `data`. Reference\ndownstream fields directly: `{{ steps.review-invoice.output.vendor }}`.\n\n**Evaluations:** evaluation runs always simulate review and never pause the\nrun. Use `meta.json` `review` fixtures to assert routing, reasons, and\nsimulated reviewer edits — see `reference/dataset-format.md`. Empty selection\ncontinues immediately without creating a task.\n\n**Limits:** 2 MiB review JSON, 10k scalar leaves, 1 MiB metadata, 2k required\nfields, 100 attachments.\n\nUse `eigenpal workflow step-type get control.human_review` for the full schema.\n\n## Control containers — nested step shape and scoping\n\n`control.parallel`, `control.parallel_map`, `control.foreach`, `control.if`,\nand inline `action.invoke-workflow` (`execution: inline`) contain nested steps. The auto-generated catalog below\ncannot render that shape, so the YAML form lives here. Same for the scoping\nrules — important because the runtime treats nested steps differently from\ntop-level ones, and getting the access path wrong silently returns\n`undefined` (no error).\n\n### `control.parallel` — independent branches\n\nRuns each branch concurrently. Use when several pieces of work share input\nbut do not depend on each other.\n\n```yaml\n- name: enrich\n type: control.parallel\n branches:\n - name: legal\n steps:\n - name: extract-clauses\n type: ai.extract\n with:\n input: '{{ steps.parse.output.markdown }}'\n schema: { clauses: { type: array, items: { type: string } } }\n - name: financial\n steps:\n - name: extract-totals\n type: ai.extract\n with:\n input: '{{ steps.parse.output.markdown }}'\n schema: { total: { type: number } }\n```\n\n**Access the output:** branch step outputs are stored under the parent\nparallel step keyed by branch name, then by inner step name. There is no\nflat top-level entry for branch-internal steps.\n\n```liquid\n{{ steps.enrich.output.legal.extract-clauses.clauses }}\n{{ steps.enrich.output.financial.extract-totals.total }}\n```\n\n**Scope inside a branch:** top-level steps that ran before the parallel,\nplus earlier siblings in the same branch. **Other branches' steps are\nNOT visible** — each branch runs in an isolated child scope.\n\n```liquid\n# Inside branch `legal`, second step:\n{{ steps.parse.output.markdown }} # ancestor: visible\n{{ steps.extract-clauses.output.clauses }} # sibling: visible\n{{ steps.extract-totals.output.total }} # other branch: UNDEFINED\n```\n\n### `control.parallel_map` — fan-out over an array\n\nRuns the inner step block concurrently for each item, up to `concurrency`.\n\n```yaml\n- name: process-pages\n type: control.parallel_map\n items: '{{ steps.split.output.pages }}'\n as: page\n indexAs: i # optional\n concurrency: 5 # default 5, max 50\n steps:\n - name: extract-fields\n type: ai.extract\n with:\n input: '{{ page.text }}'\n schema: { fields: { type: object } }\n```\n\n**Access the output:** iteration results are returned as an array in the\noriginal input order under the parent step's `items` field.\n\n```liquid\n{{ steps.process-pages.output.items[0].extract-fields.fields }}\n{{ steps.process-pages.output.count }} # number of completed iterations\n{{ steps.process-pages.output.totalIterations }}\n```\n\n`steps.extract-fields.output.fields` (the flat form) is **not** addressable\nfrom outside the parallel_map.\n\n**Multi-step iterations only key the LAST step's output into `items[i]`.**\nIf your iteration body has steps `[parse, extract]`, each `items[i]` is\n`{ extract: <extract output> }` — `parse`'s output is gone. To preserve\nintermediate fields, end the body with a `transform.script` that returns\nthe combined shape:\n\n```yaml\nsteps:\n - name: parse\n type: ai.parse-v2\n with: { ... }\n - name: extract\n type: ai.extract\n with: { input: '{{ steps.parse.output.markdown }}', ... }\n - name: combine\n type: transform.script\n with:\n inputs:\n parsed: '{{ steps.parse.output }}'\n extracted: '{{ steps.extract.output }}'\n function: |\n function script(parsed, extracted): { parsed: any; extracted: any } {\n return { parsed, extracted };\n }\n```\n\nNow `items[i].combine.parsed` / `items[i].combine.extracted` both survive.\n\n### `control.foreach` — sequential loop over an array\n\nSame shape as `parallel_map` minus `concurrency`; iterations run in order.\nUse when each iteration depends on the previous, or when concurrency would\ncause downstream rate limits.\n\n```yaml\n- name: per-row\n type: control.foreach\n items: '{{ steps.fetch.output.rows }}'\n as: row\n steps:\n - name: persist\n type: action.http-request\n with:\n method: POST\n url: 'https://example.com/api/rows/{{ row.id }}'\n body: '{{ row }}'\n```\n\n**Access the output:** same shape as parallel_map — an `items[]` array of\nper-iteration results, in iteration order. Same \"only the LAST inner step\nis keyed into `items[i]`\" rule applies (use a trailing `transform.script`\nto preserve intermediate outputs).\n\n> ⚠️ Foreach does NOT isolate scopes — the last iteration's inner step\n> outputs technically persist on the top-level `steps` map and `steps.<inner>.output.x`\n> resolves at runtime. That is an only-the-last-row hazard; the autocomplete\n> hides these names and you should treat `steps.<foreach>.output.items[]`\n> as the only correct access.\n\n### `control.if` — conditional branch\n\n```yaml\n- name: route\n type: control.if\n condition: '{{ input.priority == \"high\" }}'\n then:\n - name: rush-extract\n type: ai.extract\n with: { ... }\n else:\n - name: normal-extract\n type: ai.extract\n with: { ... }\n```\n\n**Access the output:** the `if` step's output is\n\n```ts\n{\n condition: boolean, // evaluated condition\n branch: 'then' | 'else', // which branch ran\n result: <last inner step's output> | null // null when chosen branch is empty\n}\n```\n\nThe canonical way to consume the result is through the if step itself:\n\n```liquid\n{{ steps.route.output.branch }} # \"then\" or \"else\"\n{{ steps.route.output.result.foo }} # field from the branch's last step\n```\n\n`steps.<innerName>.output` references from outside the `if` also resolve\nat runtime (unlike `parallel`/`parallel_map`, `if` does not isolate\nscopes), but the template breaks the moment the OTHER branch runs. Use\n`steps.<if>.output.result` so the access is branch-agnostic — or compute\nthe final shape in a trailing `transform.script` that handles both cases.\n\n### `action.invoke-workflow` (inline) — call another workflow in the same run\n\n```yaml\n- name: invoice-flow\n type: action.invoke-workflow\n with:\n workflow: parse-invoice # target workflow name or wf_ id\n execution: inline # default; omit for same-run execution\n input:\n contract: '{{ input.contract }}'\n```\n\n**Access the output:** the target's declared output fields are exposed as\ntop-level keys under `steps.<this-step>.output`, with a `files` array alongside.\nInvoked workflow steps run in an isolated scope inside the parent run.\n\nFor a separate child run with lineage, set `execution: child`. Waiting for the\nchild releases worker capacity and resumes automatically when the child finishes.\nSet `wait: false` for fire-and-forget execution.\n\n## Classify-and-fail pattern\n\n`ai.classify` + `control.fail` together let a workflow reject bad inputs\nfast with a typed HTTP-style status code that callers (and evals) can\nmatch against. The classifier picks one label from a closed set; the\nfail step terminates the run when the label is one you do not want to\nprocess.\n\n```yaml\n- name: parse\n type: ai.parse-v2\n with:\n input: '{{ input.document }}'\n\n- name: classify\n type: ai.classify\n with:\n input: '{{ steps.parse.output.text }}'\n labels:\n - name: invoice\n description: A vendor invoice with line items and totals.\n - name: contract\n description: A multi-page contract or agreement.\n - name: other\n description: Anything that is not an invoice or contract.\n\n- name: reject-unsupported\n type: control.fail\n condition: '{{ steps.classify.output.label == \"other\" }}'\n statusCode: 422\n message: 'Unsupported document: {{ steps.classify.output.reason }}'\n```\n\n> `control.fail` config is step-level (no `with:`), matching every other\n> `control.*` step. `condition`, `statusCode`, and `message` sit directly\n> on the step node.\n\nThe synchronous run endpoint surfaces the `statusCode` as the HTTP\nresponse status; async runs persist `{ code, message, step }` to\n`executions.error` so the eval scorer can match against\n`expected.json` with `$error` (see `reference/dataset-format.md`). When\n`condition` is omitted, `control.fail` always fails when reached, so\ncompose with `control.if` for legacy gating.\n\n<!-- GENERATED:STEP_CATALOG START -->\n## Full catalog\n\n_Generated from `STEP_SCHEMAS` in `@eigenpal/types/src/workflow/step-configs.ts`. Do not hand-edit between the GENERATED fences — run `bun run --cwd packages/cli generate:skill`._\n\n### AI steps — model-backed processing\n\n#### `ai.parse-v2` — Parse Document\n\nAutomatically read native, scanned, and mixed documents with capability-aware OCR/vision fallback and explicit completeness.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/parse-v2`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `policy` | object | yes | | |\n| `providers` | object | yes | | |\n| `output` | object | yes | | |\n| `enrichment` | object | yes | | |\n| `advanced` | object | yes | | |\n| `input` | string | yes | | File reference or template expression for the document |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `document` | object | yes | | |\n| `usage` | object | yes | | |\n| `pages` | array<object> | yes | | |\n| `text` | string | yes | | Combined text from all pages |\n| `parserType` | `\"plaintext\"` \\| `\"office\"` \\| `\"llm-vision\"` \\| `\"ocr\"` | yes | | |\n| `parserVersion` | `\"2\"` | yes | | |\n| `model` | string | no | | Model used (for LLM/OCR parsers) |\n| `processingStrategy` | `\"native\"` \\| `\"ocr\"` \\| `\"vision\"` \\| `\"hybrid\"` | no | | How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages). |\n| `structured` | record<string, unknown> | no | | Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser |\n| `completeness` | object | yes | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"policy\": {\n \"type\": \"object\",\n \"properties\": {\n \"native\": {\n \"default\": \"prefer\",\n \"description\": \"Prefer local text extraction, require local text extraction with no image transcription, or skip native PDF extraction. Figure enrichment is independent.\",\n \"type\": \"string\",\n \"enum\": [\n \"prefer\",\n \"require\",\n \"skip\"\n ]\n },\n \"imageReading\": {\n \"type\": \"object\",\n \"properties\": {\n \"order\": {\n \"default\": [\n \"ocr\",\n \"vision\"\n ],\n \"description\": \"Ordered allowed backends. A single entry prohibits the other backend.\",\n \"minItems\": 1,\n \"maxItems\": 2,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"ocr\",\n \"vision\"\n ]\n }\n }\n },\n \"required\": [\n \"order\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"native\",\n \"imageReading\"\n ],\n \"additionalProperties\": false\n },\n \"providers\": {\n \"type\": \"object\",\n \"properties\": {\n \"ocr\": {\n \"description\": \"Exact configured OCR provider ID. Missing pins fail; they never resolve to another provider.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"vision\": {\n \"description\": \"Exact configured vision provider ID. Otherwise uses the deployment parsing default or vision role.\",\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"output\": {\n \"type\": \"object\",\n \"properties\": {\n \"textFormat\": {\n \"default\": \"markdown\",\n \"type\": \"string\",\n \"enum\": [\n \"plain\",\n \"markdown\",\n \"html\",\n \"djot\"\n ]\n },\n \"includeCellMetadata\": {\n \"default\": false,\n \"description\": \"Include spreadsheet cell evidence in pages[].spreadsheet and annotate text for downstream extraction. Preserves raw/displayed values and workbook date system.\",\n \"type\": \"boolean\"\n },\n \"nativeWhitespace\": {\n \"default\": \"reading-order\",\n \"description\": \"Spatial preserves native PDF column spacing. It does not promise OCR/vision coordinates.\",\n \"type\": \"string\",\n \"enum\": [\n \"reading-order\",\n \"spatial\"\n ]\n },\n \"require\": {\n \"default\": [],\n \"description\": \"Required evidence capabilities on nonblank pages. Backends unable to satisfy them are rejected.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"wordCoordinates\",\n \"tables\"\n ]\n }\n }\n },\n \"required\": [\n \"textFormat\",\n \"includeCellMetadata\",\n \"nativeWhitespace\",\n \"require\"\n ],\n \"additionalProperties\": false\n },\n \"enrichment\": {\n \"type\": \"object\",\n \"properties\": {\n \"figures\": {\n \"type\": \"object\",\n \"properties\": {\n \"enabled\": {\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"instructions\": {\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n }\n },\n \"required\": [\n \"enabled\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"figures\"\n ],\n \"additionalProperties\": false\n },\n \"advanced\": {\n \"type\": \"object\",\n \"properties\": {\n \"vision\": {\n \"type\": \"object\",\n \"properties\": {\n \"maxConcurrency\": {\n \"default\": 3,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 10\n },\n \"pagesPerBatch\": {\n \"default\": 5,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 20\n },\n \"renderScale\": {\n \"default\": 2,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"instructions\": {\n \"description\": \"Transcription instructions, never document-specific extraction/schema instructions.\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n }\n },\n \"required\": [\n \"maxConcurrency\",\n \"pagesPerBatch\",\n \"renderScale\",\n \"imageQuality\"\n ],\n \"additionalProperties\": false\n },\n \"languages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"allowPartial\": {\n \"default\": false,\n \"description\": \"Return unresolved pages explicitly instead of failing. Default false.\",\n \"type\": \"boolean\"\n },\n \"cache\": {\n \"default\": false,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"vision\",\n \"allowPartial\",\n \"cache\"\n ],\n \"additionalProperties\": false\n },\n \"input\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File reference or template expression for the document\"\n }\n },\n \"required\": [\n \"policy\",\n \"providers\",\n \"output\",\n \"enrichment\",\n \"advanced\",\n \"input\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"document\": {\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"type\": \"string\"\n },\n \"mimeType\": {\n \"type\": \"string\"\n },\n \"size\": {\n \"type\": \"number\",\n \"description\": \"File size in bytes\"\n },\n \"storageRef\": {\n \"description\": \"Storage reference for the original file\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n },\n \"usage\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageCount\": {\n \"type\": \"number\"\n },\n \"processingTimeMs\": {\n \"type\": \"number\"\n },\n \"ocrPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPromptTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionCompletionTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"cached\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"pageCount\",\n \"visionPagesProcessed\"\n ],\n \"additionalProperties\": false\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"spreadsheet\": {\n \"description\": \"Opt-in original spreadsheet cell evidence\",\n \"type\": \"object\",\n \"properties\": {\n \"dateSystem\": {\n \"type\": \"string\",\n \"enum\": [\n \"1900\",\n \"1904\"\n ]\n },\n \"declaredRange\": {\n \"type\": \"string\"\n },\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\",\n \"description\": \"Original A1 cell address\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Excel storage type: n=number, s=string, b=boolean, e=error, d=date, z=blank. A numeric date remains type n.\"\n },\n \"rawValue\": {\n \"description\": \"Stored cached value; formulas are never evaluated\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"displayedValue\": {\n \"type\": \"string\",\n \"description\": \"Value formatted using the workbook number format and date system\"\n },\n \"numberFormat\": {\n \"type\": \"string\"\n },\n \"formula\": {\n \"type\": \"string\"\n },\n \"dateValue\": {\n \"description\": \"Calendar rendering for a valid date-formatted serial, without a timezone. Evidence of Excel formatting, not a business classification.\",\n \"type\": \"string\"\n },\n \"excelLeapDay\": {\n \"description\": \"True for the fictitious 1900-02-29 in the Excel 1900 date system\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"address\",\n \"type\",\n \"displayedValue\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"dateSystem\",\n \"cells\"\n ],\n \"additionalProperties\": false\n },\n \"pageIndex\": {\n \"type\": \"number\",\n \"description\": \"0-based page index\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Extracted page text (markdown/HTML/plain, or spatial layout text)\"\n },\n \"pageName\": {\n \"description\": \"Page/sheet name (e.g., Excel sheet name)\",\n \"type\": \"string\"\n },\n \"layoutElements\": {\n \"description\": \"Semantic layout elements in reading order\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"paragraph\",\n \"title\",\n \"sectionHeading\",\n \"pageHeader\",\n \"pageFooter\",\n \"pageNumber\",\n \"footnote\",\n \"table\",\n \"figure\",\n \"formulaBlock\"\n ]\n },\n \"content\": {\n \"type\": \"string\"\n },\n \"table\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n },\n \"caption\": {\n \"type\": \"string\"\n },\n \"figureId\": {\n \"type\": \"string\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"type\",\n \"content\"\n ],\n \"additionalProperties\": false\n }\n },\n \"words\": {\n \"description\": \"Word-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"lines\": {\n \"description\": \"Line-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"tables\": {\n \"description\": \"Extracted tables\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n }\n },\n \"width\": {\n \"description\": \"Page width\",\n \"type\": \"number\"\n },\n \"height\": {\n \"description\": \"Page height\",\n \"type\": \"number\"\n },\n \"unit\": {\n \"description\": \"Unit for width/height and bounding regions\",\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"confidence\": {\n \"description\": \"Overall page confidence\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"nativeTextQuality\": {\n \"description\": \"Per-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness — valid-looking wrong mappings and literal \\\"?\\\" cannot be distinguished from legitimate text.\",\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"clean\",\n \"empty\",\n \"suspect\"\n ]\n },\n \"reasons\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"empty\",\n \"replacement-character\",\n \"lone-surrogate\",\n \"forbidden-control\",\n \"unassigned\",\n \"noncharacter\",\n \"private-use\"\n ]\n }\n },\n \"counts\": {\n \"type\": \"object\",\n \"properties\": {\n \"codePoints\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"nonWhitespace\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"replacement\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"loneSurrogate\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"forbiddenControl\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"unassigned\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"noncharacter\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"privateUse\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"codePoints\",\n \"nonWhitespace\",\n \"replacement\",\n \"loneSurrogate\",\n \"forbiddenControl\",\n \"unassigned\",\n \"noncharacter\",\n \"privateUse\"\n ],\n \"additionalProperties\": false\n },\n \"profile\": {\n \"type\": \"object\",\n \"properties\": {\n \"replacementRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"loneSurrogateRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"forbiddenControlRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"unassignedRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"noncharacterRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"privateUseRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n }\n },\n \"required\": [\n \"replacementRatio\",\n \"loneSurrogateRatio\",\n \"forbiddenControlRatio\",\n \"unassignedRatio\",\n \"noncharacterRatio\",\n \"privateUseRatio\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"status\",\n \"reasons\",\n \"counts\",\n \"profile\"\n ],\n \"additionalProperties\": false\n },\n \"provenance\": {\n \"type\": \"object\",\n \"properties\": {\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\"\n ]\n },\n \"provider\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"reason\": {\n \"type\": \"string\"\n },\n \"textFormat\": {\n \"type\": \"string\",\n \"enum\": [\n \"plain\",\n \"markdown\",\n \"html\",\n \"djot\"\n ]\n },\n \"capabilities\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"wordCoordinates\",\n \"tables\"\n ]\n }\n }\n },\n \"required\": [\n \"source\",\n \"reason\",\n \"textFormat\",\n \"capabilities\"\n ],\n \"additionalProperties\": false\n },\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"complete\",\n \"blank\",\n \"no-text\",\n \"unresolved\"\n ]\n },\n \"warnings\": {\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"provenance\",\n \"status\",\n \"warnings\"\n ],\n \"additionalProperties\": false\n }\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Combined text from all pages\"\n },\n \"parserType\": {\n \"type\": \"string\",\n \"enum\": [\n \"plaintext\",\n \"office\",\n \"llm-vision\",\n \"ocr\"\n ]\n },\n \"parserVersion\": {\n \"type\": \"string\",\n \"const\": \"2\"\n },\n \"model\": {\n \"description\": \"Model used (for LLM/OCR parsers)\",\n \"type\": \"string\"\n },\n \"processingStrategy\": {\n \"description\": \"How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\",\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\",\n \"hybrid\"\n ]\n },\n \"structured\": {\n \"description\": \"Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"completeness\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"complete\",\n \"partial\"\n ]\n },\n \"unresolvedPageIndexes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n }\n },\n \"required\": [\n \"status\",\n \"unresolvedPageIndexes\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"document\",\n \"usage\",\n \"pages\",\n \"text\",\n \"parserType\",\n \"parserVersion\",\n \"completeness\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.parse` — Parse Document v1\n\nParse Document v1, the retired parser, kept only so existing workflows run unchanged. Do not add it to workflows: use ai.parse-v2 (Parse Document), which picks native text, OCR or vision per page.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/parse`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Storage reference or template expression for the document |\n| `parseMode` | `\"ocr\"` \\| `\"vision\"` \\| `\"native\"` \\| `\"native-or-ocr\"` | no | | Base parser for PDF/image inputs. OCR is the default; vision uses the selected LLM. `native` extracts PDF embedded text only and never calls OCR or vision. `native-or-ocr` extracts native text, runs page-quality diagnostics, and requests OCR when pages have detectable anomalies (empty, U+FFFD, lone surrogates, forbidden controls, unassigned/noncharacter, heavy PUA). Page selection, subset egress, and billing are provider-dependent. Valid-looking wrong text and literal \"?\" are not flagged. Text and Office files always use local parsing. |\n| `ocrModel` | string | no | | OCR provider ID for PDF/image parsing |\n| `llmModel` | string | no | | LLM provider ID for vision-based parsing |\n| `llmReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `figureModel` | string | no | | Vision model used only for the optional figure-description pass |\n| `figureReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxConcurrency` | number | no | `3` | Max concurrent VLM batch requests |\n| `pagesPerBatch` | number | no | `5` | Number of page images per VLM request |\n| `pdfRenderScale` | number | no | `1` | Scale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes. |\n| `imageQuality` | integer | no | `85` | JPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes. |\n| `prompt` | string | no | | Custom extraction prompt |\n| `languages` | array<string> | no | | OCR language hints |\n| `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`. |\n| `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. |\n| `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. |\n| `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. |\n| `cache` | boolean | no | `false` | When true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `document` | object | yes | | |\n| `usage` | object | yes | | |\n| `pages` | array<object> | yes | | |\n| `text` | string | yes | | Combined text from all pages |\n| `parserType` | `\"plaintext\"` \\| `\"office\"` \\| `\"llm-vision\"` \\| `\"ocr\"` | yes | | |\n| `parserVersion` | string | no | | |\n| `model` | string | no | | Model used (for LLM/OCR parsers) |\n| `processingStrategy` | `\"native\"` \\| `\"ocr\"` \\| `\"vision\"` \\| `\"hybrid\"` | no | | How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages). |\n| `structured` | record<string, unknown> | no | | Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Storage reference or template expression for the document\"\n },\n \"parseMode\": {\n \"description\": \"Base parser for PDF/image inputs. OCR is the default; vision uses the selected LLM. `native` extracts PDF embedded text only and never calls OCR or vision. `native-or-ocr` extracts native text, runs page-quality diagnostics, and requests OCR when pages have detectable anomalies (empty, U+FFFD, lone surrogates, forbidden controls, unassigned/noncharacter, heavy PUA). Page selection, subset egress, and billing are provider-dependent. Valid-looking wrong text and literal \\\"?\\\" are not flagged. Text and Office files always use local parsing.\",\n \"type\": \"string\",\n \"enum\": [\n \"ocr\",\n \"vision\",\n \"native\",\n \"native-or-ocr\"\n ]\n },\n \"ocrModel\": {\n \"description\": \"OCR provider ID for PDF/image parsing\",\n \"type\": \"string\"\n },\n \"llmModel\": {\n \"description\": \"LLM provider ID for vision-based parsing\",\n \"type\": \"string\"\n },\n \"llmReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"figureModel\": {\n \"description\": \"Vision model used only for the optional figure-description pass\",\n \"type\": \"string\"\n },\n \"figureReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxConcurrency\": {\n \"description\": \"Max concurrent VLM batch requests\",\n \"default\": 3,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 10\n },\n \"pagesPerBatch\": {\n \"description\": \"Number of page images per VLM request\",\n \"default\": 5,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 20\n },\n \"pdfRenderScale\": {\n \"description\": \"Scale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes.\",\n \"default\": 1,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes.\",\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"prompt\": {\n \"description\": \"Custom extraction prompt\",\n \"type\": \"string\"\n },\n \"languages\": {\n \"description\": \"OCR language hints\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"outputFormat\": {\n \"description\": \"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`.\",\n \"default\": \"markdown\",\n \"type\": \"string\",\n \"enum\": [\n \"plain\",\n \"markdown\",\n \"djot\",\n \"html\",\n \"layout\"\n ]\n },\n \"nativeText\": {\n \"description\": \"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.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"describeFigures\": {\n \"description\": \"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.\",\n \"type\": \"boolean\"\n },\n \"figureInstructions\": {\n \"description\": \"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.\",\n \"type\": \"string\"\n },\n \"cache\": {\n \"description\": \"When true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off.\",\n \"default\": false,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"input\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"document\": {\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"type\": \"string\"\n },\n \"mimeType\": {\n \"type\": \"string\"\n },\n \"size\": {\n \"type\": \"number\",\n \"description\": \"File size in bytes\"\n },\n \"storageRef\": {\n \"description\": \"Storage reference for the original file\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n },\n \"usage\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageCount\": {\n \"type\": \"number\"\n },\n \"processingTimeMs\": {\n \"type\": \"number\"\n },\n \"ocrPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPromptTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionCompletionTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"cached\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"pageCount\"\n ],\n \"additionalProperties\": false\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"spreadsheet\": {\n \"description\": \"Opt-in original spreadsheet cell evidence\",\n \"type\": \"object\",\n \"properties\": {\n \"dateSystem\": {\n \"type\": \"string\",\n \"enum\": [\n \"1900\",\n \"1904\"\n ]\n },\n \"declaredRange\": {\n \"type\": \"string\"\n },\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\",\n \"description\": \"Original A1 cell address\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Excel storage type: n=number, s=string, b=boolean, e=error, d=date, z=blank. A numeric date remains type n.\"\n },\n \"rawValue\": {\n \"description\": \"Stored cached value; formulas are never evaluated\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"displayedValue\": {\n \"type\": \"string\",\n \"description\": \"Value formatted using the workbook number format and date system\"\n },\n \"numberFormat\": {\n \"type\": \"string\"\n },\n \"formula\": {\n \"type\": \"string\"\n },\n \"dateValue\": {\n \"description\": \"Calendar rendering for a valid date-formatted serial, without a timezone. Evidence of Excel formatting, not a business classification.\",\n \"type\": \"string\"\n },\n \"excelLeapDay\": {\n \"description\": \"True for the fictitious 1900-02-29 in the Excel 1900 date system\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"address\",\n \"type\",\n \"displayedValue\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"dateSystem\",\n \"cells\"\n ],\n \"additionalProperties\": false\n },\n \"pageIndex\": {\n \"type\": \"number\",\n \"description\": \"0-based page index\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Extracted page text (markdown/HTML/plain, or spatial layout text)\"\n },\n \"pageName\": {\n \"description\": \"Page/sheet name (e.g., Excel sheet name)\",\n \"type\": \"string\"\n },\n \"layoutElements\": {\n \"description\": \"Semantic layout elements in reading order\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"paragraph\",\n \"title\",\n \"sectionHeading\",\n \"pageHeader\",\n \"pageFooter\",\n \"pageNumber\",\n \"footnote\",\n \"table\",\n \"figure\",\n \"formulaBlock\"\n ]\n },\n \"content\": {\n \"type\": \"string\"\n },\n \"table\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n },\n \"caption\": {\n \"type\": \"string\"\n },\n \"figureId\": {\n \"type\": \"string\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"type\",\n \"content\"\n ],\n \"additionalProperties\": false\n }\n },\n \"words\": {\n \"description\": \"Word-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"lines\": {\n \"description\": \"Line-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"tables\": {\n \"description\": \"Extracted tables\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n }\n },\n \"width\": {\n \"description\": \"Page width\",\n \"type\": \"number\"\n },\n \"height\": {\n \"description\": \"Page height\",\n \"type\": \"number\"\n },\n \"unit\": {\n \"description\": \"Unit for width/height and bounding regions\",\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"confidence\": {\n \"description\": \"Overall page confidence\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"nativeTextQuality\": {\n \"description\": \"Per-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness — valid-looking wrong mappings and literal \\\"?\\\" cannot be distinguished from legitimate text.\",\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"clean\",\n \"empty\",\n \"suspect\"\n ]\n },\n \"reasons\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"empty\",\n \"replacement-character\",\n \"lone-surrogate\",\n \"forbidden-control\",\n \"unassigned\",\n \"noncharacter\",\n \"private-use\"\n ]\n }\n },\n \"counts\": {\n \"type\": \"object\",\n \"properties\": {\n \"codePoints\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"nonWhitespace\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"replacement\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"loneSurrogate\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"forbiddenControl\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"unassigned\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"noncharacter\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"privateUse\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"codePoints\",\n \"nonWhitespace\",\n \"replacement\",\n \"loneSurrogate\",\n \"forbiddenControl\",\n \"unassigned\",\n \"noncharacter\",\n \"privateUse\"\n ],\n \"additionalProperties\": false\n },\n \"profile\": {\n \"type\": \"object\",\n \"properties\": {\n \"replacementRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"loneSurrogateRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"forbiddenControlRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"unassignedRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"noncharacterRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"privateUseRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n }\n },\n \"required\": [\n \"replacementRatio\",\n \"loneSurrogateRatio\",\n \"forbiddenControlRatio\",\n \"unassignedRatio\",\n \"noncharacterRatio\",\n \"privateUseRatio\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"status\",\n \"reasons\",\n \"counts\",\n \"profile\"\n ],\n \"additionalProperties\": false\n },\n \"provenance\": {\n \"description\": \"Which extractor produced the final text/layout on this page\",\n \"type\": \"object\",\n \"properties\": {\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\"\n ]\n }\n },\n \"required\": [\n \"source\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Combined text from all pages\"\n },\n \"parserType\": {\n \"type\": \"string\",\n \"enum\": [\n \"plaintext\",\n \"office\",\n \"llm-vision\",\n \"ocr\"\n ]\n },\n \"parserVersion\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model used (for LLM/OCR parsers)\",\n \"type\": \"string\"\n },\n \"processingStrategy\": {\n \"description\": \"How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\",\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\",\n \"hybrid\"\n ]\n },\n \"structured\": {\n \"description\": \"Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"document\",\n \"usage\",\n \"pages\",\n \"text\",\n \"parserType\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.extract` — Extract Data\n\nExtract structured data from text using AI with a JSON schema\n\n**Behavior and examples:** `eigenpal docs read steps/ai/extract`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Text content or template expression |\n| `schema` | object | yes | | JSON Schema defining the structure to extract. Fields not listed in `required` come back null when the document does not contain them; a missing required field fails the step. |\n| `prompt` | string | no | | Custom prompt template for extraction |\n| `provider` | string | no | | Provider ID (e.g., \"openai/gpt-6-luna\") |\n| `model` | string | no | | Model override |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxInputTokens` | integer | no | | Max input tokens. Truncates input text and logs a warning when exceeded. Omit for no limit. |\n| `grounded` | boolean | no | | Grounding is ON by default: each schema field gets a source span + confidence (high=verbatim, medium=fuzzy, low=ungrounded) under a reserved `_grounding` output key, and fields whose value cannot be located in the source are flagged for human review. Values stay the reliable schema-typed ones. The pass runs through the workspace LLM (any provider) and chunks long documents automatically. Tri-state: unset (default) = on, degrading gracefully to deterministic text alignment (`_grounding._degraded: true`) if no grounding model is available; `true` = strict, the step fails when the grounding model cannot be resolved; `false` = off, no `_grounding` key at all. |\n| `groundingModel` | string | no | | Provider/model for the grounding pass. Defaults to the workspace default LLM. Any configured provider works; the pass only fails the step when `grounded: true` is set explicitly and no model resolves. |\n| `groundingReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `groundingExamples` | array<object> | no | | Optional few-shot examples pinning grounding to verbatim source text per field. |\n| `reviewOn` | `\"medium_or_low\"` \\| `\"low_only\"` | no | | Which grounding confidences set needsReview on a field. Default: low_only (only fields whose value could not be located in the source). Use medium_or_low to also flag approximate and derived matches. |\n\n**Output:** `record<string, unknown>`\n\n> Extracted structured data matching the provided schema. Unless grounding is disabled (grounded: false), the output also carries a reserved `_grounding` map keyed by dotted field path: `_grounding[\"line_items.0.amount\"] = { confidence: high|medium|low, score?, needsReview, reason?, quote?, citations?, source_span }`, plus reserved `_degraded: true` / `_reason` markers when grounding could not run the shared algorithm or the Eigenpal text pass. Lineage is never included in this JSON.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Text content or template expression\"\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"const\": \"object\"\n },\n \"properties\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"required\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"type\",\n \"properties\"\n ],\n \"additionalProperties\": false,\n \"description\": \"JSON Schema defining the structure to extract. Fields not listed in `required` come back null when the document does not contain them; a missing required field fails the step.\"\n },\n \"prompt\": {\n \"description\": \"Custom prompt template for extraction\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID (e.g., \\\"openai/gpt-6-luna\\\")\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxInputTokens\": {\n \"description\": \"Max input tokens. Truncates input text and logs a warning when exceeded. Omit for no limit.\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"grounded\": {\n \"description\": \"Grounding is ON by default: each schema field gets a source span + confidence (high=verbatim, medium=fuzzy, low=ungrounded) under a reserved `_grounding` output key, and fields whose value cannot be located in the source are flagged for human review. Values stay the reliable schema-typed ones. The pass runs through the workspace LLM (any provider) and chunks long documents automatically. Tri-state: unset (default) = on, degrading gracefully to deterministic text alignment (`_grounding._degraded: true`) if no grounding model is available; `true` = strict, the step fails when the grounding model cannot be resolved; `false` = off, no `_grounding` key at all.\",\n \"type\": \"boolean\"\n },\n \"groundingModel\": {\n \"description\": \"Provider/model for the grounding pass. Defaults to the workspace default LLM. Any configured provider works; the pass only fails the step when `grounded: true` is set explicitly and no model resolves.\",\n \"type\": \"string\"\n },\n \"groundingReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"groundingExamples\": {\n \"description\": \"Optional few-shot examples pinning grounding to verbatim source text per field.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"extractions\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"field\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"field\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"text\",\n \"extractions\"\n ],\n \"additionalProperties\": false\n }\n },\n \"reviewOn\": {\n \"description\": \"Which grounding confidences set needsReview on a field. Default: low_only (only fields whose value could not be located in the source). Use medium_or_low to also flag approximate and derived matches.\",\n \"type\": \"string\",\n \"enum\": [\n \"medium_or_low\",\n \"low_only\"\n ]\n }\n },\n \"required\": [\n \"input\",\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Extracted structured data matching the provided schema. Unless grounding is disabled (grounded: false), the output also carries a reserved `_grounding` map keyed by dotted field path: `_grounding[\\\"line_items.0.amount\\\"] = { confidence: high|medium|low, score?, needsReview, reason?, quote?, citations?, source_span }`, plus reserved `_degraded: true` / `_reason` markers when grounding could not run the shared algorithm or the Eigenpal text pass. Lineage is never included in this JSON.\"\n}\n```\n\n\n#### `ai.split` — Split Document\n\nSplit a parsed document into named sections using an LLM. Consumes ai.parse output; emits per-section page ranges and text ready for downstream ai.extract via control.parallel_map.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/split`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Template expression resolving to ai.parse output, e.g. \"{{ steps.parse.output }}\" |\n| `sections` | array<object> | yes | | Named sections to find in the document |\n| `rules` | string | no | | Optional natural-language rules appended to the system prompt. E.g. \"End-of-section markers like *Koniec prílohy 2* close the current section.\" |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml (e.g. \"openai/gpt-6-luna\"). Falls back to the tenant default LLM provider when omitted. |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `windowTokenBudget` | integer | no | | Override the estimated per-window token ceiling. Oversized pages are subdivided with overlap while retaining their original page index. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. Inputs requiring more than 64 LLM windows are rejected before calls begin. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `splits` | array<object> | yes | | Sections found in the document, in page order. Absent sections are omitted. |\n| `sections` | record<string, object> | yes | | The same sections keyed by config name, so a downstream step can reference one directly: `{{ steps.<split>.output.sections.<name>.page_range }}`. Prefer this over filtering `splits`. On a duplicate name the last wins. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Template expression resolving to ai.parse output, e.g. \\\"{{ steps.parse.output }}\\\"\"\n },\n \"sections\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Stable id, used as the key in output and template references\"\n },\n \"description\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"What this section looks like in the document. Use the document's own terminology (e.g. \\\"Príloha 2 / Anlage 2\\\") and visual cues. Multilingual variants belong here.\"\n },\n \"required\": {\n \"description\": \"If true, log a warn when this section is not found, and lean the LLM toward expecting it. Default: false (sections may be absent).\",\n \"type\": \"boolean\"\n },\n \"endHints\": {\n \"description\": \"Natural-language hints fed to the LLM about what marks the END of this section (e.g. [\\\"PRÍPAD PORUŠENIA ZMLUVY\\\", \\\"*Koniec prílohy*\\\"]). The LLM uses these as guidance — not a regex match — so casing variants, missing diacritics, and multilingual phrasings all close the section correctly.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"name\",\n \"description\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Named sections to find in the document\"\n },\n \"rules\": {\n \"description\": \"Optional natural-language rules appended to the system prompt. E.g. \\\"End-of-section markers like *Koniec prílohy 2* close the current section.\\\"\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml (e.g. \\\"openai/gpt-6-luna\\\"). Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"windowTokenBudget\": {\n \"description\": \"Override the estimated per-window token ceiling. Oversized pages are subdivided with overlap while retaining their original page index. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. Inputs requiring more than 64 LLM windows are rejected before calls begin.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"sections\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"splits\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Section name from the config\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence at the anchor page. Coarse enum (low | medium | high) — numeric scores cluster meaninglessly at 0.85-0.95.\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the anchor — useful for debugging\"\n },\n \"evidence\": {\n \"description\": \"Structured start-anchor evidence — parse this instead of regexing over `notes`.\",\n \"type\": \"object\",\n \"properties\": {\n \"start_heading_text\": {\n \"description\": \"Verbatim heading text the LLM cited as the section start\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"start_page\": {\n \"description\": \"Page where start_heading_text appears\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"additionalProperties\": false\n },\n \"end_evidence\": {\n \"description\": \"Set when the LLM detected an end-of-section cue (matched against the section's `endHints` or an explicit closing marker). Absent when the section was closed by continuity-fill alone.\",\n \"type\": \"object\",\n \"properties\": {\n \"end_page\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"LAST page of the section (inclusive)\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the end. Pair with start `notes` for reconciliation.\"\n }\n },\n \"required\": [\n \"end_page\",\n \"confidence\",\n \"notes\"\n ],\n \"additionalProperties\": false\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Joined per-page content for this section, ready for downstream ai.extract\"\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"pageName\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"anchored\",\n \"inferred\"\n ],\n \"description\": \"Whether this page is direct LLM evidence (anchored) or continuity-filled (inferred)\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"source\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Raw per-page records covered by this split (in page order). Iterate when downstream needs per-page context (e.g. control.parallel_map over section pages).\"\n },\n \"pages_anchored\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages with direct LLM evidence\"\n },\n \"pages_inferred\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages assigned by deterministic continuity fill\"\n }\n },\n \"required\": [\n \"name\",\n \"page_range\",\n \"confidence\",\n \"notes\",\n \"text\",\n \"pages\",\n \"pages_anchored\",\n \"pages_inferred\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Sections found in the document, in page order. Absent sections are omitted.\"\n },\n \"sections\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Section name from the config\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence at the anchor page. Coarse enum (low | medium | high) — numeric scores cluster meaninglessly at 0.85-0.95.\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the anchor — useful for debugging\"\n },\n \"evidence\": {\n \"description\": \"Structured start-anchor evidence — parse this instead of regexing over `notes`.\",\n \"type\": \"object\",\n \"properties\": {\n \"start_heading_text\": {\n \"description\": \"Verbatim heading text the LLM cited as the section start\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"start_page\": {\n \"description\": \"Page where start_heading_text appears\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"additionalProperties\": false\n },\n \"end_evidence\": {\n \"description\": \"Set when the LLM detected an end-of-section cue (matched against the section's `endHints` or an explicit closing marker). Absent when the section was closed by continuity-fill alone.\",\n \"type\": \"object\",\n \"properties\": {\n \"end_page\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"LAST page of the section (inclusive)\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the end. Pair with start `notes` for reconciliation.\"\n }\n },\n \"required\": [\n \"end_page\",\n \"confidence\",\n \"notes\"\n ],\n \"additionalProperties\": false\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Joined per-page content for this section, ready for downstream ai.extract\"\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"pageName\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"anchored\",\n \"inferred\"\n ],\n \"description\": \"Whether this page is direct LLM evidence (anchored) or continuity-filled (inferred)\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"source\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Raw per-page records covered by this split (in page order). Iterate when downstream needs per-page context (e.g. control.parallel_map over section pages).\"\n },\n \"pages_anchored\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages with direct LLM evidence\"\n },\n \"pages_inferred\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages assigned by deterministic continuity fill\"\n }\n },\n \"required\": [\n \"name\",\n \"page_range\",\n \"confidence\",\n \"notes\",\n \"text\",\n \"pages\",\n \"pages_anchored\",\n \"pages_inferred\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"The same sections keyed by config name, so a downstream step can reference one directly: `{{ steps.<split>.output.sections.<name>.page_range }}`. Prefer this over filtering `splits`. On a duplicate name the last wins.\"\n }\n },\n \"required\": [\n \"splits\",\n \"sections\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.segment` — Separate Documents\n\nSeparate a concatenated batch (one big scan) into typed document instances using an LLM. Consumes ai.parse output and a type taxonomy; discovers an unknown number of documents in any order and emits per-document page ranges + text + type, ready for type-specific ai.extract via control.parallel_map. The inverse of ai.split.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/segment`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Template expression resolving to ai.parse output, e.g. \"{{ steps.parse.output }}\" |\n| `documentTypes` | array<object> | yes | | The document-type taxonomy. The LLM tags each detected document with one of these names, or the reserved \"unknown\" type when none fit. |\n| `rules` | string | no | | Optional natural-language rules appended to the system prompt. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted. |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `windowTokenBudget` | integer | no | | Override the per-window token ceiling. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `summary` | object | yes | | Batch-level escalation summary: labelled vs unlabelled counts + docs needing review. |\n| `documents` | array<object> | yes | | Documents discovered in the batch, in page order. The full batch is covered. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Template expression resolving to ai.parse output, e.g. \\\"{{ steps.parse.output }}\\\"\"\n },\n \"documentTypes\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Type label returned in documents[].type (e.g. \\\"timesheet\\\", \\\"deal-memo\\\")\"\n },\n \"description\": {\n \"description\": \"What this document type looks like — headings, layout, vocabulary, and the cues that mark its FIRST page. Fed to the LLM for both boundary detection and typing.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"The document-type taxonomy. The LLM tags each detected document with one of these names, or the reserved \\\"unknown\\\" type when none fit.\"\n },\n \"rules\": {\n \"description\": \"Optional natural-language rules appended to the system prompt.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"windowTokenBudget\": {\n \"description\": \"Override the per-window token ceiling. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"documentTypes\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"summary\": {\n \"type\": \"object\",\n \"properties\": {\n \"total\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Total documents discovered.\"\n },\n \"labelled\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Documents assigned a known taxonomy type.\"\n },\n \"unlabelled\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Documents the segmenter could not label (type \\\"unknown\\\") — escalate to a human.\"\n },\n \"lowConfidence\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Documents with low boundary/type confidence.\"\n },\n \"byType\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Per-type document counts.\"\n },\n \"needsReview\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"type\": {\n \"type\": \"string\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2\n },\n \"reason\": {\n \"type\": \"string\",\n \"enum\": [\n \"unlabelled\",\n \"low_confidence\"\n ]\n },\n \"notes\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"index\",\n \"type\",\n \"page_range\",\n \"reason\",\n \"notes\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Documents to escalate to a human operator, with the reason for each.\"\n }\n },\n \"required\": [\n \"total\",\n \"labelled\",\n \"unlabelled\",\n \"lowConfidence\",\n \"byType\",\n \"needsReview\"\n ],\n \"additionalProperties\": false,\n \"description\": \"Batch-level escalation summary: labelled vs unlabelled counts + docs needing review.\"\n },\n \"documents\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"0-based position of this document in the batch\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Chosen type name from the taxonomy, or \\\"unknown\\\"\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence at the boundary + type. Coarse enum (low | medium | high).\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM justification for the boundary — useful for debugging\"\n },\n \"evidence\": {\n \"description\": \"Structured start evidence — parse this instead of regexing over `notes`.\",\n \"type\": \"object\",\n \"properties\": {\n \"start_heading_text\": {\n \"description\": \"Verbatim heading/title text the LLM cited as the document start\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"start_page\": {\n \"description\": \"Page where the start appears\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"additionalProperties\": false\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Joined per-page content for this document, ready for downstream ai.extract\"\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"pageName\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"anchored\",\n \"inferred\"\n ]\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"source\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Raw per-page records covered by this document, in page order.\"\n },\n \"pages_anchored\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages with direct LLM boundary evidence\"\n },\n \"pages_inferred\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages assigned by deterministic continuity fill\"\n }\n },\n \"required\": [\n \"index\",\n \"type\",\n \"page_range\",\n \"confidence\",\n \"notes\",\n \"text\",\n \"pages\",\n \"pages_anchored\",\n \"pages_inferred\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Documents discovered in the batch, in page order. The full batch is covered.\"\n }\n },\n \"required\": [\n \"summary\",\n \"documents\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.classify` — Classify\n\nClassify a document or text into one of a fixed label set using an LLM. Output exposes the picked label (constrained to the configured names), a coarse confidence, and a short justification. Pair with control.fail to reject documents that match an undesired label.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/classify`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Template expression for the text to classify. Typically the output of ai.parse, e.g. \"{{ steps.parse.output.text }}\". |\n| `labels` | array<object> | yes | | Allowed labels. The LLM is constrained to pick exactly one of these names. |\n| `prompt` | string | no | | Custom classification instructions appended to the system prompt. Use to clarify edge cases or emphasize evidence the model should weigh. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml (e.g. \"openai/gpt-6-luna\"). Falls back to the tenant default LLM provider when omitted. |\n| `model` | string | no | | Model override (advanced) |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxInputTokens` | integer | no | | Max input tokens. Truncates input text when exceeded. Omit for no limit. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `label` | string | yes | | The selected label name (one of the configured labels). Compare against literal strings to gate downstream steps. |\n| `confidence` | `\"low\"` \\| `\"medium\"` \\| `\"high\"` | yes | | LLM confidence in the classification. Coarse enum — numeric scores cluster meaninglessly at 0.85-0.95. |\n| `reason` | string | yes | | Short justification for the chosen label — useful for debugging. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Template expression for the text to classify. Typically the output of ai.parse, e.g. \\\"{{ steps.parse.output.text }}\\\".\"\n },\n \"labels\": {\n \"minItems\": 2,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"The label value returned in output.label. Keep it short and stable (used in downstream conditions).\"\n },\n \"description\": {\n \"description\": \"What documents fall into this label. Fed to the LLM as guidance.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Allowed labels. The LLM is constrained to pick exactly one of these names.\"\n },\n \"prompt\": {\n \"description\": \"Custom classification instructions appended to the system prompt. Use to clarify edge cases or emphasize evidence the model should weigh.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml (e.g. \\\"openai/gpt-6-luna\\\"). Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (advanced)\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxInputTokens\": {\n \"description\": \"Max input tokens. Truncates input text when exceeded. Omit for no limit.\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"labels\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"label\": {\n \"type\": \"string\",\n \"description\": \"The selected label name (one of the configured labels). Compare against literal strings to gate downstream steps.\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence in the classification. Coarse enum — numeric scores cluster meaninglessly at 0.85-0.95.\"\n },\n \"reason\": {\n \"type\": \"string\",\n \"description\": \"Short justification for the chosen label — useful for debugging.\"\n }\n },\n \"required\": [\n \"label\",\n \"confidence\",\n \"reason\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.classify-pages` — Label Pages\n\nAssign zero or more labels to each page independently (multi-label) using an LLM. Consumes ai.parse output; emits per-page labels and a byLabel map (label -> page indices) that supports NON-contiguous selections. Feed byLabel.<label> straight into ai.vision `pageIndices` to inspect scattered pages of a type (e.g. every signature or property-photo page).\n\n**Behavior and examples:** `eigenpal docs read steps/ai/classify-pages`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | The ai.parse output to label, e.g. \"{{ steps.parse.output }}\". Each page is labelled independently. |\n| `labels` | array<string \\| object> | yes | | Labels a page can carry. A page may match ZERO, ONE, or MANY of them. Each entry is a bare name (e.g. \"photo\") or { name, description }. Names must be unique. |\n| `prompt` | string | no | | Extra classification guidance appended to the system prompt. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml. Falls back to the tenant default. |\n| `model` | string | no | | Model override (advanced). |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `windowTokenBudget` | integer | no | | Per-window token ceiling. Pages are packed into windows under this budget; one LLM call per window. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET (20000). |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `pages` | array<object> | yes | | Every input page, in order, with the labels the model assigned to it. |\n| `byLabel` | record<string, array<integer>> | yes | | Label name -> ascending page indices carrying it. Every configured label is present (empty array when no page matched), so dot access is always safe: `{{ steps.<step>.output.byLabel.<label> }}` resolves to a number[] ready for ai.vision `pageIndices`. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"The ai.parse output to label, e.g. \\\"{{ steps.parse.output }}\\\". Each page is labelled independently.\"\n },\n \"labels\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Label value — the key in output.byLabel and an entry in pages[].labels.\"\n },\n \"description\": {\n \"description\": \"What a page must show to earn this label. Fed to the LLM as guidance.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Labels a page can carry. A page may match ZERO, ONE, or MANY of them. Each entry is a bare name (e.g. \\\"photo\\\") or { name, description }. Names must be unique.\"\n },\n \"prompt\": {\n \"description\": \"Extra classification guidance appended to the system prompt.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml. Falls back to the tenant default.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (advanced).\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"windowTokenBudget\": {\n \"description\": \"Per-window token ceiling. Pages are packed into windows under this budget; one LLM call per window. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET (20000).\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"labels\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"labels\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Labels assigned to this page (possibly empty).\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"labels\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Every input page, in order, with the labels the model assigned to it.\"\n },\n \"byLabel\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n },\n \"description\": \"Label name -> ascending page indices carrying it. Every configured label is present (empty array when no page matched), so dot access is always safe: `{{ steps.<step>.output.byLabel.<label> }}` resolves to a number[] ready for ai.vision `pageIndices`.\"\n }\n },\n \"required\": [\n \"pages\",\n \"byLabel\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.vision` — Inspect Pages (Vision)\n\nInspect rendered page images with a vision model and return structured JSON matching a schema. The visual counterpart to Extract Data: use it for conclusions that live in the pixels rather than the text (is the document signed? are the photos usable?). Renders PDF, image, or Office/Word inputs; route to specific pages with an ai.split page range to keep it cheap.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/vision`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `document` | string | yes | | Template expression resolving to the input file (PDF, image, or Office document). |\n| `pageFrom` | integer \\| string | no | | First page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, starts from the first page. |\n| `pageTo` | integer \\| string | no | | Last page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, runs to the last page. When BOTH pageFrom and pageTo are omitted, the whole document is inspected in chunks of maxPages (divide-and-conquer, results merged). |\n| `pageIndices` | array<integer> \\| string | no | | Explicit list of 0-based page indices to inspect — supports NON-contiguous selections, e.g. [4, 11, 19], or a template resolving to a number[] such as \"{{ steps.label_pages.output.byLabel.photo }}\". Highest priority: when set, pageFrom/pageTo and pages are ignored. |\n| `schema` | object | yes | | JSON Schema defining the structure the vision model should return. Fields not listed in `required` come back null when not found; a missing required field fails the step. |\n| `prompt` | string | no | | Optional instruction refining the extraction. The schema drives it when omitted. |\n| `provider` | string | no | | Provider ID (must support vision). |\n| `model` | string | no | | Model override (must support vision). |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `renderScale` | number | no | | PDF render scale (1.0 = 72 DPI). Raise for small text or weak VLM OCR. Capped at 6 to avoid oversized page rasters. |\n| `imageQuality` | integer | no | | JPEG quality for rendered pages (default 85). |\n| `maxPages` | integer | no | | Chunk size: the maximum pages sent to the vision model in a single call. When the inspected range (or the whole document) is larger, it is split into chunks of this size and the per-chunk results are merged by a reduce pass. The reduce follows each field's DESCRIPTION: a boolean described as \"present on any page\" is OR-ed, one described as \"true for every page\" is AND-ed, and list fields are concatenated. The merge is most reliable for boolean/scalar claims; for schemas that AGGREGATE long lists across chunks it can still drop or reorder items, so prefer a bounded page range for large list extraction. Default 20, capped at 100. |\n\n**Output:** `record<string, unknown>`\n\n> Structured data matching the provided schema. The output also carries a reserved `_vision` key recording the inspected source document ref and the page indices that were rendered, so the UI can re-rasterize exactly those pages client-side. `_vision` is excluded from user-schema validation.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"document\": {\n \"type\": \"string\",\n \"description\": \"Template expression resolving to the input file (PDF, image, or Office document).\"\n },\n \"pageFrom\": {\n \"description\": \"First page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, starts from the first page.\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"pageTo\": {\n \"description\": \"Last page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, runs to the last page. When BOTH pageFrom and pageTo are omitted, the whole document is inspected in chunks of maxPages (divide-and-conquer, results merged).\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"pageIndices\": {\n \"description\": \"Explicit list of 0-based page indices to inspect — supports NON-contiguous selections, e.g. [4, 11, 19], or a template resolving to a number[] such as \\\"{{ steps.label_pages.output.byLabel.photo }}\\\". Highest priority: when set, pageFrom/pageTo and pages are ignored.\",\n \"anyOf\": [\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"pages\": {\n \"description\": \"DEPRECATED — prefer pageIndices (scattered) or pageFrom/pageTo (contiguous). Which pages to inspect: \\\"all\\\", a single [start,end] range, a list of ranges, or a template expression resolving to one of those.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"const\": \"all\"\n },\n {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"Inclusive 0-based [start, end] page range, matching ai.split page_range.\"\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"Inclusive 0-based [start, end] page range, matching ai.split page_range.\"\n }\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"const\": \"object\"\n },\n \"properties\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"required\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"type\",\n \"properties\"\n ],\n \"additionalProperties\": false,\n \"description\": \"JSON Schema defining the structure the vision model should return. Fields not listed in `required` come back null when not found; a missing required field fails the step.\"\n },\n \"prompt\": {\n \"description\": \"Optional instruction refining the extraction. The schema drives it when omitted.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID (must support vision).\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (must support vision).\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"renderScale\": {\n \"description\": \"PDF render scale (1.0 = 72 DPI). Raise for small text or weak VLM OCR. Capped at 6 to avoid oversized page rasters.\",\n \"type\": \"number\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 6\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for rendered pages (default 85).\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"maxPages\": {\n \"description\": \"Chunk size: the maximum pages sent to the vision model in a single call. When the inspected range (or the whole document) is larger, it is split into chunks of this size and the per-chunk results are merged by a reduce pass. The reduce follows each field's DESCRIPTION: a boolean described as \\\"present on any page\\\" is OR-ed, one described as \\\"true for every page\\\" is AND-ed, and list fields are concatenated. The merge is most reliable for boolean/scalar claims; for schemas that AGGREGATE long lists across chunks it can still drop or reorder items, so prefer a bounded page range for large list extraction. Default 20, capped at 100.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 100\n }\n },\n \"required\": [\n \"document\",\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Structured data matching the provided schema. The output also carries a reserved `_vision` key recording the inspected source document ref and the page indices that were rendered, so the UI can re-rasterize exactly those pages client-side. `_vision` is excluded from user-schema validation.\"\n}\n```\n\n\n#### `ai.search-files` — Search Files\n\nInvestigate a ZIP archive with a question and return an answer plus file citations. Read-only: the step opens files in the archive and never writes back. ZIP is the only accepted format in this version. Optionally scope the search to a folder prefix and cap how many files and investigation turns may run.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/search-files`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `archive` | string | yes | | Template expression or file reference for the ZIP archive to inspect. ZIP is the only accepted format in this version. |\n| `query` | string | yes | | Natural-language question to answer from files inside the archive. |\n| `root` | string | no | | Optional folder prefix inside the archive. When set, only files under this path are in scope. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted. |\n| `model` | string | no | | Model override (advanced). |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxIterations` | integer | no | `12` | Maximum investigation turns. Default 12, capped at 50. |\n| `maxFiles` | integer | no | `50` | Maximum files the step may open. Default 50, capped at 200. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `answer` | string | yes | | The investigation answer. Citations point at inspected files; the answer text itself is model-generated. |\n| `citations` | array<object> | yes | | Citations to files the step inspected. Excerpts, when present, are copied from inspected text. |\n| `filesInspected` | array<string> | yes | | Archive-relative paths of files the step opened during investigation. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"archive\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression or file reference for the ZIP archive to inspect. ZIP is the only accepted format in this version.\"\n },\n \"query\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Natural-language question to answer from files inside the archive.\"\n },\n \"root\": {\n \"description\": \"Optional folder prefix inside the archive. When set, only files under this path are in scope.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (advanced).\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxIterations\": {\n \"description\": \"Maximum investigation turns. Default 12, capped at 50.\",\n \"default\": 12,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 50\n },\n \"maxFiles\": {\n \"description\": \"Maximum files the step may open. Default 50, capped at 200.\",\n \"default\": 50,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 200\n }\n },\n \"required\": [\n \"archive\",\n \"query\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"answer\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"The investigation answer. Citations point at inspected files; the answer text itself is model-generated.\"\n },\n \"citations\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Archive-relative path of a file the step inspected and cited.\"\n },\n \"excerpt\": {\n \"description\": \"Optional excerpt copied from the inspected file text. Omitted when no verbatim excerpt was supplied.\",\n \"type\": \"string\",\n \"maxLength\": 2000\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Citations to files the step inspected. Excerpts, when present, are copied from inspected text.\"\n },\n \"filesInspected\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Archive-relative paths of files the step opened during investigation.\"\n }\n },\n \"required\": [\n \"answer\",\n \"citations\",\n \"filesInspected\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.figure-crops` — Figure Crops\n\nCrop and caption figure elements from a parsed PDF. Renders the source document, crops each kind=figure bbox from ai.parse output, and describes the crop with a vision model. Output is captions plus normalized bboxes for evidence viewers.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/figure-crops`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Storage reference or template expression for the source PDF |\n| `parseOutput` | unknown | yes | | ai.parse output object (template {{steps.<parse>.output}}); figure elements are read from its `elements` array |\n| `model` | string | no | | Vision model for captions (defaults to workspace model) |\n| `figureInstructions` | string | no | | Custom caption instruction; applied per figure crop |\n| `maxFigures` | integer | no | `40` | Cap on figures processed per document |\n| `minAreaFrac` | number | no | `0` | Skip figures below this page-area fraction (logos/decorations) |\n| `includeCrops` | boolean | no | `false` | Include base64 JPEG crops in output (heavy; default off — captions + bboxes only) |\n| `renderScale` | number | no | `1` | Scale factor for rendering PDF pages before cropping |\n| `imageQuality` | integer | no | `85` | JPEG quality for crops |\n| `llmReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `figures` | array<object> | yes | | |\n| `_figureCrops` | object | yes | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Storage reference or template expression for the source PDF\"\n },\n \"parseOutput\": {\n \"description\": \"ai.parse output object (template {{steps.<parse>.output}}); figure elements are read from its `elements` array\"\n },\n \"model\": {\n \"description\": \"Vision model for captions (defaults to workspace model)\",\n \"type\": \"string\"\n },\n \"figureInstructions\": {\n \"description\": \"Custom caption instruction; applied per figure crop\",\n \"type\": \"string\"\n },\n \"maxFigures\": {\n \"description\": \"Cap on figures processed per document\",\n \"default\": 40,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"minAreaFrac\": {\n \"description\": \"Skip figures below this page-area fraction (logos/decorations)\",\n \"default\": 0,\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"includeCrops\": {\n \"description\": \"Include base64 JPEG crops in output (heavy; default off — captions + bboxes only)\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"renderScale\": {\n \"description\": \"Scale factor for rendering PDF pages before cropping\",\n \"default\": 1,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for crops\",\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"llmReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n }\n },\n \"required\": [\n \"input\",\n \"parseOutput\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"figures\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"page\": {\n \"type\": \"number\"\n },\n \"bboxNorm\": {\n \"anyOf\": [\n {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"number\"\n },\n {\n \"type\": \"number\"\n },\n {\n \"type\": \"number\"\n },\n {\n \"type\": \"number\"\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 4,\n \"maxItems\": 4\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"areaFrac\": {\n \"type\": \"number\"\n },\n \"caption\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"cropJpegBase64\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"page\",\n \"bboxNorm\",\n \"areaFrac\",\n \"caption\"\n ],\n \"additionalProperties\": false\n }\n },\n \"_figureCrops\": {\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"number\"\n }\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"skippedSmall\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"pages\",\n \"skippedSmall\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"figures\",\n \"_figureCrops\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n### Transform steps — deterministic data transforms\n\n#### `transform.set` — Set Value\n\nSet key-value pairs in the output object\n\n**Behavior and examples:** `eigenpal docs read steps/transform/set`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fields` | record<string, unknown> | yes | | Key-value pairs to set in output |\n| `input` | record<string, unknown> | no | | Base object to extend |\n\n**Output:** `record<string, unknown>`\n\n> Object with all fields set\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fields\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Key-value pairs to set in output\"\n },\n \"input\": {\n \"description\": \"Base object to extend\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"fields\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Object with all fields set\"\n}\n```\n\n\n#### `transform.remove` — Remove Fields\n\nRemove specified fields from an object\n\n**Behavior and examples:** `eigenpal docs read steps/transform/remove`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | record<string, unknown> | no | | Object to remove fields from |\n| `fields` | array<string> | yes | | Field names to remove |\n\n**Output:** `record<string, unknown>`\n\n> Object with fields removed\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"description\": \"Object to remove fields from\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"fields\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Field names to remove\"\n }\n },\n \"required\": [\n \"fields\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Object with fields removed\"\n}\n```\n\n\n#### `transform.combine` — Combine Data\n\nMerge multiple objects or concatenate arrays\n\n**Behavior and examples:** `eigenpal docs read steps/transform/combine`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `sources` | array<string> | yes | | Template expressions for sources to combine |\n| `target` | string | yes | | Target path in output |\n| `mode` | `\"merge\"` \\| `\"concat\"` \\| `\"deep\"` | no | `\"merge\"` | |\n\n**Output:** `record<string, unknown> \\| array<unknown>`\n\n> Combined result\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"sources\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Template expressions for sources to combine\"\n },\n \"target\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Target path in output\"\n },\n \"mode\": {\n \"default\": \"merge\",\n \"type\": \"string\",\n \"enum\": [\n \"merge\",\n \"concat\",\n \"deep\"\n ]\n }\n },\n \"required\": [\n \"sources\",\n \"target\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"anyOf\": [\n {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n {\n \"type\": \"array\",\n \"items\": {}\n }\n ],\n \"description\": \"Combined result\"\n}\n```\n\n\n#### `transform.split` — Split Data\n\nSplit a string by delimiter or extract keys from an object\n\n**Behavior and examples:** `eigenpal docs read steps/transform/split`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string \\| record<string, unknown> | no | | String or object to split |\n| `source` | string | no | | Template expression for source |\n| `by` | string | no | `\",\"` | Delimiter for string splitting |\n| `delimiter` | string | no | | Alias for by |\n| `limit` | number | no | | Max number of splits |\n| `keys` | array<string> | no | | Keys to extract from object |\n\n**Output:** `array<string> \\| object`\n\n> Split result - array or extracted/remaining object\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"description\": \"String or object to split\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n ]\n },\n \"source\": {\n \"description\": \"Template expression for source\",\n \"type\": \"string\"\n },\n \"by\": {\n \"description\": \"Delimiter for string splitting\",\n \"default\": \",\",\n \"type\": \"string\"\n },\n \"delimiter\": {\n \"description\": \"Alias for by\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"description\": \"Max number of splits\",\n \"type\": \"number\"\n },\n \"keys\": {\n \"description\": \"Keys to extract from object\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"anyOf\": [\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"extracted\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"remaining\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"extracted\",\n \"remaining\"\n ],\n \"additionalProperties\": false\n }\n ],\n \"description\": \"Split result - array or extracted/remaining object\"\n}\n```\n\n\n#### `transform.merge` — Merge Inputs\n\nMerge multiple named inputs into a single output\n\n**Behavior and examples:** `eigenpal docs read steps/transform/merge`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | record<string, unknown> | no | | Named inputs to merge; each key becomes a key in the merged output |\n| `preservePortNames` | boolean | no | `true` | |\n| `outputKey` | string | no | | |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | array<unknown> | yes | | |\n| `count` | number | yes | | |\n| `merged` | record<string, unknown> | no | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"description\": \"Named inputs to merge; each key becomes a key in the merged output\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"preservePortNames\": {\n \"default\": true,\n \"type\": \"boolean\"\n },\n \"outputKey\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"array\",\n \"items\": {}\n },\n \"count\": {\n \"type\": \"number\"\n },\n \"merged\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"items\",\n \"count\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.template` — Fill Template\n\nFill a DOCX or XLSX workspace template with data from previous steps. Reference a tmpl_... id, or a local ./templates/file.xlsx path (CLI push uploads it). Git agent templates use the fill-template skill instead and cannot be referenced here. File IDs (file_...) are not accepted. Placeholders are auto-detected. In the Office file use {placeholder} and {table:array.prop}; {{placeholder}} in an XLSX file is rejected ({{ }} is YAML Liquid only).\n\n**Behavior and examples:** `eigenpal docs read steps/transform/template`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `templateId` | string | no | | Workspace template ID (tmpl_...) from the Templates table (DOCX or XLSX). Git agent templates cannot be referenced here. File IDs (file_...) are not accepted. Mutually exclusive with `template`. |\n| `template` | string | no | | Local DOCX or XLSX path relative to the workflow YAML (e.g. ./templates/foo.xlsx). CLI push keeps the real path inside the workflow project unless you pass --allow-external-templates, uploads unmatched files as new tmpl_ resources, and does not rewrite the source YAML. Mutually exclusive with templateId. |\n| `templateRevisionId` | string | no | | Immutable template revision ID (tmpr_...). Pin this when executions must keep using the same template bytes after replacements. Requires templateId; local `template` paths are pinned automatically on push. |\n| `data` | record<string, unknown> | yes | | Data object to merge into template. Each key must be explicitly defined - cannot pass a whole object as single expression. |\n| `outputFilename` | string | no | | Output filename - supports {{field}} syntax; .docx or .xlsx extension is added if omitted |\n| `highlightNotFound` | boolean | no | `true` | Highlight missing variables with red-colored text in the output document (DOCX only; ignored for XLSX) |\n| `notFoundText` | string | no | `\"NOT FOUND\"` | Text to display for missing variables when highlightNotFound is enabled (DOCX only; ignored for XLSX) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from files table |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"templateId\": {\n \"description\": \"Workspace template ID (tmpl_...) from the Templates table (DOCX or XLSX). Git agent templates cannot be referenced here. File IDs (file_...) are not accepted. Mutually exclusive with `template`.\",\n \"type\": \"string\",\n \"pattern\": \"^tmpl_[A-Za-z0-9_-]{21}$\"\n },\n \"template\": {\n \"description\": \"Local DOCX or XLSX path relative to the workflow YAML (e.g. ./templates/foo.xlsx). CLI push keeps the real path inside the workflow project unless you pass --allow-external-templates, uploads unmatched files as new tmpl_ resources, and does not rewrite the source YAML. Mutually exclusive with templateId.\",\n \"type\": \"string\"\n },\n \"templateRevisionId\": {\n \"description\": \"Immutable template revision ID (tmpr_...). Pin this when executions must keep using the same template bytes after replacements. Requires templateId; local `template` paths are pinned automatically on push.\",\n \"type\": \"string\",\n \"pattern\": \"^tmpr_[A-Za-z0-9_-]{21}$\"\n },\n \"data\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Data object to merge into template. Each key must be explicitly defined - cannot pass a whole object as single expression.\"\n },\n \"outputFilename\": {\n \"description\": \"Output filename - supports {{field}} syntax; .docx or .xlsx extension is added if omitted\",\n \"type\": \"string\"\n },\n \"highlightNotFound\": {\n \"description\": \"Highlight missing variables with red-colored text in the output document (DOCX only; ignored for XLSX)\",\n \"default\": true,\n \"type\": \"boolean\"\n },\n \"notFoundText\": {\n \"description\": \"Text to display for missing variables when highlightNotFound is enabled (DOCX only; ignored for XLSX)\",\n \"default\": \"NOT FOUND\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"data\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from files table\"\n }\n },\n \"required\": [\n \"fileId\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.pdf-embed` — Embed PDF Text\n\nEmbed OCR text layer into scanned PDFs/images to make them searchable\n\n**Behavior and examples:** `eigenpal docs read steps/transform/pdf-embed`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | File input - template expression e.g. {{input.document}} |\n| `parseResult` | string | yes | | Parse result - template expression e.g. {{steps.parse.output}} |\n| `outputFilename` | string | no | | Output filename - supports {{filename}} syntax |\n| `confidenceThreshold` | number | no | `0.7` | Minimum OCR confidence (0-1) to include a word |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from files table |\n| `pageCount` | number | yes | | Number of pages in the output PDF |\n| `wordCount` | number | yes | | Number of words embedded |\n| `text` | string | yes | | Extracted text from the document |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"File input - template expression e.g. {{input.document}}\"\n },\n \"parseResult\": {\n \"type\": \"string\",\n \"description\": \"Parse result - template expression e.g. {{steps.parse.output}}\"\n },\n \"outputFilename\": {\n \"description\": \"Output filename - supports {{filename}} syntax\",\n \"type\": \"string\"\n },\n \"confidenceThreshold\": {\n \"description\": \"Minimum OCR confidence (0-1) to include a word\",\n \"default\": 0.7,\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"required\": [\n \"input\",\n \"parseResult\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from files table\"\n },\n \"pageCount\": {\n \"type\": \"number\",\n \"description\": \"Number of pages in the output PDF\"\n },\n \"wordCount\": {\n \"type\": \"number\",\n \"description\": \"Number of words embedded\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Extracted text from the document\"\n }\n },\n \"required\": [\n \"fileId\",\n \"pageCount\",\n \"wordCount\",\n \"text\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.crop-regions` — Crop Regions\n\nRender a PDF or image and crop normalized bounding boxes into JPEG run output artifacts. Pair with transform.script (bbox lists from ai.parse layout) and ai.extract or ai.vision for captions.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/crop-regions`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | File input — template expression e.g. {{ input.document }} resolving to a PDF or image |\n| `regions` | string \\| array<object> | yes | | Regions to crop — pageIndex + normalized bbox per entry |\n| `renderScale` | number | no | `1` | Scale factor when rasterizing PDF pages before cropping |\n| `imageQuality` | integer | no | `85` | JPEG quality for cropped outputs |\n| `paddingFrac` | number | no | `0.02` | Padding around each bbox as a fraction of the shorter page edge |\n| `minCropPx` | integer | no | `8` | Minimum crop width/height in pixels; smaller crops fall back to the full page |\n| `maxRegions` | integer | no | `100` | Maximum regions processed per invocation |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `regions` | array<object> | yes | | Successfully cropped regions |\n| `skipped` | integer | no | | Regions skipped (invalid bbox or missing page) |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"File input — template expression e.g. {{ input.document }} resolving to a PDF or image\"\n },\n \"regions\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to a region array, e.g. {{ steps.list-figures.output.regions }}\"\n },\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"description\": \"Stable region id used in output and crop filenames (defaults to region-N)\",\n \"type\": \"string\"\n },\n \"pageIndex\": {\n \"description\": \"0-based page index to crop from (images use page 0)\",\n \"default\": 0,\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"bbox\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 4,\n \"maxItems\": 4,\n \"description\": \"Normalized axis-aligned bbox [x0, y0, x1, y1]\"\n }\n },\n \"required\": [\n \"bbox\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Regions to crop from the rendered document\"\n }\n ],\n \"description\": \"Regions to crop — pageIndex + normalized bbox per entry\"\n },\n \"renderScale\": {\n \"description\": \"Scale factor when rasterizing PDF pages before cropping\",\n \"default\": 1,\n \"type\": \"number\",\n \"minimum\": 0.5,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for cropped outputs\",\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"paddingFrac\": {\n \"description\": \"Padding around each bbox as a fraction of the shorter page edge\",\n \"default\": 0.02,\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 0.2\n },\n \"minCropPx\": {\n \"description\": \"Minimum crop width/height in pixels; smaller crops fall back to the full page\",\n \"default\": 8,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991\n },\n \"maxRegions\": {\n \"description\": \"Maximum regions processed per invocation\",\n \"default\": 100,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 200\n }\n },\n \"required\": [\n \"input\",\n \"regions\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"regions\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"description\": \"Region id (from input or auto-generated)\"\n },\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"0-based page index the crop was taken from\"\n },\n \"bbox\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 4,\n \"maxItems\": 4,\n \"description\": \"Normalized bbox that was cropped\"\n },\n \"width\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991,\n \"description\": \"Crop width in pixels\"\n },\n \"height\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991,\n \"description\": \"Crop height in pixels\"\n },\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"Run output file id for the JPEG crop\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Stored crop filename\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"const\": \"image/jpeg\",\n \"description\": \"Always image/jpeg\"\n },\n \"size\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"JPEG size in bytes\"\n }\n },\n \"required\": [\n \"id\",\n \"pageIndex\",\n \"bbox\",\n \"width\",\n \"height\",\n \"fileId\",\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Successfully cropped regions\"\n },\n \"skipped\": {\n \"description\": \"Regions skipped (invalid bbox or missing page)\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"regions\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.xlsx-to-json` — Spreadsheet to JSON\n\nConvert 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.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/xlsx-to-json`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime |\n| `sheet` | integer \\| string | no | | Sheet to read: 0-based index or exact sheet name. Omit for the first sheet. |\n| `outputCsv` | boolean | no | `false` | If true, also write CSV to storage and include fileId. Zero-config uses SheetJS CSV of the effective sheet extent, excluding empty trailing rows and columns. When columns, range, headerRow, valueMode, blankCells, or blankRows are set, CSV matches that projection. |\n| `includeCellMetadata` | boolean | no | `false` | Include original cell address, type, raw/displayed value, number format and date rendering. Also includes sheet metadata with the workbook date system. Does not classify identifiers or clean names. |\n| `includeMetadata` | boolean | no | `false` | If true, include sheet metadata and diagnostics in the step output. includeCellMetadata also enables these. Omit to keep output as rows (and fileId when outputCsv is true). Warnings are still logged when this is false. |\n| `outputFilename` | string | no | | Output CSV filename when outputCsv is true - supports LiquidJS e.g. {{filename}}.csv |\n| `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. |\n| `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. |\n| `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. |\n| `range` | string | no | | Optional rectangular A1 range without a sheet qualifier, e.g. A1:D20. Disjoint ranges are rejected. |\n| `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. |\n| `blankRows` | `\"skip\"` \\| `\"keep\"` | no | `\"skip\"` | skip (default) drops rows whose projected columns are all truly empty. keep retains them. Detection uses projected columns only. |\n| `limits` | object | no | | Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `cellMetadata` | array<object> | no | | Evidence for nonblank projected data cells, linked to rows by outputRowIndex and key. Present when includeCellMetadata is true. |\n| `rows` | array<record<string, unknown>> | yes | | Array of row objects (first row = headers as keys unless headerRow is false) |\n| `fileId` | string | no | | File ID of stored CSV when outputCsv is true |\n| `sheet` | object | no | | Selected sheet metadata after projection. Present when includeMetadata or includeCellMetadata is true. |\n| `diagnostics` | array<object> | no | | Non-fatal warnings collected while reading the sheet. Present when includeMetadata or includeCellMetadata is true. Warnings are still logged when metadata is omitted. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime\"\n },\n \"sheet\": {\n \"description\": \"Sheet to read: 0-based index or exact sheet name. Omit for the first sheet.\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"outputCsv\": {\n \"description\": \"If true, also write CSV to storage and include fileId. Zero-config uses SheetJS CSV of the effective sheet extent, excluding empty trailing rows and columns. When columns, range, headerRow, valueMode, blankCells, or blankRows are set, CSV matches that projection.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"includeCellMetadata\": {\n \"description\": \"Include original cell address, type, raw/displayed value, number format and date rendering. Also includes sheet metadata with the workbook date system. Does not classify identifiers or clean names.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"includeMetadata\": {\n \"description\": \"If true, include sheet metadata and diagnostics in the step output. includeCellMetadata also enables these. Omit to keep output as rows (and fileId when outputCsv is true). Warnings are still logged when this is false.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"outputFilename\": {\n \"description\": \"Output CSV filename when outputCsv is true - supports LiquidJS e.g. {{filename}}.csv\",\n \"type\": \"string\"\n },\n \"headerRow\": {\n \"description\": \"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.\",\n \"anyOf\": [\n {\n \"type\": \"boolean\",\n \"const\": false\n },\n {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991\n }\n ]\n },\n \"columns\": {\n \"description\": \"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.\",\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Output object key for this column\"\n },\n \"index\": {\n \"description\": \"0-based absolute worksheet column. Use instead of header.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"header\": {\n \"description\": \"Exact displayed header text. Use instead of index. Requires a header row.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"occurrence\": {\n \"description\": \"1-based occurrence of header when the same displayed header appears more than once. Only valid with header.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"key\"\n ],\n \"additionalProperties\": false\n }\n },\n \"valueMode\": {\n \"description\": \"raw (default) returns typed cached cell values. displayed returns formatted cell text (dates, leading zeros, punctuation, diacritics, embedded newlines). Formulas are never calculated.\",\n \"default\": \"raw\",\n \"type\": \"string\",\n \"enum\": [\n \"raw\",\n \"displayed\"\n ]\n },\n \"range\": {\n \"description\": \"Optional rectangular A1 range without a sheet qualifier, e.g. A1:D20. Disjoint ranges are rejected.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"blankCells\": {\n \"description\": \"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.\",\n \"default\": \"empty-string\",\n \"type\": \"string\",\n \"enum\": [\n \"empty-string\",\n \"null\",\n \"omit\"\n ]\n },\n \"blankRows\": {\n \"description\": \"skip (default) drops rows whose projected columns are all truly empty. keep retains them. Detection uses projected columns only.\",\n \"default\": \"skip\",\n \"type\": \"string\",\n \"enum\": [\n \"skip\",\n \"keep\"\n ]\n },\n \"limits\": {\n \"type\": \"object\",\n \"properties\": {\n \"maxInputBytes\": {\n \"description\": \"Maximum input file size in bytes. Omitted uses the server default (52,428,800, 50 MiB). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 52428800\n },\n \"maxRows\": {\n \"description\": \"Maximum rows in the selected range. Omitted uses the server default (100,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100000\n },\n \"maxColumns\": {\n \"description\": \"Maximum columns in the selected range. Omitted uses the server default (256). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 256\n },\n \"maxCells\": {\n \"description\": \"Maximum cells in the selected range. Omitted uses the server default (5,000,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 5000000\n }\n },\n \"additionalProperties\": false,\n \"description\": \"Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults.\"\n }\n },\n \"required\": [\n \"input\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"cellMetadata\": {\n \"description\": \"Evidence for nonblank projected data cells, linked to rows by outputRowIndex and key. Present when includeCellMetadata is true.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\",\n \"description\": \"Original A1 cell address\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Excel storage type: n=number, s=string, b=boolean, e=error, d=date, z=blank. A numeric date remains type n.\"\n },\n \"rawValue\": {\n \"description\": \"Stored cached value; formulas are never evaluated\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"displayedValue\": {\n \"type\": \"string\",\n \"description\": \"Value formatted using the workbook number format and date system\"\n },\n \"numberFormat\": {\n \"type\": \"string\"\n },\n \"formula\": {\n \"type\": \"string\"\n },\n \"dateValue\": {\n \"description\": \"Calendar rendering for a valid date-formatted serial, without a timezone. Evidence of Excel formatting, not a business classification.\",\n \"type\": \"string\"\n },\n \"excelLeapDay\": {\n \"description\": \"True for the fictitious 1900-02-29 in the Excel 1900 date system\",\n \"type\": \"boolean\"\n },\n \"key\": {\n \"type\": \"string\"\n },\n \"outputRowIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"address\",\n \"type\",\n \"displayedValue\",\n \"key\",\n \"outputRowIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rows\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"description\": \"Array of row objects (first row = headers as keys unless headerRow is false)\"\n },\n \"fileId\": {\n \"description\": \"File ID of stored CSV when outputCsv is true\",\n \"type\": \"string\"\n },\n \"sheet\": {\n \"description\": \"Selected sheet metadata after projection. Present when includeMetadata or includeCellMetadata is true.\",\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Selected sheet name\"\n },\n \"declaredRange\": {\n \"description\": \"Worksheet declared extent before empty trailing rows/columns were removed\",\n \"type\": \"string\"\n },\n \"dateSystem\": {\n \"description\": \"Workbook Excel date system\",\n \"type\": \"string\",\n \"enum\": [\n \"1900\",\n \"1904\"\n ]\n },\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"0-based sheet index in the workbook\"\n },\n \"range\": {\n \"type\": \"string\",\n \"description\": \"Effective rectangular A1 range that was read\"\n },\n \"rowCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of data rows returned in rows\"\n },\n \"columns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Output keys in order\"\n }\n },\n \"required\": [\n \"name\",\n \"index\",\n \"range\",\n \"rowCount\",\n \"columns\"\n ],\n \"additionalProperties\": false\n },\n \"diagnostics\": {\n \"description\": \"Non-fatal warnings collected while reading the sheet. Present when includeMetadata or includeCellMetadata is true. Warnings are still logged when metadata is omitted.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"severity\": {\n \"type\": \"string\",\n \"const\": \"warning\",\n \"description\": \"Diagnostic severity\"\n },\n \"code\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Stable diagnostic code\"\n },\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Human-readable diagnostic message\"\n },\n \"cell\": {\n \"description\": \"A1 address of the related cell when applicable\",\n \"type\": \"string\"\n },\n \"row\": {\n \"description\": \"1-based Excel row when applicable\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"column\": {\n \"description\": \"0-based worksheet column when applicable\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"severity\",\n \"code\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"rows\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.json-to-xlsx` — JSON to XLSX\n\nConvert JSON rows into an XLSX spreadsheet. Pair with transform.xlsx-to-json. Formula-looking strings stay text; nested cell values are rejected.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/json-to-xlsx`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `filename` | string | no | | Output filename — supports LiquidJS; .xlsx is added if omitted |\n| `columns` | array<object> | no | | Ordered columns for a single-sheet workbook. Use sheets for multiple sheets. |\n| `rows` | string \\| array<record<string, unknown>> | no | | Array of row objects, or a template expression that resolves to one |\n| `sheets` | array<object> | no | | Multiple sheets. Do not combine with top-level columns/rows. |\n| `limits` | object | no | | Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from the files table |\n| `filename` | string | yes | | Sanitized output filename including .xlsx |\n| `sheetCount` | integer | yes | | Number of sheets in the workbook |\n| `sheets` | array<object> | yes | | Per-sheet name and row count |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"description\": \"Output filename — supports LiquidJS; .xlsx is added if omitted\",\n \"type\": \"string\"\n },\n \"columns\": {\n \"description\": \"Ordered columns for a single-sheet workbook. Use sheets for multiple sheets.\",\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Row object key to read for this column\"\n },\n \"header\": {\n \"description\": \"Header cell text. Defaults to key.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"date\"\n ],\n \"description\": \"Cell type. Omit to infer from the JSON value. YYYY-MM-DD strings stay text unless type is date.\"\n }\n },\n \"required\": [\n \"key\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rows\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to an array of row objects, e.g. {{ steps.extract.output.items }}\"\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"description\": \"Array of row objects\"\n }\n ],\n \"description\": \"Array of row objects, or a template expression that resolves to one\"\n },\n \"sheets\": {\n \"description\": \"Multiple sheets. Do not combine with top-level columns/rows.\",\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Sheet name. Defaults to Sheet1, Sheet2, …. Excel limit: 31 characters. Cannot contain : \\\\ / ? * [ ], cannot start or end with a single quote, and History is reserved.\"\n },\n \"columns\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Row object key to read for this column\"\n },\n \"header\": {\n \"description\": \"Header cell text. Defaults to key.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"date\"\n ],\n \"description\": \"Cell type. Omit to infer from the JSON value. YYYY-MM-DD strings stay text unless type is date.\"\n }\n },\n \"required\": [\n \"key\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Ordered columns for this sheet\"\n },\n \"rows\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to an array of row objects, e.g. {{ steps.extract.output.items }}\"\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"description\": \"Array of row objects\"\n }\n ],\n \"description\": \"Array of row objects, or a template expression that resolves to one\"\n }\n },\n \"required\": [\n \"columns\",\n \"rows\"\n ],\n \"additionalProperties\": false\n }\n },\n \"limits\": {\n \"type\": \"object\",\n \"properties\": {\n \"maxSheets\": {\n \"description\": \"Maximum worksheets. Omitted uses the server default (50). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 50\n },\n \"maxRowsPerSheet\": {\n \"description\": \"Maximum data rows per sheet. Omitted uses the server default (100,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100000\n },\n \"maxTotalRows\": {\n \"description\": \"Maximum data rows summed across all sheets. Omitted uses the server default (250,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 250000\n },\n \"maxColumns\": {\n \"description\": \"Maximum columns per sheet. Omitted uses the server default (256). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 256\n },\n \"maxTotalCells\": {\n \"description\": \"Maximum populated cells across the workbook. Omitted uses the server default (5,000,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 5000000\n },\n \"maxOutputBytes\": {\n \"description\": \"Maximum serialized .xlsx size in bytes. Omitted uses the server default (52,428,800, 50 MiB). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 52428800\n }\n },\n \"additionalProperties\": false,\n \"description\": \"Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from the files table\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Sanitized output filename including .xlsx\"\n },\n \"sheetCount\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of sheets in the workbook\"\n },\n \"sheets\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Written sheet name\"\n },\n \"rowCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of data rows written (excludes header)\"\n }\n },\n \"required\": [\n \"name\",\n \"rowCount\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Per-sheet name and row count\"\n }\n },\n \"required\": [\n \"fileId\",\n \"filename\",\n \"sheetCount\",\n \"sheets\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.script` — Script\n\nExecute a TypeScript function in a QuickJS sandbox. Input keys become function parameters in any order, and the required `: R` return-type annotation IS this step's output schema: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/script`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `inputs` | record<string, string> | no | | Named inputs mapped from template expressions. Keys become function parameters; parameter order is independent of YAML/JSON key order: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`. |\n| `function` | string | yes | | TypeScript function declaration. Must be `function script(args): R { … }` where parameter names exactly match the configured input keys in any order and `R` is a return type annotation. The annotation IS this step's output schema. |\n| `timeout` | number | no | `5000` | Max execution time in milliseconds (default: 5000) |\n| `memoryLimit` | number | no | `10485760` | Max memory in bytes (default: 10MB) |\n\n**Output:** `unknown`\n\n> Value returned from script. Validated at runtime against the JSON Schema derived from the function's return type annotation.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"inputs\": {\n \"description\": \"Named inputs mapped from template expressions. Keys become function parameters; parameter order is independent of YAML/JSON key order: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"function\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 50000,\n \"description\": \"TypeScript function declaration. Must be `function script(args): R { … }` where parameter names exactly match the configured input keys in any order and `R` is a return type annotation. The annotation IS this step's output schema.\"\n },\n \"timeout\": {\n \"description\": \"Max execution time in milliseconds (default: 5000)\",\n \"default\": 5000,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n },\n \"memoryLimit\": {\n \"description\": \"Max memory in bytes (default: 10MB)\",\n \"default\": 10485760,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n }\n },\n \"required\": [\n \"function\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"description\": \"Value returned from script. Validated at runtime against the JSON Schema derived from the function's return type annotation.\"\n}\n```\n\n\n#### `transform.text-chunker` — Text Chunker\n\nSplit long text into chunks with regex-anchored boundaries, overlap, and header preservation. Accepts raw text or a parsed-document object; chunks carry source page indexes when pages are provided.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/text-chunker`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string \\| record<string, unknown> | yes | | Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }` (e.g. `{{ steps.parse.output }}`). Pages preserve per-chunk page provenance. |\n| `maxChars` | integer | yes | | Target chunk size in characters. Hard ceiling per chunk is 1.5×. |\n| `overlap` | integer | no | `0` | Characters duplicated at chunk boundaries (default 0). Must be < maxChars / 2. |\n| `splitOn` | array<string> | no | | Ordered list of regexes; the first that matches near the chunk boundary wins. Falls back to char-cut when none match. Tip: list narrowest first (e.g. /\\d+\\.\\d+\\s+/ before /\\n\\n+/). |\n| `maxChunks` | integer | no | `64` | Safety cap; later chunks are dropped and `summary.truncated` flips to true. |\n| `preserveHeader` | integer | no | `0` | Prepend the first N characters of the input to every chunk (good for \"always include the contract title\"). |\n| `minChunkChars` | integer | no | `0` | Trailing chunks shorter than this are merged into the previous chunk. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `chunks` | array<object> | yes | | |\n| `summary` | object | yes | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"pages\"\n ],\n \"additionalProperties\": {}\n }\n ],\n \"description\": \"Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }` (e.g. `{{ steps.parse.output }}`). Pages preserve per-chunk page provenance.\"\n },\n \"maxChars\": {\n \"type\": \"integer\",\n \"minimum\": 100,\n \"maximum\": 100000,\n \"description\": \"Target chunk size in characters. Hard ceiling per chunk is 1.5×.\"\n },\n \"overlap\": {\n \"default\": 0,\n \"description\": \"Characters duplicated at chunk boundaries (default 0). Must be < maxChars / 2.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"splitOn\": {\n \"description\": \"Ordered list of regexes; the first that matches near the chunk boundary wins. Falls back to char-cut when none match. Tip: list narrowest first (e.g. /\\\\d+\\\\.\\\\d+\\\\s+/ before /\\\\n\\\\n+/).\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"maxChunks\": {\n \"default\": 64,\n \"description\": \"Safety cap; later chunks are dropped and `summary.truncated` flips to true.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 1000\n },\n \"preserveHeader\": {\n \"default\": 0,\n \"description\": \"Prepend the first N characters of the input to every chunk (good for \\\"always include the contract title\\\").\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"minChunkChars\": {\n \"default\": 0,\n \"description\": \"Trailing chunks shorter than this are merged into the previous chunk.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"maxChars\",\n \"overlap\",\n \"maxChunks\",\n \"preserveHeader\",\n \"minChunkChars\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"chunks\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"total\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"startOffset\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"endOffset\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Page indexes that contributed text to this chunk (empty for raw-string input).\"\n }\n },\n \"required\": [\n \"text\",\n \"index\",\n \"total\",\n \"startOffset\",\n \"endOffset\",\n \"pages\"\n ],\n \"additionalProperties\": false\n }\n },\n \"summary\": {\n \"type\": \"object\",\n \"properties\": {\n \"inputChars\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"totalChunks\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"avgChunkChars\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"maxChunkChars\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"truncated\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"inputChars\",\n \"totalChunks\",\n \"avgChunkChars\",\n \"maxChunkChars\",\n \"truncated\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"chunks\",\n \"summary\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.regex-extract` — Regex Extract\n\nPull named fields from text via regex patterns (deterministic counterpart to ai.extract). Accepts raw text or a parsed-document object; matches carry `_evidence.pageIndex` when pages are provided.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/regex-extract`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string \\| record<string, unknown> | yes | | Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }`. Pages enable per-match `_evidence.pageIndex`. |\n| `fields` | record<string, object> | yes | | Named field → pattern mapping. |\n| `flags` | string | no | | Default regex flags applied when a field omits its own `flags`. Subset of \"gimsuy\". |\n| `searchWindow` | integer | no | | Only search the first N characters of input (perf). Omit for full search. |\n\n**Output:** `record<string, unknown>`\n\n> Field name → extracted value (or default), plus `_evidence: { [field]: { pageIndex, matchOffset, raw } }` and `_unmatched: string[]`.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"pages\"\n ],\n \"additionalProperties\": {}\n }\n ],\n \"description\": \"Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }`. Pages enable per-match `_evidence.pageIndex`.\"\n },\n \"fields\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"pattern\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Regex source. Must contain at least one capturing group.\"\n },\n \"flags\": {\n \"description\": \"Per-field regex flags (overrides the step-level `flags`). Subset of \\\"gimsuy\\\".\",\n \"type\": \"string\",\n \"pattern\": \"^(?!.*(.).*\\\\1)[gimsuy]*$\"\n },\n \"max\": {\n \"default\": 1,\n \"description\": \"Max matches to keep. Default 1. Use \\\"all\\\" plus `select` to combine multiple hits.\",\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"const\": 1\n },\n {\n \"type\": \"string\",\n \"const\": \"all\"\n },\n {\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n ]\n },\n \"select\": {\n \"description\": \"When max ≠ 1: which match to surface. \\\"first\\\" (default), \\\"last\\\", \\\"min\\\", \\\"max\\\", or \\\"all\\\" — `all` returns the full array of matches AND a parallel array of evidence entries.\",\n \"type\": \"string\",\n \"enum\": [\n \"first\",\n \"last\",\n \"min\",\n \"max\",\n \"all\"\n ]\n },\n \"normalize\": {\n \"type\": \"string\",\n \"enum\": [\n \"strip-spaces\",\n \"strip-punct\",\n \"collapse-whitespace\",\n \"lower\",\n \"upper\",\n \"trim\"\n ]\n },\n \"format\": {\n \"description\": \"Post-processing. iso-date accepts DD.MM.YYYY (1 group) or DD/MM/YYYY split across 3 groups → \\\"YYYY-MM-DD\\\".\",\n \"type\": \"string\",\n \"enum\": [\n \"iso-date\",\n \"iso-number\",\n \"lower\",\n \"upper\",\n \"trim\"\n ]\n },\n \"exclude\": {\n \"description\": \"Post-normalize values to skip (known wrong matches).\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"default\": {\n \"description\": \"Value when nothing matches.\",\n \"type\": \"string\"\n },\n \"contextChars\": {\n \"description\": \"When > 0, evidence entries gain `contextBefore` and `contextAfter` snippets of N characters surrounding the match. Useful for UI/debug display.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 2000\n }\n },\n \"required\": [\n \"pattern\",\n \"max\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Named field → pattern mapping.\"\n },\n \"flags\": {\n \"description\": \"Default regex flags applied when a field omits its own `flags`. Subset of \\\"gimsuy\\\".\",\n \"type\": \"string\",\n \"pattern\": \"^(?!.*(.).*\\\\1)[gimsuy]*$\"\n },\n \"searchWindow\": {\n \"description\": \"Only search the first N characters of input (perf). Omit for full search.\",\n \"type\": \"integer\",\n \"minimum\": 100,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"fields\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Field name → extracted value (or default), plus `_evidence: { [field]: { pageIndex, matchOffset, raw } }` and `_unmatched: string[]`.\"\n}\n```\n\n\n#### `transform.archive-list` — List Archive\n\nList files inside a ZIP archive. Returns sorted normalized paths with compressed and uncompressed sizes. Optionally filter by folder prefix or substring, then page with offset and limit. ZIP is the only accepted format in this version. Pair with foreach or parallel_map and transform.archive-extract to open individual files.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/archive-list`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `archive` | string | yes | | Template expression or file reference for the ZIP archive to list. ZIP is the only accepted format in this version. |\n| `prefix` | string | no | | Optional folder prefix inside the archive after path normalization (for example invoices or invoices/). |\n| `search` | string | no | | Optional case-insensitive substring match on the normalized archive path. |\n| `offset` | integer | no | | Number of matching entries to skip after sorting. Default 0. |\n| `limit` | integer | no | | Maximum matching entries to return after sorting. Capped at 10000. Omit to return every matching entry up to that cap. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `entries` | array<object> | yes | | Matching files, sorted by normalized path. Directories and junk paths are omitted. |\n| `total` | integer | yes | | Number of matching entries before offset/limit pagination. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"archive\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression or file reference for the ZIP archive to list. ZIP is the only accepted format in this version.\"\n },\n \"prefix\": {\n \"description\": \"Optional folder prefix inside the archive after path normalization (for example invoices or invoices/).\",\n \"type\": \"string\"\n },\n \"search\": {\n \"description\": \"Optional case-insensitive substring match on the normalized archive path.\",\n \"type\": \"string\"\n },\n \"offset\": {\n \"description\": \"Number of matching entries to skip after sorting. Default 0.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"limit\": {\n \"description\": \"Maximum matching entries to return after sorting. Capped at 10000. Omit to return every matching entry up to that cap.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 10000\n }\n },\n \"required\": [\n \"archive\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"entries\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Normalized archive-relative path\"\n },\n \"compressedSize\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Declared compressed size in bytes\"\n },\n \"uncompressedSize\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Declared uncompressed size in bytes\"\n }\n },\n \"required\": [\n \"path\",\n \"compressedSize\",\n \"uncompressedSize\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Matching files, sorted by normalized path. Directories and junk paths are omitted.\"\n },\n \"total\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of matching entries before offset/limit pagination.\"\n }\n },\n \"required\": [\n \"entries\",\n \"total\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.archive-extract` — Extract Archive File\n\nExtract exactly one file from a ZIP archive and store it as a run output file. Downstream steps can pass {{ steps.extract.output }} into Parse, Vision, or another archive step. Nested ZIPs are stored as ZIP files, not unpacked. Each extraction is capped at 64 MiB. ZIP is the only accepted format in this version.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/archive-extract`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `archive` | string | yes | | Template expression or file reference for the ZIP archive. ZIP is the only accepted format in this version. |\n| `path` | string | yes | | Archive-relative path of the single file to extract, for example {{ item.path }} from a prior archive-list step. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from the files table |\n| `path` | string | yes | | Normalized archive-relative path that was extracted |\n| `filename` | string | yes | | Basename of the extracted file |\n| `mimeType` | string | yes | | Detected MIME type of the extracted file |\n| `size` | integer | yes | | Uncompressed size in bytes |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"archive\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression or file reference for the ZIP archive. ZIP is the only accepted format in this version.\"\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Archive-relative path of the single file to extract, for example {{ item.path }} from a prior archive-list step.\"\n }\n },\n \"required\": [\n \"archive\",\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from the files table\"\n },\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Normalized archive-relative path that was extracted\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Basename of the extracted file\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"description\": \"Detected MIME type of the extracted file\"\n },\n \"size\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Uncompressed size in bytes\"\n }\n },\n \"required\": [\n \"fileId\",\n \"path\",\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.merge-documents` — Merge Documents\n\nConcatenate several files into one PDF run output, in order. Accepts PDFs, images (multi-page TIFF included) and Word, PowerPoint, OpenDocument or RTF documents. Use it when one logical document arrives as several uploads: pass {{ steps.merge.output.file }} into Parse so page labels, page ranges and vision page indices stay continuous across every source. Output sources[] maps each input file to its merged page range.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/merge-documents`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `files` | string | yes | | Template expression resolving to the files to merge, in order: a file list input such as {{ input.documents }}, or a single file. PDF, images (JPEG, PNG, TIFF, WebP, GIF) and Word, PowerPoint, OpenDocument or RTF documents. |\n| `filename` | string | no | | Filename of the merged PDF. Defaults to merged.pdf; .pdf is appended when missing. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `file` | object | yes | | The merged PDF. Pass {{ steps.<step>.output.file }} to Parse, Vision or any other file input. |\n| `pageCount` | integer | yes | | Total pages in the merged PDF |\n| `sources` | array<object> | yes | | One entry per input file, in merge order, with the merged page range it occupies. Use it to map a merged page index back to its source file. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"files\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to the files to merge, in order: a file list input such as {{ input.documents }}, or a single file. PDF, images (JPEG, PNG, TIFF, WebP, GIF) and Word, PowerPoint, OpenDocument or RTF documents.\"\n },\n \"filename\": {\n \"description\": \"Filename of the merged PDF. Defaults to merged.pdf; .pdf is appended when missing.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"files\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"file\": {\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID of the merged PDF\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Filename of the merged PDF\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"description\": \"Always application/pdf\"\n },\n \"size\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Size of the merged PDF in bytes\"\n }\n },\n \"required\": [\n \"fileId\",\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false,\n \"description\": \"The merged PDF. Pass {{ steps.<step>.output.file }} to Parse, Vision or any other file input.\"\n },\n \"pageCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Total pages in the merged PDF\"\n },\n \"sources\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Filename of the source file\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"description\": \"MIME type of the source file\"\n },\n \"pageCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Pages this source contributed\"\n },\n \"pageRange\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices in the merged PDF\"\n }\n },\n \"required\": [\n \"filename\",\n \"mimeType\",\n \"pageCount\",\n \"pageRange\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"One entry per input file, in merge order, with the merged page range it occupies. Use it to map a merged page index back to its source file.\"\n }\n },\n \"required\": [\n \"file\",\n \"pageCount\",\n \"sources\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n### Action steps — external side effects\n\n#### `action.http` — HTTP Request\n\nMake an HTTP request to an external API\n\n**Behavior and examples:** `eigenpal docs read steps/action/http`\n\n**Durable retry:** HTTP `GET` and `HEAD` can durably retry transient timeout, rate limits, selected retryable server failures failures. Other methods are not replayed.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `url` | string | yes | | Request URL (supports template expressions) |\n| `method` | `\"GET\"` \\| `\"HEAD\"` \\| `\"POST\"` \\| `\"PUT\"` \\| `\"PATCH\"` \\| `\"DELETE\"` | no | `\"GET\"` | |\n| `headers` | record<string, string> | no | | HTTP headers |\n| `body` | unknown | no | | Request body (JSON or string) |\n| `timeout` | number | no | `30000` | Timeout in milliseconds |\n| `insecureSkipTlsVerify` | boolean | no | `false` | If true, skip TLS certificate verification (use only for read-only public endpoints with bad/expired certs) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `status` | number | yes | | HTTP status code |\n| `statusText` | string | yes | | |\n| `headers` | record<string, string> | yes | | |\n| `body` | unknown | yes | | Response body (parsed JSON or string) |\n| `responseCharset` | string | yes | | Charset used to decode the response body (e.g. utf-8, windows-1250) |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Request URL (supports template expressions)\"\n },\n \"method\": {\n \"default\": \"GET\",\n \"type\": \"string\",\n \"enum\": [\n \"GET\",\n \"HEAD\",\n \"POST\",\n \"PUT\",\n \"PATCH\",\n \"DELETE\"\n ]\n },\n \"headers\": {\n \"description\": \"HTTP headers\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"body\": {\n \"description\": \"Request body (JSON or string)\"\n },\n \"timeout\": {\n \"description\": \"Timeout in milliseconds\",\n \"default\": 30000,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n },\n \"insecureSkipTlsVerify\": {\n \"description\": \"If true, skip TLS certificate verification (use only for read-only public endpoints with bad/expired certs)\",\n \"default\": false,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"number\",\n \"description\": \"HTTP status code\"\n },\n \"statusText\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"body\": {\n \"description\": \"Response body (parsed JSON or string)\"\n },\n \"responseCharset\": {\n \"type\": \"string\",\n \"description\": \"Charset used to decode the response body (e.g. utf-8, windows-1250)\"\n }\n },\n \"required\": [\n \"status\",\n \"statusText\",\n \"headers\",\n \"body\",\n \"responseCharset\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `action.invoke-workflow` — Invoke Workflow\n\nExecute another workflow and return its output\n\n**Behavior and examples:** `eigenpal docs read steps/action/invoke-workflow`\n\n**Durable retry:** Invoked workflows are not replayed as durable leaf attempts.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `tags` | string \\| array<string> | no | | Child mode only. One tag or a list. Supports templates resolving to a string or string array. Tags are not inherited. |\n| `workflow` | string | no | | Workflow to invoke — definition name or wf_ id (tenant-scoped) |\n| `workflowId` | string | no | | Legacy alias for workflow when the value is a wf_ id |\n| `execution` | `\"inline\"` \\| `\"child\"` | no | | inline: run target steps in this execution (default). child: spawn a separate run with lineage. |\n| `input` | record<string, unknown> | no | | Input record keyed by the invoked workflow's declared inputs |\n| `wait` | boolean | no | | Child mode only. Wait for the invoked workflow to complete and return its output (default: true). Set false for fire-and-forget. |\n| `timeout` | number | no | | Child mode only. Max wait time in ms while the child is queued or running (default: 300000). The deadline is stored with the invocation and survives worker restarts; expiry makes the parent eligible to resume and report the timeout. Once the child pauses for human review, the parent pauses durably instead of using this timeout. |\n| `pollInterval` | number | no | | Child mode only. Accepted for compatibility. Durable child waits no longer poll or occupy a worker slot. |\n\n**Output:** `record<string, unknown>`\n\n> 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`.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"tags\": {\n \"description\": \"Child mode only. One tag or a list. Supports templates resolving to a string or string array. Tags are not inherited.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"maxItems\": 100,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n },\n \"workflow\": {\n \"description\": \"Workflow to invoke — definition name or wf_ id (tenant-scoped)\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"workflowId\": {\n \"description\": \"Legacy alias for workflow when the value is a wf_ id\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"execution\": {\n \"description\": \"inline: run target steps in this execution (default). child: spawn a separate run with lineage.\",\n \"type\": \"string\",\n \"enum\": [\n \"inline\",\n \"child\"\n ]\n },\n \"input\": {\n \"description\": \"Input record keyed by the invoked workflow's declared inputs\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"wait\": {\n \"description\": \"Child mode only. Wait for the invoked workflow to complete and return its output (default: true). Set false for fire-and-forget.\",\n \"type\": \"boolean\"\n },\n \"timeout\": {\n \"description\": \"Child mode only. Max wait time in ms while the child is queued or running (default: 300000). The deadline is stored with the invocation and survives worker restarts; expiry makes the parent eligible to resume and report the timeout. Once the child pauses for human review, the parent pauses durably instead of using this timeout.\",\n \"type\": \"number\"\n },\n \"pollInterval\": {\n \"description\": \"Child mode only. Accepted for compatibility. Durable child waits no longer poll or occupy a worker slot.\",\n \"type\": \"number\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"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`.\"\n}\n```\n\n\n#### `action.website-reader` — Website Reader\n\nFetch a webpage and convert content to markdown\n\n**Behavior and examples:** `eigenpal docs read steps/action/website-reader`\n\n**Durable retry:** Supported for transient timeout, rate limits, selected retryable server failures failures.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `url` | string | yes | | Website URL to fetch (supports template expressions) |\n| `timeout` | number | no | `30000` | Timeout in milliseconds |\n| `encoding` | `\"auto\"` \\| `\"utf-8\"` \\| `\"latin1\"` \\| `\"windows-1250\"` \\| `\"windows-1252\"` \\| `\"iso-8859-2\"` | no | `\"auto\"` | Response encoding. Auto detects from Content-Type header and HTML meta tags. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `markdown` | string | yes | | Page content converted to markdown |\n| `title` | string \\| null | yes | | Page title |\n| `excerpt` | string \\| null | yes | | Page excerpt/description |\n| `byline` | string \\| null | yes | | Author information |\n| `siteName` | string \\| null | yes | | Site name |\n| `length` | number | yes | | Content length in characters |\n| `url` | string | yes | | Final URL after redirects |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Website URL to fetch (supports template expressions)\"\n },\n \"timeout\": {\n \"description\": \"Timeout in milliseconds\",\n \"default\": 30000,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n },\n \"encoding\": {\n \"description\": \"Response encoding. Auto detects from Content-Type header and HTML meta tags.\",\n \"default\": \"auto\",\n \"type\": \"string\",\n \"enum\": [\n \"auto\",\n \"utf-8\",\n \"latin1\",\n \"windows-1250\",\n \"windows-1252\",\n \"iso-8859-2\"\n ]\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"markdown\": {\n \"type\": \"string\",\n \"description\": \"Page content converted to markdown\"\n },\n \"title\": {\n \"description\": \"Page title\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"excerpt\": {\n \"description\": \"Page excerpt/description\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"byline\": {\n \"description\": \"Author information\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"siteName\": {\n \"description\": \"Site name\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"length\": {\n \"type\": \"number\",\n \"description\": \"Content length in characters\"\n },\n \"url\": {\n \"type\": \"string\",\n \"description\": \"Final URL after redirects\"\n }\n },\n \"required\": [\n \"markdown\",\n \"title\",\n \"excerpt\",\n \"byline\",\n \"siteName\",\n \"length\",\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `action.email` — Send Email\n\nSend an email with optional attachments via a selected email server. At most 10 recipients combined across to, cc, and bcc.\n\n**Behavior and examples:** `eigenpal docs read steps/action/email`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `server` | string | yes | | Outbound email server id (`ems_…`) |\n| `to` | string \\| array<string> | yes | | Primary recipient(s). String, comma-separated list, or nonempty string array. Combined with cc and bcc, at most 10 recipients. |\n| `cc` | string \\| array<string> | no | | Carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and bcc, at most 10 recipients. |\n| `bcc` | string \\| array<string> | no | | Blind carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and cc, at most 10 recipients. |\n| `replyTo` | string | no | | Reply-To address (supports template expressions) |\n| `subject` | string | yes | | Email subject |\n| `text` | string | yes | | Plain-text email body (max 50KiB) |\n| `attachments` | array<string \\| object> | no | | Optional same-run attachments as { fileId, filename? } or a bare fileId string (12MiB combined) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `serverId` | string | yes | | Email server that sent (or would have sent) the message |\n| `messageId` | string \\| null | yes | | Provider message id. Null when delivery was skipped (evaluation runs). |\n| `provider` | `\"resend\"` \\| `\"smtp\"` \\| null | yes | | Email provider that sent the message. Null when delivery was skipped. |\n| `to` | array<string> | yes | | Normalized To recipients |\n| `cc` | array<string> | yes | | Normalized Cc recipients |\n| `bcc` | array<string> | yes | | Normalized Bcc recipients |\n| `attachmentCount` | integer | yes | | Number of attachments sent |\n| `totalBytes` | integer | yes | | Total attachment size in bytes |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"server\": {\n \"type\": \"string\",\n \"maxLength\": 128,\n \"pattern\": \"^ems_[A-Za-z0-9_-]+$\",\n \"description\": \"Outbound email server id (`ems_…`)\"\n },\n \"to\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ],\n \"description\": \"Primary recipient(s). String, comma-separated list, or nonempty string array. Combined with cc and bcc, at most 10 recipients.\"\n },\n \"cc\": {\n \"description\": \"Carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and bcc, at most 10 recipients.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n },\n \"bcc\": {\n \"description\": \"Blind carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and cc, at most 10 recipients.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n },\n \"replyTo\": {\n \"description\": \"Reply-To address (supports template expressions)\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"subject\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Email subject\"\n },\n \"text\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Plain-text email body (max 50KiB)\"\n },\n \"attachments\": {\n \"description\": \"Optional same-run attachments as { fileId, filename? } or a bare fileId string (12MiB combined)\",\n \"maxItems\": 10,\n \"type\": \"array\",\n \"items\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File id or template expression that resolves to a file id\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File id or template expression that resolves to a file id\"\n },\n \"filename\": {\n \"description\": \"Optional download filename override\",\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"fileId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n }\n },\n \"required\": [\n \"server\",\n \"to\",\n \"subject\",\n \"text\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"serverId\": {\n \"type\": \"string\",\n \"maxLength\": 128,\n \"pattern\": \"^ems_[A-Za-z0-9_-]+$\",\n \"description\": \"Email server that sent (or would have sent) the message\"\n },\n \"messageId\": {\n \"description\": \"Provider message id. Null when delivery was skipped (evaluation runs).\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"provider\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"enum\": [\n \"resend\",\n \"smtp\"\n ]\n },\n {\n \"type\": \"null\"\n }\n ],\n \"description\": \"Email provider that sent the message. Null when delivery was skipped.\"\n },\n \"to\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Normalized To recipients\"\n },\n \"cc\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Normalized Cc recipients\"\n },\n \"bcc\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Normalized Bcc recipients\"\n },\n \"attachmentCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of attachments sent\"\n },\n \"totalBytes\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Total attachment size in bytes\"\n }\n },\n \"required\": [\n \"serverId\",\n \"messageId\",\n \"provider\",\n \"to\",\n \"cc\",\n \"bcc\",\n \"attachmentCount\",\n \"totalBytes\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n### Control steps — flow control\n\n#### `control.if` — Condition\n\nBranch execution based on a condition expression\n\n**Behavior and examples:** `eigenpal docs read steps/control/if`\n\n**Durable retry:** The control container itself is not retried, but eligible leaves inside its sequential scope may retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `condition` | string | yes | | LiquidJS expression that evaluates to boolean |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `condition` | boolean | yes | | Evaluated condition result |\n| `branch` | `\"then\"` \\| `\"else\"` | yes | | Which branch was executed |\n| `result` | unknown | yes | | Output from executed branch |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"condition\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"LiquidJS expression that evaluates to boolean\"\n }\n },\n \"required\": [\n \"condition\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"condition\": {\n \"type\": \"boolean\",\n \"description\": \"Evaluated condition result\"\n },\n \"branch\": {\n \"type\": \"string\",\n \"enum\": [\n \"then\",\n \"else\"\n ],\n \"description\": \"Which branch was executed\"\n },\n \"result\": {\n \"description\": \"Output from executed branch\"\n }\n },\n \"required\": [\n \"condition\",\n \"branch\",\n \"result\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.switch` — Switch\n\nMulti-way routing: resolve an expression and run the first case whose value matches (else default). Cleaner than a nested control.if chain for routing an item to one of N pipelines by a discriminator field like a document type.\n\n**Behavior and examples:** `eigenpal docs read steps/control/switch`\n\n**Durable retry:** The control container itself is not retried, but eligible leaves inside its sequential scope may retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `on` | string | yes | | Template expression whose resolved value selects the case, e.g. \"{{ doc.type }}\". |\n| `cases` | array<object> | yes | | Ordered cases; the first whose `when` matches runs. Each case has its own `steps`. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `matched` | string \\| number \\| boolean \\| null | yes | | The `when` value that matched, or null when the default (or no) branch ran. |\n| `branch` | `\"case\"` \\| `\"default\"` \\| `\"none\"` | yes | | Which branch executed. |\n| `result` | unknown | yes | | Output from the executed branch (its last step). |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"on\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression whose resolved value selects the case, e.g. \\\"{{ doc.type }}\\\".\"\n },\n \"cases\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"when\": {\n \"description\": \"Value matched (string-compared) against the resolved `on` value.\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\"\n ]\n }\n },\n \"required\": [\n \"when\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Ordered cases; the first whose `when` matches runs. Each case has its own `steps`.\"\n }\n },\n \"required\": [\n \"on\",\n \"cases\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"matched\": {\n \"description\": \"The `when` value that matched, or null when the default (or no) branch ran.\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"branch\": {\n \"type\": \"string\",\n \"enum\": [\n \"case\",\n \"default\",\n \"none\"\n ],\n \"description\": \"Which branch executed.\"\n },\n \"result\": {\n \"description\": \"Output from the executed branch (its last step).\"\n }\n },\n \"required\": [\n \"matched\",\n \"branch\",\n \"result\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.foreach` — For Each\n\nLoop over an array and execute steps for each item\n\n**Behavior and examples:** `eigenpal docs read steps/control/foreach`\n\n**Durable retry:** The control container itself is not retried, but eligible leaves inside its sequential scope may retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | string | yes | | Expression resolving to array |\n| `as` | string | yes | | Variable name for current item |\n| `indexAs` | string | no | | Variable name for current index |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | array<unknown> | yes | | Results from each iteration |\n| `count` | number | yes | | Number of completed iterations |\n| `totalIterations` | number | yes | | Total iterations |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Expression resolving to array\"\n },\n \"as\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Variable name for current item\"\n },\n \"indexAs\": {\n \"description\": \"Variable name for current index\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"items\",\n \"as\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"array\",\n \"items\": {},\n \"description\": \"Results from each iteration\"\n },\n \"count\": {\n \"type\": \"number\",\n \"description\": \"Number of completed iterations\"\n },\n \"totalIterations\": {\n \"type\": \"number\",\n \"description\": \"Total iterations\"\n }\n },\n \"required\": [\n \"items\",\n \"count\",\n \"totalIterations\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.parallel_map` — Parallel Map\n\nIterate over an array with concurrent execution up to a limit\n\n**Behavior and examples:** `eigenpal docs read steps/control/parallel_map`\n\n**Durable retry:** The control container and leaves inside its concurrent branches do not retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | string | yes | | Expression resolving to array |\n| `as` | string | yes | | Variable name for current item |\n| `indexAs` | string | no | | Variable name for current index |\n| `concurrency` | integer | no | `5` | Maximum concurrent executions (1-50, default 5) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | array<unknown> | yes | | Results from each iteration (maintains original order) |\n| `count` | number | yes | | Number of completed iterations |\n| `totalIterations` | number | yes | | Total iterations |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Expression resolving to array\"\n },\n \"as\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Variable name for current item\"\n },\n \"indexAs\": {\n \"description\": \"Variable name for current index\",\n \"type\": \"string\"\n },\n \"concurrency\": {\n \"description\": \"Maximum concurrent executions (1-50, default 5)\",\n \"default\": 5,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 50\n }\n },\n \"required\": [\n \"items\",\n \"as\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"array\",\n \"items\": {},\n \"description\": \"Results from each iteration (maintains original order)\"\n },\n \"count\": {\n \"type\": \"number\",\n \"description\": \"Number of completed iterations\"\n },\n \"totalIterations\": {\n \"type\": \"number\",\n \"description\": \"Total iterations\"\n }\n },\n \"required\": [\n \"items\",\n \"count\",\n \"totalIterations\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.parallel` — Parallel\n\nExecute multiple branches concurrently\n\n**Behavior and examples:** `eigenpal docs read steps/control/parallel`\n\n**Durable retry:** The control container and leaves inside its concurrent branches do not retry durably.\n\n**Config** (at step level):\n\n_No fields._\n\n**Output:** `record<string, unknown>`\n\n> Results keyed by branch name\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Results keyed by branch name\"\n}\n```\n\n\n#### `control.wait` — Wait\n\nPause workflow execution for a specified duration\n\n**Behavior and examples:** `eigenpal docs read steps/control/wait`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `duration` | number | yes | | Duration in milliseconds |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `waited` | number | yes | | Actual milliseconds waited |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"duration\": {\n \"type\": \"number\",\n \"exclusiveMinimum\": 0,\n \"description\": \"Duration in milliseconds\"\n }\n },\n \"required\": [\n \"duration\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"waited\": {\n \"type\": \"number\",\n \"description\": \"Actual milliseconds waited\"\n }\n },\n \"required\": [\n \"waited\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.human_review` — Human Review\n\nPause the run for selective field confirmation or correction, then continue with the reviewed data.\n\n**Behavior and examples:** `eigenpal docs read steps/control/human_review`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `data` | string \\| record<string, unknown> \\| array<unknown> | yes | | Structured data or a template expression resolving to an object or array |\n| `schema` | record<string, unknown> | no | | Optional JSON Schema for validating edits and exposing downstream autocomplete. When omitted with metadataFrom: ai.extract and a direct whole-output data expression, the extract step schema is reused. |\n| `metadataFrom` | `\"ai.extract\"` | no | | Producer adapter. `ai.extract` derives categorical field confidence from `_grounding`, copies valid numeric grounding scores into fieldMetadata.display.score, and strips that reserved key from review data. Grounding is not stripped unless this is set. |\n| `fieldMetadata` | record<string, object> | no | `{}` | RFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias. |\n| `selection` | object | yes | | Field selection policy resolved once when the task is created |\n| `files` | object | no | `{\"includeRunInputs\":true,\"attachments\":[]}` | Run input files and optional current-run attachments for reviewers |\n| `instructions` | string | no | | Free-form guidance shown above the review workspace |\n\n**Output:** `unknown`\n\n> The complete reviewed data in the same object or array shape as the input.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n {\n \"type\": \"array\",\n \"items\": {}\n }\n ],\n \"description\": \"Structured data or a template expression resolving to an object or array\"\n },\n \"schema\": {\n \"description\": \"Optional JSON Schema for validating edits and exposing downstream autocomplete. When omitted with metadataFrom: ai.extract and a direct whole-output data expression, the extract step schema is reused.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"metadataFrom\": {\n \"type\": \"string\",\n \"enum\": [\n \"ai.extract\"\n ],\n \"description\": \"Producer adapter. `ai.extract` derives categorical field confidence from `_grounding`, copies valid numeric grounding scores into fieldMetadata.display.score, and strips that reserved key from review data. Grounding is not stripped unless this is set.\"\n },\n \"fieldMetadata\": {\n \"description\": \"RFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias.\",\n \"default\": {},\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"confidence\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n },\n \"label\": {\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"description\": {\n \"type\": \"string\",\n \"maxLength\": 5000\n },\n \"review\": {\n \"default\": \"auto\",\n \"type\": \"string\",\n \"enum\": [\n \"auto\",\n \"always\",\n \"never\"\n ]\n },\n \"display\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"additionalProperties\": false\n }\n },\n \"selection\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"description\": \"RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"exclude\": {\n \"description\": \"RFC 6901 pointers removed after include expansion\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"fields\": {\n \"description\": \"Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"maxLength\": 512\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"review\": {\n \"type\": \"string\",\n \"enum\": [\n \"always\",\n \"never\",\n \"skip\"\n ]\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n }\n },\n \"additionalProperties\": false\n }\n },\n \"mode\": {\n \"type\": \"string\",\n \"const\": \"confidence\",\n \"description\": \"Review fields below threshold or missing confidence\"\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ],\n \"description\": \"Fields with confidence strictly below this value require review. Equality auto-approves. Numeric 0–1 or categorical low|medium|high. Template strings are resolved at runtime.\"\n },\n \"missingConfidence\": {\n \"description\": \"Whether unscored or type-mismatched fields require review (default review)\",\n \"default\": \"review\",\n \"type\": \"string\",\n \"enum\": [\n \"review\",\n \"skip\"\n ]\n }\n },\n \"required\": [\n \"mode\",\n \"threshold\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"description\": \"RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"exclude\": {\n \"description\": \"RFC 6901 pointers removed after include expansion\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"fields\": {\n \"description\": \"Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"maxLength\": 512\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"review\": {\n \"type\": \"string\",\n \"enum\": [\n \"always\",\n \"never\",\n \"skip\"\n ]\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n }\n },\n \"additionalProperties\": false\n }\n },\n \"mode\": {\n \"type\": \"string\",\n \"const\": \"explicit\",\n \"description\": \"Review only paths matched by include/exclude\"\n }\n },\n \"required\": [\n \"mode\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"description\": \"RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"exclude\": {\n \"description\": \"RFC 6901 pointers removed after include expansion\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"fields\": {\n \"description\": \"Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"maxLength\": 512\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"review\": {\n \"type\": \"string\",\n \"enum\": [\n \"always\",\n \"never\",\n \"skip\"\n ]\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n }\n },\n \"additionalProperties\": false\n }\n },\n \"mode\": {\n \"type\": \"string\",\n \"const\": \"all\",\n \"description\": \"Review every scalar leaf unless excluded or review: never\"\n }\n },\n \"required\": [\n \"mode\"\n ],\n \"additionalProperties\": false\n }\n ],\n \"description\": \"Field selection policy resolved once when the task is created\"\n },\n \"files\": {\n \"description\": \"Run input files and optional current-run attachments for reviewers\",\n \"default\": {\n \"includeRunInputs\": true,\n \"attachments\": []\n },\n \"type\": \"object\",\n \"properties\": {\n \"includeRunInputs\": {\n \"description\": \"Attach every authorized run input file to the review task\",\n \"default\": true,\n \"type\": \"boolean\"\n },\n \"attachments\": {\n \"description\": \"Additional current-run file or artifact template expressions\",\n \"default\": [],\n \"maxItems\": 100,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n },\n \"additionalProperties\": false\n },\n \"instructions\": {\n \"description\": \"Free-form guidance shown above the review workspace\",\n \"type\": \"string\",\n \"maxLength\": 10000\n }\n },\n \"required\": [\n \"data\",\n \"selection\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"description\": \"The complete reviewed data in the same object or array shape as the input.\"\n}\n```\n\n\n#### `control.fail` — Fail\n\nTerminate the workflow with a typed status code + message. With an optional condition, only fails when the condition is truthy; otherwise always fails when reached. Pair with ai.classify or any prior step to fail fast on bad inputs.\n\n**Behavior and examples:** `eigenpal docs read steps/control/fail`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `condition` | string | no | | Optional LiquidJS expression. When set, the step only fails if this evaluates truthy; when omitted, it always fails when reached (compose with control.if for legacy gating). |\n| `statusCode` | integer | no | `422` | Business rejection code exposed as error.statusCode on the run. Does not change the API HTTP response status. Default 422 (Unprocessable Entity). |\n| `message` | string | yes | | Human-readable failure message. Supports template expressions, e.g. \"Document classified as {{ steps.classify.output.label }}\". |\n\n**Output:** `unknown`\n\n> control.fail never produces output — it terminates the workflow when triggered.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"condition\": {\n \"description\": \"Optional LiquidJS expression. When set, the step only fails if this evaluates truthy; when omitted, it always fails when reached (compose with control.if for legacy gating).\",\n \"type\": \"string\"\n },\n \"statusCode\": {\n \"default\": 422,\n \"description\": \"Business rejection code exposed as error.statusCode on the run. Does not change the API HTTP response status. Default 422 (Unprocessable Entity).\",\n \"type\": \"integer\",\n \"minimum\": 400,\n \"maximum\": 599\n },\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Human-readable failure message. Supports template expressions, e.g. \\\"Document classified as {{ steps.classify.output.label }}\\\".\"\n }\n },\n \"required\": [\n \"statusCode\",\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"not\": {},\n \"description\": \"control.fail never produces output — it terminates the workflow when triggered.\"\n}\n```\n<!-- GENERATED:STEP_CATALOG END -->\n"
457
+ "content": "# Step types\n\nThe catalog is generated from `STEP_SCHEMAS` in\n`@eigenpal/types/src/workflow/step-configs.ts`. **Do not memorize fields\n— introspect.** The CLI reads the live schema:\n\n```bash\n# List every step type with a one-line description\neigenpal workflow step-type list\n\n# Filter by keyword\neigenpal workflow step-type list --search extract\n\n# Full JSON Schema for one type's `config` + `output` + behavioral docs\neigenpal workflow step-type get ai.extract\n```\n\nThe output of `step-type get` is the **authoritative source** for which\nfields each step takes, what shapes they accept, and what behavior they\nimplement at runtime. Server-side validation errors point you here.\n\n## Categories (high-level map)\n\n- `ai.*` — model-backed processing (parse, extract, classify). Cost + latency depend on the model.\n- `transform.*` — deterministic data transforms (set, remove, combine, split, merge,\n script, template, pdf-embed, xlsx-to-json, json-to-xlsx). WASM sandboxed where applicable.\n- `action.*` — external side effects (HTTP, invoke another workflow, website reader).\n- `control.*` — flow control (if, foreach, parallel, parallel_map, wait, human_review, fail).\n\nThe full per-type catalog with field tables is auto-generated below from\n`STEP_SCHEMAS`. The high-level map above tells you which family you want;\nthe catalog tells you what fields it takes.\n\n## When to reach for what\n\n| Use case | Step |\n| --------------------------------- | ------------------------------------------------- |\n| Read a PDF / DOCX / image | `ai.parse-v2` with defaults (automatic native/OCR/vision) |\n| Restrict document reading | `ai.parse-v2` with `policy.native` and `policy.imageReading.order` |\n| Pull a typed object from text | `ai.extract` with `config.schema` |\n| Pick one label from a fixed set | `ai.classify` with `config.labels` |\n| Reject bad inputs with a 4xx code | `control.fail` (often after `ai.classify`) |\n| Pause for human field review | `control.human_review` (top-level only; see below) |\n| Sum / filter / regex | `transform.script` (NOT Liquid) |\n| Render a DOCX or XLSX template (YAML workflow) | `transform.template` with `tmpl_...` or `./file.xlsx` |\n| Fill a DOCX or XLSX template (runtime agent) | fill-template platform skill |\n| Convert XLSX to JSON | `transform.xlsx-to-json` |\n| Convert JSON rows to XLSX | `transform.json-to-xlsx` |\n| Merge or combine objects | `transform.combine` / `transform.merge` |\n| Conditional execution | `if:` on the step (Liquid) or `control.if` |\n| Map over an input array | `forEach:` on the step or `control.foreach` |\n| Concurrent map over an array | `control.parallel_map` |\n| Independent parallel branches | `control.parallel` |\n| External HTTP call | `action.http` |\n| Call another workflow | `action.invoke-workflow` |\n| Fetch a webpage as markdown | `action.website-reader` |\n\n## Workspace vs Git templates\n\nTwo separate template systems share DOCX/XLSX placeholder syntax but not\nreferences:\n\n| Goal | Mechanism |\n| --- | --- |\n| YAML workflow produces a filled DOCX/XLSX | `transform.template` with `templateId: tmpl_...` or `template: ./templates/foo.xlsx` (CLI push uploads) |\n| Runtime agent produces a filled DOCX/XLSX | fill-template platform skill against Git templates |\n\nGit templates (`agents/<agent>/templates/<slug>/`, shared\n`resources/templates/<slug>/`) never receive a `tmpl_...` ID and cannot be\nused in `transform.template`. Manage Git templates through the agent source\nloop — see the eigenpal skill's **Agent templates (Git source)** section.\n\nWorkspace templates are tenant-scoped `tmpl_...` resources with immutable\n`tmpr_...` revisions. Manage them from the CLI (preferred) or Studio:\n\n```bash\neigenpal workflow templates upload ./templates/roster.xlsx --json\neigenpal workflow templates list --json\neigenpal workflow templates get tmpl_... --json\neigenpal workflow templates smoke ./templates/roster.xlsx --data ./fixture.json --out ./filled.xlsx\neigenpal workflow validate ./workflow.yaml --online\neigenpal workflow push --file workflow.yaml\n```\n\nAuthor YAML with either a live id or a source-controlled path. Push uploads\nthe file (skipped when the SHA-256 still matches) and sends `templateId` +\ncurrent `templateRevisionId` to the server without rewriting the file on disk.\n\n`templateId` must be `tmpl_...` when not using a local path; file IDs\n(`file_...`) are rejected at validate/push.\n\nIn the Office file itself use `{placeholder}` and, for XLSX row expansion,\n`{table:array.prop}`. `{{placeholder}}` is Liquid for YAML `data` mapping\nonly — putting it in an XLSX file fails at fill. Example prototype row:\n\n```yaml\n- name: fill-roster\n type: transform.template\n with:\n templateId: tmpl_...\n data:\n report_title: \"{{ steps.extract.output.title }}\"\n subjects: \"{{ steps.extract.output.subjects }}\"\n```\n\nSpreadsheet cells: `{report_title}`, `{table:subjects.first_name}`,\n`{table:subjects.last_name}`. Null/blank cells stay empty; numbers and\nbooleans keep spreadsheet types; every sheet is filled; existing formulas\nstay formulas.\n\n## Liquid vs `transform.script`\n\n| Logic shape | Use |\n| -------------------------- | -------------------------------- |\n| `steps.x.output.field` | Liquid `{{ ... }}` |\n| `value \\| default: 0` | Liquid |\n| `price \\| times: quantity` | Liquid |\n| array `reduce` / `filter` | `transform.script` |\n| multi-step calc | `transform.script` |\n| conditional branches | `transform.script` or `if:` |\n| date arithmetic | `transform.script` |\n| regex | `transform.script` |\n\n`transform.script` advantages over Liquid:\n\n- Explicit `inputs:` declaration; the validator knows the data deps\n- Typed return annotation drives downstream autocomplete + runtime validation\n- Real JS/TS (`Array.prototype.reduce`, `JSON.parse`, etc.)\n- Sandbox limits prevent infinite loops from blowing up an execution\n\n> The function is **TypeScript**. Each `inputs:` key becomes a parameter\n> in declaration order: `inputs: { items, taxRate }` ⇒\n> `function script(items: ..., taxRate: ...): R { ... }`. The return-type\n> annotation `R` is **required** and IS this step's output schema; there\n> is no separate `outputSchema:` field. Describe what your function\n> actually returns: downstream steps reference its fields via\n> `{{ steps.<this>.output.<field> }}`, so a too-loose annotation (e.g.\n> `unknown`) makes those references unresolvable. The function must\n> `return` (or `throw`) a value.\n\n## Reference / output paths\n\nAfter a step runs, its output is reachable via\n`{{ steps.<name>.output.<field> }}`. The exact field set per type comes\nfrom `step-type get`'s `outputSchema`. Example for `ai.extract`:\n\n```bash\n$ eigenpal workflow step-type get ai.extract | jq '.outputSchema'\n{\n \"type\": \"object\",\n \"properties\": {\n \"extracted\": { /* matches the user-supplied config.schema */ },\n \"rawResponse\": { \"type\": \"string\" },\n \"tokensUsed\": { \"type\": \"number\" }\n }\n}\n```\n\nReference user-supplied schema fields the same way:\n`{{ steps.extract.output.extracted.invoiceNumber }}`.\n\n## Human review — top-level gate only\n\n`control.human_review` pauses the run until a reviewer confirms or corrects\nselected scalar fields, then resumes with the reviewed object or array. Place\nit as a **top-level sequential step** only — nested placement inside\n`control.if`, `control.foreach`, `control.parallel`, `control.parallel_map`, or\n`control.switch` is rejected at publish time.\n\nConfig lives in `step.with` (unlike most other `control.*` steps). Wire data\nfrom an upstream extract or transform, choose a selection mode, and attach run\nfiles for context:\n\n```yaml\n- name: review-invoice\n type: control.human_review\n with:\n data: '{{ steps.extract.output }}'\n metadataFrom: ai.extract\n instructions: Confirm vendor and total before posting.\n selection:\n mode: confidence\n threshold: medium\n missingConfidence: review\n fields:\n /vendor:\n review: always\n /total:\n threshold: high\n fieldMetadata:\n /vendor:\n label: Vendor name\n /total:\n label: Invoice total\n files:\n includeRunInputs: true\n attachments:\n - '{{ steps.render.output.files[0] }}'\n```\n\nWhen `metadataFrom: ai.extract` is set and `data` is the whole extract output\n(`{{ steps.<name>.output }}`), the step strips the reserved `_grounding` key,\nderives categorical confidence (`low`, `medium`, `high`) per field, and reuses\nthe extract schema when `schema` is omitted.\n\n**Selection:** three modes — `confidence` (review fields below threshold),\n`explicit` (review matched include/exclude paths), and `all` (every scalar\nleaf). Thresholds accept numeric `0`–`1` or categorical `low|medium|high`;\nequality auto-approves. Per-path overrides live under `selection.fields` with\n`review: always|never|skip` and optional per-field `threshold`. Prefer\n`selection.fields` over the legacy `fieldMetadata.review`.\n\n**Output:** the complete reviewed data in the same shape as `data`. Reference\ndownstream fields directly: `{{ steps.review-invoice.output.vendor }}`.\n\n**Evaluations:** evaluation runs always simulate review and never pause the\nrun. Use `meta.json` `review` fixtures to assert routing, reasons, and\nsimulated reviewer edits — see `reference/dataset-format.md`. Empty selection\ncontinues immediately without creating a task.\n\n**Limits:** 2 MiB review JSON, 10k scalar leaves, 1 MiB metadata, 2k required\nfields, 100 attachments.\n\nUse `eigenpal workflow step-type get control.human_review` for the full schema.\n\n## Control containers — nested step shape and scoping\n\n`control.parallel`, `control.parallel_map`, `control.foreach`, `control.if`,\nand inline `action.invoke-workflow` (`execution: inline`) contain nested steps. The auto-generated catalog below\ncannot render that shape, so the YAML form lives here. Same for the scoping\nrules — important because the runtime treats nested steps differently from\ntop-level ones, and getting the access path wrong silently returns\n`undefined` (no error).\n\n### `control.parallel` — independent branches\n\nRuns each branch concurrently. Use when several pieces of work share input\nbut do not depend on each other.\n\n```yaml\n- name: enrich\n type: control.parallel\n branches:\n - name: legal\n steps:\n - name: extract-clauses\n type: ai.extract\n with:\n input: '{{ steps.parse.output.markdown }}'\n schema: { clauses: { type: array, items: { type: string } } }\n - name: financial\n steps:\n - name: extract-totals\n type: ai.extract\n with:\n input: '{{ steps.parse.output.markdown }}'\n schema: { total: { type: number } }\n```\n\n**Access the output:** branch step outputs are stored under the parent\nparallel step keyed by branch name, then by inner step name. There is no\nflat top-level entry for branch-internal steps.\n\n```liquid\n{{ steps.enrich.output.legal.extract-clauses.clauses }}\n{{ steps.enrich.output.financial.extract-totals.total }}\n```\n\n**Scope inside a branch:** top-level steps that ran before the parallel,\nplus earlier siblings in the same branch. **Other branches' steps are\nNOT visible** — each branch runs in an isolated child scope.\n\n```liquid\n# Inside branch `legal`, second step:\n{{ steps.parse.output.markdown }} # ancestor: visible\n{{ steps.extract-clauses.output.clauses }} # sibling: visible\n{{ steps.extract-totals.output.total }} # other branch: UNDEFINED\n```\n\n### `control.parallel_map` — fan-out over an array\n\nRuns the inner step block concurrently for each item, up to `concurrency`.\n\n```yaml\n- name: process-pages\n type: control.parallel_map\n items: '{{ steps.split.output.pages }}'\n as: page\n indexAs: i # optional\n concurrency: 5 # default 5, max 50\n steps:\n - name: extract-fields\n type: ai.extract\n with:\n input: '{{ page.text }}'\n schema: { fields: { type: object } }\n```\n\n**Access the output:** iteration results are returned as an array in the\noriginal input order under the parent step's `items` field.\n\n```liquid\n{{ steps.process-pages.output.items[0].extract-fields.fields }}\n{{ steps.process-pages.output.count }} # number of completed iterations\n{{ steps.process-pages.output.totalIterations }}\n```\n\n`steps.extract-fields.output.fields` (the flat form) is **not** addressable\nfrom outside the parallel_map.\n\n**Multi-step iterations only key the LAST step's output into `items[i]`.**\nIf your iteration body has steps `[parse, extract]`, each `items[i]` is\n`{ extract: <extract output> }` — `parse`'s output is gone. To preserve\nintermediate fields, end the body with a `transform.script` that returns\nthe combined shape:\n\n```yaml\nsteps:\n - name: parse\n type: ai.parse-v2\n with: { ... }\n - name: extract\n type: ai.extract\n with: { input: '{{ steps.parse.output.markdown }}', ... }\n - name: combine\n type: transform.script\n with:\n inputs:\n parsed: '{{ steps.parse.output }}'\n extracted: '{{ steps.extract.output }}'\n function: |\n function script(parsed, extracted): { parsed: any; extracted: any } {\n return { parsed, extracted };\n }\n```\n\nNow `items[i].combine.parsed` / `items[i].combine.extracted` both survive.\n\n### `control.foreach` — sequential loop over an array\n\nSame shape as `parallel_map` minus `concurrency`; iterations run in order.\nUse when each iteration depends on the previous, or when concurrency would\ncause downstream rate limits.\n\n```yaml\n- name: per-row\n type: control.foreach\n items: '{{ steps.fetch.output.rows }}'\n as: row\n steps:\n - name: persist\n type: action.http-request\n with:\n method: POST\n url: 'https://example.com/api/rows/{{ row.id }}'\n body: '{{ row }}'\n```\n\n**Access the output:** same shape as parallel_map — an `items[]` array of\nper-iteration results, in iteration order. Same \"only the LAST inner step\nis keyed into `items[i]`\" rule applies (use a trailing `transform.script`\nto preserve intermediate outputs).\n\n> ⚠️ Foreach does NOT isolate scopes — the last iteration's inner step\n> outputs technically persist on the top-level `steps` map and `steps.<inner>.output.x`\n> resolves at runtime. That is an only-the-last-row hazard; the autocomplete\n> hides these names and you should treat `steps.<foreach>.output.items[]`\n> as the only correct access.\n\n### `control.if` — conditional branch\n\n```yaml\n- name: route\n type: control.if\n condition: '{{ input.priority == \"high\" }}'\n then:\n - name: rush-extract\n type: ai.extract\n with: { ... }\n else:\n - name: normal-extract\n type: ai.extract\n with: { ... }\n```\n\n**Access the output:** the `if` step's output is\n\n```ts\n{\n condition: boolean, // evaluated condition\n branch: 'then' | 'else', // which branch ran\n result: <last inner step's output> | null // null when chosen branch is empty\n}\n```\n\nThe canonical way to consume the result is through the if step itself:\n\n```liquid\n{{ steps.route.output.branch }} # \"then\" or \"else\"\n{{ steps.route.output.result.foo }} # field from the branch's last step\n```\n\n`steps.<innerName>.output` references from outside the `if` also resolve\nat runtime (unlike `parallel`/`parallel_map`, `if` does not isolate\nscopes), but the template breaks the moment the OTHER branch runs. Use\n`steps.<if>.output.result` so the access is branch-agnostic — or compute\nthe final shape in a trailing `transform.script` that handles both cases.\n\n### `action.invoke-workflow` (inline) — call another workflow in the same run\n\n```yaml\n- name: invoice-flow\n type: action.invoke-workflow\n with:\n workflow: parse-invoice # target workflow name or wf_ id\n execution: inline # default; omit for same-run execution\n input:\n contract: '{{ input.contract }}'\n```\n\n**Access the output:** the target's declared output fields are exposed as\ntop-level keys under `steps.<this-step>.output`, with a `files` array alongside.\nInvoked workflow steps run in an isolated scope inside the parent run.\n\nFor a separate child run with lineage, set `execution: child`. Waiting for the\nchild releases worker capacity and resumes automatically when the child finishes.\nSet `wait: false` for fire-and-forget execution.\n\n## Classify-and-fail pattern\n\n`ai.classify` + `control.fail` together let a workflow reject bad inputs\nfast with a typed HTTP-style status code that callers (and evals) can\nmatch against. The classifier picks one label from a closed set; the\nfail step terminates the run when the label is one you do not want to\nprocess.\n\n```yaml\n- name: parse\n type: ai.parse-v2\n with:\n input: '{{ input.document }}'\n\n- name: classify\n type: ai.classify\n with:\n input: '{{ steps.parse.output.text }}'\n labels:\n - name: invoice\n description: A vendor invoice with line items and totals.\n - name: contract\n description: A multi-page contract or agreement.\n - name: other\n description: Anything that is not an invoice or contract.\n\n- name: reject-unsupported\n type: control.fail\n condition: '{{ steps.classify.output.label == \"other\" }}'\n statusCode: 422\n message: 'Unsupported document: {{ steps.classify.output.reason }}'\n```\n\n> `control.fail` config is step-level (no `with:`), matching every other\n> `control.*` step. `condition`, `statusCode`, and `message` sit directly\n> on the step node.\n\nThe synchronous run endpoint surfaces the `statusCode` as the HTTP\nresponse status; async runs persist `{ code, message, step }` to\n`executions.error` so the eval scorer can match against\n`expected.json` with `$error` (see `reference/dataset-format.md`). When\n`condition` is omitted, `control.fail` always fails when reached, so\ncompose with `control.if` for legacy gating.\n\n<!-- GENERATED:STEP_CATALOG START -->\n## Full catalog\n\n_Generated from `STEP_SCHEMAS` in `@eigenpal/types/src/workflow/step-configs.ts`. Do not hand-edit between the GENERATED fences — run `bun run --cwd packages/cli generate:skill`._\n\n### AI steps — model-backed processing\n\n#### `ai.parse-v2` — Parse Document\n\nAutomatically read native, scanned, and mixed documents with capability-aware OCR/vision fallback and explicit completeness.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/parse-v2`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `policy` | object | yes | | |\n| `providers` | object | yes | | |\n| `output` | object | yes | | |\n| `enrichment` | object | yes | | |\n| `advanced` | object | yes | | |\n| `input` | string | yes | | File reference or template expression for the document |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `document` | object | yes | | |\n| `usage` | object | yes | | |\n| `pages` | array<object> | yes | | |\n| `text` | string | yes | | Combined text from all pages |\n| `parserType` | `\"plaintext\"` \\| `\"office\"` \\| `\"llm-vision\"` \\| `\"ocr\"` | yes | | |\n| `parserVersion` | `\"2\"` | yes | | |\n| `model` | string | no | | Model used (for LLM/OCR parsers) |\n| `processingStrategy` | `\"native\"` \\| `\"ocr\"` \\| `\"vision\"` \\| `\"hybrid\"` | no | | How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages). |\n| `structured` | record<string, unknown> | no | | Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser |\n| `completeness` | object | yes | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"policy\": {\n \"type\": \"object\",\n \"properties\": {\n \"native\": {\n \"default\": \"prefer\",\n \"description\": \"Prefer local text extraction, require local text extraction with no image transcription, or skip native PDF extraction. Figure enrichment is independent.\",\n \"type\": \"string\",\n \"enum\": [\n \"prefer\",\n \"require\",\n \"skip\"\n ]\n },\n \"imageReading\": {\n \"type\": \"object\",\n \"properties\": {\n \"order\": {\n \"default\": [\n \"ocr\",\n \"vision\"\n ],\n \"description\": \"Ordered allowed backends. A single entry prohibits the other backend.\",\n \"minItems\": 1,\n \"maxItems\": 2,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"ocr\",\n \"vision\"\n ]\n }\n }\n },\n \"required\": [\n \"order\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"native\",\n \"imageReading\"\n ],\n \"additionalProperties\": false\n },\n \"providers\": {\n \"type\": \"object\",\n \"properties\": {\n \"ocr\": {\n \"description\": \"Exact configured OCR provider ID. Missing pins fail; they never resolve to another provider.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"vision\": {\n \"description\": \"Exact configured vision provider ID. Otherwise uses the deployment parsing default or vision role.\",\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"output\": {\n \"type\": \"object\",\n \"properties\": {\n \"textFormat\": {\n \"default\": \"markdown\",\n \"type\": \"string\",\n \"enum\": [\n \"plain\",\n \"markdown\",\n \"html\",\n \"djot\"\n ]\n },\n \"includeCellMetadata\": {\n \"default\": false,\n \"description\": \"Include spreadsheet cell evidence in pages[].spreadsheet and annotate text for downstream extraction. Preserves raw/displayed values and workbook date system.\",\n \"type\": \"boolean\"\n },\n \"nativeWhitespace\": {\n \"default\": \"reading-order\",\n \"description\": \"Spatial preserves native PDF column spacing. It does not promise OCR/vision coordinates.\",\n \"type\": \"string\",\n \"enum\": [\n \"reading-order\",\n \"spatial\"\n ]\n },\n \"require\": {\n \"default\": [],\n \"description\": \"Required evidence capabilities on nonblank pages. Backends unable to satisfy them are rejected.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"wordCoordinates\",\n \"tables\"\n ]\n }\n }\n },\n \"required\": [\n \"textFormat\",\n \"includeCellMetadata\",\n \"nativeWhitespace\",\n \"require\"\n ],\n \"additionalProperties\": false\n },\n \"enrichment\": {\n \"type\": \"object\",\n \"properties\": {\n \"figures\": {\n \"type\": \"object\",\n \"properties\": {\n \"enabled\": {\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"instructions\": {\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n }\n },\n \"required\": [\n \"enabled\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"figures\"\n ],\n \"additionalProperties\": false\n },\n \"advanced\": {\n \"type\": \"object\",\n \"properties\": {\n \"vision\": {\n \"type\": \"object\",\n \"properties\": {\n \"maxConcurrency\": {\n \"default\": 3,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 10\n },\n \"pagesPerBatch\": {\n \"default\": 5,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 20\n },\n \"renderScale\": {\n \"default\": 2,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"instructions\": {\n \"description\": \"Transcription instructions, never document-specific extraction/schema instructions.\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n }\n },\n \"required\": [\n \"maxConcurrency\",\n \"pagesPerBatch\",\n \"renderScale\",\n \"imageQuality\"\n ],\n \"additionalProperties\": false\n },\n \"languages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"allowPartial\": {\n \"default\": false,\n \"description\": \"Return unresolved pages explicitly instead of failing. Default false.\",\n \"type\": \"boolean\"\n },\n \"cache\": {\n \"default\": false,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"vision\",\n \"allowPartial\",\n \"cache\"\n ],\n \"additionalProperties\": false\n },\n \"input\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File reference or template expression for the document\"\n }\n },\n \"required\": [\n \"policy\",\n \"providers\",\n \"output\",\n \"enrichment\",\n \"advanced\",\n \"input\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"document\": {\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"type\": \"string\"\n },\n \"mimeType\": {\n \"type\": \"string\"\n },\n \"size\": {\n \"type\": \"number\",\n \"description\": \"File size in bytes\"\n },\n \"storageRef\": {\n \"description\": \"Storage reference for the original file\",\n \"type\": \"string\"\n },\n \"renderedPdfRef\": {\n \"description\": \"Storage key of the PDF an office input was rendered to. Page word boxes are measured on this PDF.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n },\n \"usage\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageCount\": {\n \"type\": \"number\"\n },\n \"processingTimeMs\": {\n \"type\": \"number\"\n },\n \"ocrPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPromptTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionCompletionTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"cached\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"pageCount\",\n \"visionPagesProcessed\"\n ],\n \"additionalProperties\": false\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"spreadsheet\": {\n \"description\": \"Opt-in original spreadsheet cell evidence\",\n \"type\": \"object\",\n \"properties\": {\n \"dateSystem\": {\n \"type\": \"string\",\n \"enum\": [\n \"1900\",\n \"1904\"\n ]\n },\n \"declaredRange\": {\n \"type\": \"string\"\n },\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\",\n \"description\": \"Original A1 cell address\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Excel storage type: n=number, s=string, b=boolean, e=error, d=date, z=blank. A numeric date remains type n.\"\n },\n \"rawValue\": {\n \"description\": \"Stored cached value; formulas are never evaluated\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"displayedValue\": {\n \"type\": \"string\",\n \"description\": \"Value formatted using the workbook number format and date system\"\n },\n \"numberFormat\": {\n \"type\": \"string\"\n },\n \"formula\": {\n \"type\": \"string\"\n },\n \"dateValue\": {\n \"description\": \"Calendar rendering for a valid date-formatted serial, without a timezone. Evidence of Excel formatting, not a business classification.\",\n \"type\": \"string\"\n },\n \"excelLeapDay\": {\n \"description\": \"True for the fictitious 1900-02-29 in the Excel 1900 date system\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"address\",\n \"type\",\n \"displayedValue\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"dateSystem\",\n \"cells\"\n ],\n \"additionalProperties\": false\n },\n \"pageIndex\": {\n \"type\": \"number\",\n \"description\": \"0-based page index\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Extracted page text (markdown/HTML/plain, or spatial layout text)\"\n },\n \"pageName\": {\n \"description\": \"Page/sheet name (e.g., Excel sheet name)\",\n \"type\": \"string\"\n },\n \"layoutElements\": {\n \"description\": \"Semantic layout elements in reading order\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"paragraph\",\n \"title\",\n \"sectionHeading\",\n \"pageHeader\",\n \"pageFooter\",\n \"pageNumber\",\n \"footnote\",\n \"table\",\n \"figure\",\n \"formulaBlock\"\n ]\n },\n \"content\": {\n \"type\": \"string\"\n },\n \"table\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n },\n \"caption\": {\n \"type\": \"string\"\n },\n \"figureId\": {\n \"type\": \"string\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"type\",\n \"content\"\n ],\n \"additionalProperties\": false\n }\n },\n \"words\": {\n \"description\": \"Word-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"lines\": {\n \"description\": \"Line-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"tables\": {\n \"description\": \"Extracted tables\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n }\n },\n \"width\": {\n \"description\": \"Page width\",\n \"type\": \"number\"\n },\n \"height\": {\n \"description\": \"Page height\",\n \"type\": \"number\"\n },\n \"unit\": {\n \"description\": \"Unit for width/height and bounding regions\",\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"confidence\": {\n \"description\": \"Overall page confidence\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"nativeTextQuality\": {\n \"description\": \"Per-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness — valid-looking wrong mappings and literal \\\"?\\\" cannot be distinguished from legitimate text.\",\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"clean\",\n \"empty\",\n \"suspect\"\n ]\n },\n \"reasons\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"empty\",\n \"replacement-character\",\n \"lone-surrogate\",\n \"forbidden-control\",\n \"unassigned\",\n \"noncharacter\",\n \"private-use\"\n ]\n }\n },\n \"counts\": {\n \"type\": \"object\",\n \"properties\": {\n \"codePoints\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"nonWhitespace\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"replacement\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"loneSurrogate\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"forbiddenControl\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"unassigned\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"noncharacter\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"privateUse\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"codePoints\",\n \"nonWhitespace\",\n \"replacement\",\n \"loneSurrogate\",\n \"forbiddenControl\",\n \"unassigned\",\n \"noncharacter\",\n \"privateUse\"\n ],\n \"additionalProperties\": false\n },\n \"profile\": {\n \"type\": \"object\",\n \"properties\": {\n \"replacementRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"loneSurrogateRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"forbiddenControlRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"unassignedRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"noncharacterRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"privateUseRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n }\n },\n \"required\": [\n \"replacementRatio\",\n \"loneSurrogateRatio\",\n \"forbiddenControlRatio\",\n \"unassignedRatio\",\n \"noncharacterRatio\",\n \"privateUseRatio\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"status\",\n \"reasons\",\n \"counts\",\n \"profile\"\n ],\n \"additionalProperties\": false\n },\n \"provenance\": {\n \"type\": \"object\",\n \"properties\": {\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\"\n ]\n },\n \"provider\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"reason\": {\n \"type\": \"string\"\n },\n \"textFormat\": {\n \"type\": \"string\",\n \"enum\": [\n \"plain\",\n \"markdown\",\n \"html\",\n \"djot\"\n ]\n },\n \"capabilities\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"wordCoordinates\",\n \"tables\"\n ]\n }\n }\n },\n \"required\": [\n \"source\",\n \"reason\",\n \"textFormat\",\n \"capabilities\"\n ],\n \"additionalProperties\": false\n },\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"complete\",\n \"blank\",\n \"no-text\",\n \"unresolved\"\n ]\n },\n \"warnings\": {\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"provenance\",\n \"status\",\n \"warnings\"\n ],\n \"additionalProperties\": false\n }\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Combined text from all pages\"\n },\n \"parserType\": {\n \"type\": \"string\",\n \"enum\": [\n \"plaintext\",\n \"office\",\n \"llm-vision\",\n \"ocr\"\n ]\n },\n \"parserVersion\": {\n \"type\": \"string\",\n \"const\": \"2\"\n },\n \"model\": {\n \"description\": \"Model used (for LLM/OCR parsers)\",\n \"type\": \"string\"\n },\n \"processingStrategy\": {\n \"description\": \"How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\",\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\",\n \"hybrid\"\n ]\n },\n \"structured\": {\n \"description\": \"Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"completeness\": {\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"complete\",\n \"partial\"\n ]\n },\n \"unresolvedPageIndexes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n }\n },\n \"required\": [\n \"status\",\n \"unresolvedPageIndexes\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"document\",\n \"usage\",\n \"pages\",\n \"text\",\n \"parserType\",\n \"parserVersion\",\n \"completeness\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.parse` — Parse Document v1\n\nParse Document v1, the retired parser, kept only so existing workflows run unchanged. Do not add it to workflows: use ai.parse-v2 (Parse Document), which picks native text, OCR or vision per page.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/parse`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Storage reference or template expression for the document |\n| `parseMode` | `\"ocr\"` \\| `\"vision\"` \\| `\"native\"` \\| `\"native-or-ocr\"` | no | | Base parser for PDF/image inputs. OCR is the default; vision uses the selected LLM. `native` extracts PDF embedded text only and never calls OCR or vision. `native-or-ocr` extracts native text, runs page-quality diagnostics, and requests OCR when pages have detectable anomalies (empty, U+FFFD, lone surrogates, forbidden controls, unassigned/noncharacter, heavy PUA). Page selection, subset egress, and billing are provider-dependent. Valid-looking wrong text and literal \"?\" are not flagged. Text and Office files always use local parsing. |\n| `ocrModel` | string | no | | OCR provider ID for PDF/image parsing |\n| `llmModel` | string | no | | LLM provider ID for vision-based parsing |\n| `llmReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `figureModel` | string | no | | Vision model used only for the optional figure-description pass |\n| `figureReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxConcurrency` | number | no | `3` | Max concurrent VLM batch requests |\n| `pagesPerBatch` | number | no | `5` | Number of page images per VLM request |\n| `pdfRenderScale` | number | no | `1` | Scale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes. |\n| `imageQuality` | integer | no | `85` | JPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes. |\n| `prompt` | string | no | | Custom extraction prompt |\n| `languages` | array<string> | no | | OCR language hints |\n| `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`. |\n| `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. |\n| `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. |\n| `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. |\n| `cache` | boolean | no | `false` | When true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `document` | object | yes | | |\n| `usage` | object | yes | | |\n| `pages` | array<object> | yes | | |\n| `text` | string | yes | | Combined text from all pages |\n| `parserType` | `\"plaintext\"` \\| `\"office\"` \\| `\"llm-vision\"` \\| `\"ocr\"` | yes | | |\n| `parserVersion` | string | no | | |\n| `model` | string | no | | Model used (for LLM/OCR parsers) |\n| `processingStrategy` | `\"native\"` \\| `\"ocr\"` \\| `\"vision\"` \\| `\"hybrid\"` | no | | How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages). |\n| `structured` | record<string, unknown> | no | | Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Storage reference or template expression for the document\"\n },\n \"parseMode\": {\n \"description\": \"Base parser for PDF/image inputs. OCR is the default; vision uses the selected LLM. `native` extracts PDF embedded text only and never calls OCR or vision. `native-or-ocr` extracts native text, runs page-quality diagnostics, and requests OCR when pages have detectable anomalies (empty, U+FFFD, lone surrogates, forbidden controls, unassigned/noncharacter, heavy PUA). Page selection, subset egress, and billing are provider-dependent. Valid-looking wrong text and literal \\\"?\\\" are not flagged. Text and Office files always use local parsing.\",\n \"type\": \"string\",\n \"enum\": [\n \"ocr\",\n \"vision\",\n \"native\",\n \"native-or-ocr\"\n ]\n },\n \"ocrModel\": {\n \"description\": \"OCR provider ID for PDF/image parsing\",\n \"type\": \"string\"\n },\n \"llmModel\": {\n \"description\": \"LLM provider ID for vision-based parsing\",\n \"type\": \"string\"\n },\n \"llmReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"figureModel\": {\n \"description\": \"Vision model used only for the optional figure-description pass\",\n \"type\": \"string\"\n },\n \"figureReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxConcurrency\": {\n \"description\": \"Max concurrent VLM batch requests\",\n \"default\": 3,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 10\n },\n \"pagesPerBatch\": {\n \"description\": \"Number of page images per VLM request\",\n \"default\": 5,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 20\n },\n \"pdfRenderScale\": {\n \"description\": \"Scale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes.\",\n \"default\": 1,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes.\",\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"prompt\": {\n \"description\": \"Custom extraction prompt\",\n \"type\": \"string\"\n },\n \"languages\": {\n \"description\": \"OCR language hints\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"outputFormat\": {\n \"description\": \"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`.\",\n \"default\": \"markdown\",\n \"type\": \"string\",\n \"enum\": [\n \"plain\",\n \"markdown\",\n \"djot\",\n \"html\",\n \"layout\"\n ]\n },\n \"nativeText\": {\n \"description\": \"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.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"describeFigures\": {\n \"description\": \"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.\",\n \"type\": \"boolean\"\n },\n \"figureInstructions\": {\n \"description\": \"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.\",\n \"type\": \"string\"\n },\n \"cache\": {\n \"description\": \"When true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off.\",\n \"default\": false,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"input\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"document\": {\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"type\": \"string\"\n },\n \"mimeType\": {\n \"type\": \"string\"\n },\n \"size\": {\n \"type\": \"number\",\n \"description\": \"File size in bytes\"\n },\n \"storageRef\": {\n \"description\": \"Storage reference for the original file\",\n \"type\": \"string\"\n },\n \"renderedPdfRef\": {\n \"description\": \"Storage key of the PDF an office input was rendered to. Page word boxes are measured on this PDF.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n },\n \"usage\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageCount\": {\n \"type\": \"number\"\n },\n \"processingTimeMs\": {\n \"type\": \"number\"\n },\n \"ocrPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPagesProcessed\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionPromptTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"visionCompletionTokens\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"cached\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"pageCount\"\n ],\n \"additionalProperties\": false\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"spreadsheet\": {\n \"description\": \"Opt-in original spreadsheet cell evidence\",\n \"type\": \"object\",\n \"properties\": {\n \"dateSystem\": {\n \"type\": \"string\",\n \"enum\": [\n \"1900\",\n \"1904\"\n ]\n },\n \"declaredRange\": {\n \"type\": \"string\"\n },\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\",\n \"description\": \"Original A1 cell address\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Excel storage type: n=number, s=string, b=boolean, e=error, d=date, z=blank. A numeric date remains type n.\"\n },\n \"rawValue\": {\n \"description\": \"Stored cached value; formulas are never evaluated\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"displayedValue\": {\n \"type\": \"string\",\n \"description\": \"Value formatted using the workbook number format and date system\"\n },\n \"numberFormat\": {\n \"type\": \"string\"\n },\n \"formula\": {\n \"type\": \"string\"\n },\n \"dateValue\": {\n \"description\": \"Calendar rendering for a valid date-formatted serial, without a timezone. Evidence of Excel formatting, not a business classification.\",\n \"type\": \"string\"\n },\n \"excelLeapDay\": {\n \"description\": \"True for the fictitious 1900-02-29 in the Excel 1900 date system\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"address\",\n \"type\",\n \"displayedValue\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"dateSystem\",\n \"cells\"\n ],\n \"additionalProperties\": false\n },\n \"pageIndex\": {\n \"type\": \"number\",\n \"description\": \"0-based page index\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Extracted page text (markdown/HTML/plain, or spatial layout text)\"\n },\n \"pageName\": {\n \"description\": \"Page/sheet name (e.g., Excel sheet name)\",\n \"type\": \"string\"\n },\n \"layoutElements\": {\n \"description\": \"Semantic layout elements in reading order\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"paragraph\",\n \"title\",\n \"sectionHeading\",\n \"pageHeader\",\n \"pageFooter\",\n \"pageNumber\",\n \"footnote\",\n \"table\",\n \"figure\",\n \"formulaBlock\"\n ]\n },\n \"content\": {\n \"type\": \"string\"\n },\n \"table\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n },\n \"caption\": {\n \"type\": \"string\"\n },\n \"figureId\": {\n \"type\": \"string\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"type\",\n \"content\"\n ],\n \"additionalProperties\": false\n }\n },\n \"words\": {\n \"description\": \"Word-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"lines\": {\n \"description\": \"Line-level positions\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"confidence\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"tables\": {\n \"description\": \"Extracted tables\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"cells\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\n \"type\": \"string\"\n },\n \"rowIndex\": {\n \"type\": \"number\"\n },\n \"columnIndex\": {\n \"type\": \"number\"\n },\n \"rowSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"columnSpan\": {\n \"default\": 1,\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"content\",\n \"rowIndex\",\n \"columnIndex\",\n \"rowSpan\",\n \"columnSpan\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rowCount\": {\n \"type\": \"number\"\n },\n \"columnCount\": {\n \"type\": \"number\"\n },\n \"boundingRegion\": {\n \"type\": \"object\",\n \"properties\": {\n \"polygon\": {\n \"minItems\": 3,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"x\": {\n \"type\": \"number\"\n },\n \"y\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"x\",\n \"y\"\n ],\n \"additionalProperties\": false\n }\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"pageIndex\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"polygon\",\n \"unit\",\n \"pageIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"cells\",\n \"rowCount\",\n \"columnCount\"\n ],\n \"additionalProperties\": false\n }\n },\n \"width\": {\n \"description\": \"Page width\",\n \"type\": \"number\"\n },\n \"height\": {\n \"description\": \"Page height\",\n \"type\": \"number\"\n },\n \"unit\": {\n \"description\": \"Unit for width/height and bounding regions\",\n \"type\": \"string\",\n \"enum\": [\n \"pixel\",\n \"inch\",\n \"point\",\n \"normalized\"\n ]\n },\n \"confidence\": {\n \"description\": \"Overall page confidence\",\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"nativeTextQuality\": {\n \"description\": \"Per-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness — valid-looking wrong mappings and literal \\\"?\\\" cannot be distinguished from legitimate text.\",\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\",\n \"enum\": [\n \"clean\",\n \"empty\",\n \"suspect\"\n ]\n },\n \"reasons\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\n \"empty\",\n \"replacement-character\",\n \"lone-surrogate\",\n \"forbidden-control\",\n \"unassigned\",\n \"noncharacter\",\n \"private-use\"\n ]\n }\n },\n \"counts\": {\n \"type\": \"object\",\n \"properties\": {\n \"codePoints\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"nonWhitespace\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"replacement\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"loneSurrogate\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"forbiddenControl\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"unassigned\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"noncharacter\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"privateUse\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"codePoints\",\n \"nonWhitespace\",\n \"replacement\",\n \"loneSurrogate\",\n \"forbiddenControl\",\n \"unassigned\",\n \"noncharacter\",\n \"privateUse\"\n ],\n \"additionalProperties\": false\n },\n \"profile\": {\n \"type\": \"object\",\n \"properties\": {\n \"replacementRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"loneSurrogateRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"forbiddenControlRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"unassignedRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"noncharacterRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n },\n \"privateUseRatio\": {\n \"type\": \"number\",\n \"minimum\": 0\n }\n },\n \"required\": [\n \"replacementRatio\",\n \"loneSurrogateRatio\",\n \"forbiddenControlRatio\",\n \"unassignedRatio\",\n \"noncharacterRatio\",\n \"privateUseRatio\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"status\",\n \"reasons\",\n \"counts\",\n \"profile\"\n ],\n \"additionalProperties\": false\n },\n \"provenance\": {\n \"description\": \"Which extractor produced the final text/layout on this page\",\n \"type\": \"object\",\n \"properties\": {\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\"\n ]\n }\n },\n \"required\": [\n \"source\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Combined text from all pages\"\n },\n \"parserType\": {\n \"type\": \"string\",\n \"enum\": [\n \"plaintext\",\n \"office\",\n \"llm-vision\",\n \"ocr\"\n ]\n },\n \"parserVersion\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model used (for LLM/OCR parsers)\",\n \"type\": \"string\"\n },\n \"processingStrategy\": {\n \"description\": \"How this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\",\n \"type\": \"string\",\n \"enum\": [\n \"native\",\n \"ocr\",\n \"vision\",\n \"hybrid\"\n ]\n },\n \"structured\": {\n \"description\": \"Canonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"document\",\n \"usage\",\n \"pages\",\n \"text\",\n \"parserType\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.extract` — Extract Data\n\nExtract structured data from text using AI with a JSON schema\n\n**Behavior and examples:** `eigenpal docs read steps/ai/extract`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Text content or template expression |\n| `schema` | object | yes | | JSON Schema defining the structure to extract. Fields not listed in `required` come back null when the document does not contain them; a missing required field fails the step. |\n| `prompt` | string | no | | Custom prompt template for extraction |\n| `provider` | string | no | | Provider ID (e.g., \"openai/gpt-6-luna\") |\n| `model` | string | no | | Model override |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxInputTokens` | integer | no | | Max input tokens. Truncates input text and logs a warning when exceeded. Omit for no limit. |\n| `grounded` | boolean | no | | Grounding is ON by default: each schema field gets a source span + confidence (high=verbatim, medium=fuzzy, low=ungrounded) under a reserved `_grounding` output key, and fields whose value cannot be located in the source are flagged for human review. Values stay the reliable schema-typed ones. The pass runs through the workspace LLM (any provider) and chunks long documents automatically. Tri-state: unset (default) = on, degrading gracefully to deterministic text alignment (`_grounding._degraded: true`) if no grounding model is available; `true` = strict, the step fails when the grounding model cannot be resolved; `false` = off, no `_grounding` key at all. |\n| `groundingModel` | string | no | | Provider/model for the grounding pass. Defaults to the workspace default LLM. Any configured provider works; the pass only fails the step when `grounded: true` is set explicitly and no model resolves. |\n| `groundingReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `groundingExamples` | array<object> | no | | Optional few-shot examples pinning grounding to verbatim source text per field. |\n| `reviewOn` | `\"medium_or_low\"` \\| `\"low_only\"` | no | | Which grounding confidences set needsReview on a field. Default: low_only (only fields whose value could not be located in the source). Use medium_or_low to also flag approximate and derived matches. |\n\n**Output:** `record<string, unknown>`\n\n> Extracted structured data matching the provided schema. Unless grounding is disabled (grounded: false), the output also carries a reserved `_grounding` map keyed by dotted field path: `_grounding[\"line_items.0.amount\"] = { confidence: high|medium|low, score?, recognitionScore?, needsReview, reason?, quote?, citations?, source_span }`. When the parsed document carries per-word OCR confidence, `recognitionScore` is the recognition of the cited words and caps the field: `score` never exceeds it, below 0.8 the field is low, below 0.9 at most medium. The map also holds reserved `_degraded: true` / `_reason` markers when grounding could not run the shared algorithm or the Eigenpal text pass. Lineage is never included in this JSON.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Text content or template expression\"\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"const\": \"object\"\n },\n \"properties\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"required\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"type\",\n \"properties\"\n ],\n \"additionalProperties\": false,\n \"description\": \"JSON Schema defining the structure to extract. Fields not listed in `required` come back null when the document does not contain them; a missing required field fails the step.\"\n },\n \"prompt\": {\n \"description\": \"Custom prompt template for extraction\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID (e.g., \\\"openai/gpt-6-luna\\\")\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxInputTokens\": {\n \"description\": \"Max input tokens. Truncates input text and logs a warning when exceeded. Omit for no limit.\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"grounded\": {\n \"description\": \"Grounding is ON by default: each schema field gets a source span + confidence (high=verbatim, medium=fuzzy, low=ungrounded) under a reserved `_grounding` output key, and fields whose value cannot be located in the source are flagged for human review. Values stay the reliable schema-typed ones. The pass runs through the workspace LLM (any provider) and chunks long documents automatically. Tri-state: unset (default) = on, degrading gracefully to deterministic text alignment (`_grounding._degraded: true`) if no grounding model is available; `true` = strict, the step fails when the grounding model cannot be resolved; `false` = off, no `_grounding` key at all.\",\n \"type\": \"boolean\"\n },\n \"groundingModel\": {\n \"description\": \"Provider/model for the grounding pass. Defaults to the workspace default LLM. Any configured provider works; the pass only fails the step when `grounded: true` is set explicitly and no model resolves.\",\n \"type\": \"string\"\n },\n \"groundingReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"groundingExamples\": {\n \"description\": \"Optional few-shot examples pinning grounding to verbatim source text per field.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"extractions\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"field\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"field\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"text\",\n \"extractions\"\n ],\n \"additionalProperties\": false\n }\n },\n \"reviewOn\": {\n \"description\": \"Which grounding confidences set needsReview on a field. Default: low_only (only fields whose value could not be located in the source). Use medium_or_low to also flag approximate and derived matches.\",\n \"type\": \"string\",\n \"enum\": [\n \"medium_or_low\",\n \"low_only\"\n ]\n }\n },\n \"required\": [\n \"input\",\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Extracted structured data matching the provided schema. Unless grounding is disabled (grounded: false), the output also carries a reserved `_grounding` map keyed by dotted field path: `_grounding[\\\"line_items.0.amount\\\"] = { confidence: high|medium|low, score?, recognitionScore?, needsReview, reason?, quote?, citations?, source_span }`. When the parsed document carries per-word OCR confidence, `recognitionScore` is the recognition of the cited words and caps the field: `score` never exceeds it, below 0.8 the field is low, below 0.9 at most medium. The map also holds reserved `_degraded: true` / `_reason` markers when grounding could not run the shared algorithm or the Eigenpal text pass. Lineage is never included in this JSON.\"\n}\n```\n\n\n#### `ai.split` — Split Document\n\nSplit a parsed document into named sections using an LLM. Consumes ai.parse output; emits per-section page ranges and text ready for downstream ai.extract via control.parallel_map.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/split`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Template expression resolving to ai.parse output, e.g. \"{{ steps.parse.output }}\" |\n| `sections` | array<object> | yes | | Named sections to find in the document |\n| `rules` | string | no | | Optional natural-language rules appended to the system prompt. E.g. \"End-of-section markers like *Koniec prílohy 2* close the current section.\" |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml (e.g. \"openai/gpt-6-luna\"). Falls back to the tenant default LLM provider when omitted. |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `windowTokenBudget` | integer | no | | Override the estimated per-window token ceiling. Oversized pages are subdivided with overlap while retaining their original page index. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. Inputs requiring more than 64 LLM windows are rejected before calls begin. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `splits` | array<object> | yes | | Sections found in the document, in page order. Absent sections are omitted. |\n| `sections` | record<string, object> | yes | | The same sections keyed by config name, so a downstream step can reference one directly: `{{ steps.<split>.output.sections.<name>.page_range }}`. Prefer this over filtering `splits`. On a duplicate name the last wins. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Template expression resolving to ai.parse output, e.g. \\\"{{ steps.parse.output }}\\\"\"\n },\n \"sections\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Stable id, used as the key in output and template references\"\n },\n \"description\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"What this section looks like in the document. Use the document's own terminology (e.g. \\\"Príloha 2 / Anlage 2\\\") and visual cues. Multilingual variants belong here.\"\n },\n \"required\": {\n \"description\": \"If true, log a warn when this section is not found, and lean the LLM toward expecting it. Default: false (sections may be absent).\",\n \"type\": \"boolean\"\n },\n \"endHints\": {\n \"description\": \"Natural-language hints fed to the LLM about what marks the END of this section (e.g. [\\\"PRÍPAD PORUŠENIA ZMLUVY\\\", \\\"*Koniec prílohy*\\\"]). The LLM uses these as guidance — not a regex match — so casing variants, missing diacritics, and multilingual phrasings all close the section correctly.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"name\",\n \"description\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Named sections to find in the document\"\n },\n \"rules\": {\n \"description\": \"Optional natural-language rules appended to the system prompt. E.g. \\\"End-of-section markers like *Koniec prílohy 2* close the current section.\\\"\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml (e.g. \\\"openai/gpt-6-luna\\\"). Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"windowTokenBudget\": {\n \"description\": \"Override the estimated per-window token ceiling. Oversized pages are subdivided with overlap while retaining their original page index. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. Inputs requiring more than 64 LLM windows are rejected before calls begin.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"sections\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"splits\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Section name from the config\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence at the anchor page. Coarse enum (low | medium | high) — numeric scores cluster meaninglessly at 0.85-0.95.\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the anchor — useful for debugging\"\n },\n \"evidence\": {\n \"description\": \"Structured start-anchor evidence — parse this instead of regexing over `notes`.\",\n \"type\": \"object\",\n \"properties\": {\n \"start_heading_text\": {\n \"description\": \"Verbatim heading text the LLM cited as the section start\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"start_page\": {\n \"description\": \"Page where start_heading_text appears\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"additionalProperties\": false\n },\n \"end_evidence\": {\n \"description\": \"Set when the LLM detected an end-of-section cue (matched against the section's `endHints` or an explicit closing marker). Absent when the section was closed by continuity-fill alone.\",\n \"type\": \"object\",\n \"properties\": {\n \"end_page\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"LAST page of the section (inclusive)\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the end. Pair with start `notes` for reconciliation.\"\n }\n },\n \"required\": [\n \"end_page\",\n \"confidence\",\n \"notes\"\n ],\n \"additionalProperties\": false\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Joined per-page content for this section, ready for downstream ai.extract\"\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"pageName\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"anchored\",\n \"inferred\"\n ],\n \"description\": \"Whether this page is direct LLM evidence (anchored) or continuity-filled (inferred)\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"source\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Raw per-page records covered by this split (in page order). Iterate when downstream needs per-page context (e.g. control.parallel_map over section pages).\"\n },\n \"pages_anchored\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages with direct LLM evidence\"\n },\n \"pages_inferred\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages assigned by deterministic continuity fill\"\n }\n },\n \"required\": [\n \"name\",\n \"page_range\",\n \"confidence\",\n \"notes\",\n \"text\",\n \"pages\",\n \"pages_anchored\",\n \"pages_inferred\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Sections found in the document, in page order. Absent sections are omitted.\"\n },\n \"sections\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Section name from the config\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence at the anchor page. Coarse enum (low | medium | high) — numeric scores cluster meaninglessly at 0.85-0.95.\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the anchor — useful for debugging\"\n },\n \"evidence\": {\n \"description\": \"Structured start-anchor evidence — parse this instead of regexing over `notes`.\",\n \"type\": \"object\",\n \"properties\": {\n \"start_heading_text\": {\n \"description\": \"Verbatim heading text the LLM cited as the section start\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"start_page\": {\n \"description\": \"Page where start_heading_text appears\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"additionalProperties\": false\n },\n \"end_evidence\": {\n \"description\": \"Set when the LLM detected an end-of-section cue (matched against the section's `endHints` or an explicit closing marker). Absent when the section was closed by continuity-fill alone.\",\n \"type\": \"object\",\n \"properties\": {\n \"end_page\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"LAST page of the section (inclusive)\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM's justification for the end. Pair with start `notes` for reconciliation.\"\n }\n },\n \"required\": [\n \"end_page\",\n \"confidence\",\n \"notes\"\n ],\n \"additionalProperties\": false\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Joined per-page content for this section, ready for downstream ai.extract\"\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"pageName\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"anchored\",\n \"inferred\"\n ],\n \"description\": \"Whether this page is direct LLM evidence (anchored) or continuity-filled (inferred)\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"source\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Raw per-page records covered by this split (in page order). Iterate when downstream needs per-page context (e.g. control.parallel_map over section pages).\"\n },\n \"pages_anchored\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages with direct LLM evidence\"\n },\n \"pages_inferred\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages assigned by deterministic continuity fill\"\n }\n },\n \"required\": [\n \"name\",\n \"page_range\",\n \"confidence\",\n \"notes\",\n \"text\",\n \"pages\",\n \"pages_anchored\",\n \"pages_inferred\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"The same sections keyed by config name, so a downstream step can reference one directly: `{{ steps.<split>.output.sections.<name>.page_range }}`. Prefer this over filtering `splits`. On a duplicate name the last wins.\"\n }\n },\n \"required\": [\n \"splits\",\n \"sections\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.segment` — Separate Documents\n\nSeparate a concatenated batch (one big scan) into typed document instances using an LLM. Consumes ai.parse output and a type taxonomy; discovers an unknown number of documents in any order and emits per-document page ranges + text + type, ready for type-specific ai.extract via control.parallel_map. The inverse of ai.split.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/segment`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Template expression resolving to ai.parse output, e.g. \"{{ steps.parse.output }}\" |\n| `documentTypes` | array<object> | yes | | The document-type taxonomy. The LLM tags each detected document with one of these names, or the reserved \"unknown\" type when none fit. |\n| `rules` | string | no | | Optional natural-language rules appended to the system prompt. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted. |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `windowTokenBudget` | integer | no | | Override the per-window token ceiling. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `summary` | object | yes | | Batch-level escalation summary: labelled vs unlabelled counts + docs needing review. |\n| `documents` | array<object> | yes | | Documents discovered in the batch, in page order. The full batch is covered. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Template expression resolving to ai.parse output, e.g. \\\"{{ steps.parse.output }}\\\"\"\n },\n \"documentTypes\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Type label returned in documents[].type (e.g. \\\"timesheet\\\", \\\"deal-memo\\\")\"\n },\n \"description\": {\n \"description\": \"What this document type looks like — headings, layout, vocabulary, and the cues that mark its FIRST page. Fed to the LLM for both boundary detection and typing.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"The document-type taxonomy. The LLM tags each detected document with one of these names, or the reserved \\\"unknown\\\" type when none fit.\"\n },\n \"rules\": {\n \"description\": \"Optional natural-language rules appended to the system prompt.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"windowTokenBudget\": {\n \"description\": \"Override the per-window token ceiling. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"documentTypes\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"summary\": {\n \"type\": \"object\",\n \"properties\": {\n \"total\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Total documents discovered.\"\n },\n \"labelled\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Documents assigned a known taxonomy type.\"\n },\n \"unlabelled\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Documents the segmenter could not label (type \\\"unknown\\\") — escalate to a human.\"\n },\n \"lowConfidence\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"Documents with low boundary/type confidence.\"\n },\n \"byType\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Per-type document counts.\"\n },\n \"needsReview\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"type\": {\n \"type\": \"string\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2\n },\n \"reason\": {\n \"type\": \"string\",\n \"enum\": [\n \"unlabelled\",\n \"low_confidence\"\n ]\n },\n \"notes\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"index\",\n \"type\",\n \"page_range\",\n \"reason\",\n \"notes\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Documents to escalate to a human operator, with the reason for each.\"\n }\n },\n \"required\": [\n \"total\",\n \"labelled\",\n \"unlabelled\",\n \"lowConfidence\",\n \"byType\",\n \"needsReview\"\n ],\n \"additionalProperties\": false,\n \"description\": \"Batch-level escalation summary: labelled vs unlabelled counts + docs needing review.\"\n },\n \"documents\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991,\n \"description\": \"0-based position of this document in the batch\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Chosen type name from the taxonomy, or \\\"unknown\\\"\"\n },\n \"page_range\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence at the boundary + type. Coarse enum (low | medium | high).\"\n },\n \"notes\": {\n \"type\": \"string\",\n \"description\": \"LLM justification for the boundary — useful for debugging\"\n },\n \"evidence\": {\n \"description\": \"Structured start evidence — parse this instead of regexing over `notes`.\",\n \"type\": \"object\",\n \"properties\": {\n \"start_heading_text\": {\n \"description\": \"Verbatim heading/title text the LLM cited as the document start\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"start_page\": {\n \"description\": \"Page where the start appears\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"null\"\n }\n ]\n }\n },\n \"additionalProperties\": false\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Joined per-page content for this document, ready for downstream ai.extract\"\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"pageName\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\",\n \"enum\": [\n \"anchored\",\n \"inferred\"\n ]\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\",\n \"source\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Raw per-page records covered by this document, in page order.\"\n },\n \"pages_anchored\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages with direct LLM boundary evidence\"\n },\n \"pages_inferred\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Pages assigned by deterministic continuity fill\"\n }\n },\n \"required\": [\n \"index\",\n \"type\",\n \"page_range\",\n \"confidence\",\n \"notes\",\n \"text\",\n \"pages\",\n \"pages_anchored\",\n \"pages_inferred\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Documents discovered in the batch, in page order. The full batch is covered.\"\n }\n },\n \"required\": [\n \"summary\",\n \"documents\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.classify` — Classify\n\nClassify a document or text into one of a fixed label set using an LLM. Output exposes the picked label (constrained to the configured names), a coarse confidence, and a short justification. Pair with control.fail to reject documents that match an undesired label.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/classify`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Template expression for the text to classify. Typically the output of ai.parse, e.g. \"{{ steps.parse.output.text }}\". |\n| `labels` | array<object> | yes | | Allowed labels. The LLM is constrained to pick exactly one of these names. |\n| `prompt` | string | no | | Custom classification instructions appended to the system prompt. Use to clarify edge cases or emphasize evidence the model should weigh. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml (e.g. \"openai/gpt-6-luna\"). Falls back to the tenant default LLM provider when omitted. |\n| `model` | string | no | | Model override (advanced) |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxInputTokens` | integer | no | | Max input tokens. Truncates input text when exceeded. Omit for no limit. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `label` | string | yes | | The selected label name (one of the configured labels). Compare against literal strings to gate downstream steps. |\n| `confidence` | `\"low\"` \\| `\"medium\"` \\| `\"high\"` | yes | | LLM confidence in the classification. Coarse enum — numeric scores cluster meaninglessly at 0.85-0.95. |\n| `reason` | string | yes | | Short justification for the chosen label — useful for debugging. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Template expression for the text to classify. Typically the output of ai.parse, e.g. \\\"{{ steps.parse.output.text }}\\\".\"\n },\n \"labels\": {\n \"minItems\": 2,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"The label value returned in output.label. Keep it short and stable (used in downstream conditions).\"\n },\n \"description\": {\n \"description\": \"What documents fall into this label. Fed to the LLM as guidance.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Allowed labels. The LLM is constrained to pick exactly one of these names.\"\n },\n \"prompt\": {\n \"description\": \"Custom classification instructions appended to the system prompt. Use to clarify edge cases or emphasize evidence the model should weigh.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml (e.g. \\\"openai/gpt-6-luna\\\"). Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (advanced)\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxInputTokens\": {\n \"description\": \"Max input tokens. Truncates input text when exceeded. Omit for no limit.\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"labels\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"label\": {\n \"type\": \"string\",\n \"description\": \"The selected label name (one of the configured labels). Compare against literal strings to gate downstream steps.\"\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ],\n \"description\": \"LLM confidence in the classification. Coarse enum — numeric scores cluster meaninglessly at 0.85-0.95.\"\n },\n \"reason\": {\n \"type\": \"string\",\n \"description\": \"Short justification for the chosen label — useful for debugging.\"\n }\n },\n \"required\": [\n \"label\",\n \"confidence\",\n \"reason\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.classify-pages` — Label Pages\n\nAssign zero or more labels to each page independently (multi-label) using an LLM. Consumes ai.parse output; emits per-page labels and a byLabel map (label -> page indices) that supports NON-contiguous selections. Feed byLabel.<label> straight into ai.vision `pageIndices` to inspect scattered pages of a type (e.g. every signature or property-photo page).\n\n**Behavior and examples:** `eigenpal docs read steps/ai/classify-pages`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | The ai.parse output to label, e.g. \"{{ steps.parse.output }}\". Each page is labelled independently. |\n| `labels` | array<string \\| object> | yes | | Labels a page can carry. A page may match ZERO, ONE, or MANY of them. Each entry is a bare name (e.g. \"photo\") or { name, description }. Names must be unique. |\n| `prompt` | string | no | | Extra classification guidance appended to the system prompt. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml. Falls back to the tenant default. |\n| `model` | string | no | | Model override (advanced). |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `windowTokenBudget` | integer | no | | Per-window token ceiling. Pages are packed into windows under this budget; one LLM call per window. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET (20000). |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `pages` | array<object> | yes | | Every input page, in order, with the labels the model assigned to it. |\n| `byLabel` | record<string, array<integer>> | yes | | Label name -> ascending page indices carrying it. Every configured label is present (empty array when no page matched), so dot access is always safe: `{{ steps.<step>.output.byLabel.<label> }}` resolves to a number[] ready for ai.vision `pageIndices`. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"The ai.parse output to label, e.g. \\\"{{ steps.parse.output }}\\\". Each page is labelled independently.\"\n },\n \"labels\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Label value — the key in output.byLabel and an entry in pages[].labels.\"\n },\n \"description\": {\n \"description\": \"What a page must show to earn this label. Fed to the LLM as guidance.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Labels a page can carry. A page may match ZERO, ONE, or MANY of them. Each entry is a bare name (e.g. \\\"photo\\\") or { name, description }. Names must be unique.\"\n },\n \"prompt\": {\n \"description\": \"Extra classification guidance appended to the system prompt.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml. Falls back to the tenant default.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (advanced).\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"windowTokenBudget\": {\n \"description\": \"Per-window token ceiling. Pages are packed into windows under this budget; one LLM call per window. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET (20000).\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"labels\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"labels\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Labels assigned to this page (possibly empty).\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"labels\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Every input page, in order, with the labels the model assigned to it.\"\n },\n \"byLabel\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n },\n \"description\": \"Label name -> ascending page indices carrying it. Every configured label is present (empty array when no page matched), so dot access is always safe: `{{ steps.<step>.output.byLabel.<label> }}` resolves to a number[] ready for ai.vision `pageIndices`.\"\n }\n },\n \"required\": [\n \"pages\",\n \"byLabel\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.vision` — Inspect Pages (Vision)\n\nInspect rendered page images with a vision model and return structured JSON matching a schema. The visual counterpart to Extract Data: use it for conclusions that live in the pixels rather than the text (is the document signed? are the photos usable?). Renders PDF, image, or Office/Word inputs; route to specific pages with an ai.split page range to keep it cheap.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/vision`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `document` | string | yes | | Template expression resolving to the input file (PDF, image, or Office document). |\n| `pageFrom` | integer \\| string | no | | First page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, starts from the first page. |\n| `pageTo` | integer \\| string | no | | Last page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, runs to the last page. When BOTH pageFrom and pageTo are omitted, the whole document is inspected in chunks of maxPages (divide-and-conquer, results merged). |\n| `pageIndices` | array<integer> \\| string | no | | Explicit list of 0-based page indices to inspect — supports NON-contiguous selections, e.g. [4, 11, 19], or a template resolving to a number[] such as \"{{ steps.label_pages.output.byLabel.photo }}\". Highest priority: when set, pageFrom/pageTo and pages are ignored. |\n| `schema` | object | yes | | JSON Schema defining the structure the vision model should return. Fields not listed in `required` come back null when not found; a missing required field fails the step. |\n| `prompt` | string | no | | Optional instruction refining the extraction. The schema drives it when omitted. |\n| `provider` | string | no | | Provider ID (must support vision). |\n| `model` | string | no | | Model override (must support vision). |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `renderScale` | number | no | | PDF render scale (1.0 = 72 DPI). Raise for small text or weak VLM OCR. Capped at 6 to avoid oversized page rasters. |\n| `imageQuality` | integer | no | | JPEG quality for rendered pages (default 85). |\n| `maxPages` | integer | no | | Chunk size: the maximum pages sent to the vision model in a single call. When the inspected range (or the whole document) is larger, it is split into chunks of this size and the per-chunk results are merged by a reduce pass. The reduce follows each field's DESCRIPTION: a boolean described as \"present on any page\" is OR-ed, one described as \"true for every page\" is AND-ed, and list fields are concatenated. The merge is most reliable for boolean/scalar claims; for schemas that AGGREGATE long lists across chunks it can still drop or reorder items, so prefer a bounded page range for large list extraction. Default 20, capped at 100. |\n\n**Output:** `record<string, unknown>`\n\n> Structured data matching the provided schema. The output also carries a reserved `_vision` key recording the inspected source document ref and the page indices that were rendered, so the UI can re-rasterize exactly those pages client-side. `_vision` is excluded from user-schema validation.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"document\": {\n \"type\": \"string\",\n \"description\": \"Template expression resolving to the input file (PDF, image, or Office document).\"\n },\n \"pageFrom\": {\n \"description\": \"First page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, starts from the first page.\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"pageTo\": {\n \"description\": \"Last page to inspect (0-based, inclusive). Optional. Accepts a template expression. When omitted, runs to the last page. When BOTH pageFrom and pageTo are omitted, the whole document is inspected in chunks of maxPages (divide-and-conquer, results merged).\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"pageIndices\": {\n \"description\": \"Explicit list of 0-based page indices to inspect — supports NON-contiguous selections, e.g. [4, 11, 19], or a template resolving to a number[] such as \\\"{{ steps.label_pages.output.byLabel.photo }}\\\". Highest priority: when set, pageFrom/pageTo and pages are ignored.\",\n \"anyOf\": [\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"pages\": {\n \"description\": \"DEPRECATED — prefer pageIndices (scattered) or pageFrom/pageTo (contiguous). Which pages to inspect: \\\"all\\\", a single [start,end] range, a list of ranges, or a template expression resolving to one of those.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"const\": \"all\"\n },\n {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"Inclusive 0-based [start, end] page range, matching ai.split page_range.\"\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"Inclusive 0-based [start, end] page range, matching ai.split page_range.\"\n }\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"const\": \"object\"\n },\n \"properties\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"required\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": [\n \"type\",\n \"properties\"\n ],\n \"additionalProperties\": false,\n \"description\": \"JSON Schema defining the structure the vision model should return. Fields not listed in `required` come back null when not found; a missing required field fails the step.\"\n },\n \"prompt\": {\n \"description\": \"Optional instruction refining the extraction. The schema drives it when omitted.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID (must support vision).\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (must support vision).\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"renderScale\": {\n \"description\": \"PDF render scale (1.0 = 72 DPI). Raise for small text or weak VLM OCR. Capped at 6 to avoid oversized page rasters.\",\n \"type\": \"number\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 6\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for rendered pages (default 85).\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"maxPages\": {\n \"description\": \"Chunk size: the maximum pages sent to the vision model in a single call. When the inspected range (or the whole document) is larger, it is split into chunks of this size and the per-chunk results are merged by a reduce pass. The reduce follows each field's DESCRIPTION: a boolean described as \\\"present on any page\\\" is OR-ed, one described as \\\"true for every page\\\" is AND-ed, and list fields are concatenated. The merge is most reliable for boolean/scalar claims; for schemas that AGGREGATE long lists across chunks it can still drop or reorder items, so prefer a bounded page range for large list extraction. Default 20, capped at 100.\",\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 100\n }\n },\n \"required\": [\n \"document\",\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Structured data matching the provided schema. The output also carries a reserved `_vision` key recording the inspected source document ref and the page indices that were rendered, so the UI can re-rasterize exactly those pages client-side. `_vision` is excluded from user-schema validation.\"\n}\n```\n\n\n#### `ai.search-files` — Search Files\n\nInvestigate a ZIP archive with a question and return an answer plus file citations. Read-only: the step opens files in the archive and never writes back. ZIP is the only accepted format in this version. Optionally scope the search to a folder prefix and cap how many files and investigation turns may run.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/search-files`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `archive` | string | yes | | Template expression or file reference for the ZIP archive to inspect. ZIP is the only accepted format in this version. |\n| `query` | string | yes | | Natural-language question to answer from files inside the archive. |\n| `root` | string | no | | Optional folder prefix inside the archive. When set, only files under this path are in scope. |\n| `provider` | string | no | | Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted. |\n| `model` | string | no | | Model override (advanced). |\n| `reasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n| `maxIterations` | integer | no | `12` | Maximum investigation turns. Default 12, capped at 50. |\n| `maxFiles` | integer | no | `50` | Maximum files the step may open. Default 50, capped at 200. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `answer` | string | yes | | The investigation answer. Citations point at inspected files; the answer text itself is model-generated. |\n| `citations` | array<object> | yes | | Citations to files the step inspected. Excerpts, when present, are copied from inspected text. |\n| `filesInspected` | array<string> | yes | | Archive-relative paths of files the step opened during investigation. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"archive\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression or file reference for the ZIP archive to inspect. ZIP is the only accepted format in this version.\"\n },\n \"query\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Natural-language question to answer from files inside the archive.\"\n },\n \"root\": {\n \"description\": \"Optional folder prefix inside the archive. When set, only files under this path are in scope.\",\n \"type\": \"string\"\n },\n \"provider\": {\n \"description\": \"Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted.\",\n \"type\": \"string\"\n },\n \"model\": {\n \"description\": \"Model override (advanced).\",\n \"type\": \"string\"\n },\n \"reasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n },\n \"maxIterations\": {\n \"description\": \"Maximum investigation turns. Default 12, capped at 50.\",\n \"default\": 12,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 50\n },\n \"maxFiles\": {\n \"description\": \"Maximum files the step may open. Default 50, capped at 200.\",\n \"default\": 50,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 200\n }\n },\n \"required\": [\n \"archive\",\n \"query\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"answer\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"The investigation answer. Citations point at inspected files; the answer text itself is model-generated.\"\n },\n \"citations\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Archive-relative path of a file the step inspected and cited.\"\n },\n \"excerpt\": {\n \"description\": \"Optional excerpt copied from the inspected file text. Omitted when no verbatim excerpt was supplied.\",\n \"type\": \"string\",\n \"maxLength\": 2000\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Citations to files the step inspected. Excerpts, when present, are copied from inspected text.\"\n },\n \"filesInspected\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Archive-relative paths of files the step opened during investigation.\"\n }\n },\n \"required\": [\n \"answer\",\n \"citations\",\n \"filesInspected\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `ai.figure-crops` — Figure Crops\n\nCrop and caption figure elements from a parsed PDF. Renders the source document, crops each kind=figure bbox from ai.parse output, and describes the crop with a vision model. Output is captions plus normalized bboxes for evidence viewers.\n\n**Behavior and examples:** `eigenpal docs read steps/ai/figure-crops`\n\n**Durable retry:** Provider request retries are separate; the workflow engine does not durably retry this step.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | Storage reference or template expression for the source PDF |\n| `parseOutput` | unknown | yes | | ai.parse output object (template {{steps.<parse>.output}}); figure elements are read from its `elements` array |\n| `model` | string | no | | Vision model for captions (defaults to workspace model) |\n| `figureInstructions` | string | no | | Custom caption instruction; applied per figure crop |\n| `maxFigures` | integer | no | `40` | Cap on figures processed per document |\n| `minAreaFrac` | number | no | `0` | Skip figures below this page-area fraction (logos/decorations) |\n| `includeCrops` | boolean | no | `false` | Include base64 JPEG crops in output (heavy; default off — captions + bboxes only) |\n| `renderScale` | number | no | `1` | Scale factor for rendering PDF pages before cropping |\n| `imageQuality` | integer | no | `85` | JPEG quality for crops |\n| `llmReasoningEffort` | `\"none\"` \\| `\"minimal\"` \\| `\"low\"` \\| `\"medium\"` \\| `\"high\"` \\| `\"xhigh\"` \\| `\"max\"` | no | | Reasoning effort for models that support it. Omit to use the selected model's default. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `figures` | array<object> | yes | | |\n| `_figureCrops` | object | yes | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"Storage reference or template expression for the source PDF\"\n },\n \"parseOutput\": {\n \"description\": \"ai.parse output object (template {{steps.<parse>.output}}); figure elements are read from its `elements` array\"\n },\n \"model\": {\n \"description\": \"Vision model for captions (defaults to workspace model)\",\n \"type\": \"string\"\n },\n \"figureInstructions\": {\n \"description\": \"Custom caption instruction; applied per figure crop\",\n \"type\": \"string\"\n },\n \"maxFigures\": {\n \"description\": \"Cap on figures processed per document\",\n \"default\": 40,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"minAreaFrac\": {\n \"description\": \"Skip figures below this page-area fraction (logos/decorations)\",\n \"default\": 0,\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n \"includeCrops\": {\n \"description\": \"Include base64 JPEG crops in output (heavy; default off — captions + bboxes only)\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"renderScale\": {\n \"description\": \"Scale factor for rendering PDF pages before cropping\",\n \"default\": 1,\n \"type\": \"number\",\n \"minimum\": 1,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for crops\",\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"llmReasoningEffort\": {\n \"description\": \"Reasoning effort for models that support it. Omit to use the selected model's default.\",\n \"type\": \"string\",\n \"enum\": [\n \"none\",\n \"minimal\",\n \"low\",\n \"medium\",\n \"high\",\n \"xhigh\",\n \"max\"\n ]\n }\n },\n \"required\": [\n \"input\",\n \"parseOutput\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"figures\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"page\": {\n \"type\": \"number\"\n },\n \"bboxNorm\": {\n \"anyOf\": [\n {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"number\"\n },\n {\n \"type\": \"number\"\n },\n {\n \"type\": \"number\"\n },\n {\n \"type\": \"number\"\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 4,\n \"maxItems\": 4\n },\n {\n \"type\": \"null\"\n }\n ]\n },\n \"areaFrac\": {\n \"type\": \"number\"\n },\n \"caption\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"cropJpegBase64\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"page\",\n \"bboxNorm\",\n \"areaFrac\",\n \"caption\"\n ],\n \"additionalProperties\": false\n }\n },\n \"_figureCrops\": {\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"number\"\n }\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"skippedSmall\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"pages\",\n \"skippedSmall\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"figures\",\n \"_figureCrops\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n### Transform steps — deterministic data transforms\n\n#### `transform.set` — Set Value\n\nSet key-value pairs in the output object\n\n**Behavior and examples:** `eigenpal docs read steps/transform/set`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fields` | record<string, unknown> | yes | | Key-value pairs to set in output |\n| `input` | record<string, unknown> | no | | Base object to extend |\n\n**Output:** `record<string, unknown>`\n\n> Object with all fields set\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fields\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Key-value pairs to set in output\"\n },\n \"input\": {\n \"description\": \"Base object to extend\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"fields\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Object with all fields set\"\n}\n```\n\n\n#### `transform.remove` — Remove Fields\n\nRemove specified fields from an object\n\n**Behavior and examples:** `eigenpal docs read steps/transform/remove`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | record<string, unknown> | no | | Object to remove fields from |\n| `fields` | array<string> | yes | | Field names to remove |\n\n**Output:** `record<string, unknown>`\n\n> Object with fields removed\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"description\": \"Object to remove fields from\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"fields\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Field names to remove\"\n }\n },\n \"required\": [\n \"fields\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Object with fields removed\"\n}\n```\n\n\n#### `transform.combine` — Combine Data\n\nMerge multiple objects or concatenate arrays\n\n**Behavior and examples:** `eigenpal docs read steps/transform/combine`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `sources` | array<string> | yes | | Template expressions for sources to combine |\n| `target` | string | yes | | Target path in output |\n| `mode` | `\"merge\"` \\| `\"concat\"` \\| `\"deep\"` | no | `\"merge\"` | |\n\n**Output:** `record<string, unknown> \\| array<unknown>`\n\n> Combined result\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"sources\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Template expressions for sources to combine\"\n },\n \"target\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Target path in output\"\n },\n \"mode\": {\n \"default\": \"merge\",\n \"type\": \"string\",\n \"enum\": [\n \"merge\",\n \"concat\",\n \"deep\"\n ]\n }\n },\n \"required\": [\n \"sources\",\n \"target\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"anyOf\": [\n {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n {\n \"type\": \"array\",\n \"items\": {}\n }\n ],\n \"description\": \"Combined result\"\n}\n```\n\n\n#### `transform.split` — Split Data\n\nSplit a string by delimiter or extract keys from an object\n\n**Behavior and examples:** `eigenpal docs read steps/transform/split`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string \\| record<string, unknown> | no | | String or object to split |\n| `source` | string | no | | Template expression for source |\n| `by` | string | no | `\",\"` | Delimiter for string splitting |\n| `delimiter` | string | no | | Alias for by |\n| `limit` | number | no | | Max number of splits |\n| `keys` | array<string> | no | | Keys to extract from object |\n\n**Output:** `array<string> \\| object`\n\n> Split result - array or extracted/remaining object\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"description\": \"String or object to split\",\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n ]\n },\n \"source\": {\n \"description\": \"Template expression for source\",\n \"type\": \"string\"\n },\n \"by\": {\n \"description\": \"Delimiter for string splitting\",\n \"default\": \",\",\n \"type\": \"string\"\n },\n \"delimiter\": {\n \"description\": \"Alias for by\",\n \"type\": \"string\"\n },\n \"limit\": {\n \"description\": \"Max number of splits\",\n \"type\": \"number\"\n },\n \"keys\": {\n \"description\": \"Keys to extract from object\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"anyOf\": [\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"extracted\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"remaining\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"extracted\",\n \"remaining\"\n ],\n \"additionalProperties\": false\n }\n ],\n \"description\": \"Split result - array or extracted/remaining object\"\n}\n```\n\n\n#### `transform.merge` — Merge Inputs\n\nMerge multiple named inputs into a single output\n\n**Behavior and examples:** `eigenpal docs read steps/transform/merge`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | record<string, unknown> | no | | Named inputs to merge; each key becomes a key in the merged output |\n| `preservePortNames` | boolean | no | `true` | |\n| `outputKey` | string | no | | |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | array<unknown> | yes | | |\n| `count` | number | yes | | |\n| `merged` | record<string, unknown> | no | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"description\": \"Named inputs to merge; each key becomes a key in the merged output\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"preservePortNames\": {\n \"default\": true,\n \"type\": \"boolean\"\n },\n \"outputKey\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"array\",\n \"items\": {}\n },\n \"count\": {\n \"type\": \"number\"\n },\n \"merged\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"required\": [\n \"items\",\n \"count\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.template` — Fill Template\n\nFill a DOCX or XLSX workspace template with data from previous steps. Reference a tmpl_... id, or a local ./templates/file.xlsx path (CLI push uploads it). Git agent templates use the fill-template skill instead and cannot be referenced here. File IDs (file_...) are not accepted. Placeholders are auto-detected. In the Office file use {placeholder} and {table:array.prop}; {{placeholder}} in an XLSX file is rejected ({{ }} is YAML Liquid only).\n\n**Behavior and examples:** `eigenpal docs read steps/transform/template`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `templateId` | string | no | | Workspace template ID (tmpl_...) from the Templates table (DOCX or XLSX). Git agent templates cannot be referenced here. File IDs (file_...) are not accepted. Mutually exclusive with `template`. |\n| `template` | string | no | | Local DOCX or XLSX path relative to the workflow YAML (e.g. ./templates/foo.xlsx). CLI push keeps the real path inside the workflow project unless you pass --allow-external-templates, uploads unmatched files as new tmpl_ resources, and does not rewrite the source YAML. Mutually exclusive with templateId. |\n| `templateRevisionId` | string | no | | Immutable template revision ID (tmpr_...). Pin this when executions must keep using the same template bytes after replacements. Requires templateId; local `template` paths are pinned automatically on push. |\n| `data` | record<string, unknown> | yes | | Data object to merge into template. Each key must be explicitly defined - cannot pass a whole object as single expression. |\n| `outputFilename` | string | no | | Output filename - supports {{field}} syntax; .docx or .xlsx extension is added if omitted |\n| `highlightNotFound` | boolean | no | `true` | Highlight missing variables with red-colored text in the output document (DOCX only; ignored for XLSX) |\n| `notFoundText` | string | no | `\"NOT FOUND\"` | Text to display for missing variables when highlightNotFound is enabled (DOCX only; ignored for XLSX) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from files table |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"templateId\": {\n \"description\": \"Workspace template ID (tmpl_...) from the Templates table (DOCX or XLSX). Git agent templates cannot be referenced here. File IDs (file_...) are not accepted. Mutually exclusive with `template`.\",\n \"type\": \"string\",\n \"pattern\": \"^tmpl_[A-Za-z0-9_-]{21}$\"\n },\n \"template\": {\n \"description\": \"Local DOCX or XLSX path relative to the workflow YAML (e.g. ./templates/foo.xlsx). CLI push keeps the real path inside the workflow project unless you pass --allow-external-templates, uploads unmatched files as new tmpl_ resources, and does not rewrite the source YAML. Mutually exclusive with templateId.\",\n \"type\": \"string\"\n },\n \"templateRevisionId\": {\n \"description\": \"Immutable template revision ID (tmpr_...). Pin this when executions must keep using the same template bytes after replacements. Requires templateId; local `template` paths are pinned automatically on push.\",\n \"type\": \"string\",\n \"pattern\": \"^tmpr_[A-Za-z0-9_-]{21}$\"\n },\n \"data\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Data object to merge into template. Each key must be explicitly defined - cannot pass a whole object as single expression.\"\n },\n \"outputFilename\": {\n \"description\": \"Output filename - supports {{field}} syntax; .docx or .xlsx extension is added if omitted\",\n \"type\": \"string\"\n },\n \"highlightNotFound\": {\n \"description\": \"Highlight missing variables with red-colored text in the output document (DOCX only; ignored for XLSX)\",\n \"default\": true,\n \"type\": \"boolean\"\n },\n \"notFoundText\": {\n \"description\": \"Text to display for missing variables when highlightNotFound is enabled (DOCX only; ignored for XLSX)\",\n \"default\": \"NOT FOUND\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"data\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from files table\"\n }\n },\n \"required\": [\n \"fileId\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.pdf-embed` — Embed PDF Text\n\nEmbed OCR text layer into scanned PDFs/images to make them searchable\n\n**Behavior and examples:** `eigenpal docs read steps/transform/pdf-embed`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | File input - template expression e.g. {{input.document}} |\n| `parseResult` | string | yes | | Parse result - template expression e.g. {{steps.parse.output}} |\n| `outputFilename` | string | no | | Output filename - supports {{filename}} syntax |\n| `confidenceThreshold` | number | no | `0.7` | Minimum OCR confidence (0-1) to include a word |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from files table |\n| `pageCount` | number | yes | | Number of pages in the output PDF |\n| `wordCount` | number | yes | | Number of words embedded |\n| `text` | string | yes | | Extracted text from the document |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"File input - template expression e.g. {{input.document}}\"\n },\n \"parseResult\": {\n \"type\": \"string\",\n \"description\": \"Parse result - template expression e.g. {{steps.parse.output}}\"\n },\n \"outputFilename\": {\n \"description\": \"Output filename - supports {{filename}} syntax\",\n \"type\": \"string\"\n },\n \"confidenceThreshold\": {\n \"description\": \"Minimum OCR confidence (0-1) to include a word\",\n \"default\": 0.7,\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n },\n \"required\": [\n \"input\",\n \"parseResult\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from files table\"\n },\n \"pageCount\": {\n \"type\": \"number\",\n \"description\": \"Number of pages in the output PDF\"\n },\n \"wordCount\": {\n \"type\": \"number\",\n \"description\": \"Number of words embedded\"\n },\n \"text\": {\n \"type\": \"string\",\n \"description\": \"Extracted text from the document\"\n }\n },\n \"required\": [\n \"fileId\",\n \"pageCount\",\n \"wordCount\",\n \"text\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.crop-regions` — Crop Regions\n\nRender a PDF or image and crop normalized bounding boxes into JPEG run output artifacts. Pair with transform.script (bbox lists from ai.parse layout) and ai.extract or ai.vision for captions.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/crop-regions`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | File input — template expression e.g. {{ input.document }} resolving to a PDF or image |\n| `regions` | string \\| array<object> | yes | | Regions to crop — pageIndex + normalized bbox per entry |\n| `renderScale` | number | no | `1` | Scale factor when rasterizing PDF pages before cropping |\n| `imageQuality` | integer | no | `85` | JPEG quality for cropped outputs |\n| `paddingFrac` | number | no | `0.02` | Padding around each bbox as a fraction of the shorter page edge |\n| `minCropPx` | integer | no | `8` | Minimum crop width/height in pixels; smaller crops fall back to the full page |\n| `maxRegions` | integer | no | `100` | Maximum regions processed per invocation |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `regions` | array<object> | yes | | Successfully cropped regions |\n| `skipped` | integer | no | | Regions skipped (invalid bbox or missing page) |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"description\": \"File input — template expression e.g. {{ input.document }} resolving to a PDF or image\"\n },\n \"regions\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to a region array, e.g. {{ steps.list-figures.output.regions }}\"\n },\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"description\": \"Stable region id used in output and crop filenames (defaults to region-N)\",\n \"type\": \"string\"\n },\n \"pageIndex\": {\n \"description\": \"0-based page index to crop from (images use page 0)\",\n \"default\": 0,\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"bbox\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 4,\n \"maxItems\": 4,\n \"description\": \"Normalized axis-aligned bbox [x0, y0, x1, y1]\"\n }\n },\n \"required\": [\n \"bbox\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Regions to crop from the rendered document\"\n }\n ],\n \"description\": \"Regions to crop — pageIndex + normalized bbox per entry\"\n },\n \"renderScale\": {\n \"description\": \"Scale factor when rasterizing PDF pages before cropping\",\n \"default\": 1,\n \"type\": \"number\",\n \"minimum\": 0.5,\n \"maximum\": 4\n },\n \"imageQuality\": {\n \"description\": \"JPEG quality for cropped outputs\",\n \"default\": 85,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100\n },\n \"paddingFrac\": {\n \"description\": \"Padding around each bbox as a fraction of the shorter page edge\",\n \"default\": 0.02,\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 0.2\n },\n \"minCropPx\": {\n \"description\": \"Minimum crop width/height in pixels; smaller crops fall back to the full page\",\n \"default\": 8,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991\n },\n \"maxRegions\": {\n \"description\": \"Maximum regions processed per invocation\",\n \"default\": 100,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 200\n }\n },\n \"required\": [\n \"input\",\n \"regions\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"regions\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"description\": \"Region id (from input or auto-generated)\"\n },\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"0-based page index the crop was taken from\"\n },\n \"bbox\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 4,\n \"maxItems\": 4,\n \"description\": \"Normalized bbox that was cropped\"\n },\n \"width\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991,\n \"description\": \"Crop width in pixels\"\n },\n \"height\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991,\n \"description\": \"Crop height in pixels\"\n },\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"Run output file id for the JPEG crop\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Stored crop filename\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"const\": \"image/jpeg\",\n \"description\": \"Always image/jpeg\"\n },\n \"size\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"JPEG size in bytes\"\n }\n },\n \"required\": [\n \"id\",\n \"pageIndex\",\n \"bbox\",\n \"width\",\n \"height\",\n \"fileId\",\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Successfully cropped regions\"\n },\n \"skipped\": {\n \"description\": \"Regions skipped (invalid bbox or missing page)\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"regions\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.xlsx-to-json` — Spreadsheet to JSON\n\nConvert 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.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/xlsx-to-json`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string | yes | | File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime |\n| `sheet` | integer \\| string | no | | Sheet to read: 0-based index or exact sheet name. Omit for the first sheet. |\n| `outputCsv` | boolean | no | `false` | If true, also write CSV to storage and include fileId. Zero-config uses SheetJS CSV of the effective sheet extent, excluding empty trailing rows and columns. When columns, range, headerRow, valueMode, blankCells, or blankRows are set, CSV matches that projection. |\n| `includeCellMetadata` | boolean | no | `false` | Include original cell address, type, raw/displayed value, number format and date rendering. Also includes sheet metadata with the workbook date system. Does not classify identifiers or clean names. |\n| `includeMetadata` | boolean | no | `false` | If true, include sheet metadata and diagnostics in the step output. includeCellMetadata also enables these. Omit to keep output as rows (and fileId when outputCsv is true). Warnings are still logged when this is false. |\n| `outputFilename` | string | no | | Output CSV filename when outputCsv is true - supports LiquidJS e.g. {{filename}}.csv |\n| `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. |\n| `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. |\n| `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. |\n| `range` | string | no | | Optional rectangular A1 range without a sheet qualifier, e.g. A1:D20. Disjoint ranges are rejected. |\n| `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. |\n| `blankRows` | `\"skip\"` \\| `\"keep\"` | no | `\"skip\"` | skip (default) drops rows whose projected columns are all truly empty. keep retains them. Detection uses projected columns only. |\n| `limits` | object | no | | Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `cellMetadata` | array<object> | no | | Evidence for nonblank projected data cells, linked to rows by outputRowIndex and key. Present when includeCellMetadata is true. |\n| `rows` | array<record<string, unknown>> | yes | | Array of row objects (first row = headers as keys unless headerRow is false) |\n| `fileId` | string | no | | File ID of stored CSV when outputCsv is true |\n| `sheet` | object | no | | Selected sheet metadata after projection. Present when includeMetadata or includeCellMetadata is true. |\n| `diagnostics` | array<object> | no | | Non-fatal warnings collected while reading the sheet. Present when includeMetadata or includeCellMetadata is true. Warnings are still logged when metadata is omitted. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime\"\n },\n \"sheet\": {\n \"description\": \"Sheet to read: 0-based index or exact sheet name. Omit for the first sheet.\",\n \"anyOf\": [\n {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"string\"\n }\n ]\n },\n \"outputCsv\": {\n \"description\": \"If true, also write CSV to storage and include fileId. Zero-config uses SheetJS CSV of the effective sheet extent, excluding empty trailing rows and columns. When columns, range, headerRow, valueMode, blankCells, or blankRows are set, CSV matches that projection.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"includeCellMetadata\": {\n \"description\": \"Include original cell address, type, raw/displayed value, number format and date rendering. Also includes sheet metadata with the workbook date system. Does not classify identifiers or clean names.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"includeMetadata\": {\n \"description\": \"If true, include sheet metadata and diagnostics in the step output. includeCellMetadata also enables these. Omit to keep output as rows (and fileId when outputCsv is true). Warnings are still logged when this is false.\",\n \"default\": false,\n \"type\": \"boolean\"\n },\n \"outputFilename\": {\n \"description\": \"Output CSV filename when outputCsv is true - supports LiquidJS e.g. {{filename}}.csv\",\n \"type\": \"string\"\n },\n \"headerRow\": {\n \"description\": \"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.\",\n \"anyOf\": [\n {\n \"type\": \"boolean\",\n \"const\": false\n },\n {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991\n }\n ]\n },\n \"columns\": {\n \"description\": \"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.\",\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Output object key for this column\"\n },\n \"index\": {\n \"description\": \"0-based absolute worksheet column. Use instead of header.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"header\": {\n \"description\": \"Exact displayed header text. Use instead of index. Requires a header row.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"occurrence\": {\n \"description\": \"1-based occurrence of header when the same displayed header appears more than once. Only valid with header.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"key\"\n ],\n \"additionalProperties\": false\n }\n },\n \"valueMode\": {\n \"description\": \"raw (default) returns typed cached cell values. displayed returns formatted cell text (dates, leading zeros, punctuation, diacritics, embedded newlines). Formulas are never calculated.\",\n \"default\": \"raw\",\n \"type\": \"string\",\n \"enum\": [\n \"raw\",\n \"displayed\"\n ]\n },\n \"range\": {\n \"description\": \"Optional rectangular A1 range without a sheet qualifier, e.g. A1:D20. Disjoint ranges are rejected.\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"blankCells\": {\n \"description\": \"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.\",\n \"default\": \"empty-string\",\n \"type\": \"string\",\n \"enum\": [\n \"empty-string\",\n \"null\",\n \"omit\"\n ]\n },\n \"blankRows\": {\n \"description\": \"skip (default) drops rows whose projected columns are all truly empty. keep retains them. Detection uses projected columns only.\",\n \"default\": \"skip\",\n \"type\": \"string\",\n \"enum\": [\n \"skip\",\n \"keep\"\n ]\n },\n \"limits\": {\n \"type\": \"object\",\n \"properties\": {\n \"maxInputBytes\": {\n \"description\": \"Maximum input file size in bytes. Omitted uses the server default (52,428,800, 50 MiB). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 52428800\n },\n \"maxRows\": {\n \"description\": \"Maximum rows in the selected range. Omitted uses the server default (100,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100000\n },\n \"maxColumns\": {\n \"description\": \"Maximum columns in the selected range. Omitted uses the server default (256). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 256\n },\n \"maxCells\": {\n \"description\": \"Maximum cells in the selected range. Omitted uses the server default (5,000,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 5000000\n }\n },\n \"additionalProperties\": false,\n \"description\": \"Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults.\"\n }\n },\n \"required\": [\n \"input\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"cellMetadata\": {\n \"description\": \"Evidence for nonblank projected data cells, linked to rows by outputRowIndex and key. Present when includeCellMetadata is true.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"address\": {\n \"type\": \"string\",\n \"description\": \"Original A1 cell address\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Excel storage type: n=number, s=string, b=boolean, e=error, d=date, z=blank. A numeric date remains type n.\"\n },\n \"rawValue\": {\n \"description\": \"Stored cached value; formulas are never evaluated\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"displayedValue\": {\n \"type\": \"string\",\n \"description\": \"Value formatted using the workbook number format and date system\"\n },\n \"numberFormat\": {\n \"type\": \"string\"\n },\n \"formula\": {\n \"type\": \"string\"\n },\n \"dateValue\": {\n \"description\": \"Calendar rendering for a valid date-formatted serial, without a timezone. Evidence of Excel formatting, not a business classification.\",\n \"type\": \"string\"\n },\n \"excelLeapDay\": {\n \"description\": \"True for the fictitious 1900-02-29 in the Excel 1900 date system\",\n \"type\": \"boolean\"\n },\n \"key\": {\n \"type\": \"string\"\n },\n \"outputRowIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"address\",\n \"type\",\n \"displayedValue\",\n \"key\",\n \"outputRowIndex\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rows\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"description\": \"Array of row objects (first row = headers as keys unless headerRow is false)\"\n },\n \"fileId\": {\n \"description\": \"File ID of stored CSV when outputCsv is true\",\n \"type\": \"string\"\n },\n \"sheet\": {\n \"description\": \"Selected sheet metadata after projection. Present when includeMetadata or includeCellMetadata is true.\",\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Selected sheet name\"\n },\n \"declaredRange\": {\n \"description\": \"Worksheet declared extent before empty trailing rows/columns were removed\",\n \"type\": \"string\"\n },\n \"dateSystem\": {\n \"description\": \"Workbook Excel date system\",\n \"type\": \"string\",\n \"enum\": [\n \"1900\",\n \"1904\"\n ]\n },\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"0-based sheet index in the workbook\"\n },\n \"range\": {\n \"type\": \"string\",\n \"description\": \"Effective rectangular A1 range that was read\"\n },\n \"rowCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of data rows returned in rows\"\n },\n \"columns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Output keys in order\"\n }\n },\n \"required\": [\n \"name\",\n \"index\",\n \"range\",\n \"rowCount\",\n \"columns\"\n ],\n \"additionalProperties\": false\n },\n \"diagnostics\": {\n \"description\": \"Non-fatal warnings collected while reading the sheet. Present when includeMetadata or includeCellMetadata is true. Warnings are still logged when metadata is omitted.\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"severity\": {\n \"type\": \"string\",\n \"const\": \"warning\",\n \"description\": \"Diagnostic severity\"\n },\n \"code\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Stable diagnostic code\"\n },\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Human-readable diagnostic message\"\n },\n \"cell\": {\n \"description\": \"A1 address of the related cell when applicable\",\n \"type\": \"string\"\n },\n \"row\": {\n \"description\": \"1-based Excel row when applicable\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n \"column\": {\n \"description\": \"0-based worksheet column when applicable\",\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"severity\",\n \"code\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"rows\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.json-to-xlsx` — JSON to XLSX\n\nConvert JSON rows into an XLSX spreadsheet. Pair with transform.xlsx-to-json. Formula-looking strings stay text; nested cell values are rejected.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/json-to-xlsx`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `filename` | string | no | | Output filename — supports LiquidJS; .xlsx is added if omitted |\n| `columns` | array<object> | no | | Ordered columns for a single-sheet workbook. Use sheets for multiple sheets. |\n| `rows` | string \\| array<record<string, unknown>> | no | | Array of row objects, or a template expression that resolves to one |\n| `sheets` | array<object> | no | | Multiple sheets. Do not combine with top-level columns/rows. |\n| `limits` | object | no | | Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from the files table |\n| `filename` | string | yes | | Sanitized output filename including .xlsx |\n| `sheetCount` | integer | yes | | Number of sheets in the workbook |\n| `sheets` | array<object> | yes | | Per-sheet name and row count |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"description\": \"Output filename — supports LiquidJS; .xlsx is added if omitted\",\n \"type\": \"string\"\n },\n \"columns\": {\n \"description\": \"Ordered columns for a single-sheet workbook. Use sheets for multiple sheets.\",\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Row object key to read for this column\"\n },\n \"header\": {\n \"description\": \"Header cell text. Defaults to key.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"date\"\n ],\n \"description\": \"Cell type. Omit to infer from the JSON value. YYYY-MM-DD strings stay text unless type is date.\"\n }\n },\n \"required\": [\n \"key\"\n ],\n \"additionalProperties\": false\n }\n },\n \"rows\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to an array of row objects, e.g. {{ steps.extract.output.items }}\"\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"description\": \"Array of row objects\"\n }\n ],\n \"description\": \"Array of row objects, or a template expression that resolves to one\"\n },\n \"sheets\": {\n \"description\": \"Multiple sheets. Do not combine with top-level columns/rows.\",\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Sheet name. Defaults to Sheet1, Sheet2, …. Excel limit: 31 characters. Cannot contain : \\\\ / ? * [ ], cannot start or end with a single quote, and History is reserved.\"\n },\n \"columns\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"key\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Row object key to read for this column\"\n },\n \"header\": {\n \"description\": \"Header cell text. Defaults to key.\",\n \"type\": \"string\"\n },\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"date\"\n ],\n \"description\": \"Cell type. Omit to infer from the JSON value. YYYY-MM-DD strings stay text unless type is date.\"\n }\n },\n \"required\": [\n \"key\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Ordered columns for this sheet\"\n },\n \"rows\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to an array of row objects, e.g. {{ steps.extract.output.items }}\"\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"description\": \"Array of row objects\"\n }\n ],\n \"description\": \"Array of row objects, or a template expression that resolves to one\"\n }\n },\n \"required\": [\n \"columns\",\n \"rows\"\n ],\n \"additionalProperties\": false\n }\n },\n \"limits\": {\n \"type\": \"object\",\n \"properties\": {\n \"maxSheets\": {\n \"description\": \"Maximum worksheets. Omitted uses the server default (50). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 50\n },\n \"maxRowsPerSheet\": {\n \"description\": \"Maximum data rows per sheet. Omitted uses the server default (100,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 100000\n },\n \"maxTotalRows\": {\n \"description\": \"Maximum data rows summed across all sheets. Omitted uses the server default (250,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 250000\n },\n \"maxColumns\": {\n \"description\": \"Maximum columns per sheet. Omitted uses the server default (256). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 256\n },\n \"maxTotalCells\": {\n \"description\": \"Maximum populated cells across the workbook. Omitted uses the server default (5,000,000). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 5000000\n },\n \"maxOutputBytes\": {\n \"description\": \"Maximum serialized .xlsx size in bytes. Omitted uses the server default (52,428,800, 50 MiB). Cannot exceed it.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 52428800\n }\n },\n \"additionalProperties\": false,\n \"description\": \"Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from the files table\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Sanitized output filename including .xlsx\"\n },\n \"sheetCount\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of sheets in the workbook\"\n },\n \"sheets\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Written sheet name\"\n },\n \"rowCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of data rows written (excludes header)\"\n }\n },\n \"required\": [\n \"name\",\n \"rowCount\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Per-sheet name and row count\"\n }\n },\n \"required\": [\n \"fileId\",\n \"filename\",\n \"sheetCount\",\n \"sheets\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.script` — Script\n\nExecute a TypeScript function in a QuickJS sandbox. Input keys become function parameters in any order, and the required `: R` return-type annotation IS this step's output schema: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/script`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `inputs` | record<string, string> | no | | Named inputs mapped from template expressions. Keys become function parameters; parameter order is independent of YAML/JSON key order: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`. |\n| `function` | string | yes | | TypeScript function declaration. Must be `function script(args): R { … }` where parameter names exactly match the configured input keys in any order and `R` is a return type annotation. The annotation IS this step's output schema. |\n| `timeout` | number | no | `5000` | Max execution time in milliseconds (default: 5000) |\n| `memoryLimit` | number | no | `10485760` | Max memory in bytes (default: 10MB) |\n\n**Output:** `unknown`\n\n> Value returned from script. Validated at runtime against the JSON Schema derived from the function's return type annotation.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"inputs\": {\n \"description\": \"Named inputs mapped from template expressions. Keys become function parameters; parameter order is independent of YAML/JSON key order: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"function\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 50000,\n \"description\": \"TypeScript function declaration. Must be `function script(args): R { … }` where parameter names exactly match the configured input keys in any order and `R` is a return type annotation. The annotation IS this step's output schema.\"\n },\n \"timeout\": {\n \"description\": \"Max execution time in milliseconds (default: 5000)\",\n \"default\": 5000,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n },\n \"memoryLimit\": {\n \"description\": \"Max memory in bytes (default: 10MB)\",\n \"default\": 10485760,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n }\n },\n \"required\": [\n \"function\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"description\": \"Value returned from script. Validated at runtime against the JSON Schema derived from the function's return type annotation.\"\n}\n```\n\n\n#### `transform.text-chunker` — Text Chunker\n\nSplit long text into chunks with regex-anchored boundaries, overlap, and header preservation. Accepts raw text or a parsed-document object; chunks carry source page indexes when pages are provided.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/text-chunker`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string \\| record<string, unknown> | yes | | Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }` (e.g. `{{ steps.parse.output }}`). Pages preserve per-chunk page provenance. |\n| `maxChars` | integer | yes | | Target chunk size in characters. Hard ceiling per chunk is 1.5×. |\n| `overlap` | integer | no | `0` | Characters duplicated at chunk boundaries (default 0). Must be < maxChars / 2. |\n| `splitOn` | array<string> | no | | Ordered list of regexes; the first that matches near the chunk boundary wins. Falls back to char-cut when none match. Tip: list narrowest first (e.g. /\\d+\\.\\d+\\s+/ before /\\n\\n+/). |\n| `maxChunks` | integer | no | `64` | Safety cap; later chunks are dropped and `summary.truncated` flips to true. |\n| `preserveHeader` | integer | no | `0` | Prepend the first N characters of the input to every chunk (good for \"always include the contract title\"). |\n| `minChunkChars` | integer | no | `0` | Trailing chunks shorter than this are merged into the previous chunk. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `chunks` | array<object> | yes | | |\n| `summary` | object | yes | | |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"pages\"\n ],\n \"additionalProperties\": {}\n }\n ],\n \"description\": \"Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }` (e.g. `{{ steps.parse.output }}`). Pages preserve per-chunk page provenance.\"\n },\n \"maxChars\": {\n \"type\": \"integer\",\n \"minimum\": 100,\n \"maximum\": 100000,\n \"description\": \"Target chunk size in characters. Hard ceiling per chunk is 1.5×.\"\n },\n \"overlap\": {\n \"default\": 0,\n \"description\": \"Characters duplicated at chunk boundaries (default 0). Must be < maxChars / 2.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"splitOn\": {\n \"description\": \"Ordered list of regexes; the first that matches near the chunk boundary wins. Falls back to char-cut when none match. Tip: list narrowest first (e.g. /\\\\d+\\\\.\\\\d+\\\\s+/ before /\\\\n\\\\n+/).\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"maxChunks\": {\n \"default\": 64,\n \"description\": \"Safety cap; later chunks are dropped and `summary.truncated` flips to true.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 1000\n },\n \"preserveHeader\": {\n \"default\": 0,\n \"description\": \"Prepend the first N characters of the input to every chunk (good for \\\"always include the contract title\\\").\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"minChunkChars\": {\n \"default\": 0,\n \"description\": \"Trailing chunks shorter than this are merged into the previous chunk.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"maxChars\",\n \"overlap\",\n \"maxChunks\",\n \"preserveHeader\",\n \"minChunkChars\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"chunks\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"index\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"total\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"startOffset\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"endOffset\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"pages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"description\": \"Page indexes that contributed text to this chunk (empty for raw-string input).\"\n }\n },\n \"required\": [\n \"text\",\n \"index\",\n \"total\",\n \"startOffset\",\n \"endOffset\",\n \"pages\"\n ],\n \"additionalProperties\": false\n }\n },\n \"summary\": {\n \"type\": \"object\",\n \"properties\": {\n \"inputChars\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"totalChunks\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"avgChunkChars\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"maxChunkChars\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"truncated\": {\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"inputChars\",\n \"totalChunks\",\n \"avgChunkChars\",\n \"maxChunkChars\",\n \"truncated\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"chunks\",\n \"summary\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.regex-extract` — Regex Extract\n\nPull named fields from text via regex patterns (deterministic counterpart to ai.extract). Accepts raw text or a parsed-document object; matches carry `_evidence.pageIndex` when pages are provided.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/regex-extract`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `input` | string \\| record<string, unknown> | yes | | Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }`. Pages enable per-match `_evidence.pageIndex`. |\n| `fields` | record<string, object> | yes | | Named field → pattern mapping. |\n| `flags` | string | no | | Default regex flags applied when a field omits its own `flags`. Subset of \"gimsuy\". |\n| `searchWindow` | integer | no | | Only search the first N characters of input (perf). Omit for full search. |\n\n**Output:** `record<string, unknown>`\n\n> Field name → extracted value (or default), plus `_evidence: { [field]: { pageIndex, matchOffset, raw } }` and `_unmatched: string[]`.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"anyOf\": [\n {\n \"type\": \"string\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"pages\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"pageIndex\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"text\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"pageIndex\",\n \"text\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"pages\"\n ],\n \"additionalProperties\": {}\n }\n ],\n \"description\": \"Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }`. Pages enable per-match `_evidence.pageIndex`.\"\n },\n \"fields\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"pattern\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Regex source. Must contain at least one capturing group.\"\n },\n \"flags\": {\n \"description\": \"Per-field regex flags (overrides the step-level `flags`). Subset of \\\"gimsuy\\\".\",\n \"type\": \"string\",\n \"pattern\": \"^(?!.*(.).*\\\\1)[gimsuy]*$\"\n },\n \"max\": {\n \"default\": 1,\n \"description\": \"Max matches to keep. Default 1. Use \\\"all\\\" plus `select` to combine multiple hits.\",\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"const\": 1\n },\n {\n \"type\": \"string\",\n \"const\": \"all\"\n },\n {\n \"type\": \"integer\",\n \"exclusiveMinimum\": 0,\n \"maximum\": 9007199254740991\n }\n ]\n },\n \"select\": {\n \"description\": \"When max ≠ 1: which match to surface. \\\"first\\\" (default), \\\"last\\\", \\\"min\\\", \\\"max\\\", or \\\"all\\\" — `all` returns the full array of matches AND a parallel array of evidence entries.\",\n \"type\": \"string\",\n \"enum\": [\n \"first\",\n \"last\",\n \"min\",\n \"max\",\n \"all\"\n ]\n },\n \"normalize\": {\n \"type\": \"string\",\n \"enum\": [\n \"strip-spaces\",\n \"strip-punct\",\n \"collapse-whitespace\",\n \"lower\",\n \"upper\",\n \"trim\"\n ]\n },\n \"format\": {\n \"description\": \"Post-processing. iso-date accepts DD.MM.YYYY (1 group) or DD/MM/YYYY split across 3 groups → \\\"YYYY-MM-DD\\\".\",\n \"type\": \"string\",\n \"enum\": [\n \"iso-date\",\n \"iso-number\",\n \"lower\",\n \"upper\",\n \"trim\"\n ]\n },\n \"exclude\": {\n \"description\": \"Post-normalize values to skip (known wrong matches).\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"default\": {\n \"description\": \"Value when nothing matches.\",\n \"type\": \"string\"\n },\n \"contextChars\": {\n \"description\": \"When > 0, evidence entries gain `contextBefore` and `contextAfter` snippets of N characters surrounding the match. Useful for UI/debug display.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 2000\n }\n },\n \"required\": [\n \"pattern\",\n \"max\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Named field → pattern mapping.\"\n },\n \"flags\": {\n \"description\": \"Default regex flags applied when a field omits its own `flags`. Subset of \\\"gimsuy\\\".\",\n \"type\": \"string\",\n \"pattern\": \"^(?!.*(.).*\\\\1)[gimsuy]*$\"\n },\n \"searchWindow\": {\n \"description\": \"Only search the first N characters of input (perf). Omit for full search.\",\n \"type\": \"integer\",\n \"minimum\": 100,\n \"maximum\": 9007199254740991\n }\n },\n \"required\": [\n \"input\",\n \"fields\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Field name → extracted value (or default), plus `_evidence: { [field]: { pageIndex, matchOffset, raw } }` and `_unmatched: string[]`.\"\n}\n```\n\n\n#### `transform.archive-list` — List Archive\n\nList files inside a ZIP archive. Returns sorted normalized paths with compressed and uncompressed sizes. Optionally filter by folder prefix or substring, then page with offset and limit. ZIP is the only accepted format in this version. Pair with foreach or parallel_map and transform.archive-extract to open individual files.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/archive-list`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `archive` | string | yes | | Template expression or file reference for the ZIP archive to list. ZIP is the only accepted format in this version. |\n| `prefix` | string | no | | Optional folder prefix inside the archive after path normalization (for example invoices or invoices/). |\n| `search` | string | no | | Optional case-insensitive substring match on the normalized archive path. |\n| `offset` | integer | no | | Number of matching entries to skip after sorting. Default 0. |\n| `limit` | integer | no | | Maximum matching entries to return after sorting. Capped at 10000. Omit to return every matching entry up to that cap. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `entries` | array<object> | yes | | Matching files, sorted by normalized path. Directories and junk paths are omitted. |\n| `total` | integer | yes | | Number of matching entries before offset/limit pagination. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"archive\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression or file reference for the ZIP archive to list. ZIP is the only accepted format in this version.\"\n },\n \"prefix\": {\n \"description\": \"Optional folder prefix inside the archive after path normalization (for example invoices or invoices/).\",\n \"type\": \"string\"\n },\n \"search\": {\n \"description\": \"Optional case-insensitive substring match on the normalized archive path.\",\n \"type\": \"string\"\n },\n \"offset\": {\n \"description\": \"Number of matching entries to skip after sorting. Default 0.\",\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991\n },\n \"limit\": {\n \"description\": \"Maximum matching entries to return after sorting. Capped at 10000. Omit to return every matching entry up to that cap.\",\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 10000\n }\n },\n \"required\": [\n \"archive\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"entries\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Normalized archive-relative path\"\n },\n \"compressedSize\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Declared compressed size in bytes\"\n },\n \"uncompressedSize\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Declared uncompressed size in bytes\"\n }\n },\n \"required\": [\n \"path\",\n \"compressedSize\",\n \"uncompressedSize\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Matching files, sorted by normalized path. Directories and junk paths are omitted.\"\n },\n \"total\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of matching entries before offset/limit pagination.\"\n }\n },\n \"required\": [\n \"entries\",\n \"total\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.archive-extract` — Extract Archive File\n\nExtract exactly one file from a ZIP archive and store it as a run output file. Downstream steps can pass {{ steps.extract.output }} into Parse, Vision, or another archive step. Nested ZIPs are stored as ZIP files, not unpacked. Each extraction is capped at 64 MiB. ZIP is the only accepted format in this version.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/archive-extract`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `archive` | string | yes | | Template expression or file reference for the ZIP archive. ZIP is the only accepted format in this version. |\n| `path` | string | yes | | Archive-relative path of the single file to extract, for example {{ item.path }} from a prior archive-list step. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `fileId` | string | yes | | File ID from the files table |\n| `path` | string | yes | | Normalized archive-relative path that was extracted |\n| `filename` | string | yes | | Basename of the extracted file |\n| `mimeType` | string | yes | | Detected MIME type of the extracted file |\n| `size` | integer | yes | | Uncompressed size in bytes |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"archive\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression or file reference for the ZIP archive. ZIP is the only accepted format in this version.\"\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Archive-relative path of the single file to extract, for example {{ item.path }} from a prior archive-list step.\"\n }\n },\n \"required\": [\n \"archive\",\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID from the files table\"\n },\n \"path\": {\n \"type\": \"string\",\n \"description\": \"Normalized archive-relative path that was extracted\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Basename of the extracted file\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"description\": \"Detected MIME type of the extracted file\"\n },\n \"size\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Uncompressed size in bytes\"\n }\n },\n \"required\": [\n \"fileId\",\n \"path\",\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `transform.merge-documents` — Merge Documents\n\nConcatenate several files into one PDF run output, in order. Accepts PDFs, images (multi-page TIFF included) and Word, PowerPoint, OpenDocument or RTF documents. Use it when one logical document arrives as several uploads: pass {{ steps.merge.output.file }} into Parse so page labels, page ranges and vision page indices stay continuous across every source. Output sources[] maps each input file to its merged page range.\n\n**Behavior and examples:** `eigenpal docs read steps/transform/merge-documents`\n\n**Durable retry:** Transforms, including those that write files, are not durably retried.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `files` | string | yes | | Template expression resolving to the files to merge, in order: a file list input such as {{ input.documents }}, or a single file. PDF, images (JPEG, PNG, TIFF, WebP, GIF) and Word, PowerPoint, OpenDocument or RTF documents. |\n| `filename` | string | no | | Filename of the merged PDF. Defaults to merged.pdf; .pdf is appended when missing. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `file` | object | yes | | The merged PDF. Pass {{ steps.<step>.output.file }} to Parse, Vision or any other file input. |\n| `pageCount` | integer | yes | | Total pages in the merged PDF |\n| `sources` | array<object> | yes | | One entry per input file, in merge order, with the merged page range it occupies. Use it to map a merged page index back to its source file. |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"files\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression resolving to the files to merge, in order: a file list input such as {{ input.documents }}, or a single file. PDF, images (JPEG, PNG, TIFF, WebP, GIF) and Word, PowerPoint, OpenDocument or RTF documents.\"\n },\n \"filename\": {\n \"description\": \"Filename of the merged PDF. Defaults to merged.pdf; .pdf is appended when missing.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"files\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"file\": {\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"description\": \"File ID of the merged PDF\"\n },\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Filename of the merged PDF\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"description\": \"Always application/pdf\"\n },\n \"size\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Size of the merged PDF in bytes\"\n }\n },\n \"required\": [\n \"fileId\",\n \"filename\",\n \"mimeType\",\n \"size\"\n ],\n \"additionalProperties\": false,\n \"description\": \"The merged PDF. Pass {{ steps.<step>.output.file }} to Parse, Vision or any other file input.\"\n },\n \"pageCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Total pages in the merged PDF\"\n },\n \"sources\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"filename\": {\n \"type\": \"string\",\n \"description\": \"Filename of the source file\"\n },\n \"mimeType\": {\n \"type\": \"string\",\n \"description\": \"MIME type of the source file\"\n },\n \"pageCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Pages this source contributed\"\n },\n \"pageRange\": {\n \"type\": \"array\",\n \"items\": [\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n },\n {\n \"type\": \"integer\",\n \"minimum\": -9007199254740991,\n \"maximum\": 9007199254740991\n }\n ],\n \"additionalItems\": false,\n \"minItems\": 2,\n \"maxItems\": 2,\n \"description\": \"[startIndex, endIndex] inclusive, 0-based page indices in the merged PDF\"\n }\n },\n \"required\": [\n \"filename\",\n \"mimeType\",\n \"pageCount\",\n \"pageRange\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"One entry per input file, in merge order, with the merged page range it occupies. Use it to map a merged page index back to its source file.\"\n }\n },\n \"required\": [\n \"file\",\n \"pageCount\",\n \"sources\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n### Action steps — external side effects\n\n#### `action.http` — HTTP Request\n\nMake an HTTP request to an external API\n\n**Behavior and examples:** `eigenpal docs read steps/action/http`\n\n**Durable retry:** HTTP `GET` and `HEAD` can durably retry transient timeout, rate limits, selected retryable server failures failures. Other methods are not replayed.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `url` | string | yes | | Request URL (supports template expressions) |\n| `method` | `\"GET\"` \\| `\"HEAD\"` \\| `\"POST\"` \\| `\"PUT\"` \\| `\"PATCH\"` \\| `\"DELETE\"` | no | `\"GET\"` | |\n| `headers` | record<string, string> | no | | HTTP headers |\n| `body` | unknown | no | | Request body (JSON or string) |\n| `timeout` | number | no | `30000` | Timeout in milliseconds |\n| `insecureSkipTlsVerify` | boolean | no | `false` | If true, skip TLS certificate verification (use only for read-only public endpoints with bad/expired certs) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `status` | number | yes | | HTTP status code |\n| `statusText` | string | yes | | |\n| `headers` | record<string, string> | yes | | |\n| `body` | unknown | yes | | Response body (parsed JSON or string) |\n| `responseCharset` | string | yes | | Charset used to decode the response body (e.g. utf-8, windows-1250) |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Request URL (supports template expressions)\"\n },\n \"method\": {\n \"default\": \"GET\",\n \"type\": \"string\",\n \"enum\": [\n \"GET\",\n \"HEAD\",\n \"POST\",\n \"PUT\",\n \"PATCH\",\n \"DELETE\"\n ]\n },\n \"headers\": {\n \"description\": \"HTTP headers\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"body\": {\n \"description\": \"Request body (JSON or string)\"\n },\n \"timeout\": {\n \"description\": \"Timeout in milliseconds\",\n \"default\": 30000,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n },\n \"insecureSkipTlsVerify\": {\n \"description\": \"If true, skip TLS certificate verification (use only for read-only public endpoints with bad/expired certs)\",\n \"default\": false,\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"number\",\n \"description\": \"HTTP status code\"\n },\n \"statusText\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"body\": {\n \"description\": \"Response body (parsed JSON or string)\"\n },\n \"responseCharset\": {\n \"type\": \"string\",\n \"description\": \"Charset used to decode the response body (e.g. utf-8, windows-1250)\"\n }\n },\n \"required\": [\n \"status\",\n \"statusText\",\n \"headers\",\n \"body\",\n \"responseCharset\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `action.invoke-workflow` — Invoke Workflow\n\nExecute another workflow and return its output\n\n**Behavior and examples:** `eigenpal docs read steps/action/invoke-workflow`\n\n**Durable retry:** Invoked workflows are not replayed as durable leaf attempts.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `tags` | string \\| array<string> | no | | Child mode only. One tag or a list. Supports templates resolving to a string or string array. Tags are not inherited. |\n| `workflow` | string | no | | Workflow to invoke — definition name or wf_ id (tenant-scoped) |\n| `workflowId` | string | no | | Legacy alias for workflow when the value is a wf_ id |\n| `execution` | `\"inline\"` \\| `\"child\"` | no | | inline: run target steps in this execution (default). child: spawn a separate run with lineage. |\n| `input` | record<string, unknown> | no | | Input record keyed by the invoked workflow's declared inputs |\n| `wait` | boolean | no | | Child mode only. Wait for the invoked workflow to complete and return its output (default: true). Set false for fire-and-forget. |\n| `timeout` | number | no | | Child mode only. Max wait time in ms while the child is queued or running (default: 300000). The deadline is stored with the invocation and survives worker restarts; expiry makes the parent eligible to resume and report the timeout. Once the child pauses for human review, the parent pauses durably instead of using this timeout. |\n| `pollInterval` | number | no | | Child mode only. Accepted for compatibility. Durable child waits no longer poll or occupy a worker slot. |\n\n**Output:** `record<string, unknown>`\n\n> 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`.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"tags\": {\n \"description\": \"Child mode only. One tag or a list. Supports templates resolving to a string or string array. Tags are not inherited.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"maxItems\": 100,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n },\n \"workflow\": {\n \"description\": \"Workflow to invoke — definition name or wf_ id (tenant-scoped)\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"workflowId\": {\n \"description\": \"Legacy alias for workflow when the value is a wf_ id\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"execution\": {\n \"description\": \"inline: run target steps in this execution (default). child: spawn a separate run with lineage.\",\n \"type\": \"string\",\n \"enum\": [\n \"inline\",\n \"child\"\n ]\n },\n \"input\": {\n \"description\": \"Input record keyed by the invoked workflow's declared inputs\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"wait\": {\n \"description\": \"Child mode only. Wait for the invoked workflow to complete and return its output (default: true). Set false for fire-and-forget.\",\n \"type\": \"boolean\"\n },\n \"timeout\": {\n \"description\": \"Child mode only. Max wait time in ms while the child is queued or running (default: 300000). The deadline is stored with the invocation and survives worker restarts; expiry makes the parent eligible to resume and report the timeout. Once the child pauses for human review, the parent pauses durably instead of using this timeout.\",\n \"type\": \"number\"\n },\n \"pollInterval\": {\n \"description\": \"Child mode only. Accepted for compatibility. Durable child waits no longer poll or occupy a worker slot.\",\n \"type\": \"number\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"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`.\"\n}\n```\n\n\n#### `action.website-reader` — Website Reader\n\nFetch a webpage and convert content to markdown\n\n**Behavior and examples:** `eigenpal docs read steps/action/website-reader`\n\n**Durable retry:** Supported for transient timeout, rate limits, selected retryable server failures failures.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `url` | string | yes | | Website URL to fetch (supports template expressions) |\n| `timeout` | number | no | `30000` | Timeout in milliseconds |\n| `encoding` | `\"auto\"` \\| `\"utf-8\"` \\| `\"latin1\"` \\| `\"windows-1250\"` \\| `\"windows-1252\"` \\| `\"iso-8859-2\"` | no | `\"auto\"` | Response encoding. Auto detects from Content-Type header and HTML meta tags. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `markdown` | string | yes | | Page content converted to markdown |\n| `title` | string \\| null | yes | | Page title |\n| `excerpt` | string \\| null | yes | | Page excerpt/description |\n| `byline` | string \\| null | yes | | Author information |\n| `siteName` | string \\| null | yes | | Site name |\n| `length` | number | yes | | Content length in characters |\n| `url` | string | yes | | Final URL after redirects |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Website URL to fetch (supports template expressions)\"\n },\n \"timeout\": {\n \"description\": \"Timeout in milliseconds\",\n \"default\": 30000,\n \"type\": \"number\",\n \"exclusiveMinimum\": 0\n },\n \"encoding\": {\n \"description\": \"Response encoding. Auto detects from Content-Type header and HTML meta tags.\",\n \"default\": \"auto\",\n \"type\": \"string\",\n \"enum\": [\n \"auto\",\n \"utf-8\",\n \"latin1\",\n \"windows-1250\",\n \"windows-1252\",\n \"iso-8859-2\"\n ]\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"markdown\": {\n \"type\": \"string\",\n \"description\": \"Page content converted to markdown\"\n },\n \"title\": {\n \"description\": \"Page title\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"excerpt\": {\n \"description\": \"Page excerpt/description\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"byline\": {\n \"description\": \"Author information\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"siteName\": {\n \"description\": \"Site name\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"length\": {\n \"type\": \"number\",\n \"description\": \"Content length in characters\"\n },\n \"url\": {\n \"type\": \"string\",\n \"description\": \"Final URL after redirects\"\n }\n },\n \"required\": [\n \"markdown\",\n \"title\",\n \"excerpt\",\n \"byline\",\n \"siteName\",\n \"length\",\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `action.email` — Send Email\n\nSend an email with optional attachments via a selected email server. At most 10 recipients combined across to, cc, and bcc.\n\n**Behavior and examples:** `eigenpal docs read steps/action/email`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `server` | string | yes | | Outbound email server id (`ems_…`) |\n| `to` | string \\| array<string> | yes | | Primary recipient(s). String, comma-separated list, or nonempty string array. Combined with cc and bcc, at most 10 recipients. |\n| `cc` | string \\| array<string> | no | | Carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and bcc, at most 10 recipients. |\n| `bcc` | string \\| array<string> | no | | Blind carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and cc, at most 10 recipients. |\n| `replyTo` | string | no | | Reply-To address (supports template expressions) |\n| `subject` | string | yes | | Email subject |\n| `text` | string | yes | | Plain-text email body (max 50KiB) |\n| `attachments` | array<string \\| object> | no | | Optional same-run attachments as { fileId, filename? } or a bare fileId string (12MiB combined) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `serverId` | string | yes | | Email server that sent (or would have sent) the message |\n| `messageId` | string \\| null | yes | | Provider message id. Null when delivery was skipped (evaluation runs). |\n| `provider` | `\"resend\"` \\| `\"smtp\"` \\| null | yes | | Email provider that sent the message. Null when delivery was skipped. |\n| `to` | array<string> | yes | | Normalized To recipients |\n| `cc` | array<string> | yes | | Normalized Cc recipients |\n| `bcc` | array<string> | yes | | Normalized Bcc recipients |\n| `attachmentCount` | integer | yes | | Number of attachments sent |\n| `totalBytes` | integer | yes | | Total attachment size in bytes |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"server\": {\n \"type\": \"string\",\n \"maxLength\": 128,\n \"pattern\": \"^ems_[A-Za-z0-9_-]+$\",\n \"description\": \"Outbound email server id (`ems_…`)\"\n },\n \"to\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ],\n \"description\": \"Primary recipient(s). String, comma-separated list, or nonempty string array. Combined with cc and bcc, at most 10 recipients.\"\n },\n \"cc\": {\n \"description\": \"Carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and bcc, at most 10 recipients.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n },\n \"bcc\": {\n \"description\": \"Blind carbon-copy recipient(s). String, comma-separated list, or string array. Combined with to and cc, at most 10 recipients.\",\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n },\n \"replyTo\": {\n \"description\": \"Reply-To address (supports template expressions)\",\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"subject\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Email subject\"\n },\n \"text\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Plain-text email body (max 50KiB)\"\n },\n \"attachments\": {\n \"description\": \"Optional same-run attachments as { fileId, filename? } or a bare fileId string (12MiB combined)\",\n \"maxItems\": 10,\n \"type\": \"array\",\n \"items\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File id or template expression that resolves to a file id\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"fileId\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"File id or template expression that resolves to a file id\"\n },\n \"filename\": {\n \"description\": \"Optional download filename override\",\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"fileId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n }\n },\n \"required\": [\n \"server\",\n \"to\",\n \"subject\",\n \"text\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"serverId\": {\n \"type\": \"string\",\n \"maxLength\": 128,\n \"pattern\": \"^ems_[A-Za-z0-9_-]+$\",\n \"description\": \"Email server that sent (or would have sent) the message\"\n },\n \"messageId\": {\n \"description\": \"Provider message id. Null when delivery was skipped (evaluation runs).\",\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"provider\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"enum\": [\n \"resend\",\n \"smtp\"\n ]\n },\n {\n \"type\": \"null\"\n }\n ],\n \"description\": \"Email provider that sent the message. Null when delivery was skipped.\"\n },\n \"to\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Normalized To recipients\"\n },\n \"cc\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Normalized Cc recipients\"\n },\n \"bcc\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"description\": \"Normalized Bcc recipients\"\n },\n \"attachmentCount\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Number of attachments sent\"\n },\n \"totalBytes\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 9007199254740991,\n \"description\": \"Total attachment size in bytes\"\n }\n },\n \"required\": [\n \"serverId\",\n \"messageId\",\n \"provider\",\n \"to\",\n \"cc\",\n \"bcc\",\n \"attachmentCount\",\n \"totalBytes\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n### Control steps — flow control\n\n#### `control.if` — Condition\n\nBranch execution based on a condition expression\n\n**Behavior and examples:** `eigenpal docs read steps/control/if`\n\n**Durable retry:** The control container itself is not retried, but eligible leaves inside its sequential scope may retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `condition` | string | yes | | LiquidJS expression that evaluates to boolean |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `condition` | boolean | yes | | Evaluated condition result |\n| `branch` | `\"then\"` \\| `\"else\"` | yes | | Which branch was executed |\n| `result` | unknown | yes | | Output from executed branch |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"condition\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"LiquidJS expression that evaluates to boolean\"\n }\n },\n \"required\": [\n \"condition\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"condition\": {\n \"type\": \"boolean\",\n \"description\": \"Evaluated condition result\"\n },\n \"branch\": {\n \"type\": \"string\",\n \"enum\": [\n \"then\",\n \"else\"\n ],\n \"description\": \"Which branch was executed\"\n },\n \"result\": {\n \"description\": \"Output from executed branch\"\n }\n },\n \"required\": [\n \"condition\",\n \"branch\",\n \"result\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.switch` — Switch\n\nMulti-way routing: resolve an expression and run the first case whose value matches (else default). Cleaner than a nested control.if chain for routing an item to one of N pipelines by a discriminator field like a document type.\n\n**Behavior and examples:** `eigenpal docs read steps/control/switch`\n\n**Durable retry:** The control container itself is not retried, but eligible leaves inside its sequential scope may retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `on` | string | yes | | Template expression whose resolved value selects the case, e.g. \"{{ doc.type }}\". |\n| `cases` | array<object> | yes | | Ordered cases; the first whose `when` matches runs. Each case has its own `steps`. |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `matched` | string \\| number \\| boolean \\| null | yes | | The `when` value that matched, or null when the default (or no) branch ran. |\n| `branch` | `\"case\"` \\| `\"default\"` \\| `\"none\"` | yes | | Which branch executed. |\n| `result` | unknown | yes | | Output from the executed branch (its last step). |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"on\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Template expression whose resolved value selects the case, e.g. \\\"{{ doc.type }}\\\".\"\n },\n \"cases\": {\n \"minItems\": 1,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"when\": {\n \"description\": \"Value matched (string-compared) against the resolved `on` value.\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\"\n ]\n }\n },\n \"required\": [\n \"when\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Ordered cases; the first whose `when` matches runs. Each case has its own `steps`.\"\n }\n },\n \"required\": [\n \"on\",\n \"cases\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"matched\": {\n \"description\": \"The `when` value that matched, or null when the default (or no) branch ran.\",\n \"type\": [\n \"string\",\n \"number\",\n \"boolean\",\n \"null\"\n ]\n },\n \"branch\": {\n \"type\": \"string\",\n \"enum\": [\n \"case\",\n \"default\",\n \"none\"\n ],\n \"description\": \"Which branch executed.\"\n },\n \"result\": {\n \"description\": \"Output from the executed branch (its last step).\"\n }\n },\n \"required\": [\n \"matched\",\n \"branch\",\n \"result\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.foreach` — For Each\n\nLoop over an array and execute steps for each item\n\n**Behavior and examples:** `eigenpal docs read steps/control/foreach`\n\n**Durable retry:** The control container itself is not retried, but eligible leaves inside its sequential scope may retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | string | yes | | Expression resolving to array |\n| `as` | string | yes | | Variable name for current item |\n| `indexAs` | string | no | | Variable name for current index |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | array<unknown> | yes | | Results from each iteration |\n| `count` | number | yes | | Number of completed iterations |\n| `totalIterations` | number | yes | | Total iterations |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Expression resolving to array\"\n },\n \"as\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Variable name for current item\"\n },\n \"indexAs\": {\n \"description\": \"Variable name for current index\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"items\",\n \"as\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"array\",\n \"items\": {},\n \"description\": \"Results from each iteration\"\n },\n \"count\": {\n \"type\": \"number\",\n \"description\": \"Number of completed iterations\"\n },\n \"totalIterations\": {\n \"type\": \"number\",\n \"description\": \"Total iterations\"\n }\n },\n \"required\": [\n \"items\",\n \"count\",\n \"totalIterations\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.parallel_map` — Parallel Map\n\nIterate over an array with concurrent execution up to a limit\n\n**Behavior and examples:** `eigenpal docs read steps/control/parallel_map`\n\n**Durable retry:** The control container and leaves inside its concurrent branches do not retry durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | string | yes | | Expression resolving to array |\n| `as` | string | yes | | Variable name for current item |\n| `indexAs` | string | no | | Variable name for current index |\n| `concurrency` | integer | no | `5` | Maximum concurrent executions (1-50, default 5) |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `items` | array<unknown> | yes | | Results from each iteration (maintains original order) |\n| `count` | number | yes | | Number of completed iterations |\n| `totalIterations` | number | yes | | Total iterations |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Expression resolving to array\"\n },\n \"as\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Variable name for current item\"\n },\n \"indexAs\": {\n \"description\": \"Variable name for current index\",\n \"type\": \"string\"\n },\n \"concurrency\": {\n \"description\": \"Maximum concurrent executions (1-50, default 5)\",\n \"default\": 5,\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 50\n }\n },\n \"required\": [\n \"items\",\n \"as\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"array\",\n \"items\": {},\n \"description\": \"Results from each iteration (maintains original order)\"\n },\n \"count\": {\n \"type\": \"number\",\n \"description\": \"Number of completed iterations\"\n },\n \"totalIterations\": {\n \"type\": \"number\",\n \"description\": \"Total iterations\"\n }\n },\n \"required\": [\n \"items\",\n \"count\",\n \"totalIterations\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.parallel` — Parallel\n\nExecute multiple branches concurrently\n\n**Behavior and examples:** `eigenpal docs read steps/control/parallel`\n\n**Durable retry:** The control container and leaves inside its concurrent branches do not retry durably.\n\n**Config** (at step level):\n\n_No fields._\n\n**Output:** `record<string, unknown>`\n\n> Results keyed by branch name\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {},\n \"description\": \"Results keyed by branch name\"\n}\n```\n\n\n#### `control.wait` — Wait\n\nPause workflow execution for a specified duration\n\n**Behavior and examples:** `eigenpal docs read steps/control/wait`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `duration` | number | yes | | Duration in milliseconds |\n\n**Output:** `object`\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `waited` | number | yes | | Actual milliseconds waited |\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"duration\": {\n \"type\": \"number\",\n \"exclusiveMinimum\": 0,\n \"description\": \"Duration in milliseconds\"\n }\n },\n \"required\": [\n \"duration\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"waited\": {\n \"type\": \"number\",\n \"description\": \"Actual milliseconds waited\"\n }\n },\n \"required\": [\n \"waited\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\n#### `control.human_review` — Human Review\n\nPause the run for selective field confirmation or correction, then continue with the reviewed data.\n\n**Behavior and examples:** `eigenpal docs read steps/control/human_review`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (in `step.with`):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `data` | string \\| record<string, unknown> \\| array<unknown> | yes | | Structured data or a template expression resolving to an object or array |\n| `schema` | record<string, unknown> | no | | Optional JSON Schema for validating edits and exposing downstream autocomplete. When omitted with metadataFrom: ai.extract and a direct whole-output data expression, the extract step schema is reused. |\n| `metadataFrom` | `\"ai.extract\"` | no | | Producer adapter. `ai.extract` derives categorical field confidence from `_grounding`, copies valid numeric grounding scores into fieldMetadata.display.score, and strips that reserved key from review data. Grounding is not stripped unless this is set. |\n| `lineageFrom` | string | no | | Name of the ai.extract step whose source lineage draws field boxes in the review. Needed only when data passes through a step that changes field paths. Without it, boxes come from the step in a direct `{{ steps.<name>.output }}` data reference, or, when that step is a transform.script, from the one whole step output it received whose field paths it kept. |\n| `fieldMetadata` | record<string, object> | no | `{}` | RFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias. |\n| `selection` | object | yes | | Field selection policy resolved once when the task is created |\n| `files` | object | no | `{\"includeRunInputs\":true,\"attachments\":[]}` | Run input files and optional current-run attachments for reviewers |\n| `instructions` | string | no | | Free-form guidance shown above the review workspace |\n\n**Output:** `unknown`\n\n> The complete reviewed data in the same object or array shape as the input.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n {\n \"type\": \"array\",\n \"items\": {}\n }\n ],\n \"description\": \"Structured data or a template expression resolving to an object or array\"\n },\n \"schema\": {\n \"description\": \"Optional JSON Schema for validating edits and exposing downstream autocomplete. When omitted with metadataFrom: ai.extract and a direct whole-output data expression, the extract step schema is reused.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n },\n \"metadataFrom\": {\n \"type\": \"string\",\n \"enum\": [\n \"ai.extract\"\n ],\n \"description\": \"Producer adapter. `ai.extract` derives categorical field confidence from `_grounding`, copies valid numeric grounding scores into fieldMetadata.display.score, and strips that reserved key from review data. Grounding is not stripped unless this is set.\"\n },\n \"lineageFrom\": {\n \"description\": \"Name of the ai.extract step whose source lineage draws field boxes in the review. Needed only when data passes through a step that changes field paths. Without it, boxes come from the step in a direct `{{ steps.<name>.output }}` data reference, or, when that step is a transform.script, from the one whole step output it received whose field paths it kept.\",\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9_-]+$\"\n },\n \"fieldMetadata\": {\n \"description\": \"RFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias.\",\n \"default\": {},\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"confidence\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n },\n \"label\": {\n \"type\": \"string\",\n \"maxLength\": 500\n },\n \"description\": {\n \"type\": \"string\",\n \"maxLength\": 5000\n },\n \"review\": {\n \"default\": \"auto\",\n \"type\": \"string\",\n \"enum\": [\n \"auto\",\n \"always\",\n \"never\"\n ]\n },\n \"display\": {\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\"\n },\n \"additionalProperties\": {}\n }\n },\n \"additionalProperties\": false\n }\n },\n \"selection\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"description\": \"RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"exclude\": {\n \"description\": \"RFC 6901 pointers removed after include expansion\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"fields\": {\n \"description\": \"Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"maxLength\": 512\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"review\": {\n \"type\": \"string\",\n \"enum\": [\n \"always\",\n \"never\",\n \"skip\"\n ]\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n }\n },\n \"additionalProperties\": false\n }\n },\n \"mode\": {\n \"type\": \"string\",\n \"const\": \"confidence\",\n \"description\": \"Review fields below threshold or missing confidence\"\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ],\n \"description\": \"Fields with confidence strictly below this value require review. Equality auto-approves. Numeric 0–1 or categorical low|medium|high. Template strings are resolved at runtime.\"\n },\n \"missingConfidence\": {\n \"description\": \"Whether unscored or type-mismatched fields require review (default review)\",\n \"default\": \"review\",\n \"type\": \"string\",\n \"enum\": [\n \"review\",\n \"skip\"\n ]\n }\n },\n \"required\": [\n \"mode\",\n \"threshold\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"description\": \"RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"exclude\": {\n \"description\": \"RFC 6901 pointers removed after include expansion\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"fields\": {\n \"description\": \"Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"maxLength\": 512\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"review\": {\n \"type\": \"string\",\n \"enum\": [\n \"always\",\n \"never\",\n \"skip\"\n ]\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n }\n },\n \"additionalProperties\": false\n }\n },\n \"mode\": {\n \"type\": \"string\",\n \"const\": \"explicit\",\n \"description\": \"Review only paths matched by include/exclude\"\n }\n },\n \"required\": [\n \"mode\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"description\": \"RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"exclude\": {\n \"description\": \"RFC 6901 pointers removed after include expansion\",\n \"default\": [],\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"maxLength\": 512\n }\n },\n \"fields\": {\n \"description\": \"Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.\",\n \"type\": \"object\",\n \"propertyNames\": {\n \"type\": \"string\",\n \"maxLength\": 512\n },\n \"additionalProperties\": {\n \"type\": \"object\",\n \"properties\": {\n \"review\": {\n \"type\": \"string\",\n \"enum\": [\n \"always\",\n \"never\",\n \"skip\"\n ]\n },\n \"threshold\": {\n \"anyOf\": [\n {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1\n },\n {\n \"type\": \"string\",\n \"enum\": [\n \"low\",\n \"medium\",\n \"high\"\n ]\n },\n {\n \"type\": \"string\",\n \"minLength\": 1\n }\n ]\n }\n },\n \"additionalProperties\": false\n }\n },\n \"mode\": {\n \"type\": \"string\",\n \"const\": \"all\",\n \"description\": \"Review every scalar leaf unless excluded or review: never\"\n }\n },\n \"required\": [\n \"mode\"\n ],\n \"additionalProperties\": false\n }\n ],\n \"description\": \"Field selection policy resolved once when the task is created\"\n },\n \"files\": {\n \"description\": \"Run input files and optional current-run attachments for reviewers\",\n \"default\": {\n \"includeRunInputs\": true,\n \"attachments\": []\n },\n \"type\": \"object\",\n \"properties\": {\n \"includeRunInputs\": {\n \"description\": \"Attach every authorized run input file to the review task\",\n \"default\": true,\n \"type\": \"boolean\"\n },\n \"attachments\": {\n \"description\": \"Additional current-run file or artifact template expressions\",\n \"default\": [],\n \"maxItems\": 100,\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n },\n \"additionalProperties\": false\n },\n \"instructions\": {\n \"description\": \"Free-form guidance shown above the review workspace\",\n \"type\": \"string\",\n \"maxLength\": 10000\n }\n },\n \"required\": [\n \"data\",\n \"selection\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"description\": \"The complete reviewed data in the same object or array shape as the input.\"\n}\n```\n\n\n#### `control.fail` — Fail\n\nTerminate the workflow with a typed status code + message. With an optional condition, only fails when the condition is truthy; otherwise always fails when reached. Pair with ai.classify or any prior step to fail fast on bad inputs.\n\n**Behavior and examples:** `eigenpal docs read steps/control/fail`\n\n**Durable retry:** This control step is not retried durably.\n\n**Config** (at step level):\n\n| Field | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `condition` | string | no | | Optional LiquidJS expression. When set, the step only fails if this evaluates truthy; when omitted, it always fails when reached (compose with control.if for legacy gating). |\n| `statusCode` | integer | no | `422` | Business rejection code exposed as error.statusCode on the run. Does not change the API HTTP response status. Default 422 (Unprocessable Entity). |\n| `message` | string | yes | | Human-readable failure message. Supports template expressions, e.g. \"Document classified as {{ steps.classify.output.label }}\". |\n\n**Output:** `unknown`\n\n> control.fail never produces output — it terminates the workflow when triggered.\n\n##### Complete machine-readable schemas\n\nConfig schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": {\n \"condition\": {\n \"description\": \"Optional LiquidJS expression. When set, the step only fails if this evaluates truthy; when omitted, it always fails when reached (compose with control.if for legacy gating).\",\n \"type\": \"string\"\n },\n \"statusCode\": {\n \"default\": 422,\n \"description\": \"Business rejection code exposed as error.statusCode on the run. Does not change the API HTTP response status. Default 422 (Unprocessable Entity).\",\n \"type\": \"integer\",\n \"minimum\": 400,\n \"maximum\": 599\n },\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"description\": \"Human-readable failure message. Supports template expressions, e.g. \\\"Document classified as {{ steps.classify.output.label }}\\\".\"\n }\n },\n \"required\": [\n \"statusCode\",\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n\nOutput schema:\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"not\": {},\n \"description\": \"control.fail never produces output — it terminates the workflow when triggered.\"\n}\n```\n<!-- GENERATED:STEP_CATALOG END -->\n"
458
458
  },
459
459
  {
460
460
  "topic": "reference/workflow-yaml",
@@ -1933,6 +1933,27 @@
1933
1933
  "source": "public",
1934
1934
  "content": "---\ntitle: '0.23.3'\nversion: '0.23.3'\ndate: '2026-11-10'\ncommit: 'c3aecdcf43dfc795e03cec874a05251b75c1cb08'\ndescription: 'EigenPal platform release 0.23.3'\n---\n\n## Platform (Studio)\n\n- Add Claude Fable 5.2 for workflow steps, structured extraction, vision, judges and agents, with every reasoning effort level from low to max. It costs less per token than Fable 5.1 and replaces it as the recommended Fable model. Existing default model selections and workflows that name Fable 5.1 stay unchanged.\n\n## CLI\n\n- The bundled self-hosting docs in `eigenpal docs` now describe the install preflight check and how to run it on its own.\n\n## Infrastructure & processing\n\n- Self-hosted installs now run a read-only preflight check before migrations. It confirms that every Secret value is present, that CA bundles and client certificates are valid (with an optional expected certificate name), and that the database, object storage, model gateway, OCR, sign-in and file source services are reachable over TLS. It prints one result per check with a fix for each failure, never prints a secret value, and stops an install or Argo CD sync before anything changes. It can also be run on its own the day before an install.\n"
1935
1935
  },
1936
+ {
1937
+ "topic": "releases/0.23.4",
1938
+ "title": "0.23.4",
1939
+ "description": "EigenPal platform release 0.23.4",
1940
+ "source": "public",
1941
+ "content": "---\ntitle: '0.23.4'\nversion: '0.23.4'\ndate: '2026-11-10'\ncommit: 'b77265aa638052b959467961d554871b39c07873'\ndescription: 'EigenPal platform release 0.23.4'\n---\n\n## Platform (Studio)\n\n- The Document layout view on a run now works for Word and PowerPoint files (and other paginated office formats such as RTF, ODT and ODP). It shows each page as it was laid out during parsing, with a box around every word that lines up with the page. Parse steps on these files now also report word coordinates, so `ai.parse-v2` steps that require them succeed for office inputs. Runs processed before this update show a note instead of a preview.\n- PowerPoint decks (.pptx) now open in the built-in file preview, in dataset review and in human review, with slide thumbnails for navigation, instead of showing \"Preview not available\". Charts on slides render too (bar, column, line, area, pie, doughnut, scatter and radar), along with shape effects such as glow, reflection and 3-D. Word document previews also pick up the latest rendering improvements.\n- Review tasks no longer tell owners and admins that their role is read-only while the page is still loading; the page waits until your role is known. The workflow Editor and Evals switch now always highlights the view you are looking at.\n\n## Public API\n\n- `GET /api/v1/automations/\\{id}/experiments/\\{experimentId}` reports the experiment as `running` until every finished run has its evaluator verdict, and its passed, failed, errored, pending and ungraded counts always add up to the run count. A run still without a verdict 15 minutes after it ends counts as ungraded and is left out of the pass rate, so a stuck run cannot hold an experiment open.\n\n## CLI\n\n- The CLI now retries rate-limited requests a few times, waiting as long as the server asks, and reports a request that is still rate limited as a rate limit with how long to wait, instead of as a validation failure.\n- `eigenpal workflow step-type get &lt;type&gt;` now accepts `--json`, like the other commands. Its output was already JSON.\n- `eigenpal workflow push --json` now prints the same shape on create and update, `\\{ id, name, version, versionId, created }`, so `jq -r .id` always gives the workflow id. `eigenpal workflow list` shows each workflow's name and version again, and its `--json` rows include `name`, `description` and `version`. New `eigenpal workflow get &lt;id-or-slug&gt;` shows one workflow's name, version, folder and your access, with `--json` for the full record. `workflow push --bump` now reads the current version correctly.\n- `eigenpal workflow experiment run --wait` now returns only after every run has finished and been graded, so its pass rate matches `workflow experiment results`. Previously it could return while the last runs were still being scored and report a pass rate that was too low.\n- The bundled step reference in `eigenpal docs` now covers OCR word confidence in extraction grounding and the `lineageFrom` option on human review.\n\n## Infrastructure & processing\n\n- Exact-diff evaluators now score an expected `null` or empty string as a real expectation instead of skipping it. A field the dataset says should stay empty fails when the workflow fills it in, so eval scores no longer overstate accuracy. An expected `null` still passes when the output leaves the field out. To skip a field on purpose, use an `ignore: true` rule or the `__any__` wildcard.\n- Human review now shows source boxes when its data passes through a script step after extraction. If the script keeps the extracted field names, boxes appear automatically; if it renames or moves fields, set `lineageFrom` on the review step to the extraction step.\n- Extraction from scanned documents now flags fields that OCR read poorly. When the OCR model reports per-word confidence, each extracted field takes the confidence of the words it was read from: a misread handwritten name is marked low confidence and sent to human review instead of passing as a verbatim match. Fields read from clean print or native PDF text are unchanged. The new `recognitionScore` in `_grounding` shows the OCR confidence behind each field.\n"
1942
+ },
1943
+ {
1944
+ "topic": "releases/0.23.5",
1945
+ "title": "0.23.5",
1946
+ "description": "EigenPal platform release 0.23.5",
1947
+ "source": "public",
1948
+ "content": "---\ntitle: '0.23.5'\nversion: '0.23.5'\ndate: '2026-11-10'\ncommit: 'e2e6452f6914f16c5ae86a0ddd5ce867a99ace02'\ndescription: 'EigenPal platform release 0.23.5'\n---\n\n- Internal improvements.\n"
1949
+ },
1950
+ {
1951
+ "topic": "releases/0.23.6",
1952
+ "title": "0.23.6",
1953
+ "description": "EigenPal platform release 0.23.6",
1954
+ "source": "public",
1955
+ "content": "---\ntitle: '0.23.6'\nversion: '0.23.6'\ndate: '2026-11-10'\ncommit: 'f74dbeae6b9d065def8f41b40776b52b9bbbaa00'\ndescription: 'EigenPal platform release 0.23.6'\n---\n\n## CLI\n\n- Bundled self-hosting documentation explains every Helm value and environment variable.\n"
1956
+ },
1936
1957
  {
1937
1958
  "topic": "releases/0.5.10",
1938
1959
  "title": "0.5.10",
@@ -2225,7 +2246,7 @@
2225
2246
  "title": "Agent sandboxes",
2226
2247
  "description": "Enable filesystem tools for agents or disable the sandbox capability.",
2227
2248
  "source": "public",
2228
- "content": "---\ntitle: Agent sandboxes\ndescription: Enable filesystem tools for agents or disable the sandbox capability.\n---\n\nEigenPal agents need a sandbox when they use filesystem tools or skills. Agents without a filesystem can run without one. Workflow `transform.script` steps use QuickJS independently.\n\n## Enable agents\n\nAgents keep their source in a Git server, which the Helm chart does not install. The chart therefore disables agents (`agents.enabled: false`): the Agents area is hidden, agent API calls return not found and agent runs are refused. Workflows are unaffected.\n\nTo enable agents, operate a Git server, then set `agents.enabled: true` and supply `AGENT_GIT_BASE_URL` and `AGENT_GIT_ADMIN_TOKEN` to app and worker through `extraEnv`. Outside the chart, `EIGENPAL_AGENTS_ENABLED` defaults to true.\n\n## Disable agent filesystem sandboxes\n\nSet this on both app and worker, then restart them:\n\n```yaml\napp:\n extraEnv:\n - name: EIGENPAL_SANDBOX_ENABLED\n value: 'false'\nworker:\n extraEnv:\n - name: EIGENPAL_SANDBOX_ENABLED\n value: 'false'\n```\n\nFilesystem-dependent agents fail with a capability error. Existing sandbox cleanup remains available. To disable workflow scripts too, set `SCRIPT_ENABLED=false` on the worker.\n\n## Enable a backend\n\nThe core Helm chart does not install a sandbox runtime or agent Git server. Configure the Git server through `AGENT_GIT_BASE_URL`, persistent repository storage and matching operator credentials. Use the [runtime reference](/self-hosting/environment-variables#agent-sandboxes) for process settings.\n\n<AccordionGroup>\n<Accordion title=\"E2B\">\n\nSet `SANDBOX_PROVIDER=e2b`, `E2B_API_KEY` and a release-compatible `E2B_SANDBOX_TEMPLATE` on app and worker. Pin a template supplied for your release; the unset-template fallback is intended for development.\n\n</Accordion>\n<Accordion title=\"Docker\">\n\nSet `SANDBOX_PROVIDER=docker` and `DOCKER_SANDBOX_IMAGE`. Use `DOCKER_SANDBOX_PLATFORM` if needed. Supply a Docker daemon accessible to the processes that manage sandboxes. The default image is local-only; use a release-compatible image.\n\nA Docker socket gives substantial control over its host. Isolate this runtime from general application workloads.\n\n</Accordion>\n<Accordion title=\"Remote runtime\">\n\nSet `SANDBOX_PROVIDER=remote`, `SANDBOX_REMOTE_URL` and `SANDBOX_REMOTE_AUTH_TOKEN` on app and worker. Provision the remote sidecar separately and set its `SIDECAR_AUTH_TOKEN` to the same secret of at least 32 characters. The sidecar must support authenticated session leases. Use remote runtimes only with single-tenant installations. Keep the service private and protect the connection with TLS. A shared sidecar does not provide a fresh OS boundary for each session; use per-run containers or VMs for stronger isolation.\n\n</Accordion>\n</AccordionGroup>\n\n## Builder requirements\n\nThe interactive builder and training sessions still use E2B, including when inference uses Docker or remote. Configure a callback address reachable from the sandbox through `EIGENPAL_API_BASE_URL` and the required relays.\n\n<Warning>\n Builder storage mounts require a working AWS STS or R2 scoped credential issuer. Mounts fail when\n scoped credentials cannot be issued.\n</Warning>\n\n<Accordion title=\"Scoped storage credentials\">\n\nUse `sandboxStorage.stsRoleArn` with permission to assume the role, or configure `sandboxStorage.r2AccountId` and `r2ApiTokenSecret`. Credential lifetimes default to 3600 seconds and accept 900 to 43200 when supported by the issuer. AWS role chaining limits sessions to 3600 seconds. Mounts refuse to start when the scoped credential issuer is unavailable.\n\nThis storage-mount path belongs to the builder. Inference sandboxes use a separate file-transfer path.\n\n</Accordion>\n"
2249
+ "content": "---\ntitle: Agent sandboxes\ndescription: Enable filesystem tools for agents or disable the sandbox capability.\n---\n\nEigenPal agents need a sandbox when they use filesystem tools or skills. Agents without a filesystem can run without one. Workflow `transform.script` steps use QuickJS independently.\n\n## Enable agents\n\nAgents keep their source in a Git server, which the Helm chart does not install. The chart therefore disables agents (`agents.enabled: false`): the Agents area is hidden, agent API calls return not found and agent runs are refused. Workflows are unaffected.\n\nTo enable agents, operate a Git server, then set `agents.enabled: true` and supply `AGENT_GIT_BASE_URL` and `AGENT_GIT_ADMIN_TOKEN` to app and worker through `extraEnv`. Outside the chart, `EIGENPAL_AGENTS_ENABLED` defaults to true.\n\n## Disable agent filesystem sandboxes\n\nSet this on both app and worker, then restart them:\n\n```yaml\napp:\n extraEnv:\n - name: EIGENPAL_SANDBOX_ENABLED\n value: 'false'\nworker:\n extraEnv:\n - name: EIGENPAL_SANDBOX_ENABLED\n value: 'false'\n```\n\nFilesystem-dependent agents fail with a capability error. Existing sandbox cleanup remains available. To disable workflow scripts too, set `SCRIPT_ENABLED=false` on the worker.\n\n## Enable a backend\n\nThe core Helm chart does not install a sandbox runtime or agent Git server. Configure the Git server through `AGENT_GIT_BASE_URL`, persistent repository storage and matching operator credentials. Use the [runtime reference](/self-hosting/environment-variables#agent-sandboxes) for process settings.\n\n<AccordionGroup>\n<Accordion title=\"E2B\">\n\nSet `SANDBOX_PROVIDER=e2b`, `E2B_API_KEY` and a release-compatible `E2B_SANDBOX_TEMPLATE` on app and worker. Pin a template supplied for your release; the unset-template fallback is intended for development.\n\n</Accordion>\n<Accordion title=\"Docker\">\n\nSet `SANDBOX_PROVIDER=docker` and `DOCKER_SANDBOX_IMAGE`. Use `DOCKER_SANDBOX_PLATFORM` if needed. Supply a Docker daemon accessible to the processes that manage sandboxes. The default image is local-only; use a release-compatible image.\n\nA Docker socket gives substantial control over its host. Isolate this runtime from general application workloads.\n\n</Accordion>\n<Accordion title=\"Remote runtime\">\n\nSet `SANDBOX_PROVIDER=remote`, `SANDBOX_REMOTE_URL` and `SANDBOX_REMOTE_AUTH_TOKEN` on app and worker. Provision the remote sidecar separately and set its `SIDECAR_AUTH_TOKEN` to the same secret of at least 32 characters. The sidecar must support authenticated session leases. Use remote runtimes only with single-tenant installations. Keep the service private and protect the connection with TLS. A shared sidecar does not provide a fresh OS boundary for each session; use per-run containers or VMs for stronger isolation.\n\n</Accordion>\n</AccordionGroup>\n\n## Builder requirements\n\nThe interactive builder and training sessions still use E2B, including when inference uses Docker or remote. Set `SERVER_BASE_URL` on the app to a public address the sandbox can reach; builder sessions call back to it and refuse to start without it.\n\n<Warning>\n Builder storage mounts require a working AWS STS or R2 scoped credential issuer. Mounts fail when\n scoped credentials cannot be issued.\n</Warning>\n\n<Accordion title=\"Scoped storage credentials\">\n\nUse `sandboxStorage.stsRoleArn` with permission to assume the role, or configure `sandboxStorage.r2AccountId` and `r2ApiTokenSecret`. Credential lifetimes default to 3600 seconds and accept 900 to 43200 when supported by the issuer. AWS role chaining limits sessions to 3600 seconds. Mounts refuse to start when the scoped credential issuer is unavailable.\n\nThis storage-mount path belongs to the builder. Inference sandboxes use a separate file-transfer path.\n\n</Accordion>\n"
2229
2250
  },
2230
2251
  {
2231
2252
  "topic": "self-hosting/authentication",
@@ -2246,14 +2267,14 @@
2246
2267
  "title": "Environment variables",
2247
2268
  "description": "Deployment settings by capability and process.",
2248
2269
  "source": "public",
2249
- "content": "---\ntitle: \"Environment variables\"\ndescription: \"Deployment settings by capability and process.\"\n---\n\n{/* Generated by bun docs:generate from checked-in configuration. Do not edit. */}\n\nSupply settings through the chart or your process environment. Restart affected processes after changes. Defaults below come from runtime declarations; feature-specific fallbacks are explained in the guides. Addresses, credentials and installation identifiers are supplied by you. Internal hosting, billing, build and authentication-bypass settings are outside this reference.\n\nStart with [Configuration](/self-hosting/configuration) or expand a group below.\n\n## Database and storage\n\nDatabase timeouts use seconds. S3 timeouts use milliseconds. Supply connection addresses and credentials for your installation. S3_* credentials and region override the corresponding AWS_* fallbacks.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `DATABASE_URL` | string | installation-specific | App, Worker, Git server |\n| `DATABASE_READ_REPLICA_URLS` | string | unset | App, Worker |\n| `DATABASE_POOL_SIZE` | integer | 10 | App, Worker |\n| `DATABASE_IDLE_TIMEOUT` | integer &#124; null | 20 | App, Worker |\n| `DATABASE_MAX_LIFETIME` | integer &#124; null | 1800 | App, Worker |\n| `DATABASE_CONNECT_TIMEOUT` | integer | 10 | App, Worker |\n| `DATABASE_QUERY_TIMEOUT` | integer | 30 | App, Worker |\n| `STORAGE_TYPE` | local &#124; s3 | \"local\" | App, Worker, Authentication |\n| `STORAGE_PATH` | string | installation-specific | App, Worker |\n| `S3_BUCKET` | string | unset | App, Worker |\n| `S3_REGION` | string | \"us-east-1\" | App, Worker |\n| `S3_ENDPOINT` | string | unset | App, Worker |\n| `S3_ACCESS_KEY` | string | unset | App, Worker |\n| `S3_SECRET_KEY` | string | unset | App, Worker |\n| `S3_CONNECTION_TIMEOUT_MS` | integer | unset | App, Worker |\n| `S3_SOCKET_TIMEOUT_MS` | integer | unset | App, Worker |\n| `S3_REQUEST_TIMEOUT_MS` | integer | unset | App, Worker |\n| `S3_MULTIPART_COMPLETE_TIMEOUT_MS` | integer | unset | App, Worker |\n| `S3_MAX_ATTEMPTS` | integer | unset | App, Worker |\n| `EIGENPAL_SECRETS_WRAPPING_KEY` | string | unset; feature-dependent | App, Authentication |\n| `EIGENPAL_SECRETS_WRAPPING_KEY_FILE` | string | unset; feature-dependent | App, Authentication |\n\n</Accordion>\n\n## Authentication\n\nUse single-tenant mode. Keep installation identity, session secret and SSO provider ID stable. OIDC admits unmatched users as members unless SSO_DEFAULT_ROLE is deny. See the authentication guide before enabling SSO-only login.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `EIGENPAL_TENANT_MODE` | single-tenant &#124; multi-tenant | \"multi-tenant\" | App, Worker, Git server, Authentication, Tracing |\n| `EIGENPAL_TENANT_ID` | string | unset; feature-dependent | App, Authentication |\n| `EIGENPAL_TENANT_NAME` | string | unset; feature-dependent | Authentication |\n| `EIGENPAL_ADMIN_EMAIL` | string | unset; feature-dependent | App, Authentication |\n| `EIGENPAL_ADMIN_PASSWORD` | string | unset; feature-dependent | App, Authentication |\n| `EIGENPAL_ADMIN_NAME` | string | unset; feature-dependent | App, Authentication |\n| `EIGENPAL_AUTH_METHODS` | string | \"password\" | App, Authentication |\n| `EIGENPAL_ALLOW_OPEN_SIGNUP` | true &#124; false | \"false\" | App |\n| `EIGENPAL_SIGN_OUT_URL` | string | unset; feature-dependent | App |\n| `BETTER_AUTH_SECRET` | string | unset; feature-dependent | App |\n| `BETTER_AUTH_URL` | string | unset; feature-dependent | App |\n| `SSO_ENABLED` | true &#124; false | \"false\" | App |\n| `SSO_PROTOCOL` | string | unset; feature-dependent | App |\n| `SSO_PROVIDER_ID` | string | unset; feature-dependent | App |\n| `SSO_PROVIDER_LABEL` | string | unset; feature-dependent | App |\n| `SSO_CLIENT_ID` | string | unset; feature-dependent | App |\n| `SSO_CLIENT_SECRET` | string | unset; feature-dependent | App |\n| `SSO_DISCOVERY_URL` | string | unset; feature-dependent | App |\n| `SSO_SCOPES` | string | \"openid,profile,email\" | App |\n| `SSO_ALLOWED_EMAIL_DOMAINS` | string | unset; feature-dependent | App |\n| `SSO_DEFAULT_ROLE` | string | unset; feature-dependent | App |\n| `SSO_LOGIN_URL` | string | unset; feature-dependent | App |\n| `SSO_SERVICE_URL` | string | unset; feature-dependent | App |\n| `SSO_APP_ID` | string | unset; feature-dependent | App |\n| `SSO_APP_SECRET` | string | unset; feature-dependent | App |\n| `SSO_USERINFO_PATH` | string | unset; feature-dependent | App |\n| `SSO_CLIENT_CERT_FILE` | string | unset; feature-dependent | App |\n| `SSO_CLIENT_KEY_FILE` | string | unset; feature-dependent | App |\n| `SSO_CA_BUNDLE_FILE` | string | unset; feature-dependent | App |\n| `SSO_ROLE_MAP` | string | unset; feature-dependent | App |\n| `SSO_GROUPS_CLAIM` | string | unset; feature-dependent | App |\n| `SSO_GROUP_FILTER` | string | unset; feature-dependent | App |\n| `SSO_DIRECTORY_RESYNC_SECONDS` | string | unset; feature-dependent | App |\n| `SSO_DIRECTORY_MAX_STALENESS_SECONDS` | string | unset; feature-dependent | App |\n| `SSO_SESSION_MAX_AGE_SECONDS` | string | unset; feature-dependent | App |\n| `SSO_USER_LOOKUP_PATH` | string | unset; feature-dependent | App |\n\n</Accordion>\n\n## Networking and transfers\n\nAllowed origins are comma-separated. Byte limits apply independently: multipart routing, archives and the reusable-file quota. Set the public HTTPS origin through SERVER_BASE_URL and BETTER_AUTH_URL where required by your proxy topology.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `SERVER_BASE_URL` | string | unset | App, Worker |\n| `SERVER_PORT` | integer | 3000 | App, Worker |\n| `EIGENPAL_CONFIG_PATH` | string | unset; feature-dependent | App, Worker |\n| `EIGENPAL_TRUSTED_ORIGINS` | string | unset; feature-dependent | App |\n| `EIGENPAL_BROWSER_STORAGE_ORIGINS` | string | unset; feature-dependent | App |\n| `EIGENPAL_DIRECT_FILE_UPLOADS` | true &#124; false | \"false\" | App |\n| `EIGENPAL_MULTIPART_MAX_BYTES` | number | unset; feature-dependent | App |\n| `EIGENPAL_ARCHIVE_MAX_BYTES` | number | unset; feature-dependent | App |\n| `EIGENPAL_REUSABLE_FILES_MAX_BYTES` | number | 0 | App |\n\n</Accordion>\n\n## Worker execution\n\nWorker pool polling, leases and webhook timings use milliseconds. SCRIPT_* and TEMPLATE_RENDER_LIMIT_MS timeouts use milliseconds; script memory uses bytes. Health heartbeat timings use milliseconds. Synchronous script limits are clamped against the liveness budget.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `WORKER_POOL_CONCURRENCY` | integer | 4 | App, Worker |\n| `WORKER_POOL_POLL_INTERVAL` | integer | 1000 | App, Worker |\n| `WORKER_POOL_MAX_POLL_INTERVAL` | integer | 30000 | App, Worker |\n| `WORKER_POOL_BACKOFF_MULTIPLIER` | number | 2 | App, Worker |\n| `WORKER_POOL_LEASE_DURATION` | integer | 60000 | App, Worker |\n| `WORKER_POOL_LEASE_RENEWAL_INTERVAL` | integer | 10000 | App, Worker |\n| `WORKER_POOL_ENABLE_NOTIFY` | boolean | true | App, Worker |\n| `WORKER_POOL_DIRECT_DATABASE_URL` | string | unset | App, Worker |\n| `WORKER_MAX_TENANT_CONCURRENCY` | integer | 3 | App, Worker |\n| `WORKER_MAX_TENANT_AGENT_CONCURRENCY` | integer | 2 | App, Worker |\n| `WORKER_MAX_TENANT_WORKFLOW_CONCURRENCY` | integer | 2 | App, Worker |\n| `WORKER_MAX_BATCH_CONCURRENCY` | integer | 2 | App, Worker |\n| `HEALTH_ENABLED` | true &#124; false | \"true\" | Worker |\n| `HEALTH_PORT` | number | 8080 | Worker |\n| `HEALTH_HOST` | string | \"0.0.0.0\" | Worker |\n| `HEALTH_LIVENESS_STALE_MS` | number | 30000 | Worker |\n| `HEALTH_HEARTBEAT_INTERVAL_MS` | number | 1000 | Worker |\n| `SCRIPT_ENABLED` | true &#124; false | \"true\" | Worker |\n| `SCRIPT_TIMEOUT_MS` | number | 5000 | Worker |\n| `SCRIPT_MAX_TIMEOUT_MS` | number | 30000 | Worker |\n| `SCRIPT_MEMORY_LIMIT_BYTES` | number | 10485760 | Worker |\n| `SCRIPT_MAX_MEMORY_BYTES` | number | 52428800 | Worker |\n| `TEMPLATE_RENDER_LIMIT_MS` | number | 5000 | Worker |\n| `SOFFICE_POOL_SIZE` | number | 4 | Worker |\n| `SOFFICE_CONVERSION_TIMEOUT_MS` | number | 60000 | Worker |\n| `SOFFICE_ACQUIRE_TIMEOUT_MS` | number | 600000 | Worker |\n| `PDFTOTEXT_TIMEOUT_MS` | number | 60000 | Worker |\n| `PDFTOTEXT_MAX_OUTPUT_BYTES` | number | 33554432 | Worker |\n| `ZIP_PROCESS_INFLATION_BUDGET_BYTES` | number | 536870912 | Worker |\n| `RENDER_SUBPROCESS_CONCURRENCY` | number | 1 | Worker |\n| `RENDER_SUBPROCESS_TIMEOUT_MS` | number | 180000 | Worker |\n| `RENDER_SUBPROCESS_ACQUIRE_TIMEOUT_MS` | number | 600000 | Worker |\n| `RENDER_SUBPROCESS_MAX_RESULT_BYTES` | number | 419430400 | Worker |\n| `EXTRACT_GROUNDING_MAX_LX_CHARS` | number | unset; feature-dependent | Worker |\n| `SPLIT_WINDOW_TOKEN_BUDGET` | number | 20000 | Worker |\n| `OCR_ANALYSIS_CONCURRENCY` | number | 8 | Worker |\n| `OCR_ANALYSIS_IDLE_TIMEOUT_MS` | number | 180000 | Worker |\n| `OCR_ANALYSIS_REQUEST_TIMEOUT_MS` | number | 30000 | Worker |\n| `OCR_ANALYSIS_POLL_INTERVAL_MS` | number | 2000 | Worker |\n\n</Accordion>\n\n## Outbound webhooks\n\nDelivery timeouts, polling, leases and retry schedules use milliseconds; retention uses days. Configure endpoint URLs and signing secrets in Studio. Private destinations require single-tenant mode and remain subject to blocked-address checks.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `WORKER_WEBHOOKS_CONCURRENCY` | integer | 4 | App, Worker |\n| `WORKER_WEBHOOKS_MAX_TENANT_CONCURRENCY` | integer | 2 | App, Worker |\n| `WORKER_WEBHOOKS_POLL_INTERVAL` | integer | 1000 | App, Worker |\n| `WORKER_WEBHOOKS_MAX_POLL_INTERVAL` | integer | 30000 | App, Worker |\n| `WORKER_WEBHOOKS_LEASE_DURATION` | integer | 60000 | App, Worker |\n| `WORKER_WEBHOOKS_LEASE_RENEWAL_INTERVAL` | integer | 10000 | App, Worker |\n| `WORKER_WEBHOOKS_REQUEST_TIMEOUT` | integer | unset | App, Worker |\n| `WORKER_WEBHOOKS_RETRY_SCHEDULE` | integer[] | unset | App, Worker |\n| `WORKER_WEBHOOKS_MAX_RETRY_AFTER` | integer | 86400000 | App, Worker |\n| `WORKER_WEBHOOKS_RESPONSE_CAPTURE_BYTES` | integer | 16384 | App, Worker |\n| `WORKER_WEBHOOKS_RETENTION_DAYS` | integer | 30 | App, Worker |\n| `WORKER_WEBHOOKS_ALLOW_PRIVATE_DESTINATIONS` | boolean | unset | App, Worker |\n| `WORKER_WEBHOOKS_ENABLE_NOTIFY` | boolean | true | App, Worker |\n\n</Accordion>\n\n## Agent sandboxes\n\nSANDBOX_PROVIDER accepts e2b, docker or remote; unset selects E2B. Configure sandbox settings on app and worker. Builder sessions require E2B. Builder mounts require a scoped credential issuer. Credential TTL defaults to 3600 seconds; longer explicit values require issuer support.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `EIGENPAL_SANDBOX_ENABLED` | true &#124; false | \"true\" | App, Worker, Agent runtime |\n| `E2B_API_KEY` | string | unset; feature-dependent | App, Agent runtime |\n| `E2B_SANDBOX_TEMPLATE` | string | unset; feature-dependent | App, Agent runtime |\n| `SANDBOX_PROVIDER` | string | unset; feature-dependent | Agent runtime |\n| `DOCKER_SANDBOX_IMAGE` | string | unset; feature-dependent | Agent runtime |\n| `DOCKER_SANDBOX_PLATFORM` | string | unset; feature-dependent | Agent runtime |\n| `SANDBOX_REMOTE_URL` | string | unset; feature-dependent | Agent runtime |\n| `SANDBOX_REMOTE_AUTH_TOKEN` | string | unset; feature-dependent | Agent runtime |\n| `EIGENPAL_API_BASE_URL` | string | unset; feature-dependent | Agent runtime |\n| `EIGENPAL_API_TOKEN` | string | unset; feature-dependent | Agent runtime |\n| `SANDBOX_STORAGE_STS_ROLE_ARN` | string | unset | App, Worker |\n| `SANDBOX_STORAGE_R2_ACCOUNT_ID` | string | unset | App, Worker |\n| `SANDBOX_STORAGE_R2_API_TOKEN` | string | unset | App, Worker |\n| `SANDBOX_STORAGE_CREDENTIAL_TTL_SECONDS` | integer | 3600 | App, Worker |\n\n</Accordion>\n\n## Agent Git server\n\nAgents need a Git server; EIGENPAL_AGENTS_ENABLED=false hides them and refuses agent runs on installations without one. Run the Git server separately with persistent repository storage. AGENT_GIT_BASE_URL belongs to its callers; port, host, storage root and command limits belong to the Git server. Keep operator credentials private and identical where used.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `EIGENPAL_AGENTS_ENABLED` | true &#124; false | \"true\" | App, Agent runtime |\n| `AGENT_GIT_BASE_URL` | string | unset; feature-dependent | App, Worker |\n| `AGENT_GIT_ADMIN_TOKEN` | string | unset; feature-dependent | App, Git server |\n| `AGENT_GIT_REQUEST_TIMEOUT_MS` | number | 30000 | App |\n| `GIT_SERVER_PORT` | number | unset; feature-dependent | Git server |\n| `GIT_SERVER_HOST` | string | \"0.0.0.0\" | Git server |\n| `AGENT_GIT_STORAGE_ROOT` | string | installation-specific | Git server |\n| `AGENT_GIT_MAX_REQUEST_BODY_BYTES` | number | 104857600 | Git server |\n| `AGENT_GIT_COMMAND_TIMEOUT_MS` | number | 60000 | Git server |\n\n</Accordion>\n\n## Logs and tracing\n\nCollect audit logs from stdout. Product telemetry and OpenTelemetry tracing have separate switches. Provide collector endpoints and authentication for your installation.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `LOG_LEVEL` | trace &#124; debug &#124; info &#124; warn &#124; error &#124; fatal &#124; silent | \"info\" | App, Worker |\n| `LOG_PRETTY` | boolean | false | App, Worker |\n| `EIGENPAL_TELEMETRY_ENABLED` | boolean | true | App, Worker |\n| `OTEL_ENABLED` | true &#124; false | \"false\" | Tracing |\n| `OTEL_SERVICE_NAME` | string | unset; feature-dependent | Tracing |\n| `OTEL_SERVICE_VERSION` | string | unset; feature-dependent | Tracing |\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | string | unset; feature-dependent | Tracing |\n| `OTEL_EXPORTER_OTLP_HEADERS` | string | unset; feature-dependent | Tracing |\n| `OTEL_EXPORTER_OTLP_PROTOCOL` | string | unset; feature-dependent | Tracing |\n\n</Accordion>\n\n## Single-node storage\n\nFresh evaluation installations use embedded storage. Select external explicitly for AWS S3 or another S3-compatible service. The persisted selection prevents accidental backend changes on restart.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `EIGENPAL_SINGLE_NODE_STORAGE_BACKEND` | embedded &#124; external | \"embedded\" | Single-node supervisor + migration CLI |\n\n</Accordion>\n\n## Maintenance and integrations\n\nCRON_SECRET authenticates scheduled maintenance. Configure promotion callbacks through Helm notifications. Provider credentials referenced by YAML can use your own variable names through configEnv.\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default | Process |\n| --- | --- | --- | --- |\n| `CRON_SECRET` | string | unset; feature-dependent | App |\n| `PROMOTION_WEBHOOK_SECRET` | string (at least 32 characters) | unset | App |\n| `NODE_EXTRA_CA_CERTS` | PEM file path | unset | App + worker |\n\n</Accordion>\n"
2270
+ "content": "---\ntitle: \"Environment variables\"\ndescription: \"Deployment settings by capability and process.\"\n---\n\n{/* Generated by bun docs:generate from checked-in configuration. Do not edit. */}\n\nSupply settings through the chart or your process environment. On Kubernetes, the chart sets the database, storage, tenant and secret variables for you from its values; add anything else through `app.extraEnv` and `worker.extraEnv`. Restart affected processes after changes. Each entry lists its type, its default when unset, and the processes that read it. Addresses, credentials and installation identifiers are supplied by you. Internal hosting, billing, build and authentication-bypass settings are outside this reference.\n\nStart with [Configuration](/self-hosting/configuration).\n\n## Database and storage\n\nWhere EigenPal keeps its data: one PostgreSQL database and one object storage bucket shared by every app and worker process. Database timeouts use seconds; S3 timeouts use milliseconds. When an S3_* credential or region is unset, the matching AWS_* variable is used instead.\n\n<ResponseField name=\"DATABASE_URL\" type=\"string\" default=\"installation-specific\">\nPostgreSQL connection string, for example `postgresql://eigenpal:<password>@db.example.internal:5432/eigenpal?sslmode=require`. Required; processes fail at startup without a reachable database. Read by: App, Worker, Git server.\n</ResponseField>\n\n<ResponseField name=\"DATABASE_READ_REPLICA_URLS\" type=\"string\">\nComma-separated connection strings of read replicas. Read-only queries are spread across them; leave unset to send every query to `DATABASE_URL`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"DATABASE_POOL_SIZE\" type=\"integer\" default=\"10\">\nMaximum open connections per process, 1 to 100. Multiply by the number of app and worker replicas to size the database connection limit. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"DATABASE_IDLE_TIMEOUT\" type=\"integer | null\" default=\"20\">\nSeconds before an idle pooled connection is closed, 0 to 3600. Set `null` to keep idle connections open. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"DATABASE_MAX_LIFETIME\" type=\"integer | null\" default=\"1800\">\nSeconds before a pooled connection is replaced, 0 to 86400. Set `null` for no limit. Lower it when a proxy or firewall drops long-lived connections. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"DATABASE_CONNECT_TIMEOUT\" type=\"integer\" default=\"10\">\nSeconds to wait for a new database connection, 1 to 60, before failing instead of hanging. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"DATABASE_QUERY_TIMEOUT\" type=\"integer\" default=\"30\">\nSeconds before a running query is cancelled, 0 to 300. `0` disables the limit. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"STORAGE_TYPE\" type=\"local | s3\" default=\"local\">\nObject storage backend: `s3` for any S3-compatible service, `local` for a directory on disk (development only). The Helm chart always sets `s3`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"STORAGE_PATH\" type=\"string\" default=\"installation-specific\">\nDirectory for stored files when `STORAGE_TYPE=local`. Ignored with `s3`. Every process must see the same directory. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_BUCKET\" type=\"string\">\nBucket for documents, run inputs and outputs. Required with `STORAGE_TYPE=s3`; the bucket must already exist. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_REGION\" type=\"string\" default=\"us-east-1\">\nBucket region, for example `eu-central-1`. S3-compatible services such as MinIO usually accept any value. Falls back to `AWS_REGION`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_ENDPOINT\" type=\"string\">\nEndpoint URL of an S3-compatible service, for example `https://s3.example.internal`. Leave unset for AWS S3. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_ACCESS_KEY\" type=\"string\">\nAccess key ID for the bucket. Falls back to `AWS_ACCESS_KEY_ID`; leave both unset to use the workload identity of the pod (for example IRSA). Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_SECRET_KEY\" type=\"string\">\nSecret access key paired with `S3_ACCESS_KEY`. Falls back to `AWS_SECRET_ACCESS_KEY`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_CONNECTION_TIMEOUT_MS\" type=\"integer\">\nMilliseconds to establish the TCP and TLS connection to storage. Unset uses the SDK default. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_SOCKET_TIMEOUT_MS\" type=\"integer\">\nMilliseconds a storage connection may sit idle mid-transfer before it is dropped. Guards against stalled downloads. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_REQUEST_TIMEOUT_MS\" type=\"integer\">\nTotal milliseconds allowed for one storage request and its response. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_MULTIPART_COMPLETE_TIMEOUT_MS\" type=\"integer\">\nMilliseconds to wait for the first byte when completing or aborting a multipart upload. Assembling a large object can take minutes; unset uses 5 minutes. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"S3_MAX_ATTEMPTS\" type=\"integer\">\nAttempts per storage request, including retries of connection errors and throttling. Unset uses the SDK default. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_SECRETS_WRAPPING_KEY\" type=\"string\">\nAt-rest encryption key: base64url text that decodes to exactly 32 bytes. Encrypts workflow variables, webhook signing secrets, email server passwords and file source credentials in the database. Set the same value on app and worker, back it up, and never change it: data encrypted with it cannot be read without it. Generate with `openssl rand -base64 32 | tr '+/' '-_' | tr -d '='`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_SECRETS_WRAPPING_KEY_FILE\" type=\"string\">\nPath to a file containing the wrapping key, for example a mounted Secret. Takes precedence over `EIGENPAL_SECRETS_WRAPPING_KEY`. Read by: App, Worker.\n</ResponseField>\n\n## Authentication\n\nSelf-hosted installations run in single-tenant mode: one organization, with password sign-in, single sign-on or both. Keep the installation identity, session secret and SSO provider ID stable once users exist. See the authentication guide before turning off password sign-in.\n\n<ResponseField name=\"EIGENPAL_TENANT_MODE\" type=\"single-tenant | multi-tenant\" default=\"multi-tenant\">\nUse `single-tenant` for every self-hosted installation; the release images and the Helm chart set it. `multi-tenant` is the hosted service mode. Read by: App, Worker, Git server.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_TENANT_ID\" type=\"string\">\nID of the single organization, matching `^tenant_[a-z0-9_]{1,56}$`. Read only when the organization is first created; unset uses `tenant_default`. Changing it later has no effect. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_TENANT_NAME\" type=\"string\">\nDisplay name of the organization when it is first created. Unset uses `Default`. Rename it later in Settings. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_ADMIN_EMAIL\" type=\"string\">\nEmail of the initial owner account. Required in single-tenant mode. The account is created or confirmed as an owner on every start; changing the address adds a second owner and leaves the first in place. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_ADMIN_PASSWORD\" type=\"string\">\nPassword of the initial owner: at least 12 characters with upper and lower case letters, a digit and a special character. The app refuses to start with a weaker value. Changing it resets that account password on the next start. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_ADMIN_NAME\" type=\"string\">\nDisplay name of the initial owner. Unset uses `Admin`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_AUTH_METHODS\" type=\"string\" default=\"password\">\nComma-separated sign-in methods: `password`, `sso` or `password,sso`. Unknown methods are rejected. SSO also needs `SSO_ENABLED=true`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_ALLOW_OPEN_SIGNUP\" type=\"true | false\" default=\"false\">\nWhen `true`, anyone who can reach the installation may create a password account and join the organization. Leave `false` so new users need an invitation; the first account always works. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_SIGN_OUT_URL\" type=\"string\">\nWhere the browser goes after signing out, for example your SSO provider logout page. Unset falls back to `BETTER_AUTH_URL`, then to the app itself. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"BETTER_AUTH_SECRET\" type=\"string\">\nSigns session cookies. At least 32 characters in production. Changing it signs every user out. Generate with `openssl rand -base64 48`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"BETTER_AUTH_URL\" type=\"string\">\nPublic origin of the installation as users reach it, for example `https://eigenpal.example.com`, with no path or trailing slash. Builds SSO callback URLs, so register `<BETTER_AUTH_URL>/api/auth/callback/<SSO_PROVIDER_ID>` with your identity provider. Falls back to `SERVER_BASE_URL`; set one of them whenever the app sits behind a proxy or uses SSO. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_ENABLED\" type=\"true | false\" default=\"false\">\nSet `true` to load single sign-on settings at startup. With `true`, missing or invalid SSO settings stop the app with a message naming them. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_PROTOCOL\" type=\"string\">\n`oidc` (default) for any OpenID Connect provider such as Entra ID, Okta or Keycloak. `user-auth` for an in-house sign-in service that redirects back with a one-time token, which the app exchanges server to server. Any other value stops the app. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_PROVIDER_ID\" type=\"string\">\nShort, stable ID of the identity provider, used in callback URLs and to link accounts, for example `entra`. 1 to 64 letters, digits, dots, underscores or hyphens; `credential` and `clerk` are reserved. Changing it unlinks existing SSO accounts. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_PROVIDER_LABEL\" type=\"string\">\nText of the sign-in button. Unset shows `Sign in with <SSO_PROVIDER_ID>`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_CLIENT_ID\" type=\"string\">\nOIDC client ID registered with the identity provider. Required for `oidc`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_CLIENT_SECRET\" type=\"string\">\nOIDC client secret registered with the identity provider. Required for `oidc`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_DISCOVERY_URL\" type=\"string\">\nOIDC discovery document URL, ending in `/.well-known/openid-configuration`. Required for `oidc`; must use HTTPS in production. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_SCOPES\" type=\"string\" default=\"openid,profile,email\">\nComma-separated OAuth scopes requested at sign-in. Add the scope your provider needs to include groups, if any. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_ALLOWED_EMAIL_DOMAINS\" type=\"string\">\nComma-separated email domains allowed to sign in with SSO, for example `example.com,example.org`. Required: users from other domains are refused even when the provider authenticates them. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_DEFAULT_ROLE\" type=\"string\">\nRole for an SSO user who matches no `SSO_ROLE_MAP` entry: `member`, `reviewer`, `viewer` or `deny` (refuse sign-in). `deny` requires `SSO_ROLE_MAP`. Unset means `member` for `oidc` and `deny` for `user-auth`. `owner` and `admin` cannot be defaults. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_LOGIN_URL\" type=\"string\">\n`user-auth` only: the sign-in page users are redirected to, with the app ID and return address. Required for `user-auth`; HTTPS in production. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_SERVICE_URL\" type=\"string\">\n`user-auth` only: base URL of the server-to-server API that exchanges the one-time token for the user. Required for `user-auth`; HTTPS in production. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_APP_ID\" type=\"string\">\n`user-auth` only: the application ID this installation is registered under. Required for `user-auth`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_APP_SECRET\" type=\"string\">\n`user-auth` only: application secret for HTTP Basic authentication of the token exchange. Needed when no client certificate is configured. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_USERINFO_PATH\" type=\"string\">\n`user-auth` only: path under `SSO_SERVICE_URL` that exchanges the token for the user, for example `api/getUser` (the default). Must stay on the same origin. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_CLIENT_CERT_FILE\" type=\"string\">\n`user-auth` only: path to the PEM client certificate for mutual TLS on the token exchange, typically a mounted Secret. Set together with `SSO_CLIENT_KEY_FILE`. Read and validated at startup; restart the app after rotating it. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_CLIENT_KEY_FILE\" type=\"string\">\n`user-auth` only: path to the unencrypted PEM private key that matches `SSO_CLIENT_CERT_FILE`. A missing, unreadable or mismatched key stops the app at startup. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_CA_BUNDLE_FILE\" type=\"string\">\n`user-auth` only: path to a PEM bundle of CA certificates to trust for the sign-in service, when its certificate is issued by an internal CA. Works with or without a client certificate. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_ROLE_MAP\" type=\"string\">\nComma-separated `<role>:<group>` pairs that grant an EigenPal role from an identity provider group or role, for example `admin:eigenpal-admins,member:eigenpal-users`. Roles are `admin`, `member`, `reviewer` and `viewer`; a user in several mapped groups gets the first in that order. Required for `user-auth`, optional for `oidc`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_GROUPS_CLAIM\" type=\"string\">\n`oidc` only: claim that lists the user groups, read from the ID token or userinfo. Unset uses `groups`; dot paths reach nested claims, for example `realm_access.roles`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_GROUP_FILTER\" type=\"string\">\nRegular expression; only identity provider groups that match become EigenPal groups, for example `^eigenpal-`. Unset keeps every group. An invalid expression stops the app. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_DIRECTORY_RESYNC_SECONDS\" type=\"string\">\nHow often, in seconds, a signed-in user groups and role are re-checked with the identity provider. Unset uses 300. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_DIRECTORY_MAX_STALENESS_SECONDS\" type=\"string\">\nWhen the identity provider cannot be reached, how many seconds a user keeps the last known groups before access is refused. Unset uses 86400; must be at least `SSO_DIRECTORY_RESYNC_SECONDS`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_SESSION_MAX_AGE_SECONDS\" type=\"string\">\nMaximum session lifetime, in seconds, for SSO sign-ins. Unset uses 7 days (604800). Read by: App.\n</ResponseField>\n\n<ResponseField name=\"SSO_USER_LOOKUP_PATH\" type=\"string\">\n`user-auth` only: path under `SSO_SERVICE_URL` that returns the current roles of a user by username, used for re-checks between sign-ins. Unset means roles refresh only when the user signs in again. Read by: App.\n</ResponseField>\n\n## Networking and transfers\n\nHow browsers and clients reach the app, and how files move between them and storage. Byte limits apply independently: request size, archive size and the reusable-file quota.\n\n<ResponseField name=\"SERVER_BASE_URL\" type=\"string\">\nPublic origin of the installation, for example `https://eigenpal.example.com`, with no trailing slash. Used for links in emails and invitations, API documentation, and the address agent builder sandboxes call back to. The Helm chart does not set it; add it through `extraEnv` on app and worker. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SERVER_PORT\" type=\"integer\" default=\"3000\">\nPort the app listens on. Falls back to `PORT`. Keep 3000 with the Helm chart, which targets that container port. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_CONFIG_PATH\" type=\"string\">\nPath of the deployment YAML file (`eigenpal.config.yaml`) with models, file sources and promotion. Startup fails when the path is set but the file is missing. The Helm chart sets `/etc/eigenpal/eigenpal.config.yaml`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_TRUSTED_ORIGINS\" type=\"string\">\nComma-separated extra origins allowed to make signed-in changes from a browser, for example `https://eigenpal.example.com`; an entry without a scheme means https. The address a request was sent to is always allowed. Needed when a proxy rewrites the `Host` header without forwarding `X-Forwarded-Host`; otherwise dashboard changes fail with 403 `csrf_origin_rejected`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_BROWSER_STORAGE_ORIGINS\" type=\"string\">\nComma-separated object storage origins the browser may load files from directly, added to the Content Security Policy. Set it with `EIGENPAL_DIRECT_FILE_UPLOADS=true` when the bucket has a different origin than the app. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_DIRECT_FILE_UPLOADS\" type=\"true | false\" default=\"false\">\nWhen `true`, files larger than `EIGENPAL_MULTIPART_MAX_BYTES` are uploaded and downloaded directly between the browser and object storage using short-lived signed URLs, bypassing the app. Requires storage reachable from browsers and a bucket CORS rule for the app origin. Leave `false` to stream every file through the app. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_MULTIPART_MAX_BYTES\" type=\"number\">\nLargest file, in bytes, sent through the app in one request; larger files use direct storage transfer when it is enabled. Set `none` for no limit. Overrides `deployment.multipartMaxBytes` in the deployment YAML; with neither set the limit is 4.5 MiB. Match it to your proxy body-size limit. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_ARCHIVE_MAX_BYTES\" type=\"number\">\nLargest ZIP archive, in bytes, accepted for upload. Overrides `deployment.archiveMaxBytes` in the deployment YAML; with neither set the limit is 5 GiB. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_REUSABLE_FILES_MAX_BYTES\" type=\"number\" default=\"0\">\nTotal bytes of reusable files the organization may keep in storage. Checked when a reusable file is created. `0` means no limit. Read by: App.\n</ResponseField>\n\n## Worker execution\n\nHow workers pick up runs and limit the work each step may do. Pool polling, leases, health and step limits use milliseconds unless the name says otherwise; memory and output limits use bytes.\n\n<ResponseField name=\"WORKER_POOL_CONCURRENCY\" type=\"integer\" default=\"4\">\nRuns one worker process executes at the same time, 1 to 100. Raise it with CPU and memory; total capacity is this value times the worker replicas. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_POOL_POLL_INTERVAL\" type=\"integer\" default=\"1000\">\nMilliseconds between checks for new runs when the queue was just active, 100 to 60000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_POOL_MAX_POLL_INTERVAL\" type=\"integer\" default=\"30000\">\nLongest wait in milliseconds between checks when the queue stays empty, 1000 to 300000. Polling slows down gradually up to this value. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_POOL_BACKOFF_MULTIPLIER\" type=\"number\" default=\"2\">\nFactor applied to the poll interval after each empty check, 1.1 to 4. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_POOL_LEASE_DURATION\" type=\"integer\" default=\"60000\">\nMilliseconds a worker holds a run before another worker may take it over, 1000 to 600000. A worker that stops renewing, for example after a crash, releases its runs after this time. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_POOL_LEASE_RENEWAL_INTERVAL\" type=\"integer\" default=\"10000\">\nMilliseconds between lease renewals for running work, 1000 to 60000. Keep it well below `WORKER_POOL_LEASE_DURATION`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_POOL_ENABLE_NOTIFY\" type=\"boolean\" default=\"true\">\nWake workers immediately on new runs through PostgreSQL LISTEN/NOTIFY instead of waiting for the next poll. Falls back to polling when unavailable. Turn off only if a connection pooler blocks LISTEN. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_POOL_DIRECT_DATABASE_URL\" type=\"string\">\nSeparate PostgreSQL connection string for the LISTEN connection, when `DATABASE_URL` points at a transaction-mode pooler that does not support LISTEN. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_MAX_TENANT_CONCURRENCY\" type=\"integer\" default=\"3\">\nMost runs of all kinds the organization may have executing at once across all workers, 1 to 1000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_MAX_TENANT_AGENT_CONCURRENCY\" type=\"integer\" default=\"2\">\nMost agent runs the organization may have executing at once, 1 to 1000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_MAX_TENANT_WORKFLOW_CONCURRENCY\" type=\"integer\" default=\"2\">\nMost workflow runs the organization may have executing at once, 1 to 1000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_MAX_BATCH_CONCURRENCY\" type=\"integer\" default=\"2\">\nHighest concurrency a user may request for a single batch of runs, 1 to 1000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"HEALTH_ENABLED\" type=\"true | false\" default=\"true\">\nServe the worker health endpoints `/health/live` and `/health/ready` for Kubernetes probes. They run on a separate thread so a busy worker still answers. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"HEALTH_PORT\" type=\"number\" default=\"8080\">\nPort of the worker health endpoints, 1 to 65535. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"HEALTH_HOST\" type=\"string\" default=\"0.0.0.0\">\nAddress the health endpoints bind to. Use `127.0.0.1` to keep them off the network. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"HEALTH_LIVENESS_STALE_MS\" type=\"number\" default=\"30000\">\nThe liveness check fails when the main worker loop has not reported in for this many milliseconds, so Kubernetes restarts a stuck worker. Minimum 1000. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"HEALTH_HEARTBEAT_INTERVAL_MS\" type=\"number\" default=\"1000\">\nMilliseconds between main loop heartbeats, minimum 100. Keep it well below `HEALTH_LIVENESS_STALE_MS`. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SCRIPT_ENABLED\" type=\"true | false\" default=\"true\">\nAllow `transform.script` workflow steps. When `false`, those steps fail with a capability error. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SCRIPT_TIMEOUT_MS\" type=\"number\" default=\"5000\">\nDefault time limit in milliseconds for one `transform.script` step. A step may ask for more, up to `SCRIPT_MAX_TIMEOUT_MS`. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SCRIPT_MAX_TIMEOUT_MS\" type=\"number\" default=\"30000\">\nHighest time limit in milliseconds a script step may request. Capped below `HEALTH_LIVENESS_STALE_MS`, because a running script blocks the worker loop. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SCRIPT_MEMORY_LIMIT_BYTES\" type=\"number\" default=\"10485760\">\nDefault memory limit in bytes for one script step (10 MiB). Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SCRIPT_MAX_MEMORY_BYTES\" type=\"number\" default=\"52428800\">\nHighest memory limit in bytes a script step may request (50 MiB). Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"TEMPLATE_RENDER_LIMIT_MS\" type=\"number\" default=\"5000\">\nTime limit in milliseconds for rendering one `{{ }}` template in a step configuration. Capped below `HEALTH_LIVENESS_STALE_MS`. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SOFFICE_POOL_SIZE\" type=\"number\" default=\"4\">\nLibreOffice processes kept ready for converting Word, PowerPoint and other office files to PDF. Each uses memory; size it to the worker memory limit. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SOFFICE_CONVERSION_TIMEOUT_MS\" type=\"number\" default=\"60000\">\nMilliseconds one office conversion may run before it is stopped, minimum 1000. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SOFFICE_ACQUIRE_TIMEOUT_MS\" type=\"number\" default=\"600000\">\nMilliseconds a conversion may wait for a free LibreOffice process before failing with a retryable error, minimum 1000. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"PDFTOTEXT_TIMEOUT_MS\" type=\"number\" default=\"60000\">\nMilliseconds the layout-preserving PDF text extraction (`pdftotext -layout`) may run, minimum 1000. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"PDFTOTEXT_MAX_OUTPUT_BYTES\" type=\"number\" default=\"33554432\">\nLargest text output in bytes from one layout extraction (32 MiB); larger output stops the extraction. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"ZIP_PROCESS_INFLATION_BUDGET_BYTES\" type=\"number\" default=\"536870912\">\nBytes of ZIP content one worker process may decompress at the same time (512 MiB). Lower it on memory-limited pods. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"RENDER_SUBPROCESS_CONCURRENCY\" type=\"number\" default=\"1\">\nPage-rendering child processes per worker. Each loads the PDF renderers, so size by memory, not CPU; 1 suits a 2 GiB worker. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"RENDER_SUBPROCESS_TIMEOUT_MS\" type=\"number\" default=\"180000\">\nMilliseconds one page render may run before its child process is killed, minimum 1000. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"RENDER_SUBPROCESS_ACQUIRE_TIMEOUT_MS\" type=\"number\" default=\"600000\">\nMilliseconds a render may wait for a free render process before failing, minimum 1000. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"RENDER_SUBPROCESS_MAX_RESULT_BYTES\" type=\"number\" default=\"419430400\">\nLargest total image output in bytes from one render (400 MiB, minimum 1 MiB). Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"EXTRACT_GROUNDING_MAX_LX_CHARS\" type=\"number\">\nMost characters of document text the `ai.extract` grounding pass sends to the model to locate values, roughly one model call per 6,000 characters. Unset uses 150,000. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"SPLIT_WINDOW_TOKEN_BUDGET\" type=\"number\" default=\"20000\">\nTokens per window when `ai.split` cuts a document into windows, one model call each. A step can override it with `windowTokenBudget`. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OCR_ANALYSIS_CONCURRENCY\" type=\"number\" default=\"8\">\nMost OCR requests one worker sends to an external OCR provider at once. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OCR_ANALYSIS_IDLE_TIMEOUT_MS\" type=\"number\" default=\"180000\">\nAn OCR operation fails when the provider reports no progress for this many milliseconds. Long operations that keep progressing are not cut off. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OCR_ANALYSIS_REQUEST_TIMEOUT_MS\" type=\"number\" default=\"30000\">\nMilliseconds allowed for each single OCR HTTP request. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OCR_ANALYSIS_POLL_INTERVAL_MS\" type=\"number\" default=\"2000\">\nMilliseconds between status checks of a long-running OCR operation, minimum 100. Read by: Worker.\n</ResponseField>\n\n## Outbound webhooks\n\nDelivery of run events to the webhook endpoints organizations configure in the dashboard. Times use milliseconds; retention uses days. Request timeout, retry schedule and private destinations can be pinned here for the whole installation; when unset, the dashboard setting applies. With Helm, set them through the `webhooks` values.\n\n<ResponseField name=\"WORKER_WEBHOOKS_CONCURRENCY\" type=\"integer\" default=\"4\">\nDeliveries one worker sends at the same time, 1 to 100. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_MAX_TENANT_CONCURRENCY\" type=\"integer\" default=\"2\">\nMost deliveries in flight for the organization at once, 1 to 100. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_POLL_INTERVAL\" type=\"integer\" default=\"1000\">\nMilliseconds between checks for pending deliveries, 100 to 60000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_MAX_POLL_INTERVAL\" type=\"integer\" default=\"30000\">\nLongest wait in milliseconds between checks when nothing is pending, 1000 to 300000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_LEASE_DURATION\" type=\"integer\" default=\"60000\">\nMilliseconds a worker holds a delivery before another may retry it, 5000 to 600000. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_LEASE_RENEWAL_INTERVAL\" type=\"integer\" default=\"10000\">\nMilliseconds between lease renewals, 1000 to 60000; must be shorter than the lease duration. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_REQUEST_TIMEOUT\" type=\"integer\">\nPins the time each delivery waits for the receiver, 100 to 120000 milliseconds. Unset leaves it to the dashboard (default 10000). Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_RETRY_SCHEDULE\" type=\"integer[]\">\nPins the retry schedule: comma-separated delays in milliseconds before each attempt, the first usually `0`, at most 20 entries. For example `0,30000,120000,600000`. Unset leaves it to the dashboard. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_MAX_RETRY_AFTER\" type=\"integer\" default=\"86400000\">\nLongest `Retry-After` delay from a receiver that is honored, in milliseconds (one day). Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_RESPONSE_CAPTURE_BYTES\" type=\"integer\" default=\"16384\">\nBytes of each response body stored in the delivery log, 0 to 1 MiB. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_RETENTION_DAYS\" type=\"integer\" default=\"30\">\nDays delivery history is kept, 1 to 3650. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_ALLOW_PRIVATE_DESTINATIONS\" type=\"boolean\">\nPins whether endpoints may resolve to private network addresses such as `10.x` or cluster services. Loopback, link-local and cloud metadata addresses are always refused. Unset leaves it to the dashboard (on by default for self-hosted). Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"WORKER_WEBHOOKS_ENABLE_NOTIFY\" type=\"boolean\" default=\"true\">\nWake delivery workers immediately through PostgreSQL LISTEN/NOTIFY instead of waiting for the next poll. Read by: App, Worker.\n</ResponseField>\n\n## File sources\n\nFile sources let a workflow fetch its input from external storage by reference. Define connections in Studio (Settings, File Sources) or under `fileSources` in the deployment YAML; see the [YAML reference](/self-hosting/yaml-reference#file-sources). Every supported type is available on single-tenant installations. `FILE_SOURCE_INTEGRATIONS`, which used to list the enabled integration types, is no longer read; remove it.\n\n<ResponseField name=\"FILE_SOURCE_CLIENT_CERT_FILE\" type=\"string\">\nPath to a PEM client certificate the installation presents to file sources that use mutual TLS, typically a mounted Secret. Used by connections that turn on \"Use deployment certificate\", so no private key is pasted into Studio. Set together with `FILE_SOURCE_CLIENT_KEY_FILE` on app and worker. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"FILE_SOURCE_CLIENT_KEY_FILE\" type=\"string\">\nPath to the unencrypted PEM private key that matches `FILE_SOURCE_CLIENT_CERT_FILE`. Read on every request, so a rotated Secret takes effect without a restart; a missing or mismatched key fails the fetch. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"FILE_SOURCE_CA_BUNDLE_FILE\" type=\"string\">\nPath to a PEM bundle of CA certificates to trust for those file source connections, when the server certificate is issued by an internal CA. Optional. Read by: App, Worker.\n</ResponseField>\n\n## Agent sandboxes\n\nAgents that use filesystem tools or skills run in an isolated sandbox. Set these on app and worker. See [Agent sandboxes](/self-hosting/agent-sandboxes) for the backends.\n\n<ResponseField name=\"EIGENPAL_SANDBOX_ENABLED\" type=\"true | false\" default=\"true\">\nAllow agent sandboxes. When `false`, filesystem-dependent agents fail with a capability error and no sandbox provider is contacted. Workflow scripts are controlled separately by `SCRIPT_ENABLED`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"E2B_API_KEY\" type=\"string\">\nAPI key for the E2B sandbox service. Required with `SANDBOX_PROVIDER=e2b`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"E2B_SANDBOX_TEMPLATE\" type=\"string\">\nE2B template that matches this release. Pin the template supplied with your release; unset falls back to a development template. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SANDBOX_PROVIDER\" type=\"string\">\nSandbox backend for agent runs: `e2b`, `docker` or `remote`. Unset selects `e2b`; any other value is an error. The interactive builder always uses E2B. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"DOCKER_SANDBOX_IMAGE\" type=\"string\">\nImage for `SANDBOX_PROVIDER=docker`. Use the release-compatible sandbox image; unset uses `eigenpal-sandbox:local`, which exists only on development machines. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"DOCKER_SANDBOX_PLATFORM\" type=\"string\">\nPlatform for Docker sandbox containers, for example `linux/amd64`, when the host architecture differs from the image. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SANDBOX_REMOTE_URL\" type=\"string\">\nURL of the remote sandbox service for `SANDBOX_PROVIDER=remote`, for example `http://sandbox-service:8081`. Required for `remote`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SANDBOX_REMOTE_AUTH_TOKEN\" type=\"string\">\nShared token, at least 32 characters, that authenticates calls to the remote sandbox service. Must match the token configured on that service. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SANDBOX_STORAGE_STS_ROLE_ARN\" type=\"string\">\nAWS only: IAM role the app assumes to issue short-lived storage credentials limited to one folder for agent builder sandboxes. Builder storage mounts are refused without this or the R2 settings. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SANDBOX_STORAGE_R2_ACCOUNT_ID\" type=\"string\">\nCloudflare R2 only: account ID used to issue temporary storage credentials for builder sandboxes. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SANDBOX_STORAGE_R2_API_TOKEN\" type=\"string\">\nCloudflare R2 only: API token allowed to issue those temporary credentials. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"SANDBOX_STORAGE_CREDENTIAL_TTL_SECONDS\" type=\"integer\" default=\"3600\">\nLifetime of builder sandbox storage credentials, 900 to 43200 seconds. A longer value needs an IAM role whose maximum session duration allows it. Read by: App, Worker.\n</ResponseField>\n\n## Agent Git server\n\nAgents keep their source in a Git server that EigenPal runs as a separate process with persistent storage. Without one, set `EIGENPAL_AGENTS_ENABLED=false`. `AGENT_GIT_BASE_URL` is set on app and worker; the port, host, storage and limits belong to the Git server.\n\n<ResponseField name=\"EIGENPAL_AGENTS_ENABLED\" type=\"true | false\" default=\"true\">\nShow the Agents area and accept agent runs. Set `false` on installations without a Git server: agent pages are hidden, agent API calls return not found, and workflows are unaffected. The Helm chart sets it from `agents.enabled`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"AGENT_GIT_BASE_URL\" type=\"string\">\nURL of the Git server as the app and worker reach it, for example `http://eigenpal-git:4010`. Required when agents are enabled. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"AGENT_GIT_ADMIN_TOKEN\" type=\"string\">\nOperator token shared by the app and the Git server. Set the same value on both. In production it must be at least 32 characters, and the app refuses to start with the development value. Read by: App, Git server.\n</ResponseField>\n\n<ResponseField name=\"AGENT_GIT_REQUEST_TIMEOUT_MS\" type=\"number\" default=\"30000\">\nMilliseconds the app waits for one Git server request. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"GIT_SERVER_PORT\" type=\"number\">\nPort the Git server listens on. `PORT` takes precedence; unset uses 4010. Read by: Git server.\n</ResponseField>\n\n<ResponseField name=\"GIT_SERVER_HOST\" type=\"string\" default=\"0.0.0.0\">\nAddress the Git server binds to. Use `127.0.0.1` when it runs next to the app and should not be reachable from the network. Read by: Git server.\n</ResponseField>\n\n<ResponseField name=\"AGENT_GIT_STORAGE_ROOT\" type=\"string\" default=\"installation-specific\">\nDirectory holding the Git repositories. Put it on a persistent volume and back it up. Read by: Git server.\n</ResponseField>\n\n<ResponseField name=\"AGENT_GIT_MAX_REQUEST_BODY_BYTES\" type=\"number\" default=\"104857600\">\nLargest request body, in bytes, the Git server accepts. Read by: Git server.\n</ResponseField>\n\n<ResponseField name=\"AGENT_GIT_COMMAND_TIMEOUT_MS\" type=\"number\" default=\"60000\">\nMilliseconds one Git command may run before it is stopped. Read by: Git server.\n</ResponseField>\n\n## Logs and tracing\n\nLogs go to stdout as JSON, including the audit log; collect them with your log pipeline. Product telemetry and OpenTelemetry tracing have separate switches.\n\n<ResponseField name=\"LOG_LEVEL\" type=\"trace | debug | info | warn | error | fatal | silent\" default=\"info\">\nLowest level written to the logs: `trace`, `debug`, `info`, `warn`, `error`, `fatal` or `silent`. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"LOG_PRETTY\" type=\"boolean\" default=\"false\">\nHuman-readable log lines instead of JSON. Keep `false` when a log collector parses the output. Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"EIGENPAL_TELEMETRY_ENABLED\" type=\"boolean\" default=\"true\">\nSend product analytics and error reports to EigenPal. Set `false` to keep all of it inside your network; the Helm chart sets it from `telemetry.enabled` (off by default). Read by: App, Worker.\n</ResponseField>\n\n<ResponseField name=\"OTEL_ENABLED\" type=\"true | false\" default=\"false\">\nExport OpenTelemetry traces of worker runs to your collector at `OTEL_EXPORTER_OTLP_ENDPOINT`. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OTEL_SERVICE_NAME\" type=\"string\">\nService name attached to traces. Unset uses `eigenpal-worker`. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OTEL_SERVICE_VERSION\" type=\"string\">\nService version attached to traces. Unset uses the release version. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OTEL_EXPORTER_OTLP_ENDPOINT\" type=\"string\">\nOTLP collector URL, for example `https://otel-collector.example.internal:4318`. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OTEL_EXPORTER_OTLP_HEADERS\" type=\"string\">\nHeaders sent to the collector, as `key=value,key2=value2` or a JSON object, for example an authorization header. Read by: Worker.\n</ResponseField>\n\n<ResponseField name=\"OTEL_EXPORTER_OTLP_PROTOCOL\" type=\"string\">\nOTLP transport: `http/protobuf` (default), `http/json` or `grpc`. An unknown value logs a warning and uses the default. Read by: Worker.\n</ResponseField>\n\n## Single-node storage\n\nApplies only to the single-node image, which can run its own embedded object storage.\n\n<ResponseField name=\"EIGENPAL_SINGLE_NODE_STORAGE_BACKEND\" type=\"embedded | external\" default=\"embedded\">\n`embedded` runs object storage inside the container; `external` uses your S3-compatible service from `S3_BUCKET`, `S3_REGION` and the related variables. The first start records the choice; a later start with a different value is refused until the data is migrated. Set it explicitly whenever you supply S3 settings. Read by: Single-node image.\n</ResponseField>\n\n## Maintenance and integrations\n\nScheduled housekeeping, workflow promotion callbacks and trust for internal certificate authorities.\n\n<ResponseField name=\"CRON_SECRET\" type=\"string\">\nBearer token the scheduled maintenance and promotion jobs send to the app `/api/cron/*` routes. In production the routes refuse to run while it is unset. Any random value, for example from `openssl rand -hex 32`; safe to change with a restart. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"PROMOTION_WEBHOOK_SECRET\" type=\"string (at least 32 characters)\">\nShared secret, at least 32 characters, that verifies GitHub or GitLab notifications for workflow promotion. Needed only when promotion notifications are enabled; the Helm chart wires it from `secrets.promotionWebhookSecret`. Read by: App.\n</ResponseField>\n\n<ResponseField name=\"NODE_EXTRA_CA_CERTS\" type=\"PEM file path\">\nPath to a PEM bundle of extra CA certificates trusted for all outbound TLS, for example an internal S3 endpoint, identity provider or model gateway. Read at process start. The Helm chart sets it from `trustedCA`. Read by: App, Worker.\n</ResponseField>\n"
2250
2271
  },
2251
2272
  {
2252
2273
  "topic": "self-hosting/helm-values",
2253
2274
  "title": "Helm values reference",
2254
2275
  "description": "Chart settings and defaults for your installation.",
2255
2276
  "source": "public",
2256
- "content": "---\ntitle: \"Helm values reference\"\ndescription: \"Chart settings and defaults for your installation.\"\n---\n\n{/* Generated by bun docs:generate from checked-in configuration. Do not edit. */}\n\nUse existing Secrets for production credentials. Empty values can mean omitted settings or Secret references; arrays replace the default array. Pin release images and configure model entries for your installation.\n\nStart with [Install on Kubernetes](/self-hosting/kubernetes) for the required values.\n\n## nameOverride\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `nameOverride` | string | \"\" |\n\n</Accordion>\n\n## fullnameOverride\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `fullnameOverride` | string | \"\" |\n\n</Accordion>\n\n## image\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `image.registry` | string | \"quay.io/eigenpal\" |\n| `image.app.repository` | string | \"eigenpal-app\" |\n| `image.app.tag` | string | \"\" |\n| `image.app.digest` | string | \"\" |\n| `image.worker.repository` | string | \"eigenpal-worker\" |\n| `image.worker.tag` | string | \"\" |\n| `image.worker.digest` | string | \"\" |\n| `image.pullPolicy` | string | \"IfNotPresent\" |\n| `image.pullSecrets` | array | [] |\n\n</Accordion>\n\n## tenant\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `tenant.mode` | string | \"single-tenant\" |\n| `tenant.id` | string | \"\" |\n\n</Accordion>\n\n## agents\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `agents.enabled` | boolean | false |\n\n</Accordion>\n\n## telemetry\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `telemetry.enabled` | boolean | false |\n\n</Accordion>\n\n## webhooks\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `webhooks.allowPrivateDestinations` | string | \"\" |\n| `webhooks.requestTimeoutMs` | string | \"\" |\n| `webhooks.retrySchedule` | string | \"\" |\n\n</Accordion>\n\n## podSecurityContext\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `podSecurityContext.runAsNonRoot` | boolean | true |\n| `podSecurityContext.runAsUser` | number | 10001 |\n| `podSecurityContext.fsGroup` | number | 10001 |\n| `podSecurityContext.seccompProfile.type` | string | \"RuntimeDefault\" |\n\n</Accordion>\n\n## containerSecurityContext\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `containerSecurityContext.allowPrivilegeEscalation` | boolean | false |\n| `containerSecurityContext.capabilities.drop` | array | [\"ALL\"] |\n| `containerSecurityContext.readOnlyRootFilesystem` | boolean | false |\n\n</Accordion>\n\n## serviceAccount\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `serviceAccount.create` | boolean | true |\n| `serviceAccount.name` | string | \"\" |\n| `serviceAccount.annotations` | object | &#123;&#125; |\n\n</Accordion>\n\n## objectStorage\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `objectStorage.endpoint` | string | installation-specific |\n| `objectStorage.bucket` | string | \"\" |\n| `objectStorage.region` | string | \"us-east-1\" |\n\n</Accordion>\n\n## admin\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `admin.email` | string | \"\" |\n| `admin.name` | string | \"Admin\" |\n\n</Accordion>\n\n## secrets\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `secrets.create` | boolean | false |\n| `secrets.databaseUrl.secret` | string | installation-specific |\n| `secrets.databaseUrl.key` | string | \"DATABASE_URL\" |\n| `secrets.s3AccessKey.secret` | string | installation-specific |\n| `secrets.s3AccessKey.key` | string | \"S3_ACCESS_KEY\" |\n| `secrets.s3SecretKey.secret` | string | installation-specific |\n| `secrets.s3SecretKey.key` | string | \"S3_SECRET_KEY\" |\n| `secrets.openaiApiKey.secret` | string | installation-specific |\n| `secrets.openaiApiKey.key` | string | \"OPENAI_API_KEY\" |\n| `secrets.adminPassword.secret` | string | installation-specific |\n| `secrets.adminPassword.key` | string | \"ADMIN_PASSWORD\" |\n| `secrets.betterAuthSecret.secret` | string | installation-specific |\n| `secrets.betterAuthSecret.key` | string | \"BETTER_AUTH_SECRET\" |\n| `secrets.secretsWrappingKey.secret` | string | installation-specific |\n| `secrets.secretsWrappingKey.key` | string | \"EIGENPAL_SECRETS_WRAPPING_KEY\" |\n| `secrets.cronSecret.secret` | string | installation-specific |\n| `secrets.cronSecret.key` | string | \"CRON_SECRET\" |\n| `secrets.promotionTokens` | object | &#123;&#125; |\n| `secrets.promotionWebhookSecret.secret` | string | installation-specific |\n| `secrets.promotionWebhookSecret.key` | string | \"webhook-secret\" |\n| `secrets.values.database.user` | string | evaluation-only input |\n| `secrets.values.database.password` | string | evaluation-only input |\n| `secrets.values.database.db` | string | evaluation-only input |\n| `secrets.values.database.url` | string | evaluation-only input |\n| `secrets.values.s3.accessKey` | string | evaluation-only input |\n| `secrets.values.s3.secretKey` | string | evaluation-only input |\n| `secrets.values.ai.openaiApiKey` | string | evaluation-only input |\n| `secrets.values.admin.password` | string | evaluation-only input |\n| `secrets.values.auth.betterAuthSecret` | string | evaluation-only input |\n| `secrets.values.secretsWrappingKey` | string | evaluation-only input |\n| `secrets.values.cronSecret` | string | evaluation-only input |\n\n</Accordion>\n\n## externalSecrets\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `externalSecrets.enabled` | boolean | false |\n| `externalSecrets.apiVersion` | string | \"external-secrets.io/v1\" |\n| `externalSecrets.secretStoreRef.name` | string | \"\" |\n| `externalSecrets.secretStoreRef.kind` | string | \"ClusterSecretStore\" |\n| `externalSecrets.refreshInterval` | string | \"1h\" |\n| `externalSecrets.extraSecrets` | array | [] |\n\n</Accordion>\n\n## sandboxStorage\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `sandboxStorage.stsRoleArn` | string | \"\" |\n| `sandboxStorage.r2AccountId` | string | \"\" |\n| `sandboxStorage.r2ApiTokenSecret.existingSecret` | string | \"\" |\n| `sandboxStorage.r2ApiTokenSecret.secretKey` | string | \"SANDBOX_STORAGE_R2_API_TOKEN\" |\n| `sandboxStorage.credentialTtlSeconds` | number | 3600 |\n\n</Accordion>\n\n## config\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `config.deployment.multipartMaxBytes` | null | null |\n| `config.deployment.archiveMaxBytes` | number | 5368709120 |\n| `config.models` | array | configure for your installation |\n\n</Accordion>\n\n## configEnv\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `configEnv` | array | [] |\n\n</Accordion>\n\n## trustedCA\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `trustedCA.secretName` | string | \"\" |\n| `trustedCA.configMapName` | string | \"\" |\n| `trustedCA.key` | string | \"ca.crt\" |\n\n</Accordion>\n\n## app\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `app.replicaCount` | number | 2 |\n| `app.extraVolumes` | array | [] |\n| `app.extraVolumeMounts` | array | [] |\n| `app.pdb.enabled` | boolean | false |\n| `app.pdb.minAvailable` | number | 1 |\n| `app.resources.requests.cpu` | string | \"250m\" |\n| `app.resources.requests.memory` | string | \"1Gi\" |\n| `app.resources.limits.cpu` | string | \"1\" |\n| `app.resources.limits.memory` | string | \"2Gi\" |\n| `app.podAnnotations` | object | &#123;&#125; |\n| `app.nodeSelector` | object | &#123;&#125; |\n| `app.tolerations` | array | [] |\n| `app.affinity` | object | &#123;&#125; |\n| `app.extraEnv` | array | [] |\n\n</Accordion>\n\n## worker\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `worker.replicaCount` | number | 2 |\n| `worker.extraVolumes` | array | [] |\n| `worker.extraVolumeMounts` | array | [] |\n| `worker.pdb.enabled` | boolean | false |\n| `worker.pdb.minAvailable` | number | 1 |\n| `worker.concurrency.pool` | string | \"4\" |\n| `worker.concurrency.maxBatch` | string | \"\" |\n| `worker.concurrency.maxTenant` | string | \"\" |\n| `worker.concurrency.maxTenantAgent` | string | \"\" |\n| `worker.concurrency.maxTenantWorkflow` | string | \"\" |\n| `worker.resources.requests.cpu` | string | \"500m\" |\n| `worker.resources.requests.memory` | string | \"512Mi\" |\n| `worker.resources.limits.cpu` | string | \"2\" |\n| `worker.resources.limits.memory` | string | \"2Gi\" |\n| `worker.podAnnotations` | object | &#123;&#125; |\n| `worker.nodeSelector` | object | &#123;&#125; |\n| `worker.tolerations` | array | [] |\n| `worker.affinity` | object | &#123;&#125; |\n| `worker.extraEnv` | array | [] |\n\n</Accordion>\n\n## promotion\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `promotion.enabled` | boolean | false |\n| `promotion.environment` | string | \"\" |\n| `promotion.provider` | string | \"github\" |\n| `promotion.apiUrl` | string | \"\" |\n| `promotion.repositories` | object | &#123;&#125; |\n| `promotion.environments` | array | configure for your installation |\n| `promotion.artifactStore` | object | &#123;&#125; |\n| `promotion.pullSchedule` | string | \"*/15 * * * *\" |\n| `promotion.notifications.enabled` | boolean | false |\n\n</Accordion>\n\n## maintenance\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `maintenance.enabled` | boolean | true |\n| `maintenance.schedule` | string | \"*/15 * * * *\" |\n| `maintenance.image` | string | \"busybox:1.36\" |\n| `maintenance.cronImage` | string | \"\" |\n| `maintenance.command` | array | [] |\n| `maintenance.resources.requests.cpu` | string | \"10m\" |\n| `maintenance.resources.requests.memory` | string | \"32Mi\" |\n| `maintenance.resources.limits.cpu` | string | \"100m\" |\n| `maintenance.resources.limits.memory` | string | \"128Mi\" |\n| `maintenance.nodeSelector` | object | &#123;&#125; |\n| `maintenance.tolerations` | array | [] |\n| `maintenance.affinity` | object | &#123;&#125; |\n\n</Accordion>\n\n## preflight\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `preflight.enabled` | boolean | true |\n| `preflight.strict` | boolean | false |\n| `preflight.expectedClientCN` | string | \"\" |\n| `preflight.ttlSecondsAfterFinished` | number | 86400 |\n| `preflight.podLabels` | object | &#123;&#125; |\n| `preflight.extraEnv` | array | [] |\n| `preflight.resources.requests.cpu` | string | \"100m\" |\n| `preflight.resources.requests.memory` | string | \"256Mi\" |\n| `preflight.resources.limits.cpu` | string | \"1\" |\n| `preflight.resources.limits.memory` | string | \"512Mi\" |\n\n</Accordion>\n\n## migrate\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `migrate.enabled` | boolean | true |\n| `migrate.hook` | boolean | true |\n| `migrate.blob` | boolean | true |\n| `migrate.scripts` | boolean | false |\n| `migrate.extraEnv` | array | [] |\n| `migrate.resources.requests.cpu` | string | \"100m\" |\n| `migrate.resources.requests.memory` | string | \"256Mi\" |\n| `migrate.resources.limits.cpu` | string | \"1\" |\n| `migrate.resources.limits.memory` | string | \"512Mi\" |\n\n</Accordion>\n\n## service\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `service.port` | number | 3000 |\n\n</Accordion>\n\n## ingress\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `ingress.enabled` | boolean | true |\n| `ingress.className` | string | \"nginx\" |\n| `ingress.host` | string | installation-specific |\n| `ingress.annotations.nginx.ingress.kubernetes.io/proxy-read-timeout` | string | \"1800\" |\n| `ingress.annotations.nginx.ingress.kubernetes.io/proxy-send-timeout` | string | \"1800\" |\n| `ingress.annotations.nginx.ingress.kubernetes.io/proxy-body-size` | string | \"500m\" |\n| `ingress.tls` | array | [] |\n\n</Accordion>\n\n## openshift\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `openshift.route.enabled` | boolean | false |\n| `openshift.route.host` | string | installation-specific |\n| `openshift.route.externalCertificate.name` | string | \"\" |\n\n</Accordion>\n\n## networkPolicy\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `networkPolicy.enabled` | boolean | false |\n\n</Accordion>\n\n## postgres\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `postgres.enabled` | boolean | false |\n| `postgres.image` | string | \"postgres:16-alpine\" |\n| `postgres.storage` | string | \"10Gi\" |\n| `postgres.resources.requests.cpu` | string | \"250m\" |\n| `postgres.resources.requests.memory` | string | \"256Mi\" |\n| `postgres.resources.limits.cpu` | string | \"1\" |\n| `postgres.resources.limits.memory` | string | \"1Gi\" |\n\n</Accordion>\n\n## minio\n\n\n\n<Accordion title=\"Show settings\">\n\n| Setting | Type | Default |\n| --- | --- | --- |\n| `minio.enabled` | boolean | false |\n| `minio.image` | string | \"\" |\n| `minio.mcImage` | string | \"\" |\n| `minio.storage` | string | \"20Gi\" |\n| `minio.resources.requests.cpu` | string | \"250m\" |\n| `minio.resources.requests.memory` | string | \"256Mi\" |\n| `minio.resources.limits.cpu` | string | \"1\" |\n| `minio.resources.limits.memory` | string | \"1Gi\" |\n\n</Accordion>\n"
2277
+ "content": "---\ntitle: \"Helm values reference\"\ndescription: \"Chart settings and defaults for your installation.\"\n---\n\n{/* Generated by bun docs:generate from checked-in configuration. Do not edit. */}\n\nEvery value the chart accepts, in `values.yaml` order. Each entry gives the type and default, then what the value does and when to change it. An empty string usually means the setting is omitted from the rendered manifests. Lists you set replace the default list rather than extending it. Credentials never go in values: the `secrets` section names Kubernetes Secrets that hold them.\n\nThe values you must set for a working install are `image.pullSecrets` (for the private registry), `objectStorage.endpoint`, `objectStorage.bucket`, `admin.email`, `config.models` and the Secrets behind `secrets.*`. Start with [Install on Kubernetes](/self-hosting/kubernetes).\n\n## nameOverride\n\n<ResponseField name=\"nameOverride\" type=\"string\" default=\"&quot;&quot;\">\nReplaces the chart name (`eigenpal`) in resource names and the `app.kubernetes.io/name` label. Leave empty unless names collide in your namespace.\n</ResponseField>\n\n## fullnameOverride\n\n<ResponseField name=\"fullnameOverride\" type=\"string\" default=\"&quot;&quot;\">\nReplaces the full resource name prefix (normally `<release>-eigenpal`). The app Service becomes `<fullnameOverride>-app`. Leave empty to derive it from the release name.\n</ResponseField>\n\n## image\n\nContainer images for the app and worker. The EigenPal registry is private, so set `pullSecrets`, or point `registry` at your own mirror.\n\n<ResponseField name=\"image.registry\" type=\"string\" default=\"quay.io/eigenpal\">\nRegistry prefix for every EigenPal image, for example your internal mirror `registry.example.internal/eigenpal`. Empty uses the repository names as they are.\n</ResponseField>\n\n<ResponseField name=\"image.app\" type=\"object\">\nApp image.\n</ResponseField>\n\n<ResponseField name=\"image.app.repository\" type=\"string\" default=\"eigenpal-app\">\nRepository name of the app image under `image.registry`.\n</ResponseField>\n\n<ResponseField name=\"image.app.tag\" type=\"string\" default=\"&quot;&quot;\">\nImage tag. Empty uses the version of the packaged chart. `latest` is refused; pin a release.\n</ResponseField>\n\n<ResponseField name=\"image.app.digest\" type=\"string\" default=\"&quot;&quot;\">\nOptional `sha256:<64 hex characters>` digest. When set it takes precedence over `tag`, which pins the exact image.\n</ResponseField>\n\n<ResponseField name=\"image.worker\" type=\"object\">\nWorker image. The migration Job and CronJobs use it too.\n</ResponseField>\n\n<ResponseField name=\"image.worker.repository\" type=\"string\" default=\"eigenpal-worker\">\nRepository name of the worker image under `image.registry`.\n</ResponseField>\n\n<ResponseField name=\"image.worker.tag\" type=\"string\" default=\"&quot;&quot;\">\nImage tag. Empty uses the version of the packaged chart. `latest` is refused; pin a release.\n</ResponseField>\n\n<ResponseField name=\"image.worker.digest\" type=\"string\" default=\"&quot;&quot;\">\nOptional `sha256:<64 hex characters>` digest. When set it takes precedence over `tag`.\n</ResponseField>\n\n<ResponseField name=\"image.pullPolicy\" type=\"Always | IfNotPresent | Never\" default=\"IfNotPresent\">\nKubernetes image pull policy: `IfNotPresent`, `Always` or `Never`.\n</ResponseField>\n\n<ResponseField name=\"image.pullSecrets\" type=\"array\" default=\"[]\">\nImage pull Secrets for the private registry, as names (`[eigenpal-registry]`) or `{name: ...}` entries. Needed for the EigenPal registry; without it pods stay in `ImagePullBackOff`.\n</ResponseField>\n\n## tenant\n\nIdentity of the single organization this installation serves.\n\n<ResponseField name=\"tenant.mode\" type=\"single-tenant\" default=\"single-tenant\">\nAlways `single-tenant` for self-hosted installations: one organization, built-in sign-in and SSO, no billing.\n</ResponseField>\n\n<ResponseField name=\"tenant.id\" type=\"string\" default=\"&quot;&quot;\">\nOptional fixed ID for the organization, matching `^tenant_[a-z0-9_]{1,56}$`. Used only when the organization is first created; empty uses `tenant_default`. Changing it later has no effect.\n</ResponseField>\n\n## agents\n\nAgents keep their source in a Git server that this chart does not install. Leave agents off unless you run one.\n\n<ResponseField name=\"agents.enabled\" type=\"boolean\" default=\"false\">\nShow the Agents area and accept agent runs. Set `true` only when you operate a Git server and have supplied `AGENT_GIT_BASE_URL` and `AGENT_GIT_ADMIN_TOKEN` to app and worker through `extraEnv`. When false, agents are hidden and agent runs refused; workflows are unaffected.\n</ResponseField>\n\n## telemetry\n\nProduct analytics and error reports sent to EigenPal. Off by default.\n\n<ResponseField name=\"telemetry.enabled\" type=\"boolean\" default=\"false\">\nSend product analytics and error reports to EigenPal. Leave `false` to keep everything inside your network.\n</ResponseField>\n\n## webhooks\n\nInstallation-wide settings for outbound webhook delivery. An empty value leaves the setting to each organization in the dashboard (Webhooks, Delivery settings); a value set here applies to the whole installation and is locked in the dashboard.\n\n<ResponseField name=\"webhooks.allowPrivateDestinations\" type=\"&quot;&quot; | true | false\" default=\"&quot;&quot;\">\n`true` or `false` to pin whether webhook endpoints may resolve to private addresses such as `10.x`, `192.168.x` or cluster services. Loopback and cloud metadata addresses are always refused. Empty leaves it to the dashboard, where it is on by default.\n</ResponseField>\n\n<ResponseField name=\"webhooks.requestTimeoutMs\" type=\"integer | string\" default=\"&quot;&quot;\">\nMilliseconds each delivery waits for the receiver, 100 to 120000. Empty leaves it to the dashboard (default 10000).\n</ResponseField>\n\n<ResponseField name=\"webhooks.retrySchedule\" type=\"string\" default=\"&quot;&quot;\">\nComma-separated delays in milliseconds before each delivery attempt; the first is the initial attempt and is usually `0`. For example `0,30000,120000,600000`. Empty leaves it to the dashboard.\n</ResponseField>\n\n## podSecurityContext\n\n<ResponseField name=\"podSecurityContext\" type=\"object\">\nPod security context for the app, worker, migration and CronJob pods. The images run as the numeric user 10001, and the default satisfies the Pod Security `restricted` profile. On OpenShift set `runAsUser` and `fsGroup` to `null` so the restricted SCC assigns a user ID from the namespace range.\n\nDefault:\n\n```yaml\nrunAsNonRoot: true\nrunAsUser: 10001\nfsGroup: 10001\nseccompProfile:\n type: RuntimeDefault\n```\n</ResponseField>\n\n## containerSecurityContext\n\n<ResponseField name=\"containerSecurityContext\" type=\"object\">\nContainer security context for the same pods. `readOnlyRootFilesystem` is false because the app and worker write temporary files; to make it true, mount writable `emptyDir` volumes through `extraVolumes` first.\n\nDefault:\n\n```yaml\nallowPrivilegeEscalation: false\ncapabilities:\n drop:\n - ALL\nreadOnlyRootFilesystem: false\n```\n</ResponseField>\n\n## serviceAccount\n\nKubernetes service account used by the app, worker and jobs.\n\n<ResponseField name=\"serviceAccount.create\" type=\"boolean\" default=\"true\">\nCreate a service account for this release. Set `false` to use an existing one named in `name`, which is required for workload identity together with the migration hook.\n</ResponseField>\n\n<ResponseField name=\"serviceAccount.name\" type=\"string\" default=\"&quot;&quot;\">\nService account name. Empty uses the release full name when `create` is true, or `default` when it is false.\n</ResponseField>\n\n<ResponseField name=\"serviceAccount.annotations\" type=\"object\" default=\"{}\">\nAnnotations on the created service account, for example `eks.amazonaws.com/role-arn` for IRSA. With annotations and the migration hook enabled, the chart requires `create: false` and a pre-created account, because hooks run before the release creates one.\n</ResponseField>\n\n## objectStorage\n\nThe S3-compatible bucket that holds documents and run files. Credentials are not set here; see `secrets.s3AccessKey` and `secrets.s3SecretKey`.\n\n<ResponseField name=\"objectStorage.endpoint\" type=\"string\" default=\"installation-specific\">\nS3-compatible endpoint URL, for example `https://s3.example.internal`. Required unless `minio.enabled`, in which case it defaults to the in-cluster MinIO service; the chart refuses to render without it.\n</ResponseField>\n\n<ResponseField name=\"objectStorage.bucket\" type=\"string\" default=\"&quot;&quot;\">\nBucket for documents and run files. Required; the chart refuses to render without it. The bucket must exist before install, because the migration Job writes to it.\n</ResponseField>\n\n<ResponseField name=\"objectStorage.region\" type=\"string\" default=\"us-east-1\">\nBucket region, for example `eu-central-1`. S3-compatible services usually accept any value.\n</ResponseField>\n\n## admin\n\nThe initial owner account, created for password sign-in. Its password comes from `secrets.adminPassword`.\n\n<ResponseField name=\"admin.email\" type=\"string\" default=\"&quot;&quot;\">\nEmail of the initial owner. Required; the chart refuses to render without it. Keep it stable: the account is confirmed as an owner on every start, and a new address creates a second owner without removing the first.\n</ResponseField>\n\n<ResponseField name=\"admin.name\" type=\"string\" default=\"Admin\">\nDisplay name of the initial owner.\n</ResponseField>\n\n## secrets\n\nWhere the chart finds credentials. In production (`create: false`) each entry names an existing Kubernetes Secret and the key inside it; the chart only references them, so group keys into Secrets however you like. A required entry with an empty `secret` fails the render; a missing Secret or key stops the pod with `CreateContainerConfigError`, and the pod events name it.\n\n<ResponseField name=\"secrets.create\" type=\"boolean\" default=\"false\">\nEvaluation only. When true, the chart creates one Secret named `<fullname>-secrets` from `secrets.values` and ignores the `secret` and `key` fields. Requires `migrate.hook: false`. Keep `false` in production.\n</ResponseField>\n\n<ResponseField name=\"secrets.databaseUrl\" type=\"object\">\nPostgreSQL connection string, for example `postgresql://<user>:<password>@<host>:5432/<database>?sslmode=require`. Read by app, worker and migration Job as `DATABASE_URL`. Required.\n</ResponseField>\n\n<ResponseField name=\"secrets.databaseUrl.secret\" type=\"string\" default=\"eigenpal-db\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.databaseUrl.key\" type=\"string\" default=\"DATABASE_URL\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.databaseUrl.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3AccessKey\" type=\"object\">\nAccess key for `objectStorage.bucket`. Read by app, worker and migration Job as `S3_ACCESS_KEY`. Required.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3AccessKey.secret\" type=\"string\" default=\"installation-specific\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3AccessKey.key\" type=\"string\" default=\"S3_ACCESS_KEY\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3AccessKey.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3SecretKey\" type=\"object\">\nSecret key for `objectStorage.bucket`. Read by app, worker and migration Job as `S3_SECRET_KEY`. Required.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3SecretKey.secret\" type=\"string\" default=\"installation-specific\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3SecretKey.key\" type=\"string\" default=\"S3_SECRET_KEY\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.s3SecretKey.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.openaiApiKey\" type=\"object\">\nAPI key behind `${OPENAI_API_KEY}` references in `config.models`. Read by app and worker as `OPENAI_API_KEY`. Required only when `config` references it; otherwise the reference is optional and a missing Secret does not block the pods. Other provider credentials go through `configEnv`.\n</ResponseField>\n\n<ResponseField name=\"secrets.openaiApiKey.secret\" type=\"string\" default=\"eigenpal-ai\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.openaiApiKey.key\" type=\"string\" default=\"OPENAI_API_KEY\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.openaiApiKey.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.adminPassword\" type=\"object\">\nPassword of the initial owner (`admin.email`): at least 12 characters with upper and lower case letters, a digit and a special character. Changing it resets that password. Read by the app as `EIGENPAL_ADMIN_PASSWORD`. Required.\n</ResponseField>\n\n<ResponseField name=\"secrets.adminPassword.secret\" type=\"string\" default=\"eigenpal-app\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.adminPassword.key\" type=\"string\" default=\"ADMIN_PASSWORD\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.adminPassword.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.betterAuthSecret\" type=\"object\">\nSigns sign-in sessions, at least 32 characters. Changing it signs everyone out. Generate with `openssl rand -base64 48`. Read by the app as `BETTER_AUTH_SECRET`. Required.\n</ResponseField>\n\n<ResponseField name=\"secrets.betterAuthSecret.secret\" type=\"string\" default=\"eigenpal-app\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.betterAuthSecret.key\" type=\"string\" default=\"BETTER_AUTH_SECRET\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.betterAuthSecret.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.secretsWrappingKey\" type=\"object\">\nAt-rest encryption key: base64url text that decodes to 32 bytes. Encrypts workflow variables, webhook signing secrets, email server passwords and file source credentials. Never change it and back it up; data encrypted with it is lost without it. Generate with `openssl rand -base64 32 | tr '+/' '-_' | tr -d '='`. Read by app and worker as `EIGENPAL_SECRETS_WRAPPING_KEY`. Set `secret` to empty only to run without those features.\n</ResponseField>\n\n<ResponseField name=\"secrets.secretsWrappingKey.secret\" type=\"string\" default=\"eigenpal-app\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.secretsWrappingKey.key\" type=\"string\" default=\"EIGENPAL_SECRETS_WRAPPING_KEY\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.secretsWrappingKey.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.cronSecret\" type=\"object\">\nBearer token between the app `/api/cron/*` routes and the maintenance and promotion CronJobs. Any random value, for example from `openssl rand -hex 32`; safe to change with an app restart. Read by the app and the CronJobs as `CRON_SECRET`. Required while `maintenance.enabled` or promotion is on.\n</ResponseField>\n\n<ResponseField name=\"secrets.cronSecret.secret\" type=\"string\" default=\"eigenpal-app\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.cronSecret.key\" type=\"string\" default=\"CRON_SECRET\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.cronSecret.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionTokens\" type=\"object\" default=\"{}\">\nPromotion Git tokens, one entry per repository in `promotion.repositories`, keyed by its short name: `{secret, key, remoteRef}`. Read by the app only, as `PROMOTION_TOKEN_<NAME>`. A token with write access to this installation's own repository is required; access to the others decides what this installation can do there. With `promotion.repositories.<name>.app.id` the entry holds the GitHub App private key.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionTokens.<name>.secret\" type=\"string\">\nName of the Kubernetes Secret that holds the token.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionTokens.<name>.key\" type=\"string\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionTokens.<name>.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionWebhookSecret\" type=\"object\">\nShared secret for Git host webhook notifications, at least 32 characters. Generate with `openssl rand -base64 48`. Read by the app as `PROMOTION_WEBHOOK_SECRET`. Required when `promotion.notifications.enabled`.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionWebhookSecret.secret\" type=\"string\" default=\"eigenpal-promotion\">\nName of the Kubernetes Secret that holds the value. Empty means not configured.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionWebhookSecret.key\" type=\"string\" default=\"webhook-secret\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.promotionWebhookSecret.remoteRef\" type=\"object\">\nOnly with `externalSecrets.enabled`: where the External Secrets Operator reads the value in your store, as `{key: <path>, property: <field>, version: <version>}`. `property` and `version` are optional. Leave unset when you create this Secret yourself.\n</ResponseField>\n\n<ResponseField name=\"secrets.values\" type=\"object\">\nEvaluation only: literal credentials used when `create: true`. Never put production credentials here. Credential fields ship empty, and the chart refuses to render when one it needs is missing. On upgrade, empty fields keep the value already stored in the Secret.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.database\" type=\"object\">\nIn-cluster or external database connection.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.database.user\" type=\"string\" default=\"evaluation-only input\">\nDatabase user name. Used for the in-cluster PostgreSQL and its readiness probe.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.database.password\" type=\"string\" default=\"evaluation-only input\">\nPassword of the in-cluster PostgreSQL. Required with `postgres.enabled`; generate one per install, for example with `openssl rand -base64 24`. Do not change it after the first install: the database volume keeps the original password.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.database.db\" type=\"string\" default=\"evaluation-only input\">\nDatabase name for the in-cluster PostgreSQL.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.database.url\" type=\"string\" default=\"evaluation-only input\">\nFull PostgreSQL connection string. Empty builds one for the in-cluster PostgreSQL when `postgres.enabled`.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.s3\" type=\"object\">\nObject storage credentials. With `minio.enabled` they also become the MinIO root user and password.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.s3.accessKey\" type=\"string\" default=\"evaluation-only input\">\nAccess key, at least 3 characters for MinIO. Required.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.s3.secretKey\" type=\"string\" default=\"evaluation-only input\">\nSecret key, at least 8 characters for MinIO. Required; generate it per install.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.ai\" type=\"object\">\nModel provider credentials.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.ai.openaiApiKey\" type=\"string\" default=\"evaluation-only input\">\nValue for `${OPENAI_API_KEY}` references in `config.models`.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.admin\" type=\"object\">\nInitial owner credentials.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.admin.password\" type=\"string\" default=\"evaluation-only input\">\nInitial owner password: at least 12 characters with upper and lower case letters, a digit and a special character.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.auth\" type=\"object\">\nSession settings.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.auth.betterAuthSecret\" type=\"string\" default=\"evaluation-only input\">\nSession signing secret, at least 32 characters.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.secretsWrappingKey\" type=\"string\" default=\"evaluation-only input\">\nAt-rest encryption key, base64url text that decodes to 32 bytes. Empty runs without encrypted secrets features.\n</ResponseField>\n\n<ResponseField name=\"secrets.values.cronSecret\" type=\"string\" default=\"evaluation-only input\">\nToken for the maintenance CronJob. Empty generates one and keeps it across upgrades; set it only when you render manifests without cluster access (`helm template`).\n</ResponseField>\n\n## externalSecrets\n\nOptional integration with the External Secrets Operator. When enabled, the chart renders an ExternalSecret for every Secret named under `secrets` whose entries have a `remoteRef`, so the operator fills them from your store (for example Vault). Requires the operator and its CRDs in the cluster.\n\n<ResponseField name=\"externalSecrets.enabled\" type=\"boolean\" default=\"false\">\nRender ExternalSecret resources. Cannot be combined with `secrets.create`. They run as pre-install and pre-upgrade hooks, so the Secrets exist before the migration Job reads them.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.apiVersion\" type=\"external-secrets.io/v1 | external-secrets.io/v1beta1\" default=\"external-secrets.io/v1\">\nExternalSecret API version. `external-secrets.io/v1` needs ESO 0.16 or later; older operators serve `external-secrets.io/v1beta1` with the same fields.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.secretStoreRef\" type=\"object\">\nThe store to read from, created by your platform team.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.secretStoreRef.name\" type=\"string\" default=\"&quot;&quot;\">\nName of the SecretStore or ClusterSecretStore. Required when enabled.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.secretStoreRef.kind\" type=\"ClusterSecretStore | SecretStore\" default=\"ClusterSecretStore\">\n`ClusterSecretStore`, or `SecretStore` for a store in the same namespace.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.refreshInterval\" type=\"string\" default=\"1h\">\nHow often the operator re-reads the store, as a duration such as `1h`. Pods read Secrets at start, so restart them after a value changes.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.extraSecrets\" type=\"array\" default=\"[]\">\nAdditional Secrets for the operator to fill that the chart only refers to by name, for example the image pull Secret, a TLS Secret mounted through `extraVolumes`, or a Secret used by `configEnv`.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.extraSecrets[].name\" type=\"string\">\nName of the Secret to create. Must not be a Secret already produced from `secrets` entries.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.extraSecrets[].type\" type=\"string\">\nKubernetes Secret type, for example `kubernetes.io/dockerconfigjson` or `kubernetes.io/tls`. Empty creates an `Opaque` Secret.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.extraSecrets[].data\" type=\"array\">\nKeys of the Secret, at least one.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.extraSecrets[].data[].secretKey\" type=\"string\">\nKey inside the created Secret, for example `.dockerconfigjson` or `tls.crt`.\n</ResponseField>\n\n<ResponseField name=\"externalSecrets.extraSecrets[].data[].remoteRef\" type=\"object\">\nWhere the operator reads the value: `{key: <path>, property: <field>, version: <version>}`. `key` is required.\n</ResponseField>\n\n## sandboxStorage\n\nShort-lived, folder-scoped storage credentials for agent builder sandboxes, which run model-written code. Configure one provider before using builder storage mounts; mounts are refused without one. Installations that never open the agent builder can leave this empty.\n\n<ResponseField name=\"sandboxStorage.stsRoleArn\" type=\"string\" default=\"&quot;&quot;\">\nAWS only. IAM role the app assumes to issue credentials limited to the mounted folder. The app identity must be allowed to assume it, and its maximum session duration must cover `credentialTtlSeconds`.\n</ResponseField>\n\n<ResponseField name=\"sandboxStorage.r2AccountId\" type=\"string\" default=\"&quot;&quot;\">\nCloudflare R2 only. Account ID for issuing temporary access credentials; the parent key is the object storage access key.\n</ResponseField>\n\n<ResponseField name=\"sandboxStorage.r2ApiTokenSecret\" type=\"object\">\nCloudflare R2 only. Secret holding an API token allowed to issue those credentials.\n</ResponseField>\n\n<ResponseField name=\"sandboxStorage.r2ApiTokenSecret.existingSecret\" type=\"string\" default=\"&quot;&quot;\">\nName of the Secret. Empty leaves R2 credentials off.\n</ResponseField>\n\n<ResponseField name=\"sandboxStorage.r2ApiTokenSecret.secretKey\" type=\"string\" default=\"SANDBOX_STORAGE_R2_API_TOKEN\">\nKey inside that Secret.\n</ResponseField>\n\n<ResponseField name=\"sandboxStorage.credentialTtlSeconds\" type=\"integer\" default=\"3600\">\nLifetime of issued credentials, 900 to 43200 seconds. A mount needs new credentials after they expire.\n</ResponseField>\n\n## config\n\nContents of the deployment YAML (`eigenpal.config.yaml`): models, transfer limits and file sources. Rendered into a ConfigMap mounted on app and worker. Credentials must be `${VAR}` references, never literal values; expose the variables through `configEnv`. Field-by-field reference: [Deployment YAML reference](/self-hosting/yaml-reference).\n\n<ResponseField name=\"config.deployment\" type=\"object\">\nTransfer limits and parser defaults. `multipartMaxBytes: null` keeps every file transfer on the app; set a byte limit when your ingress or proxy caps request size. `archiveMaxBytes` caps ZIP uploads. Fields: [Deployment](/self-hosting/yaml-reference#deployment).\n\nDefault:\n\n```yaml\nmultipartMaxBytes: null\narchiveMaxBytes: 5368709120\n```\n</ResponseField>\n\n<ResponseField name=\"config.models\" type=\"array\" default=\"configure for your installation\">\nApproved language and OCR models, one entry per model with its provider, roles and `${VAR}` credential references. Required: the chart refuses to render with an empty list. Fields: [Language models](/self-hosting/yaml-reference#language-models) and [OCR models](/self-hosting/yaml-reference#ocr-models).\n</ResponseField>\n\n<ResponseField name=\"config.fileSources\" type=\"object\">\nFile source connections defined for the installation, by name. Each shows as read-only in Studio and wins over a Studio connection of the same name. Fields: [File sources](/self-hosting/yaml-reference#file-sources).\n</ResponseField>\n\n<ResponseField name=\"config.promotion\" type=\"object\">\nLeave unset. When `promotion.enabled`, the chart writes this block from the `promotion` values.\n</ResponseField>\n\n## configEnv\n\nEnvironment variables added to both app and worker, for the `${VAR}` references in `config` (for example file source or model credentials). Same format as a container `env` list; take values from Secrets with `valueFrom.secretKeyRef`.\n\n<ResponseField name=\"configEnv[].name\" type=\"string\">\nVariable name, matching the `${NAME}` reference in `config`.\n</ResponseField>\n\n<ResponseField name=\"configEnv[].value\" type=\"string\">\nLiteral value. Use `valueFrom` for credentials.\n</ResponseField>\n\n<ResponseField name=\"configEnv[].valueFrom\" type=\"object\">\nKubernetes value source, usually `{secretKeyRef: {name: ..., key: ...}}`.\n</ResponseField>\n\n## trustedCA\n\nAn internal CA bundle trusted for all outbound TLS from app and worker, for example for an S3 endpoint, identity provider or model gateway signed by your own PKI. Set `secretName` or `configMapName`, not both.\n\n<ResponseField name=\"trustedCA.secretName\" type=\"string\" default=\"&quot;&quot;\">\nSecret containing the PEM bundle.\n</ResponseField>\n\n<ResponseField name=\"trustedCA.configMapName\" type=\"string\" default=\"&quot;&quot;\">\nConfigMap containing the PEM bundle, as an alternative to `secretName`.\n</ResponseField>\n\n<ResponseField name=\"trustedCA.key\" type=\"string\" default=\"ca.crt\">\nKey holding the bundle in that Secret or ConfigMap. The pods read it at start, so restart them after rotating the bundle.\n</ResponseField>\n\n## app\n\nThe web app and API Deployment.\n\n<ResponseField name=\"app.replicaCount\" type=\"integer\" default=\"2\">\nNumber of app pods. Use at least 2 for availability.\n</ResponseField>\n\n<ResponseField name=\"app.extraVolumes\" type=\"array\" default=\"[]\">\nExtra volumes for the app pods, for example a client certificate Secret for a file source. Reference existing Secrets; never embed key data. Do not reuse the reserved `config` and `trusted-ca` names.\n</ResponseField>\n\n<ResponseField name=\"app.extraVolumeMounts\" type=\"array\" default=\"[]\">\nMounts for those volumes in the app container. Avoid `/etc/eigenpal/eigenpal.config.yaml` and `/etc/eigenpal/trusted-ca`.\n</ResponseField>\n\n<ResponseField name=\"app.pdb\" type=\"object\">\nA PodDisruptionBudget so a node drain cannot remove all app pods at once.\n</ResponseField>\n\n<ResponseField name=\"app.pdb.enabled\" type=\"boolean\" default=\"false\">\nCreate the PodDisruptionBudget.\n</ResponseField>\n\n<ResponseField name=\"app.pdb.minAvailable\" type=\"integer | string\" default=\"1\">\nPods that must stay available, as a number or a percentage such as `50%`.\n</ResponseField>\n\n<ResponseField name=\"app.resources\" type=\"object\">\nCPU and memory requests and limits for each app pod.\n\nDefault:\n\n```yaml\nrequests:\n cpu: 250m\n memory: 1Gi\nlimits:\n cpu: \"1\"\n memory: 2Gi\n```\n</ResponseField>\n\n<ResponseField name=\"app.podAnnotations\" type=\"object\" default=\"{}\">\nAnnotations on the app pods, for example for a service mesh or log collector.\n</ResponseField>\n\n<ResponseField name=\"app.nodeSelector\" type=\"object\" default=\"{}\">\nNode selector for the app pods.\n</ResponseField>\n\n<ResponseField name=\"app.tolerations\" type=\"array\" default=\"[]\">\nTolerations for the app pods.\n</ResponseField>\n\n<ResponseField name=\"app.affinity\" type=\"object\" default=\"{}\">\nAffinity rules for the app pods.\n</ResponseField>\n\n<ResponseField name=\"app.extraEnv\" type=\"array\" default=\"[]\">\nExtra environment variables for the app container, as a container `env` list. Use it for settings without a chart value, for example `SERVER_BASE_URL`, SSO or sandbox settings; see [Environment variables](/self-hosting/environment-variables). A name the chart already sets fails the render.\n</ResponseField>\n\n<ResponseField name=\"app.extraEnv[].name\" type=\"string\">\nVariable name.\n</ResponseField>\n\n<ResponseField name=\"app.extraEnv[].value\" type=\"string\">\nLiteral value. Use `valueFrom` for credentials.\n</ResponseField>\n\n<ResponseField name=\"app.extraEnv[].valueFrom\" type=\"object\">\nKubernetes value source, for example `{secretKeyRef: {name: eigenpal-sso, key: client-secret}}`.\n</ResponseField>\n\n## worker\n\nThe worker Deployment, which executes workflow and agent runs.\n\n<ResponseField name=\"worker.replicaCount\" type=\"integer\" default=\"2\">\nNumber of worker pods. Total run capacity is this times `worker.concurrency.pool`.\n</ResponseField>\n\n<ResponseField name=\"worker.extraVolumes\" type=\"array\" default=\"[]\">\nExtra volumes for the worker pods, for example a client certificate Secret for a file source. Reference existing Secrets; never embed key data. Do not reuse the reserved `config` and `trusted-ca` names.\n</ResponseField>\n\n<ResponseField name=\"worker.extraVolumeMounts\" type=\"array\" default=\"[]\">\nMounts for those volumes in the worker container. Avoid `/etc/eigenpal/eigenpal.config.yaml` and `/etc/eigenpal/trusted-ca`.\n</ResponseField>\n\n<ResponseField name=\"worker.pdb\" type=\"object\">\nA PodDisruptionBudget so a node drain cannot remove all worker pods at once.\n</ResponseField>\n\n<ResponseField name=\"worker.pdb.enabled\" type=\"boolean\" default=\"false\">\nCreate the PodDisruptionBudget.\n</ResponseField>\n\n<ResponseField name=\"worker.pdb.minAvailable\" type=\"integer | string\" default=\"1\">\nPods that must stay available, as a number or a percentage such as `50%`.\n</ResponseField>\n\n<ResponseField name=\"worker.concurrency\" type=\"object\">\nHow many runs workers execute at once. Empty values use the built-in defaults; see the `WORKER_*` entries in [Environment variables](/self-hosting/environment-variables#worker-execution).\n</ResponseField>\n\n<ResponseField name=\"worker.concurrency.pool\" type=\"integer | string\" default=\"4\">\nRuns one worker pod executes at the same time (`WORKER_POOL_CONCURRENCY`).\n</ResponseField>\n\n<ResponseField name=\"worker.concurrency.maxBatch\" type=\"integer | string\" default=\"&quot;&quot;\">\nHighest concurrency a user may request for a single batch (`WORKER_MAX_BATCH_CONCURRENCY`, default 2).\n</ResponseField>\n\n<ResponseField name=\"worker.concurrency.maxTenant\" type=\"integer | string\" default=\"&quot;&quot;\">\nMost runs of all kinds executing at once across all workers (`WORKER_MAX_TENANT_CONCURRENCY`, default 3).\n</ResponseField>\n\n<ResponseField name=\"worker.concurrency.maxTenantAgent\" type=\"integer | string\" default=\"&quot;&quot;\">\nMost agent runs executing at once (`WORKER_MAX_TENANT_AGENT_CONCURRENCY`, default 2).\n</ResponseField>\n\n<ResponseField name=\"worker.concurrency.maxTenantWorkflow\" type=\"integer | string\" default=\"&quot;&quot;\">\nMost workflow runs executing at once (`WORKER_MAX_TENANT_WORKFLOW_CONCURRENCY`, default 2).\n</ResponseField>\n\n<ResponseField name=\"worker.resources\" type=\"object\">\nCPU and memory requests and limits for each worker pod. Raise memory with `worker.concurrency.pool` and the document sizes you process.\n\nDefault:\n\n```yaml\nrequests:\n cpu: 500m\n memory: 512Mi\nlimits:\n cpu: \"2\"\n memory: 2Gi\n```\n</ResponseField>\n\n<ResponseField name=\"worker.podAnnotations\" type=\"object\" default=\"{}\">\nAnnotations on the worker pods, for example for a service mesh or log collector.\n</ResponseField>\n\n<ResponseField name=\"worker.nodeSelector\" type=\"object\" default=\"{}\">\nNode selector for the worker pods.\n</ResponseField>\n\n<ResponseField name=\"worker.tolerations\" type=\"array\" default=\"[]\">\nTolerations for the worker pods.\n</ResponseField>\n\n<ResponseField name=\"worker.affinity\" type=\"object\" default=\"{}\">\nAffinity rules for the worker pods.\n</ResponseField>\n\n<ResponseField name=\"worker.extraEnv\" type=\"array\" default=\"[]\">\nExtra environment variables for the worker container, as a container `env` list. Use it for settings without a chart value, for example `SERVER_BASE_URL`, SSO or sandbox settings; see [Environment variables](/self-hosting/environment-variables). A name the chart already sets fails the render.\n</ResponseField>\n\n<ResponseField name=\"worker.extraEnv[].name\" type=\"string\">\nVariable name.\n</ResponseField>\n\n<ResponseField name=\"worker.extraEnv[].value\" type=\"string\">\nLiteral value. Use `valueFrom` for credentials.\n</ResponseField>\n\n<ResponseField name=\"worker.extraEnv[].valueFrom\" type=\"object\">\nKubernetes value source, for example `{secretKeyRef: {name: eigenpal-sso, key: client-secret}}`.\n</ResponseField>\n\n## promotion\n\nGit-based release of workflows between environments. Each environment is its own installation of this chart; workflows are edited in the first and move up one environment at a time through pull requests in Git repositories you own. Every installation gets the same `repositories` and `environments`, and only `environment` differs. See [Workflow promotion](/self-hosting/workflow-promotion).\n\n<ResponseField name=\"promotion.enabled\" type=\"boolean\" default=\"false\">\nTurn on workflow promotion for this installation. Requires `tenant.mode: single-tenant`, at least two `environments`, a `repositories` entry for each and an `artifactStore`.\n</ResponseField>\n\n<ResponseField name=\"promotion.environment\" type=\"string\" default=\"&quot;&quot;\">\nThis installation's environment: one of the names in `environments`. The only promotion value that differs between installations.\n</ResponseField>\n\n<ResponseField name=\"promotion.provider\" type=\"github | gitlab\" default=\"github\">\nDefault Git host of `repositories`: `github` (github.com or GitHub Enterprise Server) or `gitlab` (gitlab.com or self-managed).\n</ResponseField>\n\n<ResponseField name=\"promotion.apiUrl\" type=\"string\" default=\"&quot;&quot;\">\nGit host API URL. Empty for github.com or gitlab.com; otherwise `https://<host>/api/v3` for GitHub Enterprise Server or `https://<host>/api/v4` for self-managed GitLab.\n</ResponseField>\n\n<ResponseField name=\"promotion.repositories\" type=\"object\" default=\"{}\">\nThe Git repositories of the release path, by short name (lowercase letters, digits and hyphens), for example `workflows: {project: group/eigenpal-workflows, branch: main}`. Each environment is kept in one of them. Tokens come from `secrets.promotionTokens.<name>`.\n</ResponseField>\n\n<ResponseField name=\"promotion.repositories.<name>.provider\" type=\"github | gitlab\">\nOverrides `promotion.provider` for this repository.\n</ResponseField>\n\n<ResponseField name=\"promotion.repositories.<name>.apiUrl\" type=\"string\">\nOverrides `promotion.apiUrl` for this repository.\n</ResponseField>\n\n<ResponseField name=\"promotion.repositories.<name>.project\" type=\"string\">\nRequired. `owner/name` on GitHub, or the full project path on GitLab.\n</ResponseField>\n\n<ResponseField name=\"promotion.repositories.<name>.branch\" type=\"string\">\nBranch that holds the released workflows. Empty uses `main`.\n</ResponseField>\n\n<ResponseField name=\"promotion.repositories.<name>.app\" type=\"object\">\nGitHub only. Authenticate as a GitHub App instead of with a token; its private key goes in `secrets.promotionTokens.<name>`.\n</ResponseField>\n\n<ResponseField name=\"promotion.repositories.<name>.app.id\" type=\"string | integer\">\nThe GitHub App ID. EigenPal then writes as `<app>[bot]`.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments\" type=\"array\" default=\"configure for your installation\">\nThe release path in order, at least two entries, identical in every installation. Workflows are edited in the first.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments[].name\" type=\"string\">\nLowercase name used in Git paths and branch names, for example `dev`.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments[].label\" type=\"string\">\nName people see. Empty uses `name` in upper case.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments[].url\" type=\"string\">\nPublic URL of that installation, used for links and webhooks.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments[].repository\" type=\"string\">\nRequired. The repository this environment is kept in, one of `promotion.repositories`.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments[].bot\" type=\"string\">\nRequired. The Git user this environment writes as in its repository: the GitHub login, or the GitLab user of its token. Every environment needs its own.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments[].acceptsFrom\" type=\"string\">\nThe Git user the previous environment writes as in this repository. Needed when the previous environment is kept in a different repository.\n</ResponseField>\n\n<ResponseField name=\"promotion.environments[].releasedWith\" type=\"string\">\nName of the environment right before this one, when both are released by the same pull request. Both must be kept in the same repository.\n</ResponseField>\n\n<ResponseField name=\"promotion.artifactStore\" type=\"object\" default=\"{}\">\nWhere dataset files travel between environments. Required when promotion is enabled; set exactly one of `git: true` (recommended: Git LFS in the promotion repository), `s3: {bucket, region, endpoint, accessKeyId, secretAccessKey}` (a bucket every installation reaches; credentials as `${VAR}`), or `path` with `existingClaim` (a ReadWriteMany volume every installation mounts).\n</ResponseField>\n\n<ResponseField name=\"promotion.pullSchedule\" type=\"string\" default=\"*/15 * * * *\">\nCron schedule on which later environments check Git for approved versions. Rendered as a CronJob in every environment but the first; needs `secrets.cronSecret`.\n</ResponseField>\n\n<ResponseField name=\"promotion.notifications\" type=\"object\">\nGitHub or GitLab webhook notifications that advance promotions without waiting for the scheduled pull.\n</ResponseField>\n\n<ResponseField name=\"promotion.notifications.enabled\" type=\"boolean\" default=\"false\">\nAccept notifications at `/api/webhooks/promotion`. Requires `secrets.promotionWebhookSecret`. The scheduled pull stays on as a fallback.\n</ResponseField>\n\n## maintenance\n\nA CronJob that calls the app housekeeping endpoint: it fails runs stuck for more than 20 minutes, removes abandoned uploads and applies data retention. Without it (or an external scheduler calling the same endpoint), retention never runs.\n\n<ResponseField name=\"maintenance.enabled\" type=\"boolean\" default=\"true\">\nRun the housekeeping CronJob. Requires `secrets.cronSecret`; the chart refuses to render without it. Disable only when an external scheduler calls `/api/cron/reap-stale-executions` with the same token.\n</ResponseField>\n\n<ResponseField name=\"maintenance.schedule\" type=\"string\" default=\"*/15 * * * *\">\nCron schedule of the housekeeping job.\n</ResponseField>\n\n<ResponseField name=\"maintenance.image\" type=\"string\" default=\"busybox:1.36\">\nSmall utility image for the wait-for-database init containers, for example a mirrored busybox. Must provide `sh` and `nc`.\n</ResponseField>\n\n<ResponseField name=\"maintenance.cronImage\" type=\"string\" default=\"&quot;&quot;\">\nImage for the housekeeping and promotion CronJobs. Empty uses the worker image, which has the Bun runtime the default command needs.\n</ResponseField>\n\n<ResponseField name=\"maintenance.command\" type=\"array\" default=\"[]\">\nCustom command for the housekeeping job only, as a list. Empty uses the built-in authenticated HTTP call.\n</ResponseField>\n\n<ResponseField name=\"maintenance.resources\" type=\"object\">\nCPU and memory requests and limits for the housekeeping and promotion CronJobs.\n\nDefault:\n\n```yaml\nrequests:\n cpu: 10m\n memory: 32Mi\nlimits:\n cpu: 100m\n memory: 128Mi\n```\n</ResponseField>\n\n<ResponseField name=\"maintenance.nodeSelector\" type=\"object\" default=\"{}\">\nNode selector for the CronJob pods.\n</ResponseField>\n\n<ResponseField name=\"maintenance.tolerations\" type=\"array\" default=\"[]\">\nTolerations for the CronJob pods.\n</ResponseField>\n\n<ResponseField name=\"maintenance.affinity\" type=\"object\" default=\"{}\">\nAffinity rules for the CronJob pods.\n</ResponseField>\n\n## preflight\n\nA read-only check Job that runs before the migration on install and every upgrade (Helm hook, Argo CD PreSync). It verifies Secrets, mounted files, certificates, the database, object storage and the model gateway, and stops the sync with a readable FAIL before anything changes. It prints no secret values.\n\n<ResponseField name=\"preflight.enabled\" type=\"boolean\" default=\"true\">\nRun the preflight Job. Set `false` only to unblock a sync while a reported problem is being fixed.\n</ResponseField>\n\n<ResponseField name=\"preflight.strict\" type=\"boolean\" default=\"false\">\n`true` turns reachability warnings (OCR, SSO, file sources, Git hosts, model gateway) into failures. Use it for a first install or a standalone run before a change window.\n</ResponseField>\n\n<ResponseField name=\"preflight.expectedClientCN\" type=\"string\" default=\"&quot;&quot;\">\nSubject CN the client certificate (`SSO_CLIENT_CERT_FILE`, `FILE_SOURCE_CLIENT_CERT_FILE`) must carry, for example `eigenpal-prod`. A different CN fails the check, which catches a certificate from another environment. Empty skips this comparison.\n</ResponseField>\n\n<ResponseField name=\"preflight.ttlSecondsAfterFinished\" type=\"integer\" default=\"86400\">\nSeconds the finished Job and its log are kept before Kubernetes removes them.\n</ResponseField>\n\n<ResponseField name=\"preflight.podLabels\" type=\"object\" default=\"{}\">\nExtra labels on the preflight pod, for example the ones your egress NetworkPolicies select, so it can reach the same services as the app and worker.\n</ResponseField>\n\n<ResponseField name=\"preflight.extraEnv\" type=\"array\" default=\"[]\">\nExtra environment variables for the preflight Job only, as a container `env` list. The app and worker `extraEnv` are already included.\n</ResponseField>\n\n<ResponseField name=\"preflight.extraEnv[].name\" type=\"string\">\nVariable name.\n</ResponseField>\n\n<ResponseField name=\"preflight.extraEnv[].value\" type=\"string\">\nLiteral value. Use `valueFrom` for credentials.\n</ResponseField>\n\n<ResponseField name=\"preflight.extraEnv[].valueFrom\" type=\"object\">\nKubernetes value source, for example `{secretKeyRef: {name: eigenpal-sso, key: client-secret}}`.\n</ResponseField>\n\n<ResponseField name=\"preflight.resources\" type=\"object\">\nCPU and memory requests and limits for the preflight Job.\n\nDefault:\n\n```yaml\nrequests:\n cpu: 100m\n memory: 256Mi\nlimits:\n cpu: \"1\"\n memory: 512Mi\n```\n</ResponseField>\n\n## migrate\n\nThe database and storage migration Job, run with the worker image on install and every upgrade: object storage migrations, then the database schema. Disable only if you run migrations another way.\n\n<ResponseField name=\"migrate.enabled\" type=\"boolean\" default=\"true\">\nRun the migration Job. Disable only if you apply migrations another way before upgrading the app and worker.\n</ResponseField>\n\n<ResponseField name=\"migrate.hook\" type=\"boolean\" default=\"true\">\n`true` runs migrations as a Helm pre-install and pre-upgrade hook (Argo CD PreSync), so they finish before new pods start; correct for an external database and bucket. Set `false` with `postgres.enabled` or `secrets.create`, which create resources that do not exist yet during hooks; it then runs as an ordinary Job.\n</ResponseField>\n\n<ResponseField name=\"migrate.blob\" type=\"boolean\" default=\"true\">\nRun object storage migrations first. They need the bucket to exist. Set `false` with `minio.enabled` until the bucket is initialized.\n</ResponseField>\n\n<ResponseField name=\"migrate.scripts\" type=\"boolean\" default=\"false\">\nRun data migrations for existing data. Off for fresh installations, which have nothing to migrate; enable only when importing or upgrading existing data, and supply any variables they need through `extraEnv`.\n</ResponseField>\n\n<ResponseField name=\"migrate.extraEnv\" type=\"array\" default=\"[]\">\nExtra environment variables for the migration Job, as a container `env` list.\n</ResponseField>\n\n<ResponseField name=\"migrate.extraEnv[].name\" type=\"string\">\nVariable name.\n</ResponseField>\n\n<ResponseField name=\"migrate.extraEnv[].value\" type=\"string\">\nLiteral value. Use `valueFrom` for credentials.\n</ResponseField>\n\n<ResponseField name=\"migrate.extraEnv[].valueFrom\" type=\"object\">\nKubernetes value source, for example `{secretKeyRef: {name: eigenpal-sso, key: client-secret}}`.\n</ResponseField>\n\n<ResponseField name=\"migrate.resources\" type=\"object\">\nCPU and memory requests and limits for the migration Job.\n\nDefault:\n\n```yaml\nrequests:\n cpu: 100m\n memory: 256Mi\nlimits:\n cpu: \"1\"\n memory: 512Mi\n```\n</ResponseField>\n\n## service\n\nThe Kubernetes Service in front of the app.\n\n<ResponseField name=\"service.port\" type=\"integer\" default=\"3000\">\nPort of the app Service. The container always listens on 3000.\n</ResponseField>\n\n## ingress\n\nA Kubernetes Ingress for the app, the default on plain Kubernetes, EKS, AKS and GKE. On OpenShift use `openshift.route` instead.\n\n<ResponseField name=\"ingress.enabled\" type=\"boolean\" default=\"true\">\nCreate the Ingress. Cannot be combined with `openshift.route.enabled`.\n</ResponseField>\n\n<ResponseField name=\"ingress.className\" type=\"string\" default=\"nginx\">\nIngressClass to use, for example `nginx`. Empty uses the cluster default.\n</ResponseField>\n\n<ResponseField name=\"ingress.host\" type=\"string\" default=\"installation-specific\">\nHost name users reach EigenPal on, for example `eigenpal.example.com`. Required when the Ingress is enabled.\n</ResponseField>\n\n<ResponseField name=\"ingress.annotations\" type=\"object\">\nAnnotations on the Ingress. The defaults raise NGINX timeouts to 30 minutes and the request body limit to 500 MB, so large uploads and dataset imports are not cut off. Translate them for other ingress controllers.\n\nDefault:\n\n```yaml\nnginx.ingress.kubernetes.io/proxy-read-timeout: \"1800\"\nnginx.ingress.kubernetes.io/proxy-send-timeout: \"1800\"\nnginx.ingress.kubernetes.io/proxy-body-size: 500m\n```\n</ResponseField>\n\n<ResponseField name=\"ingress.tls\" type=\"array\" default=\"[]\">\nTLS settings as Kubernetes `tls` entries, for example `[{secretName: eigenpal-tls, hosts: [eigenpal.example.com]}]`. Empty serves HTTP and expects TLS to end at a load balancer.\n</ResponseField>\n\n## openshift\n\nOpenShift-specific resources.\n\n<ResponseField name=\"openshift.route\" type=\"object\">\nAn OpenShift Route with edge TLS, used instead of an Ingress. HTTP redirects to HTTPS, and the router timeout is raised to 30 minutes for large uploads.\n</ResponseField>\n\n<ResponseField name=\"openshift.route.enabled\" type=\"boolean\" default=\"false\">\nCreate the Route. Set `ingress.enabled: false` with it.\n</ResponseField>\n\n<ResponseField name=\"openshift.route.host\" type=\"string\" default=\"installation-specific\">\nHost name of the Route. Empty lets OpenShift generate one.\n</ResponseField>\n\n<ResponseField name=\"openshift.route.externalCertificate\" type=\"object\">\nUse a TLS certificate from an existing Secret (OpenShift 4.19 or later).\n</ResponseField>\n\n<ResponseField name=\"openshift.route.externalCertificate.name\" type=\"string\" default=\"&quot;&quot;\">\nName of a `kubernetes.io/tls` Secret in the Route namespace; the router needs read access to it. Empty uses the router default certificate.\n</ResponseField>\n\n## networkPolicy\n\nNetworkPolicies that let only EigenPal pods reach the in-cluster PostgreSQL and MinIO.\n\n<ResponseField name=\"networkPolicy.enabled\" type=\"boolean\" default=\"false\">\nCreate the policies. Has an effect only with `postgres.enabled` or `minio.enabled`.\n</ResponseField>\n\n## postgres\n\nAn in-cluster PostgreSQL for evaluation only. Production uses an external, managed database through `secrets.databaseUrl`.\n\n<ResponseField name=\"postgres.enabled\" type=\"boolean\" default=\"false\">\nRun PostgreSQL in the cluster. Requires `secrets.create: true` and `migrate.hook: false`.\n</ResponseField>\n\n<ResponseField name=\"postgres.image\" type=\"string\" default=\"postgres:16-alpine\">\nPostgreSQL image.\n</ResponseField>\n\n<ResponseField name=\"postgres.storage\" type=\"string\" default=\"10Gi\">\nSize of the PostgreSQL volume.\n</ResponseField>\n\n<ResponseField name=\"postgres.resources\" type=\"object\">\nCPU and memory requests and limits for PostgreSQL.\n\nDefault:\n\n```yaml\nrequests:\n cpu: 250m\n memory: 256Mi\nlimits:\n cpu: \"1\"\n memory: 1Gi\n```\n</ResponseField>\n\n## minio\n\nAn in-cluster MinIO for evaluation only. Production uses an external S3-compatible service through `objectStorage`.\n\n<ResponseField name=\"minio.enabled\" type=\"boolean\" default=\"false\">\nRun MinIO in the cluster. Requires `migrate.blob: false` until the bucket exists.\n</ResponseField>\n\n<ResponseField name=\"minio.image\" type=\"string\" default=\"&quot;&quot;\">\nMinIO server image, pinned by version tag or `sha256` digest. Required when enabled; `latest` is refused.\n</ResponseField>\n\n<ResponseField name=\"minio.mcImage\" type=\"string\" default=\"&quot;&quot;\">\nMinIO client image that creates the bucket, pinned like `image`. Required when enabled.\n</ResponseField>\n\n<ResponseField name=\"minio.storage\" type=\"string\" default=\"20Gi\">\nSize of the MinIO volume.\n</ResponseField>\n\n<ResponseField name=\"minio.resources\" type=\"object\">\nCPU and memory requests and limits for MinIO.\n\nDefault:\n\n```yaml\nrequests:\n cpu: 250m\n memory: 256Mi\nlimits:\n cpu: \"1\"\n memory: 1Gi\n```\n</ResponseField>\n"
2257
2278
  },
2258
2279
  {
2259
2280
  "topic": "self-hosting/kubernetes",
@@ -2337,7 +2358,7 @@
2337
2358
  "title": "Extract Data",
2338
2359
  "description": "Extract structured data from text using AI with a JSON schema",
2339
2360
  "source": "public",
2340
- "content": "---\ntitle: \"Extract Data\"\ndescription: \"Extract structured data from text using AI with a JSON schema\"\n---\n\n`ai.extract`, Extract structured data from text using AI with a JSON schema\n\nUse `ai.extract` after parsing or collecting text when you need typed JSON back:\ninvoice fields, contract clauses, email metadata, line items, or classifications\nwith supporting fields.\n\nKeep the schema as narrow as possible. Enum fields work well for closed choices,\nand descriptions should explain business meaning, not just repeat the field\nname. For deterministic calculations after extraction, pass the output into\n`transform.script` instead of asking the model to do math.\n\nThe worker validates the returned JSON against this schema after every provider\ncall. Missing `required` fields, wrong types, and nested constraint failures\nfail the step with a schema-validation error; they are never reclassified as\nordinary “not found” values.\n\nUse `provider` to select an Eigenpal catalog entry such as\n`anthropic/claude-sonnet-5-5`. The optional `model` field is only a raw\nprovider-specific override (for example a vendor model version) and must not\ncontain an Eigenpal catalog ID. Online validation reports this mix-up before\nthe workflow runs.\n\nGPT-6.1 Terra is available as `openai/gpt-6.1-terra` for text and image extraction.\nSelect it explicitly with `provider`; its reasoning effort accepts `none`, `low`,\n`medium` (the default), `high`, `xhigh`, and `max`. Workflow requests use the\nResponses API. Existing default model selections remain unchanged.\n\n```yaml\n- name: extract-invoice\n type: ai.extract\n with:\n input: '{{ steps.parse.output.text }}'\n provider: openai/gpt-6.1-terra\n schema:\n type: object\n properties:\n invoice_id: { type: string }\n total: { type: number }\n required: [invoice_id, total]\n```\n\nPublished provider rates are $1 per million input tokens and $5 per million\noutput tokens, with $0.05 cache reads and $1.25 standard cache writes. Requests\nover 272,000 input tokens cost twice the input/cache rates and 1.5 times the\noutput rate for the entire request. Agent sandbox sessions use a conservative\n272,000-token context limit; workflows retain the model's larger context window.\n\n## Grounding and confidence (on by default)\n\nGrounding is on unless you set `grounded: false`. Step output stays\nschema-shaped; provenance lives under a reserved `_grounding` map keyed by\n**dotted field path** (array indexes are decimal segments), so nested values\nand their grounding line up:\n\n```yaml\n# {{ steps.extract-invoice.output.vendor }} -> \"Acme Corp\"\n# {{ steps.extract-invoice.output._grounding.vendor.confidence }} -> \"high\"\n# {{ steps.extract-invoice.output._grounding.vendor.needsReview }} -> false\n# {{ steps.extract-invoice.output._grounding['line_items.0.amount'].score }} -> 0.92\n```\n\nEach entry carries categorical `confidence` (`high`, `medium`, `low`),\n`needsReview`, optional numeric `score`, `reason`, `quote`, `source_span`, and\n— when spatial evidence exists — `citations` with page/element references.\nLineage and the full parsed document graph are **never** mixed into step JSON;\nthey are stored as optional run sidecars for review and audit surfaces.\n\n### Shared grounded extraction (parse → extract)\n\nWhen `input` resolves to an object that includes a valid OpenParser\n`ParsedDocument` in `structured` (for example the whole\n`{{ steps.parse.output }}` from a layout-aware parse) **and** your configured\nprovider supports a single strict structured extraction call, Eigenpal runs the\nsame grounded extraction algorithm as OpenParser locally — no call to the hosted\nOpenParser extract service. On-prem deployments use the same library in the\nworker.\n\nWire the parse output object, not just `.text`, to unlock spatial citations and\nsidecars:\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: ocr\n ocrModel: openparser-default\n\n- name: extract-invoice\n type: ai.extract\n with:\n input: '{{ steps.parse.output }}'\n schema:\n type: object\n properties:\n vendor:\n type: string\n total:\n type: number\n required: [vendor, total]\n```\n\nPassing only `{{ steps.parse.output.text }}` still works; extraction and\ngrounding fall back to the text path described below.\n\n### Text grounding fallback\n\nWhen there is no valid `ParsedDocument`, or the provider cannot run one strict\nstructured call, Eigenpal uses the legacy text grounding pass over the resolved\ntext. That path may set `_grounding._degraded: true` with a truthful `_reason`\n(for example unsupported provider, missing grounding model, or credit quota too\nlow for the second pass). It does **not** emit lineage sidecars.\n\n- `high` means the value appears verbatim in the source text, `medium` means it\n matches approximately or is derived from a highlighted passage the model\n attested, and `low` means no supporting source could be located.\n- Fields at or below the `reviewOn` threshold carry `needsReview: true`. Default\n is `low_only`; use `medium_or_low` to also flag approximate matches.\n- `source_span` holds character offsets into the resolved text; the run view\n highlights them in the Grounding panel. Long documents are chunked\n automatically on the text path.\n\nThe text pass uses your workspace default model unless `groundingModel` picks a\ndifferent one. Set `grounded: true` to fail the step when grounding cannot run\ninstead of degrading; `grounded: false` removes `_grounding` entirely.\n\nNote that grounding confidence measures whether the value is supported in the\nsource the step saw, not whether OCR read the original document correctly. For\nnumeric cross-checks (for example rate times hours equals gross), add a\n`transform.script` step.\n\n### Current limitations\n\n- Spatial citations and lineage sidecars require **one** canonical\n `ParsedDocument` on the extract input. Multiple merged documents are not\n supported for bbox identity yet.\n- Legacy text grounding never writes lineage sidecars — only `_grounding` in\n step output.\n- Human review decisions are not yet appended back into lineage.\n\n## Configuration\n\nConfiguration goes inside the step's `with:` block.\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"input\" type=\"string\" required>\nText content or template expression\n</ParamField>\n<ParamField path=\"schema\" type=\"object\" required>\nJSON Schema defining the structure to extract. Fields not listed in `required` come back null when the document does not contain them; a missing required field fails the step.\n<Expandable title=\"schema properties\">\n<ParamField path=\"type\" type=\"string\" required>\n</ParamField>\n<ParamField path=\"properties\" type=\"record<string, unknown>\" required>\n</ParamField>\n<ParamField path=\"required\" type=\"array<string>\">\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"prompt\" type=\"string\">\nCustom prompt template for extraction\n</ParamField>\n<ParamField path=\"provider\" type=\"string\">\nProvider ID (e.g., \"openai/gpt-6-luna\")\n</ParamField>\n<ParamField path=\"model\" type=\"string\">\nModel override\n</ParamField>\n<ParamField path=\"reasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"maxInputTokens\" type=\"integer\">\nMax input tokens. Truncates input text and logs a warning when exceeded. Omit for no limit.\n</ParamField>\n<ParamField path=\"grounded\" type=\"boolean\">\nGrounding is ON by default: each schema field gets a source span + confidence (high=verbatim, medium=fuzzy, low=ungrounded) under a reserved `_grounding` output key, and fields whose value cannot be located in the source are flagged for human review. Values stay the reliable schema-typed ones. The pass runs through the workspace LLM (any provider) and chunks long documents automatically. Tri-state: unset (default) = on, degrading gracefully to deterministic text alignment (`_grounding._degraded: true`) if no grounding model is available; `true` = strict, the step fails when the grounding model cannot be resolved; `false` = off, no `_grounding` key at all.\n</ParamField>\n<ParamField path=\"groundingModel\" type=\"string\">\nProvider/model for the grounding pass. Defaults to the workspace default LLM. Any configured provider works; the pass only fails the step when `grounded: true` is set explicitly and no model resolves.\n</ParamField>\n<ParamField path=\"groundingReasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"groundingExamples\" type=\"array<object>\">\nOptional few-shot examples pinning grounding to verbatim source text per field.\n<Expandable title=\"groundingExamples properties\">\n<ParamField path=\"text\" type=\"string\" required>\n</ParamField>\n<ParamField path=\"extractions\" type=\"array<object>\" required>\n<Expandable title=\"extractions properties\">\n<ParamField path=\"field\" type=\"string\" required>\n</ParamField>\n<ParamField path=\"text\" type=\"string\" required>\n</ParamField>\n</Expandable>\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"reviewOn\" type=\"&quot;medium_or_low&quot; | &quot;low_only&quot;\">\nWhich grounding confidences set needsReview on a field. Default: low_only (only fields whose value could not be located in the source). Use medium_or_low to also flag approximate and derived matches.\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output\n\n{/* GENERATED:OUTPUT START */}\nReturns `record<string, unknown>`. Extracted structured data matching the provided schema. Unless grounding is disabled (grounded: false), the output also carries a reserved `_grounding` map keyed by dotted field path: `_grounding[\"line_items.0.amount\"] = &#123; confidence: high|medium|low, score?, needsReview, reason?, quote?, citations?, source_span }`, plus reserved `_degraded: true` / `_reason` markers when grounding could not run the shared algorithm or the EigenPal text pass. Lineage is never included in this JSON.\n{/* GENERATED:OUTPUT END */}\n"
2361
+ "content": "---\ntitle: \"Extract Data\"\ndescription: \"Extract structured data from text using AI with a JSON schema\"\n---\n\n`ai.extract`, Extract structured data from text using AI with a JSON schema\n\nUse `ai.extract` after parsing or collecting text when you need typed JSON back:\ninvoice fields, contract clauses, email metadata, line items, or classifications\nwith supporting fields.\n\nKeep the schema as narrow as possible. Enum fields work well for closed choices,\nand descriptions should explain business meaning, not just repeat the field\nname. For deterministic calculations after extraction, pass the output into\n`transform.script` instead of asking the model to do math.\n\nThe worker validates the returned JSON against this schema after every provider\ncall. Missing `required` fields, wrong types, and nested constraint failures\nfail the step with a schema-validation error; they are never reclassified as\nordinary “not found” values.\n\nUse `provider` to select an Eigenpal catalog entry such as\n`anthropic/claude-sonnet-5-5`. The optional `model` field is only a raw\nprovider-specific override (for example a vendor model version) and must not\ncontain an Eigenpal catalog ID. Online validation reports this mix-up before\nthe workflow runs.\n\nGPT-6.1 Terra is available as `openai/gpt-6.1-terra` for text and image extraction.\nSelect it explicitly with `provider`; its reasoning effort accepts `none`, `low`,\n`medium` (the default), `high`, `xhigh`, and `max`. Workflow requests use the\nResponses API. Existing default model selections remain unchanged.\n\n```yaml\n- name: extract-invoice\n type: ai.extract\n with:\n input: '{{ steps.parse.output.text }}'\n provider: openai/gpt-6.1-terra\n schema:\n type: object\n properties:\n invoice_id: { type: string }\n total: { type: number }\n required: [invoice_id, total]\n```\n\nPublished provider rates are $1 per million input tokens and $5 per million\noutput tokens, with $0.05 cache reads and $1.25 standard cache writes. Requests\nover 272,000 input tokens cost twice the input/cache rates and 1.5 times the\noutput rate for the entire request. Agent sandbox sessions use a conservative\n272,000-token context limit; workflows retain the model's larger context window.\n\n## Grounding and confidence (on by default)\n\nGrounding is on unless you set `grounded: false`. Step output stays\nschema-shaped; provenance lives under a reserved `_grounding` map keyed by\n**dotted field path** (array indexes are decimal segments), so nested values\nand their grounding line up:\n\n```yaml\n# {{ steps.extract-invoice.output.vendor }} -> \"Acme Corp\"\n# {{ steps.extract-invoice.output._grounding.vendor.confidence }} -> \"high\"\n# {{ steps.extract-invoice.output._grounding.vendor.needsReview }} -> false\n# {{ steps.extract-invoice.output._grounding['line_items.0.amount'].score }} -> 0.92\n```\n\nEach entry carries categorical `confidence` (`high`, `medium`, `low`),\n`needsReview`, optional numeric `score`, `reason`, `quote`, `source_span`, and\n— when spatial evidence exists — `citations` with page/element references.\nLineage and the full parsed document graph are **never** mixed into step JSON;\nthey are stored as optional run sidecars for review and audit surfaces.\n\n### OCR word confidence\n\nWhen the extract input is a `ParsedDocument` whose OCR provider reports\nper-word confidence (for example Mistral OCR), each field also carries\n`recognitionScore`: how well OCR read the words the value was taken from. It\nis the weakest cited word, pulled down slightly when the surrounding words in\nthe same region also scanned poorly. It never raises a field, only caps it:\n\n- `score` is at most `recognitionScore`.\n- Below `0.8` the field is `low`; below `0.9` it is at most `medium`. A\n handwritten name read at `0.53` is found verbatim in the OCR text, but it\n becomes `low`, carries `needsReview: true` and a reason, and human review\n with `metadataFrom: ai.extract` selects it.\n- Other fields in the same paragraph keep their own band when their own words\n scanned cleanly.\n\nFields read from native PDF text, or from OCR providers without per-word\nconfidence, have no `recognitionScore` and keep the alignment-only result.\n\n### Shared grounded extraction (parse → extract)\n\nWhen `input` resolves to an object that includes a valid OpenParser\n`ParsedDocument` in `structured` (for example the whole\n`{{ steps.parse.output }}` from a layout-aware parse) **and** your configured\nprovider supports a single strict structured extraction call, Eigenpal runs the\nsame grounded extraction algorithm as OpenParser locally — no call to the hosted\nOpenParser extract service. On-prem deployments use the same library in the\nworker.\n\nWire the parse output object, not just `.text`, to unlock spatial citations and\nsidecars:\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: ocr\n ocrModel: openparser-default\n\n- name: extract-invoice\n type: ai.extract\n with:\n input: '{{ steps.parse.output }}'\n schema:\n type: object\n properties:\n vendor:\n type: string\n total:\n type: number\n required: [vendor, total]\n```\n\nPassing only `{{ steps.parse.output.text }}` still works; extraction and\ngrounding fall back to the text path described below.\n\n### Text grounding fallback\n\nWhen there is no valid `ParsedDocument`, or the provider cannot run one strict\nstructured call, Eigenpal uses the legacy text grounding pass over the resolved\ntext. That path may set `_grounding._degraded: true` with a truthful `_reason`\n(for example unsupported provider, missing grounding model, or credit quota too\nlow for the second pass). It does **not** emit lineage sidecars.\n\n- `high` means the value appears verbatim in the source text, `medium` means it\n matches approximately or is derived from a highlighted passage the model\n attested, and `low` means no supporting source could be located.\n- Fields at or below the `reviewOn` threshold carry `needsReview: true`. Default\n is `low_only`; use `medium_or_low` to also flag approximate matches.\n- `source_span` holds character offsets into the resolved text; the run view\n highlights them in the Grounding panel. Long documents are chunked\n automatically on the text path.\n\nThe text pass uses your workspace default model unless `groundingModel` picks a\ndifferent one. Set `grounded: true` to fail the step when grounding cannot run\ninstead of degrading; `grounded: false` removes `_grounding` entirely.\n\nNote that text grounding confidence measures whether the value is supported in\nthe source the step saw, not whether OCR read the original document correctly;\nonly the shared path above folds in OCR word confidence. For\nnumeric cross-checks (for example rate times hours equals gross), add a\n`transform.script` step.\n\n### Current limitations\n\n- Spatial citations and lineage sidecars require **one** canonical\n `ParsedDocument` on the extract input. Multiple merged documents are not\n supported for bbox identity yet.\n- Legacy text grounding never writes lineage sidecars — only `_grounding` in\n step output.\n- Human review decisions are not yet appended back into lineage.\n\n## Configuration\n\nConfiguration goes inside the step's `with:` block.\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"input\" type=\"string\" required>\nText content or template expression\n</ParamField>\n<ParamField path=\"schema\" type=\"object\" required>\nJSON Schema defining the structure to extract. Fields not listed in `required` come back null when the document does not contain them; a missing required field fails the step.\n<Expandable title=\"schema properties\">\n<ParamField path=\"type\" type=\"string\" required>\n</ParamField>\n<ParamField path=\"properties\" type=\"record<string, unknown>\" required>\n</ParamField>\n<ParamField path=\"required\" type=\"array<string>\">\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"prompt\" type=\"string\">\nCustom prompt template for extraction\n</ParamField>\n<ParamField path=\"provider\" type=\"string\">\nProvider ID (e.g., \"openai/gpt-6-luna\")\n</ParamField>\n<ParamField path=\"model\" type=\"string\">\nModel override\n</ParamField>\n<ParamField path=\"reasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"maxInputTokens\" type=\"integer\">\nMax input tokens. Truncates input text and logs a warning when exceeded. Omit for no limit.\n</ParamField>\n<ParamField path=\"grounded\" type=\"boolean\">\nGrounding is ON by default: each schema field gets a source span + confidence (high=verbatim, medium=fuzzy, low=ungrounded) under a reserved `_grounding` output key, and fields whose value cannot be located in the source are flagged for human review. Values stay the reliable schema-typed ones. The pass runs through the workspace LLM (any provider) and chunks long documents automatically. Tri-state: unset (default) = on, degrading gracefully to deterministic text alignment (`_grounding._degraded: true`) if no grounding model is available; `true` = strict, the step fails when the grounding model cannot be resolved; `false` = off, no `_grounding` key at all.\n</ParamField>\n<ParamField path=\"groundingModel\" type=\"string\">\nProvider/model for the grounding pass. Defaults to the workspace default LLM. Any configured provider works; the pass only fails the step when `grounded: true` is set explicitly and no model resolves.\n</ParamField>\n<ParamField path=\"groundingReasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"groundingExamples\" type=\"array<object>\">\nOptional few-shot examples pinning grounding to verbatim source text per field.\n<Expandable title=\"groundingExamples properties\">\n<ParamField path=\"text\" type=\"string\" required>\n</ParamField>\n<ParamField path=\"extractions\" type=\"array<object>\" required>\n<Expandable title=\"extractions properties\">\n<ParamField path=\"field\" type=\"string\" required>\n</ParamField>\n<ParamField path=\"text\" type=\"string\" required>\n</ParamField>\n</Expandable>\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"reviewOn\" type=\"&quot;medium_or_low&quot; | &quot;low_only&quot;\">\nWhich grounding confidences set needsReview on a field. Default: low_only (only fields whose value could not be located in the source). Use medium_or_low to also flag approximate and derived matches.\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output\n\n{/* GENERATED:OUTPUT START */}\nReturns `record<string, unknown>`. Extracted structured data matching the provided schema. Unless grounding is disabled (grounded: false), the output also carries a reserved `_grounding` map keyed by dotted field path: `_grounding[\"line_items.0.amount\"] = &#123; confidence: high|medium|low, score?, recognitionScore?, needsReview, reason?, quote?, citations?, source_span }`. When the parsed document carries per-word OCR confidence, `recognitionScore` is the recognition of the cited words and caps the field: `score` never exceeds it, below 0.8 the field is low, below 0.9 at most medium. The map also holds reserved `_degraded: true` / `_reason` markers when grounding could not run the shared algorithm or the EigenPal text pass. Lineage is never included in this JSON.\n{/* GENERATED:OUTPUT END */}\n"
2341
2362
  },
2342
2363
  {
2343
2364
  "topic": "steps/ai/figure-crops",
@@ -2351,14 +2372,14 @@
2351
2372
  "title": "Parse Document v1",
2352
2373
  "description": "Extract text from documents (PDF, DOCX, images) using native extraction, OCR, or vision models",
2353
2374
  "source": "public",
2354
- "content": "---\ntitle: \"Parse Document v1\"\ndescription: \"Extract text from documents (PDF, DOCX, images) using native extraction, OCR, or vision models\"\n---\n\nFor new workflows, use [Parse Document](/steps/ai/parse-v2) (`ai.parse-v2`). This page describes Parse Document v1 (`ai.parse`), kept so existing workflows run unchanged. In the builder, a v1 step offers a one-click switch to v2.\n\n`ai.parse` turns a document into text. It is almost always the first step in a\ndocument-understanding workflow: point it at an uploaded file, get back clean\ntext plus per-page content, then feed that into [`ai.extract`](/steps/ai/extract),\n[`ai.split`](/steps/ai/split), or a [`transform.script`](/steps/transform/script).\n\n## When to use it\n\n- **You have a PDF, image, or Office document and need its text.** `ai.parse`\n handles PDFs, images (PNG/JPG), and Office formats (DOCX, PPTX, XLSX, ODT, and\n more), normalizing them to one text representation.\n- **You need per-page boundaries.** The `pages` array carries page-scoped text so\n downstream steps can cite evidence by page or split a document into sections.\n- **You need document geometry or spatial extraction.** Layout-aware OCR also\n returns normalized `pages[].layoutElements` and, when the provider supports\n it, a canonical OpenParser `ParsedDocument` on `structured` — blocks,\n regions, tables, figures, chunks, polygons, and bounding boxes. Pass the\n whole parse output (not just `.text`) into downstream `ai.extract` to enable\n shared grounded extraction, spatial citations, and lineage sidecars.\n- **You need strict data-egress control.** Use `parseMode: native` when embedded\n PDF text is enough and document bytes must not leave your deployment for OCR or\n vision. Use `parseMode: native-or-ocr` when most pages have good embedded text\n but some pages show objectively detectable extraction anomalies.\n- **You need column-aligned native PDF text.** Use `outputFormat: layout` with\n native extraction when markdown would flatten multi-column tables or forms and\n you want fixed-width plain text with horizontal gaps preserved.\n\n## How parsing is chosen\n\nThe step picks a strategy based on the document and your config:\n\n### Native (`parseMode: native`)\n\nLocal extraction only — embedded PDF text is read in the worker with **no OCR or\nvision egress**. There are **no parsing credits**. Raster images (PNG, JPG, TIFF,\nand similar) are **not supported** in this mode. **`describeFigures` is\nincompatible** — figure descriptions require a vision pass.\n\nNative extraction is **not a universal OCR replacement**. PDFs can render glyphs\nwithout usable Unicode mappings; diagnostics report detectable problems (empty\npages, replacement characters, forbidden controls, unassigned/noncharacter code\npoints, heavy private-use) but cannot certify that valid-looking text is\nsemantically correct. If **every** page is empty or suspect, the step **fails**\ninstead of returning unusable text or silently calling OCR. Mixed documents keep\nthe native text and attach per-page `nativeTextQuality`.\n\nOffice formats and plain text still use native extraction. Paginated word-processing\nand presentation formats use headless LibreOffice when per-page boundaries are\nneeded. Spreadsheets are read directly: each non-empty sheet becomes a named page,\nincluding legacy and macro-enabled Excel workbooks. Formulas and macros are never\nexecuted. Blank sheets are omitted and `pageIndex` counts the returned non-empty\nsheets, so use `pageName` when you need the workbook's sheet identity.\n\n### Spatial layout text (`outputFormat: layout`)\n\nReturns the same `text` and `pages[].text` fields as other formats, but as\nfixed-width plain text that preserves column spacing and line breaks from the\nPDF page layout. Use it for multi-column forms, tables, or address blocks where\n`markdown` (the default) would collapse horizontal alignment.\n\nConstraints:\n\n- **PDF only** — Office files, images, and plaintext fail. There is no\n Kreuzberg or OCR substitute for those types.\n- **Explicit native parse mode** — set `parseMode: native` or\n `parseMode: native-or-ocr`. Omitted `parseMode`, OCR, vision, and\n `nativeText: true` reject `layout`.\n- **Native mode is fail-closed** — every page is spatial layout text. If\n extraction fails, the step fails.\n- **Hybrid output can mix formats** — `native-or-ocr` keeps layout text on\n accepted native pages and uses the OCR provider's markdown on suspect or\n empty pages.\n- **Extractor failure is fail-closed** — a Poppler process error never\n silently routes to Kreuzberg or OCR.\n- **Other formats unchanged** — `markdown`, `plain`, `djot`, and `html` behave\n as before; `markdown` remains the default.\n\nLocal development requires `pdftotext` on `PATH` (`brew install poppler` on\nmacOS, `poppler-utils` on Linux). Managed deployments include this dependency.\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: native\n outputFormat: layout\n```\n\n### Native with OCR fallback (`parseMode: native-or-ocr`)\n\nStarts with the same local native extraction, then runs **page-quality diagnostics**\non each PDF page. Pages with **objectively detectable anomalies** — empty text,\nU+FFFD replacement characters, lone UTF-16 surrogates, forbidden controls,\nunassigned/noncharacter code points, or heavy private-use areas — trigger the\nconfigured OCR engine.\nValid-looking wrong mappings and literal `?` characters are **not** flagged; native\ndiagnostics report detectable issues but do **not** certify semantic correctness.\n\nWhen the OCR provider supports page selection, only fallback pages are processed\nand billed. Page selection does not imply reduced-byte egress: a provider may\nstill receive the original document bytes. When page selection is unavailable,\nthe provider processes and bills the **whole document**. Only detected fallback\npages replace native pages in the merged output; clean native pages are retained.\nWith `outputFormat: layout`, retained native pages stay as fixed-width layout\ntext and replaced pages use OCR markdown.\n\nYou pay **OCR credits for pages actually processed by the provider** — see\n`output.usage.ocrPagesProcessed` (which may reflect a whole-document OCR call even\nwhen only some pages replace native text). Per-page provenance is recorded on each\npage (`pages[].provenance`).\n\n### OCR (`parseMode: ocr`, the default)\n\nRuns optical character recognition for scanned PDFs and images. Select the engine\nwith `ocrModel`. Document bytes are sent to the OCR provider — **billed per\npage** according to the provider's credit rate.\n\n### Vision AI (`parseMode: vision`)\n\nReads rendered page images with the selected `llmModel`. Page images are sent to\nthe vision provider — **billed per page**. Use it for layouts where semantic\nvisual understanding matters. `pagesPerBatch` and `maxConcurrency` tune how pages\nare batched.\n\n### Legacy document-wide native text (`nativeText: true`)\n\nWhen set on **OCR or Vision** configs, the worker tries embedded PDF text first\nand falls back to the selected parser for the **whole document** if native text\nis missing. This is legacy behavior — prefer explicit `parseMode: native` or\n`native-or-ocr` for predictable egress and billing.\n\n### Figure descriptions (`describeFigures: true`)\n\nOptional vision pass **after** text extraction. With OCR or hybrid native+OCR,\n`figureModel` chooses the caption model; with Vision AI, the selected `llmModel`\nis reused. **Unavailable in Native mode.** The layout scan and caption calls are\nbilled separately and send page images to the vision provider.\n\nPaginated Office formats are converted to PDF first (via headless LibreOffice) so\nthey get true per-page boundaries instead of a single blob. Spreadsheets stay\nworkbook-native to avoid cropping wide sheets.\n\n## Data egress and cost\n\n| Mode | Document egress | Typical cost |\n| --- | --- | --- |\n| `native` | None for parsing | No parsing credits |\n| `native-or-ocr` | Capability-dependent: the provider may receive the full document even when it processes selected pages; without page selection it receives/processes the whole document | OCR credits × `usage.ocrPagesProcessed` (provider pages dispatched) |\n| `ocr` | OCR provider receives document/pages | OCR credits × page count |\n| `vision` | Vision provider receives rendered page images | Vision credits × page count |\n| `describeFigures` | Vision provider receives figure pages (additive) | Vision credits for captioned pages |\n\nThere is **one combined text output** — the worker does not emit separate native\nand OCR text streams.\n\n## Example\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: native-or-ocr\n ocrModel: openparser-default\n```\n\nFor a digital PDF with one page of garbled embedded text, most pages stay native\nin the merged output. OpenParser currently processes the whole document for OCR,\nso every page incurs OCR processing and credits. Azure can process and bill only\nthe anomalous page, but the current Azure adapter still uploads the original PDF\nbytes; page selection is not a subset-egress guarantee.\n\n## Content cache (`cache: true`)\n\nOpt-in reuse of prior parse output for **identical file bytes, filename, MIME type, and parse settings**.\nWhen enabled, the worker computes `SHA-256(file bytes + normalized parse config + filename + mimeType)`,\nlooks up a JSON blob in tenant storage (`_meta/parse-cache/<digest>.json`), and on\nhit **skips OCR/vision entirely** — no OpenParser call, no parse credits for that\nstep. On miss it parses normally and stores the result under the same key.\nResults are not cached when an optional `describeFigures` pass fails.\n\n- **Default:** `false` (safe for multi-tenant workflows; turn on when repeat parsing\n of the same uploads is expected, e.g. corpus preprocessing).\n- **Expiry:** none for now — entries persist until manually deleted or a future\n lifecycle policy lands.\n- **Scope:** tenant-isolated blob storage via the existing S3/R2 adapter (`_meta/parse-cache/<digest>.json`).\n- **Usage on hit:** returns the cached parse text/pages, but `usage.processingTimeMs` and `usage.ocrPagesProcessed` are **zero** and `usage.cached` is **true** so run metrics and OCR page counts are not double-counted. Fresh parses still record normal usage.\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: ocr\n ocrModel: openparser/paddleocr-vl-1.6\n cache: true\n```\n\n## Configuration\n\nConfiguration goes inside the step's `with:` block.\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"input\" type=\"string\" required>\nStorage reference or template expression for the document\n</ParamField>\n<ParamField path=\"parseMode\" type=\"&quot;ocr&quot; | &quot;vision&quot; | &quot;native&quot; | &quot;native-or-ocr&quot;\">\nBase parser for PDF/image inputs. OCR is the default; vision uses the selected LLM. `native` extracts PDF embedded text only and never calls OCR or vision. `native-or-ocr` extracts native text, runs page-quality diagnostics, and requests OCR when pages have detectable anomalies (empty, U+FFFD, lone surrogates, forbidden controls, unassigned/noncharacter, heavy PUA). Page selection, subset egress, and billing are provider-dependent. Valid-looking wrong text and literal \"?\" are not flagged. Text and Office files always use local parsing.\n</ParamField>\n<ParamField path=\"ocrModel\" type=\"string\">\nOCR provider ID for PDF/image parsing\n</ParamField>\n<ParamField path=\"llmModel\" type=\"string\">\nLLM provider ID for vision-based parsing\n</ParamField>\n<ParamField path=\"llmReasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"figureModel\" type=\"string\">\nVision model used only for the optional figure-description pass\n</ParamField>\n<ParamField path=\"figureReasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"maxConcurrency\" type=\"number\" default=\"3\">\nMax concurrent VLM batch requests\n</ParamField>\n<ParamField path=\"pagesPerBatch\" type=\"number\" default=\"5\">\nNumber of page images per VLM request\n</ParamField>\n<ParamField path=\"pdfRenderScale\" type=\"number\" default=\"1\">\nScale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes.\n</ParamField>\n<ParamField path=\"imageQuality\" type=\"integer\" default=\"85\">\nJPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes.\n</ParamField>\n<ParamField path=\"prompt\" type=\"string\">\nCustom extraction prompt\n</ParamField>\n<ParamField path=\"languages\" type=\"array<string>\">\nOCR language hints\n</ParamField>\n<ParamField path=\"outputFormat\" type=\"&quot;plain&quot; | &quot;markdown&quot; | &quot;djot&quot; | &quot;html&quot; | &quot;layout&quot;\" default=\"markdown\">\nFormat 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`.\n</ParamField>\n<ParamField path=\"nativeText\" type=\"boolean\" default=\"false\">\nExtract 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.\n</ParamField>\n<ParamField path=\"describeFigures\" type=\"boolean\">\nOpt-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 `&lt;figure>description&lt;/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.\n</ParamField>\n<ParamField path=\"figureInstructions\" type=\"string\">\nCustom instruction for the figure-description pass, e.g. \"Describe each figure; label a handwritten signature as `&lt;figure>signature&lt;/figure>` and a stamp as `&lt;figure>stamp&lt;/figure>`; for property photos note the room or exterior shown.\" Applied only when describeFigures runs.\n</ParamField>\n<ParamField path=\"cache\" type=\"boolean\" default=\"false\">\nWhen true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off.\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output\n\nAfter a run, inspect **`processingStrategy`** for the resolved path: `native`,\n`ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\nEach page may include **`provenance`** (`native` or `ocr`) and\n**`nativeTextQuality`** when native diagnostics ran — diagnostics report\ndetectable anomalies only, not semantic correctness.\n**`usage.ocrPagesProcessed`** counts pages billed through the OCR provider on\nhybrid runs.\n\n**`structured`** carries an OpenParser `ParsedDocument` (`openparser@1`) when\nthe parser produced one. Downstream `ai.extract` validates it at runtime; invalid\nor absent structured data keeps text-only extraction and text grounding.\n\nPer-page provenance badges in Studio run detail are planned; until then use these\noutput fields in templates, CLI inspection, or the execution JSON view.\n\n{/* GENERATED:OUTPUT START */}\n<ResponseField path=\"document\" type=\"object\" required>\n<Expandable title=\"document properties\">\n<ResponseField path=\"filename\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"mimeType\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"size\" type=\"number\" required>\nFile size in bytes\n</ResponseField>\n<ResponseField path=\"storageRef\" type=\"string\">\nStorage reference for the original file\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"usage\" type=\"object\" required>\n<Expandable title=\"usage properties\">\n<ResponseField path=\"pageCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"processingTimeMs\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"ocrPagesProcessed\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionPagesProcessed\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionPromptTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionCompletionTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"cached\" type=\"boolean\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pages\" type=\"array<object>\" required>\n<Expandable title=\"pages properties\">\n<ResponseField path=\"spreadsheet\" type=\"object\">\nOpt-in original spreadsheet cell evidence\n<Expandable title=\"spreadsheet properties\">\n<ResponseField path=\"dateSystem\" type=\"&quot;1900&quot; | &quot;1904&quot;\" required>\n</ResponseField>\n<ResponseField path=\"declaredRange\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pageIndex\" type=\"number\" required>\n0-based page index\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nExtracted page text (markdown/HTML/plain, or spatial layout text)\n</ResponseField>\n<ResponseField path=\"pageName\" type=\"string\">\nPage/sheet name (e.g., Excel sheet name)\n</ResponseField>\n<ResponseField path=\"layoutElements\" type=\"array<object>\">\nSemantic layout elements in reading order\n<Expandable title=\"layoutElements properties\">\n<ResponseField path=\"type\" type=\"&quot;paragraph&quot; | &quot;title&quot; | &quot;sectionHeading&quot; | &quot;pageHeader&quot; | &quot;pageFooter&quot; | &quot;pageNumber&quot; | &quot;footnote&quot; | &quot;table&quot; | &quot;figure&quot; | &quot;formulaBlock&quot;\" required>\n</ResponseField>\n<ResponseField path=\"content\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"table\" type=\"object\">\n</ResponseField>\n<ResponseField path=\"caption\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"figureId\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"words\" type=\"array<object>\">\nWord-level positions\n<Expandable title=\"words properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"lines\" type=\"array<object>\">\nLine-level positions\n<Expandable title=\"lines properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"tables\" type=\"array<object>\">\nExtracted tables\n<Expandable title=\"tables properties\">\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n<ResponseField path=\"rowCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"columnCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"width\" type=\"number\">\nPage width\n</ResponseField>\n<ResponseField path=\"height\" type=\"number\">\nPage height\n</ResponseField>\n<ResponseField path=\"unit\" type=\"&quot;pixel&quot; | &quot;inch&quot; | &quot;point&quot; | &quot;normalized&quot;\">\nUnit for width/height and bounding regions\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\nOverall page confidence\n</ResponseField>\n<ResponseField path=\"nativeTextQuality\" type=\"object\">\nPer-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness, valid-looking wrong mappings and literal \"?\" cannot be distinguished from legitimate text.\n<Expandable title=\"nativeTextQuality properties\">\n<ResponseField path=\"status\" type=\"&quot;clean&quot; | &quot;empty&quot; | &quot;suspect&quot;\" required>\n</ResponseField>\n<ResponseField path=\"reasons\" type=\"array<&quot;empty&quot; | &quot;replacement-character&quot; | &quot;lone-surrogate&quot; | &quot;forbidden-control&quot; | &quot;unassigned&quot; | &quot;noncharacter&quot; | &quot;private-use&quot;>\" required>\n</ResponseField>\n<ResponseField path=\"counts\" type=\"object\" required>\n</ResponseField>\n<ResponseField path=\"profile\" type=\"object\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"provenance\" type=\"object\">\nWhich extractor produced the final text/layout on this page\n<Expandable title=\"provenance properties\">\n<ResponseField path=\"source\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot;\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nCombined text from all pages\n</ResponseField>\n<ResponseField path=\"parserType\" type=\"&quot;plaintext&quot; | &quot;office&quot; | &quot;llm-vision&quot; | &quot;ocr&quot;\" required>\n</ResponseField>\n<ResponseField path=\"parserVersion\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"model\" type=\"string\">\nModel used (for LLM/OCR parsers)\n</ResponseField>\n<ResponseField path=\"processingStrategy\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot; | &quot;hybrid&quot;\">\nHow this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\n</ResponseField>\n<ResponseField path=\"structured\" type=\"record<string, unknown>\">\nCanonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\n</ResponseField>\n{/* GENERATED:OUTPUT END */}\n"
2375
+ "content": "---\ntitle: \"Parse Document v1\"\ndescription: \"Extract text from documents (PDF, DOCX, images) using native extraction, OCR, or vision models\"\n---\n\nFor new workflows, use [Parse Document](/steps/ai/parse-v2) (`ai.parse-v2`). This page describes Parse Document v1 (`ai.parse`), kept so existing workflows run unchanged. In the builder, a v1 step offers a one-click switch to v2.\n\n`ai.parse` turns a document into text. It is almost always the first step in a\ndocument-understanding workflow: point it at an uploaded file, get back clean\ntext plus per-page content, then feed that into [`ai.extract`](/steps/ai/extract),\n[`ai.split`](/steps/ai/split), or a [`transform.script`](/steps/transform/script).\n\n## When to use it\n\n- **You have a PDF, image, or Office document and need its text.** `ai.parse`\n handles PDFs, images (PNG/JPG), and Office formats (DOCX, PPTX, XLSX, ODT, and\n more), normalizing them to one text representation.\n- **You need per-page boundaries.** The `pages` array carries page-scoped text so\n downstream steps can cite evidence by page or split a document into sections.\n- **You need document geometry or spatial extraction.** Layout-aware OCR also\n returns normalized `pages[].layoutElements` and, when the provider supports\n it, a canonical OpenParser `ParsedDocument` on `structured` — blocks,\n regions, tables, figures, chunks, polygons, and bounding boxes. Pass the\n whole parse output (not just `.text`) into downstream `ai.extract` to enable\n shared grounded extraction, spatial citations, and lineage sidecars.\n- **You need strict data-egress control.** Use `parseMode: native` when embedded\n PDF text is enough and document bytes must not leave your deployment for OCR or\n vision. Use `parseMode: native-or-ocr` when most pages have good embedded text\n but some pages show objectively detectable extraction anomalies.\n- **You need column-aligned native PDF text.** Use `outputFormat: layout` with\n native extraction when markdown would flatten multi-column tables or forms and\n you want fixed-width plain text with horizontal gaps preserved.\n\n## How parsing is chosen\n\nThe step picks a strategy based on the document and your config:\n\n### Native (`parseMode: native`)\n\nLocal extraction only — embedded PDF text is read in the worker with **no OCR or\nvision egress**. There are **no parsing credits**. Raster images (PNG, JPG, TIFF,\nand similar) are **not supported** in this mode. **`describeFigures` is\nincompatible** — figure descriptions require a vision pass.\n\nNative extraction is **not a universal OCR replacement**. PDFs can render glyphs\nwithout usable Unicode mappings; diagnostics report detectable problems (empty\npages, replacement characters, forbidden controls, unassigned/noncharacter code\npoints, heavy private-use) but cannot certify that valid-looking text is\nsemantically correct. If **every** page is empty or suspect, the step **fails**\ninstead of returning unusable text or silently calling OCR. Mixed documents keep\nthe native text and attach per-page `nativeTextQuality`.\n\nOffice formats and plain text still use native extraction. Paginated word-processing\nand presentation formats use headless LibreOffice when per-page boundaries are\nneeded. Spreadsheets are read directly: each non-empty sheet becomes a named page,\nincluding legacy and macro-enabled Excel workbooks. Formulas and macros are never\nexecuted. Blank sheets are omitted and `pageIndex` counts the returned non-empty\nsheets, so use `pageName` when you need the workbook's sheet identity.\n\n### Spatial layout text (`outputFormat: layout`)\n\nReturns the same `text` and `pages[].text` fields as other formats, but as\nfixed-width plain text that preserves column spacing and line breaks from the\nPDF page layout. Use it for multi-column forms, tables, or address blocks where\n`markdown` (the default) would collapse horizontal alignment.\n\nConstraints:\n\n- **PDF only** — Office files, images, and plaintext fail. There is no\n Kreuzberg or OCR substitute for those types.\n- **Explicit native parse mode** — set `parseMode: native` or\n `parseMode: native-or-ocr`. Omitted `parseMode`, OCR, vision, and\n `nativeText: true` reject `layout`.\n- **Native mode is fail-closed** — every page is spatial layout text. If\n extraction fails, the step fails.\n- **Hybrid output can mix formats** — `native-or-ocr` keeps layout text on\n accepted native pages and uses the OCR provider's markdown on suspect or\n empty pages.\n- **Extractor failure is fail-closed** — a Poppler process error never\n silently routes to Kreuzberg or OCR.\n- **Other formats unchanged** — `markdown`, `plain`, `djot`, and `html` behave\n as before; `markdown` remains the default.\n\nLocal development requires `pdftotext` on `PATH` (`brew install poppler` on\nmacOS, `poppler-utils` on Linux). Managed deployments include this dependency.\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: native\n outputFormat: layout\n```\n\n### Native with OCR fallback (`parseMode: native-or-ocr`)\n\nStarts with the same local native extraction, then runs **page-quality diagnostics**\non each PDF page. Pages with **objectively detectable anomalies** — empty text,\nU+FFFD replacement characters, lone UTF-16 surrogates, forbidden controls,\nunassigned/noncharacter code points, or heavy private-use areas — trigger the\nconfigured OCR engine.\nValid-looking wrong mappings and literal `?` characters are **not** flagged; native\ndiagnostics report detectable issues but do **not** certify semantic correctness.\n\nWhen the OCR provider supports page selection, only fallback pages are processed\nand billed. Page selection does not imply reduced-byte egress: a provider may\nstill receive the original document bytes. When page selection is unavailable,\nthe provider processes and bills the **whole document**. Only detected fallback\npages replace native pages in the merged output; clean native pages are retained.\nWith `outputFormat: layout`, retained native pages stay as fixed-width layout\ntext and replaced pages use OCR markdown.\n\nYou pay **OCR credits for pages actually processed by the provider** — see\n`output.usage.ocrPagesProcessed` (which may reflect a whole-document OCR call even\nwhen only some pages replace native text). Per-page provenance is recorded on each\npage (`pages[].provenance`).\n\n### OCR (`parseMode: ocr`, the default)\n\nRuns optical character recognition for scanned PDFs and images. Select the engine\nwith `ocrModel`. Document bytes are sent to the OCR provider — **billed per\npage** according to the provider's credit rate.\n\n### Vision AI (`parseMode: vision`)\n\nReads rendered page images with the selected `llmModel`. Page images are sent to\nthe vision provider — **billed per page**. Use it for layouts where semantic\nvisual understanding matters. `pagesPerBatch` and `maxConcurrency` tune how pages\nare batched.\n\n### Legacy document-wide native text (`nativeText: true`)\n\nWhen set on **OCR or Vision** configs, the worker tries embedded PDF text first\nand falls back to the selected parser for the **whole document** if native text\nis missing. This is legacy behavior — prefer explicit `parseMode: native` or\n`native-or-ocr` for predictable egress and billing.\n\n### Figure descriptions (`describeFigures: true`)\n\nOptional vision pass **after** text extraction. With OCR or hybrid native+OCR,\n`figureModel` chooses the caption model; with Vision AI, the selected `llmModel`\nis reused. **Unavailable in Native mode.** The layout scan and caption calls are\nbilled separately and send page images to the vision provider.\n\nPaginated Office formats are converted to PDF first (via headless LibreOffice) so\nthey get true per-page boundaries instead of a single blob. Spreadsheets stay\nworkbook-native to avoid cropping wide sheets.\n\n## Data egress and cost\n\n| Mode | Document egress | Typical cost |\n| --- | --- | --- |\n| `native` | None for parsing | No parsing credits |\n| `native-or-ocr` | Capability-dependent: the provider may receive the full document even when it processes selected pages; without page selection it receives/processes the whole document | OCR credits × `usage.ocrPagesProcessed` (provider pages dispatched) |\n| `ocr` | OCR provider receives document/pages | OCR credits × page count |\n| `vision` | Vision provider receives rendered page images | Vision credits × page count |\n| `describeFigures` | Vision provider receives figure pages (additive) | Vision credits for captioned pages |\n\nThere is **one combined text output** — the worker does not emit separate native\nand OCR text streams.\n\n## Example\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: native-or-ocr\n ocrModel: openparser-default\n```\n\nFor a digital PDF with one page of garbled embedded text, most pages stay native\nin the merged output. OpenParser currently processes the whole document for OCR,\nso every page incurs OCR processing and credits. Azure can process and bill only\nthe anomalous page, but the current Azure adapter still uploads the original PDF\nbytes; page selection is not a subset-egress guarantee.\n\n## Content cache (`cache: true`)\n\nOpt-in reuse of prior parse output for **identical file bytes, filename, MIME type, and parse settings**.\nWhen enabled, the worker computes `SHA-256(file bytes + normalized parse config + filename + mimeType)`,\nlooks up a JSON blob in tenant storage (`_meta/parse-cache/<digest>.json`), and on\nhit **skips OCR/vision entirely** — no OpenParser call, no parse credits for that\nstep. On miss it parses normally and stores the result under the same key.\nResults are not cached when an optional `describeFigures` pass fails.\n\n- **Default:** `false` (safe for multi-tenant workflows; turn on when repeat parsing\n of the same uploads is expected, e.g. corpus preprocessing).\n- **Expiry:** none for now — entries persist until manually deleted or a future\n lifecycle policy lands.\n- **Scope:** tenant-isolated blob storage via the existing S3/R2 adapter (`_meta/parse-cache/<digest>.json`).\n- **Usage on hit:** returns the cached parse text/pages, but `usage.processingTimeMs` and `usage.ocrPagesProcessed` are **zero** and `usage.cached` is **true** so run metrics and OCR page counts are not double-counted. Fresh parses still record normal usage.\n\n```yaml\n- name: parse\n type: ai.parse\n with:\n input: '{{ input.document }}'\n parseMode: ocr\n ocrModel: openparser/paddleocr-vl-1.6\n cache: true\n```\n\n## Configuration\n\nConfiguration goes inside the step's `with:` block.\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"input\" type=\"string\" required>\nStorage reference or template expression for the document\n</ParamField>\n<ParamField path=\"parseMode\" type=\"&quot;ocr&quot; | &quot;vision&quot; | &quot;native&quot; | &quot;native-or-ocr&quot;\">\nBase parser for PDF/image inputs. OCR is the default; vision uses the selected LLM. `native` extracts PDF embedded text only and never calls OCR or vision. `native-or-ocr` extracts native text, runs page-quality diagnostics, and requests OCR when pages have detectable anomalies (empty, U+FFFD, lone surrogates, forbidden controls, unassigned/noncharacter, heavy PUA). Page selection, subset egress, and billing are provider-dependent. Valid-looking wrong text and literal \"?\" are not flagged. Text and Office files always use local parsing.\n</ParamField>\n<ParamField path=\"ocrModel\" type=\"string\">\nOCR provider ID for PDF/image parsing\n</ParamField>\n<ParamField path=\"llmModel\" type=\"string\">\nLLM provider ID for vision-based parsing\n</ParamField>\n<ParamField path=\"llmReasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"figureModel\" type=\"string\">\nVision model used only for the optional figure-description pass\n</ParamField>\n<ParamField path=\"figureReasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\nReasoning effort for models that support it. Omit to use the selected model's default.\n</ParamField>\n<ParamField path=\"maxConcurrency\" type=\"number\" default=\"3\">\nMax concurrent VLM batch requests\n</ParamField>\n<ParamField path=\"pagesPerBatch\" type=\"number\" default=\"5\">\nNumber of page images per VLM request\n</ParamField>\n<ParamField path=\"pdfRenderScale\" type=\"number\" default=\"1\">\nScale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes.\n</ParamField>\n<ParamField path=\"imageQuality\" type=\"integer\" default=\"85\">\nJPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes.\n</ParamField>\n<ParamField path=\"prompt\" type=\"string\">\nCustom extraction prompt\n</ParamField>\n<ParamField path=\"languages\" type=\"array<string>\">\nOCR language hints\n</ParamField>\n<ParamField path=\"outputFormat\" type=\"&quot;plain&quot; | &quot;markdown&quot; | &quot;djot&quot; | &quot;html&quot; | &quot;layout&quot;\" default=\"markdown\">\nFormat 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`.\n</ParamField>\n<ParamField path=\"nativeText\" type=\"boolean\" default=\"false\">\nExtract 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.\n</ParamField>\n<ParamField path=\"describeFigures\" type=\"boolean\">\nOpt-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 `&lt;figure>description&lt;/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.\n</ParamField>\n<ParamField path=\"figureInstructions\" type=\"string\">\nCustom instruction for the figure-description pass, e.g. \"Describe each figure; label a handwritten signature as `&lt;figure>signature&lt;/figure>` and a stamp as `&lt;figure>stamp&lt;/figure>`; for property photos note the room or exterior shown.\" Applied only when describeFigures runs.\n</ParamField>\n<ParamField path=\"cache\" type=\"boolean\" default=\"false\">\nWhen true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off.\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output\n\nAfter a run, inspect **`processingStrategy`** for the resolved path: `native`,\n`ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\nEach page may include **`provenance`** (`native` or `ocr`) and\n**`nativeTextQuality`** when native diagnostics ran — diagnostics report\ndetectable anomalies only, not semantic correctness.\n**`usage.ocrPagesProcessed`** counts pages billed through the OCR provider on\nhybrid runs.\n\n**`structured`** carries an OpenParser `ParsedDocument` (`openparser@1`) when\nthe parser produced one. Downstream `ai.extract` validates it at runtime; invalid\nor absent structured data keeps text-only extraction and text grounding.\n\nPer-page provenance badges in Studio run detail are planned; until then use these\noutput fields in templates, CLI inspection, or the execution JSON view.\n\n{/* GENERATED:OUTPUT START */}\n<ResponseField path=\"document\" type=\"object\" required>\n<Expandable title=\"document properties\">\n<ResponseField path=\"filename\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"mimeType\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"size\" type=\"number\" required>\nFile size in bytes\n</ResponseField>\n<ResponseField path=\"storageRef\" type=\"string\">\nStorage reference for the original file\n</ResponseField>\n<ResponseField path=\"renderedPdfRef\" type=\"string\">\nStorage key of the PDF an office input was rendered to. Page word boxes are measured on this PDF.\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"usage\" type=\"object\" required>\n<Expandable title=\"usage properties\">\n<ResponseField path=\"pageCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"processingTimeMs\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"ocrPagesProcessed\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionPagesProcessed\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionPromptTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionCompletionTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"cached\" type=\"boolean\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pages\" type=\"array<object>\" required>\n<Expandable title=\"pages properties\">\n<ResponseField path=\"spreadsheet\" type=\"object\">\nOpt-in original spreadsheet cell evidence\n<Expandable title=\"spreadsheet properties\">\n<ResponseField path=\"dateSystem\" type=\"&quot;1900&quot; | &quot;1904&quot;\" required>\n</ResponseField>\n<ResponseField path=\"declaredRange\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pageIndex\" type=\"number\" required>\n0-based page index\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nExtracted page text (markdown/HTML/plain, or spatial layout text)\n</ResponseField>\n<ResponseField path=\"pageName\" type=\"string\">\nPage/sheet name (e.g., Excel sheet name)\n</ResponseField>\n<ResponseField path=\"layoutElements\" type=\"array<object>\">\nSemantic layout elements in reading order\n<Expandable title=\"layoutElements properties\">\n<ResponseField path=\"type\" type=\"&quot;paragraph&quot; | &quot;title&quot; | &quot;sectionHeading&quot; | &quot;pageHeader&quot; | &quot;pageFooter&quot; | &quot;pageNumber&quot; | &quot;footnote&quot; | &quot;table&quot; | &quot;figure&quot; | &quot;formulaBlock&quot;\" required>\n</ResponseField>\n<ResponseField path=\"content\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"table\" type=\"object\">\n</ResponseField>\n<ResponseField path=\"caption\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"figureId\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"words\" type=\"array<object>\">\nWord-level positions\n<Expandable title=\"words properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"lines\" type=\"array<object>\">\nLine-level positions\n<Expandable title=\"lines properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"tables\" type=\"array<object>\">\nExtracted tables\n<Expandable title=\"tables properties\">\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n<ResponseField path=\"rowCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"columnCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"width\" type=\"number\">\nPage width\n</ResponseField>\n<ResponseField path=\"height\" type=\"number\">\nPage height\n</ResponseField>\n<ResponseField path=\"unit\" type=\"&quot;pixel&quot; | &quot;inch&quot; | &quot;point&quot; | &quot;normalized&quot;\">\nUnit for width/height and bounding regions\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\nOverall page confidence\n</ResponseField>\n<ResponseField path=\"nativeTextQuality\" type=\"object\">\nPer-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness, valid-looking wrong mappings and literal \"?\" cannot be distinguished from legitimate text.\n<Expandable title=\"nativeTextQuality properties\">\n<ResponseField path=\"status\" type=\"&quot;clean&quot; | &quot;empty&quot; | &quot;suspect&quot;\" required>\n</ResponseField>\n<ResponseField path=\"reasons\" type=\"array<&quot;empty&quot; | &quot;replacement-character&quot; | &quot;lone-surrogate&quot; | &quot;forbidden-control&quot; | &quot;unassigned&quot; | &quot;noncharacter&quot; | &quot;private-use&quot;>\" required>\n</ResponseField>\n<ResponseField path=\"counts\" type=\"object\" required>\n</ResponseField>\n<ResponseField path=\"profile\" type=\"object\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"provenance\" type=\"object\">\nWhich extractor produced the final text/layout on this page\n<Expandable title=\"provenance properties\">\n<ResponseField path=\"source\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot;\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nCombined text from all pages\n</ResponseField>\n<ResponseField path=\"parserType\" type=\"&quot;plaintext&quot; | &quot;office&quot; | &quot;llm-vision&quot; | &quot;ocr&quot;\" required>\n</ResponseField>\n<ResponseField path=\"parserVersion\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"model\" type=\"string\">\nModel used (for LLM/OCR parsers)\n</ResponseField>\n<ResponseField path=\"processingStrategy\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot; | &quot;hybrid&quot;\">\nHow this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\n</ResponseField>\n<ResponseField path=\"structured\" type=\"record<string, unknown>\">\nCanonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\n</ResponseField>\n{/* GENERATED:OUTPUT END */}\n"
2355
2376
  },
2356
2377
  {
2357
2378
  "topic": "steps/ai/parse-v2",
2358
2379
  "title": "Parse Document",
2359
2380
  "description": "Automatic native-first parsing with OCR/vision recovery, explicit completeness, and professional controls.",
2360
2381
  "source": "public",
2361
- "content": "---\ntitle: 'Parse Document'\ndescription: 'Automatic native-first parsing with OCR/vision recovery, explicit completeness, and professional controls.'\n---\n\n`ai.parse-v2` reads supported PDF, image, Office, and text files. Start with just the input:\n\n```yaml\n- name: parse\n type: ai.parse-v2\n with:\n input: '{{ input.document }}'\n```\n\nPDFs use local embedded text first. Empty or suspect pages and pages containing embedded raster images are read with the first available allowed image-reading backend: OCR, then vision. Clean native pages are retained. Text and Office files use local parsers; the optical recovery policy applies to PDFs and raster images. Raster images go directly to image reading; multipage TIFF/image frames keep their original page indices.\n\nThe worker conservatively treats embedded images as potential text, including scans below a native header. It reads the entire affected page and replaces that page's text, avoiding duplicated native headers. This can process pages containing photos or logos even when their native text is usable. It is a completeness safeguard, not semantic proof that every extracted character is correct. Unicode diagnostics cannot detect valid-looking wrong font mappings.\n\nA uniformly white rendered page is marked `blank` without a provider call. Vision can explicitly report `no-text` for a visual page without readable text. Empty provider responses, missing pages, and missing required evidence remain unresolved. Ambiguous multi-page vision results are retried as individual pages.\n\nVision selection prefers the deployment parsing default or vision role, then another registered image-capable client. A vision-capable model with a text role can still recover scans; a text-only model cannot. Configuration readiness uses the same client capability inference and requires a live probe to verify custom endpoints.\n\n## Policy and provider selection\n\n```yaml\npolicy:\n native: prefer\n imageReading:\n order: [ocr, vision]\nproviders:\n ocr: onprem/paddle\n vision: openai/gpt-6-luna\n```\n\n| Setting | Meaning |\n| --- | --- |\n| `policy.native: prefer` | Try native PDF text, then recover unread content. Default. |\n| `policy.native: require` | Require local extraction. Never send document content for OCR or vision transcription. Explicit figure enrichment is independent. Scanned/unread pages fail. Raster images are rejected. |\n| `policy.native: skip` | Read every nonblank PDF/image page visually. Text and Office files still parse locally. |\n| `policy.imageReading.order` | Ordered **allowed** backends: `[ocr, vision]`, `[vision, ocr]`, `[ocr]`, or `[vision]`. A single backend prohibits the other. |\n| `providers.ocr` / `providers.vision` | Exact model/provider IDs. Missing or non-vision pins fail; they never silently use a different provider. |\n\nOmitted providers use deployment parsing defaults. Vision otherwise uses the configured vision role, then an available vision-capable registered client. V2 does not inherit the workflow's text-generation `defaultModel` or the tenant's general text default.\n\nOn-prem administrators can configure defaults and enforce provider boundaries once:\n\n```yaml\n# eigenpal.config.yaml; models must also be configured as usual.\ndeployment:\n parsing:\n ocrProvider: onprem/paddle\n visionProvider: onprem/vision\n allowedProviders: [onprem/paddle, onprem/vision]\n```\n\n`allowedProviders` applies to provider overrides and figure enrichment, too. With no OCR, a configured allowed vision provider reads scans automatically. With neither capability, scans cannot be read; configure an approved OCR/vision endpoint. Eigenpal does not bundle a new local OCR service in this release.\n\nRecoverable provider outages use client retry budgets and may proceed to the next allowed backend. Authentication, authorization, cancellation, quota, and validation failures propagate. A sparse or empty OCR result can recover only unresolved pages through vision.\n\n## Output and evidence\n\n```yaml\noutput:\n textFormat: markdown\n nativeWhitespace: reading-order\n require: []\n```\n\n`textFormat` supports `markdown`, `plain`, `html`, and `djot`. OCR/vision Markdown is converted locally to the requested format. Use `nativeWhitespace: spatial` with `textFormat: plain` to preserve native PDF column spacing. Spatial whitespace is PDF-only and does not invent coordinates for OCR/vision output.\n\n`output.require` accepts `wordCoordinates` and `tables`. Every nonblank text page must provide the requested evidence. Vision transcription cannot satisfy these requirements. A native page lacking required evidence is eligible for OCR recovery. Table capability does not mean a table exists on every page.\n\nThe familiar `text`, `pages`, `document`, and `processingStrategy` fields remain available for downstream extraction, splitting, and review. V2 adds:\n\n- `parserVersion: \"2\"`.\n- `completeness.status`: `complete` or `partial`.\n- `completeness.unresolvedPageIndexes`: original 0-based page indices.\n- Per-page `status`: `complete`, `blank`, `no-text`, or `unresolved`.\n- Per-page `provenance`: source, provider/model when applicable, reason, actual text format, and available evidence capabilities.\n- Per-page warnings and native-text diagnostics.\n- `usage.ocrPagesProcessed` and `usage.visionPagesProcessed`.\n\nOriginal page order and indices are retained. Document-wide structured output is retained for fully native output or a complete result from one OCR call. There is no fabricated merged document graph for mixed backends; page-level evidence remains available.\n\nOCR selection, egress, and billing depend on provider capabilities: a provider may receive or process the whole PDF even when only some pages need recovery. Vision renders and sends selected pages. Provider calls and figure descriptions can incur credits.\n\n## Spreadsheet fidelity\n\nXLS and XLSX parse locally into one page per nonempty sheet. Cells retain addresses and their displayed text, formatted using recorded number formats and the workbook's 1900/1904 date system. Formulas use cached values and are never calculated. Empty declared trailing extent does not generate text.\n\nSet `output.includeCellMetadata: true` for ambiguous or mixed date/identifier columns. Each page adds `spreadsheet: {dateSystem, declaredRange, cells}` with raw/displayed values, storage types, formats, addresses, and formulas. The same evidence is annotated in page text, so downstream extraction using only `text` can still see it. A valid date-formatted serial also exposes `dateValue` without a timezone; Excel's fictitious 1900-02-29 is explicitly marked. This describes Excel formatting, not the value's business meaning.\n\nThe parser preserves identifiers and strings even under misleading headers. It does not infer dates from unformatted numbers, normalize names, or classify birth dates versus identifiers. Let the extraction model interpret source evidence and domain rules; flag conflicting or ambiguous evidence. For row objects from one selected sheet, use [`transform.xlsx-to-json`](/steps/transform/xlsx-to-json) with `valueMode: displayed` and `includeCellMetadata: true`, passing the full output to extraction.\n\n## Enrichment and advanced controls\n\n```yaml\nenrichment:\n figures:\n enabled: false\n # provider: onprem/vision\n # instructions: Describe charts and signatures.\n # reasoningEffort: low\nadvanced:\n cache: false\n allowPartial: false\n # languages: [en, de]\n vision:\n maxConcurrency: 3\n pagesPerBatch: 5\n renderScale: 2\n imageQuality: 85\n # instructions: Faithfully transcribe all visible text; do not summarize.\n # reasoningEffort: low\n```\n\nFigure descriptions are a separate opt-in vision pass and cannot run under native-only policy. Enrichment errors fail v2 instead of silently omitting a requested pass.\n\n`advanced.allowPartial: true` returns unresolved pages with explicit diagnostics. The default fails whenever a page remains unresolved. An empty provider response is never accepted as completed parsing.\n\n`advanced.cache: true` reuses only complete results. Cache identity includes v2 policy/version, file identity, settings, and resolved provider IDs. Cache hits do not incur new parsing usage. Cache JSON remains in tenant storage without automatic expiry.\n\n## Readiness and migration\n\n```bash\neigenpal workflow step-type get ai.parse-v2\neigenpal models parser-readiness --json\neigenpal models list --json\n```\n\nReadiness reports configured, deployment-approved image-reading capabilities. It does **not** probe worker binaries or live provider health. Before accepting customer traffic, run native, scanned, and mixed fixtures through the deployment. For the bundled headless `parse-document` workflow:\n\n```bash\nbun scripts/smoke/parse-v2.ts --base-url http://127.0.0.1:8080\n```\n\nThe smoke test sends only a generated native/scanned fixture and checks that both page values were recovered. Use `HEADLESS_API_TOKEN` for authenticated headless deployments.\n\nLegacy `ai.parse` keeps its existing behavior. Migration writes a new local workflow file and never changes or publishes the source:\n\n```bash\n# Keep deliberate native/OCR/vision restrictions.\neigenpal workflow migrate-parser workflow.yaml --policy preserve --out workflow-v2.yaml\n\n# Adopt native-first automatic OCR/vision recovery.\neigenpal workflow migrate-parser workflow.yaml --policy auto --out workflow-v2-auto.yaml\n```\n\nPreserving `native-or-ocr` preserves its OCR-only restriction: it still cannot use vision. Choose automatic policy to fix the OCR-absent/vision-available case. Migration reports broadened backend use, formatting changes, and document-wide `nativeText` behavior changes. Unknown settings require review rather than being silently dropped. The builder offers the same two reversible migration choices.\n\nValidate and compare representative documents before publishing, including downstream fields, evidence, page coverage, latency, and costs. V2 completeness checks can expose failures that legacy parsing previously accepted. Migration is not a byte-identical output promise.\n\nFigure enrichment is independent of text transcription policy and must be explicitly enabled. It may call vision even with `policy.native: require`; keep it disabled when all document processing must remain local. Requested enrichment failures fail the step.\n\n## Configuration reference\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"policy\" type=\"object\" required>\n<Expandable title=\"policy properties\">\n<ParamField path=\"native\" type=\"&quot;prefer&quot; | &quot;require&quot; | &quot;skip&quot;\" default=\"prefer\">\nPrefer local text extraction, require local text extraction with no image transcription, or skip native PDF extraction. Figure enrichment is independent.\n</ParamField>\n<ParamField path=\"imageReading\" type=\"object\" required>\n<Expandable title=\"imageReading properties\">\n<ParamField path=\"order\" type=\"array<&quot;ocr&quot; | &quot;vision&quot;>\" default=\"[&quot;ocr&quot;,&quot;vision&quot;]\">\nOrdered allowed backends. A single entry prohibits the other backend.\n</ParamField>\n</Expandable>\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"providers\" type=\"object\" required>\n<Expandable title=\"providers properties\">\n<ParamField path=\"ocr\" type=\"string\">\nExact configured OCR provider ID. Missing pins fail; they never resolve to another provider.\n</ParamField>\n<ParamField path=\"vision\" type=\"string\">\nExact configured vision provider ID. Otherwise uses the deployment parsing default or vision role.\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"output\" type=\"object\" required>\n<Expandable title=\"output properties\">\n<ParamField path=\"textFormat\" type=\"&quot;plain&quot; | &quot;markdown&quot; | &quot;html&quot; | &quot;djot&quot;\" default=\"markdown\">\n</ParamField>\n<ParamField path=\"includeCellMetadata\" type=\"boolean\" default=\"false\">\nInclude spreadsheet cell evidence in pages[].spreadsheet and annotate text for downstream extraction. Preserves raw/displayed values and workbook date system.\n</ParamField>\n<ParamField path=\"nativeWhitespace\" type=\"&quot;reading-order&quot; | &quot;spatial&quot;\" default=\"reading-order\">\nSpatial preserves native PDF column spacing. It does not promise OCR/vision coordinates.\n</ParamField>\n<ParamField path=\"require\" type=\"array<&quot;wordCoordinates&quot; | &quot;tables&quot;>\" default=\"[]\">\nRequired evidence capabilities on nonblank pages. Backends unable to satisfy them are rejected.\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"enrichment\" type=\"object\" required>\n<Expandable title=\"enrichment properties\">\n<ParamField path=\"figures\" type=\"object\" required>\n<Expandable title=\"figures properties\">\n<ParamField path=\"enabled\" type=\"boolean\" default=\"false\">\n</ParamField>\n<ParamField path=\"provider\" type=\"string\">\n</ParamField>\n<ParamField path=\"instructions\" type=\"string\">\n</ParamField>\n<ParamField path=\"reasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\n</ParamField>\n</Expandable>\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"advanced\" type=\"object\" required>\n<Expandable title=\"advanced properties\">\n<ParamField path=\"vision\" type=\"object\" required>\n<Expandable title=\"vision properties\">\n<ParamField path=\"maxConcurrency\" type=\"integer\" default=\"3\">\n</ParamField>\n<ParamField path=\"pagesPerBatch\" type=\"integer\" default=\"5\">\n</ParamField>\n<ParamField path=\"renderScale\" type=\"number\" default=\"2\">\n</ParamField>\n<ParamField path=\"imageQuality\" type=\"integer\" default=\"85\">\n</ParamField>\n<ParamField path=\"instructions\" type=\"string\">\nTranscription instructions, never document-specific extraction/schema instructions.\n</ParamField>\n<ParamField path=\"reasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"languages\" type=\"array<string>\">\n</ParamField>\n<ParamField path=\"allowPartial\" type=\"boolean\" default=\"false\">\nReturn unresolved pages explicitly instead of failing. Default false.\n</ParamField>\n<ParamField path=\"cache\" type=\"boolean\" default=\"false\">\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"input\" type=\"string\" required>\nFile reference or template expression for the document\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output reference\n\n{/* GENERATED:OUTPUT START */}\n<ResponseField path=\"document\" type=\"object\" required>\n<Expandable title=\"document properties\">\n<ResponseField path=\"filename\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"mimeType\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"size\" type=\"number\" required>\nFile size in bytes\n</ResponseField>\n<ResponseField path=\"storageRef\" type=\"string\">\nStorage reference for the original file\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"usage\" type=\"object\" required>\n<Expandable title=\"usage properties\">\n<ResponseField path=\"pageCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"processingTimeMs\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"ocrPagesProcessed\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionPagesProcessed\" type=\"integer\" required>\n</ResponseField>\n<ResponseField path=\"visionPromptTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionCompletionTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"cached\" type=\"boolean\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pages\" type=\"array<object>\" required>\n<Expandable title=\"pages properties\">\n<ResponseField path=\"spreadsheet\" type=\"object\">\nOpt-in original spreadsheet cell evidence\n<Expandable title=\"spreadsheet properties\">\n<ResponseField path=\"dateSystem\" type=\"&quot;1900&quot; | &quot;1904&quot;\" required>\n</ResponseField>\n<ResponseField path=\"declaredRange\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pageIndex\" type=\"number\" required>\n0-based page index\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nExtracted page text (markdown/HTML/plain, or spatial layout text)\n</ResponseField>\n<ResponseField path=\"pageName\" type=\"string\">\nPage/sheet name (e.g., Excel sheet name)\n</ResponseField>\n<ResponseField path=\"layoutElements\" type=\"array<object>\">\nSemantic layout elements in reading order\n<Expandable title=\"layoutElements properties\">\n<ResponseField path=\"type\" type=\"&quot;paragraph&quot; | &quot;title&quot; | &quot;sectionHeading&quot; | &quot;pageHeader&quot; | &quot;pageFooter&quot; | &quot;pageNumber&quot; | &quot;footnote&quot; | &quot;table&quot; | &quot;figure&quot; | &quot;formulaBlock&quot;\" required>\n</ResponseField>\n<ResponseField path=\"content\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"table\" type=\"object\">\n</ResponseField>\n<ResponseField path=\"caption\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"figureId\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"words\" type=\"array<object>\">\nWord-level positions\n<Expandable title=\"words properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"lines\" type=\"array<object>\">\nLine-level positions\n<Expandable title=\"lines properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"tables\" type=\"array<object>\">\nExtracted tables\n<Expandable title=\"tables properties\">\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n<ResponseField path=\"rowCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"columnCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"width\" type=\"number\">\nPage width\n</ResponseField>\n<ResponseField path=\"height\" type=\"number\">\nPage height\n</ResponseField>\n<ResponseField path=\"unit\" type=\"&quot;pixel&quot; | &quot;inch&quot; | &quot;point&quot; | &quot;normalized&quot;\">\nUnit for width/height and bounding regions\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\nOverall page confidence\n</ResponseField>\n<ResponseField path=\"nativeTextQuality\" type=\"object\">\nPer-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness, valid-looking wrong mappings and literal \"?\" cannot be distinguished from legitimate text.\n<Expandable title=\"nativeTextQuality properties\">\n<ResponseField path=\"status\" type=\"&quot;clean&quot; | &quot;empty&quot; | &quot;suspect&quot;\" required>\n</ResponseField>\n<ResponseField path=\"reasons\" type=\"array<&quot;empty&quot; | &quot;replacement-character&quot; | &quot;lone-surrogate&quot; | &quot;forbidden-control&quot; | &quot;unassigned&quot; | &quot;noncharacter&quot; | &quot;private-use&quot;>\" required>\n</ResponseField>\n<ResponseField path=\"counts\" type=\"object\" required>\n</ResponseField>\n<ResponseField path=\"profile\" type=\"object\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"provenance\" type=\"object\" required>\n<Expandable title=\"provenance properties\">\n<ResponseField path=\"source\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot;\" required>\n</ResponseField>\n<ResponseField path=\"provider\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"model\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"reason\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"textFormat\" type=\"&quot;plain&quot; | &quot;markdown&quot; | &quot;html&quot; | &quot;djot&quot;\" required>\n</ResponseField>\n<ResponseField path=\"capabilities\" type=\"array<&quot;wordCoordinates&quot; | &quot;tables&quot;>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"status\" type=\"&quot;complete&quot; | &quot;blank&quot; | &quot;no-text&quot; | &quot;unresolved&quot;\" required>\n</ResponseField>\n<ResponseField path=\"warnings\" type=\"array<string>\" default=\"[]\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nCombined text from all pages\n</ResponseField>\n<ResponseField path=\"parserType\" type=\"&quot;plaintext&quot; | &quot;office&quot; | &quot;llm-vision&quot; | &quot;ocr&quot;\" required>\n</ResponseField>\n<ResponseField path=\"parserVersion\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"model\" type=\"string\">\nModel used (for LLM/OCR parsers)\n</ResponseField>\n<ResponseField path=\"processingStrategy\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot; | &quot;hybrid&quot;\">\nHow this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\n</ResponseField>\n<ResponseField path=\"structured\" type=\"record<string, unknown>\">\nCanonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\n</ResponseField>\n<ResponseField path=\"completeness\" type=\"object\" required>\n<Expandable title=\"completeness properties\">\n<ResponseField path=\"status\" type=\"&quot;complete&quot; | &quot;partial&quot;\" required>\n</ResponseField>\n<ResponseField path=\"unresolvedPageIndexes\" type=\"array<integer>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n{/* GENERATED:OUTPUT END */}\n"
2382
+ "content": "---\ntitle: 'Parse Document'\ndescription: 'Automatic native-first parsing with OCR/vision recovery, explicit completeness, and professional controls.'\n---\n\n`ai.parse-v2` reads supported PDF, image, Office, and text files. Start with just the input:\n\n```yaml\n- name: parse\n type: ai.parse-v2\n with:\n input: '{{ input.document }}'\n```\n\nPDFs use local embedded text first. Empty or suspect pages and pages containing embedded raster images are read with the first available allowed image-reading backend: OCR, then vision. Clean native pages are retained. Text and Office files use local parsers; the optical recovery policy applies to PDFs and raster images. Raster images go directly to image reading; multipage TIFF/image frames keep their original page indices.\n\nThe worker conservatively treats embedded images as potential text, including scans below a native header. It reads the entire affected page and replaces that page's text, avoiding duplicated native headers. This can process pages containing photos or logos even when their native text is usable. It is a completeness safeguard, not semantic proof that every extracted character is correct. Unicode diagnostics cannot detect valid-looking wrong font mappings.\n\nA uniformly white rendered page is marked `blank` without a provider call. Vision can explicitly report `no-text` for a visual page without readable text. Empty provider responses, missing pages, and missing required evidence remain unresolved. Ambiguous multi-page vision results are retried as individual pages.\n\nVision selection prefers the deployment parsing default or vision role, then another registered image-capable client. A vision-capable model with a text role can still recover scans; a text-only model cannot. Configuration readiness uses the same client capability inference and requires a live probe to verify custom endpoints.\n\n## Policy and provider selection\n\n```yaml\npolicy:\n native: prefer\n imageReading:\n order: [ocr, vision]\nproviders:\n ocr: onprem/paddle\n vision: openai/gpt-6-luna\n```\n\n| Setting | Meaning |\n| --- | --- |\n| `policy.native: prefer` | Try native PDF text, then recover unread content. Default. |\n| `policy.native: require` | Require local extraction. Never send document content for OCR or vision transcription. Explicit figure enrichment is independent. Scanned/unread pages fail. Raster images are rejected. |\n| `policy.native: skip` | Read every nonblank PDF/image page visually. Text and Office files still parse locally. |\n| `policy.imageReading.order` | Ordered **allowed** backends: `[ocr, vision]`, `[vision, ocr]`, `[ocr]`, or `[vision]`. A single backend prohibits the other. |\n| `providers.ocr` / `providers.vision` | Exact model/provider IDs. Missing or non-vision pins fail; they never silently use a different provider. |\n\nOmitted providers use deployment parsing defaults. Vision otherwise uses the configured vision role, then an available vision-capable registered client. V2 does not inherit the workflow's text-generation `defaultModel` or the tenant's general text default.\n\nOn-prem administrators can configure defaults and enforce provider boundaries once:\n\n```yaml\n# eigenpal.config.yaml; models must also be configured as usual.\ndeployment:\n parsing:\n ocrProvider: onprem/paddle\n visionProvider: onprem/vision\n allowedProviders: [onprem/paddle, onprem/vision]\n```\n\n`allowedProviders` applies to provider overrides and figure enrichment, too. With no OCR, a configured allowed vision provider reads scans automatically. With neither capability, scans cannot be read; configure an approved OCR/vision endpoint. Eigenpal does not bundle a new local OCR service in this release.\n\nRecoverable provider outages use client retry budgets and may proceed to the next allowed backend. Authentication, authorization, cancellation, quota, and validation failures propagate. A sparse or empty OCR result can recover only unresolved pages through vision.\n\n## Output and evidence\n\n```yaml\noutput:\n textFormat: markdown\n nativeWhitespace: reading-order\n require: []\n```\n\n`textFormat` supports `markdown`, `plain`, `html`, and `djot`. OCR/vision Markdown is converted locally to the requested format. Use `nativeWhitespace: spatial` with `textFormat: plain` to preserve native PDF column spacing. Spatial whitespace is PDF-only and does not invent coordinates for OCR/vision output.\n\n`output.require` accepts `wordCoordinates` and `tables`. Every nonblank text page must provide the requested evidence. Vision transcription cannot satisfy these requirements. A native page lacking required evidence is eligible for OCR recovery. Table capability does not mean a table exists on every page.\n\nThe familiar `text`, `pages`, `document`, and `processingStrategy` fields remain available for downstream extraction, splitting, and review. V2 adds:\n\n- `parserVersion: \"2\"`.\n- `completeness.status`: `complete` or `partial`.\n- `completeness.unresolvedPageIndexes`: original 0-based page indices.\n- Per-page `status`: `complete`, `blank`, `no-text`, or `unresolved`.\n- Per-page `provenance`: source, provider/model when applicable, reason, actual text format, and available evidence capabilities.\n- Per-page warnings and native-text diagnostics.\n- `usage.ocrPagesProcessed` and `usage.visionPagesProcessed`.\n\nOriginal page order and indices are retained. Document-wide structured output is retained for fully native output or a complete result from one OCR call. There is no fabricated merged document graph for mixed backends; page-level evidence remains available.\n\nOCR selection, egress, and billing depend on provider capabilities: a provider may receive or process the whole PDF even when only some pages need recovery. Vision renders and sends selected pages. Provider calls and figure descriptions can incur credits.\n\n## Spreadsheet fidelity\n\nXLS and XLSX parse locally into one page per nonempty sheet. Cells retain addresses and their displayed text, formatted using recorded number formats and the workbook's 1900/1904 date system. Formulas use cached values and are never calculated. Empty declared trailing extent does not generate text.\n\nSet `output.includeCellMetadata: true` for ambiguous or mixed date/identifier columns. Each page adds `spreadsheet: {dateSystem, declaredRange, cells}` with raw/displayed values, storage types, formats, addresses, and formulas. The same evidence is annotated in page text, so downstream extraction using only `text` can still see it. A valid date-formatted serial also exposes `dateValue` without a timezone; Excel's fictitious 1900-02-29 is explicitly marked. This describes Excel formatting, not the value's business meaning.\n\nThe parser preserves identifiers and strings even under misleading headers. It does not infer dates from unformatted numbers, normalize names, or classify birth dates versus identifiers. Let the extraction model interpret source evidence and domain rules; flag conflicting or ambiguous evidence. For row objects from one selected sheet, use [`transform.xlsx-to-json`](/steps/transform/xlsx-to-json) with `valueMode: displayed` and `includeCellMetadata: true`, passing the full output to extraction.\n\n## Enrichment and advanced controls\n\n```yaml\nenrichment:\n figures:\n enabled: false\n # provider: onprem/vision\n # instructions: Describe charts and signatures.\n # reasoningEffort: low\nadvanced:\n cache: false\n allowPartial: false\n # languages: [en, de]\n vision:\n maxConcurrency: 3\n pagesPerBatch: 5\n renderScale: 2\n imageQuality: 85\n # instructions: Faithfully transcribe all visible text; do not summarize.\n # reasoningEffort: low\n```\n\nFigure descriptions are a separate opt-in vision pass and cannot run under native-only policy. Enrichment errors fail v2 instead of silently omitting a requested pass.\n\n`advanced.allowPartial: true` returns unresolved pages with explicit diagnostics. The default fails whenever a page remains unresolved. An empty provider response is never accepted as completed parsing.\n\n`advanced.cache: true` reuses only complete results. Cache identity includes v2 policy/version, file identity, settings, and resolved provider IDs. Cache hits do not incur new parsing usage. Cache JSON remains in tenant storage without automatic expiry.\n\n## Readiness and migration\n\n```bash\neigenpal workflow step-type get ai.parse-v2\neigenpal models parser-readiness --json\neigenpal models list --json\n```\n\nReadiness reports configured, deployment-approved image-reading capabilities. It does **not** probe worker binaries or live provider health. Before accepting customer traffic, run native, scanned, and mixed fixtures through the deployment. For the bundled headless `parse-document` workflow:\n\n```bash\nbun scripts/smoke/parse-v2.ts --base-url http://127.0.0.1:8080\n```\n\nThe smoke test sends only a generated native/scanned fixture and checks that both page values were recovered. Use `HEADLESS_API_TOKEN` for authenticated headless deployments.\n\nLegacy `ai.parse` keeps its existing behavior. Migration writes a new local workflow file and never changes or publishes the source:\n\n```bash\n# Keep deliberate native/OCR/vision restrictions.\neigenpal workflow migrate-parser workflow.yaml --policy preserve --out workflow-v2.yaml\n\n# Adopt native-first automatic OCR/vision recovery.\neigenpal workflow migrate-parser workflow.yaml --policy auto --out workflow-v2-auto.yaml\n```\n\nPreserving `native-or-ocr` preserves its OCR-only restriction: it still cannot use vision. Choose automatic policy to fix the OCR-absent/vision-available case. Migration reports broadened backend use, formatting changes, and document-wide `nativeText` behavior changes. Unknown settings require review rather than being silently dropped. The builder offers the same two reversible migration choices.\n\nValidate and compare representative documents before publishing, including downstream fields, evidence, page coverage, latency, and costs. V2 completeness checks can expose failures that legacy parsing previously accepted. Migration is not a byte-identical output promise.\n\nFigure enrichment is independent of text transcription policy and must be explicitly enabled. It may call vision even with `policy.native: require`; keep it disabled when all document processing must remain local. Requested enrichment failures fail the step.\n\n## Configuration reference\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"policy\" type=\"object\" required>\n<Expandable title=\"policy properties\">\n<ParamField path=\"native\" type=\"&quot;prefer&quot; | &quot;require&quot; | &quot;skip&quot;\" default=\"prefer\">\nPrefer local text extraction, require local text extraction with no image transcription, or skip native PDF extraction. Figure enrichment is independent.\n</ParamField>\n<ParamField path=\"imageReading\" type=\"object\" required>\n<Expandable title=\"imageReading properties\">\n<ParamField path=\"order\" type=\"array<&quot;ocr&quot; | &quot;vision&quot;>\" default=\"[&quot;ocr&quot;,&quot;vision&quot;]\">\nOrdered allowed backends. A single entry prohibits the other backend.\n</ParamField>\n</Expandable>\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"providers\" type=\"object\" required>\n<Expandable title=\"providers properties\">\n<ParamField path=\"ocr\" type=\"string\">\nExact configured OCR provider ID. Missing pins fail; they never resolve to another provider.\n</ParamField>\n<ParamField path=\"vision\" type=\"string\">\nExact configured vision provider ID. Otherwise uses the deployment parsing default or vision role.\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"output\" type=\"object\" required>\n<Expandable title=\"output properties\">\n<ParamField path=\"textFormat\" type=\"&quot;plain&quot; | &quot;markdown&quot; | &quot;html&quot; | &quot;djot&quot;\" default=\"markdown\">\n</ParamField>\n<ParamField path=\"includeCellMetadata\" type=\"boolean\" default=\"false\">\nInclude spreadsheet cell evidence in pages[].spreadsheet and annotate text for downstream extraction. Preserves raw/displayed values and workbook date system.\n</ParamField>\n<ParamField path=\"nativeWhitespace\" type=\"&quot;reading-order&quot; | &quot;spatial&quot;\" default=\"reading-order\">\nSpatial preserves native PDF column spacing. It does not promise OCR/vision coordinates.\n</ParamField>\n<ParamField path=\"require\" type=\"array<&quot;wordCoordinates&quot; | &quot;tables&quot;>\" default=\"[]\">\nRequired evidence capabilities on nonblank pages. Backends unable to satisfy them are rejected.\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"enrichment\" type=\"object\" required>\n<Expandable title=\"enrichment properties\">\n<ParamField path=\"figures\" type=\"object\" required>\n<Expandable title=\"figures properties\">\n<ParamField path=\"enabled\" type=\"boolean\" default=\"false\">\n</ParamField>\n<ParamField path=\"provider\" type=\"string\">\n</ParamField>\n<ParamField path=\"instructions\" type=\"string\">\n</ParamField>\n<ParamField path=\"reasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\n</ParamField>\n</Expandable>\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"advanced\" type=\"object\" required>\n<Expandable title=\"advanced properties\">\n<ParamField path=\"vision\" type=\"object\" required>\n<Expandable title=\"vision properties\">\n<ParamField path=\"maxConcurrency\" type=\"integer\" default=\"3\">\n</ParamField>\n<ParamField path=\"pagesPerBatch\" type=\"integer\" default=\"5\">\n</ParamField>\n<ParamField path=\"renderScale\" type=\"number\" default=\"2\">\n</ParamField>\n<ParamField path=\"imageQuality\" type=\"integer\" default=\"85\">\n</ParamField>\n<ParamField path=\"instructions\" type=\"string\">\nTranscription instructions, never document-specific extraction/schema instructions.\n</ParamField>\n<ParamField path=\"reasoningEffort\" type=\"&quot;none&quot; | &quot;minimal&quot; | &quot;low&quot; | &quot;medium&quot; | &quot;high&quot; | &quot;xhigh&quot; | &quot;max&quot;\">\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"languages\" type=\"array<string>\">\n</ParamField>\n<ParamField path=\"allowPartial\" type=\"boolean\" default=\"false\">\nReturn unresolved pages explicitly instead of failing. Default false.\n</ParamField>\n<ParamField path=\"cache\" type=\"boolean\" default=\"false\">\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"input\" type=\"string\" required>\nFile reference or template expression for the document\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output reference\n\n{/* GENERATED:OUTPUT START */}\n<ResponseField path=\"document\" type=\"object\" required>\n<Expandable title=\"document properties\">\n<ResponseField path=\"filename\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"mimeType\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"size\" type=\"number\" required>\nFile size in bytes\n</ResponseField>\n<ResponseField path=\"storageRef\" type=\"string\">\nStorage reference for the original file\n</ResponseField>\n<ResponseField path=\"renderedPdfRef\" type=\"string\">\nStorage key of the PDF an office input was rendered to. Page word boxes are measured on this PDF.\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"usage\" type=\"object\" required>\n<Expandable title=\"usage properties\">\n<ResponseField path=\"pageCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"processingTimeMs\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"ocrPagesProcessed\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionPagesProcessed\" type=\"integer\" required>\n</ResponseField>\n<ResponseField path=\"visionPromptTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"visionCompletionTokens\" type=\"integer\">\n</ResponseField>\n<ResponseField path=\"cached\" type=\"boolean\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pages\" type=\"array<object>\" required>\n<Expandable title=\"pages properties\">\n<ResponseField path=\"spreadsheet\" type=\"object\">\nOpt-in original spreadsheet cell evidence\n<Expandable title=\"spreadsheet properties\">\n<ResponseField path=\"dateSystem\" type=\"&quot;1900&quot; | &quot;1904&quot;\" required>\n</ResponseField>\n<ResponseField path=\"declaredRange\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"pageIndex\" type=\"number\" required>\n0-based page index\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nExtracted page text (markdown/HTML/plain, or spatial layout text)\n</ResponseField>\n<ResponseField path=\"pageName\" type=\"string\">\nPage/sheet name (e.g., Excel sheet name)\n</ResponseField>\n<ResponseField path=\"layoutElements\" type=\"array<object>\">\nSemantic layout elements in reading order\n<Expandable title=\"layoutElements properties\">\n<ResponseField path=\"type\" type=\"&quot;paragraph&quot; | &quot;title&quot; | &quot;sectionHeading&quot; | &quot;pageHeader&quot; | &quot;pageFooter&quot; | &quot;pageNumber&quot; | &quot;footnote&quot; | &quot;table&quot; | &quot;figure&quot; | &quot;formulaBlock&quot;\" required>\n</ResponseField>\n<ResponseField path=\"content\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"table\" type=\"object\">\n</ResponseField>\n<ResponseField path=\"caption\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"figureId\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"words\" type=\"array<object>\">\nWord-level positions\n<Expandable title=\"words properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"lines\" type=\"array<object>\">\nLine-level positions\n<Expandable title=\"lines properties\">\n<ResponseField path=\"text\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"tables\" type=\"array<object>\">\nExtracted tables\n<Expandable title=\"tables properties\">\n<ResponseField path=\"cells\" type=\"array<object>\" required>\n</ResponseField>\n<ResponseField path=\"rowCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"columnCount\" type=\"number\" required>\n</ResponseField>\n<ResponseField path=\"boundingRegion\" type=\"object\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"width\" type=\"number\">\nPage width\n</ResponseField>\n<ResponseField path=\"height\" type=\"number\">\nPage height\n</ResponseField>\n<ResponseField path=\"unit\" type=\"&quot;pixel&quot; | &quot;inch&quot; | &quot;point&quot; | &quot;normalized&quot;\">\nUnit for width/height and bounding regions\n</ResponseField>\n<ResponseField path=\"confidence\" type=\"number\">\nOverall page confidence\n</ResponseField>\n<ResponseField path=\"nativeTextQuality\" type=\"object\">\nPer-page diagnosis of native-extracted text. Reports objectively detectable anomalies (empty, U+FFFD, forbidden controls, unassigned/noncharacter code points, heavy private-use). Does not certify semantic correctness, valid-looking wrong mappings and literal \"?\" cannot be distinguished from legitimate text.\n<Expandable title=\"nativeTextQuality properties\">\n<ResponseField path=\"status\" type=\"&quot;clean&quot; | &quot;empty&quot; | &quot;suspect&quot;\" required>\n</ResponseField>\n<ResponseField path=\"reasons\" type=\"array<&quot;empty&quot; | &quot;replacement-character&quot; | &quot;lone-surrogate&quot; | &quot;forbidden-control&quot; | &quot;unassigned&quot; | &quot;noncharacter&quot; | &quot;private-use&quot;>\" required>\n</ResponseField>\n<ResponseField path=\"counts\" type=\"object\" required>\n</ResponseField>\n<ResponseField path=\"profile\" type=\"object\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"provenance\" type=\"object\" required>\n<Expandable title=\"provenance properties\">\n<ResponseField path=\"source\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot;\" required>\n</ResponseField>\n<ResponseField path=\"provider\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"model\" type=\"string\">\n</ResponseField>\n<ResponseField path=\"reason\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"textFormat\" type=\"&quot;plain&quot; | &quot;markdown&quot; | &quot;html&quot; | &quot;djot&quot;\" required>\n</ResponseField>\n<ResponseField path=\"capabilities\" type=\"array<&quot;wordCoordinates&quot; | &quot;tables&quot;>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"status\" type=\"&quot;complete&quot; | &quot;blank&quot; | &quot;no-text&quot; | &quot;unresolved&quot;\" required>\n</ResponseField>\n<ResponseField path=\"warnings\" type=\"array<string>\" default=\"[]\">\n</ResponseField>\n</Expandable>\n</ResponseField>\n<ResponseField path=\"text\" type=\"string\" required>\nCombined text from all pages\n</ResponseField>\n<ResponseField path=\"parserType\" type=\"&quot;plaintext&quot; | &quot;office&quot; | &quot;llm-vision&quot; | &quot;ocr&quot;\" required>\n</ResponseField>\n<ResponseField path=\"parserVersion\" type=\"string\" required>\n</ResponseField>\n<ResponseField path=\"model\" type=\"string\">\nModel used (for LLM/OCR parsers)\n</ResponseField>\n<ResponseField path=\"processingStrategy\" type=\"&quot;native&quot; | &quot;ocr&quot; | &quot;vision&quot; | &quot;hybrid&quot;\">\nHow this result was produced: `native` (local PDF text only), `ocr`, `vision`, or `hybrid` (native pages merged with OCR on fallback pages).\n</ResponseField>\n<ResponseField path=\"structured\" type=\"record<string, unknown>\">\nCanonical structured document with ordered blocks, regions, bounding boxes, tables, figures, and chunks when supported by the parser\n</ResponseField>\n<ResponseField path=\"completeness\" type=\"object\" required>\n<Expandable title=\"completeness properties\">\n<ResponseField path=\"status\" type=\"&quot;complete&quot; | &quot;partial&quot;\" required>\n</ResponseField>\n<ResponseField path=\"unresolvedPageIndexes\" type=\"array<integer>\" required>\n</ResponseField>\n</Expandable>\n</ResponseField>\n{/* GENERATED:OUTPUT END */}\n"
2362
2383
  },
2363
2384
  {
2364
2385
  "topic": "steps/ai/search-files",
@@ -2407,7 +2428,7 @@
2407
2428
  "title": "Human Review",
2408
2429
  "description": "Pause the run for selective field confirmation or correction, then continue with the reviewed data.",
2409
2430
  "source": "public",
2410
- "content": "---\ntitle: \"Human Review\"\ndescription: \"Pause the run for selective field confirmation or correction, then continue with the reviewed data.\"\n---\n\n`control.human_review`: Pause the run for selective field confirmation or correction, then continue with the reviewed data.\n\nUse this step after extraction or transformation when a human must confirm or\ncorrect specific fields before the run continues. Place it as a **top-level\nsequential step** only — nested placement inside other control containers is\nrejected at publish time.\n\n```yaml\n- name: review-invoice\n type: control.human_review\n with:\n data: '{{ steps.extract.output }}'\n metadataFrom: ai.extract\n instructions: Confirm vendor and total before posting.\n selection:\n mode: confidence\n threshold: medium\n missingConfidence: review\n fields:\n /vendor:\n review: always\n /total:\n threshold: high\n files:\n includeRunInputs: true\n```\n\nWhen `metadataFrom: ai.extract` is set and `data` references the whole extract\noutput, the step strips the reserved `_grounding` key, derives categorical\nconfidence (`low`, `medium`, `high`) per field from nested dotted-path\ngrounding, and reuses the extract schema when `schema` is omitted.\n\nWhen `data` is exactly `{{ steps.<extract-step>.output }}`, Eigenpal also\nsnapshots any lineage and ParsedDocument sidecars the extract step produced.\nStudio loads them for the review workspace: source PDFs/images beside the\nstructured output, spatial citation highlights on supported fields, and bbox\noverlays when a canonical ParsedDocument is available. Missing or unreadable\nsidecars are skipped — review still works from `_grounding` alone. Review\ndecisions are not yet written back into lineage.\n\nThe human review API includes optional `lineage` and `parsedDocument` on task\ndetail when sidecars resolve; they are API-only context, not workflow output.\n\n**Selection modes:** `confidence` reviews fields below a threshold;\n`explicit` reviews paths matched by include/exclude; `all` reviews every scalar\nleaf. Thresholds accept numeric `0`–`1` or categorical `low|medium|high`.\nPer-path overrides live under `selection.fields` with `review:\nalways|never|skip` and optional per-field `threshold`.\n\n**Selectors:** pointers address scalar leaves, not containers. For an array of\nstrings named `reasons`, use `/reasons/*` (all items) or `/reasons/0` (one item),\nnot `/reasons`. For nested objects, select a leaf such as `/client/name`.\n`include`, `exclude` and `selection.fields` follow the same rule. Validation\nrejects selectors that a known review schema proves cannot reach a scalar,\nincluding schemas inferred through `metadataFrom: ai.extract`. Dynamic or\nunresolved schemas are checked at runtime; even a valid array selector can\nmatch no fields when that array is empty.\n\n**Evaluations:** evaluation runs always simulate review and never pause. Assert\nrouting and simulated edits with `review` fixtures in dataset `meta.json` — see\n[Build a dataset](/guides/build-a-dataset).\n\n## Configuration\n\nConfiguration goes inside the step's `with:` block.\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"data\" type=\"string | record<string, unknown> | array<unknown>\" required>\nStructured data or a template expression resolving to an object or array\n</ParamField>\n<ParamField path=\"schema\" type=\"record<string, unknown>\">\nOptional JSON Schema for validating edits and exposing downstream autocomplete. When omitted with metadataFrom: ai.extract and a direct whole-output data expression, the extract step schema is reused.\n</ParamField>\n<ParamField path=\"metadataFrom\" type=\"&quot;ai.extract&quot;\">\nProducer adapter. `ai.extract` derives categorical field confidence from `_grounding`, copies valid numeric grounding scores into fieldMetadata.display.score, and strips that reserved key from review data. Grounding is not stripped unless this is set.\n</ParamField>\n<ParamField path=\"fieldMetadata\" type=\"record<string, object>\" default=\"{}\">\nRFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias.\n</ParamField>\n<ParamField path=\"selection\" type=\"object\" required>\nField selection policy resolved once when the task is created\n</ParamField>\n<ParamField path=\"files\" type=\"object\" default=\"{&quot;includeRunInputs&quot;:true,&quot;attachments&quot;:[]}\">\nRun input files and optional current-run attachments for reviewers\n<Expandable title=\"files properties\">\n<ParamField path=\"includeRunInputs\" type=\"boolean\" default=\"true\">\nAttach every authorized run input file to the review task\n</ParamField>\n<ParamField path=\"attachments\" type=\"array<string>\" default=\"[]\">\nAdditional current-run file or artifact template expressions\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"instructions\" type=\"string\">\nFree-form guidance shown above the review workspace\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output\n\n{/* GENERATED:OUTPUT START */}\nReturns `unknown`. The complete reviewed data in the same object or array shape as the input.\n{/* GENERATED:OUTPUT END */}\n"
2431
+ "content": "---\ntitle: \"Human Review\"\ndescription: \"Pause the run for selective field confirmation or correction, then continue with the reviewed data.\"\n---\n\n`control.human_review`: Pause the run for selective field confirmation or correction, then continue with the reviewed data.\n\nUse this step after extraction or transformation when a human must confirm or\ncorrect specific fields before the run continues. Place it as a **top-level\nsequential step** only — nested placement inside other control containers is\nrejected at publish time.\n\n```yaml\n- name: review-invoice\n type: control.human_review\n with:\n data: '{{ steps.extract.output }}'\n metadataFrom: ai.extract\n instructions: Confirm vendor and total before posting.\n selection:\n mode: confidence\n threshold: medium\n missingConfidence: review\n fields:\n /vendor:\n review: always\n /total:\n threshold: high\n files:\n includeRunInputs: true\n```\n\nWhen `metadataFrom: ai.extract` is set and `data` references the whole extract\noutput, the step strips the reserved `_grounding` key, derives categorical\nconfidence (`low`, `medium`, `high`) per field from nested dotted-path\ngrounding, and reuses the extract schema when `schema` is omitted.\n\nWhen `data` is exactly `{{ steps.<extract-step>.output }}`, Eigenpal also\nsnapshots any lineage and ParsedDocument sidecars the extract step produced.\nStudio loads them for the review workspace: source PDFs/images beside the\nstructured output, spatial citation highlights on supported fields, and bbox\noverlays when a canonical ParsedDocument is available. Missing or unreadable\nsidecars are skipped — review still works from `_grounding` alone. Review\ndecisions are not yet written back into lineage.\n\nWhen a `transform.script` sits between the extract and the review (`ai.extract`\nthen `transform.script` then `control.human_review`), the review still shows\nfield boxes if the script keeps the extract's field paths: `data` is\n`{{ steps.<script-step>.output }}`, the script receives the whole\n`{{ steps.<extract-step>.output }}` as one of its `inputs`, and every reviewed\nfield path also exists in that extract output. Correcting values is fine;\nrenaming or moving fields is not. When the script reshapes the data, name the\nextract step explicitly with `lineageFrom`. Boxes then appear on the reviewed\nfields whose paths still match the extract output.\n\n```yaml\n- name: normalize\n type: transform.script\n with:\n inputs:\n extracted: '{{ steps.extract.output }}'\n function: |\n function script(extracted: { vendor: string; total: number }): { supplier: { name: string }; total: number } {\n return { supplier: { name: extracted.vendor.trim() }, total: extracted.total };\n }\n\n- name: review-invoice\n type: control.human_review\n with:\n data: '{{ steps.normalize.output }}'\n lineageFrom: extract\n selection:\n mode: all\n```\n\nThe human review API includes optional `lineage` and `parsedDocument` on task\ndetail when sidecars resolve; they are API-only context, not workflow output.\n\n**Selection modes:** `confidence` reviews fields below a threshold;\n`explicit` reviews paths matched by include/exclude; `all` reviews every scalar\nleaf. Thresholds accept numeric `0`–`1` or categorical `low|medium|high`.\nPer-path overrides live under `selection.fields` with `review:\nalways|never|skip` and optional per-field `threshold`.\n\n**Selectors:** pointers address scalar leaves, not containers. For an array of\nstrings named `reasons`, use `/reasons/*` (all items) or `/reasons/0` (one item),\nnot `/reasons`. For nested objects, select a leaf such as `/client/name`.\n`include`, `exclude` and `selection.fields` follow the same rule. Validation\nrejects selectors that a known review schema proves cannot reach a scalar,\nincluding schemas inferred through `metadataFrom: ai.extract`. Dynamic or\nunresolved schemas are checked at runtime; even a valid array selector can\nmatch no fields when that array is empty.\n\n**Evaluations:** evaluation runs always simulate review and never pause. Assert\nrouting and simulated edits with `review` fixtures in dataset `meta.json` — see\n[Build a dataset](/guides/build-a-dataset).\n\n## Configuration\n\nConfiguration goes inside the step's `with:` block.\n\n{/* GENERATED:CONFIG START */}\n<ParamField path=\"data\" type=\"string | record<string, unknown> | array<unknown>\" required>\nStructured data or a template expression resolving to an object or array\n</ParamField>\n<ParamField path=\"schema\" type=\"record<string, unknown>\">\nOptional JSON Schema for validating edits and exposing downstream autocomplete. When omitted with metadataFrom: ai.extract and a direct whole-output data expression, the extract step schema is reused.\n</ParamField>\n<ParamField path=\"metadataFrom\" type=\"&quot;ai.extract&quot;\">\nProducer adapter. `ai.extract` derives categorical field confidence from `_grounding`, copies valid numeric grounding scores into fieldMetadata.display.score, and strips that reserved key from review data. Grounding is not stripped unless this is set.\n</ParamField>\n<ParamField path=\"lineageFrom\" type=\"string\">\nName of the ai.extract step whose source lineage draws field boxes in the review. Needed only when data passes through a step that changes field paths. Without it, boxes come from the step in a direct `&#123;&#123; steps.&lt;name>.output }}` data reference, or, when that step is a transform.script, from the one whole step output it received whose field paths it kept.\n</ParamField>\n<ParamField path=\"fieldMetadata\" type=\"record<string, object>\" default=\"{}\">\nRFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias.\n</ParamField>\n<ParamField path=\"selection\" type=\"object\" required>\nField selection policy resolved once when the task is created\n</ParamField>\n<ParamField path=\"files\" type=\"object\" default=\"{&quot;includeRunInputs&quot;:true,&quot;attachments&quot;:[]}\">\nRun input files and optional current-run attachments for reviewers\n<Expandable title=\"files properties\">\n<ParamField path=\"includeRunInputs\" type=\"boolean\" default=\"true\">\nAttach every authorized run input file to the review task\n</ParamField>\n<ParamField path=\"attachments\" type=\"array<string>\" default=\"[]\">\nAdditional current-run file or artifact template expressions\n</ParamField>\n</Expandable>\n</ParamField>\n<ParamField path=\"instructions\" type=\"string\">\nFree-form guidance shown above the review workspace\n</ParamField>\n{/* GENERATED:CONFIG END */}\n\n## Output\n\n{/* GENERATED:OUTPUT START */}\nReturns `unknown`. The complete reviewed data in the same object or array shape as the input.\n{/* GENERATED:OUTPUT END */}\n"
2411
2432
  },
2412
2433
  {
2413
2434
  "topic": "steps/control/if",