MetaList 0.17.0__tar.gz → 0.18.0__tar.gz

{metalist-0.17.0 → metalist-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metalist
-Version: 0.17.0
+Version: 0.18.0
 Summary: A minimalist single-user note-taking app with SSR, fast in-memory tree operations, and efficient sync.
 Project-URL: Homepage, https://github.com/evolvingstuff/metalist
 Project-URL: Repository, https://github.com/evolvingstuff/metalist
@@ -51,6 +51,11 @@ A minimalist single-user note-taking app focused on server-side rendering (SSR),
 - Multi-tab search contexts with server-persisted scroll/search state (survives browser restarts)
 - Manual namespace backups/restores to a user-selected backup folder with retention controls
 
+## Changes in 0.18.0
+
+- Right-click a tag suggestion, in the tag bar or the search bar, to see why it is suggested. The menu starts with **Why suggested**: the words of the note that name the tag (or a synonym), the tags it goes with and on how many notes, notes sharing this note's tags, whether it already applies through a parent or a rule, or that nothing in the note points to it; then how often the tag is used. Search suggestions also say how often you worked with a tag lately (when that put it first), what your search so far finds, or what leaving it out removes. The reasons are MetaList's own ranking, not the AI's, and appear instantly.
+- Fixed: right-clicking a suggestion closed the list and opened the menu of the note underneath (or the browser's own menu). The list, your typed letters and the cursor now stay as they were, and `Escape` on an open right-click menu closes only the menu instead of also leaving edit mode.
+
 ## Changes in 0.17.0
 
 - A whole-view summary that fails or is stopped keeps the batches it finished; saying "try that again" continues it, running only the remaining batches with the original question.

{metalist-0.17.0 → metalist-0.18.0}/README.md

@@ -12,6 +12,11 @@ A minimalist single-user note-taking app focused on server-side rendering (SSR),
 - Multi-tab search contexts with server-persisted scroll/search state (survives browser restarts)
 - Manual namespace backups/restores to a user-selected backup folder with retention controls
 
+## Changes in 0.18.0
+
+- Right-click a tag suggestion, in the tag bar or the search bar, to see why it is suggested. The menu starts with **Why suggested**: the words of the note that name the tag (or a synonym), the tags it goes with and on how many notes, notes sharing this note's tags, whether it already applies through a parent or a rule, or that nothing in the note points to it; then how often the tag is used. Search suggestions also say how often you worked with a tag lately (when that put it first), what your search so far finds, or what leaving it out removes. The reasons are MetaList's own ranking, not the AI's, and appear instantly.
+- Fixed: right-clicking a suggestion closed the list and opened the menu of the note underneath (or the browser's own menu). The list, your typed letters and the cursor now stay as they were, and `Escape` on an open right-click menu closes only the menu instead of also leaving edit mode.
+
 ## Changes in 0.17.0
 
 - A whole-view summary that fails or is stopped keeps the batches it finished; saying "try that again" continues it, running only the remaining batches with the original question.

{metalist-0.17.0 → metalist-0.18.0}/app/api/routes/notes.py

@@ -138,7 +138,8 @@ from app.services.note_fullscreen import build_note_fullscreen_markup
 from app.services.link_titles import link_title_store
 from app.services.search_index import search_index
 from app.services.dictation_cleanup import clean_dictated_paste
-from app.services.tag_suggestions import suggest_tags_for_note
+from app.services.tag_suggestion_reasons import search_suggestion_reasons
+from app.services.tag_suggestions import suggest_tags_with_reasons_for_note
 from app.services.client_state_service import suggests_already_applying_tags
 from app.services.undo_state import reset_undo_stack
 from app.usecases.prioritize import list_prioritize_tag_suggestions
@@ -496,9 +497,20 @@ def search_suggestions(request: Request, payload: SearchSuggestionsRequest) -> D
         for selection in personalized_selections
         if selection.tag in suggestions
     ]
+    # Why each is suggested, shown when it is right-clicked (docs/ui/controls.md).
+    facts = search_index.describe_search_suggestions(query=query, terms=suggestions)
+    recent_activity = {
+        selection.tag.casefold(): (selection.window_days, selection.activity_count)
+        for selection in personalized_selections
+        if selection.tag in suggestions
+    }
     return {
         "suggestions": suggestions,
         "personalizedSuggestions": personalized_suggestions,
+        "reasons": {
+            tag: list(search_suggestion_reasons(facts=facts, term=tag, recent_activity=recent_activity))
+            for tag in suggestions
+        },
     }
 
 
@@ -626,7 +638,7 @@ def tag_suggestions(request: Request, payload: TagSuggestionsRequest) -> Dict[st
 
     _require_note_present(note_id, context="notes.tag-suggestions")
 
-    suggestions = suggest_tags_for_note(
+    suggestions = suggest_tags_with_reasons_for_note(
         note_id=note_id,
         anchors=anchors,
         explicit_tags=explicit_tags,
@@ -635,7 +647,11 @@ def tag_suggestions(request: Request, payload: TagSuggestionsRequest) -> Dict[st
         limit=MAX_TAG_SUGGESTIONS,
         include_already_applying=suggests_already_applying_tags(token=_require_bearer_token(request)),
     )
-    return {"suggestions": suggestions}
+    # Why each is suggested, shown when it is right-clicked (docs/ui/tag-bar.md).
+    return {
+        "suggestions": [suggestion.tag for suggestion in suggestions],
+        "reasons": {suggestion.tag: list(suggestion.reasons) for suggestion in suggestions},
+    }
 
 
 @router.get("/notes/export-html")

{metalist-0.17.0 → metalist-0.18.0}/app/services/agent/skills/help-notes.md

@@ -172,7 +172,7 @@ On macOS, `⌘ + Y` normally opens Safari History rather than performing native
 | Right-click image in note | Adds image actions to the note context menu: `Copy Image`, `Save Image`, `Zoom Image`, `Open Image in New Tab` |
 | Right-click anywhere in a completed AI response bubble (including padding and links) | Choose `Copy Response` to place its raw Markdown on the MetaList note clipboard with `@markdown @llm`, while also writing rendered HTML and raw Markdown to the system clipboard. It can be pasted as a note but not as a reference until inserted. |
 | Right-click notes view background | Open the view menu: outside edit mode `Add Note at Top`, `Paste Note at Top` (once a note is copied), `Undo`, `Redo`; `Go to Top`, `Go to Bottom` (unless at that end), `Fully Expand All`, `Fully Collapse All`; `View ▸` (All / Untagged notes), `Sort by ▸`, `Show ▸` (Chat, Tabs, Tags in List), `Theme ▸` (System, Light, Dark), each ticking the current choice; `New Tab`, `Open/Switch Namespace…`, `Reminders…`; `Export View as HTML`; `Log Out`. Shortcuts show on the right; items that do not apply are hidden. |
-| Right-click tag in search input, tag bar, or their suggestion lists | Open tag context menu (Edit Tag Relationships). If a note is being edited, it is saved and the view refresh completes first, restoring view-only rendering such as cached URL titles. |
+| Right-click tag in search input, tag bar, or their suggestion lists | Open tag context menu (Edit Tag Relationships); a suggestion's menu (tag bar or search) starts with **Why suggested**. A suggestion list, the typed letters and edit mode stay as they were. Choosing Edit Tag Relationships saves an edited note first and completes the view refresh, restoring view-only rendering such as cached URL titles. |
 | Right-click left or right lane | Open the same view menu |
 | Hover left side of search bar | Show the tab/search-context overlay |
 | Hover/click search input | Hide the tab/search-context overlay |
@@ -201,7 +201,7 @@ On macOS, `⌘ + Y` normally opens Safari History rather than performing native
 
 > Note: On Windows/Linux, use `Ctrl` instead of `⌘` (Command)
 
-App menus close with `Escape` or an outside click. The right-click menu also closes once the pointer moves about 28px away from it and any open submenu, like the tab overlay; small movements just past its edge keep it open. Every modal has a standard upper-right circular `×` matching full-screen note view and also closes with `Escape` or an outside click. Dismiss-only footer `Close`/`OK` buttons are omitted; `Enter` still submits a modal's declared primary workflow action.
+App menus close with `Escape` (only the menu: a note being edited stays in edit mode) or an outside click. The right-click menu also closes once the pointer moves about 28px away from it and any open submenu, like the tab overlay; small movements just past its edge keep it open. Every modal has a standard upper-right circular `×` matching full-screen note view and also closes with `Escape` or an outside click. Dismiss-only footer `Close`/`OK` buttons are omitted; `Enter` still submits a modal's declared primary workflow action.
 
 When `Show tags in list` is enabled, the grey right-aligned tag column wraps and is capped at 25% of its note row so note content retains the majority of the available width.
 

{metalist-0.17.0 → metalist-0.18.0}/app/services/agent/skills/help-releases.md

@@ -5,6 +5,11 @@ README. Changes made after the newest listed version are not described here.
 Compare with installed_version from the help lookup to tell the user whether
 they already have a release. Version info offers updates (see the data topic).
 
+## 0.18.0
+
+- Right-click a tag suggestion, in the tag bar or the search bar, to see why it is suggested. The menu starts with **Why suggested**: the words of the note that name the tag (or a synonym), the tags it goes with and on how many notes, notes sharing this note's tags, whether it already applies through a parent or a rule, or that nothing in the note points to it; then how often the tag is used. Search suggestions also say how often you worked with a tag lately (when that put it first), what your search so far finds, or what leaving it out removes. The reasons are MetaList's own ranking, not the AI's, and appear instantly.
+- Fixed: right-clicking a suggestion closed the list and opened the menu of the note underneath (or the browser's own menu). The list, your typed letters and the cursor now stay as they were, and `Escape` on an open right-click menu closes only the menu instead of also leaving edit mode.
+
 ## 0.17.0
 
 - A whole-view summary that fails or is stopped keeps the batches it finished; saying "try that again" continues it, running only the remaining batches with the original question.

{metalist-0.17.0 → metalist-0.18.0}/app/services/agent/skills/help-search.md

@@ -144,6 +144,8 @@ Ontology rules also add **inferred tags** before search matching:
 - A typed prefix can match either the start of the full tag or the start of any connector-separated segment.
   - Example: `wor` suggests `workspaces` and `databricks-workspaces`.
   - Example: `orksp` suggests neither.
+- Right-clicking a search suggestion (Control-click on a Mac) opens its tag menu: **Why suggested**, then Edit Tag Relationships. The search and the list stay as they were; `Escape` closes only the menu. A right-click earns no activity credit.
+- **Why suggested** says what MetaList's ranking used (not the AI): how often you worked with the tag in a personalization window (`You've worked with it 12 times in the last 7 days`), the notes it shares with the tags already in the search, how many notes the search so far finds it on, how many notes leaving it out removes, or that a first tag is listed by use; last, how many notes searching for it finds.
 - The server returns at most `MAX_SEARCH_SUGGESTIONS` suggestions; the default is 20.
 - This affects suggestions only; actual tag search matching remains exact against effective tag terms.
 

{metalist-0.17.0 → metalist-0.18.0}/app/services/agent/skills/help-tags.md

@@ -161,6 +161,8 @@ Unclosed comments behave like unclosed wrappers:
 - Tags declared in ontology rules remain eligible for literal-content matching and typed-prefix completion even when they have never been explicitly assigned to a note. With a blank prefix, unrelated unused ontology tags are not added as generic fallback suggestions.
 - Tags already present explicitly in the current tag bar are never suggested.
 - Tags already present only via inheritance or ontology inference are suppressed unless they match the prefix. For one-character prefixes they come right after the suggestions with evidence; for longer prefixes they appear at the bottom. The **Tag Suggestions** settings dialog has `Allow suggesting tags that already apply` (off by default): when on, tags a parent already has and tags the rules imply from them are ranked like any other tag. Tags written in the note's own bar are still never suggested.
+- Right-clicking a suggestion (Control-click on a Mac) opens the tag menu for it: **Why suggested**, then Edit Tag Relationships. The list, the typed letters and edit mode stay as they were; `Escape` closes only the menu.
+- **Why suggested** says what the ranking found, then how often the tag is used: named (or partly named) in the note's text, a synonym named in it, the rest of the tag after what was typed, on N notes together with the note's tags, named in the note as last saved, on N notes that share the note's tags, or already applying through a parent or a rule. `Nothing in this note points to it` means it is listed only because it is used often. The reasons are MetaList's own ranking, not the AI's.
 - Suggestions appear below the tag bar when there is room; if the tag bar is near the bottom, the list flips upward but keeps the same best-on-top ordering and initial scroll position.
 - The server returns at most `MAX_TAG_SUGGESTIONS` note tag suggestions; the default is 20.
 

{metalist-0.17.0 → metalist-0.18.0}/app/services/search_history.py

@@ -52,6 +52,8 @@ class TagActivityState:
 class TagActivityWindowSelection:
     tag: str
     window_days: int
+    # The tag's activity credits in that window (why it won the slot).
+    activity_count: int
 
 
 def current_local_date() -> date:
@@ -153,6 +155,7 @@ def rank_tag_activity_window_selections(
             TagActivityWindowSelection(
                 tag=candidate_by_casefold[winner_casefold],
                 window_days=day_count,
+                activity_count=totals_by_casefold[winner_casefold],
             )
         )
     return selections

{metalist-0.17.0 → metalist-0.18.0}/app/services/search_index.py

@@ -128,6 +128,42 @@ def _parse_search_query_for_suggestions(raw_input: str) -> tuple[Tuple[str, ...]
     return context.anchors, context.partial_prefix
 
 
+@dataclass(frozen=True, slots=True)
+class TagCooccurrence:
+    """A tag's notes that carry the most of some anchor tags, as tag suggestions rank them."""
+
+    anchor_count: int
+    note_count: int
+    # The anchors (casefolded) those notes carry; one set when they all carry the same ones.
+    anchor_sets: FrozenSet[FrozenSet[str]]
+
+    def __post_init__(self) -> None:
+        if self.anchor_count <= 0 or self.note_count <= 0:
+            raise ValueError("A tag co-occurrence needs at least one anchor and one note")
+        if not self.anchor_sets or any(len(anchors) != self.anchor_count for anchors in self.anchor_sets):
+            raise ValueError("Every anchor set holds anchor_count anchors")
+
+
+@dataclass(frozen=True, slots=True)
+class SearchSuggestionFacts:
+    """What the search-bar ranking used for some shown suggestions, to say why each is there."""
+
+    partial_prefix: str
+    # Tags (and words) already typed in the clause; with them the ranking is by co-occurrence.
+    anchors: Tuple[str, ...]
+    has_completed_clause: bool
+    is_exclusion: bool
+    # Notes the search so far finds (every note when nothing precedes the typed tag).
+    matching_note_count: int
+    note_counts: Dict[str, int]
+    matching_counts: Dict[str, int]
+    cooccurrences: Dict[str, TagCooccurrence]
+
+    @property
+    def is_ranked_by_cooccurrence(self) -> bool:
+        return any(anchor and not anchor.startswith("@") for anchor in self.anchors)
+
+
 @dataclass(frozen=True, slots=True)
 class SearchRecord:
     note_id: str
@@ -513,6 +549,79 @@ class SearchIndex:
                 if term and not term.startswith("@")
             }
 
+    def describe_tag_cooccurrence(self, *, anchors: Iterable[str], terms: Iterable[str]) -> Dict[str, TagCooccurrence]:
+        """For each term, the notes carrying it together with the most of the anchors.
+
+        The same measure `suggest_tag_completions` ranks by (the most anchors one
+        of the term's notes carries, and how many notes carry that many), with
+        the anchors named. Terms on no note with an anchor are left out.
+        """
+        anchor_casefold_set = frozenset(
+            anchor.casefold() for anchor in anchors if anchor and not anchor.startswith("@")
+        )
+        described: Dict[str, TagCooccurrence] = {}
+        with self._lock:
+            for term in terms:
+                term_casefold = term.casefold()
+                if term_casefold not in self._tag_notes_casefold:
+                    continue
+                term_notes = self._tag_notes_casefold[term_casefold]
+                anchors_by_note: Dict[int, Set[str]] = {}
+                for anchor_casefold in anchor_casefold_set:
+                    if anchor_casefold == term_casefold or anchor_casefold not in self._tag_notes_casefold:
+                        continue
+                    for note_id in term_notes & self._tag_notes_casefold[anchor_casefold]:
+                        anchors_by_note.setdefault(note_id, set()).add(anchor_casefold)
+                if not anchors_by_note:
+                    continue
+                most_anchors = max(len(note_anchors) for note_anchors in anchors_by_note.values())
+                at_most = [frozenset(note_anchors) for note_anchors in anchors_by_note.values()
+                           if len(note_anchors) == most_anchors]
+                described[term] = TagCooccurrence(
+                    anchor_count=most_anchors, note_count=len(at_most), anchor_sets=frozenset(at_most),
+                )
+        return described
+
+    def describe_search_suggestions(self, *, query: str, terms: Iterable[str]) -> SearchSuggestionFacts:
+        """The facts `suggest_all_tag_completions` ranked and filtered these terms by."""
+        context = _parse_search_suggestion_context(query)
+        partial_prefix = ""
+        if context.partial_prefix is not None:
+            partial_prefix = context.partial_prefix
+        shown = list(terms)
+        with self._lock:
+            has_completed_clause = context.completed_clause.strip() != ""
+            if has_completed_clause:
+                clause = parse_search_query(context.completed_clause).first_clause
+                matching_ids = self._matching_note_int_ids_for_clause_locked(clause)
+            else:
+                matching_ids = self._alive
+            note_counts: Dict[str, int] = {}
+            matching_counts: Dict[str, int] = {}
+            for term in shown:
+                posting: FrozenSet[int] = frozenset()
+                if term.casefold() in self._tag_notes_casefold:
+                    posting = frozenset(self._tag_notes_casefold[term.casefold()])
+                note_counts[term] = len(posting)
+                matching_counts[term] = len(posting & matching_ids)
+            cooccurrences = self.describe_tag_cooccurrence(anchors=context.anchors, terms=shown)
+            return SearchSuggestionFacts(
+                partial_prefix=partial_prefix, anchors=tuple(context.anchors),
+                has_completed_clause=has_completed_clause, is_exclusion=context.is_exclusion,
+                matching_note_count=len(matching_ids), note_counts=note_counts,
+                matching_counts=matching_counts, cooccurrences=cooccurrences,
+            )
+
+    def count_notes_with_tag(self, term: str) -> int:
+        """Notes carrying the tag, as suggestions count usage (case-insensitive)."""
+        if not isinstance(term, str) or term == "":
+            raise TypeError("term must be a non-empty string")
+        with self._lock:
+            term_casefold = term.casefold()
+            if term_casefold not in self._tag_notes_casefold:
+                return 0
+            return len(self._tag_notes_casefold[term_casefold])
+
     def suggest_tag_completions(self, *, query: str, limit: int) -> List[str]:
         if not isinstance(query, str):
             raise TypeError(f"query must be a string, got {type(query)}")

metalist-0.18.0/app/services/tag_suggestion_reasons.py

@@ -0,0 +1,326 @@
+"""Why a tag is suggested, in the tag bar or the search bar: short reasons shown on right-click.
+
+The facts come from the rankings (`tag_suggestions` for the tag bar: what the
+note's text names, which of its tags the tag goes with, which notes share its
+tags; the search index and search history for the search bar): the reasons say
+what the ranking used, never a second guess at it. Only the shown suggestions
+are explained (docs/ui/tag-bar.md, docs/ui/controls.md).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, FrozenSet, Iterable, List, Mapping, Tuple
+
+from app.services.search_index import SearchIndex
+from app.services.search_index import SearchSuggestionFacts
+from app.services.search_index import TagCooccurrence
+from app.services.tag_ontology import TagOntology
+from app.services.tag_term_matching import TagContentMatch
+from app.services.tag_term_matching import quote_content_match
+
+NOTHING_POINTS_TO_IT = "Nothing in this note points to it"
+
+
+@dataclass(frozen=True, slots=True)
+class TagSuggestion:
+    tag: str
+    reasons: Tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.tag, str) or self.tag == "":
+            raise ValueError("A tag suggestion needs a tag")
+        if not isinstance(self.reasons, tuple) or not self.reasons:
+            raise ValueError(f"Tag suggestion {self.tag!r} needs at least one reason")
+        for reason in self.reasons:
+            if not isinstance(reason, str) or reason.strip() == "":
+                raise ValueError(f"Tag suggestion {self.tag!r} has an empty reason")
+
+
+@dataclass(frozen=True)
+class ContextOverlap:
+    """Other notes that share the most of this note's tags and have the term written on them."""
+
+    shared_count: int
+    note_count: int
+    # The shared tags (casefolded) of those notes; a second set means they differ.
+    shared_casefold_sets: Tuple[FrozenSet[str], ...]
+
+    def __post_init__(self) -> None:
+        assert self.shared_count > 0 and self.note_count > 0
+        assert 1 <= len(self.shared_casefold_sets) <= 2
+        assert all(len(shared) == self.shared_count for shared in self.shared_casefold_sets)
+
+
+def _quoted(text: str) -> str:
+    return f'"{text}"'
+
+
+def _join_names(names: Iterable[str]) -> str:
+    quoted = [_quoted(name) for name in sorted(names, key=lambda name: (name.casefold(), name))]
+    assert quoted
+    if len(quoted) == 1:
+        return quoted[0]
+    return ", ".join(quoted[:-1]) + " and " + quoted[-1]
+
+
+def _count_notes(count: int) -> str:
+    assert count > 0
+    if count == 1:
+        return "1 note"
+    return f"{count:,} notes"
+
+
+def _usage_line(count: int) -> str:
+    assert count > 0
+    return f"You've tagged {_count_notes(count)} with it"
+
+
+def _names_for(casefold_names: FrozenSet[str], display_by_casefold: Mapping[str, str]) -> List[str]:
+    for name in casefold_names:
+        assert name in display_by_casefold, name
+    return [display_by_casefold[name] for name in casefold_names]
+
+
+def _cooccurrence_phrase(cooccurrence: TagCooccurrence, anchors: Iterable[str], anchors_name: str) -> str:
+    """`on 4 notes together with "python"`, naming the anchors those notes carry
+    (or how many of them, `anchors_name` saying whose they are)."""
+    notes = _count_notes(cooccurrence.note_count)
+    if len(cooccurrence.anchor_sets) > 1:
+        return f"on {notes} together with {cooccurrence.anchor_count} of {anchors_name}"
+    display_by_casefold = {anchor.casefold(): anchor for anchor in anchors}
+    (anchor_set,) = cooccurrence.anchor_sets
+    return f"on {notes} together with {_join_names(_names_for(anchor_set, display_by_casefold))}"
+
+
+def _count_times(count: int) -> str:
+    assert count > 0
+    if count == 1:
+        return "once"
+    if count == 2:
+        return "twice"
+    return f"{count:,} times"
+
+
+@dataclass(frozen=True)
+class ReasonWriter:
+    """Reasons any suggestion can have: whether it already applies, and its use."""
+
+    count_by_casefold: Mapping[str, int]
+    ontology_only_casefold: FrozenSet[str]
+    inherited_casefold: FrozenSet[str]
+    implied_casefold: FrozenSet[str]
+    base_tags: FrozenSet[str]
+    ontology: TagOntology
+
+    @classmethod
+    def build(
+        cls, *, exact_tag_counts: Mapping[str, int], ontology_only_casefold: FrozenSet[str],
+        inherited_non_meta: FrozenSet[str], base_tags: FrozenSet[str], ontology: TagOntology,
+    ) -> ReasonWriter:
+        count_by_casefold: Dict[str, int] = {}
+        for term, count in exact_tag_counts.items():
+            assert term.casefold() not in count_by_casefold, f"case variants are merged before counting: {term}"
+            count_by_casefold[term.casefold()] = count
+        base_casefold = frozenset(tag.casefold() for tag in base_tags)
+        implied_casefold: FrozenSet[str] = frozenset()
+        if not ontology.is_empty:
+            implied_casefold = frozenset(
+                tag.casefold() for tag in ontology.infer_implication_only(base_tags=base_tags)
+            ) - base_casefold
+        return cls(
+            count_by_casefold=count_by_casefold, ontology_only_casefold=ontology_only_casefold,
+            inherited_casefold=frozenset(tag.casefold() for tag in inherited_non_meta),
+            implied_casefold=implied_casefold, base_tags=base_tags, ontology=ontology,
+        )
+
+    def already_applies(self, term: str) -> Tuple[str, ...]:
+        term_casefold = term.casefold()
+        if term_casefold in self.inherited_casefold:
+            return ("Already applies: inherited from a parent note",)
+        if term_casefold not in self.implied_casefold:
+            return ()
+        for base in sorted(self.base_tags, key=lambda tag: (tag.casefold(), tag)):
+            implied = self.ontology.infer_implication_only(base_tags=frozenset({base}))
+            if term_casefold in {tag.casefold() for tag in implied}:
+                return (f"Already applies: implied by {_quoted(base)}",)
+        # Implied only by several of the note's tags together.
+        return ("Already applies: implied by this note's tags",)
+
+    def usage(self, term: str) -> str:
+        term_casefold = term.casefold()
+        if term_casefold in self.count_by_casefold and self.count_by_casefold[term_casefold] > 0:
+            return _usage_line(self.count_by_casefold[term_casefold])
+        assert term_casefold in self.ontology_only_casefold, f"suggested tag {term!r} is on no note"
+        return "Not on any note yet; it is in your tag relationships"
+
+    def without_evidence(self, term: str) -> Tuple[str, ...]:
+        """A tag listed for its use (or because it already applies), not for this note."""
+        already = self.already_applies(term)
+        if already:
+            return (*already, self.usage(term))
+        return (NOTHING_POINTS_TO_IT, self.usage(term))
+
+
+def meta_tag_reasons(*, index: SearchIndex, term: str, prefix: str) -> Tuple[str, ...]:
+    """Meta tags are listed by use once `@` is typed."""
+    assert term.startswith("@") and prefix.startswith("@"), (term, prefix)
+    count = index.count_notes_with_tag(term)
+    usage = "Not on any note yet"
+    if count > 0:
+        usage = _usage_line(count)
+    return (f"A built-in tag starting with {_quoted(prefix)}", usage)
+
+
+@dataclass(frozen=True)
+class SuggestionEvidence:
+    """What one ranking found for its terms, to say why a shown tag is suggested."""
+
+    # The index the ranking used, for the co-occurring notes behind a reason.
+    index: SearchIndex
+    writer: ReasonWriter
+    prefix: str
+    content_matches: Mapping[str, TagContentMatch]
+    # Terms whose content match is the rest of the tag after the typed prefix.
+    prefix_remainder_terms: FrozenSet[str]
+    # Synonym named exactly in the content -> (the tag it is a synonym of, its match).
+    synonym_matches: Mapping[str, Tuple[str, TagContentMatch]]
+    cooccurrence_terms: FrozenSet[str]
+    cooccurrence_anchors: Tuple[str, ...]
+    saved_text_matches: Mapping[str, TagContentMatch]
+    overlaps: Mapping[str, ContextOverlap]
+    context_tags: FrozenSet[str]
+    # Shown tag -> the ranked terms it stands for (equivalent tags are shown once).
+    sources: Mapping[str, Tuple[str, ...]]
+
+    def reasons_for(self, tag: str) -> Tuple[str, ...]:
+        assert tag in self.sources, f"{tag!r} was not ranked"
+        subjects = [tag] + [term for term in self.sources[tag] if term != tag]
+        cooccurrences = self.index.describe_tag_cooccurrence(
+            anchors=self.cooccurrence_anchors,
+            terms=[subject for subject in subjects if subject in self.cooccurrence_terms],
+        )
+        lines: List[str] = []
+        for subject in subjects:
+            lines.extend(self._evidence(subject=subject, shown=tag, cooccurrences=cooccurrences))
+        lines.extend(self.writer.already_applies(tag))
+        if not lines:
+            lines.append(NOTHING_POINTS_TO_IT)
+        lines.append(self.writer.usage(tag))
+        return tuple(dict.fromkeys(lines))
+
+    def _evidence(self, *, subject: str, shown: str, cooccurrences: Mapping[str, TagCooccurrence]) -> List[str]:
+        lines: List[str] = []
+        if subject in self.synonym_matches:
+            representative, match = self.synonym_matches[subject]
+            lines.append(self._named(match=match, shown=shown, where="this note", is_remainder=False))
+            lines.append(f"A synonym of {_quoted(representative)}")
+        elif subject in self.content_matches:
+            lines.append(self._named(
+                match=self.content_matches[subject], shown=shown, where="this note",
+                is_remainder=subject in self.prefix_remainder_terms,
+            ))
+        if subject in self.cooccurrence_terms:
+            assert subject in cooccurrences, f"{subject!r} was ranked as co-occurring"
+            lines.append(self._about(subject, shown, self._cooccurrence(cooccurrences[subject])))
+        if subject in self.saved_text_matches and subject not in self.content_matches:
+            lines.append(self._named(
+                match=self.saved_text_matches[subject], shown=shown, where="this note as last saved",
+                is_remainder=False,
+            ))
+        if subject in self.overlaps and subject not in self.cooccurrence_terms:
+            overlap = self._overlap(subject=subject, overlap=self.overlaps[subject])
+            if overlap != "":
+                lines.append(self._about(subject, shown, overlap))
+        return lines
+
+    def _named(self, *, match: TagContentMatch, shown: str, where: str, is_remainder: bool) -> str:
+        quoted = ", ".join(_quoted(words) for words in quote_content_match(match))
+        # Whole only when every part of the tag was found (`topic-41` is partly named by "topic").
+        is_whole = len(match.evidence_raw_indexes) == match.raw_segment_count
+        if is_remainder:
+            return f"The rest of it after {_quoted(self.prefix)} is in {where}: {quoted}"
+        if match.term.casefold() == shown.casefold():
+            if is_whole:
+                return f"Named in {where}: {quoted}"
+            return f"Partly named in {where}: {quoted}"
+        where_capitalized = where[0].upper() + where[1:]
+        if is_whole:
+            return f"{where_capitalized} names its synonym {_quoted(match.term)}"
+        return f"{where_capitalized} partly names its synonym {_quoted(match.term)}: {quoted}"
+
+    def _cooccurrence(self, cooccurrence: TagCooccurrence) -> str:
+        return _cooccurrence_phrase(cooccurrence, self.cooccurrence_anchors, "this note's tags")
+
+    def _overlap(self, *, subject: str, overlap: ContextOverlap) -> str:
+        """Empty when the only tag shared is the term itself (a tag that already
+        applies, ranked when that setting is on): notes with it have it."""
+        notes = _count_notes(overlap.note_count)
+        # The term itself is no evidence for itself.
+        shared_sets = [shared - {subject.casefold()} for shared in overlap.shared_casefold_sets]
+        if any(not shared for shared in shared_sets):
+            return ""
+        if len(shared_sets) > 1:
+            shared_count = min(len(shared) for shared in shared_sets)
+            return f"on {notes} sharing {shared_count} of this note's tags"
+        display_by_casefold = {tag.casefold(): tag for tag in self.context_tags}
+        names = _join_names(_names_for(shared_sets[0], display_by_casefold))
+        verb = "share"
+        if overlap.note_count == 1:
+            verb = "shares"
+        return f"on {notes} that {verb} {names} with this one"
+
+    @staticmethod
+    def _about(subject: str, shown: str, finding: str) -> str:
+        """A finding about the shown tag, or about a synonym it is shown in place of."""
+        if subject == shown:
+            return finding[0].upper() + finding[1:]
+        return f"Its synonym {_quoted(subject)} is {finding}"
+
+
+def search_suggestion_reasons(
+    *, facts: SearchSuggestionFacts, term: str, recent_activity: Mapping[str, Tuple[int, int]],
+) -> Tuple[str, ...]:
+    """Why the search bar suggests a tag.
+
+    recent_activity: casefolded tag -> (window days, activity credits) for the
+    tags a personalization window put first.
+    """
+    assert term in facts.note_counts, f"{term!r} was not described"
+    lines: List[str] = []
+    if term.casefold() in recent_activity:
+        window_days, activity_count = recent_activity[term.casefold()]
+        when = "today"
+        if window_days > 1:
+            when = f"in the last {window_days} days"
+        lines.append(f"You've worked with it {_count_times(activity_count)} {when}")
+    note_count = facts.note_counts[term]
+    if facts.partial_prefix.startswith("@"):
+        lines.append(f"A built-in tag starting with {_quoted(facts.partial_prefix)}")
+        if note_count == 0:
+            lines.append("Not on any note yet")
+            return tuple(lines)
+        lines.append(f"Searching for it finds {_count_notes(note_count)}")
+        return tuple(lines)
+    if facts.is_exclusion:
+        lines.append(_exclusion_line(facts=facts, term=term))
+    elif term in facts.cooccurrences:
+        finding = _cooccurrence_phrase(facts.cooccurrences[term], facts.anchors, "the tags in your search")
+        lines.append(finding[0].upper() + finding[1:])
+    elif facts.has_completed_clause:
+        lines.append(f"Your search so far finds it on {_count_notes(facts.matching_counts[term])}")
+    else:
+        lines.append("Tags are listed by how many notes have them")
+    assert note_count > 0, f"suggested search tag {term!r} is on no note"
+    lines.append(f"Searching for it finds {_count_notes(note_count)}")
+    return tuple(lines)
+
+
+def _exclusion_line(*, facts: SearchSuggestionFacts, term: str) -> str:
+    removed = facts.matching_counts[term]
+    of_notes = f"of your {facts.matching_note_count:,} notes"
+    if facts.has_completed_clause:
+        of_notes = f"of the {facts.matching_note_count:,} notes your search finds"
+    if removed == 0:
+        return f"Leaving it out removes none {of_notes}"
+    return f"Leaving it out removes {removed:,} {of_notes}"