@imenam/mcp-documentor 1.0.92 → 1.0.93

package/README.md

@@ -1,327 +1,343 @@
-# @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. Navigation runs from an icon rail on the left: the current project's badge (click to switch projects or create one), then Documentation, Search (`Ctrl/⌘ + K`, current or all projects), Outdated, Recent, Export bundles and Logs, with Sync and Settings at the bottom. Each destination fills the panel next to the rail; the panel's hide button, or a second click on the active icon, folds it away. Drag the panel's right edge to resize it (double-click resets the width); the browser remembers the width. The details panel on the right of a document (`Ctrl/⌘ + \`) is open by default from 1280 px wide; showing or hiding it by hand is remembered across reloads until the window crosses that width. Badges show the outdated docs, pending commits and the day's failed GitHub calls. Each open tab polls `GET /api/changes` every 3 seconds and every request is answered immediately: no connection stays open, so many tabs can share the proxy's origin, and changes made by the agent show up within 3 seconds. After a GUI worker restart, or when it has fallen more than 200 changes behind, the tab reloads the server state (`GET /api/initial-state`) and the list of the project it shows
-- **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; the text must occur once unless `replace_all` is set (`project` required) |
-| `move_doc` | Change a doc’s path (`new_path`) and/or project (`new_project`); links are rewritten across all projects, bare within their own project (`project` required) |
-| `delete_doc` | Permanently delete a documentation entry (`project` required) |
-| `create_project` | Create an empty project, optionally with its code source (`code_source`, as `set_code_source`) |
-| `delete_project` | Delete a project; refused while it holds any doc, image or other file besides its settings |
-| `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` | Diff of changed tracked files between their snapshot content and the current one (`project` required). Files whose tracked sections can no longer be located (anchors lost) are included and diffed whole, with a warning |
-| `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 | the commit the snapshot was taken at, else the last one before its date | the blob the snapshot was taken from, else its commit, else the last one before its date |
-
-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, and `git_diff_doc` falls back on the last commit before the snapshot date. Whatever its origin, a baseline is checked against the hash stored at the snapshot; when it does not match — typically after a rebase that rewrote commit dates — the diff is reported impossible, and one `refresh_file_snapshot` anchors the file on its blob, which survives rebases.
-
-### 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.
-
-Resolving the branch head is a conditional request: while the branch has not moved, GitHub answers `304 Not Modified`, which does not count against the rate limit of an authenticated token.
-
-Everything else is content-addressed: a commit's tree is cached by its sha for the life of the process, and a file's bytes by their blob sha on disk, in `<data dir>/blob-cache/` (machine-local, excluded from sync) — each version of a file is downloaded once per machine, across restarts. 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`). The open and closed folders of each project's navigation tree are also kept in `localStorage`, so a reload restores them. 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. Navigation runs from an icon rail on the left: the current project's badge (click to switch projects or create one), then Documentation, Search (`Ctrl/⌘ + K`, current or all projects), Outdated, Recent, Export bundles, Publications and Logs, with Sync and Settings at the bottom. Each destination fills the panel next to the rail; the panel's hide button, or a second click on the active icon, folds it away. Drag the panel's right edge to resize it (double-click resets the width); the browser remembers the width. On wide screens the whole interface is capped at 1600 px and centred. The details panel on the right of a document (`Ctrl/⌘ + \`) is open by default from 1280 px wide; showing or hiding it by hand is remembered across reloads until the window crosses that width. Badges show the outdated docs, pending commits and the day's failed GitHub calls. Each open tab polls `GET /api/changes` every 3 seconds and every request is answered immediately: no connection stays open, so many tabs can share the proxy's origin, and changes made by the agent show up within 3 seconds. After a GUI worker restart, or when it has fallen more than 200 changes behind, the tab reloads the server state (`GET /api/initial-state`) and the list of the project it shows
+- **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; the text must occur once unless `replace_all` is set (`project` required) |
+| `move_doc` | Change a doc’s path (`new_path`) and/or project (`new_project`); links are rewritten across all projects, bare within their own project (`project` required) |
+| `delete_doc` | Permanently delete a documentation entry (`project` required) |
+| `create_project` | Create an empty project, optionally with its code source (`code_source`, as `set_code_source`) |
+| `delete_project` | Delete a project; refused while it holds any doc, image or other file besides its settings |
+| `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` | Diff of changed tracked files between their snapshot content and the current one (`project` required). Files whose tracked sections can no longer be located (anchors lost) are included and diffed whole, with a warning |
+| `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
+
+## Publishing documents
+
+A document can be shared, read-only, with anyone who holds its link — no account, no session. Publishing is a user action in the GUI only: no MCP tool exposes it, so an agent can neither publish nor unpublish.
+
+- **Publish** — the **Publish** button of the document toolbar freezes the current version, with an optional version note, and creates the link. The button then reads **Published**; its popover gives the link (copy, open), the publication date, the frozen version and the note. An amber dot on the button means the document changed since it was published.
+- **Update publication** — freezes the current version under the **same** link, with a new optional note. Offered only when the document changed.
+- **Unpublish** — revokes the link after a confirmation: it answers 404 at once. Publishing again creates a new link.
+- **Publications page** — the globe of the rail lists every published document of the current project: version note, publication date, state (*Up to date*, *Changed · v12 → v14*, or *Document removed*), with Update, copy, open and Unpublish on each row. *Changed* keeps only the publications that lag behind their document.
+
+What the reader sees is the viewer's rendering (code highlighting, Mermaid, tables, images) without any action. An *On this page* table of contents of the document's headings sits on the right and follows the scroll; it is hidden below 1024 px wide. Web links stay active and open in a new tab; links to other documents become plain text; in-page anchors work. Images uploaded to the project are copied into the snapshot when it is frozen, so the page never changes until the publication is updated.
+
+**The link** is a *capability URL*: its last segment is a 32-byte random token, and holding it is the only authorization. The page is served under `public/<token>/` next to the GUI, or under `/_pub/<route of the GUI>/<token>/` behind the mcp-gateway-manager hub, which relays that prefix without a session. Every public response carries `X-Robots-Tag: noindex, nofollow, noarchive` and `Referrer-Policy: no-referrer` (the token never leaks to the sites the reader opens), and the page has a strict Content-Security-Policy. The page embeds the frozen document: it makes no API call.
+
+Publications live in `<data dir>/publications/` — `index.json` plus one snapshot directory per publication. The directory is machine-local and excluded from sync: a link is served by the machine that created it. A document moved with `move_doc` keeps its publication; a deleted one keeps serving its frozen snapshot until it is unpublished. `READ_ONLY` disables publishing, updating and unpublishing.
+
+## 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) |
+| | `publications/` (public links served by this machine) |
+
+### 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 | the commit the snapshot was taken at, else the last one before its date | the blob the snapshot was taken from, else its commit, else the last one before its date |
+
+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, and `git_diff_doc` falls back on the last commit before the snapshot date. Whatever its origin, a baseline is checked against the hash stored at the snapshot; when it does not match — typically after a rebase that rewrote commit dates — the diff is reported impossible, and one `refresh_file_snapshot` anchors the file on its blob, which survives rebases.
+
+### 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.
+
+Resolving the branch head is a conditional request: while the branch has not moved, GitHub answers `304 Not Modified`, which does not count against the rate limit of an authenticated token.
+
+Everything else is content-addressed: a commit's tree is cached by its sha for the life of the process, and a file's bytes by their blob sha on disk, in `<data dir>/blob-cache/` (machine-local, excluded from sync) — each version of a file is downloaded once per machine, across restarts. 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`). The open and closed folders of each project's navigation tree are also kept in `localStorage`, so a reload restores them. A legacy `currentProject` left in `config.json` is dropped on first read. GitHub sync settings live in environment variables, not on disk.
+
+## License
+
+ISC