gentle-pi 3.5.0 → 3.5.1

package/README.md

@@ -12,8 +12,8 @@
   <a href="https://www.npmjs.com/package/gentle-pi"><img src="https://img.shields.io/npm/v/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="npm"></a>
   <a href="https://pi.dev/packages/gentle-pi"><img src="https://img.shields.io/badge/Pi-native-F095C8?style=for-the-badge&labelColor=1A1218" alt="Pi-native package"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="MIT license"></a>
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/stargazers"><img src="https://img.shields.io/github/stars/Gentleman-Programming/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="GitHub stars"></a>
-  <a href="https://github.com/Gentleman-Programming/gentle-pi"><img src="https://img.shields.io/github/last-commit/Gentleman-Programming/gentle-pi?style=for-the-badge&labelColor=1A1218&color=D7A0B8" alt="Last commit"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/stargazers"><img src="https://img.shields.io/github/stars/Gentleman-Programming/gentle-shell?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="GitHub stars"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell"><img src="https://img.shields.io/github/last-commit/Gentleman-Programming/gentle-shell?style=for-the-badge&labelColor=1A1218&color=D7A0B8" alt="Last commit"></a>
 </p>
 
 <p align="center">
@@ -37,7 +37,7 @@
 <p align="center"><strong>BUILT FOR PI</strong> &nbsp;·&nbsp; Coding-agent workspace &nbsp;·&nbsp; Focused agents &nbsp;·&nbsp; ODD</p>
 
 <p align="center">
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/stargazers"><strong>★ Star gentle-shell on GitHub</strong></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/stargazers"><strong>★ Star gentle-shell on GitHub</strong></a>
 </p>
 
 <div align="center">
@@ -185,13 +185,13 @@ Extension commands are only useful if you can find them. `alt+k` opens a curated
 
 ---
 
-### What's new in v2.6.0
+### What's new in v3.5
 
-The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) brings a more persistent, inspectable Pi workspace:
+The [v3.5.1 release](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1) makes Gentle Shell runnable on its own:
 
-- **Shell:** `/gentle:changes` groups captured write/edit changes from the current agent session and its subagents, without startup repository scans; fullscreen navigation, sidebars, and mouse support stay available. See the [capture limits and shell-command coverage](docs/gentle-shell.md#what-appears-in-changes).
-- **Agents and profiles:** the Agents view shows orchestrator/session hierarchy, retained completion, abort, and lost-exit history, parent-child handoff, and model, effort, and usage observability. Named `/gentle:profiles` atomically route the orchestrator independently from packaged and review roles; applying one replaces the routing of every agent, a repository can be pinned to a profile with `p` so its subagent launches stop following the globally active profile, and the panel shows the routing the runtime actually uses even when `models.json` is sparse.
-- **Control and recovery:** native SDD requires parent-confirmed preflight; native review supports intended-untracked selection, consent, and provider continuations. Subsystems install with explicit recovery guidance when npm lifecycle scripts were skipped; Pi Git installs are recognized globally; custom ask responses are opt-in. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
+- **Standalone launcher:** `npm i -g gentle-pi` installs `gentle-shell`, which opens Pi with the Gentle Shell package loaded from its own home (`~/.gentle-shell/agent`) or, with `--link`, from your existing `~/.pi/agent`; `gentle-shell install npm:<pkg>` and the other pi subcommands run against the selected home. A bundled or `PATH` pi is used, never a modified one.
+- **Link mode take-over:** when `~/.pi/agent` already declares gentle-pi as a path package, the launcher takes over extension loading (`--no-extensions` plus explicit `-e` for every other declared package and loose extension) so tools never register twice.
+- **Interactive RPC hosts:** with `GENTLE_SHELL_INTERACTIVE_HOST=1` and `--mode rpc`, ask-user tools use pi's RPC dialogs and gentle-agents publishes live subagent activity for the desktop app. See the [reference](docs/readme-reference.md#interactive-rpc-hosts).
 
 ---
 
@@ -203,13 +203,38 @@ The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases
 
 ## Get started
 
-Install the stable release, restart Pi, then synchronize the installed assets.
-
 > **Naming transition:** The product is called `gentle-shell`; the current npm package and repository remain `gentle-pi` until migration.
 
+### Path A: standalone `gentle-shell` (recommended, no pi changes)
+
+`gentle-shell` opens Pi with the Gentle Shell package loaded, without installing it into your pi agent or editing its `settings.json`.
+
+```bash
+npm i -g gentle-pi
+
+# Own home, never touches your pi install
+gentle-shell
+
+# Reuse your pi sign-ins, models and chats instead
+gentle-shell --link
+```
+
+`gentle-shell` alone starts in its own home, `~/.gentle-shell/agent`. `gentle-shell --link` reuses `~/.pi/agent` as-is.
+
 ```bash
-# Published stable release: v2.6.0
-pi install npm:gentle-pi@2.6.0
+# Make --link the default
+gentle-shell home link
+```
+
+Every other argument is forwarded to pi unchanged, for example `gentle-shell --mode rpc` or `gentle-shell -p "..."`. Full flags, env vars, and modes: **[launcher reference](docs/readme-reference.md#gentle-shell-launcher)**.
+
+### Path B: inside an existing pi
+
+Install the stable release into an existing pi agent, restart Pi, then synchronize the installed assets.
+
+```bash
+# Published stable release: v3.5.1
+pi install npm:gentle-pi@3.5.1
 
 # Restart Pi, then run:
 gentle-ai sync
@@ -218,7 +243,7 @@ gentle-ai sync
 pi
 ```
 
-See the [v2.6.0 release notes](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) for version-specific changes.
+See the [v3.5.1 release notes](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1) for version-specific changes.
 
 ```text
 /gentle:status
@@ -233,29 +258,6 @@ See the [v2.6.0 release notes](https://github.com/Gentleman-Programming/gentle-p
 
 For prerequisites, source-checkout instructions, full install behavior, and release policy, use the **[installation reference](docs/readme-reference.md#install)**. For everyday work, describe the outcome and follow [ODD](#odd--the-everyday-workflow).
 
-### Without touching your pi
-
-`gentle-shell` opens Pi with the Gentle Shell package loaded, without installing it into your pi agent or editing its `settings.json`.
-
-```bash
-npm i -g gentle-pi
-
-# Own home, never touches your pi install
-gentle-shell
-
-# Reuse your pi sign-ins, models and chats instead
-gentle-shell --link
-```
-
-`gentle-shell` alone starts in its own home, `~/.gentle-shell/agent`. `gentle-shell --link` reuses `~/.pi/agent` as-is.
-
-```bash
-# Make --link the default
-gentle-shell home link
-```
-
-Every other argument is forwarded to pi unchanged, for example `gentle-shell --mode rpc` or `gentle-shell -p "..."`. Full flags, env vars, and modes: **[launcher reference](docs/readme-reference.md#gentle-shell-launcher)**.
-
 <p align="right"><a href="#top">Back to top ↑</a></p>
 
 <p align="center">
@@ -287,17 +289,17 @@ Start with the product-facing destination, then move into the operational refere
 This project is built in public. Bring a real workflow, a sharp question, a bug report, or a small improvement that makes the next person’s work clearer.
 
 <p align="center">
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/issues"><img src="https://img.shields.io/badge/Issues-join%20the%20conversation-F095C8?style=for-the-badge&labelColor=1A1218" alt="GitHub issues"></a>
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/graphs/contributors"><img src="https://img.shields.io/badge/Contributors-thank%20you-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="Contributors"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/issues"><img src="https://img.shields.io/badge/Issues-join%20the%20conversation-F095C8?style=for-the-badge&labelColor=1A1218" alt="GitHub issues"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/graphs/contributors"><img src="https://img.shields.io/badge/Contributors-thank%20you-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="Contributors"></a>
   <a href="https://discord.com/invite/gentleman-programming-769863833996754944"><img src="https://img.shields.io/badge/Discord-Gentleman%20Programming-F095C8?style=for-the-badge&labelColor=1A1218" alt="Gentleman Programming Discord"></a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/Gentleman-Programming/gentle-pi/graphs/contributors"><img src="https://contrib.rocks/image?repo=Gentleman-Programming/gentle-pi" alt="gentle-shell contributors"></a>
+  <a href="https://github.com/Gentleman-Programming/gentle-shell/graphs/contributors"><img src="https://contrib.rocks/image?repo=Gentleman-Programming/gentle-shell" alt="gentle-shell contributors"></a>
 </p>
 
-- Open an [issue](https://github.com/Gentleman-Programming/gentle-pi/issues) with the context needed to reproduce or understand the idea.
-- See the people shaping the project in the [contributors graph](https://github.com/Gentleman-Programming/gentle-pi/graphs/contributors).
+- Open an [issue](https://github.com/Gentleman-Programming/gentle-shell/issues) with the context needed to reproduce or understand the idea.
+- See the people shaping the project in the [contributors graph](https://github.com/Gentleman-Programming/gentle-shell/graphs/contributors).
 - Follow [Gentleman Programming](https://github.com/Gentleman-Programming) for the wider ecosystem.
 
 <p align="right"><a href="#top">Back to top ↑</a></p>

package/bin/gentle-shell.mjs

@@ -4,7 +4,7 @@
 // resolution, pi resolution order, the version gate, and the pi invocation —
 // lives in that pure, unit-tested module; this file only wires it to the real
 // process, filesystem, and child process.
-import { accessSync, constants as fsConstants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { constants as osConstants, homedir } from "node:os";
 import { delimiter, dirname, join, resolve as resolvePath } from "node:path";
@@ -13,16 +13,19 @@ import { fileURLToPath } from "node:url";
 import {
 	buildPiInvocation,
 	checkPiVersion,
+	decideTakeOver,
 	describeVersion,
+	discoverLooseExtensionEntries,
+	findGentlePiDeclaration,
 	helpText,
 	launcherConfigPath,
 	missingPiMessage,
+	otherPackageInjections,
 	parseLauncherArgs,
 	parseLauncherConfig,
 	planSpawn,
 	resolveHome,
 	resolvePiRuntime,
-	settingsDeclareGentlePi,
 } from "../runtime/gentle-shell-launcher.mjs";
 import { installIsolatedTuiModeSetting } from "../scripts/install-tui-mode-setting.mjs";
 
@@ -83,7 +86,119 @@ function ownPackageVersion() {
 }
 
 function emptyArgs() {
-	return { link: false, isolated: false, home: undefined, help: false, version: false, command: undefined, commandArgs: [], passthrough: [], error: undefined };
+	return {
+		link: false,
+		isolated: false,
+		home: undefined,
+		packageRoot: undefined,
+		help: false,
+		version: false,
+		command: undefined,
+		commandArgs: [],
+		passthrough: [],
+		piSubcommand: undefined,
+		error: undefined,
+	};
+}
+
+// package.json "name" reader injected into findGentlePiDeclaration: a
+// missing or unreadable package.json, or a non-string "name", is never an
+// error here — it just means that path package is not gentle-pi.
+function readPackageName(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		return typeof pkg.name === "string" ? pkg.name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// Best-effort realpath: a directory that does not exist (yet, or ever)
+// cannot be realpath'd, so the take-over decision falls back to comparing
+// the raw path instead of failing.
+function safeRealpath(path) {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}
+
+// Used to filter the loose extension dirs a take-over re-injects: a missing
+// path, or one that is not a directory (for example a stray file named
+// "extensions"), is silently excluded rather than passed to pi as -e.
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+// Real-fs adapter for discoverLooseExtensionEntries (lib/gentle-shell-launcher.ts):
+// statSync-based isFile/isDirectory (not readdirSync's Dirent, which uses
+// lstat and so would treat a symlinked file or directory as neither) so a
+// symlinked loose extension resolves the same way pi's own fs.existsSync-based
+// checks would.
+const looseExtensionFs = {
+	readdir(dir) {
+		let names;
+		try {
+			names = readdirSync(dir);
+		} catch (error) {
+			// resolveLooseExtensionEntries only calls this once isDirectory(dir)
+			// has already confirmed the directory exists, so a failure here (for
+			// example EACCES) is a real read failure, not a missing directory.
+			// Warn instead of silently dropping every loose extension it would
+			// have contributed (R4-loose-extension-enumeration-fails-silently).
+			process.stderr.write(`gentle-shell: could not read loose extension directory ${dir}: ${error.message} (skipping)\n`);
+			return [];
+		}
+		return names.map((name) => {
+			const entryPath = join(dir, name);
+			try {
+				const entryStat = statSync(entryPath);
+				return { name, isFile: entryStat.isFile(), isDirectory: entryStat.isDirectory() };
+			} catch {
+				return { name, isFile: false, isDirectory: false };
+			}
+		});
+	},
+	exists: existsSync,
+};
+
+// A loose extensions directory that is itself a self-contained extension —
+// a package.json declaring a non-empty "pi.extensions" manifest — is passed
+// through as a single -e <dir> instead of being broken into per-file
+// entries: pi's own module loader (jiti) resolves that case directly,
+// exactly as it would for any other explicitly configured package path. A
+// root-level index.ts/index.js is deliberately NOT treated as that same
+// marker: pi's own discovery loads it as just another loose file, so
+// collapsing the whole directory on its presence silently dropped sibling
+// loose files like extra.ts (R4-loose-index-collapses-sibling-extensions).
+function readPiManifestExtensions(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		return Array.isArray(pkg?.pi?.extensions) ? pkg.pi.extensions : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function looseDirHasOwnEntryPoint(dir) {
+	const manifestExtensions = readPiManifestExtensions(dir);
+	return manifestExtensions !== undefined && manifestExtensions.length > 0;
+}
+
+// Resolves one candidate loose-extensions directory (<agentDir>/extensions or
+// <cwd>/.pi/extensions) into the -e entries a take-over must re-inject: the
+// directory itself when it is a self-contained extension, otherwise every
+// loose file discoverLooseExtensionEntries finds inside it. A missing or
+// non-directory candidate resolves to no entries.
+function resolveLooseExtensionEntries(dir) {
+	if (!isDirectory(dir)) return [];
+	if (looseDirHasOwnEntryPoint(dir)) return [dir];
+	return discoverLooseExtensionEntries(dir, looseExtensionFs);
 }
 
 function loadConfig() {
@@ -165,17 +280,77 @@ async function main() {
 		process.stderr.write(`gentle-shell: using a separate home at ${home.dir}. Run 'gentle-shell --link' to reuse your pi sign-ins and chats.\n`);
 	}
 
-	let linkDeclaresGentlePi = false;
-	if (home.mode === "link") {
+	const packageRootExplicit = args.packageRoot !== undefined;
+	const effectivePackageRoot = packageRootExplicit ? resolvePath(args.packageRoot) : packageRoot;
+	// R4-forced-package-root-unvalidated / R3-005: an unvalidated --package-root
+	// forces a take-over (dropping normal extension discovery via
+	// --no-extensions) and then hands pi -e/--theme/--skill/--prompt-template
+	// flags pointing at directories that do not exist, turning an operator typo
+	// into an obscure pi loader failure instead of a clear launcher error.
+	if (packageRootExplicit && !isDirectory(effectivePackageRoot)) {
+		fail(`--package-root ${args.packageRoot} does not exist or is not a directory.`, 2);
+	}
+
+	let declaration;
+	let takeOver = false;
+	let otherPackagePaths = [];
+	let looseExtensionEntries = [];
+
+	// Only --link can read another gentle-pi declaration out of a real
+	// settings.json; isolated and --home homes never declare one, so they
+	// always get the plain injection (declaration stays undefined) unless
+	// --package-root itself forces a take-over below. A pi subcommand skips
+	// this whole block: buildPiInvocation ignores takeOver/declaration once
+	// piSubcommand is set, and running the take-over/loose-dir discovery
+	// anyway would still print a misleading "taking over gentle-pi..."
+	// message (and otherPackageInjections warnings) for a plain
+	// `gentle-shell install npm:x` that never actually takes anything over.
+	if (home.mode === "link" && args.piSubcommand === undefined) {
 		const settingsText = readJsonIfExists(join(home.dir, "settings.json"));
-		linkDeclaresGentlePi = settingsDeclareGentlePi(settingsText);
+		declaration = findGentlePiDeclaration(settingsText, { agentDir: home.dir, readPackageName });
+		const realEffectivePackageRoot = safeRealpath(effectivePackageRoot);
+		const realDeclaredDir = declaration?.kind === "path" ? safeRealpath(declaration.dir) : undefined;
+		takeOver = decideTakeOver({
+			declaration,
+			realPackageRoot: realEffectivePackageRoot,
+			realDeclaredDir,
+			packageRootExplicit,
+		});
+		if (takeOver) {
+			const skip = declaration ?? { kind: "path", dir: realEffectivePackageRoot };
+			const injections = otherPackageInjections({ settingsText, agentDir: home.dir, skip, isDirectory, realpath: safeRealpath });
+			otherPackagePaths = injections.paths;
+			for (const warning of injections.warnings) process.stderr.write(`${warning}\n`);
+			// --no-extensions drops pi's normal settings-driven extension
+			// discovery, which also covers loose (non-package) extensions
+			// under <agentDir>/extensions and the project-local
+			// <cwd>/.pi/extensions. Re-injecting either directory wholesale
+			// as `-e <dir>` does not work for a directory of loose files: pi's
+			// -e flag hands the path straight to its module loader with no
+			// directory-discovery pass, so a bare directory of loose files
+			// fails with "Cannot find module ...". Resolve each candidate
+			// into its actual loose file entries (or pass it through
+			// unchanged when it is itself a self-contained extension) so a
+			// take-over does not silently stop loading them.
+			looseExtensionEntries = [join(home.dir, "extensions"), join(process.cwd(), ".pi", "extensions")].flatMap(resolveLooseExtensionEntries);
+			const declaredFrom = declaration === undefined ? "the requested package root" : declaration.kind === "npm" ? "npm:gentle-pi" : declaration.dir;
+			process.stderr.write(
+				`gentle-shell: taking over gentle-pi from ${declaredFrom} for this run (settings unchanged; its skills, prompts, and themes still load alongside this launcher's).\n`,
+			);
+		}
 	}
+	// Isolated and --home homes have no declaration to take over: declaration
+	// stays undefined and buildPiInvocation injects effectivePackageRoot the
+	// same way it always has, --package-root included.
 
 	const invocation = buildPiInvocation({
 		runtime,
 		home,
-		packageRoot,
-		settingsDeclareGentlePi: home.mode === "link" ? linkDeclaresGentlePi : false,
+		packageRoot: effectivePackageRoot,
+		declaration,
+		takeOver,
+		otherPackagePaths,
+		looseExtensionEntries,
 		passthrough: args.passthrough,
 		piSubcommand: args.piSubcommand,
 		baseEnv: process.env,

package/docs/readme-reference.md

@@ -135,15 +135,33 @@ Callers own keyboard policy, theme state, and business actions.
 
 ## Install
 
+Two paths reach the same package. Path A stays standalone; Path B installs into an existing pi.
+
+### Path A: standalone `gentle-shell` (recommended, no pi changes)
+
 ```bash
-pi install npm:gentle-pi@2.6.0
+npm i -g gentle-pi
+
+# Own home, never touches your pi install
+gentle-shell
+
+# Reuse your pi sign-ins, models and chats instead
+gentle-shell --link
 ```
 
-The stable release is [`v2.6.0`](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0). Restart Pi after installation, then run `gentle-ai sync`. That published release pairs with Gentle AI `v2.8.0` and provider contract `1.2.0`; capabilities `v2.5` are retained. The command above installs that exact published version.
+`gentle-shell` alone starts in its own home, `~/.gentle-shell/agent`. `gentle-shell --link` reuses `~/.pi/agent` as-is. Run `gentle-shell home link` to make `--link` the default. Full flags, env vars, and modes: [gentle-shell launcher](#gentle-shell-launcher).
+
+### Path B: inside an existing pi
+
+```bash
+pi install npm:gentle-pi@3.5.1
+```
+
+The stable release is [`v3.5.1`](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1). Restart Pi after installation, then run `gentle-ai sync`. That published release pairs with Gentle AI `v2.8.0` and provider contract `1.2.0`; capabilities `v2.5` are retained. The command above installs that exact published version.
 
 ### Source checkout
 
-This checkout prepares `gentle-pi` `3.4.0`; it is source state, not a published release. Its package-local native runtime pin is Gentle AI `v3.5.0`, distinct from the published `v2.6.0` pairing.
+This checkout prepares `gentle-pi` `3.5.1`; it is source state, not a published release. Its package-local native runtime pin is Gentle AI `v3.5.0`, distinct from the published `v3.5.1` pairing.
 
 The native SDD status consumer accepts both the pinned producer's legacy
 `apply`/`verify`/`remediate`/`archive` instruction record and the classical
@@ -161,13 +179,13 @@ Classical direct-archive behavior is compatibility-tested with an identified
 upstream development build, not presented as a published fix or version bump.
 The complete classical flow awaits a compatible published native version; this
 change does not bump the pin. Ordinary attempt governance and research/planning simplification remain separate
-work under [SDD parity #1051](https://github.com/Gentleman-Programming/gentle-pi/issues/1051).
+work under [SDD parity #1051](https://github.com/Gentleman-Programming/gentle-shell/issues/1051).
 
 ### Pi compatibility
 
 The current package requires Pi 0.85.1 or newer (development tests pin 0.85.1). Use the latest Pi release; gentle-pi does not update your installed Pi automatically. Children, including any `GENTLE_PI_AGENTS_PI` override, must emit `agent_settled`: `agent_end` records a run's output but is not completion because retries or queued continuations may follow.
 
-The [`v2.6.0` release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) adds persistent registered worktrees and grouped `/gentle:changes` views; fuller workspace interaction details are in the [Gentle Shell reference](gentle-shell.md). It also adds named atomic `/gentle:profiles`, parent-confirmed native SDD preflight transport, native review intended-untracked selection and provider continuations, and opt-in custom ask responses. Pi recognizes its global Git-managed package path; subsystems install with explicit recovery guidance when npm lifecycle work was skipped. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
+The [`v2.6.0` release](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v2.6.0) added persistent registered worktrees and grouped `/gentle:changes` views; fuller workspace interaction details are in the [Gentle Shell reference](gentle-shell.md). It also adds named atomic `/gentle:profiles`, parent-confirmed native SDD preflight transport, native review intended-untracked selection and provider continuations, and opt-in custom ask responses. Pi recognizes its global Git-managed package path; subsystems install with explicit recovery guidance when npm lifecycle work was skipped. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
 
 ### Install-time fullscreen
 
@@ -179,18 +197,30 @@ Malformed/nonobject JSON, symlink/nonregular settings, unsafe paths, or a busy s
 
 ### RDD history and opt-in
 
-Native RDD was introduced in `gentle-pi` `v0.15.0` on 2026-07-10 with bounded review transactions. The current stable release, [`v2.6.0`](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0), includes native RDD:
+Native RDD was introduced in `gentle-pi` `v0.15.0` on 2026-07-10 with bounded review transactions. The current stable release, [`v3.5.1`](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1), includes native RDD:
 
 ```bash
 # Stable release
-pi install npm:gentle-pi@2.6.0
+pi install npm:gentle-pi@3.5.1
 ```
 
 RDD remains opt-in. Enable it only through an explicit user decision with `/gentle:review-mode enable`; `status` lets you inspect the mode without changing it.
 
 The source checkout's RDD integration installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned release assets with asset and executable SHA-256 verification (signed archives for source pin `v3.5.0`; raw prerelease binaries only under a prerelease pin). Windows x64 and arm64 build the exact `v3.5.0` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error. To recover explicitly, if `GENTLE_PI_SKIP_GENTLE_AI_INSTALL` is set, remove or unset it before changing to the installed `gentle-pi` package directory. Then run `node scripts/install-gentle-ai.mjs`. This invokes the package-owned installer without relying on a global binary or npm configuration change. A missing binary can result from skipped lifecycle scripts, but does not prove that lifecycle scripts were disabled.
 
-Recommended companion packages:
+Recommended companion packages, into the standalone `gentle-shell` home:
+
+```bash
+gentle-shell install npm:pi-intercom
+gentle-shell install npm:gentle-engram
+gentle-shell install npm:pi-web-access
+gentle-shell install npm:pi-lens
+gentle-shell install npm:@juicesharp/rpiv-ask-user-question
+```
+
+`--link` before the subcommand (for example `gentle-shell --link install npm:pi-intercom`) targets `~/.pi/agent` instead of the isolated home.
+
+Or, when `gentle-pi` is installed inside an existing pi:
 
 ```bash
 pi install npm:pi-intercom
@@ -241,6 +271,7 @@ gentle-shell home [link|isolated|<path>]
 | `--link` | Home is `PI_CODING_AGENT_DIR` or `~/.pi/agent`. Reuses your existing pi sign-ins, models, and chats; never writes to its `settings.json`. |
 | `--isolated` | Home is `GENTLE_SHELL_HOME` or `~/.gentle-shell/agent`. No credential seeding. Default when nothing else is configured. |
 | `--home <path>` | Home is the given directory. |
+| `--package-root <dir>` | Force this directory as the gentle-pi package to load, taking over from any conflicting package the target `settings.json` already declares (see "Loading the package" below). |
 | `--help`, `-h` | Print usage (flags, commands, env vars) and exit 0. |
 | `--version` | Print `gentle-shell <version>`, `pi <version>`, and `home <mode> <dir>`, then exit 0. |
 | `--` | Everything after is forwarded to pi verbatim, even text that looks like a `gentle-shell` flag. |
@@ -255,6 +286,8 @@ gentle-shell home [link|isolated|<path>]
 
 `gentle-shell install npm:<pkg>`, `gentle-shell remove ...`, `gentle-shell list`, `gentle-shell update ...`, `gentle-shell config`, and `gentle-shell auth ...` run pi's own commands against the resolved home — the `--isolated` home by default, or your own pi home with `--link`. A launcher flag before the subcommand (`--link`, `--isolated`, `--home <path>`) still selects which home the subcommand runs against. Running `gentle-shell install npm:gentle-pi` inside the isolated home is unnecessary: the launcher already loads the Gentle Shell package itself (see "Loading the package" below).
 
+`gentle-shell update` and `gentle-shell list` follow that same home selection, so they inspect and update packages in whichever home the effective flag or persisted `home` config points to.
+
 ### pi runtime resolution
 
 1. `GENTLE_SHELL_PI` — path to a pi executable, when set to a non-empty value.
@@ -274,7 +307,25 @@ If none resolve, `gentle-shell` exits 1 naming all three options. Once a runtime
 
 ### Loading the package
 
-Unless the target home's `settings.json` already lists `npm:gentle-pi` in its `packages` array (checked only for `--link`), every invocation injects `-e <package root> --theme <root>/themes --skill <root>/skills --prompt-template <root>/prompts` ahead of the forwarded arguments, so the Gentle Shell extensions, themes, skills, and prompt templates load without a separate `pi install`. Isolated and `--home <path>` homes never declare the package, so they always get the injection — except when the forwarded arguments start with one of pi's own subcommands (`install`, `remove`, `uninstall`, `update`, `list`, `config`, `auth`): pi dispatches those on `argv[0]` before it parses any flags, so the injection is skipped entirely and pi sees the bare subcommand, e.g. `gentle-shell install npm:x` runs exactly `pi install npm:x`.
+Unless the target home's `settings.json` already declares gentle-pi (checked only for `--link`), every invocation injects `-e <package root> --theme <root>/themes --skill <root>/skills --prompt-template <root>/prompts` ahead of the forwarded arguments, so the Gentle Shell extensions, themes, skills, and prompt templates load without a separate `pi install`. Isolated and `--home <path>` homes never declare the package, so they always get this injection — except when the forwarded arguments start with one of pi's own subcommands (`install`, `remove`, `uninstall`, `update`, `list`, `config`, `auth`): pi dispatches those on `argv[0]` before it parses any flags, so the injection — and any take-over below — is skipped entirely and pi sees the bare subcommand, e.g. `gentle-shell install npm:x` runs exactly `pi install npm:x`. A subcommand never triggers a take-over, even against a home whose settings declare a conflicting gentle-pi; see "Managing packages" above.
+
+A declaration is recognized either as `npm:gentle-pi[@version]` in the `packages` array, or as a local path package (string or `{"source": "..."}` entry, relative or absolute) whose own `package.json` names it `"gentle-pi"` — the shape produced when gentle-pi is developed from a checkout and referenced by path in `settings.json` instead of installed via `pi install npm:gentle-pi`.
+
+- **A pi subcommand as the first forwarded argument**: no injection and no take-over at all, regardless of any declaration — pi must see the bare subcommand as `argv[0]`.
+- **npm declaration matching this launcher's own install**: no injection — pi already loads gentle-pi from the declared package.
+- **No declaration at all, or a path declaration that resolves (after `realpath`) to this launcher's own package root**: the same plain injection as above.
+- **A declaration that resolves to a *different* gentle-pi** (a different checkout declared by path, for example) **— take-over**: `gentle-shell` prints `taking over gentle-pi from <declared source> for this run (settings unchanged; its skills, prompts, and themes still load alongside this launcher's)` to stderr, then runs pi with `--no-extensions` followed by an explicit `-e <dir>` for every *other* package already in settings (npm entries resolve to `<agent dir>/npm/node_modules/<name>`; path entries resolve relative to the settings file), then loose extension entries for `<agent dir>/extensions` and the project-local `<cwd>/.pi/extensions` (each candidate directory only consulted when it already exists), and finally its own `-e <package root> --theme ... --skill ... --prompt-template ...`. `settings.json` itself is never modified, and every `-e` path — including the launcher's own package root — is injected at most once even if it would otherwise repeat.
+
+  A declared *other* package whose resolved directory does not actually exist (a hand-edited `settings.json`, a failed or interrupted `pi install`, or an npm store laid out anywhere other than `<agent dir>/npm/node_modules`) is skipped with a stderr warning naming the source and the resolved path, instead of being handed to pi as an unresolvable `-e` that would fail the whole launch with "Cannot find module".
+
+  `--no-extensions` disables pi's normal directory-discovery pass, and pi's `-e` flag hands a path straight to its module loader with no discovery of its own — passing a loose extensions directory as-is via `-e <dir>` fails with "Cannot find module" unless that directory is itself a self-contained extension. So each loose candidate directory is resolved before injection: a directory that is itself a self-contained extension (a `package.json` declaring a `pi.extensions` manifest) is passed through as a single `-e <dir>`; otherwise its direct `*.ts`/`*.js`/`*.mjs` files — including a root-level `index.ts`/`index.js`, which is just another loose file — and any `<subdir>/index.ts`/`index.js` are discovered individually — mirroring pi's own directory scan — and each is injected as its own `-e <file>`. Hidden entries (dotfiles) and `*.d.ts` declaration files are skipped, since neither was ever a runnable extension.
+
+  A git-sourced other package is skipped with a stderr warning, since its install directory cannot be derived without pi's own package manager; an object entry with `extensions` or `autoload` filters is still included but warned about, because the take-over cannot honor those filters for extension discovery — that package's skills, prompts, and themes still load normally through settings discovery, which `--no-extensions` does not affect.
+
+  **Known limitation**: the take-over never removes the original declaration from `settings.json`, so its skills, prompt templates, and themes are still discovered alongside this launcher's own — only its extensions are replaced by `--no-extensions` plus the injected `-e` flags above.
+- **`--package-root <dir>`**: forces a take-over using `<dir>` as the package root, even when settings already declare a matching `npm:gentle-pi`, or when there is no declaration at all. Use it to test a different gentle-pi checkout against a home whose settings already point at another one. Has no effect when the forwarded arguments start with a pi subcommand, since a subcommand skips the take-over entirely. The take-over path itself is only ever reached for `--link`: with `--isolated` or `--home <path>`, `--package-root` still changes which directory is injected, but always through the same plain injection as "no declaration at all" above — no `--no-extensions`, and no other-package or loose-extension re-injection — since those homes never carry a `settings.json` declaration to take over from. `--package-root` must also name an existing directory; a missing or non-directory path fails fast with a clear error instead of launching pi with unresolvable flags.
+
+This take-over exists because two gentle-pi copies loaded at once — the declared one plus this launcher's own injection — register the same tools and extensions twice, which pi reports as tool conflicts (for example `Tool ask_user_choice conflicts with ...`).
 
 ### First run in an isolated or custom home
 
@@ -375,7 +426,7 @@ Reconciliation is intentionally narrow: native code may quarantine only the boun
 
 Native lifecycle status remains informational. VALIDATE does not authorize delivery; commit, push, PR, and release commands follow ordinary repository policy. Recovery grants no new budget, and legacy graph bundle export/import is retired.
 
-This is the post-U8 boundary, not the final architecture. [Issue #191](https://github.com/Gentleman-Programming/gentle-pi/issues/191) is the immediate final unit in this same delivery: extract the remaining Pi command-projection and lifecycle-gate surface from `review-transaction.ts`, repoint runtime enforcement, then delete only dependencies proven unreachable without weakening graph-v1 Judgment Day. The branch-wide High-tier 4R runs after that extraction, before the single size-exception PR.
+This is the post-U8 boundary, not the final architecture. [Issue #191](https://github.com/Gentleman-Programming/gentle-shell/issues/191) is the immediate final unit in this same delivery: extract the remaining Pi command-projection and lifecycle-gate surface from `review-transaction.ts`, repoint runtime enforcement, then delete only dependencies proven unreachable without weakening graph-v1 Judgment Day. The branch-wide High-tier 4R runs after that extraction, before the single size-exception PR.
 
 ### Review Lens Selection (architecture reference)
 
@@ -1138,10 +1189,10 @@ tag="v${version}"
 git fetch --no-tags origin "refs/tags/${tag}"
 test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "$(git rev-parse "${tag}^{commit}")"
 gh workflow run publish.yml \
-  --repo Gentleman-Programming/gentle-pi \
+  --repo Gentleman-Programming/gentle-shell \
   --ref main \
   -f tag="${tag}"
-gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
+gh run watch <run-id> --repo Gentleman-Programming/gentle-shell --exit-status
 npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
 npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
 ```