gentle-pi v3.5.1 — Link Mode Take-Over and Standalone Install Docs

Gentle Shell v3.5.1 is a patch release for the standalone launcher: gentle-shell --link now works when your ~/.pi/agent already declares gentle-pi as a local path package, loose extensions load file by file during that take-over, and the README leads with the standalone install. The npm package remains gentle-pi and the bundled Gentle AI runtime remains v3.5.0.

Provenance

• Previous stable: v3.5.0 → ba985f5037a71d7b7c9d53113340c39ffc4b702a
• Release target: v3.5.1 → df41b3a2420f8f9910cebd8b4bfb4a29f5fefa60
• Release validation: run 35756639150 passed package verification and published to npm with provenance.
• Pinned Gentle AI: v3.5.0; the review provider contract remains unchanged.

What's new

Standalone install first in the docs

The README now presents npm i -g gentle-pi followed by gentle-shell (own home) or gentle-shell --link (your existing ~/.pi/agent) as the primary path, with pi install npm:gentle-pi@3.5.1 as the path for an existing pi. The reference shows the companion packages in both forms, gentle-shell install npm:<pkg> for the isolated home and pi install npm:<pkg> inside pi, and the "What's new" section and repository links point at the renamed gentle-shell repository. Included work: release commits on main (this release).

What was fixed

Link mode with a path-declared gentle-pi

Root cause: the launcher only recognised npm:gentle-pi in the linked settings.json, so a gentle-pi declared as a local path (a source checkout) loaded twice and pi reported duplicate tools such as ask_user_choice. The launcher now recognises path declarations and, when the declared checkout is not its own package root, takes over extension loading: --no-extensions, then explicit -e for every other declared package and for loose extensions, plus its own package root, themes, skills and prompt templates. Declared-but-missing package directories are skipped with one warning instead of handing pi an unresolvable -e, symlinked entries are compared through realpath so one physical package is never injected twice, and --package-root fails fast when the directory does not exist. Known limit: the taken-over gentle-pi still contributes its skills, prompt templates and themes through ordinary discovery. Included work: #1335 (folding #1333 and #1334).

Loose extensions during a take-over

Root cause: pi cannot load a bare directory through -e (it imports the path as a module). Loose extensions are now injected file by file: direct *.ts/*.js/*.mjs children and <subdir>/index.*, dotfiles and .d.ts skipped; only a directory with its own pi.extensions manifest is passed through whole, and a root index.ts no longer hides its sibling files. An unreadable loose-extensions directory warns once. Included work: #1335.

Activity payload session scoping

The gentle-agents RPC activity payload is locked to the current session by tests, so an interactive host never receives helpers from other chats. Included work: #1337.

Pinned runtime

The pinned gentle-ai runtime is unchanged at v3.5.0: same module path, same signed archives for Darwin and Linux, same SumDB-verified source build for Windows, and the review provider contract did not change. No new NATIVE_CLI_CONTRACTS row or capabilities/vN identity was added.

Breaking changes

None. Existing ODD, SDD, review, and package interfaces remain compatible.

Upgrade

pi install npm:gentle-pi@3.5.1

No runtime migration is required: the pinned runtime and its managed assets did not change. Standalone users run npm i -g gentle-pi@3.5.1.

Numbers

11 non-merge commits, 2 merged pull requests, and 1 unique GitHub PR author since v3.5.0. Release preparation: three commits pushed directly to main (docs and version bump).

Verification

• Local suite on macOS (Node 24): 3245 tests, 3207 pass, 0 fail, 38 skipped (Windows-native cases); provider contract mirror check and runtime harness passed.
• Package verification: 171 files, 69 byte-pinned contract artifacts for the v3.5.0 runtime; npm pack --dry-run lists bin/gentle-shell.mjs (548 files).
• Native review over the whole link-mode branch: four lenses, one bounded correction, targeted validation approved and acknowledged (review-a5648d9b9cfc3253); follow-up test guard approved (review-b9b28b54b1660ec3); all remaining findings advisory.
• Manual: gentle-shell --link on the maintainer's home (gentle-pi declared as a path package, five loose extensions) starts without tool conflicts; profiles and the gentle-agents widget load.

Install

pi install npm:gentle-pi@3.5.1

Package: https://www.npmjs.com/package/gentle-pi

Full changelog: v3.5.0...v3.5.1