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

docs/compose.prod.yml

@@ -7,18 +7,18 @@
 # If you change them, read the comments first:
 #
 #   1. AGENT WORKDIR (spoon-agent-worker): the worker is containerized but
-#      launches the Codex job container by talking to the HOST Docker daemon.
-#      The host can only bind-mount real HOST paths, so the work directory MUST
-#      be a bind mount whose path is IDENTICAL inside and outside the container,
-#      and SPOON_AGENT_HOST_WORKDIR must match it. A named volume does NOT work
-#      here because its real host path is hidden from the worker. All three
-#      references to /var/lib/spoon-agent/work below must stay in sync; change
-#      them together if you want the data somewhere else.
+#      creates and `exec`s into the per-user box (spoon-box-{username}) by talking
+#      to the HOST Docker daemon. The host can only bind-mount real HOST paths, so
+#      the work directory MUST be a bind mount whose path is IDENTICAL inside and
+#      outside the container, and SPOON_AGENT_HOST_WORKDIR must match it. A named
+#      volume does NOT work here because its real host path is hidden from the
+#      worker. All three references to /var/lib/spoon-agent/work below must stay
+#      in sync; change them together if you want the data somewhere else.
 #
 #   2. IMAGE FRESHNESS: services use `pull_policy: always` + Watchtower labels so
-#      a redeploy / new push always lands. The Codex *job* image is pulled by the
-#      worker itself on startup (see SPOON_AGENT_JOB_IMAGE); restarting the worker
-#      (which Watchtower does on a new image) re-pulls a fresh job image.
+#      a redeploy / new push always lands. The *box* image is pulled by the worker
+#      itself on startup (see SPOON_AGENT_JOB_IMAGE); restarting the worker (which
+#      Watchtower does on a new image) re-pulls a fresh box image.
 
 networks:
   nginx-bridge: # Change to network you plan to use
@@ -83,9 +83,9 @@ services:
       - SPOON_WORKER_TOKEN=${SPOON_WORKER_TOKEN}
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
-      # Identical host:container path so the sibling Codex job containers can
-      # bind-mount the workspace via the host daemon. Do NOT switch this to a
-      # named volume. See header note (1).
+      # Identical host:container path so the sibling per-user box can bind-mount
+      # the persistent home (homes/{username}) via the host daemon. Do NOT switch
+      # this to a named volume. See header note (1).
       - /var/lib/spoon-agent/work:/var/lib/spoon-agent/work
     labels: ['com.centurylinklabs.watchtower.enable=true']
     tty: true