@akanjs/cli 3.0.0-beta.3 → 3.0.0-beta.30

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -1,4 +1,4 @@
-# Runtime Rule — Serving, Processes, Logging, Image, Assets
+# Runtime Rule — Serving, Processes, Logging, Image, Native Apps, Desktop Server, Assets
 
 How an Akan app is built, what it serves, how many processes it runs, where its logs go, and what ends up in
 its image. Everything here is declared in `akan.config.ts` or narrowed by an env at boot; none of it is reached
@@ -11,14 +11,14 @@ on; the other two are declared in `akan.config.ts` as **`web: true | false | { c
 narrowed again per deployment.
 
 ```ts
-const config: AppConfig = { web: { csr: false } }; // web without the mobile bundle
+const config: AppConfig = { web: { csr: false } }; // web without the CSR bundle the native apps ship
 const config: AppConfig = { web: false }; // api only
 ```
 
 - **`web: { csr: false }`** drops the CSR build phase and the `/__csr` + `?csr=true` routes. The CSR bundle is
-  what the Capacitor mobile build ships, so a web-only deployment never needs it — and an app that declares a
-  `mobile` section is refused, because `akan build-ios` copies `dist/apps/<app>/csr/<target>.html` into the
-  native project.
+  what the native apps ship, so a web-only deployment never needs it — and an app that declares a `native` section
+  is refused, because every native build copies `dist/apps/<app>/csr/<target>.html` into the target's web root,
+  `.akan/native/<target>/web`.
 - **`web: false`** is an API-only build: no base artifact, no pages or client bundles, no RSC worker
   entrypoint, and no `public/` in the image (the web router's catch-all is its only reader). Nothing under
   `page/` is served, including routes a lib contributed through `syncPageLibs`.
@@ -68,7 +68,7 @@ const config: AppConfig = { api: { prefix: "/backend", websocketPrefix: "/socket
   origin when the module graph initializes, before any component renders, so a React prop — a `System.Provider`
   value, anything out of `implicitRootLayout` — is always too late. The value rides the SSR classic bootstrap
   script instead, the one thing guaranteed to run ahead of every module script, and is omitted when it matches
-  what the bundle already assumes. `akan.config.ts` is what a Capacitor bundle or a statically served CSR shell
+  what the bundle already assumes. `akan.config.ts` is what a native app bundle or a statically served CSR shell
   follows, because neither is rendered by a server that could tell it otherwise.
 - **A prefix is a path segment.** A blank value or a bare `/` is refused: `/` would be mounted ahead of the SSR
   catch-all and swallow every page route. A prefix whose first segment is a declared basePath is refused at
@@ -184,6 +184,268 @@ const config: AppConfig = { docker: "FROM oven/bun:1-slim\n…" }; // verbatim,
 - `AkanAppConfig.docker` is the resolved declaration; `AkanAppConfig.dockerfile` is the text `akan build` writes
   to `dist/apps/<app>/Dockerfile`.
 
+## Native Apps — The `native` Section
+
+An app's iOS, Android and desktop (macOS, Windows, Linux) apps are the `native` section of its `akan.config.ts`.
+Each ships the CSR bundle on the native runtime, so one set of pages serves the web and every app.
+
+```ts
+const config: AppConfig = {
+  native: {
+    appName: "Board",
+    appId: "com.example.board", // or one per platform: { default, ios, android, macos, windows, linux }
+    version: "1.2.0",
+    buildNum: 12,
+    indexPath: "/explore", // the first page, and where a deep link's stack and a back with no history land
+    permissions: ["camera", "push"],
+    plugins: ["file-picker", "keep-awake"],
+    deepLinks: { schemes: ["board"], domains: ["board.example.com"] },
+    ios: { teamId: "ABCDE12345" }, // universal links for deepLinks.domains
+    android: { googleServices: "secrets/google-services.json", sha256CertFingerprints: ["…"] }, // FCM, app links
+    desktop: { server: true },
+  },
+};
+```
+
+- **Without `targets` the app has one target, `default`** — the usual case, with every setting in the section
+  itself; `native: { desktop: { server: true } }` alone is a whole desktop app that carries its server. Defaults:
+  the app's folder name for `appName` and `fileName`, an id made from the repository's and the app's names for
+  `appId`, `0.0.1` and `1`.
+- **A target is another app made from the section.** It has the section's shape minus `targets` and overrides it
+  field by field: plain objects merge key by key — `ios`, `android`, `desktop`, `deepLinks`, `updates` and the
+  objects inside them — and every other value replaces the section's, a list included, so a target's `plugins` or
+  `permissions` is its whole list. An `icon` or `splash` object is one value. Once `targets` is declared, only the
+  targets it names are built:
+
+  ```ts
+  native: {
+    appId: "com.example.board",
+    plugins: ["file-picker"],
+    targets: {
+      board: {},
+      lobby: { appId: "com.example.lobby", plugins: ["file-picker", "keep-awake"], desktop: { recovery: "reload" } },
+    },
+  },
+  ```
+
+- **`basePath` is the client a target opens.** An app with no basePaths leaves it out. Without `targets`, the one
+  target opens the basePath named like the app when there is one; in an app with basePaths, a target that names
+  none is a template, and `--target <basePath>` builds that client from it.
+- Every native command takes `--target <name>`. `build-*`, `release-*`, `update-keygen` and `publish-update` also
+  take `all`; `start-*` and `pack-update` handle one target at a time.
+- **Everything a build makes is under `apps/<app>/.akan/native/<target>/`**: `build/<platform>` (`build-ios`,
+  `build-android`, `build-desktop`), `dev/<platform>` (the dev builds `start-*` run), `updates` (what
+  `publish-update` signs and `pack-update` packs), `web` (the bundle the app loads) and `bin`. `akan start` leaves
+  the folder alone.
+- **`start-ios` / `start-android` / `start-desktop` run a dev build that loads its pages from `akan start`.** It has
+  to be running — except for a desktop app that carries its server, which starts it when none of this checkout
+  answers. `--release true` runs a release build of the app's own bundle instead.
+- **A desktop app builds only for the computer that builds it** — a `.app` on macOS, signed ad hoc or with the
+  development identity, and an unsigned folder on Windows and Linux. `build-desktop --installer true` adds a
+  per-user NSIS setup on Windows (`/S` installs silently). Distribution signing and notarization are not akan
+  commands yet.
+- **`updates: { url, publicKey }` lets an installed app update itself** — the whole app on a desktop, the web
+  bundle on a phone. `akan update-keygen <app>` makes the signing key once
+  (`~/.akan/native/keys/<app id>.update.key`, or the path `AKAN_NATIVE_UPDATE_KEY` names) and prints the
+  `publicKey`. `akan publish-update <app>` builds and signs a release into `updates/`: upload that folder to `url`,
+  the manifests last. `akan pack-update` writes an unsigned phone bundle for whoever holds the key to sign. The
+  channel is the backend env the binary was built for unless `channel` names one, and a release that does not
+  come up is rolled back to the one before.
+- **An unattended screen** — signage, a kiosk — takes `desktop.recovery: "reload"` (a crashed page loads again,
+  and the app relaunches when the webview ends), `desktop.window: { fullscreen, skipTaskbar }`,
+  `desktop.screenCapture: "auto"` (Windows answers `getDisplayMedia()` with the first screen, no picker) and
+  `android.autoplay` (media plays with sound without a tap).
+
+## A Desktop App's Server — `bin` And `trustedDependencies`
+
+A desktop app whose `native` section, or target, declares `desktop: { server: true }` carries the app's server:
+`akan build-desktop`, `start-desktop --release` and `publish-update` put the backend `akan build` made into the
+app — everything the backend build wrote (the `.js`, `akan.build.json`, `private/`, a bundled package's `.node`,
+`.wasm` or file asset) but the Dockerfile, the RSC worker, the console, `csr/` and `public/` — and install its
+packages first with `bun install --production --prefer-offline`, before `akan build` runs. `start-desktop` without
+`--release` starts `akan start` beside the app when no dev server of this checkout answers. The setting is the
+app's backend, so it does not change under an installed app: an update whose release carries a server when the app
+has none, or none when it has one, is refused, and switching means a reinstall.
+A desktop app builds only for the computer it is built on, so every native addon's prebuild matches the one it runs
+on. It runs as an API-only edge server on SQLite, on a loopback port the launcher picks — the last session's when
+it is free, which is not a guarantee, so a provider that needs an exact redirect URI signs in through a cloud
+server's adapter. It refuses a `Host` other than its own, but any program on the computer can still call that port:
+guard its endpoints as a network server's. It runs in one process, so a `main.ts` or an env asking for replicas (`replica`,
+`solo: false`, `AKAN_SOLO=false`, `AKAN_REPLICA`, `AKAN_COMMAND_TYPE=start`) does not boot in the app. Its data lives in the app's local data folder (`%LOCALAPPDATA%\<id>\server`
+on Windows, never Roaming; `server-debug` for a `--debug` build). It trusts the OS certificate store, and of the
+user's environment it takes a fixed set and nothing else: the system's own (`PATH`, `HOME`, the temp folder, `LANG`,
+`TZ`, Windows' folders and `ComSpec`), the desktop session a `bin` tool needs for the screen or the audio server
+(`DISPLAY`, `XAUTHORITY`, `WAYLAND_DISPLAY`, the session bus, `PULSE_*`, `XDG_*`), and the proxy and CA variables
+(`HTTP(S)_PROXY`, `NO_PROXY`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`).
+
+**Everything it carries is on the user's computer, readable.** That is `private/` as it is — each lib's too, under
+`private/libs/<lib>` — and the server env of the one environment the build is for (`--env`: `debug` for
+`build-desktop`, `local` for `start-desktop --release`, `main` for `publish-update`, unless named): the build keeps
+`env/env.server.<env>.ts` and swaps every other environment's file for exports that refuse to be read. The server env
+each lib exports as its defaults (the lib's `env.server.testing.ts`, spread into every environment by
+`env.server.type.ts`) ships as well. Keep a key in those files only if every user of the app may hold it; a secret the
+server needs belongs to a cloud server its adapter calls. There is no `public/`: a file the server reads at runtime
+goes in `private/` and is read from `AKAN_APP_DIR` (the folder `server.js` sits in), never from `process.cwd()`, which
+is the app's data folder.
+
+**Nothing from `docker` reaches it.** `preRuns`, `postRuns` and a whole Dockerfile install into a Linux image the
+desktop app never runs in, and the build warns when an app has them and carries no `bin`. What the server needs
+from them comes one of two ways:
+
+```ts
+const config: AppConfig = {
+  trustedDependencies: ["rclnodejs"],
+  bin: {
+    ffmpeg: {
+      "darwin-arm64": {
+        url: "https://files.example.com/ffmpeg-7.1-lgpl-darwin-arm64.zip",
+        sha256: "…",
+        file: "ffmpeg-7.1/bin/ffmpeg",
+      },
+      "win32-x64": { url: "https://files.example.com/ffmpeg-7.1-lgpl-win64.zip", sha256: "…", file: "bin/ffmpeg.exe" },
+      "linux-x64": { path: "tools/linux-x64/ffmpeg" },
+    },
+  },
+};
+```
+
+- **An executable the desktop app spawns goes in `bin`** — its server's code or its native plugins, whether or not
+  it carries a server — keyed by the name the code spawns and then by
+  `${process.platform}-${process.arch}` (`darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64`,
+  `win32-x64`). A source is `{ url, sha256, file? }` — downloaded when the app is built, refused unless it hashes
+  to `sha256` (so plain http is as safe as https), kept in `apps/<app>/.akan/cache/bin/<sha256>` — or
+  `{ path, file? }`, relative to the `akan.config.ts` that declares it. `file` is the executable inside an archive
+  (`.zip`, `.tar.gz`, `.tgz`, `.tar.xz`, `.tar.bz2`, `.tar`), unpacked with the OS's own `tar` (`unzip` for a zip
+  on Linux).
+- Only the building computer's platform is fetched, and an entry without it fails the build instead of the user's
+  call. `build-desktop` and `start-desktop` copy the file into the app's `bin/` (keeping `.exe` on Windows), sign it
+  with the app on macOS, and put that folder first on the app's PATH. The server's `spawn("ffmpeg")` needs no change
+  and finds the carried file even in an app launched from the Finder, whose PATH is only
+  `/usr/bin:/bin:/usr/sbin:/sbin`. A native plugin finds the folder in `ctx.binDir`: Bun's own `spawn` and `which`
+  without `env` read the environment the app started with, so a plugin passes `env: process.env` to run one by name.
+  The server passes it too when it spawns a carried `bun build --compile` executable: the shell starts the server as
+  Bun with `BUN_BE_BUN=1`, which akanjs takes out of `process.env` at boot, and a child spawned without `env` still
+  inherits it and runs as Bun's own CLI instead of the tool.
+- **One file per entry, so carry a static build.** A build that loads its own shared libraries — a `-shared`
+  archive, or Homebrew's ffmpeg with its 55 dylibs — runs on the computer that built it and nowhere else.
+- **A lib's `bin` reaches only the apps that depend on it**, unlike its `docker` steps; the app's own entry of the
+  same name wins, and two libs that declare one name differently fail the build.
+- **The image does not read `bin`.** Keep installing through `docker.preRuns` there.
+- **A package that builds itself at install goes in `trustedDependencies`.** `bun install --production` runs no
+  dependency's install or postinstall script unless the package is trusted, so an addon with no prebuild arrives
+  unbuilt and fails at its first call. The list lands in the built `package.json`, so it applies to the image and to
+  the desktop server alike, and a lib's list reaches every app, like its `externalLibs`.
+
+**Carry an LGPL ffmpeg.** A build configured with `--enable-nonfree` may not be redistributed at all — the macOS
+binary npm's `ffmpeg-static` downloads is one — and a `--enable-gpl` build obliges you to offer its source. An LGPL
+build has no `libx264`, so encode H.264 through the OS's encoder: `h264_videotoolbox` on macOS, `h264_mf` on
+Windows, VAAPI or NVENC on Linux. Codec patents are a separate question to settle before shipping.
+
+**A server bound to its machine stays a service.** A server that needs a whole environment — ROS, system services,
+root to change the network or the clock — runs as a service on that machine (the image), and the desktop app's
+target leaves `desktop.server` off, pinned to it with `AKAN_PUBLIC_SERVER_URL` at build time. A carried server runs
+as the signed-in user and stops with the app, and so does what it started. On macOS and Linux the server leads its
+own process group: quitting the app ends the group, and when the app was killed or crashed — even while the server
+was still starting — the server sees its parent gone and ends the group itself, SIGTERM first and SIGKILL a second
+later for whatever ignored it. On Windows the job object ends them all with the app. A process started `detached`
+leaves the group, or the job, and keeps running.
+
+**A file the user picks reaches the server as a grant, never as a copy or a path.** With `"file-picker"` in
+`native.plugins`, `filePicker.pickFiles({ forServer: true })` (also `pickDirectory` and `saveFile`,
+from `akanjs/client/native`) copies nothing, whatever the size: its FileRefs serve the originals for a preview, and
+each result carries a `grant`. The page hands the grant to an endpoint, and the server exchanges it:
+
+```ts
+const input = await NativeFile.resolve(grant, "read"); // "write" for a saveFile grant, "folder" for pickDirectory
+const clip = await NativeFile.resolveIn(folderGrant, "day1/a.mp4"); // refused if it climbs out of the folder
+```
+
+The carried server asks the shell that showed the dialog over its IPC channel, so it reaches what the user picked
+and nothing else, and no page ever holds a path. Behind a dev build `akan start` checks the grant's signature
+against a key in `~/.akan/native` instead, in `operationMode` local only; every other server refuses a grant.
+
+**Devices belong to the shell, not the server.** Displays and their changes (`screen`), windows placed on them
+(`window`), the system volume and mute (`volume`), global shortcuts (`global-shortcut`), keep-awake (`keep-awake`)
+and launch at login (`autostart`) are native runtime plugins, each added to `native.plugins`. Every builtin plugin's
+page API is
+`akanjs/client/native/<id>` (`akanjs/client/native/window`, `…/screen`, `…/global-shortcut`), imported in a `webkit/`
+hook; `volume` and `filePicker` also come from `akanjs/client/native` itself. A capability the shell
+lacks is added there: an app's own plugin runs as Bun code in the plugin host and cannot add a native shell op.
+
+## Database Modes — `database` In `akan.config.ts`
+
+| mode | database | cache · queue · pubsub | runs as |
+|---|---|---|---|
+| `single` | SQLite file | SQLite files (Solid) | one container |
+| `multiple` | one SQLite file (WAL) on a host volume every container on that host opens | Redis | containers on one host |
+| `cluster` | Postgres | Redis | pods on several servers |
+
+- **`database: { modes: ["single", "cluster"] }` is what the build can run in**; the first is what `akan start`
+  runs. `akan build` carries the drivers of every declared mode (`multiple` → `bullmq`, `ioredis`; `cluster` adds
+  `postgres`).
+- **A deployment names its mode with `AKAN_DATABASE_MODE`**, and only a declared one. With one declared mode it may
+  leave it out; with several it must name one — the fallback would be a SQLite file inside each pod. `akan start`,
+  `build`, `script` and `console` resolve it the same way from the shell. One image can serve an edge site in
+  `single` and a cloud cluster in `cluster`: declare both.
+- **Where the data lives is the deployment's env, ahead of `env.server.ts`**: `SQLITE_DATABASE_PATH`,
+  `AKAN_SOLID_DB_PATH`, `POSTGRES_URL` (or `POSTGRES_HOST`/`PORT`/`DATABASE`/`USER`/`PASSWORD`),
+  `POSTGRES_INSIGHT_URL`, `LIBSQL_URL`. `REDIS_URI` is required outside local development. Pool size, SSL and
+  prepared statements ride the Postgres URL (`?max=20&ssl=require`, `prepare=false` behind PgBouncer).
+- **Uploads**: a deployed `multiple`/`cluster` app uses object storage, or a volume every instance mounts with
+  `AKAN_STORAGE_SHARED=true`.
+- **`runAdminSql` on Postgres reads as its own login role** holding base-column `SELECT` and nothing else:
+  `CREATE ROLE <name> LOGIN PASSWORD '…'` with no other role granted, `POSTGRES_INSIGHT_URL` logging in as it, and
+  `GRANT USAGE ON SCHEMA` from the DBA when the app does not own its schema. Every model table grants the role its
+  base columns at boot. Without it the console refuses on Postgres; `_doc` is never readable either way.
+- **`akan dbup`** starts what the workspace's apps declare (`--mode multiple` is Redis, `cluster` adds Postgres).
+  **`akan db-export <app>` / `akan db-import <app>`** move every model table as stored rows through NDJSON files
+  (`--dir`, default `local/transfer`) between whatever the shell's `AKAN_DATABASE_MODE` points at; a rerun
+  replaces rows, search is rebuilt after, and sessions, queued jobs and uploaded files do not move.
+- **`q.raw(sql)` is the dialect's own SQL** — `json_extract("_doc", '$.f')` on SQLite, `("_doc" #>> '{f}')` on
+  Postgres. An app that runs in both modes avoids it.
+
+## Operations — Snapshots, Restore And The `/_akan/ops` Channel
+
+`GET /_akan/app/info` answers `{ appName, repoName, environment, operationMode }` on every deployment — the same
+`AKAN_PUBLIC_*` values the client bundle already carries — so a control plane can check which app a host is
+serving without a key. Everything else is behind the ops channel.
+
+| surface | what it does |
+|---|---|
+| `bun main.js ops snapshot [--id] [--out] [--include-solid] [--json]` | `VACUUM INTO` a consistent copy, `integrity_check`, sha256, gzip, optional age encryption, `manifest.json` |
+| `bun main.js ops restore <manifest.json> [--identity <file>]` | offline only: verify, stage, keep the old file as `<db>.pre-restore-<ts>` (its `-wal`/`-shm` beside it), swap |
+| `GET /_akan/ops/info` | the public info plus `akanVersion`, `buildId`, `serverMode`, `databaseMode`, `solo`, `startedAt`, `replicaIdx` |
+| `POST /_akan/ops/snapshot` `{ id, includeSolid?, uploadUrls: { main, solid?, manifest } }` | 202; a child process snapshots, then PUTs each file and the manifest **last** |
+| `GET /_akan/ops/snapshot/:id` | `running` → `uploading` → `done` \| `failed`; kept in memory, so a restart answers 404 |
+
+- **The entry is the image's own `main.js`** — a production image carries no `akan` CLI. `AkanApp.start()` hands
+  `argv[2] === "ops"` to the command before it boots anything. It reads the container's env — the `AKAN_PUBLIC_*`
+  identity and the database paths — so run it with that env (`docker compose exec`), never a bare shell's.
+- **Restore refuses while an app answers `/_akan/app/health` on `PORT`** and names it by its `/_akan/app/info`;
+  `--force` is for a port some other app holds.
+- **The channel exists only when `AKAN_OPS_PUBLIC_KEY` is set** (Ed25519: PEM, JWK, base64 SPKI or raw 32 bytes).
+  The control plane signs a short EdDSA JWS — `aud`, `iat`, `exp` at most 300s after `iat`, a `jti` the process
+  refuses twice — and the host holds only the public half, so a machine someone carries off mints nothing.
+  `aud` is `<appName>/<environment>`, or `<appName>/<environment>/<AKAN_OPS_INSTANCE>` when that is set, and then
+  only that: a token minted for the app as a whole would replay across every host sharing the name. 30 calls a
+  minute per process; every refusal is the same 401. A malformed key leaves the app serving with the channel off.
+- **The app holds no storage credential.** It PUTs to the presigned URLs it was handed (`application/octet-stream`,
+  the manifest `application/json`), plain http only to loopback. The manifest landing is the commit marker.
+- **Snapshots cover the SQLite modes only.** `single` copies the main file and, with `includeSolid`, the Solid file;
+  `multiple` copies the main file; `cluster` is refused. Paths follow the adaptors' env precedence
+  (`SQLITE_DATABASE_PATH`, `AKAN_SOLID_DB_PATH`, `AKAN_SQLITE_DIR`); a solo process uses the path its adaptor
+  actually opened, so a gateway deployment that moved the file in `env.server.ts` names it in the env too.
+- **`AKAN_BACKUP_RECIPIENT=age1…[,age1…]` encrypts before upload** — age v1 X25519, so `age -d -i key.txt` opens
+  it. Restore takes `--identity` / `AKAN_BACKUP_IDENTITY_FILE`, or a file an operator already decrypted with
+  `age -d -o <name without .age>`.
+- **The host keeps the newest `AKAN_OPS_SNAPSHOT_KEEP` (default 2) snapshots** under `AKAN_OPS_SNAPSHOT_DIR`
+  (default `<db dir>/snapshots/<id>/`) — the copy an edge still has while its uplink or the bucket is down.
+- **`buildId` is `AKAN_BUILD_ID` when the deployment sets it**, else the git sha `akan build` wrote into
+  `akan.build.json` beside `main.js` (`-dirty` when the tree was).
+- **`operationMode` does not gate any of this** — the key does. `edge` means a production host outside the
+  cluster: the console refuses it like `cloud`, and `init` / `interval` / `cron` take `operationMode: ["edge"]` to
+  run only there. Everything else behaves as `cloud`; `local` is a developer machine.
+
 ## Shipped Assets — `assets` In `akan.config.ts`
 
 `akan build` copies the whole `public/` tree into `dist`, lib assets dereferenced, and that copy is the image.

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -129,8 +129,10 @@ eight queries threw; per-section boundaries put each rejection at its own bounda
 soft-redirect script, so `getSelf({ unauthorize: "/signin" })` stays in `_layout.tsx` or the page body — never
 inside a streamed section.
 
-**⑥ Use named `ReactNode` slots, not just `children`.** `Layout.Navbar` accepts `title`, `back`, `left`, `right`,
-and `children`, so a client shell composes server-rendered content in five places instead of absorbing it.
+**⑥ Use named `ReactNode` slots, not just `children`.** A client shell that takes one slot per region lets a
+server component supply each of them, instead of absorbing the whole subtree into the bundle. `Layout.Navbar`
+declares `title` / `left` / `right` alongside `back` and `children`, but its render body uses only `back` and
+`children` — copy the shape, not that component.
 
 **⑦ Let the server do the derived work.** Display and predicate logic belongs on `Light<Model>` (`isNew()`,
 `canWrite(user?)`, `formatTimes()`), and enum→class lookups belong in a module-scope `as const` map. Both sides call

package/guidelines/transportRule/transportRule.instruction.md

@@ -28,6 +28,57 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   neither again, and cleanup that must happen either way registers for both. From a `message` handler it belongs to
   the socket and runs at close. A handler that throws is logged and never blocks the rest of the teardown.
 
+## Request Deadlines
+
+- **`{ timeout: <ms> }` in an endpoint's signal option is the whole configuration surface**, and it reaches both
+  ends of the call. Server side, the `Timeout` middleware races the handler against it and answers
+  `base.error.gatewayTimeout` (504) once it is spent. Client side, `FetchSerializer` ships the value on the
+  serialized endpoint and `fetch.<endpoint>()` uses it as that request's `AbortSignal.timeout` budget, so the
+  browser does not abandon a call the server is still allowed to be working on.
+- **The middleware is registered by default and has no default of its own.** An endpoint that declares no
+  `timeout` is passed straight through — a default here would put a deadline on every endpoint in the app that
+  nobody asked for, which is why the middleware used to be opt-in and, being opt-in, made the declared value
+  dead. It clears its timer in a `finally`: the race's loser is a pending timer per call otherwise, and with a
+  five-minute budget that is a five-minute hold on the event loop for a call that answered in a millisecond.
+- **Without a declaration the client's own default applies — 30 seconds** (`DEFAULT_TIMEOUT_MS`,
+  `fetch/client/httpClient.ts`), and the server imposes nothing. Nothing else bounds a request: `Bun.serve` runs
+  with `idleTimeout: 0`, so a long call is only ever ended by one of these two.
+- **Precedence is caller, then endpoint, then client default.** `fetch.x(…, { timeout: 5_000 })` overrides what
+  the endpoint declared; `{ timeout: false }` waits as long as the runtime will. An app moves its own default
+  with `fetch.instance.setTimeout(ms)` — `lib/useClient.ts` is generated, so the `timeout` option on
+  `FetchClient.build` belongs to the template that writes it, not to app code.
+- **A file upload is never bounded**, on any of those paths: a large body on a slow uplink is a request that is
+  working, and the request body is the only thing the client can tell that from.
+- **The deadline answers the caller; it does not undo the call.** `Promise.race` cannot cancel `next()`, so a
+  handler that timed out keeps running and keeps writing. Reach for a `timeout` to bound what a *caller* waits
+  for, not to bound an effect — an operation that must not half-happen needs its own idempotency or compensation.
+- The failure is the same `base.error.gatewayTimeout` key whichever side gave up, so the user reads one sentence
+  in their own language either way. What differs is the status code — 504 from the server's middleware, 408 from
+  the client's own abort — and nothing downstream branches on that.
+
+## Cached Answers
+
+- **`{ cache: <ms> }` in an endpoint's signal option is the whole cache surface.** The lookup is a step of every
+  call and stands aside unless an endpoint declares one.
+- **Only a `query` that takes no internal argument may carry one.** The handler's inputs are its declared
+  arguments plus its internal ones, so an endpoint with none of the latter answers the same thing to everyone who
+  may read it — which is the only answer a shared entry can hold. An endpoint that takes `.with(Self)` answers
+  per caller, and one entry would be one caller's answer handed to the next; that endpoint and every `mutation`
+  are named once in the log and left uncached rather than silently ignored.
+- **The guards run before every hit.** The lookup sits after the guards and the internal arguments, inside the
+  call, so every middleware — the account resolution a lib registers among them — has already run and a hit
+  reaches only a caller the guards admitted. It used to be a middleware ahead of the lib's, and a guard reading
+  the account refused a signed-in caller on every hit. Shared is not public.
+- **The entry is the handler's result, not the response.** The lookup wraps the handler only, so `resolveReturn`
+  still runs per call on the cached value — field masking, `hidden`/`secret` stripping and relation resolution are
+  never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
+- **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
+  uncached; a failed write is warned and dropped.
+- The default middleware chain is `Logging → Timeout → <lib middlewares>`, and the call inside it runs guards →
+  internal arguments → cache → handler: a hung cache backend is bounded by the same deadline as the handler it
+  stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
+  whose failure it cannot classify replays whatever the first attempt already did.
+
 ## Binary Pubsub
 
 - **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`

package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md

@@ -7,6 +7,8 @@
 - `apps/<app>/page` holds server-side file-routed pages: `<routeName>.tsx` serves `/routeName`, a directory's
   `_index.tsx` serves that directory, `_layout.tsx` nests a layout, and `[modelId]` is a dynamic segment. Each route
   file is one chain — `export default page()…render()`, or `layout()` / `rootLayout()` in a `_layout.tsx`.
+- The `native` section of `akan.config.ts` makes the app an iOS, Android and desktop app built from the same pages,
+  and `apps/<app>/native/<id>` holds a native plugin the app owns.
 
 The file roles inside a module — which file owns persistence, business logic, state, and each UI shape — are in
 the convention set above under **Domain Module Conventions**.
@@ -112,6 +114,22 @@ For the default generated app, start with:
 akan start <%= appName %>
 ```
 
+### Native Apps — iOS, Android, Desktop
+
+`native: { desktop: { server: true } }` in `akan.config.ts` is all a desktop app that carries its own server needs.
+A `start-*` command loads its pages from `akan start`, so run that first; a desktop app that carries its server
+starts it itself. The full contract — targets, updates, what the carried server ships — is
+`akan guideline show runtimeRule`.
+
+```bash
+akan start-desktop <%= appName %>                   # Run the desktop app on this computer
+akan start-ios <%= appName %>                       # Run it in a simulator or on an iPhone (start-android alike)
+akan build-desktop <%= appName %>                   # Build it for this computer into .akan/native/<target>/build
+akan build-desktop <%= appName %> --installer true  # Windows: add a per-user setup program
+akan update-keygen <%= appName %>                   # Make the update signing key once; print its public key
+akan publish-update <%= appName %>                  # Build and sign a desktop release to upload to updates.url
+```
+
 ### The Essential Loop: Workflow -> Sync -> Check
 
 Almost every Akan.js change follows this pattern. **Missing sync or repair is the #1 cause of agent confusion.**
@@ -200,6 +218,8 @@ final fallback when no CLI command covers the change.
 | Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan sync <name>` |
 | Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan sync <name>` |
 | Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan sync <name>` |
+| Make the app an iOS, Android or desktop app | `akan.config.ts` → `native: { … }`; `desktop: { server: true }` puts the server in the desktop app | `akan start-desktop <name>` (or `start-ios` / `start-android`) |
+| Add a device capability the framework lacks | `native/<id>/` → `native-plugin.json`, `src/index.ts` (page API, used from a `webkit/` hook), `src/desktop.ts`, Kotlin, Swift | the platform's `akan start-*` |
 
 ## Workflow Recipes
 

package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md

@@ -376,15 +376,16 @@ export default page()
 |---|---|
 | `interface PageProps { params }` + `[x]` folder | `.param("x", ID \| String \| Int \| …)` — one per `[x]` segment, every one of them, in path order |
 | `searchParams.k` | `.search("k", Type)`; `[Type]` for a repeated key; the value arrives typed and optional |
-| `params.lang` | `lang` — on every route's `.render()`, `.head()`, `.metadata()` and `.loading()` with no stage; `.param("lang")` is refused |
+| `params.lang` | `lang` — on every route's `.render()`, `.head()` and `.loading()` with no stage; `.param("lang")` is refused |
 | `export const pageConfig = {…}` | `.config({…})` — `devOnly` stays a literal |
 | `export const head = <…/>` / `generateHead({ params })` | `.head(<…/>)` / `.head(({ x }) => <…/>)` |
-| `export const metadata` / `generateMetadata` | `.metadata({…})` / `.metadata((args) => …)` |
+| `export const metadata` / `generateMetadata` | `.head(<><title>…</title><meta name="description" content="…" /></>)` — there is no object form |
 | `export function Loading()` | `.loading((args) => …)` |
 | `export default async function Page({ params, searchParams })` | `.render(async ({ x, k }) => { …same body… })` — `async` only if it awaits |
 | `_layout.tsx`: `export default function Layout({ children })` | `layout().render(({ children }) => …)` |
 | `export function NotFound` / `export function Error` | `.notFound(fn)` / `.error(fn)` on `layout()` |
-| root `_layout.tsx`: `fonts`, `theme`, `manifest`, `reconnect`, `wsConnect`, `layoutStyle`, `gaTrackingId` | `rootLayout().fonts([…]).theme("dark").manifest({…}).reconnect(false).wsConnect(false).layoutStyle("web").gaTrackingId("G-…")` |
+| root `_layout.tsx`: `fonts`, `theme`, `manifest`, `reconnect`, `wsConnect`, `layoutStyle` | `rootLayout().fonts([…]).theme("dark").manifest({…}).reconnect(false).wsConnect(false).layoutStyle("web")` |
+| root `_layout.tsx`: `gaTrackingId` | none — render the app's own `"use client"` analytics component from the root layout's `.render()` |
 | `prompt()` on `endpoint()` (removed) | `.prompt(name, description)` on the page that shows the same screen |
 
 Rules the loader and `akan sync` enforce: a chain module has no other export; `page()` belongs in a page file and
@@ -393,6 +394,68 @@ Rules the loader and `akan sync` enforce: a chain module has no other export; `p
 `_overrides.tsx` is untouched. MCP: `prompts/get` now runs the page's body under the caller's token and hands the
 model the description, what the page fetched, and the tools of those modules — see `mcpRule`.
 
+---
+
+### Recipe 8: Migrating the LLM Adaptor and the Removed `--ai` Commands
+
+Two changes land together. The runtime LLM seam now names a wire rather than a vendor, and the CLI's AI editor is
+gone. They touch different files and neither one is optional — the first breaks a build or, worse, degrades
+silently; the second breaks a script that calls a command that no longer exists.
+
+#### The adaptor, in `lib/option.ts` and `env/env.server.*.ts`
+
+`DeepseekLlm` is deleted. `OpenaiLlm` is the default and speaks the chat-completions dialect to whatever `host`
+names, so DeepSeek, Groq, Together, OpenRouter, Ollama and a self-hosted vLLM are the same class with a different
+`host` and `model`. `AnthropicLlm` is unchanged.
+
+```ts
+// before — env/env.server.local.ts
+export const env: ModulesOptions = {
+  ...libEnv,
+  llm: { apiKey: process.env.DEEPSEEK_KEY },
+};
+
+// after — the default model and host are gone, so name both
+export const env: ModulesOptions = {
+  ...libEnv,
+  llm: { apiKey: process.env.DEEPSEEK_KEY, model: "deepseek-v4-flash", host: "https://api.deepseek.com" },
+};
+```
+
+| Before | After | What happens if you skip it |
+|---|---|---|
+| `setLlm({ apiKey })`, relying on the DeepSeek default | `setLlm({ apiKey, model, host })` | The app boots, the log warns once, and the chat answers `llmUnavailable` to every turn |
+| `applyAdaptor(LlmAdaptorRole, DeepseekLlm)` | `OpenaiLlm` + `host: "https://api.deepseek.com"` | Build error — the class is gone |
+| `OpenaiLlm` pointed at a **named** `host`, reading images | add `accepts: { image: true }` to `setLlm` | **Silent**: images reach the model as a note saying they could not be read |
+| An adaptor of your own throwing `agent.error.<vendor>RequestFailed` | `new Err("agent.error.llmRequestFailed", { provider, status, reason })` | The chat prints the raw key instead of a sentence |
+| Provider settings in a second `option.use({ myLlmOption })` | put them in `setLlm` and read `use<MyLlmOption>()` | Nothing breaks; the second channel is no longer needed |
+
+`OpenaiLlm` claims vision for its default host (`https://api.openai.com/v1`) and for nothing else, because a host
+you named is a gateway it knows nothing about — and bytes handed to a model that cannot decode them kill the whole
+turn on a 400, where text-only degrades them to a note. Declare `accepts` whenever you set `host`.
+
+`LlmOption` is now a floor rather than the whole shape: `setLlm` carries whatever else it is handed to the role, so
+an adaptor of your own declares `interface MyLlmOption extends LlmOption { region: string }`, reads it with
+`use<MyLlmOption>()`, and stops needing a config channel beside `setLlm`.
+
+#### The CLI, in scripts and CI
+
+`AiSession` and every command that drove it are removed. There is no replacement command — the workspace's agent
+surface (`akan context`, the MCP tools, `akan guideline show`) is what feeds a coding agent now.
+
+| Removed | What to do instead |
+|---|---|
+| `akan create-module <name> --ai`, `akan create-scalar <name> --ai` | Drop the flag. The command scaffolds the same files it always did; write the constant and dictionary yourself or let a coding agent do it against `get_guideline modelConstant` / `modelDictionary` |
+| `akan compact <app-or-lib>` | Edit the `*.abstract.md` by hand. `akan quality scan` still warns past 300 lines |
+| `akan set-llm`, `akan reset-llm`, `akan ask` | Nothing. The runtime LLM is `option.setLlm(...)` and has never been this config |
+| `akan generate-instruction`, `akan update-instruction`, `akan generate-document`, `akan reapply-instruction` | Nothing. `akan guideline list` / `show` still read the bundled guidelines |
+| `import { AiSession } from "@akanjs/devkit/aiEditor"` | Nothing — the module is gone |
+
+`~/.akan/config.json` keeps an `llm` entry if it had one. It is ignored; delete it, because it holds an API key.
+
+Then: `bun run akan typecheck <app>`, `bun run akan lint <app>`, and one agent turn in the browser to confirm the
+provider answers.
+
 ### Data Flow Summary
 
 For each business question, follow this chain: