@microck/raft 0.0.0-stage → 0.2.1

package/docs/guides/project-setup.mdx

@@ -0,0 +1,112 @@
+---
+title: Project setup and templates
+description: Upload or clone a project, run setup scripts, and create reusable same-host snapshot templates.
+---
+
+# Project setup and templates
+
+Raft starts a clean development image. Prepare a project with ordinary guest
+commands, then save a snapshot to reuse installed dependencies. There is no
+managed repository registry, environment registry, setup hook, or secret-injection
+service. Commands run as guest root in `/workspace` unless you choose another user.
+
+## Put a project in the box
+
+Create a persistent box after [host setup](../operations.mdx):
+
+```sh title="CONTROLLER: Create a project box"
+box=$(raft new --location lab --ttl 3600)
+```
+
+Upload a local project, excluding credentials and files you do not want copied.
+The example assumes `./my-project` contains your project and `setup.sh`:
+
+```sh title="CONTROLLER: Upload local project"
+raft upload "$box" ./my-project /workspace/my-project --recursive
+```
+
+The destination directory must not exist. For a public repository, an alternative
+is guest `git clone`; replace the example URL with your repository:
+
+```sh title="CONTROLLER: Clone instead of uploading"
+raft exec "$box" -- git clone https://github.com/OWNER/REPOSITORY.git /workspace/my-project
+```
+
+Choose one method. Private repositories require authentication configured inside
+the guest; Raft does not forward your controller's GitHub login or SSH agent.
+The clean image does not bundle coding agents or their credentials. Install and
+authenticate any agent inside the box using that tool's own instructions.
+
+## Run setup explicitly
+
+Use `bash -lc` for directory changes or shell syntax:
+
+```sh title="CONTROLLER: Run project setup"
+raft exec "$box" -- bash -lc 'cd /workspace/my-project && bash ./setup.sh'
+```
+
+Make setup scripts safe to rerun. Raft does not execute them automatically on
+create, resume, or fork. A failing synchronous command returns its exit code;
+see [Scripting and CI](./scripting-ci.mdx).
+
+For slow setup, use a detached job and inspect its result:
+
+```sh title="CONTROLLER: Run slow setup instead of synchronous setup"
+job=$(raft exec "$box" --detach -- bash -lc 'cd /workspace/my-project && bash ./setup.sh')
+raft status "$box" "$job"
+raft logs "$box" "$job"
+```
+
+Wait for successful completion before making a template. Extending the lifetime
+may be necessary; a detached job does not prevent expiry.
+
+## Supply application configuration
+
+For an application that reads a local `.env` file, upload it explicitly and set
+permissions for the application's user. This example assumes a controller file
+`./app.env` and an application running as `developer`:
+
+```sh title="CONTROLLER: Install a private application configuration file"
+raft upload "$box" ./app.env /workspace/my-project/.env
+raft exec "$box" -- chown developer:developer /workspace/my-project/.env
+raft exec "$box" -- chmod 600 /workspace/my-project/.env
+```
+
+The application must load that file; upload does not export environment variables.
+If running the whole project as `developer`, adjust project ownership separately.
+Do not place secrets in command arguments, committed files, or logs. Host journals
+can capture guest command lines. Raft does not rotate or scrub credentials.
+
+## Save and reuse a prepared template
+
+Finish setup, remove credentials that should not be inherited, and stop the box:
+
+```sh title="CONTROLLER: Save the prepared filesystem"
+raft stop "$box"
+raft snapshot "$box" prepared
+```
+
+Create another box from the snapshot:
+
+```sh title="CONTROLLER: Start a copy with explicit resources"
+copy=$(raft new --from "$box/prepared" --ttl 3600 --cpu 2 --memory 4GiB)
+raft exec "$copy" -- ls -la /workspace/my-project
+```
+
+The template stays on its source host. Its source box can be running when you
+copy the saved snapshot. `new --from` uses normal creation defaults when sizing
+is omitted: 1 CPU and 2 GiB RAM. The new box has its own handle, MAC address,
+deadline, and saved slot.
+
+The snapshot includes packages, project files, credentials, and enabled services.
+It does not include process memory. Changing the original after snapshot creation
+does not update the saved template. Keep its source box and snapshot until you
+no longer need to create copies; destroying the source deletes its snapshots.
+
+To copy the stopped box's current filesystem instead, use
+`raft fork "$box" --ttl 3600`. Fork inherits omitted CPU/RAM limits and does not
+copy the source snapshots. See [Snapshots and forks](./snapshots-forks.mdx).
+
+For a different host, use [Backup and recovery](./backup-recovery.mdx) with matching
+CPU architecture. For services that start on resume, see
+[Lifetime and persistent services](./long-running-services.mdx).

package/docs/guides/scripting-ci.mdx

@@ -0,0 +1,133 @@
+---
+title: Scripting and CI
+description: Parse CLI output, preserve command exit codes, wait for readiness, and handle interrupted operations.
+---
+
+# Scripting and CI
+
+Raft is a controller CLI using host SSH. A Linux CI runner needs Python 3.11.8+,
+OpenSSH, the installed CLI, host inventory, verified SSH host keys, batch
+authentication, and hosts with passwordless sudo. No Raft HTTP API, SDK, or API key
+exists. Give access only to trusted jobs: the configured SSH account has host sudo
+and controls all boxes on that host.
+
+## Output formats
+
+Raft does not have a global `--json` option. Parse each command's actual format:
+
+| Command | stdout |
+| --- | --- |
+| `new`, `fork`, `recover` | One location-qualified handle |
+| `exec --detach` | One `rfcmd-` job ID |
+| `list` | JSONL: one object per box, with `box`, `state`, `stopAt` |
+| `info` | One pretty-printed native Incus metadata JSON object |
+| `usage` | One JSON object containing running resource counters |
+| `limits --json` | One JSON object per location (JSONL across multiple hosts) |
+| `prune` | JSONL candidates or deleted records with `box`, `action` |
+| `status` | systemd `ActiveState`, `SubState`, `ExecMainStatus` property lines |
+| `logs` | Guest journal text |
+| `exec` | Payload stdout/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
+as a string, or an empty string when absent. `info` uses native Incus keys rather
+than a normalized Raft schema. `usage` includes `memoryBytes`, `memoryLimit`,
+`cpuTime`, `effectiveCpus`, `filesystemUsedBytes`, `filesystemAvailableBytes`, and
+`filesystemScope`; disk values describe the shared pool, not an individual box.
+See [Capacity limits](../reference/capacity-limits.mdx) for capacity calculations.
+
+These examples require `jq` on the controller:
+
+```sh title="CONTROLLER: Parse records without mixing stderr"
+raft list --location lab | jq -r 'select(.state == "Running") | .box'
+raft limits --location lab --json | jq '{location, savedSlots, warnings}'
+raft prune --location lab --older-than 7 | jq -r '.box'
+```
+
+Do not redirect `2>&1` into machine-readable output. Recovery reports its allocated
+handle on stderr before import finishes; only a successful completion prints the
+final handle on stdout.
+
+## Exit codes and job results
+
+| Situation | Exit code |
+| --- | --- |
+| Successful control operation | `0` |
+| Synchronous `exec` | Transport/command return code; preserves payload exit status when transport succeeds |
+| Recognized runtime/configuration failure | `1`, with `raft: ...` on stderr |
+| Argument parsing failure | `2`, with argparse diagnostics on stderr |
+| Caught keyboard interruption | `130` |
+
+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).
+
+## Create, wait, run, and stop
+
+`new` returns after Incus starts the box, before every guest service is necessarily
+ready. Probe a harmless command before running setup. This Bash example waits up
+to about a minute plus transport time, executes an uploaded project check, and
+attempts to stop the persistent box on exit. It assumes `./my-project/check.sh`
+exists and the configured host has a free saved slot:
+
+```bash title="CONTROLLER or trusted Linux CI runner"
+set -euo pipefail
+box=""
+cleanup() {
+  result=$?
+  trap - EXIT
+  if [ -n "$box" ]; then
+    if ! raft stop "$box"; then
+      echo "Cleanup failed; inspect $box" >&2
+      [ "$result" -ne 0 ] || result=1
+    fi
+  fi
+  exit "$result"
+}
+trap cleanup EXIT
+
+box=$(raft new --location lab --ttl 3600)
+printf 'Created %s\n' "$box" >&2
+ready=false
+for attempt in {1..30}; do
+  if raft exec "$box" -- true; then
+    ready=true
+    break
+  fi
+  sleep 2
+done
+if [ "$ready" != true ]; then
+  echo "Guest did not become command-ready: $box" >&2
+  exit 1
+fi
+
+raft upload "$box" ./my-project /workspace/my-project --recursive
+raft exec "$box" -- bash -lc 'cd /workspace/my-project && bash ./check.sh'
+```
+
+The stopped box remains available for inspection and still consumes a saved slot.
+Destroy it after collecting needed files, or preview old stopped boxes with prune.
+For disposable CI boxes, deletion on stop/expiry removes artifacts and snapshots;
+download results before cleanup. A new box or a retry still consumes a saved slot.
+
+Command readiness does not mean Docker or a web application is ready. Probe the
+specific dependency (`docker info`, an HTTP health endpoint, or systemd status)
+with its own bounded wait. Extend the deadline before work exceeding the current
+lifetime. This example's retries are only for the harmless readiness probe.
+
+## Interrupted operations and retries
+
+Raft does not automatically retry commands or provide idempotency keys. If SSH
+drops during creation, resume, import, or execution, the remote operation may have
+already happened. Inspect `raft list`, `raft info`, guest logs, and the host before
+repeating an operation that creates boxes or changes data. A failed create can
+leave a saved box even when no handle reached stdout.
+
+For an interrupted recovery, inspect the handle printed on stderr and follow
+[Host crash during recovery](./troubleshooting.mdx#host-crash-during-recovery).
+For uncertain command execution, check its effects before rerunning it; use
+idempotent setup scripts where possible. Do not treat a lost connection as proof
+of deletion or of a command not having run.

package/docs/guides/snapshots-forks.mdx

@@ -0,0 +1,107 @@
+---
+title: Snapshots and forks
+description: Capture point-in-time filesystem snapshots and fork independent workspace clones.
+---
+
+# Snapshots and forks
+
+Raft captures filesystem snapshots, rolls back changes, and clones workspaces on the same host.
+
+## Target workspace handle
+
+Commands in this guide require a stopped workspace:
+
+```sh title="CONTROLLER: Select and stop target workspace"
+raft list
+box="lab:rf-a1b2c3d4e5f60718"  # Replace with your actual workspace handle
+raft stop "$box"
+```
+
+## Stopped-source requirement
+
+<Callout type="warn" title="Workspace must be stopped">
+Creating a snapshot, restoring from a snapshot, or forking requires a stopped container. Operations run under host lock `/run/lock/raft-incus.lock` to prevent concurrent disk modification.
+</Callout>
+
+## Creating snapshots
+
+Take a point-in-time snapshot of the stopped workspace filesystem:
+
+```sh title="CONTROLLER: Create a named snapshot"
+raft snapshot "$box" pre-upgrade
+```
+
+Snapshot names must use letters, digits, underscores, or hyphens up to 64 characters.
+
+## Listing snapshots
+
+View existing snapshots for a workspace:
+
+```sh title="CONTROLLER: List existing snapshots"
+raft snapshots "$box"
+```
+
+The command prints snapshot names and creation timestamps from Incus metadata.
+
+## Restoring from a snapshot
+
+Roll back a stopped workspace to a previously recorded snapshot:
+
+```sh title="CONTROLLER: Restore snapshot"
+raft restore "$box" pre-upgrade
+```
+
+<Callout type="info" title="Configuration preservation during restore">
+`raft restore` executes Incus snapshot restore with `--diskonly`. It rolls back filesystem blocks while preserving container configuration, CPU and memory limits, and the `eth0` network MAC address.
+</Callout>
+
+Resume the workspace with a renewed lifetime:
+
+```sh title="CONTROLLER: Resume restored workspace"
+raft resume "$box" --ttl 600
+```
+
+## Forking a workspace
+
+Forking creates an independent clone on the same host:
+
+```sh title="CONTROLLER: Fork workspace into a new clone"
+copy=$(raft fork "$box" --ttl 600)
+echo "Created fork: $copy"
+```
+
+### Characteristics of forked workspaces
+
+- **Instance-only copy**: Uses Incus `--instance-only`. Filesystem data, installed packages, and `/workspace` files are copied; source snapshots are not inherited.
+- **Immediate start**: `raft fork` launches the new container immediately with the specified TTL while the source remains stopped.
+- **Fresh network identity**: The fork receives a new container name, a fresh MAC address on `rfbr0`, and an independent IP address.
+- **Capacity accounting**: The fork counts toward the location's four-saved-box limit and uses storage from the shared 60 GiB Btrfs pool.
+
+Destroy the clone when finished to release capacity:
+
+```sh title="CONTROLLER: Destroy forked workspace"
+raft destroy "$copy"
+```
+
+## Starting from a prepared snapshot
+
+```sh
+copy=$(raft new --from "$box/pre-upgrade" --ttl 600)
+```
+
+The source box can be running because Raft copies the saved snapshot. The new box stays on the same host, uses normal creation sizing defaults and has a fresh network identity. Filesystem secrets are copied too.
+
+Remove a snapshot you no longer need:
+
+```sh
+raft snapshot-delete "$box" pre-upgrade
+```
+
+## Choosing clone resources
+
+```sh
+copy=$(raft fork "$box" --ttl 600 --cpu 2 --memory 4GiB)
+raft resume "$box" --ttl 600 --memory 2GiB
+```
+
+Omitted sizing values keep the source limits. Forks are persistent by default; add `--disposable` to delete a clone when it stops or expires.

package/docs/guides/troubleshooting.mdx

@@ -0,0 +1,152 @@
+---
+title: Troubleshooting
+description: Diagnose configuration, host infrastructure, network filtering, and container lifecycle issues.
+---
+
+# Troubleshooting
+
+Diagnostic procedures and solutions for common deployment, configuration, and runtime issues.
+
+## Controller diagnostics
+
+### Preflight checks with `raft doctor`
+
+Run `raft doctor` on your controller to inspect host health across configured locations:
+
+```sh title="CONTROLLER: Run environment health check"
+raft doctor
+```
+
+`raft doctor` connects to each host over SSH and reports:
+- Incus version running in project `raft`
+- 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
+- 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.
+</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.
+
+Review the host deployment changes, then deploy from the checkout matching your
+CLI. Replace `lab` with the location reported by the diagnostic:
+
+```sh title="CONTROLLER: Explicitly update a reviewed host deployment"
+python3 deploy/deploy.py --location lab
+raft doctor
+```
+
+Deployment updates host infrastructure as well as the expiry worker. Do not run
+it on a shared host without authorization. Do not remove the compatibility check
+or mark an old worker as current; older workers may retain expired disposable
+boxes instead of deleting them.
+
+### Listing active and stopped containers
+
+Inspect workspace states across locations:
+
+```sh title="CONTROLLER: List workspaces across all hosts"
+raft list
+
+# Filter by a single location
+raft list --location lab
+```
+
+If a host is unreachable over SSH, the CLI reports a connection failure. An unreachable host does not mean containers are absent or deleted.
+
+## Host-side diagnostics
+
+Connect to the host over SSH to inspect underlying services when commands fail.
+
+### Inspecting Incus project status
+
+Verify container states and storage pools in project `raft`:
+
+```sh title="HOST: Inspect containers and storage pools"
+sudo incus --project raft list
+sudo incus --project raft storage info raft-data
+```
+
+### Checking host systemd units
+
+Raft installs two systemd units on the host:
+- `raft-network.service`: Applies firewall and bridge isolation rules before Incus starts.
+- `raft-expire.timer` / `raft-expire.service`: Runs the expiration worker every 15 seconds to stop expired workspaces.
+
+Inspect unit logs with `journalctl`:
+
+```sh title="HOST: Check Raft systemd unit logs"
+sudo systemctl status raft-network.service
+sudo systemctl status raft-expire.timer
+sudo journalctl -u raft-expire.service -n 50 --no-pager
+```
+
+<Callout type="warn" title="Host journals and guest secrets">
+Host system journals can capture command lines, arguments, and environment variables executed in guest containers. Treat host logs as sensitive records that may contain guest credentials.
+</Callout>
+
+### Manually triggering garbage collection
+
+The host timer enforces expiry every 15 seconds. Trigger an immediate expiration run from the controller:
+
+```sh title="CONTROLLER: Run expiration workers manually"
+raft gc
+```
+
+Expired persistent containers transition from `Running` to `Stopped` and retain
+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).
+
+## Common error scenarios
+
+### Configuration errors
+
+#### Missing configuration file error
+If `~/.config/raft/incus.json` does not exist, the CLI raises `FileNotFoundError`. Create the configuration directory and file. Set mode `0600` on the file only.
+
+#### "Configure at least one host in ~/.config/raft/incus.json"
+The configuration file contains valid JSON that is `{}` or is not an object (an empty file raises a JSON decoding error instead). Ensure the file defines at least one location with a non-empty `ssh` string.
+
+#### "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
+
+#### "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.
+
+#### 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.
+
+### Network and forwarding issues
+
+#### Port forward connects but returns connection refused
+Verify that the guest service binds to `0.0.0.0` or the container's `eth0` IP address. Services bound strictly to `127.0.0.1` inside the container cannot receive traffic routed through the bridge.
+
+#### Workspaces cannot reach other workspaces on the same host
+This is intended behavior. Raft configures nftables bridge filtering on `rfbr0` to prevent communication between workspaces on the same bridge.
+
+### Host crash during recovery
+
+If the controller crashes or SSH drops while `raft recover` is transferring an archive:
+1. Check the `Recovery handle: <location>:<name>` output printed to stderr when `raft recover` started.
+2. Inspect the reported handle with `raft list --location <location>` and confirm container status before removing staging.
+3. Identify the exact staging file (`/tmp/raft-recovery.XXXXXXXX`) on the host by owner and timestamp.
+4. After confirming container status, remove only that owned file:
+   ```sh title="HOST: Remove verified owned staging file"
+   sudo -n rm -f -- /tmp/raft-recovery.XXXXXXXX
+   ```
+
+<Callout type="warn" title="Do not delete by wildcard">
+Never run `rm /tmp/raft-recovery.*`. It can delete files from another recovery.
+</Callout>

package/docs/guides/upgrades.mdx

@@ -0,0 +1,113 @@
+---
+title: Upgrades and image changes
+description: Update the controller CLI and host worker, replace image fingerprints, and understand existing-box behavior.
+---
+
+# Upgrades and image changes
+
+The controller CLI, host deployment scripts, and workspace image are separate
+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 |
+| 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 |
+
+## 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
+consistently when adopting another release.
+
+```sh title="CONTROLLER: Inspect the current installation"
+raft --version
+raft doctor
+raft list
+```
+
+Save a copy of your controller inventory. Export important persistent boxes using
+[Backup and recovery](./backup-recovery.mdx) before host changes. Backup requires a
+stopped box. Stopping a disposable box deletes it, so copy needed files out before
+stopping one. Schedule redeployment when interruptions are acceptable.
+
+## Update the controller
+
+For an npm installation:
+
+```sh title="CONTROLLER: Install a pinned CLI release"
+npm install -g @microck/raft@0.2.0
+raft --version
+```
+
+For a Python installation, download the wheel and `SHA256SUMS` from the same
+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
+raft --version
+```
+
+Proceed only if checksum verification succeeds. Choose one installation method
+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.
+
+## Redeploy each host
+
+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
+python3 deploy/deploy.py --location lab
+raft doctor
+```
+
+Repeat for each configured location. The deployer uses your existing
+`~/.config/raft/incus.json`, verifies owned project/pool/network/profile state,
+replaces host scripts and units, reapplies firewall rules, and starts the expiry
+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.
+
+## Replace the image pin
+
+Follow [Acquire a native workspace image](../operations.mdx#acquire-a-native-workspace-image)
+to download and verify or build the image for each host's architecture. Retrieve
+its full fingerprint and replace only that location's `image` field in the
+controller inventory. Keep the previous fingerprint if you may need it again.
+
+Changing the pin affects ordinary `raft new` calls. Resume retains the existing
+filesystem; forks and `new --from` use their source filesystem, not the new image.
+Install guest updates explicitly inside an existing box, or create a new box and
+transfer the project and needed data. Recovering an old backup also restores that
+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)
+raft exec "$box" -- node --version
+raft exec "$box" -- docker info
+raft stop "$box"
+raft resume "$box" --ttl 600
+raft exec "$box" -- ls /workspace
+raft destroy "$box"
+```
+
+Creation can return before guest services are ready. Use the readiness pattern in
+[Scripting and CI](./scripting-ci.mdx) if an immediate check fails during startup.
+For dedicated test infrastructure, [Verification](../verification.mdx) describes
+the real-host suites and their effects.
+
+To revert an image choice for future boxes, restore the previous fingerprint
+while that image remains imported. This does not revert existing boxes. Raft has
+no automatic migration or rollback of host policy or guest packages; review the
+chosen release and backups before downgrading those components.

package/docs/incus.example.json

@@ -0,0 +1,3 @@
+{
+  "lab": {"ssh": "your-ssh-host", "image": ""}
+}

package/docs/index.mdx

@@ -0,0 +1,40 @@
+---
+title: Overview
+description: Persistent Linux workspaces powered by Incus.
+---
+
+# 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.
+
+## Getting started
+
+Read [System requirements](./requirements.mdx), follow [Installation and host setup](./operations.mdx), and create your [First working box](./first-box.mdx).
+
+```sh title="CONTROLLER: Create and use a workspace"
+box=$(raft new --location lab --ttl 600)
+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) |
+| 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) |

package/docs/meta.json

@@ -0,0 +1,21 @@
+{
+  "title": "Raft",
+  "pages": [
+    "index",
+    "---Start here---",
+    "requirements",
+    "operations",
+    "first-box",
+    "guides",
+    "reference",
+    "contract",
+    "---Comparison---",
+    "boat-capabilities",
+    "boot-performance",
+    "---Contributing---",
+    "boat-parity-design",
+    "verification",
+    "publishing",
+    "site-development"
+  ]
+}