forgedock 1.0.0 → 1.0.2

package/commands/analytics.md

@@ -14,15 +14,91 @@ You are the analytics orchestrator. Pull data from ALL available analytics platf
 
 ---
 
+## Config Preamble (REQUIRED — run before anything else)
+
+**Before any data collection, credentials access, or phase execution**, read `forge.yaml` from the project root and resolve all constants. If the config is missing or incomplete, stop and tell the user what to add.
+
+```bash
+# Locate forge.yaml (project root = directory containing the forge.yaml file)
+FORGE_YAML="${FORGE_CONFIG:-$(git rev-parse --show-toplevel 2>/dev/null)/forge.yaml}"
+
+if [ ! -f "$FORGE_YAML" ]; then
+  echo "ERROR: forge.yaml not found at $FORGE_YAML"
+  echo ""
+  echo "The /analytics command requires forge.yaml to be configured."
+  echo "Run: cp forge.yaml.example forge.yaml"
+  echo "Then fill in the required sections (project, paths, branches) and the"
+  echo "optional services.analytics section for this command."
+  exit 1
+fi
+
+# Read config with Python (YAML parser — values are shell-quoted via shlex.quote)
+ANALYTICS_CONFIG=$(python3 -c "
+import yaml, sys, shlex
+cfg = yaml.safe_load(open(sys.argv[1]))
+svc = cfg.get('services', {})
+analytics = svc.get('analytics', None)
+if analytics is None:
+    print('MISSING_ANALYTICS_CONFIG')
+    sys.exit(0)
+paths = cfg.get('paths', {})
+creds = paths.get('credentials', {})
+project = cfg.get('project', {})
+board = cfg.get('project_board', {})
+print('CREDENTIALS_FILE=' + shlex.quote(str(creds.get('file', ''))))
+print('DOMAIN=' + shlex.quote(str(svc.get('domain', ''))))
+print('SITE_URL=' + shlex.quote(str(svc.get('gsc_property', ''))))
+print('HISTORY_FILE=' + shlex.quote(str(analytics.get('history_file', ''))))
+print('UMAMI_URL=' + shlex.quote(str(analytics.get('umami', {}).get('url', ''))))
+print('UMAMI_WEBSITE_ID=' + shlex.quote(str(analytics.get('umami', {}).get('website_id', ''))))
+print('GA4_PROPERTY_ID=' + shlex.quote(str(analytics.get('ga4', {}).get('property_id', ''))))
+print('GA4_SERVICE_ACCOUNT_KEY=' + shlex.quote(str(analytics.get('ga4', {}).get('service_account_key', ''))))
+print('REPO_PATH=' + shlex.quote(str(cfg.get('paths', {}).get('root', ''))))
+print('GH_REPO=' + shlex.quote(str(project.get('owner', '')) + '/' + str(project.get('repo', ''))))
+print('PROJECT_BOARD_OWNER=' + shlex.quote(str(board.get('owner', project.get('owner', '')))))
+print('PROJECT_NUMBER=' + shlex.quote(str(board.get('project_number', ''))))
+print('PROJECT_ID=' + shlex.quote(str(board.get('project_id', ''))))
+" "$FORGE_YAML")
+
+if echo "$ANALYTICS_CONFIG" | grep -q "MISSING_ANALYTICS_CONFIG"; then
+  echo "ERROR: forge.yaml is missing the 'services.analytics' section."
+  echo ""
+  echo "Add the following to your forge.yaml to use /analytics:"
+  echo ""
+  echo "  services:"
+  echo "    domain: \"your-domain.com\""
+  echo "    gsc_property: \"https://your-domain.com\""
+  echo "    analytics:"
+  echo "      history_file: \"/path/to/analytics-history.yaml\""
+  echo "      umami:"
+  echo "        url: \"https://umami.your-domain.com\""
+  echo "        website_id: \"your-umami-website-id\""
+  echo "      ga4:"
+  echo "        property_id: \"your-ga4-property-id\""
+  echo "        service_account_key: \"/path/to/ga4-service-account.json\""
+  echo ""
+  echo "See docs/CONFIG.md for the full services.analytics schema."
+  exit 1
+fi
+
+# Export resolved constants — all downstream phases use these variables
+# Values are shell-quoted by the Python block above; eval is safe against metacharacters in forge.yaml values
+eval "$ANALYTICS_CONFIG"
+```
+
+All downstream phases use these resolved constants: `{CREDENTIALS_FILE}`, `{DOMAIN}`, `{SITE_URL}`, `{HISTORY_FILE}`, `{UMAMI_URL}`, `{UMAMI_WEBSITE_ID}`, `{GA4_PROPERTY_ID}`, `{GA4_SERVICE_ACCOUNT_KEY}`, `{REPO_PATH}`, `{GH_REPO}`.
+
+---
+
 ## Credentials
 
-**ALL credentials live in one file**: `/home/mrdubey/projects/ScraperAPI/credentials.yaml`
+**ALL credentials live in one file** at the path resolved from `forge.yaml → paths.credentials.file` (`{CREDENTIALS_FILE}`).
 
 Agents MUST read this file for API keys, tokens, and login creds. Do NOT grep SOPS, do NOT hardcode tokens, do NOT look in `.mcp.json`.
 
 ```bash
 # Read any credential:
-python3 -c "import yaml; creds=yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml')); print(creds['section']['key'])"
+python3 -c "import yaml; creds=yaml.safe_load(open('{CREDENTIALS_FILE}')); print(creds['section']['key'])"
 ```
 
 ---
@@ -30,16 +106,17 @@ python3 -c "import yaml; creds=yaml.safe_load(open('/home/mrdubey/projects/Scrap
 ## Constants
 
 ```
-CREDENTIALS_FILE = "/home/mrdubey/projects/ScraperAPI/credentials.yaml"
-SITE_URL = "sc-domain:alterlab.io"
-DOMAIN = "alterlab.io"
+CREDENTIALS_FILE = {forge.yaml → paths.credentials.file}
+SITE_URL         = {forge.yaml → services.gsc_property}
+DOMAIN           = {forge.yaml → services.domain}
+HISTORY_FILE     = {forge.yaml → services.analytics.history_file}
 TODAY = (current date in YYYY-MM-DD)
 SEVEN_DAYS_AGO = (TODAY minus 7 days)
 TWENTY_EIGHT_DAYS_AGO = (TODAY minus 28 days)
 SEO_RECENT_CHANGE_DAYS = 30
 ```
 
-All platform-specific constants (project IDs, zone IDs, API keys, base URLs) are in `credentials.yaml` — read them from there.
+All platform-specific constants (project IDs, zone IDs, API keys, base URLs) are in `{CREDENTIALS_FILE}` — read them from there.
 
 ---
 
@@ -48,18 +125,18 @@ All platform-specific constants (project IDs, zone IDs, API keys, base URLs) are
 **Before any data collection**, read the persistent audit history file. This gives you a multi-run baseline for trend analysis and tells you what issues were created in past audits so you can measure their impact and avoid duplicates.
 
 ```bash
-HISTORY_FILE="/home/mrdubey/projects/ScraperAPI/analytics-history.yaml"
+HISTORY_FILE="{HISTORY_FILE}"
 
 if [ -f "$HISTORY_FILE" ]; then
   HISTORY_AVAILABLE=true
-  # Read last 5 audit snapshots (Python for YAML parsing — same pattern as credentials.yaml)
+  # Read last 5 audit snapshots (Python for YAML parsing — same pattern as credentials file)
   python3 -c "
-import yaml, json
-history = yaml.safe_load(open('$HISTORY_FILE')) or []
+import yaml, json, sys
+history = yaml.safe_load(open(sys.argv[1])) or []
 # Keep only last 5 entries
 recent = history[-5:] if len(history) >= 5 else history
 print(json.dumps(recent, indent=2))
-"
+" "$HISTORY_FILE"
 else
   HISTORY_AVAILABLE=false
   echo 'First audit — no historical baseline. History file will be created at end of this run.'
@@ -83,7 +160,7 @@ Launch ALL 7 data collection agents simultaneously using `run_in_background=true
 
 Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 
-**Mission**: Collect Google Search Console data for alterlab.io. Use the MCP GSC tools directly.
+**Mission**: Collect Google Search Console data for `{DOMAIN}`. Use the MCP GSC tools directly.
 
 **Queries to run:**
 
@@ -95,7 +172,7 @@ Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 6. **Quick wins** — `mcp__gsc__detect_quick_wins` with minImpressions: 30, positionRangeMin: 4, positionRangeMax: 20, maxCtr: 3
 7. **Previous 28 days** (for trend comparison) — same query/page queries but for the prior period
 
-All queries use `siteUrl: "sc-domain:alterlab.io"`.
+All queries use `siteUrl: "{SITE_URL}"`.
 
 **Return**: Total clicks, impressions, avg CTR, avg position (current + previous + % change). Top 20 queries and pages. Quick wins list. Device/country splits. Rising and declining queries.
 
@@ -133,14 +210,14 @@ Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 
 **Mission**: Collect Umami analytics via REST API.
 
-**Auth**: Read credentials from `credentials.yaml` (under `umami:`), then authenticate:
+**Auth**: Read credentials from `{CREDENTIALS_FILE}` (under `umami:`), then authenticate:
 ```bash
 # Read umami creds
-python3 -c "import yaml; c=yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml')); print(c['umami']['username'], c['umami']['password'])"
-# Login: POST https://umami.alterlab.io/api/auth/login with {"username": "...", "password": "..."}
+python3 -c "import yaml; c=yaml.safe_load(open('{CREDENTIALS_FILE}')); print(c['umami']['username'], c['umami']['password'])"
+# Login: POST {UMAMI_URL}/api/auth/login with {"username": "...", "password": "..."}
 ```
 
-**Queries** (all use website ID `ccfb1cdd-5a05-4b41-8e61-48695b4ff6c0`, last 28 days):
+**Queries** (all use website ID `{UMAMI_WEBSITE_ID}`, last 28 days):
 - `/api/websites/{id}/stats` — overall stats
 - `/api/websites/{id}/pageviews?unit=day` — daily trend
 - `/api/websites/{id}/metrics?type=url` — top pages
@@ -160,13 +237,13 @@ Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 
 **Mission**: Collect Cloudflare traffic/performance data via GraphQL API.
 
-**Auth**: Read from `credentials.yaml`:
+**Auth**: Read from `{CREDENTIALS_FILE}`:
 ```bash
-CF_TOKEN=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml'))['cloudflare']['api_token'])")
-CF_ZONE=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml'))['cloudflare']['zone_id'])")
+CF_TOKEN=$(python3 -c "import yaml; print(yaml.safe_load(open('{CREDENTIALS_FILE}'))['cloudflare']['api_token'])")
+CF_ZONE=$(python3 -c "import yaml; print(yaml.safe_load(open('{CREDENTIALS_FILE}'))['cloudflare']['zone_id'])")
 ```
 
-**GraphQL queries** (zone from `credentials.yaml → cloudflare.zone_id`, last 7 days):
+**GraphQL queries** (zone from `{CREDENTIALS_FILE} → cloudflare.zone_id`, last 7 days):
 1. HTTP requests daily — requests, pageViews, bytes, cachedBytes, threats, countryMap, uniques
 2. Status code breakdown — responseStatusMap
 3. Threats/bot traffic — threatPathingMap
@@ -181,17 +258,17 @@ CF_ZONE=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/proj
 
 Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 
-**Mission**: Collect Bing Webmaster Tools data for alterlab.io via REST API. Bing powers ChatGPT search, so Bing indexing/ranking data = AI discoverability signal.
+**Mission**: Collect Bing Webmaster Tools data for `{DOMAIN}` via REST API. Bing powers ChatGPT search, so Bing indexing/ranking data = AI discoverability signal.
 
-**Auth**: Read from `credentials.yaml`:
+**Auth**: Read from `{CREDENTIALS_FILE}`:
 ```bash
-BING_KEY=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml'))['bing_webmaster']['api_key'])")
-BING_SITE=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml'))['bing_webmaster']['site_url'])")
-BING_BASE=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml'))['bing_webmaster']['api_base'])")
+BING_KEY=$(python3 -c "import yaml; print(yaml.safe_load(open('{CREDENTIALS_FILE}'))['bing_webmaster']['api_key'])")
+BING_SITE=$(python3 -c "import yaml; print(yaml.safe_load(open('{CREDENTIALS_FILE}'))['bing_webmaster']['site_url'])")
+BING_BASE=$(python3 -c "import yaml; print(yaml.safe_load(open('{CREDENTIALS_FILE}'))['bing_webmaster']['api_base'])")
 ```
 
 **Auth method**: Query param `?apikey={BING_KEY}`
-**Site URL**: URL-encode site_url as `https%3A%2F%2Falterlab.io` in siteUrl param
+**Site URL**: URL-encode the site_url value from `{CREDENTIALS_FILE} → bing_webmaster.site_url` in siteUrl param
 
 **Queries to run:**
 
@@ -233,20 +310,20 @@ Launch as a background Agent (subagent_type: general-purpose, model: sonnet):
 
 **Auth**: JWT-based service account authentication:
 ```bash
-# Service account key at:
-SA_KEY="/home/mrdubey/projects/ScraperAPI/credentials/ga4-service-account.json"
-GA4_PROPERTY_ID="522967190"
+# Service account key and property ID resolved from forge.yaml:
+SA_KEY="{GA4_SERVICE_ACCOUNT_KEY}"
+GA4_PROPERTY_ID="{GA4_PROPERTY_ID}"
 
 # Generate JWT and exchange for access token:
 python3 -c "
-import json, time, jwt, requests
-sa = json.load(open('$SA_KEY'))
+import json, sys, time, jwt, requests
+sa = json.load(open(sys.argv[1]))
 now = int(time.time())
 payload = {'iss': sa['client_email'], 'scope': 'https://www.googleapis.com/auth/analytics.readonly', 'aud': sa['token_uri'], 'iat': now, 'exp': now + 3600}
 signed = jwt.encode(payload, sa['private_key'], algorithm='RS256')
 token = requests.post(sa['token_uri'], data={'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer', 'assertion': signed}).json()['access_token']
 print(token)
-"
+" "$SA_KEY"
 ```
 
 If `jwt` (PyJWT) is not installed, use: `pip install PyJWT requests`
@@ -365,17 +442,17 @@ After tracking integrity is validated, synthesize findings. Write down key data
 
 **Quick wins (with git history check — hard gate)**: GSC queries at position 4-20 with decent impressions but low CTR = title/meta optimization. **BUT FIRST**: For every page you'd propose a title/meta rewrite, run the git history check using `SEO_RECENT_CHANGE_DAYS`:
 ```bash
-git -C /home/mrdubey/projects/ScraperAPI/alterlab log --since="${SEO_RECENT_CHANGE_DAYS} days ago" --oneline -- web/src/app/<page>/page.tsx
+git -C "{REPO_PATH}" log --since="${SEO_RECENT_CHANGE_DAYS} days ago" --oneline -- web/src/app/<page>/page.tsx
 ```
 For blog posts stored in DB, check migration files:
 ```bash
-grep -rl "<slug>" /home/mrdubey/projects/ScraperAPI/alterlab/infra/migrations/ 2>/dev/null
+grep -rl "<slug>" "{REPO_PATH}/infra/migrations/" 2>/dev/null
 ```
 **If metadata changed within `SEO_RECENT_CHANGE_DAYS` days**: **Do NOT add to Proposed Actions.** Instead, add the page to the **"Recently Updated — Monitor"** section of the report (see Phase 3 template) with the note: "Updated {date} — allow 1 SEO cycle before re-evaluating. Current GSC data may reflect pre-change state." Only pages with stable metadata (unchanged for more than `SEO_RECENT_CHANGE_DAYS` days) may appear in Proposed Actions for SEO rewrites.
 
 Quantify the opportunity (e.g., "500 impressions/month at 1.2% CTR → industry avg 5% at position 6 → ~19 extra clicks/month").
 
-**Performance**: Clarity CWV ratings cross-referenced with GSC mobile data — poor mobile CWV hurts mobile rankings. Cloudflare cache hit ratio — **interpret in context**: AlterLab is API-first, so dynamic HTML+JSON responses should NOT be cached. Only flag cache issues if static assets (JS, CSS, images, fonts) have low cache rates. Check content type breakdown from Cloudflare data before claiming "low cache rate."
+**Performance**: Clarity CWV ratings cross-referenced with GSC mobile data — poor mobile CWV hurts mobile rankings. Cloudflare cache hit ratio — **interpret in context**: API-first projects have low cache rates by design, so dynamic HTML+JSON responses should NOT be cached. Only flag cache issues if static assets (JS, CSS, images, fonts) have low cache rates. Check content type breakdown from Cloudflare data before claiming "low cache rate."
 
 **Bing vs Google divergence**: Compare Bing Webmaster keyword rankings with GSC. Keywords ranking well on Bing but not Google (or vice versa) reveal optimization gaps. Bing rankings matter for ChatGPT search discoverability. **But**: only flag as actionable if the query has >50 impressions on the platform where ranking is weak. Below 50, position data is too noisy.
 
@@ -400,7 +477,7 @@ Before treating any event count as meaningful:
 - Cloudflare threat count > 50% of total requests → subtract bot traffic from ALL per-request metrics
 
 **Under-counting awareness** (developer audience):
-- AlterLab targets developers. Developers run ad blockers at 3-5x the general population rate.
+- Developer-focused projects see ad blockers at 3-5x the general population rate.
 - GA4 event counts likely undercount true user actions by 20-50%.
 - Never create a "low conversion rate" issue if Stripe successful charges roughly match or exceed analytics purchase events — the funnel is healthy, tracking is lossy.
 - Self-hosted Umami is more reliable than GA4 for this audience — prefer Umami event counts when they diverge.
@@ -450,7 +527,7 @@ Every candidate finding must pass this gate. If any check fails, downgrade to "O
 - [ ] **Not already tracked**: Before adding a finding to Proposed Actions, check if an open issue in history's `issues_created` list already covers the same finding:
   ```bash
   # For each issue number from history's issues_created:
-  gh issue view {PAST_ISSUE_NUMBER} -R RapierCraft/AlterLab --json state,title --jq '{state, title}'
+  gh issue view {PAST_ISSUE_NUMBER} -R {GH_REPO} --json state,title --jq '{state, title}'
   # If state=OPEN and the title/category matches the current finding → skip creation, note "Already tracked in #{PAST_ISSUE_NUMBER}"
   ```
   If the past issue is closed (fixed), the finding may recur — create a new issue and note the recurrence.
@@ -654,16 +731,16 @@ If an open milestone fits, offer to assign issues to it.
 
 ### Add analytics issues to Project board
 
-For each created issue, add it to the GitHub Project. Reference `~/projects/forge/docs/WORKFLOW.md` → "Project Board Integration" for field IDs.
+For each created issue, add it to the GitHub Project. Field IDs are resolved from `forge.yaml → project_board.field_ids` (see the ForgeDock docs for the full project board configuration schema).
 
 ```bash
-ISSUE_URL="https://github.com/RapierCraft/AlterLab/issues/${ISSUE_NUM}"
-ITEM_ID=$(gh project item-add 1 --owner RapierCraft --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
+ISSUE_URL="https://github.com/{GH_REPO}/issues/${ISSUE_NUM}"
+ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {PROJECT_BOARD_OWNER} --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
 if [ -n "$ITEM_ID" ]; then
-  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  # Status=Todo
-  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  # Lane=Fast
-  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  # Component=Platform
-  gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o --single-select-option-id {PRIORITY_OPTION_ID} 2>/dev/null || true  # Priority (from issue)
+  gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {project_board.field_ids.status} --single-select-option-id {project_board.option_ids.status.todo} 2>/dev/null || true  # Status=Todo
+  gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {project_board.field_ids.lane} --single-select-option-id {project_board.option_ids.lane.fast} 2>/dev/null || true  # Lane=Fast
+  gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {project_board.field_ids.component} --single-select-option-id {project_board.option_ids.component} 2>/dev/null || true  # Component
+  gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {project_board.field_ids.priority} --single-select-option-id {PRIORITY_OPTION_ID} 2>/dev/null || true  # Priority (from issue)
 fi
 ```
 
@@ -696,10 +773,10 @@ fi
 After displaying the summary, write the current audit snapshot to the history file. This enables Phase 0 of future audits to load it.
 
 ```bash
-HISTORY_FILE="/home/mrdubey/projects/ScraperAPI/analytics-history.yaml"
+HISTORY_FILE="{HISTORY_FILE}"
 
 python3 -c "
-import yaml, os, json
+import yaml, os, sys, json
 from datetime import date
 
 # Build snapshot from current audit data
@@ -742,9 +819,9 @@ snapshot = {
 
 # Read existing history (or start fresh)
 history = []
-if os.path.exists('$HISTORY_FILE'):
+if os.path.exists(sys.argv[1]):
     try:
-        history = yaml.safe_load(open('$HISTORY_FILE')) or []
+        history = yaml.safe_load(open(sys.argv[1])) or []
     except Exception:
         history = []  # corrupt file — start fresh, do not fail
 
@@ -753,11 +830,11 @@ history.append(snapshot)
 history = history[-12:]
 
 # Write back
-with open('$HISTORY_FILE', 'w') as f:
+with open(sys.argv[1], 'w') as f:
     yaml.dump(history, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
 
-print(f'History updated: {len(history)} entries in $HISTORY_FILE')
-"
+print(f'History updated: {len(history)} entries in {sys.argv[1]}')
+" "$HISTORY_FILE"
 ```
 
 **Placeholder substitution**: Replace `{GSC_CLICKS}`, `{UMAMI_VISITORS}`, etc. with the actual numeric values from the data collection agents. For any platform that was unavailable this run, use `null` (Python None). For `{ISSUES_CREATED_LIST}`, use a list of dicts matching the schema: `[{'number': 123, 'title': '...', 'priority': 'P1', 'category': 'infra'}]`. For `{KEY_FINDINGS_LIST}`, use a list of the top 3-5 finding strings from the Executive Summary. For `{GA4_STATUS}` etc., use one of: `trusted`, `partially_trusted`, `unverified`, `unavailable`.

package/commands/audit-agents.md

@@ -18,6 +18,30 @@ Parse agent JSONL output files from orchestration runs to produce actionable dia
 
 ---
 
+## Config Preamble
+
+Before executing any phase, read `forge.yaml` to resolve project references:
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+if [ -f "$CONFIG_FILE" ]; then
+  GH_OWNER=$(yq '.project.owner' "$CONFIG_FILE")
+  GH_REPO_NAME=$(yq '.project.repo' "$CONFIG_FILE")
+  GH_REPO="${GH_OWNER}/${GH_REPO_NAME}"
+  # FORGE_REPO: the self-pipeline repo where orchestration metrics are tracked.
+  # Set project.forge_repo in forge.yaml if your pipeline repo differs from GH_REPO.
+  FORGE_REPO=$(yq '.project.forge_repo // ""' "$CONFIG_FILE")
+  [ -z "$FORGE_REPO" ] && FORGE_REPO="$GH_REPO"
+else
+  echo "WARNING: forge.yaml not found — commands will use placeholder values"
+  echo "Run: cp forge.yaml.example forge.yaml  and fill in your project details"
+  GH_REPO="your-org/your-repo"
+  FORGE_REPO="$GH_REPO"
+fi
+```
+
+---
+
 ## Phase 1: Locate Agent Outputs
 
 ### Step 1A: Find the session
@@ -42,7 +66,7 @@ done | sort -rn | head -5
 - `latest` or no argument → most recent session with agent outputs
 - A session UUID → that specific session
 - An agent ID (starts with `a`, 17+ hex chars) → find the session containing that agent
-- A project path fragment (e.g., `ScraperAPI`) → filter to sessions for that project
+- A project path fragment (e.g., `my-project`) → filter to sessions for that project
 
 ### Step 1B: Collect agent JSONL files
 
@@ -320,17 +344,17 @@ This step posts a structured `<!-- FORGE:AUDIT-AGENTS -->` summary comment to th
 
 ```bash
 # Ensure the label exists before using it (gh issue create fails with GraphQL error if label is absent)
-gh label create "orchestration-metrics" -R RapierCraftStudios/forge \
+gh label create "orchestration-metrics" -R {FORGE_REPO} \
   --color "5319E7" --description "Running log of persisted audit-agents efficiency summaries" \
   --force 2>/dev/null || true
 
-TRACKING_ISSUE=$(gh issue list -R RapierCraftStudios/forge \
+TRACKING_ISSUE=$(gh issue list -R {FORGE_REPO} \
   --state open --label "orchestration-metrics" --limit 1 \
   --json number --jq '.[0].number' 2>/dev/null)
 
 if [ -z "$TRACKING_ISSUE" ]; then
   # Create the tracking issue on first use
-  TRACKING_ISSUE=$(gh issue create -R RapierCraftStudios/forge \
+  TRACKING_ISSUE=$(gh issue create -R {FORGE_REPO} \
     --title "Orchestration Metrics — Running Log" \
     --label "orchestration-metrics" \
     --body "This issue is a running log of persisted \`/audit-agents\` summaries. Each comment contains one session's efficiency metrics. Do not close this issue — \`/pipeline-health\` Phase 2K queries it to aggregate orchestration efficiency trends." \
@@ -363,7 +387,7 @@ STALL_BOUNDARIES=$(echo "${AGENT_DATA[@]}" | jq -r '
 ```bash
 SESSION_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
-gh issue comment $TRACKING_ISSUE -R RapierCraftStudios/forge --body "<!-- FORGE:AUDIT-AGENTS -->
+gh issue comment $TRACKING_ISSUE -R {FORGE_REPO} --body "<!-- FORGE:AUDIT-AGENTS -->
 ## Audit-Agents Summary — $SESSION_DATE
 
 **Session**: \`$SESSION_ID\`

package/commands/audit.md

@@ -9,7 +9,7 @@ argument-hint: <description of what went wrong> [--issue N] [--pr N] [--repo pre
 
 You are Forge's post-mortem auditor. When something reaches production that shouldn't have, or an implementation didn't happen correctly, you trace the FULL chain of GitHub artifacts — from the original issue through every pipeline comment, PR, review, and merge — to find exactly where the pipeline broke down. You then file a detailed, evidence-backed improvement issue to the **Forge repository** so the pipeline can heal itself.
 
-**This command ALWAYS files issues to `RapierCraftStudios/forge`.** The target project is read-only — you only read its GitHub artifacts as evidence.
+**This command ALWAYS files issues to `{FORGE_REPO}`.** The target project is read-only — you only read its GitHub artifacts as evidence.
 
 **Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
 
@@ -17,26 +17,64 @@ You are Forge's post-mortem auditor. When something reaches production that shou
 
 ---
 
+## Config Preamble
+
+Before executing any phase, read `forge.yaml` to resolve project references:
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+if [ -f "$CONFIG_FILE" ]; then
+  GH_OWNER=$(yq '.project.owner' "$CONFIG_FILE")
+  GH_REPO_NAME=$(yq '.project.repo' "$CONFIG_FILE")
+  GH_REPO="${GH_OWNER}/${GH_REPO_NAME}"
+  GH_FLAG="-R $GH_REPO"
+  REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+  # FORGE_REPO: the self-pipeline repo where audit improvement issues are filed.
+  # Set project.forge_repo in forge.yaml if your pipeline repo differs from GH_REPO.
+  # Example: project:
+  #            forge_repo: "my-org/my-forge"
+  FORGE_REPO=$(yq '.project.forge_repo // ""' "$CONFIG_FILE")
+  [ -z "$FORGE_REPO" ] && FORGE_REPO="$GH_REPO"
+else
+  echo "WARNING: forge.yaml not found — commands will use placeholder values"
+  echo "Run: cp forge.yaml.example forge.yaml  and fill in your project details"
+  GH_REPO="your-org/your-repo"
+  GH_FLAG="-R $GH_REPO"
+  REPO_PATH="./"
+  FORGE_REPO="$GH_REPO"
+fi
+```
+
+---
+
 ## Multi-Repo Support
 
-| Input Pattern | Target Repo |
-|---------------|-------------|
-| `--repo alterlab` or default | `RapierCraftStudios/AlterLab` |
-| `--repo mcp` | `RapierCraftStudios/alterlab-mcp-server` |
-| `--repo n8n` | `RapierCraftStudios/n8n-nodes-alterlab` |
+If your project spans multiple repositories, define them in the `repos.satellites` section of `forge.yaml`. The `--repo <prefix>` argument selects a satellite by its `prefix` field.
 
 Parse `$ARGUMENTS` for:
 - **Problem description**: free-text explanation of what went wrong
 - **`--issue N`**: specific issue number(s) to trace (comma-separated)
 - **`--pr N`**: specific PR number(s) to trace (comma-separated)
-- **`--repo prefix`**: target repo (default: AlterLab)
+- **`--repo prefix`**: target repo prefix (default: primary repo from `project.owner/project.repo`)
 
-Set context variables:
+Set context variables from config:
 
-| Variable | AlterLab | MCP | n8n |
-|----------|----------|-----|-----|
-| `GH_REPO` | `RapierCraftStudios/AlterLab` | `RapierCraftStudios/alterlab-mcp-server` | `RapierCraftStudios/n8n-nodes-alterlab` |
-| `GH_FLAG` | _(empty)_ | `-R RapierCraftStudios/alterlab-mcp-server` | `-R RapierCraftStudios/n8n-nodes-alterlab` |
+```bash
+REPO_PREFIX=$(echo "$ARGUMENTS" | grep -oP '(?<=--repo )\S+' || true)
+
+if [ -n "$REPO_PREFIX" ]; then
+  # Look up satellite repo by prefix in forge.yaml
+  SATELLITE_REPO=$(yq ".repos.satellites[] | select(.prefix == \"$REPO_PREFIX\") | .repo" "$CONFIG_FILE" 2>/dev/null)
+  if [ -n "$SATELLITE_REPO" ] && [ "$SATELLITE_REPO" != "null" ]; then
+    GH_REPO="$SATELLITE_REPO"
+    GH_FLAG="-R $GH_REPO"
+    REPO_PATH=$(yq ".repos.satellites[] | select(.prefix == \"$REPO_PREFIX\") | .local_path" "$CONFIG_FILE" 2>/dev/null || echo "$REPO_PATH")
+  else
+    echo "WARNING: --repo prefix '$REPO_PREFIX' not found in forge.yaml repos.satellites — using default repo"
+  fi
+fi
+# GH_REPO, GH_FLAG, REPO_PATH are now set for the target repo
+```
 
 ---
 
@@ -247,7 +285,7 @@ Create a detailed, actionable issue in the **Forge repository**.
 ### 4B: Create the issue
 
 ```bash
-gh issue create -R RapierCraftStudios/forge \
+gh issue create -R {FORGE_REPO} \
   --title "fix(pipeline): {one-line description of what the pipeline missed}" \
   --label "{LABELS}" \
   --body "$(cat <<'EOF'
@@ -332,7 +370,7 @@ Files that need changes:
 
 ```bash
 # Search forge for related issues
-gh issue list -R RapierCraftStudios/forge --state all --limit 30 --json number,title \
+gh issue list -R {FORGE_REPO} --state all --limit 30 --json number,title \
   --jq '[.[] | select(.title | test("{KEYWORDS}"; "i"))]'
 ```
 
@@ -351,11 +389,11 @@ Check if this same failure pattern has occurred before:
 
 ```bash
 # Similar audit findings in forge
-gh issue list -R RapierCraftStudios/forge --state all --label "audit-finding" --limit 50 \
+gh issue list -R {FORGE_REPO} --state all --label "audit-finding" --limit 50 \
   --json number,title,state --jq '.[] | "\(.number) | \(.title) | \(.state)"'
 
 # Same failure point in existing issues
-gh issue list -R RapierCraftStudios/forge --state all --limit 100 --json number,title,body \
+gh issue list -R {FORGE_REPO} --state all --limit 100 --json number,title,body \
   --jq "[.[] | select(.body | contains(\"{FAILURE_POINT}\"))] | .[] | \"\(.number) | \(.title)\""
 ```
 
@@ -375,7 +413,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "$(cat <<'EOF'
 ## Pipeline Audit
 
 This issue was audited by Forge. A pipeline improvement issue has been filed:
-- **Forge issue**: RapierCraftStudios/forge#{FORGE_ISSUE_NUMBER}
+- **Forge issue**: {FORGE_REPO}#{FORGE_ISSUE_NUMBER}
 - **Failure point**: {FAILURE_POINT}
 - **Root cause**: {1-line summary}
 

package/commands/autopilot.md

@@ -7,7 +7,12 @@ argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
 
 **Input**: $ARGUMENTS (default: recon + triage + report, no fixing)
 
-You are AlterLab's autonomous improvement engine. Your job is to **find what's wrong, create trackable issues, and optionally fix the highest-impact ones** — all in a single cycle. Every cycle leaves the platform measurably better than before.
+**Config variables used by this command** (set in `forge.yaml`):
+- `{CREDENTIALS_FILE}` ← `paths.credentials.file` (optional) — path to credentials YAML for analytics APIs
+- `{SERVER_SSH}` ← `services.server_ssh` (optional) — SSH target for production server health checks (e.g., `ubuntu@1.2.3.4`)
+- `{EMEMO_PATH}` ← `services.ememo_path` (optional) — path on production server to open eMemo files
+
+You are an autonomous improvement engine for this project. Your job is to **find what's wrong, create trackable issues, and optionally fix the highest-impact ones** — all in a single cycle. Every cycle leaves the platform measurably better than before.
 
 **This is designed to run repeatedly.** Each cycle builds on the last — issues created in cycle N get fixed in cycle N+1. The platform compounds improvements over time.
 
@@ -94,7 +99,7 @@ Spawn these as **background agents** (all `run_in_background=true`, all `model="
 **Agent: Production Health**
 ```
 Check production system health:
-1. SSH to check for open eMemos: ssh ubuntu@51.195.40.172 "ls /opt/alterlab/app/infra/ememos/*-open-* 2>/dev/null"
+1. SSH to check for open eMemos: if {SERVER_SSH} is configured, run: ssh {SERVER_SSH} "ls {EMEMO_PATH}/*-open-* 2>/dev/null" — skip this step if SERVER_SSH or EMEMO_PATH is not set in forge.yaml
 2. If any exist, cat each one and summarize
 3. Check container health via MCP: get_production_status, run_production_health_check
 4. Check recent error logs: get_production_logs for api and worker (last 100 lines), grep for ERROR/CRITICAL
@@ -133,7 +138,7 @@ Analyze GitHub issue backlog:
 **Agent: Analytics Snapshot** (lightweight — not the full /analytics audit)
 ```
 Quick analytics pulse — just the key metrics, not a full audit:
-1. Read credentials from /home/mrdubey/projects/ScraperAPI/credentials.yaml
+1. Read credentials from {CREDENTIALS_FILE} (set via paths.credentials.file in forge.yaml)
 2. GSC: mcp__gsc__search_analytics for last 7 days — total clicks, impressions, avg position
 3. Stripe: mcp__stripe__retrieve_balance — current balance
 4. Return: clicks trend (up/down), any revenue, notable changes
@@ -409,9 +414,9 @@ When ready to deploy, merge `staging` → `main` via GitHub.
 
 Each cycle feeds the next:
 ```
-Cycle N: /failure-recon finds tier 3 headers broken → creates issue #X
-Cycle N+1: autopilot picks up #X → /work-on fixes it → merged to staging
-Cycle N+2: /failure-recon shows tier 3 pass rate improved 30% → no new issue needed
+Cycle N: CI recon detects recurring lint failures across 3 files → autopilot triage creates issue #X
+Cycle N+1: autopilot picks up #X → /work-on adds pre-commit hook → merged to staging
+Cycle N+2: CI recon shows lint failures resolved — no new issue needed
 ```
 
 ```