quartobot 0.1.0__tar.gz

quartobot-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# macOS
+.DS_Store
+
+# Editor
+.vscode/
+.idea/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Quarto (when example projects accumulate)
+_output/
+_freeze/
+.quarto/
+*_files/

quartobot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

quartobot-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: quartobot
+Version: 0.1.0
+Summary: The manubot manuscript-as-software pattern, on Quarto.
+Project-URL: Homepage, https://github.com/seandavi/quartobot
+Project-URL: Documentation, https://seandavi.github.io/quartobot
+Project-URL: Issues, https://github.com/seandavi/quartobot/issues
+Project-URL: Source, https://github.com/seandavi/quartobot
+Author-email: Sean Davis <seandavi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: citations,manubot,quarto,reproducible-research,scholarly-publishing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: manubot<0.7,>=0.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# quartobot
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-v0.1%20in%20flight-orange.svg)](DESIGN.md)
+
+The manubot manuscript-as-software pattern, on Quarto.
+
+> **Status:** v0.1 in flight. CLI commands ship; the Quarto extension
+> and the manuscript template ship. An architecture pivot is under
+> discussion in [`docs/citation-pipeline.md`](docs/citation-pipeline.md)
+> that would collapse the extension into a single pre-render hook
+> calling the CLI directly — read the design doc before non-trivial
+> work, and watch the [v0.1 milestone](https://github.com/seandavi/quartobot/milestone/1)
+> for tagging.
+
+## What this is
+
+Manubot has, for eight years, run scholarly manuscripts as a git repository
+that builds itself on every commit, resolves citations from DOIs and
+PubMed IDs automatically, hands out an immutable permalink per commit, and
+collaborates through pull requests. The pattern is published
+([Himmelstein et al. 2019](https://doi.org/10.1371/journal.pcbi.1007128))
+and has been used for hundreds of preprints.
+
+Quarto now covers more of scholarly publishing than manubot ever did —
+manuscripts, books, websites, slides, dashboards, courseware — but the
+manubot pattern does not yet exist there natively. That's the gap this
+repo closes.
+
+The shipping surface is a Python CLI and (optionally) a GitHub template:
+
+1. **`quartobot`** — a Python CLI. `quartobot resolve` pre-fetches
+   citations through manubot's resolver library, so CI never sees a
+   Crossref hiccup mid-render. `quartobot scan` summarizes cite keys
+   grouped by prefix with duplicate detection. `quartobot validate`
+   is the CI-lint surface (static checks against `_quarto.yml`).
+   `quartobot init` scaffolds the pattern into an existing Quarto
+   project. Authors write `@doi:10.1371/journal.pcbi.1007128`,
+   `@pmid:31479462`, `@arxiv:2104.10729`, `@isbn:…`, or bare DOIs in
+   their prose, and citations resolve.
+
+   ```bash
+   uv tool install git+https://github.com/seandavi/quartobot
+   ```
+
+2. **`quartobot-manuscript`** — a GitHub template that combines Quarto
+   Manuscripts, the CLI's pre-render hook, and a CI workflow that
+   gives every commit an immutable permalink at `/v/<sha>/`, embeds
+   that permalink in the rendered HTML, posts PR previews via sticky
+   comment, and deploys HTML + PDF + DOCX to GitHub Pages.
+
+   ```bash
+   gh repo create my-paper --template seandavi/quartobot-manuscript
+   ```
+
+Under the current (filter-based) architecture, a Quarto extension
+`quarto-manubot-cite` also ships at `quarto add seandavi/quartobot`.
+The pivot proposal in `docs/citation-pipeline.md` collapses that
+extension into a one-line pre-render hook calling the CLI — the
+extension shrinks to optional wiring, the CLI becomes the load-bearing
+surface. PyPI publishing and the standalone template repo are part of
+the v0.1 tag.
+
+## Why this exists
+
+[manubot/manubot#332](https://github.com/manubot/manubot/issues/332)
+("Quarto integration") was opened by Anthony Gitter in April 2022 after a
+conversation with Sean Davis. Four years later, no PR, no assignee — but
+`pandoc-manubot-cite` shipped inside the `manubot` package and Quarto
+Manuscripts shipped as a first-party project type. The integration is
+small once you stop trying to rebuild the resolver. This repo is the work
+to resolve that issue.
+
+## Working example
+
+[seandavi/2026-venice-spatial-hackathon-manuscript](https://github.com/seandavi/2026-venice-spatial-hackathon-manuscript)
+runs the CI / permalink / banner half of the pattern on a live 25-author
+preprint from the Bioconductor Spatial Hackathon. That's the working
+reference the template is being lifted from.
+
+## See also
+
+- Design — [`DESIGN.md`](DESIGN.md)
+- Prior art — [`docs/prior-art.md`](docs/prior-art.md)
+- Publication plan — [`docs/publication-plan.md`](docs/publication-plan.md)
+- Conversation notes — [`docs/conversation-notes.md`](docs/conversation-notes.md)
+- Contributing — [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Code of conduct — [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
+
+## License
+
+[MIT](LICENSE).

quartobot-0.1.0/README.md

@@ -0,0 +1,92 @@
+# quartobot
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-v0.1%20in%20flight-orange.svg)](DESIGN.md)
+
+The manubot manuscript-as-software pattern, on Quarto.
+
+> **Status:** v0.1 in flight. CLI commands ship; the Quarto extension
+> and the manuscript template ship. An architecture pivot is under
+> discussion in [`docs/citation-pipeline.md`](docs/citation-pipeline.md)
+> that would collapse the extension into a single pre-render hook
+> calling the CLI directly — read the design doc before non-trivial
+> work, and watch the [v0.1 milestone](https://github.com/seandavi/quartobot/milestone/1)
+> for tagging.
+
+## What this is
+
+Manubot has, for eight years, run scholarly manuscripts as a git repository
+that builds itself on every commit, resolves citations from DOIs and
+PubMed IDs automatically, hands out an immutable permalink per commit, and
+collaborates through pull requests. The pattern is published
+([Himmelstein et al. 2019](https://doi.org/10.1371/journal.pcbi.1007128))
+and has been used for hundreds of preprints.
+
+Quarto now covers more of scholarly publishing than manubot ever did —
+manuscripts, books, websites, slides, dashboards, courseware — but the
+manubot pattern does not yet exist there natively. That's the gap this
+repo closes.
+
+The shipping surface is a Python CLI and (optionally) a GitHub template:
+
+1. **`quartobot`** — a Python CLI. `quartobot resolve` pre-fetches
+   citations through manubot's resolver library, so CI never sees a
+   Crossref hiccup mid-render. `quartobot scan` summarizes cite keys
+   grouped by prefix with duplicate detection. `quartobot validate`
+   is the CI-lint surface (static checks against `_quarto.yml`).
+   `quartobot init` scaffolds the pattern into an existing Quarto
+   project. Authors write `@doi:10.1371/journal.pcbi.1007128`,
+   `@pmid:31479462`, `@arxiv:2104.10729`, `@isbn:…`, or bare DOIs in
+   their prose, and citations resolve.
+
+   ```bash
+   uv tool install git+https://github.com/seandavi/quartobot
+   ```
+
+2. **`quartobot-manuscript`** — a GitHub template that combines Quarto
+   Manuscripts, the CLI's pre-render hook, and a CI workflow that
+   gives every commit an immutable permalink at `/v/<sha>/`, embeds
+   that permalink in the rendered HTML, posts PR previews via sticky
+   comment, and deploys HTML + PDF + DOCX to GitHub Pages.
+
+   ```bash
+   gh repo create my-paper --template seandavi/quartobot-manuscript
+   ```
+
+Under the current (filter-based) architecture, a Quarto extension
+`quarto-manubot-cite` also ships at `quarto add seandavi/quartobot`.
+The pivot proposal in `docs/citation-pipeline.md` collapses that
+extension into a one-line pre-render hook calling the CLI — the
+extension shrinks to optional wiring, the CLI becomes the load-bearing
+surface. PyPI publishing and the standalone template repo are part of
+the v0.1 tag.
+
+## Why this exists
+
+[manubot/manubot#332](https://github.com/manubot/manubot/issues/332)
+("Quarto integration") was opened by Anthony Gitter in April 2022 after a
+conversation with Sean Davis. Four years later, no PR, no assignee — but
+`pandoc-manubot-cite` shipped inside the `manubot` package and Quarto
+Manuscripts shipped as a first-party project type. The integration is
+small once you stop trying to rebuild the resolver. This repo is the work
+to resolve that issue.
+
+## Working example
+
+[seandavi/2026-venice-spatial-hackathon-manuscript](https://github.com/seandavi/2026-venice-spatial-hackathon-manuscript)
+runs the CI / permalink / banner half of the pattern on a live 25-author
+preprint from the Bioconductor Spatial Hackathon. That's the working
+reference the template is being lifted from.
+
+## See also
+
+- Design — [`DESIGN.md`](DESIGN.md)
+- Prior art — [`docs/prior-art.md`](docs/prior-art.md)
+- Publication plan — [`docs/publication-plan.md`](docs/publication-plan.md)
+- Conversation notes — [`docs/conversation-notes.md`](docs/conversation-notes.md)
+- Contributing — [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Code of conduct — [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)
+
+## License
+
+[MIT](LICENSE).

quartobot-0.1.0/_extensions/seandavi/quarto-manubot-cite/README.md

@@ -0,0 +1,140 @@
+# quarto-manubot-cite
+
+A Quarto extension that wires `pandoc-manubot-cite` into any Quarto
+project, so authors can cite by persistent identifier
+(`@doi:10.1371/journal.pcbi.1007128`, `@pmid:31479462`, `@arxiv:2104.10729`,
+`@isbn:9780262035613`, bare DOIs, and the rest of manubot's vocabulary)
+and have entries auto-resolved into the bibliography on next build.
+
+This is a thin wrapper. The resolver itself is
+[manubot](https://github.com/manubot/manubot)'s — we don't reimplement it.
+
+## Prerequisites
+
+- Quarto ≥ 1.4
+- `pandoc-manubot-cite` on `PATH`. Install with:
+  ```bash
+  pip install manubot
+  ```
+  Manubot ships the filter as an entry point; once installed, the binary
+  is discoverable by pandoc.
+
+## Install
+
+```bash
+quarto add seandavi/quartobot
+```
+
+(While the extension lives in the parent `quartobot` repo, that's the
+install path. It will move to `seandavi/quarto-manubot-cite` after the
+first tagged release. See [#13](https://github.com/seandavi/quartobot/issues/13).)
+
+## Use
+
+Add the filter to your `_quarto.yml`:
+
+```yaml
+filters:
+  - quarto-manubot-cite
+
+# Where pandoc-manubot-cite writes the resolved CSL JSON.
+manubot-output-bibliography: references.json
+
+# Where the bibliography cache lives.
+manubot-bibliography-cache: _freeze/manubot-cache.json
+
+# Don't fail the render on a single unresolved citation — warn and continue.
+manubot-fail-on-errors: false
+
+# Both files are merged at render time. Hand-curated entries live in
+# references.bib; auto-resolved entries land in references.json.
+bibliography:
+  - references.bib
+  - references.json
+```
+
+Then cite in your `.qmd`:
+
+```markdown
+The manubot pattern is described in @doi:10.1371/journal.pcbi.1007128.
+A related approach using URL keys appears in @pmid:31479462.
+The Quarto book covers cross-format publishing [@quarto2024].
+```
+
+On render, `pandoc-manubot-cite` resolves each persistent-identifier key
+against the relevant API (Crossref, NCBI, arXiv, Wikidata, etc.), writes
+the resulting CSL JSON entries to `references.json`, and caches the
+metadata at `_freeze/manubot-cache.json` so subsequent renders don't
+re-fetch.
+
+## Citation key vocabulary
+
+The full table from manubot, for quick reference:
+
+| Prefix | Source | Example |
+|---|---|---|
+| `@doi:` | Crossref / DataCite | `@doi:10.1371/journal.pcbi.1007128` |
+| `@pmid:` | NCBI PubMed | `@pmid:31479462` |
+| `@pmcid:` | NCBI PubMed Central | `@pmcid:PMC6735409` |
+| `@arxiv:` | arXiv | `@arxiv:2104.10729` |
+| `@isbn:` | Books (multiple resolvers) | `@isbn:9780262035613` |
+| `@url:` | Web pages | `@url:https://manubot.org` |
+| `@wikidata:` | Wikidata | `@wikidata:Q56458094` |
+| `@zotero:` | Zotero web items | `@zotero:https://www.zotero.org/groups/.../items/ABCD1234` |
+| bare DOI | DOI prefix-inferred | `@10.1371/journal.pcbi.1007128` |
+
+See manubot's
+[`pandoc-manubot-cite` reference](https://manubot.github.io/manubot/reference/manubot/pandoc/cite_filter/)
+for the authoritative behavior, including normalization rules and prefix
+inference.
+
+## How the two bibliographies interact
+
+Declaring both `references.bib` (hand-curated) and `references.json`
+(auto-resolved) under `bibliography:` lets pandoc citeproc merge them.
+Hand-curated entries you author with stable BibTeX keys (`@quarto2024`,
+`@himmelstein2019`) sit alongside the auto-resolved DOI/PMID entries.
+
+Precedence and dedup semantics are tracked in
+[#10](https://github.com/seandavi/quartobot/issues/10) — the practical
+guidance is to use auto-resolved keys (`@doi:…`) by default and reach for
+hand-curated entries only when you need to override metadata the
+resolver got wrong.
+
+## Configuration reference
+
+These metadata keys are read by `pandoc-manubot-cite` from your document
+or `_quarto.yml`. Defaults shown are manubot's, not ours:
+
+- `manubot-output-bibliography` — path to write the resolved CSL JSON.
+- `manubot-bibliography-cache` — path to the persistent cache (read at
+  startup, written incrementally as citations resolve).
+- `manubot-fail-on-errors` — `false` by default. Set to `true` to make
+  unresolved citations fail the render.
+- `manubot-infer-citekey-prefixes` — `true` by default. Lets you write
+  bare `@10.1371/...` instead of `@doi:10.1371/...`.
+- `manubot-requests-cache-path` — path for the HTTP request cache
+  (separate from the bibliography cache).
+- `manubot-log-level` — `WARNING` by default.
+
+See [manubot's reference](https://manubot.github.io/manubot/reference/manubot/pandoc/cite_filter/)
+for the full list.
+
+## Failure mode
+
+By default, `pandoc-manubot-cite` warns on unresolved citations and exits
+0 — your render continues with the unresolved citation key intact in the
+output. That's deliberate: a Crossref or PubMed hiccup shouldn't fail
+your build. Set `manubot-fail-on-errors: true` in CI if you want the
+opposite.
+
+## See also
+
+- [manubot](https://github.com/manubot/manubot) — the upstream package.
+- [Himmelstein et al. 2019](https://doi.org/10.1371/journal.pcbi.1007128) —
+  the foundational manubot paper. Cite it if you use this extension.
+- The [quartobot DESIGN doc](../../../DESIGN.md) — pattern-level decisions.
+
+## License
+
+[MIT](../../../LICENSE).

quartobot-0.1.0/actions/render-manuscript/README.md

@@ -0,0 +1,47 @@
+# render-manuscript
+
+Composite action: renders a Quarto project to one or more formats.
+
+```yaml
+- uses: seandavi/quartobot/actions/render-manuscript@v0.1
+  with:
+    project: "."                # path to the Quarto project dir
+    formats: "html,pdf,docx"    # comma-separated
+    upload-logs: "true"         # render-*.log as artifact
+```
+
+## What it does
+
+1. Prints a diagnostics block (Quarto version, Pandoc version, TeX
+   engine version, project file listing).
+2. Runs `quarto render --to <fmt> --execute-debug` for each requested
+   format, capturing stdout to `render-<fmt>.log`.
+3. For PDF renders, emits a heartbeat line every 30 seconds so a stalled
+   TinyTeX run shows up in the workflow log instead of timing out
+   silently.
+4. Uploads the render logs as a workflow artifact (skippable).
+
+## Pair with setup-quartobot
+
+This action assumes Quarto, manubot, and the `quarto-manubot-cite`
+extension are already installed. Use [`setup-quartobot`](../setup-quartobot/)
+in the step before:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: seandavi/quartobot/actions/setup-quartobot@v0.1
+- uses: seandavi/quartobot/actions/render-manuscript@v0.1
+```
+
+## Formats
+
+Quarto supports a long list (`html`, `pdf`, `docx`, `epub`, `jats`,
+`revealjs`, `gfm`, plus several others). Whatever you pass here is
+handed to `quarto render --to`. Defaults to the manuscript triple:
+`html,pdf,docx`.
+
+## Exit behavior
+
+The action fails fast — any single format failing stops the loop and
+fails the action. Render logs upload regardless (`if: always()`) so
+post-mortem is straightforward.

quartobot-0.1.0/actions/setup-quartobot/README.md

@@ -0,0 +1,45 @@
+# setup-quartobot
+
+Composite action: installs everything needed to render a Quarto project
+using the manubot citation pattern.
+
+```yaml
+- uses: actions/checkout@v4
+- uses: seandavi/quartobot/actions/setup-quartobot@v0.1
+  with:
+    project: "."          # where _quarto.yml lives (default: .)
+    python-version: "3.12"
+    manubot-spec: "manubot>=0.6,<0.7"
+    quarto-version: ""    # empty = latest stable
+    tinytex: "true"       # set "false" to skip TeX install
+```
+
+## What it does
+
+1. `actions/setup-python@v5` with pip cache.
+2. `pip install '<manubot-spec>'` — installs `pandoc-manubot-cite` on `PATH`.
+3. `quarto-dev/quarto-actions/setup@v2` with TinyTeX by default.
+4. `quarto add <extension-source>` inside `<project>` — installs the
+   `quarto-manubot-cite` filter extension.
+
+## When to skip TinyTeX
+
+If you render HTML only and want a faster CI job, set `tinytex: "false"`.
+TinyTeX is required for PDF rendering and adds ~30 seconds to the job.
+
+## Pinning
+
+For reproducible CI, pin everything explicitly:
+
+```yaml
+with:
+  python-version: "3.12"
+  manubot-spec: "manubot==0.6.1"
+  quarto-version: "1.5.57"
+  extension-source: "seandavi/quartobot@v0.1"
+```
+
+## See also
+
+- [`render-manuscript`](../render-manuscript/) — the matching render step.
+- [Extension documentation](https://github.com/seandavi/quartobot/tree/main/_extensions/seandavi/quarto-manubot-cite).

quartobot-0.1.0/examples/book-minimal/README.md

@@ -0,0 +1,59 @@
+# book-minimal
+
+The smallest Quarto **book** project that exercises
+`quarto-manubot-cite`. Mirrors the shape of
+[`../extension-minimal/`](../extension-minimal/), but uses
+`project: type: book` to demonstrate that the manubot pattern isn't
+limited to manuscripts.
+
+## Run it
+
+```bash
+cd examples/book-minimal/
+
+# Once: install the extension and the resolver.
+quarto add seandavi/quartobot
+pip install 'manubot>=0.6,<0.7'
+
+# Each render:
+quarto render
+open _book/index.html
+```
+
+## What you should see
+
+- `_book/` directory with `index.html` (preface) and chapter pages
+  (`chapters/intro.html`, `chapters/methods.html`,
+  `chapters/discussion.html`), plus the standard Quarto book site
+  assets (search index, sidebar, theme bundles).
+- Each chapter's HTML carries its own bibliography section at the
+  bottom listing only the cites that chapter references — Quarto
+  book's idiomatic layout.
+- `_freeze/manubot-cache.json` is populated incrementally as each
+  chapter renders. On a clean second render, every cite is a cache
+  hit and no network round-trip is needed.
+
+## Per-chapter vs aggregated bibliography
+
+Quarto book HTML output puts each chapter's references at the bottom of
+that chapter. If you want a single aggregated references page,
+that's currently a Quarto feature gap for book HTML — separate from
+this extension. Track in
+[seandavi/quartobot#34](https://github.com/seandavi/quartobot/issues/34).
+
+## Why this isn't the template
+
+The template (`../../template-book/` once that ships) adds: a version
+banner, per-commit permalinks via CI, PR previews, gh-pages deploy.
+All of that is the *pattern*. The example here is just the
+*extension* on a book project type.
+
+If you want the pattern, use the template. If you want to add manubot-
+style citations to an existing Quarto book, this is the shape.
+
+## See also
+
+- [Manuscript-shape minimal example](../extension-minimal/)
+- [Extension reference](../../_extensions/seandavi/quarto-manubot-cite/README.md)
+- The book template (in progress, tracked at
+  [#36](https://github.com/seandavi/quartobot/issues/36))

quartobot-0.1.0/examples/extension-minimal/README.md

@@ -0,0 +1,48 @@
+# extension-minimal
+
+The smallest Quarto project that exercises `quarto-manubot-cite`. Use
+this if you want to try the extension on its own without adopting the
+full `quartobot-manuscript` template.
+
+## Run it
+
+```bash
+cd examples/extension-minimal/
+
+# Once: install the extension and the resolver.
+quarto add seandavi/quartobot
+pip install 'manubot>=0.6,<0.7'
+
+# Each render:
+quarto render index.qmd
+open index.html
+```
+
+## What you should see
+
+- `references.json` written at the project root with one CSL JSON entry
+  for the resolved DOI (`10.1371/journal.pcbi.1007128`).
+- `_freeze/manubot-cache.json` written with the cached resolver response.
+- The rendered HTML shows both `@doi:…` and `@quarto2024` citations
+  rendered correctly in a numbered bibliography.
+
+The second render should be ~instant — the cache covers the one resolver
+lookup. `@quarto2024` is read directly from `references.bib` and never
+needed a network round-trip.
+
+## Generated artifacts
+
+The render produces `index.html`, `references.json`, `_extensions/` (when
+you ran `quarto add`), and `_freeze/`. These are all gitignored
+(`examples/extension-minimal/.gitignore`) so this directory stays clean
+inside the repo.
+
+## Why this isn't the template
+
+The template (`../../template/`) adds: a version banner, per-commit
+permalinks via CI, PR previews, multi-format render (HTML + PDF + DOCX),
+gh-pages deploy. All of that is the *pattern*. The example here is just
+the *extension*.
+
+If you want the pattern, use the template. If you want to add manubot-
+style citations to an existing Quarto project, this is the shape.