makersclaw 0.6.0 → 0.8.0

package/templates/next/files/README.md

@@ -1,10 +1,11 @@
 # artifact template
 
 The app every artifact starts from: Next.js 16 (app router, JSX, server
-actions, Turbopack), Postgres via `DATABASE_URL`, Tailwind v4, and a kit
-of parts (`components/ui`, `components/parts`). It carries the behaviour
-every app shares, the parts every app is assembled from, and the
-workspace's colours. You design the surfaces: what is on them, how they
+actions, Turbopack), Postgres via `DATABASE_URL` or, in a browser app,
+the platform's data door (§2), Tailwind v4, and a kit of parts
+(`components/ui`, `components/parts`). It carries the behaviour every
+app shares, the parts every app is assembled from, and the workspace's
+colours. You design the surfaces: what is on them, how they
 are laid out, how dense, how they read — never what colour anything is.
 
 ## 1. What you are inside
@@ -48,15 +49,23 @@ Paths here are relative to this folder — the artifact's `app/`.
 `app/`: this file's `app/shell.jsx` is written as `app/app/shell.jsx`,
 `surfaces/<key>.jsx` as `app/surfaces/<key>.jsx`.
 
+An app is one of two modes, and `makersclaw.json`'s `mode` says which.
+A **server app** runs on a Next server of its own (`"server"`, or no
+key). A **browser app** runs in the member's browser: its pages are
+files built once, and every read and write goes through the platform's
+data door (`"browser"`). People add, edit and delete in it as in any
+app. Both lay the files below; a browser app swaps six of them and
+leaves out four (Per mode, below). Which to build: §4.
+
 Yours — write and rewrite freely:
 
 ```
-app/shell.jsx          the inside of the window: nav, layout, type, density
+app/shell.jsx          the inside of the window: nav, layout, type, density — an AppLayout (§3b, Layouts)
 app/DESIGN.md          the design, written before the code (§3)
 surfaces/<key>.jsx     one file per domain surface
 surfaces.js            the manifest entries (import + component when built)
 components/*.jsx       anything shared between surfaces
-components/*-actions.js your own server actions, for a write lib/actions.js cannot make (§5)
+components/*-actions.js a server app's own server actions, for a write lib/actions.js cannot make (§5)
 components/depictions/ pictures of things that exist elsewhere, in their own colours (§3c)
 ```
 
@@ -69,17 +78,59 @@ app/page.jsx           / → the home surface (or "No surfaces yet" while the ma
 app/s/[key]/page.jsx   renders the surface with that key; planned ones say so
 app/error.jsx, app/global-error.jsx, app/not-found.jsx, app/error-relay.jsx, app/auto-refresh.jsx,
 app/escape-relay.jsx, app/frame.js, app/claw-alive/route.js   the app inside its window: refresh while shown (a surface opts out, §7), Escape from the desk
-components/ui/         the kit: Button, Field, Input, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction… (§3b, §3c)
+components/ui/         the kit: AppLayout, DocumentLayout, Button, Field, Input, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction… (§3b, §3c)
 components/parts/      the parts: RecordSwitcher, LiveEmpty + LiveWork, useFixture + FixtureNotice (§3a, §3b)
 check/pins.json        the fixed files by hash; `npm run check` refuses one that differs
-lib/*                  db, data, actions, claw, platform, hooks, sample (§5)
 check/                 `npm run check` (§6)
 proxy.js               product-token check, x-claw-surface and x-claw-theme headers (Next 16's name for middleware.js)
-next.config.mjs        basePath + Server Actions allowedOrigins (and the dev server's allowedDevOrigins), from env (§4b)
+next.config.mjs        basePath + Server Actions allowedOrigins (and the dev server's allowedDevOrigins), from env (§4b);
+                       a browser app's export (output "export"), from makersclaw.json's mode
 postcss.config.mjs     Tailwind v4
-schema.sql             public.artifact_activity, for reference
 ```
 
+And `lib/`, fixed too (§5):
+
+```
+lib/data.js            the reads of your own tables (Reads)
+lib/actions.js         the writes of your own tables: the one-row writes and runAction (Writes)
+lib/db.js              the database pool: query(), logActivity() — a server app's, for its server files
+lib/door.js            your own tables from the browser, through the data door; the hooks (Door)
+lib/brain.js           the company brain from the browser, in both modes; its hooks (Brain)
+lib/brain-server.js    the brain's reads for a server component — a server app's
+lib/claw.js            the _claw API the gateway answers, from the browser
+lib/platform.js        typed wrappers over lib/claw.js (Platform)
+lib/hooks.js           the React hooks over them: useJob, useLlm, useArtifact… (Hooks)
+lib/sample.js          markSample, for sample rows (§3a)
+```
+
+### Per mode
+
+A browser app lays its own copy of six fixed files (the template's
+`templates/next/browser/`). Each is fixed and pinned like the rest, and
+keeps the server copy's names, so a surface imports what it always did:
+
+```
+app/layout.jsx         built once: the theme set by a script in <head> before the page paints; examples decided at build (§3a)
+app/page.jsx           / → a page that forwards to the home surface, keeping the query
+app/s/[key]/page.jsx   one file per surface, whose surface renders in the browser inside <Suspense>
+app/auto-refresh.jsx   asks the data door what changed, and every hook on the page reads again (§7)
+lib/data.js            lib/door.js's reads and hooks, under the usual name
+lib/actions.js         lib/door.js's writes, under the usual name
+```
+
+And it has none of these, since nothing of it runs on a server:
+
+```
+proxy.js               the platform serves the files; there is no request of the app's to check
+app/claw-alive/route.js no route handler runs; the auto-refresh asks the door instead
+lib/db.js              no database login in the app: the door holds it, and knows who is asking
+lib/brain-server.js    the brain's reads run in the browser, through lib/brain.js
+```
+
+`npx makersclaw mode <browser|server>` is the only switch: it lays that
+mode's fixed files, removes the other's, and says what your own code
+must change (§4).
+
 ## 3. Design first
 
 Before any code, write `app/DESIGN.md` — one screen of text:
@@ -96,7 +147,12 @@ Before any code, write `app/DESIGN.md` — one screen of text:
 - Type: scale and weight within the workspace's faces (`font-sans`,
   `font-mono`, `font-display`). Numbers tabular (`data-nums` on the element).
 - Layout and nav: where the surfaces live, what the home surface shows in
-  the first second.
+  the first second. Who scrolls: the shell is an `AppLayout` (§3b,
+  Layouts), the one owner of the window's height; say for each surface
+  whether its content scrolls (a list, an article) or fills (a canvas, a
+  grid that scrolls itself), whether it has an inspector and how wide,
+  and what sits in a footer that must stay in view. Decide it before
+  the shell, not after a long page has pushed a button out of reach.
 - Density, empty states (§3a: what each surface says while its table is
   empty), error states.
 - What makes this app look like ITS domain and not another.
@@ -108,7 +164,8 @@ to design: Agent, Runs and Activity are tabs the OS draws on the window,
 and the app's settings — model, prompt, skills, connections, schedule —
 are the window's Settings tab, the same for every artifact. The keys
 `agent`, `runs` and `activity` are reserved; a surface may not take one.
-The starter `app/shell.jsx` is a placeholder; replace it first.
+The starter `app/shell.jsx` is a placeholder; replace it first, and
+keep it an `AppLayout`.
 
 What the OS does **not** own is asking the agent for something. Those
 tabs are where the founder goes to look back; the app is where they set
@@ -168,7 +225,9 @@ shadcn project. There a surface may still open on a worked example —
 `useFixture(rows, SAMPLE)`, §3b — so its author sees it filled.
 `app/layout.jsx` decides per request: examples are off whenever
 `CLAW_ARTIFACT_ID` is set (`product_run` sets it for every workspace app)
-and on otherwise; `CLAW_EXAMPLES=1` forces them on. Inside a workspace
+and on otherwise; `CLAW_EXAMPLES=1` forces them on. A browser app's
+layout decides the same once, at build: the platform builds every browser
+app with its `CLAW_ARTIFACT_ID`. Inside a workspace
 `useFixture` hands back the real rows — none — so the same surface falls
 through to `LiveEmpty`. Up to 0.3.x a workspace app opened on its example
 until its table had a row; since 0.4.0 it opens empty.
@@ -203,12 +262,64 @@ import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGr
          Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption,
          Spinner, Skeleton, Progress, Separator, Kbd, KbdGroup, AspectRatio,
          Stat, StatGroup, Delta, StatusDot, Legend, Meter, Distribution, Swatch, Steps,
-         toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx }
+         toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx,
+         AppLayout, DocumentLayout }
   from "../components/ui";           // "./ui" from a component
 import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNotice, isSample,
          Examples, useExamples } from "../components/parts";
 ```
 
+- **Layouts** — who owns the window's height, and who scrolls. Every
+  design-first build of 2026-10-07 shipped a shell of `min-h-dvh` that
+  grew with its content: no pane scrolled on its own, and a footer or a
+  button after a long article sat past the end of the window, where
+  nothing could reach it. So the kit owns the window, once, and `npm
+  run check` refuses anything else that sizes by it (`viewport`, §6).
+
+  `AppLayout` is the app frame and the one viewport owner: the
+  outermost one is exactly the window's height; one inside another
+  fills the slot it is in instead, so there is never a second owner.
+  The shell is one. Slots and props:
+  `header` (the top bar, in view; it draws its own bottom border) ·
+  `navigation` (a rail from 768px, `navigationWidth` px, 176 by default;
+  below 768px a Sheet behind the menu button, titled `navigationLabel`;
+  a press on a link closes it) · `children`, the content, with
+  `contentMode` `scroll` (the default: its region scrolls) or `fill` (a
+  bounded column whose child scrolls itself: a canvas, a grid, a
+  spreadsheet), `contentLabel`, `contentClassName` (spacing and token
+  backgrounds only) and `scrollKey` (pass the route: when it changes the
+  content scrolls back to its top and the drawer closes) · `inspector`
+  (beside the content from `inspectorAt` md · lg · xl, lg by default;
+  `inspectorWidth` px, 360 by default, 240 to 560; `inspectorLabel`) ·
+  `footer` (under the content, in view) · `height` viewport · parent.
+  Below `inspectorAt` there is no room for two columns: in `scroll` mode
+  the content and the inspector share one scroll, the inspector after
+  the content, so everything is reachable and nothing hides behind a
+  button; in `fill` mode the inspector is a bounded pane under the
+  content (at most 45% of the height) that scrolls on its own. A
+  surface that needs an inspector or a fill of its own returns an
+  `AppLayout` as its outermost element; inside the shell it fills the
+  content edge to edge (the content's padding drops for it):
+  ```jsx
+  <AppLayout
+    header={<EditorBar draft={draft} />}
+    inspector={<ReviewPanel notes={notes} />}
+    inspectorWidth={440}
+    footer={<SaveState saved={saved} />}
+    contentClassName="p-6"
+    contentLabel="Draft"
+  >
+    <DraftText draft={draft} />
+  </AppLayout>
+  ```
+  `DocumentLayout` is a page that flows, for print and export: no
+  height of its own, it sits in the content and the content scrolls it.
+  `toolbar` (held at the top, never printed), `width` prose · page (A4)
+  · letter · full, `paper` (a sheet on screen, plain in print), `align`
+  start · center, `label`. In print the frame lets go (no bound, no
+  navigation, header, inspector or footer) and the document flows onto
+  pages. Inside either, bound a box by its parent (`h-full`, `flex-1
+  min-h-0`) or by a size (`max-h-96`, `ScrollArea`), never by the window.
 - `Button` — `variant` primary (one per surface, in the app's accent —
   say it: a Button with no `variant` is secondary) · secondary · quiet ·
   danger · link (inline text: no padding or height, wraps and truncates
@@ -494,7 +605,7 @@ default import, framed wherever it is rendered, and is never dropped
 into the shell, the kit or `lib/`: rendered outside its frame it inherits
 the workspace, and the check says so.
 
-**One door, one bundle.** The folder is reached one way: a static
+**One door, one bundle.** The folder is reached one way: a plain
 `import XPost from "…/depictions/x-post"` at the top of the file that
 frames it. No `import()`, no `next/dynamic`, no re-export module, no
 alias (`const P = XPost`), no picture passed along as a value. Through
@@ -507,15 +618,83 @@ never reaches the page.
 
 ## 4. Server and client
 
+### Which mode
+
+**An app is a browser app unless it needs server code.** Server code
+means one of three things:
+
+- a route handler: a proxy to a service with a secret, a render to PDF;
+- an upload larger than the data door takes;
+- SQL a member types (`sql-console`).
+
+Nothing else needs a server. A browser app reads and writes its own
+tables and the company brain through the door, runs a write of more
+than one row as an action (§5), and has no process of its own to start,
+stop or crash. `makersclaw.json`'s `mode` says which this app is
+(`"browser"` is a browser app; §2). An app moves with `npx makersclaw
+mode server` (or `browser`), and its own code moves in the same build:
+the command prints what must change.
+
+### A browser app
+
+Its pages are built once, with no request, into files the platform
+serves. Everything below runs in the member's browser:
+
+- **Every surface is a client component.** Its file starts with `"use
+  client"`. It reads through the hooks: `useRows`, `useRow`, `useCount`,
+  `useCountBy` and `useActivity` from `lib/data.js`, and the brain's
+  `useRecords`, `useRecord`, `useRecordCounts` and `useBrainSearch` from
+  `lib/brain.js`. It hands rows to blocks once they have loaded, and
+  wires the blocks' callbacks to `lib/actions.js` (§5, Door, has a
+  whole surface).
+- **It receives `surface` alone.** No `searchParams`: the page has no
+  request. `?row=`, `?list=` and any other view state come from
+  `useSearchParams()` (`next/navigation`).
+- **No `process.env` in its code but `CLAW_BASE_PATH`, `CLAW_PRODUCT`
+  and `NEXT_PUBLIC_*`.** A prerendered page prints what it reads into a
+  file anyone who opens the app can fetch. A secret stays with the
+  platform; the build never sees `.env`.
+- No `"use server"`, no `route.js`, no `proxy.js`, no import of
+  `next/headers`, `next/cache`, `next/server`, `pg` or `lib/db`, no
+  route segment config (`dynamic`, `revalidate`…). There is no server to
+  run them, and `npm run check` names each one (§6, `browser`).
+
+```jsx
+// surfaces/investors.jsx (a browser app)
+"use client";
+import { useSearchParams } from "next/navigation";
+import { useRows } from "../lib/data";
+import InvestorBoard from "../components/InvestorBoard";
+
+export default function Investors() {
+  const highlight = useSearchParams().get("row");
+  const { rows, error, loading } = useRows({ source: "investors", orderBy: "updated_at desc" });
+  if (loading) return null; // nothing until the first answer: useFixture must not take a read in flight for an empty table
+  return <InvestorBoard rows={rows} error={error} highlight={highlight} />;
+}
+```
+
+`components/InvestorBoard.jsx` is the same file in both modes (below):
+it calls `moveRow` from `lib/actions.js`, which in a browser app goes
+through the door.
+
+### A server app
+
 One split, stated once:
 
 ```
 lib/data.js, lib/db.js       server components and server actions only
 lib/platform.js, lib/hooks.js   "use client" files only
 lib/actions.js               either (they are server actions)
+lib/brain.js                 "use client" files only, in a server app too (§5, Brain)
+lib/door.js                  "use client" files only: the own tables from the browser (§5, Door)
+lib/brain-server.js          server components only: the brain's reads
 surfaces.js                  server files only (entries import components)
 ```
 
+In a browser app every `lib/` file but `sample.js` is for `"use client"`
+files, and `surfaces.js` is the pages'.
+
 Pass plain data across the boundary — strings, numbers, arrays, objects.
 `plain(row)` already turns a timestamp into its ISO string. A `date`
 column is its day, `"2026-09-28"`: text, the same day for every reader,
@@ -537,7 +716,7 @@ import { loadRows } from "../lib/data";
 import InvestorBoard from "../components/InvestorBoard";
 
 export default async function Investors({ surface, searchParams }) {
-  const { rows, error } = await loadRows({ source: "public.investors", orderBy: "updated_at desc" });
+  const { rows, error } = await loadRows({ source: "investors", orderBy: "updated_at desc" });
   return <InvestorBoard rows={rows} error={error} highlight={searchParams.row ?? null} />;
 }
 ```
@@ -559,7 +738,11 @@ export default function InvestorBoard({ rows: real, error, highlight }) {
 
 Every surface component receives `surface` (`{ key, kind, label, source
 }`) and `searchParams` (the URL query; `?row=<id>` is the convention for
-"highlight this row" — an activity line opens its surface with it).
+"highlight this row" — an activity line opens its surface with it). A
+browser app's surface receives `surface` alone and reads the query with
+`useSearchParams()` (above).
+`source` is the table's bare name, `"investors"`, with no schema in
+front: the app's tables are in its own schema (§5, Your tables).
 
 ### Views by link
 
@@ -572,10 +755,12 @@ part of the contract, the same way `?row=` is:
 - `?list=<value>` shows one list. An app that keeps separate lists in
   shared tables declares which column names them (`lists: { table,
   column }`), and every surface over that table reads `list` and filters
-  by that column — `loadRows({ source, filter: searchParams.list ? {
-  [column]: searchParams.list } : undefined })`. With no `list` it shows
-  every list: a filter of `{ [column]: undefined }` matches no row at
-  all. It is the one key every app with lists honours.
+  by that column — `loadRows({ source, filter: { [column]:
+  searchParams.list } })`; in a browser app, `useRows({ source, filter:
+  { [column]: useSearchParams().get("list") ?? undefined } })`. With no
+  `list` it shows every list: a column
+  whose condition is `undefined` is no condition (up to 0.6.x it matched
+  no row). It is the one key every app with lists honours.
 - A job's view may declare a filter (`week=this&list={list}`; `{list}`
   and `{since}` are filled in per request). Its keys are query params
   the surface ALREADY reads: declare one only for a param the surface
@@ -608,6 +793,11 @@ action="/…">`. A real external URL (`https://`, `mailto:`) is fine.
 
 ### 4b. Writes are rejected — "Invalid Server Actions request"
 
+A server app only. A browser app has no Server Actions: its writes go
+to the data door on the page's own origin, and nothing here applies to
+them. Its preview still runs on `next dev`, so the dev server's
+`allowedDevOrigins` below holds for it too.
+
 Already handled. Do not fix it in `next.config.mjs`.
 
 Next refuses a Server Action whose `Origin` header disagrees with
@@ -631,53 +821,205 @@ source — say so and stop; it is not an app-level fix.
 
 ## 5. API reference
 
+### Your tables — one schema, named bare
+
+The app's tables live in its own schema, and no other app reads them.
+In Makersclaw that is `app_<name>`, and `makersclaw.json` says
+`"tables": "own"`. Besides its own tables, the app's database role
+reaches only what the platform lays for it under `claw.` and
+`claw_app.` (the activity door, `claw_app.activity`, below).
+
+**Name every table bare: `deals`, with no schema in front — neither
+`public.` nor `app_<name>.`.** The role's search path sends a bare name
+to the app's schema. A schema written by hand breaks the app: its role
+reaches nothing in `public`, and a second copy of the app lives in a
+schema of another name. Bare holds everywhere a table is named: a
+surface's `source`, every `lib/data.js` and `lib/actions.js` call, and
+SQL of your own (`update deals set …`). `npm run check` refuses a
+qualified name (§6, `tables`).
+
+One schema per app, not one per copy of its code. A change build's
+preview reads and writes the live app's tables, so rows saved while
+testing are real rows. In a change to a live app, add what the change
+needs (new tables, new columns that allow null or have a default);
+remove or rename in a build after it ships.
+
+**The company's things are not your tables.** A customer, a person, a
+product — anything another app or a person would look up — is a record
+in the company brain, read and written through `lib/brain.js` (Brain,
+below). A row of yours points at a record by a `uuid` column named for
+its kind (`contact_id`), declared in `links`. Never copy a record's
+fields into a table of yours: the copy goes stale the day someone edits
+the record.
+
+`makersclaw init --tables own|public` records where the tables live;
+Makersclaw passes it. It never changes afterwards: an app's tables move
+from `public` to their own schema only with its workspace. An app laid
+before 0.7.0 has no `tables` key: its tables are in `public`, and a
+bare name reaches them there too. So write names bare in either.
+
 ### Reads — `lib/data.js` (server)
 
+In a browser app `lib/data.js` is the door's (Door, below): these same
+names, shapes and filters, called from `"use client"` files, with a hook
+for each.
+
 Every read resolves `{ ..., error }` and never throws. `error` is text
 when the table is missing or the database unreachable; it is also
 `console.error`ed, so the log tail carries it to the platform agent.
-`source` is `"table"` or `"schema.table"`; names go through `ident()`.
+`source` is the table's bare name (`"drafts"`); names go through
+`ident()`. It still takes `"schema.table"`, for an app from before
+0.7.0 whose code names `public.<table>`.
 
 ```js
 loadRows({ source, idColumn = "id", orderBy, limit = 500, filter })  → { rows, error }
 loadRow({ source, idColumn = "id", id })                            → { row, error }      // row null when none
 countRows({ source, filter })                                       → { count, error }
 countBy({ source, column, filter })                                 → { counts: { [value]: n }, error }
-loadActivity({ limit = 100, surface, since })                       → { rows, error }     // public.artifact_activity, this artifact
+loadActivity({ limit = 100, surface, since })                       → { rows, error }     // claw_app.activity: this app's lines
+```
+
+`filter` is an AND of `{ column: condition }`, at most 20: the
+platform data door's grammar, so a filter means the same in a server
+app and a browser one.
+
+```
+value                        equals (text, a number, true or false, a Date)
+[value, …]                   one of, at most 1,000
+null                         empty
+{ not: value | null }        anything else, empty rows included; or not empty
+{ gt | gte | lt | lte: v }   a bound; one lower and one upper may combine
+{ has: value }               an array column (text[], int[]…) holds it
+{ prefix: "text" }           starts with, case ignored
 ```
 
-`filter` is `{ column: value }`: `null` → `IS NULL`, an array → `= ANY`,
-else equality. `orderBy` is `"updated_at desc, id"`; default `idColumn
-desc`. `limit` caps at 5000 (activity: 1000).
+A column whose condition is `undefined` is left out. Anything else is
+refused, and the read returns why as its `error`. `orderBy` is
+`"updated_at desc, id"`; default `idColumn desc`. `limit` caps at 5000
+(activity: 1000).
 
 ```js
-const { rows, error } = await loadRows({ source: "public.drafts", filter: { stage: ["draft", "approved"] } });
-const { counts } = await countBy({ source: "public.investors", column: "stage" });
+const { rows, error } = await loadRows({ source: "drafts", filter: { stage: ["draft", "approved"] } });
+const { rows: due } = await loadRows({ source: "tasks", filter: { done: false, due: { lte: today }, owner: { not: null } } });
+const { counts } = await countBy({ source: "investors", column: "stage" });
 const { rows: log } = await loadActivity({ surface: "drafts", limit: 50 });
 ```
 
 Helpers: `plain(row)` (timestamps → ISO, buffers → base64; a `date` is
 already its `"YYYY-MM-DD"`), `orderClause(orderBy,
-fallback)` (validated `ORDER BY` text), `markSample(sample, idColumn)`
+fallback)` (validated `ORDER BY` text), `whereClause(filter, params)`
+(the filter above as `WHERE` text), `markSample(sample, idColumn)`
 (stable ids + `_sample: true`), `currentSurface(explicit)` (the surface
 key of the request, from `x-claw-surface`, unless one is passed).
 
 ### Writes — `lib/actions.js` (server actions, callable from either side)
 
-Each quotes names with `ident()`, writes one activity row through
-`logActivity`, calls `revalidatePath("/", "layout")`, and resolves
-`{ ok }` or `{ ok: false, error }`. Never throws. `surface` defaults to
-the request's surface (proxy.js sets it from `/s/<key>`).
+In a browser app `lib/actions.js` is the door's (Door, below): these
+same names, shapes and codes, as plain functions of the browser. The
+door runs each write and writes its activity line.
+
+In a server app each quotes names with `ident()`, runs in its own
+transaction, writes one activity row through `logActivity` after it
+commits, calls `revalidatePath("/", "layout")`, and resolves `{ ok }`
+or `{ ok: false, error, code }`. Never throws. `code` is the data
+door's (Door, below), so a surface branches on it the same way in both
+modes: `not_found` (no such row), `no_such_table`, `no_such_action`,
+`action_refused`, `conflict`, `bad_request`, `too_slow`, `try_again`,
+else `failed`. `surface` defaults to the request's surface key
+(the `<key>` of `/s/<key>`, which proxy.js reads).
 
 ```js
-updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data })
+updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data, log })
 moveRow({ source, idColumn = "id", id, stateColumn, to, surface })            // action "moved"
 insertRow({ source, idColumn = "id", values, surface, action = "added", detail }) → { ok, id }
 deleteRow({ source, idColumn = "id", id, surface, detail })                   // action "removed"
 saveSetting({ mode = "table" | "json", source, keyColumn = "key", valueColumn = "value",
               column, idColumn = "id", id, key, value, surface })
+runAction({ name, args, surface, action, detail, rowRef, log })               → { ok, result }
+```
+
+`log: false` (`updateRow` and `runAction` only) writes no activity line:
+for a save that is typing, not a decision, like an autosave every few
+keystrokes. An insert and a delete always log. Name such a write "no
+activity line" in the brief (`references/actions.md`), so the agent logs
+none for it either. The door takes the same `log: false` in a browser
+app.
+
+**Who is asking.** Each write's transaction first sets two settings,
+local to it: `claw.member_id` and `claw.member_email`, the member the
+platform named on the request (`''` when none: a local run, a job).
+The platform's data door sets the same two for a browser app, and the
+agent's `sql` for the member it acts for. A default, a trigger or an
+action reads them:
+
+```sql
+nullif(current_setting('claw.member_email', true), '')
 ```
 
+A column the page must not choose (`created_by`, `approved_by`) is set
+by a `before insert` or `before update` trigger that reads it, never
+sent from the page: a default alone keeps whatever the page sends.
+Made with `sql`, once per table:
+
+```sql
+create or replace function deals_created_by() returns trigger
+language plpgsql as $$
+begin
+  new.created_by := nullif(current_setting('claw.member_email', true), '');
+  return new;
+end $$;
+create trigger deals_created_by before insert on deals
+  for each row execute function deals_created_by();
+```
+
+It is a label, not a permission: nothing checks it, and the app's own
+agent can set it too.
+
+**Actions.** A write of more than one row, or one that decides
+something, is an action: a function in the app's own schema, `(args
+jsonb) returns jsonb`, made with the `sql` verb. The screen calls it
+with `runAction`, which runs `select <name>($1::jsonb)` with `args` as
+JSON (`{}` when none); the app's agent runs the same function with
+`sql`, so the two can never drift. Its name is one bare, lower-case
+name (`close_cycle`): the data door calls only a function of the app's
+own schema, so a name with a schema or capitals (`CloseCycle`) is
+`no_such_action` in both modes. It refuses with `raise exception '<sentence>'`, which
+comes back as `error`, code `action_refused`. It never writes
+`claw_app.activity`: `runAction` logs the call (`action` defaults to the
+function's name, `row_ref` is `rowRef` or the result's `id`), and the
+agent logs its own.
+
+```sql
+create or replace function close_cycle(args jsonb) returns jsonb
+language plpgsql as $$
+declare
+  c uuid := (args->>'cycle')::uuid;
+begin
+  update cycles set status = 'closed', closed_at = now() where id = c and status = 'open';
+  if not found then raise exception 'that cycle is already closed'; end if;
+  update goals set status = 'carried' where cycle_id = c and status = 'open';
+  return jsonb_build_object('id', c);
+end $$;
+```
+
+```js
+const r = await runAction({ name: "close_cycle", args: { cycle: id }, action: "closed", detail: "Q3" });
+if (!r.ok) setError(r.error); // "that cycle is already closed"
+```
+
+**Name every action in the agent's brief, `references/actions.md`,
+with its `select`**: `` `close_cycle` `` and `select
+close_cycle($1::jsonb)`, its params and what it refuses. The agent
+runs it from there, and `npm run check` refuses an action the screens
+run that the brief does not name (§6, `agent`).
+
+In a change to a live app, never change or drop a function the live app
+runs, a helper one included: the preview writes the live schema, so the
+live screens would run the new body at once, and a roll back would run
+it too. Write a new one (`close_cycle_2`), call it from the new code and
+name it in `references/actions.md`. Drop the old one once neither the
+live build nor the one kept for roll back calls it.
+
 `saveSetting` table mode updates the `(key, value)` row and inserts one
 when missing — a plain `key text, value text` table is enough. JSON mode
 sets `key` inside the jsonb `column` of row `id`.
@@ -692,19 +1034,288 @@ the column's default: `updated_at timestamptz not null default now()`.
 ```js
 "use client";
 import { moveRow } from "../lib/actions";
-const r = await moveRow({ source: "public.investors", id, stateColumn: "stage", to: "sent" });
+const r = await moveRow({ source: "investors", id, stateColumn: "stage", to: "sent" });
 if (!r.ok) setError(r.error);
 ```
 
 Never write raw SQL from a surface. `lib/*.js` is fixed (`npm run check`
 refuses an edit, and `makersclaw update` lays the file again), so a write
-these cannot make goes in a server-action file of the app's own:
-`"use server"` on its first line, beside the components that call it
-(`components/deal-actions.js`). There it composes the actions above, or
-runs its UPDATE or DELETE through `query()` from `lib/db.js`, records it
-with `logActivity()` and ends with `revalidatePath("/", "layout")`, as
-`lib/actions.js` does. A new row still goes through `insertRow`: the
-check refuses a raw `INSERT INTO` anywhere outside `lib/`.
+these cannot make is an action (above), called with `runAction`. In a
+server app only, a server-action file of the app's own (`"use server"` on its first line,
+beside the components that call it: `components/deal-actions.js`) may
+compose the writes above. A new row still goes through `insertRow`:
+the check refuses a raw `INSERT INTO` anywhere outside `lib/`, and, in
+an app on its own tables, any SQL that writes in the app's code (§6,
+`agent`).
+
+### Door — `lib/door.js` (browser, both modes)
+
+The app's own tables, read and written from the browser through the
+platform's data door, `_claw/data`. The gateway answers it under the
+app's path, as the member whose cookie comes with the request. Each
+write runs on the app's own database login, in one transaction that
+knows who is asking (`claw.member_email`, above), and the door writes
+its activity line.
+
+A browser app (`"mode": "browser"` in `makersclaw.json`) has no server of
+its own. Its `lib/data.js` and `lib/actions.js` are this file under
+their usual names, so a surface imports as it always did:
+`import { useRows } from "../lib/data"`, `import { moveRow } from
+"../lib/actions"`. In a server app a `"use client"` component may take
+the hooks from here.
+
+```js
+// Reads: lib/data.js's names and shapes
+loadRows({ source, idColumn = "id", orderBy, limit = 500, filter, offset, cursor }) → { rows, error, next }
+loadRow({ source, idColumn = "id", id })            → { row, error }      // row null when none, or no id
+countRows({ source, filter })                       → { count, error }
+countBy({ source, column, filter })                 → { counts, error }
+loadActivity({ limit = 100, surface, since })       → { rows, error }
+
+// Writes: lib/actions.js's names and shapes
+insertRow({ source, idColumn, values, surface, action, detail })          → { ok, id }
+updateRow({ source, idColumn, id, patch, surface, action, detail, log })  → { ok }
+moveRow({ source, idColumn, id, stateColumn, to, surface })               → { ok }
+deleteRow({ source, idColumn, id, surface, detail })                      → { ok }
+saveSetting({ mode, source, keyColumn, valueColumn, column, idColumn, id, key, value, surface })
+runAction({ name, args, surface, action, detail, rowRef, log })           → { ok, result }
+
+// Hooks: a read on mount, and again on dataChanged()
+useRows(opts)  useRow(opts)  useCount(opts)  useCountBy(opts)  useActivity(opts)
+                                                    → { …the read's values, error, loading, reload }
+dataChanged()   every hook on the page reads again
+whenLanded()    resolves once those reads have landed
+```
+
+- `filter` is the grammar above (Reads), sent as it is. `orderBy` is
+  `"updated_at desc"`. `cursor` is the last answer's `next`, which the
+  door gives only when `orderBy` names one column; `offset` is at most
+  10,000.
+- Every function resolves and never throws. A read that fails keeps its
+  empty values: `{ rows: [], error, code }`. A write that fails is
+  `{ ok: false, error, code }`, never `undefined`. Branch on `code`;
+  show `error`.
+- No door answers (a copy on its own, an older Makersclaw):
+  `unavailable: true`, code `unavailable`. Show a quiet "not connected
+  yet".
+- The codes a page meets: `bad_request` (a column, filter or order the
+  table does not have), `no_such_table`, `no_such_action`, `not_found`,
+  `read_only` (a view: write the table it reads), `action_refused` (an
+  action's own `raise exception`: show its sentence), `conflict` (a
+  unique or foreign key), `too_slow`, `try_again`, `rate_limited`.
+- Writes go one at a time, in the order they were called, as Server
+  Actions did. A slow save never lands after the newer one.
+- A write that answers ok calls `dataChanged()`: every hook on the page
+  reads again, the brain's too. When the next step needs the new rows
+  (open the row just made), `await whenLanded()` first.
+- `loading` is true until a hook's first answer, and again when its
+  options change. A re-read keeps the last rows, and `loading` false,
+  until the new ones land; each answer is a new array. A failed re-read
+  keeps the rows and sets `error`.
+- A hook compares its options by value on every render: a new object
+  with the same values reads nothing. A server component read once per
+  request; a hook's own answer is a render. So a time in a bound
+  (`filter`, the brain's `where`, `since`; a Date or ISO text) is
+  compared to the minute: `useActivity({ since: new Date(Date.now() - 7
+  * 864e5) })` reads once, and again only after the minute has moved
+  on, keeping its rows meanwhile. The read sends the time as given.
+  Anything else worked out on each render (a `Date.now()` number) is new
+  options every time, and reads every time: work it out once
+  (`useMemo`, `useState`).
+- `useRow` with no `id` asks nothing: `row` is null.
+- `surface` defaults to the page's surface key (the `<key>` of
+  `/s/<key>` in its path). `data` on `updateRow` is taken and never
+  sent: the door never puts a value in a line. `log: false` as in
+  Writes.
+- The door writes the activity line. Nothing in the browser logs.
+
+```jsx
+// surfaces/deals.jsx (a browser app)
+"use client";
+import { useSearchParams } from "next/navigation";
+import { useRows, whenLanded } from "../lib/data";
+import { insertRow, moveRow } from "../lib/actions";
+import { Notice } from "../components/ui";
+import { Board } from "../components/blocks/board";
+
+export default function Deals() {
+  const opened = useSearchParams().get("row");
+  const { rows, error, loading } = useRows({ source: "deals", orderBy: "updated_at desc" });
+  if (error) return <Notice tone="danger">{error}</Notice>;
+  return (
+    <Board
+      rows={loading ? undefined : rows}
+      groupBy="stage"
+      columns={["lead", "call", "won"]}
+      onMove={(d, to) => moveRow({ source: "deals", id: d.id, stateColumn: "stage", to })}
+      onCreate={async (name, stage) => {
+        const r = await insertRow({ source: "deals", values: { name, stage } });
+        if (r.ok) await whenLanded();
+        return r;
+      }}
+    />
+  );
+}
+```
+
+### Brain — `lib/brain.js` (browser, both modes)
+
+The company brain is the workspace's shared records: contacts,
+companies, deals, whatever kinds the workspace keeps. Each record sits
+in an area (Everyone, Finance…). Every app sees the same Jane Doe.
+
+An app reaches the brain only through the data door, `_claw/data`. The
+gateway answers it under the app's path, so it works while the app's
+machine sleeps. It hands the app only the kinds `makersclaw.json`
+declares, and only the records the member may read. Never SQL: the
+app's database login holds none of the brain.
+
+**What the app declares: `brain` in `makersclaw.json`.** Write it
+before the first call. The platform grants it when the app ships; a
+ship that widens it waits for the member's Yes.
+
+```json
+"brain": {
+  "kinds": [
+    { "kind": "contact", "label": "Contact", "plural": "Contacts",
+      "fields": [{ "name": "name", "type": "text" }, { "name": "email", "type": "email" }],
+      "key": ["email"], "filters": [] }
+  ],
+  "reads": ["note"],
+  "writes": ["contact"],
+  "links": [{ "table": "tasks", "column": "contact_id", "kind": "contact", "on_erase": "null" }]
+}
+```
+
+- `kinds`: the full def of every kind the app reads or writes, since
+  the workspace may not have it yet. `note`, the brain's own kind, needs
+  none.
+- `reads` and `writes`: kinds by name. Writing implies reading. The door
+  answers any other kind `not_declared`.
+- `links`: a `uuid` column of one of the app's own tables (named bare,
+  `"tasks"`) that holds a record's id, and what erasing that record does
+  to the row (`null` or `delete`). Own tables only (`"tables": "own"`).
+
+`npm run check` checks the block's shape and that every call names a
+kind it declares (§6). The rest (field types, keys, each link against
+your tables) the platform checks when the app ships.
+
+Call these from `"use client"` files, in a server app too. The grant
+cookie is who is asking, and it makes a write the member's press:
+confirmed, and able to overwrite a confirmed value, erase or merge. A
+write from the app's server would be app code acting: unconfirmed, and
+skipped over a confirmed value. So there is no Server Action for the
+brain.
+
+```js
+import { listRecords, writeRecord } from "../lib/brain";
+
+// Reads
+kinds()                                                    → { kinds, brain, error }
+listRecords({ kind, where, order, limit, cursor, fields, prefix, state })
+                                                           → { records, next, error }
+getRecord({ id, links = false, state })                    → { record, links, error }
+countRecords({ kind, by, where })                          → { count, by, error }
+searchBrain({ q, kinds, limit, meaning })                  → { results, meaning, error }
+recordHistory({ id, limit, cursor })                       → { changes, next, error }
+brainChanges({ since, kinds })                             → { changes, next, error }
+brainLists({ kind })                                       → { lists, error }
+listMembers({ list, limit, cursor })                       → { list, records, next, error }
+
+// Writes
+writeRecord({ kind, id, fields, area, from, ifVersion, owner, surface, detail })
+                                                           → { ok, id, created, changed, version, skipped }
+writeRecords({ writes })                                   → { ok, results }      // at most 100, all or none
+confirmFields({ id, fields })                              → { ok, confirmed, version }
+eraseRecord({ id, reason })                                → { ok, erased }       // gone for every app, no undo
+mergeRecords({ keep, drop })                               → { ok, id, merged, filled, version }
+linkRecords({ from, to, type })                            → { ok, created }
+unlinkRecords({ from, to, type })                          → { ok, removed }
+createList({ name, kind, area })                           → { ok, id }
+changeList({ list, add, remove, position })                → { ok, added, removed }
+
+// Hooks: a read on mount, and again on dataChanged() (lib/door.js's rules)
+useRecords(args)          useRecord(args)                  // no id: record null, nothing asked
+useRecordCounts(args)     useBrainSearch(args)             // a blank q asks nothing
+                                                           → { …the read's values, error, loading, reload }
+```
+
+Every function resolves and never throws:
+
+- A read resolves the door's JSON with `error: null`.
+- A write resolves the door's JSON.
+- A refusal is `{ ok: false, error, code }`. A read keeps its empty
+  values (`records: []`, `next: null`), so the surface renders it like
+  no rows. Branch on `code`; show `error`.
+- A 404 with no code, or no network, is
+  `{ ok: false, unavailable: true }`: a claw with no door yet. Show a
+  quiet "not connected yet".
+
+Arguments are camelCase (`ifVersion`). Results are the door's keys as
+they come (`label_field`, `updated_at`).
+
+A record is `{ id, kind, area, label, fields, state, unconfirmed, owner,
+source, created_at, updated_at, version }`. `fields` holds the values;
+`state` says, field by field, who wrote it and whether a person
+confirmed it.
+
+- `where` is an AND of conditions on the kind's fields:
+  `{ stage: "lead" }` equals, `{ stage: ["lead", "won"] }` one of,
+  `{ phone: null }` empty, `{ not: v }`, `{ gt | gte | lt | lte: v }`,
+  `{ has: v }` (a choices field), `{ prefix: "ja" }`. Also `area`,
+  `owner_id`, `unconfirmed`, `updated_at`. A kind's declared `filters` are fast;
+  another field scans the kind and may answer `too_slow`.
+- `order` is `-updated_at` (the default), `updated_at`, `created_at`,
+  `-created_at`, `label`, `-label`, `<field>` or `-<field>`.
+- `limit` is 50 by default, at most 200. `cursor` is the last answer's
+  `next`; `next` is null at the end.
+- `state: false` leaves each field's state out. `fields: ["name"]`
+  returns only those.
+- `searchBrain` looks by words and by meaning. `meaning: false` is words
+  only: nothing is embedded and nothing is charged. Use it for a picker
+  that searches as the member types. A blank `q` asks nothing.
+- `brainChanges` is what changed in the member's areas and the app's
+  kinds since `since`, the last answer's `next`.
+- `ifVersion` refuses a write with `changed` when someone saved the
+  record after the page read it.
+- `surface` defaults to the page's surface key (the `<key>` of
+  `/s/<key>` in its path: `contacts`, not `/s/contacts`); `detail` is
+  one sentence.
+
+The door writes the activity line for every write it takes (Activity,
+below). Never call `logActivity` for a brain write. Writes go one at a
+time, in the same turn as `lib/door.js`'s. One that answers ok calls
+`dataChanged()`, so every hook on the page reads again (these four and
+the own tables'); a server app may also `router.refresh()`.
+
+The codes a page meets: `not_declared` (the app did not declare that
+kind, or not for writing), `not_granted` (the workspace has not granted
+the app's areas yet), `area_not_granted`, `unknown_kind`, `not_found`,
+`bad_field`, `bad_request`, `changed`, `hidden_match` (a record with
+that key is in an area the member cannot read), `key_taken`,
+`not_a_person`, `rate_limited`, `too_slow`, `not_signed_in`.
+
+**Server reads — `lib/brain-server.js`.** The same nine reads, same
+arguments and results, for a server component in a server app (a
+browser app has no such file: its brain reads are the hooks above). They go
+with the door grant the product proxy stamps on each member's request
+(`x-claw-door`), to `CLAW_DOOR_URL`. It has no writes. With no grant (a
+render outside a member's request, or a machine whose proxy does not
+stamp it yet) each read answers
+`{ ok: false, unavailable: true, code: "no_door" }`: read in the browser
+instead.
+
+```js
+// surfaces/contacts.jsx (server)
+import { listRecords } from "../lib/brain-server";
+import ContactList from "../components/ContactList";
+
+export default async function Contacts({ searchParams }) {
+  const first = await listRecords({ kind: "contact", order: "label" });
+  // no_door: ContactList reads with lib/brain.js in the browser.
+  return <ContactList first={first.code === "no_door" ? null : first} highlight={searchParams.row ?? null} />;
+}
+```
 
 ### Platform — `lib/platform.js` (browser)
 
@@ -721,6 +1332,8 @@ import { platform } from "../lib/platform";   // or the named functions
 platform.me()                                          GET  _claw/me       → { artifact: { id, name, vehicle, status, home }, user: { id, email }, blueprint, desk_origin }
 platform.ask({ text, row, how, job, list, surface, sessionId, open })
                                                        POST _claw/ask      → { ok, request, desk_origin }, and the column opens on it
+platform.llm(input, { system, schema, maxTokens, tier, task, signal })
+                                                       POST _claw/llm      → { ok: true, text } | { ok: true, data } | { ok: false, error, code }  (Calling a model)
 platform.requests()                                    GET  _claw/requests → { requests, run, desk_origin }
 platform.requests({ id })                              GET  _claw/requests?id=<id> → { request }
 platform.stopRequest(id)                               POST _claw/requests/<id>/stop → { ok, request }
@@ -744,13 +1357,16 @@ didnt_finish. `line` is the one line every screen shows for it
 show it as it is, never a status word of your own. `app_session_id` is
 set only on your own requests.
 
-Named exports: `me, ask, requests, stopRequest, openRequest,
+Named exports: `me, ask, llm, requests, stopRequest, openRequest,
 surfaceOfPath, startJob, cancelJob, reportError, platform`. That is the
 whole list. Note what is **not** there: the runs, the chat history, Run
 now, Pause / Resume. Those are MONITORING and they are the OS's — the
 window's tabs and title bar — so an app never calls `_claw/agent`,
 `_claw/runs`, `_claw/run`, `_claw/pause` or `_claw/resume`. Asking is the
 opposite thing, and it belongs here (`ask()` and `useJob`, below).
+`llm()` is neither: one call to a model, answered in the page (Calling a
+model, below). It is the one wrapper that resolves the platform's answer
+as it is, `{ ok: true, text }` and not `{ ok: true, status, data }`.
 `requests` is not monitoring either: it is this app's asks in flight, so
 an empty surface can show the work coming (§3a). `startJob` and
 `cancelJob` are the 0.3.x door to the same work, kept so `useJob` can
@@ -763,8 +1379,8 @@ that exact origin — never `"*"` — and only while the app is framed.
 
 ### Hooks — `lib/hooks.js` ("use client")
 
-Four hooks: a generic fetch over one `_claw` route, the app's identity,
-a job, and the app's requests. Each owns fetching, polling (while the
+Five hooks: a generic fetch over one `_claw` route, the app's identity,
+a job, the app's requests, and a model call. Each owns fetching, polling (while the
 tab is visible; once a minute while `unavailable`), streaming and cleanup
 on unmount. A surface renders what comes back and owns every pixel.
 
@@ -775,6 +1391,7 @@ useJob()                                      → { running, status, queued, que
                                                   steps, text, progress, error, sessionId, requestId, request, finishedAt,
                                                   start, cancel, reset, open }
 useRequests({ surface, job, every = 5000 })   → { requests, live, run, loading, error, unavailable, reload, open, stop }
+useLlm()                                      → { run, loading, result, error, unavailable }   (Calling a model)
 jobFromRequest(request)                       → what useJob shows for one request (pure; for tests)
 ```
 
@@ -791,10 +1408,10 @@ while the App tab is on screen (behind the window's other tabs it asks
 nothing; coming back looks at once); a start through `useJob` on the
 same page makes it look at once. Hand it to `LiveEmpty` (§3a).
 
-There is no chat, runs or activity hook: the OS draws those tabs.
-Activity has no hook either — it is a Postgres table, read server-side
-with `loadActivity` by any domain surface that wants a slice of it (a
-row's history beside the row, say).
+There is no chat or runs hook: the OS draws those tabs. A domain
+surface that wants a slice of the activity (a row's history beside the
+row, say) reads it with `loadActivity`: on the server in a server app,
+or with `useActivity` (`lib/door.js`, §5 Door) from the browser.
 
 ### Commissioning work — `useJob()`
 
@@ -951,14 +1568,212 @@ if (!r.ok) setError(r.error);                  // r.code: needs_answer, queue_fu
 It resolves once the platform took the ask (`{ ok: true, data: {
 request, desk_origin } }`) or refused it; it never waits for the work.
 
+### Calling a model — `llm()`
+
+`llm()` is for one-shot text work on what is on screen: sort these
+mails, draft this reply, translate this note, summarise this thread,
+pull the date out of this line. The answer comes back in the page, and
+the screen does what it likes with it.
+
+**`llm()` for one-shot text work on what the screen holds; `ask()` for
+work that needs tools, the workspace, or more than one step.** Finding
+leads, reading the Wiki, writing rows for forty threads, anything that
+should show in the agent column and the Requests list: that is `ask()`.
+The app's agent does it, with its tools. `llm()` has none: it sees the
+words you hand it and nothing else.
+
+```js
+"use client";
+import { updateRow } from "../lib/actions";
+import { llm } from "../lib/platform";
+
+// Text.
+const r = await llm(thread.body, {
+  system: "Draft a short, warm reply from the founder. Plain text, no greeting.",
+  task: "draft-reply",
+});
+if (r.ok) setDraft(r.text);                    // r.error says why not
+
+// Data: a schema in, an answer checked against it out.
+const SORT = {
+  type: "object",
+  required: ["label", "urgent"],
+  properties: { label: { enum: ["sales", "support", "billing", "other"] }, urgent: { type: "boolean" } },
+};
+const s = await llm(`From: ${mail.from}\nSubject: ${mail.subject}\n\n${mail.body}`, { system: "Sort this mail.", schema: SORT, task: "sort-mail" });
+if (s.ok) await updateRow({ source: "mail", id: mail.id, patch: { label: s.data.label, urgent: s.data.urgent } });
+```
+
+`data` is the model's JSON as it came: **a key your schema does not name
+is kept**. Read the keys you asked for, as above, and do not spread
+`data` into a row.
+
+`llm(input, opts)` takes:
+
+- `input` — what to work on: a string, or a conversation, `[{ role:
+  "user" | "assistant", content }]`: at most 100 messages, none empty,
+  the last one the user's (the one to answer). Required. An empty one
+  asks nothing of the platform and resolves `bad_input`.
+- `system` — how to go about it, at most 8,000 characters.
+- `schema` — a JSON Schema for the answer, an object, at most 16 KB
+  once written out. The answer then comes back as `data`, checked
+  against it, not as `text`. If the model's reply misses, the platform
+  sends it back once with what was wrong; a second miss is
+  `schema_mismatch`. The platform runs your schema on the model's words,
+  so what it may hold is bounded (below).
+- `maxTokens` — the answer's ceiling, a whole number, 1 or more. 1,024
+  unless you say; over 4,096 is cut to 4,096. (It travels as
+  `max_tokens`.)
+- `tier` — `"fast"` (the default) or `"smart"` for the harder job. An
+  app never names a model. `smart` costs more and is slower: a long
+  answer from it can run into the 60 second limit, so keep `maxTokens`
+  modest there.
+- `task` — a short label for the usage line, `a-z`, `0-9` and `-`, at
+  most 40 characters (`"sort-mail"`).
+- `signal` — an `AbortSignal`. An abort resolves `{ ok: false, aborted:
+  true }`.
+
+**What a schema may hold.** Write it out as a tree, small. The call
+refuses a schema with:
+
+- `pattern` or `patternProperties` (`bad_input`): a regular expression
+  run on a model's words can hang the platform. Use `enum`, `format` or
+  length bounds.
+- `$ref`, `$defs` or `definitions` (`bad_input`; `$dynamicRef` and
+  `$recursiveRef` too): each reference is checked in full where it is
+  used, so a few can mean a tree of any size. Write the shape out where
+  it is used.
+- nesting deeper than 20 levels, a list inside a list counted
+  (`bad_input`).
+- more than 1,000 parts (`too_large`): every object in it, every `enum`
+  value and every type listed in a `type` array. A real answer's schema
+  is a few dozen.
+- a schema it cannot read, such as a `type` it does not know
+  (`bad_input`).
+
+A reply with so many values that checking it against the schema would
+cost too much is a miss like any other (`schema_mismatch`, and the
+model is told why): ask for fewer values, or a smaller schema. Make the
+root an object (`type: "object"`): providers' structured answers mostly
+want one, and when one refuses the format the platform asks again in
+words alone, which is less sure. Everything else in JSON Schema is let
+through.
+
+It resolves, and never throws:
+
+- `{ ok: true, text }` — no schema.
+- `{ ok: true, data }` — with a schema.
+- `{ ok: false, error, code, status }` — a refusal, as the platform
+  sent it. Branch on `code`. **Show `error` as it is for the codes that
+  speak to the member, and a plain line of your own for the rest.** The
+  rest speak to you, the developer ("schema uses "pattern""), and a
+  member should not read them.
+
+  Words for the member, shown as they are:
+
+  - `no_credits` (402): the workspace's wallet is empty, the workspace
+    is suspended, or the Free plan's daily limit is used up.
+    `member_cap` (402): the member's monthly spend cap is used up.
+    `app_cap` (402): this app's weekly cap is used up. Say so and stop;
+    do not retry.
+  - `rate_limited` (429): 30 calls a minute per member. Wait a moment,
+    then again.
+  - `model_failed` (502), `try_again` (503) and `failed` (500): the
+    model, the membership check or the platform could not answer just
+    now. Try again.
+  - `timeout` (504): a call is held to 60 seconds, a schema retry
+    included, and one the clock cuts is still charged. Ask for less (a
+    lower `maxTokens`, a shorter input) rather than the same again.
+  - `no_member_identity` (401) and `not_a_member` (403): the page is not
+    running in a member's own session (`no_member_identity` says to open
+    the app from the desk again), or the member was removed from the
+    workspace.
+
+  Words for you, not shown:
+
+  - `bad_input` (400): the call itself is wrong; fix the code.
+  - `too_large` (413): the body is over 128 KB, `system` over 8,000
+    characters, `schema` over 16 KB or 1,000 parts, or `input` over 100
+    messages. Send less.
+  - `schema_mismatch` (422): the model could not fit the schema, twice;
+    `error` names where it missed. Loosen the schema or ask for less.
+  - `cross_origin` (403): not the app's own page (a typed URL, a form
+    post).
+  - `not_configured` (503): the platform has no model to give.
+- `{ ok: false, unavailable: true }` — the platform has no such door (a
+  claw from before it) or there is no network. Render the quiet "not
+  connected yet" of every `_claw` door, or leave the button out.
+
+`useLlm()` is the same call from a component: `{ run, loading, result,
+error, unavailable }`. `run(input, opts)` takes the same arguments and
+resolves the same answer; `result` is that answer when it was ok, `error`
+the refusal's words, and `unavailable` is true on a claw with no door (or
+no network), when `error` stays null: that is the quiet "not connected
+yet", not an alert, as for `useClaw`. A new run aborts the one before it,
+so a slow answer never lands over a newer one, and leaving the page
+aborts the call in flight. `error` is the sentence whatever the code, so
+a screen that must tell the money (`no_credits`, `member_cap`, `app_cap`)
+from the rest reads `code` from what `run()` resolves.
+
+```jsx
+"use client";
+import { Button, Notice } from "../components/ui";
+import { useLlm } from "../lib/hooks";
+
+export default function Translate({ note }) {
+  const { run, loading, result, error, unavailable } = useLlm();
+  if (unavailable) return <p className="text-sm text-muted-foreground">Translation is not connected yet.</p>;
+  return (
+    <div className="grid gap-2">
+      <Button loading={loading} onClick={() => run(`Translate to French:\n${note.text}`, { task: "translate" })}>
+        Translate
+      </Button>
+      {error ? <Notice tone="danger">{error}</Notice> : result ? <p className="text-sm">{result.text}</p> : null}
+    </div>
+  );
+}
+```
+
+What to keep in mind:
+
+- **Browser only, in both modes.** The call rides the member's session:
+  `llm()` and `useLlm()` run in a `"use client"` file. A server
+  component or a server action has no member to charge and cannot call
+  it.
+- **It spends the workspace's credits**, like any inference, and counts
+  against the member's monthly cap and the app's weekly cap. A schema
+  call the model misses is asked again once, and both are charged; so is
+  a call the 60 second clock cuts. Call it on a press, never on every
+  render or every keystroke, and never once per row of a long list: that
+  is a batch, and a batch is `ask()`'s.
+- **The answer is words, not markup.** Render `text` as text. Never put a
+  model's answer in `dangerouslySetInnerHTML`.
+- **The answer is not saved.** What matters goes into a row
+  (`updateRow`, `insertRow`) before the page closes.
+- **No streaming.** The answer arrives whole.
+- **Nothing appears on the desk.** No request, no thread, no run: the
+  agent column and the Requests list are `ask()`'s. The call is metered
+  to the member who made it; the usage line names the app, the tier and
+  the `task` label. Claw does not log the request or the reply.
+- **Never by its path.** A string naming `_claw/llm` fails
+  `npm run check` (§6, `llm`): the two functions are the contract, and
+  they handle what a bare `fetch` would not (a claw without the door, a
+  dropped network, an abort).
+
 ### Activity — the contract
 
-`public.artifact_activity` is how the founder sees the work. The OS's
-**Activity tab** on the app window reads it, newest first — and so can
-any domain surface that wants to (`loadActivity`). Every
-`lib/actions.js` write inserts a row through `logActivity()` in
-`lib/db.js`; the artifact's agent writes the same table with the `sql`
-verb, `by = 'agent'` or `'run:<id>'`.
+`claw_app.activity` is how the founder sees the work. It is the
+platform's view of the workspace's activity table, and it holds only
+this app's lines. The OS's **Activity tab** on the app window reads
+them, newest first — and so can any domain surface that wants to
+(`loadActivity`). In a server app every `lib/actions.js` write inserts a
+line through `logActivity()` in `lib/db.js` (but a `log: false` patch or
+action). In a browser app the door writes it, for every write it takes
+(`lib/door.js`), with the same `log: false`. The app's agent writes the
+same view
+with the `sql` verb, `by = 'agent'` or `'run:<id>'`. A brain write's
+line is the door's: it writes one for every write it takes (`lib/brain.js`
+never logs, and neither does the page).
 
 ```js
 await logActivity({
@@ -971,13 +1786,22 @@ await logActivity({
 });
 ```
 
-Columns: `id, artifact_id, at, action, surface, row_ref, detail, data
-(jsonb), by`. `loadActivity` returns them without `artifact_id` — every
-row is this artifact's. The OS Activity tab shows the surface's label
-on each line and does not link into the app yet; the convention for
-anything that does (a domain surface's own history slice today, the tab
-later) is `surface` + `row_ref` → `/s/<surface>?row=<row_ref>`, so stamp
-both on every line and make the surface honour `?row=`.
+The view fills in `artifact_id` (the app whose role writes the line)
+and `id`, so an insert names neither; one that names another app's id
+is refused. Columns: `id, artifact_id, at, action, surface, row_ref,
+detail, data (jsonb), by`. `loadActivity` returns them without
+`artifact_id` — every line is this app's. The OS Activity tab shows the
+surface's label on each line and does not link into the app yet; the
+convention for anything that does (a domain surface's own history slice
+today, the tab later) is `surface` + `row_ref` → `/s/<surface>?row=<row_ref>`,
+so stamp both on every line and make the surface honour `?row=`.
+
+Up to 0.6.x the lines went into the `artifact_activity` table in
+`public`, named with `CLAW_ARTIFACT_ID`. An app on its own schema can
+reach nothing in `public`, so since 0.7.0 both functions go through the
+view; the lines are the same. Outside Makersclaw there is no view:
+`logActivity` warns and returns false, and `loadActivity` returns the
+database's `error`.
 
 ### Errors
 
@@ -1009,74 +1833,261 @@ ok    controls   every control is a kit part
 ok    examples   examples show only outside a workspace (useFixture); a workspace app opens empty
 ok    manifest   2 surfaces: drafts, sent
 ok    icons      every icon name exists
-ok    kit        70 fixed files match the template
+ok    kit        74 fixed files match the template
 ok    depictions 1 picture of elsewhere, framed on 1 surface: x-post
+ok    agent      no SQL write in app code; the agent's brief names every action with its call (1), every table written (2) and every server action that writes (0)
+ok    tables     its own schema (makersclaw.json): every table named bare, and each bare name one of the 2 its schema makes (../install/schema.sql); claw. and claw_app. are the platform's
+ok    brain      no brain block in makersclaw.json; no lib/brain.js call names a kind
+ok    viewport   nothing in the app sizes itself by the window
+ok    llm        no screen names _claw/llm: a model is called through llm() or useLlm() (README §5)
 ok    smoke      built in 41s · / → 307 · /s/drafts 200 · /s/sent 200 (0.6s)
 all clear
 ```
 
+A browser app's check has one more line, and its smoke serves files:
+
+```
+ok    browser    files and a door: 2 client surfaces; no server code, route, proxy or segment config; env only by the names a page may print
+ok    smoke      built in 38s (copy at ~/.claw-check/app) · export 2.1 MB in 64 files · / → 200 to /s/drafts · /s/drafts 200 · /s/sent 200 (0.1s)
+```
+
 `kit` refuses a fixed file that differs from the template (they are
 hashed in `check/pins.json`) and any file of yours under `components/ui`
-or `components/parts`. `depictions` reads both directions: nothing of
+or `components/parts`. `viewport` refuses anything in your code that
+sizes itself by the window: `min-h-dvh`, `min-h-screen`, `h-screen`,
+`h-dvh` (and their `svh`, `lvh` and `max-h-` kin), and any `vh` unit —
+`h-[80vh]`, `max-h-[60vh]`, `h-[calc(100vh-4rem)]`, `style={{ height:
+"100vh" }}`. The window has one owner, the kit's `AppLayout` (§3b,
+Layouts); a box inside it is bounded by its parent (`h-full`, `flex-1
+min-h-0`) or by a size (`max-h-96`). `depictions` reads both directions: nothing of
 the workspace inside a depiction (a token, `font-sans`, `dark:`, a rem
 utility), nothing of the depiction outside its frame (a named import, a
 picture in the shell or a `Card`, a dead file nobody renders).
 
+`agent` holds the app's agent to what the screens do. Its brief beside
+the app (`../AGENTS.md`, `../references/*.md`) names, in backticks, every
+server action that writes. In an app on its own tables (`"tables":
+"own"`) the screens write through two doors only, so it also refuses:
+
+- SQL that writes in the app's code: `insert into`, `update … set` or
+  `delete from`, in any case, in a string of any `.js`, `.jsx` or `.mjs`
+  but the fixed `lib/`, where it reads as a statement (a `where`, a
+  `values`, a `set col =`, a `;` after it; handed to `query()`; or the
+  whole string). Both modes, brief or none. A one-row write is
+  `insertRow`, `updateRow`, `moveRow`, `deleteRow` or `saveSetting`;
+  anything else is an action (§5). Prose in JSX text and a label in an
+  attribute (`title="Delete from board"`) are not SQL; the same words
+  alone in a string of code are, so word such a label otherwise.
+- The data door by its path: a string naming `_claw/data`,
+  `data/actions/` or `data/tables/`, or `claw("data/…")`. The screens
+  reach the door through its functions, which this rule and the ship
+  can read.
+- An action the brief does not name with its call. For `runAction({
+  name: "close_cycle" })` the brief says `` `close_cycle` `` and `select
+  close_cycle(`, so the agent runs the same function:
+  ```
+  - `close_cycle`: the Close cycle button. Run `select close_cycle($1::jsonb)`
+    with params `[{"cycle": "<id>"}]` (sql execute). It carries the open goals
+    over and refuses a closed cycle. Then log `closed` on `cycles`.
+  ```
+- A table a one-row write names (`source: "deals"`) that the brief does
+  not name in backticks, with the one statement that does the same.
+- Brief or none: a name the code decides at run time (`runAction({ name:
+  kind })`: name it in the code, so the brief can), `runAction("x")`
+  (it takes one object) and a name that is not one bare, lower-case name.
+
+A name or a source is read where it is written: a literal, or a `const`
+string of the same file that the call sees; a surface's `source:
+surface.source` is its entry's in `surfaces.js`. A call counts however
+the file reaches the function: imported, renamed, through `import * as`,
+with `?.(`, or through an app file that re-exports it. A one-row write
+whose table the code decides at run time (a prop) is not checked, and
+the ok line says how many. `node check/run.mjs
+--actions` prints what the screens run and write, `{"actions": […],
+"tables": […]}`, and exits 0: the platform's ship checks that every
+action is a function in the app's schema before it builds. An app with
+no `tables` key keeps the first sentence of this rule only.
+
+`tables` reads every table name in the app's code when `makersclaw.json`
+says `"tables": "own"`: a surface's `source`, the `source` of every
+`lib/actions.js` and `lib/data.js` call (a `const` string of the same
+file counts, where the call sees it), and the name after `from`, `join`,
+`into` and `update` in SQL (not a column's `from`: `extract(epoch from
+t.at)`, `is distinct from`). Your tables are named bare (`deals`): the app's own schema answers
+them, and a second copy of the app lives in another. It refuses
+`public.<t>` (an app on its own schema reaches nothing there),
+`app_<x>.<t>` (a schema by name, even this app's), and `brain.<t>` or
+`brain_api.<t>` (the company brain goes through `lib/brain.js`, §5).
+`claw.` and `claw_app.` are the platform's (`claw_app.activity`, the
+activity view) and pass. An app laid before 0.7.0 has no `tables` key:
+its tables are in `public`, and this rule leaves its names alone.
+`"tables": "moved"` is refused: that is the platform's word for an old
+app whose tables its workspace moved, never a manifest's.
+
+And each bare name must be a table or view the app's own schema makes,
+so none leans on something else. The list is the first found of:
+`CLAW_APP_TABLES` (the platform passes it when it ships the app, read
+from the live schema), `../install/schema.sql` (a play folder's), and
+`../../schema.sql` (a store package's), from their `create table` and
+`create view`. The names read: a surface's `source` in `surfaces.js`
+(a literal or a const), the `source` of a `lib/data.js`, `lib/door.js`
+or `lib/actions.js` call by its name (`loadRows`, `useRows`,
+`insertRow`…, either side of a ternary), and in SQL — strings joined
+with `+` read as one, handed to `query()` or starting as a statement —
+the name after `from` (and after its commas), `join`, `insert into`,
+`update … set`, a delete's or merge's `using`, and `table`, `truncate`
+or `copy`. A CTE, a function (`from unnest(…)`), a SQL string or
+comment and `pg_*` are not tables. Not read: a call through an import
+alias, options held in a variable (`loadRows(opts)`), SQL a helper takes
+that does not start as a statement, and SQL built at run time. With no
+list here, the ok line says "no table list here". The same SQL is read
+for `public.`, `app_<x>.` and `brain.` names that only it shows: after a
+comma, in a `using`, with spaces around the dot.
+
+`brain` reads the `brain` block of `makersclaw.json` (§5) and every
+call of `lib/brain.js` or `lib/brain-server.js` whose kind is written in
+the code (`kind: "contact"`, or a `const` string the call sees).
+The block's `kinds`, `reads`, `writes` and `links` are arrays, and each
+kind has `kind`, `label`, `plural` and `fields`. A read's kind
+(`listRecords`, `countRecords`, `brainLists`; the `kinds` of
+`searchBrain` and `brainChanges`) is in `reads` or `writes`. A write's
+(`writeRecord`, each entry of `writeRecords`, `createList`) is in
+`writes`. A kind that only `kinds` defines is refused too: the door
+hands the app only what `reads` and `writes` name. A kind held in a
+variable is not read here; the door refuses it on the member's screen.
+
+`llm` reads every app, in both modes: no string in the code names
+`_claw/llm`, and none handed to `claw()`, `clawUrl()` or `clawStream()`
+starts `llm`. A model is called with `llm()` or `useLlm()` (§5, Calling a
+model), which handle a claw without the door, a dropped network and an
+abort; a `fetch` of the path handles none of them. The path is read as
+a browser reads it (`claw("//llm")`, `claw("./llm")` and `"/_claw/./llm"`
+are the door too). A path built from pieces or held in a variable is not
+read here, as for rule 8. A longer name (`_claw/llm-notes`) is another
+route, and a comment or text in JSX is not a string of code.
+
+`browser` reads a browser app only (`"mode": "browser"`): its pages are
+files built once, and everything they read or write goes through the
+platform's data door. So it refuses, file and line, a `"use server"`
+module or function; an import of `next/headers`, `next/cache`,
+`next/server`, `pg`, `lib/db` or `lib/brain-server`; a `route.js` under
+`app/`; a `proxy.js` or `middleware.js` at the root (under export Next
+ignores it); an export of `dynamic`, `revalidate`, `fetchCache`,
+`runtime` or `dynamicParams`; a surface whose first line is not `"use
+client"`; and a `process.env` name other than `CLAW_BASE_PATH`,
+`CLAW_PRODUCT`, `NEXT_PUBLIC_*` and `NODE_ENV` — a prerendered page
+prints what it reads into a file anyone who opens the app can fetch.
+
 The smoke test starts that build on a loopback port and loads every
-surface; `--static` skips the build and the smoke. Then, by eye:
+surface; `--no-build` skips the build and the smoke. A browser app's smoke
+builds in a copy of the app (`~/.claw-check/<app>`), never in it, with
+no `.env`; serves the export by the platform's rules; and checks that
+`/` forwards to a surface and every `/s/<key>` answers 200 with no error
+page. That proves every page prerenders, not that a surface renders
+with data: the rows come in the browser. Then, by eye:
 
 - Renders at 360px, 768px and 1280px without horizontal scroll.
+- The page itself never scrolls: the shell is the window's height
+  (`AppLayout`), and each pane scrolls inside it. With the longest
+  content a surface can hold (a 30-page article, a 40-message thread,
+  a tall inspector), the last line and every button after it are
+  reachable, at 375px and at 1280px; the header and the footer stay in
+  view.
 - In a workspace, an empty table shows `LiveEmpty`: the work in flight,
   else what would be here and the manual way to add it — never an
   example (§3a). A saved row replaces it.
 - Error state shows the text from `{ error }`.
 - Keyboard focus visible on every control.
 - Numbers tabular (`data-nums`).
-- Every write is a server action — `lib/actions.js`, or the app's own
-  `"use server"` file (§5) — never raw SQL in a surface.
+- Every write goes through `lib/actions.js` (a one-row write or
+  `runAction`), or in a server app the app's own `"use server"` file
+  (§5) — never raw SQL in a surface.
 - Every surface reachable from the nav.
 
 ## 7. Run
 
 1. `makersclaw init` laid this into the artifact's `app/` (in Makersclaw,
-   `artifact_scaffold {dir}` runs it and makes `public.artifact_activity`
-   in the workspace database). `makersclaw.json` records the version and
-   the blocks; `makersclaw update` moves the fixed files and blocks to a
-   newer version and never touches your own files. `pnpm-lock.yaml` is
-   cut from the lock this version ships (by init, add and update), so
-   every app on the version installs the same packages;
-   `makersclaw install` installs from it. Never edit it by hand.
-2. `app_database {name, dir}` → `DATABASE_URL` in `.env`. The app's role
-   reads and writes every table in `public`.
-3. Make the domain tables with the `sql` verb (they land in `public`).
+   `artifact_scaffold {dir}` runs it). `makersclaw.json` records the
+   version, the blocks, where the tables live (`"tables"`, from
+   `init --tables`; §5, Your tables) and the mode (`"mode"`, from `init
+   --mode`; §2). `makersclaw update` moves the fixed files and blocks
+   to a newer version; it never touches your own files, and keeps every
+   other key of `makersclaw.json` (`tables`, `mode`, `brain`). Only
+   `makersclaw mode` changes the mode (§4). `pnpm-lock.yaml` is cut from the lock this version ships
+   (by init, add and update), so every app on the version installs the
+   same packages; `makersclaw install` installs from it. Never edit it
+   by hand.
+2. `app_database {name, dir}` gives the app its own schema and role.
+   A server app gets `DATABASE_URL` in its environment; a browser app
+   gets none, since its pages reach the tables through the door and its
+   agent through `sql`. The role reads and writes the app's own tables,
+   by bare name. The platform lays the activity door,
+   `claw_app.activity`, with the database (§5, Activity); the app makes
+   no activity table of its own.
+3. Make the domain tables with the `sql` verb, bare
+   (`create table if not exists deals (…)`): they land in the app's own
+   schema. An app's first tables are often there before its first
+   build, made by the chat that created it (`artifact_manage
+   install_tables`): read them with `sql schema` first. An app from
+   before 0.7.0 makes them in `public`, with the same bare names.
 4. `product_run` with this directory. While building, run it as a dev
    server — `command "npx next dev -H 127.0.0.1"`, `build ""` — so each
    edit shows in the founder's live preview without a rebuild.
    `product_run` sets `CLAW_BASE_PATH`, `CLAW_PRODUCT`,
    `CLAW_PRODUCT_TOKEN` and `CLAW_ARTIFACT_ID` — the last is what turns
-   examples off (§3a).
+   examples off (§3a). A browser app previews the same way, on `next
+   dev`; its surfaces read through the door there too.
+5. `npm run check` (§6) before `surface_built` and before launch. For a
+   browser app its smoke builds the export as the platform will: in a
+   copy of the app (`~/.claw-check/<app>`), never in it; with no `.env`;
+   served by the platform's rules. It proves every page prerenders and
+   `/` forwards to a surface, not that a surface renders with data: look
+   at the preview for that.
 
 Every `artifact_files` write under `app/` comes back with the console's
 state; a 5xx carries the log tail. Fix it before moving on — the founder
 is watching the preview.
 
-Every page is `dynamic = "force-dynamic"`: nothing is prerendered, so a
-build never needs the database. `app/auto-refresh.jsx` re-renders the
-page from the server while it is shown, so the agent's writes appear:
-one refresh at a time, 5 s after the last one landed plus what that one
-took (a minute at most), and only while the App tab is on screen in a
-visible browser tab (hidden, it asks nothing; back, it refreshes at
-once), nobody is typing (never while a sheet is open, a field they typed
-in holds focus, or within 10 s of a keystroke), and the app answers
-`/claw-alive` (a fixed route) with a 204.
+In a server app every page is `dynamic = "force-dynamic"`: nothing is
+prerendered, so a build never needs the database.
+
+A browser app's pages are the opposite: `next build` prerenders each once
+(`output: "export"`), `/` as a page that forwards to the home surface
+(a script keeping the query, and a meta refresh) and
+`/s/<key>` as one file per surface, whose surface renders in the browser
+inside `<Suspense>`. Its theme is set by a script in `<head>` before the
+page paints: `?theme=`, then the `claw_theme` cookie, then dark. The
+platform builds it with `CLAW_BASE_PATH`, `CLAW_PRODUCT` and
+`CLAW_ARTIFACT_ID` and nothing else of the app's environment, and
+serves the files it leaves; no code of the app's runs on the workspace's
+machine.
+
+`app/auto-refresh.jsx` re-renders the page from the server while it is
+shown, so the agent's writes appear: one refresh at a time, 5 s after
+the last one landed plus what that one took (a minute at most), and only
+while the App tab is on screen in a visible browser tab (hidden, it asks
+nothing; back, it refreshes at once), nobody is typing (never while a
+sheet is open, a field they typed in holds focus, or within 10 s of a
+keystroke), and the app answers `/claw-alive` (a fixed route) with a
+204.
+
+A browser app's `app/auto-refresh.jsx` keeps every one of those rules,
+but a tick does not re-render anything from a server. It asks the data
+door what changed (`_claw/data/changes`: the brain's changes in the
+app's kinds, and a stamp of the app's own tables), and only when
+something did, every hook on the page (`useRows` and the rest, the
+brain's too) reads again. A brain change shows on the next tick. A
+write the agent or a job makes to the app's own tables shows within
+about 11 s: the stamp comes from Postgres's counters, which lag.
 
 **A surface that must not be refreshed opts out with
 `data-claw-refresh="off"` on its root element**: one whose rows only its
 own writes change, or a table too big to send every few seconds. While
 any element on the page carries it, nothing is refreshed and nothing is
 probed; the surface's own writes still re-render it (`lib/actions.js`
-revalidates), and so does every navigation. Set it from state to pause
-only while it matters: `data-claw-refresh={importing ? "off" : undefined}`.
+revalidates; in a browser app every write reads the hooks again), and so
+does every navigation. Set it from state to pause only while it matters:
+`data-claw-refresh={importing ? "off" : undefined}`.
 
 **A page left open stops refreshing after 30 minutes with no sign of
 anyone** in the app — a key, the pointer, a touch, a wheel, focus. The