@microck/raft 0.5.0 → 0.7.0

package/docs/guides/meta.json

@@ -3,16 +3,21 @@
   "collapsible": true,
   "defaultOpen": false,
   "pages": [
+    "index",
+    "---Develop---",
     "project-setup",
     "docker",
     "files",
+    "desktop-services",
+    "---Automate---",
     "background-jobs",
     "long-running-services",
     "scripting-ci",
-    "config-policy",
-    "desktop-services",
+    "ci-jobs",
+    "---Operate---",
     "snapshots-forks",
     "backup-recovery",
+    "config-policy",
     "upgrades",
     "troubleshooting"
   ]

package/docs/guides/project-setup.mdx

@@ -15,7 +15,7 @@ service. Commands run as guest root in `/workspace` unless you choose another us
 Create a persistent box after [host setup](../operations.mdx):
 
 ```sh title="CONTROLLER: Create a project box"
-box=$(raft new --location lab --ttl 3600)
+box=$(raft new --location lab --ttl 3600 --persistent)
 ```
 
 Upload a local project, excluding credentials and files you do not want copied.

package/docs/guides/scripting-ci.mdx

@@ -11,15 +11,34 @@ authentication, and hosts with passwordless sudo. No Raft HTTP API, SDK, or API
 exists. Give access only to trusted jobs: the configured SSH account has host sudo
 and controls all boxes on that host.
 
+For one-shot builds, [`raft run`](./ci-jobs.mdx) combines allocation, source upload,
+foreground execution, artifact collection and disposable cleanup. It is an
+orchestration command, not a registered CI runner. The manual lifecycle examples
+below remain useful for persistent debugging workflows.
+
 ## Output formats
 
-Raft does not have a global `--json` option. Parse each command's actual format:
+The development CLI supports `raft --json COMMAND ...` for JSON Lines output.
+Each event has a `type`: `data` carries a structured `value`; `stdout` and
+`stderr` carry base64-encoded bytes in `data`; `error` carries `code` and
+`message`; the final `exit` carries the process exit `code`. Decode stream events
+in order within each channel. Chunks need not end at line boundaries. This keeps
+binary output intact and streams long-running command output without buffering
+it all. Interactive `ssh`, `forward` and `desktop` reject JSON mode before acting.
+Help/version work without configuration. JSON mode suppresses release notices.
+
+```sh
+raft --json list --location lab | jq 'select(.type == "data") | .value'
+raft --json exec "$BOX" -- sh -c 'echo hello; exit 7'
+```
+
+Without global `--json`, parse each command's format:
 
 | Command | stdout |
 | --- | --- |
 | `new`, `fork`, `recover` | One location-qualified handle |
 | `exec --detach` | One `rfcmd-` job ID |
-| `list` | JSONL: one object per box, with `box`, `state`, `stopAt`, `disk`, `note` |
+| `list` | JSONL: one object per box, with `box`, `state`, `stopAt`, `deleteAt`, `disk`, `note` |
 | `info` | One pretty-printed native Incus metadata JSON object |
 | `usage` | One JSON object containing running resource counters |
 | `capacity --json` | One JSON object per location (JSONL across multiple hosts) |
@@ -27,13 +46,15 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | `config` | One pretty-printed JSON object with `file`, `defaults`, `policy` |
 | `config set/unset`, `policy` | One line describing the change |
 | `prune` | JSONL candidates or deleted records with `box`, `action` |
-| `status` | systemd `ActiveState`, `SubState`, `ExecMainStatus` property lines |
-| `logs` | Guest journal text |
-| `exec` | Payload stdout/stderr |
+| `status` | Retained JSON record with `state`, `exitCode`, timestamps and `droppedBytes` |
+| `logs` | First 1 MiB of retained combined output |
+| `exec`, `run` | Payload stdout/stderr; `run` lifecycle diagnostics use stderr |
 | Other inspection/maintenance commands | Human-readable text or no output |
 
 `list` emits nothing when there are no boxes. `stopAt` is the host Unix deadline
-as a string, or an empty string when absent. `disk` is `"shared"` or the box's
+as a string, or an empty string when absent. `deleteAt` is the Unix time the
+location's retention policy deletes a stopped box, in the same form, or an empty
+string. `disk` is `"shared"` or the box's
 own disk size, such as `"20GiB"`. `note` is the box note object with
 `purpose` and optional `owner` and `next`, or `null`. `info` uses native Incus keys rather
 than a normalized Raft schema. `usage` includes `memoryBytes`, `memoryLimit`,
@@ -52,10 +73,11 @@ raft prune --location lab --older-than 7 | jq -r '.box'
 
 `raft new` fills omitted options from the controller's
 `~/.config/raft/config.json`, so the same script can create different boxes on
-different controllers. Pass `--location`, `--ttl`, `--cpu`, `--memory` and
-`--disk` in CI.
+different controllers. Pass `--location`, `--ttl`, `--cpu`, `--memory`,
+`--disk` and `--disposable` or `--persistent` in CI.
 Hosts can also require box note fields; give `--purpose`, `--owner` and `--next`
-so a policy cannot fail the job. See [Defaults and note policies](./config-policy.mdx).
+so a policy cannot fail the job. A host retention policy can delete a box left
+stopped between jobs; see [Defaults and host policies](./config-policy.mdx).
 
 Do not redirect `2>&1` into machine-readable output. Recovery reports its allocated
 handle on stderr before import finishes; only a successful completion prints the
@@ -76,10 +98,10 @@ stderr.
 
 SSH transport failures may return SSH's status rather than the payload's result.
 The foreground tunnel replaces the CLI process with SSH and uses SSH's exit code.
-A zero exit from `status` means the query succeeded; read `ExecMainStatus` for the
-job result and `ActiveState`/`SubState` for whether it finished. Do not interpret a
-running job's initial `ExecMainStatus=0` as completion. See
-[Background jobs](./background-jobs.mdx).
+A zero exit from `status` means the query succeeded. Wait for a terminal `state`
+and read `exitCode`; running, cancelled and interrupted jobs have no confirmed
+payload exit code. Results remain readable after stop or deletion for seven days.
+See [Background jobs](./background-jobs.mdx).
 
 ## Create, wait, run, and stop
 
@@ -105,7 +127,7 @@ cleanup() {
 }
 trap cleanup EXIT
 
-box=$(raft new --location lab --ttl 3600)
+box=$(raft new --location lab --ttl 3600 --persistent)
 printf 'Created %s\n' "$box" >&2
 ready=false
 for attempt in {1..30}; do

package/docs/guides/snapshots-forks.mdx

@@ -9,7 +9,8 @@ Raft captures filesystem snapshots, rolls back changes, and clones workspaces on
 
 ## Target workspace handle
 
-Commands in this guide require a stopped workspace:
+Use a **persistent** workspace and stop it first. Stopping a disposable box deletes
+it and its snapshots; do not use one as the source for this walkthrough.
 
 ```sh title="CONTROLLER: Select and stop target workspace"
 raft list
@@ -66,6 +67,7 @@ raft resume "$box" --ttl 600
 Forking creates an independent clone on the same host:
 
 ```sh title="CONTROLLER: Fork workspace into a new clone"
+raft stop "$box"  # Use a persistent box; stop deletes disposable boxes
 copy=$(raft fork "$box" --ttl 600)
 echo "Created fork: $copy"
 ```
@@ -110,4 +112,4 @@ copy=$(raft fork "$box" --ttl 600 --cpu 2 --memory 4GiB)
 raft resume "$box" --ttl 600 --memory 2GiB
 ```
 
-Omitted CPU and RAM values keep the source limits; the disk never changes on fork or resume. Forks are persistent by default; add `--disposable` to delete a clone when it stops or expires.
+Omitted CPU and RAM values keep the source limits; the disk never changes on fork or resume. Forks are persistent by default, even when `raft config` sets `disposable true`; add `--disposable` to delete a clone when it stops or expires.

package/docs/guides/troubleshooting.mdx

@@ -33,8 +33,8 @@ raft doctor
 
 An active expiration timer can still run an older worker. Installing or updating
 the controller CLI does not deploy host code. `doctor` checks the same worker
-protocol as disposable creation and retention cleanup, without running expiry or
-changing any boxes. It exits nonzero and names the location on a mismatch.
+protocol as disposable creation, prune and setting a retention policy, without
+running expiry or changing any boxes. It exits nonzero and names the location on a mismatch.
 
 Review the host deployment changes, then deploy from the checkout matching your
 CLI. Replace `lab` with the location reported by the diagnostic:
@@ -106,6 +106,23 @@ files and snapshots. Expired disposable containers are deleted, including their
 snapshots. Use `raft gc --location lab` to check only one host. The timer normally
 checks every 15 seconds; host outages, graceful shutdown and long locked
 operations can delay expiry. See [Lifetime and persistent services](./long-running-services.mdx).
+`raft gc` also applies the location's stopped-box retention.
+
+### A stopped box disappeared
+
+A host retention policy deletes boxes left stopped for its hours. Check the
+policy and the host journal, which records every deletion:
+
+```sh title="CONTROLLER: Check retention"
+raft config | jq '.policy'
+```
+
+```sh title="HOST: Find the deletion"
+sudo journalctl -t raft | grep 'Deleted box'
+```
+
+Deleted boxes cannot be recovered except from a `raft backup` archive. See
+[Defaults and host policies](./config-policy.mdx#delete-boxes-left-stopped).
 
 ## Common error scenarios
 

package/docs/guides/upgrades.mdx

@@ -17,7 +17,7 @@ parts of Raft. Updating one does not automatically update the others.
 ## Choose a release and prepare
 
 Review [release notes](https://github.com/Microck/raft/releases) and use matching
-CLI and deployment sources. The examples below pin `v0.2.0`; replace that version
+CLI and deployment sources. The examples below pin `v0.6.0`; replace that version
 consistently when adopting another release.
 
 ```sh title="CONTROLLER: Inspect the current installation"
@@ -34,7 +34,7 @@ stopping one. Schedule redeployment when interruptions are acceptable.
 ## Update the controller
 
 `raft self-update` installs the latest release through the channel that
-installed the CLI, and `raft self-update --version 0.2.0` installs a chosen
+installed the CLI, and `raft self-update --version 0.6.0` installs a chosen
 one. `raft self-update --check` only reports. For npm installs, npm checks the
 registry integrity hash of a package published with provenance. For uv tools,
 Raft downloads the release wheel and refuses it unless its SHA-256 matches the
@@ -43,7 +43,7 @@ release `SHA256SUMS`. See [`self-update`](../reference/cli.md#self-update).
 To install a release by hand instead, for an npm installation:
 
 ```sh title="CONTROLLER: Install a pinned CLI release"
-npm install -g @microck/raft@0.2.0
+npm install -g @microck/raft@0.6.0
 raft --version
 ```
 
@@ -52,7 +52,7 @@ release, verify the checksum, then install it with `uv`:
 
 ```sh title="CONTROLLER: Install a verified release wheel instead of npm"
 sha256sum --ignore-missing -c SHA256SUMS
-uv tool install --force ./raft-0.2.0-py3-none-any.whl
+uv tool install --force ./raft-0.6.0-py3-none-any.whl
 raft --version
 ```
 
@@ -71,8 +71,8 @@ reports each host whose worker differs from the new CLI.
 Obtain a separate checkout of the matching release:
 
 ```sh title="CONTROLLER: Obtain and deploy matching host code"
-git clone --branch v0.2.0 https://github.com/Microck/raft.git raft-v0.2.0
-cd raft-v0.2.0
+git clone --branch v0.6.0 https://github.com/Microck/raft.git raft-v0.6.0
+cd raft-v0.6.0
 python3 deploy/deploy.py --location lab
 raft doctor
 ```
@@ -84,8 +84,10 @@ timer. It does not import an image or migrate guest files.
 
 Do not bypass a conflicting-resource or storage-size error. Inspect the host and
 preserve backups before explicit recovery; redeployment does not repair arbitrary
-infrastructure drift. Disposable creation/fork and prune check the worker protocol
-and fail if it differs from the CLI. That check is not an automatic upgrade.
+infrastructure drift. Disposable creation/fork, prune and setting a retention
+policy check the worker protocol and fail if it differs from the CLI. That check
+is not an automatic upgrade. Raft 0.6.0 raised the protocol for stopped-box
+retention, so hosts deployed by an earlier release need this redeploy.
 
 ## Replace the image pin
 
@@ -103,7 +105,7 @@ backup's guest filesystem rather than rebuilding it from the new image.
 ## Verify the update
 
 ```sh title="CONTROLLER: Smoke-check a new persistent box"
-box=$(raft new --location lab --ttl 600)
+box=$(raft new --location lab --ttl 600 --persistent)
 raft exec "$box" -- node --version
 raft exec "$box" -- docker info
 raft stop "$box"

package/docs/index.mdx

@@ -1,41 +1,39 @@
 ---
 title: Overview
-description: Persistent Linux workspaces powered by Incus.
+description: Create persistent Linux development boxes on Ubuntu hosts you control.
 ---
 
 # Raft
 
-Raft is an independent, self-hosted open-source alternative to [boat.dev](https://boat.dev).
-It provides persistent Linux workspaces on ARM64 and AMD64 hardware,
-supporting command execution, Docker, file transfer, snapshots, forks, and desktop access.
-Raft is not affiliated with Boat.
+Raft creates **persistent Linux boxes on your own Ubuntu hosts**. Run commands,
+Docker builds and development services; copy files; save snapshots; or open a
+private desktop. A box is an unprivileged Incus container that shares its host's
+kernel, not a virtual machine.
 
-## Getting started
+## Start here
 
-Read [System requirements](./requirements.mdx), follow [Installation and host setup](./operations.mdx), and create your [First working box](./first-box.mdx).
+1. [Check requirements](./requirements.mdx): a Linux controller and a dedicated Ubuntu host.
+2. [Set up a host](./operations.mdx): install the CLI and run guided onboarding.
+3. [Create your first box](./first-box.mdx): run a command, stop it and resume it.
 
-```sh title="CONTROLLER: Create and use a workspace"
-box=$(raft new --location lab --ttl 600)
+Already have a configured host? Run these commands on your **controller**
+(the machine where you installed `raft`). Replace `lab` with your location:
+
+```sh
+box=$(raft new --location lab --ttl 600 --persistent)
 raft exec "$box" -- node --version
 raft ssh "$box"
-raft stop "$box"
 ```
 
-Stopping a workspace preserves files and packages on disk. Resuming resets its running lifetime.
-
-## Task guides
-
-| Task | Guide |
-| :--- | :--- |
-| Prepare a project and reuse its installed dependencies | [Project setup and templates](./guides/project-setup.mdx) |
-| Run nested containers and build images | [Docker in workspaces](./guides/docker.mdx) |
-| Transfer files between controller and workspace | [File transfer](./guides/files.mdx) |
-| Run detached commands with systemd logs | [Background jobs](./guides/background-jobs.mdx) |
-| Manage deadlines and restart services after resume | [Lifetime and persistent services](./guides/long-running-services.mdx) |
-| Automate the CLI and parse its output | [Scripting and CI](./guides/scripting-ci.mdx) |
-| Set defaults for new boxes or require box note fields | [Defaults and note policies](./guides/config-policy.mdx) |
-| Forward guest ports or open noVNC desktop | [Desktop and private services](./guides/desktop-services.mdx) |
-| Capture disk state or clone workspaces | [Snapshots and forks](./guides/snapshots-forks.mdx) |
-| Export portable backups across hosts | [Backup and recovery](./guides/backup-recovery.mdx) |
-| Update the CLI, host worker, and workspace image | [Upgrades and image changes](./guides/upgrades.mdx) |
-| Inspect host services and diagnose errors | [Troubleshooting](./guides/troubleshooting.mdx) |
+Exit the guest shell, then run `raft stop "$box"` on the controller. Files remain;
+processes stop. Host retention policies can later delete stopped boxes.
+
+## Find a task
+
+- [Work with a project](./guides/project-setup.mdx) or [copy files](./guides/files.mdx).
+- [Run Docker](./guides/docker.mdx), [background jobs](./guides/background-jobs.mdx), or [open a desktop](./guides/desktop-services.mdx).
+- [Browse all guides](./guides/index.mdx), [look up a command](./reference/cli.md), or [troubleshoot](./guides/troubleshooting.mdx).
+
+Raft is an independent open-source alternative to Boat, not affiliated with it.
+[Compare the trade-offs](./boat-capabilities.md). Setup examples target published
+**0.6.0**; [0.7.0 features](./releases/0.7.0.md) are marked unreleased.

package/docs/maintainers/index.mdx

@@ -0,0 +1,18 @@
+---
+title: Maintain Raft
+description: Design, verification, release and documentation work for Raft contributors.
+---
+
+# Maintain Raft
+
+These pages are for changing or releasing Raft, not for creating your first box.
+For everyday use, start with [host setup](../operations.mdx) or the [task guides](../guides/index.mdx).
+
+- [Design decisions](../boat-parity-design.md): why Raft uses Incus and host SSH.
+- [Runtime contract](../contract.md): behavior that implementations must preserve.
+- [Verification](../verification.mdx): test commands, evidence and unverified boundaries.
+- [Publishing](../publishing.md): package and image release gates.
+- [Documentation site](../site-development.md): edit, preview and check these docs.
+
+Host tests create and delete real workspaces. Read each suite's effects before
+running it, and use dedicated infrastructure you are authorized to change.

package/docs/maintainers/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Maintainers",
+  "collapsible": true,
+  "defaultOpen": false,
+  "pages": [
+    "index",
+    "[Design decisions](/docs/boat-parity-design/)",
+    "[Verification](/docs/verification/)",
+    "[Publishing](/docs/publishing/)",
+    "[Documentation site](/docs/site-development/)"
+  ]
+}

package/docs/meta.json

@@ -2,20 +2,16 @@
   "title": "Raft",
   "pages": [
     "index",
-    "---Start here---",
+    "---Get started---",
     "requirements",
     "operations",
     "first-box",
+    "---Use Raft---",
     "guides",
     "reference",
-    "contract",
-    "---Comparison---",
+    "---About---",
     "boat-capabilities",
-    "boot-performance",
-    "---Contributing---",
-    "boat-parity-design",
-    "verification",
-    "publishing",
-    "site-development"
+    "maintainers",
+    "releases"
   ]
 }

package/docs/operations.mdx

@@ -7,6 +7,8 @@ description: Install the Raft controller CLI, provision a dedicated host, and ac
 
 Set up a dedicated Ubuntu host, install the Raft CLI, provision Incus, acquire a workspace image, and verify readiness.
 
+Examples pin published **0.6.0**. Use matching CLI, deployment scripts and image assets.
+
 Review prerequisites in [System requirements](./requirements.mdx) before starting.
 
 ## Guided onboarding
@@ -15,7 +17,7 @@ Install the CLI from npm on your Linux controller, confirm key-based SSH to the
 host, then let `raft host add` do the remaining steps:
 
 ```sh title="CONTROLLER: Onboard a host"
-npm install -g @microck/raft@0.5.0
+npm install -g @microck/raft@0.6.0
 ssh ubuntu@192.0.2.10 true
 raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
 raft host add lab --ssh ubuntu@192.0.2.10
@@ -30,6 +32,9 @@ that instead. See [`host add`](./reference/cli.md#host-add) for image options.
 
 ## Manual setup
 
+<details>
+<summary>Advanced: provision each component yourself instead of using host add</summary>
+
 The steps below are what `raft host add` automates. Follow them to inspect or
 customize each stage.
 
@@ -62,7 +67,7 @@ sudo -n true && echo "Passwordless sudo is functional"
 On your Linux controller with Python 3.11.8+, install the published CLI:
 
 ```sh title="CONTROLLER: Install published CLI"
-npm install -g @microck/raft@0.5.0
+npm install -g @microck/raft@0.6.0
 raft --version
 ```
 
@@ -70,7 +75,7 @@ Installation does not configure hosts or download images. Clone the matching
 release to obtain the deployment scripts and example configuration:
 
 ```sh title="CONTROLLER: Obtain deployment scripts"
-git clone --branch v0.5.0 https://github.com/Microck/raft.git raft
+git clone --branch v0.6.0 https://github.com/Microck/raft.git raft
 cd raft
 ```
 
@@ -161,16 +166,16 @@ Workspaces require an unprivileged Debian 13 development image matching the host
 
 <Tab value="Download release image">
 
-Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.5.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
+Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.6.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
 
 <Tabs items={["ARM64", "AMD64"]}>
 
 <Tab value="ARM64">
 
 ```sh title="HOST (ARM64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/raft-dev-arm64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/manifest-arm64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/raft-dev-arm64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/manifest-arm64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev
@@ -181,9 +186,9 @@ sha256sum --ignore-missing -c SHA256SUMS && \
 <Tab value="AMD64">
 
 ```sh title="HOST (AMD64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/raft-dev-amd64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/manifest-amd64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/raft-dev-amd64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/manifest-amd64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-amd64.tar.gz --alias raft-dev
@@ -258,6 +263,8 @@ Check that Incus, the network service, and the expiration timer are active. For
 
 </Steps>
 
+</details>
+
 ## Next step
 
 Proceed to [First working box](./first-box.mdx) to launch, verify, and manage your first workspace.

package/docs/publishing.md

@@ -1,5 +1,6 @@
 ---
 title: Publishing
+description: Release packages and native images through verified publication gates.
 ---
 
 # Publishing a clean source release
@@ -8,12 +9,12 @@ Public releases must contain only reusable code, examples, and documentation. Ke
 
 ## Release assets and image publishing
 
-Release `main` through the `native images` workflow with a semantic `release_tag`, such as `v0.2.0`. The tag must match both Python and npm versions. Clean upstream Debian bases provide the images.
+Release `main` through the `native images` workflow with a semantic `release_tag`, such as `v0.7.0`. The tag must match both Python and npm versions. Clean upstream Debian bases provide the images.
 
 The workflow builds and inspects Python and npm packages, tests their installed executables outside the checkout, and publishes `@microck/raft` using the repository's `NPM_TOKEN` secret with npm provenance. Only then does it create the GitHub release with the wheel, source archive, npm tarball and verified image assets. Published versions are immutable; after partial publication, fix the failure and use a new patch version.
 
 ```sh
-gh workflow run images.yml --ref main -f release_tag=v0.2.0
+gh workflow run images.yml --ref main -f release_tag=v0.7.0
 ```
 
 - **Validation gating**: Publication requires native lifecycle and full-image recovery jobs alongside fresh AMD64 KVM provisioning and reboot verification.
@@ -30,15 +31,24 @@ Scan **all Git history**, branches, and tags before changing repository visibili
 
 ## Release verification commands
 
+Install `gitleaks`, `uv`, Node.js with `npm`, and the OpenSSH client providing `ssh-keygen` before running these checks. Ensure they are available on `PATH`; `uv sync --locked` does not install these tools.
+
 Run security scanning, linting, formatting checks, and package builds before tagging:
 
 ```sh
 gitleaks dir --redact --no-banner .
 gitleaks git --redact --no-banner .
 uv sync --locked
-uvx ruff check raft.py deploy/*.py
-uvx ruff format --check raft.py deploy/*.py
+uvx ruff check raft.py raft_files.py raft_run.py deploy/*.py
+uvx ruff format --check raft.py raft_files.py raft_run.py deploy/*.py
+uv run python -m compileall -q raft.py raft_files.py raft_run.py deploy
+uv run python deploy/verify-limits.py
+uv run python deploy/verify-image-tests.py
+uv run python deploy/verify-run.py
+uv run python deploy/verify-features.py
+uv run python deploy/verify-self-update.py
 uv build
+uv run python deploy/verify-release.py
 ```
 
 ## Image distribution rules

package/docs/reference/capacity.mdx

@@ -23,7 +23,7 @@ A box from a snapshot (`new --from`) or a fork keeps the source's CPU, RAM and
 disk instead of any default, and each flag you pass overrides only its own value.
 
 ```sh
-box=$(raft new --cpu 4 --memory 16GiB --disk 40GiB --ttl 3600 --purpose "Large build")
+box=$(raft new --cpu 4 --memory 16GiB --disk 40GiB --ttl 3600 --persistent --purpose "Large build")
 ```
 
 A CPU or RAM request larger than the whole host fails before anything is
@@ -37,6 +37,7 @@ Change CPU and RAM when you resume a stopped box or fork one:
 
 ```sh
 raft resume "$box" --ttl 1800 --cpu 2 --memory 4GiB
+raft stop "$box"  # Fork requires a stopped persistent source
 copy=$(raft fork "$box" --ttl 1800 --memory 2GiB)
 ```