allye-pi 2.8.0 → 2.8.1

package/README.md

@@ -59,7 +59,7 @@ Then open `/plugin`, find the Allye MCP server, click **Connect** and sign in. U
 
 ### Codex, OpenCode
 
-Paste into the agent:
+Paste into the agent. The install and update guides install one pinned release: the latest GitHub release unless you name a version. They check that it exists, never download from a branch, and keep a timestamped backup of any config they rewrite (`opencode.json`, `~/.codex/AGENTS.md`, `~/.codex/skills/bridge*`) under `~/.allye/backups/<harness>/`.
 
 ```
 Install Allye following: https://raw.githubusercontent.com/allye-app/allye-plugin/main/docs/install-codex.md
@@ -69,11 +69,11 @@ Install Allye following: https://raw.githubusercontent.com/allye-app/allye-plugi
 ### Pi, OMP
 
 ```bash
-pi install npm:allye-pi          # Pi
-omp plugin install allye-pi      # OMP
+pi install npm:allye-pi@<version>          # Pi
+omp plugin install allye-pi@<version>      # OMP
 ```
 
-Then add the `allye` MCP server as described in [install-pi.md](docs/install-pi.md) or [install-omp.md](docs/install-omp.md).
+Use a pinned `<version>` (the guides resolve it for you). Then add the `allye` MCP server as described in [install-pi.md](docs/install-pi.md) or [install-omp.md](docs/install-omp.md).
 
 ## Your organization's skills
 

package/docs/install-omp.md

@@ -6,11 +6,39 @@ OMP is a fork of Pi and reads the same package manifest (`omp`, falling back to
 
 ## Install the package
 
-```text
-omp plugin install allye-pi
+Resolve the version first, before any change. Run the resolve block, the npm check and the install in one shell session, so `VERSION` and `TAG` carry over. Only stable `vX.Y.Z` releases are accepted (no pre-release or build suffix), and `curl` and `jq` are required. The version is the one the user named, otherwise the latest GitHub release of `allye-app/allye-plugin`.
+
+```bash
+# Never put user text in this script unless it already matched ^v?[0-9]+\.[0-9]+\.[0-9]+$: write only the matched digits and dots (never the original text, never a value containing a quote).
+RAW=''   # set to the version only if you checked the user's text as a whole against ^v?[0-9]+\.[0-9]+\.[0-9]+$ (digits, dots, optional leading v); otherwise leave empty
+[ -n "$RAW" ] || RAW=$(curl -fsSL https://api.github.com/repos/allye-app/allye-plugin/releases/latest | jq -r '.tag_name // empty')
+RAW="${RAW#v}"
+if ! [[ "$RAW" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then echo "No valid release version: $RAW" >&2; return 1 2>/dev/null || exit 1; fi
+VERSION="$RAW"; TAG="v$VERSION"
+echo "Installing Allye $VERSION"
+```
+
+Tell the user the version. If no valid version resolves, stop and change nothing.
+
+Check that this version exists on npm. The release tag can appear before the npm publish: if the command fails, report it and stop; never fall back to an unpinned install. Show the user the printed version and `dist.integrity`. The Git release tag is trusted as published.
+
+```bash
+: "${VERSION:?}" "${TAG:?}"
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "Invalid VERSION" >&2; return 1 2>/dev/null || exit 1; }
+(cd "$HOME" && npm view allye-pi@"$VERSION" version dist.integrity)
+```
+
+Before installing, list the installed plugins with `omp plugin list` and note any `allye-pi` entry. If an older unpinned or different-version `allye-pi` is present, follow the update rules below (confirm with the user, then `--force` or uninstall first) so the pinned install replaces it instead of adding a second copy. After the install, run `omp plugin list` again and confirm exactly one `allye-pi` entry, at the pinned version.
+
+Install the pinned version:
+
+```bash
+: "${VERSION:?}" "${TAG:?}"
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "Invalid VERSION" >&2; return 1 2>/dev/null || exit 1; }
+omp plugin install allye-pi@"$VERSION"
 ```
 
-Update with `omp plugin upgrade allye-pi`; remove with `omp plugin uninstall allye-pi`.
+To update, resolve the newer version as above (same shell, same checks) and re-run the install with it. If OMP says the plugin is already installed, first confirm the installed plugin is `allye-pi` (`omp plugin list`) and that the user agrees, then confirm `omp plugin install --help` lists `--force` and re-run with `--force`; if the flag is not listed, run `omp plugin uninstall allye-pi` and install the pinned version again. If the install fails after the uninstall, tell the user to reinstall the previous version and report the failure. Do not use `omp plugin upgrade`. Remove with `omp plugin uninstall allye-pi`.
 
 ## Configure the MCP server
 

package/docs/install-pi.md

@@ -10,13 +10,49 @@ It never edits Pi's MCP configuration or reads credentials.
 
 ## Install the package
 
-```text
-pi install npm:allye-pi
+Resolve the version first, before any change. Run the resolve block, the npm check and the install in one shell session, so `VERSION` and `TAG` carry over. Only stable `vX.Y.Z` releases are accepted (no pre-release or build suffix), and `curl` and `jq` are required. The version is the one the user named, otherwise the latest GitHub release of `allye-app/allye-plugin`.
+
+```bash
+# Never put user text in this script unless it already matched ^v?[0-9]+\.[0-9]+\.[0-9]+$: write only the matched digits and dots (never the original text, never a value containing a quote).
+RAW=''   # set to the version only if you checked the user's text as a whole against ^v?[0-9]+\.[0-9]+\.[0-9]+$ (digits, dots, optional leading v); otherwise leave empty
+[ -n "$RAW" ] || RAW=$(curl -fsSL https://api.github.com/repos/allye-app/allye-plugin/releases/latest | jq -r '.tag_name // empty')
+RAW="${RAW#v}"
+if ! [[ "$RAW" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then echo "No valid release version: $RAW" >&2; return 1 2>/dev/null || exit 1; fi
+VERSION="$RAW"; TAG="v$VERSION"
+echo "Installing Allye $VERSION"
+```
+
+Tell the user the version. If no valid version resolves, stop and change nothing.
+
+Check that this version exists on npm. The release tag can appear before the npm publish: if the command fails, report it and stop; never fall back to an unpinned install. Show the user the printed version and `dist.integrity`. The Git release tag is trusted as published.
+
+```bash
+: "${VERSION:?}" "${TAG:?}"
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "Invalid VERSION" >&2; return 1 2>/dev/null || exit 1; }
+(cd "$HOME" && npm view allye-pi@"$VERSION" version dist.integrity)
+```
+
+The npm check above must already have passed before anything is removed. Then list the installed packages with `pi list`. If it shows another `allye-pi` source (unpinned npm, an older pinned npm, or the git source `git:github.com/allye-app/allye-plugin@vX.Y.Z`), confirm with the user and remove that exact source string as shown by `pi list` with `pi remove <source>`, so the pinned install replaces it instead of adding a second source. Do the removal just before the install. If the install then fails, tell the user to reinstall the previous version (the source string you removed) and report the failure. After the install, run `pi list` again and confirm exactly one `allye-pi` source (npm or git), at the pinned version.
+
+Install the pinned version:
+
+```bash
+: "${VERSION:?}" "${TAG:?}"
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "Invalid VERSION" >&2; return 1 2>/dev/null || exit 1; }
+pi install npm:allye-pi@"$VERSION"
+```
+
+From Git, at the release tag:
+
+```bash
+: "${VERSION:?}" "${TAG:?}"
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "Invalid VERSION" >&2; return 1 2>/dev/null || exit 1; }
+pi install git:github.com/allye-app/allye-plugin@"$TAG"
 ```
 
-From Git (preferably at a tag): `pi install git:github.com/allye-app/allye-plugin`. From a local checkout, for development: `pi install /absolute/path/to/allye-plugin`.
+From a local checkout, for development: `pi install /absolute/path/to/allye-plugin`.
 
-Update with `pi update npm:allye-pi`; remove with `pi remove npm:allye-pi`. Removing the package does not remove MCP configuration or OAuth credentials.
+To update, resolve the newer version as above (same shell, same checks) and re-run `pi install npm:allye-pi@"$VERSION"` with it (no `pi update`, which would not move a pinned version), then repeat the `pi list` check: exactly one `allye-pi` source. Remove with `pi remove <source>` using the source string shown by `pi list` (`npm:allye-pi@<version>` or the git source `git:github.com/allye-app/allye-plugin@<tag>`). Removing the package does not remove MCP configuration or OAuth credentials.
 
 ## Configure the MCP server
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allye-pi",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "Allye extension for Pi and OMP: the Allye bootstrap, the Bridge skill and the repository-to-project link",
   "type": "module",
   "keywords": [
@@ -49,9 +49,10 @@
     "test:installer": "bash install/test-validation.sh && bash install/test-installer.sh && npm run test:docs-gate",
     "test:bootstrap": "bash test/test-bootstrap.sh && bash hooks/test-session-start.sh",
     "test:agents": "node test/test-agents.mjs",
+    "test:guides": "node test/test-install-guides.mjs",
     "test:docs-gate": "bash install/test-docs-gate.sh",
     "test:skills": "node test/test-skills-text.mjs && node test/test-ci-proof.mjs && node test/test-ci-workflows.mjs",
-    "test": "npm run test:bootstrap && npm run test:agents && npm run test:skills && npm run test:installer && npm run test:pi && npm run test:opencode"
+    "test": "npm run test:bootstrap && npm run test:agents && npm run test:guides && npm run test:skills && npm run test:installer && npm run test:pi && npm run test:opencode"
   },
   "repository": {
     "type": "git",