stageflow 0.42.0 → 0.44.0

package/dist/guide/knowledge/topics/pipelines.js

@@ -0,0 +1,93 @@
+export const pipelinesTopic = {
+    id: "pipelines",
+    title: "Pipelines: wiring, contracts, checks, gates and envelopes",
+    summary: "Pipeline YAML, route/entry wiring and DAG rules, io schemas between stages, verify and on_verify_fail, feedback loops, clone chains, HITL gates, envelopes and artifacts, and validation.",
+    body: `# Pipelines
+
+A pipeline file is \`<id>.pipeline.yaml\`. Required: \`id\` (should match the file name) and \`stages\` (a non-empty list of objects). Optional top level: \`model\` (default model for stages), \`agent\` (backend: \`pi\` or Claude), \`schemas\` (named JSON Schemas for \`$ref\`), \`browser\`, \`requires\` (tools on PATH), \`channels\` (default channel inherited by every stage), \`memories\` (memory ids every stage gets), \`include\` (merge stage lists from fragment files).
+
+## Where Guide saves them
+
+Every pipeline the Guide creates is \`pipelines/<id>/<id>.pipeline.yaml\`. Stage files for that pipeline (\`uses: ./<stage>.yaml\`) go in the same \`pipelines/<id>/\` folder. A folder the person names is input for a stage to read, not a place to write these files. The host writes them under \`pipelines/<id>\` even when a tool call passes another directory. Leave \`project_root\` unset. An existing pipeline is edited at the path already on disk.
+
+## Stage entries
+
+Each entry is either inline (\`system_prompt\`, \`io\`, …) or \`uses: ./stage.yaml\` (path relative to the pipeline file). On a \`uses:\` wrapper you may add only wiring (\`route\`, \`entry\`, \`on_verify_fail\`, \`replay_safe\`, and for a clone emitter \`clone_cap\`/\`clone_mode\`) plus \`mcp\`, \`secrets\`, \`requires\`, \`browser\`. Any other body key beside \`uses:\` fails (\`pipeline.stage_uses_inline_conflict\`). \`skill\` and \`channels\` are body-only.
+
+## Wiring: \`route\` and \`entry\`
+
+Wiring lives on the **source** stage. \`needs\`, \`fork\`, \`feedback_loop\` (top level), \`route_select\` and \`allow_none\` are rejected with a hard error. Do not write them.
+
+\`\`\`yaml
+stages:
+  - id: clarify
+    uses: ./clarify.yaml
+    entry: true
+    route:
+      - to: research
+      - to: validation
+  - id: research
+    uses: ./research.yaml
+    route:
+      - to: synthesize
+  - id: validation
+    uses: ./validation.yaml
+    route:
+      - to: synthesize
+  - id: synthesize
+    uses: ./synthesize.yaml
+\`\`\`
+
+- Mark at least one root \`entry: true\`.
+- Several \`to:\` entries fan out; every listed target stays on the graph and runs after the source succeeds. The agent does not pick which ones run.
+- \`if\` on a route entry skips that target unless a condition on the source's output payload holds. Leaf: \`{ field, op, value }\`; composition: \`all\`, \`any\`, \`not\`. Operators: \`eq\`, \`ne\`, \`gt\`, \`gte\`, \`lt\`, \`lte\`, \`in\`, \`not_in\`. The \`field\` path must be a **required** property in the source \`io.output.schema\` (no arrays, no optional fields). There is no \`exists\` operator and no else branch. Bad \`if\` is \`pipeline.route_if_invalid\`.
+- \`on:\` (\`succeeded\`, \`failed\`, \`skipped\`) only stops skip-cascade. Write \`succeeded\`, not \`success\` (envelope status). It does **not** launch a stage after a failure. A child always needs a succeeded parent. For branching, use \`if\` on a succeeded payload.
+- A stage with two or more parents is a **join**. It waits until every parent is finished, runs if at least one succeeded, stays pending (run fails) if any parent failed, and is skipped if all parents skipped. It receives every succeeded parent's envelope.
+- Cycles and backward edges are \`pipeline.dag_error\`. Going back is only possible with a loop entry.
+
+## Contracts: \`io\`
+
+Every stage body must have \`io.input.schema\` and \`io.output.schema\` (both required; missing is \`stage.invalid_io\`). The root must be \`type: object\`. Supported: \`object\`, \`string\`, \`number\`, \`integer\`, \`boolean\`, \`array\`, with \`properties\`, \`required\`, \`items\`, \`additionalProperties\` (boolean), \`minItems\`, \`maxItems\`, \`enum\`, \`minimum\`, \`maximum\`, \`pattern\`, \`minLength\`, \`maxLength\`, \`nullable\` on nested nodes. On each edge the child's input schema must be a structural subset of the parent's output schema, or load fails with \`pipeline.io_incompatible\`. The entry stage's input is matched against the task's \`input\` (missing \`input\` counts as \`{}\`).
+
+## Checks: \`verify\` and \`on_verify_fail\`
+
+\`verify\` is one list on the stage body. Each item has \`id\`, \`type\`, and \`when\` (\`[emit]\`, \`[after]\` or both).
+- Emit-phase (soft, in the same session; the agent can fix and retry): \`gate\` (the last \`ask_operator\` exchange of that kind this attempt must be accepted), \`artifact\` with \`basename\` (the name must be in the envelope's artifacts list).
+- After-phase (Stageflow checks after the agent claims success): \`command\` (runs \`bash -c\`, needs exit 0), \`artifact\` with \`path\` and optional \`nonempty\`, \`checklist\` (agent attestation, not proof), \`payload_schema\`, \`checkout_changes\` (the checkout really changed), \`browser_login\`.
+- Defaults: \`gate\` is emit; \`command\`, \`checklist\`, \`payload_schema\`, \`checkout_changes\` are after; \`artifact\` must set \`when\`.
+
+\`on_verify_fail\` sits on the pipeline entry and needs at least one after-phase check:
+- \`mode: repair\` with \`max_attempts\`, \`retry_safety: idempotent\`, \`include_failed_checks\` starts fresh attempts automatically.
+- \`mode: manual\` with \`retry_safety\` leaves the stage failed until a person chooses Retry with guidance or Stop recovery. Use manual for anything with side effects (publishing, payments, sending).
+
+## Feedback loops
+
+A \`route\` entry \`{ type: loop, to, max_replays, on_max_replays, replay_session }\` lets a later stage send work back to an earlier ancestor. \`on_max_replays\` is \`require_continue\` or \`wait_for_human\` (a person decides extend / continue / abandon). \`replay_session\` is \`resume\` or \`new_session\`. One loop entry per stage, no \`if\` on it. Mark one-shot stages \`replay_safe: false\`; a loop whose path crosses one fails validation. The source must emit \`feedback_loop: { action: continue }\` or \`{ action: send_back, target }\` on success.
+
+## Clone chain (one run per list item)
+
+Emitter → clone child → join. The emitter's output has exactly one array property whose items are \`{ $ref: "#/schemas/<Name>" }\`; the child's whole input schema is that same \`$ref\`. The emitter entry needs \`clone_cap\` (≥ 1) and \`clone_mode\` (\`parallel\` or \`sequential\`). An empty array or more items than the cap fails the emitter's emit; gate the zero-item case earlier. Every clone must succeed for the join to run. \`clonable\`, \`clone_actions\` and \`clone_forks\` are rejected.
+
+## Questions to a person (HITL)
+
+A stage with a non-empty \`gate_kinds\` list (\`free_text\`, \`confirm\`, \`multi_question\`, \`artifact_backed\`) gets the \`ask_operator\` tool. Omitted or \`[]\` means no tool. The run waits until a person answers in the Inbox or the run page. To make the approval binding, add a \`verify\` item \`{ type: gate, kind: ... }\`; otherwise the agent could emit success without waiting.
+
+## Envelopes and artifacts
+
+A stage ends only when the agent calls \`emit_stage_envelope\` with \`status\` (\`success\`/\`failure\`), a non-empty \`summary\`, \`artifacts\` (list, may be empty) and \`payload\` (validated against \`io.output.schema\` on success). If the agent stops without emitting, Stageflow sends up to two reminders, then fails the stage (\`missing emit_stage_envelope\`). A \`failure\` envelope skip-cascades single-parent children.
+
+### Artifact contract
+
+Cross-stage **file** handoff is declared artifacts plus the envelope — not checkout edits and not \`work/\`.
+
+1. **Durable writes only via \`write_stage_artifact\`.** The tool writes under the current attempt's artifacts directory and returns a run-relative path for the envelope list. Bash/\`cp\` into a sandbox desk path (for example \`/workspace/artifacts\`) does not persist as a host handoff file.
+2. **Emit list ≠ disk until emit checks pass.** Listing a path in \`artifacts\` is a claim. On success emit, a non-empty list is accepted only when each path is an existing regular file under **this** attempt's artifacts dir (emit disk-truth). Empty \`artifacts: []\` stays valid. Optional after-phase \`verify\` \`type: artifact\` is separate hard proof; do not add it on every new stage by default.
+3. **Facts travel in \`payload\`.** Put required fields the next stage needs in \`io.output.schema\`. Use artifacts for files; put pointers or basenames in payload when useful.
+4. **Sandbox consumers read grants (or payload), not host attempt paths.** Under a stage container, each prior file is copied read-only to the sandbox path listed in the stage assignment (a file grant is that file, under \`/workspace/grants/<stage>/…\`). Do not author prompts that \`read stages/<id>/attempts/…/artifacts/…\` as the handoff. Unbound (no container) stages can still open run-relative artifact paths on the host.
+5. **\`/workspace/work\` is never handoff.** Scratch only; it is not copied into the next stage's desk as an artifact grant.
+
+## Validation
+
+\`validate\` (tool) or \`sf validate\` checks shape, \`uses:\` paths, wiring, \`io\` compatibility, verify rules, model resolution, MCP names, channels and memories. It does not check provider keys, env vars or a live MCP connection; those fail at run start.
+`,
+};

package/dist/guide/knowledge/topics/stages.d.ts

@@ -0,0 +1,2 @@
+import type { GuideKnowledgeTopic } from "../index.js";
+export declare const stagesTopic: GuideKnowledgeTopic;

package/dist/guide/knowledge/topics/stages.js

@@ -0,0 +1,54 @@
+export const stagesTopic = {
+    id: "stages",
+    title: "Stage fields, what each one costs and risks",
+    summary: "Every stage field (system_prompt, model, io, verify, gate_kinds, skill, mcp, browser, channels, secrets, requires, timeout_ms) with what it does, where it goes, and its cost or risk.",
+    body: `# Stages
+
+A stage is one step. Each attempt runs in a fresh agent session on the Host. A stage body lives inline in the pipeline or in its own YAML file (\`uses: ./name.yaml\`). An external stage file must have \`id\` equal to the file name stem and must not contain wiring (\`route\`, \`entry\`, \`on_verify_fail\`, \`clone_cap\`, \`clone_mode\`). The Guide stores that file in the same \`pipelines/<id>/\` folder as its pipeline. A path the person names does not change that folder.
+
+## Body fields
+
+| Field | Required | What it does | Cost / risk |
+|---|---|---|---|
+| \`system_prompt\` | yes | The stage's instructions. | Vague prompts cause wrong envelopes and repair loops. Say exactly what to put in \`payload\`. |
+| \`model\` | no if a default exists | \`provider/model\` id. Resolved as stage, then pipeline \`model\`, then \`stageflow.yaml\` \`model\`. None at all fails load. | Bigger models cost more per attempt. Cheap models fail structured output more often. |
+| \`io\` | yes | \`io.input.schema\` and \`io.output.schema\`, both required. Output is checked on every success emit. | A strict output schema rejects bad envelopes early. Over-strict schemas make the agent retry. |
+| \`verify\` | no | Checks at emit time or after the agent claims success. | \`command\` runs a shell command on the Host with the stage's environment: same trust level as running the command yourself. |
+| \`gate_kinds\` | no | Non-empty list turns on \`ask_operator\` (\`free_text\`, \`confirm\`, \`multi_question\`, \`artifact_backed\`). | The run stops until a person answers. Evals cannot answer gates. \`sf run --skip-gates\` fails the stage at the first wait. |
+| \`skill\` | no | Binds one installed skill; its instructions are added to the prompt. Body only (not on a \`uses:\` wrapper). | A skill that is not installed fails the stage before the agent starts. |
+| \`mcp\` | no | List of MCP server names the stage may use. | Each server is a process or remote service; tools can act outside Stageflow. Connect failures or unset variables fail the stage at run time. |
+| \`secrets\` | no | Host secret names the stage may receive (for example \`GITHUB_TOKEN\`, or \`{ name: NPM_TOKEN, as: env }\`), or console MCP secrets used only to fill MCP placeholders. | Every secret granted widens what the agent can do. Grant only what the step needs. |
+| \`requires\` | no | \`[{ tool, version? }]\` binaries that must be on PATH. Checked before the run starts. | Stageflow never installs tools. |
+| \`browser\` | no | A real browser session (\`profile\`, \`headed\`, \`allow_domains\`, \`login_url\`, \`check\`). Adds an \`agent-browser\` requirement. | The agent drives a logged-in browser. \`allow_domains\` is not enforced for profile stages. Sites may forbid automation. |
+| \`channels\` | no | One send channel: \`connection\`, pinned \`to\`, \`operations: [send]\`. Gives the \`send_message\` tool. Body only. | Sends real messages. Only one channel per stage. Pi backend only. |
+| \`timeout_ms\` | no | Wall-clock budget per attempt. Default 3600000 (60 minutes). | On timeout the attempt fails but the session is kept so a person can Resume. |
+
+Pipeline-entry wiring (not body): \`route\`, \`entry\`, \`on_verify_fail\`, \`replay_safe\`, \`clone_cap\`, \`clone_mode\`. \`memories\` is pipeline-level only; a stage cannot list its own.
+
+## Tools every stage has
+
+\`emit_stage_envelope\` (ends the stage), \`write_stage_artifact\` (durable files under the attempt artifacts folder — the only durable handoff write) and, when \`gate_kinds\` is non-empty, \`ask_operator\`. On Pi, stages also have the Pi coding agent's own file and shell tools (for example \`read\` and \`bash\`). With memories attached, Pi stages get \`read_memory\`, \`replace_memory\`, \`add_memory_card\`, \`update_memory_card\`, \`read_memory_card\`, \`search_memory_cards\`. With a channel, Pi stages get \`send_message\`.
+
+Artifact handoff: list paths from \`write_stage_artifact\` on emit (non-empty lists must exist on disk). Under a stage sandbox, a later stage reads each prior file at the sandbox path in its assignment (a file grant is the file itself, under \`/workspace/grants/<stage>/…\`) or takes facts from \`payload\` — not host \`stages/…/artifacts\` paths and not \`/workspace/work\`. \`create_stage\` does not auto-add after-phase artifact \`verify\`; add that only when you need hard proof of a named file.
+
+## Stage environment
+
+A stage never gets the Host's raw environment. It gets an allowlist (PATH, locale, proxy, \`STAGEFLOW_HOME\`, …) plus the secrets it declares. Provider API keys are never put in the stage environment; model auth goes through the Host's credential file.
+
+## Backends
+
+The default backend is Pi. The Claude backend (pipeline or manifest \`agent\`) does not provide \`send_message\` or the memory tools, so a stage with \`channels:\` or a pipeline with \`memories:\` fails at stage start there.
+
+## Creating stages with tools
+
+- \`create_stage\` adds a file-backed stage (\`uses: ./<id>.yaml\`) to a pipeline. If you pass no \`model\`, it writes the Host's current default model into the stage file. If you pass no \`io\`, it writes a minimal object/object \`io\`.
+- \`edit_stage\` changes body fields (via \`patch\`, \`body\`, \`system_prompt\`, \`model\`, \`io\`) and/or the pipeline entry (\`route\`, \`entry\`, \`uses\`, \`pipeline_entry\`).
+- \`create_stage_file\` writes a standalone stage file that is not wired into any pipeline (\`id\`, \`system_prompt\`, optional \`model\`, \`gate_kinds\`, \`skill\`).
+- \`write_catalog_file\` overwrites an existing stage file; an invalid write is restored.
+- Each pipeline tool validates and writes nothing when invalid, unless \`allow_invalid\` is set to build up step by step.
+
+## Recovering a stage in a run
+
+Retry (new attempt), Resume (same session, for interrupted or timed-out attempts), Abandon (stop a running stage), and for manual recovery Retry with guidance or Stop recovery. Tools: \`retry_stage\`, \`resume_stage\`, \`abandon_stage\`, \`recover_manual_stage\`, \`stop_manual_recovery\`.
+`,
+};

package/dist/guide/knowledge/topics/tasks.d.ts

@@ -0,0 +1,2 @@
+import type { GuideKnowledgeTopic } from "../index.js";
+export declare const tasksTopic: GuideKnowledgeTopic;

package/dist/guide/knowledge/topics/tasks.js

@@ -0,0 +1,52 @@
+export const tasksTopic = {
+    id: "tasks",
+    title: "Tasks: what a run starts from",
+    summary: "Task file fields (id, goal, context, constraints, input, checkout, repository, ref), how input meets the entry stage, standalone vs pipeline tasks, and dynamic tasks built by triggers.",
+    body: `# Tasks
+
+A task file is \`<id>.task.yaml\`. Every run is one pipeline plus one task. The task says what this run should do; the pipeline says how.
+
+## Fields
+
+| Field | Required | Meaning |
+|---|---|---|
+| \`id\` | yes | Task identifier. Tools expect lowercase kebab-case, 1 to 64 characters. |
+| \`goal\` | yes | What the run should accomplish. Every stage sees it. |
+| \`context\` | no | Background for the agents. |
+| \`constraints\` | no | Boundaries the agents must respect. |
+| \`input\` | no | Structured object matched against each entry stage's \`io.input.schema\`. Omitted means \`{}\`. |
+| \`checkout\` | no | Path (relative or absolute) to an existing working folder. Conflicts with \`repository\`. |
+| \`repository\` | no | GitHub \`owner/repo\`; the Host creates its own worktree. Requires \`ref\`. |
+| \`ref\` | with \`repository\` | Branch, tag or SHA. |
+
+Do not set both \`checkout\` and \`repository\`. The loader also accepts \`checkout: { branch, base }\` (Stageflow creates or reuses a git worktree), \`run_branch_template\` and \`git_identity\`; these are not in the public field table, so prefer the documented forms.
+
+## How \`input\` meets the pipeline
+
+- If an entry stage's \`io.input.schema\` requires fields, the task must provide them under \`input\`. A missing or wrong \`input\` makes run start fail with \`task.invalid_shape\`, even though validating the task file alone succeeds.
+- A prose-only task (no \`input\`) is fine when the entry stage's input schema is an empty object.
+- Non-entry stages also see the whole task in their prompt, plus their parents' envelopes.
+
+## Standalone task vs pipeline task
+
+- \`create_task_file\` writes a standalone catalog task (\`directory\`, \`id\`, \`goal\`, optional \`context\`, \`constraints\`, \`checkout\`, \`repository\`, \`ref\`). It is not tied to a pipeline; any pipeline can run with it. \`update_task_file\` replaces it by id (\`goal\` required; pass \`null\` or empty to drop an optional field).
+- \`create_task\` / \`edit_task\` write the task that sits beside a pipeline package (same folder).
+- \`import_task_file\` turns a GitHub issue into a task (title becomes goal and id). It calls GitHub.
+- Neither tool set writes \`input\` as a named argument on standalone tasks; to set \`input\` on a pipeline task pass it inside \`body\` of \`create_task\` / \`edit_task\`.
+
+## Tasks and triggers
+
+- A trigger with \`task: <id>\` (catalog mode) always runs that catalog task. Supplying a different task at fire time is refused (\`trigger.task_override_not_allowed\`).
+- A trigger without \`task\` (dynamic mode) needs a task at every fire. GitHub pull request triggers build one from the PR (\`goal\` summarizes it, \`input\` holds \`action\`, \`number\`, \`title\`, \`url\`, \`author\`, \`repo\`, \`updatedAt\`). Webhook triggers put the JSON body in \`input\`. Email triggers put \`from\`, \`subject\`, \`date\`, \`text\` in \`input\`. A manual fire must pass a task inline, otherwise \`trigger.task_required\`.
+- A schedule trigger has nothing to build a task from, so it needs a catalog task.
+- When the task is built from an event, design the entry stage's \`io.input.schema\` around that event shape.
+
+## Repository-bound tasks
+
+With \`repository\` + \`ref\`, the stage works in a Host-owned worktree. Repository-bound stages read the repository's own \`.mcp.json\` and \`.pi/skills\` as untrusted workspace content and never see console MCP servers or console secrets. Evals cannot use a checkout or repository: eval cases run with neither.
+
+## Starting a run
+
+The console's Start a run picks a task and a pipeline (\`#/new\`). Tools: \`start_run\` (pipeline and task), \`run_stage\` (one stage), \`rerun\`. The CLI is \`sf run --pipeline <path> --task <path>\` (paths, not ids).
+`,
+};

package/dist/guide/knowledge/topics/triggers.d.ts

@@ -0,0 +1,2 @@
+import type { GuideKnowledgeTopic } from "../index.js";
+export declare const triggersTopic: GuideKnowledgeTopic;

package/dist/guide/knowledge/topics/triggers.js

@@ -0,0 +1,68 @@
+export const triggersTopic = {
+    id: "triggers",
+    title: "Triggers: manual, schedule and event",
+    summary: "Trigger YAML, catalog vs dynamic task mode, manual / schedule (cron) / event (GitHub pull requests, signed webhook, email) adapters, which combinations work, and the trigger tools.",
+    body: `# Triggers
+
+A trigger file is \`<id>.trigger.yaml\`. It binds one id to an existing pipeline (and usually a task) so a run can start without someone picking files. Agent schedules are different: an agent's own \`schedule\` field starts an agent turn, not a pipeline run.
+
+## Fields
+
+| Field | Required | Meaning |
+|---|---|---|
+| \`id\` | yes | Trigger id, unique in the project. |
+| \`pipeline\` | yes | Id of a catalog pipeline. |
+| \`task\` | no | Id of a catalog task. Its presence is the mode switch (below). |
+| \`kind\` | yes | \`manual\`, \`schedule\` or \`event\`. |
+| \`enabled\` | yes in the file | A disabled trigger refuses to fire (409). \`create_trigger\` defaults it to \`true\`. |
+| \`schedule\` | for \`schedule\` | \`{ cron, timezone? }\`. Cron is checked when created. |
+| \`event\` | for \`event\` | \`{ source, match?, config? }\`. |
+
+The pipeline and task ids must exist in the catalog; \`create_trigger\` refuses unknown ids (422) and \`validate\` reports \`trigger.unknown_pipeline\` / \`trigger.unknown_task\`.
+
+## Catalog mode vs dynamic mode
+
+- **\`task\` set (catalog mode).** Every fire runs that task. Passing a task at fire time is refused (\`trigger.task_override_not_allowed\`).
+- **\`task\` absent (dynamic mode).** Every fire must supply a task. GitHub, webhook and email adapters build one from the event. A manual fire must pass one inline (\`fire_trigger\` with \`task\`, or \`sf trigger fire --task-inline\`), else \`trigger.task_required\`. The console's Fire button is disabled for dynamic triggers.
+
+## Kinds
+
+**manual.** Fires only when asked: console Fire, \`fire_trigger\`, \`sf trigger fire\`, \`POST /api/triggers/<id>/fire\`.
+
+**schedule.** While a Host is running, a scheduler checks about every 30 seconds and fires when the cron time passes. If the Host was down, it fires **once** for the latest missed time, not once per missed slot. A schedule trigger needs a catalog task: in dynamic mode the timer has no task, so every automatic fire fails with \`trigger.task_required\`. The console blocks that combination on save; \`create_trigger\` does not, so check it yourself.
+
+**event, \`source\` starting with \`github.\`** (console tile uses \`github.pull_request\`). Polls the GitHub pull request list of \`event.config.repo\` (\`owner/repo\`) about every 60 seconds, with a token from \`event.config.secretRef\` (default \`GITHUB_TOKEN\`). Only pull requests, not issues or repo pushes outside a PR. The first poll of a repo only records a cursor (and per-PR head SHAs) and fires nothing for old PRs; the same quiet baseline runs when a cursor already exists but heads were never written (upgrade). \`match.action\` is **required** for github sources — \`create_trigger\` / validate reject omit-match. Actions: \`opened\` (brand-new PR: equal created/updated timestamps, or created after the cursor), \`synchronize\` (head SHA changed — use this for every push), \`updated\` (other activity, same head; also aged PRs with no prior SHA), \`merged\`, \`closed\`. \`match\` can also filter \`author\` and the other normalized fields; exact equality only.
+
+**event, \`source: webhook\`.** Gets its own endpoint \`POST /api/triggers/<id>/webhook\`, verified by HMAC-SHA256 over the raw body. \`event.config\`: \`secretRef\` (required, name of the Host secret), \`header\` (required, for example \`x-hub-signature-256\`), \`scheme\` (\`hex\` default or \`base64\`). Wrong signature is 401. A body that does not match \`match\` returns 200 with \`fired: false\`. The Host listens on loopback by default, so an outside sender needs a tunnel or an exposed deployment.
+
+**event, \`source\` starting with \`email.\`** (console uses \`email.message\`). Holds an IMAP IDLE connection to a mailbox the user supplies. \`event.config\`: \`host\`, \`port\`, \`user\`, \`secretRef\` (password or app password). \`match\` compares \`from\`, \`subject\`, \`date\`, \`text\` by exact equality (a subject filter must equal the whole subject). No attachments. After creating or changing an email trigger, restart the Host if the mailbox does not connect.
+
+**Any other \`event.source\`** loads and validates but nothing watches it. It can only be fired manually.
+
+## What works end to end
+
+| Setup | Works automatically |
+|---|---|
+| manual + catalog task | fires when asked |
+| schedule + catalog task | yes |
+| schedule + no task | no, every tick fails |
+| GitHub PR + catalog or dynamic | yes |
+| webhook + catalog or dynamic | yes, if reachable and the secret is set |
+| email + catalog or dynamic | yes, with a real mailbox and the secret set |
+| other event source | no, manual fire only |
+
+All automatic triggers need a running Host (\`sf ui\`, \`sf mcp\` or Docker). They do not run from the CLI alone.
+
+## Secrets
+
+Trigger secrets are referenced by name (\`secretRef\`) and read from the Host environment or a \`_FILE\` variant. Never put a token or password in trigger YAML.
+
+## Tools
+
+\`list_triggers\`, \`get_trigger\`, \`create_trigger\` (\`directory\`, \`id\`, \`pipeline\`, optional \`task\`, \`kind\`, \`schedule\`, \`event\`, \`enabled\`), \`update_trigger\` (replaces the whole definition; the id cannot change), \`set_trigger_enabled\`, \`fire_trigger\`. There is no delete tool: to stop a trigger, disable it; removing it means deleting the file by hand.
+
+## Before you add a trigger
+
+Run the pipeline once by hand with the same task and confirm it succeeds. A trigger repeats whatever the pipeline does, including its cost and any messages it sends.
+`,
+};

package/dist/guide/knowledge/topics/troubleshooting.d.ts

@@ -0,0 +1,2 @@
+import type { GuideKnowledgeTopic } from "../index.js";
+export declare const troubleshootingTopic: GuideKnowledgeTopic;

package/dist/guide/knowledge/topics/troubleshooting.js

@@ -0,0 +1,85 @@
+export const troubleshootingTopic = {
+    id: "troubleshooting",
+    title: "Troubleshooting: common findings and errors",
+    summary: "What common validation finding codes and run, trigger, channel, agent and eval errors mean, and how to fix each one.",
+    body: `# Troubleshooting
+
+Run \`validate\` (or \`validate_catalog_draft\` for a draft, \`validate_agent\`, \`validate_eval\`) first. Findings have a \`code\`; errors block, warnings do not.
+
+## Pipelines and stages
+
+| Code or message | Meaning and fix |
+|---|---|
+| "model is required (set on stage, pipeline, or stageflow.yaml)" | No model anywhere in the chain. Set pipeline \`model\` or \`stageflow.yaml\` \`model\`. |
+| \`stage.invalid_io\` | A stage body lacks \`io.input.schema\` or \`io.output.schema\`. Both are required. |
+| \`pipeline.io_incompatible\` | A child's input schema is not a subset of a parent's output schema. Make the child require only fields the parent's output declares. |
+| \`pipeline.route_if_invalid\` | Bad \`if\`: unknown operator, field not required in the source output, array path, mixed shape, or \`if\` on a loop entry. |
+| \`pipeline.route_all_gated\` (warning) | Every forward route has \`if\`; the run may skip all successors. |
+| \`pipeline.model_applies\` (warning) | The pipeline \`model\` fills stages. Informational. |
+| \`pipeline.dag_error\` | A cycle, or a backward or circular edge without a \`type: loop\` entry. |
+| \`"needs" is no longer supported …\` (also \`fork\`, \`feedback_loop\`, \`route_select\`, \`allow_none\`) | Old wiring. Put \`route: [{ to: child }]\` on the parent and \`entry: true\` on roots; loops become a \`type: loop\` route entry. |
+| \`pipeline.stage_uses_inline_conflict\` | Body keys beside \`uses:\`. Move them into the stage file. |
+| \`pipeline.stage_wrapper_skill_rejected\` | \`skill\` on a \`uses:\` wrapper. Put it in the stage file. |
+| \`stage.unresolved_schema_ref\` | A \`$ref\` stage validated alone; validate the pipeline that defines \`schemas\`. |
+| \`catalog.legacy_yaml\` (warning) | Old contract keys (\`payload_schema:\`, \`pre_emit_checks\`, \`completion\`, \`recovery\`). Convert with \`sf migrate-yaml --write\`. |
+| \`pipeline.invalid_memories\` / \`pipeline.memory_unavailable\` | Duplicate memory id, or a memory that does not exist on this Host. Create it first. |
+| \`pipeline.invalid_shape\` | Wrong structure, including \`memories\` on a stage entry. |
+| \`stage.invalid_channels\` / \`pipeline.invalid_channels\` | Bad \`channels\` shape, or more than one channel on a stage. |
+| \`stage.channel_unavailable\` | Connection missing or disabled, operation unsupported, or recipient invalid for the provider. |
+| \`stage.invalid_browser\` | Unknown \`browser\` key, or \`path\`, \`scope\`, \`secret\`, launch options in YAML. |
+| \`stage.invalid_requires\` / \`pipeline.invalid_requires\` / \`pipeline.requires_conflict\` | Bad \`requires\` entries, or version ranges that cannot both hold. |
+| \`stage.unknown_secret\` | A \`secrets\` name that is neither a console MCP secret nor a registered Host secret. |
+| "Unknown MCP server" | A stage \`mcp\` name in neither \`.mcp.json\` nor the console list. |
+| Clone chain errors | Extra routes on emitter or child, \`if\` on chain edges, extra join parents, inline array items, \`clone_cap\`/\`clone_mode\` on the wrong stage. |
+
+## Running
+
+| Symptom | Meaning and fix |
+|---|---|
+| \`task.invalid_shape\` at run start | The task's \`input\` does not match the entry stage's \`io.input.schema\` (missing \`input\` counts as \`{}\`). |
+| \`channel_check_failed: <connection>: <reason>\` | Live connection check failed. Fix the key or recipient; \`test_connection\`. |
+| \`missing emit_stage_envelope\` | The agent ended without a valid envelope after two reminders. Make the prompt name the payload fields; check \`io.output.schema\` is achievable. |
+| \`provider error: …\` | Usually a missing or invalid provider key or an unavailable model. Check Settings → Providers. |
+| \`stage timed out after …ms\` | Raise \`timeout_ms\` or simplify; the session is kept, so Resume works. |
+| Run waiting | A stage asked a person. Answer in the Inbox. |
+| Stage failed after-phase verify | See the stage's verification history (\`get_stage_verification\`). With \`mode: manual\`, use Retry with guidance or Stop recovery; plain retry is refused. |
+| Join never runs | One parent failed. A join does not run on a failed parent. |
+| "waiting for browser profile" | Another run holds the browser profile until it ends. |
+
+## Triggers
+
+| Code | Meaning |
+|---|---|
+| \`trigger.invalid_shape\` | Missing or wrong \`id\`, \`pipeline\`, \`kind\`, \`enabled\`. |
+| \`trigger.unknown_pipeline\` / \`trigger.unknown_task\` | The id is not in the catalog. |
+| \`trigger.task_required\` | Dynamic trigger fired without a task (always the case for a schedule without \`task\`). |
+| \`trigger.task_override_not_allowed\` | A task was passed to a catalog-mode trigger. |
+| 409 on fire | The trigger is disabled. |
+| Webhook 401 | Signature does not match the secret and header. |
+
+## Channels
+
+\`CHANNEL_AUTH_FAILED\` (bad credential), \`CHANNEL_UNAUTHORIZED\` (missing scope, or stage did not declare the channel), \`CHANNEL_SECRET_UNAVAILABLE\` (env secret not set on this Host), \`CHANNEL_TARGET_INVALID\`, \`CHANNEL_RECIPIENT_REJECTED\` (bot not added, user did not start the bot or text the line), \`CHANNEL_WINDOW_CLOSED\` (WhatsApp 24-hour window; pin a template), \`CHANNEL_RATE_LIMIT\`/\`CHANNEL_TIMEOUT\`/\`CHANNEL_CONNECTION_FAILED\` (retryable), \`CHANNEL_PROVIDER_UNSUPPORTED\` (optional iMessage/WhatsApp packages missing), \`CHANNEL_SEND_OUTCOME_UNKNOWN\` (do not resend), \`CHANNEL_OPERATION_CONFLICT\` (same key, different content).
+
+## Agents
+
+| Code | Meaning |
+|---|---|
+| \`agent.invalid\` | Issues block the save; each has a field \`path\`. |
+| \`agent.unknown_field\`, \`agent.required\` | Typo or missing field. |
+| \`agent.ask_first_not_granted\` | \`ask_first\` names a tool the agent does not hold. |
+| \`agent.stageflow_operator_only\` | Tried to grant \`gates.decide\` or \`get_started\`. |
+| \`agent.channel_in_use\` | That connection (or its inbox) already belongs to another agent. |
+| \`agent.memory_unavailable\` | A memory id does not exist. |
+| \`agent.conflict\` | Saved from an old revision; reload and reapply. |
+| \`agent.disabled\`, \`agent.limit_reached\`, \`agent.session_busy\` | Turn refused: disabled, a limit hit, or a turn/approval already pending. |
+| \`agent.guardrail_blocked\` | A \`block_patterns\` regex matched the reply. |
+| \`agent.model_timeout\` | The model sent nothing for 180 s. |
+| \`agent.reply_undelivered\` | A channel reply failed or its outcome is unknown; Resend or Mark as delivered on the run page. |
+| Warnings: \`agent.mcp_server_unknown\`, \`agent.skill_unknown\`, \`agent.model_unknown\`, \`agent.connection_unknown\`, \`agent.channel_nobody_allowed\`, \`agent.channel_open_to_anyone\`, \`agent.shell_not_path_confined\`, \`agent.web_chat_reads_conversations\` | Advice; the agent still saves. |
+
+## Evals
+
+\`eval.target_unresolved\` (target does not load, often no default model), \`eval.grader_not_applicable\`, \`eval.judge_missing\`, \`eval.schema_grader_without_output_schema\`, \`eval.no_valid_cases\`, \`eval.cases_skipped\`, \`eval.real_tools_not_allowed\`, \`eval.user_model_missing\`, \`eval.simulator_unsupported\`, \`eval.agent_not_found\`, \`eval.agent_archived\`. At run: \`EVAL_ENGINE_UNAVAILABLE\` (install the engine), \`EVAL_NODE_TOO_OLD\`, \`EVAL_RUN_ACTIVE\`, \`EVAL_REAL_TOOLS_NOT_CONFIRMED\`, \`EVAL_INVALID\` (including an unsupported judge provider), \`budget_stopped\` (raise \`max_cost_usd\` or run fewer cases). On results: \`EVAL_STAGE_NEEDS_INPUT\`, \`EVAL_STAGE_TIMEOUT\`, \`EVAL_JUDGE_ERROR\` (judge key missing or non-JSON reply), \`EVAL_CASE_MISSING_EXPECTED\`, \`EVAL_AGENT_EMPTY_REPLY\` (provider rate limit or outage). Saving: \`FILE_CHANGED\` (reload and reapply).
+`,
+};

package/dist/guide/knowledgeTools.d.ts

@@ -0,0 +1,2 @@
+import type { OperatorAgentTool } from "../operatorAgent/types.js";
+export declare function createGuideKnowledgeTools(): OperatorAgentTool[];

package/dist/guide/knowledgeTools.js

@@ -0,0 +1,56 @@
+import { Type } from "typebox";
+import { findGuideKnowledge, GUIDE_KNOWLEDGE_TOPICS, searchGuideKnowledge } from "./knowledge/index.js";
+const SEARCH_LIMIT = 3;
+function textArg(args, key) {
+    const value = args[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function failure(error, content = {}) {
+    return { ok: false, content: { error, ...content }, error };
+}
+export function createGuideKnowledgeTools() {
+    return [
+        {
+            name: "list_guide_topics",
+            description: "List the Stageflow knowledge topics (id, title, summary). Read a topic with read_guide_topic before you explain how a part of Stageflow works, recommend a design, or say whether something is possible.",
+            parameters: Type.Object({}, { additionalProperties: false }),
+            handler: () => ({
+                ok: true,
+                content: {
+                    topics: GUIDE_KNOWLEDGE_TOPICS.map(({ id, title, summary }) => ({ id, title, summary })),
+                },
+            }),
+        },
+        {
+            name: "read_guide_topic",
+            description: "Read Stageflow knowledge. Pass { id } to get a topic's full text (ids from list_guide_topics), or { query } to get the best matching topics with a short excerpt. Prefer the limitations topic before promising a feature.",
+            parameters: Type.Union([
+                Type.Object({ id: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+                Type.Object({ query: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+            ]),
+            handler: (args) => {
+                const id = textArg(args, "id");
+                if (id !== undefined) {
+                    const topic = findGuideKnowledge(id);
+                    if (!topic) {
+                        return failure("guide.topic_not_found", {
+                            id,
+                            topics: GUIDE_KNOWLEDGE_TOPICS.map((entry) => entry.id),
+                        });
+                    }
+                    return { ok: true, content: { id: topic.id, title: topic.title, body: topic.body } };
+                }
+                const query = textArg(args, "query");
+                if (query !== undefined) {
+                    const matches = searchGuideKnowledge(query, SEARCH_LIMIT).map(({ topic, excerpt }) => ({
+                        id: topic.id,
+                        title: topic.title,
+                        excerpt,
+                    }));
+                    return { ok: true, content: { query, matches } };
+                }
+                return failure("guide.id_or_query_required");
+            },
+        },
+    ];
+}

package/dist/guide/showUi.d.ts

@@ -0,0 +1,6 @@
+import type { McpToolDeps } from "../mcp/deps.js";
+import type { OperatorAgentTool, OperatorAgentToolResult } from "../operatorAgent/types.js";
+export declare const GUIDE_UI_TOOL_NAMES: readonly ["show_ui"];
+export { GUIDE_LINK_KINDS, GUIDE_RESOURCE_KINDS, type GuideLink, type GuideLinkKind, type GuidePipelineStage, type GuideUi, } from "./cardContract.js";
+export declare function buildGuideUi(deps: McpToolDeps, args: Record<string, unknown>): Promise<OperatorAgentToolResult>;
+export declare function createShowUiTool(deps: McpToolDeps): OperatorAgentTool;