@zihanw/pi-forge 0.4.0-beta.1 → 0.4.0

package/docs/getting-started.md

@@ -0,0 +1,93 @@
+# Getting started
+
+[Documentation](README.md) · [中文](zh-CN/getting-started.md)
+
+## Requirements and installation
+
+pi-forge requires Node.js 22.19 or newer and runs as a Pi extension.
+
+```bash
+pi install npm:@zihanw/pi-forge
+```
+
+Restart Pi after installing or updating. The running Pi host supplies its SDK packages; see [Pi compatibility](development/setup.md#pi-compatibility) for the tested-version policy.
+
+Project stacks, profiles, and configuration are loaded only after Pi trusts the project.
+
+## Create your first stack
+
+Prompt stacks live in `.pi/forge/prompt-stacks/*.json`. The quickest baseline is [the default Pi mirror](../examples/default-prompt-stack.json), which preserves normal Pi behavior while splitting its prompt into movable sections.
+
+In a repository clone:
+
+```bash
+mkdir -p .pi/forge/prompt-stacks
+cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
+```
+
+When installed from npm, open `/preset ui` and create a stack; new stacks start from the same mirror layout.
+
+Reload and activate it:
+
+```text
+/preset reload
+/preset use default
+```
+
+If no restored session selection or explicit opt-out takes precedence, `default.json` auto-activates. Set `"autoActivate": false` to prevent that behavior.
+
+## Edit and inspect
+
+```text
+/preset ui
+```
+
+The editor opens on a token-protected `127.0.0.1` URL. It supports structured and raw JSON editing, drag-and-drop ordering, validation, exact preview, policy selection, regex rules, import/export, fork, and profile management. See the [web-editor guide](guides/web-editor.md).
+
+To inspect without opening a browser:
+
+```text
+/preset validate default
+/preset preview default
+/preset diagnostics
+```
+
+## Create a profile
+
+Select the model, thinking level, and prompt stack you want in Pi, then save them:
+
+```text
+/profile save reviewer
+/profile preview reviewer
+/profile use reviewer
+```
+
+Profiles live in `.pi/forge/agent-profiles/*.json`. Applying one is a preflighted, one-shot operation: later manual model/thinking changes remain until you apply the profile again. Read [agent-profile concepts](concepts/agent-profiles.md) for validation, auto-activation, and drift semantics.
+
+## Storage and migration
+
+| Location | Purpose |
+|---|---|
+| `.pi/forge/prompt-stacks/` | Project prompt stacks |
+| `.pi/forge/agent-profiles/` | Project agent profiles |
+| `.pi/forge/config.json` | Trusted project configuration and delegation authorization |
+| `.pi/forge/extensions/` | Trusted project macro/slot registration code |
+| `~/.pi/forge/config.json` | User defaults |
+| `~/.pi/forge/extensions/` | Trusted user macro/slot registration code |
+
+Legacy `.pi/prompt-stacks/*.json` files remain readable. New stacks go to `.pi/forge/prompt-stacks`, and same-named new-location files shadow legacy ones. Migrate safely with:
+
+```text
+/preset migrate-stacks --dry-run
+/preset migrate-stacks
+```
+
+Add `--overwrite` only when target replacement is intended. Add `--delete-legacy` only after checking the copied files.
+
+## Where to go next
+
+- Learn the [prompt-stack model](concepts/prompt-stacks.md).
+- Fork a [focused reviewer](../examples/reviewer-prompt-stack.json) or [DM writer](../examples/sillytavern-dm-writer-prompt-stack.json).
+- Use the [SillyTavern importer](guides/sillytavern-import.md).
+- Learn [macros and slots](reference/macros-and-slots.md).
+- Inspect the [complete commands](reference/commands.md) and [stack schema](reference/stack-schema.md).

package/docs/guides/custom-macros-and-slots.md

@@ -0,0 +1,68 @@
+# Custom macros and slots
+
+[Documentation](../README.md)
+
+Custom macros and slots are registered by trusted extension code, never embedded as executable code in prompt-stack JSON.
+
+Put small project registrations in `.pi/forge/extensions/` and machine-wide personal registrations in `~/.pi/forge/extensions/`. Global modules load first, then project modules, after trust and before stack validation. Both locations reload with `/preset reload`.
+
+## Registration module
+
+Modules receive the pi-forge API directly, so they do not need to import the package:
+
+```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"),
+  });
+}
+```
+
+Use the slot declaratively:
+
+```json
+{
+  "kind": "slot",
+  "id": "ticket-context",
+  "enabled": true,
+  "role": "system",
+  "slot": "ticket-context",
+  "options": { "heading": "Current ticket" }
+}
+```
+
+## Module rules
+
+- Supported files are `.ts`, `.js`, `.mjs`, `.cjs`, and `index.*` inside a subdirectory.
+- TypeScript should use syntax Node can strip at runtime; otherwise use JavaScript or precompile it.
+- Export `default function register(api)` or named `register(api)`.
+- Names must be unique across built-ins, global extensions, and project extensions.
+- Duplicate names and load failures appear in diagnostics.
+- Missing custom slots are validation warnings until their module is loaded.
+- Registration ownership is disposed when the runtime shuts down.
+
+The API provides `cwd`, `forgeDir`, `extensionPath`, helpers, registration functions, and `getRegisteredMacros()` / `getRegisteredSlots()`. Global `forgeDir` is `~/.pi/forge`; project `forgeDir` is `<project>/.pi/forge`.
+
+Reusable Pi packages may import `registerMacro` and `registerSlot` from `@zihanw/pi-forge`. The directory loaders are intended for small trusted customizations without package boilerplate.
+
+## Security
+
+Registration modules execute with the Pi process's user permissions. Load them only from code you trust. Stack JSON remains declarative and cannot register executable behavior by itself.
+
+For a copyable example, see [custom-system-status-extension](../../examples/custom-system-status-extension/README.md). For built-ins, see [macros and slots](../reference/macros-and-slots.md).

package/docs/guides/debugging.md

@@ -0,0 +1,39 @@
+# Prompt and payload debugging
+
+[Documentation](../README.md)
+
+## Validate and preview
+
+```text
+/preset validate [id]
+/preset preview [id]
+/preset status
+/preset diagnostics
+```
+
+Validation checks schema shape, item IDs, slots, policy, regex rules, custom dependencies, and activation conflicts. Preview compiles without sending a provider request. Diagnostics includes runtime policy, regex activity, extension modules, and load failures.
+
+The web editor provides the same validation plus a full visual preview and source-aware resources.
+
+## Inspect the next provider payload
+
+```text
+/payload next
+/payload next save=.pi/forge/payloads/last.json
+```
+
+Or open `/preset ui`, click **Arm payload**, then send the next Pi prompt. Credential-shaped token fields are redacted; normal request limits and accounting fields such as `max_tokens`, `input_tokens`, and `output_tokens` remain visible.
+
+`/intercept` is the compact command for showing the next provider payload.
+
+Saved payloads can contain prompt and conversation content. Keep them out of version control unless deliberately sanitized.
+
+## Common checks
+
+- Unexpected duplicate task: set the `chat-history` slot's `includeLastUserMessage` to `false` when a later block uses `{{lastUserMessage}}`.
+- Missing tool: inspect stack `allow`/`deny` policy and `/preset status`; the tool-call guard enforces the selected stack even if another extension modifies active tools.
+- Skill still visible: use `replace` mode when Pi's base prompt must not include its own skill listing.
+- Missing custom slot: trust the project, check `.pi/forge/extensions`, reload, and inspect diagnostics.
+- Changed profile source: `/profile status` distinguishes source-definition changes from manual runtime drift.
+- Delegation unavailable: use `/forge-agent backends`, `/profile preview`, and `forge_subagent_profiles` metadata before provider execution.
+- Provider authentication works in the parent but not the child: restart after updating Pi or pi-forge and confirm the installed extension/runtime versions are not stale.

package/docs/guides/delegation.md

@@ -0,0 +1,99 @@
+# Experimental foreground delegation
+
+[Documentation](../README.md) · [中文](../zh-CN/guides/delegation.md)
+
+> **Experimental:** This API and its backends may change independently of stable prompt-stack and profile behavior.
+
+pi-forge can execute an explicitly authorized agent profile as a separate, clean, one-shot Pi process. It runs in the foreground and returns a bounded report to the parent conversation.
+
+## Enable a profile
+
+Profiles are not delegatable by default. Enable each eligible ID in the trusted project's `.pi/forge/config.json`, or use the profile's delegation card in `/preset ui`:
+
+```json
+{
+  "subagents": {
+    "backend": "pi-subprocess-readonly",
+    "timeoutMs": 60000,
+    "profiles": {
+      "reviewer": {
+        "enabled": true,
+        "timeoutMs": 300000
+      },
+      "rpc-reviewer": {
+        "enabled": true,
+        "backend": "pi-rpc-readonly",
+        "timeoutMs": 180000
+      }
+    }
+  }
+}
+```
+
+Enablement and per-profile overrides are project-only because profiles are project-local. A global `~/.pi/forge/config.json` may define general `backend` and `timeoutMs` defaults; global `profiles` entries warn and are ignored. Disabled or unlisted IDs are hidden from discovery and rejected even if guessed.
+
+## Discover, plan, and run
+
+Humans use:
+
+```text
+/forge-agent backends
+/forge-agent plan reviewer Review this API design for correctness.
+/forge-agent run reviewer Review this API design for correctness.
+/forge-agent run reviewer --backend pi-rpc-readonly Review this API design.
+```
+
+`plan` resolves the profile and stack, compiles and validates the exact immutable provider-bound plan, displays it, and discards it without provider transport.
+
+The parent model uses `forge_subagent_profiles` to discover enabled profiles and `forge_subagent` to invoke one. A restrictive parent stack must allow both tool names. Discovery is local/no-egress and reports metadata, resolution readiness, effective backend/timeout, approval mode, and whether parent tool policy permits invocation.
+
+## Backends and precedence
+
+Two fresh-process backends are registered:
+
+- `pi-subprocess-readonly` is the default and uses `pi --mode text --print`.
+- `pi-rpc-readonly` uses `pi --mode rpc`.
+
+Both execute the same sealed prompt and shared-user read-only policy; only their process protocol differs. There is no fallback if the selected backend is unavailable.
+
+Interactive backend precedence is: per-run override, project profile override, project default, user default, built-in default. Unattended model invocation is pinned to the effective configured backend and rejects a per-call override. Timeout follows profile, project, user, then the 60-second built-in default; valid values are 1,000–3,600,000 ms. Host timeout is best effort.
+
+## Approval and unattended invocation
+
+By default, the exact plan is prepared before an approval screen shows the task, profile/stack, provider/model, thinking level, tools, working directory, boundary, payload size, and fingerprint. **View full prompt** reveals the complete provider-bound system prompt and ordered messages. Editing that view cannot alter the sealed plan.
+
+To authorize the parent model without per-run approval:
+
+```json
+{
+  "subagents": {
+    "allowAgentInvocationWithoutApproval": true
+  }
+}
+```
+
+This affects only `forge_subagent`; `/forge-agent run` remains interactive. It is ignored in untrusted projects and malformed values fail closed. Treat this project config as an authorization file: do not enable or commit it unless every parent agent allowed to call `forge_subagent` may send the compiled prompt and readable file contents to the selected provider without asking again.
+
+## Child context and output
+
+The child receives a clean conversation, the exact profile model/thinking/stack, and the delegated task as a protected final user message. It does not automatically receive parent history.
+
+Candidate tools are `read`, `grep`, `find`, and `ls`, further restricted by stack tool policy. The child loads no write/edit/shell tools, skills, prompt templates, project context files, or third-party extensions.
+
+The model-visible result is bounded. Expandable human details retain normalized status, a text transcript, tool events, diagnostics, usage, approval receipt, and execution report. Retained strings are bounded, base64-like text is redacted, and the transcript keeps a 512 KiB rolling tail. Inline image bytes are replaced by MIME/encoded-size metadata before retention in the parent session.
+
+## Security boundary
+
+The current backends are **shared-user, not operating-system sandboxes**.
+
+- “Read-only” is a model-tool policy. The process retains the invoking user's OS permissions.
+- Absolute paths readable by that user may be read and sent to the selected provider.
+- Text may be retained in parent tool-result details and Pi's on-disk session JSONL.
+- Timeout and cancellation are best effort.
+- `/tree` changes the active conversation branch; abandoned entries can remain on disk.
+- `/tree` cannot undo provider requests, billing, or external effects.
+- Removing sensitive retained text requires deleting the relevant Pi session data.
+
+The default tools intentionally provide no mutation path. Do not add write, edit, or shell access to this shared-user design. OS isolation and separately approved staged writes remain future work.
+
+For integration authors, see the [experimental adapter contract](../reference/subagent-adapter.md).

package/docs/guides/sillytavern-import.md

@@ -0,0 +1,47 @@
+# Importing SillyTavern presets
+
+[Documentation](../README.md)
+
+Import through the command line:
+
+```text
+/preset import-silly ~/SillyTavern/presets/my-preset.json
+```
+
+Use `--dry-run` to preview, `--overwrite` to replace protected output, and an optional `character_id` when the preset contains multiple prompt orders. The web editor also accepts SillyTavern JSON and asks which character order to use when necessary.
+
+Generated stacks go to `.pi/forge/prompt-stacks/<id>.json`; reports go to `.pi/forge/import-reports/<id>.md`. Always read the report before activating the stack.
+
+## Converted behavior
+
+The importer:
+
+- converts prompt order into ordered stack items;
+- maps the chat-history marker to a movable `chat-history` slot;
+- detects `{{lastUserMessage}}` and avoids duplicating the latest user turn;
+- carries relevant identifiers in `source.sillytavern` metadata;
+- maps deterministic `promptOnly` regex scripts to history-stage outgoing rules when their behavior is representable;
+- converts full-match replacement syntax and preserves trim strings, depth limits, and supported user/assistant placement.
+
+## Report-only behavior
+
+The following require manual review and are not executed:
+
+- display-only or mixed prompt/display scripts;
+- DOM, browser, CSS, HTML-decoration, or JavaScript behavior;
+- unsupported placements or invalid regular expressions;
+- markers with no pi-forge equivalent;
+- SillyTavern features whose ordering or lifecycle cannot be represented safely.
+
+pi-forge does not embed arbitrary executable preset code. Unsupported content stays visible in the migration report instead of being silently approximated.
+
+## Recommended workflow
+
+1. Run a dry import.
+2. Read every warning and omission in the report.
+3. Open the generated stack in `/preset ui`.
+4. Validate it and inspect the full preview.
+5. Compare the history placement and regex rules with the original preset.
+6. Activate it only after the preview matches your intent.
+
+See [stack schema](../reference/stack-schema.md#regex-transforms) for the supported regex runtime.

package/docs/guides/use-cases.md

@@ -0,0 +1,65 @@
+# Prompt-stack patterns and examples
+
+[Documentation](../README.md)
+
+Use these as starting patterns rather than rigid templates. The [default Pi mirror](../../examples/default-prompt-stack.json) is the safest baseline to fork.
+
+## Roleplay and creative writing
+
+Put long-lived character rules in a system block, runtime context in appropriate slots, and the current user action in an explicit final user block:
+
+1. System character/personality block.
+2. Tools, project context, variables, and other runtime slots.
+3. `chat-history` with `includeLastUserMessage: false`.
+4. Final user block containing `{{lastUserMessage}}`.
+
+This keeps the latest request clear and avoids duplication. Static `{{char}}` / `{{user}}` variables work well for character constants; turn/session macros can track temporary scene state. Durable project memory belongs in project files, not prompt variables.
+
+## Focused code review
+
+Start from [the reviewer example](../../examples/reviewer-prompt-stack.json). It denies writing tools, wraps prior history as background, omits the latest user message from history, then reinserts it as the explicit review target.
+
+Use a rule such as “prioritize correctness, regressions, security, and missing tests.” Keep tools, project context, variables, and history when the reviewer must inspect the repository. Use `append` to retain Pi's normal coding prompt, or `replace` when the stack must fully control prompt and skill visibility.
+
+## Translation mode
+
+Create a small stack with a system block for target language, register/tone, and terminology rules. Retain history and a final `{{lastUserMessage}}`. Separate literal translation, localization review, and bilingual editing into different stacks when their rules conflict.
+
+## Multi-mode switching
+
+Keep independent project files:
+
+```text
+.pi/forge/prompt-stacks/
+  coder.json
+  writer.json
+  translator.json
+```
+
+Switch with `/preset use coder`, `/preset use writer`, or `/preset use translator`. Capture a profile when a mode also needs a specific model and thinking level.
+
+## Read-only scout
+
+Allow only `read`, `grep`, `find`, and `ls`, omit editing tools, and cap chat history with `maxChars`. This is useful for exploration turns where the model should report findings without changing files.
+
+Tool policy constrains model tool calls but is not an operating-system sandbox. A normal Pi agent may still have other non-tool ways to interact with its host; do not describe a prompt stack alone as process isolation.
+
+## Surgical patcher
+
+Keep the Pi mirror, require the tools needed for the workflow, strip prior assistant thinking from inserted history, and move project context near the current user turn. This reduces distracting prompt material without removing relevant repository instructions.
+
+## SillyTavern DM writer
+
+[The DM-writer example](../../examples/sillytavern-dm-writer-prompt-stack.json) defines a Dungeon Master through `{{char}}` / `{{user}}`, wraps prior adventure history, reinserts the current action, and uses deterministic regex cleanup for OOC notes, secret-roll markers, dice notation, and `Player:` prefixes.
+
+## Payload lab
+
+Include `active-model`, `date-cwd`, and `variables`, then add compiled regex rules for deterministic redaction or formatting. Pair the stack with `/payload next` or the web editor's capture view to audit exactly what changed.
+
+## Pi-docs expert
+
+Allow read/search tools, include the `pi-docs` and project-context slots, and keep a focused system instruction. This encourages answers grounded in installed Pi documentation rather than general model memory.
+
+## Trusted runtime status
+
+The [custom system-status example](../../examples/custom-system-status-extension/README.md) registers `{{cpuLoad}}` and a `machine-status` slot from trusted project code. Use this pattern for deterministic host data that cannot be represented as static stack JSON.

package/docs/guides/web-editor.md

@@ -0,0 +1,75 @@
+# Web editor
+
+[Documentation](../README.md)
+
+Open the browser editor from a trusted Pi project:
+
+```text
+/preset ui
+```
+
+Use `/preset ui restart` to replace its server or `/preset ui stop` to close it.
+
+## Connection and trust
+
+The editor binds to an available `127.0.0.1` port and uses a session token. Multiple Pi projects can run editors simultaneously. Lifecycle reinitialization reuses the existing editor URL for the same project when possible.
+
+Reads, preview, resources, and payload inspection remain available as appropriate, but writes require Pi to trust the project. Files are constrained to pi-forge's stack/profile storage. Never expose or proxy the editor URL to an untrusted network.
+
+Choose a preferred port in `.pi/forge/config.json`:
+
+```json
+{
+  "webEditor": {
+    "port": 41738
+  }
+}
+```
+
+If that port is unavailable, pi-forge selects another and shows the actual URL.
+
+## Prompt-stack workspace
+
+The stack workspace provides:
+
+- creation from the default Pi-mirror layout;
+- structured metadata, item, policy, variables, context, and regex editing;
+- drag-and-drop item order and enable/disable controls;
+- validation and a full compiled preview;
+- registered-tool and loaded-skill search with exact-name chips and wildcard patterns;
+- raw JSON recovery for advanced or unknown fields;
+- native pi-forge and SillyTavern JSON import;
+- export, fork, and deletion;
+- 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. New stacks, imports, and forks write to `.pi/forge/prompt-stacks`; 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 without discarding unsaved delegation fields.
+
+## Agent-profile workspace
+
+The profile list shows each profile's ID, display metadata, model, thinking level, stack, resolution state, auto-activation, last-applied provenance, and delegation status.
+
+Trusted projects can create, edit, validate, save, apply once, and delete profiles. Model choices come from Pi's model registry, thinking choices reflect model support, and stack choices come from the shared repository. The editor rejects a second auto-activation profile.
+
+The runtime/provenance card separates current runtime state, last-applied snapshot, source-definition changes, and field-level runtime drift.
+
+## Delegation card
+
+The profile delegation card edits only project-level `subagents.profiles.<id>` values: enablement, backend override, and timeout override. General defaults and `allowAgentInvocationWithoutApproval` remain config-file-only because they affect broader authorization.
+
+Unsaved delegation changes are guarded when selecting another profile, starting another profile operation, refreshing, deleting, or leaving/reloading the page. The card shows effective values and the source of each inherited or overridden setting.
+
+Read [foreground delegation](delegation.md) before enabling a profile.
+
+## Migration
+
+To copy legacy `.pi/prompt-stacks` into `.pi/forge/prompt-stacks`:
+
+```text
+/preset migrate-stacks --dry-run
+/preset migrate-stacks
+```
+
+Review before adding `--overwrite` or `--delete-legacy`.

package/docs/reference/commands.md

@@ -0,0 +1,60 @@
+# Command reference
+
+[Documentation](../README.md) · [中文](../zh-CN/reference/commands.md)
+
+Arguments in brackets are optional. Commands that write project files require a trusted project.
+
+## Prompt stacks
+
+| Command | Behavior |
+|---|---|
+| `/preset list` | List stacks and activation/validation state. |
+| `/preset status` | Show the selected stack and diagnostics summary. |
+| `/preset use <id>` | Validate and select a stack. |
+| `/preset use none` | Disable prompt stacks for this session branch. `off` is accepted as an alias. |
+| `/preset preview [id]` | Compile and display a stack without provider transport. Defaults to the selected stack. |
+| `/preset validate [id]` | Validate one stack or all stacks when omitted. |
+| `/preset diagnostics` | Show loader, runtime, policy, regex, and trusted-extension diagnostics. |
+| `/preset reload` | Reload stacks and trusted macro/slot registrations. |
+| `/preset ui [stop\|restart]` | Open, stop, or replace the local web editor. |
+
+## Storage migration and import
+
+| Command | Behavior |
+|---|---|
+| `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | Copy legacy `.pi/prompt-stacks` files into `.pi/forge/prompt-stacks`. |
+| `/preset import-silly <path> [character_id] [--dry-run] [--overwrite]` | Convert a SillyTavern preset and write a migration report. |
+
+Use migration/import dry runs before overwriting or deleting anything. See [SillyTavern import](../guides/sillytavern-import.md).
+
+## Agent profiles
+
+| Command | Behavior |
+|---|---|
+| `/profile list` | List project profiles and resolution diagnostics. |
+| `/profile use <id>` | Preflight and apply a profile once. |
+| `/profile save <id> [--overwrite]` | Capture the current model, thinking level, and stack. |
+| `/profile status` | Compare current runtime with last-applied branch provenance. |
+| `/profile preview <id>` | Resolve model/auth/thinking/stack/tools without applying. |
+| `/profile validate [id]` | Validate one profile or all profiles when omitted. |
+| `/profile reload` | Reload definitions without applying them. |
+| `/profile forget` | Remove last-applied provenance without changing runtime state. |
+
+## Experimental foreground delegation
+
+| Command | Behavior |
+|---|---|
+| `/forge-agent backends` | List registered experimental backends, capabilities, and effective defaults. |
+| `/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 project-authorized delegation profiles are accepted. The model-callable equivalents are `forge_subagent_profiles` (local discovery) and `forge_subagent` (execution). See the [delegation safety guide](../guides/delegation.md).
+
+## Payload inspection
+
+| Command | Behavior |
+|---|---|
+| `/intercept` | Display the next redacted provider payload. |
+| `/payload next [save=<path>]` | Display the next payload, optionally save it, and expose it to the web editor. |
+
+Saved payloads may include prompt and conversation text even though credential-shaped fields are redacted. Handle them as potentially sensitive.

package/docs/reference/configuration.md

@@ -0,0 +1,64 @@
+# Configuration reference
+
+[Documentation](../README.md)
+
+Project configuration lives in `.pi/forge/config.json` and is loaded only for a trusted project. User defaults live in `~/.pi/forge/config.json`.
+
+## Web editor
+
+```json
+{
+  "webEditor": {
+    "port": 41738
+  }
+}
+```
+
+The port is preferred, not guaranteed. The editor binds only to `127.0.0.1` and chooses another available port when necessary.
+
+## Experimental subagents
+
+User configuration may set general defaults:
+
+```json
+{
+  "subagents": {
+    "backend": "pi-subprocess-readonly",
+    "timeoutMs": 60000
+  }
+}
+```
+
+Trusted project configuration may override defaults, authorize individual project profile IDs, and authorize unattended model invocation:
+
+```json
+{
+  "subagents": {
+    "backend": "pi-subprocess-readonly",
+    "timeoutMs": 60000,
+    "allowAgentInvocationWithoutApproval": false,
+    "profiles": {
+      "reviewer": {
+        "enabled": true,
+        "backend": "pi-rpc-readonly",
+        "timeoutMs": 180000
+      }
+    }
+  }
+}
+```
+
+Valid timeouts are 1,000–3,600,000 ms. Invalid fields warn and fall back to the preceding applicable default. General backend precedence is project then user then built-in; an interactive run and a project profile entry can further override it as described in [delegation](../guides/delegation.md#backends-and-precedence).
+
+`profiles` in global configuration warns and is ignored. `allowAgentInvocationWithoutApproval` is project-only, requires trust, and fails closed when malformed. Deleting a profile also clears its effective delegation policy.
+
+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.
+
+## Trusted registration directories
+
+These are code-loading locations rather than JSON fields:
+
+- `~/.pi/forge/extensions/` loads trusted user macro/slot registrations.
+- `.pi/forge/extensions/` loads trusted project registrations after project trust.
+
+See [custom macros and slots](../guides/custom-macros-and-slots.md).