create-ailk 0.4.0 → 0.6.0

package/templates/apps/api/.env.example

@@ -57,6 +57,19 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # Provider selector. Only "cal" is implemented today; the self-hosted engine
 # (#4288) lands as a second value here with no change to the section.
 # SCHEDULING_PROVIDER=cal
+#
+# The booking webhook receiver (#6085) — a SEPARATE credential from the
+# three above: it verifies POST /v1/webhooks/calcom's x-cal-signature-256
+# header, it does not call the provider. Unset makes the receiver answer 503
+# and accept nothing (the same fail-closed posture STRIPE_WEBHOOK_SECRET
+# unset already has) — every booking is then silently lost, so this must be
+# set for the receiver to do anything.
+# CAL_WEBHOOK_SECRET=
+# GET /v1/schedule/appointments only returns rows where this deployment's
+# AILK_SITE_ID (declared below, under "Project listings — site addressing")
+# equals the caller's own workspace id: the receiver writes under
+# AILK_SITE_ID, the read scopes to the tenant's workspace, and a mismatch
+# fails EMPTY, never wide.
 
 # =============================================================================
 # Paid modules (D-44, #5368)

package/templates/apps/api/CLAUDE.md

@@ -37,16 +37,27 @@ Every endpoint here has a 1:1 MCP tool in `apps/mcp`. When you add, change, or r
 Routes are versioned under `/v1/*`:
 
 - `/v1/leads/{submit,subscribe,callback}` — lead capture, newsletter subscription, callback request
+- `/v1/leads` (GET, `?cursor=&limit=`) — the leads INBOX read (#5678): the caller's OWN sites' leads, newest first, cursor-paginated (`limit` defaults to 50, max 200; `(createdAt desc, id desc)`; `cursor` is the previous page's last row id, and one that does not resolve within the caller's scope is a 400, never a silent page 1 — the API keeps that contract, and the web inbox deliberately softens it on its own side by re-reading page one when a URL-supplied cursor 400s, which is a rendering choice and not a change to this response). Five fields per row and nothing more — `id`, `name` (lifted from `payload.name` when the site's form captured one), `email`, `source`, `createdAt`; `payload`'s other keys, `siteId`, `promotedUserId` and `promotedAt` are never selected (`src/services/leads-inbox.ts` is the only read path). Registered in `authScope` only (auth, no tenant guard) and — alone in that scope — **unconditionally**, with no `isModuleEnabled()` gate: lead capture is a never-gate surface at every level, so reading a lead back cannot be gated either. Identity is `request.userId`; there is no site, org or workspace parameter, so the scope cannot be widened from the wire. It is resolved from the caller's own memberships by `src/services/owner-workspaces.ts`'s `resolveOwnerWorkspaces` — the ONE site→workspace resolution in this app, shared with `lead-promotion.ts` rather than written a second time — and every read filters `siteId ∈ workspaceIds`. Role floor `owner|admin` (contact PII), the same floor and the same reason as `/v1/waitlist-experiments/*`; the scope is the UNION of every workspace the caller owns or administers, not one active tenant, because this route registers outside the tenant scope. **Two deployment preconditions decide whether it returns anything, and both fail EMPTY rather than wide:** a build with no `multi-tenant` module resolves no workspaces (a deliberate scope limit since #5677, not an absence of anything to resolve), and the `siteId` the leads were WRITTEN under must equal a workspace id. That `siteId` has TWO sources, and `currentSiteId()` is not the one on the primary path: the three POST capture routes read it from the REQUEST BODY (`routes/leads/index.ts`), which the capture sections declare in content and default to `"default"` (`ContactForm`/`Newsletter`/`StepFlow`, `ext.siteId ?? "default"`), while the recommender's capture path (`routes/flows/recommender.ts`) is the one that uses `currentSiteId()` (`lib/site.ts`, `AILK_SITE_ID ?? "default"`). A workspace id is `wksp_<uuidv7>`, so `siteId ∈ workspaceIds` matches only when the content-declared value — and, for recommender leads, `AILK_SITE_ID` — is set to it (the same convention `waitlist-dashboard.ts` already relies on). The rendered `name` is lifted from `payload.name` and truncated at 200 characters: the write side bounds `payload` at 64 keys and no per-value length, and `POST /v1/leads/submit` is anonymous with no ownership check on `siteId`. No MCP twin — identity-bound (#3591 exception, the same shape as `/v1/workspaces/*` and `/v1/billing/*`).
 - `/v1/flows/:slug` (GET), `/v1/flows/:slug/steps` (POST) — serve a flow config + submit a step's answers; server-side per-step partial-state persistence (#3956). Module: `signal-collectors` (D-48, #5366) — registers only when the module is enabled; MCP twins `get_flow`/`submit_flow_step` carry the same `module` tag (D7).
 - `/v1/flows/:slug/aggregate` (GET) — anonymous, site-scoped per-question response counts across all completed respondents for the results reveal (#4771): respondents are completed `FlowSession` rows (not `Lead` rows — a recommending-mode respondent has no Lead until the email moment), question metadata + the chart flag come from the `WaitlistExperiment` register, and only `resultsReveal`-flagged `single`/`multi` questions are returned (`src/services/flow-aggregate.ts`). No individual answer, email, name, session id, or score in the response; no auth. Module: `signal-collectors`. No MCP twin — recorded exception (an agent walking a flow already gets everything it needs from `submit_flow_step`'s own response; "how everyone else answered" changes none of it).
-- `/v1/deliverables/:grantId` (GET) — the capability-token download route for gated PDFs and reports, including client deliverables (#3961 D5); the token itself is the sole gate, no auth preHandler applies (`src/routes/deliverables/index.ts`). Module: `signal-collectors` (D-48, #5366). No MCP twin — identity-bound capability-link download (#3591 exception, the same shape as `/v1/waitlist-signups/me`).
+- `/v1/deliverables/:grantId` (GET) — the capability-token download route for gated PDFs and reports, including client deliverables (#3961 D5); the token itself is the sole gate, no auth preHandler applies (`src/routes/deliverables/index.ts`). Module: `signal-collectors` (D-48, #5366). No MCP twin — identity-bound capability-link download (#3591 exception, the same shape as `/v1/waitlist-signups/me`). **Three grant classes since #6310**, keyed on `grant.assetId`'s ADR-0031 prefix: `playbook:` (unchanged, the FEAT-074 U4b virtual asset); `asset_` — a workspace `Asset`, resolved through the named boundary `src/lib/deliverable-asset-store.ts`, scoped by `grant.workspaceId` (a serve-time tenancy re-check restored for this class — D15) — served `attachment` with an extension pinned to the stored content type, `nosniff`, a non-raster `Content-Security-Policy` (for EVERY content type, including raster — never `inline`), and `Cache-Control: private, no-store` so a deleted asset stops downloading immediately; `dasset_` — the LEGACY `DeliverableAsset` store (unchanged, tried only when a magnet's `assetKey` does not resolve against `Asset`). Every miss on the `asset_` class — a NULL `workspaceId`, no row, a foreign-workspace row — folds into the SAME uniform 404 as every other class; there is deliberately no redirect to the public `GET /v1/assets/:assetId` (that route's year-long `immutable` cache would defeat deletion as a revocation lever, and would collapse every lead's capability onto one workspace-canonical id — spec #6310 §9 SEC-001/SEC-002).
 - `/v1/flows/:slug/save` (POST), `/v1/flows/:slug/checkout` (POST) — the recommender's email moment (#4841): `save` creates the FlowSession + Lead (+ the T+0 DeliverableGrant) for the permalink's answers; `checkout` does the same, records the `FlowCheckout` buyer row at a SERVER-recomputed `price()` (the body carries no amount — `flowCheckoutInputSchema` is strict), and opens a Stripe TEST-mode Checkout Session whose metadata carries the permalink + offer key (`src/routes/flows/recommender.ts`, `src/services/recommender-capture.ts`, `packages/stripe-client`'s `createQuotedCheckoutSession`). Anonymous, rate-limited; a non-`sk_test_` key is refused before any side effect. No MCP twin — recorded exception: an agent walking a flow has no email to give and no card to pay with; the anonymous MCP surface is identity-blind.
+- `/v1/workspaces/:workspaceId/magnets` (GET, POST), `/v1/workspaces/:workspaceId/magnets/:id` (GET, PATCH), `/v1/workspaces/:workspaceId/magnets/:id/signups` (GET), `/v1/workspaces/:workspaceId/magnets/:id/subscribers` (GET), `/v1/workspaces/:workspaceId/magnets/:id/messages` (GET) — the tenant-scoped magnet Admin authoring surface over the flow engine's `FlowDefinition` rows (#6157 S5c, `src/routes/magnets/index.ts`): list (cursor-paginated, fixed 50-row page), create, get, update, and the three per-magnet captured-lead reads (#6246 S6h). Reads and writes only through `tenantDb(tenant).flows` — never `prisma.flowDefinition`, `currentSiteId()`, or `upsertFlowDefinition` (the PUBLIC/seed path below, which the admin path never calls). No DELETE — the reversible alternative is `status: "draft"` (#6156), which stops a NEW walk from starting while an in-flight walk finishes on its pinned snapshot. `slug` lives only inside `config.slug` and is immutable through this surface after create (`400 slug_immutable` on a mismatched PATCH). The two operator-writable config URLs (`abandonEmail.resumeUrl`, `followUps[].cta.href`) pass an exact-origin gate against `FRONTEND_URL` before any write, the same discipline the recommender's checkout redirect already applies (#4912). Role floor `owner|admin` on all seven routes — a magnet's `config` carries `scoring` thresholds, `offers`/`rateTable` and `deliverables` asset keys, so no route exposes it at member level. Both writes declare a route-level `bodyLimit` (256 KiB) and each records one `recordAgentAction` audit row. Module: `multi-tenant || signal-collectors`, the same gate the review-surface dashboard (`/v1/waitlist-experiments/*`, `/v1/project-listings/*`) already registers under. No MCP twin on any of the seven — identity-bound tenant routes (#3591 exception, same shape as the sibling `/v1/workspaces/*` routes); the public `/v1/flows/*` routes and their two MCP tools are unchanged, pinned by `src/routes/flows/__tests__/parity.test.ts`. **The three new list routes (#6246 S6h)** join every magnet through `Lead.source = 'flow:' + <the resolved magnet's slug>` — the literal string `flow-engine.ts`'s `completeSubmission` stamps on every flow-engine `Lead` row regardless of kind, including `newsletter`/`waitlist` (`Subscriber` is written only by the separate, pre-flow-engine `subscribe_newsletter` path, unrelated to a magnet) — via ONE new `tenantDb(tenant).leads.listBySource(source, { limit })` accessor, an exact-source-equality sibling of #6204's allowlist-scoped `listUnhandledMessages`, served by a new `(workspaceId, source)` composite index on `Lead`. `/signups` expects `kind: "waitlist"`, `/subscribers` expects `"newsletter"`, `/messages` expects `"contact"`; a magnet id absent from the caller's workspace OR resolved to the WRONG kind for the called route is `404 not_found`, indistinguishably (mirrors the existing GET's absent-or-foreign fold). `/signups` and `/subscribers` serve four keys (`id`, `name`, `email`, `createdAt`); `/messages` serves those four plus `handledAt`. Bounded `?limit=` (default 50, max 200), newest-first — mirrors `workspaces/messages.ts`'s own query schema. Applications (Listicle) is deliberately OUT of this surface — `ProjectListing` carries no reverse link to the listicle-kind `FlowDefinition` that captured it, so "scoped to that magnet" cannot be honored without a schema change (split to #6314).
 - `/v1/content/{types,:type,:type/:slug}` — public content reads
 - `/v1/auth/tokens`, `/v1/user/{profile,data/:key}` — local auth + user data
 - `/v1/checkout/sessions` — start a Stripe checkout
 - `/v1/workspaces/:workspaceId/{theme,identity,seo}` (GET/PUT) — per-workspace site config (multi-tenant module)
+- `/v1/workspaces/:workspaceId/meetings` (GET/PUT) — the operator's enabled-slug gate for meeting types (#6183 S9b, `src/routes/workspaces/meetings.ts`). Beside the three siblings above in URL shape and tenant-isolation posture, but registered in its OWN scope, gated on `isModuleEnabled("scheduling")` ALONE — not the `workspace`/`multi-tenant` scope its siblings share, because its GET reaches `services/scheduling/` (see below), which a scaffold without that module does not carry (`tools/lint-slice-registration.ts`, #5701). Both verbs are role-floored `owner|admin` (the same floor `general.ts` puts on a rename): PUT because this blob decides which pages the public site serves, and GET because — since it does NOT just return the stored blob — it echoes the deployment's whole provider catalog, including the rows the operator chose not to publish (security review, 2026-09-19). GET is the one segment in this file's family that does NOT just return the stored blob: it ALSO lists the scheduling provider's own bookable event types (`listEventTypes`, #6182), joined with `enabled: boolean`; an unconfigured/unreachable provider answers the same `SchedulingErrorKind` outcome `/v1/schedule/*` uses, distinct from an empty list. No MCP twin — identity-bound tenant route (#3591 exception).
+- `/v1/workspaces/:workspaceId/general` (GET/PUT) — the workspace's own display name, the Pro `workspace` module's general-settings surface (#5371). Registered under `isModuleEnabled("workspace") || isModuleEnabled("multi-tenant")` alongside the site-config routes above, behind the same tenant guard; the scope is always `request.tenant.workspaceId`, never the path param (the guard 403s a mismatch before any handler runs). PUT takes a strict `{ name }` body (1–200 chars, trimmed) and both verbs answer the same `{ name }` shape. Role floor on PUT `owner|admin` (#5515 item 2) — renaming is an org-level settings write; GET stays open to every member. No MCP twin — identity-bound tenant route (#3591 exception, same shape as `/v1/billing/*`).
+- `/v1/workspaces/:workspaceId/messages` (GET, `?limit=`), `/v1/workspaces/:workspaceId/messages/:leadId` (GET, PATCH) — the Inbox message API (#6216 S7e, `src/routes/workspaces/messages.ts`): the workspace's unhandled messages newest first, the item read (resolves a message handled or not, serving `handledAt`), and the one-way idempotent handled stamp over #6204's `markMessageHandled`. Registered under `isModuleEnabled("workspace") || isModuleEnabled("multi-tenant")`, the same scope as the two routes above. A message is a `Lead` whose `source` is in #6204's closed `MESSAGE_LEAD_SOURCE_LIST` allowlist — checked only in `tenantDb(tenant).leads`, never in this file; a non-message lead is a 404 on the item read and the PATCH and absent from the list, the SAME 404 body as an absent id, another workspace's id, or an unbackfilled `workspaceId`. **One served row across all three routes** — `id`, `name`, `email`, `source`, `createdAt`, `handledAt` — and nothing else: no `payload`, no message body (operator ruling, 2026-09-19; `leads-inbox.ts`'s PII boundary is unchanged, not widened). PATCH takes `{ "handled": true }` only, `.strict()`; there is no un-handle path (#6204 D4), so `{ "handled": false }` is a 400. The stamp records the actor via `tenant.userId` in `Lead.handledBy` — written, not served. Role floor `owner|admin` (`LEAD_INBOX_ROLES`, the SAME constant `services/inbox-messages.ts`'s sibling functions already enforce), checked before any read or write — **and on a single-workspace deployment RUNNING the `multi-tenant` module with `AILK_OPERATOR_EMAIL` unset, that role is self-servable first-come** (the SAME `bindOperatorMembership` TOFU bind the `AILK_OPERATOR_EMAIL` paragraph below names, reached there via `multi-tenant`'s own null-binding fallback to `resolveDefaultTenant` — NOT via the base `workspace`-only guard, which REQUIRES the pin and fails closed when it is unset, so TOFU is unreachable on a bare `workspace`-only build: these are the first routes to serve anonymous visitors' contact PII through that grant). No MCP twin — identity-bound tenant routes (#3591 exception, the same shape as `/v1/waitlist-experiments/*` and `/v1/project-listings/index.ts`): MCP carries no caller identity today, so a twin could only invent an MCP auth story or serve whatever workspace the environment points at; the deferred ambition is #6222.
+- `/v1/workspaces/:workspaceId/members` (GET) — the org's member roster (`userId`, `name`, `email`, `role`), the Pro `workspace` module's Team tab (#5371). Read-only by design: granting a Membership is the invite flow, which is its own spec with a mandatory security review (§2.3), so no POST/PUT/DELETE is routed at this path. Scoped to `request.tenant.organizationId` — Membership is org-level — server-resolved from the validated session. Role floor `owner|admin` (#5515 item 2), the same floor and the same reason as `/v1/waitlist-experiments/*` and `/v1/leads`: the roster carries every member's email, so membership alone is not authorization. No MCP twin — identity-bound tenant route (#3591 exception).
+- `/v1/workspaces/:workspaceId/content` (GET, POST), `/v1/workspaces/:workspaceId/content/:type/:slug` (GET, PATCH), `/v1/workspaces/:workspaceId/content/:type/:slug/{publish,unpublish}` (POST) — the tenant-guarded content editor's write surface (#5853, `src/routes/workspaces/content.ts`): list, create, read/save the draft tip (under `If-Match`), and publish/unpublish, all over `Artifact`/`ArtifactVersion`. `:type` is validated against the page-type registry (`z.enum(SCHEMA_ORG_TYPES)`) rather than accepted as a free string on every addressed operation — an unregistered type is a 400 before any lookup, since it is echoed back and passed to `notifyRevalidate` as the site's cache tag. Role floor: publish and unpublish are `owner|admin` only (#5922, operator decision 2026-09-17) — publishing to, or pulling down from, a live public site is the highest-consequence action in the family, so it carries the same floor as this file's rename and roster routes above; list, create, read and save stay member-level. **The GET list is a UNION of page artifacts and DOCUMENT assets** (#6093, D1/D9 — "one store, two views"): every row carries `tags: string[]` (never null, read from the draft tip's stored content for a page, from `Asset.tags` for a file) and a DERIVED `kind: "page" | "post" | "file"` (`BlogPosting` alone maps to `"post"`; an asset row is always `"file"`) — an optional `?tag=<slug>` filters the union AFTER it is built, so a file is returned under either its own tag or a shared one. The asset half of the union (`DOCUMENT_CONTENT_TYPES`, i.e. `application/pdf`) is skipped entirely when `locale`/`type` is supplied or `status` names anything but `"published"`, since a file row can never satisfy those. A foreign `:workspaceId` costs zero artifact **and** zero asset queries. No MCP twin — identity-bound tenant routes (#3591 exception, same shape as the sibling `/v1/workspaces/*` routes).
+- `/v1/workspaces/:workspaceId/assets` (GET, POST), `/v1/workspaces/:workspaceId/assets/:assetId` (PATCH, DELETE), `/v1/assets/:assetId` (GET, public/anonymous) — the workspace asset store (#5854 upload/read; #6093 list/PATCH/DELETE, `src/routes/assets/{index,upload,read,manage}.ts`). Upload accepts an allowlisted union of three named classes (`src/routes/assets/index.ts`): five RASTER images (`image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`), one VECTOR image (`image/svg+xml`, admitted under the operator's 2026-09-18 `allow-svg-assets` ruling — issue #6093 comment `5731573595` — superseding #5854's original SVG exclusion) and one DOCUMENT type (`application/pdf`), all under the existing 20 MB cap; `?tags=<slug>[,<slug>…]` stores tags on the row. The public read serves a RASTER type `inline` exactly as before; every OTHER admitted type (SVG, PDF) is served `attachment`, with the filename's extension pinned to the stored content type (closing extension spoofing) and a five-directive `Content-Security-Policy` (`default-src 'none'; sandbox; frame-ancestors 'none'; form-action 'none'; base-uri 'none'`) that makes the bytes never a document on this origin — this is what makes admitting SVG safe with NO server-side sanitizer. `GET …/assets` (member-level — the same floor the union content list above already carries for the very same rows, D9) lists a workspace's assets, metadata only, never `bytes`, with an optional `?tag=<slug>` filter; this is what narrows the store's prior "nothing lists assets" premise to its precise form — no ANONYMOUS and no CROSS-TENANT enumeration, both still true. `PATCH …/assets/:assetId` updates `title`/`description`/`tags` (`owner|admin`; `null` clears a text field to SQL `NULL`, `""` stores empty; the asset's `id` and public URL are untouched). `DELETE …/assets/:assetId` (`owner|admin`) removes the row and the bytes at the ORIGIN only — already-cached copies elsewhere are not recallable under the year-long `immutable` promise, and no reference check protects a page that still embeds the URL; absent and foreign ids both take the same 404. Every tenant route here is identity-bound; no MCP twin (#3591 exception). The public read has no MCP twin either — it serves bytes to an `<img>`/download, the same boundary `upload.ts` records for its own sibling.
 - `/v1/billing` (GET), `/v1/billing/portal-session` (POST) — org-scoped billing read + Stripe customer-portal session creation
 - `/v1/schedule/availability` (GET), `/v1/schedule/event-meta` (GET), `/v1/schedule/book` (POST) — anonymous scheduling proxy behind the provider seam (`src/services/scheduling/`); Cal.com v2 today, a self-hosted engine later, same three calls. `event-meta` is the meta-only read (title · duration · description · price) so rendering an event's facts never fetches an availability window (#4633). `CAL_API_KEY` is read server-side only. MCP twins: `list_availability` / `get_event_meta` / `create_booking` (#4416, #4633)
+- `/v1/schedule/meeting-types` (GET) — the enabled-meeting-slugs public read (#6183 S9b, `src/routes/schedule/meeting-types.ts`): the session-less read the public `/meet` surface needs to honour the operator's enabled-slug gate (`/v1/workspaces/:workspaceId/meetings`, above), since a public page holds no session. Resolves its workspace via `resolvePublicWorkspace()` (the same fail-closed predicate the public content read uses — no client-suppliable workspace, ever) and reads through a new named public-read boundary, `src/lib/public-meetings-config.ts` (modelled on `lib/asset-store.ts`): one `findUnique` by the resolved `workspaceId`, no write, no list. `{ slugs: string[] | null }` — `null` means "no stored list" (an unconfigured deployment, or the non-database adapter); the caller (`apps/web`'s `enabledMeetingSlugs()`) applies the `SCHEDULING_CAL_LINK`-derived singleton fallback for that state, since that env var is `apps/web`'s, not this app's. Reads no client input. No MCP twin — deferred to a named follow-up rather than silently skipped (the route's own header, §10 Q3 of the spec).
+- `POST /v1/webhooks/calcom` — the scheduling booking-event receiver (#6085, brief H7): verifies the provider's HMAC-SHA256 signature (`x-cal-signature-256`) over the raw body, then normalizes one of six `BOOKING_*` trigger events into an `Appointment` row (`src/services/scheduling/appointments.ts`). `CAL_WEBHOOK_SECRET` is read server-side only (`config/index.ts`); an unset secret answers `503`, never a silent accept. Registered on the same `webhooksScope` as `/v1/webhooks/stripe` (its raw-body content-type parser is what a signed receiver needs), module-conditional (`scheduling`, `src/routes/webhooks/index.ts`). No commerce-claim read: a booking event is not a money event (D-67 puts the payment on the provider's own side). No MCP twin — an inbound receiver for one named provider, not an endpoint an agent could reasonably call, the same footing `POST /v1/webhooks/stripe` already takes.
+- `/v1/schedule/appointments` (GET, `?limit=&cursor=&window=`) — the SITE's own appointments (#6085), tenant-guarded and role-floored `owner|admin` (the rows carry attendee contact PII, the same floor `/v1/leads` and `/v1/waitlist-experiments/*` carry). Registered in its OWN tenant scope, gated on `isModuleEnabled("scheduling")` alone, behind `tenantPreHandlerForBuild()` — NOT the anonymous schedule scope above (a prospect booking a call has no account). Scope is ALWAYS `request.tenant.workspaceId`, NEVER `currentSiteId()` (the receiver's own write scope) — and deliberately carries NO platform-operator escape hatch, unlike `/v1/waitlist-experiments/*`: an appointment book is a seller's customer list. `window` defaults to `upcoming`; `cursor` is the previous page's last row id, and one that does not resolve within the caller's scope is a `400`, never a silent page 1 (the `/v1/waitlist-experiments/*/signups` cursor discipline). Eight fields per row and nothing more — `id`, `startTime`, `endTime`, `title`, `attendeeName`, `attendeeEmail`, `status`, `paid`; `siteId`, `providerBookingUid`, `provider`, the three watermark columns, `paymentInitiatedAt`, `noShow`, `cancelledAt`, `createdAt` and `updatedAt` are never selected (`src/services/scheduling/appointments.ts`'s `listAppointments` is the only read path). No MCP twin — identity-bound tenant route (#3591 exception, the same shape as `/v1/waitlist-experiments/*`).
 - `/v1/aeo/score` (POST), `/v1/aeo/score/example` (GET) — anonymous instant AEO score for a respondent-supplied URL, and the bundled pre-launch example, both fed by the SSRF-guarded crawler at `@working-theory/aeo/fetch` and the pure scorer at `@working-theory/aeo` (`src/services/aeo-score.ts`, #4666). No MCP twin — recorded exception, brief D7 (exposing an arbitrary-URL crawler to anonymous agents is a security-posture decision; `apps/mcp/src/tools/audit.ts` deliberately stays same-origin-locked instead).
 - `/v1/waitlist-experiments` (GET), `/v1/waitlist-experiments/:experimentId` (GET), `/v1/waitlist-experiments/:experimentId/signups` (GET), `/v1/waitlist-experiments/:experimentId/signups/:leadId` (GET) — the operator-dashboard read API for Parallel Waitlist Validation (#4665 D7, B0): tenant-scoped list + rollup, per-waitlist comparison, paginated signups, and a signup drill-down over A1's `WaitlistExperiment` / `WaitlistScore` / `Lead` rows (`src/services/waitlist-dashboard.ts`, #4671). Role floor `owner|admin` (signup PII); the platform-operator scope (`isSentinel(organizationId) && role === "owner"`, ALSO requiring `AILK_OPERATOR_EMAIL` to be set — fail-closed, PR #4687) sees every site, an ordinary owner/admin sees only its own `siteId`. No MCP twin — identity-bound tenant routes (#3591 exception, same shape as `/v1/billing/*`).
 - `/v1/waitlist-signups/me` (GET, `?experimentKey=<slug>`) — the respondent read (#4731): a signed-in, **email-verified** user's OWN newest signup for one experiment (`experimentKey`, `waitlistKey`, `completedAt`, `tier`, `score`, `aeoScore`, `answers.q3` — seven fields, nothing more; `src/services/waitlist-signups.ts` is the only read path). Registered in `authScope` only (auth, no tenant guard — a respondent has no workspace). Identity is `request.userId`; the email is the `User`'s, never a parameter; `emailVerified !== true` → 403 `email_unverified` before any `Lead` read; no match → 404 `signup_not_found`; every read scoped to `currentSiteId()`. Module: `signal-collectors` (D-48, #5366). No MCP twin — identity-bound (#3591 exception).
@@ -55,6 +66,8 @@ Routes are versioned under `/v1/*`:
 - `/v1/project-listings/{start,submit}` (POST), `/v1/project-listings/:id` (PATCH, draft), `/v1/project-listings/public` (GET) — the anonymous founder's-application lifecycle (#4998, reshaped by #5036): draft start/patch/submit plus the public shelves read, identity-blind and rate-limited alongside the leads routes. Module: `signal-collectors`. No MCP twin — anonymous form-lifecycle routes, not agent-facing.
 - `/v1/slack/actions` (POST) — the project-listing operator decision (Slack Approve/Reject, #4999): verifies the Slack signature, applies the decision via `src/services/project-listing-decision.ts`. Module: `signal-collectors`. No MCP twin — a Slack-signed webhook, not agent-facing.
 
+**`AILK_OPERATOR_EMAIL` is REQUIRED for a `workspace`-module deployment** (#5515 item 1), exactly as it already is for the review dashboard. On a build with the `workspace` module and WITHOUT `multi-tenant`, `server.ts`'s `tenantPreHandlerForBuild()` selects the base guard (`src/middleware/default-tenant.ts` → `resolveDefaultTenantForOperator`), which fails CLOSED when the pin is unset: every `/v1/workspaces/*` route answers 403 to everyone — so the module's Admin pages (`apps/web/app/[locale]/(authed)/admin*`, renamed from `workspace` by #5637) render their shared `ForbiddenState` — and — the reason this matters — the TOFU operator bind (`services/default-tenant.ts#bindOperatorMembership`, #3631) is never reached, so the first account to load the settings page cannot seat ITSELF as the sole owner off a plain GET. With `multi-tenant` present the pin stays optional and resolution comes from the session's active workspace, unchanged. `.env.example` § Single-tenant operator pin carries the operator-facing copy; `src/middleware/__tests__/default-tenant.test.ts` § "#5515 item 1" is the objective record.
+
 The workspace site-config routes are **identity-bound tenant routes** (guarded by the tenant preHandler; the write scope is the caller's active workspace, never a body-supplied id). Like the sibling `/v1/workspaces/*` routes they have **no anonymous MCP twin** — the OSS MCP surface is identity-blind (`apps/mcp/CLAUDE.md`), so the "1:1 MCP tool" rule above does not apply to them; the tenant-scoped authed MCP surface is tracked in #3591. The `/v1/billing/*` and `/v1/waitlist-experiments/*` routes are the same shape — identity-bound tenant routes, admin/settings-facing rather than agent-facing, no MCP twin.
 
 AEO Layer 1 scoring runs both ways: locally as a CLI command (`ailk audit`, filesystem content-root input) AND behind the anonymous `/v1/aeo/score` HTTP endpoint above (external-URL input, #4666) — the CLI's content-root audit and the route's crawler-fed score are two different input paths over the same underlying scorer, not a contradiction.
@@ -143,7 +156,21 @@ sweep's own DB constraint (never a caller-side lock).
 - Don't put session state in `apps/api`. It's stateless.
 - Don't bundle `apps/api` (esbuild, rollup, webpack). Slice specifiers cannot survive it — see `## Deploy path`.
 
-Last updated: 2026-09-14 — doc-sync: signal-collectors module extraction (D-48, #5366) — added the `module: signal-collectors` note to the flows/waitlist-signups-me/project-listings-me endpoints, added the previously-undocumented `/v1/deliverables/:grantId`, `/v1/project-listings/{start,submit,:id,public}` and `/v1/slack/actions` rows — verified against `apps/api/src/server.ts` and each route's own header.
+Last updated: 2026-09-21 — doc-sync: re-pointed magnet deliverables at the workspace-scoped `Asset` store (#6310) — extended the `/v1/deliverables/:grantId` row with the new `asset_` grant class (the named boundary it reads through, its serve-time tenancy re-check, its hardened attachment+CSP+no-store serve for every content type, and its uniform-404 fold), recording the rejected redirect-to-`/v1/assets/:assetId` mechanism and why — verified against `apps/api/src/routes/deliverables/index.ts`, `apps/api/src/lib/deliverable-asset-store.ts` and `apps/api/src/services/deliverable-fulfillment.ts`.
+
+Prior: 2026-09-19 — doc-sync: added the three per-magnet captured-lead list routes (#6246 S6h) — `GET /v1/workspaces/:workspaceId/magnets/:id/{signups,subscribers,messages}` — to the magnets bullet, recording the `Lead.source = 'flow:' + slug` join, the new `tenantDb(tenant).leads.listBySource` accessor, the new `(workspaceId, source)` index, the wrong-kind/absent-magnet shared 404, the four/five-key wire shapes, the bounded `?limit=`, and the no-MCP-twin decision — verified against `apps/api/src/routes/magnets/index.ts`, `apps/api/src/lib/tenant-db.ts` and `database/inbox/schema.prisma`.
+
+Prior: 2026-09-19 — doc-sync: added the Inbox message API (#6216 S7e) — `GET /v1/workspaces/:workspaceId/messages` and `GET`/`PATCH /v1/workspaces/:workspaceId/messages/:leadId` — to Endpoint conventions, recording the six-key served row, the message-source allowlist confinement, the shared 404 for four causes, the one-way idempotent PATCH, the `owner|admin` role floor and its TOFU precondition, and the no-MCP-twin decision — verified against `apps/api/src/routes/workspaces/messages.ts`, `apps/api/src/services/inbox-messages.ts`, `apps/api/src/lib/tenant-db.ts` and `apps/api/src/server.ts`.
+
+Prior: 2026-09-19 — doc-sync: added the tenant-scoped magnet Admin authoring surface (#6157 S5c) — `GET`/`POST /v1/workspaces/:workspaceId/magnets` and `GET`/`PATCH /v1/workspaces/:workspaceId/magnets/:id` — to Endpoint conventions, recording its `tenantDb`-only data path, its `owner|admin` role floor, the `multi-tenant || signal-collectors` gate, the config-URL origin gate and the no-MCP-twin parity decision — verified against `apps/api/src/routes/magnets/index.ts`, `apps/api/src/lib/tenant-db.ts` and `apps/api/src/server.ts`.
+
+Prior: 2026-09-19 — doc-sync: the enabled-meeting-slugs gate (#6183 S9b) — added the `/v1/workspaces/:workspaceId/meetings` bullet (its own scope, gated on `scheduling` alone, the D24 `listEventTypes` join) and the `/v1/schedule/meeting-types` bullet (the public read, its own boundary file) — verified against `apps/api/src/routes/workspaces/meetings.ts`, `apps/api/src/routes/schedule/meeting-types.ts`, `apps/api/src/lib/public-meetings-config.ts` and `apps/api/src/server.ts`.
+
+Prior: 2026-09-18 — doc-sync: the Docs list gains tags and a closed kind, and the asset store admits documents and gains list, metadata update and delete (#6093) — completed the `/v1/workspaces/:workspaceId/content` bullet with the page/asset union (`tags`, derived `kind`, `?tag=` filter), and added the `/v1/workspaces/:workspaceId/assets` + `/v1/assets/:assetId` family bullet (list/PATCH/DELETE, the widened upload allowlist admitting `image/svg+xml` and `application/pdf`, and the public read's raster-inline/non-raster-attachment+CSP serve split) — verified against `apps/api/src/routes/workspaces/content.ts`, `apps/api/src/routes/assets/{index,upload,read,manage}.ts` and `apps/api/src/lib/tenant-db.ts`.
+
+Prior: 2026-09-16 — doc-sync: added `GET /v1/leads` (#5678), the owner-scoped leads inbox read, to Endpoint conventions, recording its unconditional registration, its five-field row, its `resolveOwnerWorkspaces` scoping and its no-MCP-twin parity decision — verified against `apps/api/src/routes/leads/list.ts`, `apps/api/src/services/leads-inbox.ts`, `apps/api/src/services/owner-workspaces.ts` and `apps/api/src/server.ts`.
+
+Prior: 2026-09-14 — doc-sync: signal-collectors module extraction (D-48, #5366) — added the `module: signal-collectors` note to the flows/waitlist-signups-me/project-listings-me endpoints, added the previously-undocumented `/v1/deliverables/:grantId`, `/v1/project-listings/{start,submit,:id,public}` and `/v1/slack/actions` rows — verified against `apps/api/src/server.ts` and each route's own header.
 
 Prior: 2026-09-12 — doc-sync: added the `## Deploy path` section and the matching `## What NOT to do` line (#5334), recording that bundling `apps/api` is not a supported deploy path and naming the three gates — verified against `apps/api/vercel.json`, `apps/api/src/lib/slice-load.ts` and `scripts/check-bundled-build-diagnoses.ts`.
 

package/templates/apps/api/eslint.config.mjs

@@ -0,0 +1,69 @@
+// Self-contained ESLint flat config for this scaffolded package.
+//
+// It deliberately does NOT depend on @working-theory/eslint-config — that
+// package is internal to the AI Launch Kit monorepo and is not published, so
+// it cannot be a dependency of a scaffolded starter. Everything below comes
+// from public npm packages already pinned as devDependencies (see
+// package.json): @eslint/js, globals and typescript-eslint.
+//
+// Source file name (#5556): this file is checked in as `_eslint.config.mjs`,
+// not `eslint.config.mjs` — build-templates.mjs renames it at snapshot time
+// (renameScaffoldLintConfigs()). A file literally named `eslint.config.mjs`
+// anywhere under this monorepo (even one this repo's own root eslint.config.ts
+// lists in its `ignores`) is auto-discovered by ESLint's flat-config nested
+// resolution as a competing config root, which breaks the monorepo's own
+// lint runs (verified live: typescript-eslint's "multiple candidate
+// TSConfigRootDirs" parser error across unrelated packages/create-ailk
+// files). The underscore prefix keeps it invisible to that discovery while
+// it lives in this checkout; only the snapshot in templates/ — which ships
+// to the customer, not this repo — gets the real filename.
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: [
+      "**/.next/**",
+      "**/dist/**",
+      "**/generated/**",
+      "**/node_modules/**",
+    ],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.browser,
+        ...globals.jest,
+      },
+      // Explicit, self-contained root — this scaffold config is never meant
+      // to combine with any sibling scaffold package's config (each ships
+      // standalone), and leaving it unset makes typescript-eslint's
+      // candidate-root disambiguation ambiguous the moment more than one
+      // scaffold package's config resolves in the same ESLint process (e.g.
+      // this monorepo's own `templates/` build, where all four exist
+      // side by side; a real customer scaffold never has that problem,
+      // since it only ever ships and lints ONE of these four at a time).
+      parserOptions: {
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Downgraded rather than off, so both stay visible without failing a
+      // fresh scaffold's lint:
+      //   - unused-vars: most of the source follows the underscore-prefix
+      //     convention for intentionally-unused bindings, which this rule's
+      //     default options don't recognize; a handful of test fixtures also
+      //     carry genuinely-unused locals this minimal config doesn't try to
+      //     triage file-by-file.
+      //   - require-imports: CommonJS require() is the correct form in Jest
+      //     config/mock files and in a few test-only dynamic re-require
+      //     patterns.
+      "@typescript-eslint/no-unused-vars": "warn",
+      "@typescript-eslint/no-require-imports": "warn",
+    },
+  },
+);

package/templates/apps/api/jest.config.cjs

@@ -56,6 +56,9 @@ module.exports = {
     '^@working-theory/license$': '<rootDir>/../../packages/license/src/index.ts',
     '^@working-theory/observability$': '<rootDir>/../../packages/observability/src/index.ts',
     '^@working-theory/schema/faq$': '<rootDir>/../../packages/schema/src/faq.ts',
+    // #5830 — see the `/faq` line above: source, not the ESM `dist/`.
+    '^@working-theory/schema/categories$':
+      '<rootDir>/../../packages/schema/src/categories.ts',
     '^@working-theory/schema$': '<rootDir>/../../packages/schema/src/index.ts',
     '^@working-theory/site-config/schema$': '<rootDir>/../../packages/site-config/src/schema/index.ts',
     '^@working-theory/schema-pack-registry$': '<rootDir>/../../packages/schema-pack-registry/src/index.ts',

package/templates/apps/api/package.json

@@ -20,7 +20,7 @@
     "smoke:dev": "node -e \"const{spawn}=require('child_process');const http=require('http');const PORT=process.env.PORT||'3002';const SLUG=process.env.SMOKE_FLOW_SLUG||'smoke-check';const child=spawn('pnpm',['exec','tsx','watch','src/cli.ts'],{env:process.env,stdio:'ignore'});let done=false;function finish(code){if(done)return;done=true;try{child.kill();}catch(e){}process.exit(code);}function poll(attempt){if(attempt>40){console.error('smoke:dev - timeout waiting for server');finish(1);return;}const req=http.get({host:'127.0.0.1',port:PORT,path:'/v1/flows/'+SLUG},(res)=>{console.log('smoke:dev - GET /v1/flows/'+SLUG+' -> HTTP '+res.statusCode);res.resume();finish(0);});req.on('error',()=>{setTimeout(()=>poll(attempt+1),500);});}child.on('exit',(code)=>{if(!done){console.error('smoke:dev - child exited early with code '+code);finish(1);}});setTimeout(()=>poll(0),500);\"",
     "smoke:build": "node -e \"const{spawn}=require('child_process');const http=require('http');const PORT=process.env.PORT||'3002';const SLUG=process.env.SMOKE_FLOW_SLUG||'smoke-check';const child=spawn('node',['dist/cli.js'],{env:process.env,stdio:'ignore'});let done=false;function finish(code){if(done)return;done=true;try{child.kill();}catch(e){}process.exit(code);}function poll(attempt){if(attempt>40){console.error('smoke:build - timeout waiting for server');finish(1);return;}const req=http.get({host:'127.0.0.1',port:PORT,path:'/v1/flows/'+SLUG},(res)=>{console.log('smoke:build - GET /v1/flows/'+SLUG+' -> HTTP '+res.statusCode);res.resume();finish(0);});req.on('error',()=>{setTimeout(()=>poll(attempt+1),500);});}child.on('exit',(code)=>{if(!done){console.error('smoke:build - child exited early with code '+code);finish(1);}});setTimeout(()=>poll(0),500);\"",
     "smoke": "pnpm run smoke:dev && pnpm run smoke:build",
-    "lint": "tsx ../../scripts/lint-package.ts",
+    "lint": "eslint .",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
@@ -46,6 +46,7 @@
     "@working-theory/observability": "workspace:*",
     "@working-theory/schema": "workspace:*",
     "@working-theory/site-config": "workspace:*",
+    "@working-theory/stripe-client": "workspace:*",
     "@working-theory/validation": "workspace:*",
     "dotenv": "^17.4.2",
     "fastify": "^5.12.1",
@@ -64,6 +65,10 @@
     "prisma": "^7.8.0",
     "ts-jest": "^29.4.11",
     "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "eslint": "^10.6.0",
+    "@eslint/js": "^10.0.1",
+    "globals": "^17.7.0",
+    "typescript-eslint": "^8.62.1"
   }
 }