@clubedge/create-clubedge-app 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -2,12 +2,40 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.38.0
+
+- **Security: default to Starter `v0.24.2`** (#116). It updates Next.js to 16.4.3: 16.0.0 to 16.4.0 have two critical unauthenticated remote code execution advisories and a high denial of service ([GHSA-p3m5-59mp-jv5r](https://github.com/advisories/GHSA-p3m5-59mp-jv5r) and related). It also updates Zod to 4.6.7 ([GHSA-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5)). **Every Next.js project from an earlier Starter should run `pnpm clubedge upgrade`**, or raise `next` to `^16.4.3` in `apps/web/package.json` and run `pnpm install`. The Starter release also:
+  - gives a separate API the database URL of its `--infra` (it always pointed at `127.0.0.1:5432/postgres`, wrong for supabase, local, and docker);
+  - passes the Vite frontend's `VITE_*` build arguments in `docker-compose.yml`, and runs the Vite image as an unprivileged user;
+  - lists the Firebase, Appwrite, Inngest, Supabase, OpenTelemetry, and Sentry variables in `render.yaml`.
+- **Fixes for a frontend and its API** (#115):
+  - The database URLs go to `apps/api/.env.local`, the API's, with `--infra neon`, `neon create|claim|status`, `add infra neon`, `try`, and `doctor`. Apps that also declare `DATABASE_URL` (Better Auth on the Vite frontend) get the same URLs.
+  - `deploy` with Docker: `compose.yaml` passes the frontend's `VITE_*` build arguments for every auth provider, not only Supabase. With Better Auth, the frontend gets its auth server's variables.
+  - `deploy` on Railway: with Better Auth, the frontend service gets the API's `DATABASE_URL`, `BETTER_AUTH_URL`, and a secret. Each service lists its own unset variables.
+  - `deploy --preview` refuses a frontend and its API with a clear message: it deploys one app.
+  - MCP: with `infra: neon`, `create_project` warns and `plan_project` returns `nextSteps` saying to run `pnpm clubedge neon create`.
+- The README, roadmap, and 0.35.0–0.37.0 changelog entries describe what shipped; `pnpm release` leaves dependency bumps out of the release tables (#114).
+
+## 0.37.0
+
+- **An MCP server for coding agents** (#110): `create-clubedge-app-mcp`, in the same package, lets an agent create projects with the CLI's pinned Starter and its compatibility rules. Run it from the workspace where projects should go:
+
+  ```sh
+  npx -y --package @clubedge/create-clubedge-app create-clubedge-app-mcp
+  ```
+
+  - `get_starter_capabilities` lists the frameworks, API stacks, modules, defaults, and what each option requires.
+  - `validate_project_config` checks a choice of stacks and modules.
+  - `plan_project` previews a project: the stacks and modules, the files, the environment files, toolchains such as uv, and the setup steps. It writes nothing.
+  - `create_project` writes the project to a new or empty folder beneath the server's working directory. It refuses absolute paths, `..`, and symlinks that lead outside. Git and dependency installation are off unless asked for, and their output goes to stderr, never into the MCP stream.
+- **An agent skill**, `skills/clubedge-starter/SKILL.md`, in the package: it tells Codex, Claude Code, and other agents to plan before creating, to use `add`, `remove`, and `upgrade` for existing projects, and to fall back to the CLI without MCP. The README shows how to install it and connect the server.
+- CI and the release workflow start the MCP server from the packed package and call every tool.
+- Still on Starter `v0.24.1`.
+
 ## 0.36.0
 
-- Bump vitest from 5.0.3 to 5.0.5 in the minor-and-patch group (#104).
-- Bump giget from 2.0.0 to 3.3.1 (#69).
-- Bump @types/node from 22.20.5 to 26.6.5 (#68).
-- Default to Starter `v0.24.1` (#107).
+- **Security: default to Starter `v0.24.1`** (#107). It updates the FastAPI API's locked `certifi` to 2026.10.19, for the critical advisory [GHSA-6q48-6c7w-9gw2](https://github.com/certifi/python-certifi/security/advisories/GHSA-6q48-6c7w-9gw2). If your project has `--api fastapi`, run `pnpm clubedge upgrade`, then `uv sync` in `apps/api`. The Starter's pull request previews also skip secret-backed deploys for Dependabot.
+- Dependency updates: giget 3.3.1 (#69), vitest 5.0.5 (#104), and @types/node 26.6.5 (#68).
 
 ## 0.35.0
 

package/README.md

@@ -27,6 +27,61 @@ Add, remove, or upgrade them later without losing your own changes.
 pnpm dlx @clubedge/create-clubedge-app my-app
 ```
 
+## MCP server
+
+Coding agents can connect to a local MCP server to inspect the capabilities of this CLI's pinned Starter release, validate stack and module choices, preview a complete scaffold plan, and generate a project in the server's working directory. The server exposes `get_starter_capabilities`, `validate_project_config`, `plan_project`, and `create_project`. Planning and validation do not write files. Project creation does not initialize Git or install dependencies unless those options are requested, and makes no network calls of its own: with `infra: neon`, `plan_project` lists `pnpm clubedge neon create` as a next step and `create_project` returns it as a warning, since the database is left for you to create.
+
+Run it from the workspace where projects should be created:
+
+```sh
+npx -y --package @clubedge/create-clubedge-app create-clubedge-app-mcp
+```
+
+Configure an MCP client to launch `npx -y --package @clubedge/create-clubedge-app create-clubedge-app-mcp` with its working directory set to the workspace. In Codex, add this to `~/.codex/config.toml` and replace the example with the absolute path of the workspace where projects should be created:
+
+```toml
+[mcp_servers.clubedge-starter]
+command = "npx"
+args = ["--yes", "--package", "@clubedge/create-clubedge-app", "create-clubedge-app-mcp"]
+cwd = "D:/path/to/workspace"
+```
+
+The MCP server is included in the same package and uses the CLI's bundled Starter and compatibility rules. Its create tool only writes beneath the configured working directory and refuses a non-empty destination.
+
+### Agent skill
+
+The npm package includes the Agent Skill at [`skills/clubedge-starter/SKILL.md`](skills/clubedge-starter/SKILL.md). Download and extract the package in PowerShell:
+
+```powershell
+$skillTarball = npm pack @clubedge/create-clubedge-app@latest
+tar -xzf $skillTarball
+```
+
+Then install it for the current user:
+
+```powershell
+# Codex
+New-Item -ItemType Directory -Force "$HOME/.agents/skills/clubedge-starter" | Out-Null
+Copy-Item .\package\skills\clubedge-starter\SKILL.md "$HOME/.agents/skills/clubedge-starter/SKILL.md"
+
+# Claude Code
+New-Item -ItemType Directory -Force "$HOME/.claude/skills/clubedge-starter" | Out-Null
+Copy-Item .\package\skills\clubedge-starter\SKILL.md "$HOME/.claude/skills/clubedge-starter/SKILL.md"
+```
+
+These commands create `package/` in the current directory. Remove that extracted folder and tarball when the copy is done. From a clone of this repository, the same copy commands work with `skills/...` instead of `package/skills/...`.
+
+For a repository-only install, use `.agents/skills/clubedge-starter/` for Codex or `.claude/skills/clubedge-starter/` for Claude Code instead of the `$HOME` paths. Restart the agent session after installing. In Codex, ask it to `Use the clubedge-starter skill to inspect the available stacks and modules. Do not create a project.` In Claude Code, invoke `/clubedge-starter` and give it the same request. The skill uses live MCP capabilities when available, so its choices follow the Starter release installed with the server.
+
+To connect the MCP server in Claude Code, run this from the workspace where projects should be created:
+
+```sh
+claude mcp add --scope local --transport stdio clubedge-starter -- npx -y --package @clubedge/create-clubedge-app create-clubedge-app-mcp
+claude mcp get clubedge-starter
+```
+
+Then open Claude Code in that workspace, invoke `/clubedge-starter`, and ask it to inspect the available stacks and modules without creating a project. In Codex, use the `cwd` in `~/.codex/config.toml` above, restart Codex, and ask the same prompt. To exercise project creation, ask the agent to create a named project in a new child folder with Git and dependency installation disabled; verify the folder and report before enabling those optional actions.
+
 ## Why create-clubedge-app
 
 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.
@@ -47,7 +102,7 @@ pnpm dev
 
 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.
 
-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`.
+The generated project includes `apps/web/.env.local` (and `apps/api/.env.local` with a separate API), 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`.
 
 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.
 
@@ -86,7 +141,7 @@ They meet at one HTTP contract, `packages/contract/openapi.yaml`: the frontend c
 
 With `--auth supabase`, the Vite app owns the browser session and attaches its access token to contract requests. Hono or FastAPI verifies that token with Supabase Auth and returns the contract's shared user shape. Configure `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_URL`, and `SUPABASE_PUBLISHABLE_KEY` in the generated env examples; no Supabase service-role key goes to the browser.
 
-The decoupled stacks support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy `.env.example` to `.env.production`, fill in its values, and run `docker compose --env-file .env.production up --build -d`. With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
+The decoupled stacks support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache, any local infrastructure (the API's `apps/api/.env.local` holds `DATABASE_URL`, since the API owns the database), and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy the variables of `.env.example` and `apps/api/.env.example` to `.env.production`, fill in their values, and run `docker compose --env-file .env.production up --build -d`. The frontend's `VITE_*` values are build arguments, compiled into its bundle; with Better Auth, its Node server also gets the auth variables (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and the email settings). With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
 
 ## Choosing modules
 
@@ -98,8 +153,8 @@ Authentication, file storage, caching, email, payments, background jobs, observa
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
 | `--email`   | `smtp` (any provider, or a local inbox), `resend`, `none` | `smtp` |
-| `--payments` | `stripe`, `none` (needs an auth module) | `none` |
-| `--jobs` | `pg-boss`, `none` | `none` |
+| `--payments` | `stripe` (needs an auth module), `none` | `none` |
+| `--jobs` | `pg-boss`, `bullmq` (needs the `redis` cache), `inngest`, `none` | `none` |
 | `--observability` | `otel` (OpenTelemetry, to any OTLP collector), `sentry`, `none` | `none` |
 | `--deploy`  | `docker` (any container host), `fly`, `railway`, `render`, `vercel`, `netlify` | `docker` |
 | `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `neon` (a free hosted Neon database), `none` | `docker` |
@@ -152,7 +207,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.24.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.24.2
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -171,7 +226,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 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.24.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.24.2 # 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.
@@ -179,7 +234,7 @@ The CLI renders the project twice, from the Starter commit and modules recorded
 - Files you never changed are updated, added, or deleted.
 - Files you changed keep your edits. Where the module change touches the same lines, the file gets conflict markers (`<<<<<<< yours` ... `>>>>>>> clubedge`) for you to resolve. The Starter's whole new version of each such file is saved in `.clubedge/incoming/` to compare with yours (`git diff --no-index <file> .clubedge/incoming/<file>`); Git ignores that folder, so delete it when you are done.
 - Your own files are never touched.
-- `apps/web/.env.local` keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
+- Each app's local env file (`apps/web/.env.local`, and `apps/api/.env.local` with a separate API) keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
 - `pnpm-lock.yaml` is replaced if you never changed your dependencies; otherwise `pnpm install` reconciles it.
 
 Several modules in one command are applied as one change, and their requirements are checked together, so `add auth supabase storage supabase` works even though Supabase Storage needs Supabase Auth. When lines conflict, the CLI lists each file with its number of conflict blocks. Before an upgrade, it lists the Starter releases it crosses with the sections of their release notes, such as `v0.13.0  Observability, Tests, Also`.
@@ -197,7 +252,7 @@ pnpm db:migrate
 pnpm dev
 ```
 
-The CLI creates a free database through Neon's [claimable Postgres](https://neon.com/docs/reference/claimable-postgres) and writes two URLs into `apps/web/.env.local`: `DATABASE_URL`, the pooled connection the app uses, and `DATABASE_URL_DIRECT`, the direct one that migrations and the background jobs worker use, since a transaction pooler can break them. Neon keeps an unclaimed database for 72 hours, with up to 100 MB:
+The CLI creates a free database through Neon's [claimable Postgres](https://neon.com/docs/reference/claimable-postgres) and writes two URLs into the env file of the app that owns the database, `apps/web/.env.local`, or `apps/api/.env.local` in a project with a separate API (a Vite frontend whose Better Auth server connects too gets the same `DATABASE_URL`): `DATABASE_URL`, the pooled connection the app uses, and `DATABASE_URL_DIRECT`, the direct one that migrations and the background jobs worker use, since a transaction pooler can break them. Neon keeps an unclaimed database for 72 hours, with up to 100 MB:
 
 ```sh
 pnpm clubedge neon           # where it stands and how long it has left
@@ -218,7 +273,7 @@ pnpm clubedge status    # Starter release, modules, Git state, and whether a new
 pnpm clubedge doctor    # Node.js, pnpm, dependencies, lockfile, env file, and pnpm check:services
 ```
 
-`status` ends with the command to run next, such as `pnpm clubedge upgrade` when a newer Starter release is available; it asks npm for the newest CLI and still works offline. `doctor` checks that Node.js and pnpm meet the project's versions, that dependencies are installed, that `pnpm-lock.yaml` matches every `package.json`, and that `apps/web/.env.local` has every variable in `.env.example`, then runs `pnpm check:services` (skip it with `--no-services`). It exits with an error when a check fails, so it also works in CI.
+`status` ends with the command to run next, such as `pnpm clubedge upgrade` when a newer Starter release is available; it asks npm for the newest CLI and still works offline. `doctor` checks that Node.js and pnpm meet the project's versions, that dependencies are installed, that `pnpm-lock.yaml` matches every `package.json`, and that each app's local env file has every variable in its example (`apps/web/.env.local` and `.env.example`, and `apps/api/.env.local` and `apps/api/.env.example` with a separate API), then runs `pnpm check:services` (skip it with `--no-services`). It exits with an error when a check fails, so it also works in CI.
 
 ## Try it on a Railway VM (experimental)
 
@@ -247,7 +302,7 @@ pnpm clubedge deploy --env-file .env.staging      # with another file of product
 pnpm clubedge deploy --dry-run                    # show the plan, create nothing
 ```
 
-With [Railway's CLI](https://docs.railway.com/cli) (the installed `railway`, or `npx @railway/cli`) and your Railway login, it creates or reuses a project named after the package and the databases selected by the modules. Full-stack projects get one public app service. A Vite project gets two services: the frontend has the public `*.up.railway.app` domain, and the API stays private; the frontend's Caddy proxy connects to it over Railway's private network. API variables, including `FRONTEND_URL`, go on the API service; `VITE_*` values go on the frontend service for its build. The API's migration command runs before the API release, and the frontend and API deployments are both awaited. Database variables are references to Railway's Postgres and Redis by default. Values from `.env.production` (or `--env-file`) take precedence; external database URLs stay external, and localhost URLs are ignored. `.railway/railway.ts` describes the selected service topology and health checks; `deploy` applies it and adds Railway's TypeScript SDK (`railway`) as a dev dependency. Commit the generated file and package changes. It needs Railway CLI 5.42.1 or newer. Running `deploy` again reuses the services, so it also adds variables and ships new releases. Railway bills usage on your plan.
+With [Railway's CLI](https://docs.railway.com/cli) (the installed `railway`, or `npx @railway/cli`) and your Railway login, it creates or reuses a project named after the package and the databases selected by the modules. Full-stack projects get one public app service. A Vite project gets two services: the frontend has the public `*.up.railway.app` domain, and the API stays private; the frontend's Node server (`node server.mjs`) forwards the API routes to it over Railway's private network. API variables, including `FRONTEND_URL`, go on the API service; `VITE_*` values go on the frontend service for its build. With Better Auth, the frontend's Node server runs auth: it gets the same `DATABASE_URL` as the API, a generated `BETTER_AUTH_SECRET`, the email settings, and `BETTER_AUTH_URL`, the public frontend URL both services use. Each service's unset variables are reported from its own env example. The API's migration command runs before the API release, and the frontend and API deployments are both awaited. Database variables are references to Railway's Postgres and Redis by default. Values from `.env.production` (or `--env-file`) take precedence; external database URLs stay external, and localhost URLs are ignored. `.railway/railway.ts` describes the selected service topology and health checks; `deploy` applies it and adds Railway's TypeScript SDK (`railway`) as a dev dependency. Commit the generated file and package changes. It needs Railway CLI 5.42.1 or newer. Running `deploy` again reuses the services, so it also adds variables and ships new releases. Railway bills usage on your plan.
 
 ### Deploy to Fly.io (experimental)
 
@@ -273,7 +328,7 @@ In a project that deploys to Vercel or Railway, `pnpm clubedge deploy --preview`
 NEON_API_KEY=... NEON_PROJECT_ID=... pnpm clubedge deploy --preview
 ```
 
-With `NEON_API_KEY` and `NEON_PROJECT_ID` (in the shell, or in the env file), the preview gets its own [Neon branch](https://neon.com/docs/introduction/branching), `preview/<git branch>`: a copy of the production database made in seconds that shares its storage until it changes. `deploy` creates it, or reuses it on later runs, applies this branch's migrations to it, and points the preview's `DATABASE_URL` and `DATABASE_URL_DIRECT` at it. On Vercel, the preview is a preview deployment with the project's Preview variables, and the branch's URLs are set as Preview variables of your Git branch, which needs the Vercel project connected to its Git repository; without the Neon settings, it uses the Preview `DATABASE_URL`. On Railway, it is an environment named `preview-<git branch>`, copied from production with its own domain; without the Neon settings, it gets its own empty copy of Railway's Postgres, and when production's database comes from elsewhere, `deploy --preview` refuses, since the copy would use production's data. Production is not changed.
+With `NEON_API_KEY` and `NEON_PROJECT_ID` (in the shell, or in the env file), the preview gets its own [Neon branch](https://neon.com/docs/introduction/branching), `preview/<git branch>`: a copy of the production database made in seconds that shares its storage until it changes. `deploy` creates it, or reuses it on later runs, applies this branch's migrations to it, and points the preview's `DATABASE_URL` and `DATABASE_URL_DIRECT` at it. On Vercel, the preview is a preview deployment with the project's Preview variables, and the branch's URLs are set as Preview variables of your Git branch, which needs the Vercel project connected to its Git repository; without the Neon settings, it uses the Preview `DATABASE_URL`. On Railway, it is an environment named `preview-<git branch>`, copied from production with its own domain; without the Neon settings, it gets its own empty copy of Railway's Postgres, and when production's database comes from elsewhere, `deploy --preview` refuses, since the copy would use production's data. Production is not changed. It deploys a single app for now: a Vite frontend and its API are two services, so `deploy --preview` refuses them and explains how to copy production's Railway environment yourself.
 
 Projects created with `--infra neon` also have `.github/workflows/preview.yml`, which does this for every pull request in CI: a Neon branch per pull request with its migrations, the schema diff as a comment, a Vercel or Railway preview, and cleanup when the pull request closes. The Starter's SETUP.md lists the secrets it needs.
 
@@ -282,27 +337,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.36.0
+create-clubedge-app v0.38.0
         |
         v
-Clubedge Starter v0.24.1
-commit 3e8b5ba8910767f27336cf253fbfe92a9bb42875
+Clubedge Starter v0.24.2
+commit 4450d2f00a89f1a3929a5c9d2c1541e0d65df891
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.36.0` | `clubedge-starter@v0.24.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.38.0` | `clubedge-starter@v0.24.2` | 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.24.1` tag is expected to resolve to commit
-`3e8b5ba8910767f27336cf253fbfe92a9bb42875`. The CLI verifies this before
+The `v0.24.2` tag is expected to resolve to commit
+`4450d2f00a89f1a3929a5c9d2c1541e0d65df891`. 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.24.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.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.24.2`. 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`.
 
@@ -357,7 +412,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 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.24.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.24.2`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -402,9 +457,10 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.32.0 | v0.21.0 | Pluggable authentication: `--auth firebase` and `--auth appwrite` next to Supabase and Better Auth, and a conformance suite every provider passes |
 | 0.33.0 | v0.22.0 | Starter v0.22.0: stack packs (template schema 4), and a React + Vite frontend with a separate Hono API (`--framework vite --api hono`) |
 | 0.34.0 | v0.23.0 | Starter v0.23.0: a FastAPI API in Python (`--framework vite --api fastapi`), generated with no CLI change |
-| 0.35.0 | v0.24.0 | Deploy frontend and API stack packs; Default to Starter v0.24.0 |
-| 0.36.0 | v0.24.1 | Bump vitest from 5.0.3 to 5.0.5 in the minor-and-patch group; Bump giget from 2.0.0 to 3.3.1; Bump @types/node from 22.20.5 to 26.6.5; Default to Starter v0.24.1 |
-| next | | Show the Starter's version of a conflicted file next to yours |
+| 0.35.0 | v0.24.0 | `deploy` for a frontend and its API (Docker Compose, Railway); Starter v0.24.0: all four auth providers on React + Vite with Hono or FastAPI |
+| 0.36.0 | v0.24.1 | Starter v0.24.1: security update of FastAPI's `certifi`; dependency updates |
+| 0.37.0 | v0.24.1 | An MCP server (capabilities, validate, plan, create) and an agent skill for coding agents |
+| 0.38.0 | v0.24.2 | Starter v0.24.2: Next.js security update (critical RCE advisories); database URLs, Neon, and deploy variables for a frontend and its API |
 
 ## Community
 

package/bin/mcp.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/mcp-server.js";

package/dist/core/deploy.js

@@ -10,18 +10,36 @@ export function serviceName(packageName) {
     const name = packageName.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
     return name || "web";
 }
-/** A Docker Compose production topology rendered from the selected stack service descriptors. */
-export function dockerComposeSource(services) {
+/**
+ * A Docker Compose production topology rendered from the selected stack service descriptors.
+ * `frontendKeys` are the variables the frontend's env example lists: its VITE_* values become build
+ * arguments (Vite compiles them in), the others runtime variables, such as Better Auth's when the
+ * frontend's server runs auth. Compose reads their values from its --env-file.
+ */
+export function dockerComposeSource(services, frontendKeys = []) {
     const api = Object.values(services).find((service) => service.role === "api");
-    const rows = Object.entries(services).map(([slot, service]) => {
+    const web = Object.values(services).find((service) => service.role === "frontend");
+    const mapping = (indent, values) => values.map(([key, value]) => `\n${indent}${key}: ${value}`).join("");
+    const fromEnv = (key, fallback = "") => `\${${key}:-${fallback}}`;
+    const buildKeys = frontendKeys.filter((key) => key.startsWith("VITE_"));
+    // API_URL is the API's address on the Compose network, and PORT the one the image declares.
+    const runtimeKeys = frontendKeys.filter((key) => !key.startsWith("VITE_") && key !== "API_URL" && key !== "PORT");
+    // Better Auth runs in the frontend's server: the API asks it for the session over the Compose network.
+    const authUrl = web && frontendKeys.includes("BETTER_AUTH_URL") ? `http://${web.id}:${web.port}` : null;
+    const rows = Object.entries(services).map(([, service]) => {
         const name = service.id;
         const frontend = service.role === "frontend";
-        const buildArgs = frontend
-            ? `\n      args:\n        VITE_SUPABASE_URL: \${VITE_SUPABASE_URL:-}\n        VITE_SUPABASE_PUBLISHABLE_KEY: \${VITE_SUPABASE_PUBLISHABLE_KEY:-}`
+        const buildArgs = frontend && buildKeys.length
+            ? `\n      args:${mapping("        ", buildKeys.map((key) => [key, fromEnv(key)]))}`
             : "";
+        // Better Auth's public URL defaults to the port Compose publishes.
+        const runtime = runtimeKeys.map((key) => [key, fromEnv(key, key === "BETTER_AUTH_URL" ? `http://localhost:${service.port}` : "")]);
+        // The API listens on every interface, whatever HOST the env file has from development.
+        const apiValues = [["HOST", "0.0.0.0"], ...(authUrl ? [["BETTER_AUTH_URL", authUrl]] : [])];
+        const apiEnv = service.role === "api" ? `\n    environment:${mapping("      ", apiValues)}` : "";
         const env = frontend && api
-            ? `\n    environment:\n      API_URL: http://${api.id}:${api.port}`
-            : `\n    env_file:\n      - path: .env.production\n        required: false`;
+            ? `\n    environment:${mapping("      ", [["API_URL", `http://${api.id}:${api.port}`], ...runtime])}`
+            : `\n    env_file:\n      - path: .env.production\n        required: false${apiEnv}`;
         const ports = frontend ? `\n    ports:\n      - "${service.port}:${service.port}"` : `\n    expose:\n      - "${service.port}"`;
         const depends = frontend && api ? `\n    depends_on:\n      - ${api.id}` : "";
         return `  ${name}:\n    build:\n      context: .\n      dockerfile: ${service.dockerfile}${buildArgs}${env}${ports}${depends}`;
@@ -123,6 +141,48 @@ export function planVariables(input) {
     const unset = keys.filter((key) => set[key] === undefined && !existing[key] && key !== "DATABASE_URL_DIRECT");
     return { set, unset };
 }
+/**
+ * The variables of a frontend and an API deployed as two services. The API gets what planVariables
+ * provides with the env file's server values, and the frontend's URL. The frontend gets its port,
+ * the env file's VITE_* build values, and the runtime values its own example lists. With Better
+ * Auth the frontend's server runs auth: it gets the API's database, the secret (generated unless
+ * the service already has one), and BETTER_AUTH_URL, the public URL the API asks for the session.
+ * Each service's unset variables come from its own example.
+ */
+export function planServicePair(input) {
+    const { modules, frontendKeys, apiKeys, url, existing, envFile, secret, databases, ports } = input;
+    const betterAuth = modules.auth === "better-auth";
+    // A development env file's localhost URL would send sign-in links to this machine.
+    const authUrl = envFile.BETTER_AUTH_URL && !isLocalUrl(envFile.BETTER_AUTH_URL) ? envFile.BETTER_AUTH_URL : url;
+    const apiEnv = Object.fromEntries(Object.entries(envFile).filter(([key]) => !key.startsWith("VITE_")));
+    const api = planVariables({ modules, keys: apiKeys, url, existing: existing.api, envFile: apiEnv, secret, databases, port: ports.api });
+    // Better Auth's secret belongs to the frontend's server; the API only asks it for the session.
+    if (!apiEnv.BETTER_AUTH_SECRET)
+        delete api.set.BETTER_AUTH_SECRET;
+    api.set.FRONTEND_URL = url;
+    if (betterAuth)
+        api.set.BETTER_AUTH_URL = authUrl;
+    // The image listens on every interface: its Dockerfile sets HOST.
+    api.unset = api.unset.filter((key) => api.set[key] === undefined && key !== "HOST");
+    // railway.ts sets API_URL to the API's private address; the platform provides the database.
+    const provided = ["API_URL", "PORT", "BETTER_AUTH_URL", ...Object.values(databaseVariables), "DATABASE_URL_DIRECT"];
+    const set = { PORT: String(ports.frontend) };
+    for (const [key, value] of Object.entries(envFile)) {
+        if (value && (key.startsWith("VITE_") || (frontendKeys.includes(key) && !provided.includes(key))))
+            set[key] = value;
+    }
+    if (betterAuth) {
+        const database = api.set.DATABASE_URL ?? existing.api.DATABASE_URL;
+        if (database)
+            set.DATABASE_URL = database;
+        set.BETTER_AUTH_URL = authUrl;
+        if (!set.BETTER_AUTH_SECRET && !existing.frontend.BETTER_AUTH_SECRET)
+            set.BETTER_AUTH_SECRET = secret();
+    }
+    // Optional: without VITE_API_URL the browser calls the API through the frontend's /api proxy.
+    const unset = frontendKeys.filter((key) => set[key] === undefined && !existing.frontend[key] && !["API_URL", "VITE_API_URL"].includes(key));
+    return { frontend: { set, unset }, api };
+}
 /**
  * DATABASE_URL_DIRECT for a database hosted elsewhere: the env file's, or for a pooled Neon URL the
  * same URL without -pooler. Never next to the platform's own database (no external URL), where it

package/dist/core/neon.js

@@ -210,20 +210,22 @@ export function savedDatabaseFor(databases, url) {
     return databases.find((database) => neonEndpoint(`postgresql://${database.host}`) === endpoint) ?? null;
 }
 /* ------------------------------ Env files ------------------------------ */
+/** A KEY= line, with or without `export`, as parseEnvFile reads it. */
+const assignment = (key, flags = "") => new RegExp(`^\\s*(export\\s+)?${key}\\s*=`, flags);
 /**
- * Sets variables in an env file's text: each KEY= line is replaced (the first one; a comment after
- * the value goes), and a missing variable is added at the end.
+ * Sets variables in an env file's text: each KEY= line is replaced (the first one, keeping its
+ * `export`; a comment after the value goes), and a missing variable is added at the end.
  */
 export function setEnvValues(text, values) {
     const eol = text.includes("\r\n") ? "\r\n" : "\n";
     const lines = text.split(/\r?\n/);
     const missing = [];
     for (const [key, value] of Object.entries(values)) {
-        const at = lines.findIndex((line) => new RegExp(`^\\s*${key}\\s*=`).test(line));
+        const at = lines.findIndex((line) => assignment(key).test(line));
         if (at === -1)
             missing.push(`${key}=${value}`);
         else
-            lines[at] = `${key}=${value}`;
+            lines[at] = `${assignment(key).exec(lines[at])[1] ? "export " : ""}${key}=${value}`;
     }
     let result = lines.join(eol);
     if (missing.length) {
@@ -233,6 +235,24 @@ export function setEnvValues(text, values) {
     }
     return result;
 }
+/**
+ * Sets only the variables an env file already declares, or returns null when it declares none:
+ * for another app that connects to the database too, such as Better Auth's server in a Vite frontend.
+ */
+export function setDeclaredEnvValues(text, values) {
+    const declared = Object.entries(values).filter(([key]) => assignment(key, "m").test(text));
+    return declared.length ? setEnvValues(text, Object.fromEntries(declared)) : null;
+}
+/**
+ * What is left to do for --infra neon when the project was created without a database, as MCP's
+ * create_project does (it makes no network calls), or null for other infrastructure.
+ */
+export function neonSetupStep(plan) {
+    if (!plan.modules.some(({ id, option }) => id === "infra" && option === "neon"))
+        return null;
+    const where = plan.databaseEnvFile ? ` in ${plan.databaseEnvFile}` : "";
+    return `The project uses Neon and has no database yet: after pnpm install, run \`pnpm clubedge neon create\` in the project for a free one (it sets DATABASE_URL and DATABASE_URL_DIRECT${where}), then \`pnpm db:migrate\`.`;
+}
 /* ------------------------------ Branches (Neon API) ------------------------------ */
 // `deploy --preview` gives a preview its own branch of the user's Neon project: a copy of the
 // production branch made in seconds, which shares storage until it changes.

package/dist/core/plan.js

@@ -412,6 +412,12 @@ export function createPlan(input) {
             apply: (text) => customizeSiteConfig(text, identity),
         });
     }
+    const envFiles = selected
+        .map(({ slot }) => ({ from: slot.env.example, to: slot.env.target }))
+        .filter(({ from }) => has(from));
+    // The API's env file even when its example is missing, as databaseEnvFile(project) resolves it
+    // later from the API's service, so the URLs written at creation are where commands look.
+    const apiEnvFile = selected.find(({ stack }) => stack.role === "api")?.slot.env.target;
     return {
         targetDirectory: input.targetDirectory,
         identity,
@@ -420,9 +426,8 @@ export function createPlan(input) {
         modules,
         files,
         edits,
-        envFiles: selected
-            .map(({ slot }) => ({ from: slot.env.example, to: slot.env.target }))
-            .filter(({ from }) => has(from)),
+        envFiles,
+        databaseEnvFile: apiEnvFile ?? envFiles[0]?.to ?? null,
         toolchains: selected.flatMap(({ slot, stack }) => stack.toolchain ? [{ directory: slot.path, app: stack.name, toolchain: stack.toolchain }] : []),
         git: input.git,
         install: input.install,

package/dist/core/project.js

@@ -42,6 +42,28 @@ export async function readProject(directory) {
         current = parent;
     }
 }
+/** The web app's: every project has it, with its example at the root. */
+const webEnvFile = { example: ".env.example", local: "apps/web/.env.local" };
+const appEnvFile = (app) => ({ example: `${app}/.env.example`, local: `${app}/.env.local` });
+/** The directory of the project's separate API, or null when the app is full-stack. */
+function apiDirectory(project) {
+    const api = Object.values(project.services).find(({ role }) => role === "api");
+    // Projects from Starter 0.22 record the API's stack but no services; the API is in apps/api.
+    return api?.app ?? (project.stacks.api ? "apps/api" : null);
+}
+/** Each app's env files: the web app's, then the API's, which keeps both in its own folder. */
+export function projectEnvFiles(project) {
+    const api = apiDirectory(project);
+    return [webEnvFile, ...(api ? [appEnvFile(api)] : [])];
+}
+/**
+ * The env file with the database URLs: the API's when the project has one, since the API owns
+ * the database (its migrations, its jobs), else the web app's. Matches the plan's databaseEnvFile.
+ */
+export function databaseEnvFile(project) {
+    const api = apiDirectory(project);
+    return api ? appEnvFile(api) : webEnvFile;
+}
 /** The files the CLI generates for this selection, without writing anything. */
 export async function renderProject(input) {
     const plan = createPlan({ ...input, targetDirectory: "", git: false, install: false });

package/dist/deploy-preview.js

@@ -42,6 +42,13 @@ async function migrate(root, branch) {
     }
 }
 export async function deployPreview(args, project, cli, envFile) {
+    // A preview is one service named after the package; a frontend and an API are two.
+    const separate = Object.values(project.services).filter(({ role }) => role !== "fullstack");
+    if (separate.length > 1) {
+        const base = serviceName(project.identity.packageName);
+        const services = separate.map(({ id }) => serviceName(`${base}-${id}`)).join(" and ");
+        throw new UsageError(`deploy --preview works with a single app for now, and this project runs its frontend and API as separate services (${services}). Deploy production with \`${cli} deploy\`; for a preview on Railway, copy production with \`railway environment new <name> --duplicate production\`, then run \`railway up --service <service> --environment <name>\` for each service.`);
+    }
     const platform = project.modules.deploy ?? "docker";
     if (platform !== "vercel" && platform !== "railway") {
         throw new UsageError(`deploy --preview works with Vercel and Railway, and this project deploys with "${platform}". Its pull requests still get a Neon branch from .github/workflows/preview.yml.`);

package/dist/deploy.js

@@ -12,7 +12,7 @@ import process from "node:process";
 import { UsageError } from "./cli/args.js";
 import { bold, dim } from "./cli/ui.js";
 import { FRAMEWORK_SLOT } from "./core/manifest.js";
-import { appPort, databaseVariables, dockerComposeSource, databasesFor, deploymentStatus, exampleKeys, externalDatabaseUrls, finalStatuses, isLocalUrl, meetsMinimumCli, minimumRailwayCli, parseDeploymentId, parseEnvFile, parseRailwayDomain, parseVariables, planVariables, railwayCliVersion, railwayDatabases, railwayIacPath, railwayIacSource, railwayReferences, serviceName, serviceNames, } from "./core/deploy.js";
+import { appPort, databaseVariables, dockerComposeSource, databasesFor, deploymentStatus, exampleKeys, externalDatabaseUrls, finalStatuses, isLocalUrl, meetsMinimumCli, minimumRailwayCli, parseDeploymentId, parseEnvFile, parseRailwayDomain, parseVariables, planServicePair, planVariables, railwayCliVersion, railwayDatabases, railwayIacPath, railwayIacSource, railwayReferences, serviceName, serviceNames, } from "./core/deploy.js";
 import { neonDatabaseState } from "./core/neon.js";
 import { readProject } from "./core/project.js";
 import { savedDatabaseForUrl } from "./neon.js";
@@ -259,42 +259,39 @@ async function deployRailwayServices(args, project, cli, envFile) {
     if (!domain)
         throw new Error("Railway created no frontend domain. Create one in its settings, then run deploy again.");
     const url = `https://${domain}`;
-    const apiEnv = Object.fromEntries(Object.entries(envFile).filter(([key]) => !key.startsWith("VITE_")));
-    const apiPlan = planVariables({
+    const listedWebVars = await attempt(() => railway(rw, ["variable", "list", "--service", names.frontend, "--json"]));
+    if (listedWebVars === null && existing.includes(names.frontend)) {
+        throw new Error(`Railway didn't list the variables of the frontend service "${names.frontend}", so deploy changed nothing. Run deploy again; if it keeps failing, check \`railway variable list --service ${names.frontend}\`.`);
+    }
+    const webVars = parseVariables(listedWebVars ?? "");
+    const plan = planServicePair({
         modules: project.modules,
-        keys: keys.filter((key) => !key.startsWith("VITE_")),
+        frontendKeys: keys,
+        apiKeys: exampleKeys(await readFile(join(project.root, apiStack.app, ".env.example"), "utf8").catch(() => "")),
         url,
-        existing: apiVars,
-        envFile: apiEnv,
+        existing: { frontend: webVars, api: apiVars },
+        envFile,
         secret: () => randomBytes(32).toString("hex"),
         databases: railwayReferences(databases),
-        port: apiStack.port,
+        ports: { frontend: frontendStack.port, api: apiStack.port },
     });
-    apiPlan.set.FRONTEND_URL = url;
-    if (apiPlan.unset.length) {
-        log.warn(`Not set on the API service: ${apiPlan.unset.join(", ")}. Pass --env-file to supply values before deployment.`);
+    const unset = [
+        ...(plan.api.unset.length ? [`Not set on the API service: ${plan.api.unset.join(", ")}.`] : []),
+        ...(plan.frontend.unset.length ? [`Not set on the frontend service: ${plan.frontend.unset.join(", ")}.`] : []),
+    ];
+    if (unset.length) {
+        log.warn(`${unset.join("\n")}\nPass --env-file to supply values before deployment.`);
         if (process.stdin.isTTY && !args.yes) {
             const proceed = await confirm({ message: "Deploy anyway?", initialValue: true });
             if (isCancel(proceed) || !proceed)
                 return cancel("Nothing was uploaded. Set the variables, then run deploy again.");
         }
     }
-    for (const [key, value] of Object.entries(apiPlan.set)) {
+    for (const [key, value] of Object.entries(plan.api.set)) {
         if (apiVars[key] !== value)
             await railway(rw, ["variable", "set", key, "--stdin", "--service", names.api, "--skip-deploys"], { input: value });
     }
-    const webVars = parseVariables(await attempt(() => railway(rw, ["variable", "list", "--service", names.frontend, "--json"])) ?? "");
-    const missingWebBuildVars = keys.filter((key) => key.startsWith("VITE_") && !envFile[key] && !webVars[key]);
-    if (missingWebBuildVars.length) {
-        log.warn(`Not set on the frontend service: ${missingWebBuildVars.join(", ")}. Pass --env-file to provide them.`);
-        if (process.stdin.isTTY && !args.yes) {
-            const proceed = await confirm({ message: "Deploy anyway?", initialValue: true });
-            if (isCancel(proceed) || !proceed)
-                return cancel("Nothing was uploaded. Set the variables, then run deploy again.");
-        }
-    }
-    const webSet = { PORT: String(frontendStack.port), ...Object.fromEntries(Object.entries(envFile).filter(([key, value]) => key.startsWith("VITE_") && value)) };
-    for (const [key, value] of Object.entries(webSet)) {
+    for (const [key, value] of Object.entries(plan.frontend.set)) {
         if (webVars[key] !== value)
             await railway(rw, ["variable", "set", key, "--stdin", "--service", names.frontend, "--skip-deploys"], { input: value });
     }
@@ -357,7 +354,8 @@ export async function deployProject(args) {
         if (unsupported.length) {
             throw new UsageError(`The selected stacks do not declare Docker deployment support for ${unsupported.map(([slot]) => slot).join(", ")}.`);
         }
-        const compose = dockerComposeSource(Object.fromEntries(separateApps));
+        const frontendKeys = exampleKeys(await readFile(join(project.root, ".env.example"), "utf8").catch(() => ""));
+        const compose = dockerComposeSource(Object.fromEntries(separateApps), frontendKeys);
         if (args.dryRun) {
             log.message(`Docker Compose will start ${separateApps.map(([slot, service]) => `${slot} (${service.dockerfile}, port ${service.port})`).join(" and ")}; the frontend proxies /api to the API over the Compose network.`);
             outro("Dry run: nothing was written. Run deploy to generate compose.yaml.");
@@ -368,7 +366,8 @@ export async function deployProject(args) {
             throw new UsageError("compose.yaml already exists. Review it and remove it before generating the stack configuration again.");
         await writeFile(path, compose);
         note(`Generated compose.yaml for ${separateApps.map(([slot]) => slot).join(" and ")}.`, "Docker Compose deployment");
-        outro(`Copy .env.example to .env.production and set its values, then run from the project root:\n  docker compose --env-file .env.production up --build -d\n\nThe frontend is published on its declared port; the API stays on the private Compose network.`);
+        const examples = [".env.example", ...separateApps.filter(([, service]) => service.role === "api").map(([, service]) => `${service.app}/.env.example`)];
+        outro(`Copy the variables of ${examples.join(" and ")} to .env.production and set their values, then run from the project root:\n  docker compose --env-file .env.production up --build -d\n\nThe frontend is published on its declared port; the API stays on the private Compose network.`);
         return;
     }
     if (separateApps.length > 1) {

package/dist/index.js

@@ -158,6 +158,7 @@ async function createProject(args) {
     // The spinner runs while the manifest is read and again while files are written.
     let spinning = "preparing";
     let neonEnvFile = null;
+    let sharedEnvFiles = [];
     let toolchains = [];
     try {
         const manifest = await readTemplateManifest(source.root);
@@ -185,9 +186,11 @@ async function createProject(args) {
             git: args.git,
             install: args.install,
         });
-        // --infra neon: a free Neon database, its URLs written into the new env file.
+        // --infra neon: a free Neon database, its URLs written into the env file of the app that owns
+        // the database (the API, when the project has one).
         toolchains = plan.toolchains;
-        neonEnvFile = plan.modules.some(({ id, option }) => id === "infra" && option === "neon") && args.neon ? (plan.envFiles[0]?.to ?? null) : null;
+        neonEnvFile = plan.modules.some(({ id, option }) => id === "infra" && option === "neon") && args.neon ? plan.databaseEnvFile : null;
+        sharedEnvFiles = plan.envFiles.map(({ to }) => to);
         if (args.dryRun) {
             const lines = [...describePlan(plan), ...(neonEnvFile ? [`Create a free Neon database and set its URLs in ${neonEnvFile}`] : [])];
             log.message(lines.map((line) => `• ${line}`).join("\n"));
@@ -215,7 +218,7 @@ async function createProject(args) {
     if (neonEnvFile) {
         progress.start("Creating a free Neon database");
         try {
-            const created = await provisionNeonDatabase(targetDirectory, neonEnvFile);
+            const created = await provisionNeonDatabase(targetDirectory, neonEnvFile, sharedEnvFiles);
             progress.stop(describeNewDatabase(created, "pnpm clubedge"));
             migrate = "db:migrate";
         }