brain-vault-audit

Perform a comprehensive health check of the vault: count files, find orphaned notes, check frontmatter consistency, identify stale content, analyze tag usage, and verify vault structure against brain.yaml. Output a formatted health report.

Step 1: Load Vault Configuration

Read brain.yaml to get the expected vault structure:

• vault.structure.* for expected directories
• preferences.frontmatter for whether frontmatter is expected
• preferences.wikilinks for whether wikilinks are expected
• preferences.format for format type (obsidian/plain)

Step 2: File Census

Count total .md files in each top-level directory and subdirectory:

Human/
  Daily/        -- {count} files
  Projects/     -- {count} files
  Archive/      -- {count} files
  (other)/      -- {count} files
Machine/
  Session-Logs/ -- {count} files
  Memory/       -- {count} files
  Rules/        -- {count} files
  Templates/    -- {count} files
  (other)/      -- {count} files
Total:          -- {count} files

Also note any directories that exist but are not defined in brain.yaml.

Step 3: Orphan Detection

If Obsidian CLI is available (run obsidian version to check), use the built-in orphan command:

obsidian orphans format=json

This returns a JSON array of file paths with zero incoming links. Parse and display grouped by directory.

If Obsidian CLI is not available, fall back to the manual approach below:

An orphaned file is one that has no incoming [[wikilinks]] from any other file in the vault.

1. Build a list of all .md files in the vault.
2. For each file, extract its basename (without extension) as its "link name."
3. Search all other files for [[link name]] references.
4. A file is orphaned if no other file links to it.

Exceptions (not orphans):

• Daily notes (Human/Daily/) -- these are date-indexed, not link-indexed
• Session logs (Machine/Session-Logs/) -- these are date-indexed
• Root config files (brain.yaml, CLAUDE.md, etc.)
• Template files (Machine/Templates/)
• Memory files (Machine/Memory/) -- these are system files
• Rules files (Machine/Rules/) -- these are system files

Report orphans grouped by directory.

Step 4: Frontmatter Consistency

For every .md file that should have frontmatter (per preferences.frontmatter):

1. Check if YAML frontmatter exists (file starts with ---).
2. Check for required fields: date, tags, type.
3. Check date format matches preferences.date_format.

Report:

• Files missing frontmatter entirely
• Files with incomplete frontmatter (missing required fields)
• Files with malformed dates

Step 5: Stale File Detection

Identify files not modified in 90+ days:

1. Check file modification times for all .md files.
2. Flag files older than 90 days.

Exceptions:

• Template files (expected to be stable)
• Rules files (expected to be stable unless updated)
• brain.yaml (configuration, not content)

Group stale files by directory and sort by age (oldest first).

Step 6: Tag Analysis

Scan all files for tags (both YAML frontmatter tags: and inline #tag format):

1. Build a frequency map of all tags.
2. Identify tags used fewer than 3 times ("low-usage tags").
3. Identify the most common tags (top 10).
4. Flag any tags that look like typos (similar to other tags, e.g., #proejct vs #project).

Step 7: Structure Validation

Compare the actual vault directory structure against brain.yaml vault.structure:

• Missing directories: Defined in config but do not exist
• Extra directories: Exist but not defined in config
• Empty directories: Exist but contain no files

Step 8: Generate Health Report

Output a formatted report:

# Vault Health Report
**Date:** {YYYY-MM-DD}
**Vault:** {vault path from brain.yaml}

## File Census
| Directory | Files | Notes |
|-----------|-------|-------|
| Human/Daily | {N} | |
| Human/Projects | {N} | |
| ... | | |
| **Total** | **{N}** | |

## Orphaned Files ({count})
{list of orphaned files, grouped by directory}
{or "No orphans found."}

## Frontmatter Issues ({count})
- `{path}` -- {issue description}
{or "All files have valid frontmatter."}

## Stale Files ({count}, >90 days)
- `{path}` -- last modified {date} ({N} days ago)
{or "No stale files found."}

## Tag Analysis
**Total unique tags:** {N}
**Most used:** {tag} ({N}), {tag} ({N}), ...
**Low usage (<3):** {tag} ({N}), {tag} ({N}), ...
**Possible typos:** {tag} -- did you mean {similar tag}?

## Structure Validation
- Missing directories: {list or "None"}
- Extra directories: {list or "None"}
- Empty directories: {list or "None"}

## Overall Health: {Good | Fair | Needs Attention}
{1-2 sentence summary of vault health}

Step 9: Offer Actions

After presenting the report, offer actionable suggestions:

• "Fix frontmatter on {N} files?"
• "Create missing directories?"
• "Review orphaned files for linking or archiving?"
• "Clean up stale files?"

Wait for user direction before taking any action.

- This is a read-only operation. Do NOT modify any files unless the user explicitly asks. - Report findings factually without judgment -- the user decides what to fix. - Daily notes and session logs are exempt from orphan detection. - Memory and rules files are exempt from orphan detection. - Be efficient with file reads -- use glob patterns and grep rather than reading every file in full. - If the vault is very large (500+ files), warn the user that the audit may take a moment. - Save the report to `Machine/vault-audit-{YYYY-MM-DD}.md` only if the user asks.

<success_criteria>

• Accurate file counts by directory
• Orphaned files correctly identified (with proper exemptions)
• Frontmatter consistency checked on all applicable files
• Stale files identified with modification dates
• Tag analysis with frequency data
• Structure validated against brain.yaml
• Clean, readable health report presented
• Actionable suggestions offered without auto-executing </success_criteria>