makersclaw 0.8.0 → 0.8.2

package/templates/next/files/README.md

@@ -99,7 +99,7 @@ lib/brain.js           the company brain from the browser, in both modes; its ho
 lib/brain-server.js    the brain's reads for a server component — a server app's
 lib/claw.js            the _claw API the gateway answers, from the browser
 lib/platform.js        typed wrappers over lib/claw.js (Platform)
-lib/hooks.js           the React hooks over them: useJob, useLlm, useArtifact… (Hooks)
+lib/hooks.js           the React hooks over them: useJob, useLlm, useLibraryItems, useArtifact… (Hooks)
 lib/sample.js          markSample, for sample rows (§3a)
 ```
 
@@ -255,7 +255,7 @@ import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGr
          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, toLocalDate, firstDayOfWeek,
-         Card, Notice, Badge, Kicker, Empty, Item, ItemGroup, Avatar, AvatarGroup,
+         Card, ActionCard, Notice, Badge, Kicker, Empty, Item, ItemGroup, Avatar, AvatarGroup,
          Sheet, Confirm, Tabs, TabPanel, Menu, ContextMenu, Popover, Tooltip, HoverCard,
          Breadcrumb, Pagination, Collapsible, Accordion, Carousel, ScrollArea,
          ResizablePanelGroup, ResizablePanel, ResizableHandle,
@@ -263,7 +263,7 @@ import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGr
          Spinner, Skeleton, Progress, Separator, Kbd, KbdGroup, AspectRatio,
          Stat, StatGroup, Delta, StatusDot, Legend, Meter, Distribution, Swatch, Steps,
          toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx,
-         AppLayout, DocumentLayout }
+         AppLayout, DocumentLayout, PageLayout }
   from "../components/ui";           // "./ui" from a component
 import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNotice, isSample,
          Examples, useExamples } from "../components/parts";
@@ -289,8 +289,12 @@ import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNoti
   spreadsheet), `contentLabel`, `contentClassName` (spacing and token
   backgrounds only) and `scrollKey` (pass the route: when it changes the
   content scrolls back to its top and the drawer closes) · `inspector`
-  (beside the content from `inspectorAt` md · lg · xl, lg by default;
-  `inspectorWidth` px, 360 by default, 240 to 560; `inspectorLabel`) ·
+  (beside the content from `inspectorAt` md · lg · xl, lg by default, of
+  the window's width; `inspectorIn="frame"` counts the body between the
+  rail and the dock instead, 42 · 48 · 64 rem, so an agent dock that
+  takes a quarter of the window sends the inspector under the work
+  rather than squeezing it; `inspectorWidth` px, 360 by default, 240 to
+  560; `inspectorLabel`) ·
   `footer` (under the content, in view) · `height` viewport · parent.
   Below `inspectorAt` there is no room for two columns: in `scroll` mode
   the content and the inspector share one scroll, the inspector after
@@ -320,6 +324,56 @@ import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNoti
   navigation, header, inspector or footer) and the document flows onto
   pages. Inside either, bound a box by its parent (`h-full`, `flex-1
   min-h-0`) or by a size (`max-h-96`, `ScrollArea`), never by the window.
+
+  `PageLayout` is a screen's main area with an optional side column,
+  full height. The main is the column that scrolls; the side is the fixed
+  one. Roadmap's Today ended at
+  680px in a 1240px window because it drew its own two-column grid
+  inside the scrolling content: only as tall as its words, the side's
+  divider stopped halfway and the bottom of the window was empty. Put it
+  inside an `AppLayout` with `contentMode="fill"` and no padding on the
+  content; the columns pad themselves, so the divider runs to the edges.
+  `side` (the side column) · `sideWidth` px (304; 220 to 560) · `sideAt`
+  md · lg · xl (the page's own width from which the side sits beside the
+  main, 42 · 48 · 64 rem: a measure of the page, so an open agent dock
+  does not squeeze it; narrower, the side goes under the main in one
+  scroll) · `mainLabel`, `sideLabel` · `padded` · `fill` (the main is a
+  flex column, so a child with `flex-1` grows into the height) ·
+  `className`, `mainClassName`, `sideClassName` (spacing, never a height).
+  `npm run check` refuses a screen that draws its own main + side
+  (`grid-cols-[minmax(0,1fr)_19rem]` and a ruled `<aside>`, rule `page`).
+
+  **What belongs in the side, and what never does** (the founder, looking
+  at a first run that was a short intro on the left and a long "Name it"
+  form in the right column: "this can only work if one column is fixed,
+  usually the 3rd column, and the middle one is scrolling"). The side is
+  the fixed column: it stays put while the main scrolls, so it is short
+  and never needs a scroll of its own.
+  - In the side: a summary, the next step, a few facts about the record,
+    a small panel (an allowance, "needs you" with a few lines), a short
+    list that says its bound (`items.slice(0, 5)` and "and 3 more").
+  - Never in the side: a form (`<form`, several `Field` or `Input`, a
+    `Textarea`, a paste box), a list that grows with the data, a shelf of
+    examples. They go in the main, where the page scrolls. A "Name it" or
+    "Paste a list" step that opens reveals its own card in the main flow;
+    it does not open a form in the side.
+  - The side's own scroll (thin) is a last resort for a window shorter
+    than the side. It is not how anything is meant to be read.
+  - Narrower than `sideAt`, the side goes under the main in one scroll.
+  `npm run check` rule `sidelong` refuses a `side` or an `<aside>` that
+  holds a form, a `Textarea`, three or more fields, or a `.map(` of data
+  that is not bounded by a `.slice(`. It reads the side's own markup and
+  the components defined in the app that the side draws (three levels
+  deep). It cannot see a block or kit component's insides, content that
+  arrives from props or context, or how long a list really is at run time;
+  the docs and review carry those. A screen:
+  ```jsx
+  <AppLayout header={<TopBar crumb={crumb} />} contentMode="fill">
+    <PageLayout side={<Projects />} fill>
+      <NeedsALook />
+    </PageLayout>
+  </AppLayout>
+  ```
 - `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
@@ -427,6 +481,14 @@ import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNoti
   — a table that scrolls inside itself on a phone.
 - `Card` (`padding` md · sm · none — none for a table or rows that run
   to the border, never `p-0!`; `titleSize` md · lg for a 20px title),
+  `ActionCard` (one step the member takes: `icon`, `title`,
+  `description`, `children`, `status` = `{ tone, children }` above the
+  one full-width `action`; in a row it stretches to the row's height and
+  pins its status and action to the bottom, so the buttons line up (`fit`
+  is the old only-as-tall-as-its-words, for one lone card; never
+  `self-start` on a card in a row) — a connect-and-first-read card, "Add one person", "Bring in a
+  file". A screen's boxes are Card, ActionCard or Notice, never a
+  hand-drawn bordered div),
   `Notice` (tone neutral · info · success · warning · danger),
   `Badge` (tone neutral · primary · success · warning · danger · info;
   `variant` label — small caps · soft — the case as written, every tone
@@ -453,7 +515,9 @@ import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNoti
   `Meter value max unit target thresholds` (a role=meter; over the limit
   turns danger; `direction` higher · lower picks the tone against the
   target; `valueTone`; `targetMark={false}`; tone `muted` for a plain
-  grey share) — numbers and states, never a hand-drawn tile or bar.
+  grey share; `compact` the bar (or ring) alone, its label and numbers
+  kept for screen readers and as the tooltip — a labelled Meter in a box of
+  8rem or less must be `compact`) — numbers and states, never a hand-drawn tile or bar.
   `Delta hideValue` is the arrow alone; `StatusDot` and Legend items take
   `hue` (1..5) for a category. `Distribution segments={[{ label, value,
   tone, hue }]} legend label size` (thin · md) — parts of one whole as
@@ -1048,6 +1112,130 @@ 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`).
 
+### Declared actions — `makersclaw.json` `actions` (0.8.1)
+
+Every write a screen makes is a declared action: the screens call it by
+name with `runAction({ name, args })`, and the app's agent calls the same
+name as one of its tools, run by the platform's one runner. Once an app
+declares any, its agent can write no other way, so `npm run check`
+(§6, `actions`) fails a screen write that is not one: an undeclared
+name, a one-row write (`insertRow`, `updateRow`, `moveRow`, `deleteRow`,
+`saveSetting`: make it a function) and a company brain write from
+`lib/brain.js` (erase, confirm and merge stay a person's press).
+
+```json
+"actions": [
+  {
+    "name": "add_people",
+    "description": "Add up to 100 people, each linked to their company.",
+    "input": {
+      "type": "object",
+      "properties": {
+        "people": {
+          "type": "array", "maxItems": 100,
+          "items": { "type": "object", "properties": {
+            "name": { "type": "string" }, "email": { "type": "string" },
+            "company": { "type": "string" }, "company_domain": { "type": "string" } },
+            "required": ["name"] }
+        },
+        "list_id": { "type": "string" }
+      },
+      "required": ["people"]
+    },
+    "brain": {
+      "each": "people",
+      "writes": [
+        { "as": "company", "kind": "company", "when": "company", "fields": { "name": "company", "domain": "company_domain" } },
+        { "as": "person", "kind": "contact", "fields": { "name": "name", "email": "email", "company_name": "company" } }
+      ],
+      "links": [{ "from": "person", "to": "company", "type": "works_at" }]
+    },
+    "sql": "crm_people_added"
+  },
+  { "name": "make_list", "description": "Make a list of people or companies.",
+    "input": { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] },
+    "sql": "crm_make_list" }
+]
+```
+
+- `input` is a JSON Schema object (type, properties, required, items,
+  enum, min/max, descriptions); the agent reads it whole, so keep it
+  under 12,000 characters.
+- `sql` is a function `<name>(args jsonb) returns jsonb` in the app's
+  schema, run as the app, with the member set, after the `brain` steps.
+- `brain` writes company records as the member and the app: each write
+  is `{ as, kind, fields }`, each field read from an input key (`"name"`:
+  the item's, with `each`; `"$.list_id"`: the input's top level;
+  `{ "value": "lead" }`: a constant). An empty value is left out, never
+  cleared. `when` writes it only when that key has a value; `each` runs
+  the writes once per item of a list of at most 100; `links` join two
+  writes (`from`/`to` an `as`, or `{ "id": <key> }`, a record id the
+  input holds) by a link type the kind declares. Every kind is one the
+  app writes (`brain.writes`), every field one of its fields. The `sql`
+  function gets the input plus `records`: for each `as`, `{ id, created
+  }` (a list in item order with `each`; null where `when` skipped it).
+  If the function refuses, the records the call made are taken back.
+- A write with `"id"` changes the record that input key names (an edit,
+  never a create), as the member and the app may: one they cannot both
+  read, or of another kind, is not found and nothing is written.
+  `"if_version"` names a key holding the version the screen read
+  (refused `changed` when it moved on); `{ "value": null }` empties a
+  field, and `"clear"` names a key listing fields to empty (an array of
+  strings whose `items.enum` are among the write's fields); `{ "now":
+  true }` is the time of the call. If a later step fails, the fields it
+  changed get their old values back.
+- A link with `"op": "remove"` takes one off (removals run first, so one
+  call moves a link), and an action may be `links` only, with no
+  `writes`. Archive is an edit of the kind's own field (`archived_at`:
+  `{ "now": true }`, back with `{ "value": null }`); erase and merge stay
+  a person's press, from `lib/brain.js`.
+
+```json
+{ "name": "move_deal", "description": "Move a deal to a stage and another company.",
+  "input": { "type": "object", "properties": {
+    "deal_id": { "type": "string" }, "version": { "type": "integer" }, "stage": { "type": "string" },
+    "from_company": { "type": "string" }, "to_company": { "type": "string" } },
+    "required": ["deal_id", "stage"] },
+  "brain": {
+    "writes": [{ "as": "deal", "kind": "deal", "id": "$.deal_id", "if_version": "$.version",
+      "fields": { "stage": "$.stage", "stage_changed_at": { "now": true }, "closed_at": { "value": null } } }],
+    "links": [
+      { "from": "deal", "to": { "id": "$.from_company" }, "type": "for_company", "op": "remove" },
+      { "from": "deal", "to": { "id": "$.to_company" }, "type": "for_company" }] },
+  "sql": "crm_deal_moved" }
+```
+
+- `agent: false` only for a write the agent must never make.
+- `references/actions.md` says, per action, when and why: never a recipe.
+
+### Shipped automations — `makersclaw.json` `automations` (0.8.1)
+
+An app may ship automations: flows the platform runs for it on a schedule
+or by hand, made of its own declared actions. List them in
+`makersclaw.json`, under `automations`, next to `actions`. The store ships
+the same list as `seeds.automations` in `store.json`.
+
+- Each entry is a definition in the platform's automation format (format
+  1: `key`, `name`, `trigger`, `inputs`, `settings`, `steps`), exactly as
+  the automations blocks draw and save one.
+- An `action` step names one of the app's declared `actions` (its `app`
+  stays out: an app's automation runs its own app's actions).
+- `replaces_wake` is the one field that is not part of the definition. It
+  is the name of a legacy wake (an older scheduled job of the app, in its
+  `store.json` `seeds.wakes`) that this automation takes over: when the app
+  is installed or updated the wake is switched off, so the job never fires
+  twice. Leave it out for a new automation. Name a scheduled wake (advance
+  or review), never an event wake, and one automation per wake. The
+  app's `store.json` lists the same name.
+- At most 20 automations, keys unique.
+
+`npm run check` runs the list through the platform's own validator (rule
+`automations`), so a flow the platform would refuse at install is refused
+at build. It checks the shape, the kinds of step, the expressions and that
+every `action` step names a declared action. Which wakes exist and which
+kinds of account a `tool` step may ask for are checked where the whole
+package is known (the store's publish).
+
 ### Door — `lib/door.js` (browser, both modes)
 
 The app's own tables, read and written from the browser through the
@@ -1107,7 +1295,10 @@ whenLanded()    resolves once those reads have landed
   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.
+  (open the row just made), `await whenLanded()` first. Use
+  `afterWrite(write)`: it answers with the write's answer after the hooks
+  hold the new rows; a record page asks `useNotFound(found, { loading })`
+  before it says "not found".
 - `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
@@ -1334,6 +1525,12 @@ platform.ask({ text, row, how, job, list, surface, sessionId, open })
                                                        POST _claw/ask      → { ok, request, desk_origin }, and the column opens on it
 platform.llm(input, { system, schema, maxTokens, tier, task, signal })
                                                        POST _claw/llm      → { ok: true, text } | { ok: true, data } | { ok: false, error, code }  (Calling a model)
+platform.library.collections({ q, shelf })             GET  _claw/library/collections → { collections }        (Showing the Library)
+platform.library.collection(id)                        GET  _claw/library/collections/<id> → { collection }
+platform.library.items(id, { q, tag, cursor, limit })  GET  _claw/library/collections/<id>/items → { items, next_cursor, total, preview_only }
+platform.library.rows(id, { q, filters, cursor, limit })
+                                                       GET  _claw/library/collections/<id>/rows → { rows, next_cursor, total, preview_only }
+platform.library.item(id)                              GET  _claw/library/items/<id> → { item, file_url?, text_excerpt? }
 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 }
@@ -1342,6 +1539,24 @@ platform.surfaceOfPath(pathname)                       the <key> of /s/<key> in
 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)
+
+// The kit (0.8.1) — what the kit's blocks draw; lib/hooks.js follows each one
+platform.jobs()                                        GET  _claw/jobs     → { app: { status, live }, jobs: [{ id, name, kind, topic, does, cron, tz, words,
+                                                                              enabled, next_run_at, last_run_at, last_run, plan }], budget, credits, may: { run, switch, pause } }
+platform.setJob(id, { enabled })                       PATCH _claw/jobs/<id> → { ok, job }          (not_allowed 403 · unknown_job 404)
+platform.runNow(wakeId)                                POST _claw/run      → { ok, run_id, wake }   (spends: its price on the button)
+platform.pauseApp() · platform.resumeApp()             POST _claw/pause · _claw/resume → { status }  (the Live switch)
+platform.runs({ job, limit })                          GET  _claw/runs     → { runs: [{ id, title, state, wake_id, job, trigger, by, number,
+                                                                              started_at, ended_at, duration_ms, credits, report, status }], overview }
+platform.run(id)                                       GET  _claw/runs/<id> → { run, steps: [{ label, status }], text, needs }
+platform.activity({ row, surface, since, limit })      GET  _claw/data/activity → { rows: [{ id, at, action, surface, row_ref, detail, data, by }] }
+platform.connections()                                 GET  _claw/connect  → { connections: [{ key, label, required, connected, accounts, category, category_label }] }
+platform.connectLink(key)                              POST _claw/connect  → { ok, key, label, connected, url }   (outside the desk)
+platform.openConnections(key)                          ask the desk to open its connections panel for that need → true when the desk was asked
+platform.agentKit()                                    GET  _claw/agent    → { own_skills: [{ name, title, when }], skills: [{ name, installed }],
+                                                                              actions: [{ name, description, agent }], … }
+platform.llmEstimate(input, { system, schema, maxTokens, tier, task })
+                                                       POST _claw/llm, estimate: true → { ok: true, estimate: { credits, credits_max } }  (never sent to a model, never charged)
 ```
 
 A request, as `ask` and `requests` hand it back: `{ id, title, words,
@@ -1357,16 +1572,32 @@ didnt_finish. `line` is the one line every screen shows for it
 show it as it is, never a status word of your own. `app_session_id` is
 set only on your own requests.
 
-Named exports: `me, ask, llm, requests, stopRequest, openRequest,
-surfaceOfPath, startJob, cancelJob, reportError, platform`. That is the
-whole list. Note what is **not** there: the runs, the chat history, Run
-now, Pause / Resume. Those are MONITORING and they are the OS's — the
-window's tabs and title bar — so an app never calls `_claw/agent`,
-`_claw/runs`, `_claw/run`, `_claw/pause` or `_claw/resume`. Asking is the
-opposite thing, and it belongs here (`ask()` and `useJob`, below).
-`llm()` is neither: one call to a model, answered in the page (Calling a
-model, below). It is the one wrapper that resolves the platform's answer
+Named exports: `me, ask, llm, llmEstimate, library, requests,
+stopRequest, openRequest, threads, thread, surfaceOfPath, startJob,
+cancelJob, reportError, jobs, setJob, runNow, pauseApp, resumeApp, runs,
+run, activity, connections, connectLink, openConnections, agentKit,
+platform`. That is the whole list.
+
+Up to 0.8.1 the runs, Run now, Pause / Resume and the agent's settings
+were not here: they were MONITORING, and the OS drew them as the window's
+tabs so that every app showed its agent's work in one look. The kit
+(0.8.1) moved that one look into the template's blocks (The agent and AI
+kit, below), so the app now shows its agent's work itself, beside the
+rows the work wrote, and calls `_claw/jobs`, `_claw/runs`, `_claw/run`,
+`_claw/pause`, `_claw/resume`, `_claw/agent` and `_claw/connect` through
+these wrappers. The window's tabs stay, as the full history. Two things
+never move into the app: **the account sign-in and money** stay on the
+desk. The agent's questions are answered in the app (`answer`), and the
+yes is given in the app too, but never by the app: it is a press in a
+Makersclaw-held frame (`approval`, the `approval` block). The door decides
+who may press what (`may` on `jobs`): hide what the member may not press,
+and the door refuses it anyway.
+Asking is its own thing, and it belongs here too (`ask()` and `useJob`,
+below). `llm()` is neither: one call to a model, answered in the page
+(Calling a model, below). It is the one wrapper that resolves the platform's answer
 as it is, `{ ok: true, text }` and not `{ ok: true, status, data }`.
+`library` is neither asking nor monitoring: it reads what Makersclaw
+keeps, read only (Showing the Library, 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
@@ -1379,10 +1610,13 @@ that exact origin — never `"*"` — and only while the app is framed.
 
 ### Hooks — `lib/hooks.js` ("use client")
 
-Five hooks: a generic fetch over one `_claw` route, the app's identity,
-a job, the app's requests, and a model call. Each owns fetching, polling (while the
-tab is visible; once a minute while `unavailable`), streaming and cleanup
-on unmount. A surface renders what comes back and owns every pixel.
+A generic fetch over one `_claw` route, the app's identity, a job, the
+app's requests, a model call, five that read the Library, the app's own
+chat, and the kit's eight (0.8.1). Each owns
+fetching, polling (while the tab is visible; once a minute while
+`unavailable`; the Library's read once and have nothing to poll),
+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 }
@@ -1392,9 +1626,49 @@ useJob()                                      → { running, status, queued, que
                                                   start, cancel, reset, open }
 useRequests({ surface, job, every = 5000 })   → { requests, live, run, loading, error, unavailable, reload, open, stop }
 useLlm()                                      → { run, loading, result, error, unavailable }   (Calling a model)
+useLibraryCollections({ q, shelf })           → { collections, loading, error, code, unavailable, reload }   (Showing the Library)
+useLibraryCollection(id)                      → { collection, loading, error, code, unavailable, reload }
+useLibraryItems(id, { q, tag, limit })        → { items, total, previewOnly, hasMore, loading, loadingMore, error, code, unavailable, loadMore, reload }
+useLibraryRows(id, { q, filters, limit })     → { rows, total, previewOnly, hasMore, loading, loadingMore, error, code, unavailable, loadMore, reload }
+useLibraryItem(id)                            → { item, fileUrl, textExcerpt, loading, error, code, unavailable, reload }
+useAgentThread({ row, how, job, key, view })  → { sessionId, state, needs, turns, view, pending, place, request, sending, loading, error,
+                                                  code, unavailable, send, stop, answer({ optionId, text } | { answers }), openOnDesk, newChat,
+                                                  openSession(sessionId), reload }   (the agent-chat block)
+useAgentPane({ row, how, job, key })          → useAgentThread with the desk sidebar's view, plus { chats: { items, loading, error, unavailable },
+                                                  callDetail(callId), openRequest(id) }   (the agent-pane block, D27; GET _claw/threads/<session>?view=1)
+useThreadList({ every = 30000 })              → { items: [{ sessionId, requestId, title, mark, at }], loading, error, unavailable, reload }   (the pane's Chats list)
 jobFromRequest(request)                       → what useJob shows for one request (pure; for tests)
+
+// The kit (0.8.1): each also returns { loading, error, code, unavailable, reload }
+useJobs({ every = 30000 })                    → { jobs, app, budget, credits, may, busy, appBusy, runNow(id), setEnabled(id, on), pause(), resume() }
+useRuns({ job, limit = 20, every = 30000 })   → { runs, overview }                       every 5 s while a run is going
+useRun(id)                                    → { run, steps, text, needs }              every 2.5 s while it runs; nothing without an id
+useNeedsYou({ every = 8000 })                 → { items: [{ id, request, kind, text, title, at, via, options, free, needsAt }], working, open(item), answer(item, { optionId, text }), takeBack(item), stop(request) }
+useApproval(requestId)                        → { approval, state, always, fallback, frame: { src, ref, title }, height }   (the approval block; GET _claw/requests/<id>/approval)
+useActivity({ row, surface, since, limit = 50, agent = false, every = 20000 })
+                                              → { rows }                                 agent: true keeps the agent's lines
+useConnections({ every })                     → { connections, connecting, connect(key) → { opened: "desk" | "tab" | false, error? } }
+useAgentKit()                                 → { skills: [{ name, title, when, from: "app" | "added", installed }], tools: [{ name, description }] }
+useLlmAction({ input, system, schema, tier, task, maxTokens, estimate = true })
+                                              → { estimate: { credits, credits_max } | null, estimating, run(), result, loading, error, unavailable, reset() }
+needsYouItem(request) · agentKitOf(data) · connectAccount(key)   the kit hooks' pure parts (for tests)
+
+// The automations engine (lib/automations.js, re-exported here): an app's own automations, from its own page
+useAutomations({ every = 30000 })             → { automations, busy, creating, setStatus(id, on), create(definition, { note, goLive }) }   every 5 s while one runs
+useAutomation(id)                             → { automation, live, draft, definition, versions, estimate, estimateDraft, runs, busy: "save" | "keep" | "live" | "test" | null,
+                                                  save(definition), keep(), setLive(on), test(inputs) }   resolve the platform's answer; a refusal carries `problems`
+useAutomationRun(runId)                       → { run, steps, stepsVisible, automation, definition, detail }   every 2.5 s while it runs
 ```
 
+The kit's hooks poll only while the page is shown (not behind the
+window's other tabs, not in a hidden browser tab; coming back looks at
+once), look once a minute while their door is missing, abort on unmount
+and never throw. A missing door is `unavailable` with `error` null: a
+quiet "not connected yet". `useJobs`' Run now makes every `useRuns`,
+`useRequests` and `useNeedsYou` on the page look at once. `useActivity`
+here is the kit's: polled, with `row` and `agent`; `lib/door.js`'s
+`useActivity` (§5 Door) reads the same lines once.
+
 `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);
@@ -1408,10 +1682,11 @@ 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 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.
+Up to 0.8.1 this said there was no chat or runs hook, because the OS
+drew those tabs. Since the kit there are both, and the blocks that draw
+them: a record's history beside the record is the `activity-log` block
+over `useActivity({ row })`; on the server in a server app it is
+`loadActivity`.
 
 ### Commissioning work — `useJob()`
 
@@ -1568,6 +1843,92 @@ if (!r.ok) setError(r.error);                  // r.code: needs_answer, queue_fu
 It resolves once the platform took the ask (`{ ok: true, data: {
 request, desk_origin } }`) or refused it; it never waits for the work.
 
+### The agent and AI kit — blocks (0.8.1)
+
+The app shows its agent's work and its AI features itself, in its own
+look: a chat beside the record, the schedule and its runs, what waits on
+the member, the price before a press. Up to 0.8.1 the OS drew most of
+this as the window's tabs, so every app looked the same; now the same
+look lives in these blocks, and the tabs stay as the full history. Each
+block is `makersclaw add <name>`, reads nothing itself, and takes the
+hook's answer as props (a block never imports `lib/`):
+
+- `agent-chat` (`AgentChat`) — the app's own chat with its agent, about
+  the app or one record. `useAgentThread`.
+- `ask-bar` (`AskBar`) — one line to ask, with chips; it starts the
+  thread and opens the chat. `useAgentThread`.
+- `needs-you` (`NeedsYou`, `QuestionBox`, `WaitingYes`, `AgentWorking`) —
+  what waits on this member (a question answered in place, a yes through
+  the `approval` block), the frozen "Ready to send" with Take back, the
+  working strip with Stop. `useNeedsYou`.
+- `approval` (`Approval`) — the yes, given in the app: the app's own card
+  (what goes out, to whom, the cost) over a Makersclaw-held press frame in
+  the app's theme that app code cannot script, with "Always allow this
+  kind". `useApproval`.
+- `activity-log` (`ActivityLog`) — who did what, newest first, the
+  agent as an author; with `row`, one record's timeline. `useActivity`.
+- `agent-marks` (`AgentMark`, `CallMark`, `Byline`) — the agent's mark,
+  a model call's mark, "By the agent, on Priya's ask". No hook.
+- `schedule-card` (`ScheduleCard`) — one job: its schedule in words, its
+  last run, next run, Run now with its price, the on/off switch.
+  `useJobs`.
+- `run-history` (`RunHistory`, `RunAccount`, `RunOverview`) — the runs,
+  one run's account, the overview against the week's cap. `useRuns`,
+  `useRun`.
+- `workflow-view` (`WorkflowView`) — the job as a graph: Trigger → steps
+  → result, the run picker, Live, Trigger manually, its runs beside.
+  `useJobs`, `useRuns`, `useRun`.
+- `suggestion` (`FieldSuggestion`, `InlineSuggestion`, `TextSuggestion`,
+  `Pencil`, `SuggestionGroup`, `Looking`) — a value the agent proposes,
+  in pencil until kept. No hook: Keep and Drop call the app's declared
+  actions (`runAction`).
+- `source-receipt` (`SourceReceipt`) — where a value came from, as a
+  clipping. No hook: the source is app data.
+- `agent-column` — a column the agent fills, each answer with its state,
+  how sure it is, and its receipt. The app's rows (`lib/data.js`).
+- `record-grid` — a virtualised grid of many records. The app's rows
+  (`lib/data.js`).
+- `ai-action` (`AiAction`) — one model call on what the screen holds,
+  its price on the button, the answer in place with Use. `useLlmAction`.
+- `cost` (`CostTag`, `CostConfirm`, `Allowance`) — the price on a
+  control, the confirm before a big spend, the week's allowance.
+  `useLlmAction`'s estimate, `useJobs`' budget.
+- `agent-changes` (`AgentChanges`) — the receipt of one ask, with Undo
+  this ask. `useActivity({ agent: true, since })`.
+- `connect-card` (`ConnectCard`, `ConnectRow`) — the app's accounts,
+  live or not, Connect. `useConnections`.
+- `agent-kit` (`AgentKit`) — what the agent knows and what it can do.
+  `useAgentKit`.
+- `library-shelf` (`LibraryShelf`) — "Start from a template": a Library
+  collection's items. `useLibraryItems`.
+
+The rules:
+
+1. **Use the kit.** Never redraw a chat, a schedule, a run list, a
+   needs-you queue, a suggestion or a price tag by hand: the block is
+   the one look every app shares, and it grows in the template.
+2. **The sign-in and money stay on the desk; the yes is the press
+   frame's.** The agent's question is answered in the app (`QuestionBox`,
+   `answer`). The agent's yes is the `approval` block: you draw what goes
+   out, the frame holds the press, and when it cannot load the block falls
+   back to "Waiting for your yes on the desk" and opens it
+   (`openRequest`). Connect opens the desk's connections panel; topping up
+   opens the desk. Never an Approve, Yes or Send of your own that gives
+   the yes, a password field or a payment form in the app.
+3. **Cost on every control that spends.** Run now, Read now, Enrich,
+   Summarize: the price is on the button (`CostTag`, `useLlmAction`'s
+   estimate) before the press, and a big spend asks first
+   (`CostConfirm`).
+4. **The door decides who may press.** `useJobs().may` says who may run,
+   switch and pause; hide what the member may not press. The door
+   refuses it anyway.
+5. **A missing door is quiet.** On a claw from before a door the hook is
+   `unavailable`: the block shows its empty state ("No runs yet", "Not
+   set up"), never an error.
+6. **Its own width decides its layout.** Every kit block lays itself out
+   by `@container`, at 320, 368, 800 and 1280 px of its own width; give
+   it the width, never a viewport breakpoint of yours.
+
 ### Calling a model — `llm()`
 
 `llm()` is for one-shot text work on what is on screen: sort these
@@ -1760,6 +2121,228 @@ What to keep in mind:
   they handle what a bare `fetch` would not (a claw without the door, a
   dropped network, an abort).
 
+### Showing the Library — `library`
+
+The Library is what Makersclaw keeps for every workspace: **collections of
+files** (pitch decks, PDFs, HTML website templates, graphics) and
+**collections of rows** (a dataset: a list of investors, growth
+examples). Members browse it in the Library window on the desk. An app
+can show the same content inside a screen, read live from the platform.
+
+Use it when the app **shows examples, templates or a dataset that
+Makersclaw keeps**: a gallery of pitch decks, a picker of website
+templates to start from, a table of investors to choose from. The screen
+asks the Library when it opens, so what it shows is what the Library
+holds today.
+
+Not for:
+
+- **The app's own data.** That is your tables (§5, Your tables) and the
+  company brain. The Library is Makersclaw's, the same for every
+  workspace; nothing a member does in the app is written to it.
+- **Sample rows for an empty screen.** Examples of your own app's data
+  are `useFixture` (§3a), never the Library.
+- **Copying into the workspace.** The Library is read only: the door has
+  no write. A member who wants a collection's rows in their company
+  data, or a file in their Files, asks the agent, which has the Library's
+  tools and records the copy:
+
+```js
+import { ask } from "../lib/platform";
+
+ask({ text: `Copy the "${collection.title}" list into our company data`, how: `The Library collection is "${collection.slug}".` });
+```
+
+#### Reading it
+
+```js
+import { library } from "../lib/platform";
+
+library.collections({ q, shelf })                  → data { collections: [card] }
+library.collection(id)                             → data { collection }
+library.items(id, { q, tag, cursor, limit })       → data { items, next_cursor, total, preview_only }
+library.rows(id, { q, filters, cursor, limit })    → data { rows, next_cursor, total, preview_only }
+library.item(id)                                   → data { item, file_url?, text_excerpt? }
+```
+
+Each resolves `{ ok, status, data }` or `{ ok: false, status, error,
+unavailable, code }` like `me`, and never throws. A collection's `id` is
+its slug (`"pitch-decks"`) or its uuid; an item's is its uuid. An id that
+names nothing asks nothing of the platform. Every call takes `signal`
+among its options.
+
+- `shelf` is one of `decks`, `websites`, `designs`, `documents`,
+  `datasets`, `examples`. `q` is a search. A card is `{ id, slug, title,
+  blurb, kind: "files" | "rows", shelf, tags, access: "free" | "paid",
+  status, public_page, cover_url, item_count, row_count, usable,
+  preview_only }`; `collection` adds `body`, `columns`, `source`,
+  `licence`, `preview_count`, `personal_data`, `published_at`.
+- **Items** (a files collection): `{ id, title, description, tags,
+  format, mime, bytes, preview_url, source_url, licence, position,
+  locked }`. `format` is `pdf`, `image`, `html`, `slides`, `document`,
+  `sheet`, `archive` or `other`. `tag` narrows by a tag. `limit` is a
+  whole number: 30 items a page unless you say, and more than 60 is cut
+  to 60.
+- **Rows** (a rows collection): `{ id, data, source_url }`. `data` is
+  keyed by the collection's `columns` (`{ key, label, type, filter, … }`;
+  `type` is `text`, `long_text`, `number`, `url`, `email`, `image`,
+  `tags` or `date`). `filters` is `{ <column key>: value }` for the
+  columns with `filter: true`, an exact match (for a `tags` column, rows
+  that have the tag); any other column is refused in words. `limit`: 50
+  rows a page unless you say, and more than 100 is cut to 100.
+  `source_url` is where the row
+  was found: show it beside a person, an investor or a figure.
+- **Paging.** A page with more answers `next_cursor`: pass it back as
+  `cursor`. Take it as given; do not read or build one.
+- `item(id)` is the item whole: its file's signed address as `file_url`
+  and the first 4,000 characters of its text as `text_excerpt` (the
+  start of a PDF's words, an HTML page's source).
+
+The hooks read once, when the screen opens or an argument changes, and
+page for you:
+
+```js
+useLibraryCollections({ q, shelf })          → { collections, loading, error, code, unavailable, reload }
+useLibraryCollection(id)                     → { collection, loading, error, code, unavailable, reload }
+useLibraryItems(id, { q, tag, limit })       → { items, total, previewOnly, hasMore, loading, loadingMore, error, code, unavailable, loadMore, reload }
+useLibraryRows(id, { q, filters, limit })    → { rows, total, previewOnly, hasMore, loading, loadingMore, error, code, unavailable, loadMore, reload }
+useLibraryItem(id)                           → { item, fileUrl, textExcerpt, loading, error, code, unavailable, reload }
+```
+
+`items` and `rows` hold the pages read so far; `loadMore()` reads the
+next and adds it (`hasMore` says there is one; it does nothing while a
+page is out). A new `id`, `q`, `tag`, `filters` or `limit` starts the
+list over, showing `loading` and no rows, never the last list: type-ahead
+should wait for a pause before it changes `q`. Nothing is read until
+there is an `id` (and `enabled: false` reads nothing). `unavailable` and
+`error` are never both set: `unavailable` is a claw from before the door
+or no network (show the quiet "not connected yet"), `error` is the
+platform's words and `code` its code when it named one.
+
+```jsx
+"use client";
+import { Badge, Button, Card, Empty, Image, Notice } from "../components/ui";
+import { useLibraryItems } from "../lib/hooks";
+
+export default function Decks() {
+  const { items, total, previewOnly, hasMore, loadMore, loading, loadingMore, error, unavailable } =
+    useLibraryItems("pitch-decks", { limit: 24 });
+  if (unavailable) return <p className="text-sm text-muted-foreground">The Library is not connected yet.</p>;
+  if (error) return <Notice tone="danger">{error}</Notice>;
+  if (!loading && !items.length) return <Empty title="No decks yet" body="Nothing in this collection matches." />;
+  return (
+    <div className="grid gap-4">
+      <div className="grid grid-cols-2 gap-4 lg:grid-cols-4">
+        {items.map((item) => (
+          <Card key={item.id} padding="sm" className="grid gap-2">
+            <Image src={item.preview_url} alt="" ratio="photo" />
+            <p className="text-sm font-medium">{item.title}</p>
+            <Badge>{item.format}</Badge>
+          </Card>
+        ))}
+      </div>
+      {previewOnly && total > items.length ? <Notice>{total - items.length} more come with a paid plan.</Notice> : null}
+      {hasMore ? <Button loading={loadingMore} onClick={loadMore}>Show more</Button> : null}
+    </div>
+  );
+}
+```
+
+#### A paid collection on a Free plan
+
+A collection with `access: "paid"` is for paid workspaces. On a Free plan
+it is a **preview**, not a refusal: the card says `usable: false` and
+`preview_only: true`, and `items` or `rows` answer only the first
+`preview_count` of them (a search or a filter runs over those), with
+`preview_only: true` and the **true** `total`. `total` minus what you
+hold is what "comes with a paid plan". The items past the preview are
+not in the list (the item's `locked` flag is for such an item, and a
+list of a preview carries only the preview's, so it reads `false`
+there); asking for one by its id, `library.item(id)`, is a 403 with
+`code: "needs_plan"` and the platform's words ("This collection comes
+with a paid plan."): show them, and stop. The Library window on the desk
+has the Upgrade button; an app has none to offer. On a paid plan the
+same calls answer the whole collection.
+
+#### Files
+
+- **`file_url` is a signed address, good for ten minutes.** Show or
+  download from it when the member asks, and never keep it: not in a row,
+  not in `localStorage`, not in a link that outlives the screen. A new
+  `library.item(id)` (or `reload()`) signs another. Row cells of type
+  `image` are signed the same way, so a table of rows with pictures that
+  stays open should read its page again now and then.
+- **`preview_url` and `cover_url` are plain pictures** that stay: use
+  them in `Image` for a card or a thumbnail. A row's image is not one;
+  it is a signed address.
+- A PDF opens in a new tab (`<Button href={fileUrl} target="_blank"
+  rel="noreferrer">`); an image is an `Image` of `fileUrl`; the other
+  formats are a download link.
+- **An `html` item (a website template) is shown only in a sandboxed
+  frame, never in the app's own page.** Read its file as text and give
+  it to an `iframe` as `srcDoc` with `sandbox="allow-scripts"`, so its
+  own scripts run. **Never add `allow-same-origin`**: with it the
+  template's scripts run as your app, with the member's session and
+  every `_claw` door. Never `dangerouslySetInnerHTML`, never
+  `iframe src={fileUrl}`, and never your own origin: Makersclaw does not
+  serve these files from it either.
+
+```jsx
+"use client";
+import { useEffect, useState } from "react";
+import { Notice, Spinner } from "../components/ui";
+import { useLibraryItem } from "../lib/hooks";
+
+export default function TemplatePreview({ id }) {
+  const { item, fileUrl, code, error, unavailable } = useLibraryItem(id);
+  const [html, setHtml] = useState(null);
+  const [failed, setFailed] = useState(false);
+  useEffect(() => {
+    if (!fileUrl) return undefined;
+    const controller = new AbortController();
+    fetch(fileUrl, { signal: controller.signal })
+      .then((res) => (res.ok ? res.text() : Promise.reject(new Error("no file"))))
+      .then(setHtml)
+      .catch(() => {
+        if (!controller.signal.aborted) setFailed(true);
+      });
+    return () => controller.abort();
+  }, [fileUrl]);
+  if (unavailable) return <p className="text-sm text-muted-foreground">The Library is not connected yet.</p>;
+  if (error) return <Notice tone={code === "needs_plan" ? "info" : "danger"}>{error}</Notice>;
+  if (failed) return <Notice tone="danger">This template did not open. Try again.</Notice>;
+  if (html === null) return <Spinner />;
+  return <iframe title={item.title} srcDoc={html} sandbox="allow-scripts" className="h-96 w-full rounded-md border border-border" />;
+}
+```
+
+#### What to keep in mind
+
+- **Browser only, in both modes.** The read rides the member's session:
+  `library` and the hooks run in a `"use client"` file. A server
+  component or a server action has no member and cannot call it.
+- **Never by its path.** A string naming `_claw/library` fails `npm run
+  check` (§6, `library`): the functions handle a claw without the door, a
+  dropped network and an abort, which a bare `fetch` does not.
+- **A claw from before the door** answers a 404 that names no refusal:
+  `unavailable: true`, from every call and every hook. A collection or
+  item that is not there (or is a draft the member cannot see) is a 404
+  that names its code, so `unavailable` stays false and `error` says so.
+  Show a missing door as "not connected yet", and a missing collection as
+  "not found".
+- **Show where it came from.** An item's `licence` and `source_url`, a
+  row's `source_url` and a collection's `source` are in the answer for a
+  reason: print them where the content is shown.
+- **A rows collection can list people** (`personal_data: true`). It is
+  shown to the member who has the app open. Do not copy it anywhere
+  yourself: no `insertRow` of its rows, no export, no sending it to your
+  own server. Using it in the company's data is a copy through the
+  agent.
+- **The platform notes that the app showed a collection**, once a day
+  per app and collection.
+- **Read it when the screen needs it.** Not on every keystroke, and not
+  in a loop over every collection: a shelf is one `collections` call.
+
 ### Activity — the contract
 
 `claw_app.activity` is how the founder sees the work. It is the
@@ -1840,6 +2423,8 @@ ok    tables     its own schema (makersclaw.json): every table named bare, and e
 ok    brain      no brain block in makersclaw.json; no lib/brain.js call names a kind
 ok    viewport   nothing in the app sizes itself by the window
 ok    llm        no screen names _claw/llm: a model is called through llm() or useLlm() (README §5)
+ok    library    no screen names _claw/library: the Library is read through library() or its hooks (README §5)
+ok    actions    no actions declared in makersclaw.json: the app's agent writes as references/actions.md says
 ok    smoke      built in 41s · / → 307 · /s/drafts 200 · /s/sent 200 (0.6s)
 all clear
 ```
@@ -1851,6 +2436,16 @@ ok    browser    files and a door: 2 client surfaces; no server code, route, pro
 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)
 ```
 
+`actions` holds `makersclaw.json` `actions` to the platform's rules
+(§5, Declared actions) and, once any is declared, refuses every write a
+screen makes that is not one.
+
+`automations` runs `makersclaw.json` `automations` (§5, Shipped
+automations) through the platform's own validator, one line per problem
+(its place, then what is wrong; at most 8, then "and N more"). It reads
+two copies of claw's format kept in `check/` and is skipped, not failed,
+on a node older than 22.18 (it cannot read them).
+
 `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`. `viewport` refuses anything in your code that
@@ -1966,6 +2561,14 @@ are the door too). A path built from pieces or held in a variable is not
 read here, as for rule 8. A longer name (`_claw/llm-notes`) is another
 route, and a comment or text in JSX is not a string of code.
 
+`library` is the same rule for the Library's door: no string in the code
+names `_claw/library`, and none handed to `claw()`, `clawUrl()` or
+`clawStream()` starts `library`. The Library is read with `library` from
+`lib/platform.js` or the `useLibrary…` hooks (§5, Showing the Library),
+which handle a claw without the door, a dropped network, an id that
+names nothing and an abort. It reads every app, in both modes, and the
+path as a browser reads it (`claw("./library/items")` is the door too).
+
 `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"`