@imenam/mcp-documentor 1.0.74 → 1.0.76

package/README.md

@@ -1,259 +1,271 @@
-# @imenam/mcp-documentor
-
-An MCP server to create, manage, and search project documentation — with staleness tracking and optional semantic search.
-
-Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI document, browse and verify your codebase docs without leaving the chat.
-
-## Features
-
-- **Create & update docs** — write markdown documentation entries linked to source files; prefer partial edits via `patch_doc`
-- **Staleness tracking** — automatically detects when tracked files have changed since the last doc update
-- **Portable code references** — tracked-file paths are stored relative to a configurable code root (`MCP_DOCUMENTOR_CODE_ROOT`), so synced docs resolve their source files on any machine regardless of where the repos live
-- **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
-- **Multi-project support** — organize docs into separate projects; MCP tools work across projects; `set_project` only changes what the GUI shows
-- **GUI** — built-in web interface when a proxy is configured (`PROXY_URL`); without it, the GUI worker is not started
-- **Proxy-aware** — integrates with the [proxy-setup](https://github.com/Imena/proxy-setup) for GUI exposure
-- **Links & structure** — `check_links`, `get_doc_tree`, `move_doc`, and `git_diff_doc` for maintenance workflows
-- **Image support** — upload images to a project's assets via `upload_image` (local file path) or directly from the GUI editor; images are stored per-project and rendered inline in the viewer and in PDF exports
-- **GitHub sync** — share your documentation across machines by backing the data directory with a private GitHub repo; the repo/token are fixed by the administrator via environment variables, and the agent can only `pull_docs` / `push_docs` / `sync_docs`
-
-## Installation
-
-```bash
-npx -y @imenam/mcp-documentor
-```
-
-Or install globally:
-
-```bash
-npm install -g @imenam/mcp-documentor
-```
-
-Global install exposes:
-
-- `mcp-documentor` — MCP server
-- `mcp-documentor-migrate` — CLI helper for migrating inline doc links (see `scripts/migrate-links.js`)
-- `mcp-documentor-migrate-paths` — one-shot migration of tracked-file paths from absolute to code-root-relative (see [Portable tracked-file paths](#portable-tracked-file-paths))
-
-## MCP Configuration
-
-### Quick setup
-
-From the repo you want to document, generate a ready-to-fill `.mcp.json` in the current directory:
-
-```bash
-npx @imenam/mcp-documentor --claude-setup-mcp
-```
-
-It creates the `mcp-documentor` entry with the usual environment variables as empty placeholders —
-an empty variable is simply inactive, so the generated config runs as-is and you only fill in what
-you need. An existing `.mcp.json` is merged, other servers are preserved, and an existing
-`mcp-documentor` entry is only replaced when `--force` is passed.
-
-### Manual setup
-
-Add to your MCP client config (e.g. Cursor `mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "mcp-documentor": {
-      "command": "npx",
-      "args": ["-y", "@imenam/mcp-documentor"],
-      "env": {
-        "OPENAI_API_KEY": "sk-..."
-      }
-    }
-  }
-}
-```
-
-### Environment Variables
-
-| Variable | Required | Description |
-|---|---|---|
-| `OPENAI_API_KEY` | No | Enables semantic search via OpenAI embeddings (`search_docs`) |
-| `MCP_DOCUMENTOR_OPENAI_MODEL` | No | Embedding model (default: `text-embedding-3-small`) |
-| `PROXY_URL` | No | URL of the proxy server to register and launch the GUI |
-| `APP_GROUP` | No | Groups the app under a collapsible section (folded by default) in the proxy dashboard. Apps sharing the same value appear together; if unset, the app lands in the default "ungrouped" section |
-| `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
-| `MCP_LOG_DIR` | No | Overrides the log directory of both the server and the GUI worker (default: `<package>/.docs-data/logs`). Must be set in the MCP client config — the package `.env` is loaded after the logger starts |
-| `MCP_DOCUMENTOR_CODE_ROOT` | No | Base directory that tracked-file paths are stored relative to, keeping docs portable across machines (see [Portable tracked-file paths](#portable-tracked-file-paths)) |
-| `MCP_DOCUMENTOR_CODE_ROOTS` | No | JSON map of per-project code-root overrides, e.g. `{"my-proj":"/srv/my-proj"}` |
-| `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
-| `MCP_DOCUMENTOR_SYNC_REMOTE` | No | HTTPS URL of the private GitHub repo to sync with; enables GitHub sync when set |
-| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch of the documentation sync repo to push/pull docs on (default: `main`) |
-| `MCP_DOCUMENTOR_SYNC_TOKEN` | No | Fine-grained GitHub PAT used for HTTPS auth (see GitHub sync) |
-| `SYNC_PULL_ON_START` | No | Set to `false` to disable the automatic pull at server startup |
-
-Optional `.env` at the package root (directory containing `package.json` discovered from the installed binary) is loaded when present.
-
-## Available Tools
-
-Every tool that targets a specific documentation entry takes a **mandatory `project`**. It is never
-guessed and never falls back to the active project: resolving a doc path across projects is what
-made operations silently hit the wrong project when the same path existed in several. Tools that
-work on a whole project (`list_docs`, `get_doc_tree`, `check_links`, `check_freshness` without a
-`path`, `reindex_embeddings`) keep `project` optional, since omitting it means "all projects".
-
-| Tool | Description |
-|---|---|
-| `create_doc` | Create a new documentation entry linked to source files (`project` required) |
-| `get_doc` | Retrieve a documentation entry with full content (`project` required) |
-| `get_doc_metadata` | Get metadata and freshness status without loading content (`project` required) |
-| `list_docs` | List docs with staleness indicators (optionally filter by project) |
-| `get_doc_tree` | Return folder/doc structure for a project (or all projects) |
-| `update_doc` | Fully replace content and/or metadata (`project` required; prefer `patch_doc` for small edits) |
-| `patch_doc` | Search-and-replace a fragment of a doc’s content (`project` required) |
-| `move_doc` | Change a doc’s path (folder/name) within its project (`project` required) |
-| `delete_doc` | Permanently delete a documentation entry (`project` required) |
-| `search_docs` | Semantic search over docs (natural language; requires OpenAI) |
-| `check_freshness` | Staleness for one doc (`project` required) or a full project scan |
-| `refresh_file_snapshot` | Mark tracked files as up-to-date without editing the doc (`project` required) |
-| `git_diff_doc` | Git diff for tracked files vs snapshot baseline (`project` required) |
-| `check_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors |
-| `list_projects` | List all documentation projects |
-| `set_project` | Switch the active project **for the GUI only** (not for MCP tools) |
-| `upload_image` | Upload an image from a local file path to a project's assets (`project` required); returns the markdown link to insert |
-| `sync_status` | Show branch, ahead/behind counts, conflicted files, and uncommitted changes |
-| `pull_docs` | Pull updates from the remote (defensive fast-forward; reindexes new docs) |
-| `push_docs` | Commit local doc changes and push them to the remote |
-| `sync_docs` | Full sync: pull then push (push skipped if the pull reveals a conflict) |
-| `resolve_sync_conflict` | Bulk-resolve merge conflicts by keeping `mine` or `theirs`, then stage |
-
-## Images in documents
-
-Images can be embedded in any documentation entry using standard markdown syntax:
-
-```markdown
-![alt text](/api/images/my-project/screenshot.png)   <!-- local upload -->
-![alt text](https://example.com/diagram.png)          <!-- external URL -->
-```
-
-**Via the MCP tool** — use `upload_image` with the absolute path of the file on the server:
-
-```json
-{
-  "filename": "screenshot.png",
-  "filePath": "/absolute/path/to/screenshot.png",
-  "alt": "Architecture diagram"
-}
-```
-
-The tool copies the file into `.docs-data/projects/{project}/assets/` and returns the ready-to-use markdown snippet.
-
-**Via the GUI editor** — click the **🖼 Image** button in the editor toolbar to open the image panel:
-- **Upload tab** — pick a local file; it is uploaded automatically and the markdown link is inserted at the cursor position
-- **URL tab** — paste any external image URL; the markdown link is inserted at the cursor position
-- **Project images gallery** — click any previously uploaded image to re-insert it
-
-## Syncing across machines with GitHub
-
-You can share documentation between several machines by backing the data directory with a **private** GitHub repository. The approach is git-based: only the human-readable markdown, assets, and the shared project list are versioned. Derived state (embeddings) is regenerated locally, and version history stays local to each machine.
-
-### What is and isn't synced
-
-| Synced (versioned) | Local only (gitignored) |
-|---|---|
-| `projects/**` (markdown + assets) | `embeddings.db` (regenerated after pull) |
-| `config.json` (project list) | `history.db` (per-machine version history) |
-| | `local-state.json` (active project) |
-
-### Setup
-
-The sync target is **administrator-controlled**: the repository, branch and token are read from environment variables and **cannot be set or changed by the agent**. The agent can only pull/push against whatever repo you configured.
-
-1. Create an **empty private repo** on GitHub (e.g. `my-docs`).
-2. Create a **fine-grained PAT** scoped to that single repo (Repository permissions → **Contents: Read and write**).
-3. Add the sync environment variables to your MCP client config, per machine:
-
-```jsonc
-{
-  "mcpServers": {
-    "mcp-documentor": {
-      "command": "npx",
-      "args": ["-y", "@imenam/mcp-documentor"],
-      "env": {
-        "MCP_DOCUMENTOR_SYNC_REMOTE": "https://github.com/<you>/my-docs.git",
-        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // branch of the docs sync repo, optional, defaults to "main"
-        "MCP_DOCUMENTOR_SYNC_TOKEN": "github_pat_..."
-      }
-    }
-  }
-}
-```
-
-The token is injected into the `origin` URL inside `.git/config` only (which git never commits) — it is never pushed.
-
-### Daily workflow
-
-- `sync_docs` — pull then push in one step (recommended).
-- `pull_docs` / `push_docs` — granular control.
-- `sync_status` — inspect ahead/behind, conflicts, and uncommitted changes.
-
-By default the server also performs a **defensive pull at startup**: it only fast-forwards a clean working tree and never overwrites local changes (disable with `SYNC_PULL_ON_START=false`). On the first run, a machine with no local data simply clones the remote.
-
-### Conflicts
-
-Because docs are plain markdown, merge conflicts are readable. When `pull_docs` reports a conflict:
-
-- edit the conflicted `.md` files directly (remove the `<<<<<<<` / `>>>>>>>` markers), **or**
-- run `resolve_sync_conflict` with `strategy: "mine"` or `"theirs"` to take one side in bulk,
-
-then run `push_docs` to publish the resolution. If you have **uncommitted** local changes while the remote has moved, the pull reports `diverged` without touching anything — push your changes first, then pull again.
-
-> Read-only machines (`READ_ONLY=1`) can still `pull_docs` and `sync_status`, but `push_docs`, `sync_docs`, and `resolve_sync_conflict` are disabled.
-
-## Portable tracked-file paths
-
-When docs are synced across machines, absolute tracked-file paths break: the codebase rarely lives at the same absolute location everywhere. To stay portable, tracked-file paths are stored **relative to a configurable code root** and resolved back to absolute paths on demand.
-
-Agents keep passing **absolute** paths to `create_doc` / `update_doc` (and in `[copy-from-codebase|…]` tags) as usual — the conversion to a stored relative path happens automatically server-side. No change in how the agent works.
-
-### Configuration
-
-Set the code root per machine (it is machine-local, so it lives in the environment, never in the synced data):
-
-```jsonc
-{
-  "env": {
-    "MCP_DOCUMENTOR_CODE_ROOT": "/home/you/code/repos",
-    // optional per-project overrides when repos don't share a common parent:
-    "MCP_DOCUMENTOR_CODE_ROOTS": "{\"my-proj\":\"/srv/my-proj\"}"
-  }
-}
-```
-
-Resolution precedence: `MCP_DOCUMENTOR_CODE_ROOTS[project]` → `MCP_DOCUMENTOR_CODE_ROOT` → none.
-
-| Stored path | On read |
-|---|---|
-| Relative + code root configured | resolved against the root |
-| Relative + **no** root on this machine | reported as `unverifiable` (source absent) instead of a false `stale` |
-| Absolute (legacy, or file outside the root) | used as-is |
-
-The feature is **opt-in**: with no code root configured, behaviour is unchanged (paths stored and resolved as absolute).
-
-### Migrating existing docs
-
-Docs created before this feature store absolute paths. Convert them in one shot with the bundled `mcp-documentor-migrate-paths`:
-
-```bash
-MCP_DOCUMENTOR_CODE_ROOT="/home/you/code/repos" \
-MCP_DATA_DIR="/path/to/your/data" \
-  npx -p @imenam/mcp-documentor mcp-documentor-migrate-paths --dry-run
-```
-
-Review the report (`converted` / `kept absolute (outside root)` / `projects skipped`), then re-run without `--dry-run`. Finally publish with `sync_docs` (never commit the data dir by hand). The data dir is resolved like the server: `--data-dir` flag → `MCP_DATA_DIR` → package-relative fallback.
-
-This is a **one-time** operation, and must run on the machine whose OS/filesystem **created** the stored absolute paths (path semantics differ between Windows and POSIX). Once migrated and synced, every other machine just `pull_docs` and sets its own `MCP_DOCUMENTOR_CODE_ROOT` — no migration needed.
-
-## Data Storage
-
-By default, data lives under **`.docs-data`** next to the resolved package root (the folder that contains `package.json` for the running install). Set **`MCP_DATA_DIR`** to use another directory. Contents include projects, SQLite/embeddings, and logs under `.docs-data/logs`. This tree is **not** part of the npm package; it is created at runtime.
-
-The active project is a machine-local preference kept in `local-state.json` (gitignored), separate from the shared `config.json`. On first run, a legacy `currentProject` stored in `config.json` is migrated automatically. GitHub sync settings live in environment variables, not on disk.
-
-## License
-
-ISC
+# @imenam/mcp-documentor
+
+An MCP server to create, manage, and search project documentation — with staleness tracking and optional semantic search.
+
+Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI document, browse and verify your codebase docs without leaving the chat.
+
+## Features
+
+- **Create & update docs** — write markdown documentation entries linked to source files; prefer partial edits via `patch_doc`
+- **Staleness tracking** — automatically detects when tracked files have changed since the last doc update
+- **Portable code references** — tracked-file paths are stored relative to a configurable code root (`MCP_DOCUMENTOR_CODE_ROOT`), so synced docs resolve their source files on any machine regardless of where the repos live
+- **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
+- **Multi-project support** — organize docs into separate projects; every MCP tool names the project it targets, and the GUI's project selector is a per-browser view preference
+- **GUI** — built-in web interface, either behind the proxy (`PROXY_URL`) or served directly on a local port (`APP_PORT`); with neither, the GUI worker is not started
+- **Proxy-aware** — integrates with the [proxy-setup](https://github.com/Imena/proxy-setup) for GUI exposure
+- **Links & structure** — `check_links`, `get_doc_tree`, `move_doc`, and `git_diff_doc` for maintenance workflows
+- **Image support** — upload images to a project's assets via `upload_image` (local file path) or directly from the GUI editor; images are stored per-project and rendered inline in the viewer and in PDF exports
+- **GitHub sync** — share your documentation across machines by backing the data directory with a private GitHub repo; the repo/token are fixed by the administrator via environment variables, and the agent can only `pull_docs` / `push_docs` / `sync_docs`
+
+## Installation
+
+```bash
+npx -y @imenam/mcp-documentor
+```
+
+Or install globally:
+
+```bash
+npm install -g @imenam/mcp-documentor
+```
+
+Global install exposes:
+
+- `mcp-documentor` — MCP server
+- `mcp-documentor-migrate` — CLI helper for migrating inline doc links (see `scripts/migrate-links.js`)
+- `mcp-documentor-migrate-paths` — one-shot migration of tracked-file paths from absolute to code-root-relative (see [Portable tracked-file paths](#portable-tracked-file-paths))
+
+## MCP Configuration
+
+### Quick setup
+
+From the repo you want to document, generate a ready-to-fill `.mcp.json` in the current directory:
+
+```bash
+npx @imenam/mcp-documentor --claude-setup-mcp
+```
+
+It creates the `mcp-documentor` entry with the usual environment variables as empty placeholders —
+an empty variable is simply inactive, so the generated config runs as-is and you only fill in what
+you need. An existing `.mcp.json` is merged, other servers are preserved, and an existing
+`mcp-documentor` entry is only replaced when `--force` is passed.
+
+Two flags let you pick how the GUI is exposed straight from the command line, instead of editing
+the JSON afterwards:
+
+```bash
+# GUI behind the central proxy
+npx @imenam/mcp-documentor --claude-setup-mcp --proxy_url=http://localhost:3000
+
+# GUI served directly, no proxy: http://localhost:4500
+npx @imenam/mcp-documentor --claude-setup-mcp --app_port=4500
+```
+
+The two flags are mutually exclusive — passing both fails.
+
+### Manual setup
+
+Add to your MCP client config (e.g. Cursor `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-documentor": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-documentor"],
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `OPENAI_API_KEY` | No | Enables semantic search via OpenAI embeddings (`search_docs`) |
+| `MCP_DOCUMENTOR_OPENAI_MODEL` | No | Embedding model (default: `text-embedding-3-small`) |
+| `PROXY_URL` | No | URL of the proxy server: it allocates the port and mounts the GUI under `APP_PATH` |
+| `APP_PORT` | No | Local port used **when `PROXY_URL` is unset**: the GUI is served directly at `http://localhost:<port>`, at the root. Lets you use the interface without the central hub. `PROXY_URL` wins if both are set; with neither, the GUI is disabled and the MCP tools still work |
+| `APP_GROUP` | No | Groups the app under a collapsible section (folded by default) in the proxy dashboard. Apps sharing the same value appear together; if unset, the app lands in the default "ungrouped" section |
+| `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
+| `MCP_LOG_DIR` | No | Overrides the log directory of both the server and the GUI worker (default: `<package>/.docs-data/logs`). Must be set in the MCP client config — the package `.env` is loaded after the logger starts |
+| `MCP_DOCUMENTOR_CODE_ROOT` | No | Base directory that tracked-file paths are stored relative to, keeping docs portable across machines (see [Portable tracked-file paths](#portable-tracked-file-paths)) |
+| `MCP_DOCUMENTOR_CODE_ROOTS` | No | JSON map of per-project code-root overrides, e.g. `{"my-proj":"/srv/my-proj"}` |
+| `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
+| `MCP_DOCUMENTOR_SYNC_REMOTE` | No | HTTPS URL of the private GitHub repo to sync with; enables GitHub sync when set |
+| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch of the documentation sync repo to push/pull docs on (default: `main`) |
+| `MCP_DOCUMENTOR_SYNC_TOKEN` | No | Fine-grained GitHub PAT used for HTTPS auth (see GitHub sync) |
+| `SYNC_PULL_ON_START` | No | Set to `false` to disable the automatic pull at server startup |
+
+Optional `.env` at the package root (directory containing `package.json` discovered from the installed binary) is loaded when present.
+
+## Available Tools
+
+Every tool that targets a specific documentation entry takes a **mandatory `project`**. It is never
+guessed and there is no "active project" to fall back to: resolving a doc path across projects is
+what made operations silently hit the wrong project when the same path existed in several. Tools
+that work on a whole project (`list_docs`, `get_doc_tree`, `check_freshness` without a `path`,
+`reindex_embeddings`) keep `project` optional, since omitting it means "all projects".
+
+| Tool | Description |
+|---|---|
+| `create_doc` | Create a new documentation entry linked to source files (`project` required) |
+| `get_doc` | Retrieve a documentation entry with full content (`project` required) |
+| `get_doc_metadata` | Get metadata and freshness status without loading content (`project` required) |
+| `list_docs` | List docs with staleness indicators (optionally filter by project) |
+| `get_doc_tree` | Return folder/doc structure for a project (or all projects) |
+| `update_doc` | Fully replace content and/or metadata (`project` required; prefer `patch_doc` for small edits) |
+| `patch_doc` | Search-and-replace a fragment of a doc’s content (`project` required) |
+| `move_doc` | Change a doc’s path (folder/name) within its project (`project` required) |
+| `delete_doc` | Permanently delete a documentation entry (`project` required) |
+| `search_docs` | Semantic search over docs (natural language; requires OpenAI) |
+| `check_freshness` | Staleness for one doc (`project` required) or a full project scan |
+| `refresh_file_snapshot` | Mark tracked files as up-to-date without editing the doc (`project` required) |
+| `git_diff_doc` | Git diff for tracked files vs snapshot baseline (`project` required) |
+| `check_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors (`project` required) |
+| `list_projects` | List all documentation projects |
+| `upload_image` | Upload an image from a local file path to a project's assets (`project` required); returns the markdown link to insert |
+| `sync_status` | Show branch, ahead/behind counts, conflicted files, and uncommitted changes |
+| `pull_docs` | Pull updates from the remote (defensive fast-forward; reindexes new docs) |
+| `push_docs` | Commit local doc changes and push them to the remote |
+| `sync_docs` | Full sync: pull then push (push skipped if the pull reveals a conflict) |
+| `resolve_sync_conflict` | Bulk-resolve merge conflicts by keeping `mine` or `theirs`, then stage |
+
+## Images in documents
+
+Images can be embedded in any documentation entry using standard markdown syntax:
+
+```markdown
+![alt text](/api/images/my-project/screenshot.png)   <!-- local upload -->
+![alt text](https://example.com/diagram.png)          <!-- external URL -->
+```
+
+**Via the MCP tool** — use `upload_image` with the absolute path of the file on the server:
+
+```json
+{
+  "filename": "screenshot.png",
+  "filePath": "/absolute/path/to/screenshot.png",
+  "alt": "Architecture diagram"
+}
+```
+
+The tool copies the file into `.docs-data/projects/{project}/assets/` and returns the ready-to-use markdown snippet.
+
+**Via the GUI editor** — click the **🖼 Image** button in the editor toolbar to open the image panel:
+- **Upload tab** — pick a local file; it is uploaded automatically and the markdown link is inserted at the cursor position
+- **URL tab** — paste any external image URL; the markdown link is inserted at the cursor position
+- **Project images gallery** — click any previously uploaded image to re-insert it
+
+## Syncing across machines with GitHub
+
+You can share documentation between several machines by backing the data directory with a **private** GitHub repository. The approach is git-based: only the human-readable markdown, assets, and the shared project list are versioned. Derived state (embeddings) is regenerated locally, and version history stays local to each machine.
+
+### What is and isn't synced
+
+| Synced (versioned) | Local only (gitignored) |
+|---|---|
+| `projects/**` (markdown + assets) | `embeddings.db` (regenerated after pull) |
+| `config.json` (project list) | `history.db` (per-machine version history) |
+
+### Setup
+
+The sync target is **administrator-controlled**: the repository, branch and token are read from environment variables and **cannot be set or changed by the agent**. The agent can only pull/push against whatever repo you configured.
+
+1. Create an **empty private repo** on GitHub (e.g. `my-docs`).
+2. Create a **fine-grained PAT** scoped to that single repo (Repository permissions → **Contents: Read and write**).
+3. Add the sync environment variables to your MCP client config, per machine:
+
+```jsonc
+{
+  "mcpServers": {
+    "mcp-documentor": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-documentor"],
+      "env": {
+        "MCP_DOCUMENTOR_SYNC_REMOTE": "https://github.com/<you>/my-docs.git",
+        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // branch of the docs sync repo, optional, defaults to "main"
+        "MCP_DOCUMENTOR_SYNC_TOKEN": "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+The token is injected into the `origin` URL inside `.git/config` only (which git never commits) — it is never pushed.
+
+### Daily workflow
+
+- `sync_docs` — pull then push in one step (recommended).
+- `pull_docs` / `push_docs` — granular control.
+- `sync_status` — inspect ahead/behind, conflicts, and uncommitted changes.
+
+By default the server also performs a **defensive pull at startup**: it only fast-forwards a clean working tree and never overwrites local changes (disable with `SYNC_PULL_ON_START=false`). On the first run, a machine with no local data simply clones the remote.
+
+### Conflicts
+
+Because docs are plain markdown, merge conflicts are readable. When `pull_docs` reports a conflict:
+
+- edit the conflicted `.md` files directly (remove the `<<<<<<<` / `>>>>>>>` markers), **or**
+- run `resolve_sync_conflict` with `strategy: "mine"` or `"theirs"` to take one side in bulk,
+
+then run `push_docs` to publish the resolution. If you have **uncommitted** local changes while the remote has moved, the pull reports `diverged` without touching anything — push your changes first, then pull again.
+
+> Read-only machines (`READ_ONLY=1`) can still `pull_docs` and `sync_status`, but `push_docs`, `sync_docs`, and `resolve_sync_conflict` are disabled.
+
+## Portable tracked-file paths
+
+When docs are synced across machines, absolute tracked-file paths break: the codebase rarely lives at the same absolute location everywhere. To stay portable, tracked-file paths are stored **relative to a configurable code root** and resolved back to absolute paths on demand.
+
+Agents keep passing **absolute** paths to `create_doc` / `update_doc` (and in `[copy-from-codebase|…]` tags) as usual — the conversion to a stored relative path happens automatically server-side. No change in how the agent works.
+
+### Configuration
+
+Set the code root per machine (it is machine-local, so it lives in the environment, never in the synced data):
+
+```jsonc
+{
+  "env": {
+    "MCP_DOCUMENTOR_CODE_ROOT": "/home/you/code/repos",
+    // optional per-project overrides when repos don't share a common parent:
+    "MCP_DOCUMENTOR_CODE_ROOTS": "{\"my-proj\":\"/srv/my-proj\"}"
+  }
+}
+```
+
+Resolution precedence: `MCP_DOCUMENTOR_CODE_ROOTS[project]` → `MCP_DOCUMENTOR_CODE_ROOT` → none.
+
+| Stored path | On read |
+|---|---|
+| Relative + code root configured | resolved against the root |
+| Relative + **no** root on this machine | reported as `unverifiable` (source absent) instead of a false `stale` |
+| Absolute (legacy, or file outside the root) | used as-is |
+
+The feature is **opt-in**: with no code root configured, behaviour is unchanged (paths stored and resolved as absolute).
+
+### Migrating existing docs
+
+Docs created before this feature store absolute paths. Convert them in one shot with the bundled `mcp-documentor-migrate-paths`:
+
+```bash
+MCP_DOCUMENTOR_CODE_ROOT="/home/you/code/repos" \
+MCP_DATA_DIR="/path/to/your/data" \
+  npx -p @imenam/mcp-documentor mcp-documentor-migrate-paths --dry-run
+```
+
+Review the report (`converted` / `kept absolute (outside root)` / `projects skipped`), then re-run without `--dry-run`. Finally publish with `sync_docs` (never commit the data dir by hand). The data dir is resolved like the server: `--data-dir` flag → `MCP_DATA_DIR` → package-relative fallback.
+
+This is a **one-time** operation, and must run on the machine whose OS/filesystem **created** the stored absolute paths (path semantics differ between Windows and POSIX). Once migrated and synced, every other machine just `pull_docs` and sets its own `MCP_DOCUMENTOR_CODE_ROOT` — no migration needed.
+
+## Data Storage
+
+By default, data lives under **`.docs-data`** next to the resolved package root (the folder that contains `package.json` for the running install). Set **`MCP_DATA_DIR`** to use another directory. Contents include projects, SQLite/embeddings, and logs under `.docs-data/logs`. This tree is **not** part of the npm package; it is created at runtime.
+
+There is no server-side "active project": every MCP tool call names its project, and the GUI's selector only changes what that browser displays (kept in the URL and in `localStorage`). A legacy `currentProject` left in `config.json` is dropped on first read. GitHub sync settings live in environment variables, not on disk.
+
+## License
+
+ISC

package/dist/shared/schemas/doc.schema.d.ts

@@ -164,16 +164,13 @@ export declare const PatchDocArgsSchema: z.ZodObject<{
     replacement_file: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const CheckLinksArgsSchema: z.ZodObject<{
-    project: z.ZodOptional<z.ZodString>;
+    project: z.ZodString;
 }, z.core.$strip>;
 export declare const GitDiffDocArgsSchema: z.ZodObject<{
     paths: z.ZodArray<z.ZodString>;
     project: z.ZodString;
     file_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
-export declare const SetProjectArgsSchema: z.ZodObject<{
-    project: z.ZodString;
-}, z.core.$strip>;
 export declare const ListDocVersionsArgsSchema: z.ZodObject<{
     path: z.ZodString;
     project: z.ZodString;

package/dist/shared/schemas/doc.schema.js

@@ -124,16 +124,13 @@ export const PatchDocArgsSchema = z.object({
     message: "Either replacement or replacement_file is required",
 });
 export const CheckLinksArgsSchema = z.object({
-    project: z.string().optional().describe("Project to check (defaults to current project)"),
+    project: requiredProject("the link check").describe("Project whose entries are checked. Mandatory — links are never checked across projects, and there is no current-project fallback."),
 });
 export const GitDiffDocArgsSchema = z.object({
     paths: z.array(z.string()).min(1).describe("Paths of documentation entries to diff, e.g. ['backend/auth/authentication']"),
     project: requiredProject("the diff").describe("Project holding every entry listed in paths. Mandatory — entries are never resolved across projects. Call once per project if they are spread across several."),
     file_paths: z.array(z.string()).optional().describe("Specific tracked files to diff, as absolute paths (matched against the stored paths, relative or absolute). All tracked files if omitted."),
 });
-export const SetProjectArgsSchema = z.object({
-    project: z.string().describe("Project name to switch to (created if it does not exist)"),
-});
 export const ListDocVersionsArgsSchema = z.object({
     path: z.string(),
     project: requiredProject("history lookup"),

package/dist/src/cli/setup-mcp.d.ts

@@ -1,5 +1,24 @@
+/**
+ * Comment la GUI sera exposée. `undefined` des deux côtés = rien n'a été passé
+ * en ligne de commande : on retombe sur le placeholder PROXY_URL à compléter.
+ */
+export interface GuiExposure {
+    proxyUrl?: string;
+    appPort?: number;
+}
+/**
+ * Traduit `--proxy_url=` / `--app_port=` en mode d'exposition de la GUI.
+ * Les deux ensemble sont refusés : au runtime PROXY_URL primerait toujours,
+ * donc un fichier portant les deux serait silencieusement trompeur.
+ */
+export declare function parseGuiExposure(argv: string[]): {
+    exposure: GuiExposure;
+} | {
+    error: string;
+};
 export interface SetupMcpOptions {
     cwd: string;
     force: boolean;
+    exposure?: GuiExposure;
 }
-export declare function runSetupMcp({ cwd, force }: SetupMcpOptions): number;
+export declare function runSetupMcp({ cwd, force, exposure }: SetupMcpOptions): number;