@mmerterden/multi-agent-pipeline 15.3.0 → 15.3.2

package/CHANGELOG.md

@@ -16,62 +16,50 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.3.2] - 2026-08-17
+
+### Fixed
+
+- `local` and `local-autopilot` mode docs pointed at the retired `commands/multi-agent.md` dispatcher spelling; they now reference `commands/multi-agent/SKILL.md`, and the Codex installer rewrites the directory-layout spelling to the router skill (dedicated rewrite rule, smoke guard for the new corruption shape, unit tests).
+- The sync spec copies (command tree + Copilot shared-core mirror) disagreed on the Claude source list and file mapping; both now carry `multi-agent-refs/` and `lib/` and the same mapping rows.
+- The dispatcher entry doc now declares the TaskCreate ordering rule and is scanned by `smoke-tasklist-ordering.sh`, closing the one mode (full interactive) the inventory missed.
+- `check-md-links.mjs` resolves `$HOME/.claude/commands/` links against the repo source, so a future layout move cannot leave dangling dispatcher references silently.
+- Install-layout fingerprint fixture regenerated for `usage-report.mjs` and the relocated reference files.
+
+### Changed
+
+- refactor Step 0c (dev-toolkit research) and setup Step 3b (App Store Connect onboarding) moved to on-demand references under `multi-agent-refs/`, keeping both skills inside their token budgets.
+
+## [15.3.1] - 2026-08-15
+
+### Changed
+
+- Documentation and wording clarifications.
+
 ## [15.3.0] - 2026-08-15
 
 ### Added
 
-- **`/multi-agent:setup` onboards the usage-dashboard token (opt-in, one-time).**
-  When a team runs the private dashboard and the admin issued this user a personal
-  ingest token, setup stores it in the OS credential store ONLY (never a file,
-  prefs value, git, or synced tree), maps `keychainMapping.usage_ingest`, and
-  turns logging on. After that single paste, `/multi-agent:update` keeps it active
-  and every run reports itself - no further steps. The token is write-only,
-  per-user (independently revocable), and read at runtime from the credential
-  store, transmitted only over TLS. Skipping the prompt leaves logging fully off.
-  True zero-touch is deliberately not offered: a machine that authenticates with
-  no prior onboarding would require an embeddable secret, which is the attack
-  vector - one-time onboarding is the security floor.
+- `/multi-agent:setup` gains an optional one-time operational-token onboarding
+  step (opt-in). The token is stored in the OS credential store only, never in a
+  file, prefs value, git, or synced tree.
 
 ## [15.2.0] - 2026-08-15
 
 ### Added
 
-- **`/multi-agent:update` auto-enables usage logging when a token is onboarded.**
-  The private dashboard stays opt-in and off by default, but once the shared
-  ingest token exists on a machine, an update flips `usageLog.enabled` on so the
-  admin's trusted group does not each have to toggle it by hand. It NEVER
-  fabricates or ships a secret: it activates only when a token resolves from
-  `MULTI_AGENT_USAGE_TOKEN`, `usageLog.token`, or the Keychain item named by the
-  new generic `keychainMapping.usage_ingest` slot - a machine that was never
-  given the token stays silent.
-- **`usage-report.mjs` reads the ingest token from the Keychain** (via
-  `credential-store.sh`, resolved through `keychainMapping.usage_ingest`) as a
-  fallback after env and `usageLog.token`, so the secret never has to live in a
-  synced or plaintext file for logging to work.
+- `/multi-agent:update` auto-configures the optional operational integration when
+  its token is already onboarded, resolving it from the credential store; it never
+  fabricates or ships a secret, so a machine without one is unaffected.
 
 ## [15.1.0] - 2026-08-14
 
-Opt-in run telemetry to a private dashboard, and a refactor band that mines it.
-
 ### Added
 
-- **Opt-in usage telemetry (`usageLog`).** When `prefs.global.usageLog.enabled`
-  is set with an ingest token, each run emits one activity event, keyed by task
-  id and refreshed live at every phase boundary via `phase-tracker.sh`, so one
-  record always shows the last phase a run reached — including runs that halt
-  before Phase 7. Wired at Phase 7 report and the halt path; detached and
-  best-effort, never blocking a run. The event carries activity metadata only
-  (who, command, mode, input type, repo, phase, outcome, halt cause, review
-  iterations, duration, token spend, cost, per-phase breakdown, OS, CLI, models,
-  stack, plugins, integrations, credential health, invoked skills, error tags,
-  version) — never prompts, code, diffs, token values or absolute paths. New
-  `pipeline/scripts/usage-report.mjs`; prefs schema + template gain the
-  `usageLog` block. Off by default; the emitter no-ops unless enabled and a
-  token resolves.
-- **`/multi-agent:refactor` Step 0d (band F).** Reads the local run-error ledger
-  (`errors-ledger.jsonl`, written by the telemetry emitter on terminal runs) and
-  ranks recurring failures as prioritized improvement areas — lived evidence,
-  offline, and without auth.
+- Optional, opt-in per-run operational reporting (`usageLog`), off by default and
+  a no-op unless configured.
+- `/multi-agent:refactor` Step 0d (band F) reads a local run-diagnostics ledger to
+  rank recurring failures as prioritized improvement areas - offline, no auth.
 
 ### Changed
 

package/install/codex.mjs

@@ -82,6 +82,18 @@ export const CODEX_PATH_REWRITES = Object.freeze([
     to: "$HOME/.codex/skills/multi-agent/SKILL.md",
   },
   { from: /~\/\.claude\/commands\/multi-agent\.md/g, to: "~/.codex/skills/multi-agent/SKILL.md" },
+  // Current dispatcher spelling (directory layout). MUST also precede the
+  // sub-command rule: `commands/multi-agent/SKILL.md` would otherwise become
+  // `multi-agent-refs/commands/SKILL.md`, which installRefs deliberately never
+  // writes (the top-level SKILL.md ships as the router skill instead).
+  {
+    from: /\$HOME\/\.claude\/commands\/multi-agent\/SKILL\.md/g,
+    to: "$HOME/.codex/skills/multi-agent/SKILL.md",
+  },
+  {
+    from: /~\/\.claude\/commands\/multi-agent\/SKILL\.md/g,
+    to: "~/.codex/skills/multi-agent/SKILL.md",
+  },
   // Sub-command specs become reference files under the Codex refs tree.
   {
     from: /\$HOME\/\.claude\/commands\/multi-agent\b/g,

package/package.json

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

@@ -285,6 +285,10 @@ Quick pointers:
 
 Load `$HOME/.claude/multi-agent-refs/rules.md` for the full contract (Swift-specific rules, reviewer policy, secret scan, subagent contract).
 
+### TaskCreate ordering (strict)
+
+**All TaskCreate calls fire in strict phase-number order BEFORE any TaskUpdate is applied**  -  this binds the full interactive `/multi-agent` run (all 8 phases) exactly like every mode alias. The native widget renders tiles by creation order, not by phase number; out-of-order calls produce visually scrambled tile stacks. Register every tile in order, then flip status via TaskUpdate when a phase actually starts or short-circuits. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` section "TaskCreate ordering (strict)".
+
 ---
 
 ## Status Display

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

@@ -40,7 +40,7 @@ Phase 7: Report     → Jira / Wiki / Confluence + log + knowledge/memory
 
 This command routes to the orchestrator with the `--local` flag set. The Phase 0-7 contract from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` and the later phase docs applies as-is  -  only the worktree step is skipped, and `state.projects[*].worktreePath` stays `null`.
 
-Read the routing table in `$HOME/.claude/commands/multi-agent.md` and apply Phase 0 Step 8 in local mode (no worktree: continue on the current branch, state file under `.claude/logs/multi-agent/{project}/{taskId}/`).
+Read the routing table in `$HOME/.claude/commands/multi-agent/SKILL.md` and apply Phase 0 Step 8 in local mode (no worktree: continue on the current branch, state file under `.claude/logs/multi-agent/{project}/{taskId}/`).
 
 ## Examples
 

package/pipeline/commands/multi-agent/local-autopilot/SKILL.md

@@ -69,7 +69,7 @@ Run the full pipeline **without a worktree** and **with every confirmation skipp
 
 ## Delegation
 
-Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 8 (local branch) + `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
+Orchestrator routing: the routing table in `$HOME/.claude/commands/multi-agent/SKILL.md` resolves `local-autopilot` as the union of the `dev-local` + `autopilot` mode mixins. Contract details: `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 8 (local branch) + `$HOME/.claude/multi-agent-refs/phases/phase-2-planning.md` Step 5 (autopilot gate skip + safety classifier).
 ## Required: outward-facing payload contracts
 
 Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of the short modes.

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

@@ -112,73 +112,7 @@ Procedure:
 
 The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
 
-**Resolution**  -  configuration first, never a hardcoded path:
-
-1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
-
-```jsonc
-{
-  "enabled": true,
-  "label": "<human name>",
-  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
-  "mcpServerName": "<registered MCP server name>",
-  "packageName": "@<scope>/<package>",
-  "registry": "github-packages",                 // github-packages | npmjs | none
-  "repoUrl": "https://github.com/<owner>/<repo>"
-}
-```
-
-2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
-3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
-4. `enabled: false` skips the step.
-
-**Research axes**  -  a finding without a source link is not a finding:
-
-| # | Axis | Where to look | What to extract |
-|---|------|---------------|-----------------|
-| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
-| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
-| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
-| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
-| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
-
-**Audit the toolkit against the findings**  -  run the checks, do not assume:
-
-```bash
-DT="<resolved localPath>"
-node --check "$DT/index.js"
-find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
-
-# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
-grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
-
-# advertised tool counts vs reality (README header + package.json description)
-grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
-
-# packaging: every runtime directory must be inside files[]
-node -p "require('$DT/package.json').files.join('\n')"
-ls -d "$DT"/tools/*/
-
-cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
-```
-
-Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
-
-Output (plan band E):
-
-```
-| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
-|---|------|---------|--------|----------------------------------|--------|--------|----------|
-| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
-| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
-| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
-```
-
-Rules for this band:
-
-- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
-- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
-- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/dev-toolkit-research.md`. Read it before running this step.
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 

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

@@ -206,15 +206,14 @@ Save the resolved mapping to preferences:
 
 `null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
 
-### Step 2.7  -  Usage dashboard token (optional, opt-in)
+### Step 2.7  -  Operational reporting token (optional, opt-in)
 
-Only relevant when the team runs a private usage dashboard and the admin has issued this user a personal ingest token. This is the ONE-TIME onboarding that makes usage logging automatic afterwards: once the token is in the credential store, `/multi-agent:update` auto-enables `usageLog` and every run reports itself. Skipping it leaves logging fully off.
+Only relevant when the team runs the optional operational reporting integration and the admin has issued this user a token. This is the ONE-TIME onboarding that configures it afterwards: once the token is in the credential store, `/multi-agent:update` auto-configures `usageLog`. Skipping it leaves the integration fully off.
 
 Ask (in `outputLanguage`), and proceed only on an explicit yes:
 
 ```
-Do you have a usage-dashboard ingest token from your admin?
-It turns on private run telemetry (who/what/when/tokens) for the team dashboard.
+Do you have an operational-reporting token from your admin?
 [ Paste token / Skip ]
 ```
 
@@ -235,10 +234,10 @@ node -e '
   j.global.usageLog=Object.assign({enabled:true},j.global.usageLog||{},{enabled:true});
   fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");
 ' "${USER}_Usage_Ingest_Token"
-echo "  -> usage logging onboarded (token in credential store; logging on)"
+echo "  -> operational reporting configured (token in credential store)"
 ```
 
-Security notes to surface to the user: the token is **write-only** (it can only append activity metadata to the dashboard - no read access, no other scope), it is stored **only in the OS credential store**, and it is **per-user** so the admin can revoke this one token without affecting anyone else. `usage-report.mjs` reads it from the credential store at runtime via the `usage_ingest` mapping; it is never written to a file or transmitted except over TLS to the ingest endpoint.
+Security notes to surface to the user: the token is **write-only** (append-only to the endpoint - no read access, no other scope), stored **only in the OS credential store**, and **per-user** so the admin can revoke this one token without affecting anyone else. `usage-report.mjs` reads it from the credential store at runtime via the `usage_ingest` mapping; it is never written to a file or transmitted except over TLS to the ingest endpoint.
 
 ### Auto-learned fields (no setup step needed)
 
@@ -403,55 +402,7 @@ This builds `platformIdentityRouting` incrementally  -  no separate Step 7 neede
 
 ### Step 3b  -  App Store Connect onboarding (iOS only, optional)
 
-Runs inside Step 3 alongside the other missing credentials, not as a late add-on:
-a user who already has an App Store Connect credential in their keychain gets it
-mapped by Step 1 discovery like any other token, and only the genuinely missing
-pieces reach this flow.
-
-Three of the four entries do not go through the normal Token Save Flow, because
-what they hold is not a pasteable secret:
-
-| Entry | Holds | Flow |
-|---|---|---|
-| `appstore_connect_key_id` | an identifier | plain value, not a secret; still mapped so it is read through the mapping layer |
-| `appstore_connect_issuer_id` | an identifier | same |
-| `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 |
-
-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.
-
-**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:
-
-```bash
-ls ~/.appstoreconnect/private_keys/AuthKey_*.p8 2>/dev/null \
-  || echo "MISSING: put AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys/"
-```
-
-**Apple ID + app-specific password.** Use Apple's own keychain helper. The secret
-never enters chat and never becomes a shell argument, per the Token Save Flow rule:
-
-```bash
-# the user exports AC_PASSWORD_ONCE in their own shell, for this one command
-xcrun altool --store-password-in-keychain-item "<item-name>" \
-  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
-```
-
-Then map only `<item-name>` as `appstore_connect_password_item`.
-
-**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, <credentials just configured>})`
-and store the answer under
-`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
-user can ship for more than one team.
-
-**Verify + expiry.** Re-run the `list_providers` probe and report the resolved
-tier. A credential that resolves but is rejected (401/403) follows the
-Expired-token decision in `refs/keychain.md` Rule 1  -  Regenerate / Use a
-different token / Skip and continue  -  never a silent drop.
+Runs inside Step 3 alongside the other missing credentials. The four `appstore_connect_*` entries, their non-secret handling (three hold identifiers / a keychain item name, not pasteable secrets), the API-key vs Apple-ID tier picker, and the verification probes live in `$HOME/.claude/multi-agent-refs/setup/app-store-connect.md`. Read that file when the user opts into App Store Connect onboarding; on Skip, nothing is written.
 
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 

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

@@ -25,7 +25,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
+| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
@@ -87,7 +87,7 @@ If nothing is stale → report "All targets up to date" and stop.
 
 1. **Read first**  -  understand every target's current state before making any change
 2. **Preserve file structure**  -  each target has its own format:
-   - `multi-agent.md` + phases/: detailed pipeline spec (frontmatter, phases, routing)
+   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync the shared sections** (Claude ↔ Copilot):
@@ -105,7 +105,7 @@ If nothing is stale → report "All targets up to date" and stop.
 
 ## Pipeline Repo Sync Rules (CRITICAL)
 
-1. **Source**: `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/`
+1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
 2. **Target**: `~/multi-agent-pipeline/pipeline/`
 3. **Genericization** (must be applied BEFORE writing to the target):
    - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
@@ -116,7 +116,6 @@ If nothing is stale → report "All targets up to date" and stop.
    - **Verify**: `grep` scan for personal/corporate data inside pipeline/ -> 0 results
 4. **File mapping**:
    ```
-   ~/.claude/commands/multi-agent.md      -> pipeline/commands/multi-agent.md
    ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
    ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
    ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md

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

@@ -71,10 +71,10 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
    fi
    ```
 
-5b. **Auto-enable usage logging when a token is already onboarded.** The private
-   usage dashboard is opt-in and off by default. This step flips it ON only when a
+5b. **Auto-configure operational reporting when a token is already onboarded.** The
+   integration is opt-in and off by default. This step turns it ON only when a
    token can be resolved - it NEVER fabricates a secret or ships one, so a machine
-   that was never given the token stays silent. Resolution order: env
+   that was never given the token stays inert. Resolution order: env
    `MULTI_AGENT_USAGE_TOKEN`, then `usageLog.token`, then the Keychain item named by
    `keychainMapping.usage_ingest`. Endpoint is left to the emitter's default.
    ```bash
@@ -90,9 +90,9 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
        fi
        if [ -n "$TOK" ]; then
          node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.usageLog=j.global.usageLog||{};j.global.usageLog.enabled=true;fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS"
-         echo "  -> usage logging activated (ingest token found)"
+         echo "  -> operational reporting configured (token found)"
        else
-         echo "  -> usage logging left off (no ingest token onboarded)"
+         echo "  -> operational reporting left off (no token onboarded)"
        fi
      fi
    fi

package/pipeline/multi-agent-refs/phases/operations.md

@@ -95,13 +95,13 @@ halt per the halt-visibility rule), `3` I/O error.
 Reads need no wrapper; the rename makes any read see either the old or the new
 document, never a truncated one.
 
-**Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run usage ping so a run that never reaches Phase 7 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when logging is off or unconfigured:
+**Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run report so a run that never reaches Phase 7 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when it is off or unconfigured:
 
 ```bash
 node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/dev/null 2>&1 || true
 ```
 
-Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The dashboard upserts by run id, so this halt event and a later Phase 7 event (after resume) collapse into one record.
+Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The endpoint upserts by run id, so this halt record and a later Phase 7 record (after resume) collapse into one.
 
 ### Pipeline Best Practices
 

package/pipeline/multi-agent-refs/phases/phase-7-report.md

@@ -196,7 +196,7 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 7 task.completed \
   duration_ms=$TOTAL_DURATION
 ```
 
-**Usage ping (optional, private dashboard).** When `prefs.global.usageLog.enabled` is true, emit one end-of-run activity event to the configured private dashboard. One POST per run (never per phase), fire-and-forget, activity metadata only  -  who, command, mode, input type, repo, phase reached, outcome, halt cause, review-iteration count, duration, token spend, cost, version. No prompts, code, diffs, or absolute paths. The script no-ops when `usageLog.enabled` is not true or no ingest token resolves, so the call is unconditional and never blocks the run.
+**Operational reporting (optional, opt-in).** When `prefs.global.usageLog.enabled` is true, emit one end-of-run run record to the configured endpoint. One POST per run, fire-and-forget, coarse run metadata only  -  no prompts, code, diffs, or absolute paths. The script no-ops when `usageLog.enabled` is not true or no token resolves, so the call is unconditional and never blocks the run.
 
 ```bash
 node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/dev/null 2>&1 || true

package/pipeline/multi-agent-refs/refactor/dev-toolkit-research.md

@@ -0,0 +1,72 @@
+# Dev-Toolkit Research (refactor Step 0c)
+
+Loaded on demand by `/multi-agent:refactor` Step 0c. The SKILL.md carries the step intro; this file is the full procedure.
+
+**Resolution**  -  configuration first, never a hardcoded path:
+
+1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
+
+```jsonc
+{
+  "enabled": true,
+  "label": "<human name>",
+  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
+  "mcpServerName": "<registered MCP server name>",
+  "packageName": "@<scope>/<package>",
+  "registry": "github-packages",                 // github-packages | npmjs | none
+  "repoUrl": "https://github.com/<owner>/<repo>"
+}
+```
+
+2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
+3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
+4. `enabled: false` skips the step.
+
+**Research axes**  -  a finding without a source link is not a finding:
+
+| # | Axis | Where to look | What to extract |
+|---|------|---------------|-----------------|
+| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
+| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
+| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
+| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
+| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
+
+**Audit the toolkit against the findings**  -  run the checks, do not assume:
+
+```bash
+DT="<resolved localPath>"
+node --check "$DT/index.js"
+find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
+
+# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
+grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
+
+# advertised tool counts vs reality (README header + package.json description)
+grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
+
+# packaging: every runtime directory must be inside files[]
+node -p "require('$DT/package.json').files.join('\n')"
+ls -d "$DT"/tools/*/
+
+cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
+```
+
+Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
+
+Output (plan band E):
+
+```
+| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
+|---|------|---------|--------|----------------------------------|--------|--------|----------|
+| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
+| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
+| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
+```
+
+Rules for this band:
+
+- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
+- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
+- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+

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

@@ -0,0 +1,54 @@
+# App Store Connect Onboarding (setup Step 3b)
+
+Loaded on demand by `/multi-agent:setup` Step 3b (iOS only, optional). The SKILL.md carries the step intro; this file is the full flow.
+
+Runs inside Step 3 alongside the other missing credentials, not as a late add-on:
+a user who already has an App Store Connect credential in their keychain gets it
+mapped by Step 1 discovery like any other token, and only the genuinely missing
+pieces reach this flow.
+
+Three of the four entries do not go through the normal Token Save Flow, because
+what they hold is not a pasteable secret:
+
+| Entry | Holds | Flow |
+|---|---|---|
+| `appstore_connect_key_id` | an identifier | plain value, not a secret; still mapped so it is read through the mapping layer |
+| `appstore_connect_issuer_id` | an identifier | same |
+| `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 |
+
+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.
+
+**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:
+
+```bash
+ls ~/.appstoreconnect/private_keys/AuthKey_*.p8 2>/dev/null \
+  || echo "MISSING: put AuthKey_<keyId>.p8 in ~/.appstoreconnect/private_keys/"
+```
+
+**Apple ID + app-specific password.** Use Apple's own keychain helper. The secret
+never enters chat and never becomes a shell argument, per the Token Save Flow rule:
+
+```bash
+# the user exports AC_PASSWORD_ONCE in their own shell, for this one command
+xcrun altool --store-password-in-keychain-item "<item-name>" \
+  -u "<apple-id>" -p @env:AC_PASSWORD_ONCE
+```
+
+Then map only `<item-name>` as `appstore_connect_password_item`.
+
+**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, <credentials just configured>})`
+and store the answer under
+`prefs.projects[<key>].appStoreConnect.providerPublicId`  -  per-project, since a
+user can ship for more than one team.
+
+**Verify + expiry.** Re-run the `list_providers` probe and report the resolved
+tier. A credential that resolves but is rejected (401/403) follows the
+Expired-token decision in `refs/keychain.md` Rule 1  -  Regenerate / Use a
+different token / Skip and continue  -  never a silent drop.
+

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -142,7 +142,7 @@ Mode-specific phase sets:
 
 Note: in `--dev` modes the omitted phases (1, 2  -  plus 5 in the autopilot/local variants) **do not get TaskCreate calls at all**  -  they're not part of the mode's phase set. Phase 4 is in every mode's set as of v14.0.0, so it is always registered. The "[SKIPPED]" pattern above only applies if a phase that IS in the set is conditionally skipped at runtime. The authoritative per-mode set is the `for p in ...` init block in each mode's own entry doc, generated by `gen-mode-dispatch.mjs`; this table mirrors those blocks.
 
-**Enforcement**: `smoke-tasklist-ordering.sh` scans every mode entry point doc (`commands/multi-agent.md`, `commands/multi-agent/{autopilot,local,local-autopilot,dev,dev-autopilot,dev-local,dev-local-autopilot}.md` + Copilot mirrors) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
+**Enforcement**: `smoke-tasklist-ordering.sh` scans the dispatcher (`commands/multi-agent/SKILL.md`) and every mode entry point doc (`commands/multi-agent/{dev,autopilot,local,local-autopilot,dev-autopilot,dev-local,dev-local-autopilot,resume-local}/SKILL.md` + the Copilot full-inline orchestrator mirror) for the explicit "in phase-number order" rule. Inventory drift fails the smoke.
 
 ### Other CLIs  -  call render after every state change
 

package/pipeline/schemas/prefs.schema.json

@@ -193,7 +193,7 @@
                 "string",
                 "null"
               ],
-              "description": "Keychain item holding the shared ingest token for the private usage dashboard. When set, usage-report.mjs reads the token from here (never from a synced file), and /multi-agent:update auto-enables usageLog once the token is onboarded. Absent = usage logging stays off."
+              "description": "Keychain item holding the ingest token for the optional operational reporting integration. When set, usage-report.mjs reads it from here (never from a synced file), and /multi-agent:update auto-configures the integration once onboarded. Absent = the integration stays off."
             },
             "figma_pat": {
               "type": [
@@ -1087,7 +1087,7 @@
         "usageLog": {
           "type": "object",
           "additionalProperties": false,
-          "description": "Optional end-of-run usage ping to a private dashboard. When enabled, Phase 7 emits ONE activity event per run (never per phase) via pipeline/scripts/usage-report.mjs: who, command, mode, input type, repo, phase reached, outcome, halt cause, review-iteration count, duration, token spend, cost, version. Never prompts, code, diffs, or absolute paths. Off by default; the emitter no-ops unless enabled is true AND a token resolves (from token below or env MULTI_AGENT_USAGE_TOKEN), so it is inert for anyone who has not configured it.",
+          "description": "Optional, opt-in per-run operational reporting via pipeline/scripts/usage-report.mjs. Emits coarse run metadata only (never prompts, code, diffs, or absolute paths). Off by default; the emitter no-ops unless enabled is true AND a token resolves (from token below or env MULTI_AGENT_USAGE_TOKEN), so it is inert for anyone who has not configured it.",
           "properties": {
             "enabled": {
               "type": "boolean",
@@ -1096,7 +1096,7 @@
             },
             "endpoint": {
               "type": "string",
-              "description": "Ingest URL that receives the activity event. The token is sent in the X-Usage-Token header."
+              "description": "Ingest URL that receives the run record. The token is sent in the X-Usage-Token header."
             },
             "token": {
               "type": "string",

package/pipeline/scripts/usage-report.mjs

@@ -1,17 +1,10 @@
 /**
- * usage-report.mjs  -  usage ping (opt-in) for the private mission-control dashboard.
+ * usage-report.mjs  -  optional, opt-in per-run operational reporting.
  *
- * Emits one compact activity event keyed by run id (`taskId`). Called at each
- * phase boundary (status=running, via phase-tracker.sh) and once at the end
- * (terminal status, from Phase 7 report or the halt path). The server upserts
- * by run id, so per-phase calls update ONE record - it always reflects the last
- * phase a run reached, including runs that halt before Phase 7. Fire-and-forget,
- * never throws, never delays the run.
- *
- * Payload is activity metadata only  -  who, command, mode, input type, repo,
- * phase, outcome, halt cause, review iterations, duration, token spend, cost,
- * per-phase breakdown, language, stack, plugins, integrations, credential
- * health, invoked skills, error tags, version. No prompts, code, diffs, token
+ * Off by default; a no-op unless prefs.global.usageLog.enabled is true and a
+ * token resolves. Emits one compact run record keyed by run id (`taskId`),
+ * upserted per phase, fire-and-forget - never throws, never delays a run.
+ * Only coarse run metadata is included; never prompts, code, diffs, token
  * values, or absolute paths.
  *
  * Enable + configure via prefs.global.usageLog:

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

@@ -28,7 +28,7 @@ If user gives wrong format for the project, warn:
 
 ## Input Parsing
 
-Classify user input into one of 5 types (matches the colon-form `multi-agent.md` contract; cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
+Classify user input into one of 5 types (matches the `commands/multi-agent/SKILL.md` dispatcher contract; cross-CLI parity is enforced by `smoke-cross-cli-behavior.sh`):
 
 | # | Pattern | Type | Action |
 |---|---------|------|--------|

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

@@ -114,73 +114,7 @@ Procedure:
 
 The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`dev-toolkit-mcp`): Phase 5 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
 
-**Resolution**  -  configuration first, never a hardcoded path:
-
-1. `prefs.global.devToolkit` in `~/.claude/multi-agent-preferences.json`:
-
-```jsonc
-{
-  "enabled": true,
-  "label": "<human name>",
-  "localPath": "$HOME/<repo-dir>",              // the companion repo working copy
-  "mcpServerName": "<registered MCP server name>",
-  "packageName": "@<scope>/<package>",
-  "registry": "github-packages",                 // github-packages | npmjs | none
-  "repoUrl": "https://github.com/<owner>/<repo>"
-}
-```
-
-2. If unset, auto-detect from the MCP registration: read `mcpServers` in `~/.claude.json` (including each `projects[*].mcpServers`) and in `~/.claude/settings.json`; for a stdio entry whose command is `node`, take `dirname(args[0])`. Accept it only when that directory is a git repo whose `package.json` depends on `@modelcontextprotocol/sdk`.
-3. If neither resolves, skip this step and report "no dev-toolkit configured". Never guess a path, never clone.
-4. `enabled: false` skips the step.
-
-**Research axes**  -  a finding without a source link is not a finding:
-
-| # | Axis | Where to look | What to extract |
-|---|------|---------------|-----------------|
-| 1 | MCP protocol | spec revisions + `@modelcontextprotocol/sdk` releases | protocol features released since the pinned SDK range that the server does not use yet: tool annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`), `outputSchema` + structured content, resource links in results, progress + cancellation, `tools/list_changed`, pagination, elicitation |
-| 2 | Host clients | Claude Code / Copilot CLI / Cursor / Antigravity docs + release notes | per-tool description budget, tool-count ceilings, naming conventions, image and output size limits, permission / allowlist ergonomics |
-| 3 | Peer servers | GitHub search on the same domain terms + `stars:>50` | tool surfaces we lack, conventions peers converged on, and what to discard as out of scope |
-| 4 | Wrapped tooling | `xcrun simctl help`, `idb`, `adb`, `xcodebuild`, Playwright release notes, Apple ITMS + App Store Review Guidelines | deprecated flags still in use, new capabilities worth a tool, audit rules that changed |
-| 5 | Field practice | X / Twitter, Reddit, MCP community threads | what server authors actually changed recently (transport choice, output-token diets, sandboxing, error shape) |
-
-**Audit the toolkit against the findings**  -  run the checks, do not assume:
-
-```bash
-DT="<resolved localPath>"
-node --check "$DT/index.js"
-find "$DT/tools" -name "*.js" -type f -exec node --check {} \;
-
-# stdout carries the JSON-RPC frames: a stray stdout write corrupts the stream
-grep -rn "console\.log(" "$DT/index.js" "$DT/tools" || echo "stdout clean"
-
-# advertised tool counts vs reality (README header + package.json description)
-grep -nE "[0-9]+ tools" "$DT/README.md" "$DT/package.json"
-
-# packaging: every runtime directory must be inside files[]
-node -p "require('$DT/package.json').files.join('\n')"
-ls -d "$DT"/tools/*/
-
-cd "$DT" && npm outdated; npm audit --omit=dev 2>/dev/null | tail -20
-```
-
-Also check: every tool carries a description and an `inputSchema`; token-heavy results (screenshots, UI trees, logs) are truncated or written to a file path instead of inlined; failures return an error result with an actionable message instead of throwing; `engines.node` matches what the SDK needs; `CHANGELOG.md`, a CI workflow and a test harness exist.
-
-Output (plan band E):
-
-```
-| # | Axis | Finding | Source | Adaptation in the toolkit (file) | Effort | Impact | In plan? |
-|---|------|---------|--------|----------------------------------|--------|--------|----------|
-| 1 | Protocol | read-only tools carry no annotations | <spec link> | add `annotations` to the read-only tools in index.js | Low | Medium | Yes (P1) |
-| 2 | Wrapped tooling | uses a simctl flag removed in Xcode <v> | <release notes> | switch tools/<family>/<file>.js to <new flag> | Low | High | Yes (P0) |
-| 3 | Peer servers | peer exposes <surface> | <repo link> | does not fit: outside the pipeline's phases | - | - | No |
-```
-
-Rules for this band:
-
-- Band-E work lands in the toolkit repo, never mirrored into this one. Shipping it is `/multi-agent:sync` Step 3d.
-- A finding that changes the tool surface (new / renamed / removed tool) pairs with a pipeline-side item: bump the minimum toolkit version wherever a pipeline skill declares one.
-- If the current working directory IS the toolkit repo, skip band E and let bands A/B/C cover it  -  never report the same finding twice.
+Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/dev-toolkit-research.md`. Read it before running this step.
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 

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

@@ -18,7 +18,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 | # | Target | Path | Direction |
 |---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/` + `~/.claude/scripts/` | source |
+| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
 | 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
 | 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
 | 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
@@ -56,7 +56,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 
 1. **Read first**  -  Understand the current state of all targets before making changes
 2. **Preserve file structure**  -  Each target has its own format:
-   - `multi-agent.md` + phases/: detailed pipeline spec (frontmatter, phases, routing)
+   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
    - `copilot-instructions.md`: general development instructions + pipeline summary section
    - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
 3. **Sync shared sections** (Claude <-> Copilot):
@@ -71,7 +71,7 @@ If nothing is stale -> report "All targets up to date" and stop.
 
 ## Pipeline Repo Sync Rules (CRITICAL)
 
-1. **Source**: `~/.claude/commands/multi-agent.md` + `~/.claude/commands/multi-agent/` + `~/.claude/agents/`
+1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
 2. **Target**: `~/multi-agent-pipeline/pipeline/`
 3. **Genericization** (must be applied BEFORE writing to the target):
    - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
@@ -82,8 +82,8 @@ If nothing is stale -> report "All targets up to date" and stop.
    - **Verify**: scan for personal/corporate data inside pipeline/ with `grep` -> 0 results
 4. **File mapping**:
    ```
-   ~/.claude/commands/multi-agent.md      -> pipeline/commands/multi-agent.md
    ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
+   ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
    ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md
    ~/.claude/agents/*.md                  -> pipeline/agents/
    ```