@aidemd-mcp/server 0.2.0

package/dist/tools/discover/buildAncestorChain/index.js

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import { join, relative, dirname } from "node:path";
+import parseFrontmatter from "../../../util/parseFrontmatter/index.js";
+/**
+ * Walk from `targetPath` up to `root`, collecting .aide specs at each directory
+ * level along the way. Renders them top-down (root first, target-parent last)
+ * so agents read broadest context first before drilling into the subtree.
+ *
+ * The target directory's own specs are excluded — those appear in the subtree
+ * section rendered by buildTree. This function is concerned only with the
+ * inherited lineage above the target.
+ *
+ * Root-level spec detection uses the canonical `.aide/intent.aide` path
+ * (per aide-spec.md placement rules). At all other directory levels, checks
+ * `.aide` first, then falls back to `intent.aide`.
+ *
+ * Returns `"Ancestor chain:\n" + lines` when at least one ancestor spec is
+ * found, or an empty string if the target is the root (no ancestors above it).
+ */
+export default async function buildAncestorChain(root, targetPath) {
+    // Normalize to absolute paths
+    const absRoot = root.replace(/\\/g, "/");
+    const absTarget = targetPath.replace(/\\/g, "/");
+    // No ancestors when the target IS the root
+    if (absTarget === absRoot)
+        return "";
+    /** Walk upward from target's parent to root, collecting directory levels. */
+    const levels = [];
+    let current = dirname(absTarget);
+    while (true) {
+        levels.push(current);
+        if (current === absRoot)
+            break;
+        const parent = dirname(current);
+        // Guard against hitting the filesystem root (should not happen in practice)
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // levels is ordered target-parent → root; reverse for root-first rendering
+    levels.reverse();
+    /** Try to read a file, returning null if it does not exist. */
+    async function tryRead(filePath) {
+        try {
+            return await readFile(filePath, "utf-8");
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Resolve which spec file to use at a given directory level, if any. */
+    async function resolveSpec(dir) {
+        const isRoot = dir === absRoot;
+        if (isRoot) {
+            // Root-level spec lives at .aide/intent.aide per AIDE placement rules
+            const rootSpec = join(dir, ".aide", "intent.aide");
+            const content = await tryRead(rootSpec);
+            if (content !== null)
+                return { specPath: rootSpec, content };
+            return null;
+        }
+        // Non-root: check .aide first, then intent.aide
+        const dotAide = join(dir, ".aide");
+        const intentAide = join(dir, "intent.aide");
+        const dotAideContent = await tryRead(dotAide);
+        if (dotAideContent !== null)
+            return { specPath: dotAide, content: dotAideContent };
+        const intentAideContent = await tryRead(intentAide);
+        if (intentAideContent !== null)
+            return { specPath: intentAide, content: intentAideContent };
+        return null;
+    }
+    const lines = [];
+    for (const dir of levels) {
+        const spec = await resolveSpec(dir);
+        if (!spec)
+            continue;
+        const { frontmatter } = parseFrontmatter(spec.content);
+        const description = frontmatter?.description;
+        const status = frontmatter?.status;
+        // Compute a display path relative to the project root
+        const rel = relative(absRoot, spec.specPath).replace(/\\/g, "/");
+        const displayPath = rel || spec.specPath;
+        let line = `  ${displayPath}`;
+        if (description) {
+            line += ` — ${description}`;
+        }
+        // Status badge renders whenever set, regardless of whether description is present
+        if (status === "aligned" || status === "misaligned") {
+            line += ` [${status}]`;
+        }
+        // If no description and no status, show path alone (no em-dash, no fabrication)
+        lines.push(line);
+    }
+    if (lines.length === 0)
+        return "";
+    return `Ancestor chain:\n${lines.join("\n")}`;
+}

package/dist/tools/discover/buildTree/index.d.ts

@@ -0,0 +1,9 @@
+import type { AideFile } from "../../../types/index.js";
+/**
+ * Build a progressive disclosure tree string from discovered .aide files.
+ * Collapses directories with no .aide files. Each entry shows:
+ * - Relative path with tree-drawing characters
+ * - File type tag in brackets: [intent], [research], [plan], [todo]
+ * - Truncated summary (~80 chars) from first paragraph
+ */
+export default function buildTree(files: AideFile[], root: string): string;

package/dist/tools/discover/buildTree/index.js

@@ -0,0 +1,57 @@
+import { basename } from "node:path";
+/** Sort priority for file types: intent first, then research, plan, then todo. */
+const TYPE_ORDER = { intent: 0, research: 1, plan: 2, todo: 3 };
+/** Group files by their parent directory path. */
+function groupByDir(files) {
+    const groups = new Map();
+    for (const file of files) {
+        const parts = file.relativePath.split("/");
+        const dir = parts.slice(0, -1).join("/") || ".";
+        const group = groups.get(dir) ?? [];
+        group.push(file);
+        groups.set(dir, group);
+    }
+    return groups;
+}
+/** Sort files within a directory by type priority, then by name. */
+function sortFiles(files) {
+    return [...files].sort((a, b) => {
+        const typeA = TYPE_ORDER[a.type];
+        const typeB = TYPE_ORDER[b.type];
+        if (typeA !== typeB)
+            return typeA - typeB;
+        return basename(a.relativePath).localeCompare(basename(b.relativePath));
+    });
+}
+/**
+ * Build a progressive disclosure tree string from discovered .aide files.
+ * Collapses directories with no .aide files. Each entry shows:
+ * - Relative path with tree-drawing characters
+ * - File type tag in brackets: [intent], [research], [plan], [todo]
+ * - Truncated summary (~80 chars) from first paragraph
+ */
+export default function buildTree(files, root) {
+    if (files.length === 0)
+        return "";
+    const groups = groupByDir(files);
+    const sortedDirs = [...groups.keys()].sort();
+    const lines = [];
+    for (let d = 0; d < sortedDirs.length; d++) {
+        const dir = sortedDirs[d];
+        const dirFiles = sortFiles(groups.get(dir));
+        // Directory header
+        lines.push(`${dir}/`);
+        for (let f = 0; f < dirFiles.length; f++) {
+            const file = dirFiles[f];
+            const isLastFile = f === dirFiles.length - 1;
+            const connector = isLastFile ? "└──" : "├──";
+            const name = basename(file.relativePath);
+            const tag = `[${file.type}]`;
+            const summary = file.summary ? ` — ${file.summary}` : "";
+            lines.push(`  ${connector} ${name} ${tag}${summary}`);
+        }
+        if (d < sortedDirs.length - 1)
+            lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/tools/discover/index.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare const DiscoverInput: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path?: string | undefined;
+}, {
+    path?: string | undefined;
+}>;
+/**
+ * Scan for .aide files and return a progressive disclosure tree map.
+ *
+ * Without a path: shallow scan of the entire project — returns file locations
+ * and types only (no summaries, no content reading). This is the project map
+ * the agent uses to understand where specs live.
+ *
+ * With a path: deep scan of that subtree — includes summaries extracted from
+ * file content, plus anomaly warnings. This is how the agent drills into the
+ * area it's working on.
+ */
+export default function discover(root: string, path?: string): Promise<string>;

package/dist/tools/discover/index.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { basename, join } from "node:path";
+import scan from "../../util/scan/index.js";
+import buildTree from "../../tools/discover/buildTree/index.js";
+import buildAncestorChain from "./buildAncestorChain/index.js";
+import { detectAnomalies } from "../../util/classify/index.js";
+export const DiscoverInput = z.object({
+    path: z.string().optional().describe("Subdirectory to scan (defaults to entire project)"),
+});
+/**
+ * Scan for .aide files and return a progressive disclosure tree map.
+ *
+ * Without a path: shallow scan of the entire project — returns file locations
+ * and types only (no summaries, no content reading). This is the project map
+ * the agent uses to understand where specs live.
+ *
+ * With a path: deep scan of that subtree — includes summaries extracted from
+ * file content, plus anomaly warnings. This is how the agent drills into the
+ * area it's working on.
+ */
+export default async function discover(root, path) {
+    const shallow = !path;
+    const result = await scan(root, path, shallow);
+    const { files } = result;
+    if (files.length === 0) {
+        return "No .aide files found." + (path ? ` (searched in ${path})` : "");
+    }
+    const projectName = basename(root);
+    const header = `${projectName} project — ${files.length} spec${files.length === 1 ? "" : "s"} found`;
+    const tree = buildTree(files, root);
+    // Only run anomaly detection and ancestor chain on deep (scoped) scans
+    let ancestorChain = "";
+    let warningBlock = "";
+    if (!shallow) {
+        ancestorChain = await buildAncestorChain(root, join(root, path));
+        const anomalies = await detectAnomalies(files, root);
+        if (anomalies.length > 0) {
+            const lines = anomalies.map((w) => `  ${w.path} — ${w.message}`);
+            warningBlock = `\n\n⚠ Warnings:\n${lines.join("\n")}`;
+        }
+    }
+    // Build output: header + optional ancestor chain + tree + optional warnings
+    // Each block separated by a blank line when present
+    const parts = [header];
+    if (ancestorChain)
+        parts.push(ancestorChain);
+    parts.push(tree);
+    return parts.join("\n\n") + warningBlock;
+}

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

@@ -0,0 +1,30 @@
+import type { InitStep } from "../../../types/index.js";
+/**
+ * Apply mode writer — turns a plan into disk state and returns the manifest
+ * the agent reports to the user.
+ *
+ * For each step:
+ * - `"would-create"` file steps (no `prescription` field, not a brain vault step):
+ *   creates parent directories and writes `content` to `filePath`. Returns the
+ *   step with `status` changed to `"created"` and `content` removed.
+ * - `"would-create"` brain vault steps (category `"brain"`) — two sub-types:
+ *   - **Directory step** (`filePath` has no extension): parses `content` as a
+ *     JSON array of directory names, creates each under `filePath` with
+ *     `recursive: true`. Returns with `status: "created"` and `content` removed.
+ *   - **File step** (`filePath` has a file extension, e.g. `.md`): creates the
+ *     parent directory and writes `content` to `filePath`. Used for content
+ *     templates such as the playbook hub and vault CLAUDE.md. Returns with
+ *     `status: "created"` and `content` removed.
+ * - `"would-create"` steps with a `prescription` field (MCP steps): passed
+ *   through unchanged — the agent merges prescriptions itself. Never written
+ *   by this helper.
+ * - `"would-create"` IDE VS Code steps (name contains "VS Code"): passed
+ *   through unchanged — requires the external `code` CLI. The agent executes
+ *   the extension install command.
+ * - `"exists"`, `"would-skip"` steps: passed through unchanged.
+ * - `"created"` steps (already applied): passed through unchanged (idempotent).
+ *
+ * The `prescription` field is never stripped — MCP steps keep their
+ * prescription so the agent can perform the merge.
+ */
+export default function applySteps(steps: InitStep[]): Promise<InitStep[]>;

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

@@ -0,0 +1,76 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, extname } from "node:path";
+/**
+ * Apply mode writer — turns a plan into disk state and returns the manifest
+ * the agent reports to the user.
+ *
+ * For each step:
+ * - `"would-create"` file steps (no `prescription` field, not a brain vault step):
+ *   creates parent directories and writes `content` to `filePath`. Returns the
+ *   step with `status` changed to `"created"` and `content` removed.
+ * - `"would-create"` brain vault steps (category `"brain"`) — two sub-types:
+ *   - **Directory step** (`filePath` has no extension): parses `content` as a
+ *     JSON array of directory names, creates each under `filePath` with
+ *     `recursive: true`. Returns with `status: "created"` and `content` removed.
+ *   - **File step** (`filePath` has a file extension, e.g. `.md`): creates the
+ *     parent directory and writes `content` to `filePath`. Used for content
+ *     templates such as the playbook hub and vault CLAUDE.md. Returns with
+ *     `status: "created"` and `content` removed.
+ * - `"would-create"` steps with a `prescription` field (MCP steps): passed
+ *   through unchanged — the agent merges prescriptions itself. Never written
+ *   by this helper.
+ * - `"would-create"` IDE VS Code steps (name contains "VS Code"): passed
+ *   through unchanged — requires the external `code` CLI. The agent executes
+ *   the extension install command.
+ * - `"exists"`, `"would-skip"` steps: passed through unchanged.
+ * - `"created"` steps (already applied): passed through unchanged (idempotent).
+ *
+ * The `prescription` field is never stripped — MCP steps keep their
+ * prescription so the agent can perform the merge.
+ */
+export default async function applySteps(steps) {
+    return Promise.all(steps.map(applyStep));
+}
+async function applyStep(step) {
+    // Only act on would-create steps that haven't been applied yet
+    if (step.status !== "would-create") {
+        return step;
+    }
+    // MCP steps carry a prescription — the agent merges them; never written here
+    if (step.prescription !== undefined) {
+        return step;
+    }
+    // IDE VS Code steps require the external `code` CLI — pass through with
+    // instructions so the agent knows what command to run
+    if (step.category === "ide" && step.name.includes("VS Code")) {
+        return { ...step, instructions: `code --install-extension ${step.filePath}` };
+    }
+    // Brain step — two sub-types distinguished by whether filePath has an extension
+    if (step.category === "brain") {
+        if (!step.content) {
+            // No content means placeholder (filePath is empty string) — pass through
+            return step;
+        }
+        if (extname(step.filePath)) {
+            // File step — content is a template destined for a specific file path
+            await mkdir(dirname(step.filePath), { recursive: true });
+            await writeFile(step.filePath, step.content, "utf-8");
+        }
+        else {
+            // Directory step — content is a JSON array of subdirectory names to create
+            const dirs = JSON.parse(step.content);
+            await Promise.all(dirs.map((dir) => mkdir(`${step.filePath}/${dir}`, { recursive: true })));
+        }
+        const { content: _content, ...rest } = step;
+        return { ...rest, status: "created" };
+    }
+    // Regular file step — write content to filePath
+    if (step.content !== undefined) {
+        await mkdir(dirname(step.filePath), { recursive: true });
+        await writeFile(step.filePath, step.content, "utf-8");
+        const { content: _content, ...rest } = step;
+        return { ...rest, status: "created" };
+    }
+    // No content and not a special case — pass through unchanged
+    return step;
+}

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

@@ -0,0 +1,21 @@
+import type { InitStep } from "../../../types/index.js";
+/**
+ * Inspect Zed settings and return a planning step for .aide file association.
+ *
+ * Returns `exists` when the `*.aide` entry is already in `.zed/settings.json`.
+ * Returns `would-create` with the full patched settings JSON as `content`
+ * when the entry is absent.
+ *
+ * This function never writes to disk — it is a planner only.
+ */
+export declare function configureZed(projectRoot: string): Promise<InitStep>;
+/**
+ * Check VS Code extension installation status and return a planning step.
+ *
+ * Returns `exists` when the aide-markdown extension is already installed.
+ * Returns `would-skip` when `code` CLI is unavailable or the .vsix is missing
+ * (the agent will install when confirmed).
+ *
+ * This function never writes to disk — it is a planner only.
+ */
+export declare function configureVscode(extensionsDir: string): Promise<InitStep>;

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

@@ -0,0 +1,135 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Read a file, returning empty string if it doesn't exist. */
+async function safeReadFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Inspect Zed settings and return a planning step for .aide file association.
+ *
+ * Returns `exists` when the `*.aide` entry is already in `.zed/settings.json`.
+ * Returns `would-create` with the full patched settings JSON as `content`
+ * when the entry is absent.
+ *
+ * This function never writes to disk — it is a planner only.
+ */
+export async function configureZed(projectRoot) {
+    const settingsPath = join(projectRoot, ".zed", "settings.json");
+    const filePath = settingsPath;
+    const existing = await safeReadFile(settingsPath);
+    if (existing) {
+        try {
+            const settings = JSON.parse(existing);
+            const fileTypes = settings.file_types || {};
+            const mdTypes = fileTypes.Markdown || [];
+            if (mdTypes.includes("*.aide")) {
+                return {
+                    name: "Zed config",
+                    status: "exists",
+                    category: "ide",
+                    filePath,
+                };
+            }
+            mdTypes.push("*.aide");
+            fileTypes.Markdown = mdTypes;
+            settings.file_types = fileTypes;
+            return {
+                name: "Zed config",
+                status: "would-create",
+                category: "ide",
+                filePath,
+                content: JSON.stringify(settings, null, 2) + "\n",
+            };
+        }
+        catch {
+            return {
+                name: "Zed config",
+                status: "would-skip",
+                category: "ide",
+                filePath,
+            };
+        }
+    }
+    const settings = { file_types: { Markdown: ["*.aide"] } };
+    return {
+        name: "Zed config",
+        status: "would-create",
+        category: "ide",
+        filePath,
+        content: JSON.stringify(settings, null, 2) + "\n",
+    };
+}
+/**
+ * Check VS Code extension installation status and return a planning step.
+ *
+ * Returns `exists` when the aide-markdown extension is already installed.
+ * Returns `would-skip` when `code` CLI is unavailable or the .vsix is missing
+ * (the agent will install when confirmed).
+ *
+ * This function never writes to disk — it is a planner only.
+ */
+export async function configureVscode(extensionsDir) {
+    const vsixPath = resolve(extensionsDir, "aide-markdown-0.0.1.vsix");
+    // filePath points to the vsix — not a file the agent writes, but a meaningful
+    // path for the agent to display when reporting extension installation.
+    const filePath = vsixPath;
+    // Check if `code` CLI is on PATH
+    try {
+        await execFileAsync("code", ["--version"]);
+    }
+    catch {
+        return {
+            name: "VS Code extension",
+            status: "would-skip",
+            category: "ide",
+            filePath,
+        };
+    }
+    // Check if already installed
+    try {
+        const { stdout } = await execFileAsync("code", ["--list-extensions"]);
+        if (stdout.toLowerCase().includes("aide-markdown")) {
+            return {
+                name: "VS Code extension",
+                status: "exists",
+                category: "ide",
+                filePath,
+            };
+        }
+    }
+    catch {
+        return {
+            name: "VS Code extension",
+            status: "would-skip",
+            category: "ide",
+            filePath,
+        };
+    }
+    // Check if the .vsix is present
+    try {
+        await readFile(vsixPath);
+    }
+    catch {
+        return {
+            name: "VS Code extension",
+            status: "would-skip",
+            category: "ide",
+            filePath,
+        };
+    }
+    // The agent will install when the user confirms — report as would-create
+    return {
+        name: "VS Code extension",
+        status: "would-create",
+        category: "ide",
+        filePath,
+    };
+}

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

@@ -0,0 +1,11 @@
+import type { FrameworkType, FrameworkConfig } from "../../../types/index.js";
+/**
+ * Detect the agent framework in use, or return config for a specified framework.
+ * Checks for framework-specific marker files/directories. Defaults to Claude Code
+ * if nothing is detected.
+ *
+ * Brain vault resolution is NOT performed here — it is a separate concern handled
+ * by `resolveBrainHints`, which the init orchestrator calls independently. This
+ * keeps framework detection focused on framework-related config only.
+ */
+export default function detectFramework(root: string, framework?: FrameworkType): Promise<FrameworkConfig>;

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

@@ -0,0 +1,53 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Per-framework path resolution for aide_init. The `docHubDir` field is
+ * uniform across frameworks on purpose: the host-side doc hub is a
+ * framework-agnostic surface (the agent crawls it via relative links, not
+ * via framework-specific command wiring), so there is no reason to
+ * diverge. Keeping the value uniform also makes it trivial to change the
+ * hub location across every framework in a single edit.
+ */
+const FRAMEWORK_CONFIGS = {
+    claude: { configPath: "CLAUDE.md", commandDir: ".claude/commands", mcpConfigPath: ".mcp.json", docHubDir: ".aide/docs", agentDir: ".claude/agents", skillDir: ".claude/skills" },
+    cursor: { configPath: ".cursorrules", commandDir: ".cursor/commands", mcpConfigPath: ".cursor/mcp.json", docHubDir: ".aide/docs", agentDir: ".cursor/agents", skillDir: ".cursor/skills" },
+    windsurf: { configPath: ".windsurfrules", commandDir: ".windsurf/commands", mcpConfigPath: ".windsurf/mcp.json", docHubDir: ".aide/docs", agentDir: ".windsurf/agents", skillDir: ".windsurf/skills" },
+    copilot: { configPath: ".github/copilot-instructions.md", commandDir: ".github/commands", mcpConfigPath: ".mcp.json", docHubDir: ".aide/docs", agentDir: ".github/agents", skillDir: ".github/skills" },
+};
+const DETECTION_SIGNALS = [
+    { framework: "claude", paths: [".claude", "CLAUDE.md"] },
+    { framework: "cursor", paths: [".cursor", ".cursorrules"] },
+    { framework: "windsurf", paths: [".windsurf", ".windsurfrules"] },
+    { framework: "copilot", paths: [".github/copilot-instructions.md"] },
+];
+/** Check if a path exists. */
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect the agent framework in use, or return config for a specified framework.
+ * Checks for framework-specific marker files/directories. Defaults to Claude Code
+ * if nothing is detected.
+ *
+ * Brain vault resolution is NOT performed here — it is a separate concern handled
+ * by `resolveBrainHints`, which the init orchestrator calls independently. This
+ * keeps framework detection focused on framework-related config only.
+ */
+export default async function detectFramework(root, framework) {
+    if (framework)
+        return { framework, ...FRAMEWORK_CONFIGS[framework] };
+    for (const signal of DETECTION_SIGNALS) {
+        for (const path of signal.paths) {
+            if (await exists(join(root, path))) {
+                return { framework: signal.framework, ...FRAMEWORK_CONFIGS[signal.framework] };
+            }
+        }
+    }
+    return { framework: "claude", ...FRAMEWORK_CONFIGS.claude };
+}

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

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { FrameworkType, InitResult } from "../../types/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 declare const InitInput: z.ZodObject<{
+    framework: z.ZodOptional<z.ZodEnum<["claude", "cursor", "windsurf", "copilot"]>>;
+    path: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodEnum<["framework", "methodology", "commands", "agents", "skills", "mcp", "brain", "ide"]>>;
+    brainPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    framework?: "claude" | "cursor" | "windsurf" | "copilot" | undefined;
+    path?: string | undefined;
+    category?: "framework" | "methodology" | "commands" | "agents" | "skills" | "mcp" | "brain" | "ide" | undefined;
+    brainPath?: string | undefined;
+}, {
+    framework?: "claude" | "cursor" | "windsurf" | "copilot" | undefined;
+    path?: string | undefined;
+    category?: "framework" | "methodology" | "commands" | "agents" | "skills" | "mcp" | "brain" | "ide" | undefined;
+    brainPath?: string | undefined;
+}>;
+/**
+ * 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 function init(root: string, framework?: FrameworkType, path?: string, brainPath?: string): Promise<InitResult>;