@microck/raft 0.5.0 → 0.7.0

package/docs/reference/cli.md

@@ -8,15 +8,16 @@ description: Complete command-line reference for the Raft controller CLI.
 Command-line reference for the `raft` controller tool.
 
 Syntax:
-`raft <subcommand> [options] [arguments]`
+`raft [--json] <subcommand> [options] [arguments]`
 
-`raft --help` lists commands, `raft <subcommand> --help` lists its arguments,
+`raft --help` lists commands, `raft <subcommand> --help` explains its behavior and arguments,
 and `raft --version` prints the installed version without loading configuration.
-Output is command-specific; see [Scripting and CI](../guides/scripting-ci.mdx).
+Global `--json` emits JSONL events for structured results, byte streams, errors and exit codes.
+Without it, output is command-specific; see [Scripting and CI](../guides/scripting-ci.mdx).
 
-At most once a day, after a command finishes, Raft checks GitHub for a newer
-release and prints one line on stderr, such as
-`raft 0.6.0 is available (you have 0.5.0). Run: raft self-update`. It never
+At most once a day, Raft checks GitHub for a newer release in the background
+while a command runs, then prints one line on stderr after it finishes, such as
+`raft 0.7.0 is available (you have 0.6.0). Run: raft self-update`. It never
 installs anything or changes stdout, and network failures stay silent. See
 [`self-update`](#self-update) to turn it off.
 
@@ -27,9 +28,10 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 | Task | Commands |
 | --- | --- |
 | Workspace lifecycle | [`new`](#new), [`stop`](#stop), [`resume`](#resume), [`extend`](#extend), [`destroy`](#destroy) |
+| Disposable CI jobs | [`run`](#run) |
 | Execution and inspection | [`exec`](#exec), [`ssh`](#ssh), [`info`](#info), [`usage`](#usage) |
 | Background job | [`status`](#status), [`logs`](#logs), [`cancel`](#cancel) |
-| File transfer | [`upload`](#upload), [`download`](#download) |
+| File transfer | [`upload`](#upload), [`download`](#download), [`sync`](#sync) |
 | Snapshots and cloning | [`snapshot`](#snapshot), [`snapshots`](#snapshots), [`restore`](#restore), [`snapshot-delete`](#snapshot-delete), [`fork`](#fork) |
 | Port forwarding and desktop | [`forward`](#forward), [`desktop`](#desktop) |
 | Backup and recovery | [`backup`](#backup), [`recover`](#recover) |
@@ -38,13 +40,40 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 | Host inspection and maintenance | [`capacity`](#capacity), [`doctor`](#doctor), [`list`](#list), [`gc`](#gc), [`prune`](#prune) |
 | CLI maintenance | [`self-update`](#self-update) |
 
+## Disposable CI command
+
+### `run`
+
+**Unreleased 0.7.0 feature.** Not present in published 0.6.0. See the
+[development requirements](../guides/ci-jobs.mdx) before using these commands.
+
+`raft run [--location LOCATION | --from LOCATION:BOX/SNAPSHOT] [--cpu N] [--memory SIZE] [--disk SIZE] [--timeout SECONDS] [--push DIRECTORY | --push-all DIRECTORY] [--cwd GUEST_PATH] [--pull GUEST_DIRECTORY NEW_LOCAL_DIRECTORY]... [--purpose TEXT [--owner TEXT] [--next TEXT]] -- COMMAND [ARG ...]`
+
+Create a disposable box, probe readiness, optionally upload source, stream the
+command, collect result directories and attempt ownership-checked cleanup.
+`--timeout` defaults to 600 and covers the entire job, with separate 30-second
+collection and cleanup grace periods. The host expiry is established before
+start at timeout + 120 seconds. No renewal, detach, persistent or keep option.
+
+`--push` requires a Git working tree and copies tracked/unignored files without
+`.git`; submodules are refused. `--push-all` explicitly copies the full tree,
+including ignored files. Uploads require a new guest destination with an existing
+parent, defaulting to `/workspace/project`. Without upload, cwd is `/workspace`.
+Pulls are directory transfers to new local paths and run after a failed payload.
+
+Payload failure status takes precedence; a successful payload with failed
+collection/cleanup returns 1. Timeout is 124, Ctrl-C 130 and SIGTERM 143.
+Lifecycle messages and the allocated handle go to stderr, not stdout. Unknown
+remote outcomes are not automatically retried. See the [CI guide](../guides/ci-jobs.mdx)
+for trust restrictions, template caching, recovery limits and a GitHub example.
+
 ## Workspace lifecycle commands
 
 ### `new`
 
 Create and launch a new workspace container.
 
-`raft new [--location LOCATION] [--ttl TTL] [--cpu N] [--memory SIZE] [--disk SIZE] [--disposable] [--from LOCATION:BOX/SNAPSHOT] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
+`raft new [--location LOCATION] [--ttl TTL] [--cpu N] [--memory SIZE] [--disk SIZE] [--disposable | --persistent] [--from LOCATION:BOX/SNAPSHOT] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
 
 - `--location LOCATION`: Target host location in `~/.config/raft/incus.json`. Built-in default: first configured location.
 - `--ttl TTL`: Lifetime in seconds before automatic stop (`60` to `2592000`). Built-in default: `600`.
@@ -57,7 +86,8 @@ then the built-in default. With `--from`, configured `cpu`, `memory` and `disk`
 defaults do not apply: the box keeps the snapshot's size unless a flag overrides
 it, and `--disk shared` is refused.
 
-- `--disposable`: Delete the box and snapshots on stop or expiry. Off by default.
+- `--disposable`: Delete the box and snapshots on stop or expiry. Built-in default: persistent.
+- `--persistent`: Keep the box and its disk on stop or expiry, overriding a configured `disposable` default. Cannot be combined with `--disposable`.
 - `--from LOCATION:BOX/SNAPSHOT`: Copy a named snapshot on its source host instead of the configured image. The box keeps the snapshot's CPU, RAM and disk unless `--cpu`, `--memory` or `--disk` overrides them; the source can be running. Cannot target a different location.
 - `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Record a [box note](#note). `--owner` and `--next` need `--purpose`. Without them the box starts with no note, including boxes created `--from` a noted snapshot. A host [policy](#policy) can require fields.
 
@@ -139,30 +169,31 @@ Display active resource consumption for a running workspace: cgroup memory, CPU
 
 ## Background job commands
 
-`status`, `logs` and `cancel` require a job ID returned by `exec --detach` in the selected running workspace. Unknown jobs return an error.
-
-Cancelled jobs remain inspectable while their guest journal records exist. Rotating old logs does not prevent inspection of a live job.
+`status`, `logs` and `cancel` require the exact workspace handle and job ID returned by `exec --detach`. Status and logs remain available after workspace stop or deletion. Unknown or expired jobs return an error. Guest journal rotation does not affect retained results.
 
 ### `status`
 
-Check the execution state of a detached background job.
-
 `raft status <box> <job>`
 
-Queries `systemctl show` inside the container and outputs `ActiveState`, `SubState`, and `ExecMainStatus`.
+Read retained JSON state, exit code, timestamps and dropped output bytes from the
+host, including after workspace stop or deletion. `completed` means execution
+ended; inspect `exitCode` for success. Unknown or expired jobs are rejected.
 
 ### `logs`
 
-Retrieve journal output from a detached background job using `journalctl --no-pager -o cat -u <job>`.
-
 `raft logs <box> <job>`
 
-### `cancel`
+Read the first 1 MiB of combined output retained on the host. Results expire
+seven days after completion and are pruned on access. The store allows at most
+512 records. See [Background jobs](../guides/background-jobs.mdx).
 
-Terminate a running detached background job using `systemctl stop <job>`.
+### `cancel`
 
 `raft cancel <box> <job>`
 
+Stop the guest job control group. Retained results remain available. Cancellation
+can fail while the guest unit is still starting; inspect before retrying.
+
 ## File transfer commands
 
 ### `upload`
@@ -222,7 +253,7 @@ Clone a stopped workspace into an independent container on the same host and sta
 - `--ttl TTL`: Lifetime in seconds for the clone. Required.
 - `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Replace the clone's whole note. Without them the clone keeps the source note.
 
-Omitted CPU/RAM values inherit the source limits; controller defaults never apply to forks. The clone keeps the source's disk: the shared pool, or an own disk of the same size as a thin snapshot, which reserves that size in `raft-disks`. To copy a box onto a disk of another size, snapshot it and use `new --from BOX/SNAPSHOT --disk SIZE`. The clone is persistent unless `--disposable` is supplied, regardless of the source policy.
+Omitted CPU/RAM values inherit the source limits; controller defaults never apply to forks. The clone keeps the source's disk: the shared pool, or an own disk of the same size as a thin snapshot, which reserves that size in `raft-disks`. To copy a box onto a disk of another size, snapshot it and use `new --from BOX/SNAPSHOT --disk SIZE`. The clone is persistent unless `--disposable` is supplied, regardless of the source and of a configured `disposable` default.
 The note the clone ends up with must satisfy the host [policy](#policy).
 
 Returns the qualified handle of the clone.
@@ -353,12 +384,16 @@ would leave them out. Otherwise Raft does not interpret notes.
 
 Show or change the controller defaults for `new`.
 
-`raft config`
+`raft config [--location LOCATION]`
 `raft config set KEY VALUE`
 `raft config unset KEY`
 
-- `KEY`: One of `location`, `ttl`, `cpu`, `memory`, `disk`.
-- `VALUE`: Accepted exactly when the same text is accepted by the matching `new` flag. A `location` must be configured.
+- `KEY`: One of `location`, `ttl`, `cpu`, `memory`, `disk`, `disposable`.
+- `VALUE`: Accepted exactly when the same text is accepted by the matching `new` flag. A `location` must be configured. `disposable` takes `true` or `false`.
+
+`disposable true` makes `new` create disposable boxes, including `new --from`,
+because a snapshot carries no lifecycle; `--persistent` keeps one box. `fork`
+ignores it: a fork is persistent unless it gets `--disposable`.
 
 `cpu`, `memory` and `disk` size only boxes created from the image. `new --from`
 and `fork` keep the source's CPU, RAM and disk; only explicit flags change them.
@@ -373,29 +408,51 @@ file makes `new` fail with the file path and key; `set` or `unset` that key to
 repair it.
 
 `raft config` prints one JSON object: `file`, `defaults` (each key's `value` and
-`source`, `config` or `built-in`) and `policy` (each location's `require` list
-and `changed` record). It contacts every configured host to read policies.
-See [Defaults and note policies](../guides/config-policy.mdx).
+`source`, `config` or `built-in`) and `policy`. For each location, `policy` has
+`require` (the required note fields), `deleteStoppedAfterHours` (`null` without
+retention), `deleteStoppedAfterSince` (when retention was set, Unix seconds) and
+the last change records `requireChanged` and `deleteStoppedAfterChanged`. It
+contacts every configured host to read policies unless `--location LOCATION`
+selects one. This filter affects the policy report, not controller defaults,
+and is rejected with `set` or `unset`. Location-scoped config and doctor are
+development-branch additions, not available in published 0.6.0.
+See [Defaults and host policies](../guides/config-policy.mdx).
 
 ### `policy`
 
-Set or clear the box note fields a location's host requires.
+Set or clear a location's host policies: the box note fields it requires and
+how long it keeps stopped boxes.
 
-`raft policy LOCATION --require FIELDS`
-`raft policy LOCATION --clear`
+`raft policy LOCATION [--require FIELDS|none] [--delete-stopped-after HOURS|never]`
 
-- `--require FIELDS`: Comma-separated fields from `purpose`, `owner`, `next`. Must include `purpose`.
-- `--clear`: Stop requiring fields.
+- `--require FIELDS`: Comma-separated fields from `purpose`, `owner`, `next`. Must include `purpose`. `--require none` stops requiring fields.
+- `--delete-stopped-after HOURS`: Delete boxes that stay stopped for HOURS, a positive whole number, with their snapshots. `--delete-stopped-after never` keeps stopped boxes.
 
-The policy is stored on the host in the Incus project key `user.raft.require`,
-so it applies to every controller. `new`, `fork`, `recover` and `note` check it
-on the controller for an actionable error, then again in the host transaction
-that writes the note. The command prints the change and the host records the
-time, SSH account and controller in `user.raft.require.changed` and the host
+Give either option or both; each changes only its own policy. Both values are
+checked before the host changes.
+
+Policies are stored on the host in the Incus project `raft`, so they apply to
+every controller. The command prints each change and the host records the time,
+SSH account and controller in a `.changed` key beside the policy and in the host
 journal (`journalctl -t raft`).
 
-This is a guardrail for agents, not a security boundary: SSH and sudo on the
-host can change the policy or bypass it, and older controllers do not check it.
+The note policy lives in `user.raft.require`. `new`, `fork`, `recover` and
+`note` check it on the controller for an actionable error, then again in the
+host transaction that writes the note.
+
+Retention lives in `user.raft.delete-stopped-after`, with the time it was set in
+`user.raft.delete-stopped-after.since`. The host expiry worker deletes a stopped
+box once HOURS have passed since the later of its stop and that time, so a new
+or shorter policy never deletes a box sooner than HOURS after the change. The
+worker runs every 15 seconds and on [`gc`](#gc), logs each deletion to the host
+journal and never touches running boxes. A stopped box with no recorded stop
+time, such as one powered off from inside, stopped with native `incus` or
+recovered from a backup, starts its clock when the worker first sees it.
+[`list`](#list) shows each box's `deleteAt`. Setting retention needs the current
+host worker; on an older one it fails with redeploy guidance.
+
+Policies are guardrails for agents, not a security boundary: SSH and sudo on the
+host can change or bypass them, and older controllers do not check note policies.
 
 ## Host inspection and maintenance commands
 
@@ -416,7 +473,9 @@ if any. See [Box sizing and capacity](./capacity.mdx) for the fields.
 
 Inspect host connectivity, Incus version, expiry-worker compatibility, active systemd units (`incus`, `raft-expire.timer`, `raft-network.service`), root filesystem usage, status of the shared `raft-data` pool and, when own box disks are enabled, the `raft-disks` pool, and saved box count across configured hosts. Without `raft-disks` it prints `own box disks: not enabled (redeploy with --disk-pool SIZE)` and does not fail. An incompatible worker returns a nonzero exit status and names the failing location without running expiry or modifying boxes.
 
-`raft doctor`
+`raft doctor [--location LOCATION]`
+
+Pass `--location` to inspect one configured host independently of offline hosts.
 
 ### `list`
 
@@ -424,7 +483,9 @@ List existing workspace containers across configured hosts.
 
 `raft list [--location LOCATION]`
 
-Prints one JSON object per box (JSONL), with `box`, `state`, `stopAt`, `disk` and `note` fields.
+Prints one JSON object per box (JSONL), with `box`, `state`, `stopAt`, `deleteAt`, `disk` and `note` fields.
+`deleteAt` is the Unix time when the location's [retention](#policy) deletes a
+stopped box, as a string like `stopAt`, or `""` when no deletion is due.
 `disk` is `"shared"` for the shared pool or the own disk's size, such as `"20GiB"`.
 `note` is the box note object, or `null` when the box has none.
 An empty inventory prints no records. See [Scripting and CI](../guides/scripting-ci.mdx)
@@ -432,7 +493,7 @@ for output formats, exit codes, readiness, and failure handling.
 
 ### `gc`
 
-Enforce deadlines immediately. Persistent boxes stop; disposable boxes are deleted.
+Enforce deadlines and retention immediately. Persistent boxes stop; disposable boxes are deleted; stopped boxes past the location's [retention](#policy) are deleted.
 
 `raft gc [--location LOCATION]`
 
@@ -442,9 +503,9 @@ Preview deletion of persistent stopped boxes older than the selected number of d
 
 `raft prune --older-than DAYS [--location LOCATION] [--yes]`
 
-Days must be at least one. Without `--yes`, this only prints JSONL candidates. With `--yes`, it deletes matching boxes and their snapshots under the host lock. Running boxes and boxes without a recorded stop time are excluded. Stop timestamps come from Raft stop/expiry, not box creation. No automatic retention policy is enabled.
+Days must be at least one. Without `--yes`, this only prints JSONL candidates. With `--yes`, it deletes matching boxes and their snapshots under the host lock. Running boxes and boxes without a recorded stop time are excluded. Stop timestamps come from Raft stop/expiry, or from the host worker when it first sees a box stopped another way, never from box creation. For automatic deletion, set a [retention policy](#policy).
 
-Disposable creation/fork and prune require the current expiry worker installed through the deployer. A mismatch fails with deployment guidance; the CLI does not install or adapt an older worker.
+Disposable creation/fork, prune and setting retention require the current expiry worker installed through the deployer. A mismatch fails with deployment guidance; the CLI does not install or adapt an older worker.
 
 ## CLI maintenance commands
 
@@ -481,3 +542,34 @@ pinned or scripted runs. The notice caches its last result in
 `$XDG_CACHE_HOME/raft/update.json` (default `~/.cache/raft/update.json`). It
 waits at most 2 seconds for GitHub and is skipped for `self-update` and
 `--version`.
+
+### `completions`
+
+`raft completions bash|zsh|fish`
+
+Print a shell integration script. Source it in the matching shell, for example
+`source <(raft completions bash)`. Completions discover the installed parser on
+each request, including nested commands, flags and fixed choices. They never
+load host configuration or contact a host. The private `_complete` command is
+used by these scripts, not needed in ordinary workflows.
+
+### `sync`
+
+`raft sync BOX SOURCE DESTINATION [--all] [--dry-run]`
+
+Sync source into an existing running workspace, replacing matching files and
+preserving guest-only files. Checksums detect content changes even if timestamps
+and sizes match; unchanged content is not resent. Requires rsync on the
+controller and guest. Install it explicitly if an older image lacks it.
+
+Git selects tracked and unignored files by default, excluding `.git` and rejecting
+submodules. `--all` includes ignored and hidden files too. Deleted source files
+are not deleted remotely. Rsync reports skipped unsafe symlinks and special files.
+Destination is an absolute non-root guest directory with an existing parent.
+`--dry-run` previews changes without writing files. Updates are atomic per file,
+not per tree; rerun after an interruption to finish syncing.
+
+```sh
+raft sync "$BOX" . /workspace/project --dry-run
+raft sync "$BOX" . /workspace/project
+```

package/docs/reference/configuration.mdx

@@ -80,7 +80,8 @@ controller and is separate from the location inventory:
     "ttl": 3600,
     "cpu": 2,
     "memory": "4GiB",
-    "disk": "20GiB"
+    "disk": "20GiB",
+    "disposable": true
   }
 }
 ```
@@ -92,15 +93,18 @@ controller and is separate from the location inventory:
 | `cpu` | A positive whole number | `1` |
 | `memory` | Whole GiB, e.g. `16GiB` | `2GiB` |
 | `disk` | Whole GiB for an own box disk, or `shared` | `shared` |
+| `disposable` | `true` or `false` | `false` (persistent) |
 
-Explicit flags win over these values. `cpu`, `memory` and `disk` size only boxes
-created from the image: `new --from` and `fork` keep the source's size unless a
-flag overrides it. A `disk` default needs the `raft-disks` pool on the target
+Explicit flags win over these values; `--persistent` overrides `disposable`.
+`cpu`, `memory` and `disk` size only boxes created from the image: `new --from`
+and `fork` keep the source's size unless a flag overrides it. `disposable`
+applies to `new` and `new --from`, never to `fork`. A `disk` default needs the `raft-disks` pool on the target
 host, like `--disk`. Unknown keys and invalid values make
 `raft new` fail with the file path and key. Edit the file with
 `raft config set KEY VALUE` and `raft config unset KEY`, and inspect it with
-`raft config`. Required box note fields are a host policy, not part of this
-file; see [Defaults and note policies](../guides/config-policy.mdx).
+`raft config`. Required box note fields and stopped-box retention are host
+policies, not part of this file; see
+[Defaults and host policies](../guides/config-policy.mdx).
 
 ## SSH configuration and connection behavior
 

package/docs/reference/meta.json

@@ -5,6 +5,8 @@
   "pages": [
     "cli",
     "configuration",
-    "capacity"
+    "capacity",
+    "[Runtime contract](/docs/contract/)",
+    "[Boot measurements](/docs/boot-performance/)"
   ]
 }

package/docs/releases/0.2.0.md

@@ -1,5 +1,6 @@
 ---
 title: Raft 0.2.0
+description: Historical changes and upgrade requirements for Raft 0.2.0.
 ---
 
 # Raft 0.2.0

package/docs/releases/0.2.1.md

@@ -1,5 +1,6 @@
 ---
 title: Raft 0.2.1
+description: Historical changes and upgrade requirements for Raft 0.2.1.
 ---
 
 # Raft 0.2.1

package/docs/releases/0.3.0.md

@@ -1,5 +1,6 @@
 ---
 title: Raft 0.3.0
+description: Historical changes and upgrade requirements for Raft 0.3.0.
 ---
 
 # Raft 0.3.0

package/docs/releases/0.4.0.md

@@ -1,5 +1,6 @@
 ---
 title: Raft 0.4.0
+description: Historical changes and upgrade requirements for Raft 0.4.0.
 ---
 
 # Raft 0.4.0

package/docs/releases/0.5.0.md

@@ -1,5 +1,6 @@
 ---
 title: Raft 0.5.0
+description: Historical changes and upgrade requirements for Raft 0.5.0.
 ---
 
 # Raft 0.5.0

package/docs/releases/0.6.0.md

@@ -0,0 +1,17 @@
+---
+title: Raft 0.6.0
+description: Historical changes and upgrade requirements for Raft 0.6.0.
+---
+
+# Raft 0.6.0
+
+- **Disposable by default.** `raft config set disposable true` makes `raft new` create disposable boxes, which are deleted with their snapshots when they stop or expire. `raft new --persistent` keeps one box anyway, and `--disposable` still works the other way. The default also applies to `new --from`; a fork stays persistent unless you pass `--disposable`. `raft config` shows the setting.
+- **Delete boxes left stopped.** `raft policy LOCATION --delete-stopped-after 48` makes a host delete boxes, with their snapshots, once they have been stopped for 48 hours. The host applies it every 15 seconds and on `raft gc`, even with no controller online, logs each deletion to its journal (`journalctl -t raft`) and never touches running boxes. A new or shorter policy never deletes a box sooner than its hours after the change, and resuming a box resets its clock. `raft list` shows each stopped box's `deleteAt`. `--delete-stopped-after never` turns it off.
+- **Stop times for every stopped box.** The host now records a stop time for boxes stopped outside `raft stop`, such as a poweroff inside the box, a native `incus stop` or a recovered backup, when it first sees them. `raft prune` can therefore select them later; before, it skipped them forever.
+- **`raft policy` changes.** `--require` and `--delete-stopped-after` can be set together or alone, and each changes only its own policy. `--require none` replaces `--clear`, which is gone. In `raft config`, each location's `changed` field is now `requireChanged`, beside the new `deleteStoppedAfterHours`, `deleteStoppedAfterSince` and `deleteStoppedAfterChanged`.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.6.0`, or install the attached Python wheel; existing installs can run `raft self-update`.
+
+Redeploy each host with this release's `deploy/deploy.py`. The host expiry worker changed, and until a host is redeployed `raft doctor` reports it, while `new --disposable` (including a disposable default), `fork --disposable`, `raft prune` and `raft policy --delete-stopped-after HOURS` fail on it with redeploy guidance. Redeploying changes nothing else on the host and sets no retention policy.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/docs/releases/0.7.0.md

@@ -0,0 +1,23 @@
+---
+title: Raft 0.7.0
+description: Changes and upgrade requirements for Raft 0.7.0.
+---
+
+# Raft 0.7.0
+
+- **Disposable foreground CI jobs.** `raft run -- COMMAND ...` creates a fresh disposable box, waits for readiness, streams one command and attempts ownership-checked cleanup after success, failure or cancellation. Use the existing location, size, snapshot-template and note options. This is remote job orchestration, not a registered GitHub runner or paid Boat integration.
+- **Source and result transfers.** `--push DIRECTORY` uploads Git-tracked and unignored files without Git metadata; submodules are rejected. `--push-all DIRECTORY` explicitly includes hidden and ignored files. Repeated `--pull GUEST_DIRECTORY NEW_LOCAL_DIRECTORY` options collect results before cleanup, including after a failed command. `--cwd` selects the guest working directory.
+- **Bounded lifetimes and cancellation-safe cleanup.** A single timeout covers preparation through command execution, followed by bounded collection and cleanup grace periods. A unique run identity and fixed expiry are set before startup. Private cancellation records prevent a queued creation from starting after confirmed cleanup. Payload failures retain their exit status; timeout returns 124, Ctrl-C 130 and SIGTERM 143. Collection or unconfirmed cleanup turns an otherwise successful run into failure.
+- **Transfer deadline fix.** An interrupted receive now kills and reaps its child even when stdout has already closed, instead of waiting indefinitely for process exit.
+- **Retained background jobs.** `raft exec --detach` returns a job ID. Use `status`, `logs` and `cancel` to manage it. Results and bounded output remain available after the workspace stops or is deleted.
+- **Source sync.** `raft sync` transfers changed files into an existing workspace, with Git-aware selection and a dry-run option.
+- **Structured output.** Global `--json` emits JSONL events for results, streams, errors and exit codes.
+- **Documentation and verification.** A trusted-job GitHub Actions example, package checks and real AMD64/ARM64 tests cover source transfers, failing-command artifacts, timeout, cancellation and template isolation. The static documentation build uses patched Next.js 16.4.1.
+
+Install with `npm install -g @microck/raft@0.7.0` or the attached Python wheel. Existing installs can use `raft self-update`.
+
+Use dedicated hosts and trusted code only. The controller uses existing passwordless-sudo SSH access; it is not a scoped CI identity. Incus boxes share the host kernel and do not provide VM isolation. Templates retain their complete filesystem, including secrets. No credentials, repository secrets, runner registration or paid capacity are provisioned by `raft run`.
+
+The current expiry worker (protocol 2, introduced in 0.6.0) is required. This release does not change that protocol or configure a retention policy. Host expiry remains a backstop when cleanup cannot be confirmed, not a guarantee of instantaneous deletion or rollback of command side effects.
+
+Verify `SHA256SUMS` before installing packages or importing the image for your host architecture.

package/docs/releases/index.mdx

@@ -0,0 +1,21 @@
+---
+title: Release notes
+description: Published Raft versions and clearly marked upcoming changes.
+---
+
+# Release notes
+
+The setup examples use **0.6.0**, the latest published npm package and GitHub
+release checked on 2026-10-24. [GitHub releases](https://github.com/Microck/raft/releases)
+are the source for downloadable packages, images and checksums.
+
+- [0.7.0 — unreleased](./0.7.0.md): disposable foreground CI jobs on the development branch.
+- [0.6.0](./0.6.0.md): disposable defaults and stopped-box retention.
+- [0.5.0](./0.5.0.md): flexible sizing, own box disks, defaults and self-update.
+- [0.4.0](./0.4.0.md): box notes.
+- [0.3.0](./0.3.0.md): guided host onboarding.
+- [0.2.1](./0.2.1.md): worker compatibility checks.
+- [0.2.0](./0.2.0.md): extended workspace lifecycle and transfer commands.
+
+Historical notes describe their own release, not the current command contract.
+For upgrades, follow [Upgrades and image changes](../guides/upgrades.mdx).

package/docs/releases/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Release notes",
+  "collapsible": true,
+  "defaultOpen": false,
+  "pages": [
+    "index",
+    "0.7.0",
+    "0.6.0",
+    "0.5.0",
+    "0.4.0",
+    "0.3.0",
+    "0.2.1",
+    "0.2.0"
+  ]
+}

package/docs/requirements.mdx

@@ -21,7 +21,7 @@ Each workspace host must be a dedicated physical machine or virtual instance:
 
 `raft host add` checks these requirements read-only before it changes a host.
 
-Host CPU and RAM reserves are advisory estimates for `raft capacity`, not enforced cgroup locks. Raft limits neither how many boxes a host runs nor their size.
+Host CPU and RAM reserves are advisory estimates for `raft capacity`, not enforced cgroup locks. There is no product-tier box-count cap. Individual CPU/RAM requests must fit the host, and own disks must pass storage reservation checks.
 
 <Callout type="warn" title="Dedicated host requirement">
 Do not deploy Raft on hosts with existing Incus storage pools or shared virtualization workloads. Deployment configures dedicated nftables rules, storage pools, and system services.

package/docs/reviews/docs-audit-2026-10-24.md

@@ -0,0 +1,92 @@
+# Documentation audit — 2026-10-24
+
+## Scope and comparison
+
+Reviewed the 34 existing published-source documentation pages, including seven
+release-note pages, and added three navigation hubs (37 pages total). Review
+reports are deliberately excluded from the public site; the repository-only
+`setup-explained.html` is not part of the site's generated routes.
+
+Compared Boat's complete 206-entry documentation index and representative
+quickstart, concepts, setup, snapshots, background tasks, CI, security, desktop,
+hosting and troubleshooting material. This is a documentation comparison, not a
+claim to have tested Boat's service or every one of its 206 pages.
+
+Primary references: https://docs.boat.dev/llms.txt,
+https://docs.boat.dev/quickstart, https://docs.boat.dev/concepts,
+https://docs.boat.dev/long-running-tasks/background-commands,
+https://docs.boat.dev/troubleshooting. The useful pattern is task-first pages and
+progressive disclosure, not copying Boat's managed-service promises into Raft.
+
+## Findings
+
+1. The main sidebar mixed first-run tasks with architecture, publishing and test
+   histories. New guide/maintainer/release hubs separate audiences without moving
+   established page URLs.
+2. Onboarding linked nonexistent 0.7.0 packages and images. GitHub's latest release
+   and npm both reported 0.6.0; the v0.7.0 release endpoint returned 404. Stable
+   examples now pin 0.6.0 and development-only CI is labeled and commit-pinned.
+3. Several persistent tutorials inherited a disposable controller default, and
+   one sequence resumed a box immediately before forking a source that must be
+   stopped. The examples now state the required lifecycle explicitly.
+4. Backup instructions asked for permissions on a destination that must not
+   exist. Verified against raft.py: the temporary archive is created and checked
+   privately before no-overwrite publication. Wording now matches that behavior.
+5. Search flooded the dialog with repeated paragraphs from reference/history
+   pages. Matching page titles now rank first, initial results show up to eight
+   pages with two sections each, and an explicit action restores every match.
+
+## Verification
+
+- Production static build, type checking and lint passed.
+- All 37 routes, local links and fragment targets, search index, Markdown exports,
+  asset downloads and 404 behavior passed the exported-site checks.
+- 120 shell examples passed Bash syntax checks. Help for new/fork/run was checked.
+  This is not execution against Incus; no hosts, credentials or workspaces changed.
+- Real cloud-browser interactions exercised navigation, advanced setup disclosure
+  and search. The separate automated Chromium suite could not download a valid
+  browser archive in this environment; no passing result is claimed for that suite.
+- Historical benchmark and runtime evidence remains labeled with its original
+  dates/limits. This docs-only work does not re-certify runtime behavior.
+
+## Page-by-page disposition
+
+| Page | Review / change |
+| --- | --- |
+| `boat-capabilities.md` | Renamed parity to comparison; added a short operating-model summary; folded the detailed matrix and marked run as preview. |
+| `boat-parity-design.md` | Retained architecture rationale; added description and grouped under Maintainers. |
+| `boot-performance.mdx` | Retained dated samples and limitations; added search description and moved under Reference. |
+| `contract.md` | Marked maintainer audience and unreleased CI contract; clarified persistent-only stop retention; moved navigation into Reference. |
+| `first-box.mdx` | Made persistence explicit; separated destructive cleanup from stop/resume; reduced the next-step list. |
+| `guides/background-jobs.mdx` | Retained start/status/log/cancel flow and the important exit-status versus completion distinction. |
+| `guides/backup-recovery.mdx` | Clarified persistent source and private archive creation; removed impossible pre-existing destination permission instruction. |
+| `guides/ci-jobs.mdx` | Marked unreleased 0.7.0; replaced nonexistent npm installation with a reviewed full source commit in an isolated environment. |
+| `guides/config-policy.mdx` | Retained defaults/host-policy separation and destructive-retention warnings; reachable from the operator guide group. |
+| `guides/desktop-services.mdx` | Retained tunnel foreground behavior, binding requirements and exact noVNC path. |
+| `guides/docker.mdx` | Retained daemon checks, runnable build example, storage guidance and pruning warning. |
+| `guides/files.mdx` | Resolved running-only wording versus supported stopped single-file transfers. |
+| `guides/index.mdx` | Added a task-oriented Develop / Automate / Operate hub. |
+| `guides/long-running-services.mdx` | Kept restart semantics and TTL limits; made the persistent creation example independent of controller defaults. |
+| `guides/project-setup.mdx` | Kept the upload/setup/template sequence; made persistent template source explicit. |
+| `guides/scripting-ci.mdx` | Kept output/exit-code tables and retry safety; made persistent cleanup example explicit. |
+| `guides/snapshots-forks.mdx` | Warned before stopping disposable sources and corrected the sequential resume-then-fork example. |
+| `guides/troubleshooting.mdx` | Retained symptom/error sections and safe no-wildcard recovery guidance; checked command references and anchors. |
+| `guides/upgrades.mdx` | Updated stale 0.2.0 pins to published 0.6.0; kept component separation and backup/redeploy warnings. |
+| `index.mdx` | Replaced the 12-row task catalogue with a short setup path and focused task links; explicit persistent example and release status. |
+| `maintainers/index.mdx` | Added an audience-specific hub instead of four competing top-level implementation links. |
+| `operations.mdx` | Pinned real 0.6.0 assets/packages; kept guided onboarding primary and folded manual steps without changing URLs or anchors. |
+| `publishing.md` | Retained maintainer release gates; added description and moved out of the onboarding navigation. |
+| `reference/capacity.mdx` | Corrected fork-after-resume ordering and persistent source; retained detailed accounting as reference, not onboarding. |
+| `reference/cli.md` | Kept the complete command lookup and anchors; labeled run as unreleased rather than a stable command. |
+| `reference/configuration.mdx` | Retained schema, required image fingerprint, precedence and SSH behavior; checked examples and links. |
+| `releases/0.2.0.md` | Retained historical release content; added an explicit historical description and a release-notes navigation home. |
+| `releases/0.2.1.md` | Retained historical release content; added an explicit historical description and a release-notes navigation home. |
+| `releases/0.3.0.md` | Retained historical release content; added an explicit historical description and a release-notes navigation home. |
+| `releases/0.4.0.md` | Retained historical release content; added an explicit historical description and a release-notes navigation home. |
+| `releases/0.5.0.md` | Retained historical release content; added an explicit historical description and a release-notes navigation home. |
+| `releases/0.6.0.md` | Retained historical release content; added an explicit historical description and a release-notes navigation home. |
+| `releases/0.7.0.md` | Marked as unreleased; removed claims that packages/images already exist. |
+| `releases/index.mdx` | Added explicit published versus unreleased status and links to historical notes. |
+| `requirements.mdx` | Clarified product caps versus real CPU/RAM/storage limits; kept the dedicated-host warning. |
+| `site-development.md` | Retained build/export guidance; added description and grouped under Maintainers. |
+| `verification.mdx` | Corrected obsolete shared-pool-only statement; retained dated evidence and uncertainty; grouped under Maintainers. |