obsidian-knowledge 3.26.2__tar.gz → 3.26.3__tar.gz

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3}/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "obsidian-knowledge",
       "source": "./",
       "description": "Skills, hooks, and conventions for maintaining Obsidian knowledge base vaults",
-      "version": "3.26.2"
+      "version": "3.26.3"
     }
   ]
 }

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-knowledge",
-  "version": "3.26.2",
+  "version": "3.26.3",
   "description": "Claude Code plugin that manages an Obsidian knowledge vault: capture, organize, index, and garden",
   "author": {
     "name": "Ricardo Decal"

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-knowledge",
-  "version": "3.26.2",
+  "version": "3.26.3",
   "description": "Plugin that manages an Obsidian knowledge vault: capture, organize, index, and garden.",
   "author": {
     "name": "Ricardo Decal"

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: obsidian-knowledge
-Version: 3.26.2
+Version: 3.26.3
 Summary: Obsidian vault knowledge integration for Claude Code and Codex
 License-File: LICENSE
 Requires-Python: >=3.12

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3}/plugins/obsidian-knowledge/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-knowledge",
-  "version": "3.26.2+codex.20261003154117",
+  "version": "3.26.3+codex.20261003154117",
   "description": "Plugin that manages an Obsidian knowledge vault: capture, organize, index, and garden.",
   "author": {
     "name": "Ricardo Decal"

obsidian_knowledge-3.26.3/plugins/obsidian-knowledge/skills/vault-organizer/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: vault-organizer
+description: >-
+  This skill should be used when the user asks to "organize the vault",
+  "update indexes", "fix broken links", "rename ambiguous files", "fix
+  filenames", "garden the vault", "sync indexes", "clean up the vault",
+  "maintain the vault", or after making substantial structural edits
+  (creating, moving, renaming, or deleting files) in an Obsidian vault.
+  Also triggered by scheduled cron invocations for routine vault maintenance.
+version: 1.4.12
+---
+
+# Vault organizer
+
+Maintain indexes, links, filenames, and note locations. Preserve primary note
+content except for intended link and frontmatter repairs. Read each `lib/`
+reference only when its step applies.
+
+## Setup
+
+Set `SCRIPTS` to the directory containing the loaded `SKILL.md`. Use that copy,
+not an arbitrary plugin cache or the working directory. Scripts declare their
+own dependencies; run them with `uv run`.
+
+Scripts default to the configured vault containing cwd, or the sole registered
+vault. Pass a vault root as the first argument to override it. When multiple
+vaults are configured and cwd selects none, an explicit root is required.
+
+Read the vault's local instructions, `.claude/obsidian-knowledge.yaml`, and
+`Utility/obsidian-knowledge/needs-attention.md`. Set `VAULT_NAME` to its registered
+Obsidian name. Keep `vault="$VAULT_NAME"` before every Obsidian subcommand; after
+it, the CLI can silently ignore the option. Enable automatic internal-link
+updates in Obsidian.
+
+Exclude hidden files, protected sources, and Syncthing sync conflicts from
+maintenance. Handle conflicts separately. Use `obsidian-knowledge write` for
+manual Markdown edits; its writer verifies the result. Helpers already use it.
+
+## Structure
+
+```bash
+uv run "$SCRIPTS/vault-audit.py"
+```
+
+Triage all findings:
+
+- `MISSING_INDEX`, `NOT_INDEXED`: create or complete indexes using
+  [index conventions](lib/index-format.md). Read children to write useful
+  orientation phrases; a descendant link does not replace a child-index link.
+- `EMPTY_FOLDER`: check sync state and local layout. Do not create empty indexes
+  or delete folders automatically.
+- `DUMPING_GROUND`: classify misplaced dated, design, diary, and conversation
+  notes by meaning. Follow [note locations](lib/note-types.md).
+- `STACKED_FRONTMATTER`: use `uv run "$SCRIPTS/fix-stacked-frontmatter.py" --fix NOTE_PATH`.
+  `NEEDS_MERGE` requires [manual frontmatter repair](lib/stacked-frontmatter.md).
+
+Rename ambiguous files using [rename guidance](lib/rename-files.md).
+Use Obsidian move and rename commands so internal links update.
+
+## Links
+
+```bash
+obsidian vault="$VAULT_NAME" unresolved verbose format=json | uv run "$SCRIPTS/recover-unresolved-links.py"
+```
+
+Inspect the report. Add `--apply` for unique recoveries; triage remaining links
+using [broken-link guidance](lib/broken-links.md). Preserve aliases, headings,
+block references, and primary text. Leave intentional concept stubs intact.
+
+```bash
+obsidian vault="$VAULT_NAME" orphans
+```
+
+Add managed notes to their parent indexes where appropriate. Respect established
+exceptions and ignore orphans outside managed zones.
+
+## Conventions and reports
+
+```bash
+uv run "$SCRIPTS/convention-sweep.py"
+uv run "$SCRIPTS/find-open-questions.py" --apply
+```
+
+Fix `WIKILINK_EXT` (`.md` in note links), `UNDATED_FILE` (missing required date
+prefix), and `YAML_ERR`. The question report defaults to
+`Utility/obsidian-knowledge/reports/open-questions.md`, preserving its header,
+frontmatter, and scope. Use `--report` to preview or `--timestamp` to override
+current local time. With no flags, the scanner emits TSV.
+
+## Finish
+
+Re-run affected checks. Review changed links and fresh CLI results; reload
+Obsidian only if its cache disagrees with file contents. No checksum comparison
+is needed for an ordinary CLI move or rename.
+
+Update unresolved items in `needs-attention.md` and record completed vault
+changes in one same-session changelog fragment. Follow [state-file conventions](lib/state-files.md);
+do not edit a shared changelog index. Skip logging when no vault changes occurred.

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/convention-sweep.py

@@ -1,7 +1,11 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["pyyaml"]
+# ///
 """convention-sweep: vault-wide check for write-time convention violations.
 
-Usage: python3 convention-sweep.py <vault_root>
+Usage: uv run convention-sweep.py [vault_root]
 
 Walks all `.md` files under <vault_root> (skipping dotfolders, _sources/,
 .trash/, node_modules/) and runs the same three checks as the
@@ -22,31 +26,14 @@ needs-attention.md entry format.
 
 from __future__ import annotations
 
-import sys
+import argparse
 from pathlib import Path
 
+from organizer_context import resolve_vault
 
-# Import shared patterns module from hooks/lib/. Installed plugin layout is:
-#   <plugin>/hooks/hookslib/patterns.py
-#   <plugin>/skills/vault-organizer/convention-sweep.py
-# Source checkout layout is:
-#   <repo>/plugins/obsidian-knowledge/hooks/hookslib/patterns.py
-#   <repo>/skills/vault-organizer/convention-sweep.py
-def _find_hooks_dir() -> Path:
-    here = Path(__file__).resolve()
-    candidates = [
-        here.parent.parent.parent / "hooks",
-        here.parent.parent.parent / "plugins" / "obsidian-knowledge" / "hooks",
-    ]
-    for candidate in candidates:
-        if (candidate / "hookslib" / "patterns.py").exists():
-            return candidate
-    raise ModuleNotFoundError("Could not locate hooks/hookslib/patterns.py from convention-sweep.py")
-
-
-sys.path.insert(0, str(_find_hooks_dir()))
-
-from hookslib.patterns import (  # noqa: E402
+# isort: split
+# organizer_context puts the plugin's hooks on sys.path before this import.
+from hookslib.patterns import (
     DATE_PREFIX_RE,
     PERIODIC_NOTE_RE,
     find_wikilink_ext_violations,
@@ -111,14 +98,9 @@ def print_header(lib_dir: Path, counts: dict[str, int]) -> None:
 
 
 def main() -> None:
-    if len(sys.argv) < 2:
-        print(f"Usage: {sys.argv[0]} <vault_root>", file=sys.stderr)
-        sys.exit(1)
-
-    vault_root = Path(sys.argv[1]).resolve()
-    if not vault_root.is_dir():
-        print(f"Error: {vault_root} is not a directory", file=sys.stderr)
-        sys.exit(1)
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("vault_root", type=Path, nargs="?", help="default: configured vault")
+    vault_root = resolve_vault(parser.parse_args().vault_root)
 
     lib_dir = Path(__file__).parent / "lib"
     issues = sweep(vault_root)

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3}/plugins/obsidian-knowledge/skills/vault-organizer/edit-index.py

@@ -1,7 +1,11 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["pyyaml", "pydantic>=2"]
+# ///
 """Render reviewed JSON entries into one index section; --apply verifies writes.
 
-Usage: edit-index.py VAULT wiki/topic/index.md [--apply] < reviewed.json
+Usage: uv run edit-index.py [VAULT] wiki/topic/index.md [--apply] < reviewed.json
 Input: {"section": "Notes", "entries": [{"target": "wiki/topic/note",
          "description": "orientation", "label": "optional display name"}]}
 For a new flat index, supply "title" instead of "section". Existing prose and
@@ -15,6 +19,7 @@ import re
 import sys
 from pathlib import Path
 
+from organizer_context import resolve_vault
 from organizer_io import OrganizerPolicy, visible_path, write_checked
 from pydantic import BaseModel, ConfigDict, field_validator
 
@@ -156,12 +161,12 @@ def render_index(vault: Path, index: Path, before: str | None, review: IndexRevi
 
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("vault_root", type=Path)
+    parser.add_argument("vault_root", type=Path, nargs="?", help="default: configured vault")
     parser.add_argument("index_path")
     parser.add_argument("--apply", action="store_true")
     args = parser.parse_args()
     try:
-        vault = args.vault_root.resolve(strict=True)
+        vault = resolve_vault(args.vault_root)
         if Path(args.index_path).name != "index.md":
             raise ValueError("edit-index only edits index.md")
         index = OrganizerPolicy.load(vault).writable(vault, args.index_path)

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/filter-unresolved-links.py

@@ -1,8 +1,12 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["pyyaml"]
+# ///
 """filter-unresolved-links: filter `obsidian unresolved` JSON output.
 
 Usage:
-  obsidian unresolved verbose format=json | python3 filter-unresolved-links.py <vault_root>
+  obsidian unresolved verbose format=json | uv run filter-unresolved-links.py [vault_root]
 
 Reads `stub_link_patterns:` from <vault_root>/.claude/obsidian-knowledge.yaml
 to know which link names are intentional concept-stubs (not real broken
@@ -20,22 +24,19 @@ Emits the surviving entries one per line:
 
 from __future__ import annotations
 
+import argparse
 import json
 import re
 import signal
 import sys
 from pathlib import Path
 
+import yaml
+from organizer_context import resolve_vault
+
 # Don't crash with a BrokenPipeError when stdout is piped to head/less.
 signal.signal(signal.SIGPIPE, signal.SIG_DFL)
 
-try:
-    import yaml
-
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
-
 DEFAULT_STUB_PATTERNS = [
     r"^\(PAPER\) ",
     r"^\(VIDEO\) ",
@@ -56,7 +57,7 @@ def load_config(vault_root: Path) -> tuple[list[str], list[re.Pattern]]:
     patterns_raw = DEFAULT_STUB_PATTERNS
 
     config_path = vault_root / ".claude" / "obsidian-knowledge.yaml"
-    if HAS_YAML and config_path.exists():
+    if config_path.exists():
         with open(config_path) as f:
             cfg = yaml.safe_load(f) or {}
         zones = cfg.get("ai_managed", zones)
@@ -73,11 +74,9 @@ def is_stub(link: str, patterns: list[re.Pattern]) -> bool:
 
 
 def main() -> None:
-    if len(sys.argv) < 2:
-        print(f"Usage: {sys.argv[0]} <vault_root>", file=sys.stderr)
-        sys.exit(1)
-
-    vault_root = Path(sys.argv[1]).resolve()
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("vault_root", type=Path, nargs="?", help="default: configured vault")
+    vault_root = resolve_vault(parser.parse_args().vault_root)
     zones, patterns = load_config(vault_root)
     zone_prefixes = tuple(f"{z}/" for z in zones)
 

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/find-open-questions.py

@@ -1,7 +1,11 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["pyyaml", "pydantic>=2"]
+# ///
 """find-open-questions: scan ai_managed zones for `> [!question]` callouts.
 
-Usage: python3 find-open-questions.py <vault_root>
+Usage: uv run find-open-questions.py [vault_root]
 
 Skips matches inside fenced code blocks (``` or ~~~), which are usually
 documentation examples rather than real open questions. Emits one line per
@@ -9,8 +13,8 @@ hit:
 
   <relative_path>\t<line_number>\t<question_text>
 
-Add --report Utility/obsidian-knowledge/reports/open-questions.md to render
-Markdown for review, --timestamp for reproducible output, and --apply to write.
+Add --report to render the standard Markdown report, --timestamp for
+reproducible output, or --apply to regenerate the report in place.
 Reads ai_managed zones from
 <vault_root>/.claude/obsidian-knowledge.yaml; falls back to ['wiki'].
 """
@@ -23,18 +27,15 @@ import sys
 from datetime import datetime
 from pathlib import Path
 
+import yaml
+from organizer_context import resolve_vault
 from organizer_io import visible_path, write_checked
 from pydantic import BaseModel, ConfigDict
 
-try:
-    import yaml
-
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
-
 QUESTION_MARKER = "> [!question]"
 SCAN_SKIP_DIR_NAMES = {"_sources", ".trash", "node_modules"}
+# NOTE: Standard report location is documented in SKILL.md, Conventions and reports.
+REPORT_PATH = "Utility/obsidian-knowledge/reports/open-questions.md"
 
 
 class QuestionHit(BaseModel):
@@ -79,7 +80,7 @@ def render_report(before: str | None, hits: tuple[QuestionHit, ...], timestamp:
 
 def load_managed_zones(vault_root: Path) -> list[str]:
     config_path = vault_root / ".claude" / "obsidian-knowledge.yaml"
-    if HAS_YAML and config_path.exists():
+    if config_path.exists():
         with open(config_path) as f:
             cfg = yaml.safe_load(f) or {}
         return cfg.get("ai_managed", ["wiki"])
@@ -130,19 +131,14 @@ def scan_file(path: Path) -> list[tuple[int, str]]:
 
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("vault_root", type=Path)
-    parser.add_argument("--report", help="render the existing open-questions report (dry run)")
+    parser.add_argument("vault_root", type=Path, nargs="?", help="default: configured vault")
+    parser.add_argument("--report", nargs="?", const=REPORT_PATH, help="render the standard report (dry run)")
     parser.add_argument("--timestamp", help="timezone-aware ISO timestamp; default: current local time")
-    parser.add_argument(
-        "--apply", action="store_true", help="write the reviewed report using the verified writer"
-    )
+    parser.add_argument("--apply", action="store_true", help="regenerate the standard report")
     args = parser.parse_args()
-    if args.apply and not args.report:
-        parser.error("--apply requires --report")
-    vault_root = args.vault_root.resolve()
-    if not vault_root.is_dir():
-        print(f"Error: {vault_root} is not a directory", file=sys.stderr)
-        sys.exit(1)
+    if args.apply:
+        args.report = args.report or REPORT_PATH
+    vault_root = resolve_vault(args.vault_root)
 
     zones = load_managed_zones(vault_root)
     hits = []
@@ -166,7 +162,7 @@ def main() -> None:
             print(f"{hit.path}\t{hit.line}\t{hit.text}")
         return
     try:
-        if args.report != "Utility/obsidian-knowledge/reports/open-questions.md":
+        if args.report != REPORT_PATH:
             raise ValueError("--report must target Utility/obsidian-knowledge/reports/open-questions.md")
         stamp = datetime.fromisoformat(args.timestamp) if args.timestamp else datetime.now().astimezone()
         if stamp.utcoffset() is None:

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/fix-stacked-frontmatter.py

@@ -1,4 +1,8 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = []
+# ///
 """fix-stacked-frontmatter: detect and auto-fix stray duplicate `---` markers.
 
 The most common cause of STACKED_FRONTMATTER is a stray duplicate `---` line
@@ -10,8 +14,8 @@ are left alone and reported for manual review, since merging may need
 human judgment about which keys win.
 
 Usage:
-  python3 fix-stacked-frontmatter.py <file> [<file>...]            # dry run
-  python3 fix-stacked-frontmatter.py --fix <file> [<file>...]      # rewrite
+  uv run fix-stacked-frontmatter.py <file> [<file>...]            # dry run
+  uv run fix-stacked-frontmatter.py --fix <file> [<file>...]      # rewrite
 
 Exit 0 if no issues or all fixed; exit 1 if files need manual merge.
 """

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/lib/broken-links.md

@@ -2,13 +2,7 @@
 
 ## Unresolved links
 
-Use the vault and script paths set in the organizer skill:
-
-```bash
-obsidian vault="$VAULT_NAME" unresolved verbose format=json | uv run --no-project --with pyyaml python "$SCRIPTS/filter-unresolved-links.py" "$VAULT"
-```
-
-The filter keeps links from `ai_managed` zones and excludes template placeholders
+The recovery script keeps links from `ai_managed` zones and excludes template placeholders
 and configured `stub_link_patterns` from `.claude/obsidian-knowledge.yaml`.
 Defaults cover prefixes such as `(PAPER)`, `(BOOK)`, and `@Person`.
 
@@ -40,14 +34,9 @@ from candidates. Sources must be visible managed Markdown notes outside
 `_sources/` and configured read-only paths. Apply rechecks write policy and
 delegates to the verified writer; aliases, heading and block suffixes survive.
 
-Before repair, retain exact source bytes as a baseline. After repair, compare
-the diff and confirm only intended link targets changed. Primary prose, aliases,
-headings, block references, and frontmatter must remain intact. Then obtain
-fresh `obsidian vault="$VAULT_NAME" unresolved verbose format=json` results and
-confirm each repaired target disappeared from the relevant source's findings.
-If file contents and CLI results disagree, reload Obsidian with
-`obsidian vault="$VAULT_NAME" command id="app:reload"` and retry after it loads.
-Review fresh orphan results too; unrelated totals can change during sync.
+Review the diff for intended link changes, then check fresh unresolved-link
+results. If CLI results disagree with file contents, reload Obsidian with
+`obsidian vault="$VAULT_NAME" command id="app:reload"` and retry.
 
 ## Orphans
 

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/lib/index-format.md

@@ -64,15 +64,14 @@ accepts reviewed entries; it does not infer categories or descriptions:
 }
 ```
 
-Save the review as JSON, then render without writing:
+Pass reviewed entries as JSON:
 
 ```bash
-uv run --no-project --with pyyaml --with pydantic python "$SCRIPTS/edit-index.py" \
-  "$VAULT" wiki/topic/index.md < /tmp/index-review.json > /tmp/index-preview.md
+uv run "$SCRIPTS/edit-index.py" wiki/topic/index.md --apply < entries.json
 ```
 
-Inspect the diff against the current index, then repeat with `--apply`. Supply
-`"title": "Topic"` instead of `section` when creating a flat index. For an
+Omit `--apply` to preview. Supply `"title": "Topic"` instead of `section`
+when creating a flat index. For an
 existing sectioned index, `section` must identify one leaf heading exactly.
 Multiple entry blocks, continuation text, and fenced examples are refused for
 manual review.
@@ -81,7 +80,7 @@ Only the selected entry block is sorted: subfolder indexes first, then files
 alphabetically. Existing matching entries are updated; other prose and sections
 are preserved. Targets must exist and be visible. Protected sources, hidden
 paths, symlinks, read-only paths, and paths outside managed zones are refused.
-All applied writes use `obsidian-knowledge write` and verify final bytes.
+Applied writes use `obsidian-knowledge write`.
 
 ## Stale path-based wikilinks
 
@@ -94,11 +93,7 @@ prefix recovery and ambiguity rules.
 Always use the Obsidian CLI to move files; never use filesystem `mv`:
 
 ```bash
-obsidian vault="<vault>" move path="old/path.md" to="new/folder/file.md" silent
+obsidian vault="$VAULT_NAME" move path="old/path.md" to="new/folder/file.md" silent
 ```
 
-After each move, verify that the new path exists and the old path no longer
-exists within the configured filesystem root. CLI success text alone is
-insufficient. Then search
-the vault for the old filename to verify Obsidian updated all references. Fix any
-stale wikilinks found.
+Check the destination and repair any stale links left by the move.

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3}/plugins/obsidian-knowledge/skills/vault-organizer/lib/rename-files.md

@@ -22,14 +22,12 @@ there.
 3. Choose a descriptive name using the vault's `CLAUDE.md` conventions. Prefer
    dates from file content, then EXIF metadata, then the filename, then the
    parent folder. Omit the date when none is reliable.
-4. For a confident match, record the original file's SHA-256, then rename it:
+4. For a confident match, rename the file:
 
    ```bash
    obsidian vault="$VAULT_NAME" rename path="old/name.ext" name="new-name.ext"
    ```
 
-5. Verify the new path exists, its SHA-256 matches the original, and the old path
-   is gone. If content changed intentionally (such as orientation correction),
-   take the rename baseline after that change. Search for the old name
+5. Check the new path and search for the old name
    and repair stale links. For low-confidence cases, add the proposed name and
    reasoning to `needs-attention.md` instead of renaming.

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/lib/stacked-frontmatter.md

@@ -18,10 +18,10 @@ Replace `NOTE_PATH` with the note's filesystem path:
 
 ```bash
 # Dry run (reports what would change)
-uv run --no-project --with pyyaml python "$SCRIPTS/fix-stacked-frontmatter.py" NOTE_PATH
+uv run "$SCRIPTS/fix-stacked-frontmatter.py" NOTE_PATH
 
 # Apply the fix
-uv run --no-project --with pyyaml python "$SCRIPTS/fix-stacked-frontmatter.py" --fix NOTE_PATH
+uv run "$SCRIPTS/fix-stacked-frontmatter.py" --fix NOTE_PATH
 ```
 
 The script reports these output codes:

obsidian_knowledge-3.26.3/plugins/obsidian-knowledge/skills/vault-organizer/organizer_context.py

@@ -0,0 +1,30 @@
+"""Configured vault defaults for standalone gardener scripts."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "hooks"))
+from vault_registry import load_vault_roots
+
+
+def resolve_vault(explicit: Path | None = None) -> Path:
+    """Use an explicit root, the enclosing configured vault, or the sole vault."""
+    try:
+        if explicit is None:
+            roots = tuple(Path(root) for root in load_vault_roots())
+            cwd = Path.cwd().resolve()
+            explicit = next((root for root in roots if cwd.is_relative_to(root)), None)
+            if explicit is None:
+                if len(roots) != 1:
+                    raise ValueError("pass a vault path when no single configured vault applies")
+                explicit = roots[0]
+        root = explicit.expanduser().resolve(strict=True)
+        if not root.is_dir():
+            raise ValueError(f"not a vault directory: {root}")
+        return root
+    except (OSError, ValueError, yaml.YAMLError) as exc:
+        raise SystemExit(f"Error: {exc}") from exc

{obsidian_knowledge-3.26.2 → obsidian_knowledge-3.26.3/plugins/obsidian-knowledge}/skills/vault-organizer/recover-unresolved-links.py

@@ -1,9 +1,13 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["pyyaml", "pydantic>=2"]
+# ///
 """Classify and deterministically recover Obsidian unresolved wikilinks.
 
 Usage:
   obsidian unresolved verbose format=json \
-    | python3 recover-unresolved-links.py <vault_root> [--apply]
+    | uv run recover-unresolved-links.py [vault_root] [--apply]
 
 The script is intentionally conservative. It auto-fixes only unique exact
 filename/alias/path recoveries. Ambiguous and fuzzy-looking items are reported
@@ -22,6 +26,7 @@ from collections.abc import Iterable
 from difflib import SequenceMatcher
 from pathlib import Path
 
+import yaml as yaml_module
 from link_recovery_models import (
     DEFAULT_STUB_PATTERNS,
     CandidateIndex,
@@ -31,16 +36,9 @@ from link_recovery_models import (
     RecoveryDecision,
     UnresolvedItem,
 )
+from organizer_context import resolve_vault
 from organizer_io import OrganizerPolicy, visible_path, write_checked
 
-try:
-    import yaml as yaml_module
-
-    HAS_YAML = True
-except ImportError:  # pragma: no cover - exercised in packaged fallback contexts
-    yaml_module = None
-    HAS_YAML = False
-
 signal.signal(signal.SIGPIPE, signal.SIG_DFL)
 
 TEMPLATE_PLACEHOLDER = re.compile(r"\{\{|\<%")
@@ -50,7 +48,7 @@ WIKILINK_CHARS = set("|#^")
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("vault_root", type=Path)
+    parser.add_argument("vault_root", type=Path, nargs="?", help="default: configured vault")
     parser.add_argument(
         "--apply", action="store_true", help="rewrite exact/high-confidence recoveries in source files"
     )
@@ -65,9 +63,8 @@ def parse_args() -> argparse.Namespace:
 
 def load_config(vault_root: Path) -> Config:
     config_path = vault_root / ".claude" / "obsidian-knowledge.yaml"
-    if HAS_YAML and config_path.exists():
+    if config_path.exists():
         with open(config_path, encoding="utf-8") as handle:
-            assert yaml_module is not None
             raw = yaml_module.safe_load(handle) or {}
         return Config(
             ai_managed=tuple(str(zone) for zone in raw.get("ai_managed", ("wiki",))),
@@ -126,10 +123,9 @@ def frontmatter_aliases(text: str) -> tuple[str, ...]:
     if not text.startswith("---\n"):
         return ()
     end = text.find("\n---", 4)
-    if end == -1 or not HAS_YAML:
+    if end == -1:
         return ()
     try:
-        assert yaml_module is not None
         frontmatter = yaml_module.safe_load(text[4:end]) or {}
     except yaml_module.YAMLError:
         return ()
@@ -390,7 +386,7 @@ def emit(decisions: list[RecoveryDecision], output_format: str) -> None:
 
 def main() -> None:
     args = parse_args()
-    vault_root = args.vault_root.resolve()
+    vault_root = resolve_vault(args.vault_root)
     config = load_config(vault_root)
     patterns = tuple(re.compile(pattern) for pattern in config.stub_link_patterns)
     raw_items = json.load(sys.stdin)