From 05bcbca6eef5984034f05c66c0135c024ecdd1e0 Mon Sep 17 00:00:00 2001
From: mamba <isaiahntina47@gmail.com>
Date: Sat, 31 Jan 2026 14:30:01 +0000
Subject: [PATCH] docs: expand developer documentation

---
 README.md                   |  19 +--
 docs/CONFIG.md              | 240 ++++++++++++++++++++++++++++++------
 docs/DATA.md                |  61 +++++++--
 docs/NOTION_INTERGRATION.md | 115 +++++++----------
 docs/RELEASE_NOTES.md       |   1 +
 docs/TOOLS.md               | 199 +++++++++++++++++++++++-------
 docs/TROUBLESHOOTING.md     |  75 ++++++++---
 7 files changed, 519 insertions(+), 191 deletions(-)

diff --git a/README.md b/README.md
index 6668fdf..5256074 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,15 @@
-# Context Sync
+# Context Sync
 
 Local-first memory layer for AI development tools via MCP.
 
 ![alt text](image.png)
 
-## Install and auto-config (60 seconds)
+## Why Context Sync?
+- **Local-first**: all data stays on your machine.
+- **Developer workflow**: built around projects, git activity, and structured context.
+- **Minimal tools**: 9 core tools focused on speed and clarity.
+
+## Install & auto-config (60 seconds)
 1) Install globally:
 ```bash
 npm install -g @context-sync/server
@@ -15,13 +20,12 @@ npm install -g @context-sync/server
 3) Verify tools:
 - Claude Desktop: Tools list
 - Cursor: Tools list
-- VS Code/Copilot: Copilot Chat -> Agent mode -> Tools
+- VS Code/Copilot: Copilot Chat → Agent mode → Tools
 - Continue.dev: open Continue panel
-- Codex CLI: codex mcp list
-- Claude Code: claude mcp list
+- Codex CLI: `codex mcp list`
+- Claude Code: `claude mcp list`
 
 If auto-config fails, see `docs/TROUBLESHOOTING.md` and `docs/CONFIG.md`.
-If you installed locally (non-global), auto-config does not run.
 
 ## Optional: Notion setup
 ```bash
@@ -70,9 +74,10 @@ When you run `set_project` inside a git repo, Context Sync installs hooks:
 
 Hooks are marked with "Context Sync Auto-Hook" and existing hooks are backed up.
 
-## Docs
+## Documentation
 - Release notes: `docs/RELEASE_NOTES.md`
 - Manual config: `docs/CONFIG.md`
 - Tools: `docs/TOOLS.md`
 - Troubleshooting: `docs/TROUBLESHOOTING.md`
 - Data and storage: `docs/DATA.md`
+- Notion integration: `docs/NOTION_INTERGRATION.md`
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
index c42cf8b..475ddc7 100644
--- a/docs/CONFIG.md
+++ b/docs/CONFIG.md
@@ -1,91 +1,259 @@
-**Manual Configuration**
-- Use this when auto-config fails or you prefer manual setup.
-- Restart the app/CLI after editing config files.
-- Server entry should point to the global install or use `npx -y @context-sync/server`.
+# Manual Configuration Guide
 
-**Server Entry (JSON)**
+This guide covers **manual MCP server configuration** for Context Sync. Use it when auto-config doesn't run or when you need a fully explicit setup.
+
+## When to use manual config
+- You installed locally (auto-config only runs for global installs).
+- Your AI client isn't supported by auto-config yet.
+- You prefer to maintain MCP configuration in source control (e.g., team onboarding docs).
+
+## Quick reference (server entries)
+You can run the server via a global install or via `npx`. Both work; choose the one that fits your environment.
+
+### Option A: `npx` (recommended for most users)
 ```json
 {
   "context-sync": {
-    "command": "node",
-    "args": ["/path/to/@context-sync/server/dist/index.js"],
+    "command": "npx",
+    "args": ["-y", "@context-sync/server"],
     "type": "stdio"
   }
 }
 ```
 
-**Server Entry (npx)**
+### Option B: global install (explicit Node path)
 ```json
 {
   "context-sync": {
-    "command": "npx",
-    "args": ["-y", "@context-sync/server"],
+    "command": "node",
+    "args": ["/path/to/@context-sync/server/dist/index.js"],
     "type": "stdio"
   }
 }
 ```
 
-**Claude Desktop**
+**Notes:**
+- `command` must be on PATH.
+- `args` must include an absolute path when using the `node` option.
+- The MCP transport is **stdio**.
+
+## Common fields
+| Field | Description |
+| --- | --- |
+| `command` | Executable to run (usually `npx` or `node`). |
+| `args` | CLI arguments for Context Sync. |
+| `type` | MCP transport type. Always `"stdio"`. |
+
+## Platform-specific configs
+Below are known configuration locations. Each example shows only the **MCP section** you need to add.
+
+### Claude Desktop
+**Path**
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 - Linux: `~/.config/Claude/claude_desktop_config.json`
-- Structure: `mcpServers` object.
 
-**Cursor**
+**Shape**
+```json
+{
+  "mcpServers": {
+    "context-sync": {
+      "command": "npx",
+      "args": ["-y", "@context-sync/server"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### Cursor
+**Path**
 - macOS/Linux: `~/.cursor/mcp.json`
 - Windows: `%USERPROFILE%\.cursor\mcp.json`
-- Structure: `mcpServers` object.
 
-**VS Code (GitHub Copilot)**
+**Shape**
+```json
+{
+  "mcpServers": {
+    "context-sync": {
+      "command": "npx",
+      "args": ["-y", "@context-sync/server"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+**Path**
 - macOS: `~/Library/Application Support/Code/User/mcp.json`
 - Windows: `%APPDATA%\Code\User\mcp.json`
 - Linux: `~/.config/Code/User/mcp.json`
-- Structure: `servers` object + `inputs` array.
 
-**Continue.dev**
+**Shape**
+```json
+{
+  "servers": {
+    "context-sync": {
+      "command": "npx",
+      "args": ["-y", "@context-sync/server"],
+      "type": "stdio"
+    }
+  },
+  "inputs": []
+}
+```
+
+### Continue.dev
+**Path**
 - Workspace: `./.continue/mcpServers/context-sync.yaml`
 - Global: `~/.continue/config.yaml`
-- Structure: server definition in YAML.
 
-**Zed**
+**Shape**
+```yaml
+mcpServers:
+  context-sync:
+    command: npx
+    args:
+      - -y
+      - @context-sync/server
+    type: stdio
+```
+
+### Zed
+**Path**
 - macOS: `~/Library/Application Support/Zed/settings.json`
 - Windows: `%APPDATA%\Zed\settings.json`
 - Linux: `~/.config/zed/settings.json`
-- Structure: `context_servers` object.
 
-**Windsurf**
+**Shape**
+```json
+{
+  "context_servers": {
+    "context-sync": {
+      "command": "npx",
+      "args": ["-y", "@context-sync/server"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### Windsurf
+**Path**
 - macOS: `~/.codeium/windsurf/mcp_config.json`
 - Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
 - Linux: `~/.codeium/windsurf/mcp_config.json`
-- Structure: `mcpServers` object.
 
-**Codeium**
+**Shape**
+```json
+{
+  "mcpServers": {
+    "context-sync": {
+      "command": "npx",
+      "args": ["-y", "@context-sync/server"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### Codeium
+**Path**
 - macOS: `~/Library/Application Support/Code/User/settings.json`
 - Windows: `%APPDATA%\Code\User\settings.json`
 - Linux: `~/.config/Code/User/settings.json`
-- Structure: `codeium.mcp` with `servers`.
 
-**TabNine**
+**Shape**
+```json
+{
+  "codeium.mcp": {
+    "servers": {
+      "context-sync": {
+        "command": "npx",
+        "args": ["-y", "@context-sync/server"],
+        "type": "stdio"
+      }
+    }
+  }
+}
+```
+
+### TabNine
+**Path**
 - macOS: `~/Library/Application Support/TabNine/config.json`
 - Windows: `%APPDATA%\TabNine\config.json`
 - Linux: `~/.config/TabNine/config.json`
-- Structure: `mcp.servers`.
 
-**Codex CLI**
-- Config: `~/.codex/config.toml`
-- Add:
+**Shape**
+```json
+{
+  "mcp": {
+    "servers": {
+      "context-sync": {
+        "command": "npx",
+        "args": ["-y", "@context-sync/server"],
+        "type": "stdio"
+      }
+    }
+  }
+}
+```
+
+### Codex CLI
+**Path**
+- `~/.codex/config.toml`
+
+**Shape**
 ```toml
 [mcp_servers.context-sync]
 command = "npx"
 args = ["-y", "@context-sync/server"]
 ```
 
-**Claude Code (Anthropic CLI)**
-- Config: `~/.claude/mcp_servers.json`
-- Structure: `mcpServers` object.
-- CLI option: `claude mcp add context-sync "npx" -y @context-sync/server`
+### Claude Code (Anthropic CLI)
+**Path**
+- `~/.claude/mcp_servers.json`
+
+**Shape**
+```json
+{
+  "mcpServers": {
+    "context-sync": {
+      "command": "npx",
+      "args": ["-y", "@context-sync/server"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+CLI shortcut:
+```bash
+claude mcp add context-sync "npx" -y @context-sync/server
+```
+
+### Antigravity (Google Gemini IDE)
+**Path**
+- `~/.gemini/antigravity/mcp_config.json`
+
+**Shape**
+```json
+{
+  "mcpServers": {
+    "context-sync": {
+      "command": "npx",
+      "args": ["-y", "@context-sync/server"],
+      "type": "stdio"
+    }
+  }
+}
+```
 
-**Antigravity (Google Gemini IDE)**
-- Config: `~/.gemini/antigravity/mcp_config.json`
-- Structure: `mcpServers` object.
+## Validation checklist
+- JSON/TOML/YAML syntax is valid.
+- The config file is saved to the correct location.
+- You restarted the AI client after editing config.
+- `npx` or `node` is available in PATH for the user running the AI client.
 
+If things still fail, see `docs/TROUBLESHOOTING.md`.
diff --git a/docs/DATA.md b/docs/DATA.md
index 602242e..c21fbfa 100644
--- a/docs/DATA.md
+++ b/docs/DATA.md
@@ -1,21 +1,56 @@
-**Data and Local Storage**
+# Data & Storage
 
-**Default paths**
+Context Sync is **local-first**. All state is stored in a local SQLite database and a small JSON config file.
+
+## Default paths
 - Database: `~/.context-sync/data.db`
 - Config: `~/.context-sync/config.json`
 - Install status: `~/.context-sync/install-status.json`
 
-**Custom database path**
-- CLI arg: `context-sync --db-path /absolute/path/to/db`
-- Env var: `CONTEXT_SYNC_DB_PATH=/absolute/path/to/db`
+## Custom database path
+Use a custom DB location if you need per-project isolation or if home directories are ephemeral.
+
+**CLI flag**
+```bash
+context-sync --db-path /absolute/path/to/db
+```
+
+**Environment variable**
+```bash
+CONTEXT_SYNC_DB_PATH=/absolute/path/to/db
+```
+
+## What is stored
+Context Sync stores structured project context, including:
+- Project identity (name, path, detected tech stack, purpose).
+- Context layers: active work, constraints, problems, goals, decisions, notes, caveats.
+- Conversation summaries for recall synthesis.
+- Git hook events (commit, push, merge, checkout) as decisions or active work.
+
+## Notion configuration
+`~/.context-sync/config.json` stores optional Notion settings:
+```json
+{
+  "notion": {
+    "token": "secret_or_ntn_token",
+    "defaultParentPageId": "optional-page-id"
+  }
+}
+```
+
+Only the token is required for search/read.
 
-**What is stored**
-- Projects and metadata
-- Context layers: active work, constraints, problems, goals, decisions, notes, caveats
-- Conversation summaries (for recall synthesis)
+## Backups and migrations
+On first run, Context Sync may migrate legacy data and create a backup file next to the DB.
+- Migrations are **safe** and **atomic**.
+- If migration fails, the original data is not modified.
 
-**Backups**
-- First run may migrate legacy data and create a backup file next to the DB.
+## Data deletion
+To remove all Context Sync data:
+```bash
+rm -rf ~/.context-sync/
+```
 
-**Delete all data**
-- Remove `~/.context-sync/` (this deletes DB and config).
+## Security notes
+- Data is stored locally and never sent to third parties by default.
+- Protect `~/.context-sync/config.json` because it can contain Notion tokens.
diff --git a/docs/NOTION_INTERGRATION.md b/docs/NOTION_INTERGRATION.md
index 1c1ca34..f821bef 100644
--- a/docs/NOTION_INTERGRATION.md
+++ b/docs/NOTION_INTERGRATION.md
@@ -1,92 +1,65 @@
 # Notion Integration Guide
 
-## Overview
-This guide shows you how to connect Context Sync directly to Notion using the official Notion API. You’ll be able to read and write Notion pages, search your workspace, and manage documentation—no separate MCP server required!
+Context Sync can connect directly to Notion using the official Notion API. The MCP tool exposes **search** and **read** actions once configured.
+
+## What you get
+- Search for pages in your workspace.
+- Read page content directly in your AI client.
+
+> Note: The public MCP tool currently supports **read-only** operations.
+
 ## Prerequisites
+- Node.js 16+
+- A Notion workspace
+- A Notion integration token
 
-- Node.js 16+ installed
-- A Notion account with workspace access
-- Notion API integration token
-## Step 1: Get Your Notion API Token
-   go to -> https://www.notion.so/profile/integrations
-1. **Create a Notion Integration:**
-  - Give it a name (e.g., "Context Sync")
-  - Select your workspace
-  - Click "Submit"
-2. **Share Pages access with Your Integration:**
-  - Click access under the newly created intergration.
+## Step 1: Create a Notion integration
+1. Visit https://www.notion.so/profile/integrations
+2. Click **New integration**
+3. Name it (e.g., “Context Sync”)
+4. Select your workspace and submit
 
-3. **Copy your Integration Secret**
-   - The secrete starts with ntn_ or secret_
-  
-## Step 2: Install Context Sync
+## Step 2: Share pages with the integration
+Open a page in Notion → **Share** → invite the integration. The integration can only access pages you share.
 
+## Step 3: Install Context Sync
 ```bash
 npm install -g @context-sync/server
 ```
-## Step 3: Run the Setup Wizard
 
-Just run:
+## Step 4: Run the setup wizard
 ```bash
 context-sync-setup
+# or
+npx context-sync-setup
 ```
-The wizard will prompt you for your Notion API token and handle the rest!
-## Step 4: Start Using Notion with Context Sync
+The wizard prompts for:
+- Integration token (`secret_` or `ntn_`)
+- Optional default parent page ID (future write workflows)
 
-You’re all set! Context Sync will connect directly to Notion using your API token. No extra server or config needed.
-## Step 5: Test the Integration
+This stores configuration in `~/.context-sync/config.json`.
 
-Try searching, reading, or creating pages in Notion using Context Sync’s tools and commands. If you run into any issues, check your API token and make sure the pages are shared with your integration.
-## Available Capabilities
+## Step 5: Use the Notion tool
+```json
+notion({ "action": "search", "query": "architecture" })
+notion({ "action": "read", "pageId": "<uuid>" })
+```
 
-Once configured, you can:
-- 🔍 Search all accessible Notion pages
-- 📖 Read full page content (including blocks and databases)
-- ✍️ Create new pages with rich content
-- 📝 Update existing page content
-- 🏗️ Add blocks (text, headings, lists, code, etc.)
-- 📊 Create and update database entries
-- 📁 Organize pages in hierarchies
-- 🏷️ Add tags and properties
-- 🔗 Create relationships between pages
-## Security Best Practices
+If you see “Notion is not configured,” rerun the setup wizard.
 
-1. **Token Management:**
-  - Keep your API token secure. Never commit it to version control.
-2. **Minimal Access:**
-  - Only share specific pages with the integration.
-3. **Regular Review:**
-  - Periodically check https://www.notion.so/my-integrations
-  - Revoke access to unused pages
 ## Troubleshooting
+**"Integration not found"**
+- Verify the token in `~/.context-sync/config.json`.
+- Confirm the integration exists at https://www.notion.so/my-integrations.
 
-### "Integration not found" Error
-- Verify the token is correct
-- Check the integration exists at notion.so/my-integrations
-
-### "Page not accessible" Error
-- Ensure the page is shared with your integration
-- Check workspace permissions
-
-### Server Won't Start
-```bash
-# Check Node version
-node --version  # Should be 16+
-```
-## Example Use Cases
-
-### 1. Documentation Management
-- "Create a troubleshooting guide in Notion for the authentication errors we discussed"
-- "Search my Notion for notes from the Q1 planning meeting"
-- "Update the API documentation page in Notion with the new endpoints we just created"
-- "Create a project roadmap page with milestones for Q2"
-## Context Sync Integration
+**"Page not accessible"**
+- Ensure the page is shared with your integration.
+- Check workspace permissions.
 
-Context Sync recognizes Notion as a platform and can sync, search, and update docs directly.
-- **Notion API:** https://developers.notion.com
-- **Context Sync:** https://github.com/Intina47/context-sync
-## Next Steps
+**"Failed to read page"**
+- Confirm the page ID is a valid UUID.
 
-1. ✅ Set up Notion integration token
-2. ✅ Share relevant pages with the integration
-3. 🚀 Start using Notion with Context Sync!
+## Security best practices
+- Keep tokens out of source control.
+- Limit access to specific pages.
+- Revoke unused integrations regularly.
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
index de35315..e6babf0 100644
--- a/docs/RELEASE_NOTES.md
+++ b/docs/RELEASE_NOTES.md
@@ -7,6 +7,7 @@ This release is a major v2-focused cleanup. It removes legacy v1 tooling and nar
 - Notion-only setup wizard with clearer prompts and retry flow.
 - Post-install status tracking with manual-config fallback when auto-config fails.
 - Setup wizard now summarizes auto-configured platforms and any install issues.
+- Expanded developer documentation with deeper configuration, tooling, and troubleshooting details.
 
 ## Breaking changes
 - Removed v1-only tools (todos, platform sync, call graph, type analysis, dependency analysis, file write/preview tools, performance monitor, migration prompter, and related modules).
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
index 9c335fd..ba9a675 100644
--- a/docs/TOOLS.md
+++ b/docs/TOOLS.md
@@ -1,45 +1,156 @@
-**Core Tools**
-- `set_project`: Initialize a project for context tracking (run this first).
-- `remember`: Store context (active work, constraints, problems, goals, decisions, notes, caveats).
-- `recall`: Retrieve context for the current project.
-- `read_file`: Read a file with rich context.
-- `search`: Search for files or content.
-- `structure`: Summarize project structure.
-- `git`: Git status, context, hotspots, coupling, blame, analysis.
-- `notion`: Read-only Notion access (`search`, `read`).
-
-**Minimal Workflow**
-```text
-1) set_project({ path: "/abs/path/to/project" })
-2) recall()
-3) read_file({ path: "src/index.ts" })
-4) remember({ type: "decision", content: "Use SQLite for local storage" })
-```
-
-**Important**
-- Always call `set_project` before using other tools.
-
-**Remember Types**
-- `active_work`: Current task and context.
-- `constraint`: Architectural or process rules.
-- `problem`: Blockers or issues.
-- `goal`: Targets or milestones.
-- `decision`: Key decisions and rationale.
-- `note`: General information.
-- `caveat`: Mistakes, shortcuts, unverified work.
-
-**Git Actions**
-```text
-git({ action: "status" })
-git({ action: "context" })
-git({ action: "hotspots" })
-git({ action: "coupling" })
-git({ action: "blame", path: "src/server.ts" })
-git({ action: "analysis" })
-```
-
-**Notion Actions**
-```text
-notion({ action: "search", query: "architecture" })
-notion({ action: "read", pageId: "..." })
+# Context Sync Tools (MCP)
+
+Context Sync exposes **9 core tools** over MCP. These tools are intentionally minimal and designed for daily developer workflows.
+
+## Required tool flow
+1. `set_project` (must be first)
+2. `recall` (restore context)
+3. `structure` / `search` / `read_file` (explore code)
+4. `remember` (store decisions, constraints, problems, etc.)
+
+If you see **"No workspace set"**, call `set_project` again.
+
+## Tool catalog
+| Tool | Purpose | Required args |
+| --- | --- | --- |
+| `set_project` | Initialize a project and capture tech stack/metadata. | `path` |
+| `remember` | Store context (active work, constraints, problems, goals, decisions, notes, caveats). | `type`, `content` |
+| `recall` | Retrieve project context (active work, constraints, decisions, etc.). | _none_ |
+| `read_file` | Read a file from the current workspace. | `path` |
+| `search` | Search by file name or file contents. | `query`, `type` |
+| `structure` | Summarize project structure. | _none_ |
+| `git` | Git status, context, hotspots, coupling, blame, analysis. | `action` |
+| `notion` | Read-only Notion access. | `action` |
+
+## `set_project`
+Initialize the workspace. This detects the tech stack and prepares internal caches.
+
+```json
+set_project({
+  "path": "/absolute/path/to/project",
+  "purpose": "Optional: what this project does"
+})
+```
+
+**Tips**
+- Always use absolute paths.
+- Calling `set_project` on a new path switches the current project.
+
+## `remember`
+Store important, durable context. Use it for anything that should survive sessions.
+
+```json
+remember({
+  "type": "decision",
+  "content": "Use SQLite for local storage",
+  "metadata": { "files": ["src/storage.ts"] }
+})
+```
+
+**Types**
+- `active_work` – current task and status
+- `constraint` – architectural rules or policies
+- `problem` – blockers or bugs
+- `goal` – outcomes and milestones
+- `decision` – key decisions with rationale
+- `note` – general info
+- `caveat` – AI mistakes, shortcuts, or unverified work
+
+### Caveats (important)
+When using `type: "caveat"`, include metadata:
+```json
+{
+  "category": "unverified",
+  "severity": "medium",
+  "attempted": "Updated git actions",
+  "error": "Schema validation failed",
+  "recovery": "Created manual test script",
+  "verified": true,
+  "action_required": "Restart MCP server",
+  "affects_production": true
+}
+```
+
+## `recall`
+Retrieve context for the current project.
+```json
+recall({ "query": "what were we working on?" })
+```
+
+Optional parameters:
+- `query` – focus the response.
+- `limit` – how many recent items per category (default 10).
+
+## `read_file`
+Read a file relative to the workspace root.
+```json
+read_file({ "path": "src/index.ts" })
 ```
+
+## `search`
+Search by file name or contents.
+```json
+search({ "query": "ContextSyncServer", "type": "content" })
+```
+
+Optional search options:
+```json
+{
+  "regex": true,
+  "caseSensitive": false,
+  "filePattern": "src/**/*.ts",
+  "maxResults": 50
+}
+```
+
+## `structure`
+Return a simplified file tree (default depth 3).
+```json
+structure({ "depth": 2 })
+```
+
+## `git`
+One tool, multiple actions:
+```json
+git({ "action": "status" })
+```
+
+### Available actions
+- `status` – working tree summary and change impact.
+- `context` – commit context + suggested commit messages.
+- `hotspots` – files with high change frequency.
+- `coupling` – files that change together.
+- `blame` – code ownership for a path.
+- `analysis` – consolidated health overview.
+
+### Examples
+```json
+git({ "action": "blame", "path": "src/server.ts" })
+```
+```json
+git({ "action": "hotspots", "limit": 5 })
+```
+
+## `notion`
+Read-only access to your Notion workspace. Requires the setup wizard.
+```json
+notion({ "action": "search", "query": "architecture" })
+notion({ "action": "read", "pageId": "<uuid>" })
+```
+
+If Notion is not configured, the tool returns an error with setup instructions.
+
+## Prompts & resources (MCP extras)
+Context Sync also exposes MCP prompts/resources (useful for building agents):
+- `context-sync-usage` prompt
+- `debugging-context-sync` prompt
+- `context-sync://docs/usage-guide`
+- `context-sync://docs/debugging-guide`
+- `context-sync://docs/tool-flow`
+
+## Common errors
+| Error | Likely cause | Fix |
+| --- | --- | --- |
+| `No workspace set` | `set_project` wasn’t called | Run `set_project` with an absolute path. |
+| `Not a git repository` | Path isn't in a Git repo | Run `set_project` inside a repo or skip git tools. |
+| `Notion is not configured` | Setup not run | Run `context-sync-setup` and add your token. |
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index e814499..1da46e9 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -1,16 +1,25 @@
-**Troubleshooting**
+# Troubleshooting
 
+This guide targets common developer issues when running Context Sync under MCP.
+
+## Quick diagnostics
+1. Confirm the server entry exists and is valid JSON/TOML/YAML.
+2. Restart the AI client (most clients only load MCP servers on startup).
+3. Verify the server can run from a terminal: `npx -y @context-sync/server`.
+4. Check the install status: `~/.context-sync/install-status.json`.
+
+## Installation & auto-config
 **Auto-config did not run**
-- Auto-config runs only on global install.
+- Auto-config runs only on global installs.
 - Fix: `npm install -g @context-sync/server`
-- Check status file: `~/.context-sync/install-status.json`
-  - If `needsManual` is true, use `docs/CONFIG.md`.
+- If `~/.context-sync/install-status.json` shows `needsManual: true`, follow `docs/CONFIG.md`.
 
-**Tools do not show in your AI app**
+**Tools do not show up in your AI client**
 - Restart the app/CLI after install.
-- Verify the MCP config file exists (see `docs/CONFIG.md`).
-- Check for a `context-sync` entry in the config.
+- Verify the MCP config file exists and contains `context-sync`.
+- Ensure `command` is on PATH for the user running the AI client.
 
+## Client-specific checks
 **Codex CLI**
 - Verify: `codex mcp list`
 - Config: `~/.codex/config.toml`
@@ -19,23 +28,49 @@
 - Verify: `claude mcp list`
 - Config: `~/.claude/mcp_servers.json`
 
-**Notion says "not configured"**
-- Run: `context-sync-setup` (or `npx context-sync-setup`)
-- Ensure the integration token is valid (`secret_` or `ntn_` prefix).
+## Core tool errors
+**"No workspace set"**
+- Cause: Calling tools before `set_project`.
+- Fix: `set_project({ path: "/absolute/path" })`
+
+**"Not a git repository"**
+- Cause: The current workspace isn’t a Git repo.
+- Fix: Run `set_project` inside a Git repo or skip git actions.
+
+**"No such table" or DB errors**
+- Cause: Corrupt or old database.
+- Fix: Move `~/.context-sync/data.db` aside and re-run the server to rebuild.
 
-**Notion returns no pages**
-- Share a Notion page with the integration.
-- Retry the wizard or run Notion search again.
+## Notion errors
+**"Notion is not configured"**
+- Run: `context-sync-setup` (or `npx context-sync-setup`).
+- Confirm the token starts with `secret_` or `ntn_`.
 
-**Auto-config created a file but app still cannot see tools**
-- Ensure config file is valid JSON/TOML/YAML.
-- Restart the app completely.
+**"Failed to read page"**
+- Ensure the page ID is a valid UUID.
+- Share the page with your Notion integration.
 
-**Git hooks not installed**
+**Search returns no pages**
+- Verify the integration has access to the workspace/page.
+- Try a broader search query.
+
+## Git hooks
+**Hooks not installed**
 - Hooks are installed during `set_project` if the repo has `.git`.
-- Re-run `set_project`.
+- Re-run `set_project` in the repo root.
 - Check `.git/hooks` for files containing "Context Sync Auto-Hook".
 
-**Migration messages on startup**
+**Hooks installed but no events captured**
+- Ensure the DB path is valid and writable.
+- Confirm hooks are executable (`chmod +x .git/hooks/post-commit`).
+
+## Migration messages on startup
 - First run may migrate legacy data and create a backup.
-- If the migration fails, your data is not modified; see console output for backup path.
+- If migration fails, your data is not modified; check console output for the backup path.
+
+## Still stuck?
+- Run the server directly to see stderr logs:
+```bash
+npx -y @context-sync/server
+```
+- Include the exact error output when reporting issues.