forgedock 1.0.1 → 1.0.2

package/docs/CONFIG.md

@@ -0,0 +1,398 @@
+# forge.yaml Configuration Reference
+
+`forge.yaml` is placed at your project root and tells ForgeDock commands how to interact with your specific project. Without it, commands cannot resolve your GitHub repository, paths, or branches.
+
+## Quick Start
+
+```bash
+cp forge.yaml.example forge.yaml
+# Edit forge.yaml with your project details
+echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
+```
+
+---
+
+## 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 |
+| [`verification`](#verification-optional) | No | Health-check patterns |
+| [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
+
+---
+
+## `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"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | **Yes** | Human-readable name used in pipeline reports and issue comments |
+| `owner` | string | **Yes** | GitHub org or username. Used as `GH_REPO` prefix and `--owner` flag |
+| `repo` | string | **Yes** | Repository name. Combined: `owner/repo` = the `GH_REPO` value in all commands |
+| `description` | string | No | One-line description used in issue templates |
+| `forge_repo` | string | No | Pipeline repository in `owner/repo` format. Set this when your ForgeDock pipeline lives in a different repo than the project being developed. Used by `audit.md`, `audit-agents.md`, and `security-audit.md` to resolve `{FORGE_REPO}` when looking up pipeline issues and commands. Defaults to `project.owner/project.repo` if omitted. |
+
+**Commands that use this section**: `work-on`, `review-pr`, `orchestrate`, `issue`, `milestone`, `cleanup`, `audit`, `audit-agents`, `security-audit`, `pipeline-health`
+
+---
+
+## `paths` (REQUIRED)
+
+Local filesystem paths. Commands use these to locate the project, create git worktrees, and read credential files.
+
+```yaml
+paths:
+  root: "/home/youruser/projects/acme-platform"
+  worktree_base: "/home/youruser/projects/acme-platform/.claude/worktrees"
+  # credentials:
+  #   file: "/home/youruser/credentials.yaml"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `root` | string (absolute path) | **Yes** | Absolute path to the project root. Used as the base for `git worktree add` |
+| `worktree_base` | string (absolute path) | **Yes** | Directory where per-branch git worktrees are created. Default: `{root}/.claude/worktrees` |
+| `credentials.file` | string (absolute path) | No | Path to a YAML credentials file for analytics/monitoring tools. **Do not commit.** |
+
+**Commands that use this section**: `work-on` (Phase 3E), `quality-gate`, `deploy-info`
+
+---
+
+## `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`). Used as fallback PR base |
+| `staging` | string | **Yes** | Staging branch for fast-lane PRs (issues without a milestone). Set to `main` if you have no staging branch |
+| `feature_pattern` | string | **Yes** | Pattern for feature branches. `{slug}` is the milestone title in kebab-case. Example: `milestone/{slug}` → `milestone/user-auth-v2` |
+
+**Lane routing logic** (from `work-on.md`):
+- Issue has no milestone → fast lane → PR targets `branches.staging`
+- Issue has milestone → feature lane → PR targets branch matching `branches.feature_pattern`
+
+**Commands that use this section**: `work-on`, `review-pr`, `cleanup`
+
+---
+
+## `repos` (OPTIONAL)
+
+Multi-repository routing. Use this when your project spans multiple GitHub repositories and you want to route issues to satellite repos by prefix.
+
+Without this section, all issues route to `project.owner/project.repo`.
+
+```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"
+
+    - prefix: "sdk"
+      repo: "acme-org/acme-python-sdk"
+      staging_branch: "main"
+      local_path: "/home/youruser/projects/acme-python-sdk"
+      # billing_enabled: false  # set true to run /security-audit Phase 4 on this repo
+
+    # Monorepo satellite: multiple packages in one repo.
+    # subpaths maps named identifiers to per-package root directories
+    # relative to local_path. Used by /sync-ecosystem when the repo
+    # contains multiple independently published packages.
+    - prefix: "mono"
+      repo: "acme-org/acme-sdks"
+      staging_branch: "main"
+      local_path: "/home/youruser/projects/acme-sdks"
+      subpaths:
+        python_sdk: "sdk/python"
+        node_sdk: "sdk/node"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `default.repo` | string | No | Full `owner/repo` of the primary repo. Should match `project.owner/project.repo` |
+| `default.staging_branch` | string | No | Staging branch for the default repo |
+| `satellites[].prefix` | string | **Yes (per entry)** | Short prefix used in issue routing (e.g., `mcp:5` routes issue 5 to the MCP server repo) |
+| `satellites[].repo` | string | **Yes (per entry)** | Full `owner/repo` of the satellite repository |
+| `satellites[].staging_branch` | string | **Yes (per entry)** | Target branch for fast-lane PRs in this repo |
+| `satellites[].local_path` | string | No | Absolute local path to the satellite repo's checkout |
+| `satellites[].subpaths` | map(string→string) | No | Named sub-directory paths within `local_path`, for monorepo satellites that publish multiple packages. Each key is a logical name; the value is the relative path to that package's root. Used by `/sync-ecosystem` to locate per-package version files and publish workflows. |
+| `satellites[].billing_enabled` | boolean | No | Set to `true` to run Phase 4 (Financial Integrity) of `/security-audit` against this satellite repo. Mirrors the top-level [`billing.enabled`](#billing-optional) flag but scoped per-satellite. Defaults to `false` when absent. |
+
+**Routing syntax in commands**: `<prefix>:<issue_number>` — e.g., `mcp:5`, `sdk:12`
+
+**Commands that use this section**: `work-on` (multi-repo prefix table), `sync-ecosystem`, `security-audit` (satellite billing audit)
+
+---
+
+## `project_board` (OPTIONAL)
+
+GitHub Projects v2 integration. When configured, ForgeDock automatically adds issues to the project board and updates Status, Lane, Component, Priority, and Workflow fields as issues progress through the pipeline.
+
+```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"
+      sync: "xxxxxxxx"
+    priority:
+      p0: "xxxxxxxx"
+      p1: "xxxxxxxx"
+      p2: "xxxxxxxx"
+      p3: "xxxxxxxx"
+    workflow:
+      investigating: "xxxxxxxx"
+      building: "xxxxxxxx"
+      in_review: "xxxxxxxx"
+      merged: "xxxxxxxx"
+
+  components:
+    - repo: "acme-org/acme-platform"
+      option_id: "xxxxxxxx"
+      label: "Platform"
+```
+
+### Finding Your IDs
+
+```bash
+# List projects and their numbers/IDs
+gh project list --owner <owner> --format json | jq '.projects[] | {number, id, title}'
+
+# List field IDs for a project
+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[]'
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `owner` | string | **Yes** | GitHub org/user that owns the project board |
+| `project_number` | integer | **Yes** | Project number visible in the URL (`/projects/1`) |
+| `project_id` | string | **Yes** | GraphQL node ID (`PVT_...`) returned by `gh project list` |
+| `field_ids.*` | string | **Yes (per field)** | `PVTSSF_...` IDs for each custom field |
+| `option_ids.*.*` | string | **Yes (per option)** | 8-char hex IDs for each single-select option |
+| `components` | array | No | Maps `owner/repo` values to Component field option IDs |
+
+**Commands that use this section**: `work-on` (Phase 0C, Phase 6B), `orchestrate`
+
+---
+
+## `services` (OPTIONAL)
+
+External service endpoints and identifiers. Used by analytics and monitoring commands.
+
+```yaml
+services:
+  domain: "acme.io"
+  gsc_property: "https://acme.io"
+
+  analytics:
+    umami:
+      url: "https://umami.acme.io"
+      website_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    clarity:
+      project_id: "xxxxxxxxxx"
+    history_file: "/home/youruser/analytics-history.yaml"
+    ga4:
+      property_id: "000000000"
+      service_account_key: "/home/youruser/credentials/ga4-service-account.json"
+
+  app_url: "https://acme.io"
+  api_url: "https://api.acme.io"
+
+  # server_ssh: "ubuntu@203.0.113.42"
+  # ememo_path: "/home/ubuntu/ememo"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `domain` | string | No | Primary public domain. Used in GEO and SEO checks |
+| `gsc_property` | string | No | Google Search Console property URL or `domain:` prefix |
+| `analytics.umami.url` | string | No | Base URL for Umami self-hosted analytics instance |
+| `analytics.umami.website_id` | string | No | Umami website UUID for metric queries |
+| `analytics.clarity.project_id` | string | No | Microsoft Clarity project identifier |
+| `analytics.history_file` | string (absolute path) | No | Path to the persistent audit history YAML file. Written after each `/analytics` run; provides trend baselines. Do not commit. |
+| `analytics.ga4.property_id` | string | No | Numeric Google Analytics 4 property ID (from GA4 Admin → Property Details) |
+| `analytics.ga4.service_account_key` | string (absolute path) | No | Path to a GA4 service account JSON key file. Grant the account Viewer access in GA4. Do not commit. |
+| `app_url` | string | No | Frontend app URL used by `qa-sweep` for page accessibility testing. Default: `http://localhost:3000` |
+| `api_url` | string | No | Base URL for the project's API. Used in health checks |
+| `server_ssh` | string | No | SSH target for production server health checks. Format: `user@host` (e.g., `ubuntu@203.0.113.42`). Used by `/autopilot` Phase 1 to run server-level checks over SSH. |
+| `ememo_path` | string | No | Absolute path on the production server to open eMemo files. Used by `/autopilot` to surface in-progress work notes. Only relevant if your team uses eMemo. |
+
+**Commands that use this section**: `analytics`, `geo-audit`, `autopilot` (analytics snapshot, SSH health check)
+
+---
+
+## `review` (OPTIONAL)
+
+Context injected into review agent prompts. Helps the 9-agent review system give relevant, project-specific feedback.
+
+```yaml
+review:
+  tech_stack: "Next.js 15 App Router, FastAPI, PostgreSQL 16, Docker, Traefik"
+
+  context: |
+    Multi-service monorepo: services/api (Python/FastAPI), web/ (Next.js).
+    Deploy: blue/green via Docker Compose on a single VPS behind Traefik.
+    Database: PostgreSQL with async SQLAlchemy. No ORM migrations — raw SQL.
+
+  domains:
+    billing: "Stripe webhooks; idempotency keys required on all handlers"
+    auth: "JWT + refresh token rotation; sessions stored in Redis"
+    database: "Always use docker exec <container> for psql/migrations"
+
+  # key_paths:
+  #   auth: ["services/api/auth/**", "web/src/lib/auth/**"]
+  #   billing: ["services/api/billing/**", "web/src/app/billing/**"]
+  #   database: ["services/api/db/**", "migrations/**"]
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `tech_stack` | string | No | One-line tech stack summary. Injected into all review agent prompts |
+| `context` | string (multiline) | No | Freeform context about architecture, deploy model, and known pitfalls |
+| `domains.*` | string | No | Domain-specific notes keyed by review agent name (`billing`, `auth`, `database`, `frontend`, `api`, `infra`, `security`) |
+| `key_paths` | map(string→list of strings) | No | Domain-to-file mapping used by `/work-on` investigation and `/review-pr` agents to quickly locate relevant files. Keys are domain names matching issue labels; values are lists of file path patterns (glob-style, relative to repo root). When present, agents use this table instead of inferring files from labels and issue body. |
+
+**Commands that use this section**: `review-pr`, `review-pr-agents` (all domain agents), `work-on` (Phase 1B investigation)
+
+---
+
+## `verification` (OPTIONAL)
+
+Service health-check patterns for the quality gate and validate commands.
+
+```yaml
+verification:
+  health_endpoint: "https://api.acme.io/health"
+
+  health_patterns:
+    - '"status": "ok"'
+    - '"database": "connected"'
+
+  services:
+    - name: "api"
+      container: "acme-api-blue"
+      health_url: "http://localhost:8000/health"
+    - name: "web"
+      container: "acme-web-blue"
+      health_url: "http://localhost:3000"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `health_endpoint` | string | No | Primary health-check URL that should return HTTP 200 |
+| `health_patterns` | array of strings | No | Strings that must appear in the health endpoint response body |
+| `services` | array | No | Named services to verify as part of deployment validation |
+| `services[].name` | string | **Yes (per entry)** | Human-readable service name |
+| `services[].container` | string | No | Docker container name for `docker exec` verification |
+| `services[].health_url` | string | No | Local URL for container-level health checks |
+
+**Commands that use this section**: `quality-gate`, `validate`
+
+---
+
+## Credentials File Format
+
+If `paths.credentials.file` is set, the file at that path is expected to be a YAML file with this structure:
+
+```yaml
+# credentials.yaml — DO NOT COMMIT
+umami:
+  username: "admin"
+  password: "your-password"
+
+cloudflare:
+  api_token: "your-cf-token"
+  zone_id: "your-zone-id"
+
+# QA test user credentials — read by /qa-sweep for browser-based authentication
+qa:
+  username: "test@example.com"
+  password: "your-test-password"
+
+# Add other service credentials as needed
+```
+
+The credentials file is read directly by analytics and monitoring commands. It is never committed — add it to `.gitignore`.
+
+---
+
+## `billing` (OPTIONAL)
+
+Controls whether financial integrity checks run in `/security-audit`. Only relevant for projects with Stripe or similar billing infrastructure. When omitted or set to `false`, Phase 4 (Financial Integrity) of the security audit is skipped.
+
+```yaml
+billing:
+  enabled: false
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | boolean | No | `false` | Set to `true` to enable Phase 4 (Financial Integrity) in `/security-audit`. When `false`, the billing audit phase is skipped — appropriate for projects that do not process payments or have no Stripe integration. |
+
+**Commands that use this section**: `security-audit` (Phase 4 — Financial Integrity)
+
+---
+
+## Config Reading Conventions
+
+ForgeDock commands use two accepted patterns for reading `forge.yaml`:
+
+- **`yq` (standard)**: Simple field reads use `yq '.section.field // ""' forge.yaml 2>/dev/null || echo ""`. This is the canonical pattern used by the majority of commands (`cleanup`, `orchestrate`, `work-on/close`, etc.).
+- **Python `yaml.safe_load` (complex extraction)**: Commands that need to extract many fields from optional nested sections in a single pass (e.g., `analytics`, `geo-audit`, `qa-sweep`) use a Python heredoc. This avoids chaining many `yq` calls and allows structured error messaging when optional sections are absent.
+
+Do **not** mix the two patterns for the same block of variables (e.g., `yq` with Python fallback). If a command needs more than 5 fields from a deeply nested optional section, use Python. Otherwise, use `yq`.
+
+---
+
+## Complete Example
+
+See [`forge.yaml.example`](../forge.yaml.example) at the repository root for a fully annotated example covering all sections.

package/docs/WORKFLOW.md

@@ -1,104 +1,147 @@
 # Workflow Reference
 
-Canonical reference for field IDs, option IDs, and integration constants used by Forge commands.
+Canonical reference for configuring and querying the GitHub Projects v2 field IDs and option IDs used by ForgeDock commands.
 
 ---
 
 ## Project Board Integration
 
-**Project ID**: `PVT_kwHOCx3gR84BSK2L`
+ForgeDock commands add issues to a GitHub Projects v2 board and update fields (Status, Lane, Component, Priority, Workflow) as issues move through the pipeline.
 
-All commands that add issues to the GitHub Project board use the field and option IDs below.
-Reference this document rather than hardcoding values inline.
+**All board IDs are project-specific.** You cannot reuse IDs from another project. Use the discovery commands below to find yours, or run `/forgedock-init` which does this automatically.
 
-### Field IDs
+---
 
-| Field | Field ID |
-|-------|----------|
-| Status | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E` |
-| Lane | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF98` |
-| Component | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o` |
-| Priority | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o` |
-| Workflow | `PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA` |
+## Configuration
+
+Project board IDs are stored in `forge.yaml` under the `project_board` section. See [`docs/CONFIG.md`](CONFIG.md#project_board-optional) for the full schema.
+
+```yaml
+project_board:
+  owner: "your-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"
+      sync: "xxxxxxxx"
+    priority:
+      p0: "xxxxxxxx"
+      p1: "xxxxxxxx"
+      p2: "xxxxxxxx"
+      p3: "xxxxxxxx"
+    workflow:
+      investigating: "xxxxxxxx"
+      building: "xxxxxxxx"
+      in_review: "xxxxxxxx"
+      merged: "xxxxxxxx"
+
+  components:
+    - repo: "your-org/your-repo"
+      option_id: "xxxxxxxx"
+      label: "Platform"
+```
 
-### Status Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E`)
+---
 
-| Value | Option ID |
-|-------|-----------|
-| Todo | `f75ad846` |
-| In Progress | _(query live if needed)_ |
-| Done | `98236657` |
+## Finding Your IDs
 
-### Lane Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF98`)
+### Step 1 — Find your project number and project ID
 
-| Value | Option ID |
-|-------|-----------|
-| Fast | `62864af4` |
-| Feature | `4ff6f9e6` |
-| Sync | `c0c37d33` |
+```bash
+# List all projects owned by your org or user
+gh project list --owner <your-org-or-username> --format json \
+  | jq '.projects[] | {number: .number, id: .id, title: .title}'
+```
 
-### Component Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o`)
+The `id` value is your `project_id` (`PVT_...`). The `number` is used in all subsequent queries.
 
-| Value | Option ID | Repo |
-|-------|-----------|------|
-| Platform | `214c4d65` | `RapierCraft/AlterLab` |
-| MCP Server | _(query live if needed)_ | `RapierCraft/alterlab-mcp-server` |
-| n8n Node | _(query live if needed)_ | `RapierCraft/n8n-nodes-alterlab` |
-| Python SDK | _(query live if needed)_ | `RapierCraft/alterlab-python` |
-| Node SDK | _(query live if needed)_ | `RapierCraft/alterlab-node` |
+### Step 2 — List field IDs
 
-### Priority Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o`)
+```bash
+gh project field-list <project_number> --owner <your-org-or-username> --format json \
+  | jq '.fields[] | {name: .name, id: .id}'
+```
 
-| Value | Option ID |
-|-------|-----------|
-| P0 | _(query live if needed)_ |
-| P1 | _(query live if needed)_ |
-| P2 | `4d95eef3` |
-| P3 | _(query live if needed)_ |
+Each field's `id` value (`PVTSSF_...`) maps to a key under `field_ids` in your `forge.yaml`.
 
-### Workflow Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA`)
+### Step 3 — List option IDs for single-select fields
 
-| Value | Option ID |
-|-------|-----------|
-| Investigating | _(query live if needed)_ |
-| Building | _(query live if needed)_ |
-| In Review | _(query live if needed)_ |
-| Merged | `b510c537` |
+```bash
+# Get all options for a specific field (e.g. Status)
+gh project field-list <project_number> --owner <your-org-or-username> --format json \
+  | jq '.fields[] | select(.name == "Status") | .options[] | {name: .name, id: .id}'
+```
 
-### Usage Pattern
+Repeat for each field (Lane, Priority, Workflow, Component). The 8-character hex IDs are your `option_ids` values.
 
-```bash
-# Add issue to project board and set initial fields
-ITEM_ID=$(gh project item-add PVT_kwHOCx3gR84BSK2L --owner RapierCraft --url "$ISSUE_URL" --format json --jq '.id')
+---
+
+## Automated Setup
+
+Running `/forgedock-init` in Claude Code walks you through the full setup interactively: it queries your project board, extracts all field and option IDs, and writes them to `forge.yaml` automatically.
+
+---
 
-# Set Status=Todo
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id f75ad846 2>/dev/null || true
+## Usage Pattern
 
-# Set Lane (Fast=62864af4, Feature=4ff6f9e6, Sync=c0c37d33)
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF98 --single-select-option-id 62864af4 2>/dev/null || true
+Once IDs are in `forge.yaml`, ForgeDock reads them at runtime. The pattern used by commands:
 
-# Set Component=Platform
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o --single-select-option-id 214c4d65 2>/dev/null || true
+```bash
+# Add issue to project board
+ITEM_ID=$(gh project item-add <project_id> --owner <owner> --url "$ISSUE_URL" \
+  --format json --jq '.id')
+
+# Set Status field
+gh project item-edit --project-id <project_id> --id "$ITEM_ID" \
+  --field-id <status_field_id> --single-select-option-id <todo_option_id> \
+  2>/dev/null || true
 
-# Set Priority (P2=4d95eef3)
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o --single-select-option-id 4d95eef3 2>/dev/null || true
+# Set Lane field
+gh project item-edit --project-id <project_id> --id "$ITEM_ID" \
+  --field-id <lane_field_id> --single-select-option-id <fast_option_id> \
+  2>/dev/null || true
 
 # On merge: set Status=Done and Workflow=Merged
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id 98236657 2>/dev/null || true
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA --single-select-option-id b510c537 2>/dev/null || true
+gh project item-edit --project-id <project_id> --id "$ITEM_ID" \
+  --field-id <status_field_id> --single-select-option-id <done_option_id> \
+  2>/dev/null || true
+gh project item-edit --project-id <project_id> --id "$ITEM_ID" \
+  --field-id <workflow_field_id> --single-select-option-id <merged_option_id> \
+  2>/dev/null || true
 ```
 
-### Querying Unknown Option IDs
+All `<placeholder>` values come from your `forge.yaml` — commands read `forge.yaml` and substitute them at runtime.
 
-For option IDs marked "_(query live if needed)_", use:
+---
 
-```bash
-gh project field-list PVT_kwHOCx3gR84BSK2L --owner RapierCraft --format json \
-  --jq '.fields[] | select(.name == "Status") | .options'
-```
+## Adding a Component Field
+
+The Component field maps each repository in your project to a selectable option. For each repo you track:
+
+1. Create a single-select option in your GitHub project's Component field (via the project UI)
+2. Query the new option's ID:
+   ```bash
+   gh project field-list <project_number> --owner <owner> --format json \
+     | jq '.fields[] | select(.name == "Component") | .options[]'
+   ```
+3. Add an entry under `components` in `forge.yaml`:
+   ```yaml
+   components:
+     - repo: "your-org/your-repo"
+       option_id: "xxxxxxxx"
+       label: "Platform"
+   ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"