@akanjs/devkit 3.0.0-beta.17 → 3.0.0-beta.18

package/abstractDoc.ts

@@ -5,10 +5,8 @@ export type AbstractKind = "domain" | "service" | "scalar" | "other";
 /** One `*.abstract.md` file: the agent-facing summary a module carries next to its source. */
 export class AbstractDoc {
   static readonly suffix = ".abstract.md";
-  /** `akan quality` warns above this and points at `akan compact`. */
+  /** `akan quality` warns above this. */
   static readonly maxLines = 300;
-  /** `akan compact` floor, and the line budget it compacts down to, so a compacted file is never a candidate again. */
-  static readonly compactMinLines = 40;
   // Abstracts only live in facet folders; globbing the sys root instead would walk node_modules.
   static readonly #facetRoots = "{lib,ui,webkit,srvkit,common,plugin}";
 

package/applicationBuildRunner.ts

@@ -246,11 +246,12 @@ export class ApplicationBuildRunner {
   async #writeConsoleShim() {
     await Bun.write(
       path.join(this.#app.dist.cwdPath, "console.js"),
-      `import { cnst, db, dict, option, server, sig, srv } from "./server.js";
-import { assertAkanConsoleAllowed, startAkanConsole } from "./console-runtime.js";
+      `process.env.AKAN_COMMAND_TYPE = "console";
+const { cnst, db, dict, option, server, sig, srv } = await import("./server.js");
+const { assertAkanConsoleAllowed, startAkanConsole } = await import("./console-runtime.js");
 
 const run = async () => {
-  assertAkanConsoleAllowed(server.env);
+  assertAkanConsoleAllowed();
   await server.start({ listen: false, web: false });
   try {
     await startAkanConsole(server, { globals: { cnst, db, dict, option, sig, srv } });

package/artifact/implicitRootLayout.test.ts

@@ -31,11 +31,11 @@ describe("resolveSsrPageEntries", () => {
     await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
     await write(
       rootLayoutPath,
-      'export const theme = "dark";\nexport const fonts = [{ name: "pretendard" }];\nexport const metadata = { title: "Root" };\n',
+      'export const theme = "dark";\nexport const fonts = [{ name: "pretendard" }];\nexport const head = null;\n',
     );
     await write(
       groupedLayoutPath,
-      'export function generateMetadata() { return { title: "Home" }; }\nexport default function Layout({ children }) { return children; }\n',
+      "export function generateHead() { return null; }\nexport default function Layout({ children }) { return children; }\n",
     );
 
     const entries = await resolveSsrPageEntries({
@@ -54,15 +54,10 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
     expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
     expect(generatedSource).not.toContain("<System.Provider");
-    expect(generatedSource).toContain("export async function generateMetadata(props: PageProps)");
-    expect(generatedSource).toContain("if (userLayout.generateMetadata) return userLayout.generateMetadata(props);");
-    expect(generatedSource).toContain("if (userLayout.metadata !== undefined) return userLayout.metadata;");
-    expect(generatedSource).toContain(
-      "if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);",
-    );
-    expect(generatedSource).toContain("return inheritedLayout.metadata;");
-    expect(generatedSource).not.toContain("Object.keys(userLayout.metadata)");
-    expect(generatedSource).not.toContain("Object.keys(inheritedLayout.metadata)");
+    expect(generatedSource).toContain("export async function generateHead(props: PageProps)");
+    expect(generatedSource).toContain("if (userLayout.generateHead) return userLayout.generateHead(props);");
+    expect(generatedSource).toContain("return inheritedLayout.head;");
+    expect(generatedSource).not.toContain("generateMetadata");
     expect(generatedSource).toContain("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
     expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");

package/artifact/implicitRootLayout.ts

@@ -236,13 +236,6 @@ export async function generateHead(props: PageProps) {
   return inheritedLayout.head;
 }
 
-export async function generateMetadata(props: PageProps) {
-  if (userLayout.generateMetadata) return userLayout.generateMetadata(props);
-  if (userLayout.metadata !== undefined) return userLayout.metadata;
-  if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);
-  return inheritedLayout.metadata;
-}
-
 export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
@@ -258,7 +251,6 @@ ${layoutBinding}  return (
       theme={userLayout.theme ?? inheritedLayout.theme}
       fonts={loadFonts(userFonts)}
       className={defaultFontClassName}
-      gaTrackingId={userLayout.gaTrackingId ?? inheritedLayout.gaTrackingId}
       layoutStyle={userLayout.layoutStyle ?? inheritedLayout.layoutStyle}
       reconnect={userLayout.reconnect ?? inheritedLayout.reconnect ?? false}
       wsConnect={userLayout.wsConnect ?? inheritedLayout.wsConnect ?? true}
@@ -280,13 +272,6 @@ export async function generateHead(props: PageProps) {
   return inheritedLayout.head;
 }
 
-export async function generateMetadata(props: PageProps) {
-  if (userLayout.generateMetadata) return userLayout.generateMetadata(props);
-  if (userLayout.metadata !== undefined) return userLayout.metadata;
-  if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);
-  return inheritedLayout.metadata;
-}
-
 export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;

package/biome.base.json

@@ -154,7 +154,12 @@
       ]
     },
     {
-      "includes": ["{apps,libs}/**/page/**/*.ts", "{apps,libs}/**/page/**/*.tsx"],
+      "includes": [
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.View.tsx"
+      ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
     },
     {

package/capacitorApp.test.ts

@@ -24,6 +24,7 @@ import {
   sanitizeIosNativeRunEnv,
   selectLocalDevHost,
   sortIosRunTargets,
+  toIosInfoPlistUsageDescriptions,
   writeRootCapacitorConfig,
 } from "./capacitorApp";
 
@@ -370,3 +371,28 @@ describe("raiseGradleMinSdkVersion", () => {
     expect(raiseGradleMinSdkVersion("minSdkVersion = 28", 26)).toBeNull();
   });
 });
+
+describe("toIosInfoPlistUsageDescriptions", () => {
+  test("writes Apple's real Info.plist keys, not NS + the description name", () => {
+    expect(
+      toIosInfoPlistUsageDescriptions({
+        cameraUsageDescription: "camera",
+        photoAddUsageDescription: "add",
+        photoUsageDescription: "read",
+        locationAlwaysUsageDescription: "always",
+      }),
+    ).toEqual({
+      NSCameraUsageDescription: "camera",
+      NSPhotoLibraryAddUsageDescription: "add",
+      NSPhotoLibraryUsageDescription: "read",
+      NSLocationAlwaysAndWhenInUseUsageDescription: "always",
+      NSLocationAlwaysUsageDescription: "always",
+    });
+  });
+
+  test("keeps the NS prefix convention for a key it does not know", () => {
+    expect(toIosInfoPlistUsageDescriptions({ bluetoothAlwaysUsageDescription: "ble" })).toEqual({
+      NSBluetoothAlwaysUsageDescription: "ble",
+    });
+  });
+});

package/capacitorApp.ts

@@ -489,7 +489,7 @@ export function classifyIosRunFailure(log: string): IosRunFailureClassification
     kind: "unknown",
     title: "iOS native run failed.",
     detail:
-      "Review the xcodebuild/devicectl output above. You can retry with --noAllowProvisioningUpdates to use the conservative path.",
+      "Review the xcodebuild/devicectl output above. You can retry with --no-allow-provisioning-updates to use the conservative path.",
   };
 }
 
@@ -597,6 +597,29 @@ export function raiseGradleMinSdkVersion(content: string, floor: number = ANDROI
   return content.replace(/(minSdkVersion\s*=\s*)\d+/, `$1${floor}`);
 }
 
+//* Apple's Info.plist keys do not follow the description names (photo → NSPhotoLibrary…), so each one is spelled out.
+const iosUsageDescriptionKeys = {
+  cameraUsageDescription: ["NSCameraUsageDescription"],
+  photoAddUsageDescription: ["NSPhotoLibraryAddUsageDescription"],
+  photoUsageDescription: ["NSPhotoLibraryUsageDescription"],
+  contactsUsageDescription: ["NSContactsUsageDescription"],
+  //? iOS 11+ reads the AlwaysAndWhenInUse key; the Always key only serves iOS 10 and below.
+  locationAlwaysUsageDescription: ["NSLocationAlwaysAndWhenInUseUsageDescription", "NSLocationAlwaysUsageDescription"],
+  locationWhenInUseUsageDescription: ["NSLocationWhenInUseUsageDescription"],
+  microphoneUsageDescription: ["NSMicrophoneUsageDescription"],
+  speechRecognitionUsageDescription: ["NSSpeechRecognitionUsageDescription"],
+} as const;
+
+export const toIosInfoPlistUsageDescriptions = (descriptions: { [key: string]: string }) =>
+  Object.fromEntries(
+    Object.entries(descriptions).flatMap(([key, value]) => {
+      const plistKeys: readonly string[] = Object.hasOwn(iosUsageDescriptionKeys, key)
+        ? iosUsageDescriptionKeys[key as keyof typeof iosUsageDescriptionKeys]
+        : [`NS${capitalize(key)}`];
+      return plistKeys.map((plistKey) => [plistKey, value]);
+    }),
+  );
+
 const mergeAllowNavigation = (configured: unknown, localIp: string | undefined) => {
   const values = Array.isArray(configured)
     ? configured.filter((value): value is string => typeof value === "string")
@@ -1469,9 +1492,7 @@ export class CapacitorApp {
     if (next !== content) await editor.setContent(next).save();
   }
   async #setPermissionInIos(permissions: { [key: string]: string }) {
-    const updateNs = Object.fromEntries(
-      Object.entries(permissions).map(([key, value]) => [`NS${capitalize(key)}`, value]),
-    );
+    const updateNs = toIosInfoPlistUsageDescriptions(permissions);
     await Promise.all([
       this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", updateNs),
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", updateNs),

package/codeAgent/agent/AkanCodeServices.ts

@@ -66,22 +66,29 @@ export class AkanCodeServices {
   }
 
   /**
-   * The akan skill set, then the workspace's own.
+   * The akan skill set, then the person's own, then the workspace's.
    *
-   * A path that does not exist is a reported load error rather than a skip, so both are checked first.
+   * `~/.akan/code/skills` is read because a skill somebody wrote for themselves is theirs, not one checkout's,
+   * and having to copy it into every repo is the same friction that makes people stop writing them. It is
+   * text the model may read, never code that runs — which is why extensions stay workspace-only below.
+   *
+   * A path that does not exist is a reported load error rather than a skip, so each is checked first.
    */
   static #skillPaths(profile: CodeAgentProfile, workspaceRoot: string) {
     if (!profile.context.skills) return [];
-    const workspace = akanCodePaths.skillsDir(workspaceRoot);
-    return [akanCodePaths.builtinSkillsDir(), existsSync(workspace) ? workspace : undefined].filter(
-      (dir): dir is string => !!dir,
-    );
+    const dirs = [
+      akanCodePaths.builtinSkillsDir(),
+      akanCodePaths.globalSkillsDir(),
+      akanCodePaths.skillsDir(workspaceRoot),
+    ];
+    return dirs.filter((dir): dir is string => !!dir && existsSync(dir));
   }
 
   /**
-   * What the engine's resource loader may discover. Extensions and skills come from the workspace, never from
-   * the home directory: a coding agent that picks up a globally installed extension behaves differently in two
-   * checkouts of the same repo for reasons nothing in the repo explains.
+   * What the engine's resource loader may discover. Extensions come from the workspace and nowhere else: a
+   * globally installed extension is code that runs in every checkout, so an agent would behave differently in
+   * two clones of the same repo for reasons nothing in the repo explains. Skills are text and are read from
+   * the home directory too — see `#skillPaths`.
    */
   static resourceOptions(options: AkanCodeServicesOptions) {
     // A path that does not exist is reported as a load error rather than skipped, and these two are optional.

package/codeAgent/agent/CodeAgent.ts

@@ -15,6 +15,7 @@ import {
   type CodeAgentImage,
   type CodeAgentMcpStatus,
   type CodeAgentProfile,
+  type CodeAgentProviderInfo,
   type CodeAgentQuestion,
   type CodeAgentSessionInfo,
   type CodeAgentState,
@@ -121,6 +122,7 @@ export class CodeAgent {
       mailbox: () => agent.#mailbox,
       onNotice: (message) => agent.#emit({ type: "notice", level: "warning", message }),
       onAgents: (agents) => agent.#emit({ type: "subagent", agents }),
+      onAsk: (question) => agent.ask(question),
     });
 
     const resourceLoader = new DefaultResourceLoader({
@@ -281,6 +283,7 @@ export class CodeAgent {
       const text = CodeAgent.#textOf(message.content);
       if (text) this.#emit({ type: "message", turnId, role: message.role, text });
     }
+    this.#emitContextNow();
   }
 
   static #textOf(content: unknown) {
@@ -400,6 +403,33 @@ export class CodeAgent {
     this.#emit({ type: "session", info: this.info });
   }
 
+  /**
+   * The model catalogue, as the two questions a person actually asks of it.
+   *
+   * Built from the registry rather than `getAvailable()` so it needs no await and can answer about a provider
+   * nobody has a key for: "what else could I run" is most of why the list is opened, and a list of only what
+   * is already reachable cannot answer it.
+   */
+  catalogue(): CodeAgentProviderInfo[] {
+    const runtime = this.#session?.modelRuntime;
+    if (!runtime) return [];
+    const current = this.#session?.model;
+    return runtime
+      .getProviders()
+      .map((provider) => ({
+        id: provider.id,
+        name: provider.name ?? provider.id,
+        authorized: runtime.hasConfiguredAuth(provider.id),
+        models: (runtime.getModels(provider.id) ?? []).map((model) => ({
+          id: model.id,
+          name: model.name,
+          ...(model.contextWindow ? { contextWindow: model.contextWindow } : {}),
+          current: model.provider === current?.provider && model.id === current?.id,
+        })),
+      }))
+      .sort((a, b) => a.id.localeCompare(b.id));
+  }
+
   async setModel(ref: CodeAgentModelRef) {
     const session = this.#require();
     const model = await akanCodeModel(session.modelRuntime, ref);
@@ -461,6 +491,17 @@ export class CodeAgent {
    */
   #emitContextUsage(eventType: string) {
     if (eventType !== "agent_end" && eventType !== "compaction_end") return;
+    this.#emitContextNow();
+  }
+
+  /**
+   * The same frame, on demand, for the one moment the window is already full and no turn has run.
+   *
+   * A resumed session restores a conversation the model is carrying and the host has never seen, so without
+   * this the status line offers the declared window and no share of it until the next turn ends — a session
+   * reopened at 80% looks identical to one reopened empty.
+   */
+  #emitContextNow() {
     const usage = this.#session?.getContextUsage();
     // `== null`, not `=== null`: the field is typed `number | null`, and a strict null check sails straight
     // past an `undefined` the way the mirror of this bug does — which would emit `used: undefined`.
@@ -537,25 +578,33 @@ export class CodeAgent {
     return await this.#asks.openApproval(approvalId);
   }
 
+  /**
+   * Puts one question on the wire and waits for its answer, rendered as the labels a person chose.
+   *
+   * The single way anything asks: the engine's own UI port and the `ask_user` tool both land here, so the
+   * suspend path, the profile's refusal to prompt at all, and the id the host answers against cannot disagree
+   * between them. An empty answer is a skip, which is a real answer and not a failure.
+   */
+  async ask(spec: Omit<CodeAgentQuestion, "questionId">) {
+    if (!this.#profile.ui.canPrompt) return undefined;
+    const question: CodeAgentQuestion = { questionId: this.#asks.nextId("q"), ...spec };
+    this.#emit({ type: "question", question });
+    if (this.#profile.interaction.question === "suspend") {
+      this.#mapper.noteOutcome("awaiting");
+      return undefined;
+    }
+    return (await this.#asks.openQuestion(question)) || undefined;
+  }
+
   #ui() {
     return new CodeAgentUi({
-      ask: async (prompt, kind, choices) => {
-        if (!this.#profile.ui.canPrompt) return undefined;
-        const questionId = this.#asks.nextId("q");
-        const question: CodeAgentQuestion = {
-          questionId,
+      ask: async (prompt, kind, choices) =>
+        await this.ask({
           prompt,
           kind,
           ...(choices ? { options: choices.map((label) => ({ key: label, label })) } : {}),
           freeText: kind === "text",
-        };
-        this.#emit({ type: "question", question });
-        if (this.#profile.interaction.question === "suspend") {
-          this.#mapper.noteOutcome("awaiting");
-          return undefined;
-        }
-        return (await this.#asks.openQuestion(question)) || undefined;
-      },
+        }),
       notify: (level, message) => this.#emit({ type: "notice", level, message }),
     });
   }

package/codeAgent/agent/akanCodePaths.ts

@@ -12,6 +12,15 @@ const builtinSkillsDir = () => {
   return candidates.find((candidate) => existsSync(candidate));
 };
 
+/**
+ * Where `akan code` keeps what belongs to the person rather than to the repo.
+ *
+ * `AKAN_CODE_HOME` moves the whole set. A container that mounts no home directory, a CI job that must not
+ * write to one, and a second checkout that wants its own credentials all need the same thing, and moving the
+ * files apart would let a `models.json` and the `auth.json` it names drift into different directories.
+ */
+const globalDir = () => process.env.AKAN_CODE_HOME ?? path.join(homedir(), ".akan", "code");
+
 /**
  * Sessions live in the workspace — they are project history, and a second checkout of the same repo is a
  * different project. Credentials live in the home directory instead: a repo directory is the one place a key
@@ -25,7 +34,18 @@ export const akanCodePaths = {
   mailDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mail"),
   builtinSkillsDir,
   mcpFile: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mcp.json"),
-  globalDir: () => path.join(homedir(), ".akan", "code"),
-  authFile: () => path.join(homedir(), ".akan", "code", "auth.json"),
-  modelsFile: () => path.join(homedir(), ".akan", "code", "models.json"),
+  /**
+   * The MCP servers that belong to the person rather than to one checkout.
+   *
+   * A server is an integration with an account — the credential for it is already global, in `mcpAuth.json` —
+   * so declaring it per repo means declaring it again in every repo and signing in again in each. The
+   * workspace file stays, for a server that is genuinely this repo's, and wins on a name they share.
+   */
+  globalMcpFile: () => path.join(globalDir(), "mcp.json"),
+  globalSkillsDir: () => path.join(globalDir(), "skills"),
+  globalDir,
+  authFile: () => path.join(globalDir(), "auth.json"),
+  /** MCP bearer tokens, beside the provider keys and for the same reason: never in a directory that is shared. */
+  mcpAuthFile: () => path.join(globalDir(), "mcpAuth.json"),
+  modelsFile: () => path.join(globalDir(), "models.json"),
 } as const;

package/codeAgent/agent/akanSystemPrompt.ts

@@ -14,6 +14,7 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
     "- Prefer an akan workflow to a direct source edit. `list_workflows` / `explain_workflow` / `plan_workflow`, then `apply_workflow({ planPath })`. Editing source by hand is the fallback, not the default.",
     "- Read context with `inspect_akan_context` before reading source bodies; it answers most structural questions without spending the file.",
     "- Fetch the guideline for an area before a deep pass on it: `get_guideline`.",
+    "- A question about `akan code` itself — its slash commands, MCP servers, sessions, models, keys, or where its files live — is answered by the `akan-code` skill. Read it rather than describing the tool from memory.",
     "- Never hand-edit a generated file (`lib/cnst.ts`, `db.ts`, `st.ts`, any `*/index.ts` barrel). Fix the owning source and run `repair_generated` or `akan sync`.",
   ];
   if (profile.tools.builtin.includes("write"))
@@ -28,6 +29,10 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
     lines.push(
       '- Hand a self-contained search or read to `task` — `type: "explore"` reads and reports, `type: "code"` makes the change. Only its answer comes back, so give it everything it needs and ask for exactly what you want returned. Do it yourself when the reading is short or when you need the files in front of you.',
     );
+  if (profile.ui.canPrompt)
+    lines.push(
+      "- Ask with `ask_user` when two readings of the request would lead to materially different work, and offer the options you can name. Do not ask for a choice that has an obvious default, and do not ask permission for work you were already asked to do — make the call, say the assumption, and carry on.",
+    );
   if (profile.approval !== "never")
     lines.push(
       `- Some tool calls need the user's approval (policy: ${profile.approval}). A refusal is an answer; do not retry it a different way.`,

package/codeAgent/skills/akan-code/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: akan-code
+description: "Answer a question about `akan code` itself — how to add or remove an MCP server, sign one in, switch model, fork or resume a session, what the slash commands and keys are, and where its files live. Read this before telling anyone how to use this tool."
+---
+
+# akan code — the manual
+
+This is the tool the user is talking to right now. When they ask how to do something *with it* — rather than
+with their code — answer from here, and quote the exact gesture: the slash command to type, or the file to
+edit. Do not guess a command; everything this tool offers is listed below.
+
+You cannot type a slash command yourself. They are the host's, not yours — say which one to type. You *can*
+edit the files named below, which is the useful half of most of these answers: write the change, then say
+which command makes it take effect.
+
+## MCP servers
+
+Declared in **`.akan/code/mcp.json`**, in the same `mcpServers` shape Claude, Cursor and VS Code already
+write, so a block can be pasted across rather than translated. VS Code's `servers` spelling is read too, and
+whichever key the file already uses is the one a write goes back into.
+
+```jsonc
+{
+  "mcpServers": {
+    "github":   { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
+    "linear":   { "url": "https://mcp.linear.app/sse" },
+    "internal": { "url": "https://…/mcp", "headers": { "x-api-key": "…" } },
+    "old":      { "command": "x", "disabled": true }
+  }
+}
+```
+
+A `url` is an http server; anything else is a command with its argv. `env` passes variables to a stdio
+server, `headers` goes on every http request (a server behind a static token needs nothing else), and
+`disabled: true` keeps an entry without connecting it.
+
+From the prompt:
+
+```
+/mcp                      what is declared, what connected, and how many tools each gave
+/mcp <name>               the tools that one server published
+/mcp add <name> <command> [args…]
+/mcp add <name> <https://…>
+/mcp remove <name>
+/mcp login <name>         OAuth, in the browser
+/mcp logout <name>        forget the token, leaving the server declared
+/mcp reload               reopen this session so the file takes effect
+```
+
+**A server added now is not reachable until the session reloads.** The tool allowlist is fixed when the
+session is created, so `add`, `remove`, `login` and `logout` all reload by themselves — a session that has
+said nothing yet has nothing on disk to reopen, and says so. If you edit `mcp.json` yourself, tell the user to
+run `/mcp reload`.
+
+Sign-in is discovered, not configured: the server's `401` names its resource metadata, that names the
+authorization server, and most hosted servers register a client on demand — so a url is usually the whole
+entry. For a provider that issues client ids by hand, add `"oauth": { "clientId": "…", "scope": "…" }`.
+Tokens are stored per server in `~/.akan/code/mcpAuth.json` at mode 0600, never in the repo, and refreshed
+silently; `/mcp` shows `sign-in needed` when a server wants one.
+
+## Sessions
+
+Stored under `.akan/code/sessions` — project history, so a second checkout of the same repo has its own.
+
+- `←` at the start of the prompt lists past sessions; enter reopens the chosen one.
+- `akan code --resume <id>` (`-R`) reopens one from the shell.
+- `/fork [name]` continues the conversation twice: the copy takes over here, and the notice names the command
+  that reopens the original.
+- `/name <text>` names this one, which is what the session list is read by.
+- `/peers` lists other `akan code` sessions running in this workspace; `/msg <peer> <text>` hands one a
+  message.
+- `/clear` wipes the screen and keeps the conversation; `/compact [notes]` shortens what the model carries.
+
+## Model, effort, keys
+
+- `/model <provider>/<id>`, e.g. `/model deepseek/deepseek-v4-pro`. `/effort <level>` for how hard it thinks.
+- A provider is authorized by **`<PROVIDER>_API_KEY`** — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`. The
+  workspace's own `.env` is read as well as the environment, and a key found there is used for the run and
+  never copied anywhere.
+- Credentials and the model catalogue live in `~/.akan/code/` (`auth.json`, `models.json`). **`AKAN_CODE_HOME`
+  moves the whole directory** — for a container with no home, or a checkout that wants its own.
+
+## What the agent reads, and how to change it
+
+- Every `AGENTS.md` / `CLAUDE.md` from the workspace root down to the working directory, `.cursorrules`, and
+  any `.cursor/rules/*.mdc` that applies unconditionally (`alwaysApply: true`, or no frontmatter at all).
+  Edit those to change how this agent behaves in this repo — they are the files the editor beside it reads.
+- Skills: drop a `<name>/SKILL.md` into `.akan/code/skills`. Extensions: `.akan/code/extensions`. Neither is
+  read from a home directory, so a session behaves the same in two checkouts.
+
+## Keys
+
+```
+enter send · shift+enter newline · ↑↓ move (history at the edges) · ←→ move
+esc interrupt · pgup/pgdn scroll · ^c quit · tab completes a slash command
+@ completes a file in this repo · wheel scrolls the transcript (hold shift to select text instead)
+cmd+v attaches an image from the clipboard · ^v does too, without the terminal in the way
+```
+
+Most terminals send the same byte for enter and shift+enter, so the key only arrives where the terminal can
+say which was pressed. In VS Code, bind it with `workbench.action.terminal.sendSequence` and a `text` of
+`"\\\u001b\r"`; iTerm2 calls the same thing "Send Text". Either spelling of that sequence works here, and
+the backslash a shell would read as a line continuation never reaches the prompt.
+
+## Starting it
+
+```
+akan code                       open the session
+akan code "<prompt>"            run one turn and print the answer
+akan code -i "<prompt>"         open the session with the prompt already sent
+--app <name>                    narrow the agent to one app
+--profile local|pod|review|web  what it may do (default local)
+--model <provider>/<id>         --thinking, --json, --rpc, --resume <id>
+```
+
+`review` reads and never writes, loads no project context files, and keeps no session on disk. `pod` has
+nobody in front of it: it cannot ask a question. MCP is off in both.
+
+## The rest of the commands
+
+`/help` prints all of this list · `/tools` what this session can call · `/agents` what a sub-agent may be and
+what one may spend · `/thinking` shows or folds the reasoning · `/abort` stops the running turn · `/quit`.

package/codeAgent/skills/akan-module/SKILL.md

@@ -41,5 +41,5 @@ module. Collection-level helpers go `static` on the full model.
 - Read the module's `<module>.abstract.md` before changing it, and update it when an invariant or workflow
   changes — not for formatting.
 
-Deeper detail per layer is a `get_guideline` call away: `moduleOverview`, `moduleCodegen`, `modelConstant`,
-`modelDocument`, `modelService`, `modelSignal`, `modelStore`, `modelDictionary`.
+Deeper detail per layer is a `get_guideline` call away: `moduleOverview`, `modelConstant`, `modelDocument`,
+`modelService`, `modelSignal`, `modelStore`, `modelDictionary`.

package/codeAgent/skills/akan-store/SKILL.md

@@ -37,14 +37,18 @@ Only what the generated set does not cover: extra client state, a multi-step or
 calls to the non-CRUD endpoints you added in the signal. Each is an `async` method using `this.set(...)` /
 `this.get()` / `this.pick(...)`.
 
+To reach another store, cast `this`: `import type { RootStore } from "../st"`, then
+`(this as unknown as RootStore).logout()` to call its action or `(this as unknown as RootStore).set({ … })` /
+`.get()` to write or read its state. Every store is mixed into one root at runtime, so the cast only tells the
+type what `this` already is. Keep it `import type` — `st.ts` imports every store, so a value import is a cycle.
+
 A store that needs none of this stays empty. `store(sig.comment, () => ({}))` with an empty body is the
 correct, complete result — an empty store is not an unfinished one.
 
-## Two rules the linter enforces
+## The rule the linter enforces
 
 - **An action returns nothing.** Every method dispatches through `st.do.<action>()` and is typed `void`, so a
   returned value is unreachable. Write it into state with `this.set({ … })`.
-- **Never `import type { RootStore } from "../st"`** — it crashes `akan build` with a Bun SSR segfault.
 
 ## From UI
 

package/codeAgent/tools/AkanCodePlugins.ts

@@ -1,5 +1,5 @@
 import type { InlineExtension } from "@earendil-works/pi-coding-agent";
-import type { CodeAgentMcpStatus, CodeAgentProfile, CodeAgentSubagent } from "akanjs/common";
+import type { CodeAgentMcpStatus, CodeAgentProfile, CodeAgentQuestion, CodeAgentSubagent } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
 import type { CodeMailbox } from "../agent/CodeMailbox";
 import { SubagentPool } from "../agent/SubagentPool";
@@ -9,6 +9,7 @@ import { PreviewView } from "../feedback/PreviewView";
 import { TurnFeedback, type TurnFeedbackSource } from "../feedback/TurnFeedback";
 import { VerifyFeedback } from "../feedback/VerifyFeedback";
 import { AkanToolPack } from "./AkanToolPack";
+import { AskToolPack } from "./AskToolPack";
 import { MailToolPack } from "./MailToolPack";
 import { McpToolPack } from "./McpToolPack";
 import { SessionToolPack } from "./SessionToolPack";
@@ -29,6 +30,8 @@ export interface AkanCodePluginsOptions {
   mailbox: () => CodeMailbox | undefined;
   onNotice?: (message: string) => void;
   onAgents?: (agents: CodeAgentSubagent[]) => void;
+  /** How `ask_user` reaches the person. Absent on a host that has nobody to reach. */
+  onAsk?: (question: Omit<CodeAgentQuestion, "questionId">) => Promise<string | undefined>;
 }
 
 /**
@@ -67,10 +70,21 @@ export class AkanCodePlugins {
     const sessionExtension = sessions.extension();
     const mail = new MailToolPack({ profile: options.profile, mailbox: options.mailbox });
     const mailExtension = mail.extension();
+    const onAsk = options.onAsk;
+    const ask = onAsk ? new AskToolPack({ profile: options.profile, ask: onAsk }) : undefined;
+    const askExtension = ask?.extension();
     if (!options.profile.tools.akan)
       return {
-        extensions: [mcp?.extension(), webExtension, sessionExtension, mailExtension].filter((entry) => !!entry),
-        toolNames: [...(mcp?.toolNames ?? []), ...web.names(), ...sessions.names(), ...mail.names()],
+        extensions: [mcp?.extension(), webExtension, sessionExtension, mailExtension, askExtension].filter(
+          (entry) => !!entry,
+        ),
+        toolNames: [
+          ...(mcp?.toolNames ?? []),
+          ...web.names(),
+          ...sessions.names(),
+          ...mail.names(),
+          ...(ask?.names() ?? []),
+        ],
         mcp: mcpStatus,
         dispose,
       };
@@ -102,6 +116,7 @@ export class AkanCodePlugins {
     if (webExtension) extensions.push(webExtension);
     if (sessionExtension) extensions.push(sessionExtension);
     if (mailExtension) extensions.push(mailExtension);
+    if (askExtension) extensions.push(askExtension);
     return {
       extensions,
       toolNames: [
@@ -111,6 +126,7 @@ export class AkanCodePlugins {
         ...web.names(),
         ...sessions.names(),
         ...mail.names(),
+        ...(ask?.names() ?? []),
       ],
       mcp: mcpStatus,
       dispose,