@akanjs/cli 3.0.0-beta.2 → 3.0.0-beta.21

package/{devTui-40ggmd99.js → devTui-q7k7bakd.js}

@@ -1,37 +1,17 @@
 // @bun
 import {
-  openBrowser,
-  plainTextOf,
-  HOST_SOURCE,
-  DevLogBuffer
-} from "./index-v0qh106m.js";
+  stripAnsi
+} from "./index-7md2g9vw.js";
+import {
+  writeClipboard
+} from "./index-p6pbz9n5.js";
+import {
+  openBrowser
+} from "./index-9dp031by.js";
 
 // pkgs/@akanjs/cli/application/devTui.tsx
 import { render } from "ink";
 
-// pkgs/@akanjs/cli/clipboard.ts
-var clipboardCommands = () => {
-  if (process.platform === "darwin")
-    return [["pbcopy"]];
-  if (process.platform === "win32")
-    return [["clip"]];
-  return [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]];
-};
-var writeClipboard = async (text) => {
-  for (const command of clipboardCommands()) {
-    try {
-      const proc = Bun.spawn(command, {
-        stdin: new TextEncoder().encode(text),
-        stdout: "ignore",
-        stderr: "ignore"
-      });
-      if (await proc.exited === 0)
-        return true;
-    } catch {}
-  }
-  return false;
-};
-
 // pkgs/@akanjs/cli/ui/DevTuiApp.tsx
 import { Box, Text, useInput } from "ink";
 import { useEffect, useState } from "react";
@@ -176,6 +156,8 @@ var DevTuiApp = ({ actions }) => {
       actions.copyLines();
     else if (input === "Y")
       actions.copyPath();
+    else if (input === "s")
+      actions.copyShareUrl();
     else if (input === "o")
       actions.openSelected();
     else if (input === "r")
@@ -236,12 +218,95 @@ var DevTuiApp = ({ actions }) => {
       }, undefined, false, undefined, this) : /* @__PURE__ */ jsxDEV(Text, {
         dimColor: true,
         wrap: "truncate",
-        children: `Tab next \xB7 1-9 app \xB7 \u2191\u2193 scroll (shift page) \xB7 G follow${snapshot.following ? "" : " (paused)"} \xB7 / grep${snapshot.grep ? ` (${snapshot.grep})` : ""} \xB7 e errors${snapshot.errorsOnly ? " on" : ""} \xB7 c clear \xB7 y copy \xB7 Y path \xB7 o open \xB7 r restart \xB7 q quit`
+        children: `${snapshot.hasShare ? "s share \xB7 " : ""}Tab next \xB7 1-9 app \xB7 \u2191\u2193 scroll (shift page) \xB7 G follow${snapshot.following ? "" : " (paused)"} \xB7 / grep${snapshot.grep ? ` (${snapshot.grep})` : ""} \xB7 e errors${snapshot.errorsOnly ? " on" : ""} \xB7 c clear \xB7 y copy \xB7 Y path \xB7 o open \xB7 r restart \xB7 q quit`
       }, undefined, false, undefined, this)
     ]
   }, undefined, true, undefined, this);
 };
 
+// pkgs/@akanjs/cli/application/devLogBuffer.ts
+var plainTextOf = (lines, { withApp = false } = {}) => {
+  const width = withApp ? lines.reduce((max, line) => Math.max(max, line.app.length), 0) : 0;
+  return lines.map((line) => `${withApp ? `${line.app.padEnd(width)} \u2502 ` : ""}${stripAnsi(line.text)}`).join(`
+`);
+};
+var HOST_SOURCE = "host";
+var childPrefix = /^\[child:(\d+) ([a-z-]+)\] \[(?:stdout|stderr)\] /;
+var sourceOf = (text) => {
+  const match = childPrefix.exec(text);
+  return match ? `#${match[1]} ${match[2]}` : HOST_SOURCE;
+};
+
+class DevLogBuffer {
+  static defaultLimit = 5000;
+  #limit;
+  #lines = [];
+  #partial = new Map;
+  #sources = new Map;
+  #seq = 0;
+  constructor({ limit = DevLogBuffer.defaultLimit } = {}) {
+    this.#limit = Math.max(1, limit);
+  }
+  get size() {
+    return this.#lines.length;
+  }
+  sourcesOf(app) {
+    return [...this.#sources.get(app) ?? []];
+  }
+  push(app, kind, chunk) {
+    const key = `${app}:${kind}`;
+    const parts = `${this.#partial.get(key) ?? ""}${chunk}`.split(`
+`);
+    this.#partial.set(key, parts.pop() ?? "");
+    return this.#append(app, kind, parts);
+  }
+  flushPartials() {
+    const flushed = [];
+    for (const [key, remainder] of [...this.#partial]) {
+      this.#partial.set(key, "");
+      if (!remainder)
+        continue;
+      const split = key.lastIndexOf(":");
+      const app = key.slice(0, split);
+      const kind = key.slice(split + 1) === "stderr" ? "stderr" : "stdout";
+      flushed.push(...this.#append(app, kind, [remainder]));
+    }
+    return flushed;
+  }
+  select({ app = null, source = null, grep, errorsOnly = false } = {}) {
+    const needle = grep?.trim().toLowerCase();
+    return this.#lines.filter((line) => {
+      if (app !== null && line.app !== app)
+        return false;
+      if (source !== null && line.source !== source)
+        return false;
+      if (errorsOnly && line.kind !== "stderr")
+        return false;
+      if (needle && !stripAnsi(line.text).toLowerCase().includes(needle))
+        return false;
+      return true;
+    });
+  }
+  clear(app = null) {
+    const kept = app === null ? [] : this.#lines.filter((line) => line.app !== app);
+    this.#lines.length = 0;
+    this.#lines.push(...kept);
+  }
+  #append(app, kind, texts) {
+    const known = this.#sources.get(app) ?? new Set;
+    this.#sources.set(app, known);
+    const added = texts.map((text) => {
+      const source = sourceOf(text);
+      known.add(source);
+      return { seq: ++this.#seq, app, source, kind, text };
+    });
+    this.#lines.push(...added);
+    if (this.#lines.length > this.#limit)
+      this.#lines.splice(0, this.#lines.length - this.#limit);
+    return added;
+  }
+}
+
 // pkgs/@akanjs/cli/application/devLogWindow.ts
 var windowOf = (lines, rows, anchor) => {
   const height = Math.max(1, Math.trunc(rows));
@@ -313,6 +378,7 @@ class DevTui {
         clear: this.#clear,
         copyLines: this.#copyLines,
         copyPath: this.#copyPath,
+        copyShareUrl: this.#copyShareUrl,
         openSelected: this.#openSelected,
         restartSelected: this.#restartSelected,
         quit: this.#quit
@@ -348,7 +414,7 @@ class DevTui {
       process.stdout.write(`${line.app} \u2502 ${line.text}
 `);
     for (const status of this.#statuses)
-      process.stdout.write(`${status.name} ${status.url} \u2014 ${status.state}
+      process.stdout.write(`${status.name} ${status.url}${status.shareUrl ? ` \xB7 ${status.shareUrl}` : ""} \u2014 ${status.state}
 `);
     const log = this.#supervisor.sessionLog;
     for (const name of log.appNames)
@@ -403,12 +469,12 @@ class DevTui {
     const logRows = Math.max(1, bodyHeight - DevTui.paneChromeRows);
     const rows = this.#railRows();
     const view = windowOf(this.#filtered(this.#target), logRows, this.#anchor);
-    const status = this.#statuses.find((candidate) => candidate.name === this.#target.app);
+    const status = this.#selectedStatus();
     const railLabelWidth = rows.reduce((max, row) => Math.max(max, row.label.length + row.depth * 2), 0);
     this.#cachedSnapshot = {
       rows,
       selected: this.#indexOfTarget(rows),
-      title: status ? `${status.name}${this.#target.source ? ` \xB7 ${this.#target.source}` : ""} \xB7 ${status.url} \xB7 ${status.state}${status.detail ? ` (${status.detail})` : ""}` : "all apps",
+      title: status ? `${status.name}${this.#target.source ? ` \xB7 ${this.#target.source}` : ""}${status.shareUrl ? ` \xB7 \u25C8 ${status.shareUrl}` : ""} \xB7 ${status.url} \xB7 ${status.state}${status.detail ? ` (${status.detail})` : ""}` : this.#mergedTitle(),
       lines: view.lines,
       above: view.above,
       below: view.below,
@@ -419,6 +485,7 @@ class DevTui {
       errorsOnly: this.#errorsOnly,
       editingGrep: this.#editingGrep,
       notice: this.#notice,
+      hasShare: this.#statuses.some((candidate) => !!candidate.shareUrl),
       readyCount: this.#statuses.filter((candidate) => candidate.state === "ready").length,
       appCount: this.#statuses.length,
       logRows,
@@ -467,8 +534,7 @@ class DevTui {
   };
   #setTarget(target) {
     this.#target = { app: target.app ?? null, source: target.source ?? null };
-    this.#anchor = null;
-    this.#renderNow();
+    this.#follow();
   }
   #scroll = (delta) => {
     this.#anchor = scrollAnchor(this.#filtered(this.#target), this.#snapshot().logRows, this.#anchor, delta);
@@ -480,8 +546,7 @@ class DevTui {
   };
   #setGrep = (grep) => {
     this.#grep = grep;
-    this.#anchor = null;
-    this.#renderNow();
+    this.#follow();
   };
   #setEditingGrep = (editing) => {
     this.#editingGrep = editing;
@@ -489,13 +554,11 @@ class DevTui {
   };
   #toggleErrorsOnly = () => {
     this.#errorsOnly = !this.#errorsOnly;
-    this.#anchor = null;
-    this.#renderNow();
+    this.#follow();
   };
   #clear = () => {
     this.#buffer.clear(this.#target.app ?? null);
-    this.#anchor = null;
-    this.#renderNow();
+    this.#follow();
   };
   #copyLines = () => {
     const lines = this.#filtered(this.#target);
@@ -520,6 +583,25 @@ class DevTui {
     const app = this.#target.app;
     return (app ? [app] : log.appNames).map((name) => log.relativePathOf(name));
   }
+  #copyShareUrl = () => {
+    const urls = this.#shareUrls();
+    if (urls.length === 0) {
+      this.#setNotice("no public share \u2014 start with --share");
+      return;
+    }
+    writeClipboard(urls.join(`
+`)).then((copied) => {
+      this.#setNotice(copied ? `copied ${urls.join(" \xB7 ")}` : urls.join(" \xB7 "));
+    });
+  };
+  #shareUrls() {
+    const app = this.#target.app;
+    return this.#statuses.filter((status) => app === null || status.name === app).map((status) => status.shareUrl).filter((url) => !!url);
+  }
+  #mergedTitle() {
+    const urls = this.#shareUrls();
+    return urls.length === 0 ? "all apps" : `all apps \xB7 \u25C8 ${urls.join(" \xB7 ")}`;
+  }
   #setNotice(text) {
     this.#notice = text;
     if (this.#noticeTimer)

package/fileSys-5ngz93ga.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  getDirname2,
+  FileSys2
+} from "./index-5b6tavv3.js";
+export {
+  FileSys2 as FileSys,
+  getDirname2 as getDirname
+};

package/guideline.command-7jk47fgq.js

@@ -0,0 +1,42 @@
+// @bun
+import {
+  script,
+  command
+} from "./index-rmcw8yc8.js";
+import"./index-5b6tavv3.js";
+import"./index-ga6hygxr.js";
+import {
+  Prompter2
+} from "./index-0bq14vr1.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

@@ -45,10 +45,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 +76,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 +133,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,6 +145,26 @@ 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.
+- **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
+  cannot gate one either. Both shipped vision adaptors therefore match an exact set (`jpeg`, `png`, `gif`, `webp`)
+  and name the rest in the text. It matters because an unsupported type is not one unread attachment: it is a
+  block the API refuses, so the **whole turn** dies on a vendor 400 — and `image/heic`, the iPhone camera default,
+  is the likeliest one an app meets.
 - **`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
@@ -137,10 +181,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.
@@ -212,6 +302,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
@@ -447,18 +545,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
@@ -610,4 +719,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.