@akanjs/cli 2.3.11-rc.4 → 2.3.11-rc.5

package/incrementalBuilder.proc.js

@@ -1710,7 +1710,8 @@ var appRootAllowedFiles = new Set([
   "main.ts",
   "package.json",
   "server.ts",
-  "tsconfig.json"
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo"
 ]);
 var appRootAllowedDirs = new Set([
   ".akan",

package/index.js

@@ -1708,7 +1708,8 @@ var appRootAllowedFiles = new Set([
   "main.ts",
   "package.json",
   "server.ts",
-  "tsconfig.json"
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo"
 ]);
 var appRootAllowedDirs = new Set([
   ".akan",
@@ -16028,19 +16029,12 @@ var targetPaths = {
   "agents-md": "AGENTS.md",
   claude: "CLAUDE.md"
 };
-var targetTitle = {
-  cursor: "Akan Cursor Rules",
-  "agents-md": "Akan Agent Rules",
-  claude: "Akan Claude Rules"
-};
-var renderAgentRules = async (workspace, target) => {
+var AGENT_BLOCK_START = "<!-- akan:agent:start -->";
+var AGENT_BLOCK_END = "<!-- akan:agent:end -->";
+var renderManagedBlock = async (workspace) => {
   const context = await AkanContextAnalyzer.analyze(workspace);
   const frameworkGuide = await Prompter.getInstruction("framework");
-  return `# ${targetTitle[target]}
-
-This file is generated by \`akan agent install ${target}\`.
-
-## Workspace
+  return `## Workspace
 
 - Repo: ${context.repoName}
 - Apps: ${context.apps.map((app) => app.name).join(", ") || "none"}
@@ -16077,8 +16071,61 @@ ${context.validationCommands.map((command3) => `- \`${command3}\``).join(`
 
 ## Framework Guide
 
-${frameworkGuide.trim()}
+${frameworkGuide.trim()}`;
+};
+var upsertManagedBlock = (existing, block) => {
+  const managed = `${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}`;
+  const startIndex = existing.indexOf(AGENT_BLOCK_START);
+  const endIndex = existing.indexOf(AGENT_BLOCK_END);
+  if (startIndex >= 0 && endIndex > startIndex) {
+    return `${existing.slice(0, startIndex)}${managed}${existing.slice(endIndex + AGENT_BLOCK_END.length)}`;
+  }
+  return `${existing.replace(/\s*$/, "")}
+
+${managed}
+`;
+};
+var renderAgentsMd = async (workspace, existing) => {
+  const block = await renderManagedBlock(workspace);
+  if (existing?.trim())
+    return upsertManagedBlock(existing, block);
+  const context = await AkanContextAnalyzer.analyze(workspace);
+  return `# ${context.repoName} Agent Guide
+
+This file is the single source of truth for coding agents in this workspace. Claude Code reads it through
+\`CLAUDE.md\` (\`@AGENTS.md\`) and Cursor through \`.cursor/rules/akan.mdc\`. The section between the
+\`akan:agent\` markers is regenerated by \`akan agent install\`; edit anything outside the markers freely.
+
+${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}
+`;
+};
+var renderClaudeMd = async (workspace) => {
+  const context = await AkanContextAnalyzer.analyze(workspace);
+  return `# ${context.repoName} \u2014 Claude Code Guide
+
+@AGENTS.md
+`;
+};
+var renderCursorRule = () => `---
+description: Akan workspace agent guide
+alwaysApply: true
+---
+
+Follow the workspace agent guide, which is the single source of truth for Akan conventions,
+generated-file rules, and the MCP workflow policy.
+
+@AGENTS.md
 `;
+var renderTarget = async (workspace, target, existing) => {
+  if (target === "agents-md")
+    return await renderAgentsMd(workspace, existing);
+  if (target === "claude")
+    return await renderClaudeMd(workspace);
+  return renderCursorRule();
 };
 
 class AgentRunner extends runner("agent") {
@@ -16086,11 +16133,13 @@ class AgentRunner extends runner("agent") {
     const written = [];
     for (const target of targets) {
       const filePath = targetPaths[target];
-      if (!force && await workspace.exists(filePath)) {
+      const exists2 = await workspace.exists(filePath);
+      if (exists2 && !force && target !== "agents-md") {
         throw new Error(`${filePath} already exists. Re-run with --force to overwrite it.`);
       }
-      const content = await renderAgentRules(workspace, target);
-      await workspace.writeFile(filePath, content, { overwrite: force });
+      const existing = exists2 ? await workspace.readFile(filePath) : null;
+      const content = await renderTarget(workspace, target, existing);
+      await workspace.writeFile(filePath, content, { overwrite: true });
       written.push(filePath);
     }
     return written;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.11-rc.4",
+  "version": "2.3.11-rc.5",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.11-rc.4",
+    "akanjs": "2.3.11-rc.5",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/workspaceRoot/.cursor/rules/akan.mdc.template

@@ -1,38 +1,9 @@
 ---
-description: Akan.js workspace conventions for coding agents
+description: Akan workspace agent guide
 alwaysApply: true
 ---
 
-# Akan.js Workspace Rules
+Follow the workspace agent guide, which is the single source of truth for Akan conventions,
+generated-file rules, and the MCP workflow policy.
 
-- Keep edits inside the established Akan structure: `apps/<app>`, `libs/<lib>`, `pkgs/*`, and `infra`.
-- Pages live under `apps/<app>/page`; index routes use `_index.tsx`, and nested layouts use `_layout.tsx`.
-- Database domain modules live under `lib/<model>`.
-- Service modules live under `lib/_<service>`.
-- Scalar modules live under `lib/__scalar/<scalar>`.
-- Module abstracts live beside module code as `<model>.abstract.md`, `<service>.abstract.md`, or
-  `<scalar>.abstract.md`. Read them before changing module behavior.
-- Do not hand-edit generated Akan files such as `akan.app.json`, `client.ts`, `server.ts`, generated facet indexes,
-  `lib/cnst.ts`, `lib/dict.ts`, `lib/db.ts`, `lib/srv.ts`, `lib/st.ts`, `lib/sig.ts`, `lib/useClient.ts`, or
-  `lib/useServer.ts`.
-- Prefer Akan MCP workflows before direct source edits: use `akan mcp --mode plan` for workflow discovery and
-  planning, then `akan mcp --mode apply` only for allowlisted apply, validation, and repair tools.
-- If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call `apply_workflow({ planPath })` before
-  editing source files directly.
-- After `apply_workflow`, run `run_validation` with `validationTarget` when present; otherwise use `applyReportPath`.
-- Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
-- Direct edits are fallback only after `list_workflows`/`explain_workflow` show no matching workflow, or after
-  `apply_workflow` reports unsupported/no-op/failed diagnostics that require manual action.
-- For compound requests, split the request into workflows and apply each `planPath` in order, such as `create-module`
-  followed by `add-field`.
-- If generated output is stale or broken, update the owning source file and run `akan repair generated` or
-  `akan sync <app-or-lib>` instead of patching generated files.
-- For new domain behavior, inspect sibling `constant`, `dictionary`, `signal`, `document`, `service`, `store`, and UI
-  module files before changing shape.
-- Update `*.abstract.md` when business invariants, workflows, or public behavior change. Do not update it for
-  formatting-only, import-only, or style-only changes.
-- Respect server/client import boundaries. Use `akanjs/server` only in server-side code and `akanjs/client` only in
-  client/page runtime code.
-- Treat `AKAN_PUBLIC_*` env vars as public values. Do not store secrets in them.
-- Verify changes with the smallest relevant command: `akan lint <target>`, `akan test <target>`, or
-  `akan build <app-name>`.
+@AGENTS.md

package/templates/workspaceRoot/AGENTS.md.template

@@ -576,3 +576,13 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 | `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
 
 **Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+
+## Generated Context
+
+The section below is regenerated by `akan agent install` (run `bun run setup:agent`). It lists this
+workspace's apps, generated files, validation commands, and framework guide. Edit anything outside the
+markers freely; content between them is overwritten on the next install.
+
+<!-- akan:agent:start -->
+<!-- Populated by `akan agent install`. Run `bun run setup:agent` to refresh. -->
+<!-- akan:agent:end -->