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

[kartsan03]

Description

In #4994 a fresh-looking install of specify-cli reports CLI 0.1.6, and specify init fails with No such option: --integration, then No matching release asset found for claude. The README tells you to run uv tool install specify-cli, and when specify-cli is already installed, that command keeps the installed version. uv still exits 0 and prints Installed 1 executable: specify, so it looks like it worked. uv tool upgrade specify-cli doesn't help either when the old install came from a Git tag. PyPI's oldest specify-cli release is 0.9.4, so 0.1.6 must be an earlier Git install that was left in place.

Reproduced with uv 0.12.21, using a scratch UV_TOOL_DIR/UV_TOOL_BIN_DIR:

$ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.1.6
$ specify version               # CLI Version 0.1.6
$ uv tool install specify-cli   # exit 0: "Checked 22 packages ... Installed 1 executable: specify"
$ specify version               # CLI Version 0.1.6
$ uv tool upgrade specify-cli   # "Nothing to upgrade"
$ specify init demo --integration claude
No such option: --integration
$ specify init demo --ai claude --script sh --ignore-agent-tools
No matching release asset found for claude (expected pattern: spec-kit-template-claude-sh)
Initialization failed: 1
$ uv tool install --force specify-cli
$ specify version               # CLI Version 1.2.1

The same happens over a PyPI install: with 1.1.3 installed, uv tool install specify-cli keeps 1.1.3. pipx install specify-cli keeps it too (it does say to pass --force), and pip install specify-cli stops at Requirement already satisfied.

This PR adds that to the two places that show the install commands:

• README.md, under the Get started commands: if Spec Kit is already installed, check specify version and reinstall with uv tool install --force specify-cli before specify init.
• docs/installation.md, under "Install from PyPI": the same, with the pipx and pip equivalents (the commands docs/install/pypi.md already gives for upgrades), plus the two error messages an old CLI prints, so the page can be found by searching for them.

Docs only, +6 lines. Refs #4994

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

I didn't run the test suite, since nothing outside the two Markdown files changed. I ran every command in the description, plus the 1.1.3, pipx and pip cases, against PyPI and GitHub with uv 0.12.21, each in its own scratch tool directory.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Claude Code (model: claude-opus-5-5, default reasoning effort, autonomous) reproduced the install behaviour with uv, pipx and pip, wrote the docs change and this description, and made the commit (it carries an Assisted-by trailer). Extent: docs only.

[Copilot]

🟡 Changes recommended

The replacement guidance should specify using the package manager that created the existing installation.

1 open issue

• Use the same package manager to replace the existing installation · New

What changed in this PR

Documents how to replace an older Specify CLI installation before initializing Spec Kit projects.

Changes:

• Adds a version check and forced reinstall guidance to the README.
• Documents package-manager equivalents and recognizable old-CLI errors.

File	Description
README.md	Adds replacement guidance before specify init.
docs/​installation.md	Adds upgrade commands and troubleshooting symptoms.

_{Review effort: Max}

[mnriem]

Please address Copilot feedback

[kartsan03]

Addressed Copilot's finding in 7bab9c8. The sentence on replacing an older install now says to use the same tool as the original install, since a different tool can install a second copy and leave the old specify first on PATH. That matches the Upgrade section of docs/install/pypi.md. Docs only; markdownlint passes on the file.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-opus-5-5, autonomous). The docs change was made by Codex CLI (model: gpt-6.1-sol, autonomous) and reviewed by Claude Code.

[Copilot]

🟢 Approval recommended

The documentation matches existing upgrade guidance, with only optional editorial refinements remaining.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Clarify CLI version comparison with the latest PyPI release

README.md:83

Optional: clarify what to compare the installed version against. specify version reports the installed CLI version, but does not say whether it is current. Both “if it's older” here and “Run specify version to check” in docs/installation.md:53 leave that comparison implicit. Link to the latest specify-cli release on PyPI in both notes and ask readers to compare its version with the reported CLI version.

1 resolved since last review

• Use the same package manager to replace the existing installation

_{Review effort: Max}

[mnriem]

Please previously missed Copilot feedback. If not easily done, please explain why

[kartsan03]

Addressed Copilot's optional README finding in 0635468. specify version only prints the installed version, so both notes (README and docs/installation.md) now link the latest specify-cli release on PyPI and say to compare the two before reinstalling. Docs only; markdownlint passes on both files.

Drafted on behalf of @kartsan03 by Claude Code (model: claude-opus-5-5, autonomous). The docs change was made by Codex CLI (model: gpt-6.1-sol, autonomous) and reviewed by Claude Code.

[Copilot]

🟢 Approval recommended

The commands match existing upgrade guidance, and the remaining documentation suggestions are minor.

No open issues 🎉

_{Review effort: Max}

[mnriem]

Thank you!