@zihanw/pi-forge 0.4.0 → 0.5.0

package/docs/reference/public-api.md

@@ -1,28 +1,75 @@
 # Public API policy
 
-pi-forge is pre-1.0. This document separates supported integration surfaces from experimental 0.4 work and compatibility paths that should not become permanent dependencies.
+[Documentation](../README.md)
 
-## Stable
+pi-forge is pre-1.0. This document defines the intentional integration surfaces of the 0.5.0 line.
 
-- The package default export is the Pi extension entry point declared by `pi.extensions`.
-- Package-root macro and slot registration APIs (`registerMacro`, `registerSlot`, their registry readers, render contexts, and declarative definition types) are supported for trusted reusable extensions.
-- `ForgeExtensionApi` and related registration types are supported for trusted project-local forge extensions.
+## The three intentional entry points
 
-Stable means changes should preserve source compatibility within the documented supported release range unless a changelog entry explicitly announces a breaking release.
+`check-package` enforces this allowlist; nothing else is importable from the package.
 
-## Experimental
+### 1. Package root: extension factory
 
-- Agent-profile repository, resolution, application, preview, provenance, and drift APIs are 0.4 experimental surfaces.
-- The runner-neutral subagent contract and host-resolution helpers are 0.4 experimental surfaces. Backend registration, sealing, lifecycle, and the fresh-process backends moved to `@zihanw/pi-subagent-runtime`; Forge consumes them through its public runtime API.
-- New subagent integrations should import from `@zihanw/pi-forge/subagent`. The package root continues to re-export the current subagent names through 0.4 for compatibility.
+```ts
+import piForge from "@zihanw/pi-forge";
+```
 
-Experimental APIs are typed, tested, and documented, but may change in later releases as adapter and parent-integration experience exposes missing semantics. Changes should still be deliberate and recorded.
+The default export is the Pi extension entry point declared by `pi.extensions`. Most users install the package and never import it directly.
 
-## Internal compatibility paths
+### 2. Package root: trusted extension API
 
-- `@zihanw/pi-forge/src/*` subpath exports exist for compatibility with earlier source-shaped imports. They resolve to compiled `dist` modules and are not a promise that every implementation module is a permanent public API.
-- Browser-only `@zihanw/pi-forge/src/web-editor/client/*` implementation paths are explicitly blocked. The editor is distributed only through its generated embedded assets; these authored modules have never been a runtime integration surface.
-- The package root re-exports `@zihanw/pi-forge/subagent` contract names directly from the focused contract modules. The former `src/subagent-contract.ts` compatibility barrel and the `scripts/subagent-sdk-spike*` diagnostic harness were removed in the 0.4 cleanup.
-- Physical `src/` files are not included in the npm tarball. Runtime installation and legacy `@zihanw/pi-forge/src/*` aliases use compiled `dist` modules; source inspection or modification requires a repository clone.
+```ts
+import { registerMacro, registerSlot } from "@zihanw/pi-forge";
+import type {
+  ForgeExtensionApi,
+  ForgeExtensionRegister,
+  PromptEnvironment,
+  PromptEnvironmentValue,
+  PromptExtensionArgumentDefinition,
+  PromptExtensionOptionDefinition,
+  PromptExtensionOptionsSchema,
+  PromptExtensionOptionType,
+  PromptMacroDefinition,
+  PromptMacroRenderContext,
+  PromptMacroRenderer,
+  PromptRegistryEntry,
+  PromptRenderHelpers,
+  PromptSlotDefinition,
+  PromptSlotRenderContext,
+  PromptSlotRenderer,
+} from "@zihanw/pi-forge";
+```
 
-Before removing the compatibility subpaths, check known consumers, announce the change, and provide supported package entry points for legitimate integrations.
+Supported for trusted reusable and project-local extensions. The contract (pure renderers, declared dependencies, immutable `PromptEnvironment`, bounded output) is specified in the [0.5.0 architecture plan](../design/architecture-0.5.md#extension-port-contract-050) and the [custom macros and slots guide](../guides/custom-macros-and-slots.md).
+
+### 3. `@zihanw/pi-forge/subagent`: versioned host port
+
+```ts
+import {
+  ForgeHost, ForgeHostClient, ForgeHostPortError,
+  FORGE_HOST_CHANNEL, FORGE_HOST_PORT_VERSION, FORGE_HOST_PORT_OPERATIONS,
+  validateListProfilesRequest, validateListProfilesResponse,
+  validateResolveProfileRequest, validateResolveProfileResponse,
+  validatePrepareRequest, validatePrepareResponse,
+  canonicalSubagentJson, subagentFingerprint,
+  subagentSourceProfileFingerprint, subagentPromptStackFingerprint,
+} from "@zihanw/pi-forge/subagent";
+```
+
+The experimental host port over the Pi event bus: discovery, profile listing/snapshot, and host-owned prompt preparation with mandatory lifecycle semantics (correlation IDs, payload validation, bounded timeouts, host generation, duplicate-host failure, disposal/`unavailable`, listener cleanup). The wire DTOs and validators are self-contained Forge data contracts; the main package has no dependency on `@zihanw/pi-subagent-runtime`. The canonical `sha256:v1` fingerprint helpers are Forge-owned and byte-compatible with the runtime's canonical JSON.
+
+The optional `@zihanw/pi-forge-subagents` package consumes this port and owns subagent execution and configuration.
+
+## Compatibility policy
+
+- **Stable** surfaces (root factory, macro/slot registration) preserve source compatibility within the documented release range unless a changelog entry announces a breaking release.
+- **Experimental** surfaces (the `/subagent` host port) are typed, tested, and documented, but may change deliberately as integration experience exposes missing semantics.
+- Everything not listed above is internal and may change without notice. In particular: no `src/*` subpath aliases exist, `./examples/*` is not an import surface (examples ship as browsable files), and removed 0.4 surfaces (the execution contract re-exports, loader/profile/catalog helpers) now live either nowhere or in `@zihanw/pi-forge-subagents`.
+
+## Removed in 0.5.0
+
+- All `@zihanw/pi-forge/src/*` compatibility aliases and the `./examples/*` subpath export.
+- Root re-exports of loader, agent-profile, profile-service, catalog, resource-identity, render-helper values, the `forge-v1` engine, and registry readers.
+- Root and `/subagent` re-exports of the 0.4 execution contract (`AgentRequest`, `createAgentExecutionPlan`, `validateAgentRequest`, `negotiateSubagentTools`, `resolveSubagentHostProfile`, `prepareSubagentHostPlan`, and friends). The execution contract now belongs to `@zihanw/pi-forge-subagents`.
+
+See the [0.5 migration guide](../guides/migrating-to-0.5.md) for the complete breaking-change list.

package/docs/reference/stack-schema.md

@@ -6,7 +6,7 @@ Use [the default Pi mirror](../../examples/default-prompt-stack.json) as the com
 
 ## Top-level shape
 
-A stack has a unique `id`, schema/type identity, optional display metadata and auto-activation, a system `mode`, ordered `items`, and optional defaults, variables, context, resource policy, regex, and source metadata.
+A stack has a unique `id`, schema/type identity, optional display metadata and auto-activation, a system `mode`, ordered `items`, and optional defaults, parameters (schema v2) or legacy variables, context, resource policy, regex, and source metadata.
 
 Unknown/advanced metadata is preserved by raw editing, but behavior-changing fields are shape-checked and invalid values are not silently normalized into active behavior.
 
@@ -21,7 +21,7 @@ Block:
   "name": "Readable label",
   "enabled": true,
   "role": "system",
-  "content": "Your text here. Use {{macros}} for dynamic content."
+  "content": "Your text here. Use {{ parameters.role }} / {{ runtime.lastUserMessage }} for dynamic content."
 }
 ```
 
@@ -65,7 +65,7 @@ Item IDs must be unique. Unsupported slots and missing required custom registrat
 }
 ```
 
-- Set `includeLastUserMessage: false` when a later block reinserts `{{lastUserMessage}}`.
+- Set `includeLastUserMessage: false` when a later block reinserts `{{ runtime.lastUserMessage }}`.
 - `stripAssistantThinking` removes prior thinking blocks but preserves visible assistant text, tool calls, and results. It does not change the live loop or stored transcript.
 - `includeSummaries: false` excludes branch/compaction summaries.
 - `roles` keeps only selected roles.
@@ -76,7 +76,7 @@ When filtering would separate a tool call from its result, pi-forge removes dang
 
 ## Structured slots
 
-`tools`, `tool-guidelines`, `skills`, `project-context`, and `variables` support `"format": "plain"`; the default is XML-style structure. Date slots support `includeTime: true`.
+`tools`, `tool-guidelines`, `skills`, and `project-context` support `"format": "plain"`; the default is XML-style structure. Date slots support `includeTime: true`.
 
 See [macros and slots](macros-and-slots.md) for names and options.
 
@@ -101,13 +101,14 @@ Tool policy changes Pi's active tool list, is reasserted before input/turns, and
 
 Skill policy filters only pi-forge-rendered skill slots. It does not disable explicit invocation and is not a capability boundary. `append`/`prepend` may retain Pi's unfiltered base skill text, so validation warns.
 
-## Variables
+## Parameters and schema v2
 
-Top-level static variables are JSON values:
+Schema v2 stacks store immutable static values in `parameters` (JSON-compatible):
 
 ```json
 {
-  "variables": {
+  "schemaVersion": 2,
+  "parameters": {
     "char": "Konata",
     "user": "User",
     "style": { "tone": "concise" }
@@ -115,7 +116,11 @@ Top-level static variables are JSON values:
 }
 ```
 
-Turn and session values are changed through macros. See [macro reference](macros-and-slots.md).
+Parameters resolve through `{{ parameters.<name> }}` templates and are available
+to trusted custom macros/slots. Unversioned and v1 stacks continue to read the
+legacy `variables` field (string values) and support bare `{{name}}` fallback.
+A stack must not mix `parameters` and `variables` across schema versions. See
+[macro reference](macros-and-slots.md).
 
 ## Regex transforms
 
@@ -164,4 +169,4 @@ Outgoing rules change future model input. To destructively change a completed as
 
 > `finalize` runs at `message_end`, after raw output may have streamed. It replaces the stored assistant message, so the original output is not preserved.
 
-`effect: "display"` and `"both"` validate with warnings but are ignored until true display transforms exist. Runtime diagnostics report match and changed-segment counts.
+`effect: "outgoing"` and `"finalize"` are the only valid effects; `"display"` and `"both"` are rejected during validation. Runtime diagnostics report match and changed-segment counts.

package/docs/reference/subagent-host-port.md

@@ -0,0 +1,49 @@
+# Subagent host port contract
+
+[Documentation](../README.md)
+
+Status: experimental, versioned (`FORGE_HOST_PORT_VERSION = 1`). The `/subagent` entry point is the main package's only subagent surface: a transport-neutral host port over data-only messages. Subagent execution, approval, and configuration live in the optional [`@zihanw/pi-forge-subagents`](https://github.com/MacroSony/pi-forge-subagents) package, which consumes this port and never imports main-package internals.
+
+## Ownership boundary
+
+- **Main package owns:** prompt-stack/agent-profile storage and validation (repositories + codecs), the immutable `ForgeWorkspace` snapshot, profile/stack resolution, host-owned prompt compilation, and tool filtering through stack policy.
+- **Optional package owns:** delegation authorization (`subagents.json`), the execution contract (request, preflight, plan, response, validators), backend preflight and sealing via `@zihanw/pi-subagent-runtime`, approval UX, and execution.
+- **Never crosses the port:** live contexts, internal registries, execution/runtime material (access workspace model, limits, `resultProjection`, `parent`, `remoteEgressConsent`, a base system prompt). The client sends only a profile selector, the task, prompt-compilation access facts (`level`/`network`/`allowProcess`), and backend facts (model, thinking level, tool catalog).
+
+## Transport and lifecycle
+
+`ForgeHostTransport` is a minimal `{ emit(channel, data), on(channel, handler) }` interface; the production wiring is `pi.events`. Wire messages are plain JSON-compatible data validated recursively (exact nested fields, typed enums, plain objects only, unknown fields rejected) at both boundaries.
+
+Mandatory lifecycle rules:
+
+1. Clients subscribe before announcing or discovering, and use bounded timeouts.
+2. A duplicate live host fails explicitly (`host.duplicate`).
+3. `request`/`reply` messages carry `hostId` + `generation`; stale-generation and wrong-host requests are rejected server-side, mismatched replies ignored client-side.
+4. Disposal sends `unavailable` and invalidates connections; all transient and persistent listeners are cleaned up.
+5. The host can only start after the first workspace snapshot exists, so an advertised host implies a loaded workspace. Reload honors project trust: untrusted workspaces expose global resources only.
+
+## Operations
+
+### Discovery
+
+`ForgeHostClient.discover()` / `ForgeHostSession` in the optional package announce on `FORGE_HOST_CHANNEL` and wait for `available` with capabilities.
+
+### `listProfiles`
+
+Request: `{}`. Response: `{ profiles: ForgeProfileSummary[] }` — each with `profileId`, `scope`, optional `name`/`description`/`autoActivate`, `model`, `thinkingLevel`, `promptStack`, `usable`, and load diagnostics. Read-only; no resolution side effects.
+
+### `resolveProfile`
+
+Request: `{ profile: string }` — a scoped selector (`reviewer`, `project:reviewer`, `global:reviewer`). Response: `{ snapshot }` — the immutable host-owned profile snapshot artifact: resolved profile and prompt stack JSON, prompt dependency list, and `sha256:v1` content fingerprints (`profileFingerprint`, `promptStackFingerprint`) computed with Forge-owned canonical helpers byte-compatible with the runtime's canonical JSON. The optional package re-validates and re-fingerprints the snapshot before binding it into execution plans.
+
+### `prepare`
+
+Request: `{ profile, task: { text }, access: ForgePromptAccessFacts, backend: ForgeBackendFacts }`. The workspace resolves the profile and stack from its snapshot, filters the client tool catalog through stack tool policy and the access facts, and compiles through the same compilation context as runtime and preview. Response: `{ profileId, model, thinkingLevel, systemPrompt, messages, effectiveToolIds, effectiveToolNames, diagnostics, profileSnapshot, preparedAt }`. `messages` ends with the protected delegated task (`protectedTask: true`, `source: "delegated-task"`); stack-compiled messages carry `source: "prompt-stack"`. The base system prompt is host-owned and intentionally empty for delegated subagents — the prompt stack composes the system prompt.
+
+## Fingerprints
+
+`canonicalSubagentJson`, `subagentFingerprint`, `subagentSourceProfileFingerprint`, `subagentPromptStackFingerprint`, and `SUBAGENT_FINGERPRINT_PREFIX` are Forge-owned and vendored in the main package; golden vectors pin byte compatibility with the runtime's canonical serialization. Conversation and execution fingerprints are never host-computed — they are issued by `@zihanw/pi-subagent-runtime` during plan sealing in the optional package.
+
+## Errors
+
+`ForgeHostPortError` carries `code: "timeout" | "duplicate" | "unavailable" | "protocol" | "invalid"`. Operation-level failures return `{ ok: false, error }` results rather than throwing across the bus.

package/docs/zh-CN/README.md

@@ -11,12 +11,12 @@
 ## 指南
 
 - [Web 编辑器](guides/web-editor.md)
+- [迁移到 0.5](guides/migrating-to-0.5.md)
 - [实验性前台 delegation](guides/delegation.md)：启用前请先阅读安全边界。
 - [Prompt stack 使用场景（英文）](../guides/use-cases.md)
 
-SillyTavern 导入、自定义 macros/slots 和调试的完整说明目前以英文版为准：
+自定义 macros/slots 和调试的完整说明目前以英文版为准：
 
-- [SillyTavern import](../guides/sillytavern-import.md)
 - [Custom macros and slots](../guides/custom-macros-and-slots.md)
 - [Prompt and payload debugging](../guides/debugging.md)
 
@@ -27,7 +27,7 @@ SillyTavern 导入、自定义 macros/slots 和调试的完整说明目前以英
 - [Macros 与 slots（英文）](../reference/macros-and-slots.md)
 - [配置（英文）](../reference/configuration.md)
 - [Public API（英文）](../reference/public-api.md)
-- [实验性 subagent adapter（英文）](../reference/subagent-adapter.md)
+- [实验性 subagent host port（英文）](../reference/subagent-host-port.md)
 
 ## 开发与设计
 

package/docs/zh-CN/concepts/agent-profiles.md

@@ -2,7 +2,7 @@
 
 [中文文档](../README.md) · [English](../../concepts/agent-profiles.md)
 
-Agent profile 是项目级、带 schema version 的预设，只引用一个精确模型、思考等级和 prompt stack。
+Agent profile 是项目级或用户全局、带 schema version 的预设，只引用一个精确模型、思考等级和 prompt stack。项目 profile 位于 `.pi/forge/agent-profiles/`，全局 profile 位于 `~/.pi/forge/agent-profiles/`。命令接受 `reviewer`、`project:reviewer` 和 `global:reviewer`；未限定 ID 优先解析项目 profile，项目 profile 会遮蔽同 ID 全局 profile。
 
 ```json
 {
@@ -23,6 +23,8 @@ Agent profile 是项目级、带 schema version 的预设，只引用一个精
 
 `promptStack` 可以是 `null`。Profile v1 不保存生成参数、工具、skills、backend 或 runner policy；不支持字段会直接报错。工具/skill 策略只属于引用的 stack。
 
+`promptStack` 引用相对 profile 自身 scope 解析：项目 profile 用裸 ID 引用项目 stack，也可用 `global:<id>` 显式引用全局 stack；全局 profile 只能引用全局 stack，`project:<id>` 会被拒绝。
+
 ## 应用
 
 ```text
@@ -41,4 +43,4 @@ Agent profile 是项目级、带 schema version 的预设，只引用一个精
 
 `/profile status` 会把 profile 源定义变化和当前模型/思考等级/stack drift 分开显示。Provenance 只用于 branch 状态报告；reload、resume、tree navigation 和 compaction 不会重新应用 profile。
 
-普通 profile 默认不能委派。Delegation 使用独立的可信项目授权；删除 profile 也会清除其授权，防止以后同 ID profile 继承权限。启用前见[前台 delegation](../guides/delegation.md)。
+普通 profile 默认不能委派。Delegation 授权由可选包 `@zihanw/pi-forge-subagents` 通过专用文件持有：可信项目 `.pi/forge/subagents.json` 只授权 `project:<id>`，用户全局 `~/.pi/forge/subagents.json` 只授权 `global:<id>`，并可按 profile 覆盖 backend/timeout；同 ID 的全局和项目 profile 永不互相继承授权。主包不读取任何 subagent 配置，删除 profile 也不会改动 `subagents.json`。启用前见[前台 delegation](../guides/delegation.md)。

package/docs/zh-CN/concepts/prompt-stacks.md

@@ -2,7 +2,7 @@
 
 [中文文档](../README.md) · [English](../../concepts/prompt-stacks.md)
 
-Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 **block** 和动态 **slot** 组成。
+Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 **block** 和动态 **slot** 组成。Stack 可以放在项目 `.pi/forge/prompt-stacks/`，也可以放在用户全局 `~/.pi/forge/prompt-stacks/`。命令接受 `reviewer`、`project:reviewer` 和 `global:reviewer`；未限定 ID 优先解析项目 stack，项目 stack 会遮蔽同 ID 全局 stack。重复 ID 只在同一 scope 内算错误。
 
 ## 编译模型
 
@@ -11,7 +11,7 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 1. 按 JSON 顺序排列启用的 block/slot。
 2. 构建 system 内容，并使用 `replace`、`append` 或 `prepend` 模式。
 3. 在可移动 `chat-history` 周围插入 user/assistant 消息。
-4. 展开内置、变量和可信自定义宏。
+4. 用 forge-v1 编译 `runtime.*` / `parameters.*` / `extensions.*` 模板。
 5. 对 Pi 执行工具策略，并过滤 pi-forge 渲染的 skills。
 6. 应用 history/compiled outgoing regex。
 7. 可选地在消息完成后应用破坏性的 finalize regex。
@@ -21,7 +21,7 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 1. 长期 system 规则。
 2. 工具和项目上下文。
 3. `includeLastUserMessage: false` 的 `chat-history`。
-4. 包含 `{{lastUserMessage}}` 的最终 user block。
+4. 包含 `{{ runtime.lastUserMessage }}` 的最终 user block。
 
 这样既保留旧上下文，又只在最后明确出现一次当前请求。History 还可以过滤 summary/role、去掉旧工具消息、移除 assistant thinking，并限制消息数或字符数。
 
@@ -29,12 +29,14 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 
 工具 `allow`/`deny` 会修改 Pi active tools，并在 tool call 时再次检查。Skill policy 只过滤 pi-forge 渲染给模型的列表；它不能阻止明确调用，也不是安全边界。若必须控制模型可见 skill 列表，请使用 `replace`，因为 Pi 的基础 prompt 可能已经在 `append`/`prepend` 内容之前列出 skills。
 
-## Session 行为
+## Scope 与自动启用
 
-- `default.json` 默认自动启用。
+- 只有显式设置 `"autoActivate": true` 的 stack 参与自动启用；文件名（包括 `default.json`）没有特殊作用。
+- 项目 stack 优先于全局 stack；项目 scope 存在候选时，即使项目候选无效或冲突也会 fail closed，不会回退到全局 stack。
+- 同 ID 项目 stack 会遮蔽全局 stack，包括无效 shadow 或显式 opt-out。
 - `/preset use none` 会记录 session branch 的 opt-out。
-- Active stack 和 session variables 会跟随 Pi session tree branch。
+- Active stack 选择会跟随 Pi session tree branch。
 - 恢复的 branch 状态优先于新 session 自动启用。
 - 自动启用的 agent profile 优先于独立 stack autoload。
 
-完整字段见英文 [stack schema](../../reference/stack-schema.md)，macro/slot 见[参考](../../reference/macros-and-slots.md)。
+完整字段见英文 [stack schema](../../reference/stack-schema.md)（schema v2 使用 `parameters`），模板语法见[参考](../../reference/macros-and-slots.md)。

package/docs/zh-CN/getting-started.md

@@ -10,7 +10,7 @@ pi-forge 需要 Node.js 22.19 或更高版本，并作为 Pi extension 运行：
 pi install npm:@zihanw/pi-forge
 ```
 
-安装或更新后请重启 Pi。Pi host 会提供运行时 SDK；精确 package 版本只用于可复现的开发测试。项目被 Pi 信任后，pi-forge 才会加载项目 stack、profile 和 config。
+安装或更新后请重启 Pi。Pi host 会提供运行时 SDK；精确 package 版本只用于可复现的开发测试。用户全局 stack/profile 始终可以浏览；项目 stack、profile 和 config 只在 Pi 信任项目后加载和写入。
 
 ## 第一个 stack
 
@@ -28,7 +28,7 @@ cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 /preset use default
 ```
 
-如果没有恢复的 session 选择或明确 opt-out，`default.json` 会自动启用。设置 `"autoActivate": false` 可以关闭此行为。
+示例中的 `default.json` 带 `"autoActivate": true`，因此没有恢复的 session 选择或明确 opt-out 时会自动启用。设置 `"autoActivate": false` 可以关闭此行为；文件名本身没有特殊作用。
 
 ## 编辑和检查
 
@@ -36,7 +36,7 @@ cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 /preset ui
 ```
 
-编辑器运行在带 token 的本地 `127.0.0.1` URL，支持结构化/原始 JSON 编辑、排序、校验、完整预览、策略、regex、导入导出、fork 和 profile 管理。
+编辑器运行在带 token 的本地 `127.0.0.1` URL，支持结构化/原始 JSON 编辑、排序、校验、完整预览、策略、regex、导入导出、fork 和 profile 管理。工具栏的 scope 下拉（默认 `project`）决定新建、fork 和导入 stack 写入项目 `.pi/forge/prompt-stacks` 还是用户全局 `~/.pi/forge/prompt-stacks`。
 
 命令行也可以检查：
 
@@ -56,7 +56,7 @@ cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 /profile use reviewer
 ```
 
-Profile 保存在 `.pi/forge/agent-profiles/*.json`。应用是经过 preflight 的一次性操作；之后的手动设置不会被自动覆盖。
+Profile 默认保存在 `.pi/forge/agent-profiles/*.json`。`/profile save global:reviewer` 会写入用户全局 `~/.pi/forge/agent-profiles`。应用是经过 preflight 的一次性操作；之后的手动设置不会被自动覆盖。
 
 ## 存储与迁移
 
@@ -64,12 +64,15 @@ Profile 保存在 `.pi/forge/agent-profiles/*.json`。应用是经过 preflight
 |---|---|
 | `.pi/forge/prompt-stacks/` | 项目 prompt stacks |
 | `.pi/forge/agent-profiles/` | 项目 agent profiles |
-| `.pi/forge/config.json` | 项目配置和 delegation 授权 |
+| `.pi/forge/config.json` | 项目配置（`webEditor.*`） |
 | `.pi/forge/extensions/` | 可信项目 macro/slot 代码 |
-| `~/.pi/forge/config.json` | 用户默认配置 |
+| `~/.pi/forge/prompt-stacks/` | 用户全局 prompt stacks |
+| `~/.pi/forge/agent-profiles/` | 用户全局 agent profiles |
+| `~/.pi/forge/config.json` | 用户默认配置（`webEditor.*`） |
+| `.pi/forge/subagents.json` / `~/.pi/forge/subagents.json` | 由可选包 `@zihanw/pi-forge-subagents` 持有的 delegation 授权配置 |
 | `~/.pi/forge/extensions/` | 可信用户 macro/slot 代码 |
 
-旧的 `.pi/prompt-stacks/*.json` 仍可读取；新 stack 会写到 `.pi/forge/prompt-stacks`。安全迁移方式：
+旧的 `.pi/prompt-stacks/*.json` 仍可读取；命令创建的 stack 会写到 `.pi/forge/prompt-stacks`，使用 Web 编辑器的 `global` scope 下拉可创建到用户全局 `~/.pi/forge/prompt-stacks`。安全迁移方式：
 
 ```text
 /preset migrate-stacks --dry-run

package/docs/zh-CN/guides/delegation.md

@@ -4,28 +4,26 @@
 
 > **实验性：** 此 API 和 backend 可能独立于稳定的 prompt stack/profile 功能发生变化。
 
-pi-forge 可以把明确授权的 agent profile 作为独立、干净、一次性的 Pi 进程执行。它在前台运行，并向父对话返回有界报告。
+可选包 `@zihanw/pi-forge-subagents` 可以把明确授权的 agent profile 作为独立、干净、一次性的 Pi 进程执行。它在前台运行，并向父对话返回有界报告。
 
 ## 启用 profile
 
-Profile 默认不能委派。请在可信项目的 `.pi/forge/config.json` 中逐个启用，或使用 `/preset ui` 的 delegation 卡片：
+Profile 默认不能委派。请在可信项目的 `.pi/forge/subagents.json` 中逐个启用项目 profile，在用户全局 `~/.pi/forge/subagents.json` 中逐个启用全局 profile；`.pi/forge/config.json.subagents` 仅作为只读兼容来源：
 
 ```json
 {
-  "subagents": {
-    "backend": "pi-subprocess-readonly",
-    "timeoutMs": 60000,
-    "profiles": {
-      "reviewer": {
-        "enabled": true,
-        "timeoutMs": 300000
-      }
+  "backend": "pi-subprocess-readonly",
+  "timeoutMs": 60000,
+  "profiles": {
+    "reviewer": {
+      "enabled": true,
+      "timeoutMs": 300000
     }
   }
 }
 ```
 
-Profile 授权只允许出现在项目配置，因为 profile 本身也是项目资源。全局 `~/.pi/forge/config.json` 可以设置通用 backend/timeout；全局 `profiles` 会警告并被忽略。未启用或未列出的 ID 不会被 discovery 返回，即使猜中 ID 也会被拒绝。
+授权跟随 profile scope：项目 `subagents.json` 的 `profiles.<id>` 只授权 `project:<id>`，全局 `subagents.json` 的 `profiles.<id>` 只授权 `global:<id>`。同 ID 的全局和项目 profile 不会互相继承 enable/backend/timeout。未启用或未列出的 ID 不会被 discovery 返回，即使猜中 ID 也会被拒绝。
 
 ## Plan 与运行
 
@@ -35,7 +33,7 @@ Profile 授权只允许出现在项目配置，因为 profile 本身也是项目
 /forge-agent run reviewer 检查这个 API 设计。
 ```
 
-`plan` 会解析 profile/stack、编译并校验不可变的实际 provider-bound 计划，然后在不联系 provider 的情况下丢弃。
+`plan` 会解析 profile/stack、编译并校验不可变的实际 provider-bound 计划，然后在不联系 provider 的情况下丢弃。Profile selector 在所有入口使用同一语法：`reviewer`（项目优先）、`project:reviewer` 或 `global:reviewer`。同 ID 冲突时，项目 profile 保持简写 selector，全局 profile 仍通过 `global:<id>` 调用。
 
 父模型使用无数据外发的 `forge_subagent_profiles` 做 discovery，再用 `forge_subagent` 执行。限制严格的父 stack 必须允许这两个工具名。
 
@@ -55,7 +53,7 @@ Profile 授权只允许出现在项目配置，因为 profile 本身也是项目
 }
 ```
 
-它只影响 `forge_subagent`；`/forge-agent run` 仍需要交互审批。格式错误或不可信项目会 fail closed。请把此 config 当作授权文件：除非所有可调用父 agent 都可以无需再次询问就把编译 prompt 和可读文件发给 provider，否则不要启用或提交此设置。
+它只影响 `forge_subagent`；`/forge-agent run` 仍需要交互审批。格式错误或不可信项目会 fail closed。请把此 `subagents.json` 当作授权文件：除非所有可调用父 agent 都可以无需再次询问就把编译 prompt 和可读文件发给 provider，否则不要启用或提交此设置。
 
 ## Child 边界
 

package/docs/zh-CN/guides/migrating-to-0.5.md

@@ -0,0 +1,92 @@
+# 迁移到 pi-forge 0.5
+
+[中文文档](../README.md) · [English](../../guides/migrating-to-0.5.md)
+
+0.5.0 是一个破坏性的清理版本。本页是全部变更的迁移说明。
+
+## 被移除的内容
+
+- SillyTavern 导入器（`/preset import-silly`）及其报告、指南、示例和测试。升级前请先用 pi-forge 0.4 转换 SillyTavern preset。
+- 可变 turn/session 变量、变量修改 macro、`pi-forge-variable-state` session 条目和 `variables` slot。
+- 正则的 `display` 与 `both` 效果；保留 `outgoing` 和 `finalize`。
+- 主包中的 subagent 执行功能（移至可选包，见下文 Lane 3/4）。
+
+## 模板语法变更
+
+Prompt 文本现在使用封闭的 `forge-v1` 语法编译。
+
+| 0.4 写法 | 0.5 forge-v1 |
+|---|---|
+| `{{name}}`（静态） | `{{ parameters.name }}` |
+| `{{lastUserMessage}}` | `{{ runtime.lastUserMessage }}` |
+| `{{date}}` / `{{time}}` / `{{cwd}}` | `{{ runtime.date }}` / `{{ runtime.time }}` / `{{ runtime.cwd }}` |
+| `{{tools}}` | `{{ runtime.selectedToolsText }}` |
+| `{{upper::x}}` | `{{ x \| upper }}` |
+| `{{iftools::bash::A::B}}` | `{% if runtime.tool.bash %}A{% else %}B{% endif %}` |
+| 自定义 `{{myMacro}}` | `{{ extensions.myMacro }}` |
+
+未知路径、未知 filter、解析错误、循环和输出超限都是编译错误；失败的块会被省略，而不是把原始模板文本重新注入。
+
+## Schema v2
+
+Schema v2 的 stack 把不可变静态值存入 `parameters`（JSON 兼容），取代旧的纯字符串 `variables` 字段：
+
+```json
+{
+  "schemaVersion": 2,
+  "parameters": { "char": "Konata" }
+}
+```
+
+未标注版本 / v1 的 stack 仍通过旧的 `variables` 读取器加载。
+
+## 运行迁移工具
+
+一个以诊断为先的机械脚本可转换已保存的 stack 文件：
+
+```bash
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --dry-run
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --write
+```
+
+它会把 `variables` 改名为 `parameters`、映射 runtime/parameter 路径并转换简单的 filter 管道。无法机械转换的写法会被报告；只有不存在这类写法时才会写入文件。仍含旧 `variables` 字段的 schema v2 文件不会被改动，仅给出警告。
+
+## Lane 2：带 scope 的全局 profile 与 prompt stack
+
+- 用户全局资源现在位于 `~/.pi/forge/prompt-stacks` 和 `~/.pi/forge/agent-profiles`，与项目存储并存。Profile 和 stack 选择器支持显式 scope：`project:<id>`、`global:<id>`，裸 ID 优先解析项目资源。
+- 同 ID 的项目资源会遮蔽对应的全局资源；全局 stack 不能引用项目资源（反之亦然）——引用在被引用资源的 scope 内解析。
+- 未信任的项目一律拒绝：只加载全局资源，所有变更路由被拒绝，并且当 session 可能仍活跃时 `session_shutdown` 不再销毁已信任的工作区（空闲工作区一小时后被清扫；host 独立停止）。
+- Web 编辑器新增 scope 下拉，可向任一存储创建 stack/profile，并通过显式 `global:<id>` 路由执行全局变更。
+
+## Lane 3：subagent 包拆分
+
+Subagent 执行功能从主包移入可选包 `@zihanw/pi-forge-subagents`（要求 `@zihanw/pi-forge@^0.5.0`）。如需保留前台 delegation，请单独安装该包。
+
+- **命令：** `/subagents` 和 `/subagent-run` 已从主包移除。可选包注册 `/forge-agent backends|plan|run`。
+- **模型工具：** `forge_subagent_profiles` 和 `forge_subagent` 由可选包注册。
+- **配置：** `subagents.*` 从 `.pi/forge/config.json` 移入专用的 `.pi/forge/subagents.json`（可信项目）和 `~/.pi/forge/subagents.json`（用户默认）。可选包会把旧的 `config.json.subagents` 段落作为只读回退读取并发出警告；它永远不会写入旧位置。把配置值复制到 `subagents.json` 即可消除警告。
+- **Web 编辑器：** delegation 卡片已从主编辑器移除；请直接编辑 `subagents.json`。
+- **架构：** 主包的 prompt 编译器不再携带 subagent 假设，`ForgeWorkspace` 是资源状态和编译上下文的唯一持有者。
+
+## Lane 4：Forge 原生 host 契约与公开 surface
+
+- 主包不再依赖 `@zihanw/pi-subagent-runtime`，也不再导出 0.4 执行契约。该契约（`AgentRequest`、`createAgentExecutionPlan`、`validateAgentRequest`、`negotiateSubagentTools`、preflight/plan/response 校验器等）现在位于 `@zihanw/pi-forge-subagents` 内部，供其自身 runtime 接线使用；两个包都不把它作为第三方可用的公开 surface。
+- `@zihanw/pi-forge/subagent` 现在只导出带版本的 host port：wire DTO 与校验器、`ForgeHostTransport`、`ForgeHost`/`ForgeHostClient`、生命周期常量，以及 Forge 持有的规范指纹辅助函数。`resolveSubagentHostProfile` / `prepareSubagentHostPlan` 已被 host port 的 `resolveProfile` 和 `prepare` 操作取代。
+- 包根只导出默认扩展工厂、`registerMacro`/`registerSlot` 及其契约类型。其余根导出（loader、agent-profile、profile-service、catalog、resource-identity、render-helper 值、`forge-v1` 引擎、registry 读取器）已全部移除。
+- 所有 `@zihanw/pi-forge/src/*` 子路径别名和 `./examples/*` 导出均已移除；`check-package` 会拒绝它们。
+
+### 导入迁移表
+
+| 0.4 导入 | 0.5 替代 |
+|---|---|
+| `@zihanw/pi-forge`（默认导出、`registerMacro`、`registerSlot`） | 不变 |
+| `@zihanw/pi-forge/subagent` host-port 名称（`ForgeHost*`、校验器、指纹） | 不变 |
+| `@zihanw/pi-forge/subagent` 执行契约（`AgentRequest`、`createAgentExecutionPlan` 等） | 已内置于 `@zihanw/pi-forge-subagents`；无公开替代 |
+| `@zihanw/pi-forge/subagent` 的 `resolveSubagentHostProfile` / `prepareSubagentHostPlan` | 通过 `ForgeHostClient` 使用 host-port 操作 |
+| `@zihanw/pi-forge/src/*` 别名 | 已移除；无替代（内部实现） |
+| 根部的 loader/profile/catalog/engine 再导出 | 已移除；无替代（内部实现） |
+
+## 兼容性说明
+
+- Host port 的 wire 结构在 `FORGE_HOST_PORT_VERSION = 1` 内只做增量扩展；未知操作会以普通的 `{ ok: false, error }` 结果拒绝（`"Unknown Forge host operation: …"`），而不是抛出异常。可选包必须把任何操作失败视为该请求的终态。
+- 主包内置的指纹辅助函数由黄金向量锁定，与 `@zihanw/pi-subagent-runtime` 的规范序列化保持字节兼容；计划封存（plan sealing）仍只发生在可选包中。

package/docs/zh-CN/guides/web-editor.md

@@ -10,7 +10,7 @@
 
 `/preset ui restart` 会替换 server，`/preset ui stop` 会关闭它。
 
-编辑器绑定在带 session token 的可用 `127.0.0.1` 端口；多个项目可以同时运行。可以在 `.pi/forge/config.json` 中设置偏好端口：
+编辑器绑定在带 session token 的可用 `127.0.0.1` 端口；多个项目可以同时运行。读取、预览和 payload 检查在合适范围内可用；写入要求 Pi 信任项目，并且文件被限制在 pi-forge 的 stack/profile 存储内。可以在 `.pi/forge/config.json` 中设置偏好端口：
 
 ```json
 {
@@ -29,17 +29,17 @@
 - 拖拽排序、启用/禁用、校验和完整编译预览；
 - 工具/skill 搜索、精确名称 chips 和通配符策略；
 - variables、context 和 regex 规则；
-- 原生 pi-forge 与 SillyTavern JSON 导入；
+- 原生 pi-forge JSON 导入；
 - 导出、fork、删除和 payload 捕获。
 
-已有 ID 在编辑时不可修改；需要新 ID 时使用 **Fork**，避免破坏 profile 引用和当前选择。保存、导入、fork 和删除后会重新加载当前 Pi session。
+已有 ID 在编辑时不可修改；需要新 ID 时使用 **Fork**，避免破坏 profile 引用和当前选择。工具栏的 scope 下拉（默认 `project`）决定新建、导入和 fork 的写入位置：选择 `global` 写入用户全局 `~/.pi/forge/prompt-stacks`，选择 `project` 写入项目 `.pi/forge/prompt-stacks`。列表会为全局 stack 显示 `global` badge；保存和删除通过 `global:<id>` 路由精确作用于全局文件。保存、导入、fork 和删除后会重新加载当前 Pi session。
 
 ## Agent profile 工作区
 
-列表显示 profile ID、名称、模型、思考等级、stack、校验状态、auto-activation、last-applied provenance 和 delegation 状态。
+列表显示 profile ID、名称、模型、思考等级、stack、校验状态、auto-activation 和 last-applied provenance。每个 profile 都带 `project` / `global` scope badge；同 ID 的 shadow 对会显示 `shadows global:<id>` 或 `shadowed by project:<id>`。
 
-可信项目可以新建、编辑、校验、保存、一次性应用和删除 profile。Model 选项来自 Pi registry，thinking 选项反映模型支持，stack 选项来自同一个 repository。编辑器会拒绝第二个 auto-activation profile。
+可信项目通过 **New profile** 旁的 scope 下拉（默认 `project`）选择目标 scope：选择 `global` 写入用户全局 `~/.pi/forge/agent-profiles`，选择 `project` 写入项目 `.pi/forge/agent-profiles`。全局 profile 可通过显式 `global:<id>` 路由编辑、校验、保存、一次性应用和删除；未限定路由始终只作用于项目资源。编辑全局 profile 时，stack 下拉只显示全局 stack。Model 选项来自 Pi registry，thinking 选项反映模型支持，stack 选项来自同一个 repository。编辑器会拒绝同 scope 内第二个 auto-activation profile。
 
-Delegation 卡片只修改项目级 profile 的 enable/backend/timeout。切换 profile、刷新、删除或离开页面时，未保存的 delegation 字段会得到保护。通用默认值和 `allowAgentInvocationWithoutApproval` 只能在 config 文件中设置。
+## Delegation
 
-启用前请阅读[前台 delegation](delegation.md)。
+Delegation 配置不在主编辑器中。可选包 `@zihanw/pi-forge-subagents` 持有专用的 `.pi/forge/subagents.json` 和 `~/.pi/forge/subagents.json` 文件。启用 profile 前请阅读[前台 delegation](delegation.md)。

package/docs/zh-CN/reference/commands.md

@@ -2,6 +2,8 @@
 
 [中文文档](../README.md) · [English](../../reference/commands.md)
 
+方括号参数可选。写项目文件的命令要求项目已被信任。未限定的 `<id>` 使用项目优先的有效查找；需要精确选择时使用 `project:<id>` 或 `global:<id>`。
+
 ## Prompt stack
 
 | 命令 | 行为 |
@@ -21,7 +23,6 @@
 | 命令 | 行为 |
 |---|---|
 | `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | 把旧 stack 复制到 `.pi/forge/prompt-stacks` |
-| `/preset import-silly <path> [character_id] [--dry-run] [--overwrite]` | 转换 SillyTavern preset 并生成报告 |
 
 覆盖或删除之前请先使用 `--dry-run`。
 
@@ -31,7 +32,7 @@
 |---|---|
 | `/profile list` | 列出 profile 和解析诊断 |
 | `/profile use <id>` | preflight 并一次性应用 |
-| `/profile save <id> [--overwrite]` | 捕获当前模型、thinking 和 stack |
+| `/profile save <id\|global:id> [--overwrite]` | 捕获当前模型、thinking 和 stack；`global:<id>` 写入用户全局目录 |
 | `/profile status` | 比较当前 runtime 和 last-applied provenance |
 | `/profile preview <id>` | 不应用地解析模型/auth/thinking/stack/tools |
 | `/profile validate [id]` | 校验一个或全部 profile |
@@ -40,13 +41,15 @@
 
 ## 实验性 delegation
 
+以下命令由可选包 `@zihanw/pi-forge-subagents` 提供。
+
 | 命令 | 行为 |
 |---|---|
 | `/forge-agent backends` | 列出 backend、capabilities 和默认值 |
 | `/forge-agent plan <profile> [--backend <id>] <task>` | 准备、显示并丢弃计划，不联系 provider |
 | `/forge-agent run <profile> [--backend <id>] <task>` | 审批并执行前台只读任务 |
 
-只接受项目明确授权的 profile。模型工具为 `forge_subagent_profiles` 和 `forge_subagent`。见[安全说明](../guides/delegation.md)。
+只接受匹配 scope 明确授权的 profile：项目 `subagents.json` 授权 `project:<id>`，全局 `subagents.json` 授权 `global:<id>`；也可使用 `.pi/forge/config.json.subagents` 作为只读兼容来源。模型工具为 `forge_subagent_profiles` 和 `forge_subagent`。见[安全说明](../guides/delegation.md)。
 
 ## Payload
 

package/examples/custom-system-status-extension/README.md

@@ -4,7 +4,7 @@ This example shows how trusted pi-forge extension modules can register a custom
 
 It registers:
 
-- `{{cpuLoad}}` macro: one-line CPU load summary.
+- `{{ extensions.cpuLoad }}` macro: one-line CPU load summary.
 - `machine-status` slot: CPU load, OS load average, memory, and uptime snapshot.
 
 The renderers are synchronous, so this example uses Node's OS load average and memory APIs. It is a rough machine-load signal, not an async sampled CPU-utilization profiler.
@@ -53,12 +53,12 @@ Each module exports a default function or named `register` function:
 
 ```ts
 export default function register(api) {
-  api.registerMacro({ name: "cpuLoad", render: () => "..." });
+  api.registerMacro({ name: "cpuLoad", dependencies: [], render: ({ env, helpers }) => "..." });
   api.registerSlot({ name: "machine-status", render: () => "..." });
 }
 ```
 
-pi-forge passes the registration API into the function, tracks unregister callbacks, and unregisters previous definitions before reloading the folder. If the extension is not loaded, the stack can still be read, but `machine-status` will validate as an unsupported slot and `{{cpuLoad}}` will remain an unresolved macro.
+pi-forge passes the registration API into the function, tracks unregister callbacks, and unregisters previous definitions before reloading the folder. If the extension is not loaded, the stack can still be read, but `machine-status` will validate as an unsupported slot and `{{ extensions.cpuLoad }}` will remain an unresolved extension path.
 
 Only use this folder for trusted code. These modules execute with normal local code permissions after the project is trusted.