@mmerterden/multi-agent-pipeline 16.11.0 → 16.13.0

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

@@ -9,14 +9,14 @@ Called with no args or `help`, show the usage guide in the user's preferred lang
 
 ## Language resolution
 
-Help is the assistant's own explanation to the user  -  render it in `prefs.global.outputLanguage`. Fall back to `prefs.global.promptLanguage` for legacy prefs files where `outputLanguage` did not exist yet. Two valid values: `"en"` (default) and `"tr"`. If both fields are missing / malformed → treat as `"en"`.
+Help is the assistant's own explanation to the user  -  render it in `prefs.global.outputLanguage`, falling back to `prefs.global.promptLanguage` on prefs files written before it existed. Two valid values: `"en"` (default) and `"tr"`; missing or malformed → `"en"`.
 
 ```bash
 PREFS="$HOME/.claude/multi-agent-preferences.json"
 LANG=$(jq -r '.global.outputLanguage // .global.promptLanguage // "en"' "$PREFS" 2>/dev/null || echo "en")
 ```
 
-Render **exactly one** of the two blocks below  -  the one matching `LANG`. Do not print both; the user asked for a display, not a bilingual dump.
+Render **exactly one** of the two blocks below  -  the one matching `LANG`. Never print both.
 
 ---
 
@@ -59,7 +59,7 @@ Pipeline (after Phase 0)  -  shown as visual cards in terminal:
                            only; a Short run has no plan, autopilot may not ask)
   Phase 3:   Dev        -> TDD: test -> code -> build (Sonnet) + build queue
   Phase 4:   Review     -> Deterministic gates + parallel AI review + Fable triage
-                          (Claude Code: Fable + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
+                          (Claude Code: Fable + Opus + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
   Phase 5:   Test       -> Optional: switch to branch, test in Xcode
                           (only /multi-agent has it; every autopilot and local entry drops it)
   Phase 6:   Commit     -> Commit -> push -> PR + issue body update (never auto-closes)
@@ -127,12 +127,12 @@ Post-Hoc & Side-Channel:
   /multi-agent:build-optimize iOS-only Xcode build perf wrapper → benchmark + analyze + recommend-first .build-benchmark/optimization-plan.md
   /multi-agent:create-jira ["desc"] [figma-url] [swagger-url]  Create a Jira Task/Bug/Story matching team conventions (asks type + mining + active sprint + auto-sizing sections + preview & approval)
   /multi-agent:diff-explain   Map a Phase 4 triage finding back to specific diff lines
+  /multi-agent:graph         Build and query the repo code graph (symbols, imports, references), LLM-free
   /multi-agent:search         Cross-task log search with smart ranking; --semantic queries triage corpus
   /multi-agent:scan           Skill security scan against tiered pattern catalog
   /multi-agent:refactor       Best practices + bug hunt + upstream drift + toolkit MCP research -> one plan, approval, dev + sync
   /multi-agent:store-ready [repo] [--archive=|--ipa=|--aab=|--apk=] [--skip-sweep]  Pre-submission store readiness, iOS + Android, local-only: three symmetric gates per platform plus the running-app sweep. A skipped gate is never a pass. Validates only, never uploads.
-  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  iOS-pinned alias of :store-ready, kept because it is
-                              the name you reach for when the target is TestFlight. Same three gates, one implementation.
+  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  iOS-pinned alias of :store-ready. Same three gates, one implementation.
   /multi-agent:ios-coding-standard [module]  Audit an iOS module against the 99-rule coding-standard registry -> remediation
                               plan + one-page onboarding summary -> hand off to /multi-agent or :local. Read-only, never edits source.
 
@@ -143,7 +143,7 @@ Setup & Maintenance:
   /multi-agent:stack [ids...]  Enable stack plugin(s); multi-select: ids together (ios backend) or no arg -> native picker (common always on)
   /multi-agent:sync           Sync ecosystem (Claude Code + Copilot CLI + pipeline + website + toolkit MCP)
   /multi-agent:update         Pull latest pipeline + reinstall + run migrations
-  /multi-agent:uninstall      Uninstall pipeline from every CLI (--all-data also clears settings + logs; Keychain tokens always intact, double confirm)
+  /multi-agent:uninstall      Uninstall pipeline from every CLI (--all-data also clears settings, logs, memory + knowledge; tokens always intact)
 
 ------------------------------------------------------------
 
@@ -334,7 +334,7 @@ Pipeline (Phase 0'dan sonra)  -  terminalde görsel kart olarak görünür:
                            etkileşimli; Kısa'da plan yok, autopilot soru soramaz)
   Phase 3:   Dev        -> TDD: test -> kod -> build (Sonnet) + build queue
   Phase 4:   Review     -> Deterministik kapılar + paralel AI review + Fable triage
-                          (Claude Code: Fable + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
+                          (Claude Code: Fable + Opus + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
   Phase 5:   Test       -> Opsiyonel: branch'e geç, Xcode'da test
                           (yalnız /multi-agent'ta var; her autopilot ve local girişi düşürür)
   Phase 6:   Commit     -> Commit -> push -> PR + issue body güncelleme (hiç auto-close yok)
@@ -401,12 +401,12 @@ Post-Hoc & Side-Channel:
   /multi-agent:build-optimize iOS-only Xcode build performance wrapper → benchmark + analiz + recommend-first .build-benchmark/optimization-plan.md
   /multi-agent:create-jira ["açıklama"] [figma-url] [swagger-url]  Takım standartlarına uygun Jira Task/Bug/Story oluştur (tip sorar + convention mining + aktif sprint + auto-sizing bölümler + önizleme & onay)
   /multi-agent:diff-explain   Phase 4 triage bulgusunu diff satırlarına eşle
+  /multi-agent:graph         Repo kod grafiğini kur ve sorgula (semboller, import'lar, referanslar), LLM'siz
   /multi-agent:search         Task log'larında akıllı arama; --semantic triage corpus'unu sorgular
   /multi-agent:scan           Skill güvenlik taraması (tiered pattern catalog)
   /multi-agent:refactor       Uyarlanmış best-practice + bug avı + upstream-drift + multi-agent-toolkit MCP araştırması -> tek plan, onay, dev + sync
   /multi-agent:store-ready [repo] [--archive=|--ipa=|--aab=|--apk=] [--skip-sweep]  Yükleme öncesi store hazırlığı, iOS + Android, yalnızca lokal: platform başına 3 simetrik kapı artı çalışan-app sweep'i. Atlanan kapı asla pass sayılmaz. Sadece doğrular, asla yüklemez.
-  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  :store-ready'nin iOS'a sabitlenmiş alias'ı; hedef
-                              TestFlight olduğunda akla gelen isim olduğu için korunuyor. Aynı 3 kapı, tek implementasyon.
+  /multi-agent:testflight-validation [repo] [--ipa=|--archive=]  :store-ready'nin iOS alias'ı. Aynı 3 kapı, tek implementasyon.
   /multi-agent:ios-coding-standard [modül]  Bir iOS modülünü 99 kurallık kodlama-standardı registry'sine göre denetler -> düzeltme
                               planı + tek sayfalık onboarding özeti -> /multi-agent veya :local'e devreder. Read-only, kaynağı hiç düzenlemez.
 
@@ -417,7 +417,7 @@ Setup & Maintenance:
   /multi-agent:stack [ids...]     Stack plugin'lerini etkinleştir; çoklu seçim: id'ler yan yana (ios backend) ya da argümansız -> native picker (common hep açık)
   /multi-agent:sync               Ekosistemi senkronize et (Claude Code + Copilot CLI + pipeline + website + multi-agent-toolkit MCP)
   /multi-agent:update             En son pipeline'ı çek + reinstall + migration çalıştır
-  /multi-agent:uninstall          Pipeline'ı tüm CLI'lerden kaldır (--all-data ayar + logları da siler; Keychain token her zaman dokunulmaz, çift onay)
+  /multi-agent:uninstall          Pipeline'ı tüm CLI'lerden kaldır (--all-data ayar, log, hafıza + bilgi tabanını da siler; token'a dokunulmaz)
 
 ------------------------------------------------------------
 

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

@@ -34,7 +34,7 @@ You already did the work locally  -  wrote code on the current branch and maybe
 
 ```
 Phase 0: Init          → project/branch detect, resolve base + diff (work-already-done), Jira id, state (NO worktree)
-Phase 4: Review        → deterministic gates + parallel review (Fable + Sonnet) + Fable triage
+Phase 4: Review        → deterministic gates + parallel review (Fable + Opus + Sonnet) + Fable triage
 Phase 5: Build+Test    → stack-aware build gate + run existing tests; SUCCESS required (automated, not the interactive user-test)
 Phase 6: Commit        → commit remaining local changes + push + open PR if none exists
 Phase 7: Report        → technical analysis + Jira comment with test scenarios (channels: Jira / PR / Confluence / Wiki)
@@ -52,7 +52,7 @@ Phases 1-3 (Analysis / Planning / Dev) are skipped by design  -  `ship` treats t
 
 ## Phase execution (reuse the existing phase contracts)
 
-- **Phase 4 Review** - run per `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + Sonnet on Claude Code; GPT + Opus + Sonnet on Copilot CLI), Fable triage → `triage.accepted`. Blocking/important accepted findings:
+- **Phase 4 Review** - run per `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` against the resolved diff: deterministic gates (Step 1.x), stack-specific parallel reviewers (Fable + Opus + Sonnet on Claude Code; GPT + Opus + Sonnet on Copilot CLI), Fable triage → `triage.accepted`. Blocking/important accepted findings:
   - interactive: present them and ask (`AskUserQuestion`) whether to fix now (loop back through a minimal Phase-3-style TDD fix) or proceed;
   - `autopilot` (or `prefs.global.resumeLocal.autoFix == true`): auto-fix accepted blocking/important findings, then re-review the fix, before advancing.
 - **Phase 5 Build+Test** - the **automated success gate** (this is what "build+test success" means here; the interactive device user-test is `/multi-agent:manual-test`). Stack-aware: build via `figma-config.build` (iOS scheme / Android gradle / detected backend/web build) and run the existing test suite if present (`swift test` / `xcodebuild test` / `./gradlew test` / `pytest` / `npm test` / `vitest`). Require success to advance; on failure, surface logs and (interactive) stop or (autopilot) attempt a bounded fix loop. **If the repo has no tests, report "no tests present" - never fabricate test results.**

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

@@ -1,6 +1,6 @@
 ---
-description: "Run parallel review on a branch's diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments and sets approve/needs-work review state. Use when a branch diff or a pull request needs reviewing before it merges."
-description-tr: "Bir branch diff'i veya Pull Request üzerinde paralel review koşar: Claude Code'da 2 model (Fable + Sonnet), Copilot CLI'da 3 model (GPT + Opus + Sonnet). PR girdisinde bulgu başına inline yorum atar ve approve/needs-work durumunu işaretler."
+description: "Run parallel review on a branch's diff or a Pull Request: 3 models on Claude Code (Fable + Opus + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments and sets approve/needs-work review state. Use when a branch diff or a pull request needs reviewing before it merges."
+description-tr: "Bir branch diff'i veya Pull Request üzerinde paralel review koşar: Claude Code'da 3 model (Fable + Opus + Sonnet), Copilot CLI'da 3 model (GPT + Opus + Sonnet). PR girdisinde bulgu başına inline yorum atar ve approve/needs-work durumunu işaretler."
 argument-hint: "[#N | repo#N | PR-URL | branch]  -  optional: PR by number/URL, repo+number, or local branch. Supports GitHub and Bitbucket Server URLs. If omitted (interactive), open GitHub + Bitbucket PRs are listed for multi-select; autopilot falls back to the current branch."
 ---
 
@@ -175,7 +175,7 @@ Scope note: a guide governs only files under its own directory  -  a guide found
 
 ### 3. Launch parallel reviewers  -  host-CLI dependent
 
-**Claude Code (2 in parallel):**
+**Claude Code (3 in parallel):**
 - Agent 1: `claude-fable-5` → security + architecture
 - Agent 2: `claude-sonnet-5` → general quality
 

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

@@ -16,7 +16,7 @@ Read `$HOME/.claude/multi-agent-refs/analysis/review.md` and execute it:
 
 1. **Resolve** the document from a local path, a Confluence URL or `pageId`, or a Jira key. With no argument, offer the recent analyses from `~/Desktop/multiAgentAnalysis/` and from each selected repo's `analysis/`, newest first.
 2. **Deterministic gates first**: `validate-analysis-doc.mjs` on the document, and `build-references.mjs --check` when the run's state JSON is available (`--state`, or a fresh analysis). Their output is reported verbatim, before any model reads the document. A finding a script already proves does not need an opinion.
-3. **Parallel model review** against the rubric (buildability, evidence, spine, altitude, admitted gaps, contradiction), CLI-aware: 2 models on Claude Code, 3 on Copilot CLI.
+3. **Parallel model review** against the rubric (buildability, evidence, spine, altitude, admitted gaps, contradiction), CLI-aware: 3 models on Claude Code, 3 on Copilot CLI.
 4. **Fable triage** into Blocker / Important / Suggestion, dropping duplicates and anything the document answers elsewhere.
 5. **Report**, naming the profile it judged against and, explicitly, what was NOT checked.
 6. **Output** on request only: chat (default), Confluence comment, Jira comment, or a `-review.md` beside the document.

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

@@ -16,7 +16,7 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 | Arg | Meaning |
 |---|---|
 | (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, multi-agent-toolkit MCP server. |
-| `release` | Full sync + version bump + tag + npm publish + website deploy (includes the multi-agent-toolkit ship path) |
+| `release` | Full sync + version bump + tag + npm publish + website deploy (plus the multi-agent-toolkit ship path) |
 | `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `--platform=<macos\|linux\|windows>` | Override automatic platform detection. For CI / cross-platform smoke. |
 | `"change description"` | Apply the description to every target at once |
@@ -59,7 +59,7 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 53 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 54 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 51 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
@@ -166,7 +166,7 @@ If nothing is stale → report "All targets up to date" and stop.
 Unlike the Copilot step, this one does **not** hand-copy files. The Codex tree is a
 *transform* of the Claude tree, not a mirror of it, and the transform is real work:
 
-- the 53 sub-command specs become reference files, because Codex silently truncates
+- the 54 sub-command specs become reference files, because Codex silently truncates
   its skills block (see `cross-cli-contract.md` 2.6 for the measurement)
 - every `$HOME/.claude/...` reference to a CLI-owned tree is retargeted, with
   `agents/<persona>.md` becoming `.toml` and the dispatcher becoming the router skill
@@ -467,7 +467,7 @@ When invoked with the `release` argument:
 3. LINT + TEST   ESLint + smoke tests
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
-6. PUSH          git push --tags -> release.yml auto-publish
+6. PUSH          git push --tags; publish is local (release.yml off)
 7. DEV-TOOLKIT   Ship the companion MCP server if it moved (Step 3d gates, then publish)
 8. WEBSITE       Version + features -> {website-host} (maintainer identity, build verified Ready)
 9. COPILOT       Copilot CLI instructions + skills sync
@@ -489,18 +489,18 @@ same 51 specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**53 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**54 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels,
 complaint-analysis, create-jira, design-check, dev, dev-autopilot, dev-local,
-dev-local-autopilot, diff-explain, feedback, forget, garbage-collect, help,
-ios-coding-standard, issue, jira, kill, language, local, local-autopilot,
-log, manual-test, prune-logs, prune-prompts, purge, refactor, resume,
-resume-local, review, review-analysis, review-issue, review-jira, routines,
-save, scan, search, setup, stack, status, store-ready, sync, test,
-test-accessibility, test-dark-mode, test-dynamic-type, test-screenshots,
-testflight-validation, uninstall, update
+dev-local-autopilot, diff-explain, feedback, forget, garbage-collect,
+graph, help, ios-coding-standard, issue, jira, kill, language, local,
+local-autopilot, log, manual-test, prune-logs, prune-prompts, purge,
+refactor, resume, resume-local, review, review-analysis, review-issue,
+review-jira, routines, save, scan, search, setup, stack, status,
+store-ready, sync, test, test-accessibility, test-dark-mode,
+test-dynamic-type, test-screenshots, testflight-validation, uninstall, update
 ```
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific

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

@@ -1,7 +1,7 @@
 ---
-description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings and logs. Asks for double confirmation. Use when the pipeline should be removed from Claude Code and Copilot CLI."
+description: "Uninstall the pipeline from Claude Code + Copilot CLI. Keychain access tokens are always left untouched; --all-data also clears pipeline settings, logs, per-repo memory and the knowledge base. Asks for double confirmation. Use when the pipeline should be removed from Claude Code and Copilot CLI."
 disable-model-invocation: true
-description-tr: "Pipeline'ı Claude Code + Copilot CLI'dan kaldırır. Keychain erişim token'larına asla dokunulmaz; --all-data ayrıca pipeline ayarlarını ve loglarını da siler. Çift onay ister."
+description-tr: "Pipeline'ı Claude Code + Copilot CLI'dan kaldırır. Keychain erişim token'larına asla dokunulmaz; --all-data ayrıca pipeline ayarlarını, loglarını, repo bazlı hafızayı ve bilgi tabanını da siler. Çift onay ister."
 argument-hint: "[--dry-run] [--all-data] [--claude] [--copilot] [--target=<path>]"
 ---
 
@@ -19,7 +19,7 @@ Uninstalls the pipeline itself from the system. **This is different from `:purge
 | Mode | Flag | Removes | Keeps |
 |---|---|---|---|
 | **Standard** (default) | (none) | distributed files: commands, skills, agents, scripts, refs, schemas, lib (except the credential reader) | tokens + `lib/credential-store.sh` + the `multi-agent-toolkit` MCP registration, `CLAUDE.md`, `rules/`, `multi-agent-preferences.json`, all logs |
-| **Full cleanup** | `--all-data` | standard PLUS `~/.claude/logs/multi-agent/` (task logs, state, metrics, audit) and everything in `multi-agent-preferences.json` **except `global.keychainMapping`** | tokens + the credential reader + the mapping that names them + the MCP registration, `CLAUDE.md`, `rules/` (user-owned) |
+| **Full cleanup** | `--all-data` | standard PLUS `~/.claude/logs/multi-agent/` (task logs, state, metrics, audit), `~/.claude/memory/multi-agent/` (learnings ledger + triage corpus), `~/.claude/knowledge/` (per-repo knowledge base + code graph) and everything in `multi-agent-preferences.json` **except `global.keychainMapping`** | tokens + the credential reader + the mapping that names them + the MCP registration, `CLAUDE.md`, `rules/` (user-owned) |
 
 Tokens in the OS credential store are NEVER removed by either mode.
 
@@ -35,22 +35,24 @@ Tokens in the OS credential store are NEVER removed by either mode.
 - Local-only alias wrappers (`local-only: true` frontmatter) under `commands/multi-agent/` (user-authored, exist nowhere else)
 - User-authored skill dirs and agent files (only pipeline-shipped names are removed)
 
-Settings (`multi-agent-preferences.json`) and the log root (`~/.claude/logs/multi-agent/`) are kept by default and removed only when the user picks full cleanup (`--all-data`).
+Settings (`multi-agent-preferences.json`), the log root (`~/.claude/logs/multi-agent/`), the memory root (`~/.claude/memory/multi-agent/`) and the knowledge root (`~/.claude/knowledge/`) are kept by default and removed only when the user picks full cleanup (`--all-data`). The last two are the ones a user usually means by "remove everything": they hold prose about a private codebase and, in `code-graph.json`, every symbol name in it.
+
+Per-repo memory written INSIDE a repo (`$PROJECT_ROOT/.multi-agent/memory/`) is never touched by either mode. It lives in the user's working tree, may be committed, and uninstalling a tool is not a licence to edit their repos.
 
 ## Steps
 
 1. **Determine scope**  -  parse `$ARGUMENTS`:
    - No target flag: every installed target (default)
    - `--claude / --copilot`: selective
-   - `--all-data`: full cleanup (also removes settings + logs)
+   - `--all-data`: full cleanup (also removes settings, logs, per-repo memory and the knowledge base)
    - `--target=<path>`: adapter target (default: cwd)
    - `--dry-run`: report only, delete nothing
 
 2. **Ask the cleanup depth** (skip if the user already passed `--all-data` or `--dry-run`)  -  native `AskUserQuestion` picker in `outputLanguage`:
    - `question`: "How much should uninstall remove? Tokens are preserved either way."
    - `header`: "Scope" · `options`:
-     `{ label: "Standard", description: "Remove pipeline files; keep settings + logs" }`,
-     `{ label: "Full cleanup", description: "Also remove settings + all task logs/state/metrics" }`
+     `{ label: "Standard", description: "Remove pipeline files; keep settings, logs, memory, knowledge" }`,
+     `{ label: "Full cleanup", description: "Also remove settings, logs, per-repo memory and the knowledge base" }`
    - **Full cleanup** adds `--all-data` to the flag set below.
 
 3. **Show a preview** (run the script with `--dry-run`, carrying the chosen flags):

package/pipeline/lib/figma-screenshot.sh

@@ -88,6 +88,8 @@ MAX_IDS_PER_CALL=50
 FILE_KEY=""
 NODE_ID=""
 SECTION_URL=""
+DISCOVER=0
+FEATURE_SLUG=""
 OUTPUT_DIR=""
 SCALE="2"
 FORMAT="png"
@@ -118,6 +120,12 @@ Options:
   --file-key       Figma file key (or branchKey for branch URLs).
   --node-id        Node id; may use either "-" or ":" separator.
   --section        Section URL; child FRAMEs are auto-discovered.
+  --discover-sections  With --file-key and --feature-slug: list every SECTION or
+                   FRAME in the file whose name matches the feature, with a
+                   channel guess. One GET ?depth=2. Answers "does this file also
+                   hold the other channel's design" before a run may write that a
+                   channel has none. Emits JSON, downloads nothing.
+  --feature-slug   Feature name to match against, for --discover-sections.
   --output-dir     Output directory. Default: /tmp/figma-screenshots-<ts>.
   --scale          Render scale (1-4). Default: 2.
   --format         Image format. Default: png.
@@ -387,6 +395,8 @@ while [ "$#" -gt 0 ]; do
     --file-key) FILE_KEY="${2:-}"; shift 2 ;;
     --node-id)  NODE_ID="${2:-}"; shift 2 ;;
     --section)  SECTION_URL="${2:-}"; shift 2 ;;
+    --discover-sections) DISCOVER=1; shift ;;
+    --feature-slug) FEATURE_SLUG="${2:-}"; shift 2 ;;
     --output-dir) OUTPUT_DIR="${2:-}"; shift 2 ;;
     --scale)    SCALE="${2:-2}"; shift 2 ;;
     --format)   FORMAT="${2:-png}"; shift 2 ;;
@@ -394,12 +404,16 @@ while [ "$#" -gt 0 ]; do
   esac
 done
 
-if [ -n "$SECTION_URL" ] && { [ -n "$FILE_KEY" ] || [ -n "$NODE_ID" ]; }; then
-  die 1 "--section is mutually exclusive with --file-key/--node-id"
-fi
-
-if [ -z "$SECTION_URL" ] && { [ -z "$FILE_KEY" ] || [ -z "$NODE_ID" ]; }; then
-  die 1 "either --section <url> or both --file-key and --node-id are required"
+if [ "$DISCOVER" -eq 1 ]; then
+  [ -n "$FILE_KEY" ] || die 1 "--discover-sections requires --file-key"
+  [ -n "$FEATURE_SLUG" ] || die 1 "--discover-sections requires --feature-slug"
+else
+  if [ -n "$SECTION_URL" ] && { [ -n "$FILE_KEY" ] || [ -n "$NODE_ID" ]; }; then
+    die 1 "--section is mutually exclusive with --file-key/--node-id"
+  fi
+  if [ -z "$SECTION_URL" ] && { [ -z "$FILE_KEY" ] || [ -z "$NODE_ID" ]; }; then
+    die 1 "either --section <url> or both --file-key and --node-id are required"
+  fi
 fi
 
 require_cmd curl
@@ -421,6 +435,90 @@ if [ -z "$OUTPUT_DIR" ]; then
 fi
 mkdir -p "$OUTPUT_DIR"
 
+# --- Discovery mode ---------------------------------------------------------
+# One GET /v1/files/{key}?depth=3 lists every page, its sections and their frames,
+# which is what makes frameCount real rather than always zero.
+# That is enough to answer "does this file also hold the other channel's design",
+# which a run has to ask before it may write that a channel has no design at all.
+# Matching is diacritic- and case-insensitive because the same feature is spelled
+# "Elite Kart" on one section and "Elit Kart" on its sibling.
+
+run_discover_mode() {
+  local body
+  # Same as fetch_with_retry: the token goes through a curl config on a process
+  # substitution, never argv, because argv is readable from ps.
+  body=$(curl -sS --max-time "$HTTP_TIMEOUT" --connect-timeout 5 \
+    -K <(printf 'header = "X-Figma-Token: %s"\n' "$FIGMA_TOKEN") \
+    "https://api.figma.com/v1/files/${FILE_KEY}?depth=3") || die 3 "file tree fetch failed"
+
+  printf '%s' "$body" | FEATURE_SLUG="$FEATURE_SLUG" FILE_KEY="$FILE_KEY" python3 -c '
+import json, os, re, sys, unicodedata
+
+def fold(t):
+    t = unicodedata.normalize("NFKD", t)
+    t = "".join(c for c in t if not unicodedata.combining(c))
+    # Turkish dotless i and the rest survive NFKD, so map them explicitly.
+    t = t.translate(str.maketrans("ıİşŞğĞçÇöÖüÜ", "iIsSgGcCoOuU"))
+    return re.sub(r"[^a-z0-9]+", " ", t.lower()).strip()
+
+CHANNELS = [
+    ("mobileweb", ["mobileweb", "mobile web", "mobil web", "responsive"]),
+    ("mobile",    ["mobile app", "mobil uygulama", "app", "ios", "android", "mobil", "mobile"]),
+    ("desktop",   ["desktop", "masaustu", "web"]),
+]
+
+def channel_of(name):
+    f = fold(name)
+    for label, tokens in CHANNELS:
+        for tok in tokens:
+            if re.search(r"\b" + re.escape(fold(tok)) + r"\b", f):
+                return label
+    return None
+
+raw = sys.stdin.read()
+try:
+    doc = json.loads(raw).get("document", {})
+except Exception:
+    print(json.dumps({"error": "unparseable file response"})); sys.exit(3)
+
+slug_words = [w for w in fold(os.environ["FEATURE_SLUG"]).split() if len(w) > 2]
+out, weak, pages = [], [], 0
+for page in doc.get("children", []) or []:
+    pages += 1
+    for node in page.get("children", []) or []:
+        if node.get("type") not in ("SECTION", "FRAME"):
+            continue
+        name = node.get("name", "")
+        f = fold(name)
+        hits = [w for w in slug_words if w in f]
+        if not hits:
+            continue
+        # A single shared word is not a match: "Mil Hediye Et" shares "hediye" with
+        # "Elite Kart Hediye Et" and is a different feature. Require half the slug,
+        # at least two words. Weak hits are reported separately, never dropped in
+        # silence, because a run has to be able to say what it looked at.
+        need = max(2, (len(slug_words) + 1) // 2) if len(slug_words) > 1 else 1
+        row = {
+            "id": node.get("id"),
+            "name": name,
+            "type": node.get("type"),
+            "page": page.get("name"),
+            "frameCount": len(node.get("children", []) or []),
+            "channelGuess": channel_of(name),
+            "matchedWords": hits,
+        }
+        (out if len(hits) >= need else weak).append(row)
+print(json.dumps({
+    "fileKey": os.environ["FILE_KEY"],
+    "featureSlug": os.environ["FEATURE_SLUG"],
+    "pagesScanned": pages,
+    "tokensTried": slug_words,
+    "candidates": sorted(out, key=lambda c: (c["channelGuess"] or "zz", c["id"])),
+    "weakMatches": sorted(weak, key=lambda c: c["id"]),
+}, ensure_ascii=False, indent=2))
+'
+}
+
 # --- Section mode -----------------------------------------------------------
 
 run_section_mode() {
@@ -548,7 +646,9 @@ PY
 
 # --- Dispatch ---------------------------------------------------------------
 
-if [ -n "$SECTION_URL" ]; then
+if [ "$DISCOVER" -eq 1 ]; then
+  run_discover_mode
+elif [ -n "$SECTION_URL" ]; then
   run_section_mode
 else
   run_single_mode