forgehive 0.7.1 → 0.7.3

package/README.md

@@ -14,8 +14,8 @@
 <p align="center">
   <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-217%20passing-success" alt="217 tests">
-  <img src="https://img.shields.io/badge/bundle-205KB-lightgrey" alt="205KB bundle">
+  <img src="https://img.shields.io/badge/tests-267%20passing-success" alt="267 tests">
+  <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>
 
@@ -31,18 +31,23 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 
 - **Stack Scanner** — detects tech stack, dependencies, and project structure automatically
 - **Persistent Memory** — context and session notes survive every restart
+- **Story & Epic Tracking** — lightweight agile backlog inside `.forgehive/memory/`
+- **Velocity Tracking** — sprint velocity history, rolling average, and capacity hints
 - **Party Mode** — specialized agent sets, each agent in its own isolated git worktree
 - **MCP Wiring** — preconfigured connectors for 10 services, API keys stored securely in `~/.forgehive/`
 - **Security Suite** — SAST, secret scanner, CVE check, CISO reports (GDPR/SOC2/HIPAA)
+- **CI Integration** — CI health report and GitHub Actions template generator
+- **Codebase Map** — file/line/import table for navigation and onboarding
+- **Team Sync** — share memory across the team via a dedicated git branch
 - **AGENTS.md** — cross-tool standard (Cursor, Copilot, Gemini CLI, Codex, Windsurf)
 
 **Design principle:** writes exclusively to `.forgehive/` in the target project. No globbing outside the project root. Never overwrites files it didn't create.
 
 ---
 
-## Status: Early Alpha (v0.6)
+## Status: v0.7 — Stable
 
-This is an early release. The codebase is clean — TypeScript, 217 passing tests, single bundle — but several features have not yet been tested against a real project.
+267 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
 
 **Stable — use with confidence:**
 
@@ -56,6 +61,16 @@ This is an early release. The codebase is clean — TypeScript, 217 passing test
 | `fh security report` — compliance reports | stable |
 | `fh memory` — show, clean, export, snapshot | stable |
 | MCP credential store (`fh mcp auth`) | stable |
+| `fh ci` — CI health report + GitHub Actions template | stable |
+| `fh map` — codebase structure map | stable |
+| `fh onboard` — generates ONBOARDING.md | stable |
+| `fh changelog` — semantic changelog from git | stable |
+| `fh metrics` — developer metrics by author/type | stable |
+| `fh sync` — team memory sharing via git branch | stable |
+| `fh run` — background agent execution via `claude -p` | stable |
+| `fh story` — story card create/list/show/done | stable |
+| `fh epic` — epic create/list/show | stable |
+| `fh velocity` — show history + record sprint data | stable |
 
 **Experimental — works in tests, not yet live-validated:**
 
@@ -74,7 +89,7 @@ If you run into issues, please open an issue on GitHub. The most valuable feedba
 
 - **Node.js ≥ 18** — check with `node --version`
 - **Claude Code** installed and configured (`claude` CLI available)
-- **git** — required for Party Mode worktrees and the guardrails hook
+- **git** — required for Party Mode worktrees, `fh sync`, and the guardrails hook
 
 ---
 
@@ -94,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 (~205 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.6.0
+fh --version       # should print 0.7.2
 fh --help          # lists all available commands
 ```
 
@@ -151,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/`.
 
 ---
@@ -264,6 +283,91 @@ Shows `permissions.yaml` — the file access control list for each agent. Each a
 
 ---
 
+### CI
+
+```bash
+fh ci                          # run CI health report (text output)
+fh ci --format json            # output report as JSON
+fh ci --format markdown        # output report as Markdown
+fh ci --fail-on critical       # exit 1 only on CRITICAL findings
+fh ci --fail-on high           # exit 1 on HIGH or CRITICAL
+fh ci --fail-on any            # exit 1 on any finding
+fh ci --init                   # generate a GitHub Actions workflow template
+```
+
+`fh ci` aggregates security scan, dependency audit, and test results into a single CI health report. Use `--init` to scaffold a `.github/workflows/forgehive.yml` file that runs the full check on every pull request. The `--fail-on` flag controls which severity level causes a non-zero exit code, giving you fine-grained control over what blocks a merge.
+
+---
+
+### Codebase Map
+
+```bash
+fh map
+```
+
+Prints a structured table of your codebase: file paths, line counts, and import relationships. Useful for onboarding a new engineer (or a new Claude session) to an unfamiliar codebase. Output goes to stdout; pipe it to a file if you want to save it.
+
+---
+
+### Onboarding
+
+```bash
+fh onboard                     # generate ONBOARDING.md (stdout)
+fh onboard --output ./ONBOARDING.md   # write to file
+```
+
+Generates a human-readable `ONBOARDING.md` from three sources: the detected stack in `capabilities.yaml`, the persistent memory in `.forgehive/memory/`, and the recent git log. The result is a self-contained document a new team member can read to understand the project architecture, conventions, and current state.
+
+---
+
+### Changelog
+
+```bash
+fh changelog                        # full changelog from all commits
+fh changelog --since v0.6.0         # changes since a specific tag
+fh changelog --output CHANGELOG.md  # write to file
+```
+
+Parses conventional commits (`feat:`, `fix:`, `chore:`, `docs:`, etc.) and groups them into a semantic changelog. Breaking changes are surfaced separately. Requires conventional commit messages — standard for projects that use `fh git-conventions`.
+
+---
+
+### Developer Metrics
+
+```bash
+fh metrics                          # all-time developer metrics
+fh metrics --since 2025-01-01       # metrics since a date
+```
+
+Shows commit activity broken down by author and commit type (feat, fix, chore, docs, test, refactor). Also shows rolling statistics: commit frequency, most active contributors, and type distribution. Useful for retrospectives and identifying contribution patterns.
+
+---
+
+### Team Memory Sync
+
+```bash
+fh sync push                                           # push memory to default remote/branch
+fh sync push --remote origin --branch forgehive-memory  # push to a specific remote branch
+fh sync pull                                           # pull memory from remote
+fh sync pull --remote origin --branch forgehive-memory  # pull from specific branch
+```
+
+`fh sync` shares `.forgehive/memory/` across the team by pushing to (or pulling from) a dedicated git branch. This is an alternative to committing the memory directory into the main branch. On `pull`, existing local files are not overwritten — only new files are added, the same idempotent behavior as `fh memory snapshot import`.
+
+---
+
+### Background Agent Execution
+
+```bash
+fh run <issue-url>                         # run agent on a GitHub/Linear issue URL
+fh run <issue-url> --agent kai             # use a specific agent
+fh run <issue-url> --label ready-for-ai   # filter by label
+```
+
+`fh run` launches a background agent via `claude -p`, passes the issue content as context, and returns immediately. The agent reads the issue, applies forgehive context from `.forgehive/`, and works on the task in the background. Useful for automating repetitive issues or running agents overnight. Agent output is streamed to stdout and also written to `.forgehive/runs/`.
+
+---
+
 ### Memory
 
 Memory files live in `.forgehive/memory/` and are read by Claude at session start via the CLAUDE.md block.
@@ -297,6 +401,56 @@ Memory files live in `.forgehive/memory/` and are read by Claude at session star
 
 ---
 
+### Story Cards
+
+Story cards are lightweight user stories stored in `.forgehive/memory/stories/`. They integrate with `/fh-sprint` for velocity-based sprint planning.
+
+```bash
+fh story create "As a user I want to log in"            # create a story (auto-numbered US-N)
+fh story create "As a user I want to log in" --epic EPC-1 --points 3   # with epic + points
+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` | `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.
+
+---
+
+### Epics
+
+Epics group related stories and are stored in `.forgehive/memory/epics/`.
+
+```bash
+fh epic create "User Authentication"                              # create an epic (auto-numbered EPC-N)
+fh epic create "User Authentication" --goal "Users can log in securely"  # with a goal statement
+fh epic list                                                       # list all epics
+fh epic show EPC-1                                                 # show epic with linked stories and point total
+```
+
+Each epic card is a Markdown file at `.forgehive/memory/epics/EPC-N.md`. `fh epic show` aggregates all stories linked to the epic and displays their status and point totals.
+
+---
+
+### Velocity
+
+```bash
+fh velocity show                                              # velocity history + rolling average + recommendation
+fh velocity record sprint-3 --committed 21 --delivered 18    # record sprint data
+```
+
+`fh velocity show` reads the velocity history from `.forgehive/memory/velocity.md` and prints:
+- A table of past sprints (committed vs. delivered points)
+- A rolling average (last 3 sprints)
+- A capacity recommendation for the next sprint
+
+`fh velocity record` appends a new entry to the velocity history. The `/fh-sprint` slash command reads this data automatically and uses it to calibrate the sprint scope it suggests.
+
+---
+
 ### Party Mode
 
 Party Mode runs specialized agent sets in parallel, each in an isolated git worktree.
@@ -320,7 +474,7 @@ fh party cleanup            # remove finished worktrees
 | `security` | Vera + Sam | `/security-party` |
 | `full` | All 8 agents | `/full-party` |
 
-**Model mapping** — assign specific Claude models per agent:
+**Multi-model routing** — `defaults.yaml` supports a `models:` key per agent set. Override via CLI:
 
 ```bash
 fh party --model-map "viktor:claude-opus-4-7,kai:claude-sonnet-4-6,sam:claude-haiku-4-5"
@@ -417,33 +571,57 @@ Clones the repo with `--depth=1`, copies all `.md` files from the `skills/expert
 
 ---
 
+### Slash Commands
+
+The following slash commands are available inside Claude Code sessions:
+
+| Command | Description |
+|---|---|
+| `/fh-sprint` | Sprint planning — reads backlog, velocity, and capacity; suggests scope using Fibonacci points (1/2/3/5/8/13); records velocity at end of sprint |
+| `/fh-deploy` | Pre-deploy checklist — security scan, dependency audit, test run, final confirmation |
+| `/fh-test-this` | Generate tests for the current file or selection — uses `testing-strategies` skill |
+| `/fh-docs` | Generate documentation for the current file or module |
+| `/party` | Start the `build` party (Viktor + Kai + Sam) |
+| `/design-party` | Start the `design` party (Suki + Viktor) |
+| `/review-party` | Start the `review` party (Kai + Sam + Eli) |
+| `/security-party` | Start the `security` party (Vera + Sam) |
+| `/full-party` | Start all 8 agents |
+
+**`/fh-sprint` in detail:** Reads `.forgehive/memory/stories/` for backlog items, `.forgehive/memory/velocity.md` for historical capacity, and `.forgehive/memory/epics/` for epic context. Suggests a sprint scope as a list of story cards with Fibonacci point estimates. When you close the sprint, it prompts you to record delivered points so velocity history stays up to date. If Linear or GitHub MCP servers are connected, it can pull issues directly from those services.
+
+---
+
 ## What `fh init` Creates
 
 ```
 my-project/
   .forgehive/
-    capabilities.yaml          ← detected stack (status: draft → confirmed)
-    scan-result.yaml           ← raw scanner output
-    .scan-hash                 ← checksum for fh scan --check
+    capabilities.yaml          <- detected stack (status: draft -> confirmed)
+    scan-result.yaml           <- raw scanner output
+    .scan-hash                 <- checksum for fh scan --check
     harness/
-      architecture.md          ← codebase overview for Claude
-      constraints.yaml         ← max_lines, require_tests, style rules
-      permissions.yaml         ← per-agent file access control (read/write/deny)
+      architecture.md          <- codebase overview for Claude
+      constraints.yaml         <- max_lines, require_tests, style rules
+      permissions.yaml         <- per-agent file access control (read/write/deny)
     memory/
-      MEMORY.md                ← index of all memory files
-      project.md               ← project context and open decisions
-      feedback.md              ← corrections + confirmed approaches
-      stack.md                 ← stack details the scanner can't detect
-      adrs/                    ← architecture decision records
+      MEMORY.md                <- index of all memory files
+      project.md               <- project context and open decisions
+      feedback.md              <- corrections + confirmed approaches
+      stack.md                 <- stack details the scanner can't detect
+      adrs/                    <- architecture decision records
+      stories/                 <- story cards (US-N.md)
+      epics/                   <- epic cards (EPC-N.md)
+      velocity.md              <- sprint velocity history
     skills/
-      generated/               ← AI-generated skills (fh skills regen)
-      expert/                  ← 16 preinstalled expert skills
-      workflows/               ← MCP workflow skills
-    worktrees/                 ← isolated git worktrees (fh party run)
-    audit.log                  ← JSONL audit trail (fh security commands)
-    cost-config.yaml           ← spend limits (fh cost --limit/--alert)
-  AGENTS.md                    ← cross-tool agent standard
-  CLAUDE.md                    ← forgehive block inserted, rest preserved
+      generated/               <- AI-generated skills (fh skills regen)
+      expert/                  <- 16 preinstalled expert skills
+      workflows/               <- MCP workflow skills
+    worktrees/                 <- isolated git worktrees (fh party run)
+    runs/                      <- background agent output (fh run)
+    audit.log                  <- JSONL audit trail (fh security commands)
+    cost-config.yaml           <- spend limits (fh cost --limit/--alert)
+  AGENTS.md                    <- cross-tool agent standard
+  CLAUDE.md                    <- forgehive block inserted, rest preserved
 ```
 
 ---
@@ -520,7 +698,7 @@ The hook fires on every bash command execution in Claude Code and exits 1 if a m
 cd my-project
 fh init
 fh confirm
-# Open Claude Code → Claude now has full context
+# Open Claude Code -> Claude now has full context
 ```
 
 ### After adding new dependencies
@@ -539,6 +717,49 @@ fh security deps            # check for new CVEs in dependencies
 fh security report gdpr     # update compliance report
 ```
 
+### CI integration
+
+```bash
+fh ci --init                  # scaffold .github/workflows/forgehive.yml
+fh ci --format markdown --fail-on high   # use in existing CI scripts
+```
+
+### Generating onboarding documentation
+
+```bash
+fh map                        # review codebase structure
+fh onboard --output ONBOARDING.md   # generate onboarding document
+git add ONBOARDING.md
+git commit -m "docs: add forgehive-generated onboarding"
+```
+
+### Generating a changelog
+
+```bash
+fh changelog --since v0.6.0 --output CHANGELOG.md
+```
+
+### Sprint planning
+
+```bash
+# Set up your backlog
+fh epic create "User Authentication" --goal "Users can log in securely"
+fh story create "As a user I want to log in" --epic EPC-1 --points 3
+fh story create "As a user I want to reset my password" --epic EPC-1 --points 2
+
+# Check current velocity
+fh velocity show
+
+# Open Claude Code and run:
+# /fh-sprint
+# Claude reads velocity + backlog and suggests scope
+
+# At end of sprint
+fh velocity record sprint-1 --committed 13 --delivered 11
+fh story done US-1
+fh story done US-2
+```
+
 ### Sharing context with the team
 
 ```bash
@@ -548,6 +769,11 @@ git commit -m "chore: update shared forgehive context"
 
 # On another machine:
 fh memory snapshot import ./team-context.json
+
+# Or use the sync approach (no committed file):
+fh sync push --remote origin --branch forgehive-memory
+# teammate runs:
+fh sync pull --remote origin --branch forgehive-memory
 ```
 
 ### Starting a multi-agent build session
@@ -555,8 +781,8 @@ fh memory snapshot import ./team-context.json
 ```bash
 fh party --set build
 fh party run
-# → Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
-# → Each Claude Code session opens in its own isolated worktree
+# -> Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
+# -> Each Claude Code session opens in its own isolated worktree
 
 fh party status     # check what's running
 fh party cleanup    # clean up after the session
@@ -575,6 +801,14 @@ fh mcp auth add github GITHUB_TOKEN=ghp_...
 fh mcp auth list    # verify both services are stored
 ```
 
+### Running a background agent on an issue
+
+```bash
+fh run https://github.com/my-org/my-repo/issues/42 --agent kai
+# Kai reads the issue, applies forgehive context, works in background
+# Output streamed to stdout and saved to .forgehive/runs/
+```
+
 ---
 
 ## Configuration Files
@@ -613,13 +847,13 @@ Global credential store (chmod 600). Managed exclusively via `fh mcp auth` comma
 |---|---|
 | Runtime | Node.js ≥ 18, ESM |
 | Language | TypeScript |
-| Build | esbuild → `dist/cli.js` (~205 KB, single bundle) |
+| Build | esbuild -> `dist/cli.js` (~247 KB, single bundle) |
 | Type check | `tsc --noEmit` |
-| Tests | `node:test` (native) + tsx ESM loader, 217 tests |
+| Tests | `node:test` (native) + tsx ESM loader, 267 tests |
 | Dependencies | `js-yaml` (sole runtime dependency) |
 
 ```bash
-npm run build       # esbuild → dist/cli.js
+npm run build       # esbuild -> dist/cli.js
 npm run typecheck   # tsc --noEmit
 npm test            # node --import tsx/esm --test test/*.test.ts
 ```

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,26 +6454,296 @@ 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.1");
+  console.log("0.7.3");
+  process.exit(0);
+}
+if (command === "--help" || command === "-h" || command === "help") {
+  console.log(`
+forgehive v0.7.3 \u2014 Context-aware AI development environment
+
+USAGE
+  fh <command> [subcommand] [options]
+
+SETUP
+  fh init                          Set up forgehive in the current project
+  fh confirm                       Activate capabilities (draft \u2192 confirmed)
+  fh rollback                      Remove forgehive from the project
+  fh status                        Show current project state
+  fh scan --update                 Re-scan project after changes
+  fh scan --check                  Check if scan is still current
+
+SECURITY
+  fh security scan                 Secrets + SAST scan
+  fh security deps                 CVE check (npm audit)
+  fh security report [gdpr|soc2|hipaa]  Compliance report
+  fh security audit                Show audit trail
+  fh security permissions          Show agent file permissions
+
+CI
+  fh ci                            Run CI health report
+  fh ci --format json|markdown     Output format
+  fh ci --fail-on critical|high|any  Failure threshold
+  fh ci --init                     Generate GitHub Actions workflow
+
+CODEBASE
+  fh map                           Codebase structure map
+  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]
+  fh story list [--epic EPC-N]
+  fh story show <US-N>
+  fh story sprint <US-N>           Mark story as in-sprint
+  fh story done <US-N> [--points N]
+  fh epic create <title> [--goal <text>]
+  fh epic list
+  fh epic show <EPC-N>
+  fh velocity show                 Velocity history + rolling average
+  fh velocity record <N> --committed N --delivered N
+
+TEAM
+  fh sync push|pull [--remote origin --branch forgehive-memory]
+  fh run <issue-url> [--agent name] [--label label]
+  fh memory show|clean|export|prune|snapshot
+  fh memory adr list|"<title>"
+
+AGENTS & MCP
+  fh party [--set name|run|status|cleanup]
+  fh wire <service>                Configure MCP server
+  fh mcp auth add|list|remove      Manage credentials
+  fh mcp search <query>            Search MCP registry
+  fh skills list|regen|pull <url>
+
+COST
+  fh cost [today|week|all]
+  fh cost --limit N --alert N
+
+  fh --version                     Show version
+  fh --help                        Show this help
+`);
   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 = 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).`);
+    console.log(`  Nutze 'fh scan --update' um nur den Scan zu aktualisieren.`);
+    process.exit(0);
+  }
   console.log("\u{1F50D} Analysiere Projekt...\n");
   const scanResult = scan(projectRoot);
   const tierCount = [1, 2, 3].map((t) => scanResult.signals.filter((s) => s.tier === t).length);
@@ -6485,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"
   );
@@ -6519,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);
   }
@@ -6528,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) {
@@ -6576,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`
       );
@@ -6616,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");
@@ -6628,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);
@@ -6648,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.");
@@ -6666,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);
   }
@@ -6702,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);
   }
@@ -6823,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);
   }
@@ -6862,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);
     }
@@ -6888,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);
   }
@@ -6911,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);
   }
@@ -7022,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);
   }
@@ -7108,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}`);
@@ -7121,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");
@@ -7134,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;
@@ -7172,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}`);
@@ -7228,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;
@@ -7239,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;
@@ -7264,6 +7534,14 @@ Setze diese Umgebungsvariablen:`);
     if (pointsArg) updateStoryPoints(storiesDir, id, pointsArg);
     updateStoryStatus(storiesDir, id, "done");
     console.log(`\u2714 ${id} als done markiert`);
+  } else if (subcommand === "sprint") {
+    const id = rest[0];
+    if (!id) {
+      console.error("Usage: fh story sprint <US-N>");
+      process.exit(1);
+    }
+    updateStoryStatus(storiesDir, id, "in-sprint");
+    console.log(`\u2714 ${id} in Sprint gezogen`);
   } else if (subcommand === "show") {
     const id = rest[0];
     if (!id) {
@@ -7280,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;
@@ -7290,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) {
@@ -7316,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;
@@ -7328,14 +7606,107 @@ Setze diese Umgebungsvariablen:`);
     recordVelocity(velocityFile, sprintNum, committed, delivered);
     const avg = getRollingAverage(getVelocityHistory(velocityFile));
     console.log(`\u2714 Sprint ${sprintNum} gespeichert. Rolling Average: ${avg} Punkte`);
-  } else {
+  } else if (!subcommand || subcommand === "show") {
     const history = getVelocityHistory(velocityFile);
     console.log(formatVelocityReport(history));
+  } 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 {
-  const cmd = [command, subcommand].filter(Boolean).join(" ") || "(kein)";
-  console.error(`Unbekannter Befehl: ${cmd}`);
-  console.error("Verf\xFCgbar: init | confirm | rollback | scan --update | scan --check | status | ci [--format json|markdown] [--fail-on critical|high|any] [--init] | map | onboard [--output path] | changelog [--since tag] | metrics [--since date] | sync [push|pull] [--remote origin --branch forgehive-memory] | run <issue-url> [--agent <name>] | cost [today|week|all] | cost --limit N --alert N | memory [show|clean|export|prune|snapshot] | memory adr [list|<titel>] | skills [list|regen|pull <url>] | party [--set <name>|run|status|cleanup] | wire <service> | mcp [auth|search|add] | security [scan|deps|report|audit|permissions]");
+  console.error("Unbekannter Befehl: " + command);
+  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);
 }
 /*! Bundled license information:

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.1",
+  "version": "0.7.3",
   "description": "Context-aware AI development environment — one binary, your stack.",
   "type": "module",
   "bin": {