@zihanw/pi-forge 0.4.1 → 0.5.1

package/docs/reference/macros-and-slots.md

@@ -1,56 +1,59 @@
-# Macros and runtime slots
+# Forge-v1 templates and runtime slots
 
 [Documentation](../README.md)
 
-## Value macros
+Prompt text is compiled with the `forge-v1` engine: one closed grammar with no
+includes, loops, function calls, or arbitrary expressions. Preview, runtime,
+and subagent preparation use the same engine entry.
 
-| Macro | Value |
-|---|---|
-| `{{lastUserMessage}}` | Latest user message |
-| `{{date}}` | Current date as `YYYY-MM-DD` |
-| `{{time}}` | Current time as `HH:MM:SS` |
-| `{{cwd}}` | Current working directory |
-| `{{tools}}` | Comma-separated selected tool names |
-| `{{selectedTools}}` | Alias of `{{tools}}` |
-| `{{activeModel}}` | Current `provider/model` |
-| `{{name}}` | Turn, session, then static variable lookup |
-| `{{var::name}}` / `{{getvar::name}}` | Explicit scoped-fallback variable lookup |
-| `{{getturnvar::name}}` | Turn-only lookup |
-| `{{getsessionvar::name}}` | Session-only lookup |
-
-## Variable mutation
+## Template interpolation
 
-```text
-{{setvar::name::value}}             set a turn variable
-{{setturnvar::name::value}}         set a turn variable
-{{setsessionvar::name::value}}      set a session variable
-{{setvar::session::name::value}}    set a session variable
-{{clearvar::name}}                  clear using normal scope behavior
-{{clearturnvar::name}}              clear a turn variable
-{{clearsessionvar::name}}           clear a session variable
-```
+| Syntax | Value |
+|---|---|
+| `{{ runtime.cwd }}` | Current working directory |
+| `{{ runtime.date }}` | Current date as `YYYY-MM-DD` |
+| `{{ runtime.time }}` | Current time as `HH:MM:SS` |
+| `{{ runtime.lastUserMessage }}` | Latest user message |
+| `{{ runtime.selectedToolsText }}` | Comma-separated effective tool names |
+| `{{ runtime.activeModel }}` | Current `provider/model` |
+| `{{ parameters.<name> }}` | Static stack parameter |
+| `{{ extensions.<name> }}` | Registered custom macro value |
 
-Turn variables reset for each message. Session variables follow Pi's active session-tree branch. Static variables come from top-level `stack.variables`. Non-string JSON-compatible values stringify as JSON during substitution.
+Legacy v1 stacks keep a compatibility fallback: bare `{{name}}` resolves to a
+static parameter, `{{lastUserMessage}}`/`{{date}}`/`{{time}}`/`{{cwd}}` resolve
+to the matching `runtime.*` value, and registered custom macros resolve by
+name. New v2 stacks use the explicit `parameters.*` / `runtime.*` paths.
 
-## Filters and conditionals
+## Filters
 
-Nested macros are supported. `::` separators are parsed only at the current macro depth.
+Nested pipelines are supported; filters are pure and versioned.
 
-| Macro | Result |
+| Filter | Result |
 |---|---|
-| `{{trim::value}}` | Trim surrounding whitespace |
-| `{{upper::value}}` | Uppercase value |
-| `{{lower::value}}` | Lowercase value |
-| `{{json::value}}` | JSON string literal |
-| `{{xml::value}}` | XML-escaped value |
-| `{{ifvar::name::then::else}}` | Select by variable existence |
-| `{{ifeq::name::expected::then::else}}` | Select by equality |
-| `{{iftools::tool::then::else}}` | Select by effective tool name |
-| `{{ifslot::slot::then::else}}` | Select by enabled slot name |
+| `{{ value \| trim }}` | Trim surrounding whitespace |
+| `{{ value \| upper }}` | Uppercase |
+| `{{ value \| lower }}` | Lowercase |
+| `{{ value \| json }}` | JSON string literal |
+| `{{ value \| xml }}` | XML-escaped |
+
+## Conditionals
+
+```text
+{% if runtime.tool.read %}read is available{% else %}read is unavailable{% endif %}
+{% if parameters.mode == "image-reader" %}image reader{% endif %}
+{% if runtime.tool.bash != null %}bash visible{% endif %}
+```
 
-The final `else` is optional. Branches are lazy: skipped branches are not expanded and cannot mutate variables.
+- `{% if path %}` selects the branch when the path exists and is truthy.
+- `==` / `!=` compare against a quoted string, including empty strings.
+- Nested `{% if %}` blocks are supported.
+- An undefined output path is a strict compile error (no raw fallback); the
+  legacy `defaults.unresolvedMacroPolicy` is ignored.
+- `runtime.tool.<name>` and `runtime.slot.<name>` booleans power tool/slot
+  conditionals without function calls.
 
-Unknown macro behavior is controlled by stack `defaults.unknownMacro`: keep, warn, or error according to schema validation.
+When a block fails to parse, analyze, or render, pi-forge emits an error
+diagnostic and omits that block rather than re-injecting raw template text.
 
 ## Built-in slots
 
@@ -62,21 +65,39 @@ Unknown macro behavior is controlled by stack `defaults.unknownMacro`: keep, war
 | `skills` | Model-visible loaded Pi skills |
 | `project-context` | Trusted project instructions/context |
 | `append-system-prompt` | Pi's appended system prompt text |
-| `variables` | Static/session/turn values |
 | `date` | Current date, optionally time |
 | `cwd` | Working directory |
 | `date-cwd` | Date and working directory, optionally time |
 | `active-model` | Selected provider/model |
 | `pi-docs` | Pi documentation guidance |
 
-Structured slots (`tools`, `tool-guidelines`, `skills`, `project-context`, `variables`) default to XML-style wrappers and support `"format": "plain"`.
-
-Notable Pi-mirror options include `tools.onlyWithSnippets`, `tool-guidelines.heading`, `tool-guidelines.includePiDefaultGuidelines`, `tool-guidelines.piStyle`, and `skills.requireReadTool`. `date` and `date-cwd` support `includeTime: true`.
+Structured slots (`tools`, `tool-guidelines`, `skills`, `project-context`)
+default to XML-style wrappers and support `"format": "plain"`.
 
-`variables` supports `includeStatic`, `includeSession`, `includeTurn`, and `format`.
+## Trusted custom definitions
 
-The complete `chat-history` option set is documented in [stack schema](stack-schema.md#chat-history-options).
+Trusted global/project modules register macros (addressed as
+`{{ extensions.<name> }}`) and slots through the pure extension port:
+
+```ts
+api.registerMacro({
+  name: "ticketId",
+  description: "Current ticket id.",
+  dependencies: ["parameters.ticket.id"],
+  render: ({ env, helpers }) => String(env.parameters["ticket.id"]),
+});
+
+api.registerSlot({
+  name: "ticket-context",
+  description: "Render ticket context.",
+  dependencies: ["parameters.ticket.id"],
+  options: { heading: { type: "string", default: "Ticket context" } },
+  render: ({ item, options, env, helpers }) => "...",
+});
+```
 
-## Trusted custom definitions
+Custom slots receive the same pure `{ item, options, env, helpers }` context and
+declared-dependency resolution as macros, and their output is held to the same
+16,384-character extension limit.
 
-Trusted global/project modules and reusable Pi packages can register additional macro and slot names. The runtime exposes the active definitions through `getRegisteredMacros()` and `getRegisteredSlots()`. See [custom macros and slots](../guides/custom-macros-and-slots.md).
+See [custom macros and slots](../guides/custom-macros-and-slots.md).

package/docs/reference/public-api.md

@@ -1,28 +1,87 @@
 # 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 four 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.
+
+### 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` 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
+
+- 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.
 
@@ -95,19 +95,20 @@ 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.
 
 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/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/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

@@ -43,4 +43,4 @@ Agent profile 是项目级或用户全局、带 schema version 的预设，只
 
 `/profile status` 会把 profile 源定义变化和当前模型/思考等级/stack drift 分开显示。Provenance 只用于 branch 状态报告；reload、resume、tree navigation 和 compaction 不会重新应用 profile。
 
-普通 profile 默认不能委派。Delegation 授权跟随 profile scope：可信项目 `.pi/forge/config.json` 的 `subagents.profiles.<id>` 只授权 `project:<id>`，用户全局 `~/.pi/forge/config.json` 的 `subagents.profiles.<id>` 只授权 `global:<id>`；同 ID 的全局和项目 profile 永不互相继承授权。删除 profile 会清除同 scope 的授权，防止以后同 ID profile 继承权限。启用前见[前台 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

@@ -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,13 +21,13 @@ 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，并限制消息数或字符数。
 
 ## 策略边界
 
-工具 `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 与自动启用
 
@@ -35,8 +35,8 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 - 项目 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

@@ -64,11 +64,12 @@ Profile 默认保存在 `.pi/forge/agent-profiles/*.json`。`/profile save globa
 |---|---|
 | `.pi/forge/prompt-stacks/` | 项目 prompt stacks |
 | `.pi/forge/agent-profiles/` | 项目 agent profiles |
-| `.pi/forge/config.json` | 项目配置和 `project:<id>` delegation 授权 |
+| `.pi/forge/config.json` | 项目配置（`webEditor.*`） |
 | `.pi/forge/extensions/` | 可信项目 macro/slot 代码 |
 | `~/.pi/forge/prompt-stacks/` | 用户全局 prompt stacks |
 | `~/.pi/forge/agent-profiles/` | 用户全局 agent profiles |
-| `~/.pi/forge/config.json` | 用户默认配置和 `global:<id>` delegation 授权 |
+| `~/.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`，使用 Web 编辑器的 `global` scope 下拉可创建到用户全局 `~/.pi/forge/prompt-stacks`。安全迁移方式：

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` 中逐个启用项目 profile，在用户全局 `~/.pi/forge/config.json` 中逐个启用全局 profile；也可以使用 `/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": {
+    "project:reviewer": {
+      "enabled": true,
+      "timeoutMs": 300000
     }
   }
 }
 ```
 
-授权跟随 profile scope：项目 config 的 `subagents.profiles.<id>` 只授权 `project:<id>`，全局 config 的 `subagents.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 与运行
 
@@ -55,7 +53,7 @@ Profile 默认不能委派。请在可信项目的 `.pi/forge/config.json` 中
 }
 ```
 
-它只影响 `forge_subagent`；`/forge-agent run` 仍需要交互审批。格式错误或不可信项目会 fail closed。请把此 config 当作授权文件：除非所有可调用父 agent 都可以无需再次询问就把编译 prompt 和可读文件发给 provider，否则不要启用或提交此设置。
+它只影响 `forge_subagent`；`/forge-agent run` 仍需要交互审批。格式错误或不可信项目会 fail closed。请把此 `subagents.json` 当作授权文件：除非所有可调用父 agent 都可以无需再次询问就把编译 prompt 和可读文件发给 provider，否则不要启用或提交此设置。
 
 ## Child 边界