@jr2/orchestrator 0.4.1 → 0.6.0

package/docs/concepts/composition.md

@@ -0,0 +1,357 @@
+---
+title: Composition
+description: How a Machine composes Machines that you import, and how you bind the parts that they leave Open.
+---
+
+# Composition
+
+Composition is how you make a [Workflow](../reference/glossary.md#workflow) from
+[Machines](../reference/glossary.md#machine) that exist already. It has three parts. A Machine invokes a different
+Machine as its child. [`customize()`](../reference/authoring-surface/customize.md) changes the parts that a Machine
+carries. And you bind the parts that a Machine leaves [Open](../reference/glossary.md#open). The kit ships Machines for
+you to compose in this way, in the package [`@jr2/machines`](../reference/machines.md).
+
+## Why it exists
+
+A Machine that you import must work in your [Instance](../reference/glossary.md#instance) with no change to its module.
+Thus a Machine carries all that it needs: its [Vocabulary](../reference/glossary.md#vocabulary), its
+[Agents](../reference/glossary.md#agent), its [Effects](../reference/glossary.md#effect), its
+[Sandbox Image](../reference/glossary.md#sandbox-image) and its [Repo Slots](../reference/glossary.md#repo-slot). The
+Machine does not need an Agent list or event names from the Instance. The Instance gives only access and defaults.
+Access is the model provider and its key, the secrets, and the git credentials. A default is a Sandbox Image or a
+[Size](../reference/glossary.md#size) for a Machine that states none.
+
+A package cannot know some parts. It does not know your [Repo](../reference/glossary.md#repo), and it cannot pay for
+your model. The package leaves these parts Open. You bind them where you register the Machine as a Workflow, or where
+you compose it. If you do not bind an Open part, [`jr2 up`](../reference/cli.md#up) stops before it converges. Thus a
+missing part does not become a run that spends money on a model that nobody chose.
+
+## A Machine inside a Machine
+
+A Machine composes a different Machine as an [xstate](https://xstate.js.org) child. It imports the Machine, puts it
+under `actors`, and a state invokes it by its key. The key is a slot, the same as the slot of an Agent.
+
+This Machine composes the shipped Machine [`task`](../reference/machines.md#task) two times. A
+[Menu](../reference/glossary.md#menu)-only Agent, `triager`, reads the prompt first. Then the run goes to one of the two
+copies of `task`. The copies differ only in the thinking level of their coder.
+
+The Workflow, with the model of the tab:
+
+**Anthropic**
+
+```ts
+import { z } from "zod";
+import { agent, customize, defineEvent, fail, jr2Setup, type HostInjectedInput } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const model = "anthropic/claude-haiku-5-5";
+
+// Bind the two Open parts of `task`: the Repo that the coder works in, and the coder's model.
+const coding = customize(task, {
+  repos: { target: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model } },
+});
+
+// Two changed copies of one Machine. `coding` does not change.
+const deep = customize(coding, { agents: { coder: { thinkingLevel: "high" } } });
+const quick = customize(coding, { agents: { coder: { thinkingLevel: "low" } } });
+
+const door = z.object({ prompt: z.string().describe("What to do, in prose.") });
+
+const route = defineEvent({
+  name: "route",
+  description: "Say how much care the task needs.",
+  audience: "agent",
+  input: z.object({
+    size: z.enum(["small", "large"]).describe("small: a change to one file. large: any other change."),
+  }),
+});
+
+type Input = HostInjectedInput & z.infer<typeof door>;
+
+export const machine = jr2Setup({
+  types: {} as { input: Input; context: Input },
+  events: [route],
+  actors: {
+    triager: agent({
+      model,
+      workspace: "none",
+      thinkingLevel: "off",
+      instructions: "Read the task. Call route once: small for a change to one file, large for any other change.",
+    }),
+    // Each composed Machine is a slot, like an Agent.
+    deep,
+    quick,
+    fail: fail(),
+  },
+}).createMachine({
+  id: "route",
+  input: door,
+  context: ({ input }) => input,
+  on: { "agent.fault": ".failed" },
+  initial: "triaging",
+  states: {
+    triaging: {
+      invoke: { src: "triager", input: ({ context }) => ({ prompt: context.prompt }) },
+      on: {
+        route: [{ guard: ({ event }) => event.size === "large", target: "deep" }, { target: "quick" }],
+      },
+    },
+    // A composed `task` gets its input from this Machine, so it needs a branch.
+    deep: {
+      invoke: {
+        src: "deep",
+        input: ({ context }) => ({ prompt: context.prompt, branch: `jr2/route-${context.instanceId}` }),
+        onDone: "done",
+      },
+    },
+    quick: {
+      invoke: {
+        src: "quick",
+        input: ({ context }) => ({ prompt: context.prompt, branch: `jr2/route-${context.instanceId}` }),
+        onDone: "done",
+      },
+    },
+    done: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+**Local**
+
+```ts
+import { z } from "zod";
+import { agent, customize, defineEvent, fail, jr2Setup, type HostInjectedInput } from "@jr2/orchestrator";
+import { task } from "@jr2/machines";
+
+const model = "local/qwen3.6-35b-a3b";
+
+// Bind the two Open parts of `task`: the Repo that the coder works in, and the coder's model.
+const coding = customize(task, {
+  repos: { target: { url: "https://github.com/you/app.git" } },
+  agents: { coder: { model } },
+});
+
+// Two changed copies of one Machine. `coding` does not change.
+const deep = customize(coding, { agents: { coder: { thinkingLevel: "high" } } });
+const quick = customize(coding, { agents: { coder: { thinkingLevel: "low" } } });
+
+const door = z.object({ prompt: z.string().describe("What to do, in prose.") });
+
+const route = defineEvent({
+  name: "route",
+  description: "Say how much care the task needs.",
+  audience: "agent",
+  input: z.object({
+    size: z.enum(["small", "large"]).describe("small: a change to one file. large: any other change."),
+  }),
+});
+
+type Input = HostInjectedInput & z.infer<typeof door>;
+
+export const machine = jr2Setup({
+  types: {} as { input: Input; context: Input },
+  events: [route],
+  actors: {
+    triager: agent({
+      model,
+      workspace: "none",
+      thinkingLevel: "off",
+      instructions: "Read the task. Call route once: small for a change to one file, large for any other change.",
+    }),
+    // Each composed Machine is a slot, like an Agent.
+    deep,
+    quick,
+    fail: fail(),
+  },
+}).createMachine({
+  id: "route",
+  input: door,
+  context: ({ input }) => input,
+  on: { "agent.fault": ".failed" },
+  initial: "triaging",
+  states: {
+    triaging: {
+      invoke: { src: "triager", input: ({ context }) => ({ prompt: context.prompt }) },
+      on: {
+        route: [{ guard: ({ event }) => event.size === "large", target: "deep" }, { target: "quick" }],
+      },
+    },
+    // A composed `task` gets its input from this Machine, so it needs a branch.
+    deep: {
+      invoke: {
+        src: "deep",
+        input: ({ context }) => ({ prompt: context.prompt, branch: `jr2/route-${context.instanceId}` }),
+        onDone: "done",
+      },
+    },
+    quick: {
+      invoke: {
+        src: "quick",
+        input: ({ context }) => ({ prompt: context.prompt, branch: `jr2/route-${context.instanceId}` }),
+        onDone: "done",
+      },
+    },
+    done: { type: "final" },
+    failed: { invoke: { src: "fail", input: { reason: "the Agent's Turn could not go on" } } },
+  },
+});
+```
+
+To use `@jr2/machines`, add it to the Instance at the [Kit version](../reference/glossary.md#kit-version):
+`npm install --save-exact @jr2/machines@<version>`. `<version>` is the version of `@jr2/orchestrator` in your
+`package.json`.
+
+A composed Machine is a part of the run of its parent:
+
+- The run has one run id and one snapshot. A child Machine does not start a second run.
+- The [Gates](../reference/glossary.md#gate) of the child show in the run of the parent. Its
+  [Emits](../reference/glossary.md#emit) go to the same feed.
+- Each Machine keeps its own Vocabulary. The `approve` of a child is not an event of its parent, and the parent does not
+  declare it again.
+- The parent gets to the child by `import`. It does not use the Workflow name that [`jr2 run`](../reference/cli.md#run)
+  uses.
+- Only the root Machine of a run gets `instanceId`
+  ([`HostInjectedInput`](../reference/authoring-surface/type-hostinjectedinput.md)) beside the run input. A child gets
+  only the input that its parent gives it. Thus the example gives each `task` a `branch`.
+
+### Composing a Workflow
+
+**The Workflow route, and the Machines that it composes**
+
+- **route**: the Machine that workflows/route.ts registers as the Workflow route
+  - **triager** (Agent): picks deep or quick
+  - **deep** (Machine): thinking high
+  - **quick** (Machine): thinking low
+- ↓ deep → coding: customize() · quick → coding: customize()
+- **coding**: binds the Open parts of task
+  - **Repo Slot target**: your app
+  - **coder model**: the model of the tab
+- ↓ coding is a customize() of task
+- **task**: from @jr2/machines
+  - **coder** (Agent): edits and commits
+  - **Repo Slots**: Open
+  - **coder model**: Open
+
+The file `workflows/route.ts` registers the Machine `route` as the Workflow `route`. The Machine declares three slots of
+its own: the Agent `triager` and the two Machines `deep` and `quick`. Each of the two is a `customize()` of `coding`,
+and `coding` is a `customize()` of `task`. `task` leaves its Repo Slots and the model of its coder Open. `coding` binds
+them, so `deep` and `quick` have them too.
+
+## customize()
+
+[`customize(machine, parts)`](../reference/authoring-surface/customize.md) gives a new Machine with the parts changed.
+The Machine that you give it does not change. Thus two calls on one import give two Machines, as `deep` and `quick`
+show.
+
+[`Customize`](../reference/authoring-surface/type-customize.md) gives the parts that you can change:
+
+| Key         | What it changes                                                                       |
+| ----------- | ------------------------------------------------------------------------------------- |
+| `agents`    | The definition of an Agent, by slot, field by field. `{ model }` keeps the rest.      |
+| `effects`   | The Open url, argv or secret of an Effect, by slot.                                   |
+| `actors`    | A Machine that this Machine composes, by slot. The value has the same keys, one down. |
+| `repos`     | The Repo Slots of the [`workspace()`](../reference/authoring-surface/workspace.md).   |
+| `image`     | The Sandbox Image of the `workspace()`.                                               |
+| `user`      | The [User Container](../reference/glossary.md#user-container) of the `workspace()`.   |
+| `resources` | The Size of the `workspace()`, field by field.                                        |
+
+The type comes from the Machine. It offers only the Agents, Effects, Machines and Repo Slots that the Machine declares.
+A slot that the Machine does not have does not compile.
+
+`workspace()` and [`pool()`](../reference/authoring-surface/pool.md) wrap a Machine. `customize()` goes through each
+wrapper to the Machine inside it. Thus `customize(task, { agents })` changes the Agents of the Machine in the
+`workspace()` of `task`, and you do not name the wrapper's own slot. `repos`, `image`, `user` and `resources` go down to
+the first `workspace()` on that path.
+
+## Open parts
+
+A Machine marks a part Open with [`open`](../reference/authoring-surface/open.md). These parts can be Open:
+
+- a Repo Slot with no url, or the whole Repo Slot map (`repos: open`)
+- the model of an Agent (`agent({ model: open, … })`)
+- the url of an `http` Effect, the argv of a `command`, or the name of the secret of an Effect (`secret(open)`)
+
+An Open part has no default. You bind it with `customize()`. Each Open part has two checks:
+
+- `jr2 up` reads every registered Machine. It refuses an Open part that nobody bound, and it prints the `customize()`
+  line that binds it.
+- At run time, the part refuses too. An Agent does not start a [Turn](../reference/glossary.md#turn) with an Open model.
+  An Effect does not run while it is Open.
+
+[Bind a shipped Machine's Open parts](../guides/bind-open-parts.md) shows each binding.
+
+## @jr2/machines
+
+`@jr2/machines` is the package of Machines that the kit ships. It ships Machines and never Workflows. A Machine becomes
+a Workflow only when a file in your `workflows/` folder exports it.
+
+It ships `task`: a coder Agent works on one prompt in a [Workspace](../reference/glossary.md#workspace), and a person
+approves the work at the `review` Gate. `task` leaves two parts Open: the whole Repo Slot map and the model of `coder`.
+The first Repo Slot that you name is the Repo that the coder works in. The coder can read the other Repos. It also ships
+[`body`](../reference/machines.md#body), the Machine inside `task`, for a `workspace()` of your own.
+
+The version of `@jr2/machines` is the Kit version. It names `@jr2/orchestrator` at that exact version as a peer
+dependency.
+
+## A Machine as an npm package
+
+A package exports a Machine and nothing more. The run input, the Vocabulary, the Agents, the Effects, the Sandbox Image
+and the Repo Slots are all on the Machine. A Workflow uses an imported Machine in one of three ways:
+
+- as it is, when it leaves no part Open: `export const machine = imported;`
+- changed: `export const machine = customize(task, { … });`
+- composed in a Machine of your own, as in the example above
+
+`task` cannot be used as it is, because it leaves two parts Open.
+
+A file in `workflows/` uses the same code. A package has no API of its own.
+
+A Machine package names `@jr2/orchestrator`, `xstate` and `zod` as peer dependencies, never as dependencies. jr2 keeps
+the parts of a Machine in the one copy of `@jr2/orchestrator` and of `xstate` that the Instance loads. A Machine made
+with a second copy of either has empty Menus and Gates that accept nothing. `jr2 up` shows no error for it, and prints
+no `seats:` line for it. Its run stops with the status `error` when an Agent or a Gate of the Machine starts.
+`@jr2/machines` has this shape, and your package copies it.
+
+A package can ship a docker context for its Sandbox Image. The Machine names the folder with
+`import.meta.resolve("./image")`, and `jr2 up` builds it.
+
+## Rules
+
+- A nested Machine is a child in the same run. jr2 has no second run for a child, and no invoke by Workflow name.
+- An [`agent()`](../reference/authoring-surface/agent.md), an Effect or a `workspace()` is a key of `actors`. jr2
+  refuses one that a state writes in its `invoke.src`.
+  [`jr2Setup()`](../reference/authoring-surface/jr2setup.md)`.createMachine` refuses it, and `jr2 up` refuses it too.
+- `customize()` changes only the parts that a Machine declares. You cannot add a part. A Machine that needs one more
+  Agent is a new Machine.
+- For a part that the Machine does not declare, the compiler refuses the key, and `customize()` refuses it at run time.
+  `image`, `user` and `resources` compile on every Machine. `customize()` refuses them when the Machine composes no
+  `workspace()`.
+- `jr2 up` refuses a registered Machine that leaves a part Open, and it names the Workflow and the part.
+- `jr2 up` also refuses an Open part on a Machine that a state writes in its `invoke.src`, because no `customize()` can
+  get to it. Put that Machine under `actors`.
+- A Repo Slot map that is Open takes the slots that you name. Name one slot or more. Their order means what the Machine
+  says it means.
+- An Effect's Open part is bound one time, to a value. A run does not choose it, and a second `customize()` cannot
+  change it.
+- A file in `workflows/` that a different Workflow imports is also a Workflow. Give a Machine that is only for
+  composition a file name that starts with `_`, or keep it outside `workflows/`.
+- `task` inside a different Machine needs `branch` in its input. Without it, `task` refuses to start.
+
+## Read next
+
+- [Bind a shipped Machine's Open parts](../guides/bind-open-parts.md)
+- [Publish a Machine as an npm package](../guides/publish-a-machine-as-an-npm-package.md)
+- [Machines and Workflows](machines-and-workflows.md)
+- [Workspaces](workspaces.md)
+- [Pools and Sources](pools-and-sources.md)
+- Reference: [`customize()`](../reference/authoring-surface/customize.md),
+  [`Customize`](../reference/authoring-surface/type-customize.md), [`open`](../reference/authoring-surface/open.md),
+  [`@jr2/machines`](../reference/machines.md), [`jr2 up`](../reference/cli.md#up)
+- [ADR-0049](../reference/decisions/0049-a-machine-carries-its-parts-and-composes-by-invoke.md): a Machine carries its
+  parts and composes by invoke
+- [ADR-0051](../reference/decisions/0051-a-repo-is-a-slot-on-the-workspace-and-a-cache-on-the-node.md): a Repo is a slot
+  on the Workspace
+- [ADR-0054](../reference/decisions/0054-the-kit-ships-machines-and-a-shipped-machine-leaves-its-parts-open.md): the kit
+  ships Machines, and a shipped Machine leaves its parts Open

package/docs/concepts/converge.md

@@ -0,0 +1,257 @@
+---
+title: Converge
+description: What jr2 up makes in the cluster from your Instance folder, and the Assembly that it publishes.
+---
+
+# Converge
+
+To converge is to make a cluster agree with your [Instance](../reference/glossary.md#instance) folder. One command does
+it: [`jr2 up`](../reference/cli.md#up). It reads the folder, builds the images that the folder needs, and applies the
+objects to the cluster of your current kubectl context. Then it publishes your Workflows to the
+[Orchestrator](../reference/glossary.md#orchestrator) as an [Assembly](../reference/glossary.md#assembly). You can run
+it again at any time. When nothing changed, it changes nothing.
+
+## Why one command
+
+A [Workflow](../reference/glossary.md#workflow) needs many parts in the cluster: the Orchestrator, its Secret, its
+images and the operator. Some Workflows also need a [Sandbox Image](../reference/glossary.md#sandbox-image) or the
+[Instance Harness](../reference/glossary.md#instance-harness). If you put each part there by hand, you must remember the
+steps and their order. When you forget a step, the cluster is not correct, and you find the problem only when a run
+fails. `jr2 up` does every step, in the correct order, each time. It tells you what it does at each step.
+
+The Instance folder holds no record of a cluster. The kubectl context is the address, and the namespace is the identity.
+Thus the same folder converges into kind on your computer and into a shared cluster. Only the kubectl context changes,
+and, for a cluster that is not kind, the value that [`registry`](../reference/config.md#registry) reads from `.env`.
+
+## Setup and usage
+
+The diagram shows what `jr2 up` makes, and what [`jr2 run`](../reference/cli.md#run) and
+[`jr2 send`](../reference/cli.md#send) use after it.
+
+**What jr2 up makes, and what jr2 run and jr2 send use**
+
+- **You**: the Instance folder, on your computer
+  - **jr2 up**: converges the cluster
+  - **jr2 run, jr2 send**: use what jr2 up made
+- ↓ jr2 up → the cluster: applies, then publishes · ↓ jr2 run, jr2 send → Orchestrator: read the token, then call
+- **the cluster**: of the current kubectl context
+  - **Instance**: in the namespace of the Instance
+    - **Orchestrator**: loads your Workflows
+      - **Assembly**: your Workflows and your config
+    - **jr2-instance Secret**: holds the Instance token
+    - **Instance Harness**: when an Agent is Menu-only
+    - **Instance Effector**: when an Effect runs there
+    - **Repo cache**: when a Machine has a Sandbox
+  - ↓ the Orchestrator asks for each Sandbox · ↑ the operator makes its pod
+  - **jr2-system**: one for each cluster
+    - **operator**: makes each Sandbox pod
+  - **images**: that the pods run
+    - **Kit images**: jr2 up pulls them
+    - **Pinned image**: the Envoy of the Custodian
+    - **Sandbox Images**: jr2 up builds them
+
+`jr2 up` reads the Instance folder. It applies the objects, and then it publishes the Assembly to the Orchestrator,
+which loads it. `jr2 run` and `jr2 send` do not apply objects to the cluster. They read the Instance token from the
+`jr2-instance` Secret. Then they open a port forward to the Orchestrator for the time of the command. The Orchestrator
+starts the run, and it makes each [Sandbox](../reference/glossary.md#sandbox) that the run needs. For all the parts of
+the cluster, see [Architecture](architecture.md).
+
+## What jr2 up does
+
+`jr2 up` does its steps in this order. Steps 1 to 4 change nothing in the cluster.
+[`jr2 check`](../reference/cli.md#check) does steps 2 and 3 alone, with the same code and no cluster:
+
+1. It writes the docs index of the [Kit version](../reference/glossary.md#kit-version) between the two `jr2-docs`
+   markers in `AGENTS.md`. This step changes the folder, not the cluster. Thus a converge that fails still leaves the
+   index correct.
+2. It typechecks the Instance with the Instance's own TypeScript compiler.
+3. It loads each Workflow in `workflows/`. It reads the parts that each [Machine](../reference/glossary.md#machine)
+   carries: its [Agents](../reference/glossary.md#agent), its [Repos](../reference/glossary.md#repo), its Sandbox Images
+   and its [Effects](../reference/glossary.md#effect). It also checks each [Chart](../reference/glossary.md#chart) file.
+4. It makes the Assembly from the folder, and calculates its hash. See [The Assembly](#the-assembly).
+5. It checks the Kubernetes version of the cluster.
+6. It checks that the namespace is this Instance's. Before it uses a namespace for the first time, it asks you.
+7. It checks that the cluster keeps pod-level resources.
+8. It finds the platforms of the nodes, and it decides the address of each image.
+9. It builds the Sandbox Images.
+10. It makes the values of the Secrets, and checks each Secret that the config names but that `jr2 up` does not write.
+11. It checks each model that an Agent uses: a pod in the cluster asks the provider for one tool call for each model.
+    Until each check passes, `jr2 up` writes nothing that the Instance or the operator reads. The pod has up to 5
+    minutes to start, and each model has up to 6 minutes. `jr2 up` writes each model's result as it comes. With
+    `--skip-provider-preflight`, no pod checks the models, and `jr2 up` writes a warning that names each model that it
+    did not check.
+12. It applies the operator. For a Repo with an ssh url, it asks where the deploy key comes from.
+13. It applies the Secrets and the Orchestrator, and waits for the rollout. When the Machines need them, it also waits
+    for the Repo cache, the Instance Harness and the [Instance Effector](../reference/glossary.md#instance-effector).
+    The Repo cache agent on each Sandbox node checks that the kernel of its node has Landlock, which jr2 needs. While a
+    Sandbox node has no Landlock, the converge fails. The error names each such node, the reason, and the fix: keep the
+    node out with `sandbox.nodeSelector` or a taint, or enable Landlock in its kernel. Then run `jr2 up` again.
+14. It publishes the Assembly to the Orchestrator. When the Orchestrator already has this Assembly, it publishes
+    nothing.
+15. It removes the images that nothing uses now.
+
+`jr2 up` says `converged` only when each pod that it rolled out runs the image that it expected. The labels and the
+records that `jr2 up` writes help it to skip work. They do not prove that the cluster is correct. The pods do.
+
+The Machines decide some parts. When no registered Machine makes a Sandbox, `jr2 up` builds no Sandbox Image and runs no
+Repo cache. When no Agent has `workspace: "none"`, there is no Instance Harness. When the Machines stop using the Repo
+cache or the Instance Harness, `jr2 up` removes it from the namespace. The image sweep removes a Sandbox Image that
+nothing names.
+
+## The images
+
+Each image that a converge uses is one of these kinds:
+
+| Image                                                 | Who owns it | What `jr2 up` does                                                                                                                                                                   |
+| ----------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Kit image](../reference/glossary.md#kit-image)       | jr2         | It builds nothing. The cluster pulls `jr2-orchestrator`, `jr2-harness` and `jr2-operator` at the tag of the Kit version.                                                             |
+| [Pinned image](../reference/glossary.md#pinned-image) | Upstream    | It builds nothing. The cluster pulls the Envoy image of the [Custodian](../reference/glossary.md#custodian), by its tag and its digest.                                              |
+| Sandbox Image, from a `file:` URL                     | You         | It builds the folder that a [`workspace()`](../reference/authoring-surface/workspace.md) names, and the `images/default/` folder that [`jr2 init`](../reference/cli.md#init) writes. |
+| Sandbox Image, from a registry                        | You         | It builds nothing. The cluster pulls the image.                                                                                                                                      |
+
+The Custodian is a container in each [Harness](../reference/glossary.md#harness) pod.
+[Workspaces](workspaces.md#the-sandbox-image) explains what a Sandbox Image holds.
+
+The tag of each image that `jr2 up` builds is a hash of the inputs of that image and of its platforms. Thus a new tag
+means new content, and the same tag means the same content. This rule has three results:
+
+- When the inputs of an image do not change, `jr2 up` does not build it again. A converge with no change builds no
+  image.
+- When an input changes, the tag changes. A Sandbox that starts after the converge uses the new image. A Sandbox that
+  runs does not, as the text below explains.
+- `--force` builds each image again, even when its tag did not change.
+
+The Kit images are at `ghcr.io/snapwich` by default. A cluster that cannot pull from there pulls from a mirror. A mirror
+holds the same tags. [`kitRegistry`](../reference/config.md#kitregistry) names the mirror, and
+[`jr2 kit push`](../reference/cli.md#kit-push) fills it. `jr2 up` never pushes to `kitRegistry`. `kitRegistry` also
+changes where the cluster pulls the Pinned image, and `jr2 kit push` copies it to the mirror too.
+
+`jr2 up` sends each image that it builds to the nodes in one of two ways:
+
+- When you set `registry`, it pushes the image to that registry, and the nodes pull it.
+- When you do not set `registry`, on a kind cluster it loads the image into the nodes with `kind load`. A context whose
+  name starts with `kind-` is a kind cluster.
+
+A change to a Sandbox Image changes only the Sandboxes that start after the converge. A Sandbox that runs keeps its
+image, because a new pod would lose its [Worktrees](../reference/glossary.md#worktree) and the commits that you did not
+push. `jr2 up` tells you how many running [Workspaces](../reference/glossary.md#workspace) keep each older image.
+
+`jr2 up` uses Docker only to build a Sandbox Image. When no registered Machine makes a Sandbox, it builds no image, and
+your computer does not need Docker for `jr2 up`.
+
+## The Assembly
+
+The Assembly is what the Orchestrator loads from your Instance folder: the Workflows in `workflows/`, `jr2.config.ts`,
+the folders of the `file:` Sandbox Images, and the packages that they import. The image of the Orchestrator is a Kit
+image, the same for each Instance. Your code is not in it. `jr2 up` makes the Assembly and publishes it to the
+Orchestrator that runs.
+
+- **No restart.** The Orchestrator loads a new Assembly in its process. A change to a Machine or to `jr2.config.ts`
+  starts no pod again. Thus a port forward to the [Console](../reference/glossary.md#console) stays open.
+- **The Kit packages come from the image.** `jr2 up` removes `@jr2/orchestrator` and each package that it needs, such as
+  `xstate` and `zod`, from the Assembly. The Orchestrator uses its own copies. A second copy of one of these packages
+  makes Machines whose Menus are empty, so `jr2 up` refuses it.
+- **One hash for each Assembly.** The hash comes from the files and the paths of the Assembly. When the Orchestrator
+  already has the Assembly with this hash, `jr2 up` does not publish it again.
+- **The Orchestrator checks it again.** Before it makes an Assembly current, the Orchestrator loads each Workflow and
+  does the same checks as `jr2 up`. When it refuses the Assembly, the Assembly that was current stays current.
+- **A run keeps its Assembly.** A new run starts under the current Assembly. A live run keeps the Assembly that it
+  started under, also after a restart. Thus a publish does not stop a run that waits at a
+  [Gate](../reference/glossary.md#gate). `jr2 run`, `jr2 runs` and the Console use the current Assembly. The
+  Orchestrator removes an older Assembly when no live run holds it.
+- **Only `jr2 up` publishes.** The publish needs the publish token, which is in the `jr2-instance` Secret. `jr2 up`
+  reads it through the kubectl context. The Instance token does not publish, and an Agent cannot publish code.
+
+[`jr2 status`](../reference/cli.md#status), with no run id, shows the current Assembly and each Assembly that a live run
+holds.
+
+## Kit version and Handoff
+
+An Instance has one Kit version: the version of the `@jr2/orchestrator` package that the Instance pins. It is the tag of
+each Kit image, the image of the Orchestrator too. `jr2 init` pins `@jr2/orchestrator` and `@jr2/cli` to one exact
+version in `package.json`. The Assembly records the Kit version, and the Orchestrator refuses an Assembly for a
+different Kit version. When you change the Kit version, one `jr2 up` starts the Orchestrator on its new image first, and
+then it publishes the Assembly for the new version.
+
+You install the [jr2 CLI](../reference/glossary.md#jr2-cli) two times: one time with `npm i -g`, and one time in the
+Instance, from its `package.json`. In an Instance folder, the global `jr2` runs the Instance's own `@jr2/cli`, with the
+same arguments. This is the [Handoff](../reference/glossary.md#handoff). Thus the CLI that runs is always the one that
+the Instance pins. In the Instance, the version of your global `jr2` does not matter.
+[`jr2 version`](../reference/cli.md#version) shows the CLI that runs, the global CLI that handed off, the Kit version of
+the Instance, and what the cluster runs.
+
+All the Instances on a cluster share one operator. `jr2 up` upgrades an older operator. It does not downgrade an
+operator that a different Instance upgraded to a later version.
+
+## Clean up
+
+When each tag is a content hash, each change makes a new image. Ten changes to a Dockerfile make ten images. Thus
+`jr2 up` removes the old images at the end of each converge that succeeds.
+
+An image is garbage when no live root in the cluster names it. The roots are the image map of each Instance on the
+cluster, the image of each Sandbox, and the images of the pods that run. jr2 removes only an image that it built and
+labeled. It removes the image from your computer and, on a kind cluster, from the nodes. It never removes an image that
+it did not build, such as the Pinned image. The output gives the size that it removed:
+`swept <count> image(s) (<size>)`.
+
+`jr2 up` and [`jr2 down`](../reference/cli.md#down) remove the images. [`jr2 gc`](../reference/cli.md#gc) does the same
+work at a different time, for example when your disk is full. It also removes each Repo resource that no Machine binds
+and that no run used in the last 7 days, by default. `--repo-ttl` changes the time. `jr2 gc --dry-run` shows what it
+would remove, and removes nothing.
+
+`jr2 down` deletes the namespace of the Instance. The runs, the store of the runs and the Sandboxes go with it.
+`jr2 down --all` also removes the operator.
+
+## Rules
+
+- `jr2 up` changes nothing in the cluster when the Instance does not typecheck.
+- `jr2 up` changes nothing in the cluster when the Assembly holds a second copy of a Kit package, or when its Kit
+  version is not the Kit version of the CLI.
+- `jr2 up` changes nothing in the cluster when a registered Machine has an [Open](../reference/glossary.md#open) part
+  that is not bound. Examples are a [Repo Slot](../reference/glossary.md#repo-slot) with no url and an Agent with no
+  model.
+- `jr2 up` refuses a cluster that runs a Kubernetes version earlier than 1.35. It also refuses a cluster that does not
+  keep pod-level resources.
+- `jr2 up` refuses a namespace that belongs to a different Instance. It asks you before it uses a namespace for the
+  first time. `--yes` gives the answer for CI.
+- `jr2 up` refuses a cluster that is not kind when `registry` is not set.
+- Each verb that reads the Instance, other than `jr2 version`, refuses when the Instance and the CLI do not use the same
+  copy of `@jr2/orchestrator`.
+- `jr2 up` never downgrades the operator.
+- `jr2 up` never replaces the pod of a Sandbox that runs.
+- The Orchestrator refuses an Assembly that fails its checks, and the Assembly that was current stays current.
+- Only the publish token publishes an Assembly.
+- A converge that fails removes no image.
+- `jr2 gc`, `jr2 up` and `jr2 down` remove only images that jr2 built and that no live root names.
+
+[Fix a failed converge](../guides/fix-a-failed-converge.md) gives the refusal text of each rule, and the fix.
+
+## Read next
+
+- [Iterate on a Machine on kind](../guides/iterate-on-a-machine-on-kind.md)
+- [Move from kind to a shared cluster](../guides/move-from-kind-to-a-shared-cluster.md)
+- [Mirror the Kit images](../guides/mirror-the-kit-images.md)
+- [Upgrade the Kit version](../guides/upgrade-the-kit-version.md)
+- [Clean up](../guides/clean-up.md)
+- [Fix a failed converge](../guides/fix-a-failed-converge.md)
+- Reference: [`jr2 up`](../reference/cli.md#up), [`jr2 down`](../reference/cli.md#down),
+  [`jr2 gc`](../reference/cli.md#gc), [`jr2 kit push`](../reference/cli.md#kit-push),
+  [`jr2 version`](../reference/cli.md#version), [`registry`](../reference/config.md#registry),
+  [`kitRegistry`](../reference/config.md#kitregistry) and [`platforms`](../reference/config.md#platforms)
+- [ADR-0019](../reference/decisions/0019-one-converging-command-against-the-current-context.md): one converging command
+  against the current context
+- [ADR-0038](../reference/decisions/0038-jr2-up-builds-every-image-it-deploys.md): `jr2 up` builds each image that the
+  Instance runs
+- [ADR-0039](../reference/decisions/0039-image-garbage-collects-by-reachability.md): `jr2 gc` removes the images that
+  nothing reaches
+- [ADR-0041](../reference/decisions/0041-a-build-the-host-already-holds-is-not-spent-again.md): a build that the
+  computer already holds is not done again
+- [ADR-0044](../reference/decisions/0044-kit-images-live-at-a-canonical-home-a-self-host-mirrors-it.md): the Kit images
+  and their mirror
+- [ADR-0045](../reference/decisions/0045-the-platform-joins-the-image-address-and-the-cluster-chooses-it.md): the
+  platform is a part of the image tag
+- [ADR-0046](../reference/decisions/0046-a-converge-failure-carries-its-diagnosis.md): a failed converge says why
+- [ADR-0056](../reference/decisions/0056-a-global-jr2-hands-off-to-the-instances-own-and-an-instance-has-one-kit-version.md):
+  the Handoff, and one Kit version for each Instance
+- [ADR-0069](../reference/decisions/0069-the-orchestrator-is-a-kit-image-and-an-instance-publishes-its-assembly.md): the
+  Orchestrator is a Kit image, and an Instance publishes its Assembly