pi-profile-switch 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile selects what the model sees and which capabilities the session uses — skills, MCP servers, tools, a model preset, and extra instructions — switchable in the same Pi process.
 
-Use a lean read-only profile for code review, a full-powered one for implementation, a minimal one for a quick question.
+A shipped `read-only` preset covers the read-and-report workflow; other workflows you write yourself — a profile can narrow the tool set, hide skills, pin a model, or add instructions.
 
 `pi-profile-switch` is a plain Pi package (ADR-0007). It installs like any other extension, leaves Pi's configuration directory untouched, and keeps sessions, packages, project trust, and every other installed extension native.
 
@@ -23,32 +23,17 @@ Requires [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (in
 pi
 
 # Use a profile for this run only (not saved)
-pi --profile review
+pi --profile read-only
 
 # The explicit native baseline
 pi --profile default
 ```
 
-Define profiles in `~/.pi/agent/profiles.json` (global) or `<project>/.pi/profiles.json` (project, trusted projects only):
-
-```json
-{
-  "schemaVersion": 2,
-  "profiles": {
-    "review": {
-      "label": "Code review",
-      "skills": ["code-review"],
-      "mcp": ["github"],
-      "tools": ["read", "grep", "find", "bash"],
-      "instructions": "Review only; do not modify files."
-    }
-  }
-}
-```
+Create profiles with `/profile create`, which writes `~/.pi/agent/profiles.json` (global) or `<project>/.pi/profiles.json` (project, trusted projects only). The wizard offers the shipped `read-only` preset — Pi's built-in tools only, no skills, MCP servers, or model assumed — or a blank definition.
 
-Profiles **reference** resources by name — they never copy them. Full schema with more examples: [`examples/profiles.json`](examples/profiles.json).
+A preset is a one-time copy into your catalog: it is not tracked, so a package update never changes a profile you already created. Profiles **reference** resources by name — they never copy them. [`examples/profiles.example.json`](examples/profiles.example.json) is a complete catalog with several profiles covering every field; replace its resource names with ones you own.
 
-Existing `schemaVersion: 1` catalogs keep working: the `extensions` field is reported once and ignored, because extensions now load natively in every profile.
+`schemaVersion` is 1 and is the only accepted value. A profile cannot select extensions: they load natively in every profile, so manage them with `pi install`.
 
 ## What a profile controls
 
@@ -57,7 +42,7 @@ Existing `schemaVersion: 1` catalogs keep working: the `extensions` field is rep
 | `instructions` | Text appended to the system prompt every turn |
 | `model` | Session-start model preset; an explicit `--model`/`--thinking` or a model recorded in the session wins |
 | `skills` | What the model sees in the prompt's skills list. Every installed skill stays loaded and callable by the user through `/skill:name` |
-| `mcp` | Runtime server allowlist published to `pi-mcp-adapter`; connection details stay in the adapter's own config |
+| `mcp` | Which MCP servers the session exposes: the profile's allowlist is written into the adapter's own config (`~/.pi/agent/mcp.json`), disabling every other server. Servers you keep in that file move to `mcp.user.json`; connection details stay in your config, never in the profile |
 | `tools` | Active tool set: declared names/globs become the active set; names that register later (MCP, extensions) are applied when they appear |
 
 Anything a profile does not declare keeps Pi's native behavior, and `default` declares nothing.
@@ -70,11 +55,13 @@ In the TUI, the `/profile` command family manages everything in-session:
 | --- | --- |
 | `/profile` | Interactive profile picker |
 | `/profile list` / `/profile status` | Show profiles / active profile details |
-| `/profile use <name>` | Switch instantly — same session, no reload |
+| `/profile use <name>` | Switch in place — same session; when the MCP selection changes, the runtime reloads automatically to re-apply it |
 | `/profile create\|edit\|delete\|duplicate` | Guided profile CRUD (TUI only) |
 | `/profile customize` / `/profile reset` | Narrow the active profile for this session only |
 | `/mcp enable\|disable <server>` | Toggle MCP servers in the active profile |
 
+While a non-`default` profile is active, the footer shows `profile: <name>`, with `*` appended when a session-only overlay is in effect. `default` shows no badge, so an unprofiled session keeps Pi's native footer.
+
 All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizards are TUI-only.
 
 ## Guarantees
@@ -82,24 +69,11 @@ All commands work in non-interactive modes (`--mode rpc|print|json`); CRUD wizar
 - **Reference, never copy** — profiles point at resources you already own and maintain.
 - **Pi-native** — the configuration directory is Pi's own, so sessions, extension config, packages, context files, and trust behave exactly as they do in plain Pi.
 - **Fail safe** — untrusted project directories are never read; a failed activation applies nothing and reports the cause.
-- **No reload** — switching re-applies runtime state in place; the next turn's prompt carries the new selection.
-
-## Migrating from the launcher
-
-```bash
-pi-profile review          # before
-pi --profile review        # after
-
-pi-profile review -- --mode rpc   # before
-pi --profile review --mode rpc    # after
-```
-
-`/profile reload` and the `/profile resource` commands are gone: skills are read on demand and catalogs are re-read on every use, so there is nothing to reload. Remove leftover `~/.pi/agent/pi-profile/runtime/` directories; the extension no longer creates them.
+- **No manual reload** — switching re-applies runtime state in place and the next turn's prompt carries the new selection. Only a change to the MCP selection rebuilds the runtime, automatically, in the same session.
 
 ## Docs
 
 - [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md) (Chinese)
-- JSON Schema: [`schemas/profiles.schema.json`](schemas/profiles.schema.json)
 
 ## License
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 [Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 选择模型看到什么、会话使用哪些能力——skills、MCP server、tools、预制模型和附加指令——并在同一 Pi 进程内即时切换。
 
-代码评审用精简的只读 profile，实现需求用全量 profile，临时提问用最小 profile。
+随包提供一个 `read-only` 预设覆盖「读代码 + 报告」的工作流；其余工作流由你自己定义——profile 可以收窄工具集、隐藏 skill、固定模型或附加指令。
 
 `pi-profile-switch` 是普通 Pi package（ADR-0007）：像其他扩展一样安装，不改动 Pi 的配置目录，session、packages、项目信任和其他扩展全部保持原生。
 
@@ -23,32 +23,17 @@ pi install npm:pi-profile-switch
 pi
 
 # 仅本次启动使用指定 profile（不保存）
-pi --profile review
+pi --profile read-only
 
 # 显式的原生基线
 pi --profile default
 ```
 
-在 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）中定义 profile：
-
-```json
-{
-  "schemaVersion": 2,
-  "profiles": {
-    "review": {
-      "label": "Code review",
-      "skills": ["code-review"],
-      "mcp": ["github"],
-      "tools": ["read", "grep", "find", "bash"],
-      "instructions": "Review only; do not modify files."
-    }
-  }
-}
-```
+用 `/profile create` 创建 profile，写入 `~/.pi/agent/profiles.json`（全局）或 `<项目>/.pi/profiles.json`（项目级，仅限已信任项目）。向导提供随包的 `read-only` 预设——只用 Pi 内建工具，不假设任何 skill、MCP server 或模型——也可以从空定义开始。
 
-Profile 只**引用**资源，从不复制资源。完整示例见 [`examples/profiles.json`](examples/profiles.json)。
+预设只被复制一次：它不被跟踪，包升级不会改动你已经创建的 profile。Profile 只**引用**资源，从不复制资源。[`examples/profiles.example.json`](examples/profiles.example.json) 是覆盖全部字段的完整 catalog，示例中的资源名请替换成你本机已有的名字。
 
-已有的 `schemaVersion: 1` catalog 继续可用：`extensions` 字段会被警告一次并忽略——extensions 现在在所有 profile 中原生加载。
+`schemaVersion` 为 1，也是唯一接受的值。Profile 不选择 extension：extensions 在所有 profile 中原生加载，请用 `pi install` 管理。
 
 ## Profile 控制的范围
 
@@ -57,7 +42,7 @@ Profile 只**引用**资源，从不复制资源。完整示例见 [`examples/pr
 | `instructions` | 每个 turn 追加到 system prompt 末尾 |
 | `model` | 会话启动的模型预设；显式 `--model`/`--thinking` 或 session 历史中记录的模型优先 |
 | `skills` | 模型在 prompt skills 列表中看到的内容；所有已安装 skill 仍保持加载，用户可用 `/skill:name` 手动调用 |
-| `mcp` | 发布给 `pi-mcp-adapter` 的运行时 server allowlist；连接参数仍由 adapter 自己管理 |
+| `mcp` | 本次会话暴露哪些 MCP server：白名单写入 adapter 自己的配置（`~/.pi/agent/mcp.json`），其余 server 一律标为 disabled。你原本放在该文件里的 server 会迁移到 `mcp.user.json`；连接参数只在你自己的配置里，从不进入 profile |
 | `tools` | 活动工具集：声明的名字/glob 成为活动集合；之后才注册的工具（MCP、扩展）在出现时补上 |
 
 未声明的字段保持 Pi 原生行为，`default` 什么都不声明。
@@ -70,11 +55,13 @@ Profile 只**引用**资源，从不复制资源。完整示例见 [`examples/pr
 | --- | --- |
 | `/profile` | 交互式选择 profile |
 | `/profile list` / `/profile status` | 列出 profile / 查看活动 profile 详情 |
-| `/profile use <name>` | 即时切换——同一 session，无 reload |
+| `/profile use <name>` | 原位切换——同一 session；当 MCP 选择发生变化时会自动 reload 以重新应用 |
 | `/profile create\|edit\|delete\|duplicate` | 向导式 profile 增删改（仅 TUI） |
 | `/profile customize` / `/profile reset` | 仅本次会话收窄活动 profile |
 | `/mcp enable\|disable <server>` | 在活动 profile 中开关 MCP server |
 
+活动 profile 不是 `default` 时，footer 显示 `profile: <name>`；本次会话的 overlay 生效时追加 `*`。`default` 不显示 badge，未使用 profile 的会话保持 Pi 原生 footer。
+
 非交互模式（`--mode rpc|print|json`）下命令同样生效；CRUD 向导仅 TUI 可用。
 
 ## 保证
@@ -82,24 +69,11 @@ Profile 只**引用**资源，从不复制资源。完整示例见 [`examples/pr
 - **引用而非复制**——profile 指向你自己拥有和维护的资源。
 - **Pi 原生**——配置目录就是 Pi 自己的目录，session、扩展配置、packages、context 文件和信任行为与原生 Pi 完全一致。
 - **失败安全**——未信任的项目目录从不读取；激活失败时不应用任何设置并报出原因。
-- **无 reload**——切换在原位重新应用运行时状态；下一个 turn 的 prompt 直接带上新选择。
-
-## 从 launcher 迁移
-
-```bash
-pi-profile review          # 旧
-pi --profile review        # 新
-
-pi-profile review -- --mode rpc   # 旧
-pi --profile review --mode rpc    # 新
-```
-
-`/profile reload` 与 `/profile resource` 命令已移除：skill 内容按需读取、catalog 每次使用重新读取，没有需要 reload 的缓存。删除遗留的 `~/.pi/agent/pi-profile/runtime/` 目录；新版本不再创建它们。
+- **无需手动 reload**——切换在原位重新应用运行时状态，下一个 turn 的 prompt 直接带上新选择；只有 MCP 选择变化时才会自动重建运行时（同一 session）
 
 ## 文档
 
 - [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)
-- JSON Schema：[`schemas/profiles.schema.json`](schemas/profiles.schema.json)
 
 ## 许可证
 

package/examples/profiles.example.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 1,
+  "profiles": {
+    "read-only": {
+      "label": "Read-only",
+      "description": "Read-only session; no skills or MCP servers assumed — add your own.",
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls"
+      ],
+      "instructions": "Read-only session: inspect and report; never create, edit, rename, or delete files.\nIf a change is needed, describe it in your reply instead of applying it.\nDo not run commands that modify state (installs, formatters, commits, pushes, network writes).\nPrefer an available skill or MCP tool when it fits the request; otherwise use the tools you have.\nGround claims in evidence: cite file:line and separate verified facts from inferences.\nReply in English."
+    },
+    "review": {
+      "label": "Code review",
+      "description": "Review a diff or a branch: read the change, report findings, modify nothing.",
+      "skills": [
+        "code-review",
+        "git-*"
+      ],
+      "mcp": [
+        "github"
+      ],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls",
+        "bash"
+      ],
+      "model": {
+        "provider": "anthropic",
+        "id": "claude-sonnet-4-5",
+        "thinkingLevel": "high"
+      },
+      "instructions": "Review only: read the change under review, then report findings with file:line evidence.\nNever edit tracked files, commit, or push; describe the required fix instead.\nSeparate verified behavior from suspected issues."
+    },
+    "plan": {
+      "label": "Plan",
+      "description": "Research a change and write the plan; no edits, no implementation.",
+      "skills": [],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls",
+        "bash"
+      ],
+      "instructions": "Planning session: research the code first, then write the plan in your reply.\nDo not create, edit, rename, or delete files."
+    },
+    "implement": {
+      "label": "Implement",
+      "description": "Full tool access for implementing a change end to end.",
+      "skills": [
+        "git-commit",
+        "test-*"
+      ],
+      "mcp": [
+        "github"
+      ],
+      "tools": [
+        "read",
+        "grep",
+        "find",
+        "ls",
+        "bash",
+        "edit",
+        "write"
+      ],
+      "instructions": "Implement the requested change: read before writing, keep the diff minimal.\nRun the tests that cover your change and report the exact commands."
+    }
+  }
+}

package/examples/profiles.json

@@ -1,38 +1,16 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 1,
   "profiles": {
-    "review": {
-      "label": "Code review",
-      "description": "Read-heavy review workflow",
-      "skills": [
-        "code-review",
-        "diagnosing-bugs"
-      ],
-      "mcp": [
-        "github"
-      ],
+    "read-only": {
+      "label": "Read-only",
+      "description": "Read-only session; no skills or MCP servers assumed — add your own.",
       "tools": [
         "read",
         "grep",
         "find",
-        "bash"
-      ],
-      "instructions": "Review only; do not modify files."
-    },
-    "impl": {
-      "label": "Implementation",
-      "skills": [
-        "tdd"
-      ],
-      "mcp": [
-        "github",
-        "linear"
+        "ls"
       ],
-      "model": {
-        "provider": "deepseek",
-        "id": "deepseek-v4-pro",
-        "thinkingLevel": "high"
-      }
+      "instructions": "Read-only session: inspect and report; never create, edit, rename, or delete files.\nIf a change is needed, describe it in your reply instead of applying it.\nDo not run commands that modify state (installs, formatters, commits, pushes, network writes).\nPrefer an available skill or MCP tool when it fits the request; otherwise use the tools you have.\nGround claims in evidence: cite file:line and separate verified facts from inferences.\nReply in English."
     }
   }
 }