Update docs

mathpluscode · mathpluscode · commit a575d79a0fc3 · 2026-04-12T18:44:03.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -33,6 +33,10 @@ The skill's tools live under `skills/bibtidy/tools/` in this repo. At runtime, d
 - Run `./tests/run_bibtidy_codex_tests.sh` for the Codex end-to-end path
 - Unit tests only: `uv run pytest tests/`
 
+## Previewing README
+
+Preview `README.md` (including Mermaid charts) locally with `gh markdown-preview README.md` (requires the `gh-markdown-preview` extension).
+
 ## Website (docs/)
 
 `docs/index.html` is generated by `docs/build.py`. Never edit `index.html` directly. Make changes in `build.py`, then run `python docs/build.py` to regenerate.
diff --git a/README.md b/README.md
@@ -55,49 +55,46 @@ Start a new Codex session afterwards so the refreshed `SKILL.md` is loaded into
 
 ## bibtidy
 
+In both Claude Code and Codex, use:
+
 ```text
-Use bibtidy to validate and fix refs.bib
+/bibtidy refs.bib
 ```
 
-Or in Claude Code, use the slash command: `/bibtidy refs.bib`
-
 bibtidy verifies each entry against [Google Scholar](https://scholar.google.com/) and [CrossRef](https://search.crossref.org/), fixes errors, and upgrades stale preprints to published versions. Every change includes the original entry commented out above so you can compare or revert, plus one or more `% bibtidy:` URL lines for verification. We recommend using git to track changes. If using [Overleaf](https://www.overleaf.com/), this can be done with [git sync](https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization). To remove bibtidy comments after review, ask your agent to remove all `bibtidy` comments from the file.
 
-bibtidy's output is non-deterministic: the same `.bib` file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry. See the [FAQ](#bibtidy) for why, and always verify changes via the `% bibtidy:` URLs before accepting them.
+bibtidy's output is non-deterministic: the same `.bib` file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry. See the FAQ section below for more on why, and always verify changes via the `% bibtidy:` URLs before accepting them.
 
 Note that bibtidy assumes standard brace-style BibTeX like `@article{...}`. Parenthesized forms like `@article(...)` are not supported. Special blocks such as `@string`, `@preamble`, and `@comment` are ignored by the parser.
 
 ### How it works
 
-bibtidy walks each entry through a bounded state machine. Every entry has a **web-search budget of 1**, spent at most once across two possible waves:
+Each entry goes through the following pipeline. A web search is used at most once per entry to keep runs fast. Each entry ends in one of four states: Clean (no change, no comment), Fix (patch applied with URLs + explanation), Not found (hallucinated, entry commented out), or Review (budget spent, entry unchanged, comment added for human attention).
 
 ```mermaid
-flowchart TD
-    P1["Phase 1: duplicates.py (exact/subset, lossless)"]
-    P2["Phase 2: compare.py fetches CrossRef candidates"]
-    HAS{"candidates?"}
-    WA["Wave A web search<br/>(mandatory, budget spent)"]
-    P3{"Phase 3: agent decides per entry"}
-    BUDGET{"budget spent?"}
-    WB["Wave B web search<br/>(budget spent)"]
-    DECIDE2["decide again with combined info"]
-    REVIEW["add '% bibtidy: REVIEW' comment<br/>with URLs, bib entry unchanged"]
-    PATCH["build fix patch (or no-op)"]
-    P4["Phase 4: duplicates.py (post-fix)<br/>+ manual near-duplicate review"]
+flowchart LR
+    P1["Deduplicate"]
+    P2["Query CrossRef"]
+    HAS{"Found?"}
+    WA["Web search"]
+    P3{"Confident?"}
+    BUDGET{"Web searched?"}
+    WB["Web search"]
+    PATCH["Patch or no-op"]
+    REVIEW["Flag for review"]
+    P4["Post-fix deduplicate"]
 
     P1 --> P2 --> HAS
-    HAS -- yes --> P3
-    HAS -- no --> WA --> P3
-    P3 -- confident --> PATCH
-    P3 -- not confident --> BUDGET
-    BUDGET -- no --> WB --> DECIDE2 --> PATCH
-    BUDGET -- yes --> REVIEW
+    HAS -- Y --> P3
+    HAS -- N --> WA --> P3
+    P3 -- Y --> PATCH
+    P3 -- N --> BUDGET
+    BUDGET -- N --> WB --> PATCH
+    BUDGET -- Y --> REVIEW
     PATCH --> P4
     REVIEW --> P4
 ```
 
-Each entry ends in one of four states: **Clean** (no change, no comment), **Fix** (patch applied with URLs + explanation), **Not found** (hallucinated, entry commented out), or **Review** (budget spent, entry unchanged, comment added for human attention).
-
 ### Examples
 
 <details>
diff --git a/docs/build.py b/docs/build.py
@@ -287,13 +287,12 @@ def build_html(cards_html: str) -> str:
   }}
 
   .header {{
-    border-bottom: 1px solid var(--border);
-    padding: 2rem 0;
+    padding: 2rem 0 0.5rem;
     text-align: center;
   }}
 
   .header h1 {{ font-size: 2rem; font-weight: 600; margin-bottom: 0.5rem; }}
-  .header p {{ color: var(--text-muted); font-size: 1.1rem; }}
+  .header p {{ color: var(--text-muted); }}
 
   .github-link {{
     display: inline-flex;
@@ -455,6 +454,43 @@ def build_html(cards_html: str) -> str:
   .stats .del-count {{ color: var(--del-line); }}
 
   .diff-body a {{ color: var(--accent); }}
+
+  /* Tabs */
+  .tabs {{
+    display: flex;
+    border-bottom: 1px solid var(--border);
+    margin-bottom: 2rem;
+  }}
+
+  .tab-btn {{
+    background: none;
+    border: none;
+    border-bottom: 2px solid transparent;
+    padding: 0.6rem 1.25rem;
+    font-family: inherit;
+    font-size: 0.95rem;
+    font-weight: 500;
+    color: var(--text-muted);
+    cursor: pointer;
+    transition: color 0.15s, border-color 0.15s;
+  }}
+
+  .tab-btn:hover {{
+    color: var(--text);
+  }}
+
+  .tab-btn.active {{
+    color: var(--accent);
+    border-bottom-color: var(--accent);
+  }}
+
+  .tab-panel {{
+    display: none;
+  }}
+
+  .tab-panel.active {{
+    display: block;
+  }}
 </style>
 </head>
 <body>
@@ -471,16 +507,21 @@ def build_html(cards_html: str) -> str:
 </div>
 
 <div class="container">
-<p class="intro">bibtidy cross-checks BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. It upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags duplicate entries.</p>
 
-<p class="intro"><strong>Note:</strong> bibtidy's output is non-deterministic. The same <code>.bib</code> file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry, due to variability in search results, LLM sampling, and differences between the two agents' underlying models. Every change ships with <code>% bibtidy:</code> URLs for verification &mdash; treat the output as a reviewed first draft, not a final answer.</p>
+<div class="tabs">
+  <button class="tab-btn active" data-tab="bibtidy" onclick="switchTab('bibtidy')">bibtidy</button>
+</div>
+
+<div id="tab-bibtidy" class="tab-panel active">
 
 <div class="section">
   <div class="demo">
     <img src="bibtidy_demo.gif" alt="bibtidy demo" width="1600" height="1200">
   </div>
 </div>
 
+<p class="intro">bibtidy cross-checks BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. It upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags duplicate entries.</p>
+
 <div class="section">
   <h2 class="section-title">Install</h2>
 
@@ -521,6 +562,18 @@ def build_html(cards_html: str) -> str:
 
 </div>
 
+<div class="section">
+  <h2 class="section-title">Usage</h2>
+
+  <div class="install-step">
+    <p>In both Claude Code and Codex, use:</p>
+    <div class="code-block"><code>/bibtidy refs.bib</code><button class="copy-btn" type="button" onclick="copyCode(this)">Copy</button></div>
+  </div>
+
+  <p class="intro">bibtidy's output is non-deterministic. The same <code>.bib</code> file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry, due to variability in search results, LLM sampling, and differences between the two agents' underlying models. Every change ships with <code>% bibtidy:</code> URLs for verification &mdash; treat the output as a reviewed first draft, not a final answer.</p>
+
+</div>
+
 <div class="section">
   <h2 class="section-title">Examples</h2>
 
@@ -530,7 +583,16 @@ def build_html(cards_html: str) -> str:
 
 </div>
 
+</div>
+
 <script>
+function switchTab(id) {{
+  document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
+  document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
+  document.querySelector('.tab-btn[data-tab="' + id + '"]').classList.add('active');
+  document.getElementById('tab-' + id).classList.add('active');
+}}
+
 function copyCode(btn) {{
   const code = btn.previousElementSibling.textContent;
   navigator.clipboard.writeText(code).then(() => {{
@@ -554,11 +616,7 @@ def main() -> None:
 
     input_entries = {e["key"]: e for e in parse_entries(input_text)}
     expected_entries = parse_entries(expected_text)
-
-    # Build a lookup for expected entries
-    expected_by_key = {}
-    for e in expected_entries:
-        expected_by_key[e["key"]] = e
+    expected_by_key = {e["key"]: e for e in expected_entries}
 
     # Generate diff cards, separating by category
     notfound_cards = []
diff --git a/docs/index.html b/docs/index.html
@@ -82,13 +82,12 @@
   }
 
   .header {
-    border-bottom: 1px solid var(--border);
-    padding: 2rem 0;
+    padding: 2rem 0 0.5rem;
     text-align: center;
   }
 
   .header h1 { font-size: 2rem; font-weight: 600; margin-bottom: 0.5rem; }
-  .header p { color: var(--text-muted); font-size: 1.1rem; }
+  .header p { color: var(--text-muted); }
 
   .github-link {
     display: inline-flex;
@@ -250,6 +249,43 @@
   .stats .del-count { color: var(--del-line); }
 
   .diff-body a { color: var(--accent); }
+
+  /* Tabs */
+  .tabs {
+    display: flex;
+    border-bottom: 1px solid var(--border);
+    margin-bottom: 2rem;
+  }
+
+  .tab-btn {
+    background: none;
+    border: none;
+    border-bottom: 2px solid transparent;
+    padding: 0.6rem 1.25rem;
+    font-family: inherit;
+    font-size: 0.95rem;
+    font-weight: 500;
+    color: var(--text-muted);
+    cursor: pointer;
+    transition: color 0.15s, border-color 0.15s;
+  }
+
+  .tab-btn:hover {
+    color: var(--text);
+  }
+
+  .tab-btn.active {
+    color: var(--accent);
+    border-bottom-color: var(--accent);
+  }
+
+  .tab-panel {
+    display: none;
+  }
+
+  .tab-panel.active {
+    display: block;
+  }
 </style>
 </head>
 <body>
@@ -266,16 +302,21 @@ <h1>bibtools</h1>
 </div>
 
 <div class="container">
-<p class="intro">bibtidy cross-checks BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. It upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags duplicate entries.</p>
 
-<p class="intro"><strong>Note:</strong> bibtidy's output is non-deterministic. The same <code>.bib</code> file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry, due to variability in search results, LLM sampling, and differences between the two agents' underlying models. Every change ships with <code>% bibtidy:</code> URLs for verification &mdash; treat the output as a reviewed first draft, not a final answer.</p>
+<div class="tabs">
+  <button class="tab-btn active" data-tab="bibtidy" onclick="switchTab('bibtidy')">bibtidy</button>
+</div>
+
+<div id="tab-bibtidy" class="tab-panel active">
 
 <div class="section">
   <div class="demo">
     <img src="bibtidy_demo.gif" alt="bibtidy demo" width="1600" height="1200">
   </div>
 </div>
 
+<p class="intro">bibtidy cross-checks BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. It upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags duplicate entries.</p>
+
 <div class="section">
   <h2 class="section-title">Install</h2>
 
@@ -316,6 +357,18 @@ <h3 style="font-size: 1rem; font-weight: 600; margin: 1.5rem 0 0.75rem;">Codex</
 
 </div>
 
+<div class="section">
+  <h2 class="section-title">Usage</h2>
+
+  <div class="install-step">
+    <p>In both Claude Code and Codex, use:</p>
+    <div class="code-block"><code>/bibtidy refs.bib</code><button class="copy-btn" type="button" onclick="copyCode(this)">Copy</button></div>
+  </div>
+
+  <p class="intro">bibtidy's output is non-deterministic. The same <code>.bib</code> file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry, due to variability in search results, LLM sampling, and differences between the two agents' underlying models. Every change ships with <code>% bibtidy:</code> URLs for verification &mdash; treat the output as a reviewed first draft, not a final answer.</p>
+
+</div>
+
 <div class="section">
   <h2 class="section-title">Examples</h2>
 
@@ -607,7 +660,16 @@ <h2 class="section-title">Examples</h2>
 
 </div>
 
+</div>
+
 <script>
+function switchTab(id) {
+  document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
+  document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
+  document.querySelector('.tab-btn[data-tab="' + id + '"]').classList.add('active');
+  document.getElementById('tab-' + id).classList.add('active');
+}
+
 function copyCode(btn) {
   const code = btn.previousElementSibling.textContent;
   navigator.clipboard.writeText(code).then(() => {
diff --git a/tests/test_docs_build.py b/tests/test_docs_build.py
@@ -10,6 +10,7 @@
 assert _SPEC is not None and _SPEC.loader is not None
 _MODULE = module_from_spec(_SPEC)
 _SPEC.loader.exec_module(_MODULE)
+build_html = _MODULE.build_html
 linkify = _MODULE.linkify
 
 
@@ -23,3 +24,9 @@ def test_linkify_escapes_non_url_text() -> None:
     result = linkify('5 < 6 and "ok" https://example.com?a=1&b=2')
     assert "5 &lt; 6 and &quot;ok&quot;" in result
     assert 'href="https://example.com?a=1&amp;b=2"' in result
+
+
+def test_build_html_includes_shared_usage_example() -> None:
+    result = build_html("")
+    assert "<p>In both Claude Code and Codex, use:</p>" in result
+    assert "<code>/bibtidy refs.bib</code>" in result
