@imenam/mcp-documentor 1.0.85 → 1.0.86

package/README.md

@@ -1,329 +1,323 @@
-# @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
-- **Track a branch, not a checkout** — point a project at a GitHub branch (`MCP_DOCUMENTOR_CODE_REPO`) and freshness is measured against *published* code: switching branches or editing without committing no longer makes docs look stale, and a server with no copy of the codebase (an MCP gateway) can still verify them
-- **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"}` |
-| `MCP_DOCUMENTOR_CODE_REPO` | No | Track a **GitHub branch** instead of the local working copy. Either one spec applied to every project — `owner/repo`, a GitHub URL, optional `#branch` suffix — or a JSON map of per-project specs, e.g. `{"web":"you/web#main","legacy":"local"}` (the value `local` opts a project back out to its working copy). Setting it is what enables the mode (see [Tracking a GitHub branch](#tracking-a-github-branch-instead-of-the-working-copy)) |
-| `MCP_DOCUMENTOR_CODE_BRANCH` | No | Branch used for repositories carrying no `#branch` suffix (default: the repository's own default branch) |
-| `MCP_DOCUMENTOR_CODE_TOKEN` | No | GitHub token used to read the code; falls back to `MCP_DOCUMENTOR_SYNC_TOKEN` |
-| `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.
-
-## Tracking a GitHub branch instead of the working copy
-
-By default, freshness is measured against the **working copy on the machine running the server**. That has two consequences: switching git branches locally flips docs in and out of `stale` even though the deployed code never moved, and a server that has no copy of the codebase — typically an MCP gateway on another host — cannot verify anything at all.
-
-Pointing a project at a repository makes the documentation track **one branch of published code** instead:
-
-```jsonc
-{
-  "env": {
-    "MCP_DOCUMENTOR_CODE_REPO": "you/my-repo#main",
-    // optional: reuses MCP_DOCUMENTOR_SYNC_TOKEN when omitted
-    "MCP_DOCUMENTOR_CODE_TOKEN": "github_pat_..."
-  }
-}
-```
-
-A repository names exactly one codebase, so an instance serving **several projects** gives `MCP_DOCUMENTOR_CODE_REPO` a JSON map instead of a single spec — a leading `{` is what tells the two apart:
-
-```jsonc
-"MCP_DOCUMENTOR_CODE_REPO": "{\"web\":\"you/web#main\",\"api\":\"you/api#main\",\"legacy\":\"local\"}"
-```
-
-Projects absent from the map, and projects whose value is `local`, keep reading their local working copy. **With the variable unset, nothing changes** — the local behaviour is untouched.
-
-The token needs **Contents: Read** on the code repository (a different repo from the docs sync one, so either widen the existing PAT's scope or issue a second one).
-
-### What changes once a project tracks a branch
-
-| | Local working copy (default) | GitHub branch |
-|---|---|---|
-| Sees uncommitted edits | yes | no — only what is pushed |
-| Affected by `git checkout` | yes | no |
-| Needs the codebase on the server | yes | no |
-| `git_diff_doc` baseline | last commit before the snapshot date | the exact commit the snapshot was taken at |
-
-Every report names the source it used (`Code source: GitHub you/my-repo@main`), so a verdict is never ambiguous. If the source cannot be reached — network, auth, rate limit — the status is `unverifiable` with the reason attached, **never** `stale`.
-
-### Paths and migration
-
-Stored tracked-file paths are already relative to the code root, and a code root is normally the repository root — so **existing docs keep working as-is**, with no migration and no mass re-snapshot. Two details make the switch seamless:
-
-- Hashes are computed on line-ending-normalised content, so a snapshot taken from a CRLF checkout still matches the LF blob in the repository. Hashes stored by earlier versions are still recognised.
-- Absolute paths sent by an agent are reduced by the code root when one is configured, and otherwise matched against the repository tree by their longest unambiguous suffix (a bare filename is only accepted when the repository holds exactly one file by that name).
-
-Docs snapshotted before the switch carry no source commit: `check_freshness` works immediately, while `git_diff_doc` will ask for one `refresh_file_snapshot` to anchor them on the branch.
-
-### API usage
-
-Freshness is **never computed in the background** — only when something asks for it: a `check_freshness` / `list_docs` / `get_doc` call, or the GUI loading a project's list. So the cost is bounded per request, not per unit of time.
-
-Within one such request, the branch head is resolved **once** and every tracked file is compared against that same commit — no mixed verdict if someone pushes mid-scan. The next request resolves it again, so a push is visible immediately: there is no staleness window to configure.
-
-Everything else is content-addressed and therefore cached for the life of the process: a commit's tree by its sha, a file's bytes by its blob sha. Each tracked file also records the blob sha it was snapshotted at, so an unchanged file is proven untouched without being downloaded at all. A full scan of an unchanged repository costs about two API calls — not one per file.
-
-## 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
+# @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 code root set per machine and per project (GUI or `set_code_root`), so synced docs resolve their source files on any machine regardless of where the repos live
+- **Track a branch, not a checkout** — point a project at a GitHub branch from its settings in the GUI and freshness is measured against *published* code: switching branches or editing without committing no longer makes docs look stale, and a server with no copy of the codebase (an MCP gateway) can still verify them
+- **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 | Seeds the machine's default code root the first time a data directory starts (`--claude-setup-mcp` fills it with the current folder). Afterwards code roots are set in the GUI or with `set_code_root` (see [Portable tracked-file paths](#portable-tracked-file-paths)) |
+| `MCP_DOCUMENTOR_CODE_TOKEN` | No | GitHub token used to read the code of projects tracking a GitHub branch. The only place it is set: neither the GUI nor the agent can change it |
+| `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 |
+| `get_code_source` | Show each project's code source (local working copy or GitHub branch) and its code root on this machine |
+| `set_code_source` | Make a project read its local working copy or one branch of a GitHub repository (checked before saving) |
+| `set_code_root` | Set the code root of a project, or the machine default, on this machine |
+
+## 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
+
+The code root is machine-local: it is stored in `local-state.json` in the data directory, never synced. Each machine has a **default root**, and each project can have **its own root**:
+
+- per project — in the project settings (project selector → gear → *Code root on this machine*), or with `set_code_root` and a `project`;
+- default — in Settings (*Default code root*), or with `set_code_root` without a `project`.
+
+Both apply at once, without restart. Resolution precedence: the project's own root → the machine default → none.
+
+`MCP_DOCUMENTOR_CODE_ROOT` seeds the default root the first time a data directory starts. Once a default root is stored, the variable is not read again.
+
+| 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_DATA_DIR="/path/to/your/data" \
+  npx -p @imenam/mcp-documentor mcp-documentor-migrate-paths --dry-run
+```
+
+It uses the code roots stored for that data directory, so set them first.
+
+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 code roots — no migration needed.
+
+## Tracking a GitHub branch instead of the working copy
+
+By default, freshness is measured against the **working copy on the machine running the server**. That has two consequences: switching git branches locally flips docs in and out of `stale` even though the deployed code never moved, and a server that has no copy of the codebase — typically an MCP gateway on another host — cannot verify anything at all.
+
+Pointing a project at a repository makes the documentation track **one branch of published code** instead. It is set per project in the GUI: open the project selector, hover a project and click its gear (or **Fix** on a project in error).
+
+- **Repository** — a search field: type part of a name (or `owner/name`) and matching repositories are suggested, private ones included when `MCP_DOCUMENTOR_CODE_TOKEN` can see them. Pasting `owner/repo` or a GitHub URL works too.
+- **Branch** — picked from the repository's branches; the commit it points at is shown.
+- **GitHub access** — shown read-only: the token is read from `MCP_DOCUMENTOR_CODE_TOKEN` only, and neither the GUI nor the agent can set it. It needs **Contents: Read** on the code repositories. Without it only public repositories can be read, within GitHub's unauthenticated rate limit (60 requests per hour).
+- Before saving, the project's docs are checked against the chosen source, so you see how many would turn outdated.
+
+The choice is applied at once, without restart. It is stored in `projects/<project>/project.json` next to the docs, so it is synced with them and every machine reads the same source. A project with no setting reads its local working copy. Agents can do the same with `get_code_source` and `set_code_source`.
+
+The project selector shows each project's source, and flags a project whose repository or branch cannot be found. Its docs are then reported `unverifiable`, never silently read from somewhere else.
+
+#### Migrating from the environment variables
+
+Earlier versions read `MCP_DOCUMENTOR_CODE_REPO`, `MCP_DOCUMENTOR_CODE_BRANCH` and `MCP_DOCUMENTOR_CODE_ROOTS`. On the first start of this version, each machine imports them once:
+
+- every project named by `MCP_DOCUMENTOR_CODE_REPO` (single spec or JSON map, `#branch` suffix or `MCP_DOCUMENTOR_CODE_BRANCH`) gets that source in its settings — unless it already has one, for instance pulled from another machine;
+- every project named by `MCP_DOCUMENTOR_CODE_ROOTS` gets that code root on this machine, unless it already has one.
+
+The GUI then shows a report of what each project became and which entries were not imported (unknown project, invalid spec). It can be reopened from Settings. From then on these variables are no longer read: remove them from the MCP configuration, the server only logs that they are ignored. `MCP_DOCUMENTOR_CODE_TOKEN` is not migrated — it stays the only place the token is set — and `MCP_DOCUMENTOR_CODE_ROOT` only seeds the default root (see above).
+
+### What changes once a project tracks a branch
+
+| | Local working copy (default) | GitHub branch |
+|---|---|---|
+| Sees uncommitted edits | yes | no — only what is pushed |
+| Affected by `git checkout` | yes | no |
+| Needs the codebase on the server | yes | no |
+| `git_diff_doc` baseline | last commit before the snapshot date | the exact commit the snapshot was taken at |
+
+Every report names the source it used (`Code source: GitHub you/my-repo@main`), so a verdict is never ambiguous. If the source cannot be reached — network, auth, rate limit — the status is `unverifiable` with the reason attached, **never** `stale`.
+
+### Paths and migration
+
+Stored tracked-file paths are already relative to the code root, and a code root is normally the repository root — so **existing docs keep working as-is**, with no migration and no mass re-snapshot. Two details make the switch seamless:
+
+- Hashes are computed on line-ending-normalised content, so a snapshot taken from a CRLF checkout still matches the LF blob in the repository. Hashes stored by earlier versions are still recognised.
+- Absolute paths sent by an agent are reduced by the code root when one is configured, and otherwise matched against the repository tree by their longest unambiguous suffix (a bare filename is only accepted when the repository holds exactly one file by that name).
+
+Docs snapshotted before the switch carry no source commit: `check_freshness` works immediately, while `git_diff_doc` will ask for one `refresh_file_snapshot` to anchor them on the branch.
+
+### API usage
+
+Freshness is **never computed in the background** — only when something asks for it: a `check_freshness` / `list_docs` / `get_doc` call, or the GUI loading a project's list. So the cost is bounded per request, not per unit of time.
+
+Within one such request, the branch head is resolved **once** and every tracked file is compared against that same commit — no mixed verdict if someone pushes mid-scan. The next request resolves it again, so a push is visible immediately: there is no staleness window to configure.
+
+Everything else is content-addressed and therefore cached for the life of the process: a commit's tree by its sha, a file's bytes by its blob sha. Each tracked file also records the blob sha it was snapshotted at, so an unchanged file is proven untouched without being downloaded at all. A full scan of an unchanged repository costs about two API calls — not one per file.
+
+## 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