gentle-pi 0.3.10 → 0.4.1

package/README.md

@@ -45,10 +45,10 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 
 | Capability                     | What it does                                                                                                                                  |
 | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| **el Gentleman persona**       | Makes Pi behave like a senior architect and teacher, not a generic chatbot. Spanish responses use Rioplatense voseo by default.               |
-| **Rose startup intro**         | Adds a pink rose fade-in, compact project/runtime panel, and visible startup collaboration credit for @aporcelli's `pi-gentle-startup` ideas. |
+| **el Gentleman persona**       | Makes Pi behave like a senior architect and teacher, not a generic chatbot. Spanish responses use Rioplatense voseo by default; neutral mode is saved globally with project overrides. |
+| **Configurable startup intro** | Adds a rose/text-logo startup intro, compact runtime panel, color presets, and commands to hide or show the decorative parts.                  |
 | **Work routing discipline**    | Small tasks stay inline. Context-heavy exploration can be delegated. Large or risky changes go through SDD/OpenSpec.                          |
-| **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, and `archive`.              |
+| **SDD/OpenSpec assets**        | Installs phase agents and chains for `init`, `onboard`, `explore`, `proposal`, `spec`, `design`, `tasks`, `apply`, `verify`, `sync`, and `archive`. |
 | **Lazy SDD preflight**         | Asks once per session for SDD mode, artifact store, PR chaining strategy, and review budget before the first SDD flow.                        |
 | **Subagent orchestration**     | Keeps one parent session responsible while child agents explore, implement, test, or review with focused context.                             |
 | **Strict TDD support**         | When project config declares a test command, apply/verify phases must record RED → GREEN → TRIANGULATE → REFACTOR evidence.                   |
@@ -56,7 +56,7 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Per-agent model assignment** | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents.                                                       |
 | **Skill discovery registry**   | Maintains `.atl/skill-registry.md` from project and user skills so review/comment/PR workflows do not silently miss the right skill.          |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
-| **Shell safety**               | Blocks destructive shell commands and asks for confirmation for sensitive operations.                                                         |
+| **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
 ## Install
 
@@ -88,10 +88,12 @@ pi
 
 ```text
 /gentle-ai:status          Check package, SDD assets, OpenSpec, and global model config.
+/gentle-ai:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
 /gentle-ai:sdd-preflight   Run or reuse the session SDD preflight explicitly.
 /sdd-init                  Create or refresh openspec/config.yaml.
 /gentle:models             Assign global model/effort routing to SDD/custom agents.
 /gentle:persona            Switch between gentleman and neutral persona modes.
+/gentle:banner             Configure startup rose, text logo, and color preset.
 ```
 
 Typical flow:
@@ -315,13 +317,19 @@ Delegation contract:
 | `gentleman` | Senior architect, teacher, direct technical feedback, Rioplatense Spanish/voseo when the user writes Spanish. |
 | `neutral`   | Same discipline, warmer professional language, no regional expression.                                        |
 
-Saved at:
+Saved globally at:
+
+```text
+~/.pi/gentle-ai/persona.json
+```
+
+A project can still override the global default with:
 
 ```text
 .pi/gentle-ai/persona.json
 ```
 
-Run `/reload` or start a new Pi session after switching persona.
+`/gentle:persona` writes the global config and updates an existing project override when one is present, so the current project does not stay stale. Run `/reload` or start a new Pi session after switching persona.
 
 ## Model and effort assignment
 
@@ -353,6 +361,8 @@ Saved globally at:
 
 Existing project-local `.pi/gentle-ai/models.json` files are still read as a legacy fallback when no global model config exists, but `/gentle:models` writes the shared global config.
 
+Inside `/gentle:models`, press `x` to export the saved routing to `~/.pi/gentle-ai/models.export.json`, or `r` to restore from that file after confirmation. Export uses a versioned envelope and restore writes the normal `models.json` shape before applying routing to agents.
+
 Config shape (per agent):
 
 ```json
@@ -374,13 +384,22 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | Command                          | What it does                                                        |
 | -------------------------------- | ------------------------------------------------------------------- |
 | `/gentle-ai:status`              | Shows package, SDD asset, OpenSpec, and global model config status. |
-| `/gentle:models`                 | Opens global model + effort assignment UI.                          |
-| `/gentle:persona`                | Switches persona mode.                                              |
+| `/gentle-ai:doctor`              | Runs read-only diagnostics for SDD assets, model/persona config, memory tools, and safety guards. |
+| `/gentle:models`                 | Opens global model + effort assignment UI. Press `x` to export and `r` to restore saved routing. |
+| `/gentle:persona`                | Switches global persona mode, with project override support.        |
+| `/gentle:banner`                 | Configures startup banner rose, text logo, and color preset.        |
+| `/gentle:toggle-rose`            | Toggles the startup rose.                                           |
+| `/gentle:toggle-text-logo`       | Toggles the startup text logo.                                      |
+| `/gentle:banner-color`           | Selects a startup banner color preset.                              |
 | `/sdd-init`                      | Initializes or refreshes `openspec/config.yaml`.                    |
 | `/gentle-ai:install-sdd`         | Repairs missing global SDD runtime assets without overwriting files. |
 | `/gentle-ai:install-sdd --force` | Force-refreshes installed global SDD assets.                         |
 | `/skill-registry:refresh`        | Regenerates `.atl/skill-registry.md`.                               |
 
+Package-owned global SDD runtime assets are also refreshed automatically on session start when `gentle-pi` changes. Project-local `.pi/agents` and `.pi/chains` remain manual overrides and are never overwritten by startup refresh.
+
+Startup banner settings are global and default to the current pink rose + text logo. Supported color presets are `pink`, `cyan`, `yellow`, and `green`. The `/gentle-ai:*` aliases are also available for every banner command.
+
 Startup flag:
 
 ```text
@@ -396,6 +415,10 @@ Compatibility aliases:
 /gentleman:models
 /gentle-ai:persona
 /gentleman:persona
+/gentle-ai:banner
+/gentle-ai:toggle-rose
+/gentle-ai:toggle-text-logo
+/gentle-ai:banner-color
 ```
 
 ## Included skills
@@ -432,10 +455,10 @@ Memory contract for SDD delegation:
 
 | Path                           | Purpose                                                                                                    |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `extensions/gentle-ai.ts`      | Injects identity, ensures global SDD assets, registers commands, applies model config, and protects shell execution. |
-| `extensions/startup-banner.ts` | Shows the rose startup intro, compact runtime panel, and collaboration credit.                             |
+| `extensions/gentle-ai.ts`      | Injects identity, auto-refreshes global SDD assets, registers commands, applies model/persona config, exports/restores model routing, and enforces runtime safety. |
+| `extensions/startup-banner.ts` | Shows and configures the startup intro, color presets, compact runtime panel, and collaboration credit.     |
 | `extensions/sdd-init.ts`       | Registers `/sdd-init` for OpenSpec initialization.                                                         |
-| `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills.                                               |
+| `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills and closes file watchers on shutdown.          |
 | `assets/orchestrator.md`       | Parent-session orchestration contract.                                                                     |
 | `assets/agents/`               | SDD agents installed as global Pi runtime assets.                                                          |
 | `assets/chains/`               | SDD chains installed as global Pi runtime assets.                                                          |

package/assets/orchestrator.md

@@ -31,7 +31,9 @@ User-facing conversation should stay in the user's language and follow the curre
 
 Subagent-facing prompts should be written in English by default, even when the user speaks Spanish. Translate the user's request into concise English before delegation. This keeps token usage lower and gives built-in/project subagents a consistent operating language without changing the user-facing persona.
 
-Generated artifacts — whether by the parent inline or by subagents — (code, UI copy, comments, identifiers, commit messages, filenames, PR descriptions) default to English, regardless of the user's conversation language. Override only when the user explicitly requests another language for that artifact, or when extending a project whose existing convention is non-English.
+Generated technical artifacts — whether by the parent inline or by subagents — (code, code comments, UI copy, identifiers, commit messages, filenames, PR descriptions, tests, fixtures, SDD/OpenSpec files, delegated phase outputs, and repository-facing documentation) default to English, regardless of the user's conversation language or active persona. Override only when the user explicitly requests another language for that artifact, or when extending a project whose existing convention is non-English.
+
+Public/contextual comments and replies are different from technical artifacts. When using `comment-writer` or drafting a human-facing GitHub, PR review, Slack, Discord, or async comment, write in the target context language by default. Spanish issue/thread -> Spanish comment. English thread -> English comment. Mixed context -> target message language. Explicit user language or tone override wins. Spanish comments default to neutral/professional Spanish unless the user or target context clearly calls for regional tone.
 
 Exceptions:
 

package/extensions/gentle-ai.ts

@@ -53,10 +53,17 @@ function sddGlobalAssetDriftCount(): number {
 					stale += 1;
 					continue;
 				}
-				if (
-					readFileSync(join(assetDir, entry.name), "utf8") !==
-					readFileSync(installedPath, "utf8")
-				) {
+				const packaged = readFileSync(join(assetDir, entry.name), "utf8");
+				const installed = readFileSync(installedPath, "utf8");
+				const comparablePackaged =
+					assetSubdir === "agents"
+						? updateFrontmatterRouting(packaged, undefined)
+						: packaged;
+				const comparableInstalled =
+					assetSubdir === "agents"
+						? updateFrontmatterRouting(installed, undefined)
+						: installed;
+				if (comparablePackaged !== comparableInstalled) {
 					stale += 1;
 				}
 			} catch {
@@ -181,8 +188,29 @@ const CONFIRM_BASH_PATTERNS: RegExp[] = [
 	/\bpi\s+remove\b/,
 ];
 
+const PATH_GUARDED_TOOL_NAMES = new Set(["read", "write", "edit"]);
+const PATH_INPUT_KEYS = new Set([
+	"path",
+	"paths",
+	"file",
+	"files",
+	"filePath",
+	"filePaths",
+]);
+const SENSITIVE_PATH_PATTERNS: RegExp[] = [
+	/(^|\/)\.ssh(?:\/|$)/,
+	/(^|\/)\.credentials(?:\/|$)/,
+	/(^|\/)library\/keychains(?:\/|$)/,
+	/(^|\/)\.aws\/credentials$/,
+	/(^|\/)\.config\/gh\/hosts\.ya?ml$/,
+	/(^|\/)secrets(?:\/|$)/,
+	/(^|\/)\.env(?:$|[./_-])/,
+	/\.(?:pem|key|p12|pfx)$/,
+];
+
 const SDD_AGENT_NAMES = [
 	"sdd-init",
+	"sdd-onboard",
 	"sdd-explore",
 	"sdd-proposal",
 	"sdd-spec",
@@ -293,6 +321,62 @@ function commandRequiresConfirmation(command: string): boolean {
 	return CONFIRM_BASH_PATTERNS.some((pattern) => pattern.test(command));
 }
 
+function normalizePolicyPath(value: string): string {
+	return value.trim().replace(/^~(?=\/|$)/, homedir()).replace(/\\/g, "/").toLowerCase();
+}
+
+function isSensitivePath(value: string): boolean {
+	const normalized = normalizePolicyPath(value);
+	return SENSITIVE_PATH_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function collectPathInputs(value: unknown, key?: string): string[] {
+	if (typeof value === "string") return key && PATH_INPUT_KEYS.has(key) ? [value] : [];
+	if (Array.isArray(value)) return value.flatMap((item) => collectPathInputs(item, key));
+	if (!isRecord(value)) return [];
+	return Object.entries(value).flatMap(([entryKey, entryValue]) =>
+		collectPathInputs(entryValue, entryKey),
+	);
+}
+
+function hasWritableEngramTool(pi: ExtensionAPI): boolean {
+	try {
+		const getActiveTools = (pi as unknown as { getActiveTools?: () => unknown[] })
+			.getActiveTools;
+		if (typeof getActiveTools !== "function") return false;
+		const tools = getActiveTools.call(pi);
+		return tools.some((tool) => {
+			const name =
+				typeof tool === "string"
+					? tool
+					: isRecord(tool) && typeof tool.name === "string"
+						? tool.name
+						: "";
+			return (
+				name === "mem_save" ||
+				name === "engram_mem_save" ||
+				name.endsWith(".mem_save") ||
+				name.endsWith(".engram_mem_save")
+			);
+		});
+	} catch {
+		return false;
+	}
+}
+
+function evaluateSensitivePathTool(
+	toolName: string,
+	input: unknown,
+): ToolCallEventResult | undefined {
+	if (!PATH_GUARDED_TOOL_NAMES.has(toolName)) return undefined;
+	const sensitivePath = collectPathInputs(input).find(isSensitivePath);
+	if (!sensitivePath) return undefined;
+	return {
+		block: true,
+		reason: `Gentle AI safety policy blocked access to sensitive path: ${sanitizeTerminalText(sensitivePath)}. Ask the user for an explicit safer plan.`,
+	};
+}
+
 async function confirmCommand(
 	command: string,
 	ctx: ExtensionContext,
@@ -333,30 +417,53 @@ function modelConfigPath(_cwd: string): string {
 	return join(gentleAiConfigHome(), "models.json");
 }
 
+function modelExportPath(_cwd: string): string {
+	return join(gentleAiConfigHome(), "models.export.json");
+}
+
+const MODEL_EXPORT_KIND = "gentle-pi.agent_model_routing";
+const MODEL_EXPORT_VERSION = 1;
+
 function legacyProjectModelConfigPath(cwd: string): string {
 	return join(cwd, ".pi", "gentle-ai", "models.json");
 }
 
-function personaConfigPath(cwd: string): string {
+function projectPersonaConfigPath(cwd: string): string {
 	return join(cwd, ".pi", "gentle-ai", "persona.json");
 }
 
-function readPersonaMode(cwd: string): PersonaMode {
-	const path = personaConfigPath(cwd);
-	if (!existsSync(path)) return "gentleman";
+function personaConfigPath(_cwd: string): string {
+	return join(gentleAiConfigHome(), "persona.json");
+}
+
+function readPersonaFile(path: string): PersonaMode | undefined {
+	if (!existsSync(path)) return undefined;
 	try {
 		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-		if (!isRecord(parsed)) return "gentleman";
+		if (!isRecord(parsed)) return undefined;
 		return parsed.mode === "neutral" ? "neutral" : "gentleman";
 	} catch {
-		return "gentleman";
+		return undefined;
 	}
 }
 
-function writePersonaMode(cwd: string, mode: PersonaMode): void {
-	const path = personaConfigPath(cwd);
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify({ mode }, null, 2)}\n`);
+function readPersonaMode(cwd: string): PersonaMode {
+	return (
+		readPersonaFile(projectPersonaConfigPath(cwd)) ??
+		readPersonaFile(personaConfigPath(cwd)) ??
+		"gentleman"
+	);
+}
+
+function writePersonaMode(cwd: string, mode: PersonaMode): string[] {
+	const paths = [personaConfigPath(cwd)];
+	const projectPath = projectPersonaConfigPath(cwd);
+	if (existsSync(projectPath)) paths.push(projectPath);
+	for (const path of paths) {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, `${JSON.stringify({ mode }, null, 2)}\n`);
+	}
+	return paths;
 }
 
 function isThinkingLevel(value: unknown): value is ThinkingLevel {
@@ -467,17 +574,58 @@ export async function readModelConfigAsync(
 	return result.status === "valid" ? result.config : {};
 }
 
-function writeModelConfig(cwd: string, config: AgentModelConfig): void {
-	const path = modelConfigPath(cwd);
-	mkdirSync(dirname(path), { recursive: true });
+function normalizeModelConfig(value: unknown): AgentModelConfig | undefined {
+	if (!isRecord(value)) return undefined;
 	const cleaned: AgentModelConfig = {};
-	for (const [name, value] of Object.entries(config)) {
-		const entry = normalizeRoutingEntry(value);
+	for (const [name, entryValue] of Object.entries(value)) {
+		if (!/^[A-Za-z0-9._:@/+%-]+$/.test(name)) continue;
+		const entry = normalizeRoutingEntry(entryValue);
 		if (entry) cleaned[name] = entry;
 	}
+	return cleaned;
+}
+
+function writeModelConfig(cwd: string, config: AgentModelConfig): void {
+	const path = modelConfigPath(cwd);
+	mkdirSync(dirname(path), { recursive: true });
+	const cleaned = normalizeModelConfig(config) ?? {};
 	writeFileSync(path, `${JSON.stringify(cleaned, null, 2)}\n`);
 }
 
+async function writeModelConfigAsync(cwd: string, config: AgentModelConfig): Promise<void> {
+	const path = modelConfigPath(cwd);
+	await mkdir(dirname(path), { recursive: true });
+	const cleaned = normalizeModelConfig(config) ?? {};
+	await writeFile(path, `${JSON.stringify(cleaned, null, 2)}\n`);
+}
+
+function parseModelExport(value: unknown): AgentModelConfig | undefined {
+	if (!isRecord(value)) return undefined;
+	if (value.kind !== MODEL_EXPORT_KIND || value.version !== MODEL_EXPORT_VERSION) return undefined;
+	return normalizeModelConfig(value.agents);
+}
+
+async function exportSavedModelConfig(ctx: ExtensionContext): Promise<number> {
+	const saved = await readSavedModelConfigAsync(ctx.cwd);
+	if (saved.status === "invalid") throw new Error(`Invalid model config: ${saved.path}`);
+	const agents = saved.status === "valid" ? saved.config : {};
+	const path = modelExportPath(ctx.cwd);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(
+		path,
+		`${JSON.stringify({ kind: MODEL_EXPORT_KIND, version: MODEL_EXPORT_VERSION, agents }, null, 2)}\n`,
+	);
+	return Object.keys(agents).length;
+}
+
+async function readModelExport(ctx: ExtensionContext): Promise<AgentModelConfig | undefined> {
+	try {
+		return parseModelExport(JSON.parse(await readFile(modelExportPath(ctx.cwd), "utf8")));
+	} catch {
+		return undefined;
+	}
+}
+
 function cloneModelConfig(config: AgentModelConfig): AgentModelConfig {
 	return Object.fromEntries(
 		Object.entries(config).map(([name, entry]) => [name, { ...entry }]),
@@ -549,8 +697,10 @@ function listAgentFilesRecursive(dir: string): string[] {
 	const files: string[] = [];
 	for (const entry of readdirSync(dir, { withFileTypes: true })) {
 		const path = join(dir, entry.name);
-		if (entry.isDirectory()) files.push(...listAgentFilesRecursive(path));
-		else if (
+		if (entry.isDirectory()) {
+			if (entry.name === "skills") continue;
+			files.push(...listAgentFilesRecursive(path));
+		} else if (
 			entry.isFile() &&
 			entry.name.endsWith(".md") &&
 			!entry.name.endsWith(".chain.md")
@@ -572,6 +722,7 @@ async function listAgentFilesRecursiveAsync(dir: string): Promise<string[]> {
 	for (const entry of entries) {
 		const path = join(dir, entry.name);
 		if (entry.isDirectory()) {
+			if (entry.name === "skills") continue;
 			files.push(...(await listAgentFilesRecursiveAsync(path)));
 		} else if (
 			entry.isFile() &&
@@ -607,14 +758,15 @@ async function listAgentsFromDirAsync(
 }
 
 function listDiscoverableAgents(cwd: string): AgentEntry[] {
+	const globalAgentDir = join(gentlePiAgentHome(), "agents");
 	const builtinDirs = [
-		join(gentlePiAgentHome(), "agents"),
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
 		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
 	];
 	const agents = [
 		...builtinDirs.flatMap((dir) => listAgentsFromDir(dir, "builtin")),
+		...listAgentsFromDir(globalAgentDir, "user"),
 		...listAgentsFromDir(join(homedir(), ".agents"), "user"),
 		...listAgentsFromDir(join(cwd, ".agents"), "project"),
 		...listAgentsFromDir(join(cwd, ".pi", "agents"), "project"),
@@ -632,8 +784,8 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
 }
 
 async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
+	const globalAgentDir = join(gentlePiAgentHome(), "agents");
 	const builtinDirs = [
-		join(gentlePiAgentHome(), "agents"),
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
 		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
@@ -643,6 +795,7 @@ async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
 		agents.push(...(await listAgentsFromDirAsync(dir, "builtin")));
 	}
 	const otherDirs: Array<[string, AgentSource]> = [
+		[globalAgentDir, "user"],
 		[join(homedir(), ".agents"), "user"],
 		[join(cwd, ".agents"), "project"],
 		[join(cwd, ".pi", "agents"), "project"],
@@ -845,6 +998,8 @@ interface OverlayComponent {
 type ModelPanelResult =
 	| { type: "save"; config: AgentModelConfig }
 	| { type: "custom"; agent: string | "all"; config: AgentModelConfig }
+	| { type: "export"; config: AgentModelConfig }
+	| { type: "restore"; config: AgentModelConfig }
 	| { type: "cancel" };
 
 const SET_ALL_AGENTS = "Set all agents";
@@ -945,6 +1100,14 @@ class SddModelPanel implements OverlayComponent {
 			this.effortCursor = 0;
 			return;
 		}
+		if (matchesKey(data, "x")) {
+			this.done({ type: "export", config: this.draft });
+			return;
+		}
+		if (matchesKey(data, "r")) {
+			this.done({ type: "restore", config: this.draft });
+			return;
+		}
 		if (matchesKey(data, "c")) {
 			const row = this.rows[this.cursor];
 			if (row === SET_ALL_AGENTS)
@@ -1121,7 +1284,7 @@ class SddModelPanel implements OverlayComponent {
 		lines.push("");
 		lines.push(
 			line(
-				"j/k: scroll • g/G: top/bottom • enter: change model / confirm • e: effort • i: inherit • c: custom • ctrl+s: save • esc: back",
+				"j/k scroll • enter model/save • e effort • i inherit • c custom • x export • r restore • ctrl+s save • esc back",
 			),
 		);
 		return lines;
@@ -1255,8 +1418,54 @@ async function handleModelsCommand(ctx: ExtensionContext): Promise<void> {
 	}
 	let config = savedConfig.status === "valid" ? savedConfig.config : {};
 	let result = await showSddModelPanel(ctx, config);
-	while (result.type === "custom") {
+	while (result.type === "custom" || result.type === "export" || result.type === "restore") {
 		config = cloneModelConfig(result.config);
+		if (result.type === "export") {
+			try {
+				const count = await exportSavedModelConfig(ctx);
+				ctx.ui.notify(`el Gentleman exported ${count} saved model routing entr${count === 1 ? "y" : "ies"} to ${modelExportPath(ctx.cwd)}.`, "info");
+			} catch (error) {
+				ctx.ui.notify(`Model routing export failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+			}
+			result = await showSddModelPanel(ctx, config);
+			continue;
+		}
+		if (result.type === "restore") {
+			const restored = await readModelExport(ctx);
+			if (!restored) {
+				ctx.ui.notify(`Model routing restore failed: ${modelExportPath(ctx.cwd)} is missing or invalid.`, "warning");
+				result = await showSddModelPanel(ctx, config);
+				continue;
+			}
+			const approved = await ctx.ui.confirm("Restore saved model routing?", `Replace ${modelConfigPath(ctx.cwd)} with ${modelExportPath(ctx.cwd)}`);
+			if (approved) {
+				try {
+					await writeModelConfigAsync(ctx.cwd, restored);
+				} catch (error) {
+					ctx.ui.notify(`Model routing restore failed before writing config: ${error instanceof Error ? error.message : String(error)}`, "warning");
+					result = await showSddModelPanel(ctx, config);
+					continue;
+				}
+				config = restored;
+				try {
+					const applyResult = await applyModelConfigAsync(ctx.cwd, restored);
+					ctx.ui.notify([
+						"el Gentleman restored global model config.",
+						`Import: ${modelExportPath(ctx.cwd)}`,
+						`Global config: ${modelConfigPath(ctx.cwd)}`,
+						`Agents updated: ${applyResult.updated}`,
+					].join("\n"), "info");
+				} catch (error) {
+					ctx.ui.notify([
+						"el Gentleman restored global model config, but applying it to agents failed.",
+						`Global config: ${modelConfigPath(ctx.cwd)}`,
+						`Apply error: ${error instanceof Error ? error.message : String(error)}`,
+					].join("\n"), "warning");
+				}
+			}
+			result = await showSddModelPanel(ctx, config);
+			continue;
+		}
 		const current =
 			result.agent === "all"
 				? "inherit"
@@ -1319,17 +1528,26 @@ async function handlePersonaCommand(ctx: ExtensionContext): Promise<void> {
 		[...PERSONA_OPTIONS],
 	);
 	if (selected !== "gentleman" && selected !== "neutral") return;
-	writePersonaMode(ctx.cwd, selected);
+	const writtenPaths = writePersonaMode(ctx.cwd, selected);
 	ctx.ui.notify(
 		[
 			`el Gentleman persona set to: ${selected}`,
-			`Config: ${personaConfigPath(ctx.cwd)}`,
+			`Global config: ${personaConfigPath(ctx.cwd)}`,
+			...(writtenPaths.length > 1
+				? [`Project override updated: ${projectPersonaConfigPath(ctx.cwd)}`]
+				: []),
 			"Run /reload or start a new Pi session for already-injected prompts to refresh.",
 		].join("\n"),
 		"info",
 	);
 }
 
+/** @internal */
+export const __testing = {
+	listAgentsFromDir,
+	listAgentsFromDirAsync,
+};
+
 export default function gentleAi(pi: ExtensionAPI): void {
 	function runSddPreflight(ctx: ExtensionContext): Promise<SddPreflightPreferences> {
 		return ensureSddPreflight(ctx, {
@@ -1341,7 +1559,7 @@ export default function gentleAi(pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (_event, ctx) => {
 		try {
-			const installResult = installSddAssets(ctx.cwd, false);
+			const installResult = installSddAssets(ctx.cwd, true);
 			const modelResult = await applySavedModelConfig(ctx);
 			if (ctx.hasUI && modelResult.invalidPath) {
 				ctx.ui.notify(
@@ -1396,6 +1614,11 @@ export default function gentleAi(pi: ExtensionAPI): void {
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		const sensitivePathDenied = evaluateSensitivePathTool(
+			event.toolName,
+			event.input,
+		);
+		if (sensitivePathDenied) return sensitivePathDenied;
 		if (event.toolName !== "bash") return undefined;
 		if (!isRecord(event.input) || typeof event.input.command !== "string")
 			return undefined;
@@ -1472,6 +1695,50 @@ export default function gentleAi(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("gentle-ai:doctor", {
+		description: "Run read-only Gentle AI diagnostics for this Pi workspace.",
+		handler: async (_args, ctx) => {
+			const agentsInstalled = existsSync(
+				join(gentlePiAgentHome(), "agents", "sdd-apply.md"),
+			);
+			const chainsInstalled = existsSync(
+				join(gentlePiAgentHome(), "chains", "sdd-full.chain.md"),
+			);
+			const openspecConfigured = existsSync(
+				join(ctx.cwd, "openspec", "config.yaml"),
+			);
+			const skillRegistryPresent = existsSync(
+				join(ctx.cwd, ".atl", "skill-registry.md"),
+			);
+			const staleSddAssets = sddGlobalAssetDriftCount();
+			const staleLocalOverrides = sddLocalOverrideDriftCount(ctx.cwd);
+			const modelConfig = await readSavedModelConfigAsync(ctx.cwd);
+			const engramActive = hasWritableEngramTool(pi);
+			const lines = [
+				"el Gentleman doctor",
+				`${agentsInstalled ? "pass" : "fail"}: Global SDD agents ${agentsInstalled ? "installed" : "missing"}`,
+				`${chainsInstalled ? "pass" : "fail"}: Global SDD chains ${chainsInstalled ? "installed" : "missing"}`,
+				`${staleSddAssets === 0 ? "pass" : "warn"}: Global SDD asset drift ${staleSddAssets} file(s)`,
+				`${staleLocalOverrides === 0 ? "pass" : "warn"}: Project-local SDD override drift ${staleLocalOverrides} file(s)`,
+				`${openspecConfigured ? "pass" : "warn"}: OpenSpec config ${openspecConfigured ? "present" : "missing"}`,
+				`${skillRegistryPresent ? "pass" : "warn"}: Skill registry ${skillRegistryPresent ? "present" : "missing"}`,
+				`${modelConfig.status === "invalid" ? "fail" : "pass"}: Global model config ${modelConfig.status}`,
+				"pass: Sensitive-path guard active for read/write/edit tools",
+				`${engramActive ? "pass" : "warn"}: Engram memory tools ${engramActive ? "active" : "not active in this session"}`,
+			];
+			if (!agentsInstalled || !chainsInstalled) {
+				lines.push("remedy: run /gentle-ai:install-sdd --force to refresh global SDD assets intentionally");
+			}
+			if (modelConfig.status === "invalid") {
+				lines.push(`remedy: fix or remove ${modelConfig.path}`);
+			}
+			ctx.ui.notify(
+				lines.join("\n"),
+				lines.some((line) => line.startsWith("fail:")) ? "warning" : "info",
+			);
+		},
+	});
+
 	pi.registerCommand("gentle-ai:status", {
 		description: "Show Gentle AI package status for this project.",
 		handler: async (_args, ctx) => {