hogsend

Provision and manage Hogsend deployments on Railway. Use when creating new client instances, managing env vars, checking health, updating journey configs, or troubleshooting Railway deployments.

Use when deploying or configuring production infra for YOUR scaffolded Hogsend app — Railway two services (api via railway.toml with /v1/health + pre-deploy db:migrate; worker via railway.worker.toml, no healthcheck), Hatchet-Lite, required vs optional env, and upgrading the engine + refreshing vendored skills. This is for shipping your own app, NOT the maintainer's package-release process.

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.

Use when adding or editing a code-first feature flag in src/flags/ — defineFlag({ key, name, type, variants?, defaultValue?, description?, enabled? }) from @hogsend/engine. A flag committed to the repo, upserted into a `flags` row by the boot reconciler (born DISABLED, rollout 0). Covers the contract-vs-state split (code owns key/name/type/variants/defaultValue/description; DB/Studio owns enabled/rollout/targeting/conditionSets), the register ritual (src/flags/index.ts + thread flags into createHogsendClient in BOTH src/index.ts and src/worker.ts), running `pnpm flags:generate` after adding/removing a flag to refresh flags.d.ts (typed useFlag/getFlag/evaluate), and when to use client.flags.create() / Studio (dynamic, experimental) vs defineFlag (durable product flags).

Generate the full Hogsend brand asset pack — social/OG/banner image templates in every preset, palette colorway and campaign carousel, plus Remotion campaign videos — into the gitignored marketing/out/ folder. Use whenever asked to (re)generate brand templates, ad carousels, campaign stills, brand videos, contact sheets, or "the out folder" of marketing assets.

Add a new play to hogsend.com/playbook (apps/docs/content/playbook). Use whenever someone wants a new playbook item — it walks the whole contract end to end - frontmatter, the intro + five-part template in the right register, the copy rules (tool-agnostic play steps, honest facts, valid engine snippets), the dogfood weekly-rotation sync, and the verification gates. The plays shipped in

Hatchet CLI skills for managing workflows, workers, and runs. Use this skill when triggering workflows, starting workers, debugging runs, replaying failed runs, or setting up the Hatchet CLI and profiles.

Use when releasing or publishing @hogsend/* or create-hogsend, adding a publishable package or scaffold dependency, bumping versions, reviewing a "Version Packages" PR, or diagnosing a package that is missing from npm.

Use when an agent needs to inspect or operate a running Hogsend lifecycle engine — querying metrics/contacts/events, listing or enabling/disabling journeys, checking health, or onboarding a local instance — by driving the consolidated `hogsend` CLI. Every data command supports --json for machine-readable output.

Use when creating, validating, or enabling a Journey Blueprint — the JSON-authored alternative to defineJourney() for automations that shouldn't need a PR. Covers the create_journey_blueprint/validate_journey_blueprint/enable_journey_blueprint MCP tools, the blueprint graph's node/edge vocabulary, and the validate-in-a-loop workflow.

Use when adding or editing a code-defined email list in src/lists/ — defineList({ id, name, description?, defaultOptIn, enabled? }) from @hogsend/engine. A list is just a named email_preferences.categories key (NO new table); defaultOptIn:false = opt-in, defaultOptIn:true = opt-out. Covers the reserved ids, the id pattern, and the register ritual (src/lists/index.ts + thread the lists array into createHogsendClient in BOTH src/index.ts and src/worker.ts — lists are NOT passed to createWorker). Surfaced at GET /v1/lists + POST /v1/lists/:id/(un)subscribe.

Use when migrating a product OFF Loops, Customer.io, or Resend Broadcasts/Audiences onto Hogsend — auditing the existing email-SaaS integration (SDK calls in code + GUI-side workflows/campaigns/segments/templates), mapping each source concept to its Hogsend equivalent (contacts.upsert, events.send, defineJourney journeys, four-file react-email templates, defineList lists, buckets, campaigns, webhook sources), then executing an incremental dual-write → verify → switch → remove cutover that preserves unsubscribes/suppression. NOT for a greenfield integration with no incumbent (that is hogsend-integrate) and NOT for authoring mechanics themselves (delegate to the hogsend-authoring-* skills).

Use when adding or editing a one-shot campaign (broadcast) in src/campaigns/ — defineCampaign({ id, audience: { list } | { bucket }, template, props?, subject?, from?, sendAt, enabled? }) from @hogsend/engine, a scheduled blast committed to the repo. Covers the boot reconciler (future sendAt schedules; edits sync while still scheduled; a stale sendAt at first deploy expires instead of firing; sent = retired), the register ritual (src/campaigns/index.ts + thread campaigns into createHogsendClient in BOTH src/index.ts and src/worker.ts), cancel via CLI/Studio/API, and when to use the API (hs.campaigns.send) instead of a definition.

Convert a long, flat course chapter (a single wall-of-text `.mdx`) into a nested hub + a stream of bite-size interactive "atoms" in apps/course (Next.js + Fumadocs). Use this when someone wants to atomize a chapter — or a whole course — of growth-with-posthog: it walks the proven "atom factory" pipeline end to end (pull transcripts → snapshot the block inventory → split into hub + atoms per the authoring contract → delete the flat file → regenerate + verify the manifest hasn't drifted → run gates → one commit per chapter). Reproduces chapters 0 and 1, which already ship in this shape.

Operate the Hogsend community Discord (guild 1516090424194760744) with the discli CLI — create/edit channels, roles, permissions, post messages, manage the verification gate, and extend the /link flow. Use whenever building out or administering the Hogsend Discord server, adding channels/roles, changing permissions, posting announcements, or working on the gate / slash commands.

Use when you need to verify Hogsend's one-click `hogsend connect posthog` flow locally end-to-end — pick the integration test for CI/regression, the Claude-in-Chrome OAuth handshake to prove real consent, or the cloudflared tunnel for a real PostHog event verified by the engine (snapshot+restore required).

Use when calling Hogsend from your own product/app code (a signup handler, a billing webhook, a cron) via the @hogsend/client SDK + public data-plane API — new Hogsend({ baseUrl, apiKey }), then contacts.upsert/find/delete, events.send (alias .track), emails.send, lists.list/subscribe/unsubscribe, webhooks.create/list/get/update/delete/rotateSecret/sendTest (ADMIN plane — needs a full-admin key), and verifyHogsendWebhook for the subscriber side. Teaches the contactProperties-vs-eventProperties split on POST /v1/events, the ingest-scoped HOGSEND_API_KEY, the 202 + listsError warning, and HogsendAPIError/RateLimitError. NOT for use inside a journey (there, use sendEmail()/ctx.trigger()). The scaffold ships a preconfigured `hs` at src/lib/hogsend.ts.

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.

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.

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.

Use when wiring an EXISTING product codebase — Next.js (App or Pages Router), Express, Hono, Remix, SvelteKit, or any Node server — to a running Hogsend instance via @hogsend/client. The outside-in playbook — detect the host stack, find the signup/auth/billing seams (better-auth, Clerk, Supabase, Stripe, NextAuth), install @hogsend/client, add contacts.upsert on signup + events.send on key actions + emails.send for transactional, wire HOGSEND_API_URL/HOGSEND_API_KEY env, then verify ingestion with `hogsend events`. NOT for code inside a Hogsend app itself (there, use hogsend-client-sdk for app code or the authoring skills for journeys/emails) and NOT for migrating off Loops/Customer.io/Resend Broadcasts (that is hogsend-migrate).

Use when extending a Hogsend app beyond journeys/emails/buckets — swapping the email or analytics provider behind its engine-owned contract (EmailProvider / PostHogService), wiring an outbound integration (Slack, a CRM, Stripe) as plain code called from a journey, fanning the outbound EVENT stream out to a tool via a code-defined destination (defineDestination, see hogsend-authoring-destinations), or deciding when to publish a reusable @hogsend/plugin-* package. Covers the categories of extension and where each is wired.

Use when adding or editing a code-defined OUTBOUND destination in src/destinations/ — defineDestination({ meta:{id}, events, transform(envelope, ctx) -> { url, method?, headers, body, isSuccess? } | null }) from @hogsend/engine. A destination is a delivery-time transform keyed by webhook_endpoints.kind that fans the outbound event catalog (contact.*, email.*, journey.completed, bucket.*) out to a product/data tool (PostHog, Segment, Slack, a CRM, a warehouse), reusing the engine's durable retry/backoff/DLQ delivery for free. Covers the shipped presets (webhook/posthog/segment/slack), ENABLED_DESTINATION_PRESETS, per-endpoint config credentials, the null-skip and throw-is-config-error contract, and the register ritual (src/destinations/index.ts + thread destinations into createHogsendClient in BOTH src/index.ts and src/worker.ts). NOT for ad-platform CAPI (deferred to PostHog CDP).

Use when adding an inbound webhook source in src/webhook-sources/ (defineWebhookSource — auth as a match|signature discriminated union, optional Zod schema, transform(payload, ctx) -> IngestEvent | null, served at POST /v1/webhooks/:id), reaching for a built-in integration preset (Clerk/Supabase/Stripe/Segment), or a custom Hatchet task in src/workflows/ passed as extraWorkflows (NOT workflows) to createWorker, including the idempotent batched expand→migrate→contract backfill pattern. Outbound signed webhooks are managed separately (hogsend webhooks CLI / hs.webhooks).

Use when adding or editing a real-time audience bucket in src/buckets/ — defineBucket() with a criteria condition tree, the typed bucket.entered / bucket.left transition refs used as journey trigger/exitOn, colocated bucket.on("enter"|"leave"|"dwell") reactions (dwell fires from the reconcile cron over the EXISTING population), member access (count/has/members/iterator), time-based rolling windows + reconcile, and entryLimit. Buckets wire into BOTH createHogsendClient and createWorker.