@aion0/forge 0.6.3 → 0.8.0

package/lib/chat-standalone.ts

@@ -0,0 +1,286 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Chat backend standalone — HTTP server on $CHAT_PORT (default 8408).
+ *
+ * Why a standalone:
+ *   - Exclusive writer to chat_sessions / chat_messages tables, mirroring
+ *     the workspace daemon pattern (avoids multi-writer races across
+ *     Next.js workers).
+ *   - One canonical endpoint for every surface: web `/chat` tab (via Next
+ *     proxy), `forge chat` CLI, Telegram bot, extension side panel.
+ *   - LLM streams can run for tens of seconds without occupying a Next
+ *     worker for the whole turn.
+ *
+ * Loopback-only — Next.js routes proxy requests in; CLI/Telegram talk
+ * directly. Auth happens at the Next.js / Telegram layer.
+ *
+ * Routes:
+ *   GET    /api/status
+ *   GET    /api/sessions
+ *   POST   /api/sessions                       { title?, model?, provider?, system_prompt?, meta? }
+ *   GET    /api/sessions/:id?after_ts=&limit=
+ *   PATCH  /api/sessions/:id
+ *   DELETE /api/sessions/:id
+ *   POST   /api/sessions/:id/messages          { text } → 202 { topic }
+ *   GET    /api/sessions/:id/events            SSE stream of agent events
+ *
+ * Fanout:
+ *   Each agent event is delivered to (a) local SSE subscribers and
+ *   (b) the browser bridge as `chat:<session_id>` push. Browser surfaces
+ *   keep their existing WS path; HTTP-only surfaces use SSE.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import {
+  createSession, getSession, listSessions, updateSession, deleteSession, listMessages,
+  clearSessionMessages, ensureMainSession, forkSession,
+} from './chat/session-store';
+import { runTurn, type AgentEvent } from './chat/agent-loop';
+import { bridgePush } from './chat/bridge-client';
+
+const PORT = Number(process.env.CHAT_PORT) || 8408;
+const startTime = Date.now();
+
+// ─── SSE subscriber registry ──────────────────────────────
+
+const sseSubs = new Map<string, Set<ServerResponse>>(); // session_id → subscribers
+
+function addSseSub(sessionId: string, res: ServerResponse): void {
+  let set = sseSubs.get(sessionId);
+  if (!set) { set = new Set(); sseSubs.set(sessionId, set); }
+  set.add(res);
+}
+
+function removeSseSub(sessionId: string, res: ServerResponse): void {
+  const set = sseSubs.get(sessionId);
+  if (!set) return;
+  set.delete(res);
+  if (set.size === 0) sseSubs.delete(sessionId);
+}
+
+function fanoutEvent(sessionId: string, event: AgentEvent): void {
+  // (a) browser bridge push — extension side panels listen on this topic.
+  void bridgePush(`chat:${sessionId}`, event);
+  // (b) local SSE subscribers — CLI, web tab, future surfaces.
+  const set = sseSubs.get(sessionId);
+  if (!set || set.size === 0) return;
+  const frame = `data: ${JSON.stringify(event)}\n\n`;
+  for (const res of set) {
+    try { res.write(frame); } catch {}
+  }
+}
+
+// ─── HTTP helpers ─────────────────────────────────────────
+
+async function readJson(req: IncomingMessage): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf-8');
+      if (!raw) return resolve({});
+      try { resolve(JSON.parse(raw)); } catch (e) { reject(e); }
+    });
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.statusCode = status;
+  res.setHeader('content-type', 'application/json');
+  res.end(JSON.stringify(body));
+}
+
+// ─── Route handlers ───────────────────────────────────────
+
+async function handleSessionsList(_req: IncomingMessage, res: ServerResponse, url: URL): Promise<void> {
+  const limit = Math.min(200, Math.max(1, Number(url.searchParams.get('limit') || 50)));
+  sendJson(res, 200, { sessions: listSessions(limit) });
+}
+
+async function handleSessionCreate(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const body = await readJson(req);
+  const session = createSession({
+    title: body.title,
+    model: body.model,
+    provider: body.provider,
+    system_prompt: body.system_prompt,
+    meta: body.meta,
+  });
+  sendJson(res, 200, { session });
+}
+
+async function handleSessionGet(_req: IncomingMessage, res: ServerResponse, id: string, url: URL): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  const after_ts = Number(url.searchParams.get('after_ts') || 0);
+  const limit = Math.min(2000, Math.max(1, Number(url.searchParams.get('limit') || 500)));
+  sendJson(res, 200, { session, messages: listMessages(id, { after_ts, limit }) });
+}
+
+async function handleSessionPatch(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  const body = await readJson(req);
+  const ok = updateSession(id, {
+    title: body.title,
+    model: body.model,
+    provider: body.provider,
+    system_prompt: body.system_prompt,
+    meta: body.meta,
+  });
+  sendJson(res, 200, { ok, session: getSession(id) });
+}
+
+async function handleSessionDelete(_req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  // Refuse to delete the persistent main session — the UI is allowed to
+  // "clear" it (drop messages, keep the session) via DELETE /messages.
+  const session = getSession(id);
+  if (session?.meta && (session.meta as any).kind === 'main') {
+    return sendJson(res, 400, { error: 'cannot delete the main session — use DELETE /api/sessions/:id/messages to clear it' });
+  }
+  const ok = deleteSession(id);
+  sendJson(res, 200, { ok });
+}
+
+async function handleSessionClearMessages(_req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  const removed = clearSessionMessages(id);
+  sendJson(res, 200, { ok: true, removed });
+}
+
+async function handleSessionFork(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const body = await readJson(req).catch(() => ({}));
+  const title = body?.title ? String(body.title) : undefined;
+  const upToTs = typeof body?.up_to_ts === 'number' ? body.up_to_ts : undefined;
+  const fork = forkSession(id, { title, upToTs });
+  if (!fork) return sendJson(res, 404, { error: 'source session not found' });
+  sendJson(res, 200, { ok: true, session: fork });
+}
+
+async function handleMessagePost(req: IncomingMessage, res: ServerResponse, id: string): Promise<void> {
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+  const body = await readJson(req);
+  const text = String(body?.text || '').trim();
+  if (!text) return sendJson(res, 400, { error: 'text is required' });
+
+  const startedAt = Date.now();
+  void runTurn({
+    sessionId: id,
+    userText: text,
+    callbacks: { onEvent: (e: AgentEvent) => fanoutEvent(id, e) },
+  }).then((r) => {
+    if (!r.ok) fanoutEvent(id, { type: 'error', data: { error: r.error || 'unknown' } });
+    console.log(`[chat] turn ${id.slice(0, 8)} done in ${Date.now() - startedAt}ms ok=${r.ok}`);
+  }).catch((err) => {
+    fanoutEvent(id, { type: 'error', data: { error: (err as Error).message } });
+    console.error('[chat] turn error', err);
+  });
+
+  sendJson(res, 202, { accepted: true, topic: `chat:${id}` });
+}
+
+function handleEventsSse(_req: IncomingMessage, res: ServerResponse, id: string): void {
+  // Verify the session exists before opening the stream.
+  const session = getSession(id);
+  if (!session) return sendJson(res, 404, { error: 'session not found' });
+
+  res.statusCode = 200;
+  res.setHeader('content-type', 'text/event-stream');
+  res.setHeader('cache-control', 'no-cache, no-transform');
+  res.setHeader('connection', 'keep-alive');
+  res.setHeader('x-accel-buffering', 'no'); // disable proxy buffering
+  res.write(`: subscribed to chat:${id}\n\n`);
+
+  addSseSub(id, res);
+
+  // Heartbeat every 25s keeps proxies from idling out.
+  const hb = setInterval(() => {
+    try { res.write(`: ping ${Date.now()}\n\n`); } catch {}
+  }, 25_000);
+  hb.unref?.();
+
+  const cleanup = () => {
+    clearInterval(hb);
+    removeSseSub(id, res);
+    try { res.end(); } catch {}
+  };
+  res.on('close', cleanup);
+  res.on('error', cleanup);
+}
+
+// ─── Router ───────────────────────────────────────────────
+
+async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const url = new URL(req.url || '/', 'http://localhost');
+  const m = req.method || 'GET';
+
+  if (m === 'GET' && url.pathname === '/api/status') {
+    return sendJson(res, 200, {
+      port: PORT,
+      uptime_seconds: Math.floor((Date.now() - startTime) / 1000),
+      active_sse_sessions: sseSubs.size,
+      sse_subscribers: [...sseSubs.values()].reduce((n, s) => n + s.size, 0),
+    });
+  }
+
+  if (m === 'GET' && url.pathname === '/api/sessions') return handleSessionsList(req, res, url);
+  if (m === 'POST' && url.pathname === '/api/sessions') return handleSessionCreate(req, res);
+  if (m === 'GET' && url.pathname === '/api/sessions/main') {
+    return sendJson(res, 200, { session: ensureMainSession() });
+  }
+
+  const detail = /^\/api\/sessions\/([^/]+)$/.exec(url.pathname);
+  if (detail) {
+    const id = detail[1]!;
+    if (m === 'GET') return handleSessionGet(req, res, id, url);
+    if (m === 'PATCH') return handleSessionPatch(req, res, id);
+    if (m === 'DELETE') return handleSessionDelete(req, res, id);
+  }
+
+  const messages = /^\/api\/sessions\/([^/]+)\/messages$/.exec(url.pathname);
+  if (messages && m === 'POST')   return handleMessagePost(req, res, messages[1]!);
+  if (messages && m === 'DELETE') return handleSessionClearMessages(req, res, messages[1]!);
+
+  const fork = /^\/api\/sessions\/([^/]+)\/fork$/.exec(url.pathname);
+  if (fork && m === 'POST') return handleSessionFork(req, res, fork[1]!);
+
+  const events = /^\/api\/sessions\/([^/]+)\/events$/.exec(url.pathname);
+  if (events && m === 'GET') return handleEventsSse(req, res, events[1]!);
+
+  sendJson(res, 404, { error: 'not found' });
+}
+
+// ─── Boot ─────────────────────────────────────────────────
+
+const httpServer = createServer((req, res) => {
+  route(req, res).catch((err) => {
+    console.error('[chat] http error:', err);
+    try { sendJson(res, 500, { error: 'internal' }); } catch {}
+  });
+});
+
+httpServer.listen(PORT, '127.0.0.1', () => {
+  console.log(`[chat] Chat standalone listening on http://127.0.0.1:${PORT}`);
+  // Make sure exactly one persistent main session exists. The UI uses
+  // meta.kind === 'main' to pin it, refuse delete, and route the
+  // top-level "clear" button to DELETE /messages instead.
+  try {
+    const main = ensureMainSession();
+    console.log(`[chat] Main session: ${main.id.slice(0, 8)} "${main.title}"`);
+  } catch (e) { console.warn('[chat] ensureMainSession failed:', (e as Error).message); }
+});
+
+function shutdown(): void {
+  console.log('[chat] shutting down');
+  for (const set of sseSubs.values()) {
+    for (const res of set) { try { res.end(); } catch {} }
+  }
+  sseSubs.clear();
+  httpServer.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 2000).unref();
+}
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);

package/lib/crypto.ts

@@ -63,5 +63,5 @@ export function hashSecret(value: string): string {
 }
 
 /** Secret field names in settings */
-export const SECRET_FIELDS = ['telegramBotToken', 'telegramTunnelPassword'] as const;
+export const SECRET_FIELDS = ['telegramBotToken', 'telegramTunnelPassword', 'temperKey'] as const;
 export type SecretField = typeof SECRET_FIELDS[number];

package/lib/health.ts

@@ -0,0 +1,131 @@
+/**
+ * External-tool health checks. Surfaced two ways:
+ *   - On startup (lib/init.ts) — one log line per tool with install hint
+ *     if missing, so server logs make the problem obvious
+ *   - Via `GET /api/health/tools` — the Pipelines view uses this to show
+ *     a banner when a tool needed by a built-in workflow isn't installed
+ *
+ * Add new tools by extending CHECKS. Tools are marked "optional" when a
+ * subset of Forge features needs them — the absence isn't an error, just
+ * a heads-up that those features won't work.
+ */
+
+import { execSync } from 'node:child_process';
+
+export interface ToolStatus {
+  /** binary name as invoked from PATH */
+  name: string;
+  /** human-readable label for UI */
+  label: string;
+  /** what part of Forge needs this — shown in the warning */
+  needed_for: string;
+  /** absolute path if installed, '' otherwise */
+  path: string;
+  /** parsed version string if we could pull one */
+  version: string;
+  /** true iff `which <name>` found it */
+  installed: boolean;
+  /** copy-pasteable install / auth instructions when missing */
+  install_hint: string;
+}
+
+interface Check {
+  name: string;
+  label: string;
+  needed_for: string;
+  versionFlag?: string;          // arg to invoke for version probe (default --version)
+  install_hint: string;
+}
+
+const CHECKS: Check[] = [
+  {
+    name: 'glab',
+    label: 'GitLab CLI',
+    needed_for: 'gitlab-issue-fix-and-review + mantis-bug-fix-and-mr pipelines (push branches + open MRs)',
+    install_hint: [
+      'macOS:  brew install glab',
+      'Linux:  https://gitlab.com/gitlab-org/cli/-/releases (deb/rpm/tar)',
+      'Windows: winget install GitLab.cli',
+      'Then auth once per host:  glab auth login --hostname <your-gitlab.example.com>',
+    ].join('\n'),
+  },
+  {
+    name: 'gh',
+    label: 'GitHub CLI',
+    needed_for: 'issue-fix-and-review pipeline + GitHub issue scanner',
+    install_hint: [
+      'macOS:  brew install gh',
+      'Linux:  https://cli.github.com/manual/installation',
+      'Then auth once:  gh auth login',
+    ].join('\n'),
+  },
+  {
+    name: 'git',
+    label: 'git',
+    needed_for: 'every pipeline (worktree, fetch, push)',
+    install_hint: [
+      'macOS:  xcode-select --install   (or brew install git)',
+      'Linux:  apt install git  /  dnf install git',
+      'Windows: https://git-scm.com/download/win',
+    ].join('\n'),
+  },
+  {
+    name: 'jq',
+    label: 'jq',
+    needed_for: 'gitlab-issue-fix-and-review (parses glab JSON)',
+    install_hint: [
+      'macOS:  brew install jq',
+      'Linux:  apt install jq  /  dnf install jq',
+    ].join('\n'),
+  },
+];
+
+function which(bin: string): string {
+  try {
+    return execSync(`which ${bin}`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function version(bin: string, flag = '--version'): string {
+  try {
+    const out = execSync(`${bin} ${flag}`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    // First line, usually like "git version 2.42.0" or "glab version 1.40.0 (...)"
+    return out.split('\n')[0] || '';
+  } catch {
+    return '';
+  }
+}
+
+export function checkTools(): ToolStatus[] {
+  return CHECKS.map((c) => {
+    const path = which(c.name);
+    return {
+      name: c.name,
+      label: c.label,
+      needed_for: c.needed_for,
+      path,
+      version: path ? version(c.name, c.versionFlag) : '',
+      installed: !!path,
+      install_hint: c.install_hint,
+    };
+  });
+}
+
+/**
+ * Log a one-line summary per tool to the startup console. For missing
+ * ones, also log the install hint so users see it without poking at the
+ * UI.
+ */
+export function logToolStatus(): void {
+  const results = checkTools();
+  for (const r of results) {
+    if (r.installed) {
+      console.log(`[tools] ✓ ${r.name.padEnd(6)} ${r.version || r.path}`);
+    } else {
+      console.warn(`[tools] ✗ ${r.name.padEnd(6)} NOT FOUND — ${r.needed_for}`);
+      for (const line of r.install_hint.split('\n')) console.warn(`         ${line}`);
+    }
+  }
+}

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

@@ -16,7 +16,8 @@ Forge is a self-hosted Vibe Coding platform for Claude Code. It provides a brows
 | **Telegram Bot** | Mobile control — submit tasks, receive notifications |
 | **Remote Access** | One-click Cloudflare tunnel for remote browsing |
 | **GitHub Issue Auto-fix** | Scan issues, auto-fix, create PRs |
-| **Memory (optional)** | Code graph + knowledge via `@aion0/temper` MCP server |
+| **Memory** | Long-term chat memory. Configure `@aion0/temper` for semantic + graph search, or leave URL/key blank to use the built-in local SQLite store (same block/episode API, keyword search). |
+| **Web Chat (simplified)** | `/chat` — minimal in-browser chat UI for use without the extension. Sessions, SSE streaming, memory badge. Full connector UX still lives in the extension. |
 | **IDE Plugins** | First-party VSCode extension and IntelliJ plugin — drive workspaces, agents, terminals, pipelines and docs from inside the editor (see `13-ide-plugins.md`) |
 
 ## Quick Start

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

@@ -103,14 +103,14 @@ Profiles are reusable configurations that extend a base agent with custom enviro
 
 ```yaml
 agents:
-  forti-k2:
+  forge-k2:
     base: claude
-    name: Forti K2
-    model: forti-k2
+    name: Forge K2
+    model: forge-k2
     env:
       ANTHROPIC_AUTH_TOKEN: sk-xxx
       ANTHROPIC_BASE_URL: http://my-server:7001/
-      ANTHROPIC_SMALL_FAST_MODEL: forti-k2
+      ANTHROPIC_SMALL_FAST_MODEL: forge-k2
       CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "true"
       DISABLE_TELEMETRY: "true"
 ```
@@ -143,31 +143,51 @@ 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
+    profile: forge-k2    # Claude will use forge-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
+## API agent profiles
 
-Configure API keys for direct API access (used by API-backend smiths):
+API access (used by API-backend smiths and the chat backend) is configured
+as agent profiles with `type: api`. The same profile is reused everywhere
+— no separate provider/key duplication.
 
 ```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
+agents:
+  my-litellm:
+    type: api
+    name: My LiteLLM
+    provider: litellm            # display label
+    model: claude-sonnet-4-6
+    apiKey: sk-...               # encrypted on save
+    baseUrl: http://127.0.0.1:4000/v1   # LiteLLM / Azure / self-hosted proxy
+
+  direct-anthropic:
+    type: api
+    name: Anthropic Direct
+    provider: anthropic
+    model: claude-haiku-4-5-20251001
+    apiKey: sk-ant-...
+
+chatAgent: my-litellm             # which profile Forge's chat backend uses
 ```
 
-Provider API keys are encrypted with AES-256-GCM. The UI shows masked values (••••••••).
+The chat backend (extension chat, `forge chat`, Telegram `/chat`) picks
+`settings.chatAgent` by default; a session can override via
+`Session.provider = <profile-id>`.
+
+Provider → adapter mapping for chat:
+- `provider: anthropic` (or `claude`) → Anthropic Messages API protocol
+- everything else → OpenAI-compatible protocol (LiteLLM, Grok, Google via
+  LiteLLM, OpenAI itself, Azure)
+
+`baseUrl` falls back to `env.ANTHROPIC_BASE_URL` / `env.OPENAI_BASE_URL` /
+`env.OPENAI_API_BASE` if not set directly. `apiKey` falls back to
+`env.ANTHROPIC_API_KEY` / `env.ANTHROPIC_AUTH_TOKEN` /
+`env.OPENAI_API_KEY`. This makes a single profile usable both by a CLI
+(reads `env`) and by chat (reads the top-level field).
 
 ## Admin Password
 
@@ -177,7 +197,7 @@ Provider API keys are encrypted with AES-256-GCM. The UI shows masked values (
 
 ## Encrypted Fields
 
-`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`.
+`telegramBotToken` and `telegramTunnelPassword` are encrypted with AES-256-GCM. Agent profile `apiKey` fields are also encrypted. The encryption key is stored at `~/.forge/data/.encrypt-key`.
 
 ## Settings UI
 
@@ -188,8 +208,9 @@ The Settings modal has these sections:
 | **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 |
+| **Profiles** | Agent profiles (CLI + API) — API profiles also power Forge chat |
+| **Memory (Temper)** | Long-term memory backend for the chat agent. When Temper URL+key are blank, chat falls back to a local SQLite store with the same block/episode tools (keyword search only — no semantic/graph search). |
+| **Chat backend** | Pick the default API profile for chat (extension / CLI / Telegram) |
 | **Telegram** | Bot token, chat ID, notification toggles |
 | **Display** | Name, email |
 | **Other** | Skip permissions, skills repo URL, notification retention |

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

@@ -81,7 +81,7 @@ There are two ways to open a terminal for a project:
 
 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
+- **Profiles** (e.g., Forge 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)
 

package/lib/help-docs/16-gitlab-autofix.md

@@ -0,0 +1,114 @@
+# GitLab Issue Auto-fix
+
+Scan **self-hosted GitLab issues**, resolve base branch from issue metadata,
+create a per-issue **worktree**, run Claude on the issue (with Premium epic
+context + downloaded image attachments), and open an MR — all automated.
+
+Mirrors the existing GitHub flow (`issue-fix-and-review`) but built around
+the `glab` CLI and adapted for Premium epic links + image uploads.
+
+## Setup
+
+### 1. Install + auth glab
+
+```bash
+brew install glab
+glab auth login --hostname <your-gitlab.example.com>
+```
+
+GitLab host is auto-detected per project from the git remote, so you only
+need to authenticate once per host. Self-hosted is fully supported.
+
+### 2. Bind the pipeline to your project
+
+Project tab → **Pipelines** → `+ Add` → `gitlab-issue-fix-and-review`.
+
+In the binding form set:
+- **Labels** (optional) — only process issues matching these labels
+- **Assignee filter** — `me` (default), specific username, or empty
+- **Base branch rule** — how to derive target branch from issue:
+  - `milestone` (default): `release/<milestone-title-slug>`
+  - `label:<prefix>`: pick first label starting with `<prefix>`, strip it
+    (e.g. `label:branch:` → label `branch:hotfix/4.5` → base `hotfix/4.5`)
+  - `desc`: regex match `^Base: <branch>` in issue description
+  - `default`: just `main` (or repo default)
+- **Base branch override** — string; bypasses the rule entirely
+- **MR title template** — vars: `{issue_id}`, `{issue_title}`.
+  Default: `Fix #{issue_id}: {issue_title}`
+- **MR body template** — vars: `{issue_id}`, `{issue_url}`, `{summary}`.
+  Default closes the issue and inlines Claude's summary.
+- **Schedule** — interval in minutes (`0` = manual only)
+
+### 3. Triggering
+
+Three ways:
+
+| Mode | How |
+|---|---|
+| Manual single-issue | `Run` button in Pipelines tab → enter `issue_id` |
+| Manual scan-all | `Scan` button → fetches assigned issues, fans out, dedups |
+| Scheduled | Set interval > 0 in config; runs on Forge boot + every N min |
+
+## Pipeline nodes
+
+```
+resolve              → parse host + project path from origin
+fetch-issue          → glab issue view → JSON (title, description, labels, milestone, epic.iid)
+fetch-extras         → glab api → comments JSON + epic JSON (Premium)
+resolve-base-branch  → apply rule from config
+worktree-setup       → git worktree add .forge/worktrees/issue-<id>
+download-attachments → curl GitLab /uploads/.../filename into .attachments/
+fix-code             → claude in worktree, prompt = issue + comments + epic + images
+push-and-mr          → git push + glab mr create
+notify-issue         → glab issue note → "🤖 Forge opened MR: <url>"
+```
+
+Pipeline output: an MR URL on the issue + linked from comments.
+
+## Storage
+
+Per-project config + dedup tracking lives in `workflow.db`:
+
+- `issue_autofix_gitlab_config` — projectPath → config
+- `issue_autofix_gitlab_processed` — projectPath × issueIid → status + MR
+
+Already-processed issues are skipped in scan mode. Use `reset` to re-trigger,
+or `retry` with extra context to nudge Claude in a different direction.
+
+## Image attachments
+
+GitLab uploads (`/uploads/<32-hex>/<file>`) in issue descriptions are
+auto-downloaded to `<worktree>/.attachments/`. Claude can `Read` those
+files. PNG/JPG/PDF supported via Claude Code's image reader.
+
+The download uses the same PAT that glab already has authenticated (so
+no extra credential setup). Falls back to anonymous HTTPS if the upload
+happens to be public.
+
+## Premium: Epic context
+
+If the issue links to an epic (`issue.epic.iid` present), the pipeline:
+1. Fetches the epic via `glab api groups/<id>/epics/<iid>`
+2. Includes epic description + acceptance criteria in Claude's prompt
+3. Claude can read the full JSON dump file path from `fetch-extras`
+
+Free-tier instances just skip this step — no error.
+
+## Authentication notes
+
+`glab auth login` stores a token at `~/.config/glab-cli/config.yml`. Forge
+inherits the env; the spawned `glab` invocations from the pipeline use the
+same credentials. **No env vars needed** unless you want to override per-
+session.
+
+For headless / CI mode use `GITLAB_TOKEN` env var — `glab` picks it up too.
+
+## Troubleshooting
+
+| Symptom | Cause + fix |
+|---|---|
+| `ERROR: glab CLI not installed` | `brew install glab` (or apt) and `glab auth login` |
+| `glab CLI not authenticated` | Token expired or wrong host. `glab auth login --hostname <host>` |
+| MR push fails with "main branch protected" | Configure GitLab to allow force-push to `fix/*` branches OR change pipeline to drop `--force-with-lease` |
+| Base branch resolves wrong | Switch `baseBranchRule` to `desc` and add `Base: <branch>` to the issue description as a forcing override |
+| `403 on attachment fetch` | Some self-hosted instances require token even for public-link uploads. Make sure glab is authenticated to the same host that issued the upload URL |