pi-profile-switch 0.9.0 → 0.9.2

package/README.md

@@ -36,9 +36,9 @@ Profiles live in two directories, with one JSON file per profile:
 
 Create or change a profile by editing or creating a `<name>.json` file directly — schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json).
 
-You can also configure profiles conversationally: the package ships a **`profile-config`** skill (distributed to `<agentDir>/skills/profile-config/` on install) that guides the agent to clarify requirements, discover resources, and write or remove profile files. Profiles created with a `skills` list include `"profile-config"` by default (unless explicitly opted out or covered by a wildcard like `"*"`), keeping configuration available after switching. Details: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md).
+You can also configure profiles conversationally: the package ships a **`profile-config`** skill (distributed to `<agentDir>/skills/profile-config/` — best-effort on install, and guaranteed in place at every launcher startup) that guides the agent to clarify requirements, discover resources, and write or remove profile files. Profiles created with a `skills` list include `"profile-config"` by default (unless explicitly opted out or covered by a wildcard like `"*"`), keeping configuration available after switching. Details: [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md).
 
-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:
+pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`** profile (`ask.json`) — best-effort on install, and guaranteed in place at every launcher startup — read-only Q&A and code exploration. It assumes nothing about your setup; edit or delete it freely:
 
 ```json
 {
@@ -121,7 +121,7 @@ All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizar
 
 ## Docs
 
-- [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md) (Chinese)
+- [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md)
 - JSON Schemas: [`schemas/`](schemas/)
 
 ## License

package/README.zh-CN.md

@@ -18,7 +18,7 @@ npm install -g pi-profile-switch
 # 使用内建 default profile 启动（全量资源，等同原生 Pi）
 pi-profile
 
-# 使用安装时播种的只读 ask profile 启动
+# 使用 starter 只读 ask profile 启动
 pi-profile ask
 
 # -- 后面的参数原样传给 pi
@@ -36,9 +36,9 @@ profile 保存在两个目录中，每个 profile 对应一个独立 JSON 文件
 
 直接编辑或新建 `<name>.json` 即可创建或修改 profile——schema 见 [`schemas/profiles.schema.json`](schemas/profiles.schema.json)。
 
-你也可以通过对话让 agent 帮你配置：随包附带的 **`profile-config`** skill（安装时分发至 `<agentDir>/skills/profile-config/`）会指导 agent 澄清需求、发现资源并读写 profile 文件。按约定，生成声明了 `skills` 的 profile 时默认包含 `"profile-config"`（除非明确排除或已被 `*` 等 glob 覆盖），确保切换到新 profile 后仍可持续对话配置。详情见 [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)。
+你也可以通过对话让 agent 帮你配置：随包附带的 **`profile-config`** skill（安装时 best-effort 分发、launcher 启动时保证就位，位于 `<agentDir>/skills/profile-config/`）会指导 agent 澄清需求、发现资源并读写 profile 文件。按约定，生成声明了 `skills` 的 profile 时默认包含 `"profile-config"`（除非明确排除或已被 `*` 等 glob 覆盖），确保切换到新 profile 后仍可持续对话配置。详情见 [`skills/profile-config/SKILL.md`](skills/profile-config/SKILL.md)。
 
-安装时，pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
+pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** profile（`ask.json`）——安装时 best-effort、launcher 启动时保证就位——它是只读的问答与代码走读模式。它不假设你安装过任何插件，可随意修改或删除：
 
 ```json
 {

package/bin/pi-profile.ts

@@ -16,19 +16,29 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { ExtensionError } from "../src/extension-discovery.ts";
 import { parseLauncherArgs } from "../src/launcher/args.ts";
 import { UnknownProfileError, resolveInitialProfile } from "../src/launcher/initial-profile.ts";
+import { untrustedProjectDiagnostic } from "../src/launcher/untrusted-project-diagnostic.ts";
 import { sweepStaleInstances } from "../src/launcher/runtime-cleanup.ts";
 import { spawnPi } from "../src/launcher/spawn.ts";
 import { McpConfigError, MissingMcpAdapterError } from "../src/mcp-config.ts";
 import { CatalogError } from "../src/profile-catalog.ts";
 import { ActivationError } from "../src/profile-resolver.ts";
+import { ensureStarterAssets } from "../src/starter-assets.ts";
 import { generateRuntimeDir } from "../src/settings-generator.ts";
 
 try {
 	const args = parseLauncherArgs(process.argv.slice(2));
 	const agentDir = getAgentDir();
+	// Starter assets (seed profile + profile-config skill) are ensured before
+	// initial profile resolution so the seed is visible to this launch's
+	// resolution and /profile list. Best-effort: ensure failures never block
+	// the launch (same pattern as the sweep below).
+	const starterAssets = await ensureStarterAssets({ agentDir });
+	for (const warning of starterAssets.warnings) {
+		console.error(`pi-profile: warning: ${warning}`);
+	}
 	// Fails before spawning when the profile is unknown or cannot activate.
 	// --approve/--no-approve are consumed here as a one-run trust input.
-	const { plan, discovery, projectDir, warnings } = await resolveInitialProfile(args.profile, {
+	const { plan, discovery, projectDir, projectTrusted, warnings } = await resolveInitialProfile(args.profile, {
 		agentDir,
 		cwd: process.cwd(),
 		trustOverride: args.trustOverride,
@@ -36,6 +46,13 @@ try {
 	for (const warning of warnings) {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
+	// Untrusted-project notice: fires identically for every profile (default
+	// included) because it is driven by the trust determination, not by which
+	// profile branch resolution took. Startup continues either way.
+	const untrustedNotice = untrustedProjectDiagnostic(process.cwd(), projectTrusted);
+	if (untrustedNotice) {
+		console.error(`pi-profile: warning: ${untrustedNotice}`);
+	}
 	// Stale per-launch instance dirs (dead pid, or no pid past the grace
 	// window) are swept before this launch materializes its own. Unrecognized
 	// entries are dispositioned per content scan: kept + reported when they

package/bin/postinstall.js

@@ -1,9 +1,21 @@
 #!/usr/bin/env node
 /**
- * postinstall: seed the global catalog with the default starter profile,
- * and distribute the profile-config skill to the agent skills directory.
+ * postinstall: best-effort early seeding of the global catalog with the
+ * default starter profile, and distribution of the profile-config skill to
+ * the agent skills directory.
  *
  * Runs at package install time (`npm install pi-profile-switch` / `pi install`).
+ *
+ * Role: this hook is an early optimization, NOT the sole distribution
+ * channel. npm v12+ blocks dependency lifecycle scripts by default
+ * (allowScripts), so installs that skip this hook are covered by the
+ * launcher instead: `bin/pi-profile.ts` calls the runtime ensure
+ * (src/starter-assets.ts) on every launch, before resolving the initial
+ * profile. The authoritative behavior contract for both assets lives in
+ * openspec/specs/profile-catalog/spec.md ("Seeding the starter profile" and
+ * "Distributing the profile-config skill"); keep this script's rules in sync with
+ * src/starter-assets.ts, which is the single TS implementation.
+ *
  * Idempotent and conservative:
  * - Writes the shipped `examples/ask.json` starter profile to the
  *   profiles dir ONLY when no .json profile exists there yet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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/skills/profile-config/SKILL.md

@@ -1,67 +1,67 @@
 ---
 name: profile-config
-description: 指导创建、修改或删除 pi-profile-switch 的 profile。当用户想要创建、修改、配置或删除 profile 时触发。
+description: Guides the creation, modification, and deletion of pi-profile-switch profiles. Trigger when the user wants to create, modify, configure, or delete a profile.
 ---
 
 # profile-config
 
-本 skill 指导 agent 理解用户的模糊需求或明确指令，协助用户创建、修改或删除 `pi-profile-switch` 的 profile 文件。
+This skill guides the agent in understanding the user's vague requirements or explicit instructions, and assists in creating, modifying, or deleting `pi-profile-switch` profile files.
 
-> **声明**：本 skill 文件由 `pi-profile-switch` package 安装分发并在随包升级时自动覆写，请勿手动修改此文件。
+> **Notice**: This skill file is distributed by the `pi-profile-switch` package install and is automatically overwritten on package upgrades. Do not modify this file manually.
 
 ---
 
-## 1. 核心概念与约束
+## 1. Core concepts and constraints
 
-### 1.1 Profile 与 Catalog
-- **Profile**：命名的能力定义，引用 skills、extensions、MCP servers 与 tools，可选声明 model、thinking level 与 instructions。
-- **Catalog**：保存 profile 定义的 `profiles/` 目录。每个 profile 对应目录下的一个独立 JSON 文件：`<name>.json`。
-- **default profile**：由 Pi 提供，不可删除、不可编辑的 profile，加载 Pi 可发现的全部资源。**严禁**在任何 profiles 目录下创建 `default.json`。
+### 1.1 Profiles and catalogs
+- **Profile**: a named capability definition referencing skills, extensions, MCP servers, and tools, optionally declaring model, thinking level, and instructions.
+- **Catalog**: the `profiles/` directory holding profile definitions. Each profile corresponds to one standalone JSON file in the directory: `<name>.json`.
+- **default profile**: provided by Pi; cannot be deleted or edited; loads every resource Pi can discover. **Strictly forbidden** to create `default.json` in any profiles directory.
 
-### 1.2 名字字符集规范
-Profile 名字必须完全匹配正则：
+### 1.2 Name charset rules
+A profile name must fully match the regex:
 ```regex
 ^[A-Za-z0-9][A-Za-z0-9._-]*$
 ```
-- 必须以英文字母或数字开头。
-- 只允许英文字母、数字、点（`.`）、下划线（`_`）和连字符（`-`）。
-- 不允许包含空格、中文或特殊符号。
+- Must start with an ASCII letter or digit.
+- Only ASCII letters, digits, dots (`.`), underscores (`_`), and hyphens (`-`) are allowed.
+- Spaces, CJK characters, and special symbols are not allowed.
 
-### 1.3 作用域（Source scope）与存储落点
-Profile 文件存放在两个位置之一：
+### 1.3 Scopes (source scope) and storage locations
+Profile files live in one of two locations:
 
-| 作用域 | 路径 | 说明 |
+| Scope | Path | Notes |
 | --- | --- | --- |
-| **全局（global）** | `$PI_PROFILE_SWITCH_DIR/profiles/<name>.json`<br>（缺省为 `~/.pi-profile-switch/profiles/<name>.json`） | 对所有项目通用。若环境变量 `PI_PROFILE_SWITCH_DIR` 存在且非空，则以其下的 `profiles/` 目录为准。 |
-| **项目（project）** | `<projectDir>/.pi/profiles/<name>.json` | 仅在当前项目生效，且仅当项目已受信任时可用。 |
+| **Global** | `$PI_PROFILE_SWITCH_DIR/profiles/<name>.json`<br>(default `~/.pi-profile-switch/profiles/<name>.json`) | Applies to all projects. If the `PI_PROFILE_SWITCH_DIR` environment variable exists and is non-empty, the `profiles/` directory under it is authoritative. |
+| **Project** | `<projectDir>/.pi/profiles/<name>.json` | Effective only in the current project, and only when the project is trusted. |
 
-- **覆盖规则**：项目 scope 的同名 profile 会完整替换（replace）全局条目，**不会**与全局配置合并字段。
-- **项目信任门禁**：若当前项目未受信任，项目 scope 的 profile 无法解析，向项目 scope 写入也会失败。写入项目 scope 前若项目未受信任，必须提示用户在会话中执行 `/trust` 并重启 Pi。
+- **Override rule**: a same-named profile in project scope completely replaces the global entry; fields are **not** merged with the global configuration.
+- **Project trust gate**: if the current project is untrusted, profiles in project scope cannot resolve, and writes to project scope fail. Before writing to project scope while the project is untrusted, you must tell the user to run `/trust` in the session and restart Pi.
 
 ---
 
-## 2. Profile 文件格式与字段定义
+## 2. Profile file format and fields
 
-文件内容必须为格式化 JSON，**顶层即为裸定义对象**，严禁包裹 `schemaVersion`、`profiles` 或其他外层信封字段。
+The file content must be formatted JSON, with **the bare definition object at the top level** — strictly no `schemaVersion`, `profiles`, or other outer envelope fields.
 
-全部字段均为可选（optional）。未声明的字段保持原生 Pi 行为或当前状态，不产生任何副作用。
+All fields are optional. Undeclared fields keep native Pi behavior or current state and produce no side effects.
 
-### 字段详细语义
+### Field semantics
 
-| 字段 | 类型 | 语义与约束 |
+| Field | Type | Semantics and constraints |
 | --- | --- | --- |
-| `label` | `string` | 人类可读的显示名称（如 `"Code Review"`）。 |
-| `description` | `string` | Profile 的简要描述（如 `"Read-only review profile"`）。 |
-| `skills` | `string[]` | 引用的 skill 名称或 glob 列表。未声明时不收窄可用 skills。 |
-| `extensions` | `string[]` | 引用的 extension 标识或 glob 列表。未声明时不收窄可用 extensions。 |
-| `mcps` | `string[]` | 引用的 MCP server 名称或 glob 列表。未声明时不依赖 `pi-mcp-adapter`。 |
-| `tools` | `string[]` | 白名单工具名称或 glob 列表。未声明时不收窄工具，保持 Pi 原生工具集合。 |
-| `defaultProvider` | `string` | 默认模型提供商（如 `"anthropic"`、`"openai"`）。与 `defaultModel` 必须同时声明才生效。 |
-| `defaultModel` | `string` | 默认模型名称（如 `"claude-sonnet-4-5"`）。与 `defaultProvider` 必须同时声明才生效。 |
-| `defaultThinkingLevel` | `string` | 默认思考等级，可选值：`"off"`、`"minimal"`、`"low"`、`"medium"`、`"high"`、`"xhigh"`、`"max"`。仅在模型声明成立时生效。 |
-| `instructions` | `string` | 激活该 profile 时追加到系统提示词的指令文本。 |
-
-### 示例格式
+| `label` | `string` | Human-readable display name (e.g. `"Code Review"`). |
+| `description` | `string` | Short description of the profile (e.g. `"Read-only review profile"`). |
+| `skills` | `string[]` | Skill names or globs to reference. When undeclared, available skills are not narrowed. |
+| `extensions` | `string[]` | Extension identifiers or globs to reference. When undeclared, available extensions are not narrowed. |
+| `mcps` | `string[]` | MCP server names or globs to reference. When undeclared, there is no dependency on `pi-mcp-adapter`. |
+| `tools` | `string[]` | Whitelisted tool names or globs. When undeclared, tools are not narrowed and Pi's native tool set is kept. |
+| `defaultProvider` | `string` | Default model provider (e.g. `"anthropic"`, `"openai"`). Effective only when declared together with `defaultModel`. |
+| `defaultModel` | `string` | Default model name (e.g. `"claude-sonnet-4-5"`). Effective only when declared together with `defaultProvider`. |
+| `defaultThinkingLevel` | `string` | Default thinking level; allowed values: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`. Effective only when the model declaration holds. |
+| `instructions` | `string` | Instruction text appended to the system prompt when this profile is active. |
+
+### Example
 ```json
 {
   "label": "Review Mode",
@@ -86,82 +86,82 @@ Profile 文件存放在两个位置之一：
 
 ---
 
-## 3. 可引用资源发现指引
-
-当帮助用户配置 profile 时，可检查或参考以下位置发现用户当前已有的可用资源：
-
-1. **Skills**：
-   - 发现位置：`<agentDir>/skills/` 以及全局 `~/.agents/skills/`。
-   - 引用身份：Pi 的 skill 名称（即 skill 目录下的 `SKILL.md` frontmatter 中声明的 `name`，或目录名）。
-   - 支持 glob（如 `"git-*"`）。
-2. **Extensions**：
-   - 发现位置：`<agentDir>/settings.json` 中声明的已安装 packages、`<agentDir>/extensions/` 下的散装文件（`.ts` 或 `.js`）。
-   - 引用形式：
-     - 已安装包的包名或 source 别名。
-     - 多入口包的入口 ID：`<包名>:<相对路径>`。
-     - 散装文件 ID：相对扩展目录的路径去掉 `.ts`/`.js`（如 `sub/index.ts` 引用为 `sub`）。
-     - 绝对路径或 `~/` 路径。
-     - glob 匹配。
-3. **MCP Servers**：
-   - 发现位置：`pi-mcp-adapter` 识别的标准配置位置——全局侧 `~/.config/mcp/mcp.json`、`~/.agents/mcp.json`、`~/.agents/mcp/mcp.json`、`<agentDir>/mcp.json`；受信任项目另有 `<projectDir>/.mcp.json` 与 `<projectDir>/.pi/mcp.json`。
-   - 引用身份：上述配置文件中 `mcpServers` 对象下的 server 键名。
-   - 声明了 `mcps` 的 profile 需要同时确保 `pi-mcp-adapter` extension 处于可用状态。
-4. **Tools**：
-   - 引用身份：Pi 实时工具注册表中的工具名。
-   - 包括内建工具（`read`、`write`、`edit`、`bash` 等）、extension 贡献的工具、以及 MCP server 暴露的工具（代理工具 `mcp__<server>` 与直接工具 `<server>_<tool>`）。
-   - 支持 glob（如 `"mcp__*"`、`"github_*"`）。
-5. **项目级资源的收窄边界（重要）**：
-   - Profile 的资源选择（`skills`、`extensions`）**仅作用于用户级资源**（真实 agentDir 与 `~/.agents/skills`）。
-   - 项目级资源（如项目 `.pi/skills`、项目 `.pi/extensions`、上级 `.agents/skills`）的可见性由 Pi 项目信任判定决定：在受信任项目中，它们在**任何** profile 下都始终可见；在未受信任项目中均不可见。
-   - 因此，项目级资源的可见性**不随 profile 收窄**，无需也不指导在 profile 中声明项目级资源。
+## 3. Discovering referenceable resources
+
+When helping the user configure a profile, check or consult the following locations to discover the resources the user currently has:
+
+1. **Skills**:
+   - Discovery locations: `<agentDir>/skills/` and the global `~/.agents/skills/`.
+   - Reference identity: Pi's skill name (the `name` declared in the frontmatter of the skill directory's `SKILL.md`, or the directory name).
+   - Globs supported (e.g. `"git-*"`).
+2. **Extensions**:
+   - Discovery locations: installed packages declared in `<agentDir>/settings.json`, and loose files (`.ts` or `.js`) under `<agentDir>/extensions/`.
+   - Reference forms:
+     - An installed package's package name or source alias.
+     - Entry ID of a multi-entry package: `<package>:<relative path>`.
+     - Loose-file ID: the path relative to the extension directory minus the `.ts`/`.js` suffix (e.g. `sub/index.ts` is referenced as `sub`).
+     - Absolute paths or `~/` paths.
+     - Glob matching.
+3. **MCP servers**:
+   - Discovery locations: the standard configuration locations recognized by `pi-mcp-adapter` — on the global side `~/.config/mcp/mcp.json`, `~/.agents/mcp.json`, `~/.agents/mcp/mcp.json`, `<agentDir>/mcp.json`; trusted projects additionally have `<projectDir>/.mcp.json` and `<projectDir>/.pi/mcp.json`.
+   - Reference identity: the server key names under the `mcpServers` object in those configuration files.
+   - A profile declaring `mcps` must also ensure the `pi-mcp-adapter` extension is available.
+4. **Tools**:
+   - Reference identity: tool names in Pi's live tool registry.
+   - Includes built-in tools (`read`, `write`, `edit`, `bash`, etc.), extension-contributed tools, and tools exposed by MCP servers (the proxy tool `mcp__<server>` and direct tools `<server>_<tool>`).
+   - Globs supported (e.g. `"mcp__*"`, `"github_*"`).
+5. **Narrowing boundary of project-level resources (important)**:
+   - A profile's resource selection (`skills`, `extensions`) **applies only to user-level resources** (the real agentDir and `~/.agents/skills`).
+   - The visibility of project-level resources (project `.pi/skills`, project `.pi/extensions`, ancestor `.agents/skills`) is decided by Pi's project-trust determination: in a trusted project they are always visible under **any** profile; in an untrusted project they are never visible.
+   - Therefore project-level resource visibility **does not narrow with profiles** — there is no need, and no guidance, to declare project-level resources in a profile.
 
 ---
 
-## 4. 创作时的默认注入规则
+## 4. Default injection rule at authoring time
 
-当为用户创建或生成声明了 `skills` 的新 profile 时，必须遵守以下约定：
+When creating or generating a new profile that declares `skills` for the user, follow these conventions:
 
-1. **默认注入 `"profile-config"`**：
-   - 若生成的 profile 声明了 `skills` 数组，默认在 `skills` 列表中包含 `"profile-config"`，以保证切入该 profile 后用户仍可继续通过本 skill 配置 profile。
-   - **例外 1**：用户明确要求不包含 `"profile-config"` 时除外。
-   - **例外 2**：若 `skills` 列表中已包含具有覆盖性的 glob（例如 `"*"`），则无需重复显式添加 `"profile-config"`。
-2. **未声明 `skills` 时不动作**：
-   - 若 profile 未声明 `skills` 字段，表示不收窄 skills，全部 skill（包括 `profile-config`）天然可用，因此绝对不要主动添加 `skills` 字段。
+1. **Inject `"profile-config"` by default**:
+   - If the generated profile declares a `skills` array, include `"profile-config"` in the `skills` list by default, so that after switching into the profile the user can still configure profiles through this skill.
+   - **Exception 1**: the user explicitly asks not to include `"profile-config"`.
+   - **Exception 2**: the `skills` list already contains a covering glob (e.g. `"*"`), so there is no need to add `"profile-config"` explicitly again.
+2. **Do nothing when `skills` is undeclared**:
+   - If the profile does not declare the `skills` field, skills are not narrowed and every skill (including `profile-config`) is naturally available — never proactively add a `skills` field in that case.
 
 ---
 
-## 5. 交互与执行流程
-
-### 5.1 创建（Create）
-1. **需求澄清**：根据用户自然语言描述（如「帮我配一个用于安全审计的只读 profile」），明确：
-   - 目标名称（校验符合 `^[A-Za-z0-9][A-Za-z0-9._-]*$`，且非 `default`）。
-   - 目标 scope（全局还是项目级）。
-   - 需要收窄的工具、skills、extensions、MCP servers 或特定模型设定。
-2. **资源与环境核对**：根据上述规则构造合法 JSON 定义，应用创作时默认注入规则。
-3. **写入文件**：
-   - 全局路径：`$PI_PROFILE_SWITCH_DIR/profiles/<name>.json`（默认 `~/.pi-profile-switch/profiles/<name>.json`）。
-   - 项目路径：`<projectDir>/.pi/profiles/<name>.json`。
-   - 确保目录存在，写入格式化的 JSON。
-4. **提示用户生效**：告知用户可通过 `/profile reload` 或 `/profile use <name>` 立即使用新 profile。
-
-### 5.2 修改（Edit）
-1. 读取目标 profile 文件已有内容。
-2. 根据用户要求调整对应字段，保持其余字段完整。
-3. 校验并写回格式化 JSON。
-4. 提示用户执行 `/profile reload`。
-
-### 5.3 删除（Delete）
-1. 确认要删除的 profile 存在于指定 scope。
-2. 严禁尝试删除 `default` profile。
-3. 删除对应的 `<name>.json` 文件。若当前正在使用该 profile，提醒用户先切换到其他 profile（如 `/profile use default`）。
+## 5. Interaction and execution flows
+
+### 5.1 Create
+1. **Clarify requirements**: from the user's natural-language description (e.g. "set up a read-only profile for security auditing"), determine:
+   - The target name (validate against `^[A-Za-z0-9][A-Za-z0-9._-]*$`, and not `default`).
+   - The target scope (global or project).
+   - The tools, skills, extensions, MCP servers, or specific model settings to narrow.
+2. **Check resources and environment**: construct a legal JSON definition per the rules above, applying the default injection rule.
+3. **Write the file**:
+   - Global path: `$PI_PROFILE_SWITCH_DIR/profiles/<name>.json` (default `~/.pi-profile-switch/profiles/<name>.json`).
+   - Project path: `<projectDir>/.pi/profiles/<name>.json`.
+   - Ensure the directory exists and write formatted JSON.
+4. **Tell the user how to take effect**: the new profile is immediately usable via `/profile reload` or `/profile use <name>`.
+
+### 5.2 Edit
+1. Read the existing content of the target profile file.
+2. Adjust the requested fields per the user's requirements, keeping all other fields intact.
+3. Validate and write back formatted JSON.
+4. Tell the user to run `/profile reload`.
+
+### 5.3 Delete
+1. Confirm the profile to delete exists in the specified scope.
+2. Never attempt to delete the `default` profile.
+3. Delete the corresponding `<name>.json` file. If the profile is currently in use, remind the user to switch to another profile first (e.g. `/profile use default`).
 
 ---
 
-## 6. 边界与退化处理
+## 6. Boundaries and degradation
 
-1. **只读 / 无 `write` 工具环境**：
-   - 如果当前会话处于收窄工具的 profile 中（例如没有 `write` 工具的只读模式）：
-   - 退化为在回复中输出完整的格式化 JSON 内容与建议保存的文件绝对路径，建议用户手动保存或切换至具备文件写入能力的 profile（如 `/profile use default`）后再行保存。
-2. **未受信任项目**：
-   - 如果需要写入项目 scope（`<projectDir>/.pi/profiles/`），而当前项目尚未受信任：
-   - 必须向用户说明项目未受信任无法生效，提示用户执行 `/trust` 并重启 Pi，或改将 profile 保存至全局 scope。
+1. **Read-only / no `write` tool environments**:
+   - If the current session is in a profile with narrowed tools (e.g. a read-only mode without the `write` tool):
+   - Degrade to outputting the complete formatted JSON content in the reply along with the suggested absolute file path, and suggest the user save it manually or switch to a profile with file-write capability (e.g. `/profile use default`) before saving.
+2. **Untrusted projects**:
+   - If a write to project scope (`<projectDir>/.pi/profiles/`) is needed while the current project is not yet trusted:
+   - You must explain to the user that an untrusted project cannot take effect, and suggest running `/trust` and restarting Pi, or saving the profile to global scope instead.

package/src/launcher/initial-profile.ts

@@ -55,6 +55,10 @@ export interface InitialProfile {
 	discovery?: LauncherDiscovery;
 	/** The trusted project directory, when trusted. */
 	projectDir?: string;
+	/** The launcher's project-trust determination. Drives the untrusted-
+	 *  project diagnostic; not inferable from projectDir, which the dangling
+	 *  saved-profile fallback returns unset while the project is trusted. */
+	projectTrusted: boolean;
 	/** Non-fatal notices for the user (e.g. a dangling restored profile that
 	 *  fell back to default). The launcher prints them. */
 	warnings: string[];
@@ -116,7 +120,7 @@ export async function resolveInitialProfile(
 			throw new UnknownProfileError(selected);
 		}
 		warnings.push(`saved profile "${selected}" no longer exists; starting the default profile`);
-		return { plan: defaultPlan(), warnings };
+		return { plan: defaultPlan(), projectTrusted, warnings };
 	}
 	if (profile.source === "builtin") {
 		// The default profile is normally unfiltered. With an overlay it becomes
@@ -131,7 +135,7 @@ export async function resolveInitialProfile(
 				(overlay.disabledMcps?.length ?? 0) > 0 ||
 				overlay.tools !== undefined);
 		if (!narrowed) {
-			return { plan: defaultPlan(), warnings };
+			return { plan: defaultPlan(), projectTrusted, warnings };
 		}
 		if ((overlay.disabledMcps?.length ?? 0) > 0) {
 			throw new ActivationError(
@@ -151,7 +155,7 @@ export async function resolveInitialProfile(
 			overlay,
 		});
 		warnings.push(...discovery.extensions.warnings(), ...unmatchedWarnings(plan));
-		return { plan, discovery, projectDir, warnings };
+		return { plan, discovery, projectDir, projectTrusted, warnings };
 	}
 
 	const discovery = await discoverLauncherResources({ ...context, projectTrusted });
@@ -172,5 +176,5 @@ export async function resolveInitialProfile(
 		// silently do nothing or leak through unfiltered.
 		throw new MissingMcpAdapterError(plan.profile);
 	}
-	return { plan, discovery, projectDir, warnings };
+	return { plan, discovery, projectDir, projectTrusted, warnings };
 }

package/src/launcher/untrusted-project-diagnostic.ts

@@ -0,0 +1,84 @@
+/**
+ * Untrusted-project launch diagnostic.
+ *
+ * After the launcher's project-trust determination judges the project
+ * untrusted, the project catalog, project runtime state, project MCP
+ * configuration, and Pi's own project resources are skipped silently
+ * (ADR-0011). This module names the skipped content and how to authorize it
+ * so the result of the determination is observable. Detection mirrors the
+ * trust-requiring set: pi-profile's project files (see project-trust.ts) and
+ * Pi's project resources (see pi-coding-agent's trust manager).
+ */
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { hasTrustRequiringProjectResources } from "@earendil-works/pi-coding-agent";
+
+import { PI_PROFILE_PROJECT_FILES } from "../project-trust.ts";
+
+/** The project's MCP configuration files (the project sources recognized by
+ *  mcp-config.ts). */
+const PROJECT_MCP_CONFIGS = [".mcp.json", path.join(".pi", "mcp.json")] as const;
+
+/** Pi's trust-requiring `.pi` entries (mirrors
+ *  TRUST_REQUIRING_PROJECT_CONFIG_RESOURCES in pi-coding-agent's trust
+ *  manager, which doesn't export the list). */
+const PI_PROJECT_RESOURCES = [
+	"settings.json",
+	"extensions",
+	"skills",
+	"prompts",
+	"themes",
+	"SYSTEM.md",
+	"APPEND_SYSTEM.md",
+] as const;
+
+/** Relative paths of project content skipped while the project is
+ *  untrusted; empty when the project contains nothing trust-requiring. */
+function skippedProjectContent(cwd: string): string[] {
+	const skipped: string[] = [];
+	for (const name of PI_PROFILE_PROJECT_FILES) {
+		if (existsSync(path.join(cwd, ".pi", name))) {
+			skipped.push(path.join(".pi", name));
+		}
+	}
+	for (const mcpConfig of PROJECT_MCP_CONFIGS) {
+		if (existsSync(path.join(cwd, mcpConfig))) {
+			skipped.push(mcpConfig);
+		}
+	}
+	for (const resource of PI_PROJECT_RESOURCES) {
+		if (existsSync(path.join(cwd, ".pi", resource))) {
+			skipped.push(path.join(".pi", resource));
+		}
+	}
+	if (skipped.length === 0 && hasTrustRequiringProjectResources(cwd)) {
+		// Pi gated something this list doesn't name: a cwd-local
+		// .agents/skills, or one in a parent directory.
+		skipped.push(
+			existsSync(path.join(cwd, ".agents", "skills"))
+				? path.join(".agents", "skills")
+				: "Pi project resources in a parent directory",
+		);
+	}
+	return skipped;
+}
+
+/** The untrusted-project diagnostic for this launch, or undefined when there
+ *  is nothing to report (trusted project, or untrusted with no
+ *  trust-requiring content). The launcher prints the result to stderr. */
+export function untrustedProjectDiagnostic(cwd: string, projectTrusted: boolean): string | undefined {
+	if (projectTrusted) {
+		return undefined;
+	}
+	const skipped = skippedProjectContent(cwd);
+	if (skipped.length === 0) {
+		return undefined;
+	}
+	return (
+		`project is untrusted; skipped project content is invisible to this launch: ${skipped.join(", ")}. ` +
+		'To authorize it, run "/trust" in Pi to persist the decision (effective on the next launch), ' +
+		'or relaunch with "-- --approve" to grant one-shot trust for this launch.'
+	);
+}

package/src/project-trust.ts

@@ -76,11 +76,14 @@ export function resolveProjectTrust(input: ProjectTrustInput): boolean {
 	return input.userDefaultProjectTrust === "always";
 }
 
-/** pi-profile's own project files are trust-requiring even though Pi's
- *  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", "pi-profile-state.json"].some((name) =>
-		existsSync(path.join(cwd, ".pi", name)),
-	);
+/** pi-profile's own project files, relative to the project's `.pi`
+ *  directory. They are trust-requiring even though Pi's native list doesn't
+ *  know them: a committed catalog/state file would otherwise inject profile
+ *  definitions (and instructions) unguarded. Exported so the launcher's
+ *  untrusted-project diagnostic names exactly the files the trust gate
+ *  skips — the two must never drift apart. */
+export const PI_PROFILE_PROJECT_FILES = ["profiles", "pi-profile-state.json"] as const;
+
+export function hasPiProfileProjectFiles(cwd: string): boolean {
+	return PI_PROFILE_PROJECT_FILES.some((name) => existsSync(path.join(cwd, ".pi", name)));
 }

package/src/starter-assets.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime ensure of starter assets: seeds the starter profile into global
+ * profiles/ if no profile exists yet, and distributes/syncs the profile-config
+ * skill into the user's agent skills directory.
+ *
+ * Idempotent, safe against concurrent launches, and downgrades IO errors
+ * to warnings without throwing.
+ */
+
+import { constants } from "node:fs";
+import { copyFile, mkdir, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { getGlobalProfilesDir } from "./workspace.ts";
+
+export interface StarterAssetFileResult {
+	/** Absolute path of the target file */
+	path: string;
+	/** Whether this call performed a write */
+	written: boolean;
+}
+
+export interface StarterAssetsResult {
+	profile: StarterAssetFileResult;
+	skill: StarterAssetFileResult;
+	/** Human-readable degradation warnings; empty means all succeeded or no-op */
+	warnings: string[];
+}
+
+export interface EnsureStarterAssetsOptions {
+	/** Defaults to getGlobalProfilesDir(); injected by tests */
+	globalProfilesDir?: string;
+	/** Defaults to Pi's getAgentDir(); injected by tests */
+	agentDir?: string;
+	/** Defaults to locating the package root from import.meta.url; injected by tests */
+	packageRoot?: string;
+}
+
+async function hasAnyJsonProfiles(dir: string): Promise<boolean> {
+	try {
+		const entries = await readdir(dir);
+		return entries.some((name) => name.endsWith(".json"));
+	} catch (error: unknown) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") {
+			return false;
+		}
+		throw error;
+	}
+}
+
+export async function ensureStarterAssets(options?: EnsureStarterAssetsOptions): Promise<StarterAssetsResult> {
+	const defaultPackageRoot = fileURLToPath(new URL("..", import.meta.url));
+	const packageRoot = options?.packageRoot ? path.resolve(options.packageRoot) : defaultPackageRoot;
+	const globalProfiles = options?.globalProfilesDir ? path.resolve(options.globalProfilesDir) : getGlobalProfilesDir();
+	const agent = options?.agentDir ? path.resolve(options.agentDir) : getAgentDir();
+
+	const profileTemplate = path.join(packageRoot, "examples", "ask.json");
+	const targetProfilePath = path.join(globalProfiles, "ask.json");
+
+	const skillTemplate = path.join(packageRoot, "skills", "profile-config", "SKILL.md");
+	const targetSkillDir = path.join(agent, "skills", "profile-config");
+	const targetSkillPath = path.join(targetSkillDir, "SKILL.md");
+
+	const warnings: string[] = [];
+	const profileResult: StarterAssetFileResult = {
+		path: targetProfilePath,
+		written: false,
+	};
+	const skillResult: StarterAssetFileResult = {
+		path: targetSkillPath,
+		written: false,
+	};
+
+	// 1. Starter profile seeding
+	try {
+		const hasJson = await hasAnyJsonProfiles(globalProfiles);
+		if (!hasJson) {
+			await mkdir(globalProfiles, { recursive: true });
+			try {
+				await copyFile(profileTemplate, targetProfilePath, constants.COPYFILE_EXCL);
+				profileResult.written = true;
+			} catch (error: unknown) {
+				const err = error as NodeJS.ErrnoException;
+				if (err.code === "EEXIST") {
+					// Lost a create race (concurrent launch); winner stands
+					profileResult.written = false;
+				} else {
+					throw error;
+				}
+			}
+		}
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		warnings.push(`could not seed starter profile: ${message}`);
+	}
+
+	// 2. Profile-config skill distribution & sync
+	try {
+		const templateContent = await readFile(skillTemplate, "utf8");
+		let needsWrite = true;
+		try {
+			const existingContent = await readFile(targetSkillPath, "utf8");
+			if (existingContent === templateContent) {
+				needsWrite = false;
+			}
+		} catch (error: unknown) {
+			const err = error as NodeJS.ErrnoException;
+			if (err.code !== "ENOENT") {
+				throw error;
+			}
+		}
+
+		if (needsWrite) {
+			await mkdir(targetSkillDir, { recursive: true });
+			await copyFile(skillTemplate, targetSkillPath);
+			skillResult.written = true;
+		}
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		warnings.push(`could not distribute profile-config skill: ${message}`);
+	}
+
+	return {
+		profile: profileResult,
+		skill: skillResult,
+		warnings,
+	};
+}