docs: say how to replace an older install before specify init

README.md

@@ -79,6 +79,11 @@ specify init my-project --integration copilot
 cd my-project
 ```
 
+If Spec Kit is already installed, `uv tool install specify-cli` keeps the installed
+version. Compare the version shown by `specify version` with the
+[latest version on PyPI](https://pypi.org/project/specify-cli/), and if it's older,
+run `uv tool install --force specify-cli` before `specify init`.
+
 <a id="-supported-ai-coding-agent-integrations"></a>
 
 The examples use **GitHub Copilot's default skills mode**. Replace `copilot` with

docs/installation.md

@@ -50,6 +50,8 @@ pipx install specify-cli
 pip install specify-cli
 ```
 
+If `specify-cli` is already installed, these commands keep the installed version, even when a newer release exists. Compare the version shown by `specify version` with the [latest version on PyPI](https://pypi.org/project/specify-cli/). To replace an older install, use the same tool as the original install: `uv tool install --force specify-cli`, `pipx install --force specify-cli` or `pip install --upgrade specify-cli`. A different tool can install a second copy and leave the old `specify` first on `PATH`. An old CLI can't set up projects from current releases: with 0.1.6, for example, `specify init --integration ...` fails with `No such option: --integration`, and `specify init --ai ...` fails with `No matching release asset found`.
+
 To install a specific release, pin the version — for example `uv tool install specify-cli==0.12.11`. See the [PyPI installation guide](install/pypi.md) for details, including how to upgrade and how to [install from a custom or private package index](install/pypi.md#install-from-a-custom-or-private-package-index).
 
 ### One-time Usage