Merge pull request 'docs(guide): correct install docs to clawdie binary (not just/Ansible)' (#219 ) from fix/install-docs-clawdie-binary into main

Reviewed-on: #219
docs(guide): correct install docs to clawdie binary (not just/Ansible)
2026-06-26 15:01:44 +02:00 · 2026-06-26 15:00:34 +02:00
4 changed files with 33 additions and 95 deletions
--- a/docs/guide/install/controlplane-install.md
+++ b/docs/guide/install/controlplane-install.md
@ -1,24 +1,23 @@
 ---
 title: 'Control Plane Install'
-description: Install the Clawdie control plane with the standard orchestrator.
+description: Install the Clawdie control-plane host service with the clawdie binary.
 ---

-The control plane is installed by the standard orchestrator:
+The control plane runs as the host-managed `clawdie` service (`colibri-daemon`),
+provisioned by the `clawdie` binary:

 ```bash
-just install
+cargo build -p clawdie --release
+clawdie apply --yes
 ```

-The root install runs the control plane as the host-managed Clawdie service.
-The orchestrator configures PF, worker jails, PostgreSQL, hostd, service
-installation, checkpoints, and resume state together.
+This installs the storage datasets, the `clawdie` service user, and the rc.d
+(FreeBSD) / systemd (Linux) unit that runs `colibri-daemon`. Preview first with
+`clawdie plan`; `apply` is a dry-run until you pass `--yes`. See
+[Install](./install/) for the full command set, storage strategy, and safety
+notes.

-If an install fails, resume from the failed step:
-
-```bash
-just install-from-db
-just install-from hosts
-just install -- --dry-run
-```
-
-The canonical Bastille/Warden bridge name is `warden0`.
+> **Scope.** This provisions the control-plane host service only. PF egress,
+> worker jails, PostgreSQL, and the CMS/web service were handled by the legacy
+> clawdie-ai `just` + Ansible orchestrator and are not yet part of the colibri
+> installer. The canonical Bastille/Warden bridge name remains `warden0`.
--- a/docs/guide/install/index.md
+++ b/docs/guide/install/index.md
@ -21,5 +21,5 @@ Use this path for a new machine or a reinstall from boot media.
 Use this path when FreeBSD 15.x is already installed and you manage the host.

 - [Requirements](./requirements/) — host, runtime, and toolchain requirements.
- [Install orchestrator](./install/) — run `just install` and resume failed steps.
+- [Install](./install/) — provision the host service with the `clawdie` binary (`clawdie discover` / `plan` / `apply --yes`).
 - [Fresh install checklist](./fresh-install-checklist/) — verify the completed install.
--- a/docs/guide/install/install.md
+++ b/docs/guide/install/install.md
@ -75,80 +75,17 @@ Disk-touching steps (`zfs`/`zpool create`, service install) run as root on the
 target host. `discover`, `plan`, and a bare `apply` never write — preview with
 `plan` first.

-## Scope
+## Scope: what the installer does _not_ do (yet)

-`clawdie` provisions the host service. Jail, DB, CMS, and Git provisioning are not yet in the installer.
+`clawdie` provisions the **host service** only. The wider service mesh — PF
+egress, worker jails, PostgreSQL, Forgejo/Git, and the CMS/web service — was
+provided by the legacy clawdie-ai `just` + Ansible orchestrator and is **not yet
+part of the colibri installer**. Older pages that reference `just install`,
+`just setup-db`, `just doctor`, and similar describe that legacy flow, not this
+repo; they are being reconciled to the `clawdie` model.

 ## FreeBSD validation

-### Service wrapper scripts
-
-The rc.d service (`/usr/local/etc/rc.d/${AGENT_NAME}`) runs
-`run-${AGENT_NAME}.sh` which is **generated** by `just setup-service` at
-install time. It is not tracked in git (`run-*.sh` is in `.gitignore`).
-If missing, re-run `just setup-service` to regenerate it.
-
-Local LLM runtime is optional and configured via:
-
-```
-LOCAL_LLM_PROVIDER=none|ollama|llama_cpp
-FEATURE_OLLAMA=YES|NO
-FEATURE_LLAMA_CPP=YES|NO
-FEATURE_OLLAMA_HPP=YES|NO   # optional C++ bindings for Ollama clients
-```
-
---
-
-## Required vs optional steps
-
-Steps are **required** (failure stops install), **default** (runs out of the box
-but can be disabled), or **optional** (skipped unless explicitly enabled).
-
-| Step             | Status   | Skip condition                                                     |
-| ---------------- | -------- | ------------------------------------------------------------------ |
-| onboarding       | required | —                                                                  |
-| environment      | required | —                                                                  |
-| agent-config     | optional | warn on missing provider auth or missing agent binary              |
-| pf               | required | —                                                                  |
-| jails            | required | —                                                                  |
-| git              | default  | `DB_RUNTIME=host` or `install-from hosts`                          |
-| forgejo          | default  | `FEATURE_GITEA` = NO                                               |
-| db               | default  | `DB_RUNTIME=host` skips jail, provisions on host instead           |
-| skills-memory    | default  | `bootstrap/skills-memory/artifact.sql` not present                 |
-| skills-init      | default  | —                                                                  |
-| cms              | default  | `install-from hosts` skips; cms is a shared service, not per-agent |
-| ollama           | optional | `FEATURE_OLLAMA` ≠ YES                                             |
-| llama-cpp        | optional | `FEATURE_LLAMA_CPP` ≠ YES                                          |
-| hosts            | required | —                                                                  |
-| mounts           | required | —                                                                  |
-| telegram-auth    | optional | `TELEGRAM_BOT_TOKEN` not set                                       |
-| service          | required | —                                                                  |
-| hostd            | required | —                                                                  |
-| identity-restore | optional | `SUPABASE_URL` not set                                             |
-| verify           | optional | warn on most check failures; fail on compromised runtime integrity |
-
-A required step failure stops the install immediately and prints the resume
-command. Default steps ship enabled (`FEATURE_GITEA=YES`, artifact.sql bundled)
-— they run unless the operator explicitly opts out.
-
---
-
-## Individual steps
-
-The orchestrator calls each step through `setup/index.ts` as a subprocess
-(`spawnSync` with `tsx`). This isolates `process.exit(1)` calls in individual
-step modules from killing the orchestrator.
-
-Individual steps can still be run directly:
-
-```bash
-just setup-db
-just setup -- --step verify
-```
-
-`verify` checks more than the shared docs build. If tenant sites are
-declared, it also checks their served output and publish-manifest consistency in
-the CMS webroot. A site that is merely declared but not yet manually published
-does not fail the step by itself; an inconsistent live publish state does.
-
-The step registry is implemented in `setup/index.ts`.
+The disk-touching and service-install paths are validated on real FreeBSD/Linux
+hosts; discovery, plan, and disk-candidacy logic are unit-tested. See
+`docs/CLAWDIE-INSTALLER-HANDOFF.md` for the FreeBSD validation runbook.
--- a/docs/guide/install/requirements.md
+++ b/docs/guide/install/requirements.md
@ -5,7 +5,7 @@ description: Host, runtime, and toolchain requirements for Clawdie.

 What you need on the host before installing Clawdie. The ISO installer
 provisions most of this automatically; existing-host installs should verify
-these requirements before running `just install`.
+these requirements before running `clawdie apply`.

 ## Host

@ -18,13 +18,15 @@ these requirements before running `just install`.

 ## Toolchain

- **Rust** via rustup, installed under `/opt/clawdie/rustup`.
-  Required for native dependencies (SWC, tree-sitter). The ISO
-  installs this; existing-host installs run it from
-  [`Install orchestrator`](./install).
- **Node.js + tsx** for the install scripts and runtime.
+- **Rust** (Cargo) — the colibri control plane and the `clawdie`
+  installer are a Cargo workspace. Build the installer with
+  `cargo build -p clawdie --release`. See [Install](./install/).
 - **Bastille** for jail management.

+> The legacy clawdie-ai `just` + Node/`tsx` orchestrator is not used in this
+> repo; the sections below still describe the clawdie-ai product runtime and are
+> being reconciled to the colibri model.
+
 ## Runtime philosophy

 Clawdie is a single Node.js process that orchestrates jailed
Author	SHA1	Message	Date
clawdie	f60aca1573	Merge pull request 'docs(guide): correct install docs to clawdie binary (not just/Ansible)' (#219 ) from fix/install-docs-clawdie-binary into main Some checks are pending CI / rust (push) Waiting to run Details CI / markdown (push) Waiting to run Details CI / port (push) Waiting to run Details CI / agent-jail-pkgs (push) Waiting to run Details Reviewed-on: #219	2026-06-26 15:01:44 +02:00
Sam & Claude	79f67bf575	docs(guide): correct install docs to clawdie binary (not just/Ansible) Some checks are pending CI / rust (pull_request) Waiting to run Details CI / markdown (pull_request) Waiting to run Details CI / port (pull_request) Waiting to run Details CI / agent-jail-pkgs (pull_request) Waiting to run Details Replace legacy just install / just setup-* references with clawdie binary commands (clawdie plan, clawdie apply --yes). Document scope: what the installer does not do (yet). Trim the clawdie-ai just orchestrator step tables. Rebased from #213 onto current main; supersedes #217.	2026-06-26 15:00:34 +02:00