@zihanw/pi-forge 0.1.0 → 0.3.0

package/README.md

@@ -1,286 +1,455 @@
 # pi-forge
 
-Pi extension package for prompt stack and agent profile management. This first milestone implements file-backed prompt stacks.
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-## Package setup
+![pi-forge header](https://raw.githubusercontent.com/MacroSony/pi-forge/main/assets/pi-forge-header-concept-1.png)
 
-This repository is a Pi package. Its package manifest exposes `./src/index.ts` as the extension entrypoint.
+**pi-forge** lets you customize how Pi thinks and behaves. It gives you prompt stacks — JSON files that can replace, append to, or prepend Pi's default system prompt while controlling the AI's personality, visible tools, conversation history layout, template variables, and prompt transforms.
 
-For local development in this checkout, `.pi/settings.json` points at the package root:
+Think of it as a character sheet for your AI agent.
 
-```json
-{
-  "packages": [".."]
-}
-```
+## What you can do with it
 
-After starting Pi in this directory, trust the project and use `/reload` if needed.
+- **Give Pi a personality** — turn it into a creative writer, a roleplay partner, a strict code reviewer, or anything in between.
+- **Switch contexts instantly** — one command to swap between "coding mode", "writing mode", and "translation mode".
+- **Control what the AI sees** — choose which tools, skills, and project context appear in each prompt.
+- **Limit tools and skills per stack** — enforce active tool policy and filter skill visibility for focused modes.
+- **Use template variables** — define static values such as `{{char}}` / `{{user}}`, and use ST-style turn/session variable macros inside prompt text.
+- **Transform outgoing and finalized text** — run deterministic regex replacements on selected history, compiled prompt text, or finalized assistant messages.
+- **Import SillyTavern presets** — bring your existing ST character presets into Pi with one command.
+- **Debug your prompts** — intercept and inspect exactly what gets sent to the model.
 
-After publishing under your chosen npm package name, install it with:
+## Quick start
+
+### Install
 
 ```bash
 pi install npm:@zihanw/pi-forge
 ```
 
-## Prompt stacks
+### Your first prompt stack
+
+Create `.pi/forge/prompt-stacks/default.json` from [examples/default-prompt-stack.json](examples/default-prompt-stack.json).
 
-Prompt stacks live in:
+The default example mirrors Pi's own prompt builder from `@earendil-works/pi-coding-agent/dist/core/system-prompt.js`, but splits it into movable pi-forge slots: role, tools, guidelines, Pi docs guidance, appended system prompt text, project context, skills, date/cwd, and chat history.
 
-```txt
-.pi/prompt-stacks/*.json
+```bash
+mkdir -p .pi/forge/prompt-stacks
+$EDITOR .pi/forge/prompt-stacks/default.json
 ```
 
-Activation rules:
+Paste the example JSON into that file. If you are working inside this repository, you can copy it directly with `cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json`.
 
-1. A restored `/preset use <id>` selection is used first when that stack still exists and has no validation errors.
-2. A restored `/preset use none` selection disables prompt stack replacement.
-3. `.pi/prompt-stacks/default.json` auto-activates when present unless the stack sets `"autoActivate": false`.
-4. Otherwise, the first stack with `"autoActivate": true` is used.
-5. `/preset use <id>` switches stacks for the session and persists that choice.
-6. `/preset use none` disables prompt stack replacement and persists that choice.
+That's it. Restart Pi or run `/preset reload`. If no stack is already selected, `default.json` auto-activates. If you previously chose another stack or `/preset use none`, run `/preset use default`.
 
-When a stack is active, pi-forge replaces Pi's default system prompt by default and rebuilds the first provider request for each user message around a movable `chat-history` slot. Tool-result follow-up turns use Pi's natural context so post-history instructions are not repeatedly re-appended after every tool call.
+### Visual editor
 
-## Commands
+Prefer clicking over typing JSON? pi-forge has a built-in web editor:
 
-```txt
-/preset list
-/preset use <id|none>
-/preset preview [id]
-/preset validate [id]
-/preset reload
-/preset vars [set <name> <value>|get <name>|clear [name]]
-/preset import-silly <path> [character_id]
-/intercept
+```
+/preset ui
 ```
 
-## SillyTavern preset import
+Drag, drop, edit, validate, inspect full previews and captured payloads, manage variables/context/regex rules in tabs, switch dark mode, recover through raw stack JSON, import, export, fork, and delete stacks — all in your browser. Stack metadata is collapsible so the active editor stays in view.
 
-Import a SillyTavern preset JSON into `.pi/prompt-stacks/<id>.json` and write a migration report to `.pi/forge/import-reports/<id>.md`:
+Import accepts native pi-forge stack JSON and SillyTavern preset JSON. SillyTavern presets are converted to prompt stacks automatically; if a preset contains multiple `character_id` configs, the editor asks which one to use.
 
-```txt
-/preset import-silly <path> [character_id]
+The editor runs on an available `127.0.0.1` port with a session token, so multiple Pi instances can run editors at the same time. If Pi reinitializes the extension after session navigation or a new session, `/preset ui` reuses the existing editor URL for the same project instead of orphaning the old server. Writes require a trusted project and stay inside prompt-stack storage. New stacks are written to `.pi/forge/prompt-stacks`; existing legacy stacks under `.pi/prompt-stacks` remain readable and editable. Successful save, import, fork, and delete actions reload into the current Pi session. Use `/preset ui restart` or `/preset ui stop` when needed.
+
+To copy old stacks into the new location, run `/preset migrate-stacks`. Add `--dry-run` to preview, `--overwrite` to replace existing target files, and `--delete-legacy` to remove old files after successful copy.
+
+To prefer a specific port, create `.pi/forge/config.json`. If that port is busy, pi-forge falls back to another available port and shows the actual URL:
+
+```json
+{
+  "webEditor": {
+    "port": 41738
+  }
+}
 ```
 
-If a preset contains multiple `prompt_order` entries, pass the desired `character_id`. Imported stacks are created with `autoActivate: false`; activate one with `/preset use <id>` after reviewing the report.
+## Use cases
+
+### 🎭 Roleplay & creative writing
 
-## Agent tools
+Turn Pi into a character. Define their personality in the system prompt, inject writing style rules as user messages, and use `{{lastUserMessage}}` to re-insert the user's input after the conversation history.
 
-### forge_set_var
+Useful pattern:
+- Put long-term character rules in a `system` block.
+- Keep Pi runtime context (tools, skills, project) in `user` slots.
+- Set the `chat-history` slot to skip the latest user message.
+- Add a final `user` block with `{{lastUserMessage}}`.
 
-Sets a persistent session variable. Only variables starting with `agent.` can be written by the agent; other variables are read-only. Useful for cross-turn state tracking in roleplay (character mood, story progress) or coding (task checkpoints, discovered facts).
+This keeps the latest request clear and avoids duplicating it.
 
-When the `variables` slot is active in a prompt stack, the agent sees its variable state and can update it. Without the slot, variables still work for macro substitution but the agent won't have a structured view of the state.
+For a baseline stack to fork before turning Pi into a character, start from [examples/default-prompt-stack.json](examples/default-prompt-stack.json).
 
-## Stack format
+### 🧑‍💻 Focused code review
 
-Minimal example:
+Create a `reviewer.json` stack with a strict review block: "prioritize correctness, regressions, security, and missing tests." Keep the `tools`, `project-context`, `variables`, and `chat-history` slots enabled so Pi can still inspect the repo and see any template variables you expose.
+
+Use `mode: "append"` if you want to keep Pi's normal coding behavior and only add the sharper review lens.
+
+### 🌐 Translation mode
+
+Create a small `translator.json` stack with one system block for tone and target language, then keep `chat-history` and `{{lastUserMessage}}` in the layout. This works well for switching between bilingual editing, literal translation, and localization review without changing your default assistant.
+
+### 🔀 Multi-mode switching
+
+Create separate stacks for different tasks:
+
+```
+.pi/forge/prompt-stacks/
+  coder.json       # strict coding assistant
+  writer.json      # creative writing partner
+  translator.json  # bilingual translator
+```
+
+Switch with `/preset use coder`, `/preset use writer`, etc.
+
+### 🧪 Presets that show off pi-forge
+
+- **Pi mirror** — start from [examples/default-prompt-stack.json](examples/default-prompt-stack.json). It preserves normal Pi behavior while making every runtime section movable and inspectable.
+- **Focused reviewer** — see [examples/reviewer-prompt-stack.json](examples/reviewer-prompt-stack.json). It denies file-writing tools, wraps prior chat history as background, removes the latest user message from history, then reinserts `{{lastUserMessage}}` as the explicit review target.
+- **Read-only scout** — use `tools.allow` for `read`, `grep`, `find`, and `ls`; omit editing tools; cap `chat-history` with `maxChars`. Good for exploration turns where the model should report findings without changing files.
+- **Surgical patcher** — keep the Pi mirror, require `read`, `edit`, and `bash`, strip assistant thinking from inserted history, and move `project-context` near the final user turn. Good for focused implementation passes.
+- **SillyTavern DM writer** — see [examples/sillytavern-dm-writer-prompt-stack.json](examples/sillytavern-dm-writer-prompt-stack.json). It defines a Dungeon Master character with `{{char}}` / `{{user}}`, wraps prior adventure history, reinserts `{{lastUserMessage}}` as the current player action, and uses regex cleanup for OOC notes, secret-roll markers, dice notation, and `Player:` prefixes.
+- **Payload lab** — include `active-model`, `date-cwd`, and variables slots, then add `compiled` regex rules for deterministic redaction or formatting. Pair it with `/payload next` or the web editor's capture view to audit exactly what changed.
+- **Docs-only Pi expert** — allow only read/search tools, enable the `pi-docs` slot, and keep project context. Useful when you want answers grounded in the installed Pi docs instead of general memory.
+
+### 🔧 Template variables
 
 ```json
-{
-  "schemaVersion": 1,
-  "type": "pi-forge.prompt-stack",
-  "id": "default",
-  "autoActivate": true,
-  "mode": "replace",
-  "items": [
-    {
-      "kind": "block",
-      "id": "main-role",
-      "enabled": true,
-      "role": "system",
-      "content": "You are a precise coding assistant."
-    },
-    {
-      "kind": "slot",
-      "id": "tools",
-      "enabled": true,
-      "role": "system",
-      "slot": "tools"
-    },
-    {
-      "kind": "block",
-      "id": "history-open",
-      "enabled": true,
-      "role": "user",
-      "content": "<conversation_context>"
-    },
-    {
-      "kind": "slot",
-      "id": "chat-history",
-      "enabled": true,
-      "slot": "chat-history"
-    },
-    {
-      "kind": "block",
-      "id": "history-close",
-      "enabled": true,
-      "role": "user",
-      "content": "</conversation_context>"
-    }
-  ]
+"variables": {
+  "char": "Konata",
+  "user": "User"
 }
 ```
 
-## Items
+Use static variables for stable prompt constants, and ST-style macros for local prompt-time mutation:
+
+```
+{{setvar::mood::focused}}
+{{getvar::mood}}
+{{setsessionvar::topic::compiler cleanup}}
+```
+
+For durable project memory, use normal files in the repo rather than pi-forge prompt variables.
+
+### 📦 SillyTavern migration
 
-### Blocks
+Bring your ST presets into Pi:
+
+```
+/preset import-silly ~/SillyTavern/presets/my-preset.json
+```
+
+pi-forge converts the preset to a prompt stack and generates a migration report showing what was handled and what needs manual tweaking.
+
+Deterministic SillyTavern `promptOnly` regex scripts are converted to pi-forge `regex.rules` as history-stage rules when they can be represented safely, including full-match token conversion, trim strings, depth fields, and clear user/assistant placements. Display-only, mixed prompt/display, DOM/browser, CSS/HTML decoration, JavaScript, unsupported placements, and invalid regex scripts stay report-only for manual review.
+
+### 🔍 Prompt debugging
+
+See exactly what gets sent to the model:
+
+```
+/payload next save=.pi/forge/payloads/last.json
+```
+
+Or open `/preset ui`, click **Arm payload**, send the next Pi prompt, and inspect the redacted provider payload in the browser.
+
+Or preview your compiled prompt without sending anything:
+
+```
+/preset preview
+```
 
-Static text:
+## How it works
+
+A prompt stack is a JSON file with two kinds of items:
+
+| Kind | What it does |
+|------|-------------|
+| **Block** | Static text inserted at a specific position (system prompt, user message, assistant message) |
+| **Slot** | Dynamic content from Pi's runtime — tools, skills, chat history, date, project context, etc. |
+
+Items are arranged in order. When the stack is active, pi-forge:
+
+1. Builds a system prompt from your `system`-role blocks and slots, then applies it with the stack's `mode`.
+2. Inserts `user`/`assistant` blocks and slots around the conversation history.
+3. Expands `{{macros}}` like `{{lastUserMessage}}`, `{{date}}`, and custom variables.
+4. Applies stack tool policy to Pi's active tool set and filters pi-forge-rendered tool/skill slots.
+5. Applies enabled outgoing regex rules for the `history` and `compiled` stages.
+6. Optionally applies destructive `finalize` regex rules when an assistant message finishes.
+
+### Slots at a glance
+
+| Slot | What it inserts |
+|------|----------------|
+| `chat-history` | The current conversation |
+| `tools` | Available tools and their descriptions |
+| `tool-guidelines` | Tool usage instructions |
+| `skills` | Loaded Pi skills |
+| `project-context` | Project instructions and context files |
+| `variables` | Static/session/turn template variables |
+| `date` / `cwd` / `date-cwd` | Current date and working directory |
+| `active-model` | Which model is being used |
+| `append-system-prompt` | User's appended system prompt text |
+| `pi-docs` | Pi documentation guidance |
+
+### Modes
+
+- **replace** (default) — your stack replaces Pi's system prompt entirely.
+- **append** — your stack is added after Pi's default system prompt.
+- **prepend** — your stack is added before Pi's default system prompt.
+
+## Common commands
+
+### Managing stacks
+
+| Command | What it does |
+|---------|-------------|
+| `/preset list` | Show all available stacks |
+| `/preset use <id>` | Activate a stack |
+| `/preset use none` | Disable prompt stacks for the session |
+| `/preset preview [id]` | See the compiled prompt |
+| `/preset validate [id]` | Check a stack for issues |
+| `/preset status` | Show the active stack and diagnostics summary |
+| `/preset diagnostics` | Show runtime diagnostics |
+| `/preset reload` | Reload stacks from disk |
+| `/preset migrate-stacks [--dry-run] [--overwrite] [--delete-legacy]` | Copy legacy `.pi/prompt-stacks` files into `.pi/forge/prompt-stacks` |
+| `/preset ui [stop\|restart]` | Open, stop, or restart the web editor |
+
+### Import & debug
+
+| Command | What it does |
+|---------|-------------|
+| `/preset import-silly <path>` | Import a SillyTavern preset |
+| `/intercept` | Show the next provider payload |
+| `/payload next [save=<path>]` | Show, save, and expose the next payload to the web editor |
+
+## Common macros
+
+Use these in block content to insert dynamic values:
+
+| Macro | Expands to |
+|-------|-----------|
+| `{{lastUserMessage}}` | The user's latest message |
+| `{{date}}` | Current date (YYYY-MM-DD) |
+| `{{time}}` | Current time (HH:MM:SS) |
+| `{{cwd}}` | Current working directory |
+| `{{tools}}` | Comma-separated tool names |
+| `{{selectedTools}}` | Alias for selected tool names |
+| `{{activeModel}}` | Current model (provider/id) |
+| `{{char}}` / `{{user}}` | Custom variables from your stack |
+
+### Variable macros
+
+```
+{{setvar::name::value}}       set a turn variable (cleared each message)
+{{setsessionvar::name::value}} set a session variable (persists)
+{{setvar::session::name::value}} also set a session variable
+{{getvar::name}}              read a variable (turn → session → static)
+{{getturnvar::name}}          read only a turn variable
+{{getsessionvar::name}}       read only a session variable
+{{clearvar::name}}            clear a variable
+{{clearturnvar::name}}        clear a turn variable
+{{clearsessionvar::name}}     clear a session variable
+```
+
+## Stack reference
+
+### Full item types
+
+**Block:**
 
 ```json
 {
   "kind": "block",
-  "id": "post-history-nudge",
+  "id": "unique-id",
+  "name": "Readable label",
   "enabled": true,
-  "role": "user",
-  "content": "Reason carefully about the latest request before answering."
+  "role": "system",
+  "content": "Your text here. Use {{macros}} for dynamic content."
 }
 ```
 
-### Slots
+Valid roles: `system`, `user`, `assistant`, `custom`.
 
-Live Pi runtime content:
+**Slot:**
 
 ```json
 {
   "kind": "slot",
-  "id": "skills",
+  "id": "unique-id",
+  "name": "Chat History",
   "enabled": true,
-  "role": "system",
-  "slot": "skills"
+  "role": "user",
+  "slot": "chat-history",
+  "options": {
+    "includeLastUserMessage": false
+  }
 }
 ```
 
-Supported slots:
-
-- `chat-history` — current Pi conversation context from the session
-- `tools` — active tool names and prompt snippets
-- `tool-guidelines` — active tool guidance
-- `skills` — loaded Pi skills
-- `project-context` — project instructions/context files
-- `append-system-prompt` — user-provided append system prompt text
-- `variables` — static/session/turn variables rendered as structured XML
-- `date`
-- `cwd`
-- `date-cwd`
-- `active-model`
-- `pi-docs`
-
-### Variables slot
-
-Renders variable state as structured XML:
-
-```xml
-<prompt_variables>
-  <static>
-    <char>Agent</char>
-  </static>
-  <session>
-    <agent.mood>happy</agent.mood>
-    <agent.progress>step 3</agent.progress>
-  </session>
-  <turn>
-    <recent>just happened</recent>
-  </turn>
-</prompt_variables>
-```
-
-Options:
+### Chat history options
 
 ```json
-{
-  "includeStatic": true,
-  "includeSession": true,
-  "includeTurn": true
+"options": {
+  "includeLastUserMessage": false,
+  "stripAssistantThinking": true,
+  "includeSummaries": true,
+  "toolMode": "keep",
+  "roles": ["user", "assistant"],
+  "maxMessages": 40,
+  "maxChars": 20000
 }
 ```
 
-Use this slot to give the agent visibility into mutable state that it can also update via `forge_set_var`.
+Set to `false` when you use `{{lastUserMessage}}` after the history — prevents the user's message from appearing twice.
 
-## Roles
+Set `stripAssistantThinking` to `true` to remove prior assistant thinking blocks from inserted chat history. Visible assistant text, tool calls, and tool result messages are preserved. This only affects history inserted by that slot and does not alter the current agent loop or stored transcript.
 
-- `system` items are compiled into the replacement system prompt.
-- `user` items are inserted as ephemeral user messages.
-- `assistant` items are inserted as ephemeral assistant messages.
-- `custom` items are inserted as hidden Pi custom messages and converted to user context by Pi.
+Use `includeSummaries: false` to omit Pi branch/compaction summary messages, `roles` to keep only specific message roles, `toolMode: "drop"` to remove prior tool-call/tool-result history, and `maxMessages` / `maxChars` to keep only recent history. When filters or limits can break tool-call pairs, pi-forge removes dangling tool calls/results instead of sending inconsistent tool history.
 
-`chat-history` expands to the live conversation at its position. By default, only the first enabled `chat-history` slot is expanded.
+### Structured slot format options
 
-To omit the latest user message from a chat history slot, use:
+Structured runtime slots default to XML-style wrappers. Add `"format": "plain"` to `tools`, `tool-guidelines`, `skills`, `project-context`, or `variables` slots for compact newline-separated output.
 
 ```json
 {
   "kind": "slot",
-  "id": "chat-history",
+  "id": "tools",
   "enabled": true,
-  "slot": "chat-history",
+  "role": "system",
+  "slot": "tools",
   "options": {
-    "includeLastUserMessage": false
+    "format": "plain"
   }
 }
 ```
 
-This is useful for SillyTavern-style stacks that re-insert `{{lastUserMessage}}` later as a post-history instruction.
+The default Pi mirror uses a few extra slot options:
 
-To intentionally duplicate history:
+```json
+{
+  "slot": "tools",
+  "options": {
+    "format": "plain",
+    "onlyWithSnippets": true
+  }
+}
+```
+
+`tools.onlyWithSnippets` matches Pi's default "Available tools" section by hiding tools that do not provide prompt snippets. `tool-guidelines.heading`, `tool-guidelines.includePiDefaultGuidelines`, and `tool-guidelines.piStyle` make the guidelines slot match Pi's default heading and bullets. `skills.requireReadTool` hides skills unless the read tool is active, matching Pi's default behavior.
+
+### Tool and skill policy
+
+Prompt stacks can constrain tools and skills with stack-level `allow` or `deny` lists. Patterns are exact by default and support `*` wildcards.
 
 ```json
 {
-  "context": {
-    "allowDuplicateChatHistory": true
+  "tools": {
+    "allow": ["read", "bash"]
+  },
+  "skills": {
+    "deny": ["browser-danger"]
   }
 }
 ```
 
-## Macros
+Use `allow` when only matching tools or skills should remain active. Use `deny` when everything except matching tools or skills should remain active. A single resource policy cannot contain both non-empty lists; mixed `allow` and `deny` entries are validation errors.
 
-Supported macros in block content:
+Tool policy is enforced through Pi's active tool list while the stack is active. pi-forge remembers the previous active tools and restores them when prompt stacks are disabled or switched to an unrestricted stack.
 
-- `{{cwd}}`
-- `{{date}}`
-- `{{lastUserMessage}}`
-- `{{selectedTools}}` / `{{tools}}`
-- `{{activeModel}}`
-- custom variables from the stack `variables` object, e.g. `{{char}}`
+Skill policy filters skills rendered by pi-forge's `skills` slot. If a stack uses `mode: "append"` or `"prepend"`, Pi's base prompt may already contain unfiltered skills; use `mode: "replace"` when skill visibility must be controlled.
 
-### Variables
+### Regex transforms
 
-Static variables come from the stack file:
+Prompt stacks can run deterministic regex replacements on model-bound prompt text and, optionally, finalized assistant messages. Outgoing rules support `history` and `compiled` stages. Destructive final-message cleanup uses `effect: "finalize"` at `stage: "compiled"` with the `messages` target. True display-only streaming transforms and provider-payload rewrites are not active yet.
 
 ```json
-"variables": {
-  "char": "Assistant",
-  "user": "USER"
+"regex": {
+  "schemaVersion": 1,
+  "rules": [
+    {
+      "id": "trim-ooc",
+      "enabled": true,
+      "stage": "history",
+      "effect": "outgoing",
+      "pattern": "\\(OOC:[^)]+\\)",
+      "flags": "gi",
+      "replace": "",
+      "roles": ["assistant"],
+      "maxMessages": 20
+    }
+  ]
 }
 ```
 
-Mutable turn variables are cleared for each user message:
+Use `stage: "history"` to transform messages inserted by the `chat-history` slot. Use `stage: "compiled"` with optional `targets: ["system"]`, `["messages"]`, or both to transform the final compiled prompt. Message rules can filter by `roles`, `maxMessages`, `maxChars`, `minDepth`, and `maxDepth`, where depth `0` is the latest message. Replacements use JavaScript syntax (`$&` for the full match, `$1` for captures; `$0` is also accepted as a full-match alias, and `$$` escapes a literal `$`). `trimStrings` removes literal strings from expanded replacement matches/captures, matching SillyTavern's Trim Out behavior. Supported regex flags are `g`, `i`, `m`, `s`, and `u`.
 
-```txt
-{{setvar::name::value}}
-{{setturnvar::name::value}}
-{{getvar::name}}
-{{getturnvar::name}}
-{{var::name}}
-{{clearvar::name}}
+To clean a completed assistant message after streaming, use `effect: "finalize"`:
+
+```json
+{
+  "id": "finalize-ooc",
+  "enabled": true,
+  "stage": "compiled",
+  "effect": "finalize",
+  "targets": ["messages"],
+  "roles": ["assistant"],
+  "pattern": "\\s*\\(OOC:[^)]+\\)",
+  "flags": "gi",
+  "replace": ""
+}
 ```
 
-Mutable session variables persist in the Pi session as extension state:
+Warning: `finalize` runs at `message_end`, after raw output may already have streamed in the TUI. It returns a cleaned replacement message to Pi, so the original model output is not preserved in the stored transcript.
+
+`effect: "outgoing"` changes model input. `effect: "finalize"` changes finalized assistant transcript content. `effect: "display"` and `"both"` validate with warnings but are ignored at runtime until true display transforms are implemented.
+
+SillyTavern imports convert deterministic prompt-only `{{match}}` / `$0` full-match replacements to JavaScript `$&` (both `$0` and `$&` work in pi-forge), preserve original regex metadata in `source.sillytavern`, and run as history-stage rules so depth stays chat-relative. Display-only/browser/unsupported-placement scripts stay report-only. The web editor has a structured Regex dialog for these rule fields and preserves advanced unknown fields for raw JSON editing.
+
+### Variables slot options
 
-```txt
-{{setsessionvar::name::value}}
-{{setvar::session::name::value}}
-{{getsessionvar::name}}
-{{getvar::name}}
-{{clearsessionvar::name}}
-{{clearvar::session::name}}
+```json
+{
+  "kind": "slot",
+  "id": "variables",
+  "enabled": true,
+  "role": "user",
+  "slot": "variables",
+  "options": {
+    "includeStatic": true,
+    "includeSession": true,
+    "includeTurn": false,
+    "format": "xml"
+  }
+}
+```
+
+## Package setup for development
+
+```bash
+git clone <repo>
+cd pi-forge
+# .pi/settings.json already points at the package root
+pi    # start Pi, trust the project, /reload if needed
 ```
 
-Lookup order for `{{getvar::name}}`, `{{var::name}}`, and bare `{{name}}` is:
+Run tests:
+
+```bash
+npm test
+```
+
+Typecheck:
+
+```bash
+npm run typecheck
+```
 
-1. turn variables
-2. session variables
-3. static stack variables
+## License
 
-`setvar` macros output empty text. Unknown macros warn by default and are kept literally.
+MIT