# 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.

> **Vercel:** because the deploy runs against a clean `git archive HEAD` export, `.vercel/project.json`
> (gitignored) isn't present — a bare `vercel deploy` would create a stray new project. Pin the target
> with `VERCEL_ORG_ID=… VERCEL_PROJECT_ID=… vercel deploy --yes` (IDs are not secrets; auth comes from
> your local `vercel login`). custard prints a warning if it spots an unpinned Vercel deploy.

## 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.