@aidemd-mcp/server 0.2.3 → 0.3.0

package/.aide/todo.aide

@@ -1,47 +1,38 @@
 ---
+description: >
+  QA findings for the README.md rewrite — tracks the missing @latest on the Quick Start npx command.
 intent: >
-  Canonical docs updated in c32e887 (orchestrator, synthesize phase, plan.aide
-  spec, todo.aide spec, expanded file-type table, seven-doc hub) but downstream
-  .aide intent specs still reference the pre-commit state: four file types
-  instead of five, six pipeline commands instead of seven-plus, five canonical
-  docs instead of seven, and todo.aide described as a "QA queue" instead of a
-  re-alignment document. The specs no longer faithfully reflect the methodology
-  they are supposed to deliver.
+  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
+  cached version of the CLI init subcommand to users who have previously
+  installed any version of the package.
 misalignment:
-  - implementation-drift
+  - plan-gap
 ---
 
 ## Issues
 
-- [x] **src/.aide:21** — Teaches "the four file types" in tool descriptions; canonical `aide-spec.md` now defines five file types (`.aide`, `intent.aide`, `research.aide`, `plan.aide`, `todo.aide`).
-      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
-
-- [x] **src/.aide:149-152** — Good example describes `todo.aide` as "a QA queue". Canonical docs redefine it as a "QA re-alignment document" with misalignment tags and a `## Retro` section.
-      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
-
-- [x] **src/tools/init/.aide:33-34** — References "six pipeline slash commands (research, spec, plan, build, qa, fix)". Canonical pipeline now includes a synthesize phase (`/aide:synthesize`) and an orchestrator entry point (`/aide`).
-      Traces to: `outcomes.desired[3]` | Misalignment: `implementation-drift`
-
-- [x] **src/tools/init/.aide:194-209** — Good examples list exactly six scaffolded commands and six "already present" lines. Missing synthesize phase; summary shape no longer matches what init actually produces after the doc update.
-      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
-
-- [x] **src/tools/init/scaffoldCommands/.aide:1-4** — Intent says "six AIDE pipeline slash commands (research, spec, plan, build, qa, fix)" and enforces a six-cap throughout. The canonical pipeline now has seven phase commands (adding synthesize). The "six-cap" language on lines 20, 81, 114, 116 is all stale.
-      Traces to: `outcomes.desired[3]` | Misalignment: `implementation-drift`
-
-- [x] **src/tools/init/installMethodologyDocs/.aide:101** — Context says "five canonical files under `docs/`". The hub index now lists seven docs (added `plan-aide.md` and `todo-aide.md`). The number "five" also appears in the bad-examples section (line 255) and good-examples section (line 198).
-      Traces to: `outcomes.desired[1]` | Misalignment: `implementation-drift`
-
-- [x] **src/tools/discover/.aide:23** — Type tags listed as `[intent]`, `[research]`, `[todo]`. Missing `[plan]` tag for the new `plan.aide` file type.
-      Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
-
-- [x] **src/tools/scaffold/.aide:1-28** — Supports types: intent, research, both, todo. Does not support `type=plan` for creating `plan.aide` files. The canonical `aide-spec.md` file-type table now includes `plan.aide` as a first-class file type that scaffold should know how to create.
-      Traces to: `outcomes.desired[1]` | Misalignment: `implementation-drift`
+- [ ] **README.md:25** — Quick Start block uses `npx @aidemd-mcp/server init` without `@latest`. The spec requires `@latest` on all npx invocations ("use `npx -y @aidemd-mcp/server@latest` rather than a bare package name. The bare name uses a locally cached version if one exists"). The plan carried this omission forward (plan.aide line 34 shows `npx @aidemd-mcp/server init` without `@latest`), meaning the gap originated at planning, not implementation.
+      Traces to: `outcomes.undesired[4]` ("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") | Misalignment: `plan-gap`
 
 ## Retro
 
-Every issue traces to a single cause: the canonical docs were updated in one commit but the downstream `.aide` specs that encode the same facts were not updated in the same commit. The commit changed the source of truth; the renderers of that truth were left behind.
+The spec's `@latest` requirement was written with config blocks in mind and the
+strategy section explicitly mentions "config blocks" as the scope ("all config
+blocks"). The plan correctly applied `@latest` to every JSON config block under
+Manual Configuration, but silently dropped it from the Quick Start CLI command,
+treating the CLI invocation as exempt from the rule.
+
+The gap is plan-level: the planner read the `@latest` requirement as scoped
+only to JSON config blocks and did not apply it to the `npx @aidemd-mcp/server
+init` CLI command. The spec's good examples show `npx -y
+@aidemd-mcp/server@latest` consistently, including for CLI invocations, but
+the spec's strategy text says "config blocks" — the ambiguity created a
+loophole that the plan exploited.
 
 What would have caught this earlier:
-- A pre-commit check (or a QA pass scoped to `.aide` files) that runs `aide_validate` and flags specs whose file-type counts, command counts, or doc counts disagree with the canonical docs.
-- A convention that any commit touching `.aide/docs/` also touches every downstream `.aide` that references the changed facts — enforced by review checklist, not tooling, until tooling can do it.
-- The orchestrator `/aide` could have been used to drive the doc change itself, which would have surfaced the propagation gap at the plan stage before code was written.
+- The plan step for the Quick Start block should have explicitly cross-checked
+  the `@latest` and `-y` conventions from the spec's strategy section and
+  applied them to the CLI command, not just to the JSON blocks.
+- A QA checklist item "verify every `npx` invocation in the README (not just
+  JSON blocks) uses `@latest`" would have caught this mechanically.

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/README.md

@@ -1,41 +1,130 @@
 # @aidemd-mcp/server
 
-MCP server that teaches any agent the AIDE (Autonomous Intel-Driven Engineering) methodology. When an agent connects, the tool descriptions themselves teach the convention — no config or documentation injection needed.
+[![npm version](https://img.shields.io/npm/v/@aidemd-mcp/server.svg)](https://www.npmjs.com/package/@aidemd-mcp/server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What is AIDE?
+MCP server that brings intent-driven development to any AI-powered IDE.
+Manage `.aide` spec files that live next to your code — the domain context
+that architects plan from, implementors build from, and QA validates against.
 
-AIDE specs are `.aide` files that live next to orchestrator code as progressive disclosure specs. They capture the domain context that code alone doesn't — strategy, research, implementation contracts, and anti-patterns.
+## Features
 
-| File | Purpose |
-|------|---------|
-| `.aide` | Intent spec (default). Strategy, contracts, anti-patterns. |
-| `intent.aide` | Same as `.aide` — used only when `research.aide` exists in the same folder. |
-| `research.aide` | Raw research. Sources, data points, pattern synthesis. |
-| `todo.aide` | QA checklist. Issues found by audit agents. |
+- **Project-wide spec discovery** with a progressive disclosure tree that surfaces intent, research, and QA specs at every level of your codebase
+- **One-command project bootstrap** via `aide_init` — wires methodology docs, pipeline commands, and this MCP server into your project in a single guided flow
+- **Automatic naming convention enforcement** — `aide_scaffold` handles the `.aide` / `intent.aide` rename rules so you never create conflicting specs
+- **Health-check validation** via `aide_validate` — detects orphaned specs, missing descriptions, broken links, and naming conflicts before they cause drift
+- **Upgrade drift detection** via `aide_upgrade` — compares your project's AIDE methodology artifacts against canonical versions and writes updates per-category
 
 ## Installation
 
-Add to your MCP client config:
+### Quick Start (Claude Code)
+
+The fastest path is a single npx command that wires everything up automatically:
+
+```bash
+npx @aidemd-mcp/server@latest init
+```
+
+This command:
+- Merges the AIDE MCP server entry into `.mcp.json` (creates the file or skips the entry if already present)
+- Writes the `/aide:init` slash command to `.claude/commands/aide/init.md` (skips if exists)
+- Writes the `aide-tree` launcher to `.aide/bin/aide-tree.mjs` (skips if exists)
+
+All operations are idempotent — safe to re-run at any time.
+
+After running, open Claude Code and run `/aide:init` to complete setup.
+
+### Manual Configuration
+
+If you use a client other than Claude Code, or prefer to configure manually, add the server entry to your client's MCP config file.
+
+#### Claude Code
+
+```bash
+claude mcp add aide npx -- -y @aidemd-mcp/server@latest
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "aide": {
+      "command": "npx",
+      "args": ["-y", "@aidemd-mcp/server@latest"]
+    }
+  }
+}
+```
+
+> [!NOTE]
+> The Quick Start command above handles this automatically for Claude Code users.
+
+#### Claude Desktop
+
+Config file locations:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "aide": {
       "command": "npx",
-      "args": ["@aidemd-mcp/server"]
+      "args": ["-y", "@aidemd-mcp/server@latest"]
     }
   }
 }
 ```
 
-Or with a custom project root:
+> [!NOTE]
+> Claude Desktop does not inherit the terminal PATH. If you use nvm or Homebrew to manage Node, `npx` may not be found. Run `which npx` in your terminal to get the absolute path and replace `"npx"` with it in the config above.
+
+Claude Desktop requires a full quit-and-reopen after any config change.
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "aide": {
       "command": "npx",
-      "args": ["@aidemd-mcp/server", "--root", "/path/to/project"]
+      "args": ["-y", "@aidemd-mcp/server@latest"]
+    }
+  }
+}
+```
+
+#### VS Code / Copilot
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "aide": {
+      "command": "npx",
+      "args": ["-y", "@aidemd-mcp/server@latest"]
+    }
+  }
+}
+```
+
+> [!NOTE]
+> VS Code / Copilot uses `"servers"` as the root key, not `"mcpServers"`. Using the wrong root key causes the server to silently fail to load.
+
+#### Windsurf
+
+Add to `~/.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "aide": {
+      "command": "npx",
+      "args": ["-y", "@aidemd-mcp/server@latest"]
     }
   }
 }
@@ -43,41 +132,59 @@ Or with a custom project root:
 
 ## Tools
 
-### `aide_discover`
+### aide_discover
+
+Scan the project for `.aide` spec files and return a progressive disclosure tree map showing each spec's type, location, and summary.
+
+**Inputs:**
+- `path` (string, optional): Subdirectory to drill into. When provided, the response opens with the ancestor chain — the cascading intent lineage from root to target, each ancestor showing its description and alignment status — followed by the detailed subtree with summaries and warnings. When omitted, returns a shallow project-wide map (locations and types only).
 
-Scans the project for all `.aide` files and returns a progressive disclosure tree map. This is the flagship tool — it teaches the agent the entire module architecture at a glance.
+### aide_read
 
-**Input:** optional `path` (subdirectory to scan)
+Read an `.aide` spec file with full context, returning the file content, its classified type (intent/research/plan/todo), related specs in the same directory, and links found in the content.
 
-**Output:** Tree showing each spec's type, location, and summary.
+**Inputs:**
+- `path` (string, required): Path to the `.aide` file to read.
 
-### `aide_read`
+### aide_scaffold
 
-Reads an `.aide` file with context awareness. Returns the file content, classified type, sibling specs in the same directory, and links found in the content (wikilinks, relative paths, URLs).
+Create new `.aide` spec files with automatic naming convention enforcement. Handles the rename rules: intent specs are `.aide` by default but become `intent.aide` when `research.aide` exists in the same folder; creating a `research.aide` auto-renames any existing `.aide` to `intent.aide`.
 
-**Input:** `path` (required)
+**Inputs:**
+- `directory` (string, required): Directory where the `.aide` file(s) will be created.
+- `type` (string, required): Type of `.aide` file to create. One of: `intent`, `research`, `both`, `todo`, `plan`.
 
-### `aide_scaffold`
+### aide_validate
 
-Creates new `.aide` files with automatic naming convention enforcement. Handles auto-rename logic — creating a `research.aide` will rename an existing `.aide` to `intent.aide`.
+Run a health check on `.aide` spec files in the project. Detects orphaned specs, missing specs, naming conflicts (`.aide` and `intent.aide` in the same folder), broken links, orphaned research files, and missing frontmatter descriptions.
 
-**Input:** `directory` (required), `type` (required: `intent` | `research` | `both` | `todo`)
+**Inputs:**
+- `path` (string, optional): Subdirectory to validate. Defaults to the entire project when omitted.
 
-### `aide_validate`
+### aide_init
 
-Health check for `.aide` spec files. Detects orphaned specs, missing specs, naming conflicts, broken links, and orphaned research files.
+Bootstrap the AIDE development environment into a project using a guided one-at-a-time wizard. On the first call (no `category`), returns a summary of every step with status and detected framework. On subsequent calls (with `category`), writes all pending files for that category to disk and returns a manifest.
 
-**Input:** optional `path` (subdirectory to validate)
+**Inputs:**
+- `framework` (string, optional): Force a specific framework instead of auto-detecting. One of: `claude`, `cursor`, `windsurf`, `copilot`.
+- `path` (string, optional): Custom project root path. Defaults to the server working directory.
+- `category` (string, optional): Write all `would-create` files for this category and return a manifest. One of: `framework`, `methodology`, `commands`, `agents`, `skills`, `mcp`, `brain`, `ide`. Omit on the first call to get a metadata-only summary.
+- `brainPath` (string, optional): Resolved brain vault path. Required when `category=brain`.
 
-### `aide_init`
+### aide_upgrade
 
-Bootstrap the AIDE development environment into a project with one command. Detects the agent framework, writes the AIDE methodology into the agent's config file, scaffolds slash commands for every pipeline phase (`/aide-research`, `/aide-spec`, `/aide-synthesize`, `/aide-plan`, `/aide-build`, `/aide-qa`, `/aide-fix`, `/aide-refactor`), and wires this MCP server into the project's MCP config.
+Compare the AIDE methodology artifacts in this project against canonical versions and return a structured diff grouped by category. On the first call (no `category`), returns a lightweight summary of every category with drift status. On subsequent calls (with `category`), writes all diffed or missing files for that category to disk and returns a manifest.
 
-Supports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects from marker files or accepts an override.
+**Inputs:**
+- `framework` (string, optional): Force a specific framework instead of auto-detecting. One of: `claude`, `cursor`, `windsurf`, `copilot`.
+- `path` (string, optional): Custom project root path. Defaults to the server working directory.
+- `category` (string, optional): Write all drifted or missing files for this category and return a manifest. One of: `pointer-stub`, `methodology-docs`, `version-metadata`, `commands`, `agents`, `skills`, `mcp`, `ide`. Omit on the first call to get a metadata-only summary.
 
-**Input:** optional `framework` (`claude` | `cursor` | `windsurf` | `copilot`), optional `path` (project root)
+## Getting Started
 
-Each step is idempotent — running on an already-initialized project reports what's present without overwriting.
+After adding the server to your MCP client, ask your agent to run `aide_init` to bootstrap the AIDE methodology into your project. This installs the methodology docs, scaffolds pipeline commands, and wires everything up.
+
+Then try: "Scaffold an intent spec for my authentication module" — the agent will use `aide_discover` to map your project and `aide_scaffold` to create the spec in the right place with the right naming conventions.
 
 ## Development
 
@@ -86,3 +193,7 @@ npm install
 npm run build
 npm test
 ```
+
+## License
+
+[MIT](https://github.com/aidemd-mcp/server/blob/main/LICENSE)

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]";