forgedock 1.0.22 → 1.1.2

package/README.md

@@ -4,336 +4,380 @@
 
 <h1>ForgeDock</h1>
 
-<p><strong>Autonomous software development for Claude Code.</strong></p>
+<p><strong>Deterministic orchestration for autonomous software engineering.</strong></p>
 
-<p>ForgeDock turns every bug found, every fix shipped, and every review finding into structured context that makes the next agent smarter. It catches integration bugs that code review can't see — missing route registrations, env vars present in CI but absent in deploy, Docker permission mismatches, sibling code paths left unfixed. Every finding feeds back as a prevention rule for future builds. After thousands of issues on production codebases, the system catches bugs before they reach a testing branch.</p>
+<p>LLMs generate the code. ForgeDock owns everything else — <strong>state, scheduling, recovery, review, and memory</strong> — as durable, inspectable structure on the GitHub you already have. Issues are the queue. PRs are the ledger. Annotations are the memory. Point it at an issue and get a merged, reviewed PR; point it at a <strong>milestone</strong> and get parallel pipelines with conflict-aware scheduling.</p>
+
+<a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0" /></a>
+<a href="https://github.com/RapierCraftStudios/ForgeDock/stargazers"><img src="https://img.shields.io/github/stars/RapierCraftStudios/ForgeDock?style=social" alt="GitHub Stars" /></a>
+<a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet" alt="Claude Code" /></a>
+<a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/v/forgedock?color=cb3837&logo=npm" alt="npm" /></a>
+<a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/dm/forgedock?color=cb3837&logo=npm&label=downloads" alt="npm downloads per month" /></a>
+<a href="https://github.com/RapierCraftStudios/ForgeDock/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" /></a>
+<a href="https://github.com/sponsors/RapierCraftStudios"><img src="https://img.shields.io/badge/Sponsor-❤-ea4aaa.svg" alt="Sponsor" /></a>
+
+</div>
 
-<a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/dm/forgedock?label=npm%20downloads&style=flat-square&color=CB3837" alt="npm downloads/month" /></a>&nbsp;
-<a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/v/forgedock?style=flat-square&color=CB3837" alt="npm version" /></a>&nbsp;
-<a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/forgedock?style=flat-square&color=339933" alt="node version" /></a>&nbsp;
-<a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Built%20for-Claude%20Code-7C3AED?style=flat-square" alt="Claude Code" /></a>
 <br />
-<a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="License: AGPL-3.0" /></a>&nbsp;
-<a href="https://github.com/RapierCraftStudios/ForgeDock/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome" /></a>
 
-<br /><br />
+<div align="center">
 
-<img src="docs/demo.gif" alt="ForgeDock demo — parallel orchestration across 15+ issues" width="900" />
+<img src="docs/demo.gif" alt="ForgeDock orchestrating multiple GitHub issues in parallel — agents investigate, build, review, and flip workflow labels through to merged" width="900" />
 
-<p><em>15+ issues orchestrated in parallel — investigated, built, reviewed, and shipped autonomously.</em></p>
+<p><em><strong>One <code>/orchestrate</code> runs a whole milestone.</strong> Agents pick up issues in parallel, drive each through investigate → build → review, and flip the GitHub labels to <code>merged</code> — live.</em></p>
 
 </div>
 
-<br />
+**This repository builds itself with ForgeDock.** In its first 30 days (June 4 → July 4, 2026): **693 issues filed, 605 closed, 603 PRs merged — median 56 minutes from open to merged-and-closed.** 57% of those issues were filed by the pipeline itself; 49% are findings its own review agents raised, filed, and then fixed. Every run leaves a public audit trail — [click through the receipts](#watch-the-machine-work), or count them yourself:
 
-## What ForgeDock Does
+```bash
+gh issue list -R RapierCraftStudios/ForgeDock --state closed --limit 1000 --json number --jq 'length'
+```
 
-ForgeDock runs the full issue lifecycle inside Claude Code — **investigate, architect, build, quality-gate, review, and merge** — autonomously. You open an issue, run `/work-on #42`, and click merge. Every stage writes structured context back to GitHub, so the next agent starts smart, not blind.
+**A single run, up close** — a real one, [issue #1230](https://github.com/RapierCraftStudios/ForgeDock/issues/1230):
 
+```console
+$ /work-on #1230        "orchestrate: Layer 5 co-change signal is dead code"
+
+  ✓ investigate    CONFIRMED/HIGH — feature shipped 3h earlier (PR #1204) reads a
+                   never-populated variable; the co-change query can never fire
+  ✓ build          fix branch, 1 file
+  ✓ review         caught a defect in the fix itself: stray backticks in the grep
+                   meant every git-log pathspec silently matched zero commits —
+                   "the fix would not have actually worked." Corrected.
+  ✓ merged         30m 37s → staging
+
+  filed by the pipeline's own staging review. fixed before a human read it.
 ```
-You:        /work-on #42
-ForgeDock:  Investigate → Architect → Build → Quality Gate → Review → open PR
-You:        click merge
+
+### Try it in 30 seconds — on a throwaway repo, nothing to lose
+
+```bash
+npx forgedock demo     # spins up a risk-free demo repo and shows you the pipeline end to end
 ```
 
-No new runtime, no separate process, no cloud service — just prompt-engineered command specs that run inside the Claude Code you already use.
+Ready to use it for real? **`npx forgedock`** walks you through one continuous setup: it checks your environment, installs the slash commands, reads your repo, and hands you a single annotated `forge.yaml` to review — you press Enter once.
+
+> ⭐ **If ForgeDock saves you time, [star the repo](https://github.com/RapierCraftStudios/ForgeDock/stargazers)** — it's the whole marketing budget.
 
 ---
 
-## What You Get
+**Your AI coding agent forgets everything after every session.** It re-explores the codebase from scratch, re-makes mistakes that were already fixed, and has no idea why the code it's touching looks the way it does. ForgeDock fixes that by making **GitHub itself the memory** — every pipeline stage writes structured findings that every later agent reads.
 
-| Capability | How it works |
-|---|---|
-| **Full-lifecycle automation** | `/work-on #42` — investigates the issue, architects a fix, builds it, runs quality gates, opens a PR, and reviews it. You click merge. |
-| **Persistent agent memory** | Structured `FORGE:` annotations on GitHub issues/PRs survive context resets and session boundaries. Agents never start blind. |
-| **9 specialist review agents** | Security, billing, database, concurrency, auth, frontend, API, performance, infrastructure — every PR gets domain-expert review. |
-| **Institutional memory that compounds** | Agent fixing issue #43 reads the investigation from #42 and applies the known pattern — no re-investigation. |
-| **Self-improving pipeline** | Review agents learn from past findings — recurring patterns automatically become new quality gate checks. |
-| **Parallel orchestration** | `/orchestrate` decomposes milestones into waves and runs `/work-on` on each in parallel. |
+## Without ForgeDock vs. With ForgeDock
 
-> **Cost note:** ForgeDock itself is free and open-source. It orchestrates Claude Code sessions, so you pay your normal Anthropic API usage. A typical `/work-on` run on a straightforward bug uses roughly the same tokens as a 15–20 minute manual Claude Code session.
+| Without ForgeDock | With ForgeDock |
+|---|---|
+| Agent starts every session blind — no context from prior work | Agent reads structured investigation, root cause, and history straight from GitHub |
+| The same bugs get reintroduced across PRs | Review agents surface known pitfalls from past PRs *before* you commit |
+| A crash or compaction loses the run | State lives on GitHub and in an event-sourced run log — the pipeline resumes where it stopped |
+| You write the issue, plan the fix, open the PR, and review it | `/work-on #42` → investigated, built, reviewed, merged |
+| Review depends on whoever has capacity | 9 domain-specialist agents (security, billing, DB, concurrency…) review every PR |
+| One task at a time, serialized by your attention | `/orchestrate` runs a whole milestone — many issues in parallel, each its own full pipeline |
 
 ---
 
-## How It Works
+## The idea in one paragraph
+
+AI agents have **no lookback**. They don't know a function was shaped by a bug fix in #347, that an approach was tried and reverted in PR #891, or that three other files need the same change. Context window isn't the bottleneck — **memory is.** But GitHub already stores everything an agent needs: commits, PRs, issues, blame, cross-references. It's a citation graph; agents just don't use it as one. ForgeDock makes every stage write **machine-readable annotations** to issues and PRs, and every downstream agent read them. The `gh` CLI becomes the query interface to institutional memory. The result: agents that follow structured data, not vibes.
 
 ```
-Issue → Investigate → Architect → Build → Quality Gate → Review → Merge
-              ↓            ↓         ↓          ↓            ↓
-        writes to     reads from  reads from  reads from   writes to
-         GitHub        GitHub      GitHub      GitHub       GitHub
+┌──────────────────────────────────────────────────────────────────┐
+│                     GITHUB (Knowledge Graph)                     │
+│                                                                  │
+│  Issues:  FORGE:INVESTIGATOR → FORGE:CONTEXT → FORGE:ARCHITECT   │
+│           → FORGE:TRAJECTORY (the run's full audit trail)        │
+│  PRs:     FORGE:BUILDER → structured review FINDING blocks       │
+│  Links:   git blame → commit → PR → issue → related issues       │
+│                                                                  │
+│  Every agent reads this. Every agent writes to it.               │
+│  Nothing is lost between conversations.                          │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
-Each stage writes a structured annotation (`<!-- FORGE:INVESTIGATOR -->`, `<!-- FORGE:CONTRACT -->`, etc.) to the GitHub issue or PR. Each downstream stage reads what came before. The `gh` CLI is the query interface.
-
-| Stage | What it does |
-|---|---|
-| **Investigate** | Traces root cause via `git blame`, related issues/PRs. Writes verdict, affected files, severity. |
-| **Context** | Surfaces historical bugs and known pitfalls from the same module. Institutional memory. |
-| **Architect** | Produces ordered implementation plan with exact file/function/line targets. |
-| **Build** | Writes code, creates branch, makes commits. Follows the architect's plan. |
-| **Quality Gate** | 14+ domain-specific checks (security, auth, DB, concurrency, etc.) |
-| **Review** | 9 specialist agents review the PR diff with confidence-rated findings. |
-| **Close** | Records full audit trail as `FORGE:TRAJECTORY`. |
-
-Labels track workflow state (`workflow:investigating`, `workflow:building`, `workflow:in-review`, `workflow:merged`). The pipeline resumes from whatever state GitHub says it's in — restart-safe by design.
-
 ---
 
-## Install
+## Watch the machine work
 
-**Requirements:** [Node.js 18+](https://nodejs.org/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [GitHub CLI (`gh`)](https://cli.github.com/), [`yq`](https://github.com/mikefarah/yq) (YAML parser used by pipeline commands to read `forge.yaml`), and **[Playwright MCP](https://github.com/microsoft/playwright-mcp)** (browser automation for `/qa-sweep` and visual testing commands)
+Not a staged demo — these are real, public runs on this repository. Open any of them and read the full trail:
 
-> **Playwright MCP** is a guaranteed ForgeDock dependency for browser automation commands. Register it in Claude Code after installing ForgeDock:
-> ```bash
-> claude mcp add playwright npx @playwright/mcp@latest
-> ```
-> Verify with `npx forgedock doctor` — Check 9 confirms Playwright MCP is registered.
+- **[#1230](https://github.com/RapierCraftStudios/ForgeDock/issues/1230)** — the pipeline's staging review caught dead code in a feature the pipeline had shipped three hours earlier; review then caught a bug in the fix itself. Intent to merged: **30 minutes**.
+- **[#1172](https://github.com/RapierCraftStudios/ForgeDock/issues/1172)** — review found an `ANTHROPIC_API_KEY` exfiltration path in the headless runner (an in-process file read bypassed the env scrub), with exact line evidence. Fixed and merged in **18 minutes**, with regression tests. A later re-review found a second-order bypass of the first fix ([#1243](https://github.com/RapierCraftStudios/ForgeDock/issues/1243)) — the pipeline red-teams its own fixes.
+- **[#952](https://github.com/RapierCraftStudios/ForgeDock/issues/952)** — the investigator closed the pipeline's *own proposal* as INVALID with receipts: the deliverable had already shipped weeks earlier. Zero code written, 34 minutes, full explanation.
+- **[#1256](https://github.com/RapierCraftStudios/ForgeDock/issues/1256)** — decomposition that respects the existing graph: it created only the two net-new sub-issues no open issue already claimed, then sequenced three existing issues into the dependency order.
+- **[#1322](https://github.com/RapierCraftStudios/ForgeDock/issues/1322)** — a heavyweight feature (the durable execution engine itself): 9 TDD tasks, whole-branch review caught two Criticals pre-merge, merged in **under 2 hours**.
 
-```bash
-# Install pipeline commands
-npx forgedock
+And the part that makes it compound — the context phase citing past bugs *by number* before a line is written (from [#1196](https://github.com/RapierCraftStudios/ForgeDock/issues/1196)):
 
-# Generate config for your repo
-npx forgedock init
+> "`commands/orchestrate.md` has a dense review-finding history from PR #1081/#1107/#1126… associative-array declaration mistakes (#1113), array-element removal via pattern substitution corrupting partial matches (#1108)… the new Layer 5 subsection should not introduce a competing edge-direction convention that could reintroduce a cycle class."
 
-# Verify everything is wired up correctly
-npx forgedock doctor
-```
+> Numbers on this page are point-in-time (2026-07-04), from this repository's first 30 days of dogfooding. A reproducible cost-per-issue benchmark is a hard gate on our own launch plan — [#1264](https://github.com/RapierCraftStudios/ForgeDock/issues/1264): no estimated efficiency claims.
+
+---
 
-This symlinks 25+ pipeline commands into `~/.claude/commands/` and generates a `forge.yaml` config in your project root. `npx forgedock doctor` runs an installation health check — command symlinks, `forge.yaml`, required tools (`gh`, `yq`, Claude Code), GitHub workflow labels, and Playwright MCP — printing a clear pass/fail/warn line with a fix hint for each, and exiting non-zero if anything is broken. Run it any time your setup feels off. That's it — open Claude Code and run `/work-on #42`.
+## Orchestrate an entire milestone
 
-**Try it risk-free:** Follow the [5-minute Getting Started walkthrough](docs/site/getting-started.md) to install, configure, and run your first pipeline end-to-end. New to the commands? Start with the [Command Reference](docs/site/command-reference.md) for a guided tour of what each one does.
+`/work-on` ships one issue. **`/orchestrate` ships a milestone.** It decomposes the milestone into dependency-ordered waves and runs a full `/work-on` pipeline on each issue **in parallel** — investigating, building, reviewing, and merging many at once, while GitHub labels track every agent's state live. On this repo's record day, that meant **29 issues taken to merged inside a single hour**.
 
-<details>
-<summary><strong>Other install methods & commands</strong></summary>
+Scheduling is conflict-aware before it is parallel. Five detection layers decide what may run concurrently: same-file overlap, directory proximity, shared-module fan-in, a conservative fallback when file extraction is low-confidence, and **historical co-change coupling mined from `git log`** — files that changed together in the past are assumed to conflict now. Database-touching issues are always serialized. The resulting graph is cycle-checked (Kahn's algorithm) and executed in topologically sorted waves; overlapping work is expressed as ordinary `Depends on #N` edges anyone can read.
 
-**Claude Code Plugin Marketplace** (v2.1.143+):
-```
-/plugin marketplace add RapierCraftStudios/ForgeDock
-/plugin install forgedock@forgedock
-```
+<div align="center">
+<img src="assets/orchestration.svg" alt="One milestone fanned out into parallel work-on pipelines, each issue advancing through investigating, building, in-review, and merged" width="920" />
+</div>
 
-**CLI commands:**
 ```bash
-npx forgedock update       # Pull latest commands
-npx forgedock uninstall    # Remove all ForgeDock commands from ~/.claude/commands/
-npx forgedock help         # Show all available commands
+/orchestrate milestone/checkout-v2     # decompose → conflict-aware waves → merged PRs
 ```
 
-**Standalone runner** (run pipelines outside Claude Code — CI/CD, headless batch):
-```bash
-# Preview the assembled prompt + tool plan (no API key needed)
-npx forgedock run work-on 42 --dry-run
+---
 
-# Execute headlessly via the Anthropic API directly
-export ANTHROPIC_API_KEY=sk-ant-...
-npm install @anthropic-ai/sdk        # optional dependency — only needed for live runs
-npx forgedock run work-on 42
-```
-`forgedock run` loads the same `commands/*.md` specs and drives an Anthropic
-tool-use loop directly, so the pipeline no longer depends on the Claude Code
-agent loop. Claude Code remains the recommended interactive experience; the
-runner adds CI/CD and non-Claude-Code paths. Flags: `--dry-run`, `--model <id>`,
-`--max-iterations <n>`.
+## How it works
+
+Each stage reads the structured output of the stages before it and writes its own findings back:
 
-**AI-powered setup** (inside Claude Code):
 ```
-/forgedock-init            # Guided config walkthrough — scans your repo, queries GitHub, auto-fills forge.yaml
+Issue → Investigate → Context → Architect → Build → Quality Gate → Review → Merge
+              └──────────── each stage reads & writes GitHub ────────────┘
 ```
 
-</details>
+| Stage | Reads | Writes |
+| --- | --- | --- |
+| **Investigate** | Issue body, `git blame`, related issues/PRs | `FORGE:INVESTIGATOR` — verdict, root cause, affected files, severity |
+| **Context** | Historical findings from related PRs, known pitfalls | `FORGE:CONTEXT` — institutional memory for this module |
+| **Architect** | Investigation + context | `FORGE:ARCHITECT` — ordered plan, code paths, risks |
+| **Build** | Everything above | `FORGE:BUILDER` — branch, commits, files changed |
+| **Quality Gate** | Builder output, domain-specific checks | gate results, recorded in the run's trajectory |
+| **Review** | PR diff, contract, gate results | `FORGE:REVIEW_STARTED` on the issue; per-agent findings as structured `FINDING` blocks on the PR |
+| **Close** | All of the above | `FORGE:TRAJECTORY` — the full audit trail of the run |
 
-<details>
-<summary><strong>See a real pipeline run</strong></summary>
-
-Here's what a real run looks like on [issue #619](https://github.com/RapierCraftStudios/ForgeDock/issues/619) — a performance bug where command specs were burning ~200K tokens in context:
-
-```
-FORGE:INVESTIGATOR  →  CONFIRMED. All 27 command spec files (848KB) load into
-                        context at session start via symlinks. ~200K tokens wasted.
-
-FORGE:CONTRACT      →  Replace symlink-based install with stub-file pattern.
-                        Installer parses frontmatter, writes minimal stubs.
+**GitHub as the database.** Every annotation is wrapped in an HTML comment (`<!-- FORGE:INVESTIGATOR -->`) that makes it machine-parseable. When an agent starts — even in a brand-new conversation after compaction — it queries the issue via `gh` and reconstructs full context from these tags. Workflow labels (`workflow:investigating`, `workflow:in-review`, `workflow:merged`…) track state, and the pipeline resumes from whatever state GitHub reports. The annotation format is an open standard — see the [FORGE Annotation Protocol](docs/spec/forge-protocol-v1.md).
 
-FORGE:CONTEXT       →  Issue #577: install() had overly broad catch{} — fixed to
-                        check err.code === 'ENOENT'. Issue #587: Windows writes
-                        regular files, not symlinks — keep both paths working.
+**Durable by design.** Headless runs are backed by a real execution engine, not prompt-hope: every phase transition is appended to an event-sourced, crash-safe run log, mirrored to the issue as a compact `FORGE:STATE` index, and guarded by leases so two agents can never own the same issue. Kill the process mid-run and restart it — the engine reconciles local state against GitHub (GitHub wins), adopts branches and PRs that already exist instead of re-running the LLM, and escalates to `needs-human` after bounded retries instead of looping. Phase selection is a pure rule-based state machine: **the engine, not the model, decides what happens next.** The headless core shipped in [PR #1326](https://github.com/RapierCraftStudios/ForgeDock/pull/1326); wiring the interactive path onto the same engine is in progress ([#1323](https://github.com/RapierCraftStudios/ForgeDock/issues/1323)–[#1325](https://github.com/RapierCraftStudios/ForgeDock/issues/1325)).
 
-FORGE:ARCHITECT     →  3 new functions in bin/forgedock.mjs: parseFrontmatter(),
-                        generateStubContent(), updated install() flow.
+**Domain-specialist review.** Every PR is reviewed by agents with deep, narrow expertise — Security, Auth & Access Control, Billing Integrity, Database, Concurrency, Frontend, API, Performance, Infrastructure. Findings carry a confidence level, and a **reproduction gate** keeps them honest: a finding only blocks if the reviewer traced an actual code path or input that triggers it — pattern-match suspicions are downgraded, not merged into noise. Findings above the severity threshold are **automatically filed as new issues** that enter the same pipeline: on this repo, that loop produced 49% of all issues ever filed.
 
-FORGE:BUILDER       →  Branch feat/stub-install-pattern-619, 1 file changed.
+**It measures itself.** `/pipeline-health` correlates every prompt change against review-finding rates, build failures, and manual fix-up commits, then files its own report — including failing grades — as an issue. `/autopilot` pulls production signals (errors, CI failures, stale issues, analytics), files issues from them, and optionally runs `/work-on` on the top ones. The pipeline also invalidates its own bad ideas: proposals that turn out to be already-shipped or wrong are closed `workflow:invalid` with the reasoning attached ([example](https://github.com/RapierCraftStudios/ForgeDock/issues/952)).
 
-FORGE:REVIEW        →  Auto-merged to staging.
+---
 
-FORGE:TRAJECTORY    →  Full audit trail recorded.
-```
+## Built for the ways agents fail
 
-The context phase surfaced two historical bugs (#577, #587) in the same module — preventing the builder from repeating known mistakes. [View the full issue →](https://github.com/RapierCraftStudios/ForgeDock/issues/619)
+Every mechanism above exists because autonomous agents fail in predictable ways. The skeptics are right about the failure modes — the answer is structure, not optimism:
 
-</details>
+| "We've all seen this go wrong…" | The mechanism |
+| --- | --- |
+| Parallel agents just turn typing time into *reading* time | Review is a pipeline stage: domain specialists with confidence ratings and a reproduction gate — not a pile of raw diffs |
+| Agents game their own checks (or delete the tests) | Builders never grade their own work — the quality gate and reviewers are separate agents reading the diff cold |
+| Third retry = increasingly creative excuses | Engine-owned state machine: bounded retries, then escalation to `needs-human` |
+| One runaway agent wrecks the codebase | 1 issue = 1 agent, bounded by decomposition; conflict-aware scheduling; isolated worktrees |
+| No institutional memory — "it can't read the Slack thread from 2023" | Every run writes citable annotations to GitHub; the context phase quotes past bugs by number |
+| No way to tell when an agent drifts | A `FORGE:TRAJECTORY` receipt on the issue records what every phase actually did |
+| Humans rubber-stamp 95%-good output | Specialist review raises the floor *before* a human looks at the PR |
+| The economics are opaque | ForgeDock runs on your existing Claude account — it resells no compute and takes no per-task cut. Cost-per-issue benchmarks are tracked in the open ([#1264](https://github.com/RapierCraftStudios/ForgeDock/issues/1264)) |
 
 ---
 
-## Where to Start
+## Commands
 
-ForgeDock installs 25+ commands, but **you only need three to start.** They cover the entire issue-to-merge loop:
+**The core loop:**
 
 | Command | What it does |
-|---|---|
-| `/issue` | Describe what you want — get a pipeline-ready issue |
-| **`/work-on #N`** | Investigate, build, review, and merge it automatically |
-| `/review-pr` | Review a PR with domain-specialist agents |
+| --- | --- |
+| **`/work-on`** | Full issue lifecycle: investigate → build → quality gate → review → merge |
+| `/orchestrate` | A whole milestone in parallel — conflict-aware waves, one pipeline per issue |
+| `/issue` | Creates pipeline-ready GitHub issues |
+| `/milestone` | Create, manage, and ship milestones |
+| `/review-pr` | Context-aware PR review with domain-specialist agents |
+| `/quality-gate` | Pre-commit checks, gated by the domains your change actually touches |
+| `/test-gate` | Acceptance verification against running code before anything deploys |
 
-Everything else is additive — add commands as your workflow grows: **Team Workflows** (`/orchestrate`, `/milestone`) when you run work in parallel, **Operations** (`/rollback`, `/incident-response`) when production needs it, and **Pipeline Tuning** (`/autopilot`, `/pipeline-health`) once it's routine. See the [Command Learning Path](docs/site/command-learning-path.md) for the full tiered guide.
+**Observe & recover** — the durable-state story, as commands:
 
----
+| Command | What it does |
+| --- | --- |
+| `/pipeline-status` | Fleet view of every in-flight issue, straight from workflow labels |
+| `/pipeline-resume` | Resume an interrupted run from whatever state GitHub reports |
+| `/diagnose` | Trace why a run failed, from its annotations |
+| `/explain` | Translate the FORGE annotations on any issue into plain language |
+| `/replay` | Replay a past run's full audit trail |
+| `/changelog` | Release notes assembled from merged PRs and trajectory receipts |
 
-## Commands
+**Ops:**
 
 | Command | What it does |
-|---|---|
-| **`/work-on #N`** | Full issue lifecycle: investigate → build → review → merge |
-| `/issue` | Create a pipeline-ready GitHub issue |
-| `/orchestrate` | Parallel execution across a milestone's issues |
-| `/review-pr` | PR review with 9 domain-specialist agents |
-| `/quality-gate` | Pre-commit checks across 14+ domains |
-| `/milestone` | Plan and ship milestones |
-| `/deploy-info` | Staging vs main diff with risk assessment |
-| `/review-pr-staging` | Staging-to-main review gate |
+| --- | --- |
+| `/deploy-info` | Staging vs. main diff with risk assessment |
 | `/rollback` | Automated revert PR for production incidents |
-| `/incident-response` | P0 coordination: hotfix, timeline, postmortem |
-| `/autopilot` | Autonomous improvement: recon → triage → fix |
-| `/pipeline-health` | Self-analysis and prompt tuning |
-| `/security-audit` | 4-phase security posture audit |
-| `/qa-sweep` | Full platform QA via browser automation |
-| `/analytics` | Pull metrics from GSC, Clarity, Umami, Stripe |
-| `/cleanup` | Sweep stale issues, branches, worktrees |
+| `/autopilot` | Production signals → triaged issues → fixes |
+| `/security-audit` | Multi-phase security posture audit |
+| `/cleanup` | Sweeps stale issues, branches, worktrees |
+
+More ship today (web-property analytics, browser QA sweeps, self-benchmarking) — see the [full command reference](docs/site/command-reference.md). A leaner, tiered install that keeps the core loop front and center is planned in [#1257](https://github.com/RapierCraftStudios/ForgeDock/issues/1257).
 
 ---
 
-## Global Command Namespace
+## Install
 
-ForgeDock owns the **global** `~/.claude/commands/` namespace. When `npx forgedock` runs, it symlinks all pipeline commands there and writes a `.symlink-source` sentinel file so other installers can detect the owner:
+**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
 
-```
-~/.claude/commands/
-  .symlink-source       ← sentinel: "ForgeDock owns this namespace"
-  work-on.md            → /path/to/forgedock/commands/work-on.md
-  review-pr.md          → /path/to/forgedock/commands/review-pr.md
-  ...
+```bash
+npx forgedock          # project-scoped install: checks your environment, installs commands for this repo, detects your repo, and hands you a reviewed forge.yaml
+npx forgedock --global # global install: installs into ~/.claude/commands/ — available in every Claude Code session on this machine
 ```
 
-**Project-specific commands** should install to the **project-local** `.claude/commands/` directory instead:
+**Project-scoped is the default.** `npx forgedock` installs commands scoped to the current project directory. Use `--global` only when you want the commands available across all your projects on this machine.
 
-```
-your-project/
-  .claude/
-    commands/
-      my-custom-command.md   ← project-local — Claude Code merges these in
-```
+One command does everything: it checks your environment, installs the slash commands into Claude Code, detects your repo (owner, branches, paths), and hands you a single annotated `forge.yaml` to review — press Enter to accept. Run `npx forgedock init` any time afterward to re-generate the config only.
 
-Claude Code merges global (`~/.claude/commands/`) and project-local (`.claude/commands/`) automatically. Project-local commands win on name collisions.
+Installing also registers a SessionStart hook, so every Claude Code session
+in a forge-managed directory starts already knowing ForgeDock runs it.
+Per-directory control: `npx forgedock enable` / `disable` / `status`.
 
-If another tool runs its own install script that targets `~/.claude/commands/`, it will silently repoint ForgeDock's symlinks to its own source path — breaking all ForgeDock commands globally. The `.symlink-source` sentinel is a machine-readable warning to other installers; ForgeDock also emits a per-command warning during `npx forgedock install` when it detects a collision.
+Then just open Claude Code and run `/work-on <issue>`.
 
----
+> **Cost:** ForgeDock is free and open-source. It orchestrates sessions on **your** Claude account — no compute resold, no per-task markup. A typical `/work-on` run on a straightforward bug costs about what a 15–20 minute manual Claude Code session does.
 
-## Why ForgeDock
+<details>
+<summary><strong>Other install options & commands</strong></summary>
 
-AI coding agents forget everything between sessions. They re-investigate the same bugs, miss context from past PRs, and make mistakes that were already caught and fixed last week. There's no institutional memory.
+**Claude Code plugin marketplace** (Claude Code v2.1.143+):
 
-ForgeDock fixes this by using **GitHub itself** as the memory layer. Every pipeline stage writes structured `FORGE:` annotations to issues and PRs. Every downstream agent reads them. When a new session starts — even after Claude's context resets — the agent queries GitHub and picks up exactly where the last one left off.
+```
+/plugin marketplace add RapierCraftStudios/ForgeDock
+/plugin install forgedock@forgedock
+```
 
----
+Commands then appear as `/forgedock:work-on`, etc. You still run `npx forgedock init` to generate `forge.yaml`.
+
+**Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan; with an `ANTHROPIC_API_KEY`, `npx forgedock run` drives the same command specs through a hardened tool-use loop, and `npx forgedock run-issue <issue>` executes them on the durable engine (event-sourced run log, leases, crash-safe resume).
 
-## How Is This Different
+**Install modes:**
 
-ForgeDock is **not another AI coding agent.** It's a set of prompt-engineered command specs (`.md` files) that run inside Claude Code. No new runtime, no separate process, no vendor lock-in beyond what you already use.
+```bash
+npx forgedock install           # project-scoped: <cwd>/.claude/commands/ (default)
+npx forgedock install --global  # global: ~/.claude/commands/ (opt-in)
+```
 
-| | ForgeDock | Plain Claude Code | Cursor / Windsurf | Devin / Sweep |
-|---|---|---|---|---|
-| Memory across sessions | Structured annotations on GitHub | CLAUDE.md + manual notes | Per-project context | Proprietary cloud state |
-| Autonomous pipeline | Full lifecycle: investigate → merge | Manual, step by step | Autocomplete + chat | Autonomous but opaque |
-| Review quality | 9 domain-specialist agents | You review everything | Basic suggestions | Varies |
-| Infrastructure needed | None — just `npx forgedock` | None | IDE-specific | Cloud service |
-| Codebase visibility | Everything stays on GitHub | Local | Local + cloud sync | Cloud-only |
+`uninstall`, `update`, and `doctor` auto-detect which mode is installed — no need to re-specify `--global` after a global install. To explicitly target global: `npx forgedock doctor --global`.
 
----
+**Maintenance:**
 
-## FAQ — How is ForgeDock different from X?
+```bash
+npx forgedock update      # relink commands + refresh the SessionStart hook
+npx forgedock enable      # turn ForgeDock on for this directory
+npx forgedock disable     # turn ForgeDock off for this directory
+npx forgedock status      # show ForgeDock's state for this directory
+npx forgedock doctor      # installation health check with fix hints (auto-detects mode)
+npx forgedock report      # 30-day pipeline impact receipts (--md for Markdown, --json for scripting)
+npx forgedock uninstall   # remove commands, the hook, and tracked copies (auto-detects mode)
+npx forgedock help        # show everything
+```
 
-**vs. DeepWiki (Devin)** — DeepWiki generates a read-only wiki from your codebase once. ForgeDock's FORGE annotations are written by pipeline agents during every issue run — capturing root causes, architectural decisions, and review findings as they happen, not as a snapshot of static code.
+> Running `npx forgedock` from *inside* this repo uses the local working tree. From your own project, use `npx forgedock@latest` to pin the published release.
 
-**vs. AGENTS.md / CLAUDE.md** — These files are written and maintained by you. They capture conventions and rules. ForgeDock annotations are written automatically by pipeline agents and capture execution history — what bugs were confirmed, what fixes were shipped, what review findings recurred. Use both: CLAUDE.md for conventions, ForgeDock for institutional memory.
+</details>
 
-**vs. Cursor Memories** — Cursor Memories are scoped to the Cursor IDE's backend and don't survive a Claude Code context reset. ForgeDock annotations live on GitHub — any agent, any tool, any human can read them. When Claude's context window compacts mid-session, a ForgeDock agent queries GitHub and resumes exactly where it left off.
+<details>
+<summary><strong>Migrating from a global install</strong></summary>
 
-**vs. Devin Knowledge Base** — Devin's KB is proprietary, opaque, and vendor-locked. ForgeDock context is plain GitHub issue comments — readable, editable, and queryable with `gh api`. No vendor lock-in, no black box.
+If you installed ForgeDock before project-scoped became the default, your commands live in `~/.claude/commands/`. You have two paths forward:
 
-[Full comparison →](docs/comparison.md)
+**Keep the global install** — add `--global` going forward and nothing changes:
 
----
+```bash
+npx forgedock --global   # install / update globally as before
+```
 
-## Uninstall
+**Switch to project-scoped** (recommended for multi-repo setups):
 
 ```bash
-npx forgedock uninstall
+# 1. Check your current install mode
+npx forgedock status
+
+# 2. Remove the global install
+npx forgedock uninstall --global
+
+# 3. Install project-scoped in each repo you use ForgeDock in
+cd /path/to/your/project
+npx forgedock
 ```
 
-Removes all ForgeDock command symlinks from `~/.claude/commands/`. Your `forge.yaml` config and any `FORGE:` annotations on GitHub issues/PRs are left untouched.
+Run `npx forgedock doctor` after switching to confirm everything is healthy.
+
+</details>
 
 ---
 
-## Documentation
+## For companies
+
+The core is AGPL-3.0 and stays that way: engineers run the full pipeline on their own Claude account, forever free.
 
-- [Try ForgeDock Risk-Free](examples/forgedock-demo/) — a tiny demo repo with 5 pre-written issues; clone, `npx forgedock`, `/work-on 1`, and watch a full pipeline run without touching your real code
-- [Getting Started in 5 Minutes](docs/site/getting-started.md) — install, configure, first pipeline run
-- [How the Knowledge Graph Works](docs/site/how-it-works.md) — FORGE annotations, context relay, compaction resilience
-- [What Are Those FORGE Comments?](docs/site/annotations-explained.md) — 2-minute newcomer explainer for the annotations on your issues
-- [ForgeDock vs. Manual Workflows](docs/site/vs-manual-workflows.md) — structured pipelines vs. ad-hoc prompting
-- [ForgeDock vs. DeepWiki, AGENTS.md, and Cursor Memories](docs/comparison.md) — structural differences between context tools
-- [FORGE Annotation Protocol](docs/site/forge-annotation-protocol.md) — open standard spec for AI context passing
-- [FORGE Annotation Protocol v1.0 (formal spec)](docs/spec/forge-protocol-v1.md) — standalone, versioned, CC-BY-4.0 specification you can implement in any agent pipeline
-- [Command Learning Path](docs/site/command-learning-path.md) — which commands to learn first, tiered by when you need them
-- [Command Reference](docs/site/command-reference.md) — all 25+ commands with usage and examples
-- [Troubleshooting & Recovery Guide](docs/site/troubleshooting.md) — symptom, cause, and fix for the most common pipeline failures
+Two things are for sale:
+
+- **A [commercial license](COMMERCIAL-LICENSE.md)** — for organizations that need ForgeDock inside proprietary workflows or products without AGPL copyleft obligations. Contact [support@rapiercraftstudios.com](mailto:support@rapiercraftstudios.com).
+- **The fleet layer** *(in development)* — org-wide observability over every pipeline run: the receipts on this page, live, across all your repos, plus policy controls and audit-grade provenance for autonomous merges. We're onboarding a small group of design partners — see [ForgeDock for Companies](docs/site/for-companies.md) for details and intake.
 
 ---
 
-## Star History
+## Where it's going
 
-<a href="https://star-history.com/#RapierCraftStudios/ForgeDock&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date" />
- </picture>
-</a>
+Month one built the execution layer. The open roadmap — tracked in the [five-foundations epic (#1320)](https://github.com/RapierCraftStudios/ForgeDock/issues/1320) — is about earning trust while unattended:
+
+1. **Durability** — engine-owned state instead of prose-owned state. Headless core shipped ([PR #1326](https://github.com/RapierCraftStudios/ForgeDock/pull/1326)); interactive wiring in progress.
+2. **Verification** — an outcome-based acceptance gate and a graded eval corpus, so "done" is machine-checkable before anything claims success. Per-release pipeline scorecards are published in [`docs/eval/`](docs/eval/README.md); model upgrades follow the [model-release playbook](docs/articles/model-release-playbook.md).
+3. **Learning** — per-codebase memory that compounds across runs.
+4. **Economics** — per-run cost accounting and risk×cost dispatch decisions.
+5. **Provenance** — signed, replayable records of every autonomous change.
+
+Marketing is held to the same standard: [#1264](https://github.com/RapierCraftStudios/ForgeDock/issues/1264) gates our own launch on measured cost-per-issue benchmarks — no estimated claims.
 
 ---
 
-## Contributing
+## Show your support
 
-PRs welcome. Every change goes through a PR, tested against 3+ scenarios, using conventional commits (`fix(command):`, `feat(command):`, `refactor(command):`).
+Using ForgeDock in your pipeline? Add the badge — each one is a backlink and a signal to other developers:
 
-## License
+```markdown
+[![Built with ForgeDock](https://raw.githubusercontent.com/RapierCraftStudios/ForgeDock/main/assets/built-with-forgedock.svg)](https://github.com/RapierCraftStudios/ForgeDock)
+```
+
+[![Built with ForgeDock](assets/built-with-forgedock.svg)](https://github.com/RapierCraftStudios/ForgeDock)
+
+---
 
-ForgeDock uses a **dual-licensing model**:
+## Star History
 
-- **[AGPL-3.0](LICENSE)** — free to use, modify, and distribute for open-source and personal use. If you modify ForgeDock and offer it as a service (including over a network), you must open-source your modifications under AGPL-3.0.
+<div align="center">
 
-- **[Commercial License](COMMERCIAL-LICENSE.md)** — for organizations that need to use ForgeDock in proprietary workflows or products without AGPL-3.0 copyleft obligations. [Contact RapierCraft Studios](mailto:licensing@rapiercraft.studio) to obtain a commercial license.
+<a href="https://star-history.com/#RapierCraftStudios/ForgeDock&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date&theme=dark" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date" width="600" />
+  </picture>
+</a>
 
-The open-source core remains free under AGPL-3.0. The commercial license is an exception for customers who cannot meet the copyleft requirements.
+</div>
 
 ---
 
-<div align="center">
+## Docs & community
 
-<p>Built by <a href="https://github.com/RapierCraftStudios">RapierCraft Studios</a></p>
+- [GitHub Is Already Your Agents' Memory](docs/site/github-is-the-memory.md) — the canonical argument: why GitHub is the right place for agent memory, how FORGE annotations make it machine-readable, and how to adopt the protocol without ForgeDock
+- [Getting Started in 5 Minutes](docs/site/getting-started.md)
+- [How the Knowledge Graph Works](docs/site/how-it-works.md)
+- [What Are Those FORGE Comments?](docs/site/annotations-explained.md) — 2-minute explainer for annotations you meet in the wild
+- [FORGE Annotation Protocol](docs/spec/forge-protocol-v1.md) — the open standard for AI context passing (CC-BY-4.0)
+- [ForgeDock vs. Manual Claude Code Workflows](docs/site/vs-manual-workflows.md)
+- [ForgeDock vs. DeepWiki, AGENTS.md, and Cursor Memories](docs/comparison.md)
+- [Command Learning Path](docs/site/command-learning-path.md) — which commands to learn first
+- [Complete Command Reference](docs/site/command-reference.md)
+- [Troubleshooting & Recovery](docs/site/troubleshooting.md)
+- [Pipeline Eval Scorecards](docs/eval/README.md) — per-release published results for every model/Claude Code upgrade
+- [Model-Release Upgrade Playbook](docs/articles/model-release-playbook.md) — how to validate a new model before adopting it
 
-<a href="https://github.com/sponsors/RapierCraftStudios"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa.svg?style=flat-square" alt="Sponsor" /></a>
+**Contributing:** PRs welcome — every change goes through a PR, tested against 3+ scenarios, using conventional commits (`fix(command):`, `feat(command):`). **License:** [AGPL-3.0](LICENSE) — free to use, modify, and distribute; network use of modifications must be open-sourced under the same license. Commercial licenses are available for proprietary use — see [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md).
 
+<div align="center">
+<br />
+<p>Built and dogfooded in production by <a href="https://github.com/RapierCraftStudios">RapierCraft Studios</a>.</p>
 </div>