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

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,107 @@
+# 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 follows the profile's scope. A global `~/.pi/forge/config.json` may define general `backend` and `timeoutMs` defaults and may authorize `global:<id>` profiles through its own `profiles` map. The trusted project's `.pi/forge/config.json` authorizes `project:<id>` profiles. Same-ID global and project profiles never inherit enablement, backend, or timeout policy from one another. Disabled or unlisted profiles are hidden from discovery and rejected even if guessed.
+
+## 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.
+
+Profile selectors accept the same grammar everywhere: `reviewer` (project first), `project:reviewer`, or `global:reviewer`. When both scopes expose the same ID, the project profile keeps the concise selector and the global profile remains callable as `global:<id>`.
+
+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.
+
+Projects with only a few frequently used profiles can set `subagents.summaryInToolDescription: true` (global or trusted-project config). The `forge_subagent` tool description then carries a compact summary of enabled profiles—id, model, thinking level, stack, backend, and timeout—so the parent model does not need a discovery call to pick a profile. Ready profiles appear first; unavailable enabled profiles remain visible with their first resolution error so the model knows not to invoke them. The summary rides in every request, is capped at 8 profiles and 1,000 characters, and refreshes with profiles, stacks, and configuration; `forge_subagent_profiles` remains the authoritative full-detail surface.
+
+## Parallel invocation
+
+`forge_subagent` is a parallel-execution tool: the parent model may issue several calls in one turn, and they prepare and run concurrently. Interactive approval dialogs are serialized one at a time because Pi's selector/editor UI is a single slot—a second concurrent dialog would clear the first and leave it unresolved—so each call waits its turn for the dialog and then executes immediately, letting approved runs overlap. Unattended invocation needs no dialog and is fully concurrent. Each run is an independent `pi` subprocess and provider request; a burst of parallel calls multiplies provider cost and process load, so keep the parent tool policy conservative until a configurable concurrency cap lands.
+
+## 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. The toolbar scope selector (default `project`) chooses where new stacks, imports, and forks are written: `global` targets the user-global `~/.pi/forge/prompt-stacks`, `project` targets `.pi/forge/prompt-stacks`. Stack rows show a `global` badge, and save/delete routes use `global:<id>` for exact global mutations. Legacy stacks remain editable in place.
+
+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, delegation status, and a `project`/`global` scope badge. Same-ID shadow pairs are marked `shadows global:<id>` or `shadowed by project:<id>`.
+
+Trusted projects can create profiles in either scope: the scope selector beside **New profile** (default `project`) chooses whether to write the user-global `~/.pi/forge/agent-profiles` or the project `.pi/forge/agent-profiles`. Global profiles can be edited, validated, saved, applied once, and deleted through explicit `global:<id>` routes; unqualified routes stay project-only. When editing a global profile, the prompt-stack dropdown offers only global stacks. 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 within the same scope.
+
+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 the `subagents.profiles.<id>` values for the selected profile's scope: project profiles write to `.pi/forge/config.json`, global profiles write to `~/.pi/forge/config.json`. 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,66 @@
+# 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).
+
+`subagents.summaryInToolDescription` (default `false`) embeds a compact, bounded summary of enabled subagent profiles directly in the `forge_subagent` tool description so the parent model can pick a profile without a discovery call. Ready profiles appear first, and unavailable enabled profiles include their first resolution error. It may be set in user or trusted-project configuration and applies wherever it is enabled.
+
+`profiles` in global configuration authorizes `global:<id>` profiles; the trusted project's `profiles` authorizes `project:<id>` profiles. Same-ID profiles never inherit enablement, backend, or timeout policy from each other. `allowAgentInvocationWithoutApproval` is project-only, requires trust, and fails closed when malformed. Deleting a profile clears delegation policy only from the matching scope's config.
+
+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).