@happyvertical/smrt-template-sveltekit 0.38.26 → 0.39.0

package/template/README.md

@@ -1,467 +1,301 @@
-# SMRT SvelteKit App
+# s-m-r-t SvelteKit starter
 
-A SvelteKit application with SMRT framework integration for rapid development of AI-powered, multi-tenant applications.
+This is the small, ground-up starting point for s-m-r-t 0.38.25. It contains
+one object and the current SvelteKit application foundation. It intentionally
+does not include billing, onboarding, workers, deployment infrastructure, or
+provider-specific production configuration.
 
-## Getting Started
+## 1. Install and run
 
-1. **Install dependencies**:
-   ```bash
-   npm install
-   ```
+Requirements: Node.js 24.18.0 or newer and pnpm 10.34.4. The exact pnpm version
+is declared in `packageManager`.
 
-2. **Set up environment**:
-   ```bash
-   cp .env.example .env
-   ```
-
-3. **Start development server**:
-   ```bash
-   npm run dev
-   ```
-
-4. **Initialize database** (optional):
-   ```bash
-   smrt db:setup
-   ```
-
-## Project Structure
-
-```
-├── src/
-│   ├── hooks.server.ts        # Auth + tenancy wiring (see "Multi-tenancy" below)
-│   ├── lib/
-│   │   ├── objects/           # SMRT objects (auto-generates API routes)
-│   │   │   ├── index.ts       # Export all objects here
-│   │   │   └── Item.ts        # Example SMRT object
-│   │   └── server/
-│   │       ├── smrt.ts        # SMRT configuration + local manifest seeding
-│   │       ├── smrt-register.ts # Object registration (generated by smrtPlugin, gitignored)
-│   │       └── tenancy.ts     # Pluggable tenant resolver
-│   └── routes/
-│       ├── api/               # Auto-generated API routes (don't edit!)
-│       ├── +layout.server.ts  # Builds AdminShell tenant nav server-side (manifest → nav)
-│       ├── +layout.svelte     # WASD AdminShell chrome wrapping every page
-│       ├── settings/          # ShellSettingsPanel (panel layout + hotkeys)
-│       ├── +page.server.ts    # Home page server load + demo mutation (reference pattern)
-│       └── +page.svelte       # Home page (renders inside AdminShell)
-├── smrt.config.ts             # Root SMRT config
-├── vite.config.ts             # Vite + SMRT plugin config
-└── svelte.config.js           # SvelteKit config
+```bash
+pnpm install
+cp .env.example .env
+pnpm db:migrate
+pnpm check
+pnpm build
+pnpm dev
 ```
 
-## Data loading (SSR + hydration)
+Open `http://localhost:5173`. The app loads, but tenant data remains closed
+until your application adds a sign-in flow, an active membership, and role
+permissions. That is intentional: the starter demonstrates safe boundaries
+without inventing an authentication provider.
 
-The home page (`src/routes/+page.server.ts` + `+page.svelte`) is the reference
-pattern for getting collection data onto a page. Copy it for your own routes.
+`pnpm db:migrate` first runs the Vite build so the manifest, runtime
+registration, generated routes, and types match the current objects; it then
+applies the manifest-derived schema to SQLite. Re-run it after object changes.
 
-**Query collections in a server `load`, not with `fetch` on mount.** A server
-load runs during SSR, reads the database directly through the collection API
-(no HTTP round-trip through your own `/api/*` routes), and SvelteKit
-serializes the result into the initial HTML. The client hydrates that data
-without re-fetching — the page renders with its data on first paint, and the
-first client render issues no duplicate request.
+## 2. Understand the generated files
 
-```typescript
-// src/routes/+page.server.ts
-import type { Item } from '$lib/objects/Item';
-import { getCollection } from '$lib/server/smrt';
-import type { PageServerLoad } from './$types';
+The source of truth is `src/lib/objects`. Running `pnpm dev`, `pnpm build`, or
+`pnpm db:migrate` regenerates these artifacts:
 
-export const load: PageServerLoad = async ({ depends }) => {
-  depends('smrt:items'); // see "Refreshing after mutations" below
-
-  const items = await getCollection<Item>('Item');
-  const rows = await items.list({ orderBy: 'created_at DESC', limit: 50 });
+| Path | Purpose | Commit it? |
+| --- | --- | --- |
+| `.smrt/manifest.json` | Merged local and dependency runtime manifest | No |
+| `.smrt/smrt-knowledge.json` | Agent/developer knowledge graph | No |
+| `.smrt/register.js` | External package registration used by the CLI | No |
+| `src/lib/server/smrt-register.ts` | Local runtime class registration | No |
+| `src/lib/types/smrt-generated/` | Virtual-module and consumer declarations | No |
+| `src/routes/api/**/+server.ts` | Generated SvelteKit REST routes | No |
 
-  // Return plain serializable objects, not class instances.
-  return {
-    items: rows.map((item) => ({ id: item.id, title: item.title, status: item.status })),
-  };
-};
-```
-
-```svelte
-<!-- src/routes/+page.svelte -->
-<script lang="ts">
-  import type { PageProps } from './$types';
+Do not edit generated files. `smrtPlugin()` owns local scanning, manifests,
+types, and routes. `smrtConsumer()` explicitly consumes the profiles, tenancy,
+and users manifests so those models are available to setup and tooling.
 
-  let { data }: PageProps = $props();
-</script>
+## 3. Define the first object
 
-{#each data.items as item (item.id)}
-  <p>{item.title}</p>
-{/each}
-```
+`src/lib/objects/Item.ts` is the only example. It exposes the same CRUD action
+set to REST, MCP, WebMCP definitions, and the CLI, while limiting writable REST
+fields and opting into tenant scoping:
 
-Avoid the mount-time fetch anti-pattern (`$effect(() => { fetch('/api/items') ... })`):
-it renders an empty page first, waterfalls a second request on every
-navigation, and skips SvelteKit's load/hydration machinery entirely. Reserve
-client-side `fetch` of the generated `/api/*` routes for after-load
-interactions (mutations, polling, external clients) — not for initial page
-data.
+```ts
+import {
+  ObjectRegistry,
+  SmrtCollection,
+  SmrtObject,
+  smrt,
+} from '@happyvertical/smrt-core';
+import { TenantScoped, tenantId } from '@happyvertical/smrt-tenancy';
 
-### Refreshing after mutations (`depends` / `invalidate`)
+@smrt({
+  api: {
+    include: ['list', 'get', 'create', 'update', 'delete'],
+    writable: ['title', 'description', 'status'],
+  },
+  cli: { include: ['list', 'get', 'create', 'update', 'delete'] },
+  mcp: { include: ['list', 'get', 'create', 'update', 'delete'] },
+})
+@TenantScoped({ mode: 'optional' })
+export class Item extends SmrtObject {
+  @tenantId({ nullable: true })
+  tenantId: string | null = null;
 
-Convention: each load declares one dependency key per collection it reads,
-named `smrt:<collection>` — where `<collection>` is the generated REST route
-segment (`/api/items` → `smrt:items`). After a mutation, client code calls
-`invalidate('smrt:<collection>')` and every load that declared that key
-re-runs, updating the page in place:
+  title: string = '';
+  description: string = '';
+  status: string = 'draft';
+}
 
-```svelte
-<script lang="ts">
-  import { invalidate } from '$app/navigation';
+export class ItemCollection extends SmrtCollection<Item> {
+  static readonly _itemClass = Item;
+}
 
-  async function createItem(title: string) {
-    await fetch('/api/items', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ title }),
-    });
-    await invalidate('smrt:items'); // re-runs every load that declared depends('smrt:items')
-  }
-</script>
+ObjectRegistry.registerCollection('Item', ItemCollection);
 ```
 
-The home page demonstrates the same flow with a progressively-enhanced form
-action: `use:enhance` applies the action result with
-`update({ invalidateAll: false })`, then calls `invalidate('smrt:items')` so
-only the loads that depend on items re-run (instead of SvelteKit's default
-invalidate-everything). Note that the generated `/api/*` routes are
-fail-closed — mutations 401 unless the request is authenticated or the object
-opts in via `@smrt({ api: { public: true } })` — which is why the demo uses a
-form action running server-side.
-
-### Caching SSR reads
+Add another class beside it and export the class from
+`src/lib/objects/index.ts`. Keep relationship decorators next to `@smrt()`.
+Use `@foreignKey(Target)` for same-package relationships and
+`@crossPackageRef()` for relationships to another package. Keep the explicit
+collection constructor/registration when the generated CLI or MCP runtime must
+construct the collection outside a SvelteKit request.
 
-Server-side reads can opt into the collection read cache, per call or per
-model:
+## 4. Initialize or migrate the database
 
-```typescript
-// Per call — this load only
-const rows = await items.list({ where: { status: 'published' }, cache: { ttl: 60_000 } });
+SQLite defaults to `./app.db`; override it with `DATABASE_URL` and
+`DATABASE_TYPE`.
 
-// Per model — every read of this collection
-@smrt({ cache: { ttl: 60_000 } })
-export class Item extends SmrtObject { /* ... */ }
+```bash
+pnpm db:migrate
 ```
 
-Cached rows are keyed by the final SQL + parameters and live for `ttl`
-milliseconds. Every mutation that goes through SMRT (`create()`, `save()`,
-`delete()`) invalidates the table's cached entries in this process
-automatically — so the post-mutation `invalidate('smrt:...')` re-run sees
-fresh rows, as the home page demonstrates.
-
-Use it for read-heavy, write-rare data rendered for many visitors: catalogs,
-published content, navigation. Do **not** cache:
-
-- **Per-user data** (dashboards, "my items"): each user's query shape churns
-  the cache for little reuse, and any staleness is personally visible.
-- **Admin editors / read-your-writes flows**: editors must always see the
-  row they just changed, including across processes.
-- **Multi-replica deployments without `crossProcess: true`**: the cache is
-  per-process, so a write on one replica leaves the others stale until TTL.
-  Set `cache: { ttl, crossProcess: true }` (uses the database adapter's
-  notification capability, e.g. Postgres LISTEN/NOTIFY) or keep the TTL
-  short enough to tolerate.
-
-Pass `cache: false` on a specific call to bypass a model-level cache where
-freshness matters.
-
-### Client live collections (opt-in)
-
-The server-load pattern above renders a page and refreshes it with
-`invalidate()`. For **interactive surfaces** that mutate rows and want an
-optimistic, reactive local store (an editor, a live dashboard), layer the
-browser client-data runtime on top: `@happyvertical/smrt-web` (the engine
-wrapper) + `@happyvertical/smrt-svelte/web` (the Svelte 5 runes binding). It is
-**opt-in per surface** — the client engine (~76 kB gzip) should never load on
-public or content pages, so import it only in routes that use live collections.
-
-Keep loading the initial rows in a server `load` (SSR + no waterfall), then
-**seed** the client collection from the hydrated `PageData` with `initialData`,
-so the first client render serves the SSR rows with no duplicate fetch and only
-revalidates once they go stale:
-
-```typescript
-// src/routes/live/+page.server.ts — same server-load pattern, plain rows out.
-import { getCollection } from '$lib/server/smrt';
-import type { Item } from '$lib/objects/Item';
-import type { PageServerLoad } from './$types';
-
-export const load: PageServerLoad = async () => {
-  const items = await getCollection<Item>('Item');
-  const rows = await items.list({ orderBy: 'created_at DESC', limit: 50 });
-  return { items: rows.map((i) => ({ id: i.id, title: i.title, status: i.status })) };
-};
-```
+The current command is `smrt db:migrate`. `smrt db:setup` is deprecated in
+0.38.25 and is intentionally not used. Migrations are manifest-driven: change
+the TypeScript object, regenerate the manifest, and run the migration again.
+There are no hand-written migration files in this workflow.
 
-```svelte
-<!-- src/routes/live/+page.svelte -->
-<script lang="ts">
-  import { createSmrtCollection } from '@happyvertical/smrt-web';
-  import { liveCollection } from '@happyvertical/smrt-svelte/web';
-  import { getCollectionDefinition } from '@happyvertical/smrt-virt-web';
-  import type { PageProps } from './$types';
+Runtime schema creation is disabled. A missing table should be fixed by the
+migration command, not by adding schema creation to a request handler.
 
-  let { data }: PageProps = $props();
+## 5. Understand tenant context
 
-  // initialData seeds the cache from the SSR rows: the first read is served
-  // from data.items with NO network request, and revalidates after staleTimeMs.
-  // basePath MUST match this app's generated routes — they are served at
-  // `/api/*` (routesDir: 'src/routes/api'), not the runtime's `/api/v1` default,
-  // so revalidation and live mutations hit `/api/items` instead of 404ing.
-  const items = createSmrtCollection(getCollectionDefinition('items'), {
-    initialData: data.items,
-    basePath: '/api',
-  });
-  const view = liveCollection(items);
-</script>
+`src/hooks.server.ts` keeps tenant selection separate from authorization:
 
-{#each view.rows as item (item.id)}
-  <p>{item.title}</p>
-{/each}
-```
+1. `src/lib/server/tenancy.ts` reads a subdomain slug and looks up an active
+   Tenant UUID. It stores the candidate in `locals.selectedTenantId` and
+   `locals.selectedTenantSlug`.
+2. That candidate does not enter AsyncLocalStorage and cannot scope queries.
+3. `createSessionHandler({ enterTenantContext: true })` loads the signed session,
+   resolves its membership and permissions, and establishes the authorized
+   `locals.tenantId` context.
+4. `enableTenancy()` makes `@TenantScoped` collections honor that context.
 
-`getCollectionDefinition('items')` comes from the plugin-generated
-`@happyvertical/smrt-virt-web` virtual module (its `<collection>` key is the
-same REST route segment as `depends`/`invalidate`). Add
-`@happyvertical/smrt-web` and `@happyvertical/smrt-svelte` to the project's
-dependencies before using this pattern.
-
-## Workspace shell (AdminShell)
-
-This template renders every page inside the **WASD AdminShell** — a four-edge
-admin layout from `@happyvertical/smrt-svelte/workspace`. Each edge is a scope
-(top = app, left = tenant, right = focus, bottom = system) toggled with
-<kbd>W</kbd>/<kbd>A</kbd>/<kbd>S</kbd>/<kbd>D</kbd> (press <kbd>?</kbd> for the
-shortcuts). It is wired in the root layout:
-
-- `src/routes/+layout.server.ts` builds the left "tenant" nav **server-side**
-  with `tenantNavFromManifest()` from the SMRT manifest (`.smrt/manifest.json`)
-  and returns it as layout data — no client-side nav fetch.
-- `src/routes/+layout.svelte` wraps `{@render children()}` in `<AdminShell>`
-  (inside `<ThemeProvider>` — see **Theming** below), feeding that nav to
-  `<TenantNav>`, a brand/app panel on top, and a couple of status chips on the
-  bottom.
-- `src/routes/settings/+page.svelte` drops in `<ShellSettingsPanel>` so users
-  can toggle panels and remap the hotkeys; the choices persist in
-  `localStorage` under the shell's `storageKey`.
-
-**The shell preserves the server-load pattern above.** AdminShell's public core
-is SSR-safe: it renders statically on the server and only activates hotkeys /
-`localStorage` after mount. The active page still renders inside the shell's
-`<main>` and keeps its own `+page.server.ts` load and `invalidate()` refresh —
-the shell is chrome around the page, not a replacement for its data flow. The
-home page's `depends('smrt:items')` / `invalidate('smrt:items')` cycle works
-unchanged.
-
-### Theming
-
-The layout wraps the shell in **`<ThemeProvider>`** from
-`@happyvertical/smrt-ui/themes` — the standard SMRT theming wrapper (the same
-pattern the reference `@happyvertical/smrt-content` app uses):
+The default resolver ignores `x-tenant-id`. If a gateway supplies a tenant
+header, validate the gateway identity/signature before mapping it to a tenant,
+and still use `switchSessionTenant()` for browser session changes. That helper
+checks active membership and rotates the session ID; never copy an untrusted
+header directly into `locals.tenantId` or `enterTenantContext()`.
 
-```svelte
-<script lang="ts">
-  import { ThemeProvider } from '@happyvertical/smrt-ui/themes';
-  // @font-face rules for the SMRT type stack (Space Grotesk / Inter /
-  // JetBrains Mono woff2). ThemeProvider supplies the token *variables*;
-  // this loads the font *files*. Bundled — no CDN request.
-  import '@happyvertical/smrt-ui/themes/styles/fonts.css';
-</script>
+Set `TENANT_BASE_DOMAIN` for deployed subdomain routing. The fallback parser is
+only for local shapes such as `acme.demo.local`.
 
-<ThemeProvider colorScheme="system" persist={true}>
-  <!-- AdminShell + every page render themed inside here -->
-</ThemeProvider>
-```
+## 6. Understand users, profiles, memberships, roles, and permissions
 
-- ThemeProvider injects the **entire `--smrt-*` token set** (colors, typography,
-  spacing, radius, elevation, motion, z-index) as an inline style it computes
-  during render — so the tokens are present in the SSR HTML with **no unstyled
-  flash**, and it re-resolves them on the client. You do **not** need to import
-  `styles/tokens.css` or `themes/styles/*.css` separately; the provider is the
-  runtime source of truth.
-- `colorScheme="system"` follows the OS light/dark preference; `persist` saves a
-  user's explicit switch to `localStorage`. Switch presets/scheme at runtime
-  with `ThemeSwitcher` / `ColorSchemeToggle` (also from `.../themes`), or read
-  the current theme via the theme context.
-- The one thing the provider does not carry is the font **files** — hence the
-  `themes/styles/fonts.css` import above. Drop it and the type stack degrades to
-  `system-ui` / `ui-monospace` automatically.
-
-To pin a specific look instead of following the OS, set
-`colorScheme="light"` (or `"dark"`) and `preset="material"` (or `"glass"` /
-`"studio"` / `"smrt"`).
-
-The status chips ship static (`Local`, `Ready`). To make them (and the focus
-edge) live — job counts, dispatch depth, connection state — feed real values
-through `systemFeed` (`@happyvertical/smrt-svelte/workspace/live`) or
-`activityFeed` (`@happyvertical/smrt-svelte/web`).
-
-- **Migration guide** (old `WorkspaceShell`/`RoleShell` → `AdminShell`, and why
-  adoption is additive):
-  [`@happyvertical/smrt-svelte` → `src/components/workspace/MIGRATION.md`](https://github.com/happyvertical/smrt/blob/main/packages/smrt-svelte/src/components/workspace/MIGRATION.md)
-- **Four-scope demo** (all edges, focus tools, activities) and the live-feed
-  variants, in the smrt-svelte playground:
-  `playground/src/routes/admin-shell`, `admin-shell-activity-feed`, and
-  `admin-shell-system-feed`.
-
-## Multi-tenancy
-
-This template ships with multi-tenancy pre-wired. Out of the box you get:
-
-- **Session loading + auth** via `createSessionHandler({ enterTenantContext: true })` from `@happyvertical/smrt-users/sveltekit`. After the hook runs, `event.locals` carries `{ user, permissions, tenantId, sessionId }`.
-- **Auto-scoped REST routes**. The tenancy interceptor is registered globally (`enableTenancy()` in `hooks.server.ts`), so any model decorated with `@TenantScoped()` is filtered by the current tenant in `AsyncLocalStorage`. The generated `src/routes/api/**` endpoints inherit this automatically.
-- **Subdomain-based tenant resolution**. By default, the leading subdomain is the tenant slug:
-
-  | URL | Tenant ID |
-  |---|---|
-  | `https://acme.demo.local/dashboard` | `acme` |
-  | `https://www.demo.local/` | `null` (reserved) |
-  | `https://demo.local/` | `null` (no subdomain) |
-  | `http://localhost:5173/` | `null` (root-like host) |
-
-### Local development DNS
-
-Browsers won't resolve subdomains of `demo.local` to your dev server automatically. Pick one:
-
-**Option A — `/etc/hosts` (simplest, fixed list)**
+These are separate records with separate responsibilities:
 
-```
-127.0.0.1   demo.local
-127.0.0.1   acme.demo.local
-127.0.0.1   shop.acme.demo.local
-```
+- User is the authentication identity.
+- Profile is person-facing identity and metadata; a User may reference one.
+- Tenant is an organization/security boundary.
+- Membership connects one User to one Tenant and one Role.
+- Role receives Permission records through RolePermission.
+- Session binds the authenticated user to an active tenant and publishes the
+  resolved permission set for the request.
 
-**Option B — `dnsmasq` (wildcard, recommended)**
+CRUD permissions are manifest-derived: `items.read`, `items.create`,
+`items.update`, and `items.delete`. Provisioning code should sync the catalog
+and seed roles after the database migration:
 
-```bash
-# macOS
-brew install dnsmasq
-echo 'address=/demo.local/127.0.0.1' | sudo tee -a $(brew --prefix)/etc/dnsmasq.conf
-sudo brew services restart dnsmasq
-# Tell macOS to use dnsmasq for `.local` queries
-sudo mkdir -p /etc/resolver
-echo 'nameserver 127.0.0.1' | sudo tee /etc/resolver/local
+```ts
+import {
+  RoleCollection,
+  syncPermissionCatalog,
+} from '@happyvertical/smrt-users';
+import { getSmrtConfig } from '$lib/server/smrt';
+
+await syncPermissionCatalog(getSmrtConfig('Permission'));
+const roles = await RoleCollection.create(getSmrtConfig('Role'));
+await roles.seedSystemRoles({ seedPermissions: true });
 ```
 
-After either, hit `http://acme.demo.local:5173/` and the tenant will resolve to `acme`.
+The home-page form action demonstrates the hand-written server boundary: it
+passes the session's exact `locals.permissions` snapshot to
+`assertOperationPermission()`. Keep that pattern for custom SvelteKit actions,
+endpoints, jobs running as a principal, and other in-process writes.
 
-### Swapping the resolution strategy
+Generated REST routes are authentication-gated and tenant-scoped. On SQLite,
+authentication is not a substitute for your app's operation policy. Put
+permission-checked mutations behind app-owned handlers, or use the framework's
+Postgres RLS setup when moving to a production database.
 
-`src/lib/server/tenancy.ts` exposes three built-in strategies plus a `createTenantResolver()` factory. Pick whichever matches your routing:
+## 7. Load data into a SvelteKit page
 
-```ts
-// Subdomain (default)
-import {
-  createTenantResolver,
-  subdomainStrategy,
-} from '$lib/server/tenancy';
-export const resolveTenant = createTenantResolver(subdomainStrategy);
+Initial data belongs in `+page.server.ts`, where it can use the database and
+session context directly. Return plain serializable rows:
 
-// Path prefix:  /t/<slug>/...
-import {
-  createTenantResolver,
-  pathPrefixStrategy,
-} from '$lib/server/tenancy';
-export const resolveTenant = createTenantResolver(pathPrefixStrategy());
-
-// Custom prefix:  /tenant/<slug>/...
-export const resolveTenant = createTenantResolver(
-  pathPrefixStrategy({ prefix: '/tenant/' }),
-);
+```ts
+export const load: PageServerLoad = async ({ depends, locals }) => {
+  depends('smrt:items');
 
-// HTTP header:  x-tenant-id: acme
-import {
-  createTenantResolver,
-  headerStrategy,
-} from '$lib/server/tenancy';
-export const resolveTenant = createTenantResolver(headerStrategy());
+  if (!locals.permissions.includes('items.read')) {
+    return { items: [] };
+  }
 
-// Compose:  try subdomain, fall back to header
-import {
-  createTenantResolver,
-  headerStrategy,
-  subdomainStrategy,
-} from '$lib/server/tenancy';
-export const resolveTenant = createTenantResolver((event) => {
-  const fromSubdomain = subdomainStrategy(event);
-  if (fromSubdomain.tenantId) return fromSubdomain;
-  return headerStrategy()(event);
-});
+  const items = await getCollection<Item>('Item');
+  const rows = await items.list({ limit: 50 });
+  return {
+    items: rows.flatMap((item) =>
+      item.id ? [{ id: item.id, title: item.title, status: item.status }] : [],
+    ),
+  };
+};
 ```
 
-Inside a `+server.ts` or `+page.server.ts` you can read the resolved tenant either from `event.locals.tenantId` (set by the session handler) or — for any tenant-scoped model — just call its collection methods and the global interceptor will filter automatically.
+The page receives that data through `$props()`. Do not fetch initial page data
+from `onMount` or `$effect`; SvelteKit already serialized it into the response.
+After a mutation, call `invalidate('smrt:items')`. Only loads that declared
+`depends('smrt:items')` re-run.
 
-## Creating SMRT Objects
+## 8. Use generated REST, MCP, WebMCP, and CLI interfaces
 
-1. Create a new file in `src/lib/objects/`:
+The Item configuration generates:
 
-```typescript
-// src/lib/objects/Product.ts
-import { SmrtObject, smrt } from '@happyvertical/smrt-core';
-import { TenantScoped, tenantId } from '@happyvertical/smrt-tenancy';
+- REST: `GET`/`POST /api/items` and
+  `GET`/`PUT`/`DELETE /api/items/[id]`.
+- MCP descriptors and tools for Item CRUD.
+- Web collection definitions in the virtual
+  `@happyvertical/smrt-virt-web` module.
+- CLI commands for Item CRUD.
 
-@smrt({
-  api: { include: ['list', 'get', 'create', 'update', 'delete'] },
-  cli: { include: ['list', 'get'] },
-})
-@TenantScoped({ mode: 'optional' })
-export class Product extends SmrtObject {
-  @tenantId({ nullable: true })
-  tenantId: string | null = null;
+Inspect the registered objects and use the example CLI:
 
-  name: string = '';
-  price: number = 0.0;
-  description: string = '';
-  active: boolean = true;
-}
+```bash
+pnpm smrt objects
+pnpm smrt schema Item
 ```
 
-2. Export it from `src/lib/objects/index.ts`:
+The 0.38.25 CLI's manifest-only `objects` and `schema` commands work directly
+in this source-first template. Executing local-object CRUD through the generic
+CLI additionally requires a compiled JavaScript project entry point; REST and
+the page action are the runnable CRUD examples here.
 
-```typescript
-export { Item } from './Item.js';
-export { Product } from './Product.js';
+Generate a standalone MCP server when you are ready to configure a transport:
+
+```bash
+pnpm smrt generate-mcp --no-config --no-readme
 ```
 
-3. Run `npm run dev` - API routes are auto-generated! Because `Product` is `@TenantScoped`, listing via `GET /api/products` will only return rows for the request's tenant. (The generator pluralizes each class's `collection` field; see the "Generated API Routes" table below for the general `/api/{collection}` form.)
+The output is `.smrt/mcp-server/index.js`. It is generated and ignored.
 
-## CLI Commands
+WebMCP is opt-in per browser surface. First add the browser runtime, then put
+registration in a dedicated page that actually exposes tools:
 
 ```bash
-# List discovered SMRT objects
-smrt objects
+pnpm add @happyvertical/smrt-web@0.38.25
+```
 
-# View object details
-smrt introspect
+```svelte
+<script lang="ts">
+  import { collectionDefinitions } from '@happyvertical/smrt-virt-web';
+  import { onMount } from 'svelte';
+
+  onMount(() => {
+    let dispose = () => {};
+    void import('@happyvertical/smrt-web').then(({ registerWebMcpTools }) => {
+      dispose = registerWebMcpTools([collectionDefinitions.items], {
+        basePath: '/api',
+      });
+    });
+    return () => dispose();
+  });
+</script>
+```
 
-# Initialize database tables
-smrt db:setup
+`registerWebMcpTools()` feature-detects browser support and uses the current
+authenticated page session. In 0.38.25, list/get/create/update/delete are wired.
+Generated descriptors for custom actions exist, but custom action execution is
+not yet wired; WebMCP returns a clear result for those actions. Filter to read-only on
+surfaces that should not offer browser mutations.
 
-# Regenerate API routes
-smrt generate-routes
+## 9. Add optional live browser data
 
-# Run operations on objects
-smrt item list
-smrt item get <id>
-```
+Use this only on an interactive page. `@happyvertical/smrt-web` must be a direct
+dependency because the page imports it; the base starter does not need it.
 
-## API Endpoints
+Keep the server load from section 7, then seed the browser collection from its
+hydrated rows so the first render does not issue a duplicate request:
 
-For each SMRT object, the following endpoints are auto-generated:
+```svelte
+<script lang="ts">
+  import { createSmrtCollection } from '@happyvertical/smrt-web';
+  import { liveCollection } from '@happyvertical/smrt-svelte/web';
+  import { getCollectionDefinition } from '@happyvertical/smrt-virt-web';
+  import type { PageProps } from './$types';
+
+  let { data }: PageProps = $props();
+
+  const items = createSmrtCollection(getCollectionDefinition('items'), {
+    basePath: '/api',
+    initialData: data.items,
+    staleTimeMs: 30_000,
+  });
+  const view = liveCollection(items);
+</script>
 
-- `GET /api/{collection}` - List all items
-- `GET /api/{collection}/[id]` - Get single item
-- `POST /api/{collection}` - Create new item
-- `PUT /api/{collection}/[id]` - Update item
-- `DELETE /api/{collection}/[id]` - Delete item
+{#each view.rows as item (item.id)}
+  <p>{item.title}</p>
+{/each}
+```
 
-Custom methods are exposed as:
-- `POST /api/{collection}/[id]/{method}` - Call custom method
+Import the live runtime only from routes that use it. Static pages and the root
+layout should keep using server loads and should not pay for browser data tools.
 
-## Learn More
+## 10. Graduate to smrt-saas-starter
 
-- [SMRT Framework Documentation](https://github.com/happyvertical/smrt)
-- [SvelteKit Documentation](https://kit.svelte.dev/)
+Stay here while you are learning the object model or building a focused app
+from first principles. Move to `smrt-saas-starter` when you want a
+production-shaped SaaS baseline with onboarding, billing/subscriptions,
+background workers, provider configuration, deployment conventions, and
+mobile surfaces. Those concerns are intentionally absent here.