docs: write down how this stack is actually deployed

Releasing was documented in every repository; deploying was documented in none.
docs/releases.md stopped at "deploy it, and check the running version says what
it should" and never said how, which is how a family that pins images by digest
still had no written answer to "which digest, set where, and what happens when
it goes wrong".

The gap got worse the same day the stacks moved from building on the host to
pulling a published image: the procedure changed and the documentation did not.
An agent or a person reading this repository had to reconstruct it from the
compose file.

The new Deploying section names this stack's directory on the host, the env file
that selects the image, the variable that names it, the networks it needs, the
per-stack traps worth knowing, and what a rollback actually is. AGENTS.md points
at it and repeats the two rules easiest to get wrong: nothing is built on the
host, and a digest is pinned rather than a tag.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxNv1rk7jMQtb9tMBREc5B

Author: amtiYo

AGENTS.md

@@ -146,3 +146,17 @@ Branchy is licensed under Apache-2.0. Preserve the root `LICENSE` and `NOTICE` f
   `editEphemeralMessageText`. Notifications are rich messages and group
   overlays are ephemeral ones, so a server without them makes Branchy mute.
 
+## Deploying
+
+Do not invent a deploy. [`docs/releases.md`](docs/releases.md) has a **Deploying**
+section describing this stack exactly: which host directory it lives in, which
+env file names the image, which networks it needs, and how to roll back. Read it
+before touching anything on the host.
+
+Two rules that hold everywhere and are easy to get wrong:
+
+- **Nothing is built on the host.** A production stack pulls the image the
+  release workflow published. A `build:` section in a production manifest is a
+  bug.
+- **Pin the digest, not the tag.** A tag moves; a digest names one build that was
+  tested, and a rollback becomes one line with nothing to rebuild.

CHANGELOG.md

@@ -65,6 +65,14 @@ Use this section for changes that are merged but not released yet.
 
 ### Added
 
+- `docs/releases.md` gained a **Deploying** section, and `AGENTS.md` points at it.
+  Releasing was documented; deploying was not, in any repository in the family —
+  the process stopped at "deploy it" and never said how. That gap mattered more
+  after the stacks moved from building on the host to pulling a published image,
+  because the procedure changed on the same day. The section names this stack's
+  host directory, its env file, the variable that selects the image, the networks
+  it needs, and what a rollback actually is.
+
 - An **About** card, reachable from the main menu and from the group panel. It
   states the running version — the same string `/healthz` reports — plus the
   supported events, the repository, the license, and the admin contact. Until

docs/releases.md

@@ -92,6 +92,79 @@ the whole rollback — and then publish a new patch that fixes what went wrong.
 A version that was published is a fact about what existed. Rewriting it makes
 every other record of it wrong.
 
+## Deploying
+
+The host is WS04. Every stack lives in `/opt/stacks/<stack>` and is driven by the
+`ws04` CLI, which exists on the operator's machine and reaches the host over the
+LAN. Nothing here is built on the host any more: a stack pulls the image the
+release workflow published and runs that. If you find a `build:` section in a
+production manifest, that is a bug, not a shortcut.
+
+### One deploy
+
+```sh
+ws04 deploy branchy --dry-run --yes    # prints what it would do, changes nothing
+ws04 deploy branchy --yes
+```
+
+`deploy` snapshots the stack's compose, env and image ids into
+`/opt/stacks/.ws04/deploy-snapshots/branchy/<timestamp>`, pulls, brings the stack
+up, waits up to ninety seconds for the container to report healthy, and **rolls
+back on its own** if it does not. The snapshot is kept either way.
+
+### Pointing the stack at a version
+
+The image is chosen by one variable in the stack's env file on the host, not by
+anything in this repository:
+
+```sh
+BRANCHY_IMAGE=ghcr.io/freshlabdev/branchy@sha256:<digest>
+```
+
+Pin the **digest**, not the tag. A tag can be moved; a digest names one build
+that was tested, so a rollback is one line with nothing to rebuild, and
+`docker inspect` on the running container answers which commit it came from. The
+digest of a release is in its GitHub Release notes, or:
+
+```sh
+gh api /orgs/FreshLabDev/packages/container/branchy/versions \
+  --jq '.[] | select(.metadata.container.tags[]? == "<tag>") | .name'
+```
+
+The variable has no default. An unset one stops the stack with a message naming
+it, rather than quietly starting something else.
+
+### Rolling back
+
+Set `BRANCHY_IMAGE` to the previous digest and deploy again. That is the whole
+rollback — the images are still on the host, and nothing is rebuilt. Then publish
+a patch that fixes what went wrong; never retag or delete the bad release.
+
+### What this stack needs to exist
+
+| | |
+|:--|:--|
+| Stack | `branchy` — `/opt/stacks/branchy` |
+| Manifest | [`deploy/ws04/compose.yaml`](deploy/ws04/compose.yaml) in this repository |
+| Env file | `.env` on the host, never in git |
+| Networks | `core_net` (core-postgres), `management` (the Cloudflare tunnel that terminates the GitHub OAuth callback and the repository webhooks) |
+
+Branchy is the only stack on `management`. Without it the OAuth callback and
+every GitHub webhook delivery stop arriving, and the bot looks idle rather than
+broken.
+
+### Checking what is running
+
+```sh
+ws04 container list                    # health of everything
+ws04 logs branchy --since 1h
+ws04 container inspect branchy     # includes the image digest
+```
+
+The bot also reports its own version — from the About card in Telegram, and from
+its health endpoint where it has one. Those two and `docker inspect` should
+agree; if they do not, something was deployed by hand.
+
 ## Verification
 
 The local machine may not have `go` in `PATH`; Docker is the reliable route: