@zihanw/pi-forge 0.4.0 → 0.5.0

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. New stacks, imports, and forks write to `.pi/forge/prompt-stacks`; legacy stacks remain editable in place.
+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, and delegation status.
+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, 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.
+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 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.
+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,7 +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).
 
-`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.
+`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 `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.
 

package/docs/reference/features.md

@@ -1,6 +1,6 @@
 # Implemented feature inventory
 
-This file tracks the currently implemented feature surface for agent profiles, the prompt-stack runtime, template variables, web editor, SillyTavern importer, storage migration, payload inspector, and regex MVP.
+This file tracks the currently implemented feature surface for agent profiles, the prompt-stack runtime, static stack variables, web editor, storage migration, payload inspector, and regex MVP.
 
 ## Package and Runtime
 
@@ -33,30 +33,16 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Project trust gates profile loading, application, and writes.
 - Shared typed profile services own capture, protected write/update/delete, application/rollback, immutable preview data, provenance changes, and runtime-drift calculation so command, web-editor, and adapter consumers do not duplicate behavior.
 
-## Subagent Adapter Contract
+## Subagent Host Port
 
-- Dedicated experimental `@zihanw/pi-forge/subagent` entry point, with the existing package-root exports retained for 0.4 compatibility.
-- Subagent types, canonicalization, request/preflight validation, tool negotiation, context preparation, plan construction, response validation, and diagnostics live in focused modules behind a compatibility contract barrel.
-- Exported pure v1 `AgentRequest`, profile snapshot, backend preflight, execution-plan, enforcement-receipt, and discriminated response types without registering or shipping a runner.
+- Experimental versioned `@zihanw/pi-forge/subagent` entry point: the minimal Forge DTO host contract (wire messages, recursive exact-field validators, transport-neutral `ForgeHostTransport`, `ForgeHost`/`ForgeHostClient` lifecycle) plus Forge-owned canonical `sha256:v1` fingerprint helpers byte-compatible with the runtime's canonical JSON.
+- Mandatory lifecycle semantics: bounded discovery timeouts, explicit duplicate-host failure, `hostId`+`generation`-bound request/reply with stale/foreign rejection, disposal with `unavailable` and full listener cleanup. The host starts only after the first workspace snapshot exists, so an advertised host implies a loaded workspace; reload honors project trust (untrusted workspaces expose global resources only).
+- Three minimal operations: `listProfiles` (loaded profile summaries with diagnostics), `resolveProfile` (immutable host-owned profile snapshot artifact with content fingerprints), and `prepare` (host-owned prompt compilation).
+- Host-owned preparation: the client sends only a profile selector, the task text, prompt-compilation access facts (`level`/`network`/`allowProcess`), and backend facts (model, thinking level, tool catalog). The workspace resolves the profile and stack from its snapshot, filters the tool catalog through stack policy and access facts, and compiles through the same compilation context as runtime and preview. Responses return the system prompt, messages ending with the protected delegated task, effective tool IDs/names, diagnostics, the profile snapshot, and `preparedAt`.
+- The port never exposes live contexts, internal registries, or execution/runtime material (access workspace model, limits, `resultProjection`, `parent`, `remoteEgressConsent`, base system prompt). The delegated-task base system prompt is host-owned and intentionally empty; the prompt stack composes the system prompt.
 - Backend-independent host profile resolution produces path-free declarative snapshots and does not consult the parent model registry or authentication state.
 - Host dependency scanning detects custom macro and slot references, records registration source identities, and fails resolution when required registrations are missing.
-- Backend tool negotiation intersects prompt-stack name policy with declared filesystem/process/network effects and per-request access.
-- Optional empty-by-default backend registry validates registration and preflight identity, requires the backend to supply a complete fingerprinted prompt runtime, binds the exact host preparation to execution, routes dry-plan discard, rejects unbound or refingerprinted substitute plans, arbitrates cancellation and host timeouts, normalizes failures, and protects opaque trace routing behind authorization-scoped handles.
-- Experimental `pi-subprocess-readonly` backend reuses the host Pi runtime for authenticated preparation, then runs a clean foreground Pi subprocess with the exact profile model, thinking level, and compiled prompt. Its candidate model tools are limited to `read`, `grep`, `find`, and `ls`, further filtered by prompt-stack policy; it loads no write/shell tools, skills, prompt templates, context files, or third-party extensions. Host-coupled capability mismatches fail closed during preflight.
-- Delegation is an explicit per-profile opt-in under the trusted project's `subagents.profiles`; ordinary profile loading/application remains independent. Global profile entries warn and are ignored so project-local profile IDs cannot silently authorize unrelated projects. Disabled and unlisted profiles are omitted from `forge_subagent_profiles` and rejected before preparation by the command, model-callable tool, and concrete runtime.
-- The no-egress `forge_subagent_profiles` tool gives the main agent a live catalog of enabled profile IDs, names, descriptions, model/thinking/stack metadata, effective backend/timeout and sources, and ready/unavailable resolution status. It also reports whether the parent tool policy currently permits `forge_subagent`.
-- The model-callable `forge_subagent` tool and `/forge-agent run` prepare an immutable plan before provider transport. `/forge-agent run` and the default tool path require explicit human approval; a trusted-project `subagents.allowAgentInvocationWithoutApproval` option may authorize only the model-callable tool without a per-run prompt. The default review shows the task, profile/stack, provider/model/thinking level, effective tools, working directory, shared-user boundary, payload size, and fingerprint; the complete provider-bound prompt can be opened on demand.
-- Backend selection is layered configuration rather than profile schema: `subagents.backend` supplies global/project defaults, the trusted project's `subagents.profiles.<id>.backend` supplies a per-profile override, and `/forge-agent plan|run --backend <id>` or the interactive `forge_subagent` `backend` parameter overrides one run. Both the `pi-subprocess-readonly` and `pi-rpc-readonly` backends are registered; there is no fallback when the selected backend is unavailable, and unattended tool invocation is pinned to the effective configured profile backend.
-- Foreground timeout is layered host configuration rather than profile schema: `subagents.timeoutMs` supplies a 60,000-millisecond default and `subagents.profiles.<id>.timeoutMs` can override it per profile; values must be from 1,000 through 3,600,000 milliseconds. Invalid values warn and preserve the preceding valid/default value; discovery, planning, and approval surfaces show the effective best-effort timeout and source.
-- Foreground progress and the bounded final report enter the normal tool-call result. A dedicated child report channel retains the normalized response, complete text transcript, tool calls/results, diagnostics, usage, approval receipt, and execution report without persisting the full prompt or inline image data; omitted images retain MIME and encoded-size metadata.
-- The subprocess backend is explicitly shared-user rather than OS-sandboxed: read-only is a tool policy, host timeout/cancellation are best effort, and `/tree` reverts conversation state rather than provider egress, billing, or external side effects.
-- `/forge-agent backends` and `/forge-agent plan <profile> <task>` expose backend discovery and provider-free exact dry planning to a human.
-- Deterministic fake-backend conformance coverage exercises accepted/rejected preflight, tool effects, access/limit refusal, exact preparation, success/failure, cancellation races, timeout, media, artifacts, and traces. An offline faux-provider test additionally executes the concrete SDK backend through a real Pi `AgentSession` without network traffic.
-- Selected parent context uses explicit provenance and deterministic exact UTF-8 budgeting; required items survive, optional items are selected newest-first, and the complete delegated text/media task remains the protected final user message.
-- Granular validators cover request access/depth/media/limits, backend capabilities and enforcement, prompt-runtime fidelity, plan correlation, all response terminal statuses, usage units, artifact namespaces/paths, and authorized trace handles.
-- Portable profile, prompt-stack, and complete execution fingerprints use canonical `sha256:v1` serialization without changing legacy branch-provenance fingerprints.
-- The opt-in internal Pi SDK spike remains available for broader live diagnostics, including media and trusted custom registrations beyond the shipped text-only walking skeleton.
-- Adapter responsibilities and unsupported runner behavior are documented in the [subagent adapter contract](subagent-adapter.md).
+- Execution ownership (delegation authorization in `subagents.json`, the 0.4 execution contract, backend preflight/plan sealing via `@zihanw/pi-subagent-runtime`, approval UX, `forge_subagent`/`forge_subagent_profiles`, and `/forge-agent`) lives in the optional `@zihanw/pi-forge-subagents` package, which consumes this port and never imports main-package internals. See the [subagent host port contract](subagent-host-port.md).
 
 ## Prompt Stack Loading and Storage
 
@@ -69,7 +55,6 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` copies legacy stacks into the forge storage location.
 - `default.json` auto-activation unless `autoActivate` is `false`.
 - Branch-aware persisted active stack restore from session entries.
-- Branch-aware macro session variable restore when navigating the session tree.
 - Persisted `/preset use none` / `off` opt-out.
 - Invalid stacks with error diagnostics are skipped by automatic selection.
 - Raw stack fields are shape-checked before recovery normalization, including behavior-changing booleans/enums, defaults, context, variables, and item fields.
@@ -104,7 +89,7 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `effect: "outgoing"` is active for model-bound prompt text.
 - `effect: "finalize"` is active for completed assistant messages at `stage: "compiled"` / `targets: ["messages"]`.
 - `effect: "finalize"` is destructive: it replaces the finalized assistant message in Pi's stored transcript, so the original model output is not preserved.
-- `effect: "display"` and `"both"` validate with warnings and are ignored until true display transforms are implemented.
+- `effect: "outgoing"` and `"finalize"` are the only valid effects; `"display"` and `"both"` are rejected during validation.
 - Streaming display is not transformed; raw text may be visible until the final message replacement happens.
 - Message transforms support role filters, `maxMessages`, `maxChars`, `minDepth`, `maxDepth`, and `trimStrings`. `$0` is supported as a full-match alias for `$&` in replacements.
 - Compiled-stage transforms support `targets: ["system"]`, `["messages"]`, or both.
@@ -124,7 +109,6 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `date-cwd`
 - `active-model`
 - `pi-docs`
-- `variables`
 - `date` and `date-cwd` slots can include `Current time: HH:MM:SS` with `includeTime: true`.
 - Runtime slots are registered through the same `registerSlot` definition interface used by trusted custom slots.
 - Trusted `~/.pi/forge/extensions` / `.pi/forge/extensions` modules and reusable Pi packages can register additional runtime slots through `registerSlot`, with declarative option schemas and shared render helpers.
@@ -138,36 +122,29 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Tool policy is enforced with `pi.setActiveTools()` and restored when prompt stacks are disabled or switched to an unrestricted stack.
 - Tool policy preserves later extension tool additions in the restorable baseline while keeping them filtered from an active restrictive stack.
 - A `tool_call` guard blocks tools outside the active stack policy even if another extension later changes Pi's active tool list.
-- Rendered `tools` slots, tool macros such as `{{tools}}`, and `tool-guidelines` respect stack tool policy.
+- Rendered `tools` slots, template paths such as `{{ runtime.selectedToolsText }}`, and `tool-guidelines` respect stack tool policy.
 - Rendered `skills` slots respect stack skill policy and continue to hide skills marked `disableModelInvocation`.
 - Skill policy controls model-visible skill listings rendered by pi-forge; it does not disable explicit skill invocation and is not a security boundary.
 - Validation warns when skill policy is used with `append` or `prepend` mode because Pi's base prompt may already include unfiltered skills.
 
-## Macros
+## Macros (forge-v1)
 
-- Built-in macros: `{{cwd}}`, `{{date}}`, `{{time}}`, `{{lastUserMessage}}`, `{{selectedTools}}`, `{{tools}}`, `{{activeModel}}`.
-- Built-in macros are registered through the same `registerMacro` definition interface used by trusted custom macros.
-- Parser-backed macro expansion supports nested `{{...}}` expressions and `::` argument splitting at the current macro depth.
-- Filter macros: `{{trim::value}}`, `{{upper::value}}`, `{{lower::value}}`, `{{json::value}}`, and `{{xml::value}}`.
-- Lazy conditional macros: `{{ifvar::name::then::else}}`, `{{ifeq::name::expected::then::else}}`, `{{iftools::tool::then::else}}`, and `{{ifslot::slot::then::else}}`. Only the selected branch is expanded.
-- Trusted `~/.pi/forge/extensions` / `.pi/forge/extensions` modules and reusable Pi packages can register additional macros through `registerMacro`, with argument metadata and shared runtime/variable/helper access.
-- `getRegisteredMacros()` and `getRegisteredSlots()` expose the active macro/slot definitions for implementation references and UI/resource inspection.
-- Static stack variables from `stack.variables`.
-- Turn/session/static lookup through `{{getvar::name}}`, `{{var::name}}`, and bare `{{name}}`.
-- Turn variable mutation through `{{setvar::name::value}}`, `{{setturnvar::name::value}}`, and `{{clearvar::name}}`.
-- Session variable mutation through `{{setsessionvar::name::value}}`, `{{setvar::session::name::value}}`, and `{{clearsessionvar::name}}`.
-- Unknown macro diagnostics with configurable keep/warn/error policy.
-- Non-string variable values stringify as JSON during macro substitution.
+- Prompt text is compiled with the closed `forge-v1` template engine (parse → analyze → render).
+- Runtime facts resolve through `{{ runtime.* }}` (cwd, date, time, lastUserMessage, selectedToolsText, activeModel, tool/slot booleans).
+- Static values resolve through `{{ parameters.* }}`; schema v2 stores them in `parameters` while v1 stacks read legacy `variables`.
+- Custom macros resolve through `{{ extensions.<name> }}` and are registered via the pure `registerMacro` extension port with declared dependencies and bounded output.
+- Filters: `trim`, `upper`, `lower`, `json`, `xml`, composed with `|` pipelines.
+- Conditionals: `{% if path %}...{% else %}...{% endif %}` with `==` / `!=` string comparisons over template paths.
+- Undefined paths, unknown filters, parse errors, cycles, and output-limit breaches are compile errors; a failing block is omitted rather than re-injected.
+- Legacy v1 stacks keep a bare-name compatibility fallback (`{{name}}`, `{{lastUserMessage}}`, `{{date}}`, ...) that maps to the corresponding parameter/runtime path.
+- `getRegisteredMacros()` and `getRegisteredSlots()` expose active definitions for inspection.
 
-## Template Variables
+## Parameters
 
-- Static string variables from `stack.variables`.
-- JSON-compatible session variable values: string, number, boolean, null, arrays, and objects.
-- Session variable snapshots restore from the current session tree branch, so tree navigation rolls macro variables back/forward with history.
-- Valid `<variables>` rendering from the `variables` slot.
-- XML variable entries rendered as `<var name="...">...</var>`.
-- Optional `format: "plain"` variables slot rendering.
-- Scope toggles with `includeStatic`, `includeSession`, and `includeTurn`.
+- Schema v2 stacks store immutable JSON-compatible values in top-level `parameters`.
+- Schema v1 / unversioned stacks read the legacy string-only `variables` field and support bare `{{name}}` fallback.
+- Parameters resolve through `{{ parameters.<name> }}` and are available to trusted custom macros/slots through the frozen environment.
+- Mutable turn/session stores, variable mutation macros, session variable entries, and the `variables` slot are removed in 0.5.0.
 
 ## Commands
 
@@ -179,9 +156,9 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `/profile validate [id]`
 - `/profile reload`
 - `/profile forget`
-- `/forge-agent backends`
-- `/forge-agent plan <profile> <task>`
-- `/forge-agent run <profile> <task>`
+- `/forge-agent backends` (optional `@zihanw/pi-forge-subagents` package)
+- `/forge-agent plan <profile> <task>` (optional package)
+- `/forge-agent run <profile> <task>` (optional package)
 - `/preset list`
 - `/preset status`
 - `/preset use <id|none>`
@@ -191,29 +168,9 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - `/preset reload`
 - `/preset ui [stop|restart]`
 - `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]`
-- `/preset import-silly <path> [character_id] [--dry-run] [--overwrite]`
 - `/intercept`
 - `/payload next [save=<path>]`
 
-## SillyTavern Import
-
-- Import SillyTavern preset JSON into `.pi/forge/prompt-stacks/<id>.json`.
-- Generate import reports under `.pi/forge/import-reports/<id>.md`.
-- Select a specific `character_id` when multiple prompt orders exist.
-- Protect existing generated stack/report files from accidental overwrite, with confirmation or `--overwrite`.
-- Preview generated output without writing files via `--dry-run`.
-- Convert prompt order into prompt stack items.
-- Preserve original SillyTavern identifiers in item source metadata.
-- Convert `chatHistory` marker to a movable `chat-history` slot.
-- Skip unsupported SillyTavern marker items and report omissions.
-- Detect `{{lastUserMessage}}` and configure chat history accordingly.
-- Strip SillyTavern comments and `{{trim}}` markers.
-- Report macros that need manual migration, including normalized camelCase SillyTavern macro names.
-- Report supported SillyTavern-style variable macros such as `setvar` and `getvar` as handled by pi-forge.
-- Report SillyTavern `extensions.regex_scripts` counts, prompt/display classification, script names, and migration notes.
-- Convert safe SillyTavern `promptOnly` regex scripts into pi-forge `regex.rules` with `stage: "history"`, `effect: "outgoing"`, JavaScript replacement syntax, trim strings, depth limits, clear placement role mappings, and preserved `source.sillytavern` metadata. History-stage depth is relative to the filtered chat history, matching SillyTavern's chat-relative depth.
-- Leave SillyTavern display-only, mixed prompt/display, DOM/browser, CSS/HTML decoration, JavaScript, unsupported-placement, unsupported-flag, and invalid regex scripts as report-only migration notes.
-
 ## Debugging and Tests
 
 - `/intercept` displays the next provider payload with redaction/truncation for secrets and large data.
@@ -222,10 +179,9 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - The web editor can arm, poll, clear, and inspect the next redacted provider payload in a full-screen collapsible JSON inspector.
 - Runtime compile diagnostics are visible through a footer status and `/preset diagnostics`.
 - `/preset ui` starts a token-protected localhost web editor for stack management.
-- Node built-in tests cover agent-profile resolution/application/provenance, compiler, loader, SillyTavern importer, and the command/event harness.
-- Tests cover variable rendering, XML escaping, macro persistence, and typed macro stringification.
+- Node built-in tests cover agent-profile resolution/application/provenance, compiler, loader, regex, and the command/event harness.
 - Tests cover regex validation, history-stage transforms, compiled-stage transforms, finalize transforms, replacement syntax, trim strings, depth limits, role/message/char limits, and preservation of non-text message parts.
-- Tests cover subagent host resolution, custom dependency detection, all access/required-limit/terminal-status matrices, effect-aware tool negotiation, context budgeting, protected media tasks, canonical fingerprint tamper detection, and malformed external contract values.
+- Tests cover subagent host resolution, custom dependency detection, effect-aware tool negotiation, golden canonical fingerprint vectors, and malformed host-port wire values. Execution-contract matrices (access/required-limit/terminal-status, context budgeting, protected media tasks) moved to the optional package's contract tests.
 - A real headless-Chrome smoke test covers editor load, dirty state, metadata editing, policy and regex editing, validation, save, disk persistence, export, import, and browser-console errors.
 - TypeScript strict typecheck passes.
 - Package dry-run verifies published tarball contents.
@@ -264,16 +220,15 @@ This file tracks the currently implemented feature surface for agent profiles, t
 - Save existing stack JSON and immediately reload pi-forge stack data.
 - Save rejects attempts to change an existing stack ID before writing or changing active selection.
 - Keyboard shortcuts for new stack, save, validate, preview, and closing dialogs/inspectors.
-- Import native stack JSON or SillyTavern preset JSON into `.pi/forge/prompt-stacks`; SillyTavern uploads are converted automatically.
-- Show the SillyTavern import report in the web editor after import, with copy support.
+- Import native pi-forge stack JSON into `.pi/forge/prompt-stacks`.
 - Export the current edited stack JSON from the browser, with clipboard fallback when download is unavailable.
 - Fork the current stack into a new stack file, with optional activation.
 - Delete stack files, disabling prompt-stack replacement if the deleted stack was active.
 - Trust and path guardrails for save/import/fork/delete writes.
 - Top-level navigation between prompt stacks and project agent profiles; stack drafts, selection, and active state survive surface switches.
-- Profile list shows ID, name, model/thinking/stack targets, validation state, `autoActivate` and last-applied badges, and a `subagent` badge for delegation-enabled profiles.
+- Profile list shows ID, name, model/thinking/stack targets, validation state, and `autoActivate` and last-applied badges.
 - Profile create, edit, validate, save, one-shot apply, and delete reuse the shared resolver, transactional application service, and guarded repository; save rejects a second auto-activation profile and on-disk conflicts.
 - Profile form populates provider/model choices from the model registry and stack choices from the shared stack repository, and shows resolution diagnostics for missing models, authentication, unsupported thinking levels, invalid stacks, and unmatched tool policy.
 - A runtime/provenance card distinguishes current runtime, last-applied provenance, source-definition state, and per-field runtime drift after external model, thinking-level, or stack changes.
-- Per-profile delegation card toggles the trusted project's `subagents.profiles.<id>` opt-in with backend and timeout overrides, writing `.pi/forge/config.json` while preserving unrelated keys and removing emptied entries; the card reports the effective backend/timeout and source, warns about unregistered backends, and keeps project defaults and the unattended-invocation setting read-only.
-- Smoke tests cover editor server token checks, bundled page/script markers, save, payload arm/capture/clear, create/fork, SillyTavern JSON import conversion, collision handling, delete, and stop behavior.
+- The main web editor no longer ships a delegation card; delegation configuration is owned by the optional `@zihanw/pi-forge-subagents` package through `.pi/forge/subagents.json`.
+- Smoke tests cover editor server token checks, bundled page/script markers, save, payload arm/capture/clear, create/fork, native JSON import, collision handling, delete, and stop behavior.

package/docs/reference/macros-and-slots.md

@@ -1,56 +1,59 @@
-# Macros and runtime slots
+# Forge-v1 templates and runtime slots
 
 [Documentation](../README.md)
 
-## Value macros
+Prompt text is compiled with the `forge-v1` engine: one closed grammar with no
+includes, loops, function calls, or arbitrary expressions. Preview, runtime,
+and subagent preparation use the same engine entry.
 
-| Macro | Value |
-|---|---|
-| `{{lastUserMessage}}` | Latest user message |
-| `{{date}}` | Current date as `YYYY-MM-DD` |
-| `{{time}}` | Current time as `HH:MM:SS` |
-| `{{cwd}}` | Current working directory |
-| `{{tools}}` | Comma-separated selected tool names |
-| `{{selectedTools}}` | Alias of `{{tools}}` |
-| `{{activeModel}}` | Current `provider/model` |
-| `{{name}}` | Turn, session, then static variable lookup |
-| `{{var::name}}` / `{{getvar::name}}` | Explicit scoped-fallback variable lookup |
-| `{{getturnvar::name}}` | Turn-only lookup |
-| `{{getsessionvar::name}}` | Session-only lookup |
-
-## Variable mutation
+## Template interpolation
 
-```text
-{{setvar::name::value}}             set a turn variable
-{{setturnvar::name::value}}         set a turn variable
-{{setsessionvar::name::value}}      set a session variable
-{{setvar::session::name::value}}    set a session variable
-{{clearvar::name}}                  clear using normal scope behavior
-{{clearturnvar::name}}              clear a turn variable
-{{clearsessionvar::name}}           clear a session variable
-```
+| Syntax | Value |
+|---|---|
+| `{{ runtime.cwd }}` | Current working directory |
+| `{{ runtime.date }}` | Current date as `YYYY-MM-DD` |
+| `{{ runtime.time }}` | Current time as `HH:MM:SS` |
+| `{{ runtime.lastUserMessage }}` | Latest user message |
+| `{{ runtime.selectedToolsText }}` | Comma-separated effective tool names |
+| `{{ runtime.activeModel }}` | Current `provider/model` |
+| `{{ parameters.<name> }}` | Static stack parameter |
+| `{{ extensions.<name> }}` | Registered custom macro value |
 
-Turn variables reset for each message. Session variables follow Pi's active session-tree branch. Static variables come from top-level `stack.variables`. Non-string JSON-compatible values stringify as JSON during substitution.
+Legacy v1 stacks keep a compatibility fallback: bare `{{name}}` resolves to a
+static parameter, `{{lastUserMessage}}`/`{{date}}`/`{{time}}`/`{{cwd}}` resolve
+to the matching `runtime.*` value, and registered custom macros resolve by
+name. New v2 stacks use the explicit `parameters.*` / `runtime.*` paths.
 
-## Filters and conditionals
+## Filters
 
-Nested macros are supported. `::` separators are parsed only at the current macro depth.
+Nested pipelines are supported; filters are pure and versioned.
 
-| Macro | Result |
+| Filter | Result |
 |---|---|
-| `{{trim::value}}` | Trim surrounding whitespace |
-| `{{upper::value}}` | Uppercase value |
-| `{{lower::value}}` | Lowercase value |
-| `{{json::value}}` | JSON string literal |
-| `{{xml::value}}` | XML-escaped value |
-| `{{ifvar::name::then::else}}` | Select by variable existence |
-| `{{ifeq::name::expected::then::else}}` | Select by equality |
-| `{{iftools::tool::then::else}}` | Select by effective tool name |
-| `{{ifslot::slot::then::else}}` | Select by enabled slot name |
+| `{{ value \| trim }}` | Trim surrounding whitespace |
+| `{{ value \| upper }}` | Uppercase |
+| `{{ value \| lower }}` | Lowercase |
+| `{{ value \| json }}` | JSON string literal |
+| `{{ value \| xml }}` | XML-escaped |
+
+## Conditionals
+
+```text
+{% if runtime.tool.read %}read is available{% else %}read is unavailable{% endif %}
+{% if parameters.mode == "image-reader" %}image reader{% endif %}
+{% if runtime.tool.bash != null %}bash visible{% endif %}
+```
 
-The final `else` is optional. Branches are lazy: skipped branches are not expanded and cannot mutate variables.
+- `{% if path %}` selects the branch when the path exists and is truthy.
+- `==` / `!=` compare against a quoted string, including empty strings.
+- Nested `{% if %}` blocks are supported.
+- An undefined output path is a strict compile error (no raw fallback); the
+  legacy `defaults.unresolvedMacroPolicy` is ignored.
+- `runtime.tool.<name>` and `runtime.slot.<name>` booleans power tool/slot
+  conditionals without function calls.
 
-Unknown macro behavior is controlled by stack `defaults.unknownMacro`: keep, warn, or error according to schema validation.
+When a block fails to parse, analyze, or render, pi-forge emits an error
+diagnostic and omits that block rather than re-injecting raw template text.
 
 ## Built-in slots
 
@@ -62,21 +65,39 @@ Unknown macro behavior is controlled by stack `defaults.unknownMacro`: keep, war
 | `skills` | Model-visible loaded Pi skills |
 | `project-context` | Trusted project instructions/context |
 | `append-system-prompt` | Pi's appended system prompt text |
-| `variables` | Static/session/turn values |
 | `date` | Current date, optionally time |
 | `cwd` | Working directory |
 | `date-cwd` | Date and working directory, optionally time |
 | `active-model` | Selected provider/model |
 | `pi-docs` | Pi documentation guidance |
 
-Structured slots (`tools`, `tool-guidelines`, `skills`, `project-context`, `variables`) default to XML-style wrappers and support `"format": "plain"`.
-
-Notable Pi-mirror options include `tools.onlyWithSnippets`, `tool-guidelines.heading`, `tool-guidelines.includePiDefaultGuidelines`, `tool-guidelines.piStyle`, and `skills.requireReadTool`. `date` and `date-cwd` support `includeTime: true`.
+Structured slots (`tools`, `tool-guidelines`, `skills`, `project-context`)
+default to XML-style wrappers and support `"format": "plain"`.
 
-`variables` supports `includeStatic`, `includeSession`, `includeTurn`, and `format`.
+## Trusted custom definitions
 
-The complete `chat-history` option set is documented in [stack schema](stack-schema.md#chat-history-options).
+Trusted global/project modules register macros (addressed as
+`{{ extensions.<name> }}`) and slots through the pure extension port:
+
+```ts
+api.registerMacro({
+  name: "ticketId",
+  description: "Current ticket id.",
+  dependencies: ["parameters.ticket.id"],
+  render: ({ env, helpers }) => String(env.parameters["ticket.id"]),
+});
+
+api.registerSlot({
+  name: "ticket-context",
+  description: "Render ticket context.",
+  dependencies: ["parameters.ticket.id"],
+  options: { heading: { type: "string", default: "Ticket context" } },
+  render: ({ item, options, env, helpers }) => "...",
+});
+```
 
-## Trusted custom definitions
+Custom slots receive the same pure `{ item, options, env, helpers }` context and
+declared-dependency resolution as macros, and their output is held to the same
+16,384-character extension limit.
 
-Trusted global/project modules and reusable Pi packages can register additional macro and slot names. The runtime exposes the active definitions through `getRegisteredMacros()` and `getRegisteredSlots()`. See [custom macros and slots](../guides/custom-macros-and-slots.md).
+See [custom macros and slots](../guides/custom-macros-and-slots.md).