jarvis-ai-framework 6.0.0 → 7.0.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

package/README.md

@@ -184,10 +184,10 @@ Escolha **Upgrade (C)** — adiciona chaves novas do template sem apagar os valo
 |-------|------------|
 | `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…) |
+| `jarvis init` (ou postinstall com lock) | 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 |
 |-------|-----------|------|
@@ -253,6 +253,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` (sem a CLI do host (`gh`), sem login ou sem rede, o 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/eng.docs-consolidator.agent.md

@@ -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.
@@ -42,7 +42,7 @@ Por isso o texto tem de ser **completo, autossuficiente e sem ambiguidade**.
 
 1. `architecture.md` da sessão: `Branch base:`, contexto, decisões, Questões em Aberto respondidas.
 2. `plan.md` da sessão: fases e comentários (mudanças de direção).
-3. Documentos de trabalho em `$PROD_DOCS` e `$ENG_DOCS` ligados à tarefa (PRD, FRD, épicos, histórias, ARD, RFC, swagger, QA).
+3. Documentos de trabalho em `$PROD_DOCS` e `$ENG_DOCS` ligados à tarefa (PRD, FRD, épicos, histórias, ARD, RFC, SPEC, swagger, QA).
 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.

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

@@ -16,19 +16,22 @@ bin/
     ├── 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
-    │   ├── validate-frontmatter.js  # Valida/extrai frontmatter (PRD, FRD, épico, história, tarefa, ARD, RFC)
+    │   ├── validate-frontmatter.js  # Valida/extrai frontmatter (feature, delivery e documentos de trabalho: PRD, FRD, épico, história, tarefa, ARD, RFC, QA)
     │   ├── 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`, `tokens.js`, `qa-signoff.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,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { createInterface } from "node:readline";
 import { syncAssets } from "../lib/core/sync-engine.js";
@@ -22,18 +22,44 @@ import {
   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);
 
@@ -154,20 +180,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}`);
@@ -245,6 +267,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;
@@ -281,6 +328,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 +438,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;
 }

package/bin/lib/cli/program.js

@@ -196,15 +196,17 @@ export function buildProgram() {
     .option("--env-file <path>")
     .action((options) => dailyReport(toLegacyFlags(options)));
 
-  const vcs = cmd(program, "vcs").description("Adapters de Git host (GitLab/GitHub/Bitbucket)");
+  const vcs = cmd(program, "vcs").description("Git host pela CLI oficial (gh, glab)");
 
   cmd(vcs, "create-merge")
-    .description("Abrir um MR/PR")
+    .description("Abrir um MR/PR (gh pr create / glab mr create)")
     .option("--source <branch>")
     .option("--target <branch>")
     .option("--title <titulo>")
     .option("--body-file <path>")
     .option("--repo <url>", "Padrão: git remote get-url origin")
+    .option("--ide <ide>", "IDE do ENV.md (quando há mais de um no workspace)")
+    .option("--env-file <path>", "Path explícito do ENV.md")
     .action((options) =>
       runCreateMerge({
         source: options.source,
@@ -212,12 +214,14 @@ export function buildProgram() {
         title: options.title,
         bodyFile: options.bodyFile,
         repo: options.repo,
+        ide: options.ide,
+        envFile: options.envFile,
       })
     );
 
   cmd(vcs, "create-issue")
-    .description("Abrir uma issue")
-    .option("--repo <url-ou-path>")
+    .description("Abrir uma issue (gh issue create / glab issue create)")
+    .option("--repo <url>", "URL completa do repositório")
     .option("--title <titulo>")
     .option("--body-file <path>")
     .option("--label <labels>", "Labels separadas por vírgula (padrão: bug)")
@@ -230,13 +234,24 @@ export function buildProgram() {
       })
     );
 
-  const tasks = cmd(program, "tasks").description("Adapters de task manager");
+  const tasks = cmd(program, "tasks").description(
+    "Board de cards pela CLI oficial (gh, glab, acli)"
+  );
 
   cmd(tasks, "comment")
-    .description("Comentar num card (Jira/Linear/GitHub/Asana — lê TASK_MANAGER do ENV.md)")
+    .description("Comentar num card (Jira, GitHub, GitLab — lê TASK_MANAGER do ambiente)")
     .argument("[card-key]")
     .argument("[message...]", "Texto do comentário (pode ter espaços)")
-    .action((cardKey, messageParts) => runComment(cardKey, messageParts.join(" ")));
+    .option("--body-file <path>", "Lê o texto do comentário de um arquivo")
+    .option("--ide <ide>", "IDE do ENV.md (quando há mais de um no workspace)")
+    .option("--env-file <path>", "Path explícito do ENV.md")
+    .action((cardKey, messageParts, options) =>
+      runComment(cardKey, messageParts.join(" "), {
+        bodyFile: options.bodyFile,
+        ide: options.ide,
+        envFile: options.envFile,
+      })
+    );
 
   return program;
 }

package/bin/lib/config/ide-config.js

@@ -22,6 +22,18 @@ export const STEERING_FOLDER = "steering";
  * @property {string} workflowsFolder - Nome da pasta para workflows/commands
  * @property {string} [folderName] - Nome real da pasta no filesystem (sem o ponto). Defaults para value.
  * @property {string} [icon] - Emoji/ícone da IDE (opcional)
+ * @property {ReadonlyArray<MCPTarget>} mcp - Onde a IDE lê a configuração de MCP
+ * @property {string} mcpNote - O que falta para o servidor ficar ativo depois de gravado
+ */
+
+/**
+ * Arquivo de MCP que a IDE lê. Fonte: documentação oficial de cada IDE (conferida em 2026-10).
+ * @typedef {Object} MCPTarget
+ * @property {string} path - Relativo ao workspace; com `~/`, é da pasta do usuário (global)
+ * @property {"json"|"toml"} format
+ * @property {"mcpServers"|"mcp"|"mcp_servers"} key - Chave raiz dos servidores
+ * @property {"stdio"|"opencode"|"plain"} style - Formato do item do servidor
+ * @property {boolean} [global] - Só existe config global: o init não grava, só orienta
  */
 
 /**
@@ -35,6 +47,24 @@ export const IDES = Object.freeze([
     supported: true,
     workflowsFolder: DEFAULT_WORKFLOWS_FOLDER,
     icon: "🤖",
+    mcp: [
+      {
+        path: "~/.config/devin/mcp_config.json",
+        format: "json",
+        key: "mcpServers",
+        style: "plain",
+        global: true,
+      },
+      {
+        path: "~/.codeium/windsurf/mcp_config.json",
+        format: "json",
+        key: "mcpServers",
+        style: "plain",
+        global: true,
+      },
+    ],
+    mcpNote:
+      "A Windsurf só tem config global de MCP: inclua o servidor no arquivo indicado e ative-o no painel MCP do Cascade.",
   },
   {
     name: "Claude Code",
@@ -42,6 +72,8 @@ export const IDES = Object.freeze([
     supported: true,
     workflowsFolder: COMMANDS_FOLDER,
     icon: "🔌",
+    mcp: [{ path: ".mcp.json", format: "json", key: "mcpServers", style: "stdio" }],
+    mcpNote: "Reinicie o Claude Code e aprove o servidor do .mcp.json quando ele perguntar.",
   },
   {
     name: "Cursor",
@@ -49,6 +81,8 @@ export const IDES = Object.freeze([
     supported: true,
     workflowsFolder: COMMANDS_FOLDER,
     icon: "💻",
+    mcp: [{ path: ".cursor/mcp.json", format: "json", key: "mcpServers", style: "plain" }],
+    mcpNote: "Recarregue o Cursor; o servidor aparece em Settings → MCP.",
   },
   {
     name: "Codex (OpenAI)",
@@ -56,6 +90,9 @@ export const IDES = Object.freeze([
     supported: true,
     workflowsFolder: DEFAULT_WORKFLOWS_FOLDER,
     icon: "🔮",
+    mcp: [{ path: ".codex/config.toml", format: "toml", key: "mcp_servers", style: "plain" }],
+    mcpNote:
+      "O Codex só lê o .codex/config.toml de projetos confiáveis (trusted): confie no projeto e reinicie o Codex.",
   },
   {
     name: "OpenCode",
@@ -63,6 +100,8 @@ export const IDES = Object.freeze([
     supported: true,
     workflowsFolder: COMMANDS_FOLDER,
     icon: "⚡",
+    mcp: [{ path: "opencode.json", format: "json", key: "mcp", style: "opencode" }],
+    mcpNote: "Reinicie o OpenCode para carregar o servidor do opencode.json.",
   },
   {
     name: "Gemini CLI / Antigravity (Google)",
@@ -71,6 +110,12 @@ export const IDES = Object.freeze([
     supported: true,
     workflowsFolder: DEFAULT_WORKFLOWS_FOLDER,
     icon: "🌐",
+    mcp: [
+      { path: ".gemini/settings.json", format: "json", key: "mcpServers", style: "plain" },
+      { path: ".agents/mcp_config.json", format: "json", key: "mcpServers", style: "plain" },
+    ],
+    mcpNote:
+      "Gemini CLI: confie na pasta (gemini trust) e reinicie. Antigravity: use Refresh em Customizations (ou /mcp no CLI).",
   },
   {
     name: "Kiro (AWS)",
@@ -78,6 +123,8 @@ export const IDES = Object.freeze([
     supported: true,
     workflowsFolder: STEERING_FOLDER,
     icon: "☁️",
+    mcp: [{ path: ".kiro/settings/mcp.json", format: "json", key: "mcpServers", style: "plain" }],
+    mcpNote: "O Kiro reconecta os servidores ao salvar o arquivo; confira no painel MCP.",
   },
 ]);
 
@@ -220,6 +267,15 @@ export function getWorkflowsFolder(ideValue) {
   return config?.workflowsFolder || DEFAULT_WORKFLOWS_FOLDER;
 }
 
+/**
+ * Arquivos de MCP da IDE (lista vazia para IDE desconhecida)
+ * @param {string} ideValue - Slug da IDE
+ * @returns {ReadonlyArray<MCPTarget>}
+ */
+export function getMCPTargets(ideValue) {
+  return getIDEConfig(ideValue)?.mcp || [];
+}
+
 /**
  * Limpa o cache (útil para testes)
  * @private

package/bin/lib/core/docs-migrate.js

@@ -15,6 +15,7 @@ import {
 } from "node:fs";
 import { join, resolve, relative, dirname, basename, isAbsolute, sep } from "node:path";
 import { execFileSync } from "node:child_process";
+import { rootIsRepo } from "./workspace-mode.js";
 
 const ENG_SUBDIRS = ["ARD", "RFC", "qa", "swagger", "openapi", "robots", "c4"];
 const LEGACY_ENG_SUBDIRS = ["robots", "swagger", "openapi", "c4"];
@@ -164,7 +165,8 @@ function emptyDirsUnder(dirAbs) {
 
 /**
  * Aplica o plano: `git mv` se o arquivo é versionado, senão `rename`. Remove as pastas
- * antigas só se ficarem vazias e garante `{JARVIS_DOCS}/` no `.gitignore` do workspace.
+ * antigas só se ficarem vazias e, se a raiz for um repositório, garante `{JARVIS_DOCS}/` no
+ * `.gitignore` (raiz não versionada, como no modo workspace, não tem o `.gitignore` tocado).
  * @returns {{ moved: {from: string, to: string, discovery: boolean}[], errors: string[] }}
  */
 export function applyDocsMigration(workspaceDir, plan, env) {
@@ -194,16 +196,26 @@ export function applyDocsMigration(workspaceDir, plan, env) {
     removeEmptyDirs(dirname(srcAbs), docsAbs);
   }
 
-  if (moved.length > 0) ensureGitignore(workspaceDir, `${docsFolders(env).jarvis}/`);
+  if (moved.length > 0 && rootIsRepo(workspaceDir)) {
+    ensureGitignore(workspaceDir, `${docsFolders(env).jarvis}/`);
+  }
   return { moved, errors };
 }
 
-function ensureGitignore(workspaceDir, line) {
+/**
+ * Garante `line` no `.gitignore` de `workspaceDir` (cria o arquivo se faltar). Reconhece a
+ * linha com e sem a barra final, com a barra inicial e com `/*` ou `/**` (`docs/jarvis/`,
+ * `docs/jarvis`, `/docs/jarvis/`, `docs/jarvis/**`). Acrescenta com a quebra de linha do arquivo.
+ * Quem chama decide se a raiz é versionada (`rootIsRepo`).
+ */
+export function ensureGitignore(workspaceDir, line) {
   const p = join(workspaceDir, ".gitignore");
   const text = existsSync(p) ? readFileSync(p, "utf-8") : "";
   const bare = line.replace(/\/$/, "");
-  if (text.split("\n").some((l) => [line, bare, `/${line}`, `/${bare}`].includes(l.trim()))) return;
-  appendFileSync(p, `${text && !text.endsWith("\n") ? "\n" : ""}${line}\n`);
+  const forms = [bare, `${bare}/`, `${bare}/*`, `${bare}/**`].flatMap((f) => [f, `/${f}`]);
+  if (text.split(/\r?\n/).some((l) => forms.includes(l.trim()))) return;
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  appendFileSync(p, `${text && !text.endsWith("\n") ? eol : ""}${line}${eol}`);
 }
 
 /**