makersclaw 0.3.2 → 0.5.1

package/templates/next/files/README.md

@@ -56,19 +56,21 @@ 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/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/layout.jsx         <html data-theme>, the _claw/theme.css link, AutoRefresh, ErrorRelay, EscapeRelay, Examples, 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
+app/error.jsx, app/global-error.jsx, app/not-found.jsx, app/error-relay.jsx, app/auto-refresh.jsx,
+app/escape-relay.jsx, app/frame.js, app/claw-alive/route.js   the app inside its window: refresh while shown (a surface opts out, §7), Escape from the desk
 components/ui/         the kit: Button, Field, Input, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction… (§3b, §3c)
-components/parts/      the parts: RecordSwitcher, useFixture + FixtureNotice (§3b)
+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)
@@ -95,7 +97,8 @@ Before any code, write `app/DESIGN.md` — one screen of text:
   `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.
+- Density, empty states (§3a: what each surface says while its table is
+  empty), error states.
 - What makes this app look like ITS domain and not another.
 
 Then `app/shell.jsx`, then the surfaces in the order the founder uses
@@ -109,15 +112,74 @@ 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.
+work going and see where it has got (`useJob`, `ask()`, §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 conversation is not: since 0.4.0 an ask is a request, and its
+conversation — the agent's questions, the founder's answers, the yes
+before it acts — lives in the desk's agent column, which the ask opens.
 
 **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.
 
+### 3a. Empty states — the work coming, never an example
+
+**A workspace app opens empty, and its empty state shows the live work
+— never an example.** The workspace's tables are shared by every app and
+every teammate, so an example there reads as a real row; and the member
+asked for results, not a demo. A table is empty because its agent has
+not got to it yet, or is on it right now. So an empty surface says which:
+
+```jsx
+// components/Deals.jsx (client)
+"use client";
+import { useState } from "react";
+import { useRequests } from "../lib/hooks";
+import { LiveEmpty } from "./parts";
+
+export default function Deals({ rows }) {
+  const work = useRequests({ surface: "deals" });
+  const [adding, setAdding] = useState(false);
+  if (!rows.length && !adding)
+    return <LiveEmpty work={work} surface="deals" icon="inbox" title="No deals yet"
+                      line="Ask the agent to find some, or add one."
+                      action={{ label: "Add a deal", onClick: () => setAdding(true) }} />;
+  /* … the deals, and the form while adding */
+}
+```
+
+With work in flight for this surface or its job — or the app's scheduled
+run going — `LiveEmpty` shows it as one row (its line, whose ask it is,
+what it waits behind, Answer when it needs the founder) over "Rows appear
+here as they land". With none, it is the plain empty block: what would
+be here, how it gets here, and the manual way to add one. Props: §3b.
+
+Name the job as well as the surface when its work can be asked for from
+the desk — `job: "find-deals"` to `useRequests` and `job="find-deals"`
+to `LiveEmpty`. An ask made on this surface carries the surface; one the
+desk hands to the app carries only its job, so a surface alone misses
+it. With neither, any of the app's live work shows.
+
+Examples show only OUTSIDE a workspace: in the store's authoring loop,
+where the app runs on its own with nothing but `DATABASE_URL`, and in a
+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
+`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.
+
+An example is never rendered any other way: `npm run check` refuses a
+`SAMPLE` constant (any `…SAMPLE…`, `…EXAMPLE…`, `…FIXTURE…` or `…DEMO…`
+name) in a file that renders without calling `useFixture()`, because only
+`useFixture` knows it is inside a workspace. `markSample` alone does not
+count (it did up to 0.3.x): it only gives rows their ids, so an example
+marked by hand would show to every member.
+
 ### 3b. Parts — assemble, never hand-roll
 
 Every control in the app is a part from `components/ui`; the pieces that
@@ -133,7 +195,7 @@ import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGr
          Field, Input, TimeInput, Textarea, Select, Switch, Checkbox, RadioGroup, Radio, Rating,
          InputGroup, PasswordInput, InputOTP, Slider, Image, FileInput, FileDrop, fileMatches, Combobox, Command, CommandDialog, Calendar, DatePicker, DateInput, DATE_PRESETS,
          parseDate, isDateString, toDateString, todayString, addDays, addMonths,
-         startOfMonth, endOfMonth, dayOfWeek, formatDate, firstDayOfWeek,
+         startOfMonth, endOfMonth, dayOfWeek, formatDate, toLocalDate, firstDayOfWeek,
          Card, Notice, Badge, Kicker, Empty, Item, ItemGroup, Avatar, AvatarGroup,
          Sheet, Confirm, Tabs, TabPanel, Menu, ContextMenu, Popover, Tooltip, HoverCard,
          Breadcrumb, Pagination, Collapsible, Accordion, Carousel, ScrollArea,
@@ -143,10 +205,12 @@ import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGr
          Stat, StatGroup, Delta, StatusDot, Legend, Meter, Distribution, Swatch, Steps,
          toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx }
   from "../components/ui";           // "./ui" from a component
-import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../components/parts";
+import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNotice, isSample,
+         Examples, useExamples } from "../components/parts";
 ```
 
-- `Button` — `variant` primary (one per surface) · secondary · quiet ·
+- `Button` — `variant` primary (one per surface, in the app's accent —
+  say it: a Button with no `variant` is secondary) · secondary · quiet ·
   danger · link (inline text: no padding or height, wraps and truncates
   with its sentence; `size="inherit"` takes the sentence's size;
   `tone="muted"` for a secondary link) · nav (a full-width navigation row, start-aligned, normal
@@ -155,8 +219,10 @@ import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../componen
   `IconButton` for an icon alone (`label` required). `loading` while its
   action runs: a spinner, the same width, `aria-busy`, disabled.
 - `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. `TimeInput` — a time of day
+  its label, hint and error. An `Input` is as wide as its column; a width
+  in its `className` (`w-24`, `w-auto`) sets its own. `Select` with
+  empty `options` renders a muted line, never a disabled dropdown.
+  `TimeInput` — a time of day
   ("HH:MM"; `min max step`), the kit's clock in place of the browser's.
 - `Rating` — stars: read-only `value` of `max` (halves drawn, "4.5 out
   of 5" to a reader), or with `onChange` a radio-group input; `size`, `label`.
@@ -183,8 +249,10 @@ import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../componen
 - `Sheet` — the one overlay, a rail beside the work (`side="end"`), a
   navigation drawer (`start`), a dialog (`center`) or a bottom sheet; on a narrow window every side
   becomes a bottom sheet; `bare` + `label` for a panel that draws its own
-  top (no header, flush body). `Confirm` is the "delete this?" case;
-  `consequences`, `requireText` and `acknowledge` hold it until met.
+  top (no header, flush body). A field inside with `autoFocus` takes the
+  focus once it opens (since 0.5.0; before, Close had it). `Confirm` is
+  the "delete this?" case; `consequences`, `requireText` and
+  `acknowledge` hold it until met.
 - `Image src alt ratio fit rounded` — a picture of a thing (thumbnail,
   cover): Skeleton while it loads, a glyph when it fails, lazy, `alt`
   required. Never a raw `<img>`; a face is an `Avatar`.
@@ -214,9 +282,16 @@ import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../componen
   `numberOfMonths`, `captionLayout` dropdown · none (you show and move a
   controlled `month`), `showWeekNumbers`, `weekStartsOn`, `marked` with
   `emphasizeMarked` and `onlyMarked`) and
-  `DateInput` (a typed date with the Calendar a button away). Dates are
+  `DateInput` (a typed date with the Calendar a button away;
+  `clearable` for an ×). Dates are
   `"YYYY-MM-DD"` strings in and out — never a Date — and `addDays`,
-  `addMonths`, `formatDate`… do the arithmetic.
+  `addMonths`, `formatDate`… do the arithmetic. A `date` column reads
+  as that same string (§4), so a row's day goes into a `DatePicker` and
+  back unchanged. Never `new Date("2026-09-28")`: that is UTC's
+  midnight, the 27th west of Greenwich, and a form that saves what it
+  shows moves the day back. Showing a day beside times (a due date by
+  a sent-at), `toLocalDate(value)` gives a Date at that day's LOCAL
+  midnight (a timestamp or a Date passes through).
 - `RadioGroup` (`options` or `<Radio>` children, each with a
   `description`; `variant` list · card; `orientation`; in a `Field` with
   the same `id`), `Toggle` (`pressed` + `onPressedChange`, aria-pressed),
@@ -248,7 +323,8 @@ import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../componen
   fill · code — a version tag or a commit hash in the mono face; `hue`
   1..5 for a KIND of thing — a platform, a content type — never a state:
   tone is status, hue is category), `Kicker` (the small line above a heading), `Empty` (a filter
-  or search with no matches — not the landing state, that is the fixture).
+  or search with no matches — not the landing state: an empty table is
+  `LiveEmpty`, below).
 - `Spinner` (size sm · md · lg), `Skeleton` (shape line · circle · rect,
   sized by className), `Progress` (`value` of `max`, no value for
   indeterminate; tone; `label`) — waiting, never a hand-drawn loader.
@@ -285,17 +361,46 @@ import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../componen
   counter; `loop`, `autoplay` only when asked), `ResizablePanelGroup`
   + `ResizablePanel defaultSize minSize` + `ResizableHandle grip`
   (`storageKey` remembers; a horizontal group stacks below md).
-- `Icon name="…"` — one sprite, `ICON_NAMES` lists it. Missing one? Add
-  the glyph to `components/ui/icon.jsx`; never an `<svg>` in a surface.
+- `Icon name="…" size` — one sprite, `ICON_NAMES` lists it; `size` is
+  pixels or xs · sm · md (16, the default) · lg · xl. Missing one? Pick the nearest in
+  `ICON_NAMES`: the sprite is fixed like the rest of the kit, so a new
+  glyph comes with a template release. 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.
+- `LiveEmpty work surface job icon title line action children` — what
+  an empty collection shows (§3a). `work` is what `useRequests()`
+  returns (§5); with none (a shadcn project) it is only the empty block.
+  `surface` and `job` pick the work that lands here: an ask made on this
+  surface, or work on this job wherever it was asked for — either is a
+  way in; neither means any live work. With work in flight it draws a
+  `LiveWork` row and "Rows appear here as they land"; else the empty
+  block — `icon` (default `inbox`), `title` (what would be here: "No
+  deals yet"), `line` (how it gets here), `action` (`{ label, onClick,
+  href, icon, variant }` for a Button — the manual way in — or an
+  element as it is). `children` go under either state.
+- `LiveWork request run onOpen onStop` — one piece of work in flight, as
+  a row: a pulsing dot, the request's line, "from Ana's request" when it
+  is not yours, "Queued · after …" while it waits its turn. A request
+  that needs an answer takes the warning tone and, for the one who
+  asked, **Answer** (calls `onOpen(request)`: the question is in the
+  desk's agent column); your own ask that is still going gets **Stop**
+  (calls `onStop(id)`). With no `request`, a `run` that is going shows
+  its title. `LiveEmpty` draws it for you; draw it yourself for work
+  beside a list that is not empty. `liveWords(requestOrStatus)` is the
+  status word alone: Working, Needs you, Answered, Done, Stopped, Didn't
+  finish.
+- `useFixture(rows, SAMPLE)` → `{ rows, isFixture, clear, restore }` +
+  `FixtureNotice` — the worked example, for the store's authoring loop
+  only (§3a): shown only outside a workspace, only while the real
+  collection is empty, and **never INSERTed**. Inside a workspace it
+  returns the real rows (none) with `isFixture` false, and `clear` does
+  nothing. 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 (the
+  platform refuses an ask about one: `row._sample` is not the founder's
+  data). `<Examples allowed>` is the switch `app/layout.jsx` sets and
+  `useExamples()` reads; the layout is fixed, so you never mount it.
 
 A control with nothing to act on is not drawn.
 
@@ -412,7 +517,14 @@ 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
+`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,
+from `loadRows` and from `query()` alike (`lib/db.js` reads it so). Up to
+0.4.x `query()` gave a Date at the server's midnight and the reads an ISO
+timestamp of it, a day off on either side of UTC. A server file that
+called a Date method on a `date` value now holds the day's string:
+compare days as strings (`"2026-09-28" < "2026-10-01"`), and build a
+Date only where a sum needs one. 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
@@ -437,7 +549,7 @@ import { moveRow } from "../lib/actions";
 import { Card, Notice } from "./ui";
 import { FixtureNotice, useFixture } from "./parts";
 
-const SAMPLE = [{ name: "Ada Ventures", stage: "warm" }, /* … */];
+const SAMPLE = [{ name: "Ada Ventures", stage: "warm" }, /* … */];   // shown only outside a workspace (§3a)
 
 export default function InvestorBoard({ rows: real, error, highlight }) {
   const { rows, isFixture, clear } = useFixture(real, SAMPLE);
@@ -449,6 +561,27 @@ 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).
 
+### Views by link
+
+A result points into the app. When a job is done, the desk tells the
+member where it landed ("50 emails sent · Pipeline CRM › Sales") and
+that link opens the app's window on one surface with a query: `/s/<key>?…`
+inside the app, `/a/<id>/app/s/<key>?…` on the desk. So the query is
+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.
+- 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
+  honours, and honour every one you declare. `t`, `theme`, `chat` and
+  any key starting `_` belong to the platform.
+
 ### Linking — `next/link`, never a bare `<a href="/…">`
 
 The app is served under a prefix (`/p/<label>` in local dev, nothing in
@@ -521,7 +654,8 @@ 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,
+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)`
 (stable ids + `_sample: true`), `currentSurface(explicit)` (the surface
 key of the request, from `x-claw-surface`, unless one is passed).
@@ -546,6 +680,13 @@ saveSetting({ mode = "table" | "json", source, keyColumn = "key", valueColumn =
 when missing — a plain `key text, value text` table is enough. JSON mode
 sets `key` inside the jsonb `column` of row `id`.
 
+Every update (`updateRow`, `moveRow`, `saveSetting`) sets `updated_at =
+now()` when the table has an `updated_at` timestamp it can write (since
+0.5.0; before, only a trigger of the app's own kept it). A patch that
+sets `updated_at` itself wins, and a column of that name that is text, a
+number or a view's computed value is left alone. An insert leaves it to
+the column's default: `updated_at timestamptz not null default now()`.
+
 ```js
 "use client";
 import { moveRow } from "../lib/actions";
@@ -553,47 +694,101 @@ const r = await moveRow({ source: "public.investors", id, stateColumn: "stage",
 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`.
+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/`.
 
 ### 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.
+false, status, error, unavailable, code }`; nothing throws. `unavailable:
+true` (a 404 that names no refusal, or no network) means the gateway has
+no such route yet: show a quiet "not connected yet", not an error.
+`code` names a refusal a caller can act on (`not_your_thread`,
+`needs_answer`, `queue_full`, `unknown_job`, …).
 
 ```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.me()                                          GET  _claw/me       → { artifact: { id, name, vehicle, status, home }, user: { id, email }, blueprint, desk_origin }
+platform.ask({ text, row, how, job, list, surface, sessionId, open })
+                                                       POST _claw/ask      → { ok, request, desk_origin }, and the column opens on it
+platform.requests()                                    GET  _claw/requests → { requests, run, desk_origin }
+platform.requests({ id })                              GET  _claw/requests?id=<id> → { request }
+platform.stopRequest(id)                               POST _claw/requests/<id>/stop → { ok, request }
+platform.openRequest(requestOrId)                      open its conversation in the desk's agent column → true when the desk was asked
+platform.surfaceOfPath(pathname)                       the <key> of /s/<key> in a path, or undefined
 platform.reportError({ message, stack, url, source })  POST _claw/events
+platform.startJob(message, { sessionId, onEvent })     POST _claw/chat     → streams session · delta · tool · done · error  (legacy)
+platform.cancelJob(sessionId)                          POST _claw/cancel   (legacy)
 ```
 
-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
+A request, as `ask` and `requests` hand it back: `{ id, title, words,
+status, worker, line, live_line, job_key, list_key, surface, progress: {
+n, of, noun, at } | null, result: { sentence, count, badge, view: {
+surface, label, path, window_path } | null } | null, queued: { reason,
+after_id, after_title } | null, app_session_id, mine, asker_name,
+created_at, updated_at, ended_at }`. `status` is one of eleven: seven
+live — routing, queued, installing, setting_up, building, working,
+needs_you — then answered (open, but no work is coming), done, stopped,
+didnt_finish. `line` is the one line every screen shows for it
+("Drafting · 12 of 50", "Needs you · Send 50 emails from you@acme.com?");
+show it as it is, never a status word of your own. `app_session_id` is
+set only on your own requests.
+
+Named exports: `me, ask, requests, stopRequest, openRequest,
+surfaceOfPath, startJob, cancelJob, reportError, platform`. That is the
+whole list. Note what is **not** there: the runs, the chat history, Run
+now, Pause / Resume. Those are MONITORING and they are the OS's — the
 window's tabs and title bar — so an app never calls `_claw/agent`,
-`_claw/runs`, `_claw/run`, `_claw/pause` or `_claw/resume`. 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.
+`_claw/runs`, `_claw/run`, `_claw/pause` or `_claw/resume`. Asking is the
+opposite thing, and it belongs here (`ask()` and `useJob`, below).
+`requests` is not monitoring either: it is this app's asks in flight, so
+an empty surface can show the work coming (§3a). `startJob` and
+`cancelJob` are the 0.3.x door to the same work, kept so `useJob` can
+fall back to it on a claw that has no `_claw/ask`; new code asks. The
+artifact's status lives on `<html data-claw-status>` and the desk's
+origin on `<html data-claw-desk-origin>` (`publishStatus`, `publishDesk`
+in `lib/claw.js`); `app/error-relay.jsx` and `useArtifact()` keep both
+current. An ask tells the desk which request to open with a message to
+that exact origin — never `"*"` — and only while the app is framed.
 
 ### 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.
+Four hooks: a generic fetch over one `_claw` route, the app's identity,
+a job, and the app's requests. Each owns fetching, polling (while the
+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 }
+useClaw(path, { every, enabled = true })     → { data, error, loading, unavailable, reload }
+useArtifact()                                 → { artifact, user, blueprint, loading, error, unavailable, reload }
+useJob()                                      → { running, status, queued, queuedAfter, needsYou, liveLine, count, target,
+                                                  steps, text, progress, error, sessionId, requestId, request, finishedAt,
+                                                  start, cancel, reset, open }
+useRequests({ surface, job, every = 5000 })   → { requests, live, run, loading, error, unavailable, reload, open, stop }
+jobFromRequest(request)                       → what useJob shows for one request (pure; for tests)
 ```
 
+`useRequests` is the work asked of this app's agent — from a screen or
+from the desk, by anyone in the workspace. `requests` is every one the
+gateway returned (the live ones and those that ended in the last day);
+`live` is the ones not ended that belong here — `surface`: asks made on
+this surface; `job`: work on this job wherever it was asked for; either
+is a way in, neither means all; `run` is the app's scheduled run while
+one is going, else null. `open(request)` opens its conversation in the
+desk's agent column; `stop(id)` stops one and looks again. It looks
+every `every` ms while work goes, every 20 s while none does, and only
+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
@@ -602,9 +797,21 @@ 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.
+and sees it happen where the result will land. 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.
+
+Since 0.4.0 a job is a request. `job.start(text)` asks through `ask()`
+(below): the platform makes the ask a request, hands it to the app's
+agent, and the desk opens its conversation in the agent column. **The
+conversation and the yes live in the desk's agent column** — the agent's
+questions, the founder's answers, the "Send 50 emails?" before anything
+public or paid. The app follows the request's status and draws the
+panel from it. Up to 0.3.x the job streamed into the app over
+`_claw/chat` and the panel carried the agent's running text; on a claw
+that has no `_claw/ask` yet, `useJob` still does exactly that (`text`
+filled, `requestId` null), so a 0.4.0 app runs on an older claw.
 
 ```jsx
 const job = useJob();
@@ -612,24 +819,68 @@ 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")}>
+<Button onClick={() => job.start("Draft a launch checklist for Rowhouse")} disabled={job.running}>
   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}
+</Button>
+<JobPanel job={job} title="Drafting the launch plan" doneTitle="Launch plan drafted" />
 ```
 
 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.
+rules below for you and says what the request says: its status and its
+count ("Drafting · 12 of 50"), "Needs your answer" with **Answer** while
+the agent waits on the founder, "Queued · after …" while the job waits
+its turn. Draw your own only when it cannot say what the founder needs
+to see, and from the same fields: mounted on `job.running ||
+job.finishedAt || job.error`, `job.liveLine` as its line, `job.needsYou`
+→ a button calling `job.open()`, `job.queued` →
+`job.queuedAfter?.after_title`, Stop → `job.cancel()`, Close →
+`job.reset()`.
+
+**Which job.** `start` sends `job: true` unless you pass a key, and the
+platform picks: the job whose view is this surface, else the app's only
+job, else none. Pass `job.start(text, { job: "<key>" })` when a surface
+starts a job whose view is ANOTHER surface — "Find 20 leads" pressed on
+Pipeline, landing on Leads — or it picks the wrong one, or none. A key
+the app does not declare is refused (`unknown_job`).
+
+**One job per list runs at a time.** A start on a job that is already
+running for that list does not run beside it: it answers `queued`
+(`job.queued`; `job.queuedAfter.after_title` names what it waits for)
+and starts on its own when that one ends. A job that repeats on a
+schedule waits the same way behind the app's scheduled run. It counts as
+running meanwhile — the panel stays, and Stop takes it out of the
+queue. With ten asks waiting, the app refuses the next (`queue_full`).
+
+**`start` resolves on the ask, not on the work:** `{ ok: true, data: {
+request } }` once the platform took it, or the refusal (`{ ok: false,
+error, code }` — `needs_answer` while the thread waits on an answer in
+the column, `queue_full`, `unknown_job`, `no_credits`, …; the panel
+shows the error). The hook then follows the request — every 2.5 s while
+the App tab is on screen — until it ends. On the 0.3.x path it resolves
+when the job ends, as it always did. React's development double mount
+(and a fast refresh) cleans the hook up and mounts it again: it follows
+a live request on from there, and an ask it cut off before an answer
+came closes the panel — neither done nor failed. A job started from an
+effect runs twice there; start it from a press.
+
+What it holds, for the panel:
+
+- `running` — the work is live: any of the seven live statuses, queued
+  and needs-you included. `status` is the request's own.
+- `needsYou` — the agent waits on the founder; `open()` takes them to
+  the question in the column.
+- `queued`, `queuedAfter` (`{ reason, after_id, after_title }`).
+- `liveLine` — the desk's line for it; `count`, `target` — the counted
+  progress (12 and 50), or null.
+- `steps` — one: the request, its line as the `label`. `text` — empty:
+  the account is in the column.
+- `progress` — bumps whenever the work moves (its status, its count).
+- `error` — the line when it didn't finish, "Stopped" when stopped.
+- `sessionId`, `requestId`, `request` (the whole request), `finishedAt`.
+
+Actions: `start(text, { sessionId, row, how, job, list, open })` — the
+options are `ask()`'s; `cancel()` stops the request itself, not only the
+panel; `reset()` closes the panel; `open()` opens the conversation.
 
 Four rules, and a build is wrong without them:
 
@@ -638,18 +889,65 @@ Four rules, and a build is wrong without them:
    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.
+   `job.running || job.finishedAt || job.error` (a refused ask has an
+   error and no finish); `job.reset()` closes it. A panel that is always
+   there is the monitoring console (§2.7).
+3. **The deliverable is ROWS.** Not `job.text` — the agent's own
+   account, and empty on a request, whose account is in the column —
+   and not the request's line. 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`.
+   phrase ("Drafting · 12 of 50"; "Searching the web" on the 0.3.x
+   path); `name` is `request`, or a tool's `web_search`.
+
+`job.sessionId` is the thread, and on a request it is set only when the
+thread is yours. 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. A thread that is a
+teammate's, or one the claw does not know (a 0.3.x session kept on a
+row), is refused; `start` then asks once more without it, and the ask
+gets a thread of its own.
+
+### Asking the agent — `ask()`
+
+`useJob` is `ask()` plus a panel to follow it. Call `ask()` from
+`lib/platform.js` yourself when there is nothing for the app to follow:
+a question about a row ("What do we know about Acme?"), a one-off whose
+answer is words in the column, not rows. It takes one object:
+
+- `text` — what the member reads. It is the request's words on the desk
+  (the Requests list, the column), so write it the way they would say
+  it: "Find 20 leads like Acme", never "You are a lead finder…".
+  Required; at most 2,000 characters.
+- `how` — for the agent only: the steps, the table to write, the
+  format. The member never sees it. At most 4,000 characters.
+- `row` — the row it is about: the agent's context (at most 8 KB as
+  JSON). Never an example row — one marked `_sample` is refused.
+- `job`, `list` — name the job: a declared key, or `true` to let the
+  platform pick (what `useJob` sends by default), and the list its work
+  belongs to, for an app that declares lists (§4, Views by link). With
+  no `job` the ask is not a job: nothing queues, nothing is counted.
+- `surface` — defaults to the `<key>` of `/s/<key>` in the page's path.
+- `sessionId` — continue your own thread: while its request is open the
+  ask joins it; once it has closed, a new request follows it in the
+  same thread. While that request waits on an answer (`needs_answer`)
+  or in the queue (`queued`, 409 both) the ask is refused: the answer
+  goes in the column, and a queued one starts on its own. A teammate's
+  thread is refused (`not_your_thread`, 403) — ask again without it to
+  start your own; `useJob` does that for you.
+- `open` — the ask opens its request in the desk's agent column, where
+  the conversation lives; `false` leaves the column as it is.
+
+```js
+"use client";
+import { ask } from "../lib/platform";
+
+const r = await ask({ text: `What do we know about ${row.name}?`, row, how: "Read the Wiki's customer pages first." });
+if (!r.ok) setError(r.error);                  // r.code: needs_answer, queue_full, …
+```
 
-`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.
+It resolves once the platform took the ask (`{ ok: true, data: {
+request, desk_origin } }`) or refused it; it never waits for the work.
 
 ### Activity — the contract
 
@@ -706,10 +1004,10 @@ 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    examples   examples show only outside a workspace (useFixture); a workspace app opens empty
 ok    manifest   2 surfaces: drafts, sent
 ok    icons      every icon name exists
-ok    kit        33 fixed files match the template
+ok    kit        70 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
@@ -726,11 +1024,14 @@ 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.
+- In a workspace, an empty table shows `LiveEmpty`: the work in flight,
+  else what would be here and the manual way to add it — never an
+  example (§3a). A saved row replaces it.
 - Error state shows the text from `{ error }`.
 - Keyboard focus visible on every control.
 - Numbers tabular (`data-nums`).
-- Every write goes through `lib/actions.js`; no raw SQL from a surface.
+- 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 surface reachable from the nav.
 
 ## 7. Run
@@ -747,14 +1048,37 @@ surface; `--static` skips the build and the smoke. Then, by eye:
    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`.
+   `CLAW_PRODUCT_TOKEN` and `CLAW_ARTIFACT_ID` — the last is what turns
+   examples off (§3a).
 
 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.
+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.
+
+**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}`.
+
+**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
+platform stops an app nobody used for 30 minutes, and every refresh is a
+use, so an open tab nobody looked at kept its app running all night. The
+next sign of someone refreshes at once and the refresh goes on; so does
+coming back to the tab. Nothing on the page says so: the first touch
+brings it up to date.
+
+The founder reads "artifact", "app", "agent", "automation" — nothing else.