@akanjs/cli 3.0.0-alpha.52 → 3.0.0-alpha.53

package/.build-stamp

@@ -1 +1 @@
-01ea8ed0ffbaa2533de87a90a0f930f8914cabb255e887095d14f13152decabd
+75e6ebc02c938b9bfa7b3bbce9bbe0a59753853c08b168184806c0321e3bb71e

package/{cloud.command-eqafzn1a.js → cloud.command-v5g0c7nm.js}

@@ -1,8 +1,8 @@
 // @bun
 import {
   CloudScript
-} from "./index-ssrz6xr1.js";
-import"./index-wmwcwn1f.js";
+} from "./index-rrcdemys.js";
+import"./index-d3vvvzsd.js";
 import"./index-x1dbhd80.js";
 import {
   GlobalConfig

package/guidelines/agentRule/agentRule.instruction.md

@@ -41,6 +41,9 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   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.
+  A manifest reaches a layout-mounted chat like any other component: the override provider wraps the whole layout
+  stack, root layouts included. `UiOverrideProvider` is also a public `akanjs/ui` export, for giving one mount site
+  a different slot map than its route would.
 - **The composer is a textarea**: Enter sends, Shift+Enter writes a newline, and it grows to a few lines before
   it scrolls. The vertical arrows still walk what was sent, but only from the first or last line — anywhere else
   the caret is the textarea's own. On a phone the panel is the whole screen (it is a card from `sm:` up) and it
@@ -116,12 +119,19 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
 
 ## Publishing A Tool
 - **Declare the tool beside the control that already does it.**
-  `st.tool("x", { desc }).arg("id", ID).exec(fn)` publishes one action and returns the callable to hand to
-  `onClick` — one handler for the person and the agent, which is the point: a button wired to an inline arrow can
-  be clicked by a person and by nobody else. `.exec()` is the only hook, so the chain completes in one
-  unconditional statement, and the callable carries `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.
+  `st.tool("x").desc("…").arg("id", ID).opt("force", Boolean).exec(fn)` publishes one action and returns the
+  callable to hand to `onClick` — one handler for the person and the agent, which is the point: a button wired to
+  an inline arrow can be clicked by a person and by nobody else. `.desc()` is required and comes first, `.arg()`
+  is an argument the caller must pass and `.opt()` one it may leave out (the `exec` parameter is then `| null`),
+  and `.exec()` is the only hook, so the chain completes in one unconditional statement and the callable carries
+  `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.
+- **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
+  tool that reads and one that writes are otherwise the same declaration — there is no taxonomy field, because
+  nothing downstream would read one.
 - **A falsy name declares the tool without publishing it** — the callable still drives the click a person makes,
   and the agent never learns the tool exists. That is the only way a conditional surface stays legal, because
   `.exec()` is a hook and the declaration can never be skipped: withhold the name, not the call. `st.useState`
@@ -132,7 +142,7 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
 - **An `enumOf` class is a complete argument type on its own**: `.arg("mode", TaskStatus)` publishes the values as
   the argument's `enum`, refuses anything off them by name at call time, and narrows the `.exec` parameter to the
   value union — nothing else to write, and the scalar (`string` / `integer` / `number`) comes from the values.
-  **A value set the *render* decides takes `.arg(name, type, { oneOf })`** instead, because `enumOf` registers
+  **A value set the *render* decides takes `.arg(name, type, { oneOf })`** (or `.opt`) instead, because `enumOf` registers
   globally and a component cannot build one per render: pass the list it has — a slice's sort keys, the options a
   prop carried — and it is published and enforced the same way. Neither reaches a set that fills in *after* the
   first render, since a declaration is mount-static; put that in the tool's `guard`, which is re-read per call and
@@ -145,10 +155,13 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   tool that captured its own row would be fifty registrations of one name, forty-nine of them shadowed, and the
   survivor would remove whichever row happened to mount last. Take the id instead — `removeTask(taskId)`, never
   fifty `removeTask` — and every row's registration is then interchangeable, so a row component may publish after
-  all: say so with `shared: true` and the repeats are one declaration rather than a warned-about clash. The ids
-  come from the `<slice>.items` resource `Load.Units` and `Data.ListContainer` already expose. `shared` is a claim
-  about the *tool*, not a way to quiet a console: two rows whose tools would do different things (a different
-  `modal`, a different redirect) are not interchangeable, and that one wants a `namespace` or nothing at all.
+  all. **Nothing is written to say so: the description says it.** Fifty rows of one component produce one name
+  and one `.desc()`, which is the same declaration fifty times over and warns about nothing; a second description
+  arriving under a name already taken is two components that happened to pick one word, and that warns. So the
+  rule an app follows is about the sentence, not about a flag — two tools that would do different things
+  (a different `modal`, a different redirect) cannot honestly share a description, and that pair wants a
+  `namespace` or nothing at all. The ids come from the `<slice>.items` resource `Load.Units` and
+  `Data.ListContainer` already expose.
 
 ## What `akanjs/ui` Publishes For You
 - **`akanjs/ui` publishes its own controls, so an app writes nothing for them.** `Data.ListContainer` (and every
@@ -199,9 +212,9 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   **The patch writes each plain field through that control's own published tool, not the setter underneath it** —
   which is what carries the control's `transform`, so a field cannot normalize one way for `setPhoneOnBizAccount`
   and another way for `fillBizAccountForm`. Only a composite, having no control, dispatches its setter directly.
-  The patch tool is registered `shared`, because the entry is a pure function of the model: a form put on screen by
-  a shell that subscribes it (`Model.EditModal`) *and* by the `Template` inside it is one declaration twice over,
-  not a clash — so neither has to suppress the other, and neither is asked to.
+  The patch tool's entry is a pure function of the model, so a form put on screen by a shell that subscribes it
+  (`Model.EditModal`) *and* by the `Template` inside it registers the same name with the same description twice
+  over — one declaration, not a clash. Neither has to suppress the other, and neither is asked to.
 - **A `disabled` control publishes nothing, so the agent never gets a lever the person cannot pull.** Every value
   control reads it — `Field.*`, `Input.*`, `Select`, `Switch`, and the four relation pickers — and disabling a
   mounted control withdraws its tool for as long as it stays disabled. One gate covers both writers: with no
@@ -271,18 +284,26 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   `Field.TextList` does, and the only place an inline arrow is the right answer rather than a bug.
 
 ## Reading State
-- **Reading is per key, not per store.** `st.useState(name, initial, meta)` publishes local state (read-only
-  unless `set:` names a type) and `st.expose(name, value)` a derived value. A subscribed store key is listed in
+- **Reading is per key, not per store.** `st.expose(name, Type).desc("…").value(v)` publishes a derived value and
+  `st.useState(name, Type, { set: true }).desc("…").init(initial)` local state, read-only without `set`. Both
+  end in a hook, so a conditional surface withholds the name rather than skipping the chain. A subscribed store key is listed in
   the state context block by name and pulled with `readState(key)`, masked by the model that key declares — while
   a key the screen does not read stays unreadable even when a sibling key of the same store is live. **There is no
   store-level exposure declaration**: a store class says nothing about agents, and `st.use.x({ agent: false })` is
   how the component that subscribes a value keeps it off the surface. Base-store plumbing does the same at the
   call site — `st.use.path({ agent: false })`, `st.use.tryJwt({ agent: false })` — so routing and the caller's
   credential stay off the surface unless a component opts a key in, as ThemeToggle does for `theme`.
-- **Model-facing text is English, always** — tool `desc`, `instructions`, Guide text. The `l()` rule covers
+- **Model-facing text is English, always** — every `.desc()`, `instructions`, Guide text. The `l()` rule covers
   strings a *user* reads: Chat's own buttons go through `l("base.*")`, the model's text never does.
-- A masked model never crosses the boundary: a value whose `hidden`/`secret` fields are populated is refused at
-  read unless a `mask:` model is named — the same rule and wording as `AgentBridge.read`.
+- **The declared type is the mask.** `st.expose`/`st.useState` take a scalar, an enum, a model class, a one-level
+  array of any of those, or `Any`. A model class both typechecks what the component hands over — the state object,
+  so a hydrated document and a plain copy of one are equally accepted — and strips the model's `hidden`, `secret`,
+  and `visual` fields on the way out, by the model that was *named* rather than by whatever class the value still
+  happens to carry. A `Date` leaves as an ISO string. `Any` is the escape hatch and passes the value untouched, so
+  a payload nobody modeled stays publishable and its owner keeps the tokens it costs. A type nothing can read (a
+  `Map`, an `Upload`, a class that is not a model) is reported on the console and left unpublished, never thrown —
+  the same degradation an undescribable `.arg` gets. `.value()` also takes a thunk, which is read when the agent
+  reads: that is the shape for a value assembled out of a ref the children fill in after the render.
 - **A field the page needs and an agent does not is `field.visual`.** `abstractData: field.visual(String)` — a blur
   placeholder, a rendered HTML body, a serialized geometry: real data the screen renders, and hundreds of tokens per
   record no question is answered from. It is stripped by `mask`, so it leaves every agent-facing read and every MCP

package/guidelines/conventions/conventions.instruction.md

@@ -529,14 +529,21 @@ package; apps and libs never import it directly (`no-import-external-library`)
   `option.setAgentAccess(SignedIn)`.
 - **The LLM is configured in `option.ts`, never through the environment.** `option.setLlm({ apiKey, model, host })`
   fills whichever adaptor holds `LlmAdaptorRole`; swap providers with `option.applyAdaptor(LlmAdaptorRole, X)`.
-- **Declare the tool beside the control that already does it.** `st.tool("x", { desc }).arg("id", ID).exec(fn)`
-  publishes one action and returns the callable to hand to `onClick` — one handler for the person and the agent.
-  Reach a store action from the body (`.exec((id) => st.do.removeX(id))`); `st.do` on its own reaches nobody.
+- **Declare the tool beside the control that already does it.**
+  `st.tool("x").desc("…").arg("id", ID).opt("force", Boolean).exec(fn)` publishes one action and returns the
+  callable to hand to `onClick` — one handler for the person and the agent. `.desc()` is required and comes first,
+  `.arg()` is an argument the caller must pass and `.opt()` one it may, and `.exec()` is the only hook. Reach a
+  store action from the body (`.exec((id) => st.do.removeX(id))`); `st.do` on its own reaches nobody.
 - **Publish a tool only where the screen already renders the control.** A falsy name declares the tool without
   publishing it, which is how a conditional surface stays legal — `.exec()` is a hook, so withhold the name, not
   the call. A `disabled` control publishes nothing.
 - **A component that renders once per row takes the row id as an argument**, never a closure over it — fifty
-  registrations of one name leave forty-nine shadowed. Interchangeable repeats say so with `shared: true`.
+  registrations of one name leave forty-nine shadowed. The description is what makes the repeats one declaration:
+  same name and same `.desc()` is the same tool registered fifty times, and only a second description under that
+  name warns.
+- **`{ settle: false }` is the read that returns what is already there.** Every other tool is waited out before
+  what it did to the screen is reported, because a write may still be landing when `exec` resolves. `{ confirm }`
+  and `{ guard }` ride the same object; a `remove*` name confirms by default.
 - **A component that can render twice on one screen takes a `namespace` prop** (`Tab`, `Dialog`, `Dropdown`,
   `ScreenNavigator`) and publishes nothing without one.
 - **Forms publish themselves**: a `Field.*` / `Input.*` / `Select` / `Switch` handed `onChange={st.do.setXOnY}`
@@ -544,6 +551,11 @@ package; apps and libs never import it directly (`no-import-external-library`)
   nothing — normalize with the control's `transform` prop, and multi-write with a `_postSet<Field>` store method.
 - **Reading is per key, not per store.** `st.use.x({ agent: false })` keeps a subscribed key off the surface;
   a key no component reads is unreadable. A value with populated `hidden`/`secret` fields is refused at read.
+- **A component's own value is published by its declared type.** `st.expose("taskId", ID).desc("…").value(v)` for
+  a derived value and `st.useState("tab", String, { set: true }).desc("…").init("all")` for local state — the type
+  typechecks what is handed over and decides how it is read, so a model class masks by that model. `Any` is the
+  escape hatch: no typecheck, and the value passes untouched. `.value()` also takes a thunk, read when the agent
+  reads.
 - **Return what answers the question, not the record.** A tool's value is capped at 20,000 characters before it
   enters the transcript and clipped with a note the model reads (`ToolOutput.limit`), because a store key is sized
   for a screen and not for a model's window: one `readState` of a list whose rows carry inlined bytes is megabytes,
@@ -562,7 +574,7 @@ package; apps and libs never import it directly (`no-import-external-library`)
 - The framework publishes five built-ins on every store surface — `navigate`, `goBack`, `readScreen`,
   `readState(key)`, `highlight(target)` — plus `askUser`, which the session owns. **There is no general-purpose
   wait**: publish an `st.tool` beside the control that starts the work and let it await the work.
-- **Model-facing text is English, always** — tool `desc`, `instructions`, Guide text. The `l()` rule covers
+- **Model-facing text is English, always** — every `.desc()`, `instructions`, Guide text. The `l()` rule covers
   strings a *user* reads.
 
 Full contract — the chat's own options, attachments and speech, zones, what `akanjs/ui` publishes for you, slash

package/{index-wmwcwn1f.js → index-d3vvvzsd.js}

@@ -283,7 +283,7 @@ ${chalk.green("\u27A4")} Authentication Required`));
         return;
       }
     }
-    await Promise.all(akanPkgs.map(async (library) => {
+    for (const library of akanPkgs) {
       Logger.info(`Publishing ${library}@${nextVersion} to ${registry ?? "npm"}...`);
       await workspace.spawn("npm", ["publish", "--tag", tag, ...this.#getRegistryArgs(registry), ...this.#getLocalRegistryAuthArgs(registry)], {
         cwd: path.join(workspace.workspaceRoot, "dist/pkgs", library),
@@ -291,7 +291,7 @@ ${chalk.green("\u27A4")} Authentication Required`));
         stdio: "inherit"
       });
       Logger.info(`${library}@${nextVersion} is published to ${registry ?? "npm"}`);
-    }));
+    }
     Logger.info(`All libraries are published to ${registry ?? "npm"}`);
   }
   async update(workspace, tag = "latest", { registryUrl } = {}) {

package/{index-ssrz6xr1.js → index-rrcdemys.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   CloudRunner
-} from "./index-wmwcwn1f.js";
+} from "./index-d3vvvzsd.js";
 import {
   PackageScript
 } from "./index-x1dbhd80.js";

package/index.js

@@ -19,16 +19,16 @@ import path from "path";
 
 // pkgs/@akanjs/cli/commandModules.ts
 var commandModules = {
-  workspace: async () => (await import("./workspace.command-zg8me6fg.js")).WorkspaceCommand,
+  workspace: async () => (await import("./workspace.command-s2g36sgr.js")).WorkspaceCommand,
   agent: async () => (await import("./agent.command-tsx1nsdj.js")).AgentCommand,
   application: async () => (await import("./application.command-n8ex8g9h.js")).ApplicationCommand,
   library: async () => (await import("./library.command-p3jgf5h2.js")).LibraryCommand,
-  localRegistry: async () => (await import("./localRegistry.command-jewr722x.js")).LocalRegistryCommand,
+  localRegistry: async () => (await import("./localRegistry.command-5hp7am6e.js")).LocalRegistryCommand,
   package: async () => (await import("./package.command-fbpa6r4w.js")).PackageCommand,
   module: async () => (await import("./module.command-hb3xm07r.js")).ModuleCommand,
   page: async () => (await import("./page.command-92vrmw96.js")).PageCommand,
   context: async () => (await import("./context.command-s7a41qjs.js")).ContextCommand,
-  cloud: async () => (await import("./cloud.command-eqafzn1a.js")).CloudCommand,
+  cloud: async () => (await import("./cloud.command-v5g0c7nm.js")).CloudCommand,
   guideline: async () => (await import("./guideline.command-qrw84ttb.js")).GuidelineCommand,
   scalar: async () => (await import("./scalar.command-zcsjgvax.js")).ScalarCommand,
   primitive: async () => (await import("./primitive.command-k6b9jfxr.js")).PrimitiveCommand,

package/{localRegistry.command-jewr722x.js → localRegistry.command-5hp7am6e.js}

@@ -2,7 +2,7 @@
 import {
   CloudRunner,
   getNpmRegistryUrl
-} from "./index-wmwcwn1f.js";
+} from "./index-d3vvvzsd.js";
 import {
   PackageScript
 } from "./index-x1dbhd80.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-alpha.52",
+  "version": "3.0.0-alpha.53",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.52",
+    "akanjs": "3.0.0-alpha.53",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/{workspace.command-zg8me6fg.js → workspace.command-s2g36sgr.js}

@@ -11,11 +11,11 @@ import"./index-ss469dec.js";
 import"./index-kkya2ped.js";
 import {
   CloudScript
-} from "./index-ssrz6xr1.js";
+} from "./index-rrcdemys.js";
 import {
   getLatestPackageVersion,
   getNpmRegistryUrl
-} from "./index-wmwcwn1f.js";
+} from "./index-d3vvvzsd.js";
 import {
   PackageScript
 } from "./index-x1dbhd80.js";