@microck/raft 0.2.0 → 0.3.0

package/docs/operations.mdx

@@ -9,6 +9,30 @@ Set up a dedicated Ubuntu host, install the Raft CLI, provision Incus, acquire a
 
 Review prerequisites in [System requirements](./requirements.mdx) before starting.
 
+## Guided onboarding
+
+Install the CLI from npm on your Linux controller, confirm key-based SSH to the
+host, then let `raft host add` do the remaining steps:
+
+```sh title="CONTROLLER: Onboard a host"
+npm install -g @microck/raft@0.3.0
+ssh ubuntu@192.0.2.10 true
+raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
+raft host add lab --ssh ubuntu@192.0.2.10
+```
+
+The dry run checks the host without changing it and prints the plan. The second
+command shows the same plan, asks for confirmation, provisions Incus, imports the
+checksum-verified release image, adds `lab` to `~/.config/raft/incus.json`, and
+finishes with `raft doctor` and a disposable smoke test. Unsupported hosts,
+including macOS, are rejected before any change; run an Ubuntu VM and onboard
+that instead. See [`host add`](./reference/cli.md#host-add) for image options.
+
+## Manual setup
+
+The steps below are what `raft host add` automates. Follow them to inspect or
+customize each stage.
+
 <Steps>
 
 <Step>
@@ -33,18 +57,31 @@ sudo -n true && echo "Passwordless sudo is functional"
 
 <Step>
 
-### Clone repository and install controller CLI
+### Install the CLI and obtain deployment scripts
 
-On your controller machine, clone the repository and install the `raft` CLI tool using `uv`:
+On your Linux controller with Python 3.11.8+, install the published CLI:
 
-```sh title="CONTROLLER: Clone repository and install CLI"
-git clone https://github.com/Microck/raft.git raft
+```sh title="CONTROLLER: Install published CLI"
+npm install -g @microck/raft@0.3.0
+raft --version
+```
+
+Installation does not configure hosts or download images. Clone the matching
+release to obtain the deployment scripts and example configuration:
+
+```sh title="CONTROLLER: Obtain deployment scripts"
+git clone --branch v0.3.0 https://github.com/Microck/raft.git raft
 cd raft
+```
+
+Alternatively, install from that checkout using `uv` instead of npm:
+
+```sh title="CONTROLLER: Clone repository and install CLI"
 uv sync --locked
 uv tool install --editable .
 ```
 
-Add `~/.local/bin` to `PATH` and verify the CLI:
+For the `uv` installation, add `~/.local/bin` to `PATH` and verify the CLI:
 
 ```sh title="CONTROLLER: Verify CLI installation"
 export PATH="$HOME/.local/bin:$PATH"
@@ -122,16 +159,16 @@ Workspaces require an unprivileged Debian 13 development image matching the host
 
 <Tab value="Download release image">
 
-Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). The `sha256sum` check gates import so corrupted archives are rejected:
+Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.3.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
 
 <Tabs items={["ARM64", "AMD64"]}>
 
 <Tab value="ARM64">
 
 ```sh title="HOST (ARM64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/raft-dev-arm64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/manifest-arm64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/raft-dev-arm64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/manifest-arm64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev
@@ -142,9 +179,9 @@ sha256sum --ignore-missing -c SHA256SUMS && \
 <Tab value="AMD64">
 
 ```sh title="HOST (AMD64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/raft-dev-amd64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.1.0/manifest-amd64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/raft-dev-amd64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.3.0/manifest-amd64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-amd64.tar.gz --alias raft-dev
@@ -222,3 +259,5 @@ Check that Incus, the network service, and the expiration timer are active. For
 ## Next step
 
 Proceed to [First working box](./first-box.mdx) to launch, verify, and manage your first workspace.
+
+For later releases, follow [Upgrades and image changes](./guides/upgrades.mdx).

package/docs/reference/capacity-limits.mdx

@@ -18,7 +18,7 @@ raft limits
 raft limits --location lab --json
 ```
 
-The output displays host CPU count, total RAM, configured limits, available RAM, disk headroom, and advisory recommendations across all six sizing profiles:
+The output displays host CPU count, total RAM, configured limits, available RAM, disk headroom, and advisory recommendations across all eight sizing profiles:
 
 ### Illustrative host sizing
 
@@ -48,9 +48,18 @@ Operating systems report less usable RAM than advertised hardware size. Near siz
 Select CPU and memory limits when launching with `raft new`:
 
 - `--cpu`: `1` or `2` shared vCPUs managed by Incus (default: `1`).
-- `--memory`: `1GiB`, `2GiB`, or `4GiB` cgroup limit (default: `2GiB`).
+- `--memory`: `1GiB`, `2GiB`, `4GiB`, or `8GiB` cgroup limit (default: `2GiB`). An 8 GiB box needs at least 10 GiB of usable host RAM before `raft limits` recommends running one; like other recommendations, this is advisory and not enforced.
 
-Resizing existing containers or modifying limits upon resume is not supported.
+Change supported CPU/RAM limits when resuming a stopped box or creating a fork:
+
+```sh
+raft resume "$box" --ttl 1800 --cpu 2 --memory 4GiB
+copy=$(raft fork "$box" --ttl 1800 --memory 2GiB)
+```
+
+Resume requires a stopped box; fork requires a stopped source. Omitted limits
+stay unchanged on resume and inherit the source limits on fork. Live resizing is
+not exposed by the CLI. See [Snapshots and forks](../guides/snapshots-forks.mdx).
 
 ## Host resource reserves and active states
 

package/docs/reference/cli.md

@@ -10,6 +10,10 @@ Command-line reference for the `raft` controller tool.
 Syntax:
 `raft <subcommand> [options] [arguments]`
 
+`raft --help` lists commands, `raft <subcommand> --help` lists its arguments,
+and `raft --version` prints the installed version without loading configuration.
+Output is command-specific; see [Scripting and CI](../guides/scripting-ci.mdx).
+
 Workspaces are referenced by location-qualified handles formatted as `<location>:<instance-name>` (for example `lab:rf-a1b2c3d4e5f60718`).
 
 ## Command index
@@ -23,6 +27,7 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 | 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) |
+| Locations | [`host add`](#host-add), [`locations`](#locations), [`note`](#note) |
 | Host inspection and maintenance | [`limits`](#limits), [`doctor`](#doctor), [`list`](#list), [`gc`](#gc), [`prune`](#prune) |
 
 ## Workspace lifecycle commands
@@ -31,17 +36,18 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 
 Create and launch a new workspace container.
 
-`raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB}]`
+`raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--disposable] [--from LOCATION:BOX/SNAPSHOT]`
 
 - `--location LOCATION`: Target host location in `~/.config/raft/incus.json`. Defaults to first configured location.
 - `--ttl TTL`: Lifetime in seconds before automatic stop (`60` to `2592000`). Default: `600`.
 - `--cpu {1,2}`: CPU core count managed by Incus. Default: `1`.
-- `--memory {1GiB,2GiB,4GiB}`: Memory limit. Default: `2GiB`.
+- `--memory {1GiB,2GiB,4GiB,8GiB}`: Memory limit. Default: `2GiB`.
 
 - `--disposable`: Delete the box and snapshots on stop or expiry. Off by default.
 - `--from LOCATION:BOX/SNAPSHOT`: Copy a named snapshot on its source host instead of the configured image. Normal creation sizing applies; the source can be running. Cannot target a different location.
 
-Returns the qualified workspace handle.
+Returns the qualified workspace handle. If the location has a note, `new` prints
+it to stderr; stdout still contains only the handle.
 
 ### `stop`
 
@@ -55,10 +61,13 @@ Terminates guest processes and stops the container. Persistent boxes retain file
 
 Start a stopped workspace with a renewed lifetime deadline.
 
-`raft resume <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB}]`
+`raft resume <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}]`
 
 - `--ttl TTL`: Lifetime in seconds from resumption (`60` to `2592000`). Required.
 
+CPU/RAM overrides on resume apply before startup. Omitted values stay unchanged.
+A running box is rejected before changing its limits.
+
 ### `extend`
 
 Reset the expiration deadline for a running workspace without restarting it.
@@ -75,8 +84,6 @@ Permanently delete a workspace container and its snapshots.
 
 Stops the container if running, removes all associated Btrfs snapshots, and releases host storage.
 
-CPU/RAM overrides on resume apply before startup. Omitted values stay unchanged. A running box is rejected before changing its limits.
-
 ## Execution and inspection commands
 
 ### `exec`
@@ -189,7 +196,7 @@ Roll back a stopped workspace filesystem to a named snapshot using `--diskonly`,
 
 Clone a stopped workspace into an independent container on the same host and start it.
 
-`raft fork <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB}] [--disposable]`
+`raft fork <box> --ttl TTL [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--disposable]`
 
 - `--ttl TTL`: Lifetime in seconds for the clone. Required.
 
@@ -239,6 +246,60 @@ Import a portable backup archive onto a host as a fresh stopped workspace.
 
 Returns the qualified handle of the imported stopped workspace.
 
+## Location commands
+
+### `host add`
+
+Check, provision and register a new workspace host, then prove it works.
+
+`raft host add LOCATION --ssh TARGET [--image-release TAG | --image-archive PATH | --build] [--dry-run] [--yes]`
+
+- `LOCATION`: New location name. Existing locations are rejected.
+- `--ssh TARGET`: Key-based SSH target, such as `ubuntu@192.0.2.10` or an `~/.ssh/config` alias. Accept the host key interactively first.
+- `--image-release TAG`: Download `raft-dev-<arch>.tar.gz` from this release on the host and verify it against the release `SHA256SUMS`. Default: the CLI's own version.
+- `--image-archive PATH`: Upload and import a local image archive instead.
+- `--build`: Build the image on the host from Debian 13 instead.
+- `--dry-run`: Probe the host and print the plan without changing anything.
+- `--yes`: Apply the plan without the interactive prompt. Without a terminal, `--yes` is required.
+
+Before any change, a read-only probe checks SSH, passwordless sudo, Ubuntu 22.04 or
+24.04, ARM64 or AMD64, python3, at least 2 CPUs, 8 GiB RAM and, for a fresh host,
+80 GiB free disk. Unsupported targets, including macOS, fail with the reasons and
+no changes. The command then runs the deployer, imports the image only if its
+checksum and architecture match, adds the location with the pinned fingerprint,
+and runs `doctor` plus a disposable create/exec/destroy smoke test. If the final
+checks fail, it removes the location again; host changes remain and a rerun
+reuses them.
+
+```sh title="CONTROLLER: Onboard a host"
+raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
+raft host add lab --ssh ubuntu@192.0.2.10
+```
+
+The deployment files ship in the npm package and source checkouts. The Python
+wheel contains only the CLI; use npm or a checkout to onboard hosts.
+
+### `locations`
+
+List configured locations without contacting hosts.
+
+`raft locations`
+
+Prints one JSON object per location (JSONL) in configuration order, with
+`location`, `default` and `note` fields. `default` is true for the location that
+`new` uses without `--location`. `note` is empty when none is set.
+
+### `note`
+
+Set or clear operator guidance for a location in `~/.config/raft/incus.json`.
+
+`raft note LOCATION TEXT`
+`raft note LOCATION --clear`
+
+Notes are advisory. Use them to record which host is preferred or what a host
+should not run. Raft shows notes in `locations`, `limits` and `new` but does not
+enforce them. Empty notes are rejected; use `--clear` to remove one.
+
 ## Host inspection and maintenance commands
 
 ### `limits`
@@ -250,9 +311,11 @@ Inspect host resource capacity, active allocations, and recommended workspace li
 - `--location LOCATION`: Filter report to a specific host.
 - `--json`: Output report as JSON.
 
+Each report includes the location's `note`, if any.
+
 ### `doctor`
 
-Inspect host connectivity, Incus version, active systemd units (`incus`, `raft-expire.timer`, `raft-network.service`), root filesystem usage, storage pool status, and saved box count across configured hosts.
+Inspect host connectivity, Incus version, expiry-worker compatibility, active systemd units (`incus`, `raft-expire.timer`, `raft-network.service`), root filesystem usage, storage pool status, and saved box count across configured hosts. An incompatible worker returns a nonzero exit status and names the failing location without running expiry or modifying boxes.
 
 `raft doctor`
 
@@ -262,6 +325,10 @@ List existing workspace containers across configured hosts.
 
 `raft list [--location LOCATION]`
 
+Prints one JSON object per box (JSONL), with `box`, `state`, and `stopAt` fields.
+An empty inventory prints no records. See [Scripting and CI](../guides/scripting-ci.mdx)
+for output formats, exit codes, readiness, and failure handling.
+
 ### `gc`
 
 Enforce deadlines immediately. Persistent boxes stop; disposable boxes are deleted.

package/docs/reference/configuration.mdx

@@ -27,7 +27,8 @@ The configuration file maps location names to host definition objects:
 {
   "lab": {
     "ssh": "ubuntu@192.0.2.10",
-    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    "image": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "note": "Preferred for builds"
   },
   "remote-builder": {
     "ssh": "builder.example.com",
@@ -39,7 +40,7 @@ The configuration file maps location names to host definition objects:
 ### Location keys
 
 - **Naming format**: Matches `^[a-zA-Z0-9][a-zA-Z0-9_-]*$`. Starts with an alphanumeric character and contains ASCII letters, digits, underscores, or hyphens.
-- **Default location**: The first location listed is the default for `raft new`. `raft list` and `raft limits` accept `--location` filters; `raft doctor` and `raft gc` check all configured hosts.
+- **Default location**: The first location listed is the default for `raft new`. `raft list`, `raft limits`, `raft gc`, and `raft prune` accept `--location` filters. Without a filter they check all configured hosts; `raft doctor` always checks all configured hosts.
 
 ### Host entry fields
 
@@ -47,6 +48,19 @@ The configuration file maps location names to host definition objects:
 | :--- | :--- | :--- | :--- |
 | `ssh` | `string` | Yes | Non-empty SSH connection string (IP, `user@host`, or SSH host alias from `~/.ssh/config`). |
 | `image` | `string` | For `raft new` only | Full 64-character hexadecimal SHA-256 fingerprint (`^[a-f0-9]{64}$`). An empty string `""` is allowed during initial host provisioning. |
+| `note` | `string` | No | Operator guidance for choosing this location, such as `Preferred for builds` or `Do not use for Docker`. Raft shows notes but never enforces them. |
+
+Set or clear notes with `raft note` instead of editing the file by hand:
+
+```sh title="CONTROLLER: Record location guidance"
+raft note lab "Preferred for builds"
+raft note spare "Do not use for Docker builds"
+raft locations
+raft note spare --clear
+```
+
+`raft note` rewrites the file with two-space indentation, keeps location order and
+mode `0600`. `raft locations`, `raft limits` and `raft new` show the note.
 
 <Callout type="warn" title="Replace placeholder image fingerprint">
 The `image` field requires the full 64-character hash for `raft new`; aliases such as `raft-dev` are rejected. Replace the example hash with the actual imported image fingerprint for that host.

package/docs/releases/0.2.1.md

@@ -0,0 +1,14 @@
+---
+title: Raft 0.2.1
+---
+
+# Raft 0.2.1
+
+- `raft doctor` now rejects an incompatible host expiry worker and identifies the location that needs deployment. It does not run expiry or change boxes.
+- Lifecycle transactions close controller stdin so allocation cannot wait for piped input while holding the host lock.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.2.1`, or install the attached Python wheel. Updating the CLI does not update host workers. Deploy the matching checkout to hosts that fail the readiness check.
+
+Exec, SSH, and file-transfer behavior is unchanged. Piped input to `raft exec` is unsupported.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/docs/releases/0.3.0.md

@@ -0,0 +1,15 @@
+---
+title: Raft 0.3.0
+---
+
+# Raft 0.3.0
+
+- `raft host add LOCATION --ssh TARGET` onboards a host from the CLI. It checks the host read-only first and rejects unsupported targets such as macOS, shows the exact plan, and asks before changing anything (`--dry-run` previews, `--yes` skips the prompt). It provisions Incus, imports a checksum-verified release image (or `--image-archive` / `--build`), pins the fingerprint, and finishes with `doctor` and a disposable smoke test. A failed final check removes the new location again.
+- Boxes can use 8 GiB RAM: `new`, `resume` and `fork` accept `--memory 8GiB`, and `raft limits` reports recommendations for it. An 8 GiB box needs at least 10 GiB of usable host RAM before `limits` recommends running one.
+- Locations accept an optional `note` for operator guidance, such as which host is preferred or what a host should not run. `raft note LOCATION TEXT` sets it and `raft note LOCATION --clear` removes it.
+- `raft locations` lists configured locations as JSONL with their default status and note, without contacting hosts.
+- `raft limits` includes each location's note, and `raft new` prints the target location's note to stderr. Notes are advisory and never block allocation.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.3.0`, or install the attached Python wheel. Notes live in the controller configuration; host workers are unchanged and need no redeployment. Host onboarding needs the npm package or a source checkout because the Python wheel does not ship the deployment files.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/docs/requirements.mdx

@@ -19,6 +19,8 @@ Each workspace host must be a dedicated physical machine or virtual instance:
 | **RAM** | At least 8 GiB | Sizing calculations reserve the larger of 2 GiB or 10% of host RAM (an advisory estimate, not an enforced host reservation). |
 | **Free disk** | At least 80 GiB on host disk | The deployer provisions a 60 GiB dedicated Btrfs pool (`raft-data`). |
 
+`raft host add` checks these requirements read-only before it changes a host.
+
 Host CPU and RAM reserves are advisory estimates for `raft limits`, not enforced cgroup locks.
 
 <Callout type="warn" title="Dedicated host requirement">

package/docs/verification.mdx

@@ -33,7 +33,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 28 commands; default location, TTL and desktop port; all six sizing profiles; global and per-location reports; invalid TTLs, sizes, required arguments, handles, paths, snapshot names, jobs and ports |
+| CLI options and errors | Help for all 31 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 |
 
 ## Command and option audit (2026-10-06)
 
@@ -57,9 +57,15 @@ The [final runtime validation](https://github.com/Microck/raft/actions/runs/3754
 
 ## New workspace controls
 
-`python3 deploy/verify-features.py --location lab` verifies recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, and retention preview/apply. It uses only its own fixtures. Run the archive checks without `--location` to avoid allocating boxes.
+`python3 deploy/verify-features.py --location lab` verifies `doctor` readiness against the installed worker, recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, and retention preview/apply. It uses only its own fixtures. Run the archive checks without `--location` to avoid allocating boxes.
 
-For an older deployment whose services should stay unchanged, `--isolated-worker` stages the current worker under a private temporary path. This checks worker logic without installing it; automatic timer integration is verified on disposable CI hosts. Current deployments use the normal verification mode; the isolated mode rejects them before allocation.
+The live suite also holds a controller stdin pipe open while running real remote
+readers through both captured and streamed lifecycle transactions. Both must
+receive EOF without consuming controller input, and a subsequent transaction
+must acquire the same host lock. This covers allocation stalls caused by Incus
+waiting for stdin while the expiration worker waits for the lifecycle lock.
+
+For an older deployment whose services should stay unchanged, `--isolated-worker` first verifies that `doctor` rejects the stale installed worker with a location-specific deployment diagnostic, then uses the current worker under a private temporary path. This checks worker logic without installing it; automatic timer integration is verified on disposable CI hosts. Current deployments use the normal verification mode; the isolated mode rejects them before allocation.
 
 ## Workspace controls validation (2026-10-07)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microck/raft",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Self-hosted Linux workspaces powered by Incus, an open-source alternative to boat.dev",
   "license": "MIT",
   "repository": {