C2f Documentation

---
name: c2f-documentation
description: "LEIA ANTES de escrever, corrigir, migrar ou publicar documentação do Conn2Flow (\"faça a documentação de X\", \"rode a rotina de docs\"). Se não ler: a doc nasce do texto antigo e não do código, fora do contrato de frontmatter, sem par pt-br/en, e não chega ao site /docs/."
user-invocable: true
---

# Documentação do Conn2Flow: código → Markdown → site (`c2f-documentation`)

# ⚡ Gatilho Obrigatório
- **TRIGGER**: Pedido para documentar, corrigir ou migrar documentação (biblioteca, módulo, API, CLI, hook, guia); rodar a rotina periódica de docs; publicar as docs no site `/docs/`; criar ou alterar `docs.config.json` de um projeto.
- **SKIP APENAS SE**: Edição de artefatos SDD (`sdd/`), README de repositório ou docblocks de código sem relação com `ai-workspace/<idioma>/docs/`.
- **CONSEQUÊNCIA DE IGNORAR**: Documentação defasada ou alucinada (escrita a partir do texto antigo), docs sem `verified_at` invisíveis ao ranking, tradução divergente, e páginas editadas no painel sobrescritas no próximo build.

Complementa a `c2f-documentation-governance` (princípio da autoridade do código). Esta skill é o **procedimento**.

---

## 1. Onde a documentação mora (fonte única)

- **Fonte:** `conn2flow/ai-workspace/<idioma>/docs/` no repositório do Core. Idiomas: `pt-br` e `en`.
- **Árvore:** `guides/`, `concepts/`, `reference/{libraries,modules,api,cli,hooks}/`, `whats-new/` e o `index.md` da raiz.
- **Espelhamento:** pastas e nomes de arquivo são **iguais nos dois idiomas**. O caminho relativo define o par de tradução e a URL pública (`/docs/<caminho>/`).
- **Legado:** arquivos em MAIÚSCULAS na raiz de `docs/` (e subpastas antigas como `bibliotecas/`, `modulos/`, `manual/`). Ao migrar um assunto, a doc nova nasce na árvore e o legado correspondente é removido na mesma passagem.
- **Contrato completo:** `ai-workspace/pt-br/docs/guides/documentation.md`, que é ele mesmo uma doc do sistema.

## 2. Frontmatter obrigatório

```yaml
---
title: "Biblioteca modelo.php"
description: "Uma frase — índices, compartilhamento e llms.txt."
section: reference          # guides | concepts | reference | whats-new (= pasta); home só no index.md raiz
order: 20                   # opcional (padrão 100)
visibility: public          # public (padrão) | restricted (reservado: o build não publica)
module: menus               # opcional
sources:                    # obrigatório em reference/
  - gestor/bibliotecas/modelo.php
verified_at: 5b4348ab       # git rev-parse --short HEAD do Core no momento da conferência
---
```

## 3. Procedimento por passagem (a rotina)

1. **Ranking:** `php cli/c2f.php docs:audit` (no Core). Pegue os N itens do topo. `missing:` significa que a doc não existe.
2. **Esqueleto** (só para biblioteca nova): `php cli/c2f.php docs:extract <lib> --create`. Isso cria pt-br e en com o bloco de funções.
3. **Leitura profunda do código, ANTES de qualquer texto antigo:**
   - **Biblioteca:** o arquivo inteiro, os chamadores (`grep -rn "funcao(" gestor`), os testes em `tests/`.
   - **Módulo:** `<id>.php` (switch de opções e AJAX), `<id>.json` (tabela, resources, hooks), JS, `<id>.widget.php`/`.widget.js`, `resources/<idioma>/` (pages, templates, `ai_modes`), migrations da tabela, `hooks`/`api`.
   - **Sistema/CLI/API:** o controlador ou comando e o fluxo de chamada real.
4. **Escrever o comportamento real:**
   - caixa de letras;
   - primeira ocorrência;
   - padrões e *defaults*;
   - o que acontece quando falta algo;
   - riscos de segurança.
   Se o código contradiz o próprio docblock, a doc segue o código e aponta a divergência. **Marque o legado** (função sem chamadores, chamada a função inexistente). Use exemplos tirados de usos reais do core.
5. **Bilíngue na mesma passagem:** escreva pt-br e en juntos. Nada de "traduzir depois".
6. **Fechar a doc:**
   - preencha `sources` e `verified_at`;
   - rode `php cli/c2f.php docs:extract --all`;
   - rode de novo `php cli/c2f.php docs:audit` até o item sair do ranking (score 0).
7. **Publicar (local):**
   - `php cli/c2f.php docs:build --project=conn2flow-site-local`, depois `php cli/c2f.php project:deploy conn2flow-site-local`;
   - confira as páginas (HTTP 200, `c2f page:inspect ... --screenshot`).
   - O deploy de **produção é do operador**.
8. Registre no SDD do lote e atualize a memória de execução.

## 4. Escrita

- Callouts: `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` (primeira linha sozinha).
- Links entre docs: relativos para o `.md` (`../modules/menus.md`). Link quebrado **aborta** o build.
- Links para o código: relativos à doc (`../../../../../gestor/bibliotecas/x.php#L10`). O build converte para o GitHub.
- Marcadores do Gestor (`@[[grupo#var]]@`, `<!-- widgets#... -->`, `<!-- item < -->`) podem ser mostrados em código ou texto. O build neutraliza a arroba; não "corrija" isso na doc.
- Não edite dentro de `<!-- c2f:extract:start -->` … `<!-- c2f:extract:end -->`. O `docs:audit` avisa quando uma função do código não é citada fora do bloco.

## 5. Publicação num projeto (`docs:build`)

- **Configuração:** `<gestor do projeto>/docs.config.json` define:
  - `languages`, `base_path`, `layout`;
  - `article_template` (template `target=publisher`);
  - `menu` (id + template `target=menus`);
  - `publishers` (seções → publisher, `index_path` e `index_widget` da página de entrada com `publisher-index`);
  - `repository`/`branch`, `site_url` e `labels` por idioma.
- **Requisito:** `resources/project_tables_config.json` com `sync_resources` para `publisher`, `publisher_pages`, `publisher_index` e `menus`.
- **O que é gerado** (ids `docs` e `docs-*`, **gerenciados pelo build**, que nunca devem ser editados à mão nem no painel):
  - `pages/`;
  - `publisher_pages/`;
  - `menus/<menu>/`;
  - as entradas em `pages.json`, `publisher-pages.json` e `menus.json`;
  - `assets/docs/llms*.txt`.
- O build é idempotente. Rodar duas vezes sem mudar o Markdown não altera arquivo.
- Referência de implementação: `conn2flow-site` (REQ-057 / BATCH-050) e Core `cli/src/Support/Docs/`.

## ⛔ Proibições

- Documentar a partir de memória, do texto legado ou de outra doc sem abrir o código.
- Publicar só um idioma, ou deixar `verified_at` vazio.
- Editar páginas `docs*` pelo painel ou direto em `resources/` do projeto (o próximo build sobrescreve).
- Publicar informação sensível (hosts, IPs, credenciais, caminhos de VPS, tokens). Na dúvida, `visibility: restricted`.
- Deploy de produção pelo agente.

## Como usar: termos literais da interface para RAG (BL-028)

Cada tela documentada recebe uma seção padronizada "Como usar" ("How to use" no par inglês). Confira os rótulos reais em resources/ e os handlers atuais antes de escrever. Descreva entrada/rota e permissão, campos obrigatórios/opcionais com seus nomes literais, sequência de botões com seus nomes literais, resultado esperado e recuperação de erro. Mantenha o par de idiomas alinhado e use os termos exibidos naquele idioma.

Não substitua nome visível por coluna SQL nem invente fluxo a partir de manual antigo. O assistente consulta essa seção via RAG: comportamento não documentado não pode ser prometido. Preserve referência técnica separadamente e confira o uso contra a tela real quando o fluxo mudar.

## REQ-077 — Pipeline, worktrees e preservação (DEC-136)

- Projeto: `./c2f project:deploy <id>` é o padrão (95% dos casos). Core: `./c2f manager:update-all`. `./c2f project:update-all <id>` é proibido na rotina de projeto; permitido exclusivamente em lote que altera Core e projeto simultaneamente.
- Antes de deploy, confira `git branch --show-current` e `git status --short` na origem; não publique trabalho alheio/inacabado. Confira o destino e sua autorização. Categoria B (skills/documentação/testes/memória): somente checks locais, sem deploy. Execução sequencial, foreground, logs e locks continuam obrigatórios.
- Worktrees por conveniência são proibidas. Só criar com concorrência multi-agente comprovada no mesmo repositório; em dúvida, consultar o humano antes. Registre raiz original, caminho temporário e concorrência na requisição e lote. Ao concluir/homologar, audite trabalho único, integração na main e junctions, então `git worktree remove <caminho>` e `git worktree prune`. Nunca use força para destruir trabalho não integrado; preserve e reporte impedimentos.
- DEC-136: manter por padrão; nada é removido (arquivo, `status='D'`, `DELETE`) sem confirmação explícita do operador humano. Retirada vira choque pendente; `--confirmar-retirada` só quando pedido pelo operador. Fonte incompleta não autoriza retirada.