spec-first-copilot 0.6.0-beta.9 → 0.7.0

package/templates/.github/skills/sf-mcp/SKILL.md

@@ -1,385 +1,386 @@
-# /sf-mcp <provider>
-
-Setup interativo de backend externo. Idempotente — pode rodar múltiplas vezes, só pergunta o que falta.
-
-## Providers disponíveis
-
-| Provider | O que faz |
-|----------|-----------|
-| `confluence` | Configura MCP Atlassian + descobre projeto + cria `sfw.config.yml` + `.mcp.json` + `.gitignore` |
-
-## Uso
-
-```
-/sf-mcp confluence           ← setup ou reconfiguração (idempotente)
-/sf-mcp confluence test      ← só testa conexão
-```
-
-> **Dica**: para evitar o ciclo "abrir VS Code → descobrir que falta uvx ou credenciais →
-> sair, ajustar, reiniciar", há um script opcional que prepara o ambiente antes:
->
-> ```bash
-> node .github/scripts/bootstrap-confluence.js
-> ```
->
-> Ele valida `uvx`, coleta credenciais, gera `.mcp.json` e pré-cacheia o MCP. Depois
-> você abre o Copilot Chat e `/sf-mcp confluence` só descobre a árvore do projeto. Uso
-> opcional — `/sf-mcp confluence` sozinho também cobre esses passos, mas demanda reiniciar
-> o VS Code após gerar `.mcp.json` (MCPs só sobem no startup).
-
----
-
-## Provider: Confluence
-
-### Passo 1 — Detectar estado atual
-
-Ler os 2 arquivos âncora:
-
-| Arquivo | O que extrair | Se ausente |
-|---------|---------------|------------|
-| `sfw.config.yml` | `project.root_page_id`, `project.name`, credenciais do space (`space_key`) | marcar como "falta config" |
-| `.mcp.json` | entry `mcpServers.atlassian` com `CONFLUENCE_URL`, `CONFLUENCE_USERNAME`, `CONFLUENCE_API_TOKEN` | marcar como "falta credenciais" |
-
-Calcular `state`:
-- **COMPLETO** — `sfw.config.yml` tem `root_page_id` E `.mcp.json` tem credenciais → ir pro Passo 2
-- **INCOMPLETO** — algo falta → ir pro Passo 3
-
-### Passo 2 — Estado COMPLETO: validar conexão
-
-Testar:
-```
-mcp__atlassian__confluence_get_page(page_id={root_page_id})
-```
-
-| Resultado | Ação |
-|-----------|------|
-| 200 OK | → Passo 4 (remapear árvore, reconfirmar Input/Output) |
-| 401 Unauthorized | Credencial expirou. Perguntar novo token, atualizar `.mcp.json`, avisar pra reiniciar Claude Code, PARAR |
-| 404 Not Found | `root_page_id` inválido. Perguntar novo ID, atualizar `sfw.config.yml`, retry teste |
-| MCP não responde | `.mcp.json` foi atualizado mas Claude não recarregou. Avisar pra reiniciar Claude Code, PARAR |
-| Network error | Mostrar erro, instruir troubleshooting (`.github/adapters/SETUP.md`) |
-
-### Passo 3 — Estado INCOMPLETO: coletar o que falta
-
-#### 3.1 Verificar `uvx`
-
-```bash
-uvx --version
-```
-
-Se não instalado:
-```
-uvx não encontrado. Instale com:
-  pip install uv
-
-Depois rode /sf-mcp confluence novamente.
-```
-**PARAR**.
-
-#### 3.2 Se FALTA credenciais (`.mcp.json` ausente ou incompleto)
-
-Perguntar uma por uma. Pra cada item, mostrar ao user exatamente ONDE achar:
-```
-Configurando acesso ao Confluence.
-
-1. URL do Confluence
-   Abra o Confluence no browser. A URL base é algo como:
-   https://sua-empresa.atlassian.net/wiki
-   Cole essa URL (com /wiki no final):
-   >
-
-2. Email da conta Atlassian
-   É o email que você usa pra logar no Atlassian (não é o token).
-   >
-
-3. API Token
-   Token é diferente de senha. Gere um novo:
-   a) Abra https://id.atlassian.com/manage-profile/security/api-tokens
-   b) Clique "Create API token"
-   c) Dê um nome (ex: "sfw-mcp")
-   d) Copie o token que aparece — ele só aparece UMA VEZ
-   Cole aqui:
-   >
-
-4. Space Key
-   É o código CURTO do seu espaço Confluence (geralmente 2-4 letras maiúsculas).
-   Abra qualquer page do seu espaço. Na URL, você verá:
-   https://...atlassian.net/wiki/spaces/XXX/pages/...
-                                       ^^^
-                                       esse é o Space Key
-   Exemplos comuns: "ST", "DEV", "PROJ", "ENG"
-   Qual é o seu?:
-   >
-```
-
-Criar/atualizar `.mcp.json`:
-```json
-{
-  "mcpServers": {
-    "atlassian": {
-      "command": "uvx",
-      "args": ["mcp-atlassian"],
-      "env": {
-        "CONFLUENCE_URL": "{url}",
-        "CONFLUENCE_USERNAME": "{email}",
-        "CONFLUENCE_API_TOKEN": "{token}"
-      }
-    }
-  }
-}
-```
-
-**IMPORTANTE**: credenciais hardcoded — `${VAR}` NÃO funciona no Claude Code.
-
-Se `.mcp.json` acabou de ser criado/atualizado:
-```
-.mcp.json pronto. Preciso que você reinicie o Claude Code para o MCP carregar.
-
-1. Feche o Claude Code
-2. Abra novamente na mesma pasta
-3. Rode /sf-mcp confluence — vou continuar de onde paramos (credenciais já salvas,
-   só vou pedir o que ainda falta)
-```
-**PARAR**.
-
-#### 3.3 Se FALTA root_page_id (credenciais OK mas config sem root)
-
-Testar conexão básica primeiro:
-```
-mcp__atlassian__confluence_search(query="space.key={space_key}", limit=1)
-```
-
-Se falha → Passo 2 error table (401/MCP não responde/etc).
-Se OK:
-
-```
-Conexão OK.
-
-Qual é a page RAIZ do seu projeto no Confluence?
-(A page-mãe que contém TUDO do projeto — geralmente tem Input e Output como filhas.)
-
-Duas formas de informar:
-
-  A) Page ID (recomendado — mais confiável):
-     Abra a page raiz no Confluence. A URL mostra:
-     https://...atlassian.net/wiki/spaces/ST/pages/65708/Nome-da-Page
-                                                   ^^^^^
-                                                   esse número é o Page ID
-     Cole só o número (ex: 65708).
-
-  B) Título exato:
-     O título que aparece no topo da page. Tem que bater EXATAMENTE
-     (incluindo acentos e maiúsculas/minúsculas).
-
-Page ID ou título:
-  >
-```
-
-Validar:
-```
-mcp__atlassian__confluence_get_page(page_id={resposta})
-```
-- Se 404 e user colou título → usar `confluence_search` pra achar
-- Se 404 e user colou ID → pedir de novo
-- Se OK → seguir
-
-### Passo 4 — Listar filhos diretos do root (NÃO recursivo)
-
-Nesta etapa queremos só o **primeiro nível** da árvore. Pra identificar Input/Output,
-basta saber quais pages estão logo abaixo do root. A árvore profunda vem depois via
-`/sf-load` quando o agent realmente precisa do conteúdo.
-
-```
-mcp__atlassian__confluence_get_page_children(page_id={root_page_id})
-```
-
-**APENAS 1 chamada**. Sem loop recursivo.
-
-Mostrar ao usuário:
-```
-Projeto: "Barbearia Digital" (root_page_id: 65708)
-
-Filhos diretos do root:
-  1. Requisitos (360668)
-  2. Documentação técnica (294931)
-  3. Referências (557057)
-  4. Decisões (425998)
-```
-
-Se algum desses filhos tiver sub-pages (ex: Requisitos contém scopes), isso será descoberto
-pelo `/sf-load` quando rodar. Aqui só precisamos saber quem é Input e quem é Output no nível 1.
-
-### Passo 5 — Identificar Input e Output
-
-**Se já existe config com Input/Output**: mostrar o que está salvo + opção de mudar:
-```
-Config atual:
-  Input:  Requisitos (360668)
-  Output: Documentação técnica (294931)
-
-Manter? (s/n)
-```
-
-Se `s` → pular pro Passo 7.
-Se `n` → continuar perguntando (como se fosse setup novo).
-
-**Se é setup novo**:
-```
-Qual dessas pages contém os INSUMOS (Input, onde PM/PO publica)?
-  1. Requisitos (360668)
-  2. Documentação técnica (294931)
-  3. Referências (557057)
-  4. Decisões (425998)
-  5. Criar nova page "Input" (filha da raiz)
-  >
-```
-
-Opção 1-4: usar o page_id correspondente.
-Opção 5: criar page nova — `mcp__atlassian__confluence_create_page(parent_id={root}, title="Input", content="")`.
-
-Após escolher Input, perguntar Output com as pages **restantes** (remover a escolhida de Input da lista) + opção "Criar nova page 'Output'".
-
-Se escolher "Criar nova" → `mcp__atlassian__confluence_create_page` como filha da raiz.
-
-### Passo 6 — Sugerir context_pages (opcional)
-
-Das pages do nível 1 (filhos diretos do root) que **não** foram escolhidas como Input ou Output,
-sugerir como contexto adicional pro /sf-extract e /sf-design:
-
-```
-Das pages restantes no primeiro nível:
-
-  - "Referências" (557057) → posso consultar durante /sf-extract e /sf-design
-  - "Decisões" (425998) → posso consultar para ADRs no /sf-design
-
-Quer que eu mapeie alguma dessas como contexto adicional? (listar números, ou "não")
-```
-
-Se sim, incluir as escolhidas em `context_pages[]` no `sfw.config.yml`.
-
-Obs: `/sf-load` descobre a árvore profunda sob Input/Output quando rodar. Aqui só tratamos nível 1.
-
-### Passo 7 — Escrever `sfw.config.yml`
-
-Preservar seções existentes (naming, etc) se já havia arquivo. Atualizar/criar:
-
-```yaml
-project:
-  name: "{título da page raiz}"
-  root_page_id: "{page_id raiz}"
-
-naming:
-  output_container: "out_{scope}"
-  output_artifact: "{scope} - {type}"
-
-input:
-  adapter: confluence
-  config:
-    space_key: "{space_key}"
-    parent_page_id: "{page_id do Input}"
-    recursive: true
-    include_attachments: true
-  cache:
-    local_dir: "workspace/Input/"
-    log: ".ai/sf-load-log.md"
-    incremental: true
-
-output:
-  targets:
-    - name: confluence-mirror
-      adapter: confluence
-      config:
-        space_key: "{space_key}"
-        parent_page_id: "{page_id do Output}"
-      publishes: [PRD, SDD, Progresso]
-      mode: auto
-      conflict_detection: version
-      approval_mechanism: label
-      approval_label: "sfw-approved"
-
-# Descomente se tiver selecionado context_pages no Passo 6
-# context_pages:
-#   - id: "557057"
-#     title: "Referências"
-#     use_in: [extract, design]
-```
-
-### Passo 8 — Ajustar `.gitignore`
-
-Adicionar se não existe:
-```
-.mcp.json
-
-# SFW: workspace ignored (external backend detected)
-workspace/Output/**
-!workspace/Output/.gitkeep
-```
-
-### Passo 9 — Resumir
-
-```
-Confluence configurado!
-
-Projeto: {nome} ({root_page_id})
-  Input:  {título Input} ({page_id})
-  Output: {título Output} ({page_id})
-
-Arquivos:
-  .mcp.json          ← credenciais (gitignored)
-  sfw.config.yml     ← configuração do projeto
-  .gitignore         ← atualizado
-
-O projeto tem {N} scopes no Input:
-  - {lista dos filhos do Input}
-
-Próximo passo:
-  /sf-start <nome-do-scope>
-```
-
----
-
-## Subcomando: `/sf-mcp confluence test`
-
-Apenas testa sem modificar arquivos:
-
-1. Verificar que `sfw.config.yml` existe com `project.root_page_id` e `input.config.parent_page_id`
-2. Verificar que `.mcp.json` existe com credenciais
-3. Testar `confluence_get_page(root_page_id)` → root acessível?
-4. Testar `confluence_get_page_children(input.config.parent_page_id)` → listar scopes
-5. Reportar:
-   ```
-   Conexão OK!
-     Root: "{nome}" ({root_page_id})
-     Input: {N} scopes encontrados
-     Output: {M} artefatos publicados anteriormente
-   ```
-6. Se falha: mostrar qual check falhou + link pro troubleshooting
-
----
-
-## Notas
-
-- **`/sf-mcp confluence` é idempotente** — pode rodar N vezes. Só pergunta o que falta baseado em `sfw.config.yml` + `.mcp.json`
-- **`root_page_id` é âncora** — sem ele o framework não sabe os limites do projeto no space
-- `.mcp.json` é SEMPRE gitignored — contém credenciais
-- `sfw.config.yml` é commitável — zero segredos
-- Após criar/atualizar `.mcp.json`, Claude Code PRECISA ser reiniciado
-- O framework conhece o projeto INTEIRO (raiz + toda a árvore), não só Input/Output
-- Token Atlassian pode expirar — se der 401, skill pede novo e atualiza `.mcp.json`
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| uvx não instalado | Parar, instruir instalação |
-| MCP não responde após `.mcp.json` novo | Pedir reinício, retomar depois |
-| `root_page_id` 404 | Pedir ID/título correto, validar |
-| Token expirado (401) | Pedir novo token, atualizar .mcp.json, pedir reinício |
-| Sem permissão de escrita no space | Informar, pedir ao admin |
-| Space key inválido | Listar spaces disponíveis se possível |
-
-## Referências
-
-- Setup guide completo: `.github/adapters/SETUP.md`
-- Confluence adapter: `.github/adapters/confluence.md`
-- Interface do adapter: `.github/adapters/interface.md`
+
+# /sf-mcp <provider>
+
+Setup interativo de backend externo. Idempotente — pode rodar múltiplas vezes, só pergunta o que falta.
+
+## Providers disponíveis
+
+| Provider | O que faz |
+|----------|-----------|
+| `confluence` | Configura MCP Atlassian + descobre projeto + cria `sfw.config.yml` + `.mcp.json` + `.gitignore` |
+
+## Uso
+
+```
+/sf-mcp confluence           ← setup ou reconfiguração (idempotente)
+/sf-mcp confluence test      ← só testa conexão
+```
+
+> **Dica**: para evitar o ciclo "abrir Claude → descobrir que falta uvx ou credenciais →
+> sair, ajustar, reiniciar", há um script opcional que prepara o ambiente antes:
+>
+> ```bash
+> node .github/scripts/bootstrap-confluence.js
+> ```
+>
+> Ele valida `uvx`, coleta credenciais, gera `.mcp.json` e pré-cacheia o MCP. Depois
+> você abre o VS Code com Copilot Chat e `/sf-mcp confluence` só descobre a árvore do projeto. Uso
+> opcional — `/sf-mcp confluence` sozinho também cobre esses passos, mas demanda reiniciar
+> o Copilot após gerar `.mcp.json` (MCPs só sobem no startup).
+
+---
+
+## Provider: Confluence
+
+### Passo 1 — Detectar estado atual
+
+Ler os 2 arquivos âncora:
+
+| Arquivo | O que extrair | Se ausente |
+|---------|---------------|------------|
+| `sfw.config.yml` | `project.root_page_id`, `project.name`, credenciais do space (`space_key`) | marcar como "falta config" |
+| `.mcp.json` | entry `mcpServers.atlassian` com `CONFLUENCE_URL`, `CONFLUENCE_USERNAME`, `CONFLUENCE_API_TOKEN` | marcar como "falta credenciais" |
+
+Calcular `state`:
+- **COMPLETO** — `sfw.config.yml` tem `root_page_id` E `.mcp.json` tem credenciais → ir pro Passo 2
+- **INCOMPLETO** — algo falta → ir pro Passo 3
+
+### Passo 2 — Estado COMPLETO: validar conexão
+
+Testar:
+```
+mcp__atlassian__confluence_get_page(page_id={root_page_id})
+```
+
+| Resultado | Ação |
+|-----------|------|
+| 200 OK | → Passo 4 (remapear árvore, reconfirmar Input/Output) |
+| 401 Unauthorized | Credencial expirou. Perguntar novo token, atualizar `.mcp.json`, avisar pra reiniciar VS Code com Copilot Chat, PARAR |
+| 404 Not Found | `root_page_id` inválido. Perguntar novo ID, atualizar `sfw.config.yml`, retry teste |
+| MCP não responde | `.mcp.json` foi atualizado mas Claude não recarregou. Avisar pra reiniciar VS Code com Copilot Chat, PARAR |
+| Network error | Mostrar erro, instruir troubleshooting (`.github/adapters/SETUP.md`) |
+
+### Passo 3 — Estado INCOMPLETO: coletar o que falta
+
+#### 3.1 Verificar `uvx`
+
+```bash
+uvx --version
+```
+
+Se não instalado:
+```
+uvx não encontrado. Instale com:
+  pip install uv
+
+Depois rode /sf-mcp confluence novamente.
+```
+**PARAR**.
+
+#### 3.2 Se FALTA credenciais (`.mcp.json` ausente ou incompleto)
+
+Perguntar uma por uma. Pra cada item, mostrar ao user exatamente ONDE achar:
+```
+Configurando acesso ao Confluence.
+
+1. URL do Confluence
+   Abra o Confluence no browser. A URL base é algo como:
+   https://sua-empresa.atlassian.net/wiki
+   Cole essa URL (com /wiki no final):
+   >
+
+2. Email da conta Atlassian
+   É o email que você usa pra logar no Atlassian (não é o token).
+   >
+
+3. API Token
+   Token é diferente de senha. Gere um novo:
+   a) Abra https://id.atlassian.com/manage-profile/security/api-tokens
+   b) Clique "Create API token"
+   c) Dê um nome (ex: "sfw-mcp")
+   d) Copie o token que aparece — ele só aparece UMA VEZ
+   Cole aqui:
+   >
+
+4. Space Key
+   É o código CURTO do seu espaço Confluence (geralmente 2-4 letras maiúsculas).
+   Abra qualquer page do seu espaço. Na URL, você verá:
+   https://...atlassian.net/wiki/spaces/XXX/pages/...
+                                       ^^^
+                                       esse é o Space Key
+   Exemplos comuns: "ST", "DEV", "PROJ", "ENG"
+   Qual é o seu?:
+   >
+```
+
+Criar/atualizar `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "uvx",
+      "args": ["mcp-atlassian"],
+      "env": {
+        "CONFLUENCE_URL": "{url}",
+        "CONFLUENCE_USERNAME": "{email}",
+        "CONFLUENCE_API_TOKEN": "{token}"
+      }
+    }
+  }
+}
+```
+
+**IMPORTANTE**: credenciais hardcoded — `${VAR}` NÃO funciona no VS Code com Copilot Chat.
+
+Se `.mcp.json` acabou de ser criado/atualizado:
+```
+.mcp.json pronto. Preciso que você reinicie o VS Code com Copilot Chat para o MCP carregar.
+
+1. Feche o VS Code com Copilot Chat
+2. Abra novamente na mesma pasta
+3. Rode /sf-mcp confluence — vou continuar de onde paramos (credenciais já salvas,
+   só vou pedir o que ainda falta)
+```
+**PARAR**.
+
+#### 3.3 Se FALTA root_page_id (credenciais OK mas config sem root)
+
+Testar conexão básica primeiro:
+```
+mcp__atlassian__confluence_search(query="space.key={space_key}", limit=1)
+```
+
+Se falha → Passo 2 error table (401/MCP não responde/etc).
+Se OK:
+
+```
+Conexão OK.
+
+Qual é a page RAIZ do seu projeto no Confluence?
+(A page-mãe que contém TUDO do projeto — geralmente tem Input e Output como filhas.)
+
+Duas formas de informar:
+
+  A) Page ID (recomendado — mais confiável):
+     Abra a page raiz no Confluence. A URL mostra:
+     https://...atlassian.net/wiki/spaces/ST/pages/65708/Nome-da-Page
+                                                   ^^^^^
+                                                   esse número é o Page ID
+     Cole só o número (ex: 65708).
+
+  B) Título exato:
+     O título que aparece no topo da page. Tem que bater EXATAMENTE
+     (incluindo acentos e maiúsculas/minúsculas).
+
+Page ID ou título:
+  >
+```
+
+Validar:
+```
+mcp__atlassian__confluence_get_page(page_id={resposta})
+```
+- Se 404 e user colou título → usar `confluence_search` pra achar
+- Se 404 e user colou ID → pedir de novo
+- Se OK → seguir
+
+### Passo 4 — Listar filhos diretos do root (NÃO recursivo)
+
+Nesta etapa queremos só o **primeiro nível** da árvore. Pra identificar Input/Output,
+basta saber quais pages estão logo abaixo do root. A árvore profunda vem depois via
+`/sf-load` quando o agent realmente precisa do conteúdo.
+
+```
+mcp__atlassian__confluence_get_page_children(page_id={root_page_id})
+```
+
+**APENAS 1 chamada**. Sem loop recursivo.
+
+Mostrar ao usuário:
+```
+Projeto: "Barbearia Digital" (root_page_id: 65708)
+
+Filhos diretos do root:
+  1. Requisitos (360668)
+  2. Documentação técnica (294931)
+  3. Referências (557057)
+  4. Decisões (425998)
+```
+
+Se algum desses filhos tiver sub-pages (ex: Requisitos contém scopes), isso será descoberto
+pelo `/sf-load` quando rodar. Aqui só precisamos saber quem é Input e quem é Output no nível 1.
+
+### Passo 5 — Identificar Input e Output
+
+**Se já existe config com Input/Output**: mostrar o que está salvo + opção de mudar:
+```
+Config atual:
+  Input:  Requisitos (360668)
+  Output: Documentação técnica (294931)
+
+Manter? (s/n)
+```
+
+Se `s` → pular pro Passo 7.
+Se `n` → continuar perguntando (como se fosse setup novo).
+
+**Se é setup novo**:
+```
+Qual dessas pages contém os INSUMOS (Input, onde PM/PO publica)?
+  1. Requisitos (360668)
+  2. Documentação técnica (294931)
+  3. Referências (557057)
+  4. Decisões (425998)
+  5. Criar nova page "Input" (filha da raiz)
+  >
+```
+
+Opção 1-4: usar o page_id correspondente.
+Opção 5: criar page nova — `mcp__atlassian__confluence_create_page(parent_id={root}, title="Input", content="")`.
+
+Após escolher Input, perguntar Output com as pages **restantes** (remover a escolhida de Input da lista) + opção "Criar nova page 'Output'".
+
+Se escolher "Criar nova" → `mcp__atlassian__confluence_create_page` como filha da raiz.
+
+### Passo 6 — Sugerir context_pages (opcional)
+
+Das pages do nível 1 (filhos diretos do root) que **não** foram escolhidas como Input ou Output,
+sugerir como contexto adicional pro /sf-extract e /sf-design:
+
+```
+Das pages restantes no primeiro nível:
+
+  - "Referências" (557057) → posso consultar durante /sf-extract e /sf-design
+  - "Decisões" (425998) → posso consultar para ADRs no /sf-design
+
+Quer que eu mapeie alguma dessas como contexto adicional? (listar números, ou "não")
+```
+
+Se sim, incluir as escolhidas em `context_pages[]` no `sfw.config.yml`.
+
+Obs: `/sf-load` descobre a árvore profunda sob Input/Output quando rodar. Aqui só tratamos nível 1.
+
+### Passo 7 — Escrever `sfw.config.yml`
+
+Preservar seções existentes (naming, etc) se já havia arquivo. Atualizar/criar:
+
+```yaml
+project:
+  name: "{título da page raiz}"
+  root_page_id: "{page_id raiz}"
+
+naming:
+  output_container: "out_{scope}"
+  output_artifact: "{scope} - {type}"
+
+input:
+  adapter: confluence
+  config:
+    space_key: "{space_key}"
+    parent_page_id: "{page_id do 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: "{space_key}"
+        parent_page_id: "{page_id do Output}"
+      publishes: [PRD, TRD, Progresso]
+      mode: auto
+      conflict_detection: version
+      approval_mechanism: label
+      approval_label: "sfw-approved"
+
+# Descomente se tiver selecionado context_pages no Passo 6
+# context_pages:
+#   - id: "557057"
+#     title: "Referências"
+#     use_in: [extract, design]
+```
+
+### Passo 8 — Ajustar `.gitignore`
+
+Adicionar se não existe:
+```
+.mcp.json
+
+# SFW: workspace ignored (external backend detected)
+workspace/Output/**
+!workspace/Output/.gitkeep
+```
+
+### Passo 9 — Resumir
+
+```
+Confluence configurado!
+
+Projeto: {nome} ({root_page_id})
+  Input:  {título Input} ({page_id})
+  Output: {título Output} ({page_id})
+
+Arquivos:
+  .mcp.json          ← credenciais (gitignored)
+  sfw.config.yml     ← configuração do projeto
+  .gitignore         ← atualizado
+
+O projeto tem {N} scopes no Input:
+  - {lista dos filhos do Input}
+
+Próximo passo:
+  /sf-start <nome-do-scope>
+```
+
+---
+
+## Subcomando: `/sf-mcp confluence test`
+
+Apenas testa sem modificar arquivos:
+
+1. Verificar que `sfw.config.yml` existe com `project.root_page_id` e `input.config.parent_page_id`
+2. Verificar que `.mcp.json` existe com credenciais
+3. Testar `confluence_get_page(root_page_id)` → root acessível?
+4. Testar `confluence_get_page_children(input.config.parent_page_id)` → listar scopes
+5. Reportar:
+   ```
+   Conexão OK!
+     Root: "{nome}" ({root_page_id})
+     Input: {N} scopes encontrados
+     Output: {M} artefatos publicados anteriormente
+   ```
+6. Se falha: mostrar qual check falhou + link pro troubleshooting
+
+---
+
+## Notas
+
+- **`/sf-mcp confluence` é idempotente** — pode rodar N vezes. Só pergunta o que falta baseado em `sfw.config.yml` + `.mcp.json`
+- **`root_page_id` é âncora** — sem ele o framework não sabe os limites do projeto no space
+- `.mcp.json` é SEMPRE gitignored — contém credenciais
+- `sfw.config.yml` é commitável — zero segredos
+- Após criar/atualizar `.mcp.json`, VS Code com Copilot Chat PRECISA ser reiniciado
+- O framework conhece o projeto INTEIRO (raiz + toda a árvore), não só Input/Output
+- Token Atlassian pode expirar — se der 401, skill pede novo e atualiza `.mcp.json`
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| uvx não instalado | Parar, instruir instalação |
+| MCP não responde após `.mcp.json` novo | Pedir reinício, retomar depois |
+| `root_page_id` 404 | Pedir ID/título correto, validar |
+| Token expirado (401) | Pedir novo token, atualizar .mcp.json, pedir reinício |
+| Sem permissão de escrita no space | Informar, pedir ao admin |
+| Space key inválido | Listar spaces disponíveis se possível |
+
+## Referências
+
+- Setup guide completo: `.github/adapters/SETUP.md`
+- Confluence adapter: `.github/adapters/confluence.md`
+- Interface do adapter: `.github/adapters/interface.md`