forgehive 0.7.2 → 0.7.3

package/README.md

@@ -15,7 +15,7 @@
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js ≥ 18">
   <img src="https://img.shields.io/badge/typescript-5.8-blue" alt="TypeScript">
   <img src="https://img.shields.io/badge/tests-267%20passing-success" alt="267 tests">
-  <img src="https://img.shields.io/badge/bundle-244KB-lightgrey" alt="244KB bundle">
+  <img src="https://img.shields.io/badge/bundle-247KB-lightgrey" alt="247KB bundle">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
 </p>
 
@@ -109,14 +109,14 @@ This makes both `fh` and `forgehive` available globally.
 git clone https://github.com/matharnica/forgehive
 cd forgehive
 npm install
-npm run build      # compiles to dist/cli.js (~244 KB)
+npm run build      # compiles to dist/cli.js (~247 KB)
 npm link           # makes 'fh' available globally
 ```
 
 Verify the installation:
 
 ```bash
-fh --version       # should print 0.7.1
+fh --version       # should print 0.7.2
 fh --help          # lists all available commands
 ```
 
@@ -166,11 +166,15 @@ fh security report gdpr   # generates a CISO-ready compliance report
 
 | Command | Description |
 |---|---|
-| `fh init` | Scan project, create `.forgehive/`, merge CLAUDE.md block, write AGENTS.md |
+| `fh --help` | Show full command reference |
+| `fh -h` | Same as --help |
+| `fh init` | Set up forgehive in the current project. Use --force to re-initialize an existing setup |
 | `fh confirm` | Confirm `capabilities.yaml` — activates context for Claude |
 | `fh rollback` | Remove `.forgehive/` and the CLAUDE.md block cleanly |
 | `fh status` | Show current project status, drift warning if scan is outdated |
 
+> Running `fh init` on a project that already has `.forgehive/` prints a warning and exits. Use `fh init --force` to re-initialize (overwrites `capabilities.yaml` and scans again). To update only the scan, use `fh scan --update`.
+
 **When to use `fh rollback`:** If you want to remove forgehive from a project entirely. It removes exactly the block it inserted into CLAUDE.md (nothing else) and deletes `.forgehive/`.
 
 ---
@@ -407,11 +411,12 @@ fh story create "As a user I want to log in" --epic EPC-1 --points 3   # with ep
 fh story list                                            # list all backlog stories
 fh story list --epic EPC-1                              # filter by epic
 fh story show US-1                                       # show full story card with acceptance criteria
+fh story sprint US-1                                     # mark story as in-sprint (pulled into current sprint)
 fh story done US-1                                       # mark story as done
 fh story done US-1 --points 5                           # mark done and record actual points
 ```
 
-Each story card is a Markdown file at `.forgehive/memory/stories/US-N.md`. The card includes a title, acceptance criteria placeholder, story points, epic link, and status (`backlog` | `done`). When you run `/fh-sprint` in a Claude Code session, Claude reads the backlog and uses velocity data to suggest a realistic sprint scope.
+Each story card is a Markdown file at `.forgehive/memory/stories/US-N.md`. The card includes a title, acceptance criteria placeholder, story points, epic link, and status (`backlog` | `in-sprint` | `done`). Stories move through `backlog → in-sprint → done`. When you run `/fh-sprint` in a Claude Code session, Claude reads the backlog and uses velocity data to suggest a realistic sprint scope.
 
 ---
 
@@ -842,7 +847,7 @@ Global credential store (chmod 600). Managed exclusively via `fh mcp auth` comma
 |---|---|
 | Runtime | Node.js ≥ 18, ESM |
 | Language | TypeScript |
-| Build | esbuild -> `dist/cli.js` (~244 KB, single bundle) |
+| Build | esbuild -> `dist/cli.js` (~247 KB, single bundle) |
 | Type check | `tsc --noEmit` |
 | Tests | `node:test` (native) + tsx ESM loader, 267 tests |
 | Dependencies | `js-yaml` (sole runtime dependency) |

package/dist/cli.js

@@ -2751,8 +2751,8 @@ var init_harness = __esm({
 
 // src/cli.ts
 init_js_yaml();
-import fs30 from "node:fs";
-import path31 from "node:path";
+import fs31 from "node:fs";
+import path32 from "node:path";
 
 // src/scanner.ts
 import fs from "node:fs";
@@ -6454,17 +6454,206 @@ function formatVelocityReport(history) {
   return lines.join("\n");
 }
 
+// src/docs.ts
+init_js_yaml();
+import fs30 from "node:fs";
+import path31 from "node:path";
+import { spawnSync as spawnSync11 } from "node:child_process";
+var SOURCE_EXTS = [".ts", ".tsx", ".js", ".jsx", ".py", ".go"];
+var IGNORE_DIRS3 = ["node_modules", ".git", "dist", ".forgehive", "coverage", ".next", "build", "test"];
+var EXPORT_PATTERNS = [
+  /^export\s+(?:async\s+)?function\s+(\w+)/gm,
+  /^export\s+(?:const|let|var)\s+(\w+)/gm,
+  /^export\s+(?:class|interface|type|enum)\s+(\w+)/gm,
+  /^export\s+default\s+(?:function\s+)?(\w+)?/gm
+];
+function readCapabilities2(forgehiveDir2) {
+  const capPath = path31.join(forgehiveDir2, "capabilities.yaml");
+  if (!fs30.existsSync(capPath)) return {};
+  try {
+    return jsYaml.load(fs30.readFileSync(capPath, "utf8")) ?? {};
+  } catch {
+    return {};
+  }
+}
+function readMemoryFiles2(forgehiveDir2) {
+  const memDir = path31.join(forgehiveDir2, "memory");
+  if (!fs30.existsSync(memDir)) return {};
+  const result = {};
+  for (const f of fs30.readdirSync(memDir).filter((f2) => f2.endsWith(".md") && f2 !== "MEMORY.md")) {
+    result[f] = fs30.readFileSync(path31.join(memDir, f), "utf8");
+  }
+  return result;
+}
+function getRecentCommits2(projectRoot2, n = 10) {
+  const result = spawnSync11("git", ["log", "--oneline", `-${n}`], { cwd: projectRoot2, encoding: "utf8" });
+  if (result.status !== 0) return [];
+  return result.stdout.trim().split("\n").filter(Boolean);
+}
+function extractExports(content) {
+  const exports = [];
+  for (const pattern of EXPORT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let m;
+    while ((m = pattern.exec(content)) !== null) {
+      if (m[1]) exports.push(m[1]);
+    }
+  }
+  return [...new Set(exports)];
+}
+function walkSourceFiles(dir) {
+  const results = [];
+  function walk(current) {
+    if (!fs30.existsSync(current)) return;
+    for (const entry of fs30.readdirSync(current, { withFileTypes: true })) {
+      if (IGNORE_DIRS3.includes(entry.name)) continue;
+      const full = path31.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && SOURCE_EXTS.includes(path31.extname(entry.name))) results.push(full);
+    }
+  }
+  walk(dir);
+  return results;
+}
+function generateUserGuide(projectRoot2, forgehiveDir2) {
+  const projectName = path31.basename(projectRoot2);
+  const caps = readCapabilities2(forgehiveDir2);
+  const memFiles = readMemoryFiles2(forgehiveDir2);
+  const commits = getRecentCommits2(projectRoot2);
+  const lines = [];
+  lines.push(`# ${projectName} \u2014 User Guide`);
+  lines.push("");
+  lines.push(`> Generated by forgehive on ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`);
+  lines.push("");
+  lines.push("## Overview");
+  lines.push("");
+  if (memFiles["project.md"]) {
+    const content = memFiles["project.md"].replace(/^---[\s\S]*?---\n/m, "").trim();
+    lines.push(content);
+  } else {
+    lines.push(`${projectName} is a ${caps.language ?? "software"} application.`);
+  }
+  lines.push("");
+  lines.push("## Requirements");
+  lines.push("");
+  const pm = caps.packageManager ?? "npm";
+  const lang = caps.language;
+  if (lang === "typescript" || lang === "javascript") {
+    lines.push("- **Node.js** \u2265 18");
+    lines.push(`- **${pm}** (package manager)`);
+  } else if (lang === "python") {
+    lines.push("- **Python** \u2265 3.9");
+    lines.push("- **pip** or **poetry**");
+  } else if (lang === "go") {
+    lines.push("- **Go** \u2265 1.21");
+  }
+  lines.push("");
+  lines.push("## Installation");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("# Clone the repository");
+  lines.push(`git clone <repo-url>`);
+  lines.push(`cd ${projectName}`);
+  lines.push("");
+  if (lang === "typescript" || lang === "javascript") {
+    lines.push(`${pm === "yarn" ? "yarn" : pm === "pnpm" ? "pnpm install" : "npm install"}`);
+  } else if (lang === "python") {
+    lines.push("pip install -r requirements.txt");
+  } else if (lang === "go") {
+    lines.push("go mod download");
+  }
+  lines.push("```");
+  lines.push("");
+  const entryPoints = caps.entryPoints;
+  if (Array.isArray(entryPoints) && entryPoints.length > 0) {
+    lines.push("## Getting Started");
+    lines.push("");
+    lines.push("```bash");
+    for (const ep of entryPoints.slice(0, 3)) lines.push(`node ${ep}`);
+    lines.push("```");
+    lines.push("");
+  }
+  if (memFiles["stack.md"]) {
+    lines.push("## Configuration");
+    lines.push("");
+    const content = memFiles["stack.md"].replace(/^---[\s\S]*?---\n/m, "").trim();
+    lines.push(content);
+    lines.push("");
+  }
+  if (commits.length > 0) {
+    lines.push("## Changelog");
+    lines.push("");
+    lines.push("Recent changes:");
+    lines.push("");
+    for (const c of commits.slice(0, 5)) lines.push(`- ${c}`);
+    lines.push("");
+    lines.push("Run `fh changelog` for the full changelog.");
+    lines.push("");
+  }
+  lines.push("## Support");
+  lines.push("");
+  lines.push("For issues, open a ticket in the project repository.");
+  return lines.join("\n");
+}
+function generateApiReference(projectRoot2) {
+  const srcDir = path31.join(projectRoot2, "src");
+  const searchDir = fs30.existsSync(srcDir) ? srcDir : projectRoot2;
+  const files = walkSourceFiles(searchDir);
+  const lines = [];
+  lines.push("# API Reference");
+  lines.push("");
+  lines.push(`Generated: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`);
+  lines.push("");
+  if (files.length === 0) {
+    lines.push("No source files found.");
+    return lines.join("\n");
+  }
+  for (const filePath of files) {
+    let content = "";
+    try {
+      content = fs30.readFileSync(filePath, "utf8");
+    } catch {
+      continue;
+    }
+    const exports = extractExports(content);
+    if (exports.length === 0) continue;
+    const relPath = path31.relative(projectRoot2, filePath);
+    lines.push(`## \`${relPath}\``);
+    lines.push("");
+    lines.push("**Exports:**");
+    lines.push("");
+    for (const exp of exports) lines.push(`- \`${exp}\``);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function listExistingDocs(projectRoot2) {
+  const docs = [];
+  const docsDir = path31.join(projectRoot2, "docs");
+  if (fs30.existsSync(docsDir)) {
+    for (const f of fs30.readdirSync(docsDir)) {
+      if (f.endsWith(".md")) docs.push(path31.join(docsDir, f));
+    }
+  }
+  const rootDocs = ["README.md", "CHANGELOG.md", "ONBOARDING.md", "CONTRIBUTING.md"];
+  for (const f of rootDocs) {
+    const full = path31.join(projectRoot2, f);
+    if (fs30.existsSync(full)) docs.push(full);
+  }
+  return docs;
+}
+
 // src/cli.ts
 var [, , command, subcommand, ...rest] = process.argv;
 var projectRoot = process.cwd();
-var forgehiveDir = path31.join(projectRoot, ".forgehive");
+var forgehiveDir = path32.join(projectRoot, ".forgehive");
 if (command === "--version" || command === "-v") {
-  console.log("0.7.2");
+  console.log("0.7.3");
   process.exit(0);
 }
 if (command === "--help" || command === "-h" || command === "help") {
   console.log(`
-forgehive v0.7.2 \u2014 Context-aware AI development environment
+forgehive v0.7.3 \u2014 Context-aware AI development environment
 
 USAGE
   fh <command> [subcommand] [options]
@@ -6495,6 +6684,12 @@ CODEBASE
   fh onboard [--output path]       Generate ONBOARDING.md
   fh changelog [--since tag]       Semantic changelog from git
   fh metrics [--since date]        Developer productivity metrics
+  fh docs                          List existing documentation
+  fh docs user [--output path]     Generate user-facing guide (docs/user-guide.md)
+  fh docs api [--output path]      Generate API reference from exports (docs/api.md)
+  fh docs onboard                  Generate onboarding doc
+  fh docs changelog [--since tag]  Generate changelog
+  fh docs adr "<title>"            Create Architecture Decision Record
 
 SPRINT PLANNING
   fh story create <title> [--epic EPC-N] [--points N]
@@ -6531,18 +6726,18 @@ COST
   process.exit(0);
 }
 function loadClaudeMdBlock() {
-  const templatePath = path31.join(
-    path31.dirname(new URL(import.meta.url).pathname),
+  const templatePath = path32.join(
+    path32.dirname(new URL(import.meta.url).pathname),
     "..",
     "forgehive",
     "templates",
     "claude-md.block.md"
   );
-  if (!fs30.existsSync(templatePath)) return "## forgehive\n\nSee .forgehive/ for configuration.";
-  return fs30.readFileSync(templatePath, "utf8");
+  if (!fs31.existsSync(templatePath)) return "## forgehive\n\nSee .forgehive/ for configuration.";
+  return fs31.readFileSync(templatePath, "utf8");
 }
 if (command === "init") {
-  const forgehiveDirExists = fs30.existsSync(forgehiveDir);
+  const forgehiveDirExists = fs31.existsSync(forgehiveDir);
   if (forgehiveDirExists && !rest.includes("--force")) {
     console.log(`\u26A0 .forgehive/ existiert bereits in diesem Projekt.`);
     console.log(`  Nutze 'fh init --force' um neu zu initialisieren (\xFCberschreibt capabilities.yaml).`);
@@ -6560,9 +6755,9 @@ if (command === "init") {
   const block = loadClaudeMdBlock();
   writeForgehiveDir(projectRoot, scanResult, capMap, block);
   const hash = computeHash(projectRoot);
-  fs30.writeFileSync(path31.join(forgehiveDir, ".scan-hash"), hash, "utf8");
-  const runtimeDir = path31.join(
-    path31.dirname(new URL(import.meta.url).pathname),
+  fs31.writeFileSync(path32.join(forgehiveDir, ".scan-hash"), hash, "utf8");
+  const runtimeDir = path32.join(
+    path32.dirname(new URL(import.meta.url).pathname),
     "..",
     "forgehive"
   );
@@ -6594,7 +6789,7 @@ if (command === "init") {
     process.exit(1);
   }
 } else if (command === "memory") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6603,7 +6798,7 @@ if (command === "init") {
   } else if (subcommand === "clean") {
     cleanMemory(forgehiveDir);
   } else if (subcommand === "export") {
-    const outputPath = rest[0] ?? path31.join(projectRoot, "forgehive-memory-export.md");
+    const outputPath = rest[0] ?? path32.join(projectRoot, "forgehive-memory-export.md");
     try {
       exportMemory(forgehiveDir, outputPath);
     } catch (err) {
@@ -6651,7 +6846,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
   } else if (subcommand === "snapshot") {
     const snapAction = rest[0];
     if (snapAction === "export") {
-      const outPath = rest[1] ?? path31.join(
+      const outPath = rest[1] ?? path32.join(
         projectRoot,
         `forgehive-snapshot-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}.json`
       );
@@ -6691,11 +6886,11 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     process.exit(1);
   }
 } else if (command === "scan" && subcommand === "--update") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
-  const savedHash = fs30.existsSync(path31.join(forgehiveDir, ".scan-hash")) ? fs30.readFileSync(path31.join(forgehiveDir, ".scan-hash"), "utf8").trim() : null;
+  const savedHash = fs31.existsSync(path32.join(forgehiveDir, ".scan-hash")) ? fs31.readFileSync(path32.join(forgehiveDir, ".scan-hash"), "utf8").trim() : null;
   const currentHash = computeHash(projectRoot);
   if (savedHash === currentHash) {
     console.log("\u2713 Keine \xC4nderungen erkannt \u2014 capabilities.yaml ist aktuell");
@@ -6703,7 +6898,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
   }
   console.log("\u{1F50D} \xC4nderungen erkannt \u2014 scanne erneut...\n");
   const oldDoc = jsYaml.load(
-    fs30.readFileSync(path31.join(forgehiveDir, "capabilities.yaml"), "utf8")
+    fs31.readFileSync(path32.join(forgehiveDir, "capabilities.yaml"), "utf8")
   );
   const oldMap = { confirmed: oldDoc.capabilities.confirmed ?? [], inferred: [] };
   const scanResult = scan(projectRoot);
@@ -6723,16 +6918,16 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     console.log();
     const block = loadClaudeMdBlock();
     writeForgehiveDir(projectRoot, scanResult, newMap, block);
-    fs30.writeFileSync(path31.join(forgehiveDir, ".scan-hash"), currentHash, "utf8");
+    fs31.writeFileSync(path32.join(forgehiveDir, ".scan-hash"), currentHash, "utf8");
     console.log("\u2713 scan-result.yaml und capabilities.yaml aktualisiert");
     console.log("  F\xFChre `fh confirm` aus um die \xC4nderungen zu best\xE4tigen");
   }
 } else if (command === "scan" && subcommand === "--check") {
-  if (!fs30.existsSync(path31.join(forgehiveDir, ".scan-hash"))) {
+  if (!fs31.existsSync(path32.join(forgehiveDir, ".scan-hash"))) {
     console.log("Warnung: Kein Scan-Hash gefunden. F\xFChre `fh init` aus.");
     process.exit(1);
   }
-  const saved = fs30.readFileSync(path31.join(forgehiveDir, ".scan-hash"), "utf8").trim();
+  const saved = fs31.readFileSync(path32.join(forgehiveDir, ".scan-hash"), "utf8").trim();
   const current = computeHash(projectRoot);
   if (saved !== current) {
     console.log("\u26A0 Codebase hat sich seit letztem Scan ge\xE4ndert.");
@@ -6741,7 +6936,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
   }
   console.log("\u2713 capabilities.yaml ist aktuell");
 } else if (command === "skills") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6777,7 +6972,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     process.exit(1);
   }
 } else if (command === "party") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6898,7 +7093,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     }
   }
 } else if (command === "wire") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6937,7 +7132,7 @@ N\xE4chster Schritt: Setze die erforderlichen Umgebungsvariablen und starte Clau
   const limitIdx = allArgs.indexOf("--limit");
   const alertIdx = allArgs.indexOf("--alert");
   if (limitIdx !== -1) {
-    if (!fs30.existsSync(forgehiveDir)) {
+    if (!fs31.existsSync(forgehiveDir)) {
       console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
       process.exit(1);
     }
@@ -6963,14 +7158,14 @@ N\xE4chster Schritt: Setze die erforderlichen Umgebungsvariablen und starte Clau
     }
     const sessions = parseCostSessions(projectRoot);
     console.log(formatCostReport(sessions, range));
-    if (fs30.existsSync(forgehiveDir)) {
+    if (fs31.existsSync(forgehiveDir)) {
       const total = sessions.reduce((s, x) => s + x.estimatedCostUsd, 0);
       const status = checkSpendStatus(forgehiveDir, total);
       if (status.message) console.log("\n" + status.message);
     }
   }
 } else if (command === "watch") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6986,7 +7181,7 @@ N\xE4chster Schritt: Setze die erforderlichen Umgebungsvariablen und starte Clau
     process.exit(0);
   });
 } else if (command === "mcp") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -7097,7 +7292,7 @@ Setze diese Umgebungsvariablen:`);
     process.exit(1);
   }
 } else if (command === "security") {
-  if (!fs30.existsSync(forgehiveDir)) {
+  if (!fs31.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -7183,8 +7378,8 @@ Setze diese Umgebungsvariablen:`);
 `);
     const report = generateSecurityReport(projectRoot, forgehiveDir, mode);
     const text = formatSecurityReport(report);
-    const reportPath = path31.join(forgehiveDir, "security-report.md");
-    fs30.writeFileSync(reportPath, text, "utf8");
+    const reportPath = path32.join(forgehiveDir, "security-report.md");
+    fs31.writeFileSync(reportPath, text, "utf8");
     console.log(text);
     console.log(`
 \u2713 Report gespeichert: ${reportPath}`);
@@ -7196,8 +7391,8 @@ Setze diese Umgebungsvariablen:`);
   } else if (subcommand === "permissions") {
     const { writePermissions: writePermissions2 } = await Promise.resolve().then(() => (init_harness(), harness_exports));
     writePermissions2(forgehiveDir);
-    const permPath = path31.join(forgehiveDir, "harness", "permissions.yaml");
-    console.log(fs30.readFileSync(permPath, "utf8"));
+    const permPath = path32.join(forgehiveDir, "harness", "permissions.yaml");
+    console.log(fs31.readFileSync(permPath, "utf8"));
   } else {
     console.error(`Unbekannter security-Subcommand: ${subcommand}`);
     console.error("Verf\xFCgbar: scan | deps | audit | report [gdpr|soc2|hipaa|none] | permissions");
@@ -7209,35 +7404,35 @@ Setze diese Umgebungsvariablen:`);
   const failOnArg = allCiArgs.includes("--fail-on") ? allCiArgs[allCiArgs.indexOf("--fail-on") + 1] : "high";
   const initFlag = allCiArgs.includes("--init");
   if (initFlag) {
-    const ghDir = path31.join(projectRoot, ".github", "workflows");
-    fs30.mkdirSync(ghDir, { recursive: true });
-    const outPath = path31.join(ghDir, "forgehive.yml");
-    fs30.writeFileSync(outPath, getGithubActionsTemplate(), "utf8");
+    const ghDir = path32.join(projectRoot, ".github", "workflows");
+    fs31.mkdirSync(ghDir, { recursive: true });
+    const outPath = path32.join(ghDir, "forgehive.yml");
+    fs31.writeFileSync(outPath, getGithubActionsTemplate(), "utf8");
     console.log(`\u2714 GitHub Actions workflow geschrieben: ${outPath}`);
   } else {
     const report = generateCiReport(projectRoot, forgehiveDir, failOnArg);
     const output = formatCiReport(report, format);
     console.log(output);
     if (format === "json") {
-      fs30.mkdirSync(forgehiveDir, { recursive: true });
-      fs30.writeFileSync(path31.join(forgehiveDir, "ci-report.json"), output, "utf8");
+      fs31.mkdirSync(forgehiveDir, { recursive: true });
+      fs31.writeFileSync(path32.join(forgehiveDir, "ci-report.json"), output, "utf8");
     }
     if (report.status === "fail") process.exit(1);
   }
 } else if (command === "map") {
   const map2 = generateMap(projectRoot);
   const md = formatMap(map2);
-  const mapPath = path31.join(forgehiveDir, "map.md");
-  fs30.mkdirSync(forgehiveDir, { recursive: true });
-  fs30.writeFileSync(mapPath, md, "utf8");
+  const mapPath = path32.join(forgehiveDir, "map.md");
+  fs31.mkdirSync(forgehiveDir, { recursive: true });
+  fs31.writeFileSync(mapPath, md, "utf8");
   console.log(md);
   console.log(`
 \u2714 Codebase-Map gespeichert: ${mapPath}`);
 } else if (command === "onboard") {
   const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
-  const outputPath = outputArg ?? path31.join(projectRoot, "ONBOARDING.md");
+  const outputPath = outputArg ?? path32.join(projectRoot, "ONBOARDING.md");
   const doc = generateOnboardingDoc(projectRoot, forgehiveDir);
-  fs30.writeFileSync(outputPath, doc, "utf8");
+  fs31.writeFileSync(outputPath, doc, "utf8");
   console.log(`\u2714 Onboarding-Dokument geschrieben: ${outputPath}`);
 } else if (command === "changelog") {
   const sinceArg = rest.includes("--since") ? rest[rest.indexOf("--since") + 1] : null;
@@ -7247,28 +7442,28 @@ Setze diese Umgebungsvariablen:`);
   const commits = parseGitLog(rawLog);
   let version = "unreleased";
   try {
-    const pkgPath = path31.join(projectRoot, "package.json");
-    if (fs30.existsSync(pkgPath)) {
-      const pkg = JSON.parse(fs30.readFileSync(pkgPath, "utf8").replace(/^\s*\/\/.*$/gm, ""));
+    const pkgPath = path32.join(projectRoot, "package.json");
+    if (fs31.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs31.readFileSync(pkgPath, "utf8").replace(/^\s*\/\/.*$/gm, ""));
       version = pkg.version ?? "unreleased";
     }
   } catch {
   }
   const md = formatChangelog(commits, version);
-  const outputPath = outputArg ?? path31.join(projectRoot, "CHANGELOG.md");
+  const outputPath = outputArg ?? path32.join(projectRoot, "CHANGELOG.md");
   let existing = "";
-  if (fs30.existsSync(outputPath)) existing = fs30.readFileSync(outputPath, "utf8");
-  fs30.writeFileSync(outputPath, md + "\n\n" + existing, "utf8");
+  if (fs31.existsSync(outputPath)) existing = fs31.readFileSync(outputPath, "utf8");
+  fs31.writeFileSync(outputPath, md + "\n\n" + existing, "utf8");
   console.log(`\u2714 CHANGELOG.md aktualisiert: ${outputPath}`);
   console.log(`  ${commits.length} Commits verarbeitet`);
 } else if (command === "metrics") {
   const sinceArg = rest.includes("--since") ? rest[rest.indexOf("--since") + 1] : void 0;
   const rawLog = getMetricsGitLog(projectRoot, sinceArg);
   const stats = parseCommitStats(rawLog);
-  const md = formatMetrics(stats, path31.basename(projectRoot));
-  const metricsPath = path31.join(forgehiveDir, "metrics.md");
-  fs30.mkdirSync(forgehiveDir, { recursive: true });
-  fs30.writeFileSync(metricsPath, md, "utf8");
+  const md = formatMetrics(stats, path32.basename(projectRoot));
+  const metricsPath = path32.join(forgehiveDir, "metrics.md");
+  fs31.mkdirSync(forgehiveDir, { recursive: true });
+  fs31.writeFileSync(metricsPath, md, "utf8");
   console.log(md);
   console.log(`
 \u2714 Metrics gespeichert: ${metricsPath}`);
@@ -7303,7 +7498,7 @@ Setze diese Umgebungsvariablen:`);
   console.log(`\u2714 ${result.message}`);
   console.log(`  fh run status   \u2014 aktive Sessions anzeigen`);
 } else if (command === "story") {
-  const storiesDir = path31.join(forgehiveDir, "memory", "stories");
+  const storiesDir = path32.join(forgehiveDir, "memory", "stories");
   if (subcommand === "create") {
     const title = rest.filter((r) => !r.startsWith("--")).join(" ");
     const epicArg = rest.includes("--epic") ? rest[rest.indexOf("--epic") + 1] : void 0;
@@ -7314,7 +7509,7 @@ Setze diese Umgebungsvariablen:`);
     }
     const story = createStory(storiesDir, title, epicArg);
     if (pointsArg) updateStoryPoints(storiesDir, story.id, pointsArg);
-    console.log(`\u2714 ${story.id} erstellt: ${path31.join(storiesDir, story.id + ".md")}`);
+    console.log(`\u2714 ${story.id} erstellt: ${path32.join(storiesDir, story.id + ".md")}`);
     console.log(`  Bearbeite die Datei um Acceptance Criteria hinzuzuf\xFCgen.`);
   } else if (subcommand === "list") {
     const epicFilter = rest.includes("--epic") ? rest[rest.indexOf("--epic") + 1] : null;
@@ -7363,8 +7558,8 @@ Setze diese Umgebungsvariablen:`);
     console.error("Verf\xFCgbar: fh story create | list | show | done");
   }
 } else if (command === "epic") {
-  const epicsDir = path31.join(forgehiveDir, "memory", "epics");
-  const storiesDir = path31.join(forgehiveDir, "memory", "stories");
+  const epicsDir = path32.join(forgehiveDir, "memory", "epics");
+  const storiesDir = path32.join(forgehiveDir, "memory", "stories");
   if (subcommand === "create") {
     const title = rest.filter((r) => !r.startsWith("--")).join(" ");
     const goalArg = rest.includes("--goal") ? rest[rest.indexOf("--goal") + 1] : void 0;
@@ -7373,7 +7568,7 @@ Setze diese Umgebungsvariablen:`);
       process.exit(1);
     }
     const epic = createEpic(epicsDir, title, goalArg);
-    console.log(`\u2714 ${epic.id} erstellt: ${path31.join(epicsDir, epic.id + ".md")}`);
+    console.log(`\u2714 ${epic.id} erstellt: ${path32.join(epicsDir, epic.id + ".md")}`);
   } else if (subcommand === "list") {
     const epics = listEpics(epicsDir);
     if (epics.length === 0) {
@@ -7399,7 +7594,7 @@ Setze diese Umgebungsvariablen:`);
     console.error("Verf\xFCgbar: fh epic create | list | show");
   }
 } else if (command === "velocity") {
-  const velocityFile = path31.join(forgehiveDir, "memory", "velocity.md");
+  const velocityFile = path32.join(forgehiveDir, "memory", "velocity.md");
   if (subcommand === "record") {
     const sprintNum = parseInt(rest[0] ?? "0", 10);
     const committed = rest.includes("--committed") ? parseInt(rest[rest.indexOf("--committed") + 1], 10) : NaN;
@@ -7417,9 +7612,100 @@ Setze diese Umgebungsvariablen:`);
   } else {
     console.error("Verf\xFCgbar: fh velocity show | record <N> --committed N --delivered N");
   }
+} else if (command === "docs") {
+  const docsDir = path32.join(projectRoot, "docs");
+  if (!subcommand || subcommand === "list") {
+    const existing = listExistingDocs(projectRoot);
+    if (existing.length === 0) {
+      console.log("Keine Dokumentation gefunden.");
+      console.log("");
+      console.log("Erstelle Docs:");
+      console.log("  fh docs user        \u2014 User Guide (docs/user-guide.md)");
+      console.log("  fh docs api         \u2014 API-Referenz (docs/api.md)");
+      console.log("  fh docs onboard     \u2014 Onboarding (ONBOARDING.md)");
+      console.log("  fh docs changelog   \u2014 Changelog (CHANGELOG.md)");
+      console.log("  fh docs adr <titel> \u2014 Architecture Decision Record");
+    } else {
+      console.log(`Vorhandene Dokumentation (${existing.length} Dateien):`);
+      for (const d of existing) console.log(`  ${path32.relative(projectRoot, d)}`);
+      console.log("");
+      console.log("Aktualisieren: fh docs user | api | onboard | changelog");
+    }
+  } else if (subcommand === "user") {
+    fs31.mkdirSync(docsDir, { recursive: true });
+    const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
+    const outputPath = outputArg ?? path32.join(docsDir, "user-guide.md");
+    const guide = generateUserGuide(projectRoot, forgehiveDir);
+    fs31.writeFileSync(outputPath, guide, "utf8");
+    console.log(`\u2714 User Guide geschrieben: ${outputPath}`);
+  } else if (subcommand === "api") {
+    fs31.mkdirSync(docsDir, { recursive: true });
+    const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
+    const outputPath = outputArg ?? path32.join(docsDir, "api.md");
+    const ref = generateApiReference(projectRoot);
+    fs31.writeFileSync(outputPath, ref, "utf8");
+    console.log(`\u2714 API-Referenz geschrieben: ${outputPath}`);
+  } else if (subcommand === "onboard") {
+    const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
+    const outputPath = outputArg ?? path32.join(projectRoot, "ONBOARDING.md");
+    const doc = generateOnboardingDoc(projectRoot, forgehiveDir);
+    fs31.writeFileSync(outputPath, doc, "utf8");
+    console.log(`\u2714 Onboarding-Dokument geschrieben: ${outputPath}`);
+  } else if (subcommand === "changelog") {
+    const sinceArg = rest.includes("--since") ? rest[rest.indexOf("--since") + 1] : null;
+    const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
+    const since = sinceArg ?? getLatestTag(projectRoot) ?? void 0;
+    const rawLog = getGitLogSince(projectRoot, since);
+    const commits = parseGitLog(rawLog);
+    let pkg = {};
+    try {
+      pkg = JSON.parse(fs31.readFileSync(path32.join(projectRoot, "package.json"), "utf8"));
+    } catch {
+    }
+    const version = pkg.version ?? "unreleased";
+    const md = formatChangelog(commits, version);
+    const outputPath = outputArg ?? path32.join(projectRoot, "CHANGELOG.md");
+    let existing = "";
+    if (fs31.existsSync(outputPath)) existing = fs31.readFileSync(outputPath, "utf8");
+    fs31.writeFileSync(outputPath, md + "\n\n" + existing, "utf8");
+    console.log(`\u2714 CHANGELOG.md aktualisiert (${commits.length} Commits)`);
+  } else if (subcommand === "adr") {
+    const title = rest.join(" ");
+    if (!title) {
+      console.error("Usage: fh docs adr <titel>");
+      process.exit(1);
+    }
+    const adrsDir = path32.join(forgehiveDir, "memory", "adrs");
+    fs31.mkdirSync(adrsDir, { recursive: true });
+    const existing = fs31.existsSync(adrsDir) ? fs31.readdirSync(adrsDir).filter((f) => f.endsWith(".md")).length : 0;
+    const adrId = String(existing + 1).padStart(4, "0");
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const filename = `${adrId}-${slug}.md`;
+    const content = `# ADR-${adrId}: ${title}
+
+**Datum:** ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
+**Status:** proposed
+
+## Kontext
+
+(Beschreibe das Problem oder die Situation.)
+
+## Entscheidung
+
+(Beschreibe die getroffene Entscheidung.)
+
+## Konsequenzen
+
+(Beschreibe die Auswirkungen dieser Entscheidung.)
+`;
+    fs31.writeFileSync(path32.join(adrsDir, filename), content, "utf8");
+    console.log(`\u2714 ADR erstellt: .forgehive/memory/adrs/${filename}`);
+  } else {
+    console.error("Verf\xFCgbar: fh docs [list|user|api|onboard|changelog|adr <titel>]");
+  }
 } else {
   console.error("Unbekannter Befehl: " + command);
-  console.error("Verf\xFCgbar: init | confirm | rollback | scan | status | ci | map | onboard | changelog | metrics | story [create|list|show|sprint|done] | epic [create|list|show] | velocity [show|record] | sync [push|pull] | run <issue-url> | cost | memory | skills | party | wire | mcp | security");
+  console.error("Verf\xFCgbar: init | confirm | rollback | scan | status | ci | map | onboard | changelog | metrics | docs | story [create|list|show|sprint|done] | epic [create|list|show] | velocity [show|record] | sync [push|pull] | run <issue-url> | cost | memory | skills | party | wire | mcp | security");
   console.error("Hilfe: fh --help");
   process.exit(1);
 }

package/forgehive/commands/fh-docs.md

@@ -2,6 +2,21 @@ You are Eli — Technical Writer. Your job is to write or update documentation.
 
 ## Documentation Protocol
 
+## Quick CLI Commands
+
+Before using Claude interactively, check if these CLI commands cover your need:
+
+```bash
+fh docs user         # generate user-facing guide → docs/user-guide.md
+fh docs api          # generate API reference → docs/api.md
+fh docs onboard      # generate onboarding doc → ONBOARDING.md
+fh docs changelog    # update CHANGELOG.md from git
+fh docs adr "<title>" # create Architecture Decision Record
+fh docs              # list all existing documentation
+```
+
+For interactive generation with editing, continue below.
+
 Ask the user: **"Was soll ich dokumentieren?"**
 
 Options:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgehive",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Context-aware AI development environment — one binary, your stack.",
   "type": "module",
   "bin": {