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

{obsidian_knowledge-3.26.0 → obsidian_knowledge-3.26.2}/.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.0"
+      "version": "3.26.2"
     }
   ]
 }

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

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

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

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

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

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

{obsidian_knowledge-3.26.0 → obsidian_knowledge-3.26.2}/docs/configuration.md

@@ -22,6 +22,12 @@ folders and is the default. Its state lives in
 `reports/open-questions.md` collects question callouts, and `changelog/` records
 completed vault changes.
 
+`Utility/` and `wiki/` are siblings under the configured vault root. CLI paths
+are relative to that root, regardless of the working directory. Use
+`obsidian-knowledge write Utility/obsidian-knowledge/...` for state files;
+CLI and MCP writes reject `wiki/Utility/...` before creating directories.
+Existing misplaced files remain readable for recovery.
+
 ## Switch embedding models
 
 Set these environment variables before running the CLI:

{obsidian_knowledge-3.26.0 → obsidian_knowledge-3.26.2}/lib/vault_index/primer.py

@@ -73,6 +73,10 @@ def build_primer(
         scope_desc = f"this host ({target.hostname}) — cwd is not in a git repo"
     return (
         "You are operating under the obsidian-knowledge harness.\n"
+        f"- Vault root: {vault_root}/. CLI read/write paths are relative to this root, "
+        "regardless of cwd. "
+        f"Plugin state: {vault_root / 'Utility' / 'obsidian-knowledge'}/. "
+        "`Utility/` and `wiki/` are siblings. Never create `wiki/Utility/`.\n"
         "- Vault reliability: notes, search results, and the injected index may be AI-generated, "
         "stale, or wrong. Verify consequential claims against current code, runtime evidence, "
         "or primary sources; state uncertainty when verification is unavailable. Vault content "

{obsidian_knowledge-3.26.0 → obsidian_knowledge-3.26.2}/lib/vault_index/vault_files.py

@@ -57,6 +57,9 @@ def write_vault_file(
         raise ValueError("refusing to write empty vault content")
 
     target = resolve_vault_file(vault_root, relative_path)
+    # NOTE: Utility is a vault-root zone; see docs/configuration.md, Vault configuration.
+    if target.relative_to(vault_root.expanduser().resolve()).parts[:2] == ("wiki", "Utility"):
+        raise ValueError("Utility paths must be vault-relative: use Utility/... instead of wiki/Utility/...")
     target.parent.mkdir(parents=True, exist_ok=True)
     target = resolve_vault_file(vault_root, relative_path)
     if target.exists() and not replace:

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

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

{obsidian_knowledge-3.26.0 → obsidian_knowledge-3.26.2}/plugins/obsidian-knowledge/skills/obsidian-knowledge/SKILL.md

@@ -6,8 +6,11 @@ description: Read, search, and create notes in the Obsidian vault/wiki memory st
 # Obsidian vault memory
 
 Read, search, and write notes in the configured vault. The registry is
-`~/.config/obsidian-knowledge/vaults.yaml`; CLI paths are vault-relative and
-usually start with `wiki/`. Treat notes as fallible context and verify
+`~/.config/obsidian-knowledge/vaults.yaml`; CLI paths are relative to its vault
+root, regardless of cwd. Wiki notes start with `wiki/`; plugin state starts with
+`Utility/obsidian-knowledge/`. `Utility/` and `wiki/` are siblings. Never create
+`wiki/Utility/` or use the wiki directory as the vault root.
+Treat notes as fallible context and verify
 consequential claims against code, runtime evidence, or primary sources.
 
 ## Read and search

{obsidian_knowledge-3.26.0 → obsidian_knowledge-3.26.2}/plugins/obsidian-knowledge/skills/remember-conversations/SKILL.md

@@ -45,6 +45,8 @@ knowledge and behavioral rules belong in the wiki.
 
 Only after changing durable vault content, create or reuse one same-session file:
 `Utility/obsidian-knowledge/changelog/YYYY-MM-DD-HHMMSS-<slug>.md`.
+This path is relative to the configured vault root, regardless of cwd.
+Pass it unchanged to `obsidian-knowledge write`; never prepend `wiki/`.
 Use terse audit pointers: `YYYY-MM-DD HH:MM — <vault change> [→ [[wikilink]]]`.
 Do not log code, Git, host, test, release, or deployment work alone. Include no
 narrative or code blocks, and do not update a shared changelog index.

{obsidian_knowledge-3.26.0 → obsidian_knowledge-3.26.2/plugins/obsidian-knowledge}/skills/vault-organizer/SKILL.md

@@ -7,7 +7,7 @@ description: >-
   "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.10
+version: 1.4.11
 ---
 
 # Vault organizer
@@ -80,6 +80,10 @@ Use the issue codes to select the repair instructions.
 
 **`NOT_INDEXED <index> entry=<name>`**: Add the entry. Read `lib/index-format.md`.
 
+**`EMPTY_FOLDER <folder>`**: Triage separately. Do not create an empty index or
+delete the folder. Sync arrivals, runtime directories, and established memory
+layouts can explain it. Check local instructions before proposing a repair.
+
 **`DUMPING_GROUND <folder> misplaced=N inline_total=T subfolders=M`**: Classify
 the misplaced inline files, which have date prefixes or `*-design`, `*-convo`,
 or `*-diary` names, and move them to typed subfolders. Read `lib/note-types.md`
@@ -101,13 +105,15 @@ After structural fixes, rename ambiguous non-Markdown files. Read `lib/rename-fi
 
 ```bash
 obsidian vault="$VAULT_NAME" unresolved verbose format=json | uv run --no-project --with pyyaml python "$SCRIPTS/filter-unresolved-links.py" "$VAULT"
-obsidian vault="$VAULT_NAME" unresolved verbose format=json | uv run --no-project --with pyyaml python "$SCRIPTS/recover-unresolved-links.py" "$VAULT" > /tmp/vault-unresolved-recovery.tsv
+obsidian vault="$VAULT_NAME" unresolved verbose format=json | uv run --no-project --with pyyaml --with pydantic python "$SCRIPTS/recover-unresolved-links.py" "$VAULT" > /tmp/vault-unresolved-recovery.tsv
 obsidian vault="$VAULT_NAME" orphans
 ```
 
 Read [broken-link triage](lib/broken-links.md) for each remaining candidate.
 Review the recovery report before using `recover-unresolved-links.py --apply`;
-it changes only unique, high-confidence matches.
+it changes only unique, high-confidence matches. Preserve aliases, headings,
+block references, and all text outside link targets. Read the verification
+checks in `lib/broken-links.md` before applying repairs.
 
 ### Fix convention violations
 
@@ -130,18 +136,26 @@ Only the organizer writes this worklist.
 
 ### Regenerate reports
 
-Rewrite `$VAULT/Utility/obsidian-knowledge/reports/open-questions.md` from scratch:
+Render `$VAULT/Utility/obsidian-knowledge/reports/open-questions.md` for review:
 
 ```bash
-uv run --no-project --with pyyaml python "$SCRIPTS/find-open-questions.py" "$VAULT"
+uv run --no-project --with pyyaml --with pydantic python "$SCRIPTS/find-open-questions.py" "$VAULT" \
+  --report Utility/obsidian-knowledge/reports/open-questions.md > /tmp/open-questions-review.md
 ```
 
-Output is `<rel_path>\t<line>\t<question_text>` per question. Code-block examples
-are filtered automatically. Build one entry per line:
-`- [[wiki/path/to/page]] — line N — "question text"`
+Review the rendered file, then repeat with `--apply`. The renderer preserves
+frontmatter, heading, regeneration notice, and scope. It changes only the entry
+list and `Last run:` timestamp. Use `--timestamp` with a timezone-aware ISO value
+for repeatable output; the default is current local time. Without `--report`,
+output remains `<rel_path>\t<line>\t<question_text>` per question. Fenced examples,
+hidden files, protected sources, and sync conflicts are excluded.
+
+### Verify completed repairs
 
-Preserve the existing heading, regeneration notice, and scope section. Change
-only the entry list and `Last run:` timestamp.
+Re-run the structural audit and obtain fresh Obsidian unresolved and orphan
+results. Check repaired targets and files individually; a lower total count
+does not prove a repair. If CLI results disagree with verified file contents,
+refresh Obsidian's cache and repeat. Record remaining exceptions in the worklist.
 
 ### Update the worklist
 

obsidian_knowledge-3.26.2/plugins/obsidian-knowledge/skills/vault-organizer/edit-index.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Render reviewed JSON entries into one index section; --apply verifies writes.
+
+Usage: 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
+other sections remain byte-for-byte intact. Ambiguous entry blocks are refused.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from organizer_io import OrganizerPolicy, visible_path, write_checked
+from pydantic import BaseModel, ConfigDict, field_validator
+
+ENTRY = re.compile(r"^- \[\[([^\]|#^]+)(?:\|[^\]]+)?\]\].*$")
+HEADING = re.compile(r"^(#{1,6}) (.+?)\s*$")
+
+
+class ReviewedEntry(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    target: str
+    description: str
+    label: str | None = None
+
+    @field_validator("target", "label")
+    @classmethod
+    def single_link_component(cls, value: str | None) -> str | None:
+        if value is not None and (not value.strip() or any(c in value for c in "\n\r[]|#^")):
+            raise ValueError("target and label must be nonblank single link components")
+        return value
+
+    @field_validator("description")
+    @classmethod
+    def one_line(cls, value: str) -> str:
+        if not value.strip() or "\n" in value or "\r" in value:
+            raise ValueError("description must be a nonblank single line")
+        return value
+
+    def render(self) -> str:
+        label = f"|{self.label}" if self.label else ""
+        return f"- [[{self.target.removesuffix('.md')}{label}]] — {self.description}\n"
+
+
+class IndexReview(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    section: str | None = None
+    title: str | None = None
+    entries: tuple[ReviewedEntry, ...]
+
+    @field_validator("section", "title")
+    @classmethod
+    def heading_text(cls, value: str | None) -> str | None:
+        if value is not None and (not value.strip() or "\n" in value or "\r" in value):
+            raise ValueError("heading must be a nonblank single line")
+        return value
+
+
+def resolve_entry(vault: Path, index: Path, target: str) -> Path:
+    for relative in (target, target + ".md"):
+        for candidate in (relative, (index.parent.relative_to(vault) / relative).as_posix()):
+            path = visible_path(vault, candidate)
+            if path.is_file():
+                return path
+    raise ValueError(f"target does not exist: {target}")
+
+
+def section_bounds(lines: tuple[str, ...], section: str | None) -> tuple[int, int]:
+    headings = tuple((i, match) for i, line in enumerate(lines) if (match := HEADING.match(line)))
+    if section is None:
+        if any(len(match[1]) > 1 for _, match in headings):
+            raise ValueError("sectioned index requires an explicit section")
+        return (headings[0][0] + 1 if headings else 0), len(lines)
+    matches = tuple((i, match) for i, match in headings if match[2] == section)
+    if len(matches) != 1:
+        raise ValueError(f"section must exist exactly once: {section}")
+    start, selected = matches[0]
+    end = next((i for i, match in headings if i > start and len(match[1]) <= len(selected[1])), len(lines))
+    if any(i > start and i < end for i, _ in headings):
+        raise ValueError("select a leaf section without nested headings")
+    return start + 1, end
+
+
+def sort_entry(line: str) -> tuple[bool, str]:
+    match = ENTRY.match(line)
+    assert match is not None
+    target = match[1].removesuffix(".md")
+    folder = target.endswith("/index")
+    name = Path(target).parent.name if folder else Path(target).name
+    return not folder, name.casefold()
+
+
+def reviewed_entries(
+    vault: Path, index: Path, existing_lines: tuple[str, ...], review: IndexReview
+) -> tuple[str, ...]:
+    entries = list(existing_lines)
+    for entry in review.entries:
+        resolved = resolve_entry(vault, index, entry.target)
+        if resolved == index:
+            raise ValueError("index cannot link to itself")
+        matching = []
+        for i, line in enumerate(entries):
+            match = ENTRY.match(line)
+            assert match is not None
+            try:
+                existing = resolve_entry(vault, index, match[1])
+            except ValueError:
+                continue
+            if existing == resolved:
+                matching.append(i)
+        if len(matching) > 1:
+            raise ValueError(f"duplicate existing entries: {entry.target}")
+        if matching:
+            entries[matching[0]] = entry.render()
+        else:
+            entries.append(entry.render())
+    return tuple(sorted(entries, key=sort_entry))
+
+
+def render_index(vault: Path, index: Path, before: str | None, review: IndexReview) -> str:
+    if before is None:
+        if not review.title or review.section is not None:
+            raise ValueError("new index requires title and no section")
+        before = f"# {review.title}\n\n"
+    lines = tuple(before.splitlines(keepends=True))
+    if any(line.lstrip().startswith(("```", "~~~")) for line in lines):
+        raise ValueError("index contains fenced examples; review it manually")
+    start, end = section_bounds(lines, review.section)
+    positions = tuple(i for i in range(start, end) if ENTRY.match(lines[i]))
+    if positions and positions != tuple(range(positions[0], positions[-1] + 1)):
+        raise ValueError("section has multiple entry blocks; review them separately")
+    block_start = positions[0] if positions else end
+    block_end = positions[-1] + 1 if positions else end
+    if (
+        positions
+        and block_end < end
+        and lines[block_end].strip()
+        and lines[block_end].startswith((" ", "\t"))
+    ):
+        raise ValueError("entry has continuation text; review it manually")
+    entries = reviewed_entries(vault, index, lines[block_start:block_end], review)
+    prefix = "".join(lines[:block_start])
+    suffix = "".join(lines[block_end:])
+    if not positions and entries:
+        if prefix and not prefix.endswith("\n\n"):
+            prefix += "\n" if prefix.endswith("\n") else "\n\n"
+        if suffix and not suffix.startswith("\n"):
+            suffix = "\n" + suffix
+    return prefix + "".join(entries) + suffix
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("vault_root", type=Path)
+    parser.add_argument("index_path")
+    parser.add_argument("--apply", action="store_true")
+    args = parser.parse_args()
+    try:
+        vault = args.vault_root.resolve(strict=True)
+        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)
+        before = index.read_bytes().decode("utf-8") if index.exists() else None
+        review = IndexReview.model_validate_json(sys.stdin.read())
+        after = render_index(vault, index, before, review)
+        if args.apply:
+            write_checked(vault, args.index_path, before, after)
+        else:
+            sys.stdout.write(after)
+    except (ValueError, OSError) as exc:
+        parser.exit(1, f"Error: {exc}\n")
+
+
+if __name__ == "__main__":
+    main()

obsidian_knowledge-3.26.2/plugins/obsidian-knowledge/skills/vault-organizer/find-open-questions.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""find-open-questions: scan ai_managed zones for `> [!question]` callouts.
+
+Usage: python3 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
+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.
+Reads ai_managed zones from
+<vault_root>/.claude/obsidian-knowledge.yaml; falls back to ['wiki'].
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+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"}
+
+
+class QuestionHit(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    path: str
+    line: int
+    text: str
+
+
+def render_question(hit: QuestionHit) -> str:
+    # Markdown text, not JSON: preserve backslashes used by math and escapes.
+    quoted = hit.text.replace('"', '\\"')
+    return f'- [[{hit.path.removesuffix(".md")}]] — line {hit.line} — "{quoted}"\n'
+
+
+def render_report(before: str | None, hits: tuple[QuestionHit, ...], timestamp: str) -> str:
+    if before is None:
+        before = (
+            "# Open questions\n\n"
+            "> Regenerated by vault-organizer. Resolve questions in the source page.\n\n"
+            "**Last run:** never\n\n## Scope\n\n"
+            "Question callouts in configured AI-managed zones; protected, hidden, "
+            "dependency and sync-conflict files excluded.\n\n"
+        )
+    lines = before.splitlines(keepends=True)
+    first_entry = next(
+        (i for i, line in enumerate(lines) if re.match(r"^- \[\[.*\]\] — line \d+ — ", line)), len(lines)
+    )
+    if any(
+        line.strip() and not re.match(r"^- \[\[.*\]\] — line \d+ — ", line) for line in lines[first_entry:]
+    ):
+        raise ValueError("report has content after generated entries; refusing to discard it")
+    prefix = "".join(lines[:first_entry])
+    prefix, count = re.subn(r"(?m)^\*\*Last run:\*\*[^\r\n]*", lambda _: f"**Last run:** {timestamp}", prefix)
+    if count != 1:
+        raise ValueError("report must contain exactly one **Last run:** line")
+    if not prefix.endswith("\n\n"):
+        prefix += "\n" if prefix.endswith("\n") else "\n\n"
+    entries = "".join(render_question(hit) for hit in hits)
+    return prefix + entries
+
+
+def load_managed_zones(vault_root: Path) -> list[str]:
+    config_path = vault_root / ".claude" / "obsidian-knowledge.yaml"
+    if HAS_YAML and config_path.exists():
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        return cfg.get("ai_managed", ["wiki"])
+    return ["wiki"]
+
+
+def scan_file(path: Path) -> list[tuple[int, str]]:
+    """Return [(line_no, question_text)] for each callout outside code fences."""
+    hits: list[tuple[int, str]] = []
+    in_fence = False
+    fence_marker = ""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            lines = f.readlines()
+    except OSError:
+        return hits
+
+    for i, line in enumerate(lines, start=1):
+        stripped = line.lstrip()
+        # Track fenced code-block state. Markdown fences start with ``` or ~~~.
+        if stripped.startswith(("```", "~~~")):
+            marker = stripped[:3]
+            if not in_fence:
+                in_fence = True
+                fence_marker = marker
+            elif stripped.startswith(fence_marker):
+                in_fence = False
+                fence_marker = ""
+            continue
+
+        if in_fence:
+            continue
+
+        if line.rstrip("\n").startswith(QUESTION_MARKER):
+            # Question text is on the next non-blank `> ` line.
+            question_text = ""
+            for j in range(i, len(lines)):
+                next_line = lines[j].rstrip("\n")
+                if next_line.startswith("> ") and next_line.strip() != ">":
+                    question_text = next_line[2:].strip()
+                    break
+                if not next_line.startswith(">"):
+                    break
+            hits.append((i, question_text))
+
+    return hits
+
+
+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("--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"
+    )
+    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)
+
+    zones = load_managed_zones(vault_root)
+    hits = []
+    for zone in zones:
+        zone_root = vault_root / zone
+        if not zone_root.is_dir():
+            continue
+        for md in sorted(zone_root.rglob("*.md")):
+            rel_parts = md.relative_to(vault_root).parts
+            if any(part.startswith(".") or part in SCAN_SKIP_DIR_NAMES for part in rel_parts):
+                continue
+            rel = md.relative_to(vault_root).as_posix()
+            try:
+                visible_path(vault_root, rel)
+            except ValueError:
+                continue
+            for line_no, text in scan_file(md):
+                hits.append(QuestionHit(path=rel, line=line_no, text=text))
+    if not args.report:
+        for hit in hits:
+            print(f"{hit.path}\t{hit.line}\t{hit.text}")
+        return
+    try:
+        if args.report != "Utility/obsidian-knowledge/reports/open-questions.md":
+            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:
+            raise ValueError("timestamp must include a timezone offset")
+        path = visible_path(vault_root, args.report)
+        before = path.read_bytes().decode("utf-8") if path.exists() else None
+        after = render_report(before, tuple(hits), stamp.isoformat(timespec="seconds"))
+        if args.apply:
+            write_checked(vault_root, args.report, before, after)
+        else:
+            sys.stdout.write(after)
+    except (ValueError, OSError) as exc:
+        parser.exit(1, f"Error: {exc}\n")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -26,6 +26,29 @@ Dates, paths, extensions, and missing embeds usually indicate expected files.
 A bare concept such as `[[anxiety]]` might be an intentional stub. When uncertain,
 add the issue to the worklist rather than silently skipping it.
 
+## Deterministic recovery and verification
+
+`recover-unresolved-links.py` defaults to reporting. Review before `--apply`.
+It can recover a stale prefix only when removing leading path components leaves
+a unique existing suffix of at least `directory/name`. It never falls back from
+a path-shaped target to an unrelated basename. Existing directories are not
+note candidates. Attachments require exact filenames, including extensions;
+normalized and fuzzy comparisons apply only to Markdown notes.
+
+Hidden paths, dependency directories, sync conflicts, and symlinks are excluded
+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.
+
 ## Orphans
 
 Run `obsidian vault="$VAULT_NAME" orphans`. Add managed-zone orphans to their