jarvis-ai-framework 6.1.0 → 8.1.0

package/AGENTS.md

@@ -62,8 +62,8 @@ prompts/
 │   │   ├── product-specs-update/
 │   │   ├── eng-qa/                 # Base neutra de QA (+ especializações em QA_SPECIALIZATIONS)
 │   │   ├── eng-qa-planner/         # Planejamento de testes e análise de gaps de cobertura
-│   │   ├── jarvis-report-issue/          # Auto-report de bugs no repo do Jarvis (GitLab/GitHub/Bitbucket)
-│   │   ├── eng-global-task-comment/      # Comentário no card (Jira/Linear/GitHub/Asana)
+│   │   ├── jarvis-report-issue/          # Auto-report de bugs no repo do Jarvis (CLI do host: gh)
+│   │   ├── eng-global-task-comment/      # Comentário no card (Jira/GitHub/GitLab, pela CLI do vendor)
 │   │   ├── jarvis-list-specializations/ # Lista especializações de stack instaladas e registradas
 │   │   ├── jarvis-create-specialization/ # Cria uma especialização de stack a partir do código do projeto e a registra
 │   │   ├── jarvis-evolution-architect/ # Mentor de arquitetura para a evolução do Jarvis
@@ -78,7 +78,7 @@ prompts/
 │   │   │   └── frontend/         # eng.frontend-rules.md (HUB: FRONTEND)
 │   │   └── product/              # prod-rules.md (AREA=PRODUCT)
 │   │
-│   ├── rules-on-demand/          # Rules de uma etapa so (start, plan, work, pre-pr, pr, tech-spec, breakdown): o workflow manda ler
+│   ├── rules-on-demand/          # Rules lidas pelo workflow que as usa (as de uma etapa, como start, plan e pr, e as transversais, como doc-links e warm-up)
 │   │
 │   ├── scripts/                  # Scripts utilitarios
 │   └── docs/                     # Documentacao adicional
@@ -219,7 +219,7 @@ Quando atuar em um projeto alvo, detectar comandos em:
 2. `$IDE/ENV.md` - Contexto do ambiente
 3. `$IDE/JARVIS.md` - Guia principal de uso
 4. `$IDE/rules/` - Regras especificas por dominio (carregadas no inicio)
-   `$IDE/rules-on-demand/` - Regras de uma etapa so, lidas pelo workflow
+   `$IDE/rules-on-demand/` - Regras de uma etapa ou transversais, lidas pelo workflow que as usa
 5. `$IDE/agents/` - Definicoes de agentes
 6. `$IDE/skills/` - Playbooks operacionais
 7. `$IDE/workflows/` - Templates de execucao
@@ -255,7 +255,7 @@ Cada pasta pode ter seu proprio AGENTS.md com instrucoes especificas:
 /eng.plan "feature"      # Plano de execucao faseado (somente planejamento)
 /eng.work "feature"      # Implementacao e testes (commit por fase, sem push/PR)
 /eng.pre-pr              # Validacao pre-PR
-/eng.pr                  # Cria branch, commit e PR
+/eng.pr                  # Push e PR, depois da pergunta (regra de ouro)
 ```
 
 ### Documentacao
@@ -285,7 +285,7 @@ Tabela completa de mapeamento comando/trigger → skill: ver `$IDE/skills/AGENTS
 |------|---------|-----------|
 | Planejamento | `eng.start`, `eng.plan` | Somente analise, sem codigo |
 | Implementacao | `eng.work` | Codigo e testes, commit por fase, sem push nem PR |
-| Entrega | `eng.pr` | Branch, commit e PR |
+| Entrega | `eng.pr` | Push e PR, depois da pergunta (regra de ouro) |
 
 ---
 

package/README.md

@@ -14,18 +14,13 @@
 
 ### 1. Instale
 
-Global (comando `jarvis` no PATH):
+O Jarvis é instalado **só global** (comando `jarvis` no PATH):
 
 ```bash
 npm install -g jarvis-ai-framework
 ```
 
-**Só neste workspace** (não sobe no PATH):
-
-```bash
-cd workspace-squad/
-npm install jarvis-ai-framework --save-dev
-```
+Não instale o pacote dentro do projeto: o `jarvis init` roda **dentro do projeto** e copia os assets do Jarvis global para a pasta da IDE. Se ele achar uma cópia local (`node_modules` ou dependência no `package.json`), avisa que ela é ignorada.
 
 Confira **onde** o binário ficou no PATH (útil se houver mais de uma instalação):
 
@@ -42,8 +37,6 @@ jarvis --version
 jarvis init --ide cursor
 ```
 
-Se instalou só com `--save-dev`, use `npx jarvis init --ide cursor`.
-
 IDEs: `windsurf` · `claude` · `cursor` · `codex` · `opencode` · `gemini` · `kiro`
 
 ### 3. No chat da IDE
@@ -76,13 +69,6 @@ Global (comando `jarvis` no PATH):
 npm install -g /caminho/para/jarvis
 ```
 
-**Só neste workspace** (não sobe no PATH):
-
-```bash
-cd workspace-squad/
-npm install /caminho/para/jarvis --save-dev
-```
-
 **`npm link`** (útil se você altera o clone e quer refletir na hora):
 
 ```bash
@@ -90,12 +76,7 @@ cd /caminho/para/jarvis
 npm link
 ```
 
-Isso já registra o comando `jarvis` no global. Opcional, para o workspace resolver o pacote:
-
-```bash
-cd workspace-squad/
-npm link jarvis-ai-framework
-```
+Isso já registra o comando `jarvis` no global. Não rode `npm link jarvis-ai-framework` dentro do workspace: isso cria uma cópia local em `node_modules`, que o `jarvis init` ignora (e avisa).
 
 Confira **onde** o binário ficou no PATH (útil se houver mais de uma instalação):
 
@@ -137,12 +118,6 @@ git pull
 npm install -g /caminho/para/jarvis
 ```
 
-**Só no workspace (`--save-dev`):**
-```bash
-cd workspace-squad/
-npm install /caminho/para/jarvis --save-dev
-```
-
 **Com `npm link`:** o `git pull` no clone já basta — o link aponta para a pasta.
 
 Antes de seguir, confira se o `jarvis` do PATH é o que você acabou de atualizar:
@@ -164,7 +139,7 @@ jarvis init --ide cursor
 
 Isso copia de novo `agents/`, `skills/`, `workflows/`, `rules/`, `templates/` para `.$IDE/` e atualiza o `jarvis-lock.json`.
 
-Se o workspace usa `--save-dev` e já tem `jarvis-lock.json`, o `npm install` do passo 2 também dispara o **postinstall** e sincroniza sozinho para a IDE do lock.
+Esse é o único caminho de atualização dos assets: o `npm install -g` não sincroniza nenhum projeto sozinho. Quando os assets do projeto estão atrás do Jarvis global, o `/jarvis-init` avisa no início e oferece o `jarvis init --upgrade`.
 
 ### 4. ENV.md (só se houver variáveis novas)
 
@@ -183,11 +158,11 @@ Escolha **Upgrade (C)** — adiciona chaves novas do template sem apagar os valo
 | Passo | O que muda |
 |-------|------------|
 | `git pull` | Código do framework no clone |
-| `npm install -g` / `--save-dev` | Binário `jarvis` + pacote que o `init` lê |
-| `jarvis init` (ou postinstall com lock) | Arquivos em `.$IDE/` (skills, agents, workflows…) |
+| `npm install -g` | Binário `jarvis` + pacote que o `init` lê |
+| `jarvis init` | Arquivos em `.$IDE/` (skills, agents, workflows…) e o Context7 no arquivo de MCP da IDE (ex.: `.mcp.json` no Claude Code; só acrescenta, sem apagar outros servidores) |
 | `/jarvis-init` Upgrade | Só `$IDE/ENV.md` (variáveis faltantes) e, se você aceitar o passo opcional "adicionar as stacks", as listas de especializações |
 
-`ENV.md`, `.jarvis/sessions/` e o `.gitignore` do workspace **não** são sobrescritos pelo sync de assets.
+`ENV.md`, `.jarvis/sessions/` e o `.gitignore` do workspace **não** são sobrescritos pelo sync de assets. O `.gitignore` só é criado ou alterado quando a raiz tem `.git`; sem `.git` (como no modo workspace) a raiz não é versionada e o init não o toca.
 
 | Papel | Descricao | Link |
 |-------|-----------|------|
@@ -212,7 +187,7 @@ O `/jarvis-init` pergunta o `ARTIFACT_STYLE` (variável do `ENV.md`):
 | Valor | O que acontece |
 |---|---|
 | `ai-generated` (padrão) | Como sempre: metadados, links de rastreabilidade e padrões da ferramenta |
-| `human-generated` | Nada do que o Jarvis publica (commit, PR/MR, comentário no card, issue) leva marca de IA ou da IDE: o `/eng.pr` confere e limpa antes do push. Todo documento gerado pergunta, no fim, se você quer a versão humanizada, gravada ao lado como `{nome}.public.md` para repassar a clientes ou stakeholders |
+| `human-generated` | Nada do que o Jarvis publica (commit, PR/MR, comentário no card, issue; sempre depois da pergunta) leva marca de IA ou da IDE: o `/eng.pr` confere e limpa antes do push. Todo documento gerado pergunta, no fim, se você quer a versão humanizada, gravada ao lado como `{nome}.public.md` para repassar a clientes ou stakeholders |
 
 Com `human-generated`, o `/jarvis-init` copia a rule `rules/artifact-style-rules.md` (eixo `ARTIFACT_STYLE` do `Applies to`); com `ai-generated`, ela nem existe na sessão. Trocou o valor à mão? Rode `/jarvis-init upgrade`.
 
@@ -253,6 +228,6 @@ Precisa de ajuda?
 - **Engenharia (um guia por comando `eng.*`)** — [`docs/engenharia/`](docs/engenharia/README.md)
 - **Indice de docs/** — [`docs/README.md`](docs/README.md)
 - **Instrucoes para agentes / mapa de skills** — `AGENTS.md`
-- **Issues/Feedback** — skill `jarvis-report-issue`
+- **Issues/Feedback** — skill `jarvis-report-issue` (pergunta antes de abrir; sem a CLI do host (`gh`), sem login, sem rede ou com o seu Não, a issue fica em `.jarvis/issues/issue-{desc}.md` para abrir à mão)
 - **Duvidas sobre comandos** — Pergunte diretamente ao agent:
   `"Como funciona /eng.start?"` | `"Qual a diferenca entre /eng.work e /pr?"` | `"O que e CDD?"`

package/agents/engineering/data/eng.data-engineer.agent.md

@@ -66,7 +66,7 @@ Ativado quando há suspeita de dado incorreto, queda de volume ou falha de pipel
 - Identificar causa raiz: fonte, transformação ou carga
 - Verificar logs de execução e checks de qualidade
 - Propor correção e plano de reprocessamento idempotente
-- Alertar squads afetadas com contexto claro
+- Alertar squads afetadas com contexto claro (mostrando a mensagem e perguntando antes de enviar, regra de ouro)
 
 **Skill integrada**: `$IDE/skills/eng-data/SKILL.md` + `DATA_SPECIALIZATIONS`
 
@@ -126,7 +126,7 @@ CONTEXT_PROFILE:
 
 | Sinal | Urgência | Comportamento |
 |-------|----------|---------------|
-| `dado errado em produção`, `dashboard parado`, `pipeline falhou` | **CRÍTICA** | Fast track: diagnóstico imediato, isolar causa, comunicar squads afetadas |
+| `dado errado em produção`, `dashboard parado`, `pipeline falhou` | **CRÍTICA** | Fast track: diagnóstico imediato, isolar causa, comunicar squads afetadas (texto pronto; o envio só depois da pergunta, regra de ouro) |
 | `atraso`, `dado desatualizado`, `queda de volume` | **ALTA** | Investigação ágil, reprocessar com idempotência |
 | `nova feature`, `novo pipeline`, `contrato de dados` | **NORMAL** | Fluxo completo: documentar antes, implementar, validar |
 | `melhoria`, `refactoring de query`, `otimização` | **BAIXA** | Análise cuidadosa de impacto antes de qualquer mudança |
@@ -226,7 +226,7 @@ Para detecção automática de contexto de tarefas:
 ### 3. Qualidade e Monitoramento
 
 - Bloquear promoção de camada quando falha de qualidade ocorre
-- Alertar no canal do time de Data quando falha afeta `gold`
+- Alertar no canal do time de Data quando falha afeta `gold` (depois da pergunta, regra de ouro; o alerta automático de pipeline é do runtime)
 - Manter tabela `gold.pipeline_audit` com metadados de execução
 
 ### 4. Política de Dados Sensíveis

package/agents/engineering/eng.docs-consolidator.agent.md

@@ -15,7 +15,7 @@ tools: Read, Glob, Grep, Bash, Write, Edit
 
 Você transforma o que foi **implementado** num registro que dure. Duas pessoas vão ler o que você escreve:
 - **humanos:** outro squad, alguém novo no time, a própria pessoa daqui a seis meses;
-- **IAs:** o `/warm-up`, o `/eng.start` e os `/prod.spec.*` consultam o Central docs como verdade sobre o sistema.
+- **IAs:** o `/warm-up`, o `/eng.start` e os `/prod.spec.*` consultam o Central docs como verdade sobre o que está implementado.
 
 Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
 
@@ -33,7 +33,7 @@ Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
    - Sugira o slug da funcionalidade em kebab-case, curto e pelo nome que o negócio usa (ex.: `feature-checkout-pix`, não `feature-task-123`).
    - Os títulos dizem o que a funcionalidade é.
 6. **Referências sempre com URL:**
-   - card pelo `TASK_MANAGER` do `ENV.md`, com a URL no padrão da `eng.integrations-rules.md` (Jira `/browse/`, Linear `/issue/`, GitHub `/issues/`, Asana); no modo freelance, o número de controle, sem URL;
+   - card pelo `TASK_MANAGER` do `ENV.md`, com a URL no padrão da `eng.integrations-rules.md` (Jira `/browse/`, GitHub `/issues/`, GitLab `/-/issues/`); no modo freelance, o número de controle, sem URL;
    - PR/MR pelo `VERSION_CONTROL` ou pelo `remote origin` (número + URL).
 7. **Nunca inventar.** Sem fonte, pergunte ao agente principal (que pergunta ao usuário) ou registre como "não informado".
 8. **Sem dados sensíveis.** Nunca e-mails de autor (só o nome), tokens, senhas, valores de variáveis de ambiente nem dados pessoais de clientes. Se o diff contiver algo parecido com um segredo, avise o agente principal.
@@ -46,7 +46,7 @@ Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
 4. `git log {base}..HEAD --format='%h|%an|%ad|%s' --date=short` e `git diff --stat {base}...HEAD`.
 5. O código alterado, só leitura, para confirmar o comportamento real.
 6. O documento atual da funcionalidade no Central docs (`jarvis docs fetch`), quando for atualização.
-7. O `gate-checklist.md` e o `pull-request.md` da sessão, se existirem.
+7. O `gate-checklist.md` (a rodada mais recente; as anteriores, `gate-checklist-rodada-{N}.md`, são histórico) e o `pull-request.md` da sessão, se existirem.
 
 ## O que você produz
 

package/agents/engineering/qa/eng.qa.quality-champion-task-agent.md

@@ -39,7 +39,7 @@ Você opera estritamente dentro do **contexto de tarefas Jira e especificações
    - Casos extremos não cobertos
    - Riscos potenciais, ambiguidades ou complexidade oculta
 
-5. Comentar melhorias diretamente no Jira:
+5. Comentar melhorias no Jira pelo `/eng-global-task-comment`, que mostra o texto e pergunta antes de enviar (regra de ouro, `eng.integrations-rules.md`):
    - Sugerir redação mais clara
    - Propor critérios de aceitação faltantes
    - Recomendar cenários de teste adicionais
@@ -54,7 +54,7 @@ Você opera estritamente dentro do **contexto de tarefas Jira e especificações
 
 ### Formato de Saída (Sempre Estruturado)
 
-Use o seguinte formato em comentários Jira:
+Use o seguinte formato nos comentários Jira (eles só saem depois da pergunta, regra de ouro):
 
 **Resumo da Revisão de Qualidade**
 

package/agents/engineering/qa/eng.qa.test-planner.md

@@ -15,7 +15,7 @@ Antes de qualquer ação, determine qual modo aplicar:
 
 **Modo A — Estratégia a partir da Tech Spec (pré-código)**
 Aplicar quando invocado via `eng.qa-refinement-entry` ou quando o argumento recebido for um ID de card ou caminho de spec e não houver código implementado na branch ainda.
-- Fonte de dados: card no $TASK_MANAGER via integração disponível (Jira MCP)
+- Fonte de dados: card no $TASK_MANAGER, lido pela CLI do vendor (ação `view` do catálogo `bin/lib/integrations/vendors.json`: `gh issue view`, `glab issue view` ou `acli jira workitem view`) ou pelo conteúdo colado pelo usuário
 - Não executar `git diff`, `git log` ou qualquer comando que dependa de código
 - Saída: `$ENG_DOCS/qa/strategies/{task-id}-test-strategy.md`
 
@@ -125,7 +125,7 @@ Usar quando: invocado via `eng.qa-refinement-entry`, ou quando git diff retornar
 
 ### A.1. Buscar o Card
 
-Usar a integração disponível com o $TASK_MANAGER (ex: Jira MCP) para buscar o card pelo ID recebido como argumento.
+Buscar o card pelo ID recebido como argumento, pela CLI do vendor (ação `view` do catálogo `bin/lib/integrations/vendors.json`: `gh issue view`, `glab issue view` ou `acli jira workitem view`) ou pelo conteúdo colado pelo usuário.
 Extrair: título, descrição, critérios de aceite, análise técnica, dependências e qualquer anexo de spec.
 
 Se a integração não estiver disponível, solicitar ao usuário que cole o conteúdo da spec diretamente.

package/bin/README.md

@@ -7,20 +7,23 @@ Fonte do binário `jarvis` (instalado via `npm install -g jarvis-ai-framework`,
 ```
 bin/
 ├── jarvis.js                  # Entrypoint (shebang). ~10 linhas, não cresce.
-├── postinstall.js             # Roda no `npm install` (sincroniza assets se já havia .{ide}/ no cwd)
+├── postinstall.js             # Roda no `npm install` (só imprime as dicas de uso)
 ├── commands/                  # Um arquivo por comando. Lógica pura, zero commander.
 │   ├── init.js, list.js, info.js, whoami.js, ...
 │   ├── docs-sync.js, docs-publish.js
-│   └── qa-signoff.js, install-rtk.js, tokens.js, map.js
+│   └── install-rtk.js, tokens.js, map.js
 └── lib/
     ├── cli/
     │   ├── program.js         # Único lugar que monta o commander — ver "Arquitetura"
     │   └── shared-options.js  # .option() repetidos entre comandos (--ide, --quiet, etc.)
-    ├── vcs/                   # Adapters de Git host (GitLab/GitHub/Bitbucket)
-    │   ├── api.js             # Lógica HTTP real (createIssue, createMergeRequest)
+    ├── integrations/          # Board e git pela CLI oficial do vendor (FRD-006)
+    │   ├── vendors.json       # Catálogo: vendors (jira/acli, github/gh, gitlab/glab), comandos por ação e variáveis
+    │   └── cli-runner.js      # checkCli, buildArgs, runAction (execFile sem shell), códigos de saída 0/1/3/4
+    ├── vcs/                   # GitHub/GitLab pela CLI (gh pr create, glab mr create, issue create)
+    │   ├── api.js             # createIssue, createMergeRequest, cardUrl (sobre o cli-runner)
     │   ├── create-merge.js, create-issue.js   # função exportada + CLI direto (ver abaixo)
     ├── tasks/
-    │   └── comment.js         # Adapter de task manager (jira/linear/github/asana) — mesmo padrão
+    │   └── comment.js         # Comentário no card (jira/github/gitlab) pelo cli-runner — mesmo padrão
     ├── config/                # ide-config.js (fonte de verdade de IDEs), constants.js
     ├── core/                  # scanner.js, sync-engine.js, profile-filter.js, token-report.js
     ├── docs/                  # Central docs: fetch/publish pelo adaptador + validação de frontmatter
@@ -28,7 +31,7 @@ bin/
     │   ├── fetch-file.js       # openStorageFromEnv() + fetchFile() — `docs sync`/`docs fetch`/`docs publish`
     │   ├── publish-file.js     # tipos, resolveDestPath() e publishFile() — `docs publish`
     │   └── storage/            # adaptadores (CENTRAL_DOCS_STORAGE): index.js (fábrica), filesystem.js (pasta + git), build-index.js
-    ├── utils/                 # logger.js, ui.js, paths.js, frontmatter.js, git-parser.js, npmrc-parser.js
+    ├── utils/                 # logger.js, ui.js, paths.js, frontmatter.js, git-parser.js
     ├── flow-map/              # `jarvis map` — grafo de chamadas entre workflows/skills/agents
     ├── auth/                  # session.js (auth.json legado, hoje só `jarvis logout` o lê)
     └── env-loader.js          # Resolve e lê o ENV.md ($IDE/ENV.md)
@@ -116,12 +119,12 @@ if (fileURLToPath(import.meta.url) === process.argv[1]) {
 
 ## Variáveis de ambiente lidas diretamente (fora do ENV.md)
 
-`bin/lib/tasks/comment.js` e `bin/lib/vcs/*.js` leem `process.env` direto (`TASK_MANAGER`, `TOKEN_TASK_MANAGER`, `CENTRAL_DOCS_REPO`, `VERSION_CONTROL`, etc.) — não passam pelo `env-loader.js`/ENV.md. Isso é intencional: esses adapters são chamados por skills/workflows que já exportam essas variáveis do `ENV.md` para o processo (`set -a; eval "$(grep ... $IDE/ENV.md)"; set +a`) antes de invocar o comando. Se um comando novo precisar ler o `ENV.md` diretamente, use `env-loader.js#resolveEnvPath`/`loadEnv` (ver `whoami.js`, `tokens.js`, `qa-signoff.js` como exemplo) em vez de `process.env`.
+`bin/lib/tasks/comment.js` e `bin/lib/vcs/*.js` leem `process.env` direto (`TASK_MANAGER`, `TASK_MANAGER_ACCESS`, `TASK_MANAGER_URL_BASE`, `VERSION_CONTROL`, etc.; nenhum token: o login é o da CLI do vendor) — não passam pelo `env-loader.js`/ENV.md. O `jarvis tasks comment` e o `jarvis vcs create-merge` completam o que faltar no ambiente lendo o `$IDE/ENV.md` do workspace (`readFileEnv`/`resolveFileEnv` em `integrations/cli-runner.js`, com `--ide`/`--env-file`; o ambiente do processo vence; `setting` tira aspas e comentário de fim de linha), então os skills não precisam exportar nada nem usar `eval`. O `accessGate` decide antes de qualquer envio: só `cli` (ou vazio, com aviso) segue; `manual`, valor inválido e ENV.md ilegível saem com 3. O ENV.md lido é repassado ao `createMergeRequest` (`fileEnvResult`), inclusive pelo Central docs. Se um comando novo precisar ler o `ENV.md` diretamente, use `env-loader.js#resolveEnvPath`/`loadEnv` (ver `whoami.js` e `tokens.js` como exemplo) em vez de `process.env`.
 
 ## Testes
 
 - `npm run test:comandos` — valida que toda referência a comando/skill nos workflows e skills existe de fato (não testa o CLI em runtime).
-- `npm run test:filtro` — testes unitários de `profile-filter.js`, `token-report.js`, `flow-map`, `env-loader.js`, `sync-engine.js` e `vcs/api.js`.
+- `npm run test:filtro` — testes unitários de `profile-filter.js`, `token-report.js`, `flow-map`, `env-loader.js`, `sync-engine.js`, `vcs/api.js`, `tasks/comment.js`, `integrations/` (catálogo e runner) e do upgrade.
 - Não há teste automatizado de ponta a ponta do CLI (`jarvis <comando>` real) — a camada de dispatch (`program.js`, `bin/commands/*.js`) não é cobrida pelos testes unitários. Qualquer mudança ali precisa de validação manual dos comandos afetados.
 
 ### Como testar código que lê `fs`/rede sem mockar módulo
@@ -130,10 +133,10 @@ Os 3 arquivos mais críticos sem cobertura até pouco tempo atrás (`env-loader.
 
 - **`env-loader.js`** (e `flow-map.test.js`, mais antigo): `mkdtempSync(join(tmpdir(), "jarvis-..."))` monta um workspace fake com `.{ide}/ENV.md`, roda a função contra ele, `rmSync` no `finally`.
 - **`sync-engine.js`**: `getFrameworkRoot()` (`utils/paths.js`) já tem um escape hatch — `process.env.JARVIS_ROOT`, se definido e existir, vence sobre o framework real. O teste aponta `JARVIS_ROOT` para um fixture mínimo (`agents/`, `skills/`, etc. com 1 arquivo cada) em vez de sincronizar o framework inteiro.
-- **`vcs/api.js`**: usa `mock.method(globalThis, "fetch", ...)` do `node:test` pra controlar a resposta por vendor, sem mockar o módulo nem tocar rede real. **Atenção**: toda função de rede chama `getVcsToken()` antes do fetch — fixe `GITLAB_TOKEN`/`GITHUB_TOKEN`/`BITBUCKET_TOKEN` via env var no teste (ver `withEnv` em `vcs-api.test.js`), senão o resultado depende do que a máquina que roda o teste tiver em `.npmrc`/`gh auth`.
+- **`integrations/cli-runner.js`, `vcs/api.js`, `tasks/comment.js`**: o `exec` (que roda a CLI do vendor) é injetável pelo último parâmetro (`deps`); o teste passa uma CLI falsa que responde por subcomando (ver `fakeExec` em `cli-runner.test.js`), sem chamar `gh`/`glab`/`acli` de verdade nem depender do login da máquina. No `jarvis init --upgrade` (teste por subprocesso), `JARVIS_SKIP_CLI_CHECK=1` desliga a descoberta, e o teste dela põe uma CLI falsa no `PATH`.
 - **`docs/` (Central docs)**: tudo em pasta temporária (`mkdtempSync`). A camada git do adaptador `filesystem` usa um repositório `git init --bare` local como `origin` (sem rede), e o `createMergeRequest` é injetado pelo parâmetro `deps` de `getStorage` (ver `docs-storage.test.js`).
 
-**Armadilha com `async`**: o helper `withEnv(vars, fn)` (em `vcs-api.test.js`) precisa de `return **await** fn()`, não `return fn()`, dentro do `try`. Sem o `await`, o `finally` que restaura a env var roda assim que `fn()` retorna uma Promise pendente — ou seja, **antes** da função terminar. Isso só não quebra quando a leitura da env var acontece antes do primeiro `await` de `fn` (ex: `createIssue` lê o token antes do seu próprio `fetch`); quebra silenciosamente em qualquer função com mais de um `await` antes de ler a variável.
+**Armadilha com `async`**: o helper `withEnv(vars, fn)` (em `vcs-api.test.js`) precisa de `return **await** fn()`, não `return fn()`, dentro do `try`. Sem o `await`, o `finally` que restaura a env var roda assim que `fn()` retorna uma Promise pendente — ou seja, **antes** da função terminar. Isso só não quebra quando a leitura da env var acontece antes do primeiro `await` de `fn` (ex: uma função que lê `process.env` antes do primeiro `await`); quebra silenciosamente em qualquer função com mais de um `await` antes de ler a variável.
 
 Ao escrever um teste novo para um arquivo que toca `fs`/rede, prefira um desses padrões a mockar o módulo inteiro ou refatorar pra injeção de dependência — nenhum dos arquivos acima precisou mudar uma linha de lógica de produção para ganhar teste.
 

package/bin/commands/docs-publish.js

@@ -108,7 +108,7 @@ export async function docsPublish(flags = {}) {
         "\n💡 Central docs com git: confira se a pasta está limpa (git status), se você tem permissão de push"
       );
       logger.error(
-        "   e se o token do vendor está configurado (GitLab .npmrc, GitHub gh auth, BITBUCKET_TOKEN)."
+        "   e se a CLI do host está logada (gh auth login, glab auth login)."
       );
     }
     process.exit(1);

package/bin/commands/init.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
-import { join, dirname, basename } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, dirname, basename, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { syncAssets } from "../lib/core/sync-engine.js";
 import { discoverAll } from "../lib/core/scanner.js";
@@ -16,24 +16,51 @@ import { getPackageInfo, getFrameworkRoot } from "../lib/utils/paths.js";
 import { logger, configureFromFlags } from "../lib/utils/logger.js";
 import { resolveEnvPath } from "../lib/env-loader.js";
 import { LOCK_FILE } from "../lib/config/constants.js";
+import { compareVersions, localInstall } from "../lib/utils/version.js";
 import {
   findStaleSkills,
   registeredSpecializations,
   removeStaleSkills,
 } from "../lib/core/stale-skills.js";
 import { parseEnvEntries, planEnvUpgrade, applyEnvUpgrade } from "../lib/core/env-upgrade.js";
+import { checkCli, getVendor } from "../lib/integrations/cli-runner.js";
 import {
   expandEnv,
   planDocsMigration,
   applyDocsMigration,
   rewriteRelatedDiscovery,
   declineEnvValues,
+  ensureGitignore,
 } from "../lib/core/docs-migrate.js";
+import { rootIsRepo } from "../lib/core/workspace-mode.js";
+import { ensureContext7 } from "../lib/core/mcp-config.js";
 
 function ask(rl, question) {
   return new Promise((resolve) => rl.question(question, resolve));
 }
 
+/**
+ * Grava o Context7 (MCP obrigatório) no arquivo de MCP da IDE e mostra o que falta.
+ * Só avisa: problema no arquivo de MCP não muda o código de saída (instalação e --upgrade).
+ */
+function setupMcp(workspaceDir, ide) {
+  const mcp = ensureContext7(workspaceDir, ide);
+  logger.info(`${BLUE}🔌 MCP (Context7):${NC}`);
+  for (const p of mcp.written) logger.info(`  ${GREEN}✓ ${p}${NC} (Context7 adicionado)`);
+  for (const p of mcp.present) logger.info(`${DIM}  ↳ ${p} (Context7 já configurado)${NC}`);
+  for (const m of mcp.manual) {
+    const why = m.reason
+      ? `${m.path}: ${m.reason}. Nada alterado; inclua à mão:`
+      : `Config só global: inclua em ${m.path}:`;
+    logger.info(`${YELLOW}  ⚠️  ${why}${NC}`);
+    for (const line of m.snippet.trimEnd().split("\n")) logger.info(`${DIM}     ${line}${NC}`);
+  }
+  for (const e of mcp.errors) logger.info(`${YELLOW}  ⚠️  ${e} (nada alterado)${NC}`);
+  const note = getIDEConfig(ide)?.mcpNote;
+  if (note && (mcp.written.length || mcp.manual.length)) logger.info(`${DIM}  ${note}${NC}`);
+  logger.info("");
+}
+
 export async function init(flags) {
   configureFromFlags(flags);
 
@@ -107,6 +134,10 @@ export async function init(flags) {
 
   const ideDir = join(cwd, `.${getIDEFolder(ide)}`);
 
+  // Avisos de versão antes da pergunta de reinstalação: quem responde "s" (ou usa --force)
+  // já sabe se vai rebaixar os assets.
+  warnVersionMismatch(cwd);
+
   // Reinstall: --force ou confirmação "s" devem sobrescrever assets (cpSync force:true).
   let forceSync = !!flags.force;
 
@@ -154,20 +185,16 @@ export async function init(flags) {
   for (const area of ["eng", "prod", "qa"]) {
     mkdirSync(join(jarvisRoot, "sessions", area), { recursive: true });
   }
-  const gitignore = join(cwd, ".gitignore");
-  const ignoreLine = ".jarvis/";
-  if (existsSync(gitignore)) {
-    const text = readFileSync(gitignore, "utf8");
-    if (!text.split("\n").some((l) => l.trim() === ignoreLine || l.trim() === ".jarvis")) {
-      appendFileSync(gitignore, `${text.endsWith("\n") ? "" : "\n"}${ignoreLine}\n`);
-    }
-  } else {
-    writeFileSync(gitignore, `${ignoreLine}\n`);
+  // .gitignore só numa raiz versionada (com .git): no modo workspace a raiz não é um repositório.
+  if (rootIsRepo(cwd)) {
+    ensureGitignore(cwd, ".jarvis/");
   }
 
+  logger.info("");
+  setupMcp(cwd, ide);
+
   const pkg = getPackageInfo();
 
-  logger.info("");
   logger.info(`${GREEN}✓ Configuração concluída!${NC}`);
   logger.info(`${BOLD}${CYAN}  versão: ${pkg.name} v${pkg.version}${NC}`);
   logger.info(`${DIM}  origem: ${pkg.root}${NC}`);
@@ -235,6 +262,53 @@ function ideFromEnvPath(envPath) {
   return getIDEValues().find((v) => `.${getIDEFolder(v)}` === folder);
 }
 
+/**
+ * Avisos de versão antes do sync. O Jarvis é instalado só global:
+ * - cópia local no projeto (`node_modules` ou dependência no `package.json`) é ignorada;
+ *   se é ela que está rodando (`npx jarvis`, `./node_modules/.bin/jarvis`), o aviso diz isso;
+ * - lock do projeto mais novo que o Jarvis em uso: o sync rebaixaria os assets.
+ * Recebe o lock lido antes do `syncAssets`, que o reescreve.
+ * @param {string} workspaceDir
+ * @param {string} [lock] - versão do `jarvis-lock.json` do projeto
+ * @returns {{ downgrade: boolean, running: string }} `downgrade` = lock mais novo que o Jarvis em uso
+ */
+export function warnVersionMismatch(workspaceDir, lock = readLockVersion(workspaceDir)) {
+  const running = getPackageInfo().version;
+  // Caminhos reais dos dois lados: o Node já resolve o link do script (`import.meta.url`),
+  // então uma cópia por `npm link` em node_modules só bate com o realpath.
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return resolve(p);
+    }
+  };
+  const root = real(getFrameworkRoot());
+  const localDir = join(workspaceDir, "node_modules", "jarvis-ai-framework");
+  const runningLocal =
+    (root + sep).startsWith(real(join(workspaceDir, "node_modules")) + sep) ||
+    (existsSync(localDir) && root === real(localDir));
+  const local = localInstall(workspaceDir);
+  if (runningLocal) {
+    logger.info(
+      `${BLUE}ℹ️  O Jarvis em uso (${running}) é o mesmo de node_modules (cópia local do projeto). O Jarvis é instalado global: npm install -g jarvis-ai-framework, rode \`jarvis\` (sem npx) e remova a cópia local.${NC}`
+    );
+  } else if (local) {
+    logger.info(
+      `${BLUE}ℹ️  O Jarvis é instalado global (npm install -g jarvis-ai-framework). A cópia local deste projeto (${local.version} em ${local.source}) é ignorada: pode removê-la.${NC}`
+    );
+  }
+  const downgrade = compareVersions(lock, running) === 1;
+  if (downgrade) {
+    const who = runningLocal ? "o Jarvis em uso (cópia local)" : "o seu jarvis global";
+    logger.info(
+      `${YELLOW}⚠️  Os assets deste projeto são da ${lock}, mas ${who} é a ${running}. Atualize o global: npm install -g jarvis-ai-framework${NC}`
+    );
+  }
+  if (runningLocal || local || downgrade) logger.info("");
+  return { downgrade, running };
+}
+
 function readLockVersion(workspaceDir) {
   try {
     return (
@@ -245,6 +319,31 @@ function readLockVersion(workspaceDir) {
   }
 }
 
+/**
+ * Descoberta da CLI de cada eixo (só leitura: binário no PATH + `auth status`).
+ * Não pergunta nada: a confirmação do acesso e as variáveis ficam no `/jarvis-init` (Q2 da #181).
+ * `JARVIS_SKIP_CLI_CHECK=1` pula a descoberta (CI, sem rede).
+ */
+async function reportCliDiscovery(entries) {
+  const axes = [
+    ["TASK_MANAGER", "Board de cards"],
+    ["VERSION_CONTROL", "Controle de versão"],
+  ];
+  const targets = axes
+    .map(([key, label]) => ({ key, label, vendor: (entries.get(key) || "").toLowerCase() }))
+    .filter((t) => getVendor(t.vendor));
+  if (!targets.length) return;
+  if (process.env.JARVIS_SKIP_CLI_CHECK) {
+    logger.info(`${DIM}  • Descoberta da CLI pulada (JARVIS_SKIP_CLI_CHECK)${NC}`);
+    return;
+  }
+  for (const t of targets) {
+    const r = await checkCli(t.vendor);
+    const mark = r.installed && r.loggedIn ? GREEN : YELLOW;
+    logger.info(`${mark}  • ${t.label} (${t.key}=${t.vendor}): ${r.reason}${NC}`);
+  }
+}
+
 /**
  * `jarvis init --upgrade`: atualiza um projeto já configurado em uma passada.
  * 1. arquivos do framework (como o --force, sem perguntar); 2. só as chaves novas do ENV;
@@ -272,6 +371,27 @@ async function runUpgrade(cwd, flags) {
   const workspaceDir = resolved.root;
   const envPath = resolved.path;
   const previousVersion = readLockVersion(workspaceDir);
+  const { downgrade, running } = warnVersionMismatch(workspaceDir, previousVersion);
+  if (downgrade && !flags.yes) {
+    let go = false;
+    if (process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await ask(
+        rl,
+        `Seguir e rebaixar os assets de ${previousVersion} para ${running}? (s/N): `
+      );
+      rl.close();
+      go = answer.trim().toLowerCase() === "s";
+    } else {
+      logger.info(`${DIM}  Sem terminal interativo e sem --yes: nada será rebaixado.${NC}`);
+    }
+    if (!go) {
+      logger.info(
+        `${YELLOW}Upgrade interrompido: atualize o global (npm install -g jarvis-ai-framework) e rode de novo.${NC}\n`
+      );
+      return 1;
+    }
+  }
 
   // 1. Arquivos do framework (o ENV.md não está entre os sincronizados)
   logger.info(`${BLUE}⬆️  Upgrade do Jarvis em .${getIDEFolder(ide)}/${NC}\n`);
@@ -281,6 +401,7 @@ async function runUpgrade(cwd, flags) {
     keepEnvValues: true,
   });
   for (const item of sync.errors) logger.error(`${RED}  ✗ ${item}${NC}`);
+  setupMcp(workspaceDir, ide);
 
   // 2. Variáveis novas (só acrescenta)
   const envText = readFileSync(envPath, "utf-8");
@@ -390,7 +511,32 @@ async function runUpgrade(cwd, flags) {
       `${YELLOW}  ⚠️  WORKSPACE_MODE: a raiz é um repositório e há subpastas com .git (submódulos?): gravado como project; confira no ENV.md${NC}`
     );
   }
+  for (const key of envPlan.filledApplied || []) {
+    logger.info(`  • ${key} estava vazio: preenchido com o repositório oficial do Jarvis`);
+  }
+  if (envPlan.warnings.includes("TOKEN_TASK_MANAGER")) {
+    logger.info(
+      `${YELLOW}  ⚠️  TOKEN_TASK_MANAGER não é mais usado: o Jarvis usa o login da CLI do vendor. Faça o login da CLI e remova a linha pelo /jarvis-init upgrade (o valor não foi lido nem copiado)${NC}`
+    );
+  }
+  for (const w of envPlan.warnings.filter((x) => x.startsWith("UNSUPPORTED:"))) {
+    const [, key, vendor] = w.split(":");
+    logger.info(
+      `${YELLOW}  ⚠️  ${key}=${vendor} não é suportado (jira, github, gitlab): o eixo fica em freelance e as ações viram .md${NC}`
+    );
+  }
+  await reportCliDiscovery(futureEntries);
+
+  // Eixos com vendor do catálogo e sem forma de acesso definida: a confirmação é no /jarvis-init.
+  const pendingAxes = ["TASK_MANAGER", "VERSION_CONTROL"].filter((key) => {
+    const access = (futureEntries.get(`${key}_ACCESS`) || "").trim();
+    return getVendor(futureEntries.get(key)) && (!access || /^\[.*\]$/.test(access));
+  });
   logger.info("");
-  logger.info(`${CYAN}➡️  Agora rode ${BOLD}/jarvis-init upgrade${NC}${CYAN} na IDE.${NC}\n`);
+  logger.info(
+    pendingAxes.length
+      ? `${CYAN}➡️  Agora rode ${BOLD}/jarvis-init upgrade${NC}${CYAN} na IDE para confirmar o acesso de ${pendingAxes.join(" e ")} (e as variáveis).${NC}\n`
+      : `${CYAN}➡️  Agora rode ${BOLD}/jarvis-init upgrade${NC}${CYAN} na IDE.${NC}\n`
+  );
   return sync.errors.length || moveErrors.length || staleErrors.length ? 1 : 0;
 }