makersclaw 0.1.0

package/templates/next/files/README.md

@@ -0,0 +1,626 @@
+# 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
+(`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
+
+The app renders in an iframe inside an OS window on the founder's desk.
+The window's title bar already carries the app's name, **Edit**,
+**Pause / Resume**, **Run now** and the status. Under it, the window's
+tab strip carries **App**, **Agent**, **Runs**, **Activity** and
+**Settings**: the OS draws the last four (the chat with the app's
+agent, each run and its report, every activity line, the app's settings).
+You design the **App tab**: the shell and the domain surfaces. Never
+repeat the name, the run controls, or the other tabs.
+
+**The colours are the workspace's, not yours.** The founder picks a
+theme once (System Settings → Appearance) and the desk and every app in
+the workspace are painted in it. `app/layout.jsx` links
+`_claw/theme.css`, which sets the palette's variables; `app/globals.css`
+turns them into the tokens you use: `bg-background`, `bg-card`,
+`text-foreground`, `text-muted-foreground`, `text-primary`,
+`bg-primary text-primary-foreground`, `border-border`, `bg-accent`,
+`text-destructive`, `text-success`, `text-warning`, `text-info`,
+`ring-ring`, `rounded-sm|md|lg|xl`, `font-sans|mono|display`. Never a
+hex, `rgb()`, `hsl()`, a raw Tailwind hue (`text-neutral-500`,
+`bg-white`) or a `<style jsx>` block: `npm run check` refuses each, and
+an app that carries its own colour stops matching the workspace the day
+the founder changes theme. Light or dark is a property of the preset;
+the tokens flip with it, so you write no `dark:` variants either.
+
+One exception, with rules of its own (§3c): a **depiction** — a picture
+of something that exists elsewhere, a tweet as X will show it, a
+LinkedIn post in the feed — wears THAT place's colours, face and widths,
+in `components/depictions/`, framed on a surface by the kit's
+`<Depiction>`. Colour that is a row's value (`style={{ background:
+row.hex }}`) is neither chrome nor depiction: it is data, and the check
+never sees it.
+
+## 2. Files
+
+Paths here are relative to this folder — the artifact's `app/`.
+`artifact_files` paths are relative to the artifact folder, so prefix
+`app/`: this file's `app/shell.jsx` is written as `app/app/shell.jsx`,
+`surfaces/<key>.jsx` as `app/surfaces/<key>.jsx`.
+
+Yours — write and rewrite freely:
+
+```
+app/shell.jsx          the inside of the window: nav, layout, type, density
+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/depictions/ pictures of things that exist elsewhere, in their own colours (§3c)
+```
+
+Keep — the contract; do not edit:
+
+```
+app/layout.jsx         <html data-theme>, the _claw/theme.css link, AutoRefresh, ErrorRelay, Shell
+app/globals.css        the workspace theme's tokens (§1) — no palette of your own goes here
+app/page.jsx           / → the home surface (or "No surfaces yet" while the manifest is empty)
+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
+components/ui/         the kit: Button, Field, Input, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction… (§3b, §3c)
+components/parts/      the parts: RecordSwitcher, useFixture + FixtureNotice (§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)
+postcss.config.mjs     Tailwind v4
+schema.sql             public.artifact_activity, for reference
+```
+
+## 3. Design first
+
+Before any code, write `app/DESIGN.md` — one screen of text:
+
+- The founder's design rules from the workspace file `/company/design.md`,
+  quoted. Read it before every build; if it is absent, write it from this
+  first build.
+- Which tokens carry which job on THIS app — what is `bg-card`, where
+  `text-primary` appears, what `text-destructive` is reserved for. Not a
+  palette: the colours are the workspace's (§1). Colour is a signal, so
+  status tones (success, warning, destructive, info) are for status only.
+- Depictions: `<thing> (modes)` or `none` — which pictures of elsewhere
+  the app shows (§3c), and in which of the target's modes.
+- 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.
+- Density, empty states, error states.
+- What makes this app look like ITS domain and not another.
+
+Then `app/shell.jsx`, then the surfaces in the order the founder uses
+them. Every one is a domain surface — the things the app finds, makes,
+sends or receives. There is no agent, runs, activity or settings surface
+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.
+
+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
+work going and watch it happen (`useJob`, §5). A verb on an object list —
+"Generate a launch plan" beside "New launch plan" — is part of the App
+tab, and so is the panel it opens while the work runs.
+
+**The rule: no two apps in a workspace should be mistaken for each other
+at a glance.** The design comes from the domain, not from a default. The
+colours are the same across the workspace by design; what tells the apps
+apart is the shape of each surface — which is your work.
+
+### 3b. Parts — assemble, never hand-roll
+
+Every control in the app is a part from `components/ui`; the pieces that
+touch this template's data are in `components/parts`. Each is the
+workspace's look over the browser's own behaviour (a `<dialog>` for the
+sheet, the Popover API for the menu, the native `<select>`, roving tabs)
+— which is why they work on first contact and why a hand-rolled one
+rarely does. `npm run check` refuses a raw `<select>`, `<dialog>`,
+`<svg>`, `role="tab"`, `popover` or `window.confirm()` outside the kit.
+
+```jsx
+import { Button, IconButton, Card, Field, Input, Textarea, Select, Switch, Checkbox,
+         Sheet, Confirm, Tabs, TabPanel, Menu, Notice, Badge, Kicker, Empty, Icon, cx }
+  from "../components/ui";           // "./ui" from a component
+import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../components/parts";
+```
+
+- `Button` — `variant` primary (one per surface) · secondary · quiet ·
+  danger · link; `size` md (44px) · sm; `icon="plus"`; `href` for a link.
+  `IconButton` for an icon alone (`label` required).
+- `Field` wraps `Input`, `Textarea`, `Select`, `Switch`, `Checkbox` with
+  its label, hint and error. `Select` with empty `options` renders a
+  muted line, never a disabled dropdown.
+- `Sheet` — the one overlay, a rail beside the work (`side="end"`), a
+  dialog (`center`) or a bottom sheet; on a narrow window every side
+  becomes a bottom sheet. `Confirm` is the "delete this?" case.
+- `Tabs` + `TabPanel` — views of ONE thing (a record's notes | history).
+  Never for the app's surfaces; those are the shell's nav.
+- `Menu` — the "…" of a row. Empty `items` render nothing: a menu is
+  earned by having actions.
+- `Card`, `Notice` (tone neutral · info · success · warning · danger),
+  `Badge`, `Kicker` (the small line above a heading), `Empty` (a filter
+  or search with no matches — not the landing state, that is the fixture).
+- `Icon name="…"` — one sprite, `ICON_NAMES` lists it. Missing one? Add
+  the glyph to `components/ui/icon.jsx`; never an `<svg>` in a surface.
+- `RecordSwitcher` — pick a saved record or make a new one. With nothing
+  saved it shows only New. A disabled dropdown reading "No saved…" is the
+  failure this part exists to prevent.
+- `useFixture(rows, SAMPLE)` → `{ rows, isFixture, clear }` +
+  `FixtureNotice` — the worked example (§3: it opens populated), shown
+  only while the real collection is empty and **never INSERTed**. The
+  workspace database is shared by every app; an invented row is a real
+  row somewhere else. Clearing writes nothing. Editing a fixture row
+  copies its values into a new draft and saves THAT.
+
+A control with nothing to act on is not drawn.
+
+**Blocks — the bigger pieces, added when a surface needs one.** A board
+you drag cards across, the panel that follows a job the agent is doing:
+behaviour that goes wrong when every app draws it by hand. No app has a
+block until it is added — `makersclaw search <what the surface does>`
+finds one, `makersclaw add <name>` lays it in `components/blocks/<name>/`
+and prints its props and an example (in Makersclaw, the `template` tool
+runs both). Import it from there:
+
+```jsx
+import { Board } from "../components/blocks/board";   // "./blocks/board" from a component
+```
+
+A block is fixed like the kit: compose it through its props — what a card
+says, what a move saves — never edit its files (`npm run check` refuses
+a change; `makersclaw add <name>` restores one). Search before you build
+a board, a table, a timeline, a calendar, a canvas or a job panel by
+hand. When no block fits, build the part from the kit in `components/`,
+with tokens only — except a depiction, §3c.
+
+### 3c. Depictions — the one place colour is yours to copy
+
+A depiction is a picture of something that exists elsewhere: a tweet as
+X will show it, a LinkedIn post in the feed, the row an email makes in
+Gmail's inbox, a Slack message, a receipt. Its whole job is *this is how
+it will look there*, so it is painted in that place's colours, set in
+that place's face, at that place's width — and it does not move when the
+founder changes theme. The test, per element: **will the founder send,
+post, paste or print THIS and see it there?** Then it is a depiction. Do
+they type into it, save from it, switch records in it, or does it change
+what is stored? Then it is chrome, and it is the workspace's. X's
+composer is not a depiction; the founder is the one typing. Not a
+depiction either: a chart, a code block, a status, a pin on a map, the
+founder's own brand on your buttons, a colour a user picks for a tag, a
+Slack mark on a "Post to Slack" button. Those stay tokens. A published
+thing is an embed (`<iframe>` of the real post), not a depiction.
+
+**The file.** `components/depictions/<thing>.jsx` — one thing as it looks
+in one place, one default export, `"use client"` if it holds the target's
+own toggle. It opens with a header comment: the target, the date you
+traced it, its column widths in px, its named modes, then `Exact:`
+(colours, sizes, radii, widths, where the text folds) and `Approximate:`
+(the face when it is proprietary — X's Chirp, Google Sans — and the emoji
+set). A depiction without that header is a guess, not a picture.
+
+Inside it, everything is the target's and everything is px: `text-[15px]
+p-[12px] rounded-[16px]`, `style={{ color: "#536471" }}`, its own `<svg>`
+glyphs (the X mark, the verified badge — the kit's stroke icons do not
+look like X's). Never `text-sm`, `p-4`, `rounded-lg` or `font-sans`: rem
+is the workspace's base size, `--spacing` carries the founder's density,
+`rounded-lg` is the preset's radius, and no wrapper can undo them — the
+check refuses each. Never a token, never `dark:`: the target's own modes
+(X: default, dim, lights out) are a `mode` prop and a table in the file,
+and have nothing to do with the workspace being light or dark. The root
+paints the target's page colour and its outer padding; the card sits
+inside. A white tweet floating on the workspace's charcoal is not how it
+will look there.
+
+It takes data in and nothing else: text, name, handle, avatar url, counts,
+`mode`. It imports `react`, `../ui/cx` and its siblings — never `../ui`,
+`../parts` or `lib/`. No `<form>`, no `<input>`, no `<a>` (a link there is
+a `<span>` that looks like one), no handler except the target's own
+toggle written in place (`onClick={() => setOpen(true)}` for LinkedIn's
+"…more"), no reads, no writes. When an automation will post the thing,
+the depiction renders the same text the automation sends, so preview and
+post cannot drift.
+
+**The frame.** On the surface — or in the client component that holds the
+draft, where a preview can follow typing (`components/<X>.jsx`, importing
+`Depiction` from `"./ui"`) — always this shape:
+
+```jsx
+import { Depiction, Tabs } from "../components/ui";
+import XPost from "../components/depictions/x-post";
+
+<Depiction of="x-post" scheme="dark" width={600} label="On X · Dim (face approximate)">
+  <XPost text={draft.text} name={me.name} handle={me.handle} avatar={me.avatar} mode="dim" />
+</Depiction>
+```
+
+Exactly one depiction inside the frame, self-closing. `of` names the
+file; `scheme` is the target's light or dark (never the workspace's);
+`width` is the target's real column, from the header comment — the frame
+scales the picture to fit a narrow column and never reflows it, because
+line breaks and folds are the preview. The caption is chrome. Two modes
+side by side are two frames. The composer, the record switcher, the mode
+and device toggles, Save — chrome, in tokens, outside. A depiction is a
+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
+`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
+the frame go data props only — a string, a number, a field of a row;
+never an element, an object, an array, a function or a spread, whatever
+the prop is called. The check reads every `.js`/`.jsx` the app has,
+dot-files included; Tailwind reads exactly those files (`globals.css`
+pins its sources), so a class name in a `.json` or built from pieces
+never reaches the page.
+
+## 4. Server and client
+
+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)
+surfaces.js                  server files only (entries import components)
+```
+
+Pass plain data across the boundary — strings, numbers, arrays, objects.
+`plain(row)` already turns dates into ISO strings. A client component can
+receive a server action as a prop, and nothing else that is a function.
+
+A surface file that uses hooks or event handlers starts with `"use
+client"` and cannot import `lib/data.js`. Split it: a server file loads
+the rows and renders a client component with props.
+
+```jsx
+// surfaces/investors.jsx (server)
+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" });
+  return <InvestorBoard rows={rows} error={error} highlight={searchParams.row ?? null} />;
+}
+```
+
+```jsx
+// components/InvestorBoard.jsx (client)
+"use client";
+import { moveRow } from "../lib/actions";
+import { Card, Notice } from "./ui";
+import { FixtureNotice, useFixture } from "./parts";
+
+const SAMPLE = [{ name: "Ada Ventures", stage: "warm" }, /* … */];
+
+export default function InvestorBoard({ rows: real, error, highlight }) {
+  const { rows, isFixture, clear } = useFixture(real, SAMPLE);
+  /* … */
+}
+```
+
+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).
+
+### Linking — `next/link`, never a bare `<a href="/…">`
+
+The app is served under a prefix (`/p/<label>` in local dev, nothing in
+production) and `next.config.mjs` puts it in `basePath`. **`<Link>` and
+`router.push()` apply that prefix. A plain `<a href>` does not** — the
+browser resolves it against the ORIGIN, so the click leaves the app
+entirely and loads the Makersclaw dashboard inside the app's own frame.
+
+```jsx
+import Link from "next/link";
+<Link href={`/s/${key}`}>Goals</Link>     // ✅ becomes /p/<label>/s/goals
+<a href={`/s/${key}`}>Goals</a>           // ❌ goes to /s/goals on the dashboard
+```
+
+Assets hide the mistake: Next writes those itself, so `_next/static/…`
+comes out correctly prefixed while the nav is broken, and the page still
+answers 200. Nothing in the build catches it — only a click does. A write
+under `app/` that contains a root-relative `<a>` comes back with a
+`warnings` entry saying so.
+
+Same trap, same fix: `window.location` assignments and `<form
+action="/…">`. A real external URL (`https://`, `mailto:`) is fine.
+
+
+### 4b. Writes are rejected — "Invalid Server Actions request"
+
+Already handled. Do not fix it in `next.config.mjs`.
+
+Next 15 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
+renders perfectly — and its **first save fails**, which reads like a dead
+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.
+
+**Never hardcode an origin here.** `allowedOrigins: ["localhost:5173"]`
+passes every test you can run in development and refuses every write in
+production. If a write is still rejected, the value is wrong at the
+source — say so and stop; it is not an app-level fix.
+
+## 5. API reference
+
+### Reads — `lib/data.js` (server)
+
+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()`.
+
+```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
+```
+
+`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).
+
+```js
+const { rows, error } = await loadRows({ source: "public.drafts", filter: { stage: ["draft", "approved"] } });
+const { counts } = await countBy({ source: "public.investors", column: "stage" });
+const { rows: log } = await loadActivity({ surface: "drafts", limit: 50 });
+```
+
+Helpers: `plain(row)` (dates → ISO, buffers → base64), `orderClause(orderBy,
+fallback)` (validated `ORDER BY` 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>`).
+
+```js
+updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data })
+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 })
+```
+
+`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`.
+
+```js
+"use client";
+import { moveRow } from "../lib/actions";
+const r = await moveRow({ source: "public.investors", id, stateColumn: "stage", to: "sent" });
+if (!r.ok) setError(r.error);
+```
+
+Never write raw SQL from a surface. A write that needs more than these
+is a new function in `lib/actions.js` that also calls `logActivity`.
+
+### Platform — `lib/platform.js` (browser)
+
+Typed wrappers over `lib/claw.js`, one per `_claw` route an app has a
+reason to call. Every call resolves `{ ok, status, data }` or `{ ok:
+false, status, error, unavailable }`; nothing throws. `unavailable: true`
+(404 or no network) means the gateway has no such route yet: show a
+quiet "not connected yet", not an error.
+
+```js
+import { platform } from "../lib/platform";   // or the named functions
+platform.me()                                          GET  _claw/me     → { artifact: { id, name, vehicle, status, home }, user: { id, email }, blueprint }
+platform.startJob(message, { sessionId, onEvent })     POST _claw/chat    → streams session · delta · tool · done · error
+platform.cancelJob(sessionId)                          POST _claw/cancel
+platform.reportError({ message, stack, url, source })  POST _claw/events
+```
+
+Named exports: `me, 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`. Starting work
+is the opposite thing, and it belongs here (see `useJob`). The artifact's
+status lives on `<html data-claw-status>` (`publishStatus` in
+`lib/claw.js`); `useArtifact()` keeps it current.
+
+### Hooks — `lib/hooks.js` ("use client")
+
+Three hooks: a generic fetch over one `_claw` route, the app's identity,
+and a job. 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.
+
+```js
+useClaw(path, { every, enabled = true })  → { data, error, loading, unavailable, reload }
+useArtifact()                              → { artifact, user, blueprint, loading, error, unavailable, reload }
+useJob()                                   → { running, steps, text, progress, error, sessionId, finishedAt, start, cancel, reset }
+```
+
+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).
+
+### Commissioning work — `useJob()`
+
+The founder asks the app's agent to make something, from inside the app,
+and watches it happen. This is SOP §2.3 and the reason it exists is
+blunt: with invocation only on the window's Agent tab, a founder starts
+work and then stares at an app where nothing changes.
+
+```jsx
+const job = useJob();
+const products = useProducts();                 // your own data hook
+
+useEffect(() => { products.reload(); }, [job.progress]);   // rows as they land
+
+<button onClick={() => job.start("Draft a launch checklist for Rowhouse")}>
+  Generate a launch plan
+</button>
+
+{job.running || job.finishedAt ? (
+  <aside>                                       {/* your design, not ours */}
+    {job.steps.map((s, i) => <li key={i} data-status={s.status}>{s.label}</li>)}
+    <p>{job.text}</p>
+    {job.running ? <button onClick={job.cancel}>Stop</button>
+                 : <button onClick={job.reset}>Close</button>}
+  </aside>
+) : null}
+```
+
+The panel is a block — `makersclaw add job-panel` — that keeps the four
+rules below for you: `<JobPanel job={job} title="Drafting the launch
+plan" doneTitle="Launch plan drafted" />`. Draw your own only when it
+cannot say what the founder needs to see.
+
+Four rules, and a build is wrong without them:
+
+1. **The verb sits on the object list, beside the manual one.** "Generate
+   a launch plan" next to "New launch plan", on the Launches surface.
+   Never a nav item named after the agent, and never the only way to
+   create that object — the manual form has to exist too.
+2. **The panel does not exist when no job is running.** Mount it from
+   `job.running || job.finishedAt`; `job.reset()` closes it. A panel
+   that is always there is the monitoring console (§2.7).
+3. **`job.text` is not the deliverable.** It is the agent's account of
+   what it did. The deliverable is ROWS — that is why `job.progress`
+   reloads your data hook, and why the panel closing leaves a fuller
+   list behind it.
+4. **Show `step.label`, never `step.name`.** `label` is the founder's
+   phrase ("Searching the web"); `name` is `web_search`.
+
+`job.sessionId` is the thread. Keep it on the row the job produced and
+pass it back as `job.start(msg, { sessionId })` to refine that one thing
+where it lives — one conversation per object, never a global chat.
+
+### 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>'`.
+
+```js
+await logActivity({
+  action: "drafted",          // found, drafted, sent, replied, skipped, edited, moved, added, removed…
+  surface: "drafts",          // surface key → /s/drafts?row=<row_ref>
+  row_ref: String(row.id),    // the id in that surface's source table
+  detail: "Drafted intro to Weekend Fund",
+  data: { to: "ryan@weekend.fund" },
+  by: "user:founder@x.com",   // 'agent' | 'user:<email>' | 'run:<id>'
+});
+```
+
+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=`.
+
+### Errors
+
+`app/error.jsx` catches a surface that throws while rendering, shows the
+message inside the shell, and posts it to `_claw/events`.
+`app/global-error.jsx` does the same for the layout. `app/error-relay.jsx`
+posts `window.onerror` and `unhandledrejection`. All three go through
+`reportError({ message, stack, url, source })` in `lib/claw.js`, deduped
+and capped per page load; `source` is `"preview"` while the artifact is a
+draft and `"runtime"` once launched (`app/error-relay.jsx` keeps the
+status on `<html data-claw-status>` from `_claw/me`; nothing in your
+files has to). The platform agent reads them as console events. Call
+`reportError` yourself only for a failure the boundaries cannot see.
+
+## 6. Acceptance
+
+`npm run check` — before `surface_built`, and again before launch. One
+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`.
+
+```
+check: 5 files · 2 surfaces
+ok    colours    no colour outside the workspace theme (1 depiction excepted)
+ok    controls   every control is a kit part
+ok    examples   fixtures stay in code (useFixture), nothing INSERTs one
+ok    manifest   2 surfaces: drafts, sent
+ok    icons      every icon name exists
+ok    kit        33 fixed files match the template
+ok    depictions 1 picture of elsewhere, framed on 1 surface: x-post
+ok    smoke      built in 41s · / → 307 · /s/drafts 200 · /s/sent 200 (0.6s)
+all clear
+```
+
+`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
+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).
+
+The smoke test starts that build on a loopback port and loads every
+surface; `--static` skips the build and the smoke. Then, by eye:
+
+- Renders at 360px, 768px and 1280px without horizontal scroll.
+- The fixture shows while the table is empty; a saved row replaces it.
+- Error state shows the text from `{ error }`.
+- Keyboard focus visible on every control.
+- Numbers tabular (`data-nums`).
+- Every write goes through `lib/actions.js`; no raw SQL from 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`).
+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`.
+
+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 from
+the server every 5 s while the tab is visible, so the agent's writes
+appear. The founder reads "artifact", "app", "agent", "automation" —
+nothing else.

package/templates/next/files/app/auto-refresh.jsx

@@ -0,0 +1,26 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+
+// Rows change under this page from outside it — the agent writes them
+// while the founder watches. Re-render from the server every 5 s while the
+// tab is visible; router.refresh() keeps form state and scroll, a reload
+// would not. Nothing runs while the tab is hidden.
+const EVERY_MS = 5000;
+
+export default function AutoRefresh() {
+  const router = useRouter();
+  useEffect(() => {
+    const tick = () => {
+      if (document.visibilityState === "visible") router.refresh();
+    };
+    const id = setInterval(tick, EVERY_MS);
+    document.addEventListener("visibilitychange", tick);
+    return () => {
+      clearInterval(id);
+      document.removeEventListener("visibilitychange", tick);
+    };
+  }, [router]);
+  return null;
+}