docs: rewrite for box-first model + webhooks + notifications

docs/dotfiles.md

@@ -6,10 +6,11 @@ preloaded with QoL CLI tooling, a persistent per-user home, and user dotfiles.
 ## The model
 
 - **Persistent per-user home.** Each user gets a home directory on the worker
-  host at `${SPOON_AGENT_WORKDIR}/homes/{username}`, bind-mounted into every
-  job/terminal container at `/home/{username}` (`HOME`). It survives across
-  sessions, so dotfiles, installed tools, nvim plugins, and shell history persist.
-  `username` is derived from the user's profile first name (sanitized).
+  host at `${SPOON_AGENT_WORKDIR}/homes/{username}`, bind-mounted into the
+  per-user box (`spoon-box-{username}`) at `/home/{username}` (`HOME`). It
+  survives across sessions, so dotfiles, installed tools, nvim plugins, and shell
+  history persist. `username` is derived from the user's profile first name
+  (sanitized).
 - **Threads as folders.** Each thread's checkout lives at
   `~/Code/{spoon}/{branch}` inside that home, so every thread shows up as a
   folder in one home. The agent (`codex --cd …`) and the terminal both open there.
@@ -61,18 +62,21 @@ Secrets: dotfiles are encrypted, but real API keys/tokens belong in a Spoon's
 No new required env. The home is a host directory under the existing workdir, so
 the prod bind-mount + `SPOON_AGENT_HOST_WORKDIR` translation already covers it.
 
-## Notes / limits (Phase 1)
+## Notes / limits
 
 - **Repo auth:** public repos only. Private/self-hosted (e.g. Gitea) dotfiles
   repos are a follow-up (store a token/deploy key).
 - **Binary files:** the overlay is text-first.
 - **Cleanup:** `~/Code/{spoon}/{branch}` checkouts persist (threads as folders);
   a per-thread "delete checkout" action is a follow-up.
-- **Concurrency:** jobs share one home; fine at the default
+- **Concurrency:** jobs and terminals share one box/home; fine at the default
   `SPOON_AGENT_MAX_CONCURRENT_JOBS=1`.
 
-## Phase 2 north star
+## The box
 
-A single long-running per-user container that every thread `exec`s into (agent
-via `docker exec`, not `docker run --rm`). The per-user home + `~/Code/{spoon}/
-{branch}` layout built here is its foundation.
+The per-user home + `~/Code/{spoon}/{branch}` layout is the foundation of the
+box model: a single long-running per-user container (`spoon-box-{username}`) that
+every thread's agent turn, terminal, and command `exec`s into (`docker exec`, not
+`docker run --rm`). Home materialization runs once per box start (and again when
+the dotfiles config hash changes), so the overlay and repo setup apply to every
+session in that box.