forgedock 1.0.22 → 1.1.2

package/docs/site/for-companies.md

@@ -0,0 +1,95 @@
+---
+title: "ForgeDock for Companies"
+description: "Commercial licensing, the fleet layer, design-partner program, and procurement facts for organizations evaluating ForgeDock."
+keywords: ["forgedock enterprise", "forgedock commercial license", "forgedock fleet layer", "design partner", "agpl commercial"]
+---
+
+# ForgeDock for Companies
+
+ForgeDock's open-source core — the pipeline commands, CLI installer, and all code in this repository — is licensed under AGPL-3.0 and stays that way. Engineers run the full pipeline on their own Claude account, forever free.
+
+This page answers the questions that come up when an organization considers ForgeDock for team-wide or production use.
+
+---
+
+## AGPL-3.0 vs. Commercial License
+
+The AGPL-3.0 license is broad but has one specific trigger: **network-use copyleft**. If you run a modified version of ForgeDock as a service that others access over a network, the AGPL requires you to publish your modifications under the same license.
+
+Use this table to determine which license you need:
+
+| Scenario | License needed |
+|----------|---------------|
+| Individual engineer running ForgeDock on their own repos | **AGPL-3.0 — free** |
+| Team running ForgeDock internally, no external users, comfortable with AGPL | **AGPL-3.0 — free** |
+| Organization contributing modifications back under AGPL-3.0 | **AGPL-3.0 — free** |
+| Organization integrating ForgeDock into a proprietary internal tool and cannot open-source the integration | **Commercial license required** |
+| Building a SaaS or hosted product on top of ForgeDock and cannot release derivative source | **Commercial license required** |
+| Organization whose legal policy prohibits AGPL-licensed software in certain contexts | **Commercial license required** |
+| Want enterprise terms: support SLA, indemnification, or audit rights | **Commercial license required** |
+
+Key clarification: ForgeDock is a **development tool**, not a library embedded in your product. Simply using ForgeDock to build and ship your own software does not trigger the copyleft clause — the clause applies when you modify ForgeDock itself and offer it as a service to others.
+
+For the full license text, see [`LICENSE`](../../LICENSE) (AGPL-3.0) and [`COMMERCIAL-LICENSE.md`](../../COMMERCIAL-LICENSE.md).
+
+---
+
+## The Fleet Layer *(in development)*
+
+The open-source pipeline runs one repo at a time, driven by individual engineers. The fleet layer extends this to the organization level. It is built on the same `FORGE:STATE` and `FORGE:TRAJECTORY` annotation data that the open-source pipeline already writes.
+
+**What the fleet layer includes:**
+
+- **Org-wide run observability** — a single view across all repos showing every pipeline run, its phase, and its outcome. The same structured annotation data you can already query with `gh` today, surfaced in one place.
+- **Policy controls** — configure which issue labels, branches, or repositories require human approval before the pipeline merges a PR.
+- **Audit-grade provenance** — a signed, queryable record of every autonomous change: what ran, on which issue, from which commit, and whether a human reviewed it.
+
+**Availability status**: The fleet layer is in active development in a private repository. It is **not yet shipped**. No production customers are running it. The design-partner program (below) is how we onboard the first organizations.
+
+---
+
+## Design-Partner Program
+
+We are onboarding a small group of organizations as design partners for the fleet layer. Design partners get:
+
+- **Early access** to the fleet layer as it ships, starting with read-only observability
+- **Direct roadmap influence** — your org's use cases shape the policy controls and audit features
+- **Favorable commercial terms** locked in before general availability
+
+Design partnership is appropriate for organizations that are already running ForgeDock in production (or want to start) and have a concrete need for org-level visibility or governance over autonomous merges.
+
+**To apply**: [Open a design-partner intake request](https://github.com/RapierCraftStudios/ForgeDock/issues/new?template=design-partner.yml) on GitHub, or email [support@rapiercraftstudios.com](mailto:support@rapiercraftstudios.com) directly.
+
+---
+
+## Procurement Facts
+
+Questions procurement teams typically ask, answered directly:
+
+**Does ForgeDock run on our infrastructure or yours?**
+ForgeDock runs entirely on your own environment. There is no ForgeDock-operated compute, API proxy, or data relay. The pipeline commands run inside your Claude Code session on your machine, calling the Anthropic API directly with your credentials.
+
+**Where does pipeline state live?**
+All pipeline state lives in your GitHub repository: issue comments (FORGE annotations), PR descriptions, and workflow labels. ForgeDock writes nothing to any external system. You own the data; you can query or delete it with standard GitHub tools.
+
+**Do you have access to our code or GitHub data?**
+No. ForgeDock has no server-side component that could receive your code or GitHub data. The `npx forgedock` installer symlinks command files into `~/.claude/commands/` on the developer's machine — it does not phone home.
+
+**How are contributions governed?**
+All contributors sign a Developer Certificate of Origin (DCO) on each commit. ForgeDock does not use a CLA. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for the full process.
+
+**Security policy?**
+See [`SECURITY.md`](../../SECURITY.md) for the vulnerability disclosure policy and contact.
+
+**Governance?**
+See [`GOVERNANCE.md`](../../GOVERNANCE.md) for the project's decision-making process and stewardship model.
+
+---
+
+## Contact
+
+Commercial licensing, design-partner applications, and enterprise inquiries:
+
+- **Email**: [support@rapiercraftstudios.com](mailto:support@rapiercraftstudios.com)
+- **Design-partner intake form**: [Open an intake request on GitHub](https://github.com/RapierCraftStudios/ForgeDock/issues/new?template=design-partner.yml)
+- **Sponsors / early access**: [github.com/sponsors/RapierCraftStudios](https://github.com/sponsors/RapierCraftStudios)

package/docs/site/forge-annotation-protocol.md

@@ -1,266 +1,22 @@
 ---
 title: "The FORGE Annotation Protocol"
-description: "Technical specification for FORGE annotations — the open machine-readable comment protocol for AI agent context passing. Adopt it in your own agent pipelines."
+description: "Technical specification for FORGE annotations — the open machine-readable comment protocol for AI agent context passing."
 keywords: ["ai agent context protocol", "ai agent communication", "forge annotations", "llm agent memory protocol", "ai pipeline protocol", "structured agent context"]
 ---
 
 # The FORGE Annotation Protocol
 
-FORGE annotations are machine-readable HTML comment blocks embedded in GitHub issue and PR comments. They form a **lightweight, open protocol** for AI agents to pass structured context to each other across sessions.
-
-Any AI pipeline can adopt FORGE annotations. The format is GitHub-native, human-readable, and requires no infrastructure beyond the `gh` CLI.
-
----
-
-## The Problem FORGE Solves
-
-AI agents are stateless. When a session ends, every agent starts fresh — with no knowledge of what previous agents found, decided, or built.
-
-The naive solution is to re-derive everything from scratch every time. This is:
-
-- **Slow** — repeating investigation work already done
-- **Inconsistent** — different agents may reach different conclusions about the same code
-- **Lossy** — nuance from investigation doesn't always survive into implementation
-
-FORGE solves this by making agent outputs **persistent**, **structured**, and **queryable** — written to GitHub where they stay forever and can be read by any downstream agent or human.
-
----
-
-## Protocol Overview
-
-A FORGE annotation is a GitHub comment that begins with an HTML comment tag identifying the agent that wrote it:
-
-```html
-<!-- FORGE:{AGENT_TYPE} -->
-```
-
-The comment may also contain a completion marker:
-
-```html
-<!-- {AGENT_TYPE}:COMPLETE -->
-```
-
-The completion marker is checked by downstream pipeline phases to determine whether the annotation represents a fully-written result or a partial/interrupted one.
-
----
-
-## Defined Annotation Types
-
-### `FORGE:INVESTIGATOR`
-
-Posted by the investigation agent after analyzing an issue.
-
-**Contents**:
-- Verdict: CONFIRMED | PARTIAL | INVALID
-- Confidence: HIGH | MEDIUM | LOW
-- Severity: CRITICAL | HIGH | MEDIUM | LOW
-- Root Cause with file:line references
-- Complete Affected Files list
-- Evidence (function names, behavior observed)
-- Decomposition Assessment (YES/NO with rationale)
-
-**Completion marker**: `<!-- INVESTIGATION:COMPLETE -->`
-
-**Read by**: Builder, Architect, Context Gatherer
-
-```
-<!-- FORGE:INVESTIGATOR -->
-## Investigation Report
-
-**Verdict**: CONFIRMED
-**Confidence**: HIGH
-**Root Cause**: `services/payments/validator.py:142` — billing profile lookup
-  does not guard against None for free-tier users.
-
-...
-
-<!-- INVESTIGATION:COMPLETE -->
-```
-
----
-
-### `FORGE:CONTRACT`
-
-Posted by the contract agent, establishing the build scope.
-
-**Contents**:
-- Task Type (Bug Fix | Feature | Refactor | Maintenance)
-- Proposed Approach
-- Deliverables table: file | change description | why
-- Acceptance Criteria (checkboxes)
-- Quality Considerations
-- Out of Scope
-
-**Read by**: Builder, Reviewer
-
----
-
-### `FORGE:ARCHITECT`
-
-Posted by the architecture agent with an implementation plan.
-
-**Contents**:
-- Affected Paths table: file | function | change required | why
-- Implementation Order (numbered, with rationale)
-- Consistency Checks (invariants all paths must satisfy)
-- Risk Assessment table: risk | severity | mitigation
-- Files to Read Before Coding
-
-**Completion marker**: `<!-- FORGE:ARCHITECT:COMPLETE -->`
-
-**Read by**: Builder (follows the implementation order exactly)
-
----
-
-### `FORGE:CONTEXT`
-
-Posted by the context gathering agent with institutional memory.
-
-**Contents**:
-- Known Pitfalls for This Area (from past review findings)
-- Historical Findings on These Files
-- Past Bugs in This Module
-- Related Code Paths (callers/importers of changed functions)
-- Patterns That Cause Bugs Here
-- Successful Similar Implementations
-
-**Completion marker**: `<!-- FORGE:CONTEXT:COMPLETE -->`
-
-**Read by**: Builder (read before touching any code)
-
----
-
-### `FORGE:BUILDER`
-
-Posted by the implementation agent after completing a build.
-
-**Contents**:
-- Branch name
-- Commit SHAs
-- Files changed count
-- Approach summary (key decisions)
-- Changes (bulleted file-by-file list)
-- Acceptance Criteria Status (from CONTRACT, marked pass/fail)
-- Testing Checklist
-
-**Completion marker**: `<!-- FORGE:BUILDER:COMPLETE -->`
-
-**Read by**: Review orchestrator, Phase 6 close agent
-
----
-
-### `FORGE:REVIEWER`
-
-Posted by domain review agents on the PR.
-
-**Contents**:
-- Agent type (e.g., SECURITY, LOGIC, FRONTEND, DATABASE)
-- Verdict: APPROVED | CHANGES_REQUESTED | COMMENTED
-- Findings (severity: CRITICAL | HIGH | MEDIUM | LOW)
-- Each finding: description, affected line, suggested fix, prevention rule
-
-**Read by**: Review orchestrator (determines merge eligibility), future context agents
-
----
-
-### `FORGE:TRAJECTORY`
-
-Posted as the final annotation on a closed issue. Serves as a permanent audit trail.
-
-**Contents**:
-- Phase-by-phase results table
-- Key decisions made during the pipeline
-- Anomalies detected
-- Pipeline completion timestamp
-
-**Read by**: `pipeline-health` command for performance analysis, future context agents for pattern mining
-
----
-
-## Partial Annotation Detection
-
-If a pipeline phase is interrupted mid-run (session ends, compaction, error), the annotation may be present but incomplete — missing its completion marker.
-
-The canonical detection pattern:
-
-```bash
-# Check for FORGE:INVESTIGATOR without INVESTIGATION:COMPLETE
-gh api repos/{owner}/{repo}/issues/{number}/comments \
-  --jq '.[] | select(
-    .body | contains("FORGE:INVESTIGATOR") and
-    (contains("INVESTIGATION:COMPLETE") | not)
-  ) | .id'
-```
-
-If a partial annotation is found, the pipeline deletes it and re-runs the phase from scratch. This ensures downstream agents never read incomplete context.
-
----
-
-## Querying FORGE State with the `gh` CLI
-
-FORGE annotations are queryable using standard `gh` CLI JSON filtering:
-
-```bash
-# Get the investigation report for issue #42
-gh api repos/{owner}/{repo}/issues/42/comments \
-  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
-
-# Check current workflow phase
-gh issue view 42 -R {owner}/{repo} --json labels \
-  --jq '[.labels[].name | select(startswith("workflow:"))]'
-
-# Find all issues currently in-review
-gh issue list -R {owner}/{repo} \
-  --label "workflow:in-review" \
-  --json number,title
-
-# Check if build is complete (FORGE:BUILDER exists)
-gh api repos/{owner}/{repo}/issues/42/comments \
-  --jq '.[] | select(.body | contains("FORGE:BUILDER:COMPLETE")) | .id'
-```
+> **This page has moved.**
+>
+> The normative specification for the FORGE Annotation Protocol is now maintained at:
+>
+> **[`docs/spec/forge-protocol-v1.md`](../spec/forge-protocol-v1.md)**
+>
+> That document is the single source of truth for all FORGE annotation types,
+> syntax rules, the label state machine, conformance requirements, the extension
+> mechanism, and the versioning policy. It is licensed under
+> [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
 
 ---
 
-## Adopting FORGE in Your Own Pipeline
-
-FORGE is an open format. You don't need ForgeDock to use it.
-
-**Minimum viable adoption**:
-
-1. Pick annotation types relevant to your pipeline (INVESTIGATOR + BUILDER is a good start)
-2. Write your agent prompts to post annotated comments after each phase
-3. Write your downstream agent prompts to read those comments before starting
-
-The protocol is intentionally minimal — it's just structured text in GitHub comments. Any agent that can run `gh issue comment` and `gh api` can participate.
-
-**Extending the protocol**:
-
-You can define your own annotation types by following the naming convention:
-
-```html
-<!-- FORGE:YOUR_CUSTOM_AGENT -->
-```
-
-The only constraint: use a unique name that won't conflict with existing types. Custom types are invisible to ForgeDock agents, which only read the types they know about.
-
----
-
-## Why GitHub Comments (Not a Database)
-
-FORGE deliberately uses GitHub comments rather than a dedicated database or vector store because:
-
-1. **Zero infrastructure** — no service to deploy, no schema to maintain
-2. **Human-readable** — engineers can read the full context without tooling
-3. **Durable** — GitHub issues are permanent; comments survive repo migrations
-4. **Queryable** — the `gh` CLI provides a complete query interface
-5. **Universal** — any agent that can use `gh` can participate in the pipeline
-
-The tradeoff is that querying is text-based (not semantic). For most pipeline coordination use cases, exact-match on annotation type markers is sufficient.
-
----
-
-## Next Steps
-
-- [How ForgeDock's Knowledge Graph Works](./how-it-works.md) — see FORGE annotations in the full pipeline context
-- [Complete Command Reference](./command-reference.md) — commands that read and write FORGE annotations
-- [Getting Started with ForgeDock in 5 Minutes](./getting-started.md) — see FORGE annotations appear live on your issues
+*This file is kept as a redirect stub so that existing links and references continue to resolve.*

package/docs/site/getting-started.md

@@ -43,13 +43,15 @@ go install github.com/mikefarah/yq/v4@latest
 
 ## Step 1: Install ForgeDock
 
-Run the installer with `npx`:
+Run the installer with `npx` from your project directory:
 
 ```bash
 npx forgedock
 ```
 
-This symlinks all 25+ ForgeDock command specs into `~/.claude/commands/` — making them available as slash commands in every Claude Code session.
+This installs all 25+ ForgeDock command specs into the current project (project-scoped by default) — making them available as slash commands in Claude Code sessions for this repo.
+
+> **Want commands available across all projects on this machine?** Use `npx forgedock --global` to install into `~/.claude/commands/` instead. Project-scoped is the default for new installs; use `--global` as an explicit opt-in.
 
 **Verify the install:**
 
@@ -71,24 +73,31 @@ ForgeDock Doctor — Installation Health Check
   All checks passed. ForgeDock installation is healthy.
 ```
 
-It exits `0` when everything passes and `1` if any check fails, so you can also use it in CI. The `forge.yaml` and GitHub-label checks will fully pass once you finish Step 2 below — re-run `doctor` any time your setup feels off.
+It exits `0` when everything passes and `1` if any check fails, so you can also use it in CI.
 
-> Prefer a quick spot-check? `ls ~/.claude/commands/ | grep -E "work-on|review-pr|quality-gate"` should list `work-on.md`, `review-pr.md`, and `quality-gate.md`.
+> Prefer a quick spot-check? `ls .claude/commands/ | grep -E "work-on|review-pr|quality-gate"` should list `work-on.md`, `review-pr.md`, and `quality-gate.md`. (For a `--global` install, use `ls ~/.claude/commands/` instead.)
 
 ---
 
-## Step 2: Configure Your Repository
-
-ForgeDock reads a single `forge.yaml` in your project root. **Start minimal** — only the `project`, `paths`, and `branches` sections are required. Everything else is optional and falls back to sensible defaults; add sections as you need them.
+## Step 2: Your Config Is Already There
 
-The fastest way to get a working config is the `--minimal` flag, which scans your repo and writes just the required sections with detected values:
+`npx forgedock` in Step 1 ran the full install journey — including repo detection and a reviewed `forge.yaml` — so there's no separate config step to run. If you need to redo detection later (moved the repo, renamed a branch), or want a leaner config with just the required sections, re-run:
 
 ```bash
 cd /path/to/your/project
 npx forgedock init --minimal
 ```
 
-This produces a short, readable `forge.yaml` like the one below — this is essentially ForgeDock's own real-world config:
+**Optional: enrich the config.** Once `forge.yaml` exists, open Claude Code in your project directory and run `/forgedock-init` to fill in the optional sections that plain detection can't infer:
+
+- Project board connection (GitHub Projects v2)
+- Satellite repo routing (multi-repo setups)
+- Review context (tech stack, known pitfalls)
+- Service URLs for health checks
+
+`/forgedock-init` completes an existing `forge.yaml` — it won't create one from scratch.
+
+**Minimal `forge.yaml` example:**
 
 ```yaml
 project:
@@ -110,7 +119,7 @@ That's the whole config. Run `npx forgedock doctor` to confirm it's valid.
 
 > **The three required sections are `project`, `paths`, and `branches`** — `npx forgedock init --minimal` auto-detects `paths` for you (so worktrees land in the right place) and you rarely need to touch it. Everything else (project board, review context, verification commands, multi-repo routing) is optional and falls back to sensible defaults. Browse [`forge.yaml.example`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/forge.yaml.example) and [`docs/CONFIG.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/CONFIG.md) when you're ready to customize.
 
-**Prefer guided, AI-powered setup?** Open Claude Code in your project directory and run `/forgedock-init` instead — it scans your repo and fills in the optional sections (repo owner/name, worktree path, branch strategy, project board) for you. Plain `npx forgedock init` (no flag) generates the full annotated template with every optional section commented out.
+**Prefer guided, AI-powered setup?** Open Claude Code in your project directory and run `/forgedock-init` instead — it scans your repo and fills in the optional sections (repo owner/name, worktree path, branch strategy, project board) for you.
 
 ---
 
@@ -196,11 +205,11 @@ The quick fixes below cover the most common first-run issues. For the full list
 
 **`/work-on` not found in Claude Code**
 
-The symlink wasn't created. Re-run `npx forgedock` and check `ls ~/.claude/commands/`.
+The symlink wasn't created. Re-run `npx forgedock` and check `ls .claude/commands/` (project-scoped, default) or `ls ~/.claude/commands/` (if you used `--global`).
 
 **`forge.yaml` not found**
 
-Run `/forgedock-init` in your project directory inside Claude Code, or copy `forge.yaml.example` from the ForgeDock repo and edit it.
+Run `npx forgedock init` in your project directory to generate it, or copy `forge.yaml.example` from the ForgeDock repo and edit it. Once it exists, `/forgedock-init` inside Claude Code can fill in the optional sections.
 
 **`gh` auth errors**
 
@@ -209,3 +218,40 @@ Run `gh auth login` and complete the OAuth flow. ForgeDock uses `gh` for all Git
 **Pipeline stops at investigation**
 
 The issue may have been marked `workflow:invalid`. Check the issue comments for the investigation report — it will explain why.
+
+---
+
+## Migrating from a global install
+
+If you installed ForgeDock before project-scoped became the default (prior to v1.0.22), your commands live in `~/.claude/commands/`. You have two options:
+
+**Option A: Keep the global install (no action required)**
+
+Add `--global` to all future `npx forgedock install/update/uninstall/doctor` calls. Your existing setup is unchanged.
+
+```bash
+npx forgedock update --global   # re-link after a version bump
+```
+
+**Option B: Switch to project-scoped (recommended for per-repo version control)**
+
+1. Remove the global install:
+   ```bash
+   npx forgedock uninstall --global
+   ```
+2. In each repo you want ForgeDock in, run a fresh project-scoped install:
+   ```bash
+   cd /path/to/your-repo
+   npx forgedock install
+   ```
+3. Verify:
+   ```bash
+   npx forgedock doctor      # auto-detects project-scoped install
+   ```
+
+**Detect your current mode:**
+
+```bash
+npx forgedock doctor          # prints "Mode: project-scoped" or "Mode: global"
+npx forgedock status          # shows install path
+```

package/docs/site/github-is-the-memory.md

@@ -0,0 +1,113 @@
+---
+title: "GitHub Is Already Your Agents' Memory"
+description: "AI agents re-derive everything from scratch every session. The data they need to avoid that is already in GitHub — commits, PRs, issues, blame. ForgeDock makes it machine-readable."
+keywords: ["ai agent memory", "github knowledge graph", "forge annotation protocol", "deterministic phase engine", "trajectory receipt"]
+---
+
+# GitHub Is Already Your Agents' Memory
+
+Every agent session begins the same way. The model reads the codebase, forms a hypothesis, and starts writing. It does not know that the function it is about to change was shaped by a bug fix filed in issue #347. It does not know that the approach it is about to try was already attempted and reverted in PR #891. It does not know that three other files will need the same change, because a review agent noted that dependency two weeks ago and the note lives in a comment thread the current session never read.
+
+This is the memory problem — not context length. Context windows are large enough. The bottleneck is that nothing ever gets written down in a place where the next agent session can find it.
+
+The common solution is a sidecar memory store: a vector database, an MCP memory server, a proprietary knowledge base. The agent writes embeddings after a run; the next agent retrieves them at session start. The idea is reasonable. The execution has a consistent flaw: it duplicates structure that already exists in GitHub while being invisible to humans and every tool that is not specifically wired to query it. A human reading the issue thread sees none of it. A `git blame` reveals none of it. A new developer onboarding to the codebase sees none of it.
+
+GitHub is already a citation graph. Commits reference issues. Pull requests reference commits. Issues cross-reference related issues. `git blame` traces every line to a commit, which traces to a PR, which traces to an issue thread containing the full reasoning behind the change. That graph is public, auditable, searchable with standard tools, and survives any vendor relationship. Agents just do not use it as one.
+
+The question is not whether to give agents memory. The question is whether that memory should live inside proprietary stores that duplicate GitHub, or whether it should live in GitHub itself — where every human and tool on the project can already read it.
+
+---
+
+## What "machine-readable" means here
+
+The GitHub citation graph is human-readable by design. An issue thread mixes prose rationale, code snippets, review comments, and reactions. A commit message is free text. A PR description has whatever structure the author chose to give it.
+
+Human-readable is not the same as machine-parseable. A downstream agent cannot reliably extract "the root cause identified in the investigation phase" from a prose paragraph that may or may not contain one. It cannot reliably distinguish a speculative suggestion from a confirmed finding. It cannot know which comment in a 40-comment thread represents the agreed-upon plan.
+
+ForgeDock's answer is **FORGE annotations** — structured HTML comments written by each pipeline stage and read by every downstream stage. An annotation looks like this:
+
+```html
+<!-- FORGE:INVESTIGATOR
+verdict: CONFIRMED/HIGH
+root_cause: The co-change query reads a variable populated only by the Layer 5 subsystem, which shipped in PR #1204 three hours before this issue was filed. The variable is never written on the headless path.
+affected_files: commands/orchestrate.md, scripts/layer5-query.sh
+-->
+```
+
+This is still a GitHub comment — a human reading the thread sees it as a collapsed HTML comment or reads its contents directly. But a downstream agent querying the issue with `gh issue view` gets it as structured text it can parse without guessing at prose intent. The annotation is the contract between stages.
+
+The annotation format is an open standard — the [FORGE Annotation Protocol](../spec/forge-protocol-v1.md). Any agent pipeline can implement it without ForgeDock. The format is documented in full, the vocabulary is fixed, and the license is CC-BY-4.0.
+
+---
+
+## Three terms, defined once
+
+**Knowledge graph** — in this context, the set of GitHub issues, pull requests, commits, and their cross-references, treated as a queryable graph rather than a linear history. The `gh` CLI is the query interface. `gh issue view`, `gh pr view`, `gh issue list --search`, and `git log` are the operations. No additional infrastructure is required.
+
+**Trajectory receipt** — the `FORGE:TRAJECTORY` annotation written to a GitHub issue at the end of a pipeline run. It records what each phase actually did: the investigation verdict, the architectural decision, the build summary, the quality gate results, the review findings, and the merge commit. It is not a log file on a server; it is a public comment on the issue, readable by any agent that opens that issue in any future session. On this repository, trajectory receipts are the primary mechanism by which the pipeline avoids repeating work.
+
+**Deterministic phase engine** — the component that decides what happens next in a pipeline run, based on GitHub state rather than model inference. When a run is interrupted and resumed, the engine reads the annotations present on the issue, determines which phases have completed, and advances to the correct next phase. The model does not decide whether to re-run investigation; the engine reads the `FORGE:INVESTIGATOR` annotation, finds it present and valid, and skips directly to context. Phase selection is a pure rule-based state machine. The engine shipped in [PR #1326](https://github.com/RapierCraftStudios/ForgeDock/pull/1326).
+
+---
+
+## What the receipts actually show
+
+These are public runs on this repository — the annotation trails are readable on the linked issues.
+
+**Citing past bugs by number, before a line is written.** From [issue #1196](https://github.com/RapierCraftStudios/ForgeDock/issues/1196), the context phase produced this output before build began:
+
+> "`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."
+
+That output came from querying the knowledge graph — the agent read the PR history for `commands/orchestrate.md`, extracted the annotated findings from prior reviews, and synthesized the relevant constraints. It did not come from a vector database. It came from GitHub.
+
+**Review catching a bug in the fix itself.** [Issue #1230](https://github.com/RapierCraftStudios/ForgeDock/issues/1230): the pipeline's own staging review identified dead code in a feature the pipeline had shipped three hours earlier (the co-change query read a never-populated variable). A fix was built. The review phase then caught a defect in the fix: stray backticks in the grep pattern meant every `git-log` pathspec silently matched zero commits. The reviewer's finding read: "the fix would not have actually worked." The fix was corrected. Intent to merged: 30 minutes.
+
+**Self-invalidation with receipts.** [Issue #952](https://github.com/RapierCraftStudios/ForgeDock/issues/952): the investigation phase closed the pipeline's own proposal as INVALID. The deliverable had already shipped weeks earlier. The trajectory receipt documents the reasoning and links the prior PR. Zero code written. The pipeline did not guess; it queried GitHub, found the prior work, and stopped.
+
+These are not selected for drama. They are selected because each one is a case where the pipeline's behavior was downstream of structured data in GitHub — not model intuition, not a sidecar store, not a human prompt.
+
+---
+
+## Why memory that lives where the work lives is different
+
+A sidecar memory store requires explicit maintenance. Someone has to decide what gets stored, in what format, with what retention policy. If the store is lost or migrated, the memory is gone. If a new engineer joins the project, they cannot read the memory with their existing tools — they need access to and familiarity with the store.
+
+Memory in GitHub requires none of this. Every FORGE annotation is a GitHub comment. It appears in the issue timeline. It is indexed by GitHub search. It is exportable via the standard API. It is archived in every repository clone. A new engineer reading an issue thread encounters the full investigation, architectural rationale, build summary, and review findings as part of the normal issue history — no additional access required.
+
+This is what "auditable, portable, and survives any vendor" means in practice. The annotations are machine-readable because they have structure. They are human-readable because they are GitHub comments. They are durable because GitHub is the primary store, not a secondary one.
+
+The `gh` CLI as query interface means the memory is queryable from any shell, any CI environment, and any agent session — with no SDK, no API key rotation for a separate service, and no schema migration to manage.
+
+---
+
+## The compounding property
+
+Trajectory receipts compound. When the pipeline works on a module it has touched before, the context phase finds prior trajectory receipts for that module, extracts the review findings they record, and forwards them to the architect and builder as known constraints. Known bugs do not get reintroduced. Known approaches that failed are not re-attempted. Known patterns that the reviewer flagged get applied proactively.
+
+In this repository's first 30 days (June 4 through July 4, 2026): 693 issues filed, 605 closed, 603 PRs merged. 49% of all issues filed originated from the pipeline's own review agents — bugs the pipeline found in its own output, filed as issues, and then fixed. That loop runs because each review's findings are annotated on the PR, the trajectory receipt records them on the issue, and the context phase for any subsequent work on the same files reads them. Numbers are point-in-time; a reproducible benchmark is in progress at [#1264](https://github.com/RapierCraftStudios/ForgeDock/issues/1264).
+
+---
+
+## Two paths forward
+
+**Try it end-to-end with ForgeDock:**
+
+```bash
+npx forgedock demo
+```
+
+This spins up a risk-free demo repository and walks the full pipeline — investigate, build, review, merge — so you can read the annotations it produces before pointing it at a production codebase. The full setup:
+
+```bash
+npx forgedock
+```
+
+Checks your environment, installs the slash commands into Claude Code, and generates a `forge.yaml` for your repository.
+
+**Adopt the protocol without ForgeDock:**
+
+The annotation format is the independently useful part. The [FORGE Annotation Protocol](../FORGE-PROTOCOL.md) document describes the philosophy and vocabulary. The [protocol spec](../spec/forge-protocol-v1.md) gives the full technical definition — annotation types, required fields, completion markers, and query patterns. The license is CC-BY-4.0. Any agent pipeline can implement structured GitHub annotations using these specs without adopting ForgeDock's command layer. The only requirement is consistency: if annotations are written and read with the same vocabulary, the knowledge graph is coherent across sessions.
+
+---
+
+The sidecar stores are building a parallel infrastructure for something GitHub already does. The annotations are the part that was missing — the structured layer that makes the existing graph machine-readable. Once that layer exists, the query interface is `gh`, the storage is GitHub, and the memory is wherever the work is.

package/docs/site/how-it-works.md

@@ -127,19 +127,9 @@ A new agent session running `/work-on 42` should always know what to do next by
 
 ## Labels as State Machine
 
-GitHub labels track the workflow state of every issue:
-
-| Label | Meaning |
-|-------|---------|
-| `workflow:investigating` | Investigator agent is running |
-| `workflow:ready-to-build` | Investigation complete, queued for build |
-| `workflow:building` | Builder agent is running |
-| `workflow:in-review` | PR created, review agents running |
-| `workflow:merged` | PR merged, issue closed |
-| `workflow:invalid` | Issue was not a real problem |
-| `workflow:decomposed` | Split into sub-issues |
-
-The pipeline reads these labels to determine what to do next. A human can also manually set a label to nudge the pipeline or override its routing.
+GitHub labels track the workflow state of every issue. The pipeline reads these labels to determine what to do next. A human can also manually set a label to nudge the pipeline or override its routing.
+
+> **Label reference**: [`docs/spec/label-state-machine.md`](../spec/label-state-machine.md) — full state table, transition rules, and terminal labels.
 
 ---