@akanjs/cli 3.0.0-alpha.87 → 3.0.0-alpha.89

package/devTui-2xf0meaq.js

@@ -0,0 +1,552 @@
+// @bun
+import {
+  openBrowser
+} from "./index-d61rcfa2.js";
+
+// pkgs/@akanjs/cli/application/devTui.tsx
+import { render } from "ink";
+
+// pkgs/@akanjs/cli/ui/DevTuiApp.tsx
+import { Box, Text, useInput } from "ink";
+import { useEffect, useState } from "react";
+import { jsxDEV } from "react/jsx-dev-runtime";
+var stateGlyph = {
+  starting: { glyph: "\u25D0", color: "yellow" },
+  ready: { glyph: "\u25CF", color: "green" },
+  restarting: { glyph: "\u25D0", color: "yellow" },
+  recovering: { glyph: "\u25D0", color: "yellow" },
+  suspended: { glyph: "\u25CC", color: "blue" },
+  failed: { glyph: "\u2717", color: "red" },
+  stopped: { glyph: "\u25CB", color: "gray" }
+};
+var Rail = ({ rows, selected, readyCount, appCount, width, height }) => /* @__PURE__ */ jsxDEV(Box, {
+  flexDirection: "column",
+  width,
+  height,
+  borderStyle: "round",
+  borderColor: "gray",
+  paddingX: 1,
+  children: [
+    /* @__PURE__ */ jsxDEV(Text, {
+      dimColor: true,
+      children: [
+        "apps ",
+        readyCount,
+        "/",
+        appCount
+      ]
+    }, undefined, true, undefined, this),
+    /* @__PURE__ */ jsxDEV(Box, {
+      flexDirection: "column",
+      flexGrow: 1,
+      children: rows.map((row, idx) => {
+        const marker = row.state ? stateGlyph[row.state] : null;
+        return /* @__PURE__ */ jsxDEV(Text, {
+          inverse: idx === selected,
+          wrap: "truncate",
+          children: [
+            marker ? /* @__PURE__ */ jsxDEV(Text, {
+              color: marker.color,
+              children: marker.glyph
+            }, undefined, false, undefined, this) : /* @__PURE__ */ jsxDEV(Text, {
+              dimColor: true,
+              children: "\u25C7"
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV(Text, {
+              dimColor: true,
+              children: " ".repeat(row.depth * 2 + 1)
+            }, undefined, false, undefined, this),
+            row.appIndex === null ? null : /* @__PURE__ */ jsxDEV(Text, {
+              dimColor: true,
+              children: `${row.appIndex} `
+            }, undefined, false, undefined, this),
+            row.label,
+            row.port === null ? null : /* @__PURE__ */ jsxDEV(Text, {
+              dimColor: true,
+              children: ` ${row.port}`
+            }, undefined, false, undefined, this)
+          ]
+        }, `${row.app ?? "*"}/${row.source ?? "*"}`, true, undefined, this);
+      })
+    }, undefined, false, undefined, this)
+  ]
+}, undefined, true, undefined, this);
+var LogPane = ({ lines, title, above, below, following, prefix, prefixWidth, width, height }) => /* @__PURE__ */ jsxDEV(Box, {
+  flexDirection: "column",
+  width,
+  height,
+  borderStyle: "round",
+  borderColor: following ? "gray" : "cyan",
+  paddingX: 1,
+  children: [
+    /* @__PURE__ */ jsxDEV(Text, {
+      wrap: "truncate",
+      children: [
+        title,
+        following ? null : /* @__PURE__ */ jsxDEV(Text, {
+          color: "cyan",
+          children: `  \u25B2${above} \u25BC${below} paused`
+        }, undefined, false, undefined, this)
+      ]
+    }, undefined, true, undefined, this),
+    /* @__PURE__ */ jsxDEV(Box, {
+      flexDirection: "column",
+      flexGrow: 1,
+      children: lines.map((line) => /* @__PURE__ */ jsxDEV(Text, {
+        wrap: "truncate",
+        children: [
+          prefix === "none" ? null : /* @__PURE__ */ jsxDEV(Text, {
+            dimColor: true,
+            children: `${(prefix === "app" ? line.app : line.source).padEnd(prefixWidth)} \u2502 `
+          }, undefined, false, undefined, this),
+          line.text
+        ]
+      }, line.seq, true, undefined, this))
+    }, undefined, false, undefined, this)
+  ]
+}, undefined, true, undefined, this);
+var DevTuiApp = ({ actions }) => {
+  const [snapshot, setSnapshot] = useState(actions.snapshot);
+  useEffect(() => {
+    const unsubscribe = actions.subscribe(() => setSnapshot(actions.snapshot()));
+    setSnapshot(actions.snapshot());
+    return unsubscribe;
+  }, [actions]);
+  useInput((input, key) => {
+    if (snapshot.editingGrep) {
+      if (key.escape) {
+        actions.setGrep("");
+        actions.setEditingGrep(false);
+      } else if (key.return)
+        actions.setEditingGrep(false);
+      else if (key.backspace || key.delete)
+        actions.setGrep(snapshot.grep.slice(0, -1));
+      else if (input && !key.ctrl && !key.meta)
+        actions.setGrep(snapshot.grep + input);
+      return;
+    }
+    const page = Math.max(1, snapshot.logRows - 1);
+    if (input === "q" || key.ctrl && input === "c")
+      actions.quit();
+    else if (key.upArrow)
+      actions.scroll(key.shift ? -page : -1);
+    else if (key.downArrow)
+      actions.scroll(key.shift ? page : 1);
+    else if (key.pageUp)
+      actions.scroll(-page);
+    else if (key.pageDown)
+      actions.scroll(page);
+    else if (input === "G" || input === "f")
+      actions.follow();
+    else if (key.tab)
+      actions.moveSelection(key.shift ? -1 : 1);
+    else if (input === "/")
+      actions.setEditingGrep(true);
+    else if (input === "e")
+      actions.toggleErrorsOnly();
+    else if (input === "c")
+      actions.clear();
+    else if (input === "o")
+      actions.openSelected();
+    else if (input === "r")
+      actions.restartSelected();
+    else if (/^[1-9]$/.test(input))
+      actions.selectApp(Number(input) - 1);
+  });
+  return /* @__PURE__ */ jsxDEV(Box, {
+    flexDirection: "column",
+    width: snapshot.columns,
+    height: snapshot.terminalRows,
+    children: [
+      /* @__PURE__ */ jsxDEV(Box, {
+        flexDirection: "row",
+        height: snapshot.bodyHeight,
+        children: [
+          /* @__PURE__ */ jsxDEV(Rail, {
+            rows: snapshot.rows,
+            selected: snapshot.selected,
+            readyCount: snapshot.readyCount,
+            appCount: snapshot.appCount,
+            width: snapshot.railWidth,
+            height: snapshot.bodyHeight
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV(LogPane, {
+            lines: snapshot.lines,
+            title: snapshot.title,
+            above: snapshot.above,
+            below: snapshot.below,
+            following: snapshot.following,
+            prefix: snapshot.prefix,
+            prefixWidth: snapshot.prefixWidth,
+            width: Math.max(20, snapshot.columns - snapshot.railWidth),
+            height: snapshot.bodyHeight
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      snapshot.editingGrep ? /* @__PURE__ */ jsxDEV(Text, {
+        children: [
+          /* @__PURE__ */ jsxDEV(Text, {
+            color: "cyan",
+            children: "grep "
+          }, undefined, false, undefined, this),
+          snapshot.grep,
+          /* @__PURE__ */ jsxDEV(Text, {
+            inverse: true,
+            children: " "
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV(Text, {
+            dimColor: true,
+            children: " enter to apply \xB7 esc to clear"
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this) : /* @__PURE__ */ jsxDEV(Text, {
+        dimColor: true,
+        wrap: "truncate",
+        children: `Tab next \xB7 1-9 app \xB7 \u2191\u2193 scroll (shift page) \xB7 G follow${snapshot.following ? "" : " (paused)"} \xB7 / grep${snapshot.grep ? ` (${snapshot.grep})` : ""} \xB7 e errors${snapshot.errorsOnly ? " on" : ""} \xB7 c clear \xB7 o open \xB7 r restart \xB7 q quit`
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+};
+
+// pkgs/@akanjs/cli/application/devLogBuffer.ts
+var ansi = new RegExp(`${String.fromCharCode(27)}(?:[@-Z\\\\-_]|\\[[\\s\\S]*?[@-~])`, "g");
+var stripAnsi = (text) => text.replace(ansi, "");
+var HOST_SOURCE = "host";
+var childPrefix = /^\[child:(\d+) ([a-z-]+)\] \[(?:stdout|stderr)\] /;
+var sourceOf = (text) => {
+  const match = childPrefix.exec(text);
+  return match ? `#${match[1]} ${match[2]}` : HOST_SOURCE;
+};
+
+class DevLogBuffer {
+  static defaultLimit = 5000;
+  #limit;
+  #lines = [];
+  #partial = new Map;
+  #sources = new Map;
+  #seq = 0;
+  constructor({ limit = DevLogBuffer.defaultLimit } = {}) {
+    this.#limit = Math.max(1, limit);
+  }
+  get size() {
+    return this.#lines.length;
+  }
+  sourcesOf(app) {
+    return [...this.#sources.get(app) ?? []];
+  }
+  push(app, kind, chunk) {
+    const key = `${app}:${kind}`;
+    const parts = `${this.#partial.get(key) ?? ""}${chunk}`.split(`
+`);
+    this.#partial.set(key, parts.pop() ?? "");
+    return this.#append(app, kind, parts);
+  }
+  flushPartials() {
+    const flushed = [];
+    for (const [key, remainder] of [...this.#partial]) {
+      this.#partial.set(key, "");
+      if (!remainder)
+        continue;
+      const split = key.lastIndexOf(":");
+      const app = key.slice(0, split);
+      const kind = key.slice(split + 1) === "stderr" ? "stderr" : "stdout";
+      flushed.push(...this.#append(app, kind, [remainder]));
+    }
+    return flushed;
+  }
+  select({ app = null, source = null, grep, errorsOnly = false } = {}) {
+    const needle = grep?.trim().toLowerCase();
+    return this.#lines.filter((line) => {
+      if (app !== null && line.app !== app)
+        return false;
+      if (source !== null && line.source !== source)
+        return false;
+      if (errorsOnly && line.kind !== "stderr")
+        return false;
+      if (needle && !stripAnsi(line.text).toLowerCase().includes(needle))
+        return false;
+      return true;
+    });
+  }
+  clear(app = null) {
+    const kept = app === null ? [] : this.#lines.filter((line) => line.app !== app);
+    this.#lines.length = 0;
+    this.#lines.push(...kept);
+  }
+  #append(app, kind, texts) {
+    const known = this.#sources.get(app) ?? new Set;
+    this.#sources.set(app, known);
+    const added = texts.map((text) => {
+      const source = sourceOf(text);
+      known.add(source);
+      return { seq: ++this.#seq, app, source, kind, text };
+    });
+    this.#lines.push(...added);
+    if (this.#lines.length > this.#limit)
+      this.#lines.splice(0, this.#lines.length - this.#limit);
+    return added;
+  }
+}
+
+// pkgs/@akanjs/cli/application/devLogWindow.ts
+var windowOf = (lines, rows, anchor) => {
+  const height = Math.max(1, Math.trunc(rows));
+  const end = anchor === null ? lines.length : endOf(lines, height, anchor);
+  const start = Math.max(0, end - height);
+  return {
+    lines: lines.slice(start, end),
+    above: start,
+    below: lines.length - end,
+    following: anchor === null
+  };
+};
+var scrollAnchor = (lines, rows, anchor, delta) => {
+  const height = Math.max(1, Math.trunc(rows));
+  if (lines.length <= height)
+    return null;
+  const end = anchor === null ? lines.length : endOf(lines, height, anchor);
+  const next = Math.min(lines.length, Math.max(height, end + Math.trunc(delta)));
+  if (next >= lines.length)
+    return null;
+  return lines[next - 1]?.seq ?? null;
+};
+var endOf = (lines, height, anchor) => {
+  for (let idx = lines.length - 1;idx >= 0; idx -= 1) {
+    const line = lines[idx];
+    if (line && line.seq <= anchor)
+      return idx + 1;
+  }
+  return Math.min(lines.length, height);
+};
+
+// pkgs/@akanjs/cli/application/devTui.tsx
+import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
+
+class DevTui {
+  static frameMs = 34;
+  static footerRows = 1;
+  static paneChromeRows = 3;
+  #buffer = new DevLogBuffer;
+  #listeners = new Set;
+  #supervisor;
+  #instance;
+  #statuses = [];
+  #target = { app: null, source: null };
+  #anchor = null;
+  #grep = "";
+  #editingGrep = false;
+  #errorsOnly = false;
+  #frameTimer = null;
+  #cachedSnapshot = null;
+  constructor(supervisor) {
+    this.#supervisor = supervisor;
+    this.#statuses = supervisor.statuses;
+    process.stdout.on("resize", this.#onResize);
+    this.#instance = render(/* @__PURE__ */ jsxDEV2(DevTuiApp, {
+      actions: {
+        subscribe: this.#subscribe,
+        snapshot: this.#snapshot,
+        moveSelection: this.#moveSelection,
+        selectApp: this.#selectApp,
+        scroll: this.#scroll,
+        follow: this.#follow,
+        setGrep: this.#setGrep,
+        setEditingGrep: this.#setEditingGrep,
+        toggleErrorsOnly: this.#toggleErrorsOnly,
+        clear: this.#clear,
+        openSelected: this.#openSelected,
+        restartSelected: this.#restartSelected,
+        quit: this.#quit
+      }
+    }, undefined, false, undefined, this), { patchConsole: false });
+  }
+  onOutput = (app, kind, text) => {
+    this.#buffer.push(app, kind, text);
+    this.#scheduleFrame();
+  };
+  onStatus = (statuses) => {
+    this.#statuses = statuses;
+    this.#scheduleFrame();
+  };
+  onNote = (text, level) => {
+    this.#buffer.push("akan", level === "warn" ? "stderr" : "stdout", `${text}
+`);
+    this.#scheduleFrame();
+  };
+  waitForExit = async () => {
+    await this.#instance.waitUntilExit();
+  };
+  close = () => {
+    if (this.#frameTimer)
+      clearTimeout(this.#frameTimer);
+    this.#frameTimer = null;
+    process.stdout.off("resize", this.#onResize);
+    this.#instance.unmount();
+    for (const line of this.#buffer.flushPartials())
+      process.stdout.write(`${line.app} \u2502 ${line.text}
+`);
+    for (const status of this.#statuses)
+      process.stdout.write(`${status.name} ${status.url} \u2014 ${status.state}
+`);
+  };
+  #subscribe = (listener) => {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  };
+  #railRows() {
+    const rows = [
+      { app: null, source: null, label: "all apps", state: null, port: null, depth: 0, appIndex: null }
+    ];
+    this.#statuses.forEach((status, idx) => {
+      rows.push({
+        app: status.name,
+        source: null,
+        label: status.name,
+        state: status.state,
+        port: status.port,
+        depth: 0,
+        appIndex: idx < 9 ? idx + 1 : null
+      });
+      if (status.name !== this.#target.app)
+        return;
+      for (const source of this.#buffer.sourcesOf(status.name))
+        rows.push({ app: status.name, source, label: source, state: null, port: null, depth: 1, appIndex: null });
+    });
+    return rows;
+  }
+  #indexOfTarget(rows) {
+    const found = rows.findIndex((row) => row.app === this.#target.app && row.source === this.#target.source);
+    return found < 0 ? 0 : found;
+  }
+  #filtered(target) {
+    return this.#buffer.select({
+      app: target.app ?? null,
+      source: target.source ?? null,
+      grep: this.#grep,
+      errorsOnly: this.#errorsOnly
+    });
+  }
+  #snapshot = () => {
+    if (this.#cachedSnapshot)
+      return this.#cachedSnapshot;
+    const terminalRows = Math.max(8, process.stdout.rows ?? 24);
+    const columns = Math.max(40, process.stdout.columns ?? 80);
+    const bodyHeight = Math.max(DevTui.paneChromeRows + 1, terminalRows - DevTui.footerRows);
+    const logRows = Math.max(1, bodyHeight - DevTui.paneChromeRows);
+    const rows = this.#railRows();
+    const view = windowOf(this.#filtered(this.#target), logRows, this.#anchor);
+    const status = this.#statuses.find((candidate) => candidate.name === this.#target.app);
+    const railLabelWidth = rows.reduce((max, row) => Math.max(max, row.label.length + row.depth * 2), 0);
+    this.#cachedSnapshot = {
+      rows,
+      selected: this.#indexOfTarget(rows),
+      title: status ? `${status.name}${this.#target.source ? ` \xB7 ${this.#target.source}` : ""} \xB7 ${status.url} \xB7 ${status.state}${status.detail ? ` (${status.detail})` : ""}` : "all apps",
+      lines: view.lines,
+      above: view.above,
+      below: view.below,
+      following: view.following,
+      prefix: this.#target.app === null ? "app" : this.#target.source === null ? "source" : "none",
+      prefixWidth: this.#target.app === null ? this.#appWidth() : this.#sourceWidth(),
+      grep: this.#grep,
+      errorsOnly: this.#errorsOnly,
+      editingGrep: this.#editingGrep,
+      readyCount: this.#statuses.filter((candidate) => candidate.state === "ready").length,
+      appCount: this.#statuses.length,
+      logRows,
+      bodyHeight,
+      railWidth: Math.min(34, Math.max(20, railLabelWidth + 10)),
+      columns,
+      terminalRows
+    };
+    return this.#cachedSnapshot;
+  };
+  #appWidth() {
+    return this.#statuses.reduce((max, status) => Math.max(max, status.name.length), 0);
+  }
+  #sourceWidth() {
+    let width = HOST_SOURCE.length;
+    for (const status of this.#statuses)
+      for (const source of this.#buffer.sourcesOf(status.name))
+        width = Math.max(width, source.length);
+    return width;
+  }
+  #scheduleFrame() {
+    if (this.#frameTimer)
+      return;
+    this.#frameTimer = setTimeout(() => {
+      this.#frameTimer = null;
+      this.#renderNow();
+    }, DevTui.frameMs);
+  }
+  #renderNow() {
+    this.#cachedSnapshot = null;
+    for (const listener of this.#listeners)
+      listener();
+  }
+  #onResize = () => this.#renderNow();
+  #moveSelection = (delta) => {
+    const rows = this.#railRows();
+    const next = ((this.#indexOfTarget(rows) + delta) % rows.length + rows.length) % rows.length;
+    const row = rows[next];
+    if (row)
+      this.#setTarget({ app: row.app, source: row.source });
+  };
+  #selectApp = (index) => {
+    const status = this.#statuses[index];
+    if (status)
+      this.#setTarget({ app: status.name, source: null });
+  };
+  #setTarget(target) {
+    this.#target = { app: target.app ?? null, source: target.source ?? null };
+    this.#anchor = null;
+    this.#renderNow();
+  }
+  #scroll = (delta) => {
+    this.#anchor = scrollAnchor(this.#filtered(this.#target), this.#snapshot().logRows, this.#anchor, delta);
+    this.#renderNow();
+  };
+  #follow = () => {
+    this.#anchor = null;
+    this.#renderNow();
+  };
+  #setGrep = (grep) => {
+    this.#grep = grep;
+    this.#anchor = null;
+    this.#renderNow();
+  };
+  #setEditingGrep = (editing) => {
+    this.#editingGrep = editing;
+    this.#renderNow();
+  };
+  #toggleErrorsOnly = () => {
+    this.#errorsOnly = !this.#errorsOnly;
+    this.#anchor = null;
+    this.#renderNow();
+  };
+  #clear = () => {
+    this.#buffer.clear(this.#target.app ?? null);
+    this.#anchor = null;
+    this.#renderNow();
+  };
+  #openSelected = () => {
+    const status = this.#selectedStatus();
+    if (status)
+      openBrowser(status.url);
+  };
+  #restartSelected = () => {
+    const status = this.#selectedStatus();
+    if (status)
+      this.#supervisor.restart(status.name);
+  };
+  #selectedStatus() {
+    return this.#statuses.find((candidate) => candidate.name === this.#target.app);
+  }
+  #quit = () => {
+    this.#instance.unmount();
+  };
+}
+export {
+  DevTui
+};

package/devTuiView-7jy8f30g.js

@@ -0,0 +1,9 @@
+// @bun
+// pkgs/@akanjs/cli/application/devTuiView.ts
+var createDevTuiView = async (supervisor) => {
+  const { DevTui } = await import("./devTui-2xf0meaq.js");
+  return new DevTui(supervisor);
+};
+export {
+  createDevTuiView
+};

package/{guideline.command-w6ddv13r.js → guideline.command-f38x8jhw.js}

@@ -4,11 +4,11 @@ import {
   runner,
   script,
   command
-} from "./index-ft1sfjz0.js";
-import"./index-k1n0h7dk.js";
+} from "./index-cezy7yb3.js";
 import {
   FileSys
-} from "./index-ayy5ecax.js";
+} from "./index-q0y2jq9j.js";
+import"./index-q8sn827n.js";
 import {
   getDirname2
 } from "./index-6wwzs1bc.js";
@@ -17,7 +17,7 @@ import {
 } from "./index-h7yw2z9n.js";
 import {
   AiSession
-} from "./index-wet2ytnr.js";
+} from "./index-n85fer99.js";
 
 // pkgs/@akanjs/cli/guideline/guideline.script.ts
 import { Logger } from "akanjs/common";

package/guidelines/agentRule/agentRule.instruction.md

@@ -46,7 +46,7 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   already titles, and `defaultDraft` opens the composer with text in it without sending it. A panel driven by a
   controlled `open` with **no** `onOpenChange` draws no close button at all rather than an inert one. Then the
   slots: `AgentLauncher`, `AgentBubble`, `AgentComposer`, `AgentApproval`,
-  `AgentQuestion`, `AgentMenu`, `AgentMarkdown` and `AgentCode` each replace one part in `_overrides.tsx`, and
+  `AgentQuestion`, `AgentQueued`, `AgentMenu`, `AgentMarkdown` and `AgentCode` each replace one part in `_overrides.tsx`, and
   `akanjs/ui` exports every default beside them (`DefaultBubble`, `DefaultComposer`, …) so a skin composes the
   one it is replacing. `AgentCode` is where a highlighter binds — the fence's language reaches it — and a
   replacement for `AgentBubble` carries its own `memo`, since the transcript re-renders on every delta. Only then
@@ -59,6 +59,14 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   it scrolls. The vertical arrows still walk what was sent, but only from the first or last line — anywhere else
   the caret is the textarea's own. On a phone the panel is the whole screen (it is a card from `sm:` up) and it
   lifts above the on-screen keyboard, which only `visualViewport` reports.
+  **Enter during a running turn parks the message and sends it the moment the turn ends** — the Queue button
+  beside Stop does the same, and the placeholder says so. One slot, not a list: a second send joins the first on
+  a new line, so the model is handed one user message. The card above the composer (`AgentQueued`) shows what is
+  waiting with two ways out — ✎ takes it back into the composer, ahead of whatever was typed since, and ✕ drops it.
+  **Stop hands a parked message back to the composer rather than opening the next turn with it**, so Stop means
+  stop; `/new` drops it along with the conversation it was written for, the way it drops staged files. A `/prompt`
+  parks like text and runs when its turn comes; the built-ins (`/new`, `/copy`, …) never park, and a question the
+  agent is waiting on still takes the composer as its answer.
 - **The LLM is configured in `option.ts`, never through the environment.** `option.setLlm({ apiKey, model, host })`
   — or `setLlm((options) => …)` to read the key out of the app's own env object, which is where a secret belongs —
   fills whichever adaptor holds `LlmAdaptorRole`, reaching it as the `llmOption` use. The settings are the role's

package/guidelines/conventions/conventions.instruction.md

@@ -302,6 +302,14 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   The RSC worker is always its own process (`--conditions react-server`). A solo process answers
   `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` in the gateway's own shape, and owns the
   rotating log file; nothing supervises it but the orchestrator's probes.
+- **Route prefixes move together or not at all.** `new AkanApp({ prefix, websocketPrefix })` in `main.ts` moves
+  the server's routes, the gateway's websocket upgrade and — through the SSR bootstrap script — the
+  `fetchClient` in every tab the server renders. A prebuilt CSR shell or a Capacitor bundle is never rendered by
+  a server, so `api: { prefix, websocketPrefix }` in `akan.config.ts` is what those follow; declare it there too
+  when the app ships either. Read the value with `getApiPrefix()` / `getWsPrefix()` from `akanjs/base` — never
+  write `/api` or `/ws` as a literal, and never try to hand it down as a React prop: `FetchClient` fixes its
+  origin before the first component renders. A blank prefix, a bare `/`, and one that shadows a basePath are all
+  refused.
 - **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`, not the barrel** — the barrel re-exports
   `AkanServer`, whose graph the gateway never runs. Keep entrypoint imports at the leaf.
 - **Every `Logger` call builds a `LogRecord`** carrying `traceId`, `endpoint` and `origin` alongside the message,
@@ -338,6 +346,15 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
 - Avoid hooks. `useState` is for modal-open, tab, draft-input, and drag state only — never for server data. `useEffect` must be a genuine effect such as subscribe-with-cleanup or one-shot init. Prefer `Tab` over a `useState` mode switch. `.Template.tsx` files contain zero `useState`.
 - Forms are entirely store-driven: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, the setter passed by reference. Always use `Field.*`, never a bare `<input>` for a model field. Nested rows use `st.do.writeOnX("payments.3.name", v)` plus the generated `add<Field>OnX` / `sub<Field>OnX`. **Passing the setter by reference is also what makes the framework emit `data-akan-action` / `data-akan-state`** on the control — the annotation an in-page agent, an E2E selector, and an external browser agent all read. Wrapping it in an inline arrow (`onChange={(v) => st.do.setFieldOnX(v)}`) silently drops that: a closure the caller wrote says nothing about what it does. Never hand-write a `data-akan-*` attribute.
 - Read with `st.use.*` and write with `st.do.*`. Client components do not call `fetch.*`.
+- **An edit shell recovers its own form — never persist form values yourself.** `Load.Edit`, `Model.EditModal` and
+  `Model.New` save the whole `<model>Form` as the user types and offer it back on the next open, so a modal closed
+  by accident, a route change, or a killed app costs nothing. The scope is the record id for an edit and the seed
+  plus the route for a new form, both keyed to the signed-in user, so another record or another parent never loads
+  someone else's half-finished form. A new form's draft is applied on open with a "start over" chip; an edit whose
+  record moved in the meantime is *not* applied, and asks. Turn it off with `draft={false}`, or name the scope
+  yourself with `draft="<scope>"` when the context is in neither the id nor the seed. `field.secret` and
+  `field.hidden` values are never saved. The old per-field `cache` / `cacheKey` props are deprecated and store
+  nothing — they covered five control types, keyed on the translated label, and restored over server data.
 - Static class strings stay plain strings. Reach for `cn` only for a conditional or to merge an incoming `className`, and merge the caller last: `cn("base classes", cond && "extra", className)`. `cn` comes from `akanjs/client` (token-aware tailwind-merge) and is the only class-combining function — no `clsx` (removed), no raw `twMerge` imports, no object syntax (`{ x: cond }` → `cond && "x"`).
 - Multi-slot components take extra named props (`wrapperClassName`, `bodyClassName`), never a `classNames` object.
 - Hoist enum→class lookups to a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`. Do not use `Record<...>`. Escalate the map to `webkit/` when a second module needs it.
@@ -837,6 +854,19 @@ when two shapes disagree.
 ## Application Test Commands
 
 - After changing application source code, test the app with `bun run akan start <appName>`.
+- **`akan start` takes several apps** — `akan start a,b`, `akan start a b`, `akan start all`, or no argument at
+  all for a checkbox that remembers the last pick.
+- **It opens a full-screen view by default, at any app count.** A rail of apps with the processes inside each
+  one — `host` for the dev host, gateway and RSC worker, plus a row per replica the gateway forwards — and the
+  selected one's log beside it. `Tab` walks every row and `1`-`9` jump to that app (the rail shows each
+  app's digit), `↑↓` scroll (shift for a page, `G` back to following),
+  `/` greps, `e` shows stderr only, `c` clears, `o` opens the browser, `r` restarts that app, `q` quits.
+  **`--plain` prints prefixed interleaved lines instead**, and a pipe, a redirect or an unsized terminal
+  downgrades to that on its own.
+- `--concurrency <n>` boots more than one app at a time; the default of 1 is what keeps two cold builder peaks
+  from overlapping. `--kill` frees the dev ports first — it resolves each port's listener, walks up to the top
+  of that akan dev tree and signals it, so another checkout's server or a stale orphan on the same port is
+  reclaimed. A holder that is not recognisably an akan process is reported and left alone.
 - Test production build generation with `bun run akan build <appName>`.
 - To test a built artifact locally, run it from the generated app directory with the required Akan runtime environment variables.
 

package/guidelines/modelStore/modelStore.instruction.md

@@ -21,6 +21,18 @@ Generate client state coordination for a module. Store connects generated fetch
 - Do not perform persistence logic in React components when a store action can own it.
 - Do not call private or internal signal operations from UI state.
 
+## Form Draft Recovery
+- `<model>FormDraft`, `restore<Model>FormDraft`, `discard<Model>FormDraft` and `load<Model>FormDraft` are
+  generated. Do not hand-write a draft action, and do not write `<model>Form` to browser storage yourself.
+- The draft key carries the signed-in user, derived by hashing the auth token's payload with `iat`, `exp`, `nbf`
+  and `jti` removed. **Do not put a claim that changes on every issue into the JWT.** One would rotate the key on
+  every silent token refresh, and the symptom is a form that never recovers anything: the draft was written under
+  a key nothing looks for again, and it lingers until the seven-day sweep.
+- `field.secret` and `field.hidden` values are never written to a draft, so they come back empty. That is the
+  intended trade — a user retypes a password — and is not something to work around.
+- A model whose form holds a large `field.visual` body can pass the 256KB per-draft cap, and a draft over it is
+  dropped with a warning rather than truncated.
+
 ## Review Checklist
 - The instruction points to current docs pages, not removed docs routes.
 - Generated examples use current Akan builder APIs and scanner-friendly filenames.