@eigenpal/cli 0.4.6 → 0.4.8

package/dist/skill/SKILL.md

@@ -227,6 +227,70 @@ eigenpal workflow experiment status <workflow-id> <batch-id>
 eigenpal workflow experiment results <workflow-id> <batch-id> --format csv --out r.csv
 ```
 
+### Long documents — split → chunk → extract
+
+The canonical chain when a document is too long for one `ai.extract` call (loan
+contracts, SaaS agreements, RFPs). Each step preserves source `pageIndex` so
+the final extracted fields trace back to the originating page.
+
+```yaml
+- name: parse
+  type: ai.parse
+  with: { input: "{{ input.document }}" }
+
+# LLM-driven section split — each split carries page_range + confidence
+- name: sections
+  type: ai.split
+  with:
+    input: "{{ steps.parse.output }}"
+    sections:
+      - { name: header,    description: "Title page + parties block" }
+      - { name: priloha2,  description: "Príloha 2 odkladacie podmienky", required: true }
+
+# Optional: chunk a long section before extraction (regex-anchored, keeps page refs)
+- name: chunks
+  type: transform.text-chunker
+  with:
+    input: "{{ steps.sections.output.splits[1] }}"   # priloha2 split
+    maxChars: 8000
+    overlap: 500
+    splitOn: ['(?:^|\\n)\\s*\\d+\\.\\d+\\s+', '\\n\\n+', '\\n']
+
+# Deterministic field extraction — counterpart to ai.extract; matches carry _evidence.pageIndex
+- name: header_fields
+  type: transform.regex-extract
+  with:
+    input: "{{ steps.parse.output }}"
+    fields:
+      contractNumber:
+        pattern: 'č\\.\\s*(\\d{1,4}/\\w+/\\d{4})'
+        normalize: strip-spaces
+      signatureDate:
+        pattern: 'uzavretá\\s+dňa\\s+(\\d{1,2})\\.(\\d{1,2})\\.(\\d{4})'
+        format: iso-date
+      currency:
+        pattern: '\\b(EUR|USD|CZK)\\b'
+        default: EUR
+    flags: i
+```
+
+Discovery from the CLI:
+
+```bash
+eigenpal workflow step-type get ai.split | jq '.configSchema.properties'
+eigenpal workflow step-type get transform.text-chunker | jq '.configSchema.properties'
+eigenpal workflow step-type get transform.regex-extract | jq '.configSchema.properties'
+```
+
+Pick the right operator for the job:
+
+| Goal                                     | Operator                  |
+| ---------------------------------------- | ------------------------- |
+| Extract structured data with an LLM      | `ai.extract`              |
+| Pull fields by regex (no LLM)            | `transform.regex-extract` |
+| Split a doc into named sections (LLM)    | `ai.split`                |
+| Cut text by regex boundary + overlap     | `transform.text-chunker`  |
+
 ### Debug a failing workflow
 
 ```bash

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

@@ -35,6 +35,7 @@ Manage workflows: push, pull, run, evaluate.
   - [`eigenpal workflow experiment list [options] <workflow-id>`](#eigenpal-workflow-experiment-list-options-workflow-id)
   - [`eigenpal workflow experiment run [options] <workflow-id>`](#eigenpal-workflow-experiment-run-options-workflow-id)
   - [`eigenpal workflow experiment status [options] <workflow-id> <batchId>`](#eigenpal-workflow-experiment-status-options-workflow-id-batchid)
+  - [`eigenpal workflow experiment cancel [options] <workflow-id> <batchId>`](#eigenpal-workflow-experiment-cancel-options-workflow-id-batchid)
   - [`eigenpal workflow experiment results [options] <workflow-id> [batchId]`](#eigenpal-workflow-experiment-results-options-workflow-id-batchid)
   - [`eigenpal workflow experiment compare [options] <batchIdA> <batchIdB>`](#eigenpal-workflow-experiment-compare-options-batchida-batchidb)
   - [`eigenpal workflow execution run [options] <workflow-id> [examples...]`](#eigenpal-workflow-execution-run-options-workflow-id-examples)
@@ -76,6 +77,7 @@ workflow
 │   ├── list <workflow-id>
 │   ├── run <workflow-id>
 │   ├── status <workflow-id> <batchId>
+│   ├── cancel <workflow-id> <batchId>
 │   ├── results <workflow-id> [batchId]
 │   └── compare <batchIdA> <batchIdB>
 ├── execution
@@ -140,6 +142,7 @@ workflow
 | `eigenpal workflow experiment list [options] <workflow-id>`              | List executions for the workflow, newest first.    |
 | `eigenpal workflow experiment run [options] <workflow-id>`               | Start a batch eval against the workflow's dataset. |
 | `eigenpal workflow experiment status [options] <workflow-id> <batchId>`  | Aggregate progress for a batch by `batchId`.       |
+| `eigenpal workflow experiment cancel [options] <workflow-id> <batchId>`  | Cancel every execution in a batch. Idempotent.     |
 | `eigenpal workflow experiment results [options] <workflow-id> [batchId]` | Download eval results in CSV or JSON.              |
 | `eigenpal workflow experiment compare [options] <batchIdA> <batchIdB>`   | Diff eval scores between two experiment batches.   |
 
@@ -177,9 +180,9 @@ workflow
 
 ### Step
 
-| Command                                        | Description                                                                                                                                                                                                      |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eigenpal workflow step exec [options] <type>` | Run one step locally with sample inputs and print its output as JSON. <type> is any value from `workflow step-type list`; only types with a local runner actually execute (today: transform.script, ai.extract). |
+| Command                                        | Description                                                                                                                                       |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eigenpal workflow step exec [options] <type>` | DISABLED — local mimic runners removed pending server-side redesign (EIG-104). Use `workflow execution run` or `workflow experiment run` instead. |
 
 ## Details
 
@@ -505,13 +508,33 @@ Aggregate progress for a batch by `batchId`.
 
 ### Options
 
-| Flag                   | Required | Default | Description                                                                                          |
-| ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------- |
-| `--watch`              | no       | `false` | Poll until every execution reaches a terminal state (completed/failed/cancelled/rejected), then exit |
-| `--interval <seconds>` | no       | `5`     | Poll interval in seconds when --watch is set (default 5)                                             |
-| `--max-wait <seconds>` | no       | `1800`  | Hard ceiling for --watch in seconds (default 1800 = 30 min)                                          |
-| `--base-url <url>`     | no       |         | Server base URL                                                                                      |
-| `--json`               | no       |         | Output the raw server response as JSON                                                               |
+| Flag                   | Required | Default | Description                                                                                                            |
+| ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `--watch`              | no       | `false` | Poll until every execution reaches a terminal state (completed/failed/cancelled/rejected), then exit                   |
+| `--interval <seconds>` | no       | `5`     | Poll interval in seconds when --watch is set (default 5)                                                               |
+| `--max-wait <seconds>` | no       | `1800`  | Hard ceiling for --watch in seconds (default 1800 = 30 min)                                                            |
+| `--include <kinds>`    | no       | `""`    | Comma-separated extras to attach when --watch terminates: payload (full per-execution snapshot, can be hundreds of KB) |
+| `--base-url <url>`     | no       |         | Server base URL                                                                                                        |
+| `--json`               | no       |         | Output the raw server response as JSON                                                                                 |
+
+### `eigenpal workflow experiment cancel [options] <workflow-id> <batchId>`
+
+Cancel every execution in a batch. Idempotent.
+
+### Arguments
+
+| Name          | Required | Variadic | Description |
+| ------------- | -------- | -------- | ----------- |
+| `workflow-id` | yes      | no       |             |
+| `batchId`     | yes      | no       |             |
+
+### Options
+
+| Flag               | Required | Default | Description                                                           |
+| ------------------ | -------- | ------- | --------------------------------------------------------------------- |
+| `--yes`            | no       |         | Required for non-TTY shells (CI, pipes). Acts immediately, no prompt. |
+| `--base-url <url>` | no       |         | Server base URL                                                       |
+| `--json`           | no       |         | Output the raw server response as JSON                                |
 
 ### `eigenpal workflow experiment results [options] <workflow-id> [batchId]`
 
@@ -584,12 +607,12 @@ Fetch a single execution payload. Optionally narrow to one step.
 
 ### Options
 
-| Flag                | Required | Default                         | Description                                           |
-| ------------------- | -------- | ------------------------------- | ----------------------------------------------------- |
-| `--step <name>`     | no       |                                 | Show only this step (or comma-separated list)         |
-| `--include <kinds>` | no       | `"input,output,error,duration"` | Comma-separated subset of input,output,error,duration |
-| `--base-url <url>`  | no       |                                 | Server base URL                                       |
-| `--json`            | no       |                                 | Output the raw server response as JSON                |
+| Flag                | Required | Default                         | Description                                                                                                                                                                                                      |
+| ------------------- | -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--step <name>`     | no       |                                 | Show only this step (or comma-separated list)                                                                                                                                                                    |
+| `--include <kinds>` | no       | `"input,output,error,duration"` | Comma-separated subset of input,output,error,duration. `input` projects the resolved templated config (= what the processor actually received). `inputRef` returns the minimal predecessor-id reference instead. |
+| `--base-url <url>`  | no       |                                 | Server base URL                                                                                                                                                                                                  |
+| `--json`            | no       |                                 | Output the raw server response as JSON                                                                                                                                                                           |
 
 ### `eigenpal workflow execution list [options] <workflow-id>`
 
@@ -763,7 +786,7 @@ Fetch the JSON Schema for one evaluator type. Pipe through `jq` to inspect speci
 
 ### `eigenpal workflow step exec [options] <type>`
 
-Run one step locally with sample inputs and print its output as JSON. <type> is any value from `workflow step-type list`; only types with a local runner actually execute (today: transform.script, ai.extract).
+DISABLED — local mimic runners removed pending server-side redesign (EIG-104). Use `workflow execution run` or `workflow experiment run` instead.
 
 ### Arguments
 
@@ -773,11 +796,9 @@ Run one step locally with sample inputs and print its output as JSON. <type> is
 
 ### Options
 
-| Flag                      | Required | Default | Description                                                                                                                                                                                                             |
-| ------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--config-json <json>`    | no       |         | Full step config as a JSON literal. Mutually exclusive with --config-file.                                                                                                                                              |
-| `--config-file <path\|->` | no       |         | Full step config from a JSON file (or `-` for stdin). Mutually exclusive with --config-json.                                                                                                                            |
-| `--inputs <k=v...>`       | no       | `[]`    | Repeatable. Value can be `@path` (file contents, JSON-parsed when applicable) or a literal string. Merges into the config `inputs` map for transform.script; provides the `input` for ai.extract when set as `input=…`. |
-| `--output-schema <path>`  | no       |         | Optional JSON Schema. Validates the step output; defaults to the step type’s built-in `outputSchema` from STEP_SCHEMAS when omitted.                                                                                    |
-| `--timeout-ms <n>`        | no       |         | Override transform.script wall-clock cap (default 5000)                                                                                                                                                                 |
-| `--memory-mb <n>`         | no       |         | Override transform.script heap cap in MB (default 10)                                                                                                                                                                   |
+| Flag                     | Required | Default | Description                            |
+| ------------------------ | -------- | ------- | -------------------------------------- |
+| `--config-json <json>`   | no       |         | (unused; kept for back-compat parsing) |
+| `--config-file <path>`   | no       |         | (unused)                               |
+| `--inputs <pairs...>`    | no       |         | (unused)                               |
+| `--output-schema <path>` | no       |         | (unused)                               |

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

@@ -1,164 +1,62 @@
-# Run one step locally — `workflow step exec`
+# `workflow step exec` — currently disabled (EIG-104)
 
-Tightest iteration loop in the CLI. One step, no server, no queue, no
-DAG. Milliseconds per run. Use this when you're tweaking a single
-step's logic; use `workflow execution run` when you need the whole
-workflow.
+> **Status: disabled.** The local-runner implementation was removed in
+> the ai.split branch (EIG-102). It mimicked production via a CLI-side
+> QuickJS sandbox (`transform.script`) and direct OpenAI SDK calls
+> (`ai.extract`), which diverged from the worker's behavior (no
+> retries, no tracing, no credit metering, no tenant-default LLM, no
+> strict-mode response_format) and assumed shell env state
+> (`WORKER_LLM_*`) that real CLI users — who authenticate via
+> `EIGENPAL_API_KEY` — don't have.
+>
+> Calling `eigenpal workflow step exec <type>` today exits 2 with a
+> redirect message. The server-side replacement is tracked in EIG-104:
+> a thin `POST /api/v1/workflows/step-exec` endpoint that runs the same
+> code path executions take.
 
-```bash
-eigenpal workflow step exec <type> [flags]
-```
-
-`<type>` is any value from `eigenpal workflow step-type list`. Only
-some types have a local runner today (table below). The rest exit 2
-with a "not yet supported locally" message — they still need the
-server.
-
-## What runs locally today
-
-| Step type | Runner | Notes |
-| --- | --- | --- |
-| `transform.script` | QuickJS sandbox in-process | Same sandbox as prod. TDZ traps and timeout / memory limits reproduce here. |
-| `ai.extract` | OpenAI SDK | Reads `WORKER_LLM_API_KEY` (or `OPENAI_API_KEY` for openai/openai-compatible providers) from env. Real network call. |
-| anything else | — | Exits 2 with "isn't yet supported by 'workflow step exec' locally". |
-
-If the runner you need isn't here yet, fall back to `workflow execution run`
-on the server (slower loop, but covers every step type).
+## What to use instead
 
-## Inputs — `--inputs k=v`
-
-Repeatable. Three value forms:
+Until EIG-104 lands, single-step iteration goes through the queue:
 
 ```bash
---inputs limit=10                # inline literal (string; numeric strings stay strings)
---inputs items=@items.json       # file contents (JSON-parsed if valid; raw text otherwise)
---inputs payload=@-              # stdin (the `@` prefix is required; bare `-` is a literal)
-```
-
-For `transform.script`, every `--inputs k=v` becomes a top-level
-binding in the sandbox (so `k` is referenced as `k` inside the code,
-mirroring runtime semantics — including TDZ traps for `const x = x || []`).
+# Run the whole workflow once with a specific example.
+eigenpal workflow execution run <workflow-id>
 
-For `ai.extract`, `--inputs input=…` is the document text.
+# Or iterate on one example via the experiment surface.
+eigenpal workflow experiment run <workflow-id> --example-id <name>
 
-## Config — `--config-json` or `--config-file`
-
-Mutually exclusive. The shape is whatever the step type's `with:` block
-accepts (see `eigenpal workflow step-type get <type>`).
-
-```bash
---config-json '{"code":"return items.reduce((s,i)=>s+i.v,0)"}'
---config-file ./step-config.json
---config-file -                  # config from stdin (e.g. piped from `workflow pull`)
+# Watch progress without dumping the full per-execution payload.
+eigenpal workflow experiment status <workflow-id> <batchId> --watch
 ```
 
-## Output
+For `--example-id`, the human slug works too (`ex-01-koifer-97zf`),
+not just the `evx_…` id — added as part of the same iteration.
 
-Goes to **stdout as JSON**. Status messages go to stderr — pipe stdout
-into `jq` cleanly:
+To inspect what a step actually produced (input / output / resolved
+config), use:
 
 ```bash
-eigenpal workflow step exec transform.script --config-file cfg.json --inputs items=@arr.json | jq '.'
+eigenpal workflow execution get <executionId> --json --include input,output,config
 ```
 
-## Output schema validation — `--output-schema`
+The server returns `inputData` / `outputData` / `resolvedConfig` per
+step on `?includeSteps=true`; the CLI projects them under shorter
+names (`input` / `output` / `config`).
 
-Optional. Pass a JSON Schema file:
-
-```bash
---output-schema ./expected-schema.json
-```
-
-When omitted, the CLI falls back to the step type's built-in
-`outputSchema` from `STEP_SCHEMAS` — so even without the flag, output
-shape gets checked.
-
-A violation **exits 2** with a machine-readable envelope on stderr:
-
-```json
-{ "code": "output_schema_violation", "issues": [
-  { "field": "/total", "message": "must be number" }
-]}
-```
-
-`field` is the JSON Pointer to the offending value (Ajv's `instancePath`,
-remapped to `field` for stability) or `<root>` if the whole output is
-wrong. Agents can parse this directly — no text scraping.
-
-## Resource limits (transform.script only)
-
-```bash
---timeout-ms 10000      # default 5000 (5 s wall clock)
---memory-mb 25          # default 10 MB heap
-```
-
-Use these when iterating on a memory-heavy reducer. They override the
-config's `timeout` / `memoryLimit` fields just for this run.
-
-## Worked examples
-
-### Tweak a JS reducer until tests pass
-
-Put the config in a file so the JS doesn't need escaping:
-
-```bash
-cat > cfg.json <<'EOF'
-{ "code": "return items.reduce((sum, i) => sum + i.value, 0)" }
-EOF
-echo '[{"value":1},{"value":2},{"value":3}]' > items.json
-
-eigenpal workflow step exec transform.script --config-file cfg.json --inputs items=@items.json
-# 6
-```
-
-For a one-liner without a config file, `--config-json '{"code":"..."}'`
-works too — but mind the shell escaping.
-
-### Run an extract once with sample text
-
-```bash
-cat > extract.json <<'EOF'
-{
-  "prompt": "Extract the invoice total as a number.",
-  "schema": { "type": "object", "properties": { "total": { "type": "number" } } }
-}
-EOF
-
-eigenpal workflow step exec ai.extract \
-  --config-file extract.json \
-  --inputs input=@invoice.txt
-# {"total": 1234.56}
-```
-
-### Pipe config straight from a workflow YAML
-
-When you've already pushed a workflow and want to re-run one of its
-steps locally:
-
-```bash
-eigenpal workflow pull wf_abc > workflow.yaml
-jq '.steps[] | select(.name == "extract") | .with' workflow.yaml \
-  | eigenpal workflow step exec ai.extract --config-file - --inputs input=@invoice.txt
-```
-
-## Exit codes
+## Exit codes (current placeholder)
 
 | Code | When |
 | --- | --- |
-| 0 | Step ran; output validated. |
-| 1 | Runtime crash (sandbox blew up; `ai.extract` network failure; unexpected exception). |
-| 2 | Misuse OR `output_schema_violation` (envelope on stderr) OR unknown / unsupported step type. |
+| 2 | Always — the command is disabled and redirects to `workflow execution run` / `experiment run`. |
 
-Exit 2 is always recoverable — fix your input / config / schema and
-re-run. Exit 1 means something is broken upstream (network, runtime,
-your code).
+## When this comes back
 
-## Discovery
+When EIG-104 lands, this page will document the server-routed shape:
 
-```bash
-eigenpal workflow step-type list              # all registered types
-eigenpal workflow step-type get <type>        # config + output schema
-```
+- `--inputs k=v` for binding values
+- `--config-json` / `--config-file` for the `with:` block
+- `--output-schema` for caller-supplied output validation
+- Streaming output JSON from the same engine that runs production
+- Same `output_schema_violation` envelope on stderr, exit 2
 
-The catalog is generated from `STEP_SCHEMAS` in `@eigenpal/types` and
-is always in sync with what the deployment supports.
+The CLI will be a thin client; the engine stays in one place.

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

@@ -160,6 +160,26 @@ Extract structured data from text using AI with a JSON schema
 
 > Extracted structured data matching the provided schema
 
+#### `ai.split` — Split Document
+
+Split 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.
+
+**Config** (in `step.with`):
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `input` | string | yes |  | Template expression resolving to ai.parse output, e.g. "{{ steps.parse.output }}" |
+| `sections` | array<object> | yes |  | Named sections to find in the document |
+| `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." |
+| `provider` | string | no |  | Provider ID from eigenpal.config.yaml (e.g. "openai-gpt5.4-mini"). Falls back to the tenant default LLM provider when omitted. |
+| `windowTokenBudget` | integer | no |  | Override the per-window token ceiling for this step. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. Smaller windows give sharper anchors on contract-style documents (less competing context for the LLM to mis-anchor on); bump to 50k–100k when sections routinely exceed per-window page count. |
+
+**Output:** `object`
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `splits` | array<object> | yes |  | Sections found in the document, in page order. Absent sections are omitted. |
+
 ### Transform steps — deterministic data transforms
 
 #### `transform.set` — Set Value
@@ -326,6 +346,46 @@ Execute JavaScript code in a secure sandbox. Input keys become TOP-LEVEL variabl
 
 > Value returned from script (validated against outputSchema if provided)
 
+#### `transform.text-chunker` — Text Chunker
+
+Split 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.
+
+**Config** (in `step.with`):
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `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. |
+| `maxChars` | integer | yes |  | Target chunk size in characters. Hard ceiling per chunk is 1.5×. |
+| `overlap` | integer | no | `0` | Characters duplicated at chunk boundaries (default 0). Must be < maxChars / 2. |
+| `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+/). |
+| `maxChunks` | integer | no | `64` | Safety cap; later chunks are dropped and `summary.truncated` flips to true. |
+| `preserveHeader` | integer | no | `0` | Prepend the first N characters of the input to every chunk (good for "always include the contract title"). |
+| `minChunkChars` | integer | no | `0` | Trailing chunks shorter than this are merged into the previous chunk. |
+
+**Output:** `object`
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `chunks` | array<object> | yes |  |  |
+| `summary` | object | yes |  |  |
+
+#### `transform.regex-extract` — Regex Extract
+
+Pull 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.
+
+**Config** (in `step.with`):
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `input` | string \| record<string, unknown> | yes |  | Either raw text or a parsed-document object `{ pages: [{ pageIndex, text }] }`. Pages enable per-match `_evidence.pageIndex`. |
+| `fields` | record<string, object> | yes |  | Named field → pattern mapping. |
+| `flags` | string | no |  | Default regex flags applied when a field omits its own `flags`. Subset of "gimsuy". |
+| `searchWindow` | integer | no |  | Only search the first N characters of input (perf). Omit for full search. |
+
+**Output:** `record<string, unknown>`
+
+> Field name → extracted value (or default), plus `_evidence: { [field]: { pageIndex, matchOffset, raw } }` and `_unmatched: string[]`.
+
 ### Action steps — external side effects
 
 #### `action.http` — HTTP Request

package/dist/skill/reference/workflow-yaml.md

@@ -226,6 +226,104 @@ on the step execution.
           schema: { type: object, properties: { value: { type: string } } }
 ```
 
+### Split a long doc into named sections, then extract each
+
+For documents that bundle multiple sub-documents (e.g. a contract pack with
+several annexes), use `ai.split` to find section boundaries with an LLM,
+then `control.parallel_map` to run section-specific `ai.extract`. The
+splitter operates on parsed pages, so DOCX / RTF / scans all reduce to the
+same per-page representation.
+
+Description-writing tips (mirrors Reducto's guidance):
+
+- Use the document's own terminology — a Slovak contract calls it `Príloha`,
+  not "annex". List the multilingual variants you've seen.
+- Mention stable visual cues if any — a centered title-page header, a
+  signature line, the start of a specific table.
+- Be specific. "The collateral schedule table at the start of Príloha 2"
+  beats "annex".
+
+```yaml
+- name: parse
+  type: ai.parse
+  with:
+    input: '{{ input.document }}'
+
+- name: split
+  type: ai.split
+  with:
+    input: '{{ steps.parse.output }}'
+    sections:
+      - name: intro
+        description: >-
+          The introductory cover/preamble of the loan pack — borrower details,
+          loan purpose, signature block. Always before any "Príloha".
+      - name: priloha_2
+        description: >-
+          "Príloha č. 2 / Anlage 2 / Załącznik nr 2" — the collateral
+          schedule. Starts with a section header on its own page; contains
+          a table of pledged assets.
+        required: true                  # warn if not found
+        endHints:                       # LLM-judged end cues — phrases the model treats semantically
+          - "PRÍLOHA Č. 3"
+          - "ANLAGE 3"
+      - name: priloha_3
+        description: >-
+          "Príloha č. 3 / Anlage 3" — the repayment schedule. Tabular
+          amortization plan with monthly rows.
+    rules: |
+      End-of-section markers like *Koniec prílohy 2* close the current section.
+      Repeated headers/footers are continuation, not new sections.
+
+- name: extract-each-section
+  type: control.parallel_map
+  items: '{{ steps.split.output.splits }}'
+  as: section
+  steps:
+    - name: extract-section-fields
+      type: ai.extract
+      with:
+        input: '{{ section.text }}'
+        schema:
+          type: object
+          properties:
+            section_name: { type: string }
+            key_facts: { type: array, items: { type: string } }
+```
+
+Each `splits[i]` carries `{ name, page_range, confidence, notes, evidence,
+end_evidence, text, pages, pages_anchored, pages_inferred }`.
+
+- `confidence` is `'low' | 'medium' | 'high'` — coarse enum, not a 0..1
+  number. LLMs cluster numeric scores meaninglessly; the enum is reliable.
+- `evidence.start_heading_text` is the verbatim heading the LLM cited (parse
+  this instead of regexing over `notes`).
+- `end_evidence` is set when the LLM detected a section close (matched
+  against the section's `endHints` or an explicit closing marker like
+  `*Koniec prílohy*`). Carries `{ end_page, confidence, notes }`. Absent
+  when continuity-fill alone closed the section. Pair `evidence.notes` +
+  `end_evidence.notes` for a reconciliation pass that judges whether the
+  section is correctly bounded.
+- `pages[i].source` is `'anchored'` (direct LLM evidence) or `'inferred'`
+  (filled by continuity) — use it to deprioritize inferred content.
+
+Pages that match no section are silently dropped (Reducto-style); add an
+explicit "everything else" section if you need a catch-all.
+
+Per-section knobs:
+
+- `required: true` — log a warn if missing and lean the LLM toward expecting
+  it. Default: false.
+- `endHints: [string]` — natural-language cues the LLM uses to find the
+  section's END. Treated semantically (casing variants, missing diacritics,
+  multilingual phrasings all qualify) — this is NOT a regex match. The LLM
+  emits a structured `end_anchor`; deterministic merge applies it. Replaces
+  the older `endAnchors` line-prefix matcher.
+
+`extract-each-section.output` is `{ items, count, totalIterations }`, not a
+flat array — `items[i]` holds the per-iteration result keyed by the last
+inner step's name (here `{ "extract-section-fields": {...} }`).
+
 ## Validate before pushing
 
 ```bash

package/package.json

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