npm - create-ailk - Versions diffs - 0.1.0 - Mend

create-ailk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (533) hide show

package/templates/.env.example ADDED Viewed

@@ -0,0 +1,205 @@
+# AI Launch Kit — root environment template
+# Copy to .env (gitignored) and fill in values.
+# Per-app .env files live alongside their app (apps/api/.env, etc.).
+# ── Marketing / canonical domain ─────────────────────────────────────────────
+AILK_PUBLIC_DOMAIN=ailaunchkit.ai
+# ── Launch posture ───────────────────────────────────────────────────────────
+# STEALTH defaults to "true" for new installs so a freshly-deployed instance
+# isn't indexed by crawlers or unfurled by Slack/Twitter/LinkedIn before the
+# operator is ready. Three layers gate on this single flag:
+#   1. apps-paid/marketing-web/public/robots.txt (always-blocking static file)
+#   2. X-Robots-Tag: noindex, nofollow, noarchive HTTP header (next.config.ts)
+#   3. <meta name="robots" content="noindex,nofollow"> tag (app/layout.tsx)
+# At launch, set STEALTH=false on the hosting platform's env vars and redeploy.
+# See README.md § "Going live" for the full flip checklist.
+STEALTH=true
+# Blog-OFF launch gate (#3413) — SITE-ARCHITECTURE §4.1 parks the blog at
+# launch (SITE-PLAN derived.blog_enabled=false). While unset/false, every
+# public blog surface is gated: /blog + posts 404, /blog/rss.xml and
+# /blog/<slug>.md 404, sitemap/llms.txt omit blog entries, and the nav/footer
+# hide the Blog link. Set BLOG_ENABLED=true and redeploy to launch the blog.
+# BLOG_ENABLED=true
+# ── Content backend ──────────────────────────────────────────────────────────
+# Default: mdx — reads from /content/*.mdx at the repo root.
+# Set to "pro-cms" to use the paid Pro CMS adapter (separate package, not
+# bundled with the OSS template).
+CONTENT_BACKEND=mdx
+# Override the content directory (default: <repo-root>/content). Useful for tests.
+# AILK_CONTENT_ROOT=
+# ── Database (optional in standalone mode) ───────────────────────────────────
+# DATABASE_URL=postgres://user:pass@host:5432/db
+# ── Stripe (sandbox keys only — never sk_live_/pk_live_) ─────────────────────
+# STRIPE_SECRET_KEY=sk_test_...
+# Stripe webhook signing secret — used by POST /api/webhooks/stripe to
+# verify event payloads. Get from the Stripe Dashboard:
+# Developers → Webhooks → <your endpoint> → Signing secret.
+# Format: whsec_*. Server-only — must NOT be prefixed with NEXT_PUBLIC_.
+# STRIPE_WEBHOOK_SECRET=
+# Internal URL of the billing service — used by marketing-api's webhook
+# proxy (POST /v1/webhooks/stripe) to forward verified deliveries. Format:
+# https://<vercel-deployment>.vercel.app (no trailing slash, no path).
+# BILLING_SERVICE_URL=
+# ── Auth (Better Auth — apps/web only) ───────────────────────────────────────
+# BETTER_AUTH_URL=http://localhost:3000
+# BETTER_AUTH_SECRET=
+# ── Email provider (Resend default) ──────────────────────────────────────────
+# RESEND_API_KEY=
+# ── Analytics ────────────────────────────────────────────────────────────────
+# All providers off by default. Set the env var(s) for any provider(s) you want.
+# Each is independent — set one, two, all three, or none.
+#
+# Vercel Analytics — built-in dashboard for Vercel deploys. Requires Vercel hosting.
+# Set to "true" to enable. Requires redeploy after change (NEXT_PUBLIC_* baking).
+# NEXT_PUBLIC_VERCEL_ANALYTICS_ENABLED=
+#
+# Google Analytics 4 — gtag.js measurement. Requires consent in EU/UK/CA.
+# Get the measurement ID from analytics.google.com → Admin → Data Streams.
+# Format: G-XXXXXXXXXX. Requires redeploy after change (NEXT_PUBLIC_* baking).
+# NEXT_PUBLIC_GA_MEASUREMENT_ID=
+#
+# Google Analytics tag — env-driven gtag.js wiring used by the three Next.js
+# apps (apps/web, apps-paid/marketing-web, apps-paid/dashboard-web). When set,
+# every page emits the canonical gtag.js loader + inline init in <head>.
+# Empty by default so new AILK installs do NOT pre-configure a GA property —
+# customers set their own measurement ID after registering a GA4 stream.
+# Format: G-XXXXXXXXXX (Google Analytics 4 measurement ID). See README.md
+# § "Going live" → "Analytics" for the configured wire-up flow. Distinct from
+# NEXT_PUBLIC_GA_MEASUREMENT_ID above — that var drives the consent-gated
+# @working-theory/analytics adapter; this one drives the always-on env-presence path
+# (Sam's call per issue #886). Most installs will set ONE of the two.
+# NEXT_PUBLIC_GOOGLE_TAG_ID=
+#
+# Google Search Console — verification meta tag. No script, no consent needed.
+# Get the token from search.google.com/search-console → Settings → Ownership
+# verification → HTML tag. Paste only the content="..." value (not the full tag).
+# GOOGLE_SITE_VERIFICATION=
+#
+# GA4 Measurement Protocol — server-side analytics secret.
+# Required for `lead-captured` and `purchase-completed` events to reach
+# Google Analytics 4 from apps/api. Get from analytics.google.com →
+# Admin → Data Streams → API secrets. Server-only — must NOT be prefixed
+# with NEXT_PUBLIC_.
+# GA_API_SECRET=
+# ── Error monitoring (Sentry) ────────────────────────────────────────────────
+# All Sentry env vars empty by default — a fresh AILK install sends ZERO
+# traffic to Sentry until you plug in your own DSN. Same OSS-default-on
+# pattern as #884 (stealth) and #886 (Google Analytics).
+#
+# The five vars below cover both runtime (DSN) and build-time (auth token +
+# org/project for source-map upload). When SENTRY_DSN is unset, every
+# Sentry.init() call resolves to `enabled: false` and the SDK is a no-op —
+# no network, no captures, no console noise. When SENTRY_AUTH_TOKEN +
+# SENTRY_ORG + SENTRY_PROJECT are unset, the build-time source-map upload
+# step skips silently — `next build` still succeeds.
+#
+# To turn Sentry on:
+#   1. Create a Sentry project at https://sentry.io.
+#   2. Copy the project's DSN (Settings → Projects → <project> → Client Keys).
+#   3. Mint a build-time auth token at https://sentry.io/settings/auth-tokens/
+#      with scopes: project:releases, org:read.
+#   4. Set all five vars on your hosting platform's env config.
+#   5. Redeploy. See README.md § "Going live" → "Error monitoring (Sentry)".
+#
+# Server-runtime DSN — read by sentry.server.config.ts / sentry.edge.config.ts
+# in each Next.js app and by src/lib/sentry-init.ts in each Fastify app.
+# Format: https://<key>@<org>.ingest.sentry.io/<project-id>. Server-only.
+# SENTRY_DSN=
+#
+# Browser DSN — read by sentry.client.config.ts in each Next.js app. Must
+# carry the NEXT_PUBLIC_ prefix so Next.js bakes it into the browser bundle.
+# Usually the same value as SENTRY_DSN; safe to expose because Sentry DSNs
+# are public by design.
+# NEXT_PUBLIC_SENTRY_DSN=
+#
+# Build-time auth token — read by withSentryConfig() in each Next.js app's
+# next.config.{ts,mjs}. Uploads source maps at build time so production stack
+# traces are de-minified. Server-only. Format: sntrys_*.
+# SENTRY_AUTH_TOKEN=
+#
+# Sentry organisation slug — read by withSentryConfig() alongside auth token.
+# Match the slug from your Sentry URL (https://sentry.io/organizations/<slug>/).
+# SENTRY_ORG=
+#
+# Sentry project slug — read by withSentryConfig() alongside auth token.
+# Match the slug from your Sentry project URL.
+# SENTRY_PROJECT=
+# ── License (JWT model — ADR 0014) ───────────────────────────────────────────
+# The JWT issued by ailaunchkit.ai. When set, @working-theory/license verifies it locally
+# against a bundled public key and unlocks Pro features. When unset, deploy
+# runs in free tier — no network, no parse attempt.
+# AILK_LICENSE_KEY=
+# Override the daily refresh upstream (self-hosters point at their own server
+# implementing the @working-theory/validation refresh contract).
+# Default: https://ailaunchkit.ai/api/license/refresh
+# AILK_LICENSE_REFRESH_URL=
+# Self-host override — replaces the bundled public key with a PEM-encoded one.
+# Only set this if you operate your own license-signing infrastructure.
+# AILK_LICENSE_PUBLIC_KEY_PEM=
+# Filesystem path where the daily-refreshed JWT is written. Read-only
+# filesystems silently no-op; in-process JWT continues to serve until restart.
+# Default: ${cwd}/.ailk-license.jwt
+# AILK_LICENSE_STORAGE_PATH=
+# ── E2E determinism (clock + randomness) ─────────────────────────────────────
+# These three env vars let end-to-end test harnesses freeze the wall clock and
+# seed the PRNG so flake-prone time- or random-dependent assertions become
+# deterministic. All three default UNSET to real platform behavior (Date.now,
+# crypto.randomUUID); production deployments leave them unset.
+#
+# Wired through @working-theory/common (getClock / getRandomness). Migrated call sites:
+# rate-limit window, API token expiry, session-expiry check, JWT exp comparison,
+# request-id generator. Read at call time, not module load.
+#
+# AILK_CLOCK_MODE        — unset (real) | "frozen" (clock anchored at a known
+#                          epoch; same value returned on every call)
+# AILK_RANDOMNESS_MODE   — unset (real) | "seeded" (deterministic PRNG)
+# AILK_RANDOMNESS_SEED   — required when MODE=seeded; numeric string. Non-numeric
+#                          / unset triggers a stderr warn and falls back to real.
+# AILK_CLOCK_MODE=
+# AILK_RANDOMNESS_MODE=
+# AILK_RANDOMNESS_SEED=
+# ── E2E test-auth seam (pre-OSS — never set in production) ───────────────────
+# These two env vars enable the test-auth route at POST /api/test/auth/session
+# (apps/api/src/routes/test/auth/session.ts) so an e2e harness can mint a
+# Better Auth session for a seeded test user WITHOUT going through Google
+# OAuth, GitHub OAuth, or magic-link email.
+#
+# TRIPLE-GATED — the route is only mounted when ALL three of these hold:
+#   1. NODE_ENV !== "production"
+#   2. AILK_TEST_AUTH_ENABLED === "true" (literal string)
+#   3. AILK_TEST_AUTH_USER_ALLOWLIST is non-empty
+# If any gate fails, Fastify returns its default 404 for the route — the
+# surface NEVER advertises itself. PRODUCTION DEPLOYMENTS MUST LEAVE BOTH
+# UNSET. The startup log emits "test-auth route MOUNTED" when the route is
+# active so an accidental prod-enable is visible.
+#
+# Allowlist format: comma-separated user IDs (exact-match strings; no regex,
+# no wildcard). Empty entries between commas are trimmed.
+# Run `pnpm --filter @working-theory/database db:seed:test` to seed three test users
+# (test-e2e-user / test-e2e-admin / test-e2e-owner — distinguished by the
+# Better Auth `role` field). The seed script itself refuses to run unless
+# AILK_TEST_AUTH_ENABLED === "true".
+#
+# AILK_TEST_AUTH_ENABLED=
+# AILK_TEST_AUTH_USER_ALLOWLIST=
+# ── Lead capture file store ───────────────────────────────────────────────────
+# Always-on JSONL write path — every successful submission appends a line.
+# Default output: apps/api/leads.jsonl (relative to process cwd).
+# LEAD_CAPTURE_FILE=apps/api/leads.jsonl
+# Set to "true" to disable file writes (leads go to DB only; requires DATABASE_URL).
+# LEAD_CAPTURE_FILE_DISABLED=false
+# Set to "true" to include the submitter's IP in metadata (default: off for privacy).
+# LEAD_CAPTURE_INCLUDE_IP=false

package/templates/.gitkeep ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ # Placeholder so `templates/` is committed even when its snapshot is gitignored.
2	+ # Populated by `scripts/build-templates.mjs` (runs at `prepublishOnly`).

package/templates/CLAUDE.md ADDED Viewed

@@ -0,0 +1,142 @@
+# {{PROJECT_NAME}} — Agent Operating Manual
+You are Claude, working in the `{{PROJECT_NAME}}` repo. Read this file at session start.
+## Repo shape
+```
+apps/web/         Next.js 16 app — visitor-facing UX
+apps/api/         Fastify HTTP API — checkout, lead capture, webhooks (optional)
+apps/mcp/         MCP server — agent-callable tools (optional)
+content/          MDX content for typed page surfaces (HomePage, BlogPosting, ...)
+.claude/          Rules, skills, and agent definitions for Claude Code
+docs/             Project notes (ADRs, architecture, planning)
+```
+You consume `@working-theory/*` packages from npm. Source for those packages is at
+<https://github.com/tailwind-ai/ai-launch-kit>; you don't have it locally.
+Treat each `@working-theory/*` package as a third-party dependency — read its README
+or its types, don't go looking for the source.
+## Architecture invariants
+The full rule lives at `.claude/rules/architecture.md`. Summary:
+- `apps/*` are peer apps. They do not import from each other.
+- `apps/web` does not read the database — it goes through `apps/api` via
+  the published HTTP client.
+- Vendor SDKs (Stripe, Resend, NextAuth, Prisma) are wrapped in their
+  respective `@working-theory/*` packages. Don't import them directly in your code.
+- New page types live under `content/<TypeName>/` and consume the schema
+  builders from `@working-theory/schema`.
+Crossing one of these is an architecture decision, not a workaround. If
+you think you need to, stop and write a short note in `docs/` explaining
+why before you change the boundary.
+## Resource map
+Where to find the rule, surface, or fact you need.
+| For…                                           | Look at                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------- |
+| Per-issue workflow (pick → branch → TDD → PR)  | `.claude/rules/loop-contract.md`                               |
+| Architecture boundaries (the why + escalation) | `.claude/rules/architecture.md`                                |
+| Diff hygiene when editing existing files       | `.claude/rules/preserve-existing-style.md`                     |
+| Skills available to invoke                     | `.claude/skills/README.md`                                     |
+| Domain agents (sample web agent)               | `.claude/agents/web.md`                                        |
+| Code style, testing, security, content schema  | `CONVENTIONS.md`                                               |
+| Environment variables and what they unlock     | `.env.example`                                                 |
+| Per-page-type content shape                    | `content/<TypeName>/*.mdx` frontmatter                         |
+| Deploy targets                                 | `apps/web/vercel.json`, `apps/api/vercel.json`                 |
+| Verification before push                       | `pnpm preflight` (architecture + types + lint + tests + build) |
+If a question doesn't fit any row above, add the answer to this table
+when you find it. Future-you will thank present-you.
+## Workflow
+The single-developer flow is described fully in
+`.claude/rules/loop-contract.md`. The short version:
+1. Pick or open an issue with a `## Acceptance Criteria` section.
+2. Branch from your default branch (typically `main`).
+3. Write tests against the acceptance criteria first (RED).
+4. Implement the smallest change that makes them pass (GREEN).
+5. Run `pnpm preflight` — must be green before you push.
+6. Open a PR; reference the issue with `Closes #N`.
+Skip the test-first step only for: pure documentation, single-line typo
+fixes, or config-only changes already covered by an existing test.
+## Project-specific MCP servers
+Configured in `.claude/settings.json`. This project doesn't ship any MCP
+server connections by default — add the ones you actually use (your
+database, your deployment platform, etc.) and keep the tokens in
+`.env.local`, never in the repo.
+```json
+// example shape — add only what you have credentials for
+{
+  "mcpServers": {
+    "your-database": { "command": "...", "args": ["..."] }
+  }
+}
+```
+## Content schema discipline
+This project's content is typed against schema.org via `@working-theory/schema`.
+Every MDX file under `content/` has frontmatter that the build validates:
+```yaml
+---
+type: BlogPosting # one of the supported page types
+slug: my-post # URL-safe identifier
+title: My Post
+description: "Short summary used for the page meta tag and JSON-LD."
+---
+```
+When in doubt, copy an existing file in the same folder, then change the
+slug and the body. Don't invent a new `type` value without first
+checking what `@working-theory/schema` exports.
+## Hard floors
+These are non-negotiable in this repo. Don't ask, don't try to route
+around them.
+- **No live Stripe keys in code.** `sk_live_*` and `pk_live_*` belong in
+  the deployment platform's secrets store, never in `.env`, source files,
+  or commit messages. Use Stripe sandbox keys for everything in source.
+- **No secrets in commits.** API keys, license keys, database URLs — all
+  go through `.env.local` (gitignored) for local dev and the deployment
+  platform's secrets store for prod.
+- **Validate every webhook.** Stripe sends signed payloads; reject any
+  request whose HMAC doesn't match before you do any work on it.
+- **No production database access from a dev session.** If you need to
+  inspect prod, do it through your hosting platform's read-only console,
+  not from your laptop with a copied connection string.
+## When to stop and ask
+You have wide latitude on most things, but stop and surface the question
+when:
+- An architecture invariant would have to bend.
+- A change to a shared `@working-theory/*` package would be needed (file an issue
+  upstream at <https://github.com/tailwind-ai/ai-launch-kit>; don't fork).
+- You're about to delete or move >5 files at once.
+- The acceptance criteria contradict each other or the existing code.
+A 30-second clarifying question beats two hours of work down the wrong
+branch.
+## Inherited rules
+If you have global rules in `~/.claude/rules/` they still apply. This
+file describes only what's specific to `{{PROJECT_NAME}}`. Where the two
+disagree, the global rule wins unless you're explicitly editing this
+file to override it.

package/templates/CONVENTIONS.md ADDED Viewed

@@ -0,0 +1,222 @@
+# {{PROJECT_NAME}} — Coding Conventions
+`CLAUDE.md` answers "how does this repo work?" — this file answers "what's
+the right way to write the code?" Read both before non-trivial work.
+A new convention is a PR + a short note in `docs/` explaining the change,
+not a unilateral introduction.
+---
+## Module boundaries
+The boundary rule lives at `.claude/rules/architecture.md`. The minimum
+you need to remember:
+- `apps/web`, `apps/api`, `apps/mcp` are peer apps. They do not import
+  from each other.
+- `apps/web` does not import `@working-theory/database`. It speaks to `apps/api`
+  via the published HTTP client.
+- Packages from npm (`@working-theory/*` and others) are upstream — your code
+  consumes them, never the other way around.
+- Vendor SDKs (`stripe`, `resend`, `next-auth`, `@prisma/client`) are
+  imported only inside the `@working-theory/*` package that wraps them. If you
+  need them elsewhere, route through the wrapper.
+If you genuinely need to cross a boundary, that's an architecture
+decision — write a short rationale in `docs/` first.
+---
+## TypeScript
+- **Strict mode.** No bare `any`. Use `unknown` and narrow.
+- **`import type` for type-only imports.** Reduces bundle size and
+  signals intent.
+- **Annotate return types on exported functions.** Inferred types are
+  fine for internal helpers; exports declare explicitly.
+- **No `// @ts-ignore` without an explanation.** Prefer
+  `// @ts-expect-error` so unused suppressions surface as errors.
+- **Discriminated unions over enums** for shapes shared across modules.
+  Enums don't tree-shake cleanly across boundaries.
+- **Zod for runtime validation** of anything coming from outside your
+  process — request bodies, env vars, fetched JSON.
+---
+## File sizing and naming
+- **Filenames are kebab-case.** `user-profile.ts`, not `userProfile.ts`.
+- **React component files are PascalCase `.tsx`.** `Button.tsx`,
+  `UserCard.tsx`. Tests next to them under `__tests__/`.
+- **Directories are kebab-case.** `lead-capture/`, not `leadCapture/`.
+- **Forbidden filenames:** `utils.ts`, `helpers.ts`, `common.ts`,
+  `misc.ts`. Use a name that says what's inside.
+- **One exported entity per file** is the default. If a file exports a
+  component plus seven helpers, split the helpers out.
+- **Files should fit in your head.** No hard line limit, but a single
+  file growing past ~400 lines and not being one cohesive thing is a
+  signal to split.
+---
+## React + Next.js
+- **Server Components by default.** Only add `'use client'` when the
+  component uses browser-only APIs (`useState`, `useEffect`, refs,
+  click handlers).
+- **Server actions** are fine for form-submit flows that live entirely
+  in `apps/web`. For anything reused or agent-callable, put it in
+  `apps/api` instead.
+- **`apps/web` does not own the database.** Even in server components,
+  `apps/web` reads from `apps/api`. The boundary is real.
+- **Mobile-first.** Default Tailwind utilities target mobile; use
+  `md:`/`lg:` modifiers for larger viewports.
+- **MDX rendering** uses `next-mdx-remote/rsc`. Don't introduce
+  `@next/mdx` — it conflicts with Server Components.
+---
+## Tailwind + design tokens
+- **Semantic tokens only.** `bg-canvas`, `text-fg`, `border-border`,
+  `bg-accent`. The palette comes from `@working-theory/theme`.
+- **No raw hex, rgb, or arbitrary colors.** `bg-[#abc]` is forbidden.
+  If a token you need doesn't exist, add it to your theme extension.
+- **No inline `style={{ ... }}`.** Reserve it for genuinely dynamic
+  values (computed positions, animations).
+- **Spacing uses Tailwind's scale.** `p-4`, `gap-2`, `mt-8`. Custom
+  values go in `tailwind.config.ts`.
+- **Dark mode** uses the `dark:` modifier with tokens that resolve in
+  both modes. Don't hardcode `text-white`.
+---
+## Database conventions
+If you've enabled the optional database layer:
+- **Prisma is the source of truth.** Schema lives in
+  `prisma/schema.prisma`; migrations are generated with
+  `pnpm db:migrate`.
+- **Migrations are forward-only.** Never edit a migration that has
+  already been applied. Write a corrective migration instead.
+- **No raw SQL outside the migrations folder.** All runtime data
+  access goes through Prisma.
+- **`@map` for snake_case ↔ camelCase.** DB columns are snake_case;
+  TS field names are camelCase.
+- **Index every query you ship.** Add `@@index([...])` for any field
+  combination read in a route handler.
+- **Idempotent seeds.** Your seed script must run safely twice. Use
+  `prisma.upsert` keyed on a stable unique field.
+- **Standalone-aware code.** This project boots without
+  `DATABASE_URL`. Code that requires the DB must handle the unset case
+  (return 501, fall through to MDX content, etc.).
+---
+## Testing
+- **Jest + ts-jest** for unit tests, co-located. Each app and `database/`
+  ships its own Jest config; the root `pnpm test` fans out via
+  `pnpm -r test`.
+  - Source: `Foo.tsx` → tests: `__tests__/Foo.test.tsx`.
+  - Run: `pnpm --filter <pkg> test`.
+- **Playwright** for end-to-end (root `e2e/` once you add it).
+- **TDD: RED → GREEN.** Write the failing test from the acceptance
+  criteria first. Implement to green. Refactor with tests still green.
+- **Skip TDD only for** config-only changes, pure documentation, or
+  single-line fixes already covered by an existing test.
+- **Happy-path + failure-path** is the minimum for new behavior. One
+  test of each.
+- **Don't mock code you own.** Mock external services (Stripe,
+  Resend, the HTTP layer to `apps/api` from `apps/web` tests). If
+  you're mocking your own service, the test is at the wrong layer.
+- **Existing tests pass unchanged on cleanup PRs.** A behavior change
+  needs explicit acceptance criteria.
+---
+## Security
+- **Env vars only — never hardcoded secrets.** `.env.local`
+  (gitignored) for local dev; production secrets via your deployment
+  platform's secrets store.
+- **HMAC-verify every webhook.** Stripe, license callbacks, anything
+  signed. Reject before any side effect; log the rejection; return 401.
+- **Input validation at the boundary.** Every route validates request
+  bodies via Zod. Reject with 422 on schema failure.
+- **No secrets in logs.** Redact tokens, API keys, and personal data
+  before logging. The wrapper packages handle this for you when you
+  use them.
+- **Stripe sandbox keys only in source.** `sk_live_*`/`pk_live_*` live
+  in the production secrets store. They never appear in `.env`,
+  source files, or commit messages.
+- **License key handling** uses the `@working-theory/license` verifier. License
+  keys are bearer tokens — treat them with the same care as API keys.
+---
+## Content schema
+- **Validate at MDX build time.** The build step parses every file
+  under `content/` and rejects malformed frontmatter.
+- **Frontmatter is the contract.** `type`, `slug`, plus the fields
+  that match the type's schema, in YAML at the top of every MDX file.
+- **Single source of truth** for content shape lives in `@working-theory/schema`
+  (schema.org-compatible types). Don't redefine the same shape inline.
+---
+## Cross-cutting wrappers
+Vendor SDKs are imported only inside their `@working-theory/*` wrapper. The
+wrapper exports a typed, project-flavored interface; your code imports
+from the wrapper.
+| Vendor              | Wrapper package       | Where you use it             |
+| ------------------- | --------------------- | ---------------------------- |
+| Stripe              | `@working-theory/stripe-client` | `apps/api` checkout/webhooks |
+| NextAuth            | `@working-theory/auth-client`   | `apps/api`, `apps/web`       |
+| Resend / Nodemailer | `@working-theory/email`         | `apps/api`                   |
+| Analytics           | `@working-theory/analytics`     | `apps/web`, `apps/api`       |
+| Prisma              | `@working-theory/database`      | `apps/api`, `apps/mcp`       |
+The wrapper is where retries, signature verification, error mapping,
+and config defaults live. Don't reinvent them per consumer.
+**Why bother:** swapping a vendor (Resend → SendGrid; NextAuth → Clerk;
+Prisma → Drizzle) becomes a one-package change. Your app code doesn't
+move.
+---
+## Commit + diff hygiene
+- **One PR, one task.** No "while I was in there" changes. Drive-by
+  cleanup goes in its own follow-up PR.
+- **Diff is the contract.** A 20-line behavioral change should produce
+  a ~20-line diff. If your editor reformatted unrelated lines, revert
+  the formatting before committing. See
+  `.claude/rules/preserve-existing-style.md`.
+- **Commit message format:** `feat(area): description (#N)`. Include
+  the issue number when one exists.
+- **Squash merge only.** Multiple commits on the branch are fine; the
+  merge collapses them.
+---
+## When this document changes
+A change to `CONVENTIONS.md` should be:
+1. Reviewed in a PR by you (or by an agent that's been told the
+   change is intentional).
+2. Accompanied by a short rationale in the PR body — what changed,
+   what motivated it, what's now different in practice.
+3. Reflected in any related rule under `.claude/rules/` if the
+   change implies an enforcement adjustment.
+If you find an existing convention conflicts with how the code is
+actually written: stop and decide which is correct before unifying.
+The fix might be the convention, the code, or both.