@microck/raft 0.6.0 → 0.7.0

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)
 ```
 

package/docs/reference/cli.md

@@ -8,14 +8,15 @@ 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
+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,6 +40,33 @@ 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`
@@ -140,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`
@@ -354,7 +384,7 @@ 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`
 
@@ -382,7 +412,10 @@ repair it.
 `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.
+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`
@@ -440,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`
 
@@ -507,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/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

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

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. |

package/docs/reviews/performance-audit-2026-10-29.md

@@ -0,0 +1,90 @@
+# Performance and discovery audit, 2026-10-29
+
+## Scope and execution
+
+The user approved performance fixes, confirmed dead-code removal, documentation
+corrections, a discovery-driven Raft skill, current Boat parity research, and
+verification in disposable task-owned workspaces. The follow-up request
+authorizes committing, pushing, opening a ready-for-review PR and addressing
+review feedback until ready. Production deployment, merging, releases and paid
+provisioning remain outside scope.
+Paid provisioning/research spending: not authorized.
+
+Initial checkout was clean at `1fd6d62f`; Jujutsu was initialized colocated.
+Primary agent: gpt-6-astra, high reasoning effort. Three read-only simplification
+reviewers used gpt-6.1-sol with default reasoning. All reviewer jobs are complete.
+
+## Delivered changes
+
+- List and capacity collect their data in one SSH connection per host. Doctor
+  runs its sequential checks in one connection and retains the worker lock.
+  Existing lifecycle and archive safety checks remain in place.
+- Config and doctor accept a location filter, so an unrelated offline host does
+  not prevent inspection. Location-filtered default edits are refused.
+- Command help explains behavior and operational constraints. All 38 command
+  help paths ran without configuration or writes to an empty controller home.
+- The skill teaches version/help discovery, source lookup, host inspection,
+  ownership and cleanup rather than maintaining a command/software catalog.
+  The installed skill symlink now targets this repository's canonical skill;
+  the old openboat checkout was not edited. Discovery found run in the checkout
+  while the installed 0.6.0 command tree correctly omitted it.
+- README examples select persistence explicitly and provide ownership notes.
+  Sizing, release notice timing and unreleased run status are corrected.
+- The Boat comparison was refreshed from current official documentation,
+  including team sharing, environment versions, AI proxying, telemetry,
+  automatic snapshots and retained command history.
+
+## Measurements and verification
+
+[Raw timings](../benchmarks/read-latency-2026-10-29.json) record five samples per
+command/version on the same ARM64 Incus 6.0.6 host. Median reductions were 44%
+for list, 43% for capacity and 76% for doctor. These are controller-visible read
+latencies, not boot or guest workload speedups. Update checks were disabled.
+
+Passed in the disposable workspace:
+
+- Ruff lint and format checks across all Python sources and deployment scripts.
+- Limits, image fixtures, CI orchestration and feature verifiers.
+- Self-update verification through real temporary npm and uv installations.
+- Source, wheel and npm packaging and isolated installation checks.
+- Website Oxlint, Next.js build including TypeScript, search tests, and 37-page
+  export/link/search/download verification with 52 local links.
+
+Real host checks also passed: batched versus independent native inventory and
+policy reads; doctor and config scoped away from an unreachable inventory entry;
+refusal of location-scoped controller-default edits without creating a file.
+The discovery-guided one-shot job returned exit 7, collected its result file and
+confirmed cleanup. No new mocks were introduced.
+
+The initial test source archive omitted images and Git checkout metadata.
+Correcting that disposable fixture fixed packaging and checkout-detection tests;
+no assertions were weakened. A self-update HTTP timeout fixture logged an
+expected broken pipe after its client disconnected; the verifier passed.
+
+## Cleanup and review
+
+Task-owned workspaces `paris:rf-bf5bab8180464898` and
+`paris:rf-61cc02e89fc54677` are confirmed absent. Paris inventory was empty after
+cleanup. No background verification jobs or delegates remain active.
+
+The reuse and efficiency reviewers reported no actionable findings. The quality
+reviewer found two duplicated-constant sites; both now use the existing project
+and storage constants. Superseded per-call SSH code was removed. Ruff and a
+structural/reference scan found no additional safely removable Python functions;
+graph candidates were parser callbacks, tests or framework entry points.
+
+The passive update notice still has its documented bounded wait. Removing it
+would change whether short commands display release notices. Metadata checks
+before mutations remain because they establish ownership and eligibility.
+
+## Evidence limits
+
+- Timings are a five-sample exploratory result from one host and network path.
+- Boat capabilities were checked against official documentation, not its live
+  infrastructure. Dedicated organization docs describe sharing that older
+  overview/API text still describes as creator-private; the comparison notes it.
+- Authenticated GitHub inspection confirmed v0.6.0 remains the latest published
+  release. These changes and run are development-branch work, not deployed.
+- The shared fff index returned stale and unrelated results. Exact local reads
+  and the freshly built home-ubuntu-raft graph supplied code evidence instead.
+- An unrelated configured host was unreachable; no configuration was changed.

package/docs/site-development.md

@@ -1,5 +1,6 @@
 ---
 title: Documentation site
+description: Edit, build and test the Fumadocs site without touching workspace hosts.
 ---
 
 # Documentation site

package/docs/verification.mdx

@@ -1,16 +1,18 @@
 ---
 title: Verification
+description: Read test evidence and run dedicated verification suites with explicit limits.
 ---
 
 # Verification
 
-Raft is verified using real disposable Incus workspaces, guest processes, files, Docker builds, and network connections. Tests contain no mocked services and verify Raft behavior rather than conformance with the hosted Boat service.
+Raft is verified using real disposable Incus workspaces, guest processes, files, Docker builds, and network connections. Native suites exercise real services and verify Raft behavior rather than conformance with the hosted Boat service. Separate local worker and CI-orchestration fault fixtures are labeled below; they do not establish native-host behavior.
 
 ## Verification boundaries
 
 Tests do not certify arbitrary long-running workloads, host loss, multi-tenant security boundaries, or exact Boat image/version parity. ARM64 host reboot and physical storage capacity are not certified by the AMD64 VM test. Containers share the host kernel and do not offer VM isolation.
 
-Storage accounting covers shared pools rather than per-box quotas. Large backup transfers hold the host lifecycle lock, which delays expiration checks.
+Shared-pool boxes have no per-box quota. Own-disk boxes have enforced ext4 limits
+and reservation accounting; the coverage matrix distinguishes both modes. Large backup transfers hold the host lifecycle lock, which delays expiration checks.
 
 ## Coverage matrix
 
@@ -34,7 +36,7 @@ Storage accounting covers shared pools rather than per-box quotas. Large backup
 | Development image | Real developer-user tool checks, immutable selection and credential-path archive rejection |
 | Deployment/firewall | Repeat deployment removes stale rules without restarting Incus; failed filtering blocks normal and socket startup; boot timestamps prove filtering precedes Incus |
 | Storage contract | Disposable oversized pool is rejected without automatic resizing |
-| CLI options and errors | Help for all 34 commands and `host add`; default location, TTL and desktop port; all eight sizing profiles; global and per-location reports; invalid TTLs, sizes, required arguments, handles, paths, snapshot names, jobs and ports |
+| CLI options and errors | Command help, including `run` and `host add`; default location, TTL and desktop port; all eight sizing profiles; global and per-location reports; invalid TTLs, sizes, required arguments, handles, paths, snapshot names, jobs and ports |
 
 ## Command and option audit (2026-10-06)
 
@@ -241,3 +243,19 @@ On 2026-10-06, `raft limits` (since renamed `raft capacity`, with the admission
 Allocation fixtures validated mixed sizing budgets, frozen containers, low RAM and disk conditions, host reserves, and admission limits. The four-stopped-box admission test verified that creation, forking, and recovery reject a fifth container when slots are exhausted. These are conservative allocation checks, not workload saturation benchmarks.
 
 </details>
+
+## Disposable CI command verification
+
+`python3 deploy/verify-run.py` runs explicit orchestration fault-injection tests,
+real Linux signal/deadline handling, real Git filtering and safe archive traversal,
+and the actual ownership-check cleanup program against an isolated fake Incus
+executable. These are not native-host evidence. They cover failed/uncertain
+creation, upload failures, nonzero payload preservation, artifacts, cleanup
+failures, cancellation, timeouts, existing destinations and ignored credentials.
+
+`python3 deploy/verify-run.py --location lab` additionally creates real temporary
+boxes on the explicitly selected host, uploads a source tree, executes successful
+and failing commands, retrieves result directories, checks timeout cleanup and
+compares the host inventory before/after. Native AMD64 and ARM64 image CI runs
+this suite. A new PR must have those actual runs pass before claiming native
+verification; local fault-injection success alone does not establish it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microck/raft",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Self-hosted Linux workspaces powered by Incus, an open-source alternative to boat.dev",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,8 @@
   "files": [
     "raft.py",
     "raft_files.py",
+    "raft_run.py",
+    "raft_jobs.py", "raft_output.py",
     "deploy/*.py",
     "deploy/*.sh",
     "deploy/*.conf",