@mantajs/core 0.2.0-beta.1 → 0.2.0-beta.10

package/docs/06-queries.md

@@ -1,14 +1,17 @@
-# Queries — defineQuery() & defineQueryGraph()
+# Queries — Drizzle-first defineQuery()
 
-Queries are the CQRS read side. They expose data as GET endpoints. Two primitives:
+Queries are the CQRS read side. They expose data as GET endpoints.
 
-- `defineQuery()` — named query with custom handler (specific reads)
-- `defineQueryGraph()` — expose the query graph to frontend (flexible reads)
+- `defineQuery()` is the primary application API. New code should query with the schema-aware Drizzle client.
+- `defineQueryGraph()` is reserved for generated/admin/dynamic surfaces that need entity-level browsing.
+
+Manta does not try to replace SQL. `defineModel()` generates the Drizzle schema and migrations; `defineQuery()` gives handlers the Drizzle client, generated schema, tagged SQL helper, auth context, logging, and request headers.
 
 ## defineQuery()
 
 ```typescript
 // src/queries/admin/list-products.ts
+import { eq } from 'drizzle-orm'
 import { z } from 'zod'
 
 export default defineQuery({
@@ -18,12 +21,19 @@ export default defineQuery({
     status: z.string().optional(),
     ...listParams(),
   }),
-  handler: async (input, { query, log, auth, headers }) => {
-    return query.graph({
-      entity: 'product',
-      filters: input.status ? { status: input.status } : undefined,
-      pagination: { take: input.limit, skip: input.offset },
-    })
+  handler: async (input, { drizzle, schema, sql }) => {
+    const products = schema.products
+    return drizzle
+      .select({
+        id: products.id,
+        title: products.title,
+        status: products.status,
+        totalVariants: sql<number>`count(*) over()::int`,
+      })
+      .from(products)
+      .where(input.status ? eq(products.status, input.status) : undefined)
+      .limit(input.limit)
+      .offset(input.offset)
   },
 })
 ```
@@ -43,14 +53,21 @@ defineQuery({
 
 ```typescript
 {
-  query: QueryService,                          // query.graph() for cross-module joins
+  drizzle: unknown,                             // schema-aware Drizzle client
+  db: unknown,                                  // alias for drizzle
+  schema: Record<string, unknown>,              // generated Drizzle tables
+  sql: typeof import('drizzle-orm').sql,        // tagged SQL helper
+  database: IDatabasePort,                      // raw SQL, pool, transactions
+  query: QueryService,                          // generated/admin query graph
   log: ILoggerPort,                             // Structured logging
   auth: AuthContext | null,                     // Authenticated user
   headers: Record<string, string | undefined>,  // Raw request headers
 }
 ```
 
-**No `app` access** — queries are forced to use `query.graph()` for reads. This ensures consistent access control.
+Prefer Drizzle for all application reads, including simple lists, dashboards, analytics, counts, search, and joins. Use `sql` fragments when a PostgreSQL feature is clearer than query-builder syntax.
+
+`query.graph()` remains available for generated admin screens and dynamic entity browsing. It must not be used to hide analytical work in JavaScript. If a query needs `COUNT`, `SUM`, `GROUP BY`, `FILTER`, CTEs, window functions, full-text search, or dashboard KPIs, write it as Drizzle/SQL in `defineQuery()`.
 
 ### Routing
 
@@ -65,6 +82,18 @@ Query parameters are passed as URL query string:
 GET /api/admin/list-products?status=active&limit=10&offset=0
 ```
 
+### Serverless fast routes
+
+For serverless and worker builds, Manta generates route-level functions for compatible `defineQuery()` files. These fast routes do not import `bootstrapApp()`, jobs, workflows, AI, command registries, or the catch-all Manta adapter.
+
+Fast routes are generated when:
+
+- the project uses filesystem V2 contexts (`src/queries/{context}`), not legacy `src/contexts/*.ts`
+- the file exports `defineQuery()`, not `defineQueryGraph()`
+- the query does not call `query.graph()`, `query.graphAndCount()`, `query.index()`, or `query.gql()`
+
+Pure synthetic queries do not initialize the database or generated schema. Queries that reference `drizzle`, `db`, `schema`, or `database` initialize only the DB adapter and generated Drizzle schema needed by the handler.
+
 ### Input helpers
 
 ```typescript
@@ -85,22 +114,24 @@ z.object({
 ### Auth in queries
 
 ```typescript
-handler: async (input, { query, auth }) => {
+handler: async (input, { drizzle, schema, auth }) => {
   // auth.id — user ID
   // auth.type — context ('admin', 'customer')
   // auth.email — user email
 
   // Example: only return MY orders
-  return query.graph({
-    entity: 'order',
-    filters: { customer_id: auth!.id },
-  })
+  return drizzle
+    .select()
+    .from(schema.orders)
+    .where(eq(schema.orders.customer_id, auth!.id))
 }
 ```
 
 ## defineQueryGraph()
 
-Exposes the query graph to the frontend. The frontend can compose arbitrary queries.
+Exposes the query graph to the frontend. The frontend can compose entity browsing queries for generated/admin screens.
+
+Do not use the graph as the main application query language. It is intentionally less expressive than SQL. Complex reads belong in `defineQuery()` with Drizzle.
 
 ### Wildcard — full access (admin/AI)
 
@@ -163,11 +194,11 @@ POST /api/admin/graph
 
 | Use case | Primitive | Why |
 |----------|-----------|-----|
-| Admin dashboard | `defineQueryGraph('*')` | Admin sees everything, AI needs full access |
-| Storefront public catalog | `defineQueryGraph({ product: true })` | Frontend composes queries freely, scoped |
-| Storefront orders | `defineQuery` or scoped graph | Need row-level filtering by customer |
-| Complex aggregation | `defineQuery` | Custom handler with business logic |
-| API for third parties | `defineQuery` | Fixed contract, no graph exposure |
+| Generated admin entity table | `defineQueryGraph('*')` | Dynamic browsing over known entities |
+| Storefront catalog | `defineQuery` | Stable contract, optimized Drizzle query |
+| Customer orders | `defineQuery` | Auth-scoped SQL with explicit filters |
+| Dashboard / analytics | `defineQuery` | Aggregations run in Postgres |
+| Third-party API | `defineQuery` | Fixed contract, no graph exposure |
 
 ## extendQueryGraph() — external entity resolvers
 

package/docs/10-spa.md

@@ -34,7 +34,13 @@ src/spa/admin/
 - **`.ts`** — exports `definePage()` or `defineForm()` spec (declarative, no React)
 - **`.tsx`** — exports a React component (full control, for complex cases)
 
-**Defaults**: `@mantajs/dashboard` shell + `@mantajs/ui` preset. Override in config if needed:
+**Defaults**: `@mantajs/dashboard` shell + `@mantajs/ui` preset. The generated entry imports the public stylesheet export:
+
+```typescript
+import '@mantajs/dashboard/index.css'
+```
+
+Override in config if needed:
 
 ```typescript
 // manta.config.ts — optional, only for overrides
@@ -46,6 +52,62 @@ export default defineConfig({
 })
 ```
 
+### Mount path
+
+By default, a SPA named `admin` is mounted at `/admin`:
+
+| Generated setting | Default for `src/spa/admin` |
+| --- | --- |
+| React Router basename | `/admin` |
+| Vite `base` | `/admin/` |
+| Static output | `public/admin` |
+| Vercel SPA rewrite | `/admin/:path*` → `/admin/index.html` |
+
+Use `mountPath: '/'` for a dashboard on a dedicated subdomain, such as `admin.fancypalas.com/paniers`:
+
+```typescript
+// manta.config.ts
+export default defineConfig({
+  spa: {
+    admin: { mountPath: '/' },
+  },
+})
+```
+
+With `mountPath: '/'`, React Router uses `basename="/"`, Vite uses `base: '/'`, the SPA builds into `public/`, and generated Vercel rewrites exclude `/api/*`.
+
+### Dev Vite port
+
+`manta dev` starts one Vite server per detected SPA. Ports default to `5200`, then increment for additional SPAs.
+
+Configure the port in `manta.config.ts` when another project already uses the default:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: { vitePort: 5310 },
+  },
+})
+```
+
+Environment overrides are also supported:
+
+```bash
+MANTA_VITE_PORT=5310 manta dev
+MANTA_VITE_PORT_ADMIN=5311 manta dev
+```
+
+The SPA-specific variable wins over the global one. The suffix uses the SPA name uppercased with non-alphanumeric characters replaced by `_`.
+
+### Local production fallback
+
+`manta build` writes a SPA fallback manifest into `.manta/server/spa-manifest.ts`. For the Node preset, `manta start` uses it to mirror the Vercel SPA behavior locally:
+
+- `/` redirects to the single SPA mount path when the SPA is not mounted at `/`
+- `/login`, `/reset-password`, and `/accept-invite` redirect under that mount path
+- `/admin/*` and other configured SPA mount paths serve the built `index.html`
+- `/api/*` and asset URLs remain server-side/static and are not swallowed by the SPA fallback
+
 ---
 
 ## SPA Configuration — defineSpa()

package/docs/11-config.md

@@ -17,12 +17,15 @@ Creates a complete, functional Manta project. After `pnpm install`, the project
 
 ```
 my-app/
-├── manta.config.ts           # defineConfig() — database, http, admin: true
+├── manta.config.ts           # defineConfig() — database, http, spa, presets
+├── nitro.config.ts           # Nitro host config for standalone builds
 ├── package.json              # @mantajs/core, @mantajs/cli, @mantajs/host-nitro, @mantajs/dashboard
 ├── tsconfig.json             # ES2022, ESNext, JSX support, strict
 ├── .env / .env.example       # DATABASE_URL, PORT, ANTHROPIC_API_KEY
-├── .gitignore                # .manta/, .manta/types/, node_modules/, .env
+├── .gitignore                # .manta/, node_modules/, .env
 ├── AGENT.md                  # AI instructions (copied from @mantajs/core/docs/)
+├── .codex/skills/mantajs/    # Codex skill pointing to the shipped Manta docs
+├── .claude/skills/mantajs/   # Claude skill pointing to the same docs
 └── src/
     ├── modules/              # Your business modules (entities + services)
     ├── commands/              # Application commands (cross-module workflows)
@@ -31,48 +34,44 @@ my-app/
     ├── links/                 # Cross-module relations
     ├── queries/               # CQRS read endpoints (defineQuery, defineQueryGraph)
     ├── agents/                # AI steps
-    └── admin/                 # Dashboard (index.html + main.tsx)
-        ├── index.html
-        └── main.tsx
+    └── spa/admin/             # Dashboard SPA pages, config, blocks
+        ├── config.ts
+        ├── pages/
+        └── blocks/
 ```
 
 **What it does NOT generate:**
-- No `nitro.config.ts` — the host adapter handles this internally
 - No `drizzle.config.ts` — the CLI handles this internally
 - No `src/api/` — routes are auto-generated from commands + queries
 
-The only config file the developer maintains is `manta.config.ts`.
+The developer normally maintains `manta.config.ts`, `nitro.config.ts` only when deployment/static asset behavior needs customization, and the generated `AGENT.md` when project-specific conventions need to be added.
 
-### `manta setup` — Add Manta to existing project
+### Existing projects
+
+The current CLI does not expose a separate `manta setup` command. Existing projects should install or update the Manta packages, keep a `manta.config.ts` at the project root, then run:
 
 ```bash
-cd my-nextjs-app
-npx manta setup
+manta dev
 ```
 
-Detects the existing framework and adapts:
-
-| Detected | Context | What it generates |
-|----------|---------|------------------|
-| `next.config.*` | Next.js | `AGENT.md` with Next.js + Manta instructions, `src/manta/` subdirectory |
-| `nuxt.config.*` | Nuxt | `AGENT.md` with Nuxt + Manta instructions, `server/manta/` subdirectory |
-| `workspaces` in package.json | Monorepo | `AGENT.md` at root, `packages/backend/` with Manta structure |
-| Nothing detected | Standalone | Full Manta project structure in current directory |
+`manta dev` refreshes **`.codex/skills/mantajs/SKILL.md`** and **`.claude/skills/mantajs/SKILL.md`** from the installed `@mantajs/core` package before boot validation. This keeps Codex and Claude pointed at the docs shipped in `node_modules/@mantajs/core/docs/` even when a project already existed before the current framework version.
 
-In all cases, `manta setup`:
-1. Creates `manta.config.ts`
-2. Creates module/command/subscriber directories
-3. Generates **`AGENT.md` at the project root** — the first file an AI reads
-4. The `AGENT.md` is context-aware (mentions the detected framework)
-5. `AGENT.md` is committed to git (not gitignored) — every clone has it
-
-### The AGENT.md
+### Agent docs and Codex skill
 
 The `AGENT.md` lives at the root of every Manta project. It's the first file an AI reads.
 
 **Canonical location:** `@mantajs/core/docs/AGENT.md` — alongside all other framework documentation. The CLI copies it to the project root during `manta init`.
 
-For `manta setup` (existing projects), context-specific templates exist in the CLI:
+The Codex skill is intentionally separate and smaller:
+
+```
+.codex/skills/mantajs/SKILL.md
+.claude/skills/mantajs/SKILL.md
+```
+
+It is copied from `@mantajs/core/skills/mantajs/SKILL.md` and tells Codex/Claude to load the relevant file from `node_modules/@mantajs/core/docs/` before changing Manta code. It is not installed with an npm `postinstall` hook; `manta init` creates it and `manta dev` refreshes it so existing projects stay aligned with the installed framework docs.
+
+For future setup flows and framework-specific projects, context-specific templates exist in the CLI:
 
 ```
 packages/cli/src/templates/agent/
@@ -80,7 +79,7 @@ packages/cli/src/templates/agent/
 └── nuxt.md          # Nuxt + Manta
 ```
 
-`manta init` copies the canonical AGENT.md from `@mantajs/core/docs/`. `manta setup` detects the context and uses the appropriate template. The developer can then edit it to add project-specific context (business domain, team conventions, etc.).
+`manta init` copies the canonical AGENT.md from `@mantajs/core/docs/`. Framework-specific templates can be used by future setup flows or custom scaffolding. The developer can then edit the project AGENT.md to add project-specific context (business domain, team conventions, etc.).
 
 Each AGENT.md contains:
 - Stack description (what framework + Manta)
@@ -100,7 +99,9 @@ export default {
     pool: { min: 2, max: 10 },
   },
   http: { port: 3000 },
-  admin: { enabled: true },
+  spa: {
+    admin: {}, // mounted at /admin by default
+  },
 }
 ```
 
@@ -113,7 +114,12 @@ export default defineConfig({
   auth: {
     jwtSecret: process.env.JWT_SECRET,
   },
-  admin: { enabled: true },
+  spa: {
+    admin: {
+      // Default mount path is "/admin"; use "/" for admin.example.com routes.
+      mountPath: '/admin',
+    },
+  },
   strict: false,
 })
 ```
@@ -127,12 +133,61 @@ export default defineConfig({
 | `database` | `url`, `pool.min`, `pool.max` | Required |
 | `http` | `port` | `9000` |
 | `auth` | `jwtSecret`, `session.enabled`, `session.cookieName` | Dev: auto-generated secret |
-| `query` | `maxEntities`, `defaultLimit` | `10000`, `100` |
-| `admin` | `enabled` | `false` |
-| `preset` | `'dev'`, `'vercel'` | Auto-detected from `APP_ENV` |
+| `query` | `maxTotalEntities` | `10000` |
+| `admin` | Reserved legacy object | `{}` |
+| `spa` | `{ [name]: { dashboard, preset, mountPath, vitePort } }` | Auto-detected from `src/spa/{name}` |
+| `preset` | `'dev'`, `'vercel'`, custom preset object | Auto-detected from `APP_ENV` |
 | `strict` | `true`/`false` | `false` |
 | `plugins` | Array of plugin configs | `[]` |
 
+### SPA mount path
+
+Standalone/Nitro SPAs are discovered from `src/spa/{name}/`. By default, the public mount path is `/{name}`:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: {}, // mounted at /admin
+  },
+})
+```
+
+For a dedicated admin subdomain such as `admin.fancypalas.com`, mount the SPA at the root:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: { mountPath: '/' },
+  },
+})
+```
+
+With `mountPath: '/'`, the Vite SPA uses `base: '/'`, builds into `public/`, and generated Vercel rewrites exclude `/api/*` so API routes remain server-side.
+
+### SPA dev port
+
+`manta dev` starts SPA Vite servers at `5200`, then increments for additional SPAs. Use `vitePort` when a local project already owns that port:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: {
+      mountPath: '/admin',
+      vitePort: 5310,
+    },
+  },
+})
+```
+
+Environment overrides are supported for temporary local conflicts:
+
+```bash
+MANTA_VITE_PORT=5310 manta dev
+MANTA_VITE_PORT_ADMIN=5311 manta dev
+```
+
+Precedence is `spa.{name}.vitePort`, then `MANTA_VITE_PORT_{NAME}`, then `MANTA_VITE_PORT`, then the default sequence.
+
 ## Presets (adapter bundles)
 
 The framework auto-detects the environment and loads appropriate adapters:
@@ -149,6 +204,64 @@ The framework auto-detects the environment and loads appropriate adapters:
 
 Detection: `APP_ENV` > `NODE_ENV` > default `'development'`.
 
+### Vercel Blob access
+
+The Vercel preset wires `IFilePort` to `@mantajs/adapter-file-vercel-blob`. The adapter defaults to `access: 'public'` for compatibility with existing stores. For sensitive files, create a private Vercel Blob store and configure the adapter explicitly:
+
+```typescript
+export default defineConfig({
+  preset: 'vercel',
+  adapters: {
+    IFilePort: {
+      adapter: '@mantajs/adapter-file-vercel-blob',
+      options: {
+        access: 'private',
+        signedUrlExpiresInSeconds: 300,
+      },
+    },
+  },
+})
+```
+
+Private file reads use Vercel Blob's server-side `get()` API via `getDownloadStream()`/`getAsBuffer()`. If the application needs a browser URL, `getPresignedDownloadUrl()` returns a short-lived signed URL instead of exposing the private Blob URL directly.
+
+### Durable cache for auth revocation
+
+Production auth uses `ICachePort` for logout token revocation, refresh-token blacklist checks, reset flows, and session state. The Vercel and Cloudflare presets default to Upstash:
+
+```typescript
+export default defineConfig({
+  preset: 'vercel',
+  adapters: {
+    ICachePort: {
+      adapter: '@mantajs/adapter-cache-upstash',
+      options: {
+        url: process.env.UPSTASH_REDIS_REST_URL,
+        token: process.env.UPSTASH_REDIS_REST_TOKEN,
+      },
+    },
+  },
+})
+```
+
+If Upstash REST credentials are not available or not reliable in the deployment runtime, use the Postgres-backed cache adapter:
+
+```typescript
+export default defineConfig({
+  preset: 'vercel',
+  adapters: {
+    ICachePort: {
+      adapter: '@mantajs/adapter-database-pg/cache',
+      options: {
+        tableName: 'manta_cache',
+      },
+    },
+  },
+})
+```
+
+The Postgres cache reuses the configured `IDatabasePort` connection when bootstrapped by the Manta CLI and creates the cache table automatically by default.
+
 ## Environment variables
 
 | Variable | Required | Description |
@@ -156,6 +269,8 @@ Detection: `APP_ENV` > `NODE_ENV` > default `'development'`.
 | `DATABASE_URL` | Yes | PostgreSQL connection string |
 | `JWT_SECRET` | Prod only | JWT signing secret (dev: auto-generated) |
 | `APP_ENV` | No | Force environment (`development` or `production`) |
+| `UPSTASH_REDIS_REST_URL` | Prod when using Upstash cache | Upstash Redis REST endpoint |
+| `UPSTASH_REDIS_REST_TOKEN` | Prod when using Upstash cache | Upstash Redis REST token |
 | `ANTHROPIC_API_KEY` | No | Enable AI chat in admin dashboard |
 
 ## CLI commands
@@ -178,15 +293,21 @@ Detection: `APP_ENV` > `NODE_ENV` > default `'development'`.
 
 Starts development server. Auto-performs:
 1. Load env + config
-2. Generate `.manta/types/` (TypeScript types for autocomplete)
+2. Generate `.manta/generated.d.ts` (TypeScript types for autocomplete)
 3. Start Nitro dev server with HMR
 4. On first request: connect DB, instantiate adapters, discover modules/commands/subscribers/jobs/links/queries
 5. Auto-create tables in dev mode (no manual migration needed)
 6. Wire all routes, subscribers, jobs
 
+### manta build --preset vercel
+
+For Vercel deployments, `manta build --preset vercel` generates the framework-owned SPA rewrites and cron routes in `vercel.json`.
+
+If `vercel.json` already exists, Manta preserves custom top-level project settings such as `buildCommand`, `installCommand`, `outputDirectory`, `functions`, `headers`, and other Vercel options. It also preserves custom `redirects`, `rewrites`, and `crons` unless they collide on the same `source` or `path` as a framework-generated entry.
+
 ### manta db:generate
 
-Scans `src/modules/*/models/` and `src/links/` to generate SQL migrations:
+Scans entity definitions from `src/modules/*/entities/` and relation links from `src/links/` to generate SQL migrations:
 
 ```bash
 manta db:generate --name add-blog-post
@@ -212,15 +333,13 @@ manta exec scripts/seed.ts
 manta exec scripts/seed.ts --dry-run  # Rollback after execution (test mode)
 ```
 
-## Codegen (.manta/types/)
+## Codegen (`.manta/generated.d.ts`)
 
 On `manta dev` or `manta build`, the framework generates:
 
 | File | Content |
 |------|---------|
-| `types.ts` | `MantaEntities` — typed step proxy for `step.service.catalog.create()` |
-| `app.d.ts` | `MantaAppModules` — typed `app.modules.catalog.listProducts()` |
-| `events.d.ts` | `MantaEventName` — union of all known event names |
+| `.manta/generated.d.ts` | `MantaEntities`, `MantaAppModules`, `MantaEventName`, and module augmentation used by IDE autocomplete |
 
 These are TypeScript module augmentations. After codegen, `app.modules.*` has full autocomplete in your IDE.
 

package/docs/14-adapters.md

@@ -8,7 +8,7 @@ Every infrastructure concern is abstracted behind a port. Here are all ports you
 
 | Port | Responsibility | Dev adapter | Prod adapter |
 |------|---------------|-------------|--------------|
-| `ICachePort` | Key-value cache | InMemoryCacheAdapter | UpstashCacheAdapter |
+| `ICachePort` | Key-value cache | InMemoryCacheAdapter | UpstashCacheAdapter, PostgresCacheAdapter |
 | `IEventBusPort` | Event pub/sub | InMemoryEventBusAdapter | Upstash Queues |
 | `IFilePort` | File storage | InMemoryFileAdapter | VercelBlobAdapter |
 | `ILoggerPort` | Structured logging | TestLogger | PinoLoggerAdapter |
@@ -67,6 +67,25 @@ export class RedisCacheAdapter implements ICachePort {
 }
 ```
 
+## Built-in durable Postgres cache
+
+When Redis/Upstash is not desirable, `@mantajs/adapter-database-pg` exposes a durable cache adapter:
+
+```typescript
+export default defineConfig({
+  adapters: {
+    ICachePort: {
+      adapter: '@mantajs/adapter-database-pg/cache',
+      options: {
+        tableName: 'manta_cache',
+      },
+    },
+  },
+})
+```
+
+The CLI factory reuses the active `IDatabasePort` Postgres connection. This adapter is appropriate for auth logout/reset/session revocation state where durability matters more than sub-millisecond Redis latency.
+
 ### 2. Create the barrel export
 
 ```typescript
@@ -131,8 +150,17 @@ interface IEventBusPort {
 ### IFilePort
 
 ```typescript
+type FileAccess = 'public' | 'private'
+
+interface FileUploadResult {
+  key: string
+  url: string
+  access?: FileAccess
+  downloadUrl?: string
+}
+
 interface IFilePort {
-  upload(key: string, data: Buffer | ReadableStream, contentType?: string): Promise<{ key: string; url: string }>
+  upload(key: string, data: Buffer | ReadableStream, contentType?: string): Promise<FileUploadResult>
   delete(key: string | string[]): Promise<void>
   getPresignedDownloadUrl(key: string): Promise<string>
   getDownloadStream(key: string): Promise<ReadableStream>
@@ -141,6 +169,28 @@ interface IFilePort {
 }
 ```
 
+#### Vercel Blob access mode
+
+`@mantajs/adapter-file-vercel-blob` supports both Vercel Blob access modes:
+
+```typescript
+export default defineConfig({
+  adapters: {
+    IFilePort: {
+      adapter: '@mantajs/adapter-file-vercel-blob',
+      options: {
+        access: 'private',
+        signedUrlExpiresInSeconds: 300,
+      },
+    },
+  },
+})
+```
+
+`access: 'public'` is the default for backward compatibility and should be reserved for public assets. For sensitive admin files, snapshots, invoices, or user content, use a Vercel Blob store created as private and set `access: 'private'`.
+
+Private blobs are read through the server SDK in `getDownloadStream()` and `getAsBuffer()`, so the read-write token is never sent to the browser. `getPresignedDownloadUrl()` returns a short-lived signed URL for private blobs. You can also set `MANTA_VERCEL_BLOB_ACCESS=private` or `MANTA_FILE_ACCESS=private` when configuring through environment variables.
+
 ### ILockingPort
 
 ```typescript

package/docs/15-hosts.md

@@ -17,6 +17,8 @@ Manta ships with a Nitro host (`packages/host-nitro/`). It:
 - Handles the catch-all route `server/routes/[...].ts`
 - Passes requests through to Manta's 12-step pipeline
 
+For serverless and worker production builds, Nitro also receives generated route-level `defineQuery()` handlers under `server/routes/api/{context}/{query}.ts` when the query is compatible with the fast runtime. Those handlers bypass the catch-all route and do not call `bootstrapApp()`. The catch-all remains the fallback for command graphs, query graphs, workflows, custom API routes, auth routes, cron routes, and legacy context setups.
+
 ## Creating a custom host
 
 ### Example: Express host
@@ -33,7 +35,7 @@ export async function startExpressHost(options: { port?: number; cwd?: string }
   // Bootstrap the Manta app (same as manta dev / manta start)
   const { app, adapter, logger, shutdown } = await bootstrapApp({
     cwd,
-    mode: 'production',
+    mode: 'prod',
   })
 
   // Create Express app
@@ -84,7 +86,7 @@ let bootstrapped: Awaited<ReturnType<typeof bootstrapApp>> | null = null
 export async function handler(event: APIGatewayProxyEventV2) {
   // Cold start: bootstrap once
   if (!bootstrapped) {
-    bootstrapped = await bootstrapApp({ cwd: process.cwd(), mode: 'production' })
+    bootstrapped = await bootstrapApp({ cwd: process.cwd(), mode: 'prod' })
   }
 
   // Translate Lambda event to Web Request
@@ -117,6 +119,19 @@ A host must:
 
 The H3Adapter's `handleRequest(request: Request): Promise<Response>` is the single entry point. It runs the full 12-step pipeline (auth, validation, routing, error handling).
 
+## Production bootstrap mode
+
+Production hosts must call `bootstrapApp()` with `mode: 'prod'`. Development tooling uses `mode: 'dev'`.
+
+The Nitro production build generated by `@mantajs/host-nitro` writes a production bootstrap with `mode: 'prod'` for both manifest-based builds and runtime-discovery fallback builds. This matters because production error handling must not expose development stack traces.
+
+For the Node preset, the generated Nitro catch-all route calls the Manta API first, then serves SPA fallbacks from the built static output when the API returns `404` for a `GET` request. This mirrors the generated Vercel routing locally:
+
+- `/` redirects to the single SPA mount path when there is one SPA mounted away from `/`
+- `/login`, `/reset-password`, and `/accept-invite` redirect under that mount path
+- SPA subroutes such as `/admin/login` return the built `index.html`
+- `/api/*` and file-extension asset paths are never handled by the SPA fallback
+
 ## What the pipeline provides
 
 Every request passing through `adapter.handleRequest()` goes through: