@akanjs/cli 3.0.0-beta.2 → 3.0.0-beta.20

package/guidelines/queryRule/queryRule.instruction.md

@@ -49,7 +49,7 @@ with it. `conventions` carries the invariants — this is the full contract behi
   `findBy<Filter>(...args, { select: { secretField: true } })` takes it inside the option object. The shapes do not
   swap: `{ select: … }` handed to the facade projects a field named `select`, which no model has, and the read comes
   back empty with no error. This is the only way to read a `field.secret(...)` value, which is otherwise stripped.
-- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`); client fetch results are raw `GetStateObject` plain data (functions stripped, `pkgs/akanjs/base/types.ts`).
+- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`), and so do client fetch results — `FetchClient` parses every return with `crystalize` defaulting to **true** (`pkgs/akanjs/fetch/client/fetchClient.ts`). The raw `GetStateObject` shape (functions stripped, `pkgs/akanjs/base/types.ts`) is what the `<ref>Obj` / `<ref>ObjList` / `<ref>ObjInsight` handles carry, because those pass `crystalize: false` on purpose so the value can cross the RSC boundary as a client prop.
 - Every filter generates fourteen methods: `list` · `listIds` · `find` · `findId` · `pick` · `pickId` · `exists` ·
   `count` · `insight` · `query` · **`remove`** · **`removeOne`** · **`update`** · **`updateOne`**. The last four are
   query-level writes — one atomic UPDATE, **no hooks**, and therefore no `_postRemove` and no cascade. Use them on a
@@ -90,14 +90,15 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - **A slice endpoint never reaches "unspecified".** The resolver fills `latest` before the query is built, so a
   client asking for the score order has to name `relevance`; leaving `sort` off gets `latest`, not relevance.
 - Scope a search with `columns` (`q.search(text, { columns: ["title"] })`) and re-weight with `weights`, a tuple of
-  finite numbers positional over `["title", "desc", "tag", "filter"]`.
+  finite, non-negative numbers positional over `["title", "desc", "tag", "filter"]` — Postgres ranks by weight
+  class and has no reading for a negative one.
 
 
 ## Text Search Fields — the `text` role
 
 - A field joins the full-text index by declaring one of five roles: `field(String, { text: "title" })`, and likewise
   `"desc"`, `"tag"`, `"thumb"`, `"filter"`. Nothing else opts a field in, and there is no per-model switch.
-- Pick the role by what the value *is*, because `bm25` weights them positionally (`title` 10, `tag` 3, `desc` 1,
+- Pick the role by what the value *is*, because the rank weights them positionally (`title` 10, `tag` 3, `desc` 1,
   `filter` 0): `title` is the one line a human scans for, `desc` is prose, `tag` is a keyword list, `filter` is a
   scoping value (status, owner, role) that must be matchable but must never outrank a real title hit.
 - `thumb` is mirrored for rendering a hit and is **not** indexed — never expect it to match.
@@ -114,15 +115,24 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - Declaring roles is all the wiring there is. Mirror rows are maintained by SQL triggers — not document hooks —
   because `updateOneByQuery` and friends fire no hooks, and most searchable-field mutations go through exactly that
   path.
-- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- Search runs in every database mode: fts5 on SQLite/libSQL, a weighted `tsvector` under a GIN index on Postgres.
+  For the same text the same documents match — punctuation splits words the way unicode61 does, and a phrase never
+  runs from one column into the next — but the order may differ, since Postgres ranks without document frequency.
+  Assert on the match set, never on a Postgres order the weights alone do not decide.
+- Postgres reads `AKAN_SEARCH_TOKENIZER` as `unicode61 [remove_diacritics 0|1|2]` (`simple`, with `unaccent` unless
+  `0`) or `trigram [case_sensitive 0|1]` (`pg_trgm`); any other spelling is refused. The extension is created when
+  the role may, otherwise a role that may runs `CREATE EXTENSION`. It indexes the first 20,000 characters of
+  `title`, `tag` and `filter` and 200,000 of `desc` — a tsvector refuses more than 1MB, and the refusal would fail
+  the model write. A database whose `LC_CTYPE` is `C` keeps non-ASCII case apart; use a UTF-8 ctype.
 - `AKAN_SEARCH_ENABLED=0` switches the index off process-wide; unset means on. It never deletes mirror data, and
   re-enabling reconciles every ref. **Give every process the same value** — a process cannot drop triggers for models
   it does not mount, so a mixed fleet leaves stale triggers behind.
 - The tokenizer is `AKAN_SEARCH_TOKENIZER` (or `database.search.tokenizer`, which wins), defaulting to
   `unicode61 remove_diacritics 2`. Changing it rebuilds the index from the mirror on the next boot — the model
-  tables are never re-read — so it is a safe knob, unlike a `text` role change, which re-reads every row. The
-  rebuild takes no cross-process claim, so a fleet restarted at once repeats it in every process; stagger the
-  restart when the mirror is large.
+  tables are never re-read — so it is a safe knob, unlike a `text` role change, which re-reads every row. The schema
+  is ensured in one write turn — a SQLite write transaction, a Postgres schema lock — so of a fleet restarted at
+  once the first rebuilds and the rest find it current. A SQLite process waits for that turn up to its
+  `busy_timeout`, so stagger the restart when the mirror is large.
 
 ## Cascade Remove — the `cascade` option
 

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -184,6 +184,80 @@ 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`.
 
+## 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/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:

package/incrementalBuilder.proc.js

@@ -1,22 +1,22 @@
 // @bun
+import {
+  ApplicationBuildReporter,
+  HmrWatcher,
+  WatchRootResolver
+} from "./index-khpfpcsd.js";
 import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-2tv3fdx4.js";
-import"./index-q0y2jq9j.js";
-import"./index-6wwzs1bc.js";
+} from "./index-9d9bgcx4.js";
+import"./index-5b6tavv3.js";
 import {
   GraphClientEntryDiscovery,
   RouteClientBuilder,
   AutoImportSync,
   DevChangePlanner,
   DevGeneratedIndexSync
-} from "./index-w8kmx1b6.js";
-import {
-  HmrWatcher,
-  WatchRootResolver
-} from "./index-hwkygn9s.js";
+} from "./index-fgq75haa.js";
 import {
   prepareDevWatchBatch
 } from "./index-a5vmm6x4.js";
@@ -30,12 +30,6 @@ import path from "path";
 import { Logger } from "akanjs/common";
 
 class BuildBatchRunner {
-  static #entryCandidates = (workspaceRoot) => [
-    path.join(workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(import.meta.dir, "buildBatch.proc.js"),
-    path.join(import.meta.dir, "buildBatch.proc.ts")
-  ];
   #logger = new Logger("BuildBatchRunner");
   #entry = null;
   #workspaceRoot;
@@ -47,7 +41,12 @@ class BuildBatchRunner {
   async#resolveEntry() {
     if (this.#entry)
       return this.#entry;
-    const candidates = BuildBatchRunner.#entryCandidates(this.#workspaceRoot);
+    const candidates = [
+      path.join(this.#workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(this.#workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(import.meta.dir, "buildBatch.proc.js"),
+      path.join(import.meta.dir, "buildBatch.proc.ts")
+    ];
     for (const candidate of candidates) {
       if (!await Bun.file(candidate).exists())
         continue;
@@ -173,6 +172,7 @@ class IncrementalBuilder {
         app: this.#app,
         routeId: msg.routeId,
         seeds: msg.seeds,
+        graphSeeds: msg.graphSeeds,
         artifact: this.#artifact,
         knownEntries: new Set(msg.knownEntries),
         discovery: this.#discovery
@@ -195,7 +195,7 @@ class IncrementalBuilder {
         }
       };
     } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
+      const errMsg = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
       this.#logger.error(`build-route failed routeId=${msg.routeId}: ${errMsg}`);
       this.#sendBuildStatus("route", { generation: msg.generation, ok: false, files: msg.seeds, message: errMsg });
       return { type: "build-route-res", id: msg.id, ok: false, error: errMsg };
@@ -335,20 +335,19 @@ class IncrementalBuilder {
     }, 150);
   }
   async installWatcher() {
-    const artifactDir = this.#artifactDir;
     const roots = await new WatchRootResolver(this.#app).resolve();
     const watcher = new HmrWatcher({
       roots,
       logger: this.#logger,
       onBatch: async (batch) => {
-        await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(artifactDir, batch));
+        await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(batch));
       }
     });
     await watcher.start();
     this.#watcher = watcher;
     this.#logger.verbose(`watching ${roots.length} roots`);
   }
-  async#handleWatchBatch(artifactDir, batch) {
+  async#handleWatchBatch(batch) {
     const rawKinds = new Set(batch.kinds);
     if (rawKinds.size === 0)
       return;
@@ -401,7 +400,7 @@ class IncrementalBuilder {
     }
     const needs = [];
     if (kinds.includes("code") && rebuildClient) {
-      if (this.#shouldRebuildCsr())
+      if (this.#csrActive)
         needs.push("csr");
       else
         this.#logger.verbose(`csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`);
@@ -416,13 +415,10 @@ class IncrementalBuilder {
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }
   }
-  async#runBatch({
-    generation,
-    needs,
-    changedFiles
-  }) {
+  async#runBatch(work) {
+    const { generation, needs, changedFiles } = work;
     const started = Date.now();
-    const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs, changedFiles }), (msg) => BuilderChannel.emit(msg));
+    const result = await this.#batchRunner.run(await this.#batchRequest(work), (msg) => BuilderChannel.emit(msg));
     if (result.optimizedFonts)
       this.#optimizedFonts = result.optimizedFonts;
     if (result.cssAssets)
@@ -436,11 +432,7 @@ class IncrementalBuilder {
       this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
     return result;
   }
-  async#batchRequest({
-    generation,
-    needs,
-    changedFiles
-  }) {
+  async#batchRequest({ generation, needs, changedFiles }) {
     return {
       appName: this.#app.name,
       workspaceRoot: this.#app.workspace.workspaceRoot,
@@ -505,9 +497,6 @@ class IncrementalBuilder {
       await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: true });
     });
   }
-  #shouldRebuildCsr() {
-    return this.#csrActive;
-  }
   static #csrArmedByEnv() {
     return process.env.AKAN_DEV_CSR_REBUILD === "1";
   }
@@ -606,23 +595,17 @@ class IncrementalBuilder {
         builder.shutdown(msg.reason);
         return;
       }
-      if (msg.type === "build-route") {
+      if (msg.type !== "build-route" && msg.type !== "build-csr")
+        return;
+      if (!builder || builder.shuttingDown) {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
-        if (!builder || builder.shuttingDown) {
-          BuilderChannel.emit({ type: "build-route-res", id: msg.id, ok: false, error });
-          return;
-        }
-        builder.handleBuildRoute(msg);
+        BuilderChannel.emit({ type: `${msg.type}-res`, id: msg.id, ok: false, error });
         return;
       }
-      if (msg.type === "build-csr") {
-        const error = builder?.shuttingDown ? recyclingError : bootingError;
-        if (!builder || builder.shuttingDown) {
-          BuilderChannel.emit({ type: "build-csr-res", id: msg.id, ok: false, error });
-          return;
-        }
+      if (msg.type === "build-route")
+        builder.handleBuildRoute(msg);
+      else
         builder.handleBuildCsr(msg);
-      }
     });
     process.on("disconnect", () => {
       logger.warn("host IPC channel closed; exiting builder");
@@ -647,7 +630,7 @@ class IncrementalBuilder {
     await builder.rearmCsrFromEnv();
   }
 }
-IncrementalBuilder.main().catch((err) => {
+await IncrementalBuilder.main().catch((err) => {
   console.error(err);
   process.exit(1);
 });

package/{index-h7yw2z9n.js → index-0bq14vr1.js}

@@ -1,12 +1,12 @@
 // @bun
 import {
   getDirname2
-} from "./index-6wwzs1bc.js";
+} from "./index-5b6tavv3.js";
 
 // pkgs/@akanjs/devkit/prompter.ts
 import fsPromise from "fs/promises";
 import { input, select } from "@inquirer/prompts";
-class Prompter {
+class Prompter2 {
   static async#getGuidelineRoot() {
     const dirname = getDirname2(import.meta.url);
     const candidates = [`${dirname}/guidelines`, `${dirname}/../cli/guidelines`];
@@ -19,27 +19,21 @@ class Prompter {
     return candidates[0];
   }
   static async selectGuideline() {
-    const guideNames = await Prompter.listGuidelines();
+    const guideNames = await Prompter2.listGuidelines();
     return await select({
       message: "Select a guideline",
       choices: guideNames.map((name) => ({ name, value: name }))
     });
   }
   static async listGuidelines() {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const guidelineRoot = await Prompter2.#getGuidelineRoot();
     return (await fsPromise.readdir(guidelineRoot)).filter((name) => !name.startsWith("_")).sort();
   }
-  static async getGuideJson(guideName) {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
-    const filePath = `${guidelineRoot}/${guideName}/${guideName}.generate.json`;
-    const guideJson = await fsPromise.readFile(filePath, "utf-8");
-    return JSON.parse(guideJson);
-  }
   static async getInstruction(guideName) {
-    const guideNames = await Prompter.listGuidelines();
+    const guideNames = await Prompter2.listGuidelines();
     if (!guideNames.includes(guideName))
       throw new Error(`Unknown guideline "${guideName}". Available: ${guideNames.join(", ")}`);
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const guidelineRoot = await Prompter2.#getGuidelineRoot();
     return await fsPromise.readFile(`${guidelineRoot}/${guideName}/${guideName}.instruction.md`, "utf-8");
   }
   static async getUpdateRequest(guideName) {
@@ -67,7 +61,7 @@ ${request}
 `;
   }
   async getDocumentation(guideName) {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const guidelineRoot = await Prompter2.#getGuidelineRoot();
     const filePath = `${guidelineRoot}/${guideName}/${guideName}.instruction.md`;
     const document = await fsPromise.readFile(filePath, "utf-8");
     return `\`\`\`markdown
@@ -77,4 +71,4 @@ ${document}
   }
 }
 
-export { Prompter };
+export { Prompter2 };

package/index-13ffe9wp.js

@@ -0,0 +1,69 @@
+// @bun
+import {
+  jsonText
+} from "./index-myhc3c1j.js";
+import {
+  akanMcpInstallTargets
+} from "./index-ygn77a5w.js";
+import {
+  script
+} from "./index-w2zdcw3k.js";
+import {
+  ContextRunner2
+} from "./index-nv5976x3.js";
+
+// pkgs/@akanjs/cli/context/context.script.ts
+import { Logger } from "akanjs/common";
+var resolveMcpInstallTargets = (target) => {
+  if (!target || target === "all")
+    return [...akanMcpInstallTargets];
+  if (akanMcpInstallTargets.includes(target))
+    return [target];
+  throw new Error(`Unknown MCP install target: ${target}. Use cursor, claude, codex, or all.`);
+};
+var mcpTargetLabels = {
+  cursor: "Cursor",
+  claude: "Claude Code",
+  codex: "Codex"
+};
+
+class ContextScript extends script("context", [ContextRunner2]) {
+  async context(workspace, options = {}) {
+    Logger.rawLog(await this.contextRunner.getContext(workspace, options));
+  }
+  async doctor(workspace, options = {}) {
+    Logger.rawLog(await this.contextRunner.doctor(workspace, options));
+  }
+  async mcpInstall(workspace, target, { force = false, mode = "apply" } = {}) {
+    const targets = resolveMcpInstallTargets(target);
+    const written = [];
+    for (const t of targets) {
+      const configPath = await this.contextRunner.installMcp(workspace, t, { force, mode });
+      written.push(`${mcpTargetLabels[t]}: ${configPath}`);
+    }
+    Logger.rawLog(`Akan MCP server installed (${mode} mode):
+${written.map((line) => `- ${line}`).join(`
+`)}`);
+  }
+  async mcp(workspace, { mode = "apply" } = {}) {
+    await this.contextRunner.runMcp(workspace, { mode });
+  }
+  async mcpCall(workspace, tool, {
+    mode = "readonly",
+    args = null,
+    format = "json"
+  } = {}) {
+    let parsedArgs = {};
+    if (args) {
+      const parsed = JSON.parse(args);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("MCP call args must be a JSON object.");
+      }
+      parsedArgs = parsed;
+    }
+    const result = await this.contextRunner.callMcpTool(workspace, tool, parsedArgs, { mode });
+    Logger.rawLog(format === "json" ? jsonText(result) : String(result));
+  }
+}
+
+export { ContextScript };