Auditoria

blume audit rastreia o site gerado e reporta problemas de SEO e de saúde do site — cada achado indica o arquivo-fonte e a linha do front matter que o corrige.

blume validate lê o seu conteúdo; blume audit lê o site gerado. Ele rastreia o HTML em dist/ depois de um build e reporta problemas de SEO e de saúde do site: títulos, meta descriptions, canonicals, cards do Open Graph e do X, headings, hreflang, imagens, o sitemap, robots.txt e dados estruturados.

Como foi o Blume que gerou o site, cada achado indica o arquivo-fonte e a linha do front matter que o corrige, e não só a URL que um crawler veria:

⚠ Meta description too long or too short   5 pages
    /docs/configuration/export    content/docs/configuration/export.mdx:3
    fix: Rewrite `description` in the frontmatter to fit the length range.

Rode depois de um build:

blume build
blume audit

Os achados são agrupados por verificação em vez de listados por página, então o relatório funciona como uma lista de tarefas. Use --verbose para expandir cada página afetada com todos os detalhes, e --only/--skip para trabalhar uma categoria de cada vez. blume audit --list-checks imprime o catálogo completo, que também é o catálogo de verificações no fim desta página. O docsUrl de cada achado aponta para a entrada correspondente lá.

Flags

--fail-on error|warning|info: o gate de CI. Sai com código diferente de zero a partir dessa severidade. O padrão é error; --strict é um alias para --fail-on warning.
--url <origin>: também sonda um deploy ao vivo para verificar códigos de status, headers de resposta e cadeias de redirecionamento.
--external: sonda os links externos pela rede.
--only <check|category> / --skip <check|category>: restringe o relatório a essas verificações ou categorias, ou as exclui dele (separadas por vírgula). Um termo que não corresponde a nenhuma verificação ou categoria gera um erro que sugere a mais próxima, então um erro de digitação não esvazia o relatório sem você perceber.
--list-checks: imprime todas as verificações que a auditoria pode reportar e sai.
--verbose: lista cada página afetada com o detalhe completo de cada achado, em vez de só as primeiras.
--json: emite o relatório como JSON no stdout.
--claude / --codex: passa os achados para o Claude Code ou o Codex corrigirem de forma interativa.

Fazendo o CI falhar

O código de saída é o contrato. Por padrão, blume audit só falha em erros, ou seja, coisas que com certeza estão quebradas, como um link para uma página que nunca foi gerada, um loop de redirecionamento ou um sitemap inválido. Achados consultivos (uma description curta, um título duplicado) são avisos e não fazem o build falhar:

blume audit                      # fails on errors
blume audit --fail-on warning    # also fails on warnings

Verificando um deploy ao vivo

Algumas coisas só o servidor real consegue dizer: se uma página que existe em dist/ na verdade retorna 404 por causa de um rewrite errado, se as respostas estão comprimidas e se um header X-Robots-Tag está desindexando silenciosamente uma página cujo HTML parece perfeitamente normal. Aponte a auditoria para um deploy para adicionar essas verificações:

blume audit --url https://docs.example.com
blume audit --url https://docs.example.com --external   # also probe outbound links

Os links externos são classificados, em vez de simplesmente reprovados. Um 404 é um link quebrado que você pode corrigir, enquanto um 403 ou 5xx geralmente é rate limiting ou uma instabilidade no site de outra pessoa, e é reportado como aviso.

Corrigindo os achados com um agente

Se você usa o Claude Code ou o Codex, a auditoria pode passar os achados direto para ele:

blume audit --claude   # or --codex

Isso grava o relatório JSON completo em um arquivo, com todas as páginas afetadas e não só a prévia de três páginas do terminal. Depois, abre o agente de forma interativa com um prompt que o guia pelos achados: editar o arquivo-fonte que cada achado indica, aplicar a correção sugerida e rodar blume build e blume audit de novo até o relatório ficar limpo. A sessão é interativa de propósito: você revisa as edições pelo próprio fluxo de permissões do agente, e o agente é instruído a nunca corrigir um achado apagando conteúdo.

--only e --skip restringem o que é repassado ao agente da mesma forma que restringem o relatório, então você pode enviar uma categoria de cada vez.

O que é e o que não é verificado

O conjunto de verificações é propositalmente mais enxuto que o de um crawler de SEO de uso geral. Boa parte do que um crawler desses reporta não tem como acontecer em um site Blume. Ele nunca emite rel=nofollow, e os bundles do Vite com hash de conteúdo nunca estão faltando nem redirecionam. Reportar isso como zeros permanentes só ensinaria você a ignorar o relatório.

Dois limites que vale deixar claros:

Dados estruturados são validados quanto à boa formação (JSON válido, um @context, um @type em cada nó). O Blume não valida contra o vocabulário completo do schema.org nem contra as regras de rich results do Google.
Core Web Vitals não são verificados. Eles precisam de um navegador de verdade, e uma flag que silenciosamente não medisse nada seria pior do que não ter flag nenhuma. Por isso, blume audit reporta as causas de layout shift que consegue ver offline (imagens sem width/height, assets grandes demais) e deixa o resto de lado por enquanto.

Tudo o que a auditoria não executou é reportado como ignorado, em vez de passar silenciosamente:

⊘ network      skipped — pass --url <origin> (11 checks)
⊘ external     skipped — pass --external (2 checks)

Catálogo de verificações

Todas as verificações que blume audit pode reportar, agrupadas por categoria, com a severidade padrão, o nível em que rodam e a correção que o relatório sugere. --only e --skip aceitam esses ids (sem o prefixo BLUME_AUDIT_ também funciona) ou os nomes das categorias.