Sam & Claude
61683eeb42
Convert US/ISO prose dates to EU format across iso docs (CHANGELOG, plans, handoffs, wiki-linked docs). Left as-is (data, not prose): the sample log lines in FIRSTBOOT.md and the ADMIN-PANEL.md UI mockup (timestamps/snapshot names); ISO is correct for machine output. Markdown format gate clean.
101 lines
5.6 KiB
Markdown
101 lines
5.6 KiB
Markdown
# Onboarding Simplification — Decision Doc
|
|
|
|
22.jun.2026 | 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. 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 |
|
|
|
|
## Zero-touch: direct keys on the seed (implemented)
|
|
|
|
The click only existed to trigger the Vaultwarden round-trip. For a
|
|
personalized stick that already holds the real provider keys, that round-trip
|
|
is unnecessary — and the boot ordering already favors zero-touch:
|
|
|
|
- `clawdie_live_seed` runs as root, `BEFORE: LOGIN`.
|
|
- `colibri_daemon` runs `REQUIRE: LOGIN` — strictly after.
|
|
|
|
So the importer now merges the active agent's direct provider keys (everything
|
|
except `BW_*`) into the daemon's `provider.env` as well as the operator's
|
|
`~/.env`. The daemon starts afterward, finds `DEEPSEEK_API_KEY`, and
|
|
auto-spawns the agent (`COLIBRI_AUTOSPAWN=YES`) — no click, no vault
|
|
round-trip, no typing. `BW_*` still route to `~/.config/vault-bootstrap.env`
|
|
for operators who prefer the vault-fetch path.
|
|
|
|
This makes the **personalized seed** the onboarding primitive:
|
|
|
|
- The image stays generic and publishable; secrets are never baked in.
|
|
- The seed (FAT32 `CLAWDIESEED`) is the personalization layer and stays
|
|
physical/offline — `env` (direct keys + optional `TAILSCALE_AUTH_KEY`),
|
|
`harness.toml`, `soul/`, `ssh/authorized_keys`, optional `/shred` to wipe
|
|
keys off the stick after first import.
|
|
- The seed can be generated by an agent (e.g. Hermes) that already holds the
|
|
soul and key material, written straight onto the mounted partition.
|
|
|
|
This supersedes the earlier xdg-autostart "delete the click" plan: it removes
|
|
the click for free without a first-login sentinel or a network dependency at
|
|
first boot.
|
|
|
|
## 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.
|