@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/llms.txt

@@ -1,6 +1,6 @@
 # jr2
 
-> A kit for agentic workflows as xstate Machines, run on Kubernetes. These are the docs of Kit version 0.6.0, as plain Markdown.
+> A kit for agentic workflows as xstate Machines, run on Kubernetes. These are the docs of Kit version 0.7.0, as plain Markdown.
 
 ## Home
 
@@ -24,14 +24,15 @@
 - [Machines and Workflows](concepts/machines-and-workflows.md): What a Machine and a Workflow are, the door of a run, the Vocabulary, and Emits.
 - [Agents and Turns](concepts/agents-and-turns.md): What an Agent is, what one Turn of an Agent holds, how a Turn ends, and what jr2 does when a Turn fails.
 - [The Menu](concepts/the-menu.md): How an Agent picks from the events that its Machine takes, and how the Machine decides what each pick does.
-- [Gates](concepts/gates.md): How a run waits for an event from a person, the CLI, the Console, a webhook or a CI job.
-- [Effects](concepts/effects.md): How a Machine runs a command, calls a URL, pushes a branch or starts a run, at most once.
+- [Gates](concepts/gates.md): How a run waits for an event from a person, the CLI, the Console, a Hook or a CI job.
+- [Effects](concepts/effects.md): How a Machine runs a command, calls a URL or an MCP tool, pushes a branch or starts a run.
 - [Workspaces](concepts/workspaces.md): How a Workflow gets a Sandbox with a git Worktree or a shared folder, and how long it keeps it.
 - [Composition](concepts/composition.md): How a Machine composes Machines that you import, and how you bind the parts that they leave Open.
 - [Charts](concepts/charts.md): How an Agent writes a Machine as data at run time, which cannot reach the process of the Orchestrator.
-- [Pools and Sources](concepts/pools-and-sources.md): How a Pool runs one worker Machine for each work item that a Source gives, and how its run ends.
+- [Pools and Sources](concepts/pools-and-sources.md): How a Pool runs one worker for each item of a Source, how a Hook brings items, and how its run ends.
 - [Architecture](concepts/architecture.md): What runs on your computer, in the cluster and in a Sandbox, and which part does what.
 - [Secrets and trust](concepts/secrets-and-trust.md): Where jr2 keeps each credential, which tokens it makes, and what a caller can see and do without one.
+- [Callers and Hooks](concepts/callers-and-hooks.md): Who acts on an Instance from outside its Machines, what each one may do, and what a Hook does.
 - [Converge](concepts/converge.md): What jr2 up makes in the cluster from your Instance folder, and the Assembly that it publishes.
 - [Durable runs](concepts/durable-runs.md): How a run survives a restart of the Orchestrator, what ends it, and how long jr2 keeps a run that ended.
 
@@ -39,13 +40,17 @@
 
 - [Start a run](guides/start-a-run.md): Start a run of a Workflow from the CLI, from the Console, or with a call to the HTTP API.
 - [Answer a Gate](guides/answer-a-gate.md): Send an event to an open Gate of a run, from the CLI, the Console, a webhook handler or a CI job.
+- [Answer a Gate from a forge](guides/answer-a-gate-from-a-forge.md): Make a Gate that a review on GitHub or GitLab answers, and that looks for the review it waits for.
+- [Steer an Agent](guides/steer-an-agent.md): Send free text to one Agent of a live run, from the CLI, from HTTP, or from the Machine itself.
 - [Watch a run](guides/watch-a-run.md): See where a run is and what its Agents do: in the CLI, in the Console, and in the pod log.
+- [Read a conversation](guides/read-a-conversation.md): Read what an Agent said and did in a run, live or after the run ended, with jr2 logs or the Console.
 - [Look inside a Sandbox](guides/look-inside-a-sandbox.md): Open a shell in the Sandbox of a run, and read the branch that its Agent works on.
 - [Cancel a run](guides/cancel-a-run.md): End a live run with CANCEL, and delete its Sandboxes or keep them to look inside.
-- [Open the Console](guides/open-the-console.md): Forward the port of the Orchestrator, open the Console, and unlock it with the Instance token.
+- [Open the Console](guides/open-the-console.md): Forward the port of the Orchestrator, open the Console, and unlock it with a token or a login.
 - [Use a local model](guides/use-a-local-model.md): Connect your Agents to a model on an OpenAI-compatible endpoint, with or without TLS and a key.
 - [Use a hosted provider or a gateway](guides/use-a-hosted-provider.md): Give your Agents a model from a hosted provider, directly or through a gateway.
 - [Give the cluster git credentials](guides/give-the-cluster-git-credentials.md): Give the cluster a token or an ssh key to clone and push your Repos, and choose which Repos a run can name.
+- [Give a Caller a scope](guides/give-a-caller-a-scope.md): Make a named token for a CI job or a bridge, give it only the scopes that it needs, and rotate it.
 - [Move from kind to a shared cluster](guides/move-from-kind-to-a-shared-cluster.md): Converge an Instance into a shared cluster, with a registry, Sandbox nodes, priority classes and a quota.
 - [Mirror the Kit images](guides/mirror-the-kit-images.md): Copy the Kit images and the Pinned image into your own registry, and make the cluster pull them from there.
 - [Upgrade the Kit version](guides/upgrade-the-kit-version.md): Move an Instance to a new Kit version. jr2 up converges it and updates the jr2 block in AGENTS.md.
@@ -55,13 +60,18 @@
 - [Write a Workflow](guides/write-a-workflow.md): Write a module in workflows/ that exports a Machine, with the input that starts a run and its Vocabulary.
 - [Bind a shipped Machine's Open parts](guides/bind-open-parts.md): Register a Machine from a package as a Workflow, and bind the parts that it leaves Open with customize().
 - [Set an Agent's access and Dials](guides/set-an-agents-access-and-dials.md): Choose what an Agent can do to the Workspace, and set the Dials and continue of one Turn.
+- [Give an Agent MCP tools](guides/give-an-agent-mcp-tools.md): Declare MCP servers in jr2.config.ts, and give an Agent the tools that it can call on each server.
 - [Cut a Worktree](guides/cut-a-worktree.md): Make a Worktree with worktree(), choose what a cut refuses, and remove a Worktree.
 - [Run a command or call a URL with an Effect](guides/run-a-command-or-call-a-url.md): Run a program or call a URL as an Effect, give it input from a pick, and route on its output.
+- [Call an MCP tool from a Machine](guides/call-an-mcp-tool-from-a-machine.md): Call a tool of an MCP server as an Effect, after the approval of a person, and route on its output.
 - [Push and sign a branch](guides/push-and-sign-a-branch.md): Push the branch of a Worktree, and sign its commits with a key that the Agent never reads.
 - [Start a run from a run](guides/start-a-run-from-a-run.md): Use a dispatch Effect to start a run of a Workflow from a Machine, in this Instance or in a different one.
 - [Add tools to the Sandbox](guides/add-tools-to-the-sandbox.md): Put the programs that your Agents use into the Sandbox Image, or run a service in a User Container.
+- [Write a tool as an MCP server](guides/write-a-tool-as-an-mcp-server.md): Write a small MCP server in TypeScript, put it in the Sandbox Image, and give its tool to an Agent.
 - [Size a Workspace](guides/size-a-workspace.md): Give a Workspace the memory and cpu that its Sandbox needs, and see how jr2 divides them in the pod.
 - [Run one worker per item](guides/run-one-worker-per-item.md): Make a Pool that runs one worker Machine for each item that a Source gives, and run it.
+- [Start a run for each alert](guides/start-a-run-for-each-alert.md): Make a standing Pool that starts one run for each alert that an outside service sends to a Hook.
+- [Write a Hook kind](guides/write-a-hook-kind.md): Write the kind of a service that jr2 ships no kind for, declare a Hook of it, and hear it at a Gate.
 - [Publish a Machine as an npm package](guides/publish-a-machine-as-an-npm-package.md): Ship a Machine in an npm package that names the Kit as a peer, and register it in an Instance.
 - [Let an Agent write a Chart](guides/let-an-agent-write-a-chart.md): Write a Chart wrapper whose planner Agent writes a Chart, runs it, and corrects it.
 - [Run a Chart by name](guides/run-a-chart-by-name.md): Keep a Chart under a name, as a Chart file or a runtime Chart, and run it with jr2 run.
@@ -69,14 +79,31 @@
 ## Reference
 
 - [Authoring surface](reference/authoring-surface.md): Every name that @jr2/orchestrator exports from its root, by group, with a link to its page: its signature, its TSDoc, and an example.
+  - [Authoring surface: Machine and events](reference/authoring-surface/group-machine-and-events.md): The setup a workflow writes its Machine with, the events its parties send, and the guard that makes a writing decline other senders (ADR-0011, ADR-0015).
+  - [Authoring surface: Gates](reference/authoring-surface/group-gates.md): A Gate slot hears a Hook (ADR-0011).
+  - [Authoring surface: Failure](reference/authoring-surface/group-failure.md): The Part a Machine invokes to fail its run, and the guard that tells a Failure from a defect in an `onError` (ADR-0073).
+  - [Authoring surface: Agents](reference/authoring-surface/group-agents.md): An Agent slot and the definition it carries (ADR-0028, ADR-0049).
+  - [Authoring surface: Workspaces and Repos](reference/authoring-surface/group-workspaces-and-repos.md): A Sandbox and the Repo Slots it binds (ADR-0012, ADR-0051).
+  - [Authoring surface: Effects](reference/authoring-surface/group-effects.md): Work a Machine does outside itself, as an actor slot (ADR-0067, ADR-0068, ADR-0071, ADR-0079), and what an author writes between a pick and that work.
+  - [Authoring surface: Steering](reference/authoring-surface/group-steering.md): The Machine's free text to one of its Agents, which the Agent hears once (ADR-0002).
+  - [Authoring surface: Composition](reference/authoring-surface/group-composition.md): A part left Open, a Machine's parts retuned, a Pool over a Source (ADR-0017, ADR-0049, ADR-0054, ADR-0060).
+  - [Authoring surface: Charts](reference/authoring-surface/group-charts.md): The Open body a Chart wrapper places in `actors`, and the grammar a planner's pick declares, whole or narrowed to one wrapper (ADR-0070).
+  - [Authoring surface: Config](reference/authoring-surface/group-config.md): `jr2.config.ts`, the deployment facts a Machine cannot carry (ADR-0050).
+  - [Authoring surface: Types these signatures name](reference/authoring-surface/group-types-these-signatures-name.md): The signature of an export, or a type here, names each of these types.
   - [`defineEvent`](reference/authoring-surface/defineevent.md): Define one workflow event: an event that an Agent or the caller of a Gate may send into your Machine.
   - [`jr2Setup`](reference/authoring-surface/jr2setup.md): Set up a Machine that takes workflow events: the jr2 form of xstate's `setup()`.
   - [`sentBy`](reference/authoring-surface/sentby.md): A guard that is true for an event that one party sent, and false for an event that another party sent: `guard: sentBy("coder")`.
   - [`HostInjectedInput`](reference/authoring-surface/type-hostinjectedinput.md): The fields that jr2 adds to the input of the Machine that a run starts, beside the input that the caller sent.
+  - [`gate`](reference/authoring-surface/gate.md): The Gate: an input that a run waits for from outside the run (ADR-0011).
+  - [`Delivered`](reference/authoring-surface/type-delivered.md): One plain event of a list of defs: `{ type: "approve", by }`.
+  - [`GateLook`](reference/authoring-surface/type-gatelook.md): A Gate's read of the fact that it waits for (ADR-0011).
+  - [`GateOutcome`](reference/authoring-surface/type-gateoutcome.md): What a delivery did at one open Gate.
+  - [`GateReply`](reference/authoring-surface/type-gatereply.md): The text that the person who acted reads.
   - [`fail`](reference/authoring-surface/fail.md): Fail the run: the Part a Machine invokes to end work that did not succeed.
   - [`isFailure`](reference/authoring-surface/isfailure.md): Is this error a Failure, which a state invoked `fail` to make?
   - [`agent`](reference/authoring-surface/agent.md): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
   - [`AgentDefinition`](reference/authoring-surface/type-agentdefinition.md): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
+  - [`AgentMcpServer`](reference/authoring-surface/type-agentmcpserver.md): One MCP server that an Agent uses, and the tools that it may call there.
   - [`ThinkingLevel`](reference/authoring-surface/type-thinkinglevel.md): How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` or `"xhigh"`.
   - [`workspace`](reference/authoring-surface/workspace.md): Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot.
   - [`Workspaced`](reference/authoring-surface/type-workspaced.md): The input of a `workspace()` body: the run input, plus `workspace`, the handles that the Workspace adds (`workspace.repos`, the folder of each Repo Slot).
@@ -102,27 +129,38 @@
   - [`AnyFramePath`](reference/authoring-surface/type-anyframepath.md): A Turn's Frame: a Worktree, or `/work`, stated.
   - [`AnyWorktreePath`](reference/authoring-surface/type-anyworktreepath.md): A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the slots of the body.
   - [`FramePath`](reference/authoring-surface/type-framepath.md): A Turn's Frame in a Workspace with the Repo Slots `S`.
-  - [`WorktreeFound`](reference/authoring-surface/type-worktreefound.md): What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work; `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no upstream; `commit`, a detached cut.
+  - [`WorktreeFound`](reference/authoring-surface/type-worktreefound.md): What a cut found.
   - [`WorktreeInput`](reference/authoring-surface/type-worktreeinput.md): The input of a `worktree()`: a branch Worktree, or a detached one.
   - [`WorktreeOptions`](reference/authoring-surface/type-worktreeoptions.md): The options of `worktree()`.
   - [`WorktreeOutput`](reference/authoring-surface/type-worktreeoutput.md): The output of a `worktree()`.
   - [`WorktreePath`](reference/authoring-surface/type-worktreepath.md): A Worktree of the Repo Slots `S`.
   - [`WorktreeReady`](reference/authoring-surface/type-worktreeready.md): Type, an export of @jr2/orchestrator.
-  - [`WorktreeRefused`](reference/authoring-surface/type-worktreerefused.md): No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a name that the remote cannot confirm.
+  - [`WorktreeRefused`](reference/authoring-surface/type-worktreerefused.md): No Worktree, and nothing changed.
   - [`dispatch`](reference/authoring-surface/dispatch.md): Make a `dispatch` Effect: it starts a run of a Workflow.
   - [`DispatchOutput`](reference/authoring-surface/type-dispatchoutput.md): The output of a `dispatch` Effect.
+  - [`mcp`](reference/authoring-surface/mcp.md): The `mcp` Effects (ADR-0067, ADR-0079): `mcp.call(server, tool, { input })` calls a tool, `mcp.read(server, uri)` reads a resource, and `mcp.prompt(server, name, { input })` gets a prompt.
+  - [`McpOptions`](reference/authoring-surface/type-mcpoptions.md): The options of an `mcp` Effect.
+  - [`McpCallOutput`](reference/authoring-surface/type-mcpcalloutput.md): The output of an `mcp.call` Effect: what the `onDone` of its state gets as `event.output`.
+  - [`McpOutput`](reference/authoring-surface/type-mcpoutput.md): The output of any `mcp` Effect: a call's, a read's or a prompt's.
+  - [`McpReadOutput`](reference/authoring-surface/type-mcpreadoutput.md): The output of an `mcp.read` or an `mcp.prompt` Effect.
   - [`answer`](reference/authoring-surface/answer.md): Set what the Agent reads when jr2 answers its pick.
   - [`fromPick`](reference/authoring-surface/frompick.md): Make the `input` of the invoke of a state that a pick enters: the params of the pick go to the input of the invoked actor by name.
   - [`paramsOf`](reference/authoring-surface/paramsof.md): Read the params of a pick from the event that entered the state.
+  - [`steer`](reference/authoring-surface/steer.md): Send a Steering message to one Agent of this Machine: an action for a transition.
   - [`open`](reference/authoring-surface/open.md): Leave a part of a Machine Open: for the Instance that registers the Machine to bind with `customize()`.
   - [`customize`](reference/authoring-surface/customize.md): Retune the parts that a Machine carries, without a change to the module that exports it.
   - [`Customize`](reference/authoring-surface/type-customize.md): The parts of one Machine that `customize()` can retune: its Agents, its Open Effects, the Machines it composes, and the Sandbox of its `workspace()`.
   - [`EffectBinding`](reference/authoring-surface/type-effectbinding.md): The values that bind the Open parts of one Effect.
   - [`Size`](reference/authoring-surface/type-size.md): The Size of a Workspace: the most memory and cpu that its whole Sandbox can use.
   - [`UserContainer`](reference/authoring-surface/type-usercontainer.md): The User Container in its object form: its image, and its part of the Workspace's Size.
-  - [`pool`](reference/authoring-surface/pool.md): Make a Pool: a Machine that runs one worker Machine for each item that a Source gives, with at most `cap` workers at once.
+  - [`carry`](reference/authoring-surface/carry.md): Give the item itself.
+  - [`pool`](reference/authoring-surface/pool.md): Make a Pool: a Machine that runs one worker for each item that a Source gives, with at most `cap` workers at once.
+  - [`reread`](reference/authoring-surface/reread.md): Read the Source again.
+  - [`skip`](reference/authoring-surface/skip.md): Bring nothing, and say why.
   - [`source`](reference/authoring-surface/source.md): Declare a Source: where a `pool()` gets its work items, one at a time.
   - [`PoolNextInput`](reference/authoring-surface/type-poolnextinput.md): The input of a Source's `next`: the ids of the items that workers have now, the ids of the items that settled, and the Pool's input.
+  - [`SourceReply`](reference/authoring-surface/type-sourcereply.md): The text that the person who acted reads, from this Source's verdict (ADR-0011, ADR-0017).
+  - [`SourceVerdict`](reference/authoring-surface/type-sourceverdict.md): A Source's verdict on one delivery, as its `reply` reads it (ADR-0017).
   - [`openBody`](reference/authoring-surface/openbody.md): Make an Open body: the actor slot that a Chart binds.
   - [`OpenBodyDeclaration`](reference/authoring-surface/type-openbodydeclaration.md): What an Open body declares: the parts that it lends a Chart, what the Agents of a Chart can have, and the limits of a Chart.
   - [`OpenBodyOutput`](reference/authoring-surface/type-openbodyoutput.md): The output of an Open body.
@@ -130,10 +168,17 @@
   - [`chartSchemaFor`](reference/authoring-surface/chartschemafor.md): The Chart grammar for one Open body, as a zod schema.
   - [`defineConfig`](reference/authoring-surface/defineconfig.md): Declare the config of an Instance: the default export of `jr2.config.ts`.
   - [`JR2Config`](reference/authoring-surface/type-jr2config.md): The shape of `jr2.config.ts`: the deployment facts of an Instance, which a Machine cannot carry.
+  - [`McpRemoteServer`](reference/authoring-surface/type-mcpremoteserver.md): A remote MCP server, which the Harness reaches over Streamable HTTP.
+  - [`McpServer`](reference/authoring-surface/type-mcpserver.md): One MCP server of the Instance: a `McpRemoteServer` (`url`) or a `McpStdioServer` (`command`).
+  - [`McpStdioServer`](reference/authoring-surface/type-mcpstdioserver.md): A stdio MCP server: a program of the Sandbox Image that the Harness starts for each Agent conversation, through jr2's spawner, inside the Agent's confinement.
+  - [`RunsConfig`](reference/authoring-surface/type-runsconfig.md): How long jr2 keeps an ended run, and the volume that keeps it (ADR-0065).
   - [`EventSemantics`](reference/authoring-surface/type-eventsemantics.md): How the party that sends an event gets its answer.
   - [`EventAudience`](reference/authoring-surface/type-eventaudience.md): Who may send an event: `"agent"` (an Agent, as a pick from its Menu), `"external"` (the caller of a Gate), or `"any"` (both).
   - [`EventDef`](reference/authoring-surface/type-eventdef.md): A workflow event, as `defineEvent` gives it back: plain, frozen data and a zod schema, safe to import anywhere.
   - [`WorkflowEvent`](reference/authoring-surface/type-workflowevent.md): The type of `event` in a Machine that `jr2Setup` makes: each workflow event in its `events`, and each Mechanism event.
+  - [`GateSlot`](reference/authoring-surface/type-gateslot.md): A Gate with parts that the Machine carries.
+  - [`Duration`](reference/authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
+  - [`CallerRecord`](reference/authoring-surface/type-callerrecord.md): A Caller as a run records it (ADR-0078): who acted, and the party it says it acted for.
   - [`FailSlot`](reference/authoring-surface/type-failslot.md): The logic `fail()` returns: `failLogic` with the brand the walk reads.
   - [`Failure`](reference/authoring-surface/type-failure.md): A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself.
   - [`AgentDeclaration`](reference/authoring-surface/type-agentdeclaration.md): What `agent()` takes: an `AgentDefinition`, except that `model` can also be `open`.
@@ -159,20 +204,30 @@
   - [`OpenSecret`](reference/authoring-surface/type-opensecret.md): `secret(open)`: a secret a packaged Machine names in its auth, a header or a command's env, and leaves for its composer to name (ADR-0054).
   - [`PushOptions`](reference/authoring-surface/type-pushoptions.md): The options of `push()`.
   - [`PushInput`](reference/authoring-surface/type-pushinput.md): The input of a `push` Effect: the Worktree that a cut made, `{ sha }` with `pin`, and `{ message }` with `squash`.
-  - [`Duration`](reference/authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
   - [`NameStart`](reference/authoring-surface/type-namestart.md): What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path.
   - [`DispatchDefinition`](reference/authoring-surface/type-dispatchdefinition.md): The definition of a `dispatch` Effect (ADR-0071).
   - [`DispatchInput`](reference/authoring-surface/type-dispatchinput.md): A dispatch's input: the run's body — the slot's schema's type, or any JSON object.
   - [`DispatchOpenParts`](reference/authoring-surface/type-dispatchopenparts.md): The Open part a dispatch definition states: its target, when it is `open`.
-  - [`ChainLink`](reference/authoring-surface/type-chainlink.md): One reply since the pick, as the author reads it: an invoked actor's output, typed by its slot (`src`); or an event that answered a state below the Agent's — a Gate's answer, a nested Agent's pick — typed by the Machine's events.
+  - [`McpNotReturned`](reference/authoring-surface/type-mcpnotreturned.md): The outcomes that an `mcp` Effect gives besides `returned`.
+  - [`ChainLink`](reference/authoring-surface/type-chainlink.md): One reply since the pick, as the author reads it.
+  - [`SteerArgs`](reference/authoring-surface/type-steerargs.md): The arguments a `steer` text or `from` function gets: the Machine's context and the event that the transition takes.
+  - [`Sender`](reference/authoring-surface/type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
   - [`Quantity`](reference/authoring-surface/type-quantity.md): A Kubernetes quantity: `"2Gi"`, `"1500m"`, `"2"`, or a plain number (`2` cpus, bytes of memory).
-  - [`PoolSpec`](reference/authoring-surface/type-poolspec.md): What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets.
-  - [`SourceSpec`](reference/authoring-surface/type-sourcespec.md): Where a Pool gets its work items: the Source.
+  - [`Carry`](reference/authoring-surface/type-carry.md): What `carry(item)` gives.
+  - [`PoolSpec`](reference/authoring-surface/type-poolspec.md): What you pass to `pool()` with a child Machine as its worker.
+  - [`StandingPoolSpec`](reference/authoring-surface/type-standingpoolspec.md): What you pass to `pool()` for a Pool of runs.
+  - [`Reread`](reference/authoring-surface/type-reread.md): What `reread()` gives.
+  - [`Skip`](reference/authoring-surface/type-skip.md): What `skip(reason)` gives: the delivery brings nothing, and the reason says why.
+  - [`SourceSpec`](reference/authoring-surface/type-sourcespec.md): A pull Source.
+  - [`SourceHooks`](reference/authoring-surface/type-sourcehooks.md): A Source's handlers, by Hook kind and event key.
+  - [`PushSourceSpec`](reference/authoring-surface/type-pushsourcespec.md): A push Source.
+  - [`ReadSourceSpec`](reference/authoring-surface/type-readsourcespec.md): A read Source.
   - [`OpenBodyLogic`](reference/authoring-surface/type-openbodylogic.md): The logic `openBody()` returns: actor logic that carries the brand.
   - [`Lends`](reference/authoring-surface/type-lends.md): The parts of the Chart wrapper that a Chart can use, by their keys in `actors`, `guards`, `actions` and `delays`.
   - [`Ceilings`](reference/authoring-surface/type-ceilings.md): The limits that an Open body sets on its Chart.
   - [`ChartText`](reference/authoring-surface/type-charttext.md): The Chart text (ADR-0070).
-  - [`Sender`](reference/authoring-surface/type-sender.md): Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015).
+  - [`DeliveredEvent`](reference/authoring-surface/type-deliveredevent.md): A workflow event as delivered into a Machine: the def's name as `type`, plus its payload.
+  - [`Caller`](reference/authoring-surface/type-caller.md): A request's Caller (ADR-0078): who acts, through which authenticator, and what it may do.
   - [`FailureInput`](reference/authoring-surface/type-failureinput.md): What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine reader.
   - [`SandboxOptions`](reference/authoring-surface/type-sandboxoptions.md): The options of a `workspace()` that say what its Sandbox is made of and which Repos it clones.
   - [`SlotHandles`](reference/authoring-surface/type-slothandles.md): The handles of a Workspace that declares Repo Slots.
@@ -180,8 +235,10 @@
   - [`TextPart`](reference/authoring-surface/type-textpart.md): One part of a `Text`: `{ text }`, literal text, or `{ secret }`, the name of an Effect secret.
   - [`HttpMethod`](reference/authoring-surface/type-httpmethod.md): The method of an `http` Effect: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE` or `OPTIONS`.
   - [`HttpRequestParts`](reference/authoring-surface/type-httprequestparts.md): What the `request` of an `http` definition returns: the part of the request that changes for each run.
-  - [`NamedSecret`](reference/authoring-surface/type-namedsecret.md): A named secret, never `secret(open)`: where a definition's Open part is a whole that holds a secret — a dispatch's target (ADR-0071) — the secret is bound with it, to a name, so the mark `secret(open)` carries may not be present.
+  - [`NamedSecret`](reference/authoring-surface/type-namedsecret.md): A secret bound to a name, never `secret(open)`.
+  - [`SenderCallerField`](reference/authoring-surface/type-sendercallerfield.md): A field of a `Sender`'s Caller that jr2 can verify.
   - [`SourceNextResult`](reference/authoring-surface/type-sourcenextresult.md): What the `next` of a Source resolves to: an item, to claim it; `null`, when no item is ready now; or `{ item, open }`, where `open` is the number of items that exist but are not ready.
+  - [`SourceIn`](reference/authoring-surface/type-sourcein.md): What a Source's handler reads beside `payload`.
   - [`OpenBodySlot`](reference/authoring-surface/type-openbodyslot.md): The brand an Open body slot carries, as `definition` marks an Agent slot (ADR-0049).
   - [`ChartJson`](reference/authoring-surface/type-chartjson.md): Plain JSON.
   - [`ChartEvent`](reference/authoring-surface/type-chartevent.md): An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
@@ -198,6 +255,9 @@
   - [`ToParameterizedObject`](reference/authoring-surface/type-toparameterizedobject.md): A type that the Authoring surface names.
   - [`BindActors`](reference/authoring-surface/type-bindactors.md): A type that the Authoring surface names.
   - [`SentByGuards`](reference/authoring-surface/type-sentbyguards.md): A type that the Authoring surface names.
+  - [`GateHooks`](reference/authoring-surface/type-gatehooks.md): A type that the Authoring surface names.
+  - [`EventFrom`](reference/authoring-surface/type-eventfrom.md): A type that the Authoring surface names.
+  - [`LookOutput`](reference/authoring-surface/type-lookoutput.md): A type that the Authoring surface names.
   - [`AgentLogic`](reference/authoring-surface/type-agentlogic.md): A type that the Authoring surface names.
   - [`BodyAcceptsDoor`](reference/authoring-surface/type-bodyacceptsdoor.md): A type that the Authoring surface names.
   - [`WorkspaceMachine`](reference/authoring-surface/type-workspacemachine.md): A type that the Authoring surface names.
@@ -218,17 +278,23 @@
   - [`OpenEffectSlots`](reference/authoring-surface/type-openeffectslots.md): A type that the Authoring surface names.
   - [`BindingOf`](reference/authoring-surface/type-bindingof.md): A type that the Authoring surface names.
   - [`LogicAt`](reference/authoring-surface/type-logicat.md): A type that the Authoring surface names.
+  - [`GateSlots`](reference/authoring-surface/type-gateslots.md): A type that the Authoring surface names.
+  - [`GateBinding`](reference/authoring-surface/type-gatebinding.md): A type that the Authoring surface names.
+  - [`GateTypesAt`](reference/authoring-surface/type-gatetypesat.md): A type that the Authoring surface names.
   - [`ChildSlots`](reference/authoring-surface/type-childslots.md): A type that the Authoring surface names.
   - [`ChildAt`](reference/authoring-surface/type-childat.md): A type that the Authoring surface names.
   - [`RepoSlotsOf`](reference/authoring-surface/type-reposlotsof.md): A type that the Authoring surface names.
   - [`WorkspaceOf`](reference/authoring-surface/type-workspaceof.md): A type that the Authoring surface names.
   - [`PoolMachine`](reference/authoring-surface/type-poolmachine.md): A type that the Authoring surface names.
-  - [`EventFrom`](reference/authoring-surface/type-eventfrom.md): A type that the Authoring surface names.
+  - [`StandingPoolMachine`](reference/authoring-surface/type-standingpoolmachine.md): A type that the Authoring surface names.
+  - [`GateSlotInput`](reference/authoring-surface/type-gateslotinput.md): A type that the Authoring surface names.
+  - [`GateSlotParts`](reference/authoring-surface/type-gateslotparts.md): A type that the Authoring surface names.
   - [`ArgNames`](reference/authoring-surface/type-argnames.md): A type that the Authoring surface names.
   - [`WorktreeKey`](reference/authoring-surface/type-worktreekey.md): A type that the Authoring surface names.
   - [`NotWorktreeKeys`](reference/authoring-surface/type-notworktreekeys.md): A type that the Authoring surface names.
   - [`OpenSecretMark`](reference/authoring-surface/type-opensecretmark.md): A type that the Authoring surface names.
 - [@jr2/machines](reference/machines.md): The Machines that @jr2/machines ships: their input, their output, and their Open parts.
+- [Hook kinds](reference/hooks.md): Every name that @jr2/orchestrator/hooks exports: the interface of a Hook kind, the kinds that jr2 ships, and webhook().
 - [jr2.config.ts](reference/config.md): Every field of jr2.config.ts: its type, whether it is required, its default, and what it does.
 - [CLI](reference/cli.md): Every jr2 command: its synopsis, its arguments, flags and env vars, and what it prints.
 - [HTTP API](reference/http-api.md): Every route of the Orchestrator's HTTP API, by access band, and the types of its bodies and answers.

package/docs/reference/authoring-surface/agent.md

@@ -5,7 +5,7 @@ description: "Make an Agent: an actor slot that runs one Turn of a model each ti
 
 # `agent`
 
-Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, in the [Agents](group-agents.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function agent<

package/docs/reference/authoring-surface/answer.md

@@ -5,7 +5,7 @@ description: Set what the Agent reads when jr2 answers its pick.
 
 # `answer`
 
-Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function answer<

package/docs/reference/authoring-surface/arg.md

@@ -5,7 +5,7 @@ description: Mark one argv entry of a `command` that the input of the Effect fil
 
 # `arg`
 
-Constant, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Constant, in `@jr2/orchestrator/src/effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const arg: <const N extends string>(name: N) => Arg<N>

package/docs/reference/authoring-surface/basic.md

@@ -5,7 +5,7 @@ description: "Make the `auth` of an `http` Effect that sends `Authorization: Bas
 
 # `basic`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function basic<

package/docs/reference/authoring-surface/bearer.md

@@ -5,7 +5,7 @@ description: "Make the `auth` of an `http` Effect that sends `Authorization: Bea
 
 # `bearer`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function bearer<const S extends Secret>(s: S): MarkedIf<S, { readonly bearer: Secret }>

package/docs/reference/authoring-surface/branchname.md

@@ -5,7 +5,7 @@ description: A kit schema for a pick param that names a branch.
 
 # `branchName`
 
-Constant, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Constant, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const branchName: ZodString

package/docs/reference/authoring-surface/carry.md

@@ -0,0 +1,23 @@
+---
+title: carry
+description: Give the item itself.
+---
+
+# `carry`
+
+Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+function carry<T>(item: T): Carry<T>
+```
+
+Give the item itself. The Pool holds it, in its run's blob, until it claims it. Only a push
+Source gives it.
+
+**Parameters**
+
+- `item`: The item, of the type of the Source's `item` schema.
+
+**See also**
+
+- [Pools and Sources](../../concepts/pools-and-sources.md)

package/docs/reference/authoring-surface/chartschema.md

@@ -5,7 +5,7 @@ description: The Chart grammar, as a zod schema.
 
 # `chartSchema`
 
-Constant, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Constant, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 const chartSchema: z.ZodType<ChartText>

package/docs/reference/authoring-surface/chartschemafor.md

@@ -5,7 +5,7 @@ description: The Chart grammar for one Open body, as a zod schema.
 
 # `chartSchemaFor`
 
-Function, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Charts.
+Function, in `@jr2/orchestrator/src/chart.ts`. It is an export of `@jr2/orchestrator`, in the [Charts](group-charts.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function chartSchemaFor(decl: OpenBodyDeclaration): z.ZodType<ChartText>

package/docs/reference/authoring-surface/command.md

@@ -5,7 +5,7 @@ description: "Make a `command` Effect: an actor slot that runs one program in th
 
 # `command`
 
-Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/harness-client.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 

package/docs/reference/authoring-surface/customize.md

@@ -5,7 +5,7 @@ description: Retune the parts that a Machine carries, without a change to the mo
 
 # `customize`
 
-Function, in `@jr2/orchestrator/src/customize.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.
+Function, in `@jr2/orchestrator/src/customize.ts`. It is an export of `@jr2/orchestrator`, in the [Composition](group-composition.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function customize<M extends AnyStateMachine>(machine: M, parts: Customize<M>): M
@@ -24,6 +24,9 @@ refuse most mistakes when you compile. At run time, `customize()` also throws:
 - `customize(): machine "<id>" carries no Agent slot "<slot>" — its Agents are: <slots>`
 - `customize(): machine "<id>" composes no Machine under "<slot>" — the Machines it composes are: <slots>`
 - `customize(): machine "<id>" carries no Effect slot "<slot>" — its Effects are: <slots>`
+- `customize(): machine "<id>" carries no Gate slot "<slot>" — its Gate slots are: <slots>`
+- `` customize(): Gate slot "<slot>"'s look is bound once, to a look or "none" — not `open` again ``, and the
+  refusals of a look that `gate()` makes
 - `customize(): machine "<id>" declares no Repo Slot "<slot>" — its slots are: <slots>`
 - `customize(): machine "<id>" declares its Repo Slots open as a map — name at least one`
 - `` customize(): `repos` say what a SANDBOX is made of, how big it is and which Repos it

package/docs/reference/authoring-surface/defineconfig.md

@@ -5,7 +5,7 @@ description: "Declare the config of an Instance: the default export of `jr2.conf
 
 # `defineConfig`
 
-Function, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Config.
+Function, in `@jr2/orchestrator/src/config.ts`. It is an export of `@jr2/orchestrator`, in the [Config](group-config.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function defineConfig(c: JR2Config): JR2Config

package/docs/reference/authoring-surface/defineevent.md

@@ -5,7 +5,7 @@ description: "Define one workflow event: an event that an Agent or the caller of
 
 # `defineEvent`
 
-Function, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Machine and events.
+Function, in `src/define-event.ts` of `@jr2/agent-protocol`, a dependency of `@jr2/orchestrator`. It is an export of `@jr2/orchestrator`, in the [Machine and events](group-machine-and-events.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function defineEvent<const Name extends string, Input extends z.ZodObject>(def: {

package/docs/reference/authoring-surface/dispatch.md

@@ -5,7 +5,7 @@ description: "Make a `dispatch` Effect: it starts a run of a Workflow."
 
 # `dispatch`
 
-Function, in `@jr2/orchestrator/src/dispatch-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/dispatch-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function dispatch<
@@ -69,9 +69,10 @@ It refuses:
     How long the Effect waits: by default 30s for the start, and 10m with `wait`.
   - `target` (optional): `{ url: string; token: NamedSecret; } | typeof open`
 
-    A different Orchestrator: `url` is its origin, and `token` is the secret that holds its
-    Instance token. Or `open`, which the composer binds with `customize(<import>, { effects: {
-    <slot>: { target: { url, token } } } })`. Without it, the run starts in this Orchestrator.
+    A different Orchestrator: `url` is its origin, and `token` is the secret that holds the token
+    of a Caller of it with `start` for the Workflow, and `read` too when `wait` is true. Or `open`,
+    which the composer binds with `customize(<import>, { effects: { <slot>: { target: { url, token
+    } } } })`. Without it, the run starts in this Orchestrator.
 
 **Returns**: An Effect, for `actors`.
 

package/docs/reference/authoring-surface/fail.md

@@ -5,7 +5,7 @@ description: "Fail the run: the Part a Machine invokes to end work that did not
 
 # `fail`
 
-Function, in `@jr2/orchestrator/src/fail.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Failure.
+Function, in `@jr2/orchestrator/src/fail.ts`. It is an export of `@jr2/orchestrator`, in the [Failure](group-failure.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function fail(): FailSlot

package/docs/reference/authoring-surface/file.md

@@ -5,7 +5,7 @@ description: "Make a Worktree file the body of an `http` Effect: `body: file(\"d
 
 # `file`
 
-Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/http-effect.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ```ts
 function file<S extends z.ZodType | undefined = undefined>(path: FromInput<S, string>, options: {

package/docs/reference/authoring-surface/frompick.md

@@ -5,7 +5,7 @@ description: "Make the `input` of the invoke of a state that a pick enters: the
 
 # `fromPick`
 
-Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Effects.
+Function, in `@jr2/orchestrator/src/pick.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 

package/docs/reference/authoring-surface/gate.md

@@ -0,0 +1,118 @@
+---
+title: gate
+description: "The Gate: an input that a run waits for from outside the run (ADR-0011)."
+---
+
+# `gate`
+
+Function, in `@jr2/orchestrator/src/gate.ts`. It is an export of `@jr2/orchestrator`, in the [Gates](group-gates.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+function gate<
+  const D extends readonly EventDef[],
+  M extends z.ZodObject = z.ZodObject<{}>,
+  R extends AnyActorLogic = never,
+>(
+  spec: {
+    readonly meta?: M;
+    readonly delivers: D;
+    readonly hooks?: GateHooks<z.output<NoInfer<M>>, Delivered<D>>;
+    readonly look?: GateLook<z.output<NoInfer<M>>, Delivered<D>, R> | typeof open | "none";
+    readonly reply?: GateReply<z.output<NoInfer<M>>, Delivered<D>>;
+  },
+): GateSlot<z.output<M>, Delivered<D>>
+```
+
+The Gate: an input that a run waits for from outside the run ([ADR-0011](../decisions/0011-workflow-defined-events.md)).
+
+`gate({ … })` declares a GATE SLOT that also hears a Hook: put it in `actors` and invoke it by
+its key. A plain Gate needs no value: jr2Setup puts it in each Machine as `invoke: { src: "gate" }`.
+Its accepted set derives from the invoking state's transitions, and a Caller answers it with
+`jr2 send`, the Console or `POST /runs/:runId/gates/:gate/events`.
+
+- `meta`: a zod object of the meta that the invoking state sets. The Gate checks it when it
+  opens, and the handlers, the look and `reply` read it typed.
+- `delivers`: the events that the handlers and the look can give. An event whose def leaves the
+  audience unset reads as `audience: "external"`, so no Agent below the Gate has it on its Menu.
+  `createMachine` refuses an entry that the Gate's derived accepted set does not hold.
+- `hooks`: a handler for each Hook kind id and event key. A handler reads `{ payload, meta,
+  caller }` and gives one event of `delivers`, or `undefined` to ignore the delivery. It is pure
+  and synchronous. A throw is a refusal that the hook log keeps; it never faults the run.
+- `look`: the Gate's read of the fact that it waits for (see [`GateLook`](type-gatelook.md)), `"none"` for a
+  Gate that hears a command, or `open` for the composer to bind with
+  `customize(m, { gates: { <slot>: { look } } })`. With no look and no `after` on the invoking
+  state, or with an Open look, `jr2 up` warns.
+- `reply`: the text that the person who acted reads, for a Hook kind whose answer a person reads.
+
+It throws on a spec that it cannot run: an unknown key, a `delivers` that is empty or that holds an
+entry `defineEvent` did not make, a handler that is not a function, or a look whose read is not an
+`http` Effect marked `idempotent: true` or a promise.
+
+**Parameters**
+
+- `spec`
+
+  - `meta` (optional): `M`
+
+    A zod object for the meta that the invoking state sets. The Gate checks it when it opens.
+  - `delivers`: `D`
+
+    The events that the handlers and the look can give.
+  - `hooks` (optional): `GateHooks<z.output<NoInfer<M>>, Delivered<D>>`
+
+    The handlers, by Hook kind id and event key.
+  - `look` (optional): `GateLook<z.output<NoInfer<M>>, Delivered<D>, R> | typeof open | "none"`
+
+    The look, `"none"` for a Gate that hears a command, or `open` for its composer to bind.
+  - `reply` (optional): `GateReply<z.output<NoInfer<M>>, Delivered<D>>`
+
+    The text that the person who acted reads.
+
+**Example**
+
+```ts
+import { z } from "zod";
+import type {} from "@jr2/orchestrator/hooks/github";
+import { defineEvent, gate, jr2Setup } from "@jr2/orchestrator";
+
+const approve = defineEvent({ name: "approve", input: z.object({ by: z.string() }) });
+
+const review = gate({
+  meta: z.object({ pr: z.string(), sha: z.string() }),
+  delivers: [approve],
+  hooks: {
+    github: {
+      "pull_request_review.submitted": ({ payload, meta }) =>
+        payload.pull_request.html_url === meta.pr &&
+        payload.review.commit_id === meta.sha &&
+        payload.review.state === "approved"
+          ? { type: "approve", by: payload.review.user.login }
+          : undefined,
+    },
+  },
+  look: "none",
+});
+
+export const machine = jr2Setup({
+  types: {} as { context: { pr: string; sha: string }; input: { pr: string; sha: string } },
+  events: [approve],
+  actors: { review },
+}).createMachine({
+  id: "pr",
+  context: ({ input }) => input,
+  initial: "inReview",
+  states: {
+    inReview: {
+      invoke: { src: "review", input: ({ context }) => ({ meta: { pr: context.pr, sha: context.sha } }) },
+      on: { approve: "merged" },
+    },
+    merged: { type: "final" },
+  },
+});
+```
+
+**See also**
+
+- [Gates](../../concepts/gates.md)
+- [Answer a Gate from a forge](../../guides/answer-a-gate-from-a-forge.md)
+- [ADR-0011: Control events are workflow-defined and delivered by closure, not routed](../decisions/0011-workflow-defined-events.md)

package/docs/reference/authoring-surface/group-agents.md

@@ -0,0 +1,15 @@
+---
+title: "Authoring surface: Agents"
+description: An Agent slot and the definition it carries (ADR-0028, ADR-0049).
+---
+
+# Authoring surface: Agents
+
+This page is one group of the names that `@jr2/orchestrator` exports from its root, on the [Authoring surface](../authoring-surface.md) page. It gives each name its kind and the first sentence of its TSDoc. Each name has a page of its own, in this folder.
+
+An Agent slot and the definition it carries ([ADR-0028](../decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md), [ADR-0049](../decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)).
+
+- [`agent`](agent.md) (function): Make an Agent: an actor slot that runs one Turn of a model each time a state invokes it.
+- [`AgentDefinition`](type-agentdefinition.md) (type): An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace.
+- [`AgentMcpServer`](type-agentmcpserver.md) (type): One MCP server that an Agent uses, and the tools that it may call there.
+- [`ThinkingLevel`](type-thinkinglevel.md) (type): How hard the model thinks before it answers: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"` or `"xhigh"`.