claude-code-arcane 1.4.0 → 2.1.0

package/skills/second-brain/hooks/validate-note.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# PostToolUse guard for notes written into an Obsidian vault.
+#
+# Warns, never blocks: a note half-written is still worth keeping, and a hook
+# that rejects writes turns capture into a fight. Everything here is a warning on
+# stderr and the exit code is always 0.
+#
+# Only fires for .md files that live under a directory containing .obsidian/, so
+# it stays silent in a code repo even when the profile is installed there.
+set +e
+
+VAULT_MARKER=".obsidian"
+
+find_vault_root() {
+  local dir="$1"
+  while [[ -n "$dir" && "$dir" != "/" && "$dir" != "." ]]; do
+    [[ -d "$dir/$VAULT_MARKER" ]] && { echo "$dir"; return 0; }
+    local parent
+    parent=$(dirname "$dir")
+    [[ "$parent" == "$dir" ]] && break
+    dir="$parent"
+  done
+  return 1
+}
+
+frontmatter_of() {
+  # Lines between the opening --- on line 1 and the next ---. Empty if the note
+  # has no frontmatter at all.
+  awk 'NR==1 && $0!="---" {exit} NR==1 {next} /^---$/ {exit} {print}' "$1" 2>/dev/null
+}
+
+main() {
+  local INPUT FILE
+  INPUT=$(cat 2>/dev/null) || true
+  FILE=$(echo "$INPUT" | grep -oE '"file_path"\s*:\s*"[^"]*"' | head -1 | sed 's/.*"file_path"\s*:\s*"//;s/"$//') || true
+
+  [[ -z "$FILE" ]] && return 0
+  [[ "$FILE" != *.md ]] && return 0
+  [[ ! -f "$FILE" ]] && return 0
+
+  # Windows paths arrive backslash-escaped inside the JSON payload.
+  FILE=$(echo "$FILE" | sed 's|\\\\|/|g; s|\\|/|g')
+  [[ ! -f "$FILE" ]] && return 0
+
+  local ROOT REL
+  ROOT=$(find_vault_root "$(dirname "$FILE")") || return 0
+  REL=${FILE#"$ROOT"/}
+
+  # Templates are hollow and unlinked by design; vault config is not a note.
+  case "$REL" in
+    Templates/*|*/Templates/*|.obsidian/*) return 0 ;;
+  esac
+
+  local FM
+  FM=$(frontmatter_of "$FILE")
+
+  if [[ -z "$FM" ]]; then
+    echo "WARN [vault] $REL has no frontmatter: the vault contract expects created and type" >&2
+    return 0
+  fi
+
+  local MISSING=""
+  echo "$FM" | grep -qE '^created:' || MISSING="created"
+  echo "$FM" | grep -qE '^type:' || MISSING="${MISSING:+$MISSING, }type"
+  [[ -n "$MISSING" ]] && \
+    echo "WARN [vault] $REL is missing frontmatter field(s): $MISSING" >&2
+
+  # A raw dump is allowed to have no links: /review-dump is what adds them.
+  local TYPE
+  TYPE=$(echo "$FM" | grep -E '^type:' | head -1 | sed 's/^type:[[:space:]]*//;s/["'\'']//g')
+  case "$TYPE" in
+    dump|"") return 0 ;;
+  esac
+  case "$REL" in
+    _inbox/*) return 0 ;;
+  esac
+
+  if ! grep -q '\[\[' "$FILE" 2>/dev/null; then
+    echo "WARN [vault] $REL has no wikilink: an unlinked note is an orphan the day it is written" >&2
+  fi
+}
+# stderr is left alone on purpose: it is the whole output of this hook. Some
+# hooks in hooks/ swallow it; here that would make the guard invisible.
+main
+exit 0

package/skills/second-brain/references/cross-project.md

@@ -0,0 +1,57 @@
+# Un vault, todos los proyectos
+
+El vault no sirve solo cuando estás sentado en él. Sirve cuando estás en otro repo y necesitás algo que ya pensaste. Esta es la receta para que cualquier proyecto lea el mismo segundo cerebro, sin duplicar nada.
+
+Adaptado del patrón de `AgriciDaniel/claude-obsidian` (MIT), con la cascada de lectura y la regla de exclusión que son la parte que importa.
+
+## El snippet
+
+Pegar esto en el `CLAUDE.md` **del otro proyecto**, con el path real:
+
+```markdown
+## Segundo cerebro
+
+Vault: `~/ruta/al/vault`
+
+Cuando necesites contexto que no está en este repo, en este orden y parando en
+cuanto alcance:
+
+1. `hot.md` del vault: caché de contexto reciente, corto por diseño.
+2. `python <vault>/.claude/skills/vault-recall/scripts/vault_index.py "<vault>" search "<consulta>"`
+   para encontrar las notas relevantes por relevancia, no por keyword.
+3. El hub del tema en `Hubs/`, y de ahí a las notas que linkea.
+4. Solo entonces, la nota específica.
+
+NO leas el vault para preguntas generales de programación. Es memoria personal,
+no documentación técnica: si la respuesta está en los docs del lenguaje o en este
+repo, el vault no aporta y solo gasta contexto.
+
+Nunca escribas en el vault desde este proyecto sin que yo lo pida explícitamente.
+```
+
+## Por qué la cascada, y por qué en ese orden
+
+Cada escalón es más caro que el anterior. `hot.md` son 40 líneas y cubre "qué estaba haciendo". La búsqueda cuesta una llamada y devuelve rutas, no contenido. El hub cuesta una lectura y te da el mapa del tema. La nota específica es lo único que trae texto completo.
+
+Sin la cascada, un agente con acceso al vault hace lo que haría cualquiera sin instrucciones: `Glob` de todo y leer lo que parezca relacionado. En un vault de mil notas eso es la sesión entera gastada antes de empezar.
+
+## Por qué la regla de exclusión es la línea más importante
+
+`NO leas el vault para preguntas generales de programación`.
+
+Sin eso, el vault se convierte en un lugar más donde buscar antes de responder cualquier cosa, y cada consulta paga el costo sin recibir nada. El vault aporta cuando la respuesta depende de **tu** historia: una decisión que tomaste, una persona con la que hablaste, algo que ya te pasó. Para saber cómo funciona un `Promise.all`, no.
+
+## Escritura desde otro proyecto
+
+Por default, **solo lectura**. Un proyecto que escribe en el vault sin que se lo pidas mete notas sin frontmatter, sin links y sin que nadie las revise, que es exactamente el material del que están hechas las huérfanas.
+
+Cuando quieras capturar algo al vault desde otro repo, hay dos caminos:
+
+- **Recomendado:** `/brain-dump` con `--vault <path>`. Va al dump del día, sin clasificar, y lo procesa el review a la noche como cualquier otra captura.
+- **Si te molesta pasar el path:** un servidor MCP de Obsidian (por ejemplo `@bitbonsai/mcpvault`) te deja tocar el vault desde cualquier sesión. Cuesta una dependencia y latencia, y hay que aclarar en el `CLAUDE.md` del proyecto que solo se usa para capturar, no para reorganizar.
+
+## Lo que no hay que hacer
+
+- **No copiar notas del vault al repo.** Dos copias divergen y ninguna gana.
+- **No apuntar el proyecto a una subcarpeta del vault** para "acotar". Rompe la resolución de `[[wikilinks]]`, que es global al vault.
+- **No dejar que un proyecto corra `/vault-tidy` ni `/review-dump`.** Esos escriben en volumen y necesitan al usuario mirando. Desde otro repo, el vault se lee.

package/skills/second-brain/references/templates/Atomic.md

@@ -0,0 +1,22 @@
+---
+created: {{date:YYYY-MM-DD}}
+type: atomic
+tags: []
+---
+
+# <Título que afirma la idea, no que la nombra>
+
+<La idea en tus palabras, en un párrafo. Si necesitás dos títulos `##` que no se relacionan, son dos notas.>
+
+## Por qué me importa
+
+<Una o dos líneas: qué problema tuyo toca esto. Es lo que hace que la nota sea tuya y no un resumen.>
+
+## Relacionado
+
+- [[Hub del tema]]
+- <otras notas atómicas con las que discute o a las que refuerza>
+
+## Fuente
+
+<Link al clip, al libro, a la conversación. Si salió de tu cabeza, decilo.>

package/skills/second-brain/references/templates/Daily.md

@@ -0,0 +1,25 @@
+---
+created: {{date:YYYY-MM-DD}}
+type: daily
+tags: []
+---
+
+# {{date:YYYY-MM-DD}}
+
+Dump del día: [[{{date:YYYY-MM-DD}} dump]]
+
+## Qué pasó
+
+<Síntesis en 3 a 5 líneas, escrita por /review-dump a partir del dump. Hechos, no interpretación.>
+
+## Notas creadas
+
+<Links a las notas que salieron del dump de hoy.>
+
+## Tareas del día
+
+<Tareas que quedaron en este día, con su estado real. Las no hechas quedan como `- [-]`, no se mueven.>
+
+## Reflexión
+
+<Esta sección la escribe el usuario. Claude no la toca.>

package/skills/second-brain/references/templates/Dashboard.base

@@ -0,0 +1,70 @@
+filters:
+  and:
+    - '!file.inFolder("Templates")'
+    - '!file.inFolder("04_Archive")'
+
+formulas:
+  dias_sin_tocar: '(now() - file.mtime).days'
+
+properties:
+  status:
+    displayName: Madurez
+  formula.dias_sin_tocar:
+    displayName: "Dias sin tocar"
+  file.mtime:
+    displayName: Modificada
+
+views:
+  - type: table
+    name: "Semillas que no crecieron"
+    filters:
+      and:
+        - 'status == "seed"'
+        - "formula.dias_sin_tocar > 30"
+    order:
+      - file.name
+      - formula.dias_sin_tocar
+      - created
+    summaries:
+      formula.dias_sin_tocar: Average
+
+  - type: table
+    name: "Contradicciones abiertas"
+    filters:
+      - 'status == "contested"'
+    order:
+      - file.name
+      - created
+
+  - type: table
+    name: "Tocado esta semana"
+    limit: 30
+    filters:
+      - "file.mtime > now() - 7d"
+    order:
+      - file.mtime
+      - file.name
+      - status
+
+  - type: table
+    name: "Conocimiento por madurez"
+    filters:
+      - 'type == "atomic" || type == "hub" || type == "clip"'
+    groupBy:
+      property: status
+      direction: ASC
+    order:
+      - file.name
+      - type
+      - formula.dias_sin_tocar
+
+  - type: table
+    name: "Proyectos activos"
+    filters:
+      and:
+        - 'type == "project"'
+        - 'status != "cerrado"'
+    order:
+      - file.name
+      - status
+      - deadline

package/skills/second-brain/references/templates/Dump.md

@@ -0,0 +1,11 @@
+---
+created: {{date:YYYY-MM-DD}}
+type: dump
+tags: []
+---
+
+# {{date:YYYY-MM-DD}} dump
+
+<!-- Tirá todo acá. Sin tags, sin decidir dónde va, sin orden. Una línea por cosa.
+     Tareas como `- [ ] ...`. Lo clasifica /review-dump a la noche. -->
+

package/skills/second-brain/references/templates/Hub.md

@@ -0,0 +1,22 @@
+---
+created: {{date:YYYY-MM-DD}}
+type: hub
+tags: []
+aliases: []
+---
+
+# <Nombre de la entidad>
+
+<Qué es y por qué tiene una nota propia, en una o dos líneas.>
+
+## Estado actual
+
+<Lo que hay que saber hoy sobre esto. Esta sección se reescribe, no se acumula.>
+
+## Notas
+
+<Links a las notas atómicas y proyectos de este tema. Acá sí se acumula.>
+
+## Historial
+
+<Línea por evento, formato `- YYYY-MM-DD - qué pasó`, agregado por /review-dump cuando la entidad aparece en un dump. Lo más nuevo arriba.>

package/skills/second-brain/references/templates/Monthly.md

@@ -0,0 +1,29 @@
+---
+created: {{date:YYYY-MM-DD}}
+type: monthly
+tags: []
+---
+
+# {{date:YYYY-MM}}
+
+Weeklies del mes: <links a los weeklies>
+
+## Patrones
+
+<Lo que se repitió a lo largo del mes y no se ve en una sola semana.>
+
+## Logros
+
+<Lo que efectivamente se cerró, con link a la nota que lo respalda.>
+
+## Ideas para adelante
+
+<Semillas: lo que apareció este mes y merece seguimiento el mes que viene.>
+
+## Salud del vault
+
+<Resumen de la última corrida de /vault-audit: huérfanas, stale, tareas viejas abiertas.>
+
+## Reflexión
+
+<Esta sección la escribe el usuario.>

package/skills/second-brain/references/templates/Weekly.md

@@ -0,0 +1,29 @@
+---
+created: {{date:YYYY-MM-DD}}
+type: weekly
+tags: []
+---
+
+# {{date:YYYY}}-W{{date:ww}}
+
+Dailies de la semana: <links a los dailies existentes>
+
+## Temas de la semana
+
+<Los 3 a 5 temas que se repitieron, cada uno con los dailies donde aparece.>
+
+## Hilos abiertos
+
+<Lo que quedó sin cerrar y sigue vivo. Distinto de una tarea: es una pregunta o decisión pendiente.>
+
+## Tareas: hechas y no hechas
+
+<Conteo y detalle. Las no hechas se nombran, no se esconden.>
+
+## Notas que crecieron
+
+<Hub files y notas atómicas que recibieron contenido esta semana.>
+
+## Reflexión
+
+<Esta sección la escribe el usuario.>

package/skills/second-brain/references/templates/codebases.md

@@ -0,0 +1,37 @@
+---
+created: {{date:YYYY-MM-DD}}
+type: codebases
+---
+
+# Codebases
+
+Puente del vault al código. Las notas de hub y de proyecto declaran `repos:` en su frontmatter; esta tabla dice qué es cada repo y dónde está en esta máquina.
+
+**El vault apunta, no copia.** Acá no va arquitectura, ni estructura de carpetas, ni explicaciones de módulos: eso vive en el repo y se desactualiza el día que alguien mergea. Acá va solo lo que el repo no te puede decir: dónde está local, cómo se corre, y qué te vas a llevar puesto.
+
+| Repo | Path local | Rama | Cómo correr | Grafo | Notas |
+|---|---|---|---|---|---|
+| `<repo>` | `~/code/<repo>` | `main` | `npm run dev` | `graphify` | `<gotcha en una línea>` |
+
+## Antes de explorar un repo, consultá su grafo
+
+Si el repo tiene un grafo de código consultable, **esa es la primera parada, no un subagente explorando**. Un relevamiento de arquitectura con subagentes cuesta del orden de 100k tokens y minutos; una consulta al grafo cuesta uno o dos mil y es instantánea.
+
+```bash
+graphify query "que conecta X con Y" --budget 2000
+graphify explain "<Simbolo>"
+```
+
+Y si el repo tiene una capa curada de arquitectura (por ejemplo `exploracion/ARQUITECTURA.md`), leela después del grafo: ahí viven las decisiones y los gotchas que un AST no ve. Si tu cambio invalida algo de lo que documenta, actualizarla es parte del cambio.
+
+## Qué va en el vault y qué va en el repo
+
+| Pregunta | La responde |
+|---|---|
+| ¿Qué hace esto y para quién? | El vault: el hub del tema |
+| ¿Por qué está hecho así? | El vault: la decisión, en una nota atómica |
+| ¿Qué archivos toco? | El repo: el grafo |
+| ¿Qué se rompe si cambio esto? | El repo: el grafo |
+| ¿Cómo lo corro y qué me va a explotar? | Esta tabla |
+
+Si te encontrás copiando arquitectura al vault, la pregunta que estabas contestando era del repo.

package/skills/second-brain/references/templates/hot.md

@@ -0,0 +1,37 @@
+---
+type: cache
+updated: {{date:YYYY-MM-DD}}
+---
+
+# Contexto reciente
+
+> [!warning] Esto es un caché, no una nota
+> Lo reescribe `/review-dump` al cerrar el día. Si contradice a una nota, **la nota gana**. Se puede borrar sin perder nada: se regenera. No lo edites a mano, no lo linkees desde otras notas.
+
+## Dónde estoy
+
+<Dos o tres líneas: en qué está trabajando el usuario ahora. Reescrito cada vez, no acumulado.>
+
+## Cambió en los últimos días
+
+<Links a las notas creadas o tocadas, con una línea de qué cambió en cada una. Máximo 10.>
+
+## Hilos abiertos
+
+<Preguntas y decisiones pendientes, con link a donde aparecieron. Máximo 5. Un hilo que se cierra se saca de acá.>
+
+## Tareas vivas
+
+<Las tareas abiertas que siguen vigentes, con link a su nota. No las canceladas.>
+
+<!--
+Reglas de este archivo, y son duras porque es lo único del vault que un agente
+reescribe sin preguntar:
+
+- Techo de 40 lineas. Si no entra, es que hay que resumir mas, no agrandar el techo.
+- Nada de secretos, tokens, ni credenciales, aunque aparezcan en un dump.
+- Nada de transcripciones crudas ni de texto pegado de terceros.
+- Ninguna afirmacion sin su link a la nota que la respalda. Este archivo no crea
+  conocimiento: apunta al que ya existe.
+- Se reescribe completo, no se le agrega al final. Un caché que crece es un log.
+-->

package/skills/second-brain/references/templates/vault-CLAUDE.md

@@ -0,0 +1,127 @@
+# <NOMBRE DEL VAULT>
+
+Vault de Obsidian usado como segundo cerebro. Este archivo es el contrato: Claude Code lo lee al inicio de cada sesión y de acá saca dónde va cada cosa. Si una convención cambia, se cambia acá primero.
+
+## Quién soy
+
+<Rol, en qué proyectos estoy, qué temas me interesan. Dos o tres líneas: sirve para que las síntesis tengan contexto y no sean genéricas.>
+
+## Rutas
+
+Contrato de rutas: los skills escriben en **roles**, y esta tabla dice qué carpeta es cada rol en este vault. Si cambiás una carpeta de lugar, se cambia acá y todo lo demás sigue funcionando.
+
+| Rol | Ruta en este vault |
+|---|---|
+| `inbox` | `_inbox` |
+| `daily` | `Reflect/Daily` |
+| `weekly` | `Reflect/Weekly` |
+| `monthly` | `Reflect/Monthly` |
+| `atomic` | `03_Resources` |
+| `hubs` | `Hubs` |
+| `projects` | `01_Projects` |
+| `areas` | `02_Areas` |
+| `archive` | `04_Archive` |
+| `templates` | `Templates` |
+
+Y tres archivos fijos en la raíz: este `CLAUDE.md` (el contrato), `hot.md` (el caché de contexto reciente, lo reescribe `/review-dump`) y `codebases.md` (el puente a los repos, si hay código).
+
+Un rol que este vault no usa se marca `(no usa)` en vez de borrar la fila: así queda explícito que la ausencia fue una decisión.
+
+Los scripts reciben esto por flag: `--role hubs=Hubs --role atomic=03_Resources`.
+
+## Estructura
+
+| Carpeta | Qué vive acá |
+|---|---|
+| `_inbox/` | Captura cruda, un archivo por día (`YYYY-MM-DD dump.md`). Sin estructura, sin tags, sin pensar. El sufijo evita que el nombre choque con el del daily. |
+| `Reflect/Daily/` | Síntesis del día (`YYYY-MM-DD.md`), la crea `/review-dump`. |
+| `Reflect/Weekly/` | Retrospectiva semanal (`YYYY-Www.md`). |
+| `Reflect/Monthly/` | Balance del mes (`YYYY-MM.md`). |
+| `01_Projects/` | Algo con deadline o resultado definido. Cuando cierra, va a `04_Archive/`. |
+| `02_Areas/` | Responsabilidad continua sin fecha de fin (salud, finanzas, un rol). |
+| `03_Resources/` | Notas atómicas: una idea por nota, plano, sin subcarpetas. |
+| `04_Archive/` | Cerrado. Nunca se borra nada, se archiva. |
+| `Hubs/` | Una nota por entidad que importa: persona, herramienta, concepto, empresa. |
+| `Bases/` | Vistas `.base`. |
+| `Templates/` | Mis plantillas. Claude no las edita. |
+
+## Contrato de frontmatter
+
+Todo campo que se escriba tiene que estar acá. Un campo que no está declarado no se inventa: se propone y se agrega primero.
+
+```yaml
+---
+created: YYYY-MM-DD        # ISO, nunca se reescribe
+type: daily                # daily | weekly | monthly | dump | atomic | hub | project | area | clip
+status: seed               # madurez, solo en atomic, hub y clip (ver abajo)
+tags: []
+---
+```
+
+### `status`: madurez de la nota
+
+Solo para `atomic`, `hub` y `clip`. Las notas periódicas (`daily`, `weekly`, `monthly`, `dump`) no lo llevan: son registro, no conocimiento, y no maduran.
+
+| Valor | Significa | Efecto |
+|---|---|---|
+| `seed` | Apenas plantada, incompleta a propósito | No cuenta como hueca. Si sigue `seed` a los 30 días, el audit la marca: una semilla que no crecio es la falla clasica del vault. |
+| `provisional` | Tiene cuerpo pero no la sostendría en una discusión | Default de una nota recién escrita con contenido |
+| `evergreen` | Dice lo que tiene que decir. Puede quedarse quieta años | **No cuenta como stale.** Es lo que distingue una nota que ya hizo su trabajo de una abandonada. |
+| `contested` | Contradice a otra nota del vault y no está resuelto | El audit la lista para que un review la mire. La contradicción se preserva, no se resuelve sola. |
+| `archived` | Cerrada | Fuera del alcance del audit, viva donde viva |
+
+Sin este campo el audit no puede distinguir una nota de referencia que terminó su trabajo de un stub que nunca creció, y reporta las dos como stale.
+
+**Los proyectos usan el mismo campo con otro vocabulario** (`activo | pausado | cerrado`): es su ciclo de vida, no su madurez. El audit solo interpreta los cinco valores de arriba, así que un `activo` le resulta inerte y el proyecto se evalúa como cualquier otra nota. Si eso te molesta, renombralo acá y el contrato manda.
+
+Campos adicionales por tipo:
+
+| `type` | Campos propios |
+|---|---|
+| `project` | `status: activo \| pausado \| cerrado`, `deadline` (opcional), `repos:` si tiene código |
+| `clip` | `source` (URL), `author` (opcional) |
+| `hub` | `aliases` (nombres alternativos de la entidad), `repos:` si la entidad tiene código |
+
+`repos:` es el puente al código: la lista de repos que implementan esa entidad. Se traduce a path local en `codebases.md`. **El vault apunta, no copia:** la arquitectura vive en el repo.
+
+## Reglas de link
+
+- **Los links van hacia arriba, nunca hacia abajo.** Dump linkea a hubs y proyectos. Daily linkea al dump. Weekly linkea a los dailies. Monthly linkea a los weeklies. Los backlinks de Obsidian dan la dirección inversa gratis.
+- **Ninguna nota se cierra sin al menos un `[[wikilink]]`.** Si no hay a qué linkearla, falta un hub file.
+- `[[wikilinks]]` para lo interno, `[texto](url)` solo para URLs externas.
+
+## Tareas
+
+Las tareas viven en la nota a la que pertenecen, no en una lista central. Una tarea de un proyecto vive en la nota del proyecto; una que apareció en el día vive en el dump de ese día.
+
+**Una tarea abierta no se arrastra al día siguiente.** Queda en su día marcada como cancelada (`- [-]`) y se crea de nuevo donde corresponda. No haber hecho algo un día es información.
+
+## Qué puede hacer Claude
+
+- Crear y editar notas, clasificar el dump, actualizar hub files, generar dailies/weeklies/monthlies, buscar en el vault, proponer links.
+
+## Qué no puede hacer Claude
+
+- Borrar notas (mueve a `04_Archive/`).
+- Renombrar o mover notas sin que yo lo apruebe.
+- Editar `Templates/` ni nada dentro de `.obsidian/`.
+- Escribir la sección de reflexión de los reviews: los hechos los sintetiza Claude, la interpretación la escribo yo.
+- Editar en masa: los cambios que afectan muchas notas van por `/vault-tidy` con approval.
+
+## Plugins instalados
+
+<Completado por `/second-brain setup` con la detección real. Lo que no está en esta lista no se usa en las notas.>
+
+## Quién escribe qué
+
+- **Autorado** (lo escribo yo, Claude no lo toca sin approval): dumps, notas atómicas, hubs, clips, proyectos, este archivo, y la `## Reflexión` de los reviews.
+- **Sintetizado** (Claude lo escribe con mi OK y queda como nota): dailies, weeklies, monthlies, el `## Historial` de los hubs.
+- **Proyectado** (Claude lo reescribe sin preguntar, es derivado y descartable): `hot.md`, `.vault-index.json`, las vistas `.base`. No los edito a mano porque se pisan.
+
+## Uso desde otros proyectos
+
+Otros repos pueden leer este vault. El orden de lectura es `hot.md` → búsqueda con `vault_index.py` → el hub del tema → la nota. **No se lee el vault para preguntas generales de programación**, y no se escribe en él desde otro proyecto salvo pedido explícito. Receta completa: `/second-brain link`.
+
+## Git
+
+Este vault es un repo git. Antes de una corrida que escribe varias notas, el árbol tiene que estar limpio: es el único undo confiable.

package/skills/vault-audit/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: vault-audit
+description: "Reporte de salud del vault de Obsidian via script Python: huerfanas, links roto, notas stale, tag sprawl, nombres duplicados y frontmatter fuera de contrato. Read-only, no escribe nada. Triggers: auditar el vault, salud del vault, notas huerfanas, links roto, vault audit, que tan sano esta mi vault."
+argument-hint: "[--vault <path>] [--stale-days N] [--seed-days N] [--exempt <dir>] [-n 0]"
+category: "pkm"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Vault Audit - Salud del vault
+
+Medís el estado real del vault y explicás qué significan los números. **Este skill es read-only:** no escribe ni una línea en el vault. Los arreglos necesitan approval del usuario y los aplica `/vault-tidy`.
+
+Flags: `$ARGUMENTS`
+
+## Fase 1 - Correr el script
+
+El conteo lo hace Python, no vos: leer nota por nota para contar links cuesta cientos de miles de tokens en un vault real y da números peores.
+
+```bash
+python .claude/skills/vault-audit/scripts/vault_audit.py "<vault>" --format json
+```
+
+Flags útiles: `--stale-days N` (default 180), `--hollow-words N` (default 30), `--task-days N` (default 7), `--seed-days N` (default 30), `--require <campo>` (repetible, default `created` y `type`), `--exempt <carpeta>` (repetible, default `Templates` y `04_Archive`), `-n 0` para no truncar listas, `--audit-all` para auditar también las carpetas exentas.
+
+El script solo lee el filesystem: sin dependencias, corre sobre miles de notas en segundos.
+
+**Los defaults no son la verdad del vault: el `CLAUDE.md` lo es.** Antes de correr, leer su contrato y traducirlo a flags: los campos de frontmatter a `--require`, y los roles `templates` y `archive` a `--exempt`. Auditar un vault adoptado con los defaults produce hallazgos falsos (sus plantillas aparecen como huérfanas huecas) y esconde los reales.
+
+## Fase 2 - Interpretar
+
+Un hallazgo no es un problema hasta que sabés por qué está ahí. Las lecturas que importan:
+
+| Hallazgo | Qué suele significar | Cuándo NO es un problema |
+|---|---|---|
+| `orphans` | Notas que nadie linkea y que no linkean nada: el síntoma del vault-cementerio | Casi nunca. Es el hallazgo que más vale atacar. |
+| `no_backlinks` | Nada apunta a la nota, aunque ella sí apunta a otras | Notas de entrada (dashboards, hubs de primer nivel) |
+| `broken_links` | Link a una nota que no existe. Los `aliases` del frontmatter ya se resuelven, igual que en Obsidian, así que un `[[Nacho]]` que apunta al hub "Ignacio Martinez" no aparece acá | **Un link roto es muchas veces una intención, no un error:** es la nota que el usuario todavía no escribió. Distinguí typo de intención antes de proponer nada. |
+| `ambiguous_names` | Dos archivos con el mismo nombre en carpetas distintas | Nunca: hace que todo `[[link corto]]` a ese nombre resuelva de forma impredecible. Es el hallazgo más urgente aunque parezca menor. |
+| `stale` | Sin tocar en 180 días o más. Las `evergreen` **no** aparecen acá: ya dijeron lo que tenían que decir | Referencia que ya hizo su trabajo pero que nadie marcó `evergreen` todavía |
+| `stale_seeds` | Notas en `seed` hace más de 30 días | Casi nunca. Es la falla clásica del vault: las semillas nunca maduran. Es más grave que una huérfana porque no se ve. |
+| `contested` | Notas marcadas como contradictorias y sin resolver | Nunca es un error del vault: es el vault haciendo su trabajo. Va al `/review-monthly`, no a `/vault-tidy`. |
+| `hollow` | Menos de 30 palabras | Semilla reciente. Dejala crecer. |
+| `single_use_tags` | Tags usados una sola vez | Inocuo salvo que sean cientos: ahí hay confusión de vocabulario, no organización. |
+| `stale_open_tasks` | Tareas abiertas en un día que ya cerró | Es la regla de arrastre incumplida: había que cancelarlas en su día. |
+| `missing_frontmatter` | Campos del contrato ausentes | Notas viejas anteriores al contrato |
+| `orphan_attachments` | Imágenes y PDFs que nadie embebe | Ocupan espacio, no rompen nada |
+
+El campo `status` del contrato (`seed | provisional | evergreen | contested | archived`) es lo que hace accionables a `stale` y `hollow`: sin él, una nota de referencia que ya cumplió y un stub abandonado se reportan igual. `counts.by_status` te dice cuánto del vault está declarado y cuánto no.
+
+Dos métricas de tendencia valen más que cualquier lista: **`avg_links_per_note`** (si es baja, el vault es un archivo de documentos, no una red de ideas) y **`orphan_rate`**. Compará contra el monthly anterior si existe.
+
+## Fase 3 - Reportar
+
+1. Los conteos primero, en una tabla corta. Sin adornos.
+2. Los 3 a 5 hallazgos que valen la pena, ordenados por impacto real: `ambiguous_names` y `orphans` arriba, `hollow` y `single_use_tags` abajo o directamente omitidos si son ruido.
+3. **Si el reporte trae `truncated`, decirlo con el total real.** Un reporte truncado que no se anuncia se lee como un vault sano, y esa es la única mentira que este skill no puede cometer.
+4. Cerrar con una recomendación concreta: qué arreglaría primero y por qué.
+
+Audit COMPLETE cuando el usuario sabe los números, cuáles importan y cuál es el primer arreglo.
+
+## Reglas
+
+- No escribir en el vault. Ni una nota, ni un frontmatter, ni un link. Para eso está `/vault-tidy`.
+- No dramatizar los números: un vault de 2000 notas con 40 huérfanas está sano.
+- No proponer plugins como solución a un problema de higiene: menos plugins es más sano.
+- No sugerir borrar nada. El vocabulario es archivar.
+- Sin guiones largos en el reporte.
+
+## Handoff
+
+Con el reporte listo, el siguiente paso es `/vault-tidy` para aplicar los arreglos elegidos con approval item por item. Si el audit muestra muchas huérfanas del mismo tema, el arreglo real es `/hub-note` para el hub que falta. `/review-monthly` corre este audit como parte del cierre del mes.