Obsidian Migrate

obsidian-migrate

Adota o obsidian-master-kit em um vault Obsidian existente sem quebrar o que ja funciona. Segue a Opcao C (hibrida): descoberta de areas reais via clustering + approval humano por lote + rollback disponivel + backup obrigatorio antes de qualquer movimento.

Quando usar

• Usuario diz: "quero usar o kit no vault que ja tenho", "adota o obsidian-master-kit

no meu Obsidian atual", "migra meu vault pro kit sem apagar nada"

• Usuario invoca /obsidian-master-kit:migrate
• Usuario aponta pra uma pasta que ja tem .md e quer estrutura do kit

Quando nao usar

• Vault vazio — use obsidian-init (scaffold do zero)
• Vault ja migrado (tem .obsidian-master/marker.json) — use obsidian-librarian
• Usuario quer reorganizacao continua de vault ja migrado — use obsidian-organizer

(Epic 04, futuro)

Como usar — fluxo canonico

A skill tem 6 etapas, cada uma com aprovacao do usuario. Nunca pula etapa nem executa sem confirmacao.

Etapa 1 — Deteccao de estado

python3 ${CLAUDE_PLUGIN_ROOT}/skills/obsidian-migrate/scripts/migrate.py status --vault PATH

Retorna um de:

• empty — pasta nao tem .md. Sugere /obsidian-master-kit:init.
• existing — tem .md, sem marker. Pronto pra migrar.
• already_migrated — tem .obsidian-master/marker.json. Usa obsidian-librarian.

Etapa 2 — Shadow scan + backup (Wave 2)

migrate.py shadow-scan --vault PATH

Cria backup (vault.backup-YYYYMMDD-HHMMSS/), inicializa DB, roda scanner sem mover arquivos. Output: contagem por pasta + total + tamanho do DB.

Etapa 3 — Clustering (Wave 3)

migrate.py cluster --vault PATH [--ai-label]

HDBSCAN sobre embeddings + TF-IDF pra label candidato. Opcional: --ai-label pede label via Claude.

Etapa 4 — Proposta de mapping (Wave 4)

migrate.py propose --vault PATH

Gera .obsidian-master/migration-proposal.md: tabela pasta -> cluster dominante -> area proposta. Usuario revisa/edita.

Etapa 5 — Plan + approval (Wave 5)

migrate.py plan --vault PATH
migrate.py approve --batch 1 [--batch all]

Gera registros em migration_plan em lotes de 20. Approval interativo por nota (y/n/a/s).

Etapa 6 — Execute + rollback (Wave 6)

migrate.py apply --batch 1 [--batch all]
migrate.py rollback --batch N   # se precisar reverter

Aplica os renames dos approved, refatora wikilinks que quebrariam, emite eventos, e ao terminar cria .obsidian-master/marker.json com migration_completed=true.

Garantias

• Backup obrigatorio: nunca move nada sem ter um .backup-* intacto
• Approval por lote: usuario aprova 20 notas por vez, nunca o vault inteiro de

um golpe

• Rollback disponivel: cada batch aplicado pode ser revertido
• Opcao C: descoberta de areas respeita o que ja existe; o kit adapta ao vault,

nao o vault ao kit

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: melgarafael
• Source: melgarafael/obsidian-master-kit
• License: MIT

Install and usage instructions live in the source repository linked above.