docs: deploy & release CLI usage

@@ -145,4 +145,30 @@ The tag (must be semver `vX.Y.Z`) fires the webhook → custard verifies the HMAC signature,
 archives the tag, writes the tarball, and pushes an updated formula to the tap. `scripts/brew-release.sh`
 remains as a manual fallback.
 
+## Deploy & release CLI
+
+The same `custard` binary is also a local client for shipping (the droplet runs `custard serve`;
+your laptop runs the verbs). It never pushes git — you keep committing/pushing however you like;
+it owns *deploy + release*. Configure check/deploy commands per repo in `.custard.yaml`:
+
+```yaml
+ci:
+  - go vet ./...
+  - go test ./...
+deploy:
+  preview: vercel deploy              # any command that prints a URL (vercel/netlify/fly/rsync…)
+  promote: vercel promote {{url}}     # {{url}} = the preview; defaults to vercel promote
+```
+
+```bash
+custard check               # run ci on the working tree (fast inner loop)
+custard preview             # export HEAD, run ci, deploy a preview → URL
+custard promote             # promote the last preview → production
+custard release v0.2.0      # run ci, tag + push → tap auto-publishes
+```
+
+Deploys **build from the committed HEAD** (uncommitted edits are never deployed) and require HEAD
+pushed. `preview`/`promote` report signed status back to the forge (`~/.custardrc` or
+`CUSTARD_URL`/`CUSTARD_TOKEN`), which badges commits **✓ in production / 👁 preview / ⚠ unverified**.
+
 See `PLAN.md` for the phased build plan.