baldart 3.27.1 → 3.28.1

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.1] - 2026-05-28
+
+Patch su tre drift segnalati dal curator dopo v3.28.0 install in `mayo`:
+(1) `--yes` non si propaga da `update --reset` al child `baldart add`,
+(2) errore "Configuring alias is not permitted without enabling allowUnsafeAlias" stampato come install-failed mentre l'install era OK,
+(3) due template `ui-guidelines.template.md` + `brand-guidelines.md` lasciati untracked senza istruzioni chiare all'utente. Tutti e tre cosmetici/UX, nessuno affecta la correctness del framework installato — ma confondono l'utente durante il post-install.
+
+### Fixed — `baldart add` honors `--yes` from parent caller
+
+- **[src/commands/add.js](src/commands/add.js)** + **[src/commands/update.js:237](src/commands/update.js)**: `add(repo, options)` ora legge `options.yes` e auto-conferma i prompt non-distruttivi (`Install framework?`, `Configure git aliases?`, `Configure project context now?`). Il prompt distruttivo `Remove and reinstall?` resta interattivo anche con `--yes` (safety). `update --reset` ora invoca correttamente `addCmd(undefined, { yes: true })` — prima passava `{ yes: true }` come **primo argomento** (cioè `repo`), facendo `options` undefined e ogni prompt scattava.
+
+### Fixed — Git alias config failure non più mascherato da install-failure
+
+- **[src/commands/add.js](src/commands/add.js)**: la configurazione degli alias `fw-version`/`fw-update`/`fw-push` passa da `git.git.addConfig()` (simple-git, che rifiuta i bang-alias senza `allowUnsafeAlias`) a `spawnSync('git', ['config', key, value])` diretto. Il bypass del check simple-git è esplicito qui: l'utente sta opt-in agli alias durante l'install. Failure isolato per alias (non bubble-up al catch globale), reported come WARNING se non-zero count, install continua. Il messaggio "✗ Installation failed: Configuring alias is not permitted…" non appare più.
+
+### Fixed — Template editable post-install: istruzioni chiare
+
+- **[src/commands/add.js](src/commands/add.js)** NEXT STEPS box: i due template `docs/references/ui-guidelines.template.md` e `docs/references/brand-guidelines.md`, copiati incondizionatamente durante `copyCustomizableFiles()`, ora sono elencati esplicitamente con cosa farne (rename / edit / delete) e con il punto chiave: "Commit them to track your project's design language, or add them to .gitignore if you don't need them." Evita la confusione del curator durante v3.28.0 install ("non chiari se debbano essere scelti/scartati dall'utente o committati. Non c'è prompt che lo chieda").
+
+## [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.

package/VERSION

@@ -1 +1 @@
-3.27.1
+3.28.1

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/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.1",
+  "version": "3.28.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/add.js

@@ -7,6 +7,13 @@ const Hooks = require('../utils/hooks');
 async function add(repo, options) {
   const git = new GitUtils();
   const symlinks = new SymlinkUtils();
+  // Non-interactive flag honored on non-destructive prompts only. The
+  // "Remove and reinstall?" prompt (line 40) stays interactive even with
+  // --yes — that path requires explicit user intent, not flag inheritance.
+  // Callers that have already established intent (e.g. `update --reset`)
+  // rm -rf `.framework/` themselves, so `git.frameworkExists()` is false
+  // here and the destructive prompt is never reached.
+  const nonInteractive = options && options.yes === true;
 
   try {
     // Step 1: Verify environment
@@ -70,7 +77,9 @@ async function add(repo, options) {
       'Templates copied for customization'
     ]);
 
-    const proceed = await UI.confirm('Install framework?', true);
+    const proceed = nonInteractive
+      ? true
+      : await UI.confirm('Install framework?', true);
     if (!proceed) {
       UI.info('Installation cancelled');
       process.exit(0);
@@ -157,13 +166,39 @@ async function add(repo, options) {
     // Configure Git aliases
     UI.section('Configuring Git Aliases');
 
-    const configureAliases = await UI.confirm('Configure git aliases (fw-version, fw-update, fw-push)?', true);
+    const configureAliases = nonInteractive
+      ? true
+      : await UI.confirm('Configure git aliases (fw-version, fw-update, fw-push)?', true);
 
     if (configureAliases) {
-      await git.git.addConfig('alias.fw-version', '!cat .framework/VERSION');
-      await git.git.addConfig('alias.fw-update', '!npx github:antbald/BALDART update');
-      await git.git.addConfig('alias.fw-push', '!npx github:antbald/BALDART push');
-      UI.success('Git aliases configured');
+      // simple-git >=3.21 rejects shell-command aliases (prefix `!`) unless
+      // `allowUnsafeAlias` is set in its constructor — and even that is
+      // version-gated. Spawning `git config` directly bypasses the safety
+      // check (which is a simple-git policy, not a git policy: the user is
+      // explicitly opting in to these aliases here). Any failure here is
+      // cosmetic (the framework is fully installed without aliases), so we
+      // warn and continue instead of bubbling up to the global catch — that
+      // surfaced as "✗ Installation failed: Configuring alias is not
+      // permitted without enabling allowUnsafeAlias" while the install was
+      // actually fine.
+      const { spawnSync } = require('child_process');
+      const aliases = [
+        ['alias.fw-version', '!cat .framework/VERSION'],
+        ['alias.fw-update', '!npx baldart update'],
+        ['alias.fw-push', '!npx baldart push'],
+      ];
+      let aliasFailures = 0;
+      for (const [key, value] of aliases) {
+        const r = spawnSync('git', ['config', key, value], { stdio: 'pipe' });
+        if (r.status !== 0) {
+          aliasFailures += 1;
+        }
+      }
+      if (aliasFailures === 0) {
+        UI.success('Git aliases configured');
+      } else {
+        UI.warning(`${aliasFailures}/${aliases.length} git alias(es) could not be configured (non-blocking — install continues).`);
+      }
     }
 
     // BALDART hooks (multi-hook registry since v3.18.0)
@@ -201,10 +236,12 @@ async function add(repo, options) {
     // Skills now resolve project-specific facts from baldart.config.yml
     // instead of hard-coding paths. Configure prompts for these on install.
     UI.newline();
-    const runConfigure = await UI.confirm(
-      'Configure project context now (paths, identity, stack, feature flags)?',
-      true
-    );
+    const runConfigure = nonInteractive
+      ? true
+      : await UI.confirm(
+          'Configure project context now (paths, identity, stack, feature flags)?',
+          true
+        );
     if (runConfigure) {
       try {
         const configureCmd = require('./configure');
@@ -226,9 +263,13 @@ async function add(repo, options) {
       '   • Rename to lint-before-commit.sh',
       '   • Make executable: chmod +x .claude/hooks/lint-before-commit.sh',
       '',
-      '2. Customize UI guidelines:',
-      '   • Edit docs/references/ui-guidelines.template.md',
-      '   • Define colors, typography, spacing',
+      '2. Two editable templates landed at docs/references/ (untracked):',
+      '   • ui-guidelines.template.md  — UI design language template.',
+      '     Edit and rename to ui-guidelines.md if you adopt it.',
+      '   • brand-guidelines.md        — Brand voice & visual identity.',
+      '     Edit to taste, or delete if your project does not need one.',
+      '   These are starting points. Commit them to track your project\'s',
+      '   design language, or add them to .gitignore if you don\'t need them.',
       '',
       '3. Create backlog cards:',
       '   • Copy templates/feature-card.template.yml',

package/src/commands/update.js

@@ -234,7 +234,12 @@ async function runReset(git, options, autoYes) {
   UI.newline();
   UI.info('Re-installing framework via `baldart add`…');
   const addCmd = require('./add');
-  await addCmd({ yes: true });
+  // `add(repo, options)` — first arg is the repo URL (undefined → use default
+  // from package.json). Pre-v3.28.1 we incorrectly passed `{ yes: true }` as
+  // the first arg, so `options` was undefined and every interactive prompt
+  // ("Install framework?", "Configure git aliases?", …) fired despite the
+  // parent `update --reset --yes --i-know` having already established intent.
+  await addCmd(undefined, { yes: true });
 
   // Post-restore sanity check — confirm nothing user-owned got clobbered.
   const stillPresent = {