@hogsend/cli 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@hogsend/studio": "^0.8.0",
+    "@hogsend/studio": "^0.9.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {

package/skills/hogsend-authoring-destinations/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: hogsend-authoring-destinations
+description: Use when adding or editing a code-defined OUTBOUND destination in src/destinations/ — defineDestination({ meta:{id}, events, transform(envelope, ctx) -> { url, method?, headers, body, isSuccess? } | null }) from @hogsend/engine. A destination is a delivery-time transform keyed by webhook_endpoints.kind that fans the outbound event catalog (contact.*, email.*, journey.completed, bucket.*) out to a product/data tool (PostHog, Segment, Slack, a CRM, a warehouse), reusing the engine's durable retry/backoff/DLQ delivery for free. Covers the shipped presets (webhook/posthog/segment/slack), ENABLED_DESTINATION_PRESETS, per-endpoint config credentials, the null-skip and throw-is-config-error contract, and the register ritual (src/destinations/index.ts + thread destinations into createHogsendClient in BOTH src/index.ts and src/worker.ts). NOT for ad-platform CAPI (deferred to PostHog CDP).
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Authoring Hogsend destinations
+
+A **destination** is a code-defined target for Hogsend's OUTBOUND event stream —
+PostHog, Segment, Slack, a CRM, a data warehouse. You declare it with
+`defineDestination()` in `src/destinations/`, the symmetric twin of
+`defineWebhookSource()` on the inbound side. It is the AUTHORING layer for event
+**fan-out**.
+
+The headline fact: a destination is a **delivery-time transform**, not a new
+delivery pipeline. The engine already has a durable outbound spine — every
+catalog event (`contact.*`, `email.*`, `journey.completed`, `bucket.*`) is
+written as a `webhook_deliveries` row and POSTed with retry / backoff / DLQ /
+reaper. A destination just **rewrites the HTTP request** for an endpoint whose
+`kind` matches your destination's `id`. You inherit ALL the durable delivery
+machinery for free — you only write the per-vendor projection.
+
+You are editing a **scaffolded consumer app** (content only). You import
+`defineDestination` from `@hogsend/engine`; you never touch engine internals (the
+registry, the delivery task, the retry machinery are all engine-owned). Relative
+imports use the ESM `.js` extension.
+
+> ⚠️ Destinations are for event **fan-out**. They are NOT the home for
+> ad-platform conversion forwarding (CAPI) — that stays deferred to PostHog CDP;
+> Hogsend just fires the events.
+
+## Do you even need to write one?
+
+Probably not. The engine ships four presets, each `defineDestination()` already:
+
+| preset id | target | credentials (per-endpoint `config`) |
+|-----------|--------|-------------------------------------|
+| `webhook` | the DEFAULT signed Standard-Webhooks POST to a subscriber URL | `secret` column (a `whsec_…`) |
+| `posthog` | PostHog capture endpoint | `{ apiKey, host?, eventNames? }` |
+| `segment` | Segment HTTP Tracking API (`/v1/track`, Basic auth) | `{ writeKey, host?, eventNames? }` |
+| `slack`   | Slack incoming webhook (formatted text block) | `{ url?, username?, iconEmoji? }` — `url` falls back to the endpoint `url` column |
+
+`webhook` and `posthog` are **always** registered. `segment`/`slack` register when
+`ENABLED_DESTINATION_PRESETS` allows them (see below). To USE a preset you create a
+`webhook_endpoints` row with that `kind` and its `config` (via the admin API /
+`hs.webhooks` SDK) — **no code**. Write a `defineDestination()` only for a NEW
+target shape, or to OVERRIDE a preset of the same id.
+
+## The shape
+
+```ts
+import { defineDestination } from "@hogsend/engine";
+
+export const crm = defineDestination({
+  meta: {
+    id: "crm",                 // == webhook_endpoints.kind it delivers
+    name: "Acme CRM",
+    description: "Forward lifecycle events to Acme.",
+  },
+  events: ["contact.created", "email.bounced"], // catalog events it accepts
+  transform(envelope, ctx) {
+    // envelope = the FROZEN { id, type, timestamp, data } emitOutbound wrote.
+    // ctx.endpoint = the LIVE webhook_endpoints row (url, config, secret).
+    const cfg = (ctx.endpoint.config ?? {}) as { token?: string };
+    if (!cfg.token) {
+      // A THROW = non-retryable CONFIG error → straight to the DLQ.
+      throw new Error("crm destination missing config.token");
+    }
+    return {
+      url: "https://api.acme.example/ingest",
+      method: "POST",                          // optional, defaults to POST
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${cfg.token}`,
+      },
+      body: JSON.stringify({ type: envelope.type, data: envelope.data }),
+      // isSuccess?: (status, bodySnippet) => boolean  — optional; default is 2xx.
+    };
+  },
+});
+```
+
+`defineDestination({ meta, events, transform })`:
+
+| field | required | notes |
+|-------|----------|-------|
+| `meta.id` | yes | The `webhook_endpoints.kind` this destination delivers. Pick a stable lowercase id; an endpoint with `kind === meta.id` routes here. Reusing a preset id (`posthog`/`segment`/`slack`) **overrides** that preset (you win on the merge). |
+| `meta.name` | yes | Human label. |
+| `meta.description` | no | One-liner. |
+| `events` | yes | The outbound catalog events this destination accepts (`OutboundEventName[]`). Per-endpoint subscription is STILL scoped by `webhook_endpoints.event_types`, so an endpoint only ever receives what it subscribed to — `events` documents intent and is the authoring-time contract. |
+| `transform` | yes | `(envelope, ctx) => { url, method?, headers, body, isSuccess? } \| null`. **Synchronous.** |
+
+`defineDestination` is an identity/validating function (like `defineWebhookSource`)
+— it returns its argument so a typo in the shape is a compile error.
+
+## The transform contract — three outcomes
+
+The `transform` runs once per delivery ATTEMPT (including retries), so it must be a
+**pure projection** of the envelope + endpoint — never mutate external state in it.
+
+1. **Return an `AdapterRequest`** (`{ url, headers, body, method?, isSuccess? }`)
+   → the delivery task POSTs exactly those bytes. `body` is the EXACT bytes sent
+   (for the `webhook` preset they are the SIGNED bytes — never re-stringify them).
+   Success is the default 2xx rule unless you supply `isSuccess`.
+2. **Return `null`** → SKIP delivery for that envelope. The row is marked
+   `delivered` as a successful **no-op** (no POST, no retry, no DLQ). Use this to
+   filter: e.g. only forward `email.bounced` for a certain template, drop the
+   rest.
+3. **Throw** → a non-retryable CONFIG error (missing credential, bad shape). The
+   row fast-fails straight to the dead-letter queue — it does NOT burn the retry
+   budget. A bad config should fail loudly, not silently retry 8 times.
+
+A network error / timeout / retryable HTTP status (`5xx`, `408`, `429`) is the
+delivery task's job — it retries with backoff off `nextRetryAt`. You never handle
+retries in a transform.
+
+## Where credentials live
+
+Destination credentials are **per-endpoint**, in `webhook_endpoints.config`
+(a JSONB bag) — NOT env vars, NOT a fake `whsec_`. The transform reads
+`ctx.endpoint.config`. This is the deliberate split from inbound presets (whose
+secrets are env-gated): a destination can have many endpoints, each with its own
+key, region, channel. `ENABLED_DESTINATION_PRESETS` only decides which preset
+TRANSFORMS are resolvable, never supplies a credential.
+
+## `ENABLED_DESTINATION_PRESETS` — which presets register
+
+A process-wide env knob (same `*`/csv/`none`/absent grammar as
+`ENABLED_WEBHOOK_PRESETS`), resolving which PRESET transforms are in the registry:
+
+- absent → `webhook` + `posthog` only (the always-on set).
+- `"none"` → STILL `webhook` + `posthog` (you can never disable the
+  no-regression signed-POST path or the auto-seeded PostHog destination).
+- a csv (e.g. `"segment,slack"`) → those, **unioned** with the always-on set.
+- `"*"` → every shipped preset.
+
+Your own `defineDestination()` destinations are NOT gated by this env — they are
+always registered (they came from your `destinations` array). The env governs
+PRESETS only.
+
+## Registering a destination (the wiring ritual)
+
+A defined destination does nothing until it is (1) exported from the barrel and
+(2) threaded into `createHogsendClient` in BOTH entry points. Like buckets — and
+UNLIKE lists — the wiring touches both `src/index.ts` and `src/worker.ts`, because
+the durable delivery task runs in the WORKER process and resolves transforms from
+the process registry `createHogsendClient` installs. **`destinations` is NOT passed
+to `createWorker`** — the worker's `createHogsendClient` call installs the registry.
+
+### 1. Export from `src/destinations/index.ts`
+
+```ts
+// src/destinations/index.ts
+import type { DefinedDestination } from "@hogsend/engine";
+import { crm } from "./crm.js"; // your defineDestination(), or inline it here
+
+// All defined destinations for this app. Passed to
+// createHogsendClient({ destinations }) in BOTH src/index.ts and src/worker.ts.
+export const destinations: DefinedDestination[] = [crm];
+```
+
+### 2. Thread into `createHogsendClient` in `src/index.ts`
+
+```ts
+import { createApp, createHogsendClient } from "@hogsend/engine";
+import { destinations } from "./destinations/index.js";
+// ...templates, journeys, webhookSources...
+
+const client = createHogsendClient({
+  journeys,
+  destinations,        // ← merged with the env presets; consumer wins on id collision
+  email: { templates },
+});
+const app = createApp(client, { webhookSources });
+```
+
+### 3. Thread into `createHogsendClient` in `src/worker.ts`
+
+```ts
+import { createHogsendClient, createWorker } from "@hogsend/engine";
+import { destinations } from "./destinations/index.js";
+
+const client = createHogsendClient({
+  journeys,
+  destinations,        // ← same array; the WORKER's delivery task needs the registry
+  email: { templates },
+});
+const worker = createWorker({ container: client, journeys /* …, NO destinations */ });
+```
+
+Wire `destinations` into `createHogsendClient` in BOTH files. Passing it to
+`createWorker` is not an accepted option — the worker resolves the registry through
+its OWN `createHogsendClient` call.
+
+## Creating the endpoint that uses your destination
+
+The destination is the TRANSFORM; an endpoint row is what makes it fire. Create
+one with the admin API / `hs.webhooks.create` with `kind` = your destination id,
+its `config` credentials, and the `eventTypes` it subscribes to. See the
+**hogsend-client-sdk** / **hogsend-cli** skills for managing outbound endpoints.
+
+## Golden rules
+
+1. A destination is a delivery-time transform keyed by `webhook_endpoints.kind`,
+   reusing the engine's durable delivery. You write the projection, not a pipeline.
+2. `transform` is SYNCHRONOUS and a PURE projection (runs per attempt). Return a
+   request, return `null` to skip (delivered no-op), or throw on bad config (→ DLQ).
+3. Credentials live per-endpoint in `webhook_endpoints.config`, never in env.
+   `ENABLED_DESTINATION_PRESETS` only governs which PRESETS register.
+4. `webhook` + `posthog` presets are always on; you cannot disable them.
+5. Wire `destinations` into `createHogsendClient` in BOTH `src/index.ts` AND
+   `src/worker.ts`. Do NOT pass it to `createWorker`.
+6. Reusing a preset id overrides that preset (consumer wins on the merge).
+7. Destinations are event fan-out — NOT ad-platform CAPI (deferred to PostHog CDP).

package/skills/hogsend-authoring-emails/references/tracking-and-unsubscribe.md

@@ -41,7 +41,10 @@ per unique URL, then single-pass replaces each href with
   `WHERE clicked_at IS NULL`), then **302-redirects to the original URL**.
 - After responding it fire-and-forgets an `email.link_clicked` event (props:
   `emailSendId`, `templateKey`, `linkUrl`, `linkId`) into PostHog + the ingest
-  pipeline, so journeys can branch on it and `exitOn` can fire.
+  pipeline, so journeys can branch on it and `exitOn` can fire. It ALSO emits the
+  outbound-catalog `email.clicked` event, which fans out durably to every
+  subscribed DESTINATION — **per-hit, not first-touch** (every click is delivered,
+  unlike the first-only `clicked_at` column).
 
 Authoring implication: use real `<a href>` / react-email `Button`/`Link` with
 absolute `https://` URLs and they're tracked automatically. Non-HTTP links
@@ -56,7 +59,9 @@ just before `</body>` (so always compose inside `Layout`, which emits a proper
 - `GET /v1/t/o/:id` sets `email_sends.opened_at` (first open only), returns a
   42-byte transparent GIF with `Cache-Control: no-store`.
 - Then fire-and-forgets an `email.opened` event (props: `emailSendId`,
-  `templateKey`).
+  `templateKey`) into PostHog + the ingest pipeline, and emits the outbound-catalog
+  `email.opened` event that fans out durably to every subscribed DESTINATION —
+  **per-hit, not first-touch**.
 
 The engine's own constants for these are `EMAIL_OPENED = "email.opened"` and
 `EMAIL_LINK_CLICKED = "email.link_clicked"`. In journey code, reference them via

package/skills/hogsend-authoring-journeys/SKILL.md

@@ -59,10 +59,17 @@ export const welcome = defineJourney({
 ## Key concepts
 
 - **`ctx` is orchestration primitives ONLY** — `sleep`, `sleepUntil`, `when`,
-  `waitForEvent`, `checkpoint`, `trigger`, `identify`, `guard.isSubscribed`,
-  `history.hasEvent/journey/email`, `posthog.capture`. Features are standalone
-  imports: `sendEmail()` and `getPostHog()` come from `@hogsend/engine`, NOT off
-  `ctx`.
+  `waitForEvent`, `checkpoint`, `trigger`, `guard.isSubscribed`,
+  `history.hasEvent/journey/email`. Features are standalone imports: `sendEmail()`
+  comes from `@hogsend/engine`, NOT off `ctx`.
+- **Fan-out is DESTINATIONS, not `ctx`.** There is no `ctx.identify` /
+  `ctx.posthog.capture` — those single-vendor PostHog shims were removed. To get
+  user/event data into product + data tools (PostHog, Segment, Slack, a CRM, a
+  warehouse), set up an outbound DESTINATION: the email/contact/journey/bucket
+  lifecycle is delivered there durably (retry/backoff/DLQ), keyed by
+  `webhook_endpoints.kind`. EVERY destination receives EVERY open and click
+  (per-hit, not first-touch), and `email.delivered` is the canonical "email was
+  received" signal. See the **hogsend-authoring-destinations** skill.
 - **Duration helpers** `days()` / `hours()` / `minutes()` from `@hogsend/core`
   (also re-exported by `@hogsend/engine`) — never magic strings.
 - **`user`** carries `id`, `email`, `properties`, `stateId`, `journeyId`,

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

@@ -72,15 +72,27 @@ await ctx.trigger({
 });
 ```
 
-## PostHog (no-op without POSTHOG_API_KEY)
+## Fanning data out — use DESTINATIONS, not `ctx`
 
-```ts
-// Set person properties on PostHog for the current user.
-ctx.identify({ plan: "pro", onboarded: true });   // synchronous, void
+There is **no `ctx.identify` and no `ctx.posthog.capture`** — those single-vendor
+PostHog shims were removed. `ctx` does not fan data out to product/data tools.
 
-// Fire a custom PostHog event for the current user.
-ctx.posthog.capture({ event: "journey_step_reached", properties: { step: 2 } });
-```
+To mirror user/event data into PostHog, Segment, Slack, a CRM or a warehouse, set
+up an outbound **DESTINATION**: the email/contact/journey/bucket lifecycle is
+delivered there DURABLY (retry / backoff / DLQ), keyed by `webhook_endpoints.kind`.
+You don't fire it from `run` — it receives the lifecycle automatically:
+
+- `email.sent` / `email.delivered` / `email.opened` / `email.clicked` /
+  `email.bounced` / `email.complained`, `contact.*`, `journey.completed`,
+  `bucket.entered` / `bucket.left`.
+- `email.delivered` is the canonical **"email was received"** signal.
+- EVERY destination receives EVERY open and click — **per-hit, not first-touch** —
+  so downstream tools see the full engagement stream.
+
+See the **hogsend-authoring-destinations** skill. (PostHog is now JUST a
+destination, `kind="posthog"`.) If you need a fire-and-forget raw write inside a
+journey, `getPostHog()` is still importable from `@hogsend/engine` — but for
+fan-out, reach for a destination, not an in-journey vendor call.
 
 ## Guards
 
@@ -122,7 +134,9 @@ orchestration:
 - **`sendEmail()`** — `import { sendEmail } from "@hogsend/engine"`. See
   `references/sending-email-from-a-journey.md`.
 - **`getPostHog()`** — `import { getPostHog } from "@hogsend/engine"` for the raw
-  PostHog service (`ctx.identify` / `ctx.posthog.capture` cover the common cases).
+  PostHog service (a fire-and-forget escape hatch). For fanning lifecycle data out
+  to product/data tools, prefer an outbound DESTINATION (see above) — it delivers
+  durably and is vendor-neutral.
 - **SMS / push / Slack** — plain functions you import, never on `ctx`.
 - There is **no `ctx.db`, no `ctx.sendEmail`, no `ctx.hatchet`** surfaced to
   consumer journeys. If you reach for one of those, you are modelling it wrong —

package/skills/hogsend-client-sdk/SKILL.md

@@ -126,6 +126,24 @@ if your data-plane `hs` only holds an ingest key.
 signing secret (`whsec_…`) is returned **only once** — on `create` and
 `rotateSecret`; `list`/`get` only expose `secretPrefix`. Store it on create.
 
+`create`/`update` also take a **`kind`** (+ **`config`**) — this is how you manage
+an outbound DESTINATION from the SDK. `kind="webhook"` (the default) is the
+byte-identical signed POST. A keyed destination (`kind="posthog"|"segment"|"slack"|…`)
+fans the same event stream out to that tool via a server-side transform; its
+credentials live in `config` (e.g. `{ apiKey }`) — never an env var — and it
+returns NO `secret` (it authenticates via `config`). Same durable
+retry/backoff/DLQ spine either way.
+
+```ts
+// Fan the email lifecycle out to PostHog as a managed destination — no code:
+await hs.webhooks.create({
+  url: "https://us.i.posthog.com",            // host (the posthog transform appends /capture/)
+  eventTypes: ["email.delivered", "email.opened", "email.clicked", "email.bounced"],
+  kind: "posthog",
+  config: { apiKey: process.env.POSTHOG_API_KEY! },
+});
+```
+
 **Subscriber side:** in the handler that RECEIVES Hogsend's signed POSTs, call
 `verifyHogsendWebhook({ payload, headers, secret })` (also exported from
 `@hogsend/client`). Pass the **raw request body bytes** (never a re-stringified

package/skills/hogsend-client-sdk/references/api-surface.md

@@ -167,8 +167,10 @@ Signing-secret management is the same trust class as API-key management.
 ### `webhooks.create(input) → CreatedWebhookEndpoint`
 
 `POST /v1/admin/webhooks`. Register an endpoint subscribed to one or more of the
-12 outbound event types. Returns the endpoint INCLUDING the full signing
-`secret` (`whsec_…`) — shown ONLY here and on `rotateSecret`. Store it now.
+13 outbound event types. For the default `kind="webhook"` it returns the endpoint
+INCLUDING the full signing `secret` (`whsec_…`) — shown ONLY here and on
+`rotateSecret`. Store it now. A keyed DESTINATION (`kind="posthog"|"segment"|
+"slack"|…`) carries its credentials in `config` and returns NO secret.
 
 ```ts
 type CreateWebhookInput = {
@@ -176,6 +178,8 @@ type CreateWebhookInput = {
   eventTypes: OutboundEventType[]; // contact.* | email.* | journey.completed | bucket.*
   description?: string;
   disabled?: boolean;
+  kind?: WebhookKind;              // "webhook" (default signed POST) | "posthog" | "segment" | "slack" | (string & {})
+  config?: Record<string, unknown>; // per-destination credentials, e.g. { apiKey } — ignored for kind="webhook"
 };
 
 interface WebhookEndpoint {
@@ -183,7 +187,9 @@ interface WebhookEndpoint {
   url: string;
   description: string | null;
   eventTypes: OutboundEventType[];
-  secretPrefix: string;               // first 12 chars, e.g. whsec_AbCd
+  secretPrefix: string | null;        // first chars, e.g. whsec_AbCd — null for keyed destinations
+  kind: WebhookKind;                  // delivery transform selector
+  config: Record<string, unknown> | null; // credentials REDACTED in responses (apiKey → "***"); null for kind="webhook"
   status: "enabled" | "disabled";
   organizationId: string | null;
   lastDeliveryAt: string | null;      // ISO
@@ -191,7 +197,8 @@ interface WebhookEndpoint {
   updatedAt: string;                  // ISO
 }
 
-type CreatedWebhookEndpoint = WebhookEndpoint & { secret: string }; // full secret ONCE
+// `secret` is present ONLY for kind="webhook" (keyed destinations carry none), hence optional.
+type CreatedWebhookEndpoint = WebhookEndpoint & { secret?: string }; // full secret ONCE
 ```
 
 ### `webhooks.list(opts?) → WebhookEndpoint[]`
@@ -215,6 +222,8 @@ type UpdateWebhookInput = {
   eventTypes?: OutboundEventType[];
   description?: string | null;
   disabled?: boolean;
+  kind?: WebhookKind;                       // switch the delivery transform
+  config?: Record<string, unknown> | null;  // replace per-destination config; null clears it
 };
 ```
 

package/skills/hogsend-extending/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hogsend-extending
-description: Use when extending a Hogsend app beyond journeys/emails/buckets — swapping the email or analytics provider behind its engine-owned contract (EmailProvider / PostHogService), wiring an outbound integration (Slack, a CRM, Stripe) as plain code called from a journey, or deciding when to publish a reusable @hogsend/plugin-* package. Covers the two categories of extension and where each is wired.
+description: Use when extending a Hogsend app beyond journeys/emails/buckets — swapping the email or analytics provider behind its engine-owned contract (EmailProvider / PostHogService), wiring an outbound integration (Slack, a CRM, Stripe) as plain code called from a journey, fanning the outbound EVENT stream out to a tool via a code-defined destination (defineDestination, see hogsend-authoring-destinations), or deciding when to publish a reusable @hogsend/plugin-* package. Covers the categories of extension and where each is wired.
 license: MIT
 metadata:
   author: withSeismic
@@ -9,7 +9,7 @@ metadata:
 
 # Extending Hogsend
 
-There are **two** ways to extend a Hogsend app, and they are different
+There are **three** ways to extend a Hogsend app, and they are different
 mechanisms — don't reach for the wrong one.
 
 1. **Capability providers** (email, analytics). The engine itself drives these,
@@ -21,15 +21,30 @@ mechanisms — don't reach for the wrong one.
    `@hogsend/plugin-resend` and `@hogsend/plugin-posthog` are the **bundled
    defaults and reference implementations**; you only swap when you want a
    different vendor. → `references/swap-a-provider.md`.
+   Note: the `analytics` (`PostHogService`) role is now NARROW — it is NOT the
+   outbound-event firing path (that's destinations, below). It's load-bearing for
+   exactly two things: the identity **PULL** (`getPersonProperties` for per-user
+   timezone resolution at enrollment) and the opt-in `bucket.syncToPostHog`
+   person-property mirror. PostHog is otherwise just a destination (`kind="posthog"`).
 
-2. **Integrations** (everything you call *out* to — Slack, a CRM, Stripe, an
-   internal HTTP API). **No contract, no framework.** Install the SDK, write a
-   thin wrapper in your own `src/lib/`, import it into a journey, and call it like
-   a function. The engine never sees it. → `references/build-an-integration.md`.
+2. **Integrations** (a one-directional call *out* to a service — post to Slack,
+   create a CRM record, charge Stripe — from inside a JOURNEY at a specific
+   step). **No contract, no framework.** Install the SDK, write a thin wrapper in
+   your own `src/lib/`, import it into a journey, and call it like a function. The
+   engine never sees it. → `references/build-an-integration.md`.
 
-**The deciding question: does the engine call it, or do you?** If the engine
-drives the capability (sending mail, capturing analytics) it's a provider behind
-a contract. If your journey reaches outward, it's a plain integration.
+3. **Destinations** (fan the engine's OUTBOUND EVENT stream — `contact.*`,
+   `email.*`, `journey.completed`, `bucket.*` — out to a tool DURABLY, on every
+   matching event, not at a single journey step). A code-defined
+   `defineDestination()` is a delivery-time transform keyed by an endpoint
+   `kind`; it reuses the engine's durable retry / backoff / DLQ delivery. The
+   engine ships `webhook`/`posthog`/`segment`/`slack` presets. → the
+   **hogsend-authoring-destinations** skill.
+
+**The deciding questions.** Does the engine DRIVE the capability (sending mail,
+capturing analytics)? → a provider behind a contract (1). Are you reaching out at
+ONE journey step? → a plain integration (2). Do you want EVERY lifecycle event
+mirrored to a tool, durably? → a destination (3).
 
 ## Swapping a capability provider — the short version
 
@@ -38,7 +53,8 @@ a contract. If your journey reaches outward, it's a plain integration.
   reference implementation to copy is `packages/plugin-resend/src/provider.ts`
   (`createResendProvider`).
 - **Wire it.** `createHogsendClient({ email: { templates, provider: createMyProvider(...) } })`.
-  Analytics is a **top-level** option (the engine itself fires captures):
+  Analytics is a **top-level** option (the engine uses it for the identity pull +
+  bucket sync, not for outbound fan-out):
   `createHogsendClient({ analytics: createMyAnalytics(...) })`.
 - **You get everything else for free.** Template rendering, link-click + open
   tracking, preference/suppression checks, the frequency cap, and the
@@ -62,6 +78,19 @@ a contract. If your journey reaches outward, it's a plain integration.
   Hatchet task in `src/workflows/` and register it via
   `createWorker({ extraWorkflows })`.
 
+## Fanning the event stream to a tool — the short version
+
+When you want a tool to receive EVERY matching lifecycle event (an analytics
+warehouse mirroring `email.*`, a Slack channel pinged on `email.bounced`), don't
+hand-roll an integration call in every journey — author an outbound
+**destination** instead. `defineDestination({ meta:{id}, events, transform })` in
+`src/destinations/` is a delivery-time projection keyed by an endpoint `kind`,
+and it inherits the engine's durable retry / backoff / DLQ delivery for free. The
+engine ships `webhook` (default signed POST), `posthog`, `segment`, and `slack`
+presets, so most fan-out is config (a `webhook_endpoints` row), not code. Wire
+your `destinations` array into `createHogsendClient` in BOTH `src/index.ts` and
+`src/worker.ts`. → the **hogsend-authoring-destinations** skill.
+
 ## When to publish a `@hogsend/plugin-*` package
 
 Almost never from a scaffolded app. A standalone module in your `src/` is the
@@ -73,7 +102,9 @@ Hogsend monorepo, not in your client app.
 ## What NOT to do
 
 - **Don't put a service on `ctx`.** `ctx` is durable-orchestration primitives only
-  (`sleep`, `checkpoint`, `trigger`, `guard`, `history`, `posthog`, `identify`).
+  (`sleep`, `sleepUntil`, `when`, `waitForEvent`, `checkpoint`, `trigger`, `guard`,
+  `history`). There is no `ctx.posthog` / `ctx.identify` — those were removed; fan
+  data out with a destination instead.
 - **Don't reach for a provider contract for a one-directional call** — that's an
   integration (just code).
 - **Don't import the `EmailProvider`/`PostHogService` contract from a

package/skills/hogsend-extending/references/swap-a-provider.md

@@ -115,8 +115,21 @@ Same shape: the `PostHogService` contract lives in `@hogsend/core`
 (canonical `@hogsend/engine`); `createPostHogService` (`@hogsend/plugin-posthog`)
 is the default + reference impl. Supply your own via the **top-level**
 `createHogsendClient({ analytics })` option. PostHog is optional — with no
-`POSTHOG_API_KEY` the engine resolves analytics to `undefined` and every capture
-is a no-op.
+`POSTHOG_API_KEY` the engine resolves analytics to `undefined` and the reads
+below become no-ops.
+
+Its role is now **NARROW**. The engine no longer fires the outbound event catalog
+(`email.*` / `contact.*` / `journey.completed` / `bucket.*`) through analytics —
+that fan-out moved to **destinations** on the durable webhook spine, and PostHog
+is now just one destination (`kind="posthog"`, see hogsend-authoring-destinations).
+`PostHogService` is load-bearing for exactly two things, both of which a swapped
+provider must still satisfy:
+
+1. The identity **PULL** — `getPersonProperties(distinctId)`, used for per-user
+   timezone resolution at journey enrollment.
+2. The opt-in `bucket.syncToPostHog` person-property mirror (`$set`/`$unset` of a
+   cohort boolean on bucket transitions) — a PostHog-direct write because `$set`
+   identity semantics have no vendor-neutral envelope.
 
 ## Don't over-reach
 

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

@@ -77,7 +77,19 @@ Relative imports use the ESM `.js` extension.
 - To verify a webhook or task against a running instance (events landing,
   contacts upserted, journeys firing), see the **hogsend-cli** skill.
 - **Inbound vs outbound:** this skill is about *inbound* sources (HTTP → engine).
-  The engine also emits an *outbound* signed event stream (`contact.*`,
-  `email.*`, `journey.completed`, `bucket.*`) to subscriber URLs — manage those
-  endpoints with `hogsend webhooks …` (hogsend-cli skill) or `hs.webhooks.*`
-  (hogsend-client-sdk skill), and verify deliveries with `verifyHogsendWebhook`.
+  The engine also emits an *outbound* event stream (`contact.*`, `email.*`,
+  `journey.completed`, `bucket.*`). Two halves:
+  - **Subscriber endpoints** — manage the `webhook_endpoints` rows with
+    `hogsend webhooks …` (hogsend-cli skill) or `hs.webhooks.*` (hogsend-client-sdk
+    skill); verify signed deliveries with `verifyHogsendWebhook`. `create`/`update`
+    now take a `kind` + `config`: the default `kind="webhook"` is the byte-identical
+    signed `whsec_` POST (returns a one-time `secret`); a keyed destination
+    (`kind="posthog"|"segment"|"slack"|…`) carries its credentials in `config`
+    (e.g. `{ apiKey }`) and returns NO secret. Same durable retry/backoff/DLQ spine
+    either way — `kind` just selects the delivery-time transform.
+  - **Code-defined destinations** — author a delivery-time transform for a new
+    fan-out TARGET (a CRM, a warehouse, a custom shape) with `defineDestination()`
+    in `src/destinations/`. This is the symmetric twin of `defineWebhookSource`
+    on the OUTBOUND side. → the **hogsend-authoring-destinations** skill. NOTE:
+    outbound is no longer "just code in a journey" — for event fan-out, reach for
+    a destination, not a per-step integration call.

package/src/commands/webhooks.ts

@@ -4,10 +4,10 @@ import { color } from "../lib/output.js";
 import type { Command, CommandContext } from "./types.js";
 
 /**
- * The 12-event outbound catalog, VENDORED from the engine's
+ * The 13-event outbound catalog, VENDORED from the engine's
  * `WEBHOOK_EVENT_TYPES` (lib/webhook-signing.ts). The CLI cannot import the
- * engine, so the tuple is re-declared here; a drift test asserts equality. The
- * `webhook.test` sentinel is NOT a member (out-of-band).
+ * engine, so the tuple is re-declared here and MUST be kept in sync BY HAND when
+ * the engine catalog changes. The `webhook.test` sentinel is NOT a member.
  */
 const WEBHOOK_EVENT_TYPES = [
   "contact.created",
@@ -19,6 +19,7 @@ const WEBHOOK_EVENT_TYPES = [
   "email.opened",
   "email.clicked",
   "email.bounced",
+  "email.complained",
   "journey.completed",
   "bucket.entered",
   "bucket.left",
@@ -49,14 +50,14 @@ list options:
 create options (--url required, plus at least one event):
   --url <url>                Destination URL (required).
   --event <type>             Subscribe to an event; repeatable.
-  --all-events               Subscribe to all 12 event types.
+  --all-events               Subscribe to all 13 event types.
   --description <text>       Human label.
   --disabled                 Create the endpoint disabled.
 
 update options (only the provided fields change):
   --url <url>                New destination URL.
   --event <type>             Replace the subscribed events (repeatable).
-  --all-events               Subscribe to all 12 event types.
+  --all-events               Subscribe to all 13 event types.
   --description <text>       New description.
   --disabled / --enabled     Disable or enable the endpoint.
 
@@ -80,7 +81,9 @@ interface WebhookEndpoint {
   url: string;
   description: string | null;
   eventTypes: OutboundEventType[];
-  secretPrefix: string;
+  // null for keyed destinations (kind !== "webhook"), which carry no signing
+  // secret — their credentials live in the endpoint config, not a whsec_.
+  secretPrefix: string | null;
   status: "enabled" | "disabled";
   organizationId: string | null;
   lastDeliveryAt: string | null;
@@ -228,7 +231,7 @@ function renderEndpoint(
           ? color.green(ep.status)
           : color.yellow(ep.status),
       eventTypes: ep.eventTypes,
-      secretPrefix: ep.secretPrefix,
+      secretPrefix: ep.secretPrefix ?? color.dim("(none — keyed destination)"),
       lastDeliveryAt: ep.lastDeliveryAt ?? color.dim("(never)"),
       createdAt: ep.createdAt,
       updatedAt: ep.updatedAt,