Vault Organizer

¿Qué hace Vault Organizer?

Convierte una bóveda de Markdown desordenada en una base de conocimiento limpia, hiperenlazada e indexada que un LLM (o un compañero de equipo) pueda consultar rápidamente. Basado en el principio de Karpathy: trata el conocimiento como código. Las fuentes sin procesar son archivos fuente, la wiki compilada es el resultado del build, el INDEX es el esquema, y esta habilidad es el compilador + linter.

El modelo (3 capas)

Capa	Qué	Dónde
RAW	Sin procesar: transcripciones, clips, volcados, capturas de pantalla	00_Inbox/raw/, carpeta temática más cercana
COMPILED	Páginas sintetizadas, con referencias cruzadas usando [[wikilinks]]	Carpetas PARA (01_–04_)
SCHEMA	Archivos INDEX, CLAUDE.md, las reglas	INDEX.md por carpeta + un índice maestro

Cada archivo lleva type: en el frontmatter (raw | compiled | reference | framework | client | index). Consulta references/standards.md para las plantillas de frontmatter e INDEX.

Flujo de trabajo

Ejecuta en orden. Audita y propón antes de cambiar nada. Nunca elimines ni muevas sin confirmar. Prefiere un repositorio Git para que los cambios sean reversibles.

1. Auditoría (solo lectura)

# bóveda completa:
python3 scripts/audit.py <vault_root> --stale-days 120 --report /tmp/vault-audit.md
# una subcarpeta, pero resuelve [[wikilinks]] contra toda la bóveda (evita falsos "enlaces rotos"):
python3 scripts/audit.py <subfolder> --link-root <vault_root> --report /tmp/vault-audit.md

Devuelve un informe de salud: frontmatter faltante, wikilinks rotos/faltantes, huérfanos, secciones Related faltantes, duplicados, archivos obsoletos, carpetas sin INDEX. Léelo, luego muéstrale al usuario la tabla resumen y los problemas principales. (--json para salida en máquina.)

2. Triage

Agrupa los hallazgos y pregunta qué arreglar ahora vs. más tarde. Prioridad por defecto:

1. Carpetas sin INDEX (mata la recuperación)
2. Frontmatter faltante (mata la búsqueda + Propiedades)
3. Wikilinks rotos (mata el grafo)
4. Secciones Related faltantes + huérfanos (mata el descubrimiento)
5. Obsoletos / duplicados (limpieza)

3. Limpieza (por archivo)

Para cada archivo marcado:

• Agrega frontmatter YAML (title, type, source, author, created, description, tags) — infiere del contenido, usa la fecha de hoy para created si se desconoce.
• Agrega [[wikilinks]] en la primera mención de cualquier concepto, herramienta, persona o archivo que exista en otra parte de la bóveda.
• Agrega una sección ## Related al final con 3–8 [[wikilinks]] a las páginas más conectadas. Agrega el archivo de vuelta en el Related de 2–3 de esas páginas (bidireccional).
• Arregla wikilinks rotos: redirige al slug correcto, o déjalo como un stub intencional si vale la pena escribir el destino más tarde. Usa las plantillas en references/standards.md. No elimines el frontmatter ni los enlaces existentes.

4. Organización (propón primero)

• Mueve los archivos mal ubicados a la capa/carpeta correcta (raw → 00_Inbox/raw/, compilado → PARA).
• Normaliza los nombres de archivo a kebab-case; fusiona o renombra duplicados.
• Mantén los movimientos pequeños y reversibles. Enumera cada movimiento y obtén un sí antes de ejecutarlo.

5. Registro (el entregable)

• Para cada carpeta de contenido, genera o actualiza INDEX.md: un puntero de una línea por archivo (- [[nombre-archivo]] — breve descripción), agrupado por tipo, los más nuevos o importantes primero.
• Construye/actualiza un índice maestro (por ejemplo, INDEX.md en la raíz, o una carpeta de esquema meta/) que enlace a cada INDEX de carpeta.
• Este registro es lo que hace que la recuperación sea rápida y lo que le entregas a un compañero de equipo.

6. Linting (confirmación)

Vuelve a ejecutar audit.py. Muestra los contadores antes/después. La bóveda está "limpia" cuando los contadores de frontmatter, cobertura de INDEX y enlaces rotos están en cero (los huérfanos/obsoletos pueden permanecer por elección).

Enviarlo a un compañero de equipo

Cuando el objetivo sea compartir la bóveda organizada con un compañero de equipo: asegúrate de que el INDEX maestro esté actualizado, cada carpeta tenga su propio INDEX, y un breve README.md en la raíz explique el modelo de 3 capas y cómo navegar. El README + el índice maestro es el punto de entrada.

Reglas

• Auditoría de solo lectura primero, siempre. Superficie, no sorprendas.
• Nunca elimines ni muevas en masa sin confirmación explícita; recomienda hacer commit primero.
• No toques .obsidian/, .git/, ni la configuración de Claude Code (settings.json, hooks).
• Respeta las convenciones existentes de la bóveda (esta: PARA + los estándares en references/standards.md).
• Trabaja en lotes; informa qué cambió después de cada lote.

Archivos

• scripts/audit.py — escáner de solo lectura, el motor. Ejecútalo primero y último.
• references/standards.md — especificación de frontmatter, taxonomía de tipos, plantillas de INDEX + README.