gentle-pi 3.3.0 → 3.5.0

package/README.md

@@ -1,7 +1,7 @@
 <a id="top"></a>
 
 <div align="center">
-  <img src="docs/assets/brand/gentle-pi-banner.png" width="1200" alt="gentle-shell — Ecosystem, Agent, One shell">
+  <img src="docs/assets/brand/gentle-shell-banner.gif" width="1200" alt="gentle-shell — Ecosystem, Agent, One shell">
 </div>
 
 <h1 align="center">gentle-shell™</h1>
@@ -34,7 +34,7 @@
 
 <p align="center"><sub>One workspace. A coding agent you direct. A workflow you can inspect.</sub></p>
 
-<p align="center"><strong>BUILT FOR PI</strong> &nbsp;·&nbsp; Coding-agent workspace &nbsp;·&nbsp; Focused agents &nbsp;·&nbsp; ODD + optional SDD</p>
+<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>
@@ -74,122 +74,126 @@
 
 ### gentle-shell — Your coding agent, in the workspace you lead
 
-<p align="center">
-  <img src="docs/assets/features/gentle-shell.png" width="1200" alt="gentle-shell showing an SDD agent task, todo list, changes summary, status bar, and usage footer in Pi">
-</p>
+<img width="100%" src="https://github.com/user-attachments/assets/5d9eefc2-7b2a-48f8-b212-1439834ce195" alt="gentle-shell running a live agent session: a header row with branch, model, and context gauge above the transcript, with status, changes, and todo cards in the right rail">
 
-<strong>A complete workspace for the agent you direct.</strong> gentle-shell is your coding agent, built for Pi, with native workspace features for agent orchestration, usage monitoring for supported provider accounts, and built-in diff views—all in one integrated layout.
-
-See active tasks, session changes, and runtime status without leaving the work you are leading.
+A bare terminal answers "what is the agent doing?" only with scrollback. gentle-shell turns your Pi session into a workspace: agent orchestration, live changes and runtime status, usage monitoring for supported provider accounts, and built-in diff views — so you lead the work instead of chasing it.
 
 <p align="center"><sub>gentle-shell in action. Screenshot from <a href="https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/docs/assets/features/gentle-shell.png">Gentle-AI</a>.</sub></p>
 
-**[→ Read the gentle-shell reference](docs/gentle-shell.md)**
+**[Docs →](docs/gentle-shell.md)**
 
 ---
 
 ### el Gentleman — Think before you build
 
-<p align="center">
-  <img src="docs/assets/diagrams/gentleman-workflow.svg" width="1200" alt="Diagram of el Gentleman turning human intent into clarified scope, a smallest workflow choice, evidence, and a human delivery decision">
-</p>
-
-Say what you need once, then keep moving. el Gentleman helps turn intent into clear scope, a sensible next step, and evidence people can review—without making every task feel like a process meeting.
+<img width="100%" src="docs/assets/diagrams/gentleman-workflow.svg" alt="Diagram of el Gentleman turning human intent into clarified scope, a smallest workflow choice, evidence, and a human delivery decision">
 
-**[→ Follow the organic workflow and recovery](docs/readme-reference.md#organic-driven-development)**
+Say what you need once, then keep moving. el Gentleman helps turn intent into clear scope, a sensible next step, and evidence people can review — without making every task feel like a process meeting.
 
-**[→ See persona modes and routing](docs/readme-reference.md#persona-modes)**
+**[Docs →](docs/readme-reference.md#organic-driven-development)**
 
 ---
 
 ### Focused agents — Context with a return path
 
-<p align="center">
-  <img src="docs/assets/diagrams/agent-orchestration.svg" width="1200" alt="Diagram of one parent session directing bounded map, implementation, and verification work and receiving evidence back">
-</p>
+<img width="100%" src="docs/assets/diagrams/agent-orchestration.svg" alt="Diagram of one parent session directing bounded map, implementation, and verification work and receiving evidence back">
 
 Bring in help without losing the thread. Focused package-owned Pi agents can map a codebase, implement a bounded change, or verify it, while one parent stays accountable for the scope, the decisions, and the final summary.
 
-**[→ Learn how work is routed](docs/readme-reference.md#how-the-harness-decides-what-to-do)**
-
-- `orchestrator_session_id`, `orchestrator_list`, and `orchestrator_send_message` provide local-profile session notifications. List results advertise IDs only and reachability remains unknown. Sending selects the sole advertised peer or asks the user to choose; a successful ACK means the peer accepted the notification for delivery, not that it read or completed work. This is notification-and-ACK transport only: it has no cross-session queries, offline queue, retries, broadcasts, or read/completion guarantees. On Unix, presence records remain in the profile's private transport directory while socket endpoints use a private, profile-hashed directory below the canonical system temporary directory, keeping endpoint length independent of the profile path and at most 100 encoded bytes. The shared system temporary parent is only validated (current-user-owned without group/other write, or root/current-user-owned, world-writable, and sticky); it is never claimed, permissioned, or cleaned up by gentle-pi. On Windows, the transport selects a package-local PowerShell helper for a Windows named pipe; availability and delivery depend on the helper's bounded startup and pipe checks.
+**[Docs →](docs/readme-reference.md#how-the-harness-decides-what-to-do)**
 
 ---
 
 ### ODD — The everyday workflow
 
-**Organic Driven Development (ODD)** is the recommended path for everyday work: explore the code, clarify real decisions, implement authorized changes, and run proportionate checks. Ask for an outcome, for example: "Add CSV export using the existing report filters." Small/read-only work needs no durable implementation artifacts; substantial work can use focused workers without entering SDD.
+<img width="100%" src="docs/assets/diagrams/odd-workflow.svg" alt="Organic Driven Development as seven numbered steps: Authorize, Explore, Resolve uncertainty, and Classify across the top row; Classify forks, so small understood work stays light while substantial work gets step five, Track, with one feature document; both paths converge on Implement task by task and then Close, above a dashed band marking that one feature document mirrored in Engram lets work resume across sessions">
+
+**Organic Driven Development (ODD)** is the everyday path: the agent explores before changing anything, clarifies only real decisions, and keeps small understood work small. Substantial, authorized work gets one recoverable feature document — mirrored in memory when available — so progress, evidence, and the next step survive an interruption; checks follow the configured TDD mode.
 
-One `odd/tasks/<feature-name>.md` keeps objective/problem/why, scope/constraints, actionable tasks, evidence, progress, next step, and meaningful accepted-change rationale. Engram mirrors the full document under project-scoped `odd/<feature-name>/tasks`; accepted changes update intent and affected tasks while preserving valid completed work. Memory is separately installed; if unavailable, local progress survives with an explicitly pending mirror.
+**[Docs →](docs/readme-reference.md#organic-driven-development)**
 
-TDD follows configured mode, source, and exact runner, forwarded to workers and refreshed on resume. Tests existing does not enable it; disabled TDD still runs functional checks. Native RDD is separate and user-owned.
+---
 
-**Why not SDD every day?** Its separate proposal/spec/design/tasks artifacts and phase handoffs add coordination that ordinary work often does not need. Choose SDD explicitly when you want those formal artifacts, never automatically because of size, ambiguity, or risk. SDD remains supported, not deprecated.
+### Native review — Review the exact change
+
+<img width="100%" src="docs/assets/diagrams/native-review.svg" alt="Diagram showing one frozen candidate passing through risk-scoped native review to an outcome, while human delivery choices stay separate">
+
+Review the exact change, not a moving target. Native review keeps one candidate in view, returns risk-scoped evidence, and can surface a bounded correction path. You still decide what happens next in your repository.
 
-**[→ ODD details and recovery](docs/readme-reference.md#organic-driven-development)**
+**[Docs →](docs/review-integration.md)**
 
 ---
 
-### Optional SDD — Formal phases when you choose them
+### Gentle Changes — Every edit, attributed and reviewable
 
-<p align="center">
-  <img src="docs/assets/diagrams/sdd-cycle.svg" width="1200" alt="Diagram of an optional specification-driven development cycle from explore through archive, with TDD evidence attached to apply when available">
-</p>
+<img width="100%" src="docs/assets/features/changes-view.png" alt="Gentle Changes viewer: worktree accordion with per-file status on the left, the captured diff with line counts on the right, and a keyboard hint row">
 
-When you explicitly want separate proposal, specification, design, tasks, and verification artifacts, choose SDD/OpenSpec. Configured Strict TDD records RED → GREEN → TRIANGULATE → REFACTOR evidence during apply. TDD is also available in ODD; it does not require SDD.
+You should not have to run `git status` to find out what your agent did. Gentle Changes captures the successful write and edit tool calls from the current session and its owned subagents — no repository scans, no background polling — and shows them in a two-pane viewer with per-file line counts and an honest **diff unavailable** when an external edit breaks continuity. Coverage stops at those tools, so shell commands and failed runs leave no row, and a missing entry never proves a clean tree. `alt+g` opens it; `o` drops the real file into your editor.
 
-**[→ Explore the SDD/OpenSpec flow](docs/readme-reference.md#sddopenspec-flow)**
+**[Docs →](docs/gentle-shell.md#browse-captured-diffs)**
 
 ---
 
-### Native review — Review the exact change
+### Gentle Agents — Parallel work with a live view
 
-<p align="center">
-  <img src="docs/assets/diagrams/native-review.svg" width="1200" alt="Diagram showing one frozen candidate passing through risk-scoped native review to an outcome, while human delivery choices stay separate">
-</p>
+<img width="100%" src="docs/assets/features/agents-view.png" alt="Gentle Agents overlay showing a completed subagent thread with model, tokens, and elapsed columns, and the structured handoff it returned">
 
-Review the exact change, not a moving target. Native review keeps one candidate in view, returns risk-scoped evidence, and can surface a bounded correction path. You still decide what happens next in your repository.
+Delegating work should not mean losing it. Every subagent runs as its own process with a live card above the editor — model, tokens, cost, elapsed — and `alt+a` opens the full view with retained threads, stop controls, and history restored on resume. A child can ask you a question as an ordinary dialog, and background results come back as cards that start a new turn — nothing polls.
 
-**[→ Read the review integration boundary](docs/review-integration.md)**
+**[Docs →](docs/gentle-shell.md#gentle-agents)**
 
 ---
 
-### What's new in v2.6.0
+### Profiles and model routing — One deliberate decision per knob
 
-The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) brings a more persistent, inspectable Pi workspace:
+<img width="100%" src="docs/assets/features/profiles-routing.png" alt="Profiles view: profile list on the left, orchestrator model and effort on the right, with per-role profile routing and effective current routing">
 
-- **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.
+Model, effort, and who does what should be choices, not accidents. Named profiles route the orchestrator atomically and independently from packaged and review roles; a repository can pin its profile so its subagents stop following the globally active one, and the panel always shows the routing the runtime actually uses.
+
+**[Docs →](docs/readme-reference.md#agent-model-profiles)**
+
+---
+
+### Command palette — Every command, one keystroke away
+
+<img width="100%" src="docs/assets/features/command-palette.png" alt="Command palette with a search field and grouped entries: Configuration, Session, Diagnostics, SDD, and Skills">
+
+Extension commands are only useful if you can find them. `alt+k` opens a curated, grouped palette — Configuration, Session, Diagnostics, SDD, and Skills — searchable by label, command name, or description, showing entries only when they are actually registered.
+
+**[Docs →](docs/gentle-shell.md#command-palette)**
 
 ---
 
 ### Also in the box
 
-| Capability | What it brings to the workspace |
-| --- | --- |
+| Component | What it does |
+| :--- | :--- |
 | Startup and runtime panel | A configurable gentle-shell entry point and visible runtime state for Pi. |
 | Skills and delivery guidance | Package skills for documentation, issue work, PRs, reviews, and reviewable work units. |
 | Model, effort, persona, and profile controls | Explicit knobs for how Pi routes and presents work. |
 | Safety boundaries | Guards around destructive operations and sensitive-path handling. |
 | Optional companion packages | Extra capabilities you may choose to add; persistent memory is **not** bundled with `gentle-pi`. |
+| Fullscreen workspace layout | Header row plus a scrolling Status → Changes → TODO rail on wide terminals. |
+| Live status bar and prompt petal | One-line gauge, cost, and statuses; the petal shows `working` and `queued`. |
+| Parent ↔ subagent communication | Delegate, steer, reply, and cross-session notification within your local profile. |
+| Native interactive tools | Built-in questions, choices, and review captures — no third-party dependency. |
+| Gentle Todo | A plan card that turns amber when the model lets it go stale. |
+| Subscription usage | Per-window meters and resets for supported provider accounts. |
+| Gentle notices | Gentle AI calls and review reminders as cards in the transcript. |
 
-<details>
-<summary><strong>Optional companions, when they fit your setup</strong></summary>
+> **Every component, skill and preset: [Full breakdown →](docs/gentle-shell.md)**
 
-<br>
+---
 
-| Package | Optional role |
-| --- | --- |
-| `pi-intercom` | Cross-session communication where your Pi setup supports it. |
-| `gentle-engram` | Persistent memory, separately installed and configured. |
-| `pi-web-access` | Web access when a task needs it and your policy allows it. |
-| `pi-lens` | Additional inspection surfaces. |
-| `@juicesharp/rpiv-ask-user-question` | Interactive choice support. |
+### What's new in v2.6.0
+
+The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) brings a more persistent, inspectable Pi workspace:
 
-These are companions, not hidden prerequisites or a claim that every Pi installation has every capability.
+- **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.
 
-</details>
+---
 
 <p align="right"><a href="#top">Back to top ↑</a></p>
 
@@ -225,7 +229,32 @@ See the [v2.6.0 release notes](https://github.com/Gentleman-Programming/gentle-p
 
 > **Fullscreen installation note:** a recognized global installation persists Pi’s `"tuiMode": "fullscreen"` setting. Project-local and other install paths do not receive that change.
 
-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). Choose SDD/OpenSpec explicitly only when you want its separate phase artifacts.
+> **Interactive RPC hosts:** the desktop app sets `GENTLE_SHELL_INTERACTIVE_HOST=1` automatically, without touching your Pi config — see the [installation reference](docs/readme-reference.md#interactive-rpc-hosts).
+
+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>
 

package/assets/orchestrator-delegation.md

@@ -203,7 +203,7 @@ When the policy is on and `subagent_run` is available:
 
 - The runtime already defaults `subagent_run` to `mode: "background"` under this policy in interactive and RPC sessions, so omit `mode` for ordinary delegation. It returns a task id at once; the terminal stays free and the human keeps typing. Pass a `label` of three to six words naming the work.
 - A child `agent_end` retains its latest answer but is not completion: Pi may still retry, compact, or run a queued follow-up. Treat the task as finished only at `agent_settled`; only then release its queue slot, publish its background result, or terminate it. If it exits first, report failure with its retained answer as diagnostics.
-- When a background task settles, its result arrives as a message in this session (custom type `gentle-agents.result`, one per task) and starts a new turn if you are idle. Wait for it: end the turn once launches and any non-overlapping work are done. Never poll, sleep, or call `subagent_status`/`subagent_result` for completion.
+- When a background task settles, its result arrives as a message in this session (custom type `gentle-agents.result`, one per task) and starts a new turn if you are idle. Wait for it: end the turn once launches and any non-overlapping work are done. Never sleep or periodically poll `subagent_status`/`subagent_result` for completion or cache maintenance. Retain the task ID. Use `subagent_status` only at a real orchestration decision boundary: user-requested inspection, relevant scope change, input request, or suspected abnormal behavior. Never relaunch equivalent work merely because it is queued or running. Cache warming belongs to Pi's native runtime, never to model-driven maintenance turns.
 - Do not claim an implementation ready or RDD-ready while its required verification or correction follow-up remains queued. Run the required focused verification before that claim, and retain legitimate post-correction verification. This does not invent a universal full-suite requirement or make a receipt a delivery gate.
 - Use `mode: "task"` only when the subagent must ask the human something mid-flight (task-mode dialogs reach the human; background dialogs are dismissed) or when the human asked to wait.
 - Launch as many independent tasks as the work has; the runner queues beyond `max_concurrency`. Do not duplicate launches or work, and do not overlap files or topics. Never run parallel writers in one worktree.

package/bin/gentle-shell.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// Thin process/fs/exec glue around lib/gentle-shell-launcher.ts (built to
+// runtime/gentle-shell-launcher.mjs). All decision logic — argv parsing, home
+// 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 { createRequire } from "node:module";
+import { constants as osConstants, homedir } from "node:os";
+import { delimiter, dirname, join, resolve as resolvePath } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+	buildPiInvocation,
+	checkPiVersion,
+	describeVersion,
+	helpText,
+	launcherConfigPath,
+	missingPiMessage,
+	parseLauncherArgs,
+	parseLauncherConfig,
+	planSpawn,
+	resolveHome,
+	resolvePiRuntime,
+	settingsDeclareGentlePi,
+} from "../runtime/gentle-shell-launcher.mjs";
+import { installIsolatedTuiModeSetting } from "../scripts/install-tui-mode-setting.mjs";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function fail(message, code) {
+	process.stderr.write(`${message}\n`);
+	process.exit(code);
+}
+
+function readJsonIfExists(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+// @earendil-works/pi-coding-agent ships as an optional peer dependency: it may
+// not be installed at all, so a resolution failure here is expected, not an error.
+function resolveBundledCli() {
+	try {
+		const require = createRequire(import.meta.url);
+		const pkgJsonPath = require.resolve("@earendil-works/pi-coding-agent/package.json");
+		const cliPath = join(dirname(pkgJsonPath), "dist", "bundle", "cli.js");
+		return existsSync(cliPath) ? cliPath : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function findOnPath(name) {
+	const dirs = (process.env.PATH || "").split(delimiter).filter((entry) => entry.length > 0);
+	const extensions = process.platform === "win32" ? (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+	for (const dir of dirs) {
+		for (const extension of extensions) {
+			const candidate = join(dir, `${name}${extension}`);
+			try {
+				accessSync(candidate, fsConstants.X_OK);
+				return candidate;
+			} catch {
+				// keep scanning
+			}
+		}
+	}
+	return undefined;
+}
+
+function signalExitCode(signal) {
+	const number = osConstants.signals[signal];
+	return 128 + (typeof number === "number" ? number : 0);
+}
+
+function ownPackageVersion() {
+	const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	return packageJson.version;
+}
+
+function emptyArgs() {
+	return { link: false, isolated: false, home: undefined, help: false, version: false, command: undefined, commandArgs: [], passthrough: [], error: undefined };
+}
+
+function loadConfig() {
+	const configPath = launcherConfigPath(homedir());
+	const text = readJsonIfExists(configPath);
+	return text === undefined ? undefined : parseLauncherConfig(text);
+}
+
+function handleHomeCommand(commandArgs) {
+	if (commandArgs.length === 0) {
+		const resolved = resolveHome({ args: emptyArgs(), env: process.env, homedir: homedir(), config: loadConfig() });
+		process.stdout.write(`${resolved.mode} ${resolved.dir}\n`);
+		process.exit(0);
+	}
+	if (commandArgs.length > 1) fail("gentle-shell home accepts at most one argument. Run 'gentle-shell --help'.", 2);
+	const [value] = commandArgs;
+	if (value.length === 0) fail("gentle-shell home requires a non-empty argument. Run 'gentle-shell --help'.", 2);
+
+	const configPath = launcherConfigPath(homedir());
+	const configDir = dirname(configPath);
+	if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true, mode: 0o700 });
+
+	if (value === "link" || value === "isolated") {
+		writeFileSync(configPath, `${JSON.stringify({ home: value }, null, 2)}\n`, "utf8");
+		process.stdout.write(`Saved home: ${value}\n`);
+		process.exit(0);
+	}
+	const dir = resolvePath(value);
+	writeFileSync(configPath, `${JSON.stringify({ home: dir }, null, 2)}\n`, "utf8");
+	process.stdout.write(`Saved home: path ${dir}\n`);
+	process.exit(0);
+}
+
+async function main() {
+	const args = parseLauncherArgs(process.argv.slice(2));
+	if (args.error !== undefined) fail(`${args.error}\nRun 'gentle-shell --help' for usage.`, 2);
+	if (args.help) {
+		process.stdout.write(`${helpText()}\n`);
+		process.exit(0);
+	}
+	if (args.command === "home") {
+		handleHomeCommand(args.commandArgs);
+		return;
+	}
+
+	const config = loadConfig();
+	let home = resolveHome({ args, env: process.env, homedir: homedir(), config });
+	if (home.mode === "path") home = { ...home, dir: resolvePath(home.dir) };
+
+	const runtime = resolvePiRuntime({
+		env: process.env,
+		resolveBundledCli,
+		findOnPath,
+		nodeExecPath: process.execPath,
+	});
+	if (runtime === undefined) fail(missingPiMessage(), 1);
+
+	const versionProbePlan = planSpawn({ command: runtime.command, args: [...runtime.args, "--version"], platform: process.platform });
+	const versionProbe = spawnSync(versionProbePlan.command, versionProbePlan.args, {
+		stdio: ["ignore", "pipe", "pipe"],
+		timeout: 15000,
+		encoding: "utf8",
+		shell: versionProbePlan.shell,
+	});
+	if (versionProbe.error) fail(`Could not run the pi runtime at "${runtime.command}": ${versionProbe.error.message}`, 1);
+	const versionCheck = checkPiVersion(versionProbe.stdout ?? "");
+	if (!versionCheck.ok) fail(versionCheck.message, 1);
+
+	if (args.version) {
+		process.stdout.write(`${describeVersion({ gentlePiVersion: ownPackageVersion(), piVersion: versionCheck.version, home })}\n`);
+		process.exit(0);
+	}
+
+	// Isolated-home bootstrap: only on a home gentle-shell has not seen before
+	// (link never bootstraps — it reuses the user's own pi agent home as-is).
+	if ((home.mode === "isolated" || home.mode === "path") && !existsSync(home.dir)) {
+		mkdirSync(home.dir, { recursive: true });
+		await installIsolatedTuiModeSetting(home.dir);
+		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 settingsText = readJsonIfExists(join(home.dir, "settings.json"));
+		linkDeclaresGentlePi = settingsDeclareGentlePi(settingsText);
+	}
+
+	const invocation = buildPiInvocation({
+		runtime,
+		home,
+		packageRoot,
+		settingsDeclareGentlePi: home.mode === "link" ? linkDeclaresGentlePi : false,
+		passthrough: args.passthrough,
+		piSubcommand: args.piSubcommand,
+		baseEnv: process.env,
+	});
+
+	const launchPlan = planSpawn({ command: invocation.command, args: invocation.args, platform: process.platform });
+	const child = spawn(launchPlan.command, launchPlan.args, { stdio: "inherit", env: invocation.env, shell: launchPlan.shell });
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+		process.on(signal, () => child.kill(signal));
+	}
+	child.on("error", (error) => fail(`Could not start pi: ${error.message}`, 1));
+	child.on("exit", (code, signal) => {
+		process.exit(signal ? signalExitCode(signal) : (code ?? 1));
+	});
+}
+
+main().catch((error) => {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exit(1);
+});

package/docs/assets/diagrams/odd-workflow.svg

@@ -0,0 +1,74 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="760" viewBox="0 0 960 760" role="img" aria-labelledby="odd-title odd-desc">
+  <title id="odd-title">Organic Driven Development workflow</title>
+  <desc id="odd-desc">One feature moves through the seven ODD protocol steps. Authorize, explore, resolve uncertainty, then classify: small understood work stays light with no durable artifacts, while substantial work is tracked in one feature document before the first write. Both paths implement task by task and close with verified proof. The same feature document carries progress across sessions so work resumes instead of restarting.</desc>
+  <defs>
+    <linearGradient id="odd-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#100c15"/><stop offset="1" stop-color="#21101f"/></linearGradient>
+    <marker id="odd-arrow" markerUnits="userSpaceOnUse" markerWidth="10" markerHeight="10" viewBox="0 0 10 10" refX="10" refY="5" orient="auto"><path d="M0 0 10 5 0 10z" fill="#f095c8"/></marker>
+  </defs>
+  <rect width="960" height="760" rx="20" fill="url(#odd-bg)"/>
+  <text x="40" y="65" fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Explore, track, implement.</text>
+  <text x="40" y="120" fill="#d7a0b8" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Resume without ceremony.</text>
+  <g fill="#1c1420" stroke="#d7a0b8" stroke-width="2">
+    <rect x="40" y="170" width="196" height="120" rx="16"/>
+    <rect x="268" y="170" width="196" height="120" rx="16"/>
+    <rect x="496" y="170" width="196" height="120" rx="16"/>
+    <rect x="724" y="170" width="196" height="120" rx="16"/>
+    <rect x="724" y="330" width="196" height="120" rx="16" fill="#2a1426" stroke="#f095c8" stroke-width="3"/>
+    <rect x="610" y="490" width="196" height="120" rx="16"/>
+    <rect x="268" y="490" width="196" height="120" rx="16"/>
+  </g>
+  <rect x="496" y="330" width="196" height="120" rx="16" fill="#18121b" stroke="#d7a0b8" stroke-width="2" stroke-dasharray="6 6"/>
+  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round" marker-end="url(#odd-arrow)">
+    <path d="M236 230H268"/>
+    <path d="M464 230H496"/>
+    <path d="M692 230H724"/>
+    <path d="M822 290V330"/>
+    <path d="M822 290V310H594V330"/>
+    <path d="M708 470V490"/>
+    <path d="M610 550H464"/>
+  </g>
+  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round">
+    <path d="M594 450V470H708"/>
+    <path d="M822 450V470H708"/>
+  </g>
+  <g font-family="Arial, Helvetica, sans-serif" font-size="20" fill="#d7a0b8" opacity="0.85">
+    <text x="56" y="198">01</text>
+    <text x="284" y="198">02</text>
+    <text x="512" y="198">03</text>
+    <text x="740" y="198">04</text>
+    <text x="740" y="358">05</text>
+    <text x="626" y="518">06</text>
+    <text x="284" y="518">07</text>
+  </g>
+  <g font-family="Arial, Helvetica, sans-serif" text-anchor="middle">
+    <g fill="#fff7f1" font-size="30" font-weight="700">
+      <text x="138" y="222">Authorize</text>
+      <text x="366" y="222">Explore</text>
+      <text x="594" y="222">Resolve</text>
+      <text x="822" y="222">Classify</text>
+      <text x="822" y="382">Track</text>
+      <text x="594" y="382">Stay light</text>
+      <text x="708" y="542">Implement</text>
+      <text x="366" y="542">Close</text>
+    </g>
+    <g fill="#d7a0b8" font-size="22">
+      <text x="138" y="262">read-only</text>
+      <text x="366" y="262">code and needs</text>
+      <text x="594" y="262">uncertainty</text>
+      <text x="822" y="262">substantial?</text>
+      <text x="822" y="422">one document</text>
+      <text x="594" y="422">small work</text>
+      <text x="708" y="582">task by task</text>
+      <text x="366" y="582">verified proof</text>
+    </g>
+  </g>
+  <g font-family="Arial, Helvetica, sans-serif" font-size="22" fill="#d7a0b8">
+    <text x="708" y="302" text-anchor="middle">small</text>
+    <text x="838" y="316" text-anchor="start">substantial</text>
+  </g>
+  <rect x="40" y="650" width="880" height="90" rx="16" fill="#18121b" stroke="#d7a0b8" stroke-width="2" stroke-dasharray="8 7"/>
+  <g font-family="Arial, Helvetica, sans-serif" text-anchor="middle">
+    <text x="480" y="686" fill="#fff7f1" font-size="34" font-weight="700">Resume where you stopped</text>
+    <text x="480" y="722" fill="#d7a0b8" font-size="26">One feature document, mirrored in Engram across sessions.</text>
+  </g>
+</svg>