docs: expand developer documentation and configuration guides

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`

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`.