@ai-agent-forge/agent-forge 0.88.1 → 0.88.2

package/docs/usage.md

@@ -1,292 +1,292 @@
-# Using Agent Forge
-
-This page collects day-to-day usage details that do not fit on the quickstart page.
-
-## Interactive Mode
-
-<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
-
-The interface has four main areas:
-
-- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and themes
-- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, and errors
-- **Editor** - where you type; border color indicates the current thinking level
-- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
-
-The editor can be replaced temporarily by built-in UI such as `/settings` or `/model`.
-
-### Editor Features
-
-| Feature | How |
-|---------|-----|
-| File reference | Type `@` to fuzzy-search project files |
-| Path completion | Press Tab to complete paths |
-| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
-| Copy response | Ctrl+X copies the selected message in `/tree`; otherwise it copies the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
-| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
-| Shell command | `!command` runs and sends output to the model |
-| Hidden shell command | `!!command` runs without sending output to the model |
-| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
-
-See [Keybindings](keybindings.md) for all shortcuts and customization.
-
-## Slash Commands
-
-Type `/` in the editor to open command completion. Capability plugins can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
-
-| Command | Description |
-|---------|-------------|
-| `/login`, `/logout` | Manage OAuth or API-key credentials |
-| [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
-| `/model` | Switch models; Ctrl+S in the picker saves the startup default |
-| `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
-| `/scoped-models` | Enable/disable models for model cycling (bindable, no default key) |
-| `/settings` | Theme, message delivery, transport, and other preferences |
-| `/resume` | Pick from previous sessions |
-| `/new` | Start a new session |
-| `/name <name>` | Set session display name |
-| `/session` | Show session file, ID, messages, tokens, and cost |
-| `/tree` | Jump to any point in the session and continue from there |
-| `/fork` | Create a new session from a previous user message |
-| `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
-| `/copy` | Copy last assistant message to clipboard |
-| `/export [file]` | Export session to HTML or JSONL |
-| `/import <file>` | Import and resume a session from a JSONL file |
-| `/share` | 由显式安装的 session-share 插件提供；核心不内置 |
-| `/reload` | Reload keybindings, skills, prompts, themes, and context files |
-| `/hotkeys` | Show all keyboard shortcuts |
-| `/changelog` | Display version history |
-| `/quit` | Quit Agent Forge |
-
-## Message Queue
-
-You can submit messages while the agent is still working:
-
-- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
-- **`/queue <text>`** queues a follow-up message, delivered after the agent finishes all work.
-- **Escape** aborts and restores queued messages to the editor.
-- **`/dequeue`** restores queued messages back to the editor.
-- **`/queue-list`** opens the queued-message manager (both queues): reorder entries with alt+up / alt+down, delete one with delete, recall one to the editor with enter, close with escape.
-
-Follow-up queueing and dequeue are command-only by default (their shipped keybinding defaults were cleared per the single-entry-point rule, 2026-10-01); bind `app.message.followUp` / `app.message.dequeue` in `keybindings.json` if you want keys (see [Keybindings](keybindings.md)).
-
-Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
-
-## Sessions
-
-Sessions are saved automatically to `~/.agent-forge/agent/sessions/`, organized by working directory.
-
-```bash
-agent-forge -c                  # Continue most recent session
-agent-forge -r                  # Browse and select a session
-agent-forge --no-session        # Ephemeral mode; do not save
-agent-forge --name "my task"    # Set session display name at startup
-agent-forge --session <path|id> # Use a specific session file or session ID
-agent-forge --fork <path|id>    # Fork a session into a new session file
-```
-
-Useful session commands:
-
-- `/session` shows the current session file and ID.
-- `/tree` navigates the in-file session tree and can summarize abandoned branches.
-- `/fork` creates a new session from an earlier user message.
-- `/clone` duplicates the current active branch into a new session file.
-- `/compact` summarizes older messages to free context.
-
-See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
-
-## Context Files
-
-Agent Forge loads `AGENTS.md` or `CLAUDE.md` at startup from:
-
-- `~/.agent-forge/agent/AGENTS.md` for global instructions
-- parent directories, walking up from the current working directory
-- the current directory
-
-If a directory contains `AGENTS.override.md`, Agent Forge loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
-
-Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
-
-### System Prompt Files
-
-Replace the default system prompt with:
-
-- `.agent-forge/SYSTEM.md` for a project
-- `~/.agent-forge/agent/SYSTEM.md` globally
-
-Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
-
-## Exporting and Sharing Sessions
-
-Use `/export [file]` to write a session to HTML.
-
-Install and configure the optional `session-share` plugin before using `/share`; the core does not provide a built-in sharing transport.
-
-If you publish sessions for model, prompt, tool, or evaluation research, choose a destination and publication workflow that match your own privacy requirements.
-
-## CLI Reference
-
-```bash
-agent-forge [options] [--] [@files...] [messages...]
-```
-
-### Package Commands
-
-```bash
-agent-forge install <source> [-l]     # Install package, -l for project-local
-agent-forge remove <source> [-l]      # Remove package
-agent-forge uninstall <source> [-l]   # Alias for remove
-agent-forge update [source|self|agent-forge] # Update Agent Forge or one package source
-agent-forge update --all              # Update Agent Forge and packages; reconcile pinned git refs
-agent-forge update --packages        # Update packages only; reconcile pinned git refs
-agent-forge update --models           # Refresh model catalogs only
-agent-forge update --self             # Update Agent Forge only
-agent-forge update --package <src>   # Update one package
-agent-forge list                      # List installed packages
-agent-forge config                    # Enable/disable package resources
-```
-
-These commands manage legacy packages. New capability plugins are discovered through `plugin.json`; see [Plugins](packages.md). To uninstall Agent Forge itself, see [Quickstart](quickstart.md#uninstall).
-
-See [Plugins](packages.md) for plugin sources and execution notes.
-
-### Modes
-
-| Flag | Description |
-|------|-------------|
-| default | Interactive mode |
-| `-p`, `--print` | Print response and exit |
-| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
-| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
-| `--export <in> [out]` | Export a session to HTML |
-
-In print mode, Agent Forge also reads piped stdin and merges it into the initial prompt:
-
-```bash
-cat README.md | agent-forge -p "Summarize this text"
-```
-
-### Model Options
-
-| Option | Description |
-|--------|-------------|
-| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
-| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
-| `--api-key <key>` | API key, overriding environment variables |
-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
-| `--models <patterns>` | Comma-separated patterns for model cycling (bindable, no default key) |
-| `--list-models [search]` | List available models |
-
-### Session Options
-
-| Option | Description |
-|--------|-------------|
-| `-c`, `--continue` | Continue the most recent session |
-| `-r`, `--resume` | Browse and select a session |
-| `--session <path\|id>` | Use a specific session file or partial UUID |
-| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
-| `--session-dir <dir>` | Custom session storage directory |
-| `--no-session` | Ephemeral mode; do not save |
-| `--name <name>`, `-n <name>` | Set session display name at startup |
-
-### Tool Options
-
-| Option | Description |
-|--------|-------------|
-| `--tools <list>`, `-t <list>` | Allowlist specific built-in, plugin, and custom tools |
-| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, plugin, and custom tools |
-| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep plugin/custom tools enabled |
-| `--no-tools`, `-nt` | Disable all tools |
-
-Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
-
-### Resource Options
-
-| Option | Description |
-|--------|-------------|
-| `--skill <path>` | Load a skill; repeatable |
-| `--no-skills` | Disable skill discovery |
-| `--prompt-template <path>` | Load a prompt template; repeatable |
-| `--no-prompt-templates` | Disable prompt template discovery |
-| `--theme <path>` | Load a theme; repeatable |
-| `--no-themes` | Disable theme discovery |
-| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
-
-Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
-
-```bash
-agent-forge --no-skills --no-prompt-templates
-```
-
-### Other Options
-
-| Option | Description |
-|--------|-------------|
-| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
-| `--append-system-prompt <text>` | Append to system prompt |
-| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
-| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
-| `--verbose` | Force verbose startup |
-| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
-| `-h`, `--help` | Show help |
-| `-v`, `--version` | Show version |
-
-In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, Agent Forge uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. See [Terminal setup](terminal-setup.md) for terminal-specific settings and workarounds.
-
-Set **TUI mode** in `/settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
-
-### File Arguments
-
-Prefix files with `@` to include them in the message:
-
-```bash
-agent-forge @prompt.md "Answer this"
-agent-forge -p @screenshot.png "What's in this image?"
-agent-forge @code.ts @test.ts "Review these files"
-```
-
-### Examples
-
-```bash
-# Interactive with initial prompt
-agent-forge "List all .ts files in src/"
-
-# Non-interactive
-agent-forge -p "Summarize this codebase"
-
-# Prompt beginning with a dash
-agent-forge -p -- "- Summarize these points"
-
-# Non-interactive with piped stdin
-cat README.md | agent-forge -p "Summarize this text"
-
-# Named one-shot session
-agent-forge --name "release audit" -p "Audit this repository"
-
-# Different model
-agent-forge --provider openai --model gpt-4o "Help me refactor"
-
-# Model with provider prefix
-agent-forge --model openai/gpt-4o "Help me refactor"
-
-# Model with thinking level shorthand
-agent-forge --model sonnet:high "Solve this complex problem"
-
-# Limit model cycling
-agent-forge --models "claude-*,gpt-4o"
-
-# Read-only mode
-agent-forge --tools read,grep,find,ls -p "Review the code"
-
-# Disable one plugin or built-in tool while keeping the rest available
-agent-forge --exclude-tools ask_question
-```
-
-## Design Principles
-
-Agent Forge keeps the core small and pushes workflow-specific behavior into plugins, Skills, prompt templates, and external tools.
-
-It intentionally does not include MCP, multi-Agent workflows, approval policy, Plan mode, to-dos, or background bash as core business branches. MCP servers are configured through `mcp.json` ([MCP](mcp.md)); the rest are added through plugins or external tools such as containers and tmux.
-
-For the architectural rationale, see the repository [核心架构宪法](../../../docs/核心架构宪法.md).
+# Using Agent Forge
+
+This page collects day-to-day usage details that do not fit on the quickstart page.
+
+## Interactive Mode
+
+<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+
+The interface has four main areas:
+
+- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and themes
+- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, and errors
+- **Editor** - where you type; border color indicates the current thinking level
+- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
+
+The editor can be replaced temporarily by built-in UI such as `/settings` or `/model`.
+
+### Editor Features
+
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Press Tab to complete paths |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Copy response | Ctrl+X copies the selected message in `/tree`; otherwise it copies the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
+| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
+
+See [Keybindings](keybindings.md) for all shortcuts and customization.
+
+## Slash Commands
+
+Type `/` in the editor to open command completion. Capability plugins can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
+
+| Command | Description |
+|---------|-------------|
+| `/login`, `/logout` | Manage OAuth or API-key credentials |
+| [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
+| `/model` | Switch models; Ctrl+S in the picker saves the startup default |
+| `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
+| `/scoped-models` | Enable/disable models for model cycling (bindable, no default key) |
+| `/settings` | Theme, message delivery, transport, and other preferences |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session file, ID, messages, tokens, and cost |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML or JSONL |
+| `/import <file>` | Import and resume a session from a JSONL file |
+| `/share` | 由显式安装的 session-share 插件提供；核心不内置 |
+| `/reload` | Reload keybindings, skills, prompts, themes, and context files |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit Agent Forge |
+
+## Message Queue
+
+You can submit messages while the agent is still working:
+
+- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
+- **`/queue <text>`** queues a follow-up message, delivered after the agent finishes all work.
+- **Escape** aborts and restores queued messages to the editor.
+- **`/dequeue`** restores queued messages back to the editor.
+- **`/queue-list`** opens the queued-message manager (both queues): reorder entries with alt+up / alt+down, delete one with delete, recall one to the editor with enter, close with escape.
+
+Follow-up queueing and dequeue are command-only by default (their shipped keybinding defaults were cleared per the single-entry-point rule, 2026-10-01); bind `app.message.followUp` / `app.message.dequeue` in `keybindings.json` if you want keys (see [Keybindings](keybindings.md)).
+
+Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.agent-forge/agent/sessions/`, organized by working directory.
+
+```bash
+agent-forge -c                  # Continue most recent session
+agent-forge -r                  # Browse and select a session
+agent-forge --no-session        # Ephemeral mode; do not save
+agent-forge --name "my task"    # Set session display name at startup
+agent-forge --session <path|id> # Use a specific session file or session ID
+agent-forge --fork <path|id>    # Fork a session into a new session file
+```
+
+Useful session commands:
+
+- `/session` shows the current session file and ID.
+- `/tree` navigates the in-file session tree and can summarize abandoned branches.
+- `/fork` creates a new session from an earlier user message.
+- `/clone` duplicates the current active branch into a new session file.
+- `/compact` summarizes older messages to free context.
+
+See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+
+## Context Files
+
+Agent Forge loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.agent-forge/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+If a directory contains `AGENTS.override.md`, Agent Forge loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
+
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+
+### System Prompt Files
+
+Replace the default system prompt with:
+
+- `.agent-forge/SYSTEM.md` for a project
+- `~/.agent-forge/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+## Exporting and Sharing Sessions
+
+Use `/export [file]` to write a session to HTML.
+
+Install and configure the optional `session-share` plugin before using `/share`; the core does not provide a built-in sharing transport.
+
+If you publish sessions for model, prompt, tool, or evaluation research, choose a destination and publication workflow that match your own privacy requirements.
+
+## CLI Reference
+
+```bash
+agent-forge [options] [--] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+agent-forge install <source> [-l]     # Install package, -l for project-local
+agent-forge remove <source> [-l]      # Remove package
+agent-forge uninstall <source> [-l]   # Alias for remove
+agent-forge update [source|self|agent-forge] # Update Agent Forge or one package source
+agent-forge update --all              # Update Agent Forge and packages; reconcile pinned git refs
+agent-forge update --packages        # Update packages only; reconcile pinned git refs
+agent-forge update --models           # Refresh model catalogs only
+agent-forge update --self             # Update Agent Forge only
+agent-forge update --package <src>   # Update one package
+agent-forge list                      # List installed packages
+agent-forge config                    # Enable/disable package resources
+```
+
+These commands manage legacy packages. New capability plugins are discovered through `plugin.json`; see [Plugins](packages.md). To uninstall Agent Forge itself, see [Quickstart](quickstart.md#uninstall).
+
+See [Plugins](packages.md) for plugin sources and execution notes.
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| default | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
+| `--export <in> [out]` | Export a session to HTML |
+
+In print mode, Agent Forge also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | agent-forge -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
+| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
+| `--api-key <key>` | API key, overriding environment variables |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `--models <patterns>` | Comma-separated patterns for model cycling (bindable, no default key) |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue the most recent session |
+| `-r`, `--resume` | Browse and select a session |
+| `--session <path\|id>` | Use a specific session file or partial UUID |
+| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode; do not save |
+| `--name <name>`, `-n <name>` | Set session display name at startup |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific built-in, plugin, and custom tools |
+| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, plugin, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep plugin/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools |
+
+Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
+
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `--skill <path>` | Load a skill; repeatable |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load a prompt template; repeatable |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load a theme; repeatable |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```bash
+agent-forge --no-skills --no-prompt-templates
+```
+
+### Other Options
+
+| Option | Description |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
+| `--verbose` | Force verbose startup |
+| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, Agent Forge uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. See [Terminal setup](terminal-setup.md) for terminal-specific settings and workarounds.
+
+Set **TUI mode** in `/settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```bash
+agent-forge @prompt.md "Answer this"
+agent-forge -p @screenshot.png "What's in this image?"
+agent-forge @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+agent-forge "List all .ts files in src/"
+
+# Non-interactive
+agent-forge -p "Summarize this codebase"
+
+# Prompt beginning with a dash
+agent-forge -p -- "- Summarize these points"
+
+# Non-interactive with piped stdin
+cat README.md | agent-forge -p "Summarize this text"
+
+# Named one-shot session
+agent-forge --name "release audit" -p "Audit this repository"
+
+# Different model
+agent-forge --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+agent-forge --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+agent-forge --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+agent-forge --models "claude-*,gpt-4o"
+
+# Read-only mode
+agent-forge --tools read,grep,find,ls -p "Review the code"
+
+# Disable one plugin or built-in tool while keeping the rest available
+agent-forge --exclude-tools ask_question
+```
+
+## Design Principles
+
+Agent Forge keeps the core small and pushes workflow-specific behavior into plugins, Skills, prompt templates, and external tools.
+
+It intentionally does not include MCP, multi-Agent workflows, approval policy, Plan mode, to-dos, or background bash as core business branches. MCP servers are configured through `mcp.json` ([MCP](mcp.md)); the rest are added through plugins or external tools such as containers and tmux.
+
+For the architectural rationale, see the repository [核心架构宪法](../../../docs/核心架构宪法.md).

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "agent-forge-extension-with-deps",
-  "version": "0.87.1",
+  "version": "0.87.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "agent-forge-extension-with-deps",
-      "version": "0.87.1",
+      "version": "0.87.2",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-forge-extension-with-deps",
   "private": true,
-  "version": "0.87.1",
+  "version": "0.87.2",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.example.with-deps",
-	"version": "0.87.1",
+	"version": "0.87.2",
 	"hostVersion": ">=0.84.0",
 	"apiVersion": "1-draft",
 	"entry": "./index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ai-agent-forge/agent-forge",
-	"version": "0.88.1",
+	"version": "0.88.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"agentForgeConfig": {