@aion0/forge 0.4.16 → 0.5.1

package/lib/forge-skills/forge-inbox.md

@@ -0,0 +1,37 @@
+---
+description: Check and manage messages from other Forge Workspace agents (QA reports, review feedback, PM requests)
+---
+
+# Forge Inbox
+
+Check for messages from other agents and manage their status.
+
+## When to trigger
+- At the start of a new conversation/session
+- When the user asks about other agents' status or messages
+
+## How to use
+
+IMPORTANT: Do NOT check environment variables. Just run the commands — they auto-discover the workspace.
+
+Step 1 — Get workspace ID:
+```bash
+curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
+```
+
+Step 2 — Check inbox (replace WORKSPACE_ID):
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"inbox","agentId":"'"$FORGE_AGENT_ID"'"}'
+```
+
+## Mark message as done
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"message_done","agentId":"'"$FORGE_AGENT_ID"'","messageId":"MESSAGE_ID"}'
+```
+
+## Mark message as failed
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"message_failed","agentId":"'"$FORGE_AGENT_ID"'","messageId":"MESSAGE_ID"}'
+```
+
+After handling a message, always mark it as done or failed.

package/lib/forge-skills/forge-send.md

@@ -0,0 +1,40 @@
+---
+description: Send a message to another Forge Workspace agent immediately via API (notify QA of a fix, ask PM a question, etc.)
+---
+
+# Forge Send
+
+Send a message to another agent in the Forge Workspace.
+
+## When to trigger
+- You fixed a bug that QA reported → notify QA immediately
+- You have a question about requirements → ask PM
+- You found an issue that another agent should know about
+- User explicitly asks to send a message to another agent
+
+## When NOT to trigger
+- Do NOT send a reply to the agent whose message you are currently processing. The system automatically marks your result as done and notifies them. Only use forge-send for NEW issues or questions to OTHER agents.
+
+## How to send
+
+IMPORTANT: Do NOT check environment variables first. Just run the command below — it auto-discovers everything.
+
+Step 1 — Get workspace ID:
+```bash
+curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
+```
+
+Step 2 — Send message (replace WORKSPACE_ID with result from step 1):
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"send","agentId":"'"$FORGE_AGENT_ID"'","to":"TARGET_LABEL","msgAction":"ACTION","content":"YOUR MESSAGE"}'
+```
+
+Replace:
+- `WORKSPACE_ID` = the ID from step 1
+- `TARGET_LABEL` = target agent label (e.g., "QA", "PM", "Engineer", "Reviewer")
+- `ACTION` = one of: `fix_request`, `update_notify`, `question`, `info_request`, `review`
+- `YOUR MESSAGE` = your actual message
+
+Note: `$FORGE_AGENT_ID` is automatically set by Forge when launching the terminal. Do NOT replace it manually.
+
+Tell the user the result.

package/lib/forge-skills/forge-status.md

@@ -0,0 +1,32 @@
+---
+description: Check the status of all agents in the Forge Workspace (who is running, done, waiting)
+---
+
+# Forge Status
+
+Check the current status of all agents in the Forge Workspace.
+
+## When to trigger
+- User asks "what's the status?" or "how are other agents doing?"
+- At the start of a session to understand the current workspace state
+
+## How to check
+
+IMPORTANT: Do NOT check environment variables. Just run the commands.
+
+Step 1 — Get workspace ID:
+```bash
+curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
+```
+
+Step 2 — Check status (replace WORKSPACE_ID):
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"status","agentId":"'"$FORGE_AGENT_ID"'"}'
+```
+
+Present the results as a clear status overview:
+- 🟢 active — smith is online and listening
+- 🔵 running — agent is currently executing a task
+- ✅ done — agent completed its work
+- 🔴 failed — agent encountered an error
+- ⬚ down — smith is not started

package/lib/forge-skills/forge-workspace-sync.md

@@ -0,0 +1,37 @@
+---
+description: Automatically sync your work progress with Forge Workspace when you've completed a task or made significant changes
+---
+
+# Forge Workspace Sync
+
+When you detect that the user has completed a meaningful unit of work, automatically sync with Forge Workspace.
+
+## When to trigger
+- User says they're done ("done", "完成了", "finished", "that should work")
+- You've made multiple file changes and the conversation reaches a natural stopping point
+- User asks to move on to the next task or agent
+
+## How to sync
+
+IMPORTANT: Do NOT check environment variables. Just run the commands.
+
+Step 1 — Get workspace ID:
+```bash
+curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
+```
+
+Step 2 — Sync (replace WORKSPACE_ID):
+```bash
+curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"done","agentId":"'"$FORGE_AGENT_ID"'","output":"PASTE_YOUR_RECENT_OUTPUT_HERE"}'
+```
+
+Include any `[SEND:AgentLabel:action] message` markers in the `output` field.
+
+This will:
+1. Detect git changes since last sync
+2. Record what you did in agent memory
+3. Parse [SEND:...] markers and deliver messages
+4. Mark this agent as "done"
+5. Notify downstream agents
+
+Tell the user what files changed, messages sent, and that downstream agents were notified.

package/lib/help-docs/00-overview.md

@@ -1,6 +1,6 @@
 # Forge Overview
 
-Forge is a self-hosted Vibe Coding platform for Claude Code. It provides a browser-based terminal, AI task orchestration, remote access, and mobile control via Telegram.
+Forge is a self-hosted Vibe Coding platform for Claude Code. It provides a browser-based terminal, multi-agent workspace orchestration, AI task management, remote access, and mobile control via Telegram.
 
 ## Quick Start
 
@@ -19,8 +19,14 @@ Open `http://localhost:8403`. First launch prompts you to set an admin password.
 ## Data Location
 - Config: `~/.forge/` (binaries)
 - Data: `~/.forge/data/` (settings, database, state)
+- Workspaces: `~/.forge/workspaces/<id>/` (workspace state files)
 - Claude: `~/.claude/` (skills, commands, sessions)
 
+## Architecture
+- `forge-server.mjs` starts: Next.js (port 8403) + Terminal server + Telegram bot + Workspace daemon (port 8405)
+- `pnpm dev` / `start.sh dev`: Next.js dev mode (init.ts spawns terminal + telegram + workspace)
+- `FORGE_EXTERNAL_SERVICES=1`: Next.js skips spawning (forge-server manages external services)
+
 ## Server Commands
 ```bash
 forge server start              # background (default)

package/lib/help-docs/01-settings.md

@@ -19,19 +19,176 @@ Settings are stored in `~/.forge/data/settings.yaml`. Configure via the web UI (
 | `taskModel` | string | `"default"` | Model for background tasks |
 | `pipelineModel` | string | `"default"` | Model for pipeline workflows |
 | `telegramModel` | string | `"sonnet"` | Model for Telegram AI features |
+| `defaultAgent` | string | `"claude"` | Default agent for tasks and terminal |
+| `telegramAgent` | string | `""` | Agent for Telegram task execution |
+| `docsAgent` | string | `""` | Agent for documentation queries |
 | `skipPermissions` | boolean | `false` | Add `--dangerously-skip-permissions` to claude invocations |
 | `notificationRetentionDays` | number | `30` | Auto-cleanup notifications older than N days |
 | `skillsRepoUrl` | string | forge-skills URL | GitHub raw URL for skills registry |
 | `displayName` | string | `"Forge"` | Display name shown in header |
 | `displayEmail` | string | `""` | User email |
+| `favoriteProjects` | string[] | `[]` | Starred project paths |
+| `obsidianVault` | string | `""` | Path to Obsidian vault |
+
+## Agents
+
+Forge auto-detects installed CLI agents (Claude Code, Codex, Aider). You can also add custom agents manually.
+
+### Agent Fields
+
+Each agent entry in `settings.agents` supports:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name |
+| `path` | string | Path to CLI binary |
+| `enabled` | boolean | Whether this agent is available |
+| `cliType` | string | CLI tool type: `claude-code`, `codex`, `aider`, `generic` |
+| `taskFlags` | string | Flags for headless task execution (e.g. `-p --verbose`) |
+| `interactiveCmd` | string | Command for interactive terminal sessions |
+| `resumeFlag` | string | Flag to resume sessions (e.g. `-c` for claude) |
+| `outputFormat` | string | Output format: `stream-json`, `text` |
+| `skipPermissionsFlag` | string | Flag to skip permissions (e.g. `--dangerously-skip-permissions`) |
+| `requiresTTY` | boolean | Whether agent needs a PTY (true for codex) |
+| `models` | object | Model overrides per context: `terminal`, `task`, `telegram`, `help`, `mobile` |
+| `profile` | string | Linked profile ID — applies that profile's env/model when launching |
+
+### CLI Type
+
+The `cliType` field determines how Forge interacts with the agent:
+
+| CLI Type | Session Support | Resume | Skip Permissions |
+|----------|----------------|--------|------------------|
+| `claude-code` | Yes (session files) | `-c` / `--resume <id>` | `--dangerously-skip-permissions` |
+| `codex` | No | — | `--full-auto` |
+| `aider` | No | — | `--yes` |
+| `generic` | No | — | — |
+
+### Example YAML
+
+```yaml
+agents:
+  claude:
+    name: Claude Code
+    path: /usr/local/bin/claude
+    enabled: true
+    cliType: claude-code
+    skipPermissionsFlag: --dangerously-skip-permissions
+  codex:
+    name: OpenAI Codex
+    path: codex
+    enabled: true
+    cliType: codex
+    requiresTTY: true
+    skipPermissionsFlag: --full-auto
+```
+
+## Agent Profiles
+
+Profiles are reusable configurations that extend a base agent with custom environment variables, model overrides, and CLI settings. Any smith or terminal session can use a profile.
+
+### Profile Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `base` | string | Base agent ID (e.g. `claude`, `codex`) — makes this entry a profile |
+| `name` | string | Display name |
+| `model` | string | Model override (passed via `--model` flag) |
+| `env` | object | Environment variables injected when launching |
+| `cliType` | string | Override CLI type (inherits from base if not set) |
+| `enabled` | boolean | Whether this profile is available |
+
+### Example: Custom API Endpoint Profile
+
+```yaml
+agents:
+  forti-k2:
+    base: claude
+    name: Forti K2
+    model: forti-k2
+    env:
+      ANTHROPIC_AUTH_TOKEN: sk-xxx
+      ANTHROPIC_BASE_URL: http://my-server:7001/
+      ANTHROPIC_SMALL_FAST_MODEL: forti-k2
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "true"
+      DISABLE_TELEMETRY: "true"
+```
+
+### Example: Model Override Profile
+
+```yaml
+agents:
+  claude-opus:
+    base: claude
+    name: Claude Opus
+    model: claude-opus-4-6
+  claude-sonnet:
+    base: claude
+    name: Claude Sonnet
+    model: claude-sonnet-4-6
+```
+
+### How Profiles Work
+
+1. A profile inherits all capabilities from its base agent (binary path, session support, resume flags)
+2. Environment variables from `env` are exported before launching the CLI
+3. The `model` field is passed as `--model <value>` flag (claude-code) or via env
+4. Profiles appear in agent selection dropdowns alongside base agents
+
+### Linking a Profile to an Agent
+
+In the agent configuration, set the `profile` field to link a profile:
+
+```yaml
+agents:
+  claude:
+    profile: forti-k2    # Claude will use forti-k2's env/model when launched
+```
+
+This applies the profile's environment variables and model override whenever that agent is launched in a terminal.
+
+## API Providers
+
+Configure API keys for direct API access (used by API-backend smiths):
+
+```yaml
+providers:
+  anthropic:
+    apiKey: sk-ant-...    # encrypted on save
+    defaultModel: claude-sonnet-4-6
+    enabled: true
+  google:
+    apiKey: AIza...
+    defaultModel: gemini-2.0-flash
+    enabled: true
+  openai:
+    apiKey: sk-...
+    enabled: false
+```
+
+Provider API keys are encrypted with AES-256-GCM. The UI shows masked values (••••••••).
 
 ## Admin Password
 
 - Set on first launch (CLI prompt)
 - Required for: login, tunnel start, secret changes, Telegram commands
 - Reset: `forge --reset-password`
-- Forgot? Run `forge --reset-password` in terminal
 
 ## Encrypted Fields
 
-`telegramBotToken` and `telegramTunnelPassword` are encrypted with AES-256-GCM. The encryption key is stored at `~/.forge/data/.encrypt-key`.
+`telegramBotToken` and `telegramTunnelPassword` are encrypted with AES-256-GCM. Agent/provider `apiKey` fields are also encrypted. The encryption key is stored at `~/.forge/data/.encrypt-key`.
+
+## Settings UI
+
+The Settings modal has these sections:
+
+| Section | What it configures |
+|---------|-------------------|
+| **Project Roots** | Directories to scan for projects |
+| **Document Roots** | Markdown/Obsidian vault paths |
+| **Agents** | Detected CLI agents + configuration |
+| **Profiles** | Agent profiles with env/model overrides |
+| **Providers** | API provider keys and defaults |
+| **Telegram** | Bot token, chat ID, notification toggles |
+| **Display** | Name, email |
+| **Other** | Skip permissions, skills repo URL, notification retention |

package/lib/help-docs/05-pipelines.md

@@ -308,6 +308,95 @@ curl -X POST http://localhost:8403/api/pipelines \
   -d '{"action": "save-workflow", "yaml": "<yaml content>"}'
 ```
 
+## Conversation Mode (Multi-Agent Dialogue)
+
+Conversation mode enables multiple agents to collaborate through structured dialogue. Instead of a DAG of tasks, Forge acts as a message broker — sending prompts between agents in rounds until a stop condition is met.
+
+### YAML Format
+
+```yaml
+name: architect-implementer
+type: conversation
+description: "Architect designs, implementer builds"
+input:
+  project: "Project name"
+  task: "What to build"
+agents:
+  - id: architect
+    agent: claude
+    role: "You are a software architect. Design the solution, define interfaces, and review implementations."
+  - id: implementer
+    agent: codex
+    role: "You are a developer. Implement what the architect designs."
+max_rounds: 10
+stop_condition: "both agents say DONE"
+initial_prompt: "Build: {{input.task}}"
+```
+
+### Fields
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `type` | Must be `conversation` | required |
+| `agents` | List of participating agents | required |
+| `agents[].id` | Logical ID within conversation | required |
+| `agents[].agent` | Agent registry ID (`claude`, `codex`, `aider`, etc.) | `claude` |
+| `agents[].role` | System prompt / role description | none |
+| `agents[].project` | Project context (overrides input.project) | none |
+| `max_rounds` | Maximum number of full rounds | `10` |
+| `stop_condition` | When to stop early | none |
+| `initial_prompt` | The seed prompt (supports `{{input.*}}` templates) | required |
+| `context_strategy` | How to pass history between agents: `full`, `window`, `summary` | `summary` |
+| `context_window` | Number of recent messages to include in full (for `window`/`summary`) | `4` |
+| `max_content_length` | Truncate each message to this many characters | `3000` |
+
+### Context Strategies
+
+Agents don't share memory — Forge acts as broker and decides what context to forward.
+
+- **`summary`** (default): Older messages are compressed to one-line summaries. The most recent N messages (set by `context_window`) are passed in full. Best balance of context quality and token usage.
+- **`window`**: Only the last N messages are passed, older ones are dropped entirely. Lowest token usage.
+- **`full`**: All messages from all rounds are passed in full (each truncated to `max_content_length`). Most context but token-heavy.
+
+### Execution Flow
+
+1. Forge sends `initial_prompt` + role to the first agent
+2. Agent responds → Forge collects the response
+3. Forge builds context (per `context_strategy`) and sends to the next agent
+4. Repeat through all agents = 1 round
+5. Continue rounds until `stop_condition` or `max_rounds`
+
+### Stop Conditions
+
+- `"any agent says DONE"` — stops when any agent includes "DONE" in its response
+- `"both agents say DONE"` / `"all agents say DONE"` — stops when all agents have said "DONE"
+- If no stop condition, runs until `max_rounds`
+
+### UI
+
+Conversation pipelines show a chat-like view with color-coded agent bubbles, round numbers, and linked task IDs. The sidebar shows round progress (e.g., R3/10).
+
+### Example: Code Review Dialogue
+
+```yaml
+name: review-dialogue
+type: conversation
+description: "Two agents discuss code quality"
+input:
+  project: "Project name"
+  pr_number: "PR number to review"
+agents:
+  - id: reviewer
+    agent: claude
+    role: "You are a code reviewer. Find bugs, security issues, and suggest improvements."
+  - id: author
+    agent: claude
+    role: "You are the code author. Address review feedback, explain design decisions, and fix issues."
+max_rounds: 5
+stop_condition: "all agents say DONE"
+initial_prompt: "Review PR #{{input.pr_number}} in project {{input.project}}. Reviewer: analyze the diff. Author: be ready to address feedback."
+```
+
 ## Pipeline Model
 
 In **Settings → Pipeline Model**, you can select which Claude model runs pipeline tasks. Set to `default` to use the same model as regular tasks.

package/lib/help-docs/07-projects.md

@@ -30,10 +30,44 @@ Add project directories in Settings → **Project Roots** (e.g. `~/Projects`). F
 - Processed issues history with retry/delete
 - Auto-chains: fix → create PR → review
 
+### Workspace Tab
+- Configure multi-agent workspace (Forge Smiths)
+- Add smiths with roles, steps, and dependencies
+- Start/stop daemon, monitor execution
+- See [Workspace documentation](11-workspace.md) for details
+
 ## Favorites
 
 Click ★ next to a project to favorite it. Favorites appear at the top of the sidebar.
 
 ## Terminal
 
-Click "Terminal" button in project header to open a Vibe Coding terminal for that project. Uses `claude -c` to continue last session.
+### Opening a Terminal
+
+There are two ways to open a terminal for a project:
+
+**1. Project Header Button**
+- Click **Terminal** in the project header → opens with default agent (claude)
+- Click **▾** dropdown to select a different agent or profile
+- If the agent supports sessions (claude-code), a dialog shows: New Session / Resume Latest / Browse Sessions
+- Non-session agents (codex, aider) open directly
+
+**2. Terminal Tab "+" Button**
+- Click **+** in the terminal tab bar → select a project root → expand to see projects
+- Click an agent button (C = Claude, X = Codex, A = Aider, ● = Profile) to open
+- The terminal launches with the agent's configured env vars and model
+
+### Agent & Profile Selection
+
+When selecting an agent or profile for a terminal:
+- **Base agents** (Claude, Codex, Aider): Use their default configuration
+- **Profiles** (e.g., Forti K2, Claude Opus): Apply the profile's environment variables and model override
+- Environment variables are exported in the terminal before launching the CLI
+- Model is passed via `--model` flag (for claude-code agents)
+
+### Terminal Features
+- Full xterm.js terminal with tmux session persistence
+- Split panes (horizontal/vertical)
+- Multiple tabs per project
+- Tab state preserved across page refreshes
+- Tabs can be renamed and reordered