makersclaw 0.7.0 → 0.8.0

package/templates/next/files/README.md

@@ -60,7 +60,7 @@ leaves out four (Per mode, below). Which to build: §4.
 Yours — write and rewrite freely:
 
 ```
-app/shell.jsx          the inside of the window: nav, layout, type, density
+app/shell.jsx          the inside of the window: nav, layout, type, density — an AppLayout (§3b, Layouts)
 app/DESIGN.md          the design, written before the code (§3)
 surfaces/<key>.jsx     one file per domain surface
 surfaces.js            the manifest entries (import + component when built)
@@ -78,7 +78,7 @@ app/page.jsx           / → the home surface (or "No surfaces yet" while the ma
 app/s/[key]/page.jsx   renders the surface with that key; planned ones say so
 app/error.jsx, app/global-error.jsx, app/not-found.jsx, app/error-relay.jsx, app/auto-refresh.jsx,
 app/escape-relay.jsx, app/frame.js, app/claw-alive/route.js   the app inside its window: refresh while shown (a surface opts out, §7), Escape from the desk
-components/ui/         the kit: Button, Field, Input, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction… (§3b, §3c)
+components/ui/         the kit: AppLayout, DocumentLayout, Button, Field, Input, Select, Sheet, Tabs, Menu, Notice, Icon, Depiction… (§3b, §3c)
 components/parts/      the parts: RecordSwitcher, LiveEmpty + LiveWork, useFixture + FixtureNotice (§3a, §3b)
 check/pins.json        the fixed files by hash; `npm run check` refuses one that differs
 check/                 `npm run check` (§6)
@@ -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, useArtifact… (Hooks)
+lib/hooks.js           the React hooks over them: useJob, useLlm, useArtifact… (Hooks)
 lib/sample.js          markSample, for sample rows (§3a)
 ```
 
@@ -147,7 +147,12 @@ Before any code, write `app/DESIGN.md` — one screen of text:
 - Type: scale and weight within the workspace's faces (`font-sans`,
   `font-mono`, `font-display`). Numbers tabular (`data-nums` on the element).
 - Layout and nav: where the surfaces live, what the home surface shows in
-  the first second.
+  the first second. Who scrolls: the shell is an `AppLayout` (§3b,
+  Layouts), the one owner of the window's height; say for each surface
+  whether its content scrolls (a list, an article) or fills (a canvas, a
+  grid that scrolls itself), whether it has an inspector and how wide,
+  and what sits in a footer that must stay in view. Decide it before
+  the shell, not after a long page has pushed a button out of reach.
 - Density, empty states (§3a: what each surface says while its table is
   empty), error states.
 - What makes this app look like ITS domain and not another.
@@ -159,7 +164,8 @@ to design: Agent, Runs and Activity are tabs the OS draws on the window,
 and the app's settings — model, prompt, skills, connections, schedule —
 are the window's Settings tab, the same for every artifact. The keys
 `agent`, `runs` and `activity` are reserved; a surface may not take one.
-The starter `app/shell.jsx` is a placeholder; replace it first.
+The starter `app/shell.jsx` is a placeholder; replace it first, and
+keep it an `AppLayout`.
 
 What the OS does **not** own is asking the agent for something. Those
 tabs are where the founder goes to look back; the app is where they set
@@ -256,12 +262,64 @@ import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGr
          Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption,
          Spinner, Skeleton, Progress, Separator, Kbd, KbdGroup, AspectRatio,
          Stat, StatGroup, Delta, StatusDot, Legend, Meter, Distribution, Swatch, Steps,
-         toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx }
+         toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx,
+         AppLayout, DocumentLayout }
   from "../components/ui";           // "./ui" from a component
 import { RecordSwitcher, LiveEmpty, LiveWork, liveWords, useFixture, FixtureNotice, isSample,
          Examples, useExamples } from "../components/parts";
 ```
 
+- **Layouts** — who owns the window's height, and who scrolls. Every
+  design-first build of 2026-10-07 shipped a shell of `min-h-dvh` that
+  grew with its content: no pane scrolled on its own, and a footer or a
+  button after a long article sat past the end of the window, where
+  nothing could reach it. So the kit owns the window, once, and `npm
+  run check` refuses anything else that sizes by it (`viewport`, §6).
+
+  `AppLayout` is the app frame and the one viewport owner: the
+  outermost one is exactly the window's height; one inside another
+  fills the slot it is in instead, so there is never a second owner.
+  The shell is one. Slots and props:
+  `header` (the top bar, in view; it draws its own bottom border) ·
+  `navigation` (a rail from 768px, `navigationWidth` px, 176 by default;
+  below 768px a Sheet behind the menu button, titled `navigationLabel`;
+  a press on a link closes it) · `children`, the content, with
+  `contentMode` `scroll` (the default: its region scrolls) or `fill` (a
+  bounded column whose child scrolls itself: a canvas, a grid, a
+  spreadsheet), `contentLabel`, `contentClassName` (spacing and token
+  backgrounds only) and `scrollKey` (pass the route: when it changes the
+  content scrolls back to its top and the drawer closes) · `inspector`
+  (beside the content from `inspectorAt` md · lg · xl, lg by default;
+  `inspectorWidth` px, 360 by default, 240 to 560; `inspectorLabel`) ·
+  `footer` (under the content, in view) · `height` viewport · parent.
+  Below `inspectorAt` there is no room for two columns: in `scroll` mode
+  the content and the inspector share one scroll, the inspector after
+  the content, so everything is reachable and nothing hides behind a
+  button; in `fill` mode the inspector is a bounded pane under the
+  content (at most 45% of the height) that scrolls on its own. A
+  surface that needs an inspector or a fill of its own returns an
+  `AppLayout` as its outermost element; inside the shell it fills the
+  content edge to edge (the content's padding drops for it):
+  ```jsx
+  <AppLayout
+    header={<EditorBar draft={draft} />}
+    inspector={<ReviewPanel notes={notes} />}
+    inspectorWidth={440}
+    footer={<SaveState saved={saved} />}
+    contentClassName="p-6"
+    contentLabel="Draft"
+  >
+    <DraftText draft={draft} />
+  </AppLayout>
+  ```
+  `DocumentLayout` is a page that flows, for print and export: no
+  height of its own, it sits in the content and the content scrolls it.
+  `toolbar` (held at the top, never printed), `width` prose · page (A4)
+  · letter · full, `paper` (a sheet on screen, plain in print), `align`
+  start · center, `label`. In print the frame lets go (no bound, no
+  navigation, header, inspector or footer) and the document flows onto
+  pages. Inside either, bound a box by its parent (`h-full`, `flex-1
+  min-h-0`) or by a size (`max-h-96`, `ScrollArea`), never by the window.
 - `Button` — `variant` primary (one per surface, in the app's accent —
   say it: a Button with no `variant` is secondary) · secondary · quiet ·
   danger · link (inline text: no padding or height, wraps and truncates
@@ -1274,6 +1332,8 @@ import { platform } from "../lib/platform";   // or the named functions
 platform.me()                                          GET  _claw/me       → { artifact: { id, name, vehicle, status, home }, user: { id, email }, blueprint, desk_origin }
 platform.ask({ text, row, how, job, list, surface, sessionId, open })
                                                        POST _claw/ask      → { ok, request, desk_origin }, and the column opens on it
+platform.llm(input, { system, schema, maxTokens, tier, task, signal })
+                                                       POST _claw/llm      → { ok: true, text } | { ok: true, data } | { ok: false, error, code }  (Calling a model)
 platform.requests()                                    GET  _claw/requests → { requests, run, desk_origin }
 platform.requests({ id })                              GET  _claw/requests?id=<id> → { request }
 platform.stopRequest(id)                               POST _claw/requests/<id>/stop → { ok, request }
@@ -1297,13 +1357,16 @@ didnt_finish. `line` is the one line every screen shows for it
 show it as it is, never a status word of your own. `app_session_id` is
 set only on your own requests.
 
-Named exports: `me, ask, requests, stopRequest, openRequest,
+Named exports: `me, ask, llm, requests, stopRequest, openRequest,
 surfaceOfPath, startJob, cancelJob, reportError, platform`. That is the
 whole list. Note what is **not** there: the runs, the chat history, Run
 now, Pause / Resume. Those are MONITORING and they are the OS's — the
 window's tabs and title bar — so an app never calls `_claw/agent`,
 `_claw/runs`, `_claw/run`, `_claw/pause` or `_claw/resume`. Asking is the
 opposite thing, and it belongs here (`ask()` and `useJob`, below).
+`llm()` is neither: one call to a model, answered in the page (Calling a
+model, below). It is the one wrapper that resolves the platform's answer
+as it is, `{ ok: true, text }` and not `{ ok: true, status, data }`.
 `requests` is not monitoring either: it is this app's asks in flight, so
 an empty surface can show the work coming (§3a). `startJob` and
 `cancelJob` are the 0.3.x door to the same work, kept so `useJob` can
@@ -1316,8 +1379,8 @@ that exact origin — never `"*"` — and only while the app is framed.
 
 ### Hooks — `lib/hooks.js` ("use client")
 
-Four hooks: a generic fetch over one `_claw` route, the app's identity,
-a job, and the app's requests. Each owns fetching, polling (while the
+Five hooks: a generic fetch over one `_claw` route, the app's identity,
+a job, the app's requests, and a model call. Each owns fetching, polling (while the
 tab is visible; once a minute while `unavailable`), streaming and cleanup
 on unmount. A surface renders what comes back and owns every pixel.
 
@@ -1328,6 +1391,7 @@ useJob()                                      → { running, status, queued, que
                                                   steps, text, progress, error, sessionId, requestId, request, finishedAt,
                                                   start, cancel, reset, open }
 useRequests({ surface, job, every = 5000 })   → { requests, live, run, loading, error, unavailable, reload, open, stop }
+useLlm()                                      → { run, loading, result, error, unavailable }   (Calling a model)
 jobFromRequest(request)                       → what useJob shows for one request (pure; for tests)
 ```
 
@@ -1504,6 +1568,198 @@ if (!r.ok) setError(r.error);                  // r.code: needs_answer, queue_fu
 It resolves once the platform took the ask (`{ ok: true, data: {
 request, desk_origin } }`) or refused it; it never waits for the work.
 
+### Calling a model — `llm()`
+
+`llm()` is for one-shot text work on what is on screen: sort these
+mails, draft this reply, translate this note, summarise this thread,
+pull the date out of this line. The answer comes back in the page, and
+the screen does what it likes with it.
+
+**`llm()` for one-shot text work on what the screen holds; `ask()` for
+work that needs tools, the workspace, or more than one step.** Finding
+leads, reading the Wiki, writing rows for forty threads, anything that
+should show in the agent column and the Requests list: that is `ask()`.
+The app's agent does it, with its tools. `llm()` has none: it sees the
+words you hand it and nothing else.
+
+```js
+"use client";
+import { updateRow } from "../lib/actions";
+import { llm } from "../lib/platform";
+
+// Text.
+const r = await llm(thread.body, {
+  system: "Draft a short, warm reply from the founder. Plain text, no greeting.",
+  task: "draft-reply",
+});
+if (r.ok) setDraft(r.text);                    // r.error says why not
+
+// Data: a schema in, an answer checked against it out.
+const SORT = {
+  type: "object",
+  required: ["label", "urgent"],
+  properties: { label: { enum: ["sales", "support", "billing", "other"] }, urgent: { type: "boolean" } },
+};
+const s = await llm(`From: ${mail.from}\nSubject: ${mail.subject}\n\n${mail.body}`, { system: "Sort this mail.", schema: SORT, task: "sort-mail" });
+if (s.ok) await updateRow({ source: "mail", id: mail.id, patch: { label: s.data.label, urgent: s.data.urgent } });
+```
+
+`data` is the model's JSON as it came: **a key your schema does not name
+is kept**. Read the keys you asked for, as above, and do not spread
+`data` into a row.
+
+`llm(input, opts)` takes:
+
+- `input` — what to work on: a string, or a conversation, `[{ role:
+  "user" | "assistant", content }]`: at most 100 messages, none empty,
+  the last one the user's (the one to answer). Required. An empty one
+  asks nothing of the platform and resolves `bad_input`.
+- `system` — how to go about it, at most 8,000 characters.
+- `schema` — a JSON Schema for the answer, an object, at most 16 KB
+  once written out. The answer then comes back as `data`, checked
+  against it, not as `text`. If the model's reply misses, the platform
+  sends it back once with what was wrong; a second miss is
+  `schema_mismatch`. The platform runs your schema on the model's words,
+  so what it may hold is bounded (below).
+- `maxTokens` — the answer's ceiling, a whole number, 1 or more. 1,024
+  unless you say; over 4,096 is cut to 4,096. (It travels as
+  `max_tokens`.)
+- `tier` — `"fast"` (the default) or `"smart"` for the harder job. An
+  app never names a model. `smart` costs more and is slower: a long
+  answer from it can run into the 60 second limit, so keep `maxTokens`
+  modest there.
+- `task` — a short label for the usage line, `a-z`, `0-9` and `-`, at
+  most 40 characters (`"sort-mail"`).
+- `signal` — an `AbortSignal`. An abort resolves `{ ok: false, aborted:
+  true }`.
+
+**What a schema may hold.** Write it out as a tree, small. The call
+refuses a schema with:
+
+- `pattern` or `patternProperties` (`bad_input`): a regular expression
+  run on a model's words can hang the platform. Use `enum`, `format` or
+  length bounds.
+- `$ref`, `$defs` or `definitions` (`bad_input`; `$dynamicRef` and
+  `$recursiveRef` too): each reference is checked in full where it is
+  used, so a few can mean a tree of any size. Write the shape out where
+  it is used.
+- nesting deeper than 20 levels, a list inside a list counted
+  (`bad_input`).
+- more than 1,000 parts (`too_large`): every object in it, every `enum`
+  value and every type listed in a `type` array. A real answer's schema
+  is a few dozen.
+- a schema it cannot read, such as a `type` it does not know
+  (`bad_input`).
+
+A reply with so many values that checking it against the schema would
+cost too much is a miss like any other (`schema_mismatch`, and the
+model is told why): ask for fewer values, or a smaller schema. Make the
+root an object (`type: "object"`): providers' structured answers mostly
+want one, and when one refuses the format the platform asks again in
+words alone, which is less sure. Everything else in JSON Schema is let
+through.
+
+It resolves, and never throws:
+
+- `{ ok: true, text }` — no schema.
+- `{ ok: true, data }` — with a schema.
+- `{ ok: false, error, code, status }` — a refusal, as the platform
+  sent it. Branch on `code`. **Show `error` as it is for the codes that
+  speak to the member, and a plain line of your own for the rest.** The
+  rest speak to you, the developer ("schema uses "pattern""), and a
+  member should not read them.
+
+  Words for the member, shown as they are:
+
+  - `no_credits` (402): the workspace's wallet is empty, the workspace
+    is suspended, or the Free plan's daily limit is used up.
+    `member_cap` (402): the member's monthly spend cap is used up.
+    `app_cap` (402): this app's weekly cap is used up. Say so and stop;
+    do not retry.
+  - `rate_limited` (429): 30 calls a minute per member. Wait a moment,
+    then again.
+  - `model_failed` (502), `try_again` (503) and `failed` (500): the
+    model, the membership check or the platform could not answer just
+    now. Try again.
+  - `timeout` (504): a call is held to 60 seconds, a schema retry
+    included, and one the clock cuts is still charged. Ask for less (a
+    lower `maxTokens`, a shorter input) rather than the same again.
+  - `no_member_identity` (401) and `not_a_member` (403): the page is not
+    running in a member's own session (`no_member_identity` says to open
+    the app from the desk again), or the member was removed from the
+    workspace.
+
+  Words for you, not shown:
+
+  - `bad_input` (400): the call itself is wrong; fix the code.
+  - `too_large` (413): the body is over 128 KB, `system` over 8,000
+    characters, `schema` over 16 KB or 1,000 parts, or `input` over 100
+    messages. Send less.
+  - `schema_mismatch` (422): the model could not fit the schema, twice;
+    `error` names where it missed. Loosen the schema or ask for less.
+  - `cross_origin` (403): not the app's own page (a typed URL, a form
+    post).
+  - `not_configured` (503): the platform has no model to give.
+- `{ ok: false, unavailable: true }` — the platform has no such door (a
+  claw from before it) or there is no network. Render the quiet "not
+  connected yet" of every `_claw` door, or leave the button out.
+
+`useLlm()` is the same call from a component: `{ run, loading, result,
+error, unavailable }`. `run(input, opts)` takes the same arguments and
+resolves the same answer; `result` is that answer when it was ok, `error`
+the refusal's words, and `unavailable` is true on a claw with no door (or
+no network), when `error` stays null: that is the quiet "not connected
+yet", not an alert, as for `useClaw`. A new run aborts the one before it,
+so a slow answer never lands over a newer one, and leaving the page
+aborts the call in flight. `error` is the sentence whatever the code, so
+a screen that must tell the money (`no_credits`, `member_cap`, `app_cap`)
+from the rest reads `code` from what `run()` resolves.
+
+```jsx
+"use client";
+import { Button, Notice } from "../components/ui";
+import { useLlm } from "../lib/hooks";
+
+export default function Translate({ note }) {
+  const { run, loading, result, error, unavailable } = useLlm();
+  if (unavailable) return <p className="text-sm text-muted-foreground">Translation is not connected yet.</p>;
+  return (
+    <div className="grid gap-2">
+      <Button loading={loading} onClick={() => run(`Translate to French:\n${note.text}`, { task: "translate" })}>
+        Translate
+      </Button>
+      {error ? <Notice tone="danger">{error}</Notice> : result ? <p className="text-sm">{result.text}</p> : null}
+    </div>
+  );
+}
+```
+
+What to keep in mind:
+
+- **Browser only, in both modes.** The call rides the member's session:
+  `llm()` and `useLlm()` run in a `"use client"` file. A server
+  component or a server action has no member to charge and cannot call
+  it.
+- **It spends the workspace's credits**, like any inference, and counts
+  against the member's monthly cap and the app's weekly cap. A schema
+  call the model misses is asked again once, and both are charged; so is
+  a call the 60 second clock cuts. Call it on a press, never on every
+  render or every keystroke, and never once per row of a long list: that
+  is a batch, and a batch is `ask()`'s.
+- **The answer is words, not markup.** Render `text` as text. Never put a
+  model's answer in `dangerouslySetInnerHTML`.
+- **The answer is not saved.** What matters goes into a row
+  (`updateRow`, `insertRow`) before the page closes.
+- **No streaming.** The answer arrives whole.
+- **Nothing appears on the desk.** No request, no thread, no run: the
+  agent column and the Requests list are `ask()`'s. The call is metered
+  to the member who made it; the usage line names the app, the tier and
+  the `task` label. Claw does not log the request or the reply.
+- **Never by its path.** A string naming `_claw/llm` fails
+  `npm run check` (§6, `llm`): the two functions are the contract, and
+  they handle what a bare `fetch` would not (a claw without the door, a
+  dropped network, an abort).
+
 ### Activity — the contract
 
 `claw_app.activity` is how the founder sees the work. It is the
@@ -1577,11 +1833,13 @@ ok    controls   every control is a kit part
 ok    examples   examples show only outside a workspace (useFixture); a workspace app opens empty
 ok    manifest   2 surfaces: drafts, sent
 ok    icons      every icon name exists
-ok    kit        70 fixed files match the template
+ok    kit        74 fixed files match the template
 ok    depictions 1 picture of elsewhere, framed on 1 surface: x-post
 ok    agent      no SQL write in app code; the agent's brief names every action with its call (1), every table written (2) and every server action that writes (0)
 ok    tables     its own schema (makersclaw.json): every table named bare, and each bare name one of the 2 its schema makes (../install/schema.sql); claw. and claw_app. are the platform's
 ok    brain      no brain block in makersclaw.json; no lib/brain.js call names a kind
+ok    viewport   nothing in the app sizes itself by the window
+ok    llm        no screen names _claw/llm: a model is called through llm() or useLlm() (README §5)
 ok    smoke      built in 41s · / → 307 · /s/drafts 200 · /s/sent 200 (0.6s)
 all clear
 ```
@@ -1595,7 +1853,13 @@ ok    smoke      built in 38s (copy at ~/.claw-check/app) · export 2.1 MB in 64
 
 `kit` refuses a fixed file that differs from the template (they are
 hashed in `check/pins.json`) and any file of yours under `components/ui`
-or `components/parts`. `depictions` reads both directions: nothing of
+or `components/parts`. `viewport` refuses anything in your code that
+sizes itself by the window: `min-h-dvh`, `min-h-screen`, `h-screen`,
+`h-dvh` (and their `svh`, `lvh` and `max-h-` kin), and any `vh` unit —
+`h-[80vh]`, `max-h-[60vh]`, `h-[calc(100vh-4rem)]`, `style={{ height:
+"100vh" }}`. The window has one owner, the kit's `AppLayout` (§3b,
+Layouts); a box inside it is bounded by its parent (`h-full`, `flex-1
+min-h-0`) or by a size (`max-h-96`). `depictions` reads both directions: nothing of
 the workspace inside a depiction (a token, `font-sans`, `dark:`, a rem
 utility), nothing of the depiction outside its frame (a named import, a
 picture in the shell or a `Card`, a dead file nobody renders).
@@ -1692,6 +1956,16 @@ kind has `kind`, `label`, `plural` and `fields`. A read's kind
 hands the app only what `reads` and `writes` name. A kind held in a
 variable is not read here; the door refuses it on the member's screen.
 
+`llm` reads every app, in both modes: no string in the code names
+`_claw/llm`, and none handed to `claw()`, `clawUrl()` or `clawStream()`
+starts `llm`. A model is called with `llm()` or `useLlm()` (§5, Calling a
+model), which handle a claw without the door, a dropped network and an
+abort; a `fetch` of the path handles none of them. The path is read as
+a browser reads it (`claw("//llm")`, `claw("./llm")` and `"/_claw/./llm"`
+are the door too). A path built from pieces or held in a variable is not
+read here, as for rule 8. A longer name (`_claw/llm-notes`) is another
+route, and a comment or text in JSX is not a string of code.
+
 `browser` reads a browser app only (`"mode": "browser"`): its pages are
 files built once, and everything they read or write goes through the
 platform's data door. So it refuses, file and line, a `"use server"`
@@ -1713,6 +1987,12 @@ page. That proves every page prerenders, not that a surface renders
 with data: the rows come in the browser. Then, by eye:
 
 - Renders at 360px, 768px and 1280px without horizontal scroll.
+- The page itself never scrolls: the shell is the window's height
+  (`AppLayout`), and each pane scrolls inside it. With the longest
+  content a surface can hold (a 30-page article, a 40-message thread,
+  a tall inspector), the last line and every button after it are
+  reachable, at 375px and at 1280px; the header and the footer stay in
+  view.
 - In a workspace, an empty table shows `LiveEmpty`: the work in flight,
   else what would be here and the manual way to add it — never an
   example (§3a). A saved row replaces it.

package/templates/next/files/app/shell.jsx

@@ -9,14 +9,26 @@
 // Activity; never repeat any of them. This shell is the App tab: the
 // domain surfaces and nothing else.
 //
-// Mobile first: this starter is one column with the surfaces as a strip
-// along the top, and grows a side rail from 640px. Start narrow, widen.
+// TWO THINGS TO KEEP when you replace it.
 //
-// ONE THING TO KEEP when you replace it: `next/link`. The app runs under
-// a base path and <Link> applies it; a plain <a href="/s/..."> resolves
-// against the origin instead and the click leaves the app, loading the
-// Makersclaw dashboard inside this frame. The page still answers 200, so
-// nothing catches it but a click (README §4).
+// 1. AppLayout (components/ui) as the outermost element. It is the one
+//    owner of the window's height: the shell is exactly the window, and
+//    the content scrolls inside it, so a footer, an inspector or a button
+//    after a long page stays reachable. Fill its slots — header,
+//    navigation, inspector, footer — and pick contentMode, but never
+//    size anything by the window yourself (min-h-dvh, h-screen, 100vh,
+//    h-[80vh]): `npm run check` refuses it (README §3b, Layouts). A
+//    surface that needs an inspector or a canvas of its own returns an
+//    AppLayout too; inside this one it fills the content, edge to edge.
+//
+// 2. `next/link`. The app runs under a base path and <Link> applies it; a
+//    plain <a href="/s/..."> resolves against the origin instead and the
+//    click leaves the app, loading the Makersclaw dashboard inside this
+//    frame. The page still answers 200, so nothing catches it but a click
+//    (README §4).
+//
+// Mobile first: below 768px the surfaces sit behind the menu button, in
+// a drawer; from 768px they are a rail beside the content.
 //
 // Props: name (the app's name — for aria labels, not for display),
 // surfaces (surfaceNav() from surfaces.js: { key, label, kind, source,
@@ -24,41 +36,46 @@
 
 import Link from "next/link";
 import { usePathname } from "next/navigation";
-import { cx } from "../components/ui";
+import { AppLayout, cx } from "../components/ui";
 
 export default function Shell({ name, surfaces, children }) {
   const pathname = usePathname() ?? "";
   const activeKey = decodeURIComponent(/^\/s\/([^/?#]+)/.exec(pathname)?.[1] ?? "");
+  const active = surfaces.find((s) => s.key === activeKey);
 
   return (
-    <div className="flex min-h-dvh flex-col bg-background text-foreground sm:flex-row">
-      <nav
-        aria-label={`${name} surfaces`}
-        className="shrink-0 overflow-x-auto border-b border-border p-2 sm:w-44 sm:overflow-visible sm:border-b-0 sm:border-r sm:p-3"
-      >
-        <ul className="flex gap-1 sm:flex-col">
-          {surfaces.map((s) => {
-            const active = s.key === activeKey;
-            return (
-              <li key={s.key} className="shrink-0">
-                <Link
-                  href={`/s/${encodeURIComponent(s.key)}`}
-                  aria-current={active ? "page" : undefined}
-                  className={cx(
-                    "flex min-h-9 items-center justify-between gap-2 rounded-md px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring",
-                    active ? "bg-accent text-accent-foreground" : "hover:bg-accent",
-                    !s.built && "text-muted-foreground",
-                  )}
-                >
-                  <span>{s.label}</span>
-                  {s.built ? null : <span className="text-2xs uppercase tracking-wide">planned</span>}
-                </Link>
-              </li>
-            );
-          })}
-        </ul>
-      </nav>
-      <main className="min-w-0 flex-1 p-4 sm:p-6">{children}</main>
-    </div>
+    <AppLayout
+      navigation={
+        <nav aria-label={`${name} surfaces`} className="p-2 md:p-3">
+          <ul className="flex flex-col gap-1">
+            {surfaces.map((s) => {
+              const current = s.key === activeKey;
+              return (
+                <li key={s.key}>
+                  <Link
+                    href={`/s/${encodeURIComponent(s.key)}`}
+                    aria-current={current ? "page" : undefined}
+                    className={cx(
+                      "flex min-h-9 items-center justify-between gap-2 rounded-md px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                      current ? "bg-accent text-accent-foreground" : "hover:bg-accent",
+                      !s.built && "text-muted-foreground",
+                    )}
+                  >
+                    <span>{s.label}</span>
+                    {s.built ? null : <span className="text-2xs uppercase tracking-wide">planned</span>}
+                  </Link>
+                </li>
+              );
+            })}
+          </ul>
+        </nav>
+      }
+      navigationLabel="Surfaces"
+      contentLabel={active?.label ?? name}
+      contentClassName="p-4 sm:p-6"
+      scrollKey={pathname}
+    >
+      {children}
+    </AppLayout>
   );
 }

package/templates/next/files/check/run.mjs

@@ -18,6 +18,10 @@
 // screen, long after the build (brain). Number 10 is browser mode's rule
 // (claw's STATIC-SPEC §3): a browser app is files and a door, and the
 // build refuses its server code late and unclearly, or not at all.
+// Number 12 is the shell that grew with its content: a footer and the
+// buttons after a long article sat past the window's end (viewport).
+// Number 13 (llm, 0.8.0) keeps a model call on llm(): a screen that
+// fetched the model door by its path got none of what the function does.
 //
 //   npm run check               source rules, then smoke
 //   npm run check -- --no-build source rules only: no build, no smoke
@@ -94,7 +98,7 @@ const ACTIONS_ONLY = process.argv.includes("--actions");
 // .jsx (a components/ui/depiction.js beside depiction.jsx won); Next 16's
 // Turbopack tries .jsx before .js (seen on 16.3.7), so the kit's own file
 // wins there, but the rule holds for every bundler.
-const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:radio|toggle|button-group|avatar|breadcrumb|pagination|button|collapsible|item|table|depiction|feedback|stat|distribution|swatch|steps|separator|scroll-area|field|icon|menu|context-menu|popover|calendar|date-picker|tooltip|notice|sheet|tabs|slider|input-group|image|file-input|input-otp|command|combobox|rating|toast|carousel|resizable)\.jsx|parts\/(?:index|sample)\.js|parts\/(?:fixture|record-switcher|live-work)\.jsx)$/;
+const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:radio|toggle|button-group|avatar|breadcrumb|pagination|button|collapsible|item|table|depiction|feedback|stat|distribution|swatch|steps|separator|scroll-area|layout|field|icon|menu|context-menu|popover|calendar|date-picker|tooltip|notice|sheet|tabs|slider|input-group|image|file-input|input-otp|command|combobox|rating|toast|carousel|resizable)\.jsx|parts\/(?:index|sample)\.js|parts\/(?:fixture|record-switcher|live-work)\.jsx)$/;
 
 // The pins: sha256 of every fixed file, written by `makersclaw init` and
 // `makersclaw add` (check/pins.json). Read first, because a BLOCK is
@@ -228,13 +232,20 @@ const COLOUR_PREFIXES = "bg|text|border(?:-[xytrbles])?|ring(?:-offset)?|inset-r
 
 /** Source without its comments, newlines kept so line numbers hold: a
  *  rule reads code, not the prose beside it (a header that says
- *  "window." or names <a> is not browser access or a link). */
-function stripComments(text) {
+ *  "window." or names <a> is not browser access or a link). A line comment
+ *  is a `//` that follows anything but a `:` or a backslash, which also
+ *  blanks a string that opens with two slashes ("//llm") or holds a
+ *  doubled one ("/_claw//llm") to the end of its line. `slashStrings`
+ *  reads those as strings: a `//` is a comment only at the start of a line
+ *  or after a space or one of ; , ( ) { } [ ]. For a rule that reads a
+ *  URL's slashes (12, llm). */
+function stripComments(text, { slashStrings = false } = {}) {
   const blank = (m) => m.replace(/[^\n]/g, " ");
+  const line = slashStrings ? /(^|[\s;,(){}[\]])\/\/[^\n]*/g : /(^|[^:\\])\/\/[^\n]*/g;
   return text
     .replace(/\{\/\*[\s\S]*?\*\/\}/g, blank)
     .replace(/\/\*[\s\S]*?\*\//g, blank)
-    .replace(/(^|[^:\\])\/\/[^\n]*/g, (m, lead) => lead + blank(m.slice(lead.length)));
+    .replace(line, (m, lead) => lead + blank(m.slice(lead.length)));
 }
 /** JSX attributes up to the tag's `>`: strings and balanced braces may hold a `>` or `=>`. */
 const ATTRS = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{])*`;
@@ -1871,6 +1882,67 @@ function columnFrom(code, at) {
   }
 }
 
+// 12. One viewport owner: the kit's AppLayout. Every design-first build
+//     of 2026-10-07 shipped a shell of min-h-dvh that grew with its
+//     content: the page scrolled, no pane scrolled on its own, and a
+//     footer or a button after a 30-page article sat past the end of the
+//     window, where nothing could reach it. So the app's code never sizes
+//     anything by the window: no min-h-dvh, min-h-screen, h-screen, h-dvh
+//     (nor their svh, lvh and max-h- kin), and no vh unit at all
+//     (h-[80vh], max-h-[60vh], h-[calc(100vh-4rem)], style={{ height:
+//     "100vh" }}). The kit is skipped: AppLayout in components/ui is the
+//     one place the window's height is written. Depictions are read too:
+//     a picture is drawn in px, never by the window.
+{
+  const L = limiter("viewport");
+  const DO =
+    'the window has one owner, AppLayout from components/ui (the shell\'s frame: the content scrolls inside it, contentMode="fill" for a canvas, an inspector beside it), and a page for print is DocumentLayout; inside it bound a box by its parent (h-full, flex-1 min-h-0) or by a size (max-h-96)';
+  scan(/(?<![\w-])(?:min-|max-)?h-(?:screen|dvh|svh|lvh)(?![\w-])/, (f, m, line) => L.hit(`${f.path}:${line}`, m[0], `${m[0]} sizes by the window, so what follows a long page cannot be reached; ${DO}`), files);
+  scan(/(?<![\w.])\d+(?:\.\d+)?[dsl]?vh(?![A-Za-z0-9_])/, (f, m, line) => {
+    // The whole class or value it sits in: h-[calc(100vh-4rem)], "100vh".
+    const from = f.code.slice(0, m.index).search(/[^\s"'`{}]*$/);
+    const token = f.code.slice(from).match(/^[^\s"'`{}]*/)[0];
+    L.hit(`${f.path}:${line}`, token, `${token} is a fraction of the window, so what follows it cannot be reached; ${DO}`);
+  }, files);
+  if (L.count > 4) fail("viewport", `${L.count - 4} more`, "more of the same: sizes taken from the window");
+  if (!L.count) ok("viewport", "nothing in the app sizes itself by the window");
+}
+
+// 13. A model is called through llm() (0.8.0, the platform's _claw/llm
+//     door). A screen that wants one answer from a model (sort, draft,
+//     translate) calls llm() from lib/platform.js, or useLlm() from
+//     lib/hooks.js, and never reaches the door by its URL: the path is the
+//     platform's to move, the two functions are the contract, and an
+//     app that fetches its own copy skips what they do (nothing throws, a
+//     claw from before the door comes back `unavailable`, an abort
+//     answers `aborted`). So no string in the app's code names `_claw/llm`,
+//     and none handed to claw(), clawUrl() or clawStream() starts `llm`.
+//     "Names" is as the browser reads it: clawUrl() drops every leading
+//     slash, and a `./` or a doubled slash in a URL is dropped on the way
+//     (`claw("//llm")`, `claw("./llm")`, `/_claw/./llm` all reach the door;
+//     it reads the code with `slashStrings` so a `//` inside a string is
+//     not taken for a comment). It reads literals, so a path built from
+//     pieces is not seen, as in rule 8. Every mode and every tables
+//     setting: the door is the same for all.
+{
+  const L = limiter("llm");
+  const LLM_PATH = /_claw\/(?:\.?\/)*llm(?![\w-])/;
+  const LLM_NAME = /^(?:\.?\/)*llm(?![\w-])/;
+  for (const f of jsFiles) {
+    const code = stripComments(f.text, { slashStrings: true });
+    const toClaw = new Set();
+    for (const m of code.matchAll(/(?<![\w$.])claw(?:Url|Stream)?\s*(?:\?\.\s*)?\(\s*(?=["'`])/g)) toClaw.add(m.index + m[0].length);
+    for (const { start, end } of literalsOf(code)) {
+      const inner = code.slice(start + 1, end);
+      if (!(LLM_PATH.test(inner) || (toClaw.has(start) && LLM_NAME.test(inner)))) continue;
+      const path = inner.replace(/\s+/g, " ").slice(0, 60);
+      L.hit(`${f.path}:${lineOf(code, start)}`, "path", `"${path}": the model door is reached through llm(input, { system, schema }) in lib/platform.js, or useLlm() in lib/hooks.js, never by its path (README §5, Calling a model)`);
+    }
+  }
+  if (L.count > 4) fail("llm", `${L.count - 4} more`, "strings that name the model door's path instead of calling llm()");
+  if (!L.count) ok("llm", "no screen names _claw/llm: a model is called through llm() or useLlm() (README §5)");
+}
+
 // 6. Smoke: the app, built and started, answers every surface.
 
 /** Newest mtime among the app's own sources (what a build reads): walk