@montytools/cli 0.5.0 → 0.5.2

package/lib/schemaCodegen.mjs

@@ -32,7 +32,8 @@ export function manifestHash(manifest) {
 
 const IMPORTABLE = [
   "defineApp", "formula", "lookup", "montyDate", "montyFileSchema",
-  "montyMember", "montyMoney", "montyPercent", "montyRef", "rollup", "self",
+  "montyMember", "montyMoney", "montyMultiSelect", "montyPercent",
+  "montyPhone", "montyRating", "montyRef", "montySelect", "rollup", "self",
 ];
 
 function fieldsInOrder(section) {
@@ -56,7 +57,34 @@ function storedSource(spec, used) {
       src = `montyRef(${JSON.stringify(spec.table)})`;
       break;
     case "enum":
-      src = `z.enum(${JSON.stringify(spec.values)})`;
+      if (spec.valueDescriptions) {
+        used.add("montySelect");
+        src = `montySelect(${JSON.stringify(spec.values)}, ${JSON.stringify(spec.valueDescriptions)})`;
+      } else {
+        src = `z.enum(${JSON.stringify(spec.values)})`;
+      }
+      break;
+    case "multiSelect":
+      if (spec.valueDescriptions) {
+        used.add("montyMultiSelect");
+        src = `montyMultiSelect(${JSON.stringify(spec.values)}, ${JSON.stringify(spec.valueDescriptions)})`;
+      } else {
+        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
@@ -64,6 +92,7 @@ function storedSource(spec, used) {
       src = "z.any()";
   }
   if (spec.optional) src += ".optional()";
+  if (spec.description) src += `.describe(${JSON.stringify(spec.description)})`;
   return src;
 }
 
@@ -98,6 +127,7 @@ function rollupSource(spec, used, indent) {
   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)},`);
+  if (spec.description !== undefined) lines.push(`description: ${JSON.stringify(spec.description)},`);
   const body = lines.map((l) => `${pad}  ${l}`).join("\n");
   return `rollup(${outputSource(spec.output, used)}, {\n${body}\n${pad}})`;
 }
@@ -108,10 +138,10 @@ function fieldSource(spec, used, indent) {
       return storedSource(spec, used);
     case "formula":
       used.add("formula");
-      return `formula(${outputSource(spec.output, used)}, ${JSON.stringify(spec.expr)})`;
+      return `formula(${outputSource(spec.output, used)}, ${JSON.stringify(spec.expr)}${spec.description !== undefined ? `, ${JSON.stringify(spec.description)}` : ""})`;
     case "lookup":
       used.add("lookup");
-      return `lookup(${outputSource(spec.output, used)}, { ref: ${JSON.stringify(spec.ref)}, field: ${JSON.stringify(spec.field)} })`;
+      return `lookup(${outputSource(spec.output, used)}, { ref: ${JSON.stringify(spec.ref)}, field: ${JSON.stringify(spec.field)}${spec.description !== undefined ? `, description: ${JSON.stringify(spec.description)}` : ""} })`;
     case "rollup":
       return rollupSource(spec, used, indent);
     default:
@@ -159,7 +189,16 @@ export function manifestToConfig(manifest, { name, icon } = {}) {
   }
 
   if (manifest.pages !== undefined) {
-    out.push(`  pages: ${JSON.stringify(manifest.pages, null, 2).replace(/\n/g, "\n  ")},`);
+    // 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montytools/cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TomasMonty/monty-v2.git",

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,64 @@ 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. Give every field a `description` and every enum/multiSelect
+   a `valueDescriptions` map saying WHEN each option applies — that's the
+   guidance later record-writing agents follow. 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 +91,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
 
@@ -42,11 +40,20 @@ this command is for.
    values come from each row, and re-running never duplicates.
 2. **Schema first, rows second.** Field names come from
    `monty data schema`, exact spelling. The server stores what you send —
-   a misspelled field is silently a new field, not an error.
-3. **Live is the default and that's correct** — operating work targets the
-   team's real data. Use `--studio` only when explicitly rehearsing.
-   Destructive verbs (`remove`, bulk `update`) on Live deserve a
-   confirmation with the user unless they clearly asked for the cleanup.
+   a misspelled field is silently a new field, not an error. The schema's
+   `description` and `enumDescriptions` annotations are the app's own
+   instructions for filling a field in: where a field has options (an
+   `enum`, alone or as array items), pick the option whose description
+   matches the situation — never your own reading of the option's name,
+   and never a value outside the list. A field without options has no
+   fixed vocabulary, so its `description` plus the conventions visible in
+   existing rows (`list` first) are the contract — write explicit,
+   consistently formatted values, not free-hand variants of the same
+   thing.
+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
@@ -59,6 +66,13 @@ this command is for.
 7. **Rows come back flattened**: your fields at the top level plus system
    fields `_id`, `_creationTime`, `updatedAt`, `createdBy`. System fields
    are read-only — never send them in `--data`.
+8. **File fields hold descriptors, never bytes or paths.** A `file`-typed
+   field stores exactly the object `monty data upload` prints
+   (`{id, name, contentType, size, uploadedAt, uploadedBy}`). Upload
+   first, then reference: use the attach flags to set an existing row's
+   field in one command, or paste the printed descriptor into `--data`
+   when inserting. Never hand-write a descriptor — an id that no upload
+   produced 404s on download.
 
 ## Command reference
 
@@ -71,8 +85,10 @@ this command is for.
 | `monty data upsert <table> --key <field[,field]> --data '<json\|[json,…]>'` | find-or-create matched on the key fields — the idempotent write |
 | `monty data update <table> <id> --data '<json>' [--unset a,b]` | shallow-merge onto one row; `--unset` deletes fields |
 | `monty data remove <table> <id>` | delete one row |
+| `monty data upload <path> [--name N] [--type mime] [--table <t> --record <id> --field <f>]` | store a file (10MB cap); prints the descriptor a `file` field holds — the attach flags set it on an existing row in the same command |
+| `monty data download <file-id> [--out path]` | fetch a stored file's bytes to disk; the id is the `id` key of a row's file descriptor |
 
-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

package/template/AGENTS.md

@@ -31,15 +31,25 @@ Folders are managed for you: this app lives in `~/Monty/<slug>`. `monty current`
    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.
+   The look is Lyra: surfaces are stock components — borderless,
+   sharp-cornered — never hand-styled divs; chart marks are sharp
+   rectangles on real axes. The `monty-design` skill is the full spec.
 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.
+   `.default(...)` so existing records stay readable. Describe fields for
+   the next agent that fills them in: `.describe("what this holds")` on any
+   field, and `montySelect`/`montyMultiSelect` instead of bare `z.enum` so
+   every option says WHEN it applies, not what the word means.
+5. **You are not done until the work is saved.** After every meaningful
+   change verified in dev, run `monty save "<what changed>"` — it builds,
+   typechecks, and pushes the working copy to the cloud copy, like
+   `git push main`. Unsaved work exists only on this machine.
 
 ## Data: define, then use
 
 ```ts
 // monty.config.ts
-import { defineApp, montyFileSchema } from "@montytools/sdk";
+import { defineApp, montyFileSchema, montySelect } from "@montytools/sdk";
 import { z } from "zod";
 
 export const app = defineApp({
@@ -47,8 +57,12 @@ export const app = defineApp({
   tables: {
     expenses: z.object({
       title: z.string().min(1),
-      amount: z.number().positive(),
-      status: z.enum(["draft", "submitted", "approved"]).default("draft"),
+      amount: z.number().positive().describe("Receipt total in USD, tax included."),
+      status: montySelect(["draft", "submitted", "approved"], {
+        draft: "Still being filled in, not yet sent for review.",
+        submitted: "Awaiting a manager's decision.",
+        approved: "Cleared for reimbursement.",
+      }).default("draft"),
       assigneeId: z.string().optional(), // userId from useMembers()
       receipt: montyFileSchema.optional(),
     }),
@@ -95,7 +109,7 @@ const { url } = useFileUrl(app, row.receipt);            // authenticated blob:
 ## 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.
+you — system table views, record drawers — no React needed.
 This SPA scaffold exists for the pages that ARE bespoke (`pages` entries
 with `kind: "custom"` mount your routes inside that shell).
 
@@ -127,12 +141,11 @@ export const app = defineApp({
       closedAt: montyDate().optional(),
     }),
   },
-  metrics: {  // app-level named numbers for dashboards + formulas (`metrics.wonThisMonth`)
+  metrics: {  // app-level named numbers formulas reach as `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
   },
 });
@@ -140,6 +153,32 @@ export const app = defineApp({
 
 Rules that matter:
 
+- **Custom pages wear the platform chrome from `@montytools/sdk/ui`** — the
+  SAME components the shell renders its own pages with, so your page is
+  indistinguishable from a system table view. Every custom page opens with
+  `PageHeader`; without it the page looks foreign beside record pages:
+
+  ```tsx
+  import { PageHeader, PageHeaderButton } from "@montytools/sdk/ui";
+
+  <div className="flex h-full min-h-dvh flex-col">
+    <PageHeader icon={ChartColumn} title="Reports" meta="42 rows">
+      <PageHeaderButton onClick={exportCsv}>Export</PageHeaderButton>
+      <PageHeaderButton primary onClick={openNew}>
+        <Plus className="size-3.5" /> New
+      </PageHeaderButton>
+    </PageHeader>
+    <main className="min-h-0 flex-1 overflow-auto p-6">…</main>
+  </div>
+  ```
+
+  `primary` marks the page's one main action; other actions wear the quiet
+  control style; `icon` is any lucide icon (defaults to the custom-page
+  puzzle mark the sidebar uses). Also there: `FloatingBar` +
+  `FloatingBarButton` (the bottom-center bar for bulk-selection actions and
+  mode strips) and the Lyra table classes `SURFACE`/`THEAD`/`TH`/`ROW`/`CHIP`
+  for record-like tables (`<div className={SURFACE}><table>…`), identical to
+  the app's Configuration surfaces.
 - **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
@@ -183,10 +222,13 @@ When logic must not run in the browser (private tables, third-party APIs with
 secret keys, webhooks, clocks), create `server/index.ts` with named async
 exports. Web-standard APIs only (`fetch`, `crypto`, `URL`, …) — no `node:`
 imports; it runs on Cloudflare Workers when Live and inside `monty dev` in
-Studio. Every export gets `ctx`: `ctx.records` (full CRUD on all your
-tables, including ones the UI never exposes), `ctx.secrets` (see below),
-`ctx.viewer` (who called: member session/visitor/schedule/none), and
-`ctx.track()` (emit an event).
+a session. Every export gets `ctx`: `ctx.records` (full CRUD on all your
+tables, including ones the UI never exposes), `ctx.files` (platform file
+storage: `upload(data, {name?, contentType?}) → MontyFile`,
+`download(fileOrId) → Blob`, `remove(fileOrId)` — same descriptors as the
+`useUploadFile` hook, 10MB cap), `ctx.secrets` (see below), `ctx.viewer`
+(who called: member session/visitor/schedule/none), and `ctx.track()`
+(emit an event).
 
 ```ts
 // server/index.ts
@@ -227,10 +269,10 @@ Public functions are NOT callable through `useServerFn` — only at their
 public).
 
 **Secrets:** `monty secret set STRIPE_KEY` stores a key for Live (write-only,
-never in code or config). In Studio, put the same names in the gitignored
-`.monty/secrets.json`. Both arrive as `ctx.secrets.STRIPE_KEY`.
+never in code or config). In a dev session, put the same names in the
+gitignored `.monty/secrets.json`. Both arrive as `ctx.secrets.STRIPE_KEY`.
 
-**Studio behavior:** `monty dev` runs your schedules for real (a `cron:` line
+**Session behavior:** `monty dev` runs your schedules for real (a `cron:` line
 prints per firing, UTC) and serves public functions at
 `http://localhost:<port>/__monty/public/<name>` — curl them to test.
 
@@ -247,25 +289,24 @@ monty dev         # Vite + HMR, auto-picks a free port and prints it
 Headless? Verify with `monty build` then `monty typecheck` (typecheck builds
 first when needed — the build generates `src/routeTree.gen.ts`).
 
-**Studio vs Live:** every Monty app has two states. While `monty dev` runs,
-the app is in **Studio** — visible in the workspace to admins only
-(tunneled, `#dev` sandboxed data). **Live** is the published state the
-whole team sees. Going Live is the owner's **Publish** click in the
-workspace menu bar — it signals your running `monty dev`, which builds,
-typechecks, and uploads. You are done when the app works in Studio;
-leave `monty dev` running and let the owner publish. Only run
-`monty deploy` directly if the user explicitly asks.
+**One live app:** there is ONE copy of the app — the one the team uses.
+While `monty dev` runs, workspace admins see your running session's
+version automatically (tunneled); everyone else
+keeps the saved copy. After every meaningful change verified in dev, run
+`monty save "<what changed>"` — it pushes the work to the cloud copy,
+like `git push main` (build + typecheck gate it, so nothing uncompilable
+ever ships). Leave `monty dev` running while you work.
 
 **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
-reactive sandboxed data, and read your errors in the `monty dev` terminal
+reactive live data, and read your errors in the `monty dev` terminal
 (`[browser:error] …` lines). Edit → HMR → look → fix: verify your own work.
 
-Studio writes go to a sandboxed `#dev` namespace inside your real workspace —
-iterate freely, Live app data is untouched. The "STUDIO · … · sandbox data"
-badge confirms it.
+The session reads and writes the app's REAL records — there is one set
+of data, and every write journals into the app's Activity. Treat edits as
+real edits; the "SESSION · … · live data" badge reminds you.
 
 ## Modeling tips
 

package/template/package.json

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