@zihanw/pi-forge 0.4.0 → 0.5.0

package/docs/development/scoped-global-profiles-stacks.md

@@ -0,0 +1,325 @@
+# Scoped global profiles and prompt stacks
+
+[Documentation](../README.md) · [Roadmap](roadmap.md)
+
+Status: accepted design; implementation complete for 0.4.1 (identity, catalogs, scoped stacks/profiles, persistence, auto-activation, delegation, zh-CN docs, and web-editor global create/fork/import with explicit scope). Historical record: the delegation-policy references to `.pi/forge/config.json` `subagents.*` below are superseded in 0.5 — delegation configuration moved to the optional package's dedicated `subagents.json` files (see the [0.5 migration guide](../guides/migrating-to-0.5.md)).
+
+## Confirmed design decisions
+
+Recorded before implementation started; these resolve the options left open by the analysis above.
+
+- **D1** Unified resource ID grammar: `/^[A-Za-z0-9][A-Za-z0-9._-]*$/` for both profiles and stacks. `:` is reserved for scope qualification and rejected in JSON IDs (with a diagnostic, not a load failure).
+- **D2** When capturing/saving a profile, `promptStack` is serialized relative to the target profile scope: same scope writes a bare ID, a different scope writes a qualified selector (`global:<id>`), and a global profile is never allowed to reference a project stack (the save is rejected).
+- **D3** Global profiles/stacks are loaded and can be browsed/previewed in untrusted projects, but applying a profile or stack still requires project trust.
+- **D4** Subagent delegation remains entirely disabled in untrusted projects, including for global profiles.
+- **D5** `default.json` has no special auto-activation role anymore. Only `autoActivate: true` participates in standalone stack activation. A `default.json` without an explicit `autoActivate` field receives a one-time migration warning; `autoActivate: false` remains an explicit opt-out. Multiple `autoActivate: true` stacks in the same scope fail closed.
+- **D6** Legacy provenance records without a scope field are interpreted as project-scoped.
+- **D7** `forge_subagent` accepts a bare `profileId` through effective lookup (project first) and `global:<id>` for exact global access; tool descriptions and `forge_subagent_profiles` explain the canonical selectors.
+- **D8** New session entries and provenance persist the string selector form (`project:<id>` / `global:<id>`); `none` stays a scope-independent bare opt-out.
+- **D9** Runtime state keeps flat `Loaded*[]` arrays whose entries carry `scope`/`key`; a shared catalog module owns `all`/`effective`/exact resolution.
+- **D10** Web editor API routes encode scope as a single path segment (`scope:id`, e.g. `/api/stacks/global:reviewer`).
+- **D11** A new `PI_FORGE_GLOBAL_DIR` environment override replaces the real `~/.pi/forge` for tests and embedders; loaders accept an explicit global Forge directory, and `globalForgeDir()` is only the default.
+- **D12** Slice 5 is split into 5a (forge-config data model, scoped authorization, and unit tests) and 5b (discovery, tool descriptions, approval display, commands, docs, and browser verification).
+- **D13** The web editor may edit/delete global resources when the route uses an explicit scope; unqualified routes remain project-only.
+
+
+This note defines the resource identity, lookup, activation, persistence, and delegation model for adding user-global agent profiles and prompt stacks without weakening project shadowing or authorization boundaries.
+
+## Goals
+
+- Reuse profiles and prompt stacks across projects.
+- Keep common commands concise through project-over-global shadowing.
+- Preserve an explicit way to address either scope when IDs collide.
+- Make stored profile dependencies deterministic rather than dependent on later shadowing.
+- Keep global and project delegation authorization separate.
+- Preserve existing project-only files and unqualified commands where no collision exists.
+
+## Non-goals
+
+- Do not add inheritance or merging between two profile or stack definitions.
+- Do not make profiles continuously own runtime state.
+- Do not move tool or skill policy from prompt stacks into profiles.
+- Do not let a global profile depend on project-controlled prompt content.
+- Do not add writable subagents, compaction settings, or a concurrency cap as part of this feature.
+
+## Storage and identity
+
+Global resources use the existing user-owned Forge root:
+
+```text
+~/.pi/forge/prompt-stacks/*.json
+~/.pi/forge/agent-profiles/*.json
+```
+
+Project resources keep their current locations:
+
+```text
+<project>/.pi/forge/prompt-stacks/*.json
+<project>/.pi/forge/agent-profiles/*.json
+```
+
+The JSON `id` remains an unqualified value such as `reviewer`. Scope comes from the storage location and must not be duplicated as an editable field in the file.
+
+Every loaded resource must carry a first-class scoped identity:
+
+```ts
+type ResourceScope = "global" | "project";
+
+interface ResourceKey {
+	scope: ResourceScope;
+	id: string;
+}
+```
+
+Do not repeatedly infer scope from `filePath`. Loaded profiles and stacks should expose their scope/key directly, and runtime state should compare keys rather than bare IDs.
+
+Duplicate IDs are errors only within one scope. A project and global resource with the same ID form a valid shadow pair.
+
+## Selector syntax
+
+Commands, completion candidates, profile stack references, persisted diagnostics, and delegation discovery use one selector grammar:
+
+```text
+reviewer
+project:reviewer
+global:reviewer
+```
+
+Existing resource IDs cannot contain `:`, so qualification is unambiguous. Reject unknown scope prefixes, empty IDs, and malformed selectors with a specific diagnostic.
+
+The canonical formatter should return:
+
+- `reviewer` only when presenting the effective unqualified resource;
+- `project:reviewer` or `global:reviewer` when exact identity matters;
+- qualified selectors for both resources when a collision must be shown.
+
+Internally, parse selectors into `{ scope?: ResourceScope; id: string }` and resolve them to a required `ResourceKey` before mutation, application, persistence, or delegation.
+
+## Two lookup modes
+
+Unqualified interactive selection and unqualified profile dependencies deliberately use different lookup rules.
+
+### Effective lookup
+
+Commands such as `/preset use` and `/profile use` use effective lookup:
+
+1. A qualified selector resolves only the named scope.
+2. An unqualified selector resolves the project resource when present.
+3. Otherwise it resolves the global resource.
+4. A project definition shadows the same-ID global definition even when the project definition is invalid. The invalid shadow fails closed; it must not silently fall back to the global resource.
+
+Examples:
+
+```text
+/profile use reviewer          # project first, otherwise global
+/profile use global:reviewer   # exact global profile
+/preset use project:reviewer   # exact project stack
+```
+
+Both colliding resources remain inspectable and explicitly selectable. Shadowing is an ergonomic default, not deletion of the global definition.
+
+### Profile dependency lookup
+
+A profile's `promptStack` is a stored dependency and must remain stable when unrelated files are later added. Its unqualified reference therefore resolves relative to the profile's own scope rather than through effective lookup.
+
+| Profile scope | `"reviewer"` | `"project:reviewer"` | `"global:reviewer"` |
+|---|---|---|---|
+| Project | project stack | project stack | global stack |
+| Global | global stack | rejected | global stack |
+
+Consequences:
+
+- A project profile may use either a project stack or an explicitly qualified global stack.
+- A project profile with `"promptStack": "reviewer"` does not fall back to a global stack when the project stack is missing. The diagnostic should suggest `global:reviewer` when that global stack exists.
+- A global profile may use only global stacks. `project:*` is rejected even if the project is trusted.
+- Adding a project stack later cannot silently change the dependency of a project profile that explicitly uses `global:reviewer`.
+- A project cannot replace the prompt or tool policy of a user-authorized global profile.
+
+The string form remains sufficient for profile schema v1 because qualification expands the accepted reference syntax without adding a new field or object shape. Existing project profiles keep resolving their unqualified stack IDs to project stacks.
+
+## Loading and catalogs
+
+Global definitions are user-owned and may load independently of project trust. Project definitions load only when the project is trusted.
+
+Pure loaders and tests must not accidentally read the developer's real home directory. Prefer an explicit catalog/repository input for the global Forge directory over relying on a process-wide environment variable. Existing project-only public loader functions may remain as compatibility wrappers while the extension runtime adopts scoped catalog loaders.
+
+Maintain both views:
+
+- `all`: every loaded scoped definition, including shadowed resources;
+- `effective`: one resource per unqualified ID after project-over-global shadowing.
+
+Centralize resolution helpers instead of continuing to use bare `array.find(candidate.id === id)` calls. Application, preview, mutation, auto-activation, subagent preparation, and the editor must resolve through the same catalog semantics.
+
+## Selection and persistence
+
+New session entries must persist the exact scoped key, not just the bare ID. This prevents a restored global selection from changing to a newly created project shadow after reload or tree navigation.
+
+For compatibility:
+
+- Read legacy branch entries containing only `activeStackId` using effective lookup.
+- Write new entries with a scoped active-stack reference.
+- Preserve the explicit `none`/`off` selection as a scope-independent opt-out.
+- Profile provenance should add the profile scope/key while continuing to accept older provenance that has only `profileId` and `sourcePath`.
+- Drift snapshots should store the resolved scoped stack reference so status can distinguish definition changes from a scope change.
+
+Profile application remains transactional and one-shot. Later manual model/thinking changes remain respected; the selected stack continues enforcing its existing policy exactly as it does now.
+
+## Auto-activation
+
+Restored branch state and explicit opt-out continue to take precedence over all fresh-session defaults.
+
+For agent profiles:
+
+1. Inspect project `autoActivate: true` candidates first.
+2. If any project candidate exists, do not fall back to a global candidate.
+3. Exactly one usable project candidate applies; an invalid or ambiguous project selection fails closed.
+4. If no project candidate exists, apply the same rules to global candidates.
+5. A project and global auto-activation candidate are not a conflict because project scope has explicit precedence.
+
+For standalone prompt-stack activation, apply the same scope precedence after profile auto-activation has declined to select a profile:
+
+1. Only stacks with `autoActivate: true` participate; `default.json` has no filename-based activation role (D5).
+2. Resolve project candidates before global candidates.
+3. A same-ID project stack shadows the global stack, including an invalid shadow or `autoActivate: false` opt-out.
+4. Exactly one usable candidate applies; multiple `autoActivate: true` stacks in the same scope fail closed.
+5. Do not silently activate the global same-ID stack through an invalid or opted-out project shadow.
+6. Preserve the existing rule that agent-profile auto-activation takes precedence over standalone stack activation, including profiles whose `promptStack` is `null`.
+
+## Commands and editor behavior
+
+Unqualified commands use effective lookup. Qualified commands address exact scope.
+
+Recommended command behavior:
+
+```text
+/preset use reviewer
+/preset use global:reviewer
+/profile use project:reviewer
+/profile preview global:reviewer
+/profile save reviewer                 # project by default
+/profile save global:reviewer          # explicit global mutation
+```
+
+Mutations must resolve the target scope before computing a path. Existing overwrite, changed-file, containment, and symbolic-link protections apply independently to each storage root. Global mutation must always be explicit; an unqualified save/fork/import continues to target project storage.
+
+The web editor should:
+
+- show global/project badges on profiles and stacks;
+- show `shadows global:<id>` and `shadowed by project:<id>` states;
+- retain both resources in navigation when IDs collide;
+- require explicit scope for create, fork, import, save-as, and delete targets;
+- prevent editing a shadowed global resource through an unqualified project route;
+- keep the current token, trust, idle-state, overwrite, and browser-test protections for mutations.
+
+Completions may prefer concise unqualified effective selectors, but must also offer qualified selectors when a collision exists or when the user has begun typing a scope prefix.
+
+## Delegation boundary
+
+Delegation authorization follows the profile's scope, not the effective unqualified ID:
+
+- `~/.pi/forge/config.json` `subagents.profiles.<id>` authorizes only `global:<id>`.
+- `<project>/.pi/forge/config.json` `subagents.profiles.<id>` authorizes only `project:<id>`.
+- Same-ID global and project profiles never inherit enablement, backend, or timeout policy from one another.
+- General backend, timeout, and summary defaults retain their current global-then-project layering.
+- Deleting a profile clears delegation policy only from the matching scope's config.
+- A global profile remains bound to global prompt content even when a project profile or stack shadows the same ID.
+
+`forge_subagent_profiles` should return canonical callable selectors. When both scopes expose the same ID, the project profile may use the concise effective selector and the global profile must remain callable as `global:<id>`. The `forge_subagent` parameter, `/forge-agent` commands, embedded description summary, preparation lookup, approval display, fingerprints, and reports must retain exact scope.
+
+Global profiles are user-owned, but ordinary delegation safety does not change: profiles remain disabled unless authorized in the matching config, unattended invocation remains a separate trusted-project decision, and read-only still does not imply an OS sandbox.
+
+## Compatibility and migration
+
+- No files move automatically.
+- Existing `.pi/forge` and legacy `.pi/prompt-stacks` resources remain project-scoped.
+- Existing project profile `promptStack` strings remain project-relative.
+- Existing unqualified commands behave the same when no global collision exists.
+- Legacy bare-ID session entries restore through effective lookup; all new entries record scope.
+- Same-ID cross-scope definitions are valid and must not receive duplicate-ID errors.
+- Duplicate IDs within one scope keep the current fail-closed diagnostics.
+- Global `subagents.profiles` entries, which currently warn and are ignored, become scoped authorization for global profiles only. Document this behavior change prominently.
+- Public loaded-resource types may add scope/key metadata without removing existing fields; compatibility helpers should continue accepting legacy bare IDs where persisted data requires them.
+
+## Implementation slices
+
+Each slice should land with focused tests and leave the full verification surface green.
+
+### Slice 1: scoped identity and storage
+
+- Add `ResourceScope`, `ResourceKey`, selector parsing/formatting, and exact/effective resolution primitives.
+- Add global profile/stack directory and safe mutation-path helpers.
+- Add scope/key metadata to loaded resources.
+- Keep JSON IDs unqualified and validate selector syntax separately from ID syntax.
+- Add table-driven parser, formatter, storage-containment, and same-ID-key tests.
+
+Exit criterion: scoped resources can be represented and addressed without changing runtime loading behavior.
+
+### Slice 2: scoped stack catalog and persistence
+
+- Load global stacks plus trusted project/legacy stacks into `all` and `effective` views.
+- Implement project shadowing, exact qualified selection, and invalid-shadow fail-closed behavior.
+- Replace bare-ID runtime lookups with catalog resolution.
+- Persist scoped active-stack references and restore legacy bare-ID entries.
+- Apply scoped standalone stack auto-activation and explicit opt-out rules.
+
+Exit criterion: `/preset` runtime behavior, branch restoration, tool policy, preview, and stack diagnostics operate correctly across both scopes before profiles are migrated.
+
+### Slice 3: scoped profiles and dependency resolution
+
+- Load global and trusted-project profiles with duplicate and auto-activation diagnostics scoped correctly.
+- Implement the profile-to-stack resolution matrix.
+- Extend preview, application, rollback, provenance, drift, save, delete, and reload with exact scoped keys.
+- Preserve profile auto-activation precedence over standalone stacks.
+- Extend host/subagent profile snapshots and fingerprints with resolved scope where required without changing legacy provenance fingerprint interpretation.
+
+Exit criterion: global and project profiles apply deterministically, including explicit project-to-global stack reuse and rejection of global-to-project references.
+
+### Slice 4: commands and web editor
+
+- Add qualified parsing and completions to `/preset`, `/profile`, and editor APIs.
+- Make unqualified mutations project-scoped and global mutations explicit.
+- Show scope, collisions, shadow relationships, exact dependencies, and scoped drift in human surfaces.
+- Add real-browser coverage for browsing, applying, editing, forking, deleting, collision handling, and failed scoped preflight.
+
+Exit criterion: users can understand and manage both scopes without an unqualified action mutating a global resource.
+
+### Slice 5: scoped delegation, documentation, and release verification
+
+- Accept global profile authorization from global config and project profile authorization from project config.
+- Update discovery, embedded summaries, callable selectors, `/forge-agent`, preparation, approval, reports, and policy cleanup.
+- Test same-ID profiles with independent enablement/backend/timeout settings and no authority inheritance.
+- Update English and Chinese concepts, guides, commands, configuration, schema/reference, feature inventory, changelog, and roadmap.
+- Regenerate tracked browser assets and `dist`, then run `npm run verify` and a packed-install smoke test.
+
+Exit criterion: scoped ordinary use and scoped delegation are documented, fail closed, package-clean, and verified end to end.
+
+## Required scenario coverage
+
+At minimum, automated tests should cover:
+
+- Global-only, project-only, and same-ID collision lookup.
+- Exact global access while shadowed.
+- Invalid project shadow without global fallback.
+- Global profile to global stack.
+- Project profile to unqualified project stack.
+- Project profile to explicitly qualified global stack.
+- Missing project stack with a same-ID global suggestion but no fallback.
+- Rejected global profile to project stack.
+- Project auto-activation precedence, global fallback, ambiguity, invalid candidate, restored branch, and explicit opt-out.
+- `default.json` no longer auto-activates by filename; missing `autoActivate` yields a migration warning (D5).
+- Scoped session restoration after a new shadow appears.
+- Scoped provenance and drift after source edits or scope changes.
+- Independent global/project delegation authorization for the same ID.
+- Deletion clearing only matching-scope delegation policy.
+- Untrusted projects loading global resources but not project resources.
+- Web-editor collision navigation and explicit-scope mutation safeguards.
+
+## Architectural guardrails
+
+- Keep resolution in shared catalog/services; do not duplicate shadow rules across commands, the editor, and subagent code.
+- Never use project-over-global effective lookup for a stored global profile dependency.
+- Never infer delegation authority from a bare ID after profile resolution.
+- Never persist a new active selection or provenance record without exact scope.
+- Never silently fall back across scopes after an explicit selector or an invalid shadow.
+- Keep profile application transactional and tool/skill policy owned by the resolved prompt stack.
+- Require the complete unit, browser, type, generated-output, documentation, and package verification surface for the final slice.

package/docs/development/setup.md

@@ -14,6 +14,8 @@ pi
 
 Trust the project in Pi and use `/reload` when needed.
 
+Before making structural changes, read the [architecture and development rules](architecture-rules.md) and the active [0.5 architecture plan](../design/architecture-0.5.md). Boundary, schema, persistence, public API, and product changes require an accepted architecture decision before implementation.
+
 The npm package loads compiled `dist/index.js` and intentionally omits physical `src/` files. Clone or fork the repository to inspect or modify source; do not edit generated files in `node_modules`.
 
 ## Load the extension
@@ -67,9 +69,9 @@ Document the tested range separately from peer constraints. Pi-coupled experimen
 
 ## Package boundaries
 
-- `@zihanw/pi-forge` is the Pi extension and stable macro/slot registration surface.
-- `@zihanw/pi-forge/subagent` is the preferred experimental host-contract entry point.
-- `@zihanw/pi-subagent-runtime` owns execution lifecycle and fresh-process backends.
-- Legacy `@zihanw/pi-forge/src/*` aliases resolve to compiled compatibility modules and are not a promise that internals are public.
+- `@zihanw/pi-forge` is the Pi extension (default export) and the stable macro/slot registration surface; no other root exports or `src/*` aliases exist.
+- `@zihanw/pi-forge/subagent` is the experimental versioned host-port entry point (wire DTOs, validators, transport, client/host lifecycle, canonical fingerprints).
+- `@zihanw/pi-forge-subagents` is the optional package owning subagent execution, configuration, and the 0.4 execution contract.
+- `@zihanw/pi-subagent-runtime` owns execution lifecycle and fresh-process backends (a dependency of the optional package, not of the main package).
 
 See the [public API policy](../reference/public-api.md).

package/docs/getting-started.md

@@ -62,7 +62,7 @@ Select the model, thinking level, and prompt stack you want in Pi, then save the
 /profile use reviewer
 ```
 
-Profiles live in `.pi/forge/agent-profiles/*.json`. Applying one is a preflighted, one-shot operation: later manual model/thinking changes remain until you apply the profile again. Read [agent-profile concepts](concepts/agent-profiles.md) for validation, auto-activation, and drift semantics.
+Profiles live in `.pi/forge/agent-profiles/*.json` by default; `/profile save global:<id>` writes to `~/.pi/forge/agent-profiles`. Applying one is a preflighted, one-shot operation: later manual model/thinking changes remain until you apply the profile again. Read [agent-profile concepts](concepts/agent-profiles.md) for validation, auto-activation, and drift semantics.
 
 ## Storage and migration
 
@@ -70,12 +70,15 @@ Profiles live in `.pi/forge/agent-profiles/*.json`. Applying one is a preflighte
 |---|---|
 | `.pi/forge/prompt-stacks/` | Project prompt stacks |
 | `.pi/forge/agent-profiles/` | Project agent profiles |
-| `.pi/forge/config.json` | Trusted project configuration and delegation authorization |
+| `.pi/forge/config.json` | Trusted project configuration (`webEditor.*`) |
 | `.pi/forge/extensions/` | Trusted project macro/slot registration code |
-| `~/.pi/forge/config.json` | User defaults |
+| `~/.pi/forge/prompt-stacks/` | User-global prompt stacks |
+| `~/.pi/forge/agent-profiles/` | User-global agent profiles |
+| `~/.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. New stacks go to `.pi/forge/prompt-stacks`, and same-named new-location files shadow legacy ones. Migrate safely with:
+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:
 
 ```text
 /preset migrate-stacks --dry-run
@@ -87,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 and per-profile overrides are project-only because profiles are project-local. A global `~/.pi/forge/config.json` may define general `backend` and `timeoutMs` defaults; global `profiles` entries warn and are ignored. Disabled or unlisted IDs are hidden from discovery and rejected even if guessed.
+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
 
@@ -45,8 +43,16 @@ Humans use:
 
 `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 `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
+
+`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:
@@ -66,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
 
@@ -96,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.