---
description: Explain what this project is and how to get started
allowed-tools: [Read, Glob]
---

Present this entire introduction to the user verbatim — do NOT summarize or condense it.

# Co-op Cloud Recipe Toolkit — Introduction

This repository is an AI-assisted toolkit for maintaining [Co-op Cloud](https://coopcloud.tech) recipes. It runs inside a container with `~/.abra` bind-mounted, providing an isolated environment where the `abra` CLI operates normally without access to the host's SSH keys or abra configuration. The only credentials available are the test SSH keys in `test-ssh/`, limiting all deployment operations to the designated test server.

## What it does

The toolkit wraps `abra` and other tools into slash-command skills that automate the full recipe maintenance lifecycle: checking for upstream upgrades, planning and applying updates, deploying to a test server, running tests, managing backups, reviewing recipes against best practices, and tagging releases.

## Repository structure

- **`.claude/commands/`** — Skill definitions (slash commands). This is where all the automation lives.
- **`recipe-info/`** — Per-recipe data organized by recipe name: upstream release note URLs, test instance environment files, and test scripts.
- **`planned-updates/`** — Upgrade reports and summaries generated by `/recipe-upgrade-plan` and `/recipe-upgrade-apply`.
- **`plans/`** — Project planning documents.
- **`test-ssh/`** — SSH config and keys for the test server where recipe instances are deployed.
- **`settings.toml`** — Defines which test server instances are available and which is the current default.
- **`maintained-recipes.md`** — List of recipes this toolkit actively maintains. Used by `/recipe-overview` and `/recipe-test-all`.
- **`learnings.md`** — Hard-won lessons and `abra` CLI quirks discovered during operation.
- **`docs.coopcloud.tech/`** — Local copy of the Co-op Cloud documentation; used as reference for recipe structure, deployment patterns, and platform conventions.
- **`lib/`** — Python helper library used by test scripts and automation (SSH, abra wrappers, secrets management).
- **`.opencode/`** — OpenCode stubs that point back to `.claude/commands/` so skills work in both Claude Code and OpenCode.

## Available skills

### Recipe lifecycle
- **`/recipe-overview`** — Check all maintained recipes, see what needs upgrading
- **`/recipe-check <name>`** — Check a single recipe for available upstream upgrades
- **`/recipe-upgrade-plan <name>`** — Research release notes and create a detailed upgrade plan
- **`/recipe-upgrade-apply <name>`** — Apply the plan: update images, deploy, test, commit, and tag
- **`/recipe-init <name>`** — Bootstrap a new recipe from scratch (fetch, create test instance, deploy)
- **`/recipe-new-tag <name>`** — Bump the version and create an annotated git tag
- **`/recipe-review <name>`** — Audit a recipe against Co-op Cloud best practices

### Deploying and testing
- **`/recipe-deploy <name>`** — Deploy local recipe checkout to the test server (chaos mode)
- **`/recipe-test <name>`** — Run all tests for a recipe
- **`/recipe-test-new <name>`** — Test a fresh install from scratch
- **`/recipe-test-update <name>`** — Test upgrading an existing deployment
- **`/recipe-test-backup <name>`** — Test the backup/restore cycle
- **`/recipe-test-all`** — Run tests for every maintained recipe

### Infrastructure and utilities
- **`/init-instance`** — Deploy all maintained recipes to the test server
- **`/test-context-reset`** — Undeploy all apps except traefik
- **`/switch-default-instance`** — Switch between test servers
- **`/sync-secrets`** — Sync secrets from the test server locally
- **`/opencode-sync`** — Sync Claude skills to OpenCode format

## Recommended workflow

1. **Daily check-in:** `/recipe-overview` to see what needs attention
2. **Upgrade a recipe:** `/recipe-check` → `/recipe-upgrade-plan` → review the plan → `/recipe-upgrade-apply`
3. **Day-to-day development:** edit a recipe locally → `/recipe-deploy` → `/recipe-test`
4. **Push when satisfied:** `cd ~/.abra/recipes/<name> && git push && git push --tags`

### Working with a recipe not yet in recipe-info?

Run `/recipe-init <recipe>` to set up tests for that recipe and a deployment to your local test instance.

### Developing a new recipe that doesn't exist yet?

Run `/new-recipe-guide` for detailed instructions on developing a new recipe from scratch.

## Next steps

- Run **`/test-setup`** to verify your environment is configured correctly (settings, SSH, abra CLI, connectivity).
- Run **`/setup-sandbox`** for guidance on setting up a sandboxed Docker environment to run Claude Code with this project — see also `sandbox/` for a reference implementation.