⚙️ Instalação

1) Valida prereqs · 2) Instala Sinapsis em ~/.claude · 3) Cria estrutura OS · 4) Cria soul.md/decisions-log · 5) Instala install-gate hook · 6) Regista em settings.json.

Para perceberes o que cada passo faz e debug rapidamente se algo trava num deles.

Sequência determinística · ~30 segundos total · cada passo escreve no state file antes de avançar.

Script tenta python3, python, py -3 consoante OS. Em Windows deteta se executável veio da Microsoft Store (path com WindowsApps) e bloqueia.

Para resolveres em segundos o erro mais comum: "Python from Microsoft Store detected — install from python.org".

PATH detection · WindowsApps stub · WSL como alternativa · validação versão ≥3.9.

Cada passo verifica se já está feito antes de fazer. Reentrante: podes correr install.sh 5x e o resultado é o mesmo da primeira vez.

Para não teres medo de re-executar. Falhou a meio? Corre outra vez. Não duplica nada nem sobrescreve dados.

Check before write · [SKIP] em vez de duplicar · sem efeitos colaterais.

Default do /install. Lê o state file, identifica próxima fase pendente, executa só essa (e seguintes). Não toca no que já está done.

Quando uma fase falha (ex: deep-dive interrompido), /install --resume retoma sem reiniciar tudo.

State-driven · resume from checkpoint · respeita pausedBy.

Faz backup automático em ~/.claude.backup-<timestamp>, reinicia state file, e corre install do zero. Requer confirmação explícita.

Para casos de corrupção ou quando queres começar do zero limpo sem perder dados anteriores.

Backup automático · confirmação obrigatória · destrutivo mas reversível.

Cada linha do output tem prefixo: [OK] sucesso · [SKIP] já feito · [WARN] não-crítico · [ERROR] bloqueia.

Para scanneares o output e veres rapidamente onde algo correu mal. Erros nunca se confundem com avisos.

UNIX-friendly logs · cor opcional · timestamp por linha · exit code não-zero em ERROR.

JSON em ~/.claude/skills/_install-state.json com 6 fases: prereqs, sinapsis-engine, context-files, operator-state, welcome-completed, deep-dive-completed. Cada uma: done/failed/pending/in-progress/skipped.

É a fonte da verdade. Tudo o que vês em /install-status, /doctor e o gate vem daqui.

5 fases required + 1 deferrable · timestamp por transição · pausedBy: "user".

Script bash+node em ~/.claude/skills/_install-gate.sh. Corre antes de cada sessão começar. Lê state, se há fases required pendentes, injeta aviso ao modelo.

É a peça que impede "o Claude inventou que instalou". Enforcement estrutural, não confia no modelo.

SessionStart hook · fail-open (se script crashar, sessão continua) · zero dependências externas.

O hook devolve JSON {additionalContext: "..."} que o Claude Code injeta no contexto da sessão. O modelo lê isso antes de qualquer mensagem tua.

Para entenderes porque o agente diz "instala primeiro" mesmo quando não pediste nada de instalação.

SystemContext-like · prioridade sobre user message · API oficial do Claude Code.

/install lê state, identifica próxima fase, executa (ou pede para correres bash). /install-status é read-only — mostra dashboard sem tocar em nada.

Para destrancar instalações a meio. /install --resume retoma onde ficou, --force-reinstall reinicia (com confirmação).

Reentrante · fases técnicas (terminal) vs conversacionais (Claude Code).

Skill health-check (invocada por /doctor) faz validação real: JSON parseable, hooks executáveis, conteúdo >100 chars em ficheiros críticos. Não só test -f.

Para diagnosticares falhas subtis. Um ficheiro pode existir mas estar vazio ou corrompido — validação profunda apanha.

🟢🟡🔴 report · auto-fix com confirmação · cruzamento com state machine.

O /doctor cruza state file com disco. Se state diz "context-files: done" mas context/me.md está vazio, é drift. Reporta e propõe fix.

Quando algo falha sem deres conta — apagaste um ficheiro, sync entre máquinas correu mal — drift detection apanha.

State vs reality · auto-revert (state → pending) · sugestão de comando para corrigir.