@zihanw/pi-forge 0.3.2 → 0.4.0

package/README.md

@@ -1,540 +1,155 @@
 # pi-forge
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](README.md) | [简体中文](README.zh-CN.md) · [Documentation](docs/README.md)
 
 ![pi-forge header](https://raw.githubusercontent.com/MacroSony/pi-forge/main/assets/pi-forge-header-concept-1.png)
 
-**pi-forge** lets you customize how Pi thinks and behaves. It gives you prompt stacks — JSON files that can replace, append to, or prepend Pi's default system prompt while controlling the AI's personality, visible tools, conversation history layout, template variables, and prompt transforms.
+**pi-forge** lets you customize how [Pi](https://github.com/badlogic/pi-mono) thinks and behaves. Prompt stacks control prompt composition and tool policy; agent profiles apply a model, thinking level, and stack as a reusable one-shot preset.
 
-Think of it as a character sheet for your AI agent.
+Think of it as a character sheet and workbench for your AI agent.
 
-## What you can do with it
+## Highlights
 
-- **Give Pi a personality** — turn it into a creative writer, a roleplay partner, a strict code reviewer, or anything in between.
-- **Switch contexts instantly** — one command to swap between "coding mode", "writing mode", and "translation mode".
-- **Control what the AI sees** — choose which tools, skills, and project context appear in each prompt.
-- **Limit tools and skills per stack** — enforce active tool policy and filter skill visibility for focused modes.
-- **Use template variables** — define static values such as `{{char}}` / `{{user}}`, and use ST-style turn/session variable macros inside prompt text.
-- **Transform outgoing and finalized text** — run deterministic regex replacements on selected history, compiled prompt text, or finalized assistant messages.
-- **Import SillyTavern presets** — bring your existing ST character presets into Pi with one command.
-- **Debug your prompts** — intercept and inspect exactly what gets sent to 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/stack profiles.
+- Enforce per-stack tool policy and filter model-visible skills.
+- Use static, turn, and session variables with nested template macros.
+- Apply deterministic regex transforms to outgoing prompts or finalized assistant messages.
+- Import SillyTavern presets and inspect the migration report.
+- Edit stacks and profiles in a local browser UI and inspect the exact provider payload.
+- Run an explicitly enabled profile as an experimental, approval-gated foreground subagent.
 
-## Quick start
+## Install
 
-### Install
+pi-forge requires Node.js 22.19 or newer.
 
 ```bash
 pi install npm:@zihanw/pi-forge
 ```
 
-### Your first prompt stack
+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.
 
-Create `.pi/forge/prompt-stacks/default.json` from [examples/default-prompt-stack.json](examples/default-prompt-stack.json).
+## Five-minute start
 
-The default example mirrors Pi's own prompt builder from `@earendil-works/pi-coding-agent/dist/core/system-prompt.js`, but splits it into movable pi-forge slots: role, tools, guidelines, Pi docs guidance, appended system prompt text, project context, skills, date/cwd, and chat history.
+### 1. Create a prompt stack
+
+Create `.pi/forge/prompt-stacks/default.json` from [the default Pi mirror](examples/default-prompt-stack.json):
 
 ```bash
 mkdir -p .pi/forge/prompt-stacks
-$EDITOR .pi/forge/prompt-stacks/default.json
-```
-
-Paste the example JSON into that file. If you are working inside this repository, you can copy it directly with `cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json`.
-
-That's it. Restart Pi or run `/preset reload`. If no stack is already selected, `default.json` auto-activates. If you previously chose another stack or `/preset use none`, run `/preset use default`.
-
-### Visual editor
-
-Prefer clicking over typing JSON? pi-forge has a built-in web editor:
-
-```
-/preset ui
-```
-
-Drag, drop, create, edit, validate, inspect full previews and captured payloads, manage variables/context/regex rules in tabs, switch dark mode, recover through raw stack JSON, import, export, fork, and delete stacks — all in your browser. New stacks start from the default Pi prompt mirror layout. Stack metadata is collapsible so the active editor stays in view. The policy tab shows registered tools and loaded skills with selected-pattern chips and filtering, so allow/deny rules can be built from exact names while still supporting wildcards.
-
-Import accepts native pi-forge stack JSON and SillyTavern preset JSON. SillyTavern presets are converted to prompt stacks automatically; if a preset contains multiple `character_id` configs, the editor asks which one to use.
-
-The editor runs on an available `127.0.0.1` port with a session token, so multiple Pi instances can run editors at the same time. If Pi reinitializes the extension after session navigation or a new session, `/preset ui` reuses the existing editor URL for the same project instead of orphaning the old server. Writes require a trusted project and stay inside prompt-stack storage. New stacks are written to `.pi/forge/prompt-stacks`; existing legacy stacks under `.pi/prompt-stacks` remain readable and editable. Successful save, import, fork, and delete actions reload into the current Pi session. Use `/preset ui restart` or `/preset ui stop` when needed.
-
-To copy old stacks into the new location, run `/preset migrate-stacks`. Add `--dry-run` to preview, `--overwrite` to replace existing target files, and `--delete-legacy` to remove old files after successful copy.
-
-To prefer a specific port, create `.pi/forge/config.json`. If that port is busy, pi-forge falls back to another available port and shows the actual URL:
-
-```json
-{
-  "webEditor": {
-    "port": 41738
-  }
-}
-```
-
-## Use cases
-
-### 🎭 Roleplay & creative writing
-
-Turn Pi into a character. Define their personality in the system prompt, inject writing style rules as user messages, and use `{{lastUserMessage}}` to re-insert the user's input after the conversation history.
-
-Useful pattern:
-- Put long-term character rules in a `system` block.
-- Keep Pi runtime context (tools, skills, project) in `user` slots.
-- Set the `chat-history` slot to skip the latest user message.
-- Add a final `user` block with `{{lastUserMessage}}`.
-
-This keeps the latest request clear and avoids duplicating it.
-
-For a baseline stack to fork before turning Pi into a character, start from [examples/default-prompt-stack.json](examples/default-prompt-stack.json).
-
-### 🧑‍💻 Focused code review
-
-Create a `reviewer.json` stack with a strict review block: "prioritize correctness, regressions, security, and missing tests." Keep the `tools`, `project-context`, `variables`, and `chat-history` slots enabled so Pi can still inspect the repo and see any template variables you expose.
-
-Use `mode: "append"` if you want to keep Pi's normal coding behavior and only add the sharper review lens.
-
-### 🌐 Translation mode
-
-Create a small `translator.json` stack with one system block for tone and target language, then keep `chat-history` and `{{lastUserMessage}}` in the layout. This works well for switching between bilingual editing, literal translation, and localization review without changing your default assistant.
-
-### 🔀 Multi-mode switching
-
-Create separate stacks for different tasks:
-
-```
-.pi/forge/prompt-stacks/
-  coder.json       # strict coding assistant
-  writer.json      # creative writing partner
-  translator.json  # bilingual translator
+cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 ```
 
-Switch with `/preset use coder`, `/preset use writer`, etc.
+If you installed from npm rather than cloning this repository, open `/preset ui` and create a new stack; the editor starts with the same Pi-mirror layout.
 
-### 🧪 Presets that show off pi-forge
+Restart Pi or run:
 
-- **Pi mirror** — start from [examples/default-prompt-stack.json](examples/default-prompt-stack.json). It preserves normal Pi behavior while making every runtime section movable and inspectable.
-- **Focused reviewer** — see [examples/reviewer-prompt-stack.json](examples/reviewer-prompt-stack.json). It denies file-writing tools, wraps prior chat history as background, removes the latest user message from history, then reinserts `{{lastUserMessage}}` as the explicit review target.
-- **Read-only scout** — use `tools.allow` for `read`, `grep`, `find`, and `ls`; omit editing tools; cap `chat-history` with `maxChars`. Good for exploration turns where the model should report findings without changing files.
-- **Surgical patcher** — keep the Pi mirror, require `read`, `edit`, and `bash`, strip assistant thinking from inserted history, and move `project-context` near the final user turn. Good for focused implementation passes.
-- **SillyTavern DM writer** — see [examples/sillytavern-dm-writer-prompt-stack.json](examples/sillytavern-dm-writer-prompt-stack.json). It defines a Dungeon Master character with `{{char}}` / `{{user}}`, wraps prior adventure history, reinserts `{{lastUserMessage}}` as the current player action, and uses regex cleanup for OOC notes, secret-roll markers, dice notation, and `Player:` prefixes.
-- **Payload lab** — include `active-model`, `date-cwd`, and variables slots, then add `compiled` regex rules for deterministic redaction or formatting. Pair it with `/payload next` or the web editor's capture view to audit exactly what changed.
-- **Docs-only Pi expert** — allow only read/search tools, enable the `pi-docs` slot, and keep project context. Useful when you want answers grounded in the installed Pi docs instead of general memory.
-
-### 🔧 Template variables
-
-```json
-"variables": {
-  "char": "Konata",
-  "user": "User"
-}
-```
-
-Use static variables for stable prompt constants, and ST-style macros for local prompt-time mutation:
-
-```
-{{setvar::mood::focused}}
-{{getvar::mood}}
-{{setsessionvar::topic::compiler cleanup}}
+```text
+/preset reload
+/preset use default
 ```
 
-For durable project memory, use normal files in the repo rather than pi-forge prompt variables.
+`default.json` auto-activates when no stack or restored session selection takes precedence.
 
-### 📦 SillyTavern migration
+### 2. Open the visual editor
 
-Bring your ST presets into Pi:
-
-```
-/preset import-silly ~/SillyTavern/presets/my-preset.json
+```text
+/preset ui
 ```
 
-pi-forge converts the preset to a prompt stack and generates a migration report showing what was handled and what needs manual tweaking.
-
-Deterministic SillyTavern `promptOnly` regex scripts are converted to pi-forge `regex.rules` as history-stage rules when they can be represented safely, including full-match token conversion, trim strings, depth fields, and clear user/assistant placements. Display-only, mixed prompt/display, DOM/browser, CSS/HTML decoration, JavaScript, unsupported placements, and invalid regex scripts stay report-only for manual review.
-
-### 🔍 Prompt debugging
-
-See exactly what gets sent to the model:
+The local editor can create, fork, validate, preview, import, export, and delete prompt stacks. Its **Agent profiles** view manages one-shot model/thinking/stack presets and experimental delegation settings. Writes require a trusted project.
 
-```
-/payload next save=.pi/forge/payloads/last.json
-```
-
-Or open `/preset ui`, click **Arm payload**, send the next Pi prompt, and inspect the redacted provider payload in the browser.
+### 3. Save a profile
 
-Or preview your compiled prompt without sending anything:
+Configure Pi normally, then capture and reuse the current settings:
 
+```text
+/profile save reviewer
+/profile use reviewer
 ```
-/preset preview
-```
-
-## How it works
 
-A prompt stack is a JSON file with two kinds of items:
+A profile applies once. Later manual changes to the model or thinking level remain in effect until the profile is applied again; an active prompt stack continues enforcing its tool policy.
 
-| Kind | What it does |
-|------|-------------|
-| **Block** | Static text inserted at a specific position (system prompt, user message, assistant message) |
-| **Slot** | Dynamic content from Pi's runtime — tools, skills, chat history, date, project context, etc. |
+## The basic model
 
-Items are arranged in order. When the stack is active, pi-forge:
+A prompt stack is an ordered JSON document containing:
 
-1. Builds a system prompt from your `system`-role blocks and slots, then applies it with the stack's `mode`.
-2. Inserts `user`/`assistant` blocks and slots around the conversation history.
-3. Expands `{{macros}}` like `{{lastUserMessage}}`, `{{date}}`, and custom variables.
-4. Applies stack tool policy to Pi's active tool set and filters pi-forge-rendered tool/skill slots.
-5. Applies enabled outgoing regex rules for the `history` and `compiled` stages.
-6. Optionally applies destructive `finalize` regex rules when an assistant message finishes.
+| Item | Purpose |
+|---|---|
+| **Block** | Static `system`, `user`, `assistant`, or hidden `custom` text |
+| **Slot** | Runtime content such as tools, skills, project context, variables, date/cwd, or chat history |
 
-### Slots at a glance
+Stacks can `replace`, `append`, or `prepend` Pi's base system prompt. During compilation, pi-forge expands macros, inserts conversation content, enforces tool policy, filters its skill listing, and applies enabled regex rules.
 
-| Slot | What it inserts |
-|------|----------------|
-| `chat-history` | The current conversation |
-| `tools` | Available tools and their descriptions |
-| `tool-guidelines` | Tool usage instructions |
-| `skills` | Loaded Pi skills |
-| `project-context` | Project instructions and context files |
-| `variables` | Static/session/turn template variables |
-| `date` / `cwd` / `date-cwd` | Current date, optional current time, and working directory |
-| `active-model` | Which model is being used |
-| `append-system-prompt` | User's appended system prompt text |
-| `pi-docs` | Pi documentation guidance |
+Agent profiles are project-local references to an exact provider/model, thinking level, and prompt stack. They intentionally do not duplicate tool or skill policy—the referenced stack remains the source of truth.
 
-### Modes
+Start with these examples:
 
-- **replace** (default) — your stack replaces Pi's system prompt entirely.
-- **append** — your stack is added after Pi's default system prompt.
-- **prepend** — your stack is added before Pi's default system prompt.
+- [Default Pi mirror](examples/default-prompt-stack.json) keeps normal Pi behavior while making its sections movable.
+- [Focused reviewer](examples/reviewer-prompt-stack.json) creates a read-only review layout with an explicit latest-user target.
+- [SillyTavern DM writer](examples/sillytavern-dm-writer-prompt-stack.json) demonstrates characters, variables, history placement, and regex cleanup.
+- [Custom system-status extension](examples/custom-system-status-extension/README.md) registers a trusted macro and slot.
 
 ## Common commands
 
-### Managing stacks
-
-| Command | What it does |
-|---------|-------------|
-| `/preset list` | Show all available stacks |
-| `/preset use <id>` | Activate a stack |
-| `/preset use none` | Disable prompt stacks for the session |
-| `/preset preview [id]` | See the compiled prompt |
-| `/preset validate [id]` | Check a stack for issues |
-| `/preset status` | Show the active stack and diagnostics summary |
-| `/preset diagnostics` | Show runtime diagnostics |
-| `/preset reload` | Reload stacks from disk |
-| `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | Copy legacy `.pi/prompt-stacks` files into `.pi/forge/prompt-stacks` |
-| `/preset ui [stop\|restart]` | Open, stop, or restart the web editor |
-
-### Import & debug
-
-| Command | What it does |
-|---------|-------------|
-| `/preset import-silly <path>` | Import a SillyTavern preset |
-| `/intercept` | Show the next provider payload |
-| `/payload next [save=<path>]` | Show, save, and expose the next payload to the web editor |
-
-## Common macros
-
-Use these in block content to insert dynamic values:
-
-| Macro | Expands to |
-|-------|-----------|
-| `{{lastUserMessage}}` | The user's latest message |
-| `{{date}}` | Current date (YYYY-MM-DD) |
-| `{{time}}` | Current time (HH:MM:SS) |
-| `{{cwd}}` | Current working directory |
-| `{{tools}}` | Comma-separated tool names |
-| `{{selectedTools}}` | Alias for selected tool names |
-| `{{activeModel}}` | Current model (provider/id) |
-| `{{char}}` / `{{user}}` | Custom variables from your stack |
-
-### Variable macros
+| Command | Purpose |
+|---|---|
+| `/preset ui [stop\|restart]` | Open or manage the web editor |
+| `/preset list` | List prompt stacks |
+| `/preset use <id\|none>` | Select or disable a stack |
+| `/preset preview [id]` | Compile a stack without sending a request |
+| `/preset validate [id]` | Validate one stack or all stacks |
+| `/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 |
 
-```
-{{setvar::name::value}}       set a turn variable (cleared each message)
-{{setsessionvar::name::value}} set a session variable (persists)
-{{setvar::session::name::value}} also set a session variable
-{{getvar::name}}              read a variable (turn → session → static)
-{{getturnvar::name}}          read only a turn variable
-{{getsessionvar::name}}       read only a session variable
-{{clearvar::name}}            clear a variable
-{{clearturnvar::name}}        clear a turn variable
-{{clearsessionvar::name}}     clear a session variable
-```
-
-### Filter and conditional macros
-
-Nested macros are supported, and `::` separators are parsed only at the current macro depth.
-
-| Macro | Expands to |
-|-------|-----------|
-| `{{trim::value}}` | `value` with leading/trailing whitespace removed |
-| `{{upper::value}}` | Uppercase `value` |
-| `{{lower::value}}` | Lowercase `value` |
-| `{{json::value}}` | JSON string literal for `value` |
-| `{{xml::value}}` | XML-escaped `value` |
-| `{{ifvar::name::then::else}}` | `then` when a variable exists, otherwise `else` |
-| `{{ifeq::name::expected::then::else}}` | `then` when a variable equals `expected`, otherwise `else` |
-| `{{iftools::tool::then::else}}` | `then` when the selected tool list includes `tool`, otherwise `else` |
-| `{{ifslot::slot::then::else}}` | `then` when the enabled stack items include `slot`, otherwise `else` |
-
-Conditional branches are lazy: only the selected branch is expanded, so skipped branches cannot set or clear variables. The final `else` argument is optional and defaults to empty text.
-
-### Trusted custom macros and slots
-
-Custom macros and slots are registered by trusted extension code, not embedded in prompt-stack JSON. For project-local customization, put registration modules in `.pi/forge/extensions/`. For machine-wide personal customization, put them in `~/.pi/forge/extensions/`. pi-forge loads global modules first, then project-local modules, after project trust and before stack validation. Both locations reload on `/preset reload`.
-
-These modules receive the registration API from pi-forge, so they do not need to import `@zihanw/pi-forge` or know where pi-forge is installed.
-
-```ts
-// .pi/forge/extensions/ticket-context.ts
-export default function register(api) {
-  api.registerMacro({
-    name: "ticketId",
-    description: "Current ticket id from session variables.",
-    render: (ctx) => ctx.variables.toMacroText(ctx.variables.get("ticket.id")),
-  });
-
-  api.registerSlot({
-    name: "ticket-context",
-    description: "Render ticket context for the current task.",
-    options: {
-      heading: { type: "string", default: "Ticket context" },
-    },
-    render: (ctx) => [
-      String(ctx.options.heading ?? "Ticket context") + ":",
-      "- Ticket: " + ctx.variables.toMacroText(ctx.variables.get("ticket.id")),
-      "- Project: " + ctx.helpers.normalizePath(ctx.runtime.options.cwd),
-    ].join("\n"),
-  });
-}
-```
-
-The stack remains declarative:
-
-```json
-{
-  "kind": "slot",
-  "id": "ticket-context",
-  "enabled": true,
-  "role": "system",
-  "slot": "ticket-context",
-  "options": {
-    "heading": "Current ticket"
-  }
-}
-```
-
-Supported module files are `.ts`, `.js`, `.mjs`, `.cjs`, and `index.*` inside a subdirectory. TypeScript modules should stick to syntax Node can strip at runtime, or you can use `.js` / `.mjs` instead. A module can export either `default function register(api)` or `export function register(api)`. Registered macro and slot names must be unique across built-ins, global extensions, and project extensions; duplicate names show as extension load warnings.
-
-The API includes `cwd`, `forgeDir`, `extensionPath`, `helpers`, `registerMacro`, `registerSlot`, `getRegisteredMacros`, and `getRegisteredSlots`. For global modules, `forgeDir` is `~/.pi/forge`; for project modules, it is `<project>/.pi/forge`.
+See the [complete command reference](docs/reference/commands.md).
 
-Missing custom slots are validation warnings until the registering module is loaded. Built-in macros and slots use the same registry internally, so `getRegisteredMacros()` and `getRegisteredSlots()` can be used as implementation references. `/preset diagnostics` shows loaded pi-forge extension files and load failures.
+## Experimental foreground delegation
 
-For a complete copyable extension and stack, see [examples/custom-system-status-extension](examples/custom-system-status-extension). It registers a `{{cpuLoad}}` macro and a `machine-status` slot from `.pi/forge/extensions/system-status.ts`.
+pi-forge can run an explicitly enabled profile as a clean, foreground Pi subprocess. 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`.
 
-Reusable Pi packages can still import `registerMacro` and `registerSlot` from `@zihanw/pi-forge`. The `.pi/forge/extensions` and `~/.pi/forge/extensions` loaders are intended for small trusted customizations without package boilerplate.
+This feature is **experimental** and profiles are not delegatable by default. Enable each profile in the trusted project's `.pi/forge/config.json` or its web-editor delegation card. Interactive execution presents an immutable plan for approval unless the project explicitly authorizes unattended model invocation.
 
-## Stack reference
+> **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.
 
-### Full item types
+Read [foreground delegation and its safety model](docs/guides/delegation.md) before enabling it.
 
-**Block:**
-
-```json
-{
-  "kind": "block",
-  "id": "unique-id",
-  "name": "Readable label",
-  "enabled": true,
-  "role": "system",
-  "content": "Your text here. Use {{macros}} for dynamic content."
-}
-```
-
-Valid roles: `system`, `user`, `assistant`, `custom`.
-
-**Slot:**
-
-```json
-{
-  "kind": "slot",
-  "id": "unique-id",
-  "name": "Chat History",
-  "enabled": true,
-  "role": "user",
-  "slot": "chat-history",
-  "options": {
-    "includeLastUserMessage": false
-  }
-}
-```
-
-### Chat history options
-
-```json
-"options": {
-  "includeLastUserMessage": false,
-  "stripAssistantThinking": true,
-  "includeSummaries": true,
-  "toolMode": "keep",
-  "roles": ["user", "assistant"],
-  "maxMessages": 40,
-  "maxChars": 20000
-}
-```
+## Documentation
 
-Set to `false` when you use `{{lastUserMessage}}` after the history — prevents the user's message from appearing twice.
+### Learn
 
-Set `stripAssistantThinking` to `true` to remove prior assistant thinking blocks from inserted chat history. Visible assistant text, tool calls, and tool result messages are preserved. This only affects history inserted by that slot and does not alter the current agent loop or stored transcript.
+- [Getting started](docs/getting-started.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)
+- [SillyTavern import](docs/guides/sillytavern-import.md)
+- [Custom macros and slots](docs/guides/custom-macros-and-slots.md)
+- [Prompt and payload debugging](docs/guides/debugging.md)
 
-Use `includeSummaries: false` to omit Pi branch/compaction summary messages, `roles` to keep only specific message roles, `toolMode: "drop"` to remove prior tool-call/tool-result history, and `maxMessages` / `maxChars` to keep only recent history. When filters or limits can break tool-call pairs, pi-forge removes dangling tool calls/results instead of sending inconsistent tool history.
+### Reference
 
-### Date slot options
+- [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 adapter](docs/reference/subagent-adapter.md)
 
-Set `"includeTime": true` on a `date` or `date-cwd` slot to include the current time in `HH:MM:SS` after the current date.
+### Develop and design
 
-### Structured slot format options
+- [Development setup](docs/development/setup.md)
+- [Release process](docs/development/release.md)
+- [Roadmap](docs/development/roadmap.md)
+- [Historical design archive](docs/design/README.md)
 
-Structured runtime slots default to XML-style wrappers. Add `"format": "plain"` to `tools`, `tool-guidelines`, `skills`, `project-context`, or `variables` slots for compact newline-separated output.
-
-```json
-{
-  "kind": "slot",
-  "id": "tools",
-  "enabled": true,
-  "role": "system",
-  "slot": "tools",
-  "options": {
-    "format": "plain"
-  }
-}
-```
-
-The default Pi mirror uses a few extra slot options:
-
-```json
-{
-  "slot": "tools",
-  "options": {
-    "format": "plain",
-    "onlyWithSnippets": true
-  }
-}
-```
-
-`tools.onlyWithSnippets` matches Pi's default "Available tools" section by hiding tools that do not provide prompt snippets. `tool-guidelines.heading`, `tool-guidelines.includePiDefaultGuidelines`, and `tool-guidelines.piStyle` make the guidelines slot match Pi's default heading and bullets. `skills.requireReadTool` hides skills unless the read tool is active, matching Pi's default behavior.
-
-### Tool and skill policy
-
-Prompt stacks can constrain tools and skills with stack-level `allow` or `deny` lists. Patterns are exact by default and support `*` wildcards.
-
-```json
-{
-  "tools": {
-    "allow": ["read", "bash"]
-  },
-  "skills": {
-    "deny": ["browser-danger"]
-  }
-}
-```
-
-Use `allow` when only matching tools or skills should remain active. Use `deny` when everything except matching tools or skills should remain active. A single resource policy cannot contain both non-empty lists; mixed `allow` and `deny` entries are validation errors.
-
-Tool policy is enforced through Pi's active tool list while the stack is active. pi-forge remembers the previous active tools and restores them when prompt stacks are disabled or switched to an unrestricted stack.
-
-Skill policy filters skills rendered by pi-forge's `skills` slot. If a stack uses `mode: "append"` or `"prepend"`, Pi's base prompt may already contain unfiltered skills; use `mode: "replace"` when skill visibility must be controlled.
-
-### Regex transforms
-
-Prompt stacks can run deterministic regex replacements on model-bound prompt text and, optionally, finalized assistant messages. Outgoing rules support `history` and `compiled` stages. Destructive final-message cleanup uses `effect: "finalize"` at `stage: "compiled"` with the `messages` target. True display-only streaming transforms and provider-payload rewrites are not active yet.
-
-```json
-"regex": {
-  "schemaVersion": 1,
-  "rules": [
-    {
-      "id": "trim-ooc",
-      "enabled": true,
-      "stage": "history",
-      "effect": "outgoing",
-      "pattern": "\\(OOC:[^)]+\\)",
-      "flags": "gi",
-      "replace": "",
-      "roles": ["assistant"],
-      "maxMessages": 20
-    }
-  ]
-}
-```
-
-Use `stage: "history"` to transform messages inserted by the `chat-history` slot. Use `stage: "compiled"` with optional `targets: ["system"]`, `["messages"]`, or both to transform the final compiled prompt. Message rules can filter by `roles`, `maxMessages`, `maxChars`, `minDepth`, and `maxDepth`, where depth `0` is the latest message. Replacements use JavaScript syntax (`$&` for the full match, `$1` for captures; `$0` is also accepted as a full-match alias, and `$$` escapes a literal `$`). `trimStrings` removes literal strings from expanded replacement matches/captures, matching SillyTavern's Trim Out behavior. Supported regex flags are `g`, `i`, `m`, `s`, and `u`.
-
-To clean a completed assistant message after streaming, use `effect: "finalize"`:
-
-```json
-{
-  "id": "finalize-ooc",
-  "enabled": true,
-  "stage": "compiled",
-  "effect": "finalize",
-  "targets": ["messages"],
-  "roles": ["assistant"],
-  "pattern": "\\s*\\(OOC:[^)]+\\)",
-  "flags": "gi",
-  "replace": ""
-}
-```
-
-Warning: `finalize` runs at `message_end`, after raw output may already have streamed in the TUI. It returns a cleaned replacement message to Pi, so the original model output is not preserved in the stored transcript.
-
-`effect: "outgoing"` changes model input. `effect: "finalize"` changes finalized assistant transcript content. `effect: "display"` and `"both"` validate with warnings but are ignored at runtime until true display transforms are implemented.
-
-SillyTavern imports convert deterministic prompt-only `{{match}}` / `$0` full-match replacements to JavaScript `$&` (both `$0` and `$&` work in pi-forge), preserve original regex metadata in `source.sillytavern`, and run as history-stage rules so depth stays chat-relative. Display-only/browser/unsupported-placement scripts stay report-only. The web editor has a structured Regex dialog for these rule fields and preserves advanced unknown fields for raw JSON editing.
-
-### Variables slot options
-
-```json
-{
-  "kind": "slot",
-  "id": "variables",
-  "enabled": true,
-  "role": "user",
-  "slot": "variables",
-  "options": {
-    "includeStatic": true,
-    "includeSession": true,
-    "includeTurn": false,
-    "format": "xml"
-  }
-}
-```
-
-## Package setup for development
-
-```bash
-git clone <repo>
-cd pi-forge
-npm install
-npm run build
-# .pi/settings.json already points at the package root
-pi    # start Pi, trust the project, /reload if needed
-```
-
-Run tests:
-
-```bash
-npm test
-```
-
-Typecheck:
-
-```bash
-npm run typecheck
-```
-
-Build package output:
-
-```bash
-npm run build
-```
+Chinese user documentation starts at [docs/zh-CN/README.md](docs/zh-CN/README.md).
 
 ## License
 
-MIT
+[MIT](LICENSE)