Build, inspect, test, and run an application

Choose a supported starting point

smrt-start is the public SvelteKit template, and the one smrt cookbook apply copies by default. It includes one Note model, SQLite, the application runtime from smrt-app-runtime mounted through hooks.server.ts, the AppShell root layout, an assistant, and generated interfaces. It ships no operator scripts; every lifecycle script is a smrt app command. Its vite.config.ts is the smrt() preset, with the consumed packages read from package.json in smrt.config.ts. A cookbook, from build-a-boilerplate or the CLI library, adds recipe packages on top of the same template.

• Clone smrt-start when you want the smallest working application with every layer visible.
• Use smrt cookbook apply when you have a cookbook; it pins the template to the CLI release.
• Use smrt init only to add framework files to an existing SvelteKit project.

Keep one short local loop

Start the Vite development server while you change models and pages. The framework plugins scan the object sources and refresh the local manifest, registration, types, routes, and knowledge artifact. Restart the server after you add a new object or change scanner inputs if the generated view does not update.

pnpm dev

# In a second terminal, inspect the generated project view.
pnpm smrt introspect
pnpm smrt doctor

# Before review, check types and produce the static build.
pnpm check
pnpm build

Use the CLI as the developer control surface

The CLI discovers project and installed-package manifests. It can inspect objects, generate interfaces, scaffold playground files, run diagnostics, and operate the configured development database. Generated object commands use the action lists in the model manifest.

• Use introspect, objects, schema, status, and doctor to inspect the project.
• doctor's agent-surface section reports the application's agent-addressable model tools and declared view intents from build artifacts alone. It starts no server and mounts no route.
• Use generate-types, generate-routes, generate-register, and generate-mcp for explicit generation tasks.
• Use playground init, playground list, and playground dev for component and package previews.
• Use the knowledge command family when the output is evidence for a coding agent.
• Use smrt app <operation> for the application lifecycle. The operations are install, setup, start, stop, recover, doctor, open, backup, export, import, migrate, and worker. Success output is JSON on stdout; a failure is one JSON envelope on stderr with exit code 1 and no secret values.
• Use smrt cookbook validate to check a cookbook against the recipe manifests. Use smrt cookbook apply to create a project from it. Use smrt kitchen to serve the planner on localhost and apply the cookbook it produces.
• Every db:* command resolves its database once. packages.cli.database.url from config wins, then DATABASE_URL with the engine from database.type or DATABASE_TYPE, then :memory:, which schema commands refuse.
• smrt db:diff --empty-text-as-null previews how many empty text values become NULL and smrt db:migrate --empty-text-as-null applies it. smrt db:migrate-qualified-names rewrites stored names declared through previousQualifiedNames; it is opt-in and idempotent, and smrt doctor --db counts what remains.

Treat the manifest as generated evidence

The scanner parses TypeScript syntax and never executes the source. It resolves supported class inheritance and converts the result into the manifest shape that migrations, tests, and interface generators consume. A scan is not a full TypeScript type check. Rebuild after source changes before you trust a generated artifact.

• The scanner excludes dependency, hidden, and generated directories by default.
• A scan diagnostic blocks production manifest generation instead of publishing a partial result.
• The runtime manifest supports registration. The separate knowledge artifact supports developer and coding-agent inspection.

Make migrations follow the model

Schema changes are computed from the current manifest. The CLI does not write migration files to review or commit. Build first so the manifest is current. Then inspect the status or diff before you apply the change. In smrt-start, the db:migrate script runs smrt app build and then smrt app migrate, which holds the operation lock around smrt db:migrate.

pnpm build
pnpm smrt db:status
pnpm smrt db:diff
pnpm smrt db:migrate --dry-run
pnpm smrt db:migrate

Give tests the same generated model

Every framework test project uses smrtVitestPlugin. It scans source at Vitest startup, loads installed manifests, and registers the classes that tests use. Restart Vitest after you add a model or field. Use the isolated database helpers for model and policy tests.

import { smrtVitestPlugin } from '@happyvertical/smrt-vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [smrtVitestPlugin()],
  test: {
    environment: 'node',
    setupFiles: ['@happyvertical/smrt-vitest/setup']
  }
});