@hogsend/cli 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
     "dist",
     "src",
     "skills",
+    "studio",
     "README.md"
   ],
   "publishConfig": {
@@ -31,6 +32,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
+    "@hogsend/studio": "^0.3.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {
@@ -41,6 +43,7 @@
     "picocolors": "^1.1.1"
   },
   "scripts": {
+    "prebuild": "node scripts/bundle-studio.mjs",
     "build": "tsup",
     "check-types": "tsc --noEmit",
     "lint": "biome check .",

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

@@ -0,0 +1,69 @@
+---
+name: hogsend-authoring-buckets
+description: Use when adding or editing a real-time audience bucket in src/buckets/ — defineBucket() with a criteria condition tree, time-based rolling windows + reconcile, entryLimit, the hand-maintained BucketId literal-union typo-safety ritual, and binding journeys to bucket:entered / bucket:left triggers. Buckets wire into BOTH createHogsendClient and createWorker.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Authoring Hogsend buckets
+
+A **bucket** is a real-time, code-defined group of users — the peer of a
+journey. A user JOINS the moment their data satisfies `meta.criteria` and LEAVES
+when it stops. Each transition fires `bucket:entered:<id>` / `bucket:left:<id>`
+through the same ingestion spine a journey trigger binds to, so buckets are how
+you turn "who is in this audience right now" into "start/stop a flow".
+
+This skill is for editing a scaffolded app's `src/buckets/` (content only). You
+import `defineBucket` / `DefinedBucket` from `@hogsend/engine` and the condition
+helpers / duration helpers from `@hogsend/core`. You never touch engine
+internals — the engine owns the registry, the reconcile cron, and the backfill.
+
+## Key concepts
+
+- **`defineBucket({ meta })`** — returns a `DefinedBucket`. `meta.criteria` is the
+  membership predicate, authored as a `ConditionEval` data tree OR a fluent
+  `(b) => b.all(...)` builder function. Same condition system journeys use.
+- **Real-time path** — on every ingested event the engine re-evaluates candidate
+  buckets and writes/flips `bucket_memberships` rows, emitting transitions.
+- **Time-based path** — `criteria` with a rolling `within` window (or `maxDwell`)
+  can flip membership with NO inbound event; the engine-wide reconcile cron
+  sweeps those leaves/joins on a cadence (default every 5 min).
+- **`entryLimit` / `entryPeriod`** — gate when a RE-join re-emits `bucket:entered`.
+- **The `BucketId` ritual** — a hand-maintained literal union in
+  `src/journeys/constants/index.ts` plus `bucketEntered`/`bucketLeft` helpers that
+  make a typo'd trigger binding a COMPILE error.
+- **Dual wiring** — buckets thread into BOTH `createHogsendClient({ buckets })`
+  (registry, real-time eval, reconcile) AND `createWorker({ buckets })`
+  (fast-expiry timer task + boot backfill).
+
+Criteria use the same 4-type condition engine (property / event /
+email_engagement / composite) and the same `days()`/`hours()`/`minutes()`
+duration helpers as journeys — see the hogsend-conditions skill for operator and
+window semantics.
+
+## Task playbooks — load the matching reference
+
+- **Author / shape a bucket's `meta`** (id, criteria, time windows, entryLimit,
+  dwell, fastExpiry) → `references/bucket-meta.md`
+- **Keep trigger names typo-safe** (the `BucketId` union + `bucketEntered`/
+  `bucketLeft` alias ritual and why it exists) → `references/bucket-id-aliases.md`
+- **Decide bucket vs journey** (membership vs a one-shot durable flow; how
+  `bucket:entered`/`bucket:left` drive journeys) → `references/buckets-vs-journeys.md`
+- **Register + wire a bucket** (export from `src/buckets/index.ts`, thread into
+  `createHogsendClient` AND `createWorker`, the reconcile cron) →
+  `references/register-a-bucket.md`
+
+## Golden rules
+
+1. A `kind:"dynamic"` bucket (the default) REQUIRES `criteria`, and the criteria
+   must contain at least one POSITIVE leaf — pure-negation criteria are rejected
+   at registration. A windowed `event(...).within(W).notExists()` counts as a
+   valid (time-bounded) anchor.
+2. Never reference a `bucket:*` event name inside `criteria` — it is rejected at
+   registration so transition rows can never satisfy a predicate.
+3. Add the new id to the `BucketId` union the moment you add the bucket. Without
+   it, a journey can bind to a misspelled alias that silently never fires.
+4. Wire `buckets` into BOTH factories. The client without the worker means no
+   reconcile/fast-expiry; the worker without the client means an empty registry.

package/skills/hogsend-authoring-buckets/references/bucket-id-aliases.md

@@ -0,0 +1,117 @@
+# The `BucketId` union + `bucketEntered` / `bucketLeft` ritual
+
+When a user joins or leaves a bucket the engine emits a per-bucket ALIAS event:
+`bucket:entered:<id>` / `bucket:left:<id>` (e.g. `bucket:entered:power-users`).
+Journeys bind to those alias strings via `trigger.event`. The problem: a
+journey's `trigger.event` is typed `string`, so a misspelled alias compiles fine
+and the journey just silently never fires.
+
+The fix is a hand-maintained literal union plus two typed helper functions, in
+the CONSUMER's `src/journeys/constants/index.ts`. This is the ritual you MUST
+keep in sync whenever you add or rename a bucket.
+
+## The constants block
+
+```ts
+// src/journeys/constants/index.ts
+
+/**
+ * The union of bucket ids registered in src/buckets/index.ts. Keep this in sync
+ * with the `buckets` array — it is what makes the alias helpers catch a typo at
+ * COMPILE time.
+ */
+export type BucketId = "power-users";
+
+// Narrow-alias helpers — ONLY accept a registered BucketId, so a typo such as
+// bucketEntered("power-uesrs") is a compile error rather than a silently
+// never-firing trigger. The return type is the EXACT literal event name, so it
+// drops straight into a journey's trigger.event / exitOn rule.
+export const bucketEntered = <T extends BucketId>(id: T) =>
+  `bucket:entered:${id}` as const;
+
+export const bucketLeft = <T extends BucketId>(id: T) =>
+  `bucket:left:${id}` as const;
+```
+
+When you add a second bucket, the union grows by hand:
+
+```ts
+export type BucketId = "power-users" | "went-dormant";
+```
+
+## Why it MUST be a hand-written literal union
+
+You might be tempted to derive the union from the `buckets` array:
+
+```ts
+// DON'T — this collapses to `string` and loses all typo-safety.
+type BucketId = (typeof buckets)[number]["meta"]["id"];
+```
+
+`defineBucket` widens `meta.id` to `string` (`BucketMeta.id: string`), so an
+array-derived union evaluates to `string`. Then `bucketEntered("anything")`
+type-checks, and the whole guard is gone. The explicit literal union is the
+source of truth precisely because it can't be widened.
+
+## How journeys consume the helpers
+
+The helpers return the exact literal, so they drop straight into a journey's
+`trigger.event` (and `exitOn`):
+
+```ts
+import { hours } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { bucketEntered, bucketLeft, Templates } from "./constants/index.js";
+
+export const winback = defineJourney({
+  meta: {
+    id: "winback",
+    name: "Win-back",
+    enabled: true,
+    // Enroll the moment a user lands in the went-dormant bucket.
+    trigger: { event: bucketEntered("went-dormant") },
+    entryLimit: "once_per_period",
+    // `suppress` is REQUIRED on every JourneyMeta — the re-entry cool-down.
+    suppress: hours(24),
+    // Pull them out the instant they re-activate (leave the bucket).
+    exitOn: [{ event: bucketLeft("went-dormant") }],
+  },
+  run: async (user) => {
+    await sendEmail({
+      to: user.email,
+      userId: user.id,
+      journeyStateId: user.stateId,
+      template: Templates.ACTIVATION_NUDGE,
+      subject: "We miss you",
+      journeyName: user.journeyName,
+    });
+  },
+});
+```
+
+A typo'd id — `bucketEntered("went-dorment")` — is now a compile error.
+
+## Generic forms vs aliases
+
+The constants file also defines the GENERIC events:
+
+```ts
+export const Events = {
+  // ...
+  BUCKET_ENTERED: "bucket:entered",
+  BUCKET_LEFT: "bucket:left",
+} as const;
+```
+
+These fire for ANY bucket. The engine only emits the generic `bucket:entered` /
+`bucket:left` when a journey actually binds to it (otherwise it's not written at
+all). Prefer the narrowly-routed per-bucket aliases (`bucketEntered(id)`) for
+real journey bindings — bind to the generic forms only if you genuinely want
+"any bucket transition" routing.
+
+## The checklist when adding a bucket
+
+1. Add the `defineBucket(...)` in `src/buckets/`.
+2. Add its `meta.id` literal to the `BucketId` union.
+3. Register it in `src/buckets/index.ts` (see register-a-bucket).
+4. Bind journeys with `bucketEntered("<id>")` / `bucketLeft("<id>")`.

package/skills/hogsend-authoring-buckets/references/bucket-meta.md

@@ -0,0 +1,142 @@
+# Authoring a bucket's `meta`
+
+A bucket is `defineBucket({ meta })`. The `meta` (a `BucketMeta`) is the whole
+declaration — the engine derives everything (registry indexes, reconcile
+behavior, Studio size) from it. This is the field-by-field guide.
+
+```ts
+import { defineBucket } from "@hogsend/engine";
+import { days } from "@hogsend/core";
+import { Events } from "../journeys/constants/index.js";
+
+export const powerUsers = defineBucket({
+  meta: {
+    id: "power-users",                 // also the alias suffix: bucket:entered:power-users
+    name: "Power users",
+    description: "Used the key feature 10+ times in the last 30 days.",
+    enabled: true,
+    timeBased: true,                    // rolling window → reconcile owns the leave
+    entryLimit: "once_per_period",
+    entryPeriod: { hours: 24 * 7 },     // 7-day cooldown before a re-emit
+    criteria: {
+      type: "event",
+      eventName: Events.FEATURE_USED,
+      check: "count",
+      operator: "gte",
+      value: 10,
+      within: days(30),                 // makes the bucket time-based
+    },
+  },
+});
+```
+
+## The fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `string` (required) | Stable identity AND the alias suffix. Changing it makes a NEW bucket. Keep it in the `BucketId` union (see bucket-id-aliases). |
+| `name` | `string` (required) | Human label, surfaced in Studio + the emitted `bucketName`. |
+| `description` | `string?` | Free text. |
+| `enabled` | `boolean` (required) | Static load-time on/off (guard #1), mirrors a journey's `enabled`. A disabled bucket is not registered. |
+| `kind` | `"dynamic" \| "manual"?` | Defaults `"dynamic"`. `"manual"` is REJECTED at registration in v1 — always use dynamic + `criteria`. |
+| `criteria` | `ConditionEval?` | The membership predicate. REQUIRED for dynamic buckets. |
+| `entryLimit` | `"once" \| "once_per_period" \| "unlimited"?` | Defaults `"unlimited"`. Gates re-EMISSION of `bucket:entered` on a re-join. |
+| `entryPeriod` | `DurationObject?` | The cooldown for `"once_per_period"`: re-emit only once this elapses since the prior LEAVE. |
+| `minDwell` | `DurationObject?` | Anti-flap floor: defer (never drop) `bucket:left` until membership is at least this old. |
+| `maxDwell` | `DurationObject?` | Unconditional membership TTL: force-leave N after join REGARDLESS of criteria. |
+| `timeBased` | `boolean?` | Marks that a clock (not an event) can flip membership. Inferred from a `within` window if omitted; set it explicitly for clarity. |
+| `reconcileEvery` | `DurationObject?` | Advisory cadence surfaced in Studio (one engine-wide cron sweeps all time-based buckets; this is informational). |
+| `reconcileJoins` | `boolean?` | Tri-state. `false` = hard off; `true` = explicit on; `undefined` = inferred on only for safe absence shapes. See "Time-based" below. |
+| `fastExpiry` | `boolean?` | Opt-in per-user durable timer for sub-second absence leaves. Defaults `false`; cron is the backstop. Requires worker wiring. |
+| `syncToPostHog` | `boolean?` | Mirror membership to a PostHog person property on join/leave. Off by default; no-op without `POSTHOG_API_KEY`. |
+| `postHogPropertyKey` | `string?` | Override the synced property name (default `hogsend_bucket_<id>`). |
+
+## `criteria` — two authoring forms
+
+Both forms produce the SAME `ConditionEval` data. The builder runs ONCE at
+definition time and is resolved to declarative data by `defineBucket`, so the
+registry / schema / reconcile only ever see the canonical tree.
+
+**Declarative tree** (a `ConditionEval`):
+
+```ts
+criteria: {
+  type: "composite",
+  operator: "and",
+  conditions: [
+    { type: "property", property: "plan", operator: "eq", value: "pro" },
+    {
+      type: "event",
+      eventName: Events.FEATURE_USED,
+      check: "count",
+      operator: "gte",
+      value: 5,
+      within: days(14),
+    },
+  ],
+}
+```
+
+**Fluent builder** — `criteria` accepts `(b: CriteriaBuilder) => ConditionEval`:
+
+```ts
+criteria: (b) =>
+  b.all(
+    b.prop("plan").eq("pro"),
+    b.event(Events.FEATURE_USED).within(days(14)).atLeast(5),
+  ),
+```
+
+Builder surface: `b.prop(name)` → `.eq/.neq/.gt/.gte/.lt/.lte/.contains/.exists/.notExists`;
+`b.event(name)` → optional `.within(window)` then a terminal
+`.exists()/.notExists()/.count(op, n)/.atLeast(n)/.moreThan(n)/.atMost(n)/.lessThan(n)/.exactly(n)`;
+`b.all(...)`/`b.any(...)` for AND/OR composites.
+
+For the full operator table, window semantics, and how `event` count/within
+windows evaluate, see the hogsend-conditions skill — bucket criteria are the
+exact same condition system.
+
+## Registration validation (fail-fast rules)
+
+`BucketRegistry.register()` runs `bucketMetaSchema.parse()`, so these throw at
+client/worker boot, not silently:
+
+- **At least one positive leaf.** A dynamic bucket whose every leaf is negative
+  (`property neq`/`not_exists`, `event not_exists` with NO `within`,
+  `email_engagement not_opened`/`not_clicked`) is degenerate. Exception: an
+  `event ... not_exists` WITH a `within` window is a valid time-bounded dormancy
+  anchor and counts as legitimate.
+- **No reserved event names.** No `EventCondition.eventName` may start with
+  `bucket:` — transition rows must never satisfy a predicate.
+- **No `email_engagement` in v1.** Engagement conditions are not allowed in
+  bucket criteria (they ARE allowed in journey conditions).
+- **`maxDwell >= minDwell`** when both are set.
+- **`kind:"manual"` is rejected.** Use `kind:"dynamic"`.
+
+## Time-based buckets (rolling windows + reconcile)
+
+A `within` window means a user can fall OUT with no inbound event (the window
+just rolls past). The real-time path structurally can't catch that, so the
+engine-wide reconcile cron sweeps every time-based dynamic bucket and leaves
+members whose criteria no longer hold.
+
+- **Leaves** are handled automatically for any time-based bucket — no extra
+  config. The 30-day `power-users` example above leaves a user the moment they
+  drop below 10 uses in the trailing 30 days, swept by the cron.
+- **Absence joins** (a user who STOPPED doing X fires no event) need the cron to
+  materialize the join. `reconcileJoins` is INFERRED on for the two safe
+  set-based absence shapes — a single windowed `event(X).within(W).notExists()`,
+  and the lapsed-active composite `all(event(X).exists(), event(X).within(W).notExists())`.
+  Any other absence-containing composite (OR-of-absence, absence mixed with
+  property/count) needs an explicit `reconcileJoins: true`.
+- **`maxDwell`** is a hard time-box independent of criteria — pair with
+  `entryLimit:"once"`/`"once_per_period"` for "in for exactly N then out", or
+  leave the default `"unlimited"` for a periodic flush (re-join on next
+  qualifying event).
+- **`fastExpiry: true`** arms a per-user durable timer so the leave lands
+  sub-second instead of waiting for the next cron tick. It needs the bucket
+  wired into `createWorker` (see register-a-bucket); the cron is still the
+  authoritative backstop.
+
+Reconcile cadence is the `BUCKET_RECONCILE_CRON` env var (default `*/5 * * * *`),
+so time-based exits land within that cadence, not to-the-second.

package/skills/hogsend-authoring-buckets/references/buckets-vs-journeys.md

@@ -0,0 +1,96 @@
+# Bucket vs journey — when to use which
+
+Buckets and journeys are peers built on the same ingestion spine, but they
+answer different questions:
+
+- A **bucket** answers **"who is in this audience right NOW?"** It is continuous
+  membership. A user is in or out at every instant based on whether their data
+  satisfies `criteria`. There is no flow, no steps, no sleeps — just a
+  `bucket_memberships` row that flips active/left as the data changes.
+- A **journey** answers **"run this one-shot durable flow for a user."** It is a
+  TypeScript control-flow process: send, `ctx.sleep`, branch, send again. It has
+  a beginning and an end, durable state, and enrollment guards.
+
+Buckets DRIVE journeys: a join/leave transition emits an event, and a journey
+can trigger (or exit) on that event. That's the whole integration.
+
+## Pick a bucket when…
+
+- You're describing a STATE that comes and goes: "power users", "trial ending
+  this week", "went dormant", "on the pro plan and active".
+- Membership should self-heal as data changes — including time-based exits (a
+  rolling `within` window rolling past) with no inbound event. The reconcile
+  cron owns those leaves; a journey cannot observe "nothing happened".
+- You want to reuse the same audience for MANY downstream flows. One bucket, N
+  journeys binding to its transitions.
+- You want the audience size visible in Studio.
+
+## Pick a journey when…
+
+- You're describing a SEQUENCE with timing: welcome series, dunning, onboarding
+  nudges. Steps, durable sleeps, branches.
+- The thing is a one-time reaction to an event, not an ongoing membership.
+- You need per-step email sends, history checks, cross-journey triggers, etc.
+
+## How transitions drive journeys
+
+On a real join the engine emits `bucket:entered:<id>`; on a leave,
+`bucket:left:<id>`. Both flow through the SAME `ingestEvent` pipeline a normal
+event does, so journeys route on them exactly like any other trigger. Bind with
+the typed `bucketEntered`/`bucketLeft` helpers (see bucket-id-aliases):
+
+```ts
+import { days, hours } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { bucketEntered, bucketLeft, Templates } from "./constants/index.js";
+
+export const powerUserOnboarding = defineJourney({
+  meta: {
+    id: "power-user-onboarding",
+    name: "Power-user onboarding",
+    enabled: true,
+    trigger: { event: bucketEntered("power-users") },   // join → start the flow
+    entryLimit: "once_per_period",
+    suppress: hours(24),                                 // required re-entry cool-down
+    exitOn: [{ event: bucketLeft("power-users") }],      // leave → pull them out
+  },
+  run: async (user, ctx) => {
+    await sendEmail({
+      to: user.email,
+      userId: user.id,
+      journeyStateId: user.stateId,
+      template: Templates.ACTIVATION_WELCOME,
+      subject: "You're a power user now — here's the deep dive",
+      journeyName: user.journeyName,
+    });
+    await ctx.sleep({ duration: days(3), label: "follow-up" });
+    // ...continue the flow
+  },
+});
+```
+
+## The re-emit / debounce knobs work TOGETHER
+
+A bucket and the journeys it drives both have entry policies; tune them so
+oscillation doesn't spam:
+
+- **Bucket `minDwell`** debounces flapping membership — it defers `bucket:left`
+  until membership has existed at least that long, so a user bouncing in and out
+  doesn't fire a leave-then-enter storm.
+- **Bucket `entryLimit` / `entryPeriod`** gate when a RE-join re-emits
+  `bucket:entered` (e.g. `"once_per_period"` with a 7-day `entryPeriod` won't
+  re-emit a join within a week of the prior leave).
+- **Journey `entryLimit` / `suppress`** are the journey's own re-entry guard on
+  top of that.
+
+Rule of thumb: shape the audience on the bucket (`criteria`, `minDwell`,
+`entryLimit`), shape the messaging cadence on the journey (`suppress`,
+`exitOn`). For the condition/duration semantics shared by both, see the
+hogsend-conditions skill.
+
+## What buckets are NOT
+
+Buckets are observe-only in Studio — there is no visual builder, exactly like
+journeys. They live in code. And `kind:"manual"` (membership mutated only by
+explicit API/import) is declared on the type for forward-compat but is REJECTED
+at registration in v1 — every bucket today is `kind:"dynamic"` with `criteria`.

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

@@ -0,0 +1,129 @@
+# Registering + wiring a bucket (dual wiring)
+
+A bucket only does anything once it is (1) exported from the barrel and (2)
+threaded into BOTH engine factories. This is the dual wiring the SKILL keeps
+warning about: `createHogsendClient` AND `createWorker`. Miss either and the
+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.
+
+```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.
+ */
+export const buckets: DefinedBucket[] = [powerUsers, wentDormant];
+
+// Re-export individual buckets for direct reference (tests, custom wiring).
+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.
+
+## 2. Thread into `createHogsendClient` (the registry + real-time + reconcile)
+
+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()`.
+
+```ts
+// src/index.ts
+import { createApp, createHogsendClient } from "@hogsend/engine";
+import { buckets } from "./buckets/index.js";
+import { templates } from "./emails/index.js";
+import { journeys } from "./journeys/index.js";
+import { webhookSources } from "./webhook-sources/index.js";
+
+const client = createHogsendClient({ journeys, buckets, email: { templates } });
+
+// ...schema boot-guard...
+
+const app = createApp(client, { webhookSources });
+```
+
+## 3. Thread into `createWorker` (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`.
+
+```ts
+// src/worker.ts
+import { createHogsendClient, createWorker } from "@hogsend/engine";
+import { buckets } from "./buckets/index.js";
+import { templates } from "./emails/index.js";
+import { journeys } from "./journeys/index.js";
+import { extraWorkflows } from "./workflows/index.js";
+
+async function main() {
+  const client = createHogsendClient({
+    journeys,
+    buckets,
+    email: { templates },
+  });
+  const worker = createWorker({
+    container: client,
+    journeys,
+    buckets,            // ← registers fastExpiry timer task(s) for opted-in buckets
+    extraWorkflows,
+  });
+
+  // ...signal handlers...
+  await worker.start();
+}
+```
+
+## 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. |
+
+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.
+
+## The reconcile cron (engine-owned — you don't register it)
+
+The engine ALWAYS registers `bucketReconcileTask` and `bucketBackfillTask` in
+the worker's base workflows — you do NOT add them to `extraWorkflows`. The cron:
+
+- runs on `BUCKET_RECONCILE_CRON` (default `*/5 * * * *`), non-cancelling (an
+  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;
+- 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);
+- 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.
+
+So: change a bucket's `criteria` and redeploy the worker → the engine
+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.
+- The `ENABLED_BUCKETS` env var (comma-separated ids, or `*` for all) filters
+  which buckets load, mirroring `ENABLED_JOURNEYS`. You can override per-call via
+  `createHogsendClient({ enabledBuckets })` / `createWorker({ enabledBuckets })`.
+
+To verify a bucket is live on a running instance (membership counts, transition
+events), see the hogsend-cli skill.

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

@@ -0,0 +1,68 @@
+---
+name: hogsend-authoring-emails
+description: Use when adding or editing a transactional email in src/emails/ — creating a react-email .tsx, keeping the four-file contract (component, types.ts props, registry.ts entry, templates.d.ts augmentation) in sync with the Templates constant key, sharing _components, plaintext/preview, and how link-click + open tracking and unsubscribe are applied automatically on send.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Authoring Hogsend emails
+
+A Hogsend email is a [react-email](https://react.email) component plus three
+small sidecar declarations that make it sendable and type-checked. You author
+them in your app's `src/emails/`; `@hogsend/email` is render machinery only — it
+bakes in no concrete templates. You call the engine factories and import from
+`@hogsend/engine` / `@hogsend/email`; you never edit engine internals.
+
+The send pipeline is engine-owned: the same `createTrackedMailer` that renders
+your template also rewrites every link for click tracking, injects an open
+pixel, runs preference/suppression checks, and writes the `email_sends` row —
+automatically, before the email reaches the provider. That is why tracking and
+unsubscribe live in THIS skill, not a separate one: you get them for free on
+every send, and what you author in `src/emails/` only has to leave room for them
+(an `unsubscribeUrl` slot in the footer).
+
+## The five touch points that must agree
+
+Every template is really FIVE coordinated edits keyed on one string:
+
+1. `src/emails/<name>.tsx` — the react-email component (default export).
+2. `src/emails/types.ts` — its `Props` interface.
+3. `src/emails/registry.ts` — a `templates[key]` entry (component + subject).
+4. `src/emails/templates.d.ts` — augments `TemplateRegistryMap` so `key → Props`.
+5. `src/journeys/constants/index.ts` — the `Templates.*` constant journeys send.
+
+If the key in (3), (4), and (5) drifts, or the `Props` in (2)/(4) disagree, you
+get a type error at the send call site — the #1 trap. See
+`references/template-four-file-contract.md`.
+
+## Key concepts
+
+- **Registry is wired once.** `src/emails/index.ts` exports `templates`;
+  `src/index.ts` passes it as `createHogsendClient({ email: { templates } })`.
+  You only edit `src/emails/`; the wiring already exists.
+- **Shared chrome lives in `src/emails/_components/`** — `Layout` (preview +
+  card + footer), `ui` primitives (`Title`/`Body`/`Button`/`Callout`/…), `Logo`,
+  `Footer`. Compose these instead of raw HTML.
+- **Subject + preview + category** are declared on the registry entry, not in the
+  component. `defaultSubject` is the fallback subject; `preview` is the inbox
+  snippet; `category` drives frequency-cap exemption (`transactional` is exempt).
+- **Tracking + unsubscribe are automatic on `emailService.send` / `sendEmail`.**
+  You never call `prepareTrackedHtml` or `generateUnsubscribeUrl` yourself.
+
+## Task playbooks — load the matching reference
+
+- **Add or rename a template and keep all five touch points in sync (and read
+  the type-error trap)** → `references/template-four-file-contract.md`
+- **Build the component itself: shared `_components`, props typing, preview /
+  category / defaultSubject, plaintext** → `references/email-components.md`
+- **Render or preview a template, and how the consumer registry is built /
+  threaded** → `references/preview-and-render.md`
+- **What happens automatically on send: link-click + open tracking, the
+  `/v1/t/*` endpoints, the unsubscribe token/URL + preference checks** →
+  `references/tracking-and-unsubscribe.md`
+
+To send a template from inside a lifecycle flow, see the
+**hogsend-authoring-journeys** skill. To inspect a send / open / click rate
+against a live instance, see the **hogsend-cli** skill.