docs: Add uv installation guide and inline callouts (#2465)

* Initial plan

* docs: Add uv installation guide and inline callouts

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/027c81a0-57f2-4f67-ab54-4c72f93eb254

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* docs: improve uv install guide PATH and Windows instructions

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/f56bcfb8-2cf5-44a5-b5e5-0fd6c3caa46f

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* docs: clarify uv note in README applies only to uv commands not pipx

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/a6ada1f7-522d-4a31-ac5b-880e763f9c97

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

* docs: clarify uv note in installation.md applies only to uvx commands not pipx

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/4ec791dd-b048-4606-8db3-671bc8956b05

Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

README.md

@@ -56,6 +56,9 @@ Choose your preferred installation method:
 
 Install once and use everywhere. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
 
+> [!NOTE]
+> The `uv tool install` commands below require **[uv](https://docs.astral.sh/uv/)** — a fast Python package manager. If you see `command not found: uv`, [install uv first](./docs/install/uv.md). The `pipx` alternative does not require uv.
+
 ```bash
 # Install a specific stable release (recommended — replace vX.Y.Z with the latest tag)
 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

docs/install/uv.md

@@ -0,0 +1,60 @@
+# Installing uv
+
+[uv](https://docs.astral.sh/uv/) is a fast Python package manager by [Astral](https://astral.sh/). Spec Kit uses `uv` (via `uvx` or `uv tool install`) to run the `specify` CLI without polluting your global Python environment.
+
+> [!NOTE]
+> **Already have uv?** Run `uv --version` to confirm it is installed, then head back to the [Installation Guide](../installation.md).
+
+## Installation
+
+### macOS and Linux — Standalone Installer
+
+The quickest way to install uv on macOS or Linux is the official shell script:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+After the script finishes, follow any instructions printed by the installer to add uv to your `PATH`, then open a new terminal.
+
+### Windows — Standalone Installer
+
+Run the following in **Command Prompt or PowerShell**:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+After the script finishes, open a new terminal so the `uv` binary is on your `PATH`.
+
+### macOS — Homebrew
+
+```bash
+brew install uv
+```
+
+### Windows — WinGet
+
+```powershell
+winget install --id=astral-sh.uv -e
+```
+
+### Windows — Scoop
+
+```powershell
+scoop install uv
+```
+
+## Verification
+
+Confirm that uv is installed and on your `PATH`:
+
+```bash
+uv --version
+```
+
+You should see output similar to `uv 0.x.y (...)`.
+
+## Further Reading
+
+For advanced options (self-update, proxy settings, uninstall, etc.) see the official [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).

docs/installation.md

@@ -16,6 +16,9 @@
 
 The easiest way to get started is to initialize a new project. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
 
+> [!NOTE]
+> The `uvx` commands below require **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uvx`, [install uv first](./install/uv.md). The `pipx` alternative does not require uv.
+
 ```bash
 # Install from a specific stable release (recommended — replace vX.Y.Z with the latest tag)
 uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>

docs/toc.yml

@@ -11,6 +11,8 @@
       href: quickstart.md
     - name: Upgrade
       href: upgrade.md
+    - name: Install uv
+      href: install/uv.md
 
 # Reference
 - name: Reference