docs(mcp): clarify support matrix and canonical specs

ai-agentic-embedded-base/specs/03_plan.md

@@ -1,16 +1,134 @@
-# Easter Egg musique expérimentale
+# Plan d'execution autonome local (RTC + Zacus)
 
-_« Le plan du projet se transforme, comme un evidence pack modulé par Daphne Oram. »_
-# Plan
+Last updated: 2026-02-21
 
-## Étapes
-1) ...
-2) ...
+## Objectif
 
-## Validation à chaque étape
-- Build
-- Tests
-- Gates hardware (ERC/DRC)
+Atteindre une boucle autonome locale stable sur les deux repos branches au hardware:
 
-## Evidence pack
-- artifacts/...
+- `RTC_BL_PHONE`
+- `le-mystere-professeur-zacus`
+
+avec:
+
+- stack ZeroClaw local operationnel (`3000`, `8788`, `9090`),
+- dev/test reproductible sur chaque repo,
+- preflight hardware systematique avant toute action firmware,
+- traces et preuves dans `artifacts/zeroclaw/`.
+
+## Criteres de succes
+
+- `tools/ai/zeroclaw_stack_up.sh` lance gateway + follow + Prometheus (binary ou docker fallback).
+- `http://127.0.0.1:8788/` affiche les conversations et logs en live.
+- `http://127.0.0.1:9090/targets` est reachable (Prometheus up).
+- `tools/ai/zeroclaw_dual_chat.sh rtc --provider-check` et `... zacus --provider-check` passent.
+- Au moins une boucle dev/test complete par repo est executee et tracee.
+
+## Contraintes
+
+- Local only (loopback `127.0.0.1`), pas d'exposition publique.
+- Secrets hors git (`~/.zeroclaw/env`, mode `600`).
+- Cout modele borne par quotas webhook locaux.
+- Flash/upload/serial monitor forces par defaut apres detection hardware valide.
+- Jamais de commande `pio` sur un env non declare dans `platformio.ini`.
+
+## Plan par phases
+
+## Phase 0 - Preflight (auth + outils)
+
+Actions:
+
+1. Verifier `gh auth status`.
+2. Verifier `zeroclaw auth status`.
+3. Verifier `~/.zeroclaw/env` contient `OPENROUTER_API_KEY=...` et permissions `600`.
+4. Verifier backend Prometheus local:
+   - binaire `prometheus`, sinon docker daemon.
+
+Sortie attendue:
+
+- environnement provider OK,
+- fallback Prometheus disponible.
+
+## Phase 1 - Stack local ZeroClaw
+
+Actions:
+
+1. `tools/ai/zeroclaw_stack_down.sh`
+2. `ZEROCLAW_PROM_MODE=auto tools/ai/zeroclaw_stack_up.sh`
+3. Verifs:
+   - `curl -fsS http://127.0.0.1:3000/health`
+   - `curl -fsS http://127.0.0.1:8788/`
+   - `curl -fsS http://127.0.0.1:9090/-/ready`
+
+Sortie attendue:
+
+- gateway healthy,
+- dashboard live actif,
+- Prometheus ready.
+
+## Phase 2 - Boucle autonome RTC
+
+Actions:
+
+1. Provider check: `tools/ai/zeroclaw_dual_chat.sh rtc --provider-check`
+2. Hardware discover: `tools/ai/zeroclaw_dual_chat.sh rtc --hardware`
+3. Build/test firmware repo RTC:
+   - `cd /Users/cils/Documents/Lelectron_rare/RTC_BL_PHONE`
+   - `pio run -e esp32dev`
+   - `pio run -e esp32dev -t upload`
+   - `pio device monitor -p <port> -b 115200` (capture 60s)
+   - ou commande unique: `tools/ai/zeroclaw_hw_firmware_loop.sh rtc`
+4. Trace webhook:
+   - `tools/ai/zeroclaw_webhook_send.sh --repo-hint rtc "rtc loop status ..."`
+
+Sortie attendue:
+
+- build RTC passe ou echec documente avec logs,
+- ligne JSONL enrichie pour la boucle RTC.
+
+## Phase 3 - Boucle autonome Zacus
+
+Actions:
+
+1. Provider check: `tools/ai/zeroclaw_dual_chat.sh zacus --provider-check`
+2. Hardware discover: `tools/ai/zeroclaw_dual_chat.sh zacus --hardware`
+3. Build/test firmware repo Zacus:
+   - `cd /Users/cils/Documents/Lelectron_rare/le-mystere-professeur-zacus/hardware/firmware`
+   - `pio run -e esp32dev`
+   - `pio run -e esp32dev -t upload`
+   - `pio device monitor -p <port> -b 115200` (capture 60s)
+   - ou commande unique: `tools/ai/zeroclaw_hw_firmware_loop.sh zacus`
+   - statut tests: `blocked` tant que dossier `test/` absent
+4. Trace webhook:
+   - `tools/ai/zeroclaw_webhook_send.sh --repo-hint zacus "zacus loop status ..."`
+
+Sortie attendue:
+
+- build Zacus passe ou echec documente avec logs,
+- ligne JSONL enrichie pour la boucle Zacus.
+
+## Phase 4 - Stabilisation autonomie
+
+Actions:
+
+1. Dry-run budget: `tools/ai/zeroclaw_webhook_send.sh --dry-run "budget probe"`
+2. Verifier quota state: `artifacts/zeroclaw/webhook_budget.json`
+3. Verifier logs:
+   - `artifacts/zeroclaw/gateway.log`
+   - `artifacts/zeroclaw/conversations.jsonl`
+4. Mettre a jour TODO (`specs/04_tasks.md` + `specs/zeroclaw_dual_hw_todo.md`).
+
+Sortie attendue:
+
+- boucles previsibles,
+- cout controle,
+- preuves a jour.
+
+## Cadence autonome quotidienne
+
+1. Preflight auth + hardware.
+2. Stack up + smoke endpoints.
+3. RTC loop (build + upload + monitor + webhook trace).
+4. Zacus loop (build + upload + monitor + webhook trace).
+5. Review logs + correction ciblée.
+6. Commit/PR petit lot.

ai-agentic-embedded-base/specs/README.md

@@ -1,25 +1,29 @@
 # Specs (Spec-driven)
 
-Flux conseillé (itératif) :
-1) `00_intake.md` : idée brute + contexte
+Flux conseille (iteratif) :
+1) `00_intake.md` : idee brute + contexte
 2) `01_spec.md` : spec claire + AC
 3) `02_arch.md` : architecture + ADR
-4) `03_plan.md` : plan découpé, risques, validations
-5) `04_tasks.md` : backlog exécutable (issues / PRs)
-6) Implémentation (firmware/hardware) + tests + doc
+4) `03_plan.md` : plan decoupe, risques, validations
+5) `04_tasks.md` : backlog executable (issues / PRs)
+6) Implementation (firmware/hardware) + tests + doc
 
-Le fichier `constraints.yaml` est la **source de vérité** des contraintes non-fonctionnelles et règles repo.
+Le fichier `constraints.yaml` est la **source de verite** des contraintes non-fonctionnelles et regles repo.
 
-Specs complémentaires:
+Specs complementaires:
 
+- `github_mcp_conversion_spec.md`: prep de conversion de `workflow_dispatch` vers une surface MCP future.
 - `kicad_mcp_scope_spec.md`: perimetre fonctionnel, hors scope et criteres d'acceptation du MCP KiCad supporte.
-- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double matériel.
-- `zeroclaw_dual_hw_todo.md`: backlog opérationnel court terme pour autonomie contrôlée.
+- `mcp_tasks.md`: backlog canonique des actions MCP locales, partage entre runtime, doc et gouvernance.
+- `notion_mcp_conversion_spec.md`: prep de conversion du bridge Notion actuel vers une surface MCP future.
+- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double materiel.
+- `zeroclaw_dual_hw_todo.md`: backlog operationnel court terme pour autonomie controlee.
 
 Synchronisation `spec_kit`:
 
-- `specs/` (racine repo) et `ai-agentic-embedded-base/specs/` doivent rester alignés.
-- Après toute mise à jour, synchroniser avec:
+- `specs/` (racine repo) est la source de verite canonique.
+- `ai-agentic-embedded-base/specs/` est un miroir exporte.
+- Apres toute mise a jour canonique, synchroniser le miroir avec:
   - `rsync -a --delete specs/ ai-agentic-embedded-base/specs/`
-- Vérifier l'absence d'écart avec:
+- Verifier l'absence d'ecart avec:
   - `diff -ru ai-agentic-embedded-base/specs specs`

ai-agentic-embedded-base/specs/constraints.yaml

@@ -4,7 +4,7 @@ project:
   targets:
     - esp32s3
     - esp32
-    - native
+    - esp32dev
 
 ai:
   triggers:

ai-agentic-embedded-base/specs/github_mcp_conversion_spec.md

@@ -0,0 +1,51 @@
+# Spec conversion MCP GitHub dispatch
+
+Last updated: 2026-03-07
+
+## Objectif
+
+Documenter l'implémentation MCP `github-dispatch` à partir de l'intégration `workflow_dispatch` existante, sans remplacer la voie API existante en V1.
+
+## État actuel
+
+- backend réel dans `mascarade/api/src/lib/killlife.ts` et `crazy_life/api/src/lib/killlife.ts`
+- dépendance secrète: `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN`
+- contrôle de sécurité actuel:
+  - allowlist de workflows
+  - sanitation des clés d'input
+  - repo et ref par défaut contrôlés
+
+## Surface MCP implémentée
+
+Serveur MCP `github-dispatch` local avec les outils:
+
+- `list_allowlisted_workflows`
+- `dispatch_workflow`
+- `get_dispatch_status`
+
+## Mapping depuis l'existant
+
+- config allowlist actuelle -> `list_allowlisted_workflows`
+- `POST /repos/:repo/actions/workflows/:workflow/dispatches` -> `dispatch_workflow`
+- suivi de run et réconciliation locale -> `get_dispatch_status`
+
+## Contraintes
+
+- garder `stdio` comme transport par défaut
+- interdire tout dispatch hors allowlist
+- ne pas exposer de surface générique GitHub issue/PR/repo en V1
+- conserver l'API actuelle tant que les éditeurs de workflow ne consomment pas MCP
+- launcher opérateur: `tools/run_github_dispatch_mcp.sh`
+
+## Hors scope V1
+
+- gestion générique GitHub
+- mutation libre d'issues, PR, labels ou releases
+- changement dynamique du repo cible hors politique versionnée
+
+## Validation minimale
+
+- handshake `initialize -> tools/list` vert
+- `dispatch_workflow` refuse un workflow non allowlisté
+- erreur structurée si token absent
+- `get_dispatch_status` retourne un état exploitable sans lecture manuelle brute de l'API GitHub

ai-agentic-embedded-base/specs/kicad_mcp_scope_spec.md

@@ -6,7 +6,7 @@ Last updated: 2026-03-07
 
 - O1. Definir le perimetre fonctionnel du serveur MCP KiCad supporte par `Kill_LIFE`.
 - O2. Eviter la derive entre implementation serveur, launcher local, docs et attentes des agents.
-- O3. Fixer une frontiere claire entre ce que le MCP KiCad MUST couvrir en v1, ce qui SHOULD venir en v2, et ce qui reste hors scope.
+- O3. Fixer une frontiere claire entre le contrat stable du MCP KiCad, les extensions futures legitimes et ce qui reste hors scope.
 
 ## Non-objectifs
 
@@ -34,6 +34,7 @@ Last updated: 2026-03-07
   - Le serveur MUST exposer `stdio` local uniquement.
   - Le serveur MUST parler JSON-RPC compatible MCP avec framing ligne par ligne, conforme au SDK utilise.
   - Le serveur MUST fonctionner via `tools/hw/run_kicad_mcp.sh`.
+  - Le serveur MUST exposer une seule surface stable; aucun profil runtime alternatif ne doit etre requis.
 
 - F2. Cycle projet
   - Le serveur MUST permettre de creer, ouvrir, sauvegarder et inspecter un projet KiCad.
@@ -68,7 +69,13 @@ Last updated: 2026-03-07
   - Le serveur SHOULD permettre la recherche de composants JLCPCB/LCSC, les alternatives proches et l'acces aux datasheets.
   - Les integrations de sourcing MAY utiliser un backend local ou une API externe si les credentials sont presents.
 
-- F10. Runtime
+- F10. Resources / prompts / UI
+  - Le serveur MUST exposer `tools`, `resources` et `prompts` comme surface stable unique.
+  - Toute resource exposee MUST correspondre a un backend reel et testable.
+  - Les prompts MUST referencer uniquement des capabilities supportees.
+  - Les actions UI supportees MUST retourner un resultat deterministe ou une erreur structuree quand le contexte graphique est indisponible.
+
+- F11. Runtime
   - Le serveur MUST preferer un backend KiCad reel.
   - Le backend SHOULD preferer IPC quand disponible.
   - Le backend MUST pouvoir retomber sur SWIG si IPC n'est pas disponible.
@@ -82,7 +89,7 @@ Last updated: 2026-03-07
   - Le serveur MUST NOT exiger de secrets pour les usages locaux de base.
 
 - Fiabilite
-  - `initialize` puis `tools/list` MUST passer sur une machine supportee.
+  - `initialize`, `tools/list`, `resources/list` et `prompts/list` MUST passer sur une machine supportee.
   - Le launcher MUST gerer le fallback host -> container quand l'hote n'expose pas `pcbnew`.
   - Les erreurs MUST etre actionnables et non silencieuses.
 
@@ -99,13 +106,13 @@ Last updated: 2026-03-07
   - Le contrat de transport MUST rester stable pour les consommateurs locaux de `Kill_LIFE`.
   - Le runtime conteneur supporte SHOULD rester aligne avec la version KiCad cible du projet, y compris la trajectoire v10.
 
-## V2 / extensions legitimes
+## Extensions futures legitimes
 
-- V2.1. Session IPC plus riche, synchronisee avec une UI KiCad vivante.
-- V2.2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs.
-- V2.3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation.
-- V2.4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite.
-- V2.5. Dry-run systematique pour les mutations a fort impact.
+- E1. Session IPC plus riche, synchronisee avec une UI KiCad vivante.
+- E2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs.
+- E3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation.
+- E4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite.
+- E5. Dry-run systematique pour les mutations a fort impact.
 
 ## Hors scope
 
@@ -125,11 +132,15 @@ Last updated: 2026-03-07
   - `initialize`
   - `notifications/initialized`
   - `tools/list`
+  - `resources/list`
+  - `prompts/list`
+  - `resources/read` sur au moins une resource stable
+  - `prompts/get` sur au moins un prompt stable
 
 ## Critieres d'acceptation
 
 - AC1. Le repo documente un seul serveur KiCad MCP supporte en v1.
-- AC2. Le serveur expose au moins une famille d'outils fonctionnelle pour: projet, schema, PCB, librairies, validation, export.
+- AC2. Le serveur expose une surface stable fonctionnelle pour: projet, schema, PCB, librairies, validation, export, resources, prompts et sourcing.
 - AC3. `python3 tools/hw/mcp_smoke.py` passe sur un environnement supporte.
 - AC4. En absence de `pcbnew` host, le launcher supporte bascule vers le runtime conteneur.
 - AC5. La doc d'usage locale renvoie explicitement vers cette spec de perimetre.

ai-agentic-embedded-base/specs/mcp_tasks.md

@@ -0,0 +1,74 @@
+# Tasks MCP local
+
+Last updated: 2026-03-07
+
+Backlog MCP canonique pour `Kill_LIFE`.
+
+Références:
+
+- doc opérateur: `docs/MCP_SETUP.md`
+- matrice de support: `docs/MCP_SUPPORT_MATRIX.md`
+- spec de périmètre: `specs/kicad_mcp_scope_spec.md`
+
+Format:
+
+- `[ ]` non fait
+- `[x]` fait
+
+## État courant
+
+- [x] K-001 — Rendre `validate-specs` réel
+  - AC: `mcp.json` ne référence plus de chemin absent.
+
+- [x] K-002 — Ajouter un launcher KiCad supporté
+  - AC: `tools/hw/run_kicad_mcp.sh` résout `mascarade`, prépare un runtime writable et exécute le serveur.
+
+- [x] K-003 — Aligner `tools/hw/cad_stack.sh mcp`
+  - AC: l'alias opérateur appelle le même launcher que `mcp.json`.
+
+- [x] K-004 — Fixer une doc opérateur canonique
+  - AC: `docs/MCP_SETUP.md` décrit le chemin réellement supporté.
+
+- [x] K-005 — Fixer une spec de périmètre canonique
+  - AC: `specs/kicad_mcp_scope_spec.md` décrit le contrat MCP KiCad supporté.
+
+- [x] K-006 — Fixer une matrice de support canonique
+  - AC: `docs/MCP_SUPPORT_MATRIX.md` classe explicitement les surfaces supportées et les chemins hors chaîne supportée.
+
+- [x] K-007 — Ajouter un smoke test consommateur versionné
+  - AC: `python3 tools/hw/mcp_smoke.py --timeout 30` passe sur un environnement supporté.
+
+- [x] K-008 — Documenter les prérequis machine utiles
+  - AC: `docs/MCP_SETUP.md` documente `node`, Docker, le repo compagnon et le fallback hôte -> conteneur.
+
+- [x] K-009 — Décider du sort du chemin `cad_stack.sh mcp`
+  - AC: ce n'est plus un chemin legacy, mais un alias supporté du launcher canonique.
+
+## À faire ensuite
+
+- [x] K-010 — Aligner la matrice de protocoles MCP
+  - AC: le runtime KiCad principal, `validate-specs` et les micro-serveurs auxiliaires exposent une compatibilité documentée et non contradictoire.
+
+- [x] K-011 — Ajouter une observabilité MCP synthétique
+  - AC: un état `ready / degraded / failed` est visible sans lecture manuelle des logs.
+
+- [ ] K-012 — Rejouer la validation host-native sur une machine avec `pcbnew`
+  - AC: le smoke passe aussi sur le chemin hôte, pas seulement via le fallback conteneur.
+
+- [x] K-013 — Décider du statut final des micro-serveurs `kicad_kic_ai`
+  - AC: `component_database`, `kicad_tools` et `nexar_api` sont explicitement promus en surfaces auxiliaires supportées.
+
+- [ ] K-014 — Valider le mode live de `nexar_api`
+  - AC: un run avec `NEXAR_TOKEN` confirme le comportement réel et le distingue du mode démo.
+
+- [x] K-015 — Implémenter le MCP `Notion`
+  - AC: `tools/run_notion_mcp.sh` expose `search_pages`, `read_page`, `append_to_page`, `create_page` sans retirer le bridge HTTP en V1.
+
+- [x] K-016 — Implémenter le MCP `GitHub dispatch`
+  - AC: `tools/run_github_dispatch_mcp.sh` expose `list_allowlisted_workflows`, `dispatch_workflow` et `get_dispatch_status` sans retirer la voie API actuelle en V1.
+
+- [x] K-017 — Ajouter des smokes MCP dedies hors KiCad
+  - AC: `validate-specs`, `notion` et `github-dispatch` ont chacun un smoke versionne avec sortie JSON.
+
+- [x] K-018 — Etendre l'observabilite MCP a plusieurs serveurs
+  - AC: `/api/ops/summary` expose un etat agrege et le detail par serveur pour `kicad`, `validate-specs`, `notion` et `github-dispatch`.

ai-agentic-embedded-base/specs/notion_mcp_conversion_spec.md

@@ -0,0 +1,51 @@
+# Spec conversion MCP Notion
+
+Last updated: 2026-03-07
+
+## Objectif
+
+Documenter l'implémentation MCP `notion` à partir de l'intégration `Notion` existante, sans remplacer la voie HTTP existante en V1.
+
+## État actuel
+
+- backend réel dans `mascarade/core/mascarade/integrations/notion.py`
+- bridge HTTP existant dans `mascarade/api/src/routes/notion.ts`
+- UI consommatrice existante dans `crazy_life/src/pages/NotionBrowser.tsx`
+- dépendance secrète: `NOTION_API_KEY`
+
+## Surface MCP implémentée
+
+Serveur MCP `notion` local avec les outils:
+
+- `search_pages`
+- `read_page`
+- `append_to_page`
+- `create_page`
+
+## Mapping depuis l'existant
+
+- `GET /api/notion/search` -> `search_pages`
+- `GET /api/notion/pages/:pageId` -> `read_page`
+- `POST /api/notion/pages/:pageId/append` -> `append_to_page`
+- `POST /api/notion/pages` -> `create_page`
+
+## Contraintes
+
+- garder `stdio` comme transport par défaut
+- ne pas exposer un MCP réseau en V1
+- erreurs explicites si `NOTION_API_KEY` absent
+- conserver le bridge HTTP existant tant que la migration client n'est pas faite
+- launcher opérateur: `tools/run_notion_mcp.sh`
+
+## Hors scope V1
+
+- suppression du bridge HTTP existant
+- édition riche avancée ou gestion fine des blocs Notion
+- sync bidirectionnelle UI <-> MCP
+
+## Validation minimale
+
+- handshake `initialize -> tools/list` vert
+- `search_pages` et `read_page` smokés
+- erreur structurée et non ambiguë si `NOTION_API_KEY` absent
+- documentation opérateur et matrice de support mises à jour

ai-agentic-embedded-base/specs/zeroclaw_dual_hw_orchestration_spec.md

@@ -9,7 +9,7 @@ Run one orchestration layer that can:
 - converse against `RTC_BL_PHONE` and `le-mystere-professeur-zacus` independently,
 - keep workspace boundaries strict per repo,
 - run low-cost autonomous loops with guarded command allowlists,
-- stay ready for connected hardware checks before any upload/flash action.
+- enforce upload/flash/serial-monitor loops by default on connected hardware.
 
 ## 2) Scope
 
@@ -18,6 +18,7 @@ In scope:
 - local ZeroClaw profile bootstrap for both repos,
 - deterministic workspace switch (`rtc` vs `zacus`) from one CLI entrypoint,
 - hardware discovery/introspection preflight,
+- forced-by-default firmware loop (build + upload + monitor) per repo target,
 - lightweight CI validation for orchestration scripts/spec.
 
 Out of scope:
@@ -64,23 +65,57 @@ This keeps `autonomy.workspace_only = true` effective on a per-repo boundary.
 - `tools/ai/zeroclaw_dual_chat.sh`
   - target switch by alias (`rtc`, `zacus`) or absolute path,
   - message mode (`-m`) or interactive mode,
-  - provider auto-fallback (`copilot` -> `openai-codex` -> `openrouter`),
+  - `--cheap` mode to prefer local provider routing for low-credit runs,
+  - loads local auth env file `~/.zeroclaw/env` when present,
+  - provider auto-fallback (`ollama` when local preferred -> `copilot` -> `openai-codex` -> `gemini` -> `openrouter` -> `anthropic` -> `openai`),
   - token sourcing from `gh auth token` at runtime only when `copilot` is selected.
 - `tools/ai/zeroclaw_stack_up.sh`
   - starts local gateway and local follow server,
   - reuses existing listeners when ports are already bound (prevents duplicate-start failures),
+  - loads local auth env file `~/.zeroclaw/env` when present,
+  - auto-aligns gateway provider/model for autonomous cost control:
+    - default uses `openai-codex` when auth profile exists (reliable baseline),
+    - optionally prefers local `ollama` when `ZEROCLAW_PREFER_LOCAL_AI=1`,
+    - otherwise uses `openrouter` when API key exists,
+  - writes reliability fallback chain in config (`ollama -> openai-codex -> openrouter` when available),
+  - attempts automatic gateway pairing and token refresh,
+  - validates bearer token with a malformed webhook probe (`{}` payload) and re-pairs when possible,
   - generates live follow dashboard at `http://127.0.0.1:8788/`,
   - dashboard includes live polling panels for `/conversations.jsonl` and `/gateway.log` (1s polling),
   - preserves direct raw links: `/conversations.jsonl` and `/gateway.log`,
+  - starts `tools/ai/zeroclaw_watch_1min.sh` watcher and exposes `/realtime_1min.log`,
   - writes `artifacts/zeroclaw/prometheus.yml` scrape config,
-  - supports local Prometheus startup via `ZEROCLAW_PROM_MODE` (`off`, `auto`, `binary`, `docker`),
+  - supports local Prometheus startup via `ZEROCLAW_PROM_MODE` (`off`, `auto`, `binary`, `docker`) with `auto` fallback `binary -> docker`,
+  - on macOS, auto-attempts Docker Desktop startup before Prometheus docker mode,
   - stores pair token in `artifacts/zeroclaw/pair_token.txt`.
 - `tools/ai/zeroclaw_stack_down.sh`
   - stops local gateway/follow processes,
   - stops local Prometheus process/container if managed by the stack,
+  - stops `tools/ai/zeroclaw_watch_1min.sh` watcher process,
   - confirms logs remain in `artifacts/zeroclaw/`.
+- `tools/ai/zeroclaw_watch_1min.sh`
+  - supports `start|stop|status|run|once`,
+  - appends one status line every 60s by default to `artifacts/zeroclaw/realtime_1min.log`,
+  - line format:
+    - `<ts> | paired=<...> | uptime=<...> | prom=<...> | convo=<last line> | gateway=<last line>`
+- `tools/ai/zeroclaw_hw_firmware_loop.sh`
+  - target switch `rtc|zacus`,
+  - validates `platformio.ini` env exists before running,
+  - forces `build -> upload -> serial monitor` by default,
+  - auto-retries with a compatible env when chip mismatch is detected (`ESP32` vs `ESP32-S3`),
+  - auto-detects serial port when not specified,
+  - on macOS, wraps monitor with `script` pseudo-TTY to avoid `termios` non-interactive failures,
+  - monitor timeout default 60s.
+- `tools/ai/ollama_local_setup.sh`
+  - installs `ollama` via Homebrew when missing,
+  - starts local service,
+  - optionally pulls/warms a local model,
+  - prints zero-credit defaults for stack usage.
 - `tools/ai/zeroclaw_webhook_send.sh`
-  - requires `--allow-model-call` before any real webhook send,
+  - sends webhook by default (no mandatory allow flag),
+  - keeps `--allow-model-call` as backward-compatible legacy option,
+  - supports `--dry-run` to validate payload/limits without network send,
+  - enforces autonomous local quotas with `artifacts/zeroclaw/webhook_budget.json`,
   - supports `--repo-hint <hint>` metadata tagging,
   - appends enriched JSONL traces to `artifacts/zeroclaw/conversations.jsonl`.
 
@@ -89,9 +124,19 @@ This keeps `autonomy.workspace_only = true` effective on a per-repo boundary.
 Auto provider selection order in `zeroclaw_dual_chat.sh`:
 
 1. explicit `ZEROCLAW_PROVIDER` override,
-2. `copilot` when `gh` auth is valid and Copilot billing endpoint is accessible,
-3. `openai-codex` when a ZeroClaw auth profile exists,
-4. `openrouter` when `OPENROUTER_API_KEY` is present.
+2. `ollama` when `ZEROCLAW_PREFER_LOCAL_AI=1` and local model is available,
+3. `copilot` when `gh` auth is valid and Copilot billing endpoint is accessible,
+4. `openai-codex` when a ZeroClaw auth profile exists,
+5. `gemini` when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is present,
+6. `openrouter` when `OPENROUTER_API_KEY` is present,
+7. `anthropic` when `ANTHROPIC_API_KEY`/`ANTHROPIC_OAUTH_TOKEN` is present,
+8. `openai` when `OPENAI_API_KEY` is present.
+
+Gateway bootstrap provider order in `zeroclaw_stack_up.sh`:
+
+1. `openai-codex` when auth profile exists (default mode),
+2. `openrouter` when `OPENROUTER_API_KEY` exists,
+3. `ollama` only when `ZEROCLAW_PREFER_LOCAL_AI=1` and local model is available.
 
 Observed on current machine:
 
@@ -140,6 +185,7 @@ Raw URLs:
 
 - `http://127.0.0.1:8788/conversations.jsonl`
 - `http://127.0.0.1:8788/gateway.log`
+- `http://127.0.0.1:8788/realtime_1min.log`
 - `http://127.0.0.1:8788/prometheus.yml`
 
 Conversation JSONL line schema (append-only):
@@ -155,22 +201,58 @@ Compatibility rule:
 
 - viewer tolerates legacy lines that only contain `ts`, `message`, `response_raw`.
 
-Credit-protection rule:
+Webhook execution and cost controls:
 
-- without `--allow-model-call`, `zeroclaw_webhook_send.sh` exits non-zero and does not send/write logs.
+- webhook send is enabled by default.
+- `--dry-run` performs validation only (no network call, no execution log append).
+- hourly quota and message-size limits are enforced by environment variables:
+  - `ZEROCLAW_WEBHOOK_MAX_CALLS_PER_HOUR` (default: `40`)
+  - `ZEROCLAW_WEBHOOK_MAX_CHARS` (default: `1200`)
+- quota state is stored in `artifacts/zeroclaw/webhook_budget.json`.
 
 ## 9) Prometheus Integration
 
 Economical default:
 
-- `ZEROCLAW_PROM_MODE=auto` (start only if local `prometheus` binary exists)
+- `ZEROCLAW_PROM_MODE=auto` (try local `prometheus` binary first, then Docker fallback)
 
 Optional modes:
 
 - `ZEROCLAW_PROM_MODE=off` disables Prometheus startup
 - `ZEROCLAW_PROM_MODE=binary` requires local `prometheus` binary
 - `ZEROCLAW_PROM_MODE=docker` runs `prom/prometheus:latest` locally
+- `ZEROCLAW_DOCKER_WAIT_SECS` controls Docker daemon wait timeout (default: `90`)
+- `ZEROCLAW_PROM_READY_WAIT_SECS` controls Prometheus readiness wait (default: `15`)
 
 Default local endpoint when running:
 
 - `http://127.0.0.1:9090/targets`
+
+## 10) Local Auth Bootstrap
+
+Recommended local secret file:
+
+- `~/.zeroclaw/env` (permissions `600`)
+
+Suggested contents:
+
+- `OPENROUTER_API_KEY=...`
+
+Behavior:
+
+- `zeroclaw_dual_chat.sh`, `zeroclaw_stack_up.sh`, and `zeroclaw_webhook_send.sh` auto-load this file if present.
+
+## 11) Firmware Loop Defaults (local hardware)
+
+Default execution policy:
+
+- with hardware connected, upload/flash and serial monitor are forced by default.
+- if no serial port is detected, loop fails fast (non-zero) instead of silently skipping upload.
+- only declared PlatformIO envs are allowed; no `-e native` or `-e test` shortcuts.
+
+Default commands:
+
+- RTC:
+  - `tools/ai/zeroclaw_hw_firmware_loop.sh rtc`
+- Zacus:
+  - `tools/ai/zeroclaw_hw_firmware_loop.sh zacus`

docs/MCP_ECOSYSTEM_MATRIX.md

@@ -0,0 +1,61 @@
+# MCP ecosystem matrix
+
+Last updated: 2026-03-07
+
+Matrice transverse des surfaces MCP et non-MCP observees dans `Kill_LIFE`, `mascarade` et `crazy_life`.
+
+## Statuts
+
+- `supporte`: surface active ou officiellement maintenue dans le workspace
+- `supporte avec dependance externe`: surface maintenue mais dependante d'un autre repo, d'un cache ou d'un runtime compagnon
+- `experimental`: surface presente mais pas encore validee comme chemin stable
+- `infra-only`: composant d'infra ou de migration, pas un point d'entree operateur
+- `non supporte`: historique, doc-only ou chemin non retenu
+
+## 1. Serveurs MCP reels
+
+| Surface | Repo principal | Type | Point d'entree | Statut | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `kicad` | `Kill_LIFE` + `mascarade` | serveur MCP | `tools/hw/run_kicad_mcp.sh` | supporte | runtime KiCad canonique; implementation dans `mascarade/finetune/kicad_mcp_server` |
+| `validate-specs` | `Kill_LIFE` | serveur MCP | `python3 tools/validate_specs.py --mcp` | supporte | validation repo/specs; pas un runtime CAD |
+| `notion` | `Kill_LIFE` + `mascarade` | serveur MCP | `tools/run_notion_mcp.sh` | supporte avec dependance externe | MCP local branche sur `mascarade/core/mascarade/integrations/notion.py`; garde le bridge HTTP existant |
+| `github-dispatch` | `Kill_LIFE` + `mascarade` | serveur MCP | `tools/run_github_dispatch_mcp.sh` | supporte avec dependance externe | MCP local branche sur `mascarade/core/mascarade/integrations/github_dispatch.py`; garde l'API directe existante |
+| `component_database` | `mascarade` | micro-serveur MCP | `python3 -m mcp_servers.component_db` | supporte avec dependance externe | serveur auxiliaire; depend du cache KiCad v10 et du repo compagnon |
+| `kicad_tools` | `mascarade` | micro-serveur MCP | `python3 -m mcp_servers.kicad_tools` | supporte avec dependance externe | serveur auxiliaire; depend des fichiers KiCad reels et du repo compagnon |
+| `nexar_api` | `mascarade` | micro-serveur MCP | `python3 -m mcp_servers.nexar` | experimental | serveur auxiliaire; mode demo sans token, validation live encore ouverte |
+
+## 2. Consommateurs et configs MCP
+
+| Surface | Repo principal | Type | Point d'entree | Statut | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `mcp.json` | `Kill_LIFE` | config consommateur MCP | `mcp.json` | supporte | reference `kicad`, `validate-specs`, `notion` et `github-dispatch` |
+| `MCP setup` | `Kill_LIFE` | doc operateur MCP | `docs/MCP_SETUP.md` | supporte | source de verite d'usage local |
+| `KiCad plugin MCP config` | `mascarade` | config plugin MCP | `finetune/kicad_kic_ai/plugins/mcp_config.json` | supporte avec dependance externe | concerne les micro-serveurs auxiliaires, pas le runtime canonique |
+| `ops MCP probe` | `mascarade` | observabilite synthetique | `/api/ops/summary` via `api/src/routes/ops.ts` | supporte avec dependance externe | expose l'etat agrege de `kicad`, `validate-specs`, `notion` et `github-dispatch`, plus le detail par serveur |
+| `crazy_life MCP positionnement` | `crazy_life` | doc de non-ownership | `docs/MCP_PLAN_2026-03-07.md` | supporte | `crazy_life` ne porte pas de serveur MCP |
+
+## 3. Integrations tierces non-MCP
+
+| Surface | Repo principal | Type | Point d'entree | Dependance | Statut | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| `Notion bridge` | `mascarade` | API HTTP interne | `/api/notion/*` via `api/src/routes/notion.ts` | `NOTION_API_KEY` | supporte | bridge backend vers le client Notion, conserve en parallele du MCP `notion` |
+| `Notion client core` | `mascarade` | integration SDK | `core/mascarade/integrations/notion.py` | `NOTION_API_KEY` | supporte | source de verite backend Notion |
+| `NotionBrowser UI` | `crazy_life` | UI consommatrice | `src/pages/NotionBrowser.tsx` | backend `mascarade` | supporte | consomme encore le bridge HTTP Notion; migration MCP possible ensuite |
+| `GitHub dispatch` | `mascarade` | API GitHub directe | `api/src/lib/killlife.ts` | `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` | supporte | lance `workflow_dispatch`, conserve en parallele du MCP `github-dispatch` |
+| `GitHub dispatch` | `crazy_life` | API GitHub directe | `api/src/lib/killlife.ts` | `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` | supporte | miroir cote repo canonique frontend/API; migration MCP possible ensuite |
+| `KillLife workflow editors` | `mascarade` + `crazy_life` | UI orchestration | `web/src/pages/KillLifeWorkflowEditor.tsx`, `src/pages/KillLifeWorkflowEditor.tsx`, `src/pages/CrazyLaneEditor.tsx` | backend API | supporte | exposent `github-dispatch` comme type de noeud, pas comme MCP |
+
+## 4. Surfaces infra-only ou migration
+
+| Surface | Repo principal | Type | Point d'entree | Statut | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `openmemory-mcp / mem0` | `mascarade` | conteneur MCP tiers | `deploy/migration/compose.tools.ai.yml` | infra-only | profil `heavy`, non documente comme point d'entree canonique, non observe en execution sur cette machine |
+| `kicad-sch-mcp` | docs historiques | ancien serveur MCP externe | documentation seulement | non supporte | pas package ni retenu dans le workspace actuel |
+
+## 5. Conclusion
+
+- le point d'entree operateur MCP de `Kill_LIFE` reste la surface `kicad` lancee par `tools/hw/run_kicad_mcp.sh`
+- `Notion` et `GitHub dispatch` disposent aussi d'un serveur MCP local, mais leur logique applicative reste fournie par `mascarade`
+- `crazy_life` consomme des surfaces applicatives, mais n'own pas de serveur MCP
+- `mem0/openmemory-mcp` reste une brique d'infra optionnelle, hors chaine operateur canonique
+- les surfaces auxiliaires `kicad_kic_ai` ne doivent pas etre lues comme equivalentes au point d'entree operateur `kicad`

docs/MCP_SETUP.md

@@ -1,46 +1,83 @@
-# MCP setup (KiCad)
+# MCP setup
 
-Source canonique pour la configuration MCP locale de `Kill_LIFE`.
+Source canonique pour l'usage MCP local de `Kill_LIFE`.
 
-Spec de perimetre:
+References canoniques:
 
-- `specs/kicad_mcp_scope_spec.md`
+- spec de perimetre: `specs/kicad_mcp_scope_spec.md`
+- matrice de support: `docs/MCP_SUPPORT_MATRIX.md`
+- matrice ecosysteme: `docs/MCP_ECOSYSTEM_MATRIX.md`
+- backlog MCP: `specs/mcp_tasks.md`
 
-## Chemin supporté
+## Source de verite et ownership
 
-- Serveur MCP supporté: `mascarade/finetune/kicad_mcp_server`
-- Launcher supporté côté `Kill_LIFE`: `tools/hw/run_kicad_mcp.sh`
-- Transport supporté: `stdio` local uniquement
-- Profil supporté par défaut: `v1`
-- Profil étendu optionnel: `v2`
+- `Kill_LIFE` own le lancement, la consommation et la gouvernance documentaire MCP locale
+- `mascarade` own l'implementation du serveur KiCad principal et l'observabilite compagnon
+- `specs/` a la racine de `Kill_LIFE` est la source de verite canonique
+- `ai-agentic-embedded-base/specs/` n'est qu'un miroir exporte
 
-`kicad-sch-mcp` n’est plus le chemin recommandé dans ce repo. Il reste un ancien axe documentaire, mais il n’est ni installé ni supporté ici comme runtime principal.
+## Chemins supportes
 
-## Prérequis
+- serveur MCP KiCad supporte: `../mascarade/finetune/kicad_mcp_server`
+- launcher supporte cote `Kill_LIFE`: `tools/hw/run_kicad_mcp.sh`
+- alias operateur supporte: `tools/hw/cad_stack.sh mcp`
+- serveur auxiliaire supporte: `python3 tools/validate_specs.py --mcp`
+- serveur MCP Notion supporte: `tools/run_notion_mcp.sh`
+- serveur MCP GitHub dispatch supporte: `tools/run_github_dispatch_mcp.sh`
+- transport supporte: `stdio` local uniquement
+
+`kicad-sch-mcp` n'est plus un chemin supporte dans ce repo. Il reste un ancien axe documentaire, pas un runtime principal.
+
+## Ce qui est reellement supporte
+
+- `kicad`: runtime MCP KiCad canonique, avec `tools`, `resources` et `prompts`
+- `validate-specs`: validation repo/specs cote `Kill_LIFE`, sans role CAD
+- `notion`: MCP local sur le backend Notion existant de `mascarade`
+- `github-dispatch`: MCP local pour workflows GitHub allowlistes
+
+Les micro-serveurs `kicad_kic_ai` de `mascarade` sont suivis comme surfaces auxiliaires. Ils ne sont pas des points d'entree operateur `Kill_LIFE`, et leur statut doit etre lu avec leurs dependances externes dans `docs/MCP_SUPPORT_MATRIX.md`.
+
+## Prerequis
 
 - le repo compagnon `mascarade` existe en voisin (`../mascarade`) ou via `MASCARADE_DIR`
 - `node` est disponible sur la machine
-- le serveur est buildé dans `mascarade/finetune/kicad_mcp_server/dist/index.js`
-- KiCad et son Python sont visibles par le runtime du serveur
+- le serveur est builde dans `mascarade/finetune/kicad_mcp_server/dist/index.js`
+- le venv `mascarade/core/.venv` existe, ou `MASCARADE_CORE_PYTHON` pointe vers un Python avec `notion-client` et `httpx`
+- Docker est disponible pour le fallback conteneur KiCad v10
+- `pcbnew` cote hote est optionnel: s'il est absent, le launcher bascule vers le conteneur supporte
+- `NOTION_API_KEY` est requis pour les outils `notion`
+- `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` est requis pour `dispatch_workflow`
 
-Diagnostic rapide :
+Le runtime prepare un environnement writable sous `.cad-home/kicad-mcp/` et exporte `KICAD_MCP_DATA_DIR` pour eviter les ecritures dans un prefixe immuable.
+
+## Diagnostic rapide
+
+Depuis `Kill_LIFE`:
 
 ```bash
 tools/hw/run_kicad_mcp.sh --doctor
-python3 tools/hw/mcp_smoke.py
+tools/hw/cad_stack.sh mcp --doctor
+tools/run_notion_mcp.sh --doctor
+tools/run_github_dispatch_mcp.sh --doctor
+python3 tools/validate_specs_mcp_smoke.py --json --quick
+python3 tools/notion_mcp_smoke.py --json --quick
+python3 tools/github_dispatch_mcp_smoke.py --json --quick
+python3 tools/hw/mcp_smoke.py --json --quick --timeout 30
+python3 tools/hw/mcp_smoke.py --timeout 30
+python3 tools/validate_specs.py --json
 ```
 
-Sélection de profil :
+Sur cette machine auditee, le smoke KiCad passe via le fallback conteneur:
 
-```bash
-tools/hw/run_kicad_mcp.sh --profile v1
-tools/hw/run_kicad_mcp.sh --profile v2
-python3 tools/hw/mcp_smoke.py --profile v2
-```
+- `HOST_PCBNEW_IMPORT=missing`
+- `CONTAINER_STATUS=available`
+- `python3 tools/hw/mcp_smoke.py --timeout 30` passe
+- `python3 tools/notion_mcp_smoke.py --json --quick` retourne `degraded` tant que `NOTION_API_KEY` est absent
+- `python3 tools/github_dispatch_mcp_smoke.py --json --quick` retourne `degraded` tant que le token GitHub est absent
 
 ## Configuration locale
 
-Le fichier versionné [mcp.json](../mcp.json) pointe déjà vers le launcher supporté :
+Le fichier versionne [mcp.json](../mcp.json) pointe vers les serveurs MCP reellement supportes:
 
 ```json
 {
@@ -48,38 +85,80 @@ Le fichier versionné [mcp.json](../mcp.json) pointe déjà vers le launcher sup
     "kicad": {
       "type": "local",
       "command": "bash",
-      "args": ["tools/hw/run_kicad_mcp.sh", "--profile", "v1"],
+      "args": ["tools/hw/run_kicad_mcp.sh"],
+      "tools": ["*"]
+    },
+    "validate-specs": {
+      "type": "local",
+      "command": "python3",
+      "args": ["tools/validate_specs.py", "--mcp"],
+      "tools": ["*"]
+    },
+    "notion": {
+      "type": "local",
+      "command": "bash",
+      "args": ["tools/run_notion_mcp.sh"],
+      "tools": ["*"]
+    },
+    "github-dispatch": {
+      "type": "local",
+      "command": "bash",
+      "args": ["tools/run_github_dispatch_mcp.sh"],
       "tools": ["*"]
     }
   }
 }
 ```
 
-Le launcher prépare un runtime local writable sous `.cad-home/kicad-mcp/` et exporte `KICAD_MCP_DATA_DIR` pour éviter les écritures dans un préfixe immuable.
-Il applique aussi par défaut un niveau de logs discret (`warn`) pour éviter de polluer les clients MCP sur le chemin nominal.
-
-## Serveur auxiliaire
-
-`Kill_LIFE` expose aussi un serveur MCP auxiliaire `validate-specs` pour la validation repo/specs :
-
-```bash
-python3 tools/validate_specs.py --json
-python3 tools/validate_specs.py --mcp
-```
-
-Ce serveur ne remplace pas le runtime KiCad. Il sert à vérifier les specs, la conformité et l’usage RFC2119 côté dépôt.
-
 ## Usage
 
-Depuis `Kill_LIFE` :
+Depuis `Kill_LIFE`:
 
 ```bash
 tools/hw/run_kicad_mcp.sh
+tools/hw/cad_stack.sh mcp
+python3 tools/validate_specs.py --mcp
+tools/run_notion_mcp.sh
+tools/run_github_dispatch_mcp.sh
 ```
 
+Le smoke `tools/hw/mcp_smoke.py` valide actuellement la surface cible suivante:
+
+- `initialize`
+- `tools/list`
+- `resources/list`
+- `prompts/list`
+- creation de projet
+- lecture de resources stables
+- lecture d'un prompt stable
+
+Les smokes dedies supplementaires sont:
+
+- `tools/validate_specs_mcp_smoke.py`: handshake MCP de `validate-specs`
+- `tools/notion_mcp_smoke.py`: handshake MCP de `notion`, puis validation live si le secret est disponible
+- `tools/github_dispatch_mcp_smoke.py`: handshake MCP de `github-dispatch`, puis validation allowlist et live optionnelle
+
+Le chemin d'observabilite synthetique n'est pas fourni par `Kill_LIFE` seul. Si la stack compagnon `mascarade` tourne, `/api/ops/summary` expose un bloc `mcp` qui remonte le statut, le runtime reellement choisi, la version de protocole et les compteurs de surface.
+
+## Outils auxiliaires
+
+- `tools/hw/sync_kicad_v10_libs.sh` est un helper auxiliaire optionnel, hors chemin operateur principal, pour prechauffer les libs/cache KiCad v10 des micro-serveurs auxiliaires
+- ce helper depend:
+  - d'une image Docker locale `kill_life_cad-kicad-mcp:latest`
+  - du repo compagnon `mascarade`
+- ce helper n'est pas requis pour lancer le runtime `kicad` canonique
+
 ## Politique de support
 
-- `stdio` reste le seul transport supporté par défaut
-- aucun serveur MCP réseau n’est exposé par défaut
-- les serveurs mock/demo restent hors chemin de production tant qu’ils ne parlent pas à un backend réel
-- `tools/hw/cad_stack.sh mcp` reste un chemin legacy à réaligner avant d’être re-documenté ici
+- `stdio` reste le seul transport supporte par defaut
+- aucun serveur MCP reseau n'est expose par defaut
+- `tools/hw/cad_stack.sh mcp` est un alias supporte du launcher canonique
+- le runtime KiCad canonique est celui de `mascarade/finetune/kicad_mcp_server`
+- `validate-specs` reste un MCP auxiliaire repo/specs, pas un runtime CAD
+- `notion` et `github-dispatch` restent en `stdio` local et reutilisent les backends existants
+- les micro-serveurs `kicad_kic_ai` sont des surfaces auxiliaires suivies, mais restent hors chemin operateur `Kill_LIFE`
+
+## Points encore ouverts
+
+- le chemin host-native avec `pcbnew` doit encore etre revalide sur une machine qui expose reellement KiCad Python
+- `nexar_api` doit encore etre valide en mode live avec `NEXAR_TOKEN`

docs/MCP_SUPPORT_MATRIX.md

@@ -0,0 +1,49 @@
+# MCP support matrix
+
+Last updated: 2026-03-07
+
+Matrice canonique du statut MCP pour `Kill_LIFE`, `mascarade` et les surfaces associees.
+
+Vue plus large de l'ecosysteme:
+
+- `docs/MCP_ECOSYSTEM_MATRIX.md`
+
+## Statuts
+
+- `supporte`: surface officiellement maintenue et validee comme point d'entree operateur
+- `supporte avec dependance externe`: surface maintenue dans le workspace, mais dependante d'un runtime, d'un cache, d'un token ou d'un repo compagnon
+- `experimental`: surface presente et suivie, mais pas encore validee comme chemin operateur stable
+- `non supporte`: ancien chemin, historique ou simple reference documentaire
+
+## Matrice
+
+| Surface | Point d'entree | Ownership | Protocole observe / declare | Statut | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `kicad` | `tools/hw/run_kicad_mcp.sh` | launcher `Kill_LIFE`, serveur `mascarade/finetune/kicad_mcp_server` | `2025-03-26` observe au smoke | supporte | runtime KiCad canonique; `tools/hw/cad_stack.sh mcp` est un alias supporte |
+| `validate-specs` | `python3 tools/validate_specs.py --mcp` | `Kill_LIFE` | `2025-03-26` observe en test | supporte | validation repo/specs; ne remplace pas le runtime KiCad |
+| `notion` | `tools/run_notion_mcp.sh` | launcher `Kill_LIFE`, backend `mascarade/core/mascarade/integrations/notion.py` | `2025-03-26` observe en test | supporte avec dependance externe | MCP local branche sur le backend Notion de `mascarade`; requiert `NOTION_API_KEY` et le repo compagnon |
+| `github-dispatch` | `tools/run_github_dispatch_mcp.sh` | launcher `Kill_LIFE`, backend `mascarade/core/mascarade/integrations/github_dispatch.py` | `2025-03-26` observe en test | supporte avec dependance externe | MCP local pour workflows allowlistes; requiert `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` et le repo compagnon |
+| `component_database` | `python3 -m mcp_servers.component_db` | `mascarade/finetune/kicad_kic_ai` | `2025-03-26` observe au handshake | supporte avec dependance externe | micro-serveur auxiliaire; depend du repo compagnon `mascarade`, du cache KiCad v10 et d'un index local prechauffe |
+| `kicad_tools` | `python3 -m mcp_servers.kicad_tools` | `mascarade/finetune/kicad_kic_ai` | `2025-03-26` observe au handshake | supporte avec dependance externe | micro-serveur auxiliaire; analyses reelles si les fichiers KiCad et dependances associees sont disponibles |
+| `nexar_api` | `python3 -m mcp_servers.nexar` | `mascarade/finetune/kicad_kic_ai` | `2025-03-26` observe au handshake | experimental | micro-serveur auxiliaire; sans `NEXAR_TOKEN`, reste en mode demo; validation live encore ouverte |
+
+## Hors chaine supportee
+
+| Surface | Point d'entree | Ownership | Protocole observe / declare | Statut | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `kicad-sch-mcp` | aucun chemin versionne supporte ici | historique | n/a | non supporte | ancien chemin documentaire, pas un runtime principal de ce workspace |
+
+## Decisions importantes
+
+- `Kill_LIFE` n'own pas de second serveur KiCad concurrent
+- `stdio` reste le seul transport supporte par defaut
+- le runtime KiCad supporte passe par `Kill_LIFE` pour le lancement et par `mascarade` pour l'implementation
+- `notion` et `github-dispatch` sont supportes comme serveurs MCP locaux, mais leur logique applicative reste fournie par `mascarade`
+- les micro-serveurs `kicad_kic_ai` sont suivis comme surfaces auxiliaires, pas comme point d'entree operateur `Kill_LIFE`
+- le probe synthetique MCP expose cote ops appartient a `mascarade/api/src/routes/ops.ts`; il n'est disponible que si la stack compagnon tourne
+
+## Dettes encore ouvertes
+
+- le chemin host-native avec `pcbnew` n'est pas encore revalide sur une machine qui l'expose reellement
+- `nexar_api` doit encore etre valide en mode live avec credentials
+- le statut des micro-serveurs auxiliaires doit rester distinct de la surface operateur `kicad`

docs/plans/15_plan_mcp_runtime_alignment.md

@@ -1,42 +1,80 @@
-# 15) Plan d’alignement MCP local
+# 15) Plan d'alignement MCP local
 
 Last updated: 2026-03-07
 
+Ce fichier est le plan MCP canonique cote `Kill_LIFE`.
+
+Sources de verite associees:
+
+- `docs/MCP_SETUP.md`
+- `docs/MCP_SUPPORT_MATRIX.md`
+- `specs/kicad_mcp_scope_spec.md`
+- `specs/mcp_tasks.md`
+
 ## Objectif
 
-Faire de `Kill_LIFE` le repo de consommation et de gouvernance MCP, sans maintenir un second serveur MCP concurrent.
+Faire de `Kill_LIFE` le repo de consommation et de gouvernance MCP, sans maintenir un second serveur KiCad concurrent.
 
-## Cible supportée
+## Etat actuel
 
-- serveur: `../mascarade/finetune/kicad_mcp_server`
-- launcher local: `tools/hw/run_kicad_mcp.sh`
-- config MCP versionnée: `mcp.json`
-- transport: `stdio`
-- serveur auxiliaire repo/specs: `tools/validate_specs.py --mcp`
+- `mcp.json` pointe vers des launchers MCP reels pour `kicad`, `validate-specs`, `notion` et `github-dispatch`
+- `tools/hw/run_kicad_mcp.sh` est le point d'entree canonique pour le runtime KiCad
+- `tools/hw/cad_stack.sh mcp` est deja aligne sur ce launcher
+- `python3 tools/hw/mcp_smoke.py --timeout 30` passe sur la machine auditee via fallback conteneur
+- `validate-specs` existe comme CLI et comme serveur MCP `stdio`
+- la pile MCP locale converge sur `2025-03-26`
+- l'observabilite synthetique MCP est exposee via `/api/ops/summary` si la stack compagnon `mascarade` tourne
 
-## Actions
+## Decisions figees
 
-### 1. Source de vérité
+- `Kill_LIFE` ne publie pas de second runtime KiCad host-side concurrent
+- `mascarade/finetune/kicad_mcp_server` reste l'implementation serveur KiCad de reference
+- `stdio` reste le seul transport supporte par defaut
+- la matrice de support MCP est centralisee dans `docs/MCP_SUPPORT_MATRIX.md`
+- le backlog executable est centralise dans `specs/mcp_tasks.md`
+- `specs/` a la racine est la source de verite canonique; `ai-agentic-embedded-base/specs/` reste un miroir exporte
 
-1. Retirer toute promesse de serveur fantôme.
-2. Pointer `mcp.json` vers le launcher supporté et les MCP auxiliaires réels.
-3. Basculer la doc MCP canonique sur `docs/MCP_SETUP.md`.
+## Travail deja absorbe
 
-### 2. Runtime opérable
+1. Retirer les promesses cassees de `mcp.json`
+2. Rendre `validate-specs` executable en CLI et en MCP
+3. Rendre le launcher KiCad operable avec runtime writable
+4. Aligner `cad_stack.sh mcp` sur le launcher supporte
+5. Stabiliser le fallback conteneur KiCad v10
+6. Ajouter un smoke consommateur versionne
+7. Fixer une doc d'usage canonique et une matrice de support
 
-1. Faire de `tools/hw/cad_stack.sh mcp` un simple wrapper vers le launcher supporté.
-2. Préparer un runtime writable sous `.cad-home/kicad-mcp`.
-3. Garder `MASCARADE_DIR` comme override explicite, pas comme dépendance cachée.
+## Travail restant
 
-### 3. Documentation
+### Priorite 1 — Alignement protocole
 
-1. Transformer les duplications `ai-agentic-embedded-base/docs/*` en pointeurs vers les docs canoniques.
-2. Corriger les références à `validate_specs.py`.
-3. Garder `stdio only` comme politique MCP locale.
+1. Fait
+2. Les launchers MCP supportes et les surfaces auxiliaires suivies convergent vers `2025-03-26`.
 
-## Critères de sortie
+### Priorite 2 — Observabilite
 
-- `mcp.json` ne référence plus de fichier absent
-- `tools/hw/run_kicad_mcp.sh --doctor` résout un serveur réel
-- `tools/hw/cad_stack.sh mcp` utilise le même chemin que `mcp.json`
-- la doc root n’annonce plus `kicad-sch-mcp` comme chemin principal
+1. Fait
+2. `/api/ops/summary` expose l'etat synthetique MCP quand la stack compagnon `mascarade` est presente.
+
+### Priorite 3 — Validation host-native
+
+1. Rejouer le smoke sur une machine avec `pcbnew` disponible
+2. Confirmer que le chemin hote reste coherent avec le fallback conteneur
+
+### Priorite 4 — Classement des surfaces auxiliaires
+
+1. Fait
+2. `component_database` et `kicad_tools` sont classes `supporte avec dependance externe`.
+3. `nexar_api` reste `experimental` tant qu'il n'est pas valide en mode live.
+
+## Criteres de sortie
+
+- `Kill_LIFE` publie une seule doc operateur MCP canonique
+- la matrice de support ne laisse plus de statut implicite
+- les TODOs MCP ne sont plus dupliques entre `docs/plans` et `specs`
+- le prochain lecteur sait immediatement:
+  - quel serveur lancer
+  - quel alias utiliser
+  - ce qui est supporte localement
+  - ce qui depend encore de `mascarade`
+  - ce qui reste reellement ouvert

docs/plans/15_plan_mcp_stack.md

@@ -2,32 +2,16 @@
 
 Last updated: 2026-03-07
 
-## Objectif
+Ce fichier n'est plus le plan MCP canonique.
 
-Rendre la couche MCP de `Kill_LIFE` cohérente côté config, validation locale et usage opérateur, sans embarquer une promesse cassée.
+Source de vérité actuelle:
 
-## Décisions figées
+- plan: `docs/plans/15_plan_mcp_runtime_alignment.md`
+- matrice de support: `docs/MCP_SUPPORT_MATRIX.md`
+- backlog: `specs/mcp_tasks.md`
 
-- `mcp.json` publie le launcher KiCad supporté `tools/hw/run_kicad_mcp.sh`.
-- `Kill_LIFE` expose aussi `validate-specs` comme serveur/CLI auxiliaire de validation repo.
-- Le runtime KiCad côté `Kill_LIFE` est piloté par `mcp.json` et `tools/hw/run_kicad_mcp.sh`.
-- `Kill_LIFE` ne publie pas de second serveur KiCad host-side concurrent tant que la convergence n’est pas terminée.
+Raison:
 
-## Implémenté
-
-- [x] Ajouter `tools/validate_specs.py` comme script CLI réel.
-- [x] Exposer le même script en serveur MCP `stdio` minimal.
-- [x] Garder `mcp.json` sur le launcher KiCad versionné.
-- [x] Ajouter des tests sur le mode CLI et le handshake MCP minimal.
-
-## Reste à faire
-
-- [ ] Documenter précisément ce que couvre `validate-specs` et ce qu’il ne couvre pas.
-- [ ] Réaligner `tools/hw/cad_stack.sh mcp` sur le launcher supporté ou le déclasser explicitement.
-- [ ] Réconcilier `docs/MCP_SETUP.md`, `docs/KICAD_AI_LOCAL.md` et `deploy/cad/README.md`.
-
-## Critères de sortie
-
-- `python3 tools/validate_specs.py` fonctionne sans ambigüité.
-- `mcp.json` démarre un serveur MCP KiCad réel.
-- La doc `Kill_LIFE` ne présente plus plusieurs vérités contradictoires pour le lancement MCP.
+- `15_plan_mcp_stack.md` et `15_plan_mcp_runtime_alignment.md` dérivaient sur le même sujet
+- le plan canonique a été recentré sur l'usage opérateur réel de `Kill_LIFE`
+- le backlog exécutable a été déplacé dans `specs/mcp_tasks.md`

docs/plans/15_todo_mcp_stack.md

@@ -2,20 +2,15 @@
 
 Last updated: 2026-03-07
 
-## Sprint actuel
+Ce fichier n'est plus le TODO MCP canonique.
 
-- [x] Implémenter `tools/validate_specs.py`.
-- [x] Rendre `mcp.json` lançable.
-- [x] Ajouter un test de handshake MCP minimal.
-- [ ] Documenter le périmètre exact de `validate-specs`.
+Source de vérité actuelle:
 
-## J7
+- backlog exécutable: `specs/mcp_tasks.md`
+- doc opérateur: `docs/MCP_SETUP.md`
+- matrice de support: `docs/MCP_SUPPORT_MATRIX.md`
 
-- [ ] Aligner la doc KiCad MCP sur un seul chemin opérateur supporté.
-- [ ] Décrire la dépendance éventuelle à `mascarade` pour le runtime KiCad avancé.
-- [ ] Ajouter une preuve d’exécution `tools/hw/cad_stack.sh mcp`.
+Raison:
 
-## J30
-
-- [ ] Transformer `docs/MCP_SETUP.md` en doc canonique unique ou en simple pointeur.
-- [ ] Ajouter une matrice `supporté / expérimental / démo`.
+- le backlog MCP ne doit plus être dupliqué entre `docs/plans` et `specs`
+- `specs/mcp_tasks.md` porte maintenant l'état courant et les actions restantes

docs/plans/README.md

@@ -22,6 +22,7 @@ Ces plans sont des **runbooks** : tu peux les suivre tels quels, ou les transfor
 12. [Plan de gestion des agents](12_plan_gestion_des_agents.md)
 13. [Plan de troubleshooting](13_plan_troubleshooting.md)
 14. [Plan de release & versioning](14_plan_release_versioning.md)
+15. [Plan d'alignement MCP local](15_plan_mcp_runtime_alignment.md)
 
 ---
 

specs/README.md

@@ -1,25 +1,29 @@
 # Specs (Spec-driven)
 
-Flux conseillé (itératif) :
-1) `00_intake.md` : idée brute + contexte
+Flux conseille (iteratif) :
+1) `00_intake.md` : idee brute + contexte
 2) `01_spec.md` : spec claire + AC
 3) `02_arch.md` : architecture + ADR
-4) `03_plan.md` : plan découpé, risques, validations
-5) `04_tasks.md` : backlog exécutable (issues / PRs)
-6) Implémentation (firmware/hardware) + tests + doc
+4) `03_plan.md` : plan decoupe, risques, validations
+5) `04_tasks.md` : backlog executable (issues / PRs)
+6) Implementation (firmware/hardware) + tests + doc
 
-Le fichier `constraints.yaml` est la **source de vérité** des contraintes non-fonctionnelles et règles repo.
+Le fichier `constraints.yaml` est la **source de verite** des contraintes non-fonctionnelles et regles repo.
 
-Specs complémentaires:
+Specs complementaires:
 
+- `github_mcp_conversion_spec.md`: prep de conversion de `workflow_dispatch` vers une surface MCP future.
 - `kicad_mcp_scope_spec.md`: perimetre fonctionnel, hors scope et criteres d'acceptation du MCP KiCad supporte.
-- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double matériel.
-- `zeroclaw_dual_hw_todo.md`: backlog opérationnel court terme pour autonomie contrôlée.
+- `mcp_tasks.md`: backlog canonique des actions MCP locales, partage entre runtime, doc et gouvernance.
+- `notion_mcp_conversion_spec.md`: prep de conversion du bridge Notion actuel vers une surface MCP future.
+- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double materiel.
+- `zeroclaw_dual_hw_todo.md`: backlog operationnel court terme pour autonomie controlee.
 
 Synchronisation `spec_kit`:
 
-- `specs/` (racine repo) et `ai-agentic-embedded-base/specs/` doivent rester alignés.
-- Après toute mise à jour, synchroniser avec:
+- `specs/` (racine repo) est la source de verite canonique.
+- `ai-agentic-embedded-base/specs/` est un miroir exporte.
+- Apres toute mise a jour canonique, synchroniser le miroir avec:
   - `rsync -a --delete specs/ ai-agentic-embedded-base/specs/`
-- Vérifier l'absence d'écart avec:
+- Verifier l'absence d'ecart avec:
   - `diff -ru ai-agentic-embedded-base/specs specs`

specs/github_mcp_conversion_spec.md

@@ -0,0 +1,51 @@
+# Spec conversion MCP GitHub dispatch
+
+Last updated: 2026-03-07
+
+## Objectif
+
+Documenter l'implémentation MCP `github-dispatch` à partir de l'intégration `workflow_dispatch` existante, sans remplacer la voie API existante en V1.
+
+## État actuel
+
+- backend réel dans `mascarade/api/src/lib/killlife.ts` et `crazy_life/api/src/lib/killlife.ts`
+- dépendance secrète: `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN`
+- contrôle de sécurité actuel:
+  - allowlist de workflows
+  - sanitation des clés d'input
+  - repo et ref par défaut contrôlés
+
+## Surface MCP implémentée
+
+Serveur MCP `github-dispatch` local avec les outils:
+
+- `list_allowlisted_workflows`
+- `dispatch_workflow`
+- `get_dispatch_status`
+
+## Mapping depuis l'existant
+
+- config allowlist actuelle -> `list_allowlisted_workflows`
+- `POST /repos/:repo/actions/workflows/:workflow/dispatches` -> `dispatch_workflow`
+- suivi de run et réconciliation locale -> `get_dispatch_status`
+
+## Contraintes
+
+- garder `stdio` comme transport par défaut
+- interdire tout dispatch hors allowlist
+- ne pas exposer de surface générique GitHub issue/PR/repo en V1
+- conserver l'API actuelle tant que les éditeurs de workflow ne consomment pas MCP
+- launcher opérateur: `tools/run_github_dispatch_mcp.sh`
+
+## Hors scope V1
+
+- gestion générique GitHub
+- mutation libre d'issues, PR, labels ou releases
+- changement dynamique du repo cible hors politique versionnée
+
+## Validation minimale
+
+- handshake `initialize -> tools/list` vert
+- `dispatch_workflow` refuse un workflow non allowlisté
+- erreur structurée si token absent
+- `get_dispatch_status` retourne un état exploitable sans lecture manuelle brute de l'API GitHub

specs/kicad_mcp_scope_spec.md

@@ -6,7 +6,7 @@ Last updated: 2026-03-07
 
 - O1. Definir le perimetre fonctionnel du serveur MCP KiCad supporte par `Kill_LIFE`.
 - O2. Eviter la derive entre implementation serveur, launcher local, docs et attentes des agents.
-- O3. Fixer une frontiere claire entre ce que le MCP KiCad MUST couvrir en v1, ce qui SHOULD venir en v2, et ce qui reste hors scope.
+- O3. Fixer une frontiere claire entre le contrat stable du MCP KiCad, les extensions futures legitimes et ce qui reste hors scope.
 
 ## Non-objectifs
 
@@ -34,6 +34,7 @@ Last updated: 2026-03-07
   - Le serveur MUST exposer `stdio` local uniquement.
   - Le serveur MUST parler JSON-RPC compatible MCP avec framing ligne par ligne, conforme au SDK utilise.
   - Le serveur MUST fonctionner via `tools/hw/run_kicad_mcp.sh`.
+  - Le serveur MUST exposer une seule surface stable; aucun profil runtime alternatif ne doit etre requis.
 
 - F2. Cycle projet
   - Le serveur MUST permettre de creer, ouvrir, sauvegarder et inspecter un projet KiCad.
@@ -68,7 +69,13 @@ Last updated: 2026-03-07
   - Le serveur SHOULD permettre la recherche de composants JLCPCB/LCSC, les alternatives proches et l'acces aux datasheets.
   - Les integrations de sourcing MAY utiliser un backend local ou une API externe si les credentials sont presents.
 
-- F10. Runtime
+- F10. Resources / prompts / UI
+  - Le serveur MUST exposer `tools`, `resources` et `prompts` comme surface stable unique.
+  - Toute resource exposee MUST correspondre a un backend reel et testable.
+  - Les prompts MUST referencer uniquement des capabilities supportees.
+  - Les actions UI supportees MUST retourner un resultat deterministe ou une erreur structuree quand le contexte graphique est indisponible.
+
+- F11. Runtime
   - Le serveur MUST preferer un backend KiCad reel.
   - Le backend SHOULD preferer IPC quand disponible.
   - Le backend MUST pouvoir retomber sur SWIG si IPC n'est pas disponible.
@@ -82,7 +89,7 @@ Last updated: 2026-03-07
   - Le serveur MUST NOT exiger de secrets pour les usages locaux de base.
 
 - Fiabilite
-  - `initialize` puis `tools/list` MUST passer sur une machine supportee.
+  - `initialize`, `tools/list`, `resources/list` et `prompts/list` MUST passer sur une machine supportee.
   - Le launcher MUST gerer le fallback host -> container quand l'hote n'expose pas `pcbnew`.
   - Les erreurs MUST etre actionnables et non silencieuses.
 
@@ -99,13 +106,13 @@ Last updated: 2026-03-07
   - Le contrat de transport MUST rester stable pour les consommateurs locaux de `Kill_LIFE`.
   - Le runtime conteneur supporte SHOULD rester aligne avec la version KiCad cible du projet, y compris la trajectoire v10.
 
-## V2 / extensions legitimes
+## Extensions futures legitimes
 
-- V2.1. Session IPC plus riche, synchronisee avec une UI KiCad vivante.
-- V2.2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs.
-- V2.3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation.
-- V2.4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite.
-- V2.5. Dry-run systematique pour les mutations a fort impact.
+- E1. Session IPC plus riche, synchronisee avec une UI KiCad vivante.
+- E2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs.
+- E3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation.
+- E4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite.
+- E5. Dry-run systematique pour les mutations a fort impact.
 
 ## Hors scope
 
@@ -125,11 +132,15 @@ Last updated: 2026-03-07
   - `initialize`
   - `notifications/initialized`
   - `tools/list`
+  - `resources/list`
+  - `prompts/list`
+  - `resources/read` sur au moins une resource stable
+  - `prompts/get` sur au moins un prompt stable
 
 ## Critieres d'acceptation
 
 - AC1. Le repo documente un seul serveur KiCad MCP supporte en v1.
-- AC2. Le serveur expose au moins une famille d'outils fonctionnelle pour: projet, schema, PCB, librairies, validation, export.
+- AC2. Le serveur expose une surface stable fonctionnelle pour: projet, schema, PCB, librairies, validation, export, resources, prompts et sourcing.
 - AC3. `python3 tools/hw/mcp_smoke.py` passe sur un environnement supporte.
 - AC4. En absence de `pcbnew` host, le launcher supporte bascule vers le runtime conteneur.
 - AC5. La doc d'usage locale renvoie explicitement vers cette spec de perimetre.

specs/mcp_tasks.md

@@ -2,39 +2,73 @@
 
 Last updated: 2026-03-07
 
+Backlog MCP canonique pour `Kill_LIFE`.
+
+Références:
+
+- doc opérateur: `docs/MCP_SETUP.md`
+- matrice de support: `docs/MCP_SUPPORT_MATRIX.md`
+- spec de périmètre: `specs/kicad_mcp_scope_spec.md`
+
 Format:
 
 - `[ ]` non fait
 - `[x]` fait
 
-## Sprint actif
+## État courant
 
-- [x] K-001 — Rendre `validate-specs` réel ou retirer la promesse
-  - AC: aucun chemin absent n’est versionné comme serveur MCP.
+- [x] K-001 — Rendre `validate-specs` réel
+  - AC: `mcp.json` ne référence plus de chemin absent.
 
-- [x] K-002 — Ajouter un launcher supporté `tools/hw/run_kicad_mcp.sh`
-  - AC: le launcher résout `mascarade`, prépare un runtime writable et exécute le serveur.
+- [x] K-002 — Ajouter un launcher KiCad supporté
+  - AC: `tools/hw/run_kicad_mcp.sh` résout `mascarade`, prépare un runtime writable et exécute le serveur.
 
 - [x] K-003 — Aligner `tools/hw/cad_stack.sh mcp`
-  - AC: la commande `mcp` appelle le même launcher que `mcp.json`.
+  - AC: l'alias opérateur appelle le même launcher que `mcp.json`.
 
-- [x] K-004 — Désigner `docs/MCP_SETUP.md` comme doc canonique
-  - AC: la version miroir renvoie vers la doc racine.
+- [x] K-004 — Fixer une doc opérateur canonique
+  - AC: `docs/MCP_SETUP.md` décrit le chemin réellement supporté.
 
-- [x] K-005 — Retirer les références à `tools/validate_specs.py`
-  - AC: les docs visibles pointent vers un validateur réellement présent.
+- [x] K-005 — Fixer une spec de périmètre canonique
+  - AC: `specs/kicad_mcp_scope_spec.md` décrit le contrat MCP KiCad supporté.
+
+- [x] K-006 — Fixer une matrice de support canonique
+  - AC: `docs/MCP_SUPPORT_MATRIX.md` classe explicitement les surfaces supportées et les chemins hors chaîne supportée.
+
+- [x] K-007 — Ajouter un smoke test consommateur versionné
+  - AC: `python3 tools/hw/mcp_smoke.py --timeout 30` passe sur un environnement supporté.
+
+- [x] K-008 — Documenter les prérequis machine utiles
+  - AC: `docs/MCP_SETUP.md` documente `node`, Docker, le repo compagnon et le fallback hôte -> conteneur.
+
+- [x] K-009 — Décider du sort du chemin `cad_stack.sh mcp`
+  - AC: ce n'est plus un chemin legacy, mais un alias supporté du launcher canonique.
 
 ## À faire ensuite
 
-- [x] K-006 — Ajouter un smoke test MCP consommateur côté `Kill_LIFE`
-  - AC: un script versionné existe pour tester `initialize` et `tools/list`.
+- [x] K-010 — Aligner la matrice de protocoles MCP
+  - AC: le runtime KiCad principal, `validate-specs` et les micro-serveurs auxiliaires exposent une compatibilité documentée et non contradictoire.
 
-- [ ] K-007 — Documenter les prérequis machine minimum pour le runtime MCP
-  - AC: Node, KiCad et repo compagnon sont explicitement listés.
+- [x] K-011 — Ajouter une observabilité MCP synthétique
+  - AC: un état `ready / degraded / failed` est visible sans lecture manuelle des logs.
 
-- [ ] K-008 — Décider du sort final du service Docker `kicad-mcp` historique
-  - AC: soit supprimé, soit rebranché sur le runtime supporté sans drift.
+- [ ] K-012 — Rejouer la validation host-native sur une machine avec `pcbnew`
+  - AC: le smoke passe aussi sur le chemin hôte, pas seulement via le fallback conteneur.
 
-- [ ] K-009 — Faire passer le smoke réel `initialize -> tools/list`
-  - AC: `python3 tools/hw/mcp_smoke.py` passe sur une machine avec `pcbnew` disponible.
-  - Blocage actuel: le host audité n’expose pas `pcbnew`, donc le runtime KiCad ne peut pas démarrer.
+- [x] K-013 — Décider du statut final des micro-serveurs `kicad_kic_ai`
+  - AC: `component_database`, `kicad_tools` et `nexar_api` sont explicitement promus en surfaces auxiliaires supportées.
+
+- [ ] K-014 — Valider le mode live de `nexar_api`
+  - AC: un run avec `NEXAR_TOKEN` confirme le comportement réel et le distingue du mode démo.
+
+- [x] K-015 — Implémenter le MCP `Notion`
+  - AC: `tools/run_notion_mcp.sh` expose `search_pages`, `read_page`, `append_to_page`, `create_page` sans retirer le bridge HTTP en V1.
+
+- [x] K-016 — Implémenter le MCP `GitHub dispatch`
+  - AC: `tools/run_github_dispatch_mcp.sh` expose `list_allowlisted_workflows`, `dispatch_workflow` et `get_dispatch_status` sans retirer la voie API actuelle en V1.
+
+- [x] K-017 — Ajouter des smokes MCP dedies hors KiCad
+  - AC: `validate-specs`, `notion` et `github-dispatch` ont chacun un smoke versionne avec sortie JSON.
+
+- [x] K-018 — Etendre l'observabilite MCP a plusieurs serveurs
+  - AC: `/api/ops/summary` expose un etat agrege et le detail par serveur pour `kicad`, `validate-specs`, `notion` et `github-dispatch`.

specs/notion_mcp_conversion_spec.md

@@ -0,0 +1,51 @@
+# Spec conversion MCP Notion
+
+Last updated: 2026-03-07
+
+## Objectif
+
+Documenter l'implémentation MCP `notion` à partir de l'intégration `Notion` existante, sans remplacer la voie HTTP existante en V1.
+
+## État actuel
+
+- backend réel dans `mascarade/core/mascarade/integrations/notion.py`
+- bridge HTTP existant dans `mascarade/api/src/routes/notion.ts`
+- UI consommatrice existante dans `crazy_life/src/pages/NotionBrowser.tsx`
+- dépendance secrète: `NOTION_API_KEY`
+
+## Surface MCP implémentée
+
+Serveur MCP `notion` local avec les outils:
+
+- `search_pages`
+- `read_page`
+- `append_to_page`
+- `create_page`
+
+## Mapping depuis l'existant
+
+- `GET /api/notion/search` -> `search_pages`
+- `GET /api/notion/pages/:pageId` -> `read_page`
+- `POST /api/notion/pages/:pageId/append` -> `append_to_page`
+- `POST /api/notion/pages` -> `create_page`
+
+## Contraintes
+
+- garder `stdio` comme transport par défaut
+- ne pas exposer un MCP réseau en V1
+- erreurs explicites si `NOTION_API_KEY` absent
+- conserver le bridge HTTP existant tant que la migration client n'est pas faite
+- launcher opérateur: `tools/run_notion_mcp.sh`
+
+## Hors scope V1
+
+- suppression du bridge HTTP existant
+- édition riche avancée ou gestion fine des blocs Notion
+- sync bidirectionnelle UI <-> MCP
+
+## Validation minimale
+
+- handshake `initialize -> tools/list` vert
+- `search_pages` et `read_page` smokés
+- erreur structurée et non ambiguë si `NOTION_API_KEY` absent
+- documentation opérateur et matrice de support mises à jour