@mmerterden/multi-agent-pipeline 15.15.0 → 15.16.0

package/CHANGELOG.md

@@ -16,6 +16,19 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.15.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/setup/SKILL.md

@@ -92,32 +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` |
-| `graylog_test` | `${USER}_Graylog_Test_Access_Token` | `graylogTest` |
-| `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):**
 
@@ -184,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)
@@ -370,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
@@ -409,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):
 
@@ -431,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:
 
@@ -443,27 +435,28 @@ Service host  -  needed to build API URLs for this token.
 
 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.
 
-For Jira specifically, also ask for the default project key (the token is useless without one for new-issue creation):
+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:
 
-```
-Default Jira project key (e.g. PROJ): ___
+```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.
@@ -709,21 +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) |
-| `graylog_test` | `${USER}_Graylog_Test_Access_Token` | same | Same page on the TEST instance; optional |
-| `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/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.

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

@@ -129,8 +129,12 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 | `fortify`          | Fortify            | `${USER}_Fortify_Access_Token`     | API Token         |
 | `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)     |
+| `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:**

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/schemas/prefs.schema.json

@@ -590,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,