Vault Health Inspector

How link resolution works across Markdown tools

Markdown note applications use different conventions for connecting notes together. Standard CommonMark relies strictly on explicit file path targets (such as [Project Plan](docs/plan.md)), whereas modern knowledge base systems frequently use wikilinks (such as [[Plan]]).

Wikilinks offer speed when writing, but create portability pitfalls when collections grow or move between applications. When a link omits the containing folder, the application must search the vault for a note matching that name. If two folders have notes with identical names, different software resolves the link differently:

• Shortest path: Resolves to the first match found or the shortest relative distance from the active file.
• Root-first: Resolves to notes sitting at the vault root before looking inside nested subdirectories.
• Strict relative: Rejects links without explicit paths, treating unrouted wikilinks as missing files.

This inspector resolves targets deterministically. When a target matches multiple files in distinct directories, it marks the link as ambiguous rather than guessing which file the writer intended.

The core health checks

Every check evaluates structural integrity and portability without interpreting opinions or rewriting your files.

Why ambiguous short links happen

When you start a personal vault, filenames are usually unique. Over months of note-taking, project names repeat. You might have an Overview.md in Projects/Alpha/ and another Overview.md in Archive/Beta/.

If a third note contains [[Overview]], the link is ambiguous. While your current editor might happen to open one of them, exporting the vault to another application or publishing it as a website can break the connection or point to the wrong document. Disambiguating by adding the containing folder (e.g. [[Projects/Alpha/Overview|Overview]]) guarantees that every Markdown reader resolves the correct note.

Preflight checklist and safe migration workflow

1. Back up before inspecting: Create an archive copy of your entire folder before running any tools or edits.
2. Run the browser inspection: Select your vault directory above to catalog all references, headings, and attachments.
3. Disambiguate duplicate targets first: Update ambiguous links so every wikilink names a distinct path.
4. Repair broken notes and anchors: Create missing notes or update obsolete filenames. Ensure heading anchors match actual section headers.
5. Export your audit report: Download the Markdown report or CSV inventory to verify all issues are resolved.

What this tool never does

• It never uploads, transmits or stores your files. Inspection runs entirely in your browser.
• It never mutates, renames or rewrites your files. It produces a diagnostic report, not automated edits.
• It never chooses arbitrarily when a short link is ambiguous. It flags every candidate path for human review.
• It does not use AI or external services. All link resolution uses deterministic path and heading indexing.

Its limits, printed

This utility operates entirely within your browser's local sandbox. It inspects up to 2,500 files and 5,000,000 characters of text per run. Individual notes exceeding 500,000 characters are flagged for review.

It does not execute external HTTP requests to verify web links, parse proprietary binary canvas schemas, or decrypt encrypted vaults. Link syntax located inside fenced code blocks or backtick spans is strictly protected and ignored. If your vault relies on daily meeting recordings and speech transcripts, the desktop app handles on-device call transcription in plain local Markdown.