forgedock 1.2.0 → 1.4.0

package/docs/launch/show-hn.md

@@ -25,9 +25,9 @@ The fix isn't a bigger context window. It's structured memory that survives conv
 
 ForgeDock treats GitHub as that memory layer. Every pipeline stage writes machine-readable HTML annotations to issues and PRs — FORGE:INVESTIGATOR traces root cause to a specific commit, FORGE:ARCHITECT produces a typed implementation plan, FORGE:CONTEXT surfaces known pitfalls from closed issues in the same module. The next agent reads these before doing anything. The gh CLI is the query interface; no external store, no embeddings.
 
-The pipeline: /work-on #42 → investigate (reads git blame, closed issues, review findings) → architect (traces all call sites, orders changes by dependency) → build → quality gate (14+ check domains) → 9-agent review → PR. Each stage writes what it found so the next stage doesn't repeat the work. After 20,000+ issues processed across real production codebases, patterns accumulate: the context phase now flags known pitfalls in a module before the builder touches it.
+The pipeline: /work-on #42 → investigate (reads git blame, closed issues, review findings) → architect (traces all call sites, orders changes by dependency) → build → quality gate (14+ check domains) → 9-agent review → PR. Each stage writes what it found so the next stage doesn't repeat the work. ForgeDock builds itself with this pipeline — in its first 30 days, 693 issues filed and 603 PRs merged across the repo — and patterns accumulate: the context phase now flags known pitfalls in a module before the builder touches it.
 
-It's 25 markdown command specs installed via npx forgedock, no runtime server. Would love to hear what the HN community thinks about using GitHub's existing graph structure — commits, blame, cross-references — as agent memory.
+It's a set of markdown command specs installed via npx forgedock, no runtime server. Would love to hear what the HN community thinks about using GitHub's existing graph structure — commits, blame, cross-references — as agent memory.
 ```
 
 **Character count**: ~1,380 characters (well within 4,000 limit)
@@ -71,7 +71,7 @@ It's 25 markdown command specs installed via npx forgedock, no runtime server. W
 
 ### "Why HTML comments for annotations?"
 
-> GitHub renders HTML comments invisibly to humans — the issue stays readable without noise. Agents grep for `<!-- FORGE:INVESTIGATOR -->` to find structured context fast. It's a zero-dependency protocol: no API, no schema registry, no additional auth. Any tool with `gh` CLI access can read and write annotations. The downside is parsing cost (tokens to extract fields from markdown); the [Vision section of the README](https://github.com/RapierCraftStudios/ForgeDock#vision) describes replacing this with a purpose-built graph store once the protocol is proven.
+> GitHub renders HTML comments invisibly to humans — the issue stays readable without noise. Agents grep for `<!-- FORGE:INVESTIGATOR -->` to find structured context fast. It's a zero-dependency protocol: no API, no schema registry, no additional auth. Any tool with `gh` CLI access can read and write annotations. The downside is parsing cost (tokens to extract fields from markdown); the [Where it's going section of the README](https://github.com/RapierCraftStudios/ForgeDock#where-its-going) describes replacing this with a purpose-built graph store once the protocol is proven.
 
 ---
 

package/docs/site/architecture.md

@@ -0,0 +1,180 @@
+---
+title: "ForgeDock Architecture"
+description: "How ForgeDock's autonomous pipeline works. Phase-by-phase breakdown, FORGE annotation relay, worktree isolation, and how agents reconstruct context after compaction."
+---
+
+# ForgeDock Architecture
+
+ForgeDock is **not an application** — it's a set of markdown command specs that get symlinked into `~/.claude/commands/` and invoked as slash commands in Claude Code. There is no runtime process. Every pipeline operation runs inside Claude Code, using GitHub as the persistence layer.
+
+---
+
+## Repository Structure
+
+```
+commands/              # Authoritative workflow specs
+  work-on.md           # Main orchestrator: investigate → build → review → merge
+  work-on/             # Sub-phases: investigate, build, review, close
+    build/             # Sub-sub-phases: context, architect, implement, validate
+  review-pr.md         # PR review orchestrator
+  review-pr-agents.md  # 9-agent review catalog
+  orchestrate.md       # Parallel multi-issue execution
+  quality-gate.md      # Pre-commit checks (14+ domains)
+  autopilot.md         # Self-improvement cycle
+  ...                  # 25+ more commands
+
+bin/                   # npm installer
+  forgedock.mjs        # npx forgedock — symlinks commands into ~/.claude/commands/
+
+docs/                  # Reference docs and this site
+scripts/               # Verification scripts used by quality-gate
+.agents/               # Codex adapter layer (repo-local skill overrides)
+```
+
+---
+
+## The Pipeline Relay
+
+The core innovation is **structured context passing via GitHub annotations**. Every pipeline phase writes a `FORGE:` annotation as a GitHub issue comment. Every downstream phase reads prior annotations before acting.
+
+```
+Issue opened
+    │
+    ▼
+FORGE:INVESTIGATOR  — root cause, affected files, recommendation
+    │
+    ▼
+FORGE:CONTRACT      — what will be built, deliverables table, acceptance criteria
+    │
+    ▼
+FORGE:CONTEXT       — past review findings, historical bugs, related code paths
+    │
+    ▼
+FORGE:ARCHITECT     — implementation plan, ordered file changes, risk assessment
+    │
+    ▼
+FORGE:BUILDER       — branch, commits, files changed, acceptance criteria status
+    │
+    ▼
+FORGE:REVIEW        — domain agent findings, severity ratings
+    │
+    ▼
+FORGE:TRAJECTORY    — audit trail, pipeline phase results, anomalies
+```
+
+This relay means:
+- A new session can pick up exactly where a previous one left off by reading GitHub state
+- Context compaction does not lose work — the next agent re-reads annotations and continues
+- The audit trail is human-readable and queryable with the `gh` CLI
+
+---
+
+## Pipeline Phases
+
+### Phase 0: Context Load
+
+Reads issue number, labels, milestone, existing annotations. Determines which phase to resume from. Classifies lane (fast vs. feature) based on milestone presence.
+
+**Fast lane**: Issues without a milestone → PR targets `staging`.
+**Feature lane**: Issues with a milestone → PR targets `milestone/{slug}`.
+
+### Phase 1: Investigation
+
+Validates whether the issue is real. Reads domain files, traces execution paths, git blame. Posts `FORGE:INVESTIGATOR` with verdict (CONFIRMED / PARTIAL / INVALID), root cause, affected files, and decomposition assessment.
+
+### Phase 2: Decomposition (conditional)
+
+If 2+ services, 6+ files across directories, or multiple task types: creates sub-issues with dependency order. Parent issue gets `workflow:decomposed`. Each sub-issue runs its own `/work-on`.
+
+### Phase 3: Build
+
+Sub-phases in order:
+
+| Sub-phase | What Happens |
+|-----------|-------------|
+| 3C: Contract | Builder posts deliverables table, acceptance criteria, quality considerations |
+| 3C.5: Context | Surfaces institutional memory — past review findings, historical bugs, related code paths |
+| 3C.6: Architect | Traces ALL affected code paths, sequences implementation order, assesses risk |
+| 3F: Implement | Writes code in isolated git worktree per the architect plan |
+| 3G: Quality Gate | 14-category pre-commit check (runs up to 3 iterations) |
+| 3H: Format | Language-specific formatting and type checking |
+| 3K: Commit | Conventional commit with issue reference |
+| 3M: Builder comment | Posts `FORGE:BUILDER` with branch, commits, acceptance criteria status |
+
+### Phase 4: PR Creation
+
+Pushes branch, creates PR targeting the correct base branch. Updates issue to `workflow:in-review`.
+
+### Phase 5: Auto-Review
+
+Invokes `/review-pr --auto-merge`. 9 domain agents (security, billing, database, concurrency, auth, frontend, API, performance, infrastructure) review the PR. Critical/HIGH findings become separate GitHub issues. PR merges if no blocking findings.
+
+### Phase 6: Close & Cleanup
+
+Closes the issue, sets `workflow:merged`, removes worktree and local branch. If issue is a sub-issue, checks off the item in the parent tracker.
+
+### Phase 7: Trajectory Log
+
+Posts `FORGE:TRAJECTORY` with phase-by-phase results table for pipeline health monitoring.
+
+---
+
+## Git Worktree Isolation
+
+Every build phase creates an isolated git worktree:
+
+```bash
+git worktree add .claude/worktrees/feat-my-feature-42 \
+  -b feat/my-feature-42 origin/staging
+```
+
+Benefits:
+- Build operations never dirty the main working tree
+- Multiple issues can be built in parallel without branch conflicts
+- Worktree is removed in Phase 6 after merge
+
+---
+
+## Quality Gate
+
+The quality gate checks code before commit across 14+ domains:
+
+- **Logic**: null checks, off-by-one errors, unreachable code
+- **Auth**: auth guards on all state-changing routes
+- **Database**: N+1 queries, missing indexes, raw SQL injection surface
+- **Security**: hardcoded credentials, injection vectors, CSRF exposure
+- **Frontend**: proxy wiring, missing error boundaries, a11y regressions
+- **Infrastructure**: Docker ownership, port binding, env var sync
+- **API contracts**: response shape changes, SDK literal sync
+- **Tests**: coverage gaps, missing edge cases
+
+Each finding is rated HIGH / MEDIUM / LOW. HIGH findings are blocking. The gate runs up to 3 iterations.
+
+---
+
+## Compaction Resilience
+
+Claude Code compacts context mid-session. ForgeDock is designed to survive this:
+
+1. **Write to GitHub after every significant step** — annotations are the durable state
+2. **Re-read GitHub at the start of each phase** — never assume in-memory context
+3. **Universal dispatcher** — any session can re-read issue labels and comments and determine exactly which phase to resume
+
+A new `/work-on 42` invocation after compaction reads the existing `FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:ARCHITECT`, and `FORGE:BUILDER` comments and jumps straight to Phase 4 (PR creation) or Phase 5 (review) without re-running earlier phases.
+
+---
+
+## Command Specs Are Prompts
+
+The `.md` files in `commands/` are detailed prompt engineering documents — some exceed 50KB. They constrain LLM behavior at every step:
+
+- **Phase boundaries** are explicit with entry conditions and exit actions
+- **Universal continuation rule** prevents premature stopping after intermediate results
+- **Structured output requirements** (e.g., `<!-- INVESTIGATION:COMPLETE -->` marker) are machine-readable gates that downstream phases check before proceeding
+- **Domain-specific rules** (INFRA footguns, type invariant verification, sibling pattern sweeps) encode institutional memory directly into the prompt
+
+---
+
+## Contributing
+
+The pipeline dogfoods itself. Bug reports, improvements, and new command specs all flow through `/work-on`. See [CONTRIBUTING.md](https://github.com/RapierCraftStudios/ForgeDock/blob/main/CONTRIBUTING.md) and [devdocs/project/architecture.md](https://github.com/RapierCraftStudios/ForgeDock/blob/main/devdocs/project/architecture.md) for the full strategic context.

package/docs/site/command-reference.md

@@ -453,6 +453,23 @@ Measures pipeline performance, correlates with prompt changes, and proposes impr
 
 ---
 
+### `/upgrade-deps`
+
+**Autonomous dependency upgrade pipeline.**
+
+Detects outdated packages, triages them by semver risk, creates GitHub issues for eligible upgrades, and runs each through `/work-on` — so every upgrade gets investigation, compatibility verification, quality gate, review, and merge rather than a blind version bump. Major upgrades are flagged for human review unless `--allow-major` is passed.
+
+```bash
+/upgrade-deps                     # Detect + triage + report only
+/upgrade-deps --dry-run           # All phases, but create nothing
+/upgrade-deps --ecosystem npm     # Limit to one ecosystem (npm|pip|cargo)
+/upgrade-deps --allow-major       # Include major upgrades in issue creation
+/upgrade-deps --limit 5           # Cap issue creation (default: 10)
+/upgrade-deps --batch             # Group patch upgrades into one issue
+```
+
+---
+
 ## Investigation & Validation
 
 ---

package/docs/site/configuration.md

@@ -0,0 +1,243 @@
+---
+title: "Configuration Reference — forge.yaml"
+description: "Complete forge.yaml schema reference for ForgeDock. All required and optional sections explained with examples."
+---
+
+# Configuration Reference — forge.yaml
+
+`forge.yaml` lives at your project root and tells ForgeDock commands how to interact with your project. Without it, commands cannot resolve your GitHub repository, paths, or branches.
+
+## Quick Start
+
+```bash
+# Option 1: Autopilot setup (recommended)
+npx forgedock init
+
+# Option 2: Manual setup
+cp forge.yaml.example forge.yaml
+# Edit forge.yaml with your project details
+echo "forge.yaml" >> .gitignore
+```
+
+`npx forgedock init` auto-detects most values from `git remote`, `package.json`, and `gh api`. You review the result on a single annotated screen.
+
+### `init` Flags
+
+| Flag | Behavior |
+|------|----------|
+| `--manual` | Skip AI enrichment — shows detection baseline values only |
+| `--verbose` | Show each field's detection source and confidence rationale |
+
+---
+
+## Schema Overview
+
+| Section | Required | Purpose |
+|---------|----------|---------|
+| [`project`](#project-required) | **Yes** | GitHub identity (owner, repo, name) |
+| [`paths`](#paths-required) | **Yes** | Local filesystem locations |
+| [`branches`](#branches-required) | **Yes** | Branch naming conventions |
+| [`repos`](#repos-optional) | No | Multi-repository routing |
+| [`project_board`](#project_board-optional) | No | GitHub Projects v2 integration |
+| [`services`](#services-optional) | No | External service URLs and IDs |
+| [`review`](#review-optional) | No | Context injected into review agents |
+| [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
+| [`verification`](#verification-optional) | No | Health-check patterns |
+| [`billing`](#billing-optional) | No | Financial integrity audit |
+| [`adaptive_scripts`](#adaptive_scripts-optional) | No | Per-repo script override configuration |
+
+---
+
+## `project` (REQUIRED)
+
+Core identity fields used by every command that calls `gh issue`, `gh pr`, or `gh project`.
+
+```yaml
+project:
+  name: "Acme Platform"
+  owner: "acme-org"
+  repo: "acme-platform"
+  description: "SaaS platform for automated data processing"
+  # forge_repo: "acme-org/acme-forge"  # if pipeline lives in a separate repo
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Human-readable name used in pipeline reports and issue comments |
+| `owner` | string | **Yes** | GitHub org or username |
+| `repo` | string | **Yes** | Repository name. Combined as `owner/repo` = the `GH_REPO` in all commands |
+| `description` | string | No | One-line description used in issue templates |
+| `forge_repo` | string | No | Pipeline repo in `owner/repo` format when pipeline lives separately from the project being developed |
+
+---
+
+## `paths` (REQUIRED)
+
+Local filesystem paths for git worktree operations.
+
+```yaml
+paths:
+  root: "/home/youruser/projects/acme-platform"
+  worktree_base: "/home/youruser/projects/acme-platform/.claude/worktrees"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `root` | string (absolute) | **Yes** | Absolute path to the project root. Base for `git worktree add` |
+| `worktree_base` | string (absolute) | **Yes** | Directory where per-branch worktrees are created |
+
+---
+
+## `branches` (REQUIRED)
+
+Branch naming conventions that control PR targeting and source branch selection.
+
+```yaml
+branches:
+  default: "main"
+  staging: "staging"
+  feature_pattern: "milestone/{slug}"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `default` | string | **Yes** | Default branch (`main` or `master`) |
+| `staging` | string | **Yes** | Staging branch for fast-lane PRs (issues without a milestone) |
+| `feature_pattern` | string | **Yes** | Pattern for feature branches. `{slug}` = milestone title in kebab-case |
+
+**Lane routing**: Issues without a milestone → fast lane → PR targets `branches.staging`. Issues with a milestone → feature lane → PR targets `branches.feature_pattern`.
+
+---
+
+## `repos` (OPTIONAL)
+
+Multi-repository routing for projects that span multiple GitHub repos.
+
+```yaml
+repos:
+  default:
+    repo: "acme-org/acme-platform"
+    staging_branch: "staging"
+
+  satellites:
+    - prefix: "mcp"
+      repo: "acme-org/acme-mcp-server"
+      staging_branch: "main"
+      local_path: "/home/youruser/projects/acme-mcp-server"
+```
+
+Use `<prefix>:<issue_number>` syntax in commands: `mcp:5`, `sdk:12`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `satellites[].prefix` | string | **Yes** | Short prefix for issue routing |
+| `satellites[].repo` | string | **Yes** | Full `owner/repo` of the satellite repository |
+| `satellites[].staging_branch` | string | **Yes** | Target branch for fast-lane PRs |
+| `satellites[].local_path` | string | No | Absolute local path to the satellite repo |
+| `satellites[].billing_enabled` | boolean | No | Enable financial integrity audit for this satellite |
+
+---
+
+## `project_board` (OPTIONAL)
+
+GitHub Projects v2 integration. When configured, ForgeDock automatically adds issues to the board and updates Status, Lane, Component, Priority, and Workflow fields.
+
+```yaml
+project_board:
+  owner: "acme-org"
+  project_number: 1
+  project_id: "PVT_kwHOxxxxxxxxxxxxxxxx"
+
+  field_ids:
+    status: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    lane: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    component: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    priority: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+    workflow: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+
+  option_ids:
+    status:
+      todo: "xxxxxxxx"
+      in_progress: "xxxxxxxx"
+      done: "xxxxxxxx"
+    lane:
+      fast: "xxxxxxxx"
+      feature: "xxxxxxxx"
+```
+
+**Finding your IDs**:
+
+```bash
+# List project IDs
+gh project list --owner <owner> --format json | jq '.projects[] | {number, id, title}'
+
+# List field IDs
+gh project field-list <project_number> --owner <owner> --format json | jq '.fields[]'
+
+# List option IDs for a single-select field
+gh project field-list <project_number> --owner <owner> --format json \
+  | jq '.fields[] | select(.name == "Status") | .options[]'
+```
+
+---
+
+## `review` (OPTIONAL)
+
+Context injected into review agent prompts. Helps agents make project-aware decisions.
+
+```yaml
+review:
+  context: |
+    This is a multi-tenant SaaS. Every endpoint must enforce tenant isolation.
+    We use row-level security in PostgreSQL — never bypass it.
+    Financial calculations must use Decimal, never float.
+```
+
+---
+
+## `devdocs` (OPTIONAL)
+
+Path to your project's devdocs knowledge tree. Agents read this for institutional context before making architectural decisions.
+
+```yaml
+devdocs:
+  path: "devdocs/"
+```
+
+The devdocs directory should contain `project/architecture.md` as the primary strategic context file. See [Architecture](./architecture) for details on ForgeDock's own devdocs structure.
+
+---
+
+## `adaptive_scripts` (OPTIONAL)
+
+Per-repo script overrides for deterministic pipeline operations. Allows you to replace prose instructions with executable scripts for project-specific validation.
+
+```yaml
+adaptive_scripts:
+  enabled: true
+  directory: "scripts/forge/"
+```
+
+---
+
+## Full Example
+
+```yaml
+# forge.yaml — minimal required config
+
+project:
+  name: "My Project"
+  owner: "my-org"
+  repo: "my-project"
+
+paths:
+  root: "/home/me/projects/my-project"
+  worktree_base: "/home/me/projects/my-project/.claude/worktrees"
+
+branches:
+  default: "main"
+  staging: "staging"
+  feature_pattern: "milestone/{slug}"
+```
+
+For the full annotated example, see [`forge.yaml.example`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/forge.yaml.example) in the repository.

package/docs/site/for-companies.md

@@ -30,7 +30,7 @@ Use this table to determine which license you need:
 
 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).
+For the full license text, see [`LICENSE`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/LICENSE) (AGPL-3.0) and [`COMMERCIAL-LICENSE.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/COMMERCIAL-LICENSE.md).
 
 ---
 
@@ -76,13 +76,13 @@ All pipeline state lives in your GitHub repository: issue comments (FORGE annota
 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.
+All contributors sign a Developer Certificate of Origin (DCO) on each commit. ForgeDock does not use a CLA. See [`CONTRIBUTING.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/CONTRIBUTING.md) for the full process.
 
 **Security policy?**
-See [`SECURITY.md`](../../SECURITY.md) for the vulnerability disclosure policy and contact.
+See [`SECURITY.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/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.
+See [`GOVERNANCE.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/GOVERNANCE.md) for the project's decision-making process and stewardship model.
 
 ---
 

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

@@ -10,7 +10,7 @@ keywords: ["ai agent context protocol", "ai agent communication", "forge annotat
 >
 > The normative specification for the FORGE Annotation Protocol is now maintained at:
 >
-> **[`docs/spec/forge-protocol-v1.md`](../spec/forge-protocol-v1.md)**
+> **[`docs/spec/forge-protocol-v1.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/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

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

@@ -36,7 +36,7 @@ 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.
+The annotation format is an open standard — the [FORGE Annotation Protocol](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/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.
 
 ---
 
@@ -106,7 +106,7 @@ Checks your environment, installs the slash commands into Claude Code, and gener
 
 **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 annotation format is the independently useful part. The [FORGE Annotation Protocol](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/FORGE-PROTOCOL.md) document describes the philosophy and vocabulary. The [protocol spec](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/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.
 
 ---
 

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

@@ -129,7 +129,7 @@ A new agent session running `/work-on 42` should always know what to do next by
 
 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.
+> **Label reference**: [`docs/spec/label-state-machine.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/spec/label-state-machine.md) — full state table, transition rules, and terminal labels.
 
 ---