kirox 1.1.0__tar.gz

kirox-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,118 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install development and MCP dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,mcp]"
+
+      - name: Ruff format check
+        run: python -m ruff format --check .
+
+      - name: Ruff lint
+        run: python -m ruff check .
+
+      - name: Mypy
+        run: python -m mypy src tests scripts
+
+      - name: Pyrefly
+        run: python -m pyrefly check
+
+      - name: Test with branch coverage
+        run: python -m pytest tests -q --cov=kirox --cov-branch --cov-report=term-missing
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Inspect wheel and run clean-install smoke test
+        run: python scripts/verify_distribution.py
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: kirox-${{ matrix.os }}-py${{ matrix.python-version }}
+          path: dist/*
+          if-no-files-found: error
+
+
+  service-extra:
+    name: Optional service extra / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build==1.5.0
+          python -m build --wheel
+
+      - name: Install wheel with the service extra
+        shell: bash
+        run: python -m pip install "$(ls dist/*.whl)[service]"
+
+      - name: Verify dependency resolution
+        run: python -m pip check
+
+      - name: Headless tray import smoke test
+        shell: bash
+        run: |
+          python - <<'PY'
+          import importlib.util
+          import os
+          import sys
+
+          import kirox.service.tray as tray
+          from kirox.service.daemon import KiroxService
+
+          # Prove the optional dependencies are installed without importing
+          # pystray, which probes a display backend at import time.
+          for name in ("pystray", "PIL"):
+              assert importlib.util.find_spec(name) is not None, f"{name} is not installed"
+
+          assert tray.KiroTray is not None
+          assert KiroxService is not None
+
+          if sys.platform.startswith("linux") and not os.environ.get("DISPLAY"):
+              assert tray.HAS_PYSTRAY is False, "tray must degrade without a display"
+              assert tray.create_icon_image() is None
+              assert tray.KiroTray().start() is False, "start() must refuse headless"
+
+          print("tray import ok, HAS_PYSTRAY =", tray.HAS_PYSTRAY)
+          PY
+
+      - name: Console script smoke test
+        run: kirox --help

kirox-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kirox
+    permissions:
+      # Required for PyPI trusted publishing. No API token is used.
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Verify the tag matches the packaged version
+        shell: bash
+        run: |
+          python - <<'PY'
+          import importlib.util
+          import os
+          import sys
+
+          # Load _version.py on its own. Importing kirox._version would execute
+          # kirox/__init__.py, which needs runtime dependencies that are not
+          # installed yet at this point in the job.
+          spec = importlib.util.spec_from_file_location("_kirox_version", "src/kirox/_version.py")
+          assert spec is not None and spec.loader is not None
+          module = importlib.util.module_from_spec(spec)
+          spec.loader.exec_module(module)
+
+          ref = os.environ["GITHUB_REF_NAME"]
+          tag = ref.removeprefix("v")
+          if tag != module.__version__:
+              sys.exit(f"tag {ref} does not match src/kirox/_version.py ({module.__version__})")
+          print(f"tag {ref} matches packaged version {module.__version__}")
+          PY
+
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build==1.5.0
+          python -m build
+
+      - name: Inspect wheel and run clean-install smoke test
+        run: python scripts/verify_distribution.py
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.2

kirox-1.1.0/.gitignore

@@ -0,0 +1,73 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.venv/
+venv/
+ENV/
+env/
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+.ipynb_checkpoints/
+.DS_Store
+Thumbs.db
+Desktop.ini
+*.log
+*.tmp
+*.temp
+.env
+.env.*
+!.env.example
+.kiro/
+*.mitm
+
+# Compiled extensions on Windows (companion to *.so above)
+*.pyd
+
+# Type checker daemons and caches not covered above
+.dmypy.json
+dmypy.json
+.pyrefly_cache/
+
+# Local interpreter pins and build metadata
+.python-version
+pip-wheel-metadata/
+
+# Merge, patch, and backup leftovers
+*.orig
+*.rej
+*.bak
+
+# Created by mistyped PowerShell redirection on Windows
+nul

kirox-1.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to Kirox are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-07-31
+
+### Added
+
+- Strict incremental AWS EventStream decoder with CRC, size, header-type, UTF-8, and truncation validation.
+- Deterministic credential resolution with explicit/config/KIROX/ASSISTANT/database precedence and fixed database discovery locations.
+- Managed service state, authenticated loopback shutdown, startup rollback, socket/thread ownership, and idempotent client cleanup.
+- Text-only OpenAI chat-completions and Anthropic messages adapters with canonical history, field-addressed validation, incremental SSE, disconnect cleanup, and sanitized errors.
+- Operational `kirox-mcp` stdio entry point with lazy optional imports, strict tool input, worker-thread bridging, one client, and lifecycle cleanup.
+- PEP 561 `py.typed` marker and wheel/clean-install distribution verifier.
+- Windows and Ubuntu CI matrix for Python 3.10–3.14 covering Ruff, mypy, Pyrefly, branch coverage, wheel/sdist build, metadata inspection, and install smoke tests, plus a dedicated job that installs the built wheel with the optional `service` extra and runs a headless tray-import and `pip check` smoke test.
+- Pyrefly as a second required type checker, with an explicit `[tool.pyrefly]` section so it does not fall back to the permissive `basic` preset, and warnings promoted to failures.
+- Loopback `Host` header validation and a 1 MiB request-body limit on every bridge route, returning HTTP 400 and provider-shaped HTTP 413 responses before validation or upstream work.
+- Kernel-derived process identity in service state, with identity-bound `kirox stop --force` termination on Linux and Windows that fails closed on PID reuse, missing identity, or unsupported platforms.
+
+### Changed
+
+- The token scheduler now treats HTTP 401 and 403 from its authentication check as credential failures, re-resolves credentials, and retries the check once instead of relying on error-message text.
+- `AssistantClient.list_tools()` now validates the upstream envelope strictly and raises `APIError` for a missing `result`, a missing or non-array `tools` member, or entries without a non-empty `name` and an `inputSchema` object.
+- Package version now has one source in `src/kirox/_version.py`; CLI, health responses, root metadata, and built distributions report 1.1.0.
+- HTTP service binding is explicitly loopback-only.
+- The service token scheduler now uses an interruptible standard-library worker, removing the unused APScheduler dependency.
+- CLI, tray, scheduler, and server lifecycle paths now close owned resources deterministically.
+- Quality configuration now checks formatting, imports, common bugs, repository typing with two checkers, and a minimum 80% branch-aware coverage threshold.
+- Development tooling is pinned to exact versions, and runtime dependencies now carry both a tested floor and a major upper bound. The optional MCP extra stays on `mcp>=1.28.1,<2`: the v2 SDK moved the low-level `Server` handlers from decorators to constructor parameters, so the current stdio server would not run against it.
+- Installation, configuration, API, contribution, and lifecycle documentation now match actual behavior and text-only limitations.
+
+### Fixed
+
+- EventStream parsing no longer assumes complete HTTP chunks or accepts bad checksums, impossible lengths, unsupported header encodings, or trailing partial frames.
+- Streaming provider responses no longer prebuffer the upstream iterator, leak it on disconnect/error, duplicate terminal events, expose exception details, or fabricate usage values.
+- MCP import no longer exits the host process when the optional dependency is absent.
+- CLI stop no longer targets a PID until persisted state and service ownership have been validated, and force stop now additionally proves process identity so a reused PID is never signalled.
+- `ModelInfo.from_api()` no longer stores `None` in fields declared `str`, `int`, or `float` when upstream sends an explicit null, and no longer raises `AttributeError` for a null `tokenLimits`; an unusable `modelId` now raises `ValueError` instead of producing a mistyped model.
+- `AssistantClient.list_models()` now validates the response envelope and reports malformed payloads as `APIError` rather than letting `KeyError` or `ValueError` escape the SDK.
+- Importing `kirox.service.tray` no longer crashes on a host with no usable display. `pystray` probes a display backend while importing, so a headless Linux server raised `Xlib.error.DisplayNameError`, which the previous `except ImportError` guard did not catch. The tray now degrades to unavailable and reports a message that names the missing display as a possible cause.
+
+## [1.0.0] - 2026-07-30
+
+### Added
+
+- Initial core API client with streaming and multi-model support.
+- CLI with interactive chat and update checks.
+- Background HTTP service and optional system tray.
+- Token refresh scheduler and configuration management.
+- OpenAI- and Anthropic-compatible bridge endpoints.
+- MCP integration and unit, integration, end-to-end, and performance tests.
+
+## [0.2.0] - 2026-07-30
+
+### Added
+
+- Background service module, system tray support, token scheduler, HTTP API server, and associated tests.
+
+## [0.1.0] - 2026-07-30
+
+### Added
+
+- Initial project structure, API client, EventStream parser, CLI interface, and basic tests.

kirox-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to Kirox
+
+## Development setup
+
+Kirox supports Python 3.10–3.14 on Windows and Linux CI.
+
+```bash
+git clone https://github.com/your-username/kirox.git
+cd kirox
+python -m venv .venv
+```
+
+Activate the environment with `.venv\Scripts\Activate.ps1` on Windows PowerShell or `source .venv/bin/activate` in a POSIX shell, then install all development dependencies used by the test suite:
+
+```bash
+python -m pip install -e ".[dev,mcp]"
+```
+
+The tray extra is not required for tests; tray behavior is exercised with fakes so CI does not need a desktop session.
+
+## Required quality gates
+
+Run every command from the repository root before opening a pull request:
+
+```bash
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy src tests scripts
+python -m pyrefly check
+python -m pytest tests -q --cov=kirox --cov-branch --cov-report=term-missing
+python -m build
+python scripts/verify_distribution.py
+```
+
+Branch coverage must remain at least 80%. Both type checkers are required: they disagree often enough that each one catches errors the other misses. Pyrefly reads its `[tool.pyrefly]` section in `pyproject.toml`; without that section it would fall back to the `basic` preset and silence most type errors. The distribution verifier checks the wheel version, `kirox/py.typed`, `kirox` and `kirox-mcp` entry points, then performs a clean temporary-environment install/import/CLI/missing-extra smoke test and `pip check`.
+
+CI runs the same gates on Windows and Ubuntu with Python 3.10, 3.11, 3.12, 3.13, and 3.14. A separate job installs the built wheel with the optional `service` extra and runs a headless tray-import and `pip check` smoke test, so the tray dependencies are exercised without requiring a desktop session in the main matrix. A local Python version outside that matrix is useful but does not replace supported-version CI.
+
+## Code style and typing
+
+- Use Ruff as the formatter and linter; do not hand-format around it.
+- Type public APIs and keep `mypy src tests scripts` and `pyrefly check` clean.
+- Preserve existing public imports and call signatures unless a compatibility plan is documented.
+- Keep optional features lazy: importing the base package must not require MCP or tray dependencies.
+- Do not add runtime dependencies when the standard library or an existing dependency is sufficient.
+- `_version.py` is the single version source. Do not duplicate the package version in `pyproject.toml` or service responses.
+
+To apply formatting during development:
+
+```bash
+python -m ruff format .
+python -m ruff check .
+```
+
+## Tests
+
+Add behavior-focused tests for every change. Tests must not use live credentials, external AI services, or arbitrary user databases.
+
+For relevant areas, cover:
+
+- Success, validation, and resource-cleanup paths
+- Incremental streaming and malformed/truncated input
+- Authentication precedence without exposing secret values
+- Service startup rollback, idempotent shutdown, socket/thread cleanup, and state ownership
+- Optional dependency present and absent behavior
+- Provider adapter text-only rejection rather than silent semantic loss
+
+Use `httpx.MockTransport`, Flask's test client, temporary paths, and injected fakes. Avoid assertions that only repeat implementation constants without exercising a contract.
+
+## Documentation and changelog
+
+Update README and focused docs whenever configuration, compatibility limitations, entry points, lifecycle behavior, or API envelopes change. Do not publish a static test-count claim; it becomes stale immediately. Add user-visible changes to `CHANGELOG.md` using semantic-versioning categories.
+
+## Pull requests
+
+1. Create a focused branch and make the smallest compatible change.
+2. Add meaningful tests and documentation.
+3. Run the full quality and distribution gates above.
+4. Include supported-OS/Python limitations and any unverified behavior in the pull-request description.
+5. Submit the pull request without generated temporary virtual environments or distribution-check directories.
+
+Be respectful and do not include credentials, database contents, or user prompts in issues, fixtures, logs, or screenshots.

kirox-1.1.0/LICENSE

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

kirox-1.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: kirox
+Version: 1.1.0
+Summary: Production-ready SDK for AI coding assistants with background service and system tray
+Project-URL: Homepage, https://github.com/idugeni/kirox
+Project-URL: Documentation, https://github.com/idugeni/kirox#readme
+Project-URL: Repository, https://github.com/idugeni/kirox
+Project-URL: Issues, https://github.com/idugeni/kirox/issues
+Author: Kirox Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,background-service,claude,coding-assistant,gpt,kiro,llm,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: flask<4,>=3.1.3
+Requires-Dist: httpx<0.29,>=0.28.1
+Provides-Extra: dev
+Requires-Dist: build==1.5.0; extra == 'dev'
+Requires-Dist: mypy==2.3.0; extra == 'dev'
+Requires-Dist: pyrefly==1.2.0; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: ruff==0.16.1; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28.1; extra == 'mcp'
+Provides-Extra: service
+Requires-Dist: pillow<13,>=12.3.0; extra == 'service'
+Requires-Dist: pystray<0.20,>=0.19.5; extra == 'service'
+Description-Content-Type: text/markdown
+
+# Kirox
+
+Kirox is a typed Python SDK and local HTTP bridge for AI coding-assistant workflows. It provides incremental AWS EventStream decoding, a synchronous client, managed local service and tray lifecycle, text-only OpenAI/Anthropic-compatible endpoints, and an optional MCP stdio server.
+
+Kirox deliberately binds its HTTP service to loopback addresses only. It is not a network-facing gateway and rejects `0.0.0.0` or other non-loopback hosts.
+
+## Requirements
+
+- Python 3.10 or newer; tested on 3.10–3.14
+- A Kiro-compatible bearer token or an authenticated supported CLI database
+- Windows, macOS, or Linux; tray support depends on the desktop environment
+
+## Installation
+
+```bash
+python -m pip install kirox                 # SDK, CLI, and local HTTP bridge
+python -m pip install "kirox[service]"      # Add pystray and Pillow
+python -m pip install "kirox[mcp]"          # Add the MCP SDK
+python -m pip install "kirox[service,mcp]"  # All optional features
+```
+
+The MCP dependency is optional and imported only by MCP operations. Running `kirox-mcp` without it exits with an instruction to install `kirox[mcp]`; importing `kirox.mcp.server` remains safe.
+
+## Authentication
+
+`AuthManager.resolve()` uses a deterministic precedence order:
+
+1. Explicit `token` / `profile_arn` arguments
+2. Configuration values
+3. `KIROX_TOKEN` / `KIROX_PROFILE_ARN`
+4. Backward-compatible `ASSISTANT_TOKEN` / `ASSISTANT_PROFILE_ARN` aliases
+5. An explicitly configured database, then fixed supported CLI database locations
+
+`KIROX_DB_PATH` and `ASSISTANT_DB_PATH` can select a database. Kirox does not scan arbitrary files or treat unrelated keys such as `OPENAI_API_KEY` as upstream credentials.
+
+## CLI and managed lifecycle
+
+```bash
+kirox                         # Same as `kirox run`
+kirox run --no-tray           # Service only
+kirox run --no-update         # Disable the background PyPI update check
+kirox status
+kirox stop                    # Authenticated graceful shutdown
+kirox stop --force            # Identity-verified PID fallback for unchanged state
+kirox models
+kirox chat --model auto
+kirox ask --model auto "Hello"
+kirox update
+```
+
+The service owns one client, refresh scheduler, HTTP server, state file, and optional tray. Startup rolls back partial resources; normal stop closes threads, sockets, state, and the client idempotently. Runtime control data is stored in `~/.kirox/service.json` with a per-process token and is accepted only over loopback. State also records a kernel-derived process identity, so `stop --force` terminates only a process that still matches the recorded owner and fails closed on mismatch, on missing identity, or where the platform cannot supply one.
+
+## Python API
+
+```python
+from kirox import AssistantClient
+
+with AssistantClient.auto() as client:
+    for event in client.chat("Explain this function", model_id="auto"):
+        if event.content:
+            print(event.content, end="", flush=True)
+```
+
+`AssistantClient.chat()` validates and decodes upstream EventStream frames incrementally, including both CRCs and frame/header bounds. Closing the generator early closes the HTTP response.
+
+## Local HTTP bridge
+
+Start the service and use `http://127.0.0.1:8420` (or the configured loopback port):
+
+```bash
+kirox run --no-tray
+
+curl http://127.0.0.1:8420/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}],"stream":true}'
+```
+
+Available routes include:
+
+- Native: `/health`, `/`, `/api/models`, `/api/chat`, `/api/token/status`
+- OpenAI-compatible: `/v1/models`, `/v1/chat/completions`
+- Anthropic-compatible: `/v1/messages`
+
+The provider adapters are intentionally **text-only**. They accept text strings or arrays of text blocks, preserve system/user/assistant history in a canonical transcript, require the final message to be from the user, and reject unsupported fields instead of silently ignoring them. Tools, tool calls, images, audio, metadata, sampling parameters, and other multimodal semantics are not supported. `max_tokens` is validated for compatibility but not enforced; responses carry an HTTP `Warning` and do not fabricate token usage.
+
+Streaming is incremental SSE. OpenAI streams terminate once with `[DONE]`; Anthropic streams use ordered message/content events and a single terminal event. Upstream and internal exception details are sanitized from HTTP responses.
+
+Requests must carry a loopback `Host` header, so a browser page on another origin cannot reach the bridge through DNS rebinding, and bodies larger than 1 MiB are rejected with HTTP 413 before validation or upstream work.
+
+See [API Reference](docs/api-reference.md) for the complete request contract.
+
+## MCP
+
+After installing the extra, configure an MCP client to launch the stdio command:
+
+```json
+{
+  "mcpServers": {
+    "kirox": {"command": "kirox-mcp"}
+  }
+}
+```
+
+The server exposes one `kirox_chat` tool with required non-empty `message` and optional non-empty `model` (default `auto`). Unknown tools, unknown arguments, and invalid values return errors. Synchronous client work runs in a worker thread so the MCP event loop stays responsive, and the owned client closes when the stdio session ends.
+
+## Configuration
+
+The default file is `~/.kirox/config.json`:
+
+```json
+{
+  "region": "us-east-1",
+  "server_host": "127.0.0.1",
+  "server_port": 8420,
+  "auto_refresh": true,
+  "refresh_interval": 3000,
+  "log_level": "INFO"
+}
+```
+
+Only loopback values are accepted for `server_host`. See [Configuration](docs/configuration.md) for all fields and environment aliases.
+
+## Development and release gates
+
+```bash
+python -m pip install -e ".[dev,mcp]"
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy src tests scripts
+python -m pyrefly check
+python -m pytest tests -q --cov=kirox --cov-branch --cov-report=term-missing
+python -m build
+python scripts/verify_distribution.py
+```
+
+Coverage is branch-aware and must remain at least 80%. Both type checkers run because they catch different classes of error; Pyrefly is configured explicitly in `pyproject.toml` so it does not silently fall back to its permissive `basic` preset. The distribution verifier checks `py.typed`, version metadata, both console scripts, then installs the wheel into a temporary clean virtual environment for import, CLI, missing-MCP, and `pip check` smoke tests.
+
+## Documentation
+
+- [Installation](docs/installation.md)
+- [Configuration](docs/configuration.md)
+- [API Reference](docs/api-reference.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT License. See [LICENSE](LICENSE).