@aidemd-mcp/server 0.2.3 → 0.3.0

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.3",
+	"version": "0.3.0",
 	"description": "MCP server that teaches any agent the AIDE methodology through tool descriptions and progressive disclosure tooling",
 	"type": "module",
 	"bin": {