@sudosandwich/limps 2.5.0 → 2.6.1

package/README.md

@@ -1,296 +1,174 @@
 # limps
 
-**L**ocal **I**ntelligent **M**CP **P**lanning **S**erver - limps your Local Intelligent MCP Planning Server across AI assistants. No subscriptions, no cloud—run it locally. Version control your planning docs in git. No more context drift—one shared source of truth for planning docs, tasks, and decisions across Claude Desktop, Cursor, GitHub Copilot, and any MCP tool.
+**L**ocal **I**ntelligent **M**CP **P**lanning **S**erver — A document and planning layer for AI assistants. No subscriptions, no cloud. Point limps at **any folder** (local, synced, or in git). One shared source of truth across Claude, Cursor, Codex, and any MCP-compatible tool.
 
 [![npm](https://img.shields.io/npm/v/@sudosandwich/limps)](https://www.npmjs.com/package/@sudosandwich/limps)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-![Tests](https://img.shields.io/badge/Tests-817%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/Tests-899%20passing-brightgreen)
 ![Coverage](https://img.shields.io/badge/Coverage-%3E70%25-brightgreen)
 
-![limps in action](https://github.com/paulbreuler/limps/blob/main/.github/assets/limps-in-action.gif?raw=true)
+![limps in action](https://github.com/paulbreuler/limps/blob/main/.github/assets/limps-a-lol-longer.gif?raw=true)
 
-*Claude Desktop accessing the planning MCP, talking to Runi project docs*
+## Quick Start
 
-## The Problem limps Solves
+```bash
+# Install globally
+npm install -g @sudosandwich/limps
 
-**Context drift between LLM providers** — Each AI assistant (Claude, ChatGPT, Cursor, GitHub Copilot, etc.) maintains its own separate context. Without a shared source of truth, planning documents, task status, and decisions get fragmented across different conversations and sessions.
+# Initialize a project
+limps init my-project --docs-path ~/Documents/my-planning-docs
 
-limps solves this by providing a **standardized MCP interface** that any MCP-compatible tool can access. Your planning documents, tasks, and decisions live in one place, accessible to:
+# Add to your AI assistant (picks up all registered projects)
+limps config sync-mcp --client cursor
+limps config sync-mcp --client claude-code
+```
 
-- **Claude Desktop** — Full access to search, read, update, create documents, and more
-- **Cursor** — Integrated planning and task management via MCP tools
-- **GitHub Copilot** — When MCP support is enabled
-- **Any MCP-compatible tool** — Standard protocol means universal access
+Run this in the folder where you want to keep the docs and that's it. Your AI assistant now has access to your documents and nothing else. The folder can be anywhere—local, synced, or in a repo; limps does not require a git repository or a `plans/` directory.
 
-### Deployment Options
+### What to know before you start
 
-- **Local (Default)** — Run limps locally for secure, private access
-- **Deployed** — You can deploy the MCP server for global access, but **research AUTH** to protect your endpoint and documents
+- **Local only** — Your data stays on disk (SQLite index + your files). No cloud, no subscription.
+- **Restart after changes** — If you change the indexed folder or config, restart the MCP server (or rely on the file watcher) so the index and tools reflect the current state.
+- **Sandboxed user code** — `process_doc` and `process_docs` run your JavaScript in a QuickJS sandbox with time and memory limits; no network or Node APIs.
+- **One optional network call** — `limps version --check` fetches from the npm registry to compare versions. All other commands (serve, init, list, search, create/update/delete docs, process_doc, etc.) do **not** contact the internet. Omit `version --check` if you want zero external calls.
 
-## Used In Production
+## How I Use limps
 
-limps is actively used to build [runi](https://github.com/paulbreuler/runi) - managing planning documents and task tracking across the development lifecycle.
+I use `limps` as a local planning layer across multiple AI tools, focused on **create → read → update → closure** for plans and tasks. The MCP server points at whatever directory I want (not necessarily a git repo), so any client reads and updates the same source of truth.
 
-### How runi Uses limps
+Typical flow:
 
-The [runi](https://github.com/paulbreuler/runi) project uses a separate git repository ([runi-planning-docs](https://github.com/paulbreuler/runi-planning-docs)) for version-controlled planning documents. Custom Cursor commands in `.cursor/commands/` integrate with limps tools:
+1. Point limps at a docs directory (any folder, local or synced).
+2. Use CLI + MCP tools to create plans/docs, read the current status, update tasks, and close work when done.
+3. Sync MCP configs so Cursor/Claude/Codex all see the same plans.
 
-**Core Commands:**
+Commands and tools I use most often:
 
-| Command | Description | MCP Tools Used |
-|---------|-------------|----------------|
-| `/create-feature-plan` | Generate TDD plan with docs and agent files | `create_plan`, `create_doc`, `list_docs` |
-| `/list-feature-plans` | List all plans with clickable file paths | `list_docs`, `process_doc` |
-| `/run-agent` | Start work on next agent task | `process_doc`, `update_task_status` |
-| `/close-feature-agent` | Verify completion, sync status | `process_doc`, `update_doc`, `update_task_status` |
-| `/update-feature-plan` | Regenerate agents from updated plan | `process_doc`, `create_doc`, `process_docs` |
-| `/plan-list-agents` | Show all agents with status | `list_docs`, `process_docs` |
+- **Create**: `limps init`, `create_plan`, `create_doc`
+- **Read**: `list_plans`, `list_agents`, `list_docs`, `search_docs`, `get_plan_status`
+- **Update**: `update_doc`, `update_task_status`, `manage_tags`
+- **Close**: `update_task_status` (e.g., `PASS`), `delete_doc` if needed
 
-**Example: `/create-feature-plan` using MCP tools:**
+Full lists are below in "CLI Commands" and "MCP Tools."
 
-```typescript
-// 1. Find next plan number
-const plans = await list_docs({ path: 'plans/', pattern: '*' });
-const nextNum = Math.max(...plans.map(p => parseInt(p.name))) + 1;
+## How You Can Use It
 
-// 2. Create plan structure
-await create_plan({ name: `${nextNum}-my-feature`, description: '...' });
+`limps` is designed to be generic and portable. Point it at **any folder** with Markdown files and use it from any MCP-compatible client. **No git repo required.** **Not limited to planning**—planning (plans, agents, task status) is one use case; the same layer gives you document CRUD, full-text search, and programmable processing on any indexed folder.
 
-// 3. Create planning documents
-await create_doc({ path: `plans/${nextNum}-my-feature/plan.md`, content: '...' });
-await create_doc({ path: `plans/${nextNum}-my-feature/interfaces.md`, content: '...' });
-```
+Common setups:
 
-**Example: `/run-agent` using process_doc:**
+- **Single project**: One docs folder for a product.
+- **Multi-project**: Register multiple folders and switch with `limps config use`.
+- **Shared team folder**: Put plans in a shared location and review changes like code.
+- **Local-first**: Keep everything on disk, no hosted service required.
 
-```typescript
-// Extract next GAP feature from plan
-const nextGap = await process_doc({
-  path: `plans/${planName}/plan.md`,
-  code: `
-    const features = extractFeatures(doc.content);
-    const gaps = features.filter(f => f.status === 'GAP');
-    return gaps.sort((a, b) => a.priority - b.priority)[0];
-  `,
-});
-```
+Key ideas:
 
-**Project Structure:**
+- **Any folder** — You choose the path; if there’s no `plans/` subdir, the whole directory is indexed. Use generic tools (`list_docs`, `search_docs`, `create_doc`, `update_doc`, `delete_doc`, `process_doc`, `process_docs`) or plan-specific ones (`create_plan`, `list_plans`, `list_agents`, `get_plan_status`, `update_task_status`, `get_next_task`).
+- **One source of truth** — MCP tools give structured access; multiple clients share the same docs.
 
-```
-runi/                          # Main codebase
-├── .cursor/commands/          # Cursor slash commands
-│   ├── create-feature-plan.md
-│   ├── list-feature-plans.md
-│   ├── run-agent.md
-│   ├── close-feature-agent.md
-│   └── update-feature-plan.md
-└── .claude/commands/          # Claude Code commands
-    └── pr.md
-
-runi-planning-docs/            # Separate git repo for plans
-├── plans/
-│   ├── 0004-datagrid/        # Feature plan
-│   │   ├── plan.md           # Full specifications
-│   │   ├── interfaces.md     # Interface contracts
-│   │   ├── README.md         # Status index
-│   │   ├── gotchas.md        # Discovered issues
-│   │   └── agents/           # Agent task files
-│   └── ...
-└── decisions/                 # Decision log
-```
+## Why limps?
 
-## Installation
+**The problem:** Each AI assistant maintains its own context. Planning documents, task status, and decisions get fragmented across Claude, Cursor, ChatGPT, and Copilot conversations.
+
+**The solution:** limps provides a standardized MCP interface that any tool can access. Your docs live in one place—a folder you choose. Use git (or any sync) if you want version control; limps is not tied to a repository.
+
+### Supported Clients
 
-### Global Install (Recommended)
+| Client | Config Location | Command |
+|--------|----------------|---------|
+| **Cursor** | `.cursor/mcp.json` (local) | `limps config sync-mcp --client cursor` |
+| **Claude Code** | `.mcp.json` (local) | `limps config sync-mcp --client claude-code` |
+| **Claude Desktop** | Global config | `limps config sync-mcp --client claude --global` |
+| **OpenAI Codex** | `~/.codex/config.toml` | `limps config sync-mcp --client codex --global` |
+| **ChatGPT** | Manual setup | `limps config sync-mcp --client chatgpt --print` |
+
+> **Note:** By default, `sync-mcp` writes to local/project configs. Use `--global` for user-level configs.
+
+## Installation
 
 ```bash
 npm install -g @sudosandwich/limps
 ```
 
-### Quick Setup
+## Project Setup
+
+### Initialize a New Project
 
 ```bash
-limps init my-project --docs-path ~/Documents/my-project
+limps init my-project --docs-path ~/Documents/my-planning-docs
 ```
 
-This creates a config and outputs the Cursor/Claude Desktop configuration snippets with full paths.
-
-## CLI Commands
+This creates a config file and outputs setup instructions.
 
-limps provides a full CLI for managing projects and viewing plans without needing an MCP client.
+### Register an Existing Directory
 
 ```bash
-limps --help              # Show all commands
-limps <command> --help    # Show command help
+limps config add my-project ~/Documents/existing-docs
 ```
 
-### Project Management
+If the directory contains a `plans/` subdirectory, limps uses it. Otherwise, it indexes the entire directory.
 
-| Command | Description |
-|---------|-------------|
-| `limps init <name>` | Initialize a new project |
-| `limps serve` | Start the MCP server |
-
-### Plan Commands
-
-| Command | Description |
-|---------|-------------|
-| `limps list-plans` | List all plans with status |
-| `limps list-agents <plan>` | List agents in a plan |
-| `limps next-task <plan>` | Get the highest-priority available task |
-| `limps status <plan>` | Show plan status summary |
-
-### Configuration
-
-| Command | Description |
-|---------|-------------|
-| `limps config list` | Show all registered projects |
-| `limps config use <name>` | Switch to a different project |
-| `limps config show` | Display resolved configuration |
-| `limps config path` | Print the config file path |
-| `limps config add <name> <path>` | Register an existing config |
-| `limps config remove <name>` | Unregister a project |
-| `limps config set <path>` | Set current from config path |
-| `limps config discover` | Find configs in default locations |
-| `limps config update <name>` | Update project paths |
-| `limps config sync-mcp` | Add projects to MCP client configs |
-
-### Multi-Project Workflow
+### Multiple Projects
 
 ```bash
 # Register multiple projects
-limps init project-a --docs-path ~/Documents/project-a
-limps init project-b --docs-path ~/Documents/project-b
+limps init project-a --docs-path ~/docs/project-a
+limps init project-b --docs-path ~/docs/project-b
 
-# Switch between projects
+# Switch between them
 limps config use project-a
-limps list-plans
-
-limps config use project-b
-limps list-plans
 
-# Use environment variable
-LIMPS_PROJECT=project-a limps list-plans
+# Or use environment variable
+LIMPS_PROJECT=project-b limps list-plans
 ```
 
-### Example: Git-based Document Versioning
+## Client Setup
 
-Point limps at a git repository to version control your planning documents:
+### Automatic (Recommended)
 
 ```bash
-# Create a dedicated docs repo
-mkdir ~/Documents/GitHub/my-planning-docs
-cd ~/Documents/GitHub/my-planning-docs
-git init
-
-# Initialize limps with your docs repo
-limps init my-project --docs-path ~/Documents/GitHub/my-planning-docs
-```
-
-This approach gives you:
-- **Version history** for all plans and decisions
-- **Branching** for experimental planning
-- **Collaboration** via pull requests
-- **Backup** through remote repositories
-
-### Manual Configuration
-
-The server automatically finds configuration at OS-specific locations:
-
-| OS | Config Location |
-|----|-----------------|
-| macOS | `~/Library/Application Support/limps/config.json` |
-| Linux | `~/.config/limps/config.json` |
-| Windows | `%APPDATA%\limps\config.json` |
+# Add all projects to a client's local config
+limps config sync-mcp --client cursor
 
-## Configuration
+# Preview changes without writing
+limps config sync-mcp --client cursor --print
 
-Create a `config.json` at the OS-specific location or specify a path:
+# Write to global config instead of local
+limps config sync-mcp --client cursor --global
 
-```json
-{
-  "plansPath": "~/Documents/my-plans",
-  "docsPaths": ["~/Documents/my-plans"],
-  "fileExtensions": [".md"],
-  "dataPath": "~/Library/Application Support/limps/data",
-  "extensions": ["@sudosandwich/limps-radix"],
-  "@sudosandwich/limps-radix": {
-    "cacheDir": "~/Library/Application Support/limps-radix",
-    "featureFlags": {
-      "enableRadix": true
-    }
-  },
-  "scoring": {
-    "weights": {
-      "dependency": 40,
-      "priority": 30,
-      "workload": 30
-    },
-    "biases": {}
-  }
-}
+# Custom config path
+limps config sync-mcp --client cursor --path ./custom-mcp.json
 ```
 
-### Config Resolution Priority
-
-The server finds configuration in this order:
-
-1. **CLI argument**: `limps serve --config /path/to/config.json`
-2. **Environment variable**: `MCP_PLANNING_CONFIG=/path/to/config.json`
-3. **Project environment**: `LIMPS_PROJECT=my-project` (looks up in registry)
-4. **Registry current project**: Set via `limps config use <name>`
-5. **OS-specific default**: See table above
-
-> **Note:** If no config exists at the resolved path, limps auto-creates a default config file.
-
-### Config Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `plansPath` | string | `./plans` | Primary directory for structured plans (contains `NNNN-name/` directories with agents, tasks, status tracking) |
-| `docsPaths` | string[] | `[]` | Additional directories to index for search (any markdown, no structure required) |
-| `fileExtensions` | string[] | `[".md"]` | File types to index |
-| `dataPath` | string | `./data` | SQLite database location |
-| `scoring` | object | required | Task scoring configuration for `get_next_task` (weights and biases) |
-| `extensions` | string[] | `[]` | Extension package names to load (e.g., `["@sudosandwich/limps-radix"]`) |
+### Manual Setup
 
-### Path Options
+<details>
+<summary><b>Cursor</b></summary>
 
-- **Tilde expansion**: `~/Documents/plans` → `/Users/you/Documents/plans`
-- **Absolute paths**: `/Users/john/Documents/plans`
-- **Relative paths**: `./plans` (relative to config file location)
-
-### Extensions
-
-Extensions are loaded by package name from `node_modules` and can register MCP tools/resources.
-Per-extension configuration lives under a top-level key matching the package name.
-
-Security note: extensions execute local code. Only install extensions you trust. Extensions should never log prompts or model outputs; keep logs to metadata only.
+Add to `.cursor/mcp.json` in your project:
 
 ```json
 {
-  "extensions": ["@sudosandwich/limps-radix"],
-  "@sudosandwich/limps-radix": {
-    "cacheDir": "~/Library/Application Support/limps-radix",
-    "featureFlags": {
-      "enableRadix": true
+  "mcpServers": {
+    "limps": {
+      "command": "limps",
+      "args": ["serve", "--config", "/path/to/config.json"]
     }
   }
 }
 ```
 
-## MCP Client Setup
+</details>
 
-> **Important:** MCP clients must use the `serve` subcommand. Run `limps init my-project` first to generate a config.
+<details>
+<summary><b>Claude Code</b></summary>
 
-### Cursor
-
-Add to settings (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):
+Add to `.mcp.json` in your project root:
 
 ```json
 {
-  "mcp.servers": {
+  "mcpServers": {
     "limps": {
       "command": "limps",
       "args": ["serve", "--config", "/path/to/config.json"]
@@ -299,9 +177,12 @@ Add to settings (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):
 }
 ```
 
-### Claude Desktop
+</details>
 
-Claude Desktop runs in a macOS sandbox—use `npx` instead of global binaries.
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Claude Desktop runs in a sandbox—use `npx` instead of global binaries.
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -316,290 +197,329 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-### Claude Code
+</details>
 
-Add to `~/.claude/.mcp.json`:
+<details>
+<summary><b>OpenAI Codex</b></summary>
 
-```json
-{
-  "mcpServers": {
-    "limps": {
-      "command": "npx",
-      "args": ["-y", "@sudosandwich/limps", "serve", "--config", "/path/to/config.json"]
-    }
-  }
-}
-```
+Add to `~/.codex/config.toml`:
 
-### Automatic MCP Client Configuration
+```toml
+[mcp_servers.limps]
+command = "limps"
+args = ["serve", "--config", "/path/to/config.json"]
+```
 
-Instead of manually editing config files, use the CLI:
+</details>
 
-```bash
-# Add all registered projects to all MCP clients
-limps config sync-mcp
+<details>
+<summary><b>ChatGPT</b></summary>
 
-# Add to specific client only
-limps config sync-mcp --client claude
-limps config sync-mcp --client cursor
-limps config sync-mcp --client claude-code
+ChatGPT requires a remote MCP server over HTTPS. Deploy limps behind an MCP-compatible HTTP/SSE proxy.
 
-# Add specific projects
-limps config sync-mcp --projects my-project,other-project
+In ChatGPT → Settings → Connectors → Add custom connector:
 
-# Preview without writing
-limps config sync-mcp --print
+- **Server URL**: `https://your-domain.example/mcp`
+- **Authentication**: Configure as needed
 
-# Show a JSON Patch diff before writing (confirm prompt)
-limps config sync-mcp
+Print setup instructions:
 
-# Skip diff/confirmation and write directly
-limps config sync-mcp -f
+```bash
+limps config sync-mcp --client chatgpt --print
 ```
 
-## Features
-
-### MCP Tools (15 Tools)
+</details>
 
-#### Document Operations
+## CLI Commands
 
-| Tool | Description |
-|------|-------------|
-| `process_doc` | Process a document with JavaScript code (read, filter, transform, extract) |
-| `process_docs` | Process multiple documents with JavaScript for cross-document analysis |
-| `create_doc` | Create new documents |
-| `update_doc` | Update with overwrite, append, or prepend modes |
-| `delete_doc` | Delete documents |
-| `list_docs` | List files and directories |
-| `search_docs` | Full-text search with frontmatter support, excerpts, and match counts |
-| `manage_tags` | Add, remove, or list tags (frontmatter and inline `#tag` format) |
-| `open_document_in_cursor` | Open files in Cursor editor |
+### Viewing Plans
 
-#### Plan Management
+```bash
+limps list-plans              # List all plans with status
+limps list-agents <plan>      # List agents in a plan
+limps status <plan>           # Show plan progress summary
+limps next-task <plan>        # Get highest-priority available task
+```
 
-| Tool | Description |
-|------|-------------|
-| `create_plan` | Create feature plans with directory structure and agent files |
-| `list_plans` | List all plans with status, workType, and overview |
-| `list_agents` | List agents for a plan with status, persona, and file counts |
-| `get_plan_status` | Get plan progress with completion %, blocked/WIP agents |
+### Project Management
 
-#### Task Management
+```bash
+limps init <name>             # Initialize new project
+limps serve                   # Start MCP server
+limps config list             # Show registered projects
+limps config use <name>       # Switch active project
+limps config show             # Display current config
+limps config sync-mcp         # Add projects to MCP clients
+```
 
-| Tool | Description |
-|------|-------------|
-| `get_next_task` | Get highest-priority task with detailed score breakdown |
-| `update_task_status` | Update task status (GAP → WIP → PASS/BLOCKED) |
+## Configuration
 
-#### Task Scoring Algorithm
+Config location varies by OS:
 
-When using `get_next_task` with a `planId`, returns a detailed score breakdown:
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/limps/config.json` |
+| Linux | `~/.config/limps/config.json` |
+| Windows | `%APPDATA%\limps\config.json` |
 
-| Score Component | Max Points | Description |
-|----------------|------------|-------------|
-| Dependency Score | 40 | All dependencies satisfied = 40, otherwise 0 |
-| Priority Score | 30 | Based on agent number (lower = higher priority) |
-| Workload Score | 30 | Based on file count (fewer files = higher score) |
-| **Total** | **100** | Sum of all components |
+### Config Options
 
-Example response:
 ```json
 {
-  "taskId": "0001-feature#002",
-  "title": "Implement API endpoints",
-  "totalScore": 85,
-  "dependencyScore": 40,
-  "priorityScore": 24,
-  "workloadScore": 21,
-  "reasons": ["All 2 dependencies satisfied", "Agent #2 priority: 24/30", "3 files to modify: 21/30"],
-  "otherAvailableTasks": 3
+  "plansPath": "~/Documents/my-plans",
+  "docsPaths": ["~/Documents/my-plans"],
+  "fileExtensions": [".md"],
+  "dataPath": "~/Library/Application Support/limps/data",
+  "extensions": ["@sudosandwich/limps-radix"],
+  "scoring": {
+    "weights": { "dependency": 40, "priority": 30, "workload": 30 },
+    "biases": {}
+  }
 }
 ```
 
-#### Scoring Biases
+| Option | Description |
+|--------|-------------|
+| `plansPath` | Directory for structured plans (`NNNN-name/` with agents) |
+| `docsPaths` | Additional directories to index |
+| `fileExtensions` | File types to index (default: `.md`) |
+| `dataPath` | SQLite database location |
+| `extensions` | Extension packages to load |
+| `scoring` | Task prioritization weights and biases |
 
-Biases are numeric adjustments added to the final score. Use them to promote or demote specific plans, personas, or statuses.
+## MCP Tools
 
-Supported bias keys:
+limps exposes 15 MCP tools for AI assistants:
 
-| Bias Key | Description | Example |
-|---------|-------------|---------|
-| `plans` | Per-plan bias keyed by plan folder name | `"plans": { "0030-limps-scoring-weights": 20 }` |
-| `personas.coder` | Bias for coder tasks | `"personas": { "coder": 10 }` |
-| `personas.reviewer` | Bias for reviewer tasks | `"personas": { "reviewer": -10 }` |
-| `personas.pm` | Bias for PM tasks | `"personas": { "pm": 5 }` |
-| `personas.customer` | Bias for customer tasks | `"personas": { "customer": 5 }` |
-| `statuses.GAP` | Bias for GAP tasks | `"statuses": { "GAP": 5 }` |
-| `statuses.WIP` | Bias for WIP tasks | `"statuses": { "WIP": -5 }` |
-| `statuses.BLOCKED` | Bias for BLOCKED tasks | `"statuses": { "BLOCKED": 10 }` |
+| Category | Tools |
+|----------|-------|
+| **Documents** | `process_doc`, `process_docs`, `create_doc`, `update_doc`, `delete_doc`, `list_docs`, `search_docs`, `manage_tags`, `open_document_in_cursor` |
+| **Plans** | `create_plan`, `list_plans`, `list_agents`, `get_plan_status` |
+| **Tasks** | `get_next_task`, `update_task_status` |
+
+## Extensions
+
+Extensions add MCP tools and resources. Install from npm:
+
+```bash
+npm install -g @sudosandwich/limps-radix
+```
+
+Add to config:
 
-Example:
 ```json
 {
-  "scoring": {
-    "weights": {
-      "dependency": 40,
-      "priority": 30,
-      "workload": 30
-    },
-    "biases": {
-      "plans": { "0030-limps-scoring-weights": 20 },
-      "personas": { "reviewer": -10, "coder": 5 },
-      "statuses": { "GAP": 5 }
-    }
+  "extensions": ["@sudosandwich/limps-radix"],
+  "@sudosandwich/limps-radix": {
+    "cacheDir": "~/Library/Application Support/limps-radix"
   }
 }
 ```
 
-### RLM (Recursive Language Model) Support
+**Available extensions:**
 
-Implements the [RLM pattern from MIT CSAIL](https://arxiv.org/abs/2512.24601) for programmatic document examination and recursive processing:
+- `@sudosandwich/limps-radix` — Radix UI contract extraction and semantic analysis
 
-- **Sandbox execution** - Secure JavaScript via QuickJS
-- **Recursive sub-calls** - Depth-limited processing
-- **Parallel execution** - Cross-document analysis
-- **Document extractors** - Markdown, YAML, Gherkin parsing
+## Obsidian Compatibility
 
-#### Sub-query LLM Gating
+limps works with Obsidian vaults. Open your `plans/` directory as a vault for visual editing:
 
-`process_doc` and `process_docs` only invoke LLM sub-queries when explicitly enabled. This keeps local workflows deterministic by default and avoids token spend unless requested.
+- Full YAML frontmatter support
+- Tag management (frontmatter and inline `#tag`)
+- Automatic exclusion of `.obsidian/`, `.git/`, `node_modules/`
 
-- **Opt-in:** `allow_llm: true` is required to run `sub_query`
-- **Policy:** `llm_policy: "auto"` (default) skips small results (under 800 bytes); `"force"` always runs
-- **Skip metadata:** when skipped, responses include `sub_query_skipped` and `sub_query_reason`
+![Obsidian vault with limps plans](https://github.com/paulbreuler/limps/blob/main/.github/assets/obsidian-vault.png?raw=true)
 
-Example:
-```typescript
-await process_doc({
-  path: 'plans/0001-feature/plan.md',
-  code: 'extractFeatures(doc.content)',
-  sub_query: 'Summarize each feature',
-  allow_llm: true,
-  llm_policy: 'force'
-});
+## Development
+
+```bash
+git clone https://github.com/paulbreuler/limps.git
+cd limps
+npm install
+npm run build
+npm test
 ```
 
-### Obsidian Vault Compatibility
+This is a monorepo with:
 
-limps is compatible with Obsidian vaults. Simply open your `plans/` directory as an Obsidian vault to get a visual editor for your planning documents:
+- `packages/limps` — Core MCP server
+- `packages/limps-radix` — Radix UI extension
 
-![Obsidian vault with limps plans](https://github.com/paulbreuler/limps/blob/main/.github/assets/obsidian-vault.png?raw=true)
+## Used in Production
 
-**Features:**
-- **Frontmatter parsing** - Full YAML frontmatter support via `gray-matter`
-- **Tag management** - Both frontmatter `tags:` arrays and inline `#tag` format
-- **Path filtering** - Automatically excludes `.obsidian/`, `.git/`, `node_modules/`
-- **Frontmatter search** - Search within YAML properties with `searchFrontmatter: true`
+limps manages planning for [runi](https://github.com/paulbreuler/runi), using a separate folder (in this case a git repo) for plans.
 
-> **Tip:** The `.obsidian/` folder is automatically excluded from indexing and should be added to `.gitignore` to keep local settings out of version control.
+---
 
-#### Enhanced Search Features
+## Creating a feature plan
 
-```typescript
-// Search with frontmatter and excerpts
-await search_docs({
-  query: 'status PASS',
-  searchFrontmatter: true,  // Search in YAML frontmatter
-  searchContent: true,       // Search in body content
-  caseSensitive: false,      // Case-insensitive (default)
-  prettyPrint: true          // Human-readable output
-});
+This flow is used by the **create-feature-plan** command you can find in [claude/commands](/.claude/commands/) along with other useful commands and skills. These can be followed manually with MCP tools. The docs path is whatever folder limps is pointed at (any directory, not necessarily a repo).
+
+1. **Gather context** — Project name and scope, work type (`refactor` | `overhaul` | `features`), tech stack, prototype/reference docs, known gotchas.
+2. **Create planning docs** — Use MCP:
+   - `list_docs` on `plans/` to get the next plan number (max existing + 1).
+   - `create_plan` with name `NNNN-descriptive-name` and a short description.
+   - `create_doc` for: `{plan-name}-plan.md` (full specs), `interfaces.md`, `README.md`, `gotchas.md` (template). Use template `none` for plan/interfaces/README, `addendum` for gotchas if available.
+3. **Assign features to agents** — Group by file ownership and dependencies; 2–4 features per agent; minimize cross-agent conflicts.
+4. **Distill agent files** — For each agent, `create_doc` at `plans/NNNN-name/agents/NNN_agent_descriptive-name.agent.md` (template `none`). Extract from the plan: feature IDs + TL;DRs, interface contracts, files to create/modify, test IDs, TDD one-liners, brief gotchas. Target ~200–400 lines per agent.
+5. **Validate** — Agent files self-contained; interfaces consistent; dependency graph and file ownership correct; each agent file <500 lines.
 
-// Returns: path, title, excerpt (with context), matchCount, lineNumber
+Resulting layout:
+
+```
+NNNN-descriptive-name/
+├── README.md
+├── {plan-name}-plan.md
+├── interfaces.md
+├── gotchas.md
+└── agents/
+    ├── 000_agent_infrastructure.agent.md
+    ├── 001_agent_....agent.md
+    └── ...
 ```
 
-#### Write Modes for update_doc
+### Why the prefixes?
 
-```typescript
-// Append content (preserves existing, merges frontmatter)
-await update_doc({
-  path: 'notes/meeting.md',
-  content: '\n## Action Items\n- Task 1',
-  mode: 'append'
-});
+I chose this to keep things lexicographically ordered and easier to reference in chat. "Show me the next agent or agents we can run now in plan 25", and the MCP will run the tool to process the agents applying weights and biases to choose the next best task or tasks that can run in parallel.
 
-// Prepend content
-await update_doc({
-  path: 'notes/log.md',
-  content: '## 2024-01-26\nNew entry\n',
-  mode: 'prepend'
-});
+## Deep Dive
+
+<details>
+<summary><b>Plan Structure</b></summary>
+
+```
+plans/
+├── 0001-feature-name/
+│   ├── 0001-feature-name-plan.md    # Main plan with specs
+│   ├── interfaces.md                 # Interface contracts
+│   ├── README.md                     # Status index
+│   └── agents/                       # Task files
+│       ├── 000-setup.md
+│       ├── 001-implement.md
+│       └── 002-test.md
+└── 0002-another-feature/
+    └── ...
 ```
 
-#### Tag Management
+Agent files use frontmatter to track status:
 
-```typescript
-// List all tags (frontmatter + inline #tags)
-await manage_tags({ path: 'notes/project.md', operation: 'list' });
+```yaml
+---
+status: GAP | WIP | PASS | BLOCKED
+persona: coder | reviewer | pm | customer
+depends_on: ["000-setup"]
+files:
+  - src/components/Feature.tsx
+---
+```
+
+</details>
+
+<details>
+<summary><b>Task Scoring Algorithm</b></summary>
+
+`get_next_task` returns tasks scored by:
 
-// Add tags to frontmatter
-await manage_tags({ path: 'notes/project.md', operation: 'add', tags: ['active', 'priority'] });
+| Component | Max Points | Description |
+|-----------|------------|-------------|
+| Dependency | 40 | All dependencies satisfied = 40, else 0 |
+| Priority | 30 | Based on agent number (lower = higher priority) |
+| Workload | 30 | Based on file count (fewer = higher score) |
 
-// Remove tags
-await manage_tags({ path: 'notes/project.md', operation: 'remove', tags: ['draft'] });
+**Biases** adjust final scores:
+
+```json
+{
+  "scoring": {
+    "biases": {
+      "plans": { "0030-urgent-feature": 20 },
+      "personas": { "coder": 5, "reviewer": -10 },
+      "statuses": { "GAP": 5, "WIP": -5 }
+    }
+  }
+}
 ```
 
-### Resources (Progressive Disclosure)
+</details>
 
-- `plans://index` — List of all plans (minimal)
-- `plans://summary` — Plan summaries (key info)
-- `plans://full` — Full plan documents
-- `decisions://log` — Decision log entries
-- `agents://status` — Agent status and tasks
+<details>
+<summary><b>RLM (Recursive Language Model) Support</b></summary>
 
-## Development
+`process_doc` and `process_docs` execute JavaScript in a secure QuickJS sandbox. User-provided code is statically validated and cannot use `require`, `import`, `eval`, `fetch`, `XMLHttpRequest`, `WebSocket`, `process`, timers, or other host/network APIs—so it cannot make external calls or access the host.
 
-```bash
-git clone https://github.com/paulbreuler/limps.git
-cd limps
-npm install       # Install dependencies
-npm run build     # Build TypeScript
-npm test          # Run tests
-npm run dev       # Watch mode
-npm run lint      # ESLint check
-npm run format    # Prettier format
+```typescript
+await process_doc({
+  path: 'plans/0001-feature/plan.md',
+  code: `
+    const features = extractFeatures(doc.content);
+    return features.filter(f => f.status === 'GAP');
+  `
+});
 ```
 
-Pre-commit hooks run lint-staged, build, and tests automatically.
+**Available extractors:**
 
-## Releasing
+- `extractSections()` — Markdown headings
+- `extractFrontmatter()` — YAML frontmatter
+- `extractFeatures()` — Plan features with status
+- `extractAgents()` — Agent metadata
+- `extractCodeBlocks()` — Fenced code blocks
 
-```bash
-# Update version in package.json, then:
-git tag v0.2.1
-git push origin v0.2.1
+**LLM sub-queries** (opt-in):
+
+```typescript
+await process_doc({
+  path: 'plans/0001/plan.md',
+  code: 'extractFeatures(doc.content)',
+  sub_query: 'Summarize each feature',
+  allow_llm: true,
+  llm_policy: 'force'  // or 'auto' (skips small results)
+});
 ```
 
-GitHub Actions automatically builds, tests, and creates releases with changelogs.
+</details>
+
+<details>
+<summary><b>MCP Resources</b></summary>
 
-## Architecture
+Progressive disclosure via resources:
 
-![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)
-![React](https://img.shields.io/badge/React-19-61dafb)
-![Ink](https://img.shields.io/badge/Ink-6-green)
-![SQLite](https://img.shields.io/badge/SQLite-FTS5-003B57)
-![Zod](https://img.shields.io/badge/Zod-4-3068b7)
+| Resource | Description |
+|----------|-------------|
+| `plans://index` | List of all plans (minimal) |
+| `plans://summary` | Plan summaries with key info |
+| `plans://full` | Full plan documents |
+| `decisions://log` | Decision log entries |
+| `agents://status` | Agent status and tasks |
 
-- Full-text search with auto-indexing and frontmatter support
-- Real-time file watching (Chokidar) with path filtering
-- RLM sandbox (QuickJS)
-- Obsidian-compatible frontmatter (gray-matter)
+</details>
 
-### Principles
+<details>
+<summary><b>Example: Custom Cursor Commands</b></summary>
 
-1. Simplicity over complexity
-2. Local-first, no external dependencies
-3. Progressive disclosure (index → summary → full)
-4. Optimistic concurrency
-5. Scoring-based task selection
+Create `.cursor/commands/run-agent.md`:
+
+```markdown
+# Run Agent
+
+Start work on the next available task.
+
+## Instructions
+
+1. Use `get_next_task` to find the highest-priority task
+2. Use `process_doc` to read the agent file
+3. Use `update_task_status` to mark it WIP
+4. Follow the agent's instructions
+```
 
-## Adapting for Other Uses
+This integrates with limps MCP tools for seamless task management.
+</details>
 
-The server is designed for planning documents but the core is generic. For wikis or knowledge bases: configure `plansPath`/`docsPaths`/`fileExtensions` to point at your content, and optionally customize extractors in `src/rlm/extractors.ts`.
+---
 
 ## What is MCP?
 
-**MCP (Model Context Protocol)** is a standardized protocol for AI applications to connect to external systems. Launched by Anthropic (Nov 2024), now part of the Linux Foundation's Agentic AI Foundation.
+**Model Context Protocol** is a standardized protocol for AI applications to connect to external systems. Originally from Anthropic (Nov 2024), now part of the Linux Foundation's Agentic AI Foundation.
 
 - [MCP Specification](https://modelcontextprotocol.io/)
 - [MCP Documentation](https://modelcontextprotocol.io/docs)