CLAWDIE LIVE USB — SEED PARTITION
=================================

This FAT32 partition lets you customize the live USB BEFORE flashing or
between boots. On every boot, /usr/local/etc/rc.d/clawdie_live_seed imports
an allowlisted set of files from this partition. Editing a file and
rebooting re-applies it — the importer is idempotent.

USAGE FROM LINUX / macOS / WINDOWS
----------------------------------

1. Flash the image to USB (dd, or write the .img directly).
2. Mount the CLAWDIESEED partition (typically the third partition on the
   stick, e.g. /dev/sdX3 on Linux):

       sudo mount -t vfat /dev/sdX3 /mnt/clawdie-seed

3. Drop seed files (see the two layers below).
4. Unmount and boot the USB:

       sync
       sudo umount /mnt/clawdie-seed


LAYER 1 — SIMPLE ALLOWLIST (top level)
--------------------------------------

  /authorized_keys      Public SSH keys for the operator account.
                        Installed to ~clawdie/.ssh/authorized_keys
                        (mode 0600, owner clawdie:clawdie). CRLF
                        line endings are stripped automatically.

  /ssh/authorized_keys  Same as above, in a nested ssh/ namespace.
                        Takes precedence over /authorized_keys.


LAYER 2 — PER-AGENT DIRECTORIES
-------------------------------

Create one directory per agent. THE DIRECTORY NAME IS THE AGENT NAME.
Inside it, any of these are honored:

  /<agent>/env                   Plaintext KEY=VALUE lines. Keys you list
                                 replace existing values; keys you omit are
                                 preserved. Blank/`#` lines are ignored.
                                 Routing for the ACTIVE agent:
                                   - Provider API keys and toggles
                                     (DEEPSEEK_API_KEY=..., OPENROUTER_API_KEY=...,
                                     COLIBRI_AUTOSPAWN=YES, ...) are merged
                                     into BOTH the agent's ~/.env AND the daemon's
                                     /usr/local/etc/colibri/provider.env (mode
                                     0600). Because the importer runs before the
                                     daemon starts, a seeded provider key makes
                                     colibri_daemon auto-spawn the agent on first
                                     boot with NO operator action — fully
                                     zero-touch. No Vaultwarden round-trip needed.
                                   - Vaultwarden bootstrap creds
                                     (BW_CLIENTID/BW_CLIENTSECRET/BW_PASSWORD) are
                                     routed to ~/.config/vault-bootstrap.env for
                                     clawdie-vault-fetch — use these only if you
                                     want the vault-fetch path instead of direct
                                     keys.
                                 The Vaultwarden endpoint is baked into the
                                 image; do not put it on the seed unless you
                                 are deliberately overriding it.

  /<agent>/harness.toml          Which agent harness to run + basic knobs:

                                     harness = "zot"   # zot | pi | local
                                     model = "deepseek-v4-pro"
                                     cost_mode = "smart"

                                 `harness` must be one of zot, pi, local
                                 (Colibri's AgentRuntime). Recorded for the
                                 runtime to launch the right harness.

  /<agent>/soul/                 A layered-soul backup tree (SOUL.md, USER.md,
                                 IDENTITY.md, memories/, skills/, ...). Staged
                                 under /var/db/clawdie/seed/<agent>/soul for
                                 the agent workspace to load.

  /<agent>/ssh/authorized_keys   INBOUND: public keys allowed to SSH INTO this
                                 node. Installed to ~/.ssh/authorized_keys (0600).

  /<agent>/ssh/<name>            OUTBOUND: a private client key so this node can
                                 SSH OUT hands-free (e.g. node -> mother).
                                 Installed to ~/.ssh/<name> (0600). The private
                                 key rides on this offline seed instead of being
                                 baked into the image, so the image stays
                                 secret-free. Any file here that is not
                                 authorized_keys/config/known_hosts and does not
                                 end in .pub is treated as a private key.

  /<agent>/ssh/<name>.pub        OUTBOUND: installed to ~/.ssh/<name>.pub (0644).

  /<agent>/ssh/config            OUTBOUND: installed to ~/.ssh/config (0600).
                                 Typical use — host entries for the dual-purpose
                                 mother-mcp key (see next section):

                                     Host mother
                                         HostName osa.smilepowered.org
                                         User colibri
                                         IdentityFile ~/.ssh/mother-mcp

                                     Host code.smilepowered.org
                                         IdentityFile ~/.ssh/mother-mcp
                                         IdentitiesOnly yes

  /<agent>/ssh/known_hosts       OUTBOUND: merged into ~/.ssh/known_hosts (0644),
                                 de-duplicated. Pin the mother server's host key
                                 here so the first node -> mother connection does
                                 not stop on an unknown-host prompt. Scan the
                                 TARGET that ssh/config actually connects to
                                 (the Tailscale IP in HostName, not necessarily
                                 the DNS name):
                                     ssh-keyscan <mother-tailscale-ip>

  /<agent>/ssh/mother-mcp        DUAL-PURPOSE OUTBOUND KEY. This private key
                                 serves two roles with a single identity:

                                 1. MCP calls to mother via colibri-mcp.
                                    The mother server's authorized_keys entry
                                    forces command="colibri-mcp",restrict —
                                    this key can ONLY invoke the MCP tool,
                                    never a shell session.

                                 2. Git pull from Forgejo (code.smilepowered.org).
                                    Add this same key as a read-only deploy key
                                    in the Forgejo repository settings (repo →
                                    Settings → Deploy Keys → Add Deploy Key,
                                    with "Enable write access" OFF). Read-only
                                    is sufficient for `git pull` and limits
                                    blast radius if the key is ever compromised.

                                 Placing a key named mother-mcp here gives the
                                 agent git pull from Forgejo out-of-the-box with
                                 no additional configuration — the accompanying
                                 ssh/config Host entries route it for both
                                 destinations. No other key is needed for either
                                 purpose.

                                 The importer installs this material to TWO homes:
                                 /home/clawdie/.ssh/ (operator) and
                                 /var/db/colibri/.ssh/ (daemon). The daemon
                                 spawns the external-MCP SSH connection to mother,
                                 so it needs its own copy of the key + config.

Agent directory names may contain only A-Z a-z 0-9 . _ - (no spaces or
slashes). The name `ssh` is reserved for Layer 1.

LIVE USB vs DEPLOYED
--------------------

The live USB is single-agent: the FIRST agent directory (alphabetical) maps
to the clawdie user and becomes the active agent (recorded at
/var/db/clawdie/seed/active-agent). Additional agent directories are staged
and logged, but a second live identity is NOT provisioned here — multi-agent
provisioning is a deployed-host feature.


CONSUME-AND-SHRED (optional)
----------------------------

Drop an empty file named `shred` at the seed root to have the importer wipe
all `env` files from this partition AFTER importing them, so secrets do not
persist on the stick:

       /shred

This needs a writable seed; if the remount fails the env files are left in
place and the importer logs it. Off unless you add the marker, per stick.


SECURITY — READ THIS
--------------------

  - This is FAT32: UNENCRYPTED and readable by anyone who plugs the stick
    into any machine. There is no access control on this partition.
  - By operator decision, env files here MAY carry secrets (API keys, and
    the Vaultwarden bootstrap, which includes the master password). That is a
    deliberate trade-off: treat every seeded stick as SECRET-BEARING MEDIA.
    Do not lose it; do not lend it; prefer `shred` for one-shot provisioning.
  - Imported secrets land mode 0600 owned by the agent user. Public SSH keys
    are not secret and are always safe to place here.
  - The importer runs at every boot. Removing a file from the seed and
    rebooting does NOT remove an already-installed copy from the live system;
    re-flash the image to wipe state.

The importer logs to /var/log/clawdie-live-seed.log
(`service clawdie_live_seed status` tails it).


CONTACT
-------

clawdie.si — repository: clawdie-iso, files:
  live/operator-session/clawdie-live-seed
  live/operator-session/clawdie-live-seed.README.txt
