fix(offline): address review round 5 + offline bundle ZIP

- fix(offline): pwsh-only, no powershell.exe fallback; clarify error message
- fix(offline): tighten _has_bundled to check scripts dir for source checkouts
- feat(release): build specify-bundle-v*.zip with all deps at release time
- feat(release): attach offline bundle ZIP to GitHub release assets
- docs: simplify air-gapped install to single ZIP download from releases
- docs: add Windows PowerShell 7+ (pwsh) requirement note

Author: mnriem

.github/workflows/release.yml

@@ -47,6 +47,12 @@ jobs:
           pip install build
           python -m build --wheel --outdir .genreleases/
 
+      - name: Bundle offline dependencies
+        if: steps.check_release.outputs.exists == 'false'
+        run: |
+          pip download -d .genreleases/specify-bundle/ .genreleases/specify_cli-*.whl
+          cd .genreleases && zip -r specify-bundle-${{ steps.version.outputs.tag }}.zip specify-bundle/
+
       - name: Generate release notes
         if: steps.check_release.outputs.exists == 'false'
         id: release_notes

.github/workflows/scripts/create-github-release.sh

@@ -33,6 +33,13 @@ fi
 
 WHEEL_FILE="${wheel_files[0]}"
 
+# Find the offline bundle ZIP
+bundle_files=(.genreleases/specify-bundle-"$VERSION".zip)
+BUNDLE_FILE=""
+if (( ${#bundle_files[@]} == 1 )); then
+  BUNDLE_FILE="${bundle_files[0]}"
+fi
+
 gh release create "$VERSION" \
   "$WHEEL_FILE" \
   .genreleases/spec-kit-template-copilot-sh-"$VERSION".zip \
@@ -83,5 +90,6 @@ gh release create "$VERSION" \
   .genreleases/spec-kit-template-pi-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-generic-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-generic-ps-"$VERSION".zip \
+  ${BUNDLE_FILE:+"$BUNDLE_FILE"} \
   --title "Spec Kit Templates - $VERSION_NO_V" \
   --notes-file release_notes.md

README.md

@@ -98,14 +98,15 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai c
 
 #### Option 3: Enterprise / Air-Gapped Installation
 
-If your environment blocks PyPI access, download the pre-built `specify_cli-*.whl` wheel from the [releases page](https://github.com/github/spec-kit/releases/latest) and install it directly:
+Download `specify-bundle-v*.zip` from the [releases page](https://github.com/github/spec-kit/releases/latest) — it contains the CLI wheel and all dependencies in one file (~2.5 MB):
 
 ```bash
-pip install specify_cli-*.whl
-specify init my-project --ai claude --offline   # runs without contacting api.github.com
+unzip specify-bundle-v*.zip
+pip install --no-index --find-links=./specify-bundle/ specify-cli
+specify init my-project --ai claude --offline
 ```
 
-The wheel bundles all templates, commands, and scripts, so `specify init` can run without any network access after install when you pass `--offline`. See the [Enterprise / Air-Gapped Installation](./docs/installation.md#enterprise--air-gapped-installation) section for fully offline (no-PyPI) instructions.
+See the [full air-gapped guide](./docs/installation.md#enterprise--air-gapped-installation) for details.
 
 ### 2. Establish project principles
 

docs/installation.md

@@ -77,48 +77,30 @@ The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
 
 ### Enterprise / Air-Gapped Installation
 
-If your environment blocks access to PyPI (you see 403 errors when running `uv tool install` or `pip install`), you can install Specify using the pre-built wheel from the GitHub releases page.
+For environments with no access to PyPI or GitHub, download the pre-built offline bundle from the [releases page](https://github.com/github/spec-kit/releases/latest).
 
-**Step 1: Download the wheel**
+**On a connected machine:**
 
-Go to the [Spec Kit releases page](https://github.com/github/spec-kit/releases/latest) and download the `specify_cli-*.whl` file.
+Download `specify-bundle-v*.zip` from the [Spec Kit releases page](https://github.com/github/spec-kit/releases/latest). This single ZIP contains the specify-cli wheel and all its runtime dependencies (~2.5 MB).
 
-**Step 2: Install the wheel**
+**On the air-gapped machine:**
 
 ```bash
-pip install specify_cli-*.whl
-```
+# Unzip the bundle
+unzip specify-bundle-v*.zip
 
-**Step 3: Initialize a project (no network required)**
+# Install — no network access needed
+pip install --no-index --find-links=./specify-bundle/ specify-cli
 
-```bash
+# Initialize a project — no GitHub access needed
 specify init my-project --ai claude --offline
 ```
 
-The `--offline` flag tells the CLI to use the templates, commands, and scripts bundled inside the wheel instead of downloading from GitHub — no connection to `api.github.com` needed.
+The `--offline` flag tells the CLI to use the templates, commands, and scripts bundled inside the wheel instead of downloading from GitHub.
 
-**If you also need runtime dependencies offline** (fully air-gapped machines with no access to any PyPI), use a connected machine with the same OS and Python version to download them first:
-
-```bash
-# On a connected machine (same OS and Python version as the target):
-pip download -d vendor specify_cli-*.whl
-
-# Transfer the wheel and vendor/ directory to the target machine
-
-# On the target machine:
-pip install --no-index --find-links=./vendor specify_cli-*.whl
-```
+> **Note:** Python 3.11+ is required. All dependencies are pure-Python wheels, so the bundle works on any platform without recompilation.
 
-> **Note:** Python 3.11+ is required. The wheel is a pure-Python artifact, so it works on any platform without recompilation.
-
-**Using bundled assets (offline / air-gapped):**
-
-If you want to scaffold from the templates bundled inside the specify-cli
-package instead of downloading from GitHub, use:
-
-```bash
-specify init my-project --ai claude --offline
-```
+> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from https://aka.ms/powershell.
 
 ### Git Credential Manager on Linux
 

src/specify_cli/__init__.py

@@ -1114,8 +1114,9 @@ def _locate_release_script() -> tuple[Path, str]:
         shell = shutil.which("pwsh")
         if not shell:
             raise FileNotFoundError(
-                "'pwsh' (PowerShell 7) not found on PATH. "
-                "The bundled release script requires PowerShell 7+. "
+                "'pwsh' (PowerShell 7+) not found on PATH. "
+                "The bundled release script requires PowerShell 7+ (pwsh), "
+                "not Windows PowerShell 5.x (powershell.exe). "
                 "Install from https://aka.ms/powershell to use offline scaffolding."
             )
     else:
@@ -1880,8 +1881,14 @@ def init(
     # Determine whether to use bundled assets or download from GitHub (default).
     # --offline opts in to bundled assets; without it, always use GitHub.
     _core = _locate_core_pack()
-    _repo_commands = Path(__file__).parent.parent.parent / "templates" / "commands"
-    _has_bundled = (_core is not None) or _repo_commands.is_dir()
+    _repo_root = Path(__file__).parent.parent.parent
+    _repo_commands = _repo_root / "templates" / "commands"
+    _repo_scripts = _repo_root / "scripts"
+    # Treat bundled assets as available if we have a core_pack (wheel install),
+    # or, for a source checkout, when both commands and scripts are present.
+    _has_bundled = (_core is not None) or (
+        _repo_commands.is_dir() and _repo_scripts.is_dir()
+    )
 
     if offline and not _has_bundled:
         console.print(