makersclaw 0.5.2 → 0.7.0

package/templates/next/files/README.md

@@ -1,11 +1,12 @@
 # artifact template
 
-The app every artifact starts from: Next.js 15 (app router, JSX, server
-actions), Postgres via `DATABASE_URL`, Tailwind v4, and a kit of parts
+The app every artifact starts from: Next.js 16 (app router, JSX, server
+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.
+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,6 +49,14 @@ 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:
 
 ```
@@ -56,7 +65,7 @@ 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)
 ```
 
@@ -72,14 +81,56 @@ app/escape-relay.jsx, app/frame.js, app/claw-alive/route.js   the app inside its
 components/ui/         the kit: 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)
-middleware.js          product-token check, x-claw-surface and x-claw-theme headers
-next.config.mjs        basePath + Server Actions allowedOrigins, both from env (§4b)
+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);
+                       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, 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:
@@ -168,7 +219,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.
@@ -494,7 +547,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 +560,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 +658,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 +680,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 +697,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,9 +735,14 @@ 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 15 refuses a Server Action whose `Origin` header disagrees with
+Next refuses a Server Action whose `Origin` header disagrees with
 `x-forwarded-host`, and in this stack they always disagree: the sandbox
 ingress rewrites `x-forwarded-host` to its own vercel.run name while the
 browser is on the product host. Untreated, the app builds, loads and
@@ -620,7 +752,9 @@ button rather than a proxy policy.
 `next.config.mjs` already reads `CLAW_ALLOWED_ORIGINS`, which `product_run`
 derives per environment (`src/lib/products.ts`, `productAllowedOrigins`):
 the product's own FQDN in production, the dashboard's dev origin under a
-path prefix.
+path prefix. The same hosts are the dev server's `allowedDevOrigins`:
+Next 16's `next dev` refuses its own resources (the HMR socket, the error
+overlay) to any other host, and says "Blocked cross-origin request".
 
 **Never hardcode an origin here.** `allowedOrigins: ["localhost:5173"]`
 passes every test you can run in development and refuses every write in
@@ -629,53 +763,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 `{ 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).
+`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
+```
+
+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 (middleware 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`.
@@ -690,19 +976,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)
 
@@ -789,10 +1344,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,12 +1506,18 @@ request, desk_origin } }`) or refused it; it never waits for the work.
 
 ### 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({
@@ -969,13 +1530,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
 
@@ -996,9 +1566,9 @@ files has to). The platform agent reads them as console events. Call
 line per rule, under twenty lines, exit 1 on a failure that names the
 file and line and what to use instead. It builds for itself, into
 `.next-check`, and only when a source changed since the last check —
-never run `npm run build` first, and never build into `.next`: the dev
-server product_run started owns that folder as another user, and a
-second build there dies with `EACCES: .next/trace`.
+never run `npm run build` first, and never build into `.next`: it is not
+the check's folder. In a working copy the preview's dev server owns it;
+in a live app it holds the build the platform made and serves.
 
 ```
 check: 5 files · 2 surfaces
@@ -1009,10 +1579,20 @@ ok    manifest   2 surfaces: drafts, sent
 ok    icons      every icon name exists
 ok    kit        70 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    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
@@ -1020,8 +1600,117 @@ 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.
+
+`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.
 - In a workspace, an empty table shows `LiveEmpty`: the work in flight,
@@ -1030,48 +1719,95 @@ surface; `--static` skips the build and the smoke. Then, by eye:
 - 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.
-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