graphmark 0.4.0__tar.gz → 0.6.0__tar.gz

{graphmark-0.4.0 → graphmark-0.6.0}/CHANGELOG.md

@@ -1,6 +1,135 @@
 # CHANGELOG
 
 
+## v0.6.0 (2026-07-25)
+
+### Bug Fixes
+
+- **parse**: Parse block-style frontmatter lists (#118)
+  ([#120](https://github.com/cdcoonce/graphmark/pull/120),
+  [`723c517`](https://github.com/cdcoonce/graphmark/commit/723c517d30732286fd0e6005996fb36d577042f5))
+
+* chore(release): 0.3.4 [skip ci]
+
+* chore(release): 0.4.0 [skip ci]
+
+* chore(release): 0.5.0 [skip ci]
+
+* fix(parse): parse block-style frontmatter lists (#118)
+
+_parse_frontmatter handled scalars, quoted strings and inline lists, but a block list's item lines
+  contain no colon, so the loop skipped them and the bare `key:` line stored "". Every block-style
+  property in a real vault — aliases:, tags: — silently became an empty string instead of a list.
+
+Block form is what Obsidian's own Properties UI writes, so this is the common case, not the edge
+  case, and Document.frontmatter is public: a consumer reading doc.frontmatter["tags"] got "" rather
+  than a list. Not an error, just quietly wrong data.
+
+Item lines are matched on the leading dash BEFORE the key/value split, so an item containing a colon
+  ("- Note: A Subtitle") stays an item. A block closes at the next key rather than merely pausing —
+  without that, a stray indented line later in a malformed note would silently grow the earlier
+  list, which is misattribution rather than the promised fail-soft drop. That distinction survived
+  the first four mutations and now has its own test.
+
+A `key:` with no items still reads as "" — an empty value, not an empty list — so nothing that
+  parsed before changes shape.
+
+Parity: fixture notes use inline or scalar frontmatter only, so no expected.json can move. A test
+  asserts that property directly rather than leaving it as a claim in the commit message.
+
+Still a targeted scan, not a YAML dependency: this runs over every note in a vault and a note
+  someone is mid-edit must not take the graph down.
+
+---------
+
+Co-authored-by: semantic-release <semantic-release>
+
+### Features
+
+- **graph**: Resolve frontmatter aliases in-package (#119)
+  ([#121](https://github.com/cdcoonce/graphmark/pull/121),
+  [`05bb6ce`](https://github.com/cdcoonce/graphmark/commit/05bb6ced17656a3fb3d1d1798068763b26b68588))
+
+graphmark never read frontmatter during resolution, so every link written against an Obsidian
+  `aliases:` entry was reported broken. Measured on a real 521-note vault: stock graphmark reported
+  23 broken links where the actual count was 0, and dropped 17 edges with them. A 100%
+  false-positive rate in max_unresolved_links — the flagship threshold of graphmark check, the one
+  product this repo offers outward. Larger than the four false-positive classes already fixed
+  (#98/#101/#104/#107) combined.
+
+This reverses a documented decision. the-vault's AliasResolver says "naming policy belongs to the
+  seam, so the fallback lives here rather than in the graph algorithm". That holds for idiosyncratic
+  conventions; aliases: is core Obsidian, and this package claims to work on any Obsidian-family
+  vault. Human-triaged: move it in-package, on by default, since a default that silently produces
+  wrong answers is not fixed by a knob nobody knows to flip. resolve_aliases = false restores the
+  old behavior.
+
+That AliasResolver is the oracle, and the live-vault differential is exact: stock graphmark now
+  reports the same broken-link set as the reference implementation, note for note — 0 and 0, from a
+  51-entry alias map.
+
+Its conservative rules are preserved. An alias colliding with any real note name is dropped at index
+  time, not merely outranked, so a note's own title can never be hijacked and an already-ambiguous
+  basename can't be rescued into resolving. An alias claimed by two notes resolves to nothing. A
+  slash-bearing alias is refused when the map is built, because normalization turns "/" into a space
+  and would otherwise make it reachable from a slash-free display — the lookup-side guard alone does
+  not cover that, which mutation testing caught.
+
+One honest note: rule 1 (resolver before alias) is structurally unreachable given the other two
+  rules — no display can match both a catalog key and an alias key — so mutating the order leaves
+  the suite green. It is kept as insurance against a future relaxation and is documented as untested
+  rather than dressed up as covered.
+
+Parity: this changes what resolves, so it is the most parity-sensitive change since extraction. It
+  is safe only because no frozen fixture declares aliases; a test asserts that property directly so
+  it cannot go stale.
+
+
+## v0.5.0 (2026-07-25)
+
+### Features
+
+- **graph**: Add calibrated near-miss suggestions (#112)
+  ([#116](https://github.com/cdcoonce/graphmark/pull/116),
+  [`db873b1`](https://github.com/cdcoonce/graphmark/commit/db873b1009bbef599e9eef035720306b62a548b8))
+
+Track E slice 3, and the last thing keeping a consumer's parallel resolver alive. diagnose(graph,
+  display, suggest=k) fills candidates with near-miss notes for a `missing` verdict only — every
+  other reason already carries the rel_paths in play — so the default of 0 leaves the check gate's
+  hot path untouched.
+
+The rule was calibrated, not invented. The prior art (bidirectional substring containment over
+  stems) was frozen over a real 521-note vault's broken links, giving 53 distinct displays, each
+  annotated by a human as useful / useless / missing / correct-none. Only then was an algorithm
+  chosen, and it is justified against that set: 27/27 useful kept — the non-negotiable — 7 of 8
+  useless dropped, 4 of 5 missing found, zero new false suggestions. Method and measured result in
+  tests/fixtures/suggest/README.md; the vault is private, so every shape is reproduced as a named
+  test with invented names rather than committing the rows.
+
+Matching is directional, which is what separates a suggestion from a wrong answer. A display inside
+  a candidate is an abbreviation and always offered ([[Jordan]] -> Jordan Ellis). A candidate inside
+  a display is offered only above SUGGEST_MIN_COVERAGE: dropping a "-reference" suffix is the
+  answer, matching one word out of five is a real note that is NOT the target, and that shape is
+  what made the old hints untrustworthy. Partial overlap in neither direction is rejected — it
+  carried no useful hint anywhere in the baseline, and rejecting it is what holds the
+  false-suggestion rate at zero.
+
+Two annotations were corrected mid-calibration and both changed the design: [[Work Tasks]] and
+  [[Personal Index]] looked useless only because the old rule printed bare stems, rendering four
+  distinct Index.md files as "Index, Index, Index, Index". Both are correct answers. Suggestions
+  therefore return rel_paths, and `index` is deliberately NOT a generic stem.
+
+Also scrubs real colleague names out of the package. They had been used as doc/test examples and one
+  shipped in a docstring in 0.4.0; all replaced with invented placeholders. Published history still
+  carries them.
+
+Both constants are pinned by the baseline: the cap is the lowest value that keeps every useful
+  suggestion, the floor the highest. Teeth-checked by mutation — disabling suppression fails 1,
+  dropping the coverage floor fails 3, dropping folder-keying fails 2, suggesting on every reason
+  fails 3, and dropping the digit filter initially survived until a ranking test was added to cover
+  it.
+
+
 ## v0.4.0 (2026-07-25)
 
 ### Features

{graphmark-0.4.0 → graphmark-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphmark
-Version: 0.4.0
+Version: 0.6.0
 Summary: Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults.
 Project-URL: Homepage, https://github.com/cdcoonce/graphmark
 Project-URL: Repository, https://github.com/cdcoonce/graphmark
@@ -185,6 +185,7 @@ graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
 graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
 graph.out_of_scope                            # same, for markdown outside the configured scope
+graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
 ```
 
 `catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
@@ -223,10 +224,70 @@ Alias, anchor and `.md` forms all diagnose identically to the bare form.
 contradict the graph it describes: `unresolved` is exactly the displays diagnosing as `ambiguous` or
 `missing`, and the edges are exactly the `resolved` non-self targets.
 
+### Near-miss suggestions
+
+Pass `suggest=k` to turn a `missing` verdict into an actionable one. Suggestions are computed only
+for `missing` — every other reason already carries the rel_paths in play — so the default of `0`
+costs nothing on the `check` hot path.
+
+```python
+graphmark.diagnose(graph, "Jordan", suggest=5).candidates
+# ('people/Jordan Ellis.md',)
+```
+
+Matching is **directional**, which is what separates a suggestion from a wrong answer:
+
+- a display inside a candidate name is an abbreviation — `[[Jordan]]` → `Jordan Ellis`, or
+  `[[Mood Tracker]]` → `2026-04-11-mood-tracker` (pure-digit tokens are filing metadata, not
+  content);
+- a candidate inside a display is offered only when it covers at least `SUGGEST_MIN_COVERAGE` of it
+  — `[[fable-prompt-technique-reference]]` → `fable-prompt-technique` is the answer, while
+  `[[Dagster PJM InSchedules]]` → `Dagster` is a real note that is _not_ the target;
+- partial overlap in neither direction is rejected;
+- a display matching more than `SUGGEST_MAX_MATCHES` notes names a topic, not a typo, and gets
+  nothing at all.
+
+Notes whose stem is generic (`SKILL.md`, `README.md`) are matched on their **parent folder**, where
+their name actually lives.
+
+Both constants were calibrated against a human-annotated baseline of a real vault's broken links
+rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
+for the method and the measured result.
+
+## Frontmatter aliases
+
+Obsidian's `aliases:` property declares additional real names for a note, so links written against
+one resolve like any other link. Block, inline and scalar forms all work:
+
+```yaml
+---
+aliases:
+  - Mood Tracker
+  - mood-tracker
+---
+```
+
+`[[Mood Tracker]]` now resolves to `2026-04-11-mood-tracker.md` and produces a real edge. On a
+521-note vault this was the difference between **23 reported broken links and 0** — every one of the
+23 a false positive, plus 17 edges that were silently missing.
+
+Three rules keep it conservative:
+
+- **A real note name always wins.** An alias can never hijack a link to a note that actually bears
+  that name.
+- **An alias that collides with any real note name is dropped entirely** — not merely outranked, so
+  an already-ambiguous basename can't be rescued into resolving by someone's alias.
+- **An alias claimed by two notes resolves to nothing**, the same refusal applied to colliding
+  basenames.
+
+Set `resolve_aliases = false` for strict basename-only resolution. `graph.aliases` exposes the
+resolved map.
+
 ## Configuration
 
 ```toml
 root = "."                                    # required unless --root is passed
+resolve_aliases = true                        # resolve frontmatter aliases: (default true)
 scoped_folders = ["brain", "work"]            # limit the vault to these top-level folders
 excluded_dirs = [".git", "templates"]         # skip notes under these directories
 rules_files = ["CLAUDE.md", "CLAUDE.local.md"]  # agent-rules files, not vault content

{graphmark-0.4.0 → graphmark-0.6.0}/README.md

@@ -158,6 +158,7 @@ graphmark.to_dot(graph)                       # Graphviz DOT
 graph.unresolved                              # {rel_path: [broken link displays]}
 graph.catalog                                 # {normalized stem: [rel_paths]} — 2+ means ambiguous
 graph.out_of_scope                            # same, for markdown outside the configured scope
+graph.aliases                                 # {normalized alias: rel_path} — frontmatter aliases
 ```
 
 `catalog` and `out_of_scope` are the resolution state the build consulted. They are what you need to
@@ -196,10 +197,70 @@ Alias, anchor and `.md` forms all diagnose identically to the bare form.
 contradict the graph it describes: `unresolved` is exactly the displays diagnosing as `ambiguous` or
 `missing`, and the edges are exactly the `resolved` non-self targets.
 
+### Near-miss suggestions
+
+Pass `suggest=k` to turn a `missing` verdict into an actionable one. Suggestions are computed only
+for `missing` — every other reason already carries the rel_paths in play — so the default of `0`
+costs nothing on the `check` hot path.
+
+```python
+graphmark.diagnose(graph, "Jordan", suggest=5).candidates
+# ('people/Jordan Ellis.md',)
+```
+
+Matching is **directional**, which is what separates a suggestion from a wrong answer:
+
+- a display inside a candidate name is an abbreviation — `[[Jordan]]` → `Jordan Ellis`, or
+  `[[Mood Tracker]]` → `2026-04-11-mood-tracker` (pure-digit tokens are filing metadata, not
+  content);
+- a candidate inside a display is offered only when it covers at least `SUGGEST_MIN_COVERAGE` of it
+  — `[[fable-prompt-technique-reference]]` → `fable-prompt-technique` is the answer, while
+  `[[Dagster PJM InSchedules]]` → `Dagster` is a real note that is _not_ the target;
+- partial overlap in neither direction is rejected;
+- a display matching more than `SUGGEST_MAX_MATCHES` notes names a topic, not a typo, and gets
+  nothing at all.
+
+Notes whose stem is generic (`SKILL.md`, `README.md`) are matched on their **parent folder**, where
+their name actually lives.
+
+Both constants were calibrated against a human-annotated baseline of a real vault's broken links
+rather than chosen by taste — see [`tests/fixtures/suggest/README.md`](tests/fixtures/suggest/README.md)
+for the method and the measured result.
+
+## Frontmatter aliases
+
+Obsidian's `aliases:` property declares additional real names for a note, so links written against
+one resolve like any other link. Block, inline and scalar forms all work:
+
+```yaml
+---
+aliases:
+  - Mood Tracker
+  - mood-tracker
+---
+```
+
+`[[Mood Tracker]]` now resolves to `2026-04-11-mood-tracker.md` and produces a real edge. On a
+521-note vault this was the difference between **23 reported broken links and 0** — every one of the
+23 a false positive, plus 17 edges that were silently missing.
+
+Three rules keep it conservative:
+
+- **A real note name always wins.** An alias can never hijack a link to a note that actually bears
+  that name.
+- **An alias that collides with any real note name is dropped entirely** — not merely outranked, so
+  an already-ambiguous basename can't be rescued into resolving by someone's alias.
+- **An alias claimed by two notes resolves to nothing**, the same refusal applied to colliding
+  basenames.
+
+Set `resolve_aliases = false` for strict basename-only resolution. `graph.aliases` exposes the
+resolved map.
+
 ## Configuration
 
 ```toml
 root = "."                                    # required unless --root is passed
+resolve_aliases = true                        # resolve frontmatter aliases: (default true)
 scoped_folders = ["brain", "work"]            # limit the vault to these top-level folders
 excluded_dirs = [".git", "templates"]         # skip notes under these directories
 rules_files = ["CLAUDE.md", "CLAUDE.local.md"]  # agent-rules files, not vault content

{graphmark-0.4.0 → graphmark-0.6.0}/docs/ROADMAP.md

@@ -82,7 +82,7 @@ already learned were fine. #107 is the fourth fix that had to be applied in two
 The gardener's stack survives because it answers questions graphmark cannot yet answer. graphmark
 says _whether_ a link resolves; Lane A needs to know **why it failed and what to do about it** —
 the ambiguity set, the near-miss candidates behind a "did you mean", and the canonical title of
-the note a display resolves to (so `[[ethan courtman]]` can be repaired to `[[Ethan Courtman]]`).
+the note a display resolves to (so `[[jordan ellis]]` can be repaired to `[[Jordan Ellis]]`).
 
 _Where we're going:_ a documented, typed **link-diagnosis** surface that makes the consumer a
 formatter over graphmark's answers instead of a second resolver. The classification is already

{graphmark-0.4.0 → graphmark-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphmark"
-version = "0.4.0"
+version = "0.6.0"
 description = "Deterministic knowledge-graph analysis for markdown / [[wikilink]] vaults."
 readme = "README.md"
 requires-python = ">=3.11"

{graphmark-0.4.0 → graphmark-0.6.0}/src/graphmark/__init__.py

@@ -28,12 +28,16 @@ from graphmark.dismiss import (
 from graphmark.export import to_dot, to_json
 from graphmark.graph import (
     DIAGNOSIS_REASONS,
+    SUGGEST_MAX_MATCHES,
+    SUGGEST_MIN_COVERAGE,
     LinkDiagnosis,
     NormalizeResolver,
     VaultGraph,
+    build_aliases,
     build_catalog,
     candidates_for,
     diagnose,
+    suggest_notes,
 )
 from graphmark.interfaces import LinkExtractor, Resolver, Similarity
 from graphmark.metrics import (
@@ -96,6 +100,8 @@ __all__ = [
     "Document",
     "LinkExtractor",
     "DIAGNOSIS_REASONS",
+    "SUGGEST_MAX_MATCHES",
+    "SUGGEST_MIN_COVERAGE",
     "LinkDiagnosis",
     "NormalizeResolver",
     "Resolver",
@@ -107,9 +113,11 @@ __all__ = [
     "active_dismissed_sigs",
     "bridges",
     "build",
+    "build_aliases",
     "build_catalog",
     "candidates_for",
     "diagnose",
+    "suggest_notes",
     "clusters",
     "gaps",
     "hubs",

{graphmark-0.4.0 → graphmark-0.6.0}/src/graphmark/config.py

@@ -44,6 +44,9 @@ class VaultConfig:
     excluded_dirs: list[str] = field(default_factory=list)
     rules_files: list[str] = field(default_factory=lambda: ["CLAUDE.md", "CLAUDE.local.md"])
     transient_prefixes: tuple[str, ...] = ()
+    # Obsidian's `aliases:` property names a note, so links written against one resolve by
+    # default. Set False for strict basename-only resolution.
+    resolve_aliases: bool = True
     check: CheckPolicy = field(default_factory=CheckPolicy)
 
     def __post_init__(self) -> None:
@@ -118,5 +121,6 @@ def load_config(path: str | Path, *, root_override: str | Path | None = None) ->
         excluded_dirs=data.get("excluded_dirs", []),
         rules_files=data.get("rules_files", ["CLAUDE.md", "CLAUDE.local.md"]),
         transient_prefixes=tuple(data.get("transient_prefixes", [])),
+        resolve_aliases=bool(data.get("resolve_aliases", True)),
         check=_parse_check(data, path),
     )

{graphmark-0.4.0 → graphmark-0.6.0}/src/graphmark/graph.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import re
 import string
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 
 from graphmark.config import VaultConfig
@@ -76,6 +76,43 @@ def candidates_for(display: str, catalog: dict[str, list[str]]) -> list[str]:
     return list(catalog.get(_normalize(target), ()))
 
 
+def build_aliases(docs: list[Document], catalog: dict[str, list[str]]) -> dict[str, str]:
+    """Map normalized alias → rel_path, for aliases that unambiguously name one note.
+
+    Obsidian's ``aliases:`` property declares additional real names for a note, so a link written
+    against one is not a broken link. Two rules keep this conservative, and both matter:
+
+    * **An alias that collides with any real note name is dropped entirely** — not merely
+      outranked. A note's own title must never be hijackable by someone else's alias, and an
+      already-ambiguous basename must not be rescued into resolving by a third note's alias.
+    * **An alias claimed by two or more notes resolves to nothing** — the same refusal graphmark
+      already applies to colliding basenames. Ambiguity stays ambiguous.
+
+    Alias keys go through ``_normalize``, the function that builds catalog keys, so an alias and a
+    note name can never drift apart on case or punctuation.
+    """
+    claims: dict[str, set[str]] = {}
+    for doc in docs:
+        raw = doc.frontmatter.get("aliases")
+        # A scalar is one alias; a list is many; anything else (a number, a mapping, a missing
+        # key) yields none rather than raising — a note someone is mid-edit must not break a build.
+        if isinstance(raw, str):
+            values = [raw]
+        elif isinstance(raw, list):
+            values = [v for v in raw if isinstance(v, str)]
+        else:
+            continue
+        for alias in values:
+            # A path is not a name: "[[folder/note]]" is resolved by path suffix, never by alias.
+            if "/" in alias:
+                continue
+            key = _normalize(alias)
+            if not key or key in catalog:
+                continue
+            claims.setdefault(key, set()).add(doc.rel_path)
+    return {key: paths.pop() for key, paths in claims.items() if len(paths) == 1}
+
+
 def _is_intra_note_reference(display: str) -> bool:
     """True for a link that targets no note, e.g. ``[[#Heading]]`` or ``[[#^block]]``.
 
@@ -144,6 +181,90 @@ class NormalizeResolver:
         return paths[0]
 
 
+#: A display matching more than this many notes names a *topic*, not a mistyped note, and gets no
+#: suggestions at all. Calibrated, not chosen: on the reference vault ``[[AMRT]]`` matched 47 notes
+#: while ``[[Priya Raghavan]]`` needs a cap of at least 12 to survive (that token appears in 9 note
+#: stems), so 12 is the lowest value that keeps every human-confirmed useful suggestion.
+SUGGEST_MAX_MATCHES = 12
+
+#: When a candidate's name sits *inside* a longer display, the fraction of the display it must
+#: account for. ``[[fable-prompt-technique-reference]]`` → ``fable-prompt-technique`` covers 3 of 4
+#: tokens and is the answer; ``[[Dagster PJM InSchedules]]`` → ``Dagster`` covers 1 of 3 and is a
+#: real note that is not the target — the shape that made the old suggestions untrustworthy. 0.4 is
+#: the highest floor that keeps every useful suggestion in the annotated baseline.
+SUGGEST_MIN_COVERAGE = 0.4
+
+#: Note stems that name nothing — the note's identity lives in its parent folder instead. Kept
+#: deliberately short: ``index`` is NOT here, because a vault's ``personal/Index.md`` is a real,
+#: linkable note and re-keying it onto its folder would lose the actual answer.
+GENERIC_STEMS = frozenset({"skill", "readme"})
+
+
+def _content_tokens(text: str) -> frozenset[str]:
+    """Normalized tokens with pure-digit runs dropped.
+
+    Date prefixes are filing metadata, not content: ``2026-04-11-mood-tracker`` and
+    ``Mood Tracker`` are the same note to a human, and the dated twin is the single most common
+    near-miss shape in a journal-style vault.
+    """
+    return frozenset(t for t in _normalize(text).split() if not t.isdigit())
+
+
+def _suggestion_keys(catalog: dict[str, list[str]]) -> list[tuple[str, frozenset[str]]]:
+    """(rel_path, name tokens) for every note, keyed by folder where the stem is generic."""
+    keys: list[tuple[str, frozenset[str]]] = []
+    for paths in catalog.values():
+        for rel in paths:
+            path = Path(rel)
+            name = path.parent.name if path.stem.lower() in GENERIC_STEMS else path.stem
+            tokens = _content_tokens(name)
+            if tokens:
+                keys.append((rel, tokens))
+    return keys
+
+
+def suggest_notes(display: str, catalog: dict[str, list[str]], k: int) -> tuple[str, ...]:
+    """Up to ``k`` notes whose names are near-misses for ``display``, best first.
+
+    Matching is **directional**, which is what separates a suggestion from noise:
+
+    * the display's tokens inside a candidate's — the display abbreviates a longer title
+      (``[[Jordan]]`` → ``Jordan Ellis``). Always offered; a short display naturally names a
+      longer note.
+    * a candidate's tokens inside the display's — offered only when the candidate accounts for at
+      least ``SUGGEST_MIN_COVERAGE`` of the display. Dropping a suffix is a real answer; matching
+      one word out of five is a wrong answer that invites a wrong repair.
+    * neither — rejected. Partial overlap produced no useful suggestion anywhere in the annotated
+      baseline, and rejecting it is what holds the false-suggestion rate at zero.
+
+    Ranked by how much of the longer name the match accounts for, ties broken by rel_path so the
+    output is byte-stable.
+    """
+    display_tokens = _content_tokens(display)
+    if not display_tokens or k <= 0:
+        return ()
+
+    scored: list[tuple[float, str]] = []
+    for rel, name_tokens in _suggestion_keys(catalog):
+        if display_tokens <= name_tokens:
+            score = len(display_tokens) / len(name_tokens)
+        elif name_tokens <= display_tokens:
+            score = len(name_tokens) / len(display_tokens)
+            if score < SUGGEST_MIN_COVERAGE:
+                continue
+        else:
+            continue
+        scored.append((score, rel))
+
+    # A display that matches half the vault is a topic. Offering its "best" dozen would be
+    # confident nonsense, so it gets nothing.
+    if len(scored) > SUGGEST_MAX_MATCHES:
+        return ()
+
+    scored.sort(key=lambda pair: (-pair[0], pair[1]))
+    return tuple(rel for _, rel in scored[:k])
+
+
 #: Every value ``LinkDiagnosis.reason`` can take, in the order they are decided. A consumer
 #: switches on these strings, so the set is part of the public contract.
 DIAGNOSIS_REASONS = (
@@ -167,10 +288,11 @@ class LinkDiagnosis:
 
     ``target`` is the resolved rel_path, set only when ``reason == "resolved"``; the caller recovers
     the note's canonical title from its stem, which is what makes a case repair like
-    ``[[ethan courtman]]`` → ``[[Ethan Courtman]]`` possible.
+    ``[[jordan ellis]]`` → ``[[Jordan Ellis]]`` possible.
 
     ``candidates`` carries the rel_paths in play: the colliding notes for ``ambiguous``, the
-    unindexed markdown for ``out-of-scope-note``. Empty for every other reason.
+    unindexed markdown for ``out-of-scope-note``, and — only when ``diagnose`` is asked for them —
+    the near-miss suggestions for ``missing``. Empty for every other reason.
     """
 
     display: str
@@ -184,6 +306,7 @@ def _diagnose(
     catalog: dict[str, list[str]],
     out_of_scope: dict[str, list[str]],
     resolver: Resolver,
+    aliases: dict[str, str] | None = None,
 ) -> LinkDiagnosis:
     """Classify one display against already-built resolution state.
 
@@ -199,6 +322,22 @@ def _diagnose(
     if target is not None:
         return LinkDiagnosis(display=display, target=target, reason="resolved")
 
+    # The resolver runs first, so a real note named X always beats an alias X — otherwise renaming
+    # a note could silently hijack live links. An alias hit is a genuine resolution, not a
+    # consolation: it names the note as surely as the filename does.
+    #
+    # Given the rules build_aliases already enforces, this ordering is defense in depth rather
+    # than load-bearing: an alias key can never collide with a catalog key (dropped at index
+    # time), and a path-qualified display is excluded from alias lookup below, so no display can
+    # match both paths. Mutating the order leaves the suite green, which is expected — the
+    # ordering is insurance against a future relaxation of those rules, not the mechanism.
+    if aliases:
+        stripped = _strip_display(display)
+        if stripped and "/" not in stripped:
+            aliased = aliases.get(_normalize(stripped))
+            if aliased is not None:
+                return LinkDiagnosis(display=display, target=aliased, reason="resolved")
+
     # The resolver declined. Whether it declined because nothing matched or because too much did
     # is the distinction consumers need, and only the catalog can answer it.
     collisions = candidates_for(display, catalog)
@@ -219,14 +358,24 @@ def _diagnose(
     return LinkDiagnosis(display=display, reason="missing")
 
 
-def diagnose(graph: VaultGraph, display: str) -> LinkDiagnosis:
+def diagnose(graph: VaultGraph, display: str, *, suggest: int = 0) -> LinkDiagnosis:
     """Explain what ``display`` names in ``graph`` — see :class:`LinkDiagnosis`.
 
     Uses the resolver the graph was built with, so a diagnosis can never contradict the graph it
     describes. A directly constructed ``VaultGraph`` with no resolver falls back to
     ``NormalizeResolver``.
+
+    ``suggest=k`` fills ``candidates`` with up to k near-miss notes — but only for a ``missing``
+    verdict, since every other reason either already carries the rel_paths in play or has nothing
+    to look for. The default of 0 does no extra work at all, keeping the vault-health gate's hot
+    path free of it.
     """
-    return _diagnose(display, graph.catalog, graph.out_of_scope, graph.resolver)
+    if suggest < 0:
+        raise ValueError(f"suggest must be >= 0, got {suggest}")
+    diagnosis = _diagnose(display, graph.catalog, graph.out_of_scope, graph.resolver, graph.aliases)
+    if suggest and diagnosis.reason == "missing":
+        return replace(diagnosis, candidates=suggest_notes(display, graph.catalog, suggest))
+    return diagnosis
 
 
 class VaultGraph:
@@ -253,6 +402,7 @@ class VaultGraph:
         catalog: dict[str, list[str]] | None = None,
         out_of_scope: dict[str, list[str]] | None = None,
         resolver: Resolver | None = None,
+        aliases: dict[str, str] | None = None,
     ) -> None:
         self.nodes = nodes
         self.out_links = out_links
@@ -260,6 +410,7 @@ class VaultGraph:
         self.unresolved = unresolved if unresolved is not None else {}
         self.catalog = catalog if catalog is not None else {}
         self.out_of_scope = out_of_scope if out_of_scope is not None else {}
+        self.aliases = aliases if aliases is not None else {}
         # Retained so diagnose() answers with the same resolver that built the graph; a
         # pluggable Resolver that disagreed with the graph it describes would be worse than none.
         self.resolver: Resolver = resolver if resolver is not None else NormalizeResolver()
@@ -303,6 +454,7 @@ class VaultGraph:
         docs = [parse_document(p, root) for p in md_files]
         nodes = {doc.rel_path: doc for doc in docs}
         catalog = build_catalog(docs)
+        aliases = build_aliases(docs, catalog) if config.resolve_aliases else {}
 
         out_links: dict[str, set[str]] = {rel: set() for rel in nodes}
         back_links: dict[str, set[str]] = {rel: set() for rel in nodes}
@@ -316,7 +468,7 @@ class VaultGraph:
         broken = {"ambiguous", "missing"}
         for doc in docs:
             for display in extractor.extract(doc.text):
-                d = _diagnose(display, catalog, out_of_scope, resolver)
+                d = _diagnose(display, catalog, out_of_scope, resolver, aliases)
                 if d.reason in broken:
                     unresolved.setdefault(doc.rel_path, []).append(display)
                 elif d.target is not None and d.target != doc.rel_path:
@@ -326,4 +478,6 @@ class VaultGraph:
             for dst in targets:
                 back_links[dst].add(src)
 
-        return cls(nodes, out_links, back_links, unresolved, catalog, out_of_scope, resolver)
+        return cls(
+            nodes, out_links, back_links, unresolved, catalog, out_of_scope, resolver, aliases
+        )