Document global CLI installation

CHANGELOG.md

@@ -7,6 +7,13 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Documentation
+
+- **Install docs now default to an isolated global CLI.** README, Getting Started, and generated
+  project onboarding recommend `uv tool install` or `pipx install` from the GitHub repo so users can
+  run `coding-scaffold` from any project without activating the source checkout's virtual
+  environment. The clone + editable install path remains documented for contributors.
+
 ## [0.5.1] — 2026-05-19
 
 ### Fixed

README.md

@@ -83,7 +83,34 @@ OpenRouter, GitHub Models, or another compatible provider.
 
 ## Install
 
-Recommended with uv:
+Recommended for using the CLI from any project:
+
+```bash
+uv tool install git+https://github.com/JRS1986/CodingScaffold.git
+```
+
+Then open the repo you want to prepare and run:
+
+```bash
+cd ~/dev/my-project
+coding-scaffold doctor --target .
+coding-scaffold pilot --target . --tool opencode
+```
+
+This installs `coding-scaffold` into an isolated tool environment and puts the command on your
+`PATH`, so you do not have to activate a virtual environment from the CodingScaffold source checkout
+before using it elsewhere.
+
+If you do not use `uv`, `pipx` gives the same global-command shape:
+
+```bash
+pipx install git+https://github.com/JRS1986/CodingScaffold.git
+```
+
+If your shell cannot find `coding-scaffold` after either command, follow the PATH prompt printed by
+`uv` or run `pipx ensurepath`, then restart the shell.
+
+For contributing to CodingScaffold itself, clone the repo and use the development environment:
 
 ```bash
 git clone https://github.com/JRS1986/CodingScaffold.git

docs/docs/wiki/Getting-Started.md

@@ -50,7 +50,34 @@ runtime, an authenticated CLI, or a cloud/API provider.
 
 ## Install
 
-Recommended with uv:
+Recommended for using the CLI from any project:
+
+```bash
+uv tool install git+https://github.com/JRS1986/CodingScaffold.git
+```
+
+Then open the repo you want to prepare and run:
+
+```bash
+cd ~/dev/my-project
+coding-scaffold doctor --target .
+coding-scaffold pilot --target . --tool opencode
+```
+
+This installs `coding-scaffold` into an isolated tool environment and puts the command on your
+`PATH`, so you do not have to activate a virtual environment from the CodingScaffold source checkout
+before using it elsewhere.
+
+If you do not use `uv`, `pipx` gives the same global-command shape:
+
+```bash
+pipx install git+https://github.com/JRS1986/CodingScaffold.git
+```
+
+If your shell cannot find `coding-scaffold` after either command, follow the PATH prompt printed by
+`uv` or run `pipx ensurepath`, then restart the shell.
+
+For contributing to CodingScaffold itself, clone the repo and use the development environment:
 
 ```bash
 git clone https://github.com/JRS1986/CodingScaffold.git
@@ -76,7 +103,10 @@ On Windows PowerShell outside WSL:
 .venv\Scripts\Activate.ps1
 ```
 
-`uv.lock` is committed. Use `uv sync --extra dev` for reproducible development and CI parity.
+Optional RouteLLM dependencies can be installed with `uv sync --extra dev --extra routellm` or
+`python -m pip install -e ".[dev,routellm]"`.
+
+`uv.lock` is committed. Use `uv sync --extra dev` for reproducible local development and CI parity.
 
 ## Prepare A Project
 

src/coding_scaffold/writers.py

@@ -751,25 +751,24 @@ def _getting_started_md(intake: IntakeAnswers, routing: RoutingPlan) -> str:
     )
     return f"""# Getting Started
 
-This scaffold is meant to be cloned, installed into a local venv, and run as guided setup inside
-the project you want to prepare for AI-assisted coding.
+CodingScaffold is meant to be installed once as a global command, then run inside whichever project
+you want to prepare for AI-assisted coding.
 
 The goal is not just "better autocomplete." The goal is a controlled workflow where agents inspect,
 plan, edit, verify, review, and preserve the best team habits as reusable skills.
 
 ## Fast Path
 
 ```bash
-git clone <this-repo> coding-scaffold
-cd coding-scaffold
-uv venv
-source .venv/bin/activate
-uv sync --extra dev
+uv tool install git+https://github.com/JRS1986/CodingScaffold.git
 coding-scaffold setup run --target /path/to/your/project
 ```
 
-On WSL/Linux the flow is the same. On Windows PowerShell outside WSL, activate with
-`.venv\\Scripts\\Activate.ps1`.
+If you do not use `uv`, install the same isolated command with
+`pipx install git+https://github.com/JRS1986/CodingScaffold.git`.
+
+After installation, run `coding-scaffold` from the project you are preparing. You should not need
+to activate a virtual environment from the CodingScaffold source checkout.
 
 ## What Setup Did Here
 

tests/test_writers.py

@@ -39,6 +39,24 @@ def test_write_scaffold_creates_expected_files(tmp_path, scaffold_inputs) -> Non
     assert ".coding-scaffold/AGENTS.md" in version["files"]
 
 
+def test_generated_getting_started_uses_global_cli_install(tmp_path, scaffold_inputs) -> None:
+    fixture = scaffold_inputs(tool=None)
+    write_scaffold(
+        tmp_path,
+        fixture.intake,
+        fixture.hardware,
+        fixture.providers,
+        fixture.routing,
+    )
+
+    text = (tmp_path / ".coding-scaffold" / "GETTING_STARTED.md").read_text(encoding="utf-8")
+    assert "uv tool install git+https://github.com/JRS1986/CodingScaffold.git" in text
+    assert "pipx install git+https://github.com/JRS1986/CodingScaffold.git" in text
+    assert "source .venv/bin/activate" not in text
+    assert "should not need" in text
+    assert "activate a virtual environment" in text
+
+
 def test_providers_json_redacts_azure_endpoint(tmp_path, monkeypatch, scaffold_inputs) -> None:
     from coding_scaffold.providers import detect_providers