tree-annotated-plot 0.0.1__tar.gz

tree_annotated_plot-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+# Run lint, format-check, and tests on every push to main and on every PR.
+#
+# Local equivalent: `scripts/check.sh` (which expects a local .venv;
+# this workflow uses the runner's python directly so it doesn't depend
+# on that layout).
+
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Cancel in-flight runs on the same ref when a new commit lands; PRs
+# rebased many times in quick succession don't queue up wasted minutes.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Fetch upstream Kikawa Auspice JSONs
+        # Real-data tests in tests/test_real_data.py and tests/test_cli.py
+        # skip cleanly when these files are absent. We want them to
+        # actually run in CI, so fetch the upstream JSONs first.
+        run: python examples/fetch_auspice_data.py
+
+      - name: Build Kikawa titer chart specs
+        # tests/test_real_data.py also reads the saved Vega-Lite specs
+        # produced by this script. Ditto for tests/test_cli.py end-to-end.
+        run: python examples/flu-seqneut-2025to2026_titer_charts.py
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Format check (black)
+        run: black --check .
+
+      - name: Tests (pytest)
+        run: pytest tests/

tree_annotated_plot-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+# Build the docs on every push to `main` (then deploy to GitHub Pages)
+# and on every pull request targeting `main` (build only, no deploy).
+# The PR build catches broken mkdocstrings refs, missing images, and
+# unresolved cross-links *before* they land on `main` and break the
+# next deploy.
+#
+# Local equivalent: `scripts/build_docs.sh` (mkdocs build --strict).
+# This workflow file is dormant until the repo is published with Pages
+# enabled — keep it under version control so the deployment pipeline is
+# reproducible from a clean checkout.
+
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install package + docs extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+      - name: Generate chart assets
+        # Renders docs/images/*.png and docs/charts/*.html from the
+        # example modules. Both directories are gitignored — the docs
+        # site references them, so they must exist before mkdocs runs.
+        run: python scripts/generate_docs_assets.py
+      - name: Build site
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: ./site
+
+  deploy:
+    # Only deploy on push-to-main. PRs (especially from forks) lack
+    # `pages: write` permissions and would publish PR-only content to
+    # the live site if they did. The build job above still runs on PRs
+    # — that's where docs regressions get caught pre-merge.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

tree_annotated_plot-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+# Build wheel + sdist and publish to PyPI when a `v*` tag is pushed.
+#
+# Uses PyPI trusted publishing (OIDC) — no API token / password is
+# stored in the repo. The trusted-publisher relationship must be
+# configured once on PyPI: project Settings → Publishing → Add trusted
+# publisher, pointing at this repo's owner + name + the workflow
+# filename `release.yml` + environment name `pypi` below. With that
+# config, GitHub mints a short-lived OIDC token at workflow runtime
+# and PyPI exchanges it for an upload token.
+#
+# Maintainer recipe (full version):
+#   1. Bump the `version` field in pyproject.toml on `main`.
+#   2. Commit, then tag: `git tag v0.1.0`.
+#   3. Push: `git push && git push --tags`.
+# The build job verifies the tag matches `pyproject.toml`'s version, so
+# a mismatched tag fails fast before anything reaches PyPI.
+
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Verify tag matches pyproject.toml version
+        # `python -m build` doesn't check this; without the gate, a
+        # mistyped tag would happily publish a release whose
+        # __version__ disagrees with the tag name.
+        run: |
+          tag="${GITHUB_REF#refs/tags/}"
+          version="v$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag '$tag' does not match pyproject.toml version '$version'"
+            exit 1
+          fi
+          echo "tag and version match: $tag"
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    # The `pypi` environment lets you optionally require manual approval
+    # in repo Settings → Environments → pypi → "Required reviewers"
+    # before any release lands on PyPI. PyPI's trusted-publisher config
+    # also pins this environment name.
+    environment: pypi
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      # Required by PyPI trusted publishing — GitHub mints an OIDC
+      # token that PyPI exchanges for an upload token.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

tree_annotated_plot-0.0.1/.gitignore

@@ -0,0 +1,10 @@
+.*
+!.git*
+/_*
+*.out
+examples/data/
+site/
+docs/images/
+docs/charts/
+__pycache__/
+*.pyc

tree_annotated_plot-0.0.1/CLAUDE.md

@@ -0,0 +1,116 @@
+# `tree-annotated-plot` – Claude Code Notes
+
+- **Keep CLAUDE.md, README.md, and the docs site updated** when changing the
+  code. `CLAUDE.md` describes programming conventions; `README.md` describes
+  basic use; `docs/` is the user-facing reference. Don't let them drift.
+- **Single source of truth — `pyproject.toml`**: canonical for dependencies,
+  supported Python version, build config, tool settings. Don't restate any of
+  these in prose; refer to `pyproject.toml`.
+- **Single source of truth — `PlotConfig` and `_config.py`**: every plot-parameter
+  description lives in `_config.py`. For styling/behavior knobs, the source is
+  the field's `Annotated[T, "<description>"]` metadata on `PlotConfig`; the
+  click `--help` text reads it directly, and `tree_annotated_plot.plot.__doc__`
+  is assembled at import time by `_config._render_numpy_params`, so the
+  REPL / mkdocstrings rendering pulls from the same string. Add Python-only
+  prose for a field by setting `_config.PARAM_DOC_EXTRAS[field_name] = "..."`.
+  Adding a parameter = a new `PlotConfig` field + a kwarg in
+  `tree_annotated_plot.plot`'s signature with the same default. The three
+  data-input parameters (`tree`, `chart`, `output`) can't sit on `PlotConfig`
+  because their *types* differ between surfaces (the Python API accepts live
+  `altair.Chart` / `dict` / `TreeNode`; the CLI only accepts file paths), but
+  their descriptions are still single-sourced as
+  `_config.{TREE,CHART,OUTPUT}_DESCRIPTION` constants — both the CLI's
+  `--help` and `_plot.py`'s `_PLOT_DOC_HEADER` interpolate them.
+- **Docstring style**: NumPy (Parameters / Returns sections with the
+  `----------` underline), matching `mkdocs.yml`'s
+  `docstring_style: numpy`. Don't mix Google-style `Args:` blocks in;
+  mkdocstrings won't render them consistently.
+- **Fail fast**: validate inputs early and raise clear `ValueError` on
+  unexpected data. Prefer assertions and explicit error messages over silent
+  fallbacks. Tip-set reconciliation errors should include sample values from
+  both sides plus candidate-field hints when possible.
+- **Pure-Python package**: managed via `pyproject.toml` and a plain `venv`
+  (not conda). Required Python version specified in `pyproject.toml`. Develop
+  with:
+  ```bash
+  python3 -m venv .venv
+  source .venv/bin/activate
+  pip install -e ".[dev,docs]"
+  ```
+  The `src/` layout requires `dev-mode-dirs = ["src"]` under
+  `[tool.hatch.build.targets.wheel]` for editable installs to work.
+- **Use default `black` / `ruff` line length.** Do not add `line-length`
+  overrides to `pyproject.toml` unless explicitly requested.
+- **API shape**: the user supplies their plot as a Vega-Lite chart (an
+  `altair.Chart`-or-subclass object, a JSON path, an HTML path, or a parsed
+  spec dict). The package introspects the chart to find the strain encoding
+  on `x` or `y`, overrides its sort to match the tree's tip order, and
+  hconcat's or vconcat's a tree panel on the matching side. Tree dictates
+  tip ordering; plot follows.
+- **Two surfaces, one config**: `tree_annotated_plot.plot()` and the `tree-annotated-plot`
+  CLI both accept the same parameters via `PlotConfig`. They converge on
+  `_build(tree, chart, config)` so they can never disagree.
+- **Tests must remain green at every commit on `main`.** Single-developer
+  workflow with no PRs (yet) — discipline replaces review. Lint + format +
+  pytest before committing:
+  ```bash
+  scripts/check.sh
+  ```
+  The same three checks run in CI via
+  [`.github/workflows/ci.yml`](.github/workflows/ci.yml) on push to
+  `main` and on PRs (CI also fetches the upstream Kikawa Auspice JSONs
+  so real-data tests run rather than skip). Local green ≈ CI green.
+- **Build docs alongside checks** when changing public API surface:
+  ```bash
+  scripts/build_docs.sh
+  ```
+  `--strict` mode catches broken mkdocstrings references and missing
+  cross-links. The script first calls
+  `scripts/generate_docs_assets.py` to render `docs/images/*.svg`
+  and `docs/charts/*.html` from the example modules; both
+  directories are **gitignored** — never commit anything into them.
+  The same asset script runs in CI before `mkdocs build`.
+- **Eyeball examples after any rendering change.** There are no
+  image-snapshot regression tests (vl-convert/font/platform variance
+  makes them flaky), so visual regressions only get caught by
+  looking. After any change to `_plot.py`, `_tree.py`, the example
+  scripts, or anything they touch: run `scripts/build_docs.sh`, open
+  `site/examples.html`, and click through each example — both the
+  embedded SVG and the interactive HTML link. Confirm tip-row
+  alignment, tree orientation, scale bar (if applicable),
+  tooltips, and any selection/cohort bindings still work. The full
+  recipe is in `README.md` under "Visual verification after code
+  changes". When telling the user a rendering-affecting task is
+  done, also report whether you ran this check (and that you
+  cannot, from a non-interactive shell, actually verify the rendered
+  output yourself — they need to look).
+- **Docs are auto-deployed**. The
+  [`.github/workflows/docs.yml`](.github/workflows/docs.yml)
+  workflow runs on every push to `main`, generates assets, builds
+  with `mkdocs build --strict`, and deploys to GitHub Pages
+  (https://jbloomlab.github.io/tree-annotated-plot/). Pages source
+  must be set to "GitHub Actions" in repo Settings; the workflow's
+  `permissions:` block already declares `pages: write` and
+  `id-token: write` so no further config is needed.
+- **Releases are tag-driven**. Push a `vX.Y.Z` tag (after bumping
+  `pyproject.toml`'s `version`) and
+  [`.github/workflows/release.yml`](.github/workflows/release.yml)
+  builds wheel + sdist and publishes to PyPI via trusted publishing
+  (OIDC — no token in the repo). The build job verifies the tag and
+  `pyproject.toml` version match before publishing. Per-release recipe
+  and one-time PyPI configuration steps are in `README.md` under
+  "Releasing a new version".
+- **Adding a new example** (full recipe in `README.md`):
+  1. Self-contained module under `examples/` with module-level
+     helpers (callable from outside).
+  2. New clause in `scripts/generate_docs_assets.py` that produces a
+     `.svg` (into `docs/images/`) + `.html` (into `docs/charts/`).
+  3. New section in `docs/examples.md` matching the existing
+     three-section template (motivation → embedded SVG +
+     interactive link → reproduce: CLI first, Python second).
+  4. `scripts/build_docs.sh` confirms the page renders.
+- **Iterating on docs**: prefer `mkdocs serve` (live-reload local
+  server) for content/layout changes — much faster than
+  `build_docs.sh` and shows the actual rendered page in your
+  browser. Use `build_docs.sh` for the strict pre-commit
+  verification.

tree_annotated_plot-0.0.1/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+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.

tree_annotated_plot-0.0.1/NEXT_STEPS.md

@@ -0,0 +1,94 @@
+# Next steps
+
+Phase 2 is complete. This file is the to-do list for resuming —
+either by Jesse picking up later or by a future Claude session.
+Lifecycle: shrink as items get done; delete the file when only
+hypothetical Phase 3 work is left.
+
+## Immediate actions (not yet done)
+
+1. **Push to GitHub.** Local commits haven't been pushed yet.
+   ```bash
+   git push -u origin main
+   ```
+2. **Enable Pages.** GitHub repo → Settings → Pages → Source:
+   "GitHub Actions". This activates the dormant
+   `.github/workflows/docs.yml` so the next push to `main` builds
+   and deploys the docs site to
+   https://jbloomlab.github.io/tree-annotated-plot/.
+3. **Verify the deployed site.** Click through Home / Python API /
+   Command line / Examples. On the Examples page, each "Open the
+   interactive chart →" link should open a working interactive
+   Altair chart with tooltips and selection bindings. If any link
+   404s or any image is missing, the `Generate chart assets` step
+   in the workflow probably failed — check the Actions tab.
+4. **Bump the version + cut a tag** when you're ready for v0.1.0.
+   `pyproject.toml`'s `version = "0.0.1"` is an alpha placeholder.
+   ```bash
+   # edit pyproject.toml: version = "0.1.0"
+   git commit -am "release v0.1.0" && git tag v0.1.0
+   git push && git push --tags
+   ```
+5. **Add a GitHub action to run the tests**: this should include running any tests, examples, linting, and code formatting
+6. **Add installation instructions to the docs and README**: assume it can be installed from PyPI but have documentation also link to GitHub source
+
+## Phase 3 candidate features (deferred from Phase 2)
+
+The Phase 2 plan's "Out of scope" section listed these explicitly
+and the user signed off on deferring them. Pick from this list when
+adding the next round of features:
+
+- **Clade coloring / tree decoration.** API shape undecided. Two
+  options on the table:
+  - Declarative: `clades=[{"node_attr": "subclade", "values_to_colors": {...}}]` and the package paints branches.
+  - Lower-level: expose `tree_chart()` returning the tree panel as
+    an editable `alt.Chart` so users layer their own decoration.
+- **Image-snapshot regression tests.** Render via
+  `vl-convert-python` (already a dep) to PNG and compare with a
+  structural diff or perceptual-similarity metric. Tool choice
+  undecided (`pytest-mpl` is matplotlib-only; would need to find or
+  build something for Vega-Lite output).
+- **Newick / Nexus tree input.** Auspice JSON v2 is the only tree
+  format today.
+- **Static (matplotlib) backend.** Only altair-via-Vega-Lite today.
+- **HTML chart-spec extraction beyond the default altair template.**
+  Today we parse `var spec = {...}` out of altair's standard
+  `to_html()` output via stdlib `html.parser` +
+  `json.JSONDecoder.raw_decode()`. Custom `chart.save(template=...)`
+  outputs would need a real JS-AST parser (e.g. `esprima`).
+- **Per-clade collapsing of subtrees** (different from the
+  topology-pruning we already do for `prune_tree_to_chart`).
+- **Vega-Lite v5 → v6 auto-upgrade** of stale specs. We currently
+  detect-and-report; we don't translate.
+
+## Smaller polish items
+
+- **Add `CHANGELOG.md`.** None today; `git log --oneline` is the
+  de-facto record. Worth one if multiple releases pile up.
+- **Add a PyPI publish workflow.**
+  `.github/workflows/release.yml` triggered on tag, building wheel +
+  sdist, uploading via trusted publishing. None today; would
+  complement the existing docs-deploy workflow.
+- **Compress the H1N1 docs PNG** (currently ~1 MB). Options:
+  - Pass `optimize=True` to the PIL save (might need post-processing
+    after `chart.save()`).
+  - Lower PPI in `scripts/generate_docs_assets.py` from 96 to 72.
+  - Crop or resize after rendering.
+- **Investigate the "Automatically deduplicated selection parameter"
+  altair warning** that appears when the Kikawa chart-builder runs.
+  Pre-existing and cosmetic, but it'd be cleaner to silence
+  (probably needs explicit `name=` on the selection params).
+- **Add badges to README** Add badges for GitHub Actions test and PyPI version to the README.
+  Is there also a badge I can add for the docs, or other badges to consider?
+
+## State at session close
+
+- 21 commits on `main`, none pushed.
+- All 102 tests pass via `scripts/check.sh`.
+- `scripts/build_docs.sh` produces a viewable `site/` from a clean
+  checkout.
+- `plan.md` is gone (disassembled per its own Lifecycle section in
+  commit `b9beb66`).
+- `docs_plan.md` is gone (transient design note for the docs
+  deployment + asset strategy; written, reviewed, and removed in
+  commit `f1f551d`).

tree_annotated_plot-0.0.1/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: tree-annotated-plot
+Version: 0.0.1
+Summary: Annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree.
+Project-URL: Documentation, https://jbloomlab.github.io/tree-annotated-plot/
+Project-URL: Homepage, https://github.com/jbloomlab/tree-annotated-plot
+Project-URL: Repository, https://github.com/jbloomlab/tree-annotated-plot
+Project-URL: Issues, https://github.com/jbloomlab/tree-annotated-plot/issues
+Author-email: Jesse Bloom <jbloom@fredhutch.org>
+License: MIT License
+        
+        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.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.13
+Requires-Dist: altair<7,>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: vl-convert-python>=1.9
+Provides-Extra: dev
+Requires-Dist: black>=24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-click>=0.8; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# `tree-annotated-plot`: annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+This is a Python package from the [Bloom lab](https://jbloomlab.org/) that allows you to combine an Altair / Vega-Lite plot with a Nextstrain JSON of a phylogenetic tree so that the tree is aligned to annotate strains on the axis of the plot.
+See [https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.io/tree-annotated-plot/) for detailed documentation.
+
+> **Note:** charts must be saved from altair 6+ (Vega-Lite v6). Older specs raise by default; pass `--no-strict-version` (CLI) or `strict_version=False` (Python) to override at your own risk. See the [docs](https://jbloomlab.github.io/tree-annotated-plot/) for details.
+
+## Notes for developing the package
+
+### Installation (development)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,docs]"
+```
+
+[pyproject.toml](pyproject.toml) is the canonical source for the supported Python
+version and runtime dependencies.
+
+### Visual verification after code changes
+
+This package has automated tests for chart **structure** (encodings,
+sort order, tip reconciliation, scale-bar arithmetic, etc.), but
+**not** for chart **appearance** — there are no image-snapshot
+regression tests, because rendering is sensitive to fonts,
+`vl-convert-python` versions, and platform differences in ways that
+make pixel-level comparison flaky in practice.
+
+So the discipline is manual: any time you change code that affects
+rendering (`src/tree_annotated_plot/_plot.py`,
+`src/tree_annotated_plot/_tree.py`, the example scripts under
+`examples/`, or anything they touch), run the full check below and
+**eyeball every example** before considering the change done.
+
+```bash
+bash scripts/check.sh        # lint + format + pytest (all 100+ tests)
+bash scripts/build_docs.sh   # regenerates docs/images + docs/charts and runs mkdocs --strict
+```
+
+Then open `site/examples.html` in a browser and, for each example:
+
+1. Look at the embedded SVG screenshot. Does it match what the
+   feature you changed should produce? Are tip rows still aligned with
+   the chart rows? Is the tree's tip-end facing the chart? Is the
+   scale bar (if enabled) centered and labeled correctly?
+2. Click "Open the interactive chart →". Hover tips to confirm
+   tooltips fire; if there's a cohort selector (Kikawa examples),
+   toggle it; pan/zoom if relevant.
+3. Compare against the
+   [deployed site](https://jbloomlab.github.io/tree-annotated-plot/)
+   (which still reflects `main` before your change) for what "good"
+   looks like.
+
+If something visibly regresses, fix it before pushing — there's no
+CI gate that will catch a visual regression for you.
+
+### Continuous integration
+
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on every
+push to `main` and every pull request: it installs the package, fetches
+the upstream Kikawa Auspice JSONs (so the real-data tests actually
+exercise rather than skip), builds the Kikawa titer chart specs, and
+runs `ruff check`, `black --check`, and `pytest tests/`. This mirrors
+[`scripts/check.sh`](scripts/check.sh) — green locally should mean
+green in CI.
+
+A separate workflow,
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml), builds the
+docs site on every push to `main` and every PR (catching broken
+mkdocstrings refs / missing images / unresolved cross-links before
+merge), and additionally deploys `site/` to GitHub Pages on push to
+`main`.
+
+A third workflow,
+[`.github/workflows/release.yml`](.github/workflows/release.yml),
+builds the sdist + wheel and publishes them to PyPI when a `v*` tag
+is pushed (see "Releasing a new version" below).
+
+### Releasing a new version
+
+Releases are fully automated by tag push. Trusted publishing (OIDC)
+means **no API token or password is stored in the repo** — PyPI
+authenticates the workflow via its repo + workflow filename +
+environment.
+
+One-time setup (only needed before the first release):
+
+1. Reserve `tree-annotated-plot` on [PyPI](https://pypi.org/) (first
+   successful publish creates it; or claim it manually via
+   `pip install build && python -m build && twine upload dist/*` from a
+   maintainer machine).
+2. On PyPI, go to the project → "Publishing" tab → "Add a new pending
+   publisher". Fill in: owner `jbloomlab`, repository
+   `tree-annotated-plot`, workflow filename `release.yml`, environment
+   `pypi`.
+3. (Optional but recommended) On GitHub, repo Settings → Environments
+   → New environment → name `pypi`. Add yourself as a required
+   reviewer if you want a manual approval gate before each release
+   lands on PyPI.
+
+Per-release recipe (every time):
+
+```bash
+# 1. Edit pyproject.toml and bump `version = "X.Y.Z"`.
+# 2. Commit and tag (the workflow verifies they match before publishing).
+git commit -am "release vX.Y.Z"
+git tag vX.Y.Z
+git push && git push --tags
+```
+
+The `release` workflow then builds, verifies tag ⇋ version match, and
+publishes to PyPI.
+
+### Documentation
+The docs are at
+[https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.io/tree-annotated-plot/).
+They are auto-deployed by GitHub Actions on every push to `main` —
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml) installs
+the package + docs extras, runs
+[`scripts/generate_docs_assets.py`](scripts/generate_docs_assets.py)
+to render images and standalone interactive HTML for each
+example, then `mkdocs build --strict`, and uploads `site/` as a
+GitHub Pages artifact.
+
+### Building documentation locally
+
+For day-to-day editing of the docs, use MkDocs's live-reload server
+(saves go straight to your browser):
+
+```bash
+mkdocs serve              # http://localhost:8000
+```
+
+To do this on the Fred Hutch remote server, do:
+```bash
+mkdocs serve -a $(hostname -i | awk '{print $1}'):$(fhfreeport)
+```
+
+For the strict build that matches CI (catches broken
+[`mkdocstrings`](https://mkdocstrings.github.io/) refs, missing
+images, unresolved cross-links):
+
+```bash
+bash scripts/build_docs.sh
+```
+
+This first runs `scripts/generate_docs_assets.py` (so the example
+SVGs and interactive HTMLs exist before MkDocs reads `docs/`), then
+`mkdocs build --strict`. Output lands in `site/`.
+
+### Adding a new example
+
+The docs follow a single template per example: a short motivation,
+an embedded SVG screenshot, a link to the fully-interactive
+standalone HTML, and the commands to reproduce (CLI form first,
+Python API form second). [`docs/examples.md`](docs/examples.md)
+shows the existing shape. To add another:
+
+1. Drop a runnable script into `examples/`. Keep helpers at module
+   level (callable from outside) so the asset script can import them.
+2. Add a clause to `scripts/generate_docs_assets.py` that imports
+   the script and calls `tree_annotated_plot.plot(...)` followed by saving both
+   `<name>.svg` (into `docs/images/`) and `<name>.html` (into
+   `docs/charts/`). Both directories are gitignored — only the
+   asset script writes there.
+3. Add a section to `docs/examples.md` matching the template.
+4. Run `bash scripts/build_docs.sh` and open `site/examples.html`
+   to verify. Push when happy; the deployed site updates on the
+   next CI run.