@akanjs/cli 3.0.0-alpha.99 → 3.0.0-beta.1

package/guidelines/agentRule/agentRule.instruction.md

@@ -72,9 +72,22 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   fills whichever adaptor holds `LlmAdaptorRole`, reaching it as the `llmOption` use. The settings are the role's
   rather than one provider's, so they survive a swap. **DeepSeek is the built-in default** (`deepseek-v4-flash` at
   `https://api.deepseek.com`); with no `apiKey` the app still boots and the chat answers `llmUnavailable`. Swap
-  providers the way middleware is applied: `option.applyAdaptor(LlmAdaptorRole, ClaudeLlm)`, where the
-  implementation is an `adapt()` class in a `srvkit/` implementing `LlmAdaptor.chat(request, onDelta?)` — ignore
-  `onDelta` and the chat still answers whole.
+  providers the way middleware is applied: `option.applyAdaptor(LlmAdaptorRole, AnthropicLlm)`. An app may still
+  write its own — an `adapt()` class in a `srvkit/` implementing `LlmAdaptor.chat(request, onDelta?)`, where
+  ignoring `onDelta` still answers whole — but for vision it no longer has to.
+- **Three providers ship, and only two of them read a picture.** `DeepseekLlm` is the default and declares no
+  `accepts`, which is a fact about its API rather than a gap. `OpenaiLlm` speaks the same chat-completions dialect
+  — `OpenaiDialect`, shared between them so a protocol fix lands once — against `https://api.openai.com/v1` and
+  declares `{ image: true }`, sending an image as a content part. `AnthropicLlm` is the Messages API and declares
+  `{ image: true, document: true }`; it is its own file rather than a branch, because the system prompt is a field
+  and not a message, tool calls and results are content blocks, the results ride in a *user* turn, roles must
+  alternate — so two wire turns that map to one role are merged — and `max_tokens` is required. **Both new ones
+  require `model`**: a default would age into a 404, and worse, it would decide the vision claim for the app.
+- **`accepts` is answered per model, through `option.setLlm({ accepts })`.** An adaptor answers for an API and one
+  API serves models that differ, so the override rides beside the `model` it is a fact about. It is not a table
+  the framework keeps: a table is a claim about models that ship after it, and getting this wrong is the worst
+  failure available — a provider handed bytes it cannot decode either refuses the turn or accepts it having seen
+  nothing, and the model then answers confidently about a file it never read.
 - **An adaptor answers `null` for "not configured" and *throws* for a refusal it can explain.** The two are
   different things to be told: collapsing both into `null`, the way the adapter convention otherwise reads, left a
   user reading `llmUnavailable` — "no model is configured" — about a conversation that had merely outgrown the
@@ -92,15 +105,28 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   prompt. **What the provider cannot read is replaced by a note naming the file**, never dropped: an attachment the
   model never saw is one it answers about from the filename. An adaptor declares `accepts: { image, document }` and
   `AgentService.readable` degrades the rest, so a text-only provider needs no attachment code at all — DeepSeek
-  declares none, which is why an image against the default provider is refused out loud while an extracted PDF
-  works, `text` being readable by every model there is. **A `prompt()`'s `Msg.image` is the same wire shape** and
-  reaches the chat as an attachment rather than the literal `[image]` it used to become. Persisting keeps each
+  declares none, which is why an image against the *default* provider is refused out loud while an extracted PDF
+  works, `text` being readable by every model there is. Swap in `OpenaiLlm` or `AnthropicLlm` and the same image
+  arrives as an image. `accepts.document` is one boolean over every non-image type, so an adaptor whose API has a
+  block for only some of them — Anthropic's `document` is PDF and nothing else — names the rest in the text rather
+  than dropping them, which is the wire's own rule applied at the one layer that knows which blocks exist. Persisting keeps each
   attachment's name and drops its content: web storage is a few megabytes, one screenshot fills a chunk of it, and
   a save that fails is silent — so keeping the bytes would quietly stop keeping the transcript.
   **The ceilings are the message's, not the file's**: 4 MB per file, 8 MB and five files per message, and the same
   file twice is refused by name. The bytes ride inside one turn's JSON, so what a provider refuses is the sum —
   and a request that cannot be sent is one the user has to empty the composer to escape, which is why the refusal
-  happens at the paperclip and names the file it dropped.
+  happens at the paperclip and names the file it dropped. All three are defaults rather than the law —
+  `<Agent.Chat attachLimits={{ perFileBytes, perMessageBytes, perMessageCount }} />` — because what one request can
+  carry belongs to the configured provider and not to the framework. The per-file one is measured on **what the
+  reader produced**, not on the file that was picked: a reader that uploads and answers a `url` has already paid
+  what the ceiling exists for, so refusing its 6 MB photo would refuse it for a cost it does not incur. Only the
+  built-in path checks the source size, and there the file itself is the carrier.
+- **`MessageAttachment.ref` is the host's own handle on the file — carried, never read.** A file id, a storage key,
+  whatever turns the attachment back into something a tool can be handed. The framework only moves it: the model is
+  never shown one, and a tool the app publishes (`useFileFieldTool` below) is what spends it. Without it a host that
+  stores its uploads keeps a map beside the transcript keyed on name and size — the same guess `Attachment.same`
+  has to make, and the one that is wrong for two crops of one export. So when both sides carry a `ref`, it *is* the
+  answer to "the same file twice", and the heuristic is what is left for when they do not.
 - **Speech is one engine contract and the framework's own policy.** `<Agent.Chat voice={engine} />` takes a
   `VoiceEngine` — `listen(handlers)` and `speak(sentence)`, both cancellable — and the chat decides everything
   else: a press-to-talk microphone whose transcript lands in the composer to be corrected, one utterance per
@@ -131,6 +157,11 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   `data-agent-zone` container; guides follow the layout cascade (ancestors and own, never a sibling's). Zone
   membership is positional — there is no per-declaration zone key, so a lib component joins whatever zone the app
   mounts it in.
+- **Two agents' turns run in parallel; their tool calls take turns.** Tool execution is serialized across the
+  whole page, because `AgentAbort` and `AgentProgress` reach the running call through a module slot rather than a
+  parameter — two calls in flight restore each other's slot and the second one's progress goes nowhere. Only the
+  execution queues: a zone parked on an approval card holds nothing up, since waiting for the user sits outside
+  the queue, and a call that is aborted releases it.
 - **Everything a zone publishes is named `<id>.<name>`,** and that name is what instructions must use. A bare
   `createVideoProject` inside a zone naming its tool `videoProjectDraft.createVideoProject` is a tool that does
   not exist: the model calls it, the surface answers `Unknown tool`, and a turn is gone. Build the name from the
@@ -200,7 +231,12 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   globally and a component cannot build one per render: pass the list it has — a slice's sort keys, the options a
   prop carried — and it is published and enforced the same way. Neither reaches a set that fills in *after* the
   first render, since a declaration is mount-static; put that in the tool's `guard`, which is re-read per call and
-  can name the current values in its refusal. **An argument type nothing can describe — a model class, `Any`, a
+  can name the current values in its refusal. **One array level of either is describable too** —
+  `.arg("bodies", [String])`, `.opt("modes", [TaskStatus])` — and `oneOf` then narrows the elements rather than the
+  list. It is the schema `fill<Model>Form` already builds for an array field, so the same shape reaching an agent
+  through a form and not through a component tool was an oversight: a tool that could not say "a list of these"
+  said it in prose, and the app then owned a parser for the format it invented. A second level is not describable.
+  **An argument type nothing can describe — a model class, `Any`, a
   `Map` — withdraws the whole tool and says so on the console**, naming the tool, the argument and the type; the
   callable still drives the click a person makes. It does not throw: a tool schema is built during render, and an
   agent-tooling mistake that aborted the render would cost the route its server rendering. `st.useState`'s `set`
@@ -315,6 +351,29 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   for a person too: the options arrive when the dropdown opens, and an agent never opens it. `Field.ParentId` /
   `Field.ChildrenId` need none of that — the id *is* the value, so the ordinary setter describes it. All four still
   require the setter **by reference**, and a `disabled` picker publishes nothing.
+- **An upload control reaches an agent the same way, through `useFileFieldTool`.** The clause after "picked **or
+  uploaded**" has its own hook: the control hands `read` and `label` and gets `load<Field>OptionsOn<Model>` — the
+  same name the relation picker publishes, because a form draws both side by side and a model that learned the
+  name on one field spells it the same on the next — plus the field's own `set<Field>On<Model>` taking
+  `<field>Id` / `<field>Ids`, with `add`/`sub` besides on an array field. **`read` omitted publishes nothing**: a
+  shared `Field.Img` forwards an optional prop, and a call site handing it none has no candidates and must not
+  grow a tool that refuses every id. `read` is the control's rather than the framework's because the ids are the
+  host's — a conversation carries `MessageAttachment.ref`s, and only whoever set them can turn one back into the
+  model a form field holds. akanjs draws no upload control itself, so this is the hook a lib's `Field.Img` /
+  `Field.Imgs` calls, exactly as `Field.Relation` calls the relation one.
+- **`add`/`sub` on a file field are the only way in, not the weaker way.** For every other list of ids they are a
+  convenience the framework declines to pay a tool for — `useFieldTool` publishes them for embedded rows only, and
+  the relation picker not at all, because a picker's `read` is the whole resolvable set so rewriting the array is
+  always expressible. An upload control's `read` is what *this conversation* brought, and the field may already
+  hold files that predate it: naming the array whole drops those, since the ids that would keep them are ids the
+  guard has never heard of. **`max` / `min` are passed, not derived** — `ConstantField` carries `arrDepth`, which
+  says the value is a list and not how long a legal one is — and they reach the tool's *description* as well as
+  its guard, because a limit an agent can only learn by tripping the server's `Err` is the round trip the listing
+  tool exists to spare it. Two call sites rendering one field with different caps describe one name two ways, and
+  the surface warns, which is the right answer: a field has one cap. For the same reason the unknown-id refusal
+  **names the boundary rather than the absence** on a list: an id already on the field is real, on screen, and in
+  the form the agent just read, so "no such file" reads as the form being wrong instead of the verb — it says the
+  id is not among what is *offered*, and points at `sub<Field>On<Model>`, which does cover it.
 - **An array of embedded rows also publishes `add<Field>On<Model>` and `sub<Field>On<Model>`** — append, and
   remove-by-position — beside the whole-array setter. Not new authority: the setter can already produce any array
   those two can, so they are strictly weaker. What they add is that neither can touch a row it was not given, and
@@ -367,18 +426,11 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   useless to a model — that is cheaper than every tool learning to avoid it.
 
 ## Slash Commands And The Transcript
-- **`prompt()` endpoints double as the chat's slash commands.** There is no listing endpoint — the client reads
-  its own serialized signals — so a prompt's dictionary `.desc()` is what the menu shows, and its guards are
-  enforced by the prompt's own GET at call time. Arguments are positional and whitespace-separated, and quoting
-  is how a sentence stays one of them (`/reviewTask t1 "look at the totals"`) — a prompt taking a single `String`
-  is the common case, and an unquoted sentence would fill its second parameter with the second word.
-- **The chat answers six slash commands of its own**, listed in the same `/` menu ahead of the prompts:
-  `/new` (`/clear`), `/retry`, `/compact`, `/copy`, `/help` and `/tools`. An app writes none of them and cannot add
-  one — the extension point for a product's own command is a `prompt()` endpoint, which is guarded and server-side.
-  **A built-in wins a name collision with a prompt of the same name**, the mirror image of the tool rule: a
-  component's `st.tool` shadows a built-in it means to replace, but no library's prompt may take `/new` away from
-  the user who typed it — so a shadowed prompt is dropped from the menu rather than listed twice. `/new` and
-  `/copy` are also dispatched *before* the is-a-turn-running check **and before the question card takes the
+- **The `/` menu is the chat's own.** An app's prompts are `page().prompt()` declarations served over MCP to
+  external agents; a browser chat lists none of them, so the menu holds the six built-in commands and nothing else.
+- **The chat answers six slash commands of its own**: `/new` (`/clear`), `/retry`, `/compact`, `/copy`, `/help` and
+  `/tools`. An app writes none of them and cannot add one — a workflow a person invokes by name belongs to MCP, as
+  a `page().prompt()`, where it is guarded by the page it opens. `/new` and `/copy` are dispatched *before* the is-a-turn-running check **and before the question card takes the
   composer**, because mid-turn is exactly when they are reached for and a question the agent asked is the middle
   of a turn like any other — answered as text, `/new` would have reached the model as the user's decision.
   `/new` therefore aborts the turn it is clearing and waits for it to wind down, since the loop clears its own
@@ -438,21 +490,24 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   row, Tab completing its name, and Escape closing the menu and then, pressed again, the panel.
 
 ## Built-In Tools
-- The framework publishes five built-ins on every store surface: `navigate` (internal paths only, the same
-  router `Link` rides), `goBack` (this session's history — global, because history is not a control a page owns and
-  a page that draws no back link is not one you may not leave — a screen that must not be left withholds them
-  with `builtins`, not with prose), `readScreen` (the rendered DOM as compact text —
-  headings, links, control values, and `(disabled)` on a control or button that has it; the chat's own UI is
-  skipped via `data-agent-ui`, and a password value is never read), `readState(key)` (one masked store key), and
-  `highlight(target)`. Declaring a hook tool under one of those names shadows the built-in, so reuse them only to
-  mean that. **There is no general-purpose wait**: a built-in one was reachable on every screen and a model spent
-  it on whatever key it liked, parking turns nobody asked to park. Waiting belongs to the screen that knows what
-  is worth waiting for — publish an `st.tool` beside the control that starts the work, and let it await the work.
+- The framework publishes five built-ins on every store surface: `navigate` (internal paths only, the same router
+  `Link` rides), `goBack` (this session's history — global, because history is not a control a page owns and a page
+  that draws no back link is not one you may not leave — a screen that must not be left withholds them with `builtins`,
+  not with prose), `readScreen` (the rendered DOM as compact text — headings, links, control values, and `(disabled)`
+  on a control or button that has it; the chat's own UI is skipped via `data-agent-ui`, and a password value is never
+  read), `readState(key)` (one masked store key — a key that is unknown or that this screen does not read is refused
+  *with the keys it can* read, the way `readScreen` names its sections), and `highlight(target)`. Declaring a hook tool
+  under one of those names shadows the built-in, so reuse them only to mean that. **There is no general-purpose wait**:
+  a built-in one was reachable on every screen and a model spent it on whatever key it liked, parking turns nobody
+  asked to park. Waiting belongs to the screen that knows what is worth waiting for — publish an `st.tool` beside the
+  control that starts the work, and let it await the work.
 - **A tool that changes the screen waits for the screen before it answers.** `router.push` returns while the RSC
   payload is still in flight and a store action that fires `void fetch.*` commits a tick later, so `navigate`
   awaits `ScreenSettle.wait()` — DOM quiescence, bounded, because the client router hands its promise to nobody —
-  and the session awaits it after every non-`query` tool before taking the change report. Without it the report
-  describes the moment before the change landed and the `readScreen` that follows reads the page the user left.
+  and the session awaits it after every tool that did not declare `settle: false` before taking the change report.
+  Without it the report describes the moment before the change landed and the `readScreen` that follows reads the
+  page the user left. The reading built-ins (`readScreen`, `readState`, `highlight`) declare it, because a wait
+  costs 120ms of quiet at the very least and they change nothing a resource holds.
   New tools and state from a fresh route are still only listed from the next turn: the catalogue is snapshotted
   when the turn starts.
 - **A tool that waits for its own work costs no model turns; one that returns early costs one round trip per
@@ -483,6 +538,13 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   one costs nothing, while two buttons reading "Save" are not the same control. **Nothing hidden ever resolves** —
   a ring nobody can see reads as a broken tool, not as a miss. A section named by a heading is read to the next
   heading of its level or higher.
+- **An image is always named, and its address rides only when asked for.** `readScreen` prints `[image: <alt>]`,
+  and `[image]` for one with no `alt` — dropping the unlabelled one left a card that renders a picture reading
+  exactly like a card that renders nothing, and "this page shows no image" is the one answer the screen cannot
+  support. `readScreen({ images: true })` appends `(<src>)` to each, for handing one to a tool that takes a
+  picture; it is off by default because a gallery is one long URL per thumbnail, which is the read's whole budget
+  spent on the part of the screen it can say the least about. A `data:` URL is never printed — that is the bytes
+  themselves rather than somewhere to fetch them.
 - **A screen is only aimable if its names are printed.** `readScreen` writes `(#anchor)` beside a heading that
   opens an id'd or scoped container, and a truncated read ends with the headings below the cut — otherwise
   everything past the 8000-character limit is unreachable, because nothing names it, and an agent asked to point
@@ -519,6 +581,24 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   a no-op when nobody is rendering it. The chat shows it on that call's row until the row resolves. It is the
   browser twin of `McpProgress.report`. Import it and `AgentAbort` from `akanjs/store`: an app may not reach
   `use-agentic` directly (`no-import-external-library`), and those two are the channels a long tool body needs.
+- **One turn carries every call the model made in it, and they run in order.** An assistant turn may hold any
+  number of tool calls; the session executes them one at a time, in the order they arrived, and posts them back as
+  one `tool` message. A batch therefore costs **one** model round trip, where the same calls chained one per turn
+  cost a round trip *and* a resend of the whole transcript each — and then meet the turn cap halfway through. The
+  framework asks for the batch in its own half of the system prompt (`AgentService.preamble`); what an app adds is
+  a tool that does the whole job in one call, so there are fewer calls to batch in the first place. Two agents'
+  calls still take turns page-wide — see Zones.
+- **A chain of ten calls is usually a model checking its own work, not ten things to do.** Measured against the
+  provider, the batch itself lands in one turn; what follows it is `readScreen → readState → readScreen`, one read
+  per turn, confirming a write whose change report already said the same thing. The preamble tells the model not
+  to, which is worth a turn and a half on a plain "approve what is pending". So a tool that returns *what
+  changed* pays for itself twice — once as the answer, once as the reads it stops. The read a fresh route needs
+  after `navigate` is acquisition rather than confirmation and is unaffected.
+- **A batch reports each changed resource once, at the end.** Every call takes its own before-and-after, so eight
+  approvals would each attach the whole list they approved from — and by the time the model reads the message,
+  only the last copy is still true. The superseded ones are dropped (`ToolOutput.deduped`), so a resource several
+  calls touched appears once, as it finally stands, on the last result that touched it. What each call did is
+  still its own `result`; do not compensate by returning the collection from every write.
 - **The turn cap is a question, not a dead end.** At `maxTurns` the session asks whether to keep going through the
   same card `askUser` uses, and the answer rides as the user's own turn — so a steer typed instead of the
   keep-going choice reaches the model as guidance. A host that renders no `pendingQuestion` passes no

package/guidelines/conventions/conventions.instruction.md

@@ -403,7 +403,9 @@ framework has no hard delete for a model table, and `delete` is deliberately lef
 The facade spells `Many`/`One` out on its writes (`updateOne` / `updateMany` / `removeOne` / `removeMany`); only the
 count was shortened to `count(query)`, with `countDocuments` kept as `@deprecated`. `updateById(id, update)` and
 `removeById(id)` are those same query-level writes narrowed to one id, **not** the document path: they fire no hooks,
-so a model whose removal cascades or carries a `_postRemove` still goes through `remove<Model>(id)`.
+so a model whose removal cascades or carries a `_postRemove` still goes through `remove<Model>(id)`. The
+write-through pair is `pickAndWrite(id, data)` / `pickOneAndWrite(query, data)` — pick the document, write into it
+and save it, so the save hooks do run; reach for those when the write has to be seen by them.
 
 **`<model>.service.ts`** — keep methods to a few lines: load → chain → `return await ….save()`. Write `return await`
 explicitly in tail position; do not "optimize" it away. Side effects belong in `override async _preUpdate` /
@@ -470,7 +472,7 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
 - **The guards are also the MCP exposure decision** — see MCP Exposure. An endpoint that names none is not published to agents at all, and a mutation whose only guard is `Public` is refused, so a missing `guards` array now costs visibility as well as authorization.
 - Resource guards are `Can<Verb><Model>` classes in `srvkit/guards.ts` that `implements Guard` with an `async canPass(context)`. They **fail closed**: no resource named ⇒ `false`; a load that throws ⇒ `logger.warn` then `false`. Admin bypass goes first.
 - Keep `static name = "User";` on guard classes. `fetch` serializes guard names and the API explorer filters on them; it looks like dead code, and deleting it breaks the UI. Comment it so the next reader knows.
-- **Every guard class also declares `static scope: GuardScope`, and it is required with no default.** `"account"` means the verdict reads the caller and nothing about the call, so it can be evaluated with no arguments — which is what lets an MCP listing hide what this caller certainly cannot use. `"resource"` means it needs the call's arguments (`context.getArg()`) and fails closed without them, so it is never evaluated for a listing: the entry stays visible and is stopped at call time. Getting it wrong is not a type error, so the marker is mandatory rather than defaulted — `SignedIn` / `Admin` / role checks are `"account"`, and every `Can<Verb><Model>` is `"resource"`.
+- **Every guard class also declares `static scope: GuardScope`, and it is required with no default.** `"account"` means the verdict reads the caller and nothing about the call, so it can be evaluated with no arguments — which is what lets an MCP listing hide what this caller certainly cannot use. `"resource"` means it needs the call's arguments (`context.getArg()`) and fails closed without them, so it is never evaluated for a listing: the entry stays visible and is stopped at call time. Getting it wrong is not a type error, so the marker is mandatory rather than defaulted — `SignedIn` / `Admin` / role checks are `"account"`, and every `Can<Verb><Model>` is `"resource"`. An `"account"` guard that throws at listing time reached for arguments it does not have: the entry is hidden from every caller and the guard is named once in the log as mismarked. A guard that admits no model at all — `Person` — adds `static agents = false`; the MCP catalogue then refuses every endpoint it guards outright, so the person-only act is absent from the document rather than hidden per caller.
 - The acting user arrives via `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`. Never trust a client-supplied id.
 - Guards ship with the library that owns the model and are imported by its own signals through the package path, so a mounting app inherits authorization and cannot forget it.
 - Services re-check ownership even when a guard already gated the call — two independent gates.
@@ -515,7 +517,12 @@ Full contract — filter-arg `ref` pickers, `getQueryMeta` summary counters, `la
   `[object Object]`. It is an admin API: `root:` is always `Admin`.
 - A slice's `exec` returns a `QueryOf` (an opaque query descriptor); you **cannot** chain `.sort()`/`.limit()` on
   it. Apply ordering/paging via the store `init` fetch option instead: `initX(..., { sort, page, limit })`. For a
-  chainable builder use the model facade's `findMany`/`findOne`.
+  chainable builder use the model facade's `find`/`findOne`.
+- **A projection is bare on the facade and nested under `select` on a filter accessor.** `pickById(id, { secret:
+  true })` and `find`/`findOne`/`findById`/`pickOne` take the projection as their second argument; a generated
+  `findBy<Filter>(...args, { select: { secret: true } })` takes it inside the option object. The shapes do not swap
+  — `{ select: … }` handed to the facade projects a field named `select`, which no model has, and the read comes
+  back empty with no error. This is the only way to read a `field.secret(...)` value.
 - **A slice list is either one window or an accumulated one.** `setPageOf<Model>` swaps the window;
   `loadMoreOf<Model>()` appends the rows after the ones loaded and takes **no page number** — it skips by
   `<model>List.length`, so the offset cannot drift from what is on screen when a live insertion moves the server's
@@ -598,6 +605,7 @@ Conventions that hold for both shapes:
 - Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`). There are no Result/Either wrappers.
 - `try/catch` is rare and always converts an exception into a decision, never swallows one. Guards catch → `logger.warn` → `return false`; adapters catch → `logger.error` → `return null`; UI uses `try/finally` to reset a spinner. A bodyless `catch {}` is acceptable only with a one-line reason.
 - Store actions do not `try/catch` — let the framework toast the `Err`. Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
+- **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(..., { origin })` restores the remote `Err` — the same class, key and `data` — so a hop that rethrows it answers its own caller with that error and the dictionary translates it. Never wrap the catch in a `new Error`, and never re-key it as a `new Err` of your own: both discard what the endpoint chose to say, and a bare `Error` is generalized to `Internal Server Error` on the way out.
 
 ### MCP Exposure
 
@@ -616,16 +624,41 @@ it.
   slice and generated CRUD only, never a named slice or a custom endpoint. It is an opt-**out**, and it is
   curation, not authorization: HTTP serves the endpoint exactly as before.
 - **Narrow by cost, and read the boot log first.** MCP forbids a `$ref` across entries, so every entry inlines the
-  full schema of every model it mentions and the listing is re-sent whole to every agent that connects. A plain
-  21-field model costs 12.6KB over eight entries; `mcp: { cru: false }` takes it to 4.7KB. `MCP catalogue: … ·
-  listing 214KB` plus a per-signal `MCP catalogue cost:` line says where it went.
+  schema of every model it mentions and the listing is re-sent whole to every agent that connects. By default a
+  response schema names a nested model instead of inlining it (`outputSchema: "shallow"`; `"full"` restores the
+  closure, `"none"` drops the schema and keeps the text block) and a request schema asks for a relation's id, which
+  is what the wire carries. `MCP catalogue: … · listing 214KB` plus a per-signal `MCP catalogue cost:` line says
+  where the rest went; `mcp: { cru: false }` on a model is the next lever. `outputSchema` moves wire bytes and client
+  memory only — the model receives names, descriptions and input schemas (measured: 219 tools ≈ 41k tokens either
+  way) — so tool count and the input model behind `create*` / `update*` are what cost context. In one line:
+  `Person` for an act reserved for a person, `mcp: { cru: false }` for the tools whose input models cost the model
+  tokens, `outputSchema` for nothing that reaches the model.
 - Settings live in the app's `lib/option.ts` — `option.setMcp({ enabled, readOnly, path, version, instructions,
-  allowedOrigins, pageSize, language, auth })`, **not `main.ts`**. Each field has an `AKAN_MCP_*` env spelling.
-  `AKAN_MCP_READONLY=true` is the read-only-deployment valve, not the exposure switch; `AKAN_MCP=false` takes the
-  whole surface off.
+  allowedOrigins, pageSize, language, outputSchema, rateLimit, auth })`, or `setMcp((env) => …)` for one derived from the server env, **not
+  `main.ts`**. Each field has an `AKAN_MCP_*` env spelling. `AKAN_MCP_READONLY=true` is the read-only-deployment
+  valve, not the exposure switch; `AKAN_MCP=false` takes the whole surface off. Every call that executes an
+  endpoint is rate-limited per caller (120 a minute, 8 in flight, per process; 429 + `Retry-After`) — `rateLimit`
+  / `AKAN_MCP_RATE_LIMIT` tunes or disables it.
+- **Authentication is the same server.** An app mounting `libs/shared` serves the OAuth 2.1 authorization server
+  beside `/mcp` — `/.well-known/oauth-authorization-server`, `/oauth/authorize`, `/oauth/token`, `/oauth/register`
+  (RFC 7591; Cursor's `cursor://` redirect admitted) plus the consent page `libs/shared/page/oauth/consent` — and
+  names itself as the issuer, so `/mcp` demands a bearer token, verifies its signature, and refuses one carrying no
+  `aud`. A token is the app's own access JWT plus `aud`/`iss`/`client_id`, so `AccountMiddleware` and the guards
+  judge it unchanged; there is no scope. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
+  `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `clientIdMetadata`,
+  `enabled`). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` is
+  mandatory outside `local`, because the derived fallback is forgeable from three public names. A grant is revoked
+  whole — `POST /oauth/revoke` (RFC 7009) by the client, `fetch.revokeOAuthConnection(sessionId)` by the account's
+  owner, `fetch.listOAuthConnections()` to see them — and a revoked access token is refused at its next call.
+- **A person may, a model may not.** An agent's token names its `client_id` and `aud`; a browser session has
+  neither, and `context.origin` is `"mcp"` for a call through the MCP endpoint. `guards: [Every, Person]` refuses a
+  model and, because `Person` declares `static agents = false`, takes the entry out of the MCP catalogue document
+  itself (named in the boot log like `mcp: false`); `.with(AgentCall)` hands an endpoint the same verdict as a
+  boolean to narrow what the call sets in motion; `isAgentCall(context)` is the function behind both
+  (`@libs/shared/srvkit`). Never sniff `aud` through a cast.
 - **The refusals are fail-closed**: a declared `mcp: false`, an endpoint with no `guards`, a mutation with no real
   guard, `pubsub` and `message`, an `Any` or `Upload` return, a file upload, a required `Any` argument, and the
-  generated `light<Model>` read. A `prompt` also refuses a list argument and any `Any` argument. **Every refusal
+  generated `light<Model>` read. An `enumOf` argument is checked against its values on every path. **Every refusal
   is named in the boot log**, along with every published entry missing a dictionary `.desc()` — an agent picks a
   tool by its description.
 - A refused endpoint answers the *same* "unknown tool" as one that does not exist, and a guard's refusal is
@@ -633,10 +666,14 @@ it.
 - **A `field.visual` field is stripped from every MCP result** and from the readable schema so the two agree.
 - **A structured result ships twice by default** — as `structuredContent` and as the same JSON in the text block.
   `option.setMcp({ legacyTextBlock: false })` leaves a pointer there instead.
-- **`prompt()`** is invoked by the *user* as a slash command, never chosen by the model. `exec` returns
-  `PromptMessage[]` built with `Msg.user` / `Msg.assistant` / `Msg.resource` / `Msg.image`; an embedded payload is
-  masked by the model you name, and one whose `hidden`/`secret` fields are populated with no model named is
-  refused. It is also mounted as a plain HTTP `GET` whether or not MCP is enabled, so guard it like any other read.
+- **A prompt is a screen: `page().prompt(name, description)`.** There is no `prompt()` on `endpoint()`.
+  `prompts/get` runs the page's body in the RSC worker under the caller's token — nothing is rendered — and answers
+  the description, one `resource` per `fetch.*` the page made (masked by the endpoint's return model, addressed by
+  its `akan://` uri, one document once whatever shapes read it) and the published tools of the modules it fetched
+  from, minus what is already attached; lists — only lists — are cut to `promptBudget`. A guard refusing a query
+  inside the body reads as the screen refusing the account, the same way a redirect does. A
+  required argument left out answers a pointer to the `<model>List…` tool, never a guess. The description is the
+  only instruction, in English — `<Agent.Guide>` never reaches MCP, and the in-page chat lists no page prompts.
 
 Full contract — configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions, and
 `McpProgress.report`: `get_guideline` with `mcpRule`, or `akan guideline show mcpRule`.
@@ -659,7 +696,9 @@ what every developer must know even when not building one.
   every tool runs in the caller's own browser session, gated by guards and the approval card. Its guard is
   `AgentRelayAccess`, which refuses every call until the app names a guard of its own —
   `option.setAgentAccess(SignedIn)`. **The LLM is configured in `option.ts`, never through the environment**
-  (`option.setLlm({ apiKey, model, host })`).
+  (`option.setLlm({ apiKey, model, host })`). Three providers ship — `DeepseekLlm` (the default, text only),
+  `OpenaiLlm` and `AnthropicLlm` (both read images) — and swapping one in is
+  `option.applyAdaptor(LlmAdaptorRole, AnthropicLlm)`.
 - **Declare the tool beside the control that already does it**, never as a separate surface:
   `st.tool("x").desc("…").arg("id", ID).exec(fn)` returns the callable to hand to `onClick` — one handler for the
   person and the agent. Publish it only where the screen already renders the control; a falsy name declares the
@@ -745,10 +784,11 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   forms: a relation, an id with `ref`, or a polymorphic id with `refPath`. An array, a Map, `ref` together with
   `refPath`, and a field naming no owner each fail the class build.
 - **A `refPath` must name an `enumOf` field** — a free-form owner type is unknowable at build time. The one
-  exception is opt-in and priced: `polymorphic: "any"` alongside `cascade: "removeWith"` takes a free-form
-  `String` type field holding the owner's refName, and sweeps for children on **every** model's removal. The
-  sweep is one indexed probe, but a single wildcard edge turns every cascade in the app back to one document at
-  a time; the boot log names the edges in one `info` line.
+  exception is opt-in and priced: `cascade: "removeWithAny"` takes a free-form `String` type field holding the
+  owner's refName, and sweeps for children on **every** model's removal. The sweep is one indexed probe, but a
+  single wildcard edge turns every cascade in the app back to one document at a time; the boot log names the
+  edges in one `info` line. The action carries its own `refPath` in the option type, so the widening cannot be
+  declared apart from the direction it widens.
 - **A cascade goes through the target's service, never its model** — that path is what runs the target's
   `_postRemove`, where a module puts the side effect the removal has to carry.
 - **Nothing checks whether another document still references the same target.** `File` in particular is deduped by
@@ -767,39 +807,50 @@ shape, so `cascade` never means "related" — it means one of exactly these:
 - Reserved `_*.tsx` route filenames are limited to `_index.tsx`, `_layout.tsx`, and `_overrides.tsx`; do not add files like `_Component.tsx` or `_helper.tsx`.
 - Page filenames must not start with an uppercase letter. Move helper components like `Component.tsx` to app `ui`, `common`, or `lib` instead.
 - Dynamic segments use `[id]`; route groups use directories like `(user)`, `(public)`, `(tab)`, or `(detail)`.
-- Page modules should usually export `default`, `pageConfig`, `head`, `generateHead`, or `Loading`.
+- **A route file exports one thing**: `export default page()…render(…)` for a page, `layout()…render(…)` for a
+  `_layout.tsx`, `rootLayout()…render(…)` for the app's (or a basePath's) root `_layout.tsx`. Every route setting
+  is a stage of the chain — `.param()`, `.search()`, `.config()`, `.head()` / `.metadata()`, `.loading()`;
+  `.notFound()` / `.error()` on a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()`
+  / `.layoutStyle()` / `.gaTrackingId()` on the root layout; `.prompt()` on a page. A named export beside the chain,
+  or `page()` in a `_layout.tsx`, fails the build.
+- **A page names every `[x]` segment of its path with `.param("x", Type)`** and reads a query key only through
+  `.search("k", Type)`. Values arrive typed — `ID`/`String` → string, `Int`/`Float` → number, `Boolean`, `Date` →
+  Dayjs, an `enumOf` class → its union, `[T]` → array — a path value the type refuses answers not-found, and a
+  search value that fails is dropped. A layout may declare a subset. Names are string literals: `akan sync` reads
+  them off the source and refuses a `[projectId]` folder whose page declares no `.param("projectId")`. `lang` is
+  never declared: every route sits under `/:lang`, and the locale segment reaches every stage as `lang`.
 - `_overrides.tsx` is a logic-free UI-override manifest: imports plus a single `export default override({ Slot: AppComponent })` (from `akanjs/ui`), no `"use client"`. It re-skins framework `akanjs/ui` components for its route subtree; nested manifests merge over ancestors slot-by-slot (closest wins). See the UI Customization reference for the slot list.
-- Prefer `export default function Page` or `export default async function Page` for page components.
+- The legacy shape — `export default async function Page` beside `pageConfig` / `head` / `Loading` exports — still
+  loads and logs one deprecation warning per file at boot. Migrate with the `workspaceRecipes` recipe "Migrating
+  `page/` to the route chain"; new files are never written in it.
 - `libs/<lib>/page` follows the same rules and ships routes to apps that opt in with `syncPageLibs` in `akan.config.ts`: `true` takes every lib dep that has a `page` folder, an array takes the libs listed, `false` (the default) syncs nothing.
 - `akan sync` links those routes into `apps/<app>/page/(libs)/(<lib>)` — once per basePath when the app declares subRoutes. The folder is generated and gitignored; edit the lib source, never the link.
 - Both path segments are route groups, so a lib route mounts at its own path (`libs/<lib>/page/login/_index.tsx` serves `/login`). Two synced routes that resolve to the same pattern are a sync-time error.
-- `export const pageConfig = { devOnly: true }` keeps a route out of `akan build` while it keeps serving under `akan start` and keeps being typechecked. On a `_layout.tsx` it excludes every route under that directory too. Write it as a literal `true`/`false` — the build reads it off the source without evaluating the module.
+- `.config({ devOnly: true })` keeps a route out of `akan build` while it keeps serving under `akan start` and keeps being typechecked. On a `_layout.tsx` it excludes every route under that directory too. Write it as a literal `true`/`false` — the build reads it off the source without evaluating the module.
 - Before changing route behavior, check `pkgs/akanjs/server/routeTreeBuilder.ts` and nearby routes for the expected pattern.
 
 ### Page Body Shape
 
 ```tsx
-interface PageProps {
-  params: { orgId: string };
-}
-
-export default async function Page({ params }: PageProps) {
-  const { l } = usePage();
-  getSelf({ unauthorize: "/signin" });
-  const { orgId } = params;
-  const [{ org }, { taskInitInOrg }] = await Promise.all([fetch.viewOrg(orgId), fetch.initTaskInOrg(orgId)]);
-  return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
-}
-
-export const pageConfig = { transition: "stack" } satisfies PageConfig;
+export default page()
+  .param("orgId", ID)
+  .config({ transition: "stack" })
+  .render(async ({ orgId }) => {
+    const { l } = usePage();
+    getSelf({ unauthorize: "/signin" });
+    const [{ org }, { taskInitInOrg }] = await Promise.all([fetch.viewOrg(orgId), fetch.initTaskInOrg(orgId)]);
+    return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
+  });
 ```
 
-- There is no `loader=` / `render=` page prop. Pages are `export default async function Page`.
-- Declare `interface PageProps { params: {...}; searchParams?: {...} }` immediately above the default export.
-- Body order: `usePage()`, auth, destructure params, fetch, return.
+- There is no `loader=` / `render=` page prop and no `PageProps` interface: the chain declares the arguments and
+  `.render()` receives them flat, typed, with `lang` on every route and `children` added for a layout.
+- Body order inside `.render()`: `usePage()`, auth, fetch, return.
 - Run independent fetches through `Promise.all`, even when there is only one.
 - Gate auth at `_layout.tsx`; repeating `getSelf({ unauthorize: "/signin" })` in the page is fine and common.
-- Keep `async` even when nothing is awaited — it marks a real server page.
+- `async` on the render callback only when the body awaits; the callback is not a React component, so it takes no
+  name and no return type.
+- Publish a screen to agents with `.prompt(name, description)` — see MCP Exposure.
 - No `useState`, no `useEffect`, and no comments in page files.
 
 ## Akan Sync Conventions (`apps/**`, `libs/**`)
@@ -872,9 +923,18 @@ when two shapes disagree.
   one — `host` for the dev host, gateway and RSC worker, plus a row per replica the gateway forwards — and the
   selected one's log beside it. `Tab` walks every row and `1`-`9` jump to that app (the rail shows each
   app's digit), `↑↓` scroll (shift for a page, `G` back to following),
-  `/` greps, `e` shows stderr only, `c` clears, `o` opens the browser, `r` restarts that app, `q` quits.
+  `/` greps, `e` shows stderr only, `c` clears, `y` copies, `Y` copies the log path, `o` opens the browser,
+  `r` restarts that app, `q` quits.
   **`--plain` prints prefixed interleaved lines instead**, and a pipe, a redirect or an unsized terminal
   downgrades to that on its own.
+- **A supervised session writes `local/apps/<app>/runtime/dev.log`, and that path is how a log gets handed over.**
+  Ink repaints one frame in place, so the full-screen view leaves a bordered screenshot in the scrollback and
+  takes the rest of the session with it — a drag-selection is cleared by the next repaint, and what survives
+  carries borders and lines truncated to the pane. The file is the same output with no ANSI, nothing truncated,
+  and every process of the app in arrival order, including the dev host's own build output, which reaches no
+  other file. The previous session is kept beside it as `dev.prev.log`. Hand somebody — or an agent — the
+  path rather than a paste: it costs one line instead of a transcript, and it can be re-read after a fix.
+  In the view, `y` copies the lines the filters have already narrowed and `Y` copies the path.
 - **How many apps boot at once is the machine's answer, not a constant.** A cold boot build is the builder's
   RSS peak (~900MB per app), so the default wave is what memory and cores allow — half the memory budget
   divided by that peak, and one app per four cores — which boots a laptop's apps together and still staggers

package/guidelines/mcpRule/mcpRule.generate.json

@@ -14,7 +14,17 @@
   ],
   "update": {
     "filePath": "./mcpRule.instruction.md",
-    "contents": ["exposure rule", "configuration", "declaring endpoints", "refusals and wire behaviour", "prompts"],
+    "contents": [
+      "exposure rule",
+      "configuration",
+      "declaring endpoints",
+      "refusals and wire behaviour",
+      "prompts",
+      "rolling out to an app",
+      "choosing what to open",
+      "writing instructions",
+      "verifying an app"
+    ],
     "rules": [
       "Use current Akan APIs only",
       "State the rule before the reason, and keep the reason to one clause",