# CLAUDE.md — administration-ka.com (Admin-Ka v2)

Console d'administration du Groupe KA : app chat mobile-first qui pilote le vrai Claude Code CLI sur le cluster MacLustr, plus un monitoring temps réel de tous les sites du groupe.

# Exigences non négociables

1. Vrai Claude Code, jamais l'API Messages. Le backend lance le binaire claude (headless : claude -p --output-format stream-json --verbose --include-partial-messages), avec cwd = le repo de l'app choisie. Chaque app KA s'exécute sur son nœud de déploiement (via SSH pour les nœuds distants) — le repo de prod est la seule source de vérité, aucun clone. Tous les événements du stream (texte, thinking, tool_use, tool_result, result) sont relayés et rendus comme dans le terminal (diffs colorés, blocs outils repliables, coût/tokens).
2. Options Claude Code dans l'UI : modèle par session (Opus/Sonnet/Haiku, --model), mode de permissions (default avec cartes Autoriser/Refuser/Toujours, acceptEdits, plan, bypass derrière confirmation), choix du projet/cwd, /clear /compact /cost /resume, affichage live du modèle actif, session ID, coût cumulé, tokens de contexte.
3. Sessions détachées : le process claude ne dépend JAMAIS du WebSocket. Transcript JSONL persisté par conversation ; à la reconnexion l'app rejoue l'historique manqué puis reprend le live. États : en cours / en attente de permission / inactive. Reconnexion auto avec backoff + indicateur. Notifications in-app quand une tâche se termine ou attend une permission.
4. Écosystème : health checks HTTPS toutes les 45 s des 13 sites KA depuis M3U96a (latence, code, SSL), sweep des nœuds toutes les 5 min (charge/RAM/disque + PM2 cpu/mem/status + dernier commit), historique SQLite (data/eco.sqlite, rétention 35 j), incidents (2 échecs consécutifs → alerte, rétablissement → alerte verte), uptime 24h/7j/30j, moy/p95, sparklines + graphique 24 h + barres d'uptime 14 j, push temps réel via le même WebSocket.
5. Identité Groupe KA : crème #F2F1EC, orange #F97316 (traits de graphe #e05f00), encre #1a1611, cartes à bords noirs 2 px + ombres décalées, pills, typo ronde, pastille « Ka ». Header fixe + bottom nav (Chat / Sessions / Écosystème / Réglages) avec safe-areas. Statuts JAMAIS en couleur seule (● ▲ ■ + libellé).
6. Rien de simulé : tout est branché sur le vrai CLI et les vrais sites.

# Architecture

iPhone ⇄ wss://www.administration-ka.com (ngrok) ⇄ backend :3300 (M3U96a)
   backend ⇄ claude CLI (local, apps M3U96a) 
   backend ⇄ ssh <nœud> claude CLI (apps distantes, repo de prod)
             └ tunnel SSH inverse -R : cartes de permission (perm-mcp MCP)
   backend ⇄ monitor.js : health checks + sweep nœuds + SQLite + push WS

• server/server.js — HTTP + WS + orchestration claude + états de session.
• server/monitor.js — collecteur Écosystème (node:sqlite intégré, aucune dépendance native).
• server/perm-mcp.js — serveur MCP stdio pour --permission-prompt-tool mcp__adminka__approve ; déployé aussi sur M3U96b/M4M64a/M4M64b/M2M32 dans ~/.adminka/.
• public/ — frontend une page, 4 onglets, aucun framework.

# Pièges connus (ne pas re-découvrir)

• Tailscale inter-nœuds bloqué (ACL) : depuis M3U96a, joindre les nœuds via les noms Bonjour .local (config ~/.ssh/config en place). M2U64 = sous-réseau 192.168.0.x.
• IPv4 LAN non routée entre nœuds (EHOSTUNREACH) : les permissions distantes passent par le tunnel SSH inverse, pas par le LAN.
• ControlPath ssh avec hostnames .local trop long → %C.
• Sans --model, les nœuds retombent sur leur défaut local (Sonnet) → toujours passer --model explicitement.
• Auth headless par ANTHROPIC_API_KEY de ~/.claude/.env (pas de login OAuth sur les nœuds).
• Chaque run reçoit --append-system-prompt : après toute modif → rebuild + pm2 restart + healthcheck + commit/push spbgit (origin, pas GitHub).

# Exploitation

# sur M3U96a
launchctl kickstart -k gui/501/io.adminka.backend   # redémarrer backend
launchctl kickstart -k gui/501/io.adminka.ngrok     # redémarrer tunnel
tail -f ~/apps/admin-ka/data/backend.err.log
node server/set-password.js '<nouveau>'             # changer le mot de passe

Registre des déploiements : ~/Desktop/cluster-skill/cluster-deployments.json (laptop, source de vérité). Repo : spbgit ~/srv/git/admin-ka.git.