Swarmvault

SwarmVault

Use esta skill quando o usuário quer um cofre de conhecimento local-first construído no padrão LLM Wiki — três camadas (fontes brutas, wiki, schema) onde a LLM mantém uma wiki durável entre você e as fontes brutas. Use também quando o projeto já contém swarmvault.config.json ou swarmvault.schema.md.

Para onboarding, exemplos, referências de comando ou troubleshooting, leia os README.md, examples/, references/ e TROUBLESHOOTING.md inclusos antes de improvisar conselhos de workflow.

Verificações rápidas

• Trabalhe a partir da raiz do cofre.
• Se o cofre ainda não existe, execute swarmvault init.
• Use swarmvault demo --no-serve quando o usuário quer o walkthrough zero-config mais rápido antes de apontar SwarmVault para suas próprias fontes.
• Use swarmvault scan <directory> --no-serve quando o usuário quer a passada mais rápida em um repo local ou árvore de docs sem passar manualmente por init + ingest + compile primeiro.
• Leia swarmvault.schema.md antes do trabalho com compile ou query. É o contrato operacional do cofre.
• Se wiki/graph/report.md existe, use-o antes de buscas amplas no repo.

Loop principal

1. Inicialize um cofre com swarmvault init quando necessário.
2. Atualize swarmvault.schema.md antes de um compile sério. Use-o para regras de nomenclatura, categorias, grounding, expectativas de atualização e exclusões.
3. Use swarmvault source add <input> quando a entrada é um arquivo local recorrente, diretório local, raiz do repo GitHub público ou hub de docs que deve permanecer registrado.
4. Ingira entradas únicas com swarmvault ingest <path-or-url> ou ingira uma árvore de repo inteira com swarmvault ingest <directory>. Arquivos de áudio usam tasks.audioProvider quando configurado, e URLs do YouTube suportadas passam por captura de transcrição direta em vez de ingest de URL genérico.
5. Use swarmvault ingest --guide, swarmvault source add --guide, swarmvault source reload --guide, swarmvault source guide <id> ou swarmvault source session <id> quando o humano deve integrar uma fonte por vez antes de páginas canônicas mudarem. Defina profile.guidedIngestDefault: true em swarmvault.config.json para tornar o modo guiado o padrão; use --no-guide para sobrescrever. Perfis usando guidedSessionMode: "canonical_review" colocam edições canônicas na fila de aprovação; perfis insights_only mantêm síntese exploratória em wiki/insights/. Use --review apenas para o caminho review-only mais leve.
6. Use swarmvault inbox import para lotes no estilo capture, depois swarmvault watch --lint --repo quando o workflow deve permanecer automatizado. Adicione --code-only quando a atualização deve permanecer apenas AST e adiar re-análise semântica não-código para um compile posterior. Em repos rastreados, mudanças code-only tomam aquele caminho de compile mais rápido automaticamente. Instale swarmvault hook install quando checkouts e commits do git devem disparar a mesma atualização repo-aware code-only automaticamente.
7. Compile com swarmvault compile, use compile --max-tokens <n> quando a wiki gerada deve permanecer dentro de um orçamento de contexto limitado, ou use compile --approve quando mudanças devem passar pela fila de revisão local primeiro.
8. Resolva trabalho em staging com swarmvault review list|show|accept|reject e swarmvault candidate list|promote|archive.
9. Faça perguntas com swarmvault query "<question>". Salva respostas duráveis em wiki/outputs/ por padrão; adicione --no-save apenas para verificações efêmeras. Quando um provedor de embedding está configurado, query pode mesclar correspondências de página semântica em busca local; search.rerank: true permite que o queryProvider atual rerankeie os top hits mesclados antes de responder.
10. Use swarmvault explore "<question>" --steps <n> para loops de pesquisa multi-etapas save-first, ou --format report|slides|chart|image quando o artefato deve ser orientado para apresentação.
11. Execute swarmvault lint sempre que o schema mudou, artefatos parecem obsoletos ou resultados de compile/query desviam. Defina profile.deepLintDefault: true em swarmvault.config.json quando a passada de deep-lint consultiva deve ser o padrão, e use --no-deep quando você precisa de uma execução apenas estrutural. Adicione --web apenas quando deep lint está habilitado e um adaptador webSearch.tasks.deepLintProvider está configurado; evidência web é limitada a deep lint e não altera comportamento de compile ou query.
12. Use swarmvault mcp quando outro agente ou ferramenta deve navegar, pesquisar e fazer query no cofre através de MCP.
13. Use swarmvault graph blast <target> quando o usuário quer análise de impacto de importação reversa, swarmvault graph serve quando o workspace em tempo real ou clipper bookmarklet ajudarão, swarmvault diff quando eles precisam de um resumo de mudança em nível de graph contra a baseline do último commit, ou swarmvault graph export --html <output> / graph export --report <output> quando compartilhar ajudar. graph export também suporta --html-standalone, --json, --obsidian e --canvas para compartilhamento mais leve ou nativo do Obsidian.

Regras de trabalho

• Prefira mudar o schema antes de re-executar compile quando organização ou grounding está errado.
• Trate wiki/ e state/ como outputs de primeira classe. Inspecione-os em vez de confiar em uma resposta de chat única.
• Prefira wiki/graph/report.md, state/graph.json e páginas wiki salvas sobre buscas amplas ad hoc quando já existem.
• Use source add para arquivos recorrentes, diretórios, raízes de repo GitHub público e hubs de docs. Use ingest e add para entradas deliberadas únicas.
• Quando o cofre reside em um repo git, ingest|compile|query --commit pode fazer commit das mudanças em wiki/ e state/ imediatamente após a execução.
• O provedor heurístico padrão é um ponto de partida local/offline válido. Adicione um provedor de modelo apenas quando o usuário quer qualidade de síntese mais rica ou capacidades opcionais como embeddings, vision, geração de imagem ou transcrição de áudio. A configuração totalmente local recomendada é Ollama + Gemma: ollama pull gemma4 depois defina providers.llm para { type: "ollama", model: "gemma4" } e aponte tasks.compileProvider, tasks.queryProvider e tasks.lintProvider para ele.
• Ingest de áudio precisa de tasks.audioProvider para resolver um provedor que exponha capacidade audio. Ingest de transcrição do YouTube não precisa de um provedor. Defina graph.communityResolution quando o usuário quer fixar clustering comunitário em vez de usar o padrão adaptativo.
• Se um backend compatível com OpenAI não pode satisfazer geração estruturada, reduza suas capacidades declaradas em vez de forçar cada tarefa através dele.
• Mantenha fontes brutas imutáveis. Coloque correções em schema, novas fontes ou outputs salvos em vez de reescrever manualmente proveniência gerada.

Arquivos e artefatos

• swarmvault.schema.md: regras de compile e query específicas do cofre.
• raw/sources/ e raw/assets/: armazenamento de fonte canônica.
• wiki/: páginas geradas mais outputs salvos.
• wiki/outputs/source-briefs/: briefs de onboarding salvos para fontes gerenciadas.
• wiki/outputs/source-sessions/: âncoras de sessão guiada resumível mais histórico de pergunta/resposta para integração uma-fonte-por-vez.
• wiki/outputs/source-reviews/: páginas de revisão em staging com escopo de fonte.
• wiki/outputs/source-guides/: guias de integração de fonte em staging para workflows uma-fonte-por-vez.
• wiki/dashboards/: fontes recentes, log de leitura, timeline, sessões de fonte, guias de fonte, mapa de pesquisa, contradição e dashboards de questões abertas.
• wiki/code/: páginas de módulo para JavaScript ingerido, JSX, TypeScript (incluindo .mts/.cts), TSX, script Bash/shell (com detecção baseada em shebang para scripts sem extensão), Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++ (incluindo .c/.cc/.cpp/.cxx e .h/.hh/.hpp/.hxx), PHP, Ruby, PowerShell (.ps1/.psm1/.psd1), Elixir (.ex/.exs), OCaml (.ml/.mli), Objective-C (.m/.mm), ReScript (.res/.resi), Solidity (.sol), componentes Vue single-file (.vue), HTML (.html/.htm) e fontes CSS.
• state/extracts/: markdown extraído e sidecars JSON para PDF, família Word completa (.docx/.docm/.dotx/.dotm), RTF (.rtf), OpenDocument (ODT/ODP/ODS), EPUB, CSV/TSV, família Excel completa (.xlsx/.xlsm/.xlsb/.xls/.xltx/.xltm), família PowerPoint completa (.pptx/.pptm/.potx/.potm), notebooks Jupyter (.ipynb), BibTeX (.bib), Org-mode (.org), AsciiDoc (.adoc/.asciidoc), transcrições, exportações Slack, email, calendar, transcrições de áudio, capturas de transcrição do YouTube e fontes de imagem (.png/.jpg/.jpeg/.gif/.webp/.bmp/.tif/.tiff/.svg/.ico/.heic/.heif/.avif/.jxl), além de previsualizações estruturadas para arquivos config/data (JSON/JSONC/JSON5/TOML/YAML/XML/INI/ENV/PROPERTIES/CFG/CONF) e ingest de texto com content-sniffing para manifestos de desenvolvedor (package.json, Cargo.toml, go.mod, LICENSE, .gitignore, Dockerfile, Makefile e arquivos plaintext similares).
• state/code-index.json: dados de aliases de código repo-aware e resolução de importação local.
• wiki/projects/: rollups de projeto sobre páginas canônicas.
• wiki/candidates/: páginas de conceito e entidade em staging aguardando promoção.
• state/graph.json: graph compilado.
• state/search.sqlite: índice de busca local.
• state/sources.json e state/sources/<id>/: entradas de registro de fonte gerenciada mais estado de sincronização em funcionamento.
• state/approvals/: bundles de revisão em staging de compile --approve.
• state/sessions/: artefatos de sessão canônica para compile, query, explore, lint, watch, review e ações candidate.
• state/jobs.ndjson: log de execução em modo watch.

Integração de agente

• swarmvault install --agent codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot|trae|claw|droid instala regras específicas de agente no projeto atual.
• swarmvault install --agent claude|opencode|gemini|copilot --hook instala suporte de hook graph-first ou plugin para agentes que expõem APIs de hook de projeto.
• swarmvault install --agent aider instala CONVENTIONS.md e wires .aider.conf.yml para lê-lo quando essa config é YAML válido.
• swarmvault mcp expõe tools e resources para busca de página, leitura de página, listagem de fonte, query, ingest, compile e lint.

Padrões a preservar

• Mantenha material de fonte bruta imutável sob raw/.
• Salve respostas úteis a menos que o usuário explicitamente queira output efêmero.
• Prefira fluxos revisáveis como compile --approve, review e candidate quando uma mudança não deve se ativar silenciosamente.
• Trate configuração de provedor como parte da operação séria do cofre. Se apenas heuristic está configurado, diga isso claramente.
• Quando um cofre usa o bloco profile em swarmvault.config.json, respeite-o como a camada de comportamento determinístico. swarmvault.schema.md ainda define a camada de intenção humana.