pi-profile-switch 0.7.0 → 0.8.0

package/README.md

@@ -27,72 +27,62 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## Define your own profiles
 
-Profiles live in two JSON files, both optional:
+Profiles live in two directories, with one JSON file per profile:
 
-| File | Scope |
+| Path | Scope |
 | --- | --- |
-| `~/.pi-profile-switch/profiles.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the root; `~/.pi/agent/profiles.json` is read as a legacy fallback for migration. |
-| `<project>/.pi/profiles.json` | Project-level, trusted projects only. |
+| `~/.pi-profile-switch/profiles/<name>.json` | Global, all projects. `PI_PROFILE_SWITCH_DIR` overrides the workspace root. |
+| `<project>/.pi/profiles/<name>.json` | Project-level, trusted projects only. |
 
-Create or change a profile by editing the JSON directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
+Create or change a profile by editing or creating a `<name>.json` file directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
 
-On install, pi-profile-switch seeds the global file with a starter **`ask`** profile — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
+On install, pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "ask": {
-      "label": "Ask & Discuss",
-      "description": "Read-only Q&A and code exploration; no file modifications or command execution",
-      "skills": [],
-      "extensions": [],
-      "tools": ["read", "grep", "find", "ls"],
-      "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
-    }
-  }
+  "label": "Ask & Discuss",
+  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
+  "skills": [],
+  "extensions": [],
+  "tools": ["read", "grep", "find", "ls"],
+  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
 }
 ```
 
-One profile can use every field at once. This example `impl` profile loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
+One profile can use every field at once. This example `impl` profile (`impl.json`) loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }
 ```
 
@@ -103,7 +93,15 @@ How fields resolve:
 - `mcps` references servers from your pi-mcp-adapter configuration; connection details stay in the adapter's own config.
 - Any field you omit keeps plain Pi behavior.
 
-The files in [`examples/`](examples/) mirror the two profiles above: `profiles.json` is the seeded starter, `example.json` the full-field demo.
+The files in [`examples/`](examples/) mirror the two profiles above: `ask.json` is the seeded starter, `example.json` the full-field demo.
+
+### Migrating from earlier versions
+
+If you used an earlier version that stored all profiles in a single `profiles.json` (`schemaVersion: 1`), migrate manually by creating a file for each profile under the `profiles/` directory:
+
+1. Create directory `~/.pi-profile-switch/profiles/` (or `<project>/.pi/profiles/`).
+2. For each key `<name>` in your old `profiles.json`'s `profiles` object, save its value directly as `<name>.json`.
+3. Drop the outer `schemaVersion` and `profiles` envelope.
 
 ## Commands
 

package/README.zh-CN.md

@@ -27,72 +27,62 @@ pi-profile ask -- --model openai/gpt-5.4
 
 ## 自定义 profile
 
-profile 定义在两个 JSON 文件中，均可选：
+profile 保存在两个目录中，每个 profile 对应一个独立 JSON 文件：
 
-| 文件 | 作用域 |
+| 路径 | 作用域 |
 | --- | --- |
-| `~/.pi-profile-switch/profiles.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录；`~/.pi/agent/profiles.json` 作为遗留路径向下兼容，用于迁移。 |
-| `<项目>/.pi/profiles.json` | 项目级，仅对已信任项目生效。 |
+| `~/.pi-profile-switch/profiles/<name>.json` | 全局，对所有项目生效。`PI_PROFILE_SWITCH_DIR` 可自定义根目录。 |
+| `<项目>/.pi/profiles/<name>.json` | 项目级，仅对已信任项目生效。 |
 
-直接编辑 JSON 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
+直接编辑或新建 `<name>.json` 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
 
-安装时，pi-profile-switch 会向全局文件播种一个初始 **`ask`** profile——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
+安装时，pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "ask": {
-      "label": "Ask & Discuss",
-      "description": "Read-only Q&A and code exploration; no file modifications or command execution",
-      "skills": [],
-      "extensions": [],
-      "tools": ["read", "grep", "find", "ls"],
-      "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
-    }
-  }
+  "label": "Ask & Discuss",
+  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
+  "skills": [],
+  "extensions": [],
+  "tools": ["read", "grep", "find", "ls"],
+  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
 }
 ```
 
-一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
+一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例（`impl.json`）加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
 
 ```json
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }
 ```
 
@@ -103,7 +93,15 @@ profile 定义在两个 JSON 文件中，均可选：
 - `mcps` 引用 pi-mcp-adapter 配置中的 server；连接细节留在 adapter 自己的配置里。
 - 未写的字段保持原生 Pi 行为。
 
-[`examples/`](examples/) 中的两个文件与上面一一对应：`profiles.json` 是播种的初始 profile，`example.json` 是全字段演示。
+[`examples/`](examples/) 中的两个文件与上面一一对应：`ask.json` 是播种的初始 profile，`example.json` 是全字段演示。
+
+### 从旧版本迁移
+
+如果你之前使用了把全部 profile 存在单个 `profiles.json`（含 `schemaVersion: 1`）的旧版本，请手动把每个 profile 拆分到 `profiles/` 目录：
+
+1. 创建 `~/.pi-profile-switch/profiles/`（或 `<项目>/.pi/profiles/`）目录。
+2. 将旧 `profiles.json` 中 `profiles` 下的每个 `<name>` 键值提取为独立的 `<name>.json` 文件。
+3. 去除外层的 `schemaVersion` 与 `profiles` 信封，文件顶层即为裸 profile 定义。
 
 ## 命令
 

package/bin/postinstall.js

@@ -1,29 +1,25 @@
 #!/usr/bin/env node
 /**
- * postinstall: seed the global catalog with the default profiles file.
+ * postinstall: seed the global catalog with the default starter profile.
  *
  * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
  * Idempotent and conservative:
- * - Writes the shipped `examples/profiles.json` starter catalog to the
- *   profile-switch dir ONLY when no
- *   catalog exists there yet (COPYFILE_EXCL; an existing file — including
- *   one written concurrently — is never touched).
- * - Skips entirely when a legacy `~/.pi/agent/profiles.json` exists, because
- *   the resolver still falls back to it and a new preferred-path file would
- *   silently shadow it (see src/workspace.ts resolveGlobalProfilesPath).
+ * - Writes the shipped `examples/ask.json` starter profile to the
+ *   profiles dir ONLY when no .json profile exists there yet
+ *   (COPYFILE_EXCL; an existing file — including one written concurrently — is never touched).
  * - Never fails the install: errors are downgraded to a warning.
  *
  * This module is plain Node ESM (no jiti/TS): npm may run postinstall in a
  * context where only plain JS is safe. The path rules intentionally mirror
  * src/workspace.ts — keep them in sync.
  */
-import { access, copyFile, mkdir } from "node:fs/promises";
+import { copyFile, mkdir, readdir } from "node:fs/promises";
 import { constants } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-const DEFAULT_TEMPLATE = fileURLToPath(new URL("../examples/profiles.json", import.meta.url));
+const DEFAULT_TEMPLATE = fileURLToPath(new URL("../examples/ask.json", import.meta.url));
 
 /** Mirrors getProfileSwitchDir() in src/workspace.ts.
  *  @param {NodeJS.ProcessEnv} env */
@@ -33,38 +29,40 @@ function profileSwitchDir(env) {
 	return path.join(homedir(), ".pi-profile-switch");
 }
 
-/** The legacy migration fallback the resolver still reads (~/.pi/agent).
+/** Mirrors getGlobalProfilesDir() in src/workspace.ts.
  *  @param {NodeJS.ProcessEnv} env */
-function legacyCatalogPath(env) {
-	const agentDir = env.PI_CODING_AGENT_DIR ?? path.join(homedir(), ".pi", "agent");
-	return path.join(agentDir, "profiles.json");
+function globalProfilesDir(env) {
+	return path.join(profileSwitchDir(env), "profiles");
 }
 
-/** @param {string} filePath */
-async function exists(filePath) {
+/** Checks whether the directory exists and contains any .json files.
+ *  @param {string} dir */
+async function hasAnyJsonProfiles(dir) {
 	try {
-		await access(filePath);
-		return true;
+		const entries = await readdir(dir);
+		return entries.some((name) => name.endsWith(".json"));
 	} catch {
 		return false;
 	}
 }
 
-/** @typedef {{ path: string, written: boolean, skipped?: string }} InstallResult */
+/** @typedef {{ path: string, written: boolean }} InstallResult */
 
 /**
- * Seeds the default catalog. Safe to call repeatedly; only the first call
- * writes.
+ * Seeds the default starter profile. Safe to call repeatedly; only writes
+ * if no .json files exist in the global profiles directory.
  * @param {{ env?: NodeJS.ProcessEnv }} [options]
  * @returns {Promise<InstallResult>}
  */
 export async function installDefaultProfiles({ env = process.env } = {}) {
-	const target = path.join(profileSwitchDir(env), "profiles.json");
-	if (await exists(target)) return { path: target, written: false };
-	if (await exists(legacyCatalogPath(env))) {
-		return { path: target, written: false, skipped: "legacy-catalog-present" };
+	const dir = globalProfilesDir(env);
+	const target = path.join(dir, "ask.json");
+
+	if (await hasAnyJsonProfiles(dir)) {
+		return { path: target, written: false };
 	}
-	await mkdir(path.dirname(target), { recursive: true });
+
+	await mkdir(dir, { recursive: true });
 	try {
 		await copyFile(DEFAULT_TEMPLATE, target, constants.COPYFILE_EXCL);
 	} catch (error) {
@@ -80,10 +78,10 @@ const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pat
 if (invokedDirectly) {
 	installDefaultProfiles().then(
 		(result) => {
-			if (result.written) console.log(`pi-profile: seeded default profiles at ${result.path}`);
+			if (result.written) console.log(`pi-profile: seeded starter profile at ${result.path}`);
 		},
 		(error) => {
-			console.warn(`pi-profile: could not seed default profiles: ${error instanceof Error ? error.message : error}`);
+			console.warn(`pi-profile: could not seed starter profile: ${error instanceof Error ? error.message : error}`);
 		},
 	);
 }

package/examples/ask.json

@@ -0,0 +1,13 @@
+{
+  "label": "Ask & Discuss",
+  "description": "Read-only Q&A and code exploration; no file modifications or command execution",
+  "skills": [],
+  "extensions": [],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls"
+  ],
+  "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
+}

package/examples/example.json

@@ -1,37 +1,32 @@
 {
-  "schemaVersion": 1,
-  "profiles": {
-    "impl": {
-      "label": "Implementation",
-      "description": "Full-powered implementation profile: every available field, pinned model",
-      "skills": [
-        "tdd",
-        "internal-*",
-        "mcp-scripting"
-      ],
-      "extensions": [
-        "pi-mcp-adapter"
-      ],
-      "mcps": [
-        "github",
-        "linear"
-      ],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls",
-        "bash",
-        "edit",
-        "write",
-        "mcp__*",
-        "github_*",
-        "linear_*"
-      ],
-      "defaultProvider": "anthropic",
-      "defaultModel": "claude-sonnet-4-5",
-      "defaultThinkingLevel": "high",
-      "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
-    }
-  }
+  "label": "Implementation",
+  "description": "Full-powered implementation profile: every available field, pinned model",
+  "skills": [
+    "tdd",
+    "internal-*",
+    "mcp-scripting"
+  ],
+  "extensions": [
+    "pi-mcp-adapter"
+  ],
+  "mcps": [
+    "github",
+    "linear"
+  ],
+  "tools": [
+    "read",
+    "grep",
+    "find",
+    "ls",
+    "bash",
+    "edit",
+    "write",
+    "mcp__*",
+    "github_*",
+    "linear_*"
+  ],
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-5",
+  "defaultThinkingLevel": "high",
+  "instructions": "Prefer small, verifiable changes. Run the test suite before claiming completion."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [

package/schemas/profiles.schema.json

@@ -1,86 +1,60 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "pi-profile-switch profile catalog",
-  "description": "Named profile definitions (global ~/.pi-profile-switch/profiles.json, legacy fallback ~/.pi/agent/profiles.json; or project .pi/profiles.json). Definitions are complete and self-contained: there is no inheritance field, and resource references are names/globs, never copies. The built-in \"default\" profile must not be defined here.",
+  "title": "pi-profile-switch profile definition",
+  "description": "A named profile definition stored in ~/.pi-profile-switch/profiles/<name>.json or <project>/.pi/profiles/<name>.json. Definitions are complete and self-contained: there is no inheritance field, and resource references are names/globs, never copies.",
   "type": "object",
-  "required": [
-    "schemaVersion",
-    "profiles"
-  ],
   "additionalProperties": false,
   "properties": {
-    "schemaVersion": {
-      "const": 1
+    "label": {
+      "type": "string",
+      "description": "Display label in the selector and /profile list."
     },
-    "profiles": {
-      "type": "object",
-      "propertyNames": {
-        "not": {
-          "const": "default"
-        }
+    "description": {
+      "type": "string"
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "string"
       },
-      "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 (e.g. \"review\", \"internal-*\") referencing discovered skills."
-        },
-        "extensions": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Extension names or globs. Package names, source aliases, loose-file stems, glob patterns, or direct file paths, resolved against discovered extensions."
-        },
-        "mcps": {
-          "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 tools)."
-        },
-        "defaultProvider": {
-          "type": "string",
-          "description": "Startup provider for this profile (e.g. \"anthropic\", \"openai\"). Mirrors Pi's settings.defaultProvider."
-        },
-        "defaultModel": {
-          "type": "string",
-          "description": "Startup model ID for this profile. Mirrors Pi's settings.defaultModel."
-        },
-        "defaultThinkingLevel": {
-          "type": "string",
-          "description": "Startup thinking level for this profile. Mirrors Pi's settings.defaultThinkingLevel."
-        },
-        "instructions": {
-          "type": "string",
-          "description": "Appended to Pi's fully built system prompt on every turn."
-        }
-      }
+      "description": "Skill names or globs (e.g. \"review\", \"internal-*\") referencing discovered skills."
+    },
+    "extensions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Extension names or globs. Package names, source aliases, loose-file stems, glob patterns, or direct file paths, resolved against discovered extensions."
+    },
+    "mcps": {
+      "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 tools)."
+    },
+    "defaultProvider": {
+      "type": "string",
+      "description": "Startup provider for this profile (e.g. \"anthropic\", \"openai\"). Mirrors Pi's settings.defaultProvider."
+    },
+    "defaultModel": {
+      "type": "string",
+      "description": "Startup model ID for this profile. Mirrors Pi's settings.defaultModel."
+    },
+    "defaultThinkingLevel": {
+      "type": "string",
+      "description": "Startup thinking level for this profile. Mirrors Pi's settings.defaultThinkingLevel."
+    },
+    "instructions": {
+      "type": "string",
+      "description": "Appended to Pi's fully built system prompt on every turn."
     }
   }
 }

package/src/profile-catalog-store.ts

@@ -1,109 +1,86 @@
 /**
- * ProfileCatalogStore: the WRITE side of a profile catalog file
- * (ticket 09), kept separate from the read-only ProfileCatalog.
+ * ProfileCatalogStore: the WRITE side of profile catalog files,
+ * storing each profile in its own `<name>.json` file.
  *
  * Invariants:
- * - Whole-file overwrites (pretty-printed, schemaVersion envelope);
- *   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.
+ * - Single-file operations (pretty-printed JSON without schemaVersion envelope).
+ * - Writes land in `<dir>/<name>.json` via a temporary file + rename.
+ * - Names must match `PROFILE_NAME_PATTERN` and cannot be "default".
+ * - Definitions are complete and self-contained: no inheritance fields exist.
  * - 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).
+ *   `parseProfileDefinition`, so anything written is loadable.
+ * - Writes land in exactly one scope directory (global or project).
  */
 
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, rename, rm, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-import { isRecord, readJsonFile } from "./json-file.ts";
 import {
 	CatalogError,
 	DEFAULT_PROFILE_NAME,
+	loadCatalogDirectory,
 	parseProfileDefinition,
-	PROFILE_SCHEMA_VERSION,
+	PROFILE_NAME_PATTERN,
 	type ProfileDefinition,
 } from "./profile-catalog.ts";
 
 export class ProfileCatalogStore {
-	readonly #filePath: string;
-	readonly #fallbackPath?: string;
+	readonly #dirPath: string;
 
-	constructor(catalogPath: string, fallbackPath?: string) {
-		this.#filePath = catalogPath;
-		this.#fallbackPath = fallbackPath;
+	constructor(catalogDir: string) {
+		this.#dirPath = catalogDir;
 	}
 
-	/** Validated definitions: missing file → empty; malformed → CatalogError
+	/** Validated definitions: missing directory → empty; malformed → CatalogError
 	 *  (catalog errors never pass silently, even on the write path). */
 	async readDefinitions(): Promise<Map<string, ProfileDefinition>> {
-		let result = await readJsonFile(this.#filePath);
-		if (!result.ok && result.reason === "missing" && this.#fallbackPath) {
-			result = await readJsonFile(this.#fallbackPath);
-		}
-		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`);
-		}
-		if (result.value.schemaVersion !== PROFILE_SCHEMA_VERSION) {
-			throw new CatalogError(
-				`${this.#filePath}: unsupported schemaVersion ${JSON.stringify(result.value.schemaVersion)} (expected ${PROFILE_SCHEMA_VERSION})`,
-			);
-		}
-		if (!isRecord(result.value.profiles)) {
-			throw new CatalogError(`${this.#filePath}: "profiles" must be an object mapping names to definitions`);
-		}
-		const definitions = new Map<string, ProfileDefinition>();
-		for (const [name, raw] of Object.entries(result.value.profiles)) {
-			if (name === DEFAULT_PROFILE_NAME) {
-				throw new CatalogError(
-					`${this.#filePath}: "${DEFAULT_PROFILE_NAME}" is built in and must not be defined in the catalog`,
-				);
-			}
-			definitions.set(name, parseProfileDefinition(name, raw));
-		}
-		return definitions;
-	}
-
-	/** 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`,
-		);
+		return loadCatalogDirectory(this.#dirPath);
 	}
 
-	/** Inserts or replaces one complete definition. */
+	/** Inserts or replaces one complete definition (via atomic rename). */
 	async upsert(name: string, definition: ProfileDefinition): Promise<void> {
-		if (name.trim().length === 0) {
-			throw new CatalogError(`profile name must be non-empty`);
+		if (!PROFILE_NAME_PATTERN.test(name)) {
+			throw new CatalogError(`invalid profile name "${name}" (must match ${PROFILE_NAME_PATTERN})`);
 		}
 		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);
+
+		// Validate before mutating: the definition must parse.
+		const validated = parseProfileDefinition(name, definition);
+
+		await mkdir(this.#dirPath, { recursive: true });
+		const targetPath = path.join(this.#dirPath, `${name}.json`);
+		const tempPath = path.join(
+			this.#dirPath,
+			`.${name}.json.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
+		);
+
+		try {
+			await writeFile(tempPath, `${JSON.stringify(validated, null, 2)}\n`);
+			await rename(tempPath, targetPath);
+		} catch (error) {
+			await rm(tempPath, { force: true });
+			throw error;
+		}
 	}
 
 	/** 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}`);
+		if (!PROFILE_NAME_PATTERN.test(name)) {
+			throw new CatalogError(`invalid profile name "${name}" (must match ${PROFILE_NAME_PATTERN})`);
+		}
+		if (name === DEFAULT_PROFILE_NAME) {
+			throw new CatalogError(`"${DEFAULT_PROFILE_NAME}" is built in and cannot be deleted`);
+		}
+		const targetPath = path.join(this.#dirPath, `${name}.json`);
+		try {
+			await unlink(targetPath);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				throw new CatalogError(`profile "${name}" not found in ${this.#dirPath}`);
+			}
+			throw error;
 		}
-		await this.writeDefinitions(definitions);
 	}
 }

package/src/profile-catalog.ts

@@ -1,27 +1,31 @@
 /**
  * ProfileCatalog: reads profile definitions from the global catalog
- * (`~/.pi-profile-switch/profiles.json`, legacy fallback `<agentDir>/profiles.json`)
- * and, for trusted projects, the project catalog (`<projectDir>/.pi/profiles.json`).
+ * (`~/.pi-profile-switch/profiles/`, or `PI_PROFILE_SWITCH_DIR/profiles/`)
+ * and, for trusted projects, the project catalog (`<projectDir>/.pi/profiles/`).
  *
  * Invariants:
- * - The built-in `default` profile never exists in either file and cannot be
- *   redefined there.
+ * - Each profile is stored in a separate `<name>.json` file.
+ * - The built-in `default` profile never exists as a file and cannot be
+ *   defined in any catalog (`default.json` is a hard error).
+ * - Profile names must match `^[A-Za-z0-9][A-Za-z0-9._-]*$`.
  * - A project profile with the same name fully replaces the global
- *   definition (no merge, no inheritance); removing the project entry
+ *   definition (no merge, no inheritance); removing the project file
  *   immediately reveals the global one.
  * - The caller passes `projectDir` only when the resolver's trust check
  *   passed — an untrusted project's catalog is never read.
- * - A malformed catalog fails loudly (CatalogError) rather than silently
- *   starting unfiltered.
+ * - A malformed profile file fails loudly (CatalogError) with its file path
+ *   rather than silently starting unfiltered.
  */
 
+import type { Dirent } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
 
-import { resolveGlobalProfilesPath } from "./workspace.ts";
+import { getGlobalProfilesDir } from "./workspace.ts";
 import { isRecord, readJsonFile } from "./json-file.ts";
 
-export const PROFILE_SCHEMA_VERSION = 1;
 export const DEFAULT_PROFILE_NAME = "default";
+export const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
 export interface ProfileModel {
 	provider: string;
@@ -67,75 +71,102 @@ export class CatalogError extends Error {
 	}
 }
 
-function readStringArray(value: unknown, field: string, profileName: string): string[] | undefined {
+function readStringArray(value: unknown, field: string, profileName: string, filePath?: 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`);
+		const prefix = filePath ? `${filePath}: ` : "";
+		throw new CatalogError(`${prefix}profile "${profileName}": "${field}" must be an array of strings`);
 	}
 	return value as string[];
 }
 
-function readOptionalString(value: unknown, field: string, profileName: string): string | undefined {
+function readOptionalString(value: unknown, field: string, profileName: string, filePath?: string): string | undefined {
 	if (value === undefined) return undefined;
 	if (typeof value !== "string") {
-		throw new CatalogError(`profile "${profileName}": "${field}" must be a string`);
+		const prefix = filePath ? `${filePath}: ` : "";
+		throw new CatalogError(`${prefix}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. */
-export function parseProfileDefinition(name: string, raw: unknown): ProfileDefinition {
+export function parseProfileDefinition(name: string, raw: unknown, filePath?: string): ProfileDefinition {
 	if (!isRecord(raw)) {
-		throw new CatalogError(`profile "${name}" must be an object`);
+		const prefix = filePath ? `${filePath}: ` : "";
+		throw new CatalogError(`${prefix}profile "${name}" must be an object`);
 	}
 	const definition: ProfileDefinition = {};
-	const label = readOptionalString(raw.label, "label", name);
+	const label = readOptionalString(raw.label, "label", name, filePath);
 	if (label !== undefined) definition.label = label;
-	const description = readOptionalString(raw.description, "description", name);
+	const description = readOptionalString(raw.description, "description", name, filePath);
 	if (description !== undefined) definition.description = description;
 	for (const field of ["skills", "extensions", "mcps", "tools"] as const) {
-		const entries = readStringArray(raw[field], field, name);
+		const entries = readStringArray(raw[field], field, name, filePath);
 		if (entries !== undefined) definition[field] = entries;
 	}
-	const defaultProvider = readOptionalString(raw.defaultProvider, "defaultProvider", name);
+	const defaultProvider = readOptionalString(raw.defaultProvider, "defaultProvider", name, filePath);
 	if (defaultProvider !== undefined) definition.defaultProvider = defaultProvider;
-	const defaultModel = readOptionalString(raw.defaultModel, "defaultModel", name);
+	const defaultModel = readOptionalString(raw.defaultModel, "defaultModel", name, filePath);
 	if (defaultModel !== undefined) definition.defaultModel = defaultModel;
-	const defaultThinkingLevel = readOptionalString(raw.defaultThinkingLevel, "defaultThinkingLevel", name);
+	const defaultThinkingLevel = readOptionalString(raw.defaultThinkingLevel, "defaultThinkingLevel", name, filePath);
 	if (defaultThinkingLevel !== undefined) definition.defaultThinkingLevel = defaultThinkingLevel;
-	const instructions = readOptionalString(raw.instructions, "instructions", name);
+	const instructions = readOptionalString(raw.instructions, "instructions", name, filePath);
 	if (instructions !== undefined) definition.instructions = instructions;
 	return definition;
 }
 
-/** Reads one catalog file; missing → empty map, malformed → CatalogError. */
-async function loadCatalogFile(catalogPath: string): Promise<Map<string, ProfileDefinition>> {
-	const result = await readJsonFile(catalogPath);
-	const profiles = new Map<string, ProfileDefinition>();
-	if (!result.ok) {
-		if (result.reason === "missing") return profiles;
-		throw new CatalogError(`invalid JSON in ${catalogPath}`);
-	}
-	const parsed = result.value;
-	if (!isRecord(parsed)) {
-		throw new CatalogError(`${catalogPath}: catalog must be an object`);
-	}
-	if (parsed.schemaVersion !== PROFILE_SCHEMA_VERSION) {
-		throw new CatalogError(
-			`${catalogPath}: unsupported schemaVersion ${JSON.stringify(parsed.schemaVersion)} (expected ${PROFILE_SCHEMA_VERSION})`,
-		);
-	}
-	if (!isRecord(parsed.profiles)) {
-		throw new CatalogError(`${catalogPath}: "profiles" must be an object mapping names to definitions`);
+/** Reads one catalog directory; missing directory → empty map, malformed file → CatalogError. */
+export async function loadCatalogDirectory(dirPath: string): Promise<Map<string, ProfileDefinition>> {
+	let entries: Dirent[];
+	try {
+		entries = await readdir(dirPath, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return new Map();
+		}
+		throw error;
 	}
-	for (const [name, definition] of Object.entries(parsed.profiles)) {
-		if (name === DEFAULT_PROFILE_NAME) {
+
+	// Filter to .json files and sort alphabetically by file name
+	const jsonEntries = entries.filter((entry) => entry.name.endsWith(".json"));
+	jsonEntries.sort((a, b) => a.name.localeCompare(b.name));
+
+	const profiles = new Map<string, ProfileDefinition>();
+	for (const entry of jsonEntries) {
+		const fullPath = path.join(dirPath, entry.name);
+		let isFile = entry.isFile();
+		if (!isFile && entry.isSymbolicLink()) {
+			try {
+				const st = await stat(fullPath);
+				isFile = st.isFile();
+			} catch {
+				continue;
+			}
+		}
+		if (!isFile) continue;
+
+		const profileName = entry.name.slice(0, -".json".length);
+		if (profileName === DEFAULT_PROFILE_NAME) {
 			throw new CatalogError(
-				`${catalogPath}: "${DEFAULT_PROFILE_NAME}" is built in and must not be defined in the catalog`,
+				`${fullPath}: "${DEFAULT_PROFILE_NAME}" is built in and must not be defined in the catalog`,
 			);
 		}
-		profiles.set(name, parseProfileDefinition(name, definition));
+		if (!PROFILE_NAME_PATTERN.test(profileName)) {
+			throw new CatalogError(
+				`${fullPath}: invalid profile name "${profileName}" (must match ${PROFILE_NAME_PATTERN})`,
+			);
+		}
+
+		const result = await readJsonFile(fullPath);
+		if (!result.ok) {
+			throw new CatalogError(`invalid JSON in ${fullPath}`);
+		}
+		const parsed = result.value;
+		if (!isRecord(parsed)) {
+			throw new CatalogError(`${fullPath}: profile definition must be an object`);
+		}
+		profiles.set(profileName, parseProfileDefinition(profileName, parsed, fullPath));
 	}
 	return profiles;
 }
@@ -150,17 +181,17 @@ export class ProfileCatalog {
 	/**
 	 * Reads the global catalog, plus the project catalog when `projectDir` is
 	 * given (trusted projects only — the caller gates on the trust check).
-	 * Missing files mean an empty catalog; malformed content throws
+	 * Missing directories 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 globalProfiles = await loadCatalogFile(resolveGlobalProfilesPath(agentDir));
+	static async load(_agentDir: string, options?: { projectDir?: string }): Promise<ProfileCatalog> {
+		const globalProfiles = await loadCatalogDirectory(getGlobalProfilesDir());
 		const profiles = new Map<string, CatalogEntry>();
 		for (const [name, definition] of globalProfiles) {
 			profiles.set(name, { source: "global", definition });
 		}
 		if (options?.projectDir !== undefined) {
-			const projectProfiles = await loadCatalogFile(path.join(options.projectDir, ".pi", "profiles.json"));
+			const projectProfiles = await loadCatalogDirectory(path.join(options.projectDir, ".pi", "profiles"));
 			for (const [name, definition] of projectProfiles) {
 				profiles.set(name, { source: "project", definition });
 			}
@@ -179,7 +210,7 @@ export class ProfileCatalog {
 	}
 
 	/** Lists the built-in default first, then profiles in file order (global
-	 *  entries in global order, project-only names appended after). */
+	 *  entries in global alphabetical order, project-only names appended after in alphabetical order). */
 	list(): ResolvedProfile[] {
 		return [
 			this.resolve(DEFAULT_PROFILE_NAME)!,

package/src/project-trust.ts

@@ -80,7 +80,7 @@ export function resolveProjectTrust(input: ProjectTrustInput): boolean {
  *  native list doesn't know them: a committed catalog/state file would
  *  otherwise inject profile definitions (and instructions) unguarded. */
 function hasPiProfileProjectFiles(cwd: string): boolean {
-	return ["profiles.json", "pi-profile-state.json"].some((name) =>
+	return ["profiles", "pi-profile-state.json"].some((name) =>
 		existsSync(path.join(cwd, ".pi", name)),
 	);
 }

package/src/switching/profile-crud.ts

@@ -16,7 +16,7 @@
 
 import path from "node:path";
 
-import { getGlobalProfilesPath } from "../workspace.ts";
+import { getGlobalProfilesDir } from "../workspace.ts";
 import { readTrustInputs } from "../launcher/initial-profile.ts";
 import { CatalogError, DEFAULT_PROFILE_NAME, type ProfileDefinition } from "../profile-catalog.ts";
 import { ProfileCatalogStore } from "../profile-catalog-store.ts";
@@ -31,12 +31,9 @@ export function catalogStore(
 	scope: CatalogScope,
 ): ProfileCatalogStore {
 	if (scope === "global") {
-		return new ProfileCatalogStore(
-			getGlobalProfilesPath(),
-			path.join(input.realAgentDir, "profiles.json")
-		);
+		return new ProfileCatalogStore(getGlobalProfilesDir());
 	}
-	return new ProfileCatalogStore(path.join(input.cwd, ".pi", "profiles.json"));
+	return new ProfileCatalogStore(path.join(input.cwd, ".pi", "profiles"));
 }
 
 async function requireScope(input: { realAgentDir: string; cwd: string }, scope: CatalogScope): Promise<void> {

package/src/workspace.ts

@@ -3,7 +3,7 @@
  *
  * Rooted at `~/.pi-profile-switch` (or `PI_PROFILE_SWITCH_DIR` override).
  * Contains:
- * - `profiles.json`: global profile definitions catalog
+ * - `profiles/`: global profile definitions catalog
  * - `instances/`: instance runtime directories for forked pi processes
  */
 
@@ -19,21 +19,8 @@ export function getProfileSwitchDir(): string {
 	return path.join(homedir(), ".pi-profile-switch");
 }
 
-export function getGlobalProfilesPath(): string {
-	return path.join(getProfileSwitchDir(), "profiles.json");
-}
-
-export function resolveGlobalProfilesPath(agentDir: string): string {
-	const preferred = getGlobalProfilesPath();
-	if (existsSync(preferred)) {
-		return preferred;
-	}
-	// Fallback for legacy ~/.pi/agent/profiles.json
-	const fallback = path.join(agentDir, "profiles.json");
-	if (existsSync(fallback)) {
-		return fallback;
-	}
-	return preferred;
+export function getGlobalProfilesDir(): string {
+	return path.join(getProfileSwitchDir(), "profiles");
 }
 
 export function getInstancesRootDir(): string {

package/examples/profiles.json

@@ -1,18 +0,0 @@
-{
-  "schemaVersion": 1,
-  "profiles": {
-    "ask": {
-      "label": "Ask & Discuss",
-      "description": "Read-only Q&A and code exploration; no file modifications or command execution",
-      "skills": [],
-      "extensions": [],
-      "tools": [
-        "read",
-        "grep",
-        "find",
-        "ls"
-      ],
-      "instructions": "You are in read-only discussion mode. Answer questions and explain code without modifying any files or running shell commands."
-    }
-  }
-}