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

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:

package/docs/16-reference.md

@@ -58,7 +58,7 @@ function defineLink(
 ): ResolvedLink
 ```
 
-### defineContext(config)
+### defineContext(config) — legacy
 
 ```typescript
 function defineContext(config: {
@@ -71,12 +71,32 @@ function defineContext(config: {
 }): ContextDefinition
 ```
 
+`defineContext()` is kept for legacy compatibility. New Manta apps should use filesystem contexts: `src/commands/{context}/` and `src/queries/{context}/` map to `/api/{context}/...`.
+
 ### defineConfig(config?)
 
 ```typescript
 function defineConfig(config?: Partial<MantaConfig>): MantaConfig
 ```
 
+Common SPA config shape:
+
+```typescript
+type SpaConfig = {
+  dashboard?: string | null // default: '@mantajs/dashboard'; null disables the shell
+  preset?: string | null    // default: '@mantajs/ui'; null disables the preset
+  mountPath?: string | null // default: /{spaName}; use '/' for root-mounted SPA
+}
+```
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: { mountPath: '/' },
+  },
+})
+```
+
 ## Helpers
 
 ### field property types
@@ -102,7 +122,7 @@ Modifiers: `.nullable()`, `.unique()`, `.indexed()`, `.searchable()`, `.default(
 function many(entity: DmlEntity): Many<DmlEntity>
 ```
 
-Cardinality modifier for `defineLink()`. See [Links](./07-links.md).
+Cardinality modifier for `defineLink()`. See [Links](./08-links.md).
 
 ### Globals
 
@@ -111,7 +131,8 @@ All `define*` functions and helpers are globals — zero imports needed:
 | Global | Purpose |
 |--------|---------|
 | `defineModel`, `defineService`, `defineLink`, `defineCommand` | Core primitives |
-| `defineAgent`, `defineSubscriber`, `defineJob`, `defineContext` | Extended primitives |
+| `defineAgent`, `defineSubscriber`, `defineJob` | Extended primitives |
+| `defineContext` | Legacy context primitive; prefer filesystem contexts |
 | `defineConfig` | Configuration |
 | `field` | Property type factory |
 | `many` | Cardinality modifier |
@@ -137,6 +158,14 @@ function makeIdempotent<T>(
 ): (event: Message<T>) => Promise<void>
 ```
 
+### ICachePort production adapters
+
+| Adapter | Package path | Notes |
+| --- | --- | --- |
+| Upstash Redis | `@mantajs/adapter-cache-upstash` | Default production cache for Vercel/Cloudflare presets |
+| Postgres | `@mantajs/adapter-database-pg/cache` | Durable DB-backed fallback for auth revocation/session state |
+| In-memory | `InMemoryCacheAdapter` | Dev/test only; not durable across instances |
+
 ## step API
 
 Used inside `defineCommand({ workflow: (input, { step }) => {...} })`:

package/docs/17-dashboard.md

@@ -51,6 +51,8 @@ src/spa/admin/
 
 **`.ts` not `.tsx`** — pages export `definePage()` or `defineForm()` specs (pure data), not JSX. Only files in `blocks/` and `components/` are `.tsx`.
 
+**Mount path is project config, not page config.** A SPA named `admin` defaults to `/admin`. For a dedicated admin subdomain, set `spa.admin.mountPath = "/"` in `manta.config.ts`; page routes and navigation items remain SPA-local (`/products`, `/dashboard`, etc.).
+
 ---
 
 ## defineSpa()
@@ -141,7 +143,7 @@ export default definePage({
         { key: 'created_at', label: 'Created', format: 'date' },
       ],
       searchable: ['title'],
-      navigateTo: '/admin/products/:id',
+      navigateTo: '/products/:id',
     },
   ],
 })
@@ -564,7 +566,7 @@ header: {
   actions: [
     'create',
     { label: 'Export', command: 'export-products' },
-    { label: 'Import', to: '/admin/products/import' },
+    { label: 'Import', to: '/products/import' },
   ],
 }
 ```

package/docs/AGENT.md

@@ -350,7 +350,7 @@ Tables: `admin_user`, `admin_invite`
 
 Auth routes (on `/api/admin/`):
 - `POST /login` (public) — returns JWT with `{ id, type: 'admin' }`
-- `DELETE /logout` (public) — blacklists token
+- `DELETE /logout` (public) — clears auth cookies and attempts server-side token revocation
 - `POST /refresh` (public) — refresh token
 - `POST /forgot-password` (public) — reset flow
 - `POST /reset-password` (public) — confirm reset
@@ -362,7 +362,9 @@ Protected routes (JWT required, `type === 'admin'`):
 - `POST /create-user`, `POST /update-user`, `POST /delete-user`
 - `POST /create-invite`, `POST /refresh-invite`
 
-Middleware: all `/api/admin/*` routes verify JWT + `type === 'admin'`
+Middleware: all `/api/admin/*` routes verify JWT, reject cache-blacklisted identities when cache is reachable, then require `type === 'admin'`
+
+Production auth requires a durable `ICachePort` for logout/reset/session revocation. Default production presets use `@mantajs/adapter-cache-upstash`; use `@mantajs/adapter-database-pg/cache` when Postgres should be the durable cache backend.
 
 Override: create `src/commands/admin/login.ts` to replace auto-generated login.
 Override: create `src/middleware/admin.ts` to replace auto-generated middleware.
@@ -396,7 +398,13 @@ src/spa/admin/
         └── page.tsx          # → /admin/products
 ```
 
-Defaults: `@mantajs/dashboard` (shell) + `@mantajs/ui` (preset). Override in config:
+Defaults: `@mantajs/dashboard` (shell) + `@mantajs/ui` (preset). The generated Vite entry imports the dashboard CSS through the package export:
+
+```typescript
+import '@mantajs/dashboard/index.css'
+```
+
+Override in config:
 
 ```typescript
 // manta.config.ts
@@ -408,6 +416,42 @@ export default defineConfig({
 })
 ```
 
+Mount paths:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: {},                  // default: /admin
+    // admin: { mountPath: '/' } // root mount for admin.example.com
+  },
+})
+```
+
+When `mountPath` is `/`, generated Vercel rewrites exclude `/api/*` so API routes remain server-side.
+
+Dev Vite ports:
+
+```typescript
+export default defineConfig({
+  spa: {
+    admin: {
+      vitePort: 5310, // default starts at 5200
+    },
+  },
+})
+```
+
+Temporary local overrides also work:
+
+```bash
+MANTA_VITE_PORT=5310 manta dev
+MANTA_VITE_PORT_ADMIN=5311 manta dev
+```
+
+`manta build` writes a SPA fallback manifest. With the Node preset, `manta start` mirrors Vercel SPA fallback behavior locally: root/login auth shortcuts redirect under the single SPA mount path, SPA subroutes serve `index.html`, and `/api/*` remains server-side.
+
+`manta build --preset vercel` preserves existing custom `vercel.json` project settings such as `buildCommand`, `installCommand`, `outputDirectory`, `functions`, `headers`, plus custom redirects/rewrites/crons that do not collide with framework-generated SPA or cron entries.
+
 ### SDK — Frontend hooks
 
 ```typescript
@@ -497,5 +541,8 @@ Complete framework documentation is in `node_modules/@mantajs/core/docs/`:
 | [14-adapters](node_modules/@mantajs/core/docs/14-adapters.md) | Custom adapters |
 | [15-hosts](node_modules/@mantajs/core/docs/15-hosts.md) | Custom hosts |
 | [16-reference](node_modules/@mantajs/core/docs/16-reference.md) | API reference |
+| [17-dashboard](node_modules/@mantajs/core/docs/17-dashboard.md) | Dashboard specs, pages, forms, blocks |
+
+Projects generated by `manta init` include `.codex/skills/mantajs/SKILL.md` and `.claude/skills/mantajs/SKILL.md`. `manta dev` refreshes both from `@mantajs/core/skills/mantajs/SKILL.md` so Codex and Claude keep pointing at this same docs directory.
 
-**Read the relevant doc BEFORE writing code.** When in doubt, check [04-commands.md](node_modules/@mantajs/core/docs/04-commands.md) for workflow patterns.
+**Read the relevant doc BEFORE writing code.** When in doubt, check [05-commands.md](node_modules/@mantajs/core/docs/05-commands.md) for workflow patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantajs/core",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.10",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -36,7 +36,8 @@
       "default": "./dist/testing/relational-query-suite.js"
     },
     "./package.json": "./package.json",
-    "./docs/*": "./docs/*"
+    "./docs/*": "./docs/*",
+    "./skills/*": "./skills/*"
   },
   "dependencies": {
     "drizzle-orm": "^0.35.0",
@@ -51,6 +52,7 @@
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "skills"
   ]
 }