@hogsend/cli 0.0.1 → 0.2.0

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.

package/skills/hogsend-authoring-emails/references/email-components.md

@@ -0,0 +1,112 @@
+# Building the component — shared `_components`, props, preview/category, plaintext
+
+You write the `.tsx` with [react-email](https://react.email) primitives, but
+compose the shared chrome in `src/emails/_components/` instead of hand-rolling
+HTML. That keeps every email visually consistent and leaves the right slots open
+for the engine to inject tracking + unsubscribe.
+
+## The shared `_components`
+
+| Module | Exports | Role |
+|--------|---------|------|
+| `_components/layout.js` | `Layout` | The shell: `<Html>` + `<Head>` + `<Preview>` + `<Tailwind>`, the wordmark, one bordered white card, then the footer. |
+| `_components/ui.js` | `Eyebrow`, `Title`, `Body`, `Button`, `Callout`, `CodeBlock`, `Bullets`, `Divider` | Email-safe design-system primitives. |
+| `_components/logo.js` | `Logo` | Your wordmark above the card. |
+| `_components/footer.js` | `Footer` | Renders the `unsubscribeUrl` / `preferencesUrl` links (rendered by `Layout`, not directly by you). |
+
+`Layout`'s props are the only surface most templates touch:
+
+```ts
+interface LayoutProps {
+  preview: string;          // inbox snippet — required
+  eyebrow?: string;         // small uppercase label above the heading
+  unsubscribeUrl?: string;  // forwarded to <Footer>
+  preferencesUrl?: string;  // forwarded to <Footer>
+  children: ReactNode;
+}
+```
+
+A minimal template composes them like this:
+
+```tsx
+// biome-ignore lint/correctness/noUnusedImports: required for JSX runtime
+import React from "react";
+import { Layout } from "./_components/layout.js";
+import { Body, Bullets, Button, Callout, Divider, Title } from "./_components/ui.js";
+import type { TrialEndingEmailProps } from "./types.js";
+
+export default function TrialEndingEmail({
+  name = "there",
+  daysLeft = 3,
+  upgradeUrl = "https://app.example.com/billing",
+  unsubscribeUrl,
+}: TrialEndingEmailProps) {
+  return (
+    <Layout
+      preview={`${daysLeft} days left on your trial`}
+      eyebrow="Heads up"
+      unsubscribeUrl={unsubscribeUrl}
+    >
+      <Title>Your trial ends in {daysLeft} days</Title>
+      <Body>Hey {name}, here's what you keep when you upgrade:</Body>
+      <Bullets items={["Unlimited journeys", "Full event history", "Priority support"]} />
+      <Divider />
+      <Button href={upgradeUrl}>Upgrade now</Button>
+      <Callout tone="warn">Card on file is never charged automatically.</Callout>
+    </Layout>
+  );
+}
+```
+
+These files live in YOUR repo and are yours to edit — change the colors, add
+primitives, swap `Logo` for a hosted `<Img>`. Use ESM `.js` extensions on the
+relative imports (consumer convention), even though the files are `.tsx`.
+
+## Props typing
+
+Define the props interface in `src/emails/types.ts` and import it into the
+component. Two conventions:
+
+- **Default every prop in the destructure** (`name = "there"`) so previews and
+  admin catalogs render without real data, and a missing prop never produces
+  `undefined` in the body.
+- **Always accept an optional `unsubscribeUrl?: string`.** The engine injects it
+  on send so `Layout`/`Footer` can render the unsubscribe link — see
+  `tracking-and-unsubscribe.md`. Make it optional; direct render/preview calls
+  won't pass it.
+
+## Subject, preview, category — on the registry entry, not the component
+
+These live on the `TemplateDefinition` in `src/emails/registry.ts`, NOT inside
+the `.tsx`:
+
+```ts
+export interface TemplateDefinition<P = Record<string, unknown>> {
+  component: (props: P) => ReactElement;
+  defaultSubject: string;        // fallback subject when send() omits `subject`
+  category?: string;             // e.g. "transactional" | "journey"
+  preview?: (props: P) => string; // inbox snippet, computed from props
+  examples?: Partial<P>;         // sample props for admin previews only
+}
+```
+
+- **`defaultSubject`** is used when the send call doesn't pass an explicit
+  `subject`. Journeys usually pass their own subject; transactional one-offs lean
+  on the default.
+- **`category`** drives frequency capping. The engine's frequency cap exempts
+  `"transactional"` by default — mark genuine transactional mail (receipts,
+  password resets) `"transactional"` and marketing/lifecycle mail `"journey"` so
+  caps apply correctly.
+- **`preview`** sets the snippet most inboxes show next to the subject. Note the
+  `Layout`'s own `preview` prop renders react-email's hidden `<Preview>` text in
+  the HTML; the registry `preview` is the value surfaced to admin/preview tooling
+  via `getPreviewText`. Keep them consistent.
+
+## Plaintext
+
+You do not author a separate plaintext file. The engine renders both halves from
+the same component: `renderToHtml(element)` and `renderToPlainText(element)`
+(react-email's `render(element, { plainText: true })`). Write the component once;
+keep links as real `<a href>` / react-email `Button`/`Link` so the plaintext
+extractor produces readable URLs. See `preview-and-render.md` for the render
+machinery.