@jr2/orchestrator 0.4.1 → 0.5.1

package/docs/guides/write-a-workflow.md

@@ -0,0 +1,318 @@
+---
+title: Write a Workflow
+description: Write a module in workflows/ that exports a Machine, with the input that starts a run and its Vocabulary.
+---
+
+# Write a Workflow
+
+Write a module in `workflows/` that exports a [Machine](../reference/glossary.md#machine), so that the
+[Instance](../reference/glossary.md#instance) registers it as a [Workflow](../reference/glossary.md#workflow).
+
+The module contract has three parts:
+
+- The file is `workflows/<name>.ts`. `<name>` is the name of the Workflow. `jr2 run <name>` starts it.
+- The file exports its Machine as `machine`. jr2 reads no other export.
+- The Machine holds all that it needs: its [Vocabulary](../reference/glossary.md#vocabulary), its
+  [Agents](../reference/glossary.md#agent), its [Effects](../reference/glossary.md#effect) and its
+  [Sandbox Image](../reference/glossary.md#sandbox-image). The Workflow is only a name for it.
+
+## The example
+
+This module is the Workflow `rollout`. A run waits at a [Gate](../reference/glossary.md#gate) until a person sends
+`promote` or `roll_back`. It has no Agent, so you can try it with no model. Save it as `workflows/rollout.ts`:
+
+```ts
+import { assign, emit } from "xstate";
+import { z } from "zod";
+import { defineEvent, fail, jr2Setup, type HostInjectedInput } from "@jr2/orchestrator";
+
+// The door: the input that starts a run. jr2 checks each start against this schema.
+const runInput = z.object({
+  service: z.string().min(1).describe("The service to roll out."),
+  version: z.string().min(1).describe("The version to roll out."),
+  // A field with a default is optional for the caller. The run starts with the default.
+  canaryPercent: z.number().int().min(1).max(50).default(10).describe("The percent of hosts in the canary."),
+});
+type RunInput = z.infer<typeof runInput>;
+
+// jr2 adds instanceId to the input of the root Machine of a run. No caller sends it.
+type Input = RunInput & HostInjectedInput;
+type Context = Input & { reason?: string };
+
+// The Vocabulary: the events that this Machine takes. Here, a person sends them to the Gate.
+const promote = defineEvent({
+  name: "promote",
+  description: "The canary is healthy. Roll out the version to all hosts.",
+  input: z.object({}),
+});
+const rollBack = defineEvent({
+  name: "roll_back",
+  description: "Stop the rollout. Say why.",
+  input: z.object({ reason: z.string().min(1) }),
+});
+
+// jr2 reads only this export. The file name, rollout.ts, gives the Workflow its name: rollout.
+export const machine = jr2Setup({
+  types: {} as {
+    input: Input;
+    context: Context;
+    emitted: { type: "decided"; promoted: boolean };
+  },
+  events: [promote, rollBack],
+  actors: { fail: fail() },
+}).createMachine({
+  id: "rollout",
+  input: runInput,
+  context: ({ input }) => ({ ...input }),
+  initial: "canary",
+  states: {
+    // A Gate. The run waits here until a person sends promote or roll_back.
+    canary: {
+      invoke: {
+        src: "gate",
+        input: ({ context }) => ({
+          meta: {
+            service: context.service,
+            version: context.version,
+            canaryPercent: context.canaryPercent,
+            instanceId: context.instanceId,
+          },
+        }),
+      },
+      on: {
+        promote: { target: "promoted", actions: emit({ type: "decided", promoted: true }) },
+        roll_back: {
+          target: "rolledBack",
+          actions: [assign({ reason: ({ event }) => event.reason }), emit({ type: "decided", promoted: false })],
+        },
+      },
+    },
+    promoted: { type: "final" },
+    // A person stopped the rollout, and the run ends here. Not a final state: the run ends `failed`,
+    // with the person's reason, and `jr2 run` exits 1.
+    rolledBack: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.reason! }) } },
+  },
+});
+```
+
+The parts of the module:
+
+- **The door.** The `input` of `createMachine` is a zod object. It is the input that starts a run. jr2 examines each
+  start against it, and it starts the run with the input that zod parsed. Thus `canaryPercent` gets its default when the
+  caller does not send it. Give the same type to `types.input`, with `z.infer`, so that TypeScript and jr2 agree.
+- **`instanceId`.** jr2 adds `instanceId` to the input of the root Machine of a run. Add
+  [`HostInjectedInput`](../reference/authoring-surface/type-hostinjectedinput.md) to the input type when the Machine
+  reads it. Do not put it in the door. No caller sends it.
+- **The Vocabulary.** Make each event with [`defineEvent`](../reference/authoring-surface/defineevent.md), and list it
+  in the `events` of [`jr2Setup`](../reference/authoring-surface/jr2setup.md). Write its name as an `on` key on each
+  state that takes it.
+- **The Gate.** The state `canary` invokes `gate`. The Gate takes the events of the `on` keys of that state. Its `meta`
+  is the data that `jr2 status` and the [Console](../reference/glossary.md#console) show to the person who answers.
+- **The [Emit](../reference/glossary.md#emit).** `emit()` tells the people who watch the run what happened. It does not
+  move the Machine. Declare its type in `types.emitted`.
+
+A Machine with a door uses `jr2Setup`, also when it takes no workflow event. Then leave out `events`, as in
+`jr2Setup()`. The `setup()` of [xstate](https://xstate.js.org) does not read the `input` of `createMachine`. TypeScript
+accepts a zod `input` there, but no door reads it, so `jr2 up` refuses that Machine. Without the refusal, a run would
+start with any input, and the Console start form would be only a field for JSON. Only a Machine with no door and no
+workflow event can use `setup()`, as the `ping` Workflow that `jr2 init` writes does.
+
+## Give the run an output
+
+The output of a run is the `output` at the root of `createMachine`, beside `id` and `states`. The status of the run
+shows it as `output`. When a different Machine invokes this Machine, the `onDone` of that invoke gets it as
+`event.output`. The `rollout` example has no root `output`. Thus a run of it that ends `done` has no output, and its
+result is only in its `context`.
+
+xstate does not use the `output` of a final state as the output of the Machine. It gives that output to the root
+`output` as `event.output`. Thus a Machine that has an `output` only on its final states has no output. TypeScript does
+not find this error, but `createMachine` refuses it when the module loads (see [the refusal](#rules)). Write the root
+`output` in one of these two forms:
+
+- From the context: `output: ({ context }) => ({ reason: context.reason })`.
+- From the final state that ended the run: `output: ({ event }) => event.output as Output`, with an `output` on each
+  final state. The example of [Gates](../concepts/gates.md) does this.
+
+Give the same type to `types.output`.
+
+A final state inside a compound state can have an `output` without a root `output`. The `onDone` of that compound state
+gets it as `event.output`. A Machine with no `output`, such as `rollout`, is also correct.
+
+## Fail the run
+
+A final state means that the work succeeded: the run ends `done`. When the Machine could not do its work, invoke
+[`fail`](../reference/authoring-surface/fail.md) from a state. Put it under `actors` as `fail: fail()`, and give it a
+`reason`:
+
+```ts
+failed: { invoke: { src: "fail", input: { reason: "the tests did not pass", detail: { code: 1 } } } },
+```
+
+The run ends `failed`, and its output is the `{ reason, detail }` of the [Failure](../reference/glossary.md#failure).
+`jr2 run` exits with `1`. Do not throw from a promise to fail. A throw is a defect: the run ends `error`, with no
+output, and nobody can tell it from a bug in the kit. A Failure deletes the Sandbox of each `workspace()` that it goes
+through. To keep the work for a person to read, wait at a Gate before the state that fails.
+
+The same rule applies to the decision of a person. A decision that sends the work back, such as a `reject` that goes
+back to the coder, is a usual route. A decision that ends the run, such as `roll_back` in `rollout` or a `reject` at a
+Gate, goes to a state that invokes `fail` with the reason of the person, as `rolledBack` does. Do not put a
+`{ outcome: "rejected" }` in the output type for it. When the job of the Machine is the decision itself, such as a
+triage where "no" is a correct answer, the decision is a final state, and the Machine puts the decision in its output.
+
+A Failure goes up through each parent Machine. To catch it, guard an `onError` with
+[`isFailure`](../reference/authoring-surface/isfailure.md):
+`onError: [{ guard: ({ event }) => isFailure(event.error), target: "replan" }, { target: "broken" }]`.
+[How a run ends](../concepts/machines-and-workflows.md#how-a-run-ends) tells more.
+
+## Register it and run it
+
+Run [`jr2 up`](../reference/cli.md#up) in the Instance folder. `jr2 up` typechecks the Instance, then loads each module
+in `workflows/` before it changes the cluster. An error in a module stops it. The
+[Orchestrator](../reference/glossary.md#orchestrator) runs only the Machines that the last `jr2 up` gave it.
+[Iterate on a Machine on kind](iterate-on-a-machine-on-kind.md) gives the loop.
+
+```sh
+jr2 up
+```
+
+Start a run in one terminal. The run waits at the Gate, so `jr2 run` stays attached. The output uses the kind cluster
+`jr2` and the Instance `my-instance` from [Get started](../get-started/install.md):
+
+```sh
+jr2 run rollout --input '{"service":"billing","version":"1.4.0"}'
+```
+
+```text
+→ context kind-jr2 / namespace my-instance
+run b7c3d871-e3ae-46af-8bb3-774913bcd6cc (rollout) — attached
+  → active "canary"
+```
+
+Your run id is different. When your Instance folder has a `.env` file, the output starts with one more line, `→ .env:`,
+with the keys that the CLI took from it. In a second terminal, answer the Gate. Write the run id in place of `<run id>`,
+or its first 4 characters or more:
+
+```sh
+jr2 send <run id> --gate canary --event roll_back --input '{"reason":"The error rate went up."}'
+```
+
+```text
+→ context kind-jr2 / namespace my-instance
+delivered roll_back to gate "canary" on b7c3d871-e3ae-46af-8bb3-774913bcd6cc
+```
+
+In the first terminal, the run ends. A `roll_back` ends the rollout, so the run ends `failed`, with the reason of the
+person as its output, and `jr2 run` exits with `1`. Its `context` holds the default of `canaryPercent`, the `instanceId`
+that jr2 added, and the `reason`:
+
+```text
+  emit {"type":"decided","promoted":false}
+  → active "rolledBack"
+  → failed "rolledBack"
+failed: The error rate went up.
+{"runId":"b7c3d871-e3ae-46af-8bb3-774913bcd6cc","workflow":"rollout","instanceId":"b79e7e8b-6289-4dbc-a9a3-be945f8b1173","status":"failed","value":"rolledBack","context":{"service":"billing","version":"1.4.0","canaryPercent":10,"instanceId":"b79e7e8b-6289-4dbc-a9a3-be945f8b1173","reason":"The error rate went up."},"children":[],"waiting":[],"held":[],"assembly":"83858e28b054","output":{"reason":"The error rate went up."}}
+```
+
+Your instance id and your `assembly` hash are different.
+
+[Start a run](start-a-run.md) gives the other ways to start a run. [Answer a Gate](answer-a-gate.md) gives the other
+ways to answer one.
+
+## Put shared code in a file that jr2 does not register
+
+jr2 registers each `.ts` file in `workflows/`, also a file that a different Workflow imports. It does not register a
+file whose name starts with `_`, or a `.d.ts` file. Thus put the code that two Workflows share in a file such as
+`workflows/_events.ts`, or outside `workflows/`. Import it with its `.ts` extension:
+`import { promote } from "./_events.ts";`.
+
+## Rules
+
+- `jr2 up` changes nothing when the Instance does not typecheck. It prints
+  `refusing: this instance does not typecheck — nothing was built and nothing was applied`, then each line of the output
+  of the compiler.
+- `npm run typecheck` does not find a refusal of `defineEvent`, `createMachine` or `workspace()`. These refusals occur
+  when a module loads. `jr2 up` loads each module after the typecheck and before it connects to the cluster, so a
+  refusal stops it before it changes the cluster.
+- Run [`jr2 check`](../reference/cli.md#check) (`npm run check` in the scaffold) to find these errors without a cluster.
+  It runs the typecheck and the load of each module that `jr2 up` runs first, with the same code, and it gives the same
+  refusals. It exits with `1` when it refuses. Run it before you say that a change is done. Do not import a workflow
+  module with `node`: in an installed Instance, `node` cannot load the Kit, because the Kit is TypeScript under
+  `node_modules`. The `jr2` binary can.
+- The name of a Workflow file has lower-case letters, digits and `-`, such as `release-notes.ts`. `jr2 up` refuses a
+  different name, and gives the name to use:
+  ``error: <folder>/workflows/<file>.ts: a Workflow is named by its filename stem, in lowercase letters, digits and "-", so that `jr2 run` and a `dispatch` slot name it the same way — rename it to <name>.ts (ADR-0071)``
+- `jr2 up` refuses a module with no `machine` export. It prints the error and exits with `1`:
+  ``error: workflow "<name>" (<file>) has no `machine` named export (module contract, ADR-0011/0015: `export const machine`)``
+- `defineEvent` refuses a name with a character other than a letter, a digit, `_` or `-`:
+  `defineEvent: invalid name "<name>" — must match /^[a-zA-Z0-9_-]+$/ (it becomes an MCP tool name and an xstate event type)`
+- `defineEvent` refuses an input with a `sender` field:
+  ``defineEvent: "<name>" declares `sender` in its input — the Orchestrator writes that field on every delivered event (who sent it); name the payload field something else``
+- `createMachine` refuses an `on` key that no listed event has. The compiler does not always find this error.
+  `jr2 check` and `jr2 up` find it when they load the module:
+  `machine "<id>" handles event "<key>", which no def in jr2Setup({ events }) declares (declared: <names>) — a typo, or a missing defineEvent`.
+  An `on` key with a `.` is a jr2 or xstate event, such as `agent.fault`, and you do not list it.
+- `createMachine` refuses a listed event that no state takes:
+  `machine "<id>" declares "<name>", which no state handles — a pick no state takes is on no Menu and no Gate: handle it, or drop it from jr2Setup({ events })`
+- `createMachine` refuses an entry of `events` that `defineEvent` did not make, and a name that you list two times:
+  ``machine "<id>": `events` entry is not a defineEvent() def: <entry>`` and
+  `` machine "<id>": duplicate event "<name>" in `events` ``
+- `createMachine` refuses an `agent()`, an Effect or a `workspace()` that a state writes in its `invoke.src`. Put it
+  under `actors`, and invoke it by its key:
+  `machine "<id>": state "<state>" invokes <part> inline — a Part is a key of actors, so it has a name that the ledger, the report and customize() share: actors: { <name>: <factory>(...) }, then invoke: { src: "<name>" }`
+- `jr2 up` refuses a registered Machine that has a zod `input` if `setup()` or `createMachine()` of xstate made the
+  Machine in place of `jr2Setup`. The compiler does not find this error:
+  ``refusing: workflow "<workflow>": machine "<id>" has a zod `input` on createMachine, but jr2Setup did not make this Machine, so no door reads that input: a run starts with any input, and the Console start form is only a field for JSON — make the Machine with jr2Setup in place of setup() or createMachine() (leave out `events` if it takes no workflow event) (ADR-0033)``.
+  The Orchestrator refuses a publish of that Machine with the same line.
+- `createMachine` refuses an `output` on a final state directly below the root when the root has no `output`, because
+  the run then has no output (see [Give the run an output](#give-the-run-an-output)). Move the `output` to the root, or
+  pass it on from the root:
+  `machine "<id>": final state "<state>" declares an output, and the root has no output — xstate v5 gives a run only its root output, so this output reaches nothing and the run ends with none: write it at the root, as output: ({ context }) => ..., or keep it on the final state and pass it on with output: ({ event }) => event.output at the root`.
+  With more than one such final state, the refusal names each one and puts the words in the plural:
+  `final states "<state>", "<state>" declare an output`, `these outputs reach nothing`, `write one at the root` and
+  `keep them on the final states and pass them on`. `jr2 check` and `jr2 up` also refuse this in a Machine that you make
+  with the `setup()` of xstate, and in a child Machine.
+- `createMachine` refuses a state that invokes an Agent when no `agent.fault` route is on that state or on a state above
+  it. jr2 sends `agent.fault` when the Turn of the Agent cannot go on. Route it on the state, or one time on the root:
+  `machine "<id>": state "<state>" invokes an Agent, and no route for "agent.fault" is on it or on a state above — jr2 sends agent.fault when the Agent's Turn cannot go on, and with no route the run faults: route it on that state or on a state above it, as on: { "agent.fault": "<the state that handles it>" } (ADR-0074)`.
+  With more than one such state, the refusal names each one: `states "<state>", "<state>" invoke an Agent` and
+  `is on them`. A state that invokes an [Open body](../concepts/charts.md) that lends an Agent or allows a model gets
+  the same refusal, with `invokes an Open body that can run an Agent`: the Open body sends the `agent.fault` of a
+  Chart's Agent that the Chart does not route to the Machine. `jr2 check` and `jr2 up` also refuse this in a Machine
+  that you make with the `setup()` of xstate, and in a child Machine.
+- `workspace()` refuses a body with a state that is not final when no `workspace.lost` route is on that state or on a
+  state above it. `workspace()` sends `workspace.lost` to the body when its Sandbox is gone. Route it on the root of the
+  body:
+  `workspace(): the body "<id>" has a state "<state>" that is not final, and no route for "workspace.lost" is on it or on a state above — jr2 sends workspace.lost to the body when its Sandbox is gone, and with no route the run faults: route it on the body's root, as on: { "workspace.lost": "<the state that handles it>" } (ADR-0074)`.
+  A compound state whose final child has no `onDone` is a state that the body stays in, so it needs the route too.
+- When a run gets `agent.fault` or `workspace.lost` and no transition takes it, for example because the guard of its
+  route is false, the run ends `error`. Its fault names the event, the state and the reason (ADR-0074).
+- `fail` refuses an input that has no `reason`, or a `reason` that is empty. The compiler finds a missing `reason`, but
+  not an empty one. The run ends `error`, and its fault is:
+  `fail: the input must be { reason: string; detail?: unknown } with a reason that is not empty (got <value>) — invoke: { src: "fail", input: { reason: "the tests failed" } } (ADR-0073)`.
+- `workspace()` refuses a body that declares a door. Declare the door with the `input` option of `workspace()`:
+  ``workspace(): the body "<id>" declares its own run input, which nothing will ever serve or enforce — the wrapper feeds the body the run input PLUS the injected `workspace` handles, so the body's schema is not the door. Move it to the wrapper: workspace(body, { input, spec }) (ADR-0033).``
+- `jr2 up` prints each refusal of `defineEvent`, `createMachine` and `workspace()` as `error: <refusal>`, and exits with
+  `1`. It changes nothing in the cluster.
+- The Orchestrator refuses a start whose input does not agree with the door, with the status code `400`:
+  `invalid input for workflow "<workflow>": <issues>`. `<issues>` is the list of the problems as JSON. `jr2 run` prints
+  `error: invalid input for workflow "<workflow>": <issues>` and exits with `1`. No run starts.
+- The Orchestrator refuses a name that no file in `workflows/` registers, with the status code `404`:
+  `no workflow registered as "<workflow>"`.
+
+## Read next
+
+- [Machines and Workflows](../concepts/machines-and-workflows.md)
+- [ADR-0011](../reference/decisions/0011-workflow-defined-events.md): the events are the Workflow's, and jr2 delivers
+  them.
+- [ADR-0015](../reference/decisions/0015-authoring-surface-absorbs-the-mechanism.md): `jr2Setup`, the Vocabulary and the
+  module contract.
+- [ADR-0033](../reference/decisions/0033-a-machine-declares-the-input-that-starts-it.md): the door.
+- [ADR-0050](../reference/decisions/0050-what-code-names-config-declares-what-the-cli-names-discovery-finds.md): jr2
+  finds a Workflow by its file name.
+- [Gates](../concepts/gates.md) and [The Menu](../concepts/the-menu.md)
+- [Set an Agent's access and Dials](set-an-agents-access-and-dials.md), to add an Agent to the Machine.
+- [Bind a shipped Machine's Open parts](bind-open-parts.md), to register a Machine from a package.
+- Reference: [`jr2Setup`](../reference/authoring-surface/jr2setup.md),
+  [`defineEvent`](../reference/authoring-surface/defineevent.md),
+  [`HostInjectedInput`](../reference/authoring-surface/type-hostinjectedinput.md),
+  [`GET /workflows/:name`](../reference/http-api.md#get-workflows-name)

package/docs/index.md

@@ -0,0 +1,44 @@
+---
+title: Home
+description: jr2 is a Kit for agentic workflows. You write each one as an xstate Machine, and jr2 runs it.
+---
+
+# Home
+
+jr2 is a Kit for agentic workflows. Each workflow is written as an [xstate](https://xstate.js.org)
+[Machine](https://stately.ai/docs/machines), and jr2 runs it on Kubernetes. An [Agent](reference/glossary.md#agent) that
+works on a [Repo](reference/glossary.md#repo) works in a [Sandbox](reference/glossary.md#sandbox): a pod with its own
+filesystem, network and processes. Your [Assistant](reference/glossary.md#assistant) writes the Machines, and you review
+the graph.
+
+jr2 supports two primary patterns for making Agent-enabled workflows. You can let the Machine decide the order of the
+work, and give each Agent one step of it in a [Turn](reference/glossary.md#turn). Or an Agent can decide when each step
+runs, and the Machine runs that step and limits the next choices
+([how to choose](concepts/the-menu.md#keep-the-turn-or-end-it)). In both patterns, the Machine sets what each step does.
+An Agent can also write a [Chart](reference/glossary.md#chart), much like a "dynamic workflow": jr2 checks it against
+the parts that your Machine lends it, and then executes it at runtime.
+
+## Start in three commands
+
+These commands install the jr2 CLI, make an [Instance](reference/glossary.md#instance) in the folder `my-instance`, and
+converge it into the cluster of your current kubectl context. First, install the tools and make the kind cluster, as
+[Install](get-started/install.md) tells you:
+
+```sh
+npm i -g @jr2/cli
+jr2 init my-instance && cd my-instance && npm install
+jr2 up
+```
+
+`jr2 init` writes one [Workflow](reference/glossary.md#workflow), `ping`, that runs with no model. The Get started
+tutorial gives these steps one at a time, and then runs `ping`.
+
+## Where to go next
+
+- [Why jr2](why.md) shows the parts of jr2, gives the problems that each part solves, and follows one run through them.
+- [Get started](get-started/install.md) is a tutorial. It goes from the install to a branch that an Agent fixed and that
+  you approved.
+- [Concepts](concepts/machines-and-workflows.md) explains each idea of jr2. For the picture of what runs where, read
+  [Architecture](concepts/architecture.md).
+- [Guides](guides/start-a-run.md) gives the steps for one task on each page.
+- [Reference](reference/authoring-surface.md) gives each export, config field, command and HTTP route, from the code.

package/docs/llms.txt

@@ -0,0 +1,216 @@
+# jr2
+
+> A kit for agentic workflows as xstate Machines, run on Kubernetes. These are the docs of Kit version 0.5.1, as plain Markdown.
+
+## Home
+
+- [Home](index.md): jr2 is a Kit for agentic workflows. You write each one as an xstate Machine, and jr2 runs it.
+
+## Why jr2
+
+- [Why jr2](why.md): The parts of jr2, the problems of agentic workflows that each part solves, and one run through them.
+
+## Get started
+
+- [Install](get-started/install.md): Install the tools that jr2 needs and the jr2 CLI, and make a kind cluster on your computer.
+- [Create an Instance](get-started/create-an-instance.md): Make an Instance folder, converge it into the kind cluster, run its first Workflow, and open the Console.
+- [Connect a model](get-started/connect-a-model.md): Add a model to the Instance, with its key or its address in .env, and converge the Instance again.
+- [A model decides](get-started/a-model-decides.md): Write a Workflow in which a model chooses the next state, and answer its question at a Gate.
+- [An Agent in a Sandbox](get-started/an-agent-in-a-sandbox.md): A coder Agent fixes a bug in your fork of jr2, in a Sandbox. You push its branch, and approve.
+- [Have your Assistant write a Machine](get-started/have-your-assistant-write-a-machine.md): Ask your Assistant for a Machine, read its graph in the Console, then run it and approve the push.
+
+## Concepts
+
+- [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.
+- [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.
+- [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.
+- [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.
+
+## Guides
+
+- [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.
+- [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.
+- [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.
+- [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.
+- [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.
+- [Clean up](guides/clean-up.md): Remove old images and unused Repo resources with jr2 gc, and remove an Instance with jr2 down.
+- [Fix a failed converge](guides/fix-a-failed-converge.md): Read what jr2 up prints when it refuses or fails, and fix the cause.
+- [Iterate on a Machine on kind](guides/iterate-on-a-machine-on-kind.md): Change a Machine, converge the change into your kind cluster, and run it again.
+- [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.
+- [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.
+- [Push and sign a branch](guides/push-and-sign-a-branch.md): Push the branch of a Workspace, 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.
+- [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.
+- [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.
+
+## 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.
+  - [`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.
+  - [`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.
+  - [`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 Worktree of each Repo Slot on one branch.
+  - [`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`, `workspace.branch`, `workspace.review`).
+  - [`Binding`](reference/authoring-surface/type-binding.md): The repository of a Repo Slot: `{ url, ref }`.
+  - [`RepoSlot`](reference/authoring-surface/type-reposlot.md): The value of one Repo Slot in `workspace({ repos })`.
+  - [`arg`](reference/authoring-surface/arg.md): Mark one argv entry of a `command` that the input of the Effect fills.
+  - [`CommandOutput`](reference/authoring-surface/type-commandoutput.md): The output of a `command` Effect: what the `onDone` of its state gets as `event.output`.
+  - [`command`](reference/authoring-surface/command.md): Make a `command` Effect: an actor slot that runs one program in the Workspace's Sandbox when a state invokes it.
+  - [`basic`](reference/authoring-surface/basic.md): Make the `auth` of an `http` Effect that sends `Authorization: Basic <value>`, where the value is the base64 of `user:password`.
+  - [`bearer`](reference/authoring-surface/bearer.md): Make the `auth` of an `http` Effect that sends `Authorization: Bearer <value>`, with the value of an Effect secret.
+  - [`file`](reference/authoring-surface/file.md): Make a Worktree file the body of an `http` Effect: `body: file("dist/report.pdf")`.
+  - [`http`](reference/authoring-surface/http.md): Make an `http` Effect: a call to a URL, with Effect secrets that the Agent never reads.
+  - [`secret`](reference/authoring-surface/secret.md): Name an Effect secret: `secret("jira")`.
+  - [`text`](reference/authoring-surface/text.md): Make a string from literal text and Effect secrets, as a tagged template: `` text`Token ${secret("x")}` ``.
+  - [`HttpOutput`](reference/authoring-surface/type-httpoutput.md): The output of an `http` Effect: what the `onDone` of its state gets as `event.output`.
+  - [`push`](reference/authoring-surface/push.md): Make a `push` Effect: it pushes the branch of the Workspace to the Binding of its Repo Slot.
+  - [`PushOutput`](reference/authoring-surface/type-pushoutput.md): The output of a `push` Effect: what the `onDone` of its state gets as `event.output`.
+  - [`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.
+  - [`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.
+  - [`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.
+  - [`source`](reference/authoring-surface/source.md): Declare a Source: where a `pool()` gets its work items, one at a time.
+  - [`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.
+  - [`chartSchema`](reference/authoring-surface/chartschema.md): The Chart grammar, as a zod schema.
+  - [`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.
+  - [`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.
+  - [`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`.
+  - [`WorkspaceAccess`](reference/authoring-surface/type-workspaceaccess.md): What an Agent may do to the Workspace: `"write"`, `"read"` or `"none"`.
+  - [`WorkspaceOptions`](reference/authoring-surface/type-workspaceoptions.md): The options of a `workspace()` that declares the input that starts a run.
+  - [`NoSlotWorkspaceOptions`](reference/authoring-surface/type-noslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot that declares the input that starts a run.
+  - [`WithoutEmptyIndex`](reference/authoring-surface/type-withoutemptyindex.md): The fields of the run input `T`.
+  - [`PermissiveWorkspaceOptions`](reference/authoring-surface/type-permissiveworkspaceoptions.md): The options of a `workspace()` with no `input`: it starts with any input.
+  - [`PermissiveNoSlotWorkspaceOptions`](reference/authoring-surface/type-permissivenoslotworkspaceoptions.md): The options of a `workspace()` with no Repo Slot and no `input`: it starts with any input.
+  - [`WorkspaceHandles`](reference/authoring-surface/type-workspacehandles.md): What the body of a `workspace()` gets as `input.workspace`: the path of each Worktree, and the branch.
+  - [`ExecOutcome`](reference/authoring-surface/type-execoutcome.md): How an exec ended.
+  - [`Unknown`](reference/authoring-surface/type-unknown.md): The output `{ outcome: "unknown", reason }`: the Effect may have acted, and jr2 cannot tell.
+  - [`Arg`](reference/authoring-surface/type-arg.md): One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it.
+  - [`CommandOptions`](reference/authoring-surface/type-commandoptions.md): The options of `command()`: the Repo Slot it runs in, how long it can run, how much of its output it keeps, its Effect secrets, and the commit it runs against.
+  - [`CommandInput`](reference/authoring-surface/type-commandinput.md): A command's input: one string per argv slot, and with `pin` the approved commit (`{ sha }`); none when there is neither.
+  - [`OpenCommandInput`](reference/authoring-surface/type-opencommandinput.md): The input of a `command(open)`: a string for each `arg()` of the argv that the Instance binds, and with `pin`, the commit (`{ sha }`).
+  - [`Secret`](reference/authoring-surface/type-secret.md): What `secret("name")` gives: an Effect secret, by its name in the `secrets` list of `jr2.config.ts`.
+  - [`Text`](reference/authoring-surface/type-text.md): What the `text` template gives: a string of literal text and Effect secrets, in order.
+  - [`FromInput`](reference/authoring-surface/type-frominput.md): A value of a file body's part: as written, or from the Effect's input.
+  - [`FileBody`](reference/authoring-surface/type-filebody.md): `file(path, { slot?, segments?, contentType? })`: a Worktree file as an `http` body.
+  - [`HttpDefinition`](reference/authoring-surface/type-httpdefinition.md): An `http` Effect's definition.
+  - [`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: `{ sha }` with `pin`, and `{ message }` with `squash`.
+  - [`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.
+  - [`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.
+  - [`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).
+  - [`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.
+  - [`WorkspaceSpec`](reference/authoring-surface/type-workspacespec.md): What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields.
+  - [`NoSlotSpec`](reference/authoring-surface/type-noslotspec.md): What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`.
+  - [`SlotHandles`](reference/authoring-surface/type-slothandles.md): The handles of a Workspace that declares Repo Slots.
+  - [`Duration`](reference/authoring-surface/type-duration.md): A length of time: a positive number and a unit, `s`, `m` or `h`.
+  - [`CommandEnv`](reference/authoring-surface/type-commandenv.md): The `env` of a `command`: for each variable, `secret("name")` for the value of an Effect secret, or `secret("name").path` for the path of a file that holds it.
+  - [`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.
+  - [`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.
+  - [`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.
+  - [`ChartAgent`](reference/authoring-surface/type-chartagent.md): An Agent a Chart mints: the plain fields of an Agent definition (ADR-0049).
+  - [`ChartState`](reference/authoring-surface/type-chartstate.md): A state node.
+  - [`ChartValue`](reference/authoring-surface/type-chartvalue.md): A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be `{ "$ref": "<root>.<path>" }`.
+  - [`ChartInvoke`](reference/authoring-surface/type-chartinvoke.md): An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`.
+  - [`ChartTransitions`](reference/authoring-surface/type-charttransitions.md): One transition or a list, in xstate's order.
+  - [`ChartAction`](reference/authoring-surface/type-chartaction.md): An action.
+  - [`ChartTransition`](reference/authoring-surface/type-charttransition.md): A transition: a target alone, or the object form.
+  - [`ChartGuard`](reference/authoring-surface/type-chartguard.md): A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or `not`/`and`/`or`.
+  - [`ToProvidedActor`](reference/authoring-surface/type-toprovidedactor.md): A type that the Authoring surface names.
+  - [`MergedActors`](reference/authoring-surface/type-mergedactors.md): A type that the Authoring surface names.
+  - [`ToParameterizedObject`](reference/authoring-surface/type-toparameterizedobject.md): A type that the Authoring surface names.
+  - [`SentByGuards`](reference/authoring-surface/type-sentbyguards.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.
+  - [`BodyAcceptsSlots`](reference/authoring-surface/type-bodyacceptsslots.md): A type that the Authoring surface names.
+  - [`EffectLogic`](reference/authoring-surface/type-effectlogic.md): A type that the Authoring surface names.
+  - [`OpenOf`](reference/authoring-surface/type-openof.md): A type that the Authoring surface names.
+  - [`EnvOpenParts`](reference/authoring-surface/type-envopenparts.md): A type that the Authoring surface names.
+  - [`OpenEffect`](reference/authoring-surface/type-openeffect.md): A type that the Authoring surface names.
+  - [`MarkedIf`](reference/authoring-surface/type-markedif.md): A type that the Authoring surface names.
+  - [`HttpInput`](reference/authoring-surface/type-httpinput.md): A type that the Authoring surface names.
+  - [`HttpOpenParts`](reference/authoring-surface/type-httpopenparts.md): A type that the Authoring surface names.
+  - [`PushWireOutput`](reference/authoring-surface/type-pushwireoutput.md): A type that the Authoring surface names.
+  - [`SyncState`](reference/authoring-surface/type-syncstate.md): A type that the Authoring surface names.
+  - [`AnswerAction`](reference/authoring-surface/type-answeraction.md): A type that the Authoring surface names.
+  - [`AgentSlots`](reference/authoring-surface/type-agentslots.md): A type that the Authoring surface names.
+  - [`Reached`](reference/authoring-surface/type-reached.md): A type that the Authoring surface names.
+  - [`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.
+  - [`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.
+  - [`ArgNames`](reference/authoring-surface/type-argnames.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.
+- [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.
+- [Mechanism events](reference/mechanism-events.md): The events that jr2 itself sends into every jr2Setup Machine, and their payloads.
+- [Glossary](reference/glossary.md): The terms of jr2: what each one means, and the words to avoid.
+- [Decisions](reference/decisions.md): Every architecture decision record of jr2, by number.