pi-profile-switch 0.2.0 → 0.3.1

package/src/default-profiles.ts

@@ -0,0 +1,59 @@
+/**
+ * DefaultProfiles: the catalog a fresh install starts from.
+ *
+ * Pi packages have no install hook (docs/packages.md) — `pi install` only
+ * unpacks the package and runs `npm install` — so "installing the default
+ * profiles" can only happen the first time the extension actually loads.
+ * `seedDefaultProfilesSync` therefore runs at load time, before any session
+ * event, and is idempotent: an existing catalog file is never read, rewritten,
+ * or backed up, and the package never seeds again once the file exists.
+ *
+ * The seeded content is the shipped preset catalog, exactly what
+ * `examples/profiles.json` publishes, reached through the same
+ * `PROFILE_PRESETS` data `/profile create` offers — one definition, so the
+ * three cannot drift. The `read-only` profile declares built-in tools and
+ * instructions only: it activates on a machine with no skills, no
+ * `pi-mcp-adapter`, and no credentials, and it changes nothing until the
+ * user selects it.
+ *
+ * `profile-presets.test.ts` pins the content contract: this catalog equals
+ * the published `examples/profiles.json` and every definition is
+ * resource-free.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { DEFAULT_PROFILE_NAME, PROFILE_SCHEMA_VERSION } from "./profile-catalog.ts";
+import { PROFILE_PRESETS } from "./profile-presets.ts";
+
+/** The catalog written to `<agentDir>/profiles.json` on first load. */
+export const DEFAULT_PROFILE_CATALOG = {
+	schemaVersion: PROFILE_SCHEMA_VERSION,
+	profiles: Object.fromEntries(
+		PROFILE_PRESETS.filter((preset) => preset.name !== DEFAULT_PROFILE_NAME).map((preset) => [
+			preset.name,
+			preset.definition,
+		]),
+	),
+};
+
+export type DefaultSeedResult =
+	/** The agent dir had no catalog and now holds the default one. */
+	| "seeded"
+	/** A catalog file was already there; it was not touched. */
+	| "present";
+
+/**
+ * Writes `<agentDir>/profiles.json` when it does not exist yet. Synchronous
+ * on purpose: the load-time call site cannot await, and the write is one small
+ * file. Existing files win unconditionally — an empty or hand-written catalog
+ * is a user decision, not a missing default.
+ */
+export function seedDefaultProfilesSync(agentDir: string, catalog: unknown = DEFAULT_PROFILE_CATALOG): DefaultSeedResult {
+	const target = path.join(agentDir, "profiles.json");
+	if (existsSync(target)) return "present";
+	mkdirSync(agentDir, { recursive: true });
+	writeFileSync(target, `${JSON.stringify(catalog, null, 2)}\n`);
+	return "seeded";
+}

package/src/json-file.ts

@@ -5,6 +5,7 @@
  * fallback); this helper only classifies the outcome.
  */
 
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
 export type JsonFileResult =
@@ -30,6 +31,25 @@ export async function readJsonFile(filePath: string): Promise<JsonFileResult> {
 	}
 }
 
+/** Synchronous twin of `readJsonFile`, for callers that must finish before
+ *  an event Pi is about to emit (extension loading). Same classification. */
+export function readJsonFileSync(filePath: string): JsonFileResult {
+	let raw: string;
+	try {
+		raw = readFileSync(filePath, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { ok: false, reason: "missing" };
+		}
+		throw error;
+	}
+	try {
+		return { ok: true, value: JSON.parse(raw) };
+	} catch {
+		return { ok: false, reason: "invalid" };
+	}
+}
+
 export function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/mcp-config.ts

@@ -1,23 +1,32 @@
 /**
- * AdapterConfigDiscovery: reads the MCP server NAMES pi-mcp-adapter would
- * discover from its pi-native config files, without ever managing them.
+ * AdapterConfigDiscovery: reads what pi-mcp-adapter would load from its
+ * pi-native FILE sources — server names for reference validation, and the
+ * "Pi global override" slot document for the generated overlay.
  *
- * pi-profile-switch never stores MCP connection parameters or credentials
- * (ADR-0002); this module reads only the `mcpServers` key names so an
- * activation can validate a profile's `mcp` references before applying it.
+ * Discovery mirrors the adapter's own source order (later sources override
+ * earlier ones): shared global MCP config, the two `.agents` globals, the Pi
+ * global override slot (`--mcp-config`, else `<agentDir>/mcp.json`), then the
+ * project's `.mcp.json` and `.pi/mcp.json` (project sources only when Pi
+ * reports the project trusted — an untrusted project's config is never read).
  *
- * Discovery scope (documented limitation): the pi-native files only — the
- * global `<agentDir>/mcp.json` and, when trusted, the project's
- * `.pi/mcp.json`. Servers defined solely in the adapter's editor-specific
- * legacy locations (~/.claude/mcp.json et al.) are invisible here; profiles
- * referencing them fail activation validation. The pi-native files are the
- * adapter's documented default, so keep configs there.
+ * Not covered (documented limitation): the adapter's opt-in host discovery
+ * (`~/.claude.json`, `~/.cursor/mcp.json`, …), package manifests (`pi.mcp`)
+ * and agent/Claude plugin sources. Their servers are namespaced and cannot be
+ * referenced by a profile today; the overlay still disables them when a name
+ * happens to match one it knows.
+ *
+ * pi-profile-switch never writes these files and never exposes connection
+ * parameters; the slot document is read only to be carried into the generated
+ * overlay, because that file replaces the slot.
  *
  * Malformed config files fail loudly — a broken mcp.json must not silently
  * read as "no servers" and reject every reference.
  */
 
-import { isRecord, readJsonFile } from "./json-file.ts";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { isRecord, readJsonFileSync } from "./json-file.ts";
 
 export class McpConfigError extends Error {
 	readonly filePath: string;
@@ -29,35 +38,145 @@ export class McpConfigError extends Error {
 	}
 }
 
-async function readServerNames(filePath: string): Promise<string[]> {
-	const result = await readJsonFile(filePath);
-	if (!result.ok) {
-		if (result.reason === "missing") {
-			return [];
+export interface AdapterMcpSource {
+	label: string;
+	filePath: string;
+	scope: "global" | "project";
+	/** True for the slot `--mcp-config` replaces. */
+	slot: boolean;
+}
+
+export interface AdapterMcpDiscoveryInput {
+	agentDir: string;
+	cwd: string;
+	projectTrusted: boolean;
+	/** The effective `--mcp-config` value, when one is in play. */
+	overridePath?: string;
+	/** Home directory override; tests point this at their fixture. */
+	homeDir?: string;
+}
+
+/** The adapter's file sources, in its own precedence order. Paths are
+ *  de-duplicated: the adapter skips a source whose read path equals the slot. */
+export function adapterMcpSources(input: AdapterMcpDiscoveryInput): AdapterMcpSource[] {
+	const home = input.homeDir ?? homedir();
+	const slotPath = path.resolve(input.overridePath ?? path.join(input.agentDir, "mcp.json"));
+	const candidates: AdapterMcpSource[] = [
+		{ label: "shared global MCP config", filePath: path.join(home, ".config", "mcp", "mcp.json"), scope: "global", slot: false },
+		{ label: ".agents MCP config", filePath: path.join(home, ".agents", "mcp.json"), scope: "global", slot: false },
+		{ label: ".agents/mcp MCP config", filePath: path.join(home, ".agents", "mcp", "mcp.json"), scope: "global", slot: false },
+		{ label: "Pi global MCP override", filePath: slotPath, scope: "global", slot: true },
+	];
+	if (input.projectTrusted) {
+		candidates.push(
+			{ label: "project MCP config", filePath: path.resolve(input.cwd, ".mcp.json"), scope: "project", slot: false },
+			{ label: "project Pi MCP override", filePath: path.resolve(input.cwd, ".pi", "mcp.json"), scope: "project", slot: false },
+		);
+	}
+	const seen = new Set<string>();
+	return candidates.filter((source) => {
+		if (source.slot) return true; // the slot is always the read path
+		if (seen.has(source.filePath)) return false;
+		seen.add(source.filePath);
+		return true;
+	});
+}
+
+export interface AdapterMcpView {
+	/** Read path of the slot `--mcp-config` replaces. */
+	slotPath: string;
+	/** Parsed slot document (verbatim), when the file exists. */
+	slotDocument?: Record<string, unknown>;
+	slotNames: string[];
+	/** Server names from the other file sources. */
+	otherNames: string[];
+	/** Union of slot and other names, sorted. */
+	serverNames: string[];
+}
+
+/** Synchronous read: the extension-load pass must finish before the adapter's
+ *  session initialization, and the files are tiny. */
+export function readAdapterMcpViewSync(input: AdapterMcpDiscoveryInput): AdapterMcpView {
+	const sources = adapterMcpSources(input);
+	const slot = sources.find((source) => source.slot);
+	const slotPath = slot?.filePath ?? path.join(input.agentDir, "mcp.json");
+	let slotDocument: Record<string, unknown> | undefined;
+	const slotNames: string[] = [];
+	const otherNames = new Set<string>();
+	for (const source of sources) {
+		if (source.slot) {
+			const document = readMcpDocumentSync(source.filePath);
+			if (document === undefined) continue;
+			slotDocument = document;
+			slotNames.push(...serverNames(document, source.filePath));
+			continue;
 		}
+		const document = readMcpDocumentSync(source.filePath);
+		if (document === undefined) continue;
+		for (const name of serverNames(document, source.filePath)) otherNames.add(name);
+	}
+	for (const name of slotNames) otherNames.delete(name);
+	return {
+		slotPath,
+		...(slotDocument === undefined ? {} : { slotDocument }),
+		slotNames,
+		otherNames: [...otherNames].sort(),
+		serverNames: [...new Set([...slotNames, ...otherNames])].sort(),
+	};
+}
+
+/** Async twin for the runtime paths (selection, status, toggles). */
+export async function readAdapterMcpView(input: AdapterMcpDiscoveryInput): Promise<AdapterMcpView> {
+	return readAdapterMcpViewSync(input);
+}
+
+/** Server names from every source EXCEPT the slot file. The slot is generated
+ *  by pi-profile-switch, so it must not feed back into the next generation —
+ *  otherwise a stub would look like a source server and vanish on the next
+ *  write. */
+export function readAdapterOtherServerNamesSync(input: AdapterMcpDiscoveryInput): string[] {
+	const names = new Set<string>();
+	for (const source of adapterMcpSources(input)) {
+		if (source.slot) continue;
+		const document = readMcpDocumentSync(source.filePath);
+		if (document === undefined) continue;
+		for (const name of serverNames(document, source.filePath)) names.add(name);
+	}
+	return [...names].sort();
+}
+
+/** Server names the adapter would discover. `projectDir` is passed only when
+ *  the trust check passed. */
+export async function discoverAdapterServerNames(
+	agentDir: string,
+	projectDir?: string,
+	homeDir?: string,
+): Promise<string[]> {
+	return readAdapterMcpViewSync({
+		agentDir,
+		cwd: projectDir ?? process.cwd(),
+		projectTrusted: projectDir !== undefined,
+		...(homeDir === undefined ? {} : { homeDir }),
+	}).serverNames;
+}
+
+/** Missing file → undefined; malformed → McpConfigError. */
+export function readMcpDocumentSync(filePath: string): Record<string, unknown> | undefined {
+	const result = readJsonFileSync(filePath);
+	if (!result.ok) {
+		if (result.reason === "missing") return undefined;
 		throw new McpConfigError(`MCP config is not valid JSON: ${filePath}`, filePath);
 	}
 	if (!isRecord(result.value)) {
 		throw new McpConfigError(`MCP config must be a JSON object: ${filePath}`, filePath);
 	}
-	if (result.value.mcpServers === undefined) {
-		return [];
-	}
-	if (!isRecord(result.value.mcpServers)) {
-		throw new McpConfigError(`"mcpServers" must be a JSON object: ${filePath}`, filePath);
-	}
-	return Object.keys(result.value.mcpServers);
+	return result.value;
 }
 
-/** Server names the adapter would discover: global agentDir config plus the
- *  trusted project's config. Pass `projectDir` only when the trust check
- *  passed — an untrusted project's config is never read. */
-export async function discoverAdapterServerNames(agentDir: string, projectDir?: string): Promise<string[]> {
-	const names = new Set(await readServerNames(`${agentDir}/mcp.json`));
-	if (projectDir !== undefined) {
-		for (const name of await readServerNames(`${projectDir}/.pi/mcp.json`)) {
-			names.add(name);
-		}
+function serverNames(document: Record<string, unknown>, filePath: string): string[] {
+	if (document.mcpServers === undefined) return [];
+	if (!isRecord(document.mcpServers)) {
+		throw new McpConfigError(`"mcpServers" must be a JSON object: ${filePath}`, filePath);
 	}
-	return [...names].sort();
+	return Object.keys(document.mcpServers);
 }

package/src/mcp-overlay-file.ts

@@ -0,0 +1,35 @@
+/**
+ * McpOverlayFile: the only writer of the generated MCP overlay.
+ *
+ * Invariants:
+ * - Atomic (temporary file + rename) so a reader never sees a half-written
+ *   document.
+ * - Written only when the bytes change: a profile switch that does not move
+ *   the MCP selection produces no write and therefore no reload.
+ * - Mode 0600: the overlay carries the Pi-global slot's definitions verbatim
+ *   when the user keeps servers there, and those definitions may embed
+ *   credentials even though the overlay itself never introduces any.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Current bytes, or undefined when the file is missing/unreadable. */
+export function readMcpOverlaySync(overlayPath: string): string | undefined {
+	try {
+		return readFileSync(overlayPath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Writes `content` when it differs from what is on disk. Returns true when
+ *  the file changed. */
+export function writeMcpOverlayIfChangedSync(overlayPath: string, content: string): boolean {
+	if (readMcpOverlaySync(overlayPath) === content) return false;
+	mkdirSync(path.dirname(overlayPath), { recursive: true });
+	const temporary = `${overlayPath}.tmp-${process.pid}`;
+	writeFileSync(temporary, content, { mode: 0o600 });
+	renameSync(temporary, overlayPath);
+	return true;
+}

package/src/mcp-overlay.ts

@@ -0,0 +1,122 @@
+/**
+ * McpOverlay: the PURE half of the profile-scoped MCP filter.
+ *
+ * `pi-mcp-adapter` has no runtime allowlist channel (ADR-0002 amendment), so
+ * the profile's `mcp` declaration is enforced by a generated config file the
+ * adapter reads as its "Pi global override" slot (the slot `--mcp-config`
+ * replaces). The file is a DISABLE OVERLAY: entries carry no connection
+ * parameters and no credentials — `{ "<server>": { "disabled": true } }` is
+ * the adapter's own idiom for `/mcp disable`, and its config merge is
+ * per-field, so a stub merges onto the definition owned by the user's own
+ * file.
+ *
+ * One exception is structural: because the overlay file REPLACES the Pi
+ * global slot, the servers the user keeps in that slot are carried over
+ * verbatim from the sidecar (`mcp.user.json`); a hand-written slot file is
+ * adopted into the sidecar before the first overwrite.
+ *
+ * `allowed` semantics:
+ * - `"all"` — the profile declares no `mcp`: nothing is disabled.
+ * - `[]` — every discovered server is disabled.
+ * - `["github", …]` — everything outside the list is disabled.
+ */
+
+import path from "node:path";
+
+import { isRecord } from "./json-file.ts";
+import { matchesReference } from "./name-matching.ts";
+
+/**
+ * The generated overlay REPLACES the adapter's Pi-global slot, so it lives at
+ * the slot's default path. The user's own Pi-global servers move to a sidecar
+ * that this package never writes except when adopting a hand-written slot.
+ */
+export const MCP_SLOT_FILE_NAME = "mcp.json";
+export const MCP_SOURCE_FILE_NAME = "mcp.user.json";
+/** Top-level key marking a file as generated. The adapter ignores unknown
+ *  top-level keys, so the marker never reaches it as configuration. */
+export const MCP_GENERATED_MARKER = "piProfileSwitch";
+
+/** The adapter's Pi-global slot: the generated overlay. */
+export function mcpSlotPath(agentDir: string): string {
+	return path.join(agentDir, MCP_SLOT_FILE_NAME);
+}
+
+/** The user-owned sidecar holding the Pi-global servers verbatim. */
+export function mcpSourcePath(agentDir: string): string {
+	return path.join(agentDir, MCP_SOURCE_FILE_NAME);
+}
+
+/** True when the document was produced by pi-profile-switch. */
+export function isGeneratedOverlay(value: unknown): boolean {
+	if (!isRecord(value)) return false;
+	const marker = value[MCP_GENERATED_MARKER];
+	return isRecord(marker) && marker.generated === true;
+}
+
+/** True for the credential-free stubs the overlay adds for servers defined in
+ *  the adapter's other sources. */
+export function isDisabledStub(value: unknown): boolean {
+	return isRecord(value) && Object.keys(value).length === 1 && value.disabled === true;
+}
+
+/** Server names a profile's `mcp` references resolve to. `undefined` (the
+ *  profile declares nothing) means "no filtering" and is reported as the
+ *  literal `"all"`. Glob references follow the same rules as every other
+ *  profile reference. */
+export function resolveAllowedServers(
+	refs: readonly string[] | undefined,
+	discovered: readonly string[],
+): readonly string[] | "all" {
+	if (refs === undefined) return "all";
+	const allowed = new Set<string>();
+	for (const ref of refs) {
+		for (const name of discovered) {
+			if (matchesReference(ref, name)) allowed.add(name);
+		}
+	}
+	return [...allowed];
+}
+
+export interface McpOverlayInput {
+	/** Parsed Pi-global slot document, when the user has one. */
+	slotDocument?: Record<string, unknown>;
+	/** Server names defined in the adapter's other file sources. */
+	otherServerNames: readonly string[];
+	allowed: readonly string[] | "all";
+}
+
+/** Builds the overlay document. Server order is sorted so the serialized
+ *  bytes are stable and a rewrite only happens on a real change. */
+export function buildMcpOverlay(input: McpOverlayInput): Record<string, unknown> {
+	const allowed = input.allowed === "all" ? undefined : new Set(input.allowed);
+	const slotServers = isRecord(input.slotDocument?.mcpServers) ? input.slotDocument.mcpServers : {};
+	const servers: Record<string, unknown> = {};
+	for (const [name, definition] of Object.entries(slotServers)) {
+		if (allowed === undefined || allowed.has(name) || !isRecord(definition)) {
+			servers[name] = definition;
+			continue;
+		}
+		servers[name] = { ...definition, disabled: true };
+	}
+	for (const name of input.otherServerNames) {
+		if (name in servers) continue; // the slot's definition owns the name
+		if (allowed === undefined || allowed.has(name)) continue;
+		servers[name] = { disabled: true };
+	}
+	const document: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(input.slotDocument ?? {})) {
+		if (key !== "mcpServers" && key !== MCP_GENERATED_MARKER) document[key] = value;
+	}
+	document[MCP_GENERATED_MARKER] = { generated: true, version: 1 };
+	document.mcpServers = Object.fromEntries(
+		Object.entries(servers).sort(([left], [right]) => left.localeCompare(right)),
+	);
+	return document;
+}
+
+/** Stable serialization: two runs with the same semantics produce the same
+ *  bytes, so the writer can skip no-op writes. */
+export function serializeMcpOverlay(document: Record<string, unknown>): string {
+	return `${JSON.stringify(document, null, 2)}\n`;
+}

package/src/profile-catalog-store.ts

@@ -37,7 +37,7 @@ export class ProfileCatalogStore {
 
 	/** Validated definitions: missing file → empty; malformed → CatalogError
 	 *  (catalog errors never pass silently, even on the write path).
-	 *  Unknown fields (a legacy `extensions` declaration) are dropped. */
+	 *  Unknown fields (an `extensions` key left over from v0.1.0) are dropped. */
 	async readDefinitions(): Promise<Map<string, ProfileDefinition>> {
 		const result = await readJsonFile(this.#filePath);
 		if (!result.ok) {

package/src/profile-catalog.ts

@@ -7,11 +7,17 @@
  * - A profile references skills, MCP servers, and tools, and may declare
  *   instructions and a model preset. Extensions are not a profile resource:
  *   every installed extension loads natively in every profile.
- * - schemaVersion 1 is current. Version 2 describes the same fields — the
- *   number only marked the era in which `extensions` was still a profile
- *   resource — and reads the same; every save writes version 1.
- * - A legacy `extensions` field is ignored silently, like any other unknown
- *   field: extensions load natively and are managed with `pi install`.
+ * - schemaVersion 1 is the only accepted version: any other value fails
+ *   loudly instead of guessing at a shape.
+ * - Unknown fields (an `extensions` declaration left over from v0.1.0, an
+ *   inheritance key) are ignored silently; saving drops them, so a written
+ *   definition always matches the current shape.
+ * - The catalog key for MCP servers is `mcps` (plural, like `skills` and
+ *   `tools`). The legacy name `mcp` is still READ as an alias so an
+ *   existing catalog keeps its allowlist; `mcps` wins when both keys are
+ *   present, and a value of the wrong type fails loudly either way.
+ *   Definitions always carry the canonical `mcps` field in memory, and
+ *   profile-catalog-store.ts drops a file's legacy key on its next write.
  *
  * Invariants:
  * - The built-in `default` profile never exists in either file and cannot be
@@ -30,8 +36,6 @@ import path from "node:path";
 import { isRecord, readJsonFile } from "./json-file.ts";
 
 export const PROFILE_SCHEMA_VERSION = 1;
-/** The number v0.1.0 wrote for the same field shape: read, never written. */
-const LEGACY_SCHEMA_VERSION = 2;
 export const DEFAULT_PROFILE_NAME = "default";
 
 export interface ProfileModel {
@@ -46,7 +50,7 @@ export interface ProfileDefinition {
 	label?: string;
 	description?: string;
 	skills?: string[];
-	mcp?: string[];
+	mcps?: string[];
 	tools?: string[];
 	model?: ProfileModel;
 	instructions?: string;
@@ -81,6 +85,27 @@ function readStringArray(value: unknown, field: string, profileName: string): st
 	return value as string[];
 }
 
+/** Legacy catalog key names, still accepted on read (canonical name wins).
+ *  The write paths (/profile CRUD, /mcp enable|disable) delete the alias, so
+ *  a file migrates to the canonical spelling the next time it is saved. */
+export const LEGACY_FIELD_ALIASES = { mcps: "mcp" } as const;
+
+/** Reads an array-of-strings field under its canonical name or a legacy
+ *  alias. Both spellings are validated when present, so a value of the
+ *  wrong type never passes silently through either key. */
+function readAliasedStringArray(
+	raw: Record<string, unknown>,
+	canonical: string,
+	legacy: string,
+	profileName: string,
+): string[] | undefined {
+	for (const key of [canonical, legacy]) {
+		if (raw[key] !== undefined) readStringArray(raw[key], key, profileName);
+	}
+	const source = raw[canonical] !== undefined ? canonical : legacy;
+	return readStringArray(raw[source], source, profileName);
+}
+
 function readOptionalString(value: unknown, field: string, profileName: string): string | undefined {
 	if (value === undefined) return undefined;
 	if (typeof value !== "string") {
@@ -91,8 +116,8 @@ function readOptionalString(value: unknown, field: string, profileName: string):
 
 /** Parses one raw profile definition; exported for the write-side store
  *  (profile-catalog-store.ts) so anything written is loadable. Unknown
- *  fields are ignored by design — a legacy `extensions` declaration is
- *  dropped silently, exactly like any other unknown key. */
+ *  fields are ignored by design — an `extensions` key left over from
+ *  v0.1.0 is dropped silently, exactly like any other unknown key. */
 export function parseProfileDefinition(name: string, raw: unknown): ProfileDefinition {
 	if (!isRecord(raw)) {
 		throw new CatalogError(`profile "${name}" must be an object`);
@@ -102,10 +127,12 @@ export function parseProfileDefinition(name: string, raw: unknown): ProfileDefin
 	if (label !== undefined) definition.label = label;
 	const description = readOptionalString(raw.description, "description", name);
 	if (description !== undefined) definition.description = description;
-	for (const field of ["skills", "mcp", "tools"] as const) {
+	for (const field of ["skills", "tools"] as const) {
 		const entries = readStringArray(raw[field], field, name);
 		if (entries !== undefined) definition[field] = entries;
 	}
+	const mcps = readAliasedStringArray(raw, "mcps", LEGACY_FIELD_ALIASES.mcps, name);
+	if (mcps !== undefined) definition.mcps = mcps;
 	if (raw.model !== undefined) {
 		if (!isRecord(raw.model) || typeof raw.model.provider !== "string" || typeof raw.model.id !== "string") {
 			throw new CatalogError(`profile "${name}": "model" must be an object with string "provider" and "id"`);
@@ -125,7 +152,7 @@ export function parseCatalogDocument(value: unknown, filePath: string): Map<stri
 		throw new CatalogError(`${filePath}: catalog must be an object`);
 	}
 	const version = value.schemaVersion;
-	if (version !== PROFILE_SCHEMA_VERSION && version !== LEGACY_SCHEMA_VERSION) {
+	if (version !== PROFILE_SCHEMA_VERSION) {
 		throw new CatalogError(
 			`${filePath}: unsupported schemaVersion ${JSON.stringify(version)} (expected ${PROFILE_SCHEMA_VERSION})`,
 		);

package/src/profile-presets.ts

@@ -25,8 +25,9 @@
  * - `instructions` states behavior, never a capability name, and stays
  *   short: Pi appends it to the system prompt on every turn.
  *
- * `test/profile-presets.test.ts` enforces every rule above and asserts
- * `examples/profiles.json` is exactly this catalog.
+ * `test/profile-presets.test.ts` enforces every rule above, asserts
+ * `examples/profiles.json` is exactly this catalog, and asserts each preset
+ * appears verbatim in `examples/profiles.example.json`.
  */
 
 import type { ProfileDefinition } from "./profile-catalog.ts";

package/src/profile-resolver.ts

@@ -5,7 +5,7 @@
  * ADR-0007 semantics:
  * - `skills` resolves to a visibility filter (see skill-selection.ts), not
  *   to loaded resources: every skill stays loaded and user-invocable.
- * - `mcp` resolves to a runtime server allowlist; a declared MCP intent that
+ * - `mcps` resolves to a runtime server allowlist; a declared MCP intent that
  *   cannot be satisfied (adapter absent, literal server unknown) fails the
  *   activation before anything is applied.
  * - `tools` resolves to an active tool set; literals the live registry does
@@ -136,7 +136,7 @@ function resolveMcp(
 	if (!live.adapterPresent) {
 		throw new SelectionError(
 			`profile "${profileName}" declares MCP servers but pi-mcp-adapter is not active in this session — ` +
-				`install the adapter or remove the "mcp" declaration`,
+				`install the adapter or remove the "mcps" declaration`,
 		);
 	}
 	const selected: string[] = [];
@@ -201,7 +201,7 @@ export function resolveSelection(input: {
 	const definition = profile.definition;
 
 	const skills = resolveSkills(definition.skills, overlay?.disabledSkills ?? [], live.skills);
-	const mcp = resolveMcp(definition.mcp, overlay?.disabledMcp ?? [], live.mcp, profile.name);
+	const mcp = resolveMcp(definition.mcps, overlay?.disabledMcp ?? [], live.mcp, profile.name);
 	const tools = input.suppressTools === true
 		? { pendingTools: [], warning: { toolsUnmatched: [] } }
 		: resolveTools(overlay?.tools ?? definition.tools, live.toolNames);

package/src/runtime-state-store.ts

@@ -33,6 +33,11 @@ export function stateDirFor(source: ProfileSource, dirs: { agentDir: string; cwd
 export interface RuntimeState {
 	activeProfile?: string;
 	overlay?: RuntimeOverlay;
+	/** Patch-only marker: clears `activeProfile` from the store it is sent
+	 *  to, and to that store alone. A profile switch sends it to the OTHER
+	 *  scope's store, so a stale project selection cannot shadow the new
+	 *  global choice on the next startup. Never stored, never read back. */
+	otherActiveProfile?: undefined;
 }
 
 export interface RuntimeOverlay {
@@ -112,6 +117,7 @@ export class RuntimeStateStore {
 			if (patch.overlay === undefined) delete next.overlay;
 			else next.overlay = patch.overlay;
 		}
+		if ("otherActiveProfile" in patch) delete next.activeProfile;
 		await this.write(next);
 		return next;
 	}