@akanjs/cli 3.0.0-beta.1 → 3.0.0-beta.11

package/.build-stamp

@@ -1 +1 @@
-d72ecb79076daa348d8166c58417584a4ceda3a467c9d1a7ca95d7d85863822a
+14dcf08e297228b84d390560fb0b666562b61989362641c9027868a93d4c503a

package/TunnelShare-sbsaggmb.js

@@ -0,0 +1,9 @@
+// @bun
+import {
+  TunnelShare2
+} from "./index-jcekapz4.js";
+import"./index-bw2marpf.js";
+import"./index-q0y2jq9j.js";
+export {
+  TunnelShare2 as TunnelShare
+};

package/{abstractCompactor-mjh5ppsq.js → abstractCompactor-bqh31fk5.js}

@@ -1,8 +1,9 @@
 // @bun
 import"./index-q0y2jq9j.js";
+import"./index-bw2marpf.js";
 import {
   AiSession
-} from "./index-kn1h7p1x.js";
+} from "./index-yc1keaer.js";
 import {
   AbstractDoc
 } from "./index-meh558jy.js";

package/{agent.command-d2gfxfck.js → agent.command-7357vxd8.js}

@@ -2,17 +2,17 @@
 import {
   Workspace,
   command
-} from "./index-mak3cd28.js";
+} from "./index-b3ae16mg.js";
 import"./index-q0y2jq9j.js";
-import"./index-2tv3fdx4.js";
+import"./index-5nyznra1.js";
 import"./index-6wwzs1bc.js";
 import"./index-by5gpp8x.js";
-import"./index-gyd220p2.js";
-import"./index-ktb5njgy.js";
+import"./index-jwjaf9fy.js";
+import"./index-15r9a10e.js";
 import"./index-h7yw2z9n.js";
 import {
   AgentScript
-} from "./index-ne2qy0nk.js";
+} from "./index-s3fvrydw.js";
 
 // pkgs/@akanjs/cli/agent/agent.command.ts
 class AgentCommand extends command("agent", [AgentScript], ({ public: target }) => ({

package/{application.command-pj2m7584.js → application.command-pc8mdn3w.js}

@@ -6,22 +6,22 @@ import {
   Exec,
   Workspace,
   command
-} from "./index-mak3cd28.js";
+} from "./index-b3ae16mg.js";
 import"./index-q0y2jq9j.js";
-import"./index-2tv3fdx4.js";
+import"./index-5nyznra1.js";
 import"./index-6wwzs1bc.js";
 import {
   ApplicationScript
-} from "./index-v0qh106m.js";
-import"./index-259dsnz3.js";
+} from "./index-r8bd61d9.js";
+import"./index-1nwxbr2y.js";
 import"./index-hwkygn9s.js";
-import {
-  AbstractDoc
-} from "./index-meh558jy.js";
-import"./index-j9yhg404.js";
+import"./index-ys7dvdb3.js";
 import {
   getMobileTargetChoices
 } from "./index-47pj3aee.js";
+import {
+  AbstractDoc
+} from "./index-meh558jy.js";
 
 // pkgs/@akanjs/cli/application/application.command.ts
 import { select } from "@inquirer/prompts";
@@ -106,8 +106,8 @@ class ApplicationCommand extends command("application", [ApplicationScript], ({
   start: target({ short: true, desc: "Start development server(s) (frontend SSR + backend)" }).with(Apps).option("plain", Boolean, { desc: "print prefixed lines instead of the full-screen view", default: false }).option("kill", Boolean, { flag: "k", desc: "free the dev ports first, whoever is holding them", default: false }).option("concurrency", Number, {
     desc: "apps to boot at a time (default: what this machine's memory and cores allow)",
     nullable: true
-  }).option("dbup", Boolean, { desc: "start the local database first", default: true }).option("open", Boolean, { desc: "open web browser?", default: false }).option("write", Boolean, { desc: "write code generation", default: true }).exec(async function(apps, plain, kill, concurrency, dbup, open, write) {
-    await this.applicationScript.start(apps, { plain, kill, concurrency, dbup, open, write });
+  }).option("dbup", Boolean, { desc: "start the local database first", default: true }).option("open", Boolean, { desc: "open web browser?", default: false }).option("share", Boolean, { desc: "also share each app on a public URL through an akan tunnel", default: false }).option("write", Boolean, { desc: "write code generation", default: true }).exec(async function(apps, plain, kill, concurrency, dbup, open, share, write) {
+    await this.applicationScript.start(apps, { plain, kill, concurrency, dbup, open, share, write });
   }),
   startIos: target({ short: true, desc: "Start iOS app in simulator or device" }).with(App).option("target", String, mobileTargetOption).option("env", String, {
     enum: ["local", "debug", "develop", "main"],

package/{applicationBuildRunner-kxwbssgn.js → applicationBuildRunner-4f1wrba0.js}

@@ -1,14 +1,14 @@
 // @bun
 import {
   Spinner
-} from "./index-2tv3fdx4.js";
+} from "./index-5nyznra1.js";
 import {
   AllRoutesBuilder,
   CsrArtifactBuilder,
   FontPruner,
   precompressArtifacts,
   SsrBaseArtifactBuilder
-} from "./index-a64esmtb.js";
+} from "./index-vrwdx0zx.js";
 import"./index-w8kmx1b6.js";
 import"./index-q0y2jq9j.js";
 import"./index-hwkygn9s.js";

package/{applicationReleasePackager-4yasxwv9.js → applicationReleasePackager-jkjmy5ee.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-q0y2jq9j.js";
 import {
   Spinner
-} from "./index-2tv3fdx4.js";
+} from "./index-5nyznra1.js";
 
 // pkgs/@akanjs/devkit/applicationReleasePackager.ts
 import { cp, mkdir, rm } from "fs/promises";

package/buildBatch.proc.js

@@ -2,7 +2,7 @@
 import {
   WorkspaceExecutor,
   AppExecutor
-} from "./index-2tv3fdx4.js";
+} from "./index-5nyznra1.js";
 import"./index-q0y2jq9j.js";
 import"./index-6wwzs1bc.js";
 import {
@@ -11,7 +11,7 @@ import {
   CsrArtifactBuilder,
   FontOptimizer,
   SsrBaseArtifactBuilder
-} from "./index-a64esmtb.js";
+} from "./index-vrwdx0zx.js";
 import"./index-w8kmx1b6.js";
 import"./index-hwkygn9s.js";
 import"./index-n68jx79w.js";

package/{capacitorApp-36rbr858.js → capacitorApp-hqvsrec4.js}

@@ -2,8 +2,8 @@
 import {
   isPlaceholderAppId2,
   CapacitorApp2
-} from "./index-wt7qrtd4.js";
-import"./index-2tv3fdx4.js";
+} from "./index-7f4dsf9v.js";
+import"./index-5nyznra1.js";
 import"./index-6wwzs1bc.js";
 import"./index-q0y2jq9j.js";
 export {

package/{cloud.command-jshwdq22.js → cloud.command-cawrd5nq.js}

@@ -2,29 +2,30 @@
 import"./index-q0y2jq9j.js";
 import {
   GlobalConfig
-} from "./index-kn1h7p1x.js";
+} from "./index-bw2marpf.js";
 import {
   Workspace,
   command
-} from "./index-mak3cd28.js";
-import"./index-2tv3fdx4.js";
+} from "./index-b3ae16mg.js";
+import"./index-5nyznra1.js";
 import"./index-6wwzs1bc.js";
-import"./index-v0qh106m.js";
-import"./index-259dsnz3.js";
+import"./index-yc1keaer.js";
+import"./index-r8bd61d9.js";
+import"./index-1nwxbr2y.js";
 import"./index-hwkygn9s.js";
 import"./index-kcxmv48c.js";
-import"./index-ws5e0j51.js";
-import"./index-2hq52jq3.js";
+import"./index-t8gvwcrx.js";
+import"./index-8tfmh0v6.js";
 import {
-  CloudScript
-} from "./index-zry5nz81.js";
-import"./index-j9yhg404.js";
+  CloudScript2
+} from "./index-ay8wj00x.js";
+import"./index-ys7dvdb3.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.command.ts
 var localRegistryUrl = () => process.env.AKAN_NPM_REGISTRY ?? "http://127.0.0.1:4873";
 var resolveRegistryUrl = (registry) => registry === "local" ? localRegistryUrl() : undefined;
 
-class CloudCommand extends command("cloud", [CloudScript], ({ public: target }) => ({
+class CloudCommand extends command("cloud", [CloudScript2], ({ public: target }) => ({
   login: target({ desc: "Login to Akan Cloud services" }).option("host", String, { desc: "host of the cloud", default: GlobalConfig.akanCloudHost }).with(Workspace).exec(async function(host, workspace) {
     await this.cloudScript.login(workspace, host);
   }),

package/cloud.script-1bmptvw0.js

@@ -0,0 +1,20 @@
+// @bun
+import {
+  CloudScript2
+} from "./index-ay8wj00x.js";
+import"./index-8tfmh0v6.js";
+import"./index-r8bd61d9.js";
+import"./index-ys7dvdb3.js";
+import"./index-1nwxbr2y.js";
+import"./index-t8gvwcrx.js";
+import"./index-yc1keaer.js";
+import"./index-bw2marpf.js";
+import"./index-b3ae16mg.js";
+import"./index-hwkygn9s.js";
+import"./index-5nyznra1.js";
+import"./index-6wwzs1bc.js";
+import"./index-kcxmv48c.js";
+import"./index-q0y2jq9j.js";
+export {
+  CloudScript2 as CloudScript
+};

package/commandManifest.json

@@ -1 +1 @@
-{"byCommand":{"create-workspace":"workspace","generate-agent-rules":"workspace","lint":"workspace","lint-all":"workspace","sync-all":"workspace","init":"workspace","agent":"agent","create-application":"application","remove-application":"application","plan-slice":"application","sync":"application","compact":"application","script":"application","console":"application","logs":"application","build":"application","b":"application","typecheck":"application","t":"application","test":"application","build-ios":"application","bi":"application","build-android":"application","ba":"application","start":"application","s":"application","start-ios":"application","si":"application","start-android":"application","sa":"application","release-ios":"application","release-android":"application","release-source":"application","codepush":"application","dbup":"application","dbdown":"application","configure-app":"application","create-library":"library","remove-library":"library","sync-library":"library","library-status":"library","install-library":"library","start-registry":"localRegistry","reset-registry":"localRegistry","smoke-registry":"localRegistry","version":"package","create-package":"package","remove-package":"package","sync-package":"package","build-package":"package","verify-dist-package":"package","verify-akan-publish-packages":"package","create-module":"module","remove-module":"module","create-service":"module","create-view":"module","create-unit":"module","create-template":"module","create-crud-page":"page","context":"context","doctor":"context","mcp-install":"context","mcp":"context","mcp-call":"context","login":"cloud","logout":"cloud","set-llm":"cloud","reset-llm":"cloud","ask":"cloud","deploy-akan":"cloud","update":"cloud","download-env":"cloud","upload-env":"cloud","subspace":"subspace","guideline":"guideline","generate-instruction":"guideline","update-instruction":"guideline","generate-document":"guideline","reapply-instruction":"guideline","create-scalar":"scalar","remove-scalar":"scalar","create-ui":"primitive","add-field":"primitive","add-enum-field":"primitive","quality":"quality","repair":"repair","workflow":"workflow"}}
+{"byCommand":{"create-workspace":"workspace","generate-agent-rules":"workspace","lint":"workspace","lint-all":"workspace","sync-all":"workspace","init":"workspace","agent":"agent","create-application":"application","remove-application":"application","plan-slice":"application","sync":"application","compact":"application","script":"application","console":"application","logs":"application","build":"application","b":"application","typecheck":"application","t":"application","test":"application","build-ios":"application","bi":"application","build-android":"application","ba":"application","start":"application","s":"application","start-ios":"application","si":"application","start-android":"application","sa":"application","release-ios":"application","release-android":"application","release-source":"application","codepush":"application","dbup":"application","dbdown":"application","configure-app":"application","create-library":"library","remove-library":"library","sync-library":"library","library-status":"library","install-library":"library","start-registry":"localRegistry","reset-registry":"localRegistry","smoke-registry":"localRegistry","version":"package","create-package":"package","remove-package":"package","sync-package":"package","build-package":"package","verify-dist-package":"package","verify-akan-publish-packages":"package","create-module":"module","remove-module":"module","create-service":"module","create-view":"module","create-unit":"module","create-template":"module","create-crud-page":"page","context":"context","doctor":"context","mcp-install":"context","mcp":"context","mcp-call":"context","login":"cloud","logout":"cloud","set-llm":"cloud","reset-llm":"cloud","ask":"cloud","deploy-akan":"cloud","update":"cloud","download-env":"cloud","upload-env":"cloud","subspace":"subspace","guideline":"guideline","generate-instruction":"guideline","update-instruction":"guideline","generate-document":"guideline","reapply-instruction":"guideline","create-scalar":"scalar","remove-scalar":"scalar","create-ui":"primitive","add-field":"primitive","add-enum-field":"primitive","quality":"quality","repair":"repair","workflow":"workflow","tunnel":"tunnel"}}

package/{context.command-ez8a0zyz.js → context.command-982b6kdp.js}

@@ -2,25 +2,26 @@
 import {
   Workspace,
   command
-} from "./index-mak3cd28.js";
+} from "./index-b3ae16mg.js";
 import"./index-q0y2jq9j.js";
-import"./index-2tv3fdx4.js";
+import"./index-5nyznra1.js";
 import"./index-6wwzs1bc.js";
 import"./index-by5gpp8x.js";
-import"./index-gyd220p2.js";
-import"./index-ktb5njgy.js";
+import"./index-jwjaf9fy.js";
+import"./index-15r9a10e.js";
 import {
   ContextScript
-} from "./index-600zhnve.js";
-import"./index-wt7qrtd4.js";
+} from "./index-3pvkjza8.js";
+import"./index-7f4dsf9v.js";
 import"./index-h7yw2z9n.js";
-import"./index-fz5q3gd7.js";
-import"./index-7737gxcp.js";
-import"./index-kn1h7p1x.js";
-import"./index-8pm30m73.js";
-import"./index-pnqbkf5p.js";
-import"./index-4edzf1gr.js";
-import"./index-rwg2aa4f.js";
+import"./index-em4swemt.js";
+import"./index-8pkvrcv1.js";
+import"./index-bw2marpf.js";
+import"./index-yc1keaer.js";
+import"./index-fr2x3qvv.js";
+import"./index-sh88vtye.js";
+import"./index-kbsach1y.js";
+import"./index-ceph7zqj.js";
 
 // pkgs/@akanjs/cli/context/context.command.ts
 class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({

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

@@ -4,34 +4,14 @@ import {
   plainTextOf,
   HOST_SOURCE,
   DevLogBuffer
-} from "./index-v0qh106m.js";
+} from "./index-r8bd61d9.js";
+import {
+  writeClipboard
+} from "./index-p6pbz9n5.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";

package/{devTuiView-c08ccbat.js → devTuiView-40jvjnyz.js}

@@ -1,7 +1,7 @@
 // @bun
 // pkgs/@akanjs/cli/application/devTuiView.ts
 var createDevTuiView = async (supervisor) => {
-  const { DevTui } = await import("./devTui-40ggmd99.js");
+  const { DevTui } = await import("./devTui-hmteztv3.js");
   return new DevTui(supervisor);
 };
 export {

package/{guideline.command-xmqwx8zm.js → guideline.command-jn0vwszx.js}

@@ -4,20 +4,21 @@ import {
   runner,
   script,
   command
-} from "./index-mak3cd28.js";
+} from "./index-b3ae16mg.js";
 import {
   FileSys
 } from "./index-q0y2jq9j.js";
-import"./index-2tv3fdx4.js";
+import"./index-5nyznra1.js";
 import {
   getDirname2
 } from "./index-6wwzs1bc.js";
 import {
   Prompter
 } from "./index-h7yw2z9n.js";
+import"./index-bw2marpf.js";
 import {
   AiSession
-} from "./index-kn1h7p1x.js";
+} from "./index-yc1keaer.js";
 
 // pkgs/@akanjs/cli/guideline/guideline.script.ts
 import { Logger } from "akanjs/common";

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`,
+  slots: `AgentLauncher`, `AgentSteps`, `AgentBubble`, `AgentComposer`, `AgentApproval`,
   `AgentQuestion`, `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.
@@ -110,8 +116,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 +128,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
@@ -141,6 +168,43 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   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,
   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.
 - **`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.
@@ -611,3 +675,44 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   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.
+
+## 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-*`.
+- **Nothing is ever 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 batch past four calls stops scrolling and keeps ringing — eight scrolls across a page is motion
+  sickness rather than attribution.
+- **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. **`navigate` is 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.
+- **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 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), teleports otherwise, and fades once the batch is over. 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.

package/guidelines/conventions/conventions.instruction.md

@@ -464,6 +464,24 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
 - **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it**
   — a room for a `pubsub` subscribe, the socket for a `message` handler. Cleanup that must happen either way
   registers for both.
+- **A call's deadline is the endpoint's `{ timeout: <ms> }`, and there is nowhere else to put one.** It bounds
+  both ends: the `Timeout` middleware — registered by default, and standing aside for every endpoint that
+  declares none — rejects the call with `base.error.gatewayTimeout`, and the same value is serialized to the
+  client as that call's request budget. Declared nowhere, a call takes the client's own default of **30
+  seconds**, so an endpoint whose real work runs longer (provisioning, a firmware flow, an external
+  orchestration) has to declare one or it dies mid-flight with a transport error that does not say whether the
+  server ever received it. A caller overrides it per call with `fetch.x(…, { timeout })` — `false` waits as long
+  as the runtime will — and an app moves its own default with `fetch.instance.setTimeout(ms)`. An upload is
+  never bounded. **Losing the race does not cancel the work**: the handler runs to completion with nobody
+  holding its result, so a deadline is an answer to the caller, not an undo.
+- **A cached answer is the endpoint's `{ cache: <ms> }`, and only a `query` taking no internal argument may have
+  one.** The `Cache` middleware is registered by default and stands aside for every endpoint that declares
+  nothing. Internal arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them
+  answers per caller and one shared entry would be one caller's answer handed to the next — that endpoint and
+  every `mutation` are named in the log and left uncached. Guards run on every hit; what is cached is the
+  handler's result, so `resolveReturn` still masks fields and resolves relations per call; a cache backend that
+  is down is warned about and the call runs uncached. The default chain is `Logging → Timeout → Cache → handler`,
+  and there is no `Retry` middleware.
 
 ### Authorization Defaults
 
@@ -727,6 +745,7 @@ what every developer must know even when not building one.
 - Put display and predicate logic on the `Light<Model>` class rather than in a util module — see Module File Playbook.
 - Defaults are a literal for scalars and a thunk for anything constructed. Arrays are `field([T])`; optional is the postfix `.optional()`.
 - **`field.visual(T)` is a field the page renders and an agent never sees** — a blur placeholder, a rendered HTML body, a serialized geometry. It stays an ordinary stored `property` (persistence, search, forms and the page response untouched) and is stripped wherever a value is masked for an AI caller: every in-page-agent read and every MCP result, along with the MCP readable schema. Unlike `hidden`/`secret` it is cost, not secrecy — nothing is refused over one. Reach for it whenever a field is bulky and useless to a model; that is cheaper than every tool learning to avoid it.
+- **A `field.hidden` / `field.secret` value reads `null` on the client, and the type still declares it.** `SignalContext.resolveReturn` skips both field types while it builds an endpoint's response, and hydration writes `null` over the key rather than leaving it absent — the first branch of the loop in `constant/getDefault.ts`, ahead of the field's own default. So the value is a deliberate `null` behind a type promising a `string`, every use of it typechecks, and the failure lands wherever it is finally dereferenced instead of where it was read. **Guard with `??` or `== null`**: `=== undefined`, a destructuring default and an optional parameter default all catch only a missing key and sail straight past this one. A projection (`pickById(id, { secret: true })`) widens the *server's* read, never the response. If a screen needs the value, the field is neither hidden nor secret; if it only needs to be cheap for a model rather than unseen, that is `field.visual`.
 
 ### Scalar & Field Type Reference
 

package/guidelines/fieldRule/fieldRule.instruction.md

@@ -9,6 +9,7 @@ Use this whenever generating constants or scalar constants. It defines the curre
 - `field(Type).optional()` marks a nullable or optional business value when absence is valid.
 - `field.hidden(Type).optional()` is for internal state that should not be treated as a normal public field.
 - `field.secret(Type).optional()` is for sensitive values that should not be selected by default.
+- Neither survives an endpoint response: both are stripped on the way out and hydration writes `null` over the key, while the generated type still declares the field — so a client holds a deliberate `null` behind a type that promises a value, and only `??` / `== null` catch it. A field a browser has to read is neither.
 - `field([Type])` defines arrays; provide empty array defaults when the app expects list operations.
 
 ## Current Akan Patterns

package/guidelines/transportRule/transportRule.instruction.md

@@ -28,6 +28,55 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   neither again, and cleanup that must happen either way registers for both. From a `message` handler it belongs to
   the socket and runs at close. A handler that throws is logged and never blocks the rest of the teardown.
 
+## Request Deadlines
+
+- **`{ timeout: <ms> }` in an endpoint's signal option is the whole configuration surface**, and it reaches both
+  ends of the call. Server side, the `Timeout` middleware races the handler against it and answers
+  `base.error.gatewayTimeout` (504) once it is spent. Client side, `FetchSerializer` ships the value on the
+  serialized endpoint and `fetch.<endpoint>()` uses it as that request's `AbortSignal.timeout` budget, so the
+  browser does not abandon a call the server is still allowed to be working on.
+- **The middleware is registered by default and has no default of its own.** An endpoint that declares no
+  `timeout` is passed straight through — a default here would put a deadline on every endpoint in the app that
+  nobody asked for, which is why the middleware used to be opt-in and, being opt-in, made the declared value
+  dead. It clears its timer in a `finally`: the race's loser is a pending timer per call otherwise, and with a
+  five-minute budget that is a five-minute hold on the event loop for a call that answered in a millisecond.
+- **Without a declaration the client's own default applies — 30 seconds** (`DEFAULT_TIMEOUT_MS`,
+  `fetch/client/httpClient.ts`), and the server imposes nothing. Nothing else bounds a request: `Bun.serve` runs
+  with `idleTimeout: 0`, so a long call is only ever ended by one of these two.
+- **Precedence is caller, then endpoint, then client default.** `fetch.x(…, { timeout: 5_000 })` overrides what
+  the endpoint declared; `{ timeout: false }` waits as long as the runtime will. An app moves its own default
+  with `fetch.instance.setTimeout(ms)` — `lib/useClient.ts` is generated, so the `timeout` option on
+  `FetchClient.build` belongs to the template that writes it, not to app code.
+- **A file upload is never bounded**, on any of those paths: a large body on a slow uplink is a request that is
+  working, and the request body is the only thing the client can tell that from.
+- **The deadline answers the caller; it does not undo the call.** `Promise.race` cannot cancel `next()`, so a
+  handler that timed out keeps running and keeps writing. Reach for a `timeout` to bound what a *caller* waits
+  for, not to bound an effect — an operation that must not half-happen needs its own idempotency or compensation.
+- The failure is the same `base.error.gatewayTimeout` key whichever side gave up, so the user reads one sentence
+  in their own language either way. What differs is the status code — 504 from the server's middleware, 408 from
+  the client's own abort — and nothing downstream branches on that.
+
+## Cached Answers
+
+- **`{ cache: <ms> }` in an endpoint's signal option is the whole cache surface.** The `Cache` middleware is
+  registered by default and stands aside unless an endpoint declares one — it used to be opt-in and to ignore the
+  declared value for a hard-coded 60 seconds, which is the same shape the `timeout` bug had.
+- **Only a `query` that takes no internal argument may carry one.** The handler's inputs are its declared
+  arguments plus its internal ones, so an endpoint with none of the latter answers the same thing to everyone who
+  may read it — which is the only answer a shared entry can hold. An endpoint that takes `.with(Self)` answers
+  per caller, and one entry would be one caller's answer handed to the next; that endpoint and every `mutation`
+  are named once in the log and left uncached rather than silently ignored.
+- **The guards run on every hit.** A cache hit skips `next()`, and `next()` is what runs them, so the middleware
+  calls `context.checkGuards()` itself before handing the entry over. Shared is not public.
+- **The entry is the handler's result, not the response.** The middleware wraps execution, so `resolveReturn`
+  still runs per call on the cached value — field masking, `hidden`/`secret` stripping and relation resolution are
+  never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
+- **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
+  uncached; a failed write is warned and dropped.
+- The default middleware chain is `Logging → Timeout → Cache → handler`: a hung cache backend is bounded by the
+  same deadline as the handler it stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
+  whose failure it cannot classify replays whatever the first attempt already did.
+
 ## Binary Pubsub
 
 - **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`

package/incrementalBuilder.proc.js

@@ -3,7 +3,7 @@ import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-2tv3fdx4.js";
+} from "./index-5nyznra1.js";
 import"./index-q0y2jq9j.js";
 import"./index-6wwzs1bc.js";
 import {