@hogsend/cli 0.0.1 → 0.2.0

package/skills/hogsend-authoring-journeys/references/journey-meta.md

@@ -0,0 +1,142 @@
+# JourneyMeta — trigger, entryLimit, exitOn, suppress
+
+`meta` is the static declaration of who enters a journey, how often, and what
+pulls them out. It is the `JourneyMeta` type from `@hogsend/core`:
+
+```ts
+interface JourneyMeta {
+  id: string;                 // stable unique id — used for state + ENABLED_JOURNEYS
+  name: string;               // human label (becomes user.journeyName)
+  description?: string;
+  enabled: boolean;           // master on/off for this journey
+
+  trigger: {
+    event: string;            // the event name that enrolls a user
+    where?: PropertyCondition[]; // optional gate on event properties
+  };
+
+  entryLimit: "once" | "once_per_period" | "unlimited";
+  entryPeriod?: DurationObject; // required-in-practice for once_per_period
+
+  exitOn?: Array<{
+    event: string;
+    where?: PropertyCondition[];
+  }>;
+
+  suppress: DurationObject;   // declared cool-down (required field; see note)
+}
+```
+
+## Fields in detail
+
+### `trigger.event`
+
+The event name that enrolls a user. Each journey declares `onEvents:
+[trigger.event]` on its Hatchet durable task, so when `POST /v1/ingest` (or a
+webhook source) pushes that event, Hatchet routes it straight to this journey.
+Use a constant from your `src/journeys/constants/`:
+
+```ts
+trigger: { event: Events.USER_CREATED },
+```
+
+### `trigger.where` (optional)
+
+A `PropertyCondition[]` evaluated against the **enrolling event's properties**.
+If present and not met, the event is skipped with reason
+`trigger_conditions_not_met`. Use it to enroll only a slice of an event:
+
+```ts
+trigger: {
+  event: Events.USER_CREATED,
+  where: [{ property: "plan", operator: "equals", value: "pro" }],
+},
+```
+
+For the full operator set and how `PropertyCondition` is shaped, see the
+**hogsend-conditions** skill.
+
+### `entryLimit` + `entryPeriod`
+
+Controls re-entry:
+
+- `"once"` — a user can ever enter this journey exactly one time. A second
+  matching event is skipped (`already_entered_once`). Checked against ALL prior
+  states for the user+journey, regardless of completion.
+- `"once_per_period"` — re-entry allowed only after `entryPeriod` has elapsed
+  since the user's most recent enrollment. Defaults to `hours(24)` if
+  `entryPeriod` is omitted, so set it explicitly:
+  ```ts
+  entryLimit: "once_per_period",
+  entryPeriod: days(7),
+  ```
+- `"unlimited"` — every matching event enrolls (subject to the active-state
+  guard below). Good for test/smoke journeys.
+
+### `exitOn` (optional)
+
+Events that pull a user OUT of any in-flight run of this journey. Evaluated by
+the ingestion pipeline whenever a new event arrives for a user with an active
+journey state — if the incoming event name matches an `exitOn` rule (and its
+optional `where` passes), the active run is exited:
+
+```ts
+exitOn: [
+  { event: Events.USER_DELETED },
+  { event: "subscription.cancelled", where: [{ property: "reason", operator: "equals", value: "churn" }] },
+],
+```
+
+### `suppress`
+
+A **required** `DurationObject` field declaring an intended cool-down before
+re-entry. Note: the engine's enrollment gates do NOT currently read `suppress` —
+actual re-entry timing is enforced by `entryLimit` + `entryPeriod` (above). It is
+stored as journey metadata and surfaced on the admin journeys API. Treat it as
+the declarative cool-down you pair with `entryLimit` (e.g.
+`entryLimit: "once_per_period"`, `entryPeriod: days(7)`, `suppress: hours(12)`);
+use `hours(0)` on `"unlimited"` test journeys. Because it is required, always set
+it — `hours(0)` when you mean "none".
+
+### `enabled`
+
+Master switch. `enabled: false` makes every enrollment skip with reason
+`journey_disabled`. (Admins can ALSO disable a journey at runtime via a
+`journeyConfigs` override — that yields `journey_disabled_by_admin`. Toggle that
+at runtime with the **hogsend-cli** skill's `journeys enable/disable`.)
+
+## The 4-gate enrollment order
+
+When the trigger event arrives, the journey task runs these gates IN ORDER
+before `run()` executes. Any failing gate returns `{ status: "skipped", reason }`
+and creates NO state:
+
+1. **`meta.enabled`** (and the admin `journeyConfigs` override) →
+   `journey_disabled` / `journey_disabled_by_admin`.
+2. **`trigger.where`** against the event properties → `trigger_conditions_not_met`.
+3. **`entryLimit`** (`checkEntryLimit`) → `already_entered_once` /
+   `period_not_elapsed`.
+4. **Email preferences** (`checkEmailPreferences`) — if the user is unsubscribed
+   from all → `user_unsubscribed`.
+
+After the gates, an **active-state guard** prevents concurrent enrollment: if a
+state in status `active` or `waiting` already exists for this user+journey, the
+event is skipped (`already_active`). This is why a single user never has two
+overlapping runs of the same journey.
+
+## State transitions
+
+A `journeyStates` row tracks each run. Once the gates pass:
+
+- **enter** → row created with `status: "active"`, `currentNodeId: "start"`.
+- **`ctx.sleep` / `ctx.sleepUntil`** → `status: "waiting"` for the duration, back
+  to `"active"` on resume.
+- **`run()` returns** → `status: "completed"`, `completedAt` set, and a
+  `journey:completed` event is pushed.
+- **`run()` throws** → `status: "failed"`, `errorMessage` recorded, and a
+  `journey:failed` event is pushed; the error re-throws so Hatchet sees the
+  failure.
+
+Because the gates run before any state is created, a skipped event is invisible
+in `journeyStates` — to debug "why didn't this user enroll?", check the gate
+order above and inspect events with the **hogsend-cli** skill.

package/skills/hogsend-authoring-journeys/references/register-a-journey.md

@@ -0,0 +1,99 @@
+# Registering a journey
+
+Defining a journey is not enough — it has to be in the `journeys` array that the
+client and worker receive. Both processes (HTTP API + Hatchet worker) must see
+the same array: the API needs it to route ingested events, the worker needs it to
+register the durable task that actually runs `run()`.
+
+## 1. Export from `src/journeys/index.ts`
+
+Add your journey to the `journeys` array (and re-export it for tests / direct
+reference):
+
+```ts
+import type { DefinedJourney } from "@hogsend/engine";
+import { activation } from "./activation.js";
+import { testOnboarding } from "./test-onboarding.js";
+import { welcome } from "./welcome.js";
+
+export const journeys: DefinedJourney[] = [
+  welcome,
+  testOnboarding,
+  activation,            // <-- your new journey
+];
+
+export { activation, testOnboarding, welcome };
+```
+
+The exported `journeys` array is the single source of truth that both entry
+points consume.
+
+## 2. It is already threaded into the client + worker
+
+In a scaffolded app both entry points import that same array — you usually do
+NOT need to touch these files, just confirm they pass `journeys`:
+
+```ts
+// src/index.ts  (HTTP API)
+import { createApp, createHogsendClient } from "@hogsend/engine";
+import { buckets } from "./buckets/index.js";
+import { templates } from "./emails/index.js";
+import { journeys } from "./journeys/index.js";
+import { webhookSources } from "./webhook-sources/index.js";
+
+const client = createHogsendClient({ journeys, buckets, email: { templates } });
+const app = createApp(client, { webhookSources });
+```
+
+```ts
+// src/worker.ts  (Hatchet worker — this is what runs run())
+import { createHogsendClient, createWorker } from "@hogsend/engine";
+import { buckets } from "./buckets/index.js";
+import { templates } from "./emails/index.js";
+import { journeys } from "./journeys/index.js";
+import { extraWorkflows } from "./workflows/index.js";
+
+const client = createHogsendClient({ journeys, buckets, email: { templates } });
+const worker = createWorker({ container: client, journeys, buckets, extraWorkflows });
+await worker.start();
+```
+
+If you build a new entry point or a test harness, the rule is: **pass the same
+`journeys` array to both `createHogsendClient({ journeys })` and
+`createWorker({ container, journeys })`.** A journey missing from the worker is
+defined but never executes; missing from the client and ingested events won't
+route to it. (`buckets` and `extraWorkflows` are the sibling content arrays the
+scaffold threads through the same way — pass them when present.)
+
+## 3. (Optional) `ENABLED_JOURNEYS`
+
+The `ENABLED_JOURNEYS` env var filters which registered journeys actually load —
+comma-separated ids, or `*` (or empty/unset) for all:
+
+```bash
+# only these two run; everything else is registered but inert
+ENABLED_JOURNEYS=welcome,activation
+
+# all journeys (default)
+ENABLED_JOURNEYS=*
+```
+
+The filter matches on `meta.id`, so keep ids stable. It is applied identically
+when building the registry (client) and when selecting durable tasks (worker), so
+a journey is either fully on or fully off across both processes. Use it to ship a
+journey's code but keep it dark until you flip the env var — distinct from
+`meta.enabled: false` (code-level off) and the runtime admin toggle (see the
+**hogsend-cli** skill's `journeys enable/disable`).
+
+## Checklist for a new journey
+
+1. New file in `src/journeys/` using `defineJourney({ meta, run })`.
+2. Any new event / template keys added to `src/journeys/constants/`.
+3. New email? component + registry entry under `src/emails/` for each
+   `Templates.*` key you send.
+4. Journey added to the `journeys` array in `src/journeys/index.ts`.
+5. Confirm `src/index.ts` and `src/worker.ts` both receive that array.
+6. If gating by env, add the id to `ENABLED_JOURNEYS`.
+
+To smoke-test it end-to-end against a running instance (enroll a user, watch the
+state reach `completed`), use the **hogsend-cli** skill.

package/skills/hogsend-authoring-journeys/references/sending-email-from-a-journey.md

@@ -0,0 +1,82 @@
+# Sending email from a journey
+
+`sendEmail()` is a **standalone import from `@hogsend/engine`** — it is NOT a
+method on `ctx`. It renders the template, checks the user's email preferences,
+rewrites links + injects the open pixel (tracking), writes the `email_sends` row,
+and hands off to the provider. You just call it with a template key and props.
+
+```ts
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "./constants/index.js";
+
+export const welcome = defineJourney({
+  meta: { /* ... */ },
+  run: async (user, ctx) => {
+    await sendEmail({
+      to: user.email,                         // recipient
+      userId: user.id,                        // external id (for prefs + tracking)
+      journeyStateId: user.stateId,           // attributes the send to THIS run
+      template: Templates.ACTIVATION_WELCOME, // a key from your emails registry
+      subject: "Welcome — let's get you set up",
+      journeyName: user.journeyName,          // shows on the send record / tags
+      props: { firstName: user.properties.firstName }, // template props (optional)
+    });
+  },
+});
+```
+
+## The options (`SendEmailOptions`)
+
+```ts
+interface SendEmailOptions {
+  to: string;                          // required — recipient email
+  userId: string;                      // required — external user id
+  template: string;                    // required — registry key (use Templates.*)
+  subject: string;                     // required
+  journeyName?: string;                // attribution label (defaults to template)
+  journeyStateId?: string;             // pass user.stateId to tie to this run
+  props?: Record<string, unknown>;     // props handed to the template component
+}
+```
+
+`name` is auto-derived if you don't pass it: `props.firstName` → `props.name` →
+the local-part of the email → `"there"`. So a template that renders `{name}`
+always has something. Pass `firstName` in `props` for a real name.
+
+## The result (`SendEmailResult`)
+
+```ts
+interface SendEmailResult {
+  emailSendId: string;   // id of the email_sends row — keep it if you need to correlate
+  sentAt: string;        // ISO timestamp
+}
+
+const { emailSendId, sentAt } = await sendEmail({ /* ... */ });
+```
+
+## Template keys must exist in your registry
+
+`template` is a `Templates.*` constant from your `src/journeys/constants/`. Each
+key must resolve to a real template in `src/emails/` — the constant value (e.g.
+`"activation/welcome"`) is the registry key. If you send a new email, first add:
+
+1. the template component + registry entry under `src/emails/`,
+2. the matching `Templates` key in `src/journeys/constants/`,
+
+then reference it here as `Templates.YOUR_KEY`. A mismatched key fails at render
+time, not compile time, so keep them in lockstep.
+
+## Preferences, tracking, and idempotency
+
+- `sendEmail` checks the user's email preferences internally; an unsubscribed
+  user is not emailed. You do not need to gate it — though after a long
+  `ctx.sleep` it is good practice to branch on `ctx.guard.isSubscribed()` first
+  (see `references/branch-on-engagement.md`).
+- Link-click + open tracking is applied automatically by the engine mailer —
+  you get it regardless of which provider is configured.
+- `sendEmail` is **not** itself deduped — calling it twice sends twice. Guard
+  repeat sends with `ctx.history.email({ email, template })` when a journey can
+  re-run a step.
+
+For SMS / push / Slack, import the relevant standalone sender — those are also
+plain function imports, never on `ctx`.

package/skills/hogsend-cli/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: hogsend-cli
+description: Use when an agent needs to inspect or operate a running Hogsend lifecycle engine — querying metrics/contacts/events, listing or enabling/disabling journeys, checking health, or onboarding a local instance — by driving the consolidated `hogsend` CLI. Every data command supports --json for machine-readable output.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Hogsend CLI
+
+The `hogsend` CLI is the agent-native interface to a Hogsend app (the
+code-first lifecycle orchestration engine on PostHog + Resend). It wraps the
+app's `/v1/admin/*` and `/v1/health` HTTP routes, so it works against ANY
+running instance — local (`http://localhost:3002`) or production — without
+importing the database.
+
+## The --json contract (READ THIS FIRST)
+
+Every data/read command takes a global `--json` flag. In `--json` mode the
+command prints EXACTLY ONE valid JSON document to stdout and nothing else — no
+spinners, no color, no prose. **Always pass `--json` when you are parsing the
+output programmatically.** Without it, you get a human-pretty table/keyvalue
+rendering meant for a terminal.
+
+```bash
+hogsend stats --json
+hogsend journeys list --json
+hogsend contacts get user_123 --json
+```
+
+On error in `--json` mode the CLI prints `{"error":"<message>"}` to stdout and
+exits 1. On success it exits 0 (doctor is the exception — see below).
+
+## Connecting to an instance
+
+Two global flags / env vars control which instance you talk to:
+
+- Base URL: `--url <baseUrl>` > `HOGSEND_API_URL` env > `.env` `HOGSEND_API_URL`
+  > default `http://localhost:3002`.
+- Admin key: `--admin-key <key>` > `HOGSEND_ADMIN_KEY` env > `ADMIN_API_KEY`
+  env > the `.env` equivalents. Sent as `Authorization: Bearer <key>`.
+
+```bash
+hogsend stats --url https://api.example.com --admin-key "$ADMIN_API_KEY" --json
+```
+
+`doctor` hits the unauthenticated `/v1/health` and needs no admin key. Every
+other data command requires one.
+
+## Command map
+
+| Command | Purpose |
+|---------|---------|
+| `hogsend doctor` | Health + schema-drift verdict (reachability check). |
+| `hogsend stats` | Overview metrics (contacts, emails, bounce/unsub rates). |
+| `hogsend journeys list/get/enable/disable` | Inspect + toggle journeys. |
+| `hogsend contacts list/get/timeline` | Inspect contacts + their activity. |
+| `hogsend events <userId>` | Raw event stream for one user. |
+| `hogsend skills list/add` | Manage these bundled agent skills. |
+| `hogsend upgrade` | Bump `@hogsend/*` deps to latest + refresh vendored skills. |
+| `hogsend setup` | Interactive LOCAL onboarding (docker, secret, migrate). |
+| `hogsend eject <pkg>` | Vendor a `@hogsend/*` package (unchanged). |
+| `hogsend patch <pkg>` | Wrap `pnpm patch` (unchanged). |
+
+Run `hogsend <command> --help` for per-command usage.
+
+## Task playbooks (load the matching reference)
+
+- **Query metrics / analyse data** → `references/query-stats.md`
+- **List, inspect, enable or disable journeys** → `references/manage-journeys.md`
+- **Debug why a user did / didn't enroll** → `references/debug-a-journey.md`
+- **Set up a local instance** → `references/setup-local.md`
+
+## Golden rules for agents
+
+1. Pass `--json` whenever you will parse output. Never screen-scrape the table.
+2. Start a debugging session with `hogsend doctor --json` to confirm the
+   instance is reachable and the schema is in sync before trusting other reads.
+3. Enabling/disabling a journey is a write — confirm intent first.
+4. Use `--limit`/`--offset` for pagination instead of dumping everything.

package/skills/hogsend-cli/references/debug-a-journey.md

@@ -0,0 +1,66 @@
+# Debug a journey: why did (or didn't) a user enroll?
+
+A repeatable trace using `doctor` + `journeys get` + `contacts timeline` +
+`events`. Run every command with `--json` and read the output.
+
+## Step 0 — confirm the instance is healthy
+
+```bash
+hogsend doctor --json
+```
+
+Wraps `GET /v1/health`. Inspect the verdict:
+
+- `ok` — healthy, proceed.
+- `degraded` — a component (database / redis) is unhealthy; reads may be
+  unreliable. Exit code 1.
+- `migration_pending` — the engine schema and the client schema are out of
+  sync (`schema.inSync = false`, `pending` migrations listed). Data may be
+  missing columns; fix the drift before trusting other queries.
+- `unreachable` — could not connect (HTTP status 0). Check `--url` and that the
+  app is running. Exit code 1.
+
+Do NOT trust downstream reads until doctor returns `ok`.
+
+## Step 1 — understand the journey's entry rules
+
+```bash
+hogsend journeys get <journeyId> --json
+```
+
+Read the `trigger` (which event enrolls a user) and any `trigger.where`
+property conditions. Read `exitOn` rules (what removes a user). Enrollment is
+gated, in order, by: `enabled` flag → trigger `where` conditions → entry limit
+(once / once_per_period / unlimited) → email preferences (unsubscribed users
+are skipped). Any failed gate means NO enrollment.
+
+## Step 2 — look at the user's lifecycle
+
+```bash
+hogsend contacts get <userId> --json        # subscribed? unsubscribed?
+hogsend contacts timeline <userId> --json    # merged events/emails/journeys
+```
+
+The timeline shows whether the user already has an active/completed state for
+this journey (entry limit may have blocked re-entry) and whether they're
+unsubscribed (which skips email-sending journeys).
+
+## Step 3 — verify the trigger event actually fired with the right props
+
+```bash
+hogsend events <userId> --event <triggerEvent> --json
+```
+
+Wraps `GET /v1/admin/events?userId=<userId>`. Confirm the trigger event exists
+for this user AND that its properties satisfy the journey's `trigger.where`
+conditions. A missing event, or an event whose properties fail the `where`
+check, is the most common reason a user did not enroll.
+
+## Decision tree
+
+- No trigger event in `events` → upstream isn't sending it (PostHog / webhook).
+- Trigger event present but `where` mismatch → property condition not met.
+- Already has a journey state → entry limit blocked re-enrollment.
+- Contact unsubscribed → email journeys skipped at the preferences gate.
+- Journey `enabled: false` (from `journeys get`) → no enrollment at all.
+- `doctor` not `ok` → fix infra/schema first; the data is suspect.

package/skills/hogsend-cli/references/manage-journeys.md

@@ -0,0 +1,53 @@
+# Manage journeys
+
+Inspect and toggle lifecycle journeys on a running Hogsend instance. `list` and
+`get` are read-only; `enable`/`disable` are writes.
+
+## List
+
+```bash
+hogsend journeys list --json
+hogsend journeys list --enabled true --limit 50 --offset 0 --json
+```
+
+Wraps `GET /v1/admin/journeys`. Filter with `--enabled <true|false>`, paginate
+with `--limit`/`--offset`. Each row carries `id`, `name`, `enabled`, the
+trigger event, and enrollment counts (active / completed / failed). Use the
+`id` for every other journey command.
+
+## Get detail
+
+```bash
+hogsend journeys get conversion-trial-upgrade --json
+```
+
+Wraps `GET /v1/admin/journeys/{id}`. Returns the full definition view —
+trigger (event + optional `where` conditions), `exitOn` rules, aggregate
+counts, and a sample of recent `journeyStates` (so you can see who is currently
+active / waiting / completed). This is your starting point before toggling a
+journey.
+
+## Enable / disable
+
+```bash
+hogsend journeys enable conversion-trial-upgrade --json
+hogsend journeys disable conversion-trial-upgrade --json
+```
+
+Wraps `PATCH /v1/admin/journeys/{id}` with `{ "enabled": true|false }`.
+
+Safety notes:
+
+- These are WRITES against a live system. Confirm the journey `id` with
+  `journeys get` first, and confirm intent with the human before disabling a
+  journey that has active enrollments.
+- Disabling stops NEW enrollments. Contacts already mid-journey continue per
+  the engine's semantics — disabling is not a kill switch for in-flight states.
+- After toggling, re-run `journeys get <id> --json` and confirm `enabled`
+  flipped as expected.
+
+## Counts cheatsheet
+
+When reading counts: `active` = currently enrolled (may be sleeping/waiting),
+`completed` = finished the run, `failed` = errored. A journey with rising
+`failed` counts is worth a `debug-a-journey` pass.

package/skills/hogsend-cli/references/query-stats.md

@@ -0,0 +1,66 @@
+# Query metrics, contacts, and events
+
+Read-only analysis over a running Hogsend instance. Always pass `--json` when
+parsing.
+
+## Overview metrics
+
+```bash
+hogsend stats --json
+```
+
+Wraps `GET /v1/admin/metrics/overview`. Returns (shape may vary slightly by
+version):
+
+```json
+{
+  "totalContacts": 1234,
+  "activeJourneys": 5,
+  "emailsSent24h": 88,
+  "emailsSent7d": 540,
+  "emailsSent30d": 2100,
+  "bounceRate30d": 0.012,
+  "unsubscribeRate": 0.004
+}
+```
+
+Use this for a one-shot snapshot. `bounceRate30d` / `unsubscribeRate` are
+fractions (multiply by 100 for a percentage). A rising bounce rate is the first
+signal of a deliverability problem.
+
+## Contacts
+
+```bash
+# List with search + pagination
+hogsend contacts list --search "@acme.com" --limit 50 --offset 0 --json
+
+# A single contact by internal id OR externalId
+hogsend contacts get user_123 --json
+
+# Merged activity timeline (events + emails + journeys) for one contact
+hogsend contacts timeline user_123 --json
+```
+
+Wraps `GET /v1/admin/contacts`, `GET /v1/admin/contacts/{id}`, and
+`GET /v1/admin/contacts/{id}/timeline`. `get` includes the contact record plus
+email preferences (subscribed / unsubscribed). The timeline is the fastest way
+to understand a single user's lifecycle history.
+
+## Raw event stream
+
+```bash
+hogsend events user_123 --json
+hogsend events user_123 --event "checkout.completed" --from 2026-01-01T00:00:00Z --to 2026-02-01T00:00:00Z --limit 100 --json
+```
+
+Wraps `GET /v1/admin/events?userId=<userId>`. Filter by `--event`, time window
+(`--from`/`--to`, ISO 8601), and paginate with `--limit`/`--offset`. Use this
+when the timeline isn't granular enough and you need the exact event payloads
+(e.g. to see which properties were present when a journey trigger fired).
+
+## Analysis pattern
+
+1. `hogsend stats --json` for the macro picture.
+2. `hogsend contacts list --search ... --json` to find the cohort.
+3. `hogsend contacts timeline <id> --json` to understand individual journeys.
+4. `hogsend events <id> --event <name> --json` to inspect exact payloads.

package/skills/hogsend-cli/references/setup-local.md

@@ -0,0 +1,52 @@
+# Set up a local Hogsend instance
+
+`hogsend setup` is interactive LOCAL onboarding — it mirrors the "next steps"
+that `create-hogsend` prints after scaffolding. It is NOT a Railway / cloud
+deploy flow.
+
+## Run it
+
+```bash
+hogsend setup
+```
+
+What it does (interactively, with clack prompts + spinners):
+
+1. `docker compose up -d` — starts TimescaleDB (Postgres), Redis, and
+   Hatchet-Lite locally.
+2. Generates a `BETTER_AUTH_SECRET`.
+3. Copies `.env.example` to `.env` if `.env` doesn't already exist (it won't
+   clobber an existing `.env`).
+4. Runs `db:migrate` to apply the database schema.
+
+Run it from your Hogsend project root (the directory with `docker-compose.yml`
+and `.env.example`).
+
+## Verify
+
+After setup, confirm the instance is healthy and the schema is in sync:
+
+```bash
+hogsend doctor --json
+```
+
+Expect a `ok` verdict with `database` and `redis` components healthy and
+`schema.inSync = true`. If you see `migration_pending`, re-run the migration
+step; if `unreachable`, the API isn't running yet — start it with `pnpm dev`
+(default port 3002), then re-run doctor.
+
+## Typical first session
+
+```bash
+hogsend setup            # docker up, secret, .env, migrate
+pnpm dev                 # start the API on :3002 (separate terminal)
+hogsend doctor --json    # confirm ok
+hogsend stats --json     # sanity-check metrics endpoint
+```
+
+## Notes
+
+- `setup` is interactive by design; in a non-interactive / agent context,
+  prefer running the underlying steps explicitly and then `hogsend doctor`.
+- The admin key for local reads comes from your `.env` (`ADMIN_API_KEY` or
+  `HOGSEND_ADMIN_KEY`); `doctor` itself needs no key.