@rebasepro/agent-skills 0.0.1-canary.4829d6e

package/skills/rebase-basics/SKILL.md

@@ -0,0 +1,757 @@
+---
+name: rebase-basics
+description: Core principles, workflow, and maintenance for using Rebase. Use this for all Rebase CLI tasks, project setup, MCP server usage, and general development. Make sure to ALWAYS use this skill whenever you are trying to use Rebase, even if not explicitly asked.
+---
+
+# Prerequisites
+
+Please complete these setup steps before proceeding, and remember your progress to avoid repeating them in future interactions.
+
+1. **Local Environment Setup:** Verify the environment is properly set up:
+   - Run `node --version` to check Node.js is installed (v20+ required).
+   - Run `pnpm --version` to check pnpm is installed. If not, install it: `npm install -g pnpm`.
+   - Verify PostgreSQL is available: `psql --version` or confirm Docker is running with a Postgres container.
+   - If any of these checks fail, use the `rebase-local-env-setup` skill to get the environment ready.
+
+2. **Authentication:**
+   Ensure you are logged in to Rebase Cloud for MCP server access. Run `rebase login`. This opens a browser for Google OAuth.
+   - Tokens are stored at `~/.rebase/tokens.json` and shared between CLI and MCP server.
+   - If the browser fails to open, check the CLI output for a manual URL.
+
+3. **Active Project:**
+   Most Rebase tasks require a project context.
+   - For Rebase Cloud: Run `rebase login` and select your project via the MCP `list_projects` tool.
+   - For self-hosted: Ensure your `.env` file in the project root contains a valid `DATABASE_URL`.
+
+# Rebase Usage Principles
+
+Please adhere to these principles when working with Rebase, as they ensure reliability and consistency:
+
+1. **Use pnpm exclusively:** Rebase uses pnpm as its package manager. Never use `npm` or `yarn`. All commands should use `pnpm run`, `pnpm install`, `pnpm add`, etc.
+
+2. **Never convert to `any`:** TypeScript strictness is critical. Never use `as any` type assertions. Use proper typing, `unknown`, or explicit type narrowing instead.
+
+3. **Follow the Schema-as-Code approach:** Schemas are defined as standalone TypeScript files. The visual Studio generates TypeScript via AST manipulation — it does NOT run raw SQL. Always define collections in code first.
+
+4. **Use the two-step migration workflow:**
+   - `rebase schema generate` — converts collection definitions to Drizzle ORM schema
+   - `rebase db push` (development) or `rebase db generate && rebase db migrate` (production)
+
+5. **Use Rebase MCP Server tools when available:** For data operations, user management, and collection browsing, prefer the MCP tools (`list_documents`, `get_document`, `create_document`, etc.) over writing manual API calls.
+
+6. **Respect the monorepo structure:** See the [Package Reference](#package-reference) section below for the full list of packages and when to use each.
+
+7. **Never deploy unless explicitly asked:** Agents should never run `rebase deploy`, `firebase deploy`, `gcloud deploy`, or any command that pushes code to live infrastructure unless the user explicitly asks you to deploy in the current conversation. Provide the exact command and let the user run it themselves if they prefer.
+
+8. **Scripting and Data Tasks:** Default to using the Rebase SDK (`@rebasepro/client` or `@rebasepro/server`) to write scripts or tasks for manipulating data. For standalone scripts running locally, you can dynamically read the active backend URL from the `.rebase-dev-url` temp file automatically created by the dev server. For internal server-side backend tasks, use the global `import { rebase } from "@rebasepro/server"` singleton. For calling custom backend functions from the frontend, use `client.functions.invoke('name', payload)` — NEVER manually construct `/api/functions/` URLs or extract auth tokens from `localStorage`. NEVER default to using raw `psql` queries or raw REST API calls (`fetch`/`curl`) unless explicitly instructed or the SDK lacks the functionality.
+
+# Project Structure
+
+## Scaffolded Project Structure (CLI)
+
+When you initialize a Rebase project via the CLI (`rebase init`), the generated project structure contains:
+
+```
+<project-root>/
+├── frontend/             # React frontend (Vite)
+├── backend/              # Hono backend server
+│   └── src/
+│       ├── index.ts      # Server entry point
+│       └── schema.generated.ts  # Auto-generated Drizzle schema
+├── config/               # Application configuration
+│   └── collections/      # TypeScript collection files (one per collection)
+│       └── index.ts      # Barrel export of all collections
+├── .env                  # Environment variables (generated from .env.example)
+├── .env.example          # Template with placeholder secrets
+├── docker-compose.yml    # PostgreSQL container (when no custom DB provided)
+├── drizzle.config.ts     # Drizzle ORM configuration
+├── pnpm-workspace.yaml   # pnpm workspace definition
+└── package.json          # Root workspace package.json
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `.env` | Environment variables — secrets, DATABASE_URL, JWT_SECRET |
+| `config/collections/*.ts` | Collection definitions (schema-as-code) |
+| `backend/src/index.ts` | Server entry point — calls `initializeRebaseBackend()` |
+| `backend/src/schema.generated.ts` | Auto-generated by `rebase schema generate` — DO NOT edit manually |
+| `.rebase-dev-port` | Written by `rebase dev` — stores the resolved backend port |
+| `.rebase-dev-url` | Written by `rebase dev` — stores `http://localhost:<port>` for scripts |
+
+## Framework Monorepo Structure
+
+For development of the Rebase framework itself, the repository is organized as a modular monorepo:
+
+```
+rebase/
+├── app/                      # Example application (scaffolded structure above)
+│   ├── frontend/             # React frontend (Vite)
+│   ├── backend/              # Hono backend server
+│   └── config/               # Application configuration
+│       └── collections/      # TypeScript collection files (one per collection)
+├── packages/                 # each directory is its package: `@rebasepro/<dir>`
+│   ├── types/                # shared kernel — isomorphic, no UI, no node
+│   ├── utils/
+│   ├── common/
+│   ├── client/               # the SDK
+│   ├── server/               # BaaS — Hono coordinator. Never imports a UI package
+│   ├── server-postgres/      # database driver
+│   ├── server-mongo/         # database driver
+│   ├── client-postgres/
+│   ├── cli/
+│   ├── codegen/
+│   ├── inference/
+│   ├── mcp/
+│   ├── ui/                   # CMS — React tier
+│   ├── forms/
+│   ├── app/                  # the runtime admin/studio/plugins register into
+│   ├── admin/
+│   ├── firebase/
+│   ├── studio/               # Full — BaaS console (admin is an optional peer)
+│   ├── plugin-ai/
+│   └── plugin-insights/
+├── pnpm-workspace.yaml
+└── package.json
+```
+
+The tiers are adoption modes, not separate products — see `MODULAR-ARCHITECTURE.md`.
+A BaaS install is `server` + a driver + `client`, with no React in the tree.
+
+## Package Reference
+
+| Package | Purpose | When to use |
+|---------|---------|-------------|
+| `@rebasepro/server` | Hono server coordinator, API generation, auth middleware, storage, email, cron, custom functions | Backend entry point — every Rebase backend imports this |
+| `@rebasepro/server-postgres` | PostgreSQL bootstrapper and Drizzle ORM data driver | Backend setup when using PostgreSQL |
+| `@rebasepro/server-mongo` | MongoDB bootstrapper and data driver | Backend setup when using MongoDB |
+| `@rebasepro/app` | The frontend runtime: hooks, providers, context, the auth controller (`useRebaseAuthController`) and `LoginView` | Frontend — React integration, hooks, providers, auth flows |
+| `@rebasepro/types` | Shared TypeScript type definitions (`PostgresCollectionConfig`, `CollectionConfig`, `RebaseClient`, etc.) | Type imports across all packages |
+| `@rebasepro/ui` | Standalone component library (Tailwind CSS v4 + Radix) | Building custom views in Studio or standalone UI |
+| `@rebasepro/admin` | The CMS: `RebaseAdmin`, collection views, entity forms, collection editor — built from your collection definitions | The admin panel. Needs collection files |
+| `@rebasepro/studio` | The BaaS console: SQL editor, schema visualizer, RLS editor, storage browser, logs, API explorer, API keys, backups, cron | Database tooling. Ships on BaaS with no CMS — `admin` is an optional peer |
+| `@rebasepro/client` | Client SDK for consuming the Rebase API | Any client-side or script-side data operations |
+| `@rebasepro/firebase` | Firebase client adapter | When connecting to a Firebase backend |
+| `@rebasepro/client-postgres` | PostgreSQL client adapter | When connecting directly to PostgreSQL from client |
+| `@rebasepro/common` | Shared utilities, `defaultUsersCollection` | Shared constants and default collection exports |
+| `@rebasepro/forms` | Form engine | Building dynamic forms from collection schemas |
+| `@rebasepro/mcp` | AI agent MCP tools | The MCP server that agents use |
+| `@rebasepro/codegen` | Typed SDK generation from collection definitions | Used by `rebase generate-sdk` command |
+| `@rebasepro/inference` | Auto-infer schema from data / database introspection | Used by `rebase schema introspect` |
+| `@rebasepro/plugin-ai` | AI-powered data autofill | Studio plugin for auto-completing fields |
+| `@rebasepro/plugin-insights` | Usage and data insights views | Plugin for analytics over your collections |
+| `@rebasepro/cli` | CLI tool | The `rebase` CLI binary |
+| `@rebasepro/utils` | Utility functions | Low-level shared helpers |
+
+# CLI Commands
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--version`, `-v` | Show CLI version number |
+| `--help`, `-h` | Show help message |
+
+## Full Command Reference
+
+### Project Lifecycle
+
+| Command | Description |
+|---------|-------------|
+| `rebase init [name]` | Scaffold a new Rebase project interactively |
+| `rebase dev` | Start development server (backend + frontend concurrently) |
+| `rebase build` | Build all workspace packages for production |
+| `rebase start` | Start the backend server in production mode |
+
+### `rebase init` Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--git` | `-g` | Initialize a git repository |
+| `--install` | `-i` | Install dependencies with the detected PM |
+| `--database-url` | — | PostgreSQL connection string (skip prompt) |
+| `--introspect` | — | Auto-introspect the database after init |
+| `--yes` | `-y` | Non-interactive mode (use all defaults) |
+
+```bash
+# Interactive mode
+rebase init my-app
+
+# Non-interactive — scaffold with a remote database and introspect it
+rebase init my-app --yes --database-url "postgresql://user:pass@host:5432/db" --introspect --install
+```
+
+### `rebase dev` Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--backend-only` | `-b` | Only start the backend server |
+| `--frontend-only` | `-f` | Only start the frontend server |
+| `--port` | `-p` | Set the backend port (default: deterministic per-project hash) |
+| `--generate` | `-g` | Auto-regenerate schema + SDK on startup and file changes |
+
+> **IMPORTANT FOR AGENTS:** Each project automatically receives a **unique default port** derived from its directory path (range 3001–3999), preventing collisions when running multiple Rebase instances. The resolved port is saved to `.rebase-dev-port` for affinity across restarts. The backend URL is saved to `.rebase-dev-url` so scripts can read it. The frontend receives `VITE_API_URL` automatically.
+
+**Port resolution order:**
+1. Explicit `--port` flag (highest priority)
+2. `PORT` environment variable
+3. Previously saved port from `.rebase-dev-port` (port affinity)
+4. Deterministic hash from project path (unique per project)
+
+**Auto-generation:** Disabled by default. Enable with `--generate` or by setting `REBASE_AUTO_GENERATE=true` / `REBASE_GENERATE=true` in your environment. When enabled, the CLI:
+- Runs `schema generate` + `generate-sdk` once on startup
+- Watches `config/collections/` for file changes and regenerates automatically
+
+```bash
+# Start everything (default)
+rebase dev
+
+# Backend only on a specific port
+rebase dev --backend-only --port 3005
+
+# With auto-generation of schema/SDK on collection file changes
+rebase dev --generate
+```
+
+### `rebase build`
+
+Runs the build script across all workspace packages using the detected package manager (pnpm or npm). No options.
+
+```bash
+rebase build
+```
+
+### `rebase start`
+
+Starts the backend server in production mode. Automatically sets `DOTENV_CONFIG_PATH` if a `.env` file is found. No options.
+
+```bash
+rebase start
+```
+
+### Schema Commands
+
+| Command | Description |
+|---------|-------------|
+| `rebase schema generate` | Generate Drizzle schema from collection definitions |
+| `rebase schema introspect` | Introspect a live database → generate Rebase collection files |
+| `rebase schema --help` | Show schema command help |
+
+> **IMPORTANT FOR AGENTS:** Schema commands are delegated to the active database driver plugin (e.g. `@rebasepro/server-postgres`). The plugin must be installed in `backend/package.json` or the command will fail with `Could not detect an active database plugin`.
+
+#### `schema generate` Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--collections` | `-c` | Path to collections directory |
+| `--output` | `-o` | Output path for generated schema |
+| `--watch` | `-w` | Watch for changes and regenerate automatically |
+
+#### `schema introspect` Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--output` | `-o` | Output directory for generated collection files |
+
+### Database Commands
+
+| Command | Description |
+|---------|-------------|
+| `rebase db push` | Apply schema directly to database (development only) |
+| `rebase db generate` | Generate SQL migration files |
+| `rebase db migrate` | Run pending SQL migrations |
+| `rebase db studio` | Open Drizzle Studio (visual database browser) |
+| `rebase db branch` | Database branching (create, list, delete, info) |
+| `rebase db --help` | Show database command help |
+
+> **IMPORTANT FOR AGENTS:** Like schema commands, database commands are delegated to the active database driver plugin. The plugin provides the actual implementation.
+
+```bash
+# Development workflow (fast, no migration files)
+rebase schema generate && rebase db push
+
+# Production workflow (versioned migrations)
+rebase schema generate
+rebase db generate
+rebase db migrate
+
+# Create a database branch
+rebase db branch create feature_auth
+```
+
+### SDK Generation
+
+| Command | Description |
+|---------|-------------|
+| `rebase generate-sdk` | Generate a typed JS/TS SDK from collection definitions |
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--collections-dir` | `-c` | `./config/collections` | Path to collections directory |
+| `--output` | `-o` | `./generated/sdk` | Output path for generated SDK |
+
+The SDK generator uses `jiti` for dynamic TypeScript import of collection files. It will look for an `index.ts` barrel export in the collections directory. If no index file is found, it falls back to scanning individual `.ts`/`.js` files.
+
+```bash
+rebase generate-sdk --collections-dir ./config/collections --output ./generated/sdk
+```
+
+### Auth Commands
+
+| Command | Description |
+|---------|-------------|
+| `rebase auth reset-password` | Reset a user's password directly in the database |
+| `rebase auth --help` | Show auth command help |
+
+| Option | Alias | Default | Description |
+|--------|-------|---------|-------------|
+| `--email` | `-e` | (required — or pass as positional arg) | User's email address |
+| `--password` | `-p` | `NewPassword123!` | New password |
+
+```bash
+# With flags
+rebase auth reset-password --email user@example.com --password MyNewPass!
+
+# Positional args
+rebase auth reset-password user@example.com MyNewPass!
+```
+
+### Diagnostics
+
+| Command | Description |
+|---------|-------------|
+| `rebase doctor` | Detect three-way schema drift between collections, Drizzle schema, and live DB |
+
+> **IMPORTANT FOR AGENTS:** `rebase doctor` compares collection definitions, the generated Drizzle schema (`schema.generated.ts`), and the actual PostgreSQL database. Run it after any manual DB changes or when suspecting schema drift.
+
+# Environment Variables
+
+## `loadEnv()` Function
+
+Rebase provides `loadEnv()` from `@rebasepro/server` to validate and load environment variables with Zod. Call it **after** your `.env` file has been loaded (e.g. via `dotenv.config()`). It does NOT load `.env` files itself.
+
+### Behavior
+
+- **Auto-generates** ephemeral `JWT_SECRET` and `REBASE_SERVICE_KEY` in non-production mode so developers can start without manual setup
+- **Blocks** auto-generated secrets in production (fails validation)
+- Returns a fully typed, validated env object
+
+### Signature
+
+```typescript
+import { loadEnv } from "@rebasepro/server";
+
+// Basic — just Rebase env vars:
+export const env = loadEnv();
+
+// Extended — add your own typed vars:
+import { z } from "zod";
+export const env = loadEnv({
+    extend: z.object({
+        SMTP_HOST: z.string().optional(),
+        SMTP_PORT: z.string().default("587").transform(Number),
+        STRIPE_SECRET_KEY: z.string(),
+    })
+});
+// env.SMTP_HOST → string | undefined  (fully typed)
+// env.STRIPE_SECRET_KEY → string      (validated, required)
+```
+
+### Function Overloads
+
+```typescript
+function loadEnv(): RebaseEnv;
+function loadEnv<E extends z.AnyZodObject>(options: { extend: E }): RebaseEnv & z.infer<E>;
+```
+
+When `extend` is provided, the base `rebaseEnvSchema` is merged (`.merge()`) with your custom Zod object, so all fields are validated together in a single pass.
+
+### Complete Environment Variable Reference
+
+| Variable | Type | Default | Required | Description |
+|----------|------|---------|----------|-------------|
+| `NODE_ENV` | `"development" \| "production" \| "test"` | `"development"` | No | Environment mode |
+| `PORT` | `string` → `number` | `"3001"` | No | Server port |
+| `DATABASE_URL` | `string` (URL) | — | **Yes** | PostgreSQL connection string |
+| `DATABASE_DIRECT_URL` | `string` (URL) | — | No | Direct connection (bypasses pooler) |
+| `DATABASE_READ_URL` | `string` (URL) | — | No | Read replica connection |
+| `ADMIN_CONNECTION_STRING` | `string` (URL) | — | No | Admin-level DB connection |
+| `JWT_SECRET` | `string` (≥32 chars) | Auto-generated in dev | **Yes** (prod) | JWT signing secret |
+| `JWT_ACCESS_EXPIRES_IN` | `string` | `"1h"` | No | Access token TTL |
+| `JWT_REFRESH_EXPIRES_IN` | `string` | `"30d"` | No | Refresh token TTL |
+| `REBASE_SERVICE_KEY` | `string` | Auto-generated in dev | No | Static key for server-to-server auth |
+| `GOOGLE_CLIENT_ID` | `string` | — | No | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | `string` | — | No | Google OAuth client secret |
+| `ALLOW_REGISTRATION` | `"true" \| "false"` | `"false"` | No | Allow public user registration |
+| `ALLOW_LOCALHOST_IN_PRODUCTION` | `"true" \| "false"` | — | No | Skip localhost URL checks in production |
+| `CORS_ORIGINS` | `string` | — | **Yes** (prod) | Allowed CORS origins (comma-separated) |
+| `FRONTEND_URL` | `string` | — | Prod alt | Alternative to CORS_ORIGINS for single frontend |
+| `DB_POOL_MAX` | `string` → `number` | `"20"` | No | Max database pool connections |
+| `DB_POOL_IDLE_TIMEOUT` | `string` → `number` | `"30000"` | No | Pool idle timeout (ms) |
+| `DB_POOL_CONNECT_TIMEOUT` | `string` → `number` | `"10000"` | No | Pool connect timeout (ms) |
+| `STORAGE_TYPE` | `"local" \| "s3" \| "gcs"` | `"local"` | No | File storage backend type |
+| `STORAGE_PATH` | `string` | — | No | Local storage directory path |
+| `FORCE_LOCAL_STORAGE` | `"true" \| "false"` | — | No | Force local storage even in production |
+| `S3_BUCKET` | `string` | — | When S3 | S3 bucket name |
+| `S3_REGION` | `string` | — | When S3 | S3 region |
+| `S3_ACCESS_KEY_ID` | `string` | — | When S3 | S3 access key |
+| `S3_SECRET_ACCESS_KEY` | `string` | — | When S3 | S3 secret key |
+| `S3_ENDPOINT` | `string` (URL) | — | No | Custom S3 endpoint (MinIO, R2, etc.) |
+| `S3_FORCE_PATH_STYLE` | `"true" \| "false"` | — | No | Use path-style S3 URLs |
+| `GCS_BUCKET` | `string` | — | When GCS | GCS/Firebase Storage bucket name |
+| `GCS_PROJECT_ID` | `string` | — | When GCS | GCP project ID |
+| `GOOGLE_APPLICATION_CREDENTIALS` | `string` (path) | — | When GCS | Path to GCP service account JSON |
+
+### Production Validations
+
+`loadEnv()` enforces these rules when `NODE_ENV=production`:
+
+1. `CORS_ORIGINS` or `FRONTEND_URL` **must** be set
+2. `JWT_SECRET` and `REBASE_SERVICE_KEY` **must** be explicitly set (auto-generation disabled)
+3. No environment variable may contain a localhost/loopback URL (unless `ALLOW_LOCALHOST_IN_PRODUCTION=true`)
+
+### Auto-Generated Dev Secrets
+
+In non-production mode, `loadEnv()` automatically generates cryptographically secure random values for `JWT_SECRET` and `REBASE_SERVICE_KEY` using `crypto.randomBytes(48).toString("hex")` when they are not set. This means:
+
+- **Developers can start immediately** without creating a `.env` file
+- **Existing JWT tokens are invalidated on every server restart** because the secret changes
+- A console warning is emitted: `⚠️ Auto-generated secrets for: JWT_SECRET, REBASE_SERVICE_KEY...`
+- To persist sessions across restarts, set these values explicitly in `.env`
+
+# Backend Configuration
+
+## `initializeRebaseBackend()`
+
+The main entry point for initializing a Rebase backend server. Returns a `RebaseBackendInstance` with access to drivers, auth, storage, and lifecycle methods.
+
+### `RebaseBackendConfig` — Full Interface
+
+```typescript
+import { initializeRebaseBackend, RebaseBackendConfig } from "@rebasepro/server";
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `server` | `Server` (Node `http.Server`) | — | **Required.** The HTTP server instance |
+| `app` | `Hono<HonoEnv>` | — | **Required.** The Hono application instance |
+| `collections` | `CollectionConfig[]` | `[]` | Inline collection definitions |
+| `collectionsDir` | `string` | — | Directory to auto-discover collection files (used if `collections` is empty) |
+| `basePath` | `string` | `"/api"` | Base path for all API routes |
+| `database` | `DatabaseAdapter` | — | Database adapter (takes precedence over `bootstrappers`) |
+| `bootstrappers` | `BackendBootstrapper[]` | `[]` | Database bootstrappers. Use one per engine for multiple engines in a single instance (e.g. Postgres + MongoDB); mark one `isDefault` |
+| `dataSources` | `DataSourceDefinition[]` | `[]` | Declared data sources (`key`, `engine`, `transport`). Drives capabilities and the server-vs-direct distinction. Collections on a `direct`/`custom` transport are client-only — the backend skips data routes for them. Server engines need no entry |
+| `auth` | `RebaseAuthConfig \| AuthAdapter` | — | Authentication config or pluggable adapter |
+| `storage` | `BackendStorageConfig \| StorageController \| Record<string, ...>` | — | File storage configuration. Supports `"local"`, `"s3"`, and `"gcs"` (GCS/Firebase Storage) backends. Use `Record<string, StorageController>` for multi-backend setups with named sources |
+| `history` | `unknown` | — | Entity history/audit-log configuration |
+| `defaultSecurityRules` | `SecurityRule[]` | — | Default RLS rules for collections without their own |
+| `enableSwagger` | `boolean` | `true` | Enable OpenAPI spec at `/api/docs` and Swagger UI at `/api/swagger` (dev only) |
+| `functionsDir` | `string` | — | Directory for auto-discovered custom function handlers |
+| `cronsDir` | `string` | — | Directory for auto-discovered cron job handlers |
+| `cronPersistence` | `boolean` | `true` | Persist cron job execution logs to the database |
+| `maxBodySize` | `number` | `10485760` (10 MB) | Max request body size in bytes. Set `0` to disable |
+| `csrf` | `{ origin: string \| string[] \| ((origin: string) => boolean) }` | — | CSRF protection (opt-in, disabled by default) |
+| `hooks` | `BackendHooks` | — | Backend-level hooks for intercepting admin data at the API boundary |
+| `logging` | `{ level?: "error" \| "warn" \| "info" \| "debug" }` | `"info"` | Log level configuration |
+
+> **IMPORTANT FOR AGENTS:** `maxBodySize` applies to all API routes under `basePath`. Storage upload routes have their **own** limit derived from the storage config's `maxFileSize` property (default: 50 MB), which overrides the global limit.
+
+### `RebaseAuthConfig` — Authentication Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `collection` | `CollectionConfig` | `defaultUsersCollection` | The collection used for auth users |
+| `jwtSecret` | `string` | — | JWT signing secret (≥32 chars) |
+| `accessExpiresIn` | `string` | `"1h"` | Access token TTL |
+| `refreshExpiresIn` | `string` | `"30d"` | Refresh token TTL |
+| `requireAuth` | `boolean` | `true` | Require authentication for data routes |
+| `allowRegistration` | `boolean` | `false` | Allow public user registration |
+| `serviceKey` | `string` | — | Static secret for server-to-server auth (≥32 chars) |
+| `defaultRole` | `string` | — | Role assigned to new users on registration |
+| `email` | `EmailConfig` | — | SMTP email configuration |
+| `hooks` | `AuthHooks` | — | Override auth behavior (password hashing, validation, etc.) |
+| `providers` | `OAuthProvider[]` | — | Custom OAuth providers |
+
+#### Built-in OAuth Providers
+
+| Property | Required Fields | Description |
+|----------|----------------|-------------|
+| `google` | `clientId`, `clientSecret?` | Google OAuth (supports ID token without secret) |
+| `github` | `clientId`, `clientSecret` | GitHub OAuth |
+| `linkedin` | `clientId`, `clientSecret` | LinkedIn OAuth |
+| `microsoft` | `clientId`, `clientSecret`, `tenantId?` | Microsoft/Azure AD OAuth |
+| `apple` | `clientId`, `teamId`, `keyId`, `privateKey` | Apple Sign In |
+| `facebook` | `clientId`, `clientSecret` | Facebook OAuth |
+| `twitter` | `clientId`, `clientSecret` | Twitter/X OAuth |
+| `discord` | `clientId`, `clientSecret` | Discord OAuth |
+| `gitlab` | `clientId`, `clientSecret`, `baseUrl?` | GitLab OAuth (supports self-hosted) |
+| `bitbucket` | `clientId`, `clientSecret` | Bitbucket OAuth |
+| `slack` | `clientId`, `clientSecret` | Slack OAuth |
+| `spotify` | `clientId`, `clientSecret` | Spotify OAuth |
+
+### `RebaseBackendInstance` — Return Value
+
+| Property / Method | Type | Description |
+|-------------------|------|-------------|
+| `driver` | `DataDriver` | The default data driver |
+| `driverRegistry` | `DriverRegistry` | Registry of all initialized drivers |
+| `realtimeService` | `RealtimeProvider` | Default realtime provider |
+| `realtimeServices` | `Record<string, RealtimeProvider>` | All realtime providers |
+| `auth` | `BootstrappedAuth \| undefined` | Bootstrapped auth result |
+| `storageRegistry` | `StorageRegistry \| undefined` | All storage backends |
+| `storageController` | `StorageController \| undefined` | Default storage controller |
+| `collectionRegistry` | `BackendCollectionRegistry` | Registry of all active collections |
+| `cronScheduler` | `CronScheduler \| undefined` | The cron job scheduler (if configured) |
+| `healthCheck()` | `() => Promise<HealthCheckResult>` | Deep health check (verifies DB connectivity, returns latency) |
+| `shutdown(timeoutMs?)` | `(timeoutMs?: number) => Promise<void>` | Graceful shutdown (stops cron, destroys realtime, drains HTTP, default 15s timeout) |
+
+### Shutdown Behavior
+
+When `shutdown()` is called, it performs these steps in order:
+
+1. **Stops the cron scheduler** (if configured)
+2. **Destroys realtime services** (LISTEN clients, debounce timers, subscriptions) — this happens **before** pool close to prevent timer callbacks firing against a closed pool
+3. **Closes the HTTP server** (stops accepting, drains in-flight requests)
+4. **Force-resolves** after `timeoutMs` (default 15000ms). Pass `0` to disable the force timer (useful in tests)
+
+### Minimal Backend Example
+
+```typescript
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import { initializeRebaseBackend, loadEnv } from "@rebasepro/server";
+import { createPostgresAdapter } from "@rebasepro/server-postgres";
+import { defaultUsersCollection } from "@rebasepro/common";
+import collections from "../config/collections";
+import dotenv from "dotenv";
+
+dotenv.config({ path: "../../.env" });
+const env = loadEnv();
+
+const app = new Hono();
+const server = serve({ fetch: app.fetch, port: env.PORT });
+
+await initializeRebaseBackend({
+    app,
+    server,
+    database: createPostgresAdapter({
+        connectionString: env.DATABASE_URL,
+    }),
+    collections: [...collections, defaultUsersCollection],
+    collectionsDir: "../config/collections",
+    functionsDir: "./src/functions",
+    cronsDir: "./src/crons",
+    auth: {
+        collection: defaultUsersCollection,
+        jwtSecret: env.JWT_SECRET,
+        serviceKey: env.REBASE_SERVICE_KEY,
+        allowRegistration: env.ALLOW_REGISTRATION,
+        google: env.GOOGLE_CLIENT_ID
+            ? { clientId: env.GOOGLE_CLIENT_ID }
+            : undefined,
+    },
+    // Single backend: { type: "local" | "s3" | "gcs" }
+    // Multi-backend: Record<string, StorageController> with named sources
+    storage: { type: env.STORAGE_TYPE },
+    defaultSecurityRules: [
+        { operation: "select", access: "public" },
+        { operations: ["insert", "update", "delete"], roles: ["admin"] },
+    ],
+});
+
+console.log(`Server running at http://localhost:${env.PORT}`);
+```
+
+# The `rebase` Singleton
+
+After `initializeRebaseBackend()` completes, a server-side singleton is available:
+
+```typescript
+import { rebase } from "@rebasepro/server";
+```
+
+> **WARNING FOR AGENTS:** The singleton is a **lazy proxy** — accessing it at module import time (top-level) will throw. Only use it inside request handlers, cron jobs, hooks, or functions that run after the server has started.
+
+### How It Works
+
+The singleton is a JavaScript `Proxy` object. Any property access on `rebase.*` is intercepted:
+- If the server **has** been initialized (`_initRebase()` called by `initializeRebaseBackend()`), the access is forwarded to the internal `RebaseClient` instance.
+- If the server **has not** been initialized yet, a descriptive error is thrown: `"rebase.<prop>: server not initialized yet"`.
+- The proxy is **read-only** — attempting to assign `rebase.anything = value` throws.
+
+The underlying client uses an internal `app.request()` fetch (no network hop) and authenticates with the `serviceKey`, giving it **admin-level access** (bypasses RLS).
+
+### What It Exposes
+
+The `rebase` singleton implements the `RebaseClient` interface:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `rebase.data` | `RebaseData` | Admin-level data access (bypasses RLS). Use `rebase.data.<slug>.find()`, `.findOne()`, `.create()`, `.update()`, `.delete()` |
+| `rebase.auth` | `AuthClient` | Authentication operations |
+| `rebase.storage` | `StorageSource \| undefined` | File storage operations |
+| `rebase.email` | `EmailService \| undefined` | Send emails via SMTP (only when email is configured) |
+| `rebase.admin` | `AdminAPI \| undefined` | User management API |
+| `rebase.sql` | `(query: string) => Promise<Record[]> \| undefined` | Raw SQL execution (only for SQL databases) |
+| `rebase.baseUrl` | `string \| undefined` | The base HTTP URL of the backend |
+
+### Usage Examples
+
+```typescript
+import { rebase } from "@rebasepro/server";
+
+// In a cron job, custom function, or hook:
+
+// Data operations (admin-level, no RLS)
+const posts = await rebase.data.posts.find({ limit: 10 });
+await rebase.data.orders.create({ status: "pending", total: 99.99 });
+
+// Send an email
+await rebase.email?.send({
+    to: "admin@company.com",
+    subject: "Daily Report",
+    html: "<p>Today's summary...</p>",
+});
+
+// Execute raw SQL
+if (rebase.sql) {
+    const rows = await rebase.sql("SELECT count(*) FROM orders WHERE status = 'pending'");
+}
+```
+
+### Testing
+
+```typescript
+import { _setRebaseMock, _resetRebaseMock } from "@rebasepro/server";
+
+// Only works when NODE_ENV=test
+beforeEach(() => {
+    _setRebaseMock({
+        data: mockDataLayer,
+        email: mockEmailService,
+    });
+});
+afterEach(() => _resetRebaseMock());
+```
+
+> **IMPORTANT FOR AGENTS:** `_setRebaseMock()` and `_resetRebaseMock()` throw if `NODE_ENV !== "test"`. This prevents accidental use in production.
+
+# MCP Server Tools
+
+The Rebase MCP server provides these tools for AI agents. Use the MCP tool calling convention (`call_mcp_tool` with server name `rebase`):
+
+### Dev Server Management
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `rebase_dev_start` | Start the Rebase dev server (frontend + backend). Returns immediately — use `rebase_dev_logs` to check output | — |
+| `rebase_dev_stop` | Stop the running Rebase dev server | — |
+| `rebase_dev_logs` | Read recent output from the running dev server | `lines?: number` (default 50) |
+
+### Schema & Database
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `rebase_schema_generate` | Generate Drizzle schema from collection definitions. Run after adding or modifying collection files | — |
+| `rebase_schema_introspect` | Introspect the live database and generate Rebase collection definitions from existing tables | — |
+| `rebase_db_push` | Apply the current Drizzle schema directly to the database (development shortcut, skips migration files) | — |
+| `rebase_db_generate` | Generate SQL migration files from schema changes (compares current Drizzle schema against the last entity) | — |
+| `rebase_db_migrate` | Run all pending SQL migrations against the database | — |
+
+### SDK
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `rebase_generate_sdk` | Generate a fully-typed JS/TS SDK from collection definitions | — |
+
+### Document Operations
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `list_documents` | List documents from a collection with optional filtering, sorting, pagination | `collection` (required), `where?: object`, `orderBy?: string`, `limit?: number` (default 25), `offset?: number` |
+| `get_document` | Get a single document by ID | `collection` (required), `id` (required) |
+| `create_document` | Create a new document in a collection | `collection` (required), `data` (required) |
+| `update_document` | Update an existing document | `collection` (required), `id` (required), `data` (required) |
+| `delete_document` | Delete a document from a collection | `collection` (required), `id` (required) |
+
+### User Management
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `list_users` | List all users registered in the backend, including their roles | — |
+| `create_user` | Create a new user | `email` (required), `displayName?: string`, `password?: string`, `roles?: string[]` |
+| `update_user` | Update an existing user (email, display name, roles) | `userId` (required), `email?: string`, `displayName?: string`, `roles?: string[]` |
+| `delete_user` | Delete a user from the backend | `userId` (required) |
+| `list_roles` | List all roles defined in the backend | — |
+
+### Filtering with `list_documents`
+
+The `where` parameter accepts a filter object with PostgREST-style operators:
+
+```json
+{
+  "collection": "products",
+  "where": {
+    "status": "eq.active",
+    "price": "gte.100",
+    "category": "eq.electronics"
+  },
+  "orderBy": "price:desc",
+  "limit": 10
+}
+```
+
+# Common Issues
+
+### Database & Connection
+
+- **`DATABASE_URL is not set`:** Ensure `.env` exists in the project root with `DATABASE_URL=postgresql://user:password@localhost:5432/rebase`
+- **`DATABASE_URL must be a valid URL`:** The value must be a proper PostgreSQL URL including protocol (`postgresql://`). Check for missing or malformed values.
+- **Connection refused on port 5432:** PostgreSQL is not running. Start it with `docker compose up -d db` or verify your local Postgres service.
+- **`CORS_ORIGINS or FRONTEND_URL must be set in production`:** In `NODE_ENV=production`, set `CORS_ORIGINS=https://yourapp.com` or `FRONTEND_URL=https://yourapp.com` in `.env`.
+- **Localhost URL blocked in production:** `loadEnv()` rejects localhost/loopback URLs in production. Set `ALLOW_LOCALHOST_IN_PRODUCTION=true` to override (not recommended).
+
+### JWT & Authentication
+
+- **`JWT_SECRET must be at least 32 characters long`:** Generate one with `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` and set it in `.env`.
+- **`JWT_SECRET must be explicitly set in production`:** Auto-generated dev secrets are blocked in production. Set the value explicitly in `.env`.
+- **Tokens invalidated on restart:** In development, `JWT_SECRET` is auto-generated ephemerally. Set it explicitly in `.env` for persistent sessions across restarts.
+- **`REBASE_SERVICE_KEY is too short`:** Must be ≥32 characters. Generate with `node -e "console.log(require('crypto').randomBytes(48).toString('base64'))"`.
+
+### Port Conflicts
+
+- **Port already in use:** `rebase dev` auto-selects a unique port per project (3001–3999). If a conflict occurs, use `--port <number>` to specify an explicit port: `rebase dev --port 3010`.
+- **Frontend connecting to wrong backend:** Delete `.rebase-dev-port` to reset port affinity, then restart with `rebase dev`.
+
+### Schema Drift
+
+- **Schema out of sync:** Run `rebase doctor` to detect three-way drift between collections, generated Drizzle schema, and the live database.
+- **`schema.generated.ts` is stale:** Run `rebase schema generate` to regenerate it from your collection definitions.
+- **Migrations pending:** Run `rebase db migrate` to apply outstanding migration files.
+- **Column type mismatch after manual DB edit:** Never edit the database manually. Always modify collection files → `rebase schema generate` → `rebase db push` (dev) or `rebase db generate && rebase db migrate` (prod).
+
+### CLI & Tooling
+
+- **pnpm not found:** Install with `npm install -g pnpm`.
+- **Node.js version mismatch:** Rebase requires Node.js v20+. Use `nvm install 20 && nvm use 20`.
+- **`Could not find tsx binary`:** Install tsx in your project: `pnpm add -D tsx`.
+- **`Could not detect an active database plugin`:** Ensure `@rebasepro/server-postgres` (or another driver) is listed in `backend/package.json` dependencies.
+- **`No bootstrappers or database adapter provided`:** The `initializeRebaseBackend()` call is missing the `database` (or `bootstrappers`) property. See the backend configuration section above.
+- **`Could not find CLI entry point for <plugin>`:** The database driver plugin's CLI script is missing or not found. Reinstall the plugin: `pnpm add @rebasepro/server-postgres`.
+
+### Singleton Errors
+
+- **`rebase.<prop>: server not initialized yet`:** You are accessing the `rebase` singleton at module import time or before `initializeRebaseBackend()` has completed. Move the access inside a handler, hook, or function body.
+- **`Cannot set rebase.<prop> directly`:** The singleton is read-only. You cannot assign properties to it.
+- **`_setRebaseMock can only be called in a test environment`:** Set `NODE_ENV=test` before calling `_setRebaseMock()`.
+
+### Storage
+
+- **`Storage backend "default" uses local filesystem in production`:** A warning is emitted when using `type: "local"` with `NODE_ENV=production`. Files will be lost on container restart. Configure S3-compatible storage or a custom `StorageController`.
+- **`File too large`:** The storage upload endpoint has its own body limit (default 50 MB), separate from the global `maxBodySize` (default 10 MB). Configure `maxFileSize` in your storage config to increase it.
+
+# References
+
+- **Documentation:** [rebase.pro/docs](https://rebase.pro/docs)
+- **GitHub:** [github.com/rebasepro/rebase](https://github.com/rebasepro/rebase)