@montytools/cli 0.4.2 → 0.5.1

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,222 @@
+// 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;
+    case "multiSelect":
+      src = `z.array(z.enum(${JSON.stringify(spec.values)}))`;
+      break;
+    case "email":
+      src = "z.email()";
+      break;
+    case "url":
+      src = "z.url()";
+      break;
+    case "phone":
+      used.add("montyPhone");
+      src = "montyPhone()";
+      break;
+    case "rating":
+      used.add("montyRating");
+      src = "montyRating()";
+      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) {
+    // Emit in declared nav order — the config's declaration order becomes
+    // pagesOrder on the next compile, so emission order must match it.
+    const orderedPages = {};
+    for (const name of manifest.pagesOrder ?? Object.keys(manifest.pages)) {
+      if (name in manifest.pages) orderedPages[name] = manifest.pages[name];
+    }
+    for (const [name, page] of Object.entries(manifest.pages)) {
+      if (!(name in orderedPages)) orderedPages[name] = page;
+    }
+    out.push(`  pages: ${JSON.stringify(orderedPages, 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.1",
   "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-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: monty-build
-description: Build, run, and deploy Monty workspace apps. Use whenever the task involves a Monty app, monty.config.ts, the monty CLI (create/dev/logs/deploy/add), the @montytools/sdk, or a prompt mentioning usemonty.dev. Covers folder discipline, the build loop, data/auth rules, and error handling.
+description: Build, run, and save Monty workspace apps. Use whenever the task involves a Monty app, monty.config.ts, the monty CLI (create/dev/logs/save/add), the @montytools/sdk, or a prompt mentioning usemonty.dev. Covers folder discipline, the build loop, data/auth rules, and error handling.
 ---
 
 # Building Monty apps
@@ -11,10 +11,11 @@ platform's job. The complete contract lives in the app's own `AGENTS.md`
 (nearest-file-wins — read it before writing code). This skill is the map, not
 the territory.
 
-Every app has two states: **Live** (published — what members and visitors
-see) and **Studio** (development — a running dev shell on `#dev`-sandboxed
-data, often already started for you by the Monty desktop). Those are the only
-names for them; "dev"/"prod" mean something else on this platform.
+There is ONE copy of every app: **Live**, the cloud copy the team uses
+(`monty save` updates it). While a dev **session** runs (a dev shell on
+the app's LIVE records, often already started for you by the Monty desktop),
+workspace admins see the session's version automatically — no publish, no
+channel switch. "dev"/"prod" mean platform environments, never app states.
 
 ## Rules
 
@@ -23,45 +24,61 @@ names for them; "dev"/"prod" mean something else on this platform.
    `monty login` first). `monty current` tells you where you are;
    `cd "$(monty select <slug>)"` jumps to an app; `monty apps` lists local
    ones. Never mkdir app folders by hand, and never edit the `id:` line in
-   `monty.config.ts`.
+   `monty.config.ts`. The folder IS the app's source: every file in it
+   rides the source snapshot on `monty save`, so never leave scratch files
+   here (manifest edits, notes, one-off scripts). Work in the OS temp dir
+   instead, or pipe — `monty schema | <edit> | monty schema set -` needs
+   no file at all — and delete anything temporary before saving.
 2. **The loop:** `monty create <slug> --name "Name" --icon <tabler-icon>` →
    (if the prompt includes a `build id`, pass it: `--build <id>` — the
    workspace's New app screen tracks your progress live) →
-   `monty install` → edit `monty.config.ts` (zod tables) + `src/routes/` →
-   verify in Studio: run `monty dev` once — if the dev shell is already
+   `monty install` → shape the schema through `monty schema` /
+   `monty schema set` (a brand-new app's very first session lands its
+   monty.config.ts once; after that the workspace owns the schema) + edit
+   `src/routes/` →
+   verify in the session: run `monty dev` once — if the dev shell is already
    running (the Monty desktop usually runs it for you) it prints the status,
-   Studio URL, and recent log lines, then **exits immediately**; if nothing
+   app URL, and recent log lines, then **exits immediately**; if nothing
    is running it starts the shell (start it in the background and move on).
    Then iterate: edit code → vite hot-reloads → `monty logs -n 50` shows
-   whether it compiled and any browser errors. **You are done when
-   `monty dev` reports `state: online` (or prints the Studio URL on a fresh
-   start) and the app works.** Re-running `monty dev` is always safe — it
-   attaches, prints status, and exits. Never try to run a second dev
-   *server* for the same app (attach handles this for you) and never kill a
-   dev shell you didn't start; `monty dev --takeover` is the only sanctioned
-   restart when a session is wedged. Taking the app Live is the OWNER'S
-   click (Publish in the workspace menu bar); **never run `monty deploy`
-   yourself** unless the user explicitly asks for a direct Live deploy.
+   whether it compiled and any browser errors. Re-running `monty dev` is
+   always safe — it attaches, prints status, and exits. Never try to run a
+   second dev *server* for the same app (attach handles this for you) and
+   never kill a dev shell you didn't start; `monty dev --takeover` is the
+   only sanctioned restart when a session is wedged. **You are not done
+   until you've saved: once the work is verified in the session, run
+   `monty save "<what changed>"`** — it builds, typechecks, and pushes the
+   working copy to the cloud copy, like `git push main`. Save after every
+   meaningful change, not just at the end; unsaved work exists only on this
+   machine.
 3. **Everything through the CLI.** `monty install`, `monty build`,
-   `monty typecheck`, `monty dev`, `monty deploy` — never run vite, tsc,
+   `monty typecheck`, `monty dev`, `monty save` — never run vite, tsc,
    pnpm, or npm scripts directly. `monty dev` auto-picks a free port and
    prints it; `monty typecheck` builds first when needed. `monty logs`
    (add `-f` to follow) is how you read the dev shell's output — vite build
-   errors, browser errors, and publish results all land there.
+   errors, browser errors, and save results all land there.
 4. **One import surface:** `@montytools/sdk` (`defineApp`, zod) and
    `@montytools/sdk/react` (hooks: `useList`, `useInsert`, …). Never import
    Clerk or Convex directly; never fetch external APIs from app code — the
    platform CSP blocks them.
-5. **Schema is zod in `monty.config.ts`.** Field names `_*`, `updatedAt`,
-   `createdBy` are reserved. Push happens automatically on dev/deploy.
+5. **The data schema lives in the WORKSPACE, not in code.** Read it with
+   `monty schema` (JSON on stdout); change it by editing that JSON and
+   running `monty schema set <file>` — validated server-side, additive by
+   default. On workspace-owned apps, `monty.config.ts` edits do NOT change
+   the schema. Declare a page in the manifest BEFORE shipping its route —
+   a save with an undeclared route refuses with the fix. Field names `_*`,
+   `updatedAt`, `createdBy` are reserved.
 6. **UI is stock shadcn** (preset already wired). Add curated components with
    `monty add <name>`; browse with `monty components` / `monty docs <name>`.
+   How pages should LOOK — Lyra surfaces, dark-only, the chart language — is
+   the `monty-design` skill; read it before styling any page.
 7. **Errors are instructions.** Every failure prints
    `[MontyError CODE] Fix: …` — do exactly what the Fix says; don't guess.
-   Typecheck failures block deploy by design.
-8. **Verify before publish.** The dev shell writes to the `#dev` Studio
-   sandbox — Live team records are never touched, so exercise the app for
-   real.
+   Typecheck failures block the save by design.
+8. **Edits are real.** The dev shell reads and writes the app's LIVE
+   records — there is one set of data, and every write journals into the
+   app's Activity. Exercise the app for real; clean up test rows you
+   create; never seed junk into a team's working tables.
 
 ## CLI reference
 
@@ -71,8 +88,10 @@ names for them; "dev"/"prod" mean something else on this platform.
 | `monty create <slug>` | register the app in the workspace + stamp it into `~/.monty/apps/<id>` (needs login) |
 | `monty current` / `select` / `apps` | where am I / jump to app / list local |
 | `monty install` / `build` / `typecheck` | full lifecycle via the CLI — no raw pnpm/vite/tsc |
-| `monty dev` | run the app in Studio, or attach to an already-running session (auto-port, sandboxed data, auto-auth) |
+| `monty dev` | run the app's session, or attach to an already-running one (auto-port, live data, auto-auth) |
 | `monty logs [-n N] [-f]` | read/follow the dev shell log — the debugging window after every edit |
 | `monty add <name…>` | install curated shadcn components |
-| `monty deploy` | build + typecheck + upload straight to Live (owner escape hatch) |
+| `monty schema [slug]` | print the app's stored manifest (tables, pages, metrics) as JSON |
+| `monty schema set <file\|->` | write an edited manifest back (validated, CAS, additive by default) |
+| `monty save ["what changed"]` | push the working copy to the cloud copy, like `git push main` (build + typecheck gate it) |
 | `monty skills` | (re)install this skill for your agent |

package/skills/monty-design/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: monty-design
+description: Design Monty app pages — Lyra shadcn styling (borderless, sharp-cornered, stock components only), dark-only theming, and the Monty chart language (square marks on real axes). Use whenever building or restyling UI in a Monty app; pages, dashboards, charts, stat tiles, KPI rows, tables, or any prompt about how a Monty app should look.
+---
+
+# Designing Monty pages
+
+Monty is a B2B work OS. Apps render inside the platform shell, so a page is
+"designed" when it looks native to Monty: quiet, rectilinear, data-forward.
+The design system is already installed — your job is to NOT fight it.
+
+## The one law: stock Lyra, nothing invented
+
+Every app ships shadcn preset `radix-lyra` (see `components.json`). Lyra
+surfaces are **borderless and sharp-cornered**: `Card` is `rounded-none`,
+no border, a `bg-card` fill with a hairline `ring-1 ring-foreground/10`.
+
+- Use the components as they come: `Card`/`CardHeader`/`CardTitle`/
+  `CardDescription`/`CardContent`, `Table`, `Badge`, … Never rebuild a
+  surface as a styled `div` — a hand-rolled `rounded-xl border bg-…` card is
+  the canonical mistake.
+- Never invent tokens or raw colors. Semantic tokens only (`bg-background`,
+  `text-muted-foreground`, `border-border`, `var(--chart-2)`, …).
+- Sanctioned overrides are content-level only: e.g. `text-2xl tabular-nums`
+  on a stat value, a width on a label column. If an override styles a
+  SURFACE, you are off the system.
+
+## Dark-only, in the shell's palette
+
+The Monty shell is dark-only; a light page inside it reads as broken. The
+app theme's `.dark` tokens mirror the shell palette (#101112 ground,
+#17181A cards, #266DF0 primary) so embedded pages are seamless — never
+retheme or hand-pick your own dark colors. Until
+the template ships dark by default: `class="dark"` on `<html>` in
+`index.html`, and any boot-splash background set to the dark `--background`
+value. Verify your page against the shell, not in isolation.
+
+## Page anatomy
+
+Every page opens with the platform chrome from `@montytools/sdk/ui` — the
+SAME components the shell renders system table views with, so a custom page
+is indistinguishable from a record page. Never hand-roll the header bar.
+
+```tsx
+import { PageHeader, PageHeaderButton } from "@montytools/sdk/ui";
+
+<div className="flex h-full min-h-dvh flex-col bg-background">
+  <PageHeader icon={ChartColumn} title="Page title" meta="context (count, filter)">
+    <PageHeaderButton onClick={secondary}>Export</PageHeaderButton>
+    <PageHeaderButton primary onClick={main}><Plus className="size-3.5" /> New</PageHeaderButton>
+  </PageHeader>
+  <div className="min-h-0 flex-1 overflow-auto">
+    <div className="flex flex-col gap-3 p-6 pt-4">
+      {/* KPI row */}
+      <div className="grid grid-cols-[repeat(auto-fill,minmax(14rem,1fr))] gap-3">…</div>
+      {/* section cards */}
+      <div className="grid gap-3 lg:grid-cols-2">…</div>
+    </div>
+  </div>
+</div>
+```
+
+Also in `@montytools/sdk/ui`: `FloatingBar` + `FloatingBarButton` (the
+bottom-center bar for bulk-selection actions and mode strips) and the Lyra
+table classes `SURFACE`/`THEAD`/`TH`/`ROW`/`CHIP` — record-like tables are
+`<div className={SURFACE}><table>…` with those classes, identical to the
+shell's Configuration surfaces.
+
+A stat tile is a stock Card, nothing more:
+
+```tsx
+<Card size="sm">
+  <CardHeader>
+    <CardDescription>Leads added</CardDescription>
+    <CardTitle className="text-2xl tabular-nums">{value}</CardTitle>
+    <div className="text-xs text-muted-foreground">{delta or context}</div>
+  </CardHeader>
+</Card>
+```
+
+## Charts: sharp marks on real axes
+
+Chart marks are **sharp rectangles — no rounded corners, ever** (matches the
+Lyra rectilinear look). The three failure modes to avoid: pill "track+fill"
+bars (read as progress bars), rounded caps (misstate where a value ends),
+and floating bars with no axis (nothing anchors the eye).
+
+- **Horizontal bars**: grow from a left hairline baseline
+  (`border-l border-foreground/25`) over quarter gridlines
+  (`absolute left-1/4|1/2|3/4 border-l border-foreground/10` —
+  foreground-alpha so hairlines read on any surface), bar `h-4`,
+  fill `var(--chart-2)`. Label left in `text-muted-foreground`
+  (fixed-width, truncate); count right in `font-medium tabular-nums`,
+  zero values muted with no fill.
+- **Columns**: a value axis with a baseline (`border-foreground/25`) plus
+  hairline gridlines (`border-foreground/10`) and tiny tabular tick labels (10px, muted,
+  right-aligned in a left gutter). Round the axis top to a "nice" integer
+  (≤4 exact; else the next multiple of 5/10/50) so ticks stay honest.
+  Direct value labels above non-zero columns.
+- **Color**: one accent ramp from the Monty palette — `var(--chart-2)` for
+  the emphasized series (today, the selection), `var(--chart-5)` for
+  context. The values are the platform's (Attio-blue family, matching the
+  shell); never restate them as hex, never a hue per category, and text
+  never wears the data color.
+- **Numbers**: `tabular-nums` everywhere values align; money via
+  `toLocaleString(undefined, { style: "currency", currency: "USD" })`
+  (compact notation on tiles, full in tables).
+- **Empty states**: keep the axis and gridlines rendered with an honest
+  muted line ("No activity logged on this day.") — structure stays, zeros
+  carry meaning.
+
+Reference implementations: `ColumnChart` and `BarRow` in
+`demos/crm/src/routes/stats.tsx` (day-selector columns, status bars) and
+`demos/crm-v2/src/routes/stats.tsx` (money detail on bars, top-deals table).
+
+## Checklist before you call a page done
+
+1. No `border`/`rounded-*` on any surface you authored — surfaces are stock
+   Lyra components.
+2. No rounded corners on any chart mark; every bar/column sits on an axis.
+3. Dark: the page blends into the shell with no light seams.
+4. Values in tabular figures; labels in text tokens; one accent hue.
+5. Screenshot it inside the shell (`/apps/<slug>/…`), not just the dev port.

package/skills/monty-operate/SKILL.md

@@ -11,10 +11,8 @@ 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.
+One set of records per app — the team's real data. Writing to it is
+normal operating work; that is what this command is for.
 
 ## The loop
 
@@ -43,10 +41,10 @@ this command is for.
 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.
+3. **Every write is real** — operating work targets the team's data, and
+   the app's Activity journals it. Destructive verbs (`remove`, bulk
+   `update`) 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
@@ -72,7 +70,7 @@ this command is for.
 | `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
+All verbs take `--app <slug>`. Output is one JSON document on
 stdout.
 
 ## Example: import scraped leads into a CRM app