@aion0/forge 0.4.5 → 0.4.6

package/RELEASE_NOTES.md

@@ -1,11 +1,12 @@
-# Forge v0.4.5
+# Forge v0.4.6
 
 Released: 2026-03-21
 
-## Changes since v0.4.4
+## Changes since v0.4.5
 
-### Bug Fixes
-- fix: add drag-to-resize for left sidebars across all split-panel pages (#14)
+### Other
+- improve help features
+- imporve help features
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.4.4...v0.4.5
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.4.5...v0.4.6

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

@@ -2,7 +2,7 @@
 
 ## What Are Pipelines?
 
-Pipelines chain multiple tasks into a DAG (directed acyclic graph). Each step can depend on previous steps, pass outputs forward, and run in parallel.
+Pipelines chain multiple tasks into a DAG (directed acyclic graph). Each step can depend on previous steps, pass outputs forward, and run in parallel. Pipelines are defined as YAML workflow files.
 
 ## YAML Workflow Format
 
@@ -10,9 +10,10 @@ Pipelines chain multiple tasks into a DAG (directed acyclic graph). Each step ca
 name: my-workflow
 description: "What this workflow does"
 input:
-  feature: "Feature description"
+  feature: "Feature description"      # required input fields
+  priority: "Priority level (optional)"
 vars:
-  project: my-app
+  project: my-app                     # default variables
 nodes:
   design:
     project: "{{vars.project}}"
@@ -23,7 +24,10 @@ nodes:
   implement:
     project: "{{vars.project}}"
     depends_on: [design]
-    prompt: "Implement: {{nodes.design.outputs.spec}}"
+    prompt: "Implement based on: {{nodes.design.outputs.spec}}"
+    outputs:
+      - name: diff
+        extract: git_diff
   review:
     project: "{{vars.project}}"
     depends_on: [implement]
@@ -32,30 +36,252 @@ nodes:
 
 ## Node Options
 
-| Field | Description |
-|-------|-------------|
-| `project` | Project name (supports `{{vars.xxx}}` templates) |
-| `prompt` | Claude Code prompt or shell command |
-| `mode` | `claude` (default) or `shell` |
-| `branch` | Auto-checkout branch before running |
-| `depends_on` | List of node IDs that must complete first |
-| `outputs` | Extract results: `result`, `git_diff`, or `stdout` |
-| `routes` | Conditional routing to next nodes |
+| Field | Description | Default |
+|-------|-------------|---------|
+| `project` | Project name (supports templates) | required |
+| `prompt` | Claude Code prompt or shell command | required |
+| `mode` | `claude` (AI agent) or `shell` (raw command) | `claude` |
+| `branch` | Auto-checkout branch before running (supports templates) | none |
+| `depends_on` | List of node IDs that must complete first | `[]` |
+| `outputs` | Extract results (see Output Extraction) | `[]` |
+| `routes` | Conditional routing to next nodes (see Routing) | `[]` |
+| `max_iterations` | Max loop iterations for routed nodes | `3` |
+
+## Node Modes
+
+### `claude` (default)
+Runs the prompt via Claude Code (`claude -p`). The AI agent reads the codebase, makes changes, and returns a result.
+
+### `shell`
+Runs the prompt as a raw shell command (`bash -c "..."`). Useful for git operations, CLI tools, API calls, etc.
+
+```yaml
+nodes:
+  setup:
+    mode: shell
+    project: my-app
+    prompt: |
+      git checkout main && git pull && echo "READY"
+    outputs:
+      - name: info
+        extract: stdout
+```
+
+**Shell escaping**: Template values in shell mode are automatically escaped (single quotes `'` → `'\''`) to prevent injection.
 
 ## Template Variables
 
-- `{{input.xxx}}` — pipeline input values
-- `{{vars.xxx}}` — workflow variables
-- `{{nodes.xxx.outputs.yyy}}` — outputs from previous nodes
+Templates use `{{...}}` syntax and are resolved before execution:
+
+- `{{input.xxx}}` — pipeline input values provided at trigger time
+- `{{vars.xxx}}` — workflow-level variables defined in YAML
+- `{{nodes.<node_id>.outputs.<output_name>}}` — outputs from completed nodes
+
+Node IDs can contain hyphens (e.g., `{{nodes.fetch-issue.outputs.data}}`).
+
+### Examples
+
+```yaml
+prompt: "Fix issue #{{input.issue_id}} in {{input.project}}"
+prompt: "Based on: {{nodes.design.outputs.spec}}"
+prompt: |
+  REPO={{nodes.setup.outputs.repo}} && \
+  gh pr create --title "Fix #{{input.issue_id}}" -R "$REPO"
+```
+
+## Output Extraction
+
+Each node can extract outputs for downstream nodes:
+
+| Extract Type | Description |
+|-------------|-------------|
+| `result` | Claude's final response text |
+| `stdout` | Shell command stdout (same as result for shell mode) |
+| `git_diff` | Git diff of changes made during the task |
+
+```yaml
+outputs:
+  - name: summary
+    extract: result
+  - name: changes
+    extract: git_diff
+```
+
+## Skip Convention (`__SKIP__`)
+
+If a shell node outputs `__SKIP__` in its stdout and exits with code 0, the node is marked as `skipped` instead of `done`. All downstream dependent nodes are also skipped. The pipeline completes successfully (not failed).
+
+```yaml
+nodes:
+  check:
+    mode: shell
+    project: my-app
+    prompt: |
+      if [ -z "{{input.issue_id}}" ]; then
+        echo "__SKIP__ No issue_id provided"
+        exit 0
+      fi
+      echo "Processing issue {{input.issue_id}}"
+```
+
+Use this for optional steps that should gracefully skip when preconditions aren't met.
+
+## Conditional Routing
+
+Nodes can route to different next steps based on output content:
+
+```yaml
+nodes:
+  analyze:
+    project: my-app
+    prompt: "Analyze the issue. Reply SIMPLE or COMPLEX."
+    outputs:
+      - name: complexity
+        extract: result
+    routes:
+      - condition: "{{outputs.complexity contains 'SIMPLE'}}"
+        next: quick-fix
+      - condition: default
+        next: deep-fix
+  quick-fix:
+    depends_on: [analyze]
+    project: my-app
+    prompt: "Apply a quick fix"
+  deep-fix:
+    depends_on: [analyze]
+    project: my-app
+    prompt: "Do a thorough analysis and fix"
+```
+
+### Route Conditions
+
+- `{{outputs.<name> contains '<keyword>'}}` — check if output contains a keyword
+- `default` — fallback route (always matches)
+
+### Loops
+
+If a route points back to the same node, it creates a loop (up to `max_iterations`):
+
+```yaml
+nodes:
+  fix-and-test:
+    project: my-app
+    prompt: "Fix the failing test, then run tests."
+    max_iterations: 5
+    outputs:
+      - name: test_result
+        extract: result
+    routes:
+      - condition: "{{outputs.test_result contains 'PASS'}}"
+        next: done
+      - condition: default
+        next: fix-and-test   # loop back to retry
+  done:
+    depends_on: [fix-and-test]
+    mode: shell
+    project: my-app
+    prompt: "echo 'All tests passing!'"
+```
+
+## Branch Auto-checkout
+
+Nodes can auto-checkout a git branch before execution:
+
+```yaml
+nodes:
+  work:
+    project: my-app
+    branch: "feature/{{input.feature_name}}"
+    prompt: "Implement the feature"
+```
+
+## Parallel Execution
+
+Nodes without dependency relationships run in parallel:
+
+```yaml
+nodes:
+  frontend:
+    project: my-app
+    prompt: "Build frontend component"
+  backend:
+    project: my-app
+    prompt: "Build API endpoint"
+  integration:
+    depends_on: [frontend, backend]  # waits for both
+    project: my-app
+    prompt: "Integration test"
+```
+
+`frontend` and `backend` run simultaneously; `integration` starts when both finish.
 
 ## Built-in Workflows
 
-### issue-fix-and-review
-Complete issue resolution pipeline: fetch issue → fix code → create PR → review code → notify.
+### issue-auto-fix
+Complete issue resolution: fetch GitHub issue → fix code on new branch → create PR.
+
+**Input**: `issue_id`, `project`, `base_branch` (optional), `extra_context` (optional)
+
+**Steps**: setup → fetch-issue → fix-code → push-and-pr → notify
+
+**Prerequisites**: `gh` CLI installed and authenticated (`gh auth login`), project has GitHub remote.
+
+### pr-review
+Review a pull request: fetch PR diff → AI review → report.
+
+**Input**: `pr_number`, `project`
+
+**Steps**: setup → fetch-pr → review → post-review
 
-Steps: setup → fetch-issue → fix-code → push-and-pr → review → cleanup
+## Project Pipeline Bindings
 
-Input: `issue_id`, `project`, `base_branch` (optional), `extra_context` (optional)
+Projects can bind workflows for easy access and scheduled execution.
+
+### Binding a Workflow to a Project
+
+1. Go to **Projects → select project → Pipelines tab**
+2. Click **+ Add** to attach a workflow
+3. Configure:
+   - **Enabled**: toggle on/off
+   - **Schedule**: Manual only, or periodic (15min to 24h intervals)
+4. Click **Run** to manually trigger
+
+### Scheduled Execution
+
+When a schedule is set (e.g., "Every 30 min"):
+- The scheduler checks all bindings every 60 seconds
+- If the interval has elapsed since last run, the pipeline triggers automatically
+- Running pipelines are not re-triggered (prevents overlap)
+- `Last run` and `Next run` times are shown in the UI
+
+Schedule options: Manual only, 15min, 30min, 1h, 2h, 6h, 12h, 24h.
+
+### API
+
+```bash
+# List bindings + runs + workflows for a project
+curl "http://localhost:3000/api/project-pipelines?project=/path/to/project"
+
+# Add binding
+curl -X POST http://localhost:3000/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"add","projectPath":"/path","projectName":"my-app","workflowName":"issue-auto-fix"}'
+
+# Update binding (enable/disable, change config/schedule)
+curl -X POST http://localhost:3000/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"update","projectPath":"/path","workflowName":"issue-auto-fix","config":{"interval":30}}'
+
+# Trigger pipeline manually
+curl -X POST http://localhost:3000/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"trigger","projectPath":"/path","projectName":"my-app","workflowName":"issue-auto-fix","input":{"issue_id":"42"}}'
+
+# Remove binding
+curl -X POST http://localhost:3000/api/project-pipelines \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"remove","projectPath":"/path","workflowName":"issue-auto-fix"}'
+```
 
 ## CLI
 
@@ -66,7 +292,7 @@ forge run my-workflow    # execute a workflow
 
 ## Import a Workflow
 
-1. In Pipelines tab, click **Import**
+1. In **Pipelines** tab, click **Import**
 2. Paste YAML workflow content
 3. Click **Save Workflow**
 
@@ -79,10 +305,25 @@ To create a workflow via Help AI: ask "Create a pipeline that does X" — the AI
 ```bash
 curl -X POST http://localhost:3000/api/pipelines \
   -H 'Content-Type: application/json' \
-  -d '{"action": "save-workflow", "yaml": "name: my-flow\nnodes:\n  step1:\n    project: my-project\n    prompt: do something"}'
+  -d '{"action": "save-workflow", "yaml": "<yaml content>"}'
 ```
 
+## 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.
+
 ## Storage
 
 - Workflow YAML: `~/.forge/data/flows/`
 - Execution state: `~/.forge/data/pipelines/`
+- Binding config & run history: SQLite database (`~/.forge/data/forge.db`)
+
+## Tips for Writing Workflows
+
+1. **Start with shell nodes** for setup (git checkout, environment checks)
+2. **Use `__SKIP__`** for optional steps with precondition checks
+3. **Extract outputs** to pass data between nodes
+4. **Use routes** for conditional logic (simple/complex paths, retry loops)
+5. **Keep prompts focused** — each node should do one thing well
+6. **Test manually first** before setting up schedules
+7. **Use `depends_on`** to control execution order; nodes without dependencies run in parallel

package/lib/help-docs/09-issue-autofix.md

@@ -2,50 +2,50 @@
 
 ## Overview
 
-Automatically scan GitHub Issues, fix code, create PRs, and review — all hands-free.
+Automatically scan GitHub Issues, fix code, create PRs — all hands-free. Uses the built-in `issue-auto-fix` pipeline workflow.
 
 ## Prerequisites
 
 - `gh` CLI installed and authenticated: `gh auth login`
 - Project has a GitHub remote
 
-## Setup
+## Setup (via Project Pipeline Binding)
 
-1. Go to **Projects → select project → Issues tab**
-2. Enable **Issue Auto-fix**
-3. Configure:
-   - **Scan Interval**: minutes between scans (0 = manual only)
-   - **Base Branch**: leave empty for auto-detect (main/master)
-   - **Labels Filter**: comma-separated labels (empty = all issues)
-4. Click **Scan Now** to test
+1. Go to **Projects → select project → Pipelines tab**
+2. Click **+ Add** and select `issue-auto-fix`
+3. Enable the binding
+4. Set a **Schedule** (e.g., Every 30 min) for automatic scanning, or leave as "Manual only"
+5. Click **Run** to manually trigger with an `issue_id`
 
 ## Flow
 
 ```
-Scan → Fetch Issue → Fix Code (new branch) → Push → Create PR → Auto Review → Notify
+Setup → Fetch Issue → Fix Code (new branch) → Push & Create PR → Notify
 ```
 
-1. **Scan**: `gh issue list` finds open issues matching labels
-2. **Fix**: Claude Code analyzes issue and fixes code on `fix/<id>-<description>` branch
-3. **PR**: Pushes branch and creates Pull Request
-4. **Review**: AI reviews the code changes in the same pipeline
-5. **Notify**: Results sent via Telegram (if configured)
+1. **Setup**: Checks for clean working directory, detects repo and base branch
+2. **Fetch Issue**: `gh issue view` fetches issue data (skips if no issue_id)
+3. **Fix Code**: Claude analyzes issue and fixes code on `fix/<id>-<description>` branch
+4. **Push & PR**: Pushes branch and creates Pull Request via `gh pr create`
+5. **Notify**: Switches back to original branch, reports PR URL
 
-## Manual Trigger
+## Input Fields
 
-Enter an issue number in "Manual Trigger" section and click "Fix Issue".
-
-## Retry
-
-Failed fixes show a "Retry" button. Click to provide additional context (e.g. "rebase from main first") and re-run.
+| Input | Description | Required |
+|-------|-------------|----------|
+| `issue_id` | GitHub issue number | Yes (skips if empty) |
+| `project` | Project name | Yes |
+| `base_branch` | Base branch for fix | No (auto-detect) |
+| `extra_context` | Additional instructions | No |
 
 ## Safety
 
 - Checks for uncommitted changes before starting (aborts if dirty)
-- Always works on new branches (never modifies main)
+- Always works on new branches (never modifies main/master)
+- Cleans up old fix branches for the same issue
 - Switches back to original branch after completion
-- Existing PRs are updated, not duplicated
+- Uses `--force-with-lease` for safe push
 
-## Processed Issues
+## Legacy Issue Scanner
 
-History shows all processed issues with status (processing/done/failed), PR number, and pipeline ID. Click pipeline ID to view details.
+The old issue scanner (`Projects → Issues tab`) is still functional for existing configurations. It uses `issue_autofix_config` DB table for per-project scan settings. New projects should use the pipeline binding approach above.

package/lib/help-docs/CLAUDE.md

@@ -0,0 +1,41 @@
+You are a help assistant for **Forge** — a self-hosted Vibe Coding platform.
+
+Your job is to answer user questions about Forge features, configuration, and troubleshooting.
+
+## How to answer
+
+1. Read the relevant documentation file(s) from this directory before answering
+2. Base your answers on the documentation content, not assumptions
+3. If the answer isn't in the docs, say so honestly
+4. Give concise, actionable answers with code examples when helpful
+5. When generating files (YAML workflows, configs, scripts, etc.), **always save the file directly** to the appropriate directory rather than printing it. For pipeline workflows, save to `~/.forge/data/flows/<name>.yaml`. Tell the user the file path so they can find it. The terminal does not support copy/paste.
+
+## Available documentation
+
+| File | Topic |
+|------|-------|
+| `00-overview.md` | Installation, startup, data paths, architecture |
+| `01-settings.md` | All settings fields and configuration |
+| `02-telegram.md` | Telegram bot setup and commands |
+| `03-tunnel.md` | Remote access via Cloudflare tunnel |
+| `04-tasks.md` | Background task system |
+| `05-pipelines.md` | Pipeline/workflow engine — YAML format, nodes, templates, routing, scheduling, project bindings |
+| `06-skills.md` | Skills marketplace and installation |
+| `07-projects.md` | Project management |
+| `08-rules.md` | CLAUDE.md templates and rule injection |
+| `09-issue-autofix.md` | GitHub issue auto-fix pipeline |
+| `10-troubleshooting.md` | Common issues and solutions |
+
+## Matching questions to docs
+
+- Pipeline/workflow/DAG/YAML → `05-pipelines.md`
+- Issue/PR/auto-fix → `09-issue-autofix.md` + `05-pipelines.md`
+- Telegram/notification → `02-telegram.md`
+- Tunnel/remote/cloudflare → `03-tunnel.md`
+- Task/background/queue → `04-tasks.md`
+- Settings/config → `01-settings.md`
+- Install/start/update → `00-overview.md`
+- Error/bug/crash → `10-troubleshooting.md`
+- Skill/marketplace → `06-skills.md`
+- Project/favorite → `07-projects.md`
+- Rules/CLAUDE.md/template → `08-rules.md`

package/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {