@happyvertical/smrt-template-sveltekit 0.53.2 → 0.53.4

package/AGENTS.md

@@ -17,6 +17,16 @@ It is the ground-up alternative to `smrt-saas-starter`.
   images ship no Corepack, so the Dockerfile installs a pinned copy.
 - `runtime.profile` is the canonical infrastructure selector. Generated apps
   expose deterministic `app:*` operations and keep runtime state outside source.
+- Every lifecycle script is a `smrt app <operation>` one-liner
+  (`packages/cli/agents/app-commands.md`); the template ships no `scripts/`.
+  Never reintroduce copied operator scripts: fix the CLI command instead.
+- Server composition is `createSmrtSvelteKitRuntime()` from
+  `@happyvertical/smrt-app-runtime/sveltekit`, built once in
+  `src/lib/server/smrt.ts` with the writer lease
+  (`acquireWriterLease(prepareApplicationStateRoot(...))`) and provider
+  readiness (`createProviderReadinessProbe`) from app-runtime's root entry, so
+  the web process never imports the CLI. Health, diagnostics, layout session,
+  and owner setup routes mount that package's handlers.
 - The production baseline uses adapter-node with separate web, task-worker, and
   schedule-worker processes. Workers import the build-compiled
   `.smrt/runtime/register.js` (#3117) before creating runners so app-defined
@@ -37,8 +47,9 @@ It is the ground-up alternative to `smrt-saas-starter`.
   different or stale server is never accepted as this app. Deployed health
   responses expose only generic status and profile.
 - Directly used `@happyvertical/smrt-*` packages share one current release range.
-- `@happyvertical/smrt-cli` is a direct dev dependency because scripts/docs use
-  its binary. The template includes `@happyvertical/smrt-web` because the root
+- `@happyvertical/smrt-cli` is a direct dev dependency because every
+  lifecycle script runs its binary; the runtime image keeps dev dependencies so
+  workers and operator commands can. The template includes `@happyvertical/smrt-web` because the root
   Provider wires the generated read-only WebMCP definitions for every page.
 - The generated MCP server resolves its imports from the scaffolded app, not
   from the CLI, so every specifier `generate-mcp` emits must be declared here.
@@ -49,9 +60,10 @@ It is the ground-up alternative to `smrt-saas-starter`.
   for the default worker and tenant surfaces. Do not assume pnpm exposes the
   CLI's or core's transitive dependencies to the app root — its strict layout
   does not (#2297).
-- `smrtConsumer()` explicitly consumes profiles, tenancy, and users manifests;
-  `smrtPlugin()` scans `src/lib/objects`, generates Vite virtual definitions,
-  SvelteKit routes, runtime registration, and knowledge artifacts.
+- `vite.config.ts` is `[sveltekit(), smrt()]`. The preset consumes exactly the
+  packages in `smrt.config.ts` `consumer.packages` (profiles, tenancy, users),
+  scans `src/lib/objects`, and generates Vite virtual definitions, SvelteKit
+  routes, runtime registration, and knowledge artifacts.
 - `pnpm db:migrate` builds first to refresh generated artifacts, then the
   migration wrapper holds the shared operation/writer exclusion for the full
   manifest-driven migration command. Do not restore deprecated `smrt db:setup`
@@ -59,11 +71,13 @@ It is the ground-up alternative to `smrt-saas-starter`.
 
 ## Application patterns
 
-- `src/hooks.server.ts` stores a URL-selected tenant candidate separately, then
-  lets `createSessionHandler({ enterTenantContext: true })` establish the only
-  authorized tenant context. Never turn an untrusted header into authority.
+- `src/hooks.server.ts` re-exports the runtime's `handle`/`init`: URL tenant
+  selection stays a separate candidate and only the verified session
+  establishes tenant context. Never turn an untrusted header into authority.
 - `src/lib/server/smrt.ts` imports generated local registrations, loads the
-  generated manifest metadata, and uses the public users request-scoped DB API.
+  generated manifest metadata, creates the runtime, and exposes
+  `getCollection()`/`getSmrtConfig()` over `runtime.classOptions()`, which is
+  request-scoped (RLS transaction) and must never be retained.
 - `Item` is the single example object and demonstrates optional tenant scope,
   a REST writable allowlist, shared CRUD action metadata, and the explicit
   collection registration required by generated CLI/MCP runtime commands.
@@ -71,18 +85,25 @@ It is the ground-up alternative to `smrt-saas-starter`.
   `depends('smrt:items')`, mutations call `invalidate('smrt:items')`, and
   hand-written writes call `assertOperationPermission()` with the session's
   exact permission snapshot.
-- The root layout uses Provider, the current smrt-ui ThemeProvider, AdminShell,
-  and a small explicit TenantNav. Generated REST routes do not imply page routes.
-- The root Provider registers generated WebMCP read tools with the authenticated
-  page session. Write/destructive effects require an explicit page-owned policy.
+- The root layout is `AppShell` from `@happyvertical/smrt-svelte/app` with a
+  small explicit `nav`; `/setup` and `/settings` mount that package's
+  `OwnerSetupForm` and `ShellSettingsPage`. Generated REST routes do not imply
+  page routes.
+- AppShell's Provider registers generated WebMCP read tools with the
+  authenticated page session. Write/destructive effects require an explicit
+  page-owned policy.
   Live browser collections remain opt-in per page and must seed from SSR
   `initialData` to avoid a duplicate first request.
-- `RuntimeDiagnosticsWebMcp` owns exactly one additional read-only tool,
-  `smrt.runtime.diagnostics.read`. It uses same-origin page-session fetch to the
-  authored `/api/_runtime/diagnostics` route and aborts its registration on
-  unmount. The route requires a direct active tenant membership plus either the
-  owner role or the explicit `runtime_diagnostics.read` permission before any
-  runtime projection/probe; it never calls principal-bound server tools.
+- AppShell's `runtimeDiagnostics` (on for signed-in sessions) owns exactly one
+  additional read-only tool, `smrt.runtime.diagnostics.read`, which fetches the
+  mounted `/api/_runtime/diagnostics` route as the page user. That route
+  (`createRuntimeDiagnosticsHandler`) requires a direct active tenant membership
+  plus the owner role or `runtime_diagnostics.read` before any projection or
+  probe; it never calls principal-bound server tools.
+- The opt-in `mcp-apps-template/` overlay is one `mountMcpAppRoute()` route,
+  the protected-resource metadata route, and the application-owned
+  `mcp-hosted-principal.ts` binding; `pnpm typecheck` checks it against the
+  template.
 
 ## Tests
 
@@ -126,11 +147,13 @@ own. Never add a mocked REST handler, an in-memory database, or DOM automation
 presented as WebMCP execution.
 
 - `@happyvertical/smrt-cli` is a devDependency **because the gate needs it**:
-  the app's `app:setup` migration step shells out to `pnpm exec smrt db:migrate`,
-  and the copied app deliberately never runs `pnpm install`, so `smrt` has to
-  arrive through the linked `node_modules/.bin`. The harness pins the app's own
-  `.bin` ahead of `PATH` and fails with a named error if that binary is missing,
-  so a host-global `smrt` cannot make a local run pass where CI fails.
+  the harness runs the app's own `smrt app setup` and `smrt app dev` from the
+  linked CLI, and setup's `pnpm build` is `smrt app build`. The copied app
+  deliberately never runs `pnpm install`, so `smrt` has to arrive through the
+  linked `node_modules`. The harness pins the app's own `.bin` ahead of `PATH`
+  and fails with a named error if the binary is missing, so a host-global
+  `smrt` cannot make a local run pass where CI fails. Identity and state-root
+  values it checks come from `@happyvertical/smrt-app-runtime`.
 - `pnpm test:e2e` runs the browser half.
 - `pnpm test:m5` runs the whole aggregate gate through
   `e2e/support/gate.mjs`, which requires a PostgreSQL service and fails when a
@@ -145,8 +168,12 @@ presented as WebMCP execution.
   from `testInfo.project.outputDir` and asserts it is outside the repository.
   The harness gives the copied app a real `node_modules` directory of
   individually symlinked entries rather than one symlink to this package's, so
-  the served app's `node_modules/.vite` cache cannot land in the checkout —
-  never replace that loop with a whole-directory symlink.
+  the served app's `node_modules/.vite` cache cannot land in the checkout.
+  Scope directories (`@happyvertical/`) and `.bin/` are real directories of
+  per-entry links too: the copy ships `pnpm-workspace.yaml` and setup runs
+  `pnpm build` in it, so anything pnpm relinks must land in the copy, never in
+  this package's `node_modules`. Never replace either loop with a
+  whole-directory symlink.
 - `e2e/` is outside `biome.json`'s include globs, as every package's `e2e/` is,
   so a green `Lint` job says nothing about this tree. `pnpm typecheck` covers
   the `.ts` files (`tsconfig.fixture.json` includes `e2e/**/*.ts`) but NOT

package/README.md

@@ -52,17 +52,21 @@ fixtures.
 
 ## 2. Understand the generated files
 
-The checked-in template contains authored objects, hooks, server helpers,
-pages, and configuration. Vite generates `.smrt/manifest.json`,
+The checked-in template contains authored objects, one server module
+(`src/lib/server/smrt.ts`, the runtime and collection access), thin hooks and
+routes that mount package handlers, pages, and configuration. It ships no
+operator scripts. Vite generates `.smrt/manifest.json`,
 `.smrt/smrt-knowledge.json`, `.smrt/register.js`,
 `src/lib/server/smrt-register.ts`, `src/lib/types/smrt-generated/`, and
 `src/routes/api/**/+server.ts`. All are ignored and excluded from scaffold
 fixtures.
 
-`smrtPlugin()` scans the local object directory and generates local routes and
-types. `smrtConsumer()` explicitly consumes the profiles, tenancy, and users
-package manifests. `@happyvertical/smrt-cli` is a direct dev dependency because
-the generated package scripts and README invoke its `smrt` binary.
+`vite.config.ts` is `plugins: [sveltekit(), smrt()]`: the
+`@happyvertical/smrt-core/vite` preset applies the decorator transform, scans
+the local object directory, generates local routes and types, and consumes the
+packages `smrt.config.ts` lists under `consumer.packages` (profiles, tenancy,
+users). `@happyvertical/smrt-cli` is a direct dev dependency because every
+lifecycle script is `smrt app <operation>`.
 
 ## 3. Define the first object
 
@@ -85,25 +89,28 @@ pnpm db:migrate
 ```
 
 The script builds first to refresh manifests, registrations, types, and API
-routes, then runs `smrt db:migrate`. The deprecated `smrt db:setup` command is
+routes, then runs `smrt app migrate`, which holds the operation lock and runs
+`smrt db:migrate`. The deprecated `smrt db:setup` command is
 not documented or shipped.
 
 ## 5. Understand tenant context
 
-The template resolves a URL tenant candidate into separate
-`selectedTenantId`/`selectedTenantSlug` locals. It does not establish query
-context from that selection. The session hook runs afterward and only its
-membership-authorized tenant enters the s-m-r-t tenancy context.
+`src/hooks.server.ts` mounts `createSmrtSvelteKitRuntime()` from
+`@happyvertical/smrt-app-runtime/sveltekit`. It resolves a URL tenant candidate
+into separate `selectedTenantId`/`selectedTenantSlug` locals and does not
+establish query context from that selection. The session step runs afterward
+and only its membership-authorized tenant enters the s-m-r-t tenancy context.
 
-Untrusted tenant headers are ignored. Applications may replace
-`src/lib/server/tenancy.ts` with a path, signed-cookie, or trusted-gateway
-selector, but selection must remain separate from authorization and session
-switches must use `switchSessionTenant()`.
+Untrusted tenant headers are ignored. Applications may pass `selectTenant` for
+a path, signed-cookie, or trusted-gateway selector, but selection must remain
+separate from authorization and session switches must use
+`switchSessionTenant()`.
 
 ## 6. Understand users, profiles, memberships, roles, and permissions
 
 The generated project consumes the current profiles and users manifests and
-wires `createSessionHandler({ enterTenantContext: true })`. A User is the auth
+loads the signed session through the runtime, which enters tenant context only
+for a verified active membership. A User is the auth
 identity, Profile is person-facing metadata, Membership joins a User to a
 Tenant and Role, Role maps to Permission records, and Session publishes the
 resolved permission snapshot.

package/mcp-apps-template/package.dependencies.json

@@ -1,4 +1,4 @@
 {
-  "@happyvertical/smrt-app-mcp": "^0.53.2",
-  "@happyvertical/smrt-mcp-openai": "^0.53.2"
+  "@happyvertical/smrt-app-mcp": "^0.53.4",
+  "@happyvertical/smrt-mcp-openai": "^0.53.4"
 }

package/mcp-apps-template/src/routes/.well-known/oauth-protected-resource/api/mcp/+server.ts

@@ -1,7 +1,15 @@
-import { hostedMcpAuth } from '$lib/server/mcp-hosted';
+import { createHostedMcpResourceAuth } from '@happyvertical/smrt-app-mcp/auth';
+import { mountMcpProtectedResourceMetadataRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
 
-/** Serve exactly the RFC 9728 metadata URL advertised by hosted bearer challenges. */
-export function GET() {
-  const auth = hostedMcpAuth();
-  return auth?.metadataResponse() ?? new Response(null, { status: 404 });
-}
+import { resolveHostedMcpPrincipal } from '$lib/server/mcp-hosted-principal';
+import { runtime } from '$lib/server/smrt';
+
+const { profile } = await runtime.resolvedRuntime();
+
+/** RFC 9728 metadata at exactly the URL hosted bearer challenges advertise (404 locally). */
+export const GET = mountMcpProtectedResourceMetadataRoute(
+  createHostedMcpResourceAuth({
+    profile,
+    resolvePrincipal: resolveHostedMcpPrincipal,
+  }),
+);

package/mcp-apps-template/src/routes/api/mcp/+server.ts

@@ -1,15 +1,72 @@
-import { mountMcpRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
+import type { McpWorkflowToolDefinition } from '@happyvertical/smrt-app-mcp';
+import { createHostedMcpResourceAuth } from '@happyvertical/smrt-app-mcp/auth';
+import { mountMcpAppRoute } from '@happyvertical/smrt-app-mcp/sveltekit';
+import { openAiDisplayMetadata, withOpenAiEntrypoints } from '@happyvertical/smrt-mcp-openai';
 
-import { mcpServer, resolveMcpPrincipal } from '$lib/server/mcp';
-import { hostedMcpAuth } from '$lib/server/mcp-hosted';
+import { Item } from '$lib/objects/Item';
+import { resolveHostedMcpPrincipal } from '$lib/server/mcp-hosted-principal';
+import { runtime } from '$lib/server/smrt';
 
-/** Stateless SDK-v2 Streamable HTTP MCP endpoint. */
-const localRoute = mountMcpRoute(mcpServer, { resolvePrincipal: resolveMcpPrincipal });
+const ITEM_RESOURCE_URI = 'ui://smrt-app/v1/items.html';
+const itemResourceHtml = `<!doctype html><html lang="en"><head><title>Items</title></head><body><main tabindex="-1"><h1>Items</h1><p>Use the host controls to review your authorized items.</p></main></body></html>`;
 
-export async function POST(event: Parameters<typeof localRoute>[0]) {
-  const auth = hostedMcpAuth();
-  if (!auth) return localRoute(event);
-  const checked = await auth.authenticate(event.request);
-  if (!checked.ok) return checked.response;
-  return mountMcpRoute(mcpServer, { resolvePrincipal: () => checked.principal })(event);
-}
+const itemsOverview: McpWorkflowToolDefinition = withOpenAiEntrypoints(
+  {
+    name: 'items_overview',
+    description: 'Open the authorized item overview.',
+    title: 'Items',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    outputSchema: {
+      type: 'object',
+      properties: { state: { type: 'string' } },
+      required: ['state'],
+      additionalProperties: false,
+    },
+    effect: 'read',
+    idempotent: true,
+    openWorld: false,
+    ui: { resourceUri: ITEM_RESOURCE_URI },
+    async execute() {
+      return {
+        content: [{ type: 'text', text: 'Item overview is ready.' }],
+        structuredContent: { state: 'ready' },
+      };
+    },
+  },
+  ['global'],
+);
+
+const { profile } = await runtime.resolvedRuntime();
+
+/**
+ * Stateless SDK-v2 Streamable HTTP MCP endpoint for this app's own `Item`.
+ * Locally the principal is the signed session (user, authorized tenant, and
+ * permission slugs); hosted profiles verify a bearer token and map it through
+ * the application-owned `resolveHostedMcpPrincipal`, and the verified bearer
+ * principal is bound into the request permission context (under
+ * `database-rls`, its own RLS transaction). Every principal needs
+ * `items.read`, so only read-only tools are published until per-operation
+ * authorization exists; browser requests from a foreign `Origin` are refused.
+ */
+export const POST = mountMcpAppRoute({
+  models: [Item],
+  requiredScopes: ['items.read'],
+  effects: ['read'],
+  smrtOptions: () => ({ db: runtime.databaseConfig() }),
+  auth: createHostedMcpResourceAuth({
+    profile,
+    resolvePrincipal: resolveHostedMcpPrincipal,
+  }),
+  bindPrincipal: runtime.runAsPrincipal,
+  workflowTools: [itemsOverview],
+  resources: [
+    {
+      uri: ITEM_RESOURCE_URI,
+      version: 'v1',
+      name: 'Items',
+      html: itemResourceHtml,
+      csp: {},
+      metadata: openAiDisplayMetadata({ availableDisplayModes: ['inline'] }),
+    },
+  ],
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-template-sveltekit",
-  "version": "0.53.2",
+  "version": "0.53.4",
   "description": "Minimal SvelteKit project template with s-m-r-t framework integration",
   "type": "module",
   "main": "index.js",
@@ -32,22 +32,24 @@
     "directory": "packages/template-sveltekit"
   },
   "peerDependencies": {
-    "@happyvertical/smrt-core": "0.53.2"
+    "@happyvertical/smrt-core": "0.53.4"
   },
   "devDependencies": {
-    "@happyvertical/smrt-app-runtime": "0.53.2",
-    "@happyvertical/smrt-assets": "0.53.2",
-    "@happyvertical/smrt-cli": "0.53.2",
-    "@happyvertical/smrt-config": "0.53.2",
-    "@happyvertical/smrt-jobs": "0.53.2",
-    "@happyvertical/smrt-playbooks": "0.53.2",
-    "@happyvertical/smrt-profiles": "0.53.2",
-    "@happyvertical/smrt-scanner": "0.53.2",
-    "@happyvertical/smrt-svelte": "0.53.2",
-    "@happyvertical/smrt-tenancy": "0.53.2",
-    "@happyvertical/smrt-ui": "0.53.2",
-    "@happyvertical/smrt-users": "0.53.2",
-    "@happyvertical/smrt-web": "0.53.2",
+    "@happyvertical/smrt-app-mcp": "0.53.4",
+    "@happyvertical/smrt-app-runtime": "0.53.4",
+    "@happyvertical/smrt-assets": "0.53.4",
+    "@happyvertical/smrt-cli": "0.53.4",
+    "@happyvertical/smrt-config": "0.53.4",
+    "@happyvertical/smrt-jobs": "0.53.4",
+    "@happyvertical/smrt-mcp-openai": "0.53.4",
+    "@happyvertical/smrt-playbooks": "0.53.4",
+    "@happyvertical/smrt-profiles": "0.53.4",
+    "@happyvertical/smrt-scanner": "0.53.4",
+    "@happyvertical/smrt-svelte": "0.53.4",
+    "@happyvertical/smrt-tenancy": "0.53.4",
+    "@happyvertical/smrt-ui": "0.53.4",
+    "@happyvertical/smrt-users": "0.53.4",
+    "@happyvertical/smrt-web": "0.53.4",
     "@happyvertical/sql": "^0.89.12",
     "@modelcontextprotocol/server": "^2.0.0",
     "@playwright/test": "^1.63.0",

package/template/AGENTS.md

@@ -18,7 +18,16 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
   return only the schema-versioned allowlist; never expose private runtime
   objects, identity fields, paths, URLs, secrets, PII, raw errors, or logs.
 - Never improvise setup internals. Run `pnpm app:install`; use individual
-  `app:*` commands only for recovery or explicit operator control.
+  `app:*` commands only for recovery or explicit operator control. They call
+  `smrt app <operation>` from `@happyvertical/smrt-cli`; do not copy operator
+  scripts into this app.
+- Server composition (profile, storage custody, owner bootstrap, tenant
+  selection, session, health, diagnostics) comes from
+  `@happyvertical/smrt-app-runtime/sveltekit`, configured once in
+  `src/lib/server/smrt.ts`. Pass app-specific behaviour as options
+  (`selectTenant`, `classOverrides`, `session`, `prepareDatabase`); do not
+  reimplement hooks. `getCollection()`/`getSmrtConfig()` are request-scoped:
+  never keep their result beyond the request.
 - Recover an interrupted unclaimed owner invitation with `pnpm app:stop`, then
   `pnpm app:recover`, `pnpm app:start`, and `pnpm app:open`; never print or copy
   its token.
@@ -48,8 +57,9 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
 - Keep object relationship metadata close to `@smrt()`.
 - Add human-facing routes explicitly; generated REST routes do not create nav
   pages.
-- The root layout includes `@happyvertical/smrt-web` and registers generated
-  WebMCP read tools through Provider when the browser exposes `modelContext`.
+- The root layout is `AppShell` from `@happyvertical/smrt-svelte/app`; it
+  includes `@happyvertical/smrt-web` and registers generated WebMCP read tools
+  through its Provider when the browser exposes `modelContext`.
   Keep the guard in place for SSR and seed live collections with SSR
   `initialData`.
 - Do not enable knowledge HTTP routes in production without explicit admin auth.
@@ -57,8 +67,9 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
   imports `.smrt/runtime/register.js` (compiled by `pnpm build`) before any
   runner starts, so jobs can target this app's own `@smrt()` objects; keep that
   import ahead of runner creation and keep domain objects free of SvelteKit
-  virtual modules (`$env/*`, `$app/*`), which a worker cannot load. Extend the
-  portability adapter instead of converting database files. Deployed provider
+  virtual modules (`$env/*`, `$app/*`), which a worker cannot load. Add a
+  `scripts/smrt-portability.mjs` adapter (it overrides the CLI's built-in one)
+  instead of converting database files. Deployed provider
   readiness must come from installed modules that probe the real backing
   services; environment booleans are not readiness evidence.
 - Every supported local web entry point (`app:start` or `pnpm dev`) holds the

package/template/Dockerfile

@@ -17,7 +17,6 @@ ENV NODE_ENV=production
 ENV SMRT_RUNTIME_PROFILE=self-hosted
 COPY --from=build /app/build ./build
 COPY --from=build /app/.smrt ./.smrt
-COPY --from=build /app/scripts ./scripts
 COPY --from=build /app/smrt.config.ts ./smrt.config.ts
 RUN chown -R node:node /app
 USER node

package/template/INSTALL_PROMPT.md

@@ -7,5 +7,5 @@
 > `pnpm app:doctor`, show me its secret-free recovery findings, and ask before
 > changing provider configuration.
 
-The prompt is intentionally thin. `scripts/smrt-app.mjs` owns operations and
-recovery.
+The prompt is intentionally thin. `smrt app` (from `@happyvertical/smrt-cli`)
+owns operations and recovery.

package/template/README.md

@@ -22,7 +22,9 @@ re-running install, setup, or recovery; each operation is repeatable from that
 stopped state. `pnpm app:doctor`
 prints secret-free JSON diagnostics and recovery steps. Individual
 setup/start/doctor/open/stop/backup/export/import operations are available as
-`pnpm app:<operation>`.
+`pnpm app:<operation>`. Every lifecycle script is a one-line call to
+`smrt app <operation>` from `@happyvertical/smrt-cli`; the app ships no copied
+operator scripts, so upgrading the CLI upgrades them.
 
 `app:start` defaults adapter-node `ORIGIN` to its loopback HTTP URL (including
 the selected `PORT`) and preserves an explicitly configured `ORIGIN`. Origin
@@ -58,9 +60,12 @@ The source of truth is `src/lib/objects`. Running `pnpm dev`, `pnpm build`, or
 | `src/lib/types/smrt-generated/` | Virtual-module and consumer declarations | No |
 | `src/routes/api/**/+server.ts` | Generated SvelteKit REST routes | No |
 
-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.
+Do not edit generated files. The `smrt()` plugin in `vite.config.ts` owns
+local scanning, manifests, types, routes, and the decorator transform. It
+consumes exactly the packages listed in `smrt.config.ts` under
+`consumer.packages` (profiles, tenancy, and users) so those models are
+available to setup and tooling; add a SMRT package there when the app uses its
+objects.
 
 ## 3. Define the first object
 
@@ -130,22 +135,31 @@ migration command, not by adding schema creation to a request handler.
 
 ## 5. Understand tenant context
 
-`src/hooks.server.ts` keeps tenant selection separate from authorization:
+`src/hooks.server.ts` mounts the runtime configured in `src/lib/server/smrt.ts`
+(`createSmrtSvelteKitRuntime()` from `@happyvertical/smrt-app-runtime/sveltekit`).
+It keeps tenant selection separate from authorization:
 
-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`.
+1. A subdomain slug is looked up as an active Tenant UUID and stored only as a
+   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.
-
-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()`.
+3. The signed session is loaded. Its tenant is accepted only for an active (or
+   legitimately inherited) membership, which establishes the authorized
+   `locals.tenantId`, the permission set, and the tenant context.
+4. The runtime enables tenancy, so `@TenantScoped` collections honor that
+   context.
+
+The default selector ignores `x-tenant-id`. To select tenants from a path,
+signed cookie, or trusted gateway, pass `selectTenant` to
+`createSmrtSvelteKitRuntime()`; selection must still never establish
+authorization. Validate a gateway's identity/signature before mapping its
+header to a tenant, and 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()`.
+
+`getCollection()` and `getSmrtConfig()` in `$lib/server/smrt` return
+request-scoped options (under `database-rls` isolation they carry the request
+transaction): call them inside a request and never keep the result.
 
 Set `TENANT_BASE_DOMAIN` for deployed subdomain routing. The fallback parser is
 only for local shapes such as `acme.demo.local`.
@@ -234,10 +248,14 @@ non-object or malformed manifests, credential-shaped JSON fields and credential
 URL userinfo, non-portable schemas, and non-loopback HTTP server URLs. Diagnostics never
 include malformed manifest content.
 
-The option stages `src/routes/api/mcp/+server.ts`, a session-authorized `mcp`
-server, and a bounded static resource with a restrictive CSP. It also includes
-`McpAppsBridge.svelte` for an application-configured trusted host origin and
-the optional OpenAI display adapter; it stays inert until your UI mounts it.
+The option stages `src/routes/api/mcp/+server.ts`, one `mountMcpAppRoute()`
+call from `@happyvertical/smrt-app-mcp/sveltekit` that publishes `Item` to
+principals holding `items.read` (the signed session's permissions locally),
+refuses browser requests from a foreign `Origin`, and serves a bounded static
+resource with a restrictive CSP and the optional OpenAI display metadata. It
+also stages the protected-resource metadata route. For a view, mount
+`McpAppsBridge` from `@happyvertical/smrt-svelte/mcp-apps` with an
+application-configured trusted host origin.
 The scaffold does not enable remote MCP tasks, so a deployment that adds them
 must supply the durable worker's live authorization callback before publication.
 
@@ -300,7 +318,7 @@ narrower tool set.
 ```svelte
 <script lang="ts">
   import { webMcpToolDefinitions } from '@happyvertical/smrt-virt-web';
-  import { Provider } from '@happyvertical/smrt-svelte';
+  import { AppShell } from '@happyvertical/smrt-svelte/app';
 
   const webmcp = $derived(
     typeof document !== 'undefined' && 'modelContext' in document
@@ -309,11 +327,17 @@ narrower tool set.
   );
 </script>
 
-<Provider {webmcp}>
+<!-- AppShell passes `webmcp` to its Provider unchanged. -->
+<AppShell title="s-m-r-t app" {webmcp} {nav}>
   {@render children()}
-</Provider>
+</AppShell>
 ```
 
+The root layout is `AppShell` from `@happyvertical/smrt-svelte/app` (Provider,
+theme and its CSS, the admin shell, and navigation); the app supplies its
+navigation and content. `/setup` and `/settings` use the same package's
+`OwnerSetupForm` and `ShellSettingsPage`.
+
 `registerWebMcpTools()` feature-detects browser support and uses the current
 authenticated page session. Omitted policy exposes all `read`-effect tools:
 intrinsic `list`/`get` plus custom actions explicitly declared as reads. To
@@ -399,8 +423,9 @@ Every supported local web
 entry point (`app:start` or `pnpm dev`) holds a shared writer lease. Direct
 production startup must set an explicit loopback `HOST`, and `app:start` is the
 recommended entry point. Stop the app before backup/import. For deployed import, stop
-web/workers and set `SMRT_MAINTENANCE_MODE=true`. Extend
-`scripts/smrt-portability.mjs` for domain-specific transformations.
+web/workers and set `SMRT_MAINTENANCE_MODE=true`. For domain-specific
+transformations, add a `scripts/smrt-portability.mjs` adapter; when present it
+replaces `smrt app export`/`import`'s built-in one.
 
 ### Hosted MCP authorization
 

package/template/compose.yaml

@@ -16,7 +16,7 @@ services:
     build: .
     env_file: .env.self-hosted
     environment: *runtime-environment
-    command: node scripts/smrt-worker.mjs task
+    command: pnpm exec smrt app worker task
     depends_on:
       migrate:
         condition: service_completed_successfully
@@ -24,7 +24,7 @@ services:
     build: .
     env_file: .env.self-hosted
     environment: *runtime-environment
-    command: node scripts/smrt-worker.mjs schedule
+    command: pnpm exec smrt app worker schedule
     depends_on:
       migrate:
         condition: service_completed_successfully