@microck/raft 0.6.0 → 0.7.0

package/docs/guides/backup-recovery.mdx

@@ -9,7 +9,8 @@ Raft exports portable workspace archives and restores them onto compatible hosts
 
 ## Target workspace handle
 
-Commands in this guide require a stopped workspace:
+Use a **persistent** workspace. Stop it before backup; stopping a disposable box
+deletes it and its snapshots, so copy files out instead.
 
 ```sh title="CONTROLLER: Select and stop target workspace"
 raft list
@@ -35,7 +36,7 @@ Backup archives contain the entire guest filesystem, including credentials, SSH
 
 Raft enforces safeguards during export:
 
-- **Private permissions**: Destination mode must be `0600`. Group and world permissions must be zero before export begins.
+- **Private permissions**: Raft creates the staged archive with mode `0600` and publishes it privately. Choose a new destination path; do not pre-create the file.
 - **Atomic link publication**: After export and `fsync`, Raft publishes the archive using `os.link(archive.name, destination)`. Hard-link support is checked at final publication rather than preflight; export can succeed while publication fails if the filesystem lacks hard-link support.
 - **No overwriting**: The destination file must not already exist.
 - **Lifecycle lock**: Export holds `/run/lock/raft-incus.lock`. Expiry checks for other containers on the host are delayed while the lock is held.

package/docs/guides/ci-jobs.mdx

@@ -0,0 +1,209 @@
+---
+title: Disposable CI jobs
+description: Run trusted builds in temporary Raft boxes, collect results, and clean up with a bounded lifetime.
+---
+
+# Disposable CI jobs
+
+`raft run` runs one foreground command in a fresh disposable box. It creates the
+box, waits for command readiness, optionally uploads source, streams command
+output, collects requested result directories, and attempts ownership-checked
+cleanup even after failure or cancellation. It does not register a GitHub
+self-hosted runner or replace your CI scheduler.
+
+<Callout type="warn" title="Unreleased: requires the 0.7.0 development code">
+The published release is 0.6.0, which does not include `raft run`. As checked on
+2026-10-24, no 0.7.0 npm package or GitHub release assets are available. Use the
+[stable scripting workflow](./scripting-ci.mdx) unless you intend to test a reviewed
+source revision. Do not install a nonexistent 0.7.0 package.
+</Callout>
+
+For development, run `python3 /path/to/raft.py run` from the reviewed checkout.
+The CI example below pins the full source commit instead of an unpublished tag.
+
+## Trust boundary
+
+Use dedicated hosts and trusted jobs only. The controller's SSH identity has
+passwordless sudo and controls the host; it is not a scoped, per-job CI token.
+Boxes are unprivileged Incus containers sharing the host kernel, not separate
+kernel VMs. Do not expose this identity to unreviewed pull requests, fork jobs,
+or a `pull_request_target` workflow that checks out attacker-controlled code.
+
+Raft does not install or register a runner, configure repository secrets, forward
+your SSH agent, copy controller environment variables, or buy cloud capacity.
+The operator must approve and configure existing host access separately. Never
+copy a host private key or a GitHub token into the guest.
+
+## One command
+
+```sh title="CONTROLLER: Git working tree"
+RAFT_NO_UPDATE_CHECK=1 raft run \
+  --location lab --timeout 600 --cpu 2 --memory 4GiB \
+  --purpose "Project tests" --owner "Local CI" --next "Delete after collection" \
+  --push . --pull /workspace/project/reports ./ci-reports \
+  -- bash -lc 'set -euo pipefail; mkdir -p reports; npm ci; npm test 2>&1 | tee reports/test.log'
+```
+
+The controller needs Linux, Python 3.11.8+, OpenSSH, Git for `--push`, a configured
+Raft location, verified SSH host keys, batch authentication, and the current host
+expiry worker. Ordinary image/host sizing and note policies still apply. `run`
+always forces disposable behavior, regardless of controller lifetime defaults.
+It never retries the payload command.
+
+- stdout/stderr stream the payload; lifecycle messages and elapsed time go to
+  stderr. There is no cost estimate or JSON result protocol.
+- `--timeout` is one total deadline for Git filtering, creation, readiness, upload
+  and execution, not a fresh timeout for each step. Default: 600 seconds; range:
+  1 to 2,591,880 seconds.
+- `--push` includes tracked and unignored untracked files from the chosen Git
+  working tree, including working-tree edits. It excludes `.git` at every level
+  and refuses submodules. Tracked files remain included even if ignored later:
+  this is not a secret scanner. Deleted tracked files are absent.
+- `--push-all` explicitly copies the complete directory, including hidden and
+  ignored files and Git metadata. Inspect it for credentials first. This is the
+  opt-in alternative for non-Git or explicitly staged trees; it is not a silent
+  fallback when Git fails.
+- Uploads default to `/workspace/project`; without an upload, commands default
+  to `/workspace`. `--cwd` overrides this. An upload destination must not exist,
+  and its parent must already exist. Raft never merges into a stale checkout.
+- Repeat `--pull GUEST_DIRECTORY NEW_LOCAL_DIRECTORY` to collect directories,
+  including after a failing payload. Local parents must exist; destinations
+  must be new, including no existing symlinks. Files can be placed in a result
+  directory. Collection happens before deletion, with a shared 30-second grace.
+  A failed pull does not stop later pulls unless that grace has expired.
+- Exit status preserves a failing payload, including signal-style statuses.
+  Job timeout returns 124, Ctrl-C 130, SIGTERM 143. Setup/collection/cleanup
+  failure returns 1 when there is no earlier failing status. A successful
+  payload is not reported successful when cleanup cannot be confirmed.
+
+The host receives a unique ownership marker and a fixed expiry of timeout + 120
+seconds as part of creation, before startup. Cleanup checks ownership under the
+host lifecycle lock and has a separate 30-second grace. Repeated cancellation is
+ignored during these bounded collection/cleanup attempts. No lease renewal or
+`--keep` mode is implemented.
+
+If creation was not acknowledged, cleanup first records that run's cancellation
+under the same host lifecycle lock. Creation checks that record before allocating,
+so a queued SSH request cannot start the box after cleanup has confirmed absence.
+These empty per-run records live in the root-only `/run/raft-ci-cancelled`
+directory, use no-follow operations, and remain until host reboot, when queued
+processes also disappear. Ordinary acknowledged runs leave no cancellation file.
+
+If the controller is killed before cleanup, SSH is lost, or cleanup fails, inspect
+the exact handle printed on stderr. A disconnected create may still finish when
+cancellation could not be recorded. The disposable expiry worker is a backstop,
+not a guarantee of instantaneous deletion: an unreachable host, stopped worker or
+held lifecycle lock can delay it. Do not blindly rerun an uncertain job or assume
+its side effects were rolled back.
+
+## Prepared templates instead of shared mutable caches
+
+Prepare dependencies and tool versions in a persistent base box, stop it, then
+create a named snapshot. See [project setup](./project-setup.mdx) and
+[snapshots](./snapshots-forks.mdx). Keep the source box and snapshot available:
+
+```sh title="CONTROLLER: Use an existing trusted snapshot"
+raft run --from lab:rf-REPLACE_WITH_BASE_ID/ci-base --timeout 900 \
+  --purpose "Cached build" --owner "CI" --next "Delete after tests" \
+  --push . -- bash -lc 'npm ci --prefer-offline && npm test'
+```
+
+The template stays on its source host and retains its size unless explicitly
+overridden. Put reusable caches outside the upload destination, which must be
+new. Each job gets an independent copy; its mutations do not update the template
+or another job's cache. Refresh templates deliberately when dependencies change.
+
+Raft snapshots retain filesystem contents, including credentials and Docker
+storage. They do not save process memory. Inspect and sanitize the base before
+sharing it with jobs. Do not assume Boat's selective snapshot/cache rules apply
+to Raft's whole-filesystem copies.
+
+## GitHub Actions orchestration example
+
+The following is an example for a separate trusted project, not a change to
+Raft's own runner fleet. An ordinary `ubuntu-latest` job invokes Raft over SSH.
+Before using it, an operator must approve storing a dedicated CI host key as
+`RAFT_SSH_KEY`, verified host-key lines as `RAFT_KNOWN_HOSTS`, and the location
+inventory JSON as `RAFT_INVENTORY`. The inventory's SSH target must use that key
+and its image fingerprint must be pinned. Never generate trust with an unchecked
+`ssh-keyscan` or disable host-key checking. Restrict access to these secrets.
+
+The example pins development commit `7d678bb079a9b2dcde4e2eb9e4cd0468d00f50f3` in a
+separate Python environment. Review that code and its unreleased status
+before use; do not silently replace it with a moving branch.
+
+```yaml title="EXAMPLE: .github/workflows/trusted-build.yml"
+name: Trusted Raft build
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      RAFT_NO_UPDATE_CHECK: '1'
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: '3.14'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: '24'
+      - name: Install reviewed development controller
+        run: |
+          python -m venv "$RUNNER_TEMP/raft-cli"
+          "$RUNNER_TEMP/raft-cli/bin/pip" install "git+https://github.com/Microck/raft.git@7d678bb079a9b2dcde4e2eb9e4cd0468d00f50f3"
+          echo "$RUNNER_TEMP/raft-cli/bin" >> "$GITHUB_PATH"
+      - name: Configure approved existing access
+        env:
+          SSH_KEY: ${{ secrets.RAFT_SSH_KEY }}
+          KNOWN_HOSTS: ${{ secrets.RAFT_KNOWN_HOSTS }}
+          INVENTORY: ${{ secrets.RAFT_INVENTORY }}
+        run: |
+          umask 077
+          mkdir -p ~/.ssh ~/.config/raft
+          printf '%s\n' "$SSH_KEY" > ~/.ssh/id_ed25519
+          printf '%s\n' "$KNOWN_HOSTS" > ~/.ssh/known_hosts
+          printf '%s\n' "$INVENTORY" > ~/.config/raft/incus.json
+          printf 'Host *\n  BatchMode yes\n  StrictHostKeyChecking yes\n  IdentitiesOnly yes\n' > ~/.ssh/config
+      - name: Run remote tests and collect logs
+        run: |
+          raft run --location ci --timeout 900 --cpu 2 --memory 4GiB \
+            --purpose "Trusted project tests" --owner "GitHub Actions" --next "Delete after tests" \
+            --push . --pull /workspace/project/reports ./ci-reports \
+            -- bash -lc 'set -euo pipefail; mkdir -p reports; npm ci; npm test 2>&1 | tee reports/test.log'
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        if: always()
+        with:
+          name: test-reports
+          path: ci-reports/
+          if-no-files-found: warn
+```
+
+No checkout credential is needed in the guest. The secret files are outside the
+uploaded tree, and `.git` is excluded. Set a CI job limit longer than Raft's
+command deadline plus collection and cleanup grace. A forcibly terminated CI
+runner cannot perform final cleanup; check the host expiry service and inventory.
+
+## Comparison and cost
+
+[Boat's CI guide](https://docs.boat.dev/ci) uses the same broad pattern: an existing
+CI job orchestrates a disposable remote workspace. Boat also provides a managed
+`run` command, scoped API keys, renewable leases and a different VM/snapshot
+model. Raft implements a fixed lifetime on operator-owned Incus hosts and uses
+host-level SSH access; these are meaningful differences, not interchangeable
+security or billing guarantees.
+
+There is no universal “10x cheaper” claim for Raft. Compare the complete host,
+storage, idle capacity, operations and orchestration-runner cost. Standard
+GitHub-hosted runners are already free for public repositories; remote capacity
+can still help with specific hardware, prepared environments or isolation from
+other trusted jobs. See [Boat pricing](https://docs.boat.dev/pricing) and
+[GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions).

package/docs/guides/files.mdx

@@ -5,11 +5,11 @@ description: Transfer files between your controller machine and running Raft wor
 
 # File transfer
 
-Upload and download individual files between your local controller and running workspaces over verified host SSH and Incus instance APIs.
+Upload and download individual files between your controller and a box over verified host SSH and Incus instance APIs.
 
 ## Target workspace handle
 
-Commands in this guide target a running workspace. Select one from `raft list` (see [First working box](../first-box.mdx)):
+Use a running box for all examples below. Individual-file transfers also work while stopped; recursive directory transfers require a running box. Select one from `raft list` (see [First working box](../first-box.mdx)):
 
 ```sh title="CONTROLLER: Select running workspace"
 raft list

package/docs/guides/index.mdx

@@ -0,0 +1,31 @@
+---
+title: Task guides
+description: Pick a workflow after setting up your first Raft host.
+---
+
+# Task guides
+
+Start with [your first box](../first-box.mdx) if you have not run a command yet.
+Commands run on the controller unless a block is labeled **HOST**.
+
+## Develop
+
+- [Project setup and templates](./project-setup.mdx): upload a project and reuse dependencies.
+- [Docker](./docker.mdx): build images and manage guest disk use.
+- [File transfer](./files.mdx): copy individual files or directory trees.
+- [Desktop and private services](./desktop-services.mdx): open a browser, desktop or local tunnel.
+
+## Automate
+
+- [Background jobs](./background-jobs.mdx): detach, inspect logs and cancel.
+- [Lifetime and persistent services](./long-running-services.mdx): set deadlines and restart services after resume.
+- [Scripting and CI](./scripting-ci.mdx): parse output and handle failures.
+- [Disposable CI jobs — unreleased 0.7.0](./ci-jobs.mdx): run and clean up one temporary build.
+
+## Operate
+
+- [Snapshots and forks](./snapshots-forks.mdx): save disk state or make a same-host copy.
+- [Backup and recovery](./backup-recovery.mdx): move a whole box to a compatible host.
+- [Defaults and policies](./config-policy.mdx): set creation defaults and retention rules.
+- [Upgrades](./upgrades.mdx): update the CLI, host worker and image separately.
+- [Troubleshooting](./troubleshooting.mdx): start from a symptom.

package/docs/guides/long-running-services.mdx

@@ -11,7 +11,7 @@ terminal, and detached jobs do not extend that deadline automatically.
 ## Choose a lifetime and retention policy
 
 ```sh title="CONTROLLER: Create a persistent box"
-box=$(raft new --location lab --ttl 3600)
+box=$(raft new --location lab --ttl 3600 --persistent)
 ```
 
 TTL is in seconds: 60 to 2,592,000 (30 days), with a creation default of 600.

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,9 +11,28 @@ 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 |
 | --- | --- |
@@ -27,9 +46,9 @@ 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
@@ -79,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
 
@@ -108,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"
 ```

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
 ```
@@ -105,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, require box note fields or delete boxes left stopped | [Defaults and host 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
@@ -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.
 
@@ -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.