forgedock 1.0.22 → 1.1.2

package/docs/design/eval-gate-runbook.md

@@ -0,0 +1,178 @@
+# Eval Gate Runbook
+
+> Companion to issue #1286, workflow `.github/workflows/eval-gate.yml`, and
+> `scripts/eval-gate-scorecard.mjs`.
+
+The pipeline eval gate automatically runs the eval harness (#1285) against
+`commands/` changes and fails CI if the one-shot success rate drops more than
+the defined threshold. This runbook explains how to interpret a gate failure,
+override when necessary, and update the baseline.
+
+---
+
+## What the gate checks
+
+The gate compares a fresh scorecard (produced by `scripts/eval-harness-runner.mjs`)
+against the committed baseline at `scripts/eval-gate-baseline.json`.
+
+**Regression threshold**: 5 percentage points.
+
+A drop of **more than 5 pp** in `success_rate_pct` vs the baseline is a
+regression and fails CI with exit code 1.
+
+Example:
+- Baseline: `success_rate_pct: 80`
+- Fresh: `success_rate_pct: 74` → drop = 6 pp → **FAIL** (6 > 5)
+- Fresh: `success_rate_pct: 75` → drop = 5 pp → **PASS** (5 = 5, not strictly greater)
+
+**Subset run carve-out**: When the fresh run has fewer than 8 issues, the rate
+assertion is skipped. Rationale: on n=5, one failure is 20 pp — always failing
+the gate even with no spec changes. The gate still validates structural
+correctness and emits a non-blocking summary.
+
+---
+
+## Trigger conditions
+
+| Event | What runs | Rate assertion applied |
+|-------|-----------|----------------------|
+| PR / push with substantive `commands/**` changes | Subset run | Only if n >= 8 |
+| `workflow_dispatch` (default) | Full corpus run | Yes |
+| `workflow_dispatch` with `run_mode: subset` | Subset run | Only if n >= 8 |
+| Non-substantive `commands/**` changes (typos, comments) | Nothing | N/A |
+
+A non-substantive change is one where every changed line in `commands/` is a
+blank line, HTML comment (`<!-- ... -->`), or Markdown heading (`# ...`).
+
+---
+
+## Interpreting a gate failure
+
+When the gate fails, the CI step prints:
+
+```
+eval-gate FAILED: REGRESSION: success rate dropped N pp
+(X% fresh vs Y% baseline). Threshold is 5 pp.
+A deliberate spec degradation or a real pipeline regression caused this failure.
+```
+
+Followed by actionable steps:
+1. Review the diff in `commands/` to identify what changed.
+2. Re-run the full corpus locally:
+   ```bash
+   node scripts/eval-harness-runner.mjs --mode full
+   ```
+3. If the regression is real: fix the spec, re-run, update the baseline (see below).
+4. If the regression is a false positive: see Override below.
+
+The structured JSON result is also printed and uploaded as a CI artifact
+(`eval-scorecard-subset-<sha>.json` or `eval-scorecard-full-<sha>.json`).
+
+---
+
+## Reading the scorecard diff
+
+The scorecard artifact contains:
+
+```json
+{
+  "pass": false,
+  "fresh_success_rate_pct": 74,
+  "baseline_success_rate_pct": 80,
+  "drop_pp": 6,
+  "threshold_pp": 5,
+  "rate_assertion_skipped": false,
+  "fresh_issues_run": 20,
+  "fresh_run_mode": "full",
+  "reason": "REGRESSION: ..."
+}
+```
+
+- `drop_pp`: positive = regression, negative = improvement.
+- `rate_assertion_skipped`: true means the run was too small for a meaningful rate.
+- `fresh_run_id` / `baseline_run_id`: link back to the specific runs for debugging.
+
+---
+
+## Updating the baseline
+
+After a deliberate improvement is confirmed (full corpus run passes with a
+higher success rate), update the baseline:
+
+```bash
+# Re-seed the baseline from the latest full run scorecard:
+node scripts/eval-gate-scorecard.mjs scorecard.json --seed
+
+# Commit the updated baseline:
+git add scripts/eval-gate-baseline.json
+git commit -m "chore(bench): update eval-gate baseline to vN.N"
+```
+
+The `--seed` flag overwrites the baseline file with the fresh scorecard regardless
+of the current baseline content.
+
+**Rule**: never lower the baseline. Only update it upward (higher success rate) or
+after a deliberate scope change to the corpus.
+
+---
+
+## Override / force-merge (false positive procedure)
+
+A false positive is a gate failure where the spec did not regress but the eval run
+produced a low score due to:
+- Flaky sandbox or network issues during the harness run
+- Corpus issue that was already broken before the PR
+- Known harness limitation (#1285 tracking)
+
+**Override procedure**:
+
+1. Confirm the false positive by running the harness locally:
+   ```bash
+   node scripts/eval-harness-runner.mjs --mode full
+   ```
+   If the local run passes, it is likely a CI flake.
+
+2. Re-trigger the workflow from the PR UI: **Re-run failed jobs**.
+
+3. If it still fails and you have confirmed the spec change is safe:
+   - Add a PR comment documenting why the failure is a false positive.
+   - Get a second approver.
+   - Merge with the label `eval-gate:override` on the PR.
+
+4. File a follow-up issue to investigate the false positive root cause.
+
+**Never** skip the gate entirely by editing the workflow YAML in the same PR
+that contains the spec change. That defeats the purpose.
+
+---
+
+## Running on demand (model release)
+
+When a new Claude model is released, run the full corpus to establish a new
+baseline for the model:
+
+1. Trigger via GitHub Actions UI: **Actions → Pipeline Eval Gate → Run workflow**
+2. Select `run_mode: full`.
+3. Download the scorecard artifact.
+4. If the success rate is acceptable, update the baseline:
+   ```bash
+   node scripts/eval-gate-scorecard.mjs <downloaded-scorecard.json> --seed
+   git add scripts/eval-gate-baseline.json
+   git commit -m "chore(bench): rebaseline for claude-<model-version>"
+   ```
+
+---
+
+## Baseline storage rationale
+
+The baseline is committed as `scripts/eval-gate-baseline.json` rather than stored
+in a GitHub Actions cache or release asset. Reasons:
+
+- **Auditable**: every baseline update appears in `git log` and `git blame`.
+- **Reproducible**: a cold clone has everything needed to run the gate.
+- **Diff-visible**: baseline changes show up in PRs, making ratcheting explicit.
+- **No external dependencies**: no cache eviction, no release asset permissions.
+
+The tradeoff is that updating the baseline requires a commit — which is
+intentional. Baseline bumps should be deliberate human decisions, not
+auto-ratcheted by CI.

package/docs/design/show-hn-draft.md

@@ -2,6 +2,17 @@
 
 <!-- Updated by #1092: messaging angles research (2026-06-25) -->
 <!-- Updated by #1099: context-rot pain framing (2026-06-27) -->
+<!-- GATE: #1264 — DO NOT POST until benchmark scorecard is available.
+     Every quantitative efficiency claim must trace to a reproducible benchmark run.
+     Required before posting:
+       1. Land cost accounting (#1255) and topology fix (#1254)
+       2. Run benchmark suite (#1259) and publish scorecard:
+            - cost per issue by difficulty class
+            - one-shot success rate
+            - before/after the optimization wave
+       3. Rewrite the maker comment to lead with the measured table
+          (keep context-rot framing, replace estimates with actuals)
+     See: #1264 -->
 <!-- Research: "LLM Wiki" vocabulary = 17M views / 5K stars (Karpathy gist, April 2026).
      "Context rot" is now mainstream community vocabulary (MindStudio, Augment Code, Stack Overflow, 2025-2026).
      Lead with context rot pain; use LLM Wiki vocabulary as the HN title hook. Full research: docs/design/messaging-angles-research.md -->
@@ -68,7 +79,7 @@ Some technical details:
 
 Known limitations:
 - Claude Code only (no Cursor/Codex/Aider support yet)
-- Token-heavy on first run before adaptive scripts cache project patterns
+- Token-heavy on first run before adaptive scripts cache project patterns <!-- BENCHMARK_NEEDED: replace with measured cost figure from scorecard (#1264) -->
 - The pipeline is opinionated — it enforces a specific workflow that may not fit every team
 
 I'm a solo developer building this to solve my own problems. Happy to answer questions about the architecture, the FORGE annotation protocol, or the prompt engineering behind the command specs.
@@ -84,3 +95,17 @@ I'm a solo developer building this to solve my own problems. Happy to answer que
 - **If compared to Devin**: "Devin is a cloud service; ForgeDock runs locally with your own API key. Different trade-offs — Devin is turnkey, ForgeDock gives you full control and traceability."
 - **If compared to DeepWiki**: "DeepWiki generates a documentation snapshot of your repo. ForgeDock writes structured annotations during each pipeline run — context stays current with your actual work, not a snapshot."
 - **If asked about scale**: Be honest about current adoption. Don't inflate numbers.
+
+---
+
+## Pre-Post Benchmark Gate (#1264)
+
+**Do not submit to HN until all items are checked.**
+
+- [ ] Cost accounting landed (#1255)
+- [ ] Topology fix landed (#1254)
+- [ ] Benchmark suite run (#1259) and scorecard published
+- [ ] Scorecard includes: cost per issue by difficulty class, one-shot success rate, before/after optimization wave
+- [ ] Every quantitative claim in the maker comment above traces to a row in the scorecard
+- [ ] `<!-- BENCHMARK_NEEDED -->` comments in the draft have been replaced with measured figures
+- [ ] Reproducible method documented: demo repo + runner script so readers can re-run the benchmark

package/docs/design/token-cost-baseline-1298.md

@@ -0,0 +1,59 @@
+# Token-cost baseline measurement plan — issue #1298
+
+**Parent**: #1255
+**Depends on**: #1295, #1296, #1297 (tooling), #1246, #1247, #1249, #1254 (optimization PRs)
+
+## Purpose
+
+Close the loop on #1255's "measured, not estimated" savings claim by capturing
+before/after token-cost baselines using `scripts/bench-topology-cost.mjs` around
+the landing of each optimization PR.
+
+## Tooling
+
+`scripts/bench-topology-cost.mjs` — reads a `runs.json` file of per-issue token
+usage records and emits a cost comparison table across pipeline topologies.
+
+Baseline inputs are `FORGE:USAGE_JSON` annotations written to GitHub by the
+pipeline (via `bin/runner.mjs`'s `renderSummaryCard`). Collect them with:
+
+```bash
+# Collect FORGE:USAGE_JSON annotations from the last N issue runs
+gh issue list -R <repo> --state closed --label workflow:merged --limit 20 \
+  --json number,comments \
+  | jq '[.[] | {number: .number, comments: [.comments[].body | select(contains("FORGE:USAGE_JSON"))]}]'
+```
+
+Then feed the extracted token counts into a `runs.json` for `bench-topology-cost.mjs`.
+
+## Measurement gates
+
+Run the corpus (5 seeded issues in `examples/forgedock-demo/`) through the pipeline
+and record token counts **immediately before** and **immediately after** each PR lands:
+
+| Gate | PR | Description |
+|------|----|-------------|
+| Before #1246 | — | Baseline: current skills-format |
+| After #1246  | #1246 | Skills-format migration |
+| After #1247  | #1247 | Single-source FORGE protocol |
+| After #1249  | #1249 | Model/effort tiering (Haiku/xhigh) |
+| After #1254  | #1254 | Agent topology refactor |
+
+## Results
+
+_To be filled in as each dependency PR lands. Record before/after deltas as comments
+on issue #1298 and update this table._
+
+| PR | Topology | Avg input tokens | Avg output tokens | Delta vs prior |
+|----|----------|-----------------|-------------------|----------------|
+| (baseline) | spawned | — | — | — |
+| #1246 | spawned | — | — | — |
+| #1247 | spawned | — | — | — |
+| #1249 | spawned+tiering | — | — | — |
+| #1254 | inline-sequential | — | — | — |
+
+## Status
+
+Dependencies #1246, #1247, #1249, #1254 are all open as of 2026-07-04. Measurements
+cannot be taken until those PRs land. This document serves as the tracking record and
+protocol so that whoever executes the measurements has the exact steps available.

package/docs/eval/README.md

@@ -0,0 +1,117 @@
+# Pipeline Eval — Published Scorecards
+
+Per-release pipeline evaluation results for ForgeDock. Every scorecard here was produced by the eval harness (#1285) running the seeded benchmark corpus (#1284) and aggregated by `scripts/bench-scorecard.mjs`. Scorecards are published following the model-release upgrade playbook (`docs/articles/model-release-playbook.md`).
+
+---
+
+## Current baseline
+
+| Field | Value |
+|-------|-------|
+| Scorecard | [claude-sonnet-4-6-2026-07-04.json](published/claude-sonnet-4-6-2026-07-04.json) |
+| Model | claude-sonnet-4-6 |
+| Corpus | seed-v1 |
+| Run date | 2026-07-04 |
+| One-shot success rate | — (pending harness) |
+| Human-intervention mean | — (pending harness) |
+
+> **Note**: The baseline above is a format placeholder. The harness (#1285) and CI gate (#1286) must be operational before real scorecard values can be populated. When the first real run completes, update this table and remove this note.
+
+---
+
+## Published results
+
+| Run ID | Model | Corpus | Date | One-shot success | Human interventions/issue | Scorecard |
+|--------|-------|--------|------|-----------------|--------------------------|-----------|
+| claude-sonnet-4-6-2026-07-04 | claude-sonnet-4-6 | seed-v1 | 2026-07-04 | pending | pending | [scorecard](published/claude-sonnet-4-6-2026-07-04.json) |
+
+---
+
+## Scorecard schema
+
+Every file in `published/` is a JSON object with the following fields:
+
+```jsonc
+{
+  // Run metadata
+  "run_id": "claude-sonnet-4-6-2026-07-04",       // <model-slug>-<YYYY-MM-DD>
+  "model": "claude-sonnet-4-6",                    // exact model identifier
+  "claude_code_version": "1.x.x",                  // Claude Code version used
+  "corpus_version": "seed-v1",                     // corpus tag from docs/eval/corpus/
+  "run_date": "2026-07-04",                        // ISO 8601 date
+  "n_issues": 20,                                  // total corpus issues attempted
+  "n_completed": 20,                               // issues that reached a terminal state
+
+  // Primary metrics — regression gate checks these
+  "one_shot_success_rate": 0.75,                   // fraction of issues merged without human intervention
+  "human_intervention_count": {
+    "mean": 0.3,                                   // mean interventions per issue
+    "median": 0.0,
+    "p90": 1.0
+  },
+  "wall_clock_seconds": {
+    "mean": 3420,                                  // mean wall-clock per issue (seconds)
+    "median": 3180,
+    "p90": 6000
+  },
+  "cost_per_issue_usd": {
+    "mean": 0.85,
+    "median": 0.72,
+    "p90": 1.40
+  },
+
+  // Per-issue breakdown (array)
+  "issues": [
+    {
+      "issue_id": "corpus-001",
+      "difficulty": "easy",                        // easy | medium | hard
+      "category": "bug",                           // bug | feature | refactor | perf | docs
+      "outcome": "merged",                         // merged | needs-human | failed | timeout
+      "human_interventions": 0,
+      "wall_clock_seconds": 2980,
+      "cost_usd": 0.63
+    }
+    // ... one entry per corpus issue
+  ],
+
+  // Comparison against previous baseline (populated at publish time)
+  "vs_baseline": {
+    "baseline_run_id": null,                       // null if this is the first run
+    "one_shot_success_rate_delta": null,
+    "human_intervention_delta": null,
+    "regressions": []
+  }
+}
+```
+
+---
+
+## Directory layout
+
+```
+docs/eval/
+  README.md                     # this file — published results index
+  corpus/
+    seed-v1.json                # seeded benchmark corpus (20 issues, graded difficulty)
+  published/
+    <run-id>.json               # published scorecard per model release
+  runs/
+    <run-id>/
+      raw.json                  # raw per-issue outcome data from the harness
+      scorecard.json            # aggregated scorecard (bench-scorecard.mjs output)
+```
+
+Raw run data in `runs/` is the source of truth. Published scorecards in `published/` are the canonical record referenced in the playbook and README.
+
+---
+
+## Upgrade decision table
+
+| One-shot success rate delta | Human intervention delta | Decision |
+|-----------------------------|--------------------------|----------|
+| > -5pp | <= +0.5 | Adopt |
+| -5pp to -10pp | any | WARN — investigate |
+| < -10pp | any | BLOCK — regression issue required |
+| any | > +0.5 | BLOCK — regression issue required |
+
+Full decision procedure: `docs/articles/model-release-playbook.md`.

package/docs/eval/corpus/seed-v1.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "PLACEHOLDER — seeded benchmark corpus will be populated by #1284. This file establishes the location and schema.",
+  "version": "seed-v1",
+  "description": "Seeded benchmark corpus for ForgeDock pipeline eval. ~20 issues of graded difficulty across bug/feature/refactor/perf/docs categories.",
+  "issues": []
+}

package/docs/eval/published/claude-sonnet-4-6-2026-07-04.json

@@ -0,0 +1,33 @@
+{
+  "_comment": "PLACEHOLDER — harness (#1285) and CI gate (#1286) are not yet operational. This file establishes the schema and location convention. Replace with a real run when the harness is ready.",
+  "run_id": "claude-sonnet-4-6-2026-07-04",
+  "model": "claude-sonnet-4-6",
+  "claude_code_version": "pending",
+  "corpus_version": "seed-v1",
+  "run_date": "2026-07-04",
+  "n_issues": null,
+  "n_completed": null,
+  "one_shot_success_rate": null,
+  "human_intervention_count": {
+    "mean": null,
+    "median": null,
+    "p90": null
+  },
+  "wall_clock_seconds": {
+    "mean": null,
+    "median": null,
+    "p90": null
+  },
+  "cost_per_issue_usd": {
+    "mean": null,
+    "median": null,
+    "p90": null
+  },
+  "issues": [],
+  "vs_baseline": {
+    "baseline_run_id": null,
+    "one_shot_success_rate_delta": null,
+    "human_intervention_delta": null,
+    "regressions": []
+  }
+}

package/docs/site/annotations-explained.md

@@ -50,6 +50,30 @@ Affected: bin/forgedock.mjs
 
 Read them whenever you want visibility into what your agents are doing. That's the whole point: the work is transparent and auditable, right there in GitHub.
 
+## Attribution Footers (Opt-In)
+
+ForgeDock can optionally append a small attribution line to pipeline-created PRs and visible annotation comments. This is the same mechanic used by Dependabot, Renovate, and CodeRabbit to grow through public repos — consentful and single-key opt-out.
+
+**`attribution.pr_footer: true`** — every pipeline-created PR ends with one muted footer:
+
+```
+> Orchestrated with ForgeDock — state, scheduling, review, and memory on GitHub.
+```
+
+**`attribution.annotation_link: true`** — visible (human-readable) annotation comments in the GitHub UI carry a small "Pipeline powered by ForgeDock" link at the end. Machine-readable `<!-- FORGE:... -->` HTML comments are never modified, regardless of this setting.
+
+Both keys default to disabled. The recommended configuration for public repos is to enable both; for private repos, leave both off.
+
+To configure, add an `attribution:` section to your `forge.yaml`:
+
+```yaml
+attribution:
+  pr_footer: true        # append footer to pipeline-created PRs
+  annotation_link: true  # append link to visible annotation comments
+```
+
+To opt out entirely, set both to `false` or omit the section. No commit messages, git trailers, or machine-readable annotations are ever modified — this applies to PR bodies and visible comments only.
+
 ## Want the Technical Details?
 
 If you're building your own agent pipeline or contributing to ForgeDock, the full machine-readable format — every annotation type, completion markers, and parsing rules — is documented in the [FORGE Annotation Protocol](./forge-annotation-protocol.md).

package/docs/site/command-learning-path.md

@@ -1,14 +1,14 @@
 ---
 title: "ForgeDock Command Learning Path"
-description: "A tiered learning path for ForgeDock's slash commands. Learn the 3 essential commands first, then add team, operations, and pipeline-tuning commands as you need them."
+description: "A tiered learning path for ForgeDock's slash commands. Learn the 3 essential commands first, then add observe-&-recover, ops, and advanced commands as you need them."
 keywords: ["claude code commands guide", "forgedock learning path", "claude code getting started", "which claude code commands to learn", "ai pipeline commands"]
 ---
 
 # Command Learning Path
 
-ForgeDock installs 25+ slash commands. You do **not** need to learn them all. Most of the time you'll use three.
+ForgeDock installs many slash commands. You do **not** need to learn them all. Most of the time you'll use three.
 
-This page tiers every command by *when you need it* — so you can start small and add commands as your workflow grows. For an alphabetical, domain-grouped lookup of every command, see the [Complete Command Reference](./command-reference.md).
+This page tiers every command by *when you need it* — so you can start small and add commands as your workflow grows. For a full domain-grouped lookup of every command, see the [Complete Command Reference](./command-reference.md).
 
 ---
 
@@ -26,7 +26,7 @@ Everything below is optional and additive. Come back when you hit the situation
 
 ---
 
-## Tier 1 — Essential
+## Tier 1 — Core Loop
 
 **When you need this:** Day 1. This is the minimum viable ForgeDock.
 
@@ -35,8 +35,10 @@ Everything below is optional and additive. Come back when you hit the situation
 | `/work-on #N` | Pick up an issue and run the full pipeline: investigate → build → review → merge |
 | `/issue` | Create a well-structured issue the pipeline can consume reliably |
 | `/review-pr` | Review a PR with context-aware, 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 |
 
-With just these three, you can ship a change end-to-end: write an issue, run it, and review the result.
+With just these, you can ship a change end-to-end: write an issue, run it, review the result, and verify it works before it ships.
 
 ---
 
@@ -49,13 +51,31 @@ With just these three, you can ship a change end-to-end: write an issue, run it,
 | `/orchestrate` | Run multiple issues — or an entire milestone — in parallel |
 | `/milestone` | Plan, track, and ship a milestone |
 | `/deploy-info` | See what will deploy next: staging vs. main diff with risk assessment |
-| `/quality-gate` | Run pre-commit quality checks before you push |
+| `/scope` | Estimate issue complexity before committing to `/work-on` |
+| `/adopt` | Bootstrap an existing repo's backlog into pipeline-ready issues |
 
 These commands scale ForgeDock from "one issue at a time" to "a planned body of work moving in parallel."
 
 ---
 
-## Tier 3 — Operations
+## Tier 3 — Observe & Recover
+
+**When you need this:** As soon as you have multiple pipeline runs in flight or your first interrupted run. These are the durable-state commands — the most differentiating part of ForgeDock's architecture.
+
+| 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 |
+
+These commands turn ForgeDock's event-sourced run log and FORGE annotation trail into something you can inspect, recover from, and communicate about — crash-safe pipelines that can always resume, and audit trails that any teammate can read.
+
+---
+
+## Tier 4 — Operations
 
 **When you need this:** When something goes wrong in production, or when you're shipping a release.
 
@@ -64,33 +84,50 @@ These commands scale ForgeDock from "one issue at a time" to "a planned body of
 | `/rollback` | Create a revert PR to roll back a shipped feature or fix |
 | `/incident-response` | Coordinate a P0 incident: hotfix validation, timeline, postmortem |
 | `/security-audit` | Run a periodic security posture audit |
-| `/changelog` | Generate release notes from merged work |
+| `/autopilot` | Autonomous improvement cycle: recon → triage → fix |
+| `/cleanup` | Sweep stale issues, branches, and worktrees |
 
 You'll reach for these occasionally, not daily — but you'll be glad they exist the moment you need them.
 
 ---
 
-## Tier 4 — Pipeline Tuning
+## Tier 5 — Pipeline Tuning
 
 **When you need this:** Advanced. Once ForgeDock is part of your daily workflow and you want to make the pipeline itself faster and smarter.
 
 | Command | What it does |
 |---------|-------------|
-| `/autopilot` | Autonomous improvement cycle: recon → triage → fix |
 | `/pipeline-health` | Self-analysis: measure pipeline performance and propose improvements |
 | `/optimize` | Generate adaptive scripts to speed up repeated pipeline work |
-| `/diagnose` | Debug pipeline failures |
+| `/ci-audit` | Audit CI workflows for missing stack-specific validation checks |
+| `/compat-audit` | Check Claude Code version compatibility with ForgeDock features |
 
 These commands turn ForgeDock on itself — measuring, debugging, and tuning the pipeline you run every day.
 
 ---
 
+## Extras / Project-Specific
+
+**When you need this:** Only if your project is a public web property with analytics platforms (GSC, GA4, Umami, Cloudflare, Stripe, Clarity) configured in `forge.yaml`.
+
+| Command | What it does |
+|---------|-------------|
+| `/analytics` | Pull production analytics from multiple sources and create issues |
+| `/qa-sweep` | Browser-automated QA sweep across your web app (requires Playwright MCP) |
+| `/geo-audit` | Check AI referral traffic and GEO compliance for your pages |
+| `/audit-agents` | Analyze per-agent performance from large `/orchestrate` runs |
+
+These ship with ForgeDock but are not general-purpose pipeline commands. If your project is a backend service, CLI tool, or library, these have nothing to act on.
+
+---
+
 ## How to grow your toolkit
 
-1. **Start with the 3 Essential commands.** Ship one issue end-to-end.
+1. **Start with the Tier 1 commands.** Ship one issue end-to-end.
 2. **Add Tier 2 when you have more than one thing in flight.** Orchestrate a milestone instead of babysitting issues one by one.
-3. **Reach for Tier 3 only when operations demand it** — a bad deploy, an incident, a release.
-4. **Explore Tier 4 once the pipeline is routine** and you want it faster and self-tuning.
+3. **Add Tier 3 when you hit your first interrupted run or want visibility into in-flight work.** These are the observe-and-recover commands — they make the pipeline resilient and readable.
+4. **Reach for Tier 4 only when operations demand it** — a bad deploy, an incident, a release.
+5. **Explore Tier 5 once the pipeline is routine** and you want it faster and self-tuning.
 
 You never have to memorize the full command set. Learn the next tier the day you need it.