@mmerterden/multi-agent-pipeline 15.14.0 → 15.16.0

package/CHANGELOG.md

@@ -16,6 +16,33 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.16.0] - 2026-08-22
+
+### Added
+- **More than one Firebase project per team.** `keychainMapping.firebase` held exactly one service-account key, which is wrong for the normal case: a legacy app next to its redesign, or staging next to production, each with its own key. A crash URL from the project you did not pick failed the `project_id` check and reported it as a configuration error, which it was, but not the one the message suggested. `global.firebase.accounts[]` maps `projectId` to a keychain key, `fetch-crashlytics.sh` reads the projectId out of the console URL and picks the matching account, and the single slot stays the fallback so a one-project setup needs no config at all. `/multi-agent:setup` now loops the Firebase pass (`Add another Firebase project? [y/N]`), reading `project_id` from each decoded JSON rather than asking for it.
+- A `project_id` mismatch now names the key it used and prints the `accounts[]` entry to add. With several projects in play, "project mismatch" alone does not say whether the URL is wrong or the mapping is incomplete.
+
+- **Jira project keys are discovered instead of recalled.** The token is saved and the host is known by the time setup asks for a project key, so it now asks Jira: one search for issues the person assigned or reported, most-recently-updated first, and the distinct project keys become a picker. A corporate instance has thousands of projects and a typed key is a typo that routes branches and new issues at the wrong board. The free-text prompt stays as the fallback for no-VPN and fresh accounts, and the per-repo mapping offers the discovered keys rather than asking for them again.
+
+### Changed
+- `setup/SKILL.md` lost its third copy of the service-ID table and its second copy of the `keychainMapping` shape; both live in `refs/keychain.md`, which the flow already cites. What stayed is the column nothing else had: where to generate each token. The Firebase host-exemption note also stopped being stated twice, two paragraphs apart.
+- The App Store Connect tier reasoning moved into the ref that owns that flow, and `refs/keychain.md` gained the four App Store Connect standard key names so it is now the complete answer for every service setup points at.
+- `smoke-url-enrichment.sh` follows the type label to where it now lives and adds eight assertions: five for the multi-account contract (including that the single-slot fallback survives) and three for Jira discovery and the completeness of the key-name reference.
+
+## [15.15.0] - 2026-08-22
+
+### Added
+- **Graylog has two instances now, because it always did.** Test and production are separate Graylog deployments, and a trx id minted by a tester does not exist in production - so searching production alone answered "no logs" for a complaint that was fully logged one host over, and that answer was indistinguishable from a genuine miss. `hosts.graylogTest` and the optional `keychainMapping.graylog_test` (which falls back to the production key, correct for shared-token deployments) make the second instance addressable. `fetch-graylog.sh --env auto` is the new default: production first, test when production returns nothing or is unreachable. `--env prod` / `--env test` pin one.
+- **The payload names the instance that answered** (`source.environment`, `source.searchedEnvironments[]`), and `/multi-agent:complaint-analysis` now has to cite it. A production complaint corroborated only by test logs is `insufficient-evidence`, not a confirmed `bff` fault, and the old payload gave the triage no way to tell those apart.
+- `/multi-agent:setup` asks for the two things the previous release added a consumer for but no collector: the Graylog test host plus its optional separate token, and `fortify.versionIds`. `versionIds` shipped in 15.14.0 as the only way to resolve an instance-id-only Fortify ticket, and nothing asked for it, so that path silently no-opped for everyone.
+- **`smoke-graylog-environments.sh`**, 15 assertions over the resolution rules that are easy to get subtly wrong: auto stops at production when production answers, falls back on empty AND on unreachable, degrades (never blocks) when both are down, treats a pinned environment with no host as exit 6 rather than silently searching the other one, and lets a 401 on one instance fall through instead of masking a working answer from the other.
+
+### Fixed
+- A pinned `--env` with no configured host now exits 6 naming the exact pref, instead of falling back to whichever host happened to be set. Attaching test logs to a production complaint is worse than attaching none.
+
+### Changed
+- `fetch-graylog.sh` resolves host and token per environment instead of once at the top, and reads prefs through one helper rather than three near-identical inline python blocks.
+
 ## [15.14.0] - 2026-08-22
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.14.0",
+  "version": "15.16.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/complaint-analysis/SKILL.md

@@ -81,12 +81,16 @@ For each complaint with at least one id and `skipGraylog: false`:
 ~/.claude/lib/fetch-graylog.sh --trx <trxId> --conv <convId>   # pass whichever exist
 ```
 
-Record per complaint: `graylog: {status: ok|degraded|skipped, totalResults, degradeReason}` plus the top messages (timestamp, source, level, message excerpt) kept in working context for Phase 2/3. Failure handling:
+Environment defaults to `auto`: production first, the test instance (`hosts.graylogTest`) when production returns nothing or is unreachable. A customer complaint is normally a production event, but a tester-minted id only exists on test, and prod-only search reports "no logs" for both cases identically. When the intake itself says which environment a complaint came from, pin it with `--env prod` / `--env test` rather than letting the fallback decide.
+
+Record per complaint: `graylog: {status: ok|degraded|skipped, environment, totalResults, degradeReason}` plus the top messages (timestamp, source, level, message excerpt) kept in working context for Phase 2/3. Failure handling:
 
 - Exit 0 with `degraded: true` -> `status: degraded`, keep the reason, continue.
 - Exit 2 / 3 / 6 (credential / auth / host) -> per `$HOME/.claude/multi-agent-refs/keychain.md` non-critical rule: warn ONCE (`WARN: Graylog unavailable (<reason>); remaining complaints proceed without log evidence.`), mark this and all remaining fetches `status: degraded`, continue. Never halt (Locked 1).
 - `skipGraylog: true` -> `status: skipped`.
 
+**Always name the environment when citing log evidence.** `source.environment` in the fetcher payload says which instance answered; the same lines mean different things depending on whether a production complaint was corroborated by production logs or only by test ones. A complaint whose only evidence came from test is `insufficient-evidence` for a production claim, not `bff`.
+
 Set `phase: "correlating_repos"`.
 
 ### Phase 2 - Repo evidence correlation (read-only)

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -92,31 +92,32 @@ DISCOVERED=$(~/.claude/lib/credential-store.sh list 2>/dev/null | grep -i "^${US
 echo "$DISCOVERED"
 ```
 
-**1b. Standard key names (convention):**
-
-These are the RECOMMENDED key names. When creating NEW keys, use these. But existing keys under different names are perfectly valid  -  the discovery step will find them.
-
-| Service ID | Standard Key Name | Search Keywords |
-|------------|------------------|-----------------|
-| `jira` | `${USER}_Jira_Access_Token` | `jira` |
-| `bitbucket_token` | `${USER}_Bitbucket_Access_Token` | `bitbucket` + (`token` or `access` or `pass`) |
-| `bitbucket_user` | `${USER}_Bitbucket_Username` | `bitbucket` + (`user` or `name`) |
-| `github` | `${USER}_Github_Access_Token` | `github` or `gh` (exclude `ssh`) |
-| `confluence` | `${USER}_Confluence_Access_Token` | `confluence` |
-| `figma` | `${USER}_Figma_Access_Token` | `figma` + (`token` or `pat` or `access`) + NOT `mcp` |
-| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | `figma` + `mcp` |
-| `fortify` | `${USER}_Fortify_Access_Token` | `fortify` |
-| `graylog` | `${USER}_Graylog_Access_Token` | `graylog` |
-| `firebase` | `${USER}_Firebase_Access_Json` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
-| `jenkins` | `${USER}_Jenkins_Access_Token` | `jenkins` |
-| `appstore_connect_key_id` | `${USER}_AppStoreConnect_Key_Id` | (`appstore` or `asc` or `app_store`) + (`key` or `keyid`) |
-| `appstore_connect_issuer_id` | `${USER}_AppStoreConnect_Issuer_Id` | (`appstore` or `asc` or `app_store`) + `issuer` |
-| `appstore_connect_apple_id` | `${USER}_AppStoreConnect_Apple_Id` | (`appstore` or `asc`) + (`apple` or `account` or `user`) |
-| `appstore_connect_password_item` | `${USER}_AppStoreConnect_Password_Item` | (`appstore` or `asc` or `altool`) + (`password` or `app_specific`) |
+**1b. Search keywords (per service):**
+
+Standard key names  -  the ones to use when creating a NEW key  -  live in `$HOME/.claude/multi-agent-refs/keychain.md` "Standard key names"; read the name for a service from there. Existing keys under other names are perfectly valid, which is what these keywords are for.
+
+| Service ID | Search Keywords |
+|------------|-----------------|
+| `jira` | `jira` |
+| `bitbucket_token` | `bitbucket` + (`token` or `access` or `pass`) |
+| `bitbucket_user` | `bitbucket` + (`user` or `name`) |
+| `github` | `github` or `gh` (exclude `ssh`) |
+| `confluence` | `confluence` |
+| `figma` | `figma` + (`token` or `pat` or `access`) + NOT `mcp` |
+| `figma_mcp` | `figma` + `mcp` |
+| `fortify` | `fortify` |
+| `graylog` | `graylog` |
+| `graylog_test` | `graylog` + `test` |
+| `firebase` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
+| `jenkins` | `jenkins` |
+| `appstore_connect_key_id` | (`appstore` or `asc` or `app_store`) + (`key` or `keyid`) |
+| `appstore_connect_issuer_id` | (`appstore` or `asc` or `app_store`) + `issuer` |
+| `appstore_connect_apple_id` | (`appstore` or `asc`) + (`apple` or `account` or `user`) |
+| `appstore_connect_password_item` | (`appstore` or `asc` or `altool`) + (`password` or `app_specific`) |
 
 > Multi-agent setup onboards **both** Figma tokens because the pipeline's 3-tier Figma access chain (see `$HOME/.claude/rules/figma-pipeline.md`) uses them in priority order: Tier 1 = MCP (`figma_mcp`), Tier 2 = REST PAT (`figma`), Tier 3 = user screenshot fallback. Missing either token forces a downshift; missing both leaves Tier 3 as the only path. The Tier 2 logical key is `figma`, not `figma_pat`: `figma_pat` is the pre-v13.6 name that `migrate-prefs.mjs` consolidates away, and writing a new mapping under it means the next migration deletes it.
 
-> The four App Store Connect entries are **iOS-only and optional**: skip them all and the pipeline still works, it just reports Gate 2 of `/multi-agent:store-ready` as `SKIPPED` (never as a pass). They mirror the Figma 3-tier shape  -  Tier 1 = API key (`appstore_connect_key_id` + `appstore_connect_issuer_id`), Tier 2 = Apple ID + app-specific password (`appstore_connect_apple_id` + `appstore_connect_password_item`), Tier 3 = nothing configured. **Offer Tier 2 first when the user says they cannot create an API key**: creating one needs an Admin or App Manager role in App Store Connect, while an app-specific password is generated by the account holder at `appleid.apple.com` with no team permission at all. Two of these hold identifiers rather than secrets (key id, issuer id) and one holds a keychain ITEM NAME, not a password  -  they still go through the mapping layer so every credential is read the same way. Onboarding mechanics in Step 3b.
+> The four App Store Connect entries are **iOS-only and optional**  -  skipping them all reports Gate 2 of `/multi-agent:store-ready` as `SKIPPED`, never as a pass. Two hold identifiers rather than secrets and one holds a keychain ITEM NAME, yet all four go through the mapping layer so every credential is read the same way. Tiers, the role constraint that decides which to offer first, and the onboarding mechanics: Step 3b and `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`.
 
 **1c. Resolution logic (per service):**
 
@@ -183,27 +184,14 @@ Keychain Token Discovery (${USER}):
 
 Non-standard key names are perfectly valid  -  the mapping handles resolution. No rename or migration is offered.
 
-Save the resolved mapping to preferences:
+Save the resolved mapping to `prefs.global.keychainMapping`  -  every service ID gets an entry, the discovered key name verbatim or `null` when nothing was found:
+
 ```json
-{
-  "global": {
-    "keychainMapping": {
-      "jira": "${USER}_Jira_Access_Token",
-      "bitbucket_token": "${USER}_Bitbucket_Access_Token",
-      "bitbucket_user": "${USER}_Bitbucket_Username",
-      "github": "${USER}_Github",
-      "confluence": null,
-      "figma": "${USER}_Figma_Access_Token",
-      "figma_mcp": "${USER}_Figma_Mcp_Access_Token",
-      "fortify": null,
-      "graylog": null,
-      "firebase": "${USER}_Firebase_Access_Json",
-      "jenkins": null
-    }
-  }
-}
+{ "jira": "${USER}_Jira_Access_Token", "github": "${USER}_Github", "confluence": null, "...": "..." }
 ```
 
+Full key list and shape: `$HOME/.claude/multi-agent-refs/keychain.md`.
+
 `null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
 
 ### Step 2.7  -  Operational reporting token (optional, opt-in)
@@ -288,7 +276,7 @@ The Step 2 discovery summary is never the end of setup. Immediately after showin
 Loop rules:
 
 - **One prompt per service.** Never collapse the list into a single "add missing tokens now?" yes/no, and never offer one multi-select covering all services: each service has its own source URL, key name, identity binding and host prompt, so each gets its own Token Save Flow pass.
-- **Each service pass asks, in order: token → author → host.** Step A/B collect the secret, Step C binds the git identity (author)  -  Bitbucket and GitHub included; every saved token gets an author  -  and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog). GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
+- **Each service pass asks, in order: token → author → host.** Step A/B collect the secret, Step C binds the git identity (author)  -  Bitbucket and GitHub included; every saved token gets an author  -  and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog) - plus the Fortify project versions and the optional Graylog test instance. GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
 - **Skip is per-service.** A Skip answer leaves that service's `keychainMapping` at `null` and the loop continues with the next service. Skips never abort the loop.
 - **`figma` and `figma_mcp` are distinct credentials for distinct tiers  -  ask both.** Skipping the PAT does not imply skipping MCP, and vice versa. The `figma_mcp` pass opens with a Remote / Local mode question instead of a clipboard paste (see "Figma MCP Setup" below): Remote generates a `figu_` OAuth token for the current user, Local wires the PAT-based local server.
 - The loop ends only when every missing service has been asked exactly once; then continue to Step 4 (Verify all).
@@ -369,6 +357,12 @@ pbcopy < /dev/null   # clear clipboard
 
 Linux substitutes: `xclip -selection clipboard -o` or `wl-paste` for `pbpaste`; matching clear command for `pbcopy < /dev/null`. The shell driver detects platform and routes accordingly (see `~/.claude/lib/credential-store.sh`).
 
+**Firebase repeats per project.** Teams own several Firebase projects (legacy plus redesign, staging plus prod), each with its own key, and a crash URL from the second one used to fail the `project_id` check as if it were misconfigured. After each saved key, read `project_id` from the decoded JSON (never ask) and offer another round: `Saved: <project_id>. Add another Firebase project? [y/N]`.
+
+- Every key appends `{projectId, keychainKey, label?}` to `prefs.global.firebase.accounts`; the first one also fills `keychainMapping.firebase`, so a one-project setup is unchanged.
+- Keys after the first are named `${USER}_Firebase_Access_Json_<projectId>` so they cannot collide.
+- At run time `fetch-crashlytics.sh` picks the account matching the console URL's projectId, falling back to `keychainMapping.firebase`.
+
 For GitHub (special case):
 ```
   ! gh auth login
@@ -408,8 +402,7 @@ Update `serviceStatus.{service} = { ok: true, checkedAt: <now> }`.
 **→ Next: if `{service}` is `jira` / `confluence` / `bitbucket` / `fortify` / `graylog` AND the corresponding
 `prefs.global.hosts.{service}` is unset, run Step 3.5 (Host Prompt) inline before
 the Auto-routing rule below. required  -  the pipeline cannot build API URLs without
-the host. Firebase is skipped here (host is always `console.firebase.google.com` /
-`firebasecrashlytics.googleapis.com`); the SA JSON itself carries `project_id`.**
+the host. Firebase is exempt (see Step 3.5).**
 
 **Auto-routing rule** (optional, on first token per platform):
 
@@ -430,7 +423,7 @@ Runs inside Step 3 alongside the other missing credentials. The four `appstore_c
 
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 
-**Not a standalone step**  -  runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify, Graylog) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step  -  Crashlytics is always on Google's fixed domains and `project_id` is embedded in the SA JSON.
+**Not a standalone step**  -  runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify, Graylog) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step  -  Crashlytics is always on Google's fixed domains and `project_id` is embedded in the service-account JSON.
 
 Right after Step D (identity mapping confirmed), ask:
 
@@ -440,27 +433,30 @@ Service host  -  needed to build API URLs for this token.
   {Service} host (e.g. jira.example.com): ___
 ```
 
-Save to `prefs.global.hosts.{service}`. For Jira specifically, also ask for the default project key (the token is useless without one for new-issue creation):
+Save to `prefs.global.hosts.{service}`. For Fortify, also ask `Fortify project version ids (optional, comma-separated - e.g. 1234,5678)` → `prefs.global.fortify.versionIds`. A ticket naming only an instance id carries no version, so the lookup silently no-ops without these; URL-referenced findings resolve either way.
 
-```
-Default Jira project key (e.g. PROJ): ___
+For Jira, **discover the project keys instead of asking the user to recall them.** The token is already saved and the host is already known, so ask Jira which projects this person actually works in - a corporate instance has thousands of projects, and a typed key is a typo waiting to route branches and new issues at the wrong board:
+
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://{JIRA_HOST}/rest/api/2/search?jql=assignee%3DcurrentUser()%20OR%20reporter%3DcurrentUser()%20ORDER%20BY%20updated%20DESC&fields=project&maxResults=100" \
+  | jq -r '[.issues[].fields.project | "\(.key)\t\(.name)"] | unique | .[]'
 ```
 
-Save to `prefs.global.defaultJiraKey`. From Jira host, derive `corpDomain` (e.g. `jira.example.com` → `example.com`) and pre-fill it so the Confluence / Bitbucket prompts only need the subdomain.
+Present the distinct keys, most-recently-worked first, as a picker; fall back to the free-text prompt `Default Jira project key (e.g. PROJ)` when the call fails or returns nothing (no VPN, fresh account). The picked key → `prefs.global.defaultJiraKey`. From the Jira host, derive `corpDomain` (`jira.example.com` → `example.com`) and pre-fill it so the Confluence / Bitbucket prompts only need the subdomain.
 
-`defaultJiraKey` stays a single global fallback, but one Jira host usually serves several repos with DIFFERENT project keys, so the Jira pass continues with a per-repo key mapping (multi-select, optional):
+`defaultJiraKey` is a single global fallback, but one Jira host usually serves several repos with DIFFERENT keys, so the pass continues with a per-repo mapping. Show the repos, and let the key come from the discovered list rather than being typed again:
 
 ```
 Per-repo Jira keys (optional)  -  repos whose project key differs from {defaultJiraKey}:
 
   [ ] 1. my-ios-app        (current: PROJA)
   [ ] 2. my-other-app      (current:  - )
-  ...
 
-  Toggle repos, then enter the project key for each selected repo. Enter to skip.
+  Toggle repos, then pick a project for each  -  discovered: PROJA, PROJB, PROJC. Enter to skip.
 ```
 
-- The repo list comes from `prefs.projects` + `recentProjects` (when Step 5 already ran); a free-text repo path is accepted for repos not discovered yet.
+- The repo list comes from `prefs.projects` + `recentProjects` (when Step 5 already ran); a free-text repo path is accepted for repos not discovered yet, and a free-text key for a project the search did not surface.
 - Each answer is PREPENDED to `prefs.projects[{slug}].jiraProjectKeys` (deduped, max 10 per schema). Example: `my-ios-app` → `PROJA`, `my-other-app` → `PROJB`  -  two repos on the same Jira host, two different project keys.
 - Resolution order everywhere a Jira key is needed (placeholder replacement, branch names, new-issue creation): `prefs.projects[{slug}].jiraProjectKeys[0]` first, `global.defaultJiraKey` as fallback.
 - **Re-run / update**: `/multi-agent:setup jira-keys` re-opens only this mapping without touching tokens or hosts.
@@ -476,6 +472,7 @@ Resulting shape:
       "bitbucket":  "bitbucket.example.com",
       "fortify":    "ssc.example.com",
       "graylog":    "graylog.example.com",
+      "graylogTest": "graylog-test.example.com",
       "corpDomain": "example.com"
     },
     "defaultJiraKey": "PROJ"
@@ -483,9 +480,18 @@ Resulting shape:
 }
 ```
 
-Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_HOST}`, `{GRAYLOG_HOST}`, `{CORP_DOMAIN}`, `{JIRA_KEY}` in skills/commands are resolved from this block at runtime. If a host is ever missing when a phase needs it, Phase 0 prompts the same Host Prompt inline.
+Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_HOST}`, `{GRAYLOG_HOST}`, `{GRAYLOG_TEST_HOST}`, `{CORP_DOMAIN}`, `{JIRA_KEY}` in skills/commands are resolved from this block at runtime. If a host is ever missing when a phase needs it, Phase 0 prompts the same Host Prompt inline.
+
+Graylog uses a **PAT** whose API auth is HTTP Basic with the token as username and the literal `token` as password  -  no separate username entry. It is optional by the null-mapping convention: `keychainMapping.graylog` or `hosts.graylog` left `null` degrades the log fetch to empty and never blocks a run.
+
+Graylog is asked **twice**  -  test and production are separate instances, and a tester-minted trx id does not exist in production. After the production host:
+
+```
+Graylog test host (optional  -  Enter to skip): ___
+Does the test instance use a different token? [y/N]
+```
 
-Graylog uses a **PAT (access token)** whose API auth is HTTP Basic with the token as the username and the literal `token` as the password (`<token>:token`)  -  no separate username entry. Its host prompt behaves exactly like the Jira host prompt (saved to `prefs.global.hosts.graylog`, resolved as `{GRAYLOG_HOST}`). Graylog is **automatically optional / non-blocking** via the null-mapping convention: leaving `keychainMapping.graylog` (and/or `hosts.graylog`) `null` simply means the log-fetch adapter degrades to empty and never blocks a run  -  no extra setup code.
+Test host → `hosts.graylogTest` (`{GRAYLOG_TEST_HOST}`); skipped means production-only search, which degrades nothing. Yes to the token question runs one more Token Save Flow pass for `graylog_test`; no (default) leaves it null and the fetcher reuses the production key. Run-time order is `--env auto`: production first, test on empty or unreachable, and the payload names which answered.
 
 **Re-run / update**: `/multi-agent:setup hosts` re-opens the prompt to edit values without touching tokens.
 
@@ -696,20 +702,23 @@ If no backend is available, setup falls back to a plain-text prompt + a warning
 
 Standard key names (used when creating NEW tokens). Discovery may find existing keys under different names  -  that's fine, the mapping in preferences handles it.
 
-| Service ID | Standard Key Name | Type | Where to Get |
-|------------|------------------|------|---------------|
-| `jira` | `${USER}_Jira_Access_Token` | PAT | Jira -> Profile -> Personal Access Tokens (VPN required) |
-| `bitbucket_token` | `${USER}_Bitbucket_Access_Token` | App Password | Bitbucket -> Personal settings -> App passwords |
-| `bitbucket_user` | `${USER}_Bitbucket_Username` | Plain text | Bitbucket profile username |
-| `github` | `${USER}_Github_Access_Token` | PAT | GitHub Settings -> Tokens (scopes: repo, read:org, project) |
-| `confluence` | `${USER}_Confluence_Access_Token` | PAT | Confluence -> Profile -> Personal Access Tokens (VPN required) |
-| `figma` | `${USER}_Figma_Access_Token` | PAT (Tier 2, REST API) | Figma Developer Settings (max 90 days). Token Save Flow prompt copy: "Figma Personal Access Token (for Tier 2)". |
-| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | OAuth (Tier 1, MCP) | Automatic via Claude Code Figma MCP remote auth. Token Save Flow prompt copy: "Figma MCP token (for Tier 1)". |
-| `fortify` | `${USER}_Fortify_Access_Token` | API Token | Fortify SSC -> Token Management (VPN required) |
-| `graylog` | `${USER}_Graylog_Access_Token` | PAT (API Basic `<token>:token`) | Graylog -> System -> Users and Teams -> Edit Tokens (VPN required). Auth is HTTP Basic with the token as username and literal `token` as password. |
-| `firebase` | `${USER}_Firebase_Access_Json` | Firebase JSON (base64) | Firebase Console -> Project settings -> Service accounts -> Generate new private key. Project id is parsed from the decoded JSON  -  no separate entry. |
-| `jenkins` | `${USER}_Jenkins_Access_Token` | API Token | Jenkins -> User -> Configure -> API Token |
-|  -  | Git Identities | JSON (preferences) | Stored in `$HOME/.claude/multi-agent-preferences.json`  -  not Keychain |
+Standard key names and token types: `$HOME/.claude/multi-agent-refs/keychain.md` "Standard key names". Where to generate each one:
+
+| Service ID | Where to Get |
+|------------|---------------|
+| `jira` | Jira -> Profile -> Personal Access Tokens (VPN required) |
+| `bitbucket_token` | Bitbucket -> Personal settings -> App passwords |
+| `bitbucket_user` | Bitbucket profile username (plain text, not a PAT) |
+| `github` | GitHub Settings -> Tokens (scopes: repo, read:org, project) |
+| `confluence` | Confluence -> Profile -> Personal Access Tokens (VPN required) |
+| `figma` | Figma Developer Settings (max 90 days). Tier 2 / REST. Prompt copy: "Figma Personal Access Token (for Tier 2)". |
+| `figma_mcp` | Automatic via Claude Code Figma MCP remote auth. Tier 1 / MCP. Prompt copy: "Figma MCP token (for Tier 1)". |
+| `fortify` | Fortify SSC -> Token Management (VPN required) |
+| `graylog` | Graylog -> System -> Users and Teams -> Edit Tokens (VPN required) |
+| `graylog_test` | Same page on the TEST instance; optional |
+| `firebase` | Firebase Console -> Project settings -> Service accounts -> Generate new private key. One key per Firebase project; `project_id` is parsed from the decoded JSON, never asked. |
+| `jenkins` | Jenkins -> User -> Configure -> API Token |
+| Git Identities | Stored in `$HOME/.claude/multi-agent-preferences.json`, not Keychain |
 
 ### Inline Token Save Pattern
 

package/pipeline/lib/fetch-crashlytics.sh

@@ -13,8 +13,13 @@
 #
 # Optional env:
 #   FIREBASE_TIMEOUT_SECONDS    default 20
-#   FIREBASE_TOKEN_KEY          default prefs.global.keychainMapping.firebase
-#                               fallback "${USER}_Firebase_Access_Json"
+#   FIREBASE_TOKEN_KEY          forces one keychain key, skipping account lookup
+#
+# Credential resolution, in order:
+#   1. FIREBASE_TOKEN_KEY (env override)
+#   2. prefs.global.firebase.accounts[] entry whose projectId matches the URL
+#   3. prefs.global.keychainMapping.firebase (single-project setups)
+#   4. "${USER}_Firebase_Access_Json"
 #
 # Output (stdout, single JSON object):
 #   {
@@ -116,18 +121,35 @@ if [ -z "$PROJECT_ID" ] || [ -z "$PLATFORM" ] || [ -z "$BUNDLE" ] || [ -z "$ISSU
   exit 4
 fi
 
-# Resolve Firebase SA JSON via keychain mapping (matches Phase 0 contract).
+# Resolve the Firebase SA JSON via keychain mapping (matches Phase 0 contract).
+#
+# One team routinely owns several Firebase projects - a legacy app and its
+# redesign, or staging next to production - and each has its own service-account
+# key. A single `keychainMapping.firebase` slot forced a choice, and a crash URL
+# from the other project then failed the project_id check as if it were a
+# configuration error. `global.firebase.accounts[]` maps projectId -> keychain
+# key, and the URL's projectId picks the key. The single slot stays the fallback,
+# so a one-project setup needs no config at all.
 PREFS="$HOME/.claude/multi-agent-preferences.json"
 TOKEN_KEY="${FIREBASE_TOKEN_KEY:-}"
+FIREBASE_ACCOUNT_LABEL=""
 if [ -z "$TOKEN_KEY" ] && [ -f "$PREFS" ]; then
-  TOKEN_KEY=$(python3 -c "
-import json
+  ACCOUNT_HIT=$(WANT_PROJECT="$PROJECT_ID" python3 -c "
+import json, os
+want = os.environ.get('WANT_PROJECT') or ''
 try:
-    p = json.load(open('$PREFS'))
-    print(p.get('global', {}).get('keychainMapping', {}).get('firebase') or '')
+    g = json.load(open('$PREFS')).get('global', {})
 except Exception:
-    print('')
-")
+    g = {}
+for a in (g.get('firebase', {}) or {}).get('accounts') or []:
+    if isinstance(a, dict) and str(a.get('projectId') or '') == want and a.get('keychainKey'):
+        print('%s\t%s' % (a['keychainKey'], a.get('label') or a['projectId']))
+        break
+else:
+    print('%s\t' % ((g.get('keychainMapping', {}) or {}).get('firebase') or ''))
+" 2>/dev/null || printf '\t')
+  TOKEN_KEY=$(printf '%s' "$ACCOUNT_HIT" | cut -f1)
+  FIREBASE_ACCOUNT_LABEL=$(printf '%s' "$ACCOUNT_HIT" | cut -f2)
 fi
 [ -z "$TOKEN_KEY" ] && TOKEN_KEY="${USER}_Firebase_Access_Json"
 
@@ -199,7 +221,12 @@ except Exception:
     print('')
 ")
 if [ -n "$SA_PROJECT" ] && [ "$SA_PROJECT" != "$PROJECT_ID" ]; then
+  # Still a hard error, but say which key was used and how to map the right one:
+  # with several Firebase projects in play, "project mismatch" alone does not
+  # tell you whether the URL is wrong or the mapping is missing an account.
   echo "ERR: SA project_id ($SA_PROJECT) != URL project ($PROJECT_ID)" >&2
+  echo "     key used: $TOKEN_KEY${FIREBASE_ACCOUNT_LABEL:+ (account: $FIREBASE_ACCOUNT_LABEL)}" >&2
+  echo "     map this project: prefs.global.firebase.accounts[] += {\"projectId\":\"$PROJECT_ID\",\"keychainKey\":\"<keychain-key>\"}" >&2
   exit 5
 fi
 

package/pipeline/lib/fetch-graylog.sh

@@ -11,14 +11,29 @@
 #   ./fetch-graylog.sh --trx <transaction-id>
 #   ./fetch-graylog.sh --conv <conversation-id>
 #   ./fetch-graylog.sh --trx <id> --conv <id>
+#   ./fetch-graylog.sh --trx <id> --env test      # force one environment
+#
+# Environments. Test and production are separate Graylog instances, and a trx id
+# minted by a tester simply does not exist in production - searching only prod
+# returns "no logs" for a complaint that is fully logged one host over. The
+# default `--env auto` searches production first and falls back to test when
+# production returns nothing or is unreachable; the answer always names the
+# environment that produced it, so a result is never silently from elsewhere.
+# `--env prod` / `--env test` pin a single instance.
 #
 # Required configuration:
-#   prefs.global.hosts.graylog            -  Graylog host (e.g. logs.example.com)
-#   prefs.global.keychainMapping.graylog  -  keychain key holding the API token
+#   prefs.global.hosts.graylog                 -  production host (e.g. logs.example.com)
+#   prefs.global.keychainMapping.graylog       -  keychain key holding the prod API token
+# Optional (test environment):
+#   prefs.global.hosts.graylogTest             -  test host; without it, test is skipped
+#   prefs.global.keychainMapping.graylog_test  -  test token key; falls back to the prod
+#                                                 key when unset (shared-token deployments)
 #
 # Optional env:
 #   GRAYLOG_TIMEOUT_SECONDS    default 25
-#   GRAYLOG_HOST_OVERRIDE      forces the host (used by tests and CI dry-runs)
+#   GRAYLOG_ENV                auto|prod|test, same as --env (default auto)
+#   GRAYLOG_HOST_OVERRIDE      forces one host, reported as environment "override"
+#                              (used by tests and CI dry-runs)
 #   GRAYLOG_RANGE_SECONDS      relative search window, default 86400 (24h)
 #   GRAYLOG_LIMIT              max messages to return, default 200
 #
@@ -30,7 +45,9 @@
 # Output (stdout, single JSON object):
 #   {
 #     "fetchedAt": "<ISO8601>",
-#     "source": { "host": "<host>", "transactionId": "..."|null,
+#     "source": { "host": "<host>", "environment": "prod|test|override",
+#                 "searchedEnvironments": [ "prod", ... ],
+#                 "transactionId": "..."|null,
 #                 "conversationId": "..."|null, "query": "..." },
 #     "totalResults": <n>,
 #     "messages": [
@@ -45,12 +62,13 @@
 #   2  missing/expired credential (orchestrator handles the Save Flow)
 #   3  auth rejected on a reachable host (4xx)
 #   4  bad usage
-#   6  host not configured (prefs.global.hosts.graylog is empty)
+#   6  host not configured (the requested environment has no host in prefs)
 
 set -euo pipefail
 
 TRX_ID=""
 CONV_ID=""
+ENVIRONMENT="${GRAYLOG_ENV:-auto}"
 TIMEOUT="${GRAYLOG_TIMEOUT_SECONDS:-25}"
 RANGE="${GRAYLOG_RANGE_SECONDS:-86400}"
 LIMIT="${GRAYLOG_LIMIT:-200}"
@@ -59,32 +77,50 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --trx)  TRX_ID="$2";  shift 2 ;;
     --conv) CONV_ID="$2"; shift 2 ;;
+    --env)  ENVIRONMENT="$2"; shift 2 ;;
     -h|--help)
-      echo "usage: $0 --trx <transaction-id> | --conv <conversation-id>" >&2
+      echo "usage: $0 --trx <transaction-id> | --conv <conversation-id> [--env auto|prod|test]" >&2
       exit 4 ;;
     *)
       echo "ERR: unexpected arg $1" >&2; exit 4 ;;
   esac
 done
 
-# Host comes from prefs (private config); skill templates only show {GRAYLOG_HOST}.
+case "$ENVIRONMENT" in
+  auto|prod|test) ;;
+  *) echo "ERR: --env must be auto, prod or test (got '$ENVIRONMENT')" >&2; exit 4 ;;
+esac
+
+# Hosts and token keys come from prefs (private config); skill templates only
+# show {GRAYLOG_HOST} / {GRAYLOG_TEST_HOST}.
 PREFS="$HOME/.claude/multi-agent-preferences.json"
-HOST="${GRAYLOG_HOST_OVERRIDE:-}"
-if [ -z "$HOST" ] && [ -f "$PREFS" ]; then
-  HOST=$(python3 -c "
-import json
+
+pref_str() {
+  # Usage: pref_str <dotted.path.under.global>  -> value or empty
+  [ -f "$PREFS" ] || { printf ''; return 0; }
+  PREF_PATH="$1" python3 -c "
+import json, os
 try:
-    p = json.load(open('$PREFS'))
-    print(p.get('global', {}).get('hosts', {}).get('graylog') or '')
+    node = json.load(open('$PREFS')).get('global', {})
+    for part in os.environ['PREF_PATH'].split('.'):
+        node = node.get(part, {}) if isinstance(node, dict) else {}
+    print(node if isinstance(node, str) else '')
 except Exception:
     print('')
-")
-fi
-if [ -z "$HOST" ]; then
-  printf '%s\n' '{"status":"blocked","reason":"host-not-configured","service":"graylog","expected_pref":"global.hosts.graylog"}' >&2
-  exit 6
-fi
-HOST=${HOST%/}  # strip trailing slash if any
+" 2>/dev/null || printf ''
+}
+
+HOST_PROD=$(pref_str hosts.graylog)
+HOST_TEST=$(pref_str hosts.graylogTest)
+HOST_PROD=${HOST_PROD%/}
+HOST_TEST=${HOST_TEST%/}
+
+KEY_PROD=$(pref_str keychainMapping.graylog)
+[ -z "$KEY_PROD" ] && KEY_PROD="${USER}_Graylog_Access_Token"
+# A test instance usually issues its own token, but plenty of deployments share
+# one; falling back to the prod key beats refusing to search test at all.
+KEY_TEST=$(pref_str keychainMapping.graylog_test)
+[ -z "$KEY_TEST" ] && KEY_TEST="$KEY_PROD"
 
 if [ -z "$TRX_ID" ] && [ -z "$CONV_ID" ]; then
   echo "ERR: no id (pass --trx <transaction-id> and/or --conv <conversation-id>)" >&2
@@ -104,20 +140,6 @@ if [ -n "$CONV_ID" ]; then
   fi
 fi
 
-# Token via keychain mapping.
-TOKEN_KEY=""
-if [ -f "$PREFS" ]; then
-  TOKEN_KEY=$(python3 -c "
-import json
-try:
-    p = json.load(open('$PREFS'))
-    print(p.get('global', {}).get('keychainMapping', {}).get('graylog') or '')
-except Exception:
-    print('')
-")
-fi
-[ -z "$TOKEN_KEY" ] && TOKEN_KEY="${USER}_Graylog_Access_Token"
-
 # Locate the resolver with an existence check, not a `.`-chain.
 #
 # Sourcing a file that does not exist aborts the shell under `set -e` - `||` included -
@@ -142,50 +164,125 @@ for _cred_resolver in \
 done
 unset _cred_resolver
 if [ -z "${CRED_STORE:-}" ]; then
-  printf '%s\n' '{"status":"blocked","reason":"missing-credential-helper","service":"graylog","expected_key":"'"$TOKEN_KEY"'"}' >&2
+  printf '%s\n' '{"status":"blocked","reason":"missing-credential-helper","service":"graylog","expected_key":"'"$KEY_PROD"'"}' >&2
   exit 2
 fi
 
-TOKEN=$("$CRED_STORE" get "$TOKEN_KEY" 2>/dev/null || true)
-if [ -z "$TOKEN" ]; then
-  printf '%s\n' '{"status":"blocked","reason":"missing-token","service":"graylog","expected_key":"'"$TOKEN_KEY"'"}' >&2
-  exit 2
-fi
+# Graylog relative universal search, built once and reused per environment.
+ENC_QUERY=$(QUERY_IN="$QUERY" python3 -c "
+import os, urllib.parse as up
+print(up.quote(os.environ['QUERY_IN']))
+")
+SEARCH_PATH="search/universal/relative?query=$ENC_QUERY&range=$RANGE&limit=$LIMIT&sort=timestamp:desc"
 
-API_BASE="https://$HOST/api"
+# Set by run_search: the outcome of the most recent environment probe.
+RUN_HTTP=""
+RUN_BODY=""
+RUN_HITS=0
 
-graylog_get() {
-  # Usage: graylog_get <path-and-query-relative-to-API_BASE>
-  # Prints "<body>\n<http_code>"; the caller splits the last line off.
-  local path="$1"
-  local url="$API_BASE/$path"
+run_search() {
+  # Usage: run_search <host> <token-key>
+  local host="$1" token_key="$2" token url resp
+  token=$("$CRED_STORE" get "$token_key" 2>/dev/null || true)
+  if [ -z "$token" ]; then
+    RUN_HTTP="no-token"; RUN_BODY=""; RUN_HITS=0
+    return 0
+  fi
+  url="https://$host/api/$SEARCH_PATH"
   # PAT basic auth: username=<token>, password=literal "token". The credential
   # goes through a curl config via process substitution so it never lands in
   # argv (argv is visible to ps).
-  curl -sS --max-time "$TIMEOUT" --connect-timeout 5 -w "\n%{http_code}" \
-    -K <(printf 'user = "%s:token"\n' "$TOKEN") \
+  resp=$(curl -sS --max-time "$TIMEOUT" --connect-timeout 5 -w "\n%{http_code}" \
+    -K <(printf 'user = "%s:token"\n' "$token") \
     -H "Accept: application/json" \
     -H "X-Requested-By: multi-agent-pipeline" \
-    "$url" 2>/dev/null || true
+    "$url" 2>/dev/null || true)
+  RUN_HTTP=$(printf '%s' "$resp" | tail -n1)
+  RUN_BODY=$(printf '%s' "$resp" | sed '$d')
+  RUN_HITS=0
+  if [ "$RUN_HTTP" = "200" ]; then
+    RUN_HITS=$(BODY_IN="$RUN_BODY" python3 -c "
+import json, os
+try:
+    print(len(json.loads(os.environ['BODY_IN']).get('messages') or []))
+except Exception:
+    print(0)
+" 2>/dev/null || echo 0)
+  fi
+  # An empty RUN_HITS would make the caller's numeric test abort under `set -e`.
+  case "$RUN_HITS" in (*[!0-9]*|"") RUN_HITS=0 ;; esac
 }
 
-# Graylog relative universal search.
-ENC_QUERY=$(QUERY_IN="$QUERY" python3 -c "
-import os, urllib.parse as up
-print(up.quote(os.environ['QUERY_IN']))
-")
-SEARCH_PATH="search/universal/relative?query=$ENC_QUERY&range=$RANGE&limit=$LIMIT&sort=timestamp:desc"
+# Which instances to try, in order. `auto` reaches for test only when prod had
+# nothing to say - either no hits or no answer at all.
+CANDIDATES=""
+if [ -n "${GRAYLOG_HOST_OVERRIDE:-}" ]; then
+  CANDIDATES="override"
+else
+  case "$ENVIRONMENT" in
+    prod) CANDIDATES="prod" ;;
+    test) CANDIDATES="test" ;;
+    auto) if [ -n "$HOST_TEST" ]; then CANDIDATES="prod test"; else CANDIDATES="prod"; fi ;;
+  esac
+fi
+
+host_for() {
+  case "$1" in
+    override) printf '%s' "${GRAYLOG_HOST_OVERRIDE%/}" ;;
+    test)     printf '%s' "$HOST_TEST" ;;
+    *)        printf '%s' "$HOST_PROD" ;;
+  esac
+}
+key_for() {
+  case "$1" in
+    test) printf '%s' "$KEY_TEST" ;;
+    *)    printf '%s' "$KEY_PROD" ;;
+  esac
+}
+
+# A pinned environment with no host is a configuration error, not a degrade:
+# silently searching the other instance would attach the wrong logs.
+for _env in $CANDIDATES; do
+  if [ -z "$(host_for "$_env")" ]; then
+    if [ "$_env" = "test" ]; then
+      printf '%s\n' '{"status":"blocked","reason":"host-not-configured","service":"graylog","environment":"test","expected_pref":"global.hosts.graylogTest"}' >&2
+    else
+      printf '%s\n' '{"status":"blocked","reason":"host-not-configured","service":"graylog","environment":"prod","expected_pref":"global.hosts.graylog"}' >&2
+    fi
+    exit 6
+  fi
+done
 
-RESP=$(graylog_get "$SEARCH_PATH")
-HTTP=$(printf '%s' "$RESP" | tail -n1)
-BODY=$(printf '%s' "$RESP" | sed '$d')
+HOST=""
+ENV_USED=""
+SEARCHED=""
+HTTP=""
+BODY=""
+LAST_CANDIDATE="${CANDIDATES##* }"
+for _env in $CANDIDATES; do
+  SEARCHED="${SEARCHED:+$SEARCHED }$_env"
+  run_search "$(host_for "$_env")" "$(key_for "$_env")"
+  HOST=$(host_for "$_env")
+  ENV_USED="$_env"
+  HTTP="$RUN_HTTP"
+  BODY="$RUN_BODY"
+  # An auth rejection on a reachable host is the only hard failure, and it is
+  # per-instance: a dead test token must not mask a working prod answer, so it
+  # aborts only when no candidate is left to try.
+  if [ "$HTTP" = "401" ] || [ "$HTTP" = "403" ]; then
+    if [ "$_env" = "$LAST_CANDIDATE" ]; then
+      echo "ERR: Graylog auth rejected on $_env (HTTP $HTTP)" >&2
+      exit 3
+    fi
+    continue
+  fi
+  if [ "$RUN_HITS" -gt 0 ]; then break; fi
+done
 
-# A genuine auth rejection on a reachable host is the only hard failure.
-case "$HTTP" in
-  401|403)
-    echo "ERR: Graylog auth rejected (HTTP $HTTP)" >&2
-    exit 3 ;;
-esac
+if [ "$HTTP" = "no-token" ]; then
+  printf '%s\n' '{"status":"blocked","reason":"missing-token","service":"graylog","expected_key":"'"$(key_for "$ENV_USED")"'"}' >&2
+  exit 2
+fi
 
 # Any other non-200 (empty code on connection failure, 5xx, timeout) degrades
 # to an empty result so a log fetch never blocks a run.
@@ -197,7 +294,8 @@ if [ "$HTTP" != "200" ]; then
   BODY=""
 fi
 
-SRC_HOST="$HOST" SRC_TRX="$TRX_ID" SRC_CONV="$CONV_ID" SRC_QUERY="$QUERY" \
+SRC_HOST="$HOST" SRC_ENV="$ENV_USED" SRC_SEARCHED="$SEARCHED" \
+SRC_TRX="$TRX_ID" SRC_CONV="$CONV_ID" SRC_QUERY="$QUERY" \
 DEGRADED_IN="$DEGRADED" DEGRADE_REASON_IN="$DEGRADE_REASON" \
 BODY_IN="$BODY" LIMIT_IN="$LIMIT" \
 python3 - <<'PY'
@@ -239,9 +337,11 @@ if not isinstance(total, int):
     total = len(messages)
 
 result = {
-    "fetchedAt": datetime.datetime.utcnow().isoformat() + "Z",
+    "fetchedAt": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
     "source": {
         "host": os.environ["SRC_HOST"],
+        "environment": os.environ.get("SRC_ENV") or "prod",
+        "searchedEnvironments": (os.environ.get("SRC_SEARCHED") or "").split(),
         "transactionId": trx,
         "conversationId": conv,
         "query": os.environ.get("SRC_QUERY") or "",

package/pipeline/multi-agent-refs/features/url-enrichment.md

@@ -45,7 +45,7 @@ The catalogue is the single source of truth for downstream phases  -  they read
 URL pattern (caught by the extractor): `console.firebase.google.com/(u/[0-9]+/)?project/<projectId>/crashlytics/app/(ios|android)(:|%3A)<bundleOrPackage>/issues/<issueId>(/sessions/<sessionId>)?`
 
 - Host is fixed (`console.firebase.google.com`); no `hosts.firebase` pref needed.
-- Token resolution: `prefs.global.keychainMapping.firebase` → `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from decoded JSON  -  verify it matches the `<projectId>` from the URL; mismatch → warn, skip enrichment.
+- Token resolution, in order: env `FIREBASE_TOKEN_KEY`; the `prefs.global.firebase.accounts[]` entry whose `projectId` equals the URL's project; `prefs.global.keychainMapping.firebase` (single-project setups). Then `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from the decoded JSON  -  verify it matches the `<projectId>` from the URL; mismatch → the fetcher exits `5` naming the key it used and the `accounts[]` entry to add, and enrichment is skipped. Several Firebase projects per team is the normal case (legacy plus redesign, staging plus prod), which is what `accounts[]` exists for.
 - Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only  -  never persist.
 - Resolve the opaque `appId` first: `GET https://firebase.googleapis.com/v1beta1/projects/<projectId>/(iosApps|androidApps)?pageSize=200` and match `bundleId` (iOS) / `packageName` (Android) against the bundle from the URL. The console URL only carries the bundle, and the Crashlytics API only accepts the appId (`1:1234567890:ios:abcdef`). No match in a multi-app project → exit `3`, reason `app-not-found`; never guess at another app.
 - Fetch crash detail with two calls  -  v1alpha has no get-issue-by-id endpoint: `GET .../v1alpha/projects/<projectId>/apps/<appId>/reports/topIssues?pageSize=200` for the summary and metrics (filter to the issue id), and `GET .../apps/<appId>/events?filter.issue.id=<issueId>&pageSize=1` for the newest event, which carries the stack frames, device, OS and breadcrumbs.
@@ -74,10 +74,11 @@ Two entry shapes reach this step, and `metadata.source` says which:
 
 The extractor emits `graylog` entries from free-text trx / conversation ids (labels like `trx`, `trxId`, `transaction id`, `conversationId`, `convId`, `X-conversationId`), not from a URL  -  so these entries carry `"url": null`. When at least one is present, pull the matching diagnostic logs.
 
-- Host comes from `prefs.global.hosts.graylog` (`GRAYLOG_HOST_OVERRIDE` env forces it for tests/CI); no literal host lives in any source file. Missing host → the fetcher exits `6`; log a setup hint and skip.
-- Token resolution: `prefs.global.keychainMapping.graylog` → `~/.claude/lib/credential-store.sh get "<key>"` → Graylog PAT (fallback key `${USER}_Graylog_Access_Token`). Auth is HTTP Basic with the token as username and the literal `token` as password; the token is fed to `curl` only via a `-K` config file (process substitution), never on argv.
+- Hosts come from `prefs.global.hosts.graylog` (production) and the optional `prefs.global.hosts.graylogTest` (`GRAYLOG_HOST_OVERRIDE` forces a single host for tests/CI); no literal host lives in any source file. Missing host for the requested environment → the fetcher exits `6`; log a setup hint and skip.
+- **Environment**: the fetcher defaults to `--env auto`, which searches production and falls back to test when production returns nothing or is unreachable. A trx id minted by a tester does not exist in production, so prod-only search reports "no logs" for a complaint that is fully logged one host over. The result carries `source.environment` and `source.searchedEnvironments[]`; quote the environment whenever the logs are cited, because evidence from test says something different about a production complaint than the same lines from prod. Pin one instance with `--env prod` / `--env test` when the ticket already says which.
+- Token resolution: `prefs.global.keychainMapping.graylog` → `~/.claude/lib/credential-store.sh get "<key>"` → Graylog PAT (fallback key `${USER}_Graylog_Access_Token`). The test instance uses `keychainMapping.graylog_test`, falling back to the production key when unset. Auth is HTTP Basic with the token as username and the literal `token` as password; the token is fed to `curl` only via a `-K` config file (process substitution), never on argv.
 - Fetch logs (VPN required; respect `vpnServices.graylog`): call `~/.claude/lib/fetch-graylog.sh --trx <id>` (or `--conv <id>` for conversation ids) once per extracted id. The fetcher emits a normalized JSON object of matching log messages.
-- Store as `state.graylogContext = { idType, id, messages[], fetchedAt }` (or an array keyed per id when several were extracted).
+- Store as `state.graylogContext = { idType, id, environment, searchedEnvironments[], messages[], fetchedAt }` (or an array keyed per id when several were extracted).
 - Phase 1 Analysis prepends `state.graylogContext` to the agent prompt under the **Referenced External Sources** section as **diagnostic context, advisory only** (never contradicts code; no task is generated from it, no Phase 4 gate).
 - Soft-fail (non-blocking, mirrors Crashlytics): unreachable host / VPN down / network timeout → the fetcher emits a normalized empty object and exits `0`; mark `state.graylogContext = { skipped: "vpn-unreachable" }` and continue. Only a genuine auth rejection (4xx on a reachable host, fetcher exit `3`) is logged as `skipped` with the auth reason. A log fetch never blocks the run.
 

package/pipeline/multi-agent-refs/keychain.md

@@ -127,9 +127,14 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 | `figma`            | Figma              | `${USER}_Figma_Access_Token`       | PAT               |
 | `figma_mcp`        | Figma MCP          | `${USER}_Figma_Mcp_Access_Token`   | OAuth             |
 | `fortify`          | Fortify            | `${USER}_Fortify_Access_Token`     | API Token         |
-| `graylog`          | Graylog            | `${USER}_Graylog_Access_Token`     | API Token         |
-| `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | JSON (base64)     |
+| `graylog`          | Graylog (prod)     | `${USER}_Graylog_Access_Token`     | API Token         |
+| `graylog_test`     | Graylog (test)     | `${USER}_Graylog_Test_Access_Token` | API Token, optional  -  unset falls back to `graylog` |
+| `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | JSON (base64). One key per Firebase project; extras are named `..._Json_<projectId>` and listed in `global.firebase.accounts[]` |
 | `jenkins`          | Jenkins CI         | `${USER}_Jenkins_Access_Token`     | API Token         |
+| `appstore_connect_key_id` | App Store Connect | `${USER}_AppStoreConnect_Key_Id` | Identifier, not a secret |
+| `appstore_connect_issuer_id` | App Store Connect | `${USER}_AppStoreConnect_Issuer_Id` | Identifier, not a secret |
+| `appstore_connect_apple_id` | App Store Connect | `${USER}_AppStoreConnect_Apple_Id` | Email address |
+| `appstore_connect_password_item` | App Store Connect | `${USER}_AppStoreConnect_Password_Item` | Keychain ITEM NAME, not a password |
 |  -                   | Git Identity       | Stored in preferences JSON         | Not Keychain      |
 
 **Key name mapping lives in preferences:**
@@ -147,6 +152,7 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
       "figma_mcp": "${USER}_Figma_Mcp_Access_Token",
       "fortify": "${USER}_Fortify_Access_Token",
       "graylog": "${USER}_Graylog_Access_Token",
+      "graylog_test": null,
       "firebase": "${USER}_Firebase_Access_Json",
       "jenkins": "${USER}_Jenkins_Access_Token"
     }

package/pipeline/multi-agent-refs/setup/app-store-connect.md

@@ -17,9 +17,20 @@ what they hold is not a pasteable secret:
 | `appstore_connect_apple_id` | an email address | same |
 | `appstore_connect_password_item` | a keychain ITEM NAME | the password lives in Apple's own keychain item, referenced as `-p @keychain:<item>` and never read by the pipeline |
 
+All four entries are **iOS-only and optional**: skip them all and the pipeline
+still works, it just reports Gate 2 of `/multi-agent:store-ready` as `SKIPPED`,
+never as a pass.
+
+The tiers mirror the Figma 3-tier shape: Tier 1 = API key (`appstore_connect_key_id`
++ `appstore_connect_issuer_id`), Tier 2 = Apple ID + app-specific password
+(`appstore_connect_apple_id` + `appstore_connect_password_item`), Tier 3 = nothing
+configured.
+
 Ask which tier to configure (picker): **API key** / **Apple ID + app-specific
 password** / **Skip**. Lead with the second when the user says they cannot create
-an API key.
+an API key: creating one needs an Admin or App Manager role in App Store Connect,
+while an app-specific password is generated by the account holder at
+`appleid.apple.com` with no team permission at all.
 
 **API key.** The private key is a FILE and is never copied into the credential
 store. It must sit in a directory `altool` already searches:

package/pipeline/preferences-template.json

@@ -12,6 +12,7 @@
       "figma_mcp": null,
       "fortify": null,
       "graylog": null,
+      "graylog_test": null,
       "usage_ingest": null,
       "firebase": null,
       "jenkins": null

package/pipeline/schemas/complaint-analysis-spec.schema.json

@@ -114,7 +114,12 @@
             "properties": {
               "status": { "type": "string", "enum": ["pending", "ok", "degraded", "skipped"] },
               "totalResults": { "type": "integer", "minimum": 0 },
-              "degradeReason": { "type": ["string", "null"] }
+              "degradeReason": { "type": ["string", "null"] },
+              "environment": {
+                "type": ["string", "null"],
+                "enum": ["prod", "test", "override", null],
+                "description": "v15.15+ - which Graylog instance answered. Test and production are separate instances; a production complaint corroborated only by test logs is insufficient-evidence, not a confirmed bff fault, so the verdict has to know where the lines came from."
+              }
             }
           },
           "repoEvidence": {

package/pipeline/schemas/prefs.schema.json

@@ -143,6 +143,10 @@
             "graylog": {
               "type": ["string", "null"]
             },
+            "graylog_test": {
+              "type": ["string", "null"],
+              "description": "v15.15+ - Keychain key for the TEST Graylog instance. Null or absent falls back to the `graylog` key, which is correct for deployments that share one token across both."
+            },
             "supabase_access": {
               "type": ["string", "null"],
               "description": "Supabase personal access token (Management API). Used by personal-site tooling; not consumed by pipeline phases."
@@ -574,7 +578,11 @@
             },
             "graylog": {
               "type": "string",
-              "description": "Graylog host without scheme, e.g. logs.example.com. Used by the Graylog log-fetch adapter for direct REST API calls. Resolves {GRAYLOG_HOST}."
+              "description": "Graylog PRODUCTION host without scheme, e.g. logs.example.com. Used by the Graylog log-fetch adapter for direct REST API calls. Resolves {GRAYLOG_HOST}."
+            },
+            "graylogTest": {
+              "type": "string",
+              "description": "v15.15+ - Graylog TEST host without scheme. Optional; leaving it unset means fetch-graylog.sh only ever searches production. Test and production are separate instances, so a trx id minted by a tester does not exist in prod and searching prod alone answers 'no logs' for a complaint that is fully logged one host over. Resolves {GRAYLOG_TEST_HOST}."
             },
             "corpDomain": {
               "type": "string",
@@ -582,6 +590,36 @@
             }
           }
         },
+        "firebase": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v15.16+ - Firebase service-account keys. One team routinely owns several Firebase projects (a legacy app and its redesign, staging next to production), each with its own key, and the single keychainMapping.firebase slot forced a choice: a crash URL from the other project then failed the project_id check as if it were misconfigured. Leave this out entirely for a one-project setup - the single slot stays the fallback.",
+          "properties": {
+            "accounts": {
+              "type": "array",
+              "description": "Maps a Firebase projectId to the keychain key holding its service-account JSON. fetch-crashlytics.sh reads the projectId out of the console URL and picks the matching entry; no match falls back to keychainMapping.firebase.",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["projectId", "keychainKey"],
+                "properties": {
+                  "projectId": {
+                    "type": "string",
+                    "description": "Firebase project id exactly as it appears in a console URL, e.g. my-app-prod-1234."
+                  },
+                  "keychainKey": {
+                    "type": "string",
+                    "description": "Keychain key holding this project's service-account JSON (base64 or raw)."
+                  },
+                  "label": {
+                    "type": "string",
+                    "description": "Human label used in error output, e.g. \"redesign prod\". Defaults to the projectId."
+                  }
+                }
+              }
+            }
+          }
+        },
         "fortify": {
           "type": "object",
           "additionalProperties": false,

package/pipeline/scripts/README.md

@@ -26,6 +26,7 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 - `smoke-handoff-contract.sh`  -  phase-boundary structured handoff + handoff-first resume (v10.8.0)
 - `smoke-update-check.sh`  -  Phase 0 Step 0.6 update-check + required-floor contract (v10.9.0, floor v15.14.0)
 - `smoke-context-links.sh`  -  context-link-extractor classification contract, all types (v15.14.0)
+- `smoke-graylog-environments.sh`  -  Graylog prod / test instance resolution + auto fallback (v15.15.0)
 
 ### Schema + state
 - `smoke-schema-validation.sh`  -  all JSON schemas validate