create-basalt 1.9.0 → 1.11.0

package/README.md

@@ -16,6 +16,8 @@ Starting a backend project from scratch involves dozens of decisions and files b
 
 It works in two ways: interactive mode (answers questions in the terminal) or direct mode with flags (ideal for scripts). It doesn't install dependencies or touch git unless you ask it to (`--install`, `--git`).
 
+It also stays useful **after** the project exists: `create-basalt update` moves an app to the latest dependency versions, `create-basalt add ui|cli|mcp` adds a feature you didn't pick at creation time, and `create-basalt doctor` / `info` check the project — see [Project commands](#project-commands-update-add-doctor-info). In a scaffolded app they are simply `pnpm basalt update`, `pnpm basalt add ui`, …
+
 ## Installation
 
 You don't need to install anything — your package manager's `create` command downloads and runs the package on the spot:
@@ -84,13 +86,14 @@ Usage: npm create basalt <name> [options]
 
 | Flag | Default | What it does |
 | --- | --- | --- |
-| `<name>` | — (asked in interactive mode) | Project name (and folder name, unless `--dir`) |
+| `<name>` | — (asked in interactive mode) | Project name (and folder name, unless `--dir`). `update`, `add`, `doctor` and `info` are reserved for the [project commands](#project-commands-update-add-doctor-info) |
+| `--name=<name>` | — | Project name as a flag — the way to create a project literally called `update`/`add`/`doctor`/`info` |
 | `--dir=<path>` | `./<name>` | Destination folder |
 | `--no-tenancy` | tenancy **on** | Removes multi-tenancy (`@basaltkit/tenancy`) |
 | `--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) |
@@ -117,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
@@ -135,28 +138,31 @@ Always:
 
 ```
 my-app/
-├── package.json          # scripts: dev, start, test, typecheck (+ basalt with --cli)
+├── 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/* release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
+├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* + create-basalt release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
 ├── src/
 │   ├── 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. With `--cli`, adds `bin/basalt.ts` and the `"basalt": "tsx bin/basalt.ts"` script. 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
 
 ```bash
 pnpm install
-pnpm dev                              # terminal 1 — API on :3000
-pnpm --filter my-app-web dev       # terminal 2 — UI at http://localhost:5180
+pnpm dev        # terminal 1 — API on :3000
+pnpm dev:web    # terminal 2 — UI at http://localhost:5180 (= pnpm --filter my-app-web dev)
 ```
 
 Vite's dev server proxies `/api` to the API — there's no CORS to configure.
@@ -181,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
 ```
@@ -197,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
@@ -209,6 +215,138 @@ pnpm basalt make:resource Project   # generates schema → repository → servic
 
 With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies (`verifyDepsBeforeRun`, default `install`) and runs `pnpm install` when any workspace project is out of sync — so `pnpm basalt …` can need the network. `node_modules/.bin/tsx bin/basalt.ts …` skips that check; `verifyDepsBeforeRun: warn` (commented out in the generated `pnpm-workspace.yaml`) turns it into a warning for the whole project.
 
+## Project commands: update, add, doctor, info
+
+Run inside an existing Basalt app — any app, created with or without the CLI (`--no-cli`),
+by any create-basalt release:
+
+```bash
+npx create-basalt@latest update        # or, in a scaffolded app: pnpm basalt update
+npx create-basalt@latest add ui        # pnpm basalt add ui
+npx create-basalt@latest doctor        # pnpm basalt doctor
+npx create-basalt@latest info          # pnpm basalt info
+```
+
+The first positional argument picks the mode: `update`, `add`, `doctor` and
+`info` are project commands; anything else is a new project's name (use
+`--name=update` to create a project with one of those names). Outside a Basalt
+app (no `package.json`, or no `@basaltkit/*` dependency) they stop with an
+actionable error. Every command has `--help`; `--cwd=<dir>` targets another
+directory, `--pm=` overrides the detected package manager (`packageManager`
+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. 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` /
+`bunx` / `npx create-basalt@latest` when it isn't installed.
+
+### Updating an app
+
+```bash
+pnpm basalt update --dry      # the table, nothing written
+pnpm basalt update            # asks, writes, installs, runs the codemods
+```
+
+| Flag | What it does |
+| --- | --- |
+| `--dry` | Prints the plan; writes nothing |
+| `-y`, `--yes` | Applies without asking (required when stdin is not a terminal) |
+| `--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`, `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
+link to its CHANGELOG and to the upgrade notes; third-party packages go to the
+newest release **on the app's current major** (a newer major is listed as
+"kept … pass --major"); a version younger than the release-age window (pnpm
+`minimumReleaseAge`, read from the project's `pnpm-workspace.yaml` when set) is
+left for later so the install cannot refuse it. When a framework release
+declares a peer range the app would not meet (say `zod ^5` while zod is held on
+4), the plan warns before anything is written.
+
+Both `package.json` and `web/package.json` are updated, **in place**: only the
+version strings change — order, indentation and range style (`^`, `~`, exact)
+are kept, and ranges `update` does not manage (`workspace:`, tags, git, `>=`) are
+left alone. The lockfile is never edited by hand: the detected package manager
+installs, then the installed `@basaltkit/cli` upgrade codemods run (no app
+boot), then it suggests `pnpm typecheck && pnpm test`. If the install fails the
+edits stay and the command says how to revert (`git checkout -- package.json …`).
+`--offline` is refused: update needs the registry.
+
+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`); 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
+
+```bash
+pnpm basalt add ui --dry       # what would be created/merged/skipped
+pnpm basalt add ui             # web/ exactly as --ui scaffolds it
+pnpm basalt add cli            # bin/basalt.ts + @basaltkit/cli, generator, prisma
+pnpm basalt add mcp            # @basaltkit/mcp at POST /mcp + the dev-only ai-mcp bridge + .mcp.json
+```
+
+`add` adapts the templates to the project as it is now (name, auth/tenancy from
+its dependencies) and plans every change before applying any:
+
+- **Existing files are never overwritten** — skipped with a notice; `--force`
+  overwrites generated files.
+- **Merged, not replaced:** `package.json` (new dependencies in sorted
+  position, scripts such as `dev:web`; an existing entry is never changed),
+  `pnpm-workspace.yaml` (`web` added to `packages:`), `.gitignore`, `README.md`.
+- **Your code** (`src/app.ts`, `src/routes.ts`) is regenerated only when
+  `.basalt/project.json` proves it untouched, patched where the template's
+  anchors are still unambiguous (works with `fastifyPlugin`, `expressPlugin` or
+  `honoPlugin`), and otherwise left alone with the exact manual steps printed.
+- `add ui` needs a pnpm project (`web/` is a pnpm workspace member) and touches
+  no API code: the Vite dev server proxies `/api`, so there is no CORS to set up.
+- Dependencies are installed afterwards unless `--no-install`; `--offline` uses
+  the ranges bundled with this create-basalt instead of the registry.
+
+A project created without `--ui` followed by `add ui` ends up with the same
+files as one created with `--ui` (the test suite checks exactly that).
+
+### doctor and info
+
+`doctor` is read-only and exits non-zero only on errors (warnings exit 0). It
+checks Node against `engines` and Basalt's `>=22.5.0`; the package manager and
+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()`); 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` 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
+bug reports.
+
+### The scaffold manifest
+
+`.basalt/project.json` records the create-basalt version, the options and a
+`sha256` of every file the scaffold wrote (`package.json` excluded — installs
+rewrite it). Commit it: it is how `add` and `update` tell an untouched template
+file from one you edited. Projects created before it existed are handled too —
+features are inferred from `package.json` and the tree, and every file counts as
+yours; the first `add` creates the manifest.
+
 ### `pnpm-workspace.yaml` and pnpm 11
 
 - `minimumReleaseAgeExclude` is evaluated **first-match-wins by package name**. To exclude several versions of one package, write ONE entry with a union — `'@types/node@22.20.4 || 26.6.2'` — never two `@types/node@…` entries (only the first would apply). The generated file carries this example as a comment.
@@ -216,7 +354,9 @@ With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies
 
 ### 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.
 
@@ -237,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)
@@ -289,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' }`) |
 
@@ -299,6 +441,17 @@ Throws `TargetNotEmptyError` if the destination folder exists and isn't empty.
 
 Detects the manager that invoked the command from `npm_config_user_agent` (or the string passed in). Returns `'pnpm' | 'yarn' | 'bun'` when recognized; otherwise `'npm'`.
 
+### Project commands (programmatic)
+
+| Export | What it does |
+| --- | --- |
+| `runProjectCommand(argv, deps)` | Runs `update`/`add`/`doctor`/`info` and returns the exit code; every side effect (output, prompts, package-manager runs, registry fetch, codemods) is injected through `deps` |
+| `loadProject(dir, pm?)` | Reads an app: package.json (+ `web/`), manifest, detected features and package manager. Throws `NotABasaltAppError` |
+| `planUpdate(ctx, { major?, only?, tooling?, registry? })` | The update plan — entries, the full before/after of every file, tooling, warnings, framework majors. Writes nothing |
+| `planAdd(ctx, feature, { force?, resolveLatest?, registry? })` | The add plan — created/merged/skipped files and manual steps. Writes nothing |
+| `runDoctor(ctx, options)` | Doctor findings (`{ level: 'ok' \| 'info' \| 'warn' \| 'error', area, message }`) |
+| `MANIFEST_PATH`, `readManifest(dir)`, `hashContent(text)` | The scaffold manifest |
+
 ### `TargetNotEmptyError`
 
 Error (extends `Error`) with the message `Target directory "<dir>" already exists and is not empty.`
@@ -329,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`.
+
+**`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`.**
+**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
@@ -346,13 +502,28 @@ 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`.
 
-**I want to change my mind after generating (e.g. add billing).**
-There's no "re-scaffold" command. Either generate a new project with the right flags and compare, or add it by hand: install `@basaltkit/subscriptions` and add the `subscriptionsPlugin` to `src/app.ts` (the generated README and the templates serve as reference).
+**I want to change my mind after generating (e.g. add the frontend).**
+`pnpm basalt add ui` (or `npx create-basalt@latest add ui`) — likewise `cli` and `mcp`; see [Adding features later](#adding-features-later). Billing, tenancy and auth are not `add`-able (they reshape `src/app.ts` and the schema): install `@basaltkit/subscriptions` and add the `subscriptionsPlugin` to `src/app.ts` by hand (the generated README and the templates serve as reference).
+
+**`npm create basalt update` did not create a project called "update".**
+`update`, `add`, `doctor` and `info` are project commands. Use `npm create basalt -- --name=update`.
+
+**`update cannot run with --offline` / `Could not reach https://registry.npmjs.org for any package`.**
+`update` resolves versions from the registry. Drop `--offline`, check the connection, or point `npm_config_registry` at your mirror.
+
+**`Not a terminal — nothing written. Re-run with --yes`.**
+`update` and `add` only apply after a confirmation; in CI or a pipe, pass `--yes`.
+
+**`pnpm basalt update` says `Unknown command "update"`.**
+The app's `bin/basalt.ts` predates the project commands. Run `npx create-basalt@latest update` once — it patches an unmodified `bin/basalt.ts` (or prints the snippet for a customised one).
 
 ## How it connects to other modules
 
@@ -363,6 +534,6 @@ There's no "re-scaffold" command. Either generate a new project with the right f
 - **`@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.
+- **`@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  --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";
+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

@@ -2,12 +2,15 @@ import { stdout } from 'node:process';
 export const USAGE = `Usage: npm create basalt <name> [options]
 
 Options:
+  --name=<name>   Project name (the way to create a project named like a
+                  project command: update, add, doctor, info)
   --dir=<path>    Target directory (default: ./<name>)
   --no-tenancy    Skip multi-tenancy
   --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
@@ -25,6 +28,13 @@ Options:
   -h, --help      Show this help
 
 Run with no name in a terminal to be prompted interactively.
+
+Project commands — inside an existing app (in a scaffolded app: pnpm basalt <command>):
+  create-basalt update            Update dependencies to the latest versions (--dry, --major, …)
+  create-basalt add <feature>     Add ui | cli | mcp to the app
+  create-basalt doctor            Check the project's health
+  create-basalt info              Versions summary for bug reports
+  create-basalt <command> --help  Options of one command
 `;
 export function parseArgs(argv) {
     const flags = {
@@ -32,7 +42,7 @@ export function parseArgs(argv) {
         auth: true,
         billing: false,
         ui: false,
-        cli: false,
+        cli: true,
         mcp: false,
         prisma: false,
         yes: false,
@@ -49,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
@@ -69,6 +81,8 @@ export function parseArgs(argv) {
             flags.offline = true;
         else if (token.startsWith('--dir='))
             flags.dir = token.slice('--dir='.length);
+        else if (token.startsWith('--name='))
+            flags.name = token.slice('--name='.length);
         else if (token.startsWith('--pm='))
             flags.pm = token.slice('--pm='.length);
         else if (token === '--help' || token === '-h') {

package/dist/bin-template.d.ts

@@ -0,0 +1,28 @@
+/** 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
+ * (CRLF-insensitive). Only these — or a file the project's manifest records as
+ * untouched — are patched automatically.
+ */
+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 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 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 (only the parts it lacks). */
+export declare function manualBinSnippet(content: string): string;