@aion0/forge 0.3.5 → 0.3.7

package/components/LogViewer.tsx

@@ -0,0 +1,194 @@
+'use client';
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export default function LogViewer() {
+  const [lines, setLines] = useState<string[]>([]);
+  const [total, setTotal] = useState(0);
+  const [fileSize, setFileSize] = useState(0);
+  const [filePath, setFilePath] = useState('');
+  const [search, setSearch] = useState('');
+  const [maxLines, setMaxLines] = useState(200);
+  const [autoRefresh, setAutoRefresh] = useState(true);
+  const [processes, setProcesses] = useState<{ pid: string; cpu: string; mem: string; cmd: string }[]>([]);
+  const [showProcesses, setShowProcesses] = useState(false);
+  const bottomRef = useRef<HTMLDivElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [autoScroll, setAutoScroll] = useState(true);
+
+  const fetchLogs = useCallback(async () => {
+    try {
+      const res = await fetch(`/api/logs?lines=${maxLines}${search ? `&search=${encodeURIComponent(search)}` : ''}`);
+      const data = await res.json();
+      setLines(data.lines || []);
+      setTotal(data.total || 0);
+      setFileSize(data.size || 0);
+      if (data.file) setFilePath(data.file);
+    } catch {}
+  }, [maxLines, search]);
+
+  const fetchProcesses = async () => {
+    try {
+      const res = await fetch('/api/logs', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action: 'processes' }),
+      });
+      const data = await res.json();
+      setProcesses(data.processes || []);
+    } catch {}
+  };
+
+  const clearLogs = async () => {
+    if (!confirm('Clear all logs?')) return;
+    await fetch('/api/logs', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'clear' }),
+    });
+    fetchLogs();
+  };
+
+  // Initial + auto refresh
+  useEffect(() => { fetchLogs(); }, [fetchLogs]);
+  useEffect(() => {
+    if (!autoRefresh) return;
+    const id = setInterval(fetchLogs, 3000);
+    return () => clearInterval(id);
+  }, [autoRefresh, fetchLogs]);
+
+  // Auto scroll
+  useEffect(() => {
+    if (autoScroll) bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [lines, autoScroll]);
+
+  // Detect manual scroll
+  const onScroll = () => {
+    const el = containerRef.current;
+    if (!el) return;
+    const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 50;
+    setAutoScroll(atBottom);
+  };
+
+  const formatSize = (bytes: number) => {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  };
+
+  const getLineColor = (line: string) => {
+    if (line.includes('[error]') || line.includes('Error') || line.includes('FATAL')) return 'text-red-400';
+    if (line.includes('[warn]') || line.includes('Warning') || line.includes('WARN')) return 'text-yellow-400';
+    if (line.includes('[forge]') || line.includes('[init]')) return 'text-cyan-400';
+    if (line.includes('[task]') || line.includes('[pipeline]')) return 'text-green-400';
+    if (line.includes('[telegram]') || line.includes('[terminal]')) return 'text-purple-400';
+    if (line.includes('[issue-scanner]') || line.includes('[watcher]')) return 'text-orange-300';
+    return 'text-[var(--text-primary)]';
+  };
+
+  return (
+    <div className="flex-1 flex flex-col min-h-0">
+      {/* Toolbar */}
+      <div className="flex items-center gap-2 px-4 py-2 border-b border-[var(--border)] shrink-0 flex-wrap">
+        <span className="text-xs font-semibold text-[var(--text-primary)]">Logs</span>
+        <span className="text-[8px] text-[var(--text-secondary)]">{total} lines · {formatSize(fileSize)}</span>
+
+        {/* Search */}
+        <input
+          type="text"
+          value={search}
+          onChange={e => setSearch(e.target.value)}
+          placeholder="Filter..."
+          className="px-2 py-0.5 bg-[var(--bg-tertiary)] border border-[var(--border)] rounded text-[10px] text-[var(--text-primary)] w-32 focus:outline-none focus:border-[var(--accent)]"
+        />
+
+        {/* Max lines */}
+        <select
+          value={maxLines}
+          onChange={e => setMaxLines(Number(e.target.value))}
+          className="px-1 py-0.5 bg-[var(--bg-tertiary)] border border-[var(--border)] rounded text-[10px] text-[var(--text-primary)]"
+        >
+          <option value={100}>100 lines</option>
+          <option value={200}>200 lines</option>
+          <option value={500}>500 lines</option>
+          <option value={1000}>1000 lines</option>
+        </select>
+
+        <div className="ml-auto flex items-center gap-2">
+          {/* Auto refresh toggle */}
+          <label className="flex items-center gap-1 text-[9px] text-[var(--text-secondary)] cursor-pointer">
+            <input type="checkbox" checked={autoRefresh} onChange={e => setAutoRefresh(e.target.checked)} className="accent-[var(--accent)]" />
+            Auto (3s)
+          </label>
+
+          {/* Processes */}
+          <button
+            onClick={() => { setShowProcesses(v => !v); fetchProcesses(); }}
+            className={`text-[9px] px-2 py-0.5 rounded ${showProcesses ? 'bg-[var(--accent)]/20 text-[var(--accent)]' : 'text-[var(--text-secondary)] hover:text-[var(--text-primary)]'}`}
+          >Processes</button>
+
+          {/* Refresh */}
+          <button onClick={fetchLogs} className="text-[9px] text-[var(--text-secondary)] hover:text-[var(--text-primary)]">↻</button>
+
+          {/* Clear */}
+          <button onClick={clearLogs} className="text-[9px] text-[var(--red)] hover:underline">Clear</button>
+        </div>
+      </div>
+
+      {/* Processes panel */}
+      {showProcesses && processes.length > 0 && (
+        <div className="border-b border-[var(--border)] bg-[var(--bg-tertiary)] max-h-32 overflow-y-auto shrink-0">
+          <div className="px-4 py-1 text-[8px] text-[var(--text-secondary)] uppercase">Running Processes</div>
+          {processes.map(p => (
+            <div key={p.pid} className="px-4 py-0.5 text-[10px] font-mono flex gap-3">
+              <span className="text-[var(--accent)] w-12 shrink-0">{p.pid}</span>
+              <span className="text-green-400 w-10 shrink-0">{p.cpu}%</span>
+              <span className="text-yellow-400 w-10 shrink-0">{p.mem}%</span>
+              <span className="text-[var(--text-secondary)] truncate">{p.cmd}</span>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {/* Log content */}
+      <div
+        ref={containerRef}
+        onScroll={onScroll}
+        className="flex-1 overflow-auto bg-[var(--bg-primary)] font-mono text-[11px] leading-[1.6]"
+      >
+        {lines.length === 0 ? (
+          <div className="flex items-center justify-center h-full text-[var(--text-secondary)] text-xs">
+            {filePath ? 'No log entries' : 'Log file not found — server running in foreground?'}
+          </div>
+        ) : (
+          <div className="p-3">
+            {lines.map((line, i) => (
+              <div key={i} className={`${getLineColor(line)} hover:bg-[var(--bg-tertiary)] px-1`}>
+                {search ? (
+                  // Highlight search matches
+                  line.split(new RegExp(`(${search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})`, 'gi')).map((part, j) =>
+                    part.toLowerCase() === search.toLowerCase()
+                      ? <span key={j} className="bg-[var(--yellow)]/30 text-[var(--yellow)]">{part}</span>
+                      : part
+                  )
+                ) : line}
+              </div>
+            ))}
+            <div ref={bottomRef} />
+          </div>
+        )}
+      </div>
+
+      {/* Footer */}
+      <div className="px-4 py-1 border-t border-[var(--border)] shrink-0 flex items-center gap-2 text-[8px] text-[var(--text-secondary)]">
+        <span>{filePath}</span>
+        {!autoScroll && (
+          <button
+            onClick={() => { setAutoScroll(true); bottomRef.current?.scrollIntoView({ behavior: 'smooth' }); }}
+            className="ml-auto text-[var(--accent)] hover:underline"
+          >↓ Scroll to bottom</button>
+        )}
+      </div>
+    </div>
+  );
+}

package/components/ProjectManager.tsx

@@ -192,9 +192,18 @@ export default function ProjectManager() {
   };
 
   // Group projects by root
+  const [collapsedRoots, setCollapsedRoots] = useState<Set<string>>(new Set());
   const roots = [...new Set(projects.map(p => p.root))];
   const favoriteProjects = projects.filter(p => favorites.includes(p.path));
 
+  const toggleRoot = (root: string) => {
+    setCollapsedRoots(prev => {
+      const next = new Set(prev);
+      if (next.has(root)) next.delete(root); else next.add(root);
+      return next;
+    });
+  };
+
   return (
     <div className="flex-1 flex min-h-0">
       {/* Left sidebar — project list */}
@@ -234,10 +243,14 @@ export default function ProjectManager() {
           {/* Favorites section */}
           {favoriteProjects.length > 0 && (
             <div>
-              <div className="px-3 py-1 text-[9px] text-[var(--yellow)] uppercase bg-[var(--bg-tertiary)] flex items-center gap-1">
-                <span>★</span> Favorites
-              </div>
-              {favoriteProjects.map(p => (
+              <button
+                onClick={() => toggleRoot('__favorites__')}
+                className="w-full px-3 py-1 text-[9px] text-[var(--yellow)] uppercase bg-[var(--bg-tertiary)] flex items-center gap-1 hover:bg-[var(--border)]/30"
+              >
+                <span className="text-[8px]">{collapsedRoots.has('__favorites__') ? '▸' : '▾'}</span>
+                <span>★</span> Favorites ({favoriteProjects.length})
+              </button>
+              {!collapsedRoots.has('__favorites__') && favoriteProjects.map(p => (
                 <button
                   key={`fav-${p.path}`}
                   onClick={() => openProjectTab(p)}
@@ -262,12 +275,17 @@ export default function ProjectManager() {
           {roots.map(root => {
             const rootName = root.split('/').pop() || root;
             const rootProjects = projects.filter(p => p.root === root).sort((a, b) => a.name.localeCompare(b.name));
+            const isCollapsed = collapsedRoots.has(root);
             return (
               <div key={root}>
-                <div className="px-3 py-1 text-[9px] text-[var(--text-secondary)] uppercase bg-[var(--bg-tertiary)]">
-                  {rootName}
-                </div>
-                {rootProjects.map(p => (
+                <button
+                  onClick={() => toggleRoot(root)}
+                  className="w-full px-3 py-1 text-[9px] text-[var(--text-secondary)] uppercase bg-[var(--bg-tertiary)] flex items-center gap-1 hover:bg-[var(--border)]/30"
+                >
+                  <span className="text-[8px]">{isCollapsed ? '▸' : '▾'}</span>
+                  {rootName} ({rootProjects.length})
+                </button>
+                {!isCollapsed && rootProjects.map(p => (
                   <button
                     key={p.path}
                     onClick={() => openProjectTab(p)}

package/lib/auth.ts

@@ -37,8 +37,10 @@ export const { handlers, signIn, signOut, auth } = NextAuth({
         if (verifyLogin(password, sessionCode, isRemote)) {
           const { loadSettings } = await import('./settings');
           const settings = loadSettings();
+          console.log(`[auth] Login success (${isRemote ? 'remote' : 'local'})`);
           return { id: 'local', name: settings.displayName || 'Forge', email: settings.displayEmail || 'local@forge' };
         }
+        console.warn(`[auth] Login failed (${isRemote ? 'remote' : 'local'})`);
         return null;
       },
     }),

package/lib/cloudflared.ts

@@ -23,11 +23,13 @@ function getDownloadUrl(): string {
   const base = 'https://github.com/cloudflare/cloudflared/releases/latest/download';
 
   if (os === 'darwin') {
-    // macOS universal binary
-    return `${base}/cloudflared-darwin-amd64.tgz`;
+    return cpu === 'arm64'
+      ? `${base}/cloudflared-darwin-arm64.tgz`
+      : `${base}/cloudflared-darwin-amd64.tgz`;
   }
   if (os === 'linux') {
     if (cpu === 'arm64') return `${base}/cloudflared-linux-arm64`;
+    if (cpu === 'arm') return `${base}/cloudflared-linux-arm`;
     return `${base}/cloudflared-linux-amd64`;
   }
   if (os === 'win32') {
@@ -38,49 +40,87 @@ function getDownloadUrl(): string {
 
 // ─── Download helper ────────────────────────────────────────────
 
-function followRedirects(url: string, dest: string): Promise<void> {
+const DOWNLOAD_TIMEOUT_MS = 120_000; // 2 minutes total per redirect hop
+
+function followRedirects(url: string, dest: string, redirectsLeft = 10): Promise<void> {
   return new Promise((resolve, reject) => {
     const client = url.startsWith('https') ? https : http;
-    client.get(url, { headers: { 'User-Agent': 'forge' } }, (res) => {
+    const req = client.get(url, { headers: { 'User-Agent': 'forge/1.0' } }, (res) => {
       if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        followRedirects(res.headers.location, dest).then(resolve, reject);
+        res.resume(); // drain redirect response
+        if (redirectsLeft <= 0) {
+          reject(new Error('Too many redirects'));
+          return;
+        }
+        followRedirects(res.headers.location, dest, redirectsLeft - 1).then(resolve, reject);
         return;
       }
       if (res.statusCode !== 200) {
+        res.resume();
         reject(new Error(`Download failed: HTTP ${res.statusCode}`));
         return;
       }
       const file = createWriteStream(dest);
       res.pipe(file);
       file.on('finish', () => file.close(() => resolve()));
-      file.on('error', reject);
-    }).on('error', reject);
+      file.on('error', (err) => { try { unlinkSync(dest); } catch {} reject(err); });
+      res.on('error', (err) => { try { unlinkSync(dest); } catch {} reject(err); });
+    });
+    req.setTimeout(DOWNLOAD_TIMEOUT_MS, () => {
+      req.destroy(new Error(`Download timed out after ${DOWNLOAD_TIMEOUT_MS / 1000}s`));
+    });
+    req.on('error', reject);
   });
 }
 
+// Guard against concurrent downloads
+let downloadPromise: Promise<string> | null = null;
+
 export async function downloadCloudflared(): Promise<string> {
   if (existsSync(BIN_PATH)) return BIN_PATH;
+  if (downloadPromise) return downloadPromise;
 
-  mkdirSync(BIN_DIR, { recursive: true });
-  const url = getDownloadUrl();
-  const isTgz = url.endsWith('.tgz');
-  const tmpPath = isTgz ? `${BIN_PATH}.tgz` : BIN_PATH;
-
-  console.log(`[cloudflared] Downloading from ${url}...`);
-  await followRedirects(url, tmpPath);
+  downloadPromise = (async () => {
+    mkdirSync(BIN_DIR, { recursive: true });
+    const url = getDownloadUrl();
+    const isTgz = url.endsWith('.tgz');
+    const tmpPath = isTgz ? `${BIN_PATH}.tgz` : `${BIN_PATH}.tmp`;
 
-  if (isTgz) {
-    // Extract tgz (macOS)
-    execSync(`tar -xzf "${tmpPath}" -C "${BIN_DIR}"`, { encoding: 'utf-8' });
+    // Clean up any leftover partial files from a previous failed attempt
     try { unlinkSync(tmpPath); } catch {}
-  }
 
-  if (platform() !== 'win32') {
-    chmodSync(BIN_PATH, 0o755);
-  }
+    console.log(`[cloudflared] Downloading from ${url}...`);
+    try {
+      await followRedirects(url, tmpPath);
+    } catch (e) {
+      try { unlinkSync(tmpPath); } catch {}
+      throw e;
+    }
+
+    if (isTgz) {
+      // Extract tgz (macOS)
+      try {
+        execSync(`tar -xzf "${tmpPath}" -C "${BIN_DIR}"`, { encoding: 'utf-8' });
+      } finally {
+        try { unlinkSync(tmpPath); } catch {}
+      }
+    } else {
+      // Rename .tmp to final name atomically
+      const { renameSync } = require('node:fs');
+      renameSync(tmpPath, BIN_PATH);
+    }
+
+    if (platform() !== 'win32') {
+      chmodSync(BIN_PATH, 0o755);
+    }
+
+    console.log(`[cloudflared] Installed to ${BIN_PATH}`);
+    return BIN_PATH;
+  })().finally(() => {
+    downloadPromise = null;
+  });
 
-  console.log(`[cloudflared] Installed to ${BIN_PATH}`);
-  return BIN_PATH;
+  return downloadPromise;
 }
 
 export function isInstalled(): boolean {
@@ -130,6 +170,7 @@ function pushLog(line: string) {
 }
 
 export async function startTunnel(localPort: number = parseInt(process.env.PORT || '3000')): Promise<{ url?: string; error?: string }> {
+  console.log(`[tunnel] Starting tunnel on port ${localPort}...`);
   // Check if this worker already has a process
   if (state.process) {
     return state.url ? { url: state.url } : { error: 'Tunnel is starting...' };
@@ -207,6 +248,7 @@ export async function startTunnel(localPort: number = parseInt(process.env.PORT
       state.status = 'error';
       state.error = err.message;
       pushLog(`[error] ${err.message}`);
+      console.error(`[tunnel] Error: ${err.message}`);
       if (!resolved) {
         resolved = true;
         resolve({ error: err.message });
@@ -214,16 +256,19 @@ export async function startTunnel(localPort: number = parseInt(process.env.PORT
     });
 
     state.process.on('exit', (code) => {
+      const recentLog = state.log.slice(-5).join(' ').slice(0, 200);
+      const reason = code !== 0 ? `cloudflared failed (exit ${code}): ${recentLog || 'no output'}` : 'cloudflared stopped';
+      console.log(`[tunnel] ${reason}`);
       state.process = null;
       if (state.status !== 'error') {
         state.status = 'stopped';
       }
       state.url = null;
       saveTunnelState();
-      pushLog(`[exit] cloudflared exited with code ${code}`);
+      pushLog(`[exit] ${reason}`);
       if (!resolved) {
         resolved = true;
-        resolve({ error: `cloudflared exited with code ${code}` });
+        resolve({ error: reason });
       }
     });
 
@@ -241,6 +286,7 @@ export async function startTunnel(localPort: number = parseInt(process.env.PORT
 }
 
 export function stopTunnel() {
+  console.log('[tunnel] Stopping tunnel');
   stopHealthCheck();
   if (state.process) {
     state.process.kill('SIGTERM');

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