docs: onboarding simplification — seed partition zero-touch vs zot extensions
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:
parent
7fd49363d2
commit
9a159b8593
1 changed files with 89 additions and 0 deletions
89
docs/ONBOARDING-SIMPLIFICATION.md
Normal file
89
docs/ONBOARDING-SIMPLIFICATION.md
Normal 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.
|
||||||
Loading…
Add table
Reference in a new issue