npm - docrev - Versions diffs - 0.9.17 → 0.9.18 - Mend

docrev 0.9.17 → 0.9.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/dist/lib/anchor-match.d.ts +1 -1
package/dist/lib/anchor-match.d.ts.map +1 -1
package/dist/lib/anchor-match.js +17 -47
package/dist/lib/anchor-match.js.map +1 -1
package/dist/lib/build.d.ts +111 -1
package/dist/lib/build.d.ts.map +1 -1
package/dist/lib/build.js +351 -21
package/dist/lib/build.js.map +1 -1
package/dist/lib/commands/build.d.ts.map +1 -1
package/dist/lib/commands/build.js +25 -10
package/dist/lib/commands/build.js.map +1 -1
package/dist/lib/schema.d.ts.map +1 -1
package/dist/lib/schema.js +37 -0
package/dist/lib/schema.js.map +1 -1
package/docs-src/build.py +113 -113
package/docs-src/extra.css +208 -208
package/docs-src/md-to-html.lua +6 -6
package/docs-src/template.html +116 -116
package/issues.md +180 -0
package/lib/anchor-match.ts +17 -49
package/lib/build.ts +410 -22
package/lib/commands/build.ts +32 -10
package/lib/schema.ts +37 -0
package/mkdocs.yml +64 -64
package/package.json +1 -1
package/site/assets/extra.css +208 -0
package/site/commands.html +926 -0
package/site/configuration.html +469 -0
package/site/index.html +288 -0
package/site/troubleshooting.html +461 -0
package/site/workflow.html +518 -0
package/skill/REFERENCE.md +66 -0
package/skill/SKILL.md +25 -4
package/.claude/settings.local.json +0 -9

package/docs-src/template.html CHANGED Viewed

@@ -1,116 +1,116 @@
-<!DOCTYPE html>
-<html lang="en" data-bs-theme="light">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>$if(pagetitle)$$pagetitle$ — $endif$docrev</title>
-  <meta name="description" content="CLI for writing documents in Markdown while collaborating with Word users.">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@5.3.3/dist/sandstone/bootstrap.min.css">
-$if(highlighting-css)$
-  <style>
-$highlighting-css$
-  </style>
-$endif$
-  <link rel="stylesheet" href="assets/extra.css">
-</head>
-<body>
-<nav class="navbar navbar-expand-lg fixed-top" aria-label="Site navigation">
-  <div class="container">
-    <a class="navbar-brand me-2" href="index.html">docrev</a>
-    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar-main" aria-controls="navbar-main" aria-expanded="false" aria-label="Toggle navigation">
-      <span class="navbar-toggler-icon"></span>
-    </button>
-    <div class="collapse navbar-collapse" id="navbar-main">
-      <ul class="navbar-nav me-auto">
-        <li class="nav-item">
-          <a class="nav-link$if(active-home)$ active$endif$" $if(active-home)$aria-current="page"$endif$ href="index.html">Home</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-workflow)$ active$endif$" $if(active-workflow)$aria-current="page"$endif$ href="workflow.html">Get Started</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-commands)$ active$endif$" $if(active-commands)$aria-current="page"$endif$ href="commands.html">Commands</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-configuration)$ active$endif$" $if(active-configuration)$aria-current="page"$endif$ href="configuration.html">Configuration</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-troubleshooting)$ active$endif$" $if(active-troubleshooting)$aria-current="page"$endif$ href="troubleshooting.html">Troubleshooting</a>
-        </li>
-      </ul>
-      <ul class="navbar-nav">
-        <li class="nav-item">
-          <button id="theme-toggle" class="btn btn-link nav-link border-0" aria-label="Toggle dark mode">
-            <svg id="icon-sun" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
-              <path d="M8 11a3 3 0 1 1 0-6 3 3 0 0 1 0 6m0 1a4 4 0 1 0 0-8 4 4 0 0 0 0 8M8 0a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 0m0 13a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 13m8-5a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2a.5.5 0 0 1 .5.5M3 8a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2A.5.5 0 0 1 3 8m10.657-5.657a.5.5 0 0 1 0 .707l-1.414 1.415a.5.5 0 1 1-.707-.708l1.414-1.414a.5.5 0 0 1 .707 0m-9.193 9.193a.5.5 0 0 1 0 .707L3.05 13.657a.5.5 0 0 1-.707-.707l1.414-1.414a.5.5 0 0 1 .707 0m9.193 2.121a.5.5 0 0 1-.707 0l-1.414-1.414a.5.5 0 0 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707M4.464 4.465a.5.5 0 0 1-.707 0L2.343 3.05a.5.5 0 1 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707"/>
-            </svg>
-            <svg id="icon-moon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16" style="display:none">
-              <path d="M6 .278a.768.768 0 0 1 .08.858 7.208 7.208 0 0 0-.878 3.46c0 4.021 3.278 7.277 7.318 7.277.527 0 1.04-.055 1.533-.16a.787.787 0 0 1 .81.316.733.733 0 0 1-.031.893A8.349 8.349 0 0 1 8.344 16C3.734 16 0 12.286 0 7.71 0 4.266 2.114 1.312 5.124.06A.752.752 0 0 1 6 .278"/>
-            </svg>
-          </button>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="https://github.com/gcol33/docrev" aria-label="GitHub">
-            <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" viewBox="0 0 16 16">
-              <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.012 8.012 0 0 0 16 8c0-4.42-3.58-8-8-8"/>
-            </svg>
-          </a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="https://www.npmjs.com/package/docrev" aria-label="npm">
-            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 16 16">
-              <path d="M0 0v16h16V0zm5.333 13.333H2.667V5.333h2.666v5.334H8V5.333h2.667v8H5.333z"/>
-            </svg>
-          </a>
-        </li>
-      </ul>
-    </div>
-  </div>
-</nav>
-<div class="container template-$if(active-home)$home$else$article$endif$">
-  <div class="row">
-    <main id="main" class="$if(toc)$col-md-9$else$col-12$endif$">
-      $body$
-    </main>
-$if(toc)$
-    <aside class="col-md-3 d-none d-md-block">
-      <nav id="toc" data-toggle="toc" aria-label="On this page">
-        <h2 class="h6">On this page</h2>
-        <div class="toc">$toc$</div>
-      </nav>
-    </aside>
-$endif$
-  </div>
-</div>
-<footer class="border-top py-3 mt-auto">
-  <div class="container d-flex justify-content-between align-items-center text-muted" style="font-size:.85rem">
-    <span>docrev$if(version)$ $version$$endif$</span>
-    <span>Built with <a href="https://pandoc.org" class="text-muted">pandoc</a></span>
-  </div>
-</footer>
-<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
-<script>
-(function () {
-  var html  = document.documentElement;
-  var sun   = document.getElementById('icon-sun');
-  var moon  = document.getElementById('icon-moon');
-  function apply(t) {
-    html.setAttribute('data-bs-theme', t);
-    sun.style.display  = t === 'dark' ? 'none' : '';
-    moon.style.display = t === 'dark' ? ''     : 'none';
-  }
-  apply(localStorage.getItem('docrev-theme') || 'light');
-  document.getElementById('theme-toggle').addEventListener('click', function () {
-    var next = html.getAttribute('data-bs-theme') === 'dark' ? 'light' : 'dark';
-    localStorage.setItem('docrev-theme', next);
-    apply(next);
-  });
-})();
-</script>
-</body>
-</html>
+<!DOCTYPE html>
+<html lang="en" data-bs-theme="light">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>$if(pagetitle)$$pagetitle$ — $endif$docrev</title>
+  <meta name="description" content="CLI for writing documents in Markdown while collaborating with Word users.">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@5.3.3/dist/sandstone/bootstrap.min.css">
+$if(highlighting-css)$
+  <style>
+$highlighting-css$
+  </style>
+$endif$
+  <link rel="stylesheet" href="assets/extra.css">
+</head>
+<body>
+<nav class="navbar navbar-expand-lg fixed-top" aria-label="Site navigation">
+  <div class="container">
+    <a class="navbar-brand me-2" href="index.html">docrev</a>
+    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar-main" aria-controls="navbar-main" aria-expanded="false" aria-label="Toggle navigation">
+      <span class="navbar-toggler-icon"></span>
+    </button>
+    <div class="collapse navbar-collapse" id="navbar-main">
+      <ul class="navbar-nav me-auto">
+        <li class="nav-item">
+          <a class="nav-link$if(active-home)$ active$endif$" $if(active-home)$aria-current="page"$endif$ href="index.html">Home</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-workflow)$ active$endif$" $if(active-workflow)$aria-current="page"$endif$ href="workflow.html">Get Started</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-commands)$ active$endif$" $if(active-commands)$aria-current="page"$endif$ href="commands.html">Commands</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-configuration)$ active$endif$" $if(active-configuration)$aria-current="page"$endif$ href="configuration.html">Configuration</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-troubleshooting)$ active$endif$" $if(active-troubleshooting)$aria-current="page"$endif$ href="troubleshooting.html">Troubleshooting</a>
+        </li>
+      </ul>
+      <ul class="navbar-nav">
+        <li class="nav-item">
+          <button id="theme-toggle" class="btn btn-link nav-link border-0" aria-label="Toggle dark mode">
+            <svg id="icon-sun" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+              <path d="M8 11a3 3 0 1 1 0-6 3 3 0 0 1 0 6m0 1a4 4 0 1 0 0-8 4 4 0 0 0 0 8M8 0a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 0m0 13a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 13m8-5a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2a.5.5 0 0 1 .5.5M3 8a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2A.5.5 0 0 1 3 8m10.657-5.657a.5.5 0 0 1 0 .707l-1.414 1.415a.5.5 0 1 1-.707-.708l1.414-1.414a.5.5 0 0 1 .707 0m-9.193 9.193a.5.5 0 0 1 0 .707L3.05 13.657a.5.5 0 0 1-.707-.707l1.414-1.414a.5.5 0 0 1 .707 0m9.193 2.121a.5.5 0 0 1-.707 0l-1.414-1.414a.5.5 0 0 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707M4.464 4.465a.5.5 0 0 1-.707 0L2.343 3.05a.5.5 0 1 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707"/>
+            </svg>
+            <svg id="icon-moon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16" style="display:none">
+              <path d="M6 .278a.768.768 0 0 1 .08.858 7.208 7.208 0 0 0-.878 3.46c0 4.021 3.278 7.277 7.318 7.277.527 0 1.04-.055 1.533-.16a.787.787 0 0 1 .81.316.733.733 0 0 1-.031.893A8.349 8.349 0 0 1 8.344 16C3.734 16 0 12.286 0 7.71 0 4.266 2.114 1.312 5.124.06A.752.752 0 0 1 6 .278"/>
+            </svg>
+          </button>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link" href="https://github.com/gcol33/docrev" aria-label="GitHub">
+            <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" viewBox="0 0 16 16">
+              <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.012 8.012 0 0 0 16 8c0-4.42-3.58-8-8-8"/>
+            </svg>
+          </a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link" href="https://www.npmjs.com/package/docrev" aria-label="npm">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 16 16">
+              <path d="M0 0v16h16V0zm5.333 13.333H2.667V5.333h2.666v5.334H8V5.333h2.667v8H5.333z"/>
+            </svg>
+          </a>
+        </li>
+      </ul>
+    </div>
+  </div>
+</nav>
+<div class="container template-$if(active-home)$home$else$article$endif$">
+  <div class="row">
+    <main id="main" class="$if(toc)$col-md-9$else$col-12$endif$">
+      $body$
+    </main>
+$if(toc)$
+    <aside class="col-md-3 d-none d-md-block">
+      <nav id="toc" data-toggle="toc" aria-label="On this page">
+        <h2 class="h6">On this page</h2>
+        <div class="toc">$toc$</div>
+      </nav>
+    </aside>
+$endif$
+  </div>
+</div>
+<footer class="border-top py-3 mt-auto">
+  <div class="container d-flex justify-content-between align-items-center text-muted" style="font-size:.85rem">
+    <span>docrev$if(version)$ $version$$endif$</span>
+    <span>Built with <a href="https://pandoc.org" class="text-muted">pandoc</a></span>
+  </div>
+</footer>
+<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
+<script>
+(function () {
+  var html  = document.documentElement;
+  var sun   = document.getElementById('icon-sun');
+  var moon  = document.getElementById('icon-moon');
+  function apply(t) {
+    html.setAttribute('data-bs-theme', t);
+    sun.style.display  = t === 'dark' ? 'none' : '';
+    moon.style.display = t === 'dark' ? ''     : 'none';
+  }
+  apply(localStorage.getItem('docrev-theme') || 'light');
+  document.getElementById('theme-toggle').addEventListener('click', function () {
+    var next = html.getAttribute('data-bs-theme') === 'dark' ? 'light' : 'dark';
+    localStorage.setItem('docrev-theme', next);
+    apply(next);
+  });
+})();
+</script>
+</body>
+</html>

package/issues.md ADDED Viewed

@@ -0,0 +1,180 @@
+# docrev — Open Issues
+Three issues identified during real-world use on the ADAPT proposal build. Working through one by one.
+Status legend: `[ ]` planned · `[~]` in progress · `[x]` shipped
+---
+## Issue 1 — Allow custom pandoc filters / args through `rev build`  `[x]`
+### Problem
+Source markdown with custom raw-LaTeX commands needs a pandoc filter to convert them for docx (e.g. `\tofill{X}` → bold `[X]`). `rev build docx` has no escape hatch:
+- `rev build --help` exposes no `--filter` / `--lua-filter` / `--pandoc-arg`.
+- `rev.yaml` exposes `docx.reference` and `docx.keepComments` but no generic pandoc passthrough.
+Working around it requires letting `rev build` produce `paper.md` as a side effect, then calling pandoc manually — which defeats the point of `rev build`.
+### Design (agreed)
+**rev.yaml**: top-level `pandoc-args` (applied to every format) plus per-format `<format>.pandoc-args` (concatenated *after* the top-level list so format-specific can override):
+```yaml
+pandoc-args:
+  - --lua-filter=tofill_filter.lua
+docx:
+  pandoc-args:
+    - --lua-filter=docx_only.lua
+pdf:
+  pandoc-args:
+    - --variable=papersize:a4
+```
+**CLI**: repeatable `--pandoc-arg <arg>` on `rev build`, appended *after* config args so CLI wins:
+```bash
+rev build docx --pandoc-arg=--lua-filter=tofill.lua --pandoc-arg=--shift-heading-level-by=1
+```
+**Verbose mode**: `rev build --verbose` already exists but doesn't echo the pandoc invocation. Print the full `pandoc <args>` command (one line per format) so users can copy-paste to replicate manually.
+### Touch points
+- `lib/build.ts` — `BuildConfig` + `DEFAULT_CONFIG` (add `pandocArgs: string[]`; add `pandocArgs` to each format config), `buildPandocArgs()` (append top-level then format-specific), `runPandoc()` (echo command under verbose), `loadConfig()` (read hyphenated `pandoc-args` key and map to camelCase `pandocArgs`).
+- `lib/commands/build.ts` — add `--pandoc-arg <arg>` (repeatable via custom collector), forward through `BuildOptions`, ensure CLI args are appended last.
+- `lib/schema.ts` — declare `pandoc-args` (array of strings) at top level and inside each format object.
+- `skill/SKILL.md` + `skill/REFERENCE.md` — document new field and flag with a `--lua-filter=` example.
+- `test/build.test.js` — cover (a) top-level only, (b) format-specific only, (c) both concatenated in order, (d) CLI overrides config.
+### Open questions
+None. Hyphenated YAML key + camelCase TS field is consistent with how the rest of the schema is read (we're already free-form on the JS side, just need a small key transform in `loadConfig`).
+---
+## Issue 2 — Output filename is auto-truncated mid-word and not configurable  `[x]`
+### Problem
+Default output landed at `output/adapt-alien-dark-diversity-across-plant-communitie.docx` — title slugified and hard-truncated at 50 chars (`communitie` missing the trailing `s`). No `-o` flag, no `output:` field in `rev.yaml`.
+Root cause: `lib/build.ts:1055-1056` (`runPandoc`) and `lib/commands/build.ts:591-592` (`--show-changes` path):
+```ts
+const baseName = config.title
+  ? config.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50)
+  : 'paper';
+```
+`.slice(0, 50)` is a blind cut.
+### Design (agreed)
+**rev.yaml**: per-format `output:` map. Extensions optional — added if missing.
+```yaml
+output:
+  docx: ADAPT_proposal_draft.docx
+  pdf: ADAPT_proposal_draft.pdf
+```
+**CLI**: `-o, --output <path>` on `rev build`. When multiple formats are built, applies as basename to all (extension swapped per format); for single-format builds, used verbatim.
+**Truncation fix**: when no `output:` is configured, slug at last `-` boundary at-or-before 50 chars instead of mid-word. Also bump the cap to 80 — 50 is conservative.
+**Doc fix**: surface the default `output/` directory in `rev build --help` and SKILL.md "Project Structure" tree (already mentioned in passing — make it explicit).
+### Touch points
+- `lib/build.ts` — `BuildConfig` (`output?: Record<string, string>`), `DEFAULT_CONFIG`, `runPandoc()` (resolve filename: `config.output[format]` → CLI `-o` → slug). Helper: `resolveOutputName(config, format, cliOverride)`.
+- `lib/commands/build.ts` — add `-o, --output <path>` flag, wire into `BuildOptions`; same fix applied to the `--show-changes` branch's `baseName` construction.
+- `lib/schema.ts` — declare `output` as object mapping format → string.
+- `skill/SKILL.md` — "Project Structure" tree explicitly notes `output/`; new `output:` example under config.
+- `test/build.test.js` — cover (a) `output:` per-format honored, (b) `-o` CLI override, (c) word-boundary truncation when title >50 chars.
+### Resolved
+- `-o` relative paths resolve under `outputDir`; absolute paths bypass it. Same rule applies to values in `output:`.
+- Cap raised from 50 → 80 chars; fallback truncates at the last `-` boundary at-or-before the cap so words stay whole (the ADAPT title now slugs cleanly without losing the trailing "s" on "communities").
+- `--show-changes` and `--dual` derived filenames (`-changes.docx`, `_comments.docx`, `_comments.pdf`) follow the chosen base name.
+- Fixed an unrelated misleading example in SKILL.md that showed `output: { docx: { reference-doc: ... } }` — the real config key is `docx.reference` (top-level), not nested under `output:`.
+---
+## Issue 3 — Raw LaTeX figure blocks silently disappear in docx builds  `[x]`
+### Problem
+Source markdown with `\begin{figure}[H]\includegraphics{...}\end{figure}` blocks renders correctly in the PDF target but produces a docx where all figures are silently missing. Pandoc strips the raw LaTeX because docx has no LaTeX rendering pipeline. No warning is emitted.
+This catches you only on careful inspection — a less careful user would ship a docx with no figures and not notice until a reviewer asks.
+### Design (agreed)
+Three layers, combined:
+**1. Warn during build (always on).** In `applyFormatTransforms()` for docx, scan for raw LaTeX figure environments (`\begin{figure}` … `\end{figure}` containing `\includegraphics`). Emit:
+```
+Warning: 3 raw LaTeX figure block(s) won't render in docx.
+  intro.md:42  \begin{figure}[H] ... \includegraphics{figures/map.pdf} ...
+  methods.md:118
+  results.md:201
+  Hint: use ![caption](path){#fig:label width=80%} for format-portable figures, or
+        pass --pandoc-arg=--lua-filter=<your.lua> to translate them yourself.
+```
+Counted by file/line so the user can jump to fix.
+**2. Auto-translate the common shape (opt-out via `docx.translateRawFigures: false`).** Convert
+```latex
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.8\textwidth]{figures/map.pdf}
+\caption{Map of study sites.}
+\label{fig:map}
+\end{figure}
+```
+→
+```markdown
+![Map of study sites.](figures/map.pdf){#fig:map width=80%}
+```
+Cover the 80% case. If the block has anything more exotic (`\subfloat`, `\rotatebox`, multi-`\includegraphics`), skip auto-translate, warn loudly, and leave the block as-is.
+Width conversion: `0.8\textwidth` → `80%`; bare `8cm` → `8cm`; missing → omit.
+**3. Document.** SKILL.md "Cross-References" section currently mentions `@fig:label` and `{#fig:label}` but doesn't show how to *insert* a figure. Add:
+```markdown
+![Caption text.](figures/foo.pdf){#fig:foo width=80%}
+```
+Note this is the format-portable form. Also mention that raw `\begin{figure}` blocks are PDF-only.
+### Touch points
+- `lib/build.ts` — new helper `detectRawLatexFigures(content): {file?, line, block}[]` and `translateRawLatexFigures(content): {translated, untranslatedCount}`. Wire into `applyFormatTransforms()` for docx (after `convertDynamicRefsToDisplay`).
+- `lib/build.ts` — propagate warnings up via the existing `warnings: string[]` returned by `build()`. `rev build` already prints from there.
+- `lib/commands/build.ts` — surface warnings in normal output (not just verbose).
+- `lib/schema.ts` — declare `docx.translateRawFigures: boolean` (default true).
+- `skill/SKILL.md` — figure-insertion example under "Cross-References".
+- `test/build.test.js` — cover (a) detection counts blocks correctly, (b) auto-translate of `\includegraphics{path}`, (c) auto-translate of `\includegraphics[width=0.8\textwidth]{path}` → `width=80%`, (d) exotic block → not translated, warned, left alone, (e) opt-out via `translateRawFigures: false`.
+### Open questions
+- Should auto-translate also handle bare `\includegraphics{...}` outside a `figure` env? Lean no — keep scope to figure environments. If a user writes raw `\includegraphics` without wrapping, that's a deliberate choice we shouldn't second-guess.
+- Width unit handling: `0.8\textwidth` → `80%` is unambiguous. `\linewidth` → `100%`? Yes. Other relative units → leave raw and warn.
+---
+## Working order
+1. **Issue 1** first — unblocks immediate workflow needs and provides the manual escape hatch for issue 3 even before auto-translate ships.
+2. **Issue 2** next — small, low-risk, quality-of-life win.
+3. **Issue 3** last — biggest behavior change; benefits from the verbose pandoc echo (Issue 1) for debugging the lua-filter fallback path.

package/lib/anchor-match.ts CHANGED Viewed

@@ -11,8 +11,6 @@ export type AnchorStrategy =
   | 'stripped'
   | 'partial-start'
   | 'partial-start-stripped'
-  | 'partial-window'
-  | 'partial-window-stripped'
   | 'context-both'
   | 'context-before'
   | 'context-after'
@@ -173,69 +171,41 @@ export function findAnchorInText(
     return { occurrences, matchedAnchor: anchor, strategy: 'stripped', stripped: true };
   }
-  // Strategy 4: word window from anchor (prefix or interior).
-  // Sliding the window across the anchor catches the case where the
-  // anchor's prefix has been edited but a chunk in the middle/end
-  // survived intact (e.g. "Sensitivity analyses were performed by
-  // perturbing the prior variance" → drifted "Sensitivity analyses
-  // perturbed the prior variance" still contains "the prior variance").
+  // Strategy 4: first N words of anchor (long anchors)
   const words = anchor.split(/\s+/);
   if (words.length > 3) {
     for (let n = Math.min(6, words.length); n >= 3; n--) {
-      for (let start = 0; start + n <= words.length; start++) {
-        const window = words.slice(start, start + n).join(' ');
-        const windowLower = window.toLowerCase();
-        if (windowLower.length < 15) continue;
-        let occ = findAllOccurrences(textLower, windowLower);
-        if (occ.length > 0) {
-          const strategy: AnchorStrategy = start === 0 ? 'partial-start' : 'partial-window';
-          return { occurrences: occ, matchedAnchor: window, strategy };
+      const partialAnchor = words.slice(0, n).join(' ').toLowerCase();
+      if (partialAnchor.length >= 15) {
+        occurrences = findAllOccurrences(textLower, partialAnchor);
+        if (occurrences.length > 0) {
+          return { occurrences, matchedAnchor: words.slice(0, n).join(' '), strategy: 'partial-start' };
         }
-        occ = findAllOccurrences(strippedLower, windowLower);
-        if (occ.length > 0) {
-          const strategy: AnchorStrategy = start === 0 ? 'partial-start-stripped' : 'partial-window-stripped';
-          return { occurrences: occ, matchedAnchor: window, strategy, stripped: true };
+        occurrences = findAllOccurrences(strippedLower, partialAnchor);
+        if (occurrences.length > 0) {
+          return {
+            occurrences,
+            matchedAnchor: words.slice(0, n).join(' '),
+            strategy: 'partial-start-stripped',
+            stripped: true,
+          };
         }
       }
     }
   }
-  // Strategy 5: context (before/after) only.
-  //
-  // For a non-empty anchor that already failed every text-based strategy
-  // above, we treat context as a degraded placement: classify it
-  // 'context-only' so callers can warn the user. We also reject
-  // implausible brackets — if both contexts match but the gap between
-  // them is far too small to contain the anchor (e.g. the anchored
-  // sentence was deleted), do not silently land the comment between
-  // the surviving sentences. Return 'failed' so the user is told to
-  // place it manually.
+  // Strategy 5: context (before/after) only
   if (before || after) {
     const beforeLower = before.toLowerCase();
     const afterLower = after.toLowerCase();
-    const anchorLen = anchor.length;
     if (before && after) {
       const beforeIdx = textLower.indexOf(beforeLower.slice(-50));
       if (beforeIdx !== -1) {
         const searchStart = beforeIdx + beforeLower.slice(-50).length;
         const afterIdx = textLower.indexOf(afterLower.slice(0, 50), searchStart);
-        if (afterIdx !== -1) {
-          const gap = afterIdx - searchStart;
-          // Require the bracket to plausibly contain a remnant of the anchor.
-          // Below 30% of anchor length: anchor was deleted — refuse to place.
-          // Above 2× anchor length + slack: brackets are too far apart, the
-          // matcher has latched onto unrelated repeats of common context.
-          const minGap = Math.floor(anchorLen * 0.3);
-          const maxGap = Math.min(500, anchorLen * 2 + 50);
-          if (gap >= minGap && gap <= maxGap) {
-            return { occurrences: [searchStart], matchedAnchor: null, strategy: 'context-both' };
-          }
-          // Both brackets found but gap implausible: anchor likely deleted.
-          // Don't fall back to single-side context — that would silently
-          // place the comment in the wrong location.
-          return { occurrences: [], matchedAnchor: null, strategy: 'failed' };
+        if (afterIdx !== -1 && afterIdx - searchStart < 500) {
+          return { occurrences: [searchStart], matchedAnchor: null, strategy: 'context-both' };
         }
       }
     }
@@ -292,8 +262,6 @@ export function classifyStrategy(strategy: AnchorStrategy, occurrences: number):
     case 'stripped':
     case 'partial-start':
     case 'partial-start-stripped':
-    case 'partial-window':
-    case 'partial-window-stripped':
     case 'split-match':
       return 'drift';
     case 'context-both':