@montytools/cli 0.4.2 → 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.2",
+  "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/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",