@clubedge/create-clubedge-app 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.14.1
+
+- Default to Starter `v0.13.1`. In projects with background jobs or observability, a configuration error such as a missing `DATABASE_URL` no longer stops the server at startup; pages that need no database keep working, and the error is reported once.
+
 ## 0.14.0
 
 - Default to Starter `v0.13.0`, which adds observability (`--observability otel|sentry`): request tracing and server error reporting through OpenTelemetry, to any OTLP collector, or Sentry, behind provider-neutral hooks in `@clubedge/core`. `--observability` needs no CLI code: it comes from the Starter's manifest.

package/README.md

@@ -1,76 +1,57 @@
+<div align="center">
+
 # create-clubedge-app
 
-[![CI](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml)
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+**Create a production-ready Next.js or TanStack Start app with one command, and keep it up to date.**
 
-Create a Next.js or TanStack Start application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
+Pick only the modules you need: auth, storage, email, payments, jobs, observability, deployment.<br>
+Add, remove, or upgrade them later without losing your own changes.
 
-The CLI downloads a tested Starter release, names the generated project, creates `apps/web/.env.local` from the example, initializes Git, and installs dependencies. The Starter remains the source of truth for the generated architecture.
+[![npm](https://img.shields.io/npm/v/@clubedge/create-clubedge-app?style=flat-square)](https://www.npmjs.com/package/@clubedge/create-clubedge-app)
+[![npm downloads](https://img.shields.io/npm/dm/@clubedge/create-clubedge-app?style=flat-square)](https://www.npmjs.com/package/@clubedge/create-clubedge-app)
+[![CI](https://img.shields.io/github/actions/workflow/status/Clubedge/create-clubedge-app/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/Clubedge/create-clubedge-app?style=flat-square)](https://github.com/Clubedge/create-clubedge-app/releases)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](LICENSE)
 
-## Version relationship
+[Website](https://starter.clubedge.live) ·
+[Clubedge Starter](https://github.com/Clubedge/clubedge-starter) ·
+[Changelog](CHANGELOG.md) ·
+[Roadmap](ROADMAP.md) ·
+[Contributing](CONTRIBUTING.md)
 
-Each CLI release is tested against one specific Starter release:
+</div>
 
-```text
-create-clubedge-app v0.14.0
-        |
-        v
-Clubedge Starter v0.13.0
-commit 62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app
 ```
 
-The current relationship is:
-
-| CLI release | Default Starter release | Meaning |
-| --- | --- | --- |
-| `create-clubedge-app@0.14.0` | `clubedge-starter@v0.13.0` | The CLI's required, tested default |
-
-This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
+## Why create-clubedge-app
 
-The `v0.13.0` tag is expected to resolve to commit
-`62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50`. The CLI verifies this before
-scaffolding with the default reference and fails rather than silently using a
-moved tag.
+Copying a starter is easy; living with it is not. You delete the services you don't use by hand, and once you've changed the code, every later improvement to the starter has to be copied over by hand too.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.13.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+create-clubedge-app generates a project from a tested release of [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) with only the modules you choose. A module you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The project records exactly what it was generated from, so later the CLI can add a module, remove one, or upgrade to a newer Starter release by merging the change into your code. Files you never touched are updated; your edits are kept.
 
-## Requirements
+Every CLI release is pinned to one Starter release and verified against it, so the same command always produces the same project.
 
-- Node.js 22.12 or newer.
-- pnpm 10.9.0 or newer. The generated project is a pnpm workspace, so dependencies are installed with pnpm even when you start the CLI with `npx`; the CLI falls back to `corepack pnpm` when `pnpm` is not on your path.
-- Git, when using the default Git initialization.
-- Internet access to install dependencies. The default Starter release ships inside the CLI package, so GitHub is only contacted for `--ref`.
+## Quick start
 
-## Usage
+You need Node.js 22.12 or newer and pnpm 10.9.0 or newer. Git is used for the default repository initialization.
 
 ```sh
 pnpm dlx @clubedge/create-clubedge-app my-app
-```
-
-Or run it with npm:
-
-```sh
-npx @clubedge/create-clubedge-app my-app
-```
-
-After scaffolding:
-
-```sh
 cd my-app
 pnpm dev
 ```
 
-The generated project includes `.env.local`; fill in `DATABASE_URL` to start the app and configure Supabase Auth or other providers as needed. The root route is a project-named landing page, and the reference dashboard is available at `/dashboard`. See its `SETUP.md` for database, Redis, storage, and Docker setup.
+Or start it with npm: `npx @clubedge/create-clubedge-app my-app`. The generated project is a pnpm workspace, so dependencies are installed with pnpm either way; the CLI falls back to `corepack pnpm` when `pnpm` is not on your path. Without a destination, the CLI asks where to create the project.
 
-When no destination is provided, the CLI asks where to create the project:
+The generated project includes `apps/web/.env.local`, created from the example and pointing at the local services you chose. Its `SETUP.md` describes every variable and provider. The root route is a landing page named after your project, and the dashboard is at `/dashboard`.
 
-```sh
-pnpm dlx @clubedge/create-clubedge-app
-```
+The default Starter release ships inside the CLI package, so GitHub is only contacted when you pass `--ref`. Internet access is needed to install dependencies.
 
-### Choosing a framework
+## Choosing a framework
 
-The Starter ships the same application for two React frameworks. Next.js is the default; pick TanStack Start with `--framework`, or choose interactively when the Starter offers more than one:
+The Starter ships the same application for two React frameworks. Next.js is the default; pick TanStack Start with `--framework`, or choose interactively:
 
 ```sh
 pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
@@ -83,9 +64,9 @@ pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
 
 Either way, the app lives in `apps/web` and uses the same shared packages, so the project layout, root scripts, and Docker commands are identical.
 
-### Choosing services
+## Choosing modules
 
-Authentication, file storage, caching, email, payments, background jobs, observability, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
+Authentication, file storage, caching, email, payments, background jobs, observability, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
@@ -101,35 +82,40 @@ Authentication, file storage, caching, email, payments, background jobs, observa
 
 ```sh
 # Only the monorepo, UI, database, and tooling
-pnpm dlx @clubedge/create-clubedge-app my-app --auth none --storage none --cache memory
+pnpm dlx @clubedge/create-clubedge-app my-app --auth none --storage none --cache memory --email none
+
+# A SaaS starting point: your own auth, payments, and background jobs, no Docker needed
+pnpm dlx @clubedge/create-clubedge-app my-app --auth better-auth --payments stripe --jobs pg-boss --infra local
 ```
 
-Interactive runs ask whether to customize these after the framework question. The options come from the Starter's manifest, so `--help` lists the ones the bundled Starter offers.
+Interactive runs ask whether to customize these after the framework question.
 
 ## Options
 
 ```text
-Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
-
---framework <id>        App framework: next (default) or tanstack-start
---auth <id>             Authentication: supabase (default), better-auth, or none
---storage <id>          File storage: s3 (default), supabase, or none
---cache <id>            Cache and rate limits: redis (default) or memory
---infra <id>            Local services: docker (default), supabase, local, or none
---ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
---template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
---dry-run               Show what would be created without writing anything
--y, --yes               Accept defaults and never prompt (default directory: my-app)
---no-install            Skip dependency installation
---no-git                Skip Git initialization
--h, --help              Show help
--v, --version           Show the CLI version
+Usage:
+  pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
+  pnpm dlx @clubedge/create-clubedge-app add [module] [option]   (inside a project)
+  pnpm dlx @clubedge/create-clubedge-app remove [module]         (inside a project)
+  pnpm dlx @clubedge/create-clubedge-app upgrade [--ref <tag>]   (inside a project)
+
+Options:
+  --framework <id>        App framework, such as next or tanstack-start
+  --<module> <option>     A module option, such as --auth none; the Starter lists its modules
+  --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
+                          (upgrade: the Starter to upgrade to)
+  --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
+  --dry-run               Show what would be created or changed without writing anything
+  --force                 add/remove: change a project with uncommitted changes or without Git
+  -y, --yes               Accept defaults and never prompt (default directory: my-app)
+  --no-install            Skip dependency installation
+  --no-git                Skip Git repository initialization
+  -h, --help              Show this help
+  -v, --version           Show the CLI version
 ```
 
 The target directory must be empty or not exist. The CLI never deletes or overwrites existing files, and if scaffolding fails it removes whatever it wrote, so a failed run leaves nothing behind.
 
-Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
-
 ```sh
 # Preview the files and edits without writing anything
 pnpm dlx @clubedge/create-clubedge-app my-app --dry-run
@@ -141,7 +127,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.13.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.13.1
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -158,7 +144,7 @@ pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add aut
 pnpm dlx @clubedge/create-clubedge-app remove storage
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.13.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.13.1 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -171,6 +157,35 @@ The CLI renders the project twice, from the Starter commit and modules recorded
 
 The project must be a Git repository without uncommitted changes, so you can review the result with `git diff` and undo it. Pass `--force` to skip this check. Add `--no-install` to skip `pnpm install`. Afterward, run `pnpm db:migrate` and `pnpm check:services` if the change added tables or services.
 
+## Version relationship
+
+Each CLI release is tested against one specific Starter release:
+
+```text
+create-clubedge-app v0.14.1
+        |
+        v
+Clubedge Starter v0.13.1
+commit 28bfbf98c85ae500ace6a062dd10d67746e1a330
+```
+
+The current relationship is:
+
+| CLI release | Default Starter release | Meaning |
+| --- | --- | --- |
+| `create-clubedge-app@0.14.1` | `clubedge-starter@v0.13.1` | The CLI's required, tested default |
+
+This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
+
+The `v0.13.1` tag is expected to resolve to commit
+`28bfbf98c85ae500ace6a062dd10d67746e1a330`. The CLI verifies this before
+scaffolding with the default reference and fails rather than silently using a
+moved tag.
+
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.13.1`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+
+Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
+
 ## How it works
 
 Each CLI release bundles one Starter release. When the release is built, `scripts/bundle-template.mjs` clones the pinned Starter tag, verifies that it resolves to the pinned commit, and copies its tracked files into the package (`template/` and `template.lock.json`). Running the CLI then needs no GitHub access for the default Starter.
@@ -182,11 +197,23 @@ The CLI first builds a plan (the files to copy and the edits to make), which `--
 ```text
 src/
   cli/      argument parsing and terminal output
-  core/     manifest, template sources, customizations, planning, and execution
+  core/     manifest, template sources, customizations, planning, merging, and execution
   steps/    Git initialization and dependency installation
   utils/    file listing and copying, processes, and naming
 ```
 
+## Documentation
+
+| I want to | Read |
+| --- | --- |
+| Configure a generated project | Its `SETUP.md`, also in the [Starter repository](https://github.com/Clubedge/clubedge-starter/blob/main/SETUP.md) |
+| Change modules or upgrade a project | [Change an existing project](#change-an-existing-project) |
+| Reproduce an exact Starter version | [Version relationship](#version-relationship) |
+| See what changed in each release | [CHANGELOG.md](CHANGELOG.md) |
+| See what is planned next | [ROADMAP.md](ROADMAP.md) |
+| Contribute code | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Report a security problem | [SECURITY.md](SECURITY.md) |
+
 ## Development
 
 ```sh
@@ -200,7 +227,7 @@ node ./bin/create.mjs my-app --template-dir ../clubedge-starter --dry-run
 
 Without a bundled template, a local build downloads the pinned Starter release from GitHub and verifies its commit. Run `pnpm bundle-template` to bundle it, or `pnpm bundle-template --from ../clubedge-starter` to bundle a local checkout.
 
-CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarball, installs its dependencies, runs linting, typechecking, unit tests, browser checks, and a production build, then starts the generated app and checks the landing page, sign-up page, dashboard, health endpoint, logo, and favicon. A scheduled, non-blocking compatibility job also checks Starter `main`.
+CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarball, installs their dependencies, runs linting, typechecking, unit tests, browser checks, and a production build, then starts each generated app and checks the landing page, sign-up page, dashboard, health endpoint, logo, and favicon. It also adds and removes modules in an existing project and upgrades a project from an older Starter. A scheduled, non-blocking compatibility job checks Starter `main`.
 
 ## Release workflow
 
@@ -209,7 +236,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.13.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.13.1`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -221,9 +248,28 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 
 The required CI job always tests the pinned default. The scheduled compatibility job tests Starter `main` early, but unreleased Starter changes must not change the stable CLI default.
 
-## Contributing
+## Roadmap
+
+Each phase ends with a Starter release and a CLI release pinned to it. The full plan is in [ROADMAP.md](ROADMAP.md).
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull request guidance, and [ROADMAP.md](ROADMAP.md) for the planned phases. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+| CLI release | Starter release | Theme |
+| --- | --- | --- |
+| 0.5.0 to 0.9.0 | v0.5.0 to v0.8.0 | Optional modules, local services, `add`, `remove`, and `upgrade` |
+| 0.10.0 | v0.9.0 | Module flags from the Starter's manifest, and email |
+| 0.11.0 | v0.10.0 | Deployment |
+| 0.12.0 | v0.11.0 | Payments |
+| 0.13.0 | v0.12.0 | Background jobs |
+| 0.14.0 | v0.13.0 | Observability |
+| next | | `status` and `doctor` commands, several modules in one change, macOS CI |
+
+## Community
+
+- **[Issues](https://github.com/Clubedge/create-clubedge-app/issues)** for problems creating, changing, or upgrading a project.
+- **[Clubedge Starter issues](https://github.com/Clubedge/clubedge-starter/issues)** for problems in the generated application itself.
+- **[Pull requests](https://github.com/Clubedge/create-clubedge-app/pulls)** are welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).
+- **Security problems** go through the private process in [SECURITY.md](SECURITY.md), not public issues.
+
+Everyone taking part is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.13.0",
-    "starterCommit": "62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50"
+    "starterRef": "v0.13.1",
+    "starterCommit": "28bfbf98c85ae500ace6a062dd10d67746e1a330"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/README.md

@@ -1,38 +1,75 @@
+<!-- clubedge:if starter-repository -->
+<div align="center">
+
 # Clubedge Starter
 
-[![CI](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml)
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+**A production-ready full-stack TypeScript starter that ships only the modules you choose.**
 
-Clubedge Starter is a production-oriented, modular React application foundation. It brings together a pnpm monorepo, shared shadcn/ui components, PostgreSQL access through Drizzle, replaceable infrastructure providers, and a working example dashboard. It provides engineering conventions and a reference implementation; review its security and deployment choices for your application before production use.
+Next.js or TanStack Start on PostgreSQL, with optional auth, storage, email, payments,<br>
+background jobs, observability, and deployment, each behind an interface you can replace.
 
-<!-- clubedge:if starter-repository -->
+[![CI](https://img.shields.io/github/actions/workflow/status/Clubedge/clubedge-starter/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml)
+[![Generated projects](https://img.shields.io/github/actions/workflow/status/Clubedge/clubedge-starter/starter.yml?branch=main&label=generated%20projects&style=flat-square)](https://github.com/Clubedge/clubedge-starter/actions/workflows/starter.yml)
+[![Release](https://img.shields.io/github/v/release/Clubedge/clubedge-starter?style=flat-square)](https://github.com/Clubedge/clubedge-starter/releases)
+[![npm](https://img.shields.io/npm/v/@clubedge/create-clubedge-app?label=create-clubedge-app&style=flat-square)](https://www.npmjs.com/package/@clubedge/create-clubedge-app)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](LICENSE)
+
+[Website](https://starter.clubedge.live) ·
+[Create a project](https://github.com/Clubedge/create-clubedge-app) ·
+[Setup guide](SETUP.md) ·
+[Roadmap](ROADMAP.md) ·
+[Releases](https://github.com/Clubedge/clubedge-starter/releases)
+
+</div>
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app
+```
 
-This repository contains the same application for two frameworks, Next.js (`apps/web`) and TanStack Start (`apps/start`), plus every optional module. [create-clubedge-app](https://github.com/Clubedge/create-clubedge-app) generates a project with one framework and only the modules you choose; sections of this README marked for a framework or module appear only in projects that use it. Contributions and bug reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Repository maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist, and [ROADMAP.md](ROADMAP.md) describes the planned phases.
+## Why Clubedge Starter
 
+Most starters give you one stack and leave you to rip out what you don't need. Removing a provider means hunting down its package, its environment variables, its docs, and its lockfile entries, and once you have changed the code, a newer version of the starter is something you can only copy from by hand.
+
+Clubedge Starter is built the other way around. Every service is an optional module, and a module you leave out is removed completely. Each provider sits behind an interface in its own package, so you can swap Supabase Auth for Better Auth, or OpenTelemetry for Sentry, without touching your pages. And because [create-clubedge-app](https://github.com/Clubedge/create-clubedge-app) records exactly what your project was generated from, it can add, remove, or upgrade modules later by merging the change into your code, keeping your edits.
+
+Every combination in the CI matrix is generated as a real project and runs its full pipeline: install, lint, typecheck, unit tests, browser tests against real local services, a production build, and a smoke test.
+
+<!-- In generated projects, the block below supplies the title that create-clubedge-app replaces with the project's name; its comment keeps it hidden here. -->
+<!-- clubedge:end -->
+<!-- clubedge:if framework=next|tanstack-start
+# Clubedge Starter
 <!-- clubedge:end -->
 
 ## Features
 
+**Application**
+
 - Next.js App Router with React, TypeScript, Tailwind CSS 4, and shadcn/ui using Base UI primitives. <!-- clubedge:only framework=next -->
 - TanStack Start with React, TypeScript, Vite, Tailwind CSS 4, and shadcn/ui using Base UI primitives. <!-- clubedge:only framework=tanstack-start -->
 - pnpm workspaces and Turborepo, with the web app in `apps/web` and framework-agnostic packages under `packages/`.
 - Drizzle ORM and PostgreSQL schema, migrations, and seed commands.
+- Zod environment validation, security headers, structured errors, and `/api/health`.
+- A landing page and a working dashboard built from the shared UI package.
+
+**Modules**
+
 - Supabase Auth with server-verified sessions in secure cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=supabase -->
 - Better Auth with users and sessions in your own PostgreSQL, secure session cookies, a protected dashboard, and rate-limited sign-in. <!-- clubedge:only auth=better-auth -->
 - Password reset by email, and email verification that can be required before sign-in. <!-- clubedge:only auth=better-auth && email!=none -->
 - Password reset by email, sent by Supabase. <!-- clubedge:only auth=supabase -->
+- Email over SMTP, for any provider or a local inbox; development prints emails to the server log until SMTP is configured. <!-- clubedge:only email=smtp -->
+- Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
 - S3-compatible storage adapter for AWS S3, Cloudflare R2, and MinIO. <!-- clubedge:only storage=s3 -->
 - Supabase Storage adapter that uses the signed-in user's session. <!-- clubedge:only storage=supabase -->
 - Fixed-window rate limiter and cache on Redis, falling back to process memory without `REDIS_URL`. <!-- clubedge:only cache=redis -->
 - Fixed-window rate limiter and cache in process memory, suited to a single server instance. <!-- clubedge:only cache=memory -->
-- Email over SMTP, for any provider or a local inbox; development prints emails to the server log until SMTP is configured. <!-- clubedge:only email=smtp -->
-- Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
 - Subscriptions with Stripe Checkout and the customer portal, kept in sync by verified webhooks, behind a provider-neutral payments interface. <!-- clubedge:only payments=stripe -->
 - Background jobs with retries and schedules, stored in PostgreSQL by pg-boss and run by a worker inside the app server, behind a provider-neutral jobs interface. <!-- clubedge:only jobs=pg-boss -->
 - Server error reporting and request tracing with OpenTelemetry, to any OTLP collector, behind a provider-neutral observability interface. <!-- clubedge:only observability=otel -->
 - Server error reporting and request tracing with Sentry, behind a provider-neutral observability interface. <!-- clubedge:only observability=sentry -->
-- Zod environment validation, security headers, structured errors, and `/api/health`.
-- Docker support, GitHub Actions CI, Vitest, Playwright, ESLint, and Prettier.
+
+**Production**
+
 - A production image that includes its own migrator (`node /app/migrate.mjs`), for running migrations before each release.
 - A manual deploy workflow for the chosen platform, and a readiness endpoint (`/api/ready`) that checks the database.
 - Deployment to Fly.io with `fly.toml`: migrations run as the release command. <!-- clubedge:only deploy=fly -->
@@ -41,52 +78,42 @@ This repository contains the same application for two frameworks, Next.js (`apps
 - Deployment to Vercel with `apps/web/vercel.json`: migrations run during the build. <!-- clubedge:only deploy=vercel -->
 - Deployment to Netlify with `apps/web/netlify.toml`: migrations run during the build. <!-- clubedge:only deploy=netlify -->
 
-## Architecture
+**Quality**
 
-```mermaid
-flowchart TB
-  %% clubedge:if framework=next
-  Browser --> App[Next.js application]
-  %% clubedge:end
-  %% clubedge:if framework=tanstack-start
-  Browser --> App[TanStack Start application]
-  %% clubedge:end
-  App -->|Drizzle ORM| DB[(PostgreSQL)]
-  %% clubedge:if auth=supabase
-  App -->|auth interface and server sessions| Auth[Supabase Auth]
-  %% clubedge:end
-  %% clubedge:if auth=better-auth
-  App -->|auth interface and server sessions| Auth[Better Auth]
-  Auth -->|users and sessions| DB
-  %% clubedge:end
-  %% clubedge:if cache=redis
-  App -->|cache and rate limits| Redis[(Redis, or memory)]
-  %% clubedge:end
-  %% clubedge:if email=smtp
-  App -->|email interface| SMTP[SMTP server, or the log]
-  %% clubedge:end
-  %% clubedge:if email=resend
-  App -->|email interface| Resend[Resend, or the log]
-  %% clubedge:end
-  %% clubedge:if storage=s3
-  App -->|storage interface| S3[S3-compatible storage: AWS S3, R2, MinIO]
-  %% clubedge:end
-  %% clubedge:if storage=supabase
-  App -->|storage interface| SupabaseStorage[Supabase Storage]
-  %% clubedge:end
-```
+- GitHub Actions CI with Vitest, Playwright, ESLint, and Prettier.
+- `pnpm check:services`, which proves the app can reach every configured service with a real round trip.
 
-### Architecture principles
+<!-- clubedge:if starter-repository -->
 
-- **PostgreSQL is the source of truth for application data.** Drizzle centralizes application schema, queries, and migrations.
-- **Authentication stays separate from application data.** The auth provider owns credentials and sessions; application tables are managed by Drizzle. <!-- clubedge:only auth!=none -->
-- **Providers sit behind interfaces.** Interfaces live in `packages/{auth,storage,cache}` and each provider in its own package, so replacing a provider does not touch application code.
-- **Shared packages are framework-agnostic.** Packages under `packages/` receive configuration and request cookies as arguments and never import a web framework. ESLint enforces these boundaries.
-- **One composition root.** `apps/web/src/server/` is the only place that reads environment variables and chooses providers. Routes and components call it rather than a provider SDK.
-- **Keep the baseline focused.** Additional providers, queues, and generator tooling should be added when a real use case calls for them.
+## Modules
+
+Pick modules when you create a project, and change them later with `pnpm clubedge add` and `pnpm clubedge remove`.
+
+| Module        | Options                                                   | Default    |
+| ------------- | --------------------------------------------------------- | ---------- |
+| Framework     | `next`, `tanstack-start`                                  | `next`     |
+| Auth          | `supabase`, `better-auth`, `none`                         | `supabase` |
+| Storage       | `s3`, `supabase`, `none`                                  | `s3`       |
+| Cache         | `redis`, `memory`                                         | `redis`    |
+| Email         | `smtp`, `resend`, `none`                                  | `smtp`     |
+| Payments      | `stripe`, `none`                                          | `none`     |
+| Jobs          | `pg-boss`, `none`                                         | `none`     |
+| Observability | `otel`, `sentry`, `none`                                  | `none`     |
+| Local infra   | `docker`, `supabase`, `local` (no Docker), `none`         | `docker`   |
+| Deploy        | `docker`, `fly`, `railway`, `render`, `vercel`, `netlify` | `docker`   |
+
+A module you leave out takes its packages, provider SDK, environment variables, documentation, and lockfile entries with it.
+
+<!-- clubedge:end -->
 
 ## Quick start
 
+<!-- clubedge:if starter-repository -->
+
+To start a new application, create a project with the CLI as shown above; it contains only your modules. The steps below run this repository itself, with every module, for working on the Starter.
+
+<!-- clubedge:end -->
+
 ### Requirements
 
 - Node.js 22.12 or newer (Node.js 22 LTS recommended).
@@ -156,6 +183,65 @@ pnpm dev
 
 Open <http://localhost:3000> for the landing page, <http://localhost:3000/dashboard> for the dashboard, or <http://localhost:3000/api/health> for the liveness endpoint. The pages render without connecting to providers; database and provider operations require their configuration.
 
+> [!NOTE]
+> This is a foundation and a reference implementation. Review its security and deployment choices for your application before you go to production; [SETUP.md](SETUP.md#before-deploying) has a checklist.
+
+## How it works
+
+```mermaid
+flowchart TB
+  %% clubedge:if framework=next
+  Browser --> App[Next.js application]
+  %% clubedge:end
+  %% clubedge:if framework=tanstack-start
+  Browser --> App[TanStack Start application]
+  %% clubedge:end
+  App -->|Drizzle ORM| DB[(PostgreSQL)]
+  %% clubedge:if auth=supabase
+  App -->|auth interface and server sessions| Auth[Supabase Auth]
+  %% clubedge:end
+  %% clubedge:if auth=better-auth
+  App -->|auth interface and server sessions| Auth[Better Auth]
+  Auth -->|users and sessions| DB
+  %% clubedge:end
+  %% clubedge:if cache=redis
+  App -->|cache and rate limits| Redis[(Redis, or memory)]
+  %% clubedge:end
+  %% clubedge:if email=smtp
+  App -->|email interface| SMTP[SMTP server, or the log]
+  %% clubedge:end
+  %% clubedge:if email=resend
+  App -->|email interface| Resend[Resend, or the log]
+  %% clubedge:end
+  %% clubedge:if storage=s3
+  App -->|storage interface| S3[S3-compatible storage: AWS S3, R2, MinIO]
+  %% clubedge:end
+  %% clubedge:if storage=supabase
+  App -->|storage interface| SupabaseStorage[Supabase Storage]
+  %% clubedge:end
+  %% clubedge:if payments=stripe
+  App -->|payments interface| Stripe[Stripe Checkout and portal]
+  Stripe -->|verified webhooks| App
+  %% clubedge:end
+  %% clubedge:if jobs=pg-boss
+  App -->|jobs interface, worker in the server| Jobs[pg-boss]
+  Jobs -->|jobs table| DB
+  %% clubedge:end
+  %% clubedge:if observability=otel
+  App -->|traces and errors| Otel[OTLP collector]
+  %% clubedge:end
+  %% clubedge:if observability=sentry
+  App -->|traces and errors| Sentry[Sentry]
+  %% clubedge:end
+```
+
+- **PostgreSQL is the source of truth for application data.** Drizzle centralizes application schema, queries, and migrations.
+- **Authentication stays separate from application data.** The auth provider owns credentials and sessions; application tables are managed by Drizzle. <!-- clubedge:only auth!=none -->
+- **Providers sit behind interfaces.** Each interface lives in its own package under `packages/`, and each provider in another, so replacing a provider does not touch application code.
+- **Shared packages are framework-agnostic.** Packages under `packages/` receive configuration and request cookies as arguments and never import a web framework. ESLint enforces these boundaries.
+- **One composition root.** `apps/web/src/server/` is the only place that reads environment variables and chooses providers. Routes and components call it rather than a provider SDK.
+- **Keep the baseline focused.** Additional providers and tooling should be added when a real use case calls for them.
+
 ## Common commands
 
 Run these from the repository root:
@@ -198,13 +284,28 @@ Change the project later:
 
 These commands merge the change into your code instead of overwriting it: files you never touched are updated, your edits are kept, and lines you both changed get conflict markers. Commit first, because they need a clean Git tree so that `git diff` shows the result. Add `--dry-run` to preview a change.
 
+## Documentation
+
+| I want to                                   | Read                                          |
+| ------------------------------------------- | --------------------------------------------- |
+| Configure the environment and each provider | [SETUP.md](SETUP.md)                          |
+| Run the local services                      | [Local services](SETUP.md#local-services)     |
+| Deploy the app                              | [Deploy](SETUP.md#deploy)                     |
+| Check the app before going live             | [Before deploying](SETUP.md#before-deploying) |
+| Fix a common problem                        | [Troubleshooting](SETUP.md#troubleshooting)   |
+| Contribute code                             | [CONTRIBUTING.md](CONTRIBUTING.md)            |
+| Get help                                    | [SUPPORT.md](SUPPORT.md)                      |
+| Report a security problem                   | [SECURITY.md](SECURITY.md)                    |
+
 <!-- clubedge:if starter-repository -->
 
 ## Working on this repository
 
+This repository contains the same application for two frameworks, Next.js (`apps/web`) and TanStack Start (`apps/start`), plus every optional module. Sections of this README marked for a framework or module appear only in projects that use it.
+
 The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start dev`. It reads `apps/start/.env.local`, copied from `apps/start/.env.example`. Run the browser suite against it with `E2E_APP=start pnpm test:e2e`, and build its image with `docker build -f apps/start/Dockerfile --build-arg APP_DIR=apps/start --build-arg APP_PACKAGE=@clubedge/start .`.
 
-`clubedge.template.json` tells create-clubedge-app what each framework and module owns: packages, files, variant files under `variants/` that replace a default, and files with `clubedge:if` blocks. Write those blocks so the default selection keeps every block; use a variant file when two options need different code. `.github/workflows/starter.yml` generates projects for several combinations and runs their full pipeline.
+`clubedge.template.json` tells create-clubedge-app what each framework and module owns: packages, files, variant files under `variants/` that replace a default, and files with `clubedge:if` blocks. Write those blocks so the default selection keeps every block; use a variant file when two options need different code. `.github/workflows/starter.yml` generates projects for several combinations and runs their full pipeline. Maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist.
 
 <!-- clubedge:end -->
 
@@ -212,7 +313,7 @@ The TanStack Start app is `apps/start`, run with `pnpm --filter @clubedge/start
 
 - `apps/web/`: the web app, with routes, UI, and the composition root in `src/server/`
 - `e2e/`: Playwright browser checks
-- `packages/core/`: errors, `Result` type, and HTTP helpers (no dependencies)
+- `packages/core/`: errors, `Result` type, HTTP helpers, and the error reporting and tracing hooks (no dependencies)
 - `packages/db/`: Drizzle schema, client factory, migrations, and seed script
 - `packages/auth/`: `AuthProvider` and `CookieStore` interfaces <!-- clubedge:only auth!=none -->
 - `packages/auth-supabase/`: Supabase Auth adapter <!-- clubedge:only auth=supabase -->
@@ -250,6 +351,33 @@ pnpm dlx shadcn@latest add badge -c apps/web
 
 Shared components are generated under `packages/ui/src/components` and can be imported from `@clubedge/ui/components/<component>`. The app and `packages/ui` `components.json` files intentionally share the `base-nova` style, neutral color base, Lucide icons, Tailwind v4 stylesheet, and RTL-aware generation setting. The app currently renders English in LTR; set the root document's `lang` and `dir` for the locale used by your application. Put app-only components in `apps/web/src/components`.
 
+<!-- clubedge:if starter-repository -->
+
+## Roadmap
+
+Each phase ends with a Starter release and a create-clubedge-app release pinned to it. The full plan is in [ROADMAP.md](ROADMAP.md).
+
+| Release          | Theme                                                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| v0.5.0 to v0.8.0 | Optional modules, local services with and without Docker, `add`, `remove`, and `upgrade` |
+| v0.9.0           | Email, password reset, and email verification                                            |
+| v0.10.0          | Deployment to Docker hosts, Fly.io, Railway, Render, Vercel, and Netlify                 |
+| v0.11.0          | Payments with Stripe                                                                     |
+| v0.12.0          | Background jobs with pg-boss                                                             |
+| v0.13.0          | Observability with OpenTelemetry or Sentry                                               |
+| next             | Browser error reporting, Sentry source maps, and auth emails through the job queue       |
+
+## Community
+
+- **[Issues](https://github.com/Clubedge/clubedge-starter/issues)** for bugs and feature requests, using the issue forms.
+- **[Pull requests](https://github.com/Clubedge/clubedge-starter/pulls)** are welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).
+- **[create-clubedge-app](https://github.com/Clubedge/create-clubedge-app)** for problems creating, changing, or upgrading a project.
+- **Security problems** go through the private process in [SECURITY.md](SECURITY.md), not public issues.
+
+Everyone taking part is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+<!-- clubedge:end -->
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. For local changes, run the relevant checks before submitting. You can report vulnerabilities privately using the process in [SECURITY.md](SECURITY.md).

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/start/src/nitro/plugins/jobs.ts

@@ -1,8 +1,8 @@
 import { definePlugin } from "nitro";
-import { getJobs, startJobsWorker } from "@/server/jobs";
+import { startJobsWorker, stopJobsWorker } from "@/server/jobs";
 
 /** Starts the background jobs worker with the server, and stops it with the server. */
 export default definePlugin((nitroApp) => {
   startJobsWorker();
-  nitroApp.hooks.hook("close", () => getJobs().stop());
+  nitroApp.hooks.hook("close", stopJobsWorker);
 });

package/template/apps/start/src/server/jobs.test.ts

@@ -0,0 +1,27 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { startJobsWorker } from "./jobs";
+
+// The server starts the worker before handling any request. A configuration mistake must be
+// reported, not stop the server, so pages that need no database keep working.
+const holder = globalThis as typeof globalThis & { clubedgeJobs?: unknown };
+
+afterEach(() => {
+  delete holder.clubedgeJobs;
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+});
+
+describe("startJobsWorker", () => {
+  it("reports a missing DATABASE_URL instead of failing to start", () => {
+    const log = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.stubEnv("DATABASE_URL", "");
+    vi.stubEnv("JOBS_WORKER", "on");
+
+    expect(() => startJobsWorker()).not.toThrow();
+    expect(log).toHaveBeenCalledWith(
+      "Background jobs: the worker did not start.",
+      expect.any(Error),
+    );
+    expect(holder.clubedgeJobs).toBeUndefined();
+  });
+});

package/template/apps/start/src/server/jobs.ts

@@ -53,15 +53,27 @@ export function getJobs(): JobQueue {
 
 /** Starts the worker when this server should run one, retrying until the database answers. */
 export function startJobsWorker() {
-  if (!isWorkerEnabled()) return;
+  let jobs: JobQueue;
+  try {
+    if (!isWorkerEnabled()) return;
+    jobs = getJobs();
+  } catch (error) {
+    // Invalid configuration, such as a missing DATABASE_URL, is reported once; the rest of the
+    // app keeps serving instead of failing to start.
+    reportError(error, { message: "Background jobs: the worker did not start." });
+    return;
+  }
   const start = () =>
-    getJobs()
-      .startWorker()
-      .catch((error: unknown) => {
-        reportError(error, {
-          message: "Background jobs: the worker could not start, retrying in 5 seconds.",
-        });
-        setTimeout(start, 5_000).unref();
+    jobs.startWorker().catch((error: unknown) => {
+      reportError(error, {
+        message: "Background jobs: the worker could not start, retrying in 5 seconds.",
       });
+      setTimeout(start, 5_000).unref();
+    });
   void start();
 }
+
+/** Stops the worker, if this process created a queue. */
+export async function stopJobsWorker() {
+  await globalForJobs.clubedgeJobs?.stop();
+}

package/template/apps/start/src/server/observability.test.ts

@@ -0,0 +1,23 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { startObservability } from "./observability";
+
+// The server starts observability before handling any request. An invalid setting must leave it
+// off with a report, not stop the server.
+const holder = globalThis as typeof globalThis & { clubedgeObservability?: unknown };
+
+afterEach(() => {
+  delete holder.clubedgeObservability;
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+});
+
+describe("startObservability", () => {
+  it("leaves observability off when its settings are invalid", () => {
+    const log = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.stubEnv("OTEL_EXPORTER_OTLP_ENDPOINT", "not a url");
+    vi.stubEnv("SENTRY_DSN", "not a url");
+
+    expect(startObservability()).toBeNull();
+    expect(log).toHaveBeenCalledWith("Observability did not start.", expect.any(Error));
+  });
+});

package/template/apps/start/src/server/observability.ts

@@ -1,6 +1,6 @@
 import "@tanstack/react-start/server-only";
 import { z } from "zod";
-import { setTelemetry } from "@clubedge/core";
+import { reportError, setTelemetry } from "@clubedge/core";
 import type { ObservabilityProvider } from "@clubedge/observability";
 import { createOtelObservability, parseOtlpHeaders } from "@clubedge/observability-otel";
 import { siteConfig } from "@/config/site";
@@ -22,7 +22,15 @@ const globalForObservability = globalThis as typeof globalThis & {
 export function startObservability(): ObservabilityProvider | null {
   if (globalForObservability.clubedgeObservability !== undefined)
     return globalForObservability.clubedgeObservability;
-  const env = parseEnv(observabilityEnvSchema, "Observability");
+  let env: z.infer<typeof observabilityEnvSchema>;
+  try {
+    env = parseEnv(observabilityEnvSchema, "Observability");
+  } catch (error) {
+    // An invalid variable leaves observability off rather than stopping the server.
+    reportError(error, { message: "Observability did not start." });
+    globalForObservability.clubedgeObservability = null;
+    return null;
+  }
   const provider = env.OTEL_EXPORTER_OTLP_ENDPOINT
     ? createOtelObservability({
         endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT,

package/template/apps/start/src/server/variants/observability.sentry.ts

@@ -1,6 +1,6 @@
 import "@tanstack/react-start/server-only";
 import { z } from "zod";
-import { setTelemetry } from "@clubedge/core";
+import { reportError, setTelemetry } from "@clubedge/core";
 import type { ObservabilityProvider } from "@clubedge/observability";
 import { createSentryObservability } from "@clubedge/observability-sentry";
 import { optional, parseEnv } from "@/env/server";
@@ -25,7 +25,15 @@ const globalForObservability = globalThis as typeof globalThis & {
 export function startObservability(): ObservabilityProvider | null {
   if (globalForObservability.clubedgeObservability !== undefined)
     return globalForObservability.clubedgeObservability;
-  const env = parseEnv(observabilityEnvSchema, "Observability");
+  let env: z.infer<typeof observabilityEnvSchema>;
+  try {
+    env = parseEnv(observabilityEnvSchema, "Observability");
+  } catch (error) {
+    // An invalid variable leaves observability off rather than stopping the server.
+    reportError(error, { message: "Observability did not start." });
+    globalForObservability.clubedgeObservability = null;
+    return null;
+  }
   const provider = env.SENTRY_DSN
     ? createSentryObservability({
         dsn: env.SENTRY_DSN,

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {

package/template/apps/web/src/server/jobs.ts

@@ -53,15 +53,27 @@ export function getJobs(): JobQueue {
 
 /** Starts the worker when this server should run one, retrying until the database answers. */
 export function startJobsWorker() {
-  if (!isWorkerEnabled()) return;
+  let jobs: JobQueue;
+  try {
+    if (!isWorkerEnabled()) return;
+    jobs = getJobs();
+  } catch (error) {
+    // Invalid configuration, such as a missing DATABASE_URL, is reported once; the rest of the
+    // app keeps serving instead of failing to start.
+    reportError(error, { message: "Background jobs: the worker did not start." });
+    return;
+  }
   const start = () =>
-    getJobs()
-      .startWorker()
-      .catch((error: unknown) => {
-        reportError(error, {
-          message: "Background jobs: the worker could not start, retrying in 5 seconds.",
-        });
-        setTimeout(start, 5_000).unref();
+    jobs.startWorker().catch((error: unknown) => {
+      reportError(error, {
+        message: "Background jobs: the worker could not start, retrying in 5 seconds.",
       });
+      setTimeout(start, 5_000).unref();
+    });
   void start();
 }
+
+/** Stops the worker, if this process created a queue. */
+export async function stopJobsWorker() {
+  await globalForJobs.clubedgeJobs?.stop();
+}

package/template/apps/web/src/server/observability.ts

@@ -1,6 +1,6 @@
 import "server-only";
 import { z } from "zod";
-import { setTelemetry } from "@clubedge/core";
+import { reportError, setTelemetry } from "@clubedge/core";
 import type { ObservabilityProvider } from "@clubedge/observability";
 import { createOtelObservability, parseOtlpHeaders } from "@clubedge/observability-otel";
 import { siteConfig } from "@/config/site";
@@ -22,7 +22,15 @@ const globalForObservability = globalThis as typeof globalThis & {
 export function startObservability(): ObservabilityProvider | null {
   if (globalForObservability.clubedgeObservability !== undefined)
     return globalForObservability.clubedgeObservability;
-  const env = parseEnv(observabilityEnvSchema, "Observability");
+  let env: z.infer<typeof observabilityEnvSchema>;
+  try {
+    env = parseEnv(observabilityEnvSchema, "Observability");
+  } catch (error) {
+    // An invalid variable leaves observability off rather than stopping the server.
+    reportError(error, { message: "Observability did not start." });
+    globalForObservability.clubedgeObservability = null;
+    return null;
+  }
   const provider = env.OTEL_EXPORTER_OTLP_ENDPOINT
     ? createOtelObservability({
         endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT,

package/template/apps/web/src/server/variants/observability.sentry.ts

@@ -1,6 +1,6 @@
 import "server-only";
 import { z } from "zod";
-import { setTelemetry } from "@clubedge/core";
+import { reportError, setTelemetry } from "@clubedge/core";
 import type { ObservabilityProvider } from "@clubedge/observability";
 import { createSentryObservability } from "@clubedge/observability-sentry";
 import { optional, parseEnv } from "@/env/server";
@@ -25,7 +25,15 @@ const globalForObservability = globalThis as typeof globalThis & {
 export function startObservability(): ObservabilityProvider | null {
   if (globalForObservability.clubedgeObservability !== undefined)
     return globalForObservability.clubedgeObservability;
-  const env = parseEnv(observabilityEnvSchema, "Observability");
+  let env: z.infer<typeof observabilityEnvSchema>;
+  try {
+    env = parseEnv(observabilityEnvSchema, "Observability");
+  } catch (error) {
+    // An invalid variable leaves observability off rather than stopping the server.
+    reportError(error, { message: "Observability did not start." });
+    globalForObservability.clubedgeObservability = null;
+    return null;
+  }
   const provider = env.SENTRY_DSN
     ? createSentryObservability({
         dsn: env.SENTRY_DSN,

package/template/clubedge.template.json

@@ -258,6 +258,7 @@
             "apps/start/src/routes/jobs",
             "apps/start/src/server/jobs-forms.ts",
             "apps/start/src/server/jobs.functions.ts",
+            "apps/start/src/server/jobs.test.ts",
             "apps/start/src/server/jobs.ts",
             "apps/web/src/app/api/jobs",
             "apps/web/src/app/dashboard/_components/jobs-actions.ts",
@@ -285,6 +286,7 @@
           },
           "files": [
             "apps/start/src/nitro/plugins/observability.ts",
+            "apps/start/src/server/observability.test.ts",
             "apps/start/src/server/observability.ts",
             "apps/web/src/instrumentation.ts",
             "apps/web/src/server/observability.ts",
@@ -300,6 +302,7 @@
           },
           "files": [
             "apps/start/src/nitro/plugins/observability.ts",
+            "apps/start/src/server/observability.test.ts",
             "apps/start/src/server/observability.ts",
             "apps/web/src/instrumentation.ts",
             "apps/web/src/server/observability.ts",

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clubedge-starter-v1",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.9.0",

package/template/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/auth-better-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-better-auth",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Better Auth adapter for @clubedge/auth, storing users and sessions in your own PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-supabase",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Supabase Auth adapter for @clubedge/auth.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/cache-redis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache-redis",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Redis rate limiter and cache for @clubedge/cache.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/core",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/db",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/email/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Email interface, console and in-memory providers, and message templates.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-resend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-resend",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Resend provider for @clubedge/email, through Resend's HTTP API.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-smtp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-smtp",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "SMTP provider for @clubedge/email, for any SMTP server.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Background jobs interface: job definitions, a queue contract, and an in-memory queue.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-pg-boss/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-pg-boss",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "pg-boss provider for @clubedge/jobs: a job queue stored in the project's PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/local-db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/local-db",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "PostgreSQL for development without Docker: PGlite served over the PostgreSQL protocol.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Observability interface: error reports and spans for @clubedge/core's telemetry hooks, and an in-memory provider for tests.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-otel",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "OpenTelemetry provider for @clubedge/observability: traces and error logs exported over OTLP to any collector.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-sentry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-sentry",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Sentry provider for @clubedge/observability: server errors and traces sent to Sentry.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Provider-neutral payments: the PaymentProvider interface, billing logic, and subscription tables.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments-stripe/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments-stripe",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Stripe provider for @clubedge/payments: Checkout, the customer portal, and verified webhooks.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/storage-s3/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-s3",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "S3-compatible adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-supabase",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Supabase Storage adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/ui",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template.lock.json

@@ -1,7 +1,7 @@
 {
   "repository": "Clubedge/clubedge-starter",
-  "ref": "v0.13.0",
-  "commit": "62fb8d1b1e13ed8e8e134bd1e53f2bfdde2c6a50",
+  "ref": "v0.13.1",
+  "commit": "28bfbf98c85ae500ace6a062dd10d67746e1a330",
   "files": [
     ".dockerignore",
     ".env.example",
@@ -95,7 +95,9 @@
     "apps/start/src/server/email.ts",
     "apps/start/src/server/jobs-forms.ts",
     "apps/start/src/server/jobs.functions.ts",
+    "apps/start/src/server/jobs.test.ts",
     "apps/start/src/server/jobs.ts",
+    "apps/start/src/server/observability.test.ts",
     "apps/start/src/server/observability.ts",
     "apps/start/src/server/payments.ts",
     "apps/start/src/server/storage.ts",