## Getting Started

At the start of each session, before doing any work:

1. Read `README.md` to understand this project's purpose, structure, skills, and test environment setup.
2. Read the `docs.coopcloud.tech/` folder to understand how Co-op Cloud and `abra` work, including recipe structure, deployment patterns, configuration conventions, and best practices.

This background context is essential for all recipe-related tasks.

3. **Read `learnings.md`** for abra CLI best practices — it contains critical information about TTY requirements, `--chaos` flag usage, and other operational patterns that will save you from common pitfalls. In particular:
   - Many `abra` commands (e.g. `abra app cmd`, `abra app backup create`, `abra app logs`) require a TTY wrapper: `script -qefc "abra ..." /dev/null`
   - Always use `--chaos` during local recipe development to prevent abra from changing your working tree
   - Prefer `docker service logs` via SSH over `abra app logs` in non-interactive environments

4. **Read these key skill files** so you understand operational patterns used across all tasks:
   - `.claude/commands/test-context-reset.md` — how context reset works, including the **in-use lock file** mechanism (`in-use/<recipe>.lock`): these files protect recipes from being undeployed during active work. Always create one when starting work on a recipe, remove it when done.
   - `.claude/commands/recipe-deploy.md` — the standard deploy flow (chaos mode, force, no-input)
   - `.claude/commands/recipe-test.md` — how recipe tests are run
   - `.claude/commands/init-instance.md` — how the test instance is initialised from scratch

## Always pull the latest recipe before answering questions about it

Before answering any question about a specific recipe (config, env vars, compose overlays, secrets, etc.), `git fetch` and check `origin/main` in the recipe's checkout. The local copy can be days or weeks behind, and recipes change — new `compose.*.yml` overlays, new secrets, env-var renames, and entrypoint changes land regularly. Answering from a stale tree produces confidently-wrong advice.

```bash
cd /workspace/.container-abra/recipes/<recipe>
git fetch
git log --oneline HEAD..origin/main   # show what you're missing
```

If `origin/main` is ahead, either pull or `git show`/`git diff` the new commits before answering.

## Recipe semver vs. image versions

Co-op Cloud recipe versions are independent of the upstream app/image version, and follow semver
*for the recipe* — not the app. The recipe version label (the `coop-cloud.${STACK_NAME}.version`
tag in `compose.yml`, e.g. `0.3.4+v5.2.0`) has two parts: `<recipe-semver>+<app-version>`.

When you bump an image tag (the `+<app-version>` part), you **must** also bump the recipe semver
(the part before `+`). The size of that bump is determined by what the operator has to do, **not**
by how big the app's own version jump is:

- **Patch** (`0.3.4 → 0.3.5`) — the usual case. The image version increased but **no operator
  action is required**: deploying the new version "just works" (no new/renamed env vars, no new
  secrets, no manual migration, no breaking config changes).
- **Minor** (`0.3.4 → 0.4.0`) — new optional functionality or new env vars/secrets that have safe
  defaults; the operator *may* want to act but isn't forced to.
- **Major** (`0.3.4 → 1.0.0`) — operator action is **required**: breaking changes, mandatory new
  secrets/env vars, manual data migrations, or anything that breaks an existing deployment if applied
  blindly.

Default to a **patch** bump for routine image-version upgrades. Only go minor/major when the upgrade
genuinely demands operator awareness or action.

## Git commits

- Author every commit as `notplants <@notplants>` (use `--author="notplants <@notplants>"`).
- Do **not** add `Co-Authored-By` trailers to commit messages — no Claude/AI co-author lines.

## Tailscale + SSH (userspace mode)

Some test servers require Tailscale for SSH access. To connect from this containerized environment:

1. **Start tailscaled in userspace mode** (no root, no TUN device needed):
   ```bash
   tailscaled --state=/tmp/tailscale-state --tun=userspace-networking \
     --socks5-server=localhost:1055 --socket=/tmp/tailscale-run/tailscaled.sock &>/tmp/tailscaled.log &
   ```

2. **Authenticate** using an auth key from `test-ssh/.testenv`:
   ```bash
   source test-ssh/.testenv
   tailscale --socket=/tmp/tailscale-run/tailscaled.sock up \
     --authkey=$TS_AUTH_KEY --hostname=claude-recipe-maintainer
   ```

3. **SSH via the SOCKS5 proxy** — set `ALL_PROXY` before any SSH command:
   ```bash
   export ALL_PROXY=socks5://localhost:1055
   ssh -o StrictHostKeyChecking=no server.example.com "echo connected"
   ```

4. The SSH config in `test-ssh/ssh-config` should use `HostName` with the Tailscale IP (100.x.x.x) for servers that require Tailscale. Auth keys are stored in `test-ssh/.testenv` (not committed).

## OpenCode

If you are running in OpenCode, read `OPENCODE.md` for details on how skills and commands are configured.