baldart 3.27.0 → 3.28.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.28.0] - 2026-05-28
+
+Tre additions indipendenti accumulate nel working tree e pronte per il rilascio: convenzione testuale per le dipendenze MCP, supporto `.zip` per il mockup intake del PRD, e nuovo hook `capture-detect` come parte del proactive mode dello skill `/capture` (registrazione opt-in, non auto-attivata). Tre temi distinti ma raggruppati in un'unica release di accumulo perché tutti additive e zero-schema-change.
+
+### Added — Convenzione MCP integration
+
+- **[framework/docs/MCP-INTEGRATION.md](framework/docs/MCP-INTEGRATION.md)**: nuovo documento centralizzato. Spiega quando un agent/skill deve appoggiarsi a un MCP server, fornisce un catalogo di MCP raccomandati per i casi d'uso comuni (doc-rag, playwright, firestore/db, LSP, …), e definisce la convenzione testuale "MCP dependencies" per dichiarare le dipendenze nel body dell'agent/skill. Zero nuove chiavi config in `baldart.config.yml` — la convenzione resta testuale finché una skill concreta non dovrà gate-arne il comportamento (regola di schema-change propagation: niente layer drift).
+- **[framework/.claude/agents/codebase-architect.md](framework/.claude/agents/codebase-architect.md)**: aggiunta sezione `## MCP dependencies` con classificazione Required (`doc-rag` come primo step dell'Investigation Protocol) vs Optional (LSP find-references, DB MCP per inspect runtime). Documentato il degrade path quando l'MCP non è disponibile.
+- **[framework/.claude/skills/bug/SKILL.md](framework/.claude/skills/bug/SKILL.md)**: aggiunta sezione `## MCP dependencies` con Required (`playwright` per Phase 1 reproduction di UI/Client bug — senza è impossibile catturare stato deterministico) e Optional (`doc-rag` per known patterns, DB MCP per Data bugs, `codebase-architect` agent).
+
+### Added — PRD mockup intake da archivio `.zip`
+
+- **[framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)** Step 1.6: nuovo formato `local-archive` accettato accanto a `chat-images` / `local-paths` / `mixed`. Caso d'uso: export "Download as .zip" da Claude Design (o qualsiasi altro tool che produce bundle di mockup) già scaricato sul disco dell'utente.
+- **[framework/.claude/skills/prd/references/discovery-phase.md](framework/.claude/skills/prd/references/discovery-phase.md)** § Mockup Intake: Step 1.6.4b descrive l'intero flow per `.zip` — `unzip` in scratch dir `mockups/_archive/`, enumerazione candidati visivi, scoring di rilevanza contro lo scope del Kickoff, selezione auto-proposta, STOP per conferma, materializzazione del sottoinsieme confermato in `${paths.prd_dir}/<slug>/mockups/`. Evita di copiare PNG irrilevanti nell'asset directory definitiva.
+- **[framework/.claude/skills/prd/assets/state-template.md](framework/.claude/skills/prd/assets/state-template.md)**: aggiornato `mockups.format` enum per includere `local-archive`.
+
+### Added — Hook `capture-detect` (proactive mode, opt-in)
+
+- **[framework/.claude/hooks/capture-detect.sh](framework/.claude/hooks/capture-detect.sh)**: nuovo Stop hook che drop una candidate JSON in `.claude/capture-queue/` quando rileva ragionamento cross-document nella sessione appena chiusa. La distillazione vera in synthesis page wiki resta sempre una human-approved manual step via lo skill `/capture`. Failure-isolated (exit 0 sempre, non blocca lo Stop event).
+- **Registrazione opt-in (NOT auto-attivata)**: la entry corrispondente in [src/utils/hooks.js](src/utils/hooks.js) resta commentata (linee 90-97). Lo skill `/capture` funziona già in modalità manual senza il hook; il proactive mode è una feature opzionale. Per attivarlo nel proprio consumer: scommentare la entry e re-installare via `npx baldart update`. Una futura release potrà rendere il proactive il default.
+
+### Added — Smoke test del hooks registry
+
+- **[scripts/test-hooks.sh](scripts/test-hooks.sh)**: nuovo smoke test per `src/utils/hooks.js` (multi-hook registry introdotto v3.18.0). Verifica register/unregister/isRegistered/merge idempotente con fixture in tmpdir. Dev tooling, non user-visible.
+
+## [3.27.1] - 2026-05-28
+
+Patch follow-up alla v3.27.0 dopo l'incidente reale in `mayo`: l'utente aveva CLI globale v3.24.0 e ha eseguito `/baldart-update` per aggiornarsi a v3.27.0. La skill ha rilanciato `npx baldart update`, che ha aggiornato il framework payload da v3.24 a v3.27, ma `update.js` in esecuzione era il binario v3.24.0 — quello che precede sia il meccanismo di auto-relaunch (introdotto v3.26.0) sia la logica di symlink-indirection (v3.27.0). Risultato: i 6 agent overlay-merged sono stati rigenerati con la **vecchia logica** (file regolari direttamente in `.claude/agents/`), e quindi il fix v3.27.0 NON si è attivato — `npx baldart doctor` ha riportato "tutto healthy" ma in realtà gli agent erano ancora invisibili a Claude Code (bug #20931). Chicken-and-egg: il CLI vecchio non sa rilanciare il nuovo, il nuovo non è ancora in esecuzione.
+
+### Fixed — /baldart-update skill: CLI version drift gate
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)** Step 0: la skill ora rileva esplicitamente il CLI version drift e HALTA pre-update quando il CLI globale è < v3.26.0 (no auto-relaunch) e il payload sta per attraversare il boundary v3.27.0 (migration breaking). Decision logic articolata: se CLI è già >= v3.26.0 lascia che l'auto-relaunch faccia il suo lavoro; altrimenti istruisce `npm i -g baldart@latest` PRIMA di ri-eseguire la skill. Evita il silent-fail dove il CLI vecchio applica una pseudo-migration con codice obsoleto.
+
+### Note al curator
+
+Questo è un edge case strutturale che si manifesta SOLO quando un consumer attraversa il boundary v3.26.0 / v3.27.0 partendo da un CLI globale precedente alla v3.26.0. I consumer già su CLI v3.26.0+ hanno l'auto-relaunch (`npx baldart@latest`) e non sono affected. Per i consumer pre-v3.26.0 il fix in skill aiuta solo le sessioni future (skill caricata da framework payload >= v3.27.1); chi aveva già la skill vecchia in sessione al momento dell'incidente — come `mayo` ieri — può solo riparare manualmente: `npm i -g baldart@latest` + restart sessione CC + `/baldart-update`.
+
 ## [3.27.0] - 2026-05-28
 
 Fix critico al meccanismo di overlay-merge degli agent. Sintomo riproducibile osservato in `mayo` durante `/new FEAT-0009 -full` (team mode, claude-opus-4-7): gli agent overlay-merged (`coder`, `ui-expert`, `code-reviewer`, `doc-reviewer`, `qa-sentinel`, `security-reviewer` quando hanno un overlay) **non comparivano nella lista "Available agent types"** del Claude Code session reminder. Sequenza concreta: `codebase-architect` (symlink) parte e completa; i 4 background agent (`coder×2` + `ui-expert×2`) lanciati subito dopo falliscono con `InputValidationError: subagent_type not recognized`; l'orchestratore halta con un AskUserQuestion fuori-protocollo. Repro: `ls -la .claude/agents/` mostra 21 symlink + 6 file regolari (i 6 overlay-merged); CC discoverizza i 21 symlink e omette i 6 file regolari. Confermato su sessioni indipendenti del 2026-05-27 e 2026-05-28 → bug strutturale, non transiente. Workflow `/new` in team mode, `/check`, `/qa`, `/codexreview` e skill `prd` erano **bloccati end-to-end** su qualsiasi consumer con overlay agent.

package/VERSION

@@ -1 +1 @@
-3.27.0
+3.28.0

package/framework/.claude/agents/codebase-architect.md

@@ -37,6 +37,17 @@ This codebase follows strict protocols defined in AGENTS.md. Key architectural r
 - `/docs/references/project-status.md` - Current system state and active work
 - `agents/coding-standards.md` - Terminology and coding conventions
 
+## MCP dependencies
+
+See [framework/docs/MCP-INTEGRATION.md](../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
+
+**Required** (this agent's primary investigation protocol assumes them; degraded operation only):
+- `mcp__doc-rag__search_docs` — semantic + knowledge-graph search across project docs. This is the **first** call in the Investigation Protocol; without it the agent falls back to broad `rg` sweeps that blow the token budget and miss canonical sources. If the MCP is unavailable the agent must announce the degrade explicitly and switch to targeted `rg` over `docs/`, `backlog/`, and `.claude/agents/` (see § Investigation Protocol step 1).
+
+**Optional** (the agent benefits if present, has a documented fallback):
+- LSP find-references / go-to-definition (whichever LSP MCP / plugin is wired by [features.has_lsp_layer](../../templates/baldart.config.template.yml)) — preferred over `rg` for symbol queries (cap: 3 LSP calls per task, then escalate to direct file reads). Fallback: silent degrade to Grep, per [code-search-protocol.md](../../agents/code-search-protocol.md).
+- `mcp__plugin_firebase_firebase__firestore_*` (or equivalent DB MCP) — only when the architectural analysis needs to inspect runtime DB state (rare for an architect agent). Fallback: read schema docs in `${paths.references_dir}` and rely on declared structure.
+
 ## Linking Protocol Consumption (MUST)
 
 You consume Linking Protocol v1 in read-only mode to find the right facts faster before

package/framework/.claude/hooks/capture-detect.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+#
+# capture-detect.sh — BALDART proactive capture hook (event: Stop)
+#
+# Runs at the end of every Claude Code session. When the just-finished
+# session contains cross-document reasoning (the user has been weaving
+# together facts from multiple docs/references files), this hook drops a
+# *candidate* file into `.claude/capture-queue/` so the next `/capture`
+# invocation can surface it and offer to distill the synthesis into a
+# durable wiki page.
+#
+# This hook NEVER spawns Claude itself — it only writes a small JSON
+# candidate. The actual synthesis is always a human-approved manual step
+# via the `capture` skill.
+#
+# Stdin: Claude Code passes a JSON envelope; we read `transcript_path`,
+#        `session_id`, `cwd` (best-effort — falls back if jq is unavailable).
+#
+# Exit: always 0. Failure isolation — a non-zero exit on a Stop hook can
+#       be ignored by the runtime, but as a matter of hygiene we never
+#       propagate errors out of an instrumentation hook.
+
+set -u
+exec 2>/dev/null  # silence stderr; we are not user-visible
+
+# --- read envelope --------------------------------------------------------
+
+INPUT=""
+if [ ! -t 0 ]; then
+  INPUT="$(cat)"
+fi
+
+# Try jq first, fall back to grep/sed extraction.
+get_field() {
+  local field="$1"
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$INPUT" | jq -r ".$field // empty" 2>/dev/null
+  else
+    printf '%s' "$INPUT" | sed -n "s/.*\"$field\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" | head -1
+  fi
+}
+
+TRANSCRIPT_PATH="$(get_field transcript_path)"
+SESSION_ID="$(get_field session_id)"
+CWD_FROM_ENV="$(get_field cwd)"
+CWD="${CWD_FROM_ENV:-$PWD}"
+
+[ -n "$TRANSCRIPT_PATH" ] || exit 0
+[ -f "$TRANSCRIPT_PATH" ] || exit 0
+
+cd "$CWD" 2>/dev/null || exit 0
+
+# --- gate on features.has_wiki_overlay -----------------------------------
+
+CONFIG="baldart.config.yml"
+[ -f "$CONFIG" ] || exit 0
+# Coarse check: look for `has_wiki_overlay: true` (whitespace-tolerant).
+if ! grep -E '^\s*has_wiki_overlay\s*:\s*true\b' "$CONFIG" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# --- gates: kill switch + anti-spam --------------------------------------
+
+QUEUE_DIR=".claude/capture-queue"
+mkdir -p "$QUEUE_DIR" || exit 0
+
+[ -f "$QUEUE_DIR/.disabled" ] && exit 0
+
+# Anti-spam: refuse when ≥10 unprocessed candidates already queued.
+EXISTING="$(find "$QUEUE_DIR" -maxdepth 1 -type f -name '*.json' 2>/dev/null | wc -l | tr -d ' ')"
+[ "${EXISTING:-0}" -ge 10 ] && exit 0
+
+# --- heuristic: is this session worth flagging? --------------------------
+#
+# We treat "≥3 distinct docs/references-style paths mentioned across the
+# session" as a weak signal of cross-document reasoning. False positives
+# are acceptable here — the user reviews every candidate in /capture and
+# can reject. False negatives are also fine — the user can always invoke
+# /capture manually.
+
+REFS="$(grep -ohE '(\./|/|\b)((docs|wiki|references|backlog|prd)/[A-Za-z0-9._/-]+\.(md|yml|yaml|json))' "$TRANSCRIPT_PATH" 2>/dev/null \
+  | sort -u | head -10)"
+
+REF_COUNT="$(printf '%s\n' "$REFS" | grep -c . || true)"
+[ "${REF_COUNT:-0}" -lt 3 ] && exit 0
+
+# --- write candidate ------------------------------------------------------
+
+TS_FILE="$(date -u +%Y%m%dT%H%M%SZ)"
+TS_HUMAN="$(date -u +'%Y-%m-%d %H:%M UTC')"
+OUT="$QUEUE_DIR/${TS_FILE}-${SESSION_ID:-unknown}.json"
+
+# JSON-escape with awk (no jq required for emit either).
+escape_json() {
+  printf '%s' "$1" | awk 'BEGIN{ORS=""} {gsub(/\\/,"\\\\"); gsub(/"/,"\\\""); gsub(/\r/,""); gsub(/\n/,"\\n"); print}'
+}
+
+REFS_JSON="["
+first=1
+while IFS= read -r r; do
+  [ -z "$r" ] && continue
+  if [ $first -eq 1 ]; then first=0; else REFS_JSON="$REFS_JSON,"; fi
+  REFS_JSON="$REFS_JSON\"$(escape_json "$r")\""
+done <<EOF
+$REFS
+EOF
+REFS_JSON="$REFS_JSON]"
+
+cat > "$OUT" <<JSON
+{
+  "trigger": "cross_doc_refs",
+  "detected_at": "$TS_HUMAN",
+  "session_id": "$(escape_json "${SESSION_ID:-unknown}")",
+  "transcript_path": "$(escape_json "$TRANSCRIPT_PATH")",
+  "refs_mentioned": $REFS_JSON,
+  "excerpt": "Session referenced ${REF_COUNT} distinct doc paths — possible cross-document synthesis worth capturing.",
+  "hint": "Run /capture to review this candidate."
+}
+JSON
+
+exit 0

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -178,9 +178,28 @@ Match the `Remote:` line in this order (first match wins):
 
 Always also capture:
 - `Installed:\s+v(\S+)` → `installedVersion` (saved for post-flight assert).
-- `CLI:\s+v\S+\s+→\s+v(\S+)\s+available` → if present, tell the user once:
-  "Il CLI globale è vecchio (v<old> → v<new>). L'update lo gestirà
-  auto-relanciando via `npx baldart@latest` — niente da fare."
+- `CLI:\s+v(\S+?)(?:\s+→\s+v(\S+)\s+available)?` → `cliVersion` (current CLI binary)
+  + optional `cliLatest` (newest npm version).
+
+**CLI version drift gate (BLOCKING)** — added in v3.27.1 after a real
+incident in `mayo`: a consumer on CLI v3.24.0 ran update against payload
+v3.27.0 and the v3.27.0 symlink-indirection migration silently did NOT
+trigger (the running `update.js` was the v3.24.0 binary, predating both
+auto-relaunch and the migration logic). The CLI v3.26.0+ self-relaunches
+via `npx baldart@latest`, but pre-v3.26.0 binaries do not — chicken-and-egg.
+
+Decision logic (apply after parsing):
+
+| If… | Then… |
+|---|---|
+| `cliVersion >= 3.26.0` AND `cliLatest` present | Tell once: "Il CLI globale è v<cliVersion>, ne esiste v<cliLatest>. L'update si autorelancerà via `npx baldart@latest` — niente da fare." Continue. |
+| `cliVersion < 3.26.0` AND `installedVersion >= 3.27.0` (already on the new payload but old binary) | **HALT**. Tell the user: "Il CLI globale (v<cliVersion>) è troppo vecchio per applicare la migration symlink-indirection di v3.27.0 (introdotta v3.26.0+ self-relaunch e v3.27.0 symlink-indirection). Lancia `npm i -g baldart@latest` PRIMA di ri-eseguire /baldart-update, altrimenti `update.js` non vedrà la nuova logica e i 6 agent overlay-merged resteranno file regolari invisibili a Claude Code (bug #20931)." Do not launch `npx baldart update`. |
+| `cliVersion < 3.26.0` AND `installedVersion < 3.27.0` AND update is going to bring the payload to `>= 3.27.0` (parse the remoteVersion from Step 0) | **HALT** with the same message — the payload will cross the v3.27.0 boundary during this update, and the running `update.js` will lack the migration logic. |
+| Otherwise | Continue normally. |
+
+Semver compare: split on `.`, compare numerically. Treat any non-numeric
+segment (e.g. `3.27.0-rc1`) as "less than" the same major.minor.patch
+without suffix only when strictly required; if unsure, ASK the user.
 
 **Decision after parsing**:
 

package/framework/.claude/skills/bug/SKILL.md

@@ -21,6 +21,18 @@ Argument: optional bug description (e.g., `/bug feature X is not saving`).
 **Overlay:** loads `.baldart/overlays/bug.md` if present — project-specific debug entry points (e.g. SWR debug switches, env summary helpers, error-code modules). The base skill stays generic; project-specific code paths live in the overlay.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
+## MCP dependencies
+
+See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
+
+**Required** (skill cannot complete its task without these MCPs for the relevant bug class):
+- `mcp__playwright__browser_*` (`browser_navigate`, `browser_take_screenshot`, `browser_console_messages`, `browser_network_requests`, `browser_evaluate`) — Phase 1 reproduction for **UI/Client** bugs. Without it the skill cannot capture deterministic state and Phase 1 degrades to "ask the user to reproduce manually and paste console logs". Phase 2's client-side `window.fetch` interception is impossible without `browser_evaluate`.
+
+**Optional** (the skill benefits if present, has a documented fallback):
+- `mcp__doc-rag__search_docs` — Phase 0 lookup for known patterns and error codes. Fallback: targeted `rg` over the project's error-code module (path listed in `.baldart/overlays/bug.md`) and `docs/wiki/`.
+- `mcp__plugin_firebase_firebase__firestore_*` (or the project's DB MCP, when `stack.database.primary` is set) — Phase 1 inspection of runtime data state for **Data** bugs. Fallback: ask the user for a document export, or read the relevant code path and infer.
+- `codebase-architect` agent (always available, listed for completeness) — Phase 0 code-path mapping. Not an MCP per se but is treated as a required dependency by this skill.
+
 ## ANTI-PATTERNS (NEVER DO)
 
 - NEVER change code before reproducing the bug

package/framework/.claude/skills/prd/SKILL.md

@@ -92,8 +92,17 @@ message. You ask questions, wait for answers, and iterate.
     structure and `assets/card-template.yml` for child structure.
 16. **Mockup Intake (MANDATORY).** Subito dopo Kickoff (Step 1) e prima di entrare in
     Discovery (Step 2), esegui Step 1.6 — chiedi all'utente se ha mockup a disposizione.
-    Se **sì**: chiedi formato (immagini in chat / path locali), **STOP**, attendi. Sull'arrivo:
-    copia i path locali in `${paths.prd_dir}/<slug>/mockups/`, analizza in dettaglio (vedi
+    Se **sì**: chiedi formato (immagini in chat / path locali — singoli file **o
+    archivi `.zip`** — / misti), **STOP**, attendi. Sull'arrivo:
+    - **chat-images** / file singoli in **local-paths**: copia in `${paths.prd_dir}/<slug>/mockups/`,
+      passa subito all'analisi.
+    - **`.zip` in local-paths** (es. export "Download as .zip" da Claude Design già
+      sul disco): esegui Step 1.6.4b — `unzip` in scratch dir sotto `mockups/_archive/`,
+      enumera i candidati visivi, calcola uno score di rilevanza contro lo scope
+      del Kickoff, presenta la selezione auto-proposta, **STOP**, attendi conferma,
+      poi materializza solo il sottoinsieme confermato in `${paths.prd_dir}/<slug>/mockups/`.
+
+    Quindi analizza in dettaglio (vedi
     [discovery-phase.md](references/discovery-phase.md) § "Mockup analysis schema"), popola
     `## UI Design` nello state, poi entra in Discovery. Se **no**: marca
     `mockups.status: none` e procedi col flow standard. Il decision tree di Step 3 (UI Design)

package/framework/.claude/skills/prd/assets/state-template.md

@@ -74,11 +74,18 @@ Scenarios: pending
 
 ## UI Design
 
-mockups.status: pending           # none | requested | provided | partial
-mockups.format: pending           # chat-images | local-paths | mixed
-mockups.original_paths: []        # user-provided paths or chat://image-N
+mockups.status: pending           # none | requested | provided | partial | pending_external
+mockups.format: pending           # chat-images | local-paths | local-archive | mixed
+mockups.original_paths: []        # user-provided paths, chat://image-N, or archive://<rel-path>
 mockups.canonical_paths: []       # mockups/<file> after copy
 
+mockups.archive:                  # populated only when format includes local-archive
+  local_zip_path: pending         # abs path of the .zip the user gave us
+  kind: pending                   # zip
+  extracted_dir: pending          # abs path of _archive/extracted/
+  truncated: false                # true when candidate list capped at 200
+  candidates: []                  # see discovery-phase.md § 1.6.4b step b-c
+
 mockup_analysis.screens: []       # see discovery-phase.md § Mockup analysis schema
 mockup_analysis.user_flow: []
 mockup_analysis.design_system_alignment:

package/framework/.claude/skills/prd/references/discovery-phase.md

@@ -172,9 +172,12 @@ Append this follow-up to the SAME message:
 Perfetto. In che forma me li passi?
 
 - **Immagini in chat** — incollale direttamente nel prossimo messaggio.
-- **Path locali** — incolla i percorsi (assoluti o relativi al repo) e li copio
-  in `${paths.prd_dir}/<slug>/mockups/`.
-- **Misti** — entrambe le cose.
+- **Path locali** — incolla i percorsi (assoluti o relativi al repo). Funzionano:
+  - file singoli (PNG, HTML, SVG, …) → li copio in `${paths.prd_dir}/<slug>/mockups/`.
+  - **archivi `.zip`** (es. export "Download as .zip" da Claude Design già
+    scaricato sul tuo disco) → lo unzippo io, analizzo TUTTI i mockup dentro
+    e seleziono automaticamente quelli rilevanti per questa feature.
+- **Misti** — combinazioni delle modalità sopra.
 ```
 
 - Update state file `## UI Design`: `mockups.status: requested`, `mockups.format: pending`.
@@ -184,19 +187,170 @@ Perfetto. In che forma me li passi?
 
 When the user replies with the mockups:
 
-1. **Detect format** and update `mockups.format` ∈ {`chat-images`, `local-paths`, `mixed`}.
+1. **Detect format** and update `mockups.format` ∈ {`chat-images`, `local-paths`, `local-archive`, `mixed`}.
+   - `local-archive` applies when at least one of the provided local paths is a
+     `.zip` (case-insensitive) — also if mixed with other regular files.
 2. **For each local path provided:**
    - Resolve to absolute path. If file does not exist: ask the user to confirm/correct
      (do not silently skip).
-   - Ensure `${paths.prd_dir}/<slug>/mockups/` exists (create if missing).
-   - Copy the file into that directory, preserving filename. On collision (file with
-     same name already there): append numeric suffix (`<name>-2.png`).
+   - **If the path is a `.zip`** (extension match OR `file <path>` reports a Zip
+     archive): route it to Step 1.6.4b and DO NOT copy the zip itself into
+     `${paths.prd_dir}/<slug>/mockups/`. Only the user-confirmed subset extracted
+     from it ends up there.
+   - **Otherwise** (regular mockup file): ensure `${paths.prd_dir}/<slug>/mockups/`
+     exists (create if missing), then copy the file into that directory,
+     preserving filename. On collision (file with same name already there):
+     append numeric suffix (`<name>-2.png`).
    - Record both paths in state: `mockups.original_paths[]` and `mockups.canonical_paths[]`.
 3. **For chat images:** record in state `mockups.original_paths[]` as `chat://image-N`
    (the images remain in the conversation context window).
-4. Update `mockups.status: provided` (or `partial` only if the user explicitly says
+4. **For zip archives:** execute Step 1.6.4b BEFORE marking `status: provided`. The
+   archive flow has its own scan + selection + confirmation gate; only the
+   user-confirmed subset is copied into `${paths.prd_dir}/<slug>/mockups/`.
+5. Update `mockups.status: provided` (or `partial` only if the user explicitly says
    "ho solo questi 2 ma servono anche altri").
 
+### 1.6.4b — Archive ingestion & relevance selection (when `mockups.format` includes `local-archive`)
+
+Triggered when the user hands a local `.zip` path (typically a Claude Design
+"Download as .zip" export already on disk). The flow scans every mockup inside,
+scores each against the feature scope from Kickoff, and asks the user to confirm
+the auto-selected subset before analysis.
+
+#### Step a — Detect & unpack
+
+For each zip path provided:
+
+```bash
+file "<user-zip-path>"
+```
+
+- If `file` does NOT report a Zip archive, treat the path as a regular file and
+  go back to step 1.6.4 point 2's "Otherwise" branch — no special handling.
+- If it IS a zip, record in state:
+  - `mockups.archive.local_zip_path: <user-zip-path>` (absolute)
+  - `mockups.archive.kind: zip`
+- Unpack into a scratch directory under the PRD's mockup folder:
+
+```bash
+mkdir -p "$WORKTREE_PATH/${paths.prd_dir}/<slug>/mockups/_archive"
+unzip -q "<user-zip-path>" \
+  -d "$WORKTREE_PATH/${paths.prd_dir}/<slug>/mockups/_archive/extracted"
+```
+
+- Record `mockups.archive.extracted_dir`.
+- If `unzip` fails (corrupted/encrypted): STOP, surface the exit code, ask the
+  user to verify the zip or provide an alternative.
+
+#### Step b — Enumerate candidates
+
+Scan the extracted tree for mockup-shaped files. The candidate filter is:
+
+- Extensions: `.html`, `.htm`, `.png`, `.jpg`, `.jpeg`, `.svg`, `.webp`, `.gif`, `.pdf`.
+- Exclude: `node_modules/`, `.git/`, anything under a directory named `assets/`
+  whose parent is itself excluded, `*.min.*`, `thumbs.db`, `.DS_Store`.
+- Size sanity: skip files > 50 MB (likely video/binary blobs, never a mockup).
+
+```bash
+find "$WORKTREE_PATH/${paths.prd_dir}/<slug>/mockups/_archive/extracted" \
+  -type f \
+  \( -iname '*.html' -o -iname '*.htm' -o -iname '*.png' -o -iname '*.jpg' \
+     -o -iname '*.jpeg' -o -iname '*.svg' -o -iname '*.webp' -o -iname '*.gif' \
+     -o -iname '*.pdf' \) \
+  -size -50M \
+  -not -path '*/node_modules/*' -not -path '*/.git/*' \
+  -not -name '*.min.*' -not -name 'thumbs.db' -not -name '.DS_Store'
+```
+
+For each candidate, build a lightweight index entry:
+- `path` (relative to `extracted/`)
+- `filename`
+- `ext`
+- `size_kb`
+- For HTML: `<title>` content + first `<h1>` (use `grep -oE` or a single Read of
+  the first ~200 lines; do NOT load the full file — they can be massive).
+- For images: nothing extra at this stage (filename is the only cheap signal).
+
+Cap the indexed list at 200 entries. If the archive contains more, sort by
+`size_kb DESC` (larger files are typically the rendered screens) and keep the
+top 200, recording `mockups.archive.truncated: true`.
+
+Record the full index in state under `mockups.archive.candidates[]`.
+
+#### Step c — Score against feature scope
+
+Build the scope vector from the Kickoff state (Step 1):
+- `feature_title` (from `## Feature Description`).
+- `slug`.
+- ISA touchpoints (if Discovery dimension 9 already ran).
+- Verbatim screen names the user mentioned in the initial description.
+- Keywords from `feature_objective_one_sentence` (strip stopwords).
+
+For each candidate, compute a relevance score 0-100:
+- `+40` if any scope keyword appears in the filename (case-insensitive,
+  whole-word; for kebab/snake/camelCase, split before matching).
+- `+30` if any scope keyword appears in the HTML `<title>` or `<h1>`.
+- `+15` if the file path contains a directory name matching a scope keyword.
+- `+10` if the filename matches typical screen patterns (`screen`, `page`,
+  `view`, `flow`, the user's domain entity names).
+- `-20` if the filename matches typical non-screen patterns (`icon`, `logo`,
+  `favicon`, `thumbnail`, `og-image`, `sitemap`, `manifest`).
+
+Selection threshold: keep candidates with `score ≥ 30` as the auto-selected set.
+If fewer than 3 candidates clear the threshold, lower to `≥ 20` and surface the
+fact. If zero candidates clear `≥ 20`, surface "selezione non automatizzabile —
+ti chiedo di indicarmi a mano quali sono rilevanti" and present the full
+candidate list.
+
+Record per-candidate: `score`, `matched_keywords[]`, `selected: bool`.
+
+#### Step d — Confirmation gate (STOP)
+
+Present a compact table to the user — selected candidates first, then up to 10
+discarded with the highest scores, then a footer count for "altri N scartati":
+
+```
+Bundle scaricato e analizzato: <N> file candidati, <K> selezionati come rilevanti.
+
+**Selezionati** (score ≥ 30 vs. feature scope):
+| # | File                          | Score | Match                  |
+|---|-------------------------------|-------|------------------------|
+| 1 | screens/lista-fornitori.html  | 75    | "fornitori", "lista"   |
+| 2 | screens/dettaglio-ordine.html | 55    | "ordine"               |
+…
+
+**Scartati ad alto score** (per trasparenza):
+| # | File                          | Score | Motivo                 |
+|---|-------------------------------|-------|------------------------|
+| 1 | screens/landing-marketing.html| 22    | nessun keyword match   |
+…
+
+Altri <M> file scartati (score < 20 o pattern non-schermata).
+
+Procedo all'analisi visiva dei <K> selezionati? Oppure indicami modifiche
+(es. "aggiungi il #3 degli scartati", "togli il #2 dei selezionati").
+```
+
+**STOP.** Wait for explicit confirmation or an adjustment list. On adjustment,
+recompute `mockups.archive.candidates[].selected`, then re-present and STOP again
+until the user confirms.
+
+#### Step e — Materialize the confirmed subset
+
+Copy ONLY the confirmed selection into `${paths.prd_dir}/<slug>/mockups/`,
+preserving relative directory structure under the extracted root so that
+relative asset references (CSS, images) keep working. On filename collision,
+use the `<name>-2.<ext>` rule from 1.6.4 point 2.
+
+Record `mockups.original_paths[]` as `archive://<relative-path-in-zip>` and
+`mockups.canonical_paths[]` as the new path under `mockups/`. The scratch
+`_archive/extracted/` directory is kept for the duration of the PRD session
+(may be needed to resolve `<link>` / `<img src>` references during analysis)
+and cleaned up at Step 7 (Commit & Merge) — add a `.gitignore` entry for
+`mockups/_archive/` if not already present.
+
+Then continue to Step 1.6.5 with the selected subset.
+
 ### 1.6.5 — Mockup analysis (MANDATORY before Discovery)
 
 Analyze ALL provided mockups (visual analysis for chat images, Read for copied files
@@ -561,11 +715,26 @@ structure. Be specific — vague analysis defeats the purpose of skipping Step 3
 ```yaml
 mockups:
   status: provided | partial | none | requested
-  format: chat-images | local-paths | mixed
+  format: chat-images | local-paths | local-archive | mixed
   original_paths:
-    - <user-provided path or chat://image-N>
+    - <user-provided path, chat://image-N, or archive://<rel-path-in-zip>>
   canonical_paths:
-    - mockups/<file>.png         # only for local-paths
+    - mockups/<file>.png         # only for local-paths and local-archive
+  archive:                       # only when format includes local-archive
+    local_zip_path: <abs path to the user-provided .zip>
+    kind: zip
+    extracted_dir: <abs path to _archive/extracted/>
+    truncated: false             # true when candidate list capped at 200
+    candidates:                  # full enumerated list (post-filter)
+      - path: <rel path under extracted/>
+        filename: <basename>
+        ext: html | png | jpg | svg | …
+        size_kb: <int>
+        html_title: <optional, HTML only>
+        html_h1: <optional, HTML only>
+        score: <0-100>
+        matched_keywords: [<keyword>, …]
+        selected: <bool>         # true = part of the confirmed subset
 mockup_analysis:
   screens:
     - name: <inferred name, e.g. "Lista ordini">

package/framework/docs/MCP-INTEGRATION.md

@@ -0,0 +1,119 @@
+# MCP Integration — Guida BALDART per i consumer
+
+Questo documento spiega **quando** un agent/skill BALDART deve appoggiarsi a un Model Context Protocol (MCP) server, **quali** MCP sono raccomandati per i casi d'uso più comuni, e **come** dichiarare la dipendenza MCP nel body dell'agent in modo che il consumer sappia subito cosa configurare.
+
+> **Scope di questa release**: convenzione testuale, **zero nuove chiavi config** in `baldart.config.yml`. Le chiavi `mcp.*` (es. `mcp.required: []` / `mcp.optional: []`) entreranno solo se e quando una skill concreta dovrà gatearne il comportamento, in una release dedicata con propagazione end-to-end completa (regola di [schema-change propagation](../docs/PROJECT-CONFIGURATION.md)).
+
+---
+
+## 1. Quando usare un MCP
+
+Tre opzioni per integrare un sistema esterno in un agent BALDART. Scegli il più semplice che risolve il problema:
+
+| Opzione | Quando ha senso | Costi/limiti |
+|---|---|---|
+| **MCP server** | Il sistema è **bidirezionale**, ha molte operazioni discrete (search, get, mutate), serve a **molti agent diversi**, o richiede **stato di sessione** (browser, DB). | Setup nel consumer (configurazione MCP), dipendenza esplicita, esposizione dei dati al modello. |
+| **Script CLI / Bash** | È un'azione **one-shot** o **idempotente** (build, test, git, lint, deploy), output testuale ben definito, niente stato di sessione. | Niente — è la baseline. Preferibile quando funziona. |
+| **API call diretta (fetch/curl)** | Serve **un'unica chiamata** verso un endpoint REST/GraphQL pubblico o autenticato via env var, **non serve a più agent**. | Risposta opaca al framework (non recuperabile per altri agent), parsing manuale, niente cache strutturata. |
+
+**Regola pratica**: se la stessa integrazione tornerà utile a **2+ agent o skill**, è un MCP. Se è un'esecuzione una-tantum da una singola skill, è uno script CLI o un fetch.
+
+---
+
+## 2. Catalogo MCP raccomandati per i casi d'uso comuni
+
+Non è un'imposizione: BALDART non installa MCP, non li valida, non li richiede. È una lista curata di MCP che hanno senso nei deployment dove BALDART è già in uso.
+
+### Browser automation
+- **Playwright MCP** (`@modelcontextprotocol/server-playwright`) — usato da [bug](../.claude/skills/bug/SKILL.md) e [webapp-testing](../.claude/skills/webapp-testing/SKILL.md) per cattura visiva, network, console.
+
+### Documentation retrieval (RAG)
+- **doc-rag MCP** (interno o `@modelcontextprotocol/server-everything-search` come stand-in) — usato da [codebase-architect](../.claude/agents/codebase-architect.md) e [code-search-protocol.md](../agents/code-search-protocol.md) per ricerca semantica nei doc + knowledge graph.
+
+### Database
+- **Firebase MCP** (`@modelcontextprotocol/server-firebase` — già integrato come plugin BALDART quando `stack.database.primary` è Firestore) — ispezione documenti, query collection, transazioni.
+- **Postgres MCP** (`@modelcontextprotocol/server-postgres`) — per stack SQL.
+
+### Issue tracker / project management
+- **GitHub MCP** (`@modelcontextprotocol/server-github`) o **`gh` CLI** — issue triage, PR review, gist creation. Per BALDART consigliamo `gh` (è una CLI già universale), MCP solo se servono molte mutazioni in pipeline.
+- **Linear MCP**, **Jira MCP** — disponibili nella registry ufficiale Anthropic per chi usa quei ticketing system.
+
+### Design tool
+- **Figma MCP** — usato da agent di design / UI per estrarre token, screenshot, asset.
+
+### Observability
+- **Sentry MCP** — già disponibile in BALDART come [sentry plugin](../../CLAUDE.md). Per analisi error → root cause.
+
+### Communication
+- **Slack MCP**, **Gmail MCP** — disponibili nel marketplace MCP. Usali solo se l'agent deve davvero comunicare verso umani (es. post-mortem auto-pubblicato).
+
+**Anti-pattern**: NON installare MCP "perché esistono". Ogni MCP aggiunge tool al system prompt del modello, consuma context, e crea dipendenze infrastrutturali nel consumer. Il pattern BALDART è "tanti agent specializzati, pochi MCP universalmente utili".
+
+---
+
+## 3. La convenzione `## MCP dependencies` (per author di agent/skill BALDART)
+
+Ogni agent o skill BALDART che usa MCP deve dichiararlo esplicitamente nel body, in una sezione dedicata. Questo permette:
+- al **consumer** di sapere cosa configurare (e cosa succede se non lo configura);
+- al `baldart doctor` futuro di leggere queste sezioni e verificare gli MCP `required`;
+- ad altri agent di sapere se invocare questo agent è "free" o richiede setup.
+
+### Struttura
+
+Subito dopo la sezione `## Project Context` (o, in mancanza, subito dopo il frontmatter e l'intro):
+
+```markdown
+## MCP dependencies
+
+**Required** (skill/agent rifiuta o degrada visibilmente senza questi MCP):
+- `mcp__<server>__<tool>` — cosa serve, perché.
+
+**Optional** (l'agent ne approfitta se disponibile, ma ha un fallback):
+- `mcp__<server>__<tool>` — cosa offre in più, qual è il fallback.
+
+**None** (per skill senza MCP — utile dichiararlo esplicitamente):
+- This skill uses no MCP servers. <breve nota se rilevante>
+```
+
+### Regole
+
+1. **Sii specifico**: cita il prefisso del tool (`mcp__playwright__browser_navigate`), non il "concetto" (`Playwright MCP`). Aiuta il consumer a fare grep.
+2. **Required vs Optional**: required = la skill non può completare il proprio task senza il MCP (o degrada gravemente). Optional = la skill ha un fallback funzionante.
+3. **Fallback espliciti**: per ogni `Optional`, descrivi il fallback in una frase ("se MCP unavailable, usa `rg` su `docs/` per trovare pattern noti").
+4. **Niente nuovo schema in `baldart.config.yml`**: non aggiungere `mcp.required` o `mcp.optional` nel config — è solo convenzione testuale finché non c'è una skill che ha bisogno di gatearne il comportamento a runtime.
+5. **Aggiorna la dichiarazione quando la dipendenza cambia**: se rimuovi un MCP dall'agent, rimuovi la riga; se aggiungi un fallback Grep e l'MCP diventa optional, sposta la riga.
+
+### Esempi nel framework corrente
+
+Vedi le seguenti dichiarazioni per pattern di riferimento:
+- [framework/.claude/agents/codebase-architect.md](../.claude/agents/codebase-architect.md) — `## MCP dependencies` con doc-rag required + LSP-related optional.
+- [framework/.claude/skills/bug/SKILL.md](../.claude/skills/bug/SKILL.md) — Playwright required per UI bug, doc-rag + Firestore optional.
+- [framework/.claude/skills/playwright-skill/SKILL.md](../.claude/skills/playwright-skill/SKILL.md) — esempio di sezione "None" (la skill usa Playwright Test CLI, non MCP).
+
+---
+
+## 4. FAQ per il consumer
+
+**D: BALDART installa gli MCP per me?**
+R: No. BALDART distribuisce agent e skill che eventualmente li **usano**. L'installazione e configurazione MCP è responsabilità del consumer (di solito via `.mcp.json` o `.claude/settings.json`). Vedi la [documentazione Claude Code](https://docs.claude.com) per il setup MCP.
+
+**D: Cosa succede se invoco un agent che richiede un MCP non configurato?**
+R: Dipende da come l'agent è stato scritto. Gli agent BALDART che seguono il pattern raccomandato fanno **graceful degrade** (riportano il missing MCP e provano un fallback documentato). Quelli che dichiarano un MCP come **Required** dovrebbero rifiutare visibilmente di proseguire — ma oggi BALDART non enforza questa policy in modo automatico. Il `baldart doctor` futuro potrà controllarla.
+
+**D: Posso aggiungere un MCP custom non nella lista del § 2?**
+R: Sì, e se diventa utile a più agent valuta una PR upstream a BALDART per aggiungerlo al catalogo. Vedi [MAINTAINING.md](../../MAINTAINING.md) per il workflow di contribuzione.
+
+**D: La mia organizzazione ha un sistema interno (ticketing, docs, monitoring) — devo per forza esporlo via MCP?**
+R: Non per forza. Se l'integrazione serve a **uno** script una tantum, una semplice fetch è meglio. Se serve a 2+ agent BALDART o se vuoi che gli agent possano "scoprire" dati senza che tu glieli passi manualmente, allora vale la pena un MCP custom.
+
+---
+
+## 5. Cosa cambia per BALDART nelle prossime release
+
+Roadmap (vedi piano [gap-analysis vs. large codebases](../../.claude/plans/voglio-che-studi-questo-fluttering-nova.md)):
+
+- **Adesso** (questa release): convenzione testuale `## MCP dependencies`, doc + 3 agent/skill aggiornati come reference.
+- **Prossima release MINOR** (se serve): introduzione di una skill che richiede gating runtime su MCP → in quella release sarà propagata la chiave `mcp.required/optional` end-to-end (template + configure + doctor + CHANGELOG), seguendo la regola di schema-change propagation.
+- **Routine `mcp-check`** (opzionale, T-level): controllo settimanale che ogni MCP `Required` dichiarato nel framework abbia un endpoint sano nel consumer.
+
+Finché la chiave config non esiste, la convenzione testuale **è** il contratto.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.27.0",
+  "version": "3.28.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"