@hogsend/cli 0.0.1 → 0.2.0

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.

package/skills/hogsend-webhooks-and-workflows/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: hogsend-webhooks-and-workflows
+description: Use when adding an inbound webhook source in src/webhook-sources/ (defineWebhookSource — auth header + envKey, optional Zod schema, transform(payload, ctx) -> IngestEvent | null, served at POST /v1/webhooks/:id) or a custom Hatchet task in src/workflows/ passed as extraWorkflows (NOT workflows) to createWorker, including the idempotent batched expand→migrate→contract backfill pattern.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Hogsend webhooks & workflows
+
+This skill covers the two extension points a scaffolded Hogsend app uses to take
+in external events and run background jobs:
+
+1. **Webhook sources** — turn an inbound HTTP payload into an `IngestEvent` that
+   flows through the engine's ingestion pipeline (and can trigger journeys).
+2. **Custom Hatchet tasks** — durable background work (one-off jobs, backfills,
+   cron-style maintenance) registered alongside the engine's built-in workflows.
+
+You are editing a **content-only consumer**: you import everything from
+`@hogsend/engine` (and `@hogsend/db` for tasks). Never edit engine internals.
+Relative imports use the ESM `.js` extension.
+
+## Capability map / key concepts
+
+- **`defineWebhookSource({ meta, auth, schema?, transform })`** (from
+  `@hogsend/engine`) — declares one source served at `POST /v1/webhooks/:id`.
+  `auth` matches a request header against an env secret; `schema` is an optional
+  Zod validator; `transform(payload, ctx)` returns an `IngestEvent | null`
+  (`null` = accept-and-skip). Register sources in `src/webhook-sources/index.ts`
+  and pass them to `createApp(client, { webhookSources })` in `src/index.ts`.
+- **`IngestEvent`** — the shape `transform` must return:
+  `{ event, userId, userEmail, properties, idempotencyKey? }`. The route feeds it
+  straight into `ingestEvent()`, so a webhook can enroll users into journeys.
+- **Custom Hatchet tasks** — define with `hatchet.task({ name, fn })` (or
+  `hatchet.durableTask` for event-driven/long-running work), export from
+  `src/workflows/index.ts` in the `extraWorkflows` array, and pass it as
+  `createWorker({ ..., extraWorkflows })` — the option is **`extraWorkflows`,
+  NOT `workflows`**. Never list the engine's built-ins (send-email,
+  import-contacts, check-alerts, bucket tasks) — those register automatically.
+- **JSON-serializable IO** — task input AND return value must serialize to JSON.
+  Use specific keys or `JsonValue`-compatible types; do **not** use a
+  `[key: string]: unknown` index signature.
+- **Backfill pattern** — `runBatchedBackfill()` (from `@hogsend/engine`) drives a
+  long data migration in small, idempotent, lock-friendly batches from inside a
+  task — the supported home for bulk data changes (never inside a schema
+  migration). Follow expand → migrate → contract across releases.
+
+## Task playbooks — load the matching reference
+
+- **Adding / editing an inbound webhook source** → load
+  `references/webhook-source.md` (defineWebhookSource fields, the `transform` →
+  `ingestEvent` contract, auth matching, registration + `createApp` wiring).
+- **Writing a custom Hatchet task (one-off job, cron, event-driven)** → load
+  `references/custom-workflow.md` (`hatchet.task`/`durableTask`,
+  JSON-serializable IO, export from `index.ts`, `createWorker({ extraWorkflows })`).
+- **Backfilling a new column on existing rows** → load
+  `references/backfill-pattern.md` (the idempotent batched
+  expand→migrate→contract job from the template example).
+
+## Cross-skill pointers
+
+- A webhook's `transform` only needs to emit the right `event`/`properties`;
+  whether a journey then enrolls or exits is decided by trigger/exit conditions —
+  see the **hogsend-conditions** skill for `where`/`exitOn`/criteria and duration
+  helpers.
+- To verify a webhook or task against a running instance (events landing,
+  contacts upserted, journeys firing), see the **hogsend-cli** skill.

package/skills/hogsend-webhooks-and-workflows/references/backfill-pattern.md

@@ -0,0 +1,148 @@
+# Reference: the idempotent batched backfill
+
+When a release adds a column that needs populating on existing rows, **do not**
+put the data change inside a schema migration — that holds locks and runs
+unbounded against a live database. Instead, drive it from a Hatchet task using
+`runBatchedBackfill` (from `@hogsend/engine`), which runs the migration in small,
+idempotent, lock-friendly batches that are **resumable**: if the process dies,
+re-running continues from where it left off because each batch only selects rows
+that still need work.
+
+The scaffold ships a ready-to-customize template at
+`src/workflows/backfill-example.ts`.
+
+## Expand → migrate → contract
+
+Sequence the change across releases so old and new code can run side by side:
+
+1. **Release N (expand)** — the migration adds the column (nullable / defaulted);
+   code writes BOTH the old and new shape. Deploy.
+2. **Run the backfill task once** (Hatchet dashboard, or push its event) to
+   populate existing rows. It's batched, idempotent and resumable.
+3. **Release N+1** — code reads the new column.
+4. **Release N+2 (contract)** — once the backfill is confirmed complete, a
+   migration drops the old column / adds `NOT NULL`.
+
+## `runBatchedBackfill` — the driver
+
+```ts
+interface BatchedBackfillOptions {
+  db: Database;
+  logger: { info: (m: string) => unknown; warn: (m: string) => unknown };
+  label: string;            // human label for logs, e.g. "contacts.normalized_email"
+  runBatch: (db: Database, batchSize: number) => Promise<number>; // rows affected; 0 = done
+  batchSize?: number;       // default 500
+  pauseMs?: number;         // default 0 — pause between batches to relieve a live DB
+  maxBatches?: number;      // default 100_000 — safety cap, logs + stops (not an error)
+}
+
+interface BatchedBackfillResult {
+  batches: number;
+  rows: number;
+  exhausted: boolean;       // true only when a batch returned 0 (ran to completion)
+}
+```
+
+The two rules that make it safe:
+
+- **`runBatch` MUST be idempotent and self-bounding.** It should touch only rows
+  that still need the change (e.g. `WHERE new_col IS NULL ... LIMIT n`) and return
+  the number of rows affected. Return `0` when nothing is left — that's the signal
+  to stop (`exhausted: true`).
+- **Lock-friendly batches.** Select the batch with `FOR UPDATE SKIP LOCKED` so
+  concurrent runs/workers don't fight over the same rows, and keep `batchSize`
+  small so each statement holds locks only briefly.
+
+## The template task
+
+`src/workflows/backfill-example.ts` — assumes a release just added
+`contacts.normalized_email`. Change the table/columns to match your migration:
+
+```ts
+import { createDatabase } from "@hogsend/db";
+import { createLogger, hatchet, runBatchedBackfill } from "@hogsend/engine";
+import { sql } from "drizzle-orm";
+
+export const backfillExampleTask = hatchet.task({
+  name: "backfill-example",
+  retries: 2,
+  executionTimeout: "30m",
+  fn: async () => {
+    const { db, client } = createDatabase({ url: process.env.DATABASE_URL ?? "" });
+    const logger = createLogger(process.env.LOG_LEVEL ?? "info");
+
+    try {
+      const result = await runBatchedBackfill({
+        db,
+        logger,
+        label: "contacts.normalized_email",
+        batchSize: 500,
+        pauseMs: 50,
+        runBatch: async (database, limit) => {
+          // Bounded, idempotent batch: only rows that still need it, locked with
+          // SKIP LOCKED so concurrent runs/workers don't fight over the same rows.
+          const updated = (await database.execute(sql`
+            WITH batch AS (
+              SELECT id FROM contacts
+              WHERE normalized_email IS NULL
+              LIMIT ${limit}
+              FOR UPDATE SKIP LOCKED
+            )
+            UPDATE contacts c
+            SET normalized_email = lower(trim(c.email))
+            FROM batch
+            WHERE c.id = batch.id
+            RETURNING c.id
+          `)) as unknown as unknown[];
+          return updated.length;
+        },
+      });
+
+      // Return a plain JSON object so Hatchet can serialize the task output.
+      return {
+        batches: result.batches,
+        rows: result.rows,
+        exhausted: result.exhausted,
+      };
+    } finally {
+      await client.end({ timeout: 5 });
+    }
+  },
+});
+```
+
+Anatomy of the batch SQL above:
+
+- The `batch` CTE selects up to `limit` rows that **still need work**
+  (`WHERE normalized_email IS NULL`) and locks them with `FOR UPDATE SKIP LOCKED`.
+- The `UPDATE ... FROM batch` writes only those locked rows and `RETURNING c.id`
+  gives a row count — `updated.length` is what `runBatch` returns.
+- Because the predicate excludes already-migrated rows, a re-run after a crash
+  resumes cleanly, and two workers never collide.
+
+## Enabling it
+
+The example is **already wired** via `extraWorkflows` in `src/workflows/index.ts`:
+
+```ts
+import { backfillExampleTask } from "./backfill-example.js";
+
+export const extraWorkflows = [backfillExampleTask];
+```
+
+which `src/worker.ts` passes as `createWorker({ container, journeys, buckets,
+extraWorkflows })`. (Remove `backfillExampleTask` and the file if you don't need
+it.) For the general task-registration mechanics see
+`references/custom-workflow.md`. Trigger the run once from the Hatchet dashboard
+(or by pushing its event); re-running is safe and resumes where it left off.
+
+## Adapting it — checklist
+
+1. Copy `backfill-example.ts` (or edit it) to target your new table/column.
+2. Make `runBatch`'s predicate exclude already-done rows (`WHERE new_col IS NULL`)
+   and lock with `FOR UPDATE SKIP LOCKED`.
+3. Keep `batchSize` modest; set `pauseMs` to relieve a live database.
+4. Return the plain `{ batches, rows, exhausted }` summary (JSON-serializable).
+5. Ensure the task is listed in `extraWorkflows`, restart the worker, run it once.
+6. Only after `exhausted: true` is confirmed, ship the contract migration
+   (`NOT NULL` / drop old column).

package/skills/hogsend-webhooks-and-workflows/references/custom-workflow.md

@@ -0,0 +1,156 @@
+# Reference: custom Hatchet tasks (`extraWorkflows`)
+
+Custom tasks are durable background jobs you own — one-off maintenance, backfills,
+cron-style work, or event-driven side effects. They run in the **worker** process
+alongside the engine's built-in workflows. You define them in `src/workflows/`,
+export them from `src/workflows/index.ts`, and the scaffold passes them to
+`createWorker({ container, journeys, extraWorkflows })`.
+
+The option is **`extraWorkflows` — NOT `workflows`.** The engine registers its own
+built-ins (`send-email`, `import-contacts`, `check-alerts`, and the bucket tasks)
+automatically; `extraWorkflows` is *additive*. Never list a built-in there.
+
+## Defining a task
+
+Import the shared `hatchet` client from `@hogsend/engine`. Two flavours:
+
+- `hatchet.task({ name, fn })` — a plain task you trigger explicitly (one-off
+  jobs, backfills, anything kicked off from the dashboard or via `hatchet.events`).
+- `hatchet.durableTask({ name, onEvents, fn })` — long-running / event-driven work
+  (this is what journeys use under the hood). Declare `onEvents: [eventName]` to
+  have Hatchet route ingested events to the task automatically.
+
+### JSON-serializable IO (hard requirement)
+
+A task's **input** and **return value** must serialize to JSON.
+
+- Use specific, named keys (`{ jobId: string; format: string }`) or
+  `JsonValue`-compatible types.
+- Do **NOT** use a `[key: string]: unknown` index signature on the input type.
+- Return a plain object (or a small JSON-safe value) so Hatchet can store the
+  task output — return `void`/`undefined` if there's nothing to report.
+
+```ts
+import { hatchet } from "@hogsend/engine";
+
+// input + return are both plain, named-key JSON objects
+export const reindexSearchTask = hatchet.task({
+  name: "reindex-search",
+  retries: 2,
+  executionTimeout: "30m",
+  fn: async (input: { since: string; dryRun: boolean }) => {
+    // ... do the work ...
+    return { reindexed: 0, skipped: 0, dryRun: input.dryRun };
+  },
+});
+```
+
+The engine's own `import-contacts` task is a faithful template for a parameterized
+job — a named-key input, batched processing, and a JSON return:
+
+```ts
+export const importContactsTask = hatchet.task({
+  name: "import-contacts",
+  retries: 0,
+  executionTimeout: "600s",
+  fn: async (input: { jobId: string; data: string; format: string }) => {
+    // ...batched upserts...
+    return { status: "completed", processed, failed };
+  },
+});
+```
+
+### Event-driven variant
+
+If the task should run whenever a particular event is ingested, use a durable task
+with `onEvents`. The input arrives as the ingested event payload
+(`userId` / `userEmail` / scalar `properties`):
+
+```ts
+import { hatchet } from "@hogsend/engine";
+
+export const onSignupAuditTask = hatchet.durableTask({
+  name: "on-signup-audit",
+  onEvents: ["user.signed_up"],
+  executionTimeout: "10m",
+  retries: 1,
+  fn: async (input: {
+    userId: string;
+    userEmail: string;
+    properties: Record<string, string | number | boolean | null>;
+  }) => {
+    // side effect; return a JSON-safe summary (or nothing)
+    return { audited: input.userId };
+  },
+});
+```
+
+> For normal lifecycle messaging, prefer a journey (`defineJourney`) over a raw
+> durable task — journeys give you enrollment guards, state tracking, durable
+> sleeps and exit conditions for free. Reach for a custom durable task only when
+> you need orchestration the journey system doesn't model.
+
+## Accessing the database inside a task
+
+Tasks run in the worker and are constructed at module load, so they don't receive
+the request `container`. Open a connection inside `fn` with `createDatabase` from
+`@hogsend/db` and **always close it** in a `finally`:
+
+```ts
+import { createDatabase } from "@hogsend/db";
+import { createLogger, hatchet } from "@hogsend/engine";
+
+export const nightlyCleanupTask = hatchet.task({
+  name: "nightly-cleanup",
+  fn: async () => {
+    const { db, client } = createDatabase({ url: process.env.DATABASE_URL ?? "" });
+    const logger = createLogger(process.env.LOG_LEVEL ?? "info");
+    try {
+      // ...work with db...
+      return { ok: true };
+    } finally {
+      await client.end({ timeout: 5 });
+    }
+  },
+});
+```
+
+## Wiring it up (two edits)
+
+### 1. Export from `src/workflows/index.ts`
+
+List only YOUR tasks here — the engine adds its built-ins itself:
+
+```ts
+import { backfillExampleTask } from "./backfill-example.js";
+import { nightlyCleanupTask } from "./nightly-cleanup.js";
+
+export const extraWorkflows = [backfillExampleTask, nightlyCleanupTask];
+```
+
+### 2. Confirm `src/worker.ts` passes it
+
+The scaffold already does this — the key detail is the option name:
+
+```ts
+const worker = createWorker({
+  container: client,
+  journeys,
+  buckets,
+  extraWorkflows, // <-- NOT `workflows`
+});
+```
+
+`createWorker` builds the worker as `[...engine built-ins, ...journeyTasks,
+...bucketTasks, ...extraWorkflows]`. After editing, restart the worker
+(`hatchet worker dev` or `pnpm worker:dev`) so the new task registers.
+
+## Authoring a new task — checklist
+
+1. Create `src/workflows/<name>.ts` exporting `hatchet.task({...})` (or
+   `hatchet.durableTask` for event-driven/long-running work).
+2. Type the input with named keys (no `[key: string]: unknown`); return JSON-safe
+   data.
+3. Open `createDatabase(...)` inside `fn` and close it in `finally`.
+4. Add the export to the `extraWorkflows` array in `src/workflows/index.ts`.
+5. Restart the worker; trigger the task (Hatchet dashboard or `hatchet.events`).

package/skills/hogsend-webhooks-and-workflows/references/webhook-source.md

@@ -0,0 +1,172 @@
+# Reference: webhook sources (`defineWebhookSource`)
+
+A webhook source turns an inbound HTTP request into an `IngestEvent`. Each source
+is served by the engine at **`POST /v1/webhooks/{sourceId}`** and its output is
+fed straight into `ingestEvent()` — so a webhook can store an event, push it to
+Hatchet (routing it to matching journey tasks), evaluate journey exit conditions,
+and upsert the contact.
+
+You write the source files; the engine owns the route. Edit only
+`src/webhook-sources/`.
+
+## The shape you implement
+
+`defineWebhookSource` is imported from `@hogsend/engine`. The definition object:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `meta.id` | `string` | The `:sourceId` segment in the URL. Keep it URL-safe. |
+| `meta.name` | `string` | Human label. |
+| `meta.description?` | `string` | Optional. |
+| `auth.header` | `string` | Request header carrying the shared secret. |
+| `auth.envKey` | `string` | Env var holding the expected secret value. |
+| `auth.type` | `"match"` | Only mode today: header value must equal the env value. |
+| `schema?` | `z.ZodSchema<T>` | Optional Zod validator; on success `payload` is typed `T`. |
+| `transform(payload, ctx)` | `=> Promise<IngestEvent \| null>` | Map payload → event. Return `null` to accept-and-skip. |
+
+### Auth behaviour (important)
+
+The route enforces auth **only when the env secret is set**. If
+`process.env[auth.envKey]` is empty/undefined the source is treated as **open**
+(no auth). When the secret is present, the request must send it either in
+`auth.header` or as `Authorization: Bearer <secret>`; otherwise the route returns
+`401`. Always set the env secret in any non-local environment.
+
+### Validation
+
+If you provide `schema`, the route runs `schema.safeParse(payload)` before
+calling `transform`; a parse failure returns `400` and `transform` never runs.
+Inside `transform`, `payload` is the parsed, typed value.
+
+## The `transform` → `IngestEvent` contract
+
+`transform(payload, ctx)` returns an `IngestEvent` (or `null`):
+
+```ts
+interface IngestEvent {
+  event: string;                       // event name (this is what journeys trigger on)
+  userId: string;                      // external/distinct id of the person
+  userEmail: string;                   // "" if unknown — emptystring, not undefined
+  properties: Record<string, unknown>; // event + person props; merged into the event
+  idempotencyKey?: string;             // optional dedupe key (see below)
+}
+```
+
+`ctx` is `{ db, logger }` — a Drizzle `Database` and the engine logger — for
+lookups/diagnostics inside the transform. It does **not** carry `hatchet` or the
+registry; those are applied by the route when it calls `ingestEvent`.
+
+Notes that match the engine's behaviour:
+
+- `event` is the routing key. Hatchet routes the pushed event to every journey
+  whose trigger declares `onEvents: [thatEvent]`. The decision to *enroll* (or
+  *exit*) is then made by trigger/exit conditions — see the **hogsend-conditions**
+  skill.
+- `userEmail` should be `""` when unknown (the ingestion pipeline treats a falsy
+  email as "no email" for the contact upsert). Don't pass `undefined`.
+- Only JSON-scalar properties (`string | number | boolean | null`) survive the
+  push to Hatchet; nested objects/arrays are dropped from the event payload that
+  reaches journey tasks (they're still stored on the `userEvents` row). Flatten
+  anything a journey needs to branch on into a scalar property.
+- `idempotencyKey` (optional): when set, a duplicate delivery with the same key is
+  a no-op (`{ stored: false }`) — use the provider's event id when available.
+- Return `null` to accept the delivery (HTTP `200 { ok: true, skipped: true }`)
+  without ingesting — e.g. event types you don't care about.
+
+## Example: a source from the scaffold
+
+`src/webhook-sources/posthog.ts` — validates a PostHog destination payload and
+maps it to an `IngestEvent`:
+
+```ts
+import { defineWebhookSource } from "@hogsend/engine";
+import { z } from "zod";
+
+const posthogWebhookSchema = z.object({
+  event: z.object({
+    uuid: z.string().optional(),
+    event: z.string(),
+    distinct_id: z.string(),
+    properties: z.record(z.string(), z.unknown()).optional(),
+  }),
+  person: z
+    .object({
+      properties: z
+        .object({ email: z.string().optional() })
+        .catchall(z.unknown())
+        .optional(),
+    })
+    .optional(),
+});
+
+export const posthogSource = defineWebhookSource({
+  meta: {
+    id: "posthog",
+    name: "PostHog",
+    description: "Receives events from PostHog webhook destinations.",
+  },
+  auth: {
+    header: "x-posthog-webhook-secret",
+    envKey: "POSTHOG_WEBHOOK_SECRET",
+    type: "match",
+  },
+  schema: posthogWebhookSchema,
+  async transform(payload) {
+    const rawEmail = payload.person?.properties?.email;
+    const userEmail = typeof rawEmail === "string" ? rawEmail : "";
+
+    const properties: Record<string, unknown> = {
+      ...payload.event.properties,
+      ...payload.person?.properties,
+    };
+    if (payload.event.uuid) {
+      properties._posthogEventId = payload.event.uuid;
+    }
+
+    return {
+      event: payload.event.event,
+      userId: payload.event.distinct_id,
+      userEmail,
+      properties,
+    };
+  },
+});
+```
+
+## Wiring it up (two edits)
+
+### 1. Register in `src/webhook-sources/index.ts`
+
+```ts
+import type { DefinedWebhookSource } from "@hogsend/engine";
+import { posthogSource } from "./posthog.js";
+import { stripeSource } from "./stripe.js"; // your new source
+
+export const webhookSources: DefinedWebhookSource[] = [
+  posthogSource,
+  stripeSource,
+];
+```
+
+### 2. Pass to `createApp` in `src/index.ts`
+
+The scaffold already threads this — confirm it's present:
+
+```ts
+import { webhookSources } from "./webhook-sources/index.js";
+
+const app = createApp(client, { webhookSources });
+```
+
+That's it. Your source is now live at `POST /v1/webhooks/stripe`.
+
+## Authoring a new source — checklist
+
+1. Create `src/webhook-sources/<id>.ts` exporting a `defineWebhookSource({...})`.
+2. Pick a unique `meta.id` (becomes the URL segment).
+3. Set `auth.envKey` and add that secret to your env for non-local deploys.
+4. Add a Zod `schema` for the payload you expect (recommended).
+5. In `transform`, produce `{ event, userId, userEmail, properties }` (or `null`).
+   Flatten anything a journey will branch on into a scalar property.
+6. Add the export to the `webhookSources` array in `index.ts`.
+7. Verify deliveries land using the **hogsend-cli** skill (events/contacts).