tempest-cli 0.1.0__tar.gz → 0.3.0__tar.gz

tempest_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to **tempest-cli** are listed below.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-08-15
+
+### Changed
+
+- **`ruff` now ships with the package.** It moved from the `[tools]`
+  extra into the runtime dependencies, so `uv add --dev tempest-cli` is
+  enough for `lint`, `fix`, `format` and `fmt-check` to run — no second
+  install, and no dependency on `uv` being around to fetch one. The cost
+  is nil: ruff is a static binary wheel with no Python dependencies of
+  its own, so no bound of its reaches a consumer's resolution.
+
+  `mypy` and `pytest` stay out on purpose. A mypy bump changes which
+  errors a codebase reports and pytest has to match the suite and its
+  plugins — those are the project's call. `[tools]` now installs exactly
+  those two.
+
+- **The project's environment is searched before the CLI's own.** With
+  ruff bundled, the CLI's environment always has one; looking there
+  first would silently override a version the project pinned whenever
+  `tempest-cli` is installed apart from it (`uv tool install`, pipx).
+  The order is now `$VIRTUAL_ENV` → nearest `.venv` → the CLI's own
+  environment → `PATH` → `uv run --with`.
+
+## [0.2.0] — 2026-08-15
+
+### Added
+
+- **`tc`, the short alias.** The package now installs a second console
+  script pointing at the same entry point, so `tc check` is `tempest-cli
+  check`. While the installing environment is on `PATH`, `tc` shadows
+  iproute2's `tc(8)`; call the traffic controller as `/usr/sbin/tc` when
+  you need it.
+
+### Fixed
+
+- **The gate no longer runs a dead pyenv/asdf shim.** `tempest-cli fix`
+  in a project whose environment has no ruff answered `pyenv: ruff:
+  command not found` and exited 127 — the lookup took the first `PATH`
+  hit, and on a version-manager machine that hit is a shim that exists
+  for every tool any installed interpreter ever provided. The lookup now
+  searches the environments that belong to the run first (the CLI's own
+  interpreter directory, `$VIRTUAL_ENV`, the nearest `.venv`), accepts a
+  shim only after `<tool> --version` proves it dispatches, and applies
+  the same check to `uv` itself.
+
+- **The `uv` fallback stopped leaking back to `PATH`.** It ran `uv run
+  <tool>`, which falls back to `PATH` when the project environment has
+  no such tool — landing on the very shim that had just been rejected.
+  It is now `uv run --with <tool> <tool>`, so the tool is always present
+  in the run's overlay; a version pinned by the project still wins,
+  since uv resolves the overlay against the project's requirements.
+
+- **The 127 message names the fix.** It now says what to install
+  (`uv add --dev ruff`, or `"tempest-cli[tools]"` for the set) instead
+  of only reporting that `PATH` and `uv` came up empty.
+
+## [0.1.0] — 2026-08-15
+
+First release. Extracted from
+[`tempest-fastapi-sdk`](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk),
+where the same gate shipped as `tempest check` — reachable only by
+installing a FastAPI SDK.
+
+### Added
+
+- **The quality gate**: `lint`, `fix`, `format`, `fmt-check`, `type`,
+  `test` and `check`, over `ruff` / `mypy` / `pytest`. Each returns the
+  underlying tool's exit code; `check` runs the four in order and stops
+  at the first failure.
+
+- **Typing strictness as configuration**, read from `[tool.tempest]
+  typing_strictness` in `pyproject.toml` (`lenient` | `standard` |
+  `strict`, defaulting to `standard`), with a `--strictness` / `-s`
+  override per run. Levels only ever **add** flags on top of the
+  project's own `[tool.ruff]` / `[tool.mypy]`. `ANN401` is never enabled
+  at any level: `Any` is a legitimate annotation.
+
+- **`pr-prompt`** — builds the prompt that makes an AI write a branch's
+  pull-request description, carrying the repository's own PR template
+  (or a bundled PT-BR / EN-US default), the rules that stop a model from
+  returning the template unfilled, and the branch context read as
+  `base...head`.
+
+- **A library surface**: `run_full_check`, `run_ruff_check`,
+  `run_ruff_fix`, `run_ruff_format`, `run_mypy`, `run_pytest`,
+  `load_tempest_config`, `find_pyproject`, `generate_pr_prompt`.
+
+- **`register_commands(app)`** mounts the whole gate onto an existing
+  `typer.Typer`, so another CLI exposes these commands under its own
+  name without copying a body. `tempest-fastapi-sdk` uses exactly this,
+  which is what keeps `tempest check` and `tempest-cli check` identical.
+
+### Notes
+
+- The only runtime dependency is `typer`. `ruff`, `mypy` and `pytest`
+  are invoked from the active environment (or through `uv run` when they
+  are not on `PATH`), so the project pins the versions it wants. The
+  `[tools]` extra installs all three for whoever prefers that.
+- Measured against the SDK it came from: reaching these commands there
+  loaded 38.7 MB of dependencies and about 0.5 s of import time per
+  invocation — for four commands that touch none of it. A test in this
+  package asserts that importing it pulls no web framework.

{tempest_cli-0.1.0 → tempest_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Framework-agnostic quality gate for Python projects: ruff + mypy + pytest behind one command, with a typing-strictness dial and a PR-description prompt generator.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-cli
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-cli
@@ -22,11 +22,11 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: ruff>=0.8.0
 Requires-Dist: typer>=0.12.0
 Provides-Extra: tools
 Requires-Dist: mypy>=1.13.0; extra == 'tools'
 Requires-Dist: pytest>=8.3.3; extra == 'tools'
-Requires-Dist: ruff>=0.8.0; extra == 'tools'
 Description-Content-Type: text/markdown
 
 # tempest-cli
@@ -42,7 +42,8 @@ One command for the quality gate of any Python project — `ruff` +
 `pyproject.toml` instead of in four different Makefile targets.
 
 Framework-agnostic on purpose: Django, Flask, Litestar, FastAPI, a
-library, a script. The only runtime dependency is `typer`.
+library, a script. It brings `ruff` along, so the gate runs the moment
+you install it; `typer` is the only other runtime dependency.
 
 ```bash
 uv add --dev tempest-cli
@@ -50,6 +51,8 @@ uv add --dev tempest-cli
 tempest-cli check          # lint + fmt-check + type + test, in order, stops at the first failure
 tempest-cli fix            # every ruff autofix, then format
 tempest-cli type -s strict # override the configured strictness for one run
+
+tc check                   # `tc` is the short alias for the same program
 ```
 
 ## Why it exists
@@ -139,16 +142,33 @@ cli: typer.Typer = typer.Typer(name="mytool")
 register_commands(cli)
 ```
 
-## Installing the tools
+## Where the tools come from
+
+**`ruff` comes with the package** — six of the eight commands are ruff,
+so `lint`, `fix`, `format` and `fmt-check` work straight after
+`uv add --dev tempest-cli`, with nothing else to install. It is a static
+binary wheel with no Python dependencies of its own, so nothing of its
+propagates into your resolution.
 
-`tempest-cli` shells out to whatever `ruff`, `mypy` and `pytest` it
-finds — it does not pin them, so your project chooses the versions. To
-install them alongside it:
+`mypy` and `pytest` are deliberately left to you — a mypy bump changes
+which errors your code reports, and pytest has to match your plugins and
+your suite. Add them yourself, or take the bundle:
 
 ```bash
 uv add --dev "tempest-cli[tools]"
 ```
 
+Whatever you pin wins over the bundled ruff. The lookup runs in this
+order:
+
+1. the project's environment — `$VIRTUAL_ENV`, then the nearest `.venv`
+   up the tree;
+2. the environment `tempest-cli` itself runs from (where the bundled
+   ruff lives);
+3. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
+   that answers `pyenv: ruff: command not found`);
+4. `uv run --with <tool> <tool>`, when `uv` is available.
+
 ## Relationship with tempest-fastapi-sdk
 
 This package was extracted from

{tempest_cli-0.1.0 → tempest_cli-0.3.0}/README.md

@@ -11,7 +11,8 @@ One command for the quality gate of any Python project — `ruff` +
 `pyproject.toml` instead of in four different Makefile targets.
 
 Framework-agnostic on purpose: Django, Flask, Litestar, FastAPI, a
-library, a script. The only runtime dependency is `typer`.
+library, a script. It brings `ruff` along, so the gate runs the moment
+you install it; `typer` is the only other runtime dependency.
 
 ```bash
 uv add --dev tempest-cli
@@ -19,6 +20,8 @@ uv add --dev tempest-cli
 tempest-cli check          # lint + fmt-check + type + test, in order, stops at the first failure
 tempest-cli fix            # every ruff autofix, then format
 tempest-cli type -s strict # override the configured strictness for one run
+
+tc check                   # `tc` is the short alias for the same program
 ```
 
 ## Why it exists
@@ -108,16 +111,33 @@ cli: typer.Typer = typer.Typer(name="mytool")
 register_commands(cli)
 ```
 
-## Installing the tools
+## Where the tools come from
+
+**`ruff` comes with the package** — six of the eight commands are ruff,
+so `lint`, `fix`, `format` and `fmt-check` work straight after
+`uv add --dev tempest-cli`, with nothing else to install. It is a static
+binary wheel with no Python dependencies of its own, so nothing of its
+propagates into your resolution.
 
-`tempest-cli` shells out to whatever `ruff`, `mypy` and `pytest` it
-finds — it does not pin them, so your project chooses the versions. To
-install them alongside it:
+`mypy` and `pytest` are deliberately left to you — a mypy bump changes
+which errors your code reports, and pytest has to match your plugins and
+your suite. Add them yourself, or take the bundle:
 
 ```bash
 uv add --dev "tempest-cli[tools]"
 ```
 
+Whatever you pin wins over the bundled ruff. The lookup runs in this
+order:
+
+1. the project's environment — `$VIRTUAL_ENV`, then the nearest `.venv`
+   up the tree;
+2. the environment `tempest-cli` itself runs from (where the bundled
+   ruff lives);
+3. `PATH`, skipping a pyenv/asdf shim that dispatches nowhere (the one
+   that answers `pyenv: ruff: command not found`);
+4. `uv run --with <tool> <tool>`, when `uv` is available.
+
 ## Relationship with tempest-fastapi-sdk
 
 This package was extracted from

tempest_cli-0.3.0/docs/changelog.en.md

@@ -0,0 +1,71 @@
+# Changelog
+
+The full history lives in the repository's
+[`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md).
+
+## [0.3.0] — 2026-08-15
+
+### Changed
+
+- **`ruff` now ships with the package.** It left the `[tools]` extra for
+  the runtime dependencies, so `uv add --dev tempest-cli` is enough for
+  `lint`, `fix`, `format` and `fmt-check` to run. The cost is nil: ruff
+  is a static binary wheel with no Python dependencies of its own, so no
+  bound of its reaches a consumer's resolution. `mypy` and `pytest` stay
+  out on purpose; `[tools]` now installs exactly those two.
+- **The project's environment is searched before the CLI's own.** With
+  ruff bundled, the CLI's environment always has one — looking there
+  first would silently override a version the project pinned whenever
+  `tempest-cli` lives apart from it (`uv tool install`, pipx). The order
+  is now `$VIRTUAL_ENV` → nearest `.venv` → the CLI's environment →
+  `PATH` → `uv run --with`.
+
+## [0.2.0] — 2026-08-15
+
+### Added
+
+- **`tc`**, a short alias installed next to `tempest-cli` — the same
+  program. While the installing environment is on `PATH` it shadows
+  iproute2's `tc(8)` (call `/usr/sbin/tc` for the network one).
+
+### Fixed
+
+- **The gate no longer runs a dead pyenv/asdf shim.** `tempest-cli fix`
+  in a project without ruff answered `pyenv: ruff: command not found`
+  and exited 127. The lookup now searches the run's own environments
+  first (the CLI's interpreter directory, `$VIRTUAL_ENV`, the nearest
+  `.venv`) and accepts a shim only after `<tool> --version` proves it
+  dispatches — the same check applies to `uv` itself.
+- **The `uv` fallback stopped leaking back to `PATH`.** It was `uv run
+  <tool>`, which falls back to `PATH` when the project environment has
+  no such tool — landing on the shim just rejected. It is now `uv run
+  --with <tool> <tool>`.
+- **The 127 message names the fix** (`uv add --dev ruff`, or
+  `"tempest-cli[tools]"` for the set).
+
+## [0.1.0] — 2026-08-15
+
+First release. Extracted from
+[`tempest-fastapi-sdk`](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk),
+where the same gate shipped as `tempest check` — reachable only by
+installing a FastAPI SDK.
+
+### Added
+
+- The gate: `lint`, `fix`, `format`, `fmt-check`, `type`, `test` and
+  `check`.
+- Typing strictness through `[tool.tempest] typing_strictness`, with a
+  `--strictness` override per run.
+- `pr-prompt` — the prompt that makes an AI write the PR description.
+- A library surface (`run_full_check`, `load_tempest_config`,
+  `generate_pr_prompt`, …) and `register_commands(app)` to mount the
+  gate on another CLI.
+
+### Notes
+
+- The only runtime dependency is `typer`. The tools come from the
+  project environment.
+- Measured against the SDK it came from: reaching these commands there
+  loaded 38.7 MB of dependencies and ~0.5 s of import time per
+  invocation. A test in this package asserts that importing it pulls no
+  web framework.

tempest_cli-0.3.0/docs/changelog.md

@@ -0,0 +1,71 @@
+# Changelog
+
+O histórico completo vive no
+[`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-cli/blob/main/CHANGELOG.md)
+do repositório.
+
+## [0.3.0] — 2026-08-15
+
+### Mudado
+
+- **O `ruff` agora vem junto com o pacote.** Saiu do extra `[tools]` e
+  virou dependência: `uv add --dev tempest-cli` já basta para `lint`,
+  `fix`, `format` e `fmt-check` rodarem. Custo zero — o ruff é binário
+  estático, sem dependência Python, então nenhum limite dele entra na
+  resolução de quem instala. `mypy` e `pytest` continuam de fora de
+  propósito; `[tools]` agora instala exatamente esses dois.
+- **O ambiente do projeto passa a ser procurado antes do da CLI.** Com o
+  ruff embutido, o ambiente da CLI sempre tem um — procurar ali primeiro
+  sobrescreveria em silêncio a versão que o projeto fixou quando o
+  `tempest-cli` mora fora dele (`uv tool install`, pipx). A ordem agora é
+  `$VIRTUAL_ENV` → `.venv` mais próximo → ambiente da CLI → `PATH` →
+  `uv run --with`.
+
+## [0.2.0] — 2026-08-15
+
+### Adicionado
+
+- **`tc`**, apelido curto instalado ao lado de `tempest-cli` — mesmo
+  programa. Enquanto o ambiente instalador estiver no `PATH`, ele
+  sombreia o `tc(8)` do iproute2 (chame `/usr/sbin/tc` para o de rede).
+
+### Corrigido
+
+- **O gate não roda mais um shim morto do pyenv/asdf.** `tempest-cli
+  fix` num projeto sem ruff respondia `pyenv: ruff: command not found` e
+  saía 127. A busca agora tenta primeiro os ambientes da execução
+  (diretório do interpretador da CLI, `$VIRTUAL_ENV`, `.venv` mais
+  próximo) e só aceita um shim depois que `<ferramenta> --version` prova
+  que ele despacha — o mesmo vale para o próprio `uv`.
+- **O fallback do `uv` parou de vazar para o `PATH`.** Era `uv run
+  <ferramenta>`, que cai no `PATH` quando o ambiente do projeto não tem
+  a ferramenta — voltando ao shim recém-rejeitado. Agora é `uv run
+  --with <ferramenta> <ferramenta>`.
+- **A mensagem do 127 diz o que instalar** (`uv add --dev ruff`, ou
+  `"tempest-cli[tools]"` para as três).
+
+## [0.1.0] — 2026-08-15
+
+Primeira versão. Extraída do
+[`tempest-fastapi-sdk`](https://github.com/mauriciobenjamin700/tempest-fastapi-sdk),
+onde o mesmo gate era o `tempest check` — alcançável só instalando um SDK
+de FastAPI.
+
+### Adicionado
+
+- O gate: `lint`, `fix`, `format`, `fmt-check`, `type`, `test` e
+  `check`.
+- Rigor de tipagem por `[tool.tempest] typing_strictness`, com override
+  `--strictness` por execução.
+- `pr-prompt` — o prompt que faz uma IA escrever a descrição do PR.
+- Superfície de biblioteca (`run_full_check`, `load_tempest_config`,
+  `generate_pr_prompt`, …) e `register_commands(app)` para montar o gate
+  em outra CLI.
+
+### Notas
+
+- Única dependência de runtime: `typer`. As ferramentas vêm do ambiente
+  do projeto.
+- Medido contra o SDK de origem: chegar nesses comandos lá carregava
+  38,7 MB de dependências e ~0,5 s de import por invocação. Um teste
+  deste pacote garante que importá-lo não puxa framework web nenhum.

{tempest_cli-0.1.0 → tempest_cli-0.3.0}/docs/commands.en.md

@@ -14,6 +14,11 @@ tool's exit code.
 | `check` | the four above, in order, stopping at the first failure |
 | `pr-prompt` | builds the PR-description prompt — [its own page](pr-prompt.md) |
 
+!!! tip "`tc` is the short form"
+    The package installs `tempest-cli` and `tc` pointing at the same
+    program. The examples use the long name; `tc check`, `tc fix` and
+    `tc type -s strict` work exactly the same.
+
 ## The full gate
 
 ```bash
@@ -63,8 +68,11 @@ The exit code is the tool's own, untranslated:
 tempest-cli lint; echo "exited $?"
 ```
 
-There is exactly one code of its own: **127**, when the tool is not on
-`PATH` and `uv` is not either — the message then names what was missing.
+There is exactly one code of its own: **127**, when the tool is in none
+of the places the CLI looks — the run's environment, `PATH`, `uv run
+--with` — and the message then names what was missing and how to install
+it. The lookup order is in
+[Installation](installation.md#where-ruff-mypy-and-pytest-come-from).
 
 ## Recap
 

{tempest_cli-0.1.0 → tempest_cli-0.3.0}/docs/commands.md

@@ -14,6 +14,11 @@ saída da ferramenta por baixo.
 | `check` | os quatro acima, em ordem, parando na primeira falha |
 | `pr-prompt` | monta o prompt da descrição do PR — [página própria](pr-prompt.md) |
 
+!!! tip "`tc` é a forma curta"
+    O pacote instala `tempest-cli` e `tc` apontando para o mesmo
+    programa. Os exemplos usam o nome longo; `tc check`, `tc fix` e
+    `tc type -s strict` funcionam igual.
+
 ## O gate completo
 
 ```bash
@@ -63,8 +68,10 @@ O código de saída é o da ferramenta, sem tradução:
 tempest-cli lint; echo "saiu $?"
 ```
 
-Só há um código próprio: **127**, quando a ferramenta não está no `PATH`
-e o `uv` também não — aí a mensagem diz qual faltou.
+Só há um código próprio: **127**, quando a ferramenta não está em nenhum
+dos lugares onde a CLI procura — ambiente da execução, `PATH`, `uv run
+--with` — e aí a mensagem diz qual faltou e como instalá-la. A ordem de
+busca está em [Instalação](installation.md#de-onde-vem-o-ruff-o-mypy-e-o-pytest).
 
 ## Recap
 

{tempest_cli-0.1.0 → tempest_cli-0.3.0}/docs/index.en.md

@@ -5,11 +5,14 @@ and `pytest` — with the typing strictness living in `pyproject.toml`
 instead of spread across four Makefile targets.
 
 Framework-agnostic on purpose: Django, Flask, Litestar, FastAPI, a
-library, a script. The only runtime dependency is `typer`.
+library, a script. There are two runtime dependencies: `typer` and
+`ruff` — the latter ships along, so the gate runs the moment you install
+it.
 
 ```bash
 uv add --dev tempest-cli
 tempest-cli check
+tc check          # the same, through the short alias
 ```
 
 ```console

{tempest_cli-0.1.0 → tempest_cli-0.3.0}/docs/index.md

@@ -5,11 +5,14 @@ Um comando para o gate de qualidade de qualquer projeto Python — `ruff`,
 em vez de espalhado por quatro alvos de Makefile.
 
 Agnóstico de framework de propósito: Django, Flask, Litestar, FastAPI,
-uma biblioteca, um script. A única dependência de runtime é o `typer`.
+uma biblioteca, um script. As dependências de runtime são duas: o
+`typer` e o `ruff` — que já vem junto, para o gate rodar assim que
+instala.
 
 ```bash
 uv add --dev tempest-cli
 tempest-cli check
+tc check          # o mesmo, pelo apelido curto
 ```
 
 ```console

tempest_cli-0.3.0/docs/installation.en.md

@@ -0,0 +1,107 @@
+# Installation
+
+```bash
+uv add --dev tempest-cli
+```
+
+Or with pip:
+
+```bash
+pip install tempest-cli
+```
+
+Requires **Python 3.11+**. It brings `ruff` along — six of the eight
+commands are ruff, so the gate runs the moment the package installs. The
+other runtime dependency is `typer`.
+
+It installs **two executables**: `tempest-cli` and the short alias `tc`.
+They are the same program — everything in these docs applies to both.
+
+```bash
+tc check        # identical to tempest-cli check
+```
+
+!!! warning "`tc` is also iproute2's `tc(8)`"
+    While the environment that installed the package is on `PATH`, `tc`
+    resolves to this CLI. For Linux traffic control, call it by absolute
+    path (`/usr/sbin/tc`) — or use `tempest-cli` and leave `tc` alone.
+
+## Where ruff, mypy and pytest come from
+
+**`ruff` comes with the package**: install it and `lint`, `fix`,
+`format` and `fmt-check` already work — nothing else to install.
+
+```bash
+uv add --dev tempest-cli
+tempest-cli fix            # runs right away
+```
+
+`mypy` and `pytest` stay with you. A mypy bump changes which errors your
+code starts reporting, and pytest has to match your plugins and your
+suite — those versions are the project's call. Add them yourself, or
+take the bundle:
+
+```bash
+uv add --dev "tempest-cli[tools]"   # mypy + pytest
+```
+
+!!! question "Why ruff is a dependency and the other two are not"
+    Six of the eight commands are ruff — a `tempest-cli` without ruff is
+    a gate that cannot run. And it costs nothing: ruff is a static
+    binary with no Python dependencies at all, so no bound of its enters
+    your project's resolution. mypy and pytest, in contrast, run through
+    your code and your suite; pinning them here would be deciding for
+    you.
+
+### The lookup order
+
+What your project pins **wins** over the bundled ruff. The CLI runs the
+first thing it finds, in this order:
+
+1. **the project's environment** — `$VIRTUAL_ENV`, then the nearest
+   `.venv` up the tree;
+2. **the CLI's own environment** — where the bundled ruff lives;
+3. **`PATH`** — skipping a version-manager shim that dispatches nowhere
+   (see below);
+4. **`uv run --with <tool> <tool>`** when `uv` is available — the
+   project's environment plus the tool, with no activation and no prior
+   `uv sync` required.
+
+If nothing resolves, the command exits with **127**, naming the missing
+tool and how to install it, instead of raising a traceback.
+
+!!! info "Why `PATH` does not come first"
+    On a pyenv/asdf machine the `shims` directory is on `PATH`
+    globally and holds a stub for every tool any installed version ever
+    provided. Looking up `ruff` there finds `~/.pyenv/shims/ruff` even
+    when the project has no ruff at all — and running it prints
+    `pyenv: ruff: command not found`. So the run's own environments win
+    over `PATH`, and a shim is only accepted after proving it dispatches
+    (`<tool> --version` exiting `0`).
+
+## Verifying
+
+```bash
+tempest-cli --version
+tc --version          # the same program
+tempest-cli check --help
+```
+
+## In CI
+
+Every command returns the underlying tool's exit code, so the job reads
+it exactly as it would read `ruff` directly:
+
+```yaml
+- name: Quality gate
+  run: uv run tempest-cli check
+```
+
+## Recap
+
+- `uv add --dev tempest-cli`, Python 3.11+, `ruff` already included.
+- `mypy` and `pytest` are yours — or take `"tempest-cli[tools]"`.
+- Two executables: `tempest-cli` and the `tc` alias.
+- What the project pins beats the bundled ruff; then come `PATH` (never
+  a dead shim) and `uv run --with`.
+- A missing tool means exit 127 with a message, not a traceback.