@akanjs/cli 3.0.0-alpha.10 → 3.0.0-alpha.12

package/.build-stamp

@@ -1 +1 @@
-544f143bd80d934e3bfc7a589535a00d139a33c5b27cfc22c4b02fd681602c1c
+84acd2086ed367dc670ca155f5d5f884d8af105b3527914ac5ba312e3e1985e6

package/{agent.command-f0gqkfgz.js → agent.command-a3n15c6t.js}

@@ -1,15 +1,15 @@
 // @bun
 import {
   AgentScript
-} from "./index-eyyf2149.js";
-import"./index-774gcx29.js";
-import"./index-rxkpk7n4.js";
+} from "./index-z1s5f4e0.js";
+import"./index-e4b2ae6b.js";
+import"./index-kcsa1zff.js";
 import"./index-j37qq1f2.js";
 import {
   Workspace,
   command
-} from "./index-kdh76j26.js";
-import"./index-z8ptfkzv.js";
+} from "./index-etwh7sd3.js";
+import"./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-1577bej2.js";

package/{application.command-x903m2qq.js → application.command-rp3y4ejb.js}

@@ -4,8 +4,8 @@ import {
 } from "./index-0wae5ebk.js";
 import {
   ApplicationScript
-} from "./index-62955kn5.js";
-import"./index-d43t8af2.js";
+} from "./index-5yjc80ha.js";
+import"./index-8pd02prk.js";
 import {
   getMobileTargetChoices
 } from "./index-76rn3g2c.js";
@@ -15,10 +15,10 @@ import {
   Sys,
   Workspace,
   command
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 import"./index-fgc8r6dj.js";
 import"./index-bjpxzr6s.js";
-import"./index-z8ptfkzv.js";
+import"./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";

package/{applicationBuildRunner-ha3y8ew8.js → applicationBuildRunner-73kbbb7e.js}

@@ -4,7 +4,7 @@ import {
   CsrArtifactBuilder,
   SsrBaseArtifactBuilder,
   precompressArtifacts
-} from "./index-qb61h0k7.js";
+} from "./index-wzdeact3.js";
 import"./index-xjd3rqzj.js";
 import"./index-j9cxndc0.js";
 import"./index-bjpxzr6s.js";

package/buildBatch.proc.js

@@ -5,14 +5,14 @@ import {
   FontOptimizer,
   PagesBundleBuilder,
   SsrBaseArtifactBuilder
-} from "./index-qb61h0k7.js";
+} from "./index-wzdeact3.js";
 import"./index-xjd3rqzj.js";
 import"./index-j9cxndc0.js";
 import"./index-bjpxzr6s.js";
 import {
   AppExecutor,
   WorkspaceExecutor
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";

package/{capacitorApp-9xswcgx7.js → capacitorApp-mr81qdxq.js}

@@ -25,9 +25,9 @@ import {
   selectLocalDevHost,
   sortIosRunTargets,
   writeRootCapacitorConfig
-} from "./index-779ske1y.js";
+} from "./index-9va8zayb.js";
 import"./index-76rn3g2c.js";
-import"./index-z8ptfkzv.js";
+import"./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";

package/{cloud.command-zs6kyf83.js → cloud.command-7mcmm52j.js}

@@ -1,22 +1,22 @@
 // @bun
 import {
   CloudScript
-} from "./index-82jrh4hj.js";
-import"./index-4m0bphac.js";
-import"./index-gcv8ncfh.js";
+} from "./index-k8gpsrm1.js";
+import"./index-rdv33eye.js";
+import"./index-h5whaj26.js";
 import {
   GlobalConfig
 } from "./index-0cj2zxbm.js";
-import"./index-62955kn5.js";
-import"./index-d43t8af2.js";
+import"./index-5yjc80ha.js";
+import"./index-8pd02prk.js";
 import"./index-76rn3g2c.js";
 import {
   Workspace,
   command
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 import"./index-fgc8r6dj.js";
 import"./index-bjpxzr6s.js";
-import"./index-z8ptfkzv.js";
+import"./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-46tjzh6s.js";

package/{context.command-fmepgjzg.js → context.command-ysxawe7h.js}

@@ -1,25 +1,25 @@
 // @bun
 import {
   ContextScript
-} from "./index-5sn5w2mt.js";
-import"./index-jf2ya7r2.js";
-import"./index-qzdjd4ct.js";
-import"./index-y4vkyhvv.js";
-import"./index-3vta1tqa.js";
-import"./index-jhpa13zj.js";
+} from "./index-3789fdpg.js";
+import"./index-yzmqvg23.js";
+import"./index-cv9cxs5k.js";
+import"./index-4mgkgba3.js";
+import"./index-m90fn8xe.js";
+import"./index-mewacxye.js";
 import"./index-ss469dec.js";
-import"./index-xmmzf150.js";
-import"./index-779ske1y.js";
+import"./index-65aeh789.js";
+import"./index-9va8zayb.js";
 import"./index-0cj2zxbm.js";
-import"./index-774gcx29.js";
-import"./index-rxkpk7n4.js";
+import"./index-e4b2ae6b.js";
+import"./index-kcsa1zff.js";
 import"./index-j37qq1f2.js";
 import"./index-76rn3g2c.js";
 import {
   Workspace,
   command
-} from "./index-kdh76j26.js";
-import"./index-z8ptfkzv.js";
+} from "./index-etwh7sd3.js";
+import"./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-1577bej2.js";

package/{guideline.command-n6sw0a0c.js → guideline.command-yqf9a372.js}

@@ -10,8 +10,8 @@ import {
   command,
   runner,
   script
-} from "./index-kdh76j26.js";
-import"./index-z8ptfkzv.js";
+} from "./index-etwh7sd3.js";
+import"./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import {
   getDirname

package/guidelines/conventions/conventions.instruction.md

@@ -72,6 +72,17 @@ that looks wrong; do not "fix" it back.
   (`no-import-client-functions.grit`, `no-use-client-in-server.grit`, `non-scalar-props-restricted.grit`).
 - `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose: `key={idx}` for embedded scalars and
   short dependency arrays are intentional, not oversights.
+- **A grit plugin diagnostic is suppressed as `lint/plugin`, not `plugin`** — `// biome-ignore lint/plugin: <reason>`
+  for one line, `// biome-ignore-all lint/plugin: <reason>` for a file. The bare `// biome-ignore plugin:` form Biome's
+  own category name suggests does nothing. Suppress a plugin only where the rule is genuinely wrong for the file, and
+  say why: the module-convention plugins (`no-import-external-library`, `no-deep-internal-import`, the store/signal
+  ones) apply to `apps/**` and `libs/**` only, so a plain package under `pkgs/` never needs the escape hatch.
+- **`biome.json` is strict JSON — a comment in it breaks config resolution.** Biome 2.5.8 does not report the parse
+  error; it falls back to discovery and aborts on whatever nested config the walk finds, typically inside a directory
+  `files.includes` excludes. Rename the file to `biome.jsonc` to document a disabled rule; `akan lint` pins the config
+  path either way, so it reports the parse error on the offending line.
+- **`akan lint` prints up to 200 diagnostics** (`--maxDiagnostics <n>`, `0` for no limit). Biome's own default is 20
+  with no count, which reads as progress when the mix of findings merely changed.
 
 ## Coding Style (`**/*.{ts,tsx}`)
 
@@ -261,7 +272,7 @@ Full version with code, the `Tab` composition example, and a review checklist: `
 - Conditional render is `cond ? <X/> : null`. Never `{cond && <X/>}` — in a `className` context it renders the literal string `"false"`. Early `return null` is for guard clauses only.
 - Never hand-roll loading, empty, or list states. Use `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`, `renderView`, and `renderEmpty`; `<Empty />` for a bare placeholder; and `Model.New` / `Model.Edit` / `Model.SureToRemove` for CRUD modals.
 - Avoid hooks. `useState` is for modal-open, tab, draft-input, and drag state only — never for server data. `useEffect` must be a genuine effect such as subscribe-with-cleanup or one-shot init. Prefer `Tab` over a `useState` mode switch. `.Template.tsx` files contain zero `useState`.
-- Forms are entirely store-driven: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, the setter passed by reference. Always use `Field.*`, never a bare `<input>` for a model field. Nested rows use `st.do.writeOnX("payments.3.name", v)` plus the generated `add<Field>OnX` / `sub<Field>OnX`.
+- Forms are entirely store-driven: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, the setter passed by reference. Always use `Field.*`, never a bare `<input>` for a model field. Nested rows use `st.do.writeOnX("payments.3.name", v)` plus the generated `add<Field>OnX` / `sub<Field>OnX`. **Passing the setter by reference is also what makes the framework emit `data-akan-action` / `data-akan-state`** on the control — the annotation an in-page agent, an E2E selector, and an external browser agent all read. Wrapping it in an inline arrow (`onChange={(v) => st.do.setFieldOnX(v)}`) silently drops that: a closure the caller wrote says nothing about what it does. Never hand-write a `data-akan-*` attribute.
 - Read with `st.use.*` and write with `st.do.*`. Client components do not call `fetch.*`.
 - Static class strings stay plain strings. Reach for `cn` only for a conditional or to merge an incoming `className`, and merge the caller last: `cn("base classes", cond && "extra", className)`. `cn` comes from `akanjs/client` (token-aware tailwind-merge) and is the only class-combining function — no `clsx` (removed), no raw `twMerge` imports, no object syntax (`{ x: cond }` → `cond && "x"`).
 - Multi-slot components take extra named props (`wrapperClassName`, `bodyClassName`), never a `classNames` object.
@@ -333,6 +344,10 @@ 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
@@ -460,6 +475,147 @@ Conventions that hold for both shapes:
 - `try/catch` is rare and always converts an exception into a decision, never swallows one. Guards catch → `logger.warn` → `return false`; adapters catch → `logger.error` → `return null`; UI uses `try/finally` to reset a spinner. A bodyless `catch {}` is acceptable only with a one-line reason.
 - Store actions do not `try/catch` — let the framework toast the `Err`. Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
 
+### 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`,
+`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.
+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
+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 } },
+  (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 () {
+      return this.taskService.queryByStatuses(["todo"]);
+    }),
+  }),
+) {}
+
+export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => ({
+  startTask: mutation(cnst.Task, { guards: [SignedIn], mcp: { expose: true } })
+    .param("taskId", ID)
+    .exec(async function (taskId) {
+      return await this.taskService.startTask(taskId);
+    }),
+  reviewTask: prompt({ guards: [SignedIn], mcp: { expose: true } })
+    .param("taskId", ID)
+    .exec(async function (taskId) {
+      const task = await this.taskService.getTask(taskId);
+      return [Msg.user(`Review this task and suggest next steps.`), Msg.resource(`akan://task/${taskId}`, task)];
+    }),
+})) {}
+```
+
+- **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**.
+  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.
+- **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.
+- **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
+  match it, so a client SDK throws on the first call that finds nothing. A nullable *list* keeps its schema, and a
+  scalar return has no structured half at all: it ships as the value itself, not as JSON.
+- **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
+  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.
+- **`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
+  path, the spelling most clients try first). `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, and `AKAN_MCP_RESOURCE`
+  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.
+- 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
+  header. `AKAN_MCP_RESOURCE` pins the resource identifier where you cannot guarantee it.
+- **A `resources/read` uri that does not decode** — a stray `%` — is `Unknown resource`, not a server failure.
+- **A caller's own mistake is reported as one** and never as a server failure: an argument that is missing,
+  unparseable or **undeclared** comes back as `isError` naming it — `additionalProperties: false` travels in the
+  published schema and nothing on the wire enforces it — and so does a document that is not there, as
+  `No <model> found for the arguments given.` A `prompt`, having no `isError` to carry a refusal, answers `-32602`.
+  Only a real failure logs a stack; an agent can drive the rest at will.
+- **Three revisions are spoken**: the modern `2026-07-28` and the legacy `2025-11-25` / `2025-06-18`, which are
+  wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
+  disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
+  method answers `404` to a modern client but `200` to a legacy one, whose era spends `404` on "your session is
+  gone".
+- **A modern-era request mirrors `MCP-Protocol-Version` and `Mcp-Method` into headers** (plus `Mcp-Name` when the
+  body names one), and one that leaves a mirror out is refused just like one that contradicts the body: a gateway
+  rule keyed on a header never fires for the request that omitted it. Legacy requests are not checked. Capabilities
+  are derived from the catalogue, so a server with no prompts does not advertise `prompts`.
+- **An expired or wrongly-audienced bearer token is refused up front**, so an agent is told to authenticate rather
+  than that the tool does not exist. Its **signature is not checked** — that needs your app's own secret — so a
+  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.
+- **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.
+
+**`prompt()`** is invoked by the *user* — a client renders it as a slash command — not chosen by the model. `exec`
+returns `PromptMessage[]`, or a bare string that is wrapped into one user message; build them with `Msg.user` /
+`Msg.assistant` / `Msg.link` / `Msg.resource` / `Msg.image` / `Msg.imageOf`. It takes `.param()` and `.search()`
+only, because `prompts/get` sends a flat string map. **An embedded payload is masked by the model you name** —
+`Msg.resource(uri, task, { model: cnst.LightTask })`, or `Msg.mask(cnst.LightTask, task)` for one piece of an
+assembly. Taking the model as an argument is what makes a `{ ...doc }` spread maskable, since that and `toJSON()`
+arrive with the class already gone; a value with no model named whose `hidden`/`secret` fields are populated is
+**refused**, one level into a plain object too. **A `prompt` is also mounted as a
+plain HTTP `GET` whether or not you enabled MCP**, because that route is what lets a web UI preview one — and it
+is in your OpenAPI document like any other `GET`, answering the one fixed `PromptMessage[]` shape. MCP exposure
+gates the catalogue, not the surface, so guard it
+like any other read — and a prompt declaring no
+`guards` at all is named in the boot log, while an explicit `[Public]` is a decision and stays quiet. Every `Msg` builder takes
+optional `annotations` last (`audience`, `priority` 0..1, `lastModified`) — give the instruction a high `priority`
+and its attachments a low one, or a client with a full window drops blocks by position and keeps the attachment
+over the ask.
+
+**`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
+frames down included, and is a no-op when nobody is streaming — so the same code runs unchanged over HTTP, a
+websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
+costs something to assemble.
+
 ## Scalar Modeling (`**/*.constant.ts`)
 
 - Define Akan models in `.constant.ts` files with `via` from `akanjs/constant`.
@@ -630,6 +786,7 @@ export const pageConfig = { transition: "stack" } satisfies PageConfig;
 | `plugin/` | build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
 
 - Hooks return a named object of async closures, never a tuple.
+- `libs/<lib>/ui/tokens.css` is the one CSS file a lib owns: plain `:root` custom properties for colors that must **not** follow the theme (a vendor brand color, a fixed surface). Every app whose pages reach that lib compiles it automatically, ahead of the app's own stylesheets, so nothing is imported by hand and no app can forget it. Reference them as `bg-[var(--kakao)]`; `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet. Theme-following colors are the app's, not the lib's.
 - A layer-root `index.ts` is generated, but a `ui/<Folder>/index.tsx` that builds a namespace is hand-written source. The distinguishing test is that a generated barrel contains nothing but `export * from "./X";` lines.
 - `ui/<Folder>/index_.tsx` (trailing underscore) is the `"use client"` + `lazy()` boundary, with a server-safe `index.tsx` beside it. Collapsing the pair into one file breaks RSC.
 

package/guidelines/cssRule/cssRule.instruction.md

@@ -55,6 +55,13 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 - Switching themes is toggling the `data-theme` attribute. Keep every token defined in both the dark and light blocks.
 - Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes).
 
+## Lib-Owned Tokens (`libs/<lib>/ui/tokens.css`)
+- A lib that needs colors of its own — vendor brand colors pinned by someone else's guide (Kakao `#fee500`, Naver `#1ec800`), fixed in-game surfaces — declares them **once** in `libs/<lib>/ui/tokens.css`. Never copy the block into each app's stylesheet.
+- The file is collected automatically: every app whose page graph reaches that lib compiles it, ordered **ahead of** the app's own stylesheets, so the app wins on any variable both declare. There is nothing to import and no sync step to remember; two libs both declaring one variable resolve in lib-name order, so do not rely on that.
+- Declare plain custom properties under `:root`, not a Tailwind `@theme` extension: the color vocabulary is closed per stylesheet, so `bg-kakao` would generate no CSS. Reference them as `bg-[var(--kakao)]` / `text-[var(--kakao-foreground)]`, which `no-arbitrary-color` allows by design (a `var()` reference is not an arbitrary color literal).
+- Theme-following colors still belong to the app: a lib token is for a color that must **not** change with `data-theme`.
+- An `@import` the CSS pipeline cannot resolve fails the build; it is never dropped. A stylesheet under `page/` that no route imports is compiled by nothing and warns at build time.
+
 ## Codegen Rules
 - Do not hardcode hex or raw-palette colors (`bg-red-500`, `#ff0000`); use semantic tokens.
 - Do not put inline color literals in `style={{ }}`; use token classes.

package/guidelines/framework/framework.instruction.md

@@ -26,6 +26,7 @@ Use this as the compact framework context for AI codegen. It should explain how
 When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
 
 - **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
+- **Lib tokens (`libs/<lib>/ui/tokens.css`).** Colors a lib's own components pin — a vendor brand color, a fixed surface — are declared once there as plain `:root` custom properties and compiled into every app that reaches the lib, ahead of the app's stylesheets. Reference them as `bg-[var(--kakao)]`; never copy the block into each app.
 - **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
 
 ## Review Checklist

package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md

@@ -459,7 +459,9 @@ is convention that keeps hand-written code reading like generated code.
   generated. Never `import type { RootStore } from "../st"` — it crashes `akan build` with a Bun SSR segfault.
 - **`dictionary.ts`** — fixed chain with empty stages still written:
   `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`.
-  Every label is `t(["English", "한국어"])`, and nearly every one also carries `.desc([en, ko])`.
+  Every label is `t(["English", "한국어"])`, and nearly every one also carries `.desc([en, ko])`. One optional stage,
+  `.store()`, sits between `.endpoint()` and `.error()` for custom store actions whose name differs from the
+  endpoint they call — omit it rather than writing it empty.
 - **`srvkit/` adapters** — an injected singleton is an `adapt("name" as const, ({ use, env, plug, memory }) => ({…}))`
   class, injected with `plug(TheClass)`. It self-registers, so do not add it to `lib/option.ts`. `this.logger` is
   provided; lifecycle work goes in `override async onInit()`. A per-use value object stays a plain class you `new` at

package/incrementalBuilder.proc.js

@@ -16,7 +16,7 @@ import {
 import {
   AppExecutor,
   WorkspaceExecutor
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 import"./index-mxvakhsm.js";
 import"./index-1577bej2.js";
 import"./index-67546d0j.js";

package/{index-5sn5w2mt.js → index-3789fdpg.js}

@@ -1,22 +1,22 @@
 // @bun
 import {
   RepairRunner
-} from "./index-jf2ya7r2.js";
+} from "./index-yzmqvg23.js";
 import {
   WorkflowRunner
-} from "./index-qzdjd4ct.js";
+} from "./index-cv9cxs5k.js";
 import {
   ScalarScript
-} from "./index-y4vkyhvv.js";
+} from "./index-4mgkgba3.js";
 import {
   PrimitiveScript
-} from "./index-3vta1tqa.js";
+} from "./index-m90fn8xe.js";
 import {
   ModuleScript
-} from "./index-jhpa13zj.js";
+} from "./index-mewacxye.js";
 import {
   isPlaceholderAppId
-} from "./index-779ske1y.js";
+} from "./index-9va8zayb.js";
 import {
   AkanContextAnalyzer,
   akanMcpInstallConfigPaths,
@@ -27,14 +27,14 @@ import {
   renderDoctorText,
   resourceList,
   upsertCodexMcpServerBlock
-} from "./index-774gcx29.js";
+} from "./index-e4b2ae6b.js";
 import {
   buildAkanModuleContextIndex,
   createWorkflowBaselineSummary,
   createWorkflowStepRegistry,
   jsonText,
   toolingRolloutGate
-} from "./index-rxkpk7n4.js";
+} from "./index-kcsa1zff.js";
 import {
   Prompter
 } from "./index-j37qq1f2.js";
@@ -45,10 +45,10 @@ import {
   CommandContainer,
   runner,
   script
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 import {
   AppExecutor
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 
 // pkgs/@akanjs/cli/context/context.script.ts
 import { Logger } from "akanjs/common";

package/{index-y4vkyhvv.js → index-4mgkgba3.js}

@@ -9,14 +9,14 @@ import {
   createPassedPrimitiveReport,
   generatedFilesForSync,
   scalarChangedFiles
-} from "./index-rxkpk7n4.js";
+} from "./index-kcsa1zff.js";
 import {
   Prompter
 } from "./index-j37qq1f2.js";
 import {
   runner,
   script
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 
 // pkgs/@akanjs/cli/scalar/scalar.prompt.ts
 import { input } from "@inquirer/prompts";

package/{index-62955kn5.js → index-5yjc80ha.js}

@@ -1,14 +1,14 @@
 // @bun
 import {
   LibraryScript
-} from "./index-d43t8af2.js";
+} from "./index-8pd02prk.js";
 import {
   resolveMobileTargets
 } from "./index-76rn3g2c.js";
 import {
   runner,
   script
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 import {
   HmrWatcher,
   WatchRootResolver
@@ -18,7 +18,7 @@ import {
   LibExecutor,
   PkgExecutor,
   WorkspaceExecutor
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 import {
   __require
 } from "./index-r24hmh0q.js";
@@ -1898,9 +1898,9 @@ function openBrowser(url) {
 }
 
 // pkgs/@akanjs/cli/application/application.runner.ts
-var loadBuildRunner = async () => (await import("./applicationBuildRunner-ha3y8ew8.js")).ApplicationBuildRunner;
+var loadBuildRunner = async () => (await import("./applicationBuildRunner-73kbbb7e.js")).ApplicationBuildRunner;
 var loadReleasePackager = async () => (await import("./applicationReleasePackager-gg8ccbeh.js")).ApplicationReleasePackager;
-var loadCapacitorApp = async () => (await import("./capacitorApp-9xswcgx7.js")).CapacitorApp;
+var loadCapacitorApp = async () => (await import("./capacitorApp-mr81qdxq.js")).CapacitorApp;
 var loadAbstractCompactor = async () => (await import("./abstractCompactor-e5yq60qz.js")).AbstractCompactor;
 var loadPrompts = async () => await import("@inquirer/prompts");
 

package/{index-xmmzf150.js → index-65aeh789.js}

@@ -2,7 +2,7 @@
 import {
   runner,
   script
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 
 // pkgs/@akanjs/cli/page/page.runner.ts
 class PageRunner extends runner("page") {

package/{index-d43t8af2.js → index-8pd02prk.js}

@@ -2,10 +2,10 @@
 import {
   runner,
   script
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 import {
   LibExecutor
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 
 // pkgs/@akanjs/cli/semver.ts
 function parseVersion(version) {

package/{index-779ske1y.js → index-9va8zayb.js}

@@ -5,7 +5,7 @@ import {
 } from "./index-76rn3g2c.js";
 import {
   CommandExecutionError
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 
 // pkgs/@akanjs/devkit/capacitorApp.ts
 import { cp, mkdir, readFile, rm, writeFile } from "fs/promises";

package/{index-qzdjd4ct.js → index-cv9cxs5k.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   AkanContextAnalyzer
-} from "./index-774gcx29.js";
+} from "./index-e4b2ae6b.js";
 import {
   WorkflowExecutor,
   compactWorkflowInputs,
@@ -23,10 +23,10 @@ import {
   workflowCommandsForPlan,
   workflowPlanApproval,
   writeWorkflowRunArtifact
-} from "./index-rxkpk7n4.js";
+} from "./index-kcsa1zff.js";
 import {
   runner
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 
 // pkgs/@akanjs/cli/workflow/workflow.runner.ts
 import { mkdir, readFile, writeFile } from "fs/promises";

package/{index-774gcx29.js → index-e4b2ae6b.js}

@@ -2,7 +2,7 @@
 import {
   workflowRunArtifactPath,
   workflowSyncDir
-} from "./index-rxkpk7n4.js";
+} from "./index-kcsa1zff.js";
 import {
   AppExecutor,
   LibExecutor,
@@ -11,7 +11,7 @@ import {
   extractBlockVersion,
   isScannedAppRootEntry,
   readDevkitVersion
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 import {
   collectRecipeSources,
   findInlineRecipeDuplicates,

package/{index-kdh76j26.js → index-etwh7sd3.js}

@@ -6,7 +6,7 @@ import {
   ModuleExecutor,
   PkgExecutor,
   WorkspaceExecutor
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 import {
   getDirname
 } from "./index-1577bej2.js";

package/{index-gcv8ncfh.js → index-h5whaj26.js}

@@ -2,10 +2,10 @@
 import {
   runner,
   script
-} from "./index-kdh76j26.js";
+} from "./index-etwh7sd3.js";
 import {
   PkgExecutor
-} from "./index-z8ptfkzv.js";
+} from "./index-yzsxc30b.js";
 import {
   TypeScriptDependencyScanner
 } from "./index-46tjzh6s.js";