codex-overleaf-link 1.1.2 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@
   <h1>Codex Overleaf Link</h1>
   <p><strong>Empower Overleaf with Codex.</strong></p>
   <p>
-    <img src="https://img.shields.io/badge/version-1.1.2-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.2.0-blue" alt="version">
     <img src="https://img.shields.io/badge/platform-macOS%20%2F%20Windows%20%2F%20Linux-lightgrey" alt="platform">
     <img src="https://img.shields.io/badge/chrome-MV3-green" alt="chrome manifest v3">
     <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node version">
@@ -29,43 +29,36 @@ Codex Overleaf Link bridges the two: it adds a Codex panel directly inside Overl
 
 ## Install
 
-The official release path is still a one-command native-host install plus Chrome's required manual approval for an unpacked extension. The bundled extension key gives the official unpacked build a stable id, so you do not need to pass an extension id for normal release installs.
+The recommended release path is npm-first for the native host, plus Chrome's required manual approval for the unpacked extension. The bundled extension key gives the official unpacked build a stable id, so normal release installs do not need `--extension-id`.
 
-macOS / Linux latest source install:
+1. Install or update the native host with the pinned npm package:
 
 ```bash
-curl -fsSL "https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/main/install.sh?$(date +%s)" | bash
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
-Recommended version-pinned native-host install or update for v1.1.2:
+2. Download `codex-overleaf-link-extension-v1.2.0.zip` from the [v1.2.0 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.2.0), then unzip it to a stable local folder.
 
-```bash
-npm exec --yes codex-overleaf-link@1.1.2 -- install-native
-```
+3. Open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the unzipped extension folder.
+
+4. Open any Overleaf project. The Codex panel appears on the right.
+
+If you modify the extension key or load a custom build that gets a different id, rerun the native install with `--extension-id <chrome-extension-id>`.
 
-GitHub Release script fallback for macOS / Linux:
+Source installer fallback for macOS / Linux, mainly for development or source checkout installs:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.2 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.2/install.sh)"
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)"
 ```
 
-GitHub Release script fallback for Windows from PowerShell:
+Source installer fallback for Windows from PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.2/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.1.2'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.2.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
-The macOS / Linux installer creates a visible `~/Codex Overleaf Link Extension` shortcut to the extension folder. On macOS it also opens Chrome's extension page, opens Finder to the shortcut, and copies the shortcut path. The Windows installer prints the extension folder path after registering the native host.
-
-Chrome still requires one manual approval step for unpacked extensions:
-
-1. Enable **Developer mode** in `chrome://extensions`.
-2. Click **Load unpacked** and select `~/Codex Overleaf Link Extension` on macOS/Linux, or the printed extension folder on Windows.
-
-If you modify the extension key or load a custom build that gets a different id, rerun the native install with `--extension-id <chrome-extension-id>`.
-
 ## npm Native Host CLI
 
 npm installs, updates, uninstalls, and diagnoses the native host only. npm does not install the Chrome extension; install the Chrome extension separately from the release source checkout or extension zip.
@@ -73,19 +66,19 @@ npm installs, updates, uninstalls, and diagnoses the native host only. npm does
 Install or update the native host for the official release extension id:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.2 -- install-native
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
 Diagnose the registered native host:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.2 -- doctor
+npm exec --yes codex-overleaf-link@1.2.0 -- doctor
 ```
 
 Uninstall the native host:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.2 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native
 ```
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id.
@@ -123,10 +116,10 @@ If Chrome assigns a different extension id, rerun `npm run install:native -- --e
 <details>
 <summary><strong>Update</strong></summary>
 
-For a deterministic v1.1.2 update, run the pinned npm command. This is also the native mismatch recovery command shown by the popup and panel when they report **Native host update required**.
+For a deterministic v1.2.0 update, run the pinned npm command. This is also the native mismatch recovery command shown by the popup and panel when they report **Native host update required**.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.2 -- install-native
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
 If npm is unavailable, use the GitHub Release script fallback for your platform.
@@ -134,14 +127,14 @@ If npm is unavailable, use the GitHub Release script fallback for your platform.
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.2 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.2/install.sh)"
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.2/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.1.2'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.2.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -151,14 +144,15 @@ Then reload the extension in `chrome://extensions` and refresh the Overleaf page
 
 ## GitHub Release Artifacts
 
-The v1.1.2 GitHub Release contains:
+The v1.2.0 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.1.2.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.1.2.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.1.2.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
-- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.1.2` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.1.2` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v1.2.0.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v1.2.0.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-1.2.0.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
+- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.2.0` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.2.0` when run directly from the release artifact.
 - `uninstall-native-host.mjs`: native host uninstaller that removes the Chrome Native Messaging manifest, bridge executable, and runtime copy.
+- `nativeHostPlatform.js`, `manifest.js`, `runtimeInstaller.js`: helper files required by the loose uninstaller asset.
 - `SHA256SUMS` and `release-manifest.json`: checksum and artifact metadata for release verification.
 
 <details>
@@ -208,7 +202,7 @@ The uninstaller removes the Native Messaging registration, bridge executable, an
 Linux Chromium install or update:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.2 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.2/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
@@ -350,7 +344,7 @@ Composer attachments are turn-scoped Codex context. Limits are 8 attachments per
 Run the pinned npm native-host installer, reload the extension in `chrome://extensions`, then refresh the Overleaf tab. This also fixes extension/native version mismatch and native protocol mismatch.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.2 -- install-native
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
 If npm is unavailable, use the GitHub Release script fallback for your platform.
@@ -358,14 +352,14 @@ If npm is unavailable, use the GitHub Release script fallback for your platform.
 macOS/Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.2 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.2/install.sh)"
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.2/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.1.2'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.2.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -424,8 +418,8 @@ Use this matrix for release-candidate signoff and compatibility reports. Record
 | Browser/channel/version | Google Chrome channel and version. | Google Chrome channel and version. | Google Chrome channel and version. | Chromium channel/package and version. |
 | Install mode | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout; native host installed with `--browser chromium`. |
 | Extension id | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. |
-| Installer/update command | `npm exec --yes codex-overleaf-link@1.1.2 -- install-native` | `npm exec --yes codex-overleaf-link@1.1.2 -- install-native` | `npm exec --yes codex-overleaf-link@1.1.2 -- install-native` | `npm exec --yes codex-overleaf-link@1.1.2 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.1.2 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.1.2 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.1.2 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.1.2 -- uninstall-native --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native --browser chromium` |
 | Manifest/registry path | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.codex.overleaf.json` | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` -> `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime\com.codex.overleaf.json` | `~/.config/google-chrome/NativeMessagingHosts/com.codex.overleaf.json` | `~/.config/chromium/NativeMessagingHosts/com.codex.overleaf.json` |
 | Bridge/runtime/source path | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `%LOCALAPPDATA%\CodexOverleaf\codex-overleaf-bridge.cmd`; runtime `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime`; source `%LOCALAPPDATA%\CodexOverleaf\source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. |
 | Node/Git/Codex/TeX | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. |

package/extension/src/shared/compatibility.js

@@ -12,7 +12,7 @@
   const MIN_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_EXTENSION_VERSION = '1.0.0';
-  const BUILD_TARGET_VERSION = '1.1.2';
+  const BUILD_TARGET_VERSION = '1.2.0';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',

package/extension/src/shared/lineReferences.js

@@ -0,0 +1,404 @@
+(function initLineReferences(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.CodexOverleafLineReferences = factory();
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : window, function lineReferencesFactory() {
+  'use strict';
+
+  const VALID_PARSE_MODES = new Set([
+    'plain-text-token',
+    'markdown-link-label',
+    'markdown-link-target'
+  ]);
+  const TEXT_EXTENSION_PATTERN = '(?:tex|bib|sty|cls|bst|bbx|cbx|lbx|cfg|def|clo|ist|txt|md|latex)';
+  const REFERENCE_PREFIX_PATTERN = '(^|[\\s\\[({"\'])';
+  const PATH_PATTERN = `([^\\s\\[\\](){}<>"'\`,;]+?\\.${TEXT_EXTENSION_PATTERN})`;
+  const MARKDOWN_LINK_PATTERN = /\[([^\]]*)\]\(([^)]*)\)/g;
+  const BARE_LOCAL_PATH_PATTERN = /(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/]projects[\\/][^\s)\]]+)/gi;
+
+  function parseLineReferencesFromText({ text, mode }) {
+    return collectLineReferences(text, mode).map(toPublicReference);
+  }
+
+  function resolveProjectReference({ rawPath, projectFiles }) {
+    const normalizedRawPath = normalizeReferencePath(rawPath);
+    if (!normalizedRawPath || hasUnsafePathSegments(normalizedRawPath)) {
+      return null;
+    }
+
+    const textFiles = collectTextProjectFiles(projectFiles);
+    const exactMatch = textFiles.find(file => file.normalizedPath === normalizedRawPath);
+    if (exactMatch) {
+      return buildResolvedReference(exactMatch, 'exact');
+    }
+
+    const suffixMatches = textFiles.filter(file => normalizedRawPath.endsWith(`/${file.normalizedPath}`));
+    if (suffixMatches.length === 1) {
+      return buildResolvedReference(suffixMatches[0], 'suffix');
+    }
+
+    const rawBasename = getBasename(normalizedRawPath);
+    const basenameMatches = textFiles.filter(file => getBasename(file.normalizedPath) === rawBasename);
+    if (basenameMatches.length === 1) {
+      return buildResolvedReference(basenameMatches[0], 'basename');
+    }
+
+    return null;
+  }
+
+  function sanitizeLocalReferences(text, { projectFiles, context } = {}) {
+    if (typeof text !== 'string' || !text) {
+      return '';
+    }
+
+    let sanitized = text.replace(MARKDOWN_LINK_PATTERN, (rawMarkdown, label, target) => {
+      const sanitizedLabel = sanitizeLocalReferenceText(label, {
+        projectFiles,
+        placeholderBrackets: false
+      });
+      const trimmedTarget = String(target || '').trim();
+      if (/^https?:\/\//i.test(trimmedTarget)) {
+        return `[${sanitizedLabel}](${target})`;
+      }
+      if (containsLocalTarget(trimmedTarget)) {
+        return `[${sanitizedLabel}]`;
+      }
+      const sanitizedTarget = sanitizeLocalReferenceText(target, {
+        projectFiles,
+        placeholderBrackets: false
+      });
+      return `[${sanitizedLabel}](${sanitizedTarget})`;
+    });
+
+    sanitized = sanitizeLocalReferenceText(sanitized, {
+      projectFiles,
+      placeholderBrackets: true
+    });
+
+    if (context === 'render' || context === 'persist') {
+      return sanitized;
+    }
+    return sanitized;
+  }
+
+  function isLocalPathLike(value) {
+    if (typeof value !== 'string') {
+      return false;
+    }
+
+    const rawValue = value.trim();
+    if (!rawValue || /^https?:\/\//i.test(rawValue)) {
+      return false;
+    }
+
+    const normalizedPath = normalizeReferencePath(rawValue);
+    return /^file:\/\//i.test(rawValue)
+      || /^[A-Za-z]:[\\/]/.test(rawValue)
+      || rawValue.startsWith('/')
+      || rawValue.includes('.codex-overleaf/projects')
+      || rawValue.includes('.codex-overleaf\\projects')
+      || normalizedPath.includes('/.codex-overleaf/projects/')
+      || /^Users\/[^/]+\//.test(normalizedPath)
+      || /^home\/[^/]+\//.test(normalizedPath);
+  }
+
+  function normalizeReferencePath(value) {
+    if (typeof value !== 'string') {
+      return '';
+    }
+
+    let normalized = value.trim();
+    if (!normalized) {
+      return '';
+    }
+
+    if (/^file:\/\//i.test(normalized)) {
+      normalized = normalized.replace(/^file:\/\/\/?/i, '/');
+    }
+
+    try {
+      normalized = decodeURI(normalized);
+    } catch (_error) {
+      return '';
+    }
+
+    normalized = normalized
+      .replace(/\\/g, '/')
+      .replace(/\/+/g, '/')
+      .trim();
+
+    let previous;
+    do {
+      previous = normalized;
+      normalized = normalized
+        .replace(/^@+/, '')
+        .replace(/^\/+/, '')
+        .replace(/^\.\//, '');
+    } while (normalized !== previous);
+
+    return normalized;
+  }
+
+  function collectLineReferences(text, mode) {
+    if (!VALID_PARSE_MODES.has(mode) || typeof text !== 'string' || !text) {
+      return [];
+    }
+
+    const refs = [];
+    collectColonReferences(text, mode, refs);
+    collectLineWordReferences(text, mode, refs);
+    collectChineseLineReferences(text, mode, refs);
+
+    return refs
+      .filter(ref => !shouldSkipReference(ref))
+      .sort((left, right) => left.index - right.index || right.rawText.length - left.rawText.length)
+      .reduce((deduped, ref) => {
+        if (deduped.some(existing => rangesOverlap(existing, ref))) {
+          return deduped;
+        }
+        deduped.push(ref);
+        return deduped;
+      }, []);
+  }
+
+  function collectColonReferences(text, mode, refs) {
+    const pattern = new RegExp(`${REFERENCE_PREFIX_PATTERN}${PATH_PATTERN}:(\\d+)(?::(\\d+))?(?![-:\\d])`, 'gi');
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const line = parsePositiveInteger(match[3]);
+      const column = match[4] ? parsePositiveInteger(match[4]) : null;
+      if (!line || (match[4] && !column)) {
+        continue;
+      }
+      const prefixLength = match[1].length;
+      const rawText = match[0].slice(prefixLength);
+      refs.push({
+        rawText,
+        displayText: rawText,
+        rawPath: match[2],
+        line,
+        column,
+        source: mode,
+        index: match.index + prefixLength
+      });
+    }
+  }
+
+  function collectLineWordReferences(text, mode, refs) {
+    const pattern = new RegExp(`${REFERENCE_PREFIX_PATTERN}${PATH_PATTERN}\\s+line\\s+(\\d+)(?![-:\\d])`, 'gi');
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const line = parsePositiveInteger(match[3]);
+      if (!line) {
+        continue;
+      }
+      const prefixLength = match[1].length;
+      const rawText = match[0].slice(prefixLength);
+      refs.push({
+        rawText,
+        displayText: `${match[2]}:${line}`,
+        rawPath: match[2],
+        line,
+        column: null,
+        source: mode,
+        index: match.index + prefixLength
+      });
+    }
+  }
+
+  function collectChineseLineReferences(text, mode, refs) {
+    const pattern = new RegExp(`${REFERENCE_PREFIX_PATTERN}${PATH_PATTERN}\\s+第\\s*(\\d+)\\s*行`, 'gi');
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const line = parsePositiveInteger(match[3]);
+      if (!line) {
+        continue;
+      }
+      const prefixLength = match[1].length;
+      const rawText = match[0].slice(prefixLength);
+      refs.push({
+        rawText,
+        displayText: `${match[2]}:${line}`,
+        rawPath: match[2],
+        line,
+        column: null,
+        source: mode,
+        index: match.index + prefixLength
+      });
+    }
+  }
+
+  function sanitizeLocalReferenceText(text, { projectFiles, placeholderBrackets }) {
+    let sanitized = replaceLineReferences(String(text || ''), {
+      projectFiles,
+      placeholderBrackets
+    });
+    sanitized = replaceBareLocalPaths(sanitized, {
+      projectFiles,
+      placeholderBrackets
+    });
+    return sanitized;
+  }
+
+  function replaceLineReferences(text, { projectFiles, placeholderBrackets }) {
+    const refs = collectLineReferences(text, 'plain-text-token')
+      .filter(ref => isLocalPathLike(ref.rawPath))
+      .sort((left, right) => right.index - left.index);
+    let sanitized = text;
+    for (const ref of refs) {
+      const replacement = formatReferenceReplacement(ref, {
+        projectFiles,
+        placeholderBrackets
+      });
+      sanitized = `${sanitized.slice(0, ref.index)}${replacement}${sanitized.slice(ref.index + ref.rawText.length)}`;
+    }
+    return sanitized;
+  }
+
+  function replaceBareLocalPaths(text, { projectFiles, placeholderBrackets }) {
+    return text.replace(BARE_LOCAL_PATH_PATTERN, (rawPath, offset, fullText) => {
+      if (/^[A-Za-z]:[\\/]/.test(rawPath) && offset > 0 && /[A-Za-z]/.test(fullText[offset - 1])) {
+        return rawPath;
+      }
+      const { value, trailing } = splitTrailingPunctuation(rawPath);
+      const resolved = resolveProjectReference({ rawPath: value, projectFiles });
+      if (resolved) {
+        return `${resolved.path}${trailing}`;
+      }
+      return `${formatLocalPathPlaceholder(null, placeholderBrackets)}${trailing}`;
+    });
+  }
+
+  function formatReferenceReplacement(ref, { projectFiles, placeholderBrackets }) {
+    const resolved = resolveProjectReference({
+      rawPath: ref.rawPath,
+      projectFiles
+    });
+    if (resolved) {
+      return `${resolved.path}:${ref.line}${ref.column ? `:${ref.column}` : ''}`;
+    }
+    return formatLocalPathPlaceholder(ref.line, placeholderBrackets);
+  }
+
+  function formatLocalPathPlaceholder(line, includeBrackets) {
+    const value = line ? `local path:${line}` : 'local path';
+    return includeBrackets ? `[${value}]` : value;
+  }
+
+  function containsLocalTarget(target) {
+    if (!target) {
+      return false;
+    }
+    if (isLocalPathLike(target)) {
+      return true;
+    }
+    return collectLineReferences(target, 'markdown-link-target')
+      .some(ref => isLocalPathLike(ref.rawPath));
+  }
+
+  function collectTextProjectFiles(projectFiles) {
+    if (!Array.isArray(projectFiles)) {
+      return [];
+    }
+
+    const result = [];
+    for (const file of projectFiles) {
+      if (!file || file.kind !== 'text' || typeof file.path !== 'string') {
+        continue;
+      }
+
+      const normalizedPath = normalizeReferencePath(file.path);
+      if (!normalizedPath || hasUnsafePathSegments(normalizedPath)) {
+        continue;
+      }
+
+      result.push({
+        entry: file,
+        path: normalizedPath,
+        normalizedPath
+      });
+    }
+    return result;
+  }
+
+  function buildResolvedReference(file, resolution) {
+    return {
+      path: file.path,
+      file: file.entry,
+      normalizedPath: file.normalizedPath,
+      resolution
+    };
+  }
+
+  function shouldSkipReference(ref) {
+    const rawPath = String(ref.rawPath || '');
+    return /^https?:\/\//i.test(rawPath)
+      || isEmailLikePath(rawPath)
+      || hasUnsafeLineRange(ref.rawText);
+  }
+
+  function isEmailLikePath(rawPath) {
+    return /^[^@\s/\\]+@[^@\s/\\]+$/.test(rawPath);
+  }
+
+  function hasUnsafeLineRange(rawText) {
+    return /:\d+-\d+(?=$|[^\d])/.test(rawText);
+  }
+
+  function hasUnsafePathSegments(path) {
+    return normalizeReferencePath(path)
+      .split('/')
+      .some(segment => segment === '.' || segment === '..');
+  }
+
+  function rangesOverlap(left, right) {
+    const leftEnd = left.index + left.rawText.length;
+    const rightEnd = right.index + right.rawText.length;
+    return left.index < rightEnd && right.index < leftEnd;
+  }
+
+  function parsePositiveInteger(value) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+      return null;
+    }
+    return parsed;
+  }
+
+  function getBasename(path) {
+    const parts = String(path || '').split('/');
+    return parts[parts.length - 1] || '';
+  }
+
+  function splitTrailingPunctuation(value) {
+    const match = String(value || '').match(/^(.*?)([.,;!?]+)$/);
+    if (!match) {
+      return { value, trailing: '' };
+    }
+    return {
+      value: match[1],
+      trailing: match[2]
+    };
+  }
+
+  function toPublicReference(ref) {
+    return {
+      rawText: ref.rawText,
+      displayText: ref.displayText,
+      rawPath: ref.rawPath,
+      line: ref.line,
+      column: ref.column,
+      source: ref.source
+    };
+  }
+
+  return {
+    isLocalPathLike,
+    normalizeReferencePath,
+    parseLineReferencesFromText,
+    resolveProjectReference,
+    sanitizeLocalReferences
+  };
+});

package/extension/src/shared/sessionState.js

@@ -81,6 +81,7 @@
     /\b(?:sk|pk)-[A-Za-z0-9][A-Za-z0-9_-]{7,}\b/g,
     /\b(?:api[_-]?key|token|password|passwd|secret)\b\s*[:=]\s*["']?[^"'\s,;]+["']?/gi
   ];
+  const LineReferences = loadLineReferences();
 
   function normalizePanelState(input = {}, options = {}) {
     const state = {
@@ -143,7 +144,7 @@
   }
 
   function normalizeSession(session, fallbackState = DEFAULT_PANEL_STATE, options = {}) {
-    const history = Array.isArray(session.history) ? session.history.slice(-10) : [];
+    const history = normalizeHistoryEntries(session.history);
     const normalizedRuns = normalizeRuns(session.runs, options);
     const runs = normalizedRuns.length ? normalizedRuns : recoverRunsFromHistory(session, history);
     const rawTitle = typeof session.title === 'string' ? session.title.trim() : '';
@@ -159,7 +160,7 @@
       updatedAt: typeof session.updatedAt === 'string' ? session.updatedAt : new Date().toISOString(),
       history,
       runs,
-      task: typeof session.task === 'string' ? session.task : '',
+      task: sanitizeAssistantVisibleText(session.task),
       mode: VALID_MODES.has(session.mode) ? session.mode : fallbackState.mode,
       model: typeof session.model === 'string' && session.model ? session.model : fallbackState.model,
       reasoningEffort: VALID_REASONING.has(session.reasoningEffort)
@@ -267,9 +268,9 @@
       titleSource,
       createdAt: overrides.createdAt || new Date().toISOString(),
       updatedAt: overrides.updatedAt || new Date().toISOString(),
-      history: Array.isArray(overrides.history) ? overrides.history.slice(-10) : [],
+      history: normalizeHistoryEntries(overrides.history),
       runs,
-      task: typeof overrides.task === 'string' ? overrides.task : '',
+      task: sanitizeAssistantVisibleText(overrides.task),
       mode: VALID_MODES.has(overrides.mode) ? overrides.mode : DEFAULT_PANEL_STATE.mode,
       model: typeof overrides.model === 'string' && overrides.model ? overrides.model : DEFAULT_PANEL_STATE.model,
       reasoningEffort: VALID_REASONING.has(overrides.reasoningEffort)
@@ -286,6 +287,8 @@
 
   function recordSessionResult(session, entry) {
     const base = session?.id ? session : createSession();
+    const task = sanitizeAssistantVisibleText(entry?.task) || 'untitled task';
+    const result = sanitizeAssistantVisibleText(entry?.result || entry?.status) || 'completed';
     return {
       ...base,
       id: base.id,
@@ -293,12 +296,12 @@
       history: [
         ...(Array.isArray(base.history) ? base.history : []),
         {
-          task: entry.task || 'untitled task',
-          result: entry.result || entry.status || 'completed',
-          at: entry.at || new Date().toISOString()
+          task,
+          result,
+          at: entry?.at || new Date().toISOString()
         }
       ].slice(-10),
-      updatedAt: entry.at || new Date().toISOString()
+      updatedAt: entry?.at || new Date().toISOString()
     };
   }
 
@@ -419,7 +422,7 @@
   }
 
   function sanitizeAutoTitle(value) {
-    const title = String(value || '')
+    const title = sanitizeAssistantVisibleText(value)
       .replace(/@file:[^\s]+/g, ' ')
       .replace(/@(context|compile-log)\b/g, ' ')
       .replace(/\s+/g, ' ')
@@ -506,13 +509,13 @@
 
     return {
       id: run.id,
-      task: typeof run.task === 'string' && run.task ? run.task : 'untitled task',
+      task: sanitizeAssistantVisibleText(run.task) || 'untitled task',
       mode: typeof run.mode === 'string' ? run.mode : '',
       model: typeof run.model === 'string' ? run.model : '',
       reasoningEffort: typeof run.reasoningEffort === 'string' ? run.reasoningEffort : '',
       speedTier: typeof run.speedTier === 'string' ? run.speedTier : '',
       status: shouldStopRestoredRun ? 'failed' : normalizeRunStatus(run.status),
-      statusText: shouldStopRestoredRun ? '页面刷新后已停止跟踪' : typeof run.statusText === 'string' ? run.statusText : '',
+      statusText: shouldStopRestoredRun ? '页面刷新后已停止跟踪' : sanitizeAssistantVisibleText(run.statusText),
       startedAt: typeof run.startedAt === 'string' ? run.startedAt : '',
       finishedAt: shouldStopRestoredRun ? new Date().toISOString() : typeof run.finishedAt === 'string' ? run.finishedAt : '',
       events: events.slice(-MAX_RUN_EVENTS),
@@ -522,7 +525,7 @@
       undoBaseFiles: normalizeRunFiles(run.undoBaseFiles),
       undoTrackedChanges: normalizeRunTrackedChanges(run.undoTrackedChanges),
       undoExpectedFiles: normalizeRunFiles(run.undoExpectedFiles),
-      undoStatus: typeof run.undoStatus === 'string' ? redactSecretLikeText(run.undoStatus) : ''
+      undoStatus: sanitizeAssistantVisibleText(run.undoStatus)
     };
   }
 
@@ -538,14 +541,14 @@
     return (Array.isArray(events) ? events : [])
       .filter(event => event && typeof event.title === 'string')
       .map(event => ({
-        title: event.title,
+        title: sanitizeAssistantVisibleText(event.title) || 'Event',
         status: typeof event.status === 'string' ? event.status : 'info',
-        detail: event.detail,
+        detail: sanitizeAssistantVisibleValue(event.detail),
         timestamp: typeof event.timestamp === 'string' ? event.timestamp : '',
         kind: typeof event.kind === 'string' ? event.kind : 'activity',
-        technicalDetail: event.technicalDetail,
-        streamKey: typeof event.streamKey === 'string' ? event.streamKey : '',
-        streamRole: typeof event.streamRole === 'string' ? event.streamRole : ''
+        technicalDetail: sanitizeAssistantVisibleValue(event.technicalDetail),
+        streamKey: sanitizeAssistantVisibleText(event.streamKey),
+        streamRole: sanitizeAssistantVisibleText(event.streamRole)
       }))
       .slice(-MAX_RUN_EVENTS);
   }
@@ -624,8 +627,8 @@
       normalized.push({
         key,
         id: typeof change.id === 'string' ? change.id : '',
-        path: typeof change.path === 'string' ? change.path : '',
-        label: typeof change.label === 'string' ? change.label : ''
+        path: sanitizeAssistantVisibleText(change.path),
+        label: sanitizeAssistantVisibleText(change.label)
       });
     }
     return normalized;
@@ -638,7 +641,7 @@
       if (typeof item !== 'string') {
         continue;
       }
-      const path = redactSecretLikeText(item.trim());
+      const path = sanitizeAssistantVisibleText(item.trim());
       if (!path || seen.has(path)) {
         continue;
       }
@@ -914,7 +917,7 @@
     if (typeof value !== 'string' || !value.trim()) {
       return '';
     }
-    const text = redactSecretLikeText(value);
+    const text = sanitizeAssistantVisibleText(value);
     if (isOmittedStorageSummary(text)) {
       return text;
     }
@@ -938,7 +941,7 @@
     for (const key of Object.keys(value)) {
       const item = value[key];
       if (/(^|[A-Z_])path$/i.test(key) && typeof item === 'string') {
-        const path = redactSecretLikeText(item).replace(/\\/g, '/').replace(/^\/+/, '').trim();
+        const path = sanitizeAssistantVisibleText(item).replace(/\\/g, '/').replace(/^\/+/, '').trim();
         if (path) {
           state.count += 1;
           if (!state.seen.has(path) && state.items.length < 5) {
@@ -991,13 +994,107 @@
   }
 
   function normalizeTextField(value, maxChars) {
-    const text = typeof value === 'string' ? redactSecretLikeText(value) : '';
+    const text = sanitizeAssistantVisibleText(value);
     if (!Number.isFinite(maxChars) || maxChars <= 0 || text.length <= maxChars) {
       return text;
     }
     return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
   }
 
+  function normalizeHistoryEntries(history) {
+    return (Array.isArray(history) ? history : [])
+      .slice(-10)
+      .map(entry => ({
+        task: sanitizeAssistantVisibleText(entry?.task) || 'untitled task',
+        result: sanitizeAssistantVisibleText(entry?.result || entry?.status) || 'completed',
+        at: typeof entry?.at === 'string' ? entry.at : ''
+      }));
+  }
+
+  function sanitizeAssistantVisibleValue(value, depth = 0) {
+    if (typeof value === 'string') {
+      return sanitizeAssistantVisibleText(value);
+    }
+    if (value === undefined || value === null || typeof value === 'number' || typeof value === 'boolean') {
+      return value;
+    }
+    if (depth > 12) {
+      return '[redacted nested value]';
+    }
+    if (Array.isArray(value)) {
+      return value.map(item => sanitizeAssistantVisibleValue(item, depth + 1));
+    }
+    if (typeof value === 'object') {
+      const result = {};
+      for (const key of Object.keys(value)) {
+        const safeKey = sanitizeAssistantVisibleText(key) || key;
+        result[safeKey] = sanitizeAssistantVisibleValue(value[key], depth + 1);
+      }
+      return result;
+    }
+    return value;
+  }
+
+  function sanitizeAssistantVisibleText(value) {
+    if (typeof value !== 'string' || !value) {
+      return '';
+    }
+    const secretRedacted = redactSecretLikeText(value);
+    if (!mightContainLocalReferenceText(secretRedacted)) {
+      return secretRedacted;
+    }
+    if (LineReferences?.sanitizeLocalReferences) {
+      try {
+        return LineReferences.sanitizeLocalReferences(secretRedacted, {
+          projectFiles: [],
+          context: 'persist'
+        });
+      } catch (_error) {
+        return fallbackSanitizeLocalReferences(secretRedacted);
+      }
+    }
+    return fallbackSanitizeLocalReferences(secretRedacted);
+  }
+
+  function mightContainLocalReferenceText(value) {
+    return /(?:file:\/\/\/?|[A-Za-z]:[\\/]|\/(?:Users|home|private|var|tmp)\/|[\\/]\.codex-overleaf[\\/]projects[\\/]|\.codex-overleaf[\\/]projects[\\/])/i.test(String(value || ''));
+  }
+
+  function loadLineReferences() {
+    if (typeof globalThis !== 'undefined' && globalThis.CodexOverleafLineReferences) {
+      return globalThis.CodexOverleafLineReferences;
+    }
+    if (typeof require === 'function') {
+      try {
+        return require('./lineReferences');
+      } catch (_error) {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  function fallbackSanitizeLocalReferences(value) {
+    return String(value || '')
+      .replace(/\[([^\]]*)\]\(([^)]*)\)/g, (_raw, label, target) => {
+        const safeLabel = fallbackSanitizeBareLocalPaths(label);
+        return /^https?:\/\//i.test(String(target || '').trim())
+          ? `[${safeLabel}](${target})`
+          : `[${safeLabel}]`;
+      })
+      .replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/][^\s)\]]+)/gi, rawPath => {
+        const line = String(rawPath || '').match(/:(\d+)(?::\d+)?(?:[.,;!?])?$/)?.[1];
+        return line ? `[local path:${line}]` : '[local path]';
+      });
+  }
+
+  function fallbackSanitizeBareLocalPaths(value) {
+    return String(value || '').replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/][^\s)\]]+)/gi, rawPath => {
+      const line = String(rawPath || '').match(/:(\d+)(?::\d+)?(?:[.,;!?])?$/)?.[1];
+      return line ? `[local path:${line}]` : '[local path]';
+    });
+  }
+
   function redactSecretLikeText(value) {
     if (typeof value !== 'string') {
       return '';

package/extension/src/shared/storageDb.js

@@ -812,13 +812,71 @@
   }
 
   function normalizeTextField(value, maxChars) {
-    var text = typeof value === 'string' ? redactSecretLikeText(value) : '';
+    var text = sanitizeAssistantVisibleText(value);
     if (!Number.isFinite(maxChars) || maxChars <= 0 || text.length <= maxChars) {
       return text;
     }
     return text.slice(0, Math.max(0, maxChars - 1)) + '…';
   }
 
+  function sanitizeAssistantVisibleText(value) {
+    if (typeof value !== 'string' || !value) {
+      return '';
+    }
+    var text = redactSecretLikeText(value);
+    if (!mightContainLocalReferenceText(text)) {
+      return text;
+    }
+    return sanitizeLocalReferencesForStorage(text);
+  }
+
+  function mightContainLocalReferenceText(value) {
+    return /(?:file:\/\/\/?|[A-Za-z]:[\\/]|\/(?:Users|home|private|var|tmp)\/|[\\/]\.codex-overleaf[\\/]projects[\\/]|\.codex-overleaf[\\/]projects[\\/])/i.test(String(value || ''));
+  }
+
+  function sanitizeLocalReferencesForStorage(value) {
+    return String(value || '')
+      .replace(/\[([^\]]*)\]\(([^)]*)\)/g, function (_raw, label, target) {
+        var safeLabel = sanitizeBareLocalPaths(label, false);
+        var trimmedTarget = String(target || '').trim();
+        if (/^https?:\/\//i.test(trimmedTarget)) {
+          return '[' + safeLabel + '](' + sanitizeHttpTarget(trimmedTarget) + ')';
+        }
+        if (mightContainLocalReferenceText(trimmedTarget)) {
+          return '[' + safeLabel + ']';
+        }
+        return '[' + safeLabel + '](' + sanitizeBareLocalPaths(trimmedTarget, false) + ')';
+      })
+      .replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/]projects[\\/][^\s)\]]+)/gi, function (rawPath) {
+        return formatLocalPathPlaceholder(rawPath, true);
+      });
+  }
+
+  function sanitizeBareLocalPaths(value, includeBrackets) {
+    return String(value || '').replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/]projects[\\/][^\s)\]]+)/gi, function (rawPath) {
+      return formatLocalPathPlaceholder(rawPath, includeBrackets);
+    });
+  }
+
+  function sanitizeHttpTarget(value) {
+    try {
+      var parsed = new URL(value);
+      if (mightContainLocalReferenceText(parsed.href)) {
+        parsed.search = '';
+        parsed.hash = '';
+      }
+      return parsed.href;
+    } catch (_error) {
+      return '';
+    }
+  }
+
+  function formatLocalPathPlaceholder(rawPath, includeBrackets) {
+    var lineMatch = String(rawPath || '').match(/:(\d+)(?::\d+)?(?:[.,;!?])?$/);
+    var value = lineMatch ? 'local path:' + lineMatch[1] : 'local path';
+    return includeBrackets ? '[' + value + ']' : value;
+  }
+
   function nonNegativeInteger(value) {
     var number = Number(value);
     return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0;

package/native-host/src/codexPrompt.js

@@ -4,6 +4,7 @@ function buildCodexPrompt(request) {
   const project = request.project || {};
   const files = Array.isArray(project.files) ? project.files : [];
   const focusFiles = normalizeFocusFiles(request.focusFiles || request.session?.focusFiles);
+  const activePath = normalizeProjectPath(project.activePath);
   const orderedFiles = orderFilesByFocus(files, focusFiles);
   const inventory = orderedFiles.map(file => `- ${file.path} (${String(file.content || '').length} chars)`).join('\n') || '- no files supplied';
 
@@ -15,7 +16,7 @@ function buildCodexPrompt(request) {
     `Reasoning effort: ${request.reasoningEffort || 'default'}`,
     `Session: ${request.session?.id || 'none'}`,
     `Task: ${request.task}`,
-    `Active file: ${project.activePath || 'unknown'}`,
+    `Active file: ${activePath || 'unknown'}`,
     '',
     'Recent session history:',
     formatSessionHistory(request.session?.history),
@@ -23,6 +24,12 @@ function buildCodexPrompt(request) {
     'Focus files:',
     formatFocusFiles(focusFiles, files),
     '',
+    'Project location citation rules:',
+    formatProjectLocationCitationRules(),
+    '',
+    'Focused project file inventory:',
+    formatFocusedProjectFileInventory([activePath, ...focusFiles]),
+    '',
     'Files:',
     inventory,
     '',
@@ -62,10 +69,7 @@ function normalizeFocusFiles(value) {
   const seen = new Set();
   const files = [];
   for (const item of Array.isArray(value) ? value : []) {
-    if (typeof item !== 'string') {
-      continue;
-    }
-    const path = item.trim();
+    const path = normalizeProjectPath(item);
     if (!path || seen.has(path)) {
       continue;
     }
@@ -75,6 +79,42 @@ function normalizeFocusFiles(value) {
   return files.slice(0, 5);
 }
 
+function normalizeProjectPath(value) {
+  const path = String(value || '')
+    .replace(/^@file:/i, '')
+    .replace(/\\/g, '/')
+    .trim();
+  if (!path || /^file:\/\//i.test(path) || /^[A-Za-z]:\//.test(path)) {
+    return '';
+  }
+  const projectPath = path.replace(/^\/+/, '');
+  const wasAbsolutePath = path.startsWith('/');
+  if (wasAbsolutePath && /^(Users|home|tmp|var|private|Volumes)\//i.test(projectPath)) {
+    return '';
+  }
+  if (/(^|\/)\.codex-overleaf\/projects(\/|$)/.test(projectPath)) {
+    return '';
+  }
+  return projectPath;
+}
+
+function formatProjectLocationCitationRules() {
+  return [
+    '- In any user-visible output, cite project locations using only Overleaf project-relative paths from the project file inventory below.',
+    '- Use path:LINE[:COLUMN] (for example, path/to/file.tex:12:3).',
+    '- Do not cite local absolute paths, temporary workspace paths, file:// URLs, or markdown links to local files.',
+    '- If a line number is uncertain, cite only the project-relative file path.'
+  ].join('\n');
+}
+
+function formatFocusedProjectFileInventory(files) {
+  const focusFiles = normalizeFocusFiles(files);
+  if (!focusFiles.length) {
+    return '- none selected.';
+  }
+  return focusFiles.map(filePath => `- ${filePath}`).join('\n');
+}
+
 function formatFocusFiles(focusFiles, files) {
   if (!focusFiles.length) {
     return '- none (default to whole project)';

package/native-host/src/codexPromptAssembly.js

@@ -30,10 +30,15 @@ function buildCodexTurnPrompt(options = {}) {
     '',
     'Current Overleaf workspace:',
     `- Project: ${context.projectKey || context.projectId || 'unknown'}`,
-    `- Local workspace: ${context.workspacePath || 'current cwd'}`,
     '- The local workspace was synced from Overleaf immediately before this turn.',
     '- If the recent session history conflicts with the files in the workspace, trust the files.',
     '',
+    'Project location citation rules:',
+    formatProjectLocationCitationRules(),
+    '',
+    'Focused project file inventory:',
+    formatFocusedProjectFileInventory(context.focusFiles),
+    '',
     'Focus files:',
     formatFocusFiles(context.focusFiles),
     '',
@@ -222,11 +227,40 @@ function normalizeFocusFiles(value) {
 }
 
 function normalizeProjectPath(value) {
-  return String(value || '')
+  const path = String(value || '')
     .replace(/^@file:/i, '')
     .replace(/\\/g, '/')
-    .trim()
-    .replace(/^\/+/, '');
+    .trim();
+  if (!path || /^file:\/\//i.test(path) || /^[A-Za-z]:\//.test(path)) {
+    return '';
+  }
+  const projectPath = path.replace(/^\/+/, '');
+  const wasAbsolutePath = path.startsWith('/');
+  if (wasAbsolutePath && /^(Users|home|tmp|var|private|Volumes)\//i.test(projectPath)) {
+    return '';
+  }
+  if (/(^|\/)\.codex-overleaf\/projects(\/|$)/.test(projectPath)) {
+    return '';
+  }
+  return projectPath;
+}
+
+function formatProjectLocationCitationRules() {
+  return [
+    '- In any user-visible output, cite project locations using only Overleaf project-relative paths from the project file inventory below.',
+    '- Use path:LINE[:COLUMN] (for example, path/to/file.tex:12:3).',
+    '- Do not wrap project location citations in backticks or inline code; write main.tex:28 as normal text so the browser can turn it into a jump button.',
+    '- Do not cite local absolute paths, temporary workspace paths, file:// URLs, or markdown links to local files.',
+    '- If a line number is uncertain, cite only the project-relative file path.'
+  ].join('\n');
+}
+
+function formatFocusedProjectFileInventory(files) {
+  const focusFiles = normalizeFocusFiles(files);
+  if (!focusFiles.length) {
+    return '- none selected.';
+  }
+  return focusFiles.map(filePath => `- ${filePath}`).join('\n');
 }
 
 function formatFocusFiles(files) {

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "codex-overleaf-link",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Cross-platform Chrome bridge that connects Codex to the active Overleaf project.",
   "license": "MIT",
   "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ghqqqq/codex-overleaf-link.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ghqqqq/codex-overleaf-link/issues"
+  },
+  "homepage": "https://github.com/Ghqqqq/codex-overleaf-link#readme",
   "scripts": {
     "agent:codex": "node scripts/codex-json-agent.mjs",
     "test": "node scripts/run-tests.mjs",