docs: refine PyPI install guidance from review (#3516)

Address review feedback for the PyPI install documentation:

- Reword the verification guidance so `specify version` is described as a
  local version/runtime check rather than proof of package provenance.
- Clarify that upgrading a pinned `uv tool` install to the newest PyPI
  release requires an unpinned reinstall command.
- Note that `specify self upgrade` rebuilds `uv tool` and `pipx`
  installs from the GitHub source release URL rather than preserving a
  PyPI-based installation.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: mnriem

docs/install/pypi.md

@@ -1,9 +1,9 @@
 # Installing from PyPI
 
-Spec Kit is published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the [GitHub source](../installation.md#install-from-source--persistent-installation-recommended). Use whichever fits your workflow — both provide the same official `specify` CLI.
+Spec Kit is published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), maintained by the Spec Kit maintainers. Installing from PyPI is the second supported install route alongside installing from the [GitHub source](../installation.md#install-from-source--persistent-installation-recommended). Use whichever fits your workflow — both provide the same `specify` CLI.
 
 > [!NOTE]
-> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Confirm what you installed with `specify version`.
+> The PyPI release version tracks the GitHub release tags (for example, PyPI `0.12.11` corresponds to the `v0.12.11` tag). Use `specify version` as a local sanity check, and inspect your package manager's record (for example `uv tool list`, `pipx list`, or `pip show specify-cli`) if you need to confirm the installed package source.
 
 ## Install Specify CLI
 
@@ -49,21 +49,21 @@ specify init <PROJECT_NAME> --integration copilot
 
 ## Upgrade
 
-Upgrade with the same tool you installed with:
+Upgrade by reinstalling the package through the same tool you used for the original install. If you want to move to the newest PyPI release, use an unpinned install command so you do not keep the existing version pin:
 
 ```bash
 # Using uv
-uv tool upgrade specify-cli
+uv tool install --force specify-cli
 
 # Or using pipx
-pipx upgrade specify-cli
+pipx install --force specify-cli
 
 # Or using pip
 pip install --upgrade specify-cli
 ```
 
 > [!NOTE]
-> `specify self upgrade` automatically manages `uv tool` and `pipx` installs. A plain `pip install specify-cli` is treated as an unmanaged install — upgrade it with `pip install --upgrade specify-cli`. See the [Upgrade Guide](../upgrade.md) for details.
+> `specify self upgrade` currently rebuilds `uv tool` and `pipx` installs from the GitHub source release URL rather than preserving a PyPI-based installation. If you want to stay on the PyPI route, use the package-manager commands above. A plain `pip install specify-cli` is treated as an unmanaged install — upgrade it with `pip install --upgrade specify-cli`. See the [Upgrade Guide](../upgrade.md) for details.
 
 ## Uninstall
 

docs/installation.md

@@ -11,7 +11,7 @@
 ## Installation
 
 > [!IMPORTANT]
-> Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). Either route is supported for normal installs — use the commands shown below. After installing, confirm you are running the official build with `specify version`. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
+> Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). Either route is supported for normal installs — use the commands shown below. After installing, run `specify version` to confirm that the `specify` command is available and to check the installed version. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
 
 Spec Kit supports two install routes:
 
@@ -110,7 +110,7 @@ After installation, run the following command to confirm the correct version is
 specify version
 ```
 
-This helps verify you are running an official Spec Kit build — whether installed from the GitHub source or the `specify-cli` package on PyPI.
+This helps confirm that the `specify` command is available and reporting the expected version.
 
 **Stay current:** Run `specify self check` periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the [Upgrade Guide](./upgrade.md).