spec-first-copilot 0.5.0-beta.0 → 0.5.0-beta.10

package/README.md

@@ -77,11 +77,17 @@ MeuProjeto/
 │   ├── domain.md                     <- Visao de negocio + modelo de dados
 │   ├── conventions.md                <- Auth, authz, LGPD, env vars, monitoramento
 │   ├── apiContracts.md               <- Rotas, paginacao, erros, catalogo de endpoints
-│   └── decisions.md                  <- ADRs
-├── workspace/                       <- TEAM CONTENT (futuro wiki)
+│   ├── decisions.md                  <- ADRs
+│   └── specs/                        <- Especs por feature (projecoes do SDD, pro agent)
+│       └── {nome}/
+│           ├── brief.md              <- Problema/Solucao
+│           ├── contracts.md          <- Dados/API/Integracoes
+│           ├── scenarios.md          <- Fluxos/UI/CAs
+│           └── tasks.md              <- Tabela unica com coluna Area
+├── workspace/                        <- TEAM CONTENT (futuro wiki)
 │   ├── Input/                        <- Jogue seus insumos aqui
 │   │   └── setup_projeto/            <- Insumos do bootstrap
-│   └── Output/                       <- Docs por feature (gerados)
+│   └── Output/                       <- Docs narrativos pro humano (PRD, TRD, SDD, Progresso)
 └── .gitignore
 ```
 

package/bin/cli.js

@@ -2,26 +2,35 @@
 
 const path = require('path');
 const { init } = require('../lib/init');
+const { update } = require('../lib/update');
 
 const args = process.argv.slice(2);
 const command = args[0];
 
 function printUsage() {
-  console.log('Usage: spec-first-copilot init --name=<project-name> [--target=<path>]');
+  console.log('Usage:');
+  console.log('  spec-first-copilot init --name=<project-name> [--target=<path>]');
+  console.log('  spec-first-copilot update [--target=<path>] [--force]');
   console.log('');
-  console.log('Creates a new spec-first project configured for GitHub Copilot.');
+  console.log('Commands:');
+  console.log('  init     Create a new spec-first project');
+  console.log('  update   Update an existing project with new framework files');
+  console.log('           (adds missing files, updates framework files like skills/adapters/agents)');
   console.log('');
   console.log('Options:');
-  console.log('  --name=<name>    Project name (required)');
-  console.log('  --target=<path>  Target directory (defaults to ./<name>)');
+  console.log('  --name=<name>    Project name (required for init)');
+  console.log('  --target=<path>  Target directory (defaults to ./<name> for init, cwd for update)');
+  console.log('  --force          Force update all files, not just framework files (use with caution)');
 }
 
 function parseArgs(args) {
-  const parsed = {};
+  const parsed = { flags: [] };
   for (const arg of args) {
     const match = arg.match(/^--(\w+)=(.+)$/);
     if (match) {
       parsed[match[1]] = match[2];
+    } else if (arg.startsWith('--')) {
+      parsed.flags.push(arg.slice(2));
     }
   }
   return parsed;
@@ -43,6 +52,15 @@ if (command === 'init') {
     templatesDir,
     targetDir: opts.target || undefined,
   });
+} else if (command === 'update') {
+  const opts = parseArgs(args.slice(1));
+  const templatesDir = path.join(__dirname, '..', 'templates');
+
+  update({
+    templatesDir,
+    targetDir: opts.target || undefined,
+    force: opts.flags.includes('force'),
+  });
 } else {
   printUsage();
   if (command) {

package/lib/init.js

@@ -62,8 +62,8 @@ function init({ name, templatesDir, targetDir }) {
   console.log(`\nDone! Project "${name}" is ready.`);
   console.log('\nNext steps:');
   console.log(`  1. cd ${name}`);
-  console.log('  2. Add your input files to workspace/Input/setup_projeto/');
-  console.log('  3. Run /sf-setup-projeto to start the pipeline');
+  console.log('  2. Create a folder in workspace/Input/ with your project files (e.g. workspace/Input/my_app/)');
+  console.log('  3. Run /sf-new-project <folder-name> to start the pipeline');
   console.log('');
 }
 

package/lib/update.js

@@ -0,0 +1,130 @@
+const fs = require('fs');
+const path = require('path');
+
+const FRAMEWORK_DIRS = [
+  path.join('.github', 'adapters'),
+  path.join('.github', 'skills'),
+  path.join('.github', 'agents'),
+  path.join('.github', 'templates'),
+  path.join('.github', 'instructions'),
+];
+
+const FRAMEWORK_FILES = [
+  path.join('.github', 'rules.md'),
+  path.join('.github', 'copilot-instructions.md'),
+  path.join('.github', 'CHANGELOG.md'),
+  'sfw.config.yml.example',
+];
+
+function update({ templatesDir, targetDir, force }) {
+  const dest = targetDir || process.cwd();
+
+  if (!fs.existsSync(dest)) {
+    console.error(`Error: directory "${dest}" does not exist.`);
+    console.error('Run "spec-first-copilot init --name=<name>" first to create a project.');
+    process.exit(1);
+  }
+
+  const githubDir = path.join(dest, '.github');
+  if (!fs.existsSync(githubDir)) {
+    console.error('Error: not a spec-first project (missing .github/ directory).');
+    console.error('Run "spec-first-copilot init --name=<name>" first.');
+    process.exit(1);
+  }
+
+  console.log(`\nUpdating project in ${dest}\n`);
+
+  const stats = { added: [], updated: [], skipped: 0 };
+  syncDir(templatesDir, dest, force, stats, dest);
+
+  console.log('');
+  if (stats.added.length > 0) {
+    console.log(`Added (${stats.added.length}):`);
+    for (const f of stats.added) console.log(`  + ${f}`);
+  }
+  if (stats.updated.length > 0) {
+    console.log(`Updated (${stats.updated.length}):`);
+    for (const f of stats.updated) console.log(`  ~ ${f}`);
+  }
+  if (stats.added.length === 0 && stats.updated.length === 0) {
+    console.log('Already up to date — no new files to add.');
+  } else {
+    console.log(`\n${stats.added.length} added, ${stats.updated.length} updated, ${stats.skipped} unchanged`);
+  }
+  console.log('');
+}
+
+function syncDir(src, dest, force, stats, root) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      syncDir(srcPath, destPath, force, stats, root);
+    } else {
+      syncFile(srcPath, destPath, force, stats, root);
+    }
+  }
+}
+
+function syncFile(src, dest, force, stats, root) {
+  const rel = path.relative(root, dest);
+  const exists = fs.existsSync(dest);
+
+  if (exists && !force) {
+    const isFramework = isFrameworkPath(rel);
+    if (!isFramework) {
+      stats.skipped++;
+      return;
+    }
+    const srcContent = fs.readFileSync(src, 'utf-8');
+    const destContent = fs.readFileSync(dest, 'utf-8');
+    if (srcContent === destContent) {
+      stats.skipped++;
+      return;
+    }
+    fs.writeFileSync(dest, srcContent, 'utf-8');
+    stats.updated.push(rel);
+    return;
+  }
+
+  if (exists && force) {
+    const srcContent = fs.readFileSync(src, 'utf-8');
+    const destContent = fs.readFileSync(dest, 'utf-8');
+    if (srcContent === destContent) {
+      stats.skipped++;
+      return;
+    }
+    fs.writeFileSync(dest, srcContent, 'utf-8');
+    stats.updated.push(rel);
+    return;
+  }
+
+  const textExtensions = ['.md', '.yaml', '.yml', '.json', '.js', '.ts', '.gitignore', '.gitkeep', ''];
+  const ext = path.extname(src).toLowerCase();
+  const basename = path.basename(src);
+  const isText = textExtensions.includes(ext) || basename.startsWith('.');
+
+  if (isText) {
+    const content = fs.readFileSync(src, 'utf-8');
+    fs.writeFileSync(dest, content, 'utf-8');
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+  stats.added.push(rel);
+}
+
+function isFrameworkPath(rel) {
+  const normalized = rel.split(path.sep).join('/');
+  for (const dir of FRAMEWORK_DIRS) {
+    const normalizedDir = dir.split(path.sep).join('/');
+    if (normalized.startsWith(normalizedDir + '/')) return true;
+  }
+  for (const file of FRAMEWORK_FILES) {
+    const normalizedFile = file.split(path.sep).join('/');
+    if (normalized === normalizedFile) return true;
+  }
+  return false;
+}
+
+module.exports = { update };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.5.0-beta.0",
+  "version": "0.5.0-beta.10",
   "description": "Spec-first workflow kit for GitHub Copilot — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-copilot": "bin/cli.js"

package/templates/.github/CHANGELOG.md

@@ -0,0 +1,112 @@
+# SFW Changelog — spec-first-copilot
+
+> Este arquivo é atualizado automaticamente pelo `spec-first-copilot update`.
+> O agent deve ler este arquivo quando o usuário perguntar sobre mudanças,
+> funcionalidades novas, ou o que está disponível no framework.
+>
+> **Não editar manualmente** — será sobrescrito no próximo update.
+
+---
+
+## 0.5.0-beta.7 (2026-04-12)
+
+### Novo: Comando `/sf-load <nome>`
+Puxa insumos do backend configurado (Confluence ou filesystem) para `workspace/Input/{nome}/`.
+- Busca o scope pelo nome no backend (match exato)
+- Desce recursivamente na árvore (Confluence `get_page_children` é apenas direto — `/sf-load` faz loop)
+- Baixa conteúdo + attachments
+- Log incremental em `.ai/sf-load-log.md` (NOVO/MODIFICADO/INALTERADO via sha256)
+- Idempotente — rodar N vezes sem mudanças no backend não altera nada
+- Referência: `.github/commands/sf-load.md`
+
+### Novo: Adapter layer (Confluence + Filesystem)
+Pipeline agora é backend-agnóstico via adapters plugáveis.
+- **ConfluenceAdapter** — fala com Confluence via MCP `sooperset/mcp-atlassian`
+- **FilesystemAdapter** — lê/escreve direto no disco (também serve como mock pra testes)
+- Configurado em `sfw.config.yml` (copiar de `sfw.config.yml.example`)
+- Interface: `.github/adapters/interface.md` (7 métodos)
+- Erros tipados: `.github/adapters/errors.md` (6 classes)
+- Naming engine: `.github/adapters/naming.md` (placeholders `{scope}`, `{type}`)
+- Registry: `.github/adapters/registry.md`
+- Setup guide: `.github/adapters/SETUP.md` (passo a passo de MCP + Confluence)
+
+### Novo: `sfw.config.yml`
+Manifesto do projeto que define de onde vêm e pra onde vão os artefatos.
+- `input.adapter` — de onde puxar insumos (`confluence` ou `filesystem`)
+- `output.targets[].mode` — ligar/desligar publish (`auto`, `manual`, `off`)
+- `naming.output_container` — template do nome da subpasta no Output (ex: `out_{scope}`)
+- `naming.output_artifact` — template do nome do artefato (ex: `{scope} - {type}`)
+- Copiar `sfw.config.yml.example` e preencher. Zero segredos neste arquivo.
+
+### Novo: `SETUP.md` — Guia de configuração
+Guia passo a passo em `.github/adapters/SETUP.md`:
+- Setup Confluence: uvx, .mcp.json, token Atlassian, space key, page IDs
+- Setup 100% local (filesystem, zero dependências)
+- Como ligar/desligar Confluence via `mode: auto|manual|off`
+- Troubleshooting: tabela com todos os gotchas conhecidos
+- **IMPORTANTE**: Confluence NÃO é CLI. Acesso via MCP tools prefixadas `mcp__atlassian__confluence_*`
+
+### Novo: CLI `update`
+```bash
+npx spec-first-copilot update           # adiciona novos, atualiza framework
+npx spec-first-copilot update --force   # sobrescreve tudo incluindo copilot-instructions.md
+```
+Atualiza projeto existente sem perder arquivos do usuário.
+
+### Breaking: `/sf-setup-projeto` → `/sf-new-project <nome>`
+- Antes: `/sf-setup-projeto` era hardcoded pra pasta `setup_projeto`
+- Agora: `/sf-new-project <nome>` recebe o nome como argumento (simétrico com `/sf-feature <nome>`)
+- `/sf-new-project` gera TRD (bootstrap técnico), `/sf-feature` gera PRD (feature)
+- **Não existe mais pasta mágica** — usuário nomeia livremente em `workspace/Input/`
+- O antigo `setup-projeto.md` foi removido. Usar `new-project.md`
+
+### Breaking: `{sequence}` removido
+- Antes: todo item tinha prefixo numérico `001 - ` pra unicidade no Confluence
+- Agora: usuário nomeia livremente, agent segue o nome do Input
+- Naming simplificado: só `{scope}` e `{type}` como placeholders
+- Premissa: 1 space Confluence = 1 projeto (multi-projeto no mesmo space requer nomes únicos no Input)
+
+### Breaking: Output agrupado por scope
+- Antes: artefatos flat no Output (ex: `001 - TRD setup_projeto`)
+- Agora: subpasta por scope (ex: `out_app_barbearia/app_barbearia - TRD`)
+- Container configurável via `naming.output_container` (default: `out_{scope}`)
+- Artifact configurável via `naming.output_artifact` (default: `{scope} - {type}`)
+
+---
+
+## 0.5.0-beta.2 (2026-04-11)
+
+### Refactor: `docs/specs/` → `specs/` (top-level)
+- Projeções do SDD (brief, contracts, scenarios, tasks) movidas pra raiz
+- Regra: humano lê `workspace/Output/`, agent lê `specs/`
+
+### Refactor: 3-zone separation
+- `.github/` = AI config (rules, templates, commands, agents)
+- `docs/` = system knowledge (5 docs de sistema)
+- `workspace/` = team content (Input/ + Output/)
+
+---
+
+## 0.4.0 (2026-04-10) — v1 stable
+
+### Funcionalidades base
+- 9 commands: setup-projeto, feature, discovery, extract, design, plan, dev, merge-delta, session-finish
+- 7 agents: backend-coder, frontend-coder, db-coder, infra-coder, doc-writer, reviewer, security-reviewer
+- Templates: PRD, TRD, SDD, tasks, Progresso, context, extract-log, backlog, projetos.yaml
+- Templates de estrutura: architecture, domain, conventions, apiContracts, decisions
+- Pipeline: extract → design → plan → dev com checkpoints de aprovação
+- Delta Specs (SDD §11) + merge-delta automático
+- Security Reviewer como gate pós-dev
+- Multi-repo via projetos.yaml
+- Entregáveis contínuos (fases de entrega)
+
+---
+
+## Como usar este arquivo
+
+Se o usuário perguntar:
+- **"O que tem de novo?"** → ler a versão mais recente acima
+- **"Como uso o /sf-load?"** → apontar pra `.github/commands/sf-load.md`
+- **"Como configuro Confluence?"** → apontar pra `.github/adapters/SETUP.md`
+- **"O que é adapter?"** → apontar pra `.github/adapters/interface.md`
+- **"O que mudou de setup-projeto?"** → seção "Breaking" do 0.5.0-beta.7

package/templates/.github/adapters/SETUP.md

@@ -0,0 +1,314 @@
+# Adapter Setup Guide
+
+> Guia passo a passo para configurar os adapters do SFW.
+> Se o usuário pedir ajuda pra configurar, siga este guia.
+
+---
+
+## Escolha seu modo de trabalho
+
+O SFW funciona em **3 modos**, configurados no `sfw.config.yml`:
+
+| Modo | Input | Output | Quando usar |
+|------|-------|--------|-------------|
+| **Full Confluence** | `adapter: confluence` | `mode: auto` | Time usa Confluence, PM publica lá, quer artefatos lá |
+| **Confluence só leitura** | `adapter: confluence` | `mode: off` | PM publica no Confluence, mas artefatos ficam só local |
+| **100% local** | `adapter: filesystem` | `mode: off` | Time sem Confluence, tudo no disco |
+
+Para mudar: edite `sfw.config.yml` e ajuste `input.adapter` e `output.targets[].mode`.
+
+---
+
+## Setup 1: Confluence (Full ou só leitura)
+
+### Pré-requisitos
+
+- Python 3.10+ instalado
+- Conta Atlassian com acesso ao Confluence Cloud
+- Claude Code instalado
+
+### Passo 1 — Instalar uvx
+
+`uvx` é o runtime que executa o MCP server do Confluence.
+
+```bash
+# Windows (PowerShell)
+pip install uv
+
+# Mac/Linux
+pip install uv
+# ou
+brew install uv
+```
+
+Verificar:
+```bash
+uvx --version
+```
+
+### Passo 2 — Gerar API Token Atlassian
+
+1. Acesse: https://id.atlassian.com/manage-profile/security/api-tokens
+2. Clique **Create API token**
+3. Nome: `sfw-mcp` (ou qualquer nome descritivo)
+4. Copie o token gerado — **ele só aparece uma vez**
+
+Você vai precisar de:
+- **Email**: seu email da conta Atlassian (ex: `dev@empresa.com`)
+- **Token**: o token que acabou de copiar
+- **URL do Confluence**: geralmente `https://sua-empresa.atlassian.net/wiki`
+
+### Passo 3 — Criar `.mcp.json`
+
+Crie o arquivo `.mcp.json` na **raiz do projeto** (onde está o `sfw.config.yml`).
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "uvx",
+      "args": ["mcp-atlassian"],
+      "env": {
+        "CONFLUENCE_URL": "https://sua-empresa.atlassian.net/wiki",
+        "CONFLUENCE_USERNAME": "seu-email@empresa.com",
+        "CONFLUENCE_API_TOKEN": "seu-token-aqui"
+      }
+    }
+  }
+}
+```
+
+**IMPORTANTE — Gotchas aprendidos na prática:**
+
+1. **Credenciais HARDCODED no arquivo** — `${VAR}` com variáveis de ambiente **NÃO funciona** no startup do Claude Code. Coloque os valores direto.
+
+2. **`.mcp.json` DEVE estar no `.gitignore`** — tem credenciais. O template do kit já inclui isso, mas verifique:
+   ```
+   # .gitignore
+   .mcp.json
+   ```
+
+3. **Após criar/editar `.mcp.json`, REINICIE o Claude Code** — servers MCP só são carregados no startup. Mudança no arquivo não tem efeito em sessão ativa.
+
+4. **Primeira execução baixa ~118 dependências** — o pacote `mcp-atlassian` é pesado. A primeira vez pode demorar 1-2 minutos. As seguintes são instantâneas.
+
+### Passo 4 — Descobrir seu Space Key
+
+O Space Key é o identificador curto do espaço Confluence (ex: `ST`, `DEV`, `PROJ`).
+
+Para encontrar:
+- Abra qualquer página do seu espaço Confluence
+- Olhe a URL: `https://empresa.atlassian.net/wiki/spaces/ST/pages/...`
+- O `ST` é o Space Key
+
+### Passo 5 — Criar estrutura no Confluence
+
+Crie manualmente no Confluence (ou peça pro PM criar):
+
+```
+{Seu Space}
+└── {Nome do Projeto}          ← page raiz do projeto
+    ├── Input                  ← PM coloca insumos aqui
+    │   └── (scopes como pages filhas)
+    └── Output                 ← agent publica aqui (não editar manualmente)
+```
+
+Anote os **Page IDs** de `Input` e `Output`:
+- Abra a page → ... (menu) → Page information → o ID está na URL
+- Ou: URL da page contém `/pages/123456/...` — o número é o Page ID
+
+### Passo 6 — Configurar `sfw.config.yml`
+
+Copie o `sfw.config.yml.example` pra `sfw.config.yml` e preencha:
+
+```yaml
+project:
+  name: "Meu Projeto"
+
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{scope} - {type}"
+
+input:
+  adapter: confluence
+  config:
+    space_key: "ST"                    # ← seu Space Key
+    parent_page_id: "360668"           # ← Page ID da page Input
+    recursive: true
+    include_attachments: true
+  cache:
+    local_dir: "workspace/Input/"
+    log: ".ai/load-log.md"
+    incremental: true
+
+output:
+  targets:
+    - name: confluence-mirror
+      adapter: confluence
+      config:
+        space_key: "ST"                # ← mesmo Space Key
+        parent_page_id: "294931"       # ← Page ID da page Output
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto                       # ← auto | manual | off
+      conflict_detection: version
+      approval_mechanism: label
+      approval_label: "sfw-approved"
+```
+
+### Passo 7 — Testar a conexão
+
+Após reiniciar o Claude Code com o `.mcp.json` configurado, peça ao agent:
+
+```
+Teste a conexão com o Confluence: liste as páginas filhas da page {Page ID do Input}
+```
+
+**IMPORTANTE — Como o Confluence funciona no Claude Code:**
+
+O Confluence **NÃO é um comando de terminal**. Não existe `confluence` como CLI.
+O acesso é feito via **MCP tools** — funções que o Claude Code expõe automaticamente
+quando o server MCP está configurado no `.mcp.json`.
+
+As tools disponíveis são prefixadas com `mcp__atlassian__confluence_`:
+
+| Tool MCP | O que faz |
+|----------|-----------|
+| `mcp__atlassian__confluence_get_page` | Lê conteúdo de uma page por ID |
+| `mcp__atlassian__confluence_get_page_children` | Lista filhos diretos de uma page |
+| `mcp__atlassian__confluence_create_page` | Cria page nova |
+| `mcp__atlassian__confluence_update_page` | Atualiza conteúdo de page existente |
+| `mcp__atlassian__confluence_search` | Busca por texto no space |
+| `mcp__atlassian__confluence_get_labels` | Lê labels de uma page |
+| `mcp__atlassian__confluence_get_attachments` | Lista attachments de uma page |
+| `mcp__atlassian__confluence_download_attachment` | Baixa attachment |
+
+O agent chama essas tools diretamente — **nunca via bash/terminal**.
+Se o agent tentar rodar `confluence ...` no terminal, está errado.
+
+**Como verificar que o MCP está funcionando:**
+1. Reinicie o Claude Code após criar/editar `.mcp.json`
+2. Peça ao agent: "Use a tool `mcp__atlassian__confluence_get_page` com page_id {ID}" 
+3. Se funcionar, está conectado. Se der "tool not found", o MCP não subiu — verifique `.mcp.json`
+
+**Nota**: `get_page_children` retorna apenas filhos **diretos** (não recursivo).
+Para trazer toda a árvore, o agent faz loop: chama `get_page_children` em cada
+filho que tem `hasChildren`, empilha e desce. O `/load` já faz isso automaticamente.
+
+---
+
+## Setup 2: 100% Local (sem Confluence)
+
+Nenhuma instalação extra necessária. Não precisa de `.mcp.json`.
+
+### Passo 1 — Configurar `sfw.config.yml`
+
+```yaml
+project:
+  name: "Meu Projeto"
+
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{type}"           # sem {scope} no nome — sem risco de colisão local
+
+input:
+  adapter: filesystem
+  config:
+    root_path: "workspace/Input"
+  cache:
+    local_dir: "workspace/Input/"
+    log: ".ai/load-log.md"
+    incremental: true
+
+output:
+  targets:
+    - name: local
+      adapter: filesystem
+      config:
+        root_path: "workspace/Output"
+      publishes: [PRD, TRD, SDD, Progresso]
+      mode: auto
+      conflict_detection: hash
+      approval_mechanism: none
+```
+
+### Passo 2 — Criar pastas de Input
+
+```bash
+mkdir -p workspace/Input/meu_escopo
+# Adicione seus arquivos de insumo na pasta
+```
+
+Pronto. `/new-project meu_escopo` funciona direto.
+
+---
+
+## Ligar e desligar Confluence (sem mudar nada estrutural)
+
+### Desligar output pro Confluence (manter input)
+
+Mude `mode` no target:
+
+```yaml
+output:
+  targets:
+    - name: confluence-mirror
+      mode: off              # ← era "auto", agora "off"
+```
+
+Pipeline roda normal, artefatos ficam locais. Quando quiser religar, volte pra `auto`.
+
+### Desligar tudo (input + output) — virar 100% local
+
+Mude o adapter do input:
+
+```yaml
+input:
+  adapter: filesystem        # ← era "confluence"
+  config:
+    root_path: "workspace/Input"
+```
+
+E coloque `mode: off` nos targets de Confluence.
+
+### Adicionar Confluence depois (começou local, quer publicar)
+
+1. Siga os passos 1-5 do Setup Confluence
+2. Adicione o target no `sfw.config.yml`:
+   ```yaml
+   output:
+     targets:
+       - name: confluence-mirror
+         adapter: confluence
+         config:
+           space_key: "ST"
+           parent_page_id: "294931"
+         publishes: [PRD, TRD, SDD, Progresso]
+         mode: auto
+   ```
+3. Re-rode `/extract`, `/design`, `/plan` — os artefatos locais serão publicados
+
+---
+
+## Troubleshooting
+
+| Problema | Solução |
+|----------|---------|
+| MCP server não aparece no Claude Code | Reiniciar Claude Code. MCP só carrega no startup |
+| `${VAR}` não resolve no `.mcp.json` | Hardcode as credenciais direto. Variáveis de ambiente não funcionam |
+| "401 Unauthorized" | Verifique email + token no `.mcp.json`. Token pode ter expirado |
+| "403 Forbidden" | Usuário sem permissão no space. Pedir acesso ao admin |
+| "Page not found" (404) | Page ID errado. Confirme o ID via URL da page no Confluence |
+| Primeira execução demora muito | Normal — uvx baixa ~118 deps na primeira vez |
+| `BadRequestException: title already exists` | Title duplicado no space (unique per space no Confluence). Renomear o scope no Input |
+| Edição no `.mcp.json` não faz efeito | Reiniciar Claude Code obrigatório |
+| Content no Confluence parece diferente do local | Markdown roundtrip normaliza (`#`→`===`, `-`→`*`). Normal — version number é fonte de verdade, não bytes |
+
+---
+
+## Referências
+
+- Interface do adapter: `.github/adapters/interface.md`
+- ConfluenceAdapter: `.github/adapters/confluence.md`
+- FilesystemAdapter: `.github/adapters/filesystem.md`
+- Erros: `.github/adapters/errors.md`
+- Naming: `.github/adapters/naming.md`