Manter e publicar o guia

Desenvolvimento local

Node 22.12+ e .NET SDK 10 para sincronizar; somente Node para compilar o site.

npm --prefix site ci
npm --prefix site run sync
npm --prefix site run dev

sync compila CLI/MCP, exporta comandos, regras e schemas, lê a amostra e as entregas e calcula um hash das fontes fora de site/. sync:check refaz a exportação sem gravar e falha se os dados versionados estiverem antigos. Não há timestamps nem caminhos da máquina no artefato.

Plugin do repositório

claude --plugin-dir ./plugins/sil-builder-site

Use /sil-builder-site:update-site. O hook PostToolUse observa mudanças no repositório e fornece o lembrete de atualizar o texto correspondente. O hook Stop sincroniza os dados quando as fontes mudam. Ele não faz commit, push ou deploy e não bloqueia o agente em loop.

O plugin também está no marketplace local do Codex; a skill e AGENTS.md orientam a atualização nesse cliente. Os hooks automáticos descritos aqui são do Claude Code.

Dados são atualizados automaticamente; explicações precisam de revisão semântica pelo agente/dev. O plugin indica quais páginas revisar. O CI garante a atualidade dos dados, não interpreta mudanças de negócio.

CI e atualização da main

Todo PR executa o check de dados, testes do plugin, verificação Astro e build. Em push para main, o workflow sincroniza e valida; se necessário, faz um commit apenas do JSON gerado. Proteções de branch podem recusar esse push: nesse caso, execute o sync e inclua o resultado no PR. O token do workflow precisa de contents: write somente nesse job.

Publicação do SDK

A versão compartilhada fica em Directory.Build.props; templates, amostra e ferramenta local acompanham esse valor. python3 eng/release/verify_version.py confere os pins antes de publicar.

O fluxo Prepare release usa eng/release/bump_version.py para preparar a versão. Um arquivo existente em docs/releases/<versão>.md sem marcadores é editorial e permanece intacto. Nas notas novas, os commits e as issues ficam entre <!-- builder:changelog:start --> e <!-- builder:changelog:end -->; uma regeneração substitui somente essa região. Escreva instruções de migração fora dela e revise baseline, normalização de GUIDs e ordem das conversões antes de integrar a release. Marcadores incompletos ou duplicados causam erro, sem sobrescrever as notas.

A tag v0.2.1 aciona Publish SDK: testes de todos os componentes e PostgreSQL, entrega empacotada e validação deste guia. Após os gates, os 11 pacotes são publicados no GitHub Packages e um consumidor com cache vazio instala as ferramentas e o template, compila e executa testes. A release só é criada depois dessa verificação, com os pacotes e checksums anexados.

O feed é https://nuget.pkg.github.com/silsistemas/index.json. Consumo requer uma identidade com leitura dos pacotes privados. O workflow usa o token do próprio job; nenhum segredo fica nas fontes. Consulte docs/releases/0.2.1.md para as mudanças de API e os passos de atualização. Esse fluxo não faz deploy dos backends consumidores.

Vercel

1. Importe silsistemas/src-dotnet-builder na Vercel.
2. Defina Root Directory = site e Production Branch = main.
3. Escolha Node 22.x ou 24.x. O preset Astro usa npm ci, npm run build e dist de site/vercel.json.
4. Ative o deploy por Git e mantenha a detecção de alterações fora da pasta raiz habilitada; não use um filtro que ignore mudanças no repo.

O site é estático, sem variáveis de ambiente, banco, segredos ou .NET no build da Vercel. O GitHub sincroniza o JSON; a Vercel publica os commits. Se o projeto for privado, configure o acesso ao deployment conforme o público autorizado.