@aidemd-mcp/server 0.2.0

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

@@ -0,0 +1,239 @@
+import { readFile, access, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { platform } from "node:os";
+/** Check if a path exists. */
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check if a vault already exists at brainPath (.obsidian/ dir present, or directory is non-empty). */
+async function vaultExists(brainPath) {
+    if (await exists(join(brainPath, ".obsidian")))
+        return true;
+    try {
+        const entries = await readdir(brainPath);
+        return entries.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read a file, returning empty string if it doesn't exist. */
+async function safeReadFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/** Build the Obsidian MCP server entry, wrapping with cmd /c on Windows. */
+function obsidianMcpEntry(brainPath) {
+    if (platform() === "win32") {
+        return { command: "cmd", args: ["/c", "npx", "@bitbonsai/mcpvault", brainPath] };
+    }
+    return { command: "npx", args: ["@bitbonsai/mcpvault", brainPath] };
+}
+/** The vault directories that init scaffolds into a fresh vault. */
+const VAULT_DIRS = ["research", "process/retro", "coding-playbook"];
+/** Markdown template for the vault-root CLAUDE.md. Covers vault navigation only:
+ * wikilink crawling protocol, decision protocol, where-to-find-things table, and
+ * the brain's role in AIDE. Contains no project-specific instructions or user config. */
+const VAULT_CLAUDE_MD_TEMPLATE = `# Brain Vault Navigation
+
+## Brain's Role in AIDE
+
+The vault is the pipeline's durable memory. Research agents write domain findings into it, QA agents promote retros, and the coding playbook captures engineering conventions that survive across projects. Without the vault, agents cannot persist or retrieve knowledge across runs — each session starts from scratch.
+
+## Wikilink Crawling Protocol
+
+When reading any vault note, follow \`[[wikilinks]]\` that are relevant to your current task. The rules:
+
+- **Hub notes** (tagged \`hub\` or acting as section indexes) are navigation, not content. Read all wikilinks in their \`## Subnotes\` section to get the full context of that domain. Hubs do not count toward depth.
+- **Content notes** are where depth starts (depth 0). When reading a content note, look for \`[[wikilinks]]\` in the body. If a linked note looks relevant to the task, read it (depth 1). Check *that* note's links too — go at least 1–2 levels deep from the first content note in any direction where the information could apply.
+- **Never re-read.** If a note is already in your conversation context from a prior read, skip it. This applies across skill invocations and manual reads within the same session.
+- **Stay in scope.** Wikilinks that point outside the current domain of interest can be skipped. Follow links that deepen understanding of the task, not links that branch into unrelated topics.
+
+## Decision Protocol
+
+There are two lookup paths — use the right one:
+
+- **Coding conventions and patterns** → use the \`study-playbook\` skill. It navigates the coding playbook hub top-down (hub → section hub → content notes → wikilinks). Do NOT flat-search for playbook content with \`search_notes\` — the hub structure gives you the full picture; search gives you fragments.
+- **Everything else** (project context, journal logs, research, domain knowledge, tasks) → use \`mcp__obsidian__search_notes\` with query terms matching the domain.
+
+## Where to Find Things
+
+| What you need | Where to look |
+|---------------|---------------|
+| Coding conventions, patterns | \`study-playbook\` skill (not search) |
+| Domain research, reference material | \`research/\` (search by domain) |
+| QA retros, process learnings | \`process/retro/\` |
+`;
+/** Markdown template for the coding-playbook hub note. Contains the five-section
+ * structure the study-playbook skill's crawling protocol expects — headings and
+ * table skeleton are present, all content rows and entries are left empty. */
+const PLAYBOOK_HUB_TEMPLATE = `# Coding Playbook
+
+## Task Routing
+
+| Task domain | Section |
+|-------------|---------|
+
+---
+
+## How to Use This Index
+
+Read this note first. Each section links to a **section hub** that lists its notes with keywords. Navigate to the section relevant to your task, then drill into the specific notes you need. Do not read all sections — only the ones whose keywords match the work.
+
+---
+
+## Always Read First
+
+These notes are **required reading** for every task, regardless of which section you're working in:
+
+1. **[[your-conventions-note]]** — Add your naming, function ordering, and code hygiene conventions here.
+2. **[[your-folder-structure-note]]** — Add your folder layout and progressive disclosure conventions here.
+
+---
+
+## Sections
+
+---
+
+## Contents
+`;
+/**
+ * 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 async function provisionBrain(brainPath, mcpConfigPath) {
+    const vaultStep = await buildVaultStep(brainPath);
+    const playbookHubStep = await buildPlaybookHubStep(brainPath);
+    const vaultClaudeMdStep = await buildVaultClaudeMdStep(brainPath);
+    const mcpStep = await buildObsidianMcpStep(brainPath, mcpConfigPath);
+    return [vaultStep, playbookHubStep, vaultClaudeMdStep, mcpStep];
+}
+/** Build the vault scaffolding planning step. */
+async function buildVaultStep(brainPath) {
+    if (await vaultExists(brainPath)) {
+        return {
+            name: "Brain vault",
+            status: "exists",
+            category: "brain",
+            filePath: brainPath,
+        };
+    }
+    return {
+        name: "Brain vault",
+        status: "would-create",
+        category: "brain",
+        filePath: brainPath,
+        content: JSON.stringify(VAULT_DIRS),
+    };
+}
+/** Build the playbook hub template planning step, with per-file idempotency. */
+async function buildPlaybookHubStep(brainPath) {
+    const filePath = join(brainPath, "coding-playbook", "coding-playbook.md");
+    if (await exists(filePath)) {
+        return {
+            name: "Playbook hub",
+            status: "exists",
+            category: "brain",
+            filePath,
+        };
+    }
+    return {
+        name: "Playbook hub",
+        status: "would-create",
+        category: "brain",
+        filePath,
+        content: PLAYBOOK_HUB_TEMPLATE,
+    };
+}
+/** Build the vault-root CLAUDE.md planning step, with per-file idempotency. */
+async function buildVaultClaudeMdStep(brainPath) {
+    const filePath = join(brainPath, "CLAUDE.md");
+    if (await exists(filePath)) {
+        return {
+            name: "Vault CLAUDE.md",
+            status: "exists",
+            category: "brain",
+            filePath,
+        };
+    }
+    return {
+        name: "Vault CLAUDE.md",
+        status: "would-create",
+        category: "brain",
+        filePath,
+        content: VAULT_CLAUDE_MD_TEMPLATE,
+    };
+}
+/** Build the Obsidian MCP wiring planning step. */
+async function buildObsidianMcpStep(brainPath, mcpConfigPath) {
+    const prescription = {
+        key: "obsidian",
+        entry: obsidianMcpEntry(brainPath),
+    };
+    const existing = await safeReadFile(mcpConfigPath);
+    if (existing) {
+        try {
+            const config = JSON.parse(existing);
+            const servers = config.mcpServers || {};
+            if ("obsidian" in servers) {
+                return {
+                    name: "MCP config (obsidian)",
+                    status: "exists",
+                    category: "mcp",
+                    filePath: mcpConfigPath,
+                };
+            }
+            return {
+                name: "MCP config (obsidian)",
+                status: "would-create",
+                category: "mcp",
+                filePath: mcpConfigPath,
+                prescription,
+            };
+        }
+        catch {
+            return {
+                name: "MCP config (obsidian)",
+                status: "would-create",
+                category: "mcp",
+                filePath: mcpConfigPath,
+                prescription,
+                configMalformed: true,
+            };
+        }
+    }
+    return {
+        name: "MCP config (obsidian)",
+        status: "would-create",
+        category: "mcp",
+        filePath: mcpConfigPath,
+        prescription,
+    };
+}

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

@@ -0,0 +1,17 @@
+import type { BrainHint } from "../../../types/index.js";
+/**
+ * Discover all candidate brain vault locations and return them as hints.
+ *
+ * Checks three sources in order:
+ * 1. AIDE_BRAIN_PATH environment variable
+ * 2. Sibling my-brain/ directory next to projectRoot
+ * 3. Platform-conventional location: ~/my-brain
+ *
+ * Returns every candidate that exists on disk. Returns an empty array when
+ * none are found — the agent must then ask the user directly.
+ *
+ * The caller (agent) presents these hints as suggestions and asks the user
+ * to confirm or provide a different path. The hints are never silently
+ * adopted — this function reports candidates, not a winner.
+ */
+export default function resolveBrainHints(projectRoot: string): Promise<BrainHint[]>;

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

@@ -0,0 +1,44 @@
+import { access } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+/** Check if a path exists on disk. */
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Discover all candidate brain vault locations and return them as hints.
+ *
+ * Checks three sources in order:
+ * 1. AIDE_BRAIN_PATH environment variable
+ * 2. Sibling my-brain/ directory next to projectRoot
+ * 3. Platform-conventional location: ~/my-brain
+ *
+ * Returns every candidate that exists on disk. Returns an empty array when
+ * none are found — the agent must then ask the user directly.
+ *
+ * The caller (agent) presents these hints as suggestions and asks the user
+ * to confirm or provide a different path. The hints are never silently
+ * adopted — this function reports candidates, not a winner.
+ */
+export default async function resolveBrainHints(projectRoot) {
+    const hints = [];
+    const envPath = process.env.AIDE_BRAIN_PATH;
+    if (envPath && await exists(envPath)) {
+        hints.push({ source: "env", path: envPath });
+    }
+    const siblingPath = join(dirname(projectRoot), "my-brain");
+    if (await exists(siblingPath)) {
+        hints.push({ source: "sibling", path: siblingPath });
+    }
+    const conventionalPath = join(homedir(), "my-brain");
+    if (await exists(conventionalPath)) {
+        hints.push({ source: "conventional", path: conventionalPath });
+    }
+    return hints;
+}

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

@@ -0,0 +1,38 @@
+import type { InitStep } from "../../../types/index.js";
+import { type CanonicalDocName } from "../../../tools/init/initContent/index.js";
+/**
+ * Fixed registry of the /aide orchestrator entry point plus the AIDE pipeline
+ * phase commands. Owning this list here — rather than discovering it
+ * from .claude/commands/ at runtime — is the mechanical guarantee that a stray
+ * Markdown file committed under .claude/commands/aide/ cannot silently expand
+ * the pipeline.
+ *
+ * Layout: the orchestrator is installed at <commandDir>/aide.md — a peer of
+ * the `aide/` subfolder, not inside it. Phase commands are installed at
+ * <commandDir>/aide/<phase>.md. The `aide/` subfolder is the namespace, not a
+ * filename prefix — host frameworks derive slash-command namespaces from folder
+ * nesting, so a file at aide/research.md becomes `/aide:research` on the host.
+ * This is the layout .claude/commands/aide/.aide mandates: "filenames must be
+ * bare phase names ... the enclosing aide/ folder already carries the
+ * namespace". Reintroducing an `aide-` filename prefix here would produce
+ * `/aide:aide-research` on the host — the exact double-namespace failure the
+ * canonical spec names as undesired. The orchestrator lives one level up
+ * (aide.md) so it registers as the plain `/aide` command with no colon suffix.
+ */
+export declare const COMMANDS: readonly {
+    canonical: CanonicalDocName;
+    hostPath: string;
+    displayName: string;
+}[];
+/**
+ * Return planning steps for the /aide orchestrator and pipeline phase commands.
+ *
+ * For each command in COMMANDS, checks whether the host file already exists.
+ * Returns `exists` for present files, `would-create` with the canonical content
+ * for absent files. A failed canonical read returns `would-skip` for that
+ * command only.
+ *
+ * The COMMANDS export stays unchanged — upgrade's logic still uses it.
+ * This helper never writes to disk — it is a planner only.
+ */
+export default function scaffoldCommands(commandDir: string): Promise<InitStep[]>;

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

@@ -0,0 +1,94 @@
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { readCanonicalDoc, } from "../../../tools/init/initContent/index.js";
+/**
+ * Fixed registry of the /aide orchestrator entry point plus the AIDE pipeline
+ * phase commands. Owning this list here — rather than discovering it
+ * from .claude/commands/ at runtime — is the mechanical guarantee that a stray
+ * Markdown file committed under .claude/commands/aide/ cannot silently expand
+ * the pipeline.
+ *
+ * Layout: the orchestrator is installed at <commandDir>/aide.md — a peer of
+ * the `aide/` subfolder, not inside it. Phase commands are installed at
+ * <commandDir>/aide/<phase>.md. The `aide/` subfolder is the namespace, not a
+ * filename prefix — host frameworks derive slash-command namespaces from folder
+ * nesting, so a file at aide/research.md becomes `/aide:research` on the host.
+ * This is the layout .claude/commands/aide/.aide mandates: "filenames must be
+ * bare phase names ... the enclosing aide/ folder already carries the
+ * namespace". Reintroducing an `aide-` filename prefix here would produce
+ * `/aide:aide-research` on the host — the exact double-namespace failure the
+ * canonical spec names as undesired. The orchestrator lives one level up
+ * (aide.md) so it registers as the plain `/aide` command with no colon suffix.
+ */
+export const COMMANDS = [
+    { canonical: "commands/aide/aide", hostPath: "aide.md", displayName: "aide" },
+    { canonical: "commands/aide/research", hostPath: "aide/research.md", displayName: "aide:research" },
+    { canonical: "commands/aide/spec", hostPath: "aide/spec.md", displayName: "aide:spec" },
+    { canonical: "commands/aide/synthesize", hostPath: "aide/synthesize.md", displayName: "aide:synthesize" },
+    { canonical: "commands/aide/plan", hostPath: "aide/plan.md", displayName: "aide:plan" },
+    { canonical: "commands/aide/build", hostPath: "aide/build.md", displayName: "aide:build" },
+    { canonical: "commands/aide/qa", hostPath: "aide/qa.md", displayName: "aide:qa" },
+    { canonical: "commands/aide/fix", hostPath: "aide/fix.md", displayName: "aide:fix" },
+    { canonical: "commands/aide/upgrade", hostPath: "aide/upgrade.md", displayName: "aide:upgrade" },
+    { canonical: "commands/aide/init", hostPath: "aide/init.md", displayName: "aide:init" },
+    { canonical: "commands/aide/update-playbook", hostPath: "aide/update-playbook.md", displayName: "aide:update-playbook" },
+    { canonical: "commands/aide/refactor", hostPath: "aide/refactor.md", displayName: "aide:refactor" },
+    { canonical: "commands/aide/align", hostPath: "aide/align.md", displayName: "aide:align" },
+];
+/** Check if a file exists. */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Return planning steps for the /aide orchestrator and pipeline phase commands.
+ *
+ * For each command in COMMANDS, checks whether the host file already exists.
+ * Returns `exists` for present files, `would-create` with the canonical content
+ * for absent files. A failed canonical read returns `would-skip` for that
+ * command only.
+ *
+ * The COMMANDS export stays unchanged — upgrade's logic still uses it.
+ * This helper never writes to disk — it is a planner only.
+ */
+export default async function scaffoldCommands(commandDir) {
+    const steps = [];
+    for (const cmd of COMMANDS) {
+        const filePath = join(commandDir, cmd.hostPath);
+        if (await fileExists(filePath)) {
+            steps.push({
+                name: cmd.displayName,
+                status: "exists",
+                category: "commands",
+                filePath,
+            });
+            continue;
+        }
+        let content;
+        try {
+            content = readCanonicalDoc(cmd.canonical);
+        }
+        catch {
+            steps.push({
+                name: cmd.displayName,
+                status: "would-skip",
+                category: "commands",
+                filePath,
+            });
+            continue;
+        }
+        steps.push({
+            name: cmd.displayName,
+            status: "would-create",
+            category: "commands",
+            filePath,
+            content,
+        });
+    }
+    return steps;
+}

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

@@ -0,0 +1,16 @@
+import type { InitStep, McpPrescription } from "../../../types/index.js";
+/** Build the MCP server entry, wrapping with cmd /c on Windows. */
+export declare function mcpEntry(): McpPrescription["entry"];
+/**
+ * Inspect the project's MCP config and return a planning step for the aide
+ * server entry.
+ *
+ * Returns `exists` when an aide entry is already present. Returns
+ * `would-create` with a McpPrescription when the entry is absent.
+ * If the config file exists but contains malformed JSON, returns
+ * `would-create` with `configMalformed: true` so the agent can surface
+ * the issue to the user.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default function wireMcp(mcpConfigPath: string): Promise<InitStep>;

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

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import { platform } from "node:os";
+/** Read a file, returning empty string if it doesn't exist. */
+async function safeReadFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/** Build the MCP server entry, wrapping with cmd /c on Windows. */
+export function mcpEntry() {
+    if (platform() === "win32") {
+        return { command: "cmd", args: ["/c", "npx", "@aidemd-mcp/server"] };
+    }
+    return { command: "npx", args: ["@aidemd-mcp/server"] };
+}
+/**
+ * Inspect the project's MCP config and return a planning step for the aide
+ * server entry.
+ *
+ * Returns `exists` when an aide entry is already present. Returns
+ * `would-create` with a McpPrescription when the entry is absent.
+ * If the config file exists but contains malformed JSON, returns
+ * `would-create` with `configMalformed: true` so the agent can surface
+ * the issue to the user.
+ *
+ * This helper never writes to disk — it is a planner only.
+ */
+export default async function wireMcp(mcpConfigPath) {
+    const prescription = { key: "aide", entry: mcpEntry() };
+    const existing = await safeReadFile(mcpConfigPath);
+    if (existing) {
+        try {
+            const config = JSON.parse(existing);
+            const servers = config.mcpServers || {};
+            if ("aide" in servers || "aidemd-mcp" in servers) {
+                return {
+                    name: "MCP config (aide)",
+                    status: "exists",
+                    category: "mcp",
+                    filePath: mcpConfigPath,
+                };
+            }
+            return {
+                name: "MCP config (aide)",
+                status: "would-create",
+                category: "mcp",
+                filePath: mcpConfigPath,
+                prescription,
+            };
+        }
+        catch {
+            return {
+                name: "MCP config (aide)",
+                status: "would-create",
+                category: "mcp",
+                filePath: mcpConfigPath,
+                prescription,
+                configMalformed: true,
+            };
+        }
+    }
+    return {
+        name: "MCP config (aide)",
+        status: "would-create",
+        category: "mcp",
+        filePath: mcpConfigPath,
+        prescription,
+    };
+}

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

@@ -0,0 +1,20 @@
+import type { InitStep } from "../../../types/index.js";
+/**
+ * Compose the marker-bounded pointer stub. The body is the inlined
+ * STUB_TEMPLATE with the host-side hub path substituted in; marker
+ * comments wrap it for idempotency detection.
+ */
+export declare function composeStub(docHubDir: string): string;
+/**
+ * Inspect the host's agent config file and return a planning step for the
+ * AIDE methodology pointer stub.
+ *
+ * Returns `exists` if the marker is already present. Returns `would-create`
+ * with the composed stub as `content` — the caller writes the stub
+ * appended to the existing content (or as the full content when the file is
+ * absent).
+ *
+ * This helper never writes to disk — it is a planner only. `composeStub`
+ * remains a named export so upgrade's `spliceStub` can continue to use it.
+ */
+export default function writeMethodology(configPath: string, docHubDir: string): Promise<InitStep>;

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

@@ -0,0 +1,94 @@
+import { readFile } from "node:fs/promises";
+import { getMethodologyMarker } from "../../../tools/init/initContent/index.js";
+/** Placeholder token inside the stub template that names the host-side
+ * doc hub path. writeMethodology substitutes this at install time with
+ * the caller-supplied relative path, so the stub's pointer and the
+ * installer's write target derive from a single shared source. */
+const HUB_PATH_PLACEHOLDER = "{{HUB_PATH}}";
+/**
+ * The pointer stub written into the host's agent config file. This is
+ * framework plumbing — not AIDE doctrine — because its only job is to
+ * tell the agent where the canonical docs live and that they must be
+ * crawled before acting on any `.aide` file. The doctrine itself lives
+ * in the canonical docs the stub points at; this template just routes
+ * the agent there.
+ */
+const STUB_TEMPLATE = `## AIDE — Autonomous Intent-Driven Engineering
+
+This project uses the AIDE methodology. AIDE treats a short \`.aide\` intent
+spec living next to orchestrator code as the contract every downstream
+agent (architect, implementor, QA) works from — when the intent changes,
+the code changes.
+
+The full canonical methodology is installed in this project at
+\`${HUB_PATH_PLACEHOLDER}/\`. Start at \`${HUB_PATH_PLACEHOLDER}/index.md\` for the doc list, then
+crawl into the specific canonical doc your current task requires. Read
+only what the task actually needs — the hub is organized for
+progressive disclosure, not for front-loading.
+
+**Before writing, editing, or acting on any \`.aide\` file, crawl the hub
+and read the canonical doc that governs the work you are about to do.**
+Never guess AIDE rules from memory: the files under \`${HUB_PATH_PLACEHOLDER}/\` are
+the authoritative source, and any decision that disagrees with them is
+wrong by definition.
+
+**AIDE tools quick-reference:**
+- \`aide_discover\` — map where \`.aide\` specs live in the project
+- \`aide_read\` — read a specific \`.aide\` file with context
+- \`aide_scaffold\` — create a new \`.aide\` file
+- \`aide_validate\` — check spec layout for drift or issues
+- \`aide_init\` — bootstrap AIDE into a new project (first-time setup)
+- \`aide_upgrade\` — update/sync/refresh AIDE docs, commands, agents, and skills to the latest canonical versions (use this when asked to "update AIDE", "update the docs", or "sync the methodology")
+`;
+/** Read a file, returning empty string if it doesn't exist. */
+async function safeReadFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Compose the marker-bounded pointer stub. The body is the inlined
+ * STUB_TEMPLATE with the host-side hub path substituted in; marker
+ * comments wrap it for idempotency detection.
+ */
+export function composeStub(docHubDir) {
+    const marker = getMethodologyMarker();
+    const body = STUB_TEMPLATE.replaceAll(HUB_PATH_PLACEHOLDER, docHubDir);
+    return `${marker}\n${body}\n${marker}`;
+}
+/**
+ * Inspect the host's agent config file and return a planning step for the
+ * AIDE methodology pointer stub.
+ *
+ * Returns `exists` if the marker is already present. Returns `would-create`
+ * with the composed stub as `content` — the caller writes the stub
+ * appended to the existing content (or as the full content when the file is
+ * absent).
+ *
+ * This helper never writes to disk — it is a planner only. `composeStub`
+ * remains a named export so upgrade's `spliceStub` can continue to use it.
+ */
+export default async function writeMethodology(configPath, docHubDir) {
+    const existing = await safeReadFile(configPath);
+    const marker = getMethodologyMarker();
+    if (existing.includes(marker)) {
+        return {
+            name: "Methodology pointer",
+            status: "exists",
+            category: "methodology",
+            filePath: configPath,
+        };
+    }
+    const stub = composeStub(docHubDir);
+    const content = existing ? `${existing}\n\n${stub}\n` : `${stub}\n`;
+    return {
+        name: "Methodology pointer",
+        status: "would-create",
+        category: "methodology",
+        filePath: configPath,
+        content,
+    };
+}

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

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { ReadResult } from "../../types/index.js";
+export declare const ReadInput: z.ZodObject<{
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+}, {
+    path: string;
+}>;
+/**
+ * Read an .aide file with context awareness.
+ * Returns the file content, classified type, sibling specs in the same
+ * directory, and links found in the content.
+ */
+export default function read(root: string, filePath: string): Promise<ReadResult>;