@zihanw/pi-forge 0.5.0 → 0.5.1

package/docs/design/0.5.1-plan.md

@@ -0,0 +1,237 @@
+# pi-forge 0.5.1 — Combined Release Plan
+
+Status: active. Target release: 0.5.1 (first feature release after 0.5.0).
+Owner of truth: this document. Supersedes/folds in:
+- `docs/design/context-diff-plan.md` (context diff, now Lane 2)
+- The subagent UI-contribution discussion from the 0.5.x review thread (now Lane 1)
+
+Theme: **observability + subagent usability**. 0.5.0 was the architecture-split
+release; 0.5.1 ships per-turn prompt observability and makes the optional
+subagent package configurable without hand-editing JSON.
+
+## Lane ordering (deliberate)
+
+**Lane 1 ships first.** Its tab-registry refactor turns the web editor's tab
+system data-driven, which Lane 2's Preview dock builds on. Both lanes touch the
+client build pipeline and the tab area — do not run them in parallel in the
+same working tree.
+
+---
+
+## Lane 1 — UI contribution framework + subagent config UI
+
+### Goal
+
+Let the optional `@zihanw/pi-forge-subagents` package own its configuration UI
+(schema, validation, defaults, file writes) while the rendered settings tab
+appears inside the pi-forge web editor when — and only when — the subagent
+package is installed.
+
+Non-goal: arbitrary JS/component injection into the forge web UI. The event bus
+carries JSON only; that rule does not bend for UI.
+
+### Architecture (schema-driven contribution, "plan A")
+
+```
+┌─ pi-forge-subagents ─────────────┐         ┌─ pi-forge ─────────────────┐
+│ UI contribution provider:        │  bus    │ web host discovers provider │
+│  · getContribution() → { tabId,  │ ◄────── │ at startup (capability      │
+│    title, icon, schema, values } │  JSON   │ negotiation)                │
+│  · writeValues(patch) → validate │ ──────► │ generic schema-form tab     │
+│    + write subagents.json        │         │ (self-contained Vue comp.)  │
+└──────────────────────────────────┘         │ PUT /api/contrib/<id> proxy │
+                                             └─────────────────────────────┘
+```
+
+- **Contribution protocol**: new versioned port, separate version counter from
+  the v1 host port. All payloads are plain recursively-validated JSON (schema +
+  values), same discipline as `host-port.ts`.
+- **Forge side** is fully generic: it knows nothing about subagents. No
+  provider discovered → no contributed tab, zero cost.
+- **Config ownership stays put**: `subagents.json` (project/global + legacy
+  fallback) remains owned and written by the subagent package. Forge's web
+  server only proxies the bus call.
+
+### Forge-side changes (~1.5–2d)
+
+1. Tab registry: replace the hardcoded `"policy" | "regex" | "stack"` union in
+   `vue-tab-host.ts` with a data-driven registry (string tab ids, dynamic
+   buttons in `App.vue`).
+2. Generic schema-form renderer: self-contained Vue component, bridged via the
+   vue-host mechanism. Restricted field types for v1: boolean, number, enum,
+   string, plus a record/table shape for per-profile entries. **Do NOT add
+   imperative code to `legacy-editor.ts`.**
+3. Web server: `PUT /api/contrib/<tabId>` route proxying `writeValues` over the
+   bus; contribution descriptors fetched at page load through `/api/contrib`.
+4. Contribution discovery: web host acts as client toward the provider port;
+   tolerate provider disappear/reappear across sessions.
+
+### Subagents-side changes (~1d)
+
+1. Provider endpoint implementing the contribution protocol.
+2. `ForgeSubagentSettings` → schema mapping (backend, timeoutMs,
+   approval flag, summary-in-description flag, per-profile
+   enabled/backend/timeout table).
+3. Server-side re-validation on write, reusing existing validators
+   (`isValidSubagentTimeoutMs` et al.). Never trust the web client.
+4. TUI companion: `/forge-agent config` subcommand for the same settings
+   (internal to the package, no cross-repo coordination).
+
+### Known v1 limitation
+
+Pure schema cannot express "dropdown fed by live forge data" (e.g. a profileId
+picker backed by `listProfiles`). v1: plain text input + validation errors.
+v2 candidate: a "remote data source" field type. Do not gold-plate v1.
+
+### Lane 1B — subagent call-time UX (subagents package only)
+
+Two usability extras that live entirely in `@zihanw/pi-forge-subagents`; no
+forge-side coupling, safe to build in parallel with the forge contribution
+framework.
+
+**1. Call-time model override** (~0.5d)
+
+Main agent may pick the execution model per `forge_subagent` call; default
+remains the profile's model. Feasibility already verified: the wire carries
+model facts (`ForgeBackendFacts.model`, `ForgePrepareResponse.model`), and the
+pi-subagent-runtime subprocess backend already spawns with `--model` — only
+the tool surface lacks the knob.
+
+- Add optional `model` parameter (`provider/id` string, parsed + validated) to
+  `ForgeSubagentParameters`.
+- Resolution order: `model` param > profile default.
+- Same policy as the `backend` param: override allowed for interactively
+  approved runs; unattended invocation is pinned to the profile/configured
+  model.
+- Approval summary's existing `Model:` line shows the effective model for free.
+- Update tool description accordingly.
+
+**2. Restore rich TUI rendering for subagent runs** (~0.5–1d)
+
+The 0.4 tool shipped `renderCall`/`renderResult` (pi-tui Container/Markdown,
+collapsed/expanded states, live progress, usage stats); the 0.5 split dropped
+them, falling back to the default tool display. Streaming infrastructure is
+still intact (`onUpdate` progress pushes, `details.progress` ring buffer at
+`MAX_PROGRESS_ITEMS`).
+
+- Port the 0.4.1 renderers from git history (`v0.4.1:src/subagent-tool.ts`)
+  into `forge-subagent.ts`, adapted to the current details shape and including
+  the approval receipt.
+- `@earendil-works/pi-tui` is already an optional peer dependency.
+- Reference the historical render tests where recoverable.
+
+---
+
+## Lane 2 — Context diff (folded from context-diff-plan.md)
+
+### Goal
+
+Per-turn observability for prompt changes so users can optimize KV-cache reuse:
+
+- Mark which blocks of the prompt changed after each turn.
+- Show token delta (added/removed/modified) vs the previous turn.
+- Mark where the KV-cache prefix survives ("cache boundary").
+
+Secondary goal: merge with live preview — while editing a stack,
+debounce-compile and diff against the previous compile, so edits show their
+prompt/token impact immediately.
+
+### Existing building blocks
+
+- `src/payload-capture.ts` — real provider request payload (secret-redacted),
+  with deliberately rough `approxTokens` (chars/4).
+- Pi's authoritative assistant `message_end` usage — input, output, cache read,
+  and cache write token buckets correlated FIFO with captured provider requests.
+- `src/preview.ts` — edit-time compile output split into sections (system +
+  per-message), each with chars/approxTokens.
+- Legacy editor already polls payload state every 2s.
+
+### Two data sources
+
+| Scenario | Source | Question answered |
+|---|---|---|
+| Edit time (live preview merge point) | debounced compile vs previous compile | "what does this edit change, how many tokens" |
+| Run time (request structure) | diff of consecutive real payloads | "where would the reusable serialized prefix end, and what changed" |
+| Run time (provider truth) | correlated assistant usage | "how many prompt tokens and cache reads/writes did the provider report" |
+
+### Core engine: `src/context-diff.ts` (host-neutral pure functions)
+
+```
+TurnSnapshot  { turnId, capturedAt, stackId, blocks: Block[] }
+Block         { key, role, text, chars, approxTokens, hash }
+TurnDiff      { blocks: DiffBlock[], prefixTokens, prefixRatio, deltaTokens, summary }
+DiffBlock     { status: same|added|removed|modified, before?, after?, tokenDelta }
+```
+
+Cache-boundary algorithm: KV-cache hits depend on the longest common prefix of
+the serialized request. Walk the block arrays in order while hashes match; at
+the first mismatch, trim a char-level common prefix inside that block and
+convert to tokens. Render a boundary marker: "cache valid up to ~18,204 tokens
+(63% of prompt)". No Myers diff needed — prefix + block classification
+suffices.
+
+Honesty note: diff token figures remain chars/4 estimates and are always labeled
+as such. Provider prompt/cache usage is displayed separately. Cache hit rate is
+`cacheRead / (input + cacheRead + cacheWrite)` only after cache activity has
+been observed for that provider/model; an all-zero normalized cache bucket is
+otherwise reported as unavailable because it cannot distinguish a true miss
+from a provider that did not report cache detail.
+
+### UI
+
+Promote the Preview modal into a dockable right-side panel with three tabs:
+
+- **Compiled** — current preview content, auto-refresh with 500ms debounce
+  while editing (this is the live preview).
+- **Draft diff** and **Run diff** — git-style unified/split line views with
+  old/new line numbers, inline changed spans, and selectable changes-only,
+  three-line, or full context. Run metadata keeps estimated reusable prefix
+  separate from actual provider usage and cache-hit rate.
+
+Run-time mode: payload poll captures a new payload → rolling history (last 20
+turns) → auto-compute diff.
+Edit mode: diff current edited compile vs the active on-disk version.
+
+Implementation constraint: self-contained Vue component bridged via the
+vue-host mechanism, riding Lane 1's data-driven dock/tab registry. Do NOT add
+more imperative code to `legacy-editor.ts`. Do NOT refactor the legacy editor
+in the same lane.
+
+### Phases / estimate
+
+| Phase | Content | Effort |
+|---|---|---|
+| 0 | Design freeze + golden fixtures (turn payload sets) | 0.5d |
+| 1 | `context-diff.ts` engine + unit tests (prefix/add/remove/modify/token rollups) | 1d |
+| 2 | Server endpoint + rolling snapshot state on the web host | 0.5d |
+| 3 | Web UI: preview dock + Diff view (self-contained Vue, bridged, on Lane 1's registry) | 1.5d |
+| 4 | Browser tests + docs + changelog | 0.5–1d |
+
+Lane 2 total ~4–5 working days. Descope option (~3d): run-time diff only,
+live preview reduced to plain auto-refresh without edit-time diffing.
+
+---
+
+## Combined estimate
+
+| Lane | Content | Effort |
+|---|---|---|
+| 1 | UI contribution framework (forge) + provider & config UI (subagents) | ~2.5–3d |
+| 1B | Call-time model override + rich TUI restore (subagents only) | ~1–1.5d |
+| 2 | Context diff engine + dock UI | ~4–5d |
+
+~8.5–9.5 working days total, ~2 calendar weeks with review. Both lanes require
+coordinated releases: forge 0.5.1 must understand the contribution protocol
+before (or simultaneously with) subagents 0.5.1 advertising it — the
+capability negotiation makes order-independent rollout safe. Lane 1B lives
+entirely in subagents 0.5.1 and ships with it; the promo should present both
+packages together.
+
+## Release narrative
+
+0.5.1 headlines "observability + subagent UX". The promo video leads with the
+context diff money shot (edit one system-prompt line, watch the cache-boundary
+marker jump). Promo pipeline follows the AIGC/VIDEO_PRODUCTION ep02 reference:
+`PLAN.md` → script draft → `narration.json` → roughcut → review; terminology
+rule: plain words first, formal term named once ("KV cache" on first mention,
+then "prefix cache / cache reuse region").

package/docs/design/architecture-0.5.md

@@ -36,6 +36,15 @@ It is not a platformization release.
 12. **Public surfaces are exactly three intentional entry points:** package root default factory, package root named extension API (`registerMacro`, `registerSlot`, and their contract types), and `@zihanw/pi-forge/subagent`. All other root re-exports and `src/*` aliases are removed. `check-package` enforces this allowlist.
 13. **Migration is a small utility plus release notes, not a framework.** A v1-to-v2 script converts mechanical `variables`/macro fields with explicit diagnostics; removed behavior is never silently approximated.
 
+## Accepted 0.5.1 amendment: generic settings contributions
+
+Dogfooding invalidated decisions 10 and 12 as forward-looking constraints, while preserving their 0.5.0 historical outcome. The accepted 0.5.1 amendment is:
+
+1. `@zihanw/pi-forge/ui-contribution` is a fourth intentional, experimental entry point. It is a generic, versioned, data-only event-bus port; main pi-forge owns the renderer and HTTP proxy but has no subagent-specific schema or persistence logic.
+2. Optional packages may contribute restricted schema-driven Settings pages. Schemas and values are recursively validated JSON data; provider handlers may be asynchronous and receive generation-bound cancellation before side effects.
+3. `pi-forge-subagents` remains the sole owner of both `subagents.json` files. It obtains profile choices only through `/subagent`, contributes plain settings descriptors through `/ui-contribution`, and performs all subagent validation and persistence itself.
+4. This amendment does not authorize a general plugin UI/component runtime, arbitrary browser code, a second resource registry, or main-package reads/writes of optional-package configuration.
+
 ## Extension port contract (0.5.0)
 
 The 0.5.0 extension contract is part of the breaking release. It is a trusted-extension port, not a security boundary.
@@ -77,6 +86,7 @@ flowchart LR
     Workspace --> Compiler["forge-v1 compiler"]
     Compiler --> Extensions["Trusted extension port"]
     Workspace -. "event-bus host port v1" .-> Optional["pi-forge-subagents"]
+    WebEditor["Generic Settings renderer"] -. "UI contribution port v1" .-> Optional
     Optional --> Runtime["pi-subagent-runtime"]
 ```
 
@@ -193,6 +203,7 @@ Lane 4e: release.
 - Schema v2, extension contract, and migration notes are documented.
 - Main package has no subagent runtime dependency and passes packed smoke tests alone.
 - Optional package passes packed smoke tests through host port v1 and owns only its dedicated config files.
+- UI contribution port passes schema validation, async generation cancellation, provider churn, and packed optional-consumer tests.
 - No non-allowlisted root exports or `src/*` aliases remain.
 - User-facing breaking changes are documented in English and Chinese.
 
@@ -205,7 +216,7 @@ These items come from the archived full plan and are intentionally not part of 0
 - automatic dependency-direction checking;
 - full `PromptStackService` / `AgentProfileService` application facades;
 - complete host RPC operation catalogue, progress events, and richer lifecycle features beyond host port v1;
-- optional-package standalone delegation UI or a main-editor contribution port;
+- optional-package standalone delegation UI and arbitrary contributed UI components;
 - full public-surface classification register and consumer audit repeat;
 - rolling Pi compatibility matrix and scheduled latest-Pi probe;
 - sandbox, staged writes, new prompt features, richer imports, and orchestration.

package/docs/design/context-diff-plan.md

@@ -1,7 +1,13 @@
 # Context Diff — design plan (post-0.5.0)
 
-Status: planned. Target release: 0.5.1 (first feature release after 0.5.0).
-Owner of truth: this document; discussion record lives in the 0.5.x review thread.
+Status: folded into `docs/design/0.5.1-plan.md` as Lane 2 — that file is now the owner of truth. Kept for discussion history.
+
+Implemented follow-up: the dock now provides git-style line diffs and correlates
+captured requests with Pi's assistant usage. The structural cache-prefix figure
+remains a chars/4 estimate; provider-reported cache hit rate is shown separately
+and is unavailable until cache reporting is observed for that provider/model.
+
+Original status: planned. Target release: 0.5.1 (first feature release after 0.5.0).
 
 ## Goal
 

package/docs/development/release.md

@@ -6,12 +6,18 @@
 
 1. Confirm the changelog and user documentation describe the intended version and experimental surfaces accurately.
 2. Publish and smoke-test any required `@zihanw/pi-subagent-runtime` version first.
-3. Install dependencies from the lockfile and run `npm run verify`.
+3. Install dependencies from the lockfile and run `npm run verify`; require the
+   Ubuntu, macOS, and Windows GitHub Actions jobs to pass for the release commit.
 4. Test a packed installation against the documented minimum and current Pi versions.
 5. Exercise ordinary stack/profile use independently of delegation.
 6. Exercise both configured foreground backends and confirm unsupported host capabilities fail closed before provider transport.
 7. Inspect `npm pack --dry-run` for package size and unexpected or missing files.
 
+The macOS and Windows jobs run the same complete verification surface as Linux,
+including the real-browser editor suite against the hosted runner's system
+Chrome. Compatibility-version and scheduled latest-Pi probes remain Linux-only;
+they test dependency drift rather than operating-system behavior.
+
 ## Dependency policy
 
 Published manifests use wildcard peer dependencies for Pi-host-provided SDK packages. Exact versions belong in development dependencies and the lockfile so tests are reproducible without restricting compatible host releases.

package/docs/guides/delegation.md

@@ -15,11 +15,11 @@ Profiles are not delegatable by default. Enable each eligible ID in the trusted
   "backend": "pi-subprocess-readonly",
   "timeoutMs": 60000,
   "profiles": {
-    "reviewer": {
+    "project:reviewer": {
       "enabled": true,
       "timeoutMs": 300000
     },
-    "rpc-reviewer": {
+    "project:rpc-reviewer": {
       "enabled": true,
       "backend": "pi-rpc-readonly",
       "timeoutMs": 180000
@@ -28,7 +28,7 @@ Profiles are not delegatable by default. Enable each eligible ID in the trusted
 }
 ```
 
-Legacy `.pi/forge/config.json.subagents` is accepted as read-only fallback with a warning. Enablement follows the profile's scope. A global `~/.pi/forge/subagents.json` may define general `backend` and `timeoutMs` defaults and may authorize `global:<id>` profiles through its own `profiles` map. The trusted project's `subagents.json` authorizes `project:<id>` profiles. Same-ID global and project profiles never inherit enablement, backend, or timeout policy from one another. Disabled or unlisted profiles are hidden from discovery and rejected even if guessed.
+Legacy `.pi/forge/config.json.subagents` is accepted as read-only fallback with a warning. Authorization keys should be canonical selectors: `project:<id>` or `global:<id>`. Bare keys remain a compatibility spelling for project profiles only, even inside `~/.pi/forge/subagents.json`; use an explicit key such as `global:reviewer` to authorize a global profile. Same-ID global and project profiles never inherit enablement, backend, or timeout policy from one another. Disabled or unlisted profiles are hidden from discovery and rejected even if guessed.
 
 ## Discover, plan, and run
 

package/docs/guides/web-editor.md

@@ -43,7 +43,7 @@ The stack workspace provides:
 - payload arming and redacted captured-payload inspection;
 - light and dark themes.
 
-Existing IDs are immutable during edit. Use **Fork** to create a different ID without breaking profile references or the active selection. The toolbar scope selector (default `project`) chooses where new stacks, imports, and forks are written: `global` targets the user-global `~/.pi/forge/prompt-stacks`, `project` targets `.pi/forge/prompt-stacks`. Stack rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy stacks remain editable in place.
+Existing IDs are immutable during edit. Use **More → Fork** to create a different ID without breaking profile references or the active selection. The compact selector attached to **New stack** (default `Project`) chooses where new stacks, imports, and forks are written: `Global` targets the user-global `~/.pi/forge/prompt-stacks`, `Project` targets `.pi/forge/prompt-stacks`. Less-used capture, fork, import, export, and delete actions live under **More** so the stack and Preview/Diff panes keep the available viewport. Stack rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy stacks remain editable in place.
 
 Saves, imports, forks, and deletes reload stack state into the current Pi session. When another surface changes a referenced stack, returning to profiles refreshes profile resolution.
 

package/docs/reference/commands.md

@@ -49,7 +49,7 @@ The commands below are provided by the optional `@zihanw/pi-forge-subagents` pac
 | `/forge-agent plan <profile> [--backend <id>] <task>` | Prepare, validate, display, and discard an exact plan without provider transport. |
 | `/forge-agent run <profile> [--backend <id>] <task>` | Review and approve an exact foreground read-only run. |
 
-Only profiles explicitly authorized in the matching scope are accepted: the project `subagents.json` authorizes `project:<id>` profiles and the global `subagents.json` authorizes `global:<id>` profiles; `.pi/forge/config.json.subagents` remains a read-only legacy fallback. The model-callable equivalents are `forge_subagent_profiles` (local discovery) and `forge_subagent` (execution). See the [delegation safety guide](../guides/delegation.md).
+Only explicitly scoped profiles are accepted: use `project:<id>` or `global:<id>` keys in `subagents.json`. A bare authorization key always means `project:<id>`, even in the global file; `.pi/forge/config.json.subagents` remains a read-only legacy fallback. The model-callable equivalents are `forge_subagent_profiles` (local discovery) and `forge_subagent` (execution). See the [delegation safety guide](../guides/delegation.md).
 
 ## Payload inspection
 

package/docs/reference/configuration.md

@@ -38,7 +38,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 +51,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/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

@@ -95,7 +95,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.
 

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

@@ -27,7 +27,7 @@ Prompt stack 是一份有序、声明式的 prompt 与策略描述，由固定 *
 
 ## 策略边界
 
-工具 `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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zihanw/pi-forge",
-	"version": "0.5.0",
+	"version": "0.5.1",
 	"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": [