📋 Os 6 passos do installer
O scripts/install.sh faz 6 passos sequenciais. Cada um valida-se antes do seguinte. Total: ~30 segundos numa máquina já preparada.
Valida prereqs
Node ≥18, Python ≥3.9, Git, Claude Code CLI. Se algo falta ou versão antiga, bloqueia com mensagem clara.
Instala Sinapsis em ~/.claude
Copia vendor/sinapsis/ para ~/.claude/skills/ + comandos globais (/system-status, /evolve, etc.).
Cria estrutura OS (Camada)
Garante brand-context/, context/, projects/, clients/_templates/ com placeholders.
Cria soul.md + decisions-log.md
Ficheiros seed que o agente lê em cada sessão. soul.md = personalidade. decisions-log = histórico append-only.
Instala _install-gate.sh hook
Copia o hook para ~/.claude/skills/_install-gate.sh e dá-lhe permissões de execução.
Regista hook em settings.json
Adiciona o hook à secção hooks.SessionStart em ~/.claude/settings.json. A partir daqui, cada sessão passa pelo gate.
💡 Dica prática
Cada passo escreve no _install-state.json ANTES de avançar. Se o passo 4 falha, passos 1-3 ficam marcados done e --resume retoma no 4.
🐍 Deteção Python multi-plataforma
Python é o ponto de fricção #1 da instalação. Diferentes OS, diferentes binários, e em Windows o caso da Microsoft Store que parece funcionar mas não.
Estratégia de deteção
detect_python() {
for cmd in python3 python py; do
if command -v "$cmd" >/dev/null 2>&1; then
# Verifica se é Microsoft Store stub (Windows)
local path=$(command -v "$cmd")
if [[ "$path" == *"WindowsApps"* ]]; then
echo "[ERROR] Python from Microsoft Store detected at $path"
echo " Install from python.org instead"
exit 1
fi
# Verifica versão ≥3.9
local version=$("$cmd" -c 'import sys; print(sys.version_info[:2])')
if [[ "$version" >= "(3, 9)" ]]; then
PYTHON_CMD="$cmd"
return 0
fi
fi
done
echo "[ERROR] No Python ≥3.9 found"
exit 1
}
⚠️ Caso Microsoft Store
Em Windows, se correres python sem ter Python instalado, abre a Microsoft Store. Mesmo depois de "instalar" daí, o binário fica em WindowsApps/ como stub limitado. Hooks falham silenciosamente. Solução: instala de python.org e adiciona ao PATH manualmente.
🔁 Idempotência
Idempotente = correr 5 vezes dá o mesmo resultado que correr 1 vez. Cada passo verifica se já está feito antes de fazer.
✓ O que acontece se já está feito
- ✓Fase prereqs →
[SKIP] All prereqs OK - ✓Sinapsis já em ~/.claude →
[SKIP] Sinapsis present - ✓soul.md existe e >100 chars →
[SKIP] - ✓Hook já em settings.json →
[SKIP]
✗ O que NUNCA acontece
- ✗Sobrescrever soul.md com placeholder
- ✗Adicionar hook 2x ao settings.json
- ✗Apagar contexto que já editaste
- ✗Modificar vendor/sinapsis/ local
💡 Sem medo de re-executar
Se algo travou a meio ou tens dúvidas, corre bash scripts/install.sh outra vez. No pior caso, vês uma lista de [SKIP]. Idempotência é uma rede de segurança.
▶️ Modo --resume
Default do /install. Lê o state file, identifica a próxima fase pending ou failed, e executa só essa (e seguintes). Não toca no que já está done.
Cenário real
Imagina que o welcome-quick-win foi a meio (criaste cliente, mas o agente parou para perguntar algo e tu fechaste o terminal). State fica:
{
"phases": {
"prereqs": { "status": "done" },
"sinapsis-engine": { "status": "done" },
"context-files": { "status": "done" },
"operator-state": { "status": "done" },
"welcome-completed": { "status": "in-progress", "pausedBy": "user" },
"deep-dive-completed": { "status": "pending" }
}
}
Próxima sessão, /install --resume retoma do welcome, não do prereqs.
📊 O que --resume respeita
- pausedBy: "user" — retoma exatamente nessa fase, não tenta avançar
- failed — re-tenta a fase falhada, não as anteriores
- in-progress — assume que crashou e retoma com aviso
- skipped — não re-tenta (foi decisão consciente)
💥 Modo --force-reinstall
Arranque limpo. Backup automático + reset do state file + correr install do zero. Requer confirmação explícita do utilizador — não fazes isto por acidente.
O que acontece em sequência
- Pede confirmação:
"Vais perder estado atual. Confirma escrevendo: confirmo-reinstall" - Cria backup em
~/.claude.backup-YYYYMMDD-HHMMSS/ - Apaga
_install-state.json - Mantém
operator-state.jsone_daily-summaries/(Sinapsis preserva memória) - Corre install.sh do passo 1 (sem flag --resume)
⚠️ Quando NÃO usar
Se só uma fase está partida, usa --resume. --force-reinstall é só para casos de corrupção real (state file inválido, conflitos não-recuperáveis). Backup garante reversibilidade, mas é mais trabalho.
💡 Recuperar do backup
Se --force-reinstall deu mau resultado: rm -rf ~/.claude && mv ~/.claude.backup-<timestamp> ~/.claude. Estás de volta ao estado anterior.
📤 Output estruturado [OK]/[SKIP]/[WARN]/[ERROR]
Cada linha do output do install.sh tem um prefixo claro. Scanneias o log e vês imediatamente o que correu mal — sem ler mensagens longas.
[OK]
Operação fez-se com sucesso. Continua para a próxima.
[SKIP]
Já estava feito (idempotência). Nada a fazer.
[WARN]
Algo não-crítico. Instalação continua mas vê depois.
[ERROR]
Bloqueia. Exit code não-zero. Marca fase como failed.
Exemplo de log real
[OK] Phase 1/6: Prereqs validation [OK] Node v20.10.0 found [OK] Python 3.11.4 found at /usr/bin/python3 [SKIP] Phase 2/6: Sinapsis already in ~/.claude [OK] Phase 3/6: OS structure created [WARN] brand-context/voice/ empty — run /deep-dive later [OK] Phase 4/6: soul.md + decisions-log.md created [OK] Phase 5/6: install-gate hook installed [OK] Phase 6/6: settings.json registered [OK] Install complete in 28s
💡 Para CI/CD
O exit code é não-zero em qualquer ERROR. Podes usar isto em scripts: bash scripts/install.sh && echo "ready".
✅ Resumo do Módulo
Próximo Módulo:
2.2 — Install Gate + State Machine + /doctor: hook SessionStart, 6 fases, drift detection.