@montytools/cli 0.1.0

package/bin/catalog.mjs

@@ -0,0 +1,75 @@
+// The curated component catalog: one blessed, pre-vetted implementation per
+// capability. Every entry is MIT-licensed, Radix-based, and styles itself
+// through the app's semantic tokens — so it comes out in the Monty theme
+// with no extra work. Bare names not listed here fall through to the core
+// shadcn registry (dialog, tabs, popover, ...).
+
+export const REGISTRIES = {
+  "@kibo-ui": "https://www.kibo-ui.com/r/{name}.json",
+  "@diceui": "https://diceui.com/r/{name}.json",
+};
+
+export const CATALOG = {
+  "data-table": {
+    item: "@diceui/data-table",
+    // upstream registryDependencies omit skeleton (data-table-skeleton.tsx needs it)
+    also: ["skeleton"],
+    use: "sortable/filterable/paginated table — default for any list of records",
+  },
+  kanban: {
+    item: "@kibo-ui/kanban",
+    use: "drag-and-drop board grouped by a status/enum field",
+  },
+  calendar: {
+    item: "@kibo-ui/calendar",
+    use: "month grid showing records that have a date field",
+  },
+  gantt: {
+    item: "@kibo-ui/gantt",
+    use: "timeline view for records with start and end dates",
+  },
+  combobox: {
+    item: "@kibo-ui/combobox",
+    use: "searchable select — use instead of <Select> when options exceed ~10",
+  },
+  "file-upload": {
+    item: "@kibo-ui/dropzone",
+    use: "drag-and-drop file upload area",
+  },
+  editor: {
+    item: "@kibo-ui/editor",
+    use: "rich text editor (notes, descriptions, long-form fields)",
+  },
+  tags: {
+    item: "@kibo-ui/tags",
+    use: "multi-value tag input (labels, categories)",
+  },
+  status: {
+    item: "@kibo-ui/status",
+    use: "colored status dot + label for enum states",
+  },
+  "avatar-stack": {
+    item: "@kibo-ui/avatar-stack",
+    use: "overlapping member avatars (pairs with useMembers)",
+  },
+  rating: {
+    item: "@kibo-ui/rating",
+    use: "star rating input/display",
+  },
+  chart: {
+    item: "chart",
+    use: "themed charts (bar/line/area/pie) for dashboards and KPIs",
+  },
+  sidebar: {
+    item: "sidebar",
+    use: "collapsible app sidebar — use when the app grows past one page",
+  },
+  command: {
+    item: "command",
+    use: "command palette / cmd-K search",
+  },
+  sonner: {
+    item: "sonner",
+    use: "toast notifications for action feedback",
+  },
+};

package/bin/monty.mjs

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+// monty — the Monty platform CLI. Output is agent-shaped: structured
+// single-line events, no spinners, instruction-shaped errors, and a
+// deterministic final line (`deployed: …` / `error: …`).
+
+import { spawn, spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { CATALOG, REGISTRIES } from "./catalog.mjs";
+
+const CONFIG_DIR = join(homedir(), ".monty");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const DEFAULT_HOST = "https://usemonty.dev";
+
+const [, , command, ...rest] = process.argv;
+
+function flag(name) {
+  const i = rest.indexOf(`--${name}`);
+  return i >= 0 ? rest[i + 1] : undefined;
+}
+
+function fail(code, fix) {
+  console.error(`error: [MontyError ${code}] Fix: ${fix}`);
+  process.exit(1);
+}
+
+function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// ── monty login ────────────────────────────────────────────────────────────
+async function login() {
+  const host = flag("host") ?? DEFAULT_HOST;
+  let key = flag("key");
+  if (!key) {
+    console.log(`open: ${host}/cli-auth (sign in, create a CLI key)`);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    key = (await rl.question("paste key: ")).trim();
+    rl.close();
+  }
+  if (!/^mk_[0-9a-f]{48}$/.test(key)) {
+    fail("INVALID_CLI_KEY", `That does not look like a Monty CLI key (mk_ + 48 hex chars). Create one at ${host}/cli-auth.`);
+  }
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify({ host, key }, null, 2) + "\n");
+  console.log(`logged-in: ${host} (key saved to ~/.monty/config.json)`);
+}
+
+// ── monty create ───────────────────────────────────────────────────────────
+async function create() {
+  const slug = rest.find((a) => !a.startsWith("--"));
+  if (!slug || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
+    fail("INVALID_SLUG", 'Usage: monty create <slug> — lowercase letters/digits with single hyphens (e.g. "standup-notes").');
+  }
+  const name =
+    flag("name") ??
+    slug.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+  const icon = flag("icon") ?? "layout-grid";
+  const target = join(process.cwd(), flag("dir") ?? slug);
+  if (existsSync(target)) {
+    fail("DIR_EXISTS", `${target} already exists. Pick another slug or remove the directory.`);
+  }
+
+  // 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)), "..");
+  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(`create: ${slug} -> ${target}`);
+  cpSync(templateDir, target, {
+    recursive: true,
+    filter: (src) => {
+      const base = basename(src);
+      return !["node_modules", "dist", ".monty", ".env.local", "routeTree.gen.ts"].includes(base);
+    },
+  });
+
+  // Stamp identity into the copied files.
+  const configPath = join(target, "monty.config.ts");
+  writeFileSync(
+    configPath,
+    readFileSync(configPath, "utf8")
+      .replace(/slug: "[^"]*"/, `slug: "${slug}"`)
+      .replace(/name: "[^"]*"/, `name: "${name}"`)
+      .replace(/icon: "[^"]*"/, `icon: "${icon}"`),
+  );
+  const pkgPath = join(target, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  pkg.name = slug;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  const htmlPath = join(target, "index.html");
+  writeFileSync(
+    htmlPath,
+    readFileSync(htmlPath, "utf8").replace(/<title>[^<]*<\/title>/, `<title>${name}</title>`),
+  );
+
+  // Client config comes from the platform — public values, no dashboard trip.
+  const host = loadConfig()?.host ?? DEFAULT_HOST;
+  try {
+    const cfg = await fetch(`${host}/api/config`).then((r) => r.json());
+    writeFileSync(
+      join(target, ".env.local"),
+      `VITE_CONVEX_URL=${cfg.convexUrl}\nVITE_CLERK_PUBLISHABLE_KEY=${cfg.clerkPublishableKey}\n`,
+    );
+    console.log(`config: .env.local written from ${host}/api/config`);
+  } catch {
+    console.log(`config: WARNING — could not reach ${host}/api/config; copy .env.example to .env.local manually`);
+  }
+
+  console.log(`created: ${target}`);
+  console.log(`next: cd ${relative(process.cwd(), target)} && pnpm install && monty dev`);
+}
+
+// ── monty dev ──────────────────────────────────────────────────────────────
+async function dev() {
+  const appDir = process.cwd();
+  if (!existsSync(join(appDir, "monty.config.ts"))) {
+    fail("NOT_A_MONTY_APP", "No monty.config.ts here. Run `monty dev` from your app's root directory.");
+  }
+  const meta = await compileConfig(appDir);
+  const host = loadConfig()?.host ?? DEFAULT_HOST;
+  const port = Number(flag("port") ?? 5173);
+
+  console.log(`dev: starting vite on :${port} (app "${meta.slug}")`);
+  const child = spawn("npx", ["vite", "dev", "--port", String(port), "--strictPort"], {
+    cwd: appDir,
+    stdio: ["ignore", "pipe", "inherit"],
+  });
+  let announced = false;
+  child.stdout.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stdout.write(text);
+    if (!announced && /localhost:\d+/.test(text)) {
+      announced = true;
+      console.log(`open: ${host}/apps/${meta.slug}?dev=http://localhost:${port}`);
+      console.log(`data: sandboxed to "${meta.slug}#dev" (live records untouched)`);
+      console.log(`ready: http://localhost:${port}`);
+    }
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+// ── monty add / components / docs ──────────────────────────────────────────
+// Wraps the shadcn CLI behind the curated catalog: agents ask for a
+// capability by plain name ("kanban") and get the blessed, theme-compatible
+// implementation. Only catalog registries and core shadcn resolve.
+
+function requireAppDir(cmd) {
+  const appDir = process.cwd();
+  if (!existsSync(join(appDir, "monty.config.ts"))) {
+    fail("NOT_A_MONTY_APP", `No monty.config.ts here. Run \`monty ${cmd}\` from your app's root directory.`);
+  }
+  return appDir;
+}
+
+// "kanban" -> "@kibo-ui/kanban"; bare unlisted names pass through to core
+// shadcn; explicit @namespace items must belong to a supported registry.
+function resolveComponent(name) {
+  if (CATALOG[name]) return CATALOG[name].item;
+  if (name.startsWith("@")) {
+    const ns = name.split("/")[0];
+    if (ns !== "@shadcn" && !REGISTRIES[ns]) {
+      fail("UNSUPPORTED_REGISTRY", `${ns} is not a supported registry. Run \`monty components\` for the curated catalog; core shadcn components install by bare name.`);
+    }
+  }
+  return name;
+}
+
+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.");
+  }
+  const items = names.flatMap((n) => [resolveComponent(n), ...(CATALOG[n]?.also ?? [])]);
+
+  // --overwrite so shadcn never halts on a per-file prompt (an aborted prompt
+  // cancels ALL remaining writes). Existing files win instead: snapshot them
+  // and restore any the install replaced — the app's themed primitives stay,
+  // new files land alongside.
+  const snapshot = new Map();
+  for (const dir of ["src/components", "src/hooks", "src/lib"]) {
+    const abs = join(appDir, dir);
+    if (existsSync(abs)) for (const f of walk(abs)) snapshot.set(f, readFileSync(f));
+  }
+  run(appDir, "add", ["pnpm", "dlx", "shadcn@latest", "add", "--yes", "--overwrite", ...items],
+    `Could not add ${items.join(", ")}. If the name was a guess, run \`monty components\` for the curated catalog — core shadcn components (dialog, tabs, dropdown-menu, ...) install by bare name.`);
+
+  // The shadcn CLI rewrites imports and mangles paths outside its known
+  // aliases (e.g. @/config/*, @/types/*). The template's layout matches
+  // registry sources exactly, so for third-party items restore each newly
+  // created file verbatim from the registry JSON.
+  for (const item of items) {
+    const [ns, name] = item.split("/");
+    const urlTemplate = REGISTRIES[ns];
+    if (!urlTemplate) continue;
+    const spec = await fetch(urlTemplate.replace("{name}", name)).then((r) => r.json()).catch(() => null);
+    for (const file of spec?.files ?? []) {
+      if (typeof file.content !== "string") continue;
+      const dest = join(appDir, (file.target || file.path).replace(/^~\//, ""));
+      if (existsSync(dest) && !snapshot.has(dest)) writeFileSync(dest, file.content);
+    }
+  }
+
+  let kept = 0;
+  for (const [file, buf] of snapshot) {
+    if (existsSync(file) && !readFileSync(file).equals(buf)) {
+      writeFileSync(file, buf);
+      kept++;
+    }
+  }
+  if (kept > 0) console.log(`kept: ${kept} existing file(s) unchanged (your themed versions win)`);
+  console.log(`added: ${items.join(", ")} -> src/components (already themed; import and compose)`);
+}
+
+function components() {
+  const query = rest.filter((a) => !a.startsWith("--")).join(" ").toLowerCase();
+  const entries = Object.entries(CATALOG).filter(
+    ([name, { item, use }]) => !query || `${name} ${item} ${use}`.toLowerCase().includes(query),
+  );
+  const width = Math.max(...Object.keys(CATALOG).map((n) => n.length));
+  const itemWidth = Math.max(...Object.values(CATALOG).map((c) => c.item.length));
+  console.log(`components: ${entries.length} curated (install with \`monty add <name>\`)`);
+  for (const [name, { item, use }] of entries) {
+    console.log(`  ${name.padEnd(width)}  ${item.padEnd(itemWidth)}  ${use}`);
+  }
+  console.log("core: any shadcn component installs by bare name (dialog, tabs, dropdown-menu, popover, tooltip, sheet, checkbox, textarea, ...)");
+  console.log("docs: `monty docs <name>` shows a component's source before installing");
+}
+
+async function docs() {
+  const appDir = requireAppDir("docs");
+  const name = rest.find((a) => !a.startsWith("--"));
+  if (!name) {
+    fail("NO_COMPONENT", "Usage: monty docs <name> — run `monty components` to see what's available.");
+  }
+  run(appDir, "docs", ["pnpm", "dlx", "shadcn@latest", "view", resolveComponent(name)],
+    `Could not view ${name}. Run \`monty components\` to see the curated catalog.`);
+}
+
+// ── monty deploy ───────────────────────────────────────────────────────────
+async function deploy() {
+  const appDir = process.cwd();
+  if (!existsSync(join(appDir, "monty.config.ts"))) {
+    fail("NOT_A_MONTY_APP", "No monty.config.ts here. Run `monty deploy` from your app's root directory.");
+  }
+  const config = loadConfig();
+  if (!config?.key) {
+    fail("NOT_LOGGED_IN", "Run `monty login` first (create a key at /cli-auth in the Monty host).");
+  }
+
+  // 1) Compile monty.config.ts → { slug, name, icon, schemaJson } using the
+  //    app's OWN zod/sdk instances (esbuild-bundled, run in a subprocess).
+  console.log("compile: monty.config.ts");
+  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.");
+
+  // 3) Multipart POST to the host.
+  const dist = join(appDir, "dist");
+  const files = walk(dist);
+  const form = new FormData();
+  form.set("monty", JSON.stringify(meta));
+  let total = 0;
+  for (const file of files) {
+    const rel = relative(dist, file).split("\\").join("/");
+    const buf = readFileSync(file);
+    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`);
+  const res = await fetch(`${config.host}/api/deploy`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${config.key}` },
+    body: form,
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !body?.ok) {
+    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})`);
+}
+
+async function compileConfig(appDir) {
+  const { build } = await import("esbuild");
+  const tmpDir = join(appDir, ".monty");
+  mkdirSync(tmpDir, { recursive: true });
+  const entry = join(tmpDir, "compile-entry.mjs");
+  const out = join(tmpDir, "compile-out.mjs");
+  writeFileSync(entry, [
+    `import { app } from "../monty.config";`,
+    `import { compileApp } from "@montytools/sdk/compile";`,
+    `process.stdout.write(JSON.stringify(compileApp(app)));`,
+  ].join("\n"));
+  try {
+    await build({
+      entryPoints: [entry],
+      outfile: out,
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      target: "node22",
+      absWorkingDir: appDir,
+      logLevel: "silent",
+    });
+    const result = spawnSync(process.execPath, [out], { encoding: "utf8" });
+    if (result.status !== 0) {
+      fail("CONFIG_COMPILE_FAILED", `monty.config.ts threw while loading:\n${result.stderr}\nFix the config (it must only call defineApp with zod tables).`);
+    }
+    return JSON.parse(result.stdout);
+  } catch (e) {
+    if (e?.errors) {
+      fail("CONFIG_COMPILE_FAILED", `esbuild could not bundle monty.config.ts: ${e.errors[0]?.text ?? e.message}`);
+    }
+    throw e;
+  } finally {
+    rmSync(entry, { force: true });
+    rmSync(out, { force: true });
+  }
+}
+
+function run(cwd, label, argv, fixOnFail) {
+  console.log(`${label}: ${argv.join(" ")}`);
+  // stdin ignored: interactive prompts (e.g. shadcn's per-file overwrite
+  // confirmation) take their safe default instead of blocking an agent.
+  const result = spawnSync(argv[0], argv.slice(1), { cwd, stdio: ["ignore", "inherit", "inherit"] });
+  if (result.status !== 0) {
+    fail(label.toUpperCase() + "_FAILED", fixOnFail);
+  }
+  console.log(`${label}: ok`);
+}
+
+function walk(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+// ── dispatch ───────────────────────────────────────────────────────────────
+switch (command) {
+  case "login":
+    await login();
+    break;
+  case "create":
+    await create();
+    break;
+  case "dev":
+    await dev();
+    break;
+  case "add":
+    await add();
+    break;
+  case "components":
+  case "search":
+    components();
+    break;
+  case "docs":
+    await docs();
+    break;
+  case "deploy":
+    await deploy();
+    break;
+  default:
+    console.log("usage: monty <login|create|dev|add|components|docs|deploy>");
+    console.log("  login       --host <url> --key <mk_...>    save CLI credentials");
+    console.log("  create      <slug> [--name N] [--icon I]   stamp a new app from the template");
+    console.log("  dev         [--port 5173]                  run the app locally (sandboxed data)");
+    console.log("  add         <name...>                      install curated UI components (see `monty components`)");
+    console.log("  components  [query]                        list the curated component catalog");
+    console.log("  docs        <name>                         view a component's source before installing");
+    console.log("  deploy                                      build + upload this app");
+    process.exit(command ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@montytools/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "monty": "./bin/monty.mjs"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "prepack": "node scripts/bundle-template.mjs",
+    "typecheck": "node --check bin/monty.mjs"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/.env.example

@@ -0,0 +1,3 @@
+# Copy to .env.local (gitignored). `monty dev` will manage this for you later.
+VITE_CONVEX_URL=https://YOUR-DEPLOYMENT.convex.cloud
+VITE_CLERK_PUBLISHABLE_KEY=pk_test_REPLACE_ME

package/template/AGENTS.md

@@ -0,0 +1,133 @@
+# You are building a Monty app
+
+Monty is a work OS: your app runs inside a team's workspace, on shared reactive
+data, with auth and deployment handled by the platform. **You only write product
+logic.** Everything below is the complete contract.
+
+## The three files that matter
+
+| File | What it is |
+|---|---|
+| `monty.config.ts` | Your data schema — plain zod. The ONLY place data shapes are defined. Also `name` + `icon` (any [lucide](https://lucide.dev/icons) icon name, e.g. `"receipt"`, `"users"`) — Monty renders your app's logo tile from it. |
+| `src/routes/` | Your UI — TanStack Router file routes (`index.tsx` = `/`). |
+| `src/main.tsx` | Wiring. Do not edit. |
+
+## Rules (violations break the app)
+
+1. **Never import `convex`, `@clerk/*`, or talk to a database or API directly.**
+   All data goes through `@montytools/sdk/react` hooks. Auth, tenancy, and realtime
+   are handled below you — never write them.
+2. **Never ask for or pass a workspace/tenant id.** The platform injects it
+   from the verified session; it is not part of any API you can see.
+3. **UI is shadcn/ui, preconfigured — never build components from scratch.**
+   Before building any UI piece, run `monty components`. If the capability is
+   listed (data tables, kanban, calendar, combobox, file upload, rich text,
+   charts, …) install the curated implementation with `monty add <name>`;
+   core shadcn components install by bare name (`monty add dialog tabs`).
+   Everything lands in `src/components/ui/*` already carrying the Monty
+   theme. `monty docs <name>` shows a component's source before installing.
+   Icons from `lucide-react`. Don't install other component libraries or
+   write raw-color CSS — use semantic tokens (`bg-background`,
+   `text-muted-foreground`, …). Don't edit `src/index.css` theme tokens.
+4. **Schema changes = edit `monty.config.ts` and save.** Types update
+   immediately. Prefer additive changes; give new fields `.optional()` or
+   `.default(...)` so existing records stay readable.
+
+## Data: define, then use
+
+```ts
+// monty.config.ts
+export const app = defineApp({
+  slug: "expenses",
+  tables: {
+    expenses: z.object({
+      title: z.string().min(1),
+      amount: z.number().positive(),
+      status: z.enum(["draft", "submitted", "approved"]).default("draft"),
+      assigneeId: z.string().optional(), // userId from useMembers()
+    }),
+  },
+});
+```
+
+```tsx
+import { useList, useRecord, useInsert, useUpdate, useRemove, useMembers } from "@montytools/sdk/react";
+import { app } from "../../monty.config";
+
+const { data, status, loadMore } = useList(app, "expenses", {
+  filter: { status: "submitted" },   // equality on schema fields only
+  order: "desc",                     // by creation time
+  limit: 50,
+});
+// data: rows typed from your zod schema + { _id, _creationTime, updatedAt, createdBy }
+// status: "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted"
+// LIVE: any teammate's write re-renders this. Never poll, refetch, or cache.
+
+const insert = useInsert(app, "expenses");
+await insert({ title: "Lunch", amount: 12 });          // defaults applied, validated
+
+const update = useUpdate(app, "expenses");
+await update(row._id, { status: "approved" });          // shallow-merge patch
+await update(row._id, { assigneeId: null });            // null CLEARS an .optional() field
+// Counters: read-modify-write (`update(id, { votes: row.votes + 1 })`) is the
+// blessed pattern. It is last-write-wins — two simultaneous clicks can lose
+// one. Fine for votes/likes; if exact counts matter, model events as ROWS in
+// their own table and count client-side.
+
+const remove = useRemove(app, "expenses");
+await remove(row._id);
+
+const one = useRecord(app, "expenses", idOrNull);       // row | null(missing or no selection) | undefined(loading)
+const members = useMembers();                           // [{ userId, name, email, imageUrl, role }]
+```
+
+## Errors are instructions
+
+Every platform error is one line shaped like:
+`[MontyError VALIDATION] at expenses.status: expected "draft"|"submitted"|"approved", got "done". Fix: ...`
+
+**Do exactly what the `Fix:` says.** Codes you may see:
+
+| Code | Meaning |
+|---|---|
+| `VALIDATION` | Payload doesn't match your zod schema (unknown fields are also an error) — fix the payload or the schema. |
+| `UNKNOWN_TABLE` | Table name not in `monty.config.ts` `tables`. |
+| `NOT_FOUND` | Stale, foreign, or WRONG-TABLE record id — ids come from `useList`/`useRecord` on the same table; never hard-code or mix them. |
+| `INVALID_SCHEMA` | A table field uses a reserved name (`_*`, `updatedAt`, `createdBy`) — rename it. |
+| `SCHEMA_DRIFT` (warning) | Stored rows predate your latest schema change; nothing crashes, but make changed fields `.optional()`/`.default(...)`. |
+| `UNAUTHENTICATED` / `NO_ACTIVE_WORKSPACE` | App isn't running through the Monty host/dev shell. |
+| `MISSING_ENV` / `NO_PROVIDER` | `.env.local` or the `<MontyProvider>` in `main.tsx` was removed. |
+
+## Dev loop
+
+```
+pnpm dev          # Vite + HMR on :5173; sign in with your workspace account
+```
+
+Headless? Verify with `pnpm exec vite build` then `pnpm exec tsc --noEmit` — in
+that order: the first build generates `src/routeTree.gen.ts`, without which
+typecheck fails on a fresh app. `monty deploy` runs both itself (it never
+uploads code that doesn't compile), so deploy is self-verifying.
+
+**Driving your app in a browser (agents):** while `monty dev` runs, opening
+`http://localhost:5173` is ALREADY AUTHENTICATED — no sign-in screen (the dev
+server mints short-lived workspace tokens from the CLI login). Point
+Playwright or any browser automation at it, click through your app against
+live sandboxed data, and read your errors in the `monty dev` terminal
+(`[browser:error] …` lines). Edit → HMR → look → fix: verify your own work.
+
+Dev writes go to a sandboxed `#dev` namespace inside your real workspace —
+iterate freely, live app data is untouched. The "DEV · … · sandbox data" badge
+confirms it.
+
+## Modeling tips
+
+- Rows, not embedded arrays: a comments thread is a `comments` table with a
+  `parentId` field, not an array inside a record (records cap at 1 MiB).
+- People are `z.string()` userIds from `useMembers()`; render names/avatars
+  from the member list.
+- Timestamps are `z.number()` epochs or `z.iso.datetime()` strings — never
+  `z.date()`.
+- Field names `_*`, `updatedAt`, `createdBy` are reserved for system fields.
+- Cross-field `.refine()` rules run on **insert only** — updates validate
+  field-by-field. Keep invariants per-field where possible.

package/template/components.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-lyra",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "olive",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {
+    "@kibo-ui": "https://www.kibo-ui.com/r/{name}.json",
+    "@diceui": "https://diceui.com/r/{name}.json"
+  }
+}

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Expenses</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>