@aidemd-mcp/server 0.2.0

package/dist/cli/TreePanel/index.js

@@ -0,0 +1,65 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+/** Type-tag display labels keyed by AideFileType. */
+const TYPE_TAG = {
+    intent: "intent",
+    research: "research",
+    plan: "plan",
+    todo: "todo",
+};
+/** Type-tag colors keyed by AideFileType. */
+const TYPE_COLOR = {
+    intent: "cyan",
+    research: "yellow",
+    plan: "blue",
+    todo: "magenta",
+};
+/** Render one flat node row in the tree. */
+function renderRow(flatNode, index, cursorIndex, isDeepView, expandedDirs, width) {
+    const { node, depth } = flatNode;
+    const isCursor = index === cursorIndex;
+    const indent = "  ".repeat(depth);
+    if (node.kind === "dir") {
+        const label = node.path === "." ? ". /" : `${node.path}/`;
+        const expandIndicator = expandedDirs.has(node.path) ? "v " : "> ";
+        return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, color: isCursor ? "white" : "gray", children: [indent, expandIndicator, label] }) }, `dir-${node.path}-${index}`));
+    }
+    // File node — render as a single <Text> to prevent Ink from wrapping mid-element.
+    const { file } = node;
+    const filename = file.relativePath.split("/").pop() ?? file.relativePath;
+    const connector = "└── ";
+    const tag = TYPE_TAG[file.type] ?? file.type;
+    const tagColor = TYPE_COLOR[file.type] ?? "white";
+    const prefix = `${indent}${connector}${filename} `;
+    const tagStr = `[${tag}]`;
+    // Truncate summary to fit within available panel width.
+    const fixedLen = prefix.length + tagStr.length;
+    const remaining = width - fixedLen;
+    let summary = "";
+    if (isDeepView && file.summary && remaining > 10) {
+        const full = ` — ${file.summary}`;
+        summary = full.length <= remaining ? full : `${full.slice(0, remaining - 3)}…`;
+    }
+    return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, backgroundColor: isCursor ? "blue" : undefined, wrap: "truncate", children: [prefix, _jsx(Text, { color: tagColor, children: tagStr }), summary ? _jsx(Text, { color: "gray", children: summary }) : null] }) }, `file-${file.relativePath}-${index}`));
+}
+/**
+ * Renders the left-panel tree of .aide files with cursor highlighting and optional summaries.
+ * Receives pre-filtered visibleNodes from App — manages no state and performs no filtering.
+ * Shows expand/collapse indicators on dir nodes and context-aware footer hints.
+ */
+export default function TreePanel({ visibleNodes, cursorIndex, searchFilter, isDeepView, expandedDirs, cursorOnDir, cursorDirExpanded, width, }) {
+    let hintText;
+    if (cursorOnDir) {
+        const escClear = searchFilter ? "  [esc] clear" : "";
+        hintText = cursorDirExpanded
+            ? `${escClear}  [↑↓] navigate  [enter] collapse  [tab] deep view`
+            : `${escClear}  [↑↓] navigate  [enter] expand  [tab] deep view`;
+    }
+    else if (searchFilter) {
+        hintText = "  [esc] clear  [↑↓] navigate  [enter] drill in";
+    }
+    else {
+        hintText = "  [↑↓] navigate  [enter] drill in  [tab] deep view";
+    }
+    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, children: [visibleNodes.length === 0 ? (_jsxs(Text, { color: "gray", children: ["  No results for \"", searchFilter, "\""] })) : (visibleNodes.map((fn, i) => renderRow(fn, i, cursorIndex, isDeepView, expandedDirs, width))), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: hintText }) })] }));
+}

package/dist/cli/buildTreeData/index.d.ts

@@ -0,0 +1,7 @@
+import type { AideFile, TreeNode } from "../../types/index.js";
+/**
+ * Convert a flat AideFile[] from scan() into a hierarchical TreeNode[] for TUI rendering.
+ * Directories are sorted alphabetically; files within each directory are sorted by type priority.
+ * Root-level files appear under the "." directory group.
+ */
+export default function buildTreeData(files: AideFile[]): TreeNode[];

package/dist/cli/buildTreeData/index.js

@@ -0,0 +1,51 @@
+/** Priority order for sorting files within a directory: intent first, then research, plan, todo. */
+const TYPE_PRIORITY = {
+    intent: 0,
+    research: 1,
+    plan: 2,
+    todo: 3,
+};
+/** Derive the display directory path for a file: POSIX-normalized dirname, or "." for root files. */
+function dirOf(file) {
+    const parts = file.relativePath.split("/");
+    if (parts.length === 1)
+        return ".";
+    return parts.slice(0, -1).join("/");
+}
+/**
+ * Convert a flat AideFile[] from scan() into a hierarchical TreeNode[] for TUI rendering.
+ * Directories are sorted alphabetically; files within each directory are sorted by type priority.
+ * Root-level files appear under the "." directory group.
+ */
+export default function buildTreeData(files) {
+    // Group files by their directory path.
+    const byDir = new Map();
+    for (const file of files) {
+        const dir = dirOf(file);
+        const group = byDir.get(dir) ?? [];
+        group.push(file);
+        byDir.set(dir, group);
+    }
+    // Sort files within each directory by type priority, then by filename.
+    for (const group of byDir.values()) {
+        group.sort((a, b) => {
+            const pd = TYPE_PRIORITY[a.type] - TYPE_PRIORITY[b.type];
+            if (pd !== 0)
+                return pd;
+            return a.relativePath.localeCompare(b.relativePath);
+        });
+    }
+    // Sort directories alphabetically, root "." first.
+    const dirs = [...byDir.keys()].sort((a, b) => {
+        if (a === ".")
+            return -1;
+        if (b === ".")
+            return 1;
+        return a.localeCompare(b);
+    });
+    return dirs.map((dir) => ({
+        kind: "dir",
+        path: dir,
+        children: (byDir.get(dir) ?? []).map((file) => ({ kind: "file", file })),
+    }));
+}

package/dist/cli/findPrimaryIntent/index.d.ts

@@ -0,0 +1,12 @@
+import type { AideFile, TreeNode } from "../../types/index.js";
+/**
+ * Given a dir-kind TreeNode, returns the first file child whose type is "intent"
+ * (i.e. a `.aide` or `intent.aide` file), or null if the dir has no intent child.
+ *
+ * This is a pure synchronous function — it reads from the already-loaded TreeNode
+ * data, not the filesystem. Its primary role is powering the detail panel auto-load:
+ * when the cursor lands on a dir node, App calls findPrimaryIntent to obtain the
+ * intent file so the detail panel can display its frontmatter without requiring
+ * the user to expand and explicitly select the file.
+ */
+export default function findPrimaryIntent(node: TreeNode): AideFile | null;

package/dist/cli/findPrimaryIntent/index.js

@@ -0,0 +1,20 @@
+/**
+ * Given a dir-kind TreeNode, returns the first file child whose type is "intent"
+ * (i.e. a `.aide` or `intent.aide` file), or null if the dir has no intent child.
+ *
+ * This is a pure synchronous function — it reads from the already-loaded TreeNode
+ * data, not the filesystem. Its primary role is powering the detail panel auto-load:
+ * when the cursor lands on a dir node, App calls findPrimaryIntent to obtain the
+ * intent file so the detail panel can display its frontmatter without requiring
+ * the user to expand and explicitly select the file.
+ */
+export default function findPrimaryIntent(node) {
+    if (node.kind !== "dir")
+        return null;
+    for (const child of node.children) {
+        if (child.kind === "file" && child.file.type === "intent") {
+            return child.file;
+        }
+    }
+    return null;
+}

package/dist/cli/flattenTree/index.d.ts

@@ -0,0 +1,16 @@
+import type { TreeNode } from "../../types/index.js";
+/** A flattened node with its depth for rendering and cursor indexing. */
+export interface FlatNode {
+    node: TreeNode;
+    depth: number;
+}
+/**
+ * Convert a hierarchical TreeNode[] into a flat array of { node, depth } entries
+ * in display order (depth-first). Dir nodes always appear as cursor stops.
+ * A dir's children are only emitted when the dir's path is in `expandedDirs`.
+ *
+ * @param nodes - The tree nodes to flatten.
+ * @param expandedDirs - Set of dir paths that are currently expanded. Defaults to empty Set (all collapsed).
+ * @param depth - Current recursion depth (internal use only).
+ */
+export default function flattenTree(nodes: TreeNode[], expandedDirs?: Set<string>, depth?: number): FlatNode[];

package/dist/cli/flattenTree/index.js

@@ -0,0 +1,20 @@
+/**
+ * Convert a hierarchical TreeNode[] into a flat array of { node, depth } entries
+ * in display order (depth-first). Dir nodes always appear as cursor stops.
+ * A dir's children are only emitted when the dir's path is in `expandedDirs`.
+ *
+ * @param nodes - The tree nodes to flatten.
+ * @param expandedDirs - Set of dir paths that are currently expanded. Defaults to empty Set (all collapsed).
+ * @param depth - Current recursion depth (internal use only).
+ */
+export default function flattenTree(nodes, expandedDirs = new Set(), depth = 0) {
+    const result = [];
+    for (const node of nodes) {
+        result.push({ node, depth });
+        if (node.kind === "dir" && expandedDirs.has(node.path)) {
+            for (const child of flattenTree(node.children, expandedDirs, depth + 1))
+                result.push(child);
+        }
+    }
+    return result;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { existsSync } from "node:fs";
+import scan from "../util/scan/index.js";
+import buildTreeData from "../cli/buildTreeData/index.js";
+import App from "../cli/App/index.js";
+const root = process.argv[2] ?? process.cwd();
+if (!existsSync(root)) {
+    process.stderr.write(`aide-tree: path not found: ${root}\nUsage: aide-tree [project-root]\n`);
+    process.exit(1);
+}
+const result = await scan(root, undefined, true);
+const initialNodes = buildTreeData(result.files);
+render(_jsx(App, { root: root, initialNodes: initialNodes }));

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runInit(cwd: string, write?: (line: string) => void): Promise<number>;

package/dist/cli/init/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import writeMcpEntry from "./writeMcpEntry/index.js";
+import writeInitCommand from "./writeInitCommand/index.js";
+const MCP_LABEL = ".mcp.json";
+const CMD_LABEL = ".claude/commands/aide/init.md";
+export async function runInit(cwd, write = (line) => process.stdout.write(line + "\n")) {
+    const mcpResult = await writeMcpEntry(cwd);
+    const cmdResult = await writeInitCommand(cwd);
+    write(`[${mcpResult.status}] ${MCP_LABEL} — ${mcpResult.message}`);
+    write(`[${cmdResult.status}] ${CMD_LABEL} — ${cmdResult.message}`);
+    if (mcpResult.status === "exists" && cmdResult.status === "exists") {
+        write("Already set up. Run /aide:init in Claude Code to continue.");
+        return 0;
+    }
+    write("Done. Open Claude Code and run /aide:init to complete setup.");
+    return 0;
+}
+(async () => {
+    if (process.argv.includes("--help")) {
+        process.stdout.write("Usage: npx @aidemd-mcp/server init\n" +
+            "Wires the AIDE MCP server and init command into the current project.\n");
+        process.exit(0);
+    }
+    try {
+        const code = await runInit(process.cwd());
+        process.exit(code);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${message}\n`);
+        process.exit(1);
+    }
+})();

package/dist/cli/init/writeInitCommand/index.d.ts

@@ -0,0 +1,13 @@
+export interface WriteInitCommandResult {
+    status: "created" | "exists";
+    message: string;
+}
+/**
+ * Write the `/aide:init` slash command file to the host project.
+ *
+ * Target path is `<projectRoot>/.claude/commands/aide/init.md`. Returns
+ * `exists` when the file is already present on disk. Otherwise creates the
+ * full parent directory tree, reads the canonical content via
+ * `readCanonicalDoc`, writes the file, and returns `created`.
+ */
+export default function writeInitCommand(projectRoot: string): Promise<WriteInitCommandResult>;

package/dist/cli/init/writeInitCommand/index.js

@@ -0,0 +1,25 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readCanonicalDoc } from "../../../tools/init/initContent/index.js";
+/**
+ * Write the `/aide:init` slash command file to the host project.
+ *
+ * Target path is `<projectRoot>/.claude/commands/aide/init.md`. Returns
+ * `exists` when the file is already present on disk. Otherwise creates the
+ * full parent directory tree, reads the canonical content via
+ * `readCanonicalDoc`, writes the file, and returns `created`.
+ */
+export default async function writeInitCommand(projectRoot) {
+    const commandPath = join(projectRoot, ".claude", "commands", "aide", "init.md");
+    try {
+        await access(commandPath);
+        return { status: "exists", message: "/aide:init command already present" };
+    }
+    catch {
+        // ENOENT — file does not exist, proceed to create
+    }
+    await mkdir(dirname(commandPath), { recursive: true });
+    const content = readCanonicalDoc("commands/aide/init");
+    await writeFile(commandPath, content, "utf-8");
+    return { status: "created", message: "/aide:init command" };
+}

package/dist/cli/init/writeMcpEntry/index.d.ts

@@ -0,0 +1,12 @@
+export interface WriteMcpEntryResult {
+    status: "created" | "exists";
+    message: string;
+}
+/**
+ * Read-parse-merge-write for `.mcp.json` in the given project root.
+ *
+ * Returns `exists` when the aide entry is already present (dual-key check:
+ * `aide` or `aidemd-mcp`). Returns `created` after merging and writing the
+ * new entry. Throws on malformed JSON or write failure.
+ */
+export default function writeMcpEntry(projectRoot: string): Promise<WriteMcpEntryResult>;

package/dist/cli/init/writeMcpEntry/index.js

@@ -0,0 +1,51 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { mcpEntry } from "../../../tools/init/wireMcp/index.js";
+/**
+ * Read-parse-merge-write for `.mcp.json` in the given project root.
+ *
+ * Returns `exists` when the aide entry is already present (dual-key check:
+ * `aide` or `aidemd-mcp`). Returns `created` after merging and writing the
+ * new entry. Throws on malformed JSON or write failure.
+ */
+export default async function writeMcpEntry(projectRoot) {
+    const mcpPath = join(projectRoot, ".mcp.json");
+    let existing;
+    try {
+        existing = await readFile(mcpPath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            existing = "";
+        }
+        else {
+            throw err;
+        }
+    }
+    let config = {};
+    if (existing) {
+        try {
+            config = JSON.parse(existing);
+        }
+        catch {
+            throw new Error(`.mcp.json exists but contains invalid JSON. Fix the syntax error and re-run.`);
+        }
+    }
+    const servers = (config.mcpServers ?? {});
+    if ("aide" in servers || "aidemd-mcp" in servers) {
+        return { status: "exists", message: "aide server already configured" };
+    }
+    const existingCount = Object.keys(servers).length;
+    const merged = {
+        ...config,
+        mcpServers: {
+            ...servers,
+            aide: mcpEntry(),
+        },
+    };
+    await writeFile(mcpPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+    const message = existingCount > 0
+        ? `aide MCP server entry (merged with ${existingCount} existing server${existingCount === 1 ? "" : "s"})`
+        : "aide MCP server entry";
+    return { status: "created", message };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import discover, { DiscoverInput } from "./tools/discover/index.js";
+import read, { ReadInput } from "./tools/read/index.js";
+import scaffold, { ScaffoldInput } from "./tools/scaffold/index.js";
+import validate, { ValidateInput } from "./tools/validate/index.js";
+import init, { InitInput } from "./tools/init/index.js";
+import applySteps from "./tools/init/applySteps/index.js";
+import upgrade, { UpgradeInput } from "./tools/upgrade/index.js";
+import applyFiles from "./tools/upgrade/applyFiles/index.js";
+/** Parse --root flag from CLI args, default to cwd. */
+function parseRoot() {
+    const args = process.argv.slice(2);
+    const rootIdx = args.indexOf("--root");
+    if (rootIdx !== -1 && args[rootIdx + 1])
+        return args[rootIdx + 1];
+    return process.cwd();
+}
+const root = parseRoot();
+const server = new Server({ name: "@aidemd-mcp/server", version: "0.2.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "aide_discover",
+            description: "Scan for .aide spec files in this project. Returns a tree map of where specs live, following progressive disclosure.\n\nWithout a path: returns a lightweight project-wide map — file locations and types only, no content. Use this once to understand the project's spec architecture.\n\nWith a path: the response opens with the ancestor chain — the cascading intent lineage from project root down to the target directory, with each ancestor showing its description and alignment status (aligned/misaligned when set). The ancestor chain gives you the full inherited context before you read a single spec body. After the ancestor chain comes the detailed subtree of the target directory — summaries extracted from file content and anomaly warnings. Use this to drill into the area you're working on.\n\n.aide files are progressive disclosure specs that live next to orchestrator code — they contain intent (strategy, implementation contracts, anti-patterns), research (sources, data, patterns), or QA checklists (todo). Read .aide files BEFORE reading code — they are the context layer between folder structure and implementation details.\n\nFile types (.aide, intent.aide, research.aide, plan.aide, todo.aide):\n- .aide — Intent spec (default). Strategy, contracts, anti-patterns.\n- intent.aide — Same as .aide, used only when research.aide exists in the same folder.\n- research.aide — Raw research. Sources, data points, pattern synthesis.\n- plan.aide -- Architect's implementation plan. Checkboxed steps for the implementor.\n- todo.aide — QA re-alignment document. Captures where implementation drifted from intent.\n\nNever have both .aide and intent.aide in the same folder.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Subdirectory to drill into. When provided, the response opens with the ancestor chain — the cascading intent lineage from root to target, each ancestor showing its description and alignment status — followed by the detailed subtree with summaries and warnings. When omitted, returns a shallow project-wide map (locations and types only).",
+                    },
+                },
+            },
+        },
+        {
+            name: "aide_read",
+            description: "Read an .aide spec file with full context. Returns the file content, its classified type (intent/research/plan/todo), related specs in the same directory, and links found in the content (relative paths, wikilinks, URLs). Use this after aide_discover to drill into a specific spec.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Path to the .aide file to read",
+                    },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "aide_scaffold",
+            description: "Create new .aide spec files with automatic naming convention enforcement. Handles the naming rules: intent specs are .aide by default, but become intent.aide when research.aide exists in the same folder. Creating a research.aide auto-renames any existing .aide to intent.aide.\n\nTypes:\n- intent — Strategy, contracts, anti-patterns\n- research — Sources, data, patterns (triggers rename of existing .aide)\n- both — Creates research.aide + intent.aide pair\n- todo — QA re-alignment document for QA agents\n- plan -- Architect's implementation plan (no naming interaction with intent/research)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    directory: {
+                        type: "string",
+                        description: "Directory where the .aide file(s) will be created",
+                    },
+                    type: {
+                        type: "string",
+                        enum: ["intent", "research", "both", "todo", "plan"],
+                        description: "Type of .aide file to create",
+                    },
+                },
+                required: ["directory", "type"],
+            },
+        },
+        {
+            name: "aide_validate",
+            description: "Health check for .aide spec files in the project. Detects orphaned specs (in folders with no orchestrator), missing specs (orchestrators with 3+ helper imports but no .aide), naming conflicts (.aide + intent.aide in same folder), broken links, orphaned research (research.aide without intent spec), and missing descriptions (specs with no description field in frontmatter).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Subdirectory to validate (defaults to entire project)",
+                    },
+                },
+            },
+        },
+        {
+            name: "aide_upgrade",
+            description: "Compare the AIDE methodology artifacts in this project against the canonical versions and return structured JSON results grouped by category. Use this when the user asks to update AIDE, sync AIDE, refresh AIDE, check for AIDE updates, or bring AIDE up to date. This is NOT for editing user .aide specs — it inspects methodology infrastructure only.\n\nThe tool uses a two-call pattern for progressive disclosure:\n\n**First call (no `category` param):** Returns a lightweight summary — every category with file names, statuses, and counts, but NO file content. Use this to understand what has drifted and present a summary to the user. Ask which categories they want to apply.\n\n**Second call (with `category` param):** The tool writes all differs/missing files directly to disk itself and returns a manifest — file results with `filePath`, `status` (`\"updated\"`, `\"created\"`, or `\"matches\"`), and `name`, but NO `canonicalContent`. The agent never sees file content and never uses the Write tool for methodology files.\n\nRepeat the second call for each category the user confirms.\n\nAs the calling agent, you must:\n1. Call without `category` first to get the summary\n2. Present each drifted category (differs/missing) and ask the user which to apply\n3. For each confirmed category, call again with `category=X` — the tool writes the files and returns a manifest. Report what was updated/created to the user.\n4. For the `mcp` category, the manifest still includes `prescription` data — merge the entry into the existing MCP config yourself (read → merge → write). If `malformed`, tell the user — do not overwrite.\n5. For `ide`, the manifest may include `instructions` for VS Code extension install — execute that command for the user. Zed config is written directly by the tool.\n\n**IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion:**\nDo NOT present all categories at once. Walk the user through ONE category at a time using AskUserQuestion with Yes/Skip options. Stop after each question and wait for confirmation before calling with that category.\n\nCategories: pointer-stub, methodology-docs, version-metadata, commands, agents, skills, mcp, ide.\n\nUpgrade surface (user code and user .aide specs are never touched):\n- AIDE pointer stub in the agent config file\n- Canonical methodology docs under .aide/docs/\n- versions.json metadata under .aide/docs/\n- Slash commands for all pipeline phases\n- Pipeline agent files, skill templates\n- MCP server entry in the project's MCP config\n- IDE file association config (Zed settings, VS Code extension)\n\nSupports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects the framework or accepts an override.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    framework: {
+                        type: "string",
+                        enum: ["claude", "cursor", "windsurf", "copilot"],
+                        description: "Force a specific framework instead of auto-detecting. Auto-detection checks for framework-specific files/directories and defaults to Claude Code.",
+                    },
+                    path: {
+                        type: "string",
+                        description: "Custom project root path (defaults to server working directory)",
+                    },
+                    category: {
+                        type: "string",
+                        enum: ["pointer-stub", "methodology-docs", "version-metadata", "commands", "agents", "skills", "mcp", "ide"],
+                        description: "Write all differs/missing files for this category to disk and return a manifest. Omit on the first call to get a metadata-only summary of all categories.",
+                    },
+                },
+            },
+        },
+        {
+            name: "aide_init",
+            description: "Bootstrap the AIDE development environment into a project. Returns structured JSON for agent consumption — not prose.\n\nThe tool uses a two-call pattern for progressive disclosure:\n\n**First call (no `category` param):** Returns a lightweight summary — every step with `name`, `status` (would-create/would-skip/exists), `category`, and `filePath`, but NO `content` fields. Also returns `brainHints` (vault candidates) and detected `framework`. Use this to understand what needs to be done.\n\n**Second call (with `category` param):** The tool writes all `would-create` files directly to disk itself and returns a manifest — steps with `filePath`, `status` (`created` or `exists`), and `name`, but NO `content`. The agent never sees file content and never uses the Write tool for new files.\n\n**Exception — MCP steps:** For MCP steps, the manifest includes `prescription` data (key name and entry object) so the agent can read the existing config, merge, and write. The tool never touches MCP config directly.\n\n**Exception — brain category:** When calling with `category=brain`, also pass `brainPath` with the user-confirmed vault path. The tool creates the vault scaffold directories directly.\n\n**Exception — IDE VS Code steps:** IDE steps that need external tooling (VS Code CLI) return instructions for the agent to execute, since those aren't simple file writes.\n\n**IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion:**\nDo NOT present a summary table of all categories. Do NOT offer \"all\" as an option. Do NOT ask conversational questions — use the `AskUserQuestion` tool with structured options at every pause point. Walk the user through ONE category at a time:\n\n1. Call without `category` first to get the metadata\n2. Present ONLY the detected framework — use AskUserQuestion with Yes/{alternatives} options. STOP.\n3. Present ONLY the first category with would-create steps — use AskUserQuestion with Yes/Skip options. STOP.\n4. If confirmed, call again with `category=X` (and `brainPath` when category is brain). The tool writes files and returns a manifest. Report what was created, then present the NEXT category with AskUserQuestion. STOP.\n5. Repeat step 4 for each remaining category in order: methodology, commands, agents, skills, mcp, brain, ide\n6. For brain: use AskUserQuestion with brainHints as labeled options (user can pick Other for custom path). STOP.\n7. For MCP: use AskUserQuestion with Merge/Skip options. Merge the `prescription` entry into the existing config yourself (read → merge → write). STOP.\n8. For IDE: use AskUserQuestion with multiSelect for Zed/VS Code/Neither. STOP.\n\nEach step is ONE AskUserQuestion → wait for selection → then proceed. Never show multiple categories at once. Never ask open-ended conversational questions.\n\nDo NOT auto-apply steps without user confirmation.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    framework: {
+                        type: "string",
+                        enum: ["claude", "cursor", "windsurf", "copilot"],
+                        description: "Force a specific framework instead of auto-detecting. Use this when re-calling after the user confirms or overrides detection.",
+                    },
+                    path: {
+                        type: "string",
+                        description: "Custom project root path (defaults to server working directory)",
+                    },
+                    category: {
+                        type: "string",
+                        enum: ["framework", "methodology", "commands", "agents", "skills", "mcp", "brain", "ide"],
+                        description: "Write all would-create files for this category to disk and return a manifest. Omit on the first call to get a metadata-only summary of all steps.",
+                    },
+                    brainPath: {
+                        type: "string",
+                        description: "Resolved brain vault path. Required when category=brain. The agent provides this after interviewing the user.",
+                    },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case "aide_discover": {
+            const parsed = DiscoverInput.parse(args);
+            const result = await discover(root, parsed.path);
+            return { content: [{ type: "text", text: result }] };
+        }
+        case "aide_read": {
+            const parsed = ReadInput.parse(args);
+            const result = await read(root, parsed.path);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `# ${result.type} spec\n\n${result.content}\n\n---\nSiblings: ${result.siblings.map((s) => s.relativePath).join(", ") || "none"}\nLinks: ${result.links.join(", ") || "none"}`,
+                    },
+                ],
+            };
+        }
+        case "aide_scaffold": {
+            const parsed = ScaffoldInput.parse(args);
+            const result = await scaffold(root, parsed.directory, parsed.type);
+            return { content: [{ type: "text", text: result }] };
+        }
+        case "aide_validate": {
+            const parsed = ValidateInput.parse(args);
+            const result = await validate(root, parsed.path);
+            const summary = result.warnings.length === 0
+                ? "No issues found."
+                : result.warnings.map((w) => `[${w.kind}] ${w.path} — ${w.message}`).join("\n");
+            return { content: [{ type: "text", text: summary }] };
+        }
+        case "aide_init": {
+            const parsed = InitInput.parse(args);
+            const result = await init(root, parsed.framework, parsed.path, parsed.brainPath);
+            if (parsed.category) {
+                // Category-specific call: filter to matching steps, write files to
+                // disk via applySteps, and return a manifest (no content).
+                result.steps = result.steps.filter((s) => s.category === parsed.category);
+                result.steps = await applySteps(result.steps);
+            }
+            else {
+                // Summary call: strip content to keep response small
+                result.steps = result.steps.map(({ content: _content, ...rest }) => rest);
+            }
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        case "aide_upgrade": {
+            const parsed = UpgradeInput.parse(args);
+            const result = await upgrade(root, parsed.framework, parsed.path);
+            if (parsed.category) {
+                // Category-specific call: filter to the requested category, write files
+                // to disk via applyFiles, and return a manifest (no canonicalContent).
+                const filtered = result.categories.filter((c) => c.category === parsed.category);
+                result.categories = await Promise.all(filtered.map(async (cat) => {
+                    const appliedFiles = await applyFiles(cat.files);
+                    // Recompute summary from post-apply statuses
+                    const summary = {
+                        total: appliedFiles.length,
+                        differs: appliedFiles.filter((f) => f.status === "differs").length,
+                        missing: appliedFiles.filter((f) => f.status === "missing").length,
+                        matches: appliedFiles.filter((f) => f.status === "matches").length,
+                        updated: appliedFiles.filter((f) => f.status === "updated").length,
+                        created: appliedFiles.filter((f) => f.status === "created").length,
+                        unchanged: appliedFiles.filter((f) => f.status === "unchanged").length,
+                    };
+                    // Defense in depth: strip any residual canonicalContent
+                    const manifestFiles = appliedFiles.map(({ canonicalContent: _content, ...rest }) => rest);
+                    return { ...cat, files: manifestFiles, summary };
+                }));
+            }
+            else {
+                // Summary call: strip canonicalContent to keep response small
+                result.categories = result.categories.map((cat) => ({
+                    ...cat,
+                    files: cat.files.map(({ canonicalContent: _content, ...rest }) => rest),
+                }));
+            }
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal:", error);
+    process.exit(1);
+});

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

@@ -0,0 +1,17 @@
+/**
+ * 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 function buildAncestorChain(root: string, targetPath: string): Promise<string>;