@microck/raft 0.4.0 → 0.6.0

package/docs/guides/troubleshooting.mdx

@@ -22,19 +22,19 @@ raft doctor
 - Compatibility of the installed expiry worker with the CLI
 - Active status of host systemd services (`incus`, `raft-expire.timer`, `raft-network.service`)
 - Host root filesystem disk usage (`df -h /`)
-- Status and usage of the `raft-data` Btrfs pool
+- Status and usage of the shared `raft-data` Btrfs pool, and of the `raft-disks` LVM thin pool when own box disks are enabled (otherwise `own box disks: not enabled (redeploy with --disk-pool SIZE)`)
 - Count of existing saved containers
 
 <Callout type="info" title="Doctor scope">
-`raft doctor` reports runtime daemon, expiry-worker compatibility, and storage status. It does not validate image fingerprints, inspect nftables bridge rules, enforce admission caps, or emit 5 GiB low-disk warnings.
+`raft doctor` reports runtime daemon, expiry-worker compatibility, and storage status. It does not validate image fingerprints, inspect nftables bridge rules, or emit 5 GiB low-disk warnings. A host without `raft-disks` is healthy: own box disks are opt-in.
 </Callout>
 
 ### Expiry worker differs from the CLI
 
 An active expiration timer can still run an older worker. Installing or updating
 the controller CLI does not deploy host code. `doctor` checks the same worker
-protocol as disposable creation and retention cleanup, without running expiry or
-changing any boxes. It exits nonzero and names the location on a mismatch.
+protocol as disposable creation, prune and setting a retention policy, without
+running expiry or changing any boxes. It exits nonzero and names the location on a mismatch.
 
 Review the host deployment changes, then deploy from the checkout matching your
 CLI. Replace `lab` with the location reported by the diagnostic:
@@ -106,6 +106,23 @@ files and snapshots. Expired disposable containers are deleted, including their
 snapshots. Use `raft gc --location lab` to check only one host. The timer normally
 checks every 15 seconds; host outages, graceful shutdown and long locked
 operations can delay expiry. See [Lifetime and persistent services](./long-running-services.mdx).
+`raft gc` also applies the location's stopped-box retention.
+
+### A stopped box disappeared
+
+A host retention policy deletes boxes left stopped for its hours. Check the
+policy and the host journal, which records every deletion:
+
+```sh title="CONTROLLER: Check retention"
+raft config | jq '.policy'
+```
+
+```sh title="HOST: Find the deletion"
+sudo journalctl -t raft | grep 'Deleted box'
+```
+
+Deleted boxes cannot be recovered except from a `raft backup` archive. See
+[Defaults and host policies](./config-policy.mdx#delete-boxes-left-stopped).
 
 ## Common error scenarios
 
@@ -120,13 +137,25 @@ The configuration file contains valid JSON that is `{}` or is not an object (an
 #### "Build an image and configure its full immutable fingerprint before creating boxes"
 The `image` field is missing or is not a 64-character hexadecimal SHA-256 fingerprint. Supply the full fingerprint from `sudo incus --project raft image list raft-dev --format json`.
 
-### Admission and capacity errors
+### Sizing and disk errors
+
+Raft has no box count limit and no size budget. These errors come from the
+request itself or from the host:
+
+#### "Requested N CPUs, but this host has M" or "Requested SIZE RAM, but this host has N GiB"
+The request is larger than the whole host. Ask for at most the host's CPUs and RAM; `raft capacity` shows both.
+
+#### "LOCATION has no raft-disks pool, so own box disks are not enabled there"
+Own box disks are opt-in and this host was deployed without them. Nothing was created. Enable them with `python3 deploy/deploy.py --location <location> --disk-pool SIZE`, which needs SIZE plus 20 GiB free on the host, or create the box without `--disk`. Boxes without `--disk` keep working meanwhile.
+
+#### "own box disks would need N GiB more of raft-disks"
+Each own disk, each snapshot of one, and the cached image reserve their full size in `raft-disks`, so Raft refused the request before creating anything. Destroy own-disk boxes or snapshots you no longer need, choose a smaller `--disk`, or use the shared pool. `raft capacity` shows the unreserved space. See [Reservation accounting](../reference/capacity.mdx#reservation-accounting).
 
-#### "Location already holds four boxes"
-Raft enforces a hard limit of four saved boxes per location. Both running and stopped containers count toward this limit. Destroy unused boxes with `raft destroy <box>` before creating, forking, or recovering a box.
+#### "No space left on device" inside an own-disk box
+The box filled its own disk. Delete files or Docker data inside the box. For a persistent box you can also move to a larger disk: stop it with `raft stop "$box"` (snapshots need a stopped box), take `raft snapshot "$box" <snapshot>`, then create the copy with `raft new --from "$box/<snapshot>" --disk <larger size>`. Do not stop a `--disposable` box for this: stopping deletes it.
 
 #### Low disk warnings
-`raft limits` warns when free space on host disk or the `raft-data` pool falls below 5 GiB. This warning is diagnostic and does not halt container operations. Clean up dangling images, old snapshots, or unused containers to free space.
+`raft capacity` warns when free space on host disk or the `raft-data` pool falls below 5 GiB. This warning is diagnostic and does not halt container operations. Clean up dangling images, old snapshots, or unused containers to free space.
 
 ### Network and forwarding issues
 

package/docs/guides/upgrades.mdx

@@ -10,7 +10,7 @@ parts of Raft. Updating one does not automatically update the others.
 
 | Component | Update method | Effect on existing boxes |
 | --- | --- | --- |
-| Controller CLI | Install the chosen npm or Python release | Changes controller commands; does not rewrite guest files |
+| Controller CLI | `raft self-update`, or install the chosen npm or Python release | Changes controller commands; does not rewrite guest files |
 | Host worker and firewall | Run the chosen release's deployer per host | Replaces host policy code and reapplies filtering |
 | Pinned development image | Import an image and change the configuration fingerprint | Used for future image-based `new`; existing boxes keep their files |
 
@@ -33,7 +33,14 @@ stopping one. Schedule redeployment when interruptions are acceptable.
 
 ## Update the controller
 
-For an npm installation:
+`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
+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
+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
@@ -54,7 +61,10 @@ and check which executable your shell uses with `command -v raft`.
 
 For an editable source installation, updating the checkout changes the installed
 tool's source. Keep uncommitted work separate and run `uv sync --locked` for the
-chosen checkout. Raft has no `self-update` command.
+chosen checkout. `self-update` refuses source checkouts.
+
+Updating the CLI changes no host. Continue below, and run `raft doctor` first: it
+reports each host whose worker differs from the new CLI.
 
 ## Redeploy each host
 
@@ -74,8 +84,10 @@ timer. It does not import an image or migrate guest files.
 
 Do not bypass a conflicting-resource or storage-size error. Inspect the host and
 preserve backups before explicit recovery; redeployment does not repair arbitrary
-infrastructure drift. Disposable creation/fork and prune check the worker protocol
-and fail if it differs from the CLI. That check is not an automatic upgrade.
+infrastructure drift. Disposable creation/fork, prune and setting a retention
+policy check the worker protocol and fail if it differs from the CLI. That check
+is not an automatic upgrade. Raft 0.6.0 raised the protocol for stopped-box
+retention, so hosts deployed by an earlier release need this redeploy.
 
 ## Replace the image pin
 

package/docs/index.mdx

@@ -33,6 +33,7 @@ Stopping a workspace preserves files and packages on disk. Resuming resets its r
 | 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) |

package/docs/operations.mdx

@@ -15,7 +15,7 @@ Install the CLI from npm on your Linux controller, confirm key-based SSH to the
 host, then let `raft host add` do the remaining steps:
 
 ```sh title="CONTROLLER: Onboard a host"
-npm install -g @microck/raft@0.4.0
+npm install -g @microck/raft@0.6.0
 ssh ubuntu@192.0.2.10 true
 raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
 raft host add lab --ssh ubuntu@192.0.2.10
@@ -44,7 +44,7 @@ Connect to your host over SSH, verify its host key fingerprint, and install base
 ```sh title="HOST: Install baseline system packages"
 sudo apt-get update
 sudo apt-get install -y --no-install-recommends \
-  ca-certificates curl gnupg python3 openssh-server iptables btrfs-progs
+  ca-certificates curl gnupg python3 openssh-server iptables btrfs-progs lvm2 python3-yaml
 ```
 
 Verify passwordless `sudo` on the host:
@@ -62,7 +62,7 @@ sudo -n true && echo "Passwordless sudo is functional"
 On your Linux controller with Python 3.11.8+, install the published CLI:
 
 ```sh title="CONTROLLER: Install published CLI"
-npm install -g @microck/raft@0.4.0
+npm install -g @microck/raft@0.6.0
 raft --version
 ```
 
@@ -70,7 +70,7 @@ Installation does not configure hosts or download images. Clone the matching
 release to obtain the deployment scripts and example configuration:
 
 ```sh title="CONTROLLER: Obtain deployment scripts"
-git clone --branch v0.4.0 https://github.com/Microck/raft.git raft
+git clone --branch v0.6.0 https://github.com/Microck/raft.git raft
 cd raft
 ```
 
@@ -132,15 +132,17 @@ Run the automated host deployer from your controller:
 
 ```sh title="CONTROLLER: Provision host infrastructure"
 python3 deploy/deploy.py --location lab
+# Optional: enable own box disks with a pool of this size, now or on any later redeploy
+python3 deploy/deploy.py --location lab --disk-pool 100GiB
 ```
 
 <details>
 <summary>Infrastructure created by the deployer</summary>
 
 The deployer runs over SSH and configures the host:
-1. Installs Incus 6.0 LTS and nftables packages.
+1. Installs Incus 6.0 LTS, LVM, nftables and python3-yaml packages.
 2. Creates the isolated `raft` Incus project.
-3. Creates a 60 GiB Btrfs storage pool (`raft-data`).
+3. Creates the shared 60 GiB Btrfs storage pool (`raft-data`). With `--disk-pool SIZE`, also creates the LVM thin pool for [own box disks](./reference/capacity.mdx#own-box-disks) (`raft-disks`) of SIZE, allocates its file on the host disk in full and stops it passing discards to that file. Without `--disk-pool` own box disks stay disabled, which is a healthy state. A later redeploy with `--disk-pool` adds the pool; no redeploy resizes either pool.
 4. Creates private bridge interface `rfbr0` (`10.232.0.1/24`) with NAT.
 5. Configures nftables bridge filters to block inter-workspace traffic and restrict host access.
 6. Installs and enables `raft-network.service` and `raft-expire.timer` units.
@@ -159,16 +161,16 @@ Workspaces require an unprivileged Debian 13 development image matching the host
 
 <Tab value="Download release image">
 
-Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.4.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
+Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.6.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
 
 <Tabs items={["ARM64", "AMD64"]}>
 
 <Tab value="ARM64">
 
 ```sh title="HOST (ARM64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.4.0/raft-dev-arm64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.4.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.4.0/manifest-arm64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/raft-dev-arm64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/manifest-arm64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev
@@ -179,9 +181,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.4.0/raft-dev-amd64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.4.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.4.0/manifest-amd64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/raft-dev-amd64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/manifest-amd64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-amd64.tar.gz --alias raft-dev
@@ -260,4 +262,4 @@ Check that Incus, the network service, and the expiration timer are active. For
 
 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).
+For later releases, run `raft self-update` and follow [Upgrades and image changes](./guides/upgrades.mdx).

package/docs/reference/capacity.mdx

@@ -0,0 +1,198 @@
+---
+title: Box sizing and capacity
+description: Size boxes for the task, give them their own disks, and read the advisory host capacity estimate.
+---
+
+# Box sizing and capacity
+
+<Callout type="info" title="Advisory estimate only">
+Raft enforces no box count or size budget. Create the boxes your task needs, sized for the work. `raft capacity` is planning advice, never a reason to skip a box.
+</Callout>
+
+## Sizing a box
+
+Choose CPU, RAM and disk when you run `raft new`:
+
+- `--cpu N`: any whole number of CPUs, from `1` up to the host's CPU count (default: `1`). Boxes share host CPUs, so a limit is a ceiling, not a reservation.
+- `--memory SIZE`: any whole number of GiB, such as `3GiB` or `32GiB`, up to the host's RAM (default: `2GiB`). This is the box's cgroup memory limit.
+- `--disk SIZE`: give the box its own disk instead of the shared pool, on hosts that enable own box disks. See [Own box disks](#own-box-disks).
+
+A box from the image starts from these defaults, or from the controller's
+[`config.json` defaults](../guides/config-policy.mdx#defaults-for-new) when set.
+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")
+```
+
+A CPU or RAM request larger than the whole host fails before anything is
+created, because Incus would accept it and quietly give the box less:
+
+```text
+Requested 64 CPUs, but this host has 8
+```
+
+Change CPU and RAM when you resume a stopped box or fork one:
+
+```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 values
+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).
+
+## Own box disks
+
+By default every box stores its files in the shared 60 GiB Btrfs pool
+`raft-data`. Boxes there grow until the pool is full, and Btrfs quotas cannot
+hold them back: Docker and other tools create nested subvolumes that escape
+Btrfs quotas.
+
+`raft new --disk SIZE` gives the box its own disk instead: an LVM thin volume
+of SIZE with an ext4 filesystem in the `raft-disks` pool. Everything the box
+writes, including Docker images, layers and container files, lands in that
+filesystem, so the box gets "No space left on device" at SIZE and cannot touch
+other boxes' space. Raft reserves the whole SIZE in the pool when the box is
+created, so other boxes cannot take it either.
+
+Own box disks are opt-in per host. A host deployed without `--disk-pool` has no
+`raft-disks` pool, which is a normal, healthy state: `raft doctor` and
+`raft capacity` say own box disks are not enabled, and `new --disk` fails before
+creating anything with the command that enables them.
+
+- **Size**: whole GiB, such as `20GiB`. The development image holds about 5 GiB of files, so give boxes at least `8GiB`; a disk too small for the image fails at creation and leaves nothing behind. Disks of 10 GiB or more start fastest: smaller ones are shrunk after the copy. ext4 keeps a little of the volume for itself, so `df` shows slightly less than SIZE.
+- **Copy-on-write**: a new own-disk box starts as a thin snapshot of the image, and forks, templates (`new --from`) and snapshots of own-disk boxes are thin snapshots of their source. They are created in seconds and share the source's blocks until they write their own.
+- **Reservations**: each own disk, and each snapshot of one, reserves its full size in the pool, even though it shares blocks. A request that would reserve more than the pool holds fails before anything is created. See [Reservation accounting](#reservation-accounting).
+- **Forks, templates and backups**: `fork` and `new --from` keep the source disk, shared or own, with the same size. `new --from BOX/SNAPSHOT --disk SIZE` copies a snapshot onto an own disk of a new size. `recover` puts an own-disk backup back onto an own disk of the same size, and needs the pool on the destination. Resume never changes the disk.
+- **Inspection**: `raft list` reports `disk` as `"shared"` or the size; `raft info` shows it in `expanded_devices.root`; `raft usage` reports the filesystem's space with a `filesystemScope` of `own SIZE box disk`.
+
+### Enabling the `raft-disks` pool
+
+Pass `--disk-pool SIZE` to `raft host add`, or to
+`python3 deploy/deploy.py --location LOCATION` on a host that is already
+deployed. The deployer creates `raft-disks` beside `raft-data`: a loop-backed
+LVM thin pool (`lvm.use_thinpool=true`) of SIZE. It allocates the pool's file on
+the host disk in full, so every reservation is backed by real host space, and
+it sets the thin pool to `--discards nopassdown`, so freed blocks return to the
+pool without punching holes back into that file. A fresh host then needs 80 GiB
+plus SIZE free; adding the pool later needs SIZE plus 20 GiB free.
+
+Redeploying never resizes the pool: an explicit `--disk-pool` that differs from
+the existing size is refused, and omitting it keeps the pool as it is. To change
+the size, back up the own-disk boxes, delete them, remove the pool explicitly
+with Incus and redeploy.
+
+### Reservation accounting
+
+A thin pool can promise its volumes more space than it holds, and when it fills
+up every volume in it fails at once. Raft never lets that happen. A thin volume
+can never hold more data than its own size, so as long as the sizes of all thin
+volumes in the pool add up to no more than the pool's data space, the pool
+cannot fill, however much the boxes write.
+
+Under the host lock, before Incus adds a thin volume to `raft-disks`, Raft adds
+up the size of every thin volume already there, as `lvs` reports it, and refuses
+the request if the new volumes would not fit. The sum covers everything in the
+pool: own-disk boxes, their snapshots, the cached image and anything an
+operator created. Each operation adds:
+
+| Operation | Adds |
+| --- | --- |
+| `new --disk SIZE` | The larger of SIZE and the cached image volume, plus the image volume itself the first time a box on this host needs it |
+| `new --from BOX/SNAPSHOT` of an own-disk snapshot | The larger of the snapshot's size and `--disk` |
+| `new --from BOX/SNAPSHOT --disk SIZE` of a shared-pool snapshot | SIZE |
+| `fork` of an own-disk box | The box's size |
+| `snapshot` of an own-disk box | The box's size |
+| `recover` of an own-disk backup | The box's size once for the box and once per snapshot in the backup |
+
+`restore` adds nothing: it swaps in a thin snapshot of the snapshot and removes
+the old volume. Destroying a box or deleting a snapshot frees its reservation.
+Incus caches the image in a 10 GiB volume (the pool's `volume.size` when set),
+which stays reserved while the image is in use; plan the pool size as 10 GiB
+plus the own disks and snapshots you want at once. The pool's data space is a
+little below SIZE, because LVM keeps part of the file for thin pool metadata.
+
+LVM sizes that metadata at 64 bytes per data block, above the 48 bytes per
+block the kernel documentation recommends for a fully mapped pool, and
+reservations keep the number of mapped blocks below the pool's block count. If
+metadata ever filled, every own-disk box would stop and the pool would need
+offline repair, so `raft capacity` warns when it passes 80%.
+
+## Inspecting capacity with `raft capacity`
+
+```sh title="CONTROLLER: View the advisory capacity estimate"
+raft capacity
+
+# Output JSON for programmatic inspection
+raft capacity --location lab --json
+```
+
+```text
+Advisory estimate only. Raft enforces no box count or size budget; create the boxes your task needs.
+lab: 8 CPUs, 31.3 GiB RAM (27.9 GiB available)
+Boxes: 3 saved, 2 active
+Allocated to active boxes: 3 CPUs, 6.0 GiB; host reserve: 1 CPU, 3.1 GiB; headroom: 4 CPUs, 22.2 GiB
+Disk free: 41.5 of 60.0 GiB shared pool, 48.2 GiB host
+Own box disks: 19.9 of 39.9 GiB unreserved
+CPU  RAM GiB  Fit on empty host  Fit now
+  1        2                  7        4
+  2        4                  3        2
+  4        8                  1        1
+Counts assume every box uses its full CPU and RAM at once. Boxes share host CPUs, so more can run when they are not all busy. Any whole CPU count and GiB size works.
+```
+
+The table lists example shapes that double from the 1 CPU / 2 GiB default at
+2 GiB per CPU, up to the largest that fits the host. For any other size, divide
+`headroom` by the box's CPU and RAM.
+
+### JSON fields
+
+| Field | Meaning |
+| --- | --- |
+| `notice` | The advisory sentence above |
+| `host` | CPUs, total and available RAM, free host disk, `sharedPool` space, and `boxDiskPool` |
+| `host.boxDiskPool` | `null` when own box disks are not enabled. Otherwise `totalBytes` (thin pool data space), `reservedBytes` (sizes of all its thin volumes), `usedBytes` (data written) and `metadataUsedPercent`; the last two are `null` while no own-disk volume is active. New own disks fit in `totalBytes - reservedBytes` |
+| `boxes`, `activeBoxes` | Saved boxes, and those not `Stopped` |
+| `allocated` | CPU and RAM limits of active boxes |
+| `reserve` | Host share left out of the estimates |
+| `headroom` | CPU and RAM left for more active boxes after the reserve |
+| `estimates` | Example shapes with `fitEmptyHost` and `fitNow` counts |
+| `warnings` | Low RAM or disk, overcommitted boxes, or thin pool metadata above 80% |
+
+### Calculations
+
+| Value | Calculation |
+| --- | --- |
+| CPU reserve | 1 CPU for the host OS |
+| Memory reserve | The larger of 2 GiB or 10% of host RAM |
+| Fit on empty host | `min(floor((CPUs - 1) / box CPUs), floor((RAM - reserve) / box RAM))` |
+| Fit now | The same with `headroom`, which also subtracts active allocations and keeps `MemAvailable - reserve` |
+
+All non-`Stopped` states, such as `Running` or `Frozen`, count as active.
+Stopped boxes use no CPU or RAM and keep their disk. Reserves are planning
+margins, not cgroup locks.
+
+### Illustrative hosts
+
+Fit on empty host for 1 CPU / 2 GiB boxes, using exact usable RAM values:
+
+| Host CPUs | Host RAM | Fit on empty host |
+| ---: | ---: | ---: |
+| 2 | 8 GiB | 1 |
+| 4 | 8 GiB | 3 |
+| 4 | 16 GiB | 3 |
+| 8 | 32 GiB | 7 |
+
+Operating systems report less usable RAM than the hardware size, so near
+boundaries the estimate can be one lower. Available RAM and host processes can
+lower it further. These are point-in-time estimates, not reservations.
+
+## Disk warnings
+
+`raft capacity` warns when free host disk or the shared pool falls below 5 GiB,
+and when `raft-disks` thin pool metadata passes 80%. Warnings do not block
+anything. `raft doctor` reports the shared pool and, when own box disks are
+enabled, `raft-disks`; a host without `raft-disks` is healthy.