@akanjs/cli 3.0.0-alpha.7 → 3.0.0-alpha.70

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/mcpRule/mcpRule.generate.json

@@ -0,0 +1,25 @@
+{
+  "title": "MCP Exposure Rule",
+  "description": "How Akan signals reach AI agents over MCP — guard-derived exposure, refusals, prompts, and resources",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Signal files whose slices and endpoints declare the guards MCP exposure is derived from",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./mcpRule.instruction.md",
+    "contents": ["exposure rule", "configuration", "declaring endpoints", "refusals and wire behaviour", "prompts"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule before the reason, and keep the reason to one clause",
+      "Name the env spelling beside every option field",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -0,0 +1,220 @@
+# Akan MCP Exposure Guideline
+
+## Purpose
+Use this when writing a `*.signal.ts`, configuring `option.setMcp(...)`, or debugging a tool an agent cannot see.
+The always-loaded convention set carries the short version; this is the full contract.
+
+## Exposure Rule
+
+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.
+
+## Keeping An Endpoint Off The Shelf — `mcp: false`
+
+Guards answer "may an agent call this". They do not answer "does this belong on a shelf", and those are different
+questions: a step of a UI-driven state machine (`requestPhoneCodeForSignin`, `setPasswordInPrepareUser`) is
+perfectly guarded, perfectly callable, and a model would only ever call it by mistake. **`mcp: false` is that
+second answer, and it is an opt-*out*: everything still publishes by default, so an endpoint added later is
+visible without anyone remembering it.**
+
+```ts
+requestPhoneCodeForSignin: mutation(Boolean, { guards: [Every], mcp: false }),
+inTodo: init({ guards: [SignedIn], mcp: false }),           // the slice's list and insight together
+export class FileSlice extends slice(srv.file, {
+  guards: { root: Admin, get: SignedIn, cru: SignedIn },
+  mcp: { cru: false },                                       // reads yes, generated writes no
+}) {}
+```
+
+- **It is curation, not authorization.** HTTP serves the endpoint exactly as before and the guards are still the
+  only thing deciding who may call it. Never write `mcp: false` where you meant a guard.
+- **The `mcp` map on `slice()` mirrors the `guards` map above it** — same keys (`root`, `get`, `cru`, `create`,
+  `update`, `remove`), same fallbacks (`create`/`update`/`remove` inherit `cru`), and the same scope: it narrows
+  the root slice and the generated CRUD, and never reaches a named slice or a custom endpoint. Those declare
+  their own `mcp` beside their own `guards`. The bare `mcp: false` is every key at once, still within that scope.
+- **`mcp: true` is the default and is a no-op**; write it only to say out loud that an entry is deliberately on
+  the shelf. It does not override a shape refusal (an `Any` return stays refused) and it cannot publish something
+  the guard rules keep out.
+- **Reach for it by cost, not by taste.** Every entry inlines the schema of every model it mentions, so a plain
+  21-field model with one named slice costs 12.6KB across its eight entries. `mcp: { cru: false }` on that model
+  takes it to 4.7KB — the write entries carry both the input *and* the full model, and are 63% of it.
+
+## Configuration
+Settings live in the app's `lib/option.ts` — `option.setMcp({ … })`, taking `enabled`, `readOnly`, `path`,
+`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, 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_LEGACY_TEXT`, `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.
+
+## Declaring Endpoints
+```typescript
+// apps/<app>/lib/option.ts
+export const option = new AkanOption<ModulesOptions>().setMcp({
+  instructions: "Domain tools for this 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,
+  { 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 — 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] })
+    .param("taskId", ID)
+    .exec(async function (taskId) {
+      return await this.taskService.startTask(taskId);
+    }),
+  reviewTask: prompt({ guards: [SignedIn] })
+    .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)];
+    }),
+})) {}
+```
+
+## Refusals And Wire Behaviour
+- **`mcp: false` is read first**, because it is the one answer nobody had to derive — somebody stated it. Its
+  reason says "HTTP still serves it", because that is the sentence that stops the next reader treating it as a lock.
+- **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, **an argument typed `Any` that must be filled**, and the generated
+  **`light<Model>` read** — it returns the same document as `<Model>` under the same guards, in a shape trimmed
+  for a page's payload, so publishing both put two entries per model in a listing an agent pays for every turn
+  and gave it nothing but the word "light" to choose between them.
+  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.
+- **The boot log sizes the catalogue and says which signals it went to** — `MCP catalogue: tools=48 … · listing
+  214KB` and `MCP catalogue cost: user 27/71KB · file 6/22KB · …`, heaviest first. Read it before narrowing
+  anything: the number is nobody's intuition, because MCP has no shared component section and forbids a `$ref`
+  across entries, so **every entry inlines the full schema of every model it mentions** and a listing is re-sent
+  whole to every agent that connects, before its first turn. Past 100KB it says so as a `warn`.
+- **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
+  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
+  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`, `secret`, or `visual` field.** Every response has the first two 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 all three: they are legal to send, and the same model describes a request body.
+- **A `field.visual` is stripped from every MCP result.** It is the marker for a field the page renders and no
+  question is answered from — a blur placeholder, a rendered HTML body — and it is cost rather than secrecy, so
+  nothing is refused over one. The strip happens in the MCP dispatcher rather than in `resolveReturn`, which every
+  ordinary HTTP response also passes through: the whole point is that a browser still receives it. That is also why
+  the readable schema drops it — a non-optional visual field would otherwise be listed `required` and a validating
+  client would refuse a result that correctly omits it.
+- **A structured result ships twice by default**, once as `structuredContent` and once as the same JSON in the text
+  block, which is what the spec asks of a server for clients predating the structured field. It is also a flat
+  doubling of what every model-returning tool costs a model. `option.setMcp({ legacyTextBlock: false })` — or
+  `AKAN_MCP_LEGACY_TEXT=false` — leaves a one-line pointer in the text block instead, for a deployment whose
+  clients read the structured half. A scalar return is unaffected: it has no structured half to point at, so it
+  ships as the value itself either way.
+- 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.
+- 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.
+- **RFC 9728 metadata is published only once `AKAN_MCP_AUTH_SERVERS` names an issuer.** An unprotected resource
+  that still advertises `bearer_methods_supported` is treated by Cursor (and similar clients) as an OAuth
+  mandate, so the well-known document is absent until there is somewhere to obtain a token. When it is served,
+  it lives at `/.well-known/oauth-protected-resource` (and at that path plus the mount path, the spelling most
+  clients try first). `AKAN_MCP_SCOPES` and `AKAN_MCP_RESOURCE` configure the document when it exists;
+  `insufficient_scope` is enforced only once `AKAN_MCP_SCOPES` is set. A token carrying no `aud` at all is
+  refused once an issuer is named — 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.
+- **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
+  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>/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 three are the whole set**, so only the generated reads that
+  publish are addressable: a custom endpoint keeps its tool and gets no resource template, and the refused
+  `light<Model>` read has no address either.
+- **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()`
+**`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.
+
+## Progress Reporting
+**`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.

package/guidelines/workspaceOnboarding/workspaceOnboarding.generate.json

@@ -0,0 +1,24 @@
+{
+  "title": "Workspace Onboarding",
+  "description": "Product-workspace orientation — layout, decision matrix, workflow recipes, and query gotchas",
+  "group": "core",
+  "codegenPriority": 2,
+  "deprecated": false,
+  "scans": [],
+  "update": {
+    "filePath": "./workspaceOnboarding.instruction.md",
+    "contents": [
+      "workspace layout and generated files",
+      "agent workflow and common commands",
+      "where-do-I-put-this decision matrix",
+      "workflow recipes",
+      "modeling and query gotchas"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Write for someone building a product on Akan, not for someone changing Akan",
+      "Refer to the app as <%= appName %>; the renderer substitutes the workspace's first app",
+      "Do not repeat a rule that the conventions guideline already states"
+    ]
+  }
+}