@rebasepro/cli 0.17.3 → 0.18.1

package/dist/utils/project.d.ts

@@ -78,6 +78,72 @@ export declare function resolveTsx(projectRoot: string): string | null;
  * error description string when it appears corrupted.
  */
 export declare function validateTsxInstallation(tsxBinPath: string): string | null;
+/**
+ * The one sentence a command says when the project's dependencies are missing.
+ *
+ * Six commands each had their own wording for the same state, and none of them
+ * named the remedy:
+ *
+ *   ✗ Could not find CLI entry point for @rebasepro/server-postgres.
+ *   ✗ Could not find tsx binary.
+ *   ✗ Could not find tsx binary for backend.
+ *
+ * All three mean "you have not installed yet" — `getActiveBackendPlugin` has
+ * already read the driver out of `backend/package.json` by the time the first
+ * one fires, so the package is declared and simply not on disk, and `tsx` is a
+ * devDependency of every scaffold. But they read as *Rebase* being broken, and
+ * they name an internal path or a binary the developer never asked for rather
+ * than the command that fixes it. That is the whole of the failure someone sees
+ * on a fresh clone, where `node_modules/` is the one thing a checkout does not
+ * carry.
+ *
+ * So: one sentence, naming the package manager this project uses and the
+ * directory to run it in — the working directory is usually neither.
+ */
+export declare function dependenciesNotInstalled(projectRoot: string): string;
+/**
+ * Print {@link dependenciesNotInstalled} and exit 1.
+ *
+ * For the five commands that report and stop. `db.ts` throws instead, because
+ * its caller adds the `✗` and the exit itself.
+ */
+export declare function exitDependenciesNotInstalled(projectRoot: string): never;
+/** One problem inside a refusal, when the command found several. */
+export interface JsonFailureIssue {
+    /** Where it is — a config path, a manifest key, a file. */
+    path?: string;
+    message: string;
+}
+/**
+ * The refusal envelope, for a caller that asked for JSON.
+ *
+ * Same shape as the cloud family's `fail()` — `{ error: { message, code, hint } }`
+ * — because there is one CLI and a caller should not have to know which half of
+ * it answered. `code` is what a caller branches on and is never absent; the
+ * cloud family's reasoning about that applies here unchanged. `issues` carries
+ * the per-problem detail a human reader gets as a bullet list, because a
+ * refusal that says "2 problem(s)" and does not say which two is not
+ * machine-readable in any useful sense.
+ *
+ * On **stdout**, like every other `--json` result: the contract those commands
+ * make is that stdout holds one JSON value, and a caller that pipes stdout to a
+ * parser must get a parseable refusal rather than an empty stream and a
+ * human sentence it never sees. That contract used to hold for exactly one
+ * failure of each command — the one that goes through `requireProjectRoot` —
+ * while every other exit of the *same* command wrote human text to stderr and
+ * left stdout empty. So `rebase status --json` was parseable outside a project
+ * and unparseable inside a broken one, which is the case a caller actually has
+ * to handle.
+ *
+ * The flag is read off `process.argv` because the failure happens inside a
+ * helper the command calls before it has parsed anything. Coarse — a literal
+ * `--json` as some other flag's value would count — and worth it: the failure
+ * mode of being coarse is a JSON error where a human one was wanted, and the
+ * failure mode of not doing it is an unparseable stream.
+ */
+export declare function failAsJson(message: string, code: string, hint?: string, issues?: JsonFailureIssue[]): never;
+/** Did the command line ask for machine-readable output? */
+export declare function wantsJsonOutput(argv?: readonly string[]): boolean;
 /**
  * Require the project root or exit with a helpful error.
  */

package/dist/utils/spawn-error.d.ts

@@ -0,0 +1 @@
+export declare function reportSpawnFailure(error: unknown): void;

package/dist/utils/unknown-command.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one command the user probably meant, or nothing.
+ *
+ * Tight on purpose. A suggestion that is wrong is worse than none: it sends
+ * someone to read the help for a command that was never the answer, and on a
+ * family like `db` — where `push` and `pull` are one edit apart — a loose
+ * threshold would confidently propose the destructive neighbour of what they
+ * typed. So: one edit for a short word, two for a long one, and a prefix match
+ * always counts (`rebase cloud dep` for `deploy`).
+ */
+export declare function suggestCommand(typed: string, known: readonly string[]): string | undefined;
+/**
+ * The line itself, without printing it — so callers that must answer in JSON
+ * (the cloud family, whose `fail()` writes a machine-readable envelope) use the
+ * same words as the ones that print.
+ *
+ * `family` is empty for the top level: `rebase --help`, not `rebase  --help`.
+ */
+export declare function unknownCommandMessage(typed: string | undefined, known: readonly string[], family?: string): string;
+/**
+ * Print the line to stderr and exit 1.
+ *
+ * stderr, not stdout: a mistyped command is a failure, and the families with a
+ * `--json` mode guarantee that stdout holds only their envelope.
+ */
+export declare function unknownCommand(typed: string | undefined, known: readonly string[], family?: string): never;

package/dist/utils/version.d.ts

@@ -0,0 +1,10 @@
+/** The CLI's version, or `"unknown"` when it cannot be read. Memoized. */
+export declare function cliVersion(): string;
+/**
+ * `rebase-cli/0.17.3` — sent on every control-plane request.
+ *
+ * The control plane needs it to answer `CLI_TOO_OLD` with a minimum version
+ * instead of failing somewhere further in with a shape error. A client that
+ * does not identify itself can only ever be refused generically.
+ */
+export declare function cliUserAgent(): string;

package/package.json

@@ -1,18 +1,7 @@
 {
   "name": "@rebasepro/cli",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "description": "Developer tools for Rebase projects",
-  "main": "./dist/index.es.js",
-  "module": "./dist/index.es.js",
-  "types": "./dist/index.d.ts",
-  "type": "module",
-  "source": "src/index.ts",
-  "bin": {
-    "rebase": "bin/rebase.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
   "keywords": [
     "cli",
     "create-rebase-app",
@@ -22,8 +11,30 @@
     "typescript",
     "postgresql"
   ],
-  "author": "rebase.pro",
+  "homepage": "https://rebase.pro",
+  "bugs": {
+    "url": "https://github.com/rebasepro/rebase/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rebasepro/rebase.git",
+    "directory": "packages/cli"
+  },
   "license": "MIT",
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "author": "rebase.pro",
+  "main": "./dist/index.es.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "bin": {
+    "rebase": "bin/rebase.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "arg": "^5.0.2",
     "chalk": "^5.6.2",
@@ -32,12 +43,12 @@
     "inquirer": "14.0.2",
     "jiti": "^2.7.0",
     "pg": "^8.22.0",
-    "@rebasepro/agent-skills": "0.17.3",
-    "@rebasepro/codegen": "0.17.3",
-    "@rebasepro/server": "0.17.3",
-    "@rebasepro/types": "0.17.3",
-    "@rebasepro/client": "0.17.3",
-    "@rebasepro/server-postgres": "0.17.3"
+    "@rebasepro/agent-skills": "0.18.1",
+    "@rebasepro/codegen": "0.18.1",
+    "@rebasepro/client": "0.18.1",
+    "@rebasepro/server-postgres": "0.18.1",
+    "@rebasepro/types": "0.18.1",
+    "@rebasepro/server": "0.18.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -55,21 +66,18 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.es.js"
+      "import": "./dist/index.es.js",
+      "default": "./dist/index.es.js"
     }
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/rebasepro/rebase.git",
-    "directory": "packages/cli"
-  },
   "optionalDependencies": {
-    "@electric-sql/pglite": "^0.5.6",
-    "@electric-sql/pglite-pgvector": "^0.0.7",
-    "@electric-sql/pglite-socket": "^0.2.9"
+    "@electric-sql/pglite": "0.5.6",
+    "@electric-sql/pglite-pgvector": "0.0.7",
+    "@electric-sql/pglite-socket": "0.2.9"
   },
   "scripts": {
     "test": "vitest run",
+    "test:watch": "vitest",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.json && node ../../tooling/scripts/add-dts-extensions.mjs dist && node ../../tooling/scripts/assert-build-output.mjs",

package/templates/eject/backend/src/env.ts

@@ -3,6 +3,15 @@ import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { loadEnv } from "@rebasepro/server";
+// This should be `import { loadEnv, z } from "@rebasepro/server"`, and will be
+// in the first release that publishes that `z`. `loadEnv({ extend })` composes
+// the schema below with the framework's, and a schema built against a second
+// copy of zod fails the framework's instanceof checks and is silently dropped —
+// so taking `z` from the runtime is the only form that is reliably correct.
+// The `@rebasepro/server` version an ejected project pins does not export it
+// yet, and a template may only import what the version it pins publishes
+// (`pnpm check:templates`); an import of a symbol that is not there fails at
+// boot rather than at build. Switch both lines back when the version bumps.
 import { z } from "zod";
 
 const __filename = fileURLToPath(import.meta.url);

package/templates/eject/backend/src/index.ts

@@ -15,11 +15,12 @@ import {
     HonoEnv,
     listenWithPortRetry,
     cleanupDevPortFile,
+    initializeDataSources,
+    resolveDataSources,
     resolveStorageSources,
     logger
 } from "@rebasepro/server";
-import { createPostgresDatabaseConnection, createPostgresAdapter } from "@rebasepro/server-postgres";
-import { declaredStorageSources } from "@rebasepro/types";
+import { declaredDataSources, declaredStorageSources } from "@rebasepro/types";
 // Side-effect import: declaring is what registers, so anything that dropped
 // this as "unused" would leave the backend with no buckets — silently.
 import "../../config/resources.js";
@@ -35,10 +36,11 @@ import usersCollection from "../../config/collections/users.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// Which buckets this project has, read from the declarations in
+// Which databases and buckets this project has, read from the declarations in
 // `config/resources.ts`. One declaration site, so this process, the platform
 // and the frontend all read the same list. A project that declares none gets
-// one default source from the plain, unsuffixed S3_*/GCS_* variables.
+// one default source of each, from the plain unsuffixed variables.
+const dataSources = declaredDataSources();
 const storageSources = declaredStorageSources();
 
 // ─── App ─────────────────────────────────────────────────────────────
@@ -84,10 +86,21 @@ app.use("/*", cors({
 
 app.use("/*", secureHeaders());
 
-// ─── Database ────────────────────────────────────────────────────────
-const databaseUrl = env.DATABASE_URL;
-
-const { db, pool, connectionString } = createPostgresDatabaseConnection(databaseUrl);
+// ─── Databases ───────────────────────────────────────────────────────
+// One connection per declared database, resolved from `DATABASE_URL` for the
+// default one and `DATABASE_URL__<KEY>` for every other — the same resolver the
+// managed runtime uses, so this entrypoint cannot drift from it.
+//
+// It reads `process.env` rather than the typed `env` above on purpose: the
+// suffixed names belong to sources this project declared, so no fixed schema
+// can list them.
+//
+// Doing this by hand — one `createPostgresDatabaseConnection(env.DATABASE_URL)`
+// — is what this file used to do, and it quietly broke the moment anyone
+// declared a second database: collections routed to it fell back to the default
+// driver and their rows landed in the wrong database, behind a server that
+// looked healthy.
+const resolvedDataSources = resolveDataSources(process.env, dataSources);
 
 // ─── Start ───────────────────────────────────────────────────────────
 async function startServer() {
@@ -102,6 +115,21 @@ async function startServer() {
     // the same path is right from source and from `backend/dist/backend/src`.
     const cronsDir = path.resolve(__dirname, "../crons");
 
+    // Open a connection per declared database. Sequential, and a failure on the
+    // second closes whatever the first opened rather than leaking it against a
+    // server this process is about to abandon.
+    const drivers = await initializeDataSources(
+        resolvedDataSources,
+        // {{#collections}}
+        { tables, enums, relations },
+        // {{/collections}}
+        // {{^collections}}
+        // No generated schema: this project declares no collections in code.
+        undefined,
+        // {{/collections}}
+        [__dirname]
+    );
+
     const backend = await initializeRebaseBackend({
         // {{#collections}}
         collectionsDir: path.resolve(__dirname, "../../config/collections"),
@@ -115,16 +143,11 @@ async function startServer() {
         cronsDir: fs.existsSync(cronsDir) ? cronsDir : undefined,
         server,
         app,
-        database: createPostgresAdapter({
-            connection: db,
-            // {{#collections}}
-            schema: { tables,
-enums,
-relations },
-            // {{/collections}}
-            adminConnectionString: env.ADMIN_CONNECTION_STRING || databaseUrl,
-            connectionString
-        }),
+        // One bootstrapper per data source, each registered under its own key —
+        // the key is exactly what `collection.dataSource` routes against. Only
+        // the default source is handed the generated schema, which describes
+        // this project's tables and they live in the default database.
+        bootstrappers: drivers.map(driver => driver.bootstrapper),
         auth: {
             // {{#collections}}
             collection: usersCollection,
@@ -275,7 +298,11 @@ pass: env.SMTP_PASS! }
     // Drains HTTP, stops crons, tears down realtime, then closes the pool.
     // Guards against double signals and force-exits if shutdown hangs.
     installShutdownHandlers(backend, {
-        onCleanup: () => pool.end()
+        // Every pool, not just the first: a second database left open holds a
+        // connection against the server while this process is meant to be gone.
+        onCleanup: async () => {
+            await Promise.all(drivers.map(driver => driver.connection.pool?.end()));
+        }
     });
 }
 

package/templates/eject/config/resources.ts

@@ -16,7 +16,7 @@ export const main = database();
 
 /**
  * The default bucket, bound from the plain unsuffixed storage variables
- * (`S3_BUCKET`, `GCS_BUCKET`, `STORAGE_BUCKET`).
+ * (`S3_BUCKET`, `GCS_BUCKET`).
  *
  * Name more of them to get more — `bucket("media")` reads `S3_BUCKET__MEDIA`,
  * and so on for every variable that kind uses.

package/templates/overlays/baas/README.md

@@ -22,8 +22,12 @@ CREATE POLICY your_table_owner ON your_table
 `rebase.uid()`, `rebase.roles()` and `rebase.jwt()` are provided by Rebase and read the
 identity of the authenticated request.
 
-To serve unprotected tables anyway (development only), set
-`baas: { unprotectedTables: "serve" }` in `backend/src/index.ts`.
+Serving one anyway is `baas: { unprotectedTables: "serve" }`, and it is passed
+to `initializeRebaseBackend` — so it needs a project that owns its entrypoint.
+This scaffold has none: the published runtime boots it. Run `rebase eject` if
+you want that file, and read the flag for what it is — every authenticated
+request runs as one database role, so a table with no policy is handed whole to
+every signed-in caller.
 
 ## Run it
 
@@ -32,24 +36,40 @@ pnpm install
 pnpm dev
 ```
 
-- API: `http://localhost:3001/api/data/<table>`
-- Docs: `http://localhost:3001/api/swagger`
-- Health: `http://localhost:3001/health`
+`rebase dev` prints the URL it bound, and a box with the API, the Swagger path
+and the database it is using. **Read that box**: the port is derived from this
+project's path rather than fixed, so several Rebase projects can run at once,
+and `PORT` in `.env` applies to `rebase start`, not here.
 
-Set `DATABASE_URL` in `.env` to point at your database.
+- API: `<the printed URL>/api/data/<table>` — once a table is served
+- Docs: `<the printed URL>/api/swagger` — likewise
+- Health: `<the printed URL>/health`
+
+A headless project starts with no tables, so the first two answer
+`404 NO_COLLECTIONS` until you create one and restart — the box `rebase dev`
+prints says the same thing. See [Serving a table](#serving-a-table).
+
+There is no database to install: with no `DATABASE_URL` set, `rebase dev` runs a
+managed PostgreSQL for this project, with its data under `.rebase/`. Set
+`DATABASE_URL` in `.env` to point at a database of your own — it always wins.
+`rebase db url` prints whichever one is in use, so it pipes straight into psql.
 
 ## Use it from an app
 
 ```ts
 import { createRebaseClient } from "@rebasepro/client";
 
-const rebase = createRebaseClient({ baseUrl: "http://localhost:3001" });
+// The URL `rebase dev` printed. `pnpm example` reads it from .rebase-dev-url
+// for you rather than hardcoding a port.
+const rebase = createRebaseClient({ baseUrl: process.env.REBASE_URL! });
 const posts = await rebase.data.collection("posts").find();
 ```
 
 ## Adding an admin UI later
 
-Nothing here locks you out of it. Switch `mode` to `"cms"` in
-`backend/src/index.ts`, add a `config/collections` directory, and add a frontend
-that renders them. See MODULAR-ARCHITECTURE.md in the Rebase repo for the three
-adoption modes.
+Nothing here locks you out of it. Add a `config/collections/` directory and a
+frontend that renders them: the backend serves an admin panel once collections
+exist, because the mode is derived from whether any are declared rather than
+set anywhere. There is no `backend/src/index.ts` to edit — the published
+runtime boots this project — and `rebase eject` writes one if you want to own
+the entrypoint.

package/templates/overlays/baas/backend/package.json

@@ -15,12 +15,12 @@
         "@hono/node-server": "^2.0.12",
         "pg": "^8.11.3",
         "ws": "^8.16.0",
-        "dotenv": "^16.0.0",
+        "dotenv": "^17.4.2",
         "zod": "^4.4.3"
     },
     "devDependencies": {
         "@types/pg": "^8.6.5",
-        "@types/node": "^20.10.5",
+        "@types/node": "^22.19.4",
         "@types/ws": "^8.5.10",
         "tsx": "^4.20.6",
         "typescript": "^5.9.2"

package/templates/overlays/baas/backend/tsconfig.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "ES2022",
     "module": "ESNext",
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "lib": ["ES2022"],
     "outDir": "./dist",
     "strict": true,

package/templates/overlays/baas/package.json

@@ -27,10 +27,10 @@
     },
     "dependencies": {
         "@rebasepro/client": "workspace:*",
-        "dotenv": "^16.0.0"
+        "dotenv": "^17.4.2"
     },
     "engines": {
-        "node": ">=18.0.0"
+        "node": ">=22.22.0"
     },
     "pnpm": {
         "onlyBuiltDependencies": [
@@ -38,5 +38,8 @@
             "sharp",
             "@ariga/atlas"
         ]
+    },
+    "allowScripts": {
+        "@ariga/atlas": true
     }
 }

package/templates/overlays/baas/pnpm-workspace.yaml

@@ -4,6 +4,19 @@ packages:
 linkWorkspacePackages: true
 blockExoticSubdeps: false
 minimumReleaseAge: 0
+# See the note in templates/template/pnpm-workspace.yaml: pnpm 11 reads these
+# here and no longer from `.npmrc`, where npm 12 also warns about them.
+verifyDepsBeforeRun: false
+# Refuse to install on a Node older than `engines.node` in package.json.
+#
+# Off by default, in every package manager, which is why the floor this
+# scaffold declares was enforced by nothing: pnpm 11 installs a project whose
+# `engines.node` is `>=99.0.0` and exits 0, and npm prints EBADENGINE and also
+# exits 0. So a first run on Node 20 said nothing at all, and the first sign was
+# a syntax error from inside a dependency. `engine-strict=true` in npmrc is the
+# same setting for npm.
+engineStrict: true
+confirmModulesPurge: false
 allowBuilds:
   esbuild: true
   sharp: true

package/templates/template/.cursorrules

@@ -1,2 +1,3 @@
 # Rebase AI Rules
 Please refer to and follow the instructions defined in [ai-instructions.md](./ai-instructions.md).
+Install the Rebase skills for this assistant: `rebase skills install --agent cursor`.

package/templates/template/.env.example

@@ -4,9 +4,17 @@
 # ╚══════════════════════════════════════════════════════════════════════════════╝
 
 # ── Database ──────────────────────────────────────────────────────────────────
-# Database connection string (required)
-# You can use PostgreSQL (postgresql://) or MongoDB (mongodb:// or mongodb+srv://).
-# The backend will automatically detect the database type.
+# DATABASE_URL: unset means the managed database; set means yours.
+#
+# Leave it unset and `rebase dev` starts a managed PostgreSQL for this project,
+# with its data under .rebase/ — no Docker, nothing to install. Set it and that
+# database wins over the managed one, always: PostgreSQL (postgresql://) or
+# MongoDB (mongodb:// or mongodb+srv://), detected from the scheme.
+#
+# `rebase init` writes your project's `.env` with this line commented out, which
+# is what puts a new project on the managed database. `rebase db url` prints
+# whichever one is in use.
+#
 # sslmode=disable matches the local docker-compose database, which has no TLS;
 # schema tooling (atlas) would otherwise default to requiring SSL. Remove it
 # when pointing at a managed/cloud database.
@@ -24,6 +32,15 @@ DATABASE_URL=postgresql://rebase_app:changeme@localhost:5432/rebase?options=-c%2
 # explicitly for a local database, say so:
 #   DATABASE_URL=postgresql://rebase_app:changeme@localhost:5432/rebase?options=-c%20search_path%3Dpublic&sslmode=disable
 
+# The password for the compose database, and the one inside the DATABASE_URL
+# above. `rebase init` generates it and writes both into `.env`, so they cannot
+# disagree; docker-compose.yml falls back to `changeme` when it is unset.
+#
+# Commented out on purpose: `init` writes its own line above, and a second
+# assignment here would win — dotenv and compose both take the last one, so an
+# uncommented default would silently replace the generated password.
+# DATABASE_PASSWORD=changeme
+
 # Separate admin connection string for migrations and schema operations (optional)
 # Falls back to DATABASE_URL if not set
 # ADMIN_CONNECTION_STRING=postgresql://postgres:your-password@localhost:5432/rebase
@@ -53,9 +70,42 @@ JWT_SECRET=
 JWT_ACCESS_EXPIRES_IN=1h
 JWT_REFRESH_EXPIRES_IN=30d
 
+# Does the data API demand a token before it looks at anything? Defaults to
+# `true`. Set `false` for a backend a public website reads — row-level security
+# still decides which rows come back, this only removes the gate in front of it,
+# so a collection with no `select` rule still returns nothing.
+# AUTH_REQUIRE=false
+
 # ── Registration ──────────────────────────────────────────────────────────────
 ALLOW_REGISTRATION=true
 
+# The hard kill switch. `ALLOW_REGISTRATION=false` still admits the first
+# account into an empty table — it has to, or a fresh database can never
+# produce the signed-in caller that bootstrapping an admin needs. This closes
+# that window too, so pair it with the first-admin variables below or the
+# deployment has no way in at all. docker-compose.yml defaults it to `true`.
+# DISABLE_SELF_REGISTRATION=true
+
+# ── The first admin account ───────────────────────────────────────────────────
+# Outside production the first account to register is promoted to admin, which
+# is what makes `rebase dev` one command. In production that window is closed:
+# a deployment is answering on a hostname before you have typed anything, so a
+# first-come-first-admin form is a race the operator can lose.
+#
+# So production names its first admin instead. The runtime creates the account
+# once, while the user table is empty, and does nothing on every boot after
+# that. docker-compose.yml requires both variables, and `rebase init` wrote
+# them here with a generated password.
+#
+# `rebase dev` ignores both and says so at boot: locally the first account to
+# register is still the way in, and seeding here would spend that window before
+# you opened the app.
+#
+# Change the email to yours. Sign in, then change the password — this file is
+# plain text on disk.
+REBASE_ADMIN_EMAIL=
+REBASE_ADMIN_PASSWORD=
+
 # ── Email (optional — required for password reset / verification) ─────────────
 # SMTP_HOST=smtp.example.com
 # SMTP_PORT=587
@@ -70,7 +120,14 @@ ALLOW_REGISTRATION=true
 # EMAIL_LOGO_URL=https://yourapp.com/logo.png
 
 # ── URLs ──────────────────────────────────────────────────────────────────────
-# Canonical frontend URL (used in password-reset / verification emails)
+# Canonical frontend URL. It is the base of every emailed link (welcome,
+# password reset, verification) and one of the two things CORS is derived from.
+#
+# `rebase dev` OVERRIDES this with the port it actually starts the frontend on,
+# so you do not need to keep it in step during development — the value below is
+# only a sensible default for the tools that read the file directly. Set it to
+# your real site for a deployment; in production the server refuses to boot with
+# neither this nor CORS_ORIGINS.
 FRONTEND_URL=http://localhost:5173
 
 # Allowed CORS origins in production (comma-separated)
@@ -138,11 +195,15 @@ VITE_API_URL=
 # interface and pass it directly in your backend config.
 
 # --- Several buckets ------------------------------------------------------
-# Declare them in rebase.json, then configure each from the SAME variable names
-# carrying its own suffix. The default source takes no suffix, so everything
-# above keeps working and a single-bucket project declares nothing.
+# Declare them in config/resources.ts, then configure each from the SAME
+# variable names carrying its own suffix. The default source takes no suffix, so
+# everything above keeps working and a single-bucket project declares nothing.
 #
-#   rebase.json:  "storage": { "media": { "engine": "s3" } }
+#   config/resources.ts:  export const media = bucket("media", { engine: "s3" });
+#
+# Then `rebase resources --write` regenerates rebase.resources.json, which is
+# what readers that cannot run your code — the build, the control plane — see.
+# `rebase status` prints each bucket with the variables it is actually reading.
 #
 # STORAGE_TYPE__MEDIA=s3
 # S3_BUCKET__MEDIA=my-app-media
@@ -173,3 +234,25 @@ VITE_API_URL=
 # Falls back to false. Useful for databases with application-only roles or managed setups.
 # DISABLE_DB_ROLE_SWITCHING=true
 
+# ── Collection config strictness (optional) ───────────────────────────────────
+# What boot does with a key in your collections that this version does not read.
+# A key it knows *moved* is always fatal; this governs the ones it simply does
+# not recognise, which are usually a typo and occasionally deliberate metadata.
+#   warn   log it and boot (the default)
+#   error  refuse to boot — worth turning on in CI
+#   off    say nothing
+# REBASE_STRICT_COLLECTION_CONFIG=error
+
+# ── Self-hosting (docker compose) ─────────────────────────────────────────────
+# The runtime image tag the compose file runs: `rebasepro/server:${REBASE_VERSION}`.
+# `rebase init` pins it to the version it scaffolded against, so a project does
+# not silently move to a new runtime; `latest` is only the fallback when it is
+# unset. To upgrade, change this and restart — your bundle is untouched.
+REBASE_VERSION=latest
+
+# What boot does about versioned migrations in `backend/migrations`.
+#   ensure   create missing tables and columns from your collections (the default)
+#   migrate  run the migration files, then ensure
+#   off      neither
+# REBASE_MIGRATE_ON_BOOT=ensure
+

package/templates/template/.github/copilot-instructions.md

@@ -1,2 +1,3 @@
 # Rebase AI Rules
 Please refer to and follow the instructions defined in [ai-instructions.md](../ai-instructions.md).
+Install the Rebase skills for this assistant: `rebase skills install --agent copilot`.

package/templates/template/.mcp.json

@@ -0,0 +1,11 @@
+{
+    "mcpServers": {
+        "rebase": {
+            "command": "npx",
+            "args": ["-y", "@rebasepro/mcp"],
+            "env": {
+                "REBASE_PROJECT_DIR": "."
+            }
+        }
+    }
+}