gentle-pi 0.3.10 → 0.4.0

package/README.md

@@ -353,6 +353,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
@@ -376,11 +378,20 @@ Legacy string entries are still accepted and treated as `model`-only config.
 | `/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: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

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) => {

package/extensions/skill-registry.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, watch } from "node:fs";
+import { existsSync, type FSWatcher, watch } from "node:fs";
 import {
 	access,
 	mkdir,
@@ -29,6 +29,7 @@ const LEGACY_PROJECT_REGISTRY_DISABLED_REL_PATH =
 	".pi/extensions/skill-registry.ts.disabled";
 const SKILL_REGISTRY_EXTENSION_SOURCE_KEY =
 	"__gentlePiSkillRegistryExtensionSource";
+const activeWatchers = new Set<FSWatcher>();
 
 interface SkillRegistryExtensionGlobal {
 	[SKILL_REGISTRY_EXTENSION_SOURCE_KEY]?: string;
@@ -62,6 +63,7 @@ function userSkillDirs(): string[] {
 		join(home, ".claude/skills"),
 		join(home, ".gemini/skills"),
 		join(home, ".gemini/antigravity/skills"),
+		join(home, ".trae/skills"),
 		join(home, ".cursor/skills"),
 		join(home, ".copilot/skills"),
 		join(home, ".codex/skills"),
@@ -78,6 +80,7 @@ function projectSkillDirs(cwd: string): string[] {
 		join(cwd, ".opencode/skills"),
 		join(cwd, ".claude/skills"),
 		join(cwd, ".gemini/skills"),
+		join(cwd, ".trae/skills"),
 		join(cwd, ".cursor/skills"),
 		join(cwd, ".github/skills"),
 		join(cwd, ".codex/skills"),
@@ -116,11 +119,12 @@ async function findSkillFiles(root: string): Promise<string[]> {
 }
 
 function parseFrontmatter(source: string): { name?: string; description?: string; body: string } {
-	if (!source.startsWith("---\n")) return { body: source };
-	const end = source.indexOf("\n---", 4);
-	if (end === -1) return { body: source };
-	const fm = source.slice(4, end);
-	const body = source.slice(end + 4).replace(/^\n/, "");
+	const normalized = source.replace(/\r\n?/g, "\n");
+	if (!normalized.startsWith("---\n")) return { body: normalized };
+	const end = normalized.indexOf("\n---", 4);
+	if (end === -1) return { body: normalized };
+	const fm = normalized.slice(4, end);
+	const body = normalized.slice(end + 4).replace(/^\n/, "");
 	const out: { name?: string; description?: string } = {};
 	const lines = fm.split("\n");
 	for (let i = 0; i < lines.length; i++) {
@@ -457,6 +461,18 @@ function shouldSkipDuplicateExtensionLoad(
 	return existingSource !== currentSource;
 }
 
+function closeSkillRegistryWatchers(): void {
+	for (const watcher of activeWatchers) {
+		try {
+			watcher.close();
+		} catch {
+			// Best-effort shutdown; stale handles must not block process exit.
+		}
+	}
+	activeWatchers.clear();
+	watchedCwds.clear();
+}
+
 async function startSkillRegistryWatcher(
 	cwd: string,
 	notify: (message: string) => void,
@@ -485,7 +501,8 @@ async function startSkillRegistryWatcher(
 	};
 	for (const dir of dirs) {
 		try {
-			watch(dir, { recursive: true }, refresh);
+			const watcher = watch(dir, { recursive: true }, refresh);
+			activeWatchers.add(watcher);
 		} catch {
 			// Some filesystems do not support recursive watches; session_start/manual refresh still work.
 		}
@@ -503,11 +520,20 @@ export const __testing = {
 	renderRegistry,
 	shouldSkipSkillRegistryStartup,
 	shouldSkipDuplicateExtensionLoad,
+	startSkillRegistryWatcher,
+	closeSkillRegistryWatchers,
+	activeWatcherCount() {
+		return activeWatchers.size;
+	},
 };
 
 export default function (pi: ExtensionAPI) {
 	if (shouldSkipDuplicateExtensionLoad()) return;
 
+	pi.on("session_shutdown", () => {
+		closeSkillRegistryWatchers();
+	});
+
 	pi.registerFlag(NO_SKILL_REGISTRY_FLAG, {
 		description: "Skip the Gentle AI skill registry refresh and watcher on startup.",
 		type: "boolean",
@@ -532,9 +558,11 @@ export default function (pi: ExtensionAPI) {
 					"warning",
 				);
 			}
-			await startSkillRegistryWatcher(ctx.cwd, (message) => {
-				if (ctx.hasUI) ctx.ui.notify(message, "info");
-			});
+			if (ctx.hasUI) {
+				await startSkillRegistryWatcher(ctx.cwd, (message) => {
+					ctx.ui.notify(message, "info");
+				});
+			}
 			if (quarantinedLegacy) {
 				setTimeout(() => {
 					void (async () => {

package/extensions/startup-banner.ts

@@ -4,10 +4,31 @@ import { truncateToWidth } from "@earendil-works/pi-tui";
 import * as os from "node:os";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 const execAsync = promisify(exec);
+const PI_AGENT_DIR = join(os.homedir(), ".pi", "agent");
+const PI_NPM_DIR = join(PI_AGENT_DIR, "npm", "node_modules");
+
+type BannerColor = "pink" | "cyan" | "yellow" | "green";
+interface BannerConfig {
+  showRose: boolean;
+  showTextLogo: boolean;
+  color: BannerColor;
+}
+const DEFAULT_BANNER_CONFIG: BannerConfig = {
+  showRose: true,
+  showTextLogo: true,
+  color: "pink",
+};
+const BANNER_COLORS: BannerColor[] = ["pink", "cyan", "yellow", "green"];
+const BANNER_PALETTES: Record<BannerColor, { rose: [number, number, number]; label: [number, number, number]; value: [number, number, number]; logoFresh: [number, number, number]; logoDim: [number, number, number] }> = {
+  pink: { rose: [255, 118, 195], label: [200, 100, 160], value: [255, 140, 210], logoFresh: [255, 138, 206], logoDim: [95, 30, 60] },
+  cyan: { rose: [95, 210, 255], label: [85, 170, 205], value: [130, 225, 255], logoFresh: [105, 220, 255], logoDim: [25, 80, 100] },
+  yellow: { rose: [255, 210, 95], label: [210, 165, 65], value: [255, 225, 135], logoFresh: [255, 215, 105], logoDim: [105, 75, 25] },
+  green: { rose: [110, 220, 145], label: [85, 175, 115], value: [145, 240, 170], logoFresh: [120, 230, 150], logoDim: [30, 95, 50] },
+};
 
 const TEXT_LOGO = [
   "                  ▄▄▄▀▀▀▀▀██                                ▄▄▀▄▄           ▄▄█▀▀▀██   ▀▀█▄    ▄▄▄",
@@ -47,6 +68,43 @@ function rgb(r: number, g: number, b: number, text: string): string {
   return `\x1b[38;2;${r};${g};${b}m${text}\x1b[39m`;
 }
 
+function gentleAiConfigHome(): string {
+  return process.env.GENTLE_PI_CONFIG_HOME ?? join(os.homedir(), ".pi", "gentle-ai");
+}
+
+function bannerConfigPath(): string {
+  return join(gentleAiConfigHome(), "banner.json");
+}
+
+function normalizeBannerConfig(value: unknown): BannerConfig {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return { ...DEFAULT_BANNER_CONFIG };
+  const record = value as Record<string, unknown>;
+  return {
+    showRose: typeof record.showRose === "boolean" ? record.showRose : DEFAULT_BANNER_CONFIG.showRose,
+    showTextLogo: typeof record.showTextLogo === "boolean" ? record.showTextLogo : DEFAULT_BANNER_CONFIG.showTextLogo,
+    color: BANNER_COLORS.includes(record.color as BannerColor) ? record.color as BannerColor : DEFAULT_BANNER_CONFIG.color,
+  };
+}
+
+async function readBannerConfig(): Promise<BannerConfig> {
+  try {
+    return normalizeBannerConfig(JSON.parse(await readFile(bannerConfigPath(), "utf8")));
+  } catch {
+    return { ...DEFAULT_BANNER_CONFIG };
+  }
+}
+
+async function writeBannerConfig(config: BannerConfig): Promise<void> {
+  const path = bannerConfigPath();
+  await mkdir(join(path, ".."), { recursive: true });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+function paletteColor(color: BannerColor, key: keyof typeof BANNER_PALETTES[BannerColor], text: string): string {
+  const [r, g, b] = BANNER_PALETTES[color][key];
+  return rgb(r, g, b, text);
+}
+
 function normalizeAscii(lines: string[]): string[] {
   const trimmed = lines.map((l) => l.replace(/\s+$/g, ""));
   const nonEmpty = trimmed.filter((l) => l.trim().length > 0);
@@ -433,7 +491,107 @@ function currentIntroMode(): IntroMode {
   return pickIntroMode(rows, cols);
 }
 
+async function countSddAgents(): Promise<number> {
+  try {
+    const entries = await readdir(join(PI_AGENT_DIR, "agents"), { withFileTypes: true });
+    return entries.filter((entry) => entry.isFile() && /^sdd-.*\.md$/.test(entry.name)).length;
+  } catch {
+    return 0;
+  }
+}
+
+function packageNameFromSpec(spec: unknown): string | undefined {
+  if (typeof spec !== "string") return undefined;
+  const clean = spec.replace(/^npm:/, "");
+  if (clean.startsWith("@")) {
+    const parts = clean.split("@");
+    return parts.length > 2 ? `@${parts[1]}` : clean;
+  }
+  return clean.split("@")[0] || undefined;
+}
+
+async function countPackageExtensions(packages: unknown[]): Promise<number> {
+  let count = 0;
+  for (const spec of packages) {
+    const name = packageNameFromSpec(spec);
+    if (!name) continue;
+    try {
+      const raw = await readFile(join(PI_NPM_DIR, name, "package.json"), "utf8");
+      const pkg = JSON.parse(raw);
+      const extensions = pkg?.pi?.extensions;
+      if (Array.isArray(extensions)) count += extensions.length;
+    } catch {
+      // Packages installed from non-npm sources may not live in PI_NPM_DIR.
+    }
+  }
+  return count;
+}
+
 export default function (pi: ExtensionAPI) {
+  const notifyBannerConfig = (ctx: any, config: BannerConfig) => {
+    ctx.ui.notify(
+      [
+        `Startup banner: rose=${config.showRose ? "on" : "off"}, text logo=${config.showTextLogo ? "on" : "off"}, color=${config.color}`,
+        `Config: ${bannerConfigPath()}`,
+        "Changes apply on the next startup banner render.",
+      ].join("\n"),
+      "info",
+    );
+  };
+
+  const registerBannerCommand = (name: string) => {
+    pi.registerCommand(name, {
+      description: "Configure the Gentle Pi startup banner.",
+      handler: async (_args, ctx) => {
+        const config = await readBannerConfig();
+        const selected = await ctx.ui.select("Startup banner", [
+          `Rose: ${config.showRose ? "on" : "off"}`,
+          `Text logo: ${config.showTextLogo ? "on" : "off"}`,
+          `Color: ${config.color}`,
+        ]);
+        if (!selected) return;
+        if (selected.startsWith("Rose:")) config.showRose = !config.showRose;
+        else if (selected.startsWith("Text logo:")) config.showTextLogo = !config.showTextLogo;
+        else if (selected.startsWith("Color:")) {
+          config.color = await ctx.ui.select("Startup banner color", [...BANNER_COLORS]) as BannerColor;
+        }
+        await writeBannerConfig(config);
+        notifyBannerConfig(ctx, config);
+      },
+    });
+  };
+  const registerToggleCommand = (name: string, key: "showRose" | "showTextLogo") => {
+    pi.registerCommand(name, {
+      description: `Toggle startup banner ${key === "showRose" ? "rose" : "text logo"}.`,
+      handler: async (_args, ctx) => {
+        const config = await readBannerConfig();
+        config[key] = !config[key];
+        await writeBannerConfig(config);
+        notifyBannerConfig(ctx, config);
+      },
+    });
+  };
+  const registerColorCommand = (name: string) => {
+    pi.registerCommand(name, {
+      description: "Set startup banner color preset.",
+      handler: async (args, ctx) => {
+        const config = await readBannerConfig();
+        const requested = String(args ?? "").trim() as BannerColor;
+        config.color = BANNER_COLORS.includes(requested)
+          ? requested
+          : await ctx.ui.select("Startup banner color", [...BANNER_COLORS]) as BannerColor;
+        await writeBannerConfig(config);
+        notifyBannerConfig(ctx, config);
+      },
+    });
+  };
+  for (const prefix of ["gentle", "gentle-ai"] as const) {
+    registerBannerCommand(`${prefix}:banner`);
+    registerToggleCommand(`${prefix}:toggle-rose`, "showRose");
+    registerToggleCommand(`${prefix}:toggle-text-logo`, "showTextLogo");
+    registerColorCommand(`${prefix}:banner-color`);
+  }
+
   pi.on("session_start", async (_event, ctx) => {
     if (!ctx.hasUI) return;
 
@@ -451,6 +609,8 @@ export default function (pi: ExtensionAPI) {
 
     process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
 
+    const bannerConfig = await readBannerConfig();
+    const palette = BANNER_PALETTES[bannerConfig.color];
     const roseBase = padLines(normalizeAscii(ROSE_LARGE_RAW));
     const logoBase = padLines(TEXT_LOGO);
 
@@ -458,6 +618,7 @@ export default function (pi: ExtensionAPI) {
     let mcpServersCount = 0;
     let extensionsCount = 0;
     let packagesCount = 0;
+    let sddAgentsCount = 0;
 
     const allCommands = pi.getCommands();
     const skills = allCommands.filter((c) => c.source === "skill");
@@ -493,15 +654,15 @@ export default function (pi: ExtensionAPI) {
     setTimeout(() => {
       (async () => {
         try {
+          sddAgentsCount = await countSddAgents();
           const raw = await readFile(
-            join(os.homedir(), ".pi", "agent", "settings.json"),
+            join(PI_AGENT_DIR, "settings.json"),
             "utf8",
           );
           const cfg = JSON.parse(raw);
-          extensionsCount = Array.isArray(cfg.extensions)
-            ? cfg.extensions.length
-            : 0;
-          packagesCount = Array.isArray(cfg.packages) ? cfg.packages.length : 0;
+          const packages = Array.isArray(cfg.packages) ? cfg.packages : [];
+          packagesCount = packages.length;
+          extensionsCount = await countPackageExtensions(packages);
         } catch {
           extensionsCount = 0;
           packagesCount = 0;
@@ -595,7 +756,7 @@ export default function (pi: ExtensionAPI) {
             const sideBySideMinWidth = roseBase.width + 3 + logoBase.width + 4;
             const wideStatsMinWidth = 122;
             const horizontal =
-              state.mode === "full" && width >= sideBySideMinWidth;
+              state.mode === "full" && bannerConfig.showRose && bannerConfig.showTextLogo && width >= sideBySideMinWidth;
             const wideStats = width >= wideStatsMinWidth;
 
             const b = new LayoutBuilder();
@@ -603,7 +764,7 @@ export default function (pi: ExtensionAPI) {
             b.center(width);
 
             if (state.mode === "minimal") {
-              for (let logoI = 0; logoI < logoBase.lines.length; logoI++) {
+              if (bannerConfig.showTextLogo) for (let logoI = 0; logoI < logoBase.lines.length; logoI++) {
                 const logoLine = logoBase.lines[logoI];
                 b.addRow();
                 b.lines[b.lines.length - 1].push(
@@ -660,8 +821,8 @@ export default function (pi: ExtensionAPI) {
                 b.center(width);
               }
             } else {
-              const showBanner = width >= logoBase.width + 2;
-              const showRose = width >= roseBase.width + 2;
+              const showBanner = bannerConfig.showTextLogo && width >= logoBase.width + 2;
+              const showRose = bannerConfig.showRose && width >= roseBase.width + 2;
               if (showBanner) {
                 for (let logoI = 0; logoI < logoBase.lines.length; logoI++) {
                   const logoLine = logoBase.lines[logoI];
@@ -690,7 +851,7 @@ export default function (pi: ExtensionAPI) {
               }
             }
 
-            if (state.mode === "full") {
+            if (state.mode === "full" || (!bannerConfig.showRose && !bannerConfig.showTextLogo)) {
               b.addRow();
               b.center(width);
 
@@ -720,8 +881,9 @@ export default function (pi: ExtensionAPI) {
                 ["GIT:", gitBranch],
                 ["PATH:", ctx.cwd],
                 ["MCP:", `${mcpServersCount} server(s)`],
+                ["AGENTS:", `${sddAgentsCount} phases`],
                 ["PLUGINS:", `${packagesCount} package(s)`],
-                ["AGENTS:", `${skills.length} loaded`],
+                ["SKILLS:", `${skills.length} loaded`],
                 ["EXTENSIONS:", `${extensionsCount} active`],
                 ["VER:", `v${VERSION}`],
                 ["TOOLS:", `${customTools.length} custom`],
@@ -752,22 +914,24 @@ export default function (pi: ExtensionAPI) {
                 );
                 addWideRow(
                   "AGENTS:",
-                  `${skills.length} loaded`,
+                  `${sddAgentsCount} phases`,
                   "EXTENSIONS:",
                   `${extensionsCount} active`,
                 );
                 addWideRow(
-                  "VER:",
-                  `v${VERSION}`,
+                  "SKILLS:",
+                  `${skills.length} loaded`,
                   "TOOLS:",
                   `${customTools.length} custom`,
                 );
+                addWideRow("VER:", `v${VERSION}`, "", "");
               } else {
                 addNarrowRow("GIT:", gitBranch);
                 addNarrowRow("PATH:", ctx.cwd);
                 addNarrowRow("MCP:", `${mcpServersCount} server(s)`);
                 addNarrowRow("PLUGINS:", `${packagesCount} package(s)`);
-                addNarrowRow("AGENTS:", `${skills.length} loaded`);
+                addNarrowRow("AGENTS:", `${sddAgentsCount} phases`);
+                addNarrowRow("SKILLS:", `${skills.length} loaded`);
                 addNarrowRow("EXTENSIONS:", `${extensionsCount} active`);
                 addNarrowRow("VER:", `v${VERSION}`);
                 addNarrowRow("TOOLS:", `${customTools.length} custom`);
@@ -834,9 +998,9 @@ export default function (pi: ExtensionAPI) {
                   const k = Math.max(0.01, roseOpacity * pulse);
                   const f = flashPhase ** 0.4;
 
-                  const rBase = Math.floor(255 * k);
-                  const gBase = Math.floor(118 * k);
-                  const bBase = Math.floor(195 * k);
+                  const rBase = Math.floor(palette.rose[0] * k);
+                  const gBase = Math.floor(palette.rose[1] * k);
+                  const bBase = Math.floor(palette.rose[2] * k);
 
                   if (f > 0.85) {
                     line += `\x1b[1m\x1b[38;2;255;255;255m${cell.char}\x1b[0m`;
@@ -874,22 +1038,22 @@ export default function (pi: ExtensionAPI) {
                     line += `\x1b[1m` + rgb(255, 205, 238, cell.char) + `\x1b[22m`;
                   } else if (cell.type === "logo-fresh") {
                     line += cell.char === "▒"
-                      ? rgb(110, 36, 70, cell.char)
-                      : rgb(255, 138, 206, cell.char);
+                      ? paletteColor(bannerConfig.color, "logoDim", cell.char)
+                      : paletteColor(bannerConfig.color, "logoFresh", cell.char);
                   } else {
                     line += cell.char === "▒"
-                      ? rgb(95, 30, 60, cell.char)
-                      : rgb(255, 120, 198, cell.char);
+                      ? paletteColor(bannerConfig.color, "logoDim", cell.char)
+                      : paletteColor(bannerConfig.color, "value", cell.char);
                   }
                   continue;
                 }
 
                 switch (cell.type) {
                   case "label":
-                    line += rgb(200, 100, 160, cell.char);
+                    line += paletteColor(bannerConfig.color, "label", cell.char);
                     break;
                   case "value":
-                    line += rgb(255, 140, 210, cell.char);
+                    line += paletteColor(bannerConfig.color, "value", cell.char);
                     break;
                   case "dim":
                     line += theme.fg("dim", cell.char);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/scripts/verify-package-files.mjs

@@ -11,6 +11,7 @@ const requiredPaths = [
   "assets/agents/sdd-design.md",
   "assets/agents/sdd-explore.md",
   "assets/agents/sdd-init.md",
+  "assets/agents/sdd-onboard.md",
   "assets/agents/sdd-proposal.md",
   "assets/agents/sdd-spec.md",
   "assets/agents/sdd-sync.md",

package/skills/comment-writer/SKILL.md

@@ -27,7 +27,7 @@ Use it for:
 | Keep it short | Prefer 1 to 3 short paragraphs or a tight bullet list. |
 | Explain why | Give the technical reason when asking for a change. |
 | Avoid pile-ons | Comment on the highest-value issue, not every tiny preference. |
-| Match thread language | Write in the thread/user language. If writing in Spanish, use Rioplatense Spanish/voseo: `podés`, `tenés`, `fijate`, `dale`. |
+| Match thread language | Write in the thread/user language and follow the active persona/tone. Do not force regional Spanish; use voseo only when the active persona or existing thread does. |
 | No em dashes | Use commas, periods, or parentheses instead. |
 
 ## Comment Formula

package/tests/gentle-ai.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+
+function writeMarkdown(path: string, content: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content);
+}
+
+test("agent discovery skips skills directories", async (t) => {
+	const root = mkdtempSync(join(tmpdir(), "gentle-pi-agents-"));
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const dotAgents = join(root, ".agents");
+	writeMarkdown(join(dotAgents, "reviewer.md"), "name: reviewer\n");
+	writeMarkdown(join(dotAgents, "team", "worker.md"), "name: worker\n");
+	writeMarkdown(join(dotAgents, "skills", "ai-sdk", "SKILL.md"), "name: ai-sdk\n");
+	writeMarkdown(
+		join(dotAgents, "skills", "ai-sdk", "references", "evaluation.md"),
+		"name: Prompt Evaluation\n",
+	);
+
+	const syncAgents = __testing.listAgentsFromDir(dotAgents, "user");
+	const asyncAgents = await __testing.listAgentsFromDirAsync(dotAgents, "user");
+
+	assert.deepEqual(
+		syncAgents.map((agent) => agent.name),
+		["reviewer", "worker"],
+	);
+	assert.deepEqual(
+		asyncAgents.map((agent) => agent.name),
+		["reviewer", "worker"],
+	);
+});

package/tests/runtime-harness.mjs

@@ -16,6 +16,17 @@ const EXTENSIONS = [
 	"extensions/startup-banner.ts",
 ];
 
+const EXPECTED_BANNER_COMMANDS = [
+	"gentle:banner",
+	"gentle:toggle-rose",
+	"gentle:toggle-text-logo",
+	"gentle:banner-color",
+	"gentle-ai:banner",
+	"gentle-ai:toggle-rose",
+	"gentle-ai:toggle-text-logo",
+	"gentle-ai:banner-color",
+];
+
 const EXPECTED_COMMANDS = [
 	"gentle-ai:install-sdd",
 	"gentle-ai:sdd-preflight",
@@ -27,8 +38,10 @@ const EXPECTED_COMMANDS = [
 	"gentle-ai:persona",
 	"gentleman:persona",
 	"gentle-ai:status",
+	"gentle-ai:doctor",
 	"sdd-init",
 	"skill-registry:refresh",
+	...EXPECTED_BANNER_COMMANDS,
 ];
 
 function createPi() {
@@ -151,6 +164,7 @@ async function run() {
 	}
 	assert.ok(flags.has("no-skill-registry"), "missing no-skill-registry flag");
 	assert.ok(hooks.has("session_start"), "missing session_start hook");
+	assert.ok(hooks.has("session_shutdown"), "missing session_shutdown hook");
 	assert.ok(hooks.has("input"), "missing input hook");
 	assert.ok(hooks.has("before_agent_start"), "missing before_agent_start hook");
 	assert.ok(hooks.has("tool_call"), "missing tool_call hook");
@@ -180,9 +194,8 @@ async function run() {
 		assert.match(promptResult.systemPrompt, /el Gentleman/);
 		assert.match(promptResult.systemPrompt, /openspec\/config\.yaml.*not session preflight/s);
 		assert.match(promptResult.systemPrompt, /Do not mark SDD preflight complete/);
-		await mkdir(join(promptCwd, ".pi", "gentle-ai"), { recursive: true });
 		await writeFile(
-			join(promptCwd, ".pi", "gentle-ai", "persona.json"),
+			join(globalConfigHome, "persona.json"),
 			'{"mode":"neutral"}\n',
 		);
 		const neutralPromptResult = await promptHook({ systemPrompt: "base" }, createCtx(promptCwd));
@@ -202,6 +215,37 @@ async function run() {
 			false,
 			"normal agent startup must not run SDD preflight",
 		);
+		await mkdir(join(promptCwd, ".pi", "gentle-ai"), { recursive: true });
+		await writeFile(
+			join(promptCwd, ".pi", "gentle-ai", "persona.json"),
+			'{"mode":"gentleman"}\n',
+		);
+		const localOverridePromptResult = await promptHook({ systemPrompt: "base" }, createCtx(promptCwd));
+		assert.match(
+			localOverridePromptResult.systemPrompt,
+			/When the user writes Spanish, answer in natural Rioplatense Spanish with voseo/,
+		);
+		const personaCtx = createCtx(promptCwd, true);
+		personaCtx.ui.select = async () => "neutral";
+		await commands.get("gentle:persona").handler("", personaCtx);
+		assert.equal(
+			await readFile(join(globalConfigHome, "persona.json"), "utf8"),
+			'{\n  "mode": "neutral"\n}\n',
+		);
+		assert.equal(
+			await readFile(join(promptCwd, ".pi", "gentle-ai", "persona.json"), "utf8"),
+			'{\n  "mode": "neutral"\n}\n',
+		);
+		assert.match(personaCtx.ui.notifications.at(-1).message, /Global config:/);
+		const onboardCtx = createCtx(promptCwd, true, "sdd-onboard-session");
+		onboardCtx.ui.select = async (_label, options) => options[0];
+		const onboardPromptResult = await promptHook(
+			{ agentName: "sdd-onboard", systemPrompt: "onboard base" },
+			onboardCtx,
+		);
+		assert.match(onboardPromptResult.systemPrompt, /onboard base/);
+		assert.match(onboardPromptResult.systemPrompt, /## SDD Session Preflight/);
+		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-onboard.md")), true);
 	} finally {
 		await rm(promptCwd, { recursive: true, force: true });
 	}
@@ -213,6 +257,14 @@ async function run() {
 		const denied = await toolHook({ toolName: "bash", input: { command: "rm -rf /" } }, createCtx(toolCwd));
 		assert.equal(denied.block, true);
 		assert.match(denied.reason, /destructive/);
+		const sensitiveRead = await toolHook({ toolName: "read", input: { path: join(toolCwd, ".env.local") } }, createCtx(toolCwd));
+		assert.equal(sensitiveRead.block, true);
+		assert.match(sensitiveRead.reason, /sensitive path/);
+		const sensitiveWrite = await toolHook({ toolName: "write", input: { path: join(toolCwd, "secrets", "token.txt"), content: "x" } }, createCtx(toolCwd));
+		assert.equal(sensitiveWrite.block, true);
+		const sensitiveEdit = await toolHook({ toolName: "edit", input: { edits: [], path: join(toolCwd, "id_rsa.pem") } }, createCtx(toolCwd));
+		assert.equal(sensitiveEdit.block, true);
+		assert.equal(await toolHook({ toolName: "read", input: { path: join(toolCwd, "src", "index.ts") } }, createCtx(toolCwd)), undefined);
 		const needsConfirm = await toolHook({ toolName: "bash", input: { command: "git push" } }, createCtx(toolCwd));
 		assert.equal(needsConfirm.block, true);
 		assert.match(needsConfirm.reason, /confirmation/);
@@ -220,6 +272,28 @@ async function run() {
 		await rm(toolCwd, { recursive: true, force: true });
 	}
 
+	const bannerCwd = await tempWorkspace();
+	try {
+		const ctx = createCtx(bannerCwd, true);
+		await commands.get("gentle:toggle-rose").handler("", ctx);
+		let bannerConfig = JSON.parse(await readFile(join(globalConfigHome, "banner.json"), "utf8"));
+		assert.equal(bannerConfig.showRose, false);
+		assert.equal(bannerConfig.showTextLogo, true);
+		assert.equal(bannerConfig.color, "pink");
+		await commands.get("gentle-ai:toggle-text-logo").handler("", ctx);
+		bannerConfig = JSON.parse(await readFile(join(globalConfigHome, "banner.json"), "utf8"));
+		assert.equal(bannerConfig.showTextLogo, false);
+		await commands.get("gentle:banner-color").handler("cyan", ctx);
+		bannerConfig = JSON.parse(await readFile(join(globalConfigHome, "banner.json"), "utf8"));
+		assert.equal(bannerConfig.color, "cyan");
+		await commands.get("gentle:banner").handler("", ctx);
+		bannerConfig = JSON.parse(await readFile(join(globalConfigHome, "banner.json"), "utf8"));
+		assert.equal(bannerConfig.showRose, true);
+	} finally {
+		await rm(bannerCwd, { recursive: true, force: true });
+		await rm(join(globalConfigHome, "banner.json"), { force: true });
+	}
+
 	const noUiCwd = await tempWorkspace();
 	try {
 		for (const handler of hooks.get("session_start")) {
@@ -237,6 +311,28 @@ async function run() {
 		);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "chains", "sdd-full.chain.md")), true);
+		await writeFile(join(globalAgentHome, "agents", "sdd-apply.md"), "stale global apply\n");
+		await writeFile(join(globalAgentHome, "chains", "sdd-full.chain.md"), "stale global chain\n");
+		await mkdir(join(noUiCwd, ".pi", "agents"), { recursive: true });
+		await writeFile(join(noUiCwd, ".pi", "agents", "sdd-apply.md"), "project override must stay\n");
+		for (const handler of hooks.get("session_start")) {
+			await handler({ reason: "startup" }, createCtx(noUiCwd, false));
+		}
+		assert.notEqual(
+			await readFile(join(globalAgentHome, "agents", "sdd-apply.md"), "utf8"),
+			"stale global apply\n",
+			"session_start must refresh stale global SDD agents",
+		);
+		assert.notEqual(
+			await readFile(join(globalAgentHome, "chains", "sdd-full.chain.md"), "utf8"),
+			"stale global chain\n",
+			"session_start must refresh stale global SDD chains",
+		);
+		assert.equal(
+			await readFile(join(noUiCwd, ".pi", "agents", "sdd-apply.md"), "utf8"),
+			"project override must stay\n",
+			"session_start must not overwrite project-local SDD overrides",
+		);
 	} finally {
 		await rm(noUiCwd, { recursive: true, force: true });
 	}
@@ -342,12 +438,27 @@ async function run() {
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-apply.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "agents", "sdd-sync.md")), true);
 		assert.equal(existsSync(join(globalAgentHome, "chains", "sdd-full.chain.md")), true);
-		const lazySettings = JSON.parse(await readFile(join(lazySddCwd, ".pi", "settings.json"), "utf8"));
-		assert.equal(lazySettings.subagents.agentOverrides["sdd-apply"].model, "openai/gpt-5");
-		assert.equal(lazySettings.subagents.agentOverrides["sdd-apply"].thinking, "high");
+		const globalSddApply = await readFile(
+			join(globalAgentHome, "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(globalSddApply, /model: openai\/gpt-5/);
+		assert.match(globalSddApply, /thinking: high/);
+		const lazySettingsPath = join(lazySddCwd, ".pi", "settings.json");
+		if (existsSync(lazySettingsPath)) {
+			const lazySettings = JSON.parse(await readFile(lazySettingsPath, "utf8"));
+			assert.equal(
+				lazySettings.subagents?.agentOverrides?.["sdd-apply"],
+				undefined,
+				"global SDD model routing must be materialized in agent frontmatter, not project settings overrides",
+			);
+		}
 		assert.equal(ctx.ui.selections.length, 3);
 		assert.deepEqual(ctx.ui.selections[1].options, ["openspec"]);
 		assert.match(ctx.ui.notifications.at(-1).message, /SDD preflight complete/);
+		await commands.get("gentle-ai:status").handler("", ctx);
+		assert.match(ctx.ui.notifications.at(-1).message, /Global SDD assets stale: 0 file\(s\)/);
+		assert.doesNotMatch(ctx.ui.notifications.at(-1).message, /install-sdd --force/);
 
 		await inputHook({ text: "/sdd-plan another change", source: "interactive" }, ctx);
 		assert.equal(ctx.ui.selections.length, 3, "preflight should run only once per session");
@@ -509,6 +620,13 @@ async function run() {
 		await commands.get("gentle-ai:status").handler("", ctx);
 		assert.match(ctx.ui.notifications.at(-1).message, /Project-local SDD override drift: \d+ file\(s\)/);
 		assert.match(ctx.ui.notifications.at(-1).message, /gentle-ai:install-sdd --force/);
+		await commands.get("gentle-ai:doctor").handler("", ctx);
+		assert.match(ctx.ui.notifications.at(-1).message, /el Gentleman doctor/);
+		assert.match(ctx.ui.notifications.at(-1).message, /Sensitive-path guard active/);
+		pi.setActiveTools([{ name: "engram.mem_save" }]);
+		await commands.get("gentle-ai:doctor").handler("", ctx);
+		assert.match(ctx.ui.notifications.at(-1).message, /Engram memory tools active/);
+		pi.setActiveTools(["read", "bash", "edit", "write"]);
 	} finally {
 		await rm(staleAssetsCwd, { recursive: true, force: true });
 	}
@@ -815,6 +933,44 @@ async function run() {
 			model: "custom/provider-model",
 			thinking: "medium",
 		});
+
+		let exportPanelCalls = 0;
+		ctx.ui.custom = () => {
+			exportPanelCalls += 1;
+			return Promise.resolve(exportPanelCalls === 1 ? { type: "export", config: {} } : { type: "cancel" });
+		};
+		await commands.get("gentle:models").handler("", ctx);
+		const exported = JSON.parse(await readFile(join(globalConfigHome, "models.export.json"), "utf8"));
+		assert.equal(exported.kind, "gentle-pi.agent_model_routing");
+		assert.equal(exported.version, 1);
+		assert.deepEqual(exported.agents["sdd-apply"], {
+			model: "custom/provider-model",
+			thinking: "medium",
+		});
+
+		await writeFile(
+			join(globalConfigHome, "models.export.json"),
+			JSON.stringify({
+				kind: "gentle-pi.agent_model_routing",
+				version: 1,
+				agents: { "sdd-apply": { model: "restore/provider", thinking: "high" } },
+			}, null, 2),
+		);
+		let restorePanelCalls = 0;
+		ctx.ui.confirm = async () => true;
+		ctx.ui.custom = () => {
+			restorePanelCalls += 1;
+			return Promise.resolve(restorePanelCalls === 1 ? { type: "restore", config: {} } : { type: "cancel" });
+		};
+		await commands.get("gentle:models").handler("", ctx);
+		const restoredConfig = JSON.parse(await readFile(globalModelsPath, "utf8"));
+		assert.deepEqual(restoredConfig["sdd-apply"], {
+			model: "restore/provider",
+			thinking: "high",
+		});
+		const restoredAgent = await readFile(join(modelsCwd, ".pi", "agents", "sdd-apply.md"), "utf8");
+		assert.match(restoredAgent, /model: restore\/provider/);
+		assert.match(restoredAgent, /thinking: high/);
 	} finally {
 		await rm(modelsCwd, { recursive: true, force: true });
 		await rm(globalModelsPath, { force: true });

package/tests/skill-registry.test.ts

@@ -14,6 +14,7 @@ test("project skill dirs include supported workspace roots", () => {
 		".opencode/skills",
 		".claude/skills",
 		".gemini/skills",
+		".trae/skills",
 		".cursor/skills",
 		".github/skills",
 		".codex/skills",
@@ -50,6 +51,17 @@ test("registry renders indexed skill paths instead of compact rules", () => {
 	assert.doesNotMatch(registry, /Rules:/);
 });
 
+test("frontmatter parser accepts CRLF line endings", () => {
+	const parsed = __testing.parseFrontmatter("---\r\nname: windows-skill\r\ndescription: >\r\n  Trigger: Windows-authored skills.\r\n  Preserve frontmatter metadata.\r\n---\r\n\r\n## Body\r\n");
+
+	assert.equal(parsed.name, "windows-skill");
+	assert.equal(
+		parsed.description,
+		"Trigger: Windows-authored skills. Preserve frontmatter metadata.",
+	);
+	assert.match(parsed.body, /## Body/);
+});
+
 test("frontmatter parser keeps full multiline descriptions", () => {
 	const parsed = __testing.parseFrontmatter(`---
 name: ai-sdk-5
@@ -102,6 +114,26 @@ test("uniqueExistingDirs normalizes duplicates and ignores missing roots", async
 	);
 });
 
+test("skill registry watchers close on shutdown", async () => {
+	const root = join(tmpdir(), `gentle-pi-watchers-${Date.now()}`);
+	const skillPath = join(root, "skills", "docs", "SKILL.md");
+	mkdirSync(dirname(skillPath), { recursive: true });
+	writeFileSync(skillPath, "---\nname: docs\ndescription: Docs.\n---\n");
+
+	await __testing.startSkillRegistryWatcher(root, () => undefined);
+	const attempted = __testing.activeWatcherCount();
+	__testing.closeSkillRegistryWatchers();
+	assert.equal(__testing.activeWatcherCount(), 0);
+
+	await __testing.startSkillRegistryWatcher(root, () => undefined);
+	assert.equal(
+		__testing.activeWatcherCount(),
+		attempted,
+		"shutdown must clear watched cwd state so a later session can re-watch",
+	);
+	__testing.closeSkillRegistryWatchers();
+});
+
 test("startup skip honors no skill registry controls", () => {
 	const enabled = { getFlag: () => true };
 	const disabled = { getFlag: () => false };