@akanjs/cli 3.0.0-beta.3 → 3.0.0-beta.30

package/guideline.command-11cndccb.js

@@ -0,0 +1,42 @@
+// @bun
+import {
+  script,
+  command
+} from "./index-xb7qhxa8.js";
+import"./index-52w0fvh8.js";
+import"./index-n3jk2501.js";
+import {
+  Prompter2
+} from "./index-zzvvc845.js";
+
+// pkgs/@akanjs/cli/guideline/guideline.script.ts
+import { Logger } from "akanjs/common";
+
+class GuidelineScript extends script("guideline") {
+  async guideline(action, name = null) {
+    if (action === "list") {
+      const guidelines = await Prompter2.listGuidelines();
+      Logger.rawLog(guidelines.join(`
+`));
+      return;
+    }
+    if (action === "show") {
+      if (!name)
+        throw new Error("Guideline name is required. Example: akan guideline show framework");
+      Logger.rawLog(await Prompter2.getInstruction(name));
+      return;
+    }
+    throw new Error(`Unknown guideline action: ${action}. Use "list" or "show".`);
+  }
+}
+
+// pkgs/@akanjs/cli/guideline/guideline.command.ts
+class GuidelineCommand extends command("guideline", [GuidelineScript], ({ public: target }) => ({
+  guideline: target({ desc: "List or show Akan AI guideline instructions" }).arg("action", String, { desc: "list or show" }).arg("name", String, { desc: "guideline name for show", nullable: true }).exec(async function(action, name) {
+    await this.guidelineScript.guideline(action, name);
+  })
+})) {
+}
+export {
+  GuidelineCommand
+};

package/guidelines/agentRule/agentRule.instruction.md

@@ -15,6 +15,13 @@ for. `Load` scopes, the route, and the live keys complete the context. The React
 apps and libs never import it directly (`no-import-external-library`) — everything reaches them through `st.*` and
 `akanjs/ui`.
 
+**Mounted is not published: on a CSR stack only the current page is.** The page kept under the current one for a
+swipe back stays mounted and live, and its declarations stay registered, but its tools, resources, guides and
+`st.use` keys are parked until it is current again — the agent sees the screen the user sees, never two. Each page
+container renders `use-agentic`'s `<AgentActivity active>` for this; a parked registration shadows nothing, two
+pages declaring one name never clash, and a registry kept outside the surface reads the same gate through
+`useAgentGate()`, as the store's live keys do.
+
 ## Mounting The Chat
 - **Mount `<Agent.Chat />` once in a layout.** That is the floating chat, the approval card, and the client-side
   loop. The default runner drives `runAgentTurn`, which the **framework serves on every app** — no lib to mount,
@@ -45,10 +52,16 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   clear and close. `chrome={false}` drops the header bar whole, for an `inline` chat inside a panel the app
   already titles, and `defaultDraft` opens the composer with text in it without sending it. A panel driven by a
   controlled `open` with **no** `onOpenChange` draws no close button at all rather than an inert one. Then the
-  slots: `AgentLauncher`, `AgentBubble`, `AgentComposer`, `AgentApproval`,
-  `AgentQuestion`, `AgentQueued`, `AgentMenu`, `AgentMarkdown` and `AgentCode` each replace one part in `_overrides.tsx`, and
+  slots: `AgentLauncher`, `AgentSteps`, `AgentBubble`, `AgentComposer`, `AgentApproval`,
+  `AgentQuestion`, `AgentToolCard`, `AgentQueued`, `AgentMenu`, `AgentMarkdown` and `AgentCode` each replace one part in `_overrides.tsx`, and
   `akanjs/ui` exports every default beside them (`DefaultBubble`, `DefaultComposer`, …) so a skin composes the
-  one it is replacing. `AgentCode` is where a highlighter binds — the fence's language reaches it — and a
+  one it is replacing. **`AgentSteps` is one agent turn** — the messages between the user message that opened it
+  and the next one, with `isRunning` saying whether more are still coming — which is the grain a chat needs to
+  fold a turn's steps into a `details` and stand its answer outside them. It is the one boundary a per-message
+  slot cannot see, since neither message on either side of it knows it is at an edge. The default draws the turn's
+  messages flat into a Fragment, so a chat that binds nothing renders exactly what it did before the slot existed. The attachment row is exported on its own as `AgentAttachments`, because a replaced
+  `AgentBubble` that redraws it by hand forks the rule for which carrier is shown how — and then keeps whatever
+  that rule was on the day it was copied. `AgentCode` is where a highlighter binds — the fence's language reaches it — and a
   replacement for `AgentBubble` carries its own `memo`, since the transcript re-renders on every delta. Only then
   `AgentChat`, which replaces the panel whole: it also replaces the slash commands, the compaction notice and the
   approval gate, so reach for it when the *layout* differs, not when the look does.
@@ -70,24 +83,41 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
 - **The LLM is configured in `option.ts`, never through the environment.** `option.setLlm({ apiKey, model, host })`
   — or `setLlm((options) => …)` to read the key out of the app's own env object, which is where a secret belongs —
   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, 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.
+  rather than one provider's, so they survive a swap. **`OpenaiLlm` is the built-in default**, pointed at
+  `https://api.openai.com/v1`; with no `apiKey` or no `model` the app still boots and the chat answers
+  `llmUnavailable`. Swap 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 — and
+  whatever settings it needs beyond `LlmOption` travel through the same `setLlm`, read back with
+  `use<MyLlmOption>()` from an interface extending it.
+- **Two adaptors ship, one per wire — a vendor is a host and a model name, not a protocol.** `OpenaiLlm` is the
+  chat-completions dialect (`OpenaiDialect`) pointed at whatever `host` names, so OpenAI, DeepSeek, Groq,
+  Together, OpenRouter, Ollama and a self-hosted vLLM are all one class and one `option.setLlm({ host, model })`.
+  `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 require `model`**: a default would age into a 404, and worse, it
+  would decide the vision claim for the app.
+- **`OpenaiLlm` claims vision for its default host and for nothing else.** OpenAI's own endpoint takes image
+  parts, so that is what it answers with no `host` set. A `host` the app named is a gateway the class knows
+  nothing about, and it stays text-only until `option.setLlm({ accepts })` says otherwise — handing bytes to a
+  model that cannot decode them kills the whole turn on a 400, where text-only degrades them to a note the model
+  can repeat back.
+- **A refusal is `agent.error.llmRequestFailed`, and it names the host** — unless the prompt did not fit. The
+  provider's own sentence rides in `reason` and the hostname in `provider`. `LlmOverflow.refusal(host, status,
+  reason)` builds it, and reads the one refusal a chat can undo — a prompt past the window, recognized from each
+  provider's own sentence — as `agent.error.contextOverflow` with the `limit` it named, which the relay flags so
+  the chat compacts and asks again. An adaptor an app wrote throws through the same function, so its refusals
+  translate and recover the way the shipped ones do without a key in the framework's dictionary it cannot add.
 - **`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.
+- **`contextWindow` is declared the same way: `option.setLlm({ contextWindow })`.** Every turn relays it with the
+  answer ceiling the adaptor actually sends (`LlmAdaptor.limits` — `AnthropicLlm` always sends one, `OpenaiLlm`
+  none), and the chat guards its window with it. It is not a table either; a model id is retired or renamed long
+  before a table notices.
 - **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
@@ -110,8 +140,9 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   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.
+  attachment's name, type, address and `ref` and drops only 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, while an id is the handle a restored conversation has left to find the file with.
   **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
@@ -121,11 +152,19 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   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.
-- **A `url` carrier is an address the *provider* fetches, so a reader that uploads has to know its storage is
-  reachable.** This is the one way an attachment fails with nobody reporting it: the default storage backend
-  serves a path only the app can resolve, the adaptor hands it over as written, and the model answers about a
-  picture it never saw. Answer `data` when the provider cannot reach the URL — the choice is the reader's,
-  because the reader is what chose to upload.
+- **An app may also build attachments itself and hand them to `session.send([{ role: "user", text, attachments }])`**,
+  which is why `MessageAttachment` is exported from `akanjs/ui` — the composer's path is typed by the `AttachReader`
+  callback, that one is not, and an object assembled with no nameable type is the one that gets a field wrong.
+  Nothing downstream trusts the result: an attachment whose `mimeType` is not a string is noted like any other
+  unreadable one, and its chip renders its name with no preview, because the host wrote the object and the declared
+  type is a claim rather than a check. A field that arrives wrong costs that attachment, never the turn.
+- **A `url` carrier is an address the *provider* fetches, and bytes beside it win.** A reader that uploads answers
+  `{ url }` when its storage is publicly reachable, and `{ data }` — or both — when it is not: an attachment
+  carrying both is read from its bytes and displayed from its address, so the chip draws a thumbnail and the model
+  still gets the picture. That precedence exists because the other order fails the one way nothing reports: the
+  default storage backend serves a path only the app can resolve, the adaptor would hand it over as written, and
+  the model answers about a picture it never saw. Send a provider-reachable URL **alone** — paired with bytes it
+  costs the provider hop whatever the bytes weigh, for a fetch the provider would have done itself.
 - **An image type the provider has no block for is refused at the adaptor, not upstream.** `accepts.image` is one
   boolean, so `AgentService.readable` passes every `image/*` through, and the built-in composer reader base64s
   every `image/*` as well — an `AttachReader` answering `null` means "not mine" and falls through to it, so an app
@@ -149,10 +188,56 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   there: a voice user who is never told about the card is a conversation that simply ends.
   The contract is a subscription rather than `listen(): Promise<string>` on purpose: a promise fits push-to-talk
   and nothing else, so hands-free could then only arrive as a breaking change. `useSpeech` in a util lib's
-  `webkit/` is the engine — the browser's own recognition and synthesis on the web, the Capacitor plugins in a
-  WebView, **which has neither on Android or iOS**, so a `speech.plugin.ts` declares the permission and
-  the packages the native build needs. An engine answering `available()` false renders no microphone at all,
+  `webkit/` is the engine — the browser's own recognition and synthesis. An app's WebView **has neither on
+  Android or iOS** and `@akanjs/native` ships no speech plugin yet, so a `speech.plugin.ts` declares only the
+  permission and its usage texts. An engine answering `available()` false renders no microphone at all,
   the same rule as publishing no tool for a control the screen does not draw.
+- **Data the user points at rides the message too, as `references` — and its value is a snapshot.** A file is
+  something they handed over; a reference is something they pointed at while asking, so it belongs in the same
+  place and for the same reason. Screen context does not do this job: `ContextBlock`s are rebuilt from the screen
+  every turn, so what was named three turns ago is simply not in the conversation any more. A `MessageReference`
+  carries the host's own `refName`, the id, a label, an optional dotted `path` into the document, and the `value`
+  those resolved to. **The value is never re-read on a later turn**, which is the point: re-reading rewrites what
+  the person was looking at when they spoke, and the usual next thing the agent does is edit the very field it was
+  pointed at — leaving a live reference showing the result with no record of what it was changed from.
+  `refName`/`refId`/`path` travel so a tool can read the current value when the answer needs it, and
+  `AgentService.referenced` folds the whole lot into the message text in one place, so every provider carries a
+  reference without either adaptor knowing the word. **The value is masked on the way in and nowhere else**: masking
+  needs the model class, which no wire carries, so the model a host names when it stages the reference is the whole
+  of the decision about what leaves the browser — name the class that actually holds the field, because a `Light`
+  one usually does not. **The ceiling is 20,000 characters per reference**, applied as it is staged and again on
+  the server; a reference is bulkier than a tool result and outlives one, riding every later turn and being the last
+  thing compaction folds. Persisting keeps the pointer and drops the value with a note saying so, which is a better
+  restored state than an attachment can offer — the pointer is still live, so the answer is to read it again.
+  Staging lives on the **session** (`stage` / `staged` / `unstage(key)` / `clearStaged()`), not on the composer where
+  staged files live, because a reference comes from whichever component drew the data rather than from the paperclip;
+  `unstage` is keyed on `refName/refId#path` because what orders a message's references is its text, not that list.
+- **Two ways to point at data, and which one depends on who knows the value.** `<Agent.Chat reference={[…]} />`
+  takes one `ReferenceSource` per kind of document — `refName`, a `type`, the app's own `search`, and a `resolve` —
+  and the composer's `@` menu offers whole documents from them; the token is written the moment a row is picked and
+  the value is staged when `resolve` lands, so a slow fetch never freezes the menu and one that fails leaves a
+  pointer that reads as *go and read it*. For a field *inside* a document, the component drawing it calls
+  `useAgentReference()` — it already holds the value, so there is no round trip, and it is the only thing that
+  knows a rich-text field stored as `field(Any)` reads as a paragraph rather than as the editor document it is. The
+  hook no-ops with a warning outside a session, the same call `AgentValue.publishable` makes: a card carrying a
+  reference button must not cost a route its render.
+- **The token in the draft is what carries a reference, and the chip only draws it.** Deleting
+  `@[label](mention:refName/id#path)` by hand drops the reference exactly as removing the chip does — removing the
+  chip removes the token — so the two can never disagree, and nothing re-derives a value from text somebody edited.
+  A token pasted out of an earlier message travels as a pointer with a note, which is the same shape a restored
+  conversation produces. Staged references are the **session's**, not the composer's, because `useAgentReference`
+  is called from components the composer cannot see; writing the token is the composer's half, and `refer` warns
+  rather than staging silently when no chat is mounted on that session — the case where a card sits outside the
+  `<Agent.Zone>` its chat is inside.
+- **The composer draws a pointer as the name it points at, never as the token.** Where `reference` sources are
+  declared the input is a Lexical editor rather than a textarea, and each pointer is one atomic node — a backspace
+  takes the whole thing rather than a character of a label that would then name nothing. Nothing above it changes:
+  the node's text content *is* the `@[…](mention:…)` token, so the draft string the chat reads, the `@` query, the
+  chips, the wire and the server's framing all see what they always saw, and every offset the chat hands over is
+  an offset into that string. It is its own chunk behind the chat's, fetched only where a source was declared, and
+  `mentions={false}` keeps the plain textarea — for an app that overrides `AgentComposer`, or one that would
+  rather see the tokens it is sending. An override that draws its own textarea keeps working: it fills the
+  `inputRef` it is handed, and the chat reads the caret off that when no editor filled `handleRef`.
 - **`attach` and `voice` both carry functions, so a server layout cannot pass either.** A closure does not cross
   the RSC boundary — `non-scalar-props-restricted` says so on `page/**` — so an app that wants either mounts the
   chat from a small client component in the app's own `ui/` that calls the hook.
@@ -224,6 +309,14 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   `data-akan-action` like a store setter does. A `remove*` name defaults to a confirm gate. Reach a store action
   from the body — `.exec((id) => st.do.removeX(id))` — which is how an agent gets CRUD; `st.do` on its own
   reaches nobody.
+- **`.card()` is the other way the chain ends, for an answer that is the user's to give.** Where `.exec()` runs a
+  function, `.card(({ submit, cancel }, ...args) => <Form …/>)` parks the call in the chat and renders the app's own
+  component there; what `submit` is handed is what the model reads back, and `cancel` is the refusal it reads
+  instead. A name and a phone number, a date somebody has to look up, a signature — a model that fills those in
+  has answered its own question, and every other shape of "ask the user" is `askUser`. The declared arguments are
+  checked **before** the card is parked, so a bad one reaches the model as a refusal rather than throwing inside
+  the render; `confirm` is not read at all, because the card in front of the user is already the asking. The frame
+  draws its own way out even when the card does not, and the turn is never parked on something with no exit.
 - **The second argument is how the call behaves, never what it is.** `{ settle, confirm, guard }`:
   `settle: false` marks a read that returns what is already there and skips the wait; every other tool is waited
   out before its effect on the screen is reported, because a write may still be landing when `exec` resolves. A
@@ -459,18 +552,29 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
 - **A long conversation summarizes itself, because nothing else is keeping it inside the model's window.** The
   loop runs in the browser and the relay holds no session, so an uncompacted chat grows until the provider
   refuses the whole request — a refusal, never a shorter answer, which is why compaction runs *before* the turn
-  that would have overflowed rather than as a recovery after it. Past `compact.at` estimated tokens (four
-  characters to a token, over the JSON the turn posts; 24k by default, well under the smallest window a provider
-  is likely to have, since the tools and the screen context ride on top of it and neither compacts) the history above the last `keep` messages
-  becomes one message standing in for it, flagged `summary` on the wire — `<Agent.Chat compact={{ at, keep }} />`
-  tunes it per provider and `{ at: 0 }` turns it off, and `/compact` does the same on demand keeping nothing.
+  that would have overflowed. **Two triggers, each before every assistant turn.** `compact.at` is a ceiling on
+  cost: past that many estimated transcript tokens (four characters to a token, over the JSON the turn posts —
+  except an inlined picture, counted at the ~1,600 tokens a provider bills for its pixels rather than its base64;
+  24k by default) the history compacts, because the relay resends the whole transcript every turn and the app
+  pays for each one. The **window guard** compacts once the prompt nears the window the server reports —
+  `window − answer ceiling (8,192 when unreported) − compact.buffer (13,000, the margin Claude Code leaves)` —
+  measured by the provider's own count of the last turn (`done.usage`, kept on that assistant message) plus the
+  four-character estimate for what arrived since, so a Korean transcript the character rule reads as small is
+  still caught. The window comes from `option.setLlm({ contextWindow })` or from the first refusal that names it;
+  with neither, only the ceiling runs. **A refusal for length is answered once**: a relay flags it `overflow` on
+  the wire, and the session compacts and sends the same turn again, and a second refusal in the same send fails
+  with `agent.error.contextOverflow`. Either way the history above the last `keep` messages
+  becomes one message standing in for it, flagged `summary` on the wire — `<Agent.Chat compact={{ at, keep, buffer }} />`
+  tunes it, `{ at: Infinity }` leaves only the window guard, `{ at: 0 }` turns off the ceiling, the guard and the recovery alike, and `/compact` does
+  the same on demand keeping nothing. The header draws the estimate against whichever trigger is nearer.
   **The cut never lands on a `tool` message**: the kept half may not open with a result whose call was summarized
   away, a shape every provider dialect rejects. A user message is preferred where the tail holds one — everything
   above it is settled — but one assistant turn that ran ten tools has none, and that is the transcript that
   outgrows the window, so a cut there opens on the assistant message instead. The summarizing
   turn carries no tools and no screen context — it summarizes the conversation, it does not act on it — and it is
   fed a *bounded* digest rather than the transcript itself, since the transcript being summarized is the one that
-  no longer fits. A summary that cannot be produced leaves the transcript alone, the turn goes out as it would
+  no longer fits. The previous summary is the exception: it rides the digest whole, under its own label and outside
+  the bound, because it is the only record of what was compacted before it. A summary that cannot be produced leaves the transcript alone, the turn goes out as it would
   have, and the next one asks again — a summarizer that was momentarily unreachable says nothing about whether
   this transcript can shrink. One that *landed* and shrank nothing does, so that one is not retried until another
   threshold's worth has been added. On the
@@ -622,4 +726,76 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   is among them. The loop parks on the question exactly as it parks on an approval, a dismissal is the tool's
   error result rather than a silent empty answer, and the settled exchange renders as question-and-answer instead
   of a tool row. **Never re-implement it per screen** — a `st.tool("askAboutX")` that opens a modal is the same
-  thing with a worse transcript — and a hook tool named `askUser` shadows it like any other built-in.
+  thing with a worse transcript — and a hook tool named `askUser` shadows it like any other built-in. The line
+  between it and a `.card()` tool is what the answer *is*: a sentence or a pick off a list is `askUser` and belongs
+  to the conversation, while a shape the model must not invent — fields, a form, a signature — is a card the screen
+  declares, because only the screen knows what filling it in looks like.
+
+## What The Page Draws
+- **The page shows the agent's work, not just the transcript.** A chat panel is closed as often as it is open, and
+  a form that fills itself or a tab that switches on its own is a change the user watches happen with nothing
+  anywhere attributing it. So **the control a call was published from is ringed** where it stands, scrolled to
+  first when it is off screen, and **a pointer travels to it and presses it** — both on by default, and both
+  driven from the tool call itself rather than from a store action, which cannot tell the agent's write from the
+  user's.
+- **It costs an app nothing, for the same reason `data-akan-action` does.** `onChange={st.do.setTitleOnTask}` by
+  reference is what annotates the control, and the annotation is what makes it findable — so the fields and verbs
+  that matter light up with no code. An inline arrow publishes no tool, carries no annotation, and therefore
+  draws nothing: one wrapper silently costs three things at once.
+- **For a control the framework did not render, spread `agentAttrs`** from `akanjs/ui`:
+  `<button {...agentAttrs(run)} onClick={run}>`, where `run` is what `st.tool(…).exec(…)` returned. It reads the
+  name off the callable, so there is nothing to keep in sync and no `ref` to thread — and it earns the same E2E
+  selector and accessibility name an `akanjs/ui` control has. Never hand-write `data-akan-*`.
+- **A control that shares its handler with its siblings takes a key**: `agentAttrs(switchTab, menu)`, in the same
+  vocabulary the call's argument uses. One tool serves a whole tab strip or a whole list, so without it every
+  namesake is interchangeable in the DOM and the page can say *what* the agent did but never *where* — which the
+  no-guessing rule then turns into drawing nothing. `Tab.Menu` passes its `menu` key; do the same for a row verb
+  whose id the call names.
+- **Almost nothing is waited on.** The call starts the moment the effect is handed its event; a ring that lands a
+  frame later costs the turn nothing, and an animation that held a call would make the agent slower for a
+  decoration. A turn past four scrolls stops scrolling and keeps ringing — eight scrolls across a page is motion
+  sickness rather than attribution. **The one exception is `navigate`**, whose press has to land before the router
+  replaces the tree the link is in; it is capped at 600ms and the call goes either way.
+- **What it refuses to draw is the point.** A name several rows answer to rings nothing rather than guessing a row,
+  a call an approval or a guard turned back is never drawn at all, a tool no control carries draws nothing, and a
+  backgrounded tab draws nothing. A ring on the wrong element is worse than no ring: it is the screen telling the
+  user something untrue about what just happened. **A control the screen is not actually showing is not pointed at
+  either, and the pointer goes rather than travelling to it**: `checkVisibility` answers about an element alone, so
+  one under a modal's backdrop, inside a drawer that has slid off, or faded to nothing all pass it while being
+  invisible, and a pointer sent there lands on a blank patch of overlay. The test is `elementFromPoint` at the
+  control's own centre, taken after the reveal has settled. **`navigate` is mostly in that last class** — the router is not
+  an element, so it draws nothing. A bar across the top of the page was tried for it and removed: it read as
+  chrome the page had grown rather than as the agent doing something, which is the opposite of attribution. What
+  it does draw is the **link already on screen that goes where it is going**, when exactly one does and the user
+  can already see it: that one is an element, and the pointer presses it before the route moves. Addresses are
+  compared as routes (`router.routeOf`), since the locale and base-path segments are on the `<a>` and never on the
+  tool argument. An off-screen link is left alone — scrolling to a link and then leaving the page it is on is two
+  motions for one act. **Link presence is a drawing condition, never a permission one**: the agent may navigate
+  anywhere the user could type, and a zone that must not leave one screen drops `navigate` through `builtins`.
+- **Turn it off with `visual`** on `Agent.Chat` / `Agent.Zone` — `false` for all of it, `{ cursor: false }` or
+  `{ reveal: false }` for one effect. The pointer is chrome (`data-agent-ui`, `aria-hidden`,
+  `pointer-events: none`), so `readScreen` never reads it back and `highlight` can never aim at it.
+- **`ToolActivity` is the channel underneath**, a `ToolRunner` host option and an `AgentSession.onActivity`, firing
+  `start` / `end` around the execution alone. It is deliberately not `progress`: that one fires only for a tool
+  that chose to report, and a tool that says nothing about itself is exactly the one whose effect arrives
+  unexplained. The `start` may answer a promise, and the call waits for it — the whole of what makes drawing a
+  click on a link possible.
+- **`AgentSession.onTurn(running)` is the other half**, and the unit the pointer's life is measured in. A model's
+  calls arrive with its own writing between them, seconds each, so a pointer that lived for the length of a *call*
+  spent every turn vanishing and coming back. Only the conversation loop reports there — `compact` runs under the
+  same internal flag and drives nothing on screen.
+- **The pointer presses on arrival, never on departure** — a press fired as it leaves is a click on whatever it
+  was still over. It glides only when the hop is far enough to be worth following (a third of a second to cross
+  fifty pixels reads as lag, not motion), and teleports otherwise. It appears at the first control it presses,
+  **drifts clear of what it pressed** and waits out the gap between calls there as a spinner — a person clicks and
+  takes the hand away, and a spinner left sitting on the button covers the change it just caused — and fades when
+  the turn ends; **a turn that
+  drove no control draws no pointer at all**, since parking one in a corner for a turn that only answered a
+  question claims something that did not happen. While a reveal scrolls, it holds still — as a person's does — and
+  carries a chevron pointing the way the view is travelling, because stillness over a sliding page otherwise reads
+  as a pointer that has come loose rather than as the one doing the scrolling. The ring answers *where* and the
+  pointer answers *who*, which is why they are one default rather than two.
+- **A form patch fans out over the fields it named.** `fill<Model>Form` is published by the form rather than by any
+  one control, so it rings one control per field in the arguments — resolved through the same
+  `data-akan-state="<model>Form.<field>"` the setter annotates — capped at five. `writeOn<Model>(path, value)`
+  draws nothing, for the same reason it carries no annotation: there is no control to put one on.