@forumone/create-throughline 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @forumone/create-throughline
 
+## 0.5.0
+
+### Minor Changes
+
+- 006ae30: A missing environment variable is reported together with every other one, in a
+  single error, instead of one plugin at a time.
+
+  The plugins that read the environment at init now declare what they cannot
+  start without, as data: `approvalsEnv` (`APPROVAL_TOKEN_SECRET`, 32+
+  characters), `emailEnv` (`RESEND_API_KEY`, `EMAIL_FROM_ADDRESS`) and `formsEnv`
+  (`FORMS_IP_HASH_SECRET`, 32+ characters). Each is a list of `EnvRequirement`
+  (`{ name, minLength?, why }`), a new type in `plugin-contract`, and each
+  plugin's own init check now reads the same entries, so the two cannot drift.
+  An empty or whitespace-only value now counts as missing in those checks.
+
+  Core exports `assertEnvironment(...checks)`. Call it first in
+  `payload.config.ts` with the plugins' lists and your own variables; it throws
+  one `EnvironmentError` whose first line reads "Configuration problem: N
+  environment variables are missing or invalid", followed by every missing or
+  too-short variable and why it is needed. Values are never printed. An argument
+  can also be a function, for a rule that is not "this name, this long", such as
+  a database URL accepted under several names. `checkEnvValue` is the one-value
+  check behind it, for a plugin's own backstop.
+
+  New projects call `assertEnvironment` at the top of `payload.config.ts` with
+  `approvalsEnv`, `emailEnv`, `formsEnv`, `PAYLOAD_SECRET` (32+ characters),
+  `NEXT_PUBLIC_SERVER_URL` and the database resolver, and `.env.example` marks
+  which variables are checked. An existing site can do the same and delete any
+  hand-kept copy of the plugins' requirements.
+
+- 833c1bd: A scaffolded project ships the rules an agent, or a new developer, needs:
+
+  - **`CLAUDE.md`** covers the layout, the gate in CI's own order, which files are generated and committed, how migrations and snapshots work, and the contract rule for the design system.
+  - **A Stop hook** (`.claude/hooks/gate.sh`) runs typecheck and lint when a session ends with pending changes. It reports, never blocks, and is silenced by `THROUGHLINE_SKIP_GATE=1`.
+
+  The README's project layout now matches what the scaffold generates.
+
+- 549d292: A scaffolded project runs every Payload CLI script — `payload`, `generate:types`, `generate:importmap`, `migrate`, `migrate:create`, `migrate:status` — through core's `throughline-payload`, so a hung run is killed rather than left spinning after its shell dies. It adds `payload:reap` to `apps/web` and the root, and ignores `.payload-cli-pids`.
+- 70385c4: A scaffolded project reports its failures. `apps/web/src/instrumentation.ts` sends unhandled request errors to `ERROR_WEBHOOK_URL` through core's reporter, and warns at boot when that variable is unset. The Inngest route passes `createTerminalFailureHandler` to every framework workflow and `createHealthcheckFailureHandler` to the healthcheck. `payload.config.ts` registers `jobFailuresPlugin`. `.env.example` lists `ERROR_WEBHOOK_URL` as optional.
+
+  A new project's first migration includes the `job-failures` table. An existing project that copies these changes needs `payload migrate:create`.
+
+- c8a86bf: A scaffolded project now starts with tests in `apps/web`:
+
+  - **Vitest.** `vitest.config.ts` loads `payload.config.ts` with placeholder variables and no database. `src/access/anonymousAccess.test.ts` uses `describeAnonymousAccess` to put every collection the project has into an access bucket. `pnpm test` runs it in CI's `fast` job. `check:tested` drops its exception for `apps/web`.
+  - **Playwright smoke pack.** `e2e/` runs against `next start`, or against `E2E_BASE_URL`. It checks the front door, a 404, the admin sign-in screen, and anonymous REST reads. The paths are in `e2e/site.ts`, along with the checks a new project cannot pass yet because it does not serve the routes they test. It runs in CI's `verify` job after the build. The new scripts are `test`, `test:smoke` and `test:smoke:install`.
+  - **`pages` read rule.** The example `pages` collection gains a published-or-signed-in `read` rule. Before, Payload's default refused every anonymous read, so the public site could never read a page.
+
+### Patch Changes
+
+- c8a86bf: The `Divider` contract now declares `decorative` with `defaultValue: true`, matching the component. Before, the default was written only in prose, so a divider added in the CMS started unticked and screen readers announced it.
+- ab623e1: The scaffolded `payload.config.ts` uses core's `mcpApiKeyAccess(isAdmin)` to make the MCP key collection admin-only, replacing the inline override. It now also covers `unlock` and refuses a key principal outright. The scaffold depends on `payload` and `@payloadcms/*` `^3.89.0`.
+- 653817e: Revalidation no longer guesses paths, and covers the changes a publish event never announces.
+
+  - **workflows (breaking)**: `createRevalidateOnPublishFunction` has no built-in URL
+    builders. They mapped `pages` to `/<slug>`, `posts` to `/blog/<slug>` and any other
+    collection to `/<slug>`, so a site whose routes differed revalidated the wrong path
+    without a word. `urlBuilders` is now required; a collection with no entry has its
+    tags dropped and no path revalidated, and the run logs a warning. To keep the old
+    behaviour, pass the old builders:
+
+    ```ts
+    urlBuilders: {
+      pages: (slug) => (slug === 'home' || slug === '' ? '/' : `/${slug}`),
+      posts: (slug) => `/blog/${slug}`,
+    }
+    ```
+
+    and then check them against your routes.
+
+  - **workflows**: `createTagRevalidationHooks` — collection `afterChange` and
+    `afterDelete`, and global `afterChange`, hooks that call
+    `revalidateTag(tag, { expire: 0 })`. Draft saves and autosave drop nothing (via
+    publishing's `isDraftWrite`); an unpublish still does. A hook never throws: outside a
+    Next request (seeds, migrations, the CLI) it logs at `debug`, and any other failure
+    at `error` with the tag and the cause.
+  - **workflows**: `createCacheTags` builds every tag string, so the hooks, the publish
+    workflow (new `cacheTags` option) and cached reads cannot name different tags.
+    Defaults: the bare slug for a collection, `global_<slug>` for a global. Also on the
+    dependency-free `@forumone/throughline-workflows/cache-tags` subpath for frontend code.
+    `@forumone/throughline-publishing` is now a dependency of this package.
+  - **create-throughline**: the scaffold adds `apps/web/src/lib/cache-tags.ts`, attaches
+    the tag hooks to `Pages`, and passes explicit `urlBuilders` and the shared
+    `cacheTags` to the publish workflow.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAgC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAa,MAAM,kBAAkB,CAAA;AAK5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAK3C,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC7F;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED;;;;;;;;;GASG;AACH,iBAAe,eAAe,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmClF;AAiBD,iBAAS,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI3C;AAcD,iBAAS,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AA6BD,eAAO,MAAM,SAAS;;;;;;;CAAsE,CAAA"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAgC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAa,MAAM,kBAAkB,CAAA;AAK5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAK3C,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC7F;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED;;;;;;;;;GASG;AACH,iBAAe,eAAe,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmClF;AAiBD,iBAAS,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI3C;AAeD,iBAAS,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AA6BD,eAAO,MAAM,SAAS;;;;;;;CAAsE,CAAA"}

package/dist/generator.js

@@ -117,13 +117,14 @@ function isBinary(filename) {
 /**
  * npm strips files literally named `.gitignore` from a published tarball, so
  * we author them as `gitignore` in templates and restore the dot on output.
- * `.github` goes the same way: a dot-directory in a tarball is at the mercy of
- * whichever ignore rules the publishing npm applies, and the scaffold's CI is
- * not something to lose silently.
+ * `.github` and `.claude` go the same way: a dot-directory in a tarball is at
+ * the mercy of whichever ignore rules the publishing npm applies, and neither
+ * the scaffold's CI nor its agent setup is something to lose silently.
  */
 const DOTFILE_RENAMES = {
     gitignore: '.gitignore',
     github: '.github',
+    claude: '.claude',
 };
 function applyDotfileRename(name) {
     return DOTFILE_RENAMES[name] ?? name;

package/dist/generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"generator.js","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAGzD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AACzD,MAAM,qBAAqB,GAAG,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAA;AAW7D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAgB,EAAE,UAA2B,EAAE;IAC5E,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,qBAAqB,CAAA;IAClE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAEnD,6EAA6E;IAC7E,yEAAyE;IACzE,kEAAkE;IAClE,MAAM,gBAAgB,GAAG,OAAO,CAAC,YAAY;QAC3C,CAAC,CAAC,IAAI,OAAO,CAAC,YAAY,gBAAgB;QAC1C,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,gBAAgB,CAAA;IAC1C,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,YAAY,CAAC,CAAA;IACxD,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,gBAAgB,EAAE,GAAG,QAAQ,EAAwC,CAAA;IAEhG,UAAU,CAAC,4BAA4B,CAAC,CAAA;IACxC,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACnD,MAAM,eAAe,CAAC;QACpB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC,SAAS;QACzB,IAAI;KACL,CAAC,CAAA;IAEF,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC,CAAC,qCAAqC,CAAC,CAAA;IAC7G,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,sBAAsB,CAAA;IACrF,MAAM,eAAe,CAAC;QACpB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC;QACnC,MAAM,EAAE,OAAO,CAAC,SAAS;QACzB,IAAI;KACL,CAAC,CAAA;IAEF,IAAI,OAAO,CAAC,aAAa,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QACtD,UAAU,CAAC,kBAAkB,CAAC,CAAA;QAC9B,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAClC,CAAC;IAED,IAAI,OAAO,CAAC,WAAW,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QACpD,UAAU,CAAC,kDAAkD,CAAC,CAAA;QAC9D,MAAM,mBAAmB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC9C,CAAC;AACH,CAAC;AAQD;;;;;;;;;GASG;AACH,KAAK,UAAU,eAAe,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAc;IACjE,IAAI,OAAO,CAAA;IACX,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAM;QAC9D,MAAM,KAAK,CAAA;IACb,CAAC;IAED,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAExC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;QACzE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;QAE7C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,eAAe,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;YACvE,SAAQ;QACV,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,SAAQ;QAE7B,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;YAChC,SAAQ;QACV,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;QAC/C,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAC1C,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC;YAChD,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC;YAC1C,CAAC,CAAC,UAAU,CAAA;QACd,MAAM,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;IACtC,CAAC;AACH,CAAC;AAED,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;IACP,QAAQ;IACR,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;CACP,CAAC,CAAA;AAEF,SAAS,QAAQ,CAAC,QAAgB;IAChC,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IACrC,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IAC5B,OAAO,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,eAAe,GAA2B;IAC9C,SAAS,EAAE,YAAY;IACvB,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,SAAS;CAClB,CAAA;AAED,SAAS,kBAAkB,CAAC,IAAY;IACtC,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;AACtC,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,GAAW;IAChC,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAA;IACtC,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,CAAA;IAC1C,MAAM,UAAU,CACd,KAAK,EACL,CAAC,QAAQ,EAAE,IAAI,EAAE,wCAAwC,CAAC,EAC1D,GAAG,CACJ,CAAA;AACH,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,GAAW;IAC5C,MAAM,UAAU,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,CAAA;AAC5C,CAAC;AAED,SAAS,UAAU,CAAC,GAAW,EAAE,IAAc,EAAE,GAAW;IAC1D,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE;QAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;QACzD,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,IAAI,IAAI,KAAK,CAAC;gBAAE,cAAc,EAAE,CAAA;;gBAC3B,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC,CAAA;QAC7E,CAAC,CAAC,CAAA;QACF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IAC3B,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,8EAA8E;AAC9E,wEAAwE;AACxE,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA"}

package/dist/templates/base/.env.example

@@ -1,9 +1,17 @@
-# --- Required ---
+# Every variable marked "checked at startup" is listed in the assertEnvironment
+# call at the top of apps/web/src/payload.config.ts, which reports all the
+# missing or too-short ones in a single error before anything else runs. Add a
+# variable there when you add one here that the site cannot start without.
+
+# --- Required (checked at startup) ---
+# The database may come from DATABASE_URI or, on Vercel + Neon, the
+# integration's DATABASE_URL and friends — see apps/web/src/lib/database.ts.
 DATABASE_URI=postgres://user:pass@host/dbname
 # Optional: a schema-owner credential used only by `pnpm migrate`, so the app
 # itself can run as a role that reads and writes rows and no more. See
 # apps/web/src/lib/database.ts.
 # MIGRATION_DATABASE_URL=
+# 32+ characters. Generate: openssl rand -base64 48
 PAYLOAD_SECRET=generate-with-openssl-rand-base64-48
 NEXT_PUBLIC_SERVER_URL=http://localhost:3000
 
@@ -14,17 +22,19 @@ INNGEST_EVENT_KEY=
 INNGEST_SIGNING_KEY=
 
 # --- Resend (for approval + form notification emails) ---
+# RESEND_API_KEY and EMAIL_FROM_ADDRESS are checked at startup (emailEnv).
 RESEND_API_KEY=
 EMAIL_FROM_ADDRESS=notifications@example.com
+# Optional.
 EMAIL_FROM_NAME={{projectName}}
 EMAIL_REPLY_TO=
 
-# --- Approval tokens ---
-# Generate: openssl rand -base64 48
+# --- Approval tokens (checked at startup: approvalsEnv) ---
+# 32+ characters. Generate: openssl rand -base64 48
 APPROVAL_TOKEN_SECRET=
 
-# --- Forms ---
-# Generate: openssl rand -base64 48
+# --- Forms (checked at startup: formsEnv) ---
+# 32+ characters. Generate: openssl rand -base64 48
 FORMS_IP_HASH_SECRET=
 
 # --- MCP ---
@@ -33,6 +43,14 @@ FORMS_IP_HASH_SECRET=
 # API Keys and give it to your MCP client, not to this file. Scheduled
 # publishes run in process and need no key either.
 
+# --- Optional: error reporting ---
+# Where unhandled request errors, workflows that ran out of retries and failing
+# healthchecks are POSTed as JSON (with a one-line `text`, so a Slack incoming
+# webhook works as-is). A log drain, an alerting endpoint or a proxy in front of
+# your error tracker. Unset: errors reach the log only, and the server says so
+# at boot. Job failures are also recorded in the admin under Job Failures.
+ERROR_WEBHOOK_URL=
+
 # --- Optional: storage ---
 # Vercel Blob token if deploying to Vercel; remove this and the storage
 # adapter from payload.config.ts if you're using a different provider.

package/dist/templates/base/CLAUDE.md

@@ -0,0 +1,112 @@
+# {{projectName}}
+
+A **Throughline** project: a Payload CMS application (`apps/web`) wired to the
+Throughline plugin suite, plus the design system that supplies its component
+vocabulary. Throughline docs: https://github.com/forumone/throughline
+
+```
+apps/web/          Next.js + Payload host
+design-system/     The design system and its Storybook
+scripts/           Workspace gates, each explained at the top of its file
+.github/           CI: `fast` on every pull request, `verify` on main
+```
+
+## The gate
+
+This is what CI's `fast` job runs, in its order. Run it before calling work
+done:
+
+```bash
+pnpm install --frozen-lockfile \
+  && pnpm typecheck && pnpm lint \
+  && pnpm check:instances && pnpm check:tested && pnpm check:migrations \
+  && pnpm validate \
+  && bash .github/scripts/check-generated.sh \
+  && pnpm test
+```
+
+`--frozen-lockfile` leads because a lockfile missing an entry passes every
+other gate locally and fails in CI. `check-generated.sh` needs the environment
+`payload.config.ts` validates; the placeholders at the top of
+`.github/workflows/ci.yml` are enough — it parses the connection string and
+never connects.
+
+`verify` adds a migrated Postgres and `pnpm build`; it runs on main.
+
+A Stop hook (`.claude/hooks/gate.sh`) runs typecheck and lint when a session
+ends with pending changes. It reports and never blocks. Set
+`THROUGHLINE_SKIP_GATE=1` to silence it.
+
+## Generated files are committed — never hand-edit them
+
+After any change to `payload.config.ts`, a collection or a plugin version:
+
+```bash
+pnpm --dir apps/web generate:types       # -> src/payload-types.ts
+pnpm --dir apps/web generate:importmap   # -> src/app/(payload)/admin/importMap.js
+```
+
+Commit both. CI regenerates them and fails on a difference. A stale import map
+is a 500 on any admin screen that renders a component it has never heard of;
+stale types make everything downstream compile against a schema that no longer
+exists.
+
+## Schema changes go through migrations
+
+`push` is off, in development too: `apps/web/src/migrations` is the only way the
+schema changes.
+
+```bash
+pnpm --dir apps/web migrate:create <name>   # diffs the config against the newest snapshot
+pnpm --dir apps/web migrate                 # apply
+pnpm --dir apps/web migrate:snapshot        # only after hand-writing a migration
+```
+
+`migrate:create` diffs against the `.json` snapshot beside the newest migration,
+**not the database**. A hand-written migration without its snapshot leaves the
+generator a step behind, re-proposing changes that already shipped.
+`check:migrations` fails on a missing or orphaned snapshot, and on a drop that a
+`CASCADE` has already carried out.
+
+The `payload` CLI loads `.env.local`; `tsx` scripts load nothing. For anything
+that writes to a database, pass the variables on the command line and use
+`requireTarget` from `apps/web/scripts/lib/target.ts`, which prints the target
+and demands `--confirm` before overwriting.
+
+## The design system reaches the CMS through its manifest
+
+`payload.config.ts` hands the design system's manifest to `componentsPlugin`,
+and that manifest is how the CMS knows which components exist and how they may
+be composed. It is built from a `<Name>.contract.ts` beside every component.
+{{#if useReferenceDs}}
+- **A new component needs a contract.** `build:manifest` refuses a component
+  directory without one; prefix a directory with `_` if it is not a component.
+- **`pnpm validate` must pass.** It catches an unknown token, a composition rule
+  naming a component that does not exist, and an example pointing at a story
+  that is not there.
+{{else}}
+The design system here is a placeholder. When you build it, give every
+component a contract, publish a manifest, and point `componentsPlugin` at it —
+see the design-contract package in the Throughline repository.
+{{/if}}
+## Tests
+
+`check:tested` requires at least one test in every package that ships code.
+
+`apps/web` starts with one: `src/access/anonymousAccess.test.ts`, which
+`pnpm test` runs through a vitest config that loads `payload.config.ts` without
+a database. It puts every collection in one of two buckets: read by the
+rendered site, so anonymous reads must be allowed, or private, so they must be
+refused. A new collection fails it until you add it to a bucket. Decide which,
+and don't open a collection to anonymous reads to make the test pass. More good
+first tests need no database: field validations, and hooks as functions.
+
+`pnpm test:smoke` runs the Playwright smoke pack in `e2e/` against
+`next start`, so build first, or against a deployed site when `E2E_BASE_URL`
+is set. Every check is a GET. CI runs it in `verify`, after the production
+build. Add routes to `e2e/site.ts` as the site gains them.
+
+## Conventions
+
+- pnpm only. The lockfile is at the root.
+- Open a pull request for review; do not merge your own.

package/dist/templates/base/README.md

@@ -30,7 +30,13 @@ openssl rand -base64 48
 #    - APPROVAL_TOKEN_SECRET        — generated above
 #    - FORMS_IP_HASH_SECRET         — generated above
 #    - RESEND_API_KEY               — from Resend dashboard
+#    - EMAIL_FROM_ADDRESS           — a verified sender on your Resend domain
 #    - INNGEST_EVENT_KEY/SIGNING    — from Inngest (optional in local dev)
+#
+#    Anything missing or too short is reported all at once, in one error that
+#    starts "Configuration problem", by the assertEnvironment call at the top
+#    of apps/web/src/payload.config.ts — the first command that loads the
+#    config (step 5) tells you everything left to fill in.
 
 # 5. Create and apply the first migration. The config sets `push: false`, so
 #    migrations are the only way the schema changes, from the first table on.
@@ -75,6 +81,27 @@ pnpm dev
 - `pnpm typecheck` — TypeScript check across the monorepo
 - `pnpm lint` — ESLint
 - `pnpm test` — run all package tests
+- `pnpm payload:reap` — kill any Payload CLI run a killed shell left behind (the next Payload command does this too)
+
+Every script that runs the Payload CLI — `payload`, `generate:*`, `migrate*` —
+goes through `throughline-payload` from `@forumone/throughline-core`. pnpm does
+not forward signals to the node process it starts, so a bare `payload` whose
+shell is killed keeps running, and a hung one spins on a core indefinitely. The
+runner gives Payload its own process group, forwards Ctrl-C and friends to it,
+and kills it after five minutes (`PAYLOAD_CLI_TIMEOUT_MS`, `0` to disable;
+`migrate*` has no limit unless you set one). Run the Payload CLI through these
+scripts rather than `npx payload`.
+
+- `pnpm --dir apps/web test:smoke` — the Playwright smoke pack, against a local `next start` (run `pnpm build` first) or `E2E_BASE_URL`
+
+## Tests
+
+`apps/web` has two kinds of test.
+
+- **`pnpm test`** runs vitest in Node with no database and no browser, so it runs in CI's `fast` job on every pull request. `vitest.config.ts` gives `payload.config.ts` placeholder environment variables, so the config loads without connecting to anything. The first test, `src/access/anonymousAccess.test.ts`, puts every collection into one of two buckets: collections the public site reads with nobody signed in (`renderPath`), and collections it must not read (`private`). It then checks each collection's `read` rule against its bucket. **Adding a collection, or a plugin that brings collections, fails this test until you put each new collection in a bucket.** See the Throughline guide _Adding a collection_.
+- **`pnpm --dir apps/web test:smoke`** is a Playwright smoke pack (`e2e/`) that sends real requests to `next start` on an empty, migrated database. It checks that the front door answers, that an unknown path returns 404, that the admin shows its sign-in screen, and that the REST API refuses anonymous reads of private collections while allowing reads of public ones. It runs in CI's `verify` job, which has a database. Set `E2E_BASE_URL` to run it against a deployed site. Every check is a GET request. The paths it checks are configured in `e2e/site.ts`. That file also lists checks a new project cannot pass yet because it does not serve the route: security headers, `robots.txt`, the sitemap, `llms.txt` and a draft-mode route. Add each check when you add its route.
+
+Run `pnpm --dir apps/web test:smoke:install` once to download Chromium.
 
 ## Migrations
 
@@ -109,14 +136,15 @@ map has never heard of.
 `.github/workflows/ci.yml` runs two tiers. `fast` runs on every pull request
 and needs no database: install from the lockfile, typecheck, lint, the gates
 below, manifest validation, the generated-files check and tests. `verify` runs
-on pushes to main: it migrates a fresh Postgres and runs a production build.
+on pushes to main: it migrates a fresh Postgres, runs a production build, and
+runs the smoke pack against it.
 
 ## Workspace gates
 
 Each is explained at the top of its script in `scripts/`:
 
 - `pnpm check:instances` — `payload`, `@payloadcms/ui`, `react` and `react-dom` each resolve to exactly one copy. Two byte-identical copies are two React contexts, and a runtime failure nothing else can see.
-- `pnpm check:tested` — every workspace package that ships code has at least one test. Not a coverage number. `apps/web` starts on its exception list; delete the entry with your first test.
+- `pnpm check:tested` — every workspace package that ships code has at least one test. Not a coverage number. A package with no tests can go on the exception list in the script, with a reason. An entry fails once that package has tests.
 - `pnpm check:audit` — high and critical production advisories against an allowlist that carries a reason for each entry, and that fails when an entry stops applying.
 
 ## Project layout
@@ -125,10 +153,14 @@ Each is explained at the top of its script in `scripts/`:
 {{projectName}}/
 ├── apps/
 │   └── web/                  # Next.js + Payload host
-├── packages/
-│   ├── design-system/        # UI components consumed by Components MCP
-│   ├── content/              # Reusable collections + blocks (optional)
-│   └── brand/                # Brand tokens / email theme (optional)
+│       ├── scripts/          # migration tooling, requireTarget
+│       └── src/migrations/   # the only way the schema changes
+├── design-system/            # components + contracts -> the manifest the CMS reads
+├── packages/                 # your own shared packages (optional)
+├── scripts/                  # workspace gates
+├── .claude/                  # agent settings and the Stop-hook gate
+├── .github/                  # CI: fast + verify
+├── CLAUDE.md                 # the rules an agent (or a new developer) needs
 ├── .env.example
 ├── pnpm-workspace.yaml
 ├── turbo.json

package/dist/templates/base/apps/web/e2e/site.ts

@@ -0,0 +1,36 @@
+/*
+What the smoke pack checks, and where. Site data: change the paths here, not in
+the specs.
+
+**What the pack does not check yet, because a fresh project does not serve it.**
+Each is a check worth adding with the route that makes it true:
+
+  - security headers — `next.config.mjs` sets none. Add `headers()` there, then
+    assert them per route: HSTS, `nosniff`, a referrer policy, and framing
+    (`DENY` on `/admin`, `SAMEORIGIN` where live preview frames the site).
+  - `robots.txt` and `sitemap.xml` — add `app/robots.ts` and `app/sitemap.ts`;
+    assert a 200, the content type, and that the sitemap lists each URL once.
+  - `llms.txt` — a route serving `text/markdown`, with a heading and links.
+  - draft mode — a preview route must refuse a request without its secret
+    (401) and one naming no document (400).
+*/
+export const site = {
+  /**
+   * A deployed site to point at, from `E2E_BASE_URL`. Unset, the pack starts
+   * `next start` locally on `port`.
+   */
+  baseURL: process.env.E2E_BASE_URL?.trim() || undefined,
+  port: 3100,
+
+  /** The front door. */
+  home: '/',
+  /** The Payload admin. On an empty database it asks for the first user. */
+  admin: '/admin',
+  /** A path nothing serves, which must be a 404 and never a 500. */
+  missing: '/a-page-that-was-never-written',
+
+  /** REST collections an anonymous request must be refused. */
+  privateCollections: ['users', 'payload-mcp-api-keys'],
+  /** REST collections an anonymous request may read — published documents only. */
+  publicCollections: ['pages'],
+}

package/dist/templates/base/apps/web/e2e/smoke.spec.ts

@@ -0,0 +1,52 @@
+import { expect, test } from '@playwright/test'
+import { site } from './site'
+
+test.describe('the front door', () => {
+  test('answers with a document and a main landmark', async ({ page }) => {
+    const response = await page.goto(site.home)
+    expect(response?.status()).toBe(200)
+    await expect(page.locator('main')).toBeAttached()
+  })
+
+  test('404s a path that does not exist, rather than erroring', async ({ request }) => {
+    const response = await request.get(site.missing, { maxRedirects: 0 })
+    expect(response.status()).toBe(404)
+  })
+})
+
+test.describe('the admin', () => {
+  /*
+  The whole admin is one client bundle and the import map it reads. A stale
+  map, a missing environment variable or a plugin that throws at init all
+  surface here as a 500 or a blank screen — and as nothing at all in a test
+  that does not load the page.
+  */
+  test('serves a sign-in screen', async ({ page }) => {
+    const response = await page.goto(site.admin)
+    expect(response?.status()).toBeLessThan(500)
+    await expect(page.getByRole('textbox', { name: /email/i })).toBeVisible({ timeout: 30_000 })
+  })
+})
+
+test.describe('the REST API, to a request with nobody signed in', () => {
+  /*
+  The same rules `src/access/anonymousAccess.test.ts` checks as values, here as
+  responses: proof that nothing between the rule and the wire — a plugin, an
+  endpoint, a framework upgrade — reopened a collection.
+  */
+  for (const slug of site.privateCollections) {
+    test(`refuses to list ${slug}`, async ({ request }) => {
+      const response = await request.get(`/api/${slug}`)
+      expect(response.status()).toBe(403)
+    })
+  }
+
+  for (const slug of site.publicCollections) {
+    test(`lists ${slug}`, async ({ request }) => {
+      const response = await request.get(`/api/${slug}`)
+      expect(response.status()).toBe(200)
+      const body = (await response.json()) as { docs?: unknown }
+      expect(Array.isArray(body.docs)).toBe(true)
+    })
+  }
+})

package/dist/templates/base/apps/web/package.json.template

@@ -9,14 +9,19 @@
     "start": "next start",
     "clean": "rm -rf .next .turbo",
     "typecheck": "tsc --noEmit",
-    "payload": "payload",
-    "generate:types": "payload generate:types",
-    "generate:importmap": "payload generate:importmap",
-    "migrate": "PAYLOAD_MIGRATING=1 payload migrate",
-    "migrate:create": "payload migrate:create",
-    "migrate:status": "payload migrate:status",
+    "payload": "throughline-payload",
+    "payload:reap": "throughline-payload --reap",
+    "generate:types": "throughline-payload generate:types",
+    "generate:importmap": "throughline-payload generate:importmap",
+    "migrate": "PAYLOAD_MIGRATING=1 throughline-payload migrate",
+    "migrate:create": "throughline-payload migrate:create",
+    "migrate:status": "throughline-payload migrate:status",
     "migrate:snapshot": "tsx scripts/write-migration-snapshot.ts",
-    "check:migrations": "tsx scripts/check-migrations.ts"
+    "check:migrations": "tsx scripts/check-migrations.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:smoke": "playwright test",
+    "test:smoke:install": "playwright install --with-deps chromium"
   },
   "dependencies": {
     "@forumone/throughline-approvals": "^{{version_approvals}}",
@@ -30,23 +35,25 @@
     "@forumone/throughline-workflows": "^{{version_workflows}}",
     {{#if useReferenceDs}}"@forumone/throughline-design-contract": "^{{version_design_contract}}",
     "{{designSystemName}}": "workspace:*",
-    {{/if}}"@payloadcms/db-postgres": "^3.83.0",
-    "@payloadcms/next": "^3.83.0",
-    "@payloadcms/plugin-form-builder": "^3.83.0",
-    "@payloadcms/plugin-mcp": "^3.83.0",
-    "@payloadcms/richtext-lexical": "^3.83.0",
+    {{/if}}"@payloadcms/db-postgres": "^3.89.0",
+    "@payloadcms/next": "^3.89.0",
+    "@payloadcms/plugin-form-builder": "^3.89.0",
+    "@payloadcms/plugin-mcp": "^3.89.0",
+    "@payloadcms/richtext-lexical": "^3.89.0",
     "graphql": "^16.8.1",
     "inngest": "^4.2.0",
     "next": "^16.2.4",
-    "payload": "^3.83.0",
+    "payload": "^3.89.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
     "@types/node": "^20.17.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
   }
 }

package/dist/templates/base/apps/web/playwright.config.ts

@@ -0,0 +1,63 @@
+import { defineConfig, devices } from '@playwright/test'
+import { site } from './e2e/site'
+
+/*
+The smoke pack: a real server answering real requests.
+
+The vitest suite (the `*.test.ts` files under `src`) checks values — access rules, field
+validations — and connects to nothing. What it cannot reach is anything true
+only of a *response*: that the admin serves a login screen, that an unknown
+path is a 404 rather than a 500, that the REST API refuses an anonymous read of
+`users` in practice and not only on paper. That is this.
+
+**Deliberately not a functional suite.** It runs against an empty, migrated
+database — CI's `verify` job creates one — so nothing here needs a document to
+exist. Anything that does belongs in a seeded environment.
+
+    pnpm --dir apps/web build && pnpm --dir apps/web test:smoke     # local build
+    E2E_BASE_URL=https://example.org pnpm --dir apps/web test:smoke # deployed
+
+With `E2E_BASE_URL` set the pack runs against that URL and starts no server.
+Every check is a GET, which is what makes pointing it at production defensible;
+adding one that writes would not be. Which routes it checks is in `e2e/site.ts`.
+*/
+
+/*
+`next start`, not `next dev`: headers, caching and rendering are properties of
+the built output, and a pack against `dev` would assert something nobody
+deploys. So this needs `.next/` — in CI the build step has made it; locally,
+run `pnpm build` first.
+
+Hoisted, and spread in only when there is no URL to point at: with
+`exactOptionalPropertyTypes` an explicit `webServer: undefined` is a type
+error, and omitting the key is the only way to say "start nothing".
+*/
+const webServer = {
+  command: `pnpm exec next start --port ${String(site.port)}`,
+  url: `http://127.0.0.1:${String(site.port)}${site.home}`,
+  reuseExistingServer: !process.env.CI,
+  timeout: 120_000,
+  stdout: 'pipe' as const,
+  stderr: 'pipe' as const,
+}
+
+export default defineConfig({
+  testDir: './e2e',
+  outputDir: './e2e/.results',
+
+  // A cold `next start` can lose the first request to a route while it warms.
+  // Nothing here is a visual comparison, so one retry cannot hide a real failure.
+  retries: process.env.CI ? 1 : 0,
+  forbidOnly: Boolean(process.env.CI),
+  reporter: process.env.CI ? [['github'], ['list']] : [['list']],
+  workers: 1,
+
+  use: {
+    baseURL: site.baseURL ?? `http://127.0.0.1:${String(site.port)}`,
+    trace: 'retain-on-failure',
+  },
+
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+
+  ...(site.baseURL ? {} : { webServer }),
+})

package/dist/templates/base/apps/web/src/access/anonymousAccess.test.ts

@@ -0,0 +1,36 @@
+import { describeAnonymousAccess } from '@forumone/throughline-core/testing'
+import config from '../payload.config'
+
+/*
+What a reader with no account can read, as values — no database.
+
+Every query the public site makes runs with nobody signed in, so a collection's
+own `read` rule decides whether a page can see its content. Close one by
+mistake and nothing errors: the page renders empty. Open the wrong one and the
+audit log, the approval queue or the MCP keys are on the internet.
+
+Every collection in the config — yours and the ones the plugins bring — has to
+be in exactly one bucket below. **Adding a collection fails this test until you
+put it in one.** Say where the site reads it, or why it is private.
+*/
+describeAnonymousAccess(config, {
+  renderPath: {
+    // Anonymous reads see published pages only; signed-in users see drafts.
+    pages: 'the page routes, once the frontend renders them',
+    // formsPlugin opens form definitions so a page can render the fields.
+    forms: 'any page that embeds a form',
+  },
+  private: {
+    users: 'accounts',
+    'payload-mcp-api-keys': 'MCP keys are credentials; narrowed to admins in payload.config.ts',
+    'audit-events': 'who did what',
+    approvals: 'who signed off on what',
+    'form-submissions': 'what readers typed into a form',
+    integrations: 'connection settings and sync state',
+    'job-failures': 'background jobs that ran out of retries, with their errors',
+    'payload-kv': 'the key-value store Payload keeps',
+    'payload-locked-documents': 'who is editing what',
+    'payload-preferences': 'admin UI state',
+    'payload-migrations': 'the migration history',
+  },
+})

package/dist/templates/base/apps/web/src/app/api/inngest/route.ts.template

@@ -2,15 +2,18 @@ import type { InngestFunction } from 'inngest'
 import { serve } from 'inngest/next'
 import { getPayload } from 'payload'
 import config from '@/payload.config'
+import { cacheTags } from '@/lib/cache-tags'
 import { createInngestClient } from '@forumone/throughline-core'
 import {
   createAuditEventEchoFunction,
   createExecuteScheduledPublishesFunction,
   createExpireStaleApprovalsFunction,
+  createHealthcheckFailureHandler,
   createHealthcheckFunction,
   createPayloadReachableCheck,
   createPublishAtScheduledTimeFunction,
   createRevalidateOnPublishFunction,
+  createTerminalFailureHandler,
   type ScheduledPublishRequest,
 } from '@forumone/throughline-workflows'
 import { getPublishingService } from '@forumone/throughline-publishing'
@@ -24,6 +27,13 @@ import {
 const inngest = createInngestClient({ id: '{{projectName}}' })
 const payload = await getPayload({ config })
 
+/*
+A workflow that runs out of retries is logged, recorded in the `job-failures`
+collection, and posted to ERROR_WEBHOOK_URL if that is set. Passed to every
+factory below: a factory without it fails silently into Inngest's dashboard.
+*/
+const onTerminalFailure = createTerminalFailureHandler({ payload })
+
 const emailFunctions = getEmailFunctions(payload) ?? []
 const formsFunctions = getFormsFunctions(payload) ?? []
 /*
@@ -43,6 +53,16 @@ async function publishScheduled({ collection, id, reasoning }: ScheduledPublishR
 
 const scheduledCollections = [{ slug: 'pages' }]
 
+/*
+Where each publishable collection's documents are served, so a publish
+revalidates the right path. There are no defaults: a collection missing here
+has its cache tags dropped but no path revalidated, and the run logs a warning.
+Add an entry for every collection you give publishingPlugin.
+*/
+const urlBuilders = {
+  pages: (slug: string) => (slug === 'home' ? '/' : `/${slug}`),
+}
+
 /*
 Typed with this app's own `InngestFunction.Any`. The registry is generic in what
 `createFunctions` returns and defaults to `unknown`, because the platform never
@@ -61,13 +81,20 @@ const integrationFunctions =
 export const { GET, POST, PUT } = serve({
   client: inngest,
   functions: [
-    createRevalidateOnPublishFunction({ inngest, payload }),
+    createRevalidateOnPublishFunction({
+      inngest,
+      payload,
+      urlBuilders,
+      cacheTags,
+      onTerminalFailure,
+    }),
     // On time: sleeps until each document's scheduled time.
     createPublishAtScheduledTimeFunction({
       inngest,
       payload,
       collections: scheduledCollections,
       publish: publishScheduled,
+      onTerminalFailure,
     }),
     // The backstop, for a schedule whose wake-up event never arrived.
     createExecuteScheduledPublishesFunction({
@@ -77,13 +104,16 @@ export const { GET, POST, PUT } = serve({
       publish: publishScheduled,
       schedule: '17 3 * * *',
       overdueByMs: 60 * 60 * 1000,
+      onTerminalFailure,
     }),
-    createExpireStaleApprovalsFunction({ inngest, payload }),
-    createAuditEventEchoFunction({ inngest }),
+    createExpireStaleApprovalsFunction({ inngest, payload, onTerminalFailure }),
+    createAuditEventEchoFunction({ inngest, onTerminalFailure }),
     createHealthcheckFunction({
       inngest,
       payload,
       checks: [createPayloadReachableCheck()],
+      onFailure: createHealthcheckFailureHandler({ payload }),
+      onTerminalFailure,
     }),
     ...emailFunctions,
     ...formsFunctions,

package/dist/templates/base/apps/web/src/instrumentation.ts

@@ -0,0 +1,35 @@
+import type { Instrumentation } from 'next'
+import {
+  buildRequestErrorReport,
+  describeErrorReporting,
+  reportError,
+} from '@forumone/throughline-core/observability'
+
+/*
+Where a server-side error goes.
+
+`onRequestError` fires when Next captures an error in a Server Component
+render, a Route Handler, a Server Action or the proxy — the one place that sees
+all four. It does not see client-side errors; `error.tsx` and
+`global-error.tsx` are the boundaries for those.
+
+The report is logged first, always, and then posted to `ERROR_WEBHOOK_URL` if
+it is set — a log drain, an alerting endpoint, a Slack incoming webhook, a
+proxy in front of whichever tracker you choose. Request headers are copied
+from an allowlist: `cookie` carries the Payload session, and must never leave.
+
+The subpath import keeps the CMS out of this file. This hook runs when
+something has already gone wrong, and loading Payload here would put the whole
+CMS in the one path that has to work regardless.
+*/
+export const onRequestError: Instrumentation.onRequestError = async (error, request, context) => {
+  const report = buildRequestErrorReport(error, request, context)
+  console.error('[error]', JSON.stringify(report))
+  await reportError(report)
+}
+
+/** Once per server instance: say so if error reports are going nowhere. */
+export function register(): void {
+  const status = describeErrorReporting()
+  if (!status.startsWith('error reporting: on')) console.warn('[boot]', status)
+}

package/dist/templates/base/apps/web/src/lib/cache-tags.ts

@@ -0,0 +1,23 @@
+/*
+Next cache tags, named in one place.
+
+A tag has two ends: a reader that caches under it and a hook that drops it.
+Nothing checks that they match, so both build their tags from this object —
+`payload.config.ts` hands it to the revalidation hooks, the Inngest route hands
+it to `createRevalidateOnPublishFunction`, and frontend code that caches a read
+tags it from here too:
+
+    import { unstable_cache } from 'next/cache'
+    import { cacheTags } from '@/lib/cache-tags'
+
+    const getNavigation = unstable_cache(loadNavigation, ['navigation'], {
+      tags: [cacheTags.global('navigation')],
+    })
+
+Change the scheme here and every end moves with it. Imported from the
+package's `/cache-tags` subpath, which imports nothing, so frontend code that
+uses it does not pull in Payload.
+*/
+import { createCacheTags } from '@forumone/throughline-workflows/cache-tags'
+
+export const cacheTags = createCacheTags()

package/dist/templates/base/apps/web/src/payload.config.ts.template

@@ -5,27 +5,68 @@ import type { Access, CollectionConfig } from 'payload'
 import { postgresAdapter } from '@payloadcms/db-postgres'
 import { lexicalEditor } from '@payloadcms/richtext-lexical'
 import {
+  assertEnvironment,
   auditPlugin,
   createInngestClient,
   createMcpToolCollector,
+  mcpApiKeyAccess,
 } from '@forumone/throughline-core'
 import { mcpPlugin } from '@payloadcms/plugin-mcp'
 import { componentsPlugin } from '@forumone/throughline-components'
 import { publishingPlugin } from '@forumone/throughline-publishing'
 import {
+  approvalsEnv,
   approvalsPlugin,
   buildActionUrl,
   generateActionToken,
 } from '@forumone/throughline-approvals'
 import { auditQueryPlugin } from '@forumone/throughline-audit'
 import { integrationsPlugin } from '@forumone/throughline-integrations'
-import { emailPlugin } from '@forumone/throughline-email'
-import { formsPlugin } from '@forumone/throughline-forms'
+import { emailEnv, emailPlugin } from '@forumone/throughline-email'
+import { formsEnv, formsPlugin } from '@forumone/throughline-forms'
+import { createTagRevalidationHooks } from '@forumone/throughline-workflows'
+import { cacheTags } from './lib/cache-tags'
+import { jobFailuresPlugin } from '@forumone/throughline-core/observability'
 import { databaseConnectionString } from './lib/database'
 {{#if useReferenceDs}}import type { Manifest } from '@forumone/throughline-design-contract'
 import designSystemManifest from '{{designSystemName}}/manifest' with { type: 'json' }
 {{/if}}
 
+/*
+Every variable this site needs, checked once and reported together, before any
+plugin runs. Without it each plugin throws on the first thing it finds, in
+registration order, inside `next build`'s "Failed to collect page data" — one
+missing variable per deploy, reading like a build failure.
+
+The plugins' lists are their own declarations of what they refuse to start
+without, so a requirement a plugin adds arrives here with the upgrade. Only the
+site's own variables are written out. A value passed to a plugin as an option
+rather than read from the environment takes that plugin's list out of this call.
+
+Anything that loads this file — `next build`, `payload generate:types`,
+`payload migrate` — needs these set. Where only parsing matters (CI's typecheck
+and type generation), placeholders of the right length do; see
+.github/workflows/ci.yml.
+*/
+assertEnvironment(
+  approvalsEnv,
+  emailEnv,
+  formsEnv,
+  {
+    name: 'PAYLOAD_SECRET',
+    minLength: 32,
+    why: 'Signs Payload sessions and auth tokens. Generate with `openssl rand -base64 48`.',
+  },
+  {
+    name: 'NEXT_PUBLIC_SERVER_URL',
+    why:
+      'The origin approval links are built against, e.g. http://localhost:3000. On a ' +
+      'Vercel preview, set it to https://$VERCEL_URL.',
+  },
+  // Accepts several names (see lib/database.ts), so it is a check, not a name.
+  () => databaseConnectionString(),
+)
+
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
@@ -40,6 +81,14 @@ something nobody fills.
 */
 const mcpTools = createMcpToolCollector()
 
+/*
+Drops a Next cache tag when content changes, named by the same scheme your
+cached reads use (see lib/cache-tags.ts). Give every collection and global that
+a cached read renders a pair of these: afterChange and afterDelete on a
+collection, afterChange on a global. Draft saves and autosave drop nothing.
+*/
+const revalidation = createTagRevalidationHooks({ cacheTags })
+
 // A person in `users` with the admin role. `req.user` can also be an MCP key
 // document, which has no roles and is never an admin, so the collection is
 // checked first — once payload-types.ts exists, TypeScript insists on it.
@@ -71,13 +120,27 @@ const Users: CollectionConfig = {
   ],
 }
 
+// The public site reads with nobody signed in, so a collection it renders needs
+// a read rule that says yes to that. Without one, Payload's default refuses —
+// and the page renders empty rather than erroring. Anonymous readers get a
+// query, so they see published documents only; anybody signed in sees drafts
+// too, which the admin and live preview need. `src/access/anonymousAccess.test.ts`
+// holds every collection to the bucket it is listed in.
+const publishedOrSignedIn: Access = ({ req: { user } }) =>
+  user ? true : { _status: { equals: 'published' } }
+
 // Example Pages collection. Replace this with your real content model;
 // keep the `policy` group on collections that should require approval —
 // the approvals plugin reads that field shape.
 const Pages: CollectionConfig = {
   slug: 'pages',
   admin: { useAsTitle: 'title' },
+  access: { read: publishedOrSignedIn },
   versions: { drafts: true },
+  hooks: {
+    afterChange: [revalidation.afterCollectionChange()],
+    afterDelete: [revalidation.afterCollectionDelete()],
+  },
   fields: [
     { name: 'title', type: 'text', required: true },
     { name: 'slug', type: 'text', required: true, unique: true },
@@ -138,6 +201,11 @@ export default buildConfig({
     // denied to every key with no error anywhere.
     auditPlugin({ inngest }),
 
+    // Where a workflow that ran out of retries, or a failing healthcheck, leaves
+    // a row — see the failure handlers in app/api/inngest/route.ts. Not the
+    // audit log: that records who did what through an MCP tool.
+    jobFailuresPlugin({}),
+
     componentsPlugin({
       {{#if useReferenceDs}}manifest: { type: 'object', manifest: designSystemManifest as unknown as Manifest },
       {{else}}// TODO: point at your design system manifest
@@ -197,7 +265,7 @@ export default buildConfig({
 
     formsPlugin({
       inngest,
-      ipHashSecret: process.env.FORMS_IP_HASH_SECRET!,
+      // ipHashSecret: read from FORMS_IP_HASH_SECRET, checked above.
       // TODO: list every place a form is allowed to send to, and delete the
       // placeholder. The plugin refuses to start with an empty list — the
       // allowlist is the security perimeter — and refuses to deliver anywhere
@@ -216,21 +284,13 @@ export default buildConfig({
 
     integrationsPlugin({ inngest, mcpTools }),
 
-    // Last of the tool-bearing chain. An MCP key is a credential: the plugin
-    // ships its collection with no access rules — "anybody signed in" — so it
-    // is narrowed to admins here.
+    // Last of the tool-bearing chain. An MCP key is a credential that runs
+    // every tool as the person it is bound to, so who may mint, read and
+    // revoke one is an admin's call: `mcpApiKeyAccess` narrows the key
+    // collection to `isAdmin`, and refuses a key principal outright.
     mcpPlugin({
       mcp: { tools: mcpTools.tools },
-      overrideApiKeyCollection: (collection) => ({
-        ...collection,
-        access: {
-          ...collection.access,
-          read: isAdmin,
-          create: isAdmin,
-          update: isAdmin,
-          delete: isAdmin,
-        },
-      }),
+      overrideApiKeyCollection: mcpApiKeyAccess(isAdmin),
     }),
   ],
 })

package/dist/templates/base/apps/web/vitest.config.ts

@@ -0,0 +1,57 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitest/config'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+
+/*
+The cheap tier: vitest in node, with no database and no browser.
+
+Everything here is an invariant over values — the access rules, field
+validations, hooks as functions — and `payload.config.ts` is imported, never
+connected. That is what lets these run on every pull request, in CI's `fast`
+job, which has no database. Anything that needs one belongs in `verify`, and
+anything true only of a real response belongs in the smoke pack (`e2e/`).
+
+`environment: 'node'`, deliberately: nothing in `apps/web` renders here. The
+components live in the design system, whose own suite runs them.
+*/
+export default defineConfig({
+  /*
+  The two aliases `tsconfig.json` declares. Next resolves them from that file
+  and vitest does not, so a module importing `@/lib/…` or `@payload-config`
+  cannot be loaded here unless they are repeated.
+  */
+  resolve: {
+    alias: {
+      '@payload-config': path.join(here, 'src/payload.config.ts'),
+      '@': path.join(here, 'src'),
+    },
+  },
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    /*
+    Enough for `payload.config.ts` to load, and nothing more.
+
+    The plugins check their secrets when the config is built, so importing it
+    needs every value present. None is a credential: the secrets are padded
+    placeholders, the address is under `.invalid`, which RFC 2606 reserves so
+    it can never resolve, and the connection string names a database nobody
+    has. That is safe because the config *parses* the string and never
+    connects — the same fact CI's `fast` job relies on.
+
+    Set here rather than left to the shell, so `pnpm test` needs no setup and a
+    `DATABASE_URI` somebody exported for a migration cannot reach a test.
+    */
+    env: {
+      DATABASE_URI: 'postgres://test:test@localhost:5432/does-not-exist',
+      PAYLOAD_SECRET: 'test-only-not-a-real-secret-000000000000',
+      APPROVAL_TOKEN_SECRET: 'test-only-not-a-real-secret-000000000000',
+      FORMS_IP_HASH_SECRET: 'test-only-not-a-real-secret-000000000000',
+      RESEND_API_KEY: 're_test_only_not_a_real_key',
+      EMAIL_FROM_ADDRESS: 'test-only@example.invalid',
+      NEXT_PUBLIC_SERVER_URL: 'http://localhost:3000',
+    },
+  },
+})

package/dist/templates/base/claude/hooks/gate.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Stop hook: run the cheap half of CI's gate — typecheck and lint — when a
+# session ends with pending changes under apps/ or design-system/.
+#
+# Why a hook and not only CI: these failures are cheap to fix in the session
+# that caused them and expensive later. A session that touched nothing exits in
+# milliseconds, which is what keeps this cheap enough to leave switched on.
+#
+# Deliberately not here: tests, manifest validation, the generated-files check
+# and the build. They take minutes or need a database; they are CI's job. See
+# CLAUDE.md for the whole gate.
+#
+# This reports. It never blocks and never edits, so it cannot wedge a session on
+# a failure it cannot resolve. Exit is always 0. Set THROUGHLINE_SKIP_GATE=1 to
+# silence it, for instance in headless sessions that run their own gate.
+
+set -uo pipefail
+
+[[ -z "${THROUGHLINE_SKIP_GATE:-}" ]] || exit 0
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[[ -n "$ROOT" ]] || exit 0
+
+if [[ -z "$(git -C "$ROOT" status --porcelain -- apps design-system 2>/dev/null)" ]]; then
+  exit 0
+fi
+
+cd "$ROOT" || exit 0
+
+OUTPUT="$(pnpm typecheck 2>&1 && pnpm lint 2>&1)"
+STATUS=$?
+
+if [[ $STATUS -eq 0 ]]; then
+  MESSAGE="Gate clean: typecheck + lint. Tests, validate, check-generated and the build are CI's job — see CLAUDE.md."
+else
+  # The failing rule or type error is at the end, and a systemMessage is read
+  # in a terminal, not scrolled.
+  MESSAGE="Gate FAILED (typecheck/lint) — CI will fail on this:
+
+$(printf '%s' "$OUTPUT" | tail -25)"
+fi
+
+node -e 'process.stdout.write(JSON.stringify({ systemMessage: process.argv[1], suppressOutput: true }))' "$MESSAGE"
+exit 0

package/dist/templates/base/claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "GATE=\"$(git rev-parse --show-toplevel 2>/dev/null)/.claude/hooks/gate.sh\"; [ -f \"$GATE\" ] && exec bash \"$GATE\" || exit 0",
+            "timeout": 180,
+            "statusMessage": "Running the gate (typecheck + lint)…"
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/templates/base/github/workflows/ci.yml

@@ -5,8 +5,9 @@ name: CI
 #   fast    every pull request and every push to main. No database: every gate
 #           here needs the config to parse, not to connect.
 #   verify  pushes to main, and on demand. A Postgres service, the migrations,
-#           and a production build — `next build` boots Payload to collect page
-#           data, so it needs a migrated database.
+#           a production build — `next build` boots Payload to collect page
+#           data, so it needs a migrated database — and the Playwright smoke
+#           pack against `next start` on that build.
 #
 # A green `fast` is what a pull request is reviewed on; `verify` is what says
 # main still builds and migrates. Add a path filter to run `verify` on pull
@@ -129,3 +130,14 @@ jobs:
 
       - name: Build
         run: pnpm build
+
+      # The smoke pack (apps/web/e2e): `next start` on the build above, against
+      # the empty database migrated above, asserting only what answers without
+      # content — the front door, a 404, the admin sign-in screen, and the REST
+      # API refusing an anonymous read of private collections. Here and not in
+      # `fast`, because the server needs a database to answer at all.
+      - name: Install Chromium for the smoke pack
+        run: pnpm --dir apps/web test:smoke:install
+
+      - name: Smoke test
+        run: pnpm --dir apps/web test:smoke

package/dist/templates/base/gitignore

@@ -13,3 +13,12 @@ dist/
 .vscode/
 
 coverage/
+
+# Written by throughline-payload (@forumone/throughline-core): the process
+# group of each in-flight Payload CLI run, so the next run can reap one whose
+# runner was killed before it could clean up.
+.payload-cli-pids
+
+# Playwright: traces and screenshots from a failed smoke run
+e2e/.results/
+playwright-report/

package/dist/templates/base/package.json.template

@@ -15,6 +15,7 @@
     "check:tested": "tsx scripts/check-tested-packages.ts",
     "check:audit": "tsx scripts/check-audit.ts",
     "check:migrations": "pnpm --dir apps/web run check:migrations",
+    "payload:reap": "pnpm --dir apps/web run payload:reap",
     "format": "prettier --write ."
   },
   "devDependencies": {

package/dist/templates/base/scripts/check-tested-packages.ts

@@ -25,8 +25,6 @@ after the package that caused them.
  * by the same change that makes it untrue.
  */
 const ACCEPTED: Record<string, string> = {
-  'apps/web':
-    'Freshly scaffolded: the config and routes are generated wiring. Delete this entry with your first test here — an access rule, a hook or a field validation is the place to start.',
 {{#if useReferenceDs}}{{else}}  'design-system':
     'Placeholder until the design system is written. Delete this entry with its first component.',
 {{/if}}}

package/dist/templates/with-reference-ds/design-system/src/components/Divider/Divider.contract.ts

@@ -26,6 +26,7 @@ export const contract: ComponentContract = {
         name: 'decorative',
         type: 'boolean',
         required: false,
+        defaultValue: true,
         constraints: 'When true (default), the divider is aria-hidden',
       },
     ],

package/dist/versions.json

@@ -1,14 +1,14 @@
 {
-  "@forumone/throughline-approvals": "0.8.8",
-  "@forumone/throughline-audit": "0.5.4",
-  "@forumone/throughline-components": "0.5.7",
-  "@forumone/throughline-core": "0.9.1",
+  "@forumone/throughline-approvals": "0.9.0",
+  "@forumone/throughline-audit": "0.6.0",
+  "@forumone/throughline-components": "0.6.0",
+  "@forumone/throughline-core": "0.10.0",
   "@forumone/throughline-design-contract": "0.6.0",
-  "@forumone/throughline-email": "0.2.12",
-  "@forumone/throughline-forms": "0.6.4",
-  "@forumone/throughline-integrations": "0.8.5",
-  "@forumone/throughline-plugin-contract": "0.4.1",
-  "@forumone/throughline-publishing": "0.10.0",
-  "@forumone/throughline-reference-ds": "0.3.6",
-  "@forumone/throughline-workflows": "0.4.0"
+  "@forumone/throughline-email": "0.3.0",
+  "@forumone/throughline-forms": "0.7.0",
+  "@forumone/throughline-integrations": "0.9.0",
+  "@forumone/throughline-plugin-contract": "0.5.0",
+  "@forumone/throughline-publishing": "0.11.0",
+  "@forumone/throughline-reference-ds": "0.3.7",
+  "@forumone/throughline-workflows": "0.5.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumone/create-throughline",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Scaffolder for new Throughline projects (Payload CMS + MCP servers + Inngest workflows).",
   "type": "module",
   "bin": {
@@ -44,13 +44,14 @@
     "picocolors": "^1.1.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
     "@types/node": "^20.17.0",
     "eslint": "^10.11.0",
     "tsx": "^4.21.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.10",
-    "@forumone/throughline-tsconfig": "0.0.0",
-    "@forumone/throughline-eslint-config": "0.0.0"
+    "@forumone/throughline-eslint-config": "0.0.0",
+    "@forumone/throughline-tsconfig": "0.0.0"
   },
   "engines": {
     "node": ">=20.9.0"