@aidemd-mcp/server 0.2.0

package/dist/tools/init/index.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { join, isAbsolute, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import detectFramework from "../../tools/init/detectFramework/index.js";
+import resolveBrainHints from "../../tools/init/resolveBrainHints/index.js";
+import { configureZed, configureVscode } from "../../tools/init/configureIde/index.js";
+import writeMethodology from "./writeMethodology/index.js";
+import installMethodologyDocs from "./installMethodologyDocs/index.js";
+import scaffoldCommands from "./scaffoldCommands/index.js";
+import installAgents from "./installAgents/index.js";
+import installSkills from "./installSkills/index.js";
+import wireMcp from "./wireMcp/index.js";
+import provisionBrain from "./provisionBrain/index.js";
+/**
+ * Input schema for aide_init.
+ *
+ * `brainPath` and `skipIde` are removed: the brain path is always resolved
+ * through agent-user conversation (not a silent tool parameter), and IDE
+ * configuration is presented per-category during the agent interview.
+ * `framework` remains so the agent can re-call after user confirms or
+ * overrides framework detection.
+ */
+export const InitInput = z.object({
+    framework: z.enum(["claude", "cursor", "windsurf", "copilot"]).optional().describe("Force a specific framework instead of auto-detecting"),
+    path: z.string().optional().describe("Custom project root path (defaults to server working directory)"),
+    category: z.enum(["framework", "methodology", "commands", "agents", "skills", "mcp", "brain", "ide"]).optional().describe("When provided, write all would-create files to disk and return a manifest. When omitted, return all steps as a metadata-only summary (no content fields)."),
+    brainPath: z.string().optional().describe("Resolved brain vault path for the brain category. The agent provides this after interviewing the user."),
+});
+/**
+ * Bootstrap the AIDE development environment into a project.
+ *
+ * Returns structured JSON (`InitResult`) — no prose, no formatting. The
+ * calling agent interprets the result, walks the user through each category,
+ * and applies the steps the user confirms.
+ *
+ * Each step is idempotent: re-running on a fully initialized project returns
+ * all steps as `exists`. Brain hints are discovered from env var, sibling
+ * path, and conventional path — returned as candidates the agent presents
+ * to the user; the agent confirms the path before any vault work is done.
+ *
+ * @param root - Server working directory (from --root CLI arg or cwd).
+ * @param framework - Optional framework override.
+ * @param path - Optional project root override (absolute or relative to root).
+ * @param brainPath - User-confirmed vault path. When provided, forwarded to
+ *   provisionBrain instead of using the first discovered hint.
+ */
+export default async function init(root, framework, path, brainPath) {
+    const projectRoot = path ? (isAbsolute(path) ? path : join(root, path)) : root;
+    const config = await detectFramework(projectRoot, framework);
+    const brainHints = await resolveBrainHints(projectRoot);
+    // Collect planning steps from each helper. Order follows the spec's category
+    // list: methodology, commands, agents, skills, mcp, brain, ide.
+    const docSteps = await installMethodologyDocs(join(projectRoot, config.docHubDir), config.docHubDir);
+    const methodologyStep = await writeMethodology(join(projectRoot, config.configPath), config.docHubDir);
+    const commandSteps = await scaffoldCommands(join(projectRoot, config.commandDir));
+    const agentSteps = await installAgents(join(projectRoot, config.agentDir));
+    const skillSteps = await installSkills(join(projectRoot, config.skillDir));
+    const mcpStep = await wireMcp(join(projectRoot, config.mcpConfigPath));
+    // Brain steps require a confirmed vault path. When brainPath is explicitly
+    // provided (agent-confirmed), use it directly. When hints exist, use the
+    // first hint to check existing state. When neither is available, return
+    // placeholder steps so the agent knows to interview the user first.
+    const brainMcpPath = join(projectRoot, config.mcpConfigPath);
+    let brainSteps;
+    const resolvedBrainPath = brainPath ?? (brainHints.length > 0 ? brainHints[0].path : undefined);
+    if (resolvedBrainPath) {
+        brainSteps = await provisionBrain(resolvedBrainPath, brainMcpPath);
+    }
+    else {
+        // No hints discovered and no explicit brainPath — the agent must ask the
+        // user for a path. Return would-create steps with empty filePaths so the
+        // agent knows brain provisioning is pending user input, not silently resolved.
+        brainSteps = [
+            { name: "Brain vault", status: "would-create", category: "brain", filePath: "" },
+            { name: "Playbook hub", status: "would-create", category: "brain", filePath: "" },
+            { name: "Vault CLAUDE.md", status: "would-create", category: "brain", filePath: "" },
+            { name: "MCP config (obsidian)", status: "would-create", category: "mcp", filePath: brainMcpPath },
+        ];
+    }
+    const extensionsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "extensions", "vscode");
+    const zedStep = await configureZed(projectRoot);
+    const vscodeStep = await configureVscode(extensionsDir);
+    const steps = [
+        methodologyStep,
+        ...docSteps,
+        ...commandSteps,
+        ...agentSteps,
+        ...skillSteps,
+        mcpStep,
+        ...brainSteps,
+        zedStep,
+        vscodeStep,
+    ];
+    return {
+        framework: config.framework,
+        steps,
+        brainHints,
+    };
+}

package/dist/tools/init/initContent/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Canonical-name → repo-relative-path registry. Consumers ask for content by
+ * canonical name; the file layout under the repo root is this helper's
+ * private concern and never crosses the interface. If the canonical layout
+ * is reorganized, only this map changes.
+ */
+declare const DOC_PATHS: {
+    readonly index: ".aide/docs/index.md";
+    readonly "aide-spec": ".aide/docs/aide-spec.md";
+    readonly "aide-template": ".aide/docs/aide-template.md";
+    readonly "progressive-disclosure": ".aide/docs/progressive-disclosure.md";
+    readonly "agent-readable-code": ".aide/docs/agent-readable-code.md";
+    readonly "automated-qa": ".aide/docs/automated-qa.md";
+    readonly "commands/aide/research": ".claude/commands/aide/research.md";
+    readonly "commands/aide/spec": ".claude/commands/aide/spec.md";
+    readonly "commands/aide/plan": ".claude/commands/aide/plan.md";
+    readonly "commands/aide/build": ".claude/commands/aide/build.md";
+    readonly "commands/aide/qa": ".claude/commands/aide/qa.md";
+    readonly "commands/aide/fix": ".claude/commands/aide/fix.md";
+    readonly "plan-aide": ".aide/docs/plan-aide.md";
+    readonly "todo-aide": ".aide/docs/todo-aide.md";
+    readonly "commands/aide/synthesize": ".claude/commands/aide/synthesize.md";
+    readonly "commands/aide/upgrade": ".claude/commands/aide/upgrade.md";
+    readonly "commands/aide/init": ".claude/commands/aide/init.md";
+    readonly "commands/aide/update-playbook": ".claude/commands/aide/update-playbook.md";
+    readonly "commands/aide/aide": ".claude/commands/aide.md";
+    readonly "commands/aide/refactor": ".claude/commands/aide/refactor.md";
+    readonly "agents/aide/aide-spec-writer": ".claude/agents/aide/aide-spec-writer.md";
+    readonly "agents/aide/aide-domain-expert": ".claude/agents/aide/aide-domain-expert.md";
+    readonly "agents/aide/aide-strategist": ".claude/agents/aide/aide-strategist.md";
+    readonly "agents/aide/aide-architect": ".claude/agents/aide/aide-architect.md";
+    readonly "agents/aide/aide-implementor": ".claude/agents/aide/aide-implementor.md";
+    readonly "agents/aide/aide-qa": ".claude/agents/aide/aide-qa.md";
+    readonly "agents/aide/aide-auditor": ".claude/agents/aide/aide-auditor.md";
+    readonly "agents/aide/aide-aligner": ".claude/agents/aide/aide-aligner.md";
+    readonly "commands/aide/align": ".claude/commands/aide/align.md";
+    readonly "cascading-alignment": ".aide/docs/cascading-alignment.md";
+    readonly "skills/study-playbook": ".claude/skills/study-playbook/SKILL.md";
+    readonly "skills/brain": ".claude/skills/brain/SKILL.md";
+};
+export type CanonicalDocName = keyof typeof DOC_PATHS;
+/**
+ * An entry in the methodology-doc enumeration. Consumers iterate this list
+ * to install the methodology subset into the host-side doc hub — the
+ * `canonical` field is the lookup key into `readCanonicalDoc`, and the
+ * `hostFilename` is the basename to write under the host hub directory.
+ */
+export interface MethodologyDocEntry {
+    readonly canonical: CanonicalDocName;
+    readonly hostFilename: string;
+}
+/**
+ * An entry in the agent-doc enumeration. Consumers iterate this list to
+ * install the pipeline agent files into the host's agent directory.
+ */
+export interface AgentDocEntry {
+    readonly canonical: CanonicalDocName;
+    readonly hostFilename: string;
+}
+/**
+ * An entry in the skill-doc enumeration. Consumers iterate this list to
+ * install skill templates into the host's skill directory.
+ */
+export interface SkillDocEntry {
+    readonly canonical: CanonicalDocName;
+    readonly hostPath: string;
+}
+/**
+ * Read one canonical doc verbatim from disk by canonical name. The returned
+ * string is byte-identical to the file on disk: no trimming, no normalization,
+ * no frontmatter stripping, no link rewriting. Composition is the consumer's
+ * concern and lives downstream. Throws a clear error naming the canonical
+ * name and the resolved path on any read failure — there is no fallback to
+ * an embedded default, because shipping invented content is exactly the
+ * failure mode this helper exists to prevent.
+ */
+export declare function readCanonicalDoc(name: CanonicalDocName): string;
+/** Return the idempotency marker used to detect existing methodology. */
+export declare function getMethodologyMarker(): string;
+/**
+ * Return the canonical enumeration of methodology docs that belong in the
+ * host-side doc hub. Consumers iterate the returned list rather than
+ * maintaining their own local copy — hardcoding the membership of "the
+ * methodology" anywhere else under the init subtree would be a second
+ * source of truth for the same decision and would silently drift on the
+ * next canonical-doc addition.
+ */
+export declare function listMethodologyDocs(): readonly MethodologyDocEntry[];
+/**
+ * Return the canonical enumeration of pipeline agent files that belong in
+ * the host's agent directory.
+ */
+export declare function listAgents(): readonly AgentDocEntry[];
+/**
+ * Return the canonical enumeration of skill templates that belong in the
+ * host's skill directory.
+ */
+export declare function listSkills(): readonly SkillDocEntry[];
+export {};

package/dist/tools/init/initContent/index.js

@@ -0,0 +1,162 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Idempotency marker that wraps the methodology block in the host's config
+ * file. Framework plumbing — not AIDE doctrine — so it is allowed to live as
+ * a literal here. Changing its bytes would break duplicate detection in every
+ * host project that already has a methodology block installed, so it must
+ * stay byte-stable across refactors.
+ */
+const METHODOLOGY_MARKER = "<!-- aide-methodology -->";
+/**
+ * Resolve the repo root relative to this module's own location. Anchoring to
+ * import.meta.url (not process.cwd()) is load-bearing: the MCP server is
+ * launched from the host project's directory, so cwd points there and would
+ * never find the canonical files. src/ and dist/ are siblings under the repo
+ * root at the same depth, so the same four-hop walk reaches the root whether
+ * this file runs from src/tools/init/initContent/ or dist/tools/init/initContent/.
+ * Canonical content lives under two subtrees of the repo root — `.aide/docs/`
+ * for methodology and `.claude/commands/aide/` for slash command templates —
+ * so DOC_PATHS values carry the subtree prefix and we resolve from the root.
+ */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(MODULE_DIR, "..", "..", "..", "..");
+/**
+ * Canonical-name → repo-relative-path registry. Consumers ask for content by
+ * canonical name; the file layout under the repo root is this helper's
+ * private concern and never crosses the interface. If the canonical layout
+ * is reorganized, only this map changes.
+ */
+const DOC_PATHS = {
+    "index": ".aide/docs/index.md",
+    "aide-spec": ".aide/docs/aide-spec.md",
+    "aide-template": ".aide/docs/aide-template.md",
+    "progressive-disclosure": ".aide/docs/progressive-disclosure.md",
+    "agent-readable-code": ".aide/docs/agent-readable-code.md",
+    "automated-qa": ".aide/docs/automated-qa.md",
+    "commands/aide/research": ".claude/commands/aide/research.md",
+    "commands/aide/spec": ".claude/commands/aide/spec.md",
+    "commands/aide/plan": ".claude/commands/aide/plan.md",
+    "commands/aide/build": ".claude/commands/aide/build.md",
+    "commands/aide/qa": ".claude/commands/aide/qa.md",
+    "commands/aide/fix": ".claude/commands/aide/fix.md",
+    "plan-aide": ".aide/docs/plan-aide.md",
+    "todo-aide": ".aide/docs/todo-aide.md",
+    "commands/aide/synthesize": ".claude/commands/aide/synthesize.md",
+    "commands/aide/upgrade": ".claude/commands/aide/upgrade.md",
+    "commands/aide/init": ".claude/commands/aide/init.md",
+    "commands/aide/update-playbook": ".claude/commands/aide/update-playbook.md",
+    "commands/aide/aide": ".claude/commands/aide.md",
+    "commands/aide/refactor": ".claude/commands/aide/refactor.md",
+    "agents/aide/aide-spec-writer": ".claude/agents/aide/aide-spec-writer.md",
+    "agents/aide/aide-domain-expert": ".claude/agents/aide/aide-domain-expert.md",
+    "agents/aide/aide-strategist": ".claude/agents/aide/aide-strategist.md",
+    "agents/aide/aide-architect": ".claude/agents/aide/aide-architect.md",
+    "agents/aide/aide-implementor": ".claude/agents/aide/aide-implementor.md",
+    "agents/aide/aide-qa": ".claude/agents/aide/aide-qa.md",
+    "agents/aide/aide-auditor": ".claude/agents/aide/aide-auditor.md",
+    "agents/aide/aide-aligner": ".claude/agents/aide/aide-aligner.md",
+    "commands/aide/align": ".claude/commands/aide/align.md",
+    "cascading-alignment": ".aide/docs/cascading-alignment.md",
+    "skills/study-playbook": ".claude/skills/study-playbook/SKILL.md",
+    "skills/brain": ".claude/skills/brain/SKILL.md",
+};
+/**
+ * The canonical list of methodology docs that ship into the host-side doc
+ * hub. Ordering is the hub's reading order and therefore stable — adding a
+ * new methodology doc appends to the end. Owning this list here (alongside
+ * the name-to-path registry it depends on) is load-bearing: the parent
+ * spec's single-reader invariant extends to enumeration, so downstream
+ * consumers iterate this list rather than hardcoding the membership of
+ * "the methodology" in their own source.
+ */
+const METHODOLOGY_DOCS = [
+    { canonical: "index", hostFilename: "index.md" },
+    { canonical: "aide-spec", hostFilename: "aide-spec.md" },
+    { canonical: "aide-template", hostFilename: "aide-template.md" },
+    { canonical: "progressive-disclosure", hostFilename: "progressive-disclosure.md" },
+    { canonical: "agent-readable-code", hostFilename: "agent-readable-code.md" },
+    { canonical: "automated-qa", hostFilename: "automated-qa.md" },
+    { canonical: "plan-aide", hostFilename: "plan-aide.md" },
+    { canonical: "todo-aide", hostFilename: "todo-aide.md" },
+    { canonical: "cascading-alignment", hostFilename: "cascading-alignment.md" },
+];
+/**
+ * The canonical list of pipeline agent files that ship into the host's
+ * agent directory. Ordering is pipeline phase order.
+ */
+const AGENT_DOCS = [
+    { canonical: "agents/aide/aide-spec-writer", hostFilename: "aide/aide-spec-writer.md" },
+    { canonical: "agents/aide/aide-domain-expert", hostFilename: "aide/aide-domain-expert.md" },
+    { canonical: "agents/aide/aide-strategist", hostFilename: "aide/aide-strategist.md" },
+    { canonical: "agents/aide/aide-architect", hostFilename: "aide/aide-architect.md" },
+    { canonical: "agents/aide/aide-implementor", hostFilename: "aide/aide-implementor.md" },
+    { canonical: "agents/aide/aide-qa", hostFilename: "aide/aide-qa.md" },
+    { canonical: "agents/aide/aide-auditor", hostFilename: "aide/aide-auditor.md" },
+    { canonical: "agents/aide/aide-aligner", hostFilename: "aide/aide-aligner.md" },
+];
+/**
+ * The canonical list of skill templates that ship into the host's skill
+ * directory.
+ */
+const SKILL_DOCS = [
+    { canonical: "skills/study-playbook", hostPath: "study-playbook/SKILL.md" },
+    { canonical: "skills/brain", hostPath: "brain/SKILL.md" },
+];
+/** Per-process cache. Populated from disk reads in this process only — never
+ * from build-time-embedded content. Keyed by canonical name. */
+const cache = new Map();
+/**
+ * Read one canonical doc verbatim from disk by canonical name. The returned
+ * string is byte-identical to the file on disk: no trimming, no normalization,
+ * no frontmatter stripping, no link rewriting. Composition is the consumer's
+ * concern and lives downstream. Throws a clear error naming the canonical
+ * name and the resolved path on any read failure — there is no fallback to
+ * an embedded default, because shipping invented content is exactly the
+ * failure mode this helper exists to prevent.
+ */
+export function readCanonicalDoc(name) {
+    const cached = cache.get(name);
+    if (cached !== undefined)
+        return cached;
+    const filePath = join(REPO_ROOT, DOC_PATHS[name]);
+    let bytes;
+    try {
+        bytes = readFileSync(filePath, "utf-8");
+    }
+    catch (cause) {
+        throw new Error(`initContent: canonical doc "${name}" not readable at ${filePath}`, { cause });
+    }
+    cache.set(name, bytes);
+    return bytes;
+}
+/** Return the idempotency marker used to detect existing methodology. */
+export function getMethodologyMarker() {
+    return METHODOLOGY_MARKER;
+}
+/**
+ * Return the canonical enumeration of methodology docs that belong in the
+ * host-side doc hub. Consumers iterate the returned list rather than
+ * maintaining their own local copy — hardcoding the membership of "the
+ * methodology" anywhere else under the init subtree would be a second
+ * source of truth for the same decision and would silently drift on the
+ * next canonical-doc addition.
+ */
+export function listMethodologyDocs() {
+    return METHODOLOGY_DOCS;
+}
+/**
+ * Return the canonical enumeration of pipeline agent files that belong in
+ * the host's agent directory.
+ */
+export function listAgents() {
+    return AGENT_DOCS;
+}
+/**
+ * Return the canonical enumeration of skill templates that belong in the
+ * host's skill directory.
+ */
+export function listSkills() {
+    return SKILL_DOCS;
+}

package/dist/tools/init/installAgents/index.d.ts

@@ -0,0 +1,12 @@
+import type { InitStep } from "../../../types/index.js";
+/**
+ * Return planning steps for each canonical AIDE pipeline agent file.
+ *
+ * For each agent named by `listAgents()`, checks whether the host file
+ * already exists. Returns `exists` for present files, `would-create` with
+ * the canonical content for absent files. A failing canonical read returns
+ * `would-skip` for that entry only.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default function installAgents(agentDir: string, displayPrefix?: string): Promise<InitStep[]>;

package/dist/tools/init/installAgents/index.js

@@ -0,0 +1,60 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { readCanonicalDoc, listAgents, } from "../../../tools/init/initContent/index.js";
+/** Check if a file exists on disk. */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Return planning steps for each canonical AIDE pipeline agent file.
+ *
+ * For each agent named by `listAgents()`, checks whether the host file
+ * already exists. Returns `exists` for present files, `would-create` with
+ * the canonical content for absent files. A failing canonical read returns
+ * `would-skip` for that entry only.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default async function installAgents(agentDir, displayPrefix = "agents") {
+    const steps = [];
+    for (const entry of listAgents()) {
+        const targetPath = join(agentDir, entry.hostFilename);
+        const displayName = `${displayPrefix}/${entry.hostFilename}`;
+        if (await fileExists(targetPath)) {
+            steps.push({
+                name: displayName,
+                status: "exists",
+                category: "agents",
+                filePath: targetPath,
+            });
+            continue;
+        }
+        let content;
+        try {
+            content = readCanonicalDoc(entry.canonical);
+        }
+        catch {
+            steps.push({
+                name: displayName,
+                status: "would-skip",
+                category: "agents",
+                filePath: targetPath,
+            });
+            continue;
+        }
+        steps.push({
+            name: displayName,
+            status: "would-create",
+            category: "agents",
+            filePath: targetPath,
+            content,
+        });
+    }
+    return steps;
+}

package/dist/tools/init/installMethodologyDocs/index.d.ts

@@ -0,0 +1,14 @@
+import type { InitStep } from "../../../types/index.js";
+/**
+ * Return planning steps for each canonical AIDE methodology doc.
+ *
+ * For each doc named by `listMethodologyDocs()` — including the hub index —
+ * checks whether the host file already exists. Returns `exists` for present
+ * files, `would-create` with the canonical content for absent files.
+ *
+ * A failing read of one canonical doc returns `would-skip` for that entry
+ * only and does not affect the other steps.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default function installMethodologyDocs(docHubDir: string, displayPrefix?: string): Promise<InitStep[]>;

package/dist/tools/init/installMethodologyDocs/index.js

@@ -0,0 +1,62 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { readCanonicalDoc, listMethodologyDocs, } from "../../../tools/init/initContent/index.js";
+/** Check if a file exists on disk. */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Return planning steps for each canonical AIDE methodology doc.
+ *
+ * For each doc named by `listMethodologyDocs()` — including the hub index —
+ * checks whether the host file already exists. Returns `exists` for present
+ * files, `would-create` with the canonical content for absent files.
+ *
+ * A failing read of one canonical doc returns `would-skip` for that entry
+ * only and does not affect the other steps.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default async function installMethodologyDocs(docHubDir, displayPrefix = ".aide") {
+    const steps = [];
+    for (const entry of listMethodologyDocs()) {
+        const targetPath = join(docHubDir, entry.hostFilename);
+        const displayName = `${displayPrefix}/${entry.hostFilename}`;
+        if (await fileExists(targetPath)) {
+            steps.push({
+                name: displayName,
+                status: "exists",
+                category: "methodology",
+                filePath: targetPath,
+            });
+            continue;
+        }
+        let content;
+        try {
+            content = readCanonicalDoc(entry.canonical);
+        }
+        catch {
+            steps.push({
+                name: displayName,
+                status: "would-skip",
+                category: "methodology",
+                filePath: targetPath,
+            });
+            continue;
+        }
+        steps.push({
+            name: displayName,
+            status: "would-create",
+            category: "methodology",
+            filePath: targetPath,
+            content,
+        });
+    }
+    return steps;
+}

package/dist/tools/init/installSkills/index.d.ts

@@ -0,0 +1,12 @@
+import type { InitStep } from "../../../types/index.js";
+/**
+ * Return planning steps for each canonical AIDE skill template.
+ *
+ * For each skill named by `listSkills()`, checks whether the host file
+ * already exists. Returns `exists` for present files, `would-create` with
+ * the canonical content for absent files. A failing canonical read returns
+ * `would-skip` for that entry only.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default function installSkills(skillDir: string, displayPrefix?: string): Promise<InitStep[]>;

package/dist/tools/init/installSkills/index.js

@@ -0,0 +1,60 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { readCanonicalDoc, listSkills, } from "../../../tools/init/initContent/index.js";
+/** Check if a file exists on disk. */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Return planning steps for each canonical AIDE skill template.
+ *
+ * For each skill named by `listSkills()`, checks whether the host file
+ * already exists. Returns `exists` for present files, `would-create` with
+ * the canonical content for absent files. A failing canonical read returns
+ * `would-skip` for that entry only.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default async function installSkills(skillDir, displayPrefix = "skills") {
+    const steps = [];
+    for (const entry of listSkills()) {
+        const targetPath = join(skillDir, entry.hostPath);
+        const displayName = `${displayPrefix}/${entry.hostPath}`;
+        if (await fileExists(targetPath)) {
+            steps.push({
+                name: displayName,
+                status: "exists",
+                category: "skills",
+                filePath: targetPath,
+            });
+            continue;
+        }
+        let content;
+        try {
+            content = readCanonicalDoc(entry.canonical);
+        }
+        catch {
+            steps.push({
+                name: displayName,
+                status: "would-skip",
+                category: "skills",
+                filePath: targetPath,
+            });
+            continue;
+        }
+        steps.push({
+            name: displayName,
+            status: "would-create",
+            category: "skills",
+            filePath: targetPath,
+            content,
+        });
+    }
+    return steps;
+}

package/dist/tools/init/provisionBrain/index.d.ts

@@ -0,0 +1,23 @@
+import type { InitStep } from "../../../types/index.js";
+/**
+ * Return planning steps for brain vault scaffolding and Obsidian MCP wiring.
+ *
+ * The function signature requires a resolved `brainPath` — the caller (agent)
+ * guarantees a path is provided before calling. Returns four `InitStep` items:
+ *
+ * 1. Vault scaffolding (category `"brain"`): `exists` if vault is already
+ *    populated, `would-create` with the directories list as JSON content.
+ * 2. Playbook hub (category `"brain"`): `exists` if `coding-playbook/coding-playbook.md`
+ *    is present, `would-create` with the five-section Markdown template when absent.
+ *    Idempotency is per-file — checked independently of the vault-level step.
+ * 3. Vault CLAUDE.md (category `"brain"`): `exists` if `CLAUDE.md` is present at the
+ *    vault root, `would-create` with the navigation guide template when absent.
+ *    Idempotency is per-file — checked independently of the vault-level step.
+ * 4. Obsidian MCP entry (category `"mcp"`): `exists` if the obsidian key is
+ *    already in the config, `would-create` with a `McpPrescription`.
+ *    If the config file is malformed JSON, returns `would-create` with
+ *    `configMalformed: true`.
+ *
+ * No step writes to disk — this helper is a planner only.
+ */
+export default function provisionBrain(brainPath: string, mcpConfigPath: string): Promise<InitStep[]>;