@akanjs/devkit 3.1.1-rc.16 → 3.1.1-rc.18

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

@@ -0,0 +1,40 @@
+---
+name: akan-transport
+description: "Guard and tune endpoints on the wire: writing a Can<Verb><Model> guard, deadlines, cache, idempotency, rate limits, server-to-server calls, body types, bytes and HTTP verbs."
+---
+
+# Akan transport
+
+## Guards
+
+- Every custom `query` / `mutation` / `pubsub` / `message` names its own `guards: [...]`; every `slice()` takes an
+  explicit guard map with `root: Admin`. `Public` belongs on a slice `get:`, and on a mutation only for an act that
+  must work signed out (sign-up, sign-in, token refresh, an OAuth route), which also declares a `rateLimit`.
+- A resource guard is a `Can<Verb><Model>` class in the model library's `srvkit/guards.ts` that fails closed:
+  no resource named, or a load that throws, is `false` (after a `logger.warn`). Admin bypass goes first.
+- Every guard declares `static scope`: `"account"` reads only the caller (`SignedIn`, `Admin`, roles), and
+  `"resource"` needs the call's arguments (every `Can<Verb><Model>`). Keep `static name = "User";` with a comment.
+- Guards read `context.get<T>("account")`, serve HTTP and websocket alike, and stay side-effect free. The acting
+  user comes from `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`, the address from `.with(Ip)` — never a
+  client-supplied id. The service re-checks ownership: two independent gates.
+
+## Endpoint options
+
+- `{ timeout: <ms> }` is the deadline on both ends; undeclared, the client quits at 30 s and the handler is not
+  cancelled.
+- `{ cache }` only on a `query` with no internal argument, capped at one day; `invalidate(endpoint, args?)` drops
+  it early through a plugged `EndpointCacheControl`.
+- `{ rateLimit: { calls, windowMs?, by? } }` per endpoint, `option.setRateLimit` per app, `plug(RateLimit)` for a
+  business key.
+- A mutation repeated under one `Idempotency-Key` header runs once and replays its first answer.
+- `{ method: "PATCH" | "PUT" | "DELETE" }` moves a mutation off `POST` — only when a foreign protocol forces it.
+- `errors: { 409: ["ticket.error.locked"] }` names the errors an endpoint throws on purpose.
+
+## Bodies and other servers
+
+- `.body()` / `.param()` take scalars, model refs or `enumOf(...)`; `Int` / `Float`, never `Number`; bytes are
+  `Binary`, never `Any`; `Upload` only in a `fileUpload: true` mutation.
+- Server to server, `fetch.clone({ origin })` opens no socket without `connect: true`, retries through `retry`,
+  and rethrows a remote `Err` as it is — never wrap or re-key it.
+
+Full detail: `get_guideline` with `transportRule`, or `mcpRule` for what a guard's scope does to an MCP listing.

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

@@ -7,17 +7,19 @@ description: "Run the akan check loop after editing and fix each failure class t
 
 ## 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.
+`akan verify` (the `akan_verify` tool in akan code) syncs, lints with fixes, typechecks, fast-builds each
+changed app, and runs the SSR check for a `.tsx` change — over everything the working tree has changed, in one
+process. It prints one line when it passes and one line per problem when it fails. **Run it after editing,
+before you say you are done.** In akan code it also runs itself at the end of a turn that changed source.
+
+Never run `akan lint`, `akan typecheck` and `akan build` in turn: that is the same work three times over, at
+three times the output. Narrow the one command instead:
+
+- `akan verify <app-or-lib-or-pkg>` — that target whole, changed or not.
+- `akan verify --lint-only` — the quick pass between edits.
+- `akan verify --no-build` — leave the app build out.
+- `akan verify --max 0` — every line, when the report ends in `+N more`.
+- `fixed N files` in the header means lint rewrote them on disk: re-read before editing them again.
 
 Raw `tsc` misses the generated barrels and reports false errors. Do not reach for it.
 

package/codeAgent/tools/AkanCli.ts

@@ -24,7 +24,8 @@ export class AkanCli {
       cwd: this.#cwd,
       stdout: "pipe",
       stderr: "pipe",
-      env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+      //? A workspace .env's AKAN_PUBLIC_LOG_LEVEL=verbose reaches the child too, and buried its error under 90 lines.
+      env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1", AKAN_LOG_STDOUT_LEVEL: "warn" },
     });
     const timer = setTimeout(() => proc.kill(), timeoutMs);
     const [stdout, stderr, exitCode] = await Promise.all([

package/codeAgent/tools/AkanEditScope.ts

@@ -2,12 +2,13 @@ export interface AkanEditScopeResult {
   paths: string[];
   apps: string[];
   libs: string[];
+  pkgs: 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 };
+const empty: AkanEditScopeResult = { paths: [], apps: [], libs: [], pkgs: [], 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 {
@@ -21,6 +22,7 @@ export class AkanEditScope {
       paths,
       apps: AkanEditScope.#targets(paths, "apps"),
       libs: AkanEditScope.#targets(paths, "libs"),
+      pkgs: AkanEditScope.#targets(paths, "pkgs"),
       needsSync: entries.some((entry) => /[ARD?]/.test(entry.code) && /^(apps|libs)\//.test(entry.file)),
       touchesTsx: paths.some((file) => file.endsWith(".tsx")),
     };
@@ -38,10 +40,13 @@ export class AkanEditScope {
     return new Set(text.split("\n").filter((line) => line.trim().length > 3));
   }
 
-  static #targets(paths: string[], root: "apps" | "libs") {
+  static #targets(paths: string[], root: "apps" | "libs" | "pkgs") {
     const names = paths
       .filter((file) => file.startsWith(`${root}/`))
-      .map((file) => file.split("/")[1] ?? "")
+      .map((file) => {
+        const [, first = "", second = ""] = file.split("/");
+        return first.startsWith("@") && second ? `${first}/${second}` : first;
+      })
       .filter(Boolean);
     return [...new Set(names)];
   }

package/codeAgent/tools/AkanToolPack.ts

@@ -1,7 +1,6 @@
 import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { Workspace } from "../../commandDecorators";
-import { AkanEditScope } from "./AkanEditScope";
 import { AkanVerifier } from "./AkanVerifier";
 
 export interface AkanToolPackOptions {
@@ -66,17 +65,12 @@ export class AkanToolPack {
       name: AkanToolPack.verifyToolName,
       label: "akan verify",
       description:
-        "Run the akan validation chain (sync, lint, typecheck, and quality ssr for .tsx changes) over everything the working tree has changed, and report what failed. Call this after editing before you finish.",
-      promptSnippet: "akan_verify: run sync/lint/typecheck/quality over the working tree's changes",
+        "Run `akan verify` over everything the working tree has changed: sync, lint (with fixes), typecheck, a fast build of each changed app, and the SSR check for .tsx changes, in one call. It prints one line when it passes and one line per problem when it fails. Call this after editing, before you finish; never run lint, typecheck or build separately.",
+      promptSnippet: "akan_verify: sync, lint, typecheck and build what the working tree changed, in one call",
       parameters: Type.Object({}),
       execute: async () => {
-        const scope = await AkanEditScope.since(this.#options.cwd, new Set());
-        const report = await verifier.verify(scope);
-        return {
-          content: [{ type: "text", text: AkanVerifier.summarize(report) }],
-          details: undefined,
-          isError: !report.ok,
-        };
+        const report = await verifier.verify();
+        return { content: [{ type: "text", text: report.text }], details: undefined, isError: !report.ok };
       },
     });
   }

package/codeAgent/tools/AkanVerifier.ts

@@ -1,48 +1,30 @@
 import { AkanCli, type AkanCliResult } from "./AkanCli";
-import type { AkanEditScopeResult } from "./AkanEditScope";
 
 export interface AkanVerifyReport {
   ok: boolean;
-  steps: AkanCliResult[];
-  scope: AkanEditScopeResult;
+  text: string;
 }
 
 export class AkanVerifier {
+  static readonly tailLines = 20;
   readonly #cli: AkanCli;
 
   constructor(cwd: string) {
     this.#cli = new AkanCli(cwd);
   }
 
-  async verify(scope: AkanEditScopeResult): Promise<AkanVerifyReport> {
-    const steps: AkanCliResult[] = [];
-    const targets = [...scope.apps, ...scope.libs];
-    // Order matters: a stale barrel reads to typecheck as a missing symbol, and lint moves the positions it reports.
-    if (scope.needsSync) for (const target of targets) steps.push(await this.#cli.run(["sync", target]));
-    for (const target of targets) steps.push(await this.#cli.run(["lint", target]));
-    for (const app of scope.apps) steps.push(await this.#cli.run(["typecheck", app]));
-    if (scope.touchesTsx) steps.push(await this.#cli.run(["quality", "ssr"]));
-    return { ok: steps.every((step) => step.ok), steps, scope };
+  async verify(paths: string[] = []): Promise<AkanVerifyReport> {
+    const args = ["verify", ...(paths.length ? ["--files", paths.join(",")] : [])];
+    const result = await this.#cli.run(args, { timeoutMs: 600_000 });
+    return { ok: result.ok, text: AkanVerifier.summarize(result) };
   }
 
-  /** What a model needs to act: which step failed and its tail — never the whole output, which rides every later turn. */
-  static summarize(report: AkanVerifyReport, { tailLines = 40 }: { tailLines?: number } = {}) {
-    if (!report.steps.length) return "No akan target was touched, so there was nothing to verify.";
-    if (report.ok) return `Verification passed: ${report.steps.map((step) => step.command).join(", ")}.`;
-    const failed = report.steps.filter((step) => !step.ok);
-    const passed = report.steps.filter((step) => step.ok).map((step) => step.command);
-    const blocks = failed.map((step) => `### ${step.command} (exit ${step.exitCode})\n${tail(step.output, tailLines)}`);
-    return [
-      `Verification failed: ${failed.map((step) => step.command).join(", ")}.`,
-      passed.length ? `Passed: ${passed.join(", ")}.` : "",
-      ...blocks,
-    ]
-      .filter(Boolean)
-      .join("\n\n");
+  //* `akan verify` already prints the agent-sized report; only a crash before it prints needs trimming.
+  static summarize(result: AkanCliResult) {
+    if (result.output.startsWith("verify ")) return result.output;
+    const lines = result.output.split("\n");
+    const tail =
+      lines.length <= AkanVerifier.tailLines ? result.output : `…\n${lines.slice(-AkanVerifier.tailLines).join("\n")}`;
+    return `${result.command} exited ${result.exitCode} before reporting:\n${tail}`;
   }
 }
-
-const tail = (text: string, lines: number) => {
-  const all = text.split("\n");
-  return all.length <= lines ? text : `…\n${all.slice(-lines).join("\n")}`;
-};

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -111,38 +111,18 @@ describe("TurnFeedback", () => {
 });
 
 describe("AkanVerifier.summarize", () => {
-  const scope = { paths: ["apps/a/x.ts"], apps: ["a"], libs: [], needsSync: false, touchesTsx: false };
+  test("passes the verify report through untouched", () => {
+    const output =
+      "verify fail · a · lint ok · typecheck 1 error · 4.1s\napps/a/x.ts:1:7 TS2322 Type 'string' is not assignable to type 'number'.";
+    expect(AkanVerifier.summarize({ command: "akan verify", ok: false, exitCode: 1, output })).toBe(output);
+  });
 
-  test("names the failing step and keeps only its tail", () => {
+  test("keeps only the tail of a crash that never reached the report", () => {
     const output = [...Array(100).keys()].map((n) => `line ${n}`).join("\n");
-    const text = AkanVerifier.summarize(
-      {
-        ok: false,
-        scope,
-        steps: [
-          { command: "akan lint a", ok: true, exitCode: 0, output: "" },
-          { command: "akan typecheck a", ok: false, exitCode: 1, output },
-        ],
-      },
-      { tailLines: 5 },
-    );
-    expect(text).toContain("Verification failed: akan typecheck a");
-    expect(text).toContain("Passed: akan lint a");
+    const text = AkanVerifier.summarize({ command: "akan verify", ok: false, exitCode: 1, output });
+    expect(text).toStartWith("akan verify exited 1 before reporting:");
     expect(text).toContain("line 99");
-    expect(text).not.toContain("line 10\n");
-  });
-
-  test("says so plainly when everything passed", () => {
-    const text = AkanVerifier.summarize({
-      ok: true,
-      scope,
-      steps: [{ command: "akan lint a", ok: true, exitCode: 0, output: "" }],
-    });
-    expect(text).toContain("Verification passed");
-  });
-
-  test("an untouched workspace is not a failure", () => {
-    expect(AkanVerifier.summarize({ ok: true, scope, steps: [] })).toContain("nothing to verify");
+    expect(text).not.toContain("line 79\n");
   });
 });
 
@@ -153,9 +133,11 @@ describe("AkanEditScope", () => {
     const baseline = await AkanEditScope.baseline(root);
     await writeText(path.join(root, "apps", "demo", "lib", "post", "post.service.ts"), "export {};\n");
     await writeText(path.join(root, "libs", "shared", "ui", "Card.tsx"), "export const Card = () => null;\n");
+    await writeText(path.join(root, "pkgs", "@akanjs", "cli", "index.ts"), "export {};\n");
     const scope = await AkanEditScope.since(root, baseline);
     expect(scope.apps).toEqual(["demo"]);
     expect(scope.libs).toEqual(["shared"]);
+    expect(scope.pkgs).toEqual(["@akanjs/cli"]);
     expect(scope.needsSync).toBe(true);
     expect(scope.touchesTsx).toBe(true);
   });
@@ -165,7 +147,7 @@ describe("AkanEditScope", () => {
     await Bun.spawn(["git", "init", "-q"], { cwd: root, stdout: "ignore", stderr: "ignore" }).exited;
     const baseline = await AkanEditScope.baseline(root);
     const scope = await AkanEditScope.since(root, baseline);
-    expect(scope).toEqual({ paths: [], apps: [], libs: [], needsSync: false, touchesTsx: false });
+    expect(scope).toEqual({ paths: [], apps: [], libs: [], pkgs: [], needsSync: false, touchesTsx: false });
   });
 });
 

package/conventionSet.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import fsPromise from "node:fs/promises";
+import path from "node:path";
+import { ConventionSet } from "./conventionSet";
+import { MaintainabilityContract } from "./maintainabilityContract";
+import { Prompter } from "./prompter";
+
+describe("ConventionSet", () => {
+  test("expands every brace list, so a comma-separated glob field can carry it", () => {
+    expect(ConventionSet.expand("{apps,libs}/**/*.{ts,tsx}")).toEqual([
+      "apps/**/*.ts",
+      "apps/**/*.tsx",
+      "libs/**/*.ts",
+      "libs/**/*.tsx",
+    ]);
+    expect(ConventionSet.expand("**/.env*")).toEqual(["**/.env*"]);
+  });
+
+  test("reads a rule's description and paths from its frontmatter, and refuses one without", () => {
+    const rule = ConventionSet.parseRule(
+      "page",
+      '---\ndescription: Route files.\npaths:\n  - "{apps,libs}/**/page/**"\n---\n\n# Pages\n',
+    );
+    expect(rule).toEqual({
+      name: "page",
+      description: "Route files.",
+      paths: ["{apps,libs}/**/page/**"],
+      body: "# Pages",
+    });
+    expect(() => ConventionSet.parseRule("bare", "# Pages\n")).toThrow("no frontmatter");
+    expect(() => ConventionSet.parseRule("empty", "---\ndescription: x\n---\n")).toThrow("description and paths");
+  });
+
+  test("nests each rule under the core when composed, leaving fenced code alone", () => {
+    const set = new ConventionSet("## Core", [
+      { name: "a", description: "d", paths: ["x"], body: "# A\n\n## Part\n\n```sh\n# a comment\n```" },
+    ]);
+    expect(set.instruction).toBe("## Core\n\n## A\n\n### Part\n\n```sh\n# a comment\n```\n");
+  });
+
+  test("the shipped conventions guideline is the core followed by every rule", async () => {
+    const set = await Prompter.getConventionSet();
+    const instruction = await Prompter.getInstruction("conventions");
+    expect(set.rules.length).toBeGreaterThanOrEqual(10);
+    expect(instruction.startsWith(set.core)).toBe(true);
+    for (const rule of set.rules) {
+      expect(rule.body).toStartWith("# ");
+      expect(instruction).toContain(`\n#${rule.body.split("\n")[0]}\n`);
+    }
+  });
+
+  test("names only checks that exist, and names every lint plugin and maintainability gate somewhere", async () => {
+    const set = await Prompter.getConventionSet();
+    const named = new Set(
+      [set.core, ...set.rules.map((rule) => rule.body)].flatMap((text) =>
+        [...text.matchAll(/`([^`\s]+)`/g)].map((match) => match[1] ?? ""),
+      ),
+    );
+    const plugins = (await fsPromise.readdir(path.join(import.meta.dir, "lint")))
+      .filter((file) => file.endsWith(".grit"))
+      .map((file) => file.slice(0, -".grit".length));
+    const gates: readonly string[] = MaintainabilityContract.ruleIds;
+    const gateAreas = new Set(gates.map((id) => id.split(".").slice(0, 2).join(".")));
+    const isPluginName = (name: string) => /^non?-[a-z]+(-[a-z]+)+$/.test(name);
+    const isGateName = (name: string) =>
+      gateAreas.has(name.split(".").slice(0, 2).join(".")) && !name.endsWith(".json");
+
+    expect([...named].filter((name) => isPluginName(name) && !plugins.includes(name))).toEqual([]);
+    expect([...named].filter((name) => isGateName(name) && !gates.includes(name))).toEqual([]);
+    expect(plugins.filter((plugin) => !named.has(plugin))).toEqual([]);
+    expect(gates.filter((gate) => !named.has(gate))).toEqual([]);
+  });
+});

package/conventionSet.ts

@@ -0,0 +1,67 @@
+import fsPromise from "node:fs/promises";
+import path from "node:path";
+
+export interface ConventionRule {
+  name: string;
+  description: string;
+  paths: string[];
+  body: string;
+}
+
+export class ConventionSet {
+  constructor(
+    readonly core: string,
+    readonly rules: ConventionRule[],
+  ) {}
+
+  static async load(dir: string) {
+    const core = await fsPromise.readFile(path.join(dir, "core.md"), "utf-8");
+    const files = (await fsPromise.readdir(path.join(dir, "rules"))).filter((file) => file.endsWith(".md")).sort();
+    const rules = await Promise.all(
+      files.map(async (file) =>
+        ConventionSet.parseRule(file.slice(0, -3), await fsPromise.readFile(path.join(dir, "rules", file), "utf-8")),
+      ),
+    );
+    return new ConventionSet(core.trim(), rules);
+  }
+
+  static parseRule(name: string, text: string): ConventionRule {
+    const match: RegExpExecArray | null = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (!match) throw new Error(`Convention rule ${name} has no frontmatter`);
+    const front = match[1] ?? "";
+    const described: RegExpExecArray | null = /^description:\s*(.+)$/m.exec(front);
+    const description = described?.[1]?.trim() ?? "";
+    const paths = [...front.matchAll(/^\s+-\s+"([^"]+)"$/gm)].map((entry) => entry[1] ?? "");
+    if (!description || paths.length === 0) throw new Error(`Convention rule ${name} needs a description and paths`);
+    return { name, description, paths, body: text.slice(match[0].length).trim() };
+  }
+
+  //? Cursor splits `globs:` on commas, so a `{a,b}` brace list has to be expanded before it is written there.
+  static expand(glob: string): string[] {
+    const open = glob.indexOf("{");
+    if (open === -1) return [glob];
+    const close = glob.indexOf("}", open);
+    if (close === -1) return [glob];
+    const head = glob.slice(0, open);
+    const tail = glob.slice(close + 1);
+    return glob
+      .slice(open + 1, close)
+      .split(",")
+      .flatMap((choice) => ConventionSet.expand(`${head}${choice}${tail}`));
+  }
+
+  static demote(markdown: string) {
+    let fenced = false;
+    return markdown
+      .split("\n")
+      .map((line) => {
+        if (line.startsWith("```")) fenced = !fenced;
+        return !fenced && /^#{1,5} /.test(line) ? `#${line}` : line;
+      })
+      .join("\n");
+  }
+
+  get instruction() {
+    return `${[this.core, ...this.rules.map((rule) => ConventionSet.demote(rule.body))].join("\n\n")}\n`;
+  }
+}

package/executors.test.ts

@@ -275,10 +275,6 @@ describe("Executor filesystem helpers", () => {
       "Akan workspace agent guide",
     );
     expect(await readFile(path.join(root, "workspace/AGENTS.md"), "utf8")).toContain("sample Agent Guide");
-    expect(await readFile(path.join(root, "workspace/docs/AI-DEVELOPMENT.md"), "utf8")).toContain(
-      "AI Development Guide",
-    );
-    expect(await readFile(path.join(root, "workspace/docs/GENERATED.md"), "utf8")).toContain("Generated Akan Files");
     // Rules live in the package's base config, so a framework release reaches an existing workspace on `bun update`.
     expect(await readFile(path.join(root, "workspace/biome.json"), "utf8")).toContain(
       '"extends": ["@akanjs/devkit/biome.base.json"]',

package/maintainabilityReport.ts

@@ -95,6 +95,17 @@ export class MaintainabilityReport {
     ].join("\n");
   }
 
+  static entriesOf(sysPath: string, failures: MaintainabilityFailure[], commands: MaintainabilityCommands = {}) {
+    return failures.map((failure) => ({
+      file: `${sysPath}/${failure.file}`,
+      line: failure.line,
+      rule: failure.rule,
+      problem: MaintainabilityReport.#problemOf(failure),
+      fix: MaintainabilityReport.#fixes[MaintainabilityReport.#fixKeyOf(failure)],
+      path: commands[failure.rule]?.[0] ?? null,
+    }));
+  }
+
   static #problemOf(failure: MaintainabilityFailure) {
     if (failure.kind === "baselineGrowth") {
       const entry = `entry "${failure.key}" under ${failure.debtRule}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.1-rc.16",
+  "version": "3.1.1-rc.18",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.1-rc.16",
+    "akanjs": "3.1.1-rc.18",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/prompter.ts

@@ -1,6 +1,7 @@
 import fsPromise from "node:fs/promises";
 import { input, select } from "@inquirer/prompts";
 
+import { ConventionSet } from "./conventionSet";
 import { getDirname } from "./fileSys";
 
 interface FileUpdateRequestProps {
@@ -40,8 +41,14 @@ export class Prompter {
     if (!guideNames.includes(guideName))
       throw new Error(`Unknown guideline "${guideName}". Available: ${guideNames.join(", ")}`);
     const guidelineRoot = await Prompter.#getGuidelineRoot();
+    const composed = `${guidelineRoot}/${guideName}/core.md`;
+    if (await Bun.file(composed).exists())
+      return (await ConventionSet.load(`${guidelineRoot}/${guideName}`)).instruction;
     return await fsPromise.readFile(`${guidelineRoot}/${guideName}/${guideName}.instruction.md`, "utf-8");
   }
+  static async getConventionSet() {
+    return await ConventionSet.load(`${await Prompter.#getGuidelineRoot()}/conventions`);
+  }
   static async getUpdateRequest(guideName: string) {
     return await input({
       message: `What do you want to update in ${guideName}?`,

package/typeChecker.ts

@@ -13,6 +13,16 @@ export interface ProjectTypecheckResult {
   message: string;
 }
 
+export interface TypecheckRecord {
+  /** Relative to the workspace root, `/`-separated; `null` for a diagnostic tied to no file. */
+  file: string | null;
+  line: number;
+  col: number;
+  code: string;
+  severity: "error" | "warning";
+  message: string;
+}
+
 export class TypeChecker {
   readonly configPath: string;
   readonly configFile: { config?: any; error?: ts.Diagnostic };
@@ -198,6 +208,28 @@ export class TypeChecker {
     return parsedConfig;
   }
 
+  static toRecords(diagnostics: ts.Diagnostic[], root: string): TypecheckRecord[] {
+    return diagnostics
+      .filter(
+        (diagnostic) =>
+          diagnostic.category === ts.DiagnosticCategory.Error || diagnostic.category === ts.DiagnosticCategory.Warning,
+      )
+      .map((diagnostic) => {
+        const position =
+          diagnostic.file && diagnostic.start !== undefined
+            ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start)
+            : null;
+        return {
+          file: diagnostic.file ? path.relative(root, diagnostic.file.fileName).split(path.sep).join("/") : null,
+          line: position ? position.line + 1 : 0,
+          col: position ? position.character + 1 : 0,
+          code: `TS${diagnostic.code}`,
+          severity: diagnostic.category === ts.DiagnosticCategory.Error ? "error" : "warning",
+          message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+        };
+      });
+  }
+
   static formatDiagnosticMessages(diagnostics: ts.Diagnostic[]): string {
     return ts.formatDiagnosticsWithColorAndContext(diagnostics, {
       getCanonicalFileName: (fileName) => fileName,

package/typecheck/projectTypecheck.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { tempDirs, writeText as write } from "../testHelpers";
 import { ProjectTypecheck } from "./projectTypecheck";
+import { TypecheckFailure } from "./typecheckFailure";
 
 const makeTempRoot = tempDirs("akan-devkit-project-typecheck-");
 
@@ -29,4 +30,21 @@ describe("ProjectTypecheck", () => {
     expect((error as Error).message).toContain("lib/user/user.signal.test.ts");
     expect((error as Error).message).not.toContain("old.test.ts");
   }, 60_000);
+
+  test("hands back one record per diagnostic when asked for records", async () => {
+    const { root, dir } = await project();
+    const error = await new ProjectTypecheck(dir, root, { ...process.env })
+      .run(["../../server.ts"], { tests: true, report: "records" })
+      .catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(TypecheckFailure);
+    const [record, ...rest] = (error as TypecheckFailure).records;
+    expect(rest).toEqual([]);
+    expect(record).toMatchObject({
+      file: "libs/demo/lib/user/user.signal.test.ts",
+      line: 1,
+      col: 14,
+      code: "TS2322",
+      severity: "error",
+    });
+  }, 60_000);
 });

package/typecheck/projectTypecheck.ts

@@ -1,11 +1,15 @@
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+import type { TypecheckRecord } from "../typeChecker";
+import { TypecheckFailure } from "./typecheckFailure";
 
 export interface ProjectTypecheckOptions {
   clean?: boolean;
   incremental?: boolean;
   /** The project's own `*.test.ts` / `*.spec.ts` as well. */
   tests?: boolean;
+  /** `records` fails with a `TypecheckFailure` carrying one record per diagnostic instead of the printed report. */
+  report?: "pretty" | "records";
 }
 
 //* tsc checks what the entries import, and nothing imports a test, so a test is checked only when it is included by
@@ -25,7 +29,10 @@ export class ProjectTypecheck {
   }
 
   /** `entries`: relative to the typecheck folder (`../../server.ts`). */
-  async run(entries: string[], { clean = false, incremental = true, tests = false }: ProjectTypecheckOptions = {}) {
+  async run(
+    entries: string[],
+    { clean = false, incremental = true, tests = false, report = "pretty" }: ProjectTypecheckOptions = {},
+  ) {
     const name = tests ? "tsconfig.tests" : "tsconfig";
     await mkdir(this.typecheckDir, { recursive: true });
     const tsconfig = {
@@ -38,14 +45,19 @@ export class ProjectTypecheck {
     const tsconfigPath = path.join(this.typecheckDir, `${name}.json`);
     await Bun.write(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}\n`);
     if (clean) await rm(path.join(this.typecheckDir, `${name}.tsbuildinfo`), { force: true });
-    await this.#check(tsconfigPath);
+    await this.check(tsconfigPath, report);
     return tsconfigPath;
   }
 
-  async #check(tsconfigPath: string) {
+  async check(tsconfigPath: string, report: "pretty" | "records" = "pretty") {
     const proc = Bun.spawn([process.execPath, await ProjectTypecheck.workerEntry(this.workspaceRoot)], {
       cwd: this.workspaceRoot,
-      env: { ...this.env, AKAN_COMMAND_TYPE: "typecheck", AKAN_TYPECHECK_TSCONFIG: tsconfigPath },
+      env: {
+        ...this.env,
+        AKAN_COMMAND_TYPE: "typecheck",
+        AKAN_TYPECHECK_TSCONFIG: tsconfigPath,
+        ...(report === "records" ? { AKAN_TYPECHECK_FORMAT: "json", AKAN_TYPECHECK_ROOT: this.workspaceRoot } : {}),
+      },
       stdout: "pipe",
       stderr: "pipe",
     });
@@ -54,7 +66,19 @@ export class ProjectTypecheck {
       new Response(proc.stderr).text(),
       proc.exited,
     ]);
-    if (exitCode !== 0) throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+    if (exitCode === 0) return;
+    const records = report === "records" ? ProjectTypecheck.#parseRecords(stdout) : null;
+    if (records?.length) throw new TypecheckFailure(records);
+    throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+  }
+
+  static #parseRecords(stdout: string): TypecheckRecord[] | null {
+    try {
+      const parsed: unknown = JSON.parse(stdout);
+      return Array.isArray(parsed) ? (parsed as TypecheckRecord[]) : null;
+    } catch {
+      return null;
+    }
   }
 
   //? The workspace's own devkit first, then an installed one, then the entry a bundle puts beside its chunks.