@akanjs/devkit 3.0.0-beta.9 → 3.0.0

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

@@ -0,0 +1,76 @@
+---
+name: akan-scaffold
+description: "Create a new module, scalar, field, mutation, slice, or UI surface — scaffold it with the akan workflow tools (plan_workflow / apply_workflow) instead of writing the files by hand."
+---
+
+# Akan scaffolding workflows (use these BEFORE writing files)
+
+Akan generates the conventional file set for you. Creating those files by hand skips the conventions, the
+generated-barrel sync, and the validation chain.
+
+## Step 0 — decide WHAT gets a module, before any tool call
+
+List the things the request says must be **stored in the database**. Those, and only those, become modules.
+Everything else is pages, sections, and props.
+
+- A page or section whose content you can write as static JSX or props is not an entity. "A self-intro page
+  with two detail pages" is pages only — no `profile` module.
+- Never invent a supporting entity (profile, category, tag, author, like) to round out a design. If one looks
+  genuinely necessary, say so in your reply and let the user decide.
+- "… plus a comment zone that saves to a database" is exactly one new module: `comment`.
+- Check what exists first (`list_modules`) and extend it when it already fits — `add-field` / `add-slice` /
+  `create-ui` beat a whole new module.
+- Build the entire request, at the smallest structure that satisfies it.
+
+Then pick the workflow that matches the intent:
+
+| The user wants… | workflow |
+| --- | --- |
+| a new database-backed entity (comment, post, todo, product …) | `create-module` |
+| a reusable embedded value object | `create-scalar` |
+| a new field on an existing module | `add-field` |
+| a new field with a closed set of values | `add-enum-field` |
+| a new state-changing action | `add-mutation` |
+| a filtered list, tab, or reusable query | `add-slice` |
+| a View / Unit / Template / Zone / Util for an existing module | `create-ui` |
+
+## The chain
+
+Each result names the next call in `next.tool`. Follow it; do not improvise.
+
+1. `plan_workflow({ workflow: "create-module", inputs: { app: "<app>", module: "comment" } })` — read-only.
+   Returns `planPath` and `next.tool=apply_workflow`. (`list_workflows` / `explain_workflow` give the names
+   and each workflow's inputs.)
+2. `apply_workflow({ planPath })` — writes the scaffold and syncs the generated barrels. Returns
+   `validationTarget`.
+3. `run_validation({ runIdOrPlan: <validationTarget> })`, or just call `akan_verify`, which runs the whole
+   chain over everything the working tree changed.
+4. **Read each scaffolded file before editing it.** They are a few lines each and they extend base classes
+   that already generated the CRUD surface. Read the `akan-store` skill before touching a store or adding
+   signal endpoints, or you will redeclare `create<Model>` and hit an "already exists" typecheck error.
+5. Now fill in: real fields in the constant, invariants in document and service, non-CRUD API in the signal,
+   extra state in the store, rendering in the UI. Filling in a scaffold is the job; creating one by hand is
+   not.
+
+## Rules
+
+- One run per unit of structure: two new entities are two `create-module` runs.
+- `requiresApproval: true` on a plan is a review signal for you, not a permission gate — read
+  `predictedChanges`, then apply.
+- Hand-writing files is the fallback, used only when no workflow matches, or when apply reports
+  unsupported / no-op / failed diagnostics telling you to act manually. Say which case applied.
+- Never hand-edit a generated file to "finish" a scaffold — use `repair_generated` or `akan sync <app>`.
+- No workflow tools this turn? The same order through bash:
+  `akan workflow list` → `akan workflow plan create-module --app <app> --module comment --format json --out <path>`
+  → `akan workflow apply <path> --format json`.
+
+## Worked example — "an intro page, two detail pages, and a comment zone with a database"
+
+0. What must be stored? Only the comments. One module, `comment`. The three pages are static content.
+1. `plan_workflow({ workflow: "create-module", inputs: { app: "<app>", module: "comment" } })`
+2. `apply_workflow({ planPath })` — `lib/comment/*` exists, barrels synced.
+3. Read the scaffolded files. Edit `comment.constant.ts` for the real shape. The store's CRUD already exists;
+   leave the store body empty unless you need extra state.
+4. Write the pages and the comment UI against the generated actions — `st.do.createComment`,
+   `st.do.initCommentInPublic`, `st.use.commentListInPublic`.
+5. `akan_verify` until clean.

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

@@ -0,0 +1,52 @@
+---
+name: akan-scalar
+description: "Create an embedded value object (scalar) under lib/__scalar/, or add a relation field to another model — including which cascade direction is which."
+---
+
+# Akan scalars and relations
+
+## Scalars
+
+A scalar is an embedded value object with no collection of its own. It lives in `lib/__scalar/<name>/`, is
+composed into models with `scalar(...)`, and its dictionary is a `scalarDictionary`. Create one with the
+`create-scalar` workflow; its UI surface is limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
+
+## Relations
+
+A reference to another model is `field(Model)`, or `field([Model])` for many. Files and images are a
+relation to the `File` model — `image: field(File).optional()` — never an `Upload` field; `Upload` is a
+signal-body primitive only. The store then generates `upload<Field>On<Model>(fileList)` for you.
+
+**Hydrated vs raw.** A server query returns a hydrated `cnst.<Model>` instance with `set` / `save` /
+`refresh`. A client `fetch` result is raw plain data with the functions stripped. Code that works in a
+service and fails in a store is usually this.
+
+**A model's `Date` fields are prototype accessors, not own properties.** `user.createdAt` is a `Dayjs` built
+on first read, so `Object.keys(user)` and `{ ...user }` do **not** include it, while `"createdAt" in user`,
+`JSON.stringify(user)` and `plainFieldsOf(user)` do. To copy a model write `new cnst.X().set(user)`, never a
+spread.
+
+## Cascade — the value names the direction, and getting it wrong loses data
+
+The two actions sit on the same field shape, so `cascade` never means "related". It means one of exactly
+these:
+
+- `removeRef` — *when I am removed, remove what this field points at.* Declared on the relation the owner
+  holds: `image: field(File, { cascade: "removeRef" })`.
+- `removeWith` — *when what this field points at is removed, remove me.* Declared on the child's own
+  reference to its owner, so the owner never learns about its children.
+
+Nothing checks whether another document still references the same target, and `File` in particular is
+deduped by `origin`, so two parents can share one row. Removal is soft, but the storage delete a
+`_postRemove` performs is not — a cascade is not restorable.
+
+Query-level removes fire no hooks and therefore no cascade: `removeManyByQuery`, the generated
+`remove<Filter>`, and the facade's `removeById`. Remove one document at a time when it cascades.
+
+## Field types
+
+Import `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `enumOf` and `dayjs` from `akanjs/base`. `String`,
+`Boolean` and `Date` are the globals. **`Number` is not a field type** — use `Int` or `Float`. There is no
+JSON scalar; use `Any`. `Binary` is wire bytes and is never a model field.
+
+Full detail: `get_guideline` with `scalarModule`, `scalarConstant`, `fieldRule`, or `queryRule`.

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

@@ -0,0 +1,34 @@
+---
+name: akan-service
+description: "Add a service module — behaviour not centred on one stored model — under lib/_<service>/, and keep its abstract current."
+---
+
+# Akan service modules
+
+Behaviour that is not centred on a single stored model lives in a **service module**: the folder is
+`lib/_<service>/` and its abstract file is `<service>.abstract.md` — the folder carries the underscore, the
+abstract drops it. Its UI surface is limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`, and its
+dictionary is a `serviceDictionary`.
+
+## Rules
+
+- Read the module's `*.abstract.md` **before** changing it — it states the invariants the code cannot show.
+  Update it when an invariant, workflow, or public behaviour changes; not for formatting or imports.
+- Keep the public surface in the signal layer and the decisions in the service.
+- Service methods stay a few lines: load → chain → `return await ….save()`. Write `return await` explicitly
+  in tail position. Side effects belong in `_preUpdate` / `_postCreate`, not inline. Fire-and-forget is
+  explicitly `void`-ed.
+- Return `null` / `false` for "not allowed" or "not found" and let the signal decide whether that is an
+  error.
+
+## Reaching other things
+
+Inside a service, in preference order: `service<srv.XService>()` for another module's service,
+`plug(AdapterClass)` for an adapter, `use<T>()` only for an `option.ts`-registered legacy singleton, and
+`env(...)` for config. Injection resolves by field name — a field named `<refName>Service` finds the service
+registered under `<refName>`, and the `Service` suffix is required.
+
+An external API or piece of infrastructure is an `adapt()` class in `srvkit/`, injected with `plug`. It
+self-registers, so do **not** add it to `lib/option.ts`.
+
+Full detail: `get_guideline` with `modelService`.

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

@@ -0,0 +1,67 @@
+---
+name: akan-store
+description: "Fill in a module store, or call module data and actions from UI — what store() already generates (CRUD, form setters, slice actions) and what belongs in your subclass."
+---
+
+# Akan store: what is already generated
+
+`class CommentStore extends store(sig.comment, () => ({ /* extra state */ })) { /* extra actions */ }`
+gives you the whole CRUD and form surface for free. **Redeclaring any of it is a typecheck error
+("already exists"), and the fix is to delete your version and call the generated one** — never rename around
+it, never cast, never reimplement.
+
+For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
+
+## Generated actions — `st.do.*`
+
+- write: `createComment(input)`, `updateComment(id, input)`, `removeComment(id)`
+- form: `newComment()`, `editComment(model)`, `writeOnComment(path, value)`, `set<Field>OnComment(value)`,
+  `add<Field>OnComment(value)` / `sub<Field>OnComment(idx)` for arrays, `upload<Field>OnComment(fileList)`
+  for file fields, `checkCommentSubmitable()`, `submitComment()`, `createCommentInForm()`,
+  `updateCommentInForm()`
+- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`
+- per slice: `initComment<Slice>(...args)`, `refreshComment<Slice>()`, `selectComment<Slice>(model)`,
+  `setPageOfComment<Slice>(page)`, `loadMoreOfComment<Slice>()`, `setLimitOfComment<Slice>(limit)`,
+  `setQueryArgsOfComment<Slice>(...)`, `setSortOfComment<Slice>(sort)`
+
+## Generated state — `st.use.*`
+
+`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentSubmit`, `commentModal`,
+`commentViewAt`, `commentOperation`; per slice `commentList<Slice>`, `commentListLoading<Slice>`,
+`commentInitList<Slice>`, `commentSelection<Slice>`, `commentInsight<Slice>`, `pageOfComment<Slice>`,
+`lastPageOfComment<Slice>`, `hasMoreOfComment<Slice>`, `limitOfComment<Slice>`, `sortOfComment<Slice>`.
+
+## What your subclass is for
+
+Only what the generated set does not cover: extra client state, a multi-step or cross-model workflow, and
+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.
+
+## 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({ … })`.
+
+## From UI
+
+Read with `st.use.commentListInPublic()`, act with `st.do.createComment(input)` / `st.do.submitComment()`.
+Do not wrap a generated action in a store method just to rename it.
+
+**Pass a form setter by reference**: `onChange={st.do.setTypeOnComment}`, never
+`onChange={(v) => st.do.setTypeOnComment(v)}`. The two run identically, but the arrow is an anonymous
+closure, so the control emits no `data-akan-action` and publishes no agent tool for the field —
+`no-unpublished-form-setter.grit` fails the build on it.
+
+## Signal side
+
+The scaffolded `slice(…, { guards: { root, get, cru } })` already exposes get / list / create / update /
+remove. Add a query or mutation only for behaviour beyond CRUD, and give it its own `guards` array — a
+custom endpoint never inherits the slice's.

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

@@ -0,0 +1,63 @@
+---
+name: akan-ui
+description: "Build Akan pages and components: the server-by-default rule, the Unit/View vs Template/Zone/Util split, forms, and what never to hand-roll."
+---
+
+# Akan UI
+
+A new View / Unit / Template / Zone / Util for an existing module comes from the `create-ui` workflow (the
+`akan-scaffold` skill). Edit the scaffolded component instead of authoring one from scratch.
+
+## The boundary is mechanical, not a judgement call
+
+| role | side | directive |
+| --- | --- | --- |
+| `<Model>.Unit.tsx`, `<Model>.View.tsx` | server | never `"use client"` |
+| `<Model>.Template.tsx`, `<Model>.Zone.tsx`, `<Model>.Util.tsx` | client | `"use client"` on line 1 |
+| `page/**` | server | never |
+
+**Server is the default and `"use client"` is a cost you justify per component.** A component earns the
+directive only by using a hook, a JSX event handler, the store, a browser global, or a client-only package.
+Rendering markup, reading a param, calling `l()`, and mapping over data are all server work. Measure with
+`akan quality ssr`; treat 50% server share as the floor and a falling share as a regression.
+
+Four moves that keep markup on the server: wrap the interaction and render `children` untouched; split a
+compound component so only the provider holds state; fetch in the route and pass the result into a `Zone` as
+an `init` prop; push the boundary down to the leaf that needs it.
+
+## Never hand-roll these
+
+- loading / empty / list states → `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`,
+  `renderView`, `renderEmpty`; `<Empty />` for a bare placeholder; `Model.New` / `Model.Edit` /
+  `Model.SureToRemove` for CRUD modals.
+- a mount-time fetch → the route calls `fetch.init<Model><Slice>(…)` before the first byte. A
+  `useEffect(…, [])` that loads data is flagged by `akan quality ssr`, and `fetch.init*` from a client file
+  fails lint outright.
+- a model field input → `Field.*`, never a bare `<input>`.
+- a mode switch → `Tab`, not a `useState`.
+
+## Component shape
+
+`export const X = ({ … }: XProps) => { return (…); };` — arrow const, block body. Never `React.FC`, never
+`defaultProps`, never `PropsWithChildren`; children are `children: ReactNode`. Declare
+`interface XProps` directly above the component with `className?: string` first.
+
+Conditional render is `cond ? <X/> : null`. **Never `{cond && <X/>}`** — in a `className` context it renders
+the literal string `"false"`.
+
+## Classes
+
+Never hand-order Tailwind classes; the formatter sorts them and its output is correct. Stay inside the
+semantic token vocabulary — `bg-primary`, `text-foreground/70` — because a raw palette class (`bg-blue-500`),
+an arbitrary colour (`bg-[#3b82f6]`), a daisyUI legacy class, and a colour literal in `style={{…}}` all
+render no CSS and fail lint. Reach for `cn` only for a conditional or to merge an incoming `className`, and
+merge the caller last.
+
+## Forms
+
+Store-driven end to end: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, **the setter passed by
+reference**. An inline arrow silently drops the control's agent annotation and fails
+`no-unpublished-form-setter.grit`. Nested rows use `st.do.writeOnX("payments.3.name", v)`.
+
+Full detail: `get_guideline` with `ssrRule`, `componentRule`, `cssRule`, `recipeRule`, or the per-role
+`modelUnit` / `modelView` / `modelZone` / `modelTemplate` / `modelUtil`.

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

@@ -0,0 +1,44 @@
+---
+name: akan-validate
+description: "Run the akan check loop after editing and fix each failure class the right way — no silencing, no lint-disable, no gaming the checker."
+---
+
+# Akan validation loop
+
+## One call does the whole chain
+
+`akan_verify` runs sync → lint → typecheck → `quality ssr` over everything the working tree has changed, in
+the right order, and reports only what failed. **Call it after editing, before you say you are done.** It
+also runs itself at the end of a turn that changed source, so a failure comes back to you either way.
+
+The same chain by hand, for the app you are editing:
+
+- `akan sync <app>` — after adding, renaming, or deleting any file. Regenerates the barrels.
+- `akan lint <app>` — fast; run after every edit. Prints up to 200 diagnostics.
+- `akan typecheck <app>` — the client/server boundary violations land here, not in lint.
+- `akan quality ssr` — only when you wrote or changed a `.tsx`. Did the server share hold?
+- `akan build <app>` — the full production build; slower, and only when the build itself is in question.
+
+Raw `tsc` misses the generated barrels and reports false errors. Do not reach for it.
+
+## Fixing rules
+
+**Apply the real fix the rule intends. Do not silence the checker.** No blanket lint-disable, no throwaway
+re-export, no export-in-place trick, no `as any`, no non-null assertion. Gaming a check is a defect, not a
+fix. When a suppression is genuinely right it carries a reason:
+`// biome-ignore lint/<rule>: <why>` — and a grit plugin diagnostic is suppressed as `lint/plugin`, not the
+bare `plugin` category Biome's own message suggests.
+
+Common classes and their real fix:
+
+| symptom | fix |
+| --- | --- |
+| a member "already exists" or conflicts with the base class | you redeclared something Akan generates, usually store CRUD. **Delete your version** and call the generated one — do not rename, cast, or suppress. See `akan-store`. |
+| `throw new Error` | a typed `Err` with a dictionary key. See `akan-err`. |
+| an edit to a generated file | regenerate instead: `akan sync <app>` or `repair_generated`. |
+| a file in the wrong place | relocate to `common/` / `webkit/` / `srvkit/` / `ui/`. Never a sibling helper `.ts` inside `lib/<model>/`. |
+| a missing dependency | declare it in the owning app or lib `package.json`. See `akan-deps`. |
+| a Tailwind class order or colour complaint | let the formatter sort; use semantic tokens. See `akan-ui`. |
+
+Re-run until clean. If a failure is genuinely outside the scope of what you changed, say so in your reply
+instead of forcing it.

package/codeAgent/tools/AkanCli.ts

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { stripAnsi } from "../../stripAnsi";
+
+export interface AkanCliResult {
+  command: string;
+  ok: boolean;
+  exitCode: number;
+  output: string;
+}
+
+// A subprocess: the akan runners print to inherited stdio and return nothing; it also isolates their crashes.
+export class AkanCli {
+  readonly #cwd: string;
+  readonly #entry: string;
+
+  constructor(cwd: string) {
+    this.#cwd = cwd;
+    this.#entry = AkanCli.#resolveEntry();
+  }
+
+  async run(args: string[], { timeoutMs = 300_000 }: { timeoutMs?: number } = {}): Promise<AkanCliResult> {
+    const proc = Bun.spawn([process.execPath, this.#entry, ...args], {
+      cwd: this.#cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+    });
+    const timer = setTimeout(() => proc.kill(), timeoutMs);
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    clearTimeout(timer);
+    // tsgo colours regardless of NO_COLOR, and escape sequences are tokens the model pays for and cannot read.
+    const output = stripAnsi(`${stdout}${stderr}`).trim();
+    return { command: `akan ${args.join(" ")}`, ok: exitCode === 0, exitCode, output };
+  }
+
+  // Bundled, import.meta.dir is the CLI's output dir with index.js beside it; Bun.main fits only when the CLI is the
+  // process. The path is written out because devkit does not depend on the CLI, and must not start.
+  static #resolveEntry() {
+    const candidates = [
+      path.join(import.meta.dir, "index.js"),
+      path.join(import.meta.dir, "..", "..", "..", "cli", "index.ts"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? Bun.main;
+  }
+}

package/codeAgent/tools/AkanCodePlugins.ts

@@ -0,0 +1,136 @@
+import type { InlineExtension } from "@earendil-works/pi-coding-agent";
+import type { CodeAgentMcpStatus, CodeAgentProfile, CodeAgentQuestion, CodeAgentSubagent } from "akanjs/common";
+import type { Workspace } from "../../commandDecorators";
+import type { CodeMailbox } from "../agent/CodeMailbox";
+import { SubagentPool, type SubagentSpend } from "../agent/SubagentPool";
+import { DevLogFeedback } from "../feedback/DevLogFeedback";
+import { PreviewFeedback } from "../feedback/PreviewFeedback";
+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";
+import { WebToolPack } from "./WebToolPack";
+
+export interface AkanCodePluginsOptions {
+  workspace: Workspace;
+  cwd: string;
+  profile: CodeAgentProfile;
+  /** Apps whose dev server should be watched, and whose page should be probed. */
+  apps: string[];
+  canSeeImages: boolean;
+  /** How many `task` levels deep the owning agent is. */
+  depth: number;
+  /** The tally of the sub-agent tree the owning agent belongs to, when a `task` opened it. */
+  subagentSpend?: SubagentSpend;
+  /** Reading the current session back would spend its own window twice, so it is excluded from search. */
+  currentSessionId: () => string;
+  /** Late, because the session this announces to its peers does not exist yet when the pack is built. */
+  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>;
+}
+
+export interface AkanCodePluginsResult {
+  extensions: InlineExtension[];
+  /** Names the session's tool allowlist has to carry, or the model is told these tools do not exist. */
+  toolNames: string[];
+  /** Every declared MCP server and what it published, including the ones that published nothing. */
+  mcp: CodeAgentMcpStatus[];
+  /** Closes anything the pack holds open — currently the MCP server connections. */
+  dispose: () => void;
+}
+
+// Gated at assembly, not at call time: a capability the profile excludes is never built and costs no prompt tokens.
+export class AkanCodePlugins {
+  static async build(options: AkanCodePluginsOptions): Promise<AkanCodePluginsResult> {
+    const mcp = await McpToolPack.connect({
+      workspaceRoot: options.workspace.workspaceRoot,
+      profile: options.profile,
+      ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+    });
+    const dispose = () => mcp?.close();
+    const mcpStatus = mcp?.status ?? [];
+    const web = new WebToolPack({ profile: options.profile });
+    const sessions = new SessionToolPack({
+      workspaceRoot: options.workspace.workspaceRoot,
+      cwd: options.cwd,
+      profile: options.profile,
+      currentSessionId: options.currentSessionId,
+    });
+    const mail = new MailToolPack({ profile: options.profile, mailbox: options.mailbox });
+    const onAsk = options.onAsk;
+    const ask = onAsk ? new AskToolPack({ profile: options.profile, ask: onAsk }) : undefined;
+    const shared = {
+      extensions: [mcp?.extension(), web.extension(), sessions.extension(), mail.extension(), ask?.extension()].filter(
+        (entry) => !!entry,
+      ),
+      toolNames: [
+        ...(mcp?.toolNames ?? []),
+        ...web.names(),
+        ...sessions.names(),
+        ...mail.names(),
+        ...(ask?.names() ?? []),
+      ],
+    };
+    if (!options.profile.tools.akan) return { ...shared, mcp: mcpStatus, dispose };
+    const readOnly = !options.profile.tools.builtin.includes("write");
+    const pack = new AkanToolPack({
+      workspace: options.workspace,
+      cwd: options.cwd,
+      mode: readOnly ? "readonly" : "apply",
+    });
+    const extensions: InlineExtension[] = [pack.extension()];
+    const subagent = SubagentPool.extensionFor({
+      workspace: options.workspace,
+      cwd: options.cwd,
+      parent: options.profile,
+      depth: options.depth,
+      ...(options.subagentSpend ? { spend: options.subagentSpend } : {}),
+      ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+      ...(options.onAgents ? { onAgents: options.onAgents } : {}),
+    });
+    if (subagent) extensions.push(subagent);
+    const sources = await AkanCodePlugins.#sources(options, readOnly);
+    if (sources.length)
+      extensions.push(
+        new TurnFeedback(sources, {
+          budget: options.profile.limits.feedback,
+          ...(options.onNotice ? { onNotice: options.onNotice } : {}),
+        }).extension(),
+      );
+    return {
+      extensions: [...extensions, ...shared.extensions],
+      toolNames: [...(await pack.names()), ...(subagent ? [SubagentPool.toolName] : []), ...shared.toolNames],
+      mcp: mcpStatus,
+      dispose,
+    };
+  }
+
+  static async #sources(options: AkanCodePluginsOptions, readOnly: boolean): Promise<TurnFeedbackSource[]> {
+    const sources: TurnFeedbackSource[] = [
+      new VerifyFeedback({ cwd: options.cwd, readOnly }),
+      new DevLogFeedback({ workspaceRoot: options.workspace.workspaceRoot, cwd: options.cwd, apps: options.apps }),
+    ];
+    const previewUrl = await AkanCodePlugins.#previewUrl(options);
+    if (!previewUrl) return sources;
+    // Said once here, or a UI turn silently skips its only visual check and reads as a clean run.
+    const reason = PreviewView.unavailableReason();
+    if (reason) options.onNotice?.(reason);
+    else sources.push(new PreviewFeedback({ cwd: options.cwd, previewUrl, canSeeImages: options.canSeeImages }));
+    return sources;
+  }
+
+  static async #previewUrl(options: AkanCodePluginsOptions) {
+    for (const app of options.apps) {
+      const url = await DevLogFeedback.previewUrl(options.workspace.workspaceRoot, app);
+      if (url) return url;
+    }
+    return undefined;
+  }
+}

package/codeAgent/tools/AkanEditScope.ts

@@ -0,0 +1,48 @@
+export interface AkanEditScopeResult {
+  paths: string[];
+  apps: string[];
+  libs: string[];
+  /** A created, deleted or renamed file under `apps/**` or `libs/**` — the only kind a barrel has to catch up with. */
+  needsSync: boolean;
+  touchesTsx: boolean;
+}
+
+const empty: AkanEditScopeResult = { paths: [], apps: [], libs: [], needsSync: false, touchesTsx: false };
+
+// Read from git, not tool events: an edit made through `bash` (a heredoc, sed, a codemod) produces no write tool call.
+export class AkanEditScope {
+  static async since(cwd: string, baseline: ReadonlySet<string>): Promise<AkanEditScopeResult> {
+    const current = await AkanEditScope.baseline(cwd);
+    const changed = [...current].filter((line) => !baseline.has(line));
+    if (!changed.length) return empty;
+    const entries = changed.map((line) => ({ code: line.slice(0, 2), file: line.slice(3).split(" -> ").at(-1) ?? "" }));
+    const paths = entries.map((entry) => entry.file).filter(Boolean);
+    return {
+      paths,
+      apps: AkanEditScope.#targets(paths, "apps"),
+      libs: AkanEditScope.#targets(paths, "libs"),
+      needsSync: entries.some((entry) => /[ARD?]/.test(entry.code) && /^(apps|libs)\//.test(entry.file)),
+      touchesTsx: paths.some((file) => file.endsWith(".tsx")),
+    };
+  }
+
+  /** The porcelain lines before a turn, so the turn is judged on what it changed rather than on a dirty tree. */
+  static async baseline(cwd: string) {
+    const proc = Bun.spawn(["git", "status", "--porcelain=v1", "--untracked-files=all"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+    return new Set(text.split("\n").filter((line) => line.trim().length > 3));
+  }
+
+  static #targets(paths: string[], root: "apps" | "libs") {
+    const names = paths
+      .filter((file) => file.startsWith(`${root}/`))
+      .map((file) => file.split("/")[1] ?? "")
+      .filter(Boolean);
+    return [...new Set(names)];
+  }
+}

package/codeAgent/tools/AkanEnvKeys.ts

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+
+// Bun auto-loads .env from the current directory only, so a run from a subdirectory sees none of the workspace's keys.
+// Applied as runtime overrides, never stored: copying a key into ~/.akan/code/auth.json gives it a second lifetime.
+export class AkanEnvKeys {
+  static async apply(runtime: ModelRuntime, workspaceRoot: string) {
+    const applied: string[] = [];
+    for (const [name, value] of AkanEnvKeys.#entries(workspaceRoot)) {
+      const provider = AkanEnvKeys.#providerOf(name);
+      if (!provider || !value) continue;
+      // Serially: the runtime's credential writes share one file, and a key written mid-write goes missing.
+      await runtime.setRuntimeApiKey(provider, value);
+      applied.push(provider);
+    }
+    return applied;
+  }
+
+  static #entries(workspaceRoot: string): [string, string][] {
+    const fromProcess = Object.entries(process.env).filter(([, value]) => typeof value === "string") as [
+      string,
+      string,
+    ][];
+    const file = path.join(workspaceRoot, ".env");
+    if (!existsSync(file)) return fromProcess;
+    const fromFile = readFileSync(file, "utf8")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#") && line.includes("="))
+      .map((line): [string, string] => {
+        const index = line.indexOf("=");
+        return [
+          line.slice(0, index).trim(),
+          line
+            .slice(index + 1)
+            .trim()
+            .replace(/^["']|["']$/g, ""),
+        ];
+      });
+    // The real environment wins: an operator exporting a key for one run should not be overridden by the file.
+    return [...fromFile, ...fromProcess];
+  }
+
+  /** `DEEPSEEK_API_KEY` names the provider `deepseek`; the engine's provider ids are lower-kebab. */
+  static #providerOf(name: string) {
+    const match = /^([A-Z0-9_]+)_API_KEY$/.exec(name);
+    return match?.[1]?.toLowerCase().replace(/_/g, "-");
+  }
+}