create-basalt 1.10.0 → 1.11.0

package/README.md

@@ -93,7 +93,7 @@ Usage: npm create basalt <name> [options]
 | `--no-auth` | auth **on** | Removes authentication (`@basaltkit/auth`, `APP_SECRET`, `/auth/*` routes) |
 | `--billing` | off | Includes subscriptions/plans (`@basaltkit/subscriptions`, example `free` and `pro` plans) |
 | `--ui` | off | Generates the `web/` frontend (React + shadcn via `@basaltkit/admin-shadcn` + `@basaltkit/sdk`). **Forces pnpm** — see note below |
-| `--cli` | off | Generates the `basalt` CLI (`bin/basalt.ts`, `pnpm basalt` script, `make:*` generators from `@basaltkit/generator`) |
+| `--no-cli` | CLI on | Skips the `basalt` CLI (by default every app gets it: `bin/basalt.ts`, the `pnpm basalt` script, `make:*` generators from `@basaltkit/generator`) |
 | `--mcp` | off | Exposes read-only routes as MCP tools (`@basaltkit/mcp`) over HTTP at `POST /mcp` — the overview and health endpoints are opted in via `meta.mcp` |
 | `--prisma` (alias `--db`) | off | Backs the app with PostgreSQL through Prisma: `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, the `@basaltkit/*-prisma` stores instead of the in-memory ones, a required `<APP>_DATABASE_URL`, the `db:*` scripts and `prismaPlugin({ assertMigrated: true })` — see *With `--prisma`* below |
 | `--install` | off | Installs dependencies at the end (with the detected/chosen manager) |
@@ -120,7 +120,7 @@ Behavior notes (faithful to the code):
 pnpm create basalt
 
 # Full project, no questions, with everything:
-pnpm create basalt my-app --billing --ui --cli --prisma --install --git
+pnpm create basalt my-app --billing --ui --prisma --install --git
 
 # Minimal API (no tenancy or auth), in another folder:
 npm create basalt service-api --no-tenancy --no-auth --dir=./apps/service-api
@@ -141,7 +141,8 @@ my-app/
 ├── package.json          # scripts: dev, start, test, typecheck, basalt (+ dev:web with --ui); create-basalt as a devDependency
 ├── .basalt/project.json  # scaffold manifest: create-basalt version, options, a hash per generated file — commit it
 ├── tsconfig.json         # strict TypeScript, ESM
-├── .env.example          # MY_APP_PORT, MY_APP_HOST, MY_APP_LOG_LEVEL, NODE_ENV (+ MY_APP_APP_SECRET with auth) + the --env-file precedence warning
+├── .env.example          # MY_APP_PORT, MY_APP_HOST, MY_APP_LOG_LEVEL, NODE_ENV (+ MY_APP_APP_SECRET with auth) + the precedence warning — committed
+├── .env                  # the same values for local development (+ a generated MY_APP_APP_SECRET with auth) — git-ignored, loaded by dev/basalt
 ├── .gitignore
 ├── README.md             # instructions adapted to the chosen options
 ├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* + create-basalt release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
@@ -149,11 +150,12 @@ my-app/
 │   ├── env.ts            # environment variables validated with Zod (@basaltkit/env), app-prefixed
 │   ├── app.ts            # buildApp() with the chosen plugins
 │   ├── routes.ts         # GET / (friendly index) and GET /health
-│   └── server.ts         # startup + clean shutdown on SIGINT/SIGTERM
+│   ├── server.ts         # startup + clean shutdown on SIGINT/SIGTERM (`pnpm start` — loads no .env)
+│   └── dev.ts            # `pnpm dev`: loads .env, defaults NODE_ENV=development, starts server.ts
 └── tests/app.test.ts     # smoke test adapted to the options
 ```
 
-With `--prisma`, adds `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, `prisma/seed.ts` (with tenancy) and the `db:generate` / `db:migrate` / `db:deploy` / `db:seed` scripts. The `basalt` script is `create-basalt --project` without `--cli` (so `pnpm basalt update|add|doctor|info` works in every app); with `--cli` it is `tsx bin/basalt.ts`, and `bin/basalt.ts` forwards those four commands to create-basalt before booting the app. With `--ui`, adds the `web/` folder (Vite 8 + React 19 + Tailwind CSS 4 via `@tailwindcss/vite` + shadcn — Tailwind is configured in `web/src/index.css`, no `tailwind.config.js`/PostCSS — with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
+With `--prisma`, adds `prisma/schema.prisma`, `prisma.config.ts`, `src/db.ts`, `prisma/seed.ts` (with tenancy) and the `db:generate` / `db:migrate` / `db:deploy` / `db:seed` scripts. The `basalt` script is `create-basalt --project` with `--no-cli` (so `pnpm basalt update|add|doctor|info` works in every app); with `--cli` it is `tsx bin/basalt.ts`, and `bin/basalt.ts` forwards those four commands to create-basalt before booting the app. With `--ui`, adds the `web/` folder (Vite 8 + React 19 + Tailwind CSS 4 via `@tailwindcss/vite` + shadcn — Tailwind is configured in `web/src/index.css`, no `tailwind.config.js`/PostCSS — with `web/src/api.ts` built on top of `@basaltkit/sdk`; with auth on it includes a login/register screen).
 
 ### With `--ui`: running the API and frontend
 
@@ -185,7 +187,7 @@ the next restart.
 ```bash
 pnpm create basalt my-app --prisma
 cd my-app && pnpm install     # postinstall runs `prisma generate`
-cp .env.example .env          # point MY_APP_DATABASE_URL at your database
+# .env already points MY_APP_DATABASE_URL at postgres://…@localhost:5432/my_app — start PostgreSQL or edit it
 pnpm db:migrate               # prisma migrate dev — creates the tables and seeds `demo`
 pnpm dev
 ```
@@ -201,9 +203,9 @@ the database and host instead of a `500` on the first request. In production:
 The generated `tests/app.test.ts` skips itself when no database is configured, so
 `pnpm test` stays green on a machine without PostgreSQL. To add another Basalt
 domain later, install its `@basaltkit/<domain>-prisma` package, run
-`pnpm basalt prisma:sync` (with `--cli`) and then `pnpm db:migrate`.
+`pnpm basalt prisma:sync` (unless `--no-cli`) and then `pnpm db:migrate`.
 
-### With `--cli`: the `basalt` command line
+### The `basalt` command line (default; `--no-cli` skips it)
 
 ```bash
 pnpm basalt list                    # available commands
@@ -215,7 +217,7 @@ With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies
 
 ## Project commands: update, add, doctor, info
 
-Run inside an existing Basalt app — any app, created with or without `--cli`,
+Run inside an existing Basalt app — any app, created with or without the CLI (`--no-cli`),
 by any create-basalt release:
 
 ```bash
@@ -235,7 +237,7 @@ field, then the lockfile), and output is colored unless `NO_COLOR` is set,
 `--no-color` is passed or stdout is not a terminal.
 
 **How `pnpm basalt <command>` reaches them.** New apps list `create-basalt` as a
-devDependency. Without `--cli` the `basalt` script is `create-basalt --project`;
+devDependency. With `--no-cli` the `basalt` script is `create-basalt --project`;
 with `--cli`, `bin/basalt.ts` handles `update`/`add`/`doctor`/`info` **before**
 importing anything of the app (they must work while the app is broken
 mid-upgrade) and runs the installed create-basalt — or `pnpm dlx` /
@@ -255,7 +257,7 @@ pnpm basalt update            # asks, writes, installs, runs the codemods
 | `--major` | Lets third-party packages cross a major too |
 | `--only=@basaltkit` | Only the framework packages (and `create-basalt`) |
 | `--no-install` | Writes `package.json`, skips the install and the codemods |
-| `--no-tooling` | Leaves `bin/basalt.ts` and the `create-basalt` devDependency alone |
+| `--no-tooling` | Leaves `bin/basalt.ts`, `src/dev.ts`, `.env.example` and the `create-basalt` devDependency alone |
 
 The policy is the scaffold's own (the same registry code): `@basaltkit/*` and
 `create-basalt` go to `latest` across majors — each framework major prints a
@@ -278,10 +280,13 @@ edits stay and the command says how to revert (`git checkout -- package.json …
 
 Project tooling rides along (skip with `--no-tooling`): an app without the
 `create-basalt` devDependency gets it plus a `basalt` script (and a
-`create-basalt` entry in `minimumReleaseAgeExclude`), and a `bin/basalt.ts`
-generated by an earlier release gains the project commands — **only** when it is
-byte-for-byte a known template (or the manifest records it untouched); a
-customised one is left alone and the exact snippet to paste is printed.
+`create-basalt` entry in `minimumReleaseAgeExclude`); a `bin/basalt.ts`
+generated by an earlier release gains the project commands, `.env` loading, a
+pre-boot `upgrade` and the readable env error; a `src/dev.ts` from 1.9/1.10 gains
+`.env` loading; and the `.env.example` header stops saying "nothing loads this
+file". Files are patched **only** when they are byte-for-byte a known template
+(or the manifest records them untouched); a customised one is left alone and the
+exact snippet to paste is printed.
 
 ### Adding features later
 
@@ -320,10 +325,14 @@ lockfiles; installed versus declared versions, duplicated `@basaltkit/*`
 versions and unmet peer ranges; framework packages behind `latest` (skip with
 `--offline`); the auth secret (`<PREFIX>_APP_SECRET`, from the environment or
 `.env`, against the `minLength` in `src/env.ts` and the placeholder rules of
-`secret()`) and `DATABASE_URL`; whether the Prisma client is generated and
+`secret()`); every variable `src/env.ts` **requires** (declared without a
+default — `DATABASE_URL` with `--prisma`) that is set neither in the environment
+nor in `.env` — an error, with the fix (`cp .env.example .env`, set it, start
+PostgreSQL); a missing `.env` next to a `.env.example` (warning); whether the Prisma client is generated and
 migrations exist (whether they are *applied* needs a database —
 `prisma migrate status`); `.mcp.json` when `@basaltkit/ai-mcp` is installed; dev
-tooling declared as a runtime dependency; and an outdated `bin/basalt.ts`.
+tooling declared as a runtime dependency; and an outdated `bin/basalt.ts` or
+`src/dev.ts`.
 
 `info` prints create-basalt, Node, OS, package manager, the app's features and
 the declared/installed versions of the framework and key tools — paste it into
@@ -345,7 +354,9 @@ yours; the first `add` creates the manifest.
 
 ### Environment variables and `--env-file`
 
-Nothing loads `.env` for you. `node --env-file=.env` / `tsx --env-file=.env` **never override a variable already exported in the shell** — in a terminal where another project exported `DATABASE_URL` or `PORT`, an app reading the generic name boots against that value and only fails on the first request that touches it.
+**Development loads `.env`; production does not.** `pnpm dev` (`src/dev.ts`) and `pnpm basalt` (`bin/basalt.ts`, scaffolded unless `--no-cli`) load `.env` from the project root when it exists, with `node --env-file` semantics. `pnpm start` (`src/server.ts`) loads **nothing**: in production the configuration comes from the real environment (or start it yourself with `node --env-file=…`). A new app gets a ready-made `.env` — a copy of `.env.example` with local values and, with auth, a generated `APP_SECRET` — git-ignored (`.gitignore` and `.dockerignore`) and written with mode `0600`; `.env.example` stays the committed template. `prisma.config.ts` loads the same file for the Prisma CLI.
+
+Loading `.env` — like `node --env-file=.env` / `tsx --env-file=.env` — **never overrides a variable already exported in the shell**: in a terminal where another project exported `DATABASE_URL` or `PORT`, an app reading the generic name boots against that value and only fails on the first request that touches it.
 
 The scaffold closes that trap instead of only warning about it: `src/env.ts` passes an **app-specific prefix** derived from the project name (`my-saas` → `MY_SAAS`) to `defineEnv`, and `.env.example` uses the prefixed names.
 
@@ -366,6 +377,8 @@ NODE_ENV=development          # never prefixed — a Node-wide convention
 # MY_SAAS_APP_SECRET=         # with auth
 ```
 
+When a variable is invalid or missing, `pnpm basalt <command>` does not print a stack trace: it lists the variables (`EnvValidationError.report`), says where they were read from (the environment, and `.env` when it exists) and how to fix it — `cp .env.example .env`, fill them in, and for `DATABASE_URL` start PostgreSQL — then exits 1. `BASALT_DEBUG=1` (or `--debug`) shows the stack. The database gets the same treatment: PostgreSQL not answering (`ECONNREFUSED`, Prisma `P1001`, or an `assertMigrated` that could not query it) and an unmigrated database (`PRISMA_NOT_MIGRATED`) print what failed, the database in use — `postgres://host:port/name` and the variable it came from, never the credentials — and the fix (start PostgreSQL, e.g. `docker compose up -d`; check `MY_SAAS_DATABASE_URL`; `pnpm db:migrate`). Any other boot error keeps its stack trace. `pnpm basalt upgrade` (the `@basaltkit/cli` codemods) never boots the app, so it runs even when the environment is incomplete.
+
 Each variable is read as `MY_SAAS_<NAME>` first and **falls back** to the bare `<NAME>`, so a deployment that already exports the generic names keeps booting — while a stray `PORT` in your shell no longer wins. The rest of the app is unchanged: the keys stay bare (`env.PORT`). To require the prefixed names only, edit the generated file to `prefix: { value: 'MY_SAAS', fallback: false }`. Full rules: [`@basaltkit/env`](https://github.com/basaltkit/basalt/tree/main/packages/env#app-specific-prefix-prefix).
 
 ### Programmatic usage (Advanced)
@@ -418,7 +431,7 @@ Exported from `create-basalt` (in addition to the `create-basalt` executable):
 | Field | Type | Description |
 | --- | --- | --- |
 | `dir` | `string` | Absolute path of the created folder |
-| `files` | `string[]` | Files written (relative, sorted) |
+| `files` | `string[]` | Files written (relative, sorted) — includes the development `.env` |
 | `options` | `ProjectOptions` | The options actually applied (with defaults resolved) |
 | `versions` | `VersionResolution \| undefined` | With `resolveLatest`: `{ versions, resolved, failed, heldBack, tooFresh, registry }` — the final ranges, which packages got `^<latest>`, which kept the fallback after a registry failure, third-party packages held back because their latest is a new major, and third-party packages whose latest is not provably older than the release-age window (`{ name, latest, range, reason: 'recent' \| 'unknown' }`) |
 
@@ -469,9 +482,12 @@ Outside an interactive terminal (no TTY) the questions are skipped. Always pass
 Automatic installation failed (network, Node version, etc.). Go into the folder and run `pnpm install` (or the indicated manager) to see the real error.
 
 **I started the app and `GET /auth/login` gives a secret error.**
-With auth on, `src/env.ts` requires `APP_SECRET` — read as `MY_SAAS_APP_SECRET`, with at least 32 characters (`secret()` supplies a development default only when `NODE_ENV` is explicitly `development`/`test`). Copy `.env.example` to `.env` and set your own secret before going to production.
+With auth on, `src/env.ts` requires `APP_SECRET` — read as `MY_SAAS_APP_SECRET`, with at least 32 characters (`secret()` supplies a development default only when `NODE_ENV` is explicitly `development`/`test`). For development the scaffold's `.env` carries a generated one; in production export your own (`openssl rand -base64 48`) — `pnpm start` does not read `.env`.
 
-**With `--prisma`, the app refuses to boot: `PRISMA_NOT_MIGRATED`.**
+**`The app cannot start — the database did not answer`.**
+PostgreSQL is not running, or `MY_SAAS_DATABASE_URL` points at the wrong host/port (the message shows which, without credentials). Start it (`docker compose up -d`, or your local service) or fix the URL in `.env`; on a fresh database, `pnpm db:migrate`. `pnpm dev` still prints the raw error (the explainer lives in `bin/basalt.ts` only, so `src/dev.ts` stays a few lines); `pnpm basalt routes` gives the explained version.
+
+**With `--prisma`, the app refuses to boot: `PRISMA_NOT_MIGRATED`** (from `pnpm basalt`: `The app cannot start — the database is not migrated`).
 `assertMigrated` reached a database without the `_prisma_migrations` table. The
 message names the database and host it actually reached (never the
 credentials): either it is not the database you meant — check
@@ -486,7 +502,10 @@ The Prisma client is generated code, not a checked-in file. `pnpm install` runs
 or after editing the schema, run `pnpm db:generate`.
 
 **My app connects to the wrong database / port.**
-A variable exported in your shell beats `--env-file`. The generated `src/env.ts` already reads app-prefixed names (`MY_SAAS_PORT`), so set those rather than the generic ones — the bare names are only a fallback. Check `env | grep DATABASE_URL`, and see *Environment variables and `--env-file`*.
+A variable exported in your shell beats `.env` (as with `--env-file`). The generated `src/env.ts` already reads app-prefixed names (`MY_SAAS_PORT`), so set those rather than the generic ones — the bare names are only a fallback. Check `env | grep DATABASE_URL`, and see *Environment variables and `--env-file`*.
+
+**`The app cannot start — invalid environment variables` (or `EnvValidationError: … expected string, received undefined`).**
+A required variable is set neither in your shell nor in `.env`. Apps from create-basalt ≤ 1.10 did not load `.env` at all in `pnpm dev` / `pnpm basalt`: run `npx create-basalt@latest update` once — it patches an unmodified `bin/basalt.ts` and `src/dev.ts`. Then `cp .env.example .env` if there is no `.env`, fill the variables listed, and run `pnpm basalt doctor` to check. `pnpm start` never reads `.env`: export the variables there.
 
 **`pnpm basalt …` starts by running `pnpm install` (or fails offline).**
 pnpm 11's `verifyDepsBeforeRun` (default `install`). Run `node_modules/.bin/tsx bin/basalt.ts …` instead, or set `verifyDepsBeforeRun: warn` in `pnpm-workspace.yaml`.
@@ -515,6 +534,6 @@ The app's `bin/basalt.ts` predates the project commands. Run `npx create-basalt@
 - **`@basaltkit/auth`** — included by default (remove with `--no-auth`): `/auth/*` routes and `APP_SECRET` validated in `env.ts`.
 - **`@basaltkit/subscriptions`** — with `--billing`: example `free`/`pro` plans with trial and feature limits.
 - **`@basaltkit/prisma` + `@basaltkit/{tenancy,auth,teams,subscriptions}-prisma`** — with `--prisma`: the PostgreSQL layer — `prismaPlugin` (tenant-scoped client, boot-time `assertMigrated`), the composed `prisma/schema.prisma` and the Prisma-backed stores for whichever domains are on.
-- **`@basaltkit/cli` + `@basaltkit/generator`** — with `--cli`: `bin/basalt.ts` calls `runCli`, and `commandsPlugin(generatorCommands())` registers the `make:*` generators. `update` runs the installed `@basaltkit/cli` upgrade codemods after an install.
+- **`@basaltkit/cli` + `@basaltkit/generator`** — by default (not with `--no-cli`): `bin/basalt.ts` calls `runCli`, and `commandsPlugin(generatorCommands())` registers the `make:*` generators. `update` runs the installed `@basaltkit/cli` upgrade codemods after an install.
 - **`@basaltkit/sdk` + `@basaltkit/admin-shadcn` + `@basaltkit/admin`** — with `--ui`: the `web/` frontend calls the API through a typed client and uses the shadcn components.
 - **`@basaltkit/testing`** — always present in `devDependencies`, with a generated smoke test in `tests/app.test.ts`.

package/dist/args.d.ts

@@ -1,5 +1,5 @@
 import type { PackageManager } from './index.js';
-export declare const USAGE = "Usage: npm create basalt <name> [options]\n\nOptions:\n  --name=<name>   Project name (the way to create a project named like a\n                  project command: update, add, doctor, info)\n  --dir=<path>    Target directory (default: ./<name>)\n  --no-tenancy    Skip multi-tenancy\n  --no-auth       Skip authentication\n  --billing       Include subscriptions/billing\n  --ui            Scaffold a web/ frontend (React + shadcn + SDK)\n  --cli           Scaffold the 'basalt' CLI (code generators + commands)\n  --mcp           Expose read-only routes as MCP tools at /mcp\n  --prisma, --db  Back the app with PostgreSQL through Prisma: schema,\n                  migrations, prisma-backed stores and a boot-time check\n                  that the database is the migrated one\n  --install       Install dependencies (default: yes in an interactive\n                  terminal, skipped in CI/non-TTY; --no-install to opt out)\n  --no-install    Never install dependencies\n  --git           Initialize a git repository with a first commit\n                  (same default rule as --install; --no-git to opt out)\n  --no-git        Never initialize a git repository\n  --offline       Don't query the npm registry for the latest versions;\n                  use the ranges bundled with this create-basalt release\n  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)\n  -y, --yes       Skip prompts and accept defaults\n  -h, --help      Show this help\n\nRun with no name in a terminal to be prompted interactively.\n\nProject commands \u2014 inside an existing app (in a scaffolded app: pnpm basalt <command>):\n  create-basalt update            Update dependencies to the latest versions (--dry, --major, \u2026)\n  create-basalt add <feature>     Add ui | cli | mcp to the app\n  create-basalt doctor            Check the project's health\n  create-basalt info              Versions summary for bug reports\n  create-basalt <command> --help  Options of one command\n";
+export declare const USAGE = "Usage: npm create basalt <name> [options]\n\nOptions:\n  --name=<name>   Project name (the way to create a project named like a\n                  project command: update, add, doctor, info)\n  --dir=<path>    Target directory (default: ./<name>)\n  --no-tenancy    Skip multi-tenancy\n  --no-auth       Skip authentication\n  --billing       Include subscriptions/billing\n  --ui            Scaffold a web/ frontend (React + shadcn + SDK)\n  --no-cli        Skip the 'basalt' CLI (code generators + commands;\n                  on by default)\n  --mcp           Expose read-only routes as MCP tools at /mcp\n  --prisma, --db  Back the app with PostgreSQL through Prisma: schema,\n                  migrations, prisma-backed stores and a boot-time check\n                  that the database is the migrated one\n  --install       Install dependencies (default: yes in an interactive\n                  terminal, skipped in CI/non-TTY; --no-install to opt out)\n  --no-install    Never install dependencies\n  --git           Initialize a git repository with a first commit\n                  (same default rule as --install; --no-git to opt out)\n  --no-git        Never initialize a git repository\n  --offline       Don't query the npm registry for the latest versions;\n                  use the ranges bundled with this create-basalt release\n  --pm=<manager>  Package manager: pnpm | npm | yarn | bun (default: auto-detect)\n  -y, --yes       Skip prompts and accept defaults\n  -h, --help      Show this help\n\nRun with no name in a terminal to be prompted interactively.\n\nProject commands \u2014 inside an existing app (in a scaffolded app: pnpm basalt <command>):\n  create-basalt update            Update dependencies to the latest versions (--dry, --major, \u2026)\n  create-basalt add <feature>     Add ui | cli | mcp to the app\n  create-basalt doctor            Check the project's health\n  create-basalt info              Versions summary for bug reports\n  create-basalt <command> --help  Options of one command\n";
 export interface Flags {
     name?: string;
     dir?: string;

package/dist/args.js

@@ -9,7 +9,8 @@ Options:
   --no-auth       Skip authentication
   --billing       Include subscriptions/billing
   --ui            Scaffold a web/ frontend (React + shadcn + SDK)
-  --cli           Scaffold the 'basalt' CLI (code generators + commands)
+  --no-cli        Skip the 'basalt' CLI (code generators + commands;
+                  on by default)
   --mcp           Expose read-only routes as MCP tools at /mcp
   --prisma, --db  Back the app with PostgreSQL through Prisma: schema,
                   migrations, prisma-backed stores and a boot-time check
@@ -41,7 +42,7 @@ export function parseArgs(argv) {
         auth: true,
         billing: false,
         ui: false,
-        cli: false,
+        cli: true,
         mcp: false,
         prisma: false,
         yes: false,
@@ -58,6 +59,8 @@ export function parseArgs(argv) {
             flags.ui = true;
         else if (token === '--cli')
             flags.cli = true;
+        else if (token === '--no-cli')
+            flags.cli = false;
         else if (token === '--mcp')
             flags.mcp = true;
         // `--db` reads naturally in a sentence ("scaffold it with a db") and is the

package/dist/bin-template.d.ts

@@ -1,5 +1,7 @@
 /** Marker proving a bin/basalt.ts already delegates the project commands. */
 export declare const PROJECT_COMMANDS_MARKER = "['update', 'add', 'doctor', 'info'].includes(process.argv[2]";
+/** Marker proving a bin/basalt.ts already has the dev prelude (.env loading, `upgrade`, env errors). */
+export declare const DEV_PRELUDE_MARKER = "process.loadEnvFile(envFile)";
 export declare function basaltBin(): string;
 /**
  * Hashes of every bin/basalt.ts an earlier create-basalt release generated
@@ -8,16 +10,19 @@ export declare function basaltBin(): string;
  */
 export declare const LEGACY_BIN_HASHES: ReadonlySet<string>;
 export declare const hasProjectCommands: (content: string) => boolean;
+export declare const hasDevPrelude: (content: string) => boolean;
 /**
- * Upgrades a template-generated bin/basalt.ts to delegate the project
- * commands: inserts the prelude after the shebang and turns the remaining
- * static imports into dynamic ones (so they no longer run before it).
- * Deterministic for the known templates — for the latest one the result is
- * exactly {@link basaltBin}.
+ * Upgrades a template-generated bin/basalt.ts to the current template, step by
+ * step: (1) without the project commands, inserts their prelude after the
+ * shebang and turns the remaining static imports into dynamic ones (so they no
+ * longer run before it); (2) without the dev prelude, inserts it right after
+ * the project commands and routes the app import through `explainBootFailure`.
+ * Deterministic for the known templates — for the latest ones (1.9, 1.10) the
+ * result is exactly {@link basaltBin}.
  */
 export declare function patchBasaltBin(content: string): string;
 export type BinStatus = 'current' | 'patchable' | 'modified' | 'absent';
-/** Where a bin/basalt.ts stands: already delegating, an untouched old template, or user code. */
+/** Where a bin/basalt.ts stands: already current, an untouched old template, or user code. */
 export declare function binStatus(content: string | undefined, manifestHash?: string): BinStatus;
-/** What to paste by hand into a customised bin/basalt.ts. */
-export declare const MANUAL_BIN_SNIPPET = "Paste this right after the shebang line of bin/basalt.ts, then turn its\nstatic imports of @basaltkit/* and ../src/app.js into dynamic ones\n(`import { runCli } from '@basaltkit/cli'` \u2192 `const { runCli } = await import('@basaltkit/cli')`)\nso they no longer run before it:\n\nimport { spawnSync } from 'node:child_process'\nimport { existsSync, readFileSync } from 'node:fs'\nimport { join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n// Project commands run BEFORE anything of the app is imported, so they keep\n// working while the app is broken mid-upgrade. create-basalt provides them \u2014\n// the project's devDependency when installed, else its latest release:\n//   pnpm basalt update                  \u2014 update dependencies to the latest versions (--dry to preview)\n//   pnpm basalt add ui                  \u2014 add a feature later (ui, cli, mcp)\n//   pnpm basalt doctor                  \u2014 check the project's health\n//   pnpm basalt info                    \u2014 versions summary for bug reports\nconst root = fileURLToPath(new URL('..', import.meta.url))\nif (['update', 'add', 'doctor', 'info'].includes(process.argv[2] ?? '')) {\n  process.exit(createBasalt(process.argv.slice(2)))\n}\n\n/** Runs create-basalt: the installed devDependency, else `<pm> dlx create-basalt@latest`. */\nfunction createBasalt(args: string[]): number {\n  const local = join(root, 'node_modules', 'create-basalt', 'dist', 'cli.js')\n  if (existsSync(local)) {\n    return spawnSync(process.execPath, [local, ...args], { cwd: root, stdio: 'inherit' }).status ?? 1\n  }\n  let declared = ''\n  try {\n    declared = String(JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).packageManager ?? '')\n  } catch {\n    // No readable package.json: the lockfiles decide.\n  }\n  const uses = (pm: string, ...lockfiles: string[]): boolean =>\n    declared.startsWith(`${pm}@`) || lockfiles.some((file) => existsSync(join(root, file)))\n  const [command, prefix]: [string, string[]] = uses('pnpm', 'pnpm-lock.yaml')\n    ? ['pnpm', ['dlx']]\n    : uses('bun', 'bun.lock', 'bun.lockb')\n      ? ['bunx', []]\n      : ['npx', ['--yes']]\n  const result = spawnSync(command, [...prefix, 'create-basalt@latest', ...args], {\n    cwd: root,\n    stdio: 'inherit',\n    shell: process.platform === 'win32',\n  })\n  return result.status ?? 1\n}\n";
+/** What to paste by hand into a customised bin/basalt.ts (only the parts it lacks). */
+export declare function manualBinSnippet(content: string): string;

package/dist/bin-template.js

@@ -55,11 +55,122 @@ function createBasalt(args: string[]): number {
   return result.status ?? 1
 }
 `;
+/**
+ * The DEV PRELUDE, right after the project commands and still before anything
+ * of the app is imported:
+ *
+ * - `upgrade` (the @basaltkit/cli codemods) only rewrites source files, so it
+ *   runs without booting the app — it must keep working while the app cannot
+ *   start (that is usually why you are upgrading);
+ * - `.env` is loaded for development with `node --env-file` semantics: a
+ *   variable already exported in the shell wins, the file only fills in what
+ *   is missing (the app-prefixed names in src/env.ts exist because of exactly
+ *   that rule). `pnpm start` / src/server.ts never loads it;
+ * - a boot-time `EnvValidationError` becomes a fix (which variables, where they
+ *   are read from, what to do) instead of a stack trace.
+ */
+const DEV_PRELUDE = `// \`upgrade\` (framework codemods) only rewrites source files: it runs without
+// booting the app, so it works even while the app cannot start.
+if (process.argv[2] === 'upgrade') {
+  const { consoleIo, parseArgv, upgradeCommand } = await import('@basaltkit/cli')
+  const { args, flags } = parseArgv(process.argv.slice(2))
+  // upgradeCommand reads only io/args/flags — there is no app to hand it.
+  const context = { io: consoleIo(), args, flags } as unknown as Parameters<typeof upgradeCommand.handle>[0]
+  process.exit((await upgradeCommand.handle(context)) ?? 0)
+}
+
+// Development loads .env (when present) like \`node --env-file=.env\`: a variable
+// already exported in your shell still wins, the file only fills in what is
+// missing. \`pnpm start\` (production) never loads it — there the configuration
+// comes from the real environment.
+const envFile = join(root, '.env')
+if (existsSync(envFile)) process.loadEnvFile(envFile)
+
+/**
+ * A boot failure as a fix instead of a stack trace (stack: BASALT_DEBUG=1 or --debug):
+ * invalid environment variables, a database that does not answer, one that is not
+ * migrated. Anything else is rethrown untouched.
+ */
+async function explainBootFailure(error: unknown): Promise<never> {
+  const failure = (error ?? {}) as { code?: unknown; report?: unknown; message?: unknown; cause?: unknown; errors?: unknown }
+  const message = String(failure.message ?? '')
+  const codes = [failure, failure.cause, ...(Array.isArray(failure.errors) ? failure.errors : [])].map((item) =>
+    String((item as { code?: unknown } | null | undefined)?.code ?? ''),
+  )
+  const unreachable =
+    codes.some((code) => /^(ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ETIMEDOUT|EAI_AGAIN|P1001|P1002)$/.test(code)) ||
+    /ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|Can't reach database server/.test(message) ||
+    // assertMigrated could not even query the database (down, wrong host/port or credentials).
+    (failure.code === 'PRISMA_NOT_MIGRATED' && message.startsWith('Could not verify'))
+  const debugHint = 'BASALT_DEBUG=1 shows the stack trace.'
+  let explanation: string | undefined
+  if (failure.code === 'ENV_INVALID' && Array.isArray(failure.report)) {
+    const hasEnvFile = existsSync(envFile)
+    explanation = [
+      'The app cannot start — invalid environment variables:',
+      ...failure.report.map((line) => '  - ' + String(line)),
+      '',
+      "Read from: your shell's environment" +
+        (hasEnvFile ? ' and ' + envFile + ' (exported variables win).' : ' only — there is no ' + envFile + '.'),
+      'Fix: ' + (hasEnvFile ? 'set them in .env' : 'cp .env.example .env, then fill them in') + ' (or export them)' +
+        (existsSync(join(root, 'prisma')) ? ' — for DATABASE_URL, start PostgreSQL and point the URL at it' : '') +
+        '. \`pnpm basalt doctor\` checks the environment; ' + debugHint,
+    ].join('\\n')
+  } else if (unreachable || failure.code === 'PRISMA_NOT_MIGRATED') {
+    const database = await databaseInUse()
+    const where = 'Database: ' + database.target + ' (from ' + database.name + '; credentials never shown).'
+    explanation = unreachable
+      ? [
+          'The app cannot start — the database did not answer.',
+          where,
+          'Fix: start PostgreSQL (e.g. \`docker compose up -d\`, or your local service) and check that ' +
+            database.name + ' in .env points at it (host, port, user, password); on a new database, then run \`pnpm db:migrate\`. ' + debugHint,
+        ].join('\\n')
+      : [
+          'The app cannot start — the database is not migrated:',
+          '  ' + message,
+          where,
+          'Fix: run \`pnpm db:migrate\` (development; \`pnpm db:deploy\` in production) — or, if this is not the database you meant, check ' +
+            database.name + ' (a shell may have exported another project\\'s). ' + debugHint,
+        ].join('\\n')
+  }
+  if (explanation === undefined || process.env['BASALT_DEBUG'] === '1' || process.argv.includes('--debug')) throw error
+  console.error(explanation)
+  process.exit(1)
+}
+
+/** The database URL the app booted with — protocol, host, port and database only, never the credentials. */
+async function databaseInUse(): Promise<{ name: string; target: string }> {
+  let url: unknown
+  try {
+    url = ((await import('../src/env.js')).env as unknown as Record<string, unknown>)['DATABASE_URL']
+  } catch {
+    // env.ts itself failed: there is no URL to show.
+  }
+  // The variable it came from: the app-prefixed name first (it wins in src/env.ts).
+  const name =
+    Object.keys(process.env)
+      .filter((key) => key.endsWith('DATABASE_URL') && process.env[key] === url)
+      .sort((a, b) => b.length - a.length)[0] ?? 'DATABASE_URL'
+  try {
+    const parsed = new URL(String(url))
+    return { name, target: parsed.protocol + '//' + parsed.hostname + ':' + (parsed.port || '5432') + parsed.pathname }
+  } catch {
+    return { name, target: '(no valid URL)' }
+  }
+}
+`;
 /** Marker proving a bin/basalt.ts already delegates the project commands. */
 export const PROJECT_COMMANDS_MARKER = "['update', 'add', 'doctor', 'info'].includes(process.argv[2]";
+/** Marker proving a bin/basalt.ts already has the dev prelude (.env loading, `upgrade`, env errors). */
+export const DEV_PRELUDE_MARKER = 'process.loadEnvFile(envFile)';
+const APP_IMPORT = "await import('../src/app.js')";
+const APP_IMPORT_EXPLAINED = `${APP_IMPORT}.catch(explainBootFailure)`;
+const RUN_CLI = 'process.exit(await runCli({ app })';
 export function basaltBin() {
     return `#!/usr/bin/env node
 ${PRELUDE}
+${DEV_PRELUDE}
 // The dev tools are imported dynamically, after the project commands above.
 const { runCli } = await import('@basaltkit/cli')
 const { generatorCommands } = await import('@basaltkit/generator')
@@ -68,7 +179,7 @@ const { prismaSyncCommand } = await import('@basaltkit/prisma')
 // Dev tooling: opt into development defaults unless NODE_ENV is already set
 // (imported dynamically below so env.ts is evaluated after this line).
 process.env['NODE_ENV'] ??= 'development'
-const { buildApp } = await import('../src/app.js')
+const { buildApp } = ${APP_IMPORT_EXPLAINED}
 
 // The 'basalt' CLI: boots the app WITH the dev/CLI commands, runs one, shuts down.
 // The dev tools (@basaltkit/generator; add @basaltkit/ai for ai:*) are imported
@@ -83,7 +194,7 @@ const app = buildApp({
   logLevel: 'silent',
   commands: [...generatorCommands(), prismaSyncCommand()],
 })
-process.exit(await runCli({ app }))
+process.exit(await runCli({ app }).catch(explainBootFailure))
 `;
 }
 /**
@@ -100,17 +211,31 @@ export const LEGACY_BIN_HASHES = new Set([
     'sha256-d09d583f1a39bffcb72f302c5f6c3e2651badea358ba38019238a4aa4b842545',
     // 2026-09-19 (create-basalt ≤ 1.9): NODE_ENV defaulted before the app import.
     'sha256-a0df89dee04091a9470f67968ff72cfc3bf64076c1bf3d141ae657c7438a94c8',
+    // 2026-10-01 (create-basalt 1.10): project commands (update/add/doctor/info)
+    // delegated before boot — but no .env loading and `upgrade` booted the app.
+    'sha256-9091e137a5de39929d0e70b2fd973386b9cc1c2f996e130989a22c795b9d0893',
 ]);
 export const hasProjectCommands = (content) => content.includes(PROJECT_COMMANDS_MARKER);
+export const hasDevPrelude = (content) => content.includes(DEV_PRELUDE_MARKER);
 /**
- * Upgrades a template-generated bin/basalt.ts to delegate the project
- * commands: inserts the prelude after the shebang and turns the remaining
- * static imports into dynamic ones (so they no longer run before it).
- * Deterministic for the known templates — for the latest one the result is
- * exactly {@link basaltBin}.
+ * Upgrades a template-generated bin/basalt.ts to the current template, step by
+ * step: (1) without the project commands, inserts their prelude after the
+ * shebang and turns the remaining static imports into dynamic ones (so they no
+ * longer run before it); (2) without the dev prelude, inserts it right after
+ * the project commands and routes the app import through `explainBootFailure`.
+ * Deterministic for the known templates — for the latest ones (1.9, 1.10) the
+ * result is exactly {@link basaltBin}.
  */
 export function patchBasaltBin(content) {
-    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    let text = content.replace(/\r\n/g, '\n');
+    if (!hasProjectCommands(text))
+        text = addProjectCommands(text);
+    if (!hasDevPrelude(text))
+        text = addDevPrelude(text);
+    return text;
+}
+function addProjectCommands(content) {
+    const lines = content.split('\n');
     const shebang = lines[0]?.startsWith('#!') ? `${lines.shift()}\n` : '';
     const body = lines.map((line) => {
         const match = /^import \{ ([^}]+) \} from '([^']+)'$/.exec(line);
@@ -122,19 +247,45 @@ export function patchBasaltBin(content) {
     }
     return `${shebang}${PRELUDE}\n${body.join('\n')}`;
 }
-/** Where a bin/basalt.ts stands: already delegating, an untouched old template, or user code. */
+function addDevPrelude(content) {
+    const at = content.indexOf(PRELUDE);
+    // A file without the template's prelude block is not ours to rearrange.
+    if (at < 0)
+        return content;
+    const end = at + PRELUDE.length + (content.startsWith('\n', at + PRELUDE.length) ? 1 : 0);
+    const rest = content
+        .slice(end)
+        .replace(`= ${APP_IMPORT}\n`, `= ${APP_IMPORT_EXPLAINED}\n`)
+        .replace(`${RUN_CLI})\n`, `${RUN_CLI}.catch(explainBootFailure))\n`);
+    return `${content.slice(0, end)}${DEV_PRELUDE}\n${rest}`;
+}
+/** Where a bin/basalt.ts stands: already current, an untouched old template, or user code. */
 export function binStatus(content, manifestHash) {
     if (content === undefined)
         return 'absent';
-    if (hasProjectCommands(content))
+    if (hasProjectCommands(content) && hasDevPrelude(content))
         return 'current';
     const hash = hashContent(content);
     return LEGACY_BIN_HASHES.has(hash) || hash === manifestHash ? 'patchable' : 'modified';
 }
-/** What to paste by hand into a customised bin/basalt.ts. */
-export const MANUAL_BIN_SNIPPET = `Paste this right after the shebang line of bin/basalt.ts, then turn its
+/** What to paste by hand into a customised bin/basalt.ts (only the parts it lacks). */
+export function manualBinSnippet(content) {
+    const steps = [];
+    if (!hasProjectCommands(content)) {
+        steps.push(`Paste this right after the shebang line of bin/basalt.ts, then turn its
 static imports of @basaltkit/* and ../src/app.js into dynamic ones
 (\`import { runCli } from '@basaltkit/cli'\` → \`const { runCli } = await import('@basaltkit/cli')\`)
 so they no longer run before it:
 
-${PRELUDE}`;
+${PRELUDE}`);
+    }
+    if (!hasDevPrelude(content)) {
+        steps.push(`${steps.length > 0 ? 'Then paste' : 'Paste'} this after the project-commands block (before anything of the app is
+imported) — it runs \`upgrade\` without booting the app, loads .env for development
+and explains env errors — and change the app import to
+\`const { buildApp } = ${APP_IMPORT_EXPLAINED}\`:
+
+${DEV_PRELUDE}`);
+    }
+    return steps.join('\n');
+}

package/dist/cli.js

@@ -152,7 +152,8 @@ try {
     if (flags.prisma) {
         // Nothing boots before the database exists: env.DATABASE_URL is required and
         // the app asserts at boot that it reached the MIGRATED database.
-        steps.push(`cp .env.example .env   # then point ${envPrefix(result.options.name)}_DATABASE_URL at your database`);
+        // .env is already written with a local URL (pnpm dev / pnpm basalt load it).
+        steps.push(`# start PostgreSQL, or edit ${envPrefix(result.options.name)}_DATABASE_URL in .env`);
         steps.push(`${pm} run db:migrate${flags.tenancy ? '   # creates the tables and seeds the demo tenant' : '   # creates the tables'}`);
     }
     steps.push(`${pm} run dev${flags.ui ? '        # API on :3000' : ''}`);

package/dist/dev-entry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `src/dev.ts` (the `pnpm dev` entrypoint) and the `.env.example` header across
+ * create-basalt releases. Up to 1.10, nothing loaded `.env`: `pnpm dev` booted
+ * without the variables the example told you to set. `update` brings untouched
+ * copies to the current templates; customised ones get the snippet instead.
+ */
+/** Hashes of every src/dev.ts an earlier create-basalt release generated (CRLF-insensitive). */
+export declare const LEGACY_DEV_HASHES: ReadonlySet<string>;
+/** Marker proving a src/dev.ts already loads .env. */
+export declare const DEV_ENV_MARKER = "process.loadEnvFile(";
+export type DevEntryStatus = 'current' | 'patchable' | 'modified' | 'absent';
+/** Where a src/dev.ts stands: loads .env already, an untouched old template, or user code. */
+export declare function devEntryStatus(content: string | undefined, manifestHash?: string): DevEntryStatus;
+/** The current src/dev.ts — what a patchable one becomes. */
+export declare const patchDevEntry: () => string;
+/** What to paste by hand into a customised src/dev.ts. */
+export declare const MANUAL_DEV_SNIPPET = "Paste this at the top of src/dev.ts, BEFORE the server is imported (keep that\nimport dynamic \u2014 `await import('./server.js')` \u2014 so the variables are set first):\n\nimport { existsSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\n\n// Development loads .env (when present) like `node --env-file=.env`: a variable\n// already exported in your shell still wins, the file only fills in what is missing.\nconst envFile = fileURLToPath(new URL('../.env', import.meta.url))\nif (existsSync(envFile)) process.loadEnvFile(envFile)\n";
+/**
+ * `.env.example` with the old "nothing loads this file" lead swapped for the
+ * current one; undefined when the file does not start with the old lead (a
+ * newer or hand-written file is left alone — it is only comments).
+ */
+export declare function patchEnvExample(content: string): string | undefined;

package/dist/dev-entry.js

@@ -0,0 +1,49 @@
+import { hashContent } from './project/manifest.js';
+import { devTs, ENV_EXAMPLE_LEAD, LEGACY_ENV_EXAMPLE_LEAD } from './templates.js';
+/**
+ * `src/dev.ts` (the `pnpm dev` entrypoint) and the `.env.example` header across
+ * create-basalt releases. Up to 1.10, nothing loaded `.env`: `pnpm dev` booted
+ * without the variables the example told you to set. `update` brings untouched
+ * copies to the current templates; customised ones get the snippet instead.
+ */
+/** Hashes of every src/dev.ts an earlier create-basalt release generated (CRLF-insensitive). */
+export const LEGACY_DEV_HASHES = new Set([
+    // 2026-09-19 → create-basalt 1.10: NODE_ENV defaulted, no .env loading.
+    'sha256-f25f09fed1b36281a806e29f5aab139a1dda0c5fa898f7c4c71b6ac294326cb7',
+]);
+/** Marker proving a src/dev.ts already loads .env. */
+export const DEV_ENV_MARKER = 'process.loadEnvFile(';
+/** Where a src/dev.ts stands: loads .env already, an untouched old template, or user code. */
+export function devEntryStatus(content, manifestHash) {
+    if (content === undefined)
+        return 'absent';
+    if (content.includes(DEV_ENV_MARKER))
+        return 'current';
+    const hash = hashContent(content);
+    return LEGACY_DEV_HASHES.has(hash) || hash === manifestHash ? 'patchable' : 'modified';
+}
+/** The current src/dev.ts — what a patchable one becomes. */
+export const patchDevEntry = () => devTs();
+/** What to paste by hand into a customised src/dev.ts. */
+export const MANUAL_DEV_SNIPPET = `Paste this at the top of src/dev.ts, BEFORE the server is imported (keep that
+import dynamic — \`await import('./server.js')\` — so the variables are set first):
+
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// Development loads .env (when present) like \`node --env-file=.env\`: a variable
+// already exported in your shell still wins, the file only fills in what is missing.
+const envFile = fileURLToPath(new URL('../.env', import.meta.url))
+if (existsSync(envFile)) process.loadEnvFile(envFile)
+`;
+/**
+ * `.env.example` with the old "nothing loads this file" lead swapped for the
+ * current one; undefined when the file does not start with the old lead (a
+ * newer or hand-written file is left alone — it is only comments).
+ */
+export function patchEnvExample(content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith(`${LEGACY_ENV_EXAMPLE_LEAD}\n`))
+        return undefined;
+    return `${ENV_EXAMPLE_LEAD}${normalized.slice(LEGACY_ENV_EXAMPLE_LEAD.length)}`;
+}

package/dist/index.d.ts

@@ -68,6 +68,12 @@ export declare function resolveRunDefaults(input: {
 export declare function scaffoldFiles(options: ProjectOptions): Record<string, string>;
 /** Generates a ready-to-run Basalt app. Does not install dependencies. */
 export declare function createProject(input: CreateProjectInput): Promise<CreateProjectResult>;
+/**
+ * A random APP_SECRET for the development .env: 48 random bytes, base64url —
+ * redrawn in the (rare) case it happens to contain a word `secret()` rejects
+ * as a placeholder (`test`, `0000`, …).
+ */
+export declare function generateAppSecret(random?: (size: number) => Buffer): string;
 export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, resolveFileVersions, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, type FreshVersion, type HeldBackVersion, type ResolveLatestOptions, type VersionResolution, } from './latest-versions.js';
 export { runProjectCommand, PROJECT_COMMANDS, isProjectCommand, type ProjectCommandDeps } from './project/run.js';
 export { planUpdate, type UpdatePlan, type UpdateEntry } from './project/update.js';

package/dist/index.js

@@ -1,7 +1,9 @@
+import { randomBytes } from 'node:crypto';
 import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { appTest, appTs, dbTs, devTs, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, prismaConfigTs, prismaSchema, prismaSeedTs, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
+import { appTest, appTs, dbTs, devEnvFile, devTs, dockerignore, envExample, envTs, gitignore, mcpJson, basaltBin, packageJson, pnpmWorkspaceYaml, prismaConfigTs, prismaSchema, prismaSeedTs, readme, routesTs, serverTs, tsconfigJson, } from './templates.js';
 import { uiFiles } from './templates-ui.js';
+import { INSECURE_SECRET } from './project/doctor.js';
 import { createManifest, MANIFEST_PATH, serializeManifest } from './project/manifest.js';
 import { resolveFileVersions } from './latest-versions.js';
 export class TargetNotEmptyError extends Error {
@@ -85,13 +87,30 @@ export async function createProject(input) {
     const files = scaffoldFiles(options);
     const versions = input.resolveLatest ? await resolveFileVersions(files, input.registry) : undefined;
     files[MANIFEST_PATH] = serializeManifest(createManifest(options, files));
+    // A ready-to-use .env for development, so `pnpm dev` / `pnpm basalt` boot
+    // without a copy step. Written after the manifest on purpose: it is
+    // git-ignored local state (with a generated secret), not a template file.
+    files['.env'] = devEnvFile(options, generateAppSecret());
     for (const [path, content] of Object.entries(files)) {
         const target = join(dir, path);
         await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, content);
+        // .env holds a secret: owner-only, like `umask 077` would make it.
+        await writeFile(target, content, path === '.env' ? { mode: 0o600 } : undefined);
     }
     return { dir, files: Object.keys(files).sort(), options, ...(versions ? { versions } : {}) };
 }
+/**
+ * A random APP_SECRET for the development .env: 48 random bytes, base64url —
+ * redrawn in the (rare) case it happens to contain a word `secret()` rejects
+ * as a placeholder (`test`, `0000`, …).
+ */
+export function generateAppSecret(random = randomBytes) {
+    for (;;) {
+        const value = random(48).toString('base64url');
+        if (!INSECURE_SECRET.test(value))
+            return value;
+    }
+}
 export { THIRD_PARTY_VERSIONS, DEFAULT_REGISTRY, DEFAULT_MINIMUM_RELEASE_AGE_MINUTES, describeResolution, resolveFileVersions, minimumReleaseAgeMinutes, resolveLatestVersions, registryUrl, } from './latest-versions.js';
 export { runProjectCommand, PROJECT_COMMANDS, isProjectCommand } from './project/run.js';
 export { planUpdate } from './project/update.js';

package/dist/project/doctor.d.ts

@@ -23,6 +23,8 @@ export interface DoctorOptions {
     /** `<pm> --version` (injected; undefined when unavailable). */
     pmVersion?: string;
 }
+/** Mirrors the placeholder check of `secret()` in @basaltkit/env (src/secret.ts). */
+export declare const INSECURE_SECRET: RegExp;
 /** The Node range every @basaltkit package declares. */
 export declare const BASALT_NODE_RANGE = ">=22.5.0";
 /** Installed version of `name` as the app resolves it (top-level node_modules). */
@@ -31,6 +33,14 @@ export declare function installedVersion(dir: string, name: string): Promise<str
 export declare function parseDotenv(text: string): Record<string, string>;
 /** The env prefix src/env.ts passes to defineEnv (`prefix: 'X'` or `prefix: { value: 'X' … }`). */
 export declare function envPrefixOf(envTs: string | undefined, name: string): string | undefined;
+/**
+ * The variables src/env.ts requires: keys of the schema object passed to
+ * `defineEnv` whose declaration has no `.default(`, `.optional(`, `.catch(` or
+ * `.nullish(` (`secret()` is checked separately — it has a dev default).
+ * A light scan, not a parser: comments and strings are skipped, nesting is
+ * tracked. Undefined when there is no `defineEnv({ … })` to read.
+ */
+export declare function requiredEnvKeys(envTs: string | undefined): string[] | undefined;
 export declare function runDoctor(ctx: ProjectContext, options?: DoctorOptions): Promise<DoctorFinding[]>;
 export declare function renderFindings(findings: readonly DoctorFinding[], colors: Colors): string[];
 /** `create-basalt info`: a paste-able versions summary for bug reports. */

package/dist/project/doctor.js

@@ -3,13 +3,14 @@ import { readdir, readFile } from 'node:fs/promises';
 import { arch, platform } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { binStatus } from '../bin-template.js';
+import { devEntryStatus } from '../dev-entry.js';
 import { alwaysLatest, lookupLatestVersions } from '../latest-versions.js';
 import { envPrefix } from '../templates.js';
 import { allDependencies } from './context.js';
 import { ownVersion } from './manifest.js';
 import { compareVersions, parseSimpleRange, parseVersion, satisfies } from './semver.js';
 /** Mirrors the placeholder check of `secret()` in @basaltkit/env (src/secret.ts). */
-const INSECURE_SECRET = /change.?me|changeme|placeholder|example|secret|password|default|test|xxxx+|0000+/i;
+export const INSECURE_SECRET = /change.?me|changeme|placeholder|example|secret|password|default|test|xxxx+|0000+/i;
 /** The Node range every @basaltkit package declares. */
 export const BASALT_NODE_RANGE = '>=22.5.0';
 async function readJson(path) {
@@ -87,6 +88,72 @@ export function envPrefixOf(envTs, name) {
     const match = /prefix:\s*(?:\{\s*value:\s*)?['"]([A-Z0-9_]+)['"]/.exec(envTs);
     return match ? match[1] : /prefix:/.test(envTs) ? undefined : '';
 }
+/**
+ * The variables src/env.ts requires: keys of the schema object passed to
+ * `defineEnv` whose declaration has no `.default(`, `.optional(`, `.catch(` or
+ * `.nullish(` (`secret()` is checked separately — it has a dev default).
+ * A light scan, not a parser: comments and strings are skipped, nesting is
+ * tracked. Undefined when there is no `defineEnv({ … })` to read.
+ */
+export function requiredEnvKeys(envTs) {
+    if (envTs === undefined)
+        return undefined;
+    const call = envTs.indexOf('defineEnv(');
+    const open = call < 0 ? -1 : envTs.indexOf('{', call);
+    if (open < 0)
+        return undefined;
+    const entries = [];
+    let depth = 0;
+    let current;
+    for (let i = open; i < envTs.length; i++) {
+        const char = envTs[i];
+        if (char === '/' && envTs[i + 1] === '/') {
+            const end = envTs.indexOf('\n', i);
+            i = end < 0 ? envTs.length : end - 1;
+            continue;
+        }
+        if (char === '/' && envTs[i + 1] === '*') {
+            const end = envTs.indexOf('*/', i + 2);
+            i = end < 0 ? envTs.length : end + 1;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === '`') {
+            let end = i + 1;
+            while (end < envTs.length && envTs[end] !== char)
+                end += envTs[end] === '\\' ? 2 : 1;
+            if (current)
+                current.body += envTs.slice(i, end + 1);
+            i = end;
+            continue;
+        }
+        if (char === '{' || char === '(' || char === '[')
+            depth++;
+        else if (char === '}' || char === ')' || char === ']') {
+            depth--;
+            if (depth === 0)
+                break;
+        }
+        if (depth === 1 && (char === ',' || char === '{')) {
+            if (current)
+                entries.push(current);
+            current = undefined;
+            const start = skipTrivia(envTs, i + 1);
+            const match = /^([A-Z][A-Z0-9_]*)\s*:/.exec(envTs.slice(start, start + 200));
+            if (match) {
+                current = { key: match[1], body: '' };
+                i = start + match[0].length - 1;
+            }
+            continue;
+        }
+        if (current)
+            current.body += char;
+    }
+    if (current)
+        entries.push(current);
+    return entries
+        .filter(({ body }) => !/\.(default|optional|catch|nullish)\(|\bsecret\(/.test(body))
+        .map(({ key }) => key);
+}
 export async function runDoctor(ctx, options = {}) {
     const findings = [];
     const push = (level, area, message) => {
@@ -203,8 +270,10 @@ export async function runDoctor(ctx, options = {}) {
     const envTs = await readText(join(dir, 'src', 'env.ts'));
     const dotenvText = await readText(join(dir, '.env'));
     const dotenv = dotenvText ? parseDotenv(dotenvText) : {};
-    if (dotenvText === undefined && existsSync(join(dir, '.env.example'))) {
-        push('info', 'env', 'No .env — copy .env.example to .env (and start with --env-file=.env) or export the variables.');
+    const exampleText = await readText(join(dir, '.env.example'));
+    const example = exampleText ? parseDotenv(exampleText) : {};
+    if (dotenvText === undefined && exampleText !== undefined) {
+        push('warn', 'env', 'No .env — `dev` and `basalt` load it for development: `cp .env.example .env` (or export the variables).');
     }
     const prefix = envPrefixOf(envTs, ctx.options.name);
     const lookup = (name) => {
@@ -237,12 +306,25 @@ export async function runDoctor(ctx, options = {}) {
             push('ok', 'env', `${label} is set (${secret.from}, ${secret.value.length} characters).`);
         }
     }
-    if (ctx.options.prisma) {
-        const url = lookup('DATABASE_URL');
-        if (!url)
-            push('warn', 'env', `${prefix ? `${prefix}_` : ''}DATABASE_URL is not set — the app does not boot without it.`);
-        else
-            push('ok', 'env', `${prefix ? `${prefix}_` : ''}DATABASE_URL is set (${url.from}).`);
+    // Required variables: declared in src/env.ts without a default (from the
+    // environment or .env, the way the dev entrypoints load it). Without a
+    // readable schema, a Prisma app still needs DATABASE_URL.
+    const required = requiredEnvKeys(envTs) ?? (ctx.options.prisma ? ['DATABASE_URL'] : []);
+    for (const name of required) {
+        const label = prefix ? `${prefix}_${name}` : name;
+        const found = lookup(name);
+        if (found) {
+            push('ok', 'env', `${label} is set (${found.from}).`);
+            continue;
+        }
+        const inExample = [label, name].some((key) => example[key] !== undefined && example[key] !== '');
+        const fix = dotenvText === undefined
+            ? exampleText !== undefined
+                ? `\`cp .env.example .env\`${inExample ? '' : ` and set ${label} in it`}`
+                : `create .env with ${label}=…`
+            : `set ${label} in .env${inExample ? ' (.env.example has an example value)' : ''}`;
+        const database = name === 'DATABASE_URL' && ctx.options.prisma ? ' — and start PostgreSQL where it points' : '';
+        push('error', 'env', `${label} is not set (environment or .env) — the app does not boot without it. Fix: ${fix}, or export it${database}.`);
     }
     // --- Prisma -------------------------------------------------------------------
     const schemaPath = join(dir, 'prisma', 'schema.prisma');
@@ -293,10 +375,18 @@ export async function runDoctor(ctx, options = {}) {
     // --- Project tooling -------------------------------------------------------------
     const bin = await readText(join(dir, 'bin', 'basalt.ts'));
     const status = binStatus(bin, ctx.manifest?.files['bin/basalt.ts']);
-    if (status === 'patchable')
-        push('warn', 'tooling', 'bin/basalt.ts predates the project commands — `npx create-basalt@latest update` patches it.');
-    if (status === 'modified')
-        push('info', 'tooling', 'bin/basalt.ts is customised and does not delegate update/add/doctor/info — see `create-basalt update` for the snippet.');
+    if (status === 'patchable') {
+        push('warn', 'tooling', 'bin/basalt.ts is an older template (no .env loading / pre-boot project commands) — `npx create-basalt@latest update` patches it.');
+    }
+    if (status === 'modified') {
+        push('info', 'tooling', 'bin/basalt.ts is customised and lacks the current preludes (project commands, .env loading, pre-boot `upgrade`) — see `create-basalt update` for the snippet.');
+    }
+    const dev = await readText(join(dir, 'src', 'dev.ts'));
+    const devStatus = devEntryStatus(dev, ctx.manifest?.files['src/dev.ts']);
+    if (devStatus === 'patchable')
+        push('warn', 'tooling', 'src/dev.ts does not load .env (older template) — `npx create-basalt@latest update` patches it.');
+    if (devStatus === 'modified')
+        push('info', 'tooling', 'src/dev.ts is customised and does not load .env — see `create-basalt update` for the snippet.');
     if (!ctx.manifest)
         push('info', 'tooling', 'No .basalt/project.json (scaffolded before create-basalt 1.10) — features are inferred from package.json.');
     return findings;
@@ -348,3 +438,23 @@ export async function projectInfo(ctx, options = {}) {
     }
     return lines;
 }
+/** Index of the first character at or after `from` that is not whitespace or a comment (linear scan). */
+function skipTrivia(source, from) {
+    let i = from;
+    while (i < source.length) {
+        const char = source[i];
+        if (char === ' ' || char === '\t' || char === '\n' || char === '\r')
+            i++;
+        else if (source.startsWith('//', i)) {
+            const end = source.indexOf('\n', i);
+            i = end === -1 ? source.length : end + 1;
+        }
+        else if (source.startsWith('/*', i)) {
+            const end = source.indexOf('*/', i + 2);
+            i = end === -1 ? source.length : end + 2;
+        }
+        else
+            break;
+    }
+    return i;
+}

package/dist/project/run.js

@@ -47,7 +47,9 @@ present) to their latest published versions, with the scaffold's policy:
 Range style (^, ~, exact) and package.json formatting are preserved. Then it
 installs, runs the @basaltkit/cli upgrade codemods, and suggests typecheck+test.
 It also upgrades project tooling: an unmodified old bin/basalt.ts gains the
-project commands; create-basalt becomes a devDependency (pnpm basalt update).
+project commands, .env loading for development and a pre-boot \`upgrade\`; an
+unmodified src/dev.ts loads .env; the .env.example header is refreshed;
+create-basalt becomes a devDependency (pnpm basalt update).
 
 Options:
   --dry           Show the plan, write nothing
@@ -56,7 +58,8 @@ Options:
   --only=@basaltkit
                   Only the framework packages (and create-basalt)
   --no-install    Write package.json, skip the install (and the codemods)
-  --no-tooling    Leave bin/basalt.ts and the create-basalt devDependency alone
+  --no-tooling    Leave bin/basalt.ts, src/dev.ts, .env.example and the
+                  create-basalt devDependency alone
 ${COMMON_FLAGS}
 `,
     add: `Usage: create-basalt add <feature> [options]   (in an app: pnpm basalt add <feature>)
@@ -85,8 +88,9 @@ ${COMMON_FLAGS}
 
 Read-only health check: Node vs engines, package manager and lockfiles,
 installed vs declared versions, duplicated @basaltkit versions and unmet peer
-ranges, framework packages behind latest, the auth secret and DATABASE_URL
-(from the environment or .env), Prisma client/migrations, .mcp.json.
+ranges, framework packages behind latest, the required variables of src/env.ts
+and the auth secret (from the environment or .env), Prisma client/migrations,
+.mcp.json, and whether bin/basalt.ts / src/dev.ts are current.
 Exits 1 when an error is found; warnings alone exit 0.
 
 Options:

package/dist/project/update.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { binStatus, MANUAL_BIN_SNIPPET, patchBasaltBin } from '../bin-template.js';
+import { binStatus, hasProjectCommands, manualBinSnippet, patchBasaltBin } from '../bin-template.js';
+import { devEntryStatus, MANUAL_DEV_SNIPPET, patchDevEntry, patchEnvExample } from '../dev-entry.js';
 import { alwaysLatest, lookupLatestVersions, minimumReleaseAgeMinutes, } from '../latest-versions.js';
 import { BASALT_PROJECT_SCRIPT } from '../templates.js';
 import { extendManifest, MANIFEST_PATH, serializeManifest } from './manifest.js';
@@ -194,22 +195,44 @@ export async function planUpdate(ctx, options = {}) {
                 }
             }
         }
-        // bin/basalt.ts from an earlier template: make it delegate the project commands.
+        // Template files from an earlier release: bring them to the current
+        // templates when untouched (known hash or the manifest's), else print the
+        // snippet. Patched files get their manifest hash refreshed.
+        const patched = {};
         const bin = await readOptional(join(ctx.dir, 'bin', 'basalt.ts'));
         const status = binStatus(bin, ctx.manifest?.files['bin/basalt.ts']);
         if (status === 'patchable' && bin !== undefined) {
             const after = patchBasaltBin(bin);
             files['bin/basalt.ts'] = { before: bin, after };
-            toolingNotes.push('bin/basalt.ts: unmodified template from an earlier release — gains update/add/doctor/info');
-            if (ctx.manifest) {
-                files[MANIFEST_PATH] = {
-                    before: serializeManifest(ctx.manifest),
-                    after: serializeManifest(extendManifest(ctx.manifest, ctx.options, { 'bin/basalt.ts': after })),
-                };
-            }
+            patched['bin/basalt.ts'] = after;
+            toolingNotes.push(`bin/basalt.ts: unmodified template from an earlier release — ${hasProjectCommands(bin) ? '' : 'gains update/add/doctor/info; '}loads .env for development, runs \`upgrade\` without booting the app, explains env errors`);
+        }
+        else if (status === 'modified' && bin !== undefined) {
+            manual.push(`bin/basalt.ts was customised, so it was not patched. To bring it up to date:\n${manualBinSnippet(bin)}`);
+        }
+        const dev = await readOptional(join(ctx.dir, 'src', 'dev.ts'));
+        const devStatus = devEntryStatus(dev, ctx.manifest?.files['src/dev.ts']);
+        if (devStatus === 'patchable' && dev !== undefined) {
+            const after = patchDevEntry();
+            files['src/dev.ts'] = { before: dev, after };
+            patched['src/dev.ts'] = after;
+            toolingNotes.push('src/dev.ts: unmodified template from an earlier release — `dev` loads .env (exported variables still win)');
+        }
+        else if (devStatus === 'modified') {
+            manual.push(`src/dev.ts was customised, so it was not patched. To load .env in development:\n${MANUAL_DEV_SNIPPET}`);
+        }
+        const example = await readOptional(join(ctx.dir, '.env.example'));
+        const exampleAfter = example === undefined ? undefined : patchEnvExample(example);
+        if (example !== undefined && exampleAfter !== undefined) {
+            files['.env.example'] = { before: example, after: exampleAfter };
+            patched['.env.example'] = exampleAfter;
+            toolingNotes.push('.env.example: header now says dev/CLI load .env automatically and `start` does not');
         }
-        else if (status === 'modified') {
-            manual.push(`bin/basalt.ts was customised, so it was not patched. To give it the project commands:\n${MANUAL_BIN_SNIPPET}`);
+        if (ctx.manifest && Object.keys(patched).length > 0) {
+            files[MANIFEST_PATH] = {
+                before: serializeManifest(ctx.manifest),
+                after: serializeManifest(extendManifest(ctx.manifest, ctx.options, patched)),
+            };
         }
     }
     // Peer ranges of the framework versions we end up on vs the app's resulting ranges.

package/dist/templates.d.ts

@@ -48,17 +48,33 @@ export declare function envTs(options: ProjectOptions): string;
  * (`DATABASE_URL`, …) other projects export too.
  */
 export declare function envPrefix(name: string): string;
+/**
+ * The opening lines of `.env.example`. Up to create-basalt 1.10 they read
+ * {@link LEGACY_ENV_EXAMPLE_LEAD} ("nothing loads this file"); `update`
+ * swaps that for this one in existing apps.
+ */
+export declare const ENV_EXAMPLE_LEAD = "# Development: copy this file to .env \u2014 `pnpm dev` and `pnpm basalt` load it\n# automatically (a new app already has one). `pnpm start` (production) does\n# NOT: there the variables come from the environment (or `node --env-file`).";
+export declare const LEGACY_ENV_EXAMPLE_LEAD = "# Nothing loads this file for you: copy it to .env and start with\n# `node --env-file=.env` / `tsx --env-file=.env`, or export the variables.";
 export declare function envExample(options: ProjectOptions): string;
+/**
+ * The `.env` a new app starts with (git-ignored, never in the manifest): the
+ * values of `.env.example` for local development plus — with auth — a freshly
+ * generated APP_SECRET, so `pnpm dev` works without a copy step.
+ */
+export declare function devEnvFile(options: ProjectOptions, appSecret: string): string;
 /** A PostgreSQL-safe database name derived from the project name. */
 export declare function databaseName(name: string): string;
 export declare function appTs(options: ProjectOptions): string;
 export declare function routesTs(options: ProjectOptions): string;
 export declare function serverTs(): string;
 /**
- * `pnpm dev` entrypoint. Opts into NODE_ENV=development (dev secret defaults,
- * pretty logs) unless NODE_ENV is already set, then starts the server. Kept out
- * of server.ts on purpose: `pnpm start` runs server.ts directly, where an unset
- * NODE_ENV counts as production and secrets are required (fail-closed).
+ * `pnpm dev` entrypoint. Loads `.env` (when present) with `node --env-file`
+ * semantics — an exported variable wins, the file only fills in what is
+ * missing — and opts into NODE_ENV=development (dev secret defaults, pretty
+ * logs) unless NODE_ENV is already set, then starts the server. Kept out of
+ * server.ts on purpose: `pnpm start` runs server.ts directly, where nothing
+ * loads `.env` (production configuration comes from the real environment) and
+ * an unset NODE_ENV counts as production, so secrets are required (fail-closed).
  */
 export declare function devTs(): string;
 /**

package/dist/templates.js

@@ -222,10 +222,19 @@ export function envPrefix(name) {
     base = base.slice(start, end);
     return base === '' || /^\d/.test(base) ? `APP_${base}` : base;
 }
+/**
+ * The opening lines of `.env.example`. Up to create-basalt 1.10 they read
+ * {@link LEGACY_ENV_EXAMPLE_LEAD} ("nothing loads this file"); `update`
+ * swaps that for this one in existing apps.
+ */
+export const ENV_EXAMPLE_LEAD = `# Development: copy this file to .env — \`pnpm dev\` and \`pnpm basalt\` load it
+# automatically (a new app already has one). \`pnpm start\` (production) does
+# NOT: there the variables come from the environment (or \`node --env-file\`).`;
+export const LEGACY_ENV_EXAMPLE_LEAD = `# Nothing loads this file for you: copy it to .env and start with
+# \`node --env-file=.env\` / \`tsx --env-file=.env\`, or export the variables.`;
 export function envExample(options) {
     const prefix = envPrefix(options.name);
-    return `# Nothing loads this file for you: copy it to .env and start with
-# \`node --env-file=.env\` / \`tsx --env-file=.env\`, or export the variables.
+    return `${ENV_EXAMPLE_LEAD}
 # --env-file NEVER overrides a variable already exported in your shell: if
 # another project exported PORT or DATABASE_URL, an app reading the generic
 # name would silently use THAT one. That is why src/env.ts reads app-prefixed
@@ -252,6 +261,20 @@ ${prefix}_DATABASE_URL=postgres://postgres:postgres@localhost:5432/${databaseNam
 # ${prefix}_DATABASE_URL=postgres://user:pass@localhost:5432/${options.name.replace(/^@[^/]+\//, '')}
 `}`;
 }
+/**
+ * The `.env` a new app starts with (git-ignored, never in the manifest): the
+ * values of `.env.example` for local development plus — with auth — a freshly
+ * generated APP_SECRET, so `pnpm dev` works without a copy step.
+ */
+export function devEnvFile(options, appSecret) {
+    const prefix = envPrefix(options.name);
+    const example = envExample(options);
+    const body = example.slice(example.indexOf(`${prefix}_PORT=`));
+    return `# Local development settings, generated by create-basalt from .env.example.
+# Git-ignored: never commit it. \`pnpm dev\` and \`pnpm basalt\` load it (a
+# variable exported in your shell wins); \`pnpm start\` (production) does not.
+${body.replace(`# ${prefix}_APP_SECRET=\n`, `${prefix}_APP_SECRET=${appSecret}\n`)}`;
+}
 /** A PostgreSQL-safe database name derived from the project name. */
 export function databaseName(name) {
     return name.replace(/^@[^/]+\//, '').replace(/[^a-zA-Z0-9]+/g, '_').toLowerCase();
@@ -526,14 +549,27 @@ for (const signal of ['SIGINT', 'SIGTERM'] as const) {
 `;
 }
 /**
- * `pnpm dev` entrypoint. Opts into NODE_ENV=development (dev secret defaults,
- * pretty logs) unless NODE_ENV is already set, then starts the server. Kept out
- * of server.ts on purpose: `pnpm start` runs server.ts directly, where an unset
- * NODE_ENV counts as production and secrets are required (fail-closed).
+ * `pnpm dev` entrypoint. Loads `.env` (when present) with `node --env-file`
+ * semantics — an exported variable wins, the file only fills in what is
+ * missing — and opts into NODE_ENV=development (dev secret defaults, pretty
+ * logs) unless NODE_ENV is already set, then starts the server. Kept out of
+ * server.ts on purpose: `pnpm start` runs server.ts directly, where nothing
+ * loads `.env` (production configuration comes from the real environment) and
+ * an unset NODE_ENV counts as production, so secrets are required (fail-closed).
  */
 export function devTs() {
     return `// Development entrypoint (\`pnpm dev\`). \`pnpm start\` runs server.ts directly,
 // where an unset NODE_ENV counts as production: secrets are then required.
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// Development loads .env (when present) like \`node --env-file=.env\`: a variable
+// already exported in your shell still wins, the file only fills in what is
+// missing. \`pnpm start\` (production) never loads it — there the configuration
+// comes from the real environment.
+const envFile = fileURLToPath(new URL('../.env', import.meta.url))
+if (existsSync(envFile)) process.loadEnvFile(envFile)
+
 process.env['NODE_ENV'] ??= 'development'
 await import('./server.js')
 `;
@@ -792,9 +828,9 @@ export function prismaConfigTs(options) {
     return `import { loadEnvFile } from 'node:process'
 import { defineConfig } from 'prisma/config'
 
-// Prisma loads no .env for you (neither does the app — see src/env.ts). This
-// mirrors \`node --env-file=.env\`: a variable already exported in your shell
-// still wins, the file only fills in what is missing.
+// Prisma loads no .env for you. Like the app's dev entrypoints (src/dev.ts,
+// bin/basalt.ts) this mirrors \`node --env-file=.env\`: a variable already
+// exported in your shell still wins, the file only fills in what is missing.
 try {
   loadEnvFile('.env')
 } catch {
@@ -947,7 +983,7 @@ Included: ${features.join(' · ')}.
 \`\`\`bash
 pnpm install${options.prisma
         ? `
-# point ${envPrefix(options.name)}_DATABASE_URL at a PostgreSQL database (.env.example), then
+# start PostgreSQL — .env points ${envPrefix(options.name)}_DATABASE_URL at localhost:5432 — then
 pnpm db:migrate # create the tables${options.tenancy ? ` (runs the seed too)` : ''}`
         : ''}
 pnpm dev        # API on http://localhost:3000
@@ -1005,16 +1041,18 @@ scaffold with \`--cli\` — \`pnpm basalt prisma:sync\` does the merge for you.)
         : ''}
 ## Environment
 
-\`src/env.ts\` validates \`process.env\` — nothing loads \`.env\` for you. Copy
-\`.env.example\` to \`.env\` and launch with \`--env-file=.env\` (Node/tsx), or
-export the variables.
+\`src/env.ts\` validates \`process.env\`. For development, ${options.cli ? '`pnpm dev` and `pnpm basalt` load' : '`pnpm dev` loads'} \`.env\`
+automatically — create-basalt wrote one for you: git-ignored, with local
+values${options.auth ? ' and a generated secret' : ''}. \`.env.example\` is its committed template.
+\`pnpm start\` (production, \`src/server.ts\`) loads **nothing**: there the
+variables come from the real environment (or \`node --env-file=.env\`).
 
 The variables are **app-prefixed**: \`${envPrefix(options.name)}_PORT\`,
 \`${envPrefix(options.name)}_HOST\`, \`${envPrefix(options.name)}_LOG_LEVEL\`${options.auth ? `, \`${envPrefix(options.name)}_APP_SECRET\`` : ''}${options.prisma ? `, \`${envPrefix(options.name)}_DATABASE_URL\`` : ''}. \`NODE_ENV\` is never prefixed.
 
-Why: **\`--env-file\` never overrides a variable that is already exported.** In a
-shell where another project exported \`DATABASE_URL\` (or \`PORT\`), an app reading
-the generic name boots against THAT value and only fails on the first request
+Why: **loading \`.env\` (like \`--env-file\`) never overrides a variable that is
+already exported.** In a shell where another project exported \`DATABASE_URL\`
+(or \`PORT\`), an app reading the generic name boots against THAT value and only fails on the first request
 that touches it. \`src/env.ts\` therefore passes \`prefix: '${envPrefix(options.name)}'\` to
 \`defineEnv\`: each variable is read as \`${envPrefix(options.name)}_<NAME>\` first and
 **falls back** to the bare \`<NAME>\`, so a deployment that already exports the

package/dist/versions.js

@@ -25,5 +25,5 @@ export const SCAFFOLD_VERSIONS = {
     '@basaltkit/tenancy': '^3.1.0',
     '@basaltkit/tenancy-prisma': '^2.0.0',
     '@basaltkit/testing': '^2.0.0',
-    'create-basalt': '^1.10.0',
+    'create-basalt': '^1.11.0',
 };

package/dist/wizard.js

@@ -11,9 +11,9 @@ export const FEATURES = [
 ];
 export const PRESETS = [
     { value: 'saas', label: 'SaaS starter', hint: 'tenancy + auth + billing + database + CLI', features: ['tenancy', 'auth', 'billing', 'prisma', 'cli'] },
-    { value: 'api', label: 'API only', hint: 'auth + MCP, no tenancy or UI', features: ['auth', 'mcp'] },
+    { value: 'api', label: 'API only', hint: 'auth + MCP + CLI, no tenancy or UI', features: ['auth', 'mcp', 'cli'] },
     { value: 'full', label: 'Full stack', hint: 'everything + web UI', features: ['tenancy', 'auth', 'billing', 'prisma', 'ui', 'cli', 'mcp'] },
-    { value: 'minimal', label: 'Minimal', hint: 'no batteries, add them later', features: [] },
+    { value: 'minimal', label: 'Minimal', hint: 'just the CLI, add the rest later', features: ['cli'] },
     { value: 'custom', label: 'Custom', hint: 'pick features yourself', features: null },
 ];
 const PACKAGE_MANAGERS = [
@@ -59,7 +59,7 @@ export async function runWizard(prompter, options = {}) {
         (await prompter.multiselect({
             message: 'Select features',
             choices: FEATURES,
-            initial: ['tenancy', 'auth'],
+            initial: ['tenancy', 'auth', 'cli'],
         })));
     let pm = await prompter.select({
         message: 'Package manager',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -30,26 +30,26 @@
     "typescript": "^7.0.2",
     "vitest": "^5.0.1",
     "zod": "^4.6.5",
+    "@basaltkit/auth": "^4.1.0",
+    "@basaltkit/auth-prisma": "^2.0.0",
+    "@basaltkit/config": "^1.1.2",
+    "@basaltkit/cli": "^1.3.0",
     "@basaltkit/core": "^1.5.0",
-    "@basaltkit/events": "^1.3.0",
     "@basaltkit/env": "^3.1.1",
+    "@basaltkit/events": "^1.3.0",
     "@basaltkit/fastify": "^2.5.0",
-    "@basaltkit/auth": "^4.1.0",
-    "@basaltkit/auth-prisma": "^2.0.0",
+    "@basaltkit/generator": "^1.5.0",
     "@basaltkit/logger": "^1.3.0",
     "@basaltkit/mcp": "^5.0.0",
     "@basaltkit/prisma": "^3.0.0",
+    "@basaltkit/subscriptions": "^5.0.0",
     "@basaltkit/subscriptions-prisma": "^3.0.0",
     "@basaltkit/teams": "^4.0.0",
-    "@basaltkit/generator": "^1.5.0",
-    "@basaltkit/cli": "^1.3.0",
-    "@basaltkit/tenancy": "^3.1.0",
     "@basaltkit/teams-prisma": "^1.1.0",
-    "@basaltkit/tenancy-prisma": "^2.0.0",
-    "@basaltkit/testing": "^2.0.3",
-    "@basaltkit/subscriptions": "^5.0.0",
+    "@basaltkit/tenancy": "^3.1.0",
     "@basaltkit/tsconfig": "^0.24.0",
-    "@basaltkit/config": "^1.1.2"
+    "@basaltkit/testing": "^2.0.3",
+    "@basaltkit/tenancy-prisma": "^2.0.0"
   },
   "publishConfig": {
     "access": "public"