@hogsend/cli 0.2.2 → 0.6.0

package/skills/hogsend-authoring-buckets/references/register-a-bucket.md

@@ -7,35 +7,47 @@ bucket is half-alive.
 
 ## 1. Export from `src/buckets/index.ts`
 
-The barrel exports the `buckets: DefinedBucket[]` array — this is the single
-list both factories consume.
+The barrel exports the `buckets` array — this is the single list both factories
+consume. Let the array INFER its element types; do NOT annotate it
+`DefinedBucket[]`. The annotation re-widens each bucket's `Id` literal back to
+`string`, which would erase the literal types on `bucket.entered` / `bucket.left`
+(see bucket-id-aliases).
 
 ```ts
 // src/buckets/index.ts
-import type { DefinedBucket } from "@hogsend/engine";
 import { powerUsers } from "./power-users.js";
 import { wentDormant } from "./went-dormant.js";
 
 /**
  * All defined buckets for this app. Passed to createHogsendClient({ buckets })
  * and createWorker({ buckets }). Edit freely — this is your content.
+ * No `DefinedBucket[]` annotation — let the literal ids survive for typed refs.
  */
-export const buckets: DefinedBucket[] = [powerUsers, wentDormant];
+export const buckets = [powerUsers, wentDormant];
 
-// Re-export individual buckets for direct reference (tests, custom wiring).
+// Re-export individual buckets for direct reference (tests, custom wiring,
+// and binding journeys to their typed `.entered` / `.left` refs).
 export { powerUsers, wentDormant };
 ```
 
-Also add the new id to the `BucketId` union in
-`src/journeys/constants/index.ts` (see bucket-id-aliases) — that's part of
-"registering" a bucket as far as typo-safety goes.
+`createHogsendClient` / `createWorker` accept the base `DefinedBucket[]`, and a
+`DefinedBucket<Id>` is assignable to `DefinedBucket`, so the inferred literal
+array still type-checks at both factories — dropping the annotation is a pure
+type-ergonomics win, never a wiring requirement.
 
-## 2. Thread into `createHogsendClient` (the registry + real-time + reconcile)
+That's the whole registration step. There is no separate `BucketId` union to
+update anymore (the typed refs replace it — see bucket-id-aliases), and any
+`.on()` reactions you attached ship automatically on the bucket (see below). You
+do NOT register reactions separately.
+
+## 2. Thread into `createHogsendClient` (registry + real-time + reconcile + reactions)
 
 In `src/index.ts` (the HTTP entry point), the client receives `buckets`. This
 builds the `BucketRegistry`, installs it as the process singleton (so the
-real-time ingest path and the reconcile cron can resolve it), and validates
-every `meta` via `bucketMetaSchema.parse()`.
+real-time ingest path and the reconcile cron can resolve it), validates every
+`meta` via `bucketMetaSchema.parse()`, and registers each bucket's `.on()`
+reactions into the journey registry (so the admin/Studio feed and the dwell cron
+can resolve them).
 
 ```ts
 // src/index.ts
@@ -52,12 +64,13 @@ const client = createHogsendClient({ journeys, buckets, email: { templates } });
 const app = createApp(client, { webhookSources });
 ```
 
-## 3. Thread into `createWorker` (fast-expiry timer + boot backfill)
+## 3. Thread into `createWorker` (reaction tasks + fast-expiry timer + boot backfill)
 
 In `src/worker.ts` (the task-execution entry point), BOTH the client AND the
 worker get `buckets`. The client call here installs the registry for the worker
-process; the `createWorker({ buckets })` call registers the per-user fast-expiry
-timer task for any bucket with `fastExpiry: true`.
+process; the `createWorker({ buckets })` call registers the durable tasks every
+bucket owns — its `.on()` reaction tasks, plus the per-user fast-expiry timer for
+any bucket with `fastExpiry: true`.
 
 ```ts
 // src/worker.ts
@@ -76,7 +89,7 @@ async function main() {
   const worker = createWorker({
     container: client,
     journeys,
-    buckets,            // ← registers fastExpiry timer task(s) for opted-in buckets
+    buckets,            // ← registers reaction tasks + fastExpiry timer(s)
     extraWorkflows,
   });
 
@@ -85,17 +98,33 @@ async function main() {
 }
 ```
 
+## Reactions ship with the bucket (no separate registration)
+
+Every `bucket.on("enter" | "leave" | "dwell", ...)` call pushes a generated
+durable journey onto `bucket.reactions`. You do NOT add reactions to the
+`journeys` array, and you do NOT register them anywhere — passing `buckets` to
+both factories is enough:
+
+- the client registers each reaction's meta into the journey registry, and
+- the worker registers each reaction's task.
+
+Crucially, reactions are gated by **`ENABLED_BUCKETS`, NOT `ENABLED_JOURNEYS`**.
+Their generated ids (`bucket-<id>-on-enter`, etc.) never appear in a consumer's
+`ENABLED_JOURNEYS` csv, so they are selected with their owning bucket and are
+absent whenever the bucket is disabled. (See the dwell/reactions section of the
+main SKILL for what the reactions DO.)
+
 ## What each side gives you
 
 | Wiring | What it enables |
 |--------|-----------------|
-| `createHogsendClient({ buckets })` | Builds + installs the `BucketRegistry` singleton; validates every `meta`; powers the real-time join/leave eval inside `ingestEvent`; lets the reconcile cron resolve enabled buckets. Required in BOTH `index.ts` and `worker.ts`. |
-| `createWorker({ buckets })` | Registers the single shared `bucket:arm-expiry` durable timer task — but ONLY if some enabled bucket has `fastExpiry: true`. Triggers the boot-time backfill / criteria-change re-eval. |
+| `createHogsendClient({ buckets })` | Builds + installs the `BucketRegistry` singleton; validates every `meta`; registers each bucket's reaction metas into the journey registry (bucket-gated); powers the real-time join/leave eval inside `ingestEvent`; lets the reconcile cron resolve enabled buckets. Required in BOTH `index.ts` and `worker.ts`. |
+| `createWorker({ buckets })` | Registers each bucket's reaction tasks AND the shared fast-expiry durable timer task (the latter only if some enabled bucket has `fastExpiry: true`). Triggers the boot-time backfill / criteria-change re-eval. |
 
-If you ONLY wire the client: time-based and fast-expiry leaves never run (no
-worker tasks), and a new bucket is never backfilled. If you ONLY wire the worker
-(client `buckets` empty): the registry is empty, so the worker's tasks resolve
-nothing.
+If you ONLY wire the client: reaction tasks, time-based, fast-expiry, and dwell
+fires never run (no worker tasks), and a new bucket is never backfilled. If you
+ONLY wire the worker (client `buckets` empty): the registry is empty, so the
+worker's tasks resolve nothing.
 
 ## The reconcile cron (engine-owned — you don't register it)
 
@@ -106,12 +135,15 @@ the worker's base workflows — you do NOT add them to `extraWorkflows`. The cro
   overrunning sweep queues, never cancels);
 - sweeps every enabled time-based / `maxDwell` dynamic bucket and emits
   `bucket:left` (and absence `bucket:entered`) for members the clock moved;
+- runs the `dwell` pass for any bucket with a `dwell` reaction (firing
+  `dwell` over the continuously-resident population — see the main SKILL);
 - is the authoritative backstop even when `fastExpiry` is on.
 
 The boot backfill (`bucketBackfillTask`, kicked off by the worker on start):
 
 - on a NEW bucket id → materializes the full member set from history WITHOUT
-  emitting `bucket:entered` (no historical blast into live journeys);
+  emitting `bucket:entered` (no historical blast into live journeys), and derives
+  the historical `dwellAnchorAt` so `dwell` can fire for the existing population;
 - on a CHANGED `criteria` (detected via a stored hash diff) → re-evaluates: joins
   new matchers silently, and emits `bucket:left` for members who no longer match.
 
@@ -120,9 +152,11 @@ automatically reconciles existing memberships on boot. You don't run a migration
 
 ## Enabling / disabling at load time
 
-- `meta.enabled: false` keeps a bucket out of the registry entirely.
+- `meta.enabled: false` keeps a bucket (and its reactions) out of the registry
+  entirely.
 - The `ENABLED_BUCKETS` env var (comma-separated ids, or `*` for all) filters
-  which buckets load, mirroring `ENABLED_JOURNEYS`. You can override per-call via
+  which buckets load, mirroring `ENABLED_JOURNEYS`. It gates the bucket AND its
+  reactions. You can override per-call via
   `createHogsendClient({ enabledBuckets })` / `createWorker({ enabledBuckets })`.
 
 To verify a bucket is live on a running instance (membership counts, transition

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

@@ -4,7 +4,7 @@ description: Use when adding or editing a lifecycle journey in src/journeys/ —
 license: MIT
 metadata:
   author: withSeismic
-  version: "1.0.0"
+  version: "1.1.0"
 ---
 
 # Authoring Hogsend journeys

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

@@ -32,9 +32,14 @@ interface JourneyMeta {
 ### `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/`:
+[trigger.event]` on its Hatchet durable task, so when that event is pushed,
+Hatchet routes it straight to this journey. The event can originate from any of
+the ingestion spine's entry points: the data-plane `POST /v1/events` endpoint
+(the public event API, also driven by `@hogsend/client`'s `hs.events.send()`), a
+registered webhook source (`POST /v1/webhooks/:sourceId`), or `ctx.trigger()`
+fired from inside another journey. All three funnel through the same
+`ingestEvent()` pipeline, so any of them can enroll a user. Use a constant from
+your `src/journeys/constants/`:
 
 ```ts
 trigger: { event: Events.USER_CREATED },

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

@@ -0,0 +1,178 @@
+---
+name: hogsend-authoring-lists
+description: Use when adding or editing a code-defined email list in src/lists/ — defineList({ id, name, description?, defaultOptIn, enabled? }) from @hogsend/engine. A list is just a named email_preferences.categories key (NO new table); defaultOptIn:false = opt-in, defaultOptIn:true = opt-out. Covers the reserved ids, the id pattern, and the register ritual (src/lists/index.ts + thread the lists array into createHogsendClient in BOTH src/index.ts and src/worker.ts — lists are NOT passed to createWorker). Surfaced at GET /v1/lists + POST /v1/lists/:id/(un)subscribe.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Authoring Hogsend lists
+
+A **list** is a code-defined email subscription category — a newsletter, a
+product-updates digest, a beta-announcements channel. You declare it with
+`defineList()` in `src/lists/`, mirroring `defineJourney()` / `defineBucket()`:
+a synchronous, definition-time call that validates the id and returns a
+`DefinedList`.
+
+The headline fact: **a list is NOT a new table.** It is a named key inside the
+existing `email_preferences.categories` JSONB. `defineList` just declares that
+key, gives it a human name, and sets its **default polarity** (`defaultOptIn`).
+The engine's mailer suppression check and the preference center read that key;
+the data plane exposes it at `GET /v1/lists` + `POST /v1/lists/:id/(un)subscribe`.
+
+You are editing a **scaffolded consumer app** (content only). You import
+`defineList` from `@hogsend/engine`; you never touch engine internals (the
+registry, the suppression check, the preference-center wiring are all engine-owned).
+
+## The shape
+
+```ts
+import { defineList } from "@hogsend/engine";
+
+export const productUpdates = defineList({
+  id: "product-updates",                 // category key — see id rules below
+  name: "Product updates",               // human label (shown in GET /v1/lists)
+  description: "New features and product news.", // optional
+  defaultOptIn: false,                   // opt-in (blocked until subscribed)
+  // enabled: true,                      // optional, defaults to true
+});
+```
+
+`defineList({ id, name, description?, defaultOptIn, enabled? })`:
+
+| field | required | notes |
+|-------|----------|-------|
+| `id` | yes | The `email_preferences.categories` key. Must match `/^[a-z0-9_-]+$/i` (letters, digits, `-`, `_`). `transactional` and `journey` are **RESERVED** and rejected (they are the engine's built-in non-list categories — colliding would corrupt suppression logic). |
+| `name` | yes | Human label surfaced on the list API + preference center. |
+| `description` | no | Optional one-liner; omitted from `meta` entirely when absent. |
+| `defaultOptIn` | yes | The default polarity. See below — this is the one decision that matters. |
+| `enabled` | no | Defaults to `true`. A disabled list is dropped from the registry. |
+
+A malformed or reserved `id` makes `defineList` **throw at definition time** — so
+a bad list id fails fast at boot, not silently at send time.
+
+## `defaultOptIn` — opt-in vs opt-out (the only real decision)
+
+A list's default polarity decides whether a contact is subscribed BEFORE they
+ever touch the preference center. The mailer's suppression check reads
+`email_preferences.categories[id]` against this default:
+
+- **`defaultOptIn: false` (opt-in).** The contact is NOT subscribed until they
+  explicitly subscribe. A send gated on this list is **blocked unless
+  `categories[id] === true`** (an exact `true`). This is the right default for a
+  marketing newsletter, a beta list, anything that needs affirmative consent.
+- **`defaultOptIn: true` (opt-out).** The contact IS subscribed by default. A
+  send is blocked **only on an explicit `false`** (`categories[id] === false`) —
+  absence or any other value means subscribed. This is the "default newsletter
+  everyone gets until they unsubscribe" pattern.
+
+The asymmetry is deliberate: opt-in requires an exact `true`, opt-out requires an
+exact `false`. Everything in between resolves to "subscribed" for opt-out and
+"not subscribed" for opt-in.
+
+To gate a send on a list, pass the list id as the `category` on the send (the
+engine's `sendEmail()` / the data-plane `POST /v1/emails`). The suppression check
+then applies the polarity above. A send with no `category` is not gated on any
+list.
+
+## Subscribe / unsubscribe paths
+
+Membership is just a write to `categories[id]`. Three surfaces flip it:
+
+- **Data plane:** `POST /v1/lists/:id/subscribe` (sets `true`) /
+  `POST /v1/lists/:id/unsubscribe` (sets `false`), by identity (`email` or
+  `userId`). `GET /v1/lists` returns every defined list's
+  `{ id, name, description?, defaultOptIn }`.
+- **`@hogsend/client`:** `hs.lists.list()` / `hs.lists.subscribe(...)` /
+  `hs.lists.unsubscribe(...)` (see the hogsend-client-sdk skill).
+- **As a side effect of a write:** `contacts.upsert` and `events.send` accept a
+  `lists: { [id]: boolean }` map that subscribes/unsubscribes inline.
+
+You author the list; you do NOT write any of these endpoints — the engine mounts
+them off the `ListRegistry` built from your `lists` array.
+
+## Registering a list (the wiring ritual)
+
+A defined list does nothing until it is (1) exported from the barrel and (2)
+threaded into the client in BOTH entry points. **Lists are NOT passed to
+`createWorker`** — unlike buckets, there is no worker-side list wiring. Lists
+resolve entirely through the client's `ListRegistry`, so the worker process picks
+them up via its OWN `createHogsendClient({ lists })` call, not via `createWorker`.
+
+### 1. Export from `src/lists/index.ts`
+
+```ts
+// src/lists/index.ts
+import { defineList } from "@hogsend/engine";
+
+export const productUpdates = defineList({
+  id: "product-updates",
+  name: "Product updates",
+  description: "Occasional emails about new features and product news.",
+  defaultOptIn: false,
+});
+
+// All defined lists for this app. Passed to createHogsendClient({ lists }) in
+// BOTH src/index.ts and src/worker.ts. Edit freely — this is your content.
+export const lists = [productUpdates];
+```
+
+(Let the array infer — no `DefinedList[]` annotation is required, mirroring the
+buckets barrel; the base type re-widens each id literal back to `string`, but a
+`DefinedList<Id>` is still assignable to the base `DefinedList[]` the client
+accepts.)
+
+### 2. Thread into `createHogsendClient` in `src/index.ts`
+
+```ts
+// src/index.ts
+import { createApp, createHogsendClient } from "@hogsend/engine";
+import { lists } from "./lists/index.js";
+// ...templates, journeys, webhookSources...
+
+const client = createHogsendClient({
+  journeys,
+  lists,                 // ← builds the ListRegistry; powers GET /v1/lists + suppression
+  email: { templates },
+});
+
+const app = createApp(client, { webhookSources });
+```
+
+### 3. Thread into `createHogsendClient` in `src/worker.ts`
+
+```ts
+// src/worker.ts
+import { createHogsendClient, createWorker } from "@hogsend/engine";
+import { lists } from "./lists/index.js";
+
+const client = createHogsendClient({
+  journeys,
+  lists,                 // ← same lists array; the worker's mailer needs the registry too
+  email: { templates },
+});
+
+const worker = createWorker({ container: client, journeys /* …, NO lists here */ });
+```
+
+Note the asymmetry vs buckets: `lists` goes into `createHogsendClient` in BOTH
+files, but it is **never** passed to `createWorker`. Passing it to `createWorker`
+is not an option the factory takes. The worker's send path gets lists through the
+client's `ListRegistry`.
+
+Reference implementation: `apps/api/src/lists/index.ts` in the engine monorepo.
+
+## Golden rules
+
+1. A list is a `categories` key, NOT a table. There is no migration, no
+   `db:generate` — `defineList` + the wiring is the whole change.
+2. `defaultOptIn` is the one decision. `false` = opt-in (needs an exact `true` to
+   send); `true` = opt-out (blocked only on an exact `false`). Pick consciously.
+3. `id` must match `/^[a-z0-9_-]+$/i`. `transactional` and `journey` are reserved
+   and throw — they are the engine's own non-list categories.
+4. Wire `lists` into `createHogsendClient` in BOTH `src/index.ts` AND
+   `src/worker.ts`. Do NOT pass `lists` to `createWorker` — it is not an accepted
+   option; lists resolve via the client's `ListRegistry`.
+5. Gate a send on a list by passing the list id as the send's `category`. No
+   `category` = not gated.

package/skills/hogsend-cli/SKILL.md

@@ -4,7 +4,7 @@ description: Use when an agent needs to inspect or operate a running Hogsend lif
 license: MIT
 metadata:
   author: withSeismic
-  version: "1.0.0"
+  version: "1.1.0"
 ---
 
 # Hogsend CLI
@@ -17,16 +17,18 @@ 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.
+Every data command — read AND write — 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 (a write still confirms what it
+did — the server's result body, e.g. `{ id, created, linked }`).
 
 ```bash
 hogsend stats --json
 hogsend journeys list --json
 hogsend contacts get user_123 --json
+hogsend events send signup --user-id user_123 --json
 ```
 
 On error in `--json` mode the CLI prints `{"error":"<message>"}` to stdout and
@@ -34,35 +36,56 @@ 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>`.
+Global flags / env vars control which instance you talk to and with which key.
+The CLI carries TWO key kinds because it spans two HTTP planes:
+
+- **Base URL:** `--url <baseUrl>` > `HOGSEND_API_URL` env > `.env`
+  `HOGSEND_API_URL` > default `http://localhost:3002`.
+- **Admin key** (the `/v1/admin/*` read commands): `--admin-key <key>` >
+  `HOGSEND_ADMIN_KEY` env > `ADMIN_API_KEY` env > the `.env` equivalents. Sent as
+  `Authorization: Bearer <key>`.
+- **Data key** (the data-plane WRITE commands — `contacts upsert`,
+  `events send`, `emails send`): `--data-key <key>` > `HOGSEND_DATA_KEY` env >
+  `HOGSEND_API_KEY` env > the `.env` equivalents. This is an `ingest`-scoped key
+  (a fresh scaffold mints `HOGSEND_API_KEY` as one). Its precedence is
+  INDEPENDENT of the admin key — but since `full-admin` implies `ingest`, an
+  admin key also works as the data key if no dedicated data key is set.
 
 ```bash
 hogsend stats --url https://api.example.com --admin-key "$ADMIN_API_KEY" --json
+hogsend events send signup --user-id u_1 --data-key "$HOGSEND_API_KEY" --json
 ```
 
-`doctor` hits the unauthenticated `/v1/health` and needs no admin key. Every
-other data command requires one.
+`doctor` hits the unauthenticated `/v1/health` and needs no key. Read commands
+require the admin key; the data-plane write commands require the data key.
 
 ## Command map
 
+Most commands READ (admin API). A handful WRITE through the data plane — marked
+**(write)** and using the **data key**, not the admin key.
+
 | 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 journeys list/get/enable/disable` | Inspect + toggle journeys (enable/disable is a write to the admin API). |
+| `hogsend contacts list/get/timeline` | Inspect contacts + their activity (read). |
+| `hogsend contacts upsert` | **(write)** Create/update a contact → `PUT /v1/contacts`. `--email`/`--user-id` (≥1 required), `--prop key=value`/`--props <json>`, `--list <id>`/`--unlist <id>`. |
+| `hogsend events <userId>` | Raw event stream for one user (READ — `<userId>` stays the read path). |
+| `hogsend events send <name>` | **(write)** Push an event → `POST /v1/events`. `--email`/`--user-id` (≥1 required), `--prop`/`--props` (event props), `--contact-prop`/`--contact-props` (contact props), `--list`/`--unlist`, `--idempotency-key`, `--timestamp`. |
+| `hogsend emails send <template>` | **(write)** Send a transactional email → `POST /v1/emails`. `--to`/`--user-id` (≥1 required), `--prop`/`--props`, `--subject`, `--from`, `--reply-to`, `--category`, `--idempotency-key`, `--skip-preference-check` (needs full-admin). |
 | `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). |
 
+`events <userId>` is the READ path; `events send` is its WRITE subcommand —
+they share the `events` command but split on the first positional (`send`). The
+write commands map 1:1 onto the `@hogsend/client` data-plane resources (see the
+hogsend-client-sdk skill); the `--prop` vs `--contact-prop` split on
+`events send` mirrors the SDK's `eventProperties` vs `contactProperties`.
+
 Run `hogsend <command> --help` for per-command usage.
 
 ## Task playbooks (load the matching reference)
@@ -77,5 +100,8 @@ Run `hogsend <command> --help` for per-command usage.
 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.
+3. Most commands READ, but `contacts upsert`, `events send`, `emails send` (and
+   `journeys enable/disable`) WRITE — confirm intent before running them, and
+   make sure a data key resolves (`--data-key` > `HOGSEND_DATA_KEY` >
+   `HOGSEND_API_KEY`) for the data-plane writes.
 4. Use `--limit`/`--offset` for pagination instead of dumping everything.

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

@@ -0,0 +1,185 @@
+---
+name: hogsend-client-sdk
+description: Use when calling Hogsend from your own product/app code (a signup handler, a billing webhook, a cron) via the @hogsend/client SDK + public data-plane API — new Hogsend({ baseUrl, apiKey }), then contacts.upsert/find/delete, events.send (alias .track), emails.send, lists.list/subscribe/unsubscribe. Teaches the contactProperties-vs-eventProperties split on POST /v1/events, the ingest-scoped HOGSEND_API_KEY, the 202 + listsError warning, and HogsendAPIError/RateLimitError. NOT for use inside a journey (there, use sendEmail()/ctx.trigger()). The scaffold ships a preconfigured `hs` at src/lib/hogsend.ts.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Hogsend client SDK (`@hogsend/client`)
+
+`@hogsend/client` is the typed HTTP client for Hogsend's **public data plane** —
+contacts, events, transactional emails, and lists. It is a thin wrapper over
+native `fetch` (no heavy deps, ships ESM + CJS + `.d.ts`). This is how you talk
+to Hogsend from your OWN product code: a signup handler, a Stripe webhook, a
+nightly cron — anything OUTSIDE the engine that needs to upsert a contact, fire
+an event, or send a one-off email.
+
+## Where this belongs (read first)
+
+This SDK is for **app code, not journey code.**
+
+- **Outside the engine** (your API routes, webhooks, jobs) → use this client.
+  You're crossing the network into Hogsend's HTTP data plane.
+- **Inside a journey's `run(user, ctx)`** → do NOT use this client. Use the
+  engine's in-process primitives instead: `sendEmail()` (from `@hogsend/engine`)
+  to send, and `ctx.trigger({ event, userId, properties })` to fire an event
+  back through the ingestion spine. Those run in-process with full attribution
+  and durability; reaching back out over HTTP from inside a journey is wrong.
+
+The scaffold already ships a **preconfigured client** at `src/lib/hogsend.ts`
+exporting `hs`. Import that — do not re-instantiate `new Hogsend(...)` per call:
+
+```ts
+import { hs } from "./lib/hogsend.js";
+
+await hs.events.send({ userId: "u_1", name: "signup" });
+```
+
+`src/lib/hogsend.ts` wires `baseUrl` from `API_PUBLIC_URL` and `apiKey` from
+`HOGSEND_API_KEY` for you. `pnpm bootstrap` mints a local ingest key and writes
+it; in production you create a key with the `ingest` scope and set
+`HOGSEND_API_KEY`.
+
+## Construction + auth
+
+```ts
+import { Hogsend } from "@hogsend/client";
+
+const hs = new Hogsend({
+  baseUrl: "https://api.example.com",      // your deployed API
+  apiKey: process.env.HOGSEND_API_KEY!,    // hsk_… key with the `ingest` scope
+  // fetch?: typeof fetch    — override for tests / custom agents (default: global)
+  // timeoutMs?: number      — per-request timeout, aborts the request (default 30000)
+  // headers?: {…}           — extra headers on every request (e.g. tracing)
+});
+```
+
+**Auth: the data plane requires an `ingest`-scoped key.** `ingest` is an
+*orthogonal* scope (not part of the `read < journey-admin < full-admin`
+hierarchy): a key must either be granted `ingest` explicitly OR hold `full-admin`
+(which implies every data-plane scope). A bare `read` admin key will NOT work
+against the data plane. This is distinct from the admin key the `hogsend` CLI's
+read commands use.
+
+**Identity on every write.** Every write takes at least one of `email` or
+`userId` (your external/distinct id). Both may be supplied. A union type + a
+runtime `assertIdentity` guard enforce that at least one is present — calling
+with neither throws before the request goes out.
+
+## The resources at a glance
+
+```ts
+// Contacts ----------------------------------------------------------------
+await hs.contacts.upsert({                      // PUT /v1/contacts
+  email: "ada@example.com",
+  userId: "u_1",
+  properties: { plan: "pro" },                  // merged onto the contact
+  lists: { newsletter: true },                  // inline list membership
+});                                             // -> { id, created, linked }
+
+await hs.contacts.find({ email: "ada@example.com" }); // GET /v1/contacts/find -> Contact[]
+await hs.contacts.delete({ userId: "u_1" });          // DELETE /v1/contacts -> { deleted }
+
+// Events ------------------------------------------------------------------
+await hs.events.send({                          // POST /v1/events
+  userId: "u_1",
+  name: "signup",
+  eventProperties: { source: "landing" },       // stored ON the event
+  contactProperties: { country: "GB" },         // merged onto the CONTACT
+  idempotencyKey: "evt_abc",
+});                                              // -> { stored, exits, listsError? }
+hs.events.track(/* … */);                       // alias of events.send
+
+// Emails ------------------------------------------------------------------
+await hs.emails.send({                          // POST /v1/emails
+  to: "ada@example.com",
+  template: "welcome",
+  props: { name: "Ada" },
+});                                              // -> { emailSendId, status, reason? }
+
+// Lists -------------------------------------------------------------------
+await hs.lists.list();                          // GET  /v1/lists -> ListSummary[]
+await hs.lists.subscribe({ list: "newsletter", email: "ada@example.com" });
+await hs.lists.unsubscribe({ list: "newsletter", userId: "u_1" });
+```
+
+## `eventProperties` vs `contactProperties` (the split that trips people up)
+
+`POST /v1/events` (`hs.events.send`) takes **two distinct property bags** — they
+land in different places and serve different jobs:
+
+- **`eventProperties`** — stored ON the event row. These are what a journey's
+  `trigger.where` and `exitOn` rules evaluate against. Use them for the
+  per-occurrence facts of THIS event: `{ source: "landing", amount: 49,
+  plan: "pro" }`. They do not change the contact.
+- **`contactProperties`** — merged onto the CONTACT record (the same upsert
+  `contacts.upsert` does). Use them for durable facts about the person:
+  `{ country: "GB", lifecycleStage: "trial" }`. They persist across events and
+  are what later condition checks on the contact read.
+
+Mnemonic: **eventProperties describe the event; contactProperties describe the
+person.** A `purchase` event might carry `eventProperties: { amount: 49 }` (this
+purchase) AND `contactProperties: { hasPurchased: true }` (a lasting fact). The
+same split is exposed by the CLI as `--prop` (event) vs `--contact-prop`
+(contact) on `hogsend events send` — see the hogsend-cli skill.
+
+## The 202 + `listsError` warning
+
+`POST /v1/events` returns **202 Accepted** (the event is durably stored and
+queued for routing), NOT 200. The result is `{ stored, exits }` plus an optional
+`listsError`:
+
+- `stored` — `true` once the event row is written (`false` only on a dedup via
+  `idempotencyKey`).
+- `exits` — the `{ journeyId, stateId, exited }[]` from evaluating active
+  journeys' `exitOn` rules for this user.
+- **`listsError?`** — present ONLY when the event was ingested fine but the
+  (non-atomic, post-ingest) `lists` membership write failed. **The event itself
+  is durably stored** — this is a soft warning surfaced on the 202, not a 400.
+  If you passed `lists` and care that membership applied, check for `listsError`
+  in the result rather than assuming success.
+
+## Errors
+
+All non-2xx responses (and transport failures) throw typed errors:
+
+```ts
+import { HogsendAPIError, RateLimitError } from "@hogsend/client";
+
+try {
+  await hs.emails.send({ to: "x@y.com", template: "welcome", props: {} });
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    // 429 — back off for err.retryAfter seconds (from the Retry-After header)
+  } else if (err instanceof HogsendAPIError) {
+    // err.status (0 = transport failure: DNS/connect/timeout), err.body (parsed JSON or raw text)
+  }
+}
+```
+
+- `HogsendAPIError` — `{ status, body }`. `status === 0` means the request never
+  reached the server.
+- `RateLimitError extends HogsendAPIError` — `status === 429`, with `retryAfter`
+  (seconds) when the `Retry-After` header is present.
+
+## Task playbooks — load the matching reference
+
+- **Full per-resource API: every method's input/result shape, identity rules,
+  the typed `emails.send` registry, idempotency** → `references/api-surface.md`
+
+## Golden rules
+
+1. Use this client from APP code only. Inside a journey, use `sendEmail()` /
+   `ctx.trigger()` — never reach back out over HTTP.
+2. Import the preconfigured `hs` from `src/lib/hogsend.ts`; don't re-instantiate
+   `new Hogsend(...)` per call.
+3. The key needs the `ingest` scope (or `full-admin`). A read admin key is
+   rejected by the data plane.
+4. On `events.send`: `eventProperties` describe the event (drive
+   `trigger.where`/`exitOn`); `contactProperties` merge onto the contact. Don't
+   conflate them.
+5. `events.send` returns 202; check `listsError` if you passed `lists` and care
+   that membership applied.
+6. Every write needs an identity (`email` and/or `userId`).