@akanjs/devkit 3.1.2-rc.4 → 3.2.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,358 @@
 # @akanjs/devkit
 
+## 3.2.0
+
+### Minor Changes
+
+- 29756e1: `akan lint`, `akan lint-all` and `akan verify` now hold each package under a workspace's `pkgs/` to a structure budget, as they already hold apps and libs: a file up to 800 lines, a function up to 150 lines (`akan.size.function`) and a class up to 60 members (`akan.size.class`). Tests and their fixtures (`*.test`, `*.spec`, `*.fixture`, `*.instance` and `*.bench` files, and `test/`, `tests/`, `__tests__/`, `__fixtures__/` and `__mocks__/` folders), `.d.ts` files, re-export barrels and a package's `examples/` are left out, and a package in a git repository is listed through git, so ignored files are never measured. Each package keeps its own `akan.baseline.json`; `akan quality baseline` now seeds one for each package too, `akan quality scan` reports its exceptions, and packing a package that would publish one fails.
+
+  A baseline only shrinks from the default branch's copy. Where the default branch has none, an app's, lib's or package's baseline may hold only the breaches the default branch's code already has, so a new one starts empty instead of skipping the check. A file's line count no longer includes the newline ending its last line, so a recorded size may drop by one on the next `akan lint`.
+
+  Upgrading: in a workspace whose packages are over the budget, run `akan quality baseline` once to record what they hold today.
+
+  `akan test <target> --coverage` measures coverage: a summary on stdout and `lcov.info` under `local/coverage/<target path>`. CI runs each package's tests this way and keeps the report as an artifact.
+
+### Patch Changes
+
+- bc792ab: What a coding agent needs to build its first app is now written where it looks, and two messages say what to do next.
+
+  - **A query or mutation that answers `null` without `nullable: true`** now fails with `query <name> answered null, but its return is not nullable: answer a value, or declare { nullable: true } and answer null`. It used to fail with `Required Any value: null`, or `Invalid Value (Nullable)` for a model, which named neither the endpoint nor the fix.
+  - **`akan build` for the `local` environment** ends its summary with one line: such a build serves the dev routes to every caller, and a host others can reach needs `AKAN_PUBLIC_ENV=main`, `AKAN_PUBLIC_REPO_NAME` and `AKAN_PUBLIC_SERVE_DOMAIN`. A build for any other environment prints nothing new, and the check that refuses a deployed build with stand-in values is unchanged.
+  - **The `akan-page` skill** carries a one-screen API summary: a data-driven `<title>`, an async render, `router.notFound()` and a layout's `.notFound()` / `.error()`, `Link`, and a shallow `router.replace` for a client filter kept in the URL. The page rule names the shallow replace too.
+  - **The `akan-service` skill** carries a recipe for pages backed by an external HTTP API: an `adapt()` adapter in `srvkit/` that reads its base URL at boot, a `lib/_<service>` service, a `Public` `query(Any, { nullable: true })` endpoint and its dictionary label, and the page that calls it.
+  - **The README's "Inside an existing repository"** runs the creator through `npx -y bun@1.4.4 x …` on a host with only Node and npm, so nothing global is written. It also gives copy-ready `build` and `start` scripts, says a fresh clone builds without a committed env file, and says which environment a `.env`-less build is for and what a deployed host sets instead.
+
+- 61fbd7d: `get_graph` takes `since`, a git revision, and returns the Change Map: the Akan Graph of what changed since HEAD forked from that revision, working tree and untracked files included. Every node, field and edge is marked `added`, `removed` or `changed`. The unchanged nodes a changed one calls, or is called by, stay in as context, and `unmapped` lists the changed files under `apps/` or `libs/` that no node covers, each marked the same way. `since: "HEAD"` maps uncommitted work only. Files `.gitignore` covers stay out, a renamed file reads as removed and added, and a CRLF checkout of an unchanged file reads as unchanged. A revision git does not know returns a `graph-since-unknown` diagnostic, and so does one HEAD shares no commit with (a shallow clone, say) instead of comparing with its tip. A revision that starts with `-` also returns it and never reaches git.
+
+  - **`AkanGraphDiff.between(base, head)`** in `@akanjs/language` diffs two graphs. `index.graph(readText, { digests: true })` gives each member, query, component and field a hash of its body text, so an edit inside a method, or to a field's options, marks it changed and moving it does not.
+  - **The change types** (`AkanGraphChange`, `AkanChangeMap`, `AkanChangedFile`) live in `akanjs/common`.
+
+- a707354: Akan Studio maps the framework itself, and `pkgs/akanjs/ARCHITECTURE.md` keeps its tables from the source.
+
+  - **The Framework view** (`/_akan/studio?view=framework`, `akan studio <app> --view framework`) lays the `akanjs` facets and `@akanjs/devkit` out by layer, with their largest classes, and draws value, lazy and type-only imports apart. Under it, one table per process channel names who sends and who handles each message, each linked to its source. It reads `pkgs/akanjs` in this repository and the installed `akanjs` in a consumer workspace (without its bundled `vendor/` and `types/`), and never joins the app's own graph or `get_graph`. The dev builder rebuilds it only when the installed version changes or a save lands under `pkgs/`.
+  - **`FrameworkMapBuilder`, `FrameworkChannelReader` and `FrameworkMapDoc`** in `@akanjs/language` build the map with the TypeScript compiler API: facets and their import layers, and for each channel union the classes that write a message's `type` literal or branch on it.
+  - **`pkgs/akanjs/ARCHITECTURE.md`** pairs a hand-kept walk through the processes and a request with a generated part between markers. `akan sync-architecture` regenerates that part, and a devkit test fails when it is stale, when a channel is gone, when two facets load values from each other, when a message lacks a recognised sender or handler outside a short list whose other end lies beyond the framework source, or when the hand-kept part names a class the source no longer has.
+  - **`AkanIpcMessage` no longer lists `backend-ready`.** The gateway sends it to the dev host, which reads it as a `BuilderMessage`, where it stays; no gateway or child ever handled it.
+
+- 0351ad4: The Akan Graph keys each guard by the app or lib that declares it, `guard:libs/shared:Admin`, and follows the import that names it there, so `Admin as AdminGuard` reaches `Admin`, `srvkit.Admin` reaches the lib's class, and two libs' `Admin` stay two nodes. A guard read out of an object map, `SSO.Kakao`, resolves through the imports of the file that declares the map. A name a lib only re-exports reaches the class it re-exports. A guard a factory makes is a guard too, whether the factory sits in the same file, wraps another factory there, or is imported from another lib. A guard node carries its source location, `doc` (the comment above its declaration that says what it checks) and, in `detail`, its `scope` (`account` or `resource`). A factory-made guard takes the factory's scope, and takes its doc when no guard of that factory has its own. With digests, an edit to a guard or to the factory that makes it marks the guard changed in the Change Map. Every guard a workspace declares is a node, referenced or not. `Public` and `None` come from `akanjs`, carry no location and say what they do. Studio shows a node's `doc` in its tooltip.
+
+  Ids and details that change for a saved graph or a Change Map base:
+
+  - A guard id names its owner: `guard:Admin` is now `guard:libs/shared:Admin`, and the framework's `guard:Public` is `guard::Public`.
+  - An endpoint's `detail` names a guard as written: `srvkit.Admin` and `SSO.Kakao` where it read `Admin` and `Kakao`.
+  - A slice map entry that lists several guards, `cru: [Owner, None]`, now reads `cru Owner` and `cru None` in `detail`, and links each of them, where it read `cru ?` and linked none.
+
+  - **`FileFacts.imports`, `guards`, `guardFactories` and `guardCalls`** in `@akanjs/language`: the reader records each class that implements `Guard` (under any name it is imported as), each factory that returns one or calls such a factory in the same file, and each const that a factory makes, a local one or an imported one. `AkanIndex.setFile` reads them from every non-test `srvkit/` file and every other non-test file that names `Guard` and `canPass`.
+  - **`AkanGraphNode.doc`** in `akanjs/common`: an optional one-paragraph description.
+
+- ba417c6: The Akan Graph draws a module's jobs and the adaptors its services plug. Each key of an `internal()` class is an `internal` node, `internal:apps/demo:memo.sweepMemos` labelled `MemoInternal.sweepMemos`, whose `detail` reads its type, its schedule (a cron expression, or an interval or timeout such as `5m`), its `serverMode` and `operationMode`, `disabled` for `enabled: false`, `once` for `once: true` and `unlocked` for `lock: false`; a job links to the service methods its `exec` calls, as an endpoint does. A `resolveField` is a field resolver, not a job, and stays out. Each `adapt()` or `dangerouslyAdapt()` class is an `adaptor` node keyed by the app or lib that declares it, with its registered name in `detail`, its location, the comment above it and a digest; anything a service plugs from `akanjs`, such as `DatabaseAdaptorRole`, is `adaptor::DatabaseAdaptorRole` with no location. A service method that calls a plugged field (`this.storageApi.deleteData(url)`) links to that adaptor rather than to whatever else shares the method's name, and a `plugs` edge runs from an adaptor to each adaptor it plugs. Studio's signals view shows jobs in its "Endpoints, slices & jobs" column and adaptors in "Queries, models & adaptors".
+
+  - **`internal`, `adaptor` and `plugs`** join `AkanGraphNodeKind` and `AkanGraphEdgeKind` in `akanjs/common`.
+  - **`FileFacts.internals` and `FileFacts.adaptors`** in `@akanjs/language`, with `ServiceClassFact.plugs`; `AkanIndex.setFile` also reads non-test files that call `adapt` or `dangerouslyAdapt`.
+
+- bb40785: The Akan Graph maps `page/`. Each route file is a `route` node named by its URL pattern after the locale (`route:apps/demo:/memo/:memoId`, groups dropped as the router drops them), and each `_layout.tsx` is a `layout` node keyed by its folder (`layout:apps/demo:/(app)`, `root` for a `rootLayout()`). A `wraps` edge runs from each layout to the routes and layouts directly inside it, located at the wrapped file. A route or layout whose default export runs `.guard()` reads `guard` and links each function its guard calls that the file imports or declares: `.guard(() => signedIn())` reaches `signedIn` in `@libs/shared/webkit`, with its location and the comment above it, and a function declared in the page itself is keyed by that file (`guard:apps/demo:page/pin.tsx#isOwn`). A call to anything else (`Boolean`, akanjs's `redirect`, a package's `dayjs`) is looked through, a helper handed to a guard (`isOwn(isId(id))`) is not a guard, and an imported guard is looked up under its import path first. A layout's guard gates every route it wraps; the routes themselves do not repeat it, so a guard added to a layout marks only that layout changed in the Change Map. A route's default export, or the const it names (`const route = page()…; export default route`), is the route node itself, so the slices and actions a page uses hang off its URL. `_overrides.tsx` and the git-ignored `page/(libs)/` links are left out; a lib's own pages are its routes. A route's digest covers its whole file, so the Change Map marks an edited page changed instead of listing it as unmapped.
+
+  An unscoped `get_graph` still answers a graph of up to 600 nodes whole. Past that, it first drops the routes and layouts that neither changed nor use a change, and the route-only guards they leave unlinked, before it asks for a scope; an `app` or `module` scope brings them back. Studio's first column reads "Pages & components".
+
+  - **`route`, `layout` and `wraps`** join `AkanGraphNodeKind` and `AkanGraphEdgeKind` in `akanjs/common`.
+  - **The fact reader** in `@akanjs/language` now also exposes `importsIn`, `docOf` and `extentOf`.
+
+- d2bd9b7: A new read-only MCP tool, `get_graph`, returns the Akan Graph, read from source with no dev server. It holds the models with their fields and relations, scalars and enums, slices and endpoints with their guards, and the service methods and queries each one calls. It also holds the store actions that fetch them and the components and pages that use them. Every node and edge carries its file, line and column. A workspace over 600 nodes asks for `app` and/or `module`; a scope keeps its own nodes and their direct neighbours. Files under `env/` are never read.
+
+  - **`AkanIndex.graph(readText)`** in `@akanjs/language` builds the graph from the same index that answers definitions. An app module that extends a lib module of the same name links to the app's own node. A component links only through `fetch`, `st` and `sig`, so `option.orgId` is not read as model `org`.
+  - **The graph types** (`AkanGraph`, `AkanGraphNode`, `AkanGraphEdge` and their kinds) live in `akanjs/common`.
+
+- 2d357d6: Editors can now jump from a name Akan.js derives to the key it comes from. `fetch.initMemoInPublic`, `st.do.setNameOnMemo` and `this.memoService.listByName` had no definition before, because TypeScript drops the declaration of a key a mapped type renames. A new package, `@akanjs/language`, indexes those names from source text, and an editor extension serves them. The extension (`pkgs/@akanjs/vscode`) is not on a marketplace yet; build it with `bun pkgs/@akanjs/vscode/build.ts --vsix`.
+
+  - **`@akanjs/language`** is an editor-neutral reverse index over a workspace's constant, document, service, signal and store files. It needs no type checker, and the host passes in its own `typescript`. For a derived name it answers definition and hover; for a source key it answers references, the keys to put a CodeLens on, and the edits of a rename. It covers slice names (`initMemoInPublic`, `slice.memoInPublic`, `memoListInPublic`), Filter queries (`listByName`), model CRUD and state (`getMemo`, `viewMemo`, `memoForm`), form setters across the `via(...)` chain (`setNameOnMemo` lands on `MemoInput.name`), store state setters, `subscribe`/`listen` endpoints, and module references (`this.memoService`, `srv.memo`, `sig.memo`). A name resolves within its own app and every lib, never another app. It ships as ES module and CommonJS with no runtime dependency.
+  - **The extension** adds those definitions and hovers next to TypeScript's, with a `Go to slice` link in the hover. A CodeLens on each slice key, Filter query key, constant field, store state key and pubsub or message endpoint shows its use count, plus the guards and `live` of a slice. Find References from a source key lists every derived use. F2 on a slice or Filter query key (or `Akan: Rename the slice or query key with its derived names`) renames the key, every name derived from it and its dictionary entry; a use that could also be another model's is left for TypeScript to report, and F2 elsewhere stays TypeScript's. In a trusted workspace it loads the workspace's own `@akanjs/language` when one is installed, so its rules match the framework version.
+  - **One copy of the name rules.** The templates behind the names apps call now live in `akanjs/common` (`sliceNames`, `queryNames`, `modelNames`, `databaseStateNames`, `formSetterNames`, `stateSetterName`, `endpointNames`, `moduleNames`). The runtime, devkit's scanners and scaffolds, and `@akanjs/language` all read them, and a type test fails when a mapped type and its table disagree. `databaseStateNames` and `formSetterNames` now live in `akanjs/common`; `akanjs/store` keeps them as deprecated aliases.
+  - devkit's write-placement and SSR checks read signals through the same reader, and its form-setter check now builds `set<Field>On<Model>` names forward from each module's constant instead of matching a pattern, so a slice setter such as `setPageOfProductOnSale` no longer reads as a field setter.
+
+- 69ed07e: Akan Studio draws the Change Map.
+
+  - **The Changes view** (`/_akan/studio?view=changes`) draws what changed since HEAD forked from the default branch, or since `since=<rev>`, uncommitted work included.
+    - Components, store actions, signals, service methods, queries, models, scalars, enums and guards are laid out in flow order and outlined as added, removed or changed. The fields that changed are listed inside their model.
+    - The unchanged nodes a change calls, or is called by, are drawn dimmed. The changed files no node covers are listed under the diagram, each marked added, removed or changed.
+    - Only this app's and the libraries' nodes are drawn. `module=` scopes the map to one module.
+    - A revision git does not know is shown as a message on the page. The `since` you picked stays when you switch views.
+    - The dev builder keeps the last map until the next save, so reloading the page does not read the workspace again.
+  - **`akan studio <app> --view changes [--since <rev>]`** prints its URL. `--since` without `--view changes` is an error.
+  - **Akan: Open the Change Map** in the VS Code / Cursor extension opens it beside the editor. The extension offers to start the app only when no dev server answers, not on any other `akan studio` failure.
+
+- 3f231a7: `akan start` now serves Akan Studio at `/_akan/studio`, a read-only view of the Akan Graph for the running app and the libs it reaches.
+
+  - **ERD:** models, scalars and enums with their fields. Each relation is drawn from the field that names it, and each referenced type sits to the right of the model that names it.
+  - **Signals:** one module laid out from left to right: components and pages, store actions, endpoints and slices with their guards, service methods, then queries and models.
+  - **Interaction:**
+    - Hovering a box highlights its edges and neighbours, and clicking it pins the highlight.
+    - The filter dims boxes whose name doesn't match.
+    - Every name opens its source in VS Code or Cursor.
+    - `/_akan/studio/graph` returns the same graph as JSON.
+  - **How it's built:**
+    - The page is server-rendered SVG with a small inline script, and loads no client bundle.
+    - The dev builder draws the graph on request through a new `build-graph` builder RPC, and keeps it until the next save.
+    - It sits behind the same gate as the other `/_akan` devtools routes, and `akan tunnel` / `akan start --share` refuse it.
+
+- 0504209: `akan build <app> --env <env>` builds for an environment other than the workspace `.env`'s, the way the desktop and mobile builds already do. Before, the shell's `AKAN_PUBLIC_ENV` lost to the `.env`, so a new workspace could only build `local` without editing it. The local-build notice, the image guard and the README now say what a `local` build changes in a built server: no endpoint rate limits, and local defaults for Redis and the database mode. They no longer say the dev routes are served, which a built server never does.
+- bf872ce: A variable the shell sets now outranks the workspace `.env` when `akan` builds or runs an app, as dotenv and Bun's own `.env` loading do: `AKAN_PUBLIC_ENV=main akan build <app>` builds `main` where the `.env` says `local`. The order is `--env` (for `AKAN_PUBLIC_ENV`), then the process environment (the shell, and the `.env.local` and `.env.<NODE_ENV>` Bun loads into it), then the `.env`, then the defaults; an empty export counts as unset. The bundles, the bundled server env, `akan.env.json` and the Dockerfile still take one set of values. Where an exported value outranks the `.env`, `akan build` now warns with both values instead of the old warning that listed the values it ignored, and the server-env message, the `--env` help, the local-build notice, the README and the CLI reference state the new order.
+
+  **Behavior change:** where the shell exports a value the workspace `.env` also sets, such as `AKAN_PUBLIC_ENV`, `AKAN_PUBLIC_REPO_NAME` or `AKAN_PUBLIC_SERVE_DOMAIN`, `akan` now takes the shell's. Unset it, or match the `.env`, to build what you built before.
+
+- e65172d: The CLI refreshes a cloud sign-in once less than an hour, or half the token's lifetime, is left, whichever is shorter. Before, a token that lived an hour or less read as due the moment it arrived, so every command rotated the refresh token and then called the cloud unsigned. Any unexpired token is now sent with the request, except the refresh call, which carries none. `akan login` signs in again when a session is due for refresh and has no refresh token left.
+- c3b5b3c: A web page no longer loads `@akanjs/native/core`. `isNativeApp()` and the other host checks read the platform the shell writes before the bundle runs, and a native shell still starts core with the page. On the minimal app this takes 15 KB raw (5.6 KB brotli) off the vendor floor and 20 KB raw (6.6 KB brotli) off every route entry. `akan build` also resolves the `production` export condition for the browser, SSR-client, CSR and MCP App view bundles, so a package such as Lexical ships its production build alone. On the minimal app the Agent editor chunk drops from 91 KB to 63 KB brotli. `akan start` is unchanged.
+- 6d5b544: A database service now has `create<Model>Many(rows)`. It creates the rows on the same path as `create<Model>`: `_preCreate` and `_postCreate`, the document's save and create hooks, and the live and pubsub events each row's commit fires. Every row's `_preCreate` and document pre hooks run first, so a check there that queries the table does not see the batch's own rows. The rows are then written in one transaction, joining the caller's when one is open, with one multi-row INSERT per 500 rows instead of one statement per row; if the database refuses one row, none is written. Every row's `_postCreate` runs once the transaction commits, as `create<Model>`'s runs once its row is stored, so a `_postCreate` that throws leaves the rows written. A service that already declares a method of that name, itself or in a lib service it extends, keeps its own at runtime, but its signature no longer typechecks against the generated one: rename it.
+
+  A store can list actions in `static silent = ["refreshToken"] satisfies (keyof UserStore)[]`. When a silent action fails, it shows no toast and logs at verbose instead of error. It still rejects with the original error, so a background write such as a token refresh is awaited by its caller, which handles the failure. Generated actions can be listed, and a store built on a lib store keeps the lib's silent actions. A name in `static silent` that is not an action of the store is reported when the store registers.
+
+  `akan lint`'s `akan.service.call-in-loop` fix and the agent guidelines name `create<Model>Many` as the way to write a set once.
+
+- cb44cc0: `akan create-workspace` and `bunx create-akan-workspace` can now create a workspace in a folder you already have, leave out the sample code, and make the first commit on a machine with no git identity. Before, a coding agent that had to put the workspace in a given folder created it elsewhere, copied it over and deleted the sample by hand.
+
+  - **In place.** Name the workspace `.` to create it in the current folder, or in `--dir` itself, instead of a new `<dir>/<name>` subfolder. The workspace takes that folder's name.
+
+    ```bash
+    bunx create-akan-workspace . --app web             # the current folder
+    bunx create-akan-workspace . --app web --dir app   # ./app
+    ```
+
+    The folder may already hold files the workspace does not write, such as `.git`, `.vscode/launch.json` or notes. When it holds one the workspace would overwrite, such as `package.json`, `README.md`, `.gitignore` or `apps/<app>`, the command writes nothing and lists them. The same check now guards `<dir>/<name>`, which was overwritten without a word before. It also refuses your home folder and a filesystem root, where the first commit would take in every file and the agent and MCP settings would overwrite your global ones. And it refuses a folder whose path ends the way a path it writes begins, such as `apps`, `patches`, or `apps/web` with `--app web`, since the files would land in the wrong place.
+
+  - **`--sample false`** creates the first app without the sample: the `task` module and its pages, the `_noti` service, the `workHistory` scalar, and the sample helpers in `common/`, `webkit/`, `srvkit/` and `ui/`. It defaults to `true`, as before.
+
+    ```bash
+    bunx create-akan-workspace my-company --app web --sample false
+    ```
+
+  - **Git.** When git has no identity configured, as in many containers and CI images, the first commit is made as `Akan.js <noreply@akanjs.com>` instead of failing; once `user.name` and `user.email` are set, `git commit --amend --reset-author` makes it yours. In a folder another git repository tracks, the scaffold no longer runs `git init`, which made the outer repository record a gitlink instead of the files, and it commits nothing there: the new files are left for you to commit in that repository. A folder that repository ignores, as `app/` or `app/*` does, still gets its own repository and commit.
+  - **`@akanjs/devkit`**: `applyTemplate` takes `dryRun` to list the files a template would write without writing them, and `WorkspaceExecutor.commit` takes an `identity` to commit under.
+
+- 1870fcd: `akan verify` adds a `fix:` line to a module file's two-parent import that names the layer barrel to import from instead, such as `import from "@apps/<app>/common"`. The lint message itself now points at the layer barrel too.
+- 245d318: A font declared on a root layout now gets its metric-adjusted fallback faces: `@font-face` rules named `"<font> fallback"` that draw a local system font with `size-adjust`, `ascent-override` and `descent-override` matched to the web font. The variable `--font-<name>` already named that family, but the build never wrote it, because fontaine's `readMetrics` takes a URL and returned nothing for the file path it was given. While a web font loaded (`font-display: swap`), text drew in the browser's default font, usually a serif, and moved when the web font arrived. The metrics are read from the source font, not the subset, so a subset without Latin letters (`subsets: ["ks-x-1001"]`, or only `subsetText`) still sizes the fallback correctly. A font whose metrics cannot be read keeps its face and gets no fallback, as before. Set `adjustFontFallback: false` on a font to keep the old output. Cached font output from `akan start` is regenerated once.
+- 6f6cc2a: A fresh clone of a workspace now builds and starts after `bun install` alone. The env files that hold secrets stay gitignored, so a clone has none of them: before, `akan typecheck`, `akan build` and `akan verify` failed with `Cannot find module './env.server.local'`, and with no `.env` the CLI picked the `debug` environment, so `akan build` stopped asking for `AKAN_PUBLIC_REPO_NAME` and `AKAN_PUBLIC_SERVE_DOMAIN`.
+
+  - **Missing env files are written on sync.** `akan sync`, and every command that syncs first (`build`, `start`, `typecheck`, `verify`, `test`), writes each per-environment file that `env/env.server.ts` or `env/env.client.ts` imports and the checkout lacks, plus `env/env.server.testing.ts`, in apps and libs alike. A file comes from the folder's tracked `env.server.example.ts` or `env.client.example.ts` when there is one, otherwise with the defaults a new workspace starts with. A file that exists is never touched, and sync logs the files it wrote. Put this machine's values in them, or fetch the team's with `akan download-env`, which overwrites them.
+  - **No `.env` means the local environment.** A workspace command run where there is no `.env` takes `AKAN_PUBLIC_ENV=local`, the environment a new workspace's `.env` names and `env/env.server.ts` falls back to, unless the shell sets `AKAN_PUBLIC_ENV`. A `.env` that exists is read as before, so a CI job that writes one, or sets the variable, builds what it did.
+  - **New workspaces** also track `env.client.example.ts`: its `.gitignore` no longer ignores it, as it already did not ignore `env.server.example.ts`.
+
+  **For an existing workspace** nothing is required. To give a fresh clone values other than the empty defaults, commit an `env/env.server.example.ts` (and `env.client.example.ts`) without secrets in it; in an older workspace, add `!**/env.client.example.ts` to `.gitignore` for the client one. If you link env files into a new worktree, link them before the first `akan` command there, or replace the defaults it wrote.
+
+- e2b809a: The typecheck behind `akan typecheck`, `akan verify` and `akan build` now uses its incremental cache. It wrote a `.tsbuildinfo` on every run, then checked every file again anyway, so a run with nothing changed cost as much as the first: about 8 seconds on a 2,400-file project. Now a run re-checks only the files that changed and the files they affect, and reads the rest from the cache. The same project's second run takes about 1.2 seconds. The diagnostics are the same, in the same order, as a full check: options, global, syntax, type and declaration errors, an edited file's new errors and the errors it causes in files that import it. `--clean` still clears the cache first.
+- bf28968: An app can now serve its default locale at unprefixed paths. Set `i18n.localePrefix` to `"as-needed"` in `akan.config.ts`, and `/books/OL45804W` is the English page itself. Before, every page lived under `/<locale>/…`, and an unprefixed path answered with a 307 to the locale the browser asked for. An app with one language, or with URLs fixed from outside (OAuth callbacks, QR codes, links in mail, a migrated site), could only meet them with raw `<a href>`s, which reloaded the whole page and went through that 307 on every click.
+
+  ```ts
+  const config: AppConfig = {
+    i18n: {
+      defaultLocale: "en",
+      locales: ["en", "ko"],
+      localePrefix: "as-needed",
+    },
+  };
+  ```
+
+  - **The default stays `"always"`**, so an app that sets nothing serves and links exactly as before.
+  - **Under `"as-needed"` the default locale drops the prefix and the other locales keep it.** `<Link href="/types">` renders `/types` on an English page and `/ko/types` on a Korean one, and still navigates in place. So do `router.push`, a server `router.redirect()`, `setLang`, active-link matching, the 404 page's home link, `hreflang` alternates and `/sitemap.xml`. `setLang` to the default locale drops the prefix. A single-locale app has no prefix anywhere.
+  - **An unprefixed URL always means the default locale.** No Accept-Language redirect runs, so one URL is one locale for caches and search engines.
+  - **`/<defaultLocale>/x` answers with a 308 to `/x`**, so links from the `"always"` days keep working and land on the one canonical URL. The 308 is cached for a day, so an app that goes back to `"always"` stops redirecting within that time.
+  - **Native and CSR boots keep their locale paths.** Their routes match on the `/:lang` segment, so a `?csr=true` request without one is redirected to the default locale's prefixed path. An Android app link limited to a basePath lists the default locale's unprefixed path as well as its prefixed one, so links from before the switch still open the app.
+  - `akan preview` keeps an unprefixed path unprefixed under `"as-needed"`, except with `--csr`. The value reaches bundles as `AKAN_PUBLIC_LOCALE_PREFIX`, and the image env carries it when it is `"as-needed"`. `LocalePath` (`akanjs/common`) and a fourth `localePrefix` argument to `getPathInfo` build the same URLs in app code.
+
+- 9b5bcee: Every SSR page now loads 72K less framework JavaScript (22K less after Brotli).
+
+  - **`akan build` narrows the vendor entries to the names the page code imports.** The `akanjs/*` and `tailwind-merge` entries in the page's import map used to re-export a whole facet. Each one now exports only the names the built route bundles import, lazy chunks included. On the minimal app, the framework floor, meaning the runtime plus the vendor entries every page loads, drops from 630.2K raw / 189.4K br to 558.4K raw / 167.4K br. `akan start` keeps whole facets, so a newly saved import never misses a name.
+  - **The agent runtime moved to `akanjs/store/agent`, which has its own vendor entry.** This covers `AgentContext`, `AgentVisual`, `AgentPrompts`, `StoreSurfaceSource`, the `Screen*` readers and the rest. A page now loads that entry (28.6K raw / 9.4K br) only when it mounts `Agent.Chat`, `Agent.Zone` or `Agent.Dock`. `akanjs/store` still re-exports these names for one minor, marked `@deprecated`. A build whose pages import none of them keeps the runtime out of the store entry. `ToolReturn`, `AgentAbort` and `AgentProgress` stay in `akanjs/store`.
+  - **A tab left open across a deploy loads its next page as a document when the import map changed.** Narrowed vendor entries differ from build to build, so a newer route chunk could import a name the tab's vendor entries lack. Each document now names its import map, and the server answers a navigation from another import map with 409. The client then loads the target as a document, with the current import map.
+  - **A narrowed build fails when route code imports a name its facet does not export**, and names the missing names. Before, the page threw a `SyntaxError` in the browser.
+
+- 4561152: The skill examples now use one neutral domain, books from a public read-only API: a `BookApi` adapter in `srvkit/`, a `lib/_openlibrary/` service with a `book` query, `fetch.book(id)` and `/books/[id]` pages. This covers the `akan-service` external-API recipe, the `akan-page` API summary, the `akanApi` import block, the `config` rule's `localePrefix` example and the README's as-needed path. The recipes teach the same steps as before.
+- 53eb6f1: A command whose app-or-lib target is left out no longer stops at a prompt error when stdin is not a terminal, as in a coding agent's shell or CI. In a workspace with a single app, lib or package, `akan sync`, `akan lint`, `akan test` and `akan create-module <name>` run on it and say so on stderr, so a new workspace's `bun run sync`, `bun run lint` and `bun run test` work there. Otherwise every target command (app, lib, package, module) exits at once with the valid targets and the line to rerun, such as `akan sync <app-or-lib>`. A library, package or module is still never picked unasked, since `akan remove-library` and its kin would delete the only one. A terminal is asked as before.
+- b24fef3: An app that draws no Akan UI component now builds and runs without the UI's optional peers. Before, `akan build` failed with `Could not resolve: "react-icons/ai"` or `"react-spring"` in an app that imported nothing from `akanjs/ui`: the System UI every root layout mounts drew react-icons glyphs and reached the model, list and dialog components through the `Load` and `Button` modules, and the CSR build, on by default, bundled the whole `akanjs/ui` barrel.
+
+  **Upgrade note.** A workspace can drop `react-spring`, `@react-spring/web`, `@use-gesture/react`, `react-refresh`, `scheduler` and `tailwind-scrollbar` from its `package.json`, unless its own code imports them. `akanjs` now depends on `@react-spring/web`, `@use-gesture/react`, `react-refresh`, `scheduler` and `tailwind-scrollbar` itself, because the System UI, the dev runtime and `akanjs/ui/styles.css` always use them, and nothing uses `react-spring` any more. New workspaces no longer list them. A workspace whose own code keeps `react-spring` or `@react-spring/web` must move it to major 10: an older one installs a second copy under `akanjs`, and a spring value the app makes no longer typechecks on an `animated.*` element from `akanjs/ui`.
+
+  - **`react-icons` stays an optional peer.** Install it when the app draws a component that shows its icons, as most form, list and dialog components do. Under `akan start`, a CSR page (`?csr=true` or a native shell) of an app that imports anything from `akanjs/ui` still needs it: the dev module registry loads that barrel whole.
+  - **`chance`** stays an optional peer that only `akanjs/test` needs.
+  - **The System UI draws its own icons.** The Button's processing and done states, the toasts and the reconnect overlay render inline SVGs with the same markup react-icons drew.
+  - **The generated root layout and `_overrides.tsx` wrapper** import `System` and `UiOverrideProvider` from their own files instead of the `akanjs/ui` barrel.
+  - **The CSR build and its MCP App views** rewrite `akanjs/ui` imports to the components a file names, as the SSR route builds already did, so a page that imports `Link` no longer bundles every component.
+  - **Animations use `@react-spring/web`** instead of the `react-spring` umbrella package, which also installed the native, three.js, konva and zdog renderers.
+
+- 686e0b8: `akan preview` and the code agent's page preview bound a page only once the browser is up. Before, a process's first page shared its `timeoutMs` with starting the browser. On a cold machine where Chrome took longer than that to start, the first page failed as `Timed out loading …; the dev server may be rebuilding or stuck.`
+
+  Starting the browser now has its own bound of 120 s, `startTimeoutMs` on `PreviewView.probe`. Running out of it reads `Timed out starting the <engine> browser after 120 s.`, where the engine is `chrome` or `webkit`. A browser that misses its bound may still come up late, so later pages in that process try again, but each waits only its own `timeoutMs` for the browser. Once the browser answers, the full bound applies again. So a browser that never starts holds the first page for 120 s, where before it held it for `timeoutMs` (60 s for `akan preview`, 30 s for the code agent's check).
+
+- eefd9cb: `akan preview <app> /_akan/studio` opens Studio instead of a 404. Preview added the default locale to every path, and the server routes `/_akan/*` without one, so `/en/_akan/studio` matched no page. A path under `/_akan`, `/__csr`, `/__rsc`, `/.well-known` or the app's API prefix, a file the app's `public/` holds, and the server's own `/favicon.ico`, `/robots.txt`, `sitemap.xml` and `manifest.webmanifest` now open as written: no locale, and no CSR boot query under `--csr`. Every other path, including one that already starts with a locale or ends in a dotted segment such as `/release/1.2.3`, is a page and gets the default locale as before. The `akan-debug` skill and the `akan preview` reference say so.
+- 4fcf44f: A new `rename-key` workflow renames a slice key or a Filter query key everywhere it is spelled. That covers the key itself, every name derived from it (`initMemoInPublic`, `memoListInPublic`, `queryByName`) in the app and every lib, and its module dictionary entry. It is the same rename the editor extension's F2 runs, so agents get it through `plan_workflow` / `apply_workflow` and the CLI through `akan workflow plan rename-key --app <app> --module <module> --slice <key> --to <newKey>` (or `--query <key>`). The plan lists each file it will change. A use that could also be another model's is left alone, and `akan verify` then reports it.
+- 9a9e1fa: A server page from `akan build` now preloads its client modules from `<head>`, so a cold load stops waiting on chains of imports.
+
+  - **What is preloaded:** the rsc client and the chunks it imports, the chunks every client reference row (`I` row) in the shell's flight names, and the importmap vendors those chunks import, each with its own chunks. A client URL that only the page's own text carries is never preloaded. Before, only the rsc client and the locale dictionary were preloaded. The browser found the rest one import level at a time, after the document finished.
+  - **Measured on `apps/minimal`:** `/en/explore` preloads 45 modules and its flight names 18 client chunks, all of them preloaded. `/en/lab/buttons` preloads 112 for 85. Preloading every client component each route's page and layouts import would have meant 237 modules for `/en/explore`, so the preloads follow the flight instead.
+  - **A boundary that resolves after the shell** still loads its chunks when its flight rows arrive. `akan start` preloads nothing new, because a dev page loads its client code from the SSR dev registry.
+  - `routes-manifest.json` carries the preload table as `modulePreloads`: the runtime chunks, each vendor's chunks, and the vendors each browser chunk imports.
+
+- 9a9e1fa: `akan build` measures the JavaScript each server route loads, and fails a route that outgrows the budget the app commits.
+
+  - **The measure:** the runtime, every client module statically reachable from the route's page and layouts, and their vendors, counted in the brotli bytes the server sends. A chunk loaded by a dynamic `import()` is left out, and so is the locale dictionary. A new `Measuring route JS` step names the largest route, and the summary lists the ten largest with their brotli and raw sizes. On `apps/minimal` the largest is `/:lang/explore` at 499.1KB brotli (1.3MB raw).
+  - **The budget:** `akan build <app> --update-budget` writes `apps/<app>/akan.budget.json` with the environment it built for and one `routeJsBrotliKB` entry per route. After that, `akan build` fails a route that passes its entry by more than the larger of 1% and 4KB, as the bundle size gate does, and names the route, its bytes and its limit, so CI stops the growth. The slack absorbs the `AKAN_PUBLIC_*` values a build inlines, so a budget recorded for one environment holds for another, and a failure says when the file was recorded for another one. The update adds a new route, lowers an entry its route now fits under and drops a route that is gone. It never raises an entry: to raise one, edit it by hand in the change that grows the route.
+  - **Where it fails:** `akan build` fails on an overage or an unreadable file, and `--update-budget` rewrites an unreadable file. `akan verify` warns of each route over its entry and of an unreadable file, one line each, but never fails on them. A mobile or desktop build skips the step.
+  - **Opt-in:** an app without the file gets the report and nothing fails. A route without an entry is reported, not failed. `akan sync` accepts `akan.budget.json` at an app root.
+
+- 27440aa: A production build now runs without Docker: `cd dist/apps/<app> && bun main.js` serves the app with no env set. Until now the env the built server needs (the app and repo names, the serve domain, locales, route prefixes, database modes and the rest) existed only as `ENV` lines in the generated Dockerfile. On a host without the image, such as a PaaS or a test harness, the server stopped at boot with `getEnv() cannot run at build time` unless a start script copied every value by hand.
+
+  **Upgrade note.** Run `akan agent install` and commit what it writes: the `akan-runtime` skill, the `config` path rule and `runtimeRule` now say how to run a build without Docker.
+
+  - **`akan build` writes `akan.env.json` beside `main.js`**, with the same values as the Dockerfile's `ENV` lines. None of them is a secret.
+  - **`main.js` reads it before any other module loads** and fills in only the variables the process was not started with. A variable set in the environment wins, even an empty one, so `PORT=3000 bun main.js` and a host's own settings still apply, and an image built from the generated Dockerfile runs exactly as before. The file is found beside `main.js` from any working directory, but start the server from its own folder, because the runtime reads its artifacts and writes `runtime/` and SQLite files relative to the working directory.
+  - **An app that writes its own Dockerfile** (`docker` as a string) and copies the build into its image now gets these values too, for whatever its Dockerfile leaves unset: among them `NODE_ENV=production`, `AKAN_PUBLIC_OPERATION_MODE=cloud` and `AKAN_LOG_TO_FILE=0`, so set those in the Dockerfile if the image needs other values.
+  - **A desktop app's carried server leaves `akan.env.json` behind.** Its launcher hands it its env as before, and the file would otherwise set the `PORT` and `AKAN_LOG_TO_FILE` the launcher leaves out on purpose.
+
+- e3de9ef: The CLI's MCP tools, tunnels, env download, local registry and generated Dockerfile now stay narrower by default. Each changed default below names how to get the old behaviour back.
+
+  - **Workflow and repair commands run without a shell.** A command taken from a plan file, a run report or an MCP argument now runs as `bun run akan <args>`. It runs only when it is an `akan` subcommand whose arguments are plain words or flags; anything else is not run and fails with exit code 2. `akan workflow validate` and `apply` (and the `apply_workflow` / `run_validation` MCP tools) rebuild the validation commands from the workflow's own spec instead of reading them from the file.
+  - **Workflow inputs are plain names.** An `app`, `module`, `scalar`, `field`, `slice`, `mutation` or `interaction` input may hold letters, digits, `-` and `_`, with no dots, slashes or spaces. Planning reports anything else as `workflow-input-invalid`, and `apply` refuses such a plan with `workflow-plan-inputs-invalid`. The `app` must be one of the workspace's apps or libraries (`workflow-target-missing`), and the `repair_*` tools check their target the same way (`repair-input-unknown`).
+  - **MCP workflow files stay in `.akan/workflows/`.** `plan_workflow`'s `out`, `apply_workflow`'s `planPath` and the `runIdOrPlan` of `run_validation` and `doctor_workspace` must resolve inside the workspace's `.akan/workflows/` folder. A path elsewhere, or a link that leads out of it, is refused. A bare run id still means `.akan/workflows/runs/<id>.json`.
+  - **The cluster database tunnel listens on loopback.** The Redis or Postgres tunnel `akan start` opens to a cluster environment now listens on `127.0.0.1` instead of every interface. Set `SSH_TUNNEL_BIND_HOST=0.0.0.0` to listen on every interface again; the tunnel then logs a warning on each start.
+  - **The tunnel checks the SSH host key.** When `SSH_TUNNEL_HOST_FINGERPRINT` lists `SHA256:` fingerprints (comma-separated), only those keys are accepted. Otherwise the first key a host shows is kept in `~/.akan/ssh_known_hosts.json`, written with mode 0600, and a different key from that host is refused. The refusal names the host and the file entry to remove after a rebuild. `SSH_TUNNEL_KNOWN_HOSTS` points at another file, and `SSH_TUNNEL_HOST_FINGERPRINT=*` accepts any key, as before.
+  - **The tunnel signs in with a key when given one.** `SSH_TUNNEL_PRIVATE_KEY_PATH` (with `SSH_TUNNEL_PASSPHRASE` if the key has one) or `SSH_TUNNEL_PASSWORD` sets how the tunnel signs in. Without either, it still uses the default shared credential, as before, and logs a warning.
+  - **A repository's dotenv file cannot loosen the tunnel or pick the registry.** `SSH_TUNNEL_HOST_FINGERPRINT`, `SSH_TUNNEL_KNOWN_HOSTS`, `SSH_TUNNEL_BIND_HOST`, `SSH_TUNNEL_PRIVATE_KEY_PATH`, `SSH_TUNNEL_PASSPHRASE` and `AKAN_NPM_REGISTRY` are ignored, with a warning, when a dotenv file in the working directory (`.env`, `.env.local`, `.env.<mode>`, `.env.<mode>.local`) names them, in `KEY=value` or `KEY: value` form, since Bun loads those files before the CLI runs; `create-akan-workspace` does the same for `AKAN_NPM_REGISTRY`. Export them in the shell instead. `SSH_TUNNEL_USERNAME`, `SSH_TUNNEL_PASSWORD` and `SSH_TUNNEL_PORT` are still read from a dotenv file, and `--registry` is unaffected.
+  - **`akan download-env` copies only env and secret files.** The archive is unpacked into a temporary folder under `local/`. Only `apps/<app>/env/env.{client,server}.*.ts`, `libs/<lib>/env/env.{client,server}.*.ts` and the files an app's `secrets` patterns name are copied into the workspace. Every other entry, links included, is left out and listed in a warning.
+  - **The local registry listens on loopback.** `akan start-registry` now publishes Verdaccio's port as `127.0.0.1:<port>`, taking the port from `--registry`. A registry URL with an IP address (`--registry http://0.0.0.0:4873`) binds to that address instead. A running `akan-verdaccio` container that already listens on every interface gets a warning naming the command that recreates it.
+  - **The local registry takes anonymous publishes for the akan packages only.** The bundled `verdaccio.yaml` still lets anyone publish the Akan.js packages. Every other name, the ones proxied from npm, now needs a signed-in user, and sign-up stays off, so a local publish cannot stand in for an npm package. Give those entries `publish: $all` again to restore anonymous publishing.
+  - **Subspace names are plain folder names.** A subspace `name` takes letters, digits, `.`, `_` and `-`, and starts with a letter or digit. Any other name is refused when the config is read and when the clone is set up.
+  - **A Dockerfile built for the `local` environment stops `docker build`.** The generated Dockerfile of an image built with `AKAN_PUBLIC_ENV=local` fails right after its `FROM` line unless `--build-arg AKAN_ALLOW_LOCAL_IMAGE=1` is passed. Images built for any other environment, and a Dockerfile given verbatim in `akan.config.ts`, are unchanged.
+  - **The sample app's task writes need a signed-in user outside local and testing.** The workspace sample's `task.signal.ts` now guards its create, update and task actions with a new `LocalOrSignedIn` guard in `srvkit/guards.ts`. A guest still writes under `AKAN_PUBLIC_ENV` `local` or `testing`, so the sample's own tests keep running. Existing workspaces are unchanged.
+  - **`akan login` prefers the device-code answer.** When the cloud answers both ways, the CLI takes the session answered for its device code. A cloud that answers only for the sign-in URL's id still signs you in, and the CLI logs a warning.
+  - **`akan tunnel` keeps the dev-only routes local.** On opening a share, the CLI now says that anyone with the URL reaches the app without signing in. Through the share, devtools (`/_akan/devtools`, `/_akan/signal`, `/_akan/constant`, `/_akan/deps`, `/_akan/dictionary`), the HMR socket `/_akan/hmr`, `/_akan/app/*`, `/_akan/ops/*` and every `*.map` file answer 404, and an `x-akan-debug` header is dropped. Pages, their assets and the app's websocket pass through unchanged. `akan start --share` opens its shares through the same filter and prints the same notice. `akan tunnel --dev-routes` (`-d`) shares everything, as before.
+  - **The `no-unguarded-endpoint` lint and the agent guidelines describe the new defaults.** The lint says an endpoint without guards is refused with 403 and stops the boot outside local operation, and the guidelines and skills cover the ops channel's limits, snapshot encryption, the agent's write confirmation and request caps.
+
+- e3de9ef: `akan code` hardening:
+
+  - Every profile's deny list now also covers per-environment server env files (`env.server.{debug,develop,main,testing,local}*.ts`; the `env.server.ts` loader and the type file stay readable), Kubernetes and Jenkins credential files, `.akan/code/mcp.json` and `.akan/code/extensions/`, and the home credential stores `~/.akan`, `~/.ssh`, `~/.aws`, `~/.kube`, `~/.docker/config.json`, `~/.netrc` and `~/.git-credentials`, for read, write and the shell. A path is checked the way the engine reads it (`@`, `~`, `$HOME` and `file://` expand) and again through its real path, so a link cannot give a denied file another name. A profile passed to `CodeAgent.create` with its own `paths.deny` still decides its list.
+  - The `local` profile asks before a `web_fetch` to a host off a short list of documentation and registry hosts, and before a shell command that reaches the network (`curl`, `wget`, `ssh`, `scp`, `rsync`, `nc`, …); loopback is exempt. Where nobody can answer, such as a sub-agent or a one-shot run, the call is refused instead. `akan code --no-ask-network` turns the question off. A fetch the profile makes without asking follows a redirect only to a host it would also reach without asking. Other profiles are unchanged.
+  - `akan code` prints at start that the `local` profile is not a sandbox.
+  - A one-shot `akan code "<prompt>"` no longer offers approvals or questions, since nobody answers them during the run. `AKAN_CODE_CAN_PROMPT=1` restores them.
+  - MCP sign-in tokens in `~/.akan/code/mcpAuth.json` are bound to the server's origin instead of its name, so a server declared under a known name at another url gets no token. Tokens an older version stored by name move to the origin they were minted for; one whose origin cannot be read is dropped and signs in again.
+  - This repo's own `.akan/code/mcp.json` servers and `.akan/code/extensions/` start only after the user approves them once at a terminal. The approval is kept in `~/.akan/code/trust.json` (mode 0600) and asked again when that content changes. An extensions folder past 10,000 files or 64 MiB, or with a link that leads out of it, is not read through and its approval is not kept, so it is asked about at every start. With nobody to ask they are not started, and the start notice says why. `akan code --trust-workspace` (`-T`) starts them for one run without asking. Servers in `~/.akan/code/mcp.json`, where `/mcp add` writes, need no approval; `/mcp add --local` writes this repo's file and keeps the approval it had, so a server added while that file waits for approval waits with it.
+  - `akan code --rpc-listen tcp:…` asks each connection to open with `{"auth":"<token>"}` on its first line and answers `{"type":"reply","id":"auth","ok":true}`. The token is generated at start and written to `~/.akan/code/rpc/<port>.token` (mode 0600), or read from the file `AKAN_CODE_RPC_TOKEN_FILE` names. A connection whose first byte is not `{`, or that does not authenticate within five seconds, is closed, and it never displaces the client already attached. `--no-rpc-token` serves without a token. A non-loopback bind is refused unless `--rpc-bind-any` is given. A `unix:` socket is created with mode 0600 and asks for no token, though a client that sends one is answered. Without a token, under `--no-rpc-token` or on a `unix:` socket, a connection whose first byte is not `{`, or that sends nothing within five seconds, is still closed.
+  - `AKAN_CODE_HOME`, `AKAN_CODE_CAN_PROMPT`, `AKAN_CODE_PROXY_*` and `AKAN_CODE_RPC_TOKEN_FILE` are ignored, with a start warning, when a dotenv file in the working directory (`.env`, `.env.local`, `.env.<mode>`, `.env.<mode>.local`) names them, because Bun loads those files before the CLI runs. Export them in the shell instead. `~/.akan` and `~/.akan/code` are created with mode 0700, and an existing `~/.akan/code` the user owns with a looser mode is tightened.
+
+- e3de9ef: Native and desktop builds now ship tighter defaults for page content, external links, temporary files and installed updates.
+
+  - **A content security policy by default.** An Akan app's native build puts a Content-Security-Policy in its `index.html`: scripts from `'self'` only (inline ones by hash), connections to `'self'` and any `https:` or `wss:` origin, `https:` images, media, fonts, stylesheets and frames, inline styles, and the plain-`http:` origins the build knows of (an `http:` `AKAN_PUBLIC_SERVER_URL`, `http://localhost:*` in local mode, the carried server's loopback port). The policy also sets `form-action 'self'`, `base-uri 'self'` and `object-src 'none'`, so a form that posts to another origin (an outside payment page, say) no longer submits, and `<object>`/`<embed>` content does not load; add the origin in a map (`{ "form-action": ["https://pay.example.com"] }`). A directive map in `native.csp` adds sources to that policy (`{ "script-src": ["https://cdn.example.com"] }`), a string replaces it, and `native.csp: false` ships no policy, as before; `native.csp: ""` is a build error. In a map, directive names ignore case, a `default-src` entry is added to every fetch directive of the policy but `object-src`, and a directive the policy lacks starts from the one CSP falls back to (`script-src-elem` from `script-src`, `manifest-src` from `default-src`). akan-native hashes inline scripts and styles into `script-src-elem` and `style-src-elem` too when a policy has them.
+  - **External links open `https:`, `mailto:` and `tel:` by default.** `opener.openUrl`, and the links and `window.open` calls the iOS, Android and desktop shells hand to the system, open only URLs that the app's `opener` permissions allow: plain `http:` links are not opened unless the app lists them, and an akan-native app whose `capabilities` grant no `opener` hands no link to the system. `native.openUrls` names the URL patterns; `native.openUrls: ["*"]` restores the previous scope. When the app refuses a link this way, `Link` and the router no longer retry it with `window.open`.
+  - **Private temporary folders on Linux.** `file-picker` copies, the `filesystem` plugin's `temp` folder and `external-view` captures live under `$XDG_CACHE_HOME/<appId>/tmp` (`~/.cache/<appId>/tmp` when unset), in folders only the user can open, instead of `/tmp/<appId>`. Unlike `/tmp`, nothing empties it at a restart: `file-picker` and `external-view` empty their own folders at launch, and a file an app writes to `temp` stays until the app removes it. macOS and Windows keep their per-user temporary folder. Set `XDG_CACHE_HOME` to move it.
+  - **single-instance on Linux without `XDG_RUNTIME_DIR`.** The socket and lock move into a per-user `akan-native-<uid>` folder that only the user can open, and an existing folder another user owns or others can read is not used. A private `XDG_RUNTIME_DIR` is used as before.
+  - **A downloaded desktop release is checked again before it is installed.** `updates.apply()` repeats the code-signature check (macOS) and the signer check (Windows) on the staged bundle. The install at quit installs a bundle only once that check passed in this run, outside the time the quit hooks share: as the release was downloaded or the app started, and again when a quit is asked for (Cmd+Q, the last window closed, a logout), which waits up to 10 s for it. A bundle that no longer passes is removed and has to be downloaded again; one whose check has not finished stays for the next quit.
+  - **`updates.windowsSigners`** (new, Windows): certificate thumbprints a release's executable must be signed by. Unset keeps the existing check that a release is signed by the same certificate as the running app.
+  - **`updates.expiresIn`** (new): `akan publish-update` signs an `expiresAt` that many seconds ahead (at least 3600) into the release manifest, and desktop, iOS and Android apps refuse a manifest past its `expiresAt`. Unset publishes no expiry, and a manifest without one is accepted as before.
+  - **`desktop.screenCapture: "auto"` on Windows denies camera and microphone requests**, which the setting would otherwise grant without asking. `"picker"`, the default, keeps the usual prompts.
+  - **`native.csp`, `native.openUrls`, `updates.windowsSigners` and `updates.expiresIn` are typed in `akan.config.ts`**, and `csp` and `openUrls` given in the `native` section reach the native build, as a target's own did.
+  - **A release build with `devtools` on prints a warning**, since the web inspector then reaches every plugin the page can call.
+  - **Paths with a `.` or `..` segment are answered by the app shell** on every platform, literal or percent-encoded, and a navigation to one is not loaded as a page, as `/__akan_native/*` paths already were.
+  - **A public env value holding a private key is refused** when the native build records its `AKAN_PUBLIC_*` values, as names with `SECRET`, `TOKEN`, `PASSWORD`, `PRIVATE` or `CREDENTIAL` already were.
+  - **akan-native only warns about `'unsafe-inline'` in `script-src`.** Inline styles under `style-src 'unsafe-inline'` no longer produce a warning; inline scripts are still left unhashed when `script-src` allows them.
+
+- 5e08722: A coding agent now finds the imports and signatures a first app needs in its skills, instead of reading the akanjs sources.
+
+  - **The `akan-service` and `akan-page` recipes** start each file with its import lines, and the `akan-service` rules say what `serverMode: "batch"` does: the module, endpoints included, mounts only in a `batch` or `all` process, so a page-facing service leaves it off.
+  - **A new `akanApi` guideline** lists every import path and the exact signatures of the route stages, `router`, `Link`, `serve`, `adapt`, the endpoint builders, `SignalOption`, `serviceDictionary`, and the keys of `akan.config.ts` with the `web` and `i18n` shapes. It is generated from the akanjs types of the same release, and a test fails when the two drift apart. `akan agent install` ships it as a reference of both skills, and `get_guideline` / `akan guideline show akanApi` print it.
+  - **`ServiceOptions.serverMode`** carries a doc comment, so an editor shows the same explanation on hover.
+
+- 58f1c64: A route's client code no longer carries the UI of every module in the app and in each lib its store merges.
+
+  - **Bootstrap.** Each route's `"use client"` entry, every generated root layout and the SSR dev registry start with `import "@apps/<app>/lib/useClient"` and `import "@apps/<app>/lib/st"`, which load the client runtime and the store. They used to import `@apps/<app>/client` bare, and that bundled the whole barrel.
+  - **Narrowed barrel imports.** A named import from an app or lib `client` barrel is still narrowed to the files that define the names. This includes `import { st } from "@apps/<app>/client"` in a component and the generated `import { RootStore as <lib> } from "@libs/<lib>/client"` in `lib/st.ts`.
+    - What the rewrite keeps of the barrel is now the files that define its `usePage` and `st`, normally `lib/useClient` and `lib/st`. It used to keep a bare import of the barrel itself, which put every module's UI of the app and of each merged lib on every route.
+    - A barrel that defines neither name keeps its bare import, as before.
+  - **Namespace re-exports.** A name the barrel re-exports as a namespace (`export * as cnst`, `export * as store`) is now narrowed too. `import { cnst } from "@libs/<lib>/client"` becomes `import * as cnst from "@libs/<lib>/lib/cnst"`, where it used to load the whole barrel.
+  - **Discovery and Tailwind.** Client entry discovery and Tailwind's candidate scan follow the same imports. A lib `"use client"` component is no longer a client entry of every route, and a module UI file that no route imports is no longer scanned.
+  - **Size.** Production build of `apps/minimal`:
+    - A route that renders only `Link` ships 53.1K raw / 17.2K br of route code, down from 226.6K / 67.1K.
+    - With `libs/shared` merged into the store, the `Link` route ships 147.0K / 37.9K, down from 645.6K / 172.8K. A route rendering shared's `Field` ships 416.0K / 113.9K, down from 645.6K / 172.5K. A route rendering shared's `Banner.Zone` ships 454.3K / 123.2K, down from 658.9K / 175.7K.
+    - A route still carries whatever its UI imports. On minimal, whose only module is `memo`, the `Memo.Zone` route stays at 243.8K / 72K.
+  - **Evaluation order.** A module UI file now runs only on the pages that import it, and only when an import reaches it. It used to run up front, in barrel order, as soon as anything imported the barrel.
+    - A UI file whose top level registers something or writes a global must be imported where that side effect is needed.
+    - A UI file that reads another UI file's export at its top level, through an import cycle, can now find it uninitialised and throw a TDZ error. Move that read into the component.
+    - Generated module `index.ts` files only collect namespaces, so they are unaffected.
+
+- bd4d45a: `akan verify` now fixes or explains three lint failures that were costly to resolve by hand.
+
+  - **A daisyUI component class your own CSS defines is no longer refused.**
+    - `no-daisyui-legacy-class` reports a component name such as `stat-value` or `card-body` as a warning, since the rule cannot read the app's CSS. `akan verify` drops the warning when a stylesheet in the app or a lib defines that class, as a selector or an `@utility`.
+    - A dropped daisyUI colour slot such as `bg-base-100` is still an error. In a string that carries both, the colour-slot error is reported first, so the warning cannot hide it.
+  - **`akan verify` renames `#private` methods in `*.{constant,document,service,store}.ts`.**
+    - `#name()` becomes `private name()`, and each call or other reference to it is renamed to match.
+    - A method is left to the diagnostic when its class already has a member with that name, or when a `#name in obj` check reads it.
+    - `#private` fields are not touched. A call on one, such as `this.#cache.get(key)`, is no longer reported as a private method call.
+    - The rule no longer suggests an underscore prefix: a service runs `_preCreate`-style names as lifecycle hooks.
+    - The rule's own rewrite is removed. Under `--unsafe` it renamed a `#field` where it was called but not where it was declared.
+  - **A raw `Error` in an `srvkit/` adapter names its fix.** `akan verify` prints the `Err` import path from that file, and where the key goes: the app's or lib's own service dictionary, `lib/_<name>/<name>.dictionary.ts`, as `<name>.error.<key>`.
+
+- adcdf3b: `akan workflow plan` and the `plan_workflow` MCP tool refuse a module the target app or library lacks, for every workflow that writes into an existing module (`add-field`, `add-enum-field`, `add-mutation`, `add-slice`, `create-ui`, `rename-key`). The `workflow-module-missing` error names the module, lists the modules the target has, and points at the module whose name differs only in case or by a leading `_`, at a scalar of that name, or at the app or library that holds it; only when none exists does it point at `create-module`. Before, the plan passed and its dry run reported `passed`. `add-mutation` used to plan a missing module with a warning so that a `create-module` plan could precede it; it now refuses too, so plan it after applying `create-module`. Every workflow now refuses an unknown `app` at plan time, listing the workspace's apps and libraries. `apply` and `--dry-run` check the target again before anything else, so a plan written earlier for a module that is gone fails instead of passing. `plan_workflow` now inspects the MCP server's workspace rather than the process directory.
+- Updated dependencies [bc792ab]
+- Updated dependencies [61fbd7d]
+- Updated dependencies [b3f85fa]
+- Updated dependencies [a707354]
+- Updated dependencies [0351ad4]
+- Updated dependencies [ba417c6]
+- Updated dependencies [bb40785]
+- Updated dependencies [d2bd9b7]
+- Updated dependencies [b391491]
+- Updated dependencies [2d357d6]
+- Updated dependencies [039ad3b]
+- Updated dependencies [69ed07e]
+- Updated dependencies [29ef72f]
+- Updated dependencies [7c85c42]
+- Updated dependencies [ddd3d96]
+- Updated dependencies [3f231a7]
+- Updated dependencies [96f9ff6]
+- Updated dependencies [1ebc57a]
+- Updated dependencies [c3b5b3c]
+- Updated dependencies [6d5b544]
+- Updated dependencies [958f175]
+- Updated dependencies [9f30e93]
+- Updated dependencies [d9eaacc]
+- Updated dependencies [d9eaacc]
+- Updated dependencies [c334caf]
+- Updated dependencies [e143263]
+- Updated dependencies [e4f7876]
+- Updated dependencies [cb0fd5b]
+- Updated dependencies [c48d780]
+- Updated dependencies [3537448]
+- Updated dependencies [c882491]
+- Updated dependencies [f3def22]
+- Updated dependencies [8424863]
+- Updated dependencies [bf28968]
+- Updated dependencies [9b5bcee]
+- Updated dependencies [4561152]
+- Updated dependencies [73e833b]
+- Updated dependencies [b24fef3]
+- Updated dependencies [5cd1fc3]
+- Updated dependencies [f47cc82]
+- Updated dependencies [1f93507]
+- Updated dependencies [5d3cb3e]
+- Updated dependencies [9a9e1fa]
+- Updated dependencies [3537448]
+- Updated dependencies [6c3a303]
+- Updated dependencies [27440aa]
+- Updated dependencies [e3de9ef]
+- Updated dependencies [e3de9ef]
+- Updated dependencies [e3de9ef]
+- Updated dependencies [e3de9ef]
+- Updated dependencies [e3de9ef]
+- Updated dependencies [e3de9ef]
+- Updated dependencies [e3de9ef]
+- Updated dependencies [99fda20]
+- Updated dependencies [5e08722]
+- Updated dependencies [df32c46]
+- Updated dependencies [5f809e8]
+- Updated dependencies [206bb69]
+- Updated dependencies [6291fec]
+- Updated dependencies [0c480c6]
+- Updated dependencies [d9eaacc]
+  - akanjs@3.2.0
+  - @akanjs/language@3.2.0
+
 ## 3.1.1
 
 ### Patch Changes

package/abstractDoc.ts

@@ -14,7 +14,7 @@ export class AbstractDoc {
     return filePath.endsWith(AbstractDoc.suffix);
   }
   static lineCountOf(content: string) {
-    return content.split(/\r?\n/).length;
+    return content.split(/\r?\n/).length - (content.endsWith("\n") ? 1 : 0);
   }
   static kindOf(filePath: string): AbstractKind {
     const [root, folder, ...rest] = filePath.split("/");

package/agentAssets.ts

@@ -31,7 +31,7 @@ export class AgentAssets {
     "akan-scaffold": ["workspaceRecipes"],
     "akan-module": ["moduleOverview", "modelConstant", "modelDictionary", "fieldRule"],
     "akan-scalar": ["scalarModule", "scalarConstant", "scalarDictionary"],
-    "akan-service": ["modelService", "modelSignal", "modelDocument"],
+    "akan-service": ["modelService", "modelSignal", "modelDocument", "akanApi"],
     "akan-store": ["modelStore"],
     "akan-ui": [
       "ssrRule",
@@ -48,7 +48,7 @@ export class AgentAssets {
     "akan-err": [],
     "akan-deps": [],
     "akan-debug": [],
-    "akan-page": ["pageRule"],
+    "akan-page": ["pageRule", "akanApi"],
     "akan-query": ["queryRule"],
     "akan-transport": ["transportRule"],
     "akan-runtime": ["runtimeRule"],

package/akanConfig/akanConfig.ts

@@ -638,10 +638,10 @@ export class AkanAppConfig implements AppConfigResult {
       ...(this.web.csr ? {} : { AKAN_CSR: "false" }),
     };
   }
-  //? An image runs where the build cannot see, and AKAN_PUBLIC_ENV=local serves the dev routes to every caller there.
+  //? An image runs where the build cannot see, and AKAN_PUBLIC_ENV=local turns off its rate limits and boot checks there.
   static readonly localImageGuard = [
     "ARG AKAN_ALLOW_LOCAL_IMAGE",
-    `RUN if [ "$AKAN_ALLOW_LOCAL_IMAGE" != "1" ]; then echo "This build ran with AKAN_PUBLIC_ENV=local, which serves the dev routes to every caller. Build with the environment it deploys to, or pass --build-arg AKAN_ALLOW_LOCAL_IMAGE=1." >&2; exit 1; fi`,
+    `RUN if [ "$AKAN_ALLOW_LOCAL_IMAGE" != "1" ]; then echo "This build ran with AKAN_PUBLIC_ENV=local, so the server runs without endpoint rate limits and on local defaults for Redis and the database mode. Build for the environment it deploys to with akan build --env, or pass --build-arg AKAN_ALLOW_LOCAL_IMAGE=1." >&2; exit 1; fi`,
   ].join("\n");
   dockerfileFor(environment: string, { lockfile = true }: { lockfile?: boolean } = {}): string {
     return this.#makeDockerfile(environment, lockfile);

package/akanMcpContract.ts

@@ -324,7 +324,7 @@ export const readonlyMcpTools: McpToolDefinition[] = [
   {
     name: "get_graph",
     description:
-      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with guards, the service methods and queries each calls, the store actions that fetch them, and the components and pages that use them. Every node and edge carries its source location. Pass app and/or module to scope a large workspace. Pass since (a git revision such as main, or HEAD for uncommitted work) for the Change Map instead: what changed since HEAD forked from it, working tree included, with each node, field and edge marked added, removed or changed, the unchanged neighbours they call or are called by, and the changed files no node covers, each marked the same way.",
+      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with the guards they name (each guard keyed by the app or lib that declares it, with its scope and the comment that says what it checks), the service methods and queries each calls, the store actions that fetch them, and the components and routes that use them. A module's jobs (internal: interval, cron, timeout, initialize, destroy, process) read their schedule and server or operation modes and call service methods like endpoints do; each adaptor a service plugs (an adapt() class, or an akanjs role) is a node, a method that calls it links to it, and an adaptor links to the adaptors it plugs itself. Each page/ file is a route (its URL pattern after the locale) or a layout, layouts wrap what they contain, and a route or layout that runs .guard() reads `guard` and links each function its guard calls; a layout's guard gates every route it wraps. A graph too large to answer unscoped drops first the routes and layouts that neither changed nor use a change; app or module brings them back. Every node and edge carries its source location. Pass app and/or module to scope a large workspace. Pass since (a git revision such as main, or HEAD for uncommitted work) for the Change Map instead: what changed since HEAD forked from it, working tree included, with each node, field and edge marked added, removed or changed, the unchanged neighbours they call or are called by, and the changed files no node covers, each marked the same way.",
     inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty, since: stringProperty } },
   },
   {

package/apiReference.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { AgentAssets } from "./agentAssets";
+import { ApiReference } from "./apiReference";
+
+const akanjsDir = path.resolve(import.meta.dir, "../../akanjs");
+const target = ApiReference.target(path.resolve(import.meta.dir, "../cli"));
+
+describe("ApiReference", () => {
+  const rendered = ApiReference.render(akanjsDir);
+
+  test("the committed guideline matches the akanjs sources; regenerate with bun pkgs/@akanjs/devkit/apiReference.ts", async () => {
+    expect(await Bun.file(target).text()).toBe(rendered);
+  });
+
+  test("fits one skill reference part", () => {
+    expect(AgentAssets.split(rendered)).toHaveLength(1);
+    expect(rendered.length).toBeLessThanOrEqual(AgentAssets.referenceLimit);
+  });
+
+  test("prints builder parameters, the import block and documented options", () => {
+    expect(rendered).toContain('import { adapt, serve } from "akanjs/service";');
+    expect(rendered).toContain('import { layout, page, rootLayout, router } from "akanjs/client";');
+    expect(rendered).toMatch(/^query<.+>\(returnRef: Returns, signalOption\?: SignalOption<Returns, Nullable>\)$/m);
+    expect(rendered).toMatch(/^\.param<.+>\(name: .+, type: Type, option\?: RouteArgOption\)$/m);
+    expect(rendered).toMatch(/^\.render\(render: \(args: RouteBaseArgs & LayoutExtra\) => .+\)$/m);
+    expect(rendered).toMatch(/children: ReactNode/);
+    expect(rendered).toMatch(/^\/\*\* .+ \*\/\nserverMode\?: "batch" \| "federation";$/m);
+  });
+
+  test("lists the keys of akan.config.ts, so the web and i18n shapes have a field to belong to", () => {
+    const appConfig = rendered.slice(rendered.indexOf("### `AppConfigInput`"));
+    expect(appConfig).toMatch(/^web\?: AkanWebOption;$/m);
+    expect(appConfig).toMatch(/^i18n\?: DeepPartial<AkanI18nConfig>;$/m);
+    expect(appConfig.indexOf("### `AkanWebOption`")).toBeGreaterThan(appConfig.indexOf("web?: AkanWebOption;"));
+  });
+});