@akanjs/cli 3.0.0-beta.0 → 3.0.0-beta.10

package/.build-stamp

@@ -1 +1 @@
-65f8fdc9a4ad5e1054cf5bf3782626283fa2a2f9fc4e3079e0619ce0b60a4641
+248a5d65f363fd5a27c6caa9355adca9158d40d43304e82483ed913ef597f0ac

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

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

package/{agent.command-d2gfxfck.js → agent.command-0q17pnrs.js}

@@ -2,7 +2,7 @@
 import {
   Workspace,
   command
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import"./index-q0y2jq9j.js";
 import"./index-2tv3fdx4.js";
 import"./index-6wwzs1bc.js";
@@ -12,7 +12,7 @@ import"./index-ktb5njgy.js";
 import"./index-h7yw2z9n.js";
 import {
   AgentScript
-} from "./index-ne2qy0nk.js";
+} from "./index-k2j1hc4r.js";
 
 // pkgs/@akanjs/cli/agent/agent.command.ts
 class AgentCommand extends command("agent", [AgentScript], ({ public: target }) => ({

package/{application.command-pj2m7584.js → application.command-18y0s485.js}

@@ -6,14 +6,14 @@ import {
   Exec,
   Workspace,
   command
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import"./index-q0y2jq9j.js";
 import"./index-2tv3fdx4.js";
 import"./index-6wwzs1bc.js";
 import {
   ApplicationScript
-} from "./index-v0qh106m.js";
-import"./index-259dsnz3.js";
+} from "./index-sj5vxr8f.js";
+import"./index-vxtad5bd.js";
 import"./index-hwkygn9s.js";
 import {
   AbstractDoc

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

@@ -2,29 +2,30 @@
 import"./index-q0y2jq9j.js";
 import {
   GlobalConfig
-} from "./index-kn1h7p1x.js";
+} from "./index-m0xccmmm.js";
 import {
   Workspace,
   command
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import"./index-2tv3fdx4.js";
 import"./index-6wwzs1bc.js";
-import"./index-v0qh106m.js";
-import"./index-259dsnz3.js";
+import"./index-te54x9zm.js";
+import"./index-sj5vxr8f.js";
+import"./index-vxtad5bd.js";
 import"./index-hwkygn9s.js";
 import"./index-kcxmv48c.js";
-import"./index-ws5e0j51.js";
-import"./index-2hq52jq3.js";
+import"./index-9077wzd2.js";
+import"./index-rtxxan88.js";
 import {
-  CloudScript
-} from "./index-zry5nz81.js";
+  CloudScript2
+} from "./index-2xp0kfkt.js";
 import"./index-j9yhg404.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-cm11xjdz.js

@@ -0,0 +1,20 @@
+// @bun
+import {
+  CloudScript2
+} from "./index-2xp0kfkt.js";
+import"./index-rtxxan88.js";
+import"./index-sj5vxr8f.js";
+import"./index-j9yhg404.js";
+import"./index-vxtad5bd.js";
+import"./index-9077wzd2.js";
+import"./index-te54x9zm.js";
+import"./index-m0xccmmm.js";
+import"./index-0g7r8xz3.js";
+import"./index-hwkygn9s.js";
+import"./index-2tv3fdx4.js";
+import"./index-6wwzs1bc.js";
+import"./index-kcxmv48c.js";
+import"./index-q0y2jq9j.js";
+export {
+  CloudScript2 as CloudScript
+};

package/{context.command-ez8a0zyz.js → context.command-5v37ef3n.js}

@@ -2,7 +2,7 @@
 import {
   Workspace,
   command
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import"./index-q0y2jq9j.js";
 import"./index-2tv3fdx4.js";
 import"./index-6wwzs1bc.js";
@@ -11,16 +11,17 @@ import"./index-gyd220p2.js";
 import"./index-ktb5njgy.js";
 import {
   ContextScript
-} from "./index-600zhnve.js";
+} from "./index-y6n8nmny.js";
 import"./index-wt7qrtd4.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-04bk599g.js";
+import"./index-ffvk10zz.js";
+import"./index-m0xccmmm.js";
+import"./index-te54x9zm.js";
+import"./index-5ystnsd5.js";
+import"./index-vyvre9en.js";
+import"./index-d43r08tf.js";
+import"./index-a17x49vg.js";
 
 // pkgs/@akanjs/cli/context/context.command.ts
 class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({

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

@@ -4,7 +4,7 @@ import {
   plainTextOf,
   HOST_SOURCE,
   DevLogBuffer
-} from "./index-v0qh106m.js";
+} from "./index-sj5vxr8f.js";
 
 // pkgs/@akanjs/cli/application/devTui.tsx
 import { render } from "ink";

package/{devTuiView-c08ccbat.js → devTuiView-0hc2emhe.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-m1atgkc9.js");
   return new DevTui(supervisor);
 };
 export {

package/{guideline.command-xmqwx8zm.js → guideline.command-4pz9g1rt.js}

@@ -4,7 +4,7 @@ import {
   runner,
   script,
   command
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import {
   FileSys
 } from "./index-q0y2jq9j.js";
@@ -15,9 +15,10 @@ import {
 import {
   Prompter
 } from "./index-h7yw2z9n.js";
+import"./index-m0xccmmm.js";
 import {
   AiSession
-} from "./index-kn1h7p1x.js";
+} from "./index-te54x9zm.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.
@@ -72,9 +78,22 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   fills whichever adaptor holds `LlmAdaptorRole`, reaching it as the `llmOption` use. The settings are the role's
   rather than one provider's, so they survive a swap. **DeepSeek is the built-in default** (`deepseek-v4-flash` at
   `https://api.deepseek.com`); with no `apiKey` the app still boots and the chat answers `llmUnavailable`. Swap
-  providers the way middleware is applied: `option.applyAdaptor(LlmAdaptorRole, ClaudeLlm)`, where the
-  implementation is an `adapt()` class in a `srvkit/` implementing `LlmAdaptor.chat(request, onDelta?)` — ignore
-  `onDelta` and the chat still answers whole.
+  providers the way middleware is applied: `option.applyAdaptor(LlmAdaptorRole, AnthropicLlm)`. An app may still
+  write its own — an `adapt()` class in a `srvkit/` implementing `LlmAdaptor.chat(request, onDelta?)`, where
+  ignoring `onDelta` still answers whole — but for vision it no longer has to.
+- **Three providers ship, and only two of them read a picture.** `DeepseekLlm` is the default and declares no
+  `accepts`, which is a fact about its API rather than a gap. `OpenaiLlm` speaks the same chat-completions dialect
+  — `OpenaiDialect`, shared between them so a protocol fix lands once — against `https://api.openai.com/v1` and
+  declares `{ image: true }`, sending an image as a content part. `AnthropicLlm` is the Messages API and declares
+  `{ image: true, document: true }`; it is its own file rather than a branch, because the system prompt is a field
+  and not a message, tool calls and results are content blocks, the results ride in a *user* turn, roles must
+  alternate — so two wire turns that map to one role are merged — and `max_tokens` is required. **Both new ones
+  require `model`**: a default would age into a 404, and worse, it would decide the vision claim for the app.
+- **`accepts` is answered per model, through `option.setLlm({ accepts })`.** An adaptor answers for an API and one
+  API serves models that differ, so the override rides beside the `model` it is a fact about. It is not a table
+  the framework keeps: a table is a claim about models that ship after it, and getting this wrong is the worst
+  failure available — a provider handed bytes it cannot decode either refuses the turn or accepts it having seen
+  nothing, and the model then answers confidently about a file it never read.
 - **An adaptor answers `null` for "not configured" and *throws* for a refusal it can explain.** The two are
   different things to be told: collapsing both into `null`, the way the adapter convention otherwise reads, left a
   user reading `llmUnavailable` — "no model is configured" — about a conversation that had merely outgrown the
@@ -92,10 +111,14 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   prompt. **What the provider cannot read is replaced by a note naming the file**, never dropped: an attachment the
   model never saw is one it answers about from the filename. An adaptor declares `accepts: { image, document }` and
   `AgentService.readable` degrades the rest, so a text-only provider needs no attachment code at all — DeepSeek
-  declares none, which is why an image against the default provider is refused out loud while an extracted PDF
-  works, `text` being readable by every model there is. 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.
+  declares none, which is why an image against the *default* provider is refused out loud while an extracted PDF
+  works, `text` being readable by every model there is. Swap in `OpenaiLlm` or `AnthropicLlm` and the same image
+  arrives as an image. `accepts.document` is one boolean over every non-image type, so an adaptor whose API has a
+  block for only some of them — Anthropic's `document` is PDF and nothing else — names the rest in the text rather
+  than dropping them, which is the wire's own rule applied at the one layer that knows which blocks exist. Persisting keeps each
+  attachment's name, 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
@@ -105,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
@@ -125,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.

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
 
@@ -696,7 +714,9 @@ what every developer must know even when not building one.
   every tool runs in the caller's own browser session, gated by guards and the approval card. Its guard is
   `AgentRelayAccess`, which refuses every call until the app names a guard of its own —
   `option.setAgentAccess(SignedIn)`. **The LLM is configured in `option.ts`, never through the environment**
-  (`option.setLlm({ apiKey, model, host })`).
+  (`option.setLlm({ apiKey, model, host })`). Three providers ship — `DeepseekLlm` (the default, text only),
+  `OpenaiLlm` and `AnthropicLlm` (both read images) — and swapping one in is
+  `option.applyAdaptor(LlmAdaptorRole, AnthropicLlm)`.
 - **Declare the tool beside the control that already does it**, never as a separate surface:
   `st.tool("x").desc("…").arg("id", ID).exec(fn)` returns the callable to hand to `onClick` — one handler for the
   person and the agent. Publish it only where the screen already renders the control; a falsy name declares the
@@ -725,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/{index-fz5q3gd7.js → index-04bk599g.js}

@@ -11,7 +11,7 @@ import {
 } from "./index-ktb5njgy.js";
 import {
   runner
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 
 // pkgs/@akanjs/cli/repair/repair.runner.ts
 var commandForShell = (command) => command.startsWith("akan ") ? `bun run ${command}` : command;

package/{index-zry5nz81.js → index-2xp0kfkt.js}

@@ -1,28 +1,30 @@
 // @bun
 import {
   GlobalConfig,
-  CloudApi,
-  AiSession
-} from "./index-kn1h7p1x.js";
+  CloudApi
+} from "./index-m0xccmmm.js";
 import {
   PkgExecutor
 } from "./index-2tv3fdx4.js";
+import {
+  AiSession
+} from "./index-te54x9zm.js";
 import {
   script
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import {
   ApplicationScript
-} from "./index-v0qh106m.js";
+} from "./index-sj5vxr8f.js";
 import {
   PackageScript
-} from "./index-ws5e0j51.js";
+} from "./index-9077wzd2.js";
 import {
   CloudRunner
-} from "./index-2hq52jq3.js";
+} from "./index-rtxxan88.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.script.ts
 import { Logger } from "akanjs/common";
-class CloudScript extends script("cloud", [CloudRunner, ApplicationScript, PackageScript]) {
+class CloudScript2 extends script("cloud", [CloudRunner, ApplicationScript, PackageScript]) {
   async login(workspace, host = GlobalConfig.akanCloudHost) {
     await this.cloudRunner.login(host, workspace);
   }
@@ -48,16 +50,23 @@ class CloudScript extends script("cloud", [CloudRunner, ApplicationScript, Packa
     }
     await this.cloudRunner.downloadEnvByScp(workspace);
   }
-  async uploadEnv(workspace, { host = GlobalConfig.akanCloudHost } = {}) {
-    const workspaceId = workspace.getWorkspaceId({ allowEmpty: true });
-    const { path } = await this.cloudRunner.gatherEnvFiles(workspace);
+  async uploadEnv(workspace, {
+    host = GlobalConfig.akanCloudHost,
+    workspaceId = workspace.getWorkspaceId({ allowEmpty: true }),
+    scope,
+    archivePath
+  } = {}) {
+    if (scope && !workspaceId)
+      throw new Error("A scoped env upload needs a cloud workspace id \u2014 the scp target is workspace-wide.");
+    const { files, path } = await this.cloudRunner.gatherEnvFiles(workspace, { scope, archivePath });
     if (workspaceId) {
       await this.login(workspace, host);
       const cloudApi = await CloudApi.fromHost(workspace, host);
       await this.cloudRunner.uploadEnv(cloudApi, workspaceId, path);
-      return;
+      return { workspaceId, files };
     }
     await this.cloudRunner.uploadEnvByScp(workspace, path);
+    return { workspaceId: null, files };
   }
   async deployAkan(workspace, { test = true, registryUrl } = {}) {
     const akanPkgs = await this.cloudRunner.getAkanPkgs(workspace);
@@ -80,4 +89,4 @@ class CloudScript extends script("cloud", [CloudRunner, ApplicationScript, Packa
   }
 }
 
-export { CloudScript };
+export { CloudScript2 };

package/{index-8pm30m73.js → index-5ystnsd5.js}

@@ -2,16 +2,16 @@
 import {
   FileSys
 } from "./index-q0y2jq9j.js";
-import {
-  AiSession
-} from "./index-kn1h7p1x.js";
 import {
   ModuleExecutor
 } from "./index-2tv3fdx4.js";
+import {
+  AiSession
+} from "./index-te54x9zm.js";
 import {
   runner,
   script
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import {
   sourceFile,
   moduleSourcePaths,
@@ -22,7 +22,7 @@ import {
 } from "./index-gyd220p2.js";
 import {
   PageScript
-} from "./index-pnqbkf5p.js";
+} from "./index-vyvre9en.js";
 import {
   Prompter
 } from "./index-h7yw2z9n.js";

package/{index-ws5e0j51.js → index-9077wzd2.js}

@@ -2,7 +2,7 @@
 import {
   runner,
   script
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import {
   FileSys
 } from "./index-q0y2jq9j.js";

package/{index-rwg2aa4f.js → index-a17x49vg.js}

@@ -2,7 +2,7 @@
 import {
   runner,
   script
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import {
   generatedFilesForSync,
   createPassedPrimitiveReport,
@@ -10,7 +10,7 @@ import {
 } from "./index-gyd220p2.js";
 import {
   AiSession
-} from "./index-kn1h7p1x.js";
+} from "./index-te54x9zm.js";
 import {
   Prompter
 } from "./index-h7yw2z9n.js";

package/{index-4edzf1gr.js → index-d43r08tf.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   script
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import {
   AppExecutor,
   LibExecutor,
@@ -42,7 +42,7 @@ import {
 } from "./index-gyd220p2.js";
 import {
   ModuleScript
-} from "./index-8pm30m73.js";
+} from "./index-5ystnsd5.js";
 
 // pkgs/@akanjs/cli/primitive/primitive.script.ts
 import { capitalize } from "akanjs/common";

package/{index-7737gxcp.js → index-ffvk10zz.js}

@@ -26,7 +26,7 @@ import {
 } from "./index-ktb5njgy.js";
 import {
   runner
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 
 // pkgs/@akanjs/cli/workflow/workflow.runner.ts
 import { mkdir, readFile, writeFile } from "fs/promises";

package/{index-ne2qy0nk.js → index-k2j1hc4r.js}

@@ -2,7 +2,7 @@
 import {
   runner,
   script
-} from "./index-mak3cd28.js";
+} from "./index-0g7r8xz3.js";
 import {
   AGENT_BLOCK_START,
   AGENT_BLOCK_END,