@parcha/agentrun-pi 0.1.0-beta.1

package/skills/author/examples/evidence-gate.json

@@ -0,0 +1,125 @@
+{
+  "v": 2,
+  "name": "fictional-evidence-gate",
+  "schemas": {
+    "Record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "claim",
+        "evidence"
+      ],
+      "properties": {
+        "claim": {
+          "type": "string"
+        },
+        "evidence": {
+          "type": "string"
+        }
+      }
+    },
+    "Input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "record"
+      ],
+      "properties": {
+        "record": {
+          "$ref": "#/definitions/Record"
+        }
+      }
+    },
+    "Questions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "supported"
+      ],
+      "properties": {
+        "supported": {
+          "type": "boolean",
+          "description": "Does the supplied evidence explicitly support every factual detail in the claim, without adding assumptions or contradicting it?"
+        }
+      }
+    },
+    "Gate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "accepted"
+      ],
+      "properties": {
+        "accepted": {
+          "type": "boolean"
+        }
+      }
+    },
+    "Result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "record",
+        "accepted"
+      ],
+      "properties": {
+        "record": {
+          "$ref": "#/definitions/Record"
+        },
+        "accepted": {
+          "type": "boolean"
+        }
+      }
+    }
+  },
+  "input": {
+    "schemaId": "Input"
+  },
+  "output": {
+    "schemaId": "Result",
+    "path": "result"
+  },
+  "root": {
+    "node": "chain",
+    "steps": [
+      {
+        "node": "code",
+        "label": "retain-record",
+        "code": "(s) => ({ original: s.record })"
+      },
+      {
+        "node": "judge",
+        "label": "check-evidence",
+        "state": {
+          "record": "{original}"
+        },
+        "out": "Questions",
+        "as": "check"
+      },
+      {
+        "node": "code",
+        "label": "probability-gate",
+        "code": "(s) => { const p = s['check$answers']?.answers?.supported?.noul; return { accepted: typeof p === 'number' && Number.isFinite(p) && p >= 0.90 && p <= 1 }; }",
+        "as": "gate"
+      },
+      {
+        "node": "escalate",
+        "label": "request-better-evidence",
+        "when": {
+          "predicate": "field_equals",
+          "path": "gate.accepted",
+          "value": false
+        },
+        "kind": "needs_evidence",
+        "stage": "verification",
+        "summary": "Evidence did not meet the required yes-probability threshold."
+      },
+      {
+        "node": "code",
+        "label": "assemble-result",
+        "code": "(s) => ({ record: s.original, accepted: s.gate.accepted })",
+        "as": "result"
+      }
+    ]
+  }
+}

package/skills/author/examples/read-file.input.json

@@ -0,0 +1 @@
+{ "path": "README.md" }

package/skills/author/examples/read-file.json

@@ -0,0 +1,44 @@
+{
+  "v": 2,
+  "name": "read-file",
+  "schemas": {
+    "Input": {
+      "type": "object",
+      "properties": { "path": { "type": "string", "minLength": 1 } },
+      "required": ["path"],
+      "additionalProperties": false
+    },
+    "ToolResult": {
+      "type": "object",
+      "properties": {
+        "content": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "type": { "type": "string", "enum": ["text", "image"] },
+              "text": { "type": "string" },
+              "data": { "type": "string" },
+              "mimeType": { "type": "string" }
+            },
+            "required": ["type"]
+          }
+        },
+        "details": {}
+      },
+      "required": ["content"]
+    }
+  },
+  "input": { "schemaId": "Input" },
+  "output": { "schemaId": "ToolResult", "path": "file" },
+  "root": {
+    "node": "call",
+    "label": "read-file",
+    "via": "tool",
+    "tool": "read",
+    "args": { "path": "{path}" },
+    "out": "ToolResult",
+    "as": "file",
+    "deadline_s": 10
+  }
+}

package/skills/author/examples/read-source-decision.input.json

@@ -0,0 +1,4 @@
+{
+  "question": "Does the source announce a required client migration for the current release rather than a proposal?",
+  "paths": ["release-note.txt"]
+}

package/skills/author/examples/read-source-decision.json

@@ -0,0 +1,37 @@
+{
+  "v": 2,
+  "name": "fictional-read-source-decision",
+  "schemas": {
+    "Input": { "type": "object", "properties": {
+      "question": { "type": "string", "minLength": 1 },
+      "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+    }, "required": ["question", "paths"], "additionalProperties": false },
+    "ToolResult": { "type": "object", "properties": {
+      "content": { "type": "array", "items": { "type": "object", "properties": {
+        "type": { "const": "text" }, "text": { "type": "string" }
+      }, "required": ["type", "text"] } }, "details": {}
+    }, "required": ["content"] },
+    "Questions": { "type": "object", "properties": {
+      "matches": { "type": "boolean", "description": "Does the original source text satisfy the condition asked in question, taking account of its headings, scope and exclusions rather than keyword overlap?" }
+    }, "required": ["matches"], "additionalProperties": false },
+    "Results": { "type": "array", "items": { "type": "object", "properties": {
+      "path": { "type": "string" }, "source": { "$ref": "#/definitions/ToolResult" },
+      "probability": { "type": "number", "minimum": 0, "maximum": 1 }
+    }, "required": ["path", "source", "probability"], "additionalProperties": false } }
+  },
+  "input": { "schemaId": "Input" },
+  "output": { "schemaId": "Results", "path": "results" },
+  "root": {
+    "node": "map", "label": "read-and-judge-originals", "itemsPath": "paths", "maxConcurrency": 2,
+    "as": "results", "resultPath": "record",
+    "body": { "node": "chain", "steps": [
+      { "node": "call", "label": "read-original", "via": "tool", "tool": "read",
+        "args": { "path": "{item}" }, "out": "ToolResult", "as": "source", "deadline_s": 30 },
+      { "node": "judge", "label": "source-membership", "state": {
+        "question": "{question}", "source": "{source}"
+      }, "out": "Questions", "as": "decision" },
+      { "node": "code", "label": "retain-source-and-probability", "as": "record",
+        "code": "(s) => ({ path: s.item, source: s.source, probability: s['decision$answers'].answers.matches.noul })" }
+    ] }
+  }
+}

package/skills/author/examples/release-note.txt

@@ -0,0 +1,10 @@
+FICTIONAL EXAMPLE — not a real product release
+
+# Current release
+
+Clients MUST send the X-Workspace header with their workspace slug.
+
+# Future proposals — not approved
+
+Changing the authentication mechanism remains a proposal. No authentication
+migration is required by this release.

package/skills/author/examples/review-release-notes.input.json

@@ -0,0 +1,6 @@
+{
+  "notes": [
+    "Requests now require the X-Workspace header. Older clients must send X-Workspace with their workspace slug.",
+    "The legacy /events endpoint has been removed. Send event queries to /v2/events instead."
+  ]
+}

package/skills/author/examples/review-release-notes.json

@@ -0,0 +1,123 @@
+{
+  "v": 2,
+  "name": "review-release-notes",
+  "schemas": {
+    "Input": {
+      "type": "object",
+      "properties": {
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "maxItems": 5
+        }
+      },
+      "required": [
+        "notes"
+      ],
+      "additionalProperties": false
+    },
+    "Change": {
+      "type": "object",
+      "properties": {
+        "breakingChange": {
+          "type": "string",
+          "minLength": 1
+        },
+        "migrationAction": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "breakingChange",
+        "migrationAction"
+      ],
+      "additionalProperties": false
+    },
+    "Report": {
+      "type": "object",
+      "properties": {
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "breakingChange": {
+                "type": "string",
+                "minLength": 1
+              },
+              "migrationAction": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "breakingChange",
+              "migrationAction"
+            ],
+            "additionalProperties": false
+          },
+          "minItems": 1
+        }
+      },
+      "required": [
+        "summary",
+        "changes"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "input": {
+    "schemaId": "Input"
+  },
+  "output": {
+    "schemaId": "Report",
+    "path": "report"
+  },
+  "root": {
+    "node": "chain",
+    "steps": [
+      {
+        "node": "map",
+        "label": "extract-each-release-note",
+        "itemsPath": "notes",
+        "as": "changes",
+        "maxConcurrency": 2,
+        "body": {
+          "node": "extract",
+          "label": "extract-change",
+          "instructions": "Extract the breaking change and its migration action from the supplied release note. Preserve the exact header name and required action. Do not invent a migration step.",
+          "state": {
+            "text": "{item}"
+          },
+          "requires": [
+            "item"
+          ],
+          "out": "Change",
+          "as": "change"
+        }
+      },
+      {
+        "node": "extract",
+        "label": "summarize-migration",
+        "instructions": "Summarize these migration actions for a client maintainer. Return the supplied changes unchanged alongside the summary. Do not invent steps.",
+        "state": {
+          "changes": "{changes}"
+        },
+        "requires": [
+          "changes"
+        ],
+        "out": "Report",
+        "as": "report"
+      }
+    ]
+  }
+}

package/skills/author/references/jev-decisions.md

@@ -0,0 +1,112 @@
+# Design Jev decisions in AgentRun
+
+Jev returns typed judgments and probabilities, not generated prose, tool calls or
+multi-step research. The host supplies its adapter and credentials. Do not write
+HTTP requests or SDK setup into workflow code. This guide maps the TypeSafe
+programming model to the installed DSL; the general TypeSafe skill is optional.
+
+## Choose the boundary
+
+Work backward from the action the result controls. Code handles exact lookups,
+parsing, arithmetic, joins, grouping and constraints. An agent handles open-ended
+research or generation. Jev can select relevant evidence, interpret a boundary,
+compare a claim to its source or choose among known actions. It need not be a
+final approval stage, and a workflow without a semantic decision need not use it.
+
+Ask one coherent judgment per property. Separate independently useful conditions;
+keep related context together. Avoid asking whether a whole complex answer is
+"correct" when no source supporting that answer is supplied. Question descriptions
+must carry their meaning; property names alone are not instructions.
+
+## Construct the evidence, not another opinion
+
+For source-grounded work, a useful pattern is:
+
+1. A tool or agent locates candidate references, retaining their identities.
+2. Direct tool calls fetch the original text at those references.
+3. Jev sees the question or full selection rule **and that original text**.
+4. Code uses the returned values; an agent may repair missing evidence or synthesize.
+
+Keep source text separate from a candidate extraction, paraphrase or claim. An
+agent's field named `quote`, `headerContext` or `verified` does not make it original
+evidence. Re-read the cited source through the host tool when independent checking
+matters. Include relevant headings, units, dates, neighboring rows, exclusions and
+section boundaries. An exact quote match checks presence, not interpretation.
+
+Judge only what the supplied context can establish. If a source is truncated,
+follow its continuation when relevant; if it is missing, retrieve or surface the
+gap. Do not silently substitute a summary to fit a size limit. Narrow or partition
+large contexts at meaningful boundaries while retaining their qualifiers.
+The adapter has no default byte ceiling. A host may explicitly configure
+`maxStateBytes`; local size errors then report the measured UTF-8 JSON bytes and
+that host's limit before any HTTP request is sent. Provider context limits are
+separate and token-based, not a fixed bytes-to-tokens conversion. Jev 1.13's
+documented contract, checked on 2026-09-22, allows 32k tokens for state plus the
+longest question and 64k for state plus all questions combined; check the selected
+model's current contract. Oversized provider requests remain
+errors, not permission to truncate evidence or silently retry a different graph.
+
+`sift` sends **all items together in one request**. Shared `state` is added to
+that batch; it does not replace or narrow each item. `describe` adds an item
+summary, but the full original item is still sent. A tool envelope can contain
+the same text in both `content` and `details`, so character limits on individual
+reads do not establish the final serialized size.
+
+When judgments are independent, explicitly use `map` with a `judge` body for one
+request per original. For records that already contain `document`, `page` and
+`text`, a body can use `state: {rule: "{question}", original: "{item}"}`. For tool
+envelopes, select the host's actual original-text and provenance fields instead
+of sending duplicate representations. Retain the full reviewed rule, relevant
+headers, units, dates, exclusions and neighboring rows. If an individual original
+is still too large, retrieve or partition it at meaningful boundaries; do not
+silently truncate it or replace it with an agent's interpretation. This explicit
+graph change changes request count; no automatic batching or truncation occurs.
+
+The fictional [read-source decision](../examples/read-source-decision.json) and
+[input](../examples/read-source-decision.input.json) demonstrate direct `read`
+results passed to Jev unchanged, followed by deterministic probability projection.
+Its paths are inputs, not a built-in corpus. Place the bundled fictional
+[release note](../examples/release-note.txt) at `release-note.txt` in the working
+directory (or change the input path to its location) before running that input.
+Adapt the tool and return schema to
+`describe`; an agent locator can produce those paths earlier in the same graph.
+
+## Use the installed primitives
+
+- `judge`: a flat output schema describes several independent questions over one
+  explicit `state` map. Boolean properties become yes-probabilities (Noul); enums
+  become Choice; integer properties with minimum 0, maximum N−1 and N described
+  levels in `criteria` (2–10 levels) become Score. Put the complete question in each
+  `description`.
+- `sift`: ask questions about each candidate and retain originals. Pass shared task
+  context in `state`; each item also needs its own original evidence. Candidate
+  coverage matters: no judge can recover a source absent from the candidate set.
+- `pick`: choose from known candidates, with `allowNone` when none may fit.
+- `route`: choose a semantic branch. Its uncertainty gate concerns that new
+  decision, not an earlier judge's probability.
+
+Batch independent questions over the same state. They cannot read each other's
+answers. Use another step when a decision is needed to retrieve new evidence or
+construct new state. Inspect the assembled state and questions, not just node names.
+
+## Consume uncertainty honestly
+
+`judge` stores decoded values at its `as` key and raw answers at `<as>$answers`.
+A boolean is true at yes-probability 0.5; to enforce another threshold, read the
+raw `.answers.<property>.noul` number and compare in code. A Noul near 0.5 means
+uncertainty between yes and no, not medium intensity. Choice/Score confidence is
+distribution concentration, not proof that the workflow is right.
+
+Use thresholds appropriate to the task, with an explicit missing/uncertain path.
+An example threshold is not calibrated policy. Low probability can justify
+exclusion, another retrieval, cheap-agent repair or escalation, depending on the
+question. Do not reject an entire result just because an unused condition is
+uncertain. Preserve raw decisions so these policies can be inspected separately.
+
+Typed output proves an interface, not truth. Test source coverage, semantics and
+the downstream action independently. A fake-judge fixture proves wiring only.
+
+Maintained against TypeSafe's state, primitives/Noul, confidence and citation-check
+documentation, reviewed 2026-09-22. Upstream reference locations:
+`https://docs.typesafe.ai/concepts/state`, `https://docs.typesafe.ai/primitives`,
+`https://docs.typesafe.ai/confidence`, `https://docs.typesafe.ai/cookbooks/citation_check`.

package/skills/author/references/sdk-authoring.md

@@ -0,0 +1,16 @@
+# Demo commands and standalone SDK
+
+## Demonstrations
+
+`/agentrun demo` runs the interpreter with scripted responses over fictional sources. `/agentrun demo empty` exercises insufficient evidence. Neither makes model calls. `/agentrun demo live` uses real Pi agent calls and Jev system one decisions over the same fictional sources; TypeSafe access is required. It is still not web research.
+
+
+## SDK authoring only
+
+Use this path when the host invokes `authorWorkflow` rather than the native `agentrun` tool. The SDK supplies a `submit` tool; deliver `{"value": workflow}` through it. Read validation and acceptance feedback, then repair within that session. The host retains each version and rejection. Acceptance does not activate or execute a replacement.
+
+With `rubricSections`, every generated LLM node must reference every supplied section, including child workflows. This conservative author policy rejects Jev nodes, semantic `ask` predicates, and `verify` clauses until the host has a separately reviewed question contract. Execution must receive the same authoritative SOP text. A schema field named `node`, `verify`, or `predicate` is ordinary data, not a judgment clause.
+
+Host-owned acceptance callbacks and fixtures remain outside generated workflows. Do not edit them to obtain a pass. Structural acceptance alone does not establish behavior. Keep request text, rubric text, candidates, and reviews in storage appropriate for their contents.
+
+SDK configuration and file retention are not features the native author must reimplement. The installed Pi package README documents `authorWorkflow`, `createPiHostRunner`, and the separate CLI.

package/skills/author/references/workflow-format.md

@@ -0,0 +1,145 @@
+# Workflow format
+
+AgentRun documents are JSON data: `v: 2`, `name`, `schemas`, optional `input: {schemaId}`, `output: {schemaId, path}`, and `root`. Schema identifiers refer to the document's own catalog. Define the input and expected output before adding nodes. The installed `@parcha/agentrun-dsl/schema` is the complete editor schema; execution performs additional semantic checks.
+
+## Minimal typed answer
+
+The complete [inline typed example](../SKILL.md#minimal-typed-example) shows the minimal extraction pattern and its input. The model must extract the stated facts; the example itself is not a passed quality test.
+
+Important fields:
+
+- `requires` names paths in workflow state, not renamed keys in the prompt map. It is a **nonempty-evidence guard**, not a field-existence check: missing/null values, blank strings, empty arrays and objects without concrete values fail before model construction. `false` and `0` are concrete values. If an empty search result is valid input to a recovery step, handle it explicitly rather than declaring it nonempty.
+- LLM `instructions` are literal prose. They do not substitute `{text}`.
+- `state: {text: "{text}"}` explicitly chooses the JSON user message. Omitted `state` sends accumulated state, excluding legacy reference catalogs.
+- `out` names the node's schema; `as` stores its value in state. For agent/extract/decide nodes, omitting `as` stores under the node's `label`; fields are not merged into top-level state. `output.path` selects the final value to validate.
+
+For repository work, an agent can declare `tools: ["read", "grep"]` only if those tools are available. Read the host's tool argument schemas; do not invent parameters. Use `tools: []` for a tool-free agent or extraction. Omitting the list inherits the runner's allowed tools; it does not mean tool-free execution.
+
+## One direct tool operation
+
+Read [read-file.json](../examples/read-file.json) and its [input](../examples/read-file.input.json). This performs one active built-in `read` call; it needs no model or Jev system one decision. Replace the input path with the file the user asked to read.
+
+A built-in returns a Pi tool result: `content` is an array of text/image blocks and `details` is optional. Give `call.out` a schema for that tool return, rather than the final answer or a plain string. A later extraction can transform it into a different output schema. The bundled fictional `search` tool is the exception: its direct effect result is `{sources}`. A `call` needs its host tool name, typed `args`, result `out`, state key `as`, and positive `deadline_s`.
+
+## Composition and decisions
+
+Read the complete [release-note review](../examples/review-release-notes.json) and its [input](../examples/review-release-notes.input.json) before composing nodes. It maps a typed extraction over two notes, collects only each `change`, then summarizes the collected changes. This needs Pi, but no Jev or external tools.
+
+Use `chain.steps` for dependencies. Each `parallel.branches` entry receives the same input; branches must write different top-level keys. In `map`, `itemsPath` selects the list and the body sees `item` and `item_index`; set `as` and bound `maxConcurrency`. A body with `as` already returns that value per item. Use `resultPath` to select a different path, or to avoid retaining whole parent states from a chain body without `as`. A `loop` needs `until` and integer `maxIters` from 1 through 20; reaching the bound is not proof of success.
+
+A Jev `judge` has a nonempty `state` map, `out`, and `as`. Its schema is flat: descriptions state questions, booleans yield yes-probabilities, enums yield choices, and integers with 2 to 10 explicit level descriptions in `criteria` yield scores. Scores range from 0 to the last level index. Raw answers are retained at `<as>$answers`; confidence is not calibrated accuracy. `sift` applies questions to each item, and `route` chooses a branch. Use an explicit uncertainty gate or escalation rather than inventing evidence. Supply the complete reviewed rubric; Jev question text is not a substitute for an unavailable SOP.
+
+For `sift`, add a flat question schema to `schemas`, then a node such as:
+
+```json
+{
+  "node": "sift", "label": "select-migration-notes",
+  "itemsPath": "notes", "out": "MigrationQuestions", "as": "selected",
+  "keep": { "path": "actionable", "gte": 0.8 }
+}
+```
+
+`MigrationQuestions` can declare `actionable` as `{"type":"boolean","description":"Does this release note state a concrete change a client maintainer must make, rather than only announce a feature?"}` inside its object `properties`. Set `required: ["actionable"]`. Read selected originals from `selected.items`, retained decisions from `selected.values`, and evidence sidecars from `selected.answers`. The `gte` value gates the yes-probability; it is an example threshold to review, not a calibrated guarantee. Handle empty results explicitly with an `escalate` node using `when: {predicate: "empty", path: "selected.items"}` before synthesis.
+
+A `sift` batches all full items into one Jev request; `state` adds shared context
+and `describe` adds summaries, neither replaces the items. The assembled request
+must fit the selected provider's token context and any explicit host byte guard;
+the adapter does not impose a default byte ceiling. A local `jev_state_too_large`
+report names the node, measured bytes and configured host limit; it means no HTTP
+request was sent. For independent judgments over larger originals,
+use an explicit `map` with a `judge` body and selected original-text/provenance
+fields, preserving the full rubric and necessary headers/qualifiers. See the
+[Jev guide](jev-decisions.md); no automatic splitting or truncation occurs.
+
+### Check the edges before running
+
+For each connection, name the actual value produced and the exact path consumed.
+These are different contracts; do not make them all the final answer schema:
+
+Inspection displays typed state keys and the final selection. It rejects nested
+paths excluded by known closed producer schemas before execution. Dynamic code,
+open schemas, unions and conditional control flow may leave shapes unknown;
+passing inspection does not prove those paths exist at runtime.
+
+| Producer | Value available downstream |
+| --- | --- |
+| Host tool called with `as: "read"` | `read.content` and optional `read.details`; not the fields inside `details` at top level |
+| Agent/extract with `out: "Row", as: "row"` | The schema-valid Row at `row`, not `{row: Row}` inside it |
+| Code with `as: "total"` returning a number | The number at `total`; returning `{total: number}` adds a second wrapper |
+| Map with an agent body using `as: "row"` | An array of Row values; no `row` wrapper on each item |
+| Map with a chain body and `resultPath: "row"` | An array of Row values selected from each completed body state |
+
+Without `resultPath`, a chain map body retains the whole item state. That is not
+the same as collecting its last step. After mapping, an array is still an array:
+if the final contract is an object, explicitly assemble that object and point
+`output.path` to it. Preserve the same distinction for tool result schemas and
+final answer schemas. Inspection does not execute transforms or prove these
+runtime shapes; check the reported value and contract when execution fails.
+
+An `escalate` node always requires `when`. Inside a route branch, the branch-taken predicate below makes escalation unconditional for that branch; outside a branch, provide a predicate for the actual stopping condition.
+
+A `route` needs a nonempty `state` map and at least two named branch objects with `body` nodes. This fragment uses the release review's `changes` state and `Report` schema:
+
+```json
+{
+  "node": "route", "label": "check-migration-detail", "as": "routing",
+  "state": { "changes": "{changes}" },
+  "instructions": "Can a maintainer follow every supplied migration action without guessing missing details?",
+  "branches": {
+    "ready": {
+      "criteria": "Every action specifies the concrete client change needed.",
+      "body": {
+        "node": "extract", "label": "summarize-ready-changes",
+        "instructions": "Summarize the supplied migration actions and return changes unchanged.",
+        "state": { "changes": "{changes}" }, "out": "Report", "as": "report"
+      }
+    },
+    "needs_details": {
+      "criteria": "Any action lacks a required detail or the supplied changes conflict.",
+      "body": {
+        "node": "escalate", "label": "request-migration-details",
+        "when": { "predicate": "field_equals", "path": "routing.taken", "value": "needs_details" },
+        "kind": "needs_input", "stage": "migration", "summary": "Migration details need clarification."
+      }
+    }
+  },
+  "unsure": { "branch": "needs_details", "gte": 0.8 }
+}
+```
+
+`unsure` selects the conservative branch below its confidence gate. Preserve the raw decision evidence; reaching `ready` does not prove migration correctness.
+
+Mechanical checks belong in predicates; semantic questions belong in agent/Jev nodes. Code is trusted JavaScript, not a sandbox, and requires the user's trusted run in the extension. Do not turn an unavailable tool or missing verifier into generated code that bypasses the host.
+
+## Code transforms and schema references
+
+Read the complete fictional [evidence gate](../examples/evidence-gate.json) and its [input](../examples/evidence-gate.input.json). It preserves a supplied claim and evidence, asks one Jev question, and gates the raw yes-probability in code before returning a typed record. It uses no agent or tool; running it with a real judge still needs Jev. The repository test uses a fake judge and proves interface behavior, not semantic quality.
+
+A code node permits **only** `node`, `label`, `code`, and optional `as`. Its `code` is a single synchronous function expression, such as `(s) => ({ count: s.items.length })`, not a bare statement body. The function receives the **full accumulated workflow state** as its first argument; it does not receive a scoped prompt map. Do not add `state`, `requires`, `out`, or `instructions` to a code node.
+
+Native inspection uses nonexecuting syntax/mechanical validation, equivalent to SDK `validateWorkflow(workflow, {executeCode: false})`. It neither evaluates code factories nor probes their outputs. The ordinary SDK validation default is for trusted code and may execute factories/probes. Neither mode is a sandbox or a proof that the eventual result will satisfy the output schema.
+
+Use synchronous data operations such as `Math`, `JSON`, `Array`, `Object`, `Map`, and `Set`. The current executor shadows `Date`, `Promise`, timers, host/network globals, and `Function`; they are unavailable even in a trusted run. For example, derive calendar-month sequences from integer year/month pairs rather than `new Date(...)`. This catches accidental host dependencies; it is not an isolation or security boundary.
+
+- With `as: "result"`, the returned value is stored at `state.result`; do not also wrap it in `{result: ...}`.
+- Without `as`, return an object patch: its top-level fields shallow-merge into state. Other state keys remain; returning a nested object replaces that entire top-level value. A non-object or array return is stored under the node's label instead, so use an object for patch semantics.
+- Do not mutate the input state. Return new values; do not return a Promise. Code remains trusted host JavaScript, not a sandbox.
+
+A node's `out: "Record"` names a sibling catalog schema directly. Inside a schema, the same sibling is referenced as `{"$ref":"#/definitions/Record"}`, **not** `{"$ref":"Record"}`. The example's input and result schemas both use this form. A `judge` has no `instructions` field: put each complete question in its output schema property's `description` (and its decision criteria in `criteria`, when needed).
+
+### Gate the raw probability, not the decoded boolean
+
+For a judge with `as: "check"` and boolean question `supported`, read:
+
+```js
+(s) => {
+  const p = s['check$answers']?.answers?.supported?.noul;
+  return {
+    accepted: typeof p === 'number' && Number.isFinite(p) && p >= 0.90 && p <= 1
+  };
+}
+```
+
+With `as: "gate"`, this stores `gate.accepted`. Missing, malformed, nonfinite, or out-of-range probabilities fail closed. Follow it with an `escalate` whose `when` is `{predicate: "field_equals", path: "gate.accepted", value: false}`, as in the example. The threshold is illustrative policy, not a calibrated accuracy guarantee.
+
+`check.supported` is only the decoded boolean (yes at probability 0.5); it does **not** prove a 0.90 threshold. Likewise, `route.unsure.gte` gates the route's **own new choice confidence**, not an upstream judge's yes-probability. Giving a route the earlier boolean or asking it to enforce a number is not this deterministic gate.