@supabase/lite 0.9.0 → 0.9.1-next.2

package/docs/integrations/vite.mdx

@@ -0,0 +1,87 @@
+---
+title: "Vite plugin"
+description: "Run Supabase Lite in-process inside the Vite dev server. The recommended path for Vite frontends."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+If your frontend uses Vite, this is the recommended way to run Supabase Lite: no separate CLI process, no Docker, no proxy config. The `@supabase/lite/vite` plugin runs the backend inline inside the Vite dev server, so one process serves both your app and the API.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { supalite } from "@supabase/lite/vite";
+
+export default defineConfig({
+  plugins: [supalite()],
+});
+```
+
+<Aside type="caution">
+Run exactly one backend per project. Don't run `lite dev` or `lite start` at the same time as this plugin, and don't run both CLI backends together. It isn't necessarily a port conflict: two backends driving the same `supabase/` project and SQLite file race migrations and declarative metadata reconciliation. Pick one process model per project; see [Running Supabase Lite](/running).
+</Aside>
+
+## What it does
+
+- Auto-resolves `./supabase/config.toml` from the project root.
+- Applies pending imperative migrations, then the declarative schema diff, on boot.
+- Watches `schemas/*.sql` (and the migrations directory) for hot-reload during `vite`/`vite dev`.
+- Mounts `/auth/v1`, `/rest/v1`, and `/_system` as middleware on the Vite dev/preview server.
+- Injects `VITE_SUPABASE_URL` (the current browser origin, via `window.location.origin`) and the project's resolved `sb_publishable_*` key as `VITE_SUPABASE_ANON_KEY` into `import.meta.env`, so the canonical client snippet works with zero `.env` setup, even with key enforcement on.
+
+<Aside type="caution">
+`vite preview` mounts the API and runs boot-time migrations, but does **not** watch schemas (it simulates production). `vite build` and any standalone production server do not mount the API at all. Use `lite start`, hosted Supabase, or an embedded app there.
+</Aside>
+
+## Client setup
+
+```ts
+import { createClient } from "@supabase/supabase-js";
+
+const client = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY,
+);
+```
+
+Equivalently, since the plugin's default URL is always the current origin:
+
+```ts
+const client = createClient(window.location.origin, "<sb_publishable_...>");
+```
+
+The plugin resolves the project's real `auth.publishable_key` (see [API keys](/auth/overview#api-keys)) and injects it as `VITE_SUPABASE_ANON_KEY`, so a `lite init`'d project works with zero `.env` setup even with key enforcement on. The placeholder `"sb-lite-anon-key"` is only used as a fallback when no project/key is found.
+
+A `.env` value for either `VITE_SUPABASE_URL` or `VITE_SUPABASE_ANON_KEY` always overrides the plugin's injected default. The plugin only fills in what you haven't set, and it resolves your `root`/`envDir`/`envPrefix` the same way Vite itself does, so a value that Vite would expose is a value the plugin sees.
+
+## Options
+
+```ts
+supalite({
+  config: "./supabase/config.toml",
+  migrateOnBoot: true,
+  watchSchema: true,
+  forceSchema: false,
+  initOnBoot: true,
+  prefixes: ["/auth/v1", "/rest/v1", "/_system"],
+  admin: true,
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `config` | string | auto-resolved `./supabase/config.toml` | Path to the project's `config.toml`. Defaults to auto-resolving `./supabase/config.toml` relative to where Vite runs. |
+| `migrateOnBoot` | boolean | `true` | Apply pending imperative migrations, then run the declarative schema diff, when the dev/preview server starts. |
+| `watchSchema` | boolean | `true` | Watch `schemas/*.sql` and the migrations directory for changes and hot-reload the schema. Only takes effect during `vite`/`vite dev`; `vite preview` never watches, regardless of this option. |
+| `forceSchema` | boolean | `false` | Allow the declarative schema diff to apply changes that would otherwise be blocked as data-loss. Logs a warning on boot when enabled. |
+| `initOnBoot` | boolean | `true` | Scaffold the initial `supabase/` structure if it doesn't exist yet, equivalent to `lite init`, before starting. |
+| `prefixes` | string[] | `["/auth/v1", "/rest/v1", "/_system"]` | Which path prefixes the plugin mounts on the Vite server. Only override this if you need to move the API off its default paths. |
+| `admin` | boolean | `true` on loopback | [Admin mode](/running#admin-mode): serve keyless, same-origin, loopback `/rest/v1` requests as `service_role`. A non-loopback Vite host (including bare `vite --host`) defaults it off and requires explicit `admin: true`; config cannot silently re-enable an exposed listener. Preview always disables it. Admin also covers `/storage/v1`, but that prefix is not mounted by default. |
+
+Vite and the Lite CLI use the same host posture: local binding keeps the local admin default, while `vite --host` / `lite dev --host` exposes the listener and disables admin unless explicitly enabled. If a sandbox or tunnel publishes the port, leave admin off even when its local forwarding socket appears loopback.
+
+## Related
+
+- [Running Supabase Lite](/running): how this compares to `lite dev`/`lite start`/embedding.
+- [Embedded / programmatic](/integrations/embedded): the same boot sequence, driven manually instead of by the plugin.
+- Upstream: [Supabase local development](https://supabase.com/docs/guides/local-development), the Docker-based equivalent this plugin replaces for Vite apps.

package/docs/llms.txt

@@ -0,0 +1,52 @@
+# Supabase Lite docs
+
+Bundled with @supabase/lite 0.9.1-next.2. Same content as https://docs.lite.dev, which tracks the latest release.
+Files are MDX source (Astro Starlight). Site path -> file: `/` -> `index.mdx`, `/database/rls` -> `database/rls.mdx`.
+
+## Start
+
+- [Introduction](index.mdx): What Supabase Lite is, what's supported today, and how it relates to hosted Supabase.
+- [Quickstart](quickstart.mdx): Install Supabase Lite, scaffold a project, write a schema, and run your first query.
+- [Compatibility](compatibility.mdx): Capability-level support matrix for the Data API, Auth, Storage, RLS, Realtime, and Edge Functions across SQLite, PGlite, and Postgres.
+- [Running Supabase Lite](running.mdx): Choose between the Vite plugin, lite dev, lite start, and embedded/programmatic usage.
+- [Upgrading to Supabase](upgrade.mdx): Migrate a Supabase Lite project to hosted or local Supabase with lite upgrade.
+
+## Database
+
+- [Database overview](database/overview.mdx): How Supabase Lite's Postgres-shaped Data API maps onto SQLite, PGlite, and Postgres.
+- [Backends](database/backends.mdx): SQLite drivers vs PGlite/Postgres: how Supabase Lite picks a database, and how to switch.
+- [Data API divergences](database/data-api.mdx): Where the PostgREST-compatible Data API and supabase-js diverge on SQLite, and the workarounds.
+- [Row Level Security](database/rls.mdx): RLS works on every Supabase Lite backend; SQLite enforces it at the application layer with specific caveats.
+- [Declarative schemas](database/schemas.mdx): Writing Postgres DDL in supabase/schemas/*.sql, and how it maps onto SQLite's single-namespace model.
+- [Migrations](database/migrations.mdx): lite migration and lite db commands, the declarative diff flow, and how they differ from supabase db.
+- [Functions & triggers](database/functions-triggers.mdx): The PL/pgSQL trigger subset supported on SQLite, and what runs unmodified on Postgres backends.
+- [Postgres → SQLite translation](database/postgres-sqlite-translation.mdx): How Supabase Lite auto-translates Postgres DDL to SQLite, and the exact errors you'll see when something isn't supported.
+
+## Auth
+
+- [Auth overview](auth/overview.mdx): GoTrue-compatible Auth API for @supabase/lite: what's implemented, what's planned, and how it fits into supabase-js.
+- [Supported auth flows](auth/supported-flows.mdx): The 13 GoTrue-compatible Auth endpoints Supabase Lite implements, with supabase-js examples.
+- [Email delivery & templates](auth/email.mdx): Configure the email driver, verification links, and customizable transactional email templates for Supabase Lite Auth.
+- [Auth: not supported](auth/not-supported.mdx): Anonymous sign-in, manual identity linking, the admin API, MFA, and OAuth providers beyond github/google are not implemented yet. What's planned vs. not planned, and the hosted-Supabase workaround.
+
+## Storage
+
+- [Storage overview](storage/overview.mdx): Storage API for @supabase/lite: experimental flag, endpoint coverage, and supabase-js parity.
+- [Storage adapters](storage/adapters.mdx): Pluggable storage backends (filesystem, S3-compatible) and transformation adapters (Noop, Sharp, Cloudflare) for Supabase Lite Storage.
+- [Storage limitations](storage/limitations.mdx): What's not yet implemented in Supabase Lite Storage: TUS uploads, webhooks, bucket-list query params, and the S3-compatible server protocol.
+
+## Integrations
+
+- [Vite plugin](integrations/vite.mdx): Run Supabase Lite in-process inside the Vite dev server. The recommended path for Vite frontends.
+- [Embedded / programmatic](integrations/embedded.mdx): Use the App class directly in Bun, Node, browser, or edge runtimes, without the CLI.
+- [Framework guides](integrations/frameworks.mdx): Running Supabase Lite inside Next.js, Cloudflare Workers, and Docker.
+
+## CLI
+
+- [CLI overview](cli/overview.mdx): The lite CLI versus the supabase CLI: parity, gaps, and what's still experimental.
+- [Telemetry](cli/telemetry.mdx): The lite CLI sends anonymous usage telemetry by default. How to disable it.
+
+## Other
+
+- [Edge Functions](other/edge-functions.mdx): Supabase Edge Functions (Deno runtime) are not supported in @supabase/lite. Run a regular server endpoint instead.
+- [Realtime](other/realtime.mdx): Supabase Realtime (channels, presence, broadcast, Postgres Changes) is not implemented in @supabase/lite yet.

package/docs/other/edge-functions.mdx

@@ -0,0 +1,34 @@
+---
+title: "Edge Functions"
+description: "Supabase Edge Functions (Deno runtime) are not supported in @supabase/lite. Run a regular server endpoint instead."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="caution">
+Edge Functions are not supported. Supabase Lite does not bundle a Deno or edge runtime, and there is no `/functions/v1/*` route.
+</Aside>
+
+A config schema for functions exists in `app/src/config/functions.ts` (per-function JWT verification, entrypoints), but nothing executes against it: `supabase/functions/*` in your project is not picked up or served by Supabase Lite.
+
+## Workaround
+
+Supabase Lite is a plain HTTP server (`app.fetch`), so anything you'd put in an Edge Function can live in a normal server endpoint instead, called directly from your client:
+
+- A [Hono](https://hono.dev/) or Express route mounted alongside your app
+- A Next.js App Router route handler
+- Vite middleware, in the same process as the [Vite plugin](/integrations/vite)
+
+```ts
+// Instead of supabase.functions.invoke("my-function", { body }):
+const res = await fetch("/api/my-function", {
+  method: "POST",
+  body: JSON.stringify(body),
+});
+```
+
+Since Supabase Lite already runs your Data API and Auth in-process (`app.fetch`), a hand-rolled endpoint has direct access to `app.getClient()` for database/auth calls without an extra network hop. See [Embedded / programmatic usage](/integrations/embedded) for wiring that up.
+
+If you specifically need Deno-compatible Edge Functions (for parity with a production Supabase project, or because you rely on Deno-only APIs), run those against hosted Supabase and keep the rest of your app on Supabase Lite.
+
+For the Edge Functions model this replaces, see the [Supabase Edge Functions docs](https://supabase.com/docs/guides/functions). See [Compatibility](/compatibility) for how this tracks against other services.

package/docs/other/realtime.mdx

@@ -0,0 +1,22 @@
+---
+title: "Realtime"
+description: "Supabase Realtime (channels, presence, broadcast, Postgres Changes) is not implemented in @supabase/lite yet."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="caution">
+Realtime is not implemented. There is no WebSocket server, no channels, and no Postgres Changes stream in Supabase Lite yet.
+</Aside>
+
+A config schema for Realtime exists in `app/src/config/realtime.ts`, but it isn't wired to any runtime behavior. Setting `[realtime]` keys in `config.toml` has no effect today. Calling `supabase.channel(...)`, `.on("postgres_changes", ...)`, presence, or broadcast against a Supabase Lite instance will not connect to anything on the server side.
+
+## Workaround
+
+Run the realtime-dependent parts of your app against hosted Supabase. Supabase Lite can still serve the Data API and Auth for the rest of the app; there's no requirement to run a single backend for every product.
+
+## What it would look like
+
+When implemented, Realtime would need to cover the same three primitives upstream does: Postgres Changes (streaming row-level INSERT/UPDATE/DELETE events), Broadcast (ephemeral pub/sub over a channel), and Presence (shared client state per channel). None of this exists yet, so check `STATUS.md` in the installed package for current status before building around an assumed timeline.
+
+For the concepts and client API this would eventually support unchanged, see the [Supabase Realtime docs](https://supabase.com/docs/guides/realtime). See [Compatibility](/compatibility) for how Realtime tracks against everything else.

package/docs/quickstart.mdx

@@ -0,0 +1,150 @@
+---
+title: "Quickstart"
+description: "Install Supabase Lite, scaffold a project, write a schema, and run your first query."
+---
+
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+
+This walks through the minimal path: install, scaffold, write a schema, run a server, query it with `supabase-js`. For the general Supabase local-dev flow this mirrors, see the [Supabase local development guide](https://supabase.com/docs/guides/local-development).
+
+<Steps>
+
+1. **Install**
+
+   Install both `@supabase/lite` and `@supabase/supabase-js`.
+
+   <Tabs sync="pkg-manager">
+   <TabItem label="bun">
+   ```bash
+   bun add @supabase/lite @supabase/supabase-js
+   ```
+   </TabItem>
+   <TabItem label="npm">
+   ```
+   npm install @supabase/lite @supabase/supabase-js
+   ```
+   </TabItem>
+   <TabItem label="pnpm">
+   ```bash
+   pnpm add @supabase/lite @supabase/supabase-js
+   ```
+   </TabItem>
+   </Tabs>
+
+   Add the `-g` flag if you want the `lite` CLI available system-wide instead of per-project.
+
+1. **Scaffold a project**
+
+   <Tabs sync="pkg-manager">
+   <TabItem label="bun">
+   ```bash
+   bunx lite init
+   ```
+   </TabItem>
+   <TabItem label="npm">
+   ```bash
+   npx lite init
+   ```
+   </TabItem>
+   <TabItem label="pnpm">
+   ```bash
+   pnpm exec lite init
+   ```
+   </TabItem>
+   </Tabs>
+
+   This creates a Supabase-compatible `supabase/` directory: `config.toml`, `schemas/schema.sql`, `seed.sql`, and a git-ignored `.temp/data.db` SQLite file.
+
+   `lite dev` scaffolds the same structure on boot if it's missing, so you can skip straight to it in an empty directory. `lite start` requires the scaffold to exist — run `init` first.
+
+1. **Write your schema**
+
+   Write plain Postgres DDL in `supabase/schemas/schema.sql`. On the SQLite path it's translated automatically (`SERIAL` → `INTEGER PRIMARY KEY AUTOINCREMENT`, `NOW()` → `datetime('now')`, and so on).
+
+   A small per-user todos example with RLS enabled:
+
+   ```sql
+   create table todos (
+     id uuid primary key default gen_random_uuid(),
+     user_id uuid not null references auth.users(id) on delete cascade,
+     task text not null,
+     is_complete boolean not null default false,
+     created_at timestamptz not null default now()
+   );
+
+   alter table todos enable row level security;
+
+   create policy "select own todos" on todos for select to authenticated using (auth.uid() = user_id);
+   create policy "insert own todos" on todos for insert to authenticated with check (auth.uid() = user_id);
+   create policy "update own todos" on todos for update to authenticated using (auth.uid() = user_id) with check (auth.uid() = user_id);
+   create policy "delete own todos" on todos for delete to authenticated using (auth.uid() = user_id);
+   ```
+
+   Currently, default values using functions support is limited, therefore `DEFAULT auth.uid()` is not supported on the SQLite path. You must supply `user_id` by the client on insert; the `WITH CHECK` policy enforces ownership server-side. The `PATTERNS.md` file shipped in the package has more recipes.
+
+1. **Pick how you run it**
+
+   If your frontend uses Vite, use the [Vite plugin](/integrations/vite): it runs Supabase Lite inline in the Vite dev server, no separate process. Otherwise, use the `lite` CLI directly: see [Running Supabase Lite](/running) to choose between `lite dev` (auto schema-reload) and `lite start` (no watch, CI/prod-like).
+
+   <Tabs sync="pkg-manager">
+   <TabItem label="bun">
+   ```bash
+   bunx lite dev
+   ```
+   </TabItem>
+   <TabItem label="npm">
+   ```bash
+   npx lite dev
+   ```
+   </TabItem>
+   <TabItem label="pnpm">
+   ```bash
+   pnpm exec lite dev
+   ```
+   </TabItem>
+   </Tabs>
+
+   The API is now running at `http://127.0.0.1:54321`. `lite init` also generated a publishable/secret API key pair into root `.env` and printed them.
+
+1. **Create a client**
+
+   ```typescript
+   import { createClient } from "@supabase/supabase-js";
+
+   const supabase = createClient(
+     "http://127.0.0.1:54321",
+     "<sb_publishable_...>"
+   );
+   ```
+
+   Use the printed `sb_publishable_*` key as the anon key. If no keys are configured, `/rest/v1`/`/auth/v1` accept any/no `apikey` (unchanged old behavior). See [API keys](/auth/overview#api-keys).
+
+   If you're using the [Vite plugin](/integrations/vite) instead, the plugin injects `VITE_SUPABASE_URL` (`window.location.origin`) and a dev `VITE_SUPABASE_ANON_KEY`, so the canonical form works with no manual setup:
+
+   ```typescript
+   import { createClient } from "@supabase/supabase-js";
+
+   const supabase = createClient(
+     import.meta.env.VITE_SUPABASE_URL,
+     import.meta.env.VITE_SUPABASE_ANON_KEY,
+   );
+   ```
+
+1. **Run a query**
+
+   ```typescript
+   const { data: { session } } = await supabase.auth.getSession();
+
+   await supabase.from("todos").insert({
+     user_id: session.user.id,
+     task: "Ship the quickstart",
+   });
+
+   const { data, error } = await supabase.from("todos").select("*");
+   ```
+
+   This is standard `supabase-js`, no Supabase Lite-specific API. See [Compatibility](/compatibility) for what else is supported.
+
+</Steps>
+
+For the full Supabase quickstart flow (project structure, general CLI usage) that this mirrors, see the [Supabase local development guide](https://supabase.com/docs/guides/local-development).

package/docs/running.mdx

@@ -0,0 +1,127 @@
+---
+title: "Running Supabase Lite"
+description: "Choose between the Vite plugin, lite dev, lite start, and embedded/programmatic usage."
+---
+
+How you run Supabase Lite is a Supabase Lite-specific concept with no direct Supabase equivalent: since there's no Docker stack, "running Supabase locally" (see the [Supabase local development guide](https://supabase.com/docs/guides/local-development)) becomes a choice between running an in-process plugin, a small CLI server, or embedding the app directly in your own runtime.
+
+## Options at a glance
+
+| Mode | Process model | Schema reload | Best for |
+|---|---|---|---|
+| [Vite plugin](/integrations/vite) | In-process, mounted on the Vite dev server | Watches `schemas/*.sql` in `vite`/`vite dev`; not in `vite preview` or `vite build` | Any Vite frontend (React/Vue/Svelte/…). Recommended default if you're on Vite. |
+| `lite dev` | Separate process | Watches `schemas/*.sql`, auto-applies on change | Non-Vite apps during active development |
+| `lite start` | Separate process | None: no watch, no auto-migrate | CI, staging, or anything that should behave like production |
+| [Embedded / programmatic](/integrations/embedded) | In-process, inside your own Bun/Node/edge runtime | Manual: you call `createMigrator(...).migrate()` yourself | Custom servers, edge functions, or when you need full control over boot sequence |
+
+## Vite plugin
+
+If your frontend uses Vite, this is the recommended path: skip the separate CLI process entirely. The `@supabase/lite/vite` plugin mounts `/auth/v1`, `/rest/v1`, and `/_system` directly on the Vite dev server, so one process serves both your app and the API.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { supalite } from "@supabase/lite/vite";
+
+export default defineConfig({
+  plugins: [supalite()],
+});
+```
+
+Active in `vite` / `vite dev` (watches schemas, hot-reloads) and `vite preview` (mounts the API and runs boot migrations, but does not watch schemas, it simulates production). `vite build` and any standalone production server do not mount the API; use `lite start`, hosted Supabase, or an equivalent there.
+
+Full setup and env-var injection details: [Vite integration](/integrations/vite).
+
+## `lite dev`
+
+```bash
+lite dev
+```
+
+Starts the API server as its own process and watches `supabase/schemas/*.sql`, re-applying the schema automatically on every change. Use this for non-Vite apps (plain Node/Bun backends, mobile clients hitting a local API, etc.) during active development.
+
+Both CLI servers bind `127.0.0.1` by default. The host flag matches Vite: `--host` listens on `0.0.0.0`, while `--host <address>` selects a specific interface.
+
+```bash
+lite dev --host --no-admin   # reachable from containers/LAN; normal auth only
+```
+
+By default, auth emails (signup confirmation, magic link, password recovery, and so on) are printed to this server console rather than actually sent. See [Email delivery & templates](/auth/email).
+
+```bash
+lite db reset --hard   # delete the DB file, replay migrations + seed
+```
+
+## `lite start`
+
+```bash
+lite start
+```
+
+Starts the API server with no file watching and no auto-migration. This is the closest Supabase Lite gets to a production-like posture: you control exactly when migrations run (`lite migration up`, `lite db reset`), and the server won't silently reapply schema changes. Use this for CI pipelines and any environment meant to behave like production.
+
+On the `sqlite-postgres` driver, the ordered SQL in `supabase_migrations.schema_migrations` is the sole startup authority. `lite start` hashes the recorded `{version, statements}` values, restores a matching migration-derived `supabase/.temp/.runtime-metadata-cache.json`, or fully rebuilds fields, enums, constraints, comments, variables, relationships, RLS tables, and policies from that history. It never reads migration files or `supabase/schemas/*.sql`, so pending files and edits or deletions of already-applied files have no effect.
+
+The runtime metadata cache is disposable. Missing, corrupt, old, stale, or tampered files rebuild automatically. During a rebuild, Supabase Lite also replays the recorded SQL into an in-memory SQLite database and compares that raw structure with the live database. Invalid history or out-of-band structural DDL makes `lite start` exit with a `lite db reset` hint; live introspection is never used as a metadata source.
+
+`lite dev` and the Vite plugin remain declarative workflows: they apply pending migrations, reconcile the current `schemas/*.sql`, and replace runtime metadata from the schema they actually applied. `lite start` ignores that declarative state. If declarative changes made the live structure differ from applied migration history, generate a migration with `lite db diff -f <name>` and use `lite db reset` to establish a clean migration-derived database before running `lite start`.
+
+## Admin mode
+
+Loopback `lite dev`, `lite start`, and Vite dev listeners run with **admin mode on**. A request that arrives with no credential at all (no `apikey` header or query parameter, no `Authorization` header) is served as `service_role`, so a local admin UI like the built-in studio can read and edit any table without a secret key ever reaching the browser. This mirrors self-hosted Supabase Studio, where the Next.js server holds the service key and does the privileged work on the client's behalf.
+
+Elevation is deliberately narrow. A request is only elevated when all of these hold:
+
+- the path is under `/rest/v1` or `/storage/v1` (`/auth/v1` is never elevated). The Vite plugin does not mount `/storage/v1` by default, so there it's `/rest/v1` only
+- it carries no `apikey` and no `Authorization`
+- it is same-origin, or has no `Origin` header at all (so `curl` works, but another website open in your browser does not)
+- it arrived from a loopback socket **and** names a loopback host. Both are required: the peer address stops a machine on your network spoofing `Host: localhost`, and the hostname stops DNS rebinding, where a hostile page re-resolves its own domain to `127.0.0.1` so the socket really is loopback while `Host` and `Origin` stay theirs
+
+Anything else falls through to normal [API key enforcement](/auth/overview#api-keys).
+
+```bash
+lite start --no-admin          # loopback, admin explicitly off
+lite start --host              # all interfaces, admin defaults off and warns
+lite start --host --no-admin   # all interfaces, explicit/silent opt-out
+lite start --host --admin      # all interfaces, local peers retain admin
+```
+
+Two things to know:
+
+1. **Keyless traffic does not go through RLS while admin mode is on.** To exercise your policies, send an `apikey` — the publishable key for `anon`, or the publishable key **plus** `Authorization: Bearer <user JWT>` for `authenticated`. Those requests are never elevated, so both roles behave exactly as they do in production. That is the whole reason elevation is credential-aware rather than blanket. A bearer token on its own is not enough: with keys configured, a request without an `apikey` is rejected before RLS is reached (401 `UNAUTHORIZED_MISSING_API_KEY`), matching upstream.
+2. **Exposing a server changes the default.** A non-loopback `--host` disables admin mode unless `--admin` is explicit. With neither admin flag, Lite warns that exposure disabled admin and shows both choices. Vite applies the same rule when its resolved host is non-loopback.
+3. **A public tunnel erases locality.** A sandbox or tunnel can publish a loopback listener and forward traffic over a local socket. Run with `--no-admin` whenever another system exposes the port; socket locality cannot authenticate the original remote user through a proxy.
+
+On a loopback CLI listener, precedence is explicit `--admin`/`--no-admin`, then `options.server.admin`, then the on-by-default launcher value. A non-loopback `--host` forces admin off unless `--admin` is present, so config cannot silently re-enable it. For Vite, an exposed host similarly requires the explicit `supalite({ admin: true })` option.
+
+Embedding `App` without request context applies only the hostname check. An adapter that owns a listener should call `app.fetch(request, { peerAddress })`; a null peer fails closed. Only enable admin on a loopback-bound server.
+
+With admin mode off, the bundled studio connects with the publishable key instead and shows you what `anon` can see under RLS, with a banner saying so — it stays usable, just scoped.
+
+## Embedded / programmatic
+
+For full control, skip the CLI entirely and embed the app directly in your own Bun, Node, browser, or edge runtime:
+
+```typescript
+import { App } from "@supabase/lite";
+import { createConnection } from "@supabase/lite/sqlite";
+
+const connection = await createConnection({ url: "file:./data.db" });
+const app = new App({ connection, auth: { enabled: true } });
+
+const schema = await Bun.file("./schema.sql").text();
+await app.connection.createMigrator(schema).migrate();
+
+export default app; // app.fetch handles requests
+```
+
+This is the path for custom server frameworks, Cloudflare Workers/Durable Objects, or any setup where you need to control the boot sequence yourself rather than delegating to the CLI or the Vite plugin. See [Embedded / programmatic](/integrations/embedded) for supported runtimes and drivers.
+
+## Choosing
+
+- Building a Vite app? Use the [Vite plugin](/integrations/vite). Stop here.
+- Building anything else, and want schema changes to apply automatically while you iterate? Use `lite dev`.
+- Deploying, running in CI, or want explicit control over migrations? Use `lite start`.
+- Building your own server, or targeting a runtime the CLI doesn't drive directly (Workers, Durable Objects)? Use the [embedded API](/integrations/embedded).
+
+Whichever mode you pick, run exactly one backend per project. Never run `lite dev` and `lite start` together, or either alongside the Vite plugin. Two backends over the same SQLite file race migrations and schema watchers even when they do not share a port.

package/docs/storage/adapters.mdx

@@ -0,0 +1,75 @@
+---
+title: "Storage adapters"
+description: "Pluggable storage backends (filesystem, S3-compatible) and transformation adapters (Noop, Sharp, Cloudflare) for Supabase Lite Storage."
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Supabase Lite's Storage API separates *where bytes live* (storage adapters) from *how images get resized* (transformation adapters). Both are supabase-js-invisible: the same `supabase.storage.from(...).upload()` call works no matter which adapter is wired up server-side. This adapter split is a Supabase Lite-specific implementation detail; there's no equivalent concept to configure in hosted Supabase.
+
+<Aside type="note">
+Storage is experimental. See [Storage overview](/storage/overview) for the `EXPERIMENTAL_STORAGE` flag and the config required before any adapter matters.
+</Aside>
+
+## Storage adapters
+
+Where object bytes are physically stored.
+
+| Adapter | Status | Notes |
+|---|---|---|
+| Filesystem | Supported | Local disk. Default for `lite dev` / `lite start` under `.temp/storage`. |
+| S3 / S3-compatible | Supported | MinIO, AWS S3, Cloudflare R2, via [`aws4fetch`](https://github.com/lquixada/aws4fetch), not the AWS SDK. |
+| Cloudflare R2 | Supported | Uses the S3 adapter with R2's S3-compatible endpoint. |
+
+### Filesystem
+
+Set programmatically on the `App` instance:
+
+```ts
+import { FilesystemStorageAdapter } from "@supabase/lite/storage/adapters/FilesystemStorageAdapter";
+
+app._storageAdapter = new FilesystemStorageAdapter({
+  basePath: "./supabase/.temp/storage",
+});
+```
+
+This is what the `lite` CLI wires up automatically when `EXPERIMENTAL_STORAGE=1` and `storage.enabled` are set: object bytes land under `<config_dir>/.temp/storage/<bucket>/<key>`.
+
+### S3-compatible
+
+```ts
+import { S3StorageAdapter } from "@supabase/lite/storage/adapters/S3StorageAdapter";
+
+app._storageAdapter = new S3StorageAdapter({
+  accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+  endpoint: "https://<account>.r2.cloudflarestorage.com",
+  region: "auto",
+  bucket: "my-bucket",       // optional: scope all operations to one S3 bucket
+  forcePathStyle: true,       // required for MinIO and some S3-compatible providers
+});
+```
+
+`endpoint` and `region` point at whichever S3-compatible provider you use (AWS S3, MinIO, Cloudflare R2). `forcePathStyle` switches between virtual-hosted-style and path-style URLs; enable it for MinIO and most self-hosted S3-compatible servers.
+
+For the S3 API surface this adapter targets on the wire, see [Supabase Storage S3 compatibility](https://supabase.com/docs/guides/storage/s3/compatibility). Note that's about Supabase's own S3-compatible *server* endpoint, which Supabase Lite does not yet implement server-side (see [Storage limitations](/storage/limitations)); this adapter is Supabase Lite acting as an S3 *client* to store bytes remotely.
+
+## Transformation adapters
+
+How (and whether) images get resized/reformatted on read.
+
+| Adapter | Status | Notes |
+|---|---|---|
+| Noop | Supported | Passthrough: no transforms, returns the original bytes. Default. |
+| Sharp | Supported | Resize + format conversion via [`sharp`](https://sharp.pixelplumbing.com/), in-process. Requires `sharp` as an optional dependency in your project. |
+| Cloudflare | Supported | Delegates to [Cloudflare Image Resizing](https://developers.cloudflare.com/images/transform-images/transform-via-workers/) via `fetch` with `cf.image` options; no image-processing library, works in Workers. |
+
+```ts
+import { SharpTransformationAdapter } from "@supabase/lite/storage/transformations/SharpTransformationAdapter";
+
+app._transformationAdapter = new SharpTransformationAdapter();
+```
+
+Pick Sharp for Node/Bun deployments where you want image transforms without an external image proxy, and Cloudflare's adapter when running on Workers, where Cloudflare's edge already handles resizing and a native image library isn't available. Leave the default Noop adapter if you don't need `?width=`/`?height=` transforms at all.
+
+For the transform options themselves (`width`, `height`, `resize`, `format`, `quality`) and how they're requested from the client, see [Supabase image transformations](https://supabase.com/docs/guides/storage/serving/image-transformations).

package/docs/storage/limitations.mdx

@@ -0,0 +1,21 @@
+---
+title: "Storage limitations"
+description: "What's not yet implemented in Supabase Lite Storage: TUS uploads, webhooks, bucket-list query params, and the S3-compatible server protocol."
+---
+
+Storage is [experimental](/storage/overview) and behind the `EXPERIMENTAL_STORAGE` flag. Everything below is a gap on top of that: even with the flag on and an adapter wired up, these features don't exist yet.
+
+## Not yet implemented
+
+| Feature | Notes |
+|---|---|
+| Bucket list query params | `GET /bucket` doesn't yet accept `?search=`, `?limit=`, `?offset=`. |
+| S3-compatible protocol (server side) | No `PUT`/`GET`/`DELETE` under `/storage/v1/s3/*`. Supabase Lite can act as an S3 *client* via the [S3 storage adapter](/storage/adapters), but doesn't expose an S3-compatible server. |
+| TUS resumable uploads | No `POST`/`PATCH`/`HEAD` on `/upload/resumable`. |
+| Webhooks | No `ObjectCreated`/`ObjectRemoved` event delivery. |
+
+## Workaround
+
+For any of the above, run the storage-dependent parts of your app against hosted Supabase and keep the rest (Data API, Auth) on Supabase Lite. Mixed backends are a normal transitional setup, not something you need to migrate wholesale for.
+
+For Storage access-control policies, see [Supabase Storage access control](https://supabase.com/docs/guides/storage/security/access-control); Supabase Lite supports that model across SQLite, PGlite, and PostgreSQL. For what is implemented today, see [Storage overview](/storage/overview) and [Storage adapters](/storage/adapters).