@sudosandwich/limps 3.0.0 → 3.1.1

package/README.md

@@ -19,12 +19,15 @@
 - [How You Can Use It](#how-you-can-use-it)
 - [Why limps?](#why-limps)
 - [Installation](#installation)
+- [Upgrading from v2](#upgrading-from-v2)
 - [Project Setup](#project-setup)
 - [Client Setup](#client-setup)
 - [Transport](#transport)
+- [Daemon Management](#daemon-management)
 - [CLI Commands](#cli-commands)
 - [Configuration](#configuration)
 - [Environment Variables](#environment-variables)
+- [Troubleshooting](#troubleshooting)
 - [MCP Tools](#mcp-tools)
 - [Skills & Commands](#skills--commands)
 - [Extensions](#extensions)
@@ -33,7 +36,6 @@
 - [Used in Production](#used-in-production)
 - [Creating a feature plan](#creating-a-feature-plan)
 - [Deep Dive](#deep-dive)
-- [Instructions](#instructions)
 - [What is MCP?](#what-is-mcp)
 - [License](#license)
 
@@ -43,15 +45,24 @@
 # Install globally
 npm install -g @sudosandwich/limps
 
-# Initialize a project
-limps init my-project --docs-path ~/Documents/my-planning-docs
+# Initialize in your project
+cd ~/Documents/my-planning-docs
+limps init
 
-# Add to your AI assistant (picks up all registered projects)
-limps config sync-mcp --client cursor
-limps config sync-mcp --client claude-code
+# Start the HTTP daemon
+limps start
+# → Daemon starts on http://127.0.0.1:4269/mcp
+# → PID file written to OS-standard location
+# → Ready for MCP client connections
+
+# Generate MCP client config
+limps config print --client claude-code
+# Copy the output to your MCP client config file
 ```
 
-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.
+That's it. Your AI assistant now has access to your documents via HTTP transport. The folder can be anywhere—local, synced, or in a repo; limps does not require a git repository or a `plans/` directory.
+
+**Tip:** `limps status-server` shows the status of the current project if a config is found in the working directory (or passed via `--config`). Run it from a directory where no limps config can be resolved to list all running limps daemons on your system.
 
 ## Features
 
@@ -59,7 +70,7 @@ Run this in the folder where you want to keep the docs and that's it. Your AI as
 - **Plan + agent workflows** with status tracking and task scoring
 - **Next-task suggestions** with score breakdowns and bias tuning
 - **Sandboxed document processing** via `process_doc(s)` helpers
-- **Multi-client sync** for Cursor, Claude, Codex, and more
+- **Multi-client support** for Cursor, Claude, Codex, and more
 - **Extensions** for domain-specific tooling (e.g., limps-headless)
 - **Knowledge graph** — Entity extraction, hybrid retrieval, conflict detection, and graph-based suggestions
 - **Health automation** — Staleness detection, code drift checks, status inference, and auto-fix proposals
@@ -70,6 +81,7 @@ Run this in the folder where you want to keep the docs and that's it. Your AI as
 
 - **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.
+- **Daemon management** — The HTTP server runs as a background process. Use `limps start`, `limps stop`, and `limps status-server` to manage the daemon lifecycle. PID files are stored in OS-standard directories for system-wide awareness.
 - **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.
 
@@ -81,7 +93,7 @@ Typical flow:
 
 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.
+3. Add the limps MCP entry to each client config so Cursor/Claude/Codex all see the same plans.
 
 Commands and tools I use most often:
 
@@ -100,7 +112,7 @@ Full lists are below in "CLI Commands" and "MCP Tools."
 Common setups:
 
 - **Single project**: One docs folder for a product.
-- **Multi-project**: Register multiple folders and switch with `limps config use`.
+- **Multi-project**: Each project gets its own `.limps/config.json`; pass `--config` to target a specific one.
 - **Shared team folder**: Put plans in a shared location and review changes like code.
 - **Local-first**: Keep everything on disk, no hosted service required.
 
@@ -115,75 +127,96 @@ Key ideas:
 
 **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
-
-| 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
 ```
 
+## Upgrading from v2
+
+v3 introduces major changes:
+
+### HTTP Transport (Breaking Change)
+
+v3 uses **HTTP transport exclusively**. stdio transport has been removed.
+
+**Migration steps:**
+
+1. **Start the HTTP daemon** for each project:
+   ```bash
+   limps start --config /path/to/.limps/config.json
+   ```
+
+2. **Update MCP client configs** — Replace stdio configs with HTTP transport:
+   ```json
+   {
+     "mcpServers": {
+       "limps-planning-myproject": {
+         "transport": {
+           "type": "http",
+           "url": "http://127.0.0.1:4269/mcp"
+         }
+       }
+     }
+   }
+   ```
+   Use `limps config print` to generate the correct snippet.
+
+### Per-Project Configs (Breaking Change)
+
+v3 removes the centralized project registry. If you previously used `limps config add`, `config use`, or the `--project` flag:
+
+1. **Run `limps init`** in each project directory to create `.limps/config.json`.
+2. **Update MCP client configs** — Replace `--project <name>` with HTTP transport config (see above).
+3. **Remove environment variable** — `LIMPS_PROJECT` no longer exists. Use `MCP_PLANNING_CONFIG` to override config path.
+
+**Removed commands:** `config list`, `config use`, `config add`, `config remove`, `config set`, `config discover`, `config migrate`, `config sync-mcp`, `serve`.
+
+**Replaced by:** `limps init` + `limps start` + `limps config print`.
+
 ## Project Setup
 
 ### Initialize a New Project
 
 ```bash
-limps init my-project --docs-path ~/Documents/my-planning-docs
+cd ~/Documents/my-planning-docs
+limps init
 ```
 
-This creates a config file and outputs setup instructions.
+This creates `.limps/config.json` in the current directory and prints MCP client setup instructions.
 
-### Register an Existing Directory
+You can also specify a path:
 
 ```bash
-limps config add my-project ~/Documents/existing-docs
+limps init ~/Documents/my-planning-docs
 ```
 
 If the directory contains a `plans/` subdirectory, limps uses it. Otherwise, it indexes the entire directory.
 
 ### Multiple Projects
 
-```bash
-# Register multiple projects
-limps init project-a --docs-path ~/docs/project-a
-limps init project-b --docs-path ~/docs/project-b
-
-# Switch between them
-limps config use project-a
+Each project has its own `.limps/config.json`. Use `--config` to target a specific project:
 
-# Or use environment variable
-LIMPS_PROJECT=project-b limps list-plans
+```bash
+limps list-plans --config ~/docs/project-b/.limps/config.json
 ```
 
 ## Client Setup
 
-### Automatic (Recommended)
+After running `limps init`, you need to add a limps entry to your MCP client's config file. Use `limps config print` to generate the correct snippet for your client, then paste it into the appropriate config file:
 
 ```bash
-# Add all projects to a client's local config
-limps config sync-mcp --client cursor
-
-# Preview changes without writing
-limps config sync-mcp --client cursor --print
+limps config print --client cursor
+limps config print --client claude-code
+limps config print --client claude
+```
 
-# Write to global config instead of local
-limps config sync-mcp --client cursor --global
+The output tells you exactly what JSON (or TOML) to add and where the config file lives.
 
-# Custom config path
-limps config sync-mcp --client cursor --path ./custom-mcp.json
-```
+### Per-Client Examples
 
-### Manual Setup
+All clients connect to the HTTP daemon. Start the daemon first with `limps start`, then configure your client.
 
 <details>
 <summary><b>Cursor</b></summary>
@@ -193,9 +226,11 @@ Add to `.cursor/mcp.json` in your project:
 ```json
 {
   "mcpServers": {
-    "limps": {
-      "command": "limps",
-      "args": ["serve", "--config", "/path/to/config.json"]
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
     }
   }
 }
@@ -211,9 +246,11 @@ Add to `.mcp.json` in your project root:
 ```json
 {
   "mcpServers": {
-    "limps": {
-      "command": "limps",
-      "args": ["serve", "--config", "/path/to/config.json"]
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
     }
   }
 }
@@ -224,48 +261,16 @@ Add to `.mcp.json` in your project root:
 <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`:
 
 ```json
 {
   "mcpServers": {
-    "limps": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@sudosandwich/limps",
-        "serve",
-        "--config",
-        "/path/to/config.json"
-      ]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Windows (npx)</b></summary>
-
-On Windows, use `cmd /c` to run `npx`:
-
-```json
-{
-  "mcpServers": {
-    "limps": {
-      "command": "cmd",
-      "args": [
-        "/c",
-        "npx",
-        "-y",
-        "@sudosandwich/limps",
-        "serve",
-        "--config",
-        "C:\\path\\to\\config.json"
-      ]
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
     }
   }
 }
@@ -279,9 +284,9 @@ On Windows, use `cmd /c` to run `npx`:
 Add to `~/.codex/config.toml`:
 
 ```toml
-[mcp_servers.limps]
-command = "limps"
-args = ["serve", "--config", "/path/to/config.json"]
+[mcp_servers.limps-planning-myproject.transport]
+type = "http"
+url = "http://127.0.0.1:4269/mcp"
 ```
 
 </details>
@@ -289,67 +294,336 @@ args = ["serve", "--config", "/path/to/config.json"]
 <details>
 <summary><b>ChatGPT</b></summary>
 
-ChatGPT requires a remote MCP server over HTTPS. Deploy limps behind an MCP-compatible HTTP/SSE proxy.
+ChatGPT requires a remote MCP server over HTTPS. Deploy limps behind an MCP-compatible HTTPS reverse proxy (nginx, Caddy, etc.) with authentication.
 
 In ChatGPT → Settings → Connectors → Add custom connector:
 
 - **Server URL**: `https://your-domain.example/mcp`
-- **Authentication**: Configure as needed
+- **Authentication**: Configure as needed for your proxy
 
 Print setup instructions:
 
 ```bash
-limps config sync-mcp --client chatgpt --print
+limps config print --client chatgpt
 ```
 
 </details>
 
 ## Transport
 
-### stdio (default)
-
-Your MCP client spawns `limps serve` as a child process. No daemon required.
+limps v3 uses **HTTP transport exclusively** via a persistent daemon. This allows multiple MCP clients to share a single server instance, avoiding file descriptor bloat from multiple stdio processes.
 
-### HTTP (persistent daemon)
-
-Run limps as a long-lived HTTP server that multiple clients can connect to:
+### Start the HTTP daemon
 
 ```bash
 # Start the daemon
-limps start --config /path/to/config.json
+limps start
 
-# Check status
+# Check status (shows uptime, sessions, PID)
 limps status-server
 
 # Stop the daemon
 limps stop
 ```
 
-Configure your MCP client to use HTTP transport:
+The daemon runs at `http://127.0.0.1:4269/mcp` by default. Use `limps config print` to generate the correct MCP client configuration:
+
+```bash
+limps config print --client claude-code
+```
+
+See [Daemon Management](#daemon-management) for detailed lifecycle documentation.
+
+### MCP Client Configuration
+
+All clients use HTTP transport. Example config:
 
 ```json
 {
   "mcpServers": {
-    "limps": {
-      "transport": { "type": "http", "url": "http://127.0.0.1:4269/mcp" }
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
     }
   }
 }
 ```
 
-Server config options (set in `config.json` under `"server"`):
+### Server Config Options
+
+Customize the HTTP server by adding a `"server"` section to your `config.json`:
+
+| Option             | Default                | Description                              |
+| ------------------ | ---------------------- | ---------------------------------------- |
+| `port`             | `4269`                 | HTTP listen port                         |
+| `host`             | `127.0.0.1`            | Bind address                             |
+| `maxSessions`      | `100`                  | Maximum concurrent MCP sessions          |
+| `sessionTimeoutMs` | `1800000`              | Session idle timeout in ms (30 min)      |
+| `corsOrigin`       | `""` (none)            | CORS origin (`""`, `"*"`, or a URL)      |
+| `maxBodySize`      | `10485760`             | Max request body in bytes (10 MB)        |
+| `rateLimit`        | `100 req/min`          | Rate limit per client IP                 |
+
+Example custom server config:
+
+```json
+{
+  "server": {
+    "port": 8080,
+    "host": "0.0.0.0"
+  }
+}
+```
+
+**Note:** PID files are stored in OS-standard application directories:
+- **macOS**: `~/Library/Application Support/limps/pids/`
+- **Linux**: `$XDG_DATA_HOME/limps/pids/` or `~/.local/share/limps/pids/`
+- **Windows**: `%APPDATA%/limps/pids/`
+
+This enables `limps status-server` to perform system-wide daemon discovery when no project configuration can be resolved; when a limps config is found for the current directory, the CLI runs in project mode and reports status for that project instead.
+
+- **Remote clients**: Use an MCP-compatible HTTPS proxy for remote clients (e.g., ChatGPT).
+
+## Daemon Management
+
+limps v3 uses a persistent HTTP daemon with system-wide awareness. PID files are stored in OS-standard directories, allowing you to manage and discover daemons from any directory on your system.
+
+### PID File Locations
+
+PID files are stored in platform-specific application data directories:
+
+**macOS:**
+```
+~/Library/Application Support/limps/pids/
+```
+
+**Linux:**
+```
+$XDG_DATA_HOME/limps/pids/
+# or if XDG_DATA_HOME is not set:
+~/.local/share/limps/pids/
+```
+
+**Windows:**
+```
+%APPDATA%/limps/pids/
+```
+
+Each PID file is named by port number (`limps-{port}.pid`) to enable system-wide discovery. Example PID file structure:
+
+```json
+{
+  "pid": 12345,
+  "port": 4269,
+  "host": "127.0.0.1",
+  "startedAt": "2026-02-08T12:00:00.000Z",
+  "configPath": "/path/to/project/.limps/config.json"
+}
+```
+
+This port-based naming allows `limps status-server` to find all running daemons across different projects without needing a config file.
+
+### Starting the Daemon
+
+**Background mode (default):**
+
+```bash
+limps start
+# → Daemon starts on http://127.0.0.1:4269/mcp
+# → PID file written to OS-standard location
+# → Process detaches and runs in background
+```
+
+**Foreground mode (debugging):**
+
+```bash
+limps start --foreground
+# → Runs in foreground (blocks terminal)
+# → Logs appear in stderr
+# → Useful for debugging startup issues
+# → Still creates PID file for discovery
+```
+
+**Custom port/host (via config):**
+
+Configure `server.port` and `server.host` in your `.limps/config.json`:
+
+```json
+{
+  "server": {
+    "port": 8080,
+    "host": "0.0.0.0"
+  }
+}
+```
+
+Then start normally:
+
+```bash
+limps start
+# → Starts using server.port/server.host from config
+# → PID file: limps-8080.pid
+```
+
+The `start` command performs health verification by polling the `/health` endpoint for up to 5 seconds, issuing repeated HTTP requests. Each individual health-check request has its own shorter timeout (for example, ~1000ms). If any request fails during this window, you'll see one of these error codes:
+
+- **TIMEOUT** — A single health-check HTTP request exceeded its per-request timeout (e.g., ~1000ms). The daemon may be slow to start or system resources may be constrained. Try `limps start --foreground` to see logs.
+- **NETWORK_ERROR** — Cannot connect to daemon. Port may be blocked or already in use by another process.
+- **NON_200_STATUS** — Health endpoint returned a non-200 status code. Check daemon logs with foreground mode.
+- **INVALID_RESPONSE** — Health endpoint responded, but the response was invalid or could not be parsed as expected (for example, malformed or missing required fields).
+
+### Checking Daemon Status
+
+**Project mode (when config is found):**
+
+```bash
+# From within a project directory with .limps/config.json
+limps status-server
+# limps server is running
+# PID: 12345 | 127.0.0.1:4269
+# Uptime: 2h 15m
+# Sessions: 3
+
+# Or specify config explicitly
+limps status-server --config /path/to/.limps/config.json
+```
+
+**System-wide discovery (when no config is found):**
+
+```bash
+# From a directory without a limps config
+cd /tmp
+limps status-server
+# Found 2 running daemons:
+# 127.0.0.1:4269 (PID 12345)
+#   Uptime: 2h 15m | Sessions: 3
+# 127.0.0.1:8080 (PID 67890)
+#   Uptime: 45m 30s | Sessions: 1
+```
+
+When `limps status-server` cannot resolve a config file in the current directory (and no `--config` is provided), it scans the system PID directory and reports all running limps daemons. When a config is found, it shows only that project's daemon status.
+
+### Stopping the Daemon
+
+```bash
+# From the project directory (where your .limps config lives):
+limps stop
+# → Gracefully shuts down daemon
+# → Closes all MCP sessions
+# → Stops file watchers
+# → Removes PID file
+# → Process exits
+
+# Or from any directory, by specifying the config explicitly:
+limps stop --config /path/to/.limps/config.json
+```
+
+The `stop` command is project-specific and resolves the config to determine which daemon to stop. The daemon performs a graceful shutdown by:
+1. Closing all active MCP sessions
+2. Shutting down file watchers
+3. Removing the PID file
+4. Exiting the process
 
-| Option             | Default        | Description                              |
-| ------------------ | -------------- | ---------------------------------------- |
-| `port`             | `4269`         | HTTP listen port                         |
-| `host`             | `127.0.0.1`   | Bind address                             |
-| `maxSessions`      | `100`          | Maximum concurrent MCP sessions          |
-| `sessionTimeoutMs` | `1800000`      | Session idle timeout in ms (30 min)      |
-| `corsOrigin`       | `""` (none)    | CORS origin (`""`, `"*"`, or a URL)      |
-| `maxBodySize`      | `10485760`     | Max request body in bytes (10 MB)        |
-| `rateLimit`        | `100 req/min`  | Rate limit per client IP                 |
+### Port Conflicts
 
-- **Remote clients**: Use an MCP-compatible proxy for HTTPS clients (e.g., ChatGPT).
+If you try to start a daemon on a port that's already in use, limps will detect the conflict and provide resolution guidance:
+
+```bash
+limps start
+# Error: Port 4269 is already in use.
+# Process using port: node (PID 12345)
+# Command: /usr/local/bin/node /usr/local/bin/limps start
+#
+# To stop the process: kill 12345
+# Or use a different port: limps start --port <port>
+```
+
+On systems with `lsof` available (macOS, Linux), limps can identify which process is using the port and show its command line. If `lsof` is not available, you'll see a simpler error message suggesting a different port.
+
+### Foreground Mode
+
+Use foreground mode for debugging, Docker deployments, or CI/CD pipelines:
+
+```bash
+limps start --foreground
+```
+
+**Use cases:**
+- **Debugging** — See server logs in real-time to diagnose startup issues
+- **Docker** — Keep container alive with the daemon as the main process
+- **CI/CD** — Run tests against a limps daemon without background processes
+
+**Behavior differences from background mode:**
+- Logs to stderr instead of being silent
+- Blocks the terminal (press Ctrl+C to stop)
+- Still creates a PID file for discovery by other processes
+- Responds to SIGINT (Ctrl+C) and SIGTERM for graceful shutdown
+
+### Health Endpoint
+
+The HTTP daemon exposes a `/health` endpoint for monitoring and health checks:
+
+```bash
+curl http://127.0.0.1:4269/health
+```
+
+**Example response:**
+
+```json
+{
+  "status": "ok",
+  "sessions": 3,
+  "uptime": 8145,
+  "pid": 12345,
+  "sessionTimeoutMs": 1800000
+}
+```
+
+**HTTP status codes:**
+- **200** — Daemon is healthy and accepting connections
+- **429** — Rate limit exceeded (rate limiter may return this before the request reaches `/health`)
+
+Use this endpoint for:
+- Monitoring daemon health in scripts or dashboards
+- Verifying daemon is running before connecting MCP clients
+- Automated health checks in orchestration tools (Kubernetes, Docker Compose)
+
+### Multiple Daemons
+
+You can run multiple limps daemons on different ports for different projects by configuring different ports in each project's config:
+
+```bash
+# Project A with default port (4269)
+cd ~/projects/project-a
+# .limps/config.json has server.port: 4269 (or uses default)
+limps start
+# → Running on http://127.0.0.1:4269/mcp
+
+# Project B with custom port (8080)
+cd ~/projects/project-b
+# .limps/config.json has server.port: 8080
+limps start
+# → Running on http://127.0.0.1:8080/mcp
+```
+
+Each daemon has its own PID file:
+- `limps-4269.pid` — Project A
+- `limps-8080.pid` — Project B
+
+Discover all running daemons (run from a directory without a limps config):
+
+```bash
+cd /tmp
+limps status-server
+# Found 2 running daemons:
+# 127.0.0.1:4269 (PID 12345)
+#   Uptime: 2h 15m | Sessions: 3
+# 127.0.0.1:8080 (PID 67890)
+#   Uptime: 45m 30s | Sessions: 1
+```
+
+Each MCP client can connect to different daemons by configuring different URLs in their config files.
 
 ## CLI Commands
 
@@ -365,15 +639,13 @@ limps next-task <plan>        # Get highest-priority available task
 ### Project Management
 
 ```bash
-limps init <name>             # Initialize new project
-limps serve                   # Start MCP server (stdio)
-limps start                   # Start persistent HTTP daemon
+limps init [path]             # Initialize new project
+limps start                   # Start HTTP daemon (background by default)
+limps start --foreground      # Start in foreground (debugging mode)
 limps stop                    # Stop HTTP daemon
-limps status-server           # Show HTTP daemon status
-limps config list             # Show registered projects
-limps config use <name>       # Switch active project
+limps status-server           # Show daemon status (current project or all daemons)
 limps config show             # Display current config
-limps config sync-mcp         # Add projects to MCP clients
+limps config print            # Print MCP client config snippets
 ```
 
 ### Health & Automation
@@ -412,22 +684,16 @@ limps repair-plans [--fix]       # Check/fix agent frontmatter
 
 ## Configuration
 
-Config location varies by OS:
-
-| OS      | Path                                              |
-| ------- | ------------------------------------------------- |
-| macOS   | `~/Library/Application Support/limps/config.json` |
-| Linux   | `~/.config/limps/config.json`                     |
-| Windows | `%APPDATA%\limps\config.json`                     |
+Config lives at `.limps/config.json` in your project directory, created by `limps init`.
 
 ### Config Options
 
 ```json
 {
-  "plansPath": "~/Documents/my-plans",
-  "docsPaths": ["~/Documents/my-plans"],
+  "plansPath": "./plans",
+  "docsPaths": ["."],
   "fileExtensions": [".md"],
-  "dataPath": "~/Library/Application Support/limps/data",
+  "dataPath": ".limps/data",
   "extensions": ["@sudosandwich/limps-headless"],
   "tools": {
     "allowlist": ["list_docs", "search_docs"]
@@ -456,12 +722,197 @@ Config location varies by OS:
 
 | Variable               | Description                                                | Example                                           |
 | ---------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
-| `LIMPS_PROJECT`        | Select active project for CLI commands                     | `LIMPS_PROJECT=project-b limps list-plans`        |
+| `MCP_PLANNING_CONFIG`  | Path to config file (overrides default discovery)          | `MCP_PLANNING_CONFIG=./my-config.json limps serve`|
 | `LIMPS_ALLOWED_TOOLS`  | Comma-separated allowlist; only these tools are registered | `LIMPS_ALLOWED_TOOLS="list_docs,search_docs"`     |
 | `LIMPS_DISABLED_TOOLS` | Comma-separated denylist; tools to hide                    | `LIMPS_DISABLED_TOOLS="process_doc,process_docs"` |
 
 **Precedence:** `config.tools` overrides env vars. If allowlist is set, denylist is ignored.
 
+## Troubleshooting
+
+### Daemon Won't Start
+
+**"Port already in use" error:**
+
+If you see this error, another process is using the port:
+
+```bash
+limps start
+# Error: Port 4269 is already in use.
+# Process using port: node (PID 12345)
+```
+
+**Resolution:**
+1. **Kill the existing process**: `kill 12345`
+2. **Or use a different port**: `limps start --port 8080`
+3. **Check if it's another limps daemon**: `limps status-server` (if so, use `limps stop` first)
+
+**"Daemon may have failed to start" error:**
+
+If the daemon starts but doesn't respond to health checks:
+
+```bash
+limps start
+# Error: Daemon may have failed to start. Check logs or try: limps start --foreground
+```
+
+**Resolution:**
+1. **Run in foreground to see logs**: `limps start --foreground`
+2. **Check for permission issues**: Ensure you have write access to the PID directory
+3. **Verify port is accessible**: Try `curl http://127.0.0.1:4269/health`
+4. **Enable debug logging**: `DEBUG=1 limps start --foreground`
+
+**Permission issues with PID directory:**
+
+If you can't create PID files:
+
+```bash
+# macOS
+ls -la ~/Library/Application\ Support/limps/pids/
+
+# Linux
+ls -la ~/.local/share/limps/pids/
+
+# Windows
+dir %APPDATA%\limps\pids
+```
+
+Ensure the directory exists and you have write permissions. If not, create it manually:
+
+```bash
+# macOS
+mkdir -p ~/Library/Application\ Support/limps/pids
+
+# Linux
+mkdir -p ~/.local/share/limps/pids
+
+# Windows
+mkdir %APPDATA%\limps\pids
+```
+
+### Health Check Failures
+
+**TIMEOUT error:**
+
+The daemon did not respond within the configured timeout. Each health-check request has its own timeout (for example, 1000ms during the final `limps start` check and 3000ms for `status-server`), and during startup limps will poll for up to about 5 seconds before reporting "Daemon may have failed to start".
+
+**Common causes:**
+- System resource constraints (high CPU/memory usage)
+- Slow filesystem (especially for index initialization)
+- Large document corpus requiring time to index
+
+**Resolution:**
+1. Check system resources: `top` or Activity Monitor
+2. Wait a bit longer and retry: `limps status-server`
+3. Run in foreground to see progress: `limps start --foreground`
+
+**NETWORK_ERROR:**
+
+Cannot establish connection to the daemon.
+
+**Common causes:**
+- Port is blocked by firewall
+- Daemon crashed after starting
+- Incorrect host/port configuration
+
+**Resolution:**
+1. Verify daemon is running: `limps status-server`
+2. Check firewall settings for port 4269
+3. Try `curl http://127.0.0.1:4269/health` manually
+4. Check daemon logs: `limps start --foreground`
+
+### Stale PID Files
+
+limps automatically cleans up stale PID files when:
+- Running `limps status-server` (discovers and removes stale files)
+- Running `limps start` (removes stale file for the target port)
+- The daemon shuts down gracefully with `limps stop`
+
+If you need to manually clean up PID files:
+
+```bash
+# macOS
+rm ~/Library/Application\ Support/limps/pids/limps-*.pid
+
+# Linux
+rm ~/.local/share/limps/pids/limps-*.pid
+
+# Windows
+del %APPDATA%\limps\pids\limps-*.pid
+```
+
+**When to manually clean up:**
+- After a system crash or forced shutdown
+- If `limps start` reports a daemon is running but it's not
+- Before uninstalling limps
+
+### Multiple Daemons Conflict
+
+If you accidentally try to start a second daemon on the same port:
+
+```bash
+limps start
+# Error: limps daemon already running (PID 12345 on 127.0.0.1:4269). Run 'limps stop' first.
+```
+
+This is expected behavior — limps prevents multiple daemons on the same port using PID-based locking.
+
+**Resolution:**
+1. **Check all running daemons**: `limps status-server`
+2. **Stop the existing daemon**: `limps stop`
+3. **Or start on a different port**: `limps start --port 8080`
+
+### Debugging Connection Issues
+
+If MCP clients can't connect to the daemon, verify connectivity step by step:
+
+**1. Check daemon status:**
+
+```bash
+limps status-server
+# Should show daemon running with healthy status
+```
+
+**2. Verify health endpoint:**
+
+```bash
+curl http://127.0.0.1:4269/health
+# Should return JSON with status "ok"
+```
+
+**3. Verify MCP endpoint:**
+
+```bash
+curl -X POST http://127.0.0.1:4269/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'
+# Should return MCP initialize response
+```
+
+**4. Enable debug logging:**
+
+```bash
+DEBUG=1 limps start --foreground
+# Watch for connection attempts and errors
+```
+
+**5. Check MCP client config:**
+
+Ensure the URL in your client config matches the daemon:
+
+```json
+{
+  "mcpServers": {
+    "limps-planning-myproject": {
+      "transport": {
+        "type": "http",
+        "url": "http://127.0.0.1:4269/mcp"
+      }
+    }
+  }
+}
+```
+
 ## MCP Tools
 
 limps exposes MCP tools for AI assistants: