@happyvertical/smrt-template-sveltekit 0.43.10 → 0.44.0

package/AGENTS.md

@@ -14,6 +14,25 @@ It is the ground-up alternative to `smrt-saas-starter`.
 ## Current generated-project contract
 
 - Node `>=24.18.0`; pnpm `10.34.4` via `packageManager` and `engines`.
+- `runtime.profile` is the canonical infrastructure selector. Generated apps
+  expose deterministic `app:*` operations and keep runtime state outside source.
+- The production baseline uses adapter-node with separate web, task-worker, and
+  schedule-worker processes. Its runtime image retains the generated manifest
+  and operator CLI needed by `app:doctor`, `app:export`, and `app:import`.
+- Deployed authentication, asset, and secret readiness is delegated to
+  installed provider-owned probe modules; never replace it with truthy flags.
+- Every supported local web writer (`app:start` or `pnpm dev`)
+  acquires the same external writer lease. Logical imports and filesystem
+  backups fail closed while any writer is alive; logical exports take one
+  database transaction snapshot and include filesystem assets referenced by
+  exported asset rows in a digest-verified, provider-neutral manifest. Imports
+  stage and verify those assets before committing database rows.
+  Direct production startup must set an explicit loopback `HOST`.
+- Local `app:start` proves readiness against the loopback-only identity fields
+  on the runtime health route using the canonical application ID, random
+  process instance, and secret-safe runtime configuration identity; a
+  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
@@ -23,17 +42,17 @@ It is the ground-up alternative to `smrt-saas-starter`.
   `@modelcontextprotocol/server` (plus its `/stdio` subpath),
   `@happyvertical/smrt-core`, and `@happyvertical/smrt-config` are always
   emitted and are always dependencies. `@happyvertical/smrt-jobs` (task actions)
-  and `@happyvertical/smrt-tenancy` (tenant-scoped objects) are conditional;
-  tenancy is already a dependency for other reasons, and jobs is documented in
-  the template README as an add-when-needed. Do not assume pnpm exposes the
+  and `@happyvertical/smrt-tenancy` (tenant-scoped objects) are also declared
+  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.
-- `pnpm db:migrate` builds first to refresh generated artifacts, then runs the
-  current manifest-driven migration command. Do not restore deprecated
-  `smrt db:setup` documentation.
+- `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`
+  documentation or split the safety check from the migration process.
 
 ## Application patterns
 
@@ -55,6 +74,12 @@ It is the ground-up alternative to `smrt-saas-starter`.
   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.
 
 ## Tests
 

package/README.md

@@ -1,7 +1,7 @@
 # @happyvertical/smrt-template-sveltekit
 
 The minimal “learn and build from the ground up” SvelteKit template for
-s-m-r-t 0.38.25. The package exports `copyTemplate()`, `getTemplatePath()`, and
+s-m-r-t 0.43.10. The package exports `copyTemplate()`, `getTemplatePath()`, and
 `templateInfo` and is the `sveltekit` template used by `smrt gnode create`.
 
 ## 1. Install and run
@@ -13,18 +13,15 @@ node --input-type=module -e "import { copyTemplate } from './packages/template-s
 cd my-app
 pnpm install
 cp .env.example .env
-pnpm db:migrate
-pnpm check
-pnpm build
-pnpm dev
+pnpm app:install
 ```
 
-Run the copy command from the monorepo root. The public 0.38.25 CLI advertises
+Run the copy command from the monorepo root. The public 0.43.10 CLI advertises
 `gnode create`, but its command dispatcher currently rejects `gnode`; this
 package's tested `copyTemplate()` export is the working scaffold path.
 
 Generated projects require Node.js 24.18.0 or newer and pnpm 10.34.4. They pin
-all directly used `@happyvertical/smrt-*` packages to 0.38.25.
+all directly used `@happyvertical/smrt-*` packages to 0.43.10.
 
 For programmatic scaffolding:
 
@@ -37,8 +34,10 @@ copyTemplate('/absolute/path/to/my-app', {
 });
 ```
 
-`copyTemplate()` substitutes the package name and excludes package-internal
-`.svelte-kit` and test fixtures.
+`copyTemplate()` turns an unscoped project name such as `my-app` into the
+runtime-safe package identity `@smrt-app/my-app`; explicitly scoped package
+names are preserved. It also excludes package-internal `.svelte-kit` and test
+fixtures.
 
 ## 2. Understand the generated files
 
@@ -67,7 +66,8 @@ Add objects beside Item and export them from `src/lib/objects/index.ts`.
 
 ## 4. Initialize or migrate the database
 
-Generated projects use SQLite at `./app.db` by default:
+Generated local projects use SQLite in the current user's operating-system
+application-data directory by default:
 
 ```bash
 pnpm db:migrate
@@ -149,3 +149,19 @@ Use this template for learning and focused, ground-up applications. Choose
 onboarding, billing/subscriptions, workers, provider configuration, deployment
 infrastructure, and mobile applications. This package intentionally avoids
 becoming a second SaaS starter.
+
+The generated project has one canonical `runtime.profile` and deterministic
+`app:*` operations. Local state stays outside source. The production baseline
+uses adapter-node and includes a container plus separate task/schedule workers;
+Compose requires operator-supplied database secrets, and cloud examples
+describe provider composition without pretending to provision it.
+Install/start/stop/recover are local-profile commands; deployed web processes
+run the production Node build or container directly.
+
+Every supported local web entry point (`app:start` or `pnpm dev`) shares one
+writer lease outside the source checkout. Direct production startup requires
+an explicit loopback `HOST`; prefer `app:start`. Filesystem backup and logical
+import fail closed while a writer is alive; logical export reads every model
+table from one transaction snapshot and reports that uploaded assets are
+excluded. The production image retains the generated manifest and operator CLI
+required by doctor/export/import.

package/index.js

@@ -7,8 +7,11 @@
 import {
   cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readFileSync,
+  renameSync,
+  rmSync,
   writeFileSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -24,6 +27,16 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  */
 const COPY_SKIP = new Set(['.svelte-kit', '__tests__', 'test', 'tests']);
 
+function pathEntryExists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
 /**
  * Get the path to the template directory
  */
@@ -31,6 +44,23 @@ export function getTemplatePath() {
   return join(__dirname, 'template');
 }
 
+function normalizePackageSegment(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function packageNameForProject(name) {
+  if (name.startsWith('@')) {
+    const slash = name.indexOf('/');
+    const scope = normalizePackageSegment(name.slice(1, slash));
+    const packageName = normalizePackageSegment(name.slice(slash + 1));
+    if (slash > 1 && scope && packageName) return `@${scope}/${packageName}`;
+  }
+  return `@smrt-app/${normalizePackageSegment(name) || 'app'}`;
+}
+
 /**
  * Copy the template to a destination directory
  *
@@ -63,12 +93,30 @@ export function copyTemplate(destination, options = {}) {
     },
   });
 
+  // npm pack omits files literally named `.gitignore`. Ship the canonical
+  // contents under a neutral name and materialize the ignore file only in the
+  // generated project so installed-package scaffolds retain secret hygiene.
+  const packagedGitignore = join(destination, 'gitignore.template');
+  if (!existsSync(packagedGitignore)) {
+    throw new Error('Template package is missing gitignore.template');
+  }
+  const destinationGitignore = join(destination, '.gitignore');
+  if (pathEntryExists(destinationGitignore) && !options.overwrite) {
+    rmSync(packagedGitignore, { force: true });
+  } else {
+    rmSync(destinationGitignore, { force: true });
+    renameSync(packagedGitignore, destinationGitignore);
+  }
+
   // Update package.json with project name if provided
   if (options.name) {
     const packageJsonPath = join(destination, 'package.json');
     if (existsSync(packageJsonPath)) {
       const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-      packageJson.name = options.name;
+      // s-m-r-t runtime identities use scoped package-qualified class names.
+      // Keep a friendly directory/project name while making the generated
+      // package identity valid for isolated runtime registration.
+      packageJson.name = packageNameForProject(options.name);
       writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
     }
   }
@@ -81,13 +129,16 @@ export function copyTemplate(destination, options = {}) {
  */
 export const templateInfo = {
   name: 'sveltekit',
-  description: 'Minimal SvelteKit project with s-m-r-t framework integration',
+  description: 'Profile-aware installable SvelteKit project with s-m-r-t integration',
   features: [
     'SvelteKit 2.x with Svelte 5',
     'Auto-generated REST API routes',
     's-m-r-t CLI integration',
     'TypeScript support',
     'SQLite database (configurable)',
+    'Local, self-hosted, and cloud runtime profiles',
+    'Deterministic install, diagnostics, and portability commands',
+    'Production Node container and separate worker entry points',
     'Session-authorized tenancy with separate subdomain selection',
   ],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-template-sveltekit",
-  "version": "0.43.10",
+  "version": "0.44.0",
   "description": "Minimal SvelteKit project template with s-m-r-t framework integration",
   "type": "module",
   "main": "index.js",
@@ -29,19 +29,33 @@
     "directory": "packages/template-sveltekit"
   },
   "peerDependencies": {
-    "@happyvertical/smrt-core": "0.43.10"
+    "@happyvertical/smrt-core": "0.44.0"
   },
   "devDependencies": {
+    "@happyvertical/sql": "^0.89.4",
+    "@types/node": "24.13.2",
+    "typescript": "5.9.3",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-tenancy": "0.43.10",
-    "@happyvertical/smrt-users": "0.43.10"
+    "@happyvertical/smrt-assets": "0.44.0",
+    "@happyvertical/smrt-playbooks": "0.44.0",
+    "@happyvertical/smrt-jobs": "0.44.0",
+    "@happyvertical/smrt-profiles": "0.44.0",
+    "@happyvertical/smrt-config": "0.44.0",
+    "@happyvertical/smrt-app-runtime": "0.44.0",
+    "@happyvertical/smrt-scanner": "0.44.0",
+    "@happyvertical/smrt-users": "0.44.0",
+    "@happyvertical/smrt-web": "0.44.0",
+    "@happyvertical/smrt-tenancy": "0.44.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
   "scripts": {
+    "build": "pnpm run typecheck && node --check index.js",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:postgres": "node ../../scripts/run-with-ci-postgres.mjs -- pnpm exec vitest run __tests__/runtimeProfileReference.postgres.optional.test.ts",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.fixture.json"
   }
 }

package/template/.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+.git
+.svelte-kit
+build
+dist
+.smrt
+.env
+.env.*
+data
+backups
+exports
+*.log

package/template/.env.cloud.example

@@ -0,0 +1,9 @@
+SMRT_RUNTIME_PROFILE=cloud
+DATABASE_URL=postgresql://managed-connection-from-secret-provider
+HOST=0.0.0.0
+PORT=3000
+# Configure installed provider-owned modules that probe the real services.
+# SMRT_AUTH_READINESS_MODULE=@your-org/auth-readiness
+# SMRT_ASSETS_READINESS_MODULE=@your-org/assets-readiness
+# SMRT_SECRETS_READINESS_MODULE=@your-org/secrets-readiness
+SMRT_WORKER_CONCURRENCY=8

package/template/.env.example

@@ -1,6 +1,18 @@
-# Database
-DATABASE_URL=./app.db
-DATABASE_TYPE=sqlite
+# One canonical infrastructure profile. Local is the safe default when omitted.
+SMRT_RUNTIME_PROFILE=local
+
+# Optional stable application id and user-owned data path. The default is the
+# operating system's application-data directory, never this source checkout.
+# SMRT_APP_ID=my-app
+# SMRT_DATA_DIR=/absolute/user-owned/path
+
+# app:*, db:migrate, and the Vite dev/build launchers load this ignored file.
+# Keep SMRT_* runtime identity here; Vite's mode-specific env files are not
+# runtime identity sources.
+# Direct `node build` does not; export HOST explicitly or prefer app:start.
+# Local owner bootstrap is loopback-only.
+HOST=127.0.0.1
+PORT=5173
 
 # Optional apex used for subdomain tenant selection.
 # The value selects a tenant candidate; session membership still authorizes it.

package/template/.env.self-hosted.example

@@ -0,0 +1,11 @@
+SMRT_RUNTIME_PROFILE=self-hosted
+HOST=0.0.0.0
+PORT=3000
+# Put DATABASE_URL and POSTGRES_PASSWORD in the ignored `.env` file. Compose
+# refuses to start if either secret is absent; never commit their values.
+# Provider adapters keep real credentials private. Each setting must name an
+# installed module whose checkReadiness() probes the real backing service.
+# SMRT_AUTH_READINESS_MODULE=@your-org/auth-readiness
+# SMRT_ASSETS_READINESS_MODULE=@your-org/assets-readiness
+# SMRT_SECRETS_READINESS_MODULE=@your-org/secrets-readiness
+SMRT_WORKER_CONCURRENCY=4

package/template/AGENTS.md

@@ -11,6 +11,21 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
 - Regenerate them with `pnpm build` or `pnpm dev`; run `pnpm db:migrate` after
   object schema changes.
 - Keep `CLAUDE.md` as the one-line `@AGENTS.md` shim.
+- The root-owned `smrt.runtime.diagnostics.read` WebMCP tool calls only the
+  authenticated `/api/_runtime/diagnostics` route as the page user. Keep its
+  registration singular/read-only and preserve owner disposal. The route must
+  authorize a direct active tenant principal before projection or probing and
+  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.
+- 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.
+- Treat `smrt.config.ts` `runtime.profile` as the only infrastructure selector.
+- Treat the local health route's configuration digest as a loopback-only
+  identity; it must never contain or hash provider credentials. Deployed
+  health responses expose only generic status and profile.
 
 ## Data and authorization
 
@@ -24,6 +39,9 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
   membership-gated browser tenant changes.
 - Use `assertOperationPermission()` for hand-written server mutations and pass
   the exact session permission snapshot when available.
+- Keep data, assets, secrets, PID state, backups, and exports outside source.
+  Never copy secrets into diagnostics, logs, exports, or agent prompts.
+- Local onboarding creates real authorization records and stays loopback-only.
 
 ## Extension rules
 
@@ -35,3 +53,17 @@ tools, WebMCP definitions, and agent/developer knowledge artifacts.
   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.
+- Run task and schedule workers as separate deployed processes. Extend the
+  portability adapter 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
+  same writer lease. Direct production startup requires an explicit loopback
+  `HOST`; prefer `app:start`. Stop the app before backup/import; never bypass
+  or delete a live lease. Deployed imports require stopped web/workers plus
+  explicit `SMRT_MAINTENANCE_MODE=true`.
+- Logical export reads every model table in one transaction and includes
+  filesystem assets referenced by exported asset rows in a bounded,
+  digest-verified manifest. Keep imports transactional, stage and verify assets
+  before commit, and preserve the relationship-aware ordering/deferred-cycle
+  contract.

package/template/Dockerfile

@@ -0,0 +1,23 @@
+FROM node:24-alpine AS build
+WORKDIR /app
+RUN corepack enable
+COPY package.json pnpm-lock.yaml* ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-alpine AS runtime
+WORKDIR /app
+RUN corepack enable
+COPY --from=build /app/package.json /app/pnpm-lock.yaml* ./
+RUN pnpm install --frozen-lockfile --prod=false
+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
+EXPOSE 3000
+CMD ["node", "build"]

package/template/INSTALL_PROMPT.md

@@ -0,0 +1,11 @@
+# Agent install prompt
+
+> Install this application using its documented deterministic path. Verify Node
+> and pnpm requirements, run `pnpm install --frozen-lockfile` when a lockfile
+> exists (otherwise `pnpm install`), then run `pnpm app:install`. Do not edit
+> source or invent database/authentication steps. If installation fails, run
+> `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.

package/template/README.md

@@ -1,9 +1,8 @@
 # s-m-r-t SvelteKit starter
 
-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.
+This is the small, ground-up starting point for s-m-r-t 0.43.10. It contains
+one object and a profile-aware operational surface for local, self-hosted, and
+managed-cloud environments. It does not provision external providers.
 
 ## 1. Install and run
 
@@ -13,20 +12,33 @@ is declared in `packageManager`.
 ```bash
 pnpm install
 cp .env.example .env
-pnpm db:migrate
-pnpm check
-pnpm build
-pnpm dev
+pnpm app:install
 ```
 
-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.
+`app:install` validates the canonical profile, builds, migrates, initializes
+the secure local owner invitation, starts the production Node build on
+loopback, and opens that single-use invitation. Stop a running local app before
+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>`.
+
+`app:install`, `app:start`, `app:stop`, and `app:recover` are local-profile
+operations. Self-hosted and cloud web processes run the production Node build
+or container directly; workers use the separate worker commands below.
+
+If installation is interrupted after the invitation is created, rerun
+`pnpm app:start` and `pnpm app:open`; the private state directory retains the
+loopback handoff without printing its token. If that invitation expired or was
+lost, run `pnpm app:stop`, then `pnpm app:recover`, start, and open again.
+Recovery rotates only an
+unclaimed invitation and cannot replace an existing owner.
 
 `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.
+holds the shared application-operation lock while it applies the
+manifest-derived schema to SQLite. Re-run it after object changes.
 
 ## 2. Understand the generated files
 
@@ -95,15 +107,17 @@ construct the collection outside a SvelteKit request.
 
 ## 4. Initialize or migrate the database
 
-SQLite defaults to `./app.db`; override it with `DATABASE_URL` and
-`DATABASE_TYPE`.
+The canonical `runtime.profile` in `smrt.config.ts` defaults to `local`. Local
+SQLite, assets, secrets, backups, exports, and PID state live in the current
+user's operating-system data/state directories, outside this checkout.
+`SMRT_DATA_DIR` is rejected when it overlaps source.
 
 ```bash
 pnpm db:migrate
 ```
 
-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 current command is `smrt db:migrate`; deprecated `smrt db:setup` 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.
 
@@ -216,8 +230,8 @@ pnpm smrt objects
 pnpm smrt schema Item
 ```
 
-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
+The 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.
 
@@ -234,20 +248,15 @@ with:
 node .smrt/mcp-server/index.js
 ```
 
-The generated entry resolves its imports from this project, not from the CLI, so
-every module it imports must be a dependency here. `@modelcontextprotocol/server`,
-`@happyvertical/smrt-core`, and `@happyvertical/smrt-config` are always imported
-and are already declared. Two more are emitted only when your objects need them,
-and you must add them yourself:
-
-| Emitted when | Dependency | Already declared? |
-| --- | --- | --- |
-| An exposed object declares task actions (`@smrt({ mcp: { tasks: true } })`) | `@happyvertical/smrt-jobs` | No — add it |
-| An exposed object is tenant-scoped | `@happyvertical/smrt-tenancy` | Yes |
+The generated entry resolves its imports from this project, not from the CLI,
+so every module it imports must be a dependency here.
+`@modelcontextprotocol/server`, `@happyvertical/smrt-core`,
+`@happyvertical/smrt-config`, `@happyvertical/smrt-jobs`, and
+`@happyvertical/smrt-tenancy` are already declared for the default runtime and
+worker surfaces.
 
-Add the jobs package on the same release line as the other
-`@happyvertical/smrt-*` pins in `package.json`, then reinstall. Missing one of
-these fails at startup with `ERR_MODULE_NOT_FOUND` naming the package to add.
+Missing a dependency added by a custom MCP extension fails at startup with
+`ERR_MODULE_NOT_FOUND` naming the package to declare.
 
 WebMCP is wired at the root Provider as a read-only, authenticated browser
 surface. The template includes `@happyvertical/smrt-web` on the synchronized
@@ -321,3 +330,36 @@ 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.
+
+## Runtime profiles and deployment
+
+- `local`: SQLite, loopback single-use owner bootstrap, user-owned files, and
+  embedded/on-demand jobs.
+- `self-hosted`: PostgreSQL, public authentication, operator providers, and
+  separate workers. Copy `.env.self-hosted.example` to `.env.self-hosted` for
+  the service configuration. Separately create the ignored plain `.env` file
+  with `DATABASE_URL` and `POSTGRES_PASSWORD` for Compose interpolation, then
+  use Compose. Compose refuses to start when either secret is absent. Configure
+  installed authentication, asset, and secret readiness modules; each module
+  must probe its real provider before web or workers can start.
+- `cloud`: hosted identity, managed providers, required tenant context, and
+  scalable workers. `.env.cloud.example` records the composition boundary.
+
+The adapter-node `Dockerfile` and `compose.yaml` provide the production path.
+Compose gates the web and both workers on the one-shot, idempotent migration
+service. The runtime image retains the generated manifest and operator CLI for
+doctor/export/import. `pnpm worker` and `pnpm worker:schedule` are separate from
+the web process.
+Logical export/import is manifest-driven JSON and refuses a non-empty target;
+it orders parent tables first and defers nullable cycle edges until every row
+exists. Export reads all model tables from one transaction snapshot. Every
+schema-v2 export includes filesystem assets referenced by exported asset rows
+through a bounded, provider-neutral manifest with byte lengths and SHA-256
+digests. Import stages and verifies those assets before committing database
+rows; legacy database-only schema-v1 bundles are rejected with a version error.
+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.

package/template/compose.yaml

@@ -0,0 +1,56 @@
+x-runtime-environment: &runtime-environment
+  DATABASE_URL: ${DATABASE_URL:?Set DATABASE_URL in the ignored .env file}
+
+services:
+  web:
+    build: .
+    env_file: .env.self-hosted
+    environment: *runtime-environment
+    command: node build
+    ports:
+      - "3000:3000"
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+  worker:
+    build: .
+    env_file: .env.self-hosted
+    environment: *runtime-environment
+    command: node scripts/smrt-worker.mjs task
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+  schedule-worker:
+    build: .
+    env_file: .env.self-hosted
+    environment: *runtime-environment
+    command: node scripts/smrt-worker.mjs schedule
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+  migrate:
+    build:
+      context: .
+      target: build
+    env_file: .env.self-hosted
+    environment: *runtime-environment
+    command: pnpm app:setup
+    depends_on:
+      database:
+        condition: service_healthy
+  database:
+    image: postgres:18-alpine
+    environment:
+      POSTGRES_DB: smrt_app
+      POSTGRES_USER: smrt_app
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in the ignored .env file}
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U smrt_app"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+volumes:
+  postgres-data: