@henryavila/mdprobe 0.1.0 → 0.2.0

package/README.md

@@ -1,152 +1,160 @@
-![mdprobe](header.png)
+![mdProbe](header.png)
 
-# mdprobe
+# mdProbe
 
-**The missing link between AI coding agents and human review.**
+Markdown viewer and reviewer with live reload, persistent annotations, and AI agent integration.
 
-AI agents generate specs, docs, and RFCs — but you need to actually *read* them, *annotate* them, and *send structured feedback back*. mdprobe closes that loop: it renders markdown in the browser, lets you annotate inline, and returns structured YAML that agents can parse and act on.
-
-It works standalone too — as a markdown viewer with live reload and persistent annotations for any review workflow.
-
-[Install](#install) | [Quick Start](#quick-start) | [Features](#features) | [CLI Reference](#cli-reference) | [Library API](#library-api) | [Schema](#annotation-schema) | [AI Integration](#ai-agent-integration)
+Open `.md` files in the browser, annotate inline, approve sections, and export structured feedback as YAML — all from the terminal.
 
 ---
 
-## What is mdprobe?
+## What mdProbe is
 
-A CLI tool that turns markdown files into a review environment in your browser.
+- A **CLI tool** that renders markdown in the browser with live reload
+- An **annotation system** where you select text and add tagged comments (bug, question, suggestion, nitpick)
+- A **review workflow** with section-level approval (approve/reject per heading)
+- An **MCP server** that lets AI agents (Claude Code, Cursor, etc.) open files, read annotations, and resolve feedback programmatically
 
-```
-AI Agent writes spec.md ──> mdprobe spec.md --once ──> Human reviews & annotates ──> spec.annotations.yaml ──> Agent reads feedback
-```
+## What mdProbe is not
 
-### The problem
+- Not a markdown editor — you edit in your own editor, mdprobe renders and annotates
+- Not a static site generator — it runs a local server for live preview
+- Not exclusive to AI — works perfectly as a standalone review tool
 
-AI agents produce markdown output (specs, architecture docs, RFCs) but have no way to get **structured, line-level feedback** from humans. You either paste comments back into chat (losing context) or approve blindly.
+---
 
-### The solution
+## Install
 
-mdprobe renders your markdown with full GFM, syntax highlighting, Mermaid diagrams and math, then lets you select text and add annotations — `bug`, `question`, `suggestion`, `nitpick` — that are saved as a YAML sidecar. In `--once` mode, the agent's process blocks until you finish reviewing, then reads the annotations programmatically.
+```bash
+npm install -g @henryavila/mdprobe
+mdprobe setup
+```
 
-It also works as a standalone tool for any markdown review workflow — no AI required.
+The setup wizard configures your author name, installs the AI skill to detected IDEs (Claude Code, Cursor, Gemini), registers the MCP server, and adds a PostToolUse hook.
 
-### Three workflows
+For non-interactive environments: `mdprobe setup --yes --author "Your Name"`
 
-| Workflow | Command | Use case |
-|----------|---------|----------|
-| **View** | `mdprobe spec.md` | Render complex markdown in the browser with live reload |
-| **Review** | `mdprobe spec.md --once` | Agent blocks until human finishes annotating, then reads feedback |
-| **Embed** | `import { createHandler }` | Mount mdprobe inside your own Node.js server or tool |
+Or run without installing:
+
+```bash
+npx @henryavila/mdprobe README.md
+```
 
-Annotations are stored as plain YAML — readable by humans, parseable by machines, and version-controllable with git.
+**Requirements:** Node.js 20+, a browser.
 
 ---
 
-## Install
+## Quick Start
+
+### View and edit
 
 ```bash
-npm install -g @henryavila/mdprobe
+mdprobe README.md
 ```
 
-Or use directly with npx:
+Opens rendered markdown in the browser. Edit the source file — the browser updates instantly via WebSocket.
 
 ```bash
-npx @henryavila/mdprobe spec.md
+mdprobe docs/
 ```
 
-### Requirements
+Discovers all `.md` files recursively and shows a file picker.
+
+### Annotate
+
+Select any text in the browser → choose a tag → write a comment → save.
+
+| Tag | Meaning |
+|-----|---------|
+| `bug` | Something is wrong |
+| `question` | Needs clarification |
+| `suggestion` | Improvement idea |
+| `nitpick` | Minor style/wording |
 
-- Node.js 20+
-- A browser (auto-opens on macOS, Linux, and WSL)
+Annotations are stored in `.annotations.yaml` sidecar files — human-readable, git-friendly.
 
 ---
 
-## Quick Start
+## Singleton Server
 
-### View a file
+mdProbe runs a **single server instance**. Multiple invocations share the same server instead of starting duplicates:
 
 ```bash
-mdprobe README.md
+mdprobe README.md          # Starts server on port 3000, opens browser
+mdprobe CHANGELOG.md       # Detects running server, adds file, opens browser, exits
 ```
 
-Opens the rendered markdown in your browser. Edit the file in your editor — the browser updates instantly.
+The second invocation adds its files to the existing server and exits immediately. The browser shows all files in the sidebar.
 
-### View a directory
+**How it works:** A lock file at `/tmp/mdprobe.lock` records the running server's PID, port, and URL. New invocations read the lock file, verify the server is alive via HTTP health check, and join via `POST /api/add-files`. On shutdown (`Ctrl+C`), the lock file is removed automatically.
 
-```bash
-mdprobe docs/
-```
+**Stale lock recovery:** If a previous instance crashed, the next invocation detects the dead process and starts fresh.
 
-Discovers all `.md` files recursively and shows a file picker.
+---
+
+## Two Review Workflows
+
+mdProbe supports two distinct review workflows for different contexts:
 
-### Review mode (blocking)
+### 1. Blocking review (`--once`) — for CI/CD and scripts
 
 ```bash
 mdprobe spec.md --once
 ```
 
-The process **blocks** until you click "Finish Review" in the UI. Annotations are saved to `spec.annotations.yaml`. Useful for AI agents that need human feedback before continuing.
+Blocks the process until you click **"Finish Review"** in the UI. When you finish, annotations are saved to `spec.annotations.yaml` and the process exits with the list of created files. This is useful for pipelines that need human sign-off before continuing.
 
-### Configure your name
+`--once` mode always creates an **isolated server instance** — it does not participate in the singleton. This ensures review sessions have independent lifecycle.
 
-```bash
-mdprobe config author "Your Name"
+### 2. AI-assisted review (MCP) — for AI coding agents
+
+When working with AI agents (Claude Code, Cursor, etc.), the workflow is different. The agent does **not** use `--once`. Instead:
+
+```
+Agent writes spec.md
+    ↓
+Agent calls mdprobe_view → browser opens, server stays running
+    ↓
+Human reads, annotates, approves/rejects sections
+    ↓
+Human tells agent via chat: "done reviewing"
+    ↓
+Agent calls mdprobe_annotations → reads all feedback
+    ↓
+Agent fixes bugs, answers questions, evaluates suggestions
+    ↓
+Agent reports changes, asks human to confirm
+    ↓
+Agent calls mdprobe_update → resolves annotations
+    ↓
+Human sees resolved items in real-time (greyed out)
 ```
 
-Your name is attached to every annotation and reply. On first use, mdprobe will prompt you interactively.
+The server stays running across the entire conversation. The agent reads annotations on demand — no blocking, no process exit. Multiple files can be reviewed in the same session via the singleton server.
 
 ---
 
 ## Features
 
-### Markdown Rendering
+### Rendering
 
-- **GFM** — tables, task lists, strikethrough, autolinks
-- **Syntax highlighting** — all languages via highlight.js
-- **Mermaid diagrams** — rendered client-side
-- **Math/LaTeX** — via KaTeX (inline and display)
-- **Frontmatter** — YAML and TOML (parsed and stripped from output)
-- **Raw HTML** — passthrough with allowlist
-- **Images** — served from the markdown file's directory
+GFM tables, syntax highlighting (highlight.js), Mermaid diagrams, math/LaTeX (KaTeX), YAML/TOML frontmatter, raw HTML passthrough, images from source directory.
 
 ### Live Reload
 
-File changes are detected via chokidar and pushed to the browser over WebSocket. Debounced at 100ms to avoid flicker during rapid saves. Scroll position is preserved across reloads.
-
-### Annotations
-
-Select any text in the rendered markdown to open the annotation popover:
-
-- **4 tags**: `bug`, `question`, `suggestion`, `nitpick` — color-coded pills
-- **Threaded replies** — discuss annotations inline
-- **Resolve/reopen** — mark items as handled
-- **Persistent** — saved to `.annotations.yaml` sidecar (YAML format, git-friendly)
-- **Draggable popover** — move the form to read the content underneath
-- **Keyboard shortcuts** — `Ctrl+Enter` to save, `Esc` to close
+File changes detected via chokidar, pushed over WebSocket. Debounced at 100ms. Scroll position preserved.
 
 ### Section Approval
 
-Every heading in your document gets approve/reject buttons:
-
-- **Symmetric cascade** — approving a parent approves all children; rejecting or resetting does the same
-- **Indeterminate state** — when children have mixed statuses, the parent shows a visual indicator
-- **Approve All / Clear All** — bulk operations for the entire document
+Every heading gets approve/reject buttons. Approving a parent cascades to all children. Progress bar tracks reviewed vs total sections.
 
 ### Drift Detection
 
-When the source markdown changes after annotations were created, mdprobe shows a warning banner. This prevents stale annotations from going unnoticed.
+Warning banner when the source file changes after annotations were created.
 
 ### Themes
 
-Five built-in themes based on the Catppuccin palette:
-
-| Theme | Style |
-|-------|-------|
-| **Mocha** | Dark (default) |
-| **Macchiato** | Dark, warm |
-| **Frappe** | Dark, deep blue |
-| **Latte** | Light |
-| **Light** | Pure white |
+Five themes based on Catppuccin: Mocha (dark, default), Macchiato, Frappe, Latte, Light.
 
 ### Keyboard Shortcuts
 
@@ -154,24 +162,61 @@ Five built-in themes based on the Catppuccin palette:
 |-----|--------|
 | `[` | Toggle left panel (files + TOC) |
 | `]` | Toggle right panel (annotations) |
-| `\` | Toggle both panels (focus mode) |
+| `\` | Focus mode (hide both panels) |
 | `j` / `k` | Next / previous annotation |
-| `?` | Show help overlay |
+| `?` | Help overlay |
 | `Ctrl+Enter` | Save annotation |
-| `Esc` | Close popover / modal |
 
 ### Export
 
-Export annotations in four formats:
-
 ```bash
 mdprobe export spec.md --report   # Markdown review report
-mdprobe export spec.md --inline   # HTML comments inserted into source
+mdprobe export spec.md --inline   # Annotations inserted into source
 mdprobe export spec.md --json     # Plain JSON
-mdprobe export spec.md --sarif    # SARIF 2.1.0 (for CI/CD integration)
+mdprobe export spec.md --sarif    # SARIF 2.1.0 (CI/CD integration)
+```
+
+---
+
+## AI Agent Integration
+
+mdProbe includes an MCP (Model Context Protocol) server and a skill file (`SKILL.md`) that teaches AI agents how to use the review workflow. This enables a two-way loop: the agent writes markdown, the human annotates, the agent reads feedback and resolves it.
+
+### Setup
+
+```bash
+mdprobe setup
 ```
 
-Also available via the HTTP API: `GET /api/export?path=spec.md&format=json`
+Interactive wizard that:
+1. Installs the `SKILL.md` to detected IDEs (Claude Code, Cursor, Gemini)
+2. Registers the MCP server (`mdprobe mcp`) in your Claude Code config
+3. Adds a PostToolUse hook that reminds the agent to use mdprobe when editing `.md` files
+4. Configures your author name
+
+Non-interactive: `mdprobe setup --yes --author "Your Name"`
+Remove everything: `mdprobe setup --remove`
+
+### MCP Tools
+
+Once set up, AI agents can call these tools:
+
+| Tool | Purpose |
+|------|---------|
+| `mdprobe_view` | Open `.md` files in the browser |
+| `mdprobe_annotations` | Read annotations and section statuses |
+| `mdprobe_update` | Resolve, reply, add, or delete annotations |
+| `mdprobe_status` | Check if the server is running |
+
+The MCP server participates in the singleton — if a CLI-started server is already running, the agent reuses it.
+
+### Manual MCP Registration
+
+If you prefer not to use `mdprobe setup`:
+
+```bash
+claude mcp add --scope user --transport stdio mdprobe -- mdprobe mcp
+```
 
 ---
 
@@ -182,27 +227,20 @@ mdprobe [files...] [options]
 
 Options:
   --port <n>      Port number (default: 3000, auto-increments if busy)
-  --once          Review mode — blocks until human finishes
+  --once          Blocking review — isolated server, exits on "Finish Review"
   --no-open       Don't auto-open browser
   --help, -h      Show help
   --version, -v   Show version
 
 Subcommands:
-  config [key] [value]           Manage configuration
-  export <path> [format-flag]    Export annotations
-  install --plugin               Install Claude Code skill
+  setup                  Interactive setup (skill + MCP + hook)
+  setup --remove         Uninstall everything
+  setup --yes [--author] Non-interactive setup
+  mcp                    Start MCP server (stdio, for AI agents)
+  config [key] [value]   Manage configuration
+  export <path> [flags]  Export annotations (--report, --inline, --json, --sarif)
 ```
 
-### Config
-
-```bash
-mdprobe config                  # Show all configuration
-mdprobe config author           # Show current author
-mdprobe config author "Name"    # Set author
-```
-
-Configuration is stored in `~/.mdprobe.json`.
-
 ---
 
 ## Library API
@@ -216,7 +254,6 @@ const handler = createHandler({
   resolveFile: (req) => '/path/to/file.md',
   listFiles: () => [
     { id: 'spec', path: '/docs/spec.md', label: 'Specification' },
-    { id: 'adr', path: '/docs/adr.md', label: 'Architecture Decision' },
   ],
   basePath: '/review',
   author: 'Review Bot',
@@ -234,13 +271,11 @@ http.createServer(handler).listen(3000)
 ```javascript
 import { AnnotationFile } from '@henryavila/mdprobe/annotations'
 
-// Load existing annotations
 const af = await AnnotationFile.load('spec.annotations.yaml')
 
 // Query
 const open = af.getOpen()
 const bugs = af.getByTag('bug')
-const mine = af.getByAuthor('Henry')
 
 // Mutate
 af.add({
@@ -253,13 +288,10 @@ af.add({
   author: 'Henry',
 })
 af.resolve(bugs[0].id)
-
-// Persist
 await af.save('spec.annotations.yaml')
 
 // Export
 import { exportJSON, exportSARIF } from '@henryavila/mdprobe/export'
-const json = exportJSON(af)
 const sarif = exportSARIF(af, 'spec.md')
 ```
 
@@ -267,7 +299,7 @@ const sarif = exportSARIF(af, 'spec.md')
 
 ## Annotation Schema
 
-Annotations are stored in YAML sidecar files (`<filename>.annotations.yaml`):
+Sidecar file format (`<filename>.annotations.yaml`):
 
 ```yaml
 version: 1
@@ -277,91 +309,42 @@ sections:
   - heading: Introduction
     level: 2
     status: approved
-  - heading: Requirements
-    level: 2
-    status: pending
 annotations:
   - id: "a1b2c3d4"
     selectors:
-      position:
-        startLine: 15
-        startColumn: 1
-        endLine: 15
-        endColumn: 42
-      quote:
-        exact: "The system shall support concurrent users"
-        prefix: ""
-        suffix: ""
-    comment: "How many concurrent users? Need a number."
+      position: { startLine: 15, startColumn: 1, endLine: 15, endColumn: 42 }
+      quote: { exact: "The system shall support concurrent users" }
+    comment: "How many concurrent users?"
     tag: question
     status: open
     author: Henry
     created_at: "2026-04-08T10:30:00.000Z"
-    updated_at: "2026-04-08T10:30:00.000Z"
     replies:
-      - author: Alice
+      - author: Agent
         comment: "Target is 500 concurrent."
         created_at: "2026-04-08T11:00:00.000Z"
 ```
 
-A JSON Schema is available at `@henryavila/mdprobe/schema.json` for validation.
-
-### Tags
-
-| Tag | Meaning | SARIF Severity |
-|-----|---------|----------------|
-| `bug` | Something is wrong | error |
-| `question` | Needs clarification | note |
-| `suggestion` | Improvement idea | warning |
-| `nitpick` | Minor style/wording | note |
-
----
-
-## AI Agent Integration
-
-mdprobe ships with a Claude Code skill that teaches the AI when and how to use it.
-
-### Install the skill
-
-```bash
-mdprobe install --plugin
-```
-
-### Agent workflow
-
-1. Agent writes a spec/document to a `.md` file
-2. Agent launches `mdprobe spec.md --once` (blocks)
-3. Human reviews in the browser, adds annotations
-4. Human clicks "Finish Review"
-5. Agent reads `spec.annotations.yaml` and addresses each annotation
-
-```javascript
-// Agent reads feedback after review
-import { AnnotationFile } from '@henryavila/mdprobe/annotations'
-
-const af = await AnnotationFile.load('spec.annotations.yaml')
-for (const ann of af.getOpen()) {
-  console.log(`[${ann.tag}] Line ${ann.selectors.position.startLine}: ${ann.comment}`)
-}
-```
+JSON Schema available at `@henryavila/mdprobe/schema.json`.
 
 ---
 
 ## HTTP API
 
-All endpoints are available when the server is running.
+Available when the server is running:
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `GET` | `/api/files` | List markdown files |
-| `GET` | `/api/file?path=<file>` | Get rendered HTML + TOC + frontmatter |
-| `GET` | `/api/annotations?path=<file>` | Get annotations + sections + drift status |
+| `GET` | `/api/file?path=<file>` | Rendered HTML + TOC + frontmatter |
+| `GET` | `/api/annotations?path=<file>` | Annotations + sections + drift status |
 | `POST` | `/api/annotations` | Create/update/delete annotations |
 | `POST` | `/api/sections` | Approve/reject/reset sections |
 | `GET` | `/api/export?path=<file>&format=<fmt>` | Export (json, report, inline, sarif) |
-| `GET` | `/api/config` | Get current author |
+| `GET` | `/api/status` | Server identity, PID, port, file list |
+| `POST` | `/api/add-files` | Add files to a running server (singleton join) |
 
-WebSocket at `/ws` provides real-time file change notifications.
+WebSocket at `/ws` for real-time updates.
 
 ---
 
@@ -371,30 +354,35 @@ WebSocket at `/ws` provides real-time file change notifications.
 git clone https://github.com/henryavila/mdprobe.git
 cd mdprobe
 npm install
-npm run build:ui    # Build the Preact UI
-npm test            # Run test suite (489 tests)
+npm run build:ui
+npm test
 ```
 
-### Project structure
+### Project Structure
 
 ```
 bin/cli.js              CLI entry point
 src/
   server.js             HTTP + WebSocket server
-  renderer.js           Markdown rendering pipeline (remark/rehype)
-  annotations.js        Annotation CRUD + section approval + cascade
-  export.js             4 export formats (report, inline, JSON, SARIF)
+  singleton.js          Lock file + cross-process singleton coordination
+  mcp.js                MCP server (4 tools, stdio transport)
+  renderer.js           Markdown → HTML (unified/remark/rehype)
+  annotations.js        Annotation CRUD + section approval
+  export.js             Export: report, inline, JSON, SARIF
+  setup.js              IDE skill + MCP + hook registration
+  setup-ui.js           Interactive setup wizard
   handler.js            Library API for embedding
-  config.js             User configuration (~/.mdprobe.json)
+  config.js             User config (~/.mdprobe.json)
+  open-browser.js       Cross-platform browser launcher
   hash.js               SHA-256 drift detection
-  anchoring.js          Text position matching for highlights
+  anchoring.js          Text position matching
   ui/
-    components/         Preact components (App, Content, Popover, Panels...)
-    hooks/              Custom hooks (WebSocket, keyboard, theme, annotations)
-    state/store.js      Preact Signals state management
-    styles/themes.css   Catppuccin theme system
-schema.json             JSON Schema for annotation YAML
-skills/                 Claude Code integration skill
+    components/         Preact components
+    hooks/              WebSocket, keyboard, theme, annotations
+    state/store.js      Preact Signals state
+    styles/themes.css   Catppuccin themes
+schema.json             Annotation YAML schema
+skills/mdprobe/         AI agent skill (SKILL.md)
 ```
 
 ---