pi-profile-switch 0.1.0

package/schemas/profiles.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "pi-profile-switch profile catalog",
+  "description": "Named profile definitions (global ~/.pi/agent/profiles.json or project .pi/profiles.json). Definitions are complete and self-contained: there is no inheritance field, and references are names/globs, never copies. Extensions are not a profile resource (ADR-0007): every installed extension loads natively. The built-in \"default\" profile must not be defined here.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "profiles"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "enum": [1, 2]
+    },
+    "profiles": {
+      "type": "object",
+      "propertyNames": {
+        "not": {
+          "const": "default"
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/profile"
+      }
+    }
+  },
+  "$defs": {
+    "profile": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "label": {
+          "type": "string",
+          "description": "Display label in the selector and /profile list."
+        },
+        "description": {
+          "type": "string"
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Skill names or globs. Controls what the model sees in the system prompt's skills section; every loaded skill stays callable by the user through /skill:name."
+        },
+        "extensions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Deprecated (schemaVersion 1). Extensions are always loaded natively (ADR-0007); the field is ignored with a warning."
+        },
+        "mcp": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "MCP server names or globs, discovered by pi-mcp-adapter configuration. Connection details stay in adapter-managed config."
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Tool names or globs expanded against Pi's live registry (including extension and MCP tools). Names that are not registered yet are retried each turn."
+        },
+        "model": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "provider",
+            "id"
+          ],
+          "properties": {
+            "provider": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "thinkingLevel": {
+              "type": "string"
+            }
+          },
+          "description": "Session-start model preset. An explicit --model/--thinking flag or a model recorded in the session history wins; /profile use applies the preset."
+        },
+        "instructions": {
+          "type": "string",
+          "description": "Appended to Pi's fully built system prompt on every turn."
+        }
+      }
+    }
+  }
+}

package/src/json-file.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared JSON-file reading for pi-profile-switch's file-backed stores (catalog,
+ * resource registry, runtime state). Each store maps read failures to its
+ * own error policy (loud CatalogError/RegistryError vs. quiet state
+ * fallback); this helper only classifies the outcome.
+ */
+
+import { readFile } from "node:fs/promises";
+
+export type JsonFileResult =
+	| { ok: true; value: unknown }
+	| { ok: false; reason: "missing" | "invalid" };
+
+/** Reads and parses a JSON file. Unexpected I/O errors (permissions etc.)
+ *  propagate — only absence and malformed JSON are classified. */
+export async function readJsonFile(filePath: string): Promise<JsonFileResult> {
+	let raw: string;
+	try {
+		raw = await readFile(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

@@ -0,0 +1,63 @@
+/**
+ * AdapterConfigDiscovery: reads the MCP server NAMES pi-mcp-adapter would
+ * discover from its pi-native config files, without ever managing them.
+ *
+ * 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 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.
+ *
+ * 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";
+
+export class McpConfigError extends Error {
+	readonly filePath: string;
+
+	constructor(message: string, filePath: string) {
+		super(message);
+		this.name = "McpConfigError";
+		this.filePath = filePath;
+	}
+}
+
+async function readServerNames(filePath: string): Promise<string[]> {
+	const result = await readJsonFile(filePath);
+	if (!result.ok) {
+		if (result.reason === "missing") {
+			return [];
+		}
+		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);
+}
+
+/** 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);
+		}
+	}
+	return [...names].sort();
+}

package/src/mcp-coordination.ts

@@ -0,0 +1,46 @@
+/**
+ * McpCoordination: the pi-profile-switch ↔ pi-mcp-adapter contract (ADR-0002).
+ *
+ * The adapter's released versions (≤2.33) offer no in-memory server
+ * allowlist, so pi-profile-switch defines the coordination channel the locked
+ * adapter implements:
+ *
+ * - pi-profile-switch publishes the active profile's runtime server allowlist on
+ *   `pi-profile:mcp-allowlist:v1` at activation (session start, `/profile
+ *   use`, `customize`/`reset`, `/mcp enable|disable`). The allowlist is
+ *   memory-only: pi-profile-switch never writes the adapter's `.pi/mcp.json`.
+ * - Adapter presence is probed via the adapter's documented
+ *   request/result event pattern: emit a snapshot request for a bogus
+ *   server name; an installed adapter fills `request.result` synchronously
+ *   (with `{ok: false}` — the name is bogus), an absent adapter leaves it
+ *   undefined.
+ *
+ * Activation probes the adapter and refuses a profile whose declared MCP
+ * intent cannot be satisfied before applying anything.
+ */
+
+/** pi-profile-switch's allowlist channel (the locked adapter subscribes). */
+export const MCP_ALLOWLIST_EVENT = "pi-profile:mcp-allowlist:v1";
+export const MCP_ALLOWLIST_VERSION = 1 as const;
+
+export interface McpAllowlistMessage {
+	version: typeof MCP_ALLOWLIST_VERSION;
+	profile: string;
+	servers: string[];
+}
+
+/** The adapter's snapshot channel, used here purely as a presence probe
+ *  (see the module docblock). Kept as a literal so pi-profile-switch doesn't
+ *  import adapter internals. */
+export const MCP_ADAPTER_SNAPSHOT_EVENT = "pi-mcp-adapter:runtime-snapshot:v1";
+
+/** True when the adapter answered the probe (filled `result` on the
+ *  request object), regardless of the answer — presence, not health. */
+export function probeAdapterPresence(events: { emit(channel: string, data: unknown): void }): boolean {
+	const request: { version: 1; name: string; result?: unknown } = {
+		version: 1,
+		name: "pi-profile:presence-probe",
+	};
+	events.emit(MCP_ADAPTER_SNAPSHOT_EVENT, request);
+	return request.result !== undefined;
+}

package/src/model-selection.ts

@@ -0,0 +1,64 @@
+/**
+ * ModelSelection: when a profile's model preset may take effect.
+ *
+ * The profile model is a PRESET, not an override. Pi's own explicit choices
+ * win:
+ *
+ * 1. `--model` / `--thinking` on the command line.
+ * 2. A model or thinking level recorded in the session history (a resumed
+ *    session restores the user's last choice).
+ * 3. The profile's declaration.
+ * 4. Pi's settings defaults.
+ *
+ * `/profile use` is the user choosing a profile deliberately, so it applies
+ * the preset over 1 and 2.
+ */
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import type { ProfileModel } from "./profile-catalog.ts";
+import type { ExplicitDeclarations } from "./startup-selection.ts";
+
+export interface SessionChoices {
+	hasRecordedModel: boolean;
+	hasRecordedThinking: boolean;
+}
+
+/** Reads whether the session history already states a model or thinking
+ *  level. Process startup is always `reason: "startup"`, so the recorded
+ *  entries — not the event reason — are what distinguishes a resumed
+ *  session from a fresh one. */
+export function readSessionChoices(entries: SessionEntry[]): SessionChoices {
+	let hasRecordedModel = false;
+	let hasRecordedThinking = false;
+	for (const entry of entries) {
+		if (entry.type === "model_change") hasRecordedModel = true;
+		if (entry.type === "thinking_level_change") hasRecordedThinking = true;
+	}
+	return { hasRecordedModel, hasRecordedThinking };
+}
+
+export interface PresetDecisions {
+	model: boolean;
+	thinking: boolean;
+}
+
+/** Decides which halves of the preset may be applied. */
+export function decidePreset(input: {
+	model: ProfileModel | undefined;
+	explicit: ExplicitDeclarations;
+	session: SessionChoices;
+	/** True for an explicit `/profile use` (overrides 1 and 2). */
+	force: boolean;
+}): PresetDecisions {
+	if (input.model === undefined) {
+		return { model: false, thinking: false };
+	}
+	if (input.force) {
+		return { model: true, thinking: true };
+	}
+	return {
+		model: !input.explicit.model && !input.session.hasRecordedModel,
+		thinking: !input.explicit.thinking && !input.session.hasRecordedThinking,
+	};
+}

package/src/name-matching.ts

@@ -0,0 +1,50 @@
+/**
+ * NameMatching: the single implementation of literal/glob reference matching
+ * and did-you-mean suggestions, shared by the resolver (selection) and the
+ * prompt filter (visible skills).
+ */
+
+import { minimatch } from "minimatch";
+
+export function isGlob(pattern: string): boolean {
+	return pattern.includes("*") || pattern.includes("?") || pattern.includes("!");
+}
+
+export function matchesReference(pattern: string, candidate: string): boolean {
+	return isGlob(pattern) ? minimatch(candidate, pattern) : candidate === pattern;
+}
+
+/** Levenshtein distance, used only for did-you-mean hints. */
+function editDistance(a: string, b: string): number {
+	const rows = a.length + 1;
+	const cols = b.length + 1;
+	let previous = Array.from({ length: cols }, (_, index) => index);
+	for (let row = 1; row < rows; row++) {
+		const current = [row];
+		for (let col = 1; col < cols; col++) {
+			const cost = a[row - 1] === b[col - 1] ? 0 : 1;
+			current[col] = Math.min(current[col - 1] + 1, previous[col] + 1, previous[col - 1] + cost);
+		}
+		previous = current;
+	}
+	return previous[cols - 1];
+}
+
+/** Up to three near-name suggestions for a literal reference. */
+export function suggestNames(reference: string, candidates: string[]): string[] {
+	const lowered = reference.toLowerCase();
+	const scored = candidates
+		.map((candidate) => {
+			const loweredCandidate = candidate.toLowerCase();
+			const prefix = loweredCandidate.startsWith(lowered) || lowered.startsWith(loweredCandidate);
+			const contains = loweredCandidate.includes(lowered) || lowered.includes(loweredCandidate);
+			return { candidate, distance: editDistance(lowered, loweredCandidate), prefix, contains };
+		})
+		.filter((entry) => entry.prefix || entry.contains || entry.distance <= Math.max(2, Math.ceil(reference.length / 3)))
+		.sort((a, b) => {
+			if (a.prefix !== b.prefix) return a.prefix ? -1 : 1;
+			if (a.contains !== b.contains) return a.contains ? -1 : 1;
+			return a.distance - b.distance;
+		});
+	return scored.slice(0, 3).map((entry) => entry.candidate);
+}

package/src/profile-catalog-store.ts

@@ -0,0 +1,91 @@
+/**
+ * ProfileCatalogStore: the WRITE side of a profile catalog file, kept
+ * separate from the read-only ProfileCatalog.
+ *
+ * Invariants:
+ * - Whole-file overwrites (pretty-printed, `schemaVersion 2` envelope).
+ *   A version 1 file is read with its `extensions` fields dropped and is
+ *   rewritten as version 2 on the next save; wizard saves never block on
+ *   concurrent edits — re-read at write time, same-name conflicts resolve
+ *   last-write-wins.
+ * - Definitions are complete and self-contained: no inheritance fields
+ *   (`extends`, merge, array append) exist or are accepted.
+ * - Definitions are re-parsed through the catalog's own
+ *   `parseProfileDefinition`, so anything written is loadable;
+ *   "default" is built in and can never be written.
+ * - Writes land in exactly one scope file (global or project).
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { isRecord, readJsonFile } from "./json-file.ts";
+import {
+	CatalogError,
+	DEFAULT_PROFILE_NAME,
+	parseCatalogDocument,
+	parseProfileDefinition,
+	PROFILE_SCHEMA_VERSION,
+	type ProfileDefinition,
+} from "./profile-catalog.ts";
+
+export class ProfileCatalogStore {
+	readonly #filePath: string;
+
+	constructor(catalogPath: string) {
+		this.#filePath = catalogPath;
+	}
+
+	/** Validated definitions: missing file → empty; malformed → CatalogError
+	 *  (catalog errors never pass silently, even on the write path).
+	 *  Version 1 files load with `extensions` dropped. */
+	async readDefinitions(): Promise<Map<string, ProfileDefinition>> {
+		const result = await readJsonFile(this.#filePath);
+		if (!result.ok) {
+			if (result.reason === "missing") return new Map();
+			throw new CatalogError(`invalid JSON in ${this.#filePath}`);
+		}
+		if (!isRecord(result.value)) {
+			throw new CatalogError(`${this.#filePath}: catalog must be an object`);
+		}
+		return parseCatalogDocument(result.value, this.#filePath).profiles;
+	}
+
+	/** Overwrites the file with the given definitions (last write wins). */
+	async writeDefinitions(definitions: ReadonlyMap<string, ProfileDefinition>): Promise<void> {
+		const profiles: Record<string, unknown> = {};
+		for (const [name, definition] of [...definitions.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+			// Round-trip through the parser: only declared, validated fields
+			// are written back (self-contained; no unknown keys survive).
+			profiles[name] = parseProfileDefinition(name, definition);
+		}
+		await mkdir(path.dirname(this.#filePath), { recursive: true });
+		await writeFile(
+			this.#filePath,
+			`${JSON.stringify({ schemaVersion: PROFILE_SCHEMA_VERSION, profiles }, null, 2)}\n`,
+		);
+	}
+
+	/** Inserts or replaces one complete definition. */
+	async upsert(name: string, definition: ProfileDefinition): Promise<void> {
+		if (name.trim().length === 0) {
+			throw new CatalogError(`profile name must be non-empty`);
+		}
+		if (name === DEFAULT_PROFILE_NAME) {
+			throw new CatalogError(`"${DEFAULT_PROFILE_NAME}" is built in and must not be defined in the catalog`);
+		}
+		const definitions = await this.readDefinitions();
+		// Validate before mutating: the wizard's definition must parse.
+		definitions.set(name, parseProfileDefinition(name, definition));
+		await this.writeDefinitions(definitions);
+	}
+
+	/** Removes one profile; unknown names are a loud error, not a no-op. */
+	async remove(name: string): Promise<void> {
+		const definitions = await this.readDefinitions();
+		if (!definitions.delete(name)) {
+			throw new CatalogError(`profile "${name}" not found in ${this.#filePath}`);
+		}
+		await this.writeDefinitions(definitions);
+	}
+}

package/src/profile-catalog.ts

@@ -0,0 +1,234 @@
+/**
+ * ProfileCatalog: reads profile definitions from the global catalog
+ * (`<agentDir>/profiles.json`) and, for trusted projects, the project
+ * catalog (`<projectDir>/.pi/profiles.json`).
+ *
+ * ADR-0007 semantics:
+ * - 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 2 is current. Version 1 files load with their per-profile
+ *   `extensions` field ignored and a warning, so existing catalogs keep
+ *   working without an edit.
+ *
+ * Invariants:
+ * - The built-in `default` profile never exists in either file and cannot be
+ *   redefined there.
+ * - A project profile with the same name fully replaces the global
+ *   definition (no merge, no inheritance); removing the project entry
+ *   immediately reveals the global one.
+ * - The caller passes `projectDir` only when Pi reports the project trusted —
+ *   an untrusted project's catalog is never read.
+ * - A malformed catalog fails loudly (CatalogError) rather than silently
+ *   starting with an unintended selection.
+ */
+
+import path from "node:path";
+
+import { isRecord, readJsonFile } from "./json-file.ts";
+
+export const PROFILE_SCHEMA_VERSION = 2;
+export const DEFAULT_PROFILE_NAME = "default";
+
+export interface ProfileModel {
+	provider: string;
+	id: string;
+	thinkingLevel?: string;
+}
+
+/** A profile definition as stored in a catalog file. All fields optional:
+ *  undeclared fields leave Pi's behavior untouched. */
+export interface ProfileDefinition {
+	label?: string;
+	description?: string;
+	skills?: string[];
+	mcp?: string[];
+	tools?: string[];
+	model?: ProfileModel;
+	instructions?: string;
+}
+
+/** Where a profile's definition came from. */
+export type ProfileSource = "builtin" | "global" | "project";
+
+interface CatalogEntry {
+	source: "global" | "project";
+	definition: ProfileDefinition;
+}
+
+export interface ResolvedProfile {
+	name: string;
+	source: ProfileSource;
+	definition: ProfileDefinition;
+}
+
+/** One parsed catalog file: definitions plus non-fatal compatibility
+ *  warnings the caller surfaces once per activation. */
+export interface CatalogDocument {
+	profiles: Map<string, ProfileDefinition>;
+	warnings: string[];
+}
+
+export class CatalogError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CatalogError";
+	}
+}
+
+function readStringArray(value: unknown, field: string, profileName: string): string[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+		throw new CatalogError(`profile "${profileName}": "${field}" must be an array of strings`);
+	}
+	return value as string[];
+}
+
+function readOptionalString(value: unknown, field: string, profileName: string): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") {
+		throw new CatalogError(`profile "${profileName}": "${field}" must be a string`);
+	}
+	return value;
+}
+
+/** 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 — `extensions` is reported by
+ *  parseCatalogDocument, which has the file path for the warning. */
+export function parseProfileDefinition(name: string, raw: unknown): ProfileDefinition {
+	if (!isRecord(raw)) {
+		throw new CatalogError(`profile "${name}" must be an object`);
+	}
+	const definition: ProfileDefinition = {};
+	const label = readOptionalString(raw.label, "label", name);
+	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) {
+		const entries = readStringArray(raw[field], field, name);
+		if (entries !== undefined) definition[field] = entries;
+	}
+	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"`);
+		}
+		const thinkingLevel = readOptionalString(raw.model.thinkingLevel, "model.thinkingLevel", name);
+		definition.model = { provider: raw.model.provider, id: raw.model.id, ...(thinkingLevel ? { thinkingLevel } : {}) };
+	}
+	const instructions = readOptionalString(raw.instructions, "instructions", name);
+	if (instructions !== undefined) definition.instructions = instructions;
+	return definition;
+}
+
+/** Parses one catalog document. Missing files are handled by the caller;
+ *  this function sees only parsed JSON. */
+export function parseCatalogDocument(value: unknown, filePath: string): CatalogDocument {
+	if (!isRecord(value)) {
+		throw new CatalogError(`${filePath}: catalog must be an object`);
+	}
+	const warnings: string[] = [];
+	const version = value.schemaVersion;
+	if (version !== 1 && version !== PROFILE_SCHEMA_VERSION) {
+		throw new CatalogError(
+			`${filePath}: unsupported schemaVersion ${JSON.stringify(version)} (expected ${PROFILE_SCHEMA_VERSION})`,
+		);
+	}
+	if (version === 1) {
+		warnings.push(
+			`${filePath}: schemaVersion 1 is read as version ${PROFILE_SCHEMA_VERSION}; profiles declaring "extensions" are upgraded with that field ignored`,
+		);
+	}
+	if (!isRecord(value.profiles)) {
+		throw new CatalogError(`${filePath}: "profiles" must be an object mapping names to definitions`);
+	}
+	const profiles = new Map<string, ProfileDefinition>();
+	for (const [name, raw] of Object.entries(value.profiles)) {
+		if (name === DEFAULT_PROFILE_NAME) {
+			throw new CatalogError(
+				`${filePath}: "${DEFAULT_PROFILE_NAME}" is built in and must not be defined in the catalog`,
+			);
+		}
+		if (isRecord(raw) && raw.extensions !== undefined) {
+			warnings.push(
+				`${filePath}: profile "${name}" declares "extensions"; extensions are always loaded natively (ADR-0007) and the field is ignored — manage extensions with pi install`,
+			);
+		}
+		profiles.set(name, parseProfileDefinition(name, raw));
+	}
+	return { profiles, warnings };
+}
+
+/** Reads one catalog file; missing → empty map, malformed → CatalogError. */
+async function loadCatalogFile(catalogPath: string): Promise<CatalogDocument> {
+	const result = await readJsonFile(catalogPath);
+	if (!result.ok) {
+		if (result.reason === "missing") return { profiles: new Map(), warnings: [] };
+		throw new CatalogError(`invalid JSON in ${catalogPath}`);
+	}
+	return parseCatalogDocument(result.value, catalogPath);
+}
+
+export class ProfileCatalog {
+	readonly #profiles: ReadonlyMap<string, CatalogEntry>;
+	readonly #warnings: readonly string[];
+
+	private constructor(profiles: ReadonlyMap<string, CatalogEntry>, warnings: readonly string[]) {
+		this.#profiles = profiles;
+		this.#warnings = warnings;
+	}
+
+	/** Compatibility warnings from reading the catalog files (v1 schema,
+	 *  ignored `extensions` fields). Empty for a current, well-formed pair. */
+	get warnings(): readonly string[] {
+		return this.#warnings;
+	}
+
+	/**
+	 * Reads the global catalog, plus the project catalog when `projectDir` is
+	 * given (trusted projects only — the caller gates on Pi's trust check).
+	 * Missing files mean an empty catalog; malformed content throws
+	 * CatalogError. Project entries replace same-name global entries.
+	 */
+	static async load(agentDir: string, options?: { projectDir?: string }): Promise<ProfileCatalog> {
+		const global = await loadCatalogFile(path.join(agentDir, "profiles.json"));
+		const profiles = new Map<string, CatalogEntry>();
+		const warnings = [...global.warnings];
+		for (const [name, definition] of global.profiles) {
+			profiles.set(name, { source: "global", definition });
+		}
+		if (options?.projectDir !== undefined) {
+			const project = await loadCatalogFile(path.join(options.projectDir, ".pi", "profiles.json"));
+			warnings.push(...project.warnings);
+			for (const [name, definition] of project.profiles) {
+				profiles.set(name, { source: "project", definition });
+			}
+		}
+		return new ProfileCatalog(profiles, warnings);
+	}
+
+	/** Resolves a profile by name. `default` always resolves to the built-in
+	 *  no-op profile; unknown names return undefined. */
+	resolve(name: string): ResolvedProfile | undefined {
+		if (name === DEFAULT_PROFILE_NAME) {
+			return { name: DEFAULT_PROFILE_NAME, source: "builtin", definition: {} };
+		}
+		const entry = this.#profiles.get(name);
+		return entry === undefined ? undefined : { name, source: entry.source, definition: entry.definition };
+	}
+
+	/** Lists the built-in default first, then profiles in file order (global
+	 *  entries in global order, project-only names appended after). */
+	list(): ResolvedProfile[] {
+		return [
+			this.resolve(DEFAULT_PROFILE_NAME)!,
+			...[...this.#profiles.keys()].map((name) => this.resolve(name)!),
+		];
+	}
+
+	/** True when a global definition of the same name is shadowed by the
+	 *  project entry. */
+	shadowsGlobal(name: string): boolean {
+		return this.#profiles.get(name)?.source === "project";
+	}
+}