imanimanyara · Oct 5, 2026 · Oct 5, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -36,6 +36,14 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   outcome raises a `Codecov upload failed` warning annotation.
 - The Codecov upload step never ran. Its condition read
   `matrix.python-version`, but the matrix key is `python`.
+- The extras install commands in the README and `docs/installation.md`
+  (`uv tool install 'shimkit[extra-tools]'` and friends) resolve against
+  PyPI, where `shimkit` is not published yet, so they failed. They now
+  name the release tag as a direct reference. `docs/shipping-checklist.md`
+  records that the `pypi` environment exists, that the missing pypi.org
+  trusted publisher is the one remaining blocker, and that past tags are
+  republished by dispatching `release.yml` rather than re-running jobs
+  whose artifacts have expired.
 
 ## [0.19.0] — 2026-05-16
 

diff --git a/README.md b/README.md
@@ -51,7 +51,8 @@ behaviour: [`docs/installation.md`](docs/installation.md).
 1. Verify the install: `shimkit version`, then `shimkit doctor` (platform, shell, package
    manager and config validity).
 2. Optional: add the extras for the tools that need them, e.g.
-   `uv tool install 'shimkit[extra-tools]'` for `dns`, `adguard` and `docker-clean`.
+   `uv tool install 'shimkit[extra-tools] @ git+https://github.com/simtabi/shimkit@v0.19.0'` for `dns`,
+   `adguard` and `docker-clean` (the bare `shimkit[extra-tools]` form needs PyPI, which is not published yet).
 3. Optional: override the bundled defaults with `shimkit config edit`, which opens
    `~/.config/shimkit/shimkit.json` in `$EDITOR`; `shimkit config show` prints the resolved config.
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -97,24 +97,29 @@ land when you actually use them.
 | `[docker-clean]`   | `docker`                                  | `shimkit docker-clean` |
 | `[extra-tools]`    | All of the above                          | Everything new         |
 
-Install with an extra:
+Install with an extra. Until PyPI publishing is live, name the release tag
+as a direct reference; the bare `'shimkit[extra-tools]'` form resolves
+against PyPI and fails there today:
 
 ```bash
-uv tool install 'shimkit[extra-tools]'
+uv tool install 'shimkit[extra-tools] @ git+https://github.com/simtabi/shimkit@v0.19.0'
 # or
-pipx install 'shimkit[extra-tools]'
+pipx install 'shimkit[extra-tools] @ git+https://github.com/simtabi/shimkit@v0.19.0'
 # or
-pip install --user 'shimkit[extra-tools]'
+pip install --user 'shimkit[extra-tools] @ git+https://github.com/simtabi/shimkit@v0.19.0'
 ```
 
 Already installed and want to add an extra later:
 
 ```bash
-uv tool install --upgrade 'shimkit[adguard]'
+uv tool install --reinstall 'shimkit[adguard] @ git+https://github.com/simtabi/shimkit@v0.19.0'
 # or
 pipx inject shimkit ruamel.yaml requests psutil
 ```
 
+Once `shimkit` is on PyPI, the short forms (`uv tool install 'shimkit[extra-tools]'`,
+`pipx install 'shimkit[extra-tools]'`) work as well.
+
 If you run a tool whose extra isn't installed, `shimkit` exits 69
 with a message naming the exact install command for your platform.
 

diff --git a/docs/shipping-checklist.md b/docs/shipping-checklist.md
@@ -46,7 +46,7 @@ intentionally don't validate), see
 | 2.1 | ✅ done | user | Repo exists at `simtabi/shimkit`. Default branch `main`. Public. |
 | 2.2 | ✅ done | user | Repo metadata set: description, homepage, topics. Issues + Discussions enabled. |
 | 2.3 | ✅ done | user | Local git identity scoped to noreply (`19682005+imanimanyara@users.noreply.github.com`). |
-| 2.4 | ⏳ **pending** | **user** | **Create the `pypi` GitHub Environment.** ⚠ blocker for the v0.11.0+ `publish-pypi` job. Settings → Environments → New environment named `pypi`. No secrets required (OIDC provides credentials). Optionally add a Required Reviewer rule for a human gate before upload. |
+| 2.4 | ✅ done | user | **Create the `pypi` GitHub Environment.** Exists (checked 2026-10-05 with `gh api repos/simtabi/shimkit/environments`). The OIDC token every `publish-pypi` run presents already carries `sub: repo:simtabi/shimkit:environment:pypi`. Optionally add a Required Reviewer rule for a human gate before upload. |
 
 ## Phase 3 · Homebrew tap — abandoned
 
@@ -80,8 +80,20 @@ user-side trusted-publisher setup.
 | 4.3 | ⏸ optional | user | (Dry-run only) Configure a `testpypi` trusted publisher at <https://test.pypi.org/manage/account/publishing/> + a `testpypi` GitHub environment if you want to rehearse a release on TestPyPI before hitting real PyPI. |
 
 After 2.4 + 4.1 + 4.2 are done, the next tag will publish to PyPI
-automatically. Failed PyPI uploads on past tags (v0.11.0, v0.12.0)
-can be re-run via Actions → failed run → "Re-run failed jobs".
+automatically.
+
+**4.2 is the one blocker left.** Every `publish-pypi` run from v0.11.0
+through v0.19.0 (nine releases) failed the token exchange with
+`invalid-publisher: valid token, but no corresponding publisher`, and
+`https://pypi.org/pypi/shimkit/json` answers 404 (checked 2026-10-05).
+The GitHub side is correct; pypi.org has no publisher registered.
+
+Failed uploads on past tags can **not** be fixed with "Re-run failed
+jobs": `publish-pypi` downloads the `dist` artifact from its run's
+`build` job, and those artifacts expire after 90 days (v0.11.0–v0.19.0
+ran 2026-05-15/16). Dispatch the whole workflow on the tag instead,
+which rebuilds and uploads:
+`gh workflow run release.yml --repo simtabi/shimkit --ref v0.19.0`.
 
 ## Phase 5 · First PyPI upload
 
@@ -91,7 +103,7 @@ Prerequisites: 2.4 + 4.1 + 4.2 all done.
 |---|--------|-------|------|
 | 5.1 | ▶︎ auto | ci | The next tagged release after 4.2 publishes to PyPI automatically. |
 | 5.2 | ⏳ pending | user | Verify the upload: `pip install shimkit` (no `--index-url`) should resolve to the latest PyPI version. |
-| 5.3 | ⏸ optional | user | Re-run failed `publish-pypi` jobs against tags v0.11.0+ to retroactively publish past releases. |
+| 5.3 | ⏸ optional | user | Retroactively publish past releases by dispatching `release.yml` on each tag (`--ref vX.Y.Z`); re-running the old failed jobs no longer works once their artifacts have expired. |
 
 ## Phase 6 · Post-release / ongoing
 
@@ -117,7 +129,7 @@ Prerequisites: 2.4 + 4.1 + 4.2 all done.
 For the next release to publish to PyPI:
 
 ```
-2.4  Create the pypi GitHub Environment
+2.4  Create the pypi GitHub Environment   (done)
   └─► 4.1  PyPI account + 2FA
         └─► 4.2  Configure trusted publisher
               └─► next tag → auto-publishes