overleaf-forge 2.9.1 → 2.12.0

package/overleaf-mcp-server.js

@@ -13,6 +13,15 @@ import { execFile as execFileCallback } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import os from 'os';
+import { createHash } from 'node:crypto';
+import { dependencyIndex, changeReport } from './dependency-index.js';
+import { renderPages } from './render-cache.js';
+import { applyChanges, publishChanges } from './transactions.js';
+import { observeTool, usageStats, toolError } from './runtime-observability.js';
+import { versionedContext, buildFingerprint, sectionBundle, sectionText, controlledBuildOptions } from './efficiency.js';
+const verifiedBuilds = new Map();
+const recentPasses = new Map();
+const buildQueues = new Map();
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -85,10 +94,20 @@ const CONFIG_PATH = path.join(DATA_HOME, 'projects.json');
 const CONTEXTS_DIR = path.join(DATA_HOME, 'contexts');
 const DEFAULT_REPO_DIR = path.join(DATA_HOME, 'repos');
 const BUNDLED_TEMPLATES_DIR = path.join(PACKAGE_DIR, 'templates');
-// A user copy in the data home overrides the bundled default writing-guidelines.
-const GUIDELINES_PATH = existsSync(path.join(DATA_HOME, 'writing-guidelines.md'))
-  ? path.join(DATA_HOME, 'writing-guidelines.md')
-  : path.join(PACKAGE_DIR, 'writing-guidelines.md');
+// Guidelines resolve personal-first:
+//   1. <dataHome>/writing-guidelines.local.md  (gitignored; never ships)
+//   2. <dataHome>/writing-guidelines.md        (user copy, when dataHome is not the package)
+//   3. <packageDir>/writing-guidelines.md      (bundled generic default)
+// The .local name is what keeps a personal copy distinct when dataHome IS the
+// package dir (a local clone with projects.json), where 2 and 3 are one file.
+// Resolved per call so creating or deleting the local file needs no restart.
+export function resolveGuidelinesPath({ dataHome, packageDir, exists }) {
+  const local = path.join(dataHome, 'writing-guidelines.local.md');
+  if (exists(local)) return local;
+  const user = path.join(dataHome, 'writing-guidelines.md');
+  if (exists(user)) return user;
+  return path.join(packageDir, 'writing-guidelines.md');
+}
 
 // Where scaffold templates (main.tex skeleton, context-scaffold.md) are read.
 // Precedence: settings.templatesDir → $OVERLEAF_MCP_TEMPLATES → ~/.overleaf-mcp/
@@ -197,7 +216,8 @@ const SETTING_HELP = {
   ssaSubdir:    'What subfolder name should new SSAs go under inside each course folder? (e.g. "MY SSAs")',
   templatesDir: 'Use your own scaffold templates? Give the directory holding main.tex / context-scaffold.md (blank keeps the bundled examples).',
   voiceLinter:  'Use your own prose linter for voice_lint? Give the command (takes a file path, exits non-zero on findings; blank keeps the bundled example).',
-  gitToken:     'Overleaf git token (prefer the OVERLEAF_GIT_TOKEN env var; set here only if you must store it in projects.json).',
+  autoPush:     'Should edit tools push to Overleaf immediately (true), or commit locally until publish_changes sends a verified batch (false, the default)?',
+  gitToken:    'Overleaf git token (prefer the OVERLEAF_GIT_TOKEN env var; set here only if you must store it in projects.json).',
 };
 const SETTING_KEYS = Object.keys(SETTING_HELP);
 const SETTING_PATHY = new Set(['repoDir', 'academicRoot', 'templatesDir']);
@@ -218,6 +238,14 @@ export function mergeSettings(current, args, homeDir) {
   return { settings, provided };
 }
 
+// Whether a mutating tool pushes to Overleaf. An explicit per-call `push` wins,
+// then settings.autoPush; the default is false, so edits stay local commits
+// until publish_changes verifies and sends them in one deliberate step.
+export function resolvePush(settings, args) {
+  if (typeof args?.push === 'boolean') return args.push;
+  return settings?.autoPush === true;
+}
+
 // Default project resolution:
 //   1. explicit projectName argument
 //   2. project whose `cwd` is a prefix of SESSION_CWD (longest match wins)
@@ -321,23 +349,71 @@ class OverleafGitClient {
     }
     // Repair older clones that embedded the token in the remote URL.
     await this._git(['-C', this.repoPath, 'remote', 'set-url', 'origin', this.gitUrl]).catch(() => {});
+    const { stdout } = await this._git(['-C', this.repoPath, 'pull', '--ff-only'], { auth: true });
+    return stdout;
+  }
+
+  async requireLocal() {
+    if (!(await this._hasRepo())) throw Object.assign(new Error('Local clone missing; call sync_project explicitly.'), { code: 'LOCAL_CLONE_MISSING' });
+  }
+
+  // Mutations that push absorb remote edits first; local-only mutations stay
+  // off the network entirely, like reads.
+  async _prepareMutation(push) {
+    if (push) await this.cloneOrPull();
+    else await this.requireLocal();
+    await this._git(['-C', this.repoPath, 'config', 'user.email', 'claude@anthropic.com']);
+    await this._git(['-C', this.repoPath, 'config', 'user.name', 'Claude']);
+    return this._head();
+  }
+
+  async _head() {
+    const { stdout } = await this._git(['-C', this.repoPath, 'rev-parse', 'HEAD']);
+    return stdout.trim();
+  }
+
+  // HEAD plus the number of local commits not yet on the remote-tracking branch.
+  // unpublished is null when there is no tracking ref to compare against.
+  async pendingState() {
+    const head = await this._head();
+    const branch = await this._currentBranch();
+    let unpublished = null;
     try {
-      const { stdout } = await this._git(['-C', this.repoPath, 'pull', '--ff-only'], { auth: true });
-      return stdout;
-    } catch {
-      // Pull failed (diverged, or leftover changes from a prior failed write).
-      // Overleaf is the source of truth, so fetch and hard-reset to the remote
-      // tip rather than cascading into a clone-into-nonempty-dir error.
-      await this._git(['-C', this.repoPath, 'fetch', 'origin'], { auth: true });
-      const { stdout: br } = await this._git(['-C', this.repoPath, 'rev-parse', '--abbrev-ref', 'HEAD']);
-      const branch = (br || '').trim() || 'master';
-      await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]);
-      return `recovered: hard-reset to origin/${branch}`;
+      const { stdout } = await this._git(['-C', this.repoPath, 'rev-list', '--count', `origin/${branch}..HEAD`]);
+      unpublished = Number(stdout.trim());
+    } catch { /* no tracking ref */ }
+    return { head, unpublished };
+  }
+
+  // Finish a mutation whose commit is already made. push:false keeps it local
+  // for publish_changes. A refused push rolls back to preHead, this operation's
+  // own starting point: only its commit is undone, and earlier unpublished
+  // commits survive. (Resetting to origin/<branch> would silently drop them.)
+  async _finishMutation(preHead, push, { merge = false, refusal }) {
+    if (!push) return { pushed: false, committed: true, ...(await this.pendingState()) };
+    if (merge) return this._pushWithMerge(preHead);
+    try {
+      await this._git(['-C', this.repoPath, 'push', 'origin', 'HEAD'], { auth: true });
+    } catch (e) {
+      await this._git(['-C', this.repoPath, 'reset', '--hard', preHead]).catch(() => {});
+      throw new Error(`${refusal} (${(e.stderr || e.message || '').slice(0, 120)})`);
+    }
+    return { pushed: true };
+  }
+
+  // git commit that reports "nothing to commit" as a value instead of throwing.
+  async _commit(message) {
+    try {
+      await this._git(['-C', this.repoPath, 'commit', '-m', message]);
+      return true;
+    } catch (e) {
+      if (/nothing to commit/i.test((e.stdout || '') + (e.stderr || ''))) return false;
+      throw e;
     }
   }
 
   async listFiles(extension = '.tex') {
-    await this.cloneOrPull();
+    await this.requireLocal();
     const out = [];
     const walk = async (dir) => {
       const entries = await readdir(dir, { withFileTypes: true });
@@ -355,14 +431,16 @@ class OverleafGitClient {
   }
 
   async readFile(filePath) {
-    await this.cloneOrPull();
-    const fullPath = path.join(this.repoPath, filePath);
+    await this.requireLocal();
+    const root = realpathSync(this.repoPath);
+    const fullPath = realpathSync(path.resolve(root, filePath));
+    if (!fullPath.startsWith(root + path.sep)) throw Object.assign(new Error('File must be inside the project.'), { code: 'INVALID_INPUT' });
     return await readFile(fullPath, 'utf-8');
   }
 
   // git blob SHA of a file at the current tip; null if the file isn't tracked.
-  async getBlobSha(filePath, { pull = true } = {}) {
-    if (pull) await this.cloneOrPull();
+  async getBlobSha(filePath) {
+    await this.requireLocal();
     try {
       const { stdout } = await this._git(['-C', this.repoPath, 'rev-parse', `HEAD:${filePath}`]);
       return stdout.trim();
@@ -387,63 +465,179 @@ class OverleafGitClient {
   // Run latexmk from the repo root (so the project's .latexmkrc -- shell-escape,
   // the python@3.13 PATH fix for minted, $pdf_mode -- applies, and refs/citations/
   // reruns resolve). clean:true adds -gg to force a complete from-scratch rebuild.
-  async _runLatexmk(filePath, engine = 'lualatex', { clean = false } = {}) {
-    await this.cloneOrPull();
+  async _runLatexmk(filePath, engine = 'lualatex', { clean = false, controlled = false } = {}) {
+    const full = path.resolve(this.repoPath, filePath);
+    if (!full.startsWith(path.resolve(this.repoPath) + path.sep) || !filePath.endsWith('.tex') || filePath.startsWith('-')) throw new Error('Build entrypoint must be a .tex path inside the project.');
+    if (!(await this._hasRepo())) throw new Error('Local clone missing; call sync_project explicitly before building.');
     const engineFlag = { pdflatex: '-pdf', xelatex: '-xelatex', lualatex: '-lualatex' }[engine];
     if (!engineFlag) {
       throw new Error(`Invalid engine "${engine}". Choose from: pdflatex, xelatex, lualatex`);
     }
     const texbin = '/Library/TeX/texbin';
     const env = { ...process.env, PATH: `${texbin}:${process.env.PATH || ''}` };
-    const args = [engineFlag, '-interaction=nonstopmode', '-halt-on-error'];
+    const args = [engineFlag, '-interaction=nonstopmode', '-halt-on-error', '-recorder'];
+    // -norc must precede all other options so no user or project Perl config runs.
+    if (controlled) args.unshift('-norc', '-no-shell-escape');
     if (clean) args.push('-gg');
     args.push(filePath);
+    let commandFailed = false;
     const { stdout, stderr } = await execFile(
       path.join(texbin, 'latexmk'), args,
       { cwd: this.repoPath, timeout: 180000, maxBuffer: 20 * 1024 * 1024, env }
-    ).catch(e => ({ stdout: e.stdout || '', stderr: e.stderr || e.message }));
+    ).catch(e => { commandFailed = true; return { stdout: e.stdout || '', stderr: e.stderr || e.message }; });
     const pdfPath = path.join(this.repoPath, filePath.replace(/\.tex$/, '.pdf'));
     let pdfExists = false;
     try { await access(pdfPath); pdfExists = true; } catch { /* no pdf */ }
-    return { stdout, stderr, log: `${stdout}\n${stderr}`, pdfPath: pdfExists ? pdfPath : null };
+    return { stdout, stderr, commandFailed, log: `${stdout}\n${stderr}`, pdfPath: !commandFailed && pdfExists ? pdfPath : null };
+  }
+
+  async compileFile(filePath, engine = 'lualatex', options = {}) {
+    return this.verifyBuild(filePath, engine, { ...options, force: true, clean: false });
+  }
+
+  // Explicit sync. Fetches, then acts on the ahead/behind relation:
+  //   behind only        -> fast-forward
+  //   ahead only / equal -> nothing to do (ahead = unpublished local commits)
+  //   diverged           -> report both sides and change nothing, unless a
+  //                         strategy is chosen:
+  //     'rebase' replays local commits onto the remote; a conflict aborts back
+  //              to the untouched pre-sync state.
+  //     'reset'  discards local work to match the remote. Requires confirm to
+  //              equal the reported local HEAD (proof the report was read), and
+  //              tags the old HEAD and any uncommitted edits as mcp-backup/*
+  //              first, so nothing becomes unrecoverable.
+  async syncProject({ strategy, confirm } = {}) {
+    if (!(await this._hasRepo())) {
+      await this.cloneOrPull();
+      return { state: 'cloned', ...(await this.pendingState()) };
+    }
+    if (strategy !== undefined && strategy !== 'rebase' && strategy !== 'reset') {
+      throw new Error(`Unknown strategy "${strategy}". Use "rebase" or "reset".`);
+    }
+    const g = (args, opts) => this._git(['-C', this.repoPath, ...args], opts);
+    await g(['remote', 'set-url', 'origin', this.gitUrl]).catch(() => {});
+    await g(['fetch', 'origin'], { auth: true });
+    // rebase and stash create write commits, which need a committer identity.
+    await g(['config', 'user.email', 'claude@anthropic.com']);
+    await g(['config', 'user.name', 'Claude']);
+    const branch = await this._currentBranch();
+    const upstream = `origin/${branch}`;
+    const count = async range => Number((await g(['rev-list', '--count', range])).stdout.trim());
+    const ahead = await count(`${upstream}..HEAD`);
+    const behind = await count(`HEAD..${upstream}`);
+    const head = await this._head();
+    const dirty = (await g(['status', '--porcelain=v1', '--untracked-files=no'])).stdout.split('\n').filter(Boolean).map(l => l.slice(3));
+
+    if (strategy === 'reset') {
+      if (confirm !== head) {
+        throw new Error(`reset discards local work; pass confirm: "${head}" (the current local HEAD) after reviewing the sync_project report.`);
+      }
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const backups = [`mcp-backup/${stamp}`];
+      await g(['tag', backups[0], head]);
+      if (dirty.length) {
+        // stash create snapshots uncommitted tracked edits as a commit without
+        // touching the working tree; the tag keeps it reachable.
+        const wip = (await g(['stash', 'create', `mcp-backup ${stamp}`])).stdout.trim();
+        if (wip) { backups.push(`mcp-backup/${stamp}-wip`); await g(['tag', backups[1], wip]); }
+      }
+      await g(['reset', '--hard', upstream]);
+      return { state: 'reset', discardedCommits: ahead, discardedFiles: dirty, backups, ...(await this.pendingState()) };
+    }
+
+    if (behind === 0) return { state: ahead ? 'ahead' : 'up-to-date', ahead, behind, head, dirtyFiles: dirty };
+    if (ahead === 0) {
+      await g(['merge', '--ff-only', upstream]);
+      return { state: 'fast-forwarded', ahead, behind, ...(await this.pendingState()) };
+    }
+
+    const log = async range => (await g(['log', '--format=%h %s', '--name-only', range])).stdout.trim();
+    const report = {
+      state: 'diverged', ahead, behind, head, upstream: (await g(['rev-parse', upstream])).stdout.trim(),
+      localCommits: await log(`${upstream}..HEAD`), remoteCommits: await log(`HEAD..${upstream}`), dirtyFiles: dirty,
+      options: 'strategy:"rebase" replays local commits onto Overleaf (aborts cleanly on conflict); strategy:"reset" with confirm:<head> discards local work after tagging a backup.',
+    };
+    if (strategy !== 'rebase') return report;
+    if (dirty.length) throw new Error(`rebase needs a clean working tree; uncommitted edits in: ${dirty.join(', ')}. Commit them or choose reset.`);
+    try {
+      await g(['rebase', upstream]);
+    } catch {
+      const conflicts = (await g(['diff', '--name-only', '--diff-filter=U']).catch(() => ({ stdout: '' }))).stdout.trim().split('\n').filter(Boolean);
+      await g(['rebase', '--abort']).catch(() => {});
+      return { ...report, state: 'rebase-conflict', conflicts, note: 'Rebase aborted; local state is unchanged.' };
+    }
+    return { state: 'rebased', ...(await this.pendingState()) };
   }
 
-  async compileFile(filePath, engine = 'lualatex') {
-    const { log, pdfPath } = await this._runLatexmk(filePath, engine, { clean: false });
-    const errors = (log.match(/^!.*$/gm) || []).slice(0, 20);
-    const undefinedRefs = (log.match(/^(?:LaTeX|Package)[^\n]*Warning:[^\n]*(?:undefined|multiply)[^\n]*/gmi) || []);
-    const overfull = (log.match(/^(?:Overfull|Underfull)[^\n]*$/gm) || []).slice(0, 20);
-    return { pdfPath, errors, undefinedRefs, overfull, tail: log.slice(-2500) };
+  // options.lint (true = every .tex file, or an array of paths) adds the voice
+  // linter to the gate: findings fail it like an undefined reference does.
+  // Lint runs outside the build cache, so a reused build verdict is never
+  // mutated and lint always sees the current files.
+  async verifyBuild(filePath, engine = 'lualatex', options = {}) {
+    const key = path.resolve(this.repoPath);
+    const previous = buildQueues.get(key) || Promise.resolve();
+    const task = previous.catch(() => {}).then(() => this._verifyLocal(filePath, engine, options));
+    buildQueues.set(key, task);
+    let verdict;
+    try { verdict = await task; } finally { if (buildQueues.get(key) === task) buildQueues.delete(key); }
+    if (!options.lint) return verdict;
+    const files = Array.isArray(options.lint) ? options.lint : await this.listFiles('.tex');
+    const lint = await this.lintFiles(files, options.lintCommand);
+    return { ...verdict, lint, pass: verdict.pass && lint.clean };
   }
 
-  // Clean-from-scratch build + structured PASS/FAIL verdict on the "done" bar.
-  async verifyBuild(filePath, engine = 'lualatex') {
-    const { log: runLog, pdfPath } = await this._runLatexmk(filePath, engine, { clean: true });
-    // Classify the FINAL-pass log (e.g. main.log), NOT latexmk's concatenated
-    // multi-pass stdout: pass 1 (before the .aux exists) flags every \ref/\cite
-    // undefined, and those transient warnings would be false positives. main.log
-    // is the last engine run's output -- the true end state; a genuinely undefined
-    // ref persists there, a resolved one does not. Fall back to the run log if the
-    // .log file is missing (a catastrophic failure that produced no .log).
-    const logFile = path.join(this.repoPath, filePath.replace(/\.tex$/, '.log'));
+  async lintFiles(files, command) {
+    const results = [];
+    for (const file of files) results.push({ file, ...(await this.voiceLint(file, { command })) });
+    return { clean: results.every(r => r.clean), results };
+  }
+
+  async _verifyLocal(filePath, engine, options = {}) {
+    const { force = false, clean = true } = options;
+    const config = controlledBuildOptions(options);
+    // Resolved so the gate (client.repoPath) and publish (path.resolve(root)) share a key.
+    const key = JSON.stringify([path.resolve(this.repoPath),filePath,engine,config]);
+    const fingerprint = () => buildFingerprint(this.repoPath,filePath,engine,config).catch(()=>null);
+    const sources = () => buildFingerprint(this.repoPath,filePath,engine,{...config,sourcesOnly:true});
+    const cached = verifiedBuilds.get(key);
+    const before = await sources();
+    if (!force && cached && cached.fingerprint === await fingerprint()) return { ...cached.verdict, reused: true };
+    // publish_changes re-verifies a commit the final gate usually just passed.
+    // Projects with executable config (rc files, minted, shell escape) never
+    // qualify for the full cache above, so without this every publish would
+    // rebuild from scratch. Reuse is allowed only when every project file is
+    // byte-identical to the state right after that PASS (the sources hash
+    // covers tracked and untracked files, the environment and the day) within
+    // this process. Not covered: a TeX installation change in between.
+    const recent = recentPasses.get(key);
+    if (options.reuseRecentPass && !force && recent && recent.sources === before) return { ...recent.verdict, reused: true };
+    verifiedBuilds.delete(key);
+    const { log: runLog, pdfPath, commandFailed } = await this._runLatexmk(filePath,engine,{clean,controlled:config.controlled});
+    const logPath = path.join(this.repoPath,filePath.replace(/\.tex$/,'.log'));
     let finalLog = runLog;
-    try { finalLog = await readFile(logFile, 'utf-8'); } catch { /* keep runLog */ }
+    try { finalLog = await readFile(logPath,'utf8'); } catch { /* failed before log creation */ }
     const verdict = classifyBuildLog(finalLog);
-    // Confirm the PDF against the real file, not just the log, so a parser miss
-    // can't yield a false PASS; then recompute the verdict.
+    if (commandFailed) verdict.errors.push('latexmk command failed; any previous PDF is not a successful build.');
     verdict.pdfProduced = pdfPath !== null;
-    verdict.pass = verdict.pdfProduced
-      && verdict.errors.length === 0
-      && verdict.undefinedRefs.length === 0
-      && verdict.undefinedCitations.length === 0;
-    verdict.tail = finalLog.slice(-2500);
+    verdict.pass = verdict.pdfProduced && !verdict.errors.length && !verdict.undefinedRefs.length && !verdict.undefinedCitations.length;
+    verdict.logPath = logPath;
+    verdict.pdfPath = pdfPath;
+    verdict.tail = (commandFailed ? runLog : finalLog).slice(-2500);
+    verdict.reused = false;
+    const after = await sources();
+    if (before && before !== after) { verdict.pass = false; verdict.errors.push('Project inputs changed during the build; verify the latest source again.'); }
+    const print = before && before === after ? await fingerprint() : null;
+    verdict.cacheEligible = Boolean(print);
+    if (verdict.pass && print) verifiedBuilds.set(key,{ fingerprint:print,verdict });
+    if (verdict.pass && before === after) recentPasses.set(key, { sources: after, verdict });
+    else recentPasses.delete(key);
     return verdict;
   }
 
   // Read-only grep across tracked files. Regex by default; fixed -> -F; ignoreCase -> -i.
   async searchText({ query, fixed = false, ignoreCase = false, extension } = {}) {
     if (!query) throw new Error('search_text needs a query.');
-    await this.cloneOrPull();
+    await this.requireLocal();
     const args = ['-C', this.repoPath, 'grep', '-n', '--no-color', fixed ? '-F' : '-E'];
     if (ignoreCase) args.push('-i');
     args.push('-e', query);
@@ -458,34 +652,28 @@ class OverleafGitClient {
     }
   }
 
-  // Append a BibTeX entry to refs.bib (reject a duplicate key), commit, push.
-  async addCitation({ entry, commitMessage } = {}) {
+  // Append a BibTeX entry to refs.bib (reject a duplicate key), commit, and
+  // push when push is true.
+  async addCitation({ entry, commitMessage, push = true } = {}) {
     if (!entry || !entry.trim()) throw new Error('add_citation needs a BibTeX entry.');
     const m = entry.match(/@\w+\s*\{\s*([^,\s]+)/);
     if (!m) throw new Error('Could not find a BibTeX key in the entry (expected @type{key, ...}).');
     const key = m[1];
-    await this.cloneOrPull();
+    const preHead = await this._prepareMutation(push);
     const bibPath = path.join(this.repoPath, 'refs.bib');
     let current = '';
     try { current = await readFile(bibPath, 'utf-8'); } catch { /* missing -> create */ }
     const dup = new RegExp(`@\\w+\\s*\\{\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*,`);
     if (dup.test(current)) throw new Error(`citation key "${key}" already in refs.bib.`);
     await writeFile(bibPath, current.replace(/\s*$/, '') + '\n\n' + entry.trim() + '\n', 'utf-8');
-    await this._git(['-C', this.repoPath, 'config', 'user.email', 'claude@anthropic.com']);
-    await this._git(['-C', this.repoPath, 'config', 'user.name', 'Claude']);
     await this._git(['-C', this.repoPath, 'add', '--', 'refs.bib']);
-    try {
-      await this._git(['-C', this.repoPath, 'commit', '-m', commitMessage || `Add citation ${key}`]);
-    } catch (e) {
-      if (/nothing to commit/i.test((e.stdout || '') + (e.stderr || ''))) return { pushed: false, reason: 'nothing to commit', key };
-      throw e;
-    }
-    return { ...(await this._pushWithMerge()), key };
+    if (!(await this._commit(commitMessage || `Add citation ${key}`))) return { pushed: false, reason: 'nothing to commit', key };
+    return { ...(await this._finishMutation(preHead, push, { merge: true })), key };
   }
 
   // Read-only: cited keys (across .tex) vs defined keys (refs.bib).
   async citeLint() {
-    await this.cloneOrPull();
+    await this.requireLocal();
     const texFiles = await this.listFiles('.tex');
     const citeRe = /\\(?:cite|autocite|parencite|citep|citet|textcite|footcite|nocite)\*?(?:\[[^\]]*\])*\{([^}]+)\}/g;
     const cited = new Set();
@@ -519,7 +707,7 @@ class OverleafGitClient {
 
   // Local rollback point: a lightweight tag mcp-snap/<label> at HEAD (not pushed).
   async checkpoint(label) {
-    await this.cloneOrPull();
+    await this.requireLocal();
     const name = `mcp-snap/${(label && label.trim()) || `snap-${Date.now()}`}`;
     let exists = false;
     try { await this._git(['-C', this.repoPath, 'rev-parse', '--verify', '--quiet', `refs/tags/${name}`]); exists = true; } catch { exists = false; }
@@ -529,10 +717,12 @@ class OverleafGitClient {
     return { label: name, head: stdout.trim() };
   }
 
-  // Forward-restore the snapshot's tree as a new commit on top of HEAD, then push.
-  // No history rewrite, no force-push (the new commit descends from HEAD).
-  async restore(label) {
-    await this.cloneOrPull();
+  // Forward-restore the snapshot's tree as a new commit on top of HEAD, pushed
+  // when push is true. No history rewrite, no force-push (the new commit
+  // descends from HEAD). The fast-forward refuses rather than overwriting
+  // uncommitted local edits to files the restore would change.
+  async restore(label, { push = true } = {}) {
+    const preHead = await this._prepareMutation(push);
     const name = String(label || '').startsWith('mcp-snap/') ? label : `mcp-snap/${label}`;
     let tree;
     try { ({ stdout: tree } = await this._git(['-C', this.repoPath, 'rev-parse', `${name}^{tree}`])); }
@@ -541,19 +731,10 @@ class OverleafGitClient {
       throw new Error(`snapshot "${name}" not found. Available: ${tags || '(none)'}`);
     }
     tree = tree.trim();
-    await this._git(['-C', this.repoPath, 'config', 'user.email', 'claude@anthropic.com']);
-    await this._git(['-C', this.repoPath, 'config', 'user.name', 'Claude']);
     const { stdout: commit } = await this._git(['-C', this.repoPath, 'commit-tree', tree, '-p', 'HEAD', '-m', `restore: ${name}`]);
-    await this._git(['-C', this.repoPath, 'reset', '--hard', commit.trim()]);
-    try {
-      await this._git(['-C', this.repoPath, 'push', 'origin', 'HEAD'], { auth: true });
-    } catch (e) {
-      const branch = await this._currentBranch();
-      await this._git(['-C', this.repoPath, 'fetch', 'origin'], { auth: true }).catch(() => {});
-      await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]).catch(() => {});
-      throw new Error(`restore: Overleaf moved during the rollback; refused. Re-run after re-pulling. (${(e.stderr || e.message || '').slice(0, 120)})`);
-    }
-    return { pushed: true, label: name, restoredTo: tree };
+    await this._git(['-C', this.repoPath, 'merge', '--ff-only', commit.trim()]);
+    const res = await this._finishMutation(preHead, push, { refusal: 'restore: Overleaf moved during the rollback; refused. Run sync_project, then retry.' });
+    return { ...res, label: name, restoredTo: tree };
   }
 
   // Run the configured voice linter on a file; advisory, read-only.
@@ -605,9 +786,11 @@ class OverleafGitClient {
   }
 
   // Push origin HEAD. If the remote moved during the op (non-fast-forward),
-  // let git 3-way merge it: clean merge -> push; real conflict -> abort, reset
-  // to the remote tip, and throw (so nothing half-applied is left behind).
-  async _pushWithMerge() {
+  // let git 3-way merge it: clean merge -> push; real conflict -> abort, roll
+  // back to preHead (the state before this operation's commit), and throw, so
+  // nothing half-applied is left behind and earlier local commits survive.
+  async _pushWithMerge(preHead) {
+    if (!preHead) throw new Error('_pushWithMerge needs the pre-operation HEAD to roll back to.');
     try {
       await this._git(['-C', this.repoPath, 'push', 'origin', 'HEAD'], { auth: true });
       return { pushed: true, merged: false };
@@ -618,15 +801,15 @@ class OverleafGitClient {
         await this._git(['-C', this.repoPath, 'merge', '--no-edit', `origin/${branch}`]);
       } catch (mergeErr) {
         await this._git(['-C', this.repoPath, 'merge', '--abort']).catch(() => {});
-        await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]);
-        const e = new Error('conflict: the file changed on Overleaf in a way that overlaps this edit. Re-read the file and retry.');
+        await this._git(['-C', this.repoPath, 'reset', '--hard', preHead]);
+        const e = new Error('conflict: the file changed on Overleaf in a way that overlaps this edit. Run sync_project, re-read the file and retry.');
         e.cause = mergeErr;
         throw e;
       }
       try {
         await this._git(['-C', this.repoPath, 'push', 'origin', 'HEAD'], { auth: true });
       } catch (e2) {
-        await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]).catch(() => {});
+        await this._git(['-C', this.repoPath, 'reset', '--hard', preHead]).catch(() => {});
         const e = new Error('conflict: Overleaf moved again while merging; reset clean — re-read the file and retry.');
         e.cause = e2;
         throw e;
@@ -639,10 +822,10 @@ class OverleafGitClient {
   // files: require either a matching baseSha (proves freshness) or overwrite:true
   // (a deliberate clobber). A stale baseSha is refused, never merged.
   async writeFile(filePath, content, opts = {}) {
-    const { baseSha, overwrite = false, commitMessage } = opts;
-    await this.cloneOrPull();
+    const { baseSha, overwrite = false, commitMessage, push = true } = opts;
+    const preHead = await this._prepareMutation(push);
     const fullPath = path.join(this.repoPath, filePath);
-    const current = await this.getBlobSha(filePath, { pull: false }); // null if new
+    const current = await this.getBlobSha(filePath); // null if new
 
     if (current !== null) {
       if (baseSha != null) {
@@ -656,28 +839,10 @@ class OverleafGitClient {
 
     await mkdir(path.dirname(fullPath), { recursive: true });
     await writeFile(fullPath, content, 'utf-8');
-    await this._git(['-C', this.repoPath, 'config', 'user.email', 'claude@anthropic.com']);
-    await this._git(['-C', this.repoPath, 'config', 'user.name', 'Claude']);
     await this._git(['-C', this.repoPath, 'add', '--', filePath]);
-    try {
-      await this._git(['-C', this.repoPath, 'commit', '-m', commitMessage || `Update ${filePath} via Claude`]);
-    } catch (e) {
-      if (/nothing to commit/i.test((e.stdout || '') + (e.stderr || ''))) {
-        return { pushed: false, reason: 'nothing to commit' };
-      }
-      throw e;
-    }
+    if (!(await this._commit(commitMessage || `Update ${filePath} via Claude`))) return { pushed: false, reason: 'nothing to commit' };
     // write_file refuses on a push race rather than merging (conflict-refuse policy).
-    try {
-      await this._git(['-C', this.repoPath, 'push', 'origin', 'HEAD'], { auth: true });
-    } catch (e) {
-      const branch = await this._currentBranch();
-      await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]).catch(() => {});
-      await this._git(['-C', this.repoPath, 'fetch', 'origin'], { auth: true }).catch(() => {});
-      await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]).catch(() => {});
-      throw new Error(`${filePath}: Overleaf moved while writing; refused to overwrite. Re-read and retry. (${(e.stderr || e.message || '').slice(0, 120)})`);
-    }
-    return { pushed: true };
+    return this._finishMutation(preHead, push, { refusal: `${filePath}: Overleaf moved while writing; refused to overwrite. Run sync_project, re-read and retry.` });
   }
 
   // Upload binary file(s) from local disk into the clone and push. Single mode:
@@ -686,7 +851,7 @@ class OverleafGitClient {
   // Binary never 3-way-merges, so a push race refuses + resets like writeFile.
   // baseSha freshness applies in single mode only; existing files in batch mode
   // require overwrite:true.
-  async uploadFile({ srcPath, destPath, files, baseSha, overwrite = false, commitMessage } = {}) {
+  async uploadFile({ srcPath, destPath, files, baseSha, overwrite = false, commitMessage, push = true } = {}) {
     let pairs;
     const batch = Array.isArray(files);
     if (batch) {
@@ -699,7 +864,7 @@ class OverleafGitClient {
       throw new Error('upload_file needs srcPath+destPath (single) or files:[{srcPath,destPath}] (batch).');
     }
 
-    await this.cloneOrPull();
+    const preHead = await this._prepareMutation(push);
     const repoAbs = path.resolve(this.repoPath);
     const resolved = [];
     for (const { src, dest } of pairs) {
@@ -711,7 +876,7 @@ class OverleafGitClient {
       if (destAbs === repoAbs || rel.startsWith('..') || path.isAbsolute(rel) || rel.split(path.sep)[0] === '.git') {
         throw new Error(`destPath escapes the project or is not allowed: ${dest}`);
       }
-      const current = await this.getBlobSha(rel, { pull: false });
+      const current = await this.getBlobSha(rel);
       if (current !== null) {
         if (!batch && baseSha != null) {
           if (baseSha !== current) {
@@ -729,34 +894,21 @@ class OverleafGitClient {
       await copyFile(src, destAbs);
     }
 
-    await this._git(['-C', this.repoPath, 'config', 'user.email', 'claude@anthropic.com']);
-    await this._git(['-C', this.repoPath, 'config', 'user.name', 'Claude']);
-    await this._git(['-C', this.repoPath, 'add', '--', ...resolved.map(r => r.rel)]);
-    try {
-      await this._git(['-C', this.repoPath, 'commit', '-m', commitMessage || `Upload ${resolved.length} file(s) via Claude`]);
-    } catch (e) {
-      if (/nothing to commit/i.test((e.stdout || '') + (e.stderr || ''))) {
-        return { pushed: false, reason: 'nothing to commit (identical to repo)', files: resolved.map(r => r.rel) };
-      }
-      throw e;
+    const rels = resolved.map(r => r.rel);
+    await this._git(['-C', this.repoPath, 'add', '--', ...rels]);
+    if (!(await this._commit(commitMessage || `Upload ${resolved.length} file(s) via Claude`))) {
+      return { pushed: false, reason: 'nothing to commit (identical to repo)', files: rels };
     }
-    try {
-      await this._git(['-C', this.repoPath, 'push', 'origin', 'HEAD'], { auth: true });
-    } catch (e) {
-      const branch = await this._currentBranch();
-      await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]).catch(() => {});
-      await this._git(['-C', this.repoPath, 'fetch', 'origin'], { auth: true }).catch(() => {});
-      await this._git(['-C', this.repoPath, 'reset', '--hard', `origin/${branch}`]).catch(() => {});
-      throw new Error(`Overleaf moved while uploading; refused. Re-read and retry. (${(e.stderr || e.message || '').slice(0, 120)})`);
-    }
-    return { pushed: true, files: resolved.map(r => r.rel) };
+    const res = await this._finishMutation(preHead, push, { refusal: 'Overleaf moved while uploading; refused. Run sync_project and retry.' });
+    return { ...res, files: rels };
   }
 
-  // Anchored, conflict-safe edit. Pulls first (absorbing non-overlapping Overleaf
-  // edits), then replaces oldString. A missing anchor means the user changed that
-  // region (overlap) or the string was wrong -> refuse, nothing written.
-  async editFile(filePath, oldString, newString, replaceAll = false, commitMessage) {
-    await this.cloneOrPull();
+  // Anchored, conflict-safe edit. When pushing, pulls first (absorbing
+  // non-overlapping Overleaf edits); local-only edits never touch the network.
+  // A missing anchor means the region changed (overlap) or the string was
+  // wrong -> refuse, nothing written.
+  async editFile(filePath, oldString, newString, replaceAll = false, commitMessage, { push = true } = {}) {
+    const preHead = await this._prepareMutation(push);
     const fullPath = path.join(this.repoPath, filePath);
     let content;
     try { content = await readFile(fullPath, 'utf-8'); }
@@ -772,39 +924,41 @@ class OverleafGitClient {
     }
     const updated = replaceAll ? parts.join(newString) : content.replace(oldString, () => newString);
     await writeFile(fullPath, updated, 'utf-8');
-
-    await this._git(['-C', this.repoPath, 'config', 'user.email', 'claude@anthropic.com']);
-    await this._git(['-C', this.repoPath, 'config', 'user.name', 'Claude']);
     await this._git(['-C', this.repoPath, 'add', '--', filePath]);
-    try {
-      await this._git(['-C', this.repoPath, 'commit', '-m', commitMessage || `Edit ${filePath} via Claude`]);
-    } catch (e) {
-      if (/nothing to commit/i.test((e.stdout || '') + (e.stderr || ''))) {
-        return { pushed: false, reason: 'no change (new === old)' };
-      }
-      throw e;
-    }
-    return await this._pushWithMerge();
+    if (!(await this._commit(commitMessage || `Edit ${filePath} via Claude`))) return { pushed: false, reason: 'no change (new === old)' };
+    return this._finishMutation(preHead, push, { merge: true });
   }
 
+  // Same slicing as the bundle (sectionText): runs to the next heading of the
+  // same or higher level, covers \paragraph, and refuses an ambiguous title
+  // rather than silently returning the first match.
   async getSectionContent(filePath, sectionTitle) {
-    const content = await this.readFile(filePath);
-    const sections = await this.getSections(filePath);
-    const target = sections.find(s => s.title === sectionTitle);
-    if (!target) {
-      throw new Error(`Section "${sectionTitle}" not found`);
-    }
-    // The body runs until the next heading of the SAME or HIGHER level, so a
-    // \section keeps its \subsections instead of being cut at the first one.
-    const rank = { section: 1, subsection: 2, subsubsection: 3 };
-    const next = sections.find(s => s.index > target.index && rank[s.type] <= rank[target.type]);
-    const endIdx = next ? next.index : content.length;
-    return content.substring(target.index, endIdx);
+    return sectionText(await this.readFile(filePath), sectionTitle);
   }
 }
 
 export { OverleafGitClient };
 
+// settings.voiceLinter / $OVERLEAF_VOICE_LINTER override the bundled example
+// linter, which ships with the package so voice_lint works out of the box. The
+// example implements generic prose checks; point the setting at your own
+// command to enforce a house style.
+function voiceLinterCommand(config) {
+  return config.settings?.voiceLinter
+    || process.env.OVERLEAF_VOICE_LINTER
+    || `node ${path.join(PACKAGE_DIR, 'examples', 'voice-lint.mjs')}`;
+}
+
+// What a mutating tool reports: pushed, or committed locally with the count of
+// commits still waiting for publish_changes.
+function mutationTail(res, what) {
+  if (res.pushed) return `${what} and pushed to Overleaf${res.merged ? ' (auto-merged a concurrent Overleaf change)' : ''}.`;
+  // The full hash is what publish_changes takes as revision; the workflow
+  // itself lives in the tool descriptions, not in every reply.
+  const n = res.unpublished == null ? '' : `, ${res.unpublished} unpublished`;
+  return `${what}; committed locally at ${res.head}${n}.`;
+}
+
 async function getClient(projectName) {
   const config = await loadConfig();
   const key = pickProjectKey(config, projectName);
@@ -973,12 +1127,21 @@ const server = new Server(
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    ...[
+      ['dependency_index', 'Local static TeX dependencies and affected sections. Dynamic macros are reported as unresolved.', { changedFiles: { type: 'array', items: { type: 'string' } }, changedSymbols: { type: 'array', items: { type: 'string' } } }, []],
+      ['change_report', 'Compact local file and section changes against an in-process baseline. Omit baselineVersion to establish one.', { baselineVersion: { type: 'string' } }, []],
+      ['render_pages', 'Render explicitly selected PDF pages to cached local PNG paths. Pages are one-based; no sync or build.', { filePath: { type: 'string' }, pages: { type: 'array', items: { type: 'integer', minimum: 1 }, minItems: 1, maxItems: 20 }, dpi: { type: 'integer', minimum: 36, maximum: 300 } }, ['filePath', 'pages']],
+      ['usage_stats', 'In-process tool counts, durations, response bytes and cache hits. Stores no document content. Bytes are not billed tokens.', { reset: { type: 'boolean' } }, []],
+      ['apply_changes', 'Verify a UTF-8 multi-file batch in an isolated worktree, then commit it locally. Requires clean tracked source, HEAD baseRevision and SHA-256 baseHash per file (null for new files). No push.', { baseRevision: { type: 'string' }, changes: { type: 'array', minItems: 1, maxItems: 100, items: { type: 'object', properties: { filePath: { type: 'string' }, baseHash: { type: ['string', 'null'] }, content: { type: 'string' } }, required: ['filePath', 'baseHash', 'content'] } }, filePath: { type: 'string' }, engine: { type: 'string' }, controlled: { type: 'boolean' }, externalInputs: { type: 'array', items: { type: 'string' } }, lint: { anyOf: [{ type: 'boolean' }, { type: 'array', items: { type: 'string' } }] } }, ['baseRevision', 'changes', 'filePath']],
+      ['publish_changes', 'Verify the clean local HEAD and push every unpublished commit once. revision must equal HEAD. Reuses this session\'s verify_build PASS when no project file changed since; force rebuilds. No pull, merge or retry: if Overleaf moved, sync_project first. Needs publishing authorization.', { revision: { type: 'string' }, force: { type: 'boolean' }, filePath: { type: 'string' }, engine: { type: 'string' }, controlled: { type: 'boolean' }, externalInputs: { type: 'array', items: { type: 'string' } }, lint: { anyOf: [{ type: 'boolean' }, { type: 'array', items: { type: 'string' } }] } }, ['revision', 'filePath']],
+    ].map(([name, description, properties, required]) => ({ name, description, inputSchema: { type: 'object', properties: { projectName: { type: 'string' }, ...properties }, required } })),
     {
       name: 'get_context',
-      description: 'Read writing guidelines + per-project context. Always call this at the start of any writing or editing session, and re-read whenever instructions feel forgotten. Both the guidelines and the project context md are re-read from disk on every call, so external edits take effect immediately without restarting.',
+      description: 'Read current writing and project context. Supply previousVersion to receive a compact unchanged response when content and project identity match.',
       inputSchema: {
         type: 'object',
         properties: {
+          previousVersion: { type: 'string', description: 'Version returned by the previous context read.' },
           projectName: { type: 'string', description: 'Project key. Omit to auto-detect from current working directory.' },
         },
       },
@@ -1019,7 +1182,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'configure',
-      description: 'Set up or update overleaf-forge\'s global settings: the scaffold templates directory, the voice_lint command, and the recurring-work settings bootstrap_ssa uses (academic root, SSA subdir, default clone dir). FIRST call this with NO arguments to see the current settings and which are unset, with a question for each; ask the user those questions in turn; THEN call it again with their answers to write them to projects.json. Omit a field to leave it unchanged; pass an empty string to clear it back to the bundled default. The git token is redacted in all output. Intended right after install to configure the server conversationally.',
+      description: 'Set up or update overleaf-forge\'s global settings: the scaffold templates directory, the voice_lint command, the edit push policy (autoPush), and the recurring-work settings bootstrap_ssa uses (academic root, SSA subdir, default clone dir). FIRST call this with NO arguments to see the current settings and which are unset, with a question for each; ask the user those questions in turn; THEN call it again with their answers to write them to projects.json. Omit a field to leave it unchanged; pass an empty string to clear it back to the bundled default. The git token is redacted in all output. Intended right after install to configure the server conversationally.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -1028,6 +1191,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           ssaSubdir: { type: 'string', description: 'Subfolder name created under each course folder for new SSAs, e.g. "MY SSAs".' },
           templatesDir: { type: 'string', description: 'Directory of your scaffold templates (main.tex, context-scaffold.md), overriding the bundled examples. ~ expanded. Empty string reverts to bundled.' },
           voiceLinter: { type: 'string', description: 'Prose-linter command for voice_lint (takes a file path, exits non-zero on findings), overriding the bundled example. Empty string reverts to bundled.' },
+          autoPush: { type: 'boolean', description: 'true: edit tools push immediately. false (default): they commit locally and publish_changes sends the verified batch.' },
           gitToken: { type: 'string', description: 'Overleaf git token. Prefer the OVERLEAF_GIT_TOKEN env var; set here only to store it in projects.json.' },
         },
       },
@@ -1107,38 +1271,42 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['filePath'],
       },
     },
+    {
+      name: 'sync_project',
+      description: 'Fetch Overleaf. Fast-forwards when behind; reports unpublished commits when ahead. On divergence it changes nothing and reports both sides unless strategy is "rebase" (aborts cleanly on conflict) or "reset" (needs confirm = the reported head; tags mcp-backup/* first). Clones a missing project.',
+      inputSchema: { type: 'object', properties: {
+        strategy: { type: 'string', enum: ['rebase', 'reset'], description: 'Only for a diverged clone. Omit to get the report first.' },
+        confirm: { type: 'string', description: 'For strategy "reset": the full local head SHA from the report.' },
+        projectName: { type: 'string' },
+      } },
+    },
     {
       name: 'get_section_content',
-      description: 'Get the body of a single section by title.',
+      description: 'Read one section (\\section to \\paragraph) by exact title from the local clone; no pull. The title must be unique in the file. bundle:true also returns the equation/figure blocks it references, matching bibliography entries and asset paths as JSON, reporting unresolved references and truncation (not a recursive TeX parser).',
       inputSchema: {
         type: 'object',
         properties: {
           filePath: { type: 'string' },
           sectionTitle: { type: 'string' },
+          bundle: { type: 'boolean', default: false, description: 'Include referenced blocks, bibliography entries and assets.' },
+          maxChars: { type: 'integer', minimum: 2000, maximum: 64000, description: 'bundle only: response budget (default 16000).' },
           projectName: { type: 'string' },
         },
         required: ['filePath', 'sectionTitle'],
       },
     },
-    {
-      name: 'compile_file',
-      description: 'Compile a .tex file locally with LuaLaTeX (default), XeLaTeX, or pdfLaTeX. Pulls before compiling. ALWAYS run this after write_file before declaring work done — silent build breakage is the most common failure mode.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          filePath: { type: 'string' },
-          engine: { type: 'string', description: 'pdflatex | xelatex | lualatex (default lualatex)' },
-          projectName: { type: 'string' },
-        },
-        required: ['filePath'],
-      },
-    },
     {
       name: 'verify_build',
-      description: 'Compile the entrypoint FROM SCRATCH (clean aux) and return a PASS/FAIL verdict on the done-bar: PASS only if a PDF is produced with zero LaTeX errors, zero undefined references, and zero undefined citations. Reports page count; overfull/underfull boxes are warnings, not failures. Use as the final gate before declaring a writing task done.',
+      description: 'Build the entrypoint and return PASS/FAIL. PASS needs a PDF, zero LaTeX errors and zero undefined references and citations (and zero findings with lint); box warnings do not fail. Default: clean from-scratch final gate, reusing an unchanged eligible PASS unless force. clean:false: quick incremental rebuild for intermediate checks. Local only.',
       inputSchema: {
         type: 'object',
         properties: {
+          clean: { type: 'boolean', default: true, description: 'false = quick incremental rebuild that always recompiles (intermediate checks); true = from-scratch final gate.' },
+          lint: { description: 'Also run the voice linter as part of the gate: true for every .tex file, or an array of paths. Findings fail the verdict.', anyOf: [{ type: 'boolean' }, { type: 'array', items: { type: 'string' } }] },
+          controlled: { type: 'boolean', default: false, description: 'Ignore all latexmk rc files and disable shell escape. Opt in only when the project supports this mode.' },
+          externalInputs: { type: 'array', items: { type: 'string' }, description: 'Absolute paths of additional build inputs to hash.' },
+          verbose: { type: 'boolean', default: false, description: 'Include a bounded log tail; full log remains on disk.' },
+          force: { type: 'boolean', default: false, description: 'Ignore a cached verification and rebuild.' },
           filePath: { type: 'string', description: 'The entrypoint, usually main.tex.' },
           engine: { type: 'string', description: 'pdflatex | xelatex | lualatex (default lualatex).' },
           projectName: { type: 'string' },
@@ -1148,7 +1316,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'edit_file',
-      description: 'Surgical, conflict-safe edit: replace oldString with newString in a file, then commit and push. PREFER this over write_file for edits to existing files — it is far cheaper than a full rewrite and it cannot silently clobber a concurrent Overleaf edit (a missing oldString means the region changed; the edit refuses). Non-overlapping concurrent edits auto-merge. oldString must match exactly once unless replaceAll is true. After editing, call compile_file to verify the build.',
+      description: 'Anchored edit: replace oldString (must match once unless replaceAll) with newString and commit. A missing anchor means the region changed, so the edit refuses instead of clobbering it. Prefer over write_file for existing files. Commits locally unless push.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -1157,6 +1325,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           newString: { type: 'string', description: 'Replacement text.' },
           replaceAll: { type: 'boolean', description: 'Replace every occurrence (default false; otherwise oldString must be unique).' },
           commitMessage: { type: 'string' },
+          push: { type: 'boolean', description: 'Push now. Default settings.autoPush; false keeps a local commit for publish_changes.' },
           projectName: { type: 'string' },
         },
         required: ['filePath', 'oldString', 'newString'],
@@ -1164,7 +1333,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'write_file',
-      description: 'Create a new file, or overwrite an existing one wholesale, then push. For edits to existing files prefer edit_file. Overwriting an existing file requires either baseSha (from read_file, so a stale write is refused) or overwrite:true. After writing, call compile_file to verify the build.',
+      description: 'Create a file or replace one wholesale, and commit. Replacing needs baseSha from read_file (a stale one is refused) or overwrite:true. Prefer edit_file for changes. Commits locally unless push.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -1173,6 +1342,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           baseSha: { type: 'string', description: 'The baseSha from read_file for this file. Required to overwrite an existing file safely; if Overleaf moved since, the write is refused.' },
           overwrite: { type: 'boolean', description: 'Force-overwrite an existing file without a baseSha (deliberate full replacement). Ignored for new files.' },
           commitMessage: { type: 'string' },
+          push: { type: 'boolean', description: 'Push now. Default settings.autoPush; false keeps a local commit for publish_changes.' },
           projectName: { type: 'string' },
         },
         required: ['filePath', 'content'],
@@ -1180,7 +1350,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'upload_file',
-      description: 'Upload a binary file (PNG/PDF figure, etc.) from a local disk path INTO the Overleaf project and push. write_file/edit_file are UTF-8 only — use this for binaries. Single: srcPath + destPath. Batch (one commit for a figure set): files: [{srcPath, destPath}, ...]. Existing dest files need baseSha (single mode, from read_file) or overwrite:true. After uploading, reference each figure with \\includegraphics{...} via edit_file, then compile_file.',
+      description: 'Copy binary file(s) such as figures from a local path into the project and commit. Single: srcPath + destPath; batch: files[] in one commit. Existing destinations need baseSha (single) or overwrite:true. Commits locally unless push.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -1194,6 +1364,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           baseSha: { type: 'string', description: 'Single-file mode only: baseSha from read_file; a stale value is refused. Ignored in batch.' },
           overwrite: { type: 'boolean', description: 'Replace existing dest file(s). Required to overwrite in batch mode.' },
           commitMessage: { type: 'string' },
+          push: { type: 'boolean', description: 'Push now. Default settings.autoPush; false keeps a local commit for publish_changes.' },
           projectName: { type: 'string' },
         },
       },
@@ -1215,12 +1386,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'add_citation',
-      description: 'Append a BibTeX entry (raw @type{key, ...} string) to refs.bib and push. Refuses if the key already exists. Creates refs.bib if absent.',
+      description: 'Append a BibTeX entry (raw @type{key, ...} string) to refs.bib and commit (local by default; see push). Refuses if the key already exists. Creates refs.bib if absent.',
       inputSchema: {
         type: 'object',
         properties: {
           entry: { type: 'string', description: 'A complete BibTeX entry, e.g. @article{key, title={...}, ...}.' },
           commitMessage: { type: 'string' },
+          push: { type: 'boolean', description: 'Push now. Default settings.autoPush; false keeps a local commit for publish_changes.' },
           projectName: { type: 'string' },
         },
         required: ['entry'],
@@ -1238,12 +1410,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'restore',
-      description: 'Roll back to a checkpoint: re-applies the snapshot\'s file tree as a NEW commit on top of history and pushes (no force-push, no history rewrite). Overleaf reflects the rollback; intervening commits are preserved.',
-      inputSchema: { type: 'object', properties: { label: { type: 'string' }, projectName: { type: 'string' } }, required: ['label'] },
+      description: 'Roll back to a checkpoint: re-applies the snapshot\'s file tree as a NEW commit on top of history (no force-push, no history rewrite); intervening commits are preserved. Local by default; see push.',
+      inputSchema: { type: 'object', properties: { label: { type: 'string' }, push: { type: 'boolean', description: 'Push now. Default settings.autoPush; false keeps a local commit for publish_changes.' }, projectName: { type: 'string' } }, required: ['label'] },
     },
     {
       name: 'voice_lint',
-      description: 'Lint a .tex file for prose issues. Runs a bundled generic example linter by default; override with settings.voiceLinter in projects.json or the OVERLEAF_VOICE_LINTER env var (a command that takes a file path and exits non-zero on findings). Lints the LOCAL working copy as-is and never pulls, so it reflects on-disk state including edits not yet pushed; if the project has not been cloned locally yet it errors rather than fetching. Read-only and advisory: reports output, never blocks. Useful after editing prose via edit_file/write_file, which bypass any local editor hooks.',
+      description: 'Run the prose linter (settings.voiceLinter, else the bundled example) on a local .tex file; never pulls. Advisory on its own; verify_build with lint makes findings fail the gate.',
       inputSchema: {
         type: 'object',
         properties: { filePath: { type: 'string' }, projectName: { type: 'string' } },
@@ -1261,7 +1433,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   ],
 }));
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request) => observeTool(request.params.name, async () => {
   try {
     const { name, arguments: args } = request.params;
 
@@ -1501,7 +1673,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const key = pickProjectKey(config, args.projectName);
         const project = config.projects[key];
         let guidelines = '';
-        try { guidelines = await readFile(GUIDELINES_PATH, 'utf-8'); }
+        const guidelinesPath = resolveGuidelinesPath({ dataHome: DATA_HOME, packageDir: PACKAGE_DIR, exists: existsSync });
+        try { guidelines = await readFile(guidelinesPath, 'utf-8'); }
         catch { guidelines = '(writing-guidelines.md missing from OverleafMCP folder)'; }
         const ctx = await readContext(key, project);
         const text = [
@@ -1522,7 +1695,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           ``,
           ctx.body,
         ].join('\n');
-        return { content: [{ type: 'text', text }] };
+        const v = versionedContext(key,text,args.previousVersion);
+        return { content: [{ type: 'text', text: `Context version: ${v.version}\n${v.text}` }], structuredContent: { version:v.version, unchanged:v.unchanged, projectName:key } };
       }
 
       case 'list_files': {
@@ -1536,7 +1710,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const content = await client.readFile(args.filePath);
         const baseSha = await client.getBlobSha(args.filePath, { pull: false });
         const header = `<!-- overleaf-mcp baseSha: ${baseSha || 'none'} (pass as baseSha to write_file to guard against clobbering Overleaf edits) -->\n`;
-        return { content: [{ type: 'text', text: header + content }] };
+        const { stdout } = await client._git(['-C', client.repoPath, 'rev-parse', 'HEAD']);
+        return { content: [{ type: 'text', text: header + content }], structuredContent: { baseSha, baseRevision: stdout.trim(), contentHash: createHash('sha256').update(content).digest('hex') } };
       }
 
       case 'get_sections': {
@@ -1547,65 +1722,114 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case 'get_section_content': {
         const { client } = await getClient(args.projectName);
+        if (args.bundle) {
+          await client.requireLocal();
+          const result = await sectionBundle(client.repoPath, args.filePath, args.sectionTitle, args.maxChars);
+          return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+        }
         const content = await client.getSectionContent(args.filePath, args.sectionTitle);
         return { content: [{ type: 'text', text: content }] };
       }
 
-      case 'compile_file': {
+      case 'sync_project': {
         const { client } = await getClient(args.projectName);
-        const r = await client.compileFile(args.filePath, args.engine || 'lualatex');
-        const status = r.pdfPath ? `✓ PDF written to ${r.pdfPath}` : '✗ Compilation failed — no PDF produced';
-        const parts = [status];
-        if (r.errors.length)        parts.push(`\n--- Errors (${r.errors.length}) ---\n${r.errors.join('\n')}`);
-        if (r.undefinedRefs.length) parts.push(`\n--- Undefined refs/citations (${r.undefinedRefs.length}) ---\n${r.undefinedRefs.join('\n')}`);
-        if (r.overfull.length)      parts.push(`\n--- Overfull/Underfull (${r.overfull.length}) ---\n${r.overfull.join('\n')}`);
-        parts.push(`\n--- Log tail ---\n${r.tail}`);
-        return { content: [{ type: 'text', text: parts.join('\n').trim() }] };
+        const result = await client.syncProject({ strategy: args.strategy, confirm: args.confirm });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result };
+      }
+      case 'usage_stats': {
+        const result = usageStats(args);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+      }
+      case 'dependency_index':
+      case 'change_report':
+      case 'render_pages': {
+        const { client } = await getClient(args.projectName);
+        await client.requireLocal();
+        const result = name === 'dependency_index' ? await dependencyIndex(client.repoPath, args)
+          : name === 'change_report' ? await changeReport(client.repoPath, args.baselineVersion)
+          : await renderPages(client.repoPath, args);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+      }
+      case 'apply_changes':
+      case 'publish_changes': {
+        const config = await loadConfig();
+        const { client } = await getClient(args.projectName);
+        await client.requireLocal();
+        const verify = async root => {
+          const candidate = new OverleafGitClient(client.projectId, client.gitToken, root);
+          return candidate.verifyBuild(args.filePath, args.engine || 'lualatex', {
+            controlled: args.controlled === true,
+            externalInputs: args.externalInputs,
+            lint: args.lint,
+            lintCommand: voiceLinterCommand(config),
+            reuseRecentPass: name === 'publish_changes' && args.force !== true,
+          });
+        };
+        const result = name === 'apply_changes' ? await applyChanges(client.repoPath, args, verify)
+          : await publishChanges(client.repoPath, args, verify, async (root, revision, branch) => {
+            try {
+              await client._git(['-C', root, 'push', 'origin', `${revision}:refs/heads/${branch}`], { auth: true });
+            } catch (e) {
+              // A rejected push means Overleaf moved since the last sync; name
+              // the recovery instead of surfacing raw git plumbing.
+              if (/rejected|fetch first|non-fast-forward/i.test(e.stderr || '')) {
+                throw new Error('Overleaf has commits this clone lacks, so the push was refused and nothing was published. Run sync_project to see both sides, resolve with strategy "rebase", verify again, then publish the new HEAD.');
+              }
+              throw e;
+            }
+          });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
       }
-
       case 'verify_build': {
+        const config = await loadConfig();
         const { client } = await getClient(args.projectName);
-        const v = await client.verifyBuild(args.filePath, args.engine || 'lualatex');
-        if (v.pass) {
-          const warn = (v.overfullCount || v.underfullCount)
-            ? ` (note: ${v.overfullCount} overfull / ${v.underfullCount} underfull boxes)` : '';
-          return { content: [{ type: 'text', text: `✓ PASS — ${v.pageCount} pages${warn}` }] };
-        }
-        const parts = ['✗ FAIL'];
-        if (!v.pdfProduced) parts.push('- no PDF produced');
-        if (v.errors.length) parts.push(`- ${v.errors.length} error(s):\n${v.errors.slice(0, 20).join('\n')}`);
-        if (v.undefinedRefs.length) parts.push(`- ${v.undefinedRefs.length} undefined reference(s):\n${v.undefinedRefs.slice(0, 20).join('\n')}`);
-        if (v.undefinedCitations.length) parts.push(`- ${v.undefinedCitations.length} undefined citation(s):\n${v.undefinedCitations.slice(0, 20).join('\n')}`);
-        if (v.overfullCount || v.underfullCount) parts.push(`- (warnings) ${v.overfullCount} overfull / ${v.underfullCount} underfull`);
-        parts.push(`\n--- log tail ---\n${v.tail}`);
-        return { content: [{ type: 'text', text: parts.join('\n') }] };
+        const opts = { ...args, lintCommand: voiceLinterCommand(config) };
+        const v = args.clean === false
+          ? await client.compileFile(args.filePath, args.engine || 'lualatex', opts)
+          : await client.verifyBuild(args.filePath, args.engine || 'lualatex', opts);
+        // A PASS already means zero errors and zero undefined references and
+        // citations, so only box warnings and reuse are worth reporting. A FAIL
+        // carries the counts, the first offenders and where the full log is.
+        const boxes = v.overfullCount || v.underfullCount ? `; ${v.overfullCount} overfull / ${v.underfullCount} underfull boxes` : '';
+        const parts = v.pass
+          ? [`PASS: ${v.pageCount ?? '?'} pages${boxes}${v.reused ? ' (reused unchanged verification)' : ''}.`]
+          : [`FAIL: ${v.pageCount ?? '?'} pages; ${v.errors.length} errors; ${v.undefinedRefs.length} undefined references; ${v.undefinedCitations.length} undefined citations${boxes}. Log: ${path.relative(client.repoPath, v.logPath)}`,
+            ...v.errors.slice(0,5),...v.undefinedRefs.slice(0,5),...v.undefinedCitations.slice(0,5)];
+        if (v.lint) parts.push(v.lint.clean ? `Voice lint: clean (${v.lint.results.length} file(s)).` : `Voice lint findings:\n${v.lint.results.filter(r => !r.clean).map(r => `${r.file}:\n${r.findings}`).join('\n')}`);
+        if (args.verbose) parts.push(v.tail);
+        return { content:[{type:'text',text:parts.join('\n')}], structuredContent: { pass: v.pass, pageCount: v.pageCount, reused: v.reused, cacheEligible: v.cacheEligible, errors: v.errors.slice(0,5), logPath: v.logPath, lintClean: v.lint ? v.lint.clean : null } };
       }
 
       case 'edit_file': {
+        const config = await loadConfig();
         const { client } = await getClient(args.projectName);
-        const res = await client.editFile(args.filePath, args.oldString, args.newString, args.replaceAll || false, args.commitMessage);
-        const tail = res.pushed
-          ? `Edited ${args.filePath}${res.merged ? ' (auto-merged a concurrent Overleaf change)' : ''}. NEXT STEP: call compile_file on the project main .tex to verify the build.`
-          : `No change applied to ${args.filePath} (${res.reason}).`;
+        const res = await client.editFile(args.filePath, args.oldString, args.newString, args.replaceAll || false, args.commitMessage, { push: resolvePush(config.settings, args) });
+        const tail = res.reason
+          ? `No change applied to ${args.filePath} (${res.reason}).`
+          : mutationTail(res, `Edited ${args.filePath}`);
         return { content: [{ type: 'text', text: tail }] };
       }
 
       case 'write_file': {
+        const config = await loadConfig();
         const { client } = await getClient(args.projectName);
         const res = await client.writeFile(args.filePath, args.content, {
           baseSha: args.baseSha,
           overwrite: args.overwrite,
           commitMessage: args.commitMessage,
+          push: resolvePush(config.settings, args),
         });
-        const tail = res.pushed
-          ? `Wrote ${args.filePath}. NEXT STEP: call compile_file on the project main .tex to verify the build.`
-          : `No change detected for ${args.filePath} (${res.reason}).`;
+        const tail = res.reason
+          ? `No change detected for ${args.filePath} (${res.reason}).`
+          : mutationTail(res, `Wrote ${args.filePath}`);
         return { content: [{ type: 'text', text: tail }] };
       }
 
       case 'upload_file': {
+        const config = await loadConfig();
         const { client } = await getClient(args.projectName);
         const res = await client.uploadFile({
+          push: resolvePush(config.settings, args),
           srcPath: args.srcPath,
           destPath: args.destPath,
           files: args.files,
@@ -1613,9 +1837,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           overwrite: args.overwrite,
           commitMessage: args.commitMessage,
         });
-        const tail = res.pushed
-          ? `Uploaded ${res.files.length} file(s): ${res.files.join(', ')}. NEXT: reference each figure with \\includegraphics{...} via edit_file, then compile_file.`
-          : `No upload performed (${res.reason}).`;
+        const tail = res.reason
+          ? `No upload performed (${res.reason}).`
+          : `${mutationTail(res, `Uploaded ${res.files.length} file(s): ${res.files.join(', ')}`)} Reference each figure with \\includegraphics{...} via edit_file.`;
         return { content: [{ type: 'text', text: tail }] };
       }
 
@@ -1628,9 +1852,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'add_citation': {
+        const config = await loadConfig();
         const { client } = await getClient(args.projectName);
-        const res = await client.addCitation({ entry: args.entry, commitMessage: args.commitMessage });
-        return { content: [{ type: 'text', text: res.pushed ? `Added citation "${res.key}" to refs.bib and pushed.` : `No change for "${res.key}" (${res.reason}).` }] };
+        const res = await client.addCitation({ entry: args.entry, commitMessage: args.commitMessage, push: resolvePush(config.settings, args) });
+        return { content: [{ type: 'text', text: res.reason ? `No change for "${res.key}" (${res.reason}).` : mutationTail(res, `Added citation "${res.key}" to refs.bib`) }] };
       }
 
       case 'cite_lint': {
@@ -1649,22 +1874,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'restore': {
+        const config = await loadConfig();
         const { client } = await getClient(args.projectName);
-        const r = await client.restore(args.label);
-        return { content: [{ type: 'text', text: `Restored "${r.label}" and pushed (forward commit). Run compile_file/verify_build to confirm.` }] };
+        const r = await client.restore(args.label, { push: resolvePush(config.settings, args) });
+        return { content: [{ type: 'text', text: `${mutationTail(r, `Restored "${r.label}" as a forward commit`)} Run verify_build to confirm.` }] };
       }
 
       case 'voice_lint': {
         const config = await loadConfig();
         const { client } = await getClient(args.projectName);
-        // settings.voiceLinter / $OVERLEAF_VOICE_LINTER override the bundled
-        // example linter, which ships with the package so voice_lint works out
-        // of the box. The example implements generic prose checks; point the
-        // setting at your own command to enforce a house style.
-        const command = config.settings?.voiceLinter
-          || process.env.OVERLEAF_VOICE_LINTER
-          || `node ${path.join(PACKAGE_DIR, 'examples', 'voice-lint.mjs')}`;
-        const r = await client.voiceLint(args.filePath, { command });
+        const r = await client.voiceLint(args.filePath, { command: voiceLinterCommand(config) });
         return { content: [{ type: 'text', text: r.clean ? `✓ voice OK — ${args.filePath}${r.findings ? `\n${r.findings}` : ''}` : `voice findings in ${args.filePath}:\n${r.findings}` }] };
       }
 
@@ -1693,14 +1912,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new Error(`Unknown tool: ${name}`);
     }
   } catch (error) {
-    // Defense in depth: scrub any tokenized URL that might surface in an error.
-    const msg = String(error?.message ?? error).replace(/git:[^@\s/]+@/g, 'git:***@');
-    return {
-      content: [{ type: 'text', text: `Error: ${msg}` }],
-      isError: true,
-    };
+    return toolError(error);
   }
-});
+})());
 
 async function main() {
   const transport = new StdioServerTransport();