docs: add MANUAL + MIGRATION guides, linked from README

@@ -171,4 +171,9 @@ 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**.
 
+## Docs
+
+- **[docs/MANUAL.md](docs/MANUAL.md)** — operating manual: everyday git, privacy, versioning, issues, the deploy CLI, brew releases, updating the forge.
+- **[docs/MIGRATION.md](docs/MIGRATION.md)** — moving a repo GitHub → Soft + custard (static/Pages → server, Vercel, CLIs, libraries).
+
 See `PLAN.md` for the phased build plan.

@@ -0,0 +1,108 @@
+# custard — operating manual
+
+Day-to-day use of a custard forge over [Soft Serve](https://github.com/charmbracelet/soft-serve).
+Replace `your-host` with your forge domain and `you/tap` with your tap namespace throughout.
+
+## The pieces
+
+- **Web forge:** `https://your-host` — custard, behind Caddy (auto-TLS) on your server.
+- **Git server:** Soft Serve on the server. An ssh `soft` alias → `your-host:23231`; remotes are `soft:<repo>`.
+- **Homebrew tap:** a `homebrew-tap` repo → `brew install` straight from your host.
+
+A handy `~/.ssh/config` alias:
+```
+Host soft
+    HostName your-host
+    Port 23231
+    IdentityFile ~/.ssh/id_ed25519
+```
+
+## Everyday git
+
+```sh
+# new repo
+ssh soft repo create thing -d "what it is"
+cd thing && git init && git add -A && git commit -m "init" && git branch -M main
+git remote add origin soft:thing && git push -u origin main
+
+# clone
+git clone soft:thing                              # ssh
+git clone https://your-host/git/thing.git         # public, read-only
+
+# admin (run `ssh soft help` for everything)
+ssh soft repo list | info <n> | description <n> "…" | private <n> true|false | webhook …
+```
+
+## Privacy
+
+```sh
+ssh soft repo private thing true     # hide from the public forge
+ssh soft repo private thing false    # publish
+```
+With `--soft-serve-db` set, only **public** repos appear on the forge; private/hidden → 404.
+
+## Versioning (git tags)
+
+```sh
+git tag -a v0.2.0 -m "release name"
+git push origin v0.2.0
+```
+- Shows as a **version pill** in the header + index; the annotated **message is labelled on the refs page**.
+- Highest semver wins. Bump anytime — tags are independent of commits, no code change needed.
+
+## Issues
+
+`backlog/tasks/*.md` ([Backlog.md](https://backlog.md)) render at `/r/<repo>/issues`. Groups order
+in progress → paused → backlog → done. Manage with the `backlog` CLI.
+
+## Deploy a web app — the custard CLI
+
+`.custard.yaml`:
+```yaml
+ci:
+  - npm test
+deploy:
+  preview: vercel deploy            # any command that prints a URL (netlify/fly/rsync work too)
+  promote: vercel promote {{url}}   # {{url}} = the preview; default is vercel
+```
+```sh
+custard check     # run ci on the working tree (fast loop)
+custard preview   # build HEAD → run ci → deploy preview → URL
+custard promote   # promote the last preview → production
+```
+Deploys build the **committed HEAD** (uncommitted edits never ship); HEAD must be **pushed**. The CLI
+never runs `git push` — you push however you like.
+
+## Release a CLI to Homebrew
+
+`.custard.yaml`:
+```yaml
+brew: { enabled: true, package: "." }   # or ./cmd/<name>
+```
+One-time per repo, register the webhook (secret = your `WEBHOOK_SECRET`):
+```sh
+ssh soft repo webhook create <name> https://your-host/hooks/release \
+  -e branch_tag_create -c json -s "$WEBHOOK_SECRET"
+```
+Release + install:
+```sh
+custard release v0.2.0          # checks → tag → push → tap publishes
+brew tap you/tap https://your-host/git/homebrew-tap.git
+brew trust you/tap              # newer Homebrew gates third-party taps
+brew install <name> ; brew upgrade <name>
+```
+
+## Updating the forge
+
+```sh
+cp deploy/deploy.env.example deploy/deploy.env   # first time: fill REMOTE, DOMAIN, secrets…
+deploy/deploy.sh                                  # build static binary, ship, restart
+```
+
+## Automatic niceties
+
+- README/markdown images with relative paths render; gifs sit embossed; click any image for a lightbox.
+- Deploy badge (✓ in production / 👁 preview / ⚠ unverified) shows only for repos with a `deploy:` in `.custard.yaml`.
+- README is its own tab; `code` is the file tree.
+
+See [MIGRATION.md](MIGRATION.md) to move a repo off GitHub.

@@ -0,0 +1,117 @@
+# Migrating GitHub → Soft Serve + custard
+
+Move a repo off GitHub onto a self-hosted Soft Serve + custard forge, including deployment.
+Replace `your-host` / `you/tap` / `<server>` with your values. See also [MANUAL.md](MANUAL.md).
+
+## Step 1 — move the git repo (every migration)
+
+```sh
+# 1. create it on Soft (or let it autocreate on first push)
+ssh soft repo create <name> -d "what it is"
+
+# 2. point the local clone at Soft
+git remote set-url origin soft:<name>          # full move, or:
+git remote add soft soft:<name>                # keep GitHub as a backup mirror
+
+# 3. push everything (history, branches, tags)
+git push origin --all && git push origin --tags
+
+# 4. set visibility (public repos show on the forge)
+ssh soft repo private <name> true|false
+```
+
+## Step 2 — drop GitHub-only cruft (full self-host)
+
+- `.github/workflows/*` — GitHub Actions → replaced by `.custard.yaml` `ci` + `custard check/preview`.
+- `.goreleaser.yaml` — if releasing to a GitHub-hosted brew tap → replaced by custard's tap.
+- README badges/links pointing at github.com.
+
+```sh
+git rm -r .github .goreleaser.yaml && git commit -m "drop GitHub CI/release" && git push
+```
+
+## Step 3 — issues → Backlog.md
+
+GitHub Issues don't transfer. Use [Backlog.md](https://backlog.md): tasks live in `backlog/tasks/`
+and render on `/r/<name>/issues`. Recreate open issues by hand.
+
+---
+
+## Deployment, by type
+
+### A. Static site / GitHub Pages → your server
+
+Pages goes away with GitHub. Serve the built site from your server with Caddy:
+
+1. Build locally (Hugo/Jekyll/Astro/HTML) → an output dir (`public/`, `dist/`, …).
+2. Add a Caddy site block for the domain → `file_server` over the output dir.
+3. Point the domain's DNS at the server; Caddy issues TLS.
+4. **Optional — gate through custard** with rsync in `.custard.yaml`:
+   ```yaml
+   ci: ["npm run build"]
+   deploy:
+     preview: "rsync -a ./public/ <server>:/var/www/<site>-preview/"
+     promote: "rsync -a ./public/ <server>:/var/www/<site>/"
+   ```
+   Then `custard preview` (build + stage) → `custard promote` (go live).
+
+> custard is a git forge, not a static host — Caddy serves the files; custard just runs the build/deploy if you want the check+gate flow.
+
+### B. Vercel app — stay on Vercel, point at the Soft repo
+
+Vercel's **git integration supports only GitHub/GitLab/Bitbucket**, so a Soft-hosted repo can't
+auto-deploy via Vercel's hook. Keep Vercel as the host, deploy from the **CLI**:
+
+1. `vercel link` the repo to the existing Vercel project (keeps the prod URL).
+2. In Vercel's dashboard, **disconnect the GitHub integration** (stop it deploying the old repo).
+3. `.custard.yaml`:
+   ```yaml
+   ci: ["pnpm test", "pnpm build"]
+   deploy:
+     preview: vercel deploy
+     promote: vercel promote {{url}}
+   ```
+4. Push to Soft → `custard preview` (build HEAD, run ci, preview URL) → `custard promote` (same build → prod).
+
+You keep Vercel hosting + URLs; you trade Vercel's auto-PR previews + GitHub checks for on-demand
+`custard preview` + `.custard.yaml` `ci`.
+
+### C. CLI / TUI → Homebrew
+
+```yaml
+# .custard.yaml
+brew: { enabled: true, package: "." }   # or ./cmd/<name>
+```
+```sh
+ssh soft repo webhook create <name> https://your-host/hooks/release \
+  -e branch_tag_create -c json -s "$WEBHOOK_SECRET"
+custard release v0.1.0
+# install: brew tap you/tap https://your-host/git/homebrew-tap.git && brew install <name>
+```
+Replaces GitHub Releases + a GitHub-hosted tap.
+
+### D. Library / plain code
+
+Step 1 is the whole migration — browsable on the forge, tag versions as usual.
+
+---
+
+## What you give up off GitHub → the replacement
+
+| GitHub feature | On Soft + custard |
+|---|---|
+| Pull requests / review | Push-based + `custard check`/`preview` gate; branches if needed |
+| GitHub Actions CI | `.custard.yaml` `ci` via `custard check`/`preview` |
+| Issues | Backlog.md (`backlog/tasks/`, shown on the forge) |
+| Releases + assets | custard `/dl` tarballs + the tap |
+| Pages | Caddy static hosting on your server |
+| Vercel/Netlify git auto-deploy | `custard preview`/`promote` (CLI) |
+| Dependabot / scanning | none (manual) |
+
+## Keep GitHub as a mirror (optional)
+
+```sh
+git remote add github git@github.com:you/<name>.git
+git push github --mirror      # occasionally
+```
+(Then you're primary-on-Soft, not fully off GitHub.)