## Guidelines

Read and follow these guidelines for all recipe operations.

### Preserving local recipe changes

Before running `abra recipe fetch <recipe> --force`, always check for uncommitted changes first:

```
git -C ~/.abra/recipes/<recipe> status --short
```

- **If the working tree is clean:** proceed with `abra recipe fetch <recipe> --force` to pull the latest upstream.
- **If there are uncommitted changes:** do NOT fetch. Log that the recipe has local modifications and that you are using the local checkout as-is. Use `--chaos` on any subsequent `abra app` commands so they pick up the local state instead of requiring a committed version.

This matters because `--force` overwrites the entire local checkout, destroying any in-progress work.

### Recipe version format

Recipe versions use the format `<recipe-semver>+v<upstream-version>`, for example `0.2.6+v4.5.0`. The `v` prefix before the upstream version is always present, even if the upstream image tag uses a different prefix (e.g. CryptPad's Docker tag `version-2025.9.0` becomes `+v2025.9.0` in the recipe version).

This version string appears in three places that must stay in sync:
1. The `coop-cloud.${STACK_NAME}.version` deploy label in `compose.yml`
2. The annotated git tag on the release commit
3. The `TYPE=<recipe>:<version>` line in the app's `.env` file on the server

Co-op Cloud requires **annotated tags** (not lightweight tags). Always use `git tag -a` with a `-m` message:

```
git tag -a "0.5.0+v2026.2.0" -m "chore: publish 0.5.0+v2026.2.0 release"
```

### Saving secrets locally

When generating secrets for an app, always use `--machine` to get machine-readable output and save it to `recipe-info/<recipe>/secrets.json`:

```
abra app secret generate <domain> --all --machine > recipe-info/<recipe>/secrets.json
```

This keeps a local record of the generated secrets (e.g. admin passwords needed for initial login). The `--machine` flag outputs JSON instead of a human-readable table.

### Active test instance

The current active test instance is set by `default_instance` in `settings.toml` at the workspace root. Read this value directly to determine which instance to operate on. The instance's server and domain_suffix are in the `[instances.<name>]` section. Domain for any recipe is `<recipe>.<domain_suffix>`.