@hogsend/cli 0.1.0 → 0.2.1

package/skills/hogsend-database/references/migrations.md

@@ -0,0 +1,132 @@
+# Migrations — db:generate → db:migrate
+
+Your client track is plain Drizzle Kit. Three scripts ship in the scaffold's
+`package.json`:
+
+```jsonc
+{
+  "db:generate": "drizzle-kit generate",                          // diff schema -> ./migrations
+  "db:push":     "drizzle-kit push",                              // direct sync (dev shortcut)
+  "db:migrate":  "tsx --env-file-if-exists=.env scripts/migrate.ts" // engine THEN client
+}
+```
+
+## drizzle.config.ts (client track)
+
+Your `drizzle.config.ts` points Drizzle Kit at your schema, your migrations
+folder, and — critically — the **client** ledger, never the engine's:
+
+```ts
+// drizzle.config.ts
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  out: "./migrations",
+  schema: "./src/schema/index.ts",
+  dialect: "postgresql",
+  migrations: {
+    table: "__client_migrations", // client ledger — NOT __drizzle_migrations
+    schema: "drizzle",
+  },
+  dbCredentials: {
+    url:
+      process.env.DATABASE_URL ??
+      "postgresql://growthhog:growthhog@localhost:5434/growthhog",
+  },
+});
+```
+
+The `migrations.table: "__client_migrations"` line is what keeps your generated
+SQL on the client track and out of the engine's `drizzle.__drizzle_migrations`
+ledger.
+
+## The flow
+
+```bash
+# 1. Edit src/schema/index.ts (add/change a pgTable)
+
+# 2. Generate a client migration from the diff
+pnpm db:generate
+#    -> writes ./migrations/NNNN_<name>.sql
+#    -> updates ./migrations/meta/_journal.json + a snapshot
+
+# 3. Apply: engine track first, then your client track
+pnpm db:migrate
+```
+
+`pnpm db:migrate` runs `scripts/migrate.ts`, which calls `@hogsend/db`'s
+`migrateEngine(...)` and then `migrateClient(...)`:
+
+```ts
+// scripts/migrate.ts (scaffolded) — the shape, not for you to edit casually
+import { type JournalShape, migrateClient, migrateEngine } from "@hogsend/db";
+
+await migrateEngine(databaseUrl);                         // engine track first
+// resolve ./migrations + read meta/_journal.json, then:
+await migrateClient(databaseUrl, migrationsFolder, journal); // your client track
+```
+
+Engine runs first so your client migrations can safely reference engine tables.
+Both tracks run under a shared Postgres advisory lock, so concurrent deploys /
+replicas serialize instead of racing.
+
+## The `./migrations` directory + meta journal
+
+```
+migrations/
+  0000_init.sql          # your generated SQL
+  meta/
+    _journal.json        # ordered list of your migrations (idx/tag/when)
+    0000_snapshot.json   # Drizzle's snapshot for the next diff
+```
+
+`meta/_journal.json` is the source of truth for the client track. Its entries
+drive which client migrations `db:migrate` applies. **Commit the whole
+`migrations/` folder.** An empty journal (`{ entries: [] }`) means a trivially
+in-sync client track — fine if you have no client tables yet.
+
+### Surfacing client drift on `/v1/health` (opt-in wiring)
+
+The `schema.client` block on `GET /v1/health` is computed from a `clientJournal`
+you pass into `createHogsendClient`. It is **opt-in** — `createHogsendClient`
+defaults `clientJournal` to `{ entries: [] }`, so until you wire it the client
+track always reports `inSync: true` regardless of pending client migrations.
+Import your journal and thread it through in `src/index.ts`:
+
+```ts
+// src/index.ts
+import { createHogsendClient } from "@hogsend/engine";
+import journal from "../migrations/meta/_journal.json" with { type: "json" };
+import { buckets } from "./buckets/index.js";
+import { templates } from "./emails/index.js";
+import { journeys } from "./journeys/index.js";
+
+const client = createHogsendClient({
+  journeys,
+  buckets,
+  email: { templates },
+  clientJournal: journal, // now /v1/health.schema.client reflects YOUR migrations
+});
+```
+
+`clientJournal` is the only client-track wiring; `JournalShape` (the `{ entries }`
+type) is re-exported from `@hogsend/engine` if you need to annotate it. The
+engine never gates boot on it — it only feeds the non-fatal `/v1/health` block.
+
+## `db:push` — the dev shortcut (and its trap)
+
+`pnpm db:push` runs `drizzle-kit push`: it diffs `src/schema/index.ts` against
+the live database and applies the changes **directly**, without writing a
+migration file or a ledger row. Great for fast local iteration.
+
+The trap: `db:push` leaves the **ledger behind the actual schema**. A later
+`db:migrate` (or the boot guard) then sees migrations it thinks are pending even
+though the objects already exist. So:
+
+- **Local-only churn:** `db:push` is fine.
+- **Anything you intend to deploy:** use `db:generate` + `db:migrate`, never
+  `db:push`. Deployments apply migration files; a `push`-only change won't exist
+  in `./migrations` and won't ship.
+
+Recovering a database that drifted because of `db:push` is covered in
+`schema-drift.md`.

package/skills/hogsend-database/references/schema-drift.md

@@ -0,0 +1,123 @@
+# Schema drift — fatal engine track vs non-fatal client track
+
+"Drift" = the migrations a build requires don't match what's applied to the
+database. Hogsend treats the two tracks **asymmetrically**, and that asymmetry
+is the whole mental model.
+
+## The gating policy
+
+- **Engine track → FATAL at boot.** The running build hard-requires its bundled
+  engine schema. If the database is behind, the engine table you query may be
+  missing a column, so the app **refuses to start** rather than 500 later. A
+  database that is *ahead* of the build is fine (forward-compatible).
+- **Client track → NON-FATAL.** You own it. You may legitimately deploy app code
+  ahead of an additive client migration, and a pending client migration must not
+  take the whole API down. It surfaces (not blocks) on `/v1/health`.
+
+The boot guard lives in the scaffold's `src/index.ts` and checks only the engine
+track:
+
+```ts
+// src/index.ts (scaffolded boot guard)
+import { getEngineSchemaVersion } from "@hogsend/engine";
+
+if (process.env.SKIP_SCHEMA_CHECK !== "true") {
+  const schema = await getEngineSchemaVersion(client.db);
+  if (!schema.inSync) {
+    client.logger.error(
+      `Database schema is out of date: this build requires ${schema.required}, ` +
+        `database is at ${schema.applied ?? "(empty)"}. ` +
+        `Pending migration(s): ${schema.pending.join(", ") || "(unknown — is the DB reachable?)"}. ` +
+        "Run `pnpm db:migrate`, or set SKIP_SCHEMA_CHECK=true to bypass.",
+    );
+    await client.dbClient.end({ timeout: 5 });
+    process.exit(1);
+  }
+  client.logger.info(`Database schema in sync at ${schema.applied}`);
+}
+```
+
+Note it calls `getEngineSchemaVersion` (re-exported by `@hogsend/engine`) — the
+**client** track is deliberately NOT in the boot guard. `client.db` is the
+container's Drizzle instance; `client.dbClient` is the underlying postgres-js
+connection it closes before exiting.
+
+## Reading drift off `GET /v1/health`
+
+`/v1/health` reports both tracks. The top-level `status` is `migration_pending`
+if **either** track is behind:
+
+```jsonc
+{
+  "status": "migration_pending",        // healthy | degraded | migration_pending
+  "schema": {
+    "engine": { "applied": "0042_…", "required": "0042_…", "inSync": true,  "pending": [] },
+    "client": { "applied": "0000_init", "required": "0001_add_tickets",
+                "inSync": false, "pending": ["0001_add_tickets"] }
+  },
+  "components": { "database": { "status": "up" }, "redis": { "status": "up" } }
+}
+```
+
+- `schema.engine.inSync: false` should be impossible on a *running* app — the
+  boot guard would have exited. If you ever see it, the app was started with
+  `SKIP_SCHEMA_CHECK=true`.
+- `schema.client.inSync: false` is the normal "I haven't run `db:migrate` yet"
+  signal — non-fatal, but your responsibility to clear. **Note:** the client
+  block only reflects your migrations if you wired `clientJournal` into
+  `createHogsendClient` (it defaults to `{ entries: [] }` ⇒ always `inSync: true`).
+  See the `clientJournal` opt-in wiring in `migrations.md`.
+
+`status` decoding:
+
+| `status` | meaning |
+|---|---|
+| `healthy` | both tracks `inSync`, db + redis up |
+| `degraded` | both tracks `inSync`, but db or redis is down |
+| `migration_pending` | engine OR client track is behind |
+
+To check this from the CLI (any instance, local or prod) without parsing JSON by
+hand, use `hogsend doctor --json` — see the **hogsend-cli** skill. It hits the
+unauthenticated `/v1/health` and gives a drift verdict.
+
+## Fixing drift
+
+- **Client track behind** (the common case): `pnpm db:migrate`. If you changed
+  `src/schema/` but never generated, run `pnpm db:generate` first.
+- **Engine track behind** (app won't boot after a `@hogsend/*` bump): `pnpm
+  db:migrate` applies the new engine migrations that arrived with the bump, then
+  the boot guard passes.
+
+## `SKIP_SCHEMA_CHECK` — emergency bypass only
+
+`SKIP_SCHEMA_CHECK=true` makes `src/index.ts` skip the engine boot guard so the
+app starts even on a behind-engine database. Use it only to bring an instance up
+during an incident; it does NOT fix the schema, and the first query against a
+missing column will still fail. Clear the drift with `db:migrate` and remove the
+flag.
+
+## The `db:push` ledger trap (and recovery)
+
+A database bootstrapped with `pnpm db:push` has the schema objects but **no
+ledger rows** — so `db:migrate` and the boot guard think migrations are pending
+even though every object already exists, and you'll see `migration_pending` /
+"type already exists" errors.
+
+- **Client track:** since `db:push` is for throwaway local churn, the cleanest
+  fix is to reset that dev database and run `pnpm db:migrate` from clean, so the
+  ledger and schema agree. For anything real, generate + migrate from the start.
+- **Engine track:** `@hogsend/db` ships a `db:stamp` recovery tool that records
+  every bundled engine migration as *applied* WITHOUT running SQL — for the
+  exact case where a dev DB was `db:push`-ed and the engine ledger is behind a
+  schema that already matches HEAD. It is an engine-package script (run inside
+  `@hogsend/db`), not a consumer command, and it is dangerous if the schema is
+  genuinely missing objects (it would mark migrations applied without creating
+  them). Reach for a clean `db:migrate` first; only stamp when you are certain
+  the schema already matches HEAD.
+
+## Bottom line
+
+You can only cause **client-track** drift (it's the only track you author), and
+client-track drift never takes the app down — it just lights up
+`migration_pending` on `/v1/health` until you `pnpm db:migrate`. Engine-track
+drift is the engine's job to gate, and it does so fatally at boot.

package/skills/hogsend-deploy/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: hogsend-deploy
+description: Use when deploying or configuring production infra for YOUR scaffolded Hogsend app — Railway two services (api via railway.toml with /v1/health + pre-deploy db:migrate; worker via railway.worker.toml, no healthcheck), Hatchet-Lite, required vs optional env, and upgrading the engine + refreshing vendored skills. This is for shipping your own app, NOT the maintainer's package-release process.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Hogsend Deploy
+
+This skill helps you ship and operate YOUR scaffolded Hogsend app in
+production: standing up the two Railway services that ship in your repo, wiring
+the env Hogsend needs at boot, pointing at a Hatchet-Lite engine, and keeping
+your `@hogsend/*` deps + vendored agent skills on the latest line.
+
+This is the **consumer** deploy guide — for shipping the app you scaffolded with
+`create-hogsend`. It is NOT the maintainer's npm release / version-line process
+(that lives in the separate `release` skill).
+
+> These are side-effecting production operations — provisioning services,
+> writing secrets, running migrations against a real database, bumping deps.
+> Run each step deliberately and confirm intent before executing.
+
+## Key concepts
+
+- **Two services, one repo.** Your scaffold ships `railway.toml` (the HTTP
+  **api**) and `railway.worker.toml` (the Hatchet **worker**). Same codebase,
+  two Railway services with different config files.
+- **api owns migrations + healthcheck.** The api's `preDeployCommand` runs
+  `pnpm db:migrate` (two-track: engine then client) before boot; it exposes
+  `/v1/health`. The worker has no HTTP port, no healthcheck, and never migrates.
+- **Hatchet-Lite is your orchestration engine.** The worker connects to it over
+  gRPC with `HATCHET_CLIENT_TOKEN` + `HATCHET_CLIENT_HOST_PORT`. Locally it runs
+  via `docker-compose.yml`; in prod it's its own service.
+- **Three required env vars, the rest optional.** `DATABASE_URL`,
+  `BETTER_AUTH_SECRET`, `RESEND_API_KEY` are hard-required at boot; PostHog,
+  webhook secrets, and the admin key are opt-in.
+- **Upgrades move code + agent guidance together.** `hogsend upgrade` bumps
+  `@hogsend/*` AND refreshes the vendored `.claude/skills`; `hogsend doctor`
+  nudges you when those skills fall behind.
+
+## Task playbooks — load the matching reference
+
+- **Stand up / configure the two Railway services (api + worker), healthcheck,
+  pre-deploy migrate, Hatchet-Lite** → `references/railway-two-services.md`
+- **Decide which env vars are required vs optional and where each comes from** →
+  `references/env-and-secrets.md`
+- **Bump the engine after a release + refresh vendored skills (`hogsend upgrade`
+  / `--skills-only` / `skills add --all --force`, the `doctor` staleness nudge)**
+  → `references/upgrade-engine.md`
+
+## Golden rules
+
+1. Migrate exactly once per deploy: only the **api** service runs
+   `db:migrate` (its `preDeployCommand`). Never add a migrate step to the worker.
+2. Set the three required secrets BEFORE the first deploy — the app hard-fails
+   at boot without them, and the api healthcheck will never go green.
+3. After a deploy, verify with `hogsend doctor --url <prod> --json` and expect
+   an `ok` verdict with the schema in sync (see the hogsend-cli skill).
+4. After an engine bump, refresh the vendored skills in the same step so the
+   agent guidance matches the code you're now running.

package/skills/hogsend-deploy/references/env-and-secrets.md

@@ -0,0 +1,118 @@
+# Env & secrets
+
+Your scaffold ships a `.env.example` documenting every variable Hogsend reads.
+The engine validates env at startup (`@t3-oss/env-core`), so the three
+**required** vars must be present before the app will boot — otherwise the api
+crashes and its `/v1/health` healthcheck never goes green.
+
+This page is the prod-deploy view of that file: what's required, what's
+optional, and which service needs each.
+
+## Required at boot
+
+These three are hard-required everywhere (local and prod). Set them on **both**
+the api and worker services in Railway.
+
+```bash
+# Postgres connection string (TimescaleDB in prod).
+DATABASE_URL=postgresql://user:pass@host:5432/dbname
+
+# Better Auth signing secret — MINIMUM 32 characters. Generate a real random
+# value (the local bootstrap/setup flow mints one for you; never reuse the
+# placeholder from .env.example).
+BETTER_AUTH_SECRET=<random, >=32 chars>
+
+# Resend API key — required for any email send.
+RESEND_API_KEY=re_...
+```
+
+If any of these is missing or invalid, env validation throws at startup. On the
+api that means the healthcheck never passes; on the worker it means the process
+exits and Railway restart-loops it.
+
+## Core operational vars
+
+Not "secrets," but you'll want to set these explicitly in prod:
+
+```bash
+NODE_ENV=production            # disables /docs + /openapi.json
+PORT=3002                      # api HTTP port (Railway may inject its own)
+LOG_LEVEL=info
+
+REDIS_URL=redis://host:6379    # PostHog property cache
+
+# Public base URL of the deployed api — used to build unsubscribe + tracking
+# links inside outgoing emails, and as the tracking domain for click/open
+# rewriting. Set this to your real api domain or links will point at localhost.
+API_PUBLIC_URL=https://api.yourapp.com
+BETTER_AUTH_URL=https://api.yourapp.com
+
+# Default From address for sends.
+RESEND_FROM_EMAIL=noreply@yourapp.com
+
+# Which journeys load. "*" = all, or a comma-separated list of journey IDs.
+ENABLED_JOURNEYS=*
+```
+
+## Hatchet (worker + api)
+
+Both processes talk to your Hatchet-Lite service. Mint the token from the
+Hatchet dashboard and set these on the api AND the worker:
+
+```bash
+HATCHET_CLIENT_TOKEN=<token minted from the Hatchet dashboard>
+HATCHET_CLIENT_HOST_PORT=hatchet-host:7077
+HATCHET_CLIENT_TLS_STRATEGY=none   # or tls, per your Hatchet deployment
+```
+
+(Locally these point at the docker-compose Hatchet-Lite: `localhost:7077`,
+dashboard at `http://localhost:8888`, login `admin@example.com` / `Admin123!!`.)
+
+## Optional
+
+All commented-out in `.env.example` — add only what you use:
+
+```bash
+# PostHog person properties + event capture (no-op if unset).
+POSTHOG_API_KEY=phc_...
+POSTHOG_HOST=https://us.i.posthog.com
+
+# Verify incoming PostHog webhooks (POST /v1/webhooks/posthog).
+POSTHOG_WEBHOOK_SECRET=...
+
+# Verify Resend bounce/complaint webhooks.
+RESEND_WEBHOOK_SECRET=whsec_...
+
+# Required for the /v1/admin/* routes + CLI access. Without it, admin reads
+# (stats, contacts, journeys via the CLI) are unavailable in prod.
+ADMIN_API_KEY=...
+```
+
+Notes:
+
+- **PostHog is fully optional.** Without `POSTHOG_API_KEY`, person-property
+  fetches and event captures are no-ops — journeys still run.
+- **Webhook secrets are per-source.** Only set the secret for a webhook source
+  you've actually registered (see the consumer's `src/webhook-sources`).
+- **`ADMIN_API_KEY` gates `/v1/admin/*`.** Set it in prod if you want to drive
+  the deployed instance with the `hogsend` CLI (`stats`, `contacts`,
+  `journeys`). `hogsend doctor` hits the unauthenticated `/v1/health` and needs
+  no key. See the hogsend-cli skill for how the CLI resolves the key.
+
+## Service-by-service checklist
+
+| Var | api | worker |
+|-----|-----|--------|
+| `DATABASE_URL` | required | required |
+| `BETTER_AUTH_SECRET` | required | required |
+| `RESEND_API_KEY` | required | required |
+| `REDIS_URL` | yes | yes |
+| `API_PUBLIC_URL` / `BETTER_AUTH_URL` | yes | — |
+| `HATCHET_CLIENT_TOKEN` / `_HOST_PORT` / `_TLS_STRATEGY` | yes | yes |
+| `ENABLED_JOURNEYS` | yes | yes |
+| `POSTHOG_*` (optional) | if used | if used |
+| `*_WEBHOOK_SECRET` (optional) | if used | — |
+| `ADMIN_API_KEY` (optional) | if used | — |
+
+Set the shared/required vars on both services; the worker doesn't serve HTTP so
+it doesn't need the public-URL or webhook/admin vars.

package/skills/hogsend-deploy/references/railway-two-services.md

@@ -0,0 +1,122 @@
+# Railway: two services from one repo
+
+Your scaffolded app ships TWO Railway config files at the repo root. Deploy them
+as **two separate Railway services pointed at the same GitHub repo** — they
+share the codebase but run different processes with different config.
+
+| Service | Config file | Process | Healthcheck | Migrations |
+|---------|-------------|---------|-------------|------------|
+| api    | `railway.toml`        | HTTP API (`pnpm start`)  | `/v1/health` | runs `db:migrate` (pre-deploy) |
+| worker | `railway.worker.toml` | Hatchet worker (`pnpm worker`) | none (no HTTP port) | never |
+
+Both are driven by `git push` — pushing to your deploy branch triggers a build
+for whichever services watch the changed paths.
+
+## The api service (`railway.toml`)
+
+```toml
+[build]
+buildCommand = "pnpm build"
+watchPatterns = ["src/**", "migrations/**", "package.json", "pnpm-lock.yaml", "railway.toml"]
+
+[deploy]
+# Two-track migrate: engine track first, then this repo's client track.
+# scripts/migrate.ts runs both in order and skips an empty client track
+# gracefully. Engine MUST succeed before the API boots (boot guard in
+# src/index.ts hard-requires the engine schema).
+preDeployCommand = "pnpm db:migrate"
+startCommand = "pnpm start"
+healthcheckPath = "/v1/health"
+healthcheckTimeout = 120
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 3
+```
+
+Key points:
+
+- **`preDeployCommand = "pnpm db:migrate"`** runs BEFORE the new container takes
+  traffic. It is two-track: the engine schema migrates first (the api's boot
+  guard in `src/index.ts` hard-requires it), then your client track. An empty
+  client track is skipped gracefully, so this works whether or not you've added
+  your own migrations under `src/schema`.
+- **`healthcheckPath = "/v1/health"`** — Railway holds traffic until this route
+  returns healthy. The route reports component status (database, redis) and the
+  two-track schema state, which is exactly what `hogsend doctor` reads.
+  `healthcheckTimeout = 120` gives migrations + boot time to settle.
+- **Restart policy** retries on failure up to 3 times.
+
+When this service is healthy, point your public domain (e.g.
+`api.yourapp.com` via a CNAME) at it.
+
+## The worker service (`railway.worker.toml`)
+
+```toml
+[build]
+buildCommand = "pnpm build"
+watchPatterns = ["src/**", "package.json", "pnpm-lock.yaml", "railway.worker.toml"]
+
+[deploy]
+# No healthcheck — the worker has no HTTP port. Migrations are owned by the API
+# service's preDeployCommand; the worker just executes Hatchet tasks.
+startCommand = "pnpm worker"
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 5
+```
+
+Key points:
+
+- **No `healthcheckPath`** — the worker is a long-running process with no HTTP
+  port, so there's nothing to probe. Don't add one; a healthcheck that can never
+  pass would keep the deploy from going green.
+- **No `preDeployCommand`** — migrations are owned solely by the api service.
+  The worker just connects to Hatchet and executes tasks (`sendEmailTask`,
+  `importContactsTask`, `checkAlertsTask`, plus your enabled journey tasks and
+  any `extraWorkflows`).
+- **`startCommand = "pnpm worker"`** runs the production worker entry
+  (`src/worker.ts` → `createWorker({ container, journeys })`).
+- **It scales independently** of the api — add worker replicas to process more
+  Hatchet tasks in parallel without touching the api.
+
+### Pointing Railway at the worker config
+
+A Railway service builds from a single config file. To make the second service
+use `railway.worker.toml` instead of the default `railway.toml`, set the service
+config-file path in the Railway dashboard (Service → Settings → Config-as-code /
+Railway config file) to `railway.worker.toml`.
+
+## Hatchet-Lite
+
+Hatchet orchestrates durable task execution (email sends, journey runs,
+background jobs). The api process pushes events to it; the worker process
+executes the tasks it routes.
+
+- **Locally** it runs via `docker-compose.yml` (started by `pnpm bootstrap` or
+  `hogsend setup`): dashboard on `:8888`, gRPC on `:7077`, with its own
+  Postgres 15. Default dashboard login: `admin@example.com` / `Admin123!!`.
+- **In production** Hatchet-Lite is its own Railway service (the
+  `ghcr.io/hatchet-dev/hatchet/hatchet-lite:latest` image). Both the api and the
+  worker connect to it via `HATCHET_CLIENT_TOKEN` + `HATCHET_CLIENT_HOST_PORT`
+  (and `HATCHET_CLIENT_TLS_STRATEGY`). Mint the token from the Hatchet
+  dashboard.
+
+See `references/env-and-secrets.md` for the exact Hatchet env keys and which
+services need them.
+
+## Deploy → verify loop
+
+1. Set the required secrets on **both** services first (see
+   `references/env-and-secrets.md`). The api won't pass its healthcheck without
+   `DATABASE_URL` / `BETTER_AUTH_SECRET` / `RESEND_API_KEY`.
+2. Push to your deploy branch. Railway builds the api (runs `pnpm db:migrate`
+   pre-deploy) and the worker.
+3. Verify the live api with the CLI:
+
+   ```bash
+   hogsend doctor --url https://api.yourapp.com --json
+   ```
+
+   Expect an `ok` verdict with `database`/`redis` up and the engine + client
+   schema in sync. A `migration_pending` verdict means the pre-deploy migrate
+   didn't catch up — re-check the api's pre-deploy logs. `unreachable` means the
+   healthcheck never went green (often a missing required secret). See the
+   hogsend-cli skill for the full doctor playbook.

package/skills/hogsend-deploy/references/upgrade-engine.md

@@ -0,0 +1,92 @@
+# Upgrade the engine + refresh vendored skills
+
+Hogsend is a versioned engine you consume as a dependency. After a new engine
+release you want your app's `@hogsend/*` deps AND the vendored Claude Code
+skills under `.claude/skills` to move together — so the code you run and the
+agent guidance that drives it stay in lockstep.
+
+> This is a side-effecting operation: it bumps dependencies and rewrites files
+> in `.claude/skills`. Run it deliberately, review the diff, and re-test before
+> deploying.
+
+## One step: `hogsend upgrade`
+
+```bash
+hogsend upgrade
+```
+
+This does both halves in order:
+
+1. **Bumps every `@hogsend/*` dependency** declared in your `package.json`
+   (`dependencies` + `devDependencies`) to `latest`, using the package manager
+   detected from your lockfile.
+2. **Refreshes the vendored skills** in `./.claude/skills` to match, then
+   version-stamps them so `hogsend doctor` can later tell when they fall behind.
+
+If the dependency bump hard-fails, the skills refresh is skipped (fix the bump,
+then re-run) — the two never drift apart silently.
+
+### Useful flags
+
+```bash
+hogsend upgrade --to 1.4.0      # pin a specific target instead of latest
+hogsend upgrade --pm pnpm       # force a package manager (default: from lockfile)
+hogsend upgrade --cwd ./apps/x  # run against a different project root
+hogsend upgrade --deps-only     # bump deps only; leave skills untouched
+hogsend upgrade --skills-only   # refresh skills only; don't touch deps
+hogsend upgrade --yes           # skip the confirmation prompt
+hogsend upgrade --json          # non-interactive, single JSON result (implies --yes)
+```
+
+`--deps-only` and `--skills-only` are mutually exclusive.
+
+## Refresh skills on their own
+
+If you only need to re-vendor the bundled skills (e.g. you bumped the engine by
+hand, or want the latest guidance without changing versions), use either:
+
+```bash
+hogsend upgrade --skills-only        # refresh + re-stamp via upgrade
+hogsend skills add --all --force     # copy every bundled skill, overwriting
+```
+
+`hogsend skills add --all --force` copies all bundled skills into
+`./.claude/skills/<name>/`, overwriting existing copies (`--force` is what makes
+it overwrite rather than skip), and re-stamps the installed set. Without
+`--force`, already-installed skills are skipped. You can also target one skill:
+
+```bash
+hogsend skills list                  # see what's bundled + what's installed
+hogsend skills add hogsend-cli --force
+```
+
+## The `hogsend doctor` staleness nudge
+
+`hogsend doctor` (the health probe; see the hogsend-cli skill) does a
+best-effort check: if your vendored skills were installed by an OLDER CLI than
+the one now running, it prints a nudge:
+
+```
+Skills out of date
+Vendored Claude skills are from v1.2.0; this CLI is v1.4.0.
+Refresh: hogsend upgrade (deps + skills) or hogsend skills add --all --force.
+```
+
+This is silent when there's no stamp (not a tracked app dir) and suppressed in
+`--json` mode (the staleness verdict is still surfaced under the `skills` key of
+the JSON output instead). Treat the nudge as your signal to run `hogsend
+upgrade`.
+
+## After upgrading
+
+1. Review the dependency + `.claude/skills` diff.
+2. Re-run your type-check / tests against the new engine line.
+3. Re-deploy (push to your deploy branch — see
+   `references/railway-two-services.md`). The api's pre-deploy `db:migrate`
+   applies any new engine migrations that came with the bump.
+4. Verify the live instance with `hogsend doctor --url <prod> --json` and
+   confirm the schema is in sync.
+
+> This is the **consumer** upgrade flow for your own app. It is NOT the
+> maintainer's npm release / version-line process for publishing `@hogsend/*` —
+> that's the separate `release` skill.