From 9a159b859373504c263faa619c0bcac39ee48299 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Mon, 22 Jun 2026 07:51:13 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20onboarding=20simplification=20=E2=80=94?= =?UTF-8?q?=20seed=20partition=20zero-touch=20vs=20zot=20extensions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the proven end-to-end chain: seed importer (rc.d BEFORE LOGIN) → BW creds in provider.env → clawdie-vault-fetch → colibri_daemon restart. The only remaining click is the 'Join Hive' desktop launcher; the seed partition already reduces onboarding from 3 typed secrets to one double-click. True zero-touch requires ~30 lines of shell (xdg autostart). Also records the zot extensions verdict: onboarding panel rejected (chicken-and-egg), guard deferred (zot is not OOTB runtime), MCP bridge kept as the first extension worth building (gated on colibri#143). --- docs/ONBOARDING-SIMPLIFICATION.md | 89 +++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/ONBOARDING-SIMPLIFICATION.md diff --git a/docs/ONBOARDING-SIMPLIFICATION.md b/docs/ONBOARDING-SIMPLIFICATION.md new file mode 100644 index 00000000..e2dd7ef2 --- /dev/null +++ b/docs/ONBOARDING-SIMPLIFICATION.md @@ -0,0 +1,89 @@ +# Onboarding Simplification — Decision Doc + +2026-06-22 | colibri#143 (zot-rpc-driver) | clawdie-iso + +## Context + +The ISO ships with a manual onboarding flow: operator opens START-HERE.txt in +Mousepad, types 3 Vaultwarden bootstrap credentials into a terminal +(`clawdie-join-hive`), waits for API key fetch, restarts the daemon. + +A zot extension was proposed as an interactive replacement. That was rejected +— the onboarding must be agent-independent (chicken-and-egg: zot needs +DEEPSEEK_API_KEY, which onboarding fetches), and the existing shell flow +already implements masked input, validation, and the full fetch→restart chain. + +The real lever is **removing the step**, not reskinning it. + +## Current state (proven, live) + +### Manual path (no seed partition) + +1. Operator boots ISO +2. START-HERE.txt opens in Mousepad (bootstrap autostart) +3. Operator double-clicks "Join Hive" on desktop +4. Prompted for BW_CLIENTID, BW_CLIENTSECRET (masked), BW_PASSWORD (masked) +5. `clawdie-vault-fetch` pulls API keys from Vaultwarden +6. `colibri_daemon` restarted +7. Pi agent auto-spawned and live + +### Seed partition path (one double-click) + +Identical except step 4 is skipped — the seed importer (`clawdie-live-seed`, +rc.d BEFORE LOGIN) already wrote the BW creds to provider.env. The operator +just double-clicks "Join Hive" and the fetch runs automatically. + +**Files:** + +| Component | Path | Role | +|-----------|------|------| +| Seed importer | `live/operator-session/clawdie-live-seed` | rc.d service, runs before login, mounts CLAWDIESEED, routes BW_* creds to provider.env | +| Vault fetcher | `live/operator-session/clawdie-vault-fetch` | Standalone: login→unlock→fetch keys by name→write env | +| Join Hive | `live/operator-session/clawdie-join-hive.sh` | Desktop launcher: checks for creds → prompts or auto-fetches | +| Seed README | `live/operator-session/clawdie-live-seed.README.txt` | Operator-facing seed partition instructions | + +## Remaining work: delete the click + +The seed partition path reduces onboarding to ONE double-click. Making it +zero-touch requires: + +1. **xdg autostart entry** — on first login, if BW_* creds are present in + provider.env AND `colibri_daemon` is not yet fully provisioned, auto-run + `clawdie-vault-fetch --write-env ` and restart the daemon. + +2. **First-boot guard** — run once per boot only (not on every login). A + sentinel file (`/var/db/clawdie/vault-fetched`) prevents re-triggering. + +3. **START-HERE.txt update** — remove the "add your 3 BW secrets" section + when the seed partition is present. Show a confirmation instead: + "Secrets loaded from seed partition. Colibri is starting." + +Estimated: ~30 lines of shell. + +## Related: one-secret path (future) + +The 3-credential bootstrap (BW_CLIENTID + BW_CLIENTSECRET + BW_PASSWORD) +could collapse to a single pasted token via `colibri-vault` tenant +provisioning. The vault would pre-generate a one-time enrollment token; +the operator pastes it once; the host exchanges it for permanent API +credentials. This eliminates the Vaultwarden account setup step entirely. + +Status: not yet designed. Depends on colibri-vault tenant provisioning +(colibri#91). + +## Zot extensions — verdict + +| Idea | Verdict | Rationale | +|------|---------|-----------| +| Onboarding panel (zot ext) | ❌ Reject | Chicken-and-egg: zot needs secrets that onboarding fetches. Already solved by `clawdie-join-hive.sh`. | +| Guard (dangerous bash) | ⏸ Defer | Guards zot, not Pi (OOTB agent). String matcher is a nudge, not a boundary. Ship through first-party extension lane after zot is the runtime. | +| MCP bridge (zot↔Colibri) | ✅ Keeper | Sanctioned lane. Gated on zot-rpc-driver (colibri#143). First extension worth building — gives zot access to task board, vault, spawn, skills. | + +## Sequencing + +1. **Now** (no dependencies): seed-partition zero-touch — delete the one remaining + click. Biggest simplification, zero dependency on the zot saga. +2. **Gated on colibri#143**: MCP bridge extension — zot↔Colibri, gives zot + reason to be the runtime. +3. **After zot is OOTB runtime**: guard extension shipped through first-party + extension lane, paired with jail confinement for the real boundary.