spec-first-copilot 0.7.0-beta.1 → 0.7.0

package/templates/.github/adapters/confluence.md

@@ -1,295 +1,295 @@
-# ConfluenceAdapter — Runbook
-
-> Implementação do `SourceAdapter` para Atlassian Confluence via MCP
-> `sooperset/mcp-atlassian` (validado end-to-end em 2026-04-11 —
-> ver `planodetarefas.md §9.9` e napkin "Hard findings do teste E2E").
->
-> Este arquivo é o **runbook que o agent segue** quando uma skill precisa
-> de uma operação de Confluence. A interface conceitual está em
-> `.github/adapters/interface.md`.
-
----
-
-## Meta
-
-| Campo | Valor |
-|-------|-------|
-| `name` | `confluence` |
-| MCP provider | `sooperset/mcp-atlassian` via uvx |
-| Credenciais | `.mcp.json` gitignored (hardcoded, `${VAR}` **não funciona**) |
-| Transporte | MCP — tools prefixadas `mcp__atlassian__confluence_*` |
-| Conflict detection | **Client-side obrigatório** (MCP não aceita `expectedVersion`) |
-| Suporta attachments? | ✅ leitura + escrita |
-| Suporta busca? | Fora da interface (skills podem chamar `confluence_search` direto se precisar) |
-
----
-
-## Config
-
-Passada via `sfw.config.yml > input.config` ou `output.targets[].config`.
-
-| Campo | Obrig. | Tipo | Descrição |
-|-------|:---:|------|-----------|
-| `space_key` | ✅ | string | Ex: `"ST"`. Usado em todas as operações que exigem space. |
-| `parent_page_id` | ✅ | string | ID numérico (como string) da página raiz. Ex: `"360668"`. |
-| `recursive` | — | boolean | Default `true`. Se `false`, `listChildren` não desce. |
-| `include_attachments` | — | boolean | Default `true`. Se `false`, `fetchAttachments` retorna `[]`. |
-
-### `validateConfig`
-
-Lança `ValidationError` se:
-- `space_key` ausente, vazio ou não-string
-- `parent_page_id` ausente, vazio ou não parseável como inteiro
-- `recursive` presente mas não-boolean
-- `include_attachments` presente mas não-boolean
-
-Não valida que `space_key` existe no Confluence — isso acontece no primeiro
-`listChildren` e vira `AuthError` ou `NotFoundError`.
-
----
-
-## Mapeamento da interface → MCP
-
-### `listChildren(containerId) → Item[]`
-
-**MCP**: `mcp__atlassian__confluence_get_page_children`
-
-> **ATENÇÃO**: `get_page_children` retorna apenas filhos **diretos** — NÃO é recursivo.
-> Para trazer a árvore inteira, o caller (ex: `/sf-load`) deve implementar recursão manual.
-
-**Passos**:
-1. Chamar tool com `page_id: containerId`
-2. Para cada filho retornado, montar `Item`:
-   - `id` = `page.id` (string)
-   - `title` = `page.title`
-   - `version` = `String(page.version.number)` (se disponível, senão chamar `get_page` pra obter)
-   - `type` = `"page"` (Confluence só tem páginas — folders são páginas vazias convencionadas)
-   - `hasChildren` = verificar via `get_page_children` no filho ou assumir `true` por default
-3. Se retorno paginado, iterar até esgotar
-4. Retornar array (apenas filhos diretos — 1 nível)
-
-**Recursão (obrigatória pro `/sf-load` com `recursive: true`)**:
-
-O `/sf-load` precisa de toda a árvore. Padrão:
-
-```
-function listChildrenRecursive(containerId):
-  filhos = listChildren(containerId)       // 1 nível
-  resultado = [...filhos]
-  para cada filho em filhos:
-    se filho.type == "page":               // tudo no Confluence é page
-      netos = listChildrenRecursive(filho.id)
-      resultado = [...resultado, ...netos]
-  retornar resultado
-```
-
-Custo: 1 chamada MCP por nó da árvore. Uma árvore com 5 scopes × 3 filhos = ~20 chamadas.
-É aceitável — MCP é local (uvx), não HTTP. Se ficar lento com árvores grandes,
-considerar cache em `.ai/load-log.md` e re-scan incremental.
-
-**Erros**:
-- `404` → `NotFoundError { kind: "container", itemId: containerId }`
-- `401/403` → `AuthError`
-- `5xx`/timeout → `TransportError { retryable: true }`
-
----
-
-### `fetchContent(itemId) → { content, metadata }`
-
-**MCP**: `mcp__atlassian__confluence_get_page` com `convert_to_markdown: true`
-
-**Passos**:
-1. Chamar tool com `page_id: itemId`, `convert_to_markdown: true`, `include_metadata: true`
-2. Extrair `content` do campo markdown retornado
-3. Montar `metadata`:
-   - `version` = `page.version.number` (inteiro)
-   - `space_key`, `parent_id`, `created_at`, `updated_at`, `author`
-   - `labels` = array das labels da página (usado pelo caller pra checar `sfw-approved`)
-4. Retornar `{ content, metadata }`
-
-**Notas importantes**:
-- Markdown roundtrip **normaliza** (`#` vira `===` no H1, `-` vira `*` em listas).
-  `version.number` é a fonte de verdade pra drift, **não** diff de bytes.
-- `labels` vêm via `confluence_get_labels` **separadamente** se não vierem
-  embutidos na resposta do `get_page`. Chamar só se o caller pediu (lazy).
-
-**Erros**: mesmas regras do `listChildren`.
-
----
-
-### `fetchAttachments(itemId) → Attachment[]`
-
-**MCP**:
-- `mcp__atlassian__confluence_get_attachments` (lista)
-- `mcp__atlassian__confluence_download_attachment` (bytes, lazy)
-
-**Passos**:
-1. Se `config.include_attachments === false`, retornar `[]` sem chamar MCP.
-2. Chamar `get_attachments` com `page_id: itemId`
-3. Para cada item retornado, montar `Attachment`:
-   - `filename` = `attachment.title`
-   - `size` = `attachment.size` em bytes
-   - `mimeType` = `attachment.mime_type`
-   - `download()` = closure que chama `confluence_download_attachment` com
-     `page_id: itemId, filename: attachment.title` e retorna `Buffer`
-4. Retornar array
-
-**Lazy**: `download()` só dispara quando o caller chama. Listar attachments é
-barato, baixar PDFs pode não ser.
-
----
-
-### `getVersion(itemId) → string`
-
-**MCP**: `mcp__atlassian__confluence_get_page` com `convert_to_markdown: false`
-
-**Passos**:
-1. Chamar tool com `page_id: itemId`, `include_metadata: true`, `convert_to_markdown: false`
-   (evita o custo de converter body quando só queremos version)
-2. Retornar `String(page.version.number)`
-
-**Nota**: se o MCP oferecer um `confluence_get_page_history` mais barato no
-futuro, trocar. Hoje `get_page` é o caminho mais direto. Custo: ~1 request HTTP.
-
----
-
-### `create(parentId, title, content) → { itemId, version }`
-
-**MCP**: `mcp__atlassian__confluence_create_page`
-
-**Passos**:
-1. Chamar tool com:
-   - `space_key: config.space_key`
-   - `parent_id: parentId`
-   - `title: title` (já vem formatado pelo naming engine — ex: `"app_barbearia - PRD"`)
-   - `content: content` (markdown — MCP converte pra storage format)
-   - `content_format: "markdown"`
-2. Retornar:
-   - `itemId` = `response.page.id`
-   - `version` = `String(response.page.version.number)` (tipicamente `"1"`)
-
-**Erros específicos**:
-- `BadRequestException: A page already exists with the same TITLE in this space` →
-  `ConflictError { kind: "duplicate_title", itemId: null }`
-  (naming templating com `{scope}` no título deveria impedir isso — se bateu,
-  dois scopes têm o mesmo nome, o user precisa renomear no Input)
-- `parent_id` inválido → `NotFoundError { kind: "container", itemId: parentId }`
-
----
-
-### `update(itemId, content, expectedVersion) → { version, ok, conflict? }`
-
-**MCP**: `mcp__atlassian__confluence_update_page` (+ `get_page` pra version check)
-
-> **Atenção crítica**: o MCP sooperset **não** aceita `expectedVersion` como
-> parâmetro. Isso significa **zero optimistic locking server-side**. Toda a
-> conflict detection é client-side — responsabilidade deste adapter.
-
-**Passos**:
-1. Chamar `getVersion(itemId)` → `currentVersion`
-   - Se o item sumiu → `NotFoundError`
-2. Comparar `currentVersion !== expectedVersion`:
-   - **Se diverge** → retornar `{ version: currentVersion, ok: false, conflict: true }`
-     (sem chamar `update_page` — não sobrescreve drift)
-3. Se bate, chamar `confluence_update_page` com:
-   - `page_id: itemId`
-   - `title: <mesmo título atual>` (pegar do `get_page` anterior se não vier em cache)
-   - `content: content`
-   - `content_format: "markdown"`
-   - `version_comment: "sfw: auto-publish"` (opcional mas recomendado pra histórico Confluence)
-4. Retornar `{ version: String(response.page.version.number), ok: true }`
-
-**Race window**: há uma pequena janela entre o `getVersion` e o `update_page`
-onde outra pessoa pode ter editado. MVP aceita — o caso é raro e o próximo
-`getVersion`/`update` no ciclo detecta. Se virar dor, documentar como
-limitação conhecida.
-
-**Erros específicos**:
-- `version_drift` detectado no passo 2 → retorno `{ ok: false, conflict: true }`
-  (não lança erro — é caminho normal do contrato)
-- Qualquer outro erro → embrulhar conforme `errors.md`
-
----
-
-### `attachFile?(itemId, filename, content, mimeType)`
-
-**MCP**: `mcp__atlassian__confluence_upload_attachment` (ou `upload_attachments` batch)
-
-**Passos**:
-1. Chamar tool com `page_id: itemId`, `filename`, `content` (bytes), `mime_type`
-2. Não retorna valor — sucesso é ausência de erro
-
-**Implementação opcional no MVP**: ativar se/quando o `/sf-publish` precisar
-anexar diagramas, planilhas, etc. Por padrão, não chamado.
-
----
-
-## Constraints descobertos (aprendizado do teste E2E)
-
-1. **Title uniqueness por SPACE inteiro** — não por parent.
-   **Premissa**: 1 space = 1 projeto. Multi-projeto no mesmo space causa
-   colisão se dois scopes tiverem o mesmo nome.
-   **Mitigação**: user nomeia items no Input com nomes únicos; naming
-   templating com `{scope}` no `output_artifact` garante unicidade no Output.
-
-2. **Markdown roundtrip é lossy** — `#` vira `===`, `-` vira `*`, emojis
-   podem normalizar. **Consequência**: nunca usar diff de bytes pra detectar
-   drift. `version.number` é a única fonte de verdade.
-
-3. **`.mcp.json` com `${VAR}` não funciona** no startup do Claude Code.
-   Credenciais precisam estar hardcoded no arquivo (gitignored). Mudanças
-   exigem reiniciar Claude Code — servers MCP só sobem no startup.
-
-4. **`page_id` é chave estável** — renomeação preserva ID, history, children.
-   Skills persistem ID em logs, não título.
-
-5. **`recursive: true` no `get_page_children`** não é suportado pelo MCP
-   atual — adapter precisa fazer recursão manual (loop + stack) quando
-   `config.recursive === true`.
-
-6. **Paginação**: `get_page_children` retorna `limit` default 25. Caller
-   deve iterar via `start` ou cursor pra esgotar filhos — não assumir
-   que primeira página é tudo.
-
----
-
-## Checklist de pré-requisitos (documentar no bootstrap do kit)
-
-Antes de usar este adapter, usuário precisa:
-
-- [ ] `uvx` instalado (ou `pipx`/`pip`)
-- [ ] `.mcp.json` na raiz do projeto com entrada pro `sooperset/mcp-atlassian`
-      + credenciais hardcoded (NUNCA commitar — está no `.gitignore` do kit)
-- [ ] Token Atlassian com scope de leitura + escrita no space alvo
-- [ ] `space_key` descoberto (ex: via `confluence_search` ou URL do Confluence)
-- [ ] Página raiz do projeto criada (manualmente ou via `/sf-start`)
-- [ ] Claude Code reiniciado após qualquer mudança no `.mcp.json`
-
-Bootstrap do kit (§9.9.P0.3) automatiza isso.
-
----
-
-## Matriz de erros Confluence → tipos do SFW
-
-| Situação Confluence | Tipo lançado | Detalhes |
-|---|---|---|
-| 401 / token inválido | `AuthError` | `hint`: "verifique token em .mcp.json" |
-| 403 / sem permissão | `AuthError` | `hint`: "usuário sem acesso ao space {space_key}" |
-| 404 page_id | `NotFoundError` | `kind: "item"` |
-| 404 parent_id | `NotFoundError` | `kind: "container"` |
-| `BadRequestException` title duplicado | `ConflictError` | `kind: "duplicate_title"` |
-| 5xx Confluence down | `TransportError` | `retryable: true` |
-| MCP server não responde | `TransportError` | `retryable: true`, `hint`: "reinicie Claude Code" |
-| Timeout | `TransportError` | `retryable: true` |
-| Attachment muito grande | `TransportError` | `retryable: false`, `hint`: tamanho máx Confluence |
-
----
-
-## Referências
-
-- Interface: `.github/adapters/interface.md`
-- Erros: `.github/adapters/errors.md`
-- Naming: `.github/adapters/naming.md`
-- Registry: `.github/adapters/registry.md`
-- Validação E2E: `planodetarefas.md §9.9` + napkin "Estado do Confluence MCP"
-- MCP provider: [sooperset/mcp-atlassian](https://github.com/sooperset/mcp-atlassian)
+# ConfluenceAdapter — Runbook
+
+> Implementação do `SourceAdapter` para Atlassian Confluence via MCP
+> `sooperset/mcp-atlassian` (validado end-to-end em 2026-04-11 —
+> ver `planodetarefas.md §9.9` e napkin "Hard findings do teste E2E").
+>
+> Este arquivo é o **runbook que o agent segue** quando uma skill precisa
+> de uma operação de Confluence. A interface conceitual está em
+> `.github/adapters/interface.md`.
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| `name` | `confluence` |
+| MCP provider | `sooperset/mcp-atlassian` via uvx |
+| Credenciais | `.mcp.json` gitignored (hardcoded, `${VAR}` **não funciona**) |
+| Transporte | MCP — tools prefixadas `mcp__atlassian__confluence_*` |
+| Conflict detection | **Client-side obrigatório** (MCP não aceita `expectedVersion`) |
+| Suporta attachments? | ✅ leitura + escrita |
+| Suporta busca? | Fora da interface (skills podem chamar `confluence_search` direto se precisar) |
+
+---
+
+## Config
+
+Passada via `sfw.config.yml > input.config` ou `output.targets[].config`.
+
+| Campo | Obrig. | Tipo | Descrição |
+|-------|:---:|------|-----------|
+| `space_key` | ✅ | string | Ex: `"ST"`. Usado em todas as operações que exigem space. |
+| `parent_page_id` | ✅ | string | ID numérico (como string) da página raiz. Ex: `"360668"`. |
+| `recursive` | — | boolean | Default `true`. Se `false`, `listChildren` não desce. |
+| `include_attachments` | — | boolean | Default `true`. Se `false`, `fetchAttachments` retorna `[]`. |
+
+### `validateConfig`
+
+Lança `ValidationError` se:
+- `space_key` ausente, vazio ou não-string
+- `parent_page_id` ausente, vazio ou não parseável como inteiro
+- `recursive` presente mas não-boolean
+- `include_attachments` presente mas não-boolean
+
+Não valida que `space_key` existe no Confluence — isso acontece no primeiro
+`listChildren` e vira `AuthError` ou `NotFoundError`.
+
+---
+
+## Mapeamento da interface → MCP
+
+### `listChildren(containerId) → Item[]`
+
+**MCP**: `mcp__atlassian__confluence_get_page_children`
+
+> **ATENÇÃO**: `get_page_children` retorna apenas filhos **diretos** — NÃO é recursivo.
+> Para trazer a árvore inteira, o caller (ex: `/sf-load`) deve implementar recursão manual.
+
+**Passos**:
+1. Chamar tool com `page_id: containerId`
+2. Para cada filho retornado, montar `Item`:
+   - `id` = `page.id` (string)
+   - `title` = `page.title`
+   - `version` = `String(page.version.number)` (se disponível, senão chamar `get_page` pra obter)
+   - `type` = `"page"` (Confluence só tem páginas — folders são páginas vazias convencionadas)
+   - `hasChildren` = verificar via `get_page_children` no filho ou assumir `true` por default
+3. Se retorno paginado, iterar até esgotar
+4. Retornar array (apenas filhos diretos — 1 nível)
+
+**Recursão (obrigatória pro `/sf-load` com `recursive: true`)**:
+
+O `/sf-load` precisa de toda a árvore. Padrão:
+
+```
+function listChildrenRecursive(containerId):
+  filhos = listChildren(containerId)       // 1 nível
+  resultado = [...filhos]
+  para cada filho em filhos:
+    se filho.type == "page":               // tudo no Confluence é page
+      netos = listChildrenRecursive(filho.id)
+      resultado = [...resultado, ...netos]
+  retornar resultado
+```
+
+Custo: 1 chamada MCP por nó da árvore. Uma árvore com 5 scopes × 3 filhos = ~20 chamadas.
+É aceitável — MCP é local (uvx), não HTTP. Se ficar lento com árvores grandes,
+considerar cache em `.ai/load-log.md` e re-scan incremental.
+
+**Erros**:
+- `404` → `NotFoundError { kind: "container", itemId: containerId }`
+- `401/403` → `AuthError`
+- `5xx`/timeout → `TransportError { retryable: true }`
+
+---
+
+### `fetchContent(itemId) → { content, metadata }`
+
+**MCP**: `mcp__atlassian__confluence_get_page` com `convert_to_markdown: true`
+
+**Passos**:
+1. Chamar tool com `page_id: itemId`, `convert_to_markdown: true`, `include_metadata: true`
+2. Extrair `content` do campo markdown retornado
+3. Montar `metadata`:
+   - `version` = `page.version.number` (inteiro)
+   - `space_key`, `parent_id`, `created_at`, `updated_at`, `author`
+   - `labels` = array das labels da página (usado pelo caller pra checar `sfw-approved`)
+4. Retornar `{ content, metadata }`
+
+**Notas importantes**:
+- Markdown roundtrip **normaliza** (`#` vira `===` no H1, `-` vira `*` em listas).
+  `version.number` é a fonte de verdade pra drift, **não** diff de bytes.
+- `labels` vêm via `confluence_get_labels` **separadamente** se não vierem
+  embutidos na resposta do `get_page`. Chamar só se o caller pediu (lazy).
+
+**Erros**: mesmas regras do `listChildren`.
+
+---
+
+### `fetchAttachments(itemId) → Attachment[]`
+
+**MCP**:
+- `mcp__atlassian__confluence_get_attachments` (lista)
+- `mcp__atlassian__confluence_download_attachment` (bytes, lazy)
+
+**Passos**:
+1. Se `config.include_attachments === false`, retornar `[]` sem chamar MCP.
+2. Chamar `get_attachments` com `page_id: itemId`
+3. Para cada item retornado, montar `Attachment`:
+   - `filename` = `attachment.title`
+   - `size` = `attachment.size` em bytes
+   - `mimeType` = `attachment.mime_type`
+   - `download()` = closure que chama `confluence_download_attachment` com
+     `page_id: itemId, filename: attachment.title` e retorna `Buffer`
+4. Retornar array
+
+**Lazy**: `download()` só dispara quando o caller chama. Listar attachments é
+barato, baixar PDFs pode não ser.
+
+---
+
+### `getVersion(itemId) → string`
+
+**MCP**: `mcp__atlassian__confluence_get_page` com `convert_to_markdown: false`
+
+**Passos**:
+1. Chamar tool com `page_id: itemId`, `include_metadata: true`, `convert_to_markdown: false`
+   (evita o custo de converter body quando só queremos version)
+2. Retornar `String(page.version.number)`
+
+**Nota**: se o MCP oferecer um `confluence_get_page_history` mais barato no
+futuro, trocar. Hoje `get_page` é o caminho mais direto. Custo: ~1 request HTTP.
+
+---
+
+### `create(parentId, title, content) → { itemId, version }`
+
+**MCP**: `mcp__atlassian__confluence_create_page`
+
+**Passos**:
+1. Chamar tool com:
+   - `space_key: config.space_key`
+   - `parent_id: parentId`
+   - `title: title` (já vem formatado pelo naming engine — ex: `"app_barbearia - PRD"`)
+   - `content: content` (markdown — MCP converte pra storage format)
+   - `content_format: "markdown"`
+2. Retornar:
+   - `itemId` = `response.page.id`
+   - `version` = `String(response.page.version.number)` (tipicamente `"1"`)
+
+**Erros específicos**:
+- `BadRequestException: A page already exists with the same TITLE in this space` →
+  `ConflictError { kind: "duplicate_title", itemId: null }`
+  (naming templating com `{scope}` no título deveria impedir isso — se bateu,
+  dois scopes têm o mesmo nome, o user precisa renomear no Input)
+- `parent_id` inválido → `NotFoundError { kind: "container", itemId: parentId }`
+
+---
+
+### `update(itemId, content, expectedVersion) → { version, ok, conflict? }`
+
+**MCP**: `mcp__atlassian__confluence_update_page` (+ `get_page` pra version check)
+
+> **Atenção crítica**: o MCP sooperset **não** aceita `expectedVersion` como
+> parâmetro. Isso significa **zero optimistic locking server-side**. Toda a
+> conflict detection é client-side — responsabilidade deste adapter.
+
+**Passos**:
+1. Chamar `getVersion(itemId)` → `currentVersion`
+   - Se o item sumiu → `NotFoundError`
+2. Comparar `currentVersion !== expectedVersion`:
+   - **Se diverge** → retornar `{ version: currentVersion, ok: false, conflict: true }`
+     (sem chamar `update_page` — não sobrescreve drift)
+3. Se bate, chamar `confluence_update_page` com:
+   - `page_id: itemId`
+   - `title: <mesmo título atual>` (pegar do `get_page` anterior se não vier em cache)
+   - `content: content`
+   - `content_format: "markdown"`
+   - `version_comment: "sfw: auto-publish"` (opcional mas recomendado pra histórico Confluence)
+4. Retornar `{ version: String(response.page.version.number), ok: true }`
+
+**Race window**: há uma pequena janela entre o `getVersion` e o `update_page`
+onde outra pessoa pode ter editado. MVP aceita — o caso é raro e o próximo
+`getVersion`/`update` no ciclo detecta. Se virar dor, documentar como
+limitação conhecida.
+
+**Erros específicos**:
+- `version_drift` detectado no passo 2 → retorno `{ ok: false, conflict: true }`
+  (não lança erro — é caminho normal do contrato)
+- Qualquer outro erro → embrulhar conforme `errors.md`
+
+---
+
+### `attachFile?(itemId, filename, content, mimeType)`
+
+**MCP**: `mcp__atlassian__confluence_upload_attachment` (ou `upload_attachments` batch)
+
+**Passos**:
+1. Chamar tool com `page_id: itemId`, `filename`, `content` (bytes), `mime_type`
+2. Não retorna valor — sucesso é ausência de erro
+
+**Implementação opcional no MVP**: ativar se/quando o `/sf-publish` precisar
+anexar diagramas, planilhas, etc. Por padrão, não chamado.
+
+---
+
+## Constraints descobertos (aprendizado do teste E2E)
+
+1. **Title uniqueness por SPACE inteiro** — não por parent.
+   **Premissa**: 1 space = 1 projeto. Multi-projeto no mesmo space causa
+   colisão se dois scopes tiverem o mesmo nome.
+   **Mitigação**: user nomeia items no Input com nomes únicos; naming
+   templating com `{scope}` no `output_artifact` garante unicidade no Output.
+
+2. **Markdown roundtrip é lossy** — `#` vira `===`, `-` vira `*`, emojis
+   podem normalizar. **Consequência**: nunca usar diff de bytes pra detectar
+   drift. `version.number` é a única fonte de verdade.
+
+3. **`.mcp.json` com `${VAR}` não funciona** no startup do Claude Code.
+   Credenciais precisam estar hardcoded no arquivo (gitignored). Mudanças
+   exigem reiniciar Claude Code — servers MCP só sobem no startup.
+
+4. **`page_id` é chave estável** — renomeação preserva ID, history, children.
+   Skills persistem ID em logs, não título.
+
+5. **`recursive: true` no `get_page_children`** não é suportado pelo MCP
+   atual — adapter precisa fazer recursão manual (loop + stack) quando
+   `config.recursive === true`.
+
+6. **Paginação**: `get_page_children` retorna `limit` default 25. Caller
+   deve iterar via `start` ou cursor pra esgotar filhos — não assumir
+   que primeira página é tudo.
+
+---
+
+## Checklist de pré-requisitos (documentar no bootstrap do kit)
+
+Antes de usar este adapter, usuário precisa:
+
+- [ ] `uvx` instalado (ou `pipx`/`pip`)
+- [ ] `.mcp.json` na raiz do projeto com entrada pro `sooperset/mcp-atlassian`
+      + credenciais hardcoded (NUNCA commitar — está no `.gitignore` do kit)
+- [ ] Token Atlassian com scope de leitura + escrita no space alvo
+- [ ] `space_key` descoberto (ex: via `confluence_search` ou URL do Confluence)
+- [ ] Página raiz do projeto criada (manualmente ou via `/sf-start`)
+- [ ] Claude Code reiniciado após qualquer mudança no `.mcp.json`
+
+Bootstrap do kit (§9.9.P0.3) automatiza isso.
+
+---
+
+## Matriz de erros Confluence → tipos do SFW
+
+| Situação Confluence | Tipo lançado | Detalhes |
+|---|---|---|
+| 401 / token inválido | `AuthError` | `hint`: "verifique token em .mcp.json" |
+| 403 / sem permissão | `AuthError` | `hint`: "usuário sem acesso ao space {space_key}" |
+| 404 page_id | `NotFoundError` | `kind: "item"` |
+| 404 parent_id | `NotFoundError` | `kind: "container"` |
+| `BadRequestException` title duplicado | `ConflictError` | `kind: "duplicate_title"` |
+| 5xx Confluence down | `TransportError` | `retryable: true` |
+| MCP server não responde | `TransportError` | `retryable: true`, `hint`: "reinicie Claude Code" |
+| Timeout | `TransportError` | `retryable: true` |
+| Attachment muito grande | `TransportError` | `retryable: false`, `hint`: tamanho máx Confluence |
+
+---
+
+## Referências
+
+- Interface: `.github/adapters/interface.md`
+- Erros: `.github/adapters/errors.md`
+- Naming: `.github/adapters/naming.md`
+- Registry: `.github/adapters/registry.md`
+- Validação E2E: `planodetarefas.md §9.9` + napkin "Estado do Confluence MCP"
+- MCP provider: [sooperset/mcp-atlassian](https://github.com/sooperset/mcp-atlassian)