@fprad0/skill-master-mcp 0.0.12 → 1.0.0

package/docs/planning/MENU_RUNTIME_CORRECTION_PLAN_2026-06-30.md

@@ -0,0 +1,551 @@
+# Menu Runtime Correction Plan - 2026-06-30
+
+Status: planejamento detalhado
+Escopo: `skill-master-menu`, `skill-master-bootstrap-global`, `skill-master-register-clients`, `skill-master-update`, `skill-master-doctor`
+Meta: corrigir erros reais observados no menu em ambiente Windows e melhorar o comportamento operacional para notebooks novos e multiplos clientes MCP.
+
+## Resumo executivo
+
+Os erros reportados nao sao do mesmo tipo. Existem tres problemas principais:
+
+1. `bootstrap-global` e `register-clients` tratam falha do Claude Code como erro fatal do fluxo inteiro, mesmo quando Codex, Claude Desktop, Gemini e Antigravity foram configurados com sucesso.
+2. `skill-master-update` tenta atualizar o pacote global enquanto o proprio pacote esta em uso, o que causa `EBUSY` no Windows. Alem disso, o launcher atual usa `shell: true` e gera aviso de deprecacao.
+3. `doctor` informa corretamente o problema do Claude Code, mas as recomendacoes ainda sao pouco contextuais e repetem comandos que ja falharam, sem classificar melhor o motivo da falha.
+
+O plano abaixo separa correcao funcional, contrato operacional, UX de terminal e validacao para evitar regressao.
+
+## Principios de decisao
+
+- O menu deve ser confiavel para humanos: uma acao parcial nao pode parecer falha total quando a maior parte do trabalho funcionou.
+- O MCP nao deve tentar atualizar a propria pasta global enquanto seu processo ainda esta rodando a partir dela.
+- Claude Code deve ser tratado como cliente suportado, mas operacionalmente opcional quando os outros clientes foram aplicados com sucesso.
+- Todo fluxo mutante precisa emitir diagnostico suficiente para uma pessoa entender se faltou PATH, CLI, permissao, arquivo bloqueado ou restart.
+- A correcao deve manter `--run`, `--status`, `--help`, `doctor` e instalacao global via npm funcionando sem depender de TTY.
+
+## Contrato operacional proposto
+
+### Classes de resultado
+
+| Classe | Exit code | Uso | Render do menu |
+| --- | ---: | --- | --- |
+| sucesso | `0` | tudo aplicado ou nada precisava mudar | `RESULT-OK` |
+| aviso | `10` | acao principal aplicada, mas ha cliente opcional ou etapa secundaria pendente | `RESULT-WARN` |
+| erro de usuario/ambiente | `20` | prerequisito ausente, pacote em uso, CLI indisponivel, auth ausente | `RESULT-ERROR` com proximo passo |
+| erro fatal | `30` | falha de escrita, JSON irrecuperavel sem `--force`, comando obrigatorio falhou | `RESULT-ERROR` com bloqueio |
+
+### Contrato de saida textual
+
+Cada subcomando operacional deve imprimir um resumo previsivel:
+
+```text
+[skill_master] Summary
+- Result: ok|warning|error
+- Applied: N
+- Warnings: N
+- Failed: N
+- Next: comando ou acao humana
+```
+
+O menu pode continuar lendo apenas exit code nesta versao. A saida padronizada prepara uma etapa futura com `--json` sem exigir refatoracao grande agora.
+
+### Criterio para `warning`
+
+Um fluxo retorna `10` quando:
+
+- pelo menos uma acao principal foi aplicada com sucesso;
+- a falha restante e recuperavel;
+- a falha restante nao corrompe configuracao;
+- a mensagem mostra o proximo passo exato.
+
+Exemplo: Codex, Claude Desktop, Gemini e Antigravity foram registrados, mas Claude Code falhou por CLI ausente ou sem saida.
+
+## Matriz de severidade
+
+| Caso | Severidade | Resultado esperado |
+| --- | --- | --- |
+| Claude Code CLI ausente e demais clientes ok | aviso | `RESULT-WARN`, proximo passo manual |
+| `claude mcp add` retorna sem saida e demais clientes ok | aviso | `RESULT-WARN`, diagnostico classificado |
+| Codex config nao pode ser escrita | fatal | `RESULT-ERROR`, apontar arquivo |
+| Claude Desktop JSON invalido sem `--force` | fatal | `RESULT-ERROR`, recomendar `--force` se seguro |
+| `npm install -g` detecta pacote em uso | erro de ambiente | `RESULT-ERROR`, orientar update fora do menu ou agendamento |
+| Doctor encontra somente Claude Code pendente | aviso em readiness | proxima acao especifica para Claude Code |
+| Doctor encontra skills globais faltando | erro de ambiente | recomendar install-global-skills |
+
+## Ordem tecnica recomendada
+
+1. Criar helpers puros e testaveis para classificar resultados de clientes e updates.
+2. Ajustar `register-clients` para produzir resultado por cliente.
+3. Ajustar `bootstrap-global` para propagar aviso sem tratar como falha total.
+4. Ajustar `menu-core` para renderizar `RESULT-WARN`.
+5. Ajustar `update` para evitar `shell: true` e detectar execucao dentro do proprio pacote.
+6. Ajustar `doctor` para recomendacoes contextuais.
+7. Rodar testes focados e `npm run check`.
+
+## Erro 1 - Bootstrap global falha por causa do Claude Code
+
+### Sintoma observado
+
+- `install-global-skills` conclui com sucesso.
+- `register-clients` registra Codex, Claude Desktop, Gemini e Antigravity.
+- Claude Code falha com:
+  `Claude Code registration failed (unknown): no output`
+- O fluxo inteiro termina com `RESULT-ERROR`.
+
+### Causa raiz provavel
+
+- Arquivo principal: [bin/skill-master-register-clients.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-register-clients.mjs>)
+- O registrador usa `spawnSync(claudeCodeCommand, claudeCodeArgs)` e, se o status nao for `0`, seta `process.exitCode = 1`.
+- O bootstrap chama o registrador com `--apply-all --force` e trata qualquer codigo diferente de `0` como falha total do bootstrap.
+- Isso mistura:
+  - erro critico do fluxo inteiro;
+  - falha parcial de um cliente opcional;
+  - ausencia do CLI do Claude Code;
+  - falha de execucao sem diagnostico.
+
+### Correcao planejada
+
+1. Transformar `register-clients` em fluxo com resultado estruturado por cliente.
+2. Diferenciar estados:
+   - `ok`
+   - `already-configured`
+   - `skipped-optional`
+   - `partial-warning`
+   - `fatal`
+3. No modo `--apply-all`, nao retornar erro fatal se somente Claude Code falhar e os demais clientes forem aplicados com sucesso.
+4. Retornar erro fatal somente quando:
+   - o servidor MCP nao puder ser resolvido;
+   - escrita de arquivo de cliente obrigatorio falhar;
+   - todos os clientes selecionados falharem.
+
+### Melhoria de UX planejada
+
+1. Mostrar no menu um resultado do tipo `RESULT-WARN` quando houver sucesso parcial.
+2. Exibir resumo por cliente:
+   - `Codex: ok`
+   - `Claude Desktop: ok`
+   - `Claude Code: warn`
+   - `Gemini: ok`
+   - `Antigravity: ok`
+3. Na volta ao menu, manter a operacao como concluida com aviso, nao como erro total.
+
+### Validacao
+
+- `skill-master-menu --run bootstrap-global --yes` deve terminar como sucesso parcial quando apenas Claude Code falhar.
+- `skill-master-register-clients --apply-all --force` deve retornar `0` se ao menos os clientes nao opcionais forem aplicados corretamente.
+- Testes novos devem cobrir:
+  - sucesso total;
+  - falha parcial no Claude Code;
+  - falha fatal de escrita de arquivo.
+
+## Erro 2 - Registro do Claude Code falha com "unknown: no output"
+
+### Sintoma observado
+
+- O menu informa:
+  `Claude Code registration failed (unknown): no output`
+- O `doctor` mostra:
+  `mode=list-failed command=nao encontrado em claude mcp list`
+
+### Causa raiz provavel
+
+- Arquivos principais:
+  - [bin/skill-master-register-clients.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-register-clients.mjs>)
+  - [bin/skill-master-doctor.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-doctor.mjs>)
+  - [bin/lib/client-config.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/lib/client-config.mjs>)
+- O fluxo atual assume que `claude` esta acessivel pelo nome simples.
+- No Windows, pode existir um destes cenarios:
+  - `claude` nao esta no PATH do processo;
+  - o executavel real e `claude.cmd`;
+  - o `claude mcp add` abre um processo com comportamento diferente e retorna sem stdout/stderr;
+  - `claude mcp list` falha sem diagnostico util.
+
+### Correcao planejada
+
+1. Criar resolucao robusta do comando do Claude Code:
+   - tentar `claude`
+   - tentar `claude.cmd` no Windows
+   - tentar caminho absoluto detectado por `where`
+2. Capturar melhor o resultado do processo:
+   - `status`
+   - `signal`
+   - `error.code`
+   - `error.message`
+   - stdout
+   - stderr
+3. Se o CLI existir, validar primeiro:
+   - `claude --version`
+   - `claude mcp list`
+4. Se `claude mcp add` falhar, imprimir diagnostico classificado:
+   - `cli-missing`
+   - `cli-not-runnable`
+   - `mcp-subcommand-missing`
+   - `registration-failed`
+5. Gerar comando manual recomendado com quoting correto para Windows.
+
+### Melhoria de UX planejada
+
+1. Alterar a mensagem do menu de:
+   `failed (unknown): no output`
+   para algo como:
+   `Claude Code: CLI encontrado, mas 'claude mcp add' falhou sem saida. Tente abrir o Claude Code e executar o comando manual abaixo.`
+2. Exibir o comando manual pronto no painel de detalhes quando a acao selecionada for `register-clients`.
+3. Adicionar uma acao de menu futura:
+   `Diagnosticar Claude Code`
+
+### Validacao
+
+- Teste unitario para resolucao de `claude.cmd` no Windows.
+- Teste para classificacao de falha com `status`, `signal` e `error`.
+- Smoke manual em Windows com:
+  - CLI ausente
+  - CLI presente
+  - `mcp list` sem `skill_master`
+  - `mcp add` bem-sucedido
+
+## Erro 3 - Atualizacao global falha com `EBUSY`
+
+### Sintoma observado
+
+- `skill-master-update` roda:
+  `npm install -g @fprad0/skill-master-mcp@latest`
+- No Windows, npm tenta renomear a pasta ativa do pacote.
+- O processo falha com:
+  `EBUSY: resource busy or locked`
+
+### Causa raiz provavel
+
+- Arquivo principal: [bin/skill-master-update.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-update.mjs>)
+- O comando de update esta sendo executado a partir do proprio pacote global em uso.
+- O pacote em execucao segura locks ou referencias em `node_modules/@fprad0/skill-master-mcp`.
+- O update usa `shell: true` no Windows, gerando tambem `DEP0190`.
+
+### Correcao planejada
+
+1. Remover `shell: true` do fluxo de update.
+2. Resolver o executavel npm de forma robusta:
+   - `npm.cmd` no Windows
+   - `npm` no Linux/macOS
+   - ou `process.execPath` + `npm-cli.js` quando necessario
+3. Mudar a estrategia de auto-update:
+   - o menu nao deve tentar substituir o pacote enquanto ele ainda esta rodando do mesmo path;
+   - em vez disso, deve gerar um handoff seguro.
+4. Implementar um destes caminhos:
+   - `A.` modo recomendado: imprimir comando e instruir a sair do menu antes de atualizar;
+   - `B.` modo melhor: spawn detached de um script temporario fora do diretorio do pacote, que espera o processo atual encerrar e so entao roda o npm install global.
+
+### Melhoria de UX planejada
+
+1. Trocar o texto atual de:
+   `Roda npm install -g fora do processo MCP stdio.`
+   para algo mais preciso:
+   `A atualizacao exige que o processo atual seja encerrado antes da troca do pacote.`
+2. Se o update for disparado de dentro do menu:
+   - mostrar `RESULT-WARN`
+   - exibir comando pronto
+   - oferecer opcao futura de `agendar atualizacao ao sair`
+3. Se ocorrer `EBUSY`, traduzir para mensagem humana:
+   `O pacote esta em uso neste momento. Feche o menu e rode o update fora desta execucao.`
+
+### Validacao
+
+- Sem `DEP0190` no Windows.
+- Update nao deve mais tentar atualizar o pacote em uso sem aviso.
+- Smoke manual:
+  - update disparado fora do menu
+  - update disparado no menu
+  - dry-run
+
+## Erro 4 - Doctor recomenda comandos pouco contextuais
+
+### Sintoma observado
+
+- O `doctor` detecta corretamente que Claude Code nao esta pronto.
+- Ainda assim recomenda:
+  - `skill-master-register-clients --apply-all --force`
+  - `skill-master-register-clients --apply-claude-code --claude-code-scope user`
+  - `skill-master-menu --run bootstrap-global --yes`
+- Isso mistura remedios amplos com remedio especifico.
+
+### Causa raiz provavel
+
+- Arquivo principal: [bin/skill-master-doctor.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-doctor.mjs>)
+- As recomendacoes sao estaticas e nao derivam do tipo exato de falha.
+
+### Correcao planejada
+
+1. Tornar o `doctor` orientado por diagnostico:
+   - se somente Claude Code falhar, recomendar apenas comando do Claude Code
+   - se skills globais faltarem, recomendar `install-global-skills`
+   - se Codex estiver ausente, recomendar `register-clients --apply-codex`
+2. Classificar `Readiness global` em:
+   - `ready`
+   - `partial`
+   - `blocked`
+3. Mostrar motivo dominante.
+
+### Melhoria de UX planejada
+
+1. Exibir um bloco:
+   `Falha dominante: Claude Code nao registrado`
+2. Mostrar uma unica proxima acao recomendada, seguida de acoes alternativas.
+3. No menu, refletir isso no painel `DETAIL FOCUS`.
+
+### Validacao
+
+- `doctor` com apenas Claude Code faltando nao deve recomendar bootstrap completo como primeira opcao.
+- Testes para matriz de recomendacoes por tipo de falha.
+
+## Erro 5 - Resultado do menu nao diferencia erro fatal de warning parcial
+
+### Sintoma observado
+
+- Tanto no bootstrap quanto no registro de clientes, o menu exibe `RESULT-ERROR`.
+- Isso passa a impressao de falha total, embora a maior parte da operacao tenha funcionado.
+
+### Causa raiz provavel
+
+- O menu trabalha hoje principalmente com `code === 0` ou `code !== 0`.
+- Falta um contrato mais rico entre subcomandos e o renderer do menu.
+
+### Correcao planejada
+
+1. Definir um contrato de saida para subcomandos operacionais:
+   - `0`: sucesso
+   - `10`: sucesso parcial / warning
+   - `20+`: erro fatal
+2. Ensinar o menu a renderizar:
+   - `RESULT-OK`
+   - `RESULT-WARN`
+   - `RESULT-ERROR`
+3. Opcionalmente, permitir `--json` nos subcomandos para leitura estruturada pelo menu no futuro.
+
+### Melhoria de UX planejada
+
+1. Mostrar contagem:
+   `4 clientes ok | 1 cliente com aviso`
+2. Mostrar um proximo passo exato no proprio resultado.
+3. Manter a tecla de retorno ao menu, mas com resumo objetivo do que ainda falta.
+
+### Validacao
+
+- Bootstrap com Claude Code falhando deve renderizar `RESULT-WARN`.
+- Update com `EBUSY` deve renderizar `RESULT-ERROR` com traducao humana.
+
+## Plano de implementacao recomendado
+
+### Fase 0 - Preparar testes e contratos
+
+Objetivo: criar uma rede minima de seguranca antes de mexer em fluxo global.
+
+Tarefas:
+
+1. Criar helper de resultado operacional, preferencialmente em `bin/lib/operation-result.mjs`.
+2. Modelar estados: `ok`, `warning`, `error`, `fatal`.
+3. Criar testes unitarios para mapear estado em exit code e titulo de resultado.
+4. Atualizar `formatResultMessage` para aceitar `0`, `10`, `20` e `30+`.
+
+Aceite:
+
+- `formatResultMessage(10)` renderiza `RESULT-WARN`.
+- `formatResultMessage(0)` continua renderizando `RESULT-OK`.
+- `formatResultMessage(1)` continua renderizando `RESULT-ERROR` para compatibilidade.
+
+### Fase 1 - Corrigir `register-clients`
+
+Objetivo: parar de transformar falha parcial do Claude Code em erro total.
+
+Arquivos:
+
+- [bin/skill-master-register-clients.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-register-clients.mjs>)
+- [bin/lib/client-config.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/lib/client-config.mjs>)
+- [src/client-config.test.ts](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/src/client-config.test.ts>)
+
+Tarefas:
+
+1. Criar `resolveClaudeCodeCommand()` com suporte a `claude`, `claude.cmd` e caminho absoluto encontrado por `where` no Windows.
+2. Criar `classifyClaudeCodeResult()` para converter `status`, `signal`, `error`, stdout e stderr em diagnostico legivel.
+3. Trocar `actions.push(string)` por `results.push({ client, status, message, next })`.
+4. Quando somente Claude Code falhar em `--apply-all`, retornar `10`.
+5. Quando o usuario chamar apenas `--apply-claude-code` e ele falhar, retornar `20`.
+
+Aceite:
+
+- `skill-master-register-clients --apply-all --force` termina em warning se apenas Claude Code falhar.
+- `skill-master-register-clients --apply-claude-code` termina em erro se Claude Code falhar.
+- A saida nunca mais deve dizer `failed (unknown): no output` sem contexto.
+
+### Fase 2 - Corrigir `bootstrap-global`
+
+Objetivo: refletir corretamente sucesso parcial do fluxo completo.
+
+Arquivos:
+
+- [bin/skill-master-bootstrap-global.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-bootstrap-global.mjs>)
+
+Tarefas:
+
+1. Rodar `install-global-skills`.
+2. Rodar `register-clients --apply-all --force`.
+3. Se install falhar, retornar erro fatal.
+4. Se register retornar `10`, imprimir `Global bootstrap complete with warnings` e retornar `10`.
+5. Se register retornar `0`, imprimir `Global bootstrap complete` e retornar `0`.
+
+Aceite:
+
+- O caso reportado pelo usuario deve virar `RESULT-WARN`, nao `RESULT-ERROR`.
+- O log deve mostrar claramente que skills globais foram instaladas e que apenas Claude Code ficou pendente.
+
+### Fase 3 - Corrigir `skill-master-update`
+
+Objetivo: acabar com `DEP0190` e tratar `EBUSY` como estado operacional previsivel.
+
+Arquivos:
+
+- [bin/skill-master-update.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-update.mjs>)
+- novo teste sugerido: `src/update-cli.test.ts`
+
+Tarefas:
+
+1. Criar `resolveNpmExecutable()`:
+   - Windows: preferir `npm.cmd`;
+   - Linux/macOS: `npm`;
+   - fallback: `process.execPath` + `npm-cli.js` quando detectavel.
+2. Remover `shell: true`.
+3. Detectar quando `process.argv[1]` esta dentro de `node_modules/@fprad0/skill-master-mcp`.
+4. Se estiver rodando de dentro do pacote global e for Windows, nao executar update direto por padrao.
+5. Imprimir comando seguro para rodar fora do menu:
+   `npm install -g @fprad0/skill-master-mcp@latest --registry=https://registry.npmjs.org`
+6. Adicionar opcao futura ou imediata `--force-direct` para permitir comportamento antigo em ambiente controlado.
+
+Aceite:
+
+- `skill-master-update --dry-run` continua imprimindo o comando.
+- Executar pelo menu no Windows nao tenta renomear o pacote em uso.
+- Nao aparece mais `DEP0190`.
+- Erro `EBUSY` recebe mensagem humana se ainda ocorrer em uso externo.
+
+### Fase 4 - Corrigir `doctor`
+
+Objetivo: transformar o doctor em orientador contextual.
+
+Arquivos:
+
+- [bin/skill-master-doctor.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-doctor.mjs>)
+
+Tarefas:
+
+1. Criar `diagnoseReadiness(clients, skills, bins, packageState)`.
+2. Criar `recommendedActionsForDiagnosis(diagnosis)`.
+3. Quando apenas Claude Code falhar, recomendar primeiro:
+   `skill-master-register-clients --apply-claude-code --claude-code-scope user`
+4. Quando o CLI do Claude Code nao for encontrado, recomendar:
+   instalar/abrir Claude Code ou pular se nao usar esse cliente.
+5. Manter `--strict` retornando erro quando readiness nao for total.
+
+Aceite:
+
+- Doctor nao recomenda bootstrap completo como primeira acao quando apenas Claude Code falhou.
+- Doctor mostra `Falha dominante`.
+- Doctor diferencia `partial` de `blocked`.
+
+### Fase 5 - Melhorar UX do menu
+
+Objetivo: mostrar resultado correto e proximo passo dentro do menu.
+
+Arquivos:
+
+- [bin/lib/menu-core.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/lib/menu-core.mjs>)
+- [bin/skill-master-menu.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-menu.mjs>)
+- [src/menu-core.test.ts](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/src/menu-core.test.ts>)
+
+Tarefas:
+
+1. Renderizar `RESULT-WARN` com cor amber.
+2. Mensagem:
+   `Comando concluido com avisos.`
+3. Explicar:
+   `workflow liberado, mas existe uma acao recomendada`
+4. Preservar comportamento atual para `RESULT-OK` e `RESULT-ERROR`.
+5. No painel de detalhe de `updateGlobal`, informar que update dentro do menu exige handoff.
+
+Aceite:
+
+- `formatResultMessage(10)` passa no teste.
+- O usuario nao confunde sucesso parcial com falha total.
+
+## Matriz de tarefas por arquivo
+
+| Arquivo | Mudanca | Teste minimo |
+| --- | --- | --- |
+| `bin/skill-master-register-clients.mjs` | status por cliente e warning parcial | mock de Claude Code falhando |
+| `bin/lib/client-config.mjs` | resolver CLI do Claude Code e formatar comando | teste Windows `claude.cmd` |
+| `bin/skill-master-bootstrap-global.mjs` | aceitar warning parcial | teste de spawn com code `10` |
+| `bin/skill-master-update.mjs` | remover `shell: true`, detectar pacote em uso | `--dry-run`, resolver npm |
+| `bin/skill-master-doctor.mjs` | diagnostico dominante e recomendacao contextual | doctor com apenas Claude Code pendente |
+| `bin/lib/menu-core.mjs` | `RESULT-WARN` | `formatResultMessage(10)` |
+| `scripts/verify-menu-actions.mjs` | confirmar que novas acoes continuam protegidas | `npm run verify:menu` |
+
+## Plano de testes
+
+### Testes unitarios
+
+- `src/client-config.test.ts`
+- `src/menu-core.test.ts`
+- novo `src/register-clients.test.ts`
+- novo `src/update-cli.test.ts`
+- novo `src/doctor-diagnosis.test.ts`
+
+### Testes de integracao locais
+
+```bash
+npm run check
+node bin/skill-master-menu.mjs --run doctor
+node bin/skill-master-register-clients.mjs --write-snippets --snippets-dir .tmp-client-snippets
+node bin/skill-master-update.mjs --dry-run
+node scripts/verify-menu-actions.mjs
+```
+
+### Smoke Windows recomendado
+
+```powershell
+skill-master-menu --run doctor
+skill-master-register-clients --apply-all --force
+skill-master-menu --run bootstrap-global --yes
+skill-master-update --dry-run
+```
+
+Se Claude Code continuar falhando:
+
+```powershell
+claude --version
+claude mcp list
+skill-master-register-clients --apply-claude-code --claude-code-scope user
+```
+
+## Stop rules
+
+- Nao publicar pacote npm sem autorizacao explicita.
+- Nao apagar configs existentes de Codex, Claude, Gemini ou Antigravity.
+- Nao sobrescrever JSON invalido sem backup.
+- Nao executar update global destrutivo enquanto o pacote estiver em uso.
+- Nao tratar Claude Code como pronto sem `claude mcp list` confirmando `skill_master`.
+
+## Arquivos que devem ser alterados
+
+- [bin/skill-master-register-clients.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-register-clients.mjs>)
+- [bin/skill-master-bootstrap-global.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-bootstrap-global.mjs>)
+- [bin/skill-master-update.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-update.mjs>)
+- [bin/skill-master-doctor.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/skill-master-doctor.mjs>)
+- [bin/lib/menu-core.mjs](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/bin/lib/menu-core.mjs>)
+- [src/client-config.test.ts](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/src/client-config.test.ts>)
+- [src/menu-core.test.ts](</home/dev/Área de trabalho/VSCODE/skill-master-mcp/src/menu-core.test.ts>)
+- novos testes para update/bootstrap/doctor
+
+## Criterios de aceite
+
+- `bootstrap-global` nao falha totalmente quando apenas Claude Code apresentar problema opcional.
+- `register-clients` classifica corretamente erro, skip e warning.
+- `update` nao gera `DEP0190` e nao falha por `EBUSY` sem mensagem humana e estrategia segura.
+- `doctor` recomenda a proxima acao correta para o problema dominante.
+- O menu diferencia `OK`, `WARN` e `ERROR`.
+- `npm run check` passa.