pocketshell 0.5.4__tar.gz → 0.5.6__tar.gz

pocketshell-0.5.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexey Grigorev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{pocketshell-0.5.4 → pocketshell-0.5.6}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: pocketshell
-Version: 0.5.4
-Summary: Unified server-side Python utility for the PocketShell Android client.
-Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
-Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues
+Version: 0.5.6
+Summary: Unified server-side Python utility for the PocketShell Android and desktop clients.
+Project-URL: Homepage, https://github.com/PocketShell-io/pocketshell-cli
+Project-URL: Issues, https://github.com/PocketShell-io/pocketshell-cli/issues
 Author: Alexey Grigorev
 License: MIT
+License-File: LICENSE
 Keywords: agents,pocketshell,ssh,usage
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
@@ -26,16 +27,17 @@ Requires-Dist: quse==0.0.15
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.0; extra == 'dev'
 Requires-Dist: ruff>=0.15.0; extra == 'dev'
-Provides-Extra: qr
-Requires-Dist: qrcode[pil]>=7.4; extra == 'qr'
 Description-Content-Type: text/markdown
 
 # pocketshell
 
-Unified server-side Python utility for the [PocketShell](https://github.com/alexeygrigorev/pocketshell)
-Android client. The app probes for this single helper on each remote
+Unified server-side Python utility for the [PocketShell](https://github.com/PocketShell-io/pocketshell)
+Android and desktop clients. This is the host-side companion CLI, maintained in its own
+repo with an independent release cycle; before v0.5.5 it lived at
+`tools/pocketshell/` in the [monorepo](https://github.com/PocketShell-io/pocketshell)
+(versioning was coupled to the app tag there — see [Release flow](#release-flow)). The app probes for this single helper on each remote
 host and uses its subcommands for usage, aplexer session lifecycle, agent
-conversations, QR host setup, repository discovery, environment files, hooks,
+conversations, repository discovery, environment files, hooks,
 logs, and daemon lifecycle checks.
 
 ## Durable workspaces
@@ -66,7 +68,7 @@ uv tool install pocketshell
 For local development from a clone:
 
 ```bash
-cd tools/pocketshell
+cd pocketshell-cli
 uv venv
 uv pip install -e .
 pocketshell --help
@@ -76,21 +78,6 @@ pocketshell --help
 pipx. Both install paths produce a `pocketshell` binary that the
 PocketShell app's bootstrap probe detects.
 
-### Optional extras
-
-`pocketshell qr-share` requires the `qrcode[pil]` package (Pillow) to
-render QR images. Because Pillow is heavy and not needed by any other
-subcommand, it ships behind an optional `qr` extra:
-
-```bash
-uv tool install pocketshell --with qrcode[pil]
-# or
-pip install pocketshell[qr]
-```
-
-Without the extra, every other subcommand keeps working; only
-`pocketshell qr-share` exits 127 with a friendly install hint.
-
 ## Usage
 
 Top-level commands in the current helper:
@@ -109,7 +96,6 @@ pocketshell hooks ...                       # Claude/Codex/OpenCode hooks
 pocketshell logs ...                        # server-side trace sink
 pocketshell daemon ...                      # IPC daemon lifecycle
 pocketshell serve --dir PATH [--port N]     # foreground static HTTP server
-pocketshell qr-share ...                    # SSH host QR import payloads
 ```
 
 Run `pocketshell --help` or `pocketshell <command> --help` for the live
@@ -180,15 +166,15 @@ Schema (every entry):
 {
   "owner": "alexeygrigorev",          // null when remote URL is non-GitHub
   "name": "pocketshell",              // local dir basename, or GH repo name
-  "full_name": "alexeygrigorev/pocketshell",  // null when owner unknown
+  "full_name": "PocketShell-io/pocketshell",  // null when owner unknown
   "local": {                          // populated by --local scans
     "path": "/home/alexey/git/pocketshell",
     "head": "main"
   },
   "remote": {                         // populated by --remote scans
     "default_branch": "main",
-    "html_url": "https://github.com/alexeygrigorev/pocketshell",
-    "ssh_url": "git@github.com:alexeygrigorev/pocketshell.git",
+    "html_url": "https://github.com/PocketShell-io/pocketshell",
+    "ssh_url": "git@github.com:PocketShell-io/pocketshell.git",
     "updated_at": "2026-05-27T12:00:00Z"
   }
 }
@@ -273,47 +259,6 @@ to its `index.html` when present; paths are resolved before the containment
 check, so parent traversal and symlinks that leave the selected directory are
 rejected rather than served.
 
-### `pocketshell qr-share`
-
-Builds a `pocketshell.ssh-import.v1` payload from an `~/.ssh/config`
-alias (resolved via `ssh -G`) or from explicit flags, wraps it in one or
-more `pocketshell.qr.v1` chunked envelopes (matching the Kotlin
-`QrChunkCodec` byte-for-byte), and emits QR codes for the phone-side
-scanner to consume (issue #129).
-
-```bash
-pocketshell qr-share prod                           # ssh-config alias
-pocketshell qr-share --host h --user u --key ~/.ssh/id_ed25519 --name h
-pocketshell qr-share prod --png --out-dir /tmp/qr   # write PNGs
-pocketshell qr-share prod --print-only --id deadbeef  # debug envelopes
-```
-
-When stdout is a TTY the QRs are drawn inline as Unicode blocks; between
-multi-part transmissions the command pauses on "Press Enter for next
-QR" so the user can scan each in turn. When stdout is not a TTY (or
-`--png` is passed) a numbered PNG sequence (`qr-share-01.png`,
-`qr-share-02.png`, ...) is written to `--out-dir`.
-
-Requires the optional `qr` extra (see [Optional extras](#optional-extras)).
-Without it, the command exits 127 with the install hint and every other
-subcommand keeps working.
-
-#### Running from a repo clone (no install)
-
-To run `qr-share` straight from a checkout without installing the tool,
-use `uv run` from `tools/pocketshell` and include the `qr` extra:
-
-```bash
-cd tools/pocketshell
-uv run --extra qr pocketshell qr-share prod
-```
-
-The first run creates `.venv` and installs the QR dependency; later runs
-are instant. Run it in an interactive terminal so stdout is a TTY and the
-QR renders inline — otherwise it falls back to writing PNGs (add
-`--png --out-dir ./qr` to force PNGs). Omitting `--extra qr` makes the
-command exit 127 with the install hint.
-
 ### `pocketshell hooks`
 
 Installs agent **stop / idle-detection** hooks across Claude Code,
@@ -388,7 +333,7 @@ generated executables, and durable ownership metadata are cleaned up.
 ## Development
 
 ```bash
-cd tools/pocketshell
+cd pocketshell-cli
 uv venv
 uv pip install -e ".[dev]"
 uv run pytest
@@ -406,120 +351,47 @@ they run in seconds without invoking a real host session.
 
 ## Release flow
 
-`pocketshell` ships in lockstep with the Android app. Every time the
-maintainer cuts an Android release tag (`vX.Y.Z`), the
-[`Build`](../../.github/workflows/build.yml) workflow assembles the APK
-and **also** builds the Python sdist + wheel and publishes them to PyPI.
-
-### Version coupling (tag-derived, issue #2356)
-
-Neither side is a hand-maintained literal any more. Both derive from the git
-tag being built, via the single shared script
-[`scripts/derive-version.sh`](../../scripts/derive-version.sh):
-
-- `app/build.gradle.kts` computes `versionCode`/`versionName` at Gradle
-  configuration time by shelling out to `scripts/derive-version.sh`.
-- `tools/pocketshell/pyproject.toml`'s committed `version` field is a
-  placeholder. The release workflow's "Stamp pyproject.toml version from
-  tag" step overwrites it (in the ephemeral CI checkout, never committed)
-  from `scripts/derive-version.sh version-name --ref <tag>` immediately
-  before building the sdist/wheel.
-
-[`scripts/check-version-coupling.sh`](../../scripts/check-version-coupling.sh)
-verifies the derivation script is the SOLE source of truth (its own
-self-test, Gradle's resolved version matching a direct script invocation,
-and both consumers referencing the script by path rather than an
-independent reimplementation) — it runs per-push in `tests.yml`.
-[`scripts/check-pypi-version.sh`](../../scripts/check-pypi-version.sh)
-verifies, at tag-publish time, that the freshly-stamped
-`pyproject.toml` version equals what `scripts/derive-version.sh` derives
-for the tag being published:
+`pocketshell` is released from THIS repo on its own cycle, independent of the
+Android app (extraction: PocketShell-io/pocketshell#2643). The `version` in
+`pyproject.toml` is the single source of truth:
 
-```bash
-scripts/check-pypi-version.sh --check-tag vX.Y.Z
-```
+1. Bump `version` in `pyproject.toml` (one small commit — the release
+   declaration; org convention, cf. PocketShell-io/quse).
+2. Tag that commit `vX.Y.Z` — the tag MUST equal the pyproject version — and
+   push the tag. `.github/workflows/publish.yml` builds the sdist + wheel,
+   refuses to publish if `dist/` does not carry exactly the tagged version,
+   and publishes to PyPI.
+3. Hosts pick it up with `uv tool upgrade pocketshell`.
 
-### Cutting a release
-
-There is no version-bump commit or PR. The tag itself is the version
-declaration:
-
-1. Pick the next semantic version after the latest GitHub Release/tag.
-2. Run the emulator release validation gate
-   (`scripts/release-emulator-validation.sh`) against the current `main`
-   HEAD, as described in [`process.md`](../../process.md) -> "Release
-   Builds".
-3. Push the tag with `scripts/push-release-tag.sh vX.Y.Z ...`. It creates
-   the tag locally FIRST and verifies `scripts/derive-version.sh` derives
-   the expected `versionName` (and a strictly-monotonic `versionCode`
-   versus the previous tag) from it before pushing — so a derivation bug
-   is caught before the tag ever reaches `origin`. The tag-triggered
-   `Build` workflow then:
-   - builds and uploads the APK (its `versionCode`/`versionName` come from
-     the tag via `app/build.gradle.kts`'s own derivation) + creates the
-     GitHub Release
-   - stamps `tools/pocketshell/pyproject.toml`'s version from the tag
-   - runs `scripts/check-pypi-version.sh --check-tag vX.Y.Z`
-   - builds the Python sdist + wheel
-   - publishes them to PyPI via OIDC trusted publishing
-
-The PyPI publish job depends on the APK build job, so a broken APK
-build also aborts the PyPI publish. If only the PyPI publish fails the
-maintainer can re-trigger the workflow at the same tag from the
-Actions tab; the APK build is idempotent against an existing release
-(`softprops/action-gh-release` updates the existing release rather
-than failing).
-
-## PyPI trusted publishing setup (one-time)
-
-The `publish-pypi` job uses GitHub's OIDC token instead of a long-lived
-API token. This avoids storing a `PYPI_API_TOKEN` secret in the repo
-and means there is nothing to rotate. The trade-off is that the
-project owner must complete one configuration step on pypi.org before
-the first automated tag publish:
-
-1. Sign in to https://pypi.org/ with the project owner account.
-2. Open the `pocketshell` project page ->
-   **Manage** -> **Publishing**.
-3. Under **Trusted publishers**, click **Add a new pending publisher**
-   (if the project is empty) or **Add a new publisher**, then fill in:
-   - **PyPI Project Name**: `pocketshell`
-   - **Owner**: `alexeygrigorev`
-   - **Repository name**: `pocketshell`
-   - **Workflow name**: `build.yml`
-   - **Environment name**: `pypi`
-4. Save the publisher.
-5. In this repository on GitHub, open
-   **Settings** -> **Environments** -> **New environment** -> name it
-   `pypi`. No secrets or reviewers are required; the environment exists
-   purely to scope the OIDC token. (If the environment already exists,
-   confirm it has no protection rules that would block the workflow
-   from running.)
-6. Push the next release tag. The `Publish to PyPI via trusted
-   publishing` step should succeed without any token configuration.
-
-### Why trusted publishing (and not `PYPI_API_TOKEN`)?
-
-- No long-lived secret to rotate, leak, or accidentally print in logs.
-- The OIDC subject is scoped to `repo=alexeygrigorev/pocketshell`,
-  `workflow=build.yml`, `environment=pypi`, so a compromised fork or
-  a different workflow file in this repo cannot reuse it.
-- D22 (no backwards-compat): we do not also maintain a token-fallback
-  path. If trusted publishing breaks, fix it; do not add a token
-  branch alongside.
-
-If trusted publishing is ever unavailable for a tag (e.g. PyPI outage
-on the OIDC verifier), the recommended manual escape hatch is:
+CI (`.github/workflows/ci.yml`) runs the pytest suite plus the packaging and
+frozen-lock guards on every PR and every push to `main`. The first
+self-governed release is **0.5.5**, continuing from the last app-coupled
+release 0.5.4 so `uv tool upgrade` stays monotonic.
+
+### PyPI publish setup (one-time)
+
+The `publish-pypi` job publishes with a PyPI API token stored as the
+`PYPI_API_TOKEN` secret on this repo (same mechanism as
+[PocketShell-io/quse](https://github.com/PocketShell-io/quse)):
+
+1. On pypi.org, create an API token scoped to the `pocketshell` project (or
+   reuse the existing project-scoped token from the monorepo era).
+2. On GitHub: this repo → Settings → Secrets and variables → Actions →
+   New repository secret → name `PYPI_API_TOKEN`. The `pypi` environment
+   already exists; the publish job runs inside it.
+
+If a publish fails after the tag is pushed, fix the cause and re-run
+`publish.yml` from the Actions tab (it has a `workflow_dispatch` trigger) —
+the tag does not need to move.
+
+Manual escape hatch (maintainer account, only when CI publishing is
+unavailable):
 
 ```bash
-cd tools/pocketshell
-python -m build
-python -m twine upload dist/*
+uv build
+uv run --with twine twine upload dist/*
 ```
 
-with the maintainer's account. Do not re-add a `PYPI_API_TOKEN` secret
-as a permanent fallback.
-
 ## Why a unified CLI?
 
 The PocketShell app previously depended on multiple host-side tools.

{pocketshell-0.5.4 → pocketshell-0.5.6}/README.md

@@ -1,9 +1,12 @@
 # pocketshell
 
-Unified server-side Python utility for the [PocketShell](https://github.com/alexeygrigorev/pocketshell)
-Android client. The app probes for this single helper on each remote
+Unified server-side Python utility for the [PocketShell](https://github.com/PocketShell-io/pocketshell)
+Android and desktop clients. This is the host-side companion CLI, maintained in its own
+repo with an independent release cycle; before v0.5.5 it lived at
+`tools/pocketshell/` in the [monorepo](https://github.com/PocketShell-io/pocketshell)
+(versioning was coupled to the app tag there — see [Release flow](#release-flow)). The app probes for this single helper on each remote
 host and uses its subcommands for usage, aplexer session lifecycle, agent
-conversations, QR host setup, repository discovery, environment files, hooks,
+conversations, repository discovery, environment files, hooks,
 logs, and daemon lifecycle checks.
 
 ## Durable workspaces
@@ -34,7 +37,7 @@ uv tool install pocketshell
 For local development from a clone:
 
 ```bash
-cd tools/pocketshell
+cd pocketshell-cli
 uv venv
 uv pip install -e .
 pocketshell --help
@@ -44,21 +47,6 @@ pocketshell --help
 pipx. Both install paths produce a `pocketshell` binary that the
 PocketShell app's bootstrap probe detects.
 
-### Optional extras
-
-`pocketshell qr-share` requires the `qrcode[pil]` package (Pillow) to
-render QR images. Because Pillow is heavy and not needed by any other
-subcommand, it ships behind an optional `qr` extra:
-
-```bash
-uv tool install pocketshell --with qrcode[pil]
-# or
-pip install pocketshell[qr]
-```
-
-Without the extra, every other subcommand keeps working; only
-`pocketshell qr-share` exits 127 with a friendly install hint.
-
 ## Usage
 
 Top-level commands in the current helper:
@@ -77,7 +65,6 @@ pocketshell hooks ...                       # Claude/Codex/OpenCode hooks
 pocketshell logs ...                        # server-side trace sink
 pocketshell daemon ...                      # IPC daemon lifecycle
 pocketshell serve --dir PATH [--port N]     # foreground static HTTP server
-pocketshell qr-share ...                    # SSH host QR import payloads
 ```
 
 Run `pocketshell --help` or `pocketshell <command> --help` for the live
@@ -148,15 +135,15 @@ Schema (every entry):
 {
   "owner": "alexeygrigorev",          // null when remote URL is non-GitHub
   "name": "pocketshell",              // local dir basename, or GH repo name
-  "full_name": "alexeygrigorev/pocketshell",  // null when owner unknown
+  "full_name": "PocketShell-io/pocketshell",  // null when owner unknown
   "local": {                          // populated by --local scans
     "path": "/home/alexey/git/pocketshell",
     "head": "main"
   },
   "remote": {                         // populated by --remote scans
     "default_branch": "main",
-    "html_url": "https://github.com/alexeygrigorev/pocketshell",
-    "ssh_url": "git@github.com:alexeygrigorev/pocketshell.git",
+    "html_url": "https://github.com/PocketShell-io/pocketshell",
+    "ssh_url": "git@github.com:PocketShell-io/pocketshell.git",
     "updated_at": "2026-05-27T12:00:00Z"
   }
 }
@@ -241,47 +228,6 @@ to its `index.html` when present; paths are resolved before the containment
 check, so parent traversal and symlinks that leave the selected directory are
 rejected rather than served.
 
-### `pocketshell qr-share`
-
-Builds a `pocketshell.ssh-import.v1` payload from an `~/.ssh/config`
-alias (resolved via `ssh -G`) or from explicit flags, wraps it in one or
-more `pocketshell.qr.v1` chunked envelopes (matching the Kotlin
-`QrChunkCodec` byte-for-byte), and emits QR codes for the phone-side
-scanner to consume (issue #129).
-
-```bash
-pocketshell qr-share prod                           # ssh-config alias
-pocketshell qr-share --host h --user u --key ~/.ssh/id_ed25519 --name h
-pocketshell qr-share prod --png --out-dir /tmp/qr   # write PNGs
-pocketshell qr-share prod --print-only --id deadbeef  # debug envelopes
-```
-
-When stdout is a TTY the QRs are drawn inline as Unicode blocks; between
-multi-part transmissions the command pauses on "Press Enter for next
-QR" so the user can scan each in turn. When stdout is not a TTY (or
-`--png` is passed) a numbered PNG sequence (`qr-share-01.png`,
-`qr-share-02.png`, ...) is written to `--out-dir`.
-
-Requires the optional `qr` extra (see [Optional extras](#optional-extras)).
-Without it, the command exits 127 with the install hint and every other
-subcommand keeps working.
-
-#### Running from a repo clone (no install)
-
-To run `qr-share` straight from a checkout without installing the tool,
-use `uv run` from `tools/pocketshell` and include the `qr` extra:
-
-```bash
-cd tools/pocketshell
-uv run --extra qr pocketshell qr-share prod
-```
-
-The first run creates `.venv` and installs the QR dependency; later runs
-are instant. Run it in an interactive terminal so stdout is a TTY and the
-QR renders inline — otherwise it falls back to writing PNGs (add
-`--png --out-dir ./qr` to force PNGs). Omitting `--extra qr` makes the
-command exit 127 with the install hint.
-
 ### `pocketshell hooks`
 
 Installs agent **stop / idle-detection** hooks across Claude Code,
@@ -356,7 +302,7 @@ generated executables, and durable ownership metadata are cleaned up.
 ## Development
 
 ```bash
-cd tools/pocketshell
+cd pocketshell-cli
 uv venv
 uv pip install -e ".[dev]"
 uv run pytest
@@ -374,120 +320,47 @@ they run in seconds without invoking a real host session.
 
 ## Release flow
 
-`pocketshell` ships in lockstep with the Android app. Every time the
-maintainer cuts an Android release tag (`vX.Y.Z`), the
-[`Build`](../../.github/workflows/build.yml) workflow assembles the APK
-and **also** builds the Python sdist + wheel and publishes them to PyPI.
-
-### Version coupling (tag-derived, issue #2356)
-
-Neither side is a hand-maintained literal any more. Both derive from the git
-tag being built, via the single shared script
-[`scripts/derive-version.sh`](../../scripts/derive-version.sh):
-
-- `app/build.gradle.kts` computes `versionCode`/`versionName` at Gradle
-  configuration time by shelling out to `scripts/derive-version.sh`.
-- `tools/pocketshell/pyproject.toml`'s committed `version` field is a
-  placeholder. The release workflow's "Stamp pyproject.toml version from
-  tag" step overwrites it (in the ephemeral CI checkout, never committed)
-  from `scripts/derive-version.sh version-name --ref <tag>` immediately
-  before building the sdist/wheel.
-
-[`scripts/check-version-coupling.sh`](../../scripts/check-version-coupling.sh)
-verifies the derivation script is the SOLE source of truth (its own
-self-test, Gradle's resolved version matching a direct script invocation,
-and both consumers referencing the script by path rather than an
-independent reimplementation) — it runs per-push in `tests.yml`.
-[`scripts/check-pypi-version.sh`](../../scripts/check-pypi-version.sh)
-verifies, at tag-publish time, that the freshly-stamped
-`pyproject.toml` version equals what `scripts/derive-version.sh` derives
-for the tag being published:
+`pocketshell` is released from THIS repo on its own cycle, independent of the
+Android app (extraction: PocketShell-io/pocketshell#2643). The `version` in
+`pyproject.toml` is the single source of truth:
 
-```bash
-scripts/check-pypi-version.sh --check-tag vX.Y.Z
-```
+1. Bump `version` in `pyproject.toml` (one small commit — the release
+   declaration; org convention, cf. PocketShell-io/quse).
+2. Tag that commit `vX.Y.Z` — the tag MUST equal the pyproject version — and
+   push the tag. `.github/workflows/publish.yml` builds the sdist + wheel,
+   refuses to publish if `dist/` does not carry exactly the tagged version,
+   and publishes to PyPI.
+3. Hosts pick it up with `uv tool upgrade pocketshell`.
 
-### Cutting a release
-
-There is no version-bump commit or PR. The tag itself is the version
-declaration:
-
-1. Pick the next semantic version after the latest GitHub Release/tag.
-2. Run the emulator release validation gate
-   (`scripts/release-emulator-validation.sh`) against the current `main`
-   HEAD, as described in [`process.md`](../../process.md) -> "Release
-   Builds".
-3. Push the tag with `scripts/push-release-tag.sh vX.Y.Z ...`. It creates
-   the tag locally FIRST and verifies `scripts/derive-version.sh` derives
-   the expected `versionName` (and a strictly-monotonic `versionCode`
-   versus the previous tag) from it before pushing — so a derivation bug
-   is caught before the tag ever reaches `origin`. The tag-triggered
-   `Build` workflow then:
-   - builds and uploads the APK (its `versionCode`/`versionName` come from
-     the tag via `app/build.gradle.kts`'s own derivation) + creates the
-     GitHub Release
-   - stamps `tools/pocketshell/pyproject.toml`'s version from the tag
-   - runs `scripts/check-pypi-version.sh --check-tag vX.Y.Z`
-   - builds the Python sdist + wheel
-   - publishes them to PyPI via OIDC trusted publishing
-
-The PyPI publish job depends on the APK build job, so a broken APK
-build also aborts the PyPI publish. If only the PyPI publish fails the
-maintainer can re-trigger the workflow at the same tag from the
-Actions tab; the APK build is idempotent against an existing release
-(`softprops/action-gh-release` updates the existing release rather
-than failing).
-
-## PyPI trusted publishing setup (one-time)
-
-The `publish-pypi` job uses GitHub's OIDC token instead of a long-lived
-API token. This avoids storing a `PYPI_API_TOKEN` secret in the repo
-and means there is nothing to rotate. The trade-off is that the
-project owner must complete one configuration step on pypi.org before
-the first automated tag publish:
-
-1. Sign in to https://pypi.org/ with the project owner account.
-2. Open the `pocketshell` project page ->
-   **Manage** -> **Publishing**.
-3. Under **Trusted publishers**, click **Add a new pending publisher**
-   (if the project is empty) or **Add a new publisher**, then fill in:
-   - **PyPI Project Name**: `pocketshell`
-   - **Owner**: `alexeygrigorev`
-   - **Repository name**: `pocketshell`
-   - **Workflow name**: `build.yml`
-   - **Environment name**: `pypi`
-4. Save the publisher.
-5. In this repository on GitHub, open
-   **Settings** -> **Environments** -> **New environment** -> name it
-   `pypi`. No secrets or reviewers are required; the environment exists
-   purely to scope the OIDC token. (If the environment already exists,
-   confirm it has no protection rules that would block the workflow
-   from running.)
-6. Push the next release tag. The `Publish to PyPI via trusted
-   publishing` step should succeed without any token configuration.
-
-### Why trusted publishing (and not `PYPI_API_TOKEN`)?
-
-- No long-lived secret to rotate, leak, or accidentally print in logs.
-- The OIDC subject is scoped to `repo=alexeygrigorev/pocketshell`,
-  `workflow=build.yml`, `environment=pypi`, so a compromised fork or
-  a different workflow file in this repo cannot reuse it.
-- D22 (no backwards-compat): we do not also maintain a token-fallback
-  path. If trusted publishing breaks, fix it; do not add a token
-  branch alongside.
-
-If trusted publishing is ever unavailable for a tag (e.g. PyPI outage
-on the OIDC verifier), the recommended manual escape hatch is:
+CI (`.github/workflows/ci.yml`) runs the pytest suite plus the packaging and
+frozen-lock guards on every PR and every push to `main`. The first
+self-governed release is **0.5.5**, continuing from the last app-coupled
+release 0.5.4 so `uv tool upgrade` stays monotonic.
+
+### PyPI publish setup (one-time)
+
+The `publish-pypi` job publishes with a PyPI API token stored as the
+`PYPI_API_TOKEN` secret on this repo (same mechanism as
+[PocketShell-io/quse](https://github.com/PocketShell-io/quse)):
+
+1. On pypi.org, create an API token scoped to the `pocketshell` project (or
+   reuse the existing project-scoped token from the monorepo era).
+2. On GitHub: this repo → Settings → Secrets and variables → Actions →
+   New repository secret → name `PYPI_API_TOKEN`. The `pypi` environment
+   already exists; the publish job runs inside it.
+
+If a publish fails after the tag is pushed, fix the cause and re-run
+`publish.yml` from the Actions tab (it has a `workflow_dispatch` trigger) —
+the tag does not need to move.
+
+Manual escape hatch (maintainer account, only when CI publishing is
+unavailable):
 
 ```bash
-cd tools/pocketshell
-python -m build
-python -m twine upload dist/*
+uv build
+uv run --with twine twine upload dist/*
 ```
 
-with the maintainer's account. Do not re-add a `PYPI_API_TOKEN` secret
-as a permanent fallback.
-
 ## Why a unified CLI?
 
 The PocketShell app previously depended on multiple host-side tools.