@zihanw/pi-forge 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -6,6 +6,89 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 In 0.x development, breaking changes may occur in minor releases and will be explicitly noted.
 
+## [Unreleased]
+
+## [0.5.6] - 2026-09-27
+
+- Make disabled Block/Slot rows visibly neutral as a whole: muted titles, gray side markers and a distinct background remain disabled-looking even when selected. Keep On/Off controls readable and preserve toggle focus for repeated Space/Enter operation.
+- Allow dragging the right edges of the Presets and Stack items panes to adjust their widths, with browser-local preferences, keyboard adjustment and double-click reset. Constrain widths to leave editing space and retain narrow-screen stacking; resizing does not change or save Preset drafts.
+
+- Keep Pi's incoming initial System message and its tool declarations at index zero when a Preset places authored messages before explicit or implicit history. Later System updates and Preview provenance remain ordered.
+- Confirm before discarding an unsaved Preset draft on import; preserve newer edits during file reading, resource creation, and reload. Reload reuses a discard confirmation only for the exact confirmed draft revision.
+- Disable Agent Profile draft controls while Save or Validate is pending, preventing edits from being lost when a successful save closes the editor.
+- Preflight surviving Capability tool patches against a prospective Preset before changing selection or retiring bound activations. Conflicting switches leave the current session unchanged and explain how to resolve the conflict; Web activation returns a conflict response. Create-and-activate discovers the new file without selecting it before this check.
+- Apply the same Capability conflict preflight before saving or overwriting the active Preset's live policy. A rejected write returns a conflict without modifying the file or session; inactive resource editing and frozen activation snapshots are unchanged.
+- Report the actual preflight diagnostics for a single invalid auto-activate Profile instead of incorrectly reporting multiple candidates; scope precedence and fail-closed activation are unchanged.
+
+## [0.5.5] - 2026-09-26
+
+- **New Preset templates:** choose the existing Default Pi prompt, an Empty preset, or Minimal Worker. Empty keeps compiler base-prompt/history fallbacks; Minimal Worker matches the bundled bash/edit example. Template choice does not affect Import/Fork or persist as a schema field.
+- **Capability completion consistency:** unique IDs complete without a scope prefix, while collisions and explicit scope prefixes stay qualified; labels retain resource provenance.
+
+- **Breaking Capabilities rename:** Instruction modes are now Capabilities. Use `/capability` with `add`, `list`, `bindings`, `enable`, `enable-bound`, `disable`, `status`, `reset`, and `help`; the Agent tool is `forge_capability` with `list`, `status`, `enable`, and `disable`. Existing development configs must convert to `capabilities` resources and new sessions; old directories, schemas, aliases, and continuing capability state are not supported. This is a breaking compatibility boundary, not a compatibility claim for older published configurations.
+
+- **Session prompt-cache usage:** document read-only branch prompt-cache hit rates (turn and session) derived from persisted message usage, separate main vs nested reporting, and the experimental v1 `toolResult.details.forgeNestedUsage` contract.
+- **Current session workspace:** capability/tool controls beside the runtime projection; preserve the separate Preset editor and Preview/Draft diff/Run diff reading state. Quiet background state polling no longer repeatedly reloads the catalog or disables controls. Late reads cannot overwrite a newer visit; navigation retains in-flight mutation receipts.
+- **Reviewed documentation and examples:** adopt bilingual README B and continuous Context/Capability/Draft diff media. Add the small Read-first Worker + Write tools pair: default reading, explicitly authorized model-selected `bash`/`edit`, and documented non-sandbox/ownership limits.
+- **CLI naming:** document `/forge ui`, `/forge payload`, and optional `/forge subagent plan` as the recommended Forge commands; `/capability` is the capability command. `/preset` and `/profile` roots are unchanged. The legacy `/subagent` smoke helper remains distinct from the `/forge subagent` execution-plan command.
+- **Payload capture boundaries:** document `next save="path with spaces.json" [--overwrite]`, `status`, and `cancel`; capture is taken at `before_provider_request`, does not itself call a model, and does not overwrite without the explicit flag. Cancellation only clears pending capture state, not retained history.
+- **Command-contribution source surface:** Forge 0.5.5 provides the intentional `@zihanw/pi-forge/command-contribution` entry from `src/command-contribution/index.ts`: synchronous local discovery, callback metadata, explicit unsubscribe, main-owned `/forge` root, and fail-closed duplicate children. It has no singleton registry, persistent format, or authorization boundary. The optional package remains an independent upcoming release and must raise its Forge dependency floor to `^0.5.5`; no optional publication is implied here.
+- **Provider support snapshot:** add bilingual docs recording, for Pi 0.87.1, how each API sends mid-conversation system updates and tool changes, which catalog models were flagged, and observed cache behavior. README and the capability reference explain that the current model's catalog flags choose native or fallback delivery.
+- **Delegation distinction:** document that `/forge-agent run` always requests approval and may write through its backend, while model-callable `forge_subagent` unattended authorization is separate.
+
+- Tool-only Capabilities (empty or whitespace-only text) no longer project an empty instruction update, removal notice, or compaction checkpoint section in native or fallback delivery; their tool changes are unchanged. Current session hides Locate for them, and the Agent `enable` reply says no instruction text is sent.
+- Preserve Capability edits made during a pending create/save or subsequent catalog refresh; follow-up saves use the exact write's revision receipt. Cancelling a pending refresh releases its busy state.
+- Persist the original tool baseline for `tools.initial`-only Presets, so rebuilding from a filtered tool set can still restore that baseline when the Preset is disabled.
+- Retain a continuous suffix of ordinary history under `maxChars`, while continuing to preserve necessary instruction control messages beyond the trimming boundary.
+- Keep Preview panel width/focus unchanged when switching Preview, Draft diff and Run diff. Focused reading is entered explicitly.
+- Specify that `tools.initial` delegation requires the matching optional subagents fix; the explicitly published optional 0.5.3 build cannot validate this selection. This is an optional-package compatibility gate, not a gate on the main Forge 0.5.5 release. See the host-port compatibility note.
+
+
+- **On-demand tool loadouts:** Presets can opt into `tools.initial` (concrete tool names; `[]` means zero defaults). Omission preserves legacy behavior; existing allow/deny remains the hard ceiling. Authorized capabilities add permitted registered tools, and disable/reset recomputes from defaults plus remaining capabilities. Live execution, Preview and subagent preparation agree; source edits never replace frozen capability snapshots. Older Forge readers do not understand this new selection field.
+- **Source-grouped tool selection and binding UX:** One searchable, collapsible picker batches the current extension/source tools into ordinary literal tool-name arrays; no permanent package bindings or automatic future-tool grants. Preset bindings move out of metadata to a peer **Capability bindings** tab, with overrides/source-effective details collapsed. Default-tool selection is opt-in. Cross-preset draft ownership, authoritative scoped identity, resource response ordering and baseline-vs-capability default seeding are guarded. Saving a capability never activates it; saving an active Preset refreshes that Preset's policy. Catalog refresh preserves literal selections without auto-selecting new package members; payload polling ignores obsolete responses after a newer capture or mutation.
+
+
+### Added
+
+- **Capabilities and session update CLI.** Session-scoped dynamic capabilities and manual directives via `/capability` (`add`, `list`, `bindings`, `enable`, `enable-bound`, `disable`, `status`, `reset`). Capabilities are stored as JSON definitions (`schemaVersion: 1`, `type: "pi-forge.capability"`) under `.pi/forge/capabilities/` or `~/.pi/forge/capabilities/`. Direct `enable` enables an unbound capability; `enable-bound` enables an authorized Preset binding.
+- **Preset capability bindings.** Declarative `capabilities` configuration in Presets supporting qualified capability references (`project:<id>`, `global:<id>`), unique binding IDs (control calls accept IDs ≤128 chars), opt-in Agent authorization (`modelCallable: boolean`), and finite overrides (content replacement or paragraph append with two newlines; tool additions/removals array replacement or explicit empty clear).
+- **Restricted model-callable Agent control.** The `forge_capability` tool accepts only `{ action: "list" | "status" | "enable" | "disable", id?: string }` (ID ≤ 128 chars). It rechecks project trust, active Preset, binding identity, `modelCallable: true`, and current tool policy on every call. The Agent cannot stop human-owned rules, reset, add arbitrary rules, or disable `forge_capability`. Repeated use is idempotent and never performs automatic owner takeover.
+- **Web editor Capabilities surface (CRUD).** Dedicated bilingual Capabilities surface for creating, editing, and deleting scoped capability files in project and global libraries. Operations require `sourceRevision` checking against raw file bytes; 409 Conflict on stale views preserves local drafts. Capability saves never activate definitions in the session.
+- **Preset Capability bindings editor.** Dedicated peer tab in the Preset editor for configuring qualified references, binding IDs, `modelCallable` toggles, and finite overrides, with live side-by-side source vs effective preview resolved through the shared server resolver.
+- **Web session capabilities activity panel and human activation picker.** Non-modal Current session workspace reached from navigation or the global summary, pairing capability/tool controls with the active saved Preset/session projection for inspecting active session capabilities, actor attribution (`user`/`agent`), collapsible frozen snapshots, tool deltas, effective tools, delivery status (`none`, `pending`, `prepared`), and presentation mode. Includes a guarded human activation picker with available capability choices (`GET /api/capability-state/available`) and guarded activation (`POST /api/capability-state/enable`) requiring session/leaf/revision and content fingerprint validation, rejecting stale state (409 Conflict) without automatic retry or inference.
+- **State concurrency guarding and conservative polling.** The Web panel polls `GET /api/capability-state` every 3 seconds only while visible, upon window focus, or via manual refresh without LLM inference. Web mutations require project trust (`isProjectTrusted()`), returning 403 on untrusted sessions with CLI recovery retained. Mutation requests enforce derived guards (`sessionId`, `leafId`, `revision`, runtime generation) to reject stale browser views (409 Conflict); errors and conflicts halt mutations for manual review rather than blindly retrying.
+- **Local execution without inference.** Capability operations (`/capability` and Web activity panel actions) execute locally without invoking LLM inference or consuming paid API tokens. Active instruction text continues to consume input tokens on subsequent model requests when inference occurs. Read-only resource discovery and Preview never mutate tool policy, commit session events, or mark pending capabilities prepared.
+- **Request-boundary tool and prompt synchronization.** Immediate executable tool synchronization (`setActiveTools`) pairs with next-request prompt text and SystemMessage section or user update delivery. Running tool batches are not interrupted mid-flight. Capability definitions are captured as immutable snapshots, preventing disk drift.
+- **Pure metadata capability delivery anchors.** Delivery markers are stored as plain `custom` session entries using the same delivery type (`pi-forge-capability-delivery`) carrying strictly cursor-only metadata (`schemaVersion: 1`, `throughEventId`). They replace previous `sendMessage` steering and dialogue-polluting `custom_message` carriers. Anchors are committed immediately when idle, deferred safely until running tool batches complete, or committed at `agent_end` after the assistant's final response when no Forge context failure or incomplete batch remains, without enqueueing an extra model turn. UI status notifications (`ctx.ui.setStatus`) are decoupled and never enqueue turns to the model.
+- **Pre-compilation ordinal materialization and rule projection.** Context assembly (`prepareCapabilityMessages`) materializes before Preset compilation plain metadata anchors into ephemeral in-memory markers at their exact ordinal session positions before rules are projected (`projectCapabilityMessages`) into request-only native `SystemMessage.sections` or fallback attributed user updates.
+- **Parent safeguards.** Enforce raw source/revision coherence (GET returns editable data and revisions from same raw bytes), external new bindings stale-save detection on binding-bearing Preset saves, and lifecycle/re-entry fences (`disposed`, `lifecycleRevision`, `sameContext`) blocking cross-session pollution or operations after session disposal.
+- **Fail-closed extension rewrite protection.** Preceding extension message rewrites are a legitimate Pi SDK capability, but because Forge requires unique ordered correspondence between session context entries and incoming context messages, incompatible or ambiguous preceding rewrites cause Forge to fail closed safely rather than misattributing anchors. Users may adjust extension order or behavior as an operational workaround; Forge does not guarantee post-extension rewrite safety, generic plugin compatibility, prompt cache retention, warming, or automatic overflow handling.
+- **Breaking pre-release session boundary.** Former instruction-mode delivery carriers and continuing capability state have no compatibility reader. Forge does not rewrite old JSONL or historical summaries; convert configuration and start a new session.
+- **Session event recovery and branch coherence.** Semantic events and derived delivery cursors enable state reconstruction across session reloads, manual compaction checkpoints, and tree branch navigation, verified offline via local SDK test harnesses.
+- **Fail-closed shadowing and literal rule isolation.** Bare capability selectors resolve project-over-global; invalid local capability definitions fail closed rather than falling back to global. Content is evaluated strictly as literal text without macro or script execution.
+
+### Fixed
+
+- **Node 22 nested-test lifecycle and portable permission fixtures.** Parent tests now await nested `t.test` calls so Node 22 does not cancel unfinished children. Targeted EACCES/EPERM fixtures replace non-portable `chmod` assumptions without dropping permission-error assertions.
+- **Windows browser fixture serialization.** Browser fixture imports are serialized and Windows path handling is normalized so cross-platform fixture tests do not depend on platform-specific module paths.
+
+- **Empty capability binding catalog.** Adding a Preset binding no longer invents an `unavailable-UUID` reference when no eligible capabilities exist. Global Presets remain limited to global capabilities. Loading, catalog errors and known-invalid definitions disable Add without dirtying the draft; bilingual empty-state guidance, retry and refresh support creating a capability in the library and updating source/effective previews. Existing missing references remain visible for explicit repair.
+
+- **Keep Agent inspection replies out of rule-body history.** `forge_capability` list/status return identities, authored descriptions, ownership and tool/status metadata, not copies of full instruction bodies. Rules remain request-only projections; human CLI/Web inspection still shows full snapshots. Real SDK control-call and summarizer tests cover the distinction. Genuine dialogue or descriptions quoting rules are not stripped.
+
+### Changed
+
+- **Preview text/metadata separation.** Keep actual System prose and named-section values separate from historical tool declarations; show draft-relative selected tools independently, hide only genuinely empty projected System cards, and retain structural-only changes in Draft diff. After the final overlay is stopped, tool previews use the restored live selection rather than captured filtered options. Text estimates exclude tool schemas. Group only consecutive history runs so intervening instruction updates retain their chronological position.
+- **Capability-aware Preview.** Compile the selected Preset draft with current session capability snapshots using the existing pure projection. Render native sections, stop notices and tool declaration changes; do not leak cursor-only metadata anchors or mark previewed instructions prepared. Preserve message provenance/order and remove the 8,000-character copy-text cutoff. Existing summaries and compaction behavior are unchanged.
+- **Tool policy coordination and boundaries.** Active capabilities participate in Forge's single tool-policy runtime: additions are subject to top-level Preset deny policies, removals take global priority across active capabilities, and session baseline tools are restored conservatively upon disable. Capabilities support `add` and `remove` ONLY; candidate `only`/allowlist is not implemented.
+- **Provider-managed cache warning.** Prompt caching and tool transport are downstream provider-managed; conservative warnings apply without promises of zero KV cache invalidation or exact cache hits.
+- **Upstream Pi 0.87 migration.** Forge now runs its full compiler/base/capability pipeline in `context_with_system`, because ordinary `context` hooks no longer receive System messages. Live anchor placement and read-only Preview use canonical `buildSessionProjection`, including context-edit omissions/replacements and branch provenance; raw history remains unchanged. Idle prefix anchors stay after the incoming leading System. Compile inputs survive low-level `agent_end` and clear only at `agent_settled`, preserving Presets during `agent_before_settle` continuations. Real SDK regressions also cover automatic retry omissions with pending rules and original history retained.
+- **Supported Pi line: 0.87.x.** All four host-provided optional Pi peers now require `>=0.87.0 <0.88.0`; development and packed-install checks use 0.87.0. Pi 0.86 is no longer supported by this development slice, and future minor versions are not implicitly accepted. Forge 0.5.5 requires this range; OMP compatibility is not promised.
+
+### Note
+
+- **0.5.5 functional source delivery.** Functional source is delivered across all planned main-package lanes: foundation codecs, human CLI core, plain metadata anchors, Web Session capabilities panel and human activation picker, live Preset bindings, restricted Agent control (`forge_capability`), Web Capabilities CRUD, Preset binding editor with finite overrides, and parent safeguards (raw source/revision coherence, external new bindings stale-save detection, lifecycle/re-entry fences). Compaction checkpoints remain placed after the leading system prompt and before summary (placement unchanged; the upstream Pi metadata chunking bug remains independent and unfixed). SDK summarization input characterization confirms summarizers observe user, assistant, and peer dialogue without metadata anchors or request-only Forge rule text, characterized offline with fake test responses that do not constitute remote LLM semantic validation. Local build and full verification passed at the accepted 2026-09-24 UI closeout (`89c6ba2`), without claiming a remote-provider matrix; release verification is tracked separately. These results do not imply remote-provider acceptance or optional-package/runtime publication.
+
 ## [0.5.4] - 2026-09-12
 
 ### Added

package/README.md

@@ -1,159 +1,123 @@
 # pi-forge
 
-[English](README.md) | [简体中文](README.zh-CN.md) · [Documentation](docs/README.md)
+[English](README.md) | [简体中文](README.zh-CN.md) · [Documentation](docs/README.md) · [Quick start](#install-and-first-run)
 
-![pi-forge header](https://raw.githubusercontent.com/MacroSony/pi-forge/main/assets/pi-forge-header-concept-1.png)
+![pi-forge - Context editor and inspection workbench for Pi](assets/pi-forge-header-concept-1.png)
 
-**pi-forge** lets you customize how [Pi](https://github.com/badlogic/pi-mono) thinks and behaves. Presets bundle an ordered prompt Stack with tool/skill policy, Regex, and parameters; agent profiles apply a model, thinking level, and Preset as a reusable one-shot configuration.
+**A context editor and inspection workbench for Pi.**
 
-Think of it as a character sheet and workbench for your AI agent.
+pi-forge provides visual context composition, tool selection, reusable configurations, and request inspection for [Pi](https://github.com/earendil-works/pi).
 
-## Highlights
+> Inspired by SillyTavern’s presets, I built pi-forge to customize both what goes into an agent’s context and how it is assembled—and inspect what actually reaches the model.
 
-- Compose Pi's system prompt, conversation history, tools, skills, project context, and runtime data as ordered blocks and slots.
-- Switch between coding, reviewing, writing, roleplay, and translation modes with one command.
-- Save and apply complete model/thinking/Preset profiles.
-- Enforce per-Preset tool policy and filter model-visible skills.
-- Use immutable Preset `parameters` with the deterministic forge-v1 template engine.
-- Apply deterministic regex transforms to outgoing prompts or finalized assistant messages.
-- Edit Presets and profiles in a local browser UI and inspect the exact provider payload.
-- Inspect prompt changes in the Preview dock: **Preview** compiles the live draft, **Draft diff** compares unsaved edits with disk, and **Run diff** compares recent provider turns. Git-style unified/split views include old/new line numbers, inline highlights, and changes-only/three-line/all-line context. Run metadata keeps chars/4 estimates separate from Pi's provider-reported prompt/cache usage and real cache-hit rate.
-- Run an explicitly enabled profile as an experimental, approval-gated foreground subagent.
+[Context composition](#context-composition) · [Tool selection](#tool-selection) · [Regex transformations](#regex-transformations) · [Capabilities](#dynamic-system-prompts-and-tools) · [Request inspection](#preview-and-request-inspection)
 
-## Install
+> **Optional subagents**: [pi-forge-subagents](https://github.com/MacroSony/pi-forge-subagents) — Delegate tasks to agents with their own model and preset.
 
-pi-forge requires Node.js 22.19 or newer.
+## Install and first run
+
+Requires Node.js **22.19 or newer**. The 0.5.6 line supports Pi **0.87.x** (`>=0.87.0 <0.88.0`), tested with **0.87.0**.
+
+> **Version note:** This README describes Forge **0.5.6**. Capabilities and configurable default tools require 0.5.5; optional subagents have a separate [compatibility requirement](docs/reference/subagent-host-port.md#tool-selection-compatibility).
 
 ```bash
 pi install npm:@zihanw/pi-forge
 ```
 
-Restart Pi after installing or updating the extension. Pi supplies its SDK packages to extensions at runtime; pi-forge keeps exact Pi versions only for reproducible development and tests. See [compatibility and setup](docs/development/setup.md#pi-compatibility) for the supported/tested policy.
+Restart Pi after installing or updating. In a trusted project:
 
-## Five-minute start
+1. Run `/forge ui` to open the local editor.
+2. Choose **New preset** to start from the default Pi-mirror layout.
+3. Edit a block or policy and check **Preview**.
+4. **Save** your changes, then **Activate** the Preset for the current session.
 
-### 1. Create a Preset
+Prefer the terminal? Select a Preset with `/preset use <id>` and enable a Capability with `/capability enable <capability>`. Try the [Read-first Worker example](docs/reference/capabilities.md#read-first-worker) yourself.
 
-Create the `default` Preset from [the default Pi mirror](examples/default-prompt-stack.json). The compatibility storage path remains `.pi/forge/prompt-stacks/default.json` in 0.5.3:
+## Features
 
-```bash
-mkdir -p .pi/forge/prompt-stacks
-cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
-```
+### Context composition
 
-If you installed from npm rather than cloning this repository, open `/preset ui` and create a new Preset; the editor starts with the same Pi-mirror layout.
+Build your agent’s context from editable text blocks and slots for tools, skills, project files, and conversation history. Reorder or toggle them and see the result in Preview.
 
-Restart Pi or run:
+- **Use case**: Give a code-review agent your project guidelines and selected context, instead of keeping one oversized prompt for every task.
+- **Try it**: In the editor’s **Stack**, edit or drag a block, toggle project context, and check **Preview**.
 
-```text
-/preset reload
-/preset use default
-```
+![Drag system blocks to reorder them, then toggle project context; Preview follows](assets/readme/en/context-composition.gif)
 
-`default.json` auto-activates when no Preset or restored session selection takes precedence.
+See [Web editor guide](docs/guides/web-editor.md) and [Stack schema](docs/reference/stack-schema.md).
 
-### 2. Open the visual editor
+### Tool selection
 
-```text
-/preset ui
-```
+Choose which tools an agent may use and which are available by default. An allowlist or denylist sets the permission limit; a smaller default set keeps other permitted tools available for Capabilities to enable later.
 
-The local editor can create, fork, validate, preview, import, export, and delete Presets. Its **Agent profiles** view manages one-shot model/thinking/Preset bundles. Writes require a trusted project. When `@zihanw/pi-forge-subagents` is installed, its schema-driven editor appears on the separate top-level **Settings** surface and persists to the optional package's `subagents.json` files.
+- **Use case**: Keep a review agent focused on reading and searching, without giving it editing or shell tools.
+- **Try it**: In **Policy**, choose the permitted tools and a default set such as `read` and `ls`. Add the already-permitted `grep` to the defaults and check the tool list in **Preview**; save and activate to apply the policy.
 
-### 3. Save a profile
+![Tool selection with policy defaults read/ls and adding grep](assets/readme/en/tool-selection.gif)
 
-Configure Pi normally, then capture and reuse the current settings:
+See [Tool policy reference](docs/reference/stack-schema.md#tool-and-skill-policy).
 
-```text
-/profile save reviewer
-/profile use reviewer
-```
+### Regex transformations
 
-A profile applies once. Later manual changes to the model or thinking level remain in effect until the profile is applied again; an active Preset continues enforcing its tool policy.
+Find and replace text in model input or completed assistant/tool output using reusable regex rules.
 
-## The basic model
+- **Use case**: Replace a known sensitive marker in selected prompt text before sending it, or clean repetitive boilerplate from responses.
+- **Try it**: In **Regex**, set up an outgoing rule matching the synthetic `SAMPLE_TOKEN`, replacing it with `[REDACTED]`, and targeting system text. The demo toggles this preconfigured rule and compares **Preview**.
 
-A **Preset** is one JSON document. Its ordered composition section is the **Stack**:
+![Regex transformation redacting outgoing synthetic SAMPLE_TOKEN](assets/readme/en/regex-transforms.gif)
 
-| Stack item | Purpose |
-|---|---|
-| **Block** | Static `system`, `user`, `assistant`, or hidden `custom` text |
-| **Slot** | Runtime content such as tools, skills, project context, date/cwd, or chat history |
+See [Regex transformation reference](docs/reference/stack-schema.md#regex-transforms).
 
-The Preset also carries system mode (`replace`, `append`, or `prepend`), tool/skill policy, Regex, parameters, and extension references. During compilation, pi-forge expands the Stack, compiles forge-v1 templates over `runtime.*` / `parameters.*` / `extensions.*`, enforces tool policy, filters its skill listing, and applies enabled Regex rules.
+### Dynamic system prompts and tools
 
-Agent profiles reference an exact provider/model, thinking level, and Preset. They intentionally do not duplicate tool or skill policy—the referenced Preset remains the source of truth.
+**Capabilities** update system instructions and available tools mid-conversation. Start an agent with minimal tools, then let it load task-specific instructions and tools when needed—without restarting the session or switching Presets.
 
-> **0.5.3 compatibility note.** User-facing terminology now follows Preset → Stack. Storage and schema identifiers remain backward-compatible in this patch: `.pi/forge/prompt-stacks/`, `"pi-forge.prompt-stack"`, profile field `promptStack`, `/api/stacks`, and internal `PromptStack` type names are unchanged. See the [roadmap](docs/development/roadmap.md) for the later storage/schema migration.
+- **Use case**: Let an agent explore code with `read` and `ls`, then enable an authorized editing Capability when it is ready to apply a fix.
+- **Try it**: Create a Capability in **Capabilities** and authorize agent access in the Preset’s **Bindings** tab. You can also enable it yourself in **Current session** or with `/capability enable <capability>`, and inspect the resulting instructions and tools.
 
-Start with these examples:
+Updates reach the model as native mid-conversation system updates on supported models, with a labeled user-message fallback otherwise (see [delivery details](docs/reference/capabilities.md#delivery-models-native-vs-fallback)).
 
-- [Default Pi mirror](examples/default-prompt-stack.json) keeps normal Pi behavior while making its sections movable.
-- [Minimal worker](examples/minimal-prompt-stack.json) borrows the DeepSeek Harness Minimal shape using stock Pi tools: the exact one-line persona, chat history, and only `bash` plus `edit`, without replicating DSH shell/editor semantics.
-- [Regex hack pack](examples/hack-prompt-stack.json) demonstrates request-frequency outgoing redaction plus transcript-finalize scrubbing for two illustrative token shapes; it is not an exhaustive secret scanner.
-- [Custom system-status extension](examples/custom-system-status-extension/README.md) registers a trusted macro and slot.
-- [Fake-assistant direct-output experiment](examples/fake-assistant-direct-output-prompt-stack.json) appends ordinary assistant text after chat history to test a model-specific reasoning shortcut; support varies by model/provider/endpoint and must be verified with an A/B run.
+On supported provider/model combinations, adding or removing tools can preserve the cached prompt prefix. Support differs for additions and removals, and cache hits are not guaranteed; see [provider support and cache observations](docs/reference/provider-support.md#observed-cache-behavior).
 
-## Common commands
+![Enable and locate Explore capability: tools and instruction changes together; Disable restores read and projects a removal](assets/readme/en/capability-tools.gif)
 
-| Command | Purpose |
-|---|---|
-| `/preset ui [stop\|restart]` | Open or manage the web editor |
-| `/preset list` | List Presets |
-| `/preset use <id\|none>` | Select or disable a Preset |
-| `/preset preview [id]` | Compile a Preset without sending a request |
-| `/preset validate [id]` | Validate one Preset or all Presets |
-| `/preset diagnostics` | Show runtime and extension diagnostics |
-| `/profile list` | List and preflight profiles |
-| `/profile save <id> [--overwrite]` | Capture the current runtime as a profile |
-| `/profile use <id>` | Preflight and apply a profile once |
-| `/profile status` | Show last-applied provenance and runtime drift |
-| `/payload next [save=<path>]` | Inspect the next redacted provider payload |
+See [Capabilities reference](docs/reference/capabilities.md).
 
-See the [complete command reference](docs/reference/commands.md).
+### Preview and request inspection
 
-## Experimental foreground delegation
+See what your edits change before calling a model, then inspect captured requests and reported usage when debugging a run.
 
-The optional `@zihanw/pi-forge-subagents` package provides foreground delegation on top of pi-forge's `/subagent` host port. The model can discover eligible profiles with `forge_subagent_profiles` and invoke one with `forge_subagent`; humans use `/forge-agent plan` and `/forge-agent run`.
+- **Use case**: Check whether a prompt edit adds the intended instructions, or compare successive requests when a run behaves differently than expected.
+- **Try it**: In `/forge ui`, switch to **Preview** to view compiled messages, open **Draft diff** to see unsaved changes, or run `/forge payload next` in the terminal to inspect the next outgoing request.
 
-This feature is **experimental** and profiles are not delegatable by default. Enable each profile in the trusted project's `.pi/forge/subagents.json` (or the optional package's read-only legacy fallback in `.pi/forge/config.json.subagents`). Interactive execution presents an immutable plan for approval unless the project explicitly authorizes unattended model invocation.
+![An unsaved instruction change compared with the saved Preset](assets/readme/en/edit-draft-diff.gif)
 
-> **Security boundary:** The current backends are shared-user processes, not operating-system sandboxes. “Read-only” describes the model-visible tool policy. The child retains the invoking user's OS read permissions, and readable content may be sent to the selected provider and retained in Pi's session data. Timeout and cancellation are best effort, and `/tree` cannot undo provider requests, billing, or external effects.
+**Current session** also shows turn and branch cache-hit rates, with main-model and reported nested-tool usage kept separate. These are recorded usage metrics, not a complete bill. See [cache usage](docs/reference/session-cache.md), [debugging](docs/guides/debugging.md), and [commands](docs/reference/commands.md).
 
-Read [foreground delegation and its safety model](docs/guides/delegation.md) before enabling it.
+## Examples
 
-## Documentation
+- [Default Pi mirror](examples/default-prompt-stack.json) — A Pi-style starting point, split into editable blocks and runtime slots.
+- [Minimal worker](examples/minimal-prompt-stack.json) — One line of instructions, chat history, and only `bash` plus `edit`.
+- [Read-first Worker](examples/read-first-worker-prompt-stack.json) + [Write tools capability](examples/capabilities/write-tools.json) — Start with `read`, `ls`, and the capability control tool; let the model enable `bash`/`edit` on demand. [Setup and limits](docs/reference/capabilities.md#read-first-worker).
+- [Regex examples](examples/hack-prompt-stack.json) — Outgoing redaction paired with stored-transcript cleanup for two sample token patterns.
 
-### Learn
+Save your current model, thinking level, and Preset as an Agent Profile with `/profile save reviewer`; restore it with `/profile use reviewer`. See [patterns and use cases](docs/guides/use-cases.md) for more ideas.
 
-- [Getting started](docs/getting-started.md)
-- [Migrating to 0.5](docs/guides/migrating-to-0.5.md)
-- [Prompt-stack concepts](docs/concepts/prompt-stacks.md)
-- [Agent-profile concepts](docs/concepts/agent-profiles.md)
-- [Web editor](docs/guides/web-editor.md)
-- [Prompt-stack patterns and examples](docs/guides/use-cases.md)
-- [Custom macros and slots](docs/guides/custom-macros-and-slots.md)
-- [Prompt and payload debugging](docs/guides/debugging.md)
+## Optional subagents
 
-### Reference
+The optional companion [`pi-forge-subagents`](https://github.com/MacroSony/pi-forge-subagents) package lets your agent delegate focused tasks—such as a code review or parallel investigation—to subagents configured with authorized Profiles. The agent uses `forge_subagent` to delegate; Forge itself does not require this package.
 
-- [Commands](docs/reference/commands.md)
-- [Stack schema and policy](docs/reference/stack-schema.md)
-- [Macros and slots](docs/reference/macros-and-slots.md)
-- [Configuration](docs/reference/configuration.md)
-- [Public API policy](docs/reference/public-api.md)
-- [Experimental subagent host port](docs/reference/subagent-host-port.md)
+Use matching local development sources pending coordinated release. Subagents operate with backend-dependent write permissions and isolation (tool restrictions alone are not an OS sandbox). See the [delegation guide](docs/guides/delegation.md) before enabling delegation.
 
-### Develop and design
+## Notes and documentation
 
-- [Development setup](docs/development/setup.md)
-- [Architecture and development rules](docs/development/architecture-rules.md)
-- [0.5 architecture plan](docs/design/architecture-0.5.md)
-- [Release process](docs/development/release.md)
-- [Roadmap](docs/development/roadmap.md)
-- [Architecture and design index](docs/design/README.md)
+- This is a **0.x** project; releases may introduce breaking changes.
+- `replace` mode replaces Pi's base system prompt. Include any tool guidance, skills, or project context you still want.
+- Skill filtering only changes Forge's rendered listing; it does not disable explicit skill invocation. Tool policy is not filesystem or process isolation.
+- Regex only handles the text and patterns you select. `finalize` overwrites stored assistant/tool-result text and does not preserve the original. Payload captures are redacted and may be truncated; they can still contain private conversation content.
+- For stack structure, resource schemas, and command details, see the documentation links below.
 
-Chinese user documentation starts at [docs/zh-CN/README.md](docs/zh-CN/README.md).
+[Getting started](docs/getting-started.md) · [Web editor](docs/guides/web-editor.md) · [Commands](docs/reference/commands.md) · [Schema and policy](docs/reference/stack-schema.md) · [Debugging](docs/guides/debugging.md) · [All documentation](docs/README.md)
 
 ## License
 

package/README.zh-CN.md

@@ -1,151 +1,123 @@
 # pi-forge
 
-[English](README.md) | [简体中文](README.zh-CN.md) · [中文文档](docs/zh-CN/README.md)
+[English](README.md) | [简体中文](README.zh-CN.md) · [中文文档](docs/zh-CN/README.md) · [快速开始](#安装与第一次使用)
 
-![pi-forge header](https://raw.githubusercontent.com/MacroSony/pi-forge/main/assets/pi-forge-header-concept-1.png)
+![pi-forge：Pi 的上下文编辑与检查工作台](assets/pi-forge-header-concept-1.png)
 
-**pi-forge** 让你自定义 [Pi](https://github.com/badlogic/pi-mono) 的思考方式和行为。Preset（预设）把有序 prompt 堆栈与工具/skill 策略、Regex 和参数放在一起；Agent Profile 可以一次性应用模型、思考等级和预设。
+**面向 Pi 的上下文编辑与检查工作台。**
 
-可以把它理解为 AI agent 的角色卡和工作台。
+pi-forge 为 [Pi](https://github.com/earendil-works/pi) 提供可视化上下文编排、工具选择、配置复用和请求检查。
 
-## 主要能力
+> 受 SillyTavern 预设的启发，我开发了 pi-forge，既用来定制 Agent 上下文的内容与组装方式，也用来检查实际发送给模型的请求。
 
-- 把 system prompt、聊天历史、工具、skills、项目上下文和运行时数据组合成可排序的 block 和 slot。
-- 用一条命令切换编程、审查、写作、角色扮演和翻译模式。
-- 保存并应用完整的模型/思考等级/预设 Profile。
-- 按预设严格限制工具，并过滤模型可见的 skills。
-- 使用静态、轮次和会话变量，以及支持嵌套的模板宏。
-- 对发给模型的 prompt 或最终 assistant 消息执行确定性 regex 转换。
-- 在本地 Web 编辑器中管理 Preset/Profile，并检查实际 provider payload。
-- 用明确启用的 profile 运行实验性、需要审批的前台 subagent。
+[上下文编排](#上下文编排) · [工具选择](#工具选择) · [正则文本变换](#正则文本变换) · [动态指令与工具](#动态系统提示词与工具) · [预览与请求检查](#预览与请求检查)
 
-## 安装
+> **Optional subagents（可选）**：[pi-forge-subagents](https://github.com/MacroSony/pi-forge-subagents) —— 将任务委派给拥有独立模型与预设的子代理。
 
-pi-forge 需要 Node.js 22.19 或更高版本。
+## 安装与第一次使用
+
+Node.js 需要 **22.19 或更高版本**。0.5.6 支持 Pi **0.87.x**（`>=0.87.0 <0.88.0`），已在 **0.87.0** 上验证。
+
+> **版本提示：** 本文介绍 Forge **0.5.6**。能力与可配置默认工具需要 0.5.5；可选 subagents 另有[兼容要求（英文）](docs/reference/subagent-host-port.md#tool-selection-compatibility)。
 
 ```bash
 pi install npm:@zihanw/pi-forge
 ```
 
-安装或更新后请重启 Pi。运行中的 Pi host 会向 extension 提供 SDK package；pi-forge 只在开发和测试中固定精确版本，以保证结果可复现，不会用 peer dependency 锁死 Pi 频繁发布的版本。兼容策略见[开发与兼容性](docs/development/setup.md#pi-compatibility)（英文）。
+安装或更新后重启 Pi。然后在已信任的项目中：
 
-## 五分钟上手
+1. 运行 `/forge ui` 打开本地编辑器。
+2. 点 **New preset**，从默认 Pi mirror 布局开始。
+3. 改一个内容块或工具策略，在 **Preview** 里看结果。
+4. 点 **Save** 保存，再点 **Activate**，让当前会话用上这份预设。
 
-### 1. 创建预设
+喜欢用终端？通过 `/preset use <id>` 选择预设，用 `/capability enable <capability>` 启用能力。你可以从 [Read-first Worker 示例](docs/zh-CN/reference/capabilities.md#read-first-worker)开始。
 
-从[默认 Pi mirror](examples/default-prompt-stack.json) 创建 `default` 预设。0.5.3 的兼容存储路径仍是 `.pi/forge/prompt-stacks/default.json`：
+## 功能
 
-```bash
-mkdir -p .pi/forge/prompt-stacks
-cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
-```
+### 上下文编排
 
-如果你通过 npm 安装而不是 clone 仓库，请直接打开 `/preset ui` 新建预设；编辑器使用相同的 Pi mirror 布局。
+用可编辑的内容块和插槽组合 Agent 的上下文：指令、工具说明、技能、项目文件和聊天记录都可以放进来。调整顺序或开关条目，直接在预览中看结果。
 
-重启 Pi，或执行：
+- **使用场景**：给代码审查 Agent 配上项目规范和相关上下文，而不是让所有任务共用一份越来越长的提示词。
+- **上手尝试**：在编辑器的 **Stack** 中编辑或拖动内容块、开关项目上下文，再看 **Preview** 中的变化。
 
-```text
-/preset reload
-/preset use default
-```
+![拖拽系统内容块排序，再关闭项目上下文插槽，预览随之更新](assets/readme/zh-CN/context-composition.gif)
 
-没有其他预设或已恢复 session 选择优先时，`default.json` 会自动启用。
+详见 [Web 编辑器指南](docs/zh-CN/guides/web-editor.md)与 [Schema 与策略文档（英文）](docs/reference/stack-schema.md)。
 
-### 2. 打开可视化编辑器
+### 工具选择
 
-```text
-/preset ui
-```
+分别选择 Agent 可以使用哪些工具，以及默认启用哪些工具。允许或禁止列表限定权限范围；默认工具可以更少，其余已获准的工具留给能力按需启用。
 
-本地编辑器可以新建、fork、校验、预览、导入、导出和删除预设，并可在新建/fork/导入时明确选择写入项目或用户全局存储。Preview dock 提供带旧/新行号和行内高亮的 unified/split diff，可只看变化行或保留三行/全部上下文；Run diff 会把 chars/4 估算与 Pi 返回的真实 prompt/cache usage、cache hit rate 明确分开。切换到 **Agent profiles** 可以浏览项目与全局 Profile、编辑和删除全局 Profile（通过显式 `global:<id>` 路由）。写入操作要求项目已被信任。Delegation 配置由可选包 `@zihanw/pi-forge-subagents` 的 `subagents.json` 文件管理，不在编辑器中。
+- **使用场景**：让代码审查 Agent 专注于阅读和搜索，不提供编辑文件或执行 shell 的工具。
+- **上手尝试**：在 **Policy** 中选择许可工具，并将默认工具设为 `read` 和 `ls`。把已获准的 `grep` 加入默认集，在 **Preview** 中查看工具列表；保存并启用预设后应用策略。
 
-### 3. 保存 profile
+![工具选择：策略默认 read/ls 并添加 grep](assets/readme/zh-CN/tool-selection.gif)
 
-先正常配置 Pi，然后捕获当前设置：
+详见 [工具策略参考（英文）](docs/reference/stack-schema.md#tool-and-skill-policy)。
 
-```text
-/profile save reviewer
-/profile use reviewer
-```
+### 正则文本变换
 
-Profile 只应用一次。之后手动修改模型或思考等级会被保留，直到再次应用 Profile；当前预设的工具策略则会在启用期间持续执行。
+用可复用的正则规则查找和替换模型输入，或处理已完成的助手回复与工具结果。
 
-## 基本概念
+- **使用场景**：发送前替换选定提示词中的已知敏感标记，或者清理回复中反复出现的套话。
+- **上手尝试**：在 **Regex** 中配置出站规则，将示例文本 `SAMPLE_TOKEN` 替换为 `[REDACTED]`，目标选择 system 文本。演示中开关这条预先配置的规则，在 **Preview** 中对比结果。
 
-一份 **Preset（预设）**对应一个 JSON 文档，其中有序的上下文编排部分叫 **Stack（堆栈）**：
+![正则文本变换：出站虚构 SAMPLE_TOKEN 脱敏开关](assets/readme/zh-CN/regex-transforms.gif)
 
-| 堆栈条目 | 用途 |
-|---|---|
-| **Block** | 固定的 `system`、`user`、`assistant` 或隐藏 `custom` 文本 |
-| **Slot** | 工具、skills、项目上下文、参数、日期/cwd、聊天历史等运行时内容 |
+详见 [正则规则参考（英文）](docs/reference/stack-schema.md#regex-transforms)。
 
-预设还会携带 system mode（`replace`、`append` 或 `prepend`）、工具/skill 策略、Regex、参数和扩展引用。编译时，pi-forge 会展开堆栈、插入对话、执行工具策略、过滤自己渲染的 skill 列表，并应用已启用的 Regex 规则。
+### 动态系统提示词与工具
 
-Agent Profile 引用精确 provider/model、思考等级和预设。它不会重复保存工具或 skill 策略；被引用的预设始终是唯一来源。项目 Profile 和预设可以遮蔽同 ID 的全局资源；需要精确选择时使用 `project:<id>` 或 `global:<id>`。
+**能力（Capabilities）**可以在对话中动态更新系统提示词和可用工具。让 Agent 从少量工具起步，需要时再加载对应任务的指令与工具，不必重启会话或切换预设。
 
-> **0.5.3 兼容说明。** 用户界面已经统一为“预设 → 堆栈”，但这个补丁版本不会偷偷迁移存储和 schema：`.pi/forge/prompt-stacks/`、`"pi-forge.prompt-stack"`、Profile 字段 `promptStack`、`/api/stacks` 和内部 `PromptStack` 类型名暂时保持不变。后续存储/schema 迁移见 [roadmap](docs/development/roadmap.md)。
+- **使用场景**：Agent 先用 `read`、`ls` 阅读代码，准备修复问题时再自行启用已授权的编辑能力。
+- **上手尝试**：在 **Capabilities** 中创建能力，在预设的 **Bindings** 页签授权 Agent 使用。你也可以在 **当前会话** 中或通过 `/capability enable <capability>` 手动启用，查看指令和工具的变化。
 
-推荐从这些示例开始：
+更新在支持的模型上以原生会话中系统消息送达，其他模型则回退为带标记的用户消息（详见[投递模型说明](docs/zh-CN/reference/capabilities.md#投递模型native-与-fallback)）。
 
-- [默认 Pi mirror](examples/default-prompt-stack.json)：保留 Pi 默认行为，同时让所有区域都可移动。
-- [最小 worker](examples/minimal-prompt-stack.json)：用 Pi 自带工具借用 DeepSeek Harness Minimal 的结构——同一句 persona、聊天历史，以及仅 `bash` + `edit`；不复刻 DSH 的 shell/editor 语义。
-- [Regex hack pack](examples/hack-prompt-stack.json)：针对两种示例 token 形态展示 request 频率的出站脱敏和 transcript finalize 清理；它不是完整的密钥扫描器。
-- [自定义 system-status extension](examples/custom-system-status-extension/README.md)：注册可信 macro 和 slot。
-- [Fake assistant 直接输出实验](examples/fake-assistant-direct-output-prompt-stack.json)：在聊天历史后追加普通 assistant 文本，测试模型特定的思考捷径；是否有效取决于 model/provider/endpoint，使用前必须做同条件 A/B。
+在支持的 provider／模型组合上，新增或移除工具可以保留已有的提示词缓存前缀。新增与移除的支持范围不同，实际缓存命中不作保证；详见[支持情况与缓存实测](docs/zh-CN/reference/provider-support.md#实测缓存表现)。
 
-## 常用命令
+![启用并定位探索能力：工具与指令同步可见；停用恢复 read 并显示移除更新](assets/readme/zh-CN/capability-tools.gif)
 
-| 命令 | 用途 |
-|---|---|
-| `/preset ui [stop\|restart]` | 打开或管理 Web 编辑器 |
-| `/preset list` | 列出预设 |
-| `/preset use <id\|none>` | 选择或禁用预设 |
-| `/preset preview [id]` | 编译预设，但不发送请求 |
-| `/preset validate [id]` | 校验一个或全部预设 |
-| `/preset diagnostics` | 查看运行时和 extension 诊断 |
-| `/profile list` | 列出并 preflight profile |
-| `/profile save <id> [--overwrite]` | 把当前运行时保存为 profile |
-| `/profile use <id>` | preflight 后一次性应用 profile |
-| `/profile status` | 查看上次应用 provenance 和当前 drift |
-| `/payload next [save=<path>]` | 检查下一个经过脱敏的 provider payload |
+详见[能力参考](docs/zh-CN/reference/capabilities.md)。
 
-完整列表见[命令参考](docs/zh-CN/reference/commands.md)。
+### 预览与请求检查
 
-## 实验性前台 delegation
+调用模型前先看清修改影响了什么；运行后，再用捕获的请求和用量信息排查问题。
 
-可选包 `@zihanw/pi-forge-subagents` 在 pi-forge 的 `/subagent` host port 之上提供前台 delegation。模型通过 `forge_subagent_profiles` 发现可用 profile，再用 `forge_subagent` 调用；用户可以使用 `/forge-agent plan` 和 `/forge-agent run`。
+- **使用场景**：确认修改后的提示词包含了想要的指令，或在 Agent 表现不同时对比前后两次请求。
+- **上手尝试**：在 `/forge ui` 中切换至 **Preview** 查看编译消息，打开 **Draft diff** 对比未保存修改，或在终端运行 `/forge payload next` 捕获下一次出站请求。
 
-此功能仍是**实验性功能**，profile 默认不能委派。请在可信项目的 `.pi/forge/subagents.json`（或可选包只读兼容的 `.pi/forge/config.json.subagents`）中逐个启用。除非项目明确授权无人值守的模型调用，否则执行前会显示与不可变计划绑定的审批界面。
+![未保存的指令修改与已保存预设的差异](assets/readme/zh-CN/edit-draft-diff.gif)
 
-> **安全边界：** 当前 backend 是 shared-user 进程，不是操作系统沙箱。“只读”只描述模型可见工具策略。Child 仍有启动用户的 OS 读取权限；可读内容可能发送给所选 provider，并保留在 Pi session 数据中。Timeout 和取消仅为 best effort，`/tree` 不能撤销 provider 请求、计费或外部影响。
+**当前会话**还会显示本轮和当前分支的缓存命中率，主模型与已上报的嵌套工具用量分开统计。这是已记录的用量，不是完整账单。详见[缓存用量](docs/zh-CN/reference/session-cache.md)、[调试指南（英文）](docs/guides/debugging.md)与[命令参考](docs/zh-CN/reference/commands.md)。
 
-启用前必须阅读[前台 delegation 与安全模型](docs/zh-CN/guides/delegation.md)。
+## 示例
 
-## 文档导航
+- [默认 Pi mirror](examples/default-prompt-stack.json)：从一份 Pi 风格的配置开始，内容已经拆成可编辑的文本块和运行时插槽。
+- [Minimal worker](examples/minimal-prompt-stack.json)：一行提示词、聊天记录，只留 `bash` 和 `edit` 两个工具。
+- [Read-first Worker](examples/read-first-worker-prompt-stack.json)＋[Write tools 能力](examples/capabilities/write-tools.json)：默认仅 `read`、`ls` 与能力控制工具，模型按需启用 `bash`／`edit`。[安装与边界](docs/zh-CN/reference/capabilities.md#read-first-worker)。
+- [正则示例](examples/hack-prompt-stack.json)：拿两种示例 token 格式，演示发送前脱敏，以及清理已存储的会话文本。
 
-### 学习
+用 `/profile save reviewer` 将当前模型、思考强度和预设存为 Agent Profile，再用 `/profile use reviewer` 恢复。更多用法见[模式与用例（英文）](docs/guides/use-cases.md)。
 
-- [快速上手](docs/zh-CN/getting-started.md)
-- [Prompt stack 概念](docs/zh-CN/concepts/prompt-stacks.md)
-- [Agent profile 概念](docs/zh-CN/concepts/agent-profiles.md)
-- [Web 编辑器](docs/zh-CN/guides/web-editor.md)
-- [前台 delegation](docs/zh-CN/guides/delegation.md)
+## Subagents（Optional，可选）
 
-### 参考
+可选配套扩展 [`pi-forge-subagents`](https://github.com/MacroSony/pi-forge-subagents) 让 Agent 通过 `forge_subagent`，把代码审查、并行调查等任务交给使用已授权 Profile 的子代理。不安装它，也能使用 Forge 的其他功能。
 
-- [命令](docs/zh-CN/reference/commands.md)
-- [英文 stack schema](docs/reference/stack-schema.md)
-- [英文 macros 与 slots](docs/reference/macros-and-slots.md)
-- [英文配置参考](docs/reference/configuration.md)
+在配套正式发布前，请使用匹配的本地开发源码。子代理的写入权限与隔离级别取决于所选后端（仅靠工具策略并不构成操作系统级沙箱）。启用前请参阅[委派指南](docs/zh-CN/guides/delegation.md)。
 
-完整英文文档从 [docs/README.md](docs/README.md) 开始。
+## 注意事项与文档
 
-## 兼容性原则
+- 本项目处于 **0.x** 阶段，更新可能包含不兼容改动。
+- `replace` 会替换 Pi 原本的系统提示词。还想保留的工具指南、技能或项目上下文，要自己放进预设。
+- 技能过滤只管 Forge 渲染的列表，不会禁用显式 skill 调用。工具策略也不负责隔离文件系统或进程。
+- 正则只会处理你选定的文本和匹配规则。`finalize` 会覆盖已存储的助手消息或工具结果，不保留原文。捕获的请求会脱敏，也可能截断，但仍可能包含私人对话。
+- 提示词栈结构、资源 Schema 与命令详情请参阅下方文档链接。
 
-- npm 安装不会要求用户跟随某个精确 Pi patch 版本。
-- Release 会分别记录实际测试过的 Pi 最低版本和当前版本。
-- 如果实验性 subagent 依赖的 host capability 不存在，它应在 provider transport 前明确报错并 fail closed。
-- 普通 prompt stack 和 profile 使用不应因为可选 delegation backend 不兼容而失效。
+[快速上手](docs/zh-CN/getting-started.md) · [Web 编辑器](docs/zh-CN/guides/web-editor.md) · [命令参考](docs/zh-CN/reference/commands.md) · [Schema 与策略（英文）](docs/reference/stack-schema.md) · [调试（英文）](docs/guides/debugging.md) · [全部文档](docs/zh-CN/README.md)
 
 ## License