Como escrever e publicar a documentação

A documentação do Conn2Flow tem uma fonte só: os arquivos Markdown de ai-workspace/<idioma>/docs/ no repositório do Core. O site público (/docs/) é gerado a partir deles; nada é escrito direto no painel.

A regra de ouro é que o código é a autoridade. Uma doc só vale se foi conferida contra o código, e o commit dessa conferência fica registrado nela.

Onde cada doc mora

ai-workspace/<idioma>/docs/
├── index.md          página inicial das docs
├── guides/           passo a passo orientado a tarefas
├── concepts/         como o sistema funciona e por quê
├── reference/
│   ├── libraries/    uma doc por gestor/bibliotecas/<nome>.php
│   ├── modules/      uma doc por gestor/modulos/<id>/
│   ├── api/  cli/  hooks/
└── whats-new/        novidades por versão

• Pastas e nomes de arquivo são iguais nos dois idiomas. pt-br/docs/guides/x.md tem o par en/docs/guides/x.md. É o que liga as traduções e define a URL (/docs/guides/x/).

• Escreva as duas versões na mesma passagem, com o mesmo contexto na cabeça. Não existe "traduzir depois".

• Os arquivos em MAIÚSCULAS na raiz de docs/ são legado. Ao migrar um assunto, a doc nova nasce na árvore acima e o legado correspondente é removido.

Frontmatter

---
title: "Biblioteca modelo.php"
description: "Uma frase: aparece nos índices, no compartilhamento e no llms.txt."
section: reference          # guides | concepts | reference | whats-new (igual à pasta)
order: 20                   # posição no menu (padrão 100)
visibility: public          # public (padrão) | restricted (reservado)
label: "Modelos HTML"       # opcional: rótulo curto no menu (bibliotecas)
module: menus               # opcional: id do módulo documentado
sources:                    # obrigatório em reference/: o código que a doc descreve
  - gestor/bibliotecas/modelo.php
verified_at: 86350986
---

sources e verified_at são o que torna a defasagem mensurável: se alguma fonte mudar depois do verified_at, a doc sobe no ranking do docs:audit.

No menu, uma doc de módulo aparece com o nome do módulo da tabela modulos (o nome de gestor/db/data/ModulosData.json, no idioma da doc); as demais usam label, ou o title se não houver label. As páginas de bibliotecas e de módulos mostram no topo o caminho do código a partir da raiz do Gestor (bibliotecas/<lib>.php, modulos/<id>/), montado pelo docs:build.

Como escrever uma doc

1. Leia o código antes do texto antigo. Para uma biblioteca, leia o arquivo inteiro, os chamadores (grep -rn "nome_da_funcao(" gestor) e os testes. Para um módulo, leia <id>.php, <id>.json, o JS, o widget (<id>.widget.php), os resources/ (pages, templates, ai_modes), as migrations da tabela e os hooks.

2. Descreva o comportamento real, inclusive o surpreendente: caixa de letras, só a primeira ocorrência, valores padrão, o que acontece quando algo falta. Se o código contradiz o próprio docblock, a doc segue o código e aponta a divergência.

3. Marque o legado. Função sem chamadores, função que chama algo inexistente e opção morta são informação útil, não constrangimento.

4. Mostre um exemplo tirado de um uso real do core, quando existir.

5. Preencha sources e verified_at com o commit atual (git rev-parse --short HEAD).

Blocos de destaque disponíveis (viram caixas coloridas no site):

> [!NOTE]
> Informação complementar.
> [!TIP]
> Atalho ou boa prática.
> [!IMPORTANT]
> Algo que muda o resultado.
> [!WARNING]
> Risco de erro.
> [!CAUTION]
> Risco de segurança ou perda de dados.

Links entre docs são relativos e apontam para o .md (../modules/menus.md). O build os converte em URLs do site e falha se o destino não existir.

Referência gerada a partir do código

As docs de reference/libraries/ terminam com um bloco gerado:

C2FFUNCTIONREFERENCEBLOCK

• php cli/c2f.php docs:extract modelo regenera o bloco da modelo.php nos dois idiomas.

• php cli/c2f.php docs:extract --all --check falha se algum bloco estiver desatualizado.

• php cli/c2f.php docs:extract 2fa --create cria o esqueleto da doc de uma biblioteca ainda não documentada.

Não edite dentro do bloco. O texto fora dele é seu, e o audit avisa quando alguma função do código não é mencionada no texto.

A rotina: docs:audit

php cli/c2f.php docs:audit            # ranking (30 primeiros)
php cli/c2f.php docs:audit --limit=0  # tudo
php cli/c2f.php docs:audit --json     # para ferramentas
php cli/c2f.php docs:audit --strict   # exit 1 se houver erro (CI)

O ranking soma 10 pontos por erro e 3 por aviso. O comando verifica:

• frontmatter;

• par de idioma;

• fontes inexistentes;

• fontes alteradas depois do verified_at;

• links quebrados;

• bloco extraído desatualizado;

• funções sem explicação;

• bibliotecas e módulos ainda sem doc.

Em cada passagem de agente pela documentação:

1. Rode docs:audit e pegue os itens do topo.

2. Para cada item, faça a leitura profunda do código e reescreva as duas línguas.

3. Rode docs:extract --all e docs:audit de novo até o item sair do ranking.

4. Publique localmente com docs:build (abaixo) e confira no navegador.

Publicação no site: docs:build

php cli/c2f.php docs:build --project=conn2flow-site-local --dry-run
php cli/c2f.php docs:build --project=conn2flow-site-local

• Configuração: o comando lê a chave docs do manifesto do módulo documentation do projeto (gestor/modulos/documentation/documentation.json) ou, na falta dele, o docs.config.json da pasta gestor/. Ela define idiomas, caminho base, layout, qual publisher recebe cada seção e o id do menu lateral. Com o módulo, as páginas geradas pertencem a ele, os templates docs-article e docs-sidebar são procurados primeiro nos recursos do módulo e cada geração grava documentation.status.json na pasta do módulo, que a tela do módulo no painel mostra. A regeneração é sempre pelo CLI, no ambiente de desenvolvimento.

• O que é gerado: o Markdown vira HTML com classes Tailwind e é gravado como recursos do sistema do projeto:

  • publicações (publisher_pages);

  • páginas com publisher_id;

  • o menu da barra lateral;

  • o llms.txt.

• Publicação: a partir daí o caminho é o de qualquer recurso. Rode project:update-all para sincronizar e reconstruir o CSS no ambiente local. O deploy de produção é feito pelo operador.

Fonte SDD do Core

Quando a configuração define "sdd": {"enabled": true}, o mesmo build inclui documentos públicos de conn2flow/sdd/ em /docs/sdd/, sob o publisher docs-sdd. Essa fonte é apenas em pt-br e deriva título, descrição (em texto puro, sem a marcação Markdown) e ordem do próprio Markdown, sem frontmatter. O archive/ de cada pasta é publicado como um subgrupo "Arquivo" no fim da pasta, no menu; o build ignora backlog/, memórias e qualquer SDD de projetos. Antes de gerar páginas e llms.txt, substitui caminhos, IPs, e-mails, hosts e nomes privados; arquivos com credenciais ou chaves são excluídos com aviso no relatório. Confira os avisos do --dry-run antes de publicar.

Veja também

• Biblioteca modelo.php: exemplo de doc de referência de biblioteca.

• Módulo menus: exemplo de doc de módulo.