@aion0/forge 0.3.5 → 0.3.6

package/CLAUDE.md

@@ -47,6 +47,21 @@ forge watch <id>         # live stream task output
 - npm package: `@aion0/forge`
 - GitHub: `github.com/aiwatching/forge`
 
+### Help Docs Rule
+When adding or changing a feature, check if `lib/help-docs/` needs updating. Each file covers one module:
+- `00-overview.md` — install, start, data paths
+- `01-settings.md` — all settings fields
+- `02-telegram.md` — bot setup and commands
+- `03-tunnel.md` — remote access
+- `04-tasks.md` — background tasks
+- `05-pipelines.md` — DAG workflows
+- `06-skills.md` — marketplace
+- `07-projects.md` — project management
+- `08-rules.md` — CLAUDE.md templates
+- `09-issue-autofix.md` — GitHub issue scanner
+- `10-troubleshooting.md` — common issues
+If a feature change affects user-facing behavior, update the corresponding help doc in the same commit.
+
 ### Architecture
 - `forge-server.mjs` starts: Next.js + terminal-standalone + telegram-standalone
 - `pnpm dev` / `start.sh dev` starts: Next.js (init.ts spawns terminal + telegram)

package/app/api/help/route.ts

@@ -0,0 +1,78 @@
+import { NextResponse } from 'next/server';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getConfigDir } from '@/lib/dirs';
+import { loadSettings } from '@/lib/settings';
+import { execSync } from 'node:child_process';
+
+const HELP_DIR = join(getConfigDir(), 'help');
+const SOURCE_HELP_DIR = join(process.cwd(), 'lib', 'help-docs');
+
+/** Ensure help docs are copied to ~/.forge/help/ */
+function ensureHelpDocs() {
+  if (!existsSync(HELP_DIR)) mkdirSync(HELP_DIR, { recursive: true });
+  if (existsSync(SOURCE_HELP_DIR)) {
+    for (const file of readdirSync(SOURCE_HELP_DIR)) {
+      if (!file.endsWith('.md')) continue;
+      const src = join(SOURCE_HELP_DIR, file);
+      const dest = join(HELP_DIR, file);
+      // Always overwrite to keep docs up to date
+      writeFileSync(dest, readFileSync(src));
+    }
+  }
+}
+
+/** Check if any agent CLI is available */
+function detectAgent(): { name: string; path: string } | null {
+  const settings = loadSettings();
+  if (settings.claudePath) {
+    try {
+      execSync(`"${settings.claudePath}" --version`, { timeout: 5000, stdio: 'pipe' });
+      return { name: 'claude', path: settings.claudePath };
+    } catch {}
+  }
+  for (const agent of ['claude', 'codex', 'aider']) {
+    try {
+      const path = execSync(`which ${agent}`, { encoding: 'utf-8', timeout: 3000, stdio: 'pipe' }).trim();
+      if (path) return { name: agent, path };
+    } catch {}
+  }
+  return null;
+}
+
+// GET /api/help
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const action = searchParams.get('action') || 'status';
+
+  if (action === 'status') {
+    const agent = detectAgent();
+    ensureHelpDocs();
+    const docs = existsSync(HELP_DIR)
+      ? readdirSync(HELP_DIR).filter(f => f.endsWith('.md')).sort()
+      : [];
+    return NextResponse.json({ agent, docsCount: docs.length, helpDir: HELP_DIR });
+  }
+
+  if (action === 'docs') {
+    ensureHelpDocs();
+    const docs = existsSync(HELP_DIR)
+      ? readdirSync(HELP_DIR).filter(f => f.endsWith('.md')).sort().map(f => ({
+          name: f,
+          title: f.replace(/^\d+-/, '').replace(/\.md$/, '').replace(/-/g, ' '),
+        }))
+      : [];
+    return NextResponse.json({ docs });
+  }
+
+  if (action === 'doc') {
+    const name = searchParams.get('name');
+    if (!name) return NextResponse.json({ error: 'name required' }, { status: 400 });
+    ensureHelpDocs();
+    const file = join(HELP_DIR, name);
+    if (!existsSync(file)) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    return NextResponse.json({ content: readFileSync(file, 'utf-8') });
+  }
+
+  return NextResponse.json({ error: 'Invalid action' }, { status: 400 });
+}

package/components/Dashboard.tsx

@@ -18,6 +18,7 @@ const CodeViewer = lazy(() => import('./CodeViewer'));
 const ProjectManager = lazy(() => import('./ProjectManager'));
 const PreviewPanel = lazy(() => import('./PreviewPanel'));
 const PipelineView = lazy(() => import('./PipelineView'));
+const HelpDialog = lazy(() => import('./HelpDialog'));
 const SkillsPanel = lazy(() => import('./SkillsPanel'));
 
 interface UsageSummary {
@@ -47,6 +48,7 @@ export default function Dashboard({ user }: { user: any }) {
   const [showNewTask, setShowNewTask] = useState(false);
   const [showSettings, setShowSettings] = useState(false);
   const [showMonitor, setShowMonitor] = useState(false);
+  const [showHelp, setShowHelp] = useState(false);
   const [usage, setUsage] = useState<UsageSummary[]>([]);
   const [providers, setProviders] = useState<ProviderInfo[]>([]);
   const [projects, setProjects] = useState<ProjectInfo[]>([]);
@@ -262,6 +264,15 @@ export default function Dashboard({ user }: { user: any }) {
               + New Task
             </button>
           )}
+          {/* Help */}
+          <button
+            onClick={() => setShowHelp(v => !v)}
+            className={`text-[10px] px-2 py-0.5 border rounded transition-colors ${
+              showHelp
+                ? 'border-[var(--accent)] text-[var(--accent)]'
+                : 'border-[var(--border)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:border-[var(--text-secondary)]'
+            }`}
+          >?</button>
           {/* Preview + Tunnel */}
           <button
             onClick={() => setViewMode('preview')}
@@ -597,6 +608,11 @@ export default function Dashboard({ user }: { user: any }) {
       {showSettings && (
         <SettingsModal onClose={() => { setShowSettings(false); fetchData(); refreshDisplayName(); }} />
       )}
+      {showHelp && (
+        <Suspense fallback={null}>
+          <HelpDialog onClose={() => setShowHelp(false)} />
+        </Suspense>
+      )}
     </div>
   );
 }

package/components/HelpDialog.tsx

@@ -0,0 +1,169 @@
+'use client';
+
+import { useState, useEffect, useRef, lazy, Suspense } from 'react';
+
+interface DocItem {
+  name: string;
+  title: string;
+}
+
+const HelpTerminal = lazy(() => import('./HelpTerminal'));
+
+export default function HelpDialog({ onClose }: { onClose: () => void }) {
+  const [docs, setDocs] = useState<DocItem[]>([]);
+  const [agent, setAgent] = useState<{ name: string } | null | undefined>(undefined); // undefined = loading
+  const [viewDoc, setViewDoc] = useState<string | null>(null);
+  const [docContent, setDocContent] = useState('');
+  const [search, setSearch] = useState('');
+  const [tab, setTab] = useState<'docs' | 'chat'>('docs');
+  const [position, setPosition] = useState({ x: Math.max(0, window.innerWidth - 520), y: 50 });
+  const [size, setSize] = useState({ w: 500, h: 560 });
+  const dragRef = useRef<{ startX: number; startY: number; origX: number; origY: number } | null>(null);
+  const resizeRef = useRef<{ startX: number; startY: number; origW: number; origH: number } | null>(null);
+
+  useEffect(() => {
+    fetch('/api/help?action=status').then(r => r.json())
+      .then(data => setAgent(data.agent || null)).catch(() => setAgent(null));
+    fetch('/api/help?action=docs').then(r => r.json())
+      .then(data => setDocs(data.docs || [])).catch(() => {});
+  }, []);
+
+  const loadDoc = async (name: string) => {
+    setViewDoc(name);
+    try {
+      const res = await fetch(`/api/help?action=doc&name=${encodeURIComponent(name)}`);
+      const data = await res.json();
+      setDocContent(data.content || '');
+    } catch { setDocContent('Failed to load'); }
+  };
+
+  // Drag
+  const onDragStart = (e: React.MouseEvent) => {
+    e.preventDefault();
+    dragRef.current = { startX: e.clientX, startY: e.clientY, origX: position.x, origY: position.y };
+    const onMove = (ev: MouseEvent) => {
+      if (!dragRef.current) return;
+      setPosition({
+        x: Math.max(0, dragRef.current.origX + ev.clientX - dragRef.current.startX),
+        y: Math.max(0, dragRef.current.origY + ev.clientY - dragRef.current.startY),
+      });
+    };
+    const onUp = () => { dragRef.current = null; window.removeEventListener('mousemove', onMove); window.removeEventListener('mouseup', onUp); };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+  };
+
+  // Resize
+  const onResizeStart = (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    resizeRef.current = { startX: e.clientX, startY: e.clientY, origW: size.w, origH: size.h };
+    const onMove = (ev: MouseEvent) => {
+      if (!resizeRef.current) return;
+      setSize({
+        w: Math.max(350, resizeRef.current.origW + ev.clientX - resizeRef.current.startX),
+        h: Math.max(300, resizeRef.current.origH + ev.clientY - resizeRef.current.startY),
+      });
+    };
+    const onUp = () => { resizeRef.current = null; window.removeEventListener('mousemove', onMove); window.removeEventListener('mouseup', onUp); };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+  };
+
+  const filtered = search ? docs.filter(d => d.title.toLowerCase().includes(search.toLowerCase())) : docs;
+
+  return (
+    <div
+      className="fixed z-50 bg-[var(--bg-secondary)] border border-[var(--border)] rounded-lg shadow-2xl flex flex-col overflow-hidden"
+      style={{ left: position.x, top: position.y, width: size.w, height: size.h }}
+    >
+      {/* Title bar */}
+      <div
+        className="flex items-center gap-2 px-3 py-2 bg-[var(--bg-tertiary)] border-b border-[var(--border)] cursor-move shrink-0 select-none"
+        onMouseDown={onDragStart}
+      >
+        <span className="text-[11px] font-semibold text-[var(--text-primary)]">Forge Help</span>
+        <div className="ml-auto flex items-center gap-1">
+          <button
+            onClick={() => { setTab('docs'); setViewDoc(null); }}
+            className={`text-[9px] px-2 py-0.5 rounded ${tab === 'docs' ? 'bg-[var(--accent)]/20 text-[var(--accent)]' : 'text-[var(--text-secondary)]'}`}
+          >Docs</button>
+          {agent && (
+            <button
+              onClick={() => setTab('chat')}
+              className={`text-[9px] px-2 py-0.5 rounded ${tab === 'chat' ? 'bg-[var(--accent)]/20 text-[var(--accent)]' : 'text-[var(--text-secondary)]'}`}
+            >AI Chat</button>
+          )}
+          <button onClick={onClose} className="text-[var(--text-secondary)] hover:text-[var(--red)] ml-1 text-sm leading-none">✕</button>
+        </div>
+      </div>
+
+      {tab === 'chat' ? (
+        /* Embedded terminal */
+        <div className="flex-1 min-h-0">
+          <Suspense fallback={<div className="flex-1 flex items-center justify-center text-xs text-[var(--text-secondary)]">Loading terminal...</div>}>
+            <HelpTerminal />
+          </Suspense>
+        </div>
+      ) : viewDoc ? (
+        /* Doc view */
+        <>
+          <div className="px-3 py-1.5 border-b border-[var(--border)] flex items-center gap-2 shrink-0">
+            <button onClick={() => setViewDoc(null)} className="text-[10px] text-[var(--accent)]">← Back</button>
+            <span className="text-[10px] text-[var(--text-primary)] font-semibold truncate">
+              {docs.find(d => d.name === viewDoc)?.title || viewDoc}
+            </span>
+          </div>
+          <div className="flex-1 overflow-y-auto p-3">
+            <pre className="text-[11px] text-[var(--text-primary)] whitespace-pre-wrap break-words font-mono leading-relaxed">
+              {docContent}
+            </pre>
+          </div>
+        </>
+      ) : (
+        /* Doc list */
+        <>
+          <div className="px-3 py-2 border-b border-[var(--border)] shrink-0">
+            <input
+              type="text"
+              value={search}
+              onChange={e => setSearch(e.target.value)}
+              placeholder="Search help topics..."
+              className="w-full px-2 py-1 bg-[var(--bg-tertiary)] border border-[var(--border)] rounded text-[10px] text-[var(--text-primary)] focus:outline-none focus:border-[var(--accent)]"
+              autoFocus
+            />
+          </div>
+          {!agent && agent !== undefined && (
+            <div className="px-3 py-2 bg-[var(--yellow)]/10 border-b border-[var(--border)] shrink-0">
+              <p className="text-[9px] text-[var(--text-secondary)]">
+                Install Claude Code for AI help: <code className="text-[var(--accent)]">npm i -g @anthropic-ai/claude-code</code>
+              </p>
+            </div>
+          )}
+          <div className="flex-1 overflow-y-auto">
+            {filtered.map(doc => (
+              <button
+                key={doc.name}
+                onClick={() => loadDoc(doc.name)}
+                className="w-full text-left px-3 py-2.5 border-b border-[var(--border)]/30 hover:bg-[var(--bg-tertiary)] text-[11px] text-[var(--text-primary)] capitalize"
+              >
+                {doc.title}
+              </button>
+            ))}
+          </div>
+          <div className="px-3 py-2 border-t border-[var(--border)] shrink-0">
+            <a href="https://github.com/aiwatching/forge" target="_blank" rel="noopener noreferrer"
+              className="text-[9px] text-[var(--text-secondary)] hover:text-[var(--accent)]">GitHub →</a>
+          </div>
+        </>
+      )}
+
+      {/* Resize handle */}
+      <div
+        onMouseDown={onResizeStart}
+        className="absolute bottom-0 right-0 w-4 h-4 cursor-se-resize"
+        style={{ background: 'linear-gradient(135deg, transparent 50%, var(--border) 50%)' }}
+      />
+    </div>
+  );
+}

package/components/HelpTerminal.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import '@xterm/xterm/css/xterm.css';
+
+const SESSION_NAME = 'mw-forge-help';
+
+function getWsUrl() {
+  if (typeof window === 'undefined') return `ws://localhost:${parseInt(process.env.TERMINAL_PORT || '3001')}`;
+  const wsProtocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  const wsHost = window.location.hostname;
+  if (wsHost !== 'localhost' && wsHost !== '127.0.0.1') {
+    return `${wsProtocol}//${window.location.host}/terminal-ws`;
+  }
+  const webPort = parseInt(window.location.port) || 3000;
+  return `${wsProtocol}//${wsHost}:${webPort + 1}`;
+}
+
+export default function HelpTerminal() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [connected, setConnected] = useState(false);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    let disposed = false;
+    const cs = getComputedStyle(document.documentElement);
+    const tv = (name: string) => cs.getPropertyValue(name).trim();
+    const term = new Terminal({
+      cursorBlink: true,
+      fontSize: 12,
+      fontFamily: 'Menlo, Monaco, "Courier New", monospace',
+      scrollback: 3000,
+      logger: { trace: () => {}, debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+      theme: {
+        background: tv('--term-bg') || '#1a1a2e',
+        foreground: tv('--term-fg') || '#e0e0e0',
+        cursor: tv('--term-cursor') || '#7c5bf0',
+        selectionBackground: (tv('--term-cursor') || '#7c5bf0') + '44',
+      },
+    });
+    const fit = new FitAddon();
+    term.loadAddon(fit);
+    term.open(containerRef.current);
+    try { fit.fit(); } catch {}
+
+    const wsUrl = getWsUrl();
+    let ws: WebSocket | null = null;
+    let reconnectTimer = 0;
+    let isNewSession = false;
+
+    function connect() {
+      if (disposed) return;
+      const socket = new WebSocket(wsUrl);
+      ws = socket;
+
+      socket.onopen = () => {
+        if (disposed) { socket.close(); return; }
+        socket.send(JSON.stringify({ type: 'attach', sessionName: SESSION_NAME, cols: term.cols, rows: term.rows }));
+      };
+
+      socket.onmessage = (event) => {
+        if (disposed) return;
+        try {
+          const msg = JSON.parse(event.data);
+          if (msg.type === 'output') {
+            try { term.write(msg.data); } catch {}
+          } else if (msg.type === 'connected') {
+            setConnected(true);
+            if (isNewSession) {
+              isNewSession = false;
+              setTimeout(() => {
+                if (socket.readyState === WebSocket.OPEN) {
+                  socket.send(JSON.stringify({ type: 'input', data: `cd ~/.forge/help 2>/dev/null && claude\n` }));
+                }
+              }, 300);
+            }
+          } else if (msg.type === 'error') {
+            isNewSession = true;
+            if (socket.readyState === WebSocket.OPEN) {
+              socket.send(JSON.stringify({ type: 'create', cols: term.cols, rows: term.rows, sessionName: SESSION_NAME }));
+            }
+          }
+        } catch {}
+      };
+
+      socket.onclose = () => {
+        if (disposed) return;
+        setConnected(false);
+        reconnectTimer = window.setTimeout(connect, 3000);
+      };
+      socket.onerror = () => {};
+    }
+
+    connect();
+
+    term.onData((data) => {
+      if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'input', data }));
+    });
+
+    const resizeObserver = new ResizeObserver(() => {
+      const el = containerRef.current;
+      if (!el || el.offsetWidth < 50 || el.offsetHeight < 30) return;
+      try {
+        fit.fit();
+        if (term.cols < 2 || term.rows < 2) return;
+        if (ws?.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }));
+        }
+      } catch {}
+    });
+    resizeObserver.observe(containerRef.current);
+
+    return () => {
+      disposed = true;
+      clearTimeout(reconnectTimer);
+      ws?.close();
+      resizeObserver.disconnect();
+      term.dispose();
+    };
+  }, []);
+
+  return (
+    <div className="h-full flex flex-col">
+      <div ref={containerRef} className="flex-1" />
+    </div>
+  );
+}

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

@@ -0,0 +1,34 @@
+# 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.
+
+## Quick Start
+
+```bash
+npm install -g @aion0/forge
+forge server start
+```
+
+Open `http://localhost:3000`. First launch prompts you to set an admin password.
+
+## Requirements
+- Node.js >= 20
+- tmux (`brew install tmux` on macOS)
+- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
+
+## Data Location
+- Config: `~/.forge/` (binaries)
+- Data: `~/.forge/data/` (settings, database, state)
+- Claude: `~/.claude/` (skills, commands, sessions)
+
+## Server Commands
+```bash
+forge server start              # background (default)
+forge server start --foreground # foreground
+forge server start --dev        # dev mode with hot-reload
+forge server stop               # stop
+forge server restart            # restart
+forge server start --port 4000  # custom port
+forge server start --dir ~/.forge-test  # custom data dir
+forge --reset-password          # reset admin password
+```

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

@@ -0,0 +1,37 @@
+# Settings Configuration
+
+Settings are stored in `~/.forge/data/settings.yaml`. Configure via the web UI (Settings button in top-right menu) or edit YAML directly.
+
+## All Settings Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `projectRoots` | string[] | `[]` | Directories containing your projects (e.g. `~/Projects`) |
+| `docRoots` | string[] | `[]` | Markdown/Obsidian vault directories |
+| `claudePath` | string | `""` | Path to claude binary (auto-detected if empty) |
+| `claudeHome` | string | `""` | Claude Code home directory (default: `~/.claude`) |
+| `telegramBotToken` | string | `""` | Telegram Bot API token (encrypted) |
+| `telegramChatId` | string | `""` | Telegram chat ID (comma-separated for multiple users) |
+| `notifyOnComplete` | boolean | `true` | Telegram notification on task completion |
+| `notifyOnFailure` | boolean | `true` | Telegram notification on task failure |
+| `tunnelAutoStart` | boolean | `false` | Auto-start Cloudflare Tunnel on server startup |
+| `telegramTunnelPassword` | string | `""` | Admin password for login + tunnel + secrets (encrypted) |
+| `taskModel` | string | `"default"` | Model for background tasks |
+| `pipelineModel` | string | `"default"` | Model for pipeline workflows |
+| `telegramModel` | string | `"sonnet"` | Model for Telegram AI features |
+| `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 |
+
+## 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`.

package/lib/help-docs/02-telegram.md

@@ -0,0 +1,41 @@
+# Telegram Bot Setup
+
+## Setup Steps
+
+1. Open Telegram, search for [@BotFather](https://t.me/botfather)
+2. Send `/newbot`, follow prompts to create a bot
+3. Copy the bot token (looks like `6234567890:ABCDefGHIJKLMNOPQRSTUVWXYZ`)
+4. In Forge Settings, paste the token into **Telegram Bot Token**
+5. To get your Chat ID: send any message to your bot, then visit `https://api.telegram.org/bot<TOKEN>/getUpdates` — find `chat.id` in the response
+6. Paste the Chat ID into **Telegram Chat ID** in Settings
+7. The bot starts automatically after saving
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/task <project> <prompt>` | Create a background task |
+| `/tasks [status]` | List tasks (running/queued/done/failed) |
+| `/sessions [project]` | AI summary of Claude Code sessions |
+| `/watch <id>` | Live stream task output |
+| `/unwatch <id>` | Stop streaming |
+| `/docs <query>` | Search Obsidian vault |
+| `/note <text>` | Quick note to vault |
+| `/peek <project>` | Preview running session |
+| `/cancel <id>` | Cancel a task |
+| `/retry <id>` | Retry a failed task |
+| `/tunnel_start <password>` | Start Cloudflare Tunnel (returns URL + code) |
+| `/tunnel_stop` | Stop tunnel |
+| `/tunnel_code <password>` | Get session code for remote login |
+| `/projects` | List configured projects |
+
+## Shortcuts
+- Reply to a task message to interact with it
+- Send `"project: instructions"` to quick-create a task
+- Numbered lists — reply with a number to select
+
+## Troubleshooting
+
+- **Bot not responding**: Check token is correct, restart server
+- **"Unauthorized"**: Chat ID doesn't match configured value
+- **Multiple users**: Set comma-separated Chat IDs (e.g. `123456,789012`)

package/lib/help-docs/03-tunnel.md

@@ -0,0 +1,31 @@
+# Remote Access (Cloudflare Tunnel)
+
+## How It Works
+
+Forge creates a temporary Cloudflare Tunnel — a secure public URL that routes to your local Forge server. No Cloudflare account needed.
+
+## Start Tunnel
+
+**From UI**: Click the "Tunnel" button in the top-right header.
+
+**From Telegram**: `/tunnel_start <admin_password>`
+
+**Auto-start**: Set `tunnelAutoStart: true` in Settings.
+
+## Login Flow
+
+- **Local access** (localhost, LAN): Admin password only
+- **Remote access** (via tunnel, `.trycloudflare.com`): Admin password + Session Code (2FA)
+
+Session code is generated when tunnel starts. Get it via:
+- Telegram: `/tunnel_code <password>`
+- CLI: `forge tcode`
+
+## Troubleshooting
+
+- **Tunnel stuck at "starting"**: Kill old cloudflared processes: `pkill -f cloudflared`
+- **URL not reachable**: Tunnel may have timed out, restart it
+- **Session cookie invalid after restart**: Set `AUTH_SECRET` in `~/.forge/data/.env.local`:
+  ```bash
+  echo "AUTH_SECRET=$(openssl rand -hex 32)" >> ~/.forge/data/.env.local
+  ```

package/lib/help-docs/04-tasks.md

@@ -0,0 +1,52 @@
+# Background Tasks
+
+## What Are Tasks?
+
+Tasks run Claude Code prompts in the background. They use `claude -p` (print mode) — execute and exit, no persistent session. Your code runs on your machine using your Claude subscription.
+
+## Create a Task
+
+**From UI**: Click "+ New Task" in the Tasks tab.
+
+**From CLI**:
+```bash
+forge task my-project "fix the login bug"
+forge task my-project "add unit tests for utils.ts" --new  # fresh session
+```
+
+**From Telegram**: `/task my-project fix the login bug`
+
+## Task Modes
+
+| Mode | Description |
+|------|-------------|
+| `prompt` | Run Claude Code with a prompt (default) |
+| `shell` | Execute raw shell command |
+| `monitor` | Watch a session and trigger actions |
+
+## Watch Task Output
+
+```bash
+forge watch <task-id>    # live stream in terminal
+```
+
+Or from Telegram: `/watch <task-id>`
+
+## CLI Commands
+
+```bash
+forge tasks              # list all tasks
+forge tasks running      # filter by status
+forge status <id>        # task details
+forge cancel <id>        # cancel
+forge retry <id>         # retry failed task
+forge log <id>           # execution log
+```
+
+## Features
+
+- **Per-project concurrency**: One prompt task per project at a time, others queue
+- **Session continuity**: All tasks in the same project share one Claude conversation
+- **Cost tracking**: Token usage and USD cost per task
+- **Git tracking**: Captures branch name and git diff after execution
+- **Scheduled execution**: Set `scheduledAt` for deferred tasks

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

@@ -0,0 +1,73 @@
+# Pipelines (Workflows)
+
+## 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.
+
+## YAML Workflow Format
+
+```yaml
+name: my-workflow
+description: "What this workflow does"
+input:
+  feature: "Feature description"
+vars:
+  project: my-app
+nodes:
+  design:
+    project: "{{vars.project}}"
+    prompt: "Design: {{input.feature}}"
+    outputs:
+      - name: spec
+        extract: result
+  implement:
+    project: "{{vars.project}}"
+    depends_on: [design]
+    prompt: "Implement: {{nodes.design.outputs.spec}}"
+  review:
+    project: "{{vars.project}}"
+    depends_on: [implement]
+    prompt: "Review the changes"
+```
+
+## 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 |
+
+## Template Variables
+
+- `{{input.xxx}}` — pipeline input values
+- `{{vars.xxx}}` — workflow variables
+- `{{nodes.xxx.outputs.yyy}}` — outputs from previous nodes
+
+## Built-in Workflows
+
+### issue-auto-fix
+Fetches a GitHub issue → fixes code on new branch → creates PR.
+
+Input: `issue_id`, `project`, `base_branch` (optional)
+
+### pr-review
+Fetches PR diff → AI code review → posts result.
+
+Input: `pr_number`, `project`
+
+## CLI
+
+```bash
+forge flows              # list available workflows
+forge run my-workflow    # execute a workflow
+```
+
+## Storage
+
+- Workflow YAML: `~/.forge/data/flows/`
+- Execution state: `~/.forge/data/pipelines/`

package/lib/help-docs/06-skills.md

@@ -0,0 +1,43 @@
+# Skills Marketplace
+
+## Overview
+
+Browse, install, and manage Claude Code skills and commands from the Forge Skills registry.
+
+## Types
+
+| | Skills | Commands |
+|---|---|---|
+| Location | `~/.claude/skills/<name>/` | `~/.claude/commands/<name>.md` |
+| Entry file | `SKILL.md` | Single `.md` file |
+| Complexity | Multi-file with templates | Simple slash command |
+
+Both register as `/slash-command` in Claude Code.
+
+## Install
+
+1. Go to **Skills** tab in Forge
+2. Click **Sync** to fetch latest registry
+3. Click **Install** on any skill → choose Global or specific project
+4. Use in Claude Code with `/<skill-name>`
+
+## Update
+
+Skills with newer versions show a yellow "update" indicator. Click to update (checks for local modifications first).
+
+## Local Skills
+
+The **Local** tab shows skills/commands installed on your machine (both from marketplace and manually created). You can:
+- **Install to...** — Copy a local skill to another project or global
+- **Delete** — Remove from project or global
+- **Edit** — View and modify installed files
+
+## Registry
+
+Default: `https://raw.githubusercontent.com/aiwatching/forge-skills/main`
+
+Change in Settings → Skills Repo URL.
+
+## Custom Skills
+
+Create your own: put a `.md` file in `<project>/.claude/commands/` or a directory in `<project>/.claude/skills/<name>/`.

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

@@ -0,0 +1,39 @@
+# Projects
+
+## Setup
+
+Add project directories in Settings → **Project Roots** (e.g. `~/Projects`). Forge scans subdirectories automatically.
+
+## Features
+
+### Code Tab
+- File tree browser
+- Syntax-highlighted code viewer
+- Git diff view (click changed files)
+- Git operations: commit, push, pull
+- Commit history
+
+### Skills & Commands Tab
+- View installed skills/commands for this project
+- Scope indicator: G (global), P (project), G+P (both)
+- Edit files, update from marketplace, uninstall
+
+### CLAUDE.md Tab
+- View and edit project's CLAUDE.md
+- Apply rule templates (built-in or custom)
+- Templates auto-injected with dedup markers
+
+### Issues Tab
+- Enable GitHub Issue Auto-fix per project
+- Configure scan interval and label filters
+- Manual trigger: enter issue # and click Fix Issue
+- Processed issues history with retry/delete
+- Auto-chains: fix → create PR → review
+
+## 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.

package/lib/help-docs/08-rules.md

@@ -0,0 +1,53 @@
+# Rules (CLAUDE.md Templates)
+
+## What Are Rules?
+
+Reusable markdown snippets that get appended to project CLAUDE.md files. They define coding conventions, security rules, workflow guidelines, etc.
+
+## Built-in Templates
+
+| Template | Description |
+|----------|-------------|
+| TypeScript Rules | Coding conventions (const, types, early returns) |
+| Git Workflow | Commit messages, branch naming |
+| Obsidian Vault | Vault integration instructions |
+| Security Rules | OWASP guidelines, no hardcoded secrets |
+
+## Manage Rules
+
+**Skills tab → Rules sub-tab**:
+- View all templates (built-in + custom)
+- Create new: click "+ New"
+- Edit any template (including built-in)
+- Delete custom templates
+- Set as "default" — auto-applied to new projects
+- Batch apply: select template → check projects → click "Apply"
+
+## Apply to Project
+
+**Project → CLAUDE.md tab**:
+- Left sidebar shows CLAUDE.md content + template list
+- Click "+ add" to inject a template
+- Click "added" to remove
+- Templates wrapped in `<!-- forge:template:id -->` markers (prevents duplicate injection)
+
+## Default Templates
+
+Templates marked as "default" are automatically injected into new projects when they first appear in the project list.
+
+## Custom Templates
+
+Stored in `~/.forge/data/claude-templates/`. Each is a `.md` file with YAML frontmatter:
+
+```markdown
+---
+name: My Rule
+description: What this rule does
+tags: [category]
+builtin: false
+isDefault: false
+---
+
+## My Custom Rule
+Your content here...
+```

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

@@ -0,0 +1,51 @@
+# Issue Auto-fix
+
+## Overview
+
+Automatically scan GitHub Issues, fix code, create PRs, and review — all hands-free.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated: `gh auth login`
+- Project has a GitHub remote
+
+## Setup
+
+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
+
+## Flow
+
+```
+Scan → Fetch Issue → Fix Code (new branch) → Push → Create PR → Auto Review → 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**: Automatically triggers `pr-review` pipeline
+5. **Notify**: Results sent via Telegram (if configured)
+
+## Manual Trigger
+
+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.
+
+## Safety
+
+- Checks for uncommitted changes before starting (aborts if dirty)
+- Always works on new branches (never modifies main)
+- Switches back to original branch after completion
+- Existing PRs are updated, not duplicated
+
+## Processed Issues
+
+History shows all processed issues with status (processing/done/failed), PR number, and pipeline ID. Click pipeline ID to view details.

package/lib/help-docs/10-troubleshooting.md

@@ -0,0 +1,82 @@
+# Troubleshooting
+
+## Common Issues
+
+### "fork failed: Device not configured" (macOS)
+PTY device limit exhausted:
+```bash
+sudo sysctl kern.tty.ptmx_max=2048
+echo 'kern.tty.ptmx_max=2048' | sudo tee -a /etc/sysctl.conf
+```
+
+### Session cookie invalid after restart
+Fix AUTH_SECRET so it persists:
+```bash
+echo "AUTH_SECRET=$(openssl rand -hex 32)" >> ~/.forge/data/.env.local
+```
+
+### Orphan processes after Ctrl+C
+Use `forge server stop` or:
+```bash
+pkill -f 'telegram-standalone|terminal-standalone|next-server|cloudflared'
+```
+
+### Tunnel stuck at "starting"
+```bash
+pkill -f cloudflared
+# Then restart tunnel from UI or Telegram
+```
+
+### Forgot admin password
+```bash
+forge --reset-password
+```
+
+### Terminal tabs lost after restart
+Terminal state is saved in `~/.forge/data/terminal-state.json`. If corrupted:
+```bash
+rm ~/.forge/data/terminal-state.json
+# Restart server — tabs will be empty but tmux sessions survive
+```
+
+### gh CLI not authenticated (Issue Scanner)
+```bash
+gh auth login
+```
+
+### Skills not syncing
+Click "Sync" in Skills tab. Check `skillsRepoUrl` in Settings points to valid registry.
+
+### Multiple instances conflict
+Use different ports and data directories:
+```bash
+forge server start --port 4000 --dir ~/.forge/data_demo
+forge server stop --port 4000 --dir ~/.forge/data_demo
+```
+
+### Page shows "Failed to load chunk"
+Clear build cache:
+```bash
+rm -rf .next
+pnpm build  # or forge server rebuild
+```
+
+## Logs
+
+- Background server: `~/.forge/data/forge.log`
+- Dev mode: terminal output
+- View with: `tail -f ~/.forge/data/forge.log`
+
+## Reset Everything
+
+```bash
+# Stop server
+forge server stop
+
+# Reset password
+forge --reset-password
+
+# Clear all data (nuclear option)
+rm -rf ~/.forge/data
+# Restart — will create fresh data directory
+```

package/package.json

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