claude-code-arcane 2.0.0 → 2.2.0

package/skills/ui-sound-design/references/anti-patterns.md

@@ -0,0 +1,57 @@
+# UI Sound Design — Anti-patterns
+
+## Sonidos de UI al nivel del gameplay
+
+Un click a −3 dB compite con la acción del juego y agota en minutos. El UI va entre −18 y −24 dB. Es el error más frecuente y el más fácil de arreglar.
+
+## Todo al mismo nivel
+
+Si el hover y el error de transacción suenan igual de importantes, no hay jerarquía y el usuario deja de prestar atención a los dos. Nivel y duración proporcionales a la importancia del evento.
+
+## Todo duckea
+
+Si cada navegación de menú baja la música, la música desaparece. Solo el nivel crítico duckea.
+
+## Sin cooldown en navegación
+
+Recorrer un menú rápido con el stick dispara el mismo tick veinte veces en 300 ms. Suena a glitch. Cooldown mínimo en todo evento de navegación.
+
+## Tonos sostenidos en 2-6 kHz
+
+Es la banda más sensible del oído y la que más fatiga. Un tono sostenido ahí cansa en una sesión. Transientes cortos.
+
+## Ignorar la sesión de audio en móvil
+
+Entra una llamada, la app pierde el audio y no lo recupera. O el juego suena con el switch de silencio activado. Los dos son rechazo de store. Manejar interrupciones y cambios de ruta explícitamente.
+
+## Forzar volumen por encima del sistema
+
+Normalizar hacia arriba o imponer un piso de volumen ignora una decisión explícita del usuario. Nunca.
+
+## Éxito y error que solo se distinguen por timbre
+
+Con pérdida de agudos, en un speaker malo o con el volumen bajo, los dos suenan igual. La diferencia tiene que estar en el contorno: ascendente para éxito, descendente para error.
+
+## Audio como único canal de información crítica
+
+Un usuario con hipoacusia, con el sonido apagado o en un lugar ruidoso pierde la información. Siempre acompañado de señal visual.
+
+## Haptic y audio desfasados
+
+Arriba de ~30 ms se perciben como dos eventos y se siente roto. Y si el haptic está desactivado, el evento no puede quedarse sin ningún feedback.
+
+## Duplicar información entre audio y haptic
+
+Si el haptic ya comunica intensidad, subir el audio para "reforzar" solo agrega molestia.
+
+## Depender del grave en dispositivos chicos
+
+Un sonido de UI cuyo peso vive en 80 Hz no existe en el speaker de un teléfono. Con haptics, el grave es trabajo del haptic; sin haptics, el sonido tiene que leerse en medios.
+
+## Un set sin toggle
+
+Los sonidos de navegación repetitivos tienen que poder apagarse, y apagarlos no debe silenciar los críticos. Controles de volumen separados de música y SFX.
+
+## Diseñar el set sin probar navegación real
+
+Un sonido aprobado clic por clic se vuelve insoportable cuando el usuario recorre seis pantallas en cuatro segundos. Probar con flujos reales, a velocidad real.

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.

package/skills/vault-audit/scripts/vault_audit.py

@@ -0,0 +1,539 @@
+"""
+vault_audit.py - Health report of an Obsidian vault. Counting only, never writes.
+
+No dependencies beyond the Python 3 standard library. Walks the vault once,
+resolves every [[wikilink]] the way Obsidian does, and emits the metrics a
+review session needs to decide what to fix: orphans, broken links, stale notes,
+tag sprawl, hollow notes, ambiguous filenames and frontmatter contract misses.
+
+The `status` field of the contract (seed | provisional | evergreen | contested |
+archived) changes what counts as a problem: evergreen notes are not stale, seeds
+are allowed to be short but not forever, and archived ones are out of scope.
+
+This exists because the same report built by reading notes through an agent
+costs hundreds of thousands of tokens on a real vault and gets the counts wrong.
+Python counts; the agent decides what the counts mean.
+
+Usage:
+    python vault_audit.py <vault> [--format json|text] [flags]
+
+Findings are capped per category (--limit) and every capped list reports its
+real total, so a truncated report never reads as a clean one.
+
+Errors go to stderr as {"error": "...", "code": "..."} with exit code 1.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+
+# Vault plumbing and sync leftovers: never notes, and walking them makes the
+# scan an order of magnitude slower on a synced vault.
+SKIP_DIRS = {
+    ".obsidian", ".git", ".trash", ".stfolder", ".stversions",
+    "node_modules", "__pycache__", ".smart-env",
+}
+
+# Scanned so links into them resolve, but excluded from the findings that would
+# be pure noise: a template is hollow and unlinked by design, and an archived
+# note is stale by definition. Override with --exempt when the vault names those
+# folders differently (its CLAUDE.md declares the mapping); --audit-all drops the
+# exemption entirely.
+EXEMPT_DIRS = ("Templates", "04_Archive")
+
+ATTACHMENT_EXTS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".pdf", ".mp3", ".mp4",
+    ".wav", ".m4a", ".mov", ".webm", ".canvas", ".base", ".excalidraw",
+}
+
+DEFAULT_STALE_DAYS = 180
+DEFAULT_HOLLOW_WORDS = 30
+DEFAULT_TASK_DAYS = 7
+DEFAULT_SEED_DAYS = 30
+DEFAULT_LIMIT = 25
+DEFAULT_REQUIRED_FIELDS = ("created", "type")
+
+# Maturity vocabulary of the frontmatter contract. Without it the audit cannot
+# tell a reference note that finished its job from a stub that never grew, so it
+# reports both as stale and the report stops being actionable.
+STATUS_EVERGREEN = "evergreen"
+STATUS_SEED = "seed"
+STATUS_CONTESTED = "contested"
+STATUS_ARCHIVED = "archived"
+
+FENCED_CODE = re.compile(r"^```.*?^```", re.DOTALL | re.MULTILINE)
+INLINE_CODE = re.compile(r"`[^`\n]*`")
+WIKILINK = re.compile(r"(!?)\[\[([^\[\]\n]+?)\]\]")
+# A tag can't start with a digit and can't be preceded by a word char, a slash
+# or another '#'. That rules out '## Heading', '#1', and url.com/x#fragment.
+INLINE_TAG = re.compile(r"(?<![\w/#])#([A-Za-z_][\w/-]*)")
+TASK = re.compile(r"^[ \t]*[-*+] \[(.)\]", re.MULTILINE)
+DATE_IN_NAME = re.compile(r"(\d{4})-(\d{2})-(\d{2})")
+
+
+def write_error(error, code):
+    sys.stderr.write(json.dumps({"error": error, "code": code}) + "\n")
+
+
+def strip_code(text):
+    """
+    Obsidian does not parse links or tags inside code, so neither do we. Without
+    this every snippet documenting wikilink syntax shows up as a broken link.
+    """
+    return INLINE_CODE.sub("", FENCED_CODE.sub("", text))
+
+
+def parse_frontmatter(text):
+    """
+    Minimal YAML subset: 'key: value', inline lists and block lists. Enough for
+    the frontmatter contract and tags, and it never raises on a malformed file.
+    Returns (fields, body_offset_in_lines).
+    """
+    lines = text.split("\n")
+    if not lines or lines[0].strip() != "---":
+        return {}, 0
+
+    fields = {}
+    key = None
+    for index in range(1, len(lines)):
+        raw = lines[index]
+        if raw.strip() == "---":
+            return fields, index + 1
+        if raw.startswith(("  - ", "- ", "\t- ")) and key:
+            # 'tags:' parsed a line earlier as an empty scalar; the first block
+            # item is what reveals it was a list all along.
+            if not isinstance(fields.get(key), list):
+                fields[key] = []
+            fields[key].append(raw.split("- ", 1)[1].strip().strip("\"'"))
+            continue
+        if ":" not in raw:
+            continue
+        key, _, value = raw.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if value.startswith("[") and value.endswith("]"):
+            items = [v.strip().strip("\"'") for v in value[1:-1].split(",")]
+            fields[key] = [v for v in items if v]
+        else:
+            fields[key] = value.strip("\"'")
+
+    # No closing '---': treat the file as bodyless frontmatter rather than
+    # silently reading the whole note as YAML.
+    return fields, len(lines)
+
+
+def collect_tags(fields, body):
+    tags = set()
+    declared = fields.get("tags")
+    if isinstance(declared, list):
+        tags.update(t.lstrip("#") for t in declared if t)
+    elif isinstance(declared, str) and declared:
+        tags.update(t.strip().lstrip("#") for t in declared.split(",") if t.strip())
+    tags.update(INLINE_TAG.findall(body))
+    return {t for t in tags if t}
+
+
+def link_target(raw):
+    """'folder/Note#Heading|Alias' -> 'folder/Note'. Empty for a same-note link."""
+    target = raw.split("|", 1)[0].strip()
+    target = target.split("#", 1)[0].strip()
+    return target
+
+
+def relative(path, root):
+    return os.path.relpath(path, root).replace(os.sep, "/")
+
+
+def resolve_exempt(args):
+    """
+    Folders scanned so links into them resolve, but kept out of the findings. A
+    vault that renamed them (an adopted vault keeps its own layout) passes
+    --exempt; argparse cannot carry a default for an append action without
+    appending to it, so the fallback lives here.
+    """
+    if not getattr(args, "exempt", None):
+        return EXEMPT_DIRS
+    return tuple(d.strip().strip("/").replace("\\", "/") for d in args.exempt if d.strip())
+
+
+def scan(root, args):
+    """One walk over the vault. Returns (notes, attachments)."""
+    exempt = resolve_exempt(args)
+    notes = {}
+    attachments = {}
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".."))
+        for filename in sorted(filenames):
+            full = os.path.join(dirpath, filename)
+            rel = relative(full, root)
+            _, ext = os.path.splitext(filename)
+            ext = ext.lower()
+
+            if ext != ".md":
+                if ext in ATTACHMENT_EXTS:
+                    attachments[rel] = {"path": rel, "embedded_by": []}
+                continue
+
+            try:
+                with open(full, "r", encoding="utf-8", errors="replace") as handle:
+                    text = handle.read()
+                mtime = os.stat(full).st_mtime
+            except OSError as e:
+                write_error("cannot read {0}: {1}".format(rel, e), "READ_FAILED")
+                continue
+
+            fields, body_start = parse_frontmatter(text)
+            body = strip_code("\n".join(text.split("\n")[body_start:]))
+            links, embeds = [], []
+            for bang, raw in WIKILINK.findall(body):
+                target = link_target(raw)
+                if not target:
+                    continue
+                (embeds if bang else links).append(target)
+
+            notes[rel] = {
+                "path": rel,
+                "name": os.path.splitext(filename)[0],
+                "fields": fields,
+                "tags": collect_tags(fields, body),
+                "links": links,
+                "embeds": embeds,
+                "words": len(body.split()),
+                "mtime": mtime,
+                "tasks": TASK.findall(body),
+                "status": str(fields.get("status") or "").strip().lower(),
+                "exempt": (rel.startswith(exempt)
+                           or str(fields.get("status") or "").strip().lower() == STATUS_ARCHIVED)
+                and not args.audit_all,
+            }
+
+    return notes, attachments
+
+
+def build_index(notes, attachments):
+    """
+    Obsidian resolves [[Name]] by unique basename anywhere in the vault, by path
+    when the link contains one, and by the `aliases` a note declares in its
+    frontmatter. Two files sharing a basename make every short link to that name
+    ambiguous, which is why by_name keeps every match.
+
+    Aliases are not a nicety here: hub notes exist to be linked by every name the
+    entity goes by, so ignoring them reports every [[Nacho]] as a broken link
+    while Obsidian resolves it fine.
+    """
+    by_path = {}
+    by_name = {}
+    by_alias = {}
+    for rel in list(notes) + list(attachments):
+        stem = rel[:-3] if rel.endswith(".md") else rel
+        by_path[stem.lower()] = rel
+        by_path[rel.lower()] = rel
+        by_name.setdefault(os.path.basename(stem).lower(), []).append(rel)
+    for rel, note in notes.items():
+        declared = (note.get("fields") or {}).get("aliases")
+        if isinstance(declared, str):
+            declared = [a.strip() for a in declared.split(",")]
+        for alias in declared or []:
+            if alias:
+                by_alias.setdefault(alias.strip().lower(), []).append(rel)
+    return by_path, by_name, by_alias
+
+
+def resolve(target, by_path, by_name, by_alias=None):
+    """Returns (resolved_path_or_None, is_ambiguous)."""
+    key = target.lower().rstrip("/")
+    if key in by_path:
+        return by_path[key], False
+    for candidates in (by_name.get(os.path.basename(key), []), (by_alias or {}).get(key, [])):
+        if len(candidates) == 1:
+            return candidates[0], False
+        if len(candidates) > 1:
+            return candidates[0], True
+    return None, False
+
+
+def audit(root, args):
+    # argparse's append action cannot carry a default without appending to it,
+    # so the fallback lives here: audit() has to stand on its own, not depend on
+    # main() having normalized its arguments first.
+    required = tuple(args.require) if args.require else DEFAULT_REQUIRED_FIELDS
+    notes, attachments = scan(root, args)
+    by_path, by_name, by_alias = build_index(notes, attachments)
+
+    backlinks = {rel: 0 for rel in notes}
+    broken = []
+    ambiguous_links = []
+    total_links = 0
+    now = time.time()
+
+    for note in notes.values():
+        for target in note["links"] + note["embeds"]:
+            total_links += 1
+            resolved, is_ambiguous = resolve(target, by_path, by_name, by_alias)
+            if resolved is None:
+                broken.append({"source": note["path"], "target": target})
+                continue
+            if is_ambiguous:
+                ambiguous_links.append({"source": note["path"], "target": target})
+            if resolved in backlinks:
+                backlinks[resolved] += 1
+            elif resolved in attachments:
+                attachments[resolved]["embedded_by"].append(note["path"])
+
+    tag_use = {}
+    for note in notes.values():
+        for tag in note["tags"]:
+            tag_use[tag] = tag_use.get(tag, 0) + 1
+
+    orphans, no_backlinks, stale, hollow, missing_fields, stale_tasks = [], [], [], [], [], []
+    stale_seeds, contested = [], []
+    by_status = {}
+    open_tasks = done_tasks = 0
+
+    for note in notes.values():
+        outgoing = len(note["links"]) + len(note["embeds"])
+        incoming = backlinks[note["path"]]
+        open_here = [t for t in note["tasks"] if t == " "]
+        open_tasks += len(open_here)
+        done_tasks += len([t for t in note["tasks"] if t in ("x", "X")])
+
+        if note["exempt"]:
+            continue
+
+        if not outgoing and not incoming:
+            orphans.append(note["path"])
+        elif not incoming:
+            no_backlinks.append(note["path"])
+
+        status = note["status"]
+        by_status[status or "(sin status)"] = by_status.get(status or "(sin status)", 0) + 1
+        if status == STATUS_CONTESTED:
+            contested.append(note["path"])
+
+        age_days = int((now - note["mtime"]) // 86400)
+
+        # A seed is allowed to be short, but not forever: a seed that never grew
+        # is the "notes go in, nothing matures" failure, and it is invisible
+        # unless the vault declares maturity. It reports here and nowhere else:
+        # the same note in stale and hollow too would read as three problems.
+        if status == STATUS_SEED:
+            if age_days >= args.seed_days:
+                stale_seeds.append({"path": note["path"], "days": age_days,
+                                    "words": note["words"]})
+        else:
+            # An evergreen note is meant to sit still: it already says what it
+            # has to say. Reporting it as stale trains the reader to ignore the
+            # whole list.
+            if age_days >= args.stale_days and status != STATUS_EVERGREEN:
+                stale.append({"path": note["path"], "days": age_days})
+            if note["words"] < args.hollow_words:
+                hollow.append({"path": note["path"], "words": note["words"]})
+
+        missing = [f for f in required if f not in note["fields"]]
+        if missing:
+            missing_fields.append({"path": note["path"], "missing": missing})
+
+        # Open tasks in a dated note (dump or daily) past the carry window: the
+        # vault convention says they should have been cancelled in place, not
+        # left hanging in a day that already closed.
+        dated = DATE_IN_NAME.search(os.path.basename(note["path"]))
+        if dated and open_here:
+            try:
+                note_age = int((now - time.mktime(time.strptime(dated.group(0), "%Y-%m-%d"))) // 86400)
+            except ValueError:
+                note_age = 0
+            if note_age >= args.task_days:
+                stale_tasks.append({
+                    "path": note["path"], "days": note_age, "open": len(open_here),
+                })
+
+    note_count = len(notes)
+    audited = len([n for n in notes.values() if not n["exempt"]])
+
+    return {
+        "vault": root,
+        "scanned_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "thresholds": {
+            "stale_days": args.stale_days,
+            "hollow_words": args.hollow_words,
+            "task_days": args.task_days,
+            "seed_days": args.seed_days,
+            "required_fields": list(required),
+            "exempt_dirs": [] if args.audit_all else list(resolve_exempt(args)),
+        },
+        "counts": {
+            "notes": note_count,
+            "notes_audited": audited,
+            "attachments": len(attachments),
+            "links": total_links,
+            "broken_links": len(broken),
+            "tags": len(tag_use),
+            "tasks_open": open_tasks,
+            "tasks_done": done_tasks,
+            "by_status": by_status,
+        },
+        "metrics": {
+            # The signal for whether this is a vault of ideas or a folder of
+            # documents. Counts embeds, since an embed is a real connection.
+            "avg_links_per_note": round(total_links / note_count, 2) if note_count else 0.0,
+            "orphan_rate": round(len(orphans) / audited, 3) if audited else 0.0,
+            "single_use_tag_rate": (
+                round(len([t for t, n in tag_use.items() if n == 1]) / len(tag_use), 3)
+                if tag_use else 0.0
+            ),
+        },
+        "findings": {
+            "orphans": orphans,
+            "no_backlinks": no_backlinks,
+            "broken_links": broken,
+            "ambiguous_links": ambiguous_links,
+            "ambiguous_names": [
+                {"name": name, "paths": paths}
+                for name, paths in sorted(by_name.items()) if len(paths) > 1
+            ],
+            "stale": sorted(stale, key=lambda s: -s["days"]),
+            "stale_seeds": sorted(stale_seeds, key=lambda s: -s["days"]),
+            "contested": contested,
+            "hollow": sorted(hollow, key=lambda h: h["words"]),
+            "single_use_tags": sorted(t for t, n in tag_use.items() if n == 1),
+            "orphan_attachments": sorted(
+                a["path"] for a in attachments.values() if not a["embedded_by"]
+            ),
+            "missing_frontmatter": missing_fields,
+            "stale_open_tasks": sorted(stale_tasks, key=lambda t: -t["days"]),
+        },
+    }
+
+
+def cap(report, limit):
+    """
+    Truncate every finding list, recording the real total. A capped list that
+    does not say so reads as 'nothing more to fix', which is the one lie a
+    health report must never tell.
+    """
+    if limit <= 0:
+        return report
+    totals = {}
+    for name, items in report["findings"].items():
+        totals[name] = len(items)
+        if len(items) > limit:
+            report["findings"][name] = items[:limit]
+    report["totals"] = totals
+    report["truncated"] = sorted(k for k, n in totals.items() if n > limit)
+    return report
+
+
+def format_text(report):
+    counts, metrics, totals = report["counts"], report["metrics"], report.get("totals", {})
+    out = [
+        "Vault: {0}".format(report["vault"]),
+        "{0} notes ({1} audited), {2} attachments, {3} links, {4} tags".format(
+            counts["notes"], counts["notes_audited"], counts["attachments"],
+            counts["links"], counts["tags"],
+        ),
+        "{0} links/note, {1} tasks open, {2} done".format(
+            metrics["avg_links_per_note"], counts["tasks_open"], counts["tasks_done"],
+        ),
+        "",
+    ]
+    labels = [
+        ("orphans", "orphans (no links in or out)"),
+        ("no_backlinks", "no backlinks (nothing points here)"),
+        ("broken_links", "broken links"),
+        ("ambiguous_names", "duplicate filenames (short links are ambiguous)"),
+        ("stale_open_tasks", "dated notes with tasks still open"),
+        ("stale", "stale notes"),
+        ("stale_seeds", "seeds that never grew"),
+        ("contested", "notes marked contested"),
+        ("hollow", "hollow notes"),
+        ("single_use_tags", "tags used once"),
+        ("orphan_attachments", "unused attachments"),
+        ("missing_frontmatter", "frontmatter contract misses"),
+        ("ambiguous_links", "links resolved ambiguously"),
+    ]
+    for key, label in labels:
+        total = totals.get(key, len(report["findings"][key]))
+        shown = len(report["findings"][key])
+        suffix = " (showing {0})".format(shown) if shown < total else ""
+        out.append("{0:>5}  {1}{2}".format(total, label, suffix))
+    return "\n".join(out)
+
+
+class JsonErrorParser(argparse.ArgumentParser):
+    """Keep the CLI's error contract: a JSON line on stderr and exit code 1."""
+
+    def error(self, message):
+        code = "NO_VAULT" if "vault" in message and "required" in message else "BAD_ARG"
+        write_error(message, code)
+        raise SystemExit(1)
+
+
+def build_parser():
+    parser = JsonErrorParser(
+        prog="vault_audit.py",
+        description="Health report of an Obsidian vault. Read-only: it never writes "
+        "to the vault. Notes under Templates/ and 04_Archive/ are scanned so links "
+        "resolve but excluded from findings unless --audit-all.",
+    )
+    parser.add_argument("vault", help="path to the vault (the directory containing .obsidian/)")
+    parser.add_argument("--format", choices=["json", "text"], default="json")
+    parser.add_argument("--stale-days", type=int, default=DEFAULT_STALE_DAYS,
+                        help="days without modification to count as stale. Default: 180")
+    parser.add_argument("--hollow-words", type=int, default=DEFAULT_HOLLOW_WORDS,
+                        help="word count below which a note is hollow. Default: 30")
+    parser.add_argument("--task-days", type=int, default=DEFAULT_TASK_DAYS,
+                        help="age of a dated note whose open tasks get flagged. Default: 7")
+    parser.add_argument("--require", action="append", metavar="FIELD",
+                        help="frontmatter field every note must declare (repeatable). "
+                             "Default: created, type")
+    parser.add_argument("-n", "--limit", type=int, default=DEFAULT_LIMIT,
+                        help="max items per finding list; 0 for no cap. Default: 25")
+    parser.add_argument("--seed-days", type=int, default=DEFAULT_SEED_DAYS,
+                        help="days after which a note still marked seed is flagged. Default: 30")
+    parser.add_argument("--exempt", action="append", metavar="DIR",
+                        help="folder scanned but kept out of the findings (repeatable). "
+                             "Default: Templates, 04_Archive")
+    parser.add_argument("--audit-all", action="store_true",
+                        help="include the exempt folders in the findings too")
+    return parser
+
+
+def force_utf8_streams():
+    """
+    On Windows stdout defaults to cp1252, so a note title with an accent raises
+    UnicodeEncodeError the moment output is piped to a file.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+
+
+def main():
+    force_utf8_streams()
+    args = build_parser().parse_args()
+    root = os.path.abspath(os.path.expanduser(args.vault))
+    if not os.path.isdir(root):
+        write_error("no such directory: {0}".format(args.vault), "NO_VAULT")
+        sys.exit(1)
+    if not os.path.isdir(os.path.join(root, ".obsidian")):
+        # Not fatal: a vault copied without its config, or a plain markdown
+        # folder, still audits fine. But the caller should know it is not one.
+        sys.stderr.write(
+            json.dumps({"warning": "no .obsidian/ found: auditing as a plain markdown folder",
+                        "code": "NOT_A_VAULT"}) + "\n"
+        )
+
+    report = cap(audit(root, args), args.limit)
+    if args.format == "text":
+        print(format_text(report))
+    else:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    main()