@hogsend/cli 0.1.0 → 0.2.1

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

@@ -0,0 +1,117 @@
+# 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.
+
+## Reactive alternative: `ctx.waitForEvent`
+
+The pattern above sleeps a **fixed window** then polls history — good when you
+want to wait a set time regardless. When you're waiting **for a specific event to
+happen** (and want to react the moment it does, or give up after a deadline),
+`ctx.waitForEvent` is the sharper tool: it resumes the instant the user fires the
+event, or returns `timedOut: true` when the timeout wins.
+
+```ts
+const { timedOut } = await ctx.waitForEvent({
+  event: Events.FEATURE_USED,
+  timeout: days(7),                 // required; capped at the 720h task limit
+  label: "await-activation",
+});
+if (!timedOut) return;              // they activated on their own — done
+if (!(await ctx.guard.isSubscribed())) return;
+await sendEmail({ /* nudge */ });
+```
+
+Rule of thumb: **fixed delay → `ctx.sleep` then `ctx.history.hasEvent`**;
+**wait until they do X (or time out) → `ctx.waitForEvent`**. The wait is
+forward-looking (only events after it begins count), and an `exitOn` match
+cancels it mid-wait, so no post-wait send fires after the journey exits.
+
+## 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,133 @@
+# 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")
+```
+
+## Durable wait-for-event
+
+```ts
+// Park the journey until THIS user emits `event`, OR `timeout` elapses —
+// whichever first. The reactive alternative to "sleep a fixed window, then poll
+// ctx.history": it resumes the INSTANT the event lands. Forward-looking — only
+// events fired AFTER the wait begins count (use ctx.history.hasEvent for the past).
+const { timedOut } = await ctx.waitForEvent({
+  event: Events.FEATURE_USED,
+  timeout: days(7),           // REQUIRED, capped at the 720h task execution limit
+  label: "await-activation",  // optional — written as currentNodeId
+});
+if (timedOut) {
+  // they never did it — nudge (re-check ctx.guard.isSubscribed() first after a long wait)
+} else {
+  // event arrived — they activated on their own
+}
+```
+
+If the journey `exitOn`-matches (or is cancelled) WHILE waiting, the run aborts
+cleanly — state goes `"exited"`, the durable run is cancelled, and no post-wait
+step (or email) fires. You don't catch anything; the engine handles it.
+
+## 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`.

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

@@ -0,0 +1,145 @@
+# JourneyMeta — trigger, entryLimit, exitOn, suppress
+
+`meta` is the static declaration of who enters a journey, how often, and what
+pulls them out. It is the `JourneyMeta` type from `@hogsend/core`:
+
+```ts
+interface JourneyMeta {
+  id: string;                 // stable unique id — used for state + ENABLED_JOURNEYS
+  name: string;               // human label (becomes user.journeyName)
+  description?: string;
+  enabled: boolean;           // master on/off for this journey
+
+  trigger: {
+    event: string;            // the event name that enrolls a user
+    where?: PropertyCondition[]; // optional gate on event properties
+  };
+
+  entryLimit: "once" | "once_per_period" | "unlimited";
+  entryPeriod?: DurationObject; // required-in-practice for once_per_period
+
+  exitOn?: Array<{
+    event: string;
+    where?: PropertyCondition[];
+  }>;
+
+  suppress: DurationObject;   // declared cool-down (required field; see note)
+}
+```
+
+## Fields in detail
+
+### `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/`:
+
+```ts
+trigger: { event: Events.USER_CREATED },
+```
+
+### `trigger.where` (optional)
+
+A `PropertyCondition[]` evaluated against the **enrolling event's properties**.
+If present and not met, the event is skipped with reason
+`trigger_conditions_not_met`. Use it to enroll only a slice of an event:
+
+```ts
+trigger: {
+  event: Events.USER_CREATED,
+  where: [{ property: "plan", operator: "equals", value: "pro" }],
+},
+```
+
+For the full operator set and how `PropertyCondition` is shaped, see the
+**hogsend-conditions** skill.
+
+### `entryLimit` + `entryPeriod`
+
+Controls re-entry:
+
+- `"once"` — a user can ever enter this journey exactly one time. A second
+  matching event is skipped (`already_entered_once`). Checked against ALL prior
+  states for the user+journey, regardless of completion.
+- `"once_per_period"` — re-entry allowed only after `entryPeriod` has elapsed
+  since the user's most recent enrollment. Defaults to `hours(24)` if
+  `entryPeriod` is omitted, so set it explicitly:
+  ```ts
+  entryLimit: "once_per_period",
+  entryPeriod: days(7),
+  ```
+- `"unlimited"` — every matching event enrolls (subject to the active-state
+  guard below). Good for test/smoke journeys.
+
+### `exitOn` (optional)
+
+Events that pull a user OUT of any in-flight run of this journey. Evaluated by
+the ingestion pipeline whenever a new event arrives for a user with an active
+journey state — if the incoming event name matches an `exitOn` rule (and its
+optional `where` passes), the active run is exited:
+
+```ts
+exitOn: [
+  { event: Events.USER_DELETED },
+  { event: "subscription.cancelled", where: [{ property: "reason", operator: "equals", value: "churn" }] },
+],
+```
+
+### `suppress`
+
+A **required** `DurationObject` field declaring an intended cool-down before
+re-entry. Note: the engine's enrollment gates do NOT currently read `suppress` —
+actual re-entry timing is enforced by `entryLimit` + `entryPeriod` (above). It is
+stored as journey metadata and surfaced on the admin journeys API. Treat it as
+the declarative cool-down you pair with `entryLimit` (e.g.
+`entryLimit: "once_per_period"`, `entryPeriod: days(7)`, `suppress: hours(12)`);
+use `hours(0)` on `"unlimited"` test journeys. Because it is required, always set
+it — `hours(0)` when you mean "none".
+
+### `enabled`
+
+Master switch. `enabled: false` makes every enrollment skip with reason
+`journey_disabled`. (Admins can ALSO disable a journey at runtime via a
+`journeyConfigs` override — that yields `journey_disabled_by_admin`. Toggle that
+at runtime with the **hogsend-cli** skill's `journeys enable/disable`.)
+
+## The 4-gate enrollment order
+
+When the trigger event arrives, the journey task runs these gates IN ORDER
+before `run()` executes. Any failing gate returns `{ status: "skipped", reason }`
+and creates NO state:
+
+1. **`meta.enabled`** (and the admin `journeyConfigs` override) →
+   `journey_disabled` / `journey_disabled_by_admin`.
+2. **`trigger.where`** against the event properties → `trigger_conditions_not_met`.
+3. **`entryLimit`** (`checkEntryLimit`) → `already_entered_once` /
+   `period_not_elapsed`.
+4. **Email preferences** (`checkEmailPreferences`) — if the user is unsubscribed
+   from all → `user_unsubscribed`.
+
+After the gates, an **active-state guard** prevents concurrent enrollment: if a
+state in status `active` or `waiting` already exists for this user+journey, the
+event is skipped (`already_active`). This is why a single user never has two
+overlapping runs of the same journey.
+
+## State transitions
+
+A `journeyStates` row tracks each run. Once the gates pass:
+
+- **enter** → row created with `status: "active"`, `currentNodeId: "start"`.
+- **`ctx.sleep` / `ctx.sleepUntil` / `ctx.waitForEvent`** → `status: "waiting"`
+  while suspended, back to `"active"` on resume.
+- **`run()` returns** → `status: "completed"`, `completedAt` set, and a
+  `journey:completed` event is pushed.
+- **`run()` throws** → `status: "failed"`, `errorMessage` recorded, and a
+  `journey:failed` event is pushed; the error re-throws so Hatchet sees the
+  failure.
+- **`exitOn` matches (or cancelled)** → `status: "exited"`. If it happens while
+  the journey is suspended in a `ctx.sleep`/`ctx.waitForEvent`, the durable run
+  is cancelled so no further step runs — even mid-wait.
+
+Because the gates run before any state is created, a skipped event is invisible
+in `journeyStates` — to debug "why didn't this user enroll?", check the gate
+order above and inspect events with the **hogsend-cli** skill.

package/skills/hogsend-authoring-journeys/references/register-a-journey.md

@@ -0,0 +1,99 @@
+# Registering a journey
+
+Defining a journey is not enough — it has to be in the `journeys` array that the
+client and worker receive. Both processes (HTTP API + Hatchet worker) must see
+the same array: the API needs it to route ingested events, the worker needs it to
+register the durable task that actually runs `run()`.
+
+## 1. Export from `src/journeys/index.ts`
+
+Add your journey to the `journeys` array (and re-export it for tests / direct
+reference):
+
+```ts
+import type { DefinedJourney } from "@hogsend/engine";
+import { activation } from "./activation.js";
+import { testOnboarding } from "./test-onboarding.js";
+import { welcome } from "./welcome.js";
+
+export const journeys: DefinedJourney[] = [
+  welcome,
+  testOnboarding,
+  activation,            // <-- your new journey
+];
+
+export { activation, testOnboarding, welcome };
+```
+
+The exported `journeys` array is the single source of truth that both entry
+points consume.
+
+## 2. It is already threaded into the client + worker
+
+In a scaffolded app both entry points import that same array — you usually do
+NOT need to touch these files, just confirm they pass `journeys`:
+
+```ts
+// src/index.ts  (HTTP API)
+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 } });
+const app = createApp(client, { webhookSources });
+```
+
+```ts
+// src/worker.ts  (Hatchet worker — this is what runs run())
+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";
+
+const client = createHogsendClient({ journeys, buckets, email: { templates } });
+const worker = createWorker({ container: client, journeys, buckets, extraWorkflows });
+await worker.start();
+```
+
+If you build a new entry point or a test harness, the rule is: **pass the same
+`journeys` array to both `createHogsendClient({ journeys })` and
+`createWorker({ container, journeys })`.** A journey missing from the worker is
+defined but never executes; missing from the client and ingested events won't
+route to it. (`buckets` and `extraWorkflows` are the sibling content arrays the
+scaffold threads through the same way — pass them when present.)
+
+## 3. (Optional) `ENABLED_JOURNEYS`
+
+The `ENABLED_JOURNEYS` env var filters which registered journeys actually load —
+comma-separated ids, or `*` (or empty/unset) for all:
+
+```bash
+# only these two run; everything else is registered but inert
+ENABLED_JOURNEYS=welcome,activation
+
+# all journeys (default)
+ENABLED_JOURNEYS=*
+```
+
+The filter matches on `meta.id`, so keep ids stable. It is applied identically
+when building the registry (client) and when selecting durable tasks (worker), so
+a journey is either fully on or fully off across both processes. Use it to ship a
+journey's code but keep it dark until you flip the env var — distinct from
+`meta.enabled: false` (code-level off) and the runtime admin toggle (see the
+**hogsend-cli** skill's `journeys enable/disable`).
+
+## Checklist for a new journey
+
+1. New file in `src/journeys/` using `defineJourney({ meta, run })`.
+2. Any new event / template keys added to `src/journeys/constants/`.
+3. New email? component + registry entry under `src/emails/` for each
+   `Templates.*` key you send.
+4. Journey added to the `journeys` array in `src/journeys/index.ts`.
+5. Confirm `src/index.ts` and `src/worker.ts` both receive that array.
+6. If gating by env, add the id to `ENABLED_JOURNEYS`.
+
+To smoke-test it end-to-end against a running instance (enroll a user, watch the
+state reach `completed`), use the **hogsend-cli** skill.

package/skills/hogsend-authoring-journeys/references/sending-email-from-a-journey.md

@@ -0,0 +1,82 @@
+# Sending email from a journey
+
+`sendEmail()` is a **standalone import from `@hogsend/engine`** — it is NOT a
+method on `ctx`. It renders the template, checks the user's email preferences,
+rewrites links + injects the open pixel (tracking), writes the `email_sends` row,
+and hands off to the provider. You just call it with a template key and props.
+
+```ts
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "./constants/index.js";
+
+export const welcome = defineJourney({
+  meta: { /* ... */ },
+  run: async (user, ctx) => {
+    await sendEmail({
+      to: user.email,                         // recipient
+      userId: user.id,                        // external id (for prefs + tracking)
+      journeyStateId: user.stateId,           // attributes the send to THIS run
+      template: Templates.ACTIVATION_WELCOME, // a key from your emails registry
+      subject: "Welcome — let's get you set up",
+      journeyName: user.journeyName,          // shows on the send record / tags
+      props: { firstName: user.properties.firstName }, // template props (optional)
+    });
+  },
+});
+```
+
+## The options (`SendEmailOptions`)
+
+```ts
+interface SendEmailOptions {
+  to: string;                          // required — recipient email
+  userId: string;                      // required — external user id
+  template: string;                    // required — registry key (use Templates.*)
+  subject: string;                     // required
+  journeyName?: string;                // attribution label (defaults to template)
+  journeyStateId?: string;             // pass user.stateId to tie to this run
+  props?: Record<string, unknown>;     // props handed to the template component
+}
+```
+
+`name` is auto-derived if you don't pass it: `props.firstName` → `props.name` →
+the local-part of the email → `"there"`. So a template that renders `{name}`
+always has something. Pass `firstName` in `props` for a real name.
+
+## The result (`SendEmailResult`)
+
+```ts
+interface SendEmailResult {
+  emailSendId: string;   // id of the email_sends row — keep it if you need to correlate
+  sentAt: string;        // ISO timestamp
+}
+
+const { emailSendId, sentAt } = await sendEmail({ /* ... */ });
+```
+
+## Template keys must exist in your registry
+
+`template` is a `Templates.*` constant from your `src/journeys/constants/`. Each
+key must resolve to a real template in `src/emails/` — the constant value (e.g.
+`"activation/welcome"`) is the registry key. If you send a new email, first add:
+
+1. the template component + registry entry under `src/emails/`,
+2. the matching `Templates` key in `src/journeys/constants/`,
+
+then reference it here as `Templates.YOUR_KEY`. A mismatched key fails at render
+time, not compile time, so keep them in lockstep.
+
+## Preferences, tracking, and idempotency
+
+- `sendEmail` checks the user's email preferences internally; an unsubscribed
+  user is not emailed. You do not need to gate it — though after a long
+  `ctx.sleep` it is good practice to branch on `ctx.guard.isSubscribed()` first
+  (see `references/branch-on-engagement.md`).
+- Link-click + open tracking is applied automatically by the engine mailer —
+  you get it regardless of which provider is configured.
+- `sendEmail` is **not** itself deduped — calling it twice sends twice. Guard
+  repeat sends with `ctx.history.email({ email, template })` when a journey can
+  re-run a step.
+
+For SMS / push / Slack, import the relevant standalone sender — those are also
+plain function imports, never on `ctx`.

package/skills/hogsend-cli/SKILL.md

@@ -58,6 +58,7 @@ other data command requires one.
 | `hogsend contacts list/get/timeline` | Inspect contacts + their activity. |
 | `hogsend events <userId>` | Raw event stream for one user. |
 | `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). |

package/skills/hogsend-conditions/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: hogsend-conditions
+description: Use when writing any condition or duration in a Hogsend app — a journey trigger.where, an exitOn rule, or a bucket criteria tree. Covers the four condition types (property, event with a time window + count, email_engagement by template, composite and/or) and DurationObjects via days()/hours()/minutes() instead of magic duration strings.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Hogsend conditions & durations
+
+Hogsend has ONE condition engine, shared everywhere you express "does this
+user match?" — a journey's `trigger.where`, an `exitOn` rule, and a bucket's
+`criteria` tree all speak the same vocabulary. This skill is the single source
+of truth for that vocabulary and for the `DurationObject` helpers (`days()`,
+`hours()`, `minutes()`) that replace magic duration strings. The journeys and
+buckets skills link here for the condition/duration details.
+
+Everything is plain data: a condition is a discriminated-union POJO
+(`ConditionEval`), a duration is `{ hours?, minutes?, seconds? }`. You author
+them as data or via the fluent `criteriaBuilder` (buckets only) — both produce
+byte-identical POJOs. You import these from `@hogsend/core` (re-exported by
+`@hogsend/engine`); you never edit the engine.
+
+## The four condition types (`ConditionEval`)
+
+| `type` | Matches on | Key fields |
+|--------|-----------|------------|
+| `"property"` | a person/event property value | `property`, `operator`, `value?` |
+| `"event"` | event occurrences, optionally in a rolling window, optionally counted | `eventName`, `check`, `operator?`, `value?`, `within?` |
+| `"email_engagement"` | open/click state of the last send of a template | `templateKey`, `check` |
+| `"composite"` | AND / OR over child conditions | `operator` (`"and"`/`"or"`), `conditions[]` |
+
+## Where each surface accepts what (IMPORTANT)
+
+Not every surface accepts all four types — match the type to the field:
+
+- **`trigger.where`** (journey) → `PropertyCondition[]` ONLY. Property
+  conditions, AND-ed together, evaluated against the triggering event's
+  properties. No event/engagement/composite legs here.
+- **`exitOn[].where`** (journey) → `PropertyCondition[]` ONLY. Same shape;
+  AND-ed against the incoming event's properties. Omit `where` to exit on the
+  event name alone.
+- **`criteria`** (bucket) → a single `ConditionEval` tree — ALL FOUR types,
+  composed with `composite` / `b.all()` / `b.any()`. This is the only surface
+  that runs against the database (event counts, engagement, windows).
+
+## Task playbooks — load the matching reference
+
+- **Exact shapes, every operator, the `within` window + count, and how
+  `evaluateCondition` reads them** → load `references/condition-types.md`
+- **`days()` / `hours()` / `minutes()` `DurationObject`s and where durations
+  are valid (sleep, `within`, `entryPeriod`, dwell)** → load
+  `references/durations.md`
+- **Copy-paste `trigger.where`, `exitOn`, and bucket `criteria` built from the
+  real builder + types** → load `references/examples.md`
+
+## Golden rules
+
+1. `trigger.where` and `exitOn[].where` take `PropertyCondition[]` only — if
+   you need an event count or a time window, that logic belongs in the
+   journey's `run` body (`ctx.history.hasEvent`) or in a bucket's `criteria`,
+   not in `where`.
+2. Use the duration helpers — never hand-write `{ hours: 168 }`; write
+   `days(7)`.
+3. A dynamic bucket's `criteria` MUST contain at least one positive condition;
+   a pure-negation tree is rejected at registration.
+4. To author/run a journey or bucket end to end, see the
+   hogsend-authoring-journeys and hogsend-authoring-buckets skills; to verify a
+   running instance, see the hogsend-cli skill.