@zihanw/pi-forge 0.5.0 → 0.5.2

package/docs/reference/configuration.md

@@ -9,13 +9,16 @@ Project configuration lives in `.pi/forge/config.json` and is loaded only for a
 ```json
 {
   "webEditor": {
-    "port": 41738
+    "port": 41738,
+    "locale": "auto"
   }
 }
 ```
 
 The port is preferred, not guaranteed. The editor binds only to `127.0.0.1` and chooses another available port when necessary.
 
+`webEditor.locale` selects the editor's interface language: `"en"`, `"zh-CN"`, or `"auto"` (default). `"auto"` follows the browser language. The language selector in the editor's top bar writes this setting; `"auto"` removes the key.
+
 ## Experimental subagents
 
 Subagent configuration is owned by the optional `@zihanw/pi-forge-subagents` package. Dedicated files are `.pi/forge/subagents.json` for a trusted project and `~/.pi/forge/subagents.json` for user defaults. Legacy `.pi/forge/config.json` / `~/.pi/forge/config.json` `subagents` sections are read-only fallback material and emit a warning.
@@ -38,7 +41,7 @@ Trusted project `subagents.json` may override defaults, authorize individual pro
   "allowAgentInvocationWithoutApproval": false,
   "summaryInToolDescription": false,
   "profiles": {
-    "reviewer": {
+    "project:reviewer": {
       "enabled": true,
       "backend": "pi-rpc-readonly",
       "timeoutMs": 180000
@@ -51,7 +54,7 @@ Valid timeouts are 1,000–3,600,000 ms. Invalid fields warn and fall back to th
 
 `summaryInToolDescription` (default `false`) embeds a compact, bounded summary of enabled subagent profiles directly in the `forge_subagent` tool description so the parent model can pick a profile without a discovery call. Ready profiles appear first, and unavailable enabled profiles include their first resolution error. It may be set in user or trusted-project `subagents.json` and applies wherever it is enabled.
 
-`profiles` in global `subagents.json` authorizes `global:<id>` profiles; the trusted project's `profiles` authorizes `project:<id>` profiles. Same-ID profiles never inherit enablement, backend, or timeout policy from each other. `allowAgentInvocationWithoutApproval` is project-only, requires trust, and fails closed when malformed. Deleting a profile does not modify `subagents.json`; remove any enabled entry for the deleted profile manually.
+Profile authorization keys should use canonical selectors: `project:<id>` or `global:<id>`. A bare key is a compatibility spelling for `project:<id>` regardless of which config file contains it; it never authorizes a global profile. Therefore a global profile must be written explicitly as `"global:reviewer": { "enabled": true }` in `~/.pi/forge/subagents.json`. Same-ID profiles never inherit enablement, backend, or timeout policy from each other. `allowAgentInvocationWithoutApproval` is project-only, requires trust, and fails closed when malformed. Deleting a profile does not modify `subagents.json`; remove any enabled entry for the deleted profile manually.
 
 Treat project configuration as an authorization boundary. In particular, do not commit unattended delegation unless every permitted parent agent may transmit compiled prompt and readable project content without another human approval.
 

package/docs/reference/features.md

@@ -72,12 +72,16 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Chat history can filter summaries/roles, drop prior tool history, and cap recent history by message count or approximate characters with dangling tool calls/results repaired after filtering.
 - Duplicate chat-history warning unless explicitly allowed.
 - Synthetic `user`, `assistant`, and hidden `custom` messages.
+- Optional consecutive-role merge (`context.mergeConsecutiveRoles`/`mergeSeparator`): runs of consecutive stack-authored `user`/`assistant` items compile into a single message; chat-history output and custom-role items are hard boundaries, and merging runs after compiled-stage regex.
+- Validation warning when an enabled `system` item appears after non-system items (cross-channel item position has no effect on compilation).
 - Context rewrite limited to the first provider request of each user-submitted turn.
 - Tool policy filters Pi's active tool list while the stack is active and restores the previous active tools when the stack no longer applies.
 - Tool policy restores its pre-policy baseline during extension shutdown so Pi reload/session replacement cannot carry a restricted built-in tool set into the replacement runtime.
 - Startup tool enforcement waits until extension `session_start` configuration is complete, reasserts before user input and turns, and blocks disallowed model tool calls at execution time.
 - Skill policy filters skills rendered by pi-forge `skills` slots.
 - Outgoing regex transforms can run after `chat-history` insertion and after final prompt compilation.
+- Per-rule `frequency: "request"` re-runs an outgoing message rule on every tool-result follow-up request over Pi's full natural context; the default `"turn"` keeps first-request-only behavior.
+- `finalize` rules whose `roles` explicitly include `"toolResult"` also rewrite stored tool-result messages at completion time (destructive, documented); rules without `roles` stay assistant-only.
 - Finalize regex transforms can rewrite completed assistant messages at `message_end`.
 
 ## Regex Transforms
@@ -197,6 +201,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Collapsible prompt-stack sidebar.
 - Collapsible stack metadata panel and main-area tabs for Items, Regex, Policy, and Stack JSON/context/variables work.
 - Light/dark theme toggle, button icons, and tooltips for common actions.
+- English/中文 interface switch (`webEditor.locale`: `"en"`, `"zh-CN"`, or `"auto"` following the browser language); contributed settings tabs remain provider-authored and are not translated.
 - Unsaved-change badge in the top bar.
 - Create a new prompt stack from the browser, including when no stack files exist yet; new stacks start from the default Pi prompt mirror layout.
 - View immutable stack ID and edit name, mode, `autoActivate`, description, and existing stack file content; use Fork to create a new ID.

package/docs/reference/public-api.md

@@ -4,7 +4,7 @@
 
 pi-forge is pre-1.0. This document defines the intentional integration surfaces of the 0.5.0 line.
 
-## The three intentional entry points
+## The four intentional entry points
 
 `check-package` enforces this allowlist; nothing else is importable from the package.
 
@@ -60,10 +60,22 @@ The experimental host port over the Pi event bus: discovery, profile listing/sna
 
 The optional `@zihanw/pi-forge-subagents` package consumes this port and owns subagent execution and configuration.
 
+### 4. `@zihanw/pi-forge/ui-contribution`: versioned settings port
+
+```ts
+import {
+  UiContributionProvider,
+  UiContributionClient,
+  UI_CONTRIBUTION_PORT_VERSION,
+} from "@zihanw/pi-forge/ui-contribution";
+```
+
+The experimental generic Settings integration surface. Optional packages contribute recursively validated, JSON-compatible schemas and values over the Pi event bus; pi-forge owns only the renderer and web proxy. Providers own validation and persistence, may resolve operations asynchronously, and receive an abort signal tied to provider generation so stale requests can stop before side effects. The full contract is documented in the [UI contribution port reference](ui-contribution-port.md).
+
 ## 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.
+- **Experimental** surfaces (the `/subagent` and `/ui-contribution` ports) 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

package/docs/reference/stack-schema.md

@@ -25,7 +25,7 @@ Block:
 }
 ```
 
-Valid roles are `system`, `user`, `assistant`, and `custom`. Custom-role content participates in compilation but does not produce a provider message directly.
+Valid roles are `system`, `user`, `assistant`, and `custom`. Custom-role content participates in compilation and reaches the provider as a `user` message: Pi converts `custom` messages to `user` when it builds the wire request, so the wire carries no distinct custom role. Custom-role items never merge with other items (see [Context options](#context-options)).
 
 Slot:
 
@@ -45,12 +45,30 @@ Slot:
 
 Item IDs must be unique. Unsupported slots and missing required custom registrations produce diagnostics. Multiple chat-history slots warn unless explicitly permitted.
 
+Item position only matters within each channel: all `system` items join the system prompt in their relative order, and all non-system items become messages in their relative order. A `system` item placed after non-system items therefore has no effect on placement and produces a validation warning; roles are never silently converted. Use a `user` item for in-conversation injection.
+
 ## Modes
 
 - `replace` replaces Pi's base system prompt; empty output falls back to the base.
 - `append` places stack system text after Pi's base.
 - `prepend` places stack system text before Pi's base.
 
+## Context options
+
+```json
+{
+  "context": {
+    "allowDuplicateChatHistory": false,
+    "mergeConsecutiveRoles": true,
+    "mergeSeparator": "\n\n"
+  }
+}
+```
+
+- `allowDuplicateChatHistory` permits multiple enabled chat-history slots; otherwise only the first expands.
+- `mergeConsecutiveRoles` (default `false`) merges runs of consecutive stack items that share the same declared role into a single message, joined by `mergeSeparator` (default a blank line). Only stack-authored `user`/`assistant` items merge: chat-history output (including the implicit history tail) and `custom` items are hard boundaries, and merging runs after compiled-stage regex so regex semantics are unchanged. The web editor preview reflects the merged layout.
+- `mergeSeparator` is inserted verbatim between merged texts and may be an empty string.
+
 ## Chat-history options
 
 ```json
@@ -95,7 +113,7 @@ Patterns are exact by default and support `*` wildcards:
 }
 ```
 
-Each resource may have a non-empty `allow` list or `deny` list, never both. Tool allow keeps matching active tools; deny removes matching active tools. Unmatched allow patterns are surfaced during validation/preflight.
+Each resource may have a non-empty `allow` list or `deny` list, never both. A selective tool `allow` list chooses matching tools from Pi's complete registered tool catalog, so it can activate a registered tool that was inactive when the stack was selected. A tool `deny` list removes matching tools from the active baseline. `allow: ["*"]` remains unrestricted and does not activate every registered tool. Unmatched allow patterns are surfaced during validation/preflight.
 
 Tool policy changes Pi's active tool list, is reasserted before input/turns, and has a tool-call guard. It preserves external additions in the restorable baseline and restores that baseline when policy no longer applies or the extension shuts down.
 
@@ -151,6 +169,43 @@ Regex rules are ordered, deterministic JavaScript `RegExp` replacements. There i
 
 Message rules may filter by `roles`, `maxMessages`, `maxChars`, `minDepth`, and `maxDepth` (depth 0 is latest). `trimStrings` removes literal strings from expanded matches/captures. Supported flags are `g`, `i`, `m`, `s`, and `u`. Replacements use JavaScript `$&`/`$1`; `$0` is accepted as a full-match alias and `$$` yields a literal dollar sign.
 
+### Frequency
+
+Outgoing rules default to `"frequency": "turn"`: they run during the full compilation on the first provider request of each user turn. Tool-result follow-up requests receive Pi's natural context, so a turn-scoped rule never sees tool output until the next user turn.
+
+Set `"frequency": "request"` to also run an outgoing message rule on every tool-result follow-up request, applied to Pi's full natural context:
+
+```json
+{
+  "id": "redact-api-keys",
+  "stage": "history",
+  "effect": "outgoing",
+  "frequency": "request",
+  "pattern": "\\b(sk-[A-Za-z0-9_-]{12,})\\b",
+  "flags": "g",
+  "replace": "[REDACTED]"
+}
+```
+
+Each provider request is rebuilt from the stored transcript, so re-applying a rule to older messages is wire-consistent and never doubles. History-stage rules and compiled-stage rules with a `messages` target both participate; on follow-ups there is no stack layout rewrite, so both stages collapse onto the natural context (history-stage rules run first). `frequency` has no effect on `finalize` rules or system-only targets, and validation says so. It is wire-only scrubbing: the stored transcript keeps the original text.
+
+Regex rules only cover the text targets and patterns you declare. They cannot recognize every credential format and do not scan system text, tool definitions, or arbitrary request metadata unless those targets are explicitly supported and selected. Treat them as deterministic text transforms, not as a security boundary.
+
+To scrub the same recognized shapes from stored assistant/tool-result text, pair a request-frequency outgoing rule with a `finalize` rule:
+
+```json
+{
+  "id": "redact-api-keys-finalize",
+  "stage": "compiled",
+  "effect": "finalize",
+  "targets": ["messages"],
+  "roles": ["assistant", "toolResult"],
+  "pattern": "\\b(sk-[A-Za-z0-9_-]{12,})\\b",
+  "flags": "g",
+  "replace": "[REDACTED]"
+}
+```
+
 Outgoing rules change future model input. To destructively change a completed assistant transcript message:
 
 ```json
@@ -170,3 +225,5 @@ 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: "outgoing"` and `"finalize"` are the only valid effects; `"display"` and `"both"` are rejected during validation. Runtime diagnostics report match and changed-segment counts.
+
+`finalize` applies to assistant messages by default, and additionally to stored tool-result messages when a rule's `roles` explicitly includes `"toolResult"` — useful for scrubbing secrets out of stored tool output before the follow-up request replays it. Rules without `roles` keep assistant-only behavior, user messages are never finalized, and unsupported roles warn.

package/docs/reference/ui-contribution-port.md

@@ -0,0 +1,51 @@
+# UI contribution port contract
+
+[Documentation](../README.md)
+
+Status: experimental, versioned (`UI_CONTRIBUTION_PORT_VERSION = 1`). The `@zihanw/pi-forge/ui-contribution` entry point is the generic cross-extension port that lets optional packages contribute schema-driven pages to the pi-forge web editor's top-level **Settings** surface. The forge side knows nothing about specific providers; the first consumer is [`@zihanw/pi-forge-subagents`](https://github.com/MacroSony/pi-forge-subagents), which contributes its Subagent Settings page when installed.
+
+## Ownership boundary
+
+- **The contributing package owns** its tab's form schema, current values, server-side validation on write, and persistence (for example, the subagent package owns `subagents.json`). It implements the provider side of the port.
+- **pi-forge owns** provider discovery over the bus, rendering contributed pages through the generic schema-form renderer, and proxying browser writes back over the bus through the web server routes. It never interprets or stores contributed configuration itself. Contributed pages are not stack tabs and never mount in the stack Preview dock.
+- **Never crosses the port:** functions, components, live contexts, internal registries, or any non-JSON-compatible value. All payloads are plain recursively validated JSON. The port is not a trust boundary — providers must re-validate everything they receive and never trust the web client.
+
+## Transport and lifecycle
+
+`UiContributionTransport` is a minimal `{ emit(channel, data), on(channel, handler) }` interface; the production wiring is `pi.events`. Messages travel on the dedicated `@zihanw/pi-forge/ui-contribution/v1` channel namespace with its own version counter, separate from the `/subagent` host port. Wire messages are plain JSON-compatible data validated recursively at both boundaries (exact field sets, typed enums, plain objects only, unknown fields rejected).
+
+Channels: `discover`, `available`, `request`, `reply`, `unavailable`.
+
+Lifecycle rules:
+
+1. Version negotiation: `discover` carries `protocolVersion` plus a supported `minVersion`/`maxVersion` range; a compatible provider answers `available` with its own `protocolVersion`, range, `capabilities`, `hostId`, and `generation`.
+2. A second compatible provider fails discovery explicitly (`duplicate`).
+3. `request`/`reply` messages carry `requestId` + `hostId` + `generation`; stale-generation and wrong-host requests are rejected server-side, mismatched replies ignored client-side.
+4. Provider disposal sends `unavailable`. The web editor clears that provider's contributed Settings pages and re-discovers when a provider reappears across sessions; late-surfacing providers are picked up without a page reload path change. The local HTTP listing also carries a forge-owned monotonic, opaque provider-session key so a fast restart refreshes a still-visible form even when browser polling never observes the empty interval. Browser PUT handling binds each response to the session that received it; a delayed success from an older session cannot mark or overwrite the newer session and the preserved draft is retried instead.
+5. Operation handlers may return a result or a promise of one and must never throw across the bus; rejected promises and thrown failures are converted to `{ ok: false, error }` results. Each invocation receives `{ signal, generation }`; stopping the provider aborts the signal. Handlers that await before persistence must check it before side effects. Replies from a stopped generation are discarded as a final transport guard.
+
+The Settings host keeps the first descriptor for each `tabId`; later duplicates are ignored. Browser button IDs use a Settings-specific prefix and cannot collide with built-in stack tabs. Providers should still emit unique stable `tabId` values because `writeValues` routes by that identifier. In-progress drafts and save status are tracked per tab, so switching between contributed pages does not discard a pending edit or leak its status into another page.
+
+## Operations
+
+### Discovery
+
+The web host acts as the client: `UiContributionClient.discover()` announces on the channel namespace and waits (bounded timeout) for an `available` announcement. Discovered tab descriptors are fetched at page load through `GET /api/contrib`.
+
+### `listContributions`
+
+Request: `{}`. Response: `{ tabs: UiContributionTabDescriptor[] }` — each descriptor carries `tabId`, `title`, `icon`, a `FormSchema`, and the current `values`. Read-only; listing a tab contributes it to the editor but performs no other side effect. Every HTTP `GET /api/contrib` refreshes this operation, so providers may update plain-data option catalogs without restarting their session.
+
+### `writeValues`
+
+Request: `{ tabId, patch }` — a partial values patch for one contributed tab. Omitted top-level fields preserve their stored values. A supplied `record` field is the complete keyed table produced by the form, so omitted rows represent deletion. The provider merges those semantics over its current values, re-validates server-side, and persists the result to its own storage. Response: `{ ok: true, values? }` with the canonical stored values, or `{ ok: false, errors }` with per-field error strings keyed by field key (dotted paths for record rows). The web server exposes this as `PUT /api/contrib/<tabId>` and rejects malformed or oversized request bodies with 400/413 before any bus call.
+
+The browser serializes autosave requests. If the form changes while a PUT is in flight, the latest complete normalized snapshot is queued and written only after the current request settles. This ordering prevents older provider writes from landing after newer ones.
+
+## Form schema
+
+v1 field types are deliberately restricted: `boolean`, `number`, `enum`, `string`, and `record` (a keyed table of entries — for example per-profile settings). Fields carry `key`, `label`, optional `description`/`required`/`default`, enum `options` (plain strings or `{ value, label }`), numeric `min`/`max`, string `maxLength`/`pattern`/`placeholder`, and record sub-fields (`recordFields`, `keyLabel`, `keyPlaceholder`). A record may also provide `keyOptions` (the same string-or-labelled-option shape as enum options); the generic renderer then uses a selector for row identity and prevents choosing a key already used by another row. Providers remain responsible for refreshing those plain-data options and validating them again on write.
+
+## Errors
+
+`UiContributionPortError` 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/concepts/agent-profiles.md

@@ -43,4 +43,4 @@ Agent profile 是项目级或用户全局、带 schema version 的预设，只
 
 `/profile status` 会把 profile 源定义变化和当前模型/思考等级/stack drift 分开显示。Provenance 只用于 branch 状态报告；reload、resume、tree navigation 和 compaction 不会重新应用 profile。
 
-普通 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)。
+普通 profile 默认不能委派。Delegation 授权由可选包 `@zihanw/pi-forge-subagents` 通过专用文件持有，使用 `project:<id>` 或 `global:<id>` 完整 key，并可按 profile 覆盖 backend/timeout。裸授权 key 无论位于哪个文件都只是项目 profile 的兼容别名；同 ID 的全局和项目 profile 永不互相继承授权。主包不读取任何 subagent 配置，删除 profile 也不会改动 `subagents.json`。启用前见[前台 delegation](../guides/delegation.md)。

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

@@ -2,7 +2,11 @@
 
 [中文文档](../README.md) · [English](../../concepts/prompt-stacks.md)
 
-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 内算错误。
+Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 **block** 和动态 **slot** 组成。
+
+> **命名说明。** Prompt stack 由 `/preset` 命令族管理：stack 文件把编排与策略打包在一起，实际作用相当于一份完整预设。命名将在未来版本统一；本文档沿用"prompt stack／提示词栈"指代该资源。
+
+Stack 可以放在项目 `.pi/forge/prompt-stacks/`，也可以放在用户全局 `~/.pi/forge/prompt-stacks/`。命令接受 `reviewer`、`project:reviewer` 和 `global:reviewer`；未限定 ID 优先解析项目 stack，项目 stack 会遮蔽同 ID 全局 stack。重复 ID 只在同一 scope 内算错误。
 
 ## 编译模型
 
@@ -13,8 +17,8 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 3. 在可移动 `chat-history` 周围插入 user/assistant 消息。
 4. 用 forge-v1 编译 `runtime.*` / `parameters.*` / `extensions.*` 模板。
 5. 对 Pi 执行工具策略，并过滤 pi-forge 渲染的 skills。
-6. 应用 history/compiled outgoing regex。
-7. 可选地在消息完成后应用破坏性的 finalize regex。
+6. 应用 history/compiled outgoing regex。`frequency: "request"` 的 outgoing 消息规则还会在 tool 结果后续请求上对 Pi 的完整自然上下文再次运行；默认 `"turn"` 保持仅在每轮首次请求运行。
+7. 可选地在消息完成后应用破坏性的 finalize regex；`roles` 显式包含 `"toolResult"` 的 finalize 规则还会改写存储的 tool 结果消息。
 
 ## 常用历史布局
 
@@ -25,9 +29,11 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 
 这样既保留旧上下文，又只在最后明确出现一次当前请求。History 还可以过滤 summary/role、去掉旧工具消息、移除 assistant thinking，并限制消息数或字符数。
 
+Stack 还可以通过 `context.mergeConsecutiveRoles`（及可选的 `context.mergeSeparator`）把连续的同角色条目合并成一条消息；chat-history 输出和 custom 角色条目永远不会被合并。详见英文 [stack schema](../../reference/stack-schema.md#context-options)。
+
 ## 策略边界
 
-工具 `allow`/`deny` 会修改 Pi active tools，并在 tool call 时再次检查。Skill policy 只过滤 pi-forge 渲染给模型的列表；它不能阻止明确调用，也不是安全边界。若必须控制模型可见 skill 列表，请使用 `replace`，因为 Pi 的基础 prompt 可能已经在 `append`/`prepend` 内容之前列出 skills。
+工具 `allow`/`deny` 会修改 Pi active tools，并在 tool call 时再次检查。具体的 `allow` 列表会从 Pi 的完整已注册工具目录中选择，因此可以启用 stack 激活前处于 inactive 状态的工具；`deny` 只从原 active baseline 中移除工具，`allow: ["*"]` 仍表示不限制且不会启用全部工具。Skill policy 只过滤 pi-forge 渲染给模型的列表；它不能阻止明确调用，也不是安全边界。若必须控制模型可见 skill 列表，请使用 `replace`，因为 Pi 的基础 prompt 可能已经在 `append`/`prepend` 内容之前列出 skills。
 
 ## Scope 与自动启用
 

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

@@ -15,7 +15,7 @@ Profile 默认不能委派。请在可信项目的 `.pi/forge/subagents.json`
   "backend": "pi-subprocess-readonly",
   "timeoutMs": 60000,
   "profiles": {
-    "reviewer": {
+    "project:reviewer": {
       "enabled": true,
       "timeoutMs": 300000
     }
@@ -23,7 +23,7 @@ Profile 默认不能委派。请在可信项目的 `.pi/forge/subagents.json`
 }
 ```
 
-授权跟随 profile scope：项目 `subagents.json` 的 `profiles.<id>` 只授权 `project:<id>`，全局 `subagents.json` 的 `profiles.<id>` 只授权 `global:<id>`。同 ID 的全局和项目 profile 不会互相继承 enable/backend/timeout。未启用或未列出的 ID 不会被 discovery 返回，即使猜中 ID 也会被拒绝。
+授权 key 应使用完整 selector：`project:<id>` 或 `global:<id>`。裸 key 仅为项目 profile 的兼容写法，即使写在 `~/.pi/forge/subagents.json` 中也只授权 `project:<id>`；授权全局 profile 必须显式写成 `"global:reviewer": { "enabled": true }`。同 ID 的全局和项目 profile 不会互相继承 enable/backend/timeout。未启用或未列出的 ID 不会被 discovery 返回，即使猜中 ID 也会被拒绝。
 
 ## Plan 与运行
 

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

@@ -20,6 +20,10 @@
 
 端口被占用时会自动选择其他端口。请不要把带 token 的编辑器 URL 暴露或代理到不可信网络。写入操作要求项目已被 Pi 信任。
 
+## 界面语言
+
+编辑器界面提供英文和中文。使用顶栏的语言选择器（Auto / English / 中文）；选择会写入项目配置中的 `webEditor.locale`。默认为 `Auto`，跟随浏览器语言，首次页面渲染也会参考浏览器的 `Accept-Language` 请求头。界面框架、内置 stack/profile 界面以及预览/差异停靠栏均已本地化；编译器诊断信息、插件提供的设置页面以及堆栈内容（条目名称、块文本）保持其原始语言。
+
 ## Prompt stack 工作区
 
 支持：

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

@@ -49,7 +49,7 @@
 | `/forge-agent plan <profile> [--backend <id>] <task>` | 准备、显示并丢弃计划，不联系 provider |
 | `/forge-agent run <profile> [--backend <id>] <task>` | 审批并执行前台只读任务 |
 
-只接受匹配 scope 明确授权的 profile：项目 `subagents.json` 授权 `project:<id>`，全局 `subagents.json` 授权 `global:<id>`；也可使用 `.pi/forge/config.json.subagents` 作为只读兼容来源。模型工具为 `forge_subagent_profiles` 和 `forge_subagent`。见[安全说明](../guides/delegation.md)。
+只接受明确 scope 的授权：请在 `subagents.json` 中使用 `project:<id>` 或 `global:<id>` key。裸授权 key 始终表示 `project:<id>`，即使它位于全局配置中；`.pi/forge/config.json.subagents` 仅作为只读兼容来源。模型工具为 `forge_subagent_profiles` 和 `forge_subagent`。见[安全说明](../guides/delegation.md)。
 
 ## Payload
 

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

@@ -2,12 +2,12 @@
 
 This example shows how trusted pi-forge extension modules can register a custom macro and custom slot without importing `@zihanw/pi-forge` from a loose Pi extension file.
 
-It registers:
+At registration time it captures one machine snapshot, then registers:
 
 - `{{ 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.
+The renderers only format that captured value, so repeated prompt compilation over the same registered extension is deterministic. The snapshot stays fixed until the extension is reloaded; this is intentionally a registration/pure-render example, not live telemetry or an async sampled CPU-utilization profiler.
 
 ## Try It
 
@@ -27,6 +27,7 @@ Start Pi, trust the project if prompted, then run:
 ```
 
 Use `/preset diagnostics` to confirm the extension file is listed under loaded pi-forge extensions.
+Run `/preset reload` whenever you want to capture a fresh machine snapshot.
 
 ## Where To Put The Extension
 
@@ -54,7 +55,7 @@ Each module exports a default function or named `register` function:
 ```ts
 export default function register(api) {
   api.registerMacro({ name: "cpuLoad", dependencies: [], render: ({ env, helpers }) => "..." });
-  api.registerSlot({ name: "machine-status", render: () => "..." });
+  api.registerSlot({ name: "machine-status", dependencies: [], render: ({ options, helpers }) => "..." });
 }
 ```
 

package/examples/custom-system-status-extension/index.ts

@@ -12,10 +12,10 @@ interface ForgeRegistrationApi {
 		name: string;
 		source?: string;
 		description?: string;
+		dependencies?: string[];
 		options?: Record<string, unknown>;
 		render: (ctx: {
 			options: Record<string, unknown>;
-			format: () => "xml" | "plain" | "json";
 			helpers: {
 				escapeXml(value: string): string;
 				plainBullet(label: string, value: string): string;
@@ -38,17 +38,20 @@ interface SystemStatusSnapshot {
 }
 
 export default function registerSystemStatus(api: ForgeRegistrationApi): void {
+	const snapshot = Object.freeze(readSystemStatus());
 	api.registerMacro({
 		name: "cpuLoad",
 		source: "pi-forge-example-system-status",
-		description: "Current machine CPU load as normalized 1-minute OS load average.",
-		render: () => formatCpuLoad(readSystemStatus()),
+		description: "Machine CPU load captured when the trusted extension was registered.",
+		dependencies: [],
+		render: () => formatCpuLoad(snapshot),
 	});
 
 	api.registerSlot({
 		name: "machine-status",
 		source: "pi-forge-example-system-status",
-		description: "Current machine CPU, memory, and uptime snapshot.",
+		description: "Machine CPU, memory, and uptime captured when the trusted extension was registered.",
+		dependencies: [],
 		options: {
 			format: { type: "enum", values: ["plain", "xml"], default: "plain" },
 			heading: { type: "string", default: "Machine status" },
@@ -56,14 +59,13 @@ export default function registerSystemStatus(api: ForgeRegistrationApi): void {
 			includeUptime: { type: "boolean", default: true },
 		},
 		render: (ctx) => {
-			const snapshot = readSystemStatus();
 			const includeMemory = ctx.options.includeMemory !== false;
 			const includeUptime = ctx.options.includeUptime !== false;
 			const heading = typeof ctx.options.heading === "string" && ctx.options.heading.trim()
 				? ctx.options.heading.trim()
 				: "Machine status";
 
-			if (ctx.format() === "xml") {
+			if (ctx.options.format === "xml") {
 				const lines = [
 					"<machine_status>",
 					`  <cpu logical_cores=\"${snapshot.logicalCores}\" normalized_load_1m=\"${snapshot.normalizedLoad1.toFixed(3)}\" model=\"${ctx.helpers.escapeXml(snapshot.cpuModel)}\">${ctx.helpers.escapeXml(formatCpuLoad(snapshot))}</cpu>`,

package/examples/hack-prompt-stack.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": 2,
+  "type": "pi-forge.prompt-stack",
+  "id": "regex-hack",
+  "name": "Regex Hack Pack",
+  "description": "Default layout plus outgoing-history regex rules: ANSI escapes are removed and illustrative sk-/ghp_ token shapes are redacted. This is a non-exhaustive demo, not a general secret scanner.",
+  "autoActivate": false,
+  "mode": "replace",
+  "defaults": {
+    "syntheticMessagesVisible": false,
+    "unresolvedMacroPolicy": "warn"
+  },
+  "context": {
+    "allowDuplicateChatHistory": false
+  },
+  "tools": {
+    "allow": [
+      "*"
+    ]
+  },
+  "items": [
+    {
+      "kind": "block",
+      "id": "main-role",
+      "name": "Pi Default Role",
+      "enabled": true,
+      "role": "system",
+      "content": "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files."
+    },
+    {
+      "kind": "slot",
+      "id": "tools",
+      "name": "Available Tools",
+      "enabled": true,
+      "role": "system",
+      "slot": "tools",
+      "options": {
+        "format": "plain",
+        "onlyWithSnippets": true
+      }
+    },
+    {
+      "kind": "slot",
+      "id": "project-context",
+      "name": "Project Context",
+      "enabled": true,
+      "role": "system",
+      "slot": "project-context"
+    },
+    {
+      "kind": "slot",
+      "id": "date-cwd",
+      "name": "Date and Working Directory",
+      "enabled": true,
+      "role": "system",
+      "slot": "date-cwd"
+    },
+    {
+      "kind": "slot",
+      "id": "chat-history",
+      "name": "Chat History",
+      "enabled": true,
+      "slot": "chat-history",
+      "options": {
+        "stripAssistantThinking": false
+      }
+    }
+  ],
+  "regex": {
+    "schemaVersion": 1,
+    "rules": [
+      {
+        "id": "strip-ansi-escapes",
+        "name": "ANSI terminal escape codes removed from outgoing history",
+        "enabled": true,
+        "stage": "history",
+        "targets": [
+          "messages"
+        ],
+        "pattern": "\\x1B\\[[0-?]*[ -/]*[@-~]",
+        "flags": "g",
+        "replace": ""
+      },
+      {
+        "id": "redact-api-keys-outgoing",
+        "name": "Illustrative sk-/ghp_ token shapes redacted on every provider request",
+        "enabled": true,
+        "stage": "history",
+        "effect": "outgoing",
+        "frequency": "request",
+        "targets": [
+          "messages"
+        ],
+        "pattern": "\\b(sk-[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,})\\b",
+        "flags": "g",
+        "replace": "[REDACTED]"
+      },
+      {
+        "id": "redact-api-keys-finalize",
+        "name": "Illustrative sk-/ghp_ token shapes scrubbed from the stored transcript",
+        "enabled": true,
+        "stage": "compiled",
+        "effect": "finalize",
+        "targets": [
+          "messages"
+        ],
+        "roles": [
+          "assistant",
+          "toolResult"
+        ],
+        "pattern": "\\b(sk-[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9]{20,})\\b",
+        "flags": "g",
+        "replace": "[REDACTED]"
+      }
+    ]
+  },
+  "parameters": {}
+}

package/examples/minimal-prompt-stack.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 2,
+  "type": "pi-forge.prompt-stack",
+  "id": "minimal",
+  "name": "Minimal Worker",
+  "description": "Bare-minimum stack: one role block, one tools slot, chat history. Policy allows bash only - what you see is literally everything that gets sent.",
+  "autoActivate": false,
+  "mode": "replace",
+  "defaults": {
+    "syntheticMessagesVisible": false,
+    "unresolvedMacroPolicy": "warn"
+  },
+  "tools": {
+    "allow": [
+      "bash"
+    ]
+  },
+  "items": [
+    {
+      "kind": "block",
+      "id": "worker-role",
+      "name": "Worker Role",
+      "enabled": true,
+      "role": "system",
+      "content": "You are a helpful software engineer assistant."
+    },
+    {
+      "kind": "slot",
+      "id": "chat-history",
+      "name": "Chat History",
+      "enabled": true,
+      "slot": "chat-history"
+    }
+  ],
+  "parameters": {}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"description": "Pi extension for prompt stacks, one-shot agent profiles, policy, import, and debugging.",
 	"repository": {
 		"type": "git",
@@ -17,6 +17,11 @@
 			"types": "./dist/subagent/index.d.ts",
 			"import": "./dist/subagent/index.js",
 			"default": "./dist/subagent/index.js"
+		},
+		"./ui-contribution": {
+			"types": "./dist/ui-contribution/index.d.ts",
+			"import": "./dist/ui-contribution/index.js",
+			"default": "./dist/ui-contribution/index.js"
 		}
 	},
 	"keywords": [