Mantenha este manual

O código-fonte fica no repositório do aplicativo, para que uma mudança de comportamento e sua documentação possam entrar juntas. As capturas de tela geradas ficam no repositório irmão lotti-docs e nunca são adicionadas à árvore do aplicativo.

Editar prosa

1. Edite ou adicione o arquivo MDX em inglês em docs-site/docs.
2. Atualize o arquivo correspondente para cada localidade publicada em docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current.
3. Adicione uma nova página a docs-site/sidebars.ts.
4. Atualize docs-site/metadata/features.json quando a cobertura mudar.
5. Atualize as entradas correspondentes em docs-site/metadata/surface-inventory.json. Uma superfície só se torna verificada quando sua interface de produção atual, a prosa e a cobertura de capturas de tela tiverem sido todas revisadas.
6. Execute make manual_check.
7. Revise a compilação de produção localmente com make manual_serve, incluindo o seletor de idioma e todas as rotas localizadas.

A validação exige que cada árvore de tradução publicada contenha os mesmos caminhos de página que a árvore de origem em inglês. Ela também rejeita corpos de página traduzidos que sejam idênticos ao inglês, de modo que páginas novas não podem ser publicadas discretamente como cópias não traduzidas. As URLs públicas em inglês permanecem inalteradas; os outros idiomas são publicados sob seu próprio prefixo de localidade com versão.

Mantenha o inventário de cobertura como fonte oficial

O inventário define o limite V1 do manual em inglês: cada página do Beamer, cada folha ou editor das Configurações V2 e todo fluxo de trabalho importante que cria ou altera materialmente dados ou configurações transversais. Cada entrada registra o arquivo de origem responsável e uma âncora no texto-fonte. A validação falha se qualquer um dos dois desaparecer, o que força uma mudança de rota ou de interface a atualizar a auditoria do manual em vez de deixar uma linha obsoleta invisível.

Os estados de cobertura têm significados deliberadamente estritos:

• Planejado significa que a superfície é conhecida, mas ainda não tem cobertura completa.
• Documentado significa que existe prosa útil, mas ainda faltam capturas de tela da produção atual ou uma revisão de precisão de ponta a ponta.
• Verificado significa que a página do recurso relevante foi verificada e está respaldada por capturas de tela de produção registradas.

Execute npm --prefix docs-site run coverage:complete para o gate de lançamento. Ele falha até que todas as superfícies inventariadas estejam verificadas; as compilações incrementais comuns do manual continuam informando as contagens restantes sem bloquear commits do tamanho de um tópico.

Adicione um caso de captura de tela

1. Adicione ou reutilize um harness determinístico de capturas de tela em Flutter.
2. Registre o caso e suas quatro imagens de origem em docs-site/metadata/screenshot-cases.json.
3. Coloque os textos visíveis do fixture atrás de manualScreenshotText(...) para cada localidade suportada quando eles ainda não forem fornecidos pelos arquivos de localização do aplicativo.
4. Capture todas as localidades em ../lotti-docs; nunca neste repositório.
5. Gere e valide o manifesto de mídia.
6. Referencie o caso com <ManualScreenshot caseId="…" alt="…" /> em cada página de idioma.

Toda captura de tela do aplicativo em uma página escrita deve usar ManualScreenshot. Links diretos para imagens antigas do lotti-docs falham na validação do manual porque não conseguem acompanhar a escolha global Mobile/Desktop nem o tema claro/escuro do manual.

Todo caso automatizado deve fornecer as variantes mobile-light, mobile-dark, desktop-light e desktop-dark em cada localidade publicada. O componente do manual escolhe o idioma e o tema correspondentes. Alterar Mobile/Desktop em qualquer imagem atualiza todas as capturas de tela imediatamente e persiste entre páginas e abas abertas do manual.

Publicar um lançamento

O código-fonte do manual não é copiado para cada versão do aplicativo. A tag de lançamento do aplicativo já preserva sua origem exata. O CI faz checkout dessa tag, compila com MANUAL_VERSION=<version> e publica um diretório estático imutável. O menu suspenso de versões é um pequeno manifesto desses diretórios.