create-ailk 0.1.0 → 0.2.0

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

@@ -38,3 +38,41 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # Must match OSS_API_INTERNAL_SECRET in apps-paid/marketing-api/.env.local.
 # Generate with: openssl rand -hex 32
 # OSS_API_INTERNAL_SECRET=your-shared-secret-here
+
+# =============================================================================
+# Scheduling — the `booker` section's provider (#4416)
+# =============================================================================
+# SERVER-SIDE ONLY. The browser never receives these: the booker section calls
+# this app's /v1/schedule/availability + /v1/schedule/book, and those handlers
+# hold the credential. Never expose any of these as NEXT_PUBLIC_*.
+#
+# Unset CAL_API_KEY is a supported state, not a broken one — the routes answer
+# 503 not_configured with the provider's public booking page, and the section
+# renders a link out to it rather than an error.
+# CAL_API_KEY=cal_live_xxx
+# Self-hosted Cal instances only; defaults to https://api.cal.com.
+# CAL_API_BASE_URL=https://api.cal.com
+# Host used to build the degraded state's link out; defaults to https://cal.com.
+# SCHEDULING_PUBLIC_BASE_URL=https://cal.com
+# 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
+
+# ── Project listings — site addressing (#5048 D2) ───────────────────────────
+# AILK_SITE_ID is this deployment's own site identifier. Unset means "default".
+# It is read SERVER-SIDE only; no request body carries a site identifier.
+# AILK_SITE_ID=default
+#
+# AILK_LISTING_PUBLIC_KEY is the PUBLIC site key an anonymous founder
+# application and the public listings read name this site by. It is not a
+# credential: it ships in browser JavaScript and in an agent's request, and
+# holding it grants only what a public application form grants. The server maps
+# it to AILK_SITE_ID.
+#
+# This is the SINGLE-TENANT path — the default create-ailk scaffold, one
+# customer per deployment, no database row required. A multi-tenant deployment
+# instead writes SiteListingConfig.public_key per site, which is consulted
+# first. With neither set, every application and every public read answers 400
+# unknown_site_key, which is the correct closed default but gives no clue at
+# boot — so set this if the deployment accepts listings.
+# AILK_LISTING_PUBLIC_KEY=

package/templates/apps/api/CLAUDE.md

@@ -17,11 +17,24 @@ 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/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)
+- `/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. 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/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/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/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/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()`. No MCP twin — identity-bound (#3591 exception).
+- `/v1/flow-checkouts/me` (GET) — the respondent purchases read (#4984, FEAT-022 M2): a signed-in, **email-verified** user's OWN `FlowCheckout` rows, newest first, `[]` when none (`id`, `flowSlug`, `experimentKey`, `offerKey`, `status`, `amountMinor`, `currency`, `period`, `completedAt`, `createdAt` — ten fields, nothing more; `src/services/flow-checkouts.ts` is the only read path). Registered in `authScope` only, beside `/v1/waitlist-signups/me`. Identity is `request.userId`; rows are joined through the promotion link (`Lead.promotedUserId = userId`, `src/services/lead-promotion.ts`) — never by an email, and no query parameter is read; `emailVerified !== true` → 403 `email_unverified` before any `Lead` read; every read scoped to `currentSiteId()`. No MCP twin — identity-bound (#3591 exception).
+- `/v1/project-listings/me` (GET) — the FOUNDER'S OWN listings read (#5295): a signed-in user's own `ProjectListing` rows, newest first, `[]` when none. Registered in `authScope` only, beside `/v1/flow-checkouts/me` — a founder is not a workspace member, so the tenant guard's default-deny would answer 403 for their own submission. Identity is `request.userId`; rows are joined through the owner link (`ProjectListing.ownerUserId = userId`, stamped by `src/services/listing-promotion.ts`) — **never** by `founderEmail`, at any stage, and no query parameter is read. `founderEmail` is an unverified string typed into an anonymous form, so a read-time email match would hand one of two people sharing an address the other's submission. The row shape is `projectListingDraftSchema` (the founder-facing shape the anonymous draft read already uses — no `siteId`, `leadId`, `decidedBy`, `issueUrl`, or `experimentKey`). The route is ADDITIVE: `PROJECT_LISTING_ROLES` stays `owner|admin` and the tenant-scoped list/get/patch routes are unchanged. No MCP twin — identity-bound (#3591 exception).
 
-AEO Layer 1 scoring runs locally as a CLI command (`ailk audit`), not an HTTP endpoint.
+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.
 
 JSON in, JSON out. Validate inputs with `@working-theory/validation`. Response envelope:
 
@@ -36,12 +49,56 @@ Capture → persist (DB or file) → notify operator → return success. That's
 
 Routing rules, enrichment, dedupe, webhook fan-out, CRM integration live in `@working-theory/lead-routing`, loaded via JWT entitlement check. Never hardcode routing logic here — the boundary is what makes paid additive.
 
+## Services (billing-ledger)
+
+- `src/services/usage-metering.ts` — the write path for a completed AI call: cost → markup → write, in one `$transaction` (`UsageEvent` insert + `UsagePeriod` upsert).
+- `src/services/usage-aggregation.ts` — sums an org/period's `UsageEvent` rows into the `UsageBillingReport` row (meter → aggregate → report).
+- `src/services/usage-credits.ts` — the credit waterfall; the sanctioned tenant-scope exception that reads/writes `Organization`'s on-demand credit balance.
+
+These own every billing-ledger mutation — don't write `UsageEvent`/`UsagePeriod`/`UsageBillingReport`/`Organization` balance fields from a route handler directly.
+
 ## Persistence
 
 - DB adapter is the default. File fallback exists for zero-config OSS use.
 - Don't assume a DB is configured. Read `AILK_DB_URL` and degrade gracefully.
 - Migrations in `database/migrations`. Never edit a shipped migration — add a new one.
 
+## Scheduled sweeps (external cron)
+
+Stateless, idempotent bins an external scheduler runs (Vercel Cron / GitHub
+Actions cron / plain crontab) — this repo has no queue or in-process timer
+(D1). Dev: `pnpm --filter @working-theory/api <script>`. Production:
+`node dist/bin/<name>.js`, on whatever cadence the deployment chooses;
+a SEQUENTIAL re-run is always a no-op for already-processed rows, via each
+sweep's own DB constraint (never a caller-side lock).
+
+- `abandon:sweep` (`src/bin/abandon-sweep.ts`, #3962) — sends (or audits, in
+  `dark` mode) the configured `abandonEmail` follow-up for an incomplete flow
+  session past its `delayMinutes` window. Idempotent via `FlowSession.abandonEmailStatus`.
+- `followup:sweep` (`src/bin/followup-sweep.ts`, #4732) — sends each due
+  `(lead, followUpKey)` pair from a completed flow session's `followUps`
+  register, tier-gated and suppressed on a booked call or a Resend
+  unsubscribe. Idempotent via `waitlist_followup_sends`'
+  `@@unique([leadId, followUpKey])`; a CONCURRENT overlapping run racing the
+  same pair is caught (the unique-constraint violation is swallowed and
+  logged, not surfaced as a sweep failure) rather than aborting the whole
+  run — the narrow race window between the idempotency check and the send
+  itself is not closed (a genuinely overlapping invocation could still
+  double-send that one email), so avoid overlapping invocations of the same
+  bin; a missed tick is still harmless either way.
+- `listing-csv:sweep` (`src/bin/listing-csv-sweep.ts`, #5001) — the WEEKLY
+  founder CSV: for each `live` `ProjectListing`, the `WaitlistScore` rows for
+  its experiment newer than the last `ListingCsvSend` become one CSV, stored
+  as a `DeliverableAsset` (`listing-{slug}-{yyyy-mm-dd}`, `text/csv`), granted
+  to the founder's own `Lead`, and emailed as a
+  `GET /v1/deliverables/:grantId` capability link — the founder's list with no
+  login. Idempotent via the `ListingCsvSend` watermark: no signup newer than
+  the last send means no asset, no grant, no email. The stamp is written only
+  after a SUCCESSFUL send, so a failed send leaves those rows for the next
+  run rather than losing them. Per-listing failures are logged (PII-safe) and
+  never stop the listings after them. The CONSUMER schedules this weekly;
+  this repo adds no cron of its own.
+
 ## Error handling
 
 - Never leak stack traces in responses. Log them, return a code.
@@ -61,3 +118,23 @@ Routing rules, enrichment, dedupe, webhook fan-out, CRM integration live in `@wo
 - Don't return 200 with `{ ok: false }`.
 - Don't read MDX directly — use `@working-theory/content-adapters`.
 - Don't put session state in `apps/api`. It's stateless.
+
+Last updated: 2026-09-12 — doc-sync: added `GET /v1/project-listings/me` (#5295), the auth-scoped founder read joined on the owner link, to Endpoint conventions — verified against `apps/api/src/routes/project-listings/me.ts` and `apps/api/src/server.ts`.
+
+Prior: 2026-09-07 — doc-sync: added `listing-csv:sweep` (#5001), the weekly founder-CSV sweep, to `## Scheduled sweeps (external cron)` — verified against `apps/api/src/bin/listing-csv-sweep.ts` and `apps/api/package.json`.
+
+Prior: 2026-09-04 — doc-sync: added the `## Scheduled sweeps (external cron)` section documenting `abandon:sweep` and `followup:sweep` (#4732 AC-6) — verified against `apps/api/package.json` and `apps/api/src/bin/`.
+
+Prior: 2026-09-04 — doc-sync: added `GET /v1/waitlist-signups/me` (#4731), the auth-scoped respondent read, to Endpoint conventions — verified against `apps/api/src/routes/waitlist-signups/index.ts` and `apps/api/src/server.ts`.
+
+Prior: 2026-09-02 — doc-sync: noted the `AILK_OPERATOR_EMAIL` fail-closed precondition on the platform-operator scope in the `/v1/waitlist-experiments/*` row (PR #4687 security review, High finding) — verified against `apps/api/src/services/waitlist-dashboard.ts`.
+
+Prior: 2026-09-02 — doc-sync: added `/v1/waitlist-experiments/*` routes (#4665 D7, #4671) to Endpoint conventions — verified against `apps/api/src/routes/waitlist-experiments/index.ts`.
+
+Prior: 2026-08-31 — doc-sync: added `GET /v1/schedule/event-meta` (#4633), the meta-only scheduling read, to the `/v1/schedule/*` row — verified against `apps/api/src/routes/schedule/index.ts`.
+
+Prior: 2026-08-26 — doc-sync: added `/v1/schedule/*` routes (#4416) to Endpoint conventions — verified against `apps/api/src/routes/schedule/index.ts`.
+
+Prior: 2026-08-10 — doc-sync: added `/v1/flows/*` routes (#3956) to Endpoint conventions — verified against `apps/api/src/routes/flows/index.ts`.
+
+Prior: 2026-07-15 — doc-sync: added `/v1/billing/*` routes (#3701) to Endpoint conventions; added the `## Services (billing-ledger)` section documenting `usage-metering.ts` / `usage-aggregation.ts` / `usage-credits.ts` — verified against `apps/api/src/routes/billing/index.ts` and `apps/api/src/services/`.

package/templates/apps/api/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tailwind AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/templates/apps/api/api/index.ts

@@ -1,144 +1,9 @@
 /**
  * Vercel Serverless Function Handler for Customer Template Backend
- * This file wraps the Fastify server for Vercel's serverless functions
+ *
+ * Thin re-export — the adapter logic lives in ../src/vercel-handler.ts so it
+ * sits under apps/api/src, which is what both tsconfig.json's `include` and
+ * jest.config.cjs's `roots` reach (this apps/api/api/ directory is outside
+ * both, so nothing here is type-checked or tested directly).
  */
-
-import { logger } from '@working-theory/observability';
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-
-import type { build as buildServer } from '../src/server.js';
-
-type FastifyServer = Awaited<ReturnType<typeof buildServer>>;
-
-// Import the build function from server
-async function getBuildFunction(): Promise<typeof buildServer> {
-  try {
-    const srcModule = await import('../src/server.js');
-    logger.info('[Vercel Handler] Using server from src/server.js');
-    return srcModule.build;
-  } catch (srcError) {
-    logger.error(
-      {
-        err: srcError instanceof Error ? srcError.message : String(srcError),
-        stack: srcError instanceof Error ? srcError.stack : undefined,
-      },
-      '[Vercel Handler] Failed to import server',
-    );
-    throw new Error(`Cannot find server module: ${srcError instanceof Error ? srcError.message : String(srcError)}`, { cause: srcError });
-  }
-}
-
-// Initialize build function
-const buildPromise = getBuildFunction();
-let serverInstance: FastifyServer | null = null;
-
-/**
- * Get or create the Fastify server instance
- */
-async function getServer() {
-  if (!serverInstance) {
-    logger.info('[Vercel Handler] Building server instance...');
-    const startTime = Date.now();
-
-    try {
-      const buildTimeout = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error('Server build timeout after 10s')), 10000);
-      });
-
-      const build = await Promise.race([buildPromise, buildTimeout]);
-      logger.info('[Vercel Handler] Build function obtained, creating server...');
-
-      const initTimeout = new Promise<never>((_, reject) => {
-        setTimeout(() => reject(new Error('Server initialization timeout after 10s')), 10000);
-      });
-
-      serverInstance = await Promise.race([build(), initTimeout]);
-
-      const buildTime = Date.now() - startTime;
-      logger.info({ buildTime }, '[Vercel Handler] Server built successfully');
-    } catch (error) {
-      const buildTime = Date.now() - startTime;
-      logger.error({ err: error, buildTime }, '[Vercel Handler] Failed to build server');
-      throw new Error(`Server build failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-    }
-  }
-  return serverInstance;
-}
-
-/**
- * Vercel serverless function handler
- */
-export default async function handler(
-  req: VercelRequest,
-  res: VercelResponse
-): Promise<void> {
-  const timeout = setTimeout(() => {
-    if (!res.headersSent) {
-      logger.error('[Vercel Handler] Request timeout');
-      res.status(504).json({
-        error: 'Gateway Timeout',
-        message: 'Request took too long to process',
-      });
-    }
-  }, 25000);
-
-  try {
-    logger.info({ method: req.method, url: req.url }, '[Vercel Handler] Starting request');
-
-    const server = await getServer();
-
-    const url = new URL(req.url || '/', 'http://localhost');
-    const pathname = url.pathname;
-
-    logger.info({ method: req.method, pathname }, '[Vercel Handler] Processing request');
-
-    const fastifyRequest = {
-      method: req.method || 'GET',
-      url: pathname,
-      headers: req.headers as Record<string, string>,
-      body: req.body,
-      query: req.query as Record<string, string>,
-    };
-
-    const response = await server.inject(fastifyRequest);
-
-    logger.info({ status: response.statusCode }, '[Vercel Handler] Response status');
-
-    clearTimeout(timeout);
-
-    res.status(response.statusCode);
-    
-    Object.entries(response.headers).forEach(([key, value]) => {
-      if (value !== undefined && !res.headersSent) {
-        const headerValue = Array.isArray(value)
-          ? value.map((v) => String(v)).join(', ')
-          : String(value);
-        res.setHeader(key, headerValue);
-      }
-    });
-
-    if (!res.getHeader('Content-Type') && !res.headersSent) {
-      res.setHeader('Content-Type', 'application/json');
-    }
-
-    if (!res.headersSent) {
-      const body = typeof response.body === 'string' 
-        ? response.body 
-        : JSON.stringify(response.body);
-      
-      res.send(body);
-      logger.info('[Vercel Handler] Response sent successfully');
-    }
-  } catch (error) {
-    clearTimeout(timeout);
-
-    logger.error({ err: error }, '[Vercel Handler] Error handling request');
-    
-    if (!res.headersSent) {
-      res.status(500).json({
-        error: 'Internal Server Error',
-        message: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-}
+export { default } from '../src/vercel-handler.js';

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

@@ -30,8 +30,21 @@ module.exports = {
     // forms to the same shared mock.
     '^@working-theory/database$': '<rootDir>/src/lib/__mocks__/prisma-client.js',
     '^.*database/generated/client/(index|client)\\.(js|ts)$': '<rootDir>/src/lib/__mocks__/prisma-client.js',
+    // The tenancy constants subpath (#3627) — real TS source, not a mock: the
+    // `database/tenancy.ts` module has no external boundary to fake, so map
+    // straight to source, matching the workspace-package-to-src pattern below.
+    '^@working-theory/database/tenancy$': '<rootDir>/../../database/tenancy.ts',
+    // The flow-presets data subpath (#3958) — same real-TS-source rationale
+    // as tenancy above: FLOW_PRESETS is plain data with no external boundary
+    // to fake, so map straight to source rather than requiring a package build.
+    '^@working-theory/database/flows/presets$': '<rootDir>/../../database/flows/presets.ts',
+    // The shared listing-diagnostic scoring register (#5001) — same
+    // real-TS-source rationale as flows/presets above.
+    '^@working-theory/database/flows/listing-diagnostic$': '<rootDir>/../../database/flows/listing-diagnostic.ts',
     // Map workspace packages to their TypeScript source so ts-jest compiles them
     // directly (the published dist is ESM, which Jest's CJS preset can't load).
+    '^@working-theory/aeo/fetch$': '<rootDir>/../../packages/aeo/src/fetch/index.ts',
+    '^@working-theory/aeo$': '<rootDir>/../../packages/aeo/src/index.ts',
     '^@working-theory/analytics/server$': '<rootDir>/../../packages/analytics/src/server/index.ts',
     '^@vercel/analytics/server$': '<rootDir>/../../packages/analytics/__mocks__/vercel-analytics-server.ts',
     '^@working-theory/common$': '<rootDir>/../../packages/common/src/index.ts',
@@ -39,11 +52,14 @@ module.exports = {
     '^@working-theory/content-projection$': '<rootDir>/../../packages/content-projection/src/index.ts',
     '^@working-theory/content-projection/node$': '<rootDir>/../../packages/content-projection/src/node.ts',
     '^@working-theory/email$': '<rootDir>/../../packages/email/src/index.ts',
+    '^@working-theory/ids$': '<rootDir>/../../packages/ids/src/index.ts',
     '^@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',
     '^@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',
+    '^@working-theory/schema-validator$': '<rootDir>/../../packages/schema-validator/src/index.ts',
     '^@working-theory/stripe-client$': '<rootDir>/../../packages/stripe-client/src/index.ts',
     '^@working-theory/validation$': '<rootDir>/../../packages/validation/src/index.ts',
     '^(\\.{1,2}/.*)\\.js$': '$1',

package/templates/apps/api/package.json

@@ -7,10 +7,20 @@
   "type": "module",
   "scripts": {
     "dev": "tsx watch src/cli.ts",
+    "abandon:sweep": "tsx src/bin/abandon-sweep.ts",
+    "followup:sweep": "tsx src/bin/followup-sweep.ts",
+    "listing-csv:sweep": "tsx src/bin/listing-csv-sweep.ts",
+    "retention:sweep": "tsx src/bin/session-retention-sweep.ts",
+    "deliverable:upload": "tsx src/bin/deliverable-upload.ts",
+    "deliverable:resend": "tsx src/bin/deliverable-resend.ts",
+    "seed:presets": "tsx src/bin/seed-presets.ts",
     "build": "tsc",
     "build:vercel": "cd ../../database && pnpm exec prisma generate && cd ../.. && pnpm --filter @working-theory/validation build && pnpm --filter @working-theory/api build && mkdir -p apps/api/public && echo '{}' > apps/api/public/.vercel",
     "start": "node dist/cli.js",
-    "lint": "eslint src --ext .ts",
+    "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",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
@@ -20,24 +30,29 @@
     "db:studio": "cd ../../database && prisma studio"
   },
   "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@prisma/adapter-pg": "^7.8.0",
+    "@prisma/client": "^7.8.0",
+    "@working-theory/aeo": "workspace:*",
     "@working-theory/analytics": "workspace:*",
     "@working-theory/common": "workspace:*",
     "@working-theory/content-adapters": "workspace:*",
     "@working-theory/content-projection": "workspace:*",
     "@working-theory/database": "workspace:*",
     "@working-theory/email": "workspace:*",
+    "@working-theory/ids": "workspace:*",
     "@working-theory/license": "workspace:*",
     "@working-theory/observability": "workspace:*",
     "@working-theory/schema": "workspace:*",
+    "@working-theory/site-config": "workspace:*",
     "@working-theory/stripe-client": "workspace:*",
     "@working-theory/validation": "workspace:*",
-    "@fastify/cors": "^11.2.0",
-    "@fastify/rate-limit": "^10.3.0",
-    "@prisma/adapter-pg": "^7.8.0",
-    "@prisma/client": "^7.8.0",
     "dotenv": "^17.4.2",
-    "fastify": "^5.7.2",
+    "fastify": "^5.12.1",
+    "pdf-lib": "^1.17.1",
     "pg": "^8.22.0",
+    "yaml": "^2.9.0",
     "zod": "^4.2.1"
   },
   "devDependencies": {
@@ -46,6 +61,7 @@
     "@types/pg": "^8.20.0",
     "@vercel/node": "^5.8.22",
     "jest": "^30.4.2",
+    "pdfjs-dist": "^6.3.289",
     "prisma": "^7.8.0",
     "ts-jest": "^29.4.11",
     "tsx": "^4.22.4",