@aidemd-mcp/server 0.2.4 → 0.3.0

package/.aide/docs/.aide

@@ -1,5 +1,7 @@
 ---
 scope: .aide/docs
+description: >
+  Spec for the canonical AIDE methodology docs — governs adding the References section so synthesis agents leave auditable breadcrumb trails.
 status: aligned
 intent: >
   Add a References section to the AIDE spec template and methodology so the

package/.aide/docs/plan.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  Plan to add the References body section to the AIDE template, spec doc, and synthesis agent instructions.
 intent: >
   Add a References section to the AIDE methodology so the synthesis agent
   leaves a traceable breadcrumb trail of which brain notes informed each

package/.aide/intent.aide

@@ -1,5 +1,7 @@
 ---
 scope: .
+description: >
+  Canonical home of the AIDE methodology and the MCP server that delivers it — single source of truth for every downstream host project.
 intent: >
   This repository is the canonical home of the AIDE methodology — Autonomous
   Intent-Driven Engineering, with a deliberate second reading as AI Domain

package/.aide/plan.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  Plan to rewrite README.md into the canonical MCP installation guide with per-client config blocks and full tool documentation.
 intent: >
   Rewrite README.md to match the readme.aide spec — quick-install via
   npx @aidemd-mcp/server init as recommended primary path, per-client manual

package/.aide/readme.aide

@@ -36,9 +36,9 @@ outcomes:
       concrete first action to take inside their agent, closing the gap
       between install and first value.
   undesired:
-    - A config block that shows one client's format and expects users of
+    - "A config block that shows one client's format and expects users of
       other clients to translate — the #1 documented friction source in
-      MCP server READMEs (mcp-readme-conventions research).
+      MCP server READMEs (mcp-readme-conventions research)."
     - A tool list without parameter documentation, forcing the developer
       to install the server just to discover what inputs each tool accepts.
     - A README that teaches the full AIDE methodology instead of focusing
@@ -50,9 +50,9 @@ outcomes:
     - A config block using a bare package name without @latest, which
       silently serves a stale cached version to users who have previously
       installed any version.
-    - A PATH-troubleshooting gap: omitting the nvm/Homebrew PATH failure
+    - "A PATH-troubleshooting gap: omitting the nvm/Homebrew PATH failure
       mode for Claude Desktop, which is the single most common MCP install
-      failure and silently loses users who blame themselves and give up.
+      failure and silently loses users who blame themselves and give up."
 ---
 
 ## Context

package/.aide/todo.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  QA findings for the README.md rewrite — tracks the missing @latest on the Quick Start npx command.
 intent: >
   README.md rewrite against readme.aide spec. One outcome violated: the Quick
   Start block omits @latest from the npx command, which can serve a stale

package/.claude/.aide

@@ -23,12 +23,12 @@ outcomes:
     - The aligner walks the tree top-down using the discover tool's ancestor
       chain, compares outcomes at each level, and produces a todo.aide at
       each misaligned node listing concrete realignment items.
-    - The aligner sets status: misaligned on specs where it finds drift and
+    - "The aligner sets status: misaligned on specs where it finds drift and
       status: aligned on specs it has verified. It is the only agent that
-      can confirm alignment through a deliberate full-tree walk.
-    - The QA agent can set status: misaligned incidentally while reviewing
+      can confirm alignment through a deliberate full-tree walk."
+    - "The QA agent can set status: misaligned incidentally while reviewing
       code-vs-spec, but cannot set aligned — only the aligner confirms
-      alignment.
+      alignment."
     - A /aide:align command exists that invokes the aligner agent, callable
       by the user or suggestable by the orchestrator when drift is suspected.
     - Agent definitions across the harness no longer contain verbose

package/.claude/agents/aide/aide-explorer.md

@@ -0,0 +1,63 @@
+---
+name: aide-explorer
+description: "Use this agent for read-only investigation of the AIDE codebase — finding code, tracing bugs, answering questions about how modules work, or understanding the cascading intent tree. This agent understands the AIDE methodology, uses aide_discover for .aide file lookups, and navigates code using progressive disclosure. It does NOT write code, edit files, or delegate to other agents.\n\nExamples:\n\n- Orchestrator delegates: \"Why does aide_init not scaffold the top-level /aide command?\"\n  [Explorer runs aide_discover, reads the scaffolding module's .aide and orchestrator, traces the issue, returns findings]\n\n- Orchestrator delegates: \"What does the scoring module's pipeline look like?\"\n  [Explorer runs aide_discover to find the module, reads .aide spec, reads orchestrator imports, returns a summary]\n\n- Orchestrator delegates: \"Find where command templates are registered and check if aide.md is in the list\"\n  [Explorer uses discover + targeted code reads to trace the registration flow and report back]"
+model: sonnet
+color: cyan
+memory: user
+mcpServers:
+  - aide
+---
+
+You are the AIDE-aware codebase explorer — a read-only investigator that understands the AIDE methodology and uses its tools to navigate codebases efficiently. You trace bugs, answer questions about how modules work, and find code — but you never modify anything.
+
+## Your Role
+
+You receive a delegation from the orchestrator with a question or investigation task, along with the current `aide_discover` output (the cascading intent tree). You use this context to navigate the codebase intelligently, then return your findings to the caller.
+
+**You do NOT write code, edit files, or delegate to other agents.** You investigate and report.
+
+## Cascading Intent — What It Means
+
+AIDE projects organize code into a tree of `.aide` spec files. Each spec declares the *intent* of its module — what it's supposed to do, what success looks like, what to avoid. Intent **cascades**: a child module's intent must align with its parent's intent, which must align with the root's intent. This ancestor chain is the "why" behind every module.
+
+When you investigate code, you are not looking at isolated files. You are looking at nodes in an intent tree. Understanding *why* a module exists (its cascading intent) comes before understanding *how* it works (its code).
+
+## Mandatory First Action
+
+**Your very first tool call MUST be `aide_discover` with the target module's path.** This returns:
+
+- The **ancestor chain** — every `.aide` spec from root down to the target, with descriptions and alignment status. This is the cascading intent context.
+- The **detailed subtree** — summaries of specs and files in the target directory, plus anomaly warnings.
+
+If the orchestrator already passed you rich discover output (with ancestor chain), you may skip this call. But if you only received a lightweight map (paths and types), you MUST call `aide_discover(path)` yourself before reading any code.
+
+**Never use Glob, Grep, find, or Bash to search for `.aide` files.** `aide_discover` is the only tool for `.aide` navigation.
+
+## How You Navigate Code
+
+After you have the cascading intent context:
+
+### Progressive Disclosure
+
+1. **Folder structure first.** Every service module is a folder named after its default export. An `ls` of a service directory tells you what it does. Start here.
+2. **Orchestrator imports + JSDoc.** If folder names aren't enough, open the orchestrator's `index.ts`. The import list + JSDoc gives you the data flow.
+3. **Function bodies.** Only drill into a helper's implementation when your task requires understanding *how* it works, not just *what* it does.
+
+### .aide Specs — Read Before Code
+
+If a module has a `.aide` spec, read it before reading the code. The spec captures domain context the code alone doesn't show — strategy, intent, implementation contracts.
+
+## Investigation Process
+
+1. **Understand cascading intent.** Use the `aide_discover(path)` output to understand the ancestor chain — why this module exists in the context of the larger system.
+2. **Read the .aide spec** for the target module to understand its specific intent, outcomes, and contracts.
+3. **Read the orchestrator** (`index.ts`) to understand the module's structure and data flow.
+4. **Drill into specific helpers** only as needed to answer the question.
+5. **Return findings** with file paths, line numbers, and a clear explanation.
+
+## What You Return
+
+Your response to the orchestrator should include:
+- **The answer** to the question or investigation
+- **Evidence** — file paths and relevant code snippets that support your finding
+- **Recommendations** (if applicable) — what should be done next, phrased as suggestions for the orchestrator to act on

package/.claude/agents/aide/aide-spec-writer.md

@@ -30,12 +30,14 @@ The orchestrator owns the user conversation. Your job is to take the context it
    - Use `intent.aide` if `research.aide` exists (co-located research triggers the rename)
 3. Fill the frontmatter ONLY:
    - `scope` — the module path this spec governs
+   - `description` — one-line purpose statement, used by `aide_discover` ancestor chains so agents understand what this spec governs without opening it
    - `intent` — one paragraph, plain language, ten-second north star
    - `outcomes.desired` — concrete, falsifiable success criteria (2-5 bullets)
    - `outcomes.undesired` — failure modes, especially the almost-right-but-wrong kind
 4. Leave body sections (`## Context`, `## Strategy`, `## Good examples`, `## Bad examples`) as empty placeholders
 5. No code in the spec — no file paths, no type signatures, no function names
 6. Every `outcomes` entry must trace back to the `intent` paragraph
+7. **Quote outcomes that contain colons.** Multi-line YAML list items whose continuation lines contain `key: value` patterns (e.g., `status: aligned`, `scope: src/tools`) break the YAML parser — it reads the colon as a map key delimiter. Wrap any outcome item that contains a colon-space (`: `) in its text in double quotes: `- "The aligner sets status: aligned on verified specs"`. Single-line items without colons don't need quoting.
 
 ## Return Format
 

package/.claude/skills/brain/.aide

@@ -1,5 +1,7 @@
 ---
 scope: .claude/skills/brain
+description: >
+  Spec for the /brain skill — a thin dispatcher that reads the vault CLAUDE.md and defers all navigation to it, giving agents general-purpose vault access.
 intent: >
   The /brain skill gives agents in host projects a general-purpose interface
   to the user's Obsidian vault. The skill prompt is deliberately minimal: it
@@ -26,11 +28,11 @@ outcomes:
       installSkills pipeline — registered in DOC_PATHS and SKILL_DOCS,
       installed to the host's skill directory, subject to the same
       idempotency and upgrade contracts as study-playbook.
-    - The skill prompt distinguishes itself from study-playbook by scope:
+    - "The skill prompt distinguishes itself from study-playbook by scope:
       study-playbook is limited to the coding playbook hub, while /brain
       is the general-purpose entry point for any vault query — research,
       project context, environment, identity, references, or any other
-      vault content the user has organized.
+      vault content the user has organized."
   undesired:
     - A skill prompt that hardcodes vault navigation rules, directory
       paths, hub locations, or routing tables. This creates two sources

package/.claude/skills/brain/plan.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  Plan to ship the /brain skill — create the SKILL.md template, register it in initContent, update the doc hub, and add a regression test.
 intent: >
   Ship the /brain skill — a thin-dispatcher SKILL.md template that tells
   agents to read the vault's root CLAUDE.md via the Obsidian MCP and follow

package/dist/cli/App/index.js

@@ -38,15 +38,17 @@ export default function App({ root, initialNodes }) {
     const [drillCache] = useState(new Map());
     // Single expanded section in drill-in mode; Tab cycles through sections.
     const [expandedSection, setExpandedSection] = useState(null);
-    // --- Detail panel frontmatter (for currently selected file) ---
+    // --- Detail panel frontmatter + body (for currently selected file) ---
     const [selectedFrontmatter, setSelectedFrontmatter] = useState(null);
+    const [selectedBody, setSelectedBody] = useState("");
     const [fmCache] = useState(new Map());
     /** Returns true if any file descendant of node matches the search filter. */
     function hasMatchingDescendant(node, filter) {
         if (node.kind === "file") {
             const lower = filter.toLowerCase();
             return (node.file.relativePath.toLowerCase().includes(lower) ||
-                (node.file.summary ?? "").toLowerCase().includes(lower));
+                (node.file.summary ?? "").toLowerCase().includes(lower) ||
+                (node.file.description ?? "").toLowerCase().includes(lower));
         }
         return node.children.some((child) => hasMatchingDescendant(child, filter));
     }
@@ -58,8 +60,10 @@ export default function App({ root, initialNodes }) {
             if (fn.node.kind === "dir") {
                 return hasMatchingDescendant(fn.node, searchFilter);
             }
-            return (fn.node.file.relativePath.toLowerCase().includes(searchFilter.toLowerCase()) ||
-                (fn.node.file.summary ?? "").toLowerCase().includes(searchFilter.toLowerCase()));
+            const lower = searchFilter.toLowerCase();
+            return (fn.node.file.relativePath.toLowerCase().includes(lower) ||
+                (fn.node.file.summary ?? "").toLowerCase().includes(lower) ||
+                (fn.node.file.description ?? "").toLowerCase().includes(lower));
         })
         : flatNodes;
     // Clamp cursor within visible range.
@@ -75,25 +79,30 @@ export default function App({ root, initialNodes }) {
     // Computed booleans for the cursor's current position.
     const cursorOnDir = cursorNode?.node.kind === "dir";
     const cursorDirExpanded = cursorOnDir && cursorNode.node.kind === "dir" && expandedDirs.has(cursorNode.node.path);
-    // Load frontmatter for the detail panel whenever selectedFile changes.
+    // Load frontmatter + body for the detail panel whenever selectedFile changes.
     useEffect(() => {
         if (!selectedFile) {
             setSelectedFrontmatter(null);
+            setSelectedBody("");
             return;
         }
         if (fmCache.has(selectedFile.path)) {
-            setSelectedFrontmatter(fmCache.get(selectedFile.path) ?? null);
+            const cached = fmCache.get(selectedFile.path);
+            setSelectedFrontmatter(cached.frontmatter);
+            setSelectedBody(cached.body);
             return;
         }
         readFile(selectedFile.path, "utf-8")
             .then((content) => {
-            const { frontmatter } = parseFrontmatter(content);
-            fmCache.set(selectedFile.path, frontmatter);
+            const { frontmatter, body } = parseFrontmatter(content);
+            fmCache.set(selectedFile.path, { frontmatter, body });
             setSelectedFrontmatter(frontmatter);
+            setSelectedBody(body);
         })
             .catch(() => {
-            fmCache.set(selectedFile.path, null);
+            fmCache.set(selectedFile.path, { frontmatter: null, body: "" });
             setSelectedFrontmatter(null);
+            setSelectedBody("");
         });
     }, [selectedFile?.path]);
     /** Load and parse a file for drill-in view. */
@@ -109,12 +118,12 @@ export default function App({ root, initialNodes }) {
             const content = await readFile(file.path, "utf-8");
             const { frontmatter, body } = parseFrontmatter(content);
             const sections = parseBody(body);
-            const data = { frontmatter, sections };
+            const data = { frontmatter, body, sections };
             drillCache.set(file.path, data);
             setDrillData(data);
         }
         catch {
-            setDrillData({ frontmatter: null, sections: [] });
+            setDrillData({ frontmatter: null, body: "", sections: [] });
         }
     }, [drillCache]);
     /** Toggle deep view on/off, caching shallow results for instant restore. */
@@ -277,6 +286,6 @@ export default function App({ root, initialNodes }) {
         // Enter is a no-op in drill-in mode.
     });
     // --- Layout ---
-    const treeWidth = Math.floor(columns * 0.38);
-    return (_jsxs(Box, { flexDirection: "row", width: columns, children: [_jsxs(Box, { flexDirection: "column", width: treeWidth, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Intent Tree" }), deepLoading && _jsx(Text, { color: "yellow", children: "  Loading summaries..." }), _jsx(TreePanel, { visibleNodes: visibleNodes, cursorIndex: clampedCursor, searchFilter: searchFilter, isDeepView: isDeepView, expandedDirs: expandedDirs, cursorOnDir: cursorOnDir, cursorDirExpanded: cursorDirExpanded, width: treeWidth - 2 })] }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Detail" }), _jsx(DetailPanel, { file: selectedFile, frontmatter: mode === "drill-in" ? (drillData?.frontmatter ?? null) : selectedFrontmatter, mode: mode === "drill-in" ? "drill-in" : "preview", sections: drillData?.sections ?? [], expandedSection: expandedSection, drilledFilePath: drilledFile?.relativePath ?? null })] })] }));
+    const treeWidth = Math.floor(columns * 0.57);
+    return (_jsxs(Box, { flexDirection: "row", width: columns, children: [_jsxs(Box, { flexDirection: "column", width: treeWidth, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Intent Tree" }), deepLoading && _jsx(Text, { color: "yellow", children: "  Loading summaries..." }), _jsx(TreePanel, { visibleNodes: visibleNodes, cursorIndex: clampedCursor, searchFilter: searchFilter, isDeepView: isDeepView, expandedDirs: expandedDirs, cursorOnDir: cursorOnDir, cursorDirExpanded: cursorDirExpanded, width: treeWidth - 2 })] }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Detail" }), _jsx(DetailPanel, { file: selectedFile, frontmatter: mode === "drill-in" ? (drillData?.frontmatter ?? null) : selectedFrontmatter, body: mode === "drill-in" ? (drillData?.body ?? "") : selectedBody, mode: mode === "drill-in" ? "drill-in" : "preview", sections: drillData?.sections ?? [], expandedSection: expandedSection, drilledFilePath: drilledFile?.relativePath ?? null })] })] }));
 }

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

@@ -3,6 +3,8 @@ import type { AideFile, AideFrontmatter, BodySection } from "../../types/index.j
 interface DetailPanelProps {
     file: AideFile | null;
     frontmatter: AideFrontmatter | null;
+    /** Raw body content of the selected or drilled-in file. Used by plan/todo renderers. */
+    body: string;
     /** Controls which rendering mode is active in the right panel. */
     mode: "preview" | "drill-in";
     /** Body sections from the drilled-in file. */
@@ -16,9 +18,11 @@ interface DetailPanelProps {
  * Right-panel component that handles both preview mode (tree navigation) and
  * drill-in mode (formatted frontmatter card with expandable body sections).
  *
- * In preview mode: scope, truncated intent, and outcome counts.
- * In drill-in mode: full frontmatter card (scope heading, full intent, side-by-side
- * outcomes) plus expandable body sections cycled with Tab.
+ * Delegates to RenderPlanDetail for plan files and RenderTodoDetail for todo files.
+ * Intent and research files use the intent-card layout (scope, intent, outcomes).
+ *
+ * In preview mode: scope, truncated intent, and outcome counts (or plan/todo summary).
+ * In drill-in mode: full frontmatter card or plan/todo detail view.
  */
-export default function DetailPanel({ file, frontmatter, mode, sections, expandedSection, drilledFilePath, }: DetailPanelProps): React.ReactElement;
+export default function DetailPanel({ file, frontmatter, body, mode, sections, expandedSection, drilledFilePath, }: DetailPanelProps): React.ReactElement;
 export {};

package/dist/cli/DetailPanel/index.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text, useStdout } from "ink";
+import RenderPlanDetail from "./renderPlanDetail/index.js";
+import RenderTodoDetail from "./renderTodoDetail/index.js";
 /** Truncate a string to maxLen chars, appending "..." if trimmed. */
 function truncate(s, maxLen) {
     if (s.length <= maxLen)
@@ -21,11 +23,13 @@ function OutcomesDisplay({ desired, undesired, wide, }) {
  * Right-panel component that handles both preview mode (tree navigation) and
  * drill-in mode (formatted frontmatter card with expandable body sections).
  *
- * In preview mode: scope, truncated intent, and outcome counts.
- * In drill-in mode: full frontmatter card (scope heading, full intent, side-by-side
- * outcomes) plus expandable body sections cycled with Tab.
+ * Delegates to RenderPlanDetail for plan files and RenderTodoDetail for todo files.
+ * Intent and research files use the intent-card layout (scope, intent, outcomes).
+ *
+ * In preview mode: scope, truncated intent, and outcome counts (or plan/todo summary).
+ * In drill-in mode: full frontmatter card or plan/todo detail view.
  */
-export default function DetailPanel({ file, frontmatter, mode, sections, expandedSection, drilledFilePath, }) {
+export default function DetailPanel({ file, frontmatter, body, mode, sections, expandedSection, drilledFilePath, }) {
     const { stdout } = useStdout();
     const columns = stdout?.columns ?? 80;
     const wide = columns >= 80;
@@ -34,6 +38,14 @@ export default function DetailPanel({ file, frontmatter, mode, sections, expande
         if (!file) {
             return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: "gray", children: "Select a file to preview" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "Type to search, [tab] for deep view" }) })] }));
         }
+        // Delegate to type-specific renderers for plan and todo files.
+        if (file.type === "plan") {
+            return _jsx(RenderPlanDetail, { file: file, frontmatter: frontmatter, mode: "preview", body: body, drilledFilePath: null });
+        }
+        if (file.type === "todo") {
+            const description = frontmatter?.description ?? file.description ?? "";
+            return _jsx(RenderTodoDetail, { description: description, body: body, mode: "preview", filePath: file.relativePath });
+        }
         if (!frontmatter) {
             return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: "red", children: "[FAILED TO PARSE]" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: file.relativePath }) })] }));
         }
@@ -44,6 +56,14 @@ export default function DetailPanel({ file, frontmatter, mode, sections, expande
         return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsxs(Text, { bold: true, children: ["scope: ", scope] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { wrap: "wrap", children: intent }) }), (desiredCount > 0 || undesiredCount > 0) && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { color: "green", children: ["\u2713 desired (", desiredCount, ")"] }), _jsxs(Text, { color: "red", children: ["\u2717 undesired (", undesiredCount, ")"] })] })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[\u2191\u2193] navigate  [enter] drill in  [tab] deep view" }) })] }));
     }
     // --- Drill-in mode ---
+    // Delegate to type-specific renderers for plan and todo files.
+    if (file?.type === "plan") {
+        return _jsx(RenderPlanDetail, { file: file, frontmatter: frontmatter, mode: "drill-in", body: body, drilledFilePath: drilledFilePath });
+    }
+    if (file?.type === "todo") {
+        const description = frontmatter?.description ?? file?.description ?? "";
+        return _jsx(RenderTodoDetail, { description: description, body: body, mode: "drill-in", filePath: drilledFilePath ?? file?.relativePath ?? "" });
+    }
     const title = drilledFilePath ?? "[unknown]";
     const scope = frontmatter?.scope ?? "[FAILED TO PARSE]";
     const intent = frontmatter?.intent ?? "[FAILED TO PARSE]";

package/dist/cli/DetailPanel/renderPlanDetail/index.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+import type { AideFile, AideFrontmatter } from "../../../types/index.js";
+interface RenderPlanDetailProps {
+    file: AideFile;
+    frontmatter: AideFrontmatter | null;
+    /** Controls which rendering mode is active in the right panel. */
+    mode: "preview" | "drill-in";
+    /** Raw body content of the plan file. */
+    body: string;
+    /** File path shown as the panel title during drill-in, or null in preview mode. */
+    drilledFilePath: string | null;
+}
+/**
+ * Detail panel renderer for plan files (.aide files of type "plan").
+ *
+ * Preview mode: description from frontmatter, progress fraction, remaining count.
+ * Drill-in mode: grouped checklist items by step heading, completion summary at top.
+ */
+export default function RenderPlanDetail({ file, frontmatter, mode, body, drilledFilePath, }: RenderPlanDetailProps): React.ReactElement;
+export {};

package/dist/cli/DetailPanel/renderPlanDetail/index.js

@@ -0,0 +1,30 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import parsePlanItems from "./parsePlanItems/index.js";
+/** Renders a compact ASCII progress bar of fixed width. */
+function ProgressBar({ done, total, width }) {
+    const filled = total > 0 ? Math.round((done / total) * width) : 0;
+    const bar = "█".repeat(filled) + "░".repeat(width - filled);
+    return _jsxs(Text, { color: "cyan", children: ["[", bar, "]"] });
+}
+/**
+ * Detail panel renderer for plan files (.aide files of type "plan").
+ *
+ * Preview mode: description from frontmatter, progress fraction, remaining count.
+ * Drill-in mode: grouped checklist items by step heading, completion summary at top.
+ */
+export default function RenderPlanDetail({ file, frontmatter, mode, body, drilledFilePath, }) {
+    const steps = parsePlanItems(body);
+    const allItems = steps.flatMap((s) => s.items);
+    const doneCount = allItems.filter((i) => i.done).length;
+    const totalCount = allItems.length;
+    const remainingCount = totalCount - doneCount;
+    // --- Preview mode ---
+    if (mode === "preview") {
+        const description = frontmatter?.description ?? file.description ?? "";
+        return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [description !== "" && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { wrap: "wrap", children: description }) })), _jsxs(Box, { flexDirection: "row", gap: 1, alignItems: "center", children: [_jsx(ProgressBar, { done: doneCount, total: totalCount, width: 20 }), _jsxs(Text, { children: [doneCount, "/", totalCount, " complete"] })] }), remainingCount > 0 && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "gray", children: [remainingCount, " item", remainingCount !== 1 ? "s" : "", " remaining"] }) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[\u2191\u2193] navigate  [enter] drill in  [tab] deep view" }) })] }));
+    }
+    // --- Drill-in mode ---
+    const title = drilledFilePath ?? file.relativePath;
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, flexGrow: 1, children: [_jsx(Text, { bold: true, children: title }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { bold: true, color: doneCount === totalCount && totalCount > 0 ? "green" : "cyan", children: ["Progress: ", doneCount, "/", totalCount, " step", totalCount !== 1 ? "s" : "", " complete"] }) }), steps.length > 0 && (_jsx(Box, { flexDirection: "column", marginTop: 1, children: steps.map((s, si) => (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [s.step !== "" && (_jsx(Text, { bold: true, children: s.step })), s.items.map((item, ii) => (_jsxs(Box, { flexDirection: "row", marginLeft: s.step !== "" ? 2 : 0, children: [item.done ? (_jsx(Text, { color: "green", children: "\u2713 " })) : (_jsx(Text, { color: "gray", children: "\u25CB " })), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { color: item.done ? "gray" : undefined, wrap: "wrap", children: item.text }) })] }, ii)))] }, si))) })), totalCount === 0 && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "No checklist items found." }) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[esc] back  [e] open in editor" }) })] }));
+}

package/dist/cli/DetailPanel/renderPlanDetail/parsePlanItems/index.d.ts

@@ -0,0 +1,32 @@
+/** A single checklist item within a plan step. */
+export interface PlanItem {
+    text: string;
+    done: boolean;
+}
+/** A plan step grouping with its heading label and checklist items. */
+export interface PlanStep {
+    step: string;
+    done: boolean;
+    items: PlanItem[];
+}
+/**
+ * Parse a plan file body string into structured step groups with checklist items.
+ *
+ * Recognises three heading formats found in this project's plan files:
+ *
+ * 1. `### N. [x] Step title`  — numbered with inline checkbox (cli/plan.aide)
+ * 2. `### N. Step title`       — numbered without inline checkbox
+ * 3. `### Phase N — Title`     — Phase-prefixed with em-dash (init/plan.aide)
+ *
+ * Checklist items below a heading are lines matching `- [x]` or `- [ ]`.
+ * Prose items (non-checklist bullet lines) and all other non-heading lines
+ * are ignored. Items that appear before any heading are grouped under an
+ * empty-string step.
+ *
+ * The `done` field on a `PlanStep` is determined as follows:
+ * - If the heading carries an inline `[x]`/`[ ]` marker (format 1), that
+ *   marker is authoritative — `done` is not overridden by item states.
+ * - Otherwise `done` is derived: true when all contained items are done,
+ *   false when any item is undone or the step has no items.
+ */
+export default function parsePlanItems(body: string): PlanStep[];

package/dist/cli/DetailPanel/renderPlanDetail/parsePlanItems/index.js

@@ -0,0 +1,80 @@
+/**
+ * Parse a plan file body string into structured step groups with checklist items.
+ *
+ * Recognises three heading formats found in this project's plan files:
+ *
+ * 1. `### N. [x] Step title`  — numbered with inline checkbox (cli/plan.aide)
+ * 2. `### N. Step title`       — numbered without inline checkbox
+ * 3. `### Phase N — Title`     — Phase-prefixed with em-dash (init/plan.aide)
+ *
+ * Checklist items below a heading are lines matching `- [x]` or `- [ ]`.
+ * Prose items (non-checklist bullet lines) and all other non-heading lines
+ * are ignored. Items that appear before any heading are grouped under an
+ * empty-string step.
+ *
+ * The `done` field on a `PlanStep` is determined as follows:
+ * - If the heading carries an inline `[x]`/`[ ]` marker (format 1), that
+ *   marker is authoritative — `done` is not overridden by item states.
+ * - Otherwise `done` is derived: true when all contained items are done,
+ *   false when any item is undone or the step has no items.
+ */
+export default function parsePlanItems(body) {
+    const lines = body.split("\n");
+    const steps = [];
+    let current = null;
+    for (const raw of lines) {
+        const line = raw.trim();
+        // Format 1: ### N. [x] Step title  (inline checkbox in heading)
+        const inlineCheckHeading = line.match(/^###\s+\d+\.\s+\[(x| )\]\s+(.+)$/i);
+        if (inlineCheckHeading) {
+            current = {
+                step: inlineCheckHeading[2].trim(),
+                done: inlineCheckHeading[1].toLowerCase() === "x",
+                items: [],
+                _headingCheckbox: true,
+            };
+            steps.push(current);
+            continue;
+        }
+        // Format 2: ### N. Step title  (no inline checkbox)
+        const numberedHeading = line.match(/^###\s+\d+\.\s+(.+)$/);
+        if (numberedHeading) {
+            current = { step: numberedHeading[1].trim(), done: false, items: [], _headingCheckbox: false };
+            steps.push(current);
+            continue;
+        }
+        // Format 3: ### Phase N — Title  (Phase prefix with em-dash, en-dash, or hyphen)
+        const phaseHeading = line.match(/^###\s+Phase\s+\d+\s+[—–-]+\s+(.+)$/i);
+        if (phaseHeading) {
+            current = { step: phaseHeading[1].trim(), done: false, items: [], _headingCheckbox: false };
+            steps.push(current);
+            continue;
+        }
+        const checkedMatch = line.match(/^-\s+\[x\]\s+(.+)$/i);
+        if (checkedMatch) {
+            if (!current) {
+                current = { step: "", done: false, items: [], _headingCheckbox: false };
+                steps.push(current);
+            }
+            current.items.push({ text: checkedMatch[1].trim(), done: true });
+            continue;
+        }
+        const uncheckedMatch = line.match(/^-\s+\[ \]\s+(.+)$/);
+        if (uncheckedMatch) {
+            if (!current) {
+                current = { step: "", done: false, items: [], _headingCheckbox: false };
+                steps.push(current);
+            }
+            current.items.push({ text: uncheckedMatch[1].trim(), done: false });
+        }
+    }
+    // Derive done for steps whose heading had no inline checkbox:
+    // true only when all items are done and at least one item exists.
+    for (const step of steps) {
+        if (!step._headingCheckbox && step.items.length > 0) {
+            step.done = step.items.every((item) => item.done);
+        }
+    }
+    // Strip the internal field before returning.
+    return steps.map(({ _headingCheckbox: _hc, ...rest }) => rest);
+}

package/dist/cli/DetailPanel/renderTodoDetail/index.d.ts

@@ -0,0 +1,17 @@
+import React from "react";
+interface RenderTodoDetailProps {
+    /** Frontmatter description field, shown as the preview summary. */
+    description: string;
+    /** Raw body content of the todo file. */
+    body: string;
+    /** Controls which rendering mode is active. */
+    mode: "preview" | "drill-in";
+    /** File path, used as the drill-in panel title. */
+    filePath: string;
+}
+/**
+ * Renders a todo.aide file in preview mode (summary counts) or drill-in mode
+ * (full issue list with misalignment annotations highlighted and completion state).
+ */
+export default function RenderTodoDetail({ description, body, mode, filePath, }: RenderTodoDetailProps): React.ReactElement;
+export {};

package/dist/cli/DetailPanel/renderTodoDetail/index.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import parseTodoItems from "./parseTodoItems/index.js";
+/**
+ * Renders a todo.aide file in preview mode (summary counts) or drill-in mode
+ * (full issue list with misalignment annotations highlighted and completion state).
+ */
+export default function RenderTodoDetail({ description, body, mode, filePath, }) {
+    const items = parseTodoItems(body);
+    const totalCount = items.length;
+    const doneCount = items.filter((item) => item.done).length;
+    const openCount = totalCount - doneCount;
+    const misalignmentCount = items.filter((item) => item.misalignment !== undefined).length;
+    if (mode === "preview") {
+        return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [description ? (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { wrap: "wrap", children: description }) })) : null, _jsxs(Text, { children: ["Issues:", " ", _jsxs(Text, { color: openCount > 0 ? "yellow" : "green", children: [openCount, " open"] }), ", ", _jsxs(Text, { color: "green", children: [doneCount, " resolved"] }), " (", _jsxs(Text, { children: [totalCount, " total"] }), ")"] }), misalignmentCount > 0 && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["\u2691 ", misalignmentCount, " misalignment annotation", misalignmentCount !== 1 ? "s" : ""] }) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[\u2191\u2193] navigate  [enter] drill in  [tab] deep view" }) })] }));
+    }
+    // Drill-in mode — full issue list
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, flexGrow: 1, children: [_jsx(Text, { bold: true, children: filePath }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { children: ["Issues:", " ", _jsxs(Text, { color: openCount > 0 ? "yellow" : "green", children: [openCount, " open"] }), ", ", _jsxs(Text, { color: "green", children: [doneCount, " resolved"] }), " (", _jsxs(Text, { children: [totalCount, " total"] }), ")"] }) }), items.length === 0 ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "No checklist items found." }) })) : (_jsx(Box, { flexDirection: "column", marginTop: 1, children: items.map((item, i) => (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { flexDirection: "row", children: [item.done ? (_jsx(Text, { color: "green", children: "\u2713 " })) : (_jsx(Text, { color: "gray", children: "\u25CB " })), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { color: item.misalignment !== undefined ? "yellow" : undefined, wrap: "wrap", children: item.text }) })] }), item.misalignment !== undefined && (_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { color: "red", children: ["\u2691 Misalignment: ", item.misalignment] }) }))] }, i))) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[esc] back  [e] open in editor" }) })] }));
+}

package/dist/cli/DetailPanel/renderTodoDetail/parseTodoItems/index.d.ts

@@ -0,0 +1,26 @@
+/** A single parsed checklist item from a todo.aide body. */
+export interface TodoItem {
+    /** The main text of the checklist item (first line only, not continuation lines). */
+    text: string;
+    /** Whether the item is checked (`- [x]`). */
+    done: boolean;
+    /**
+     * The Misalignment annotation extracted from a continuation line, if present.
+     * e.g. "implementation-drift" from a line like "  Misalignment: implementation-drift"
+     */
+    misalignment?: string;
+}
+/**
+ * Parses the body of a todo.aide file into a structured array of checklist items.
+ *
+ * Format recognised:
+ *   - `- [x] item text`   — completed item
+ *   - `- [ ] item text`   — open item
+ *   Continuation lines (indented lines that follow a checklist item) are scanned
+ *   for a `Misalignment:` annotation. The first such annotation found is attached
+ *   to the preceding item. All other continuation lines are ignored.
+ *
+ * Lines that are not checklist items and not continuations of a checklist item
+ * (e.g. `##` headings, blank lines, Retro sections) are ignored.
+ */
+export default function parseTodoItems(body: string): TodoItem[];

package/dist/cli/DetailPanel/renderTodoDetail/parseTodoItems/index.js

@@ -0,0 +1,48 @@
+/**
+ * Parses the body of a todo.aide file into a structured array of checklist items.
+ *
+ * Format recognised:
+ *   - `- [x] item text`   — completed item
+ *   - `- [ ] item text`   — open item
+ *   Continuation lines (indented lines that follow a checklist item) are scanned
+ *   for a `Misalignment:` annotation. The first such annotation found is attached
+ *   to the preceding item. All other continuation lines are ignored.
+ *
+ * Lines that are not checklist items and not continuations of a checklist item
+ * (e.g. `##` headings, blank lines, Retro sections) are ignored.
+ */
+export default function parseTodoItems(body) {
+    const lines = body.split("\n");
+    const items = [];
+    let current = null;
+    for (const line of lines) {
+        const checkboxMatch = line.match(/^- \[(x| )\] (.+)/);
+        if (checkboxMatch) {
+            // Flush previous item before starting a new one
+            if (current)
+                items.push(current);
+            current = {
+                text: checkboxMatch[2].trim(),
+                done: checkboxMatch[1] === "x",
+            };
+            continue;
+        }
+        // Continuation line — only meaningful after a checklist item
+        if (current && line.match(/^\s+/)) {
+            const misalignmentMatch = line.match(/\bMisalignment:\s*(.+)/);
+            if (misalignmentMatch && !current.misalignment) {
+                current.misalignment = misalignmentMatch[1].trim();
+            }
+            continue;
+        }
+        // Non-item, non-continuation line — flush any pending item
+        if (current) {
+            items.push(current);
+            current = null;
+        }
+    }
+    // Flush the last item if body ended while an item was open
+    if (current)
+        items.push(current);
+    return items;
+}

package/dist/cli/TreePanel/index.js

@@ -1,4 +1,4 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from "ink";
 /** Type-tag display labels keyed by AideFileType. */
 const TYPE_TAG = {
@@ -22,7 +22,24 @@ function renderRow(flatNode, index, cursorIndex, isDeepView, expandedDirs, width
     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}`));
+        // Find the first intent child to surface its status and description on the dir row.
+        const intentChild = node.children.find((c) => c.kind === "file" && c.file.type === "intent");
+        const intentFile = intentChild?.kind === "file" ? intentChild.file : null;
+        const dirStatusBadge = intentFile?.status === "aligned"
+            ? { text: " [aligned]", color: "green" }
+            : intentFile?.status === "misaligned"
+                ? { text: " [misaligned]", color: "red" }
+                : null;
+        const dirDescription = intentFile?.description ?? "";
+        // Truncate description to fit within available panel width.
+        const dirFixedLen = indent.length + expandIndicator.length + label.length + (dirStatusBadge?.text.length ?? 0);
+        const dirRemaining = width - dirFixedLen;
+        let dirSummaryText = "";
+        if (dirDescription && dirRemaining > 10) {
+            const full = ` — ${dirDescription}`;
+            dirSummaryText = full.length <= dirRemaining ? full : `${full.slice(0, dirRemaining - 3)}…`;
+        }
+        return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, color: isCursor ? "white" : "gray", wrap: "truncate", children: [indent, expandIndicator, label, dirStatusBadge ? _jsx(Text, { color: dirStatusBadge.color, children: dirStatusBadge.text }) : null, dirSummaryText ? _jsx(Text, { color: "gray", children: dirSummaryText }) : null] }) }, `dir-${node.path}-${index}`));
     }
     // File node — render as a single <Text> to prevent Ink from wrapping mid-element.
     const { file } = node;
@@ -32,15 +49,26 @@ function renderRow(flatNode, index, cursorIndex, isDeepView, expandedDirs, width
     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;
+    // Determine status badge text and color when a status flag is present.
+    const statusBadge = file.status
+        ? file.status === "aligned"
+            ? { text: " [aligned]", color: "green" }
+            : { text: " [misaligned]", color: "red" }
+        : null;
+    // Truncate summary/description to fit within available panel width.
+    const statusLen = statusBadge ? statusBadge.text.length : 0;
+    const fixedLen = prefix.length + tagStr.length + statusLen;
     const remaining = width - fixedLen;
-    let summary = "";
-    if (isDeepView && file.summary && remaining > 10) {
+    let summaryText = "";
+    if (file.description && remaining > 10) {
+        const full = ` — ${file.description}`;
+        summaryText = full.length <= remaining ? full : `${full.slice(0, remaining - 3)}…`;
+    }
+    else if (!file.description && isDeepView && file.summary && remaining > 10) {
         const full = ` — ${file.summary}`;
-        summary = full.length <= remaining ? full : `${full.slice(0, remaining - 3)}…`;
+        summaryText = 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}`));
+    return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, backgroundColor: isCursor ? "blue" : undefined, wrap: "truncate", children: [prefix, _jsx(Text, { color: tagColor, children: tagStr }), statusBadge ? _jsx(Text, { color: statusBadge.color, children: statusBadge.text }) : null, summaryText ? _jsx(Text, { color: "gray", children: summaryText }) : null] }) }, `file-${file.relativePath}-${index}`));
 }
 /**
  * Renders the left-panel tree of .aide files with cursor highlighting and optional summaries.

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

@@ -76,7 +76,7 @@ export default async function buildAncestorChain(root, targetPath) {
         if (!spec)
             continue;
         const { frontmatter } = parseFrontmatter(spec.content);
-        const description = frontmatter?.description;
+        const description = frontmatter?.description || (frontmatter?.intent ? frontmatter.intent.split(/[.\n]/)[0] : undefined);
         const status = frontmatter?.status;
         // Compute a display path relative to the project root
         const rel = relative(absRoot, spec.specPath).replace(/\\/g, "/");

package/dist/types/index.d.ts

@@ -39,6 +39,10 @@ export interface AideFile {
     type: AideFileType;
     /** First ~80 chars of the first paragraph, for tree summaries. */
     summary: string;
+    /** Frontmatter description field — one-line human-readable summary. Empty string when absent. */
+    description?: string;
+    /** Alignment status from frontmatter — present only when explicitly set. */
+    status?: "aligned" | "misaligned";
 }
 /** Result of scanning a directory tree for .aide files. */
 export interface ScanResult {

package/dist/util/scan/index.d.ts

@@ -2,6 +2,8 @@ import type { ScanResult } from "../../types/index.js";
 /**
  * Recursively walk the filesystem from `root` and collect all .aide files.
  * Skips node_modules, .git, dist, build, .next, coverage, __pycache__.
- * Reads the first ~1000 bytes of each file to extract the first meaningful body line as summary.
+ * In deep mode: reads full content to extract summary, description, and status.
+ * In shallow mode: reads only the first ~500 bytes per file to extract frontmatter
+ * description and status — summary stays empty but descriptions appear unconditionally.
  */
 export default function scan(root: string, path?: string, shallow?: boolean): Promise<ScanResult>;

package/dist/util/scan/index.js

@@ -2,6 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { classifyFile } from "../../util/classify/index.js";
 import { SKIP_DIRS } from "../../types/index.js";
+import parseFrontmatter from "../../util/parseFrontmatter/index.js";
 /** Extract the first meaningful body line as the summary, truncated to ~80 chars. */
 function extractSummary(content) {
     const lines = content.split("\n");
@@ -32,6 +33,17 @@ function extractSummary(content) {
 function toPosix(p) {
     return p.split("\\").join("/");
 }
+/**
+ * Derive a description from frontmatter, falling back to the first sentence of
+ * `intent` when `description` is absent — matching the logic in buildAncestorChain.
+ */
+function deriveDescription(frontmatter) {
+    if (frontmatter?.description)
+        return frontmatter.description;
+    if (frontmatter?.intent)
+        return frontmatter.intent.split(/[.\n]/)[0] ?? "";
+    return "";
+}
 /** Recursively walk a directory and collect all .aide files. */
 async function walk(dir, root, files, shallow) {
     let entries;
@@ -52,10 +64,31 @@ async function walk(dir, root, files, shallow) {
         if (!entry.name.endsWith(".aide"))
             continue;
         let summary = "";
+        let description = "";
+        let status;
         if (!shallow) {
             try {
                 const buf = await readFile(fullPath, { encoding: "utf-8" });
                 summary = extractSummary(buf.slice(0, 1000));
+                const { frontmatter } = parseFrontmatter(buf);
+                description = deriveDescription(frontmatter);
+                if (frontmatter?.status)
+                    status = frontmatter.status;
+            }
+            catch {
+                // skip unreadable files
+            }
+        }
+        else {
+            // In shallow mode, read only the first ~500 bytes to capture frontmatter
+            // without loading the full body — keeps startup fast for large projects.
+            try {
+                const buf = await readFile(fullPath, { encoding: "utf-8" });
+                const head = buf.slice(0, 500);
+                const { frontmatter } = parseFrontmatter(head);
+                description = deriveDescription(frontmatter);
+                if (frontmatter?.status)
+                    status = frontmatter.status;
             }
             catch {
                 // skip unreadable files
@@ -66,13 +99,17 @@ async function walk(dir, root, files, shallow) {
             relativePath: toPosix(relative(root, fullPath)),
             type: classifyFile(entry.name),
             summary,
+            description,
+            status,
         });
     }
 }
 /**
  * Recursively walk the filesystem from `root` and collect all .aide files.
  * Skips node_modules, .git, dist, build, .next, coverage, __pycache__.
- * Reads the first ~1000 bytes of each file to extract the first meaningful body line as summary.
+ * In deep mode: reads full content to extract summary, description, and status.
+ * In shallow mode: reads only the first ~500 bytes per file to extract frontmatter
+ * description and status — summary stays empty but descriptions appear unconditionally.
  */
 export default async function scan(root, path, shallow) {
     const scanRoot = path ? join(root, path) : root;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aidemd-mcp/server",
-	"version": "0.2.4",
+	"version": "0.3.0",
 	"description": "MCP server that teaches any agent the AIDE methodology through tool descriptions and progressive disclosure tooling",
 	"type": "module",
 	"bin": {