Clarify uvx command usage in docs

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Clarified README and tutorial command examples so one-off `uvx` usage is not mixed with direct
+  `dbt-specify` commands unless the CLI is persistently installed.
+
 ## [1.2.0] — 2026-05-18
 
 ### Added

README.md

@@ -54,7 +54,7 @@ cd jaffle-shop
 
 uvx --from dbt-spec-kit dbt-specify init jaffle-shop --warehouse bigquery
 
-dbt-specify doctor
+uvx --from dbt-spec-kit dbt-specify doctor
 ```
 
 Then use your AI agent:
@@ -73,8 +73,12 @@ See the full walkthrough: [Jaffle-shop AI SDLC walkthrough](docs/jaffle-shop-ai-
 
 Requires Python 3.11+. Recommended via [uv](https://docs.astral.sh/uv/).
 
+Use `uvx` for one-off commands. `uvx` does not install a permanent `dbt-specify` command, so keep
+the `uvx --from dbt-spec-kit` prefix for each CLI call:
+
 ```bash
 uvx --from dbt-spec-kit dbt-specify init my-project --warehouse snowflake
+uvx --from dbt-spec-kit dbt-specify doctor
 ```
 
 From GitHub source for development builds:
@@ -89,8 +93,11 @@ Persistent install:
 ```bash
 uv tool install dbt-spec-kit
 dbt-specify --version
+dbt-specify doctor
 ```
 
+Use the persistent install when you want to run `dbt-specify` directly from your shell.
+
 Supported warehouse presets: `snowflake`, `databricks`, `trino`, `bigquery`, `redshift`,
 `postgres`, `sqlserver`, `azure-sql`, `mysql`, `duckdb`, `motherduck`, and `athena`.
 
@@ -160,6 +167,9 @@ dbt-specify validate dbt --manifest target/manifest.json
 dbt-specify report --format markdown
 ```
 
+If you did not install the CLI persistently, run the `dbt-specify` commands above with
+`uvx --from dbt-spec-kit dbt-specify ...`.
+
 Use `dbt-specify ci` when the lifecycle and dbt artifact checks should block a PR.
 
 ## Who this is for

docs/getting-started.md

@@ -26,6 +26,14 @@ Verify:
 dbt-specify --version
 ```
 
+Use this persistent install when you want to run `dbt-specify` directly. If you choose one-off
+`uvx` commands instead, prefix every dbt-spec-kit CLI call with `uvx --from dbt-spec-kit`:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify --version
+uvx --from dbt-spec-kit dbt-specify doctor
+```
+
 ## Initialize in your dbt project
 
 ```bash

docs/jaffle-shop-ai-sdlc-walkthrough.md

@@ -59,7 +59,7 @@ For Snowflake, Databricks, or Trino, replace `bigquery` with the matching preset
 Run the brownfield diagnostic:
 
 ```bash
-dbt-specify doctor
+uvx --from dbt-spec-kit dbt-specify doctor
 ```
 
 Expected result: doctor reports adoption status for `.dbt-specify/`, `.dbt-specify/agents/`,
@@ -134,12 +134,14 @@ ahead to unrelated model cleanup.
 Before review, run:
 
 ```bash
-dbt-specify validate project
+uvx --from dbt-spec-kit dbt-specify validate project
 dbt parse
-dbt-specify validate dbt --manifest target/manifest.json
-dbt-specify report --format markdown > dbt-specify-report.md
+uvx --from dbt-spec-kit dbt-specify validate dbt --manifest target/manifest.json
+uvx --from dbt-spec-kit dbt-specify report --format markdown > dbt-specify-report.md
 ```
 
+If you installed with `uv tool install dbt-spec-kit`, the direct `dbt-specify` command is equivalent.
+
 Then ask the agent:
 
 ```text

docs/tutorials/01-initialize-a-dbt-repo.md

@@ -10,17 +10,23 @@ This tutorial adds dbt-spec-kit to an existing dbt project and explains what cha
 
 ## 1. Install the CLI
 
-Use `uvx` for a one-time run:
+For tutorials and daily use, install the CLI as a persistent tool:
+
+```bash
+uv tool install dbt-spec-kit
+dbt-specify --version
+```
+
+Use `uvx` only for one-time commands. `uvx` does not install a permanent `dbt-specify` command:
 
 ```bash
 uvx --from dbt-spec-kit dbt-specify --version
 ```
 
-Or install it as a persistent tool:
+If you choose `uvx`, keep the prefix on every dbt-spec-kit command:
 
 ```bash
-uv tool install dbt-spec-kit
-dbt-specify --version
+uvx --from dbt-spec-kit dbt-specify doctor
 ```
 
 ## 2. Initialize your dbt project

docs/tutorials/02-jaffle-shop-change.md

@@ -29,9 +29,12 @@ use jaffle-shop for BigQuery demos:
 
 ```bash
 uvx --from dbt-spec-kit dbt-specify init jaffle-shop --warehouse bigquery
-dbt-specify doctor
+uvx --from dbt-spec-kit dbt-specify doctor
 ```
 
+If you installed the CLI with `uv tool install dbt-spec-kit`, you can use `dbt-specify doctor`
+directly instead.
+
 ## 3. Start from a business request
 
 Ask your agent:
@@ -94,10 +97,10 @@ It still runs tasks sequentially and stops if validation fails or the file scope
 Run:
 
 ```bash
-dbt-specify validate project
+uvx --from dbt-spec-kit dbt-specify validate project
 dbt parse
-dbt-specify validate dbt --manifest target/manifest.json
-dbt-specify report --format markdown
+uvx --from dbt-spec-kit dbt-specify validate dbt --manifest target/manifest.json
+uvx --from dbt-spec-kit dbt-specify report --format markdown
 ```
 
 Then ask:

tests/test_docs.py

@@ -146,6 +146,21 @@ def test_readme_highlights_enterprise_adoption_choices() -> None:
     assert "not as nested folders" in readme
 
 
+def test_uvx_command_examples_are_clear() -> None:
+    readme = (ROOT / "README.md").read_text()
+    getting_started = (ROOT / "docs" / "getting-started.md").read_text()
+    jaffle_tutorial = (ROOT / "docs" / "tutorials" / "02-jaffle-shop-change.md").read_text()
+    jaffle_walkthrough = (ROOT / "docs" / "jaffle-shop-ai-sdlc-walkthrough.md").read_text()
+
+    assert "does not install a permanent `dbt-specify` command" in readme
+    assert "uvx --from dbt-spec-kit dbt-specify doctor" in readme
+    assert "prefix every dbt-spec-kit CLI call" in getting_started
+    assert "uvx --from dbt-spec-kit dbt-specify doctor" in jaffle_tutorial
+    assert "uvx --from dbt-spec-kit dbt-specify validate project" in jaffle_tutorial
+    assert "uvx --from dbt-spec-kit dbt-specify doctor" in jaffle_walkthrough
+    assert "direct `dbt-specify` command is equivalent" in jaffle_walkthrough
+
+
 def test_tutorials_cover_enterprise_onboarding_path() -> None:
     tutorials_dir = ROOT / "docs" / "tutorials"
     required_paths = [