@fprad0/skill-master-mcp 0.0.10 → 0.0.12

package/bin/skill-master-menu.mjs

@@ -7,10 +7,12 @@ import { fileURLToPath } from 'node:url';
 import {
   buildMenuCommands,
   formatActionHeader,
+  formatCyberConfirmFrame,
   formatCyberMenuFrame,
   formatHelp,
   formatRunningActionFrame,
   formatResultMessage,
+  formatSkillMasterIntroFrame,
   formatStatusReport,
   getMenuStatus,
   isInteractiveTerminal,
@@ -20,7 +22,8 @@ import {
 
 const currentFile = fileURLToPath(import.meta.url);
 const rootDir = dirname(dirname(currentFile));
-const commands = buildMenuCommands({ rootDir, currentFile });
+const invocationCwd = process.cwd();
+const commands = buildMenuCommands({ rootDir, currentFile, invocationCwd });
 readline.emitKeypressEvents(process.stdin);
 const CONTROL = {
   alternateScreenIn: '\x1b[?1049h',
@@ -100,7 +103,7 @@ async function runSelectedAction(action, { yes = false, useColor = false } = {})
   console.log('');
   console.log(formatActionHeader(action, { useColor }));
   console.log('');
-  const code = await runCommand(action, { cwd: rootDir });
+  const code = await runCommand(action, { cwd: action.cwd ?? rootDir });
   console.log('');
   console.log(formatResultMessage(code, { useColor }));
   return { cancelled: false, code };
@@ -183,6 +186,13 @@ function writeStableFrame(frame, { clear = false } = {}) {
   ].join(''));
 }
 
+function visualHudAllowed() {
+  return isInteractiveTerminal()
+    && process.env.SKILL_MASTER_NO_VISUAL !== '1'
+    && process.env.CI !== 'true'
+    && process.env.TERM !== 'dumb';
+}
+
 function renderCyberMenu(selectedIndex, tick, { clear = false } = {}) {
   const status = getMenuStatus(rootDir);
   const frame = formatCyberMenuFrame(status, commands, selectedIndex, tick, {
@@ -203,8 +213,65 @@ function renderRunningAction(action, tick) {
   writeStableFrame(frame, { clear: true });
 }
 
+function renderIntro(tick, message) {
+  const status = getMenuStatus(rootDir);
+  const frame = formatSkillMasterIntroFrame(status, tick, {
+    columns: process.stdout.columns ?? 120,
+    rows: process.stdout.rows ?? 32,
+    useColor: true,
+    message,
+  });
+  writeStableFrame(frame, { clear: tick === 0 });
+}
+
+function renderConfirmAction(action, tick) {
+  const status = getMenuStatus(rootDir);
+  const frame = formatCyberConfirmFrame(status, action, tick, {
+    columns: process.stdout.columns ?? 120,
+    rows: process.stdout.rows ?? 32,
+    useColor: true,
+  });
+  writeStableFrame(frame, { clear: tick === 0 });
+}
+
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
+async function animateIntro(message = 'skill_master assumindo o workflow', frames = 6) {
+  for (let frame = 0; frame < frames; frame += 1) {
+    renderIntro(frame, message);
+    await sleep(70);
+  }
+}
+
+async function animateRunningAction(action, startTick) {
+  for (let frame = 0; frame < 5; frame += 1) {
+    renderRunningAction(action, startTick + frame);
+    await sleep(90);
+  }
+}
+
+async function confirmVisualAction(action, startTick) {
+  let tick = startTick;
+  const reader = createKeyReader();
+
+  try {
+    while (true) {
+      renderConfirmAction(action, tick);
+      const key = await reader.read(180);
+      if (!key) {
+        tick += 1;
+        continue;
+      }
+
+      if (key.ctrl && key.name === 'c') return { confirmed: false, code: 130 };
+      if (key.name === 'return' || key.name === 'enter' || key.name === 'y') return { confirmed: true, code: 0 };
+      if (key.name === 'escape' || key.name === 'q' || key.name === 'n') return { confirmed: false, code: 0 };
+    }
+  } finally {
+    reader.close();
+  }
+}
+
 async function waitForAnyKey(message = 'Pressione qualquer tecla para voltar ao menu...') {
   process.stdout.write(`\n${message}`);
   setRawInput(true);
@@ -225,6 +292,8 @@ async function runVisualMenu() {
   restoreMenuInput();
 
   try {
+    await animateIntro('skill_master online / carregando menu operacional', 7);
+
     while (true) {
       const columns = process.stdout.columns ?? 120;
       const rows = process.stdout.rows ?? 32;
@@ -233,7 +302,7 @@ async function runVisualMenu() {
       previousRows = rows;
       renderCyberMenu(selectedIndex, tick, { clear: needsClear || resized });
       needsClear = false;
-      const key = await keyReader.read(240);
+      const key = await keyReader.read(160);
 
       if (!key) {
         tick += 1;
@@ -253,12 +322,20 @@ async function runVisualMenu() {
       if (key.name === 'return' || key.name === 'enter') {
         const action = commands[selectedIndex];
         keyReader.close();
-        renderRunningAction(action, tick);
-        await sleep(180);
+        if (action.confirmMessage) {
+          const confirmation = await confirmVisualAction(action, tick);
+          if (confirmation.code === 130) return 130;
+          if (!confirmation.confirmed) {
+            keyReader = createKeyReader();
+            needsClear = true;
+            continue;
+          }
+        }
+        await animateRunningAction(action, tick);
         setRawInput(false);
         leaveVisualScreen();
         try {
-          const result = await runSelectedAction(action, { useColor: true });
+          const result = await runSelectedAction(action, { yes: Boolean(action.confirmMessage), useColor: true });
           lastCode = result.code;
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
@@ -300,6 +377,14 @@ async function main() {
     }
 
     const action = commands.find((entry) => entry.key === actionKey);
+    if (visualHudAllowed()) {
+      enterVisualScreen();
+      try {
+        await animateIntro(`skill_master executando ${action.label}`, 6);
+      } finally {
+        leaveVisualScreen();
+      }
+    }
     const result = await runSelectedAction(action, { yes: args.yes, useColor: isInteractiveTerminal() });
     return result.code;
   }

package/bin/skill-master-register-clients.mjs

@@ -1,7 +1,20 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
+import path, { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  appendCodexServer,
+  buildClaudeCodeAddArgs,
+  buildCodexBlock,
+  buildJsonMcpSnippet,
+  buildSkillMasterServerConfig,
+  defaultClientConfigPaths,
+  formatShellCommand,
+  mergeMcpServer,
+  writeJson,
+} from './lib/client-config.mjs';
 
 const args = process.argv.slice(2);
 const has = (flag) => args.includes(flag);
@@ -10,6 +23,9 @@ const readValue = (flag, fallback) => {
   return index >= 0 ? args[index + 1] : fallback;
 };
 
+const here = dirname(fileURLToPath(import.meta.url));
+const rootDir = dirname(here);
+
 if (has('--help')) {
   console.log(`Skill Master client registration
 
@@ -17,136 +33,87 @@ Uso:
   skill-master-register-clients --write-snippets
   skill-master-register-clients --apply-codex
   skill-master-register-clients --apply-claude
+  skill-master-register-clients --apply-claude-code
   skill-master-register-clients --apply-gemini
   skill-master-register-clients --apply-antigravity
   skill-master-register-clients --apply-all
   skill-master-register-clients --apply-codex --force
+  skill-master-register-clients --apply-claude-code --claude-code-scope user
+
+Registra o servidor MCP skill_master como stdio usando Node absoluto e o
+entrypoint absoluto do pacote. Isso evita falhas de PATH em Windows, Linux,
+macOS e apps desktop que nao herdam o terminal.
 
-Registra o servidor MCP skill_master como stdio usando o binario global:
-  skill-master-mcp
+Para Claude Code, o registrador usa o CLI oficial: claude mcp add.
 `);
   process.exit(0);
 }
 
-const home = os.homedir();
-const snippetsDir = readValue('--snippets-dir', path.join(home, '.skill-master', 'client-configs'));
-const codexConfig = readValue('--codex-config', path.join(process.env.CODEX_HOME ?? path.join(home, '.codex'), 'config.toml'));
-const defaultClaudeConfig = () => {
-  if (process.platform === 'win32') {
-    return path.join(process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
-  }
-  if (process.platform === 'darwin') {
-    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
-  }
-  return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
-};
-const claudeConfig = readValue('--claude-config', defaultClaudeConfig());
-const geminiConfig = readValue('--gemini-config', path.join(home, '.gemini', 'settings.json'));
-const antigravityConfig = readValue('--antigravity-config', path.join(home, '.gemini', 'config', 'mcp_config.json'));
+const clientPaths = defaultClientConfigPaths();
+const snippetsDir = readValue('--snippets-dir', path.join(process.env.SKILL_MASTER_HOME ?? path.join(os.homedir(), '.skill-master'), 'client-configs'));
+const codexConfig = readValue('--codex-config', clientPaths.codex);
+const claudeConfig = readValue('--claude-config', clientPaths.claude);
+const geminiConfig = readValue('--gemini-config', clientPaths.gemini);
+const antigravityConfig = readValue('--antigravity-config', clientPaths.antigravity);
+const claudeCodeScope = readValue('--claude-code-scope', 'user');
+const claudeCodeCommand = readValue('--claude-code-command', 'claude');
 
 const applyAll = has('--apply-all');
 const applyCodex = applyAll || has('--apply-codex');
 const applyClaude = applyAll || has('--apply-claude');
+const applyClaudeCode = applyAll || has('--apply-claude-code');
 const applyGemini = applyAll || has('--apply-gemini');
 const applyAntigravity = applyAll || has('--apply-antigravity');
-const writeSnippets = applyAll || has('--write-snippets') || !(applyCodex || applyClaude || applyGemini || applyAntigravity);
+const writeSnippets = applyAll || has('--write-snippets') || !(applyCodex || applyClaude || applyClaudeCode || applyGemini || applyAntigravity);
 const force = has('--force');
+const serverConfig = buildSkillMasterServerConfig({ rootDir });
+const codexBlock = buildCodexBlock(serverConfig);
+const jsonSnippet = buildJsonMcpSnippet(serverConfig);
+const claudeCodeArgs = buildClaudeCodeAddArgs(serverConfig, { scope: claudeCodeScope });
+
+function commandExists(command) {
+  const lookup = process.platform === 'win32' ? 'where' : 'command';
+  const lookupArgs = process.platform === 'win32' ? [command] : ['-v', command];
+  const result = spawnSync(lookup, lookupArgs, { shell: process.platform !== 'win32', stdio: 'ignore' });
+  return result.status === 0;
+}
 
-const mcpServer = {
-  command: 'skill-master-mcp',
-  args: [],
-  env: {
-    SKILL_MASTER_UPDATE_CHANNEL: 'stable',
-  },
-};
-
-const codexBlock = `
-[mcp_servers.skill_master]
-command = "skill-master-mcp"
-startup_timeout_sec = 120
-
-[mcp_servers.skill_master.env]
-SKILL_MASTER_UPDATE_CHANNEL = "stable"
-`;
-
-const claudeSnippet = {
-  mcpServers: {
-    skill_master: mcpServer,
-  },
-};
-
-const geminiSnippet = {
-  mcpServers: {
-    skill_master: mcpServer,
-  },
-};
-
-const antigravitySnippet = {
-  mcpServers: {
-    skill_master: mcpServer,
-  },
-};
-
-const ensureParent = (filePath) => mkdirSync(path.dirname(filePath), { recursive: true });
-
-const readJsonOrEmpty = (filePath) => {
-  if (!existsSync(filePath)) return {};
-  const raw = readFileSync(filePath, 'utf8').trim();
-  return raw ? JSON.parse(raw) : {};
-};
-
-const writeJson = (filePath, value) => {
-  ensureParent(filePath);
-  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-};
+function runClaudeCodeRegistration() {
+  if (!commandExists(claudeCodeCommand)) {
+    return {
+      ok: false,
+      skipped: true,
+      message: `Claude Code CLI '${claudeCodeCommand}' not found; run manually: ${formatShellCommand(claudeCodeCommand, claudeCodeArgs)}`,
+    };
+  }
 
-const mergeMcpServer = (filePath) => {
-  const current = readJsonOrEmpty(filePath);
-  const next = {
-    ...current,
-    mcpServers: {
-      ...(current.mcpServers ?? {}),
-      skill_master: mcpServer,
-    },
+  const result = spawnSync(claudeCodeCommand, claudeCodeArgs, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
+
+  return {
+    ok: result.status === 0,
+    skipped: false,
+    message: result.status === 0
+      ? `Claude Code registered via ${formatShellCommand(claudeCodeCommand, claudeCodeArgs)}`
+      : `Claude Code registration failed (${result.status ?? 'unknown'}): ${output || 'no output'}`,
   };
-  writeJson(filePath, next);
-};
+}
 
 const writeSnippetsFiles = () => {
   mkdirSync(snippetsDir, { recursive: true });
   writeFileSync(path.join(snippetsDir, 'codex.config.toml'), codexBlock.trimStart(), 'utf8');
-  writeJson(path.join(snippetsDir, 'claude_desktop_config.skill_master.json'), claudeSnippet);
-  writeJson(path.join(snippetsDir, 'gemini.settings.skill_master.json'), geminiSnippet);
-  writeJson(path.join(snippetsDir, 'antigravity.mcp_config.skill_master.json'), antigravitySnippet);
-};
-
-const removeCodexBlock = (content) => {
-  const lines = content.split('\n');
-  const kept = [];
-  let skipping = false;
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed === '[mcp_servers.skill_master]') {
-      skipping = true;
-      continue;
-    }
-    if (skipping && trimmed.startsWith('[') && !trimmed.startsWith('[mcp_servers.skill_master')) {
-      skipping = false;
-    }
-    if (!skipping) kept.push(line);
-  }
-  return kept.join('\n').trimEnd();
-};
-
-const appendCodex = () => {
-  ensureParent(codexConfig);
-  const current = existsSync(codexConfig) ? readFileSync(codexConfig, 'utf8') : '';
-  if (current.includes('[mcp_servers.skill_master]') && !force) {
-    return false;
-  }
-  const base = force ? removeCodexBlock(current) : current.trimEnd();
-  writeFileSync(codexConfig, `${base}\n${codexBlock}`, 'utf8');
-  return true;
+  writeJson(path.join(snippetsDir, 'claude_desktop_config.skill_master.json'), jsonSnippet);
+  writeFileSync(
+    path.join(snippetsDir, 'claude-code.commands.md'),
+    `# Claude Code - registrar skill_master\n\n\`\`\`bash\n${formatShellCommand(claudeCodeCommand, claudeCodeArgs)}\n\`\`\`\n\nDepois reinicie a sessao do Claude Code e valide com:\n\n\`\`\`bash\nclaude mcp list\n\`\`\`\n`,
+    'utf8',
+  );
+  writeJson(path.join(snippetsDir, 'claude-code.project.mcp.json'), jsonSnippet);
+  writeJson(path.join(snippetsDir, 'gemini.settings.skill_master.json'), jsonSnippet);
+  writeJson(path.join(snippetsDir, 'antigravity.mcp_config.skill_master.json'), jsonSnippet);
 };
 
 const actions = [];
@@ -155,23 +122,32 @@ if (writeSnippets) {
   actions.push(`snippets written to ${snippetsDir}`);
 }
 if (applyCodex) {
-  actions.push(appendCodex() ? `Codex registered at ${codexConfig}` : `Codex already had skill_master at ${codexConfig}`);
+  actions.push(appendCodexServer(codexConfig, serverConfig, { force }) ? `Codex registered at ${codexConfig}` : `Codex already had skill_master at ${codexConfig}`);
 }
 if (applyClaude) {
-  mergeMcpServer(claudeConfig);
-  actions.push(`Claude config merged at ${claudeConfig}`);
+  mergeMcpServer(claudeConfig, serverConfig, { recoverInvalidJson: force });
+  actions.push(`Claude Desktop config merged at ${claudeConfig}`);
+}
+if (applyClaudeCode) {
+  const result = runClaudeCodeRegistration();
+  actions.push(result.message);
+  if (!result.ok && !result.skipped) {
+    process.exitCode = 1;
+  }
 }
 if (applyGemini) {
-  mergeMcpServer(geminiConfig);
+  mergeMcpServer(geminiConfig, serverConfig, { recoverInvalidJson: force });
   actions.push(`Gemini config merged at ${geminiConfig}`);
 }
 if (applyAntigravity) {
-  mergeMcpServer(antigravityConfig);
+  mergeMcpServer(antigravityConfig, serverConfig, { recoverInvalidJson: force });
   actions.push(`Antigravity config merged at ${antigravityConfig}`);
 }
 
 console.log('[skill_master] Client registration');
+console.log(`- Command: ${serverConfig.command}`);
+console.log(`- Args: ${serverConfig.args.join(' ')}`);
 for (const action of actions) {
   console.log(`- ${action}`);
 }
-console.log('- Restart Codex, Claude, Gemini or Antigravity after registration.');
+console.log('- Restart Codex, Claude Desktop, Claude Code, Gemini or Antigravity after registration.');

package/docs/operations/GUIA_MULTI_COMPUTADOR.md

@@ -0,0 +1,262 @@
+# Guia Multi-Computador - Skill Master MCP
+
+## 1. Cenario
+
+Voce quer usar o mesmo MCP `skill_master` em varios computadores, mantendo todos atualizados e escolhendo o canal de distribuicao mais adequado para cada caso.
+
+## 2. Modelos recomendados
+
+Hoje existem dois caminhos validos.
+
+### Modelo A - npm publico
+
+Melhor para:
+
+- notebooks novos
+- instalacao rapida
+- ambientes onde o usuario nao deve clonar o repositorio
+- Claude, Codex, Gemini e clientes MCP que aceitam `npx`
+
+Base:
+
+```bash
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+### Modelo B - clone + launcher com auto-update
+
+Melhor para:
+
+- desenvolvimento do MCP
+- testes de `stable` e `beta`
+- controle maior sobre manifests e atualizacao por `git pull --ff-only`
+- ambiente com repo privado
+
+Cada computador tera:
+
+- clone local do repositorio
+- `git`
+- `node` 18+
+- launcher configurado no cliente MCP
+- configuracao local em `%USERPROFILE%/.skill-master/config.json` no Windows ou `~/.skill-master/config.json` no Linux/macOS
+
+Quando o menu detectar que o computador ainda nao esta globalmente pronto, ele vai mostrar o caminho de bootstrap e o atalho unico:
+
+```bash
+skill-master-bootstrap-global
+```
+
+Esse atalho instala as skills globais embutidas e registra Codex, Claude, Gemini e Antigravity para reconhecer `skill_master` como parte do sistema no cliente local.
+
+A partir da correcao multi-OS, o registro recomendado nao depende mais de `PATH`. O registrador grava o Node.js absoluto como `command` e o `bin/skill-master.mjs` absoluto como `args`, o que evita falhas comuns em Windows, Linux, macOS e apps desktop que nao herdam o ambiente do terminal.
+
+A partir da preparacao `0.0.11`, use o doctor para validar notebooks novos:
+
+```bash
+skill-master-menu --run doctor
+skill-master-menu --run bootstrap-global --yes
+```
+
+O bootstrap registra Codex, Claude Desktop, Claude Code, Gemini CLI e Antigravity quando os clientes locais estiverem disponiveis. Depois, reinicie os clientes.
+
+## 3. Instalacao em um novo computador
+
+### 3.1 Opcao rapida - npm publico
+
+#### Windows
+
+```powershell
+npm install -g @fprad0/skill-master-mcp
+```
+
+ou:
+
+```powershell
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+#### Linux / macOS
+
+```bash
+npm install -g @fprad0/skill-master-mcp
+```
+
+ou:
+
+```bash
+npx -y @fprad0/skill-master-mcp@latest
+```
+
+### 3.2 Opcao controlada - clone local
+
+Pre-requisitos:
+
+- Git instalado
+- Node.js 18+
+- acesso ao GitHub
+- token read-only se o repositorio for privado
+
+Clone:
+
+```powershell
+cd C:\Users\CDT\Documents
+git clone https://github.com/FPrad0/skill-master-mcp.git
+cd skill-master-mcp
+npm ci
+npm run build
+```
+
+### 3.3 Configuracao local
+
+Criar:
+
+```text
+C:\Users\<USER>\.skill-master\config.json
+```
+
+Modelo:
+
+```json
+{
+  "channel": "stable",
+  "autoUpdate": true,
+  "updateMode": "on-start",
+  "manifestUrl": "https://raw.githubusercontent.com/FPrad0/skill-master-mcp/main/manifests/channels/stable.json",
+  "localSkillRoots": [
+    "%USERPROFILE%/.codex/skills",
+    "%USERPROFILE%/.agents/skills"
+  ],
+  "allowWebSources": false
+}
+```
+
+## 4. Configuracao do cliente MCP
+
+No modelo npm global, prefira sempre o registro gerado por `skill-master-register-clients`, porque ele usa caminhos absolutos.
+
+No modelo clone + launcher, o launcher ainda e valido para desenvolvimento, mas o doctor vai classificar esse modo como `launcher`, nao como o modo robusto de pacote global.
+
+Exemplo robusto para Codex:
+
+```toml
+[mcp_servers.skill_master]
+command = "C:\\Program Files\\nodejs\\node.exe"
+args = ["C:\\Users\\CDT\\AppData\\Roaming\\npm\\node_modules\\@fprad0\\skill-master-mcp\\bin\\skill-master.mjs"]
+startup_timeout_sec = 120
+
+[mcp_servers.skill_master.env]
+SKILL_MASTER_UPDATE_CHANNEL = "stable"
+```
+
+Para migrar clientes antigos que ainda usam `skill-master-mcp` via PATH, `npx` ou launcher local:
+
+```bash
+skill-master-register-clients --apply-all --force
+skill-master-menu --run doctor
+```
+
+Para corrigir apenas o Claude Code depois de `npm install -g @fprad0/skill-master-mcp`, use:
+
+```bash
+skill-master-register-clients --apply-claude-code --claude-code-scope user
+claude mcp list
+```
+
+No modelo clone + launcher, o cliente deve chamar o launcher, nao o `dist/index.js` diretamente.
+
+Exemplo conceitual:
+
+```json
+{
+  "mcpServers": {
+    "skill_master": {
+      "command": "powershell",
+      "args": [
+        "-ExecutionPolicy",
+        "Bypass",
+        "-File",
+        "C:/Users/CDT/Documents/skill-master-mcp/scripts/skill-master-launcher.ps1"
+      ]
+    }
+  }
+}
+```
+
+## 5. Como as atualizacoes chegam automaticamente
+
+### No modelo npm publico
+
+1. voce publica uma nova versao no npm publico
+2. a maquina cliente usa `@latest`
+3. no proximo `npx` ou reinstalacao, a nova versao e resolvida
+
+### No modelo clone + launcher
+
+1. voce faz push no GitHub
+2. voce atualiza o manifesto `stable.json`
+3. o usuario abre o MCP
+4. o launcher verifica o manifesto
+5. se houver versao nova e o clone local estiver limpo, o launcher atualiza
+6. o MCP inicia ja atualizado
+
+## 6. Como publicar uma atualizacao
+
+### Caminho publico
+
+1. subir a nova versao para `main`
+2. publicar pelo workflow `Publish Skill Master to npmjs` somente com autorizacao explicita
+3. validar com `npm view` e `npx`
+
+### Caminho clone + launcher
+
+1. subir a nova versao para `main`
+2. atualizar `manifests/channels/stable.json`
+3. criar release/tag quando fizer sentido
+4. deixar o launcher puxar com `git pull --ff-only`
+
+## 7. Estrategia para varios usuarios
+
+### Poucos usuarios tecnicos
+
+Use clone privado + launcher. E a rota com mais controle.
+
+### Varios usuarios sem perfil tecnico
+
+Use npm publico.
+
+Se for necessario restringir distribuicao, evolua para:
+
+- pacote npm privado
+- instalador/bundle
+- MCP remoto
+
+### Equipe ou empresa
+
+Evoluir para:
+
+- GitHub Packages com permissoes
+- workflow de release
+- canais `stable` e `beta`
+- logs e telemetria minima opcional
+
+## 8. Manutencao
+
+Recomendacoes:
+
+- manter changelog curto
+- nunca quebrar configuracao sem migracao
+- testar update em uma maquina secundaria antes de mover `stable`
+- manter `beta` para validacao
+- documentar breaking changes
+
+## 9. Quando nao atualizar automaticamente
+
+No modelo clone + launcher, o updater deve recusar atualizacao automatica quando:
+
+- houver arquivos locais modificados
+- o GitHub estiver inacessivel
+- o manifesto estiver invalido
+- houver mudanca de versao de Node nao atendida
+- `npm ci` ou build falhar
+
+Nesses casos, ele deve iniciar a versao local e mostrar o status pela ferramenta `skill_master_sync_status`.