@jr2/orchestrator 0.3.0 → 0.5.1

package/docs/reference/authoring-surface/type-agentdefinition.md

@@ -0,0 +1,80 @@
+---
+title: AgentDefinition
+description: "An Agent's definition: which model it runs, its instructions, and what it may do to the Workspace."
+---
+
+# `AgentDefinition`
+
+Type, in `@jr2/orchestrator/src/agent.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Agents.
+
+```ts
+type AgentDefinition = {
+  model: string;
+  instructions: string;
+  description?: string;
+  thinkingLevel?: ThinkingLevel;
+  workspace?: WorkspaceAccess;
+};
+```
+
+An Agent's definition: which model it runs, its instructions, and what it may do to the
+Workspace. Give it to `agent()` to get the Agent's actor slot. It is plain data that can be
+written as JSON.
+
+It holds who the Agent is, not what one Turn does. The prompt of a Turn and the directory it
+works in are the Frame. The state that invokes the Agent sets the Frame in the invoke's
+`input`. That `input` can also set `model` and `thinkingLevel` for one Turn: the Dials. It
+cannot change `instructions` or `workspace`.
+
+**Fields**
+
+- `model`: `string`
+
+  The model, as `<provider>/<modelId>`: for example `anthropic/claude-haiku-5-5`. The
+  provider must be one that `jr2.config.ts` can reach. Here it is always a string: an `open`
+  model of `agent()` must be bound before a Turn starts. One Turn may set another model in the
+  invoke's `input`.
+- `instructions`: `string`
+
+  The Agent's instructions: the text that tells the model who it is and how to work. The same
+  on every Turn.
+- `description` (optional): `string`
+
+  A short description, for people who read the Machine. The model never reads it.
+- `thinkingLevel` (optional): [`ThinkingLevel`](type-thinkinglevel.md)
+
+  How hard the model thinks: one of [`ThinkingLevel`](type-thinkinglevel.md). Absent: `"off"`. A model with no
+  `"off"` runs at another level, and the printed conversation names it. One Turn may set another
+  level in the invoke's `input`.
+- `workspace` (optional): [`WorkspaceAccess`](type-workspaceaccess.md)
+
+  What the Agent may do to the Workspace. Default: `"write"`.
+  - `"write"`: all the Working tools (read, write, edit, bash, grep, glob).
+  - `"read"`: no write or edit tool. The Agent keeps bash, so `"read"` does not stop a command
+    that writes. To keep the Agent from changing the branch, frame its Turn in the review
+    Worktree: `reviewSha` in the spec, then `cwd: context.workspace.review?.<slot>`.
+  - `"none"`: no Working tools. The Agent only reads its prompt and picks from its Menu. Its Turn
+    runs on the Instance Harness, not in a Sandbox, so it needs no `workspace()` around it.
+
+**Example**
+
+```ts
+import { agent, type AgentDefinition } from "@jr2/orchestrator";
+
+const definition: AgentDefinition = {
+  model: "anthropic/claude-haiku-5-5",
+  instructions: "You fix the failing test, and you change nothing else.",
+  description: "Fixes one failing test",
+  thinkingLevel: "medium",
+  workspace: "write",
+};
+
+export const coder = agent(definition);
+```
+
+**See also**
+
+- [Agents and Turns](../../concepts/agents-and-turns.md)
+- [Set an Agent's access and Dials](../../guides/set-an-agents-access-and-dials.md)
+- [ADR-0018: The instance authors Agent definitions; jr2 assembles the Harness](../decisions/0018-instance-agents-are-definitions-jr2-assembles-the-harness.md)
+- [ADR-0028: What an Agent may do to the Workspace is part of its definition](../decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md)

package/docs/reference/authoring-surface/type-agentlogic.md

@@ -0,0 +1,15 @@
+---
+title: AgentLogic
+description: A type that the Authoring surface names.
+---
+
+# `AgentLogic`
+
+Type, in `@jr2/orchestrator/src/actor.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type AgentLogic = CallbackActorLogic<
+  AgentRunReceiveEvent,
+  AgentTurnInput | (AgentTurnInput & AgentTurnPlacement) | AgentRunInput
+>;
+```

package/docs/reference/authoring-surface/type-agentslots.md

@@ -0,0 +1,12 @@
+---
+title: AgentSlots
+description: A type that the Authoring surface names.
+---
+
+# `AgentSlots`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type AgentSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AgentLogic }>["src"];
+```

package/docs/reference/authoring-surface/type-answeraction.md

@@ -0,0 +1,12 @@
+---
+title: AnswerAction
+description: A type that the Authoring surface names.
+---
+
+# `AnswerAction`
+
+Type, in `@jr2/orchestrator/src/pick.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type AnswerAction = { readonly jr2Answer: true };
+```

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

@@ -0,0 +1,19 @@
+---
+title: Arg
+description: "One entry of a command's argv that the input of the Effect fills, as `arg(\"name\")` makes it."
+---
+
+# `Arg`
+
+Type, in `@jr2/orchestrator/src/effect.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Arg<N extends string = string> = { readonly arg: N };
+```
+
+One entry of a command's argv that the input of the Effect fills, as `arg("name")` makes it. It
+is one argument, whatever its text. No shell reads it.
+
+**Fields**
+
+- `arg`: `N`

package/docs/reference/authoring-surface/type-argnames.md

@@ -0,0 +1,12 @@
+---
+title: ArgNames
+description: A type that the Authoring surface names.
+---
+
+# `ArgNames`
+
+Type, in `@jr2/orchestrator/src/effect.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type ArgNames<A extends readonly unknown[]> = A[number] extends infer E ? (E extends Arg<infer N> ? N : never) : never;
+```

package/docs/reference/authoring-surface/type-binding.md

@@ -0,0 +1,62 @@
+---
+title: Binding
+description: "The repository of a Repo Slot: `{ url, ref }`."
+---
+
+# `Binding`
+
+Type, in `@jr2/orchestrator/src/parts.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+
+```ts
+type Binding = {
+  url: string;
+  ref?: string;
+};
+```
+
+The repository of a Repo Slot: `{ url, ref }`. `url` is the Repo's git url. `ref` is the branch
+or commit that the branch Worktree starts from; absent, the Repo's default branch. Where only a
+url is needed, a string is enough.
+
+`workspace()` and `customize()` refuse:
+- an empty `url`: ``<where>: Repo Slot "<slot>" is bound to an empty url (got <value>) — a slot
+  is `open`, a url, `{ url, ref? }`, or a mapper `({ input }) => url | { url, ref? }` over the
+  door (ADR-0051).``
+- an empty `ref`: the same text, with `bound with an empty ref` in place of `bound to an empty
+  url`.
+- a url that names no Repo, such as a relative path: ``<where>: Repo Slot "<slot>" binds
+  "<url>", which names no Repo — <reason> (ADR-0051).``
+
+**Fields**
+
+- `url`: `string`
+
+  The Repo's git url.
+- `ref` (optional): `string`
+
+  The branch or commit that the branch Worktree starts from. Default: the Repo's default
+  branch.
+
+**Example**
+
+```ts
+import { jr2Setup, workspace, type Binding } from "@jr2/orchestrator";
+
+const app: Binding = { url: "https://github.com/you/app.git", ref: "release-2" };
+
+const body = jr2Setup().createMachine({
+  id: "body",
+  initial: "done",
+  states: { done: { type: "final" } },
+});
+
+export const machine = workspace(body, {
+  repos: { app },
+  spec: () => ({ branch: "jr2/hotfix" }),
+});
+```
+
+**See also**
+
+- [Workspaces](../../concepts/workspaces.md)
+- [ADR-0051: A Repo is a slot on the `workspace()` and a cache on the node](../decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md)

package/docs/reference/authoring-surface/type-bindingof.md

@@ -0,0 +1,12 @@
+---
+title: BindingOf
+description: A type that the Authoring surface names.
+---
+
+# `BindingOf`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type BindingOf<L> = L extends OpenEffect<infer P> ? Intersected<PartBinding<P>> : never;
+```

package/docs/reference/authoring-surface/type-bodyacceptsdoor.md

@@ -0,0 +1,15 @@
+---
+title: BodyAcceptsDoor
+description: A type that the Authoring surface names.
+---
+
+# `BodyAcceptsDoor`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type BodyAcceptsDoor<TBody extends AnyStateMachine, TDoor, TSlots extends string> =
+  TDoor & Workspaced<TDoor, TSlots> & HostInjectedInput extends InputFrom<TBody>
+    ? BodyNamesNoSlotUnderOpenMap<TBody, TSlots>
+    : { "the body's declared input must accept the door plus the injected handles": Workspaced<TDoor, TSlots> };
+```

package/docs/reference/authoring-surface/type-bodyacceptsslots.md

@@ -0,0 +1,17 @@
+---
+title: BodyAcceptsSlots
+description: A type that the Authoring surface names.
+---
+
+# `BodyAcceptsSlots`
+
+Type, in `@jr2/orchestrator/src/workspace.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type BodyAcceptsSlots<TBody extends AnyStateMachine, TSlots extends string> =
+  InputFrom<TBody> extends { workspace: infer THandles }
+    ? WorkspaceHandles<TSlots> extends THandles
+      ? BodyNamesNoSlotUnderOpenMap<TBody, TSlots>
+      : { "the body's declared handles must accept the Repo Slots the wrapper declares": WorkspaceHandles<TSlots> }
+    : unknown;
+```

package/docs/reference/authoring-surface/type-ceilings.md

@@ -0,0 +1,41 @@
+---
+title: Ceilings
+description: The limits that an Open body sets on its Chart.
+---
+
+# `Ceilings`
+
+Type, in `@jr2/orchestrator/src/open-body.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type Ceilings = {
+  turns: number;
+  wallClock: Duration;
+  transitions: number;
+  fanOut: number;
+  size: number;
+};
+```
+
+The limits that an Open body sets on its Chart. Each one is a positive bound. When the Chart gets
+to one, the Open body stops it and ends with `{ outcome: "ceiling", ceiling, detail }`.
+
+**Fields**
+
+- `turns`: `number`
+
+  The Agent Turns that start under the Open body, at all levels. The Turns of a lent Machine
+  count too.
+- `wallClock`: [`Duration`](type-duration.md)
+
+  The time from the start of the Open body, such as `"30m"`. At most about 596 hours.
+- `transitions`: `number`
+
+  The transitions of the Chart in the whole run. xstate has no guard against a loop, so this is
+  the guard.
+- `fanOut`: `number`
+
+  The children that run under the Open body at one time.
+- `size`: `number`
+
+  The size of the Chart, as JSON, in bytes. At most 1048576 (1 MiB).

package/docs/reference/authoring-surface/type-chainlink.md

@@ -0,0 +1,19 @@
+---
+title: ChainLink
+description: "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."
+---
+
+# `ChainLink`
+
+Type, in `@jr2/orchestrator/src/pick.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChainLink<TActor extends ProvidedActor, TEvent extends EventObject> =
+  | (TActor extends unknown ? { kind: "output"; src: TActor["src"]; output: OutputFrom<TActor["logic"]> } : never)
+  | { kind: "event"; event: Exclude<TEvent, { type: `${string}.${string}` }> };
+```
+
+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. A reply is from outside the Machine: the events it sends
+itself are not links.

package/docs/reference/authoring-surface/type-chartaction.md

@@ -0,0 +1,46 @@
+---
+title: ChartAction
+description: An action.
+---
+
+# `ChartAction`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartAction =
+  | { type: "set"; path: string; from: ChartValue }
+  | { type: "append"; path: string; from: ChartValue }
+  | { type: "increment"; path: string; by?: number }
+  | { type: "clear"; path: string }
+  | { type: string; params?: ChartValue };
+```
+
+An action. The four generic ones write the run's context at `path`, a context path WITHOUT the
+`context.` root (`"round"`, `"ticket.notes"`, `"items.0"`); every other `type` is a lent action.
+
+**Forms**: it is one of these objects.
+
+- Form 1: `type`, `path`, `from`
+
+  - `type`: `"set"`
+  - `path`: `string`
+  - `from`: [`ChartValue`](type-chartvalue.md)
+- Form 2: `type`, `path`, `from`
+
+  - `type`: `"append"`
+  - `path`: `string`
+  - `from`: [`ChartValue`](type-chartvalue.md)
+- Form 3: `type`, `path`, `by`
+
+  - `type`: `"increment"`
+  - `path`: `string`
+  - `by` (optional): `number`
+- Form 4: `type`, `path`
+
+  - `type`: `"clear"`
+  - `path`: `string`
+- Form 5: `type`, `params`
+
+  - `type`: `string`
+  - `params` (optional): [`ChartValue`](type-chartvalue.md)

package/docs/reference/authoring-surface/type-chartagent.md

@@ -0,0 +1,28 @@
+---
+title: ChartAgent
+description: "An Agent a Chart mints: the plain fields of an Agent definition (ADR-0049)."
+---
+
+# `ChartAgent`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartAgent = {
+  model: string;
+  instructions: string;
+  description?: string;
+  thinkingLevel?: ThinkingLevel;
+  workspace?: WorkspaceAccess;
+};
+```
+
+An Agent a Chart mints: the plain fields of an Agent definition ([ADR-0049](../decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md)).
+
+**Fields**
+
+- `model`: `string`
+- `instructions`: `string`
+- `description` (optional): `string`
+- `thinkingLevel` (optional): [`ThinkingLevel`](type-thinkinglevel.md)
+- `workspace` (optional): [`WorkspaceAccess`](type-workspaceaccess.md)

package/docs/reference/authoring-surface/type-chartevent.md

@@ -0,0 +1,20 @@
+---
+title: ChartEvent
+description: "An event a Chart mints: its payload is a JSON Schema object, built into zod at admission."
+---
+
+# `ChartEvent`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartEvent = { description?: string; input: Record<string, unknown>; audience?: EventAudience };
+```
+
+An event a Chart mints: its payload is a JSON Schema object, built into zod at admission.
+
+**Fields**
+
+- `description` (optional): `string`
+- `input`: `Record<string, unknown>`
+- `audience` (optional): [`EventAudience`](type-eventaudience.md)

package/docs/reference/authoring-surface/type-chartguard.md

@@ -0,0 +1,20 @@
+---
+title: ChartGuard
+description: "A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or `not`/`and`/`or`."
+---
+
+# `ChartGuard`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartGuard =
+  | string
+  | { type: string; params?: ChartValue }
+  | { not: ChartGuard }
+  | { and: ChartGuard[] }
+  | { or: ChartGuard[] };
+```
+
+A guard: a lent guard by name, with or without params, `jr2.sentBy`, `jr2.failure`, or
+`not`/`and`/`or`.

package/docs/reference/authoring-surface/type-chartinvoke.md

@@ -0,0 +1,28 @@
+---
+title: ChartInvoke
+description: "An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`."
+---
+
+# `ChartInvoke`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartInvoke = {
+  src: string;
+  id?: string;
+  input?: ChartValue;
+  onDone?: ChartTransitions;
+  onError?: ChartTransitions;
+};
+```
+
+An invoke: a lent Agent, Effect or Machine, a minted Agent, or the kit's `gate` or `fail`.
+
+**Fields**
+
+- `src`: `string`
+- `id` (optional): `string`
+- `input` (optional): [`ChartValue`](type-chartvalue.md)
+- `onDone` (optional): [`ChartTransitions`](type-charttransitions.md)
+- `onError` (optional): [`ChartTransitions`](type-charttransitions.md)

package/docs/reference/authoring-surface/type-chartjson.md

@@ -0,0 +1,14 @@
+---
+title: ChartJson
+description: Plain JSON.
+---
+
+# `ChartJson`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartJson = string | number | boolean | null | ChartJson[] | { [key: string]: ChartJson };
+```
+
+Plain JSON.

package/docs/reference/authoring-surface/type-chartstate.md

@@ -0,0 +1,46 @@
+---
+title: ChartState
+description: A state node.
+---
+
+# `ChartState`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartState = {
+  type?: "atomic" | "compound" | "parallel" | "final" | "history";
+  initial?: string;
+  states?: Record<string, ChartState>;
+  history?: "shallow" | "deep";
+  invoke?: ChartInvoke | ChartInvoke[];
+  on?: Record<string, ChartTransitions>;
+  always?: ChartTransitions;
+  after?: Record<string, ChartTransitions>;
+  entry?: ChartAction[];
+  exit?: ChartAction[];
+  output?: ChartValue;
+  meta?: ChartJson;
+  tags?: string[];
+  description?: string;
+};
+```
+
+A state node.
+
+**Fields**
+
+- `type` (optional): `"atomic" | "compound" | "parallel" | "final" | "history"`
+- `initial` (optional): `string`
+- `states` (optional): `Record<string, ChartState>`
+- `history` (optional): `"shallow" | "deep"`
+- `invoke` (optional): `ChartInvoke | ChartInvoke[]`
+- `on` (optional): `Record<string, ChartTransitions>`
+- `always` (optional): [`ChartTransitions`](type-charttransitions.md)
+- `after` (optional): `Record<string, ChartTransitions>`
+- `entry` (optional): `ChartAction[]`
+- `exit` (optional): `ChartAction[]`
+- `output` (optional): [`ChartValue`](type-chartvalue.md)
+- `meta` (optional): [`ChartJson`](type-chartjson.md)
+- `tags` (optional): `string[]`
+- `description` (optional): `string`

package/docs/reference/authoring-surface/type-charttext.md

@@ -0,0 +1,40 @@
+---
+title: ChartText
+description: The Chart text (ADR-0070).
+---
+
+# `ChartText`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartText = {
+  version?: 1;
+  id?: string;
+  context?: Record<string, ChartJson>;
+  events?: Record<string, ChartEvent>;
+  agents?: Record<string, ChartAgent>;
+  initial: string;
+  states: Record<string, ChartState>;
+  output?: ChartValue;
+};
+```
+
+The Chart text ([ADR-0070](../decisions/0070-a-machine-lends-its-parts-to-a-chart.md)). Every key here is the whole grammar: the door refuses any other.
+
+**Fields**
+
+- `version` (optional): `1`
+- `id` (optional): `string`
+
+  The machine id. Default: the Open body's slot key. A `#` target needs it.
+- `context` (optional): `Record<string, ChartJson>`
+
+  The initial context: plain JSON, no references.
+- `events` (optional): `Record<string, ChartEvent>`
+- `agents` (optional): `Record<string, ChartAgent>`
+- `initial`: `string`
+- `states`: `Record<string, ChartState>`
+- `output` (optional): [`ChartValue`](type-chartvalue.md)
+
+  The Chart's output, resolved when the Chart is done.

package/docs/reference/authoring-surface/type-charttransition.md

@@ -0,0 +1,22 @@
+---
+title: ChartTransition
+description: "A transition: a target alone, or the object form."
+---
+
+# `ChartTransition`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartTransition =
+  | string
+  | {
+      target?: string | string[];
+      guard?: ChartGuard;
+      actions?: ChartAction[];
+      reenter?: boolean;
+      description?: string;
+    };
+```
+
+A transition: a target alone, or the object form.

package/docs/reference/authoring-surface/type-charttransitions.md

@@ -0,0 +1,14 @@
+---
+title: ChartTransitions
+description: "One transition or a list, in xstate's order."
+---
+
+# `ChartTransitions`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartTransitions = ChartTransition | ChartTransition[];
+```
+
+One transition or a list, in xstate's order.

package/docs/reference/authoring-surface/type-chartvalue.md

@@ -0,0 +1,15 @@
+---
+title: ChartValue
+description: "A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be `{ \"$ref\": \"<root>.<path>\" }`."
+---
+
+# `ChartValue`
+
+Type, in `@jr2/orchestrator/src/chart.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
+
+```ts
+type ChartValue = ChartJson;
+```
+
+A value whose strings may hold `{{<root>.<path>}}` placeholders and whose objects may be
+`{ "$ref": "<root>.<path>" }`. Resolved by `resolveReferences` at invoke time.

package/docs/reference/authoring-surface/type-childat.md

@@ -0,0 +1,12 @@
+---
+title: ChildAt
+description: A type that the Authoring surface names.
+---
+
+# `ChildAt`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type ChildAt<M extends AnyStateMachine, K extends string> = Extract<LogicAt<M, K>, AnyStateMachine>;
+```

package/docs/reference/authoring-surface/type-childslots.md

@@ -0,0 +1,12 @@
+---
+title: ChildSlots
+description: A type that the Authoring surface names.
+---
+
+# `ChildSlots`
+
+Type, in `@jr2/orchestrator/src/customize.ts`. It is type plumbing: it computes a type from the types of a Machine or of its parts, and a workflow module does not write it. The signature of an export, or a type that it names, names this type, so its declaration is here. The [Authoring surface](../authoring-surface.md) page lists each export.
+
+```ts
+type ChildSlots<M extends AnyStateMachine> = Extract<SlotsOf<M>, { logic: AnyStateMachine }>["src"];
+```