create-ailk 0.6.1 → 0.8.0

package/templates/.claude/skills/fill-page/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: fill-page
+description: Fill one existing page's section content from a category profile. Tier 1 writes realistic, labelled sample content for the category (a plumber's home page, say). Tier 2 asks the owner the profile's questions and writes the company's own first draft from their answers and `_site.mdx`. Use when the user says "fill this page", "fill the home page for a plumber", "write sample content for my services page", or "write my real copy from what I tell you". It never creates a page, never changes a page's section stack, and never edits `_site.mdx`.
+---
+
+# fill-page
+
+Replace one page's `{brace}` instructions with content, reading the
+content from a **category profile** (`profiles/<slug>.yaml` beside this
+file). A profile is the data for one business type: the schema.org
+subtype, the typical offerings, the proof buyers expect, the buyer's own
+words, and the questions to ask the owner.
+
+Two tiers:
+
+| Tier | Source                                                   | Result                                     | `placeholder` |
+| ---- | -------------------------------------------------------- | ------------------------------------------ | ------------- |
+| 1    | the profile                                              | realistic sample content for the category  | `true`        |
+| 2    | `_site.mdx` + the owner's answers (`content/_intake.yaml`) | the company's own first draft              | by the rule in Step 2.4 |
+
+`placeholder: true` in a page's frontmatter makes the site render a
+**PLACEHOLDER — REPLACE BEFORE LAUNCH** label at the top of the page.
+The label is for people. Structured data reaches agents without it, so
+tier-1 content must be safe to publish by itself (see the never-invent
+list).
+
+## Inputs
+
+- **The page file** — `content/<locale>/<Type>/<slug>.mdx`. It must
+  already exist; `add-page` creates pages.
+- **The page type** — the frontmatter `type`.
+- **The profile slug** — a file under `profiles/` (e.g. `plumbing`).
+  Ask if the user did not name one. If there is no profile for their
+  category, say so and stop.
+- **The tier** — 1 unless the user asks for their own copy.
+
+## What never changes
+
+- The page's **section stack**: every section's `id` and `type`, in
+  order. Never add, remove or reorder a section. The starter's manifest
+  records each page's sections, and a changed stack fails its check.
+- Each section's **layout options** that are already present:
+  `variant`, `columns`, `layout`, `initialOpen`, `size` and the like.
+  They are the site's locked look.
+- Link targets (`href`) that are already present, except a link to a
+  Service page, which follows that page's slug (Step 1.3).
+- `{/* … */}` comments in the MDX body.
+- `_site.mdx`. Identity strings (the company name) are read from it,
+  never written to it.
+
+## Never invent (tier 1)
+
+At tier 1, write none of these. Remove any you find in the page:
+
+- `price`, `priceCurrency`, `availability` or `stripe` — each feeds the
+  schema.org `Offer` an agent quotes as the company's price.
+- A person's name or another company's name.
+- A phone number, a street address, or a licence or registration number.
+- A town, a county, or a distance: the service area is a company fact.
+- Testimonials: `author` is the literal `Sample customer`; no `company`,
+  `rating` or `avatar`.
+- Statistics a reader would take as measured (a count of jobs, a years
+  figure). Use the profile's `proof[]` labels as words, not numbers.
+
+The company name is the one identity string tier 1 may write, and it
+comes from `_site.mdx` `siteIdentity.name`.
+
+## Step 0 — Read
+
+1. Read the profile: `profiles/<slug>.yaml`.
+2. Read `content/_site.mdx` for `siteIdentity.name`.
+3. Read the page file. Note its stack (`sections[].type` in order).
+4. For each section type in the stack, read its data schema: the
+   `<Type>SectionDataSchema` (or `<Type>DataSchema`) export in the
+   installed `@working-theory/validation`'s `schemas/page-sections`. Fill
+   only fields the schema declares. Every field a section renders from
+   copy gets content; a field the source page did not use stays unused.
+5. Find the route that renders this page type under `apps/web/app/[locale]/`
+   and read its `bodyMode`. When it is `"mdx-body"`, the MDX body is
+   rendered and must be filled too. Otherwise the body is a short note,
+   and you rewrite it as one plain sentence that names no braces.
+
+`references/section-sources.md` maps each section type to the profile
+fields and intake answers that fill it.
+
+## Step 1 — Tier 1: sample content
+
+1. **Sections.** For each section, in place, write every copy field from
+   the profile using `references/section-sources.md`:
+   - offerings → `items` entries (`title` = the offering `name`,
+     `description` = its `job`, `link.href` = `/services/<kebab name>`);
+   - vocabulary → headlines, eyebrows and FAQ questions (the buyer's own
+     words: the `problem` list for what went wrong, `outcome` for what
+     they get);
+   - proof → `stats` labels and `testimonials` quotes, under the
+     never-invent list.
+   Keep `id`, `type` and every layout option.
+2. **Frontmatter.** Rewrite `title` and `description` without braces.
+   Use the company name from `_site.mdx` where the page names the
+   company. On a page that carries `provider.name`, set it to the company
+   name. Drop `schema.areaServed`; set `schema.serviceType` to the
+   offering name. Remove every key the never-invent list names.
+3. **Service pages.** A `Service` page is one offering. The user names
+   the offering, or you take the first profile offering that no other
+   Service page carries yet. Set `title` and `schema.serviceType` to the
+   offering `name`, and `slug` and the file name to its name in kebab
+   case (`Drain clearing` → `drain-clearing`): rename the file, never
+   copy it. To give every offering a page, the user first adds one
+   Service page per offering (`add-page`, or a copy of an existing one),
+   then runs this skill on each.
+4. **Body.** When the route renders `mdx-body`, rewrite each paragraph
+   and list item under the page's existing headings in the category's
+   words. Keep the headings, keep the order, keep the comments. Drop
+   every `\{…\}` instruction. Under a price heading, say how the job is
+   priced (the offering's `pricing`: `quote`, `fixed`, `hourly`,
+   `subscription`) in words, with no figure.
+5. **Label.** Set `placeholder: true` in the frontmatter.
+6. **Check** (below).
+
+## Step 2 — Tier 2: the company's own draft
+
+1. **Ask.** Ask each `intake[]` question from the profile, in order, one
+   at a time. Record the answers in `content/_intake.yaml`:
+
+   ```yaml
+   answers:
+     offerings: [Drain clearing, Emergency call-out]
+     service_area: "…"
+     faq: null # unanswered
+   ```
+
+   A list answer stays a list. An unanswered or skipped question is
+   `null`. Offerings are named exactly as the profile names them.
+2. **Fill.** Fill the page as in Step 1, but from `_site.mdx` and the
+   answers first; the profile fills only what the answers leave open.
+   - A profile offering the owner does not offer appears on no page:
+     remove its `items` entries, and ask before deleting its Service
+     page (the one file this skill may delete).
+   - A price appears only when the owner gave one, with `priceCurrency`.
+   - The company name appears in each page's frontmatter (`title` or
+     `description`), and the service area in the home hero when given.
+   - A section whose sources have no answer keeps its tier-1 sample
+     content.
+3. **Never invent** still holds for everything the owner did not give.
+   Testimonials stay `Sample customer` unless the owner supplies a
+   customer's name with permission to publish it.
+4. **Label.** Set `placeholder: false` only when every section is filled
+   from company facts:
+   - every section type in the stack appears in the `fills` of at least
+     one intake item whose answer is not empty, and
+   - when the stack has a `hero` or `cta`, `_site.mdx` has
+     `siteIdentity.name`.
+
+   A page with no sections is judged on its body: a `Service` page is
+   cleared only when the `offerings` answer names its offering; any
+   other page with no sections keeps `placeholder: true`. In every other
+   case, keep `placeholder: true`.
+5. **Check** (below).
+
+## The check
+
+Run the site's own structured-data check. It reads every content page
+through the same frontmatter and section schemas the site renders with,
+and validates each page's JSON-LD:
+
+```bash
+pnpm --filter web test -- lib/__tests__/structured-data.test.tsx
+```
+
+Then search the filled file for a `{` or `}` in any frontmatter string or
+in the body outside `{/* … */}` comments. Fix everything either reports
+and run both again. Stop only when both are clean.
+
+## What this skill does not do
+
+- Tier 3 (the Messaging Canvas through the content pipeline).
+- Create a page — use `add-page`.
+- Edit `_site.mdx`, the nav or the page roster. A profile's `roster` and
+  `nav` entries are declared for a later step and are not applied here.
+- Write a price, a name or an address the owner did not give.

package/templates/.claude/skills/fill-page/profiles/plumbing.yaml

@@ -0,0 +1,80 @@
+# Category profile — Local Plumbing (#6640; starter-template contract § D).
+# Read by the `fill-page` skill: tier 1 fills a page with labelled sample
+# content from this file; tier 2 asks `intake[]` and fills from the answers.
+# Twin: templates/.claude/skills/fill-page/profiles/plumbing.yaml (byte-identical).
+slug: plumbing
+shape: local-business-service
+subtype: Plumber
+secondary: Person
+offerings:
+  - name: Drain clearing
+    job: Clears blocked sinks, showers, toilets and main drains, and says what caused the blockage.
+    pricing: quote
+  - name: Water heater installation
+    job: Removes the old tank or boiler and fits, tests and registers a new water heater.
+    pricing: fixed
+  - name: Emergency call-out
+    job: A plumber at the door the same day for a burst pipe, a flood or no water at all.
+    pricing: hourly
+  - name: Leak detection and repair
+    job: Finds the hidden leak behind a wall or under a floor and fixes it with the least damage.
+    pricing: quote
+proof:
+  - kind: credential
+    label: Licensed and insured
+  - kind: reviews
+    label: Reviews from local customers
+  - kind: response-time
+    label: Same-day response on emergency calls
+  - kind: guarantee
+    label: Workmanship guaranteed
+vocabulary:
+  problem:
+    - burst pipe
+    - blocked drain
+    - no hot water
+    - leaking tap
+    - low water pressure
+    - water stain on the ceiling
+  service:
+    - drain clearing
+    - water heater install
+    - emergency call-out
+    - leak repair
+    - pipe replacement
+  outcome:
+    - same-day fix
+    - hot water back on
+    - no water damage
+    - upfront quote
+    - tidy job, nothing left behind
+roster:
+  - op: add
+    route: /emergency
+    pageType: BookCall
+    reason: Emergency jobs book a call, not a form.
+  - op: drop
+    route: /pricing
+    reason: Most plumbing work is quote-priced, so a price table misleads.
+nav:
+  Services: Plumbing services
+content_posture: sample
+intake:
+  - id: offerings
+    ask: Which of these jobs do you take on, and is there one you do not list? (Drain clearing, water heater installation, emergency call-out, leak detection and repair.)
+    fills: [hero, items]
+  - id: service_area
+    ask: Which towns, postcodes or radius do you cover?
+    fills: [hero, cta]
+  - id: about
+    ask: How did the business start, who does the work, and what will you not take on?
+    fills: [content-block]
+  - id: proof
+    ask: What can a customer check — your licence, your insurance, your reviews, your response time, your guarantee?
+    fills: [stats, testimonials, social-proof]
+  - id: faq
+    ask: What do customers ask before they book, and what do you tell them?
+    fills: [faq]
+  - id: contact
+    ask: How should a customer reach you — phone, form or booking — and how fast do you reply?
+    fills: [cta]

package/templates/.claude/skills/fill-page/references/section-sources.md

@@ -0,0 +1,41 @@
+# Section sources
+
+Where each section's copy comes from. **Profile** is tier 1's source;
+**Intake** lists the `intake[]` answers that fill the section at tier 2
+(the same ids appear in each question's `fills`). Fields not named here
+are layout options: keep them as they are.
+
+| Section type    | Copy fields                                                                 | Profile (tier 1)                                                                                                 | Intake (tier 2)                          |
+| --------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `hero`          | `eyebrow`, `headline`, `subheadline`, `primaryCta.label`, `secondaryCta.label` | `vocabulary.problem` + `vocabulary.outcome` for the headline; the category name for the eyebrow                 | `offerings`, `service_area`              |
+| `items`         | `headline`, `description`, `items[].title`, `items[].description`, `items[].link` | one item per `offerings[]` entry: `title` = `name`, `description` = `job`, `link.href` = `/services/<kebab name>` | `offerings`                              |
+| `cta`           | `headline`, `description`, `primaryCta.label`, `secondaryCta.label`         | `vocabulary.outcome`                                                                                             | `service_area`, `contact`                |
+| `content-block` | `eyebrow`, `headline`, `body`                                               | `proof[].label` and `vocabulary.service`, with no names, places or numbers                                        | `about`                                  |
+| `faq`           | `headline`, `items[].question`, `items[].answer`                            | questions in `vocabulary.problem` words; answers from `offerings[].pricing` and `proof[]`                        | `faq`                                    |
+| `stats`         | `headline`, `items[].label`, `items[].value`                                | `proof[].label` as the label; a value only when it is not a measurement (e.g. `Same day`)                        | `proof`                                  |
+| `testimonials`  | `headline`, `items[].quote`, `items[].author`                               | quotes in `vocabulary.outcome` words; `author: Sample customer`; no `company`, `rating` or `avatar`              | `proof`                                  |
+| `social-proof`  | `headline`, labels                                                          | `proof[].label`                                                                                                  | `proof`                                  |
+
+A section type not in this table: fill its copy fields from the profile's
+`vocabulary` and leave its data otherwise as it was. At tier 2 no intake
+answer fills it, so a page carrying it keeps `placeholder: true`.
+
+## Frontmatter
+
+| Key                    | Tier 1                                             | Tier 2                                      |
+| ---------------------- | -------------------------------------------------- | ------------------------------------------- |
+| `title`, `description` | the category's words; the company name from `_site.mdx` where the page names the company | the company name and the owner's answers    |
+| `provider.name`        | `siteIdentity.name`                                | `siteIdentity.name`                         |
+| `schema.serviceType`   | the offering `name`                                | the offering `name`                         |
+| `schema.areaServed`    | removed                                            | the `service_area` answer                   |
+| `price`, `priceCurrency`, `availability`, `stripe` | removed                | only a price the owner gave, with its currency |
+| `placeholder`          | `true`                                             | by the rule in `SKILL.md` Step 2.4           |
+
+## Pricing words (Service bodies, FAQ answers)
+
+| `pricing`      | Say                                                                 |
+| -------------- | ------------------------------------------------------------------- |
+| `quote`        | priced after a look at the job; the quote is given before work starts |
+| `fixed`        | one fixed price for the job, agreed before work starts               |
+| `hourly`       | charged by the hour on site, with the call-out rate stated up front  |
+| `subscription` | a regular plan, billed on a schedule                                 |

package/templates/.claude/skills/setup-database/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: setup-database
+description: Take this site from no database to a working lead inbox — provision Postgres, set the connection variables, create the tables, pin the owner, and prove it with one test message that must appear in the inbox. Use when the user asks "set up the database", "I want a lead inbox", "keep my leads", "collect newsletter signups", "connect Postgres", or when setup-deploy points here. Confirms before every write and never prints a connection string.
+---
+
+# setup-database
+
+A new site needs no database: contact-form messages are emailed to the
+owner (when the email key is set). A database turns on the **lead inbox**
+— every message kept at `/leads`, reviewed signed in — and newsletter
+signups. This skill takes the site from no database to that inbox, and
+does not call it done until one test message is in it.
+
+## When to use
+
+- "set up the database" / "connect Postgres"
+- "I want a lead inbox" / "keep every message"
+- "collect newsletter signups"
+- `setup-deploy` pointed here from its lead-delivery step
+
+Skip it when the site only needs messages by email — that is
+`setup-deploy`'s email key, no database required.
+
+## Rules for every step
+
+- **Confirm before every write.** Say what file or command is next and
+  wait for a yes.
+- **Never echo a connection string.** A database URL contains a
+  password. Refer to it as "your `DATABASE_URL`", never print it, never
+  commit it. It goes in `.env.local` (gitignored) and the hosting
+  dashboards only.
+- **Stop on the first failure** and say which step failed and why
+  (see "When a step fails"). Never skip ahead.
+
+## The mechanic
+
+### Step 1 — Detect
+
+Look for `DATABASE_URL` in `.env.local`, then `.env`. If it is already
+set, say so (without printing it) and go to Step 4.
+
+### Step 2 — Provision Postgres
+
+Ask which Postgres the owner wants. Any provider that gives a **pooled**
+and a **direct** connection URL works (Neon, Supabase, Railway, RDS, …).
+For local work, the one command in `README.md` § "When you need a
+database":
+
+```bash
+docker run --name ailk-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:17
+```
+
+The owner pastes the two URLs. Write them to `.env.local` only:
+
+```bash
+DATABASE_URL=<pooled URL>
+DATABASE_URL_NON_POOLED=<direct URL>
+```
+
+(Local Docker: the same URL for both.) Then tell the owner to add the
+same two variables to **both** hosting projects — the API's (it stores
+the leads) and the web app's (sign-in reads the database). Placeholders
+only in any file you show; the real values go in each dashboard.
+
+### Step 3 — Create the tables, then the default workspace
+
+```bash
+pnpm db:migrate:deploy
+```
+
+```bash
+pnpm db:seed
+```
+
+The seed creates the default Organization and Workspace every lead is
+filed under. Without it the API answers `503 tenant_unresolved` to every
+submission.
+
+### Step 4 — Pin the owner, and make sure they can sign in
+
+The inbox shows leads only to the site's pinned owner. Ask for the
+email address the owner signs in with and set it — in `.env.local`, and
+on the API project's dashboard:
+
+```bash
+AILK_OPERATOR_EMAIL=you@your-domain.com
+```
+
+The owner must sign in with that address, and it must be verified by
+the sign-in provider. If no sign-in provider is configured yet, hand off
+to the `add-auth` skill now — the inbox is behind sign-in — and come
+back to Step 5 when it is done.
+
+### Step 5 — Send one test message
+
+Make a nonce (for example `setup-database 3f9c2a`, a few random
+characters) and submit a lead to the running API (`pnpm dev` locally,
+or the deployed API's URL):
+
+```bash
+curl -sS -X POST <api>/v1/leads/submit \
+  -H 'content-type: application/json' \
+  -d '{"source":"web","email":"<owner email>","payload":{"name":"setup-database test","message":"<nonce>"}}'
+```
+
+It must answer **`201`** with `"persisted": "db"`. Anything else is a
+failed step (see below).
+
+### Step 6 — Verify it is in the inbox
+
+Build the database package once (its `./tenancy` export resolves to
+`dist/`), then read the inbox with the inbox's own rule — the default
+workspace, newest first, the first page of 50:
+
+```bash
+pnpm --filter @working-theory/database build
+pnpm --filter @working-theory/database exec tsx ../.claude/skills/setup-database/scripts/verify-inbox.ts "<nonce>"
+```
+
+It prints `found in inbox` and exits 0 only when the test lead is on
+that page. Then ask the owner to open `/leads`, signed in as the pinned
+email, and confirm they see the "setup-database test" row.
+
+Do not report the database as set up until verify-inbox.ts exits 0.
+
+## When a step fails
+
+Say which step failed and the likely cause — never "done":
+
+| Symptom                                     | Likely cause                                                                                   |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `db:migrate:deploy` cannot connect          | wrong `DATABASE_URL_NON_POOLED`, or the database is not reachable from here                    |
+| submit answers `503 tenant_unresolved` (or, with `CONTENT_ADAPTER=database`, the API refuses to start) | Step 3's `pnpm db:seed` did not run |
+| submit answers `201` with `persisted` ≠ `db` | the API process does not see `DATABASE_URL` — restart it, or set it on the API project        |
+| verify-inbox exits 1                        | the lead landed under another workspace, or 50 newer leads push it off the first page          |
+| `/leads` is empty but verify passed         | `AILK_OPERATOR_EMAIL` unset, a different or unverified sign-in email, or more than one workspace |
+
+## What this skill does not do
+
+- Call a database vendor's API. The owner provisions; the skill walks
+  them through it.
+- Print, log or commit a connection string.
+- Change application code. The API switches to the inbox by itself once
+  `DATABASE_URL` is set.
+
+## Coordination
+
+- **`setup-deploy`** — its lead-delivery step points here, and its
+  `RUNBOOK.md` names this skill as the **Lead inbox** path.
+- **`add-auth`** — the inbox is behind sign-in; Step 4 hands off to it
+  when no provider is configured.
+
+## Files
+
+- `scripts/verify-inbox.ts` — Step 6's read. Exports `findInInbox`
+  (pure, takes an injected Prisma-shaped client) and a thin `main()`.

package/templates/.claude/skills/setup-database/scripts/verify-inbox.ts

@@ -0,0 +1,154 @@
+/**
+ * verify-inbox — the last step of the `setup-database` skill.
+ *
+ * Proves the test lead the skill just submitted is in the lead inbox, by
+ * reading with the inbox's own predicate: `Lead.siteId` = the default
+ * workspace id, newest first, the first page of 50 — exactly what `/leads`
+ * shows. A lead that exists somewhere else in the table does not count.
+ *
+ * Run inside the scaffold's `database` workspace, which owns the Prisma client
+ * and its driver adapter. The script's own imports resolve from the WORKING
+ * directory (`resolveFromWorkspace`), not from where this file sits — the
+ * scaffold root depends on neither package. Build it first — the `./tenancy`
+ * export resolves to `dist/`:
+ *
+ *   pnpm --filter @working-theory/database build
+ *   pnpm --filter @working-theory/database exec tsx ../.claude/skills/setup-database/scripts/verify-inbox.ts <nonce>
+ *
+ * Exit 0, printing `found in inbox`, only when the nonce's lead is on that
+ * page. Exit 1 when it is not; exit 2 on a usage error. Reads only — writes
+ * nothing, and prints no lead field but the match.
+ */
+
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Import `specifier` as the package at `cwd` sees it. A bare `import()` here
+ * would resolve from this file's own directory (`.claude/skills/…`), where
+ * the scaffold installs neither `@working-theory/database` nor its adapter;
+ * resolving against `<cwd>/package.json` finds the `database` workspace's own
+ * dependencies and its self-reference.
+ */
+export function resolveFromWorkspace(specifier: string, cwd: string = process.cwd()): string {
+  return createRequire(join(cwd, "package.json")).resolve(specifier);
+}
+
+async function importFromWorkspace<T>(specifier: string): Promise<T> {
+  return (await import(pathToFileURL(resolveFromWorkspace(specifier)).href)) as T;
+}
+
+/** The inbox's first page (`GET /v1/leads`'s default `limit`). */
+export const INBOX_PAGE_SIZE = 50;
+
+interface LeadRow {
+  id: string;
+  payload: unknown;
+}
+
+/** The one Prisma call this script makes — injected, so it is testable without a database. */
+export interface InboxReader {
+  lead: {
+    findMany(args: {
+      where: { siteId: string };
+      orderBy: Array<Record<string, "desc">>;
+      take: number;
+      select: { id: true; payload: true };
+    }): Promise<LeadRow[]>;
+  };
+}
+
+function carriesNonce(payload: unknown, nonce: string): boolean {
+  if (typeof payload !== "object" || payload === null) return false;
+  const message = (payload as Record<string, unknown>)["message"];
+  return typeof message === "string" && message.includes(nonce);
+}
+
+/** Whether the lead whose message carries `nonce` is on the inbox's first page. */
+export async function findInInbox(
+  db: InboxReader,
+  { workspaceId, nonce }: { workspaceId: string; nonce: string },
+): Promise<boolean> {
+  const page = await db.lead.findMany({
+    where: { siteId: workspaceId },
+    orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+    take: INBOX_PAGE_SIZE,
+    select: { id: true, payload: true },
+  });
+  return page.some((row) => carriesNonce(row.payload, nonce));
+}
+
+/** `findInInbox` as a process result: 0 + `found in inbox`, or 1 + the reason. */
+export async function verifyInbox(
+  db: InboxReader,
+  args: { workspaceId: string; nonce: string },
+  out: (line: string) => void = (line) => process.stdout.write(`${line}\n`),
+): Promise<0 | 1> {
+  if (await findInInbox(db, args)) {
+    out("found in inbox");
+    return 0;
+  }
+  out(
+    "not in inbox: no lead carrying this nonce is on the default workspace's first page. " +
+      "Check that `pnpm db:seed` ran (else the API answers tenant_unresolved) and that " +
+      "the test submission returned 201 with persisted \"db\".",
+  );
+  return 1;
+}
+
+async function main(argv: string[]): Promise<number> {
+  const nonce = argv[0];
+  if (!nonce) {
+    process.stderr.write("usage: verify-inbox.ts <nonce>\n");
+    return 2;
+  }
+  // DATABASE_URL lives in the scaffold root's `.env.local` (setup-database
+  // writes it there); this runs from `database/`, one level down.
+  for (const file of ["../.env.local", "../.env"]) {
+    if (process.env.DATABASE_URL) break;
+    try {
+      process.loadEnvFile(file);
+    } catch {
+      // absent — try the next one
+    }
+  }
+  if (!process.env.DATABASE_URL) {
+    process.stderr.write("verify-inbox: DATABASE_URL is not set (.env.local)\n");
+    return 1;
+  }
+  // Resolved inside the scaffold's `database` workspace (see the header).
+  // Prisma 7 needs an explicit driver adapter, as `database/seed.ts` does.
+  const [{ PrismaClient }, { PrismaPg }, { DEFAULT_WORKSPACE_ID }] = await Promise.all([
+    importFromWorkspace<{
+      PrismaClient: new (opts: { adapter: unknown }) => InboxReader & {
+        $disconnect(): Promise<void>;
+      };
+    }>("@working-theory/database"),
+    importFromWorkspace<{ PrismaPg: new (opts: { connectionString: string }) => unknown }>(
+      "@prisma/adapter-pg",
+    ),
+    importFromWorkspace<{ DEFAULT_WORKSPACE_ID: string }>("@working-theory/database/tenancy"),
+  ]);
+  const prisma = new PrismaClient({
+    adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
+  });
+  try {
+    return await verifyInbox(prisma, {
+      workspaceId: DEFAULT_WORKSPACE_ID,
+      nonce,
+    });
+  } finally {
+    await prisma.$disconnect();
+  }
+}
+
+if (/verify-inbox\.ts$/.test(process.argv[1] ?? "")) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err: unknown) => {
+      process.stderr.write(`verify-inbox: ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    },
+  );
+}