@akanjs/cli 3.0.0-alpha.15 → 3.0.0-alpha.17

package/.build-stamp

@@ -1 +1 @@
-714e226e4dda771d192ec7f6f9b947d03b5556e07bb7303ac02e0287c2e03d53
+04e275c86b39878b8f59c901ec9b2e94fe61c317e6279d0f7b890998dc0fb6f4

package/README.ko.md

@@ -64,7 +64,7 @@ metadata를 검증합니다.
 
 ## 요구사항
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript 기반 Akan 워크스페이스
 
 ## 라이선스

package/README.md

@@ -77,7 +77,7 @@ artifact is built last and is not overwritten by the root `akan` bootstrap scrip
 
 ## Requirements
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - A TypeScript Akan workspace
 
 ## License

package/{abstractCompactor-e5yq60qz.js → abstractCompactor-khr60389.js}

@@ -7,7 +7,7 @@ import {
 } from "./index-0wae5ebk.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/devkit/abstractCompactor.ts
 import { Logger } from "akanjs/common";

package/{agent.command-h6tc0pzh.js → agent.command-e835fjem.js}

@@ -1,20 +1,20 @@
 // @bun
 import {
   AgentScript
-} from "./index-7ecpft60.js";
-import"./index-djh5gpb7.js";
-import"./index-9s991k9v.js";
+} from "./index-k6fvbcj1.js";
+import"./index-g9e2fhw2.js";
+import"./index-tsmjxph2.js";
 import"./index-j37qq1f2.js";
 import {
   Workspace,
   command
-} from "./index-bkwnr08k.js";
-import"./index-1twehz1x.js";
+} from "./index-n706txcv.js";
+import"./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/cli/agent/agent.command.ts
 class AgentCommand extends command("agent", [AgentScript], ({ public: target }) => ({

package/{application.command-kphnfwyg.js → application.command-bexm4597.js}

@@ -4,8 +4,8 @@ import {
 } from "./index-0wae5ebk.js";
 import {
   ApplicationScript
-} from "./index-rv16ck4r.js";
-import"./index-p42te6qb.js";
+} from "./index-x2w0y8sz.js";
+import"./index-73rnbwgg.js";
 import {
   getMobileTargetChoices
 } from "./index-76rn3g2c.js";
@@ -15,14 +15,14 @@ import {
   Sys,
   Workspace,
   command
-} from "./index-bkwnr08k.js";
+} from "./index-n706txcv.js";
 import"./index-fgc8r6dj.js";
 import"./index-bjpxzr6s.js";
-import"./index-1twehz1x.js";
+import"./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/cli/application/application.command.ts
 import { select } from "@inquirer/prompts";

package/{applicationBuildRunner-9ps10a0h.js → applicationBuildRunner-sgr3aq5b.js}

@@ -4,14 +4,14 @@ import {
   CsrArtifactBuilder,
   SsrBaseArtifactBuilder,
   precompressArtifacts
-} from "./index-2m11t9ek.js";
+} from "./index-v5vmgh0z.js";
 import"./index-xjd3rqzj.js";
-import"./index-j9cxndc0.js";
+import"./index-qyffprfs.js";
 import"./index-bjpxzr6s.js";
 import {
   Spinner
 } from "./index-mxvakhsm.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/devkit/applicationBuildRunner.ts
 import { mkdir, rm } from "fs/promises";
@@ -39,7 +39,6 @@ var SSR_RENDER_EXTERNALS = [
 var AKAN_OPTIONAL_BACKEND_EXTERNALS = [
   "@libsql/client",
   "bullmq",
-  "croner",
   "ioredis",
   "postgres",
   "protobufjs"
@@ -287,6 +286,6 @@ void run().catch((error) => {
   }
 }
 export {
-  ApplicationBuildRunner,
-  AKAN_OPTIONAL_BACKEND_EXTERNALS
+  AKAN_OPTIONAL_BACKEND_EXTERNALS,
+  ApplicationBuildRunner
 };

package/{applicationReleasePackager-gg8ccbeh.js → applicationReleasePackager-93nzdfsy.js}

@@ -5,7 +5,7 @@ import {
 import {
   FileSys
 } from "./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/devkit/applicationReleasePackager.ts
 import { cp, mkdir, rm } from "fs/promises";

package/buildBatch.proc.js

@@ -5,18 +5,18 @@ import {
   FontOptimizer,
   PagesBundleBuilder,
   SsrBaseArtifactBuilder
-} from "./index-2m11t9ek.js";
+} from "./index-v5vmgh0z.js";
 import"./index-xjd3rqzj.js";
-import"./index-j9cxndc0.js";
+import"./index-qyffprfs.js";
 import"./index-bjpxzr6s.js";
 import {
   AppExecutor,
   WorkspaceExecutor
-} from "./index-1twehz1x.js";
+} from "./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts
 import path from "path";

package/{capacitorApp-9ejk3k7q.js → capacitorApp-qv7g3dp2.js}

@@ -25,37 +25,37 @@ import {
   selectLocalDevHost,
   sortIosRunTargets,
   writeRootCapacitorConfig
-} from "./index-gz91pc3p.js";
+} from "./index-mz5jtaq7.js";
 import"./index-76rn3g2c.js";
-import"./index-1twehz1x.js";
+import"./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 export {
-  writeRootCapacitorConfig,
-  sortIosRunTargets,
-  selectLocalDevHost,
-  sanitizeIosNativeRunEnv,
-  rootCapacitorConfigPaths,
-  rootCapacitorConfigFilenames,
-  raiseGradleMinSdkVersion,
-  parseSimctlDevices,
-  parseIosRuntimeMajor,
-  parseDevicectlDevices,
-  materializeCapacitorConfig,
-  isPlaceholderAppId,
-  getMissingAndroidReleaseSigningKeys,
-  getAndroidLocalServerHost,
-  getAdbDeviceStateIssues,
-  formatIosRunFailureMessage,
-  formatAndroidReleaseSigningError,
-  clearRootCapacitorConfigs,
-  classifyIosRunFailure,
-  buildIosNativeRunCommand,
-  assertJsonSerializable,
-  SWIFTUICORE_MIN_IOS_MAJOR,
-  PLACEHOLDER_APP_IDS,
+  ANDROID_MIN_SDK_VERSION,
   CapacitorApp,
-  ANDROID_MIN_SDK_VERSION
+  PLACEHOLDER_APP_IDS,
+  SWIFTUICORE_MIN_IOS_MAJOR,
+  assertJsonSerializable,
+  buildIosNativeRunCommand,
+  classifyIosRunFailure,
+  clearRootCapacitorConfigs,
+  formatAndroidReleaseSigningError,
+  formatIosRunFailureMessage,
+  getAdbDeviceStateIssues,
+  getAndroidLocalServerHost,
+  getMissingAndroidReleaseSigningKeys,
+  isPlaceholderAppId,
+  materializeCapacitorConfig,
+  parseDevicectlDevices,
+  parseIosRuntimeMajor,
+  parseSimctlDevices,
+  raiseGradleMinSdkVersion,
+  rootCapacitorConfigFilenames,
+  rootCapacitorConfigPaths,
+  sanitizeIosNativeRunEnv,
+  selectLocalDevHost,
+  sortIosRunTargets,
+  writeRootCapacitorConfig
 };

package/{cloud.command-zn6mfscb.js → cloud.command-v44fdp23.js}

@@ -1,27 +1,27 @@
 // @bun
 import {
   CloudScript
-} from "./index-g3brq942.js";
-import"./index-96vpa123.js";
-import"./index-xwfkgss0.js";
+} from "./index-9djnsdgf.js";
+import"./index-fb2wa7j3.js";
+import"./index-33zce8gt.js";
 import {
   GlobalConfig
 } from "./index-0cj2zxbm.js";
-import"./index-rv16ck4r.js";
-import"./index-p42te6qb.js";
+import"./index-x2w0y8sz.js";
+import"./index-73rnbwgg.js";
 import"./index-76rn3g2c.js";
 import {
   Workspace,
   command
-} from "./index-bkwnr08k.js";
+} from "./index-n706txcv.js";
 import"./index-fgc8r6dj.js";
 import"./index-bjpxzr6s.js";
-import"./index-1twehz1x.js";
+import"./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-46tjzh6s.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.command.ts
 var localRegistryUrl = () => process.env.AKAN_NPM_REGISTRY ?? "http://127.0.0.1:4873";

package/{context.command-pkbccyys.js → context.command-q8r0tge3.js}

@@ -1,30 +1,30 @@
 // @bun
 import {
   ContextScript
-} from "./index-b9m84bjp.js";
-import"./index-4agbdds8.js";
-import"./index-w7farjxd.js";
-import"./index-8d9r0df5.js";
-import"./index-4v0wvt37.js";
-import"./index-aak9cctp.js";
+} from "./index-d4d3q2r8.js";
+import"./index-xyrb7pk5.js";
+import"./index-3dp7x6rc.js";
+import"./index-sn71brf9.js";
+import"./index-hxp90q94.js";
+import"./index-myy6xy5w.js";
 import"./index-ss469dec.js";
-import"./index-gyvrhtpm.js";
-import"./index-gz91pc3p.js";
+import"./index-qc0tnhs2.js";
+import"./index-mz5jtaq7.js";
 import"./index-0cj2zxbm.js";
-import"./index-djh5gpb7.js";
-import"./index-9s991k9v.js";
+import"./index-g9e2fhw2.js";
+import"./index-tsmjxph2.js";
 import"./index-j37qq1f2.js";
 import"./index-76rn3g2c.js";
 import {
   Workspace,
   command
-} from "./index-bkwnr08k.js";
-import"./index-1twehz1x.js";
+} from "./index-n706txcv.js";
+import"./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/cli/context/context.command.ts
 class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({

package/{dependencyScanner-f6grrep3.js → dependencyScanner-rbs2407b.js}

@@ -3,7 +3,7 @@ import {
   TypeScriptDependencyScanner
 } from "./index-46tjzh6s.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 export {
   TypeScriptDependencyScanner
 };

package/{getDirname-m9s0cmhq.js → getDirname-ka11hm7e.js}

@@ -2,7 +2,7 @@
 import {
   getDirname
 } from "./index-1577bej2.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 export {
   getDirname
 };

package/{guideline.command-0jj2k77g.js → guideline.command-pye36g73.js}

@@ -10,8 +10,8 @@ import {
   command,
   runner,
   script
-} from "./index-bkwnr08k.js";
-import"./index-1twehz1x.js";
+} from "./index-n706txcv.js";
+import"./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import {
   getDirname
@@ -19,7 +19,7 @@ import {
 import {
   FileSys
 } from "./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/cli/guideline/guideline.script.ts
 import { Logger } from "akanjs/common";

package/guidelines/conventions/conventions.instruction.md

@@ -57,6 +57,12 @@ that looks wrong; do not "fix" it back.
   unreachable — write it into state with `this.set({ ... })`. A bare `return;` guard, a `return` inside a nested
   callback, a getter, and a `static` helper are all still fine.
 - **Never redeclare a generated CRUD endpoint name** in `*.signal.ts` (`no-redeclare-predefined-endpoint.grit`).
+- **Never type a `*.Util.tsx` / `*.Zone.tsx` prop as a `cnst` model** (`no-model-type-in-util-zone.grit`). Those two
+  roles are always client components, so a `cnst.Banner` / `cnst.LightBanner` prop is a class instance the server has
+  to hand across the boundary; take `bannerId: string` and read the model from the store instead. Two shapes are
+  exempt because neither is an instance: `cnst.<Enum>["value"]`, whose indexed access resolves to a string union, and
+  a `ClientInit` / `ClientView` / `ClientEdit` type argument, which the framework maps to `GetStateObject<…>` plain
+  data. Any *other* indexed access is still flagged — `cnst.Banner["image"]` is a `File`.
 - **No deep imports past a barrel** (`no-deep-internal-import.grit`). Cross-module constant references such as
   `../map/map.constant` are the sanctioned exception.
 - **Never import across the client/server boundary.** Client files (`ui/`, `webkit/`, `page/`, `*.store.ts`, every
@@ -344,10 +350,6 @@ than returning it (`no-return-in-store-action.grit`); a bare `return;` guard sta
 `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`.
 Name every argument in `.arg()`, including framework-supplied `skip` / `limit` / `sort`. Use `modelDictionary`,
 `scalarDictionary`, or `serviceDictionary` to match the module kind.
-**`.store()` sits between `.endpoint()` and `.error()` and is the one optional stage** — omit it entirely rather
-than writing it empty. It names custom store actions (labels and `.desc()` only, no `.arg()`), and it is only
-needed where inheriting would be wrong: an action named after the endpoint it calls already reads as that
-endpoint's `.desc()`, which is most of them. `akan.agent.missing-store-description` names the rest.
 
 **`<module>.abstract.md`** — a title line, one declarative sentence naming what the module owns, a `## Rules` list of
 two to five invariants the code cannot show, and an optional workflow arrow chain
@@ -374,8 +376,10 @@ workflow changes.
 
 - **Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.**
 - **Every custom `mutation` / `query` / `message` names its own `guards: [...]` array.** Never rely on the slice default. `Public` belongs on a slice `get:`, never on a mutation.
+- **The guards are also the MCP exposure decision** — see MCP Exposure. An endpoint that names none is not published to agents at all, and a mutation whose only guard is `Public` is refused, so a missing `guards` array now costs visibility as well as authorization.
 - Resource guards are `Can<Verb><Model>` classes in `srvkit/guards.ts` that `implements Guard` with an `async canPass(context)`. They **fail closed**: no resource named ⇒ `false`; a load that throws ⇒ `logger.warn` then `false`. Admin bypass goes first.
 - Keep `static name = "User";` on guard classes. `fetch` serializes guard names and the API explorer filters on them; it looks like dead code, and deleting it breaks the UI. Comment it so the next reader knows.
+- **Every guard class also declares `static scope: GuardScope`, and it is required with no default.** `"account"` means the verdict reads the caller and nothing about the call, so it can be evaluated with no arguments — which is what lets an MCP listing hide what this caller certainly cannot use. `"resource"` means it needs the call's arguments (`context.getArg()`) and fails closed without them, so it is never evaluated for a listing: the entry stays visible and is stopped at call time. Getting it wrong is not a type error, so the marker is mandatory rather than defaulted — `SignedIn` / `Admin` / role checks are `"account"`, and every `Can<Verb><Model>` is `"resource"`.
 - The acting user arrives via `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`. Never trust a client-supplied id.
 - Guards ship with the library that owns the model and are imported by its own signals through the package path, so a mounting app inherits authorization and cannot forget it.
 - Services re-check ownership even when a guard already gated the call — two independent gates.
@@ -466,7 +470,7 @@ Conventions that hold for both shapes:
 - Resolve secrets as `process.env.X ?? options.x ?? deterministicGenerator(...)` **inside a function**, never at module scope.
 - Extend a function by appending an optional trailing parameter with a default, never by changing arity.
 - Parameters: up to three required primitives positional; optional flags in a trailing `{ … } = {}`; four or more parameters, or any two same-typed strings, in one named destructured object.
-- Release locks in `finally`. Load heavy optional dependencies through a module-level memoized promise (`sharpLoad ??= import("sharp")`).
+- Release locks in `finally`. Load heavy optional dependencies through a module-level memoized promise (`puppeteerLoad ??= import("puppeteer")`).
 
 ### Error Placement
 
@@ -477,39 +481,56 @@ Conventions that hold for both shapes:
 
 ### MCP Exposure
 
-Any signal can be served to AI agents as an MCP server on `POST /mcp`, and **nothing is exposed until it says so**.
-Turn it on in the app's `main.ts` — `new AkanApp("./server", { mcp: { … } })` — which takes `enabled`, `readOnly`,
-`path`, `version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, and `auth`. That is the only
-app-authored place for it: `server.ts` is generated and takes no options, and the gateway configures a child
-through its environment — so each field also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
+Every signal is served to AI agents as an MCP server on `POST /mcp`. **`/mcp` is mounted by default and exposure
+follows an endpoint's guards — there is no per-endpoint opt-in, and nothing to write in a signal file.** An endpoint
+that declares a real guard is published; one that declares none is refused, and so is a mutation whose only guard is
+`Public`. `AKAN_MCP=false` takes the whole surface off. The reasoning is that the guards are already the
+authorization decision and `filterForAccount` re-reads them per caller on every listing, so a second per-endpoint
+switch says nothing the guards do not — while guaranteeing that every endpoint added later is invisible to agents
+until somebody remembers it.
+
+Settings live in the app's `lib/option.ts` — `option.setMcp({ … })`, taking `enabled`, `readOnly`, `path`,
+`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, and `auth`. **Not `main.ts`**: the gateway
+there only spawns children, and `option.ts` is the app-authored file `server.ts` already hands to the process that
+mounts `/mcp`. Every lib's option is read in mount order with the app's last, so an app tightens what a library
+declared without restating it. Each field also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
 `AKAN_MCP_PATH`, `AKAN_MCP_VERSION`, `AKAN_MCP_INSTRUCTIONS`, `AKAN_MCP_ALLOWED_ORIGINS`, `AKAN_MCP_PAGE_SIZE`,
-`AKAN_MCP_LANGUAGE`, `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`), which code overrides.
+`AKAN_MCP_LANGUAGE`, `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`) for a deployment that
+configures what the source does not, which the option overrides.
 The two booleans answer to `AKAN_PUBLIC_MCP` / `AKAN_PUBLIC_MCP_READONLY` too, the same pairing `AKAN_OPENAPI`
 has, and a value written in code wins over the env of the same name — an explicit `undefined` is not a value.
 `AKAN_MCP_PATH` is normalized to a leading `/`, because the route key and the OAuth metadata path are both built by
 concatenation.
 
 ```typescript
-// <model>.signal.ts — a tool, a resource-backed slice, and a slash-command prompt
+// apps/<app>/lib/option.ts
+export const option = new AkanOption<ModulesOptions>().setMcp({
+  instructions: "Domain tools for the akan app. Start from taskInTodo.",
+  language: "en",
+});
+```
+
+```typescript
+// <model>.signal.ts — every one of these is an MCP tool or prompt, with no `mcp:` option anywhere
 export class TaskSlice extends slice(
   srv.task,
-  // generated CRUD per verb; `list` is the model's own unfiltered list, which `slice()` generates itself
-  { guards: { root: Admin, get: SignedIn, cru: SignedIn }, mcp: { get: true, list: true } },
+  { guards: { root: Admin, get: SignedIn, cru: SignedIn } },
   (init) => ({
-    // its own guards: the map above reaches base CRUD and the root slice, never a named slice
-    inTodo: init({ guards: [SignedIn], mcp: { expose: true } }).exec(function () {
+    // its own guards: the map above reaches base CRUD and the root slice, never a named slice — so a named slice
+    // that names none is refused rather than published, which is the one shape to watch for.
+    inTodo: init({ guards: [SignedIn] }).exec(function () {
       return this.taskService.queryByStatuses(["todo"]);
     }),
   }),
 ) {}
 
 export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => ({
-  startTask: mutation(cnst.Task, { guards: [SignedIn], mcp: { expose: true } })
+  startTask: mutation(cnst.Task, { guards: [SignedIn] })
     .param("taskId", ID)
     .exec(async function (taskId) {
       return await this.taskService.startTask(taskId);
     }),
-  reviewTask: prompt({ guards: [SignedIn], mcp: { expose: true } })
+  reviewTask: prompt({ guards: [SignedIn] })
     .param("taskId", ID)
     .exec(async function (taskId) {
       const task = await this.taskService.getTask(taskId);
@@ -518,24 +539,21 @@ export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => (
 })) {}
 ```
 
-- **The refusals are fail-closed and survive opting in**: `pubsub` and `message` (their internal args read a socket
-  an MCP request does not have), an `Any` or `Upload` return, a file upload, **a mutation with no real `guards`**
-  (`[Public]` is having none, spelled out — it answers true unconditionally), and **an argument typed `Any` that
-  must be filled**.
+- **The refusals are fail-closed**: **an endpoint that declares no `guards` at all** (nobody decided who may reach
+  it), **a mutation with no real `guards`** (`[Public]` is having none, spelled out — it answers true
+  unconditionally), `pubsub` and `message` (their internal args read a socket an MCP request does not have), an
+  `Any` or `Upload` return, a file upload, and **an argument typed `Any` that must be filled**.
   A `prompt` refuses two more, because its `arguments` is one string per name with no schema beside it: a **list
   argument**, which could never carry a second value, and **any `Any` argument** — a tool leaves that out of its
-  schema, and a prompt has no schema to leave it out of. `resource: true` is refused there too: only a read
-  publishes a resource template.
-- **Every refusal is named in the boot log**, and so is every published entry that declares no `guards` at all —
-  the access is what `[Public]` grants, but only one of the two is a decision you made. One `warn` per endpoint
-  plus a `MCP catalogue: tools=… prompts=…` count. Read that line first when a tool you exposed is missing —
-  fail-closed is right, and a silent fail-closed leaves you nothing to read. `akan quality scan` covers the two
-  shapes visible in source, `akan.mcp.missing-description` and `akan.mcp.unguarded-exposure`; the API explorer
-  badges the per-endpoint rules (`MCP` / `MCP refused`) from the same rule the catalogue runs.
+  schema, and a prompt has no schema to leave it out of.
+- **Every refusal is named in the boot log**: one `warn` per endpoint plus a `MCP catalogue: tools=… prompts=…`
+  count. Read that line first when a tool you expected is missing — and it is the *only* place the answer exists,
+  because there is no absent opt-in to notice. The API explorer badges the same rule per endpoint (`MCP` /
+  `MCP refused`), from the same shared implementation the catalogue runs.
 - **An `Any` argument is left out of the published schema** rather than described as `{}` — it tells a model
   nothing — and a value sent for one is refused by name, so the endpoint reads it as omitted. That is what happens
   to the root list's raw `query` descriptor: read as sent, it would be an arbitrary filter over every model you
-  exposed through `mcp: { list: true }`. Expose a named filter slice when an agent should narrow a list.
+  publish. Declare a named filter slice when an agent should narrow a list.
 - **A nullable model return publishes no `outputSchema`**, and its empty answer ships as the text `null` with no
   `structuredContent`. That field is an object by definition, so `null` cannot ride in it any more than an array
   can — a list is wrapped as `{ items: … }` for the same reason — and a declared schema obliges every result to
@@ -544,13 +562,13 @@ export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => (
 - **An `outputSchema` names no `hidden` or `secret` field.** Every response has both stripped, so publishing them
   promises a property no answer can carry — and on a model like `user` the names are the leak. Your *input* schema
   keeps them: they are legal to send, and the same model describes a request body.
-- An endpoint that did not opt in answers the *same* "unknown tool" as one that does not exist. Never make that
+- A refused endpoint answers the *same* "unknown tool" as one that does not exist. Never make that
   message more helpful — the difference is what enumerates your private surface. A guard's refusal is generalized
   the same way: the caller reads `You are not permitted to perform this action.`, never `Access denied by guard:
   Admin`, which names your authorization structure to the one caller barred from it. A domain `Err` resolves
   through the dictionary first and keeps its own words.
-- `mcp: { readOnly, destructive, idempotent }` only override the hints a client renders. Clients are told to
-  distrust hints; they are never a gate.
+- The `readOnly` / `destructive` / `idempotent` hints a client renders are derived from the endpoint type and key
+  and are not configurable. Clients are told to distrust hints; they are never a gate.
 - **`AKAN_MCP_READONLY=true` is the read-only-deployment valve, not the exposure switch.** It drops every mutation
   whatever it declared, and reports each one in the boot log like any other refusal.
 - OAuth resource metadata is published at `/.well-known/oauth-protected-resource` (and at that path plus the mount
@@ -558,12 +576,12 @@ export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => (
   configure it; `insufficient_scope` is enforced only once `AKAN_MCP_SCOPES` is set. A token carrying no `aud` at
   all is refused once `AKAN_MCP_AUTH_SERVERS` names an issuer — that issuer mints tokens for its other resources
   too — and accepted while none is named, because a first-party Akan token is bound by app and environment.
-- `akan quality scan` warns **`akan.mcp.missing-description`** for anything exposed without a dictionary `.desc()`.
-  An agent picks a tool by its description, so a missing one is a broken tool. What the framework generates is
-  exempt and borrows the model's own text, having none of its own: `mcp: { list: true }` reads the `.of()` label,
-  and the base CRUD tools append the model's `.desc()` to their generated `Get X`. Write that model `.desc()` — it
-  is the only text those entries can carry. The scan is not the whole answer either, because it reads source: **the
-  boot log names every published entry with no description**, generated ones included.
+- **The boot log names every published entry with no dictionary `.desc()`.** An agent picks a tool by its
+  description, so a missing one is a broken tool. What the framework generates has no text of its own and borrows
+  the model's: the generated list reads the `.of()` label, and the base CRUD tools append the model's `.desc()` to
+  their generated `Get X`. Write that model `.desc()` — it is the only text those entries can carry. There is no
+  `akan quality scan` rule for this any more: a source scanner found the exposure only as an `mcp:` literal, and
+  with exposure derived from the guards the resolved catalogue is the only place that can answer.
 - A browser-hosted client needs `allowedOrigins` **and** the CORS answer the server sends back for those origins.
   Every other MCP client sends no `Origin` at all, and the one that does is matched against the forwarded host so
   a proxy does not turn each call into a 403 — which is only as trustworthy as an edge that *overwrites* that
@@ -588,9 +606,8 @@ export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => (
   token signed wrong, like an opaque one, still degrades to an anonymous caller.
 - **Resource URIs**: `akan://<model>/{id}`, `akan://<model>/light/{id}`, `akan://<model>/list` for the model's own
   list, and `akan://<model>/list/<sliceKey>` for a slice's. The root list takes no third segment on purpose — any
-  token there is one a slice could also be named. **Those four are the whole set**, so `mcp: { resource: true }`
-  is honoured only on the generated reads: a custom endpoint keeps its tool, gets no resource template, and is
-  named in the boot log saying so.
+  token there is one a slice could also be named. **Those four are the whole set**, so only the generated reads are
+  addressable: a custom endpoint keeps its tool and gets no resource template.
 - **The catalogue is one language**, `en` unless `language` says otherwise: it is built once at boot and cached by
   clients, so there is no `Accept-Language` negotiation.
 
@@ -616,6 +633,68 @@ frames down included, and is a no-op when nobody is streaming — so the same co
 websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
 costs something to assemble.
 
+## In-Page Agent
+
+Every akan app can host a component-level agent that reads the rendered screen and drives it. Tools, state, and
+context are **derived from the rendered screen, not from the bundle**: a store joins the surface only while a
+mounted component reads one of its keys (`st.use` / `st.sel` / `st.ref` all count), and only that store's
+catalogued actions and state are published. `Load` scopes, the route, and the live keys complete the context, so
+most screens publish a full surface with zero agent code. The React core is the `use-agentic` package; apps and
+libs never import it directly (`no-import-external-library`) — everything reaches them through `st.*` and
+`akanjs/ui`.
+
+- **Mount `<Agent.Chat />` once in a layout.** That is the floating chat, the approval card, and the client-side
+  loop. The default runner drives `runAgentTurn`, which the **framework serves on every app** — no lib to mount,
+  `AKAN_AGENT=false` takes it off — and negotiates streaming via `accept`, so assistant text arrives as it is
+  generated with zero app code. The endpoint is a stateless relay and **never executes tools**: every tool runs in
+  the caller's own browser session, gated by guards and the approval card. Its guard is `AgentRelayAccess`, which
+  defaults to allow and **warns at boot while no policy is registered** — a product with accounts locks it in its
+  `option.ts`, `option.setAgentAccess((ctx) => !!ctx.get("account"))`, or anonymous visitors spend the LLM key.
+  `persist` keeps the transcript across reloads (sessionStorage; `{ storage: "local" }` to outlive the tab),
+  default off. Re-skin through the `AgentChat` slot in `_overrides.tsx`.
+- **The LLM is configured in `option.ts`, never through the environment.** `option.setLlm({ apiKey, model, host })`
+  — or `setLlm((options) => …)` to read the key out of the app's own env object, which is where a secret belongs —
+  fills whichever adaptor holds `LlmAdaptorRole`, reaching it as the `llmOption` use. The settings are the role's
+  rather than one provider's, so they survive a swap. **DeepSeek is the built-in default** (`deepseek-chat` 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.
+- **`<Agent.Zone id="comments">` runs a second agent over one section, in parallel with the root.** Everything
+  mounted inside — `st.use` subscriptions, hook tools, Guides — belongs to that zone's own conversation *and*
+  stays visible to the root agent: **zones are views, never walls**, so wrapping a section costs the root nothing.
+  An `Agent.Chat` inside binds to the zone session automatically; a zone's `readScreen` reads only its own
+  `data-agent-zone` container; guides follow the layout cascade (ancestors and own, never a sibling's). Zone
+  membership is positional — there is no per-declaration zone key, so a lib component joins whatever zone the app
+  mounts it in.
+- **Route guidance is `<Agent.Guide instructions="..." />`** rendered from a `_layout.tsx` or a page — the render
+  tree is the cascade: nested Guides concatenate outer-to-inner and navigating away withdraws them. It is a
+  component, not a pageConfig field. Module `*.abstract.md` files are developer docs and are never served to the
+  agent.
+- **Exposure is the store author's to trim.** `static agent = false` on a store class keeps the whole module off
+  the surface (the framework's base store declares it — its keys are plumbing and `tryJwt` is a credential);
+  `static agent = { exclude: ["setMapBounds", "mapCamera"] }` withholds named actions and state keys that are not
+  real levers (state a component writes into but never reads back). `st.use.x({ agent: false })` subscribes
+  without counting toward liveness. Generated `set<Key>` conveniences are never published — declare a typed action
+  or `st.tool` when an agent should set one.
+- **Hooks are the escape hatch, not the norm.** `st.useState(name, initial, meta)` publishes local state
+  (read-only unless `set:` names a type), `st.expose(name, value)` a derived value, and
+  `st.tool("x", { desc }).arg("id", ID).exec(fn)` a one-off action. `.exec()` is the only hook, so the chain
+  completes in one unconditional statement; its callable carries `data-akan-action`, so pass it to `onClick` by
+  reference like a store setter. `remove*`-named tools default to a confirm gate.
+- **Model-facing text is English, always** — tool `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`.
+- **`prompt()` endpoints double as the chat's slash commands.** There is no listing endpoint — the client reads
+  its own serialized signals — so a prompt's dictionary `.desc()` is what the menu shows, and its guards are
+  enforced by the prompt's own GET at call time.
+- The framework publishes three built-ins on every store surface: `navigate` (internal paths only, the same
+  router `Link` rides), `readScreen` (the rendered DOM as compact text — headings, links, control values; the
+  chat's own UI is skipped via `data-agent-ui`, and a password value is never read), and `readState(key)` (one
+  masked store key). Declaring a store action or hook tool under one of those names shadows the built-in, so
+  reuse them only to mean that.
+
 ## Scalar Modeling (`**/*.constant.ts`)
 
 - Define Akan models in `.constant.ts` files with `via` from `akanjs/constant`.