Skip to content

richfrem/agent-plugins-skills / plugins/agent-memory/.apm/skills/managing-obsidian-vaults

managing-obsidian-vaults

Verified

Interactive vault, wiki and Super-RAG setup in the main conversation. Use for "set up my wiki", "initialize the full knowledge stack" or combined RLM/vector/wiki setup. Manage Obsidian vaults and LLM wikis: initialize vaults, author Markdown and wikilinks, safely edit notes and Bases, create Canvas diagrams, traverse graphs, build concept wikis, distill summary/bullets/deep layers, query and lint knowledge.

FileKindSize
SKILL.mdskill md5.9 KB
assets/templates/config.yaml.templateother556 B
assets/templates/raw-sources.json.exampleother862 B
assets/templates/wiki-node.template.mdmarkdown410 B
evals/README.mdmarkdown569 B
evals/evals.jsonconfig23.4 KB
evals/legacy/obsidian-bases-manager/evals.jsonconfig692 B
evals/legacy/obsidian-bases-manager/results.tsvother301 B
evals/legacy/obsidian-canvas-architect/evals.jsonconfig731 B
evals/legacy/obsidian-canvas-architect/results.tsvother301 B
evals/legacy/obsidian-graph-traversal/evals.jsonconfig706 B
evals/legacy/obsidian-graph-traversal/results.tsvother301 B
evals/legacy/obsidian-init/evals.jsonconfig667 B
evals/legacy/obsidian-init/results.tsvother301 B
evals/legacy/obsidian-markdown-mastery/evals.jsonconfig652 B
evals/legacy/obsidian-markdown-mastery/results.tsvother301 B
evals/legacy/obsidian-query-agent/evals.jsonconfig767 B
evals/legacy/obsidian-rlm-distiller/evals.jsonconfig685 B
evals/legacy/obsidian-vault-crud/evals.jsonconfig638 B
evals/legacy/obsidian-vault-crud/results.tsvother301 B
evals/legacy/obsidian-wiki-builder/evals.jsonconfig732 B
evals/legacy/obsidian-wiki-linter/evals.jsonconfig1.5 KB
evals/results.tsvother73 B
evals/task-success.jsonconfig3.5 KB
references/acceptance-criteria.mdmarkdown2.9 KB
references/architecture-background.mdmarkdown2.8 KB
references/dependencies.mdmarkdown1.7 KB
references/interactive-setup.mdmarkdown7.0 KB
references/interactive-stack-setup.mdmarkdown5.6 KB
references/kepano-analysis-summary.mdmarkdown1.7 KB
references/obsidian-bases-manager-acceptance-criteria.mdmarkdown628 B
references/obsidian-bases-manager-fallback-tree.mdmarkdown787 B
references/obsidian-bases-manager.mdmarkdown2.1 KB
references/obsidian-canvas-architect-acceptance-criteria.mdmarkdown645 B
references/obsidian-canvas-architect-fallback-tree.mdmarkdown836 B
references/obsidian-canvas-architect.mdmarkdown1.9 KB
references/obsidian-graph-traversal-acceptance-criteria.mdmarkdown690 B
references/obsidian-graph-traversal-fallback-tree.mdmarkdown877 B
references/obsidian-graph-traversal.mdmarkdown2.2 KB
references/obsidian-init-acceptance-criteria.mdmarkdown650 B
references/obsidian-init-fallback-tree.mdmarkdown1.1 KB
references/obsidian-init.mdmarkdown2.0 KB
references/obsidian-markdown-mastery-acceptance-criteria.mdmarkdown700 B
references/obsidian-markdown-mastery-fallback-tree.mdmarkdown889 B
references/obsidian-markdown-mastery.mdmarkdown2.2 KB
references/obsidian-query-agent.mdmarkdown1.8 KB
references/obsidian-rlm-distiller.mdmarkdown1.8 KB
references/obsidian-vault-crud-acceptance-criteria.mdmarkdown833 B
references/obsidian-vault-crud-fallback-tree.mdmarkdown1.1 KB
references/obsidian-vault-crud.mdmarkdown2.2 KB
references/obsidian-vault-onboarding-guide.mdmarkdown3.7 KB
references/obsidian-wiki-builder.mdmarkdown1.8 KB
references/obsidian-wiki-linter.mdmarkdown1.7 KB
references/resource-index.mdmarkdown4.3 KB
references/safety-learnings.mdmarkdown2.7 KB
references/wiki-builder-guide.mdmarkdown2.7 KB
references/wiki-distillation-guide.mdmarkdown1.7 KB
references/wiki-linting-guide.mdmarkdown2.1 KB
references/wiki-query-guide.mdmarkdown2.1 KB
requirements.inother32 B
requirements.txtmanifest463 B
scripts/audit.pyscript9.0 KB
scripts/bases_ops.pyscript7.8 KB
scripts/canvas_gen.pyscript7.9 KB
scripts/canvas_ops.pyscript11.5 KB
scripts/concept_extractor.pyscript10.2 KB
scripts/constants.pyscript908 B
scripts/distill_wiki.pyscript12.9 KB
scripts/graph_ops.pyscript11.7 KB
scripts/ingest.pyscript8.3 KB
scripts/init_vault.pyscript5.7 KB
scripts/lint_wiki.pyscript9.3 KB
scripts/obsidian-parser/parser.pyscript6.5 KB
scripts/obsidian-parser/tests/test_parser.pyscript4.1 KB
scripts/query_wiki.pyscript21.3 KB
scripts/raw_manifest.pyscript14.3 KB
scripts/vault_ops.pyscript13.4 KB
scripts/wiki_builder.pyscript14.3 KB

scripts/audit.py

View on GitHub
#!/usr/bin/env python
"""
audit.py
=====================================

Purpose:
    Wiki health audit. Checks for orphan nodes, missing RLM summaries,
    stale source files, and broken wikilinks. Prints a human-readable
    report and exits non-zero if critical issues are found.

Layer: Audit / Wiki

Usage:
    python ./scripts/audit.py --wiki-root /path/to/wiki-root
    python ./scripts/audit.py --wiki-root /path/to/wiki-root --fix-stale
    python ./scripts/audit.py --wiki-root /path/to/wiki-root --json

Related:
    - raw_manifest.py  (WikiSourceConfig, agent-memory.json)
    - distill_wiki.py  (fixes missing summaries)
    - ingest.py        (fixes stale nodes)

Key Input Dependencies:
    - {wiki_root}/wiki/*.md nodes, {wiki_root}/rlm/ summaries, agent-memory.json
"""
import sys
import json
import argparse
import re
from pathlib import Path
from typing import Dict, List, Any

SCRIPT_DIR = Path(__file__).resolve().parent
if str(SCRIPT_DIR) not in sys.path:
    sys.path.insert(0, str(SCRIPT_DIR))

from raw_manifest import (
    WikiSourceConfig, load_agent_memory, save_agent_memory,
    compute_hash, now_iso
)

LAYERS = ["summary", "bullets", "deep"]


def audit_missing_summaries(wiki_root: Path) -> List[str]:
    """
    List concept slugs with a wiki node but no summary.md RLM layer.

    Returns:
        List of concept slugs missing at least one RLM layer.
    """
    wiki_dir = wiki_root / "wiki"
    if not wiki_dir.exists():
        return []
    missing = []
    for node_file in sorted(wiki_dir.glob("*.md")):
        if node_file.name.startswith("_"):
            continue
        concept = node_file.stem
        if not (wiki_root / "rlm" / concept / "summary.md").exists():
            missing.append(concept)
    return missing


def audit_stale_nodes(wiki_root: Path) -> List[Dict[str, str]]:
    """
    Find wiki nodes whose source file content has changed since last ingest.

    Returns:
        List of dicts with 'key' and 'reason' fields.
    """
    memory = load_agent_memory(wiki_root)
    stale = []
    for key, entry in memory.items():
        parts = key.split("/", 1)
        if len(parts) < 2:
            continue
        source_name, rel_path = parts

        try:
            cfg = WikiSourceConfig(source_name, wiki_root=wiki_root)
        except SystemExit:
            stale.append({"key": key, "reason": f"Source '{source_name}' no longer registered"})
            continue

        file_path = cfg.source_path / rel_path
        if not file_path.exists():
            stale.append({"key": key, "reason": "Source file deleted"})
            continue

        try:
            content = file_path.read_text(encoding="utf-8", errors="replace")
        except Exception:
            stale.append({"key": key, "reason": "Unreadable"})
            continue

        if compute_hash(content) != entry.get("hash", ""):
            stale.append({"key": key, "reason": "Content changed since last ingest"})

    return stale


def audit_orphan_nodes(wiki_root: Path) -> List[str]:
    """
    Find wiki nodes whose source file no longer exists.

    A node is orphaned when the 'source_file' frontmatter path resolves to a
    file that is no longer on disk.

    Returns:
        List of concept slugs that are orphaned.
    """
    wiki_dir = wiki_root / "wiki"
    if not wiki_dir.exists():
        return []

    memory = load_agent_memory(wiki_root)
    indexed_concepts = {v.get("concept") for v in memory.values() if v.get("concept")}

    orphans = []
    for node_file in sorted(wiki_dir.glob("*.md")):
        if node_file.name.startswith("_"):
            continue
        concept = node_file.stem
        if concept not in indexed_concepts:
            orphans.append(concept)
    return orphans


def audit_broken_wikilinks(wiki_root: Path) -> List[Dict[str, str]]:
    """
    Scan all wiki nodes for [[wikilinks]] that point to non-existent concepts.

    Returns:
        List of dicts with 'node', 'broken_link' fields.
    """
    wiki_dir = wiki_root / "wiki"
    if not wiki_dir.exists():
        return []

    existing = {f.stem for f in wiki_dir.glob("*.md") if not f.name.startswith("_")}
    broken = []
    wikilink_pattern = re.compile(r"\[\[([^\]|#]+)")

    for node_file in sorted(wiki_dir.glob("*.md")):
        if node_file.name.startswith("_"):
            continue
        try:
            content = node_file.read_text(encoding="utf-8")
        except Exception:
            continue
        for match in wikilink_pattern.finditer(content):
            link_target = match.group(1).strip()
            if link_target not in existing:
                broken.append({"node": node_file.stem, "broken_link": link_target})

    return broken


def audit_source_paths(wiki_root: Path) -> List[Dict[str, str]]:
    """
    Check that all registered source paths in wiki_sources.json exist on disk.

    Returns:
        List of dicts with 'source_name' and 'path' for missing sources.
    """
    sources = WikiSourceConfig.all_sources(wiki_root=wiki_root)
    missing = []
    for name, cfg in sources.items():
        if not cfg.source_path.exists():
            missing.append({"source_name": name, "path": str(cfg.source_path)})
    return missing


def fix_stale_memory(wiki_root: Path, stale: List[Dict[str, str]]) -> None:
    """
    Remove stale entries from agent-memory.json so ingest re-processes them.

    Args:
        wiki_root: Root of the wiki output directory.
        stale:     Output of audit_stale_nodes().
    """
    memory = load_agent_memory(wiki_root)
    for entry in stale:
        key = entry["key"]
        if key in memory:
            del memory[key]
            print(f"  [FIX] Removed stale entry: {key}")
    save_agent_memory(memory, wiki_root)


def _status(count: int, warn_level: int = 1) -> str:
    """Return a '[WARN] ' or '[OK]   ' prefix based on whether count meets the warn threshold."""
    return "[WARN] " if count >= warn_level else "[OK]   "


def _build_audit_report(wiki_root: Path) -> Dict[str, Any]:
    """Run all audit checks against wiki_root and assemble the report dict."""
    wiki_dir = wiki_root / "wiki"
    total_nodes = len([f for f in wiki_dir.glob("*.md") if not f.name.startswith("_")]) if wiki_dir.exists() else 0

    return {
        "wiki_root": str(wiki_root),
        "audited_at": now_iso(),
        "total_nodes": total_nodes,
        "missing_summaries": audit_missing_summaries(wiki_root),
        "stale_nodes": audit_stale_nodes(wiki_root),
        "orphan_nodes": audit_orphan_nodes(wiki_root),
        "broken_wikilinks": audit_broken_wikilinks(wiki_root),
        "missing_sources": audit_source_paths(wiki_root),
    }


def _print_audit_report(report: Dict[str, Any]) -> None:
    """Print the human-readable audit report with WARN/OK status prefixes."""
    missing_summaries = report["missing_summaries"]
    stale_nodes = report["stale_nodes"]
    orphan_nodes = report["orphan_nodes"]
    broken_links = report["broken_wikilinks"]
    missing_sources = report["missing_sources"]

    print(f"\n[AUDIT] Wiki Root: {report['wiki_root']}")
    print(f"[OK]    Total nodes       : {report['total_nodes']}")
    print(f"{_status(len(missing_summaries))}Missing RLM summaries : {len(missing_summaries)}"
          + ("  -> run /wiki-distill" if missing_summaries else ""))
    print(f"{_status(len(stale_nodes))}Stale nodes           : {len(stale_nodes)}"
          + ("  -> run /wiki-ingest" if stale_nodes else ""))
    print(f"{_status(len(orphan_nodes), 1)}Orphan nodes          : {len(orphan_nodes)}"
          + ("  -> source files deleted" if orphan_nodes else ""))
    print(f"{_status(len(broken_links))}Broken wikilinks      : {len(broken_links)}"
          + ("  -> run /wiki-rebuild" if broken_links else ""))
    print(f"{_status(len(missing_sources))}Missing source paths  : {len(missing_sources)}"
          + ("  -> update wiki_sources.json" if missing_sources else ""))


def main() -> None:
    """Run the wiki audit and print a health report."""
    parser = argparse.ArgumentParser(description="Audit the Obsidian LLM wiki for health issues")
    parser.add_argument("--wiki-root", required=True, help="Path to the wiki root directory")
    parser.add_argument("--fix-stale", action="store_true",
                        help="Remove stale entries from agent-memory.json (triggers re-ingest on next run)")
    parser.add_argument("--json", dest="output_json", action="store_true",
                        help="Output audit results as JSON")
    args = parser.parse_args()

    wiki_root = Path(args.wiki_root).resolve()
    report = _build_audit_report(wiki_root)

    if args.output_json:
        print(json.dumps(report, indent=2))
        return

    _print_audit_report(report)

    if args.fix_stale and report["stale_nodes"]:
        print(f"\n[FIX] Removing {len(report['stale_nodes'])} stale entries from agent-memory.json...")
        fix_stale_memory(wiki_root, report["stale_nodes"])
        print("      Done. Run /wiki-ingest to re-process.")

    critical = len(report["missing_sources"]) + len(report["orphan_nodes"])
    sys.exit(1 if critical > 0 else 0)


if __name__ == "__main__":
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall