@montytools/cli 0.4.1 → 0.5.0

package/bin/monty.mjs

@@ -16,6 +16,8 @@ import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { CATALOG, REGISTRIES } from "./catalog.mjs";
 import { CompileError, compileAppConfig } from "../lib/compile.mjs";
+import { manifestHash } from "../lib/schemaCodegen.mjs";
+import { readSchemaState, schemaPull, writeSchemaState } from "../lib/schemaPull.mjs";
 
 // MONTY_HOME overrides the state root (default ~/.monty): config.json,
 // apps/, and desktop.json all live under it. This is how a second, isolated
@@ -596,6 +598,63 @@ async function pull() {
 }
 
 // ── monty create ───────────────────────────────────────────────────────────
+// A CONFIG-ONLY app: no SPA at all — monty.config.ts is the whole app and
+// the platform shell renders it. The presence of index.html is the marker
+// (every SPA template ships one; the config-only scaffold never does).
+function isConfigOnlyApp(appDir) {
+  return !existsSync(join(appDir, "index.html"));
+}
+
+const CONFIG_ONLY_AGENTS_MD = `# This is a CONFIG-ONLY Monty app
+
+The entire app is \`monty.config.ts\`: tables (zod), derived fields
+(\`rollup\`/\`lookup\`/\`formula\`), \`metrics\`, \`settings\`, and \`pages\`.
+The Monty platform renders it — there is no src/, no React, no build.
+
+- Edit monty.config.ts, save; a running \`monty dev\` pushes the change to the
+  Studio within seconds (watch the terminal for instruction-shaped errors).
+- Formulas are strings in the Monty expression grammar, e.g.
+  \`formula(montyMoney(), "monthlySales * commissionRate")\` — fields declared
+  ABOVE the formula and \`metrics.<name>\` are in scope.
+- \`monty deploy\` publishes the config to the workspace (no bundle).
+- Need a bespoke page later? \`monty add page\` upgrades this app with a SPA
+  scaffold; the config keeps working unchanged.
+`;
+
+function writeConfigOnlyScaffold(target, { appId, slug, name, icon }) {
+  mkdirSync(target, { recursive: true });
+  writeFileSync(join(target, "monty.config.ts"), `import { defineApp } from "@montytools/sdk";
+
+// This file IS the app: tables, derived fields, metrics, settings, pages.
+// The Monty platform renders it — no src/, no build. Declare tables as zod
+// objects; derive with rollup()/lookup()/formula(); see AGENTS.md.
+export const app = defineApp({
+  id: "${appId}",
+  slug: "${slug}",
+  name: "${name}",
+  icon: "${icon}",
+  tables: {},
+});
+
+export type App = typeof app;
+`);
+  writeFileSync(join(target, "package.json"), JSON.stringify({
+    name: slug,
+    private: true,
+    type: "module",
+    dependencies: { "@montytools/sdk": "latest", zod: "^4.4.3" },
+  }, null, 2) + "\n");
+  writeFileSync(join(target, "tsconfig.json"), JSON.stringify({
+    compilerOptions: {
+      target: "ES2022", module: "ESNext", moduleResolution: "bundler",
+      strict: true, skipLibCheck: true, noEmit: true,
+    },
+    include: ["monty.config.ts"],
+  }, null, 2) + "\n");
+  writeFileSync(join(target, ".gitignore"), "node_modules/\n.monty/\n");
+  writeFileSync(join(target, "AGENTS.md"), CONFIG_ONLY_AGENTS_MD);
+}
+
 async function create() {
   const slug = rest.find((a) => !a.startsWith("--"));
   if (!slug || slug.length > 64 || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
@@ -652,6 +711,48 @@ async function create() {
   }
   mkdirSync(dirname(target), { recursive: true });
 
+  // DEFAULT: config-only — no SPA. monty.config.ts is the whole app and the
+  // platform shell renders it; \`monty add page\` scaffolds a SPA the moment a
+  // bespoke page is needed. \`--spa\` keeps the old full-SPA scaffold
+  // (\`--config-only\` stays accepted as the now-default no-op).
+  if (!rest.includes("--spa")) {
+    console.log(`create: ${slug} -> ${target} (config-only)`);
+    writeConfigOnlyScaffold(target, { appId, slug, name, icon });
+    // The user's brief lands at the top of AGENTS.md, same as SPA creates.
+    const brief = flag("description");
+    if (brief?.trim()) {
+      const agentsPath = join(target, "AGENTS.md");
+      writeFileSync(
+        agentsPath,
+        `# What to build: ${name}\n\n${brief.trim()}\n\n---\n\n` + readFileSync(agentsPath, "utf8"),
+      );
+      console.log("brief: AGENTS.md carries the app description");
+    }
+    const cBuildId = flag("build");
+    if (cBuildId && /^[a-z0-9]{10,64}$/i.test(cBuildId)) {
+      mkdirSync(join(target, ".monty"), { recursive: true });
+      writeFileSync(join(target, ".monty", "build"), cBuildId + "\n");
+      try {
+        await fetch(`${host}/api/build`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+          body: JSON.stringify({ buildId: cBuildId, slug }),
+        });
+      } catch { /* progress signal only */ }
+    }
+    if (!existsSync(join(target, "CLAUDE.md"))) {
+      try {
+        symlinkSync("AGENTS.md", join(target, "CLAUDE.md"));
+      } catch {
+        writeFileSync(join(target, "CLAUDE.md"), "@AGENTS.md\n");
+      }
+    }
+    installSkills({ appDir: target });
+    console.log(`created: ${target}`);
+    console.log(`next: cd ${target} && monty install && monty dev`);
+    return;
+  }
+
   // Template is bundled into the published package (../template). Fall back to
   // the monorepo path when running the CLI in-place during development.
   const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -819,7 +920,7 @@ async function freePort(start) {
 // Apps pin @montytools/sdk at scaffold time and go stale — the CLI knows the
 // minimum SDK its workflows need (e.g. tunnel-host allowlisting lives in the
 // SDK's vite plugin) and upgrades the app automatically before dev/deploy.
-const MIN_SDK = "0.1.5";
+const MIN_SDK = "0.2.0";
 const SDK_VITE_CACHE_STAMP = "sdk-vite-cache-version";
 
 function installedSdkVersion(appDir) {
@@ -1282,22 +1383,29 @@ async function dev() {
   const meta = await compileConfig(appDir);
   const cfg = loadConfig();
   const host = cfg?.host ?? DEFAULT_HOST;
+  // CONFIG-ONLY apps run no vite and no tunnel: `monty dev` is watch +
+  // compile + push — the platform shell renders the Studio channel.
+  const configOnly = isConfigOnlyApp(appDir);
   // Auto-pick a free port (agents run several apps side by side); an
   // explicit --port is honored strictly.
   const requested = flag("port");
-  const port = requested ? Number(requested) : await freePort(5173);
+  const port = configOnly ? null : requested ? Number(requested) : await freePort(5173);
 
-  const viteBin = resolveViteBin(appDir);
-  if (!viteBin) {
-    fail("VITE_MISSING", "vite is not installed in this app. Run `monty install`, then `monty dev` again.");
+  let child = null;
+  if (!configOnly) {
+    const viteBin = resolveViteBin(appDir);
+    if (!viteBin) {
+      fail("VITE_MISSING", "vite is not installed in this app. Run `monty install`, then `monty dev` again.");
+    }
+    console.log(`dev: starting vite on :${port} (app "${meta.slug}")`);
+    child = spawn(process.execPath, [viteBin, "dev", "--port", String(port), "--strictPort"], {
+      cwd: appDir,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } else {
+    console.log(`dev: config-only app "${meta.slug}" — no vite; watching monty.config.ts`);
   }
 
-  console.log(`dev: starting vite on :${port} (app "${meta.slug}")`);
-  const child = spawn(process.execPath, [viteBin, "dev", "--port", String(port), "--strictPort"], {
-    cwd: appDir,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
   let tunnelChild = null;
   let pubChild = null;
   let hbTimer = null;
@@ -1335,10 +1443,10 @@ async function dev() {
     sessionId,
     state: "starting",
     loggedIn,
-    appUrl: `http://localhost:${port}`,
+    appUrl: configOnly ? null : `http://localhost:${port}`,
     tunnelUrl: null,
     studioUrl: loggedIn ? `${host}/studio/${meta.slug}` : null,
-    previewUrl: loggedIn
+    previewUrl: loggedIn && !configOnly
       ? `${host}/studio/${meta.slug}?dev=${encodeURIComponent(`http://localhost:${port}`)}`
       : null,
     publishing: false,
@@ -1421,7 +1529,7 @@ async function dev() {
     try { tunnelChild?.kill(); } catch { /* already gone */ }
     // vite is a direct child (no npx wrapper), so this actually kills it —
     // a bare SIGTERM from the desktop must never orphan vite on the port.
-    try { child.kill(); } catch { /* already gone */ }
+    try { child?.kill(); } catch { /* already gone */ }
     sf.remove();
     logSink.close();
     await clearDevSession();
@@ -1435,7 +1543,7 @@ async function dev() {
     if (cronTimer) clearInterval(cronTimer);
     try { pubChild?.kill(); } catch { /* already gone */ }
     try { tunnelChild?.kill(); } catch { /* already gone */ }
-    try { child.kill(); } catch { /* already gone */ }
+    try { child?.kill(); } catch { /* already gone */ }
     console.log(`dev-session: superseded — ${fix}`);
     sf.remove(); // guarded — never deletes the new owner's file
     logSink.close();
@@ -1455,7 +1563,7 @@ async function dev() {
         headers: { authorization: `Bearer ${liveKey}`, "content-type": "application/json" },
         body: JSON.stringify({
           slug: meta.slug,
-          tunnelUrl: originUrl,
+          ...(originUrl !== undefined ? { tunnelUrl: originUrl } : {}),
           sessionId,
           // Keep claiming until the first successful registration, but only
           // within the lock's own 90s TTL window: after a takeover/crash the
@@ -1468,6 +1576,12 @@ async function dev() {
           icon: currentMeta.icon,
           buildId,
           schemaJson: currentMeta.schemaJson,
+          // App Manifest v2 (docs/manifest-v2.md) — present only for V2
+          // configs; the host forwards it to devManifestJson (Stage 3 wiring).
+          manifest: currentMeta.manifest,
+          // The CAS base for the Studio channel (see `monty schema pull`).
+          baseManifestHash:
+            currentMeta.manifest !== undefined ? readSchemaState(appDir)?.hash : undefined,
           // The expose block rides the same compile as the schema — the dev
           // visitor preview is gated on it (devExposureJson).
           exposure: currentMeta.exposure,
@@ -1480,6 +1594,11 @@ async function dev() {
           stopSuperseded(data.fix ?? "A newer `monty dev` session is active for this app.");
           return false;
         }
+        if (data?.code === "MANIFEST_DRIFT") {
+          // Remote schema edits (another agent, via the API) — the terminal
+          // the building agent is watching gets the fix, invariant #4.
+          console.log(`schema drift (remote changes):${data.summary ? `\n${data.summary}` : ""}`);
+        }
         console.log(`dev-session: ${data?.code ?? r.status}${data?.fix ? ` — ${data.fix}` : ""}`);
         // A dead key is a SIGNED-OUT session — advertise it so the desktop
         // (which owns the session) can surface sign-in instead of letting
@@ -1489,6 +1608,11 @@ async function dev() {
         }
         return false;
       }
+      if (currentMeta.manifest !== undefined) {
+        // This beat's manifest is now the stored Studio manifest — the new
+        // CAS base for both channels' future pushes.
+        try { writeSchemaState(appDir, manifestHash(currentMeta.manifest)); } catch { /* state is advisory */ }
+      }
       if (!registeredOnce) {
         registeredOnce = true;
         sf.write({ state: "online", loggedIn: true, lastHeartbeatAt: Date.now() });
@@ -1540,7 +1664,8 @@ async function dev() {
       return;
     }
     await clearDevSession();
-    let originUrl = `http://localhost:${port}`;
+    // Config-only sessions register WITHOUT an origin — nothing to iframe.
+    let originUrl = configOnly ? undefined : `http://localhost:${port}`;
     let tunnelUpdate = Promise.resolve();
     let tunnelVersion = 0;
     async function activateTunnelUrl(url, { initial = false } = {}) {
@@ -1579,7 +1704,7 @@ async function dev() {
         console.log("tunnel: URL update failed — waiting for the next tunnel URL");
       });
     };
-    if (!rest.includes("--no-tunnel")) {
+    if (!configOnly && !rest.includes("--no-tunnel")) {
       console.log("tunnel: starting (cloudflared quick tunnel)…");
       // cloudflared output is teed to dev.log only (the terminal stays quiet,
       // exactly as today) — post-mortems get the tunnel noise.
@@ -1603,10 +1728,28 @@ async function dev() {
     hbTimer = setInterval(() => void heartbeat(originUrl), DEV_SESSION_HEARTBEAT_MS);
   }
 
+  if (configOnly) {
+    sf.write({ state: "ready" });
+    console.log(`data: sandboxed to "${meta.slug}#dev" (Studio sandbox; Live records untouched)`);
+    console.log("ready: config-only — the Studio renders this app; edits push on save");
+    void startDevSession();
+    // Config edits should reach the Studio in seconds, not a heartbeat:
+    // watch the mtime and trigger an early beat (which recompiles + pushes).
+    const cfgWatch = setInterval(() => {
+      try {
+        if (statSync(configPath).mtimeMs !== configMtime) void heartbeat(undefined);
+      } catch { /* transient fs hiccup */ }
+    }, 2000);
+    const stopWatch = () => clearInterval(cfgWatch);
+    process.on("SIGINT", stopWatch);
+    process.on("SIGTERM", stopWatch);
+    process.on("SIGHUP", stopWatch);
+  }
+
   let announced = false;
   const viteOutTee = logSink.source();
   const viteErrTee = logSink.source();
-  child.stdout.on("data", (chunk) => {
+  child?.stdout.on("data", (chunk) => {
     const text = chunk.toString();
     process.stdout.write(text);
     viteOutTee(chunk);
@@ -1623,16 +1766,16 @@ async function dev() {
   });
   // vite stderr is where build errors and the SDK's browser-error mirror
   // land — piped (was inherit) so `monty logs` sees them too.
-  child.stderr.on("data", (chunk) => {
+  child?.stderr.on("data", (chunk) => {
     process.stderr.write(chunk);
     viteErrTee(chunk);
   });
-  child.on("error", (e) => {
+  child?.on("error", (e) => {
     void endSession().then(() => {
       fail("VITE_SPAWN_FAILED", `Could not start vite: ${e?.message ?? e}. Run \`monty install\`, then retry.`);
     });
   });
-  child.on("exit", (code) => {
+  child?.on("exit", (code) => {
     viteOutTee.flush();
     viteErrTee.flush();
     void endSession().then(() => process.exit(code ?? 0));
@@ -1881,11 +2024,154 @@ function resolveComponent(name) {
   return name;
 }
 
+// ── monty add page <name> ──────────────────────────────────────────────────
+// Upgrades an app with a bespoke (custom) page: scaffolds the SPA on first
+// use (config-only apps gain src/ + vite from the template — their
+// monty.config.ts and AGENTS.md stay untouched), writes the page route, and
+// registers `pages.<name> = { kind: "custom", path: "/<name>" }` so the
+// platform shell mounts it. The Shopify model: system pages stay
+// shell-rendered; only this page is the app's own code.
+async function addPage(appDir, pageName) {
+  if (!pageName || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(pageName) || pageName.length > 32) {
+    fail("INVALID_PAGE", 'Usage: monty add page <name> — lowercase letters/digits with single hyphens, max 32 chars (e.g. "reports").');
+  }
+  const configPath = join(appDir, "monty.config.ts");
+  if (!existsSync(configPath)) {
+    fail("NO_CONFIG", `No monty.config.ts in ${appDir} — run this inside a Monty app.`);
+  }
+  const config = readFileSync(configPath, "utf8");
+  const appName = config.match(/name: "([^"]*)"/)?.[1] ?? pageName;
+  const routeFile = join(appDir, "src", "routes", `${pageName}.tsx`);
+  if (existsSync(routeFile)) {
+    fail("PAGE_EXISTS", `src/routes/${pageName}.tsx already exists. Edit it, or pick a different page name.`);
+  }
+  if (config.includes(`"/${pageName}"`) || new RegExp(`^\\s*${pageName}:`, "m").test(config)) {
+    console.log(`note: "${pageName}" may already be declared in monty.config.ts — check its pages block after this.`);
+  }
+
+  // First custom page on a config-only app: bring in the SPA scaffold.
+  if (isConfigOnlyApp(appDir)) {
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+    const templateDir = [
+      join(pkgRoot, "template"),
+      join(pkgRoot, "..", "template"),
+    ].find((d) => existsSync(join(d, "monty.config.ts")));
+    if (!templateDir) {
+      fail("TEMPLATE_MISSING", "The Monty app template is missing from this CLI install. Reinstall the monty CLI.");
+    }
+    console.log(`add page: upgrading config-only app with the SPA scaffold`);
+    cpSync(templateDir, appDir, {
+      recursive: true,
+      force: false, // existing files (config, AGENTS.md, package.json…) win
+      filter: (src) => {
+        const base = basename(src);
+        if (["node_modules", "dist", ".monty", ".env.local", "routeTree.gen.ts"].includes(base)) return false;
+        // The app keeps its own identity files.
+        if (["monty.config.ts", "AGENTS.md", "CLAUDE.md"].includes(base)) return false;
+        return true;
+      },
+    });
+    // gitignore ships name-mangled in the published bundle (see create()).
+    if (existsSync(join(appDir, "gitignore")) && !existsSync(join(appDir, ".gitignore"))) {
+      renameSync(join(appDir, "gitignore"), join(appDir, ".gitignore"));
+    }
+    // Merge the template's SPA deps/scripts into the app's package.json —
+    // the config-only one has only sdk+zod and no scripts.
+    const tplPkg = JSON.parse(readFileSync(join(templateDir, "package.json"), "utf8"));
+    const pkgPath = join(appDir, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    pkg.scripts = { ...tplPkg.scripts, ...pkg.scripts };
+    pkg.dependencies = { ...tplPkg.dependencies, ...pkg.dependencies };
+    pkg.devDependencies = { ...tplPkg.devDependencies, ...pkg.devDependencies };
+    // The published template pins the sdk; a workspace app may carry
+    // workspace:* — the merge above keeps the app's existing pin either way.
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    const htmlPath = join(appDir, "index.html");
+    if (existsSync(htmlPath)) {
+      writeFileSync(htmlPath, readFileSync(htmlPath, "utf8").replace(/<title>[^<]*<\/title>/, `<title>${appName}</title>`));
+    }
+    // Client env for the SPA half, same as create().
+    if (!existsSync(join(appDir, ".env.local"))) {
+      try {
+        const { host } = loadConfig();
+        const cfg = await fetch(`${host}/api/config`).then((r) => r.json());
+        writeFileSync(join(appDir, ".env.local"), `VITE_CONVEX_URL=${cfg.convexUrl}\nVITE_CLERK_PUBLISHABLE_KEY=${cfg.clerkPublishableKey}\n`);
+        console.log("config: .env.local written");
+      } catch {
+        console.log("config: WARNING — could not fetch client config; copy .env.example to .env.local manually");
+      }
+    }
+    // The template's starter index route assumes it IS the app — for a page
+    // upgrade the shell owns the app; drop the starter so the page below is
+    // the only route beside __root.
+    const starter = join(appDir, "src", "routes", "index.tsx");
+    if (existsSync(starter)) rmSync(starter);
+    appendFileSync(
+      join(appDir, "AGENTS.md"),
+      `\n---\n\n## Custom pages\n\nThis app now has a SPA half (src/) serving CUSTOM pages inside the\nplatform shell. Each page = a route in src/routes/ + a\n\`pages.<name>: { kind: "custom", path: "/<name>" }\` entry in\nmonty.config.ts. System pages (views, dashboards) stay config-rendered —\nonly build bespoke UI here. \`monty dev\` serves both; \`monty deploy\`\npublishes both.\n`,
+    );
+  }
+
+  // The page route: a real, working start — SDK data hooks, shell-aware.
+  mkdirSync(dirname(routeFile), { recursive: true });
+  writeFileSync(routeFile, `import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/${pageName}")({
+  component: ${pageComponentName(pageName)},
+});
+
+// A CUSTOM page: bespoke UI mounted inside the platform shell at
+// /apps/<slug>/${pageName}. Data comes from @montytools/sdk hooks
+// (useList/useInsert/…) against the same tables the shell renders.
+function ${pageComponentName(pageName)}() {
+  return (
+    <main className="p-6">
+      <h1 className="text-lg font-semibold">${appName} — ${pageName}</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        Build this page. It ships with the app on the next \`monty deploy\`.
+      </p>
+    </main>
+  );
+}
+`);
+  console.log(`page: src/routes/${pageName}.tsx`);
+
+  // Register the page in the config's pages block (insert or create).
+  const entry = `    ${JSON.stringify(pageName).includes("-") ? JSON.stringify(pageName) : pageName}: { kind: "custom", path: "/${pageName}" },`;
+  let next = null;
+  if (/^(\s*)pages:\s*{/m.test(config)) {
+    next = config.replace(/^(\s*)pages:\s*{/m, (m) => `${m}\n${entry}`);
+  } else {
+    // No pages block: add one right before the config's closing `});`.
+    const close = config.lastIndexOf("});");
+    if (close !== -1) {
+      next = config.slice(0, close) + `  pages: {\n${entry}\n  },\n` + config.slice(close);
+    }
+  }
+  if (next) {
+    writeFileSync(configPath, next);
+    console.log(`config: pages.${pageName} registered in monty.config.ts`);
+  } else {
+    console.log(`config: could not auto-edit monty.config.ts — add this to defineApp yourself:\n  pages: { ${pageName}: { kind: "custom", path: "/${pageName}" } }`);
+  }
+
+  console.log(`added: custom page "${pageName}"`);
+  console.log(`next: monty install && monty dev — the shell mounts /${pageName} live; \`monty deploy\` publishes it.`);
+}
+
+function pageComponentName(pageName) {
+  return pageName.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join("") + "Page";
+}
+
 async function add() {
   const appDir = requireAppDir("add");
   const names = rest.filter((a) => !a.startsWith("--"));
   if (names.length === 0) {
-    fail("NO_COMPONENT", "Usage: monty add <name...> — run `monty components` to see what's available.");
+    fail("NO_COMPONENT", "Usage: monty add <name...> — run `monty components` to see what's available (or `monty add page <name>` for a custom page).");
+  }
+  if (names[0] === "page") {
+    await addPage(appDir, names[1]);
+    return;
   }
   const items = names.flatMap((n) => [resolveComponent(n), ...(CATALOG[n]?.also ?? [])]);
 
@@ -2015,16 +2301,24 @@ async function deploy() {
   const meta = await compileConfig(appDir);
   console.log(`compile: ok (app "${meta.slug}", ${Object.keys(meta.schemaJson.tables).length} tables)`);
 
-  // 2) Fail fast locally before any upload. Build FIRST — it also generates
-  //    src/routeTree.gen.ts, without which tsc fails on a fresh checkout.
-  run(appDir, "build", ["npx", "vite", "build"],
-    "The production build failed. Read the vite error above; it names the file to fix.");
-  run(appDir, "typecheck", ["npx", "tsc", "--noEmit"],
-    "TypeScript errors above. Fix them in the listed files; `monty deploy` never uploads code that does not compile.");
+  // CONFIG-ONLY apps publish the manifest alone: no vite build, no bundle —
+  // the platform shell renders the app.
+  const configOnly = isConfigOnlyApp(appDir);
+  if (!configOnly) {
+    // 2) Fail fast locally before any upload. Build FIRST — it also generates
+    //    src/routeTree.gen.ts, without which tsc fails on a fresh checkout.
+    run(appDir, "build", ["npx", "vite", "build"],
+      "The production build failed. Read the vite error above; it names the file to fix.");
+    run(appDir, "typecheck", ["npx", "tsc", "--noEmit"],
+      "TypeScript errors above. Fix them in the listed files; `monty deploy` never uploads code that does not compile.");
+  } else if (!meta.manifest) {
+    fail("MANIFEST_MISSING",
+      "This config-only app compiled without a manifest — that should be impossible (forceManifest). Re-run `monty install` to refresh the SDK, then retry.");
+  }
 
   // 3) Multipart POST to the host.
   const dist = join(appDir, "dist");
-  const files = walk(dist);
+  const files = configOnly ? [] : walk(dist);
   const buildFile = join(appDir, ".monty", "build");
   if (existsSync(buildFile)) {
     meta.buildId = readFileSync(buildFile, "utf8").trim();
@@ -2082,6 +2376,13 @@ async function deploy() {
       console.log(`source: ${(packed.buf.byteLength / 1024).toFixed(0)} KB snapshot rides this publish (restore anywhere: monty pull ${meta.slug})`);
     }
   }
+  // V2 schema CAS: prove which stored manifest this checkout last synced,
+  // so an API/MCP edit made meanwhile surfaces as MANIFEST_DRIFT instead of
+  // being clobbered (fix: `monty schema pull`).
+  if (meta.manifest !== undefined) {
+    const state = readSchemaState(appDir);
+    if (state?.hash) meta.baseManifestHash = state.hash;
+  }
   form.set("monty", JSON.stringify(meta));
   let total = 0;
   for (const file of files) {
@@ -2090,7 +2391,11 @@ async function deploy() {
     total += buf.byteLength;
     form.set(rel, new Blob([buf]), rel);
   }
-  console.log(`upload: ${files.length} files, ${(total / 1024).toFixed(0)} KB -> ${config.host}/api/deploy`);
+  console.log(
+    configOnly
+      ? `upload: config-only (manifest, no bundle) -> ${config.host}/api/deploy`
+      : `upload: ${files.length} files, ${(total / 1024).toFixed(0)} KB -> ${config.host}/api/deploy`,
+  );
   const res = await fetch(`${config.host}/api/deploy`, {
     method: "POST",
     headers: { authorization: `Bearer ${config.key}` },
@@ -2098,10 +2403,17 @@ async function deploy() {
   });
   const body = await res.json().catch(() => null);
   if (!res.ok || !body?.ok) {
+    if (body?.code === "MANIFEST_DRIFT" && body?.summary) {
+      console.log(`schema drift (remote changes):\n${body.summary}`);
+    }
     fail(body?.code ?? `HTTP_${res.status}`, body?.fix ?? "Unexpected server response — is the Monty host reachable?");
   }
   console.log(`origin: ${body.origin}`);
   console.log(`deployed: ${body.url} (version ${body.version})`);
+  // The manifest just published IS the new CAS base.
+  if (meta.manifest !== undefined) {
+    writeSchemaState(appDir, manifestHash(meta.manifest));
+  }
   // Stamp what was published — pull uses this to tell "unchanged since last
   // sync" from "locally modified".
   if (sourceHash) {
@@ -2194,7 +2506,9 @@ function discoverFnExports(serverEntry) {
 // Studio heartbeat's last good schema through transient config breakage.
 async function compileConfig(appDir, { soft = false } = {}) {
   try {
-    return await compileAppConfig(appDir);
+    // Config-only apps (no SPA) always compile a manifest: the platform
+    // shell is their only renderer.
+    return await compileAppConfig(appDir, { forceManifest: isConfigOnlyApp(appDir) });
   } catch (e) {
     if (e instanceof CompileError) {
       if (soft) {
@@ -2552,6 +2866,36 @@ if (command !== "dev" && command !== "logs") {
   installSkills({ appDir: findAppRoot(process.cwd()) });
 }
 
+// ── monty schema — the schema-as-data door of the CLI ─────────────────────
+// `monty schema pull [slug] [--force]`: regenerate monty.config.ts from the
+// app's stored Live manifest (after another agent edited it via the API).
+// Distinct from `monty pull`, which restores the whole source snapshot.
+async function schemaCmd() {
+  const verb = rest[0];
+  if (verb !== "pull") {
+    console.log("usage: monty schema pull [slug] [--force]");
+    console.log("  pull   regenerate monty.config.ts from the app's stored manifest (.bak kept; --force discards local schema edits)");
+    process.exit(verb ? 1 : 0);
+  }
+  const { host, key } = loadConfig() ?? {};
+  if (!key) fail("NOT_LOGGED_IN", "Run `monty login` first.");
+  const appDir = findAppRoot(process.cwd()) ?? process.cwd();
+  let slug = rest.slice(1).find((a) => !a.startsWith("--"));
+  if (!slug) {
+    try {
+      slug = (await compileAppConfig(appDir)).slug;
+    } catch {
+      fail("INVALID_SLUG", "Pass the app slug (monty schema pull <slug>) — no compilable monty.config.ts here to read it from.");
+    }
+  }
+  await schemaPull({
+    appDir, host, key, slug,
+    force: rest.includes("--force"),
+    compileAppConfig,
+    fail,
+  });
+}
+
 switch (command) {
   case "login":
     await login();
@@ -2613,19 +2957,22 @@ switch (command) {
   case "data":
     await data();
     break;
+  case "schema":
+    await schemaCmd();
+    break;
   case "secret":
     await secret();
     break;
   default:
     console.log("usage: monty <login|create|pull|commit|log|current|select|apps|install|dev|logs|build|typecheck|add|components|docs|deploy|data|skills>");
     console.log("  login       [--host <url>] [--key <mk_...>]  sign in (opens your browser to authorize)");
-    console.log("  create      <slug> [--name N] [--icon I] [--build ID]  register + stamp a new app into ~/.monty/apps/<id> (needs login)");
+    console.log("  create      <slug> [--name N] [--icon I] [--spa]  register a new app (config-only by default; --spa scaffolds the full SPA)");
     console.log("  pull        <slug> [--version H] [--force]  restore the app's source snapshot (latest, or one from `monty log`)");
     console.log("  commit      [-m \"message\"]                  version the app's source in the workspace without publishing");
     console.log("  log         [slug]                          the app's source version history (commits + publishes)");
     console.log("  dev         [--port N] [--no-tunnel] [--takeover]  run the app in Studio, or attach to a running session (sandboxed data)");
     console.log("  logs        [-n N] [-f]                     read/follow the dev shell log (vite output, browser errors, publish results)");
-    console.log("  add         <name...>                      install curated UI components (see `monty components`)");
+    console.log("  add         <name...> | page <name>         install UI components, or scaffold a custom page (`monty add page reports`)");
     console.log("  components  [query]                        list the curated component catalog");
     console.log("  docs        <name>                         view a component's source before installing");
     console.log("  current                                     which app folder am I in?");
@@ -2636,6 +2983,7 @@ switch (command) {
     console.log("  typecheck                                   typecheck (builds first if needed)");
     console.log("  deploy                                      build + upload this app straight to Live");
     console.log("  data        <verb> [table] [flags]          read/write an app's records from the terminal (`monty data` for verbs)");
+    console.log("  schema      pull [slug] [--force]           regenerate monty.config.ts from the app's stored manifest (schema-as-data)");
     console.log("  skills                                      install/refresh the agent build skill");
     process.exit(command ? 1 : 0);
 }

package/lib/compile.mjs

@@ -19,7 +19,7 @@ export class CompileError extends Error {
 // Throws CompileError:
 // - CONFIG_BUNDLE_FAILED — esbuild could not bundle (usually unlinked deps)
 // - CONFIG_COMPILE_FAILED — the config threw while loading
-export async function compileAppConfig(appDir) {
+export async function compileAppConfig(appDir, { forceManifest = false } = {}) {
   appDir = resolve(appDir); // esbuild requires an absolute absWorkingDir
   // esbuild is a dependency of THIS package (@montytools/cli), so resolution
   // from here works for any caller — no per-script resolution dance.
@@ -31,7 +31,7 @@ export async function compileAppConfig(appDir) {
   writeFileSync(entry, [
     `import { app } from "../monty.config";`,
     `import { compileApp } from "@montytools/sdk/compile";`,
-    `process.stdout.write(JSON.stringify(compileApp(app)));`,
+    `process.stdout.write(JSON.stringify(compileApp(app, { forceManifest: ${forceManifest} })));`,
   ].join("\n"));
   try {
     await build({

package/lib/schemaCodegen.mjs

@@ -0,0 +1,196 @@
+// Manifest → monty.config.ts codegen + the canonical manifest hash.
+//
+// `monty schema pull` regenerates the whole config from the app's stored
+// App Manifest v2. Regeneration is LOSSLESS for config-only apps because
+// every V2 surface — including formulas, which are expression STRINGS — is
+// data in the manifest; there is no code in a config that the manifest
+// doesn't carry. The emitted file uses the same SDK constructors an agent
+// would write by hand, so pulled configs and authored configs are the same
+// dialect.
+//
+// The hash mirrors packages/backend/convex/lib/manifestValidate.ts exactly:
+// sha256 over a SORTED-KEY stringify (representation-independent — Convex
+// does not guarantee object key order; declaration order travels in the
+// explicit `order` arrays).
+
+import { createHash } from "node:crypto";
+
+export function stableStringify(v) {
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  if (typeof v === "object" && v !== null) {
+    const keys = Object.keys(v).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(v) ?? "null";
+}
+
+export function manifestHash(manifest) {
+  return createHash("sha256").update(stableStringify(manifest)).digest("hex");
+}
+
+// ── zod/SDK source emission ────────────────────────────────────────────────
+
+const IMPORTABLE = [
+  "defineApp", "formula", "lookup", "montyDate", "montyFileSchema",
+  "montyMember", "montyMoney", "montyPercent", "montyRef", "rollup", "self",
+];
+
+function fieldsInOrder(section) {
+  const order = Array.isArray(section.order) ? section.order : Object.keys(section.fields);
+  return order.map((name) => [name, section.fields[name]]);
+}
+
+function storedSource(spec, used) {
+  let src;
+  switch (spec.type) {
+    case "string": src = "z.string()"; break;
+    case "number": src = "z.number()"; break;
+    case "boolean": src = "z.boolean()"; break;
+    case "money": used.add("montyMoney"); src = "montyMoney()"; break;
+    case "percent": used.add("montyPercent"); src = "montyPercent()"; break;
+    case "date": used.add("montyDate"); src = "montyDate()"; break;
+    case "member": used.add("montyMember"); src = "montyMember()"; break;
+    case "file": used.add("montyFileSchema"); src = "montyFileSchema"; break;
+    case "ref":
+      used.add("montyRef");
+      src = `montyRef(${JSON.stringify(spec.table)})`;
+      break;
+    case "enum":
+      src = `z.enum(${JSON.stringify(spec.values)})`;
+      break;
+    default:
+      // json: the manifest carries no deep shape (schemaJson owns storage
+      // validation) — z.any() keeps the field writable; refine by hand.
+      src = "z.any()";
+  }
+  if (spec.optional) src += ".optional()";
+  return src;
+}
+
+function outputSource(type, used) {
+  switch (type) {
+    case "money": used.add("montyMoney"); return "montyMoney()";
+    case "percent": used.add("montyPercent"); return "montyPercent()";
+    case "date": used.add("montyDate"); return "montyDate()";
+    case "member": used.add("montyMember"); return "montyMember()";
+    case "number": return "z.number()";
+    case "string": return "z.string()";
+    case "boolean": return "z.boolean()";
+    default: return "z.string()";
+  }
+}
+
+function rollupSource(spec, used, indent) {
+  used.add("rollup");
+  const pad = " ".repeat(indent);
+  const lines = [`from: ${JSON.stringify(spec.from)},`];
+  if (spec.where !== undefined) {
+    const entries = Object.entries(spec.where).map(([k, v]) => {
+      if (typeof v === "object" && v !== null && typeof v.self === "string") {
+        used.add("self");
+        return `${JSON.stringify(k)}: self(${JSON.stringify(v.self)})`;
+      }
+      return `${JSON.stringify(k)}: ${JSON.stringify(v)}`;
+    });
+    lines.push(`where: { ${entries.join(", ")} },`);
+  }
+  if (spec.op === "sum") lines.push(`sum: ${JSON.stringify(spec.sumField)},`);
+  else lines.push("count: true,");
+  if (spec.over !== undefined) lines.push(`over: ${JSON.stringify(spec.over)},`);
+  if (spec.range !== undefined) lines.push(`range: ${JSON.stringify(spec.range)},`);
+  const body = lines.map((l) => `${pad}  ${l}`).join("\n");
+  return `rollup(${outputSource(spec.output, used)}, {\n${body}\n${pad}})`;
+}
+
+function fieldSource(spec, used, indent) {
+  switch (spec.kind) {
+    case "stored":
+      return storedSource(spec, used);
+    case "formula":
+      used.add("formula");
+      return `formula(${outputSource(spec.output, used)}, ${JSON.stringify(spec.expr)})`;
+    case "lookup":
+      used.add("lookup");
+      return `lookup(${outputSource(spec.output, used)}, { ref: ${JSON.stringify(spec.ref)}, field: ${JSON.stringify(spec.field)} })`;
+    case "rollup":
+      return rollupSource(spec, used, indent);
+    default:
+      return "z.any()";
+  }
+}
+
+function settingsFieldSource(spec, defaultValue, used) {
+  let src = storedSource({ ...spec, optional: undefined }, used);
+  if (defaultValue !== undefined) src += `.default(${JSON.stringify(defaultValue)})`;
+  else if (spec.optional) src += ".optional()";
+  return src;
+}
+
+/** The generated monty.config.ts source for a manifest document. */
+export function manifestToConfig(manifest, { name, icon } = {}) {
+  const used = new Set(["defineApp"]);
+  const out = [];
+
+  out.push("  tables: {");
+  for (const [tableName, table] of Object.entries(manifest.tables)) {
+    out.push(`    ${JSON.stringify(tableName)}: z.object({`);
+    for (const [field, spec] of fieldsInOrder(table)) {
+      out.push(`      ${JSON.stringify(field)}: ${fieldSource(spec, used, 6)},`);
+    }
+    out.push("    }),");
+  }
+  out.push("  },");
+
+  if (manifest.metrics !== undefined) {
+    out.push("  metrics: {");
+    for (const [name2, spec] of Object.entries(manifest.metrics)) {
+      out.push(`    ${JSON.stringify(name2)}: ${rollupSource(spec, used, 4)},`);
+    }
+    out.push("  },");
+  }
+
+  if (manifest.settings !== undefined) {
+    out.push("  settings: z.object({");
+    const defaults = manifest.settings.defaults ?? {};
+    for (const [field, spec] of fieldsInOrder(manifest.settings)) {
+      out.push(`    ${JSON.stringify(field)}: ${settingsFieldSource(spec, defaults[field], used)},`);
+    }
+    out.push("  }),");
+  }
+
+  if (manifest.pages !== undefined) {
+    out.push(`  pages: ${JSON.stringify(manifest.pages, null, 2).replace(/\n/g, "\n  ")},`);
+  }
+
+  if (manifest.datasets !== undefined) {
+    out.push("  datasets: {");
+    for (const [name2, ds] of Object.entries(manifest.datasets)) {
+      out.push(`    ${JSON.stringify(name2)}: z.object({`);
+      for (const [field, spec] of fieldsInOrder(ds)) {
+        out.push(`      ${JSON.stringify(field)}: ${fieldSource(spec, used, 6)},`);
+      }
+      out.push("    }),");
+    }
+    out.push("  },");
+  }
+
+  const sdkImports = IMPORTABLE.filter((n) => used.has(n));
+  return [
+    `import { z } from "zod";`,
+    `import {`,
+    ...sdkImports.map((n) => `  ${n},`),
+    `} from "@montytools/sdk";`,
+    ``,
+    `// Regenerated by \`monty schema pull\` from the app's stored manifest.`,
+    `// Edit freely — \`monty dev\` / \`monty deploy\` push changes back; another`,
+    `// editor's remote changes surface as MANIFEST_DRIFT (then pull again).`,
+    `export const app = defineApp({`,
+    `  slug: ${JSON.stringify(manifest.slug)},`,
+    ...(name ? [`  name: ${JSON.stringify(name)},`] : []),
+    ...(icon ? [`  icon: ${JSON.stringify(icon)},`] : []),
+    ...out,
+    `});`,
+    `export type App = typeof app;`,
+    ``,
+  ].join("\n");
+}

package/lib/schemaPull.mjs

@@ -0,0 +1,83 @@
+// `monty schema pull` — regenerate monty.config.ts from the app's stored
+// Live manifest (the schema-as-data flow: another agent may have edited the
+// schema via the API/MCP; this brings the code checkout back in sync).
+// Distinct from `monty pull`, which restores the whole SOURCE SNAPSHOT.
+//
+// Safety: refuses when the local config has schema changes that never
+// reached the registry (compile-and-compare against the base hash recorded
+// in .monty/schema.json) — "deploy or discard", like git with a dirty tree.
+// The old file is backed up beside the new one on every overwrite.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { manifestHash, manifestToConfig } from "./schemaCodegen.mjs";
+
+const STATE_FILE = ["schema.json"]; // .monty/schema.json
+
+export function readSchemaState(appDir) {
+  try {
+    return JSON.parse(readFileSync(join(appDir, ".monty", ...STATE_FILE), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Record the hash of the manifest this checkout last synced with the
+ * registry (written after every successful push and every pull — the CAS
+ * base for the next push). */
+export function writeSchemaState(appDir, hash) {
+  const dir = join(appDir, ".monty");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, ...STATE_FILE), JSON.stringify({ hash, syncedAt: Date.now() }) + "\n");
+}
+
+export async function schemaPull({ appDir, host, key, slug, force, compileAppConfig, fail }) {
+  const res = await fetch(`${host}/api/schema?slug=${encodeURIComponent(slug)}`, {
+    headers: { authorization: `Bearer ${key}` },
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !body?.ok) {
+    fail(body?.code ?? `HTTP_${res.status}`, body?.fix ?? "Could not fetch the app's schema — check the connection and `monty login`.");
+  }
+  if (!body.manifest) {
+    fail(
+      "NO_MANIFEST",
+      `"${slug}" has no stored App Manifest (it is a V1 app or has never pushed one). Author monty.config.ts with V2 features and run \`monty dev\` or \`monty deploy\` first.`,
+    );
+  }
+
+  const configPath = join(appDir, "monty.config.ts");
+  if (existsSync(configPath) && !force) {
+    // Dirty check: does the local config compile to the manifest this
+    // checkout last synced? If not, pulling would clobber local edits.
+    const state = readSchemaState(appDir);
+    let localHash = null;
+    try {
+      const compiled = await compileAppConfig(appDir);
+      localHash = compiled.manifest ? manifestHash(compiled.manifest) : null;
+    } catch {
+      // A config that doesn't compile can't be proven clean — refuse without
+      // --force rather than silently discarding whatever it holds.
+      fail(
+        "SCHEMA_DIRTY",
+        "monty.config.ts does not compile, so local schema edits cannot be verified against the registry. Fix it and deploy, or re-run with --force to REPLACE it (a .bak is kept).",
+      );
+    }
+    const cleanAgainst = state?.hash ?? body.hash;
+    if (localHash !== null && localHash !== cleanAgainst && localHash !== body.hash) {
+      fail(
+        "SCHEMA_DIRTY",
+        "monty.config.ts has schema changes that never reached the registry. Push them first (`monty dev` save or `monty deploy`), or discard them with --force (a .bak is kept).",
+      );
+    }
+  }
+
+  if (existsSync(configPath)) {
+    renameSync(configPath, `${configPath}.bak`);
+    console.log(`backup: monty.config.ts.bak`);
+  }
+  writeFileSync(configPath, manifestToConfig(body.manifest, { name: body.name, icon: body.icon ?? undefined }));
+  writeSchemaState(appDir, body.hash);
+  console.log(`schema: pulled "${slug}" (${Object.keys(body.manifest.tables).length} tables) -> monty.config.ts`);
+  console.log(`base:   ${body.hash.slice(0, 12)} (.monty/schema.json — the CAS base for the next push)`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montytools/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TomasMonty/monty-v2.git",
@@ -21,8 +21,9 @@
   },
   "scripts": {
     "prepack": "node scripts/bundle-template.mjs",
-    "typecheck": "node --check bin/monty.mjs && node --check lib/compile.mjs",
-    "postinstall": "node bin/postinstall.mjs"
+    "typecheck": "node --check bin/monty.mjs && node --check lib/compile.mjs && node --check lib/schemaCodegen.mjs && node --check lib/schemaPull.mjs && node --check scripts/schema-roundtrip.mjs",
+    "postinstall": "node bin/postinstall.mjs",
+    "test:roundtrip": "node scripts/schema-roundtrip.mjs"
   },
   "dependencies": {
     "esbuild": "^0.28.1"

package/skills/monty-operate/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: monty-operate
+description: Operate a team's Monty workspace apps from the terminal — read and write a Live app's records with `monty data`. Use whenever the task is to put data INTO an existing Monty app or read data from one: add leads to a CRM, import scraped or external data, update or clean up records, check what an app currently stores, or automate recurring work against apps on usemonty.dev. Building or changing an app itself is monty-build, not this.
+---
+
+# Operating Monty apps
+
+A Monty workspace runs internal apps (CRMs, trackers, dashboards) whose data
+lives on the platform. `monty data` is how you — the operating agent — read
+and write that data directly from the terminal: no browser session, no dev
+server. You do the work (browse, scrape, decide, transform); the app is
+where the results land, and open app tabs update live as you write.
+
+Two data channels per app: **Live** (the team's real records — the default
+target) and the **Studio sandbox** (`--studio` — development data, never
+seen by the team). Writing to Live is normal operating work; that is what
+this command is for.
+
+## The loop
+
+1. **Find the app.** `monty apps` lists local apps; run inside the app
+   folder (`cd "$(monty select <slug>)"`) or pass `--app <slug>` to every
+   command.
+2. **Learn the shape — never guess.** `monty data schema` prints every
+   table; `monty data schema <table>` one table. (Schema compiles from the
+   local source — if the app isn't on this machine, `monty pull <slug>`
+   first.)
+3. **See what's there.** `monty data list <table> --limit 20` before
+   writing: learn the field conventions from real rows and avoid duplicating
+   what exists.
+4. **Write.** Prefer `upsert` with a `--key` for anything imported or
+   scraped; `insert` only for rows that are genuinely new by construction.
+5. **Verify.** `list`/`get` the rows you touched; report counts (added,
+   updated, skipped) with specifics.
+
+## Rules
+
+1. **Imports are idempotent.** Any repeatable job (scraping, syncing,
+   importing) writes with
+   `monty data upsert <table> --key <identityField> --data '[…]'` — the key
+   names the field(s) that identify a row (a URL, an email, an external id),
+   values come from each row, and re-running never duplicates.
+2. **Schema first, rows second.** Field names come from
+   `monty data schema`, exact spelling. The server stores what you send —
+   a misspelled field is silently a new field, not an error.
+3. **Live is the default and that's correct** — operating work targets the
+   team's real data. Use `--studio` only when explicitly rehearsing.
+   Destructive verbs (`remove`, bulk `update`) on Live deserve a
+   confirmation with the user unless they clearly asked for the cleanup.
+4. **Batch with arrays.** `--data` accepts a single object or an array;
+   arrays write row by row and return all ids in order.
+5. **Paginate honestly.** `list` returns `"cursor": null` when complete; a
+   non-null cursor means more rows exist — repeat with `--cursor <c>`
+   before claiming totals.
+6. **Errors are instructions.** Every failure prints
+   `[MontyError CODE] Fix: …` — do what the Fix says. `NOT_LOGGED_IN` means
+   run `monty login` (once per machine); `NOT_FOUND` on an id means it came
+   from the wrong table or a stale listing — re-`list`, never retry blind.
+7. **Rows come back flattened**: your fields at the top level plus system
+   fields `_id`, `_creationTime`, `updatedAt`, `createdBy`. System fields
+   are read-only — never send them in `--data`.
+
+## Command reference
+
+| command | purpose |
+|---|---|
+| `monty data schema [table]` | table shapes from the app's config — read this before any write |
+| `monty data list <table> [--filter '{"k":"v"}'] [--order asc\|desc] [--limit N] [--cursor C]` | newest-first rows; filter is exact-match on fields |
+| `monty data get <table> <id>` | one row (null if the id isn't in this table) |
+| `monty data insert <table> --data '<json\|[json,…]>'` | create rows |
+| `monty data upsert <table> --key <field[,field]> --data '<json\|[json,…]>'` | find-or-create matched on the key fields — the idempotent write |
+| `monty data update <table> <id> --data '<json>' [--unset a,b]` | shallow-merge onto one row; `--unset` deletes fields |
+| `monty data remove <table> <id>` | delete one row |
+
+All verbs take `--app <slug>` and `--studio`. Output is one JSON document on
+stdout.
+
+## Example: import scraped leads into a CRM app
+
+```sh
+monty data schema leads --app crm                # shape: name, company, title, linkedinUrl, status…
+monty data list leads --app crm --limit 50       # what's already in the pipeline
+# …browse/scrape/decide, then land the batch idempotently:
+monty data upsert leads --app crm --key linkedinUrl --data '[
+  {"name":"Dana Reeve","company":"Acme","title":"VP Ops","linkedinUrl":"https://linkedin.com/in/dana-r","status":"new"},
+  {"name":"Sam Ortiz","company":"Initech","title":"Head of RevOps","linkedinUrl":"https://linkedin.com/in/sam-o","status":"new"}
+]'
+monty data list leads --app crm --filter '{"status":"new"}'   # verify, then report counts
+```

package/template/AGENTS.md

@@ -92,6 +92,73 @@ await update(row._id, { receipt });                     // store descriptor, not
 const { url } = useFileUrl(app, row.receipt);            // authenticated blob: URL for previews/downloads
 ```
 
+## Derived fields, metrics, pages (V2 — the platform renders these)
+
+Your config can carry a whole database app the platform shell renders for
+you — system table views, record drawers, dashboards — no React needed.
+This SPA scaffold exists for the pages that ARE bespoke (`pages` entries
+with `kind: "custom"` mount your routes inside that shell).
+
+```ts
+import { defineApp, formula, lookup, montyDate, montyMoney, montyRef, rollup, self } from "@montytools/sdk";
+import { z } from "zod";
+
+export const app = defineApp({
+  slug: "pipeline",
+  tables: {
+    people: z.object({
+      name: z.string().min(1),
+      companyId: montyRef("companies"),          // typed relation
+      commissionRate: z.number().default(0.1),
+      // Derived fields live IN the table, like spreadsheet columns:
+      companyName: lookup(z.string(), { ref: "companyId", field: "name" }),
+      monthlySales: rollup(montyMoney(), {       // live aggregate (SUMIFS)
+        from: "sales",
+        where: { status: "won", salespersonId: self("_id") },
+        sum: "amount", over: "closedAt", range: "currentMonth",
+      }),
+      commission: formula(montyMoney(), "monthlySales * commissionRate"),
+    }),
+    companies: z.object({ name: z.string().min(1) }),
+    sales: z.object({
+      amount: montyMoney(),
+      status: z.enum(["open", "won", "lost"]).default("open"),
+      salespersonId: montyRef("people"),
+      closedAt: montyDate().optional(),
+    }),
+  },
+  metrics: {  // app-level named numbers for dashboards + formulas (`metrics.wonThisMonth`)
+    wonThisMonth: rollup(montyMoney(), { from: "sales", where: { status: "won" }, sum: "amount", over: "closedAt", range: "currentMonth" }),
+  },
+  pages: {
+    people: { kind: "view", table: "people", summaries: { monthlySales: "sum" } },
+    overview: { kind: "dashboard", metrics: ["wonThisMonth"] },
+    reports: { kind: "custom", path: "/reports" },   // ← your src/routes/reports.tsx
+  },
+});
+```
+
+Rules that matter:
+
+- **Formulas are strings**, not functions — the Monty expression grammar
+  (`+ - * / %`, comparisons, `&& || !`, `IF/ROUND/ABS/MIN/MAX`,
+  `metrics.<name>`). A formula sees only fields declared ABOVE it. Type
+  errors and unknown identifiers fail the compile with the fix inline.
+- **Derived fields are read-only** — writing one through `useInsert`/
+  `useUpdate` is a `VALIDATION` error naming the field and its kind.
+- Rollup `where` values are equality literals or `self("ownField")` ("this
+  row's value"). `sum:` names a numeric field; `count: true` counts.
+- In custom pages, read metrics/rollups with `useMetric(app, "wonThisMonth")`
+  and `useAggregate(app, "people", "monthlySales", rowIds)`.
+- **Datasets** (computed row sets — hidden data, joins): declare the row
+  shape in `datasets: { leaderboard: z.object({...}) }`, implement it as a
+  `defineDataset` export in `server/index.ts` (≤1,000 rows — aggregate or
+  filter server-side), consume with `useDataset(app, "leaderboard")` —
+  polled (focus + optional interval + your own writes), NOT live.
+- `monty schema pull` regenerates this file from the platform if another
+  agent edited the schema remotely (the terminal will tell you when —
+  `MANIFEST_DRIFT`).
+
 ## Errors are instructions
 
 Every platform error is one line shaped like:

package/template/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@fontsource-variable/roboto": "^5.2.10",
-    "@montytools/sdk": "^0.1.5",
+    "@montytools/sdk": "^0.2.0",
     "@tanstack/react-router": "1.170.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",