@akanjs/cli 3.3.0-rc.10 → 3.3.0-rc.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.build-stamp CHANGED
@@ -1,2 +1,2 @@
1
- 984cbdba94dde6966611d879a86121ced462c91a2060fd6621b4b3bff85734b0
2
- 298221b3-4275-4aa5-b781-a5f2d86cc98b
1
+ fe2b1ec6e46be41a3fcddc26ae1d606607135418af33f89dec14b82ce61a6fc9
2
+ 94aaa09f-82a1-4735-9985-542e6b279b8b
@@ -21,6 +21,16 @@ import { BookApi } from "@apps/<app>/srvkit"; // a layer barrel: common, srvkit,
21
21
  import { signedIn } from "@libs/shared/webkit"; // a workspace created with --libs true
22
22
  ```
23
23
 
24
+ What these subpaths hold:
25
+
26
+ - `akanjs/dictionary` — locales, translations and the dictionaries behind labels, descriptions and `Err` keys.
27
+ - `akanjs/document` — database documents, filters, query builders, full-text search and persistence.
28
+ - `akanjs/service` — services, adapters, dependency injection and the business-logic runtime.
29
+ - `akanjs/store` — domain state, actions and the in-page agent's `st.tool` / `st.use` surface.
30
+ - `akanjs/client/native` — the native bridge and the built-in plugins of iOS, Android and desktop apps.
31
+ - `akanjs/native/desktop` — what an app's or a lib's own native plugin builds its desktop part from.
32
+ - `akanjs/test` — signal-test setup, MCP catalogue checks and sample data (`sampleOf`).
33
+
24
34
  ## Routes (`page/`)
25
35
 
26
36
  ### `page` · `akanjs/client`
@@ -15,7 +15,7 @@ apps, heads, CSR root layouts, lib pages, `devOnly`: `pageRule`.
15
15
  - **A route file exports one chain** — `page()`, `layout()` in a `_layout.tsx`, `rootLayout()` in a root
16
16
  `_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
17
17
  `.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
18
- A named export beside it fails the build.
18
+ A named export beside it fails the build, and the legacy `export default async function Page` is never written anew.
19
19
  - **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`; a layout
20
20
  may declare a subset. `akan sync` reads the names off the `export default` chain itself, so it refuses a chain bound
21
21
  to a variable first and a `[x]` folder whose page declares no `.param("x")`. `lang` is never declared — every stage
@@ -24,8 +24,6 @@ apps, heads, CSR root layouts, lib pages, `devOnly`: `pageRule`.
24
24
  and a canonical link / `og:url` comes only from the page's own `.head()`.
25
25
  - In a CSR bundle a root layout's own markup is hidden: what a person must see from it renders through
26
26
  `createPortal(…, document.body)`.
27
- - `_overrides.tsx` is one `export default override({ Slot: AppComponent })` (`akanjs/ui`), no logic, no
28
- `"use client"`. The legacy `export default async function Page` shape is never written anew.
29
27
  - `libs/<lib>/page` reaches an app through `syncPageLibs`, linked into the generated `page/(libs)/(<lib>)`; edit the
30
28
  lib source, never the link. `.config({ devOnly: true })` (a literal) keeps a route out of `akan build`.
31
29
  - `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
@@ -7,84 +7,24 @@ paths:
7
7
 
8
8
  # Services And Signals
9
9
 
10
- - `serve(...)` services hold business operations. Signals hold contracts: `internal(...)` for init, interval, cron
11
- and queue jobs (retries, dead letter: `workspaceRecipes` Recipe 5), `slice(...)` for focused data views feeding
12
- stores and zones, `endpoint(...)` for queries and mutations. External APIs and infrastructure go through
13
- `srvkit/` adapters injected into services, never vendor clients in domain logic.
14
-
15
- ## Calls, Queries, Agents
16
-
17
- - **Guards**: the `auth` rule, loaded with every `*.signal.ts`.
18
- - **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
19
- 30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
20
- dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
21
- `option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not a caller. A
22
- device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
23
- without `connect: true`, retries through `retry`, and rethrows a remote `Err` as is — never wrapped or re-keyed.
24
- - **Body types**: `.body()` / `.param()` take scalars, model refs, or `enumOf(...)`; `Int` / `Float`, never
25
- `Number` (`pkgs/akanjs/signal/endpointInfo.ts`); `Upload` only in a `fileUpload: true` mutation; bytes are
26
- `Binary`, never `Any`. A model or scalar argument is checked against the request schema on every transport: a
27
- wrong JSON type, a value outside its enum or a missing required field answers 400 with `data.name` naming the
28
- path (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's
29
- input keeps an absent field absent.
30
- - **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
31
- whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
32
- name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
33
- - **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
34
- `query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
35
- A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
36
- only way to read a `field.secret`. More rows: `loadMoreOf<Model>()` / `hasMoreOf<Model>`, never
37
- `count > page * limit`. A filter's `remove*` / `update*` are hookless (no cascade). No value is `q.empty`, never
38
- `q.missing`.
39
- - **Search**: `q.search(text, { prefix: true })` in a filter, at an AND position, over `text`-role fields; a search
40
- *slice* only on data safe to enumerate; blank input matches nothing — never a passthrough.
41
- - **`cascade` names a direction; the wrong one loses data**: `removeRef` on the owner's relation, `removeWith` on
42
- the child's reference to its owner. A query-level removal runs no cascade.
43
- - **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
44
- mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
45
- `.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
46
- required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
47
- screen with `page().prompt(name, description)`, and publish one component a host draws with
48
- `page().app(name, description, load)` — a read-only tool whose `load` may only query.
49
- - **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
50
- every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
51
- `option.setAgentRequestPolicy`, size-capped until one is set; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
52
- The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
53
- `st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
54
- `visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
55
- `<Agent.Guide instructions="…" />`; model-facing text is English.
56
-
57
- ## Injection And Adapters
58
-
59
- - A field named `<refName>Service` / `<refName>Signal` resolves to that registration — the suffix is required
60
- (`pkgs/akanjs/service/injectInfo.ts`). In a service: `service<srv.XService>()` · `plug(AdapterClass)` /
61
- `plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
62
- - `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
63
- `String` memory.
64
- - A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
65
- `storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
66
- `readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
67
- `access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
68
- - **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
69
- register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
70
- lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy
71
- `constructor(options)` adapters migrate only when already being changed. Example and adapter conventions (one
72
- `#api<T>` with a timeout, pagination, secrets, parameter shapes): `workspaceRecipes` Recipe 2.
73
-
74
- ## Error Placement
75
-
76
- - State-machine preconditions throw in `document.ts`, cross-document rules in `service.ts`, request policy in
77
- `signal.ts` guards. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no Result types.
78
- - A `pick` or generated `get<Model>` that finds no live row answers 404 `base.error.documentNotFound` by itself
79
- (`NoDocumentError`); load with a nullable `load<Model>` and throw `Err.NotFound` only to say more than that.
80
- - An endpoint names the errors it throws on purpose — `errors: { 409: ["ticket.error.locked"] }` in its signal
81
- option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
82
- of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
83
- `Err.is(error, "ticket.error.locked")`.
84
- - An `srvkit/` adapter belongs to no module: its keys go in the app's or lib's own service dictionary,
85
- `lib/_<name>/<name>.dictionary.ts`, thrown as `new Err("<name>.error.<key>")` with `Err` from `"../lib/dict"`.
86
- - `try/catch` turns an exception into a decision: guards → `logger.warn` → `false`; adapters → `logger.error` →
87
- `null`; UI `try/finally` resets a spinner. A bodyless `catch {}` needs a one-line reason.
88
- - Store actions do not `try/catch` (the framework toasts the `Err`); one no screen waits on (a token refresh) is
89
- listed in the store's `static silent`, rejecting untoasted to the caller that handles it. Client validation is
90
- `msg.error("<key>")` plus an early return, never a throw.
10
+ `serve(...)` services hold business operations. Signals hold contracts: `internal(...)` for init, interval, cron and
11
+ queue jobs, `slice(...)` for data views feeding stores and zones, `endpoint(...)` for queries and mutations. Guards
12
+ are the `auth` rule, queries and cascades the `module` rule. How-to and detail: the `akan-service`, `akan-transport`,
13
+ `akan-query`, `akan-mcp`, `akan-agent` and `akan-err` skills.
14
+
15
+ - **External APIs and infrastructure go through a `srvkit/` adapter**, never a vendor client in domain logic: an
16
+ `adapt()` singleton injected with `plug(TheClass)`. It registers itself, so it never goes in `lib/option.ts`.
17
+ - **An injected field is named `<refName>Service` / `<refName>Signal`** — the suffix is required
18
+ (`pkgs/akanjs/service/injectInfo.ts`).
19
+ - **`fetch.*` is one namespace across modules and a pubsub or message is routed by its bare name**, so the server
20
+ refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
21
+ - **On the wire**: `.body()` / `.param()` take `Int` / `Float`, never `Number`; bytes are `Binary`, never `Any`;
22
+ `Upload` only in a `fileUpload: true` mutation. Without `{ timeout }` the client quits at 30 s and the handler runs
23
+ on. A remote `Err` from `fetch.clone({ origin })` is rethrown as is, never wrapped or re-keyed.
24
+ - **MCP**: `/mcp` publishes every guarded endpoint by default; `mcp: false` is curation, not authorization. Never
25
+ make a refusal message more helpful.
26
+ - **In-page agent**: `<Agent.Chat />` refuses every call until `option.setAgentAccess(<guard>)`; the LLM is
27
+ `option.setLlm({ apiKey, model, host })`, never env; the surface is what components declare, never a store class.
28
+ - **Errors**: a state-machine precondition throws in `document.ts`, a cross-document rule in `service.ts`, request
29
+ policy in a `signal.ts` guard. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no
30
+ Result types. `try/catch` turns an exception into a decision, and a bodyless `catch {}` needs a one-line reason.
@@ -7,16 +7,10 @@ paths:
7
7
 
8
8
  # Client/Server Boundary And SSR
9
9
 
10
- ## Client / Server Boundaries
11
-
12
10
  - `"use client";` tops client component files. It is mechanical by role: `Template`, `Zone`, `Util` always carry it
13
11
  on line 1; `Unit`, `View` never do. `usePage()` is legal in server files.
14
12
  - A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never `export *` — the server knows a
15
13
  client module only by the names it spells out, so `akan start` / `akan build` stop on a star re-export.
16
- - Keep page props serializable unless the route pattern clearly allows otherwise; be careful importing client-only
17
- code into pages and layouts. Preserve file roles (`.document.ts`, `.service.ts`, `.store.ts`, `.constant.ts`,
18
- `.client.ts`), and inspect nearby files before introducing a new boundary pattern.
19
-
20
14
  - **Never import across the client/server boundary** (`apps/**`, `libs/**`; `no-import-server-in-client`,
21
15
  `no-import-client-in-server`). Client files (`ui/`, `webkit/`, `page/`, `*.store.ts`, every `.tsx`) never import a
22
16
  `*.document|dictionary|service|signal.ts`, `srvkit/`, a package `server` entrypoint, or the `db` / `srv` / `sig` /
@@ -25,22 +19,7 @@ paths:
25
19
  `common/` and `*.constant.ts` obey both. `import type` is legal everywhere; a mixed value-and-type import is not.
26
20
  - **Server-component discipline** on `page/**`, `*.Unit.tsx`, `*.View.tsx` (`no-import-client-functions`,
27
21
  `no-use-client-in-server`, `non-scalar-props-restricted`).
28
-
29
- ## SSR First — Server Rendering Is The Default
30
-
31
- Server-rendered JSX ships as HTML and costs nothing to hydrate; `"use client"` ships it twice (markup plus JS that
32
- re-runs). **The default is server; the directive is a cost justified per component** by a React hook, a JSX event
33
- handler, the store, a browser global, or a client-only package — never by markup, params, `l()` or mapping data.
34
- `akan quality ssr` (`--format json`) prints each app's and lib's server share: **50% is the floor, and a falling
35
- share is a regression** to justify in the PR or revert. A client package or an `index_.tsx` `lazy()` boundary
36
- justifies the directive; a `fetch.*` inside `onClick` is not flagged, only mount-time loads.
37
-
38
- Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction and render `children` untouched;
39
- ② split compound components (`Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`) — never one client file with a mode
40
- `useState` and every panel inlined; ③ fetch in the route and pass `init` / `view` to a `Zone`, never a
41
- `useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
42
- promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
43
- `<Load.Stream>` (model instances, server-only) — and `await` only what the shell must contain; ⑥ named `ReactNode`
44
- slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ gate auth with
45
- `.guard(() => signedIn())` on `_layout.tsx`, not in a body after I/O (the `page` rule); ⑨ CSS (`data-*` +
46
- `group-data-[…]`, `<details>`) over client state for visibility; ⑩ heavy islands behind `index_.tsx` + `lazy()`.
22
+ - **Server is the default.** `akan quality ssr` prints each app's and lib's server share: 50% is the floor, and a
23
+ falling share is a regression to justify in the PR or revert. Why, what earns the directive and the ten-step
24
+ playbook (wrap the interaction, split compound components, fetch in the route, hand promises across, …): `ssrRule`
25
+ in the `akan-ui` skill.
@@ -8,38 +8,15 @@ paths:
8
8
 
9
9
  # Styling
10
10
 
11
+ The theme, lib tokens, `cn`, recipes and component overrides: `cssRule`, `recipeRule` and `componentRule` in the
12
+ `akan-ui` skill.
13
+
11
14
  - **Never hand-order Tailwind classes** — `nursery/useSortedClasses` sorts them, `cn()` arguments included, and its
12
15
  output (`font-bold text-2xl text-foreground`) is correct.
13
16
  - **Stay inside the color vocabulary** (`no-raw-palette-class`, `no-arbitrary-color`, `no-interpolated-arbitrary-class`,
14
- `no-daisyui-legacy-class`, `no-inline-color`): no raw palette (`bg-blue-500`), arbitrary or interpolated color classes
15
- (`bg-[#3b82f6]`), daisyUI classes or slots (`btn-primary`, `bg-base-100`), or color literals in `style={{}}` — they
16
- render no CSS. Use semantic tokens (`bg-primary`, `text-foreground/70`); a legitimate fixed color takes
17
- `// biome-ignore lint/plugin: <reason>`. A daisyUI component name (`stat-value`) is only a warning, which
18
- `akan verify` drops once the app's or a lib's CSS defines that class. Slot replacements, SVG / `el.style` warnings,
19
- legal values: `cssRule`.
20
-
21
- - Static class strings stay plain. `cn` (from `akanjs/client`) only for a conditional or to merge an incoming
22
- `className`, caller last: `cn("base", cond && "extra", className)` — the only combiner: no `clsx`, raw `twMerge`,
23
- or object syntax.
24
- - Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
25
- - Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
26
- `Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
27
- name map (`BadgeVariants["variant"]`) moves to `webkit/`.
28
-
29
- ## Theme And Component Overrides
30
-
31
- When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
32
-
33
- - **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.
34
- - **Lib tokens (`libs/<lib>/ui/tokens.css`).** The one CSS file a lib owns: colors its own components pin that must **not** follow the theme — a vendor brand color, a fixed surface — declared once as plain `:root` custom properties and compiled automatically into every app whose pages reach the lib, ahead of the app's stylesheets, so nothing is imported by hand. Reference them as `bg-[var(--kakao)]`; never copy the block into each app. `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet, and theme-following colors are the app's.
35
- - **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.
36
-
37
- ## Recipes
38
-
39
- Framework UI recipes (Tailwind-variant look factories) import from `akanjs/ui`: `<name>(variants?, className?)`.
40
- The second argument merges internally and takes an array too, so never wrap it in `cn()`:
41
- `<name>({}, ["h-full", isWide && "w-full", className])`. Do not guess a recipe name or variant value, and do not open
42
- the recipe file to consume one. Before inlining a repeated surface (card, box, tile): reuse a recipe, or add one as
43
- `apps/<app>/ui/Recipe/<name>.ts`, one per file, re-exported from that folder's `index.ts` — never a near-duplicate.
44
- Each app and lib lists its own recipes in `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` (`## Recipes In Scope`),
45
- regenerated by `akan sync`. Full policy: the `recipeRule` guideline.
17
+ `no-daisyui-legacy-class`, `no-inline-color`): no raw palette (`bg-blue-500`), arbitrary or interpolated color
18
+ classes, daisyUI classes or slots, or color literals in `style={{}}` — they render no CSS. Use semantic tokens
19
+ (`bg-primary`, `text-foreground/70`); a legitimate fixed color takes `// biome-ignore lint/plugin: <reason>`.
20
+ - **Never guess a recipe name or variant value**, nor open a recipe file to call one: an app's and a lib's recipes
21
+ are listed in its `AGENTS.md` (`## Recipes In Scope`), the framework's below. A recipe's second argument merges by
22
+ itself and takes an array, so it is never wrapped in `cn()`.
@@ -9,7 +9,12 @@ Use TailwindCSS with Akan's semantic design-token layer and the `akanjs/ui` prim
9
9
  - Surfaces/text: `bg-background`, `text-foreground`, `bg-muted`, `text-muted-foreground`, `bg-card`, `bg-popover`, `border-border`, `border-input`, `ring-ring`.
10
10
  - Brand/status: `primary`, `secondary`, `accent`, `destructive`, `success`, `warning`, `info`, `neutral`, `open` — each with a `-foreground` pair for text on that surface (e.g. `bg-primary text-primary-foreground`).
11
11
  - Compose classes with `cn` from `akanjs/client` (token-aware tailwind-merge) — the only class-combining function. No object syntax: write `cond && "x"`.
12
- - Forward `className` last so callers can extend styles.
12
+ - Static class strings stay plain: `cn` only for a conditional or to merge an incoming `className`.
13
+ - Forward `className` last so callers can extend styles: `cn("base", cond && "extra", className)`.
14
+ - Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
15
+ - An enum→class lookup is a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
16
+ `Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
17
+ name map (`BadgeVariants["variant"]`) moves to `webkit/`.
13
18
 
14
19
  ## Color Vocabulary — What Lint Refuses
15
20
  - Vocabulary closure strips the raw Tailwind palette, so these render as no CSS and fail lint: raw palette classes
@@ -34,10 +39,11 @@ Use TailwindCSS with Akan's semantic design-token layer and the `akanjs/ui` prim
34
39
  - `buttonRecipe({ variant: "primary", size: "lg" }, "w-full rounded-2xl")`
35
40
  - Prefer the `akanjs/ui` primitives (`Button`, `Badge`, `Input`, `Field`, `Table` …) over re-implementing a component's look with utility stacks. There is **no `Card`/`Box` primitive** — a card/box is a recipe surface (e.g. `appCard`), not an `akanjs/ui` component; do not `import { Card }`.
36
41
  - App-specific repeated surfaces go one-per-file in `apps/<app>/ui/Recipe/` (server-safe, no `"use client"`) via `recipe(tv({ base, variants }))`, imported from `@apps/<app>/ui`. App recipes **extend** (surfaces the lib lacks — chat bubble, tile); they never re-define a lib component in parallel.
37
- - Full recipe authoring/consumption policy: the `recipeRule` guideline. Never guess recipe names/imports — the authoritative list is `AGENTS.md` `## Recipes` plus the `list_recipes` tool.
42
+ - Full recipe authoring/consumption policy: the `recipeRule` guideline. Never guess recipe names/imports — the authoritative lists are the `style` rule (framework recipes) and each app's or lib's `AGENTS.md` (`## Recipes In Scope`).
38
43
 
39
44
  ## Customization Decision (where a design delta goes)
40
- Screen code is invariant — a plain `<Button variant="primary">` never changes. Only these config files do:
45
+ When a request implies a distinct look and feel, do not stop at colors — customize the theme and, when needed, the
46
+ components. Screen code is invariant — a plain `<Button variant="primary">` never changes. Only these config files do:
41
47
  - **Theme differs** (color/radius/font) → override token *values* in `apps/<app>/page/styles.css`.
42
48
  - **A lib component's look differs** → recipe override: `export default override({ recipes: { button: neonButtonRecipe } })` in a `page/**/_overrides.tsx`. Every `<Button>` in that route subtree re-skins; behavior (async states, focus, a11y) is untouched. The swap recipe must accept the framework recipe's full variant surface.
43
49
  - **Structure/behavior differs** (modal → drawer) → component override (`override({ Modal: BrandModal })`), reassembling headless parts.
@@ -70,7 +76,8 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
70
76
  ```
71
77
  - The framework maps these variables to Tailwind color names (`@theme inline` in `akanjs/ui/styles.css`), so a class like `bg-primary` / `text-foreground` resolves to different colors per `data-theme` — the app only sets values, never re-declares the mapping.
72
78
  - Switching themes is toggling the `data-theme` attribute. Keep every token defined in both the dark and light blocks.
73
- - Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes).
79
+ - Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes);
80
+ the theme retunes corner rounding through `--radius-box` / `--radius-field`.
74
81
 
75
82
  ## Lib-Owned Tokens (`libs/<lib>/ui/tokens.css`)
76
83
  - 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.
@@ -22,8 +22,8 @@ hallucinated, re-derived inline, or duplicated across an app.
22
22
  - The second arg is a `ClassNameValue`, so it takes **an array (and falsy entries), not just one string**:
23
23
  `<name>({}, ["h-full", isWide && "w-full", className])`. Reaching for `cn()` to combine several classes is the
24
24
  usual way the no-`cn` contract leaks — there is nothing `cn()` adds here that the recipe does not already do.
25
- - **Do not guess** recipe names or import paths. The authoritative index is split by ownership: the root `AGENTS.md`
26
- `## Recipes` (always loaded) lists **framework** recipes, and each app/lib's own `AGENTS.md` (`## Recipes In Scope`)
25
+ - **Do not guess** recipe names or import paths. The authoritative index is split by ownership: the `style` path rule
26
+ (loaded with every `.tsx`) lists **framework** recipes, and each app/lib's own `AGENTS.md` (`## Recipes In Scope`)
27
27
  lists what that scope may additionally import — its own recipes plus its dependency libs'. Both carry every recipe's
28
28
  variant surface and default, so consuming one never requires opening its file. The scoped index is regenerated by
29
29
  `akan sync <name>` and kept honest by `akan lint <name>`, which fails when it is stale.
@@ -46,7 +46,7 @@ The form of a shared look is decided by **counting**, not judgment (`akan lint`
46
46
  ## Authoring Recipes
47
47
  - A **reusable or repeated surface** (card, box, tile, chat bubble, hero, …) belongs in a recipe, **not** inline. If the same
48
48
  token-class stack appears in more than one place, extract it into a recipe.
49
- - **Before authoring, check the existing recipe indexes** (root `AGENTS.md` `## Recipes` for framework recipes, the
49
+ - **Before authoring, check the existing recipe indexes** (the `style` path rule for framework recipes, the
50
50
  scope's own `AGENTS.md` `## Recipes In Scope` for app/lib recipes) and **reuse** a matching recipe instead of
51
51
  creating a near-duplicate — registry sprawl comes from re-inventing looks that already exist.
52
52
  - Add a new recipe as its own file, `ui/Recipe/<name>.ts` holding a single
@@ -15,6 +15,9 @@ on the client side**.
15
15
  - In domain UI the file role fixes the directive: `Template`, `Zone`, and `Util` are client; `Unit` and `View` are
16
16
  server. That decides *where* the boundary sits, not how much markup sits behind it — a `Zone` that hoards markup
17
17
  is still an SSR regression.
18
+ - Keep page props serializable unless the route pattern clearly allows otherwise, and be careful importing
19
+ client-only code into pages and layouts. Preserve file roles (`.document.ts`, `.service.ts`, `.store.ts`,
20
+ `.constant.ts`, `.client.ts`) and inspect nearby files before introducing a new boundary pattern.
18
21
  - Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and
19
22
  lib as server-rendered JSX elements over total. Treat **50% server share as the floor** and a falling share as a
20
23
  regression to justify or revert.
@@ -286,6 +286,10 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
286
286
 
287
287
  - `.body(...)` / `.param(...)` args accept `ConstantFieldTypeInput` only: scalars, model refs, or `enumOf(...)`.
288
288
  Numbers are `Int` or `Float` — `Number` is rejected (`pkgs/akanjs/signal/endpointInfo.ts`).
289
+ - **A model or scalar argument is checked against the request schema on every transport**: a wrong JSON type, a
290
+ value outside its enum or a missing required field answers 400 with `data.name` naming the path
291
+ (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's input
292
+ keeps an absent field absent.
289
293
  - **`Upload` is valid only inside a mutation flagged for file upload**:
290
294
  `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a
291
295
  model field type. The other body args of such a mutation arrive typed as in a JSON body. A file's `type` on the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@akanjs/cli",
3
- "version": "3.3.0-rc.10",
3
+ "version": "3.3.0-rc.12",
4
4
  "sourceType": "module",
5
5
  "type": "module",
6
6
  "publishConfig": {
@@ -40,7 +40,7 @@
40
40
  "@earendil-works/pi-tui": "1.5.2",
41
41
  "@inquirer/prompts": "^8.7.3",
42
42
  "@tailwindcss/node": "^4.3.3",
43
- "akanjs": "3.3.0-rc.10",
43
+ "akanjs": "3.3.0-rc.12",
44
44
  "chalk": "^6.0.1",
45
45
  "commander": "^15.0.0",
46
46
  "dayjs": "^1.11.23",
@@ -30,10 +30,19 @@ import path at all**, so keep throwing code out of them entirely rather than rea
30
30
 
31
31
  Best-effort code returns a sentinel (`null`, `undefined`, `{}`) instead of throwing. `try/catch` is rare and
32
32
  always converts an exception into a decision: a guard catches, warns, and returns `false`; an adapter
33
- catches, logs, and returns `null`. A store action never catches — let the framework toast the `Err`, or list it in
34
- the store's `static silent` when no screen waits on it and its caller handles the rejection.
33
+ catches, logs (`logger.error`), and returns `null`; a UI `try/finally` resets a spinner. A store action never
34
+ catches — let the framework toast the `Err`, or list it in the store's `static silent` when no screen waits on it
35
+ and its caller handles the rejection.
35
36
  Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
36
37
 
38
+ An `srvkit/` adapter belongs to no module: its keys go in the app's or lib's own service dictionary,
39
+ `lib/_<name>/<name>.dictionary.ts`, thrown as `new Err("<name>.error.<key>")` with `Err` from `"../lib/dict"`.
40
+
41
+ **An endpoint names the errors it throws on purpose** — `errors: { 409: ["ticket.error.locked"] }` in its signal
42
+ option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
43
+ of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
44
+ `Err.is(error, "ticket.error.locked")`.
45
+
37
46
  **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(…, { origin })`
38
47
  restores the remote `Err` with its class, key and data. Rethrow it as-is — wrapping it in a `new Error`
39
48
  discards what the endpoint chose to say, and a bare `Error` is generalized to "Internal Server Error" on the
@@ -33,19 +33,13 @@ export default page()
33
33
  dropped. `lang` reaches every stage and is never declared.
34
34
  3. Gate with `.guard(() => signedIn())` on the `_layout.tsx`, and repeat a stricter guard on a page that needs more.
35
35
  `.guard((_, { path }) => signedIn({ path }))` sends a refused visitor to `/signin?redirect=<path>`.
36
- 4. In `.render()`: `usePage()`, then fetch, then return. Hand `fetch.init*` / `view*` / `edit*` fields to sections
37
- unawaited; await only what the shell reads, in one `Promise.all`.
38
- 5. `.head()` takes JSX (or a function returning it), never a metadata object.
39
- 6. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
36
+ 4. In `.render()`: `usePage()`, then fetch, then return.
37
+ 5. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
40
38
  `export default override({ Slot: AppComponent })`, no logic. Nested ones merge slot by slot, the closest winning;
41
39
  `componentRule` lists the slots.
42
40
 
43
41
  ## API at a glance
44
42
 
45
- `page`, `layout` and `router` come from `akanjs/client`, `Link` from `akanjs/ui`, `usePageLocation` from
46
- `akanjs/webkit`, and `fetch`, `usePage` and the model namespaces from `@apps/<app>/client`. A stage receives the
47
- declared params and search keys plus `lang`.
48
-
49
43
  - Data-driven title: `.head(async ({ id }) => <title>{((await fetch.book(id)) as Book | null)?.title}</title>)`,
50
44
  where `Book` is the `common/` interface for the query's `Any` return (`akan-service`).
51
45
  - Async page: `.render(async ({ id }) => { const book = (await fetch.book(id)) as Book | null; if (!book) return router.notFound(); … })`;
@@ -65,12 +59,8 @@ declared params and search keys plus `lang`.
65
59
  scrollToTop: false })`` in a `"use client"` component, read back with `usePageLocation().searchParams`. Shallow
66
60
  holds only while the path stays the same; a server `.search()` sees the value at the next full navigation.
67
61
 
68
- ## Never
69
-
70
- - A `fetch.<mutation>()` while rendering — it throws `base.error.mutationInRender`, because opening a link would
71
- perform it. Send writes from a user action.
72
- - `useState`, `useEffect`, comments, a named export beside the chain, or the legacy `export default async function`.
73
- - Editing a lib page through its link in `page/(libs)/` — edit the lib's own `page/` source.
62
+ What a route file must never do — write while rendering, hooks, a second export — is the `page` rule, loaded with
63
+ any `page/` file.
74
64
 
75
65
  Full detail: `get_guideline` with `pageRule` (guards in depth, heads, MCP apps, CSR root layouts, lib pages), or
76
66
  `ssrRule` for what may render on the server. Every stage's signature, the router's methods, Link's props and every