code-ai-installer 4.0.1-b → 4.0.1-c

package/dist/mcp_setup.d.ts

@@ -2,16 +2,26 @@ import type { DomainId } from "./shared/index.js";
 /**
  * MCP auto-setup for `--target=claude` installs.
  *
- * Two responsibilities (ADR-DEV-099):
+ * Responsibilities:
  *   1. Detect / install MemPalace as an opt-in mirror for decision storage.
- *   2. Write project-level `.mcp.json` registering `code-ai-mcp` (always) and
- *      `mempalace-mcp` (when accepted) so Claude Code picks them up automatically.
- *   3. Write `.code-ai/config.json` so `code-ai-mcp` knows which backend to use.
+ *   2. Register `code-ai-mcp` (always) and `mempalace` (when accepted) in
+ *      Claude Code's USER (global) scope via `claude mcp add --scope user`,
+ *      so the servers are available across all the user's projects.
+ *   3. Write `.code-ai/config.json` so `code-ai-mcp` knows which backend +
+ *      domain to use. This stays PROJECT-local — the global server reads it
+ *      from the project cwd at runtime.
+ *
+ * Why user scope (not a project `.mcp.json`): MCP servers are tools the user
+ * wants everywhere, not per-project copies. Writing a project `.mcp.json` both
+ * scattered `code-ai-mcp` per-project and duplicated an already-global
+ * `mempalace` into the project. Registration is idempotent — a server already
+ * present in user scope is left untouched.
  *
  * Non-Claude targets skip this whole flow — MCP is Claude-specific.
  *
- * Graceful degradation: every step is best-effort. Failures fall back to
- * "JsonlStore only" without breaking the rest of the install.
+ * Graceful degradation: every step is best-effort. If the `claude` CLI is not
+ * on PATH we never touch the user's config by hand — we print the exact
+ * `claude mcp add` commands to run manually instead.
  */
 export type PythonRuntimeTool = "uv" | "pipx" | "pip";
 export interface PythonRuntime {
@@ -25,15 +35,22 @@ export interface McpServerEntry {
     args: string[];
     env?: Record<string, string>;
 }
-export interface McpJsonShape {
-    mcpServers?: Record<string, McpServerEntry>;
-    [key: string]: unknown;
+/**
+ * Minimal `claude` CLI surface this module needs. Injectable so tests can
+ * assert the constructed argv without spawning the real CLI.
+ */
+export interface ClaudeCli {
+    /** Run `claude <args>`; resolve { ok, output } (combined stdout+stderr). */
+    run(args: string[]): Promise<{
+        ok: boolean;
+        output: string;
+    }>;
 }
 export interface McpSetupOptions {
     destinationDir: string;
     /** User's answer to the MemPalace prompt (true = wants it). */
     wantMempalace: boolean;
-    /** When true, no files are written; the report still reflects planned actions. */
+    /** When true, no commands run and no files are written; report reflects plan. */
     dryRun: boolean;
     /**
      * The selected domain, written into `.code-ai/config.json` so the gate tools
@@ -47,19 +64,29 @@ export interface McpSetupReport {
     mempalaceInstallAttempted: boolean;
     mempalaceInstallSucceeded: boolean;
     pythonRuntime: PythonRuntime | null;
-    mcpJsonPath: string;
-    mcpJsonAction: "created" | "merged" | "skipped";
+    /** Was the `claude` CLI found on PATH? When false, registration falls back to manual instructions. */
+    claudeCliAvailable: boolean;
+    /** How servers were registered. */
+    registration: "user-scope" | "manual-fallback";
+    /** Server names freshly added to user scope this run. */
+    serversRegistered: string[];
+    /** Server names already present in user scope (left untouched). */
+    serversAlreadyPresent: string[];
+    /** Server names whose registration failed. */
+    serversFailed: string[];
     configPath: string;
     notices: string[];
 }
 /**
  * Try `mempalace-mcp --help` — the dedicated MCP-server bin, which is exactly
- * what we register in `.mcp.json`. Resolves true on exit code 0, false otherwise
- * (including ENOENT — bin not on PATH). Probing the actual server bin (not the
- * `mempalace` CLI) means a stale MemPalace without `mempalace-mcp` triggers a
- * (re)install instead of writing a config that can't launch.
+ * what we register. Resolves true on exit code 0, false otherwise (including
+ * ENOENT — bin not on PATH). Probing the actual server bin (not the `mempalace`
+ * CLI) means a stale MemPalace without `mempalace-mcp` triggers a (re)install
+ * instead of registering a config that can't launch.
  */
 export declare function detectMemPalace(): Promise<boolean>;
+/** True when the `claude` CLI is on PATH (probed via `claude --version`). */
+export declare function detectClaudeCli(cli?: ClaudeCli): Promise<boolean>;
 /**
  * Find the first available Python install runtime, in preference order:
  * uv → pipx → pip. Returns null if none available.
@@ -75,21 +102,24 @@ export declare function installMemPalace(runtime: PythonRuntime): Promise<{
     output: string;
 }>;
 /**
- * Merge MCP server entries into `<destinationDir>/.mcp.json`.
- * Behaviour:
- *   - Missing file: create with `{ "mcpServers": <new> }`.
- *   - Existing valid JSON: merge `mcpServers`; if a server name already exists,
- *     keep the existing entry untouched and add a notice.
- *   - Malformed JSON: abort (return action="skipped") with notice — never clobber.
+ * Build the argv for `claude mcp add --scope user <name> -- <command> [args]`.
+ * Pure — exported for testing. Env vars become `-e KEY=VALUE` flags placed
+ * before the server name (as `claude mcp add` expects options first).
  */
-export declare function mergeMcpJson(destinationDir: string, servers: Record<string, McpServerEntry>, dryRun?: boolean): Promise<{
-    action: McpSetupReport["mcpJsonAction"];
-    path: string;
-    notices: string[];
-}>;
+export declare function buildClaudeAddArgs(name: string, entry: McpServerEntry): string[];
+/** Build the argv for `claude mcp remove --scope user <name>`. Pure — exported for testing. */
+export declare function buildClaudeRemoveArgs(name: string): string[];
+/**
+ * Is `name` already registered in Claude's USER scope? Uses `claude mcp get`,
+ * whose output prints `Scope: User config` for user-scope servers. A server in
+ * a different scope (local/project) returns false here — we still want it in
+ * user scope.
+ */
+export declare function isRegisteredInUserScope(cli: ClaudeCli, name: string): Promise<boolean>;
 /**
  * Write `<destinationDir>/.code-ai/config.json` with the chosen backend.
  * Idempotent — re-running overwrites with the same content if backend unchanged.
+ * Stays project-local: the user-scope `code-ai-mcp` reads it from the cwd.
  */
 export declare function writeCodeAiConfig(destinationDir: string, config: {
     decision_store: "jsonl" | "mempalace";
@@ -103,10 +133,33 @@ export declare function writeCodeAiConfig(destinationDir: string, config: {
  * Order:
  *   1. If user wants MemPalace: detect → install if absent → fall back if install fails.
  *   2. Build server entries (code-ai-mcp always; mempalace only when usable).
- *   3. Merge into .mcp.json.
- *   4. Write .code-ai/config.json with backend choice.
+ *   3. Register them in Claude USER scope via `claude mcp add --scope user`
+ *      (idempotent; skip if already present). If `claude` CLI is absent, emit
+ *      manual commands instead of touching the config by hand.
+ *   4. Write project-local `.code-ai/config.json` with the backend choice.
  *
  * Reports all decisions in `McpSetupReport.notices` so callers can surface
- * them to the user verbatim.
+ * them to the user verbatim. `cli` is injectable for testing.
  */
-export declare function setupMcp(opts: McpSetupOptions): Promise<McpSetupReport>;
+export declare function setupMcp(opts: McpSetupOptions, cli?: ClaudeCli): Promise<McpSetupReport>;
+export interface McpTeardownReport {
+    claudeCliAvailable: boolean;
+    removal: "user-scope" | "manual-fallback";
+    serversRemoved: string[];
+    serversNotPresent: string[];
+    serversFailed: string[];
+    notices: string[];
+}
+/**
+ * Remove the installer-owned MCP server(s) from Claude's USER scope via
+ * `claude mcp remove --scope user`. Idempotent — a server that isn't registered
+ * is reported as "nothing to remove". If the `claude` CLI is absent, prints the
+ * manual commands instead of touching the config. `cli` is injectable for tests.
+ *
+ * NOTE: the registration is global (shared across all projects), so this removes
+ * code-ai-mcp for every project. That is the chosen behaviour (symmetric with
+ * install); a multi-project user re-runs the installer to restore it.
+ */
+export declare function teardownMcp(opts: {
+    dryRun: boolean;
+}, cli?: ClaudeCli): Promise<McpTeardownReport>;

package/dist/mcp_setup.js

@@ -1,16 +1,24 @@
 import { spawn } from "node:child_process";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+const defaultClaudeCli = {
+    run: (args) => spawnCapture("claude", args),
+};
 /**
  * Try `mempalace-mcp --help` — the dedicated MCP-server bin, which is exactly
- * what we register in `.mcp.json`. Resolves true on exit code 0, false otherwise
- * (including ENOENT — bin not on PATH). Probing the actual server bin (not the
- * `mempalace` CLI) means a stale MemPalace without `mempalace-mcp` triggers a
- * (re)install instead of writing a config that can't launch.
+ * what we register. Resolves true on exit code 0, false otherwise (including
+ * ENOENT — bin not on PATH). Probing the actual server bin (not the `mempalace`
+ * CLI) means a stale MemPalace without `mempalace-mcp` triggers a (re)install
+ * instead of registering a config that can't launch.
  */
 export async function detectMemPalace() {
     return spawnExitZero("mempalace-mcp", ["--help"]);
 }
+/** True when the `claude` CLI is on PATH (probed via `claude --version`). */
+export async function detectClaudeCli(cli = defaultClaudeCli) {
+    const res = await cli.run(["--version"]);
+    return res.ok;
+}
 /**
  * Find the first available Python install runtime, in preference order:
  * uv → pipx → pip. Returns null if none available.
@@ -48,49 +56,60 @@ function installCommandArgs(runtime) {
     }
 }
 /**
- * Merge MCP server entries into `<destinationDir>/.mcp.json`.
- * Behaviour:
- *   - Missing file: create with `{ "mcpServers": <new> }`.
- *   - Existing valid JSON: merge `mcpServers`; if a server name already exists,
- *     keep the existing entry untouched and add a notice.
- *   - Malformed JSON: abort (return action="skipped") with notice — never clobber.
+ * Build the argv for `claude mcp add --scope user <name> -- <command> [args]`.
+ * Pure — exported for testing. Env vars become `-e KEY=VALUE` flags placed
+ * before the server name (as `claude mcp add` expects options first).
  */
-export async function mergeMcpJson(destinationDir, servers, dryRun = false) {
-    const path = join(destinationDir, ".mcp.json");
-    const notices = [];
-    const existingRaw = await readFile(path, "utf8").catch(() => null);
-    if (existingRaw === null) {
-        if (!dryRun) {
-            await mkdir(destinationDir, { recursive: true });
-            await writeFile(path, JSON.stringify({ mcpServers: servers }, null, 2) + "\n", "utf8");
-        }
-        return { action: "created", path, notices };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(existingRaw);
-    }
-    catch {
-        notices.push(`Existing .mcp.json is not valid JSON — skipped to avoid clobbering it. Path: ${path}`);
-        return { action: "skipped", path, notices };
-    }
-    const merged = { ...(parsed.mcpServers ?? {}) };
-    for (const [name, entry] of Object.entries(servers)) {
-        if (name in merged) {
-            notices.push(`.mcp.json already has server '${name}' — kept existing entry.`);
-            continue;
-        }
-        merged[name] = entry;
+export function buildClaudeAddArgs(name, entry) {
+    const envFlags = entry.env
+        ? Object.entries(entry.env).flatMap(([k, v]) => ["-e", `${k}=${v}`])
+        : [];
+    return ["mcp", "add", ...envFlags, "--scope", "user", name, "--", entry.command, ...entry.args];
+}
+/** Build the argv for `claude mcp remove --scope user <name>`. Pure — exported for testing. */
+export function buildClaudeRemoveArgs(name) {
+    return ["mcp", "remove", "--scope", "user", name];
+}
+/** Human-readable manual command, for the no-CLI fallback notice. */
+function manualAddCommand(name, entry) {
+    return `claude ${buildClaudeAddArgs(name, entry).join(" ")}`;
+}
+/**
+ * Is `name` already registered in Claude's USER scope? Uses `claude mcp get`,
+ * whose output prints `Scope: User config` for user-scope servers. A server in
+ * a different scope (local/project) returns false here — we still want it in
+ * user scope.
+ */
+export async function isRegisteredInUserScope(cli, name) {
+    const res = await cli.run(["mcp", "get", name]);
+    return res.ok && /Scope:\s*User config/i.test(res.output);
+}
+/**
+ * Register one server in user scope, idempotently. Skips if already present in
+ * user scope. Never throws — returns the outcome + a notice for the report.
+ */
+async function addServerToUserScope(cli, name, entry) {
+    if (await isRegisteredInUserScope(cli, name)) {
+        return {
+            outcome: "already-present",
+            notice: `MCP server '${name}' already registered in user scope — left untouched.`,
+        };
     }
-    parsed.mcpServers = merged;
-    if (!dryRun) {
-        await writeFile(path, JSON.stringify(parsed, null, 2) + "\n", "utf8");
+    const res = await cli.run(buildClaudeAddArgs(name, entry));
+    if (res.ok) {
+        return { outcome: "registered", notice: `Registered MCP server '${name}' in user scope (global).` };
     }
-    return { action: "merged", path, notices };
+    return {
+        outcome: "failed",
+        notice: `Failed to register '${name}' in user scope. Run it manually:\n` +
+            `    ${manualAddCommand(name, entry)}\n` +
+            `  Output:\n${res.output}`,
+    };
 }
 /**
  * Write `<destinationDir>/.code-ai/config.json` with the chosen backend.
  * Idempotent — re-running overwrites with the same content if backend unchanged.
+ * Stays project-local: the user-scope `code-ai-mcp` reads it from the cwd.
  */
 export async function writeCodeAiConfig(destinationDir, config, dryRun = false) {
     const dir = join(destinationDir, ".code-ai");
@@ -101,19 +120,43 @@ export async function writeCodeAiConfig(destinationDir, config, dryRun = false)
     }
     return { path };
 }
+/**
+ * Build the server entries to register. `code-ai-mcp` always; `mempalace` only
+ * when usable.
+ */
+function buildServerEntries(mempalaceUsed) {
+    // DEV-100 consolidation: the code-ai-mcp bin lives inside the
+    // `code-ai-installer` npm package. `npx -p <package> <bin>` tells npm to
+    // install that package and run the named bin from it.
+    const servers = {
+        "code-ai-mcp": {
+            command: "npx",
+            args: ["-y", "-p", "code-ai-installer", "code-ai-mcp"],
+        },
+    };
+    if (mempalaceUsed) {
+        // Use the dedicated `mempalace-mcp` stdio server bin (NOT `mempalace mcp`):
+        // the full CLI subcommand can emit to stdout before the MCP handshake and
+        // corrupt the JSON-RPC stream, so Claude Code fails to launch it.
+        servers["mempalace"] = { command: "mempalace-mcp", args: [] };
+    }
+    return servers;
+}
 /**
  * End-to-end orchestrator. Called from the install flow when `target=claude`.
  *
  * Order:
  *   1. If user wants MemPalace: detect → install if absent → fall back if install fails.
  *   2. Build server entries (code-ai-mcp always; mempalace only when usable).
- *   3. Merge into .mcp.json.
- *   4. Write .code-ai/config.json with backend choice.
+ *   3. Register them in Claude USER scope via `claude mcp add --scope user`
+ *      (idempotent; skip if already present). If `claude` CLI is absent, emit
+ *      manual commands instead of touching the config by hand.
+ *   4. Write project-local `.code-ai/config.json` with the backend choice.
  *
  * Reports all decisions in `McpSetupReport.notices` so callers can surface
- * them to the user verbatim.
+ * them to the user verbatim. `cli` is injectable for testing.
  */
-export async function setupMcp(opts) {
+export async function setupMcp(opts, cli = defaultClaudeCli) {
     const notices = [];
     let mempalaceUsed = false;
     let mempalaceInstallAttempted = false;
@@ -144,26 +187,39 @@ export async function setupMcp(opts) {
             }
         }
     }
-    // DEV-100 consolidation: the code-ai-mcp bin lives inside the
-    // `code-ai-installer` npm package. `npx -p <package> <bin>` tells npm to
-    // install that package and run the named bin from it.
-    const servers = {
-        "code-ai-mcp": {
-            command: "npx",
-            args: ["-y", "-p", "code-ai-installer", "code-ai-mcp"],
-        },
-    };
-    if (mempalaceUsed) {
-        // Use the dedicated `mempalace-mcp` stdio server bin (NOT `mempalace mcp`):
-        // the full CLI subcommand can emit to stdout before the MCP handshake and
-        // corrupt the JSON-RPC stream, so Claude Code fails to launch it.
-        servers["mempalace"] = {
-            command: "mempalace-mcp",
-            args: [],
-        };
+    const servers = buildServerEntries(mempalaceUsed);
+    const serversRegistered = [];
+    const serversAlreadyPresent = [];
+    const serversFailed = [];
+    const claudeCliAvailable = !opts.dryRun && (await detectClaudeCli(cli));
+    let registration;
+    if (opts.dryRun) {
+        registration = "user-scope";
+        for (const [name, entry] of Object.entries(servers)) {
+            notices.push(`Would register MCP server '${name}' in user scope: ${manualAddCommand(name, entry)}`);
+        }
+    }
+    else if (claudeCliAvailable) {
+        registration = "user-scope";
+        for (const [name, entry] of Object.entries(servers)) {
+            const { outcome, notice } = await addServerToUserScope(cli, name, entry);
+            notices.push(notice);
+            if (outcome === "registered")
+                serversRegistered.push(name);
+            else if (outcome === "already-present")
+                serversAlreadyPresent.push(name);
+            else
+                serversFailed.push(name);
+        }
+    }
+    else {
+        registration = "manual-fallback";
+        notices.push("The `claude` CLI was not found on PATH — not modifying your global config automatically. " +
+            "Register the MCP server(s) in user scope by running:");
+        for (const [name, entry] of Object.entries(servers)) {
+            notices.push(`    ${manualAddCommand(name, entry)}`);
+        }
     }
-    const mcp = await mergeMcpJson(opts.destinationDir, servers, opts.dryRun);
-    notices.push(...mcp.notices);
     const cfg = await writeCodeAiConfig(opts.destinationDir, {
         decision_store: mempalaceUsed ? "mempalace" : "jsonl",
         ...(opts.domain ? { domain: opts.domain } : {}),
@@ -173,12 +229,72 @@ export async function setupMcp(opts) {
         mempalaceInstallAttempted,
         mempalaceInstallSucceeded,
         pythonRuntime,
-        mcpJsonPath: mcp.path,
-        mcpJsonAction: mcp.action,
+        claudeCliAvailable,
+        registration,
+        serversRegistered,
+        serversAlreadyPresent,
+        serversFailed,
         configPath: cfg.path,
         notices,
     };
 }
+// ─── Teardown (uninstall) ───────────────────────────────────────────────────
+/**
+ * Servers the installer registers and is therefore responsible for removing on
+ * uninstall. `mempalace` is intentionally absent — it is the user's own memory
+ * server and may predate code-ai, so uninstall never touches it.
+ */
+const INSTALLER_OWNED_SERVERS = ["code-ai-mcp"];
+/**
+ * Remove the installer-owned MCP server(s) from Claude's USER scope via
+ * `claude mcp remove --scope user`. Idempotent — a server that isn't registered
+ * is reported as "nothing to remove". If the `claude` CLI is absent, prints the
+ * manual commands instead of touching the config. `cli` is injectable for tests.
+ *
+ * NOTE: the registration is global (shared across all projects), so this removes
+ * code-ai-mcp for every project. That is the chosen behaviour (symmetric with
+ * install); a multi-project user re-runs the installer to restore it.
+ */
+export async function teardownMcp(opts, cli = defaultClaudeCli) {
+    const notices = [];
+    const serversRemoved = [];
+    const serversNotPresent = [];
+    const serversFailed = [];
+    if (opts.dryRun) {
+        for (const name of INSTALLER_OWNED_SERVERS) {
+            notices.push(`Would remove MCP server '${name}' from user scope: claude ${buildClaudeRemoveArgs(name).join(" ")}`);
+        }
+        return { claudeCliAvailable: false, removal: "user-scope", serversRemoved, serversNotPresent, serversFailed, notices };
+    }
+    const claudeCliAvailable = await detectClaudeCli(cli);
+    if (!claudeCliAvailable) {
+        notices.push("The `claude` CLI was not found on PATH — not modifying your global config automatically. " +
+            "Remove the MCP server(s) from user scope by running:");
+        for (const name of INSTALLER_OWNED_SERVERS) {
+            notices.push(`    claude ${buildClaudeRemoveArgs(name).join(" ")}`);
+        }
+        return { claudeCliAvailable, removal: "manual-fallback", serversRemoved, serversNotPresent, serversFailed, notices };
+    }
+    for (const name of INSTALLER_OWNED_SERVERS) {
+        if (!(await isRegisteredInUserScope(cli, name))) {
+            serversNotPresent.push(name);
+            notices.push(`MCP server '${name}' is not registered in user scope — nothing to remove.`);
+            continue;
+        }
+        const res = await cli.run(buildClaudeRemoveArgs(name));
+        if (res.ok) {
+            serversRemoved.push(name);
+            notices.push(`Removed MCP server '${name}' from user scope.`);
+        }
+        else {
+            serversFailed.push(name);
+            notices.push(`Failed to remove '${name}' from user scope. Run it manually:\n` +
+                `    claude ${buildClaudeRemoveArgs(name).join(" ")}\n` +
+                `  Output:\n${res.output}`);
+        }
+    }
+    return { claudeCliAvailable, removal: "user-scope", serversRemoved, serversNotPresent, serversFailed, notices };
+}
 // ─── Subprocess helpers ─────────────────────────────────────────────────────
 async function spawnExitZero(command, args) {
     return new Promise((resolve) => {

package/dist/platforms/adapters.js

@@ -15,7 +15,8 @@ const targetLayouts = {
         agentsDir: ".claude/agents",
         skillsDir: ".claude/skills",
         workflowsDir: ".claude/workflows",
-        notes: "Uses CLAUDE.md and local .claude folder for role/skill docs.",
+        commandsDir: ".claude/commands",
+        notes: "Uses CLAUDE.md and local .claude folder for role/skill docs; command-type workflows install as slash commands under .claude/commands.",
     },
     "qwen-3.5": {
         instructionFile: "QWEN.md",
@@ -192,15 +193,7 @@ function planForLayout(layout, catalog, destinationDir, selectedAgents, selected
             target,
         });
     }
-    if (layout.workflowsDir) {
-        for (const workflowPath of Object.values(catalog.workflowFiles)) {
-            operations.push({
-                sourcePath: workflowPath,
-                destinationPath: path.join(destinationDir, layout.workflowsDir, path.basename(workflowPath)),
-                generated: false,
-            });
-        }
-    }
+    appendWorkflowOperations(operations, layout, catalog, destinationDir, target);
     appendExtraFileOperations(operations, catalog, destinationDir);
     return operations;
 }
@@ -288,18 +281,60 @@ function planForGeminiLayout(layout, catalog, destinationDir, selectedAgents, se
             target,
         });
     }
-    if (layout.workflowsDir) {
-        for (const workflowPath of Object.values(catalog.workflowFiles)) {
-            operations.push({
-                sourcePath: workflowPath,
-                destinationPath: path.join(destinationDir, layout.workflowsDir, path.basename(workflowPath)),
-                generated: false,
-            });
-        }
-    }
+    appendWorkflowOperations(operations, layout, catalog, destinationDir, target);
     appendExtraFileOperations(operations, catalog, destinationDir);
     return operations;
 }
+/**
+ * Returns true when a workflow file is a user-invokable command (installed as a
+ * slash command on platforms that expose a commands directory), false for
+ * pipeline rule / reference docs that stay in the workflows directory.
+ *
+ * Convention-based classifier (no source-file metadata): files ending in
+ * `pipeline-rules.md` and the implicit `auto-restart-containers.md` rule are
+ * NOT commands; everything else is. Fail-safe — an unrecognised name defaults
+ * to a command so it stays visible under commands/ rather than being hidden.
+ * @param fileName Workflow file base name.
+ * @returns True when the file is a command, false for a rule/reference doc.
+ */
+function isCommandWorkflow(fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith("pipeline-rules.md")) {
+        return false;
+    }
+    if (lower === "auto-restart-containers.md") {
+        return false;
+    }
+    return true;
+}
+/**
+ * Appends workflow copy operations, routing command-type files to the platform
+ * commands directory (when the layout defines one) and rule / reference docs to
+ * the workflows directory. Platforms without a commands directory keep all
+ * workflow files in the workflows directory (unchanged behaviour).
+ * @param operations Mutable operations list.
+ * @param layout Platform layout.
+ * @param catalog Source catalog with workflowFiles.
+ * @param destinationDir Destination root.
+ */
+function appendWorkflowOperations(operations, layout, catalog, destinationDir, target) {
+    for (const workflowPath of Object.values(catalog.workflowFiles)) {
+        const fileName = path.basename(workflowPath);
+        const targetDir = layout.commandsDir && isCommandWorkflow(fileName) ? layout.commandsDir : layout.workflowsDir;
+        if (!targetDir) {
+            continue;
+        }
+        operations.push({
+            sourcePath: workflowPath,
+            destinationPath: path.join(destinationDir, targetDir, fileName),
+            generated: false,
+            transform: {
+                target,
+                assetType: "workflow",
+            },
+        });
+    }
+}
 /**
  * Appends copy operations for extra root-level files (e.g. prompt-examples.md).
  * @param operations Mutable operations list.

package/dist/shared/frontmatter.js

@@ -61,7 +61,7 @@ export const SkillFrontmatter = z.object({
      *  n8n-pinecone-qdrant-supabase-reference). Workflows may use tactical per-skill raises
      *  up to 400 (precedent ADR-DEV-021 raised k8s-manifests-conventions workflow to 350).
      *  Raised to 800 in ADR-DEV-034 for state-zustand-beast-practices-reference (750)
-     *  — densest examples skill in codebase, DEN-locked rule prevents trim. */
+     *  — densest examples skill in codebase, the user-mandated cap prevents trim. */
     budget_lines: z.number().int().positive().max(SKILL_BUDGET_LINES_MAX).default(300),
     /** Frontmatter version. Bumped when SkillFrontmatter shape changes. */
     schema_version: z.literal(1).default(1),

package/dist/shared/persona.d.ts

@@ -7,7 +7,7 @@ import { z } from "zod";
  *   - persona-user-{handle}.md is local-only (gitignored, frontmatter flag, files-whitelist excluded)
  *   - the merged persona is what `load_role` returns to SessionStart
  *
- * Provenance per property is mandatory (DEN: "must be visible where each rule came from").
+ * Provenance per property is mandatory (the user: "must be visible where each rule came from").
  */
 /**
  * Provenance pointer — where a persona property was derived from.

package/dist/shared/persona.js

@@ -7,7 +7,7 @@ import { z } from "zod";
  *   - persona-user-{handle}.md is local-only (gitignored, frontmatter flag, files-whitelist excluded)
  *   - the merged persona is what `load_role` returns to SessionStart
  *
- * Provenance per property is mandatory (DEN: "must be visible where each rule came from").
+ * Provenance per property is mandatory (the user: "must be visible where each rule came from").
  */
 /**
  * Provenance pointer — where a persona property was derived from.