@mmerterden/multi-agent-pipeline 20.12.0 → 20.15.0

package/pipeline/skills/shared/core/multi-agent-setup/SKILL.md

@@ -1,40 +1,43 @@
 ---
 name: multi-agent-setup
 description: "First-run setup wizard: keychain token discovery, Git Identity onboarding, and pipeline preparation. Use when the pipeline is being set up for the first time, or tokens and git identity need onboarding."
+argument-hint: "[jira-keys | hosts | accounts]  -  optional; no argument runs the whole onboarding"
 user-invocable: true
 metadata:
   language: en
 ---
 
+`$HOME/.claude/multi-agent-refs/` ships with Claude Code.
+
+## Gotchas
+
+- A token is read and written only through `~/.copilot/lib/credential-store.sh`. Never echo it, never pass it on argv, never paste it back to the user.
+- A mapping in `keychainMapping` with no value in the store is not onboarded: offer the Token Save Flow, do not ask for the secret in chat.
+- Hosts are stored without a scheme (`jira.example.com`); the callers add `https://`.
+- Publishing tokens differ by registry: npmjs takes an npm token, GitHub Packages a classic PAT with `write:packages` from the account that owns the scope.
+
 ## Step 0 - What is actually wrong
 
 ```bash
-node "$HOME/.claude/scripts/doctor.mjs"
+node "$HOME/.copilot/scripts/doctor.mjs"
 ```
 
-Run it before the first question and again at the end. The first run turns setup
-from a fixed script into a targeted one: there is no point asking for a token
-that is already mapped and answering. The second run is the only honest way to
-end - "setup complete" is a claim, and the doctor's exit code is the evidence for
-or against it. Report both in `outputLanguage`, and if the second run still shows
-a BLOCK, say so plainly rather than closing on the word "complete".
+Run it before the first question and again at the end. The first run makes setup targeted: never ask for a token that is already mapped and answering. The second run is how setup ends - "setup complete" is a claim, and the doctor's exit code is the evidence. Report both in `outputLanguage`; if the second run still shows a BLOCK, say so plainly rather than closing on the word "complete".
 
-## Setup (Keychain Token + Git Identity Onboarding)
+## Setup (Credential Store + Git Identity Onboarding)
 
-Self-contained setup  -  works with inline `security` commands, no external script **required**. If `$HOME/.claude/scripts/keychain-save.sh` exists, it can be used as an interactive alternative but is not mandatory. The `setup` command starts interactive onboarding.
+Uses `~/.copilot/lib/credential-store.sh` to read/write secrets in the macOS Keychain (`security`, built in); the pipeline is macOS only (ADR-0012). Run `~/.copilot/lib/credential-store.sh doctor` first  -  it prints the platform and whether the backend is usable. The shell driver auto-delegates `get`/`set`/`delete` to the deterministic Python helper at `$HOME/.copilot/scripts/keychain.py` (Python 3 stdlib only, no external deps). The Python path writes both `-l` (label) and `-s` (service) attributes so items are findable regardless of how callers look them up. Set `KEYCHAIN_DELEGATE=0` to force the raw shell path.
 
 ### Step 0  -  Language Selection
 
-Ask BEFORE anything else. The pipeline has two language fields:
+Ask BEFORE anything else, so every subsequent setup prompt and the rest of the pipeline honour the choice. The pipeline has two language axes:
 
-| Field | Controls | Configurable? |
-|---|---|---|
-| `promptLanguage` | The picker's structural UI chrome only: the `AskUserQuestion` `header` chip, host error UI, internal contract identifiers | **No  -  fixed to `en`.** The chip is capped at 12 characters, which most Turkish equivalents overflow. |
-| `outputLanguage` | The assistant's non-interactive explanations, status updates, error messages, and pipeline-generated reports | Yes  -  set here, change later via `/multi-agent-language <en\|tr>` |
+- `promptLanguage`: picker chrome only (the `AskUserQuestion` `header` chip, host error UI, internal contract identifiers). **Not configurable  -  fixed to `en`**; the chip is capped at 12 chars, which most Turkish equivalents overflow.
+- `outputLanguage`: the assistant's non-interactive explanations, status updates, error messages and pipeline-generated reports. Set here, changeable later via `/multi-agent-language <en|tr>`.
 
-`promptLanguage` is seeded as `"en"` and never offered to the user. External payloads (commits, PR/Jira/wiki, reviewer/triage prompts, agent-log.md) always stay English regardless.
+`promptLanguage` is seeded as `"en"` and never offered to the user. **External payloads always stay English** (commits, PR titles/bodies, Jira comments, wiki content, reviewer/triage prompts, agent-log.md).
 
-**Step 0  -  outputLanguage** (English UI per skill-prompt rules):
+The wizard asks one question (English UI per skill-prompt rules):
 
 ```
 Which language should the assistant use for ITS OWN explanations,
@@ -46,62 +49,39 @@ Select (1-2):
 
 **Rules:**
 
-- Already set in prefs → skip silently. Change later via `/multi-agent-language <en|tr>` or `/multi-agent-language output <en|tr>`.
-- New value → validate against `["en", "tr"]`, atomic write to `prefs.global.outputLanguage`, force `prefs.global.promptLanguage = "en"`, echo confirmation in the chosen `outputLanguage`.
-- Unknown input → re-ask once, then abort with a hint pointing to `/multi-agent-language`.
+- **Already set in prefs** → skip silently. User can change later with `/multi-agent-language <en|tr>` or `/multi-agent-language output <en|tr>`.
+- **New value** → validate against the schema enum (`en`, `tr`), write `prefs.global.outputLanguage` via atomic rename, force `prefs.global.promptLanguage = "en"`, then echo a confirmation in the just-chosen `outputLanguage`:
+  - `en`: `outputLanguage=<Y>. promptLanguage stays "en". External payloads (PR bodies, Jira comments, reviewer prompts) stay English regardless.`
+  - `tr`: `outputLanguage=<Y>. promptLanguage "en" sabit. Dış çıktılar (PR açıklamaları, Jira yorumları, review istemleri) her durumda İngilizce kalır.`
+- **Unknown input** → re-ask once, then abort setup with a hint pointing to `/multi-agent-language`.
 
-### Step 1  -  Dynamic Keychain Discovery
+From here on, every prompt in Steps 1-6 follows the per-field matrix in
+`$HOME/.claude/multi-agent-refs/rules.md` ("Language Application"): `question`, `label`
+and `description` render in `outputLanguage`, `header` stays English; wizard status and
+the post-setup summary follow `outputLanguage`. `promptLanguage` governs only the button
+and chip chrome, never the question a user reads.
 
-Instead of checking only hardcoded key names, discover ALL user keys and intelligently map them to services.
+### Step 0.5  -  Dependency check
 
-**1a. Discover all keys:**
 ```bash
-DISCOVERED=$(security dump-keychain 2>/dev/null | grep '"svce"' | awk -F'"' '{print $4}' | grep -i "^${USER}" | sort -u)
-echo "$DISCOVERED"
+~/.copilot/lib/credential-store.sh doctor
+command -v pdftotext >/dev/null 2>&1 || echo "pdftotext: MISSING"
 ```
 
-**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` + NOT `mcp` |
-| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | `figma` + `mcp` |
-| `fortify` | `${USER}_Fortify_Access_Token` | `fortify` |
-| `firebase` | `${USER}_Firebase_Access_Json` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
-| `jenkins` | `${USER}_Jenkins_Access_Token` | `jenkins` |
-| `appstore_connect_private_key` | `${USER}_AppStoreConnect_Private_Key` | (`appstore` or `asc` or `app_store`) + (`private` or `p8`) |
-| `google_play` | `${USER}_GooglePlay_Access_Json` | (`googleplay` or `google_play` or `play_console` or `play`) + (`service` or `account` or `access` or `json` or `console`), NOT `firebase` |
-
-**1c. Resolution logic (per service):**
-
-For each service in the table above, follow this order:
-
-1. **Check standard key** -> `~/.copilot/lib/credential-store.sh get "<standard_key>" 2>/dev/null`
-   - Found -> auto-map, done
-2. **Search discovered keys** -> filter `$DISCOVERED` by the service's search keywords (case-insensitive)
-   - Exactly 1 match -> show: `"Found '${matched_key}' for ${service}  -  use this? (enter=yes / n=skip)"` -> if yes, map it
-   - Multiple matches -> show numbered list, user picks:
-     ```
-     Multiple keys found for GitHub:
-       1. ${USER}_Github
-       2. ${USER}_Github_Access_Token_Old
-       3. ${USER}_Github_Access_Token
-     Select [number] or skip:
-     ```
-   - 0 matches -> MISSING
-
-**1d. Check preferences for existing mapping:**
-
-Before running discovery, check `prefs.global.keychainMapping`. If a mapping already exists for a service AND the mapped key still exists in Keychain -> skip discovery for that service (show as already mapped from preferences).
-
-If a previously mapped key NO LONGER exists in Keychain -> clear the stale mapping, re-run discovery for that service.
+| Output | Action |
+|--------|--------|
+| `Backend: ✓` | Continue to Step 1 |
+| Platform `unknown` or `ERR: macOS only` | Halt  -  the pipeline runs on macOS only (ADR-0012). |
+| `pdftotext: MISSING` | Advisory. Print `brew install poppler`, continue. `.docx` needs nothing. |
+
+### Credential Key Naming Rule
+
+- **New token** (first-time creation in Step 3): ALWAYS use the standard key name (`${USER}_Jira_Access_Token`, etc.). This ensures cross-machine consistency.
+- **Existing token** (discovered in Step 1): NEVER rename or migrate. Map the discovered key name as-is into `keychainMapping`. The mapping layer abstracts the actual key name  -  the pipeline never reads the credential store directly by standard name.
+
+### Step 1  -  Dynamic Credential Discovery
+
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/discovery.md`. Read it for Step 1.
 
 ### Step 2  -  Show Discovery Summary + Save Mapping
 
@@ -122,317 +102,204 @@ Keychain Token Discovery (${USER}):
   Mapped: 8 | Missing: 4
 ```
 
-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,
-      "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
 
-```bash
-node "$HOME/.claude/scripts/usage-register.mjs"
-```
+Ask (in `outputLanguage`), and proceed only on an explicit yes:
 
-Requests a per-machine **write-only** token when none resolves, stores it in the
-credential store only, and switches reporting on. Registration used to happen
-only in update, so a machine that ran setup and nothing else never reported at
-all. `usageLog.optOut: true` blocks it permanently; an unreachable endpoint
-leaves reporting off with one line. Contract:
-`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
-
-### Step 3  -  Jira Project Key (auto-learned)
-
-Jira project keys are NOT asked during setup. They are auto-learned from pipeline usage:
-- User runs `/multi-agent ABC-123` → `ABC` is extracted and saved to `prefs.global.defaultJiraKey` (first ever) and `prefs.projects[{project}].jiraProjectKeys` (per-project).
-- User later runs `/multi-agent MOBILE-456` in a different project → `MOBILE` is added to that project's keys.
-- Multiple keys accumulate over time  -  most recent first, deduped.
+```
+Do you have an operational-reporting token from your admin?
+[ Paste token / Skip ]
+```
 
-Phase 0 Step 1 (Parse Input) handles extraction and persistence. No setup interaction needed.
+On paste, store it in the credential store ONLY - never in a file, prefs value,
+git or any synced tree - under the standard per-user name, so it is revocable on
+its own:
 
-### Step 4  -  Git Identity Setup (one-time)
+```bash
+pbpaste | ~/.copilot/lib/credential-store.sh set "${USER}_Usage_Ingest_Token" -
+pbcopy < /dev/null
+```
 
-Git identities are NOT secrets  -  stored in the preferences file, not Keychain:
+Then, **whether they pasted or skipped**, run:
 
 ```bash
-PREFS_FILE="$HOME/.claude/multi-agent-preferences.json"
+node "$HOME/.copilot/scripts/usage-register.mjs"
 ```
 
-If no identities exist in `prefs.global.gitIdentities` (first run):
-```
-Let's set up git identity.
+It maps whatever token exists and switches reporting on, and requests a
+per-machine write-only one when none resolves. Setup is a registration entry point
+in its own right, so a machine that runs setup and never runs update still reports.
+What is sent, what never is, and `usageLog.optOut`:
+`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
 
-Identity 1 (corporate):
-  Author name: ___
-  Email: ___
-```
+### Auto-learned fields (no setup step needed)
 
-After each identity, ask with a native `AskUserQuestion` picker (never a typed y/n):
-- `question`: "Add another git identity?" (rendered in `outputLanguage`)
-- `header`: "Identity" (English, <=12 chars)
-- `options`:
-  - `{ label: "Add another", description: "Collect one more name + email identity" }`
-  - `{ label: "Done", description: "Finish identity setup and save" }`
+**Jira Project Key**: auto-learned from pipeline usage. User runs `/multi-agent ABC-123` → `ABC` is extracted and saved to `prefs.global.defaultJiraKey` (first ever) and `prefs.projects[{project}].jiraProjectKeys` (per-project). Multiple keys accumulate over time  -  most recent first, deduped. Phase 0 Step 1 (Parse Input) handles extraction.
 
-**Add another** → collect the next identity (e.g. Identity 2, personal: author name + email), then re-ask. **Done** → save.
+**Git Identity**: auto-learned from token onboarding. Each token saved in Step 3 triggers an identity prompt (see Token Save Flow Step C). No separate identity setup step.
 
-Save to preferences JSON:
-```json
-{
-  "global": {
-    "gitIdentities": [
-      {"name": "AUTHOR_NAME", "email": "AUTHOR_EMAIL"},
-      {"name": "AUTHOR_NAME_2", "email": "AUTHOR_EMAIL_2"}
-    ]
-  }
-}
-```
+### Step 3  -  Interactive token onboarding (for missing tokens)
+
+Git identities are NOT asked as a separate step. They are learned when tokens are added via the Token Save Flow below. Each token save triggers an identity prompt:
 
-Show result:
 ```
-Git Identities (saved to preferences):
-  1. {Full Name - Organization} <{corporate@email.com}>
-  2. {Full Name} <{personal@email.com}>
+Token saved. Which git identity uses this token?
+  1. Ada Lovelace <ada@example.com>
+  2. Ada Lovelace <ada@personal.com>
+  n. Create new identity
+Select:
 ```
 
-### Step 5  -  Interactive token onboarding (for missing tokens)
+- First token ever → no existing identities → asks name + email → creates identity → maps token
+- Subsequent tokens → pick existing or create new → maps token to that identity's `servicePatMap`
+- Multiple accounts per platform supported (e.g. two GitHub tokens, each mapped to a different identity)
+- Identity is stored in `prefs.global.identities[]`, token-to-identity binding in `identity.servicePatMap`
 
-For each MISSING service, run the **Token Save Flow** (see `setup.md` for full spec).
+**Legacy compatibility**: If `prefs.global.gitIdentities` (deprecated) is present, `migrate-prefs.mjs` renames it to `identities` automatically.
 
-Summary: ask `[1] Add now / [2] Skip` → if add, user copies token to clipboard, presses Enter → pipeline reads from clipboard via `pbpaste`, saves to Keychain, clears clipboard. Token never appears in terminal.
+For each MISSING service, run the **Token Save Flow** below. When creating new tokens, use the **standard key name** from Step 1b table.
 
-The same flow is reused at Phase 0 runtime when a token is expired (401/403).
+#### Sequential onboarding loop (strict)
 
-### Step 6  -  Verify all
+The Step 2 discovery summary is never the end of setup. Immediately after showing it, walk the missing services ONE BY ONE in this fixed order and run the Token Save Flow for each:
 
-Re-run scan from Step 1. Show final status:
-```
-All tokens present. Pipeline ready to use.
-
-Optional per-project features (configured on first use, nothing to do now):
-  • Phase 5 Report Step 2 Wiki  -  auto-generates component wiki pages + Figma
-    screenshots. Activates when (a) task is a component AND (b) a Figma token
-    is in Keychain. Four adapters supported: submodule / in-repo / github-wiki
-    / separate-repo. First run asks: use auto-detected path, use a custom
-    path, skip once, or disable for this project (persisted).
-  • channels  -  post-hoc multi-channel reporter (Jira/Confluence/Wiki/PR), works on any branch with an open PR. v5.7+ replaces the older `enrich` command.
-  • Default reviewers  -  auto-fetched from Bitbucket default-reviewers endpoint
-    or GitHub CODEOWNERS on first PR.
-
-Next step:
-  /multi-agent "PROJ-12345"              -> start your first task
-  /multi-agent help                      -> full usage guide
-```
+1. `jira`
+2. `bitbucket_token` (then `bitbucket_user` right after, if missing)
+3. `github`
+4. `confluence`
+5. `figma`  -  Figma Personal Access Token (Tier 2, REST)
+6. `figma_mcp`  -  Figma MCP auth (Tier 1); its own prompt, never folded into the PAT prompt
+7. `fortify`
+8. `graylog`
+9. `firebase`
+10. `jenkins`
+11. App Store Connect block (Step 3b; only when the target repo is iOS)
+12. Google Play block (Step 3d; only when the target repo is Android)
 
-If still missing, show which ones and let user skip (pipeline will re-ask for any needed token at Phase 0).
+Loop rules:
 
-### Token -> Source Mapping
-
-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 | Figma Developer Settings (max 90 days) |
-| `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | OAuth | Automatic via Claude Code Figma MCP remote auth |
-| `fortify` | `${USER}_Fortify_Access_Token` | API Token | Fortify SSC -> Token Management (VPN required) |
-| `firebase` | `${USER}_Firebase_Access_Json` | Firebase service-account JSON | Firebase Console -> Project settings -> Service accounts -> Generate new private key. Store the file as issued; project id is read straight out of it. |
-| `jenkins` | `${USER}_Jenkins_Access_Token` | API Token | Jenkins -> User -> Configure -> API Token |
-| `appstore_connect_private_key` | `${USER}_AppStoreConnect_Private_Key` | Full PEM text of `AuthKey_<keyId>.p8` | App Store Connect -> Users and Access -> Integrations -> App Store Connect API. Stored from the file via stdin after `probe-store-key.mjs --asc` accepts it |
-| `google_play` | `${USER}_GooglePlay_Access_Json` | Service-account JSON, as issued | Play Console -> Setup -> API access. Stored from the file via stdin after `probe-store-key.mjs --play` accepts it |
-|  -  | Git Identities | JSON (preferences) | Stored in `$HOME/.claude/multi-agent-preferences.json`  -  not Keychain |
+- **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) - 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).
 
-### Inline Token Save Pattern
+---
 
-All tokens go through `~/.copilot/lib/credential-store.sh`, which wraps the macOS Keychain and auto-delegates to `~/.copilot/scripts/keychain.py`. The Python path writes both `-l` (label) and `-s` (service) attributes so existing manually-added entries with either convention remain findable.
+### Token Save Flow (reusable)
 
-```bash
-# PAT / API Key (from clipboard)
-pbpaste | ~/.copilot/lib/credential-store.sh set "<SERVICE_NAME>" -
-pbcopy < /dev/null  # clear clipboard
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md`. Read it for every token prompt (Steps 3, 3b, 3c and any command that saves a token).
 
-# Non-secret value typed inline (a secret on argv is visible to ps and lands in shell history)
-~/.copilot/lib/credential-store.sh set "<SERVICE_NAME>" "<VALUE>"
+### Step 3b  -  App Store Connect onboarding (iOS only, optional)
 
-# JSON file (stored as issued  -  the store round-trips newlines byte-exactly)
-~/.copilot/lib/credential-store.sh set "<SERVICE_NAME>" - < /path/to/file.json
+Runs inside Step 3. Every part of the API key lives in the Keychain, the `.p8` included: ask for the `.p8` as a path, validate it BEFORE saving with `node "$HOME/.copilot/scripts/probe-store-key.mjs" --asc ...` (exit 0 only), map `appstore_connect_private_key`, store it from the file with `credential-store.sh set appstore_connect_private_key - < <AuthKey_<keyId>.p8>`, run `node "$HOME/.copilot/scripts/write-store-config.mjs"`, then offer (picker, default keep) to delete the file. `store_asc_*` and `ios_testflight_validate` then read the key from the Keychain. The five entries, the tier picker and the probes: `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`. On Skip, nothing is written.
 
-# Read
-~/.copilot/lib/credential-store.sh get "<SERVICE_NAME>"
-```
+### Step 3c  -  Firebase / Crashlytics onboarding (optional)
 
-For maximum stdin hygiene (the secret never lands on argv / shell history), use the Python helper directly with the `-` sentinel:
+Runs inside Step 3. Measure first  -  `bash "$HOME/.copilot/lib/fetch-crashlytics.sh" --probe` answers `tier-1-ready` / `tier-1-no-grant` / `malformed` / `unreachable`  -  then ask by that answer, never blind. Store the Firebase service-account JSON as issued; never base64 it. Skip writes nothing. Then offer appId discovery: `bash "$HOME/.copilot/scripts/firebase-app-discovery.sh" <repo> --json` reads the pairs the repo already carries, for `firebase.accounts[].apps[]`  -  it saves a round trip per run; skipping costs nothing. The picker, both tiers, the role-request wording and the v1alpha caveat: `$HOME/.claude/multi-agent-refs/setup/firebase.md`.
 
-```bash
-pbpaste | ~/.copilot/scripts/keychain.py set "<SERVICE_NAME>" -
-```
+### Step 3d  -  Google Play onboarding (Android only, optional)
 
-### Figma MCP Setup (optional)
+Runs inside Step 3, only when the target repo is Android. One entry, `google_play`: the service-account JSON the toolkit's `store_play_*` tools use, which lets `/multi-agent-store-ready` run Android Gate 2. Ask for the JSON's path, validate BEFORE saving with `node "$HOME/.copilot/scripts/probe-store-key.mjs" --play --service-account <path>`, map `google_play`, then `credential-store.sh set google_play - < <path>` and `write-store-config.mjs`. Account prerequisites, the picker and the probe hints: `$HOME/.claude/multi-agent-refs/setup/google-play.md`. Skip writes nothing.
 
-Figma MCP works in two modes:
+### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 
-**Remote MCP** (Claude Code built-in):
-- Automatic  -  comes as `claude_ai_Figma` in Claude Code settings.json
-- If token renewal needed: re-auth from within Claude Code
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/token-save-flow.md`. Read it for the host question inside the Token Save Flow.
 
-**Local MCP** (@anthropic-ai/figma-mcp package, with PAT):
-```bash
-# 1. Save PAT to keychain (stdin sentinel keeps the value off argv)
-pbpaste | ~/.copilot/scripts/keychain.py set "${USER}_Figma_Access_Token" -
-pbcopy < /dev/null
+### Step 3.6  -  Per-account host overrides (optional)
 
-# 2. Add MCP to Claude Code settings.json
-# ~/.claude/settings.json -> mcpServers -> figma
-```
+**Runs only when** `~/.copilot/lib/account-resolver.sh` returns **more than one** account AND at least one account has Jira or Bitbucket tokens.
 
-### App Store Connect Credentials (optional, iOS only)
+Use case: one user with two identities (e.g. agency + client), each with its own Jira host; `prefs.global.hosts.jira` holds only one default.
 
-Unlocks Gate 2 of `multi-agent-testflight-validation`  -  Apple's own
-`altool --validate-app`, the only check that sees an unregistered bundle ID, a
-profile that does not match the App Store Connect app record, or a version+build
-pair already used. Skipping is a first-class answer: the validation command still
-runs its static audit and guideline review and reports Gate 2 as `SKIPPED` with
-the reason, never as a pass.
+For each non-default account, ask once: "Account {label} has Jira/Bitbucket tokens but no host override yet. Use the global default ({hosts.jira}) or set a per-account host?" with options **1) Use global default** / **2) Set per-account host**. On `2`, prompt for `jiraHost` / `bitbucketHost` / `confluenceHost` (each optional) and save to `prefs.global.accounts[]`, e.g. `{ "id": "client-x", "jiraHost": "jira.client-x.example.com", "bitbucketHost": "bitbucket.client-x.example.com" }`.
 
-Ask (picker): **API key** / **Apple ID + app-specific password** / **Skip**.
+`account-resolver.sh` reads this on every invocation; per-account override wins over `global.hosts.*`. Skip this step on autopilot  -  `accounts[]` stays empty until the user opts in via `/multi-agent-setup accounts`, which opens this editor without re-running token discovery.
 
-**API key**  -  needs an Admin or App Manager role in App Store Connect. Every part
-lives in the Keychain, the `.p8` included. Map the key id and issuer id as
-`appstore_connect_key_id` / `appstore_connect_issuer_id` (identifiers, stored as
-plain values). Ask for the `.p8` as a path, never its contents, and validate it
-BEFORE saving:
+---
 
-```bash
-node "$HOME/.copilot/scripts/probe-store-key.mjs" --asc \
-  --key-id "<key id>" --issuer-id "<issuer id>" --p8 "<path to AuthKey_<keyId>.p8>"
-```
+### Step 4  -  Verify all
 
-It prints `{ok, store, status, hint}` and no key material. On exit 1 show the
-`hint` (`401`: key id / issuer id do not match this `.p8`, the key was revoked, or
-the clock is off; `403`: the key's role cannot read apps) and save nothing. On
-exit 0, map `appstore_connect_private_key` first (`set` resolves the logical key
-through the mapping), then store the file through stdin and write the toolkit's
-store reference file:
+Re-run scan from Step 1. Show final status:
+`All tokens present. Pipeline ready to use.` Then list the optional per-project features (configured on first use, nothing to do now): **Phase 5 Report Step 2 Wiki** (component wiki pages + Figma screenshots; activates when the task is a component AND a Figma token is in Keychain; adapters submodule / in-repo / github-wiki / separate-repo; first run asks: auto-detected path, custom path, skip once, or disable for this project, persisted); **channels** (post-hoc multi-channel reporter for Jira/Confluence/Wiki/PR, any branch with an open PR); **Default reviewers** (auto-fetched from the Bitbucket default-reviewers endpoint or GitHub CODEOWNERS on first PR). Next step: `/multi-agent "PROJ-12345"` to start a first task, `/multi-agent-help` for the full usage guide.
 
-```bash
-~/.copilot/lib/credential-store.sh set appstore_connect_private_key - < "<path to AuthKey_<keyId>.p8>"
-node "$HOME/.copilot/scripts/write-store-config.mjs"
-```
+If still missing, show which ones and let user skip (pipeline will re-ask for any needed token at Phase 0).
 
-Then offer (picker, default **Keep file**) to delete the `.p8` from disk; Apple
-does not let it be downloaded again, so the choice is the user's. The toolkit's
-`store_asc_*` tools and `ios_testflight_validate` (called with neither
-`api_key_id` nor `apple_id`) read the key from the Keychain through that
-reference file.
+### Step 5  -  Repo Discovery (optional)
 
-**Apple ID + app-specific password**  -  usable by **any Apple ID holder, no elevated
-role**, which is the realistic path when API-key creation is not permitted on the
-account. Lead with this option when the user says they cannot create an API key.
-The password goes into Apple's own keychain helper, which is what
-`altool -p @keychain:<item>` reads  -  never into chat, never into an argument:
+Pre-populates the Phase 0 project picker with repos the user is active in, merging three independent sources: local `$HOME` scan (depth 3, repo markers), Bitbucket (last 90 days, token-gated), GitHub (owner + collaborator, push in last 90 days, token-gated). A failing source skips only itself and is reported (never swallowed); discovery is idempotent and never destructive.
 
-```bash
-# export AC_PASSWORD_ONCE in your own shell first, for this one command
-xcrun altool --store-password-in-keychain-item "<item-name>" \
-  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
 ```
+Step 5  -  Repo Discovery (optional)
+Scan for recent repos now to pre-populate the Phase 0 picker?
 
-Map only the ITEM NAME as `appstore_connect_password_item`, plus the Apple ID as
-`appstore_connect_apple_id`. The password stays in the keychain and is referenced,
-never read by the pipeline.
+  y  -  all three (local + Bitbucket + GitHub, ~10-30s)
+  l  -  local scan only (fastest, no network)
+  n  -  skip (Phase 0 will prompt for repo path manually)
+```
 
-**Multi-provider accounts.** A corporate Apple ID often belongs to several
-providers and altool fails opaquely without one. Resolve it once with
-`ios_testflight_validate({list_providers: true, ...})` and store the id under
-`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
-user can ship for more than one team.
+The scan commands, merge-by-origin dedup, the multi-select picker, the `recentProjects` / `serviceStatus` prefs shapes and the skip / degrade rules live in `$HOME/.claude/multi-agent-refs/setup/repo-discovery.md`  -  read that file when the user opts in.
 
-A credential that resolves but is rejected (401/403) follows the Expired-token
-decision (Regenerate / Use a different token / Skip and continue) rather than
-being silently dropped.
+### Step 6  -  Remember as Multi-Repo Group (optional)
 
-### Google Play Credentials (optional, Android only)
+After Step 5, if the user picked **2 or more** repos, offer to remember the combination as a named group; Phase 0's project picker surfaces saved groups at the top, so a multi-repo task becomes a single keypress next time. Auto-skipped if Step 5 was skipped or fewer than 2 repos were selected (single-repo selection is a no-op).
 
-Asked only when the target repo is Android, as the App Store Connect block is asked
-only for iOS. One entry, `google_play`: the service-account JSON the toolkit's
-`store_play_*` tools authenticate with. With it, `multi-agent-store-ready` hands
-Android Gate 2 to Google instead of reporting it `SKIPPED`.
+```
+Step 6  -  Remember as a multi-repo group (optional)
+You picked 2 repos: Checkout, UIComponents.
+Save this combo for one-tap selection in Phase 0?
+  Group name (Enter for auto): [Checkout + UIComponents]
+  Skip with 'n'.
+```
 
-Ask (picker): **Add Google Play** / **Skip**. Before asking for the file, say what
-the account needs: Play Console -> Setup -> API access (link a Cloud project,
-create the service account, download its JSON key); Play Console -> Users and
-permissions (invite the account's `client_email` with app permissions); and the
-**Google Play Android Developer API** plus the **Google Play Developer Reporting
-API** enabled in that Cloud project.
+- **Auto-name** (suggested, editable): 2 repos `"<repoA> + <repoB>"`; 3-4 repos `"<repoA>, <repoB>, <repoC>(+1)"`; 5+ repos `"<repoA> + <count-1> more"`. Labels use the human label from `recentProjects` (path basename, not the full path).
+- **Save** to schema `global.recentGroups[]` (`repos` required, `label` / `count` / `lastUsed` optional), e.g. `{ "label": "Checkout + UIComponents", "repos": ["~/dev/Checkout", "~/dev/UIComponents"], "count": 1, "lastUsed": "2026-04-15T21:08:00Z" }`.
+- **LRU + dedup**: a new group is unshifted to the front. The same set of `repos` (order-independent compare) bumps the existing entry to the front, increments `count`, updates `lastUsed`; do NOT create a duplicate. Schema cap is 10 entries; the oldest past the cap are dropped.
+- **`n`** → not saved; the picker still works for one-time use, and a future Phase 0 selection of the same combo re-prompts.
 
-Ask for the JSON's path, never its contents. Validate BEFORE saving:
+### Step 7  -  Platform Identity Routing (optional)
 
-```bash
-node "$HOME/.copilot/scripts/probe-store-key.mjs" --play --service-account "<path to service-account.json>"
-```
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/identity-routing.md`. Read it for Step 7.
 
-On exit 1 show the `hint` and save nothing: `403` with `SERVICE_DISABLED` means an
-API is off in the Cloud project; any other `403` means the account is not invited
-in Play Console. On exit 0, map `google_play` first, then:
+### Cross-Platform Notes (Step 1-9) and Token -> Source Mapping
 
-```bash
-~/.copilot/lib/credential-store.sh set google_play - < "<path to service-account.json>"
-node "$HOME/.copilot/scripts/write-store-config.mjs"
-```
+Every read and write goes through `~/.copilot/lib/credential-store.sh`, which wraps the macOS Keychain; stay on the helper rather than calling `security` directly. Clipboard handling and the no-backend case: `$HOME/.claude/multi-agent-refs/keychain.md` "Credential store mechanics". Standard key names are a convention for NEW tokens; the key names, token types and where to generate each one live in `$HOME/.claude/multi-agent-refs/keychain.md` "Standard key names". Git identities are stored in preferences, never in the credential store.
 
-### Firebase / Crashlytics Access (optional, any platform)
+### Inline Token Save Pattern
 
-Discovery maps a stored service-account JSON like any other credential, but it
-cannot see the thing that decides whether Crashlytics is readable: a freshly
-generated `firebase-adminsdk-*` account authenticates perfectly and holds no
-Crashlytics role. Measure it, do not assume it:
+All tokens go through `~/.copilot/lib/credential-store.sh` (auto-delegates to `~/.copilot/scripts/keychain.py`, see Setup above).
 
 ```bash
-bash "$HOME/.claude/lib/fetch-crashlytics.sh" --probe
-```
+# PAT / API Key / JSON contents (from clipboard)
+pbpaste | ~/.copilot/lib/credential-store.sh set "<SERVICE_NAME>" -
+pbcopy < /dev/null  # clear clipboard
+
+# Non-secret value typed inline (a secret on argv is visible to ps and lands in shell history)
+~/.copilot/lib/credential-store.sh set "<SERVICE_NAME>" "<VALUE>"
 
-Ask (picker): **Complete tier 1** / **Set up tier 2** / **Skip**.
+# Key file from disk (the .p8, the Google Play JSON; or when the clipboard is unavailable)
+~/.copilot/lib/credential-store.sh set "<SERVICE_NAME>" - < /path/to/file.json
 
-**Tier 1 - service account.** Store the JSON exactly as Firebase Console issued
-it; it is multi-line and the store round-trips it byte for byte. Never base64 it -
-a wrapper on the way in that nothing unwraps on the way out is how this path
-stayed broken. When the probe says `tier-1-no-grant`, the fix is one line to an
-Owner: grant `roles/firebasecrashlytics.viewer` on the project to that service
-account. Read-only, and narrower than `roles/firebase.viewer`.
+# Read  -  a JSON value comes back exactly as it was stored, newlines included
+~/.copilot/lib/credential-store.sh get "<SERVICE_NAME>"
 
-**Tier 2 - interactive session + MCP.** `firebase login` opens a browser and does
-not work from inside an agent harness; the user runs it in their own terminal.
-Both halves are required - a login with no MCP server registered reaches nothing.
-It is the bridge while a role request moves, never the durable answer: autopilot
-and url-enrichment run with nobody at the keyboard.
+# Maximum stdin hygiene (the secret never lands on argv / shell history): the Python helper with the - sentinel
+pbpaste | ~/.copilot/scripts/keychain.py set "<SERVICE_NAME>" -
+```
 
-**appId discovery.** `scripts/firebase-app-discovery.sh <repo> --json` reads the
-bundle-id / appId pairs the repo's `GoogleService-Info*.plist` and
-`google-services.json` already carry, shaped for
-`prefs.global.firebase.accounts[].apps[]`. Merging them saves the fetcher a
-Management API round trip per run; skipping it changes nothing else.
+### Figma MCP Setup (Remote / Local question)
 
-Full mechanics and the v1alpha caveat: `multi-agent-refs/setup/firebase.md`.
+Full procedure: `$HOME/.claude/multi-agent-refs/setup/figma.md`. Read it for the Figma MCP question.
 
 ### Security Rules
 
@@ -444,25 +311,40 @@ Full mechanics and the v1alpha caveat: `multi-agent-refs/setup/firebase.md`.
 
 ### Setup from Scratch Summary
 
-To set up multi-agent on a new machine:
+On a new machine: (1) `npx @{npm-scope}/multi-agent-pipeline install`; (2) `/multi-agent-setup`; (3) the interactive flow: token scan (shows what is missing) -> Git Identity creation (name + email) -> inline commands for missing tokens -> final verification; (4) ready: `/multi-agent "PROJ-12345"`, `/multi-agent "https://github.com/.../issues/42"` or `/multi-agent "bug description"`.
 
-```
-1. Install the toolkit:
-   npx @mmerterden/multi-agent-pipeline install
-
-2. Start setup:
-   /multi-agent setup
-
-3. Interactive flow:
-   -> Token scan (shows what is missing)
-   -> Git Identity creation (name + email)
-   -> Inline commands for missing tokens
-   -> Final verification
-
-4. Ready:
-   /multi-agent "PROJ-12345"
-   /multi-agent "https://github.com/.../issues/42"
-   /multi-agent "bug description"
-```
+All tokens are optional in the sense that every service can be answered with Skip  -  but the ASKING is not optional: the Step 3 sequential loop still walks every missing service one by one (token → author → host). Phase 0 re-asks at runtime only for tokens the user skipped here.
+
+### Step 8  -  Enforcement hooks (optional, Claude Code)
+
+Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus three capture hooks that block nothing (`PreCompact`, `SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+
+- Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
+- On Yes, deep-merge EVERY event in the template's `hooks` object, not `PreToolUse` alone - merging one event silently drops the capture hooks. Preserve existing hooks; never duplicate a matcher already calling the same script.
+- Say what the merge does NOT cover: only the three gates need no run-specific arguments, so only they are hookable; the rest are phase-enforced.
+- Say what it does not turn on: the read-size gate is inert until `prefs.global.bulkRead.mode` is set. Recommend `observe` first. Why, and the Phase 3 exemption: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+
+### Step 9  -  Default stack plugin enablement
+
+Stack skills ship as versioned plugins in the `{owner}/multi-agent-plugins` marketplace. On first setup, wire the stack so the pipeline works out of the box.
+
+1. Ensure the marketplace is known (idempotent):
+   ```bash
+   bash "$HOME/.copilot/scripts/plugin-refresh.sh" {owner} --add-only
+   ```
+2. Ask the detector, then derive (no marker list here; a second list would drift from the detector):
+
+   ```bash
+   eval "$(bash $HOME/.copilot/lib/stack-detect.sh "$PROJECT_ROOT")"   # MA_STACKS, MA_STACK_WHY
+   node -e 'import(process.env.HOME+"/.copilot/scripts/_stack-routing.mjs").then(m=>
+     console.log(m.pluginsForStacks(process.argv[1].split(" ").filter(Boolean)).plugins.join(" ")))' "$MA_STACKS"
+   ```
+
+   Report `MA_STACK_WHY` with the result. `ai-common-toolkit` and
+   `ai-analyst-toolkit` are in every answer, the empty one included: neither is
+   stack-specific. **No marker matched is an answer** - those two, not a guess.
+   A name the marketplace does not carry is dropped with `dropped[]` naming it,
+   so a toolkit that was never shipped is caught before it fails to load.
+3. Report the enabled set. To change later, run `/multi-agent-stack <ios|android|web|backend|...>` in the repo. Pipeline Phase 1 auto-detects the stack for its own routing regardless of enablement.
 
-All tokens are optional  -  pipeline will ask for any needed token at Phase 0. Setup only does pre-preparation.
+The marketplace name (`multi-agent-plugins`) is generic; a different org points `{owner}` at its own fork.