docs: clarify PyPI verification and upgrade guidance

Assisted-by: GitHub Copilot (model: MAI-Code-1-Flash, autonomous)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: mnriem

docs/install/pypi.md

@@ -3,7 +3,7 @@
 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). 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.
+> 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 version/runtime sanity check. It does not prove whether the `specify` executable came from PyPI or GitHub; 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,7 +49,7 @@ specify init <PROJECT_NAME> --integration copilot
 
 ## Upgrade
 
-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:
+Upgrade by reinstalling the package through the same tool you used for the original install. If you originally pinned a version, note that `uv tool upgrade` preserves that pin; to move to the newest PyPI release, use an unpinned install command so you do not keep the existing version pin:
 
 ```bash
 # Using uv

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, 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 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` as a local version/runtime sanity check. It confirms that the `specify` command is available and reports its version, but it does not prove whether the executable came from PyPI or GitHub. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
 
 Spec Kit supports two install routes:
 
@@ -104,13 +104,13 @@ specify init <project_name> --integration claude --ignore-agent-tools
 
 ## Verification
 
-After installation, run the following command to confirm the correct version is installed:
+After installation, run the following command as a local version/runtime check:
 
 ```bash
 specify version
 ```
 
-This helps confirm that the `specify` command is available and reporting the expected version.
+This confirms that the `specify` command is available and reporting the expected version. It does not prove whether that executable came from PyPI or GitHub.
 
 **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).