overleaf-forge 2.9.1 → 2.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/overleaf-forge.svg)](https://www.npmjs.com/package/overleaf-forge) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license) ![Node](https://img.shields.io/badge/node-%E2%89%A518-43853d.svg)
 
-A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI assistant (Claude Code, Claude Desktop, or any MCP client) read, edit, compile, and verify an [Overleaf](https://www.overleaf.com) project over Overleaf's built-in **git** integration. The model edits a local clone with surgical, conflict-safe operations and pushes to Overleaf; nothing depends on scraping the web UI.
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI assistant (Claude Code, Claude Desktop, or any MCP client) read, edit, compile, and verify an [Overleaf](https://www.overleaf.com) project over Overleaf's built-in **git** integration. The model edits a local clone with surgical, conflict-safe operations and publishes verified batches to Overleaf. Nothing depends on scraping the web UI.
 
 > **Acknowledgement.** Forked from [mjyoo2/OverleafMCP](https://github.com/mjyoo2/OverleafMCP), the original Overleaf MCP server. This fork adds conflict-safe editing, binary/figure upload, a clean-build PASS/FAIL gate, citation and voice linting, snapshots, a bootstrap for recurring structured documents, per-project contexts, and a hardened git layer (no-shell `execFile`, credential-helper auth, error redaction).
 
@@ -12,35 +12,49 @@ Editing a LaTeX project through an AI normally means one of two bad options: pas
 
 ## Token economy
 
-Safety is one motivation; keeping a large document out of the model's context window is the other, and it drove most of the tool design. A 50 KB chapter is about 12K to 13K tokens, so the cost of a naive workflow is dominated by moving that whole file in and out.
+Safety is one motivation. Keeping a large document out of the model's context window is the other, and it drove most of the tool design. A 50 KB chapter is about 12K to 13K tokens, so the cost of a naive workflow is dominated by moving that whole file in and out.
 
-Rough token cost per operation on such a chapter, and the cut each tool buys:
+Measured token cost on a real 48 KB chapter (a 30-page report with a bibliography and `minted` listings). The whole-file column is an estimate of the read-and-rewrite alternative. The overleaf-forge column is measured over MCP, at about four characters per token.
 
-| Operation (on a ~50 KB chapter) | Whole-file workflow | overleaf-forge | Reduction |
+| Operation (on a ~50 KB chapter) | Whole-file workflow (estimate) | overleaf-forge (measured) | Reduction |
 | --- | --- | --- | --- |
-| One surgical edit | ~25K (read + write the file) | ~0.15K (`edit_file`) | ~99% |
-| A dozen edits (one revision pass) | ~170K | ~3K | ~98% |
-| One compile check | ~1.5K (raw `latexmk` log) | ~0.02K (`verify_build` verdict) | ~99% |
+| One surgical edit | ~25K (read + write the file) | ~25 tokens (`edit_file`) | >99% |
+| A dozen edits (one revision pass) | ~170K | ~0.3K | >99% |
+| One passing build check | ~1.5K to 2K (raw `latexmk` log) | ~4 tokens (`verify_build` PASS) | >99% |
 | Locating a passage | ~13K (read the whole file) | ~2K (`get_section_content` / `search_text`) | ~85% |
+| Re-reading unchanged guidance | full guidance again | ~25 tokens (`get_context` with `previousVersion`) | >99% |
 
-Figures are order-of-magnitude, for a chapter this size; the absolute numbers scale with file size, the percentages roughly hold.
+The absolute numbers scale with file size. The percentages roughly hold.
 
-- **Anchored edits instead of whole-file rewrites.** Changing one phrase by reading the whole file and writing it back costs roughly 25K tokens per edit: the file into context, then the file back out as the write payload. `edit_file` sends only the old and new strings and returns a one-line confirmation, on the order of 100 tokens. Across a dozen edits to a single chapter that is the difference between roughly 170K tokens and 3K.
-- **A one-line build verdict instead of a raw log.** `verify_build` returns `✓ PASS — 24 pages` rather than the `latexmk` output. A raw log runs to hundreds or thousands of tokens per compile, and a multi-pass log buries the true final state under transient undefined-reference warnings from early passes (the exact trap `verify_build` classifies away by reading the final log). Over a session of repeated compiles that is a few thousand tokens against a few dozen.
-- **Section and grep reads instead of the whole file.** `get_section_content` returns one section and `search_text` returns the matching lines, so locating something costs 1K to 3K tokens rather than the full 13K.
+- **Anchored edits instead of whole-file rewrites.** Changing one phrase by reading the whole file and writing it back costs roughly 25K tokens per edit: the file enters the context, then leaves it again as the write payload. `edit_file` sends only the old and new strings and returns one line naming the new local commit.
+- **A verdict instead of a log.** A passing `verify_build` returns `PASS: 30 pages.` A failing one returns the counts, the first offending lines and the log path. A raw multi-pass log costs hundreds to thousands of tokens and buries the true final state under transient undefined-reference warnings from early passes, which `verify_build` avoids by classifying the final log only.
+- **Section and grep reads instead of the whole file.** `get_section_content` returns one section and `search_text` returns the matching lines, so locating something costs 1K to 3K tokens rather than 13K.
+- **Fewer network round trips.** Reads, builds and edits work on the local clone. In the measured session below, the previous release made 29 git network operations and this one makes 1, the final push.
 
-For an iterative edit, build, and review loop on a large document the tool traffic runs about an order of magnitude lighter than a read-and-rewrite-the-whole-file approach. The gain is workflow-dependent: a single full-file rewrite is a wash, since `write_file` moves the same bytes either way. It is the repeated, surgical work that compounds, which is exactly the shape of writing and revising a paper.
+**A measured session.** Context read, section read, twelve anchored edits, an intermediate build, the final gate, a context re-read and a publish, on the chapter above:
+
+| | 2.9.1 | 2.12 |
+| --- | --- | --- |
+| Tool responses | ~13.9K tokens | ~5.5K tokens |
+| Tool definitions (paid once per session) | ~3.9K tokens | ~5.0K tokens |
+| Git network operations | 29 | 1 |
+| Wall time against a local stand-in remote | 53 s | 53 s |
+
+The remaining wall time is LaTeX. Against real Overleaf, every one of the 28 avoided network operations is an HTTPS round trip. Most of the saving in tool responses comes from the guidance: a shorter default guide, and a compact reply when it is re-read unchanged. A revision session that also loads a long personal style reference narrows the gap.
 
 ## Features
 
-- **Surgical, conflict-safe edits**: `edit_file` replaces an exact anchor and refuses if the region changed on Overleaf; non-overlapping concurrent edits auto-merge via git.
+- **Local-first, publish when verified**: edits commit to the local clone and stay off the network until `publish_changes` verifies the build and pushes the whole batch. `settings.autoPush` restores push-on-every-write.
+- **Surgical, conflict-safe edits**: `edit_file` replaces an exact anchor and refuses if the region changed. When pushing, non-overlapping concurrent edits auto-merge via git.
 - **No silent clobbering**: full-file `write_file` requires a freshness token (`baseSha`) or an explicit `overwrite` to replace an existing file.
-- **Binary / figure upload**: push PNG/PDF figures from disk (single or a whole set in one commit), byte-exact, path-confined to the project.
-- **Build verification**: `verify_build` compiles from scratch with `latexmk` and returns PASS/FAIL on the real "done" bar (a PDF, zero errors, zero undefined references/citations) with the page count.
-- **Citation tooling**: append BibTeX entries with duplicate-key protection; lint for undefined and unused citations.
-- **Section-aware reading**: list sections and pull a single section's body by title.
+- **Divergence recovery**: `sync_project` reports what differs between the clone and Overleaf without changing anything, then resolves it by rebase (aborts cleanly on conflict) or by a confirmed reset that tags a backup first.
+- **Binary / figure upload**: add PNG/PDF figures from disk (single or a whole set in one commit), byte-exact, path-confined to the project.
+- **Build verification**: `verify_build` compiles from scratch with `latexmk` and returns PASS/FAIL on the real "done" bar (a PDF, zero errors, zero undefined references/citations) with the page count. An unchanged successful build is reused instead of rebuilt. `clean: false` gives a quicker incremental rebuild for intermediate checks, and `lint` makes voice-linter findings fail the gate.
+- **Citation tooling**: append BibTeX entries with duplicate-key protection, and lint for undefined and unused citations.
+- **Section-aware reading**: list sections and pull a single section's body by title, optionally bundled with the equations, figures and bibliography entries it references.
+- **Dependency tracking**: `dependency_index` and `change_report` name the sections affected by a changed label, value, citation or included file.
 - **Project grep**: `search_text` over tracked files.
-- **Snapshots**: `checkpoint` a rollback point before a risky edit; `restore` it as a forward commit (no force-push, no history rewrite).
+- **Snapshots**: `checkpoint` a rollback point before a risky edit, then `restore` it as a forward commit (no force-push, no history rewrite).
 - **Recurring-document bootstrap**: one call to clone, register, and scaffold a new instance of a structured document (see [Bootstrap](#bootstrap-for-recurring-structured-documents)).
 - **Per-project context**: durable notes and writing guidelines surfaced to the model at the start of a session.
 - **Hardened git layer**: every subprocess runs through `execFile` (no shell), the token is supplied via an environment-backed credential helper and never appears in a command or an error, and tokenized URLs are redacted from any error returned.
@@ -49,7 +63,7 @@ For an iterative edit, build, and review loop on a large document the tool traff
 
 - Node.js ≥ 18 (ESM).
 - `git` on `PATH`.
-- A LaTeX distribution with `latexmk` (only for `compile_file` / `verify_build`; the rest works without it). The default engine is LuaLaTeX; `latexmk` is expected at `/Library/TeX/texbin` (MacTeX) or otherwise on `PATH`.
+- A LaTeX distribution with `latexmk` (only for `verify_build`; the rest works without it). The default engine is LuaLaTeX. `latexmk` is expected at `/Library/TeX/texbin` (MacTeX) or otherwise on `PATH`.
 - An Overleaf account with **Git integration** enabled (a paid feature at time of writing).
 
 ## Install
@@ -76,7 +90,7 @@ For an iterative edit, build, and review loop on a large document the tool traff
 
 3. Restart the client (or reload its MCP servers). That's it.
 
-`npx` fetches and runs the published package on demand. The token and project id are the entire setup for a single project, with no config file (this is **env-only mode**). `@latest` means each client restart picks up the newest published version automatically; pin `overleaf-forge@2.7.1` instead to freeze a version. For multiple projects, per-project contexts, or the SSA bootstrap, see [Configuration](#configuration).
+`npx` fetches and runs the published package on demand. The token and project id are the entire setup for a single project, with no config file (this is **env-only mode**). `@latest` means each client restart picks up the newest published version automatically. Pin `overleaf-forge@2.11.0` instead to freeze a version. For multiple projects, per-project contexts, or the SSA bootstrap, see [Configuration](#configuration).
 
 An MCP server is not an app you launch yourself: the client starts it as a subprocess, so "installing" it just means making its command available to the client. The `npx` form above needs no install step. If you would rather have a real command on your `PATH`, install it globally:
 
@@ -98,7 +112,7 @@ Then use `"command": "node", "args": ["/absolute/path/to/overleaf-mcp-server.js"
 
 ### Wiring into specific clients
 
-The `mcpServers` schema is identical across clients; only the file location differs. Put the `npx` block above inside each.
+The `mcpServers` schema is identical across clients: only the file location differs. Put the `npx` block above inside each.
 
 | Client | Config file |
 | --- | --- |
@@ -111,13 +125,15 @@ Restart the client (or reload its MCP servers) after editing, so it spawns the s
 
 ## Updating
 
-**As a user.** With `overleaf-forge@latest` in your config (the recommended form), restart the client or reload its MCP servers and it fetches the newest published version. If you pinned a version (`overleaf-forge@2.7.1`), change the number. If `npx` seems to keep running an old version, clear its cache with `npx clear-npx-cache` and restart. If you installed globally instead, update with `npm update -g overleaf-forge`.
+**As a user.** With `overleaf-forge@latest` in your config (the recommended form), restart the client or reload its MCP servers and it fetches the newest published version. If you pinned a version (`overleaf-forge@2.11.0`), change the number. If `npx` seems to keep running an old version, clear its cache with `npx clear-npx-cache` and restart. If you installed globally instead, update with `npm update -g overleaf-forge`.
+
+**Upgrading from 2.9 or earlier: edits no longer push by default.** Since 2.11, `edit_file`, `write_file`, `upload_file`, `add_citation` and `restore` commit to the local clone and report the unpublished count: nothing reaches Overleaf until `publish_changes` runs. To keep the old push-on-every-write behaviour, set `autoPush: true` through `configure` (or pass `push: true` per call). Since 2.10, reads and builds no longer pull either, so start a session with `sync_project` when Overleaf may have moved. `compile_file` is now `verify_build({clean: false})`, and `get_section_bundle` is now `get_section_content({bundle: true})`.
 
 **As the maintainer (publishing a new release).** From the repository:
 
 ```bash
 npm version patch        # or minor / major; bumps package.json and tags
-npm publish              # enter your npm 2FA one-time code when prompted
+npm publish              # approve the npm 2FA prompt (browser or one-time code)
 git push --follow-tags   # push the commit and the version tag
 ```
 
@@ -176,11 +192,11 @@ That creates `~/.overleaf-mcp/projects.json` from the example and copies the edi
 | `projects.<key>.cwd` | Directory you launch the client from for this project; used to auto-detect the active project. |
 | `projects.<key>.localPath` | Explicit clone location (optional). |
 
-`projects.json` is re-read on every call, so registering a project or rotating the token takes effect immediately, with no restart. (Code changes do need a restart; the server loads its `.js` once at startup.)
+`projects.json` is re-read on every call, so registering a project or rotating the token takes effect immediately, with no restart. (Code changes do need a restart: the server loads its `.js` once at startup.)
 
 ### Where files live
 
-User state (the `projects.json`, per-project `contexts/`, customised `templates/`, and the git clones) lives in the **data home**, resolved as: `$OVERLEAF_MCP_HOME` if set, else the package directory when it already holds a `projects.json` (so an existing local clone keeps working untouched), else `~/.overleaf-mcp`. Bundled, read-only defaults (the templates and the stock writing-guidelines) ship inside the package; a copy you place in the data home overrides the bundled one.
+User state (the `projects.json`, per-project `contexts/`, customised `templates/`, and the git clones) lives in the **data home**, resolved as: `$OVERLEAF_MCP_HOME` if set, else the package directory when it already holds a `projects.json` (so an existing local clone keeps working untouched), else `~/.overleaf-mcp`. Bundled, read-only defaults (the templates and the stock writing-guidelines) ship inside the package, and a copy you place in the data home overrides the bundled one. For personal writing rules, use `writing-guidelines.local.md` (gitignored, read first on every `get_context` call). It stays distinct from the bundled file even when the data home is the package directory.
 
 ### Getting Overleaf credentials
 
@@ -222,17 +238,20 @@ A typical editing session, in the model's words:
 2. *"Show me the sections in `Chapters/ch2.tex`."* → `get_sections`
 3. *"In `Chapters/ch2.tex`, change `\section{Intro}` to `\section{Introduction}`."* → `edit_file` (anchored, conflict-safe)
 4. *"Add a figure: upload `~/plots/fig1.png` to `figures/fig1.png`."* → `upload_file`
-5. *"Verify the build."* → `verify_build` → `✓ PASS — 12 pages`
+5. *"Verify the build."* → `verify_build` → `PASS: 12 pages.`
+6. *"Publish it."* → `publish_changes` (pushes every verified local commit to Overleaf at once)
 
-Every write commits and pushes to Overleaf; `verify_build` is the gate before calling the work done.
+Every write commits locally. `verify_build` is the gate before calling the work done, and `publish_changes` pushes the verified commits to Overleaf in one step. Set `settings.autoPush: true` (or pass `push: true`) to push on every write instead.
 
 ## Conflict safety
 
 Edits never silently overwrite a concurrent Overleaf change.
 
-- **`edit_file`** pulls the latest first (so a non-overlapping browser edit is absorbed), then replaces an exact anchor string. If the anchor is gone, the region changed since you read it, and the edit refuses rather than guessing. On the rare push race, git performs a real 3-way merge and the edit refuses only on a true overlap.
-- **`write_file`** (full-file create or overwrite) creates a new file freely. To overwrite an existing file it requires either the `baseSha` you got from `read_file` (a stale one is refused) or an explicit `overwrite: true`. It never merges a wholesale replacement; a push race refuses and resets.
+- **Local by default.** Write tools commit to the local clone and stay off the network unless `push: true` or `settings.autoPush` is set. `publish_changes` pushes the accumulated commits after verification. When any push is refused, only that operation's own commit is rolled back: earlier unpublished commits are never discarded.
+- **`edit_file`** replaces an exact anchor string. If the anchor is gone, the region changed since you read it, and the edit refuses rather than guessing. When pushing, it pulls first (so a non-overlapping browser edit is absorbed), and on the rare push race git performs a real 3-way merge and the edit refuses only on a true overlap.
+- **`write_file`** (full-file create or overwrite) creates a new file freely. To overwrite an existing file it requires either the `baseSha` you got from `read_file` (a stale one is refused) or an explicit `overwrite: true`. It never merges a wholesale replacement: a push race refuses and rolls back its own commit.
 - **`upload_file`** uses the same gate for binaries, never merges, and confines every destination path inside the project clone.
+- **`sync_project`** fetches and fast-forwards when the clone is only behind. On divergence it changes nothing and reports the local and remote commits. `strategy: "rebase"` replays local work onto Overleaf (aborting cleanly on conflict), and `strategy: "reset"` discards local work only with `confirm` equal to the reported head, after tagging `mcp-backup/*` copies of the old head and any uncommitted edits.
 - An explicit `projectName` that doesn't resolve is an **error**, never a silent fall-through to a different project, so a write cannot land in the wrong repo.
 
 ## Bootstrap for recurring structured documents
@@ -243,7 +262,7 @@ Edits never silently overwrite a concurrent Overleaf change.
 
 By the built-in convention this parses the name, locates the parent course folder under `settings.academicRoot/Year <year>/Q*/<COURSE>*`, creates `<parent>/<ssaSubdir>/<name>/`, clones the Overleaf repo into an `overleaf/` subfolder, registers the project, and scaffolds a context file with a question template. Pass `cleanAfterClone: true` when the project was duplicated from a previous instance to wipe the body (chapters, appendices, bib, figures) while keeping the preamble.
 
-**Adapting it.** The parsing and folder rules are specific to the SSA scheme; to drive other recurring work, adjust `parseSsaName` / `findCourseFolder` and the `bootstrap_ssa` handler, or skip the bootstrap entirely and `register_project` each instance.
+**Adapting it.** The parsing and folder rules are specific to the SSA scheme. To drive other recurring work, adjust `parseSsaName` / `findCourseFolder` and the `bootstrap_ssa` handler, or skip the bootstrap entirely and `register_project` each instance.
 
 ## Tools
 
@@ -267,7 +286,7 @@ By the built-in convention this parses the name, locates the parent course folde
 | `read_file` | Read a file. The first line carries the file's `baseSha` (its git blob hash) for conflict-safe writes. |
 | `list_files` | List files in the project, filtered by extension. |
 | `get_sections` | List `\section` / `\subsection` / `\subsubsection` entries in a `.tex`. |
-| `get_section_content` | Pull a single section's body by title (level-aware: a section keeps its subsections). |
+| `get_section_content` | One section's body by exact, unique title, `\section` down to `\paragraph` (level-aware: a section keeps its subsections). `bundle: true` adds the referenced equation/figure blocks, bibliography entries and assets. |
 | `search_text` | Grep tracked files. Regex by default; `fixed` for a literal, `ignoreCase`, `extension` to scope. Returns `file:line:match`. |
 | `status_summary` | File count, main file, section count. |
 
@@ -275,7 +294,7 @@ By the built-in convention this parses the name, locates the parent course folde
 
 | Tool | Purpose |
 | --- | --- |
-| `edit_file` | Anchored `oldString` → `newString` edit + commit + push. Conflict-safe; auto-merges non-overlapping concurrent edits. Preferred for existing files. |
+| `edit_file` | Anchored `oldString` → `newString` edit + commit (push per `push` / `settings.autoPush`). Conflict-safe; auto-merges non-overlapping concurrent edits. Preferred for existing files. |
 | `write_file` | Create a new file, or overwrite one wholesale. Existing-file overwrite needs `baseSha` or `overwrite: true`. |
 | `upload_file` | Upload binary file(s) (figures) from a local path. Single or batch (one commit). Byte-exact, path-confined, same conflict gate. |
 
@@ -283,22 +302,52 @@ By the built-in convention this parses the name, locates the parent course folde
 
 | Tool | Purpose |
 | --- | --- |
-| `compile_file` | Compile with `latexmk` from the repo root, so the project `.latexmkrc`, reruns, and bibliography all apply; reports errors, undefined refs, overfull boxes. |
-| `verify_build` | Clean-from-scratch compile + PASS/FAIL verdict: PASS only with a PDF and zero errors / undefined references / undefined citations. Reports page count. The done-bar gate. |
+| `verify_build` | Compile with `latexmk` from the repo root (project `.latexmkrc`, reruns and bibliography apply) + PASS/FAIL verdict: PASS only with a PDF and zero errors / undefined references / undefined citations. Reports page count. Default is the clean from-scratch done-bar gate; `clean: false` is a quick incremental rebuild; `lint` adds voice-linter findings to the gate. |
+| `sync_project` | Fetch and reconcile with Overleaf: fast-forward, report divergence, or resolve it with `rebase` / confirmed `reset` (see Conflict safety). |
+| `publish_changes` | Verify the clean local HEAD and push every unpublished commit once. |
+| `apply_changes` | Verify a SHA-guarded multi-file batch in an isolated worktree, then commit it locally only if it passes. |
+
+**Analysis & measurement**
+
+| Tool | Purpose |
+| --- | --- |
+| `dependency_index` | Static map of includes, figures, labels, references, citations and declared values; names the sections a change affects. |
+| `change_report` | Compact file and section changes against a retained baseline. |
+| `render_pages` | Render chosen PDF pages to cached PNGs for visual checks. |
+| `usage_stats` | In-process call counts, durations, response sizes and cache hits (no document text). |
 
 **Citations, snapshots, voice**
 
 | Tool | Purpose |
 | --- | --- |
-| `add_citation` | Append a BibTeX entry to `refs.bib` (refuses a duplicate key) + push. |
+| `add_citation` | Append a BibTeX entry to `refs.bib` (refuses a duplicate key) + commit. |
 | `cite_lint` | Report undefined (`\cite` with no entry) and unused (entry never cited) citations. Read-only. |
 | `checkpoint` | Mark a local rollback point (a `mcp-snap/<label>` tag) before a risky edit. |
-| `restore` | Roll back to a checkpoint via a forward commit + push (no force, no history rewrite). |
-| `voice_lint` | Run a prose linter on a `.tex` (the bundled `examples/voice-lint.mjs` by default; override via `settings.voiceLinter`). Lints the local working copy as-is, never pulls. Read-only, advisory. |
+| `restore` | Roll back to a checkpoint via a forward commit (no force, no history rewrite). |
+| `voice_lint` | Run a prose linter on a `.tex` (the bundled `examples/voice-lint.mjs` by default; override via `settings.voiceLinter`). Lints the local working copy as-is, never pulls. Read-only and advisory; `verify_build` with `lint` makes it gating. |
+
+## Local reads, builds and batches
+
+- `get_context({projectName, previousVersion})` returns a context version and omits unchanged content. The version covers project identity and the rendered guidance/context.
+- `get_section_content({projectName, filePath, sectionTitle, bundle: true, maxChars})` reads locally without pulling and returns directly referenced equation/figure blocks, matching BibTeX entries and asset paths. It reports missing matches and truncation. Macro-generated references, recursive TeX expansion and parenthesized BibTeX entries require a focused follow-up read.
+- All read, search, lint, dependency, render and build tools are local-only. Use `sync_project` explicitly before reading when needed. It fast-forwards on its own and resolves divergence only through an explicitly chosen strategy.
+- Build output is compact by default. `verbose: true` includes a bounded log tail, and the full log stays at the returned path.
+- `verify_build` can reuse a successful verification within the running server when project files, recorder inputs, tool binaries, environment and output artifacts are unchanged. `force: true` rebuilds. Missing recorder data, symlinks or executable build configuration (a project `.latexmkrc`, or the user's own `~/.latexmkrc`) conservatively disable reuse. The cache is in-memory and disappears on server restart. Custom build commands can have undeclared external dependencies, so projects with latexmkrc files or detected shell/Lua generation rebuild. `publish_changes` is the exception: it reuses a PASS from the same session when every project file is byte-identical since, so publishing does not repeat the final gate's full build.
+- `controlled: true` runs `latexmk -norc -no-shell-escape` and permits caching in projects with a `.latexmkrc`, because the rc file cannot run. The mode still rejects shell escape, `minted` and Lua file generation. Add required absolute regular `externalInputs` so their content enters the cache key.
+- `dependency_index` records static TeX includes, figures, labels, references, citations and declared values. `change_report` compares a later index to a retained baseline and names affected sections. Dynamic macros are reported as unresolved rather than guessed.
+- `render_pages` caches a requested PDF page by PDF content hash, page, DPI and renderer version. `usage_stats` exposes aggregate in-process timing, response-size and cache-hit measurements without retaining request or document text.
+- Write tools commit locally unless `push: true` or `settings.autoPush` is set, and report HEAD plus the unpublished count.
+- `apply_changes` verifies an SHA-guarded UTF-8 multi-file candidate in an isolated worktree and fast-forwards one local commit only if verification passes. `publish_changes` separately re-verifies its exact clean revision, then pushes it once, carrying every unpublished local commit. Neither operation pulls, resets, retries or silently merges.
+
+After updating the server, reconnect the MCP client so it reloads the process and tool schemas.
+
+## Troubleshooting
+
+**Every build fails with undefined citations on macOS 27.** TeX Live 2025 ships biber as a universal binary that unpacks itself with `lipo -extract_family`, which the `lipo` in macOS 27 rejects (`biber: extracting arm64 binary with lipo failed`). A user-level workaround: a small `biber` wrapper that extracts the native slice with `lipo -thin` and caches it, and a `~/.latexmkrc` line pointing latexmk at it (`$biber = "$ENV{HOME}/.local/bin/biber %O %S";`). A user rc file counts as executable build configuration, so non-controlled builds stop using the full build cache while it exists.
 
 ## How it works
 
-Each project is a normal git clone of its Overleaf repo, kept under `repoDir` (or `localPath`). On every operation the server pulls the latest, performs the read/edit/build locally, and pushes. Git runs through `execFile` with argument arrays (no shell), so file paths, commit messages, and patterns can't inject commands. Authentication uses an inline git credential helper that reads the token from the process environment, so the token is never written into a remote URL, a command line, or an error message; the clone's `origin` stays token-free. `compile_file` and `verify_build` shell out to `latexmk` from the repo root so the project's own `.latexmkrc` governs the build.
+Each project is a normal git clone of its Overleaf repo, kept under `repoDir` (or `localPath`). `sync_project` is the only synchronization command. Read, search, lint, dependency, render and build tools use the existing clone without pulling. This gives a task a stable source snapshot and prevents a read from replacing local edits. Git runs through `execFile` with argument arrays (no shell), so file paths, commit messages, and patterns can't inject commands. Authentication uses an inline git credential helper that reads the token from the process environment, so the token is never written into a remote URL, a command line, or an error message. The clone's `origin` stays token-free.
 
 ## Testing & development
 
@@ -308,18 +357,18 @@ node --test            # run the full suite
 node --check overleaf-mcp-server.js
 ```
 
-Tests run the real client against a throwaway local bare repository that stands in for Overleaf, so the full edit/merge/conflict/upload/snapshot behaviour is exercised with no network and no real account. The `verify_build` log classifier is unit-tested on captured log strings; a single integration test compiles a trivial document and auto-skips when `latexmk` isn't installed, so the suite is green on any machine.
+Tests run the real client against a throwaway local bare repository that stands in for Overleaf, so the full edit/merge/conflict/upload/snapshot behaviour is exercised with no network and no real account. The `verify_build` log classifier is unit-tested on captured log strings. A single integration test compiles a trivial document and auto-skips when `latexmk` isn't installed, so the suite is green on any machine.
 
 ## Security
 
-- `projects.json` is gitignored; never commit a real token.
-- The token is supplied to git through an environment-backed credential helper and never appears in a command string, a remote URL, or an error. Any tokenized URL that could surface in an error is redacted before it is returned. Rotate by updating `settings.gitToken`; it applies on the next call.
+- `projects.json` is gitignored. Never commit a real token.
+- The token is supplied to git through an environment-backed credential helper and never appears in a command string, a remote URL, or an error. Any tokenized URL that could surface in an error is redacted before it is returned. Rotate by updating `settings.gitToken`: it applies on the next call.
 - All subprocess calls use `execFile` (no shell), so paths, commit messages, and section titles cannot inject shell commands.
 - `upload_file` destinations are resolved and confined inside the project clone (no `..` escape, no absolute paths, not the `.git` directory).
 
 ## Origin & credits
 
-Forked from [mjyoo2/OverleafMCP](https://github.com/mjyoo2/OverleafMCP). The original established the git-integration approach and the base read/write/compile tools; this fork reworked the edit path for conflict safety, hardened the git layer, and added the verification, figure, citation, snapshot, voice, bootstrap, and context tooling.
+Forked from [mjyoo2/OverleafMCP](https://github.com/mjyoo2/OverleafMCP). The original established the git-integration approach and the base read/write/compile tools. This fork reworked the edit path for conflict safety, hardened the git layer, and added the verification, figure, citation, snapshot, voice, bootstrap, and context tooling.
 
 ## License
 

package/dependency-index.js

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath, readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const parseCache = new Map();
+const snapshots = new Map();
+const MAX_FILES = 1000;
+const MAX_RESPONSE = 5000;
+const MAX_SNAPSHOTS = 8;
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const lineAt = (text, offset) => text.slice(0, offset).split('\n').length;
+const rel = (root, file) => path.relative(root, file).split(path.sep).join('/');
+
+function inside(root, candidate) {
+  const r = path.resolve(root);
+  const c = path.resolve(candidate);
+  return c === r || c.startsWith(`${r}${path.sep}`);
+}
+
+function withoutComments(source) {
+  return source.replace(/(^|[^\\])%[^\n]*/g, '$1');
+}
+
+function sectionFor(sections, offset) {
+  let result = null;
+  for (const section of sections) {
+    if (section.offset <= offset) result = section;
+    else break;
+  }
+  return result;
+}
+
+function parseFile(file, source, hash) {
+  const text = withoutComments(source);
+  const sections = [];
+  const sectionRe = /\\(part|chapter|section|subsection|subsubsection|paragraph|subparagraph)\*?\{((?:[^{}]|\{[^{}]*\})*)\}/g;
+  let match;
+  while ((match = sectionRe.exec(text))) sections.push({
+    id: `${file}#${match[2]}`,
+    title: match[2], type: match[1], line: lineAt(text, match.index), offset: match.index,
+  });
+  for (let i = 0; i < sections.length; i++) {
+    const nextOffset = i + 1 < sections.length ? sections[i + 1].offset : source.length;
+    sections[i].endLine = i + 1 < sections.length ? sections[i + 1].line - 1 : source.split('\n').length;
+    // Hash the section's own source span. This keeps an unchanged subsection
+    // stable when text in a sibling section shifts its line number.
+    sections[i].hash = digest(source.slice(sections[i].offset, nextOffset));
+    if (i > 0 && sections[i - 1].id === sections[i].id) sections[i].id += `:${i + 1}`;
+  }
+  const declarations = [];
+  const labels = [];
+  const refs = [];
+  const citations = [];
+  const includes = [];
+  const graphics = [];
+  const values = [];
+  if (/\.bib$/i.test(file)) {
+    const bibRe = /@\w+\s*\{\s*([^,\s]+)\s*,/g;
+    while ((match = bibRe.exec(text))) citations.push({ kind: 'bib', symbol: match[1], line: lineAt(text, match.index), section: null });
+  }
+  const declarationRe = /\\(?:newcommand|renewcommand|providecommand)\s*\{\\([^}]+)\}(?:\s*\[[^\]]*\])?\s*\{([^{}]*)\}/g;
+  while ((match = declarationRe.exec(text))) {
+    const symbol = `\\${match[1]}`;
+    const declaration = { symbol, value: match[2], line: lineAt(text, match.index), section: sectionFor(sections, match.index)?.id ?? null };
+    declarations.push(declaration); values.push(declaration);
+  }
+  const labelRe = /\\label\s*\{([^}]+)\}/g;
+  while ((match = labelRe.exec(text))) labels.push({ symbol: match[1], line: lineAt(text, match.index), section: sectionFor(sections, match.index)?.id ?? null });
+  const refRe = /\\(ref|pageref|autoref|cref|Cref)\s*\{([^}]+)\}/g;
+  while ((match = refRe.exec(text))) refs.push({ kind: match[1], symbol: match[2], line: lineAt(text, match.index), section: sectionFor(sections, match.index)?.id ?? null, dynamic: /\\|\$|#/.test(match[2]) });
+  const citeRe = /\\cite[a-zA-Z*]*\s*(?:\[[^\]]*\]\s*)?\{([^}]+)\}/g;
+  while ((match = citeRe.exec(text))) for (const symbol of match[1].split(',').map(x => x.trim()).filter(Boolean)) citations.push({ kind: 'cite', symbol, line: lineAt(text, match.index), section: sectionFor(sections, match.index)?.id ?? null });
+  const includeRe = /\\(input|include|includegraphics)\s*(?:\[[^\]]*\])?\s*\{([^}]+)\}/g;
+  while ((match = includeRe.exec(text))) {
+    const item = { kind: match[1], target: match[2].trim(), line: lineAt(text, match.index), section: sectionFor(sections, match.index)?.id ?? null, dynamic: /\\|\$|#/.test(match[2]) };
+    (match[1] === 'includegraphics' ? graphics : includes).push(item);
+  }
+  return { file, hash, sections, declarations, labels, refs, citations, includes, graphics, values };
+}
+
+async function filesUnder(root, notices) {
+  const result = [];
+  async function walk(dir) {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch (error) { notices.push(`cannot read ${rel(root, dir)}: ${error.message}`); return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) { notices.push(`skipped symlink ${rel(root, full)}`); continue; }
+      if (entry.isDirectory()) { await walk(full); continue; }
+      if (entry.isFile() && /\.(?:tex|sty|cls|bib|bbx|cbx|ltx)$/i.test(entry.name)) result.push(full);
+    }
+  }
+  await walk(root);
+  return result.sort();
+}
+
+function resolveTarget(target, from, root, files) {
+  if (!target || /[\\$#]/.test(target)) return null;
+  const base = path.resolve(root, path.dirname(from), target);
+  const candidates = [base, ...(!path.extname(base) ? ['.tex', '.sty', '.cls', '.bib'].map(ext => `${base}${ext}`) : [])];
+  return candidates.find(candidate => files.has(rel(root, candidate))) ? rel(root, candidates.find(candidate => files.has(rel(root, candidate)))) : null;
+}
+
+function cap(list, limit, field, truncated) {
+  if (list.length <= limit) return list;
+  truncated[field] = true;
+  return list.slice(0, limit);
+}
+
+export async function dependencyIndex(root, { changedFiles = [], changedSymbols = [] } = {}) {
+  const rootReal = await realpath(root);
+  const notices = [];
+  const paths = await filesUnder(rootReal, notices);
+  const truncated = {};
+  const files = new Map();
+  const pathSet = new Set(paths.map(file => rel(rootReal, file)));
+  for (const file of paths.slice(0, MAX_FILES)) {
+    const relative = rel(rootReal, file);
+    const bytes = await readFile(file);
+    const hash = digest(bytes);
+    const key = `${rootReal}:${relative}`;
+    const old = parseCache.get(key);
+    const parsed = old?.hash === hash ? old : parseFile(relative, bytes.toString('utf8'), hash);
+    parseCache.set(key, parsed);
+    files.set(relative, parsed);
+  }
+  if (paths.length > MAX_FILES) truncated.files = true;
+  const labels = new Map();
+  const citations = new Map();
+  for (const file of files.values()) {
+    for (const label of file.labels) labels.set(label.symbol, { file: file.file, section: label.section, line: label.line });
+    for (const citation of file.citations) citations.set(citation.symbol, { file: file.file, section: citation.section, line: citation.line });
+  }
+  const edges = [];
+  const unresolved = [];
+  for (const file of files.values()) {
+    const add = (kind, item, target, symbol = null) => edges.push({ kind, from: { file: file.file, section: item.section, line: item.line }, to: target ? { file: target.file, section: target.section ?? null, line: target.line ?? null, symbol } : { symbol: target ?? symbol, unresolved: true } });
+    for (const item of file.refs) { const target = labels.get(item.symbol); add(item.kind, item, target, item.symbol); if (!target) unresolved.push({ kind: item.kind, file: file.file, section: item.section, line: item.line, symbol: item.symbol, dynamic: item.dynamic }); }
+    for (const item of file.citations) { const target = citations.get(item.symbol); add('cite', item, target, item.symbol); if (!target) unresolved.push({ kind: 'cite', file: file.file, section: item.section, line: item.line, symbol: item.symbol }); }
+    for (const item of [...file.includes, ...file.graphics]) { const targetFile = resolveTarget(item.target, file.file, rootReal, pathSet); add(item.kind, item, targetFile ? { file: targetFile } : item.target); if (!targetFile) unresolved.push({ kind: item.kind, file: file.file, section: item.section, line: item.line, symbol: item.target, dynamic: item.dynamic }); }
+  }
+  const changed = new Set();
+  for (const file of changedFiles) {
+    const candidate = path.resolve(rootReal, file);
+    if (!inside(rootReal, candidate)) throw new Error(`changed file must be inside root: ${file}`);
+    changed.add(rel(rootReal, candidate));
+  }
+  const affected = edges.filter(edge => changed.has(edge.to.file) || (edge.to.symbol && changedSymbols.includes(edge.to.symbol))).map(edge => edge.from);
+  const version = digest(JSON.stringify([...files].map(([file, value]) => [file, value.hash])));
+  return { version, files: cap([...files.values()].map(({ file, hash, sections, declarations }) => ({ file, hash, sections, symbols: declarations.map(item => item.symbol), definitions: declarations.slice(0, 200) })), MAX_FILES, 'files', truncated), edges: cap(edges, MAX_RESPONSE, 'edges', truncated), unresolved: cap(unresolved, MAX_RESPONSE, 'unresolved', truncated), affectedSections: cap([...new Map(affected.map(x => [x.file + '#' + x.section + ':' + x.line, x])).values()], MAX_RESPONSE, 'affectedSections', truncated), notices, truncated, truncatedFields: Object.keys(truncated) };
+}
+
+export async function changeReport(root, baselineVersion) {
+  const index = await dependencyIndex(root);
+  const key = await realpath(root);
+  const previous = baselineVersion ? snapshots.get(key)?.get(baselineVersion) : null;
+  const firstCall = !baselineVersion;
+  const baselineFound = firstCall || Boolean(previous);
+  const oldFiles = previous?.files ?? [];
+  const oldMap = new Map(oldFiles.map(file => [file.file, file]));
+  const currentMap = new Map(index.files.map(file => [file.file, file]));
+  const allFileNames = new Set([...oldMap.keys(), ...currentMap.keys()]);
+  const changedFiles = [...allFileNames].filter(file => oldMap.get(file)?.hash !== currentMap.get(file)?.hash).sort();
+  const removedFiles = [...oldMap.keys()].filter(file => !currentMap.has(file)).sort();
+  const changedFileSet = new Set(changedFiles);
+  const oldEdges = previous?.edges ?? [];
+  const affectedEdges = firstCall ? [] : [...index.edges, ...oldEdges].filter(edge => changedFileSet.has(edge.to.file));
+  const affectedSections = [...new Map(affectedEdges.map(edge => [edge.from.file + '#' + edge.from.section + ':' + edge.from.line, edge.from])).values()];
+  const notices = [...index.notices];
+  if (baselineVersion && !previous) notices.push(`baseline version not found: ${baselineVersion}; full refresh required`);
+  const changedFileHashes = Object.fromEntries(index.files.filter(file => changedFiles.includes(file.file)).map(file => [file.file, file.hash]));
+  const changedSections = [];
+  if (!firstCall && previous) {
+    for (const file of allFileNames) {
+      const before = new Map((oldMap.get(file)?.sections ?? []).map(section => [section.id, section]));
+      const after = new Map((currentMap.get(file)?.sections ?? []).map(section => [section.id, section]));
+      for (const id of new Set([...before.keys(), ...after.keys()])) {
+        if (before.get(id)?.hash !== after.get(id)?.hash) changedSections.push({ file, section: id, beforeHash: before.get(id)?.hash ?? null, hash: after.get(id)?.hash ?? null, removed: !after.has(id) });
+      }
+    }
+  }
+  const report = { version: index.version, baselineVersion: baselineVersion ?? null, baselineFound, fullRefreshRequired: Boolean(baselineVersion && !previous), firstCall, changedFiles: firstCall || !previous ? [] : changedFiles, removedFiles: firstCall || !previous ? [] : removedFiles, changedFileHashes, changedSections: cap(changedSections, MAX_RESPONSE, 'changedSections', index.truncated), affectedSections: cap(affectedSections, MAX_RESPONSE, 'affectedSections', index.truncated), affectedRefs: cap(affectedEdges, MAX_RESPONSE, 'affectedRefs', index.truncated), suggestions: firstCall || !previous ? [] : affectedSections.map(section => ({ file: section.file, section: section.section, action: 'review references and recompile' })), unresolved: index.unresolved, notices, truncated: index.truncated, truncatedFields: Object.keys(index.truncated) };
+  if (!snapshots.has(key)) snapshots.set(key, new Map());
+  snapshots.get(key).set(index.version, index);
+  const retained = snapshots.get(key);
+  while (retained.size > MAX_SNAPSHOTS) retained.delete(retained.keys().next().value);
+  return report;
+}