@aidemd-mcp/server 0.2.3 → 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,169 +1,100 @@
 ---
+description: >
+  Plan to rewrite README.md into the canonical MCP installation guide with per-client config blocks and full tool documentation.
 intent: >
-  Bring the aidemd-mcp codebase into alignment with the canonical docs updated
-  in c32e887: five file types (adding plan), seven phase commands (adding
-  synthesize) plus the /aide orchestrator, seven canonical docs plus index
-  (adding plan-aide.md and todo-aide.md), todo.aide redefined as a QA
-  re-alignment document, and discover tags including [plan].
+  Rewrite README.md to match the readme.aide spec — quick-install via
+  npx @aidemd-mcp/server init as recommended primary path, per-client manual
+  config blocks as fallback, full tool parameter documentation, badges,
+  features list, post-install block, and npm-safe rendering throughout.
 ---
 
 ## Plan
 
-- [x] **Step 1 — src/types/index.ts line 2: expand AideFileType union.**
-      Change `"intent" | "research" | "todo"` to `"intent" | "research" | "todo" | "plan"`.
-      Update the JSDoc comment on line 1 from "The three spec types plus QA checklist"
-      to "The four spec types plus QA re-alignment document" (or equivalent wording
-      that reflects five file types total with plan included). No other changes in
-      this file.
-
-- [x] **Step 2 — src/util/classify/index.ts line 12-17: add plan.aide classification branch.**
-      Add a branch `if (base === "plan.aide") return "plan";` before the final
-      `return "intent"` fallback. Update the JSDoc on the function (lines 7-11) to
-      list all five patterns: `.aide` or `intent.aide` -> "intent", `research.aide` ->
-      "research", `todo.aide` -> "todo", `plan.aide` -> "plan". Order the branches
-      so the specific named files are checked before the catch-all intent return:
-      research, todo, plan, then fallback to intent.
-
-- [x] **Step 3 — src/tools/discover/buildTree/index.ts line 5: add plan to TYPE_ORDER.**
-      Change `{ intent: 0, research: 1, todo: 2 }` to
-      `{ intent: 0, research: 1, plan: 2, todo: 3 }`. Plan sorts after research
-      (it is the architect's artifact derived from the intent) and before todo
-      (which is the QA artifact). Update the JSDoc on line 4 to read:
-      "Sort priority for file types: intent first, then research, plan, then todo."
-      Also update the tree-rendering JSDoc on buildTree (line 34) to include `[plan]`
-      in the tag list: `[intent]`, `[research]`, `[plan]`, `[todo]`.
-
-- [x] **Step 4 — src/tools/scaffold/index.ts: add plan type and template.**
-      4a. Line 8: change the Zod enum from `["intent", "research", "both", "todo"]` to
-      `["intent", "research", "both", "todo", "plan"]`. Update the `.describe()` text
-      to mention plan.
-      4b. Add a `PLAN_TEMPLATE` constant after the existing `TODO_TEMPLATE` (after
-      line 43). Content should match the plan.aide spec format from
-      `.aide/docs/plan-aide.md` — a minimal scaffold with frontmatter `intent` field
-      and `## Plan` / `## Decisions` body sections:
-      ```
-      ---
-      intent: >
-
-      ---
-
-      ## Plan
-
-      - [ ]
-
-      ## Decisions
-
-      ```
-      4c. Line 67: change the `type` parameter signature from
-      `"intent" | "research" | "both" | "todo"` to
-      `"intent" | "research" | "both" | "todo" | "plan"`.
-      4d. Add a `plan` branch in the `if/else` chain (after the `todo` branch,
-      before `intent`). It should mirror the todo branch exactly in structure:
-      create `plan.aide` in the target directory using `PLAN_TEMPLATE`, push
-      action "Created plan.aide". Plan is orthogonal to intent/research naming
-      — no rename logic needed.
-      4e. Update the function-level JSDoc (lines 56-63) to document the new
-      `type=plan` branch: "type=plan -> creates plan.aide".
-
-- [x] **Step 5 — src/tools/init/initContent/index.ts: add plan-aide, todo-aide docs
-      and synthesize + aide orchestrator command entries.**
-      5a. DOC_PATHS (lines 34-47): add two methodology doc entries:
-      `"plan-aide": ".aide/docs/plan-aide.md"` and
-      `"todo-aide": ".aide/docs/todo-aide.md"`.
-      Add two command entries:
-      `"commands/aide/synthesize": ".claude/commands/aide/synthesize.md"` and
-      `"commands/aide/aide": ".claude/commands/aide.md"` (the orchestrator lives
-      at the commands root as `aide.md`, not inside the `aide/` subfolder — check
-      that the path `.claude/commands/aide.md` resolves correctly relative to
-      REPO_ROOT).
-      Note: the orchestrator canonical template is at `.claude/commands/aide.md`
-      which is a peer of the `aide/` folder, not inside it.
-      5b. METHODOLOGY_DOCS (lines 71-78): append two entries to the array:
-      `{ canonical: "plan-aide", hostFilename: "plan-aide.md" }` and
-      `{ canonical: "todo-aide", hostFilename: "todo-aide.md" }`.
-      These go after the existing `automated-qa` entry and before the closing
-      bracket. Keep insertion order matching the hub index reading order.
-
-- [x] **Step 6 — src/tools/init/scaffoldCommands/index.ts: add synthesize command
-      and /aide orchestrator.**
-      6a. COMMANDS array (lines 30-37): add the synthesize phase command entry:
-      `{ canonical: "commands/aide/synthesize", hostPath: "aide/synthesize.md", displayName: "aide:synthesize" }`.
-      Insert it between the `spec` entry and the `plan` entry to match pipeline
-      order: research, spec, synthesize, plan, build, qa, fix.
-      6b. Add the `/aide` orchestrator command entry:
-      `{ canonical: "commands/aide/aide", hostPath: "aide.md", displayName: "aide" }`.
-      **Important**: the orchestrator's `hostPath` is `"aide.md"` (at the command
-      directory root), NOT `"aide/aide.md"` (inside the subfolder). It is a peer
-      of the `aide/` subfolder. Place it as the first entry in the COMMANDS array
-      so it is installed and reported before the seven phase commands.
-      6c. Update the JSDoc comment on lines 9-25: change "six AIDE pipeline slash
-      commands" to "seven AIDE pipeline phase commands plus the /aide orchestrator
-      entry point". Explain that the orchestrator is installed as `aide.md` at
-      the command directory root (a peer of `aide/`), while phase commands go
-      inside `aide/`. Update any references to "six" or "six-phase cap" to
-      reflect the new count.
-
-- [x] **Step 7 — src/index.ts: update stale tool description strings.**
-      7a. `aide_discover` description (lines 34-35): where it lists file types,
-      add the plan.aide type. The current text lists four types (.aide, intent.aide,
-      research.aide, todo.aide). Add between research.aide and todo.aide:
-      `- plan.aide -- Architect's implementation plan. Checkboxed steps for the implementor.`
-      Also update the count text from "File types:" (which implies four) to
-      explicitly name all five. Update the description of todo.aide from
-      "QA checklist. Issues found by audit agents." to
-      "QA re-alignment document. Captures where implementation drifted from intent."
-      7b. `aide_read` description (line 50): change the parenthetical
-      `(intent/research/todo)` to `(intent/research/plan/todo)`.
-      7c. `aide_scaffold` description (lines 64-65): add `plan` to the Types list.
-      Add a line: `- plan -- Architect's implementation plan (no naming interaction
-      with intent/research)`. Also update the todo description from
-      "QA checklist for audit agents" to
-      "QA re-alignment document for QA agents".
-      Update the Zod enum in the inputSchema (line 75) from
-      `["intent", "research", "both", "todo"]` to
-      `["intent", "research", "both", "todo", "plan"]`.
-      7d. `aide_init` description (lines 98-99): update the text that says
-      "scaffolds slash commands for every pipeline phase (research, spec, plan,
-      build, QA, fix)" to include synthesize:
-      "scaffolds slash commands for every pipeline phase (research, spec,
-      synthesize, plan, build, QA, fix) plus the /aide orchestrator entry point".
-      Also ensure the methodology doc hub description mentions "seven canonical
-      methodology docs" (not five or six). Update "six pipeline slash commands"
-      references to "seven pipeline phase commands plus the /aide orchestrator".
+### 1. Write the complete README.md
+
+Read: `coding-playbook/foundations/conventions`
+
+This is a single-file documentation rewrite. The entire README is one cohesive
+document where every section references and flows into the next. It cannot be
+split across agents — section order, cross-references, and consistent voice
+require a single pass. The implementor writes the full file using the structure
+below, sourced entirely from the spec and the tool definitions in source.
+
+**Read before writing:**
+- The full spec at `.aide/readme.aide` (strategy, good/bad examples, all conventions)
+- The tool definitions in `src/index.ts` lines 46-167 (exact parameter names, types, required/optional, enum values, descriptions)
+- The current `README.md` (to understand what exists and what must change)
+
+**Section order** (canonical MCP README order per spec):
+
+- [x] 1a. **H1 + badges + description.** H1 is `# @aidemd-mcp/server`. Badges on the next line: npm version badge linking to npmjs.com/package/@aidemd-mcp/server, MIT license badge linking to opensource.org/licenses/MIT. Use shields.io badge URLs from the spec's good example. Description paragraph below badges — names the value (intent-driven specs next to code), not the mechanism (teaching). Must work as npm subtitle.
+
+- [x] 1b. **Features bullet list.** H2 `## Features`. Three to five bullets naming capabilities from the user's perspective. No "What is AIDE?" explainer, no file-type table. Capabilities to highlight: project-wide spec discovery with progressive disclosure tree, one-command project bootstrap (`aide_init`), automatic naming convention enforcement, health-check validation for spec hygiene, upgrade drift detection for methodology artifacts. Keep each bullet to one line.
+
+- [x] 1c. **Installation section with quick-install primary path and per-client manual fallback.** H2 `## Installation`.
+
+  **Quick Start (recommended) — lead the section with this.** Open with an H3 `### Quick Start (Claude Code)`. One sentence explaining this is the fastest path: a single npx command that wires everything up. Show the command in a bash code block:
+
+  ```
+  npx @aidemd-mcp/server init
+  ```
+
+  Below the code block, add a brief explanation of what the command does (three bullet points):
+  - Merges the AIDE MCP server entry into `.mcp.json` (creates or skips 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)
+
+  End with a one-liner: "All operations are idempotent — safe to re-run at any time." Then a transition sentence: "After running, open Claude Code and run `/aide:init` to complete setup."
+
+  **Manual Configuration (other clients or manual setup) — follows the quick-start.** Add an H3 `### Manual Configuration`. Open with a one-sentence intro: "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." Then one H4 per client, each with a copy-pasteable config block. Every block uses `npx -y @aidemd-mcp/server@latest`. Clients to cover in this order:
+
+  - **Claude Code** (H4) — CLI command (`claude mcp add aide npx -- -y @aidemd-mcp/server@latest`) plus `.mcp.json` JSON block with `"mcpServers"` root key. Note that the Quick Start command above handles this automatically.
+  - **Claude Desktop** (H4) — JSON block with `"mcpServers"` root key. Show both macOS (`~/Library/Application Support/Claude/claude_desktop_config.json`) and Windows (`%APPDATA%\Claude\claude_desktop_config.json`) config file paths above the block. Add a `> [!NOTE]` callout about PATH: Claude Desktop does not inherit the terminal PATH, so nvm/Homebrew users must use `which npx` to find the absolute path and replace `"npx"` with it. Add a one-line note that Claude Desktop requires a full quit-and-reopen after config changes.
+  - **Cursor** (H4) — JSON block with `"mcpServers"` root key. Note config file path (`~/.cursor/mcp.json`).
+  - **VS Code / Copilot** (H4) — JSON block with `"servers"` root key (NOT `"mcpServers"`). Note config file path (`.vscode/mcp.json`).
+  - **Windsurf** (H4) — JSON block with `"mcpServers"` root key. Note config file path (`~/.windsurf/mcp.json`).
+
+  All JSON blocks show the same server entry structure: `"command": "npx"`, `"args": ["-y", "@aidemd-mcp/server@latest"]`.
+
+- [x] 1d. **Tools section with full parameter documentation.** H2 `## Tools`. One H3 per tool in lifecycle order: `aide_discover`, `aide_read`, `aide_scaffold`, `aide_validate`, `aide_init`, `aide_upgrade`. Each tool gets:
+  - Imperative one-sentence description (condensed from the tool `description` in `src/index.ts`)
+  - `**Inputs:**` bulleted list with backtick param name, (type), optional/required marker, and description
+  - Source all parameter details exactly from `inputSchema` in `src/index.ts` — do not invent parameters or omit any
+
+  Tool parameters to document (extracted from `src/index.ts`):
+  - `aide_discover`: `path` (string, optional) — subdirectory to drill into
+  - `aide_read`: `path` (string, required) — path to the .aide file
+  - `aide_scaffold`: `directory` (string, required), `type` (string, required — enum: intent, research, both, todo, plan)
+  - `aide_validate`: `path` (string, optional) — subdirectory to validate
+  - `aide_init`: `framework` (string, optional — enum: claude, cursor, windsurf, copilot), `path` (string, optional), `category` (string, optional — enum: framework, methodology, commands, agents, skills, mcp, brain, ide), `brainPath` (string, optional)
+  - `aide_upgrade`: `framework` (string, optional — enum: claude, cursor, windsurf, copilot), `path` (string, optional), `category` (string, optional — enum: pointer-stub, methodology-docs, version-metadata, commands, agents, skills, mcp, ide)
+
+- [x] 1e. **Getting Started (post-install) block.** H2 `## Getting Started`. Short block telling the developer to run `aide_init` after adding the server, then try a concrete action. Use the spec's good example as the baseline.
+
+- [x] 1f. **Development section.** H2 `## Development`. Three commands in a single code block: `npm install`, `npm run build`, `npm test`. Nothing else.
+
+- [x] 1g. **License line.** H2 `## License`. One line: `MIT` — linked to the LICENSE file using an absolute GitHub URL (`https://github.com/aidemd-mcp/server/blob/main/LICENSE`).
+
+**Rendering rules** (apply throughout all sections):
+- No `<details>`/`<summary>` tags anywhere
+- All cross-repo links use absolute GitHub URLs (base: `https://github.com/aidemd-mcp/server`)
+- `> [!NOTE]` callouts are acceptable (degrade to blockquotes on npm)
+- No relative links to files within the repo
 
 ## Decisions
 
-**plan sorts between research and todo in TYPE_ORDER.** Plan is the architect's
-artifact that follows research synthesis and precedes implementation + QA. This
-matches the pipeline ordering: research -> synthesize -> plan -> build -> qa.
-Todo is the QA output that comes last in the lifecycle.
-
-**The orchestrator /aide is a COMMANDS entry, not a separate mechanism.** The
-scaffoldCommands helper already handles idempotent command installation. The
-orchestrator is just another command file with a different hostPath (command
-directory root instead of aide/ subfolder). Adding it to the same COMMANDS array
-avoids a second installation path and keeps reporting consistent.
-
-**The orchestrator entry goes first in the COMMANDS array.** Pipeline reporting
-order should show the entry point before the phases it routes to. This matches
-the init spec's good-example output where `aide:` appears before `aide/research:`.
-
-**PLAN_TEMPLATE follows the plan.aide spec format, not the intent template format.**
-The plan.aide canonical spec defines frontmatter with `intent` only, plus
-`## Plan` and `## Decisions` body sections. The scaffold template mirrors this
-structure with empty placeholders, same as the TODO_TEMPLATE mirrors the todo
-format.
-
-**No changes to aide_validate or aide_read.** Both tools work off the
-AideFileType union and classifyFile, which are being updated in steps 1-2.
-They will automatically handle plan.aide files once the type system includes
-"plan". No tool-specific changes needed.
-
-**The "commands/aide/aide" canonical name uses `aide` as both namespace and
-basename.** This looks redundant but is mechanically correct: the canonical
-name prefix `commands/aide/` means "lives under .claude/commands/aide/" in
-the repo, and `aide` is the bare filename. The hostPath `aide.md` (without
-the `aide/` prefix) is what places it at the command directory root on the
-host side. The asymmetry between canonical path and host path is intentional
-— the canonical source lives inside the aide/ folder in the repo, but the
-host install places it as a peer of that folder.
+1. **Single step with lettered sub-steps.** The README is one file where every section depends on the overall structure, voice, and cross-references. Splitting into multiple agents would create inconsistency in tone, duplicate header work, or miss section flow. Lettered sub-steps let one agent write top-to-bottom while the plan still specifies each section's requirements independently.
+
+2. **No deep playbook dive for documentation.** The coding playbook governs code conventions, not prose documentation. The `foundations/conventions` note is included in the Read list for general naming/style awareness, but the spec itself (`readme.aide`) is the authoritative source for every README decision — section order, badge selection, config block format, tool documentation format, rendering constraints. The spec's strategy section is unusually detailed and research-backed; the plan defers to it entirely.
+
+3. **Parameters sourced from `src/index.ts`, not current README.** The current README has incomplete and outdated parameter lists (missing `plan` type in scaffold enum, missing `aide_upgrade` tool entirely, missing `category`/`brainPath` params on `aide_init`). The plan instructs the implementor to source all parameters from the `inputSchema` definitions in `src/index.ts` lines 46-167, which are the canonical source of truth.
+
+4. **VS Code uses `"servers"` root key.** Per the spec's research, VS Code/Copilot uses `"servers"` not `"mcpServers"`. This is the number one silent failure mode for cross-client config blocks. The plan calls this out explicitly.
+
+5. **`@latest` pinning in all config blocks.** Bare package names serve stale cached versions. Every config block uses `@aidemd-mcp/server@latest` with the `-y` flag to prevent npx from hanging in non-interactive contexts like Claude Desktop's process spawner.
+
+6. **PATH callout as `> [!NOTE]`, not `<details>`.** The spec requires the PATH troubleshooting to be visible on both GitHub and npm. GitHub `> [!NOTE]` renders as a styled callout and degrades to a plain blockquote on npm — both are readable. `<details>` would hide it on npm.
+
+7. **Quick-install command leads the Installation section.** `npx @aidemd-mcp/server init` is the recommended primary path because it eliminates three manual steps (MCP config, slash command, aide-tree) with a single idempotent command. It is scoped to Claude Code users — the primary audience per the spec's v1 scope note. The per-client manual config blocks move under a "Manual Configuration" H3 as the fallback for non-Claude-Code clients or users who prefer manual setup. This preserves all existing installation guidance while reducing time-to-value for the majority audience.
+
+8. **H3/H4 nesting for Installation.** Quick Start and Manual Configuration are H3s under the Installation H2. Individual clients under Manual Configuration are H4s. This keeps the Installation section scannable — a user on Claude Code sees the quick-start immediately and never needs to scroll past five client blocks. A user on Cursor jumps to Manual Configuration and finds their H4.

package/.aide/readme.aide

@@ -0,0 +1,338 @@
+---
+scope: README.md
+description: >
+  Spec for the @aidemd-mcp/server README — the primary conversion surface
+  on GitHub and npm that must turn visitors into installed users.
+intent: >
+  The README is the single document that serves both GitHub repository
+  visitors and npm package page visitors. Its job is to convert a developer
+  who has heard of AIDE or stumbled on the package into an active user who
+  has the MCP server running in their IDE within five minutes. It must
+  communicate what the server does, how to install it in every supported
+  client, and what tools it provides — in that order, with no friction
+  that sends the visitor elsewhere for answers. The README is not a
+  methodology tutorial or a marketing page; it is a self-contained
+  installation guide with enough context to justify the install.
+outcomes:
+  desired:
+    - A developer on any supported MCP client (Claude Code, Claude Desktop,
+      Cursor, VS Code / Copilot, Windsurf) finds a copy-pasteable config
+      block for their specific client, with the correct JSON root key, the
+      correct config file path, and @latest version pinning — no translation
+      from another client's example required.
+    - The tools section documents every tool with full parameter lists in
+      the canonical MCP README format (H3 per tool, imperative description,
+      bulleted Inputs with name/type/optional markers), so a developer
+      evaluating the server knows exactly what capabilities they get before
+      installing.
+    - A developer who has never heard of AIDE understands what the server
+      does and why it matters within the first two sentences — the title
+      line and description paragraph carry the pitch, not a separate
+      "What is AIDE?" explainer section.
+    - The README renders correctly on both GitHub and the npm package page,
+      avoiding constructs that break on npm (details/summary for critical
+      content, relative links, hover-only interactions).
+    - A post-install "what happens next" block gives the developer a
+      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
+      other clients to translate — the #1 documented friction source in
+      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
+      on what the MCP server does and how to install it. The methodology
+      docs are delivered by aide_init; the README's job is to get the user
+      to that point, not to replace it.
+    - Content hidden inside details/summary tags that renders on GitHub
+      but is invisible or broken on the npm package page.
+    - 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
+      mode for Claude Desktop, which is the single most common MCP install
+      failure and silently loses users who blame themselves and give up."
+---
+
+## Context
+
+The README serves two overlapping audiences arriving from two surfaces.
+GitHub visitors are evaluating whether to adopt the tool — they scan the
+repo, read the README top-to-bottom, and decide. npm visitors land on the
+package page after finding `@aidemd-mcp/server` in search results or a
+link — they see the README rendered by npm's markdown engine, which
+supports less than GitHub (no collapsible details for critical content, no
+relative links, degraded callout styling). Both audiences need the same
+core information: what the server does, how to install it in their specific
+client, and what tools it provides. Neither audience wants a methodology
+tutorial — that is what `aide_init` delivers after the install.
+
+The MCP ecosystem has a specific install friction profile. Each client
+stores its config in a different file at a different path, and VS Code
+uses a different JSON root key (`"servers"`) than every other client
+(`"mcpServers"`). Users who copy a config block for the wrong client get
+a silent failure. Claude Desktop has an additional failure mode: it does
+not inherit the terminal's PATH, so users with nvm or Homebrew Node
+installations get "command not found" errors that are never explained in
+most MCP server READMEs. These are the documented friction points the
+README must address head-on.
+
+The server currently ships six tools (`aide_discover`, `aide_read`,
+`aide_scaffold`, `aide_validate`, `aide_init`, `aide_upgrade`) plus a
+`plan.aide` file type. With six tools, full parameter documentation is
+feasible and preferred over a summary list — the tool count is small
+enough that every parameter can be documented without the README becoming
+unwieldy. This is the recommendation from the tool documentation research
+for servers with ten or fewer tools.
+
+## Strategy
+
+**Lead with a one-line description that names the value, not the
+mechanism.** The H1 title is the package name; the line immediately below
+it says what the server does for the developer, not how it works
+internally. The current README opens with "MCP server that teaches any
+agent the AIDE methodology" — this is close but should be tightened to
+name the outcome (intent-driven specs next to code) rather than the
+mechanism (teaching). The description must work as the npm package
+subtitle, which is the only text a developer sees in search results
+before clicking through (npm badge research).
+
+**Badges signal legitimacy and version currency.** Place npm version and
+MIT license badges immediately below the H1, before the description. Add
+npm weekly downloads once the package has meaningful traction. Skip CI/build
+badges — no MCP server README in the research corpus uses them, and the
+audience does not expect them. A Smithery registry badge is worth adding
+once the package is listed there, as it is a recognized quality signal in
+the MCP ecosystem (mcp-readme-npm-badges research).
+
+**Use a brief features bullet list, not a "What is AIDE?" section.** The
+current README has a "What is AIDE?" section with a file-type table that
+front-loads methodology detail before the install instructions. This
+violates the canonical MCP README section order, which puts features
+(brief) before installation (detailed). Replace the explainer with a
+three-to-five-bullet feature list that names capabilities from the user's
+perspective: project-wide spec discovery, one-command bootstrap, naming
+convention enforcement, health-check validation, upgrade drift detection.
+The file-type table belongs in the methodology docs that `aide_init`
+installs, not in the README (mcp-readme-conventions research, section
+order finding).
+
+**Show a separate config block per client, not one block with a
+footnote.** Use Pattern A from the conventions research: one H3 per
+client under the Installation H2, each with its own copy-pasteable JSON
+block showing the correct root key, the correct config file path, and
+`@latest` version pinning. The clients to cover are Claude Code (CLI
+command and .mcp.json), Claude Desktop (Mac and Windows paths), Cursor,
+VS Code / Copilot (noting the `"servers"` root key difference), and
+Windsurf. This is the largest section of the README and the most visited
+— every character must be copy-pasteable without modification
+(mcp-readme-config-blocks research, multi-client presentation finding).
+
+**Pin to `@latest` in all config blocks.** Use `npx -y
+@aidemd-mcp/server@latest` rather than a bare package name. The bare name
+uses a locally cached version if one exists; `@latest` forces a fresh
+resolution. This is the convention in community MCP servers and
+communicates intent explicitly. Users who want reproducibility can pin in
+their own config (mcp-readme-config-blocks research, version pinning
+finding).
+
+**Include the `-y` flag in npx args.** All official MCP server READMEs
+use `npx -y` to auto-confirm the package install prompt. Omitting `-y`
+causes npx to hang waiting for confirmation in non-interactive contexts
+like Claude Desktop's process spawner, which is a silent install failure
+(mcp-readme-conventions research).
+
+**Add a PATH troubleshooting callout in the Claude Desktop section.**
+Claude Desktop does not inherit the terminal PATH — users with
+nvm/Homebrew Node hit "command not found: npx" and silently churn. A
+blockquote callout (which degrades to a plain blockquote on npm — acceptable)
+naming the problem and the fix (use `which npx` to find the absolute path)
+addresses the single most common MCP install failure
+(mcp-readme-config-blocks research, PATH problem finding; install-cta-mechanics
+research, friction map finding).
+
+**Note the Claude Desktop restart requirement.** Claude Desktop requires
+a full quit-and-reopen for config changes to take effect. This is the #2
+documented failure mode. A one-line note in the Claude Desktop section
+prevents it (mcp-readme-config-blocks research, reload requirement finding).
+
+**Document every tool with full parameters in the canonical format.** Use
+H3 per tool inside a Tools H2. Each tool gets an imperative one-sentence
+description and an Inputs bullet list with backtick name, (type, optional)
+markers, and a description. Six tools is well within the feasibility
+threshold for full documentation. Group by lifecycle phase if it helps
+scanning: discover and read (navigation), scaffold and validate
+(authoring), init and upgrade (project setup). Include the `plan.aide`
+file type in the tool documentation for `aide_scaffold` since it was added
+after the current README was written (mcp-readme-tool-documentation
+research, canonical format finding).
+
+**Add a post-install "try it" block.** After the Tools section, include a
+short block that tells the developer what to do after installing: "Run
+`aide_init` in your agent to bootstrap the AIDE methodology into your
+project, then try `/aide` to start the pipeline." This closes the
+install-to-value gap that silently loses users in dev-tool landings
+(install-cta-mechanics research, post-install hand-off finding).
+
+**Keep the Development section minimal.** Three commands (install, build,
+test) in a code block. No contributing guide, no changelog — those belong
+in separate files if needed. The README is for users, not contributors
+(mcp-readme-conventions research, building section finding).
+
+**Use absolute URLs for any cross-repo links.** Relative links work on
+GitHub but break on the npm package page. Any link to files within the
+repo (LICENSE, methodology docs) must use the full GitHub URL
+(mcp-readme-npm-badges research, npm rendering finding).
+
+**Avoid details/summary tags for any content a visitor needs to see.**
+They are broken on npm. Use flat sections instead. The `> [!NOTE]`
+callout syntax is acceptable — it renders as a styled callout on GitHub
+and degrades to a readable blockquote on npm (mcp-readme-npm-badges
+research, npm rendering finding).
+
+## Good examples
+
+A strong opening that names the value:
+
+> # @aidemd-mcp/server
+>
+> [![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)
+>
+> 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.
+
+A per-client config block that eliminates translation friction:
+
+> ### 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"]
+>     }
+>   }
+> }
+> ```
+>
+> ### VS Code / Copilot
+>
+> Add to `.vscode/mcp.json`:
+>
+> ```json
+> {
+>   "servers": {
+>     "aide": {
+>       "command": "npx",
+>       "args": ["-y", "@aidemd-mcp/server@latest"]
+>     }
+>   }
+> }
+> ```
+
+A tool documented in the canonical format:
+
+> ### 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,
+>   opens with the ancestor chain — the cascading intent lineage from root
+>   to target — followed by the detailed subtree. When omitted, returns a
+>   project-wide map.
+
+A post-install block that bridges install to first value:
+
+> ## Getting Started
+>
+> 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.
+
+## Bad examples
+
+A README that opens with a methodology explainer before the install block:
+
+> ## What is AIDE?
+>
+> AIDE (Autonomous Intent-Driven Engineering) is a methodology that puts
+> intent at the center of everything. It uses a three-layer model...
+> [300 words of methodology detail]
+>
+> ## Installation
+> ...
+
+The visitor wanted to install, not to study. The methodology detail
+belongs in the docs that `aide_init` delivers, not in the README that
+must convince the visitor to install. By the time they reach the config
+block, they have either scrolled past or left.
+
+A single config block labeled "Add to your MCP client config" with the
+`mcpServers` root key and no per-client guidance:
+
+> ```json
+> {
+>   "mcpServers": {
+>     "aide": {
+>       "command": "npx",
+>       "args": ["@aidemd-mcp/server"]
+>     }
+>   }
+> }
+> ```
+
+A VS Code user pastes this into `.vscode/mcp.json`, where the root key
+should be `"servers"`, not `"mcpServers"`. The server silently fails to
+load. The user assumes the package is broken and moves on. Meanwhile, the
+`-y` flag is missing, so Claude Desktop users get a hung npx prompt they
+never see. Two silent failures from one config block.
+
+A tool list without parameters:
+
+> - **aide_discover** — Scans for .aide files
+> - **aide_scaffold** — Creates new .aide files
+> - **aide_validate** — Validates .aide files
+
+The developer evaluating this server cannot tell what inputs each tool
+accepts, whether paths are required or optional, or what the `type`
+enum values are for scaffold. They must install the server and call the
+tools to find out. A developer comparing this against another MCP server
+that documents its parameters fully will choose the documented one.
+
+A README that uses `<details>` tags to collapse the per-client config
+blocks:
+
+> <details>
+> <summary>Claude Desktop</summary>
+> [config block]
+> </details>
+
+On the npm package page, the details/summary tags are broken — the
+content is either always expanded or invisible depending on npm's
+renderer version. The most-visited section of the README is now
+inaccessible on one of the two primary surfaces the README serves.
+
+## References
+
+- `research/mcp-readme/mcp-readme-conventions` -- Canonical section order (title, badges, features, install, tools, dev, license) and the Pattern A multi-client presentation finding that drives the per-client config block strategy.
+- `research/mcp-readme/mcp-readme-config-blocks` -- The `mcpServers` vs `"servers"` root key difference, `@latest` version pinning recommendation, PATH troubleshooting requirement for Claude Desktop, and the restart-after-config-change requirement.
+- `research/mcp-readme/mcp-readme-tool-documentation` -- The canonical tool documentation format (H3 per tool, imperative description, bulleted Inputs), the full-documentation recommendation for servers with fewer than 10 tools, and the tool annotations pattern.
+- `research/mcp-readme/mcp-readme-npm-badges` -- Badge placement convention (below H1, before description), recommended badge stack (version + license minimum), npm rendering constraints (no details/summary, absolute URLs required, callout degradation acceptable).
+- `research/aidemd-dev/install-cta-mechanics` -- The MCP install friction map (config location confusion, reload requirement, PATH inheritance failure, cross-client ambiguity), the post-install "try it" block pattern from Stripe/shadcn precedent, and the v1 scope note confirming Claude Code as primary target.