obsidian-librarian

obsidian-librarian

Curador automatico do vault. Roda apos qualquer escrita, le a doutrina (CLAUDE.md do vault), valida o que foi escrito, corrige o que e deterministico, e mantem o _INDEX.md vivo.

Quando usar

• Apos qualquer Write ou Edit em path dentro de um vault-master (disparo automatico via hook post-vault-write.py).
• Quando o usuario invoca /obsidian-master-kit:sync.
• Quando o usuario diz "atualiza o indice", "roda o bibliotecario", "sincroniza o vault".

Quando nao usar

• Em paths fora de um vault-master (o hook protege, mas valide antes por seguranca).
• Se a ultima invocacao foi ha menos de 5 segundos — dedupe para evitar loops.

Fluxo canonico

Passo 1: Detecte o vault

Caminhe para cima a partir do arquivo modificado procurando .obsidian-master/marker.json. Esse arquivo marca a raiz do vault. Se nao achar, aborta silenciosamente — nao e vault-master.

Passo 2: Leia a doutrina

Leia <vault-root>/CLAUDE.md inteiro. Dali voce extrai:

• Schema de frontmatter (campos obrigatorios, valores validos)
• Schema de tags (hierarquia canonica)
• Mapa de pastas (qual area cada pasta representa)
• Regras de linking (todo arquivo linka pelo menos para o MOC da area)

Essas sao regras locais do vault — podem divergir do default do kit se o humano tiver editado.

Passo 3: Invoque o script de indexacao

python3 ${CLAUDE_PLUGIN_ROOT}/skills/obsidian-librarian/scripts/update_index.py \
  --vault "<vault-root>" \
  [--since <ISO-timestamp>]

O script faz a parte deterministica:

• Walka o vault, le todo .md
• Parseia frontmatter (YAML)
• Valida campos obrigatorios (created, updated, area, type, status, tags)
• Normaliza tags (lowercase, sem # prefix no frontmatter)
• Atualiza campo updated com mtime do arquivo se estiver desatualizado
• Calcula estatisticas: contagem por area, MOCs ativos, notas orfas (sem wiki-link pra MOC), ultimas 10 adicoes
• Reescreve <vault-root>/_INDEX.md
• Atualiza <vault-root>/.obsidian-master/last-sync.json
• Reporta em stdout (JSON) as issues que precisam intervencao humana ou LLM

Passo 4: Trate as issues reportadas

O script retorna JSON como:

{
  "updated_index": true,
  "notes_scanned": 42,
  "orphans": ["02 - Pesquisas e Estudos/Ativas/Nota Solta.md"],
  "missing_frontmatter_fields": [
    {"file": "01 - Profissional/Projetos/X.md", "missing": ["status"]}
  ],
  "unknown_tags": [
    {"file": "02 - Pesquisas e Estudos/Ativas/Y.md", "tags": ["random/custom"]}
  ],
  "area_folder_mismatch": [],
  "last_sync": "2026-04-15T14:20:00"
}

Para cada categoria:

• orphans: consulte as referencias (em references/linking-rules.md) sobre como sugerir um MOC. Adicione linha em ## Relacionado da nota apontando para o MOC da area. Se a nota nao cabe em nenhuma area existente, escale para o usuario.
• missing_frontmatter_fields: adicione os campos faltando seguindo os defaults de references/frontmatter-schema.md:
  • status ausente → draft
  • tags ausente → []
  • updated ausente → data de hoje (mas o script ja faz isso)
  • Nunca chute area ou type — escale pro usuario.
• unknown_tags: compare com o schema em CLAUDE.md do vault. Se a tag nao bate, sugira a tag canonica mais proxima em 1 comentario para o usuario; nao altere sem permissao (tags podem ter significado semantico que o humano escolheu).
• area_folder_mismatch: a nota tem area: pesquisa mas esta em 01 - Profissional/. Nunca mova sem perguntar — reporte ao usuario.

Passo 5: Reporte curto ao usuario

Depois que o script rodou e voce tratou as issues, imprima 1 bloco conciso:

Librarian synced:
- 42 notas escaneadas, _INDEX.md atualizado
- 2 orfas linkadas ao MOC apropriado
- 1 frontmatter preenchido (status: draft)
- 1 tag desconhecida reportada (esperando sua decisao)

Mais que isso e ruido — a pessoa quer saber que o vault esta ok, nao um relatorio de auditoria.

Guardrails — regras inviolaveis

1. Nunca deleta conteudo humano. Nem 1 linha, nem 1 palavra.
2. Nunca edita o CLAUDE.md do vault. Territorio humano.
3. Nunca move arquivos entre areas sem confirmacao. Mismatch de area e um sinalizador, nao uma licenca pra mover.
4. Nunca chuta campos semanticos (area, type, aliases, conteudo do corpo).
5. Se o script falha, reporte o erro e pare. Nao tente "consertar" o vault na marra — prefere halt a corromper.

Referencias bundled

• references/obsidian-conventions.md — convencoes oficiais do Obsidian destiladas
• references/frontmatter-schema.md — schema canonico do kit (fonte de verdade quando o vault nao tem override)
• references/linking-rules.md — regras de wiki-link, backlinks, aliases, MOCs