@hogsend/cli 0.1.0 → 0.2.1

package/skills/hogsend-conditions/references/condition-types.md

@@ -0,0 +1,251 @@
+# Condition types — exact shapes & operators
+
+The condition system is the `ConditionEval` discriminated union from
+`@hogsend/core` (re-exported by `@hogsend/engine`). Every condition is a plain
+POJO discriminated by `type`. This is the canonical reference for the shapes,
+operators, and how the engine evaluates each.
+
+```ts
+import type {
+  ConditionEval,
+  PropertyCondition,
+  EventCondition,
+  EmailEngagementCondition,
+  CompositeCondition,
+} from "@hogsend/core/types";
+```
+
+```ts
+type ConditionEval =
+  | PropertyCondition
+  | EventCondition
+  | EmailEngagementCondition
+  | CompositeCondition;
+```
+
+---
+
+## 1. `property` — `PropertyCondition`
+
+Compares a single property value against an expected `value`.
+
+```ts
+interface PropertyCondition {
+  type: "property";
+  property: string;
+  operator:
+    | "eq"
+    | "neq"
+    | "gt"
+    | "gte"
+    | "lt"
+    | "lte"
+    | "exists"
+    | "not_exists"
+    | "contains";
+  value?: string | number | boolean;
+}
+```
+
+Operator semantics (from `conditions/property.ts`):
+
+| operator | meaning | value type | notes |
+|----------|---------|------------|-------|
+| `eq` | `actual === value` | string \| number \| boolean | strict equality |
+| `neq` | `actual !== value` | string \| number \| boolean | |
+| `gt` / `gte` / `lt` / `lte` | numeric comparison | number | both sides must be `number`, else `false` |
+| `exists` | value is not `undefined`/`null` | omit `value` | |
+| `not_exists` | value is `undefined`/`null` | omit `value` | |
+| `contains` | `actual.includes(value)` | string | both sides must be `string`, else `false` |
+
+```ts
+// Examples (declarative POJOs)
+{ type: "property", property: "plan", operator: "eq", value: "pro" }
+{ type: "property", property: "seats", operator: "gte", value: 5 }
+{ type: "property", property: "company", operator: "exists" }
+{ type: "property", property: "email", operator: "contains", value: "@acme.com" }
+```
+
+Used directly by `trigger.where` and `exitOn[].where` (both are
+`PropertyCondition[]`, AND-ed via `evaluatePropertyConditions` — see
+`references/examples.md`).
+
+---
+
+## 2. `event` — `EventCondition`
+
+Counts occurrences of `eventName`, optionally inside a rolling `within` window,
+and applies a `check`. This is the only type with a time window.
+
+```ts
+import type { DurationObject } from "@hogsend/core";
+
+interface EventCondition {
+  type: "event";
+  eventName: string;
+  check: "exists" | "not_exists" | "count";
+  operator?: "gt" | "gte" | "lt" | "lte" | "eq"; // only with check:"count"
+  value?: number;                                 // only with check:"count"
+  within?: DurationObject;                        // rolling window, e.g. days(7)
+}
+```
+
+How it evaluates (`conditions/event.ts`): it counts rows in `userEvents` for
+the user matching `eventName`, restricted to `occurredAt >= now - within` when
+`within` is set, then:
+
+| `check` | matches when |
+|---------|--------------|
+| `exists` | `count > 0` |
+| `not_exists` | `count === 0` |
+| `count` + `operator`/`value` | `count <op> value` (`gt`/`gte`/`lt`/`lte`/`eq`) |
+| `count` with no `operator`/`value` | falls back to `count > 0` |
+
+`within` makes the condition time-based: in a bucket, a windowed event leg is
+what the reconcile cron sweeps. See the hogsend-authoring-buckets skill for the
+reconcile implications.
+
+```ts
+// Declarative
+{ type: "event", eventName: "app.active", check: "exists" }
+{ type: "event", eventName: "app.active", check: "not_exists", within: days(7) }
+{ type: "event", eventName: "purchase", check: "count", operator: "gte", value: 3 }
+```
+
+---
+
+## 3. `email_engagement` — `EmailEngagementCondition`
+
+Checks the open/click state of the MOST RECENT send of a given template to the
+user.
+
+```ts
+interface EmailEngagementCondition {
+  type: "email_engagement";
+  templateKey: string;
+  check: "opened" | "clicked" | "not_opened" | "not_clicked";
+}
+```
+
+How it evaluates (`conditions/email-engagement.ts`): finds the latest
+`emailSends` row for the user + `templateKey`. If there is NO send, every check
+returns `false`. Otherwise:
+
+| `check` | matches when |
+|---------|--------------|
+| `opened` | `openedAt` is set |
+| `clicked` | `clickedAt` is set |
+| `not_opened` | `openedAt` is null |
+| `not_clicked` | `clickedAt` is null |
+
+`templateKey` is a key from your `src/emails/` template registry (the same
+values you use in `Templates`).
+
+```ts
+{ type: "email_engagement", templateKey: "welcome", check: "not_opened" }
+```
+
+---
+
+## 4. `composite` — `CompositeCondition`
+
+AND / OR over child `ConditionEval`s. Children can themselves be composites
+(nest freely).
+
+```ts
+interface CompositeCondition {
+  type: "composite";
+  operator: "and" | "or";
+  conditions: ConditionEval[];
+}
+```
+
+Short-circuit semantics (`conditions/composite.ts`): `and` returns `false` on
+the first child that fails; `or` returns `true` on the first child that passes.
+
+```ts
+{
+  type: "composite",
+  operator: "and",
+  conditions: [
+    { type: "property", property: "plan", operator: "eq", value: "trial" },
+    { type: "event", eventName: "app.active", check: "not_exists", within: days(7) },
+  ],
+}
+```
+
+---
+
+## The fluent builder (bucket `criteria` only)
+
+`defineBucket`'s `criteria` accepts either a `ConditionEval` POJO OR a function
+`(b) => ConditionEval`, where `b` is the `CriteriaBuilder`. The builder runs
+ONCE at definition time and returns the same POJO — it never executes per user.
+You can also import `criteriaBuilder` standalone to compose reusable fragments.
+
+```ts
+import { criteriaBuilder } from "@hogsend/core";
+```
+
+```ts
+interface CriteriaBuilder {
+  prop(property: string): PropertyMatcher;
+  event(eventName: string): EventMatcher;
+  all(...conditions: ConditionEval[]): CompositeCondition; // composite "and"
+  any(...conditions: ConditionEval[]): CompositeCondition; // composite "or"
+}
+```
+
+`PropertyMatcher` terminals → `PropertyCondition`:
+
+```ts
+b.prop("plan").eq("pro")          // operator "eq"
+b.prop("plan").neq("free")        // "neq"
+b.prop("seats").gt(5)             // "gt"
+b.prop("seats").gte(5)            // "gte"
+b.prop("seats").lt(10)            // "lt"
+b.prop("seats").lte(10)           // "lte"
+b.prop("email").contains("@acme") // "contains"
+b.prop("company").exists()        // "exists"
+b.prop("company").notExists()     // "not_exists"
+```
+
+`EventMatcher` — optional `.within(window)` precedes the terminal; terminals →
+`EventCondition`:
+
+```ts
+b.event("app.active").exists()                       // check "exists"
+b.event("app.active").within(days(7)).notExists()    // check "not_exists" + window
+b.event("purchase").count("gte", 3)                  // check "count", operator "gte"
+b.event("purchase").atLeast(3)                       // count gte 3
+b.event("purchase").moreThan(3)                      // count gt 3
+b.event("purchase").atMost(3)                        // count lte 3
+b.event("purchase").lessThan(3)                      // count lt 3
+b.event("purchase").exactly(3)                       // count eq 3
+```
+
+There is no builder terminal for `email_engagement` — author those as POJOs
+inside `b.all(...)` / `b.any(...)` when you need them.
+
+---
+
+## How conditions are evaluated
+
+`evaluateCondition({ condition, ctx })` (`conditions/evaluate.ts`) is the engine
+entry point; it dispatches on `condition.type`. The `ctx` is a
+`ConditionContext`:
+
+```ts
+interface ConditionContext {
+  db: Database;                          // event/engagement legs query this
+  userId: string;
+  journeyContext: Record<string, unknown>; // property legs read from here
+}
+```
+
+You normally do NOT call `evaluateCondition` yourself — the engine runs it for
+bucket `criteria`. For `trigger.where` / `exitOn[].where`, the engine uses
+`evaluatePropertyConditions({ conditions, properties })`, which AND-s a
+`PropertyCondition[]` against an event's properties (`.every(...)`). Knowing
+which evaluator runs tells you which condition types a surface accepts (see
+`references/examples.md`).

package/skills/hogsend-conditions/references/durations.md

@@ -0,0 +1,90 @@
+# Durations — `DurationObject` & the helpers
+
+Every "how long" in Hogsend is a `DurationObject`, never a magic string. You
+build them with `days()`, `hours()`, `minutes()` from `@hogsend/core`
+(re-exported by `@hogsend/engine`).
+
+```ts
+import { days, hours, minutes } from "@hogsend/core";
+// or, alongside engine factories:
+import { days, hours, minutes } from "@hogsend/engine";
+```
+
+## The shape
+
+```ts
+interface DurationObject {
+  readonly hours?: number;
+  readonly minutes?: number;
+  readonly seconds?: number;
+}
+```
+
+## The helpers (exact definitions)
+
+```ts
+days(n)    // => { hours: n * 24 }   — yes, days are expressed as hours
+hours(n)   // => { hours: n }
+minutes(n) // => { minutes: n }
+```
+
+So `days(7)` is `{ hours: 168 }`. There is no `days` field on `DurationObject`
+— `days()` normalizes to `hours`. Don't hand-write the object; the helpers keep
+intent readable and are what the codebase uses everywhere.
+
+`durationToMs(d)` is the conversion used internally
+(`hours*3_600_000 + minutes*60_000 + seconds*1_000`). You rarely call it
+directly; it backs `ctx.sleep` and the `within` window math.
+
+## Where durations are valid
+
+A `DurationObject` is accepted anywhere the engine measures elapsed/remaining
+time. The main spots a consumer touches:
+
+| Location | Field | What it means |
+|----------|-------|---------------|
+| Journey meta | `suppress` | global cool-off after this journey runs |
+| Journey meta | `entryPeriod` | window for `entryLimit: "once_per_period"` |
+| Journey `run` | `ctx.sleep({ duration })` | durable wait inside a journey |
+| Journey `run` | `ctx.history.hasEvent({ within })` | look-back window for an event check |
+| Condition | `EventCondition.within` | rolling window on an `event` condition |
+| Bucket meta | `entryPeriod` | window for the bucket's `entryLimit` |
+| Bucket meta | `minDwell` / `maxDwell` | membership debounce floor / unconditional TTL |
+| Bucket meta | `reconcileEvery` | advisory reconcile cadence (Studio display) |
+
+```ts
+// Journey meta
+meta: {
+  // ...
+  entryLimit: "once_per_period",
+  entryPeriod: days(3),
+  suppress: hours(4),
+}
+
+// Inside run()
+await ctx.sleep({ duration: hours(2), label: "initial-followup" });
+const { found } = await ctx.history.hasEvent({
+  userId: user.id,
+  event: Events.CHECKOUT_COMPLETED,
+  within: hours(26),
+});
+
+// On an event condition (bucket criteria)
+{ type: "event", eventName: "app.active", check: "not_exists", within: days(7) }
+```
+
+## Composing values
+
+The helpers each return a single-field object, so to express "90 minutes" use
+`minutes(90)`, not `hours(1)` plus `minutes(30)` — there's no add helper. Pick
+the largest single unit that reads cleanly:
+
+```ts
+minutes(90)   // 90 minutes
+hours(36)     // a day and a half
+days(14)      // two weeks
+```
+
+For the surfaces that consume these (journey orchestration, bucket dwell,
+condition windows), see the hogsend-authoring-journeys and
+hogsend-authoring-buckets skills.

package/skills/hogsend-conditions/references/examples.md

@@ -0,0 +1,188 @@
+# Copy-paste examples — `trigger.where`, `exitOn`, bucket `criteria`
+
+Real, type-checked patterns built from the actual types and builder. Drop these
+into `src/journeys/*.ts` and `src/buckets/*.ts`. Imports come from
+`@hogsend/engine` / `@hogsend/core`; you never edit the engine.
+
+---
+
+## `trigger.where` — gate enrollment on event properties
+
+`trigger.where` is a `PropertyCondition[]`. The conditions are AND-ed together
+(`evaluatePropertyConditions` → `.every(...)`) against the TRIGGERING event's
+properties. Only `property` conditions are valid here — there is no `within`,
+no event count, no composite. (Need a count or a window? Put that logic in the
+`run` body via `ctx.history.hasEvent`, or model it as a bucket.)
+
+```ts
+import { days, hours } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "./constants/index.js";
+
+export const proCheckoutAbandoned = defineJourney({
+  meta: {
+    id: "pro-checkout-abandoned",
+    name: "Pro plan — checkout abandoned",
+    enabled: true,
+    trigger: {
+      event: Events.CHECKOUT_ABANDONED,
+      // only fire for high-value abandons
+      where: [
+        { type: "property", property: "plan", operator: "eq", value: "pro" },
+        { type: "property", property: "cartValue", operator: "gte", value: 100 },
+      ],
+    },
+    entryLimit: "once_per_period",
+    entryPeriod: days(3),
+    suppress: hours(4),
+  },
+  run: async (user, ctx) => {
+    await ctx.sleep({ duration: hours(2), label: "nudge" });
+    await sendEmail({
+      to: user.email,
+      userId: user.id,
+      journeyStateId: user.stateId,
+      template: Templates.CONVERSION_WINBACK_OFFER,
+      subject: "Still thinking it over?",
+      journeyName: user.journeyName,
+    });
+  },
+});
+```
+
+---
+
+## `exitOn` — leave the journey when a later event arrives
+
+`exitOn` is an array of `{ event, where? }`. The engine matches the incoming
+event name; if `where` is present it must pass (`PropertyCondition[]`, AND-ed)
+for the exit to fire. Omit `where` to exit on the event name alone.
+
+```ts
+meta: {
+  // ...
+  exitOn: [
+    // exit on any completed checkout
+    { event: Events.CHECKOUT_COMPLETED },
+    // exit on a subscription, but only if it's the pro plan
+    {
+      event: Events.SUBSCRIPTION_CREATED,
+      where: [
+        { type: "property", property: "plan", operator: "eq", value: "pro" },
+      ],
+    },
+  ],
+}
+```
+
+---
+
+## Bucket `criteria` — the full condition engine
+
+`criteria` is a single `ConditionEval` tree and accepts ALL FOUR types. Author
+it with the fluent builder `(b) => ...` (preferred) or as a declarative POJO.
+Both forms produce identical data. A dynamic bucket MUST have at least one
+POSITIVE condition (a pure-negation tree is rejected at registration).
+
+### Builder form (recommended)
+
+```ts
+import { days, defineBucket } from "@hogsend/engine";
+import { Events } from "../journeys/constants/index.js";
+
+// Lapsed-active: was active once, but NOT in the last 7 days.
+export const wentDormant = defineBucket({
+  meta: {
+    id: "went-dormant",
+    name: "Went dormant",
+    enabled: true,
+    timeBased: true,
+    fastExpiry: true,
+    criteria: (b) =>
+      b.all(
+        b.event(Events.APP_ACTIVE).exists(),                 // positive anchor
+        b.event(Events.APP_ACTIVE).within(days(7)).notExists(), // windowed absence
+      ),
+  },
+});
+```
+
+### Mixing all four types
+
+```ts
+import { days, defineBucket } from "@hogsend/engine";
+
+export const atRiskPro = defineBucket({
+  meta: {
+    id: "at-risk-pro",
+    name: "At-risk pro accounts",
+    enabled: true,
+    timeBased: true,
+    criteria: (b) =>
+      b.all(
+        b.prop("plan").eq("pro"),                      // property
+        b.event("app.active").within(days(14)).lessThan(3), // event count + window
+        b.any(
+          b.event("support.ticket").within(days(30)).exists(),
+          // email_engagement has no builder terminal — drop the POJO in directly:
+          { type: "email_engagement", templateKey: "renewal-reminder", check: "not_opened" },
+        ),
+      ),
+  },
+});
+```
+
+### Declarative form (identical result)
+
+```ts
+export const wentDormantDeclarative = defineBucket({
+  meta: {
+    id: "went-dormant",
+    name: "Went dormant",
+    enabled: true,
+    timeBased: true,
+    criteria: {
+      type: "composite",
+      operator: "and",
+      conditions: [
+        { type: "event", eventName: "app.active", check: "exists" },
+        { type: "event", eventName: "app.active", check: "not_exists", within: days(7) },
+      ],
+    },
+  },
+});
+```
+
+---
+
+## Reusable fragments via `criteriaBuilder`
+
+Import the builder standalone to compose shared criteria pieces (handy in tests
+or to DRY up several buckets):
+
+```ts
+import { criteriaBuilder as b, type ConditionEval } from "@hogsend/core";
+
+const isPro: ConditionEval = b.prop("plan").eq("pro");
+const wentQuiet = (window: ReturnType<typeof days>): ConditionEval =>
+  b.event("app.active").within(window).notExists();
+
+// use inside a bucket
+criteria: (c) => c.all(isPro, wentQuiet(days(7))),
+```
+
+---
+
+## Quick decision guide
+
+- Gating who ENTERS a journey on event properties → `trigger.where`
+  (`PropertyCondition[]`).
+- Pulling someone OUT of a journey when a later event lands → `exitOn`
+  (`{ event, where? }`, `where` is `PropertyCondition[]`).
+- "Is the user in this segment right now?" with counts / windows / engagement →
+  a bucket `criteria` tree (full `ConditionEval`). See the
+  hogsend-authoring-buckets skill.
+- A look-back check mid-journey (count or window) → `ctx.history.hasEvent` in
+  the `run` body. See the hogsend-authoring-journeys skill.
+- Confirm a condition is actually firing on a running instance → see the
+  hogsend-cli skill.

package/skills/hogsend-database/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: hogsend-database
+description: Use when changing the database schema or running migrations in a Hogsend app — adding your own (client-track) tables in src/schema/ with Drizzle pgTable then db:generate + db:migrate, understanding the two-track system (engine-owned tables in @hogsend/db gate boot; your client tables are non-fatal), reading schema drift off /v1/health, using db:push as a dev shortcut, or bypassing the boot guard with SKIP_SCHEMA_CHECK.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Hogsend Database
+
+Hogsend runs **two independent migration tracks** against one Postgres
+database. As a consumer (a scaffolded, content-only app) you own exactly one of
+them: the **client track** — your own tables in `src/schema/index.ts`, your own
+migrations in `./migrations`. The other — the **engine track** — is owned by
+`@hogsend/db`, ships with `@hogsend/*` version bumps, and you never author it.
+
+This skill helps you add tables, generate + apply migrations, and read schema
+drift correctly without touching engine-internal files.
+
+## Key concepts (read this first)
+
+- **You own `src/schema/index.ts` only.** Define your app tables there with
+  Drizzle's `pgTable`. `pnpm db:generate` diffs that file and writes a migration
+  into `./migrations`; `pnpm db:migrate` applies it.
+- **Engine tables live in `@hogsend/db`, not your repo.** `contacts`,
+  `journeyStates`, `emailSends`, `trackedLinks`, `linkClicks`,
+  `emailPreferences`, `bucketMemberships`, `userEvents`, auth tables, and the
+  rest are engine-owned. **Never redefine them in `src/schema/`** — import them
+  from `@hogsend/db` if you need to read/join them.
+- **Two ledgers, one `drizzle` schema.** Engine track records into
+  `drizzle.__drizzle_migrations`; client track into `drizzle.__client_migrations`.
+  Your `drizzle.config.ts` is wired to the client ledger, so `db:generate`
+  can never collide with the engine's.
+- **Drift gating is asymmetric.** Engine-track drift is **fatal at boot** — the
+  running build hard-requires its bundled engine schema. Client-track drift is
+  **non-fatal**; once you wire `clientJournal` into `createHogsendClient` it
+  surfaces on `GET /v1/health` as `status: "migration_pending"` for you to
+  resolve (the block is opt-in — see `references/migrations.md`). You may
+  legitimately deploy app code ahead of an additive client migration.
+
+## The everyday flow
+
+```bash
+pnpm db:generate    # diff src/schema/index.ts -> new file in ./migrations
+pnpm db:migrate     # apply ENGINE track first, then your CLIENT track
+# then confirm both tracks are inSync on GET /v1/health
+```
+
+`scripts/migrate.ts` always runs engine-then-client (engine first so your client
+tables can reference engine tables). Railway's `preDeployCommand` runs the same
+`pnpm db:migrate` before every deploy.
+
+## Task playbooks — load the matching reference
+
+- **Add / change your own tables; what you may and may NOT touch** →
+  `references/client-track-schema.md`
+- **The db:generate → db:migrate flow, drizzle.config, the migrations dir +
+  meta journal, the db:push shortcut** → `references/migrations.md`
+- **Schema drift: fatal engine-track at boot vs non-fatal client-track on
+  /v1/health, SKIP_SCHEMA_CHECK, recovering a db:push'd ledger** →
+  `references/schema-drift.md`
+
+## Cross-skill links
+
+- Verifying a running instance's schema tracks (`schema.engine` /
+  `schema.client`, `inSync`) from the CLI — see the **hogsend-cli** skill
+  (`hogsend doctor --json`).
+- Querying with conditions / property checks / time windows over engine tables
+  (events, email engagement) — see the **hogsend-conditions** skill.

package/skills/hogsend-database/references/client-track-schema.md

@@ -0,0 +1,97 @@
+# Client-track schema — what you own
+
+Your app's tables live in **`src/schema/index.ts`** and migrate on the **client
+track**. This is the only schema file you author. Engine tables live in
+`@hogsend/db` and are off-limits to redefine.
+
+## What you own vs what the engine owns
+
+| | Owner | Where it lives | Ledger | Drift gating |
+|---|---|---|---|---|
+| **Client tables** (your app data) | You | `src/schema/index.ts` → `./migrations` | `drizzle.__client_migrations` | non-fatal → `/v1/health` |
+| **Engine tables** (`contacts`, `journeyStates`, `emailSends`, `trackedLinks`, `linkClicks`, `emailPreferences`, `bucketMemberships`, `userEvents`, auth, alert/import/dlq tables, …) | `@hogsend/db` | inside the published `@hogsend/db` package | `drizzle.__drizzle_migrations` | **fatal at boot** |
+
+**Rule:** never re-declare an engine table (`contacts`, `journey_states`,
+`email_sends`, etc.) in `src/schema/`. If you do, `db:generate` will try to
+create a table the engine already manages and your client migration will collide
+with engine objects. Import them from `@hogsend/db` instead.
+
+## Adding a table
+
+Open `src/schema/index.ts` and add a `pgTable`. The scaffold ships a starter
+table (`clientNotes`) you can rename or replace:
+
+```ts
+// src/schema/index.ts
+import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+/**
+ * CLIENT-track schema. Engine tables (contacts, journeyStates, emailSends,
+ * tracking, ...) live in @hogsend/db and migrate on the ENGINE track — do NOT
+ * redefine them here. Add only your own app-specific tables.
+ */
+export const supportTickets = pgTable(
+  "support_tickets",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    // Match the engine's contact identity: contacts.externalId is the user id
+    // you pass to ingest/journeys. Keep it text, not a FK, to stay decoupled.
+    userId: text("user_id").notNull(),
+    subject: text("subject").notNull(),
+    status: text("status").notNull().default("open"),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .defaultNow()
+      .notNull(),
+  },
+  (table) => [index("support_tickets_user_id_idx").on(table.userId)],
+);
+```
+
+Then generate + apply (see `migrations.md`):
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
+
+## Conventions worth matching
+
+Engine tables use these patterns; mirroring them keeps your schema consistent:
+
+- **`uuid("id").primaryKey().defaultRandom()`** for surrogate keys.
+- **`timestamp(..., { withTimezone: true })`** — always timezone-aware.
+- **`text("user_id")`** to reference a contact by its external id (the same id
+  you pass to `ctx.trigger`/ingest). Engine tables denormalize `user_id` as
+  plain `text` rather than a hard FK to `contacts`, so you stay decoupled from
+  engine internals — do the same.
+- Add `index(...)` on the columns you filter/sort by.
+
+## Reading engine tables from your code
+
+You don't redefine engine tables — you import them. The engine container exposes
+the schema-aware Drizzle db; engine table objects come from `@hogsend/db`:
+
+```ts
+// e.g. inside a custom workflow or route handler
+import { contacts, emailSends } from "@hogsend/db";
+import { eq } from "drizzle-orm";
+
+// `db` is the container's Drizzle instance (c.get("container").db, or
+// client.db). It already knows the full engine + your client schema.
+const rows = await db
+  .select()
+  .from(contacts)
+  .where(eq(contacts.externalId, "user_123"));
+```
+
+Joining your client table to an engine table (e.g. `support_tickets.userId` ↔
+`contacts.externalId`) works because both are registered on the same Drizzle
+instance — your client schema is bundled into the consumer build alongside
+`@hogsend/db`.
+
+## Don't edit
+
+- Anything under `@hogsend/db` (it's a dependency, not your source).
+- The engine ledger `drizzle.__drizzle_migrations`.
+- The engine's `drizzle.config` / migration folder — you only have your own
+  client `drizzle.config.ts` and `./migrations`.