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

Merge pull request 'docs: onboarding simplification + drop clawdie-ai source snapshot' (#109) from docs/onboarding-simplification into main

Browse source
This commit is contained in:
clawdie 2026-06-22 08:09:54 +02:00
commit 343ba35536
2 changed files with 96 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
build.sh
View file

@ -1201,24 +1201,25 @@ EOF
install_live_ai_source_snapshots() { install_live_ai_source_snapshots() {
echo " Installing live AI source checkouts..." echo " Installing live AI source checkouts..."
resolve_clawdie_ai_repo
resolve_colibri_paths resolve_colibri_paths
mkdir -p "${MOUNT_POINT}/home/clawdie/ai" mkdir -p "${MOUNT_POINT}/home/clawdie/ai"
cat > "${MOUNT_POINT}/home/clawdie/ai/README.txt" <<'EOF' cat > "${MOUNT_POINT}/home/clawdie/ai/README.txt" <<'EOF'
Clawdie live AI source checkouts Clawdie live AI source checkouts
These directories are included so the operator can start a local provider-backed These directories are included so the operator can inspect the shipped source
Pi session from the live XFCE desktop, inspect the shipped source beside the beside the running system and fetch follow-up commits from Forgejo when network
running system, and fetch follow-up commits from Forgejo when network access is access is available.
available.
No API keys, .env files, SSH private keys, build caches, package caches, tmp/ No API keys, .env files, SSH private keys, build caches, package caches, tmp/
directories, or uncommitted worktree changes are included. Each checkout keeps a directories, or uncommitted worktree changes are included. Each checkout keeps a
.git directory plus a .clawdie-source.json file recording the source remote, .git directory plus a .clawdie-source.json file recording the source remote,
branch, commit, modified state, ISO version, and build channel at image build time. branch, commit, modified state, ISO version, and build channel at image build time.
clawdie-ai (TypeScript) is no longer included — it is being phased out in favor
of the colibri (Rust) control plane. The `clawdie` name is retained as the brand
and bare-metal installer identity.
EOF EOF
seed_live_ai_source_repo "${SCRIPT_DIR}" "clawdie-iso" seed_live_ai_source_repo "${SCRIPT_DIR}" "clawdie-iso"
seed_live_ai_source_repo "${_resolved_clawdie_ai_repo}" "clawdie-ai"
seed_live_ai_source_repo "${_resolved_colibri_repo}" "colibri" seed_live_ai_source_repo "${_resolved_colibri_repo}" "colibri"
# zot source so the live rebuild lane can rebuild the agent (Go) too, not # zot source so the live rebuild lane can rebuild the agent (Go) too, not
# just Colibri (Rust). Skipped automatically if the zot checkout is absent. # just Colibri (Rust). Skipped automatically if the zot checkout is absent.

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.