@zihanw/pi-forge 0.4.1 → 0.5.0

package/docs/getting-started.md

@@ -70,11 +70,12 @@ Profiles live in `.pi/forge/agent-profiles/*.json` by default; `/profile save gl
 |---|---|
 | `.pi/forge/prompt-stacks/` | Project prompt stacks |
 | `.pi/forge/agent-profiles/` | Project agent profiles |
-| `.pi/forge/config.json` | Trusted project configuration and `project:<id>` delegation authorization |
+| `.pi/forge/config.json` | Trusted project configuration (`webEditor.*`) |
 | `.pi/forge/extensions/` | Trusted project macro/slot registration code |
 | `~/.pi/forge/prompt-stacks/` | User-global prompt stacks |
 | `~/.pi/forge/agent-profiles/` | User-global agent profiles |
-| `~/.pi/forge/config.json` | User defaults and `global:<id>` delegation authorization |
+| `~/.pi/forge/config.json` | User defaults (`webEditor.*`) |
+| `.pi/forge/subagents.json` / `~/.pi/forge/subagents.json` | Delegation authorization owned by the optional `@zihanw/pi-forge-subagents` package |
 | `~/.pi/forge/extensions/` | Trusted user macro/slot registration code |
 
 Legacy `.pi/prompt-stacks/*.json` files remain readable. Command-created stacks go to `.pi/forge/prompt-stacks`; use the web editor's `global` scope selector to create stacks in `~/.pi/forge/prompt-stacks`. Same-named new-location files shadow legacy ones. Migrate safely with:
@@ -89,7 +90,7 @@ Add `--overwrite` only when target replacement is intended. Add `--delete-legacy
 ## 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).
+- Fork a [focused reviewer](../examples/reviewer-prompt-stack.json).
 - Learn [macros and slots](reference/macros-and-slots.md).
+- Read the [0.5 migration guide](guides/migrating-to-0.5.md).
 - Inspect the [complete commands](reference/commands.md) and [stack schema](reference/stack-schema.md).

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

@@ -15,8 +15,9 @@ Modules receive the pi-forge API directly, so they do not need to import the pac
 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")),
+    description: "Current ticket id from static parameters.",
+    dependencies: ["parameters.ticket.id"],
+    render: ({ env, helpers }) => String(env.parameters["ticket.id"]),
   });
 
   api.registerSlot({
@@ -25,10 +26,10 @@ export default function register(api) {
     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),
+    render: ({ item, options, env, helpers }) => [
+      String(options.heading ?? "Ticket context") + ":",
+      "- Ticket: " + String(env.parameters["ticket.id"]),
+      "- Project: " + helpers.normalizePath(String(env.runtime.cwd)),
     ].join("\n"),
   });
 }
@@ -57,7 +58,7 @@ Use the slot declaratively:
 - 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`.
+The API provides `forgeDir`, `extensionPath`, helpers, registration functions, and `getRegisteredMacros()` / `getRegisteredSlots()`. Custom macro renderers receive a frozen `{ env, helpers }` and dependencies from the declaration. 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.
 

package/docs/guides/debugging.md

@@ -30,7 +30,7 @@ Saved payloads can contain prompt and conversation content. Keep them out of ver
 
 ## Common checks
 
-- Unexpected duplicate task: set the `chat-history` slot's `includeLastUserMessage` to `false` when a later block uses `{{lastUserMessage}}`.
+- Unexpected duplicate task: set the `chat-history` slot's `includeLastUserMessage` to `false` when a later block uses `{{ runtime.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.

package/docs/guides/delegation.md

@@ -4,33 +4,31 @@
 
 > **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.
+The optional `@zihanw/pi-forge-subagents` package executes 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`:
+Profiles are not delegatable by default. Enable each eligible ID in the trusted project's `.pi/forge/subagents.json`:
 
 ```json
 {
-  "subagents": {
-    "backend": "pi-subprocess-readonly",
-    "timeoutMs": 60000,
-    "profiles": {
-      "reviewer": {
-        "enabled": true,
-        "timeoutMs": 300000
-      },
-      "rpc-reviewer": {
-        "enabled": true,
-        "backend": "pi-rpc-readonly",
-        "timeoutMs": 180000
-      }
+  "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.
+Legacy `.pi/forge/config.json.subagents` is accepted as read-only fallback with a warning. Enablement follows the profile's scope. A global `~/.pi/forge/subagents.json` may define general `backend` and `timeoutMs` defaults and may authorize `global:<id>` profiles through its own `profiles` map. The trusted project's `subagents.json` authorizes `project:<id>` profiles. Same-ID global and project profiles never inherit enablement, backend, or timeout policy from one another. Disabled or unlisted profiles are hidden from discovery and rejected even if guessed.
 
 ## Discover, plan, and run
 
@@ -49,7 +47,7 @@ Profile selectors accept the same grammar everywhere: `reviewer` (project first)
 
 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.
+Projects with only a few frequently used profiles can set `summaryInToolDescription: true` (global or trusted-project `subagents.json`). 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
 
@@ -74,13 +72,11 @@ To authorize the parent model without per-run approval:
 
 ```json
 {
-  "subagents": {
-    "allowAgentInvocationWithoutApproval": true
-  }
+  "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.
+This affects only `forge_subagent`; `/forge-agent run` remains interactive. It is ignored in untrusted projects and malformed values fail closed. Treat this project `subagents.json` 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
 
@@ -104,4 +100,4 @@ The current backends are **shared-user, not operating-system sandboxes**.
 
 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).
+For integration authors, see the [subagent host port contract](../reference/subagent-host-port.md).

package/docs/guides/migrating-to-0.5.md

@@ -0,0 +1,107 @@
+# Migrating to pi-forge 0.5
+
+[Documentation](../README.md)
+
+0.5.0 is a breaking cleanup release. This page is the migration note for the
+changes landed so far (Lane 1a-1c plus the compiler/extension conformance
+pass in Lane 1d).
+
+## What was removed
+
+- SillyTavern importer (`/preset import-silly`), its reports, guide, example,
+  and tests. Convert SillyTavern presets with pi-forge 0.4 before upgrading.
+- Mutable turn/session variables, variable mutation macros,
+  `pi-forge-variable-state` session entries, and the `variables` slot.
+- Regex `display` and `both` effects; `outgoing` and `finalize` remain.
+
+## Template syntax changes
+
+Prompt text now compiles with the closed `forge-v1` grammar.
+
+| 0.4 construct | 0.5 forge-v1 |
+|---|---|
+| `{{name}}` (static) | `{{ parameters.name }}` |
+| `{{lastUserMessage}}` | `{{ runtime.lastUserMessage }}` |
+| `{{date}}` / `{{time}}` / `{{cwd}}` | `{{ runtime.date }}` / `{{ runtime.time }}` / `{{ runtime.cwd }}` |
+| `{{tools}}` | `{{ runtime.selectedToolsText }}` |
+| `{{upper::x}}` | `{{ x \| upper }}` |
+| `{{iftools::bash::A::B}}` | `{% if runtime.tool.bash %}A{% else %}B{% endif %}` |
+| custom `{{myMacro}}` | `{{ extensions.myMacro }}` |
+
+Unknown paths, unknown filters, parse errors, cycles, and output-limit breaches
+are compile errors; a failing block is omitted instead of re-injecting raw
+template text.
+
+## Schema v2
+
+Schema v2 stacks store immutable static values in `parameters` (JSON-compatible)
+instead of the legacy string-only `variables` field:
+
+```json
+{
+  "schemaVersion": 2,
+  "parameters": { "char": "Konata" }
+}
+```
+
+Unversioned / v1 stacks continue to load through the legacy `variables` reader.
+
+## Running the migration utility
+
+A mechanical, diagnostics-first script converts a saved stack file:
+
+```bash
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --dry-run
+node scripts/migrate-stack-v2.mjs .pi/forge/prompt-stacks/default.json --write
+```
+
+It renames `variables` to `parameters`, maps runtime/parameter paths, and
+converts simple filter pipelines. Non-mechanical constructs are reported and
+the file is only written when they are absent. A schema v2 file that still
+contains a legacy `variables` field is left untouched and only warned about.
+
+## Preview and finalize
+
+Preview never applies `finalize`; it now reports an informational diagnostic.
+`finalize` remains a destructive, lifecycle-owned transform that replaces the
+stored assistant message.
+
+## Lane 2: scoped global profiles and prompt stacks
+
+- User-global resources now live in `~/.pi/forge/prompt-stacks` and `~/.pi/forge/agent-profiles` alongside the project stores. Profile and stack selectors accept explicit scopes: `project:<id>`, `global:<id>`, with bare IDs resolving project-first.
+- Same-ID project resources shadow their global counterparts; global stacks cannot reference project resources (and vice versa) — references resolve within the referenced resource's scope.
+- Untrusted projects fail closed: only global resources load, all mutation routes are rejected, and `session_shutdown` no longer disposes a trusted workspace while sessions may still be active (idle workspaces are swept after an hour; hosts stop independently).
+- The web editor gained scope selectors for creating stacks/profiles into either store and routes global mutations through explicit `global:<id>` selectors.
+
+## Lane 3: subagent package split
+
+Subagent execution moved out of the main package into the optional `@zihanw/pi-forge-subagents` package (requires `@zihanw/pi-forge@^0.5.0`). Install it separately to keep foreground delegation.
+
+- **Commands:** `/subagents` and `/subagent-run` were removed from the main package. The optional package registers `/forge-agent backends|plan|run`.
+- **Model tools:** `forge_subagent_profiles` and `forge_subagent` are registered by the optional package.
+- **Configuration:** `subagents.*` moved out of `.pi/forge/config.json` into dedicated `.pi/forge/subagents.json` (trusted project) and `~/.pi/forge/subagents.json` (user defaults). The optional package reads legacy `config.json.subagents` sections as a read-only fallback with a warning; it never writes them. Copy the values into `subagents.json` to silence the warning.
+- **Web editor:** the delegation card was removed from the main editor; edit `subagents.json` directly.
+- **Architecture:** the main package's prompt compiler is host-neutral (no subagent assumptions), and `ForgeWorkspace` is the single owner of resource state and compilation contexts.
+
+## Lane 4: Forge-native host contract and public surface
+
+- The main package no longer depends on `@zihanw/pi-subagent-runtime` and no longer exports the 0.4 execution contract. That contract (`AgentRequest`, `createAgentExecutionPlan`, `validateAgentRequest`, `negotiateSubagentTools`, preflight/plan/response validators, …) now lives in `@zihanw/pi-forge-subagents` for its own runtime wiring; it is not a public surface of either package for third-party consumers.
+- `@zihanw/pi-forge/subagent` now exports only the versioned host port: wire DTOs and validators, `ForgeHostTransport`, `ForgeHost`/`ForgeHostClient`, lifecycle constants, and the Forge-owned canonical fingerprint helpers. `resolveSubagentHostProfile` / `prepareSubagentHostPlan` were replaced by the host-port operations `resolveProfile` and `prepare`.
+- The package root exports only the default extension factory, `registerMacro`/`registerSlot`, and their contract types. All other root re-exports (loader, agent-profile, profile-service, catalog, resource-identity, render-helper values, the `forge-v1` engine, registry readers) were removed.
+- All `@zihanw/pi-forge/src/*` subpath aliases and the `./examples/*` export were removed; `check-package` rejects them.
+
+### Import migration table
+
+| 0.4 import | 0.5 replacement |
+|---|---|
+| `@zihanw/pi-forge` (default, `registerMacro`, `registerSlot`) | unchanged |
+| `@zihanw/pi-forge/subagent` host-port names (`ForgeHost*`, validators, fingerprints) | unchanged |
+| `@zihanw/pi-forge/subagent` execution contract (`AgentRequest`, `createAgentExecutionPlan`, …) | internal to `@zihanw/pi-forge-subagents`; no public replacement |
+| `@zihanw/pi-forge/subagent` `resolveSubagentHostProfile` / `prepareSubagentHostPlan` | host-port operations via `ForgeHostClient` |
+| `@zihanw/pi-forge/src/*` aliases | removed; no replacement (internals) |
+| root loader/profile/catalog/engine re-exports | removed; no replacement (internals) |
+
+## Compatibility notes
+
+- The wire shape of the host port is additive across `FORGE_HOST_PORT_VERSION = 1`; unknown operations are rejected with a plain `{ ok: false, error }` result (`"Unknown Forge host operation: …"`), not a thrown error, and optional packages must treat any operation failure as terminal for that request.
+- Vendored fingerprint helpers in the main package are pinned by golden vectors to stay byte-compatible with `@zihanw/pi-subagent-runtime` canonical serialization; plan sealing still happens only in the optional package.

package/docs/guides/use-cases.md

@@ -9,21 +9,21 @@ Use these as starting patterns rather than rigid templates. The [default Pi mirr
 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.
+2. Tools, project context, and other runtime slots.
 3. `chat-history` with `includeLastUserMessage: false`.
-4. Final user block containing `{{lastUserMessage}}`.
+4. Final user block containing `{{ runtime.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.
+This keeps the latest request clear and avoids duplication. Static `{{ parameters.char }}` / `{{ parameters.user }}` values work well for character constants. Durable project memory belongs in project files, not parameters.
 
 ## 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.
+Use a rule such as “prioritize correctness, regressions, security, and missing tests.” Keep tools, project context, 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.
+Create a small stack with a system block for target language, register/tone, and terminology rules. Retain history and a final `{{ runtime.lastUserMessage }}`. Separate literal translation, localization review, and bilingual editing into different stacks when their rules conflict.
 
 ## Multi-mode switching
 
@@ -48,13 +48,9 @@ Tool policy constrains model tool calls but is not an operating-system sandbox.
 
 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.
+Include `active-model` and `date-cwd`, 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
 
@@ -62,4 +58,4 @@ Allow read/search tools, include the `pi-docs` and project-context slots, and ke
 
 ## 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.
+The [custom system-status example](../../examples/custom-system-status-extension/README.md) registers `{{ extensions.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

@@ -38,30 +38,26 @@ The stack workspace provides:
 - 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;
+- native pi-forge 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.
+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.
 
 ## 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>`.
+The profile list shows each profile's ID, display metadata, model, thinking level, stack, resolution state, auto-activation, last-applied provenance, 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
+## Delegation
 
-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.
+Delegation configuration is not part of the main editor. The optional `@zihanw/pi-forge-subagents` package owns the dedicated `.pi/forge/subagents.json` and `~/.pi/forge/subagents.json` files. Read [foreground delegation](delegation.md) before enabling a profile.
 
 ## Migration
 

package/docs/reference/commands.md

@@ -23,9 +23,8 @@ Arguments in brackets are optional. Commands that write project files require a
 | 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).
+Use migration dry runs before overwriting or deleting anything.
 
 ## Agent profiles
 
@@ -42,13 +41,15 @@ Use migration/import dry runs before overwriting or deleting anything. See [Sill
 
 ## Experimental foreground delegation
 
+The commands below are provided by the optional `@zihanw/pi-forge-subagents` package.
+
 | 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).
+Only profiles explicitly authorized in the matching scope are accepted: the project `subagents.json` authorizes `project:<id>` profiles and the global `subagents.json` authorizes `global:<id>` profiles; `.pi/forge/config.json.subagents` remains a read-only legacy fallback. The model-callable equivalents are `forge_subagent_profiles` (local discovery) and `forge_subagent` (execution). See the [delegation safety guide](../guides/delegation.md).
 
 ## Payload inspection
 

package/docs/reference/configuration.md

@@ -18,31 +18,30 @@ The port is preferred, not guaranteed. The editor binds only to `127.0.0.1` and
 
 ## Experimental subagents
 
-User configuration may set general defaults:
+Subagent configuration is owned by the optional `@zihanw/pi-forge-subagents` package. Dedicated files are `.pi/forge/subagents.json` for a trusted project and `~/.pi/forge/subagents.json` for user defaults. Legacy `.pi/forge/config.json` / `~/.pi/forge/config.json` `subagents` sections are read-only fallback material and emit a warning.
+
+User defaults may set general settings:
 
 ```json
 {
-  "subagents": {
-    "backend": "pi-subprocess-readonly",
-    "timeoutMs": 60000
-  }
+  "backend": "pi-subprocess-readonly",
+  "timeoutMs": 60000
 }
 ```
 
-Trusted project configuration may override defaults, authorize individual project profile IDs, and authorize unattended model invocation:
+Trusted project `subagents.json` 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
-      }
+  "backend": "pi-subprocess-readonly",
+  "timeoutMs": 60000,
+  "allowAgentInvocationWithoutApproval": false,
+  "summaryInToolDescription": false,
+  "profiles": {
+    "reviewer": {
+      "enabled": true,
+      "backend": "pi-rpc-readonly",
+      "timeoutMs": 180000
     }
   }
 }
@@ -50,9 +49,9 @@ Trusted project configuration may override defaults, authorize individual projec
 
 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.
+`summaryInToolDescription` (default `false`) embeds a compact, bounded summary of enabled subagent profiles directly in the `forge_subagent` tool description so the parent model can pick a profile without a discovery call. Ready profiles appear first, and unavailable enabled profiles include their first resolution error. It may be set in user or trusted-project `subagents.json` and applies wherever it is enabled.
 
-`profiles` in global 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.
+`profiles` in global `subagents.json` authorizes `global:<id>` profiles; the trusted project's `profiles` authorizes `project:<id>` profiles. Same-ID profiles never inherit enablement, backend, or timeout policy from each other. `allowAgentInvocationWithoutApproval` is project-only, requires trust, and fails closed when malformed. Deleting a profile does not modify `subagents.json`; remove any enabled entry for the deleted profile manually.
 
 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.