ghinsight 0.2.0__tar.gz

ghinsight-0.2.0/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

ghinsight-0.2.0/.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns: ["*"]

ghinsight-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,149 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Run tests
+        run: uv run pytest
+      - name: Build package
+        run: uv build
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install docs dependencies
+        run: uv sync --group docs
+      - name: Build docs
+        run: uv run --group docs sphinx-build -b html -W docs docs/_build/html
+
+  online-smoke:
+    # End-to-end test against *real* GitHub Actions data, using the built-in
+    # GITHUB_TOKEN to read this repository's own runs/jobs. This exercises the
+    # network fetch path that cannot run in an offline dev sandbox.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    env:
+      ORG: ${{ github.repository_owner }}
+      REPO: ${{ github.event.repository.name }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Fetch real Actions data (single repo) and build report
+        run: |
+          uv run ghinsight actions fetch \
+            --org "$ORG" --repo "$REPO" --period last-year --cache-dir cache
+          uv run ghinsight actions report \
+            --org "$ORG" --cache-dir cache --output-dir reports
+          uv run ghinsight actions dashboard \
+            --org "$ORG" --cache-dir cache \
+            --output docs/index.html --summary docs/summary.json
+      - name: Assert the pipeline produced non-empty results
+        run: |
+          uv run python - <<'PY'
+          import json
+          from pathlib import Path
+
+          from ghinsight.actions.dataset import ActionsDataset
+
+          org = __import__("os").environ["ORG"]
+          dataset = ActionsDataset.from_cache(org, Path("cache"))
+          assert not dataset.is_empty, "no completed jobs were fetched"
+          print(f"OK: {len(dataset.jobs)} jobs, {len(dataset.runs)} runs")
+
+          for csv in ["repositories.csv", "workflows.csv"]:
+              path = Path("reports/actions-usage-metrics") / csv
+              assert path.exists() and path.stat().st_size > 0, f"missing/empty {path}"
+
+          summary = json.loads(Path("docs/summary.json").read_text())
+          assert summary["raw_total_minutes_period"] > 0, "zero raw minutes"
+          print("summary:", summary["raw_total_minutes_period"], "raw minutes")
+          PY
+      - name: Upload generated dashboard
+        uses: actions/upload-artifact@v7
+        with:
+          name: dashboard
+          path: |
+            docs/index.html
+            docs/summary.json
+            reports/
+
+  online-full-account:
+    # Full-account end-to-end test across *all* repos of an account. The built-in
+    # GITHUB_TOKEN is scoped to a single repo, so this needs a Personal Access
+    # Token with read access to the target account (classic: repo + read:org;
+    # fine-grained: Actions read across repos). Configure repository secrets
+    # GH_PAT and (optionally) GH_ACCOUNT to enable it; the job skips cleanly when
+    # GH_PAT is absent, so forks and unconfigured repos stay green.
+    # Its output is deliberately not uploaded: this repository is public, so an
+    # artifact would expose the account's private repository names and usage.
+    runs-on: ubuntu-latest
+    env:
+      GH_PAT: ${{ secrets.GH_PAT }}
+      GH_ACCOUNT: ${{ secrets.GH_ACCOUNT || github.repository_owner }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Fetch the whole account and build the report
+        run: |
+          if [ -z "$GH_PAT" ]; then
+            echo "GH_PAT secret not set — skipping full-account test."
+            exit 0
+          fi
+          export GITHUB_TOKEN="$GH_PAT"
+          uv run ghinsight actions fetch \
+            --org "$GH_ACCOUNT" --period last-3-months --cache-dir cache
+          uv run ghinsight actions report \
+            --org "$GH_ACCOUNT" --cache-dir cache --output-dir reports
+          uv run ghinsight actions dashboard \
+            --org "$GH_ACCOUNT" --cache-dir cache \
+            --output docs/index.html --summary docs/summary.json
+          uv run python - <<'PY'
+          import os
+          from pathlib import Path
+
+          from ghinsight.actions.dataset import ActionsDataset
+
+          dataset = ActionsDataset.from_cache(os.environ["GH_ACCOUNT"], Path("cache"))
+          repos = {job.repo for job in dataset.jobs}
+          print(f"OK: {len(dataset.jobs)} jobs across {len(repos)} repos")
+          assert not dataset.is_empty, "no jobs fetched across the account"
+          PY

ghinsight-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ghinsight-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pixi/
+.env
+.ruff_cache/
+.pytest_cache/
+docs/_build/
+cache/
+reports/

ghinsight-0.2.0/AGENTS.md

@@ -0,0 +1,47 @@
+# Repository notes for future agents
+
+- Use `uv` for PyPI packaging and release checks in this repository.
+- The repository also defines a `pixi` environment in `pyproject.toml`; keep
+  package runtime dependencies mirrored in `[project.dependencies]` and
+  `[tool.pixi.dependencies]` so uv resolves from PyPI while pixi resolves from
+  conda-forge.
+- Prefer commands of the form:
+
+```bash
+uv run python ...
+uv run ghinsight ...
+pixi run check
+```
+
+- Do not run bare `python` for project tasks unless the user explicitly asks for
+  it.
+- Keep this package organization-agnostic. Organization names, private data
+  paths, billing assumptions, and one-off repository quirks should live in a
+  consuming repository's config, not in this library.
+
+## Architecture (post-refactor)
+
+- Layout: the core (`client.py`, `repos.py`, `activity.py`, `cli.py`) needs
+  only httpx2 and typer. `ghinsight.actions` (the Actions pipeline and its
+  dashboard) needs the `actions` extra (pandas, plotly, rich); nothing in the
+  core may import it at module level. Keep `[project.dependencies]`, the
+  `actions` extra and `[tool.pixi.dependencies]` in step.
+- All GitHub API access goes through `client.py` (httpx2; `GitHubClient`,
+  `GitHubError`, `resolve_token`) and `repos.py` (`RepoInfo`, account repo
+  listing). Keep these two modules light and stable: other packages (e.g.
+  repo-secret-scan) depend on them, so they must not import pandas/plotly.
+- `ghinsight.actions` has three functional stages: `fetch` (network) → `dataset` (the canonical tidy
+  IR, `ActionsDataset`) → analysis (`metrics`, `analysis`, `charts`, `report`).
+- The intermediate representation is a tidy per-job table, not GitHub's
+  aggregate CSVs. CSVs are an export (`csv_export`) for `compare` only.
+- Prefer the functional style already in place: frozen dataclasses, pure
+  functions, type hints on signatures, declarative specs over imperative loops.
+- Derived measures (billed minutes, durations, OS) are defined once, as
+  properties on the `Job`/`Run` records in `domain.py`.
+
+## Testing & docs
+
+- `uv run pytest` runs the offline suite against `tests/synthetic.py` (no token
+  or network needed). Add fixtures there rather than depending on a live org.
+- `uv run --group docs sphinx-build -b html -W docs docs/_build/html` builds the
+  docs (AutoAPI + MyST-NB tutorials); CI builds with `-W`, so keep it warning-free.

ghinsight-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kolen Cheung
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ghinsight-0.2.0/MAINTAINER.md

@@ -0,0 +1,88 @@
+# Maintainer Guide
+
+This package is intended to be published to PyPI as `ghinsight`.
+
+## Local Release Checks
+
+Use `uv` from the repository root:
+
+```bash
+uv sync
+uv build
+uv run twine check dist/*
+```
+
+Also check the pixi environment after dependency changes:
+
+```bash
+pixi lock
+pixi run check
+pixi run help
+```
+
+Inspect the contents before uploading:
+
+```bash
+tar -tzf dist/ghinsight-*.tar.gz | sort | head -50
+unzip -l dist/ghinsight-*.whl | sort | head -50
+```
+
+## First PyPI Release
+
+1. Confirm the package name in `pyproject.toml` is available on PyPI. If
+   `ghinsight` is already taken, rename the project before the first
+   release.
+2. Confirm `README.md`, `LICENSE`, project URLs, dependencies, and the console
+   script metadata are correct.
+3. Create a PyPI account if needed and enable 2FA.
+4. Configure a PyPI Trusted Publisher for GitHub Actions.
+   - Project name: `ghinsight`
+   - Owner: the GitHub repository owner
+   - Repository: the GitHub repository name
+   - Workflow filename: `release.yml`
+   - Environment: `pypi`
+5. Push the repository to GitHub.
+6. Create a GitHub Release for the version in `pyproject.toml`.
+7. The `release.yml` workflow will build the sdist/wheel with `uv build` and
+   publish with `pypa/gh-action-pypi-publish`.
+
+Trusted Publishing avoids storing a long-lived PyPI token in GitHub secrets.
+The workflow needs `permissions: id-token: write`, and the `pypi` environment
+should match the environment configured on PyPI.
+
+## Ongoing Releases
+
+1. Update `version` in `pyproject.toml`.
+2. Update the README or changelog if user-facing behavior changed.
+3. If runtime dependencies changed, update both `[project.dependencies]` and
+   `[tool.pixi.dependencies]` in `pyproject.toml`, then regenerate `uv.lock`
+   and `pixi.lock`.
+4. Run local checks:
+
+```bash
+uv sync
+
+uv build
+uv run twine check dist/*
+pixi lock
+pixi run check
+```
+
+5. Commit the version/docs changes.
+6. Tag or create a GitHub Release for the same version, for example `v0.1.1`.
+7. Confirm the GitHub Actions release workflow publishes successfully.
+8. Verify the package page and install path:
+
+```bash
+uv tool install --force 'ghinsight[actions]'
+ghinsight --help
+```
+
+## Useful References
+
+- PyPI Trusted Publishing:
+  https://docs.pypi.org/trusted-publishers/
+- Publishing with a Trusted Publisher:
+  https://docs.pypi.org/trusted-publishers/using-a-publisher/
+- Python Packaging User Guide for GitHub Actions publishing:
+  https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

ghinsight-0.2.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.5
+Name: ghinsight
+Version: 0.2.0
+Summary: Reusable tools for GitHub analysis: Actions usage, issue and PR activity, and a small API client
+Project-URL: Homepage, https://github.com/ickc/ghinsight
+Project-URL: Repository, https://github.com/ickc/ghinsight
+Project-URL: Issues, https://github.com/ickc/ghinsight/issues
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: actions,activity,analysis,dashboard,github,metrics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.16
+Requires-Dist: typer>=0.12
+Provides-Extra: actions
+Requires-Dist: pandas>=2.0; extra == 'actions'
+Requires-Dist: plotly>=6.0; extra == 'actions'
+Requires-Dist: rich>=13.0; extra == 'actions'
+Description-Content-Type: text/markdown
+
+# ghinsight
+
+*Pronounced "gin-sight": the h is silent.*
+
+Reusable tools for analysing GitHub organisations and user accounts:
+
+| Part | Install | What it does |
+| ---- | ------- | ------------ |
+| `ghinsight activity` | core | Markdown table of a user's issue and PR activity over a date range |
+| `ghinsight actions` | `[actions]` extra | GitHub Actions usage and performance: cached fetch, metric CSVs, HTML dashboard |
+| `ghinsight.client`, `ghinsight.repos` | core | A small GitHub REST/GraphQL client and repository listing, for other tools to build on |
+
+The core depends only on [httpx2](https://github.com/pydantic/httpx2) and
+[typer](https://typer.tiangolo.com); the `actions` extra adds pandas, plotly and
+rich. Everything is organisation-agnostic: names, paths and billing assumptions
+are arguments or config.
+
+## Install
+
+```bash
+uv tool install ghinsight              # core: activity
+uv tool install 'ghinsight[actions]'   # also: actions
+ghinsight --help
+```
+
+For local development from a checkout:
+
+```bash
+uv sync --group dev                    # includes the actions extra
+uv run ghinsight --help
+```
+
+A conda-forge `pixi` environment is also provided:
+
+```bash
+pixi run help
+pixi run check
+pixi run test
+```
+
+## Authentication
+
+Every command needs a GitHub token. For `ghinsight actions`, it must be able to
+read Actions metadata for the target account. Use either:
+
+```bash
+export GH_TOKEN=...          # or GITHUB_TOKEN
+```
+
+or login with the GitHub CLI (`gh auth login`): if neither variable is set, the
+token comes from `gh auth token`, wherever `gh` stores it. `GITHUB_API_URL` (set
+inside GitHub Actions) selects a GitHub Enterprise Server API.
+
+## Issue and PR activity
+
+```bash
+ghinsight activity --repo my-org/some-repo --user octocat --from 2026-05-20 --to 2026-05-27
+ghinsight activity --org my-org --user octocat --from 2026-09-16 --to 2026-09-24 --output week.md
+```
+
+With `--org`, every repository of the organisation (or user) is searched and
+items are labelled `repo#123`. An issue or PR is listed when, within the range,
+it was:
+
+- opened by `--user`;
+- closed or merged, and either authored or closed/merged by `--user`;
+- authored by `--user` earlier and updated by them (comments, commits,
+  force-pushes, draft/ready changes, review requests), even if still open;
+- reviewed by `--user` (someone else's PR; the type shows approved, changes
+  requested or reviewed).
+
+`--authored-only` drops the last category and PRs closed/merged by `--user`
+that they did not author. Date ranges with more than 1,000 search results are
+split automatically; long ranges across a large organisation are slower, since
+every item closed in the range is fetched to check who closed it.
+
+## GitHub Actions usage and performance
+
+`ghinsight actions` fetches workflow-run and job data from the GitHub REST API,
+caches the raw JSON locally, parses it into a single typed **intermediate
+representation**, and derives every report — GitHub-style metric tables,
+headline KPIs, and a static HTML dashboard — as a pure projection of that
+representation.
+
+### Architecture
+
+A three-stage, functional pipeline (see the [design docs](docs/design.md) for
+the full rationale):
+
+| Stage | Module | Output |
+| ----- | ------ | ------ |
+| 1. Fetch | `ghinsight.actions.fetch` | cached raw JSON (verbatim API responses) |
+| 2. Dataset (the IR) | `ghinsight.actions.dataset` | `ActionsDataset` — a tidy per-job / per-run table |
+| 3a. Metric tables | `ghinsight.actions.metrics` | usage / performance DataFrames |
+| 3b. Insights | `ghinsight.actions.analysis` | `UsageSummary`, monthly time-series |
+| 3c. Report | `ghinsight.actions.report` | HTML dashboard + JSON summary |
+
+The canonical intermediate representation is a **tidy per-job table** (one row
+per job, with all derived measures and dimensions), not GitHub's aggregate CSV
+exports. Aggregate exports drop per-job timestamps, so they cannot support
+time-series views; the tidy table can, and every other view derives from it.
+GitHub-compatible CSVs are still produced as an *export*
+(`ghinsight.actions.csv_export`) for diffing against GitHub's own metrics.
+
+### Quick start
+
+```bash
+mkdir github-actions-report && cd github-actions-report
+$EDITOR analysis.toml          # see examples/analysis.toml
+ghinsight actions recreate --config analysis.toml
+```
+
+`recreate` runs fetch → CSV export → dashboard end to end. The dashboard is
+written to `docs/index.html` and machine-readable metadata to
+`docs/summary.json`. See the [CLI tutorial](docs/tutorials/cli.md) for the
+step-by-step version and the [Python tutorial](docs/tutorials/python_analysis.py)
+for the programmatic analysis API.
+
+### Other commands
+
+```bash
+# Fetch, then export CSVs, separately:
+ghinsight actions fetch  --org example-org --period last-year --cache-dir cache
+ghinsight actions report --org example-org --cache-dir cache --output-dir reports
+
+# Print a table to the terminal:
+ghinsight actions show usage repositories --org example-org --cache-dir cache
+
+# Diff generated CSVs against a reference snapshot exported from GitHub:
+ghinsight actions compare reference-data reports
+```
+
+### Config reference
+
+See [examples/analysis.toml](examples/analysis.toml). `period` accepts
+`last-year`, `last-6-months`, `last-3-months`, `last-month`, or
+`YYYY-MM-DD..YYYY-MM-DD`.
+
+`[analysis]`: `org`, `period`, `cache_dir`, `reports_dir`, `data_dir`,
+`output_html`, `summary_json`, `billing` (optional; see below).
+
+`[dashboard]`: `title`, `period_label`, `plan_minutes` (optional monthly cap),
+`extra_insights_html`, `extra_limitations_html`.
+
+`[os_multipliers]`: runtime OS billing multipliers for billed-equivalent
+estimates (defaults: linux 1, windows 2, macos 10).
+
+### Private-repository minutes and the billing report
+
+A plan's included minutes only apply to private (and internal) repositories:
+public repositories on standard GitHub-hosted runners are free. `fetch` records
+each repository's visibility (`repo.json` in the cache), and the dashboard's
+minute charts get an **All repositories / Private repositories only** toggle,
+with private-only KPIs and a `private_only` block in `summary.json`.
+Visibility is as of the fetch, so a repository whose visibility changed during
+the period is classified by its current visibility throughout. Caches written
+before visibility was recorded render without the toggle; re-run `fetch` to add
+it.
+
+Optionally, `fetch --billing` (or `billing = true` in the config) also caches
+GitHub's [billing usage report](https://docs.github.com/en/rest/billing/usage),
+which gives the minutes GitHub actually billed and the net charge. The dashboard
+then adds a billed-usage section and a `billing_report` block in `summary.json`.
+The API appears to admit **organisation owners only**: billing managers get a
+404 even with a classic token carrying `admin:org` (for a user account, the
+token needs the `user` scope). Without access the fetch logs a warning and
+caches nothing, and the dashboard notes that all figures are estimates.
+
+Billing managers can instead download the usage report CSV from the
+organisation's billing usage page (the *summarized* report covers up to a year
+and breaks usage down by repository) and import it:
+
+```bash
+ghinsight actions import-billing usage-report.csv --org example-org --cache-dir cache
+```
+
+This writes the same cache files as the API fetch, which then reuses them.
+
+The billing report appears to list only usage that counted towards the
+quota: in testing, a public repository's usage while public was not billed at
+all, while a repository billed for months was made public only afterwards.
+The dashboard therefore shows billed minutes as they are, with no visibility
+filter; being as-billed, they also reflect each repository's visibility *at the
+time*, which the private-only estimates cannot.
+
+## Using the client from Python
+
+```python
+from ghinsight import GitHubClient, list_repos
+
+with GitHubClient() as gh:                      # token from GH_TOKEN, GITHUB_TOKEN or gh
+    repos = list_repos("my-org", gh)            # RepoInfo: slug, visibility, fork, archived, ...
+    runs = gh.paginate("/repos/my-org/some-repo/actions/runs", response_key="workflow_runs")
+    viewer = gh.graphql("{ viewer { login } }")
+```
+
+`GitHubClient` waits out primary and secondary rate limits (up to
+`max_rate_limit_wait` seconds), retries server and network errors with backoff,
+and raises `GitHubError` (with `.status`) otherwise. For the authenticated user,
+`list_repos` includes private repositories, which `/users/{user}/repos` omits.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest                  # offline test suite (synthetic fixtures)
+uv build                       # build the wheel/sdist
+```
+
+The test suite runs fully offline against a synthetic cache (`tests/synthetic.py`),
+so no token or network is required.
+
+## Documentation
+
+```bash
+uv sync --group docs
+uv run --group docs sphinx-build -b html docs docs/_build/html
+```
+
+The site uses Sphinx with AutoAPI (API reference from source), a design page,
+and CLI + Python tutorials (the Python tutorial is an executable jupytext
+notebook rendered via MyST-NB).