fix: address review - python setup, docs alignment, publish flag

- Use actions/setup-python (pinned v6, Python 3.13) instead of
  uv python install for deterministic builds
- Use python instead of python3 for setup-python compatibility
- Remove unsupported --trusted-publishing always flag from uv publish
  (OIDC is auto-detected with id-token: write)
- Update README install to lead with PyPI, source as fallback
- Update installation guide: replace PyPI disclaimer with official
  package note, add PyPI as primary install method
- Release notes: pin to exact version, clarify PyPI timing

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

Author: mnriem

.github/workflows/publish-pypi.yml

@@ -35,13 +35,15 @@ jobs:
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Set up Python
-        run: uv python install 3.13
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.13"
 
       - name: Verify tag matches package version
         run: |
           TAG_VERSION="${{ inputs.tag }}"
           TAG_VERSION="${TAG_VERSION#v}"
-          PROJECT_VERSION="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          PROJECT_VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
           if [[ "$TAG_VERSION" != "$PROJECT_VERSION" ]]; then
             echo "Error: Tag version ($TAG_VERSION) does not match pyproject.toml version ($PROJECT_VERSION)"
             exit 1
@@ -74,4 +76,4 @@ jobs:
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Publish to PyPI
-        run: uv publish --trusted-publishing always
+        run: uv publish

.github/workflows/release.yml

@@ -65,15 +65,11 @@ jobs:
           cat > release_notes.md << NOTES_EOF
           ## Install
 
-          \`\`\`bash
-          uv tool install specify-cli
-          specify init my-project
-          \`\`\`
-
-          Or pin to this exact release:
+          From [PyPI](https://pypi.org/project/specify-cli/):
 
           \`\`\`bash
           uv tool install specify-cli==${VERSION_NO_V}
+          specify init my-project
           \`\`\`
 
           Or install from source:
@@ -82,7 +78,7 @@ jobs:
           uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION}
           \`\`\`
 
-          > **Note:** PyPI publishing is triggered manually after this release. If the PyPI version is not yet available, use the source install command above.
+          > **Note:** The PyPI package is published after this GitHub release. If the version is not yet available on PyPI, use the source install above.
 
           NOTES_EOF
 

README.md

@@ -44,7 +44,13 @@ Spec-Driven Development **flips the script** on traditional software development
 
 ### 1. Install Specify CLI
 
-Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](https://github.com/github/spec-kit/blob/main/docs/install/uv.md)). Replace `vX.Y.Z` with the latest tag from [Releases](https://github.com/github/spec-kit/releases):
+Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](https://github.com/github/spec-kit/blob/main/docs/install/uv.md)):
+
+```bash
+uv tool install specify-cli
+```
+
+Or install from source using a specific [release](https://github.com/github/spec-kit/releases) tag:
 
 ```bash
 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

docs/installation.md

@@ -10,16 +10,22 @@
 
 ## Installation
 
-> [!IMPORTANT]
-> The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on pypi.org) are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
+> [!NOTE]
+> The official `specify-cli` package is published to [PyPI](https://pypi.org/project/specify-cli/) by the [github/spec-kit](https://github.com/github/spec-kit) maintainers. Source installs from the GitHub repository are also supported.
 
 ### Persistent Installation (Recommended)
 
-Install once and use everywhere. Replace `vX.Y.Z` with a tag from [Releases](https://github.com/github/spec-kit/releases):
+Install once and use everywhere:
 
 > [!NOTE]
 > The command below requires **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uv`, [install uv first](./install/uv.md).
 
+```bash
+uv tool install specify-cli
+```
+
+Or install from source using a specific [release](https://github.com/github/spec-kit/releases) tag:
+
 ```bash
 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
 ```