kuma-stats 0.3.0__tar.gz

kuma_stats-0.3.0/.env.example

@@ -0,0 +1,9 @@
+# Uptime Kuma server URL (required)
+KUMA_URL=https://kuma.example.com
+
+# Use either a server-issued JWT token...
+# KUMA_TOKEN=
+
+# ...or a username and password. These are also required for `kuma-stats login`.
+KUMA_USERNAME=
+KUMA_PASSWORD=

kuma_stats-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubicloud-standard-2
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install '.[dev]' build twine
+      - run: python -m ruff check .
+      - run: python -m mypy src/kuma_stats
+      - run: python -m pytest -q
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Verify wheel installation
+        run: |
+          python -m venv /tmp/wheel-venv
+          /tmp/wheel-venv/bin/python -m pip install dist/*.whl
+          /tmp/wheel-venv/bin/kuma-stats --help
+          /tmp/wheel-venv/bin/python -m kuma_stats --help
+      - name: Verify sdist installation
+        run: |
+          python -m venv /tmp/sdist-venv
+          /tmp/sdist-venv/bin/python -m pip install dist/*.tar.gz
+          /tmp/sdist-venv/bin/kuma-stats --help

kuma_stats-0.3.0/.github/workflows/live-kuma.yml

@@ -0,0 +1,252 @@
+name: Live Kuma smoke test
+
+# Maintainer-only Docker-backed Uptime Kuma tests.
+#
+# Preferred entry point: comment `/run-live-tests` on a same-repository PR.
+# The manual dispatch path is retained for the Actions UI; both paths are
+# restricted to the repository owner.
+on:
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: PR number for a PR check and result comment
+        type: string
+        required: false
+      pr_sha:
+        description: PR head SHA to test (defaults to the workflow ref SHA)
+        type: string
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  prepare:
+    name: Authorize Live Kuma Tests
+    # issue_comment workflows always run from the default branch. Resolve the
+    # PR head explicitly, and verify both the initial and re-run actor.
+    if: |
+      (
+        github.event_name == 'issue_comment' &&
+        github.event.issue.pull_request &&
+        github.event.comment.body == '/run-live-tests' &&
+        github.actor == github.repository_owner &&
+        github.triggering_actor == github.repository_owner
+      ) || (
+        github.event_name == 'workflow_dispatch' &&
+        github.actor == github.repository_owner &&
+        github.triggering_actor == github.repository_owner
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      pr_number: ${{ steps.pr.outputs.number }}
+      pr_sha: ${{ steps.pr.outputs.sha }}
+
+    steps:
+      - name: Restore originally authorized PR target on rerun
+        if: github.event_name == 'issue_comment' && github.run_attempt > 1
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: live-kuma-target-${{ github.run_id }}
+          path: ${{ runner.temp }}/authorized-live-kuma-target
+      - name: Get PR information
+        id: pr
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          PR_NUMBER: ${{ inputs.pr_number }}
+          PR_SHA: ${{ inputs.pr_sha }}
+          RESTORED_TARGET: ${{ runner.temp }}/authorized-live-kuma-target/target.json
+        with:
+          script: |
+            const fs = require('node:fs');
+            let target;
+
+            if (context.eventName === 'issue_comment' && context.runAttempt > 1) {
+              target = JSON.parse(fs.readFileSync(process.env.RESTORED_TARGET, 'utf8'));
+            } else if (context.eventName === 'workflow_dispatch' && !process.env.PR_NUMBER) {
+              target = { number: '', sha: process.env.PR_SHA || context.sha };
+            } else {
+              const pullNumber = context.eventName === 'issue_comment'
+                ? context.issue.number
+                : Number(process.env.PR_NUMBER);
+              const pr = await github.rest.pulls.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: pullNumber,
+              });
+
+              if (context.eventName === 'issue_comment' && pr.data.head.repo.full_name !== pr.data.base.repo.full_name) {
+                core.setFailed('Live Kuma tests cannot run on fork PRs.');
+                return;
+              }
+
+              target = { number: String(pr.data.number), sha: pr.data.head.sha };
+              if (process.env.PR_SHA && process.env.PR_SHA !== target.sha) {
+                core.setOutput('number', target.number);
+                core.setOutput('sha', target.sha);
+                core.setFailed('pr_sha must match the current head SHA of pr_number.');
+                return;
+              }
+            }
+
+            core.setOutput('number', target.number);
+            core.setOutput('sha', target.sha);
+            fs.writeFileSync(`${process.env.RUNNER_TEMP}/target.json`, JSON.stringify(target));
+      - name: Save authorized PR target
+        if: github.event_name == 'issue_comment' && github.run_attempt == 1
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: live-kuma-target-${{ github.run_id }}
+          path: ${{ runner.temp }}/target.json
+          if-no-files-found: error
+
+  live-kuma:
+    name: Run Live Kuma Tests
+    needs: prepare
+    # A re-run can be initiated by another collaborator, so check the
+    # triggering actor again before executing PR-controlled code.
+    if: |
+      always() &&
+      !cancelled() &&
+      (
+        (
+          github.event_name == 'issue_comment' &&
+          needs.prepare.result == 'success' &&
+          github.actor == github.repository_owner &&
+          github.triggering_actor == github.repository_owner
+        ) ||
+        (
+          github.event_name == 'workflow_dispatch' &&
+          needs.prepare.result == 'success' &&
+          github.actor == github.repository_owner &&
+          github.triggering_actor == github.repository_owner
+        )
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # This job executes PR-controlled code; it deliberately has no write token.
+    permissions:
+      contents: read
+    outputs:
+      pr_number: ${{ steps.meta.outputs.pr_number }}
+      pr_sha: ${{ steps.meta.outputs.pr_sha }}
+
+    steps:
+      - name: Resolve target metadata
+        id: meta
+        run: |
+          echo "pr_number=${{ needs.prepare.outputs.pr_number }}" >> "$GITHUB_OUTPUT"
+          echo "pr_sha=${{ needs.prepare.outputs.pr_sha }}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.meta.outputs.pr_sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install '.[dev]' build
+      - run: python -m build
+      - name: Install built wheel into a clean environment
+        run: |
+          python -m venv /tmp/kuma-live-venv
+          /tmp/kuma-live-venv/bin/python -m pip install dist/*.whl
+      - name: Test installed CLI against disposable Uptime Kuma
+        env:
+          RUN_LIVE_KUMA_TESTS: '1'
+          KUMA_STATS_CLI: /tmp/kuma-live-venv/bin/kuma-stats
+          KUMA_LOG_PATH: ${{ runner.temp }}/kuma-container.log
+        run: python -m pytest -q tests/integration/test_live_kuma.py
+      - name: Upload Uptime Kuma container logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: kuma-container-logs
+          path: ${{ runner.temp }}/kuma-container.log
+          if-no-files-found: ignore
+
+  report:
+    name: Report Live Kuma Result
+    needs: [prepare, live-kuma]
+    if: |
+      always() &&
+      (
+        needs.live-kuma.result != 'skipped' ||
+        (
+          github.event_name == 'workflow_dispatch' &&
+          needs.prepare.result == 'failure'
+        )
+      ) &&
+      (
+        (
+          github.event_name == 'issue_comment' &&
+          needs.prepare.result == 'success' &&
+          github.actor == github.repository_owner &&
+          github.triggering_actor == github.repository_owner
+        ) ||
+        (
+          github.event_name == 'workflow_dispatch' &&
+          inputs.pr_number != '' &&
+          github.actor == github.repository_owner &&
+          github.triggering_actor == github.repository_owner
+        )
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      checks: write
+      pull-requests: write
+
+    steps:
+      - name: Create check and comment on PR
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            const result = '${{ needs.live-kuma.result }}' === 'skipped'
+              ? 'failure'
+              : '${{ needs.live-kuma.result }}';
+            const conclusion = result === 'success'
+              ? 'success'
+              : result === 'cancelled'
+                ? 'cancelled'
+                : 'failure';
+            const sha = '${{ needs.live-kuma.outputs.pr_sha }}' || '${{ needs.prepare.outputs.pr_sha }}';
+            const prNumber = Number('${{ needs.live-kuma.outputs.pr_number }}' || '${{ needs.prepare.outputs.pr_number }}');
+            const logsUrl = '${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}';
+            const title = conclusion === 'success'
+              ? 'Live Kuma tests passed'
+              : conclusion === 'cancelled'
+                ? 'Live Kuma tests cancelled'
+                : 'Live Kuma tests failed';
+            const body = conclusion === 'success'
+              ? `✅ Live Kuma tests passed. Tested commit: \`${sha}\`. [View logs](${logsUrl})`
+              : conclusion === 'cancelled'
+                ? `⚪ Live Kuma tests cancelled. Tested commit: \`${sha}\`. [View logs](${logsUrl})`
+                : `❌ Live Kuma tests failed. Tested commit: \`${sha}\`. [View logs](${logsUrl})`;
+
+            await github.rest.checks.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              name: 'Live Kuma smoke test',
+              head_sha: sha,
+              status: 'completed',
+              conclusion,
+              details_url: logsUrl,
+              output: {
+                title,
+                summary: `[View live-test logs](${logsUrl})`,
+              },
+            });
+
+            if (Number.isFinite(prNumber) && prNumber > 0) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body,
+              });
+            }

kuma_stats-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+build/
+dist/
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+src/*.egg-info/
+.env
+.env.*
+!.env.example

kuma_stats-0.3.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+
+## [0.3.0] - 2026-07-20
+
+### Added
+
+- Public-release documentation, packaging metadata, CI validation, and security policy.
+
+### Changed
+
+- Normalized Uptime Kuma errors and clarified configuration behavior.
+- Build and package management migrated from setuptools to uv, enabling reproducible builds via a lock file. ([#23])
+
+### Fixed
+
+- Source distributions no longer include local agent artifacts that could prevent installation. ([#25])
+- Connection timeout and configuration-validation errors are now reliably enforced and surfaced instead of silently ignored. ([d5ad17d])
+
+[d5ad17d]: https://github.com/crcatala/kuma-stats/commit/d5ad17d
+[#23]: https://github.com/crcatala/kuma-stats/pull/23
+[#25]: https://github.com/crcatala/kuma-stats/pull/25
+
+
+## Release process
+
+PyPI releases are immutable. Bump the version with:
+
+```bash
+make bump          # minor bump (0.2.0 → 0.3.0)
+make bump/patch    # patch bump (0.2.0 → 0.2.1)
+make bump/major    # major bump (0.2.0 → 1.0.0)
+make bump/1.0.0    # explicit version
+```
+
+This updates `__version__` and promotes `## [Unreleased]` into a dated `## [X.Y.Z]` section. Review with `git diff`, commit, push, then use `make release-dry` before `make release`; publish the resulting `dist/*` artifacts separately with `uv run twine upload dist/*`.

kuma_stats-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Thanks for your interest in `kuma-stats`.
+
+This is a personally maintained project. Code contributions, pull requests, and feature requests are not accepted at this time. Unsolicited pull requests may be closed without review.
+
+## Bug reports
+
+Bug reports are welcome when they include:
+
+- clear reproduction steps;
+- the `kuma-stats` version;
+- operating system and Python version; and
+- relevant, sanitized error output.
+
+Please search existing issues before opening a new one. Do not include passwords, JWTs, server URLs, or other credentials in a public report.
+
+## Security issues
+
+Do not open a public issue for a security vulnerability. Follow the private reporting guidance in [SECURITY.md](SECURITY.md).
+
+## Forks
+
+You may fork and adapt this project under the terms of the [MIT License](LICENSE).

kuma_stats-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Catalan
+
+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.

kuma_stats-0.3.0/Makefile

@@ -0,0 +1,32 @@
+.PHONY: setup format lint typecheck test live-test build verify bump release-prep release release-dry
+setup:
+	uv sync --all-extras
+format:
+	uv run ruff format .
+lint:
+	uv run ruff check .
+typecheck:
+	uv run mypy src/kuma_stats
+test:
+	uv run pytest -q
+# Requires Docker; starts a disposable, pinned Uptime Kuma container.
+live-test:
+	uv run pytest -q tests/integration/test_live_kuma.py
+build:
+	uv build
+	uv run twine check dist/*
+verify: setup lint typecheck test build
+# Summarize changes since the last v* tag and print an LLM prompt for release notes.
+bump:
+	./scripts/bump-version.sh
+# Bump with explicit version or type: make bump VERSION=patch / make bump VERSION=1.2.3
+bump/%:
+	./scripts/bump-version.sh $*
+release-prep:
+	./scripts/prep-release.sh
+# Preview the safeguards and commands for a GitHub release.
+release-dry:
+	./scripts/release.sh --dry-run
+# Validate, tag, and create a GitHub Release. PyPI publishing remains manual.
+release:
+	./scripts/release.sh

kuma_stats-0.3.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: kuma-stats
+Version: 0.3.0
+Summary: Read-only CLI for Uptime Kuma monitor status, uptime, and heartbeat data
+Project-URL: Homepage, https://github.com/crcatala/kuma-stats
+Project-URL: Repository, https://github.com/crcatala/kuma-stats
+Project-URL: Issues, https://github.com/crcatala/kuma-stats/issues
+Project-URL: Security, https://github.com/crcatala/kuma-stats/security/policy
+Author-email: Christian Catalan <crcatala@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,monitoring,status,uptime,uptime-kuma
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: keyring>=24.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: uptime-kuma-api>=1.2.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kuma-stats
+
+[![CI](https://github.com/crcatala/kuma-stats/actions/workflows/ci.yml/badge.svg)](https://github.com/crcatala/kuma-stats/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/kuma-stats)](https://pypi.org/project/kuma-stats/)
+[![Python](https://img.shields.io/pypi/pyversions/kuma-stats)](https://pypi.org/project/kuma-stats/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A read-only terminal dashboard for [Uptime Kuma](https://github.com/louislam/uptime-kuma): current monitor state, uptime percentages, response time, and heartbeat history.
+
+> `kuma-stats` is an independent project and is not affiliated with or endorsed by Uptime Kuma.
+
+## Install
+
+Requires Python 3.10 or later.
+
+```bash
+pip install kuma-stats
+# or install as an isolated command-line tool
+uv tool install kuma-stats
+# pipx install kuma-stats
+```
+
+Verify the installation:
+
+```bash
+kuma-stats --version
+```
+
+## Quick start
+
+Set the Uptime Kuma URL and a server-issued JWT token. Environment variables are preferred for automation; do not pass passwords or tokens as command-line arguments because they can be exposed in shell history or process listings.
+
+```bash
+export KUMA_URL=https://kuma.example.com
+export KUMA_TOKEN=your-server-issued-jwt
+kuma-stats list
+kuma-stats --format json uptime
+```
+
+Alternatively, create a `.env` file in the directory where you run the command:
+
+```dotenv
+KUMA_URL=https://kuma.example.com
+KUMA_TOKEN=your-server-issued-jwt
+```
+
+`kuma-stats` loads this working-directory `.env` without overwriting environment variables. Keep it out of version control.
+
+To create a token with username/password credentials already supplied through environment variables, use:
+
+```bash
+export KUMA_USERNAME=your-username
+export KUMA_PASSWORD=your-password
+kuma-stats login --store-keyring
+```
+
+The keyring is the preferred token store. `login --store-token` writes an owner-only `.env` file; use it only when the OS keyring is unavailable.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `login [--store-token \| --store-keyring]` | Authenticate and print or securely save a server-issued JWT |
+| `list` | List all monitors and current telemetry |
+| `status [ID…]` | Show details and recent heartbeats; omit IDs for all monitors |
+| `beats ID [--hours N]` | Show heartbeat history for one monitor |
+| `uptime` | Show 24-hour, 30-day, and one-year uptime |
+
+Examples:
+
+```bash
+kuma-stats list
+kuma-stats status 1 2
+kuma-stats beats 1 --hours 48
+kuma-stats --format yaml uptime
+kuma-stats --format json list
+```
+
+Table output is the default. Use `--format json` or `--format yaml` for structured output. JSON and YAML errors are written to stderr with a stable code and message.
+
+## Configuration
+
+Values are resolved in this order, from highest to lowest precedence:
+
+1. Command-line options
+2. Environment variables
+3. A `.env` file in the working directory
+4. User configuration: `$XDG_CONFIG_HOME/kuma-stats/config.toml` on Linux
+5. An OS-keyring token
+
+Use `KUMA_CONFIG_FILE` to select a different TOML file. Example:
+
+```toml
+url = "https://kuma.example.com"
+format = "table" # table, json, or yaml
+timeout = 30
+max_retries = 2
+insecure = false
+```
+
+| Variable | Purpose |
+| --- | --- |
+| `KUMA_URL` | Uptime Kuma server URL |
+| `KUMA_TOKEN` | Server-issued JWT token |
+| `KUMA_USERNAME`, `KUMA_PASSWORD` | Login credentials; required for `login` without a token |
+| `KUMA_FORMAT` | Default output format: `table`, `json`, or `yaml` |
+| `KUMA_TIMEOUT` | Per-connection timeout and overall retry budget in seconds |
+| `KUMA_MAX_RETRIES` | Retry count for transient connection failures |
+| `KUMA_INSECURE` | Set to `true` only for a trusted self-signed server |
+| `NO_COLOR` | Disable terminal colour |
+
+TLS certificate verification is enabled by default. Use `--insecure` only for a trusted self-signed server. Invalid or unreadable TOML configuration files fail with an `INVALID_CONFIGURATION` error instead of being ignored.
+
+## Compatibility
+
+`kuma-stats` supports Python 3.10–3.12 and uses the maintained [`uptime-kuma-api`](https://github.com/lucasheld/uptime-kuma-api) client for Uptime Kuma communication. CI smoke-tests token authentication, password login, failed authentication, and `list` telemetry against a disposable [Uptime Kuma 1.23.16](https://hub.docker.com/layers/louislam/uptime-kuma/1.23.16/images/sha256-431fee3be822b04861cf0e35daf4beef6b7cb37391c5f26c3ad6e12ce280fe18) Docker container. It uses no external server or credentials.
+
+## Development
+
+```bash
+make setup
+make verify
+make live-test # requires Docker
+```
+
+`make verify` runs linting, type checks, tests, builds wheel/sdist artifacts, and validates their metadata. `make live-test` runs the separately gated Docker compatibility smoke test; it creates disposable credentials and state and never contacts a production server.
+
+### Releasing
+
+Releases are intentionally manual. Draft notes from the commits since the last release:
+
+```bash
+make release-prep
+```
+
+Use the printed prompt with an LLM if useful, review its suggested Keep a Changelog entry, then update `CHANGELOG.md` and `src/kuma_stats/__init__.py`. Preview and create the GitHub Release:
+
+```bash
+make release-dry
+make release
+```
+
+`make release` requires a clean `main` worktree, a new versioned changelog section, and confirmation. It validates the project, creates and pushes an annotated `vX.Y.Z` tag, then attaches the validated wheel and sdist to a GitHub Release. PyPI publishing is a separate deliberate step:
+
+```bash
+uv run twine upload dist/*
+```
+
+See [docs/RELEASING.md](docs/RELEASING.md) for PyPI/TestPyPI account setup, local token storage, testing, and troubleshooting.
+
+## Security and support
+
+See [SECURITY.md](SECURITY.md) for private vulnerability reporting, [CONTRIBUTING.md](CONTRIBUTING.md) for the maintenance policy, and [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+Distributed under the [MIT License](LICENSE).