@eigenpal/cli 0.16.0 → 0.16.2

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

@@ -25,7 +25,7 @@ implement at runtime. Server-side validation errors point you here.
 - `transform.*` — deterministic data transforms (set, remove, combine, split, merge,
   script, template, pdf-embed, xlsx-to-json, json-to-xlsx). WASM sandboxed where applicable.
 - `action.*` — external side effects (HTTP, invoke another workflow, website reader).
-- `control.*` — flow control (if, foreach, parallel, parallel_map, wait, fail).
+- `control.*` — flow control (if, foreach, parallel, parallel_map, wait, human_review, fail).
 
 The full per-type catalog with field tables is auto-generated below from
 `STEP_SCHEMAS`. The high-level map above tells you which family you want;
@@ -40,6 +40,7 @@ the catalog tells you what fields it takes.
 | Pull a typed object from text     | `ai.extract` with `config.schema`                 |
 | Pick one label from a fixed set   | `ai.classify` with `config.labels`                |
 | Reject bad inputs with a 4xx code | `control.fail` (often after `ai.classify`)        |
+| Pause for human field review      | `control.human_review` (top-level only; see below)  |
 | Sum / filter / regex              | `transform.script` (NOT Liquid)                   |
 | Render a DOCX or XLSX template (YAML workflow) | `transform.template` with `tmpl_...` or `./file.xlsx` |
 | Fill a DOCX or XLSX template (runtime agent)   | fill-template platform skill         |
@@ -158,6 +159,70 @@ $ eigenpal workflow step-type get ai.extract | jq '.outputSchema'
 Reference user-supplied schema fields the same way:
 `{{ steps.extract.output.extracted.invoiceNumber }}`.
 
+## Human review — top-level gate only
+
+`control.human_review` pauses the run until a reviewer confirms or corrects
+selected scalar fields, then resumes with the reviewed object or array. Place
+it as a **top-level sequential step** only — nested placement inside
+`control.if`, `control.foreach`, `control.parallel`, `control.parallel_map`, or
+`control.switch` is rejected at publish time.
+
+Config lives in `step.with` (unlike most other `control.*` steps). Wire data
+from an upstream extract or transform, choose a selection mode, and attach run
+files for context:
+
+```yaml
+- name: review-invoice
+  type: control.human_review
+  with:
+    data: '{{ steps.extract.output }}'
+    metadataFrom: ai.extract
+    instructions: Confirm vendor and total before posting.
+    selection:
+      mode: confidence
+      threshold: medium
+      missingConfidence: review
+      fields:
+        /vendor:
+          review: always
+        /total:
+          threshold: high
+    fieldMetadata:
+      /vendor:
+        label: Vendor name
+      /total:
+        label: Invoice total
+    files:
+      includeRunInputs: true
+      attachments:
+        - '{{ steps.render.output.files[0] }}'
+```
+
+When `metadataFrom: ai.extract` is set and `data` is the whole extract output
+(`{{ steps.<name>.output }}`), the step strips the reserved `_grounding` key,
+derives categorical confidence (`low`, `medium`, `high`) per field, and reuses
+the extract schema when `schema` is omitted.
+
+**Selection:** three modes — `confidence` (review fields below threshold),
+`explicit` (review matched include/exclude paths), and `all` (every scalar
+leaf). Thresholds accept numeric `0`–`1` or categorical `low|medium|high`;
+equality auto-approves. Per-path overrides live under `selection.fields` with
+`review: always|never|skip` and optional per-field `threshold`. Prefer
+`selection.fields` over the legacy `fieldMetadata.review`.
+
+**Output:** the complete reviewed data in the same shape as `data`. Reference
+downstream fields directly: `{{ steps.review-invoice.output.vendor }}`.
+
+**Evaluations:** evaluation runs always simulate review and never pause the
+run. Use `meta.json` `review` fixtures to assert routing, reasons, and
+simulated reviewer edits — see `reference/dataset-format.md`. Empty selection
+continues immediately without creating a task.
+
+**Limits:** 2 MiB review JSON, 10k scalar leaves, 1 MiB metadata, 2k required
+fields, 100 attachments.
+
+Use `eigenpal workflow step-type get control.human_review` for the full schema.
+
 ## Control containers — nested step shape and scoping
 
 `control.parallel`, `control.parallel_map`, `control.foreach`, `control.if`,
@@ -426,9 +491,9 @@ Extract text from documents (PDF, DOCX, images) using native extraction, OCR, or
 | `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. |
 | `ocrModel` | string | no |  | OCR provider ID for PDF/image parsing |
 | `llmModel` | string | no |  | LLM provider ID for vision-based parsing |
-| `llmReasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `llmReasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `figureModel` | string | no |  | Vision model used only for the optional figure-description pass |
-| `figureReasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `figureReasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `maxConcurrency` | number | no | `3` | Max concurrent VLM batch requests |
 | `pagesPerBatch` | number | no | `5` | Number of page images per VLM request |
 | `pdfRenderScale` | number | no | `1` | Scale factor for rendering PDF pages before VLM parsing. Higher values produce sharper images at larger payload sizes. |
@@ -486,7 +551,7 @@ Config schema:
       "type": "string"
     },
     "llmReasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -503,7 +568,7 @@ Config schema:
       "type": "string"
     },
     "figureReasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -1390,17 +1455,17 @@ Extract structured data from text using AI with a JSON schema
 | `prompt` | string | no |  | Custom prompt template for extraction |
 | `provider` | string | no |  | Provider ID (e.g., "openai-gpt4o") |
 | `model` | string | no |  | Model override |
-| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `maxInputTokens` | integer | no |  | Max input tokens. Truncates input text and logs a warning when exceeded. Omit for no limit. |
 | `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. |
 | `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. |
-| `groundingReasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `groundingReasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `groundingExamples` | array<object> | no |  | Optional few-shot examples pinning grounding to verbatim source text per field. |
 | `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. |
 
 **Output:** `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 field name: `_grounding.<field> = { confidence: high|medium|low, needsReview, reason?, source_span: { start, end, text, alignment } | null }`, plus reserved `_degraded: true` / `_reason` markers when the grounding LLM pass could not run.
+> 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.
 
 ##### Complete machine-readable schemas
 
@@ -1456,7 +1521,7 @@ Config schema:
       "type": "string"
     },
     "reasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -1483,7 +1548,7 @@ Config schema:
       "type": "string"
     },
     "groundingReasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -1559,7 +1624,7 @@ Output schema:
     "type": "string"
   },
   "additionalProperties": {},
-  "description": "Extracted structured data matching the provided schema. Unless grounding is disabled (grounded: false), the output also carries a reserved `_grounding` map keyed by field name: `_grounding.<field> = { confidence: high|medium|low, needsReview, reason?, source_span: { start, end, text, alignment } | null }`, plus reserved `_degraded: true` / `_reason` markers when the grounding LLM pass could not run."
+  "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."
 }
 ```
 
@@ -1580,7 +1645,7 @@ Split a parsed document into named sections using an LLM. Consumes ai.parse outp
 | `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. |
-| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `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`
@@ -1648,7 +1713,7 @@ Config schema:
       "type": "string"
     },
     "reasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -2052,7 +2117,7 @@ Separate a concatenated batch (one big scan) into typed document instances using
 | `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. |
 | `rules` | string | no |  | Optional natural-language rules appended to the system prompt. |
 | `provider` | string | no |  | Provider ID from eigenpal.config.yaml. Falls back to the tenant default LLM provider when omitted. |
-| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `windowTokenBudget` | integer | no |  | Override the per-window token ceiling. Defaults to env SPLIT_WINDOW_TOKEN_BUDGET or 20000. |
 
 **Output:** `object`
@@ -2107,7 +2172,7 @@ Config schema:
       "type": "string"
     },
     "reasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -2416,7 +2481,7 @@ Classify a document or text into one of a fixed label set using an LLM. Output e
 | `prompt` | string | no |  | Custom classification instructions appended to the system prompt. Use to clarify edge cases or emphasize evidence the model should weigh. |
 | `provider` | string | no |  | Provider ID from eigenpal.config.yaml (e.g. "openai-gpt4o-mini"). Falls back to the tenant default LLM provider when omitted. |
 | `model` | string | no |  | Model override (advanced) |
-| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `maxInputTokens` | integer | no |  | Max input tokens. Truncates input text when exceeded. Omit for no limit. |
 
 **Output:** `object`
@@ -2476,7 +2541,7 @@ Config schema:
       "type": "string"
     },
     "reasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -2556,7 +2621,7 @@ Assign zero or more labels to each page independently (multi-label) using an LLM
 | `prompt` | string | no |  | Extra classification guidance appended to the system prompt. |
 | `provider` | string | no |  | Provider ID from eigenpal.config.yaml. Falls back to the tenant default. |
 | `model` | string | no |  | Model override (advanced). |
-| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `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). |
 
 **Output:** `object`
@@ -2623,7 +2688,7 @@ Config schema:
       "type": "string"
     },
     "reasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -2729,7 +2794,7 @@ Inspect rendered page images with a vision model and return structured JSON matc
 | `prompt` | string | no |  | Optional instruction refining the extraction. The schema drives it when omitted. |
 | `provider` | string | no |  | Provider ID (must support vision). |
 | `model` | string | no |  | Model override (must support vision). |
-| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to preserve the current provider default. |
+| `reasoningEffort` | `"none"` \| `"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"` \| `"max"` | no |  | Reasoning effort for models that support it. Omit to use the selected model's default. |
 | `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. |
 | `imageQuality` | integer | no |  | JPEG quality for rendered pages (default 85). |
 | `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. |
@@ -2882,7 +2947,7 @@ Config schema:
       "type": "string"
     },
     "reasoningEffort": {
-      "description": "Reasoning effort for models that support it. Omit to preserve the current provider default.",
+      "description": "Reasoning effort for models that support it. Omit to use the selected model's default.",
       "type": "string",
       "enum": [
         "none",
@@ -4802,7 +4867,7 @@ Execute another workflow and return its output
 | `execution` | `"inline"` \| `"child"` | no |  | inline: run target steps in this execution (default). child: spawn a separate run with lineage. |
 | `input` | record<string, unknown> | no |  | Input record keyed by the invoked workflow's declared inputs |
 | `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. |
-| `timeout` | number | no |  | Child mode only. Max wait time in ms when waiting (default: 300000) |
+| `timeout` | number | no |  | Child mode only. Max wait time in ms while the child is queued or running (default: 300000). Once the child pauses for human review, the parent pauses durably instead of using this timeout. |
 | `pollInterval` | number | no |  | Child mode only. How often to poll status in ms when waiting (default: 1000) |
 
 **Output:** `record<string, unknown>`
@@ -4849,7 +4914,7 @@ Config schema:
       "type": "boolean"
     },
     "timeout": {
-      "description": "Child mode only. Max wait time in ms when waiting (default: 300000)",
+      "description": "Child mode only. Max wait time in ms while the child is queued or running (default: 300000). Once the child pauses for human review, the parent pauses durably instead of using this timeout.",
       "type": "number"
     },
     "pollInterval": {
@@ -5769,6 +5834,446 @@ Output schema:
 ```
 
 
+#### `control.human_review` — Human Review
+
+Pause the run for selective field confirmation or correction, then continue with the reviewed data.
+
+**Behavior and examples:** `eigenpal docs read steps/control/human_review`
+
+**Durable retry:** This control step is not retried durably.
+
+**Config** (in `step.with`):
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `data` | string \| record<string, unknown> \| array<unknown> | yes |  | Structured data or a template expression resolving to an object or array |
+| `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. |
+| `metadataFrom` | `"ai.extract"` | no |  | Producer adapter. `ai.extract` derives field confidence from `_grounding` and strips that reserved key from review data. Grounding is not stripped unless this is set. |
+| `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. |
+| `selection` | object | yes |  | Field selection policy resolved once when the task is created |
+| `files` | object | no | `{"includeRunInputs":true,"attachments":[]}` | Run input files and optional current-run attachments for reviewers |
+| `instructions` | string | no |  | Free-form guidance shown above the review workspace |
+
+**Output:** `unknown`
+
+> The complete reviewed data in the same object or array shape as the input.
+
+##### Complete machine-readable schemas
+
+Config schema:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "data": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        {
+          "type": "array",
+          "items": {}
+        }
+      ],
+      "description": "Structured data or a template expression resolving to an object or array"
+    },
+    "schema": {
+      "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.",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    },
+    "metadataFrom": {
+      "type": "string",
+      "enum": [
+        "ai.extract"
+      ],
+      "description": "Producer adapter. `ai.extract` derives field confidence from `_grounding` and strips that reserved key from review data. Grounding is not stripped unless this is set."
+    },
+    "fieldMetadata": {
+      "description": "RFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias.",
+      "default": {},
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "confidence": {
+            "anyOf": [
+              {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              {
+                "type": "string",
+                "enum": [
+                  "low",
+                  "medium",
+                  "high"
+                ]
+              },
+              {
+                "type": "string",
+                "minLength": 1
+              }
+            ]
+          },
+          "label": {
+            "type": "string",
+            "maxLength": 500
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 5000
+          },
+          "review": {
+            "default": "auto",
+            "type": "string",
+            "enum": [
+              "auto",
+              "always",
+              "never"
+            ]
+          },
+          "display": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {}
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "selection": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "include": {
+              "description": "RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)",
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 512
+              }
+            },
+            "exclude": {
+              "description": "RFC 6901 pointers removed after include expansion",
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 512
+              }
+            },
+            "fields": {
+              "description": "Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.",
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 512
+              },
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "review": {
+                    "type": "string",
+                    "enum": [
+                      "always",
+                      "never",
+                      "skip"
+                    ]
+                  },
+                  "threshold": {
+                    "anyOf": [
+                      {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                      },
+                      {
+                        "type": "string",
+                        "enum": [
+                          "low",
+                          "medium",
+                          "high"
+                        ]
+                      },
+                      {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    ]
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "mode": {
+              "type": "string",
+              "const": "confidence",
+              "description": "Review fields below threshold or missing confidence"
+            },
+            "threshold": {
+              "anyOf": [
+                {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1
+                },
+                {
+                  "type": "string",
+                  "enum": [
+                    "low",
+                    "medium",
+                    "high"
+                  ]
+                },
+                {
+                  "type": "string",
+                  "minLength": 1
+                }
+              ],
+              "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."
+            },
+            "missingConfidence": {
+              "description": "Whether unscored or type-mismatched fields require review (default review)",
+              "default": "review",
+              "type": "string",
+              "enum": [
+                "review",
+                "skip"
+              ]
+            }
+          },
+          "required": [
+            "mode",
+            "threshold"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "include": {
+              "description": "RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)",
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 512
+              }
+            },
+            "exclude": {
+              "description": "RFC 6901 pointers removed after include expansion",
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 512
+              }
+            },
+            "fields": {
+              "description": "Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.",
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 512
+              },
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "review": {
+                    "type": "string",
+                    "enum": [
+                      "always",
+                      "never",
+                      "skip"
+                    ]
+                  },
+                  "threshold": {
+                    "anyOf": [
+                      {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                      },
+                      {
+                        "type": "string",
+                        "enum": [
+                          "low",
+                          "medium",
+                          "high"
+                        ]
+                      },
+                      {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    ]
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "mode": {
+              "type": "string",
+              "const": "explicit",
+              "description": "Review only paths matched by include/exclude"
+            }
+          },
+          "required": [
+            "mode"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "include": {
+              "description": "RFC 6901 pointers or wildcard patterns (for example `/items/*/amount`)",
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 512
+              }
+            },
+            "exclude": {
+              "description": "RFC 6901 pointers removed after include expansion",
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 512
+              }
+            },
+            "fields": {
+              "description": "Per-field selection policy keyed by exact pointers or wildcard patterns. Exact beats the most specific wildcard; equally specific overlapping wildcards are rejected.",
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "maxLength": 512
+              },
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "review": {
+                    "type": "string",
+                    "enum": [
+                      "always",
+                      "never",
+                      "skip"
+                    ]
+                  },
+                  "threshold": {
+                    "anyOf": [
+                      {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1
+                      },
+                      {
+                        "type": "string",
+                        "enum": [
+                          "low",
+                          "medium",
+                          "high"
+                        ]
+                      },
+                      {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    ]
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "mode": {
+              "type": "string",
+              "const": "all",
+              "description": "Review every scalar leaf unless excluded or review: never"
+            }
+          },
+          "required": [
+            "mode"
+          ],
+          "additionalProperties": false
+        }
+      ],
+      "description": "Field selection policy resolved once when the task is created"
+    },
+    "files": {
+      "description": "Run input files and optional current-run attachments for reviewers",
+      "default": {
+        "includeRunInputs": true,
+        "attachments": []
+      },
+      "type": "object",
+      "properties": {
+        "includeRunInputs": {
+          "description": "Attach every authorized run input file to the review task",
+          "default": true,
+          "type": "boolean"
+        },
+        "attachments": {
+          "description": "Additional current-run file or artifact template expressions",
+          "default": [],
+          "maxItems": 100,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "instructions": {
+      "description": "Free-form guidance shown above the review workspace",
+      "type": "string",
+      "maxLength": 10000
+    }
+  },
+  "required": [
+    "data",
+    "selection"
+  ],
+  "additionalProperties": false
+}
+```
+
+
+Output schema:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "The complete reviewed data in the same object or array shape as the input."
+}
+```
+
+
 #### `control.fail` — Fail
 
 Terminate 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.