rogerdigital/vault-inspector

Vault Inspector

Use o Vault Inspector como um gate de qualidade somente leitura para manutenção de vaults Obsidian. Esta skill é voltada para fluxos de trabalho em terminal, CI e gerenciados por agentes que precisam encontrar links quebrados, anexos órfãos, notas vazias, links externos, arquivos duplicados, divergências de tipo no frontmatter, problemas de uso de tags e arquivos grandes.

Regras de Segurança

• Trate a CLI como somente leitura. Não modifique, mova, exclua ou reescreva arquivos do vault como parte desta skill.
• Não apresente --fix como disponível. A CLI atualmente retorna erro ao executar correções.
• Não exclua automaticamente anexos órfãos, candidatos a duplicados ou arquivos grandes. Resuma as evidências e recomende revisão manual.
• Não trate title, message, generatedAt ou durationMs como identificadores estáveis de automação.
• Use campos estáveis para automação: schemaVersion, toolVersion, summary, scannerId, severity, primaryPath, relatedPaths, evidence, fingerprint, fixAction, isNew e summary.newIssues.
• Mantenha o progresso da varredura no stderr com --progress; mantenha o stdout legível por máquina.

Quando Executar

Execute o Vault Inspector:

• antes de reorganizar, publicar, exportar ou arquivar um vault;
• após alterações em notas geradas ou gerenciadas por agente;
• antes e depois de edições em massa de links, tags, frontmatter ou anexos;
• em CI, quando um vault ou repositório de documentação gerada precisar de verificações de regressão;
• quando um usuário solicitar análise de higiene do vault, links quebrados, arquivos órfãos, arquivos duplicados ou arquivos grandes.

Comandos Básicos

De dentro de um vault:

vinspect . --format json

Para uso avulso sem instalação global:

npx vault-inspector /caminho/para/vault --format json

Gerar um relatório legível por humanos:

vinspect . --format markdown --output relatorio.md

Executar scanners selecionados:

vinspect . --scanner broken-links,empty-notes,large-files --format json

Executar o scanner opcional de links externos somente quando verificações de rede forem aceitáveis:

vinspect . --scanner external-links --format json

Mostrar progresso sem corromper o stdout:

vinspect . --format json --progress

Fluxo com Baseline

Criar um baseline:

vinspect . --format json --output .vault-inspector-baseline.json --fail-on none

Falhar somente em novas descobertas:

vinspect . --baseline .vault-inspector-baseline.json --fail-on new --format json

Ao usar um baseline, inspecione summary.newIssues e o campo isNew de cada issue. Relate novas issues antes das issues conhecidas existentes.

Códigos de Saída

• 0: varredura concluída sem atingir o limite configurado com --fail-on.
• 1: varredura concluída e atingiu o limite configurado com --fail-on.
• 2: uso inválido da CLI ou falha na configuração da varredura.

Se o código de saída for 2, reporte o erro da CLI e não interprete o stdout como resultado bem-sucedido da varredura.

Interpretação dos Resultados

Priorize as descobertas nesta ordem:

1. Links quebrados e links de anexos ausentes com severidade error.
2. Descobertas com severidade warning, incluindo headings ausentes, arquivos grandes, arquivos duplicados confirmados e anexos órfãos antigos.
3. Descobertas com severidade info, incluindo tags de baixo uso, verificações externas ignoradas ou com timeout, anexos órfãos recentes e candidatos a duplicados.

Para cada resumo, inclua:

• contagem total de issues;
• contagens por severidade;
• scanners executados;
• issues de alta confiança primeiro;
• caminhos de arquivo e evidências necessárias para revisão manual;
• contagens de novas issues do baseline, quando disponível.

Evite exagerar na certeza. Anexos órfãos e candidatos a duplicados podem ser falsos positivos quando arquivos são referenciados por CSS, Canvas, Dataview, pipelines de publicação ou ferramentas externas.

Sugestão de Resposta do Agente

Use este formato ao reportar resultados da varredura:

Vault Inspector encontrou <N> issue(s): <E> erro(s), <W> aviso(s), <I> info(s).

Descobertas de maior prioridade:
- [<severidade>] <scannerId>: <primaryPath> - <breve explicação baseada em evidências>

Observações:
- <nota sobre baseline/nova issue, se relevante>
- <advertência de revisão manual para candidatos a órfãos/duplicados, se relevante>

Se a varredura passar, informe o comando executado e as contagens zero relevantes. Não afirme que o vault está perfeito; diga que o Vault Inspector não encontrou issues correspondentes aos scanners e filtros selecionados.