docs: deployment leverages spry deploy / usm manifest deploy from the repo checkouts (no outside-repo Dockerfiles); extension guide cross-referenced

README.md

@@ -99,14 +99,28 @@ alive across restarts and is never packaged or baked into images.
 
 The database is `./clanker-saddle.sqlite`, or `SPRY_DB_PATH` when set.
 
-## Docker setup
+## Container deployment (spry deploy / usm)
 
-Two multi-stage Alpine images build everything from source against musl
-(see `../Dockerfile.saddle` and `../Dockerfile.clanker-saddle`):
+Both halves package as USM packages and build container images from
+their own checkouts — no Dockerfiles outside the repos:
 
 ```bash
-podman build -f Dockerfile.clanker-saddle -t localhost/clanker-saddle:0.1 ..
-podman build -f Dockerfile.saddle -t localhost/saddle:0.1 ..
+# this app (a Spry application — spry deploy wraps usm manifest deploy):
+spry deploy --verbose \
+    --repository https://packages.astrologue.nz/repo/web-stack/repo.usmr
+
+# the daemon (from ../saddle — usm manifest deploy directly):
+cd ../saddle && usm manifest deploy \
+    --repository https://packages.astrologue.nz/repo/web-stack/repo.usmr
+```
+
+Each writes `<name>-<version>.image.tar.xz` (single-stage, built in
+container against the canonical Web-Stack repository — allow time for
+the toolchain build on first run). Load and run:
+
+```bash
+podman load -i clanker-saddle-0.1.image.tar.xz
+podman load -i saddle-0.1.image.tar.xz
 
 podman network create clanker-net
 podman run -d --name clanker-web --userns=keep-id --network clanker-net \
@@ -136,6 +150,18 @@ mounts to be writable. For durable sessions mount `web-config.json`
 read-only and point `ASTRALIS_CONFIG_PATH` at it; otherwise the app runs
 with ephemeral keys.
 
+## Saddles with dev tools (the extendable agent container)
+
+The stock `saddle` image carries the daemon, its CLI and git — nothing
+else. Build specialised agents by extending it with the toolchains of
+your choosing (see `../saddle`'s README, *Extending the saddle image*,
+for the full guide): a two-line Containerfile `FROM` the loaded base
+plus `dnf install` of your tools (C, Vala, GTK, Node, .NET, Android,
+QEMU — anything), then tag the capability names you gave those tools in
+the web UI's saddle page so only tasks requiring them route there.
+Goal task worktrees need every container that may run a goal's tasks to
+share the `/workspace` volume.
+
 ## Creating your first project and task
 
 1. **Project** — `/projects` → name, git URL, default branch. The
@@ -386,15 +412,16 @@ HTTP/2 removes the cap entirely.
   honoured by matching pairs, and the daemon's registration/token
   persists across its restarts while the app re-seeds on a fresh DB.
 
-## Deployment (USM)
+## Packaging (USM)
 
-`MANIFEST.usm` + `usm-scripts/` package the app as `bin:clanker-saddle`
-(`usm manifest package`), published to the Web-Stack repository:
+`MANIFEST.usm` + `usm-scripts/` package the app as
+`bin:clanker-saddle` for the Web-Stack repository:
 
 ```bash
-usm manifest package
-cd ../web-stack-repo && usm repository add ../clanker-saddle-0.1.usmc
+usm manifest package      # → clanker-saddle-<version>.usmc
 ```
 
+Publishing to a USM repository is a repository-side operation (see the
+USM tooling; `usm repository add` from the repository's checkout).
 `web-config.json` is never packaged (`.usmignore`); keys are mounted at
 runtime, never baked into images.