@hogsend/cli 0.0.1 → 0.2.0

package/skills/hogsend-authoring-emails/references/preview-and-render.md

@@ -0,0 +1,116 @@
+# Render & preview — render helpers, the registry, how the consumer wires it
+
+`@hogsend/email` is render machinery only. It exposes the render functions, the
+registry helpers, and the open `TemplateRegistryMap` type — but no concrete
+templates. Your app supplies the registry; the engine threads it through at send
+and render time.
+
+## The render helpers
+
+```ts
+import { renderToHtml, renderToPlainText } from "@hogsend/email";
+import type { ReactElement } from "react";
+
+// Both wrap react-email's render():
+const html = await renderToHtml(element);        // render(element)
+const text = await renderToPlainText(element);   // render(element, { plainText: true })
+```
+
+You rarely call these directly — the engine's mailer does it for you (HTML + text
+from one component). They're useful for snapshot tests of a `.tsx`.
+
+## The registry helpers
+
+`@hogsend/email` resolves a template KEY against a `TemplateRegistry` you pass
+in:
+
+```ts
+import { getTemplate, getPreviewText, createRegistry } from "@hogsend/email";
+
+// Resolve key → { element, subject, category }
+const { element, subject, category } = getTemplate({
+  key: "activation/welcome",
+  props: { name: "Ada", dashboardUrl: "https://app.example.com" },
+  registry, // your src/emails/registry.ts `templates`
+});
+
+// Compute the inbox snippet from the entry's `preview(props)`
+const snippet = getPreviewText({ key: "activation/welcome", props, registry });
+```
+
+`createRegistry(base, overrides)` shallow-merges a partial over a base registry —
+handy if you ever inherit a starter set and tweak a few keys:
+
+```ts
+export const templates = createRegistry(starterTemplates, {
+  "activation/welcome": { ...starterTemplates["activation/welcome"], category: "journey" },
+});
+```
+
+## How the consumer registry is built and threaded
+
+You build the registry once in `src/emails/registry.ts` and re-export it from
+`src/emails/index.ts`:
+
+```ts
+// src/emails/registry.ts
+import type { TemplateRegistry } from "@hogsend/email";
+import WelcomeEmail from "./welcome.js";
+import ActivationNudgeEmail from "./activation-nudge.js";
+
+export const templates: TemplateRegistry = {
+  "activation/welcome": {
+    component: WelcomeEmail,
+    defaultSubject: "Welcome aboard",
+    category: "transactional",
+    preview: (props) => `Welcome, ${props.name}!`,
+  },
+  "activation/nudge": {
+    component: ActivationNudgeEmail,
+    defaultSubject: "You haven't tried the key feature yet",
+    category: "journey",
+    preview: (props) => `${props.name}, you're missing out`,
+  },
+};
+```
+
+```ts
+// src/emails/index.ts
+export { templates } from "./registry.js";
+export type { ActivationNudgeEmailProps, WelcomeEmailProps } from "./types.js";
+```
+
+The wiring into the engine already exists in `src/index.ts` — you don't add it,
+but this is what it looks like:
+
+```ts
+// src/index.ts (already present in the scaffold)
+import { createHogsendClient } from "@hogsend/engine";
+import { templates } from "./emails/index.js";
+
+const client = createHogsendClient({ journeys, buckets, email: { templates } });
+```
+
+`createHogsendClient` stores your `templates` on the email-service config; the
+engine's `createTrackedMailer` reads `config.templates` and passes it to
+`getTemplate({ key, props, registry })` on every `send` and `render`. That is the
+whole reason the engine never bakes in business templates — yours flow in here.
+
+## Previewing a template
+
+For an at-a-glance HTML preview during development, render a component to a file:
+
+```ts
+// scripts/preview.ts (your repo, run with tsx)
+import { renderToHtml } from "@hogsend/email";
+import { writeFileSync } from "node:fs";
+import { templates } from "../src/emails/index.js";
+
+const { component } = templates["activation/welcome"];
+const html = await renderToHtml(component({ name: "Ada" }));
+writeFileSync("preview.html", html);
+```
+
+Or run react-email's own dev server if you keep one configured. To inspect real
+sends (open/click/bounce rates per template) against a running instance, use the
+**hogsend-cli** skill rather than rendering locally.

package/skills/hogsend-authoring-emails/references/template-four-file-contract.md

@@ -0,0 +1,134 @@
+# The template contract — five touch points that must agree
+
+A sendable, type-checked template is one string (`"activation/welcome"`) wired
+across five files. Get any of them out of sync and you get a compile error at
+the `send` call site — this is the single most common email-authoring bug. The
+checklist:
+
+| # | File | What it declares | Keyed on |
+|---|------|------------------|----------|
+| 1 | `src/emails/<name>.tsx` | the react-email component (default export) | imported by (3) |
+| 2 | `src/emails/types.ts` | the `Props` interface | imported by (1) + (4) |
+| 3 | `src/emails/registry.ts` | `templates[key]` → component + subject + category | **the key** |
+| 4 | `src/emails/templates.d.ts` | augments `TemplateRegistryMap` so `key → Props` | **the key** + Props |
+| 5 | `src/journeys/constants/index.ts` | `Templates.*` constant journeys send | **the key** |
+
+The **key** in (3), (4), and (5) must be byte-identical. The **Props** in (2)
+must match what (1) destructures and what (4) maps the key to.
+
+## Walk through, file by file
+
+### 1. The component — `src/emails/order-shipped.tsx`
+
+```tsx
+// biome-ignore lint/correctness/noUnusedImports: required for JSX runtime
+import React from "react";
+import { Layout } from "./_components/layout.js";
+import { Body, Button, Title } from "./_components/ui.js";
+import type { OrderShippedEmailProps } from "./types.js";
+
+export default function OrderShippedEmail({
+  name = "there",
+  trackingUrl = "https://example.com/track",
+  unsubscribeUrl,
+}: OrderShippedEmailProps) {
+  return (
+    <Layout
+      preview={`Your order is on its way, ${name}`}
+      eyebrow="Shipped"
+      unsubscribeUrl={unsubscribeUrl}
+    >
+      <Title>Your order is on its way</Title>
+      <Body>Hey {name}, we just handed it to the carrier.</Body>
+      <Button href={trackingUrl}>Track your package</Button>
+    </Layout>
+  );
+}
+```
+
+### 2. The props — `src/emails/types.ts`
+
+```ts
+export interface OrderShippedEmailProps {
+  name: string;
+  trackingUrl?: string;
+  // Engine-injected on send (see tracking-and-unsubscribe.md) — accept it so
+  // the Layout/Footer can render an unsubscribe link. Always optional.
+  unsubscribeUrl?: string;
+}
+```
+
+### 3. The registry entry — `src/emails/registry.ts`
+
+```ts
+import type { TemplateRegistry } from "@hogsend/email";
+import OrderShippedEmail from "./order-shipped.js";
+// ...other imports
+
+export const templates: TemplateRegistry = {
+  // ...other entries
+  "fulfilment/order-shipped": {
+    component: OrderShippedEmail,
+    defaultSubject: "Your order is on its way",
+    category: "transactional",
+    preview: (props) => `On its way, ${props.name}`,
+  },
+};
+```
+
+### 4. The augmentation — `src/emails/templates.d.ts`
+
+```ts
+import type { OrderShippedEmailProps } from "./types.js";
+
+declare module "@hogsend/email" {
+  interface TemplateRegistryMap {
+    // ...other keys
+    "fulfilment/order-shipped": OrderShippedEmailProps;
+  }
+}
+```
+
+`@hogsend/email` ships an **empty** `TemplateRegistryMap`. This `declare module`
+block is the only thing that teaches the type system your keys → props, which is
+what makes `emailService.send({ template, props })` type-check.
+
+### 5. The constant — `src/journeys/constants/index.ts`
+
+```ts
+export const Templates = {
+  // ...existing keys
+  ORDER_SHIPPED: "fulfilment/order-shipped",
+} as const;
+```
+
+Journeys send `template: Templates.ORDER_SHIPPED`, never a raw string, so a typo
+is a compile error rather than a silently-missing template at runtime.
+
+## The #1 type-error trap
+
+The send site resolves props from the registry map:
+
+```ts
+// engine signature (do not edit): send<K extends TemplateName>(
+//   options: { template: K; props: TemplateRegistryMap[K]; ... })
+await container.emailService.send({
+  template: "fulfilment/order-shipped",
+  props: { name: "Ada", trackingUrl: "https://…" }, // typed by templates.d.ts
+  to: user.email,
+});
+```
+
+If you added the registry entry (3) but forgot the augmentation (4), `TemplateName`
+won't include your key and `template:` rejects the string. If (2) and (4)
+disagree on Props, `props:` rejects the object. **When you see "is not assignable
+to TemplateName" or a props mismatch, re-check 2/3/4/5 against each other.**
+
+## Rename / delete checklist
+
+Renaming `"a/old"` → `"a/new"`: change the literal in (3), (4), and (5) together;
+no `.tsx`/`types.ts` change needed if the component/props are unchanged. Deleting
+a template: remove its entry from (3), its line from (4), its `Templates.*`
+constant from (5) if present, then delete the `.tsx` and its `Props` from (2).
+Leaving a key in (4) with no (3) entry, or vice-versa, will surface as a type or
+runtime error.

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

@@ -0,0 +1,127 @@
+# Tracking & unsubscribe — what happens automatically on every send
+
+This is co-located with email authoring on purpose: link-click tracking, open
+tracking, preference checks, and unsubscribe are **automatic on every send**.
+The engine's `createTrackedMailer` owns the whole pipeline; the email provider
+(`createResendProvider`) is just the dumb wire. You author the `.tsx`; the engine
+does the rest. You should NOT call any of these helpers yourself — this reference
+explains what runs so you author components that leave room for it.
+
+## The send pipeline (engine-owned, runs on `send` / `sendEmail`)
+
+```
+emailService.send({ template, props, to, ... })   // or sendEmail({...}) in a journey
+        │
+        ▼  createTrackedMailer.send → sendTrackedEmail (the DB-backed path)
+  1. preference / suppression check, then frequency cap
+        (both skipped when skipPreferenceCheck is set)
+  2. getTemplate(key, props, registry) → resolve element + subject + category
+  3. insert email_sends row  → gives the send a stable emailSendId (status "queued")
+  4. renderToHtml(element), then prepareTrackedHtml(html, emailSendId, baseUrl, db):
+        • rewriteLinks()    — every <a href="https?://…"> → /v1/t/c/:linkId
+        • injectOpenPixel() — <img src="/v1/t/o/:emailSendId"> before </body>
+        (only when baseUrl + prepareTrackedHtml are present; else send the raw react element)
+  5. provider.send(...)     — Resend gets the already-rewritten HTML
+  6. update email_sends → resendId + status "sent" (or "failed" on throw)
+```
+
+Tracking comes along regardless of which provider you supply, because steps 2–4
+live in the engine, not the provider. The tracking domain is `options.baseUrl`
+(threaded from `config.baseUrl`, i.e. `API_PUBLIC_URL`).
+
+## Link-click tracking
+
+`rewriteLinks` (engine `lib/tracking.ts`) scans the rendered HTML for
+`href="https://…"`, deduplicates the URLs, bulk-inserts one `tracked_links` row
+per unique URL, then single-pass replaces each href with
+`{API_PUBLIC_URL}/v1/t/c/{linkId}`. At click time:
+
+- `GET /v1/t/c/:id` records a `link_clicks` row (IP + user-agent), increments
+  `tracked_links.click_count`, sets `email_sends.clicked_at` (first click only,
+  `WHERE clicked_at IS NULL`), then **302-redirects to the original URL**.
+- After responding it fire-and-forgets an `email.link_clicked` event (props:
+  `emailSendId`, `templateKey`, `linkUrl`, `linkId`) into PostHog + the ingest
+  pipeline, so journeys can branch on it and `exitOn` can fire.
+
+Authoring implication: use real `<a href>` / react-email `Button`/`Link` with
+absolute `https://` URLs and they're tracked automatically. Non-HTTP links
+(`mailto:`, `tel:`) are left alone — the regex only matches `https?://`.
+
+## Open tracking
+
+`injectOpenPixel` appends a 1×1 GIF `<img src="{API_PUBLIC_URL}/v1/t/o/{emailSendId}">`
+just before `</body>` (so always compose inside `Layout`, which emits a proper
+`<body>`). At open time:
+
+- `GET /v1/t/o/:id` sets `email_sends.opened_at` (first open only), returns a
+  42-byte transparent GIF with `Cache-Control: no-store`.
+- Then fire-and-forgets an `email.opened` event (props: `emailSendId`,
+  `templateKey`).
+
+The engine's own constants for these are `EMAIL_OPENED = "email.opened"` and
+`EMAIL_LINK_CLICKED = "email.link_clicked"`. In journey code, reference them via
+your `Events` constants and check `ctx.history.hasEvent({ event })` to branch on
+engagement — see the **hogsend-authoring-journeys** skill.
+
+## Preference / suppression check
+
+Before sending, `sendTrackedEmail` checks `email_preferences` for the recipient.
+If the user is unsubscribed/suppressed/category-unsubscribed, the send is skipped
+and the result `status` reflects it (`"unsubscribed"` / `"suppressed"` /
+`"skipped"`) — no provider call. Genuinely transactional mail that must always go
+out can pass `skipPreferenceCheck: true`. Frequency caps also short-circuit here
+(`status: "skipped", reason: "frequency_capped"`); `category: "transactional"` is
+exempt from caps by default.
+
+## Unsubscribe — token, URL, and the footer slot
+
+The unsubscribe link is a signed, expiring token, not a DB lookup. The engine's
+`sendEmail` builds it for journey sends:
+
+```ts
+import { generateUnsubscribeUrl } from "@hogsend/email";
+// engine builds this for you when API_PUBLIC_URL + BETTER_AUTH_SECRET are set:
+const unsubscribeUrl = generateUnsubscribeUrl({
+  baseUrl: process.env.API_PUBLIC_URL,
+  secret: process.env.BETTER_AUTH_SECRET,
+  externalId: userId,
+  email: to,
+});
+// → {baseUrl}/v1/email/unsubscribe?token=<base64url payload>.<hmac-sha256 sig>
+```
+
+It is injected into your template as the `unsubscribeUrl` prop AND set as the
+`List-Unsubscribe` + `List-Unsubscribe-Post` headers (one-click unsubscribe). All
+you do as the author is **accept `unsubscribeUrl?: string` in your props and pass
+it to `Layout`** (which forwards it to `Footer`) — that's the slot:
+
+```tsx
+export default function MyEmail({ name = "there", unsubscribeUrl }: MyEmailProps) {
+  return (
+    <Layout preview={`Hi ${name}`} unsubscribeUrl={unsubscribeUrl}>
+      {/* … */}
+    </Layout>
+  );
+}
+```
+
+There is a matching `generatePreferenceCenterUrl(...)` →
+`{baseUrl}/v1/email/preferences?token=…` (action `"manage"`) for a full
+preference center link; pass it as `preferencesUrl` to `Layout` the same way.
+
+## Why these links aren't click-tracked
+
+`rewriteLinks` skips any URL containing `/v1/email/unsubscribe` or
+`/v1/email/preferences` (the `SKIP_PATTERNS`), so unsubscribe and preference
+links go straight through un-rewritten — an unsubscribe must never bounce through
+the click endpoint. You don't need to do anything for this; it's handled.
+
+## What you do NOT do
+
+- Don't call `prepareTrackedHtml`, `rewriteLinks`, or `injectOpenPixel` — the
+  mailer calls them.
+- Don't call `generateUnsubscribeUrl` in a template — the engine injects the URL.
+- Don't hand-roll an open pixel or rewrite links in your `.tsx`.
+
+Author the component; the engine guarantees tracking + unsubscribe on send.
+Full system docs: `docs/tracking.md`.

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

@@ -0,0 +1,88 @@
+---
+name: hogsend-authoring-journeys
+description: Use when adding or editing a lifecycle journey in src/journeys/ — wiring a defineJourney() trigger/entryLimit/exitOn/suppress, writing the run(user, ctx) control flow, durable sleeps, branching on history/engagement, sending email from a journey, and the register-in-index + thread-into-client/worker ritual.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Authoring Hogsend journeys
+
+A journey is a code-first lifecycle flow. You declare a `defineJourney({ meta,
+run })` in `src/journeys/`: `meta` says who enters and when they exit, and
+`run(user, ctx)` is plain TypeScript control flow — send email, durably sleep,
+branch on history. Each journey compiles to its own Hatchet durable task, so the
+worker can restart mid-flow and resume exactly where it left off.
+
+You are editing a **scaffolded consumer app** (content only). You import from
+`@hogsend/engine` and `@hogsend/core`; you never touch engine internals.
+
+## Anatomy of a journey
+
+```ts
+import { days, hours } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "./constants/index.js";
+
+export const welcome = defineJourney({
+  meta: {
+    id: "welcome",                               // stable, unique id
+    name: "Welcome Series",
+    enabled: true,
+    trigger: { event: Events.USER_CREATED },     // event that enrolls a user
+    entryLimit: "once",                          // re-entry policy (+ entryPeriod)
+    suppress: hours(12),                         // required declared cool-down field
+    exitOn: [{ event: Events.USER_DELETED }],    // events that pull users out
+  },
+  run: async (user, ctx) => {
+    await sendEmail({                            // STANDALONE import, not ctx.*
+      to: user.email,
+      userId: user.id,
+      journeyStateId: user.stateId,
+      template: Templates.ACTIVATION_WELCOME,
+      subject: "Welcome — let's get you set up",
+      journeyName: user.journeyName,
+    });
+    await ctx.sleep({ duration: days(2), label: "post-welcome" });
+    const { found } = await ctx.history.hasEvent({
+      userId: user.id,
+      event: Events.FEATURE_USED,
+    });
+    if (!found) {
+      await sendEmail({ /* nudge */ });
+    }
+  },
+});
+```
+
+## Key concepts
+
+- **`ctx` is orchestration primitives ONLY** — `sleep`, `sleepUntil`, `when`,
+  `checkpoint`, `trigger`, `identify`, `guard.isSubscribed`,
+  `history.hasEvent/journey/email`, `posthog.capture`. Features are standalone
+  imports: `sendEmail()` and `getPostHog()` come from `@hogsend/engine`, NOT off
+  `ctx`.
+- **Duration helpers** `days()` / `hours()` / `minutes()` from `@hogsend/core`
+  (also re-exported by `@hogsend/engine`) — never magic strings.
+- **`user`** carries `id`, `email`, `properties`, `stateId`, `journeyId`,
+  `journeyName` — pass `user.stateId` to `sendEmail` so the send is attributed.
+- **Constants** `Events` / `Templates` live in your `src/journeys/constants/`.
+  `Templates` keys must match a key in `src/emails/` registry.
+
+## Task playbooks — load the matching reference
+
+- **Shape `meta` (trigger, entryLimit, exitOn, suppress) + understand the
+  enrollment gates and state transitions** → `references/journey-meta.md`
+- **The full `ctx` primitive API and what is deliberately NOT on it** →
+  `references/journey-context.md`
+- **Send an email from inside `run`** → `references/sending-email-from-a-journey.md`
+- **Branch after a sleep on engagement / history, idempotently** →
+  `references/branch-on-engagement.md`
+- **Register a new journey: export + thread into client/worker + ENABLED_JOURNEYS**
+  → `references/register-a-journey.md`
+
+For `trigger.where` / `exitOn[].where` property conditions and the duration
+helpers in depth, see the **hogsend-conditions** skill. To verify a journey runs
+against a live instance (enroll a test user, watch it complete), see the
+**hogsend-cli** skill.

package/skills/hogsend-authoring-journeys/references/branch-on-engagement.md

@@ -0,0 +1,93 @@
+# Branching on engagement / history after a sleep
+
+The classic lifecycle shape: send something, durably wait, then branch on what
+the user did (or didn't do) in the meantime. The branch primitives live on
+`ctx.history.*` and `ctx.guard.isSubscribed()`; the wait is `ctx.sleep`.
+
+## The pattern
+
+```ts
+import { days } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "./constants/index.js";
+
+export const activation = defineJourney({
+  meta: { /* ... */ },
+  run: async (user, ctx) => {
+    await sendEmail({
+      to: user.email,
+      userId: user.id,
+      journeyStateId: user.stateId,
+      template: Templates.ACTIVATION_WELCOME,
+      subject: "Welcome — let's get you set up",
+      journeyName: user.journeyName,
+    });
+
+    // Durable wait. The worker can restart here and resume.
+    await ctx.sleep({ duration: days(2), label: "post-welcome" });
+
+    // Branch on behaviour that happened DURING the sleep.
+    const { found: activated } = await ctx.history.hasEvent({
+      userId: user.id,
+      event: Events.FEATURE_USED,
+    });
+    if (activated) return; // happy path — nothing more to do
+
+    // Re-check subscription after the long wait before sending again.
+    if (!(await ctx.guard.isSubscribed())) return;
+
+    await sendEmail({
+      to: user.email,
+      userId: user.id,
+      journeyStateId: user.stateId,
+      template: Templates.ACTIVATION_NUDGE,
+      subject: "You haven't tried the key feature yet",
+      journeyName: user.journeyName,
+    });
+  },
+});
+```
+
+## The branch sources
+
+- **`ctx.history.hasEvent({ userId, event, within? })`** → `{ found, count }`.
+  Did the user fire an event? Add `within: days(7)` to scope to a window. This is
+  the workhorse for "did they activate / convert / open the app".
+- **`ctx.history.email({ email, template })`** → `{ sent, lastSentAt, count }`.
+  Did this email already go out? Use it to avoid re-sending the same template on
+  a re-run.
+- **`ctx.history.journey({ userId, journeyId })`** →
+  `{ completed, lastCompletedAt, entryCount }`. Has the user been through another
+  journey? Branch on cross-journey state.
+- **`ctx.guard.isSubscribed()`** → `boolean`. ALWAYS re-check before sending
+  after a long `ctx.sleep` — a user can unsubscribe during the wait. Enrollment
+  only checks preferences at entry, not at each send.
+
+## Idempotency — journeys can replay
+
+A journey task is durable, and a step before a `ctx.sleep` can be re-executed if
+the worker restarts mid-flow. `sendEmail` is NOT deduped, so guard repeatable
+sends:
+
+```ts
+const { sent } = await ctx.history.email({
+  email: user.email,
+  template: Templates.ACTIVATION_NUDGE,
+});
+if (!sent) {
+  await sendEmail({ /* ... template: Templates.ACTIVATION_NUDGE ... */ });
+}
+```
+
+Guidelines:
+
+- Make each send conditional on `ctx.history.email(...)` when a step can run more
+  than once.
+- Use `ctx.checkpoint("label")` before/after meaningful steps so a restart is
+  observable on the `journeyStates` row.
+- Keep side effects (the actual `sendEmail`, `ctx.trigger`) AFTER the history
+  checks so the check reflects reality at that moment.
+
+For the time-window / `within` duration helpers and richer condition shapes
+(`property`, `event`, `email_engagement`, `composite`), see the
+**hogsend-conditions** skill.

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

@@ -0,0 +1,110 @@
+# JourneyContext (`ctx`) — the full primitive API
+
+`ctx` is the SECOND argument to `run(user, ctx)`. It exposes **durable
+orchestration primitives only** — the things that need Hatchet's durable
+execution or the journey's bound state (sleep, checkpoints, triggering events,
+reading history). It is deliberately small.
+
+It is the `JourneyContext` type from `@hogsend/core`. Everything below is a real
+method.
+
+## Durable timing
+
+```ts
+// Durable Hatchet sleep. Sets state → "waiting" for the duration, then "active".
+// The worker can restart mid-sleep and resume — this is the core durability win.
+const { sleptAt, resumedAt } = await ctx.sleep({
+  duration: days(2),          // DurationObject from days()/hours()/minutes()
+  label: "post-welcome",      // optional — also written as currentNodeId
+});
+
+// Durable sleep until an absolute instant (Date or ISO string).
+await ctx.sleepUntil(someDate, { label: "wait-for-renewal" });
+
+// Timezone-bound fluent scheduler — always resolves to an absolute Date you
+// then pass to sleepUntil. Bound to the user's resolved timezone.
+const at = ctx.when.tomorrow().at("09:00");        // 9am local, tomorrow
+await ctx.sleepUntil(at, { label: "morning-nudge" });
+// other ctx.when builders: .next("mon").at("HH:mm"), .nextLocal("HH:mm"),
+// .in(days(3)).at("HH:mm"), and chainers .tz(zone) / .window(start,end) / .ifPast("next"|"now")
+```
+
+## Observability
+
+```ts
+// Update currentNodeId on the journeyStates row — a breadcrumb for dashboards.
+await ctx.checkpoint("awaiting-activation");
+```
+
+## Firing events (cross-journey orchestration)
+
+```ts
+// Push an event through the FULL ingest pipeline (stores it, routes to matching
+// journey tasks via Hatchet, processes exitOn). Lets one journey trigger another.
+await ctx.trigger({
+  event: Events.JOURNEY_PRO_PATH,
+  userId: user.id,            // defaults userEmail to the current user's email
+  userEmail: user.email,      // optional override
+  properties: { step: "pro_branch" },
+});
+```
+
+## PostHog (no-op without POSTHOG_API_KEY)
+
+```ts
+// Set person properties on PostHog for the current user.
+ctx.identify({ plan: "pro", onboarded: true });   // synchronous, void
+
+// Fire a custom PostHog event for the current user.
+ctx.posthog.capture({ event: "journey_step_reached", properties: { step: 2 } });
+```
+
+## Guards
+
+```ts
+// Re-check subscription AFTER a long sleep, before sending again.
+if (await ctx.guard.isSubscribed()) {
+  await sendEmail({ /* ... */ });
+}
+```
+
+## History reads (branch on what already happened)
+
+```ts
+// Did this user fire an event (optionally within a window)?
+const { found, count } = await ctx.history.hasEvent({
+  userId: user.id,
+  event: Events.FEATURE_USED,
+  within: days(7),            // optional DurationObject
+});
+
+// Has this user completed another journey before? How many times entered?
+const { completed, lastCompletedAt, entryCount } = await ctx.history.journey({
+  userId: user.id,
+  journeyId: "onboarding",
+});
+
+// Has this email already received a given template?
+const { sent, lastSentAt, count } = await ctx.history.email({
+  email: user.email,
+  template: Templates.ACTIVATION_WELCOME,
+});
+```
+
+## What is NOT on `ctx`
+
+These are **standalone imports**, not methods — keeping `ctx` to pure
+orchestration:
+
+- **`sendEmail()`** — `import { sendEmail } from "@hogsend/engine"`. See
+  `references/sending-email-from-a-journey.md`.
+- **`getPostHog()`** — `import { getPostHog } from "@hogsend/engine"` for the raw
+  PostHog service (`ctx.identify` / `ctx.posthog.capture` cover the common cases).
+- **SMS / push / Slack** — plain functions you import, never on `ctx`.
+- There is **no `ctx.db`, no `ctx.sendEmail`, no `ctx.hatchet`** surfaced to
+  consumer journeys. If you reach for one of those, you are modelling it wrong —
+  use a primitive above or a standalone import.
+
+The `user` argument (first param) carries identity + attribution: `user.id`,
+`user.email`, `user.properties`, `user.stateId` (pass to `sendEmail`),
+`user.journeyId`, `user.journeyName`.