@catapultjs/deploy 0.9.0 → 0.11.0

package/skills/catapultjs/references/api.md

@@ -0,0 +1,70 @@
+# Using the Catapult programmatic API
+
+The `Catapult` class exposes the same operations as the `cata` CLI, without any interactive prompt. Full docs: https://catapultjs.com/guide/programmatic
+
+```typescript
+import { Catapult } from '@catapultjs/deploy'
+import '@catapultjs/deploy/recipes/git'
+import '@catapultjs/deploy/recipes/pm2'
+
+const catapult = new Catapult({
+  hosts: [{ name: 'production', ssh: 'deploy@example.com', deployPath: '/home/deploy/myapp' }],
+})
+
+await catapult.deploy()
+```
+
+Rules that differ from a `deploy.ts`:
+
+- Import recipes **before** constructing, exactly like in a config file.
+- The constructor takes the same object as `defineConfig()`: `hosts`, `keepReleases`, `repository`, `packageManager`, `hooks`, `verbose`.
+- One `Catapult` instance per process. The deploy context is global; a second instance with a different config is not supported.
+- No prompts: methods either act or throw. Catch errors instead of expecting confirmation flows.
+
+## Methods
+
+All server-targeting methods accept `{ hosts?: string[] }` (default: all configured hosts; unknown names throw before anything runs).
+
+| Method | Returns | CLI equivalent |
+| --- | --- | --- |
+| `setup(options?)` | `void` | `cata deploy:setup` |
+| `deploy(options?)` | `void` | `cata deploy` |
+| `rollback({ hosts?, release? })` | `void` | `cata rollback` |
+| `task(name, options?)` | `TaskOutput[]` (`{ host, output }`) | `cata task <name>` |
+| `status(options?)` | `HostStatus[]` | `cata status --json` |
+| `listReleases(options?)` | `{ name, current, releases }[]` | `cata list:releases --json` |
+| `listRevisions({ hosts?, limit? })` | `{ name, revisions }[]` | `cata list:revisions --json` |
+| `listTasks()` | `{ pipeline, extra }` of `{ name, description }` | `cata list:tasks --json` |
+| `pipeline()` | `string[]` | `cata pipeline --json` |
+
+Behavior notes:
+
+- `deploy()` generates a fresh release name on every call, runs the full pipeline, applies the CLI's auto-rollback on failure, then rethrows. Hosts must be initialized first (`setup()`), otherwise it throws.
+- `task()` runs against the **currently deployed release** and returns what the task wrote through its `logger`, one entry per host. Display tasks (`pm2:logs`, `pm2:list`, …) report their result this way; output may contain ANSI codes. Tasks built from queued `run()` commands return an empty `output`.
+- `status()` never throws on SSH failure; the affected host entry gets an `error` field instead. Data returned by recipes' `onStatus` hooks is merged into each host entry.
+
+## Events
+
+`Catapult` is an `EventEmitter`. `deploy()` and `task()` emit:
+
+- `task:start`, `task:done` — `{ host, task }`
+- `task:error` — `{ host, task, error }`
+- `host:done` — `{ host, release }` (deploy only)
+
+```typescript
+catapult.on('host:done', ({ host, release }) => notify(`${host} → ${release}`))
+```
+
+## Silent mode
+
+By default Catapult logs progress to stdout like the CLI. For programs that rely on events and return values only:
+
+```typescript
+import { Verbose } from '@catapultjs/deploy/enums'
+
+const catapult = new Catapult({ verbose: Verbose.SILENT, hosts: […] })
+```
+
+## Lower-level functions
+
+When the class is too coarse, the primitives are exported from `@catapultjs/deploy` and take an explicit `DeployContext` + `Host`: `deployHost()`, `rollbackHost()`, `initializeHost()`, `isHostSetup()`, `getCurrentRelease()`, `getReleaseNames()`, `getRevisions()`, `collectHostStatus()`, `runTask(name, ctx, host, { logger? })`.

package/skills/catapultjs/references/cli.md

@@ -0,0 +1,160 @@
+# Catapult CLI reference
+
+The CLI is `cata`, invoked via `npx cata <command>`. Full docs: https://catapultjs.com/guide/cli
+
+## Config loading
+
+`version` and `init` work without a config file. All other commands load `deploy.ts`, `deploy.config.ts`, `deploy.js`, or `deploy.config.js` from the current directory, or use `--config <path>` / `-c <path>` to specify another file.
+
+## Global options
+
+| Option | Description |
+| --- | --- |
+| `--config <path>`, `-c <path>` | Load a specific deploy config file |
+| `--host <name>`, `-H <name>` | Target a specific host (available on all host-aware commands) |
+| `--help` | Show help for the current command |
+
+## Commands
+
+### `deploy:setup` (alias: `setup`)
+
+Creates the remote directory structure and runs recipe setup hooks. Must be run once before the first deploy.
+
+```bash
+npx cata deploy:setup
+npx cata setup --host production
+npx cata setup -H staging
+```
+
+### `deploy` (alias: `dep`)
+
+Runs the full deployment pipeline. Prompts to run `deploy:setup` if the host is not initialized.
+
+| Option | Description |
+| --- | --- |
+| `--branch <name>`, `-b <name>` | Override the branch for this deployment |
+| `-v`, `-vv`, `-vvv` | Increase verbosity |
+
+```bash
+npx cata deploy
+npx cata deploy --host production
+npx cata deploy --branch feature/my-feature
+npx cata dep -H staging -b develop
+npx cata deploy --config deploy.staging.ts
+```
+
+### `rollback`
+
+Restores the previous release. With `--interactive`, prompts to choose the target release. Automatic rollback also triggers after a failure past `deploy:publish`.
+
+| Option | Description |
+| --- | --- |
+| `--interactive`, `-i` | Choose the target release interactively |
+
+```bash
+npx cata rollback
+npx cata rollback --interactive
+npx cata rollback -i -H production
+```
+
+### `status`
+
+Shows current release, healthcheck, runtime versions, revision metadata, and lock state. With `--json`, targets all hosts by default and writes aggregated JSON to stdout (errors to stderr).
+
+| Option | Description |
+| --- | --- |
+| `--json` | Output result as JSON |
+
+```bash
+npx cata status
+npx cata status --host production
+npx cata status --json
+```
+
+### `task <task-name>`
+
+Runs a registered task against the current release. Requires an existing release on each target host. Use `list:tasks` first to see available task names.
+
+| Option | Description |
+| --- | --- |
+| `-v`, `-vv`, `-vvv` | Increase verbosity |
+
+```bash
+npx cata list:tasks
+npx cata task deploy:build
+npx cata task deploy:unlock
+npx cata task deploy:restart -H production
+npx cata task deploy:healthcheck -vv
+```
+
+### `run "<command>"`
+
+Executes a shell command on the selected hosts over SSH. Quote the command string.
+
+```bash
+npx cata run "pm2 list"
+npx cata run "pm2 reload all" --host production
+npx cata run "ls -lah current" -H staging
+```
+
+### `ssh`
+
+Opens an interactive SSH session in `deployPath` on the selected host. Prompts to choose when several hosts are configured and `--host` is omitted.
+
+```bash
+npx cata ssh
+npx cata ssh --host production
+```
+
+### `list:releases`
+
+Lists all releases on the target hosts, marking the current one.
+
+```bash
+npx cata list:releases
+npx cata list:releases --host production
+npx cata list:releases --json
+```
+
+### `list:revisions`
+
+Shows the last 10 logged revisions from `.catapult/revisions.log`.
+
+```bash
+npx cata list:revisions
+npx cata list:revisions --host production
+npx cata list:revisions --json
+```
+
+### `list:tasks`
+
+Lists all pipeline tasks and extra registered tasks from the loaded config.
+
+```bash
+npx cata list:tasks
+```
+
+### `pipeline`
+
+Shows the current deployment pipeline task order.
+
+```bash
+npx cata pipeline
+npx cata pipeline --json
+```
+
+### `init`
+
+Generates a starter `deploy.ts` in the current directory. No config required.
+
+```bash
+npx cata init
+```
+
+### `version`
+
+Prints the installed `@catapultjs/deploy` version. No config required.
+
+```bash
+npx cata version
+```

package/skills/catapultjs/references/config.md

@@ -0,0 +1,194 @@
+# Writing a Catapult deploy config
+
+The config file is auto-detected as `deploy.ts`, `deploy.js`, `deploy.config.ts` or `deploy.config.js` at the project root (override with `cata --config <path>`). It must default-export `defineConfig()`. Full reference: https://catapultjs.com/guide/api
+
+## Before creating a config
+
+If the user asks to create or configure a deployment and the repo/prompt does not provide enough information, ask for the missing deployment facts before writing files. Do not guess real production values such as SSH hostnames, deploy paths, domains, branches, or healthcheck URLs.
+
+Use project inspection first:
+
+- `package.json` scripts and dependencies identify the stack and package manager.
+- Framework config files identify variants: `next.config.*` (`standalone` vs `export`), `nuxt.config.*`, `astro.config.*`, `vite.config.*`, `adonisrc.ts`, `nest-cli.json`.
+- Existing `ecosystem.config.cjs` means `recipes/pm2` is likely wanted.
+- Existing `.env.example`, `storage/`, `uploads/`, `public/`, or app-specific folders can suggest shared paths, but confirm anything destructive or production-specific.
+
+Ask a compact set of questions for missing values:
+
+1. Which environment and server? Need host name, SSH target (`user@host`), and absolute `deployPath`.
+2. How should code reach the server? Use default SCP when uploading `source_path` is enough; choose `git` when the server can access the repository; choose `rsync` when rsync-based sync/delete behavior is preferred.
+3. Which branch or source path should deploy?
+4. Should PM2 be configured? If yes, confirm app name, start entry, port, and whether to create `ecosystem.config.cjs`.
+5. Is there a healthcheck URL and any extra shared files or directories?
+
+When the user answers, generate `deploy.ts` with the selected recipes and put `set(...)` calls before the recipe imports they configure.
+
+```typescript
+import { defineConfig } from '@catapultjs/deploy'
+import '@catapultjs/deploy/recipes/git'
+import '@catapultjs/deploy/recipes/pm2'
+
+export default defineConfig({
+  hosts: [
+    {
+      name: 'production',
+      ssh: 'deploy@example.com',
+      deployPath: '/home/deploy/myapp',
+      branch: 'main',
+    },
+  ],
+})
+```
+
+## Code delivery
+
+Catapult registers a default `deploy:update_code` task that uploads `source_path` via SCP. Recipes can override that task when a different delivery mechanism is needed. Pick one delivery mode:
+
+| Recipe | Delivery | Use for |
+| --- | --- | --- |
+| default `deploy:update_code` | Uploads `source_path` via SCP | Simple local upload, static recipes that set `source_path` |
+| `recipes/git` | Clones the repo on the server (bare mirror in `.catapult/repo`) | Server can reach the repo, build on server |
+| `recipes/rsync` | Pushes a local directory into the release | Local builds, no repo access from server |
+| `recipes/adonisjs_local` | Builds AdonisJS locally, uploads the artifact | AdonisJS without building on the server |
+| `recipes/vitepress` | Builds locally, uploads the static output | VitePress static sites |
+| custom `task('deploy:update_code', …)` | Whatever you implement | Anything else |
+
+Avoid combining providers that override `deploy:update_code` (`git`, `rsync`, `adonisjs_local`, `vitepress`, custom) unless intentionally replacing task behavior.
+
+## Picking recipes by stack
+
+Inspect the project (`package.json`, lock file, config files) before choosing:
+
+- **Next.js**: `nextjs` for standalone server builds on the server (pair with `git` or `rsync`); `nextjs_static` for static export built locally and uploaded from `./out/.` using default SCP unless `rsync` is imported.
+- **Nuxt**: `nuxt` for server builds on the server (pair with `git` or `rsync`); `nuxt_static` for local static generation uploaded from `./.output/public/.` using default SCP unless `rsync` is imported.
+- **Astro**: `astro` for standalone server builds on the server (pair with `git` or `rsync`); `astro_static` for static sites built locally and uploaded from `./dist/.` using default SCP unless `rsync` is imported.
+- **TanStack Start**: `tanstack` for server builds on the server (pair with `git` or `rsync`); configure Vite with Nitro `node-server`.
+- **NestJS**: `nestjs` wires standard install/build on the server (pair with `git` or `rsync`).
+- **AdonisJS**: `adonisjs` (installs and builds on the server, exposes `ace:*` migration tasks; pair with `git` or `rsync`) or `adonisjs_local` (build locally, upload).
+- **VitePress**: `vitepress` builds locally and uploads the static output.
+- **Process manager**: add `pm2` if the app runs under PM2 (`ecosystem.config.cjs` expected in the project). It wires restart after publish and adds `pm2:*` tasks plus a status report.
+- **Extras**: `directus` (DB migrations and schema snapshots), `redis` (`redis:db:flush*` tasks, configure with `set('redis_db', n)`).
+
+Recipes register their tasks at import time: imports must appear before or inside the config file, never lazily.
+
+## Config options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `hosts` | `Host[]` | Required |
+| `keepReleases?` | `number` | Default `5` |
+| `repository?` | `string` | Auto-detected from git origin |
+| `packageManager?` | `PackageManager` | Auto-detected from lock file |
+| `hooks?` | `Hooks` | See below |
+| `verbose?` | `Verbose` | From `@catapultjs/deploy/enums`: `SILENT`, `NORMAL`, `TRACE` (default), `DEBUG` |
+
+## Host options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `name` | `string` | Identifier used by `--host` / `hosts:` selectors |
+| `ssh` | `string \| SshConfig` | `'user@host'` or `{ user, host, port? }` |
+| `deployPath` | `string` | Absolute path on the server |
+| `branch?` | `string \| { name, ask }` | `ask: true` prompts at deploy time (CLI only) |
+| `healthcheck?` | `{ url?, retries?, delayMs? }` | Curl check after publish; the `deploy:healthcheck` task is removed automatically when no host defines a `url` |
+| `bin?` | `Record<string, string>` | Per-host binary paths, e.g. `{ node: '/home/deploy/.nvm/versions/node/v24.0.0/bin/node' }`. Needed when binaries are not on the non-interactive SSH PATH (nvm setups) |
+
+Multiple environments are just multiple hosts (`production`, `staging`); target one with `cata deploy -H staging`.
+
+## Lifecycle hooks
+
+All optional, all `(ctx: { host?, hosts?, error? }) => Promise<void>`:
+
+```typescript
+export default defineConfig({
+  hosts: […],
+  hooks: {
+    beforeDeploy: async ({ hosts }) => {},      // once, before all hosts
+    beforeHostDeploy: async ({ host }) => {},   // per host
+    afterHostDeploy: async ({ host }) => {},    // per host, even on failure
+    afterFailure: async ({ hosts, error }) => {}, // on error, before rethrow
+    afterDeploy: async ({ hosts }) => {},       // once, after success
+  },
+})
+```
+
+## Pipeline customisation
+
+The config file is a regular module: pipeline and store calls work alongside `defineConfig()`.
+
+Default pipeline order: `deploy:lock` → `deploy:release` → `deploy:update_code` → `deploy:shared` → `deploy:publish` → `deploy:log_revision` → `deploy:healthcheck` → `deploy:unlock` → `deploy:cleanup`. Inspect with `cata pipeline`. Reference: https://catapultjs.com/guide/pipeline
+
+Three built-in tasks are registered but NOT inserted by default. Insert them instead of writing custom install/build/test tasks:
+
+```typescript
+import { after } from '@catapultjs/deploy'
+
+after('deploy:update_code', 'deploy:install') // package manager install
+after('deploy:install', 'deploy:build')      // pm run build
+after('deploy:build', 'deploy:test')         // pm run test
+```
+
+Pipeline functions: `after(existing, task)`, `before(existing, task)`, `remove(name)`, `inPipeline(name)` to place a task relative to optional steps, `setPipeline([…])` to replace the whole sequence. Insertion deduplicates: re-adding a task moves it, the last position wins.
+
+```typescript
+import { set, after, inPipeline, remove, task, run, cd } from '@catapultjs/deploy'
+
+set('writable_dirs', ['logs', 'tmp/uploads'])  // created under shared/ at setup
+set('shared_files', ['.env'])                   // touched under shared/ at setup
+set('rsync_source_path', './dist')              // rsync recipe option
+
+task('app:warmup', () => {
+  cd('{{current_path}}')
+  run('curl -s localhost:3333/health')
+})
+
+// healthcheck is removed automatically when no host defines one
+if (inPipeline('deploy:healthcheck')) {
+  after('deploy:healthcheck', 'app:warmup')
+} else {
+  after('deploy:publish', 'app:warmup')
+}
+```
+
+Custom tasks can also be async functions receiving the `TaskContext` (e.g. `fetch` a Slack webhook with the `release` name). Run any registered task manually with `cata task <name>`.
+
+### Rewriting the whole pipeline
+
+`setPipeline()` replaces the sequence entirely, for full control over the order:
+
+```typescript
+import { defineConfig, setPipeline } from '@catapultjs/deploy'
+import '@catapultjs/deploy/recipes/git'
+import '@catapultjs/deploy/recipes/pm2'
+
+setPipeline([
+  'deploy:lock',
+  'deploy:release',
+  'deploy:update_code',
+  'deploy:install',
+  'deploy:build',
+  'deploy:shared',
+  'deploy:publish',
+  'pm2:startOrReload',
+  'deploy:unlock',
+  'deploy:cleanup',
+])
+
+export default defineConfig({ hosts: […] })
+```
+
+Rules:
+
+- Call it AFTER the recipe imports: recipes run their own `after()`/`before()` insertions at import time, and `setPipeline()` must have the last word.
+- Every name must be a registered task (built-in or from an imported recipe), otherwise the deploy fails at that step with "Task not found".
+- Keep `deploy:lock`/`deploy:unlock` unless concurrent deploys are acceptable, and `deploy:log_revision` if `list:revisions` and revision metadata matter.
+- Omitting `deploy:cleanup` disables release pruning (`keepReleases` has no effect then).
+
+## Checklist
+
+1. `defineConfig()` is the default export.
+2. Delivery mode is intentional: default SCP, or one overriding provider such as `git`, `rsync`, `adonisjs_local`, `vitepress`, or a custom `deploy:update_code`.
+3. Recipe store options (`set(…)`) match the imported recipes.
+4. Healthcheck URLs point to an endpoint reachable from the server itself.
+5. Pin the package version in `package.json` (the API is still in beta).
+6. Verify with `cata pipeline` (task order) and `cata list:tasks` (registered tasks), then `cata deploy:setup` before the first deploy.

package/skills/catapultjs/references/github-actions.md

@@ -0,0 +1,99 @@
+# GitHub Actions with Catapult
+
+Use the official `catapultjs/deploy-action` to run Catapult inside GitHub Actions. The action handles SSH setup, detects the package manager from the lockfile, installs dependencies, and runs the requested Catapult command.
+
+Full docs: https://catapultjs.com/guide/ci-cd
+
+## Minimal workflow
+
+```yaml
+name: Deploy
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: catapultjs/deploy-action@v0.5.0
+        with:
+          command: deploy
+          config: deploy.ts
+          private-key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+          known-hosts: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+          version: latest
+```
+
+## Workflow with a custom runtime
+
+Add `actions/setup-node` (or pnpm/bun setup) before the action when the project needs a specific Node version.
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 24
+    cache: npm
+
+- uses: catapultjs/deploy-action@v0.5.0
+  with:
+    command: deploy
+    config: deploy.ts
+    private-key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+    known-hosts: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+    version: latest
+    working-directory: .
+```
+
+## Action inputs
+
+| Name | Default | Description |
+| --- | --- | --- |
+| `command` | `deploy` | Catapult command to run (`deploy`, `rollback`, `task <name>`, etc.) |
+| `config` | — | Path to the deploy config file |
+| `args` | — | Extra CLI args, one per line |
+| `package-manager` | auto-detected | `npm`, `pnpm`, `yarn`, or `bun` |
+| `version` | `latest` | Version of `@catapultjs/deploy` to install |
+| `working-directory` | `.` | Working directory relative to the repository root |
+
+## SSH inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `private-key` | Yes | SSH private key added to `ssh-agent` |
+| `known-hosts` | Recommended | Content written to `~/.ssh/known_hosts` |
+| `ssh-config` | No | Content written to `~/.ssh/config` |
+| `insecure-ignore-host-key` | No | Disables strict host key checking |
+
+## Reading sensitive config from environment variables
+
+Keep SSH host and path out of `deploy.ts` by reading them from env vars, then passing them from the workflow:
+
+```ts
+// deploy.ts
+const ssh = process.env.DEPLOY_SSH
+const deployPath = process.env.DEPLOY_PATH
+if (!ssh) throw new Error('Missing DEPLOY_SSH')
+if (!deployPath) throw new Error('Missing DEPLOY_PATH')
+
+export default defineConfig({
+  hosts: [{ name: 'production', ssh, deployPath, branch: process.env.DEPLOY_BRANCH || 'main' }],
+})
+```
+
+```yaml
+- uses: catapultjs/deploy-action@v0.5.0
+  with:
+    command: deploy
+    private-key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+    known-hosts: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+  env:
+    DEPLOY_SSH: ${{ secrets.DEPLOY_SSH }}
+    DEPLOY_PATH: ${{ vars.DEPLOY_PATH }}
+    DEPLOY_BRANCH: main
+    DEPLOY_USER: ${{ github.actor }}
+```
+
+Use GitHub **Secrets** for sensitive values (SSH key, host string) and **Variables** for non-sensitive ones (deploy path). `DEPLOY_USER` is picked up by `deploy:log_revision` when `git config user.name` is unavailable on the runner.

package/skills/catapultjs/references/recipe.md

@@ -0,0 +1,115 @@
+# Writing a Catapult recipe
+
+A recipe is a JavaScript/TypeScript module that registers tasks and inserts them into the deployment pipeline as a side effect of being imported. Users activate it with a bare import in their `deploy.ts`:
+
+```typescript
+import './recipes/my-recipe.ts'
+```
+
+Full docs: https://catapultjs.com/guide/creating-recipes
+
+## Conventions
+
+- Namespace every task with a recipe prefix: `my-recipe:build`, not `build`.
+- Call `desc('…')` immediately before each `task()` so the task shows a description in `cata list:tasks`.
+- Tasks that queue remote commands use the DSL (`cd()`, `run()`); tasks that need command output or conditionals use `ssh()` directly with `set -e` and `q()` for quoting.
+- Resolve binaries with `bin('node')` instead of hardcoding, so users can override paths per host via `host.bin`.
+- Expose recipe options through the store (`get()`/`set()`), never through module-level mutable state.
+
+## Basic structure
+
+```typescript
+import { type TaskContext, task, desc, cd, run, after, bin } from '@catapultjs/deploy'
+import { ssh, q } from '@catapultjs/deploy/utils'
+
+// TypeScript: register task names for autocompletion
+declare module '@catapultjs/deploy' {
+  interface TaskRegistry {
+    'my-recipe:build': true
+  }
+}
+
+desc('Builds the application in the release directory')
+task('my-recipe:build', () => {
+  cd('{{release_path}}')
+  run(`${bin('node')} --run build`)
+})
+
+// Insert into the pipeline (deduplicated: re-adding moves the task)
+after('deploy:update_code', 'my-recipe:build')
+```
+
+Pipeline functions: `after(existing, newTask)`, `before(existing, newTask)`, `remove(name)`, `inPipeline(name)`, `getPipeline()`, `setPipeline(tasks)`.
+
+Default pipeline: `deploy:lock`, `deploy:release`, `deploy:update_code`, `deploy:shared`, `deploy:publish`, `deploy:log_revision`, `deploy:healthcheck`, `deploy:unlock`, `deploy:cleanup`. Recipes may override a built-in task by registering the same name (e.g. `git`/`rsync` recipes provide `deploy:update_code`).
+
+Use `inPipeline()` to attach relative to optional steps (`deploy:healthcheck` is removed when no host defines one). Insertion deduplicates: re-adding a task moves it, the last position wins.
+
+Three tasks are registered but not inserted: `deploy:install` (package manager install), `deploy:build` (`pm run build`), `deploy:test` (`pm run test`). Prefer inserting or overriding them over inventing new install/build tasks, like the `adonisjs` and `nuxt` recipes do.
+
+## Task context and raw SSH
+
+The task function receives a `TaskContext`: `{ host, paths, config, release, logger }`. Use it for output capture or host-specific logic:
+
+```typescript
+desc('Shows service logs')
+task('my-recipe:logs', async ({ host, paths, logger }: TaskContext) => {
+  const { stdout } = await ssh(host, `set -e\ncd ${q(paths.current)}\nmy-service logs --tail 50`)
+  logger.log(stdout.trim())
+})
+```
+
+Always write display output through `ctx.logger` (not `console.log`): the programmatic API captures it and returns it from `catapult.task()`.
+
+`paths` fields: `base`, `releases`, `release`, `current`, `shared`, `cataConfig`, `repo`, `builder`, `lock`.
+
+Template variables in `cd()`/`run()` strings: `{{release_path}}`, `{{current_path}}`, `{{shared_path}}`, `{{releases_path}}`, `{{base_path}}`, `{{release}}`.
+
+Other DSL helpers: `local(command, { cwd? })` runs on the local machine, `upload(localPath, remotePath)` / `download(remotePath, localPath)` transfer over SCP, `isVerbose(level)` checks verbosity.
+
+## Hooks
+
+`onSetup()` runs during `cata deploy:setup`, after base directories exist:
+
+```typescript
+import { onSetup } from '@catapultjs/deploy'
+import { ssh, q, getPaths } from '@catapultjs/deploy/utils'
+
+onSetup(async (ctx, host, logger) => {
+  const paths = getPaths(host.deployPath, ctx.release)
+  await ssh(host, `set -e\nmkdir -p ${q(paths.shared + '/storage')}`)
+  logger.step(host.name, 'storage ready')
+})
+```
+
+`onStatus()` runs during `cata status`. Return an object: each key becomes an aligned line in text mode and is merged into the host entry of `status --json` and `catapult.status()`. Output written via the `logger` argument only appears in text mode.
+
+```typescript
+import { onStatus } from '@catapultjs/deploy'
+
+onStatus(async (_ctx, host) => {
+  const { stdout } = await ssh(host, `set +e\nmy-service --version || true`)
+  return { 'my-service': stdout.trim() || 'unavailable' }
+})
+```
+
+## Configurable options
+
+```typescript
+import { task, run, get } from '@catapultjs/deploy'
+
+task('my-recipe:sync', () => {
+  const excludes = get<string[]>('my_recipe_excludes', [])
+  run(`rsync ${excludes.map((e) => `--exclude=${e}`).join(' ')} …`)
+})
+```
+
+Users set values in `deploy.ts` with `set('my_recipe_excludes', […])` before or after the import. Two store keys have built-in meaning during setup: `writable_dirs` (string[], created under `shared/`) and `shared_files` (string[], touched under `shared/`).
+
+## Checklist before shipping
+
+1. Tasks namespaced and described with `desc()`.
+2. `TaskRegistry` augmented for TypeScript users.
+3. Remote commands quoted with `q()` and prefixed with `set -e` (or `set +e` when failure is expected).
+4. Display tasks write to `ctx.logger`, status hooks return data objects.
+5. Reusable recipes can be contributed to the `contrib/` directory of https://github.com/catapultjs/deploy via pull request.