clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: onboarding simplification — seed partition zero-touch vs zot extensions

Browse source 
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).
This commit is contained in:
Sam & Claude 2026-06-22 07:51:13 +02:00
parent 7fd49363d2
commit 9a159b8593
1 changed files with 89 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
docs/ONBOARDING-SIMPLIFICATION.md Normal file
View file

@ -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 <provider.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.