feat: add briefs to index.md entries and read from frontmatter

Author: KylinMountain

openkb/agent/compiler.py

@@ -439,8 +439,19 @@ def _backlink_concepts(wiki_dir: Path, doc_name: str, concept_slugs: list[str])
         path.write_text(text, encoding="utf-8")
 
 
-def _update_index(wiki_dir: Path, doc_name: str, concept_names: list[str]) -> None:
-    """Append document and concept entries to index.md."""
+def _update_index(
+    wiki_dir: Path, doc_name: str, concept_names: list[str],
+    doc_brief: str = "", concept_briefs: dict[str, str] | None = None,
+) -> None:
+    """Append document and concept entries to index.md.
+
+    When ``doc_brief`` or entries in ``concept_briefs`` are provided, entries
+    are written as ``- [[link]] — brief text``.  Existing entries are detected
+    by the link part only, so updating a brief on a re-compile works correctly.
+    """
+    if concept_briefs is None:
+        concept_briefs = {}
+
     index_path = wiki_dir / "index.md"
     if not index_path.exists():
         index_path.write_text(
@@ -450,14 +461,20 @@ def _update_index(wiki_dir: Path, doc_name: str, concept_names: list[str]) -> No
 
     text = index_path.read_text(encoding="utf-8")
 
-    doc_entry = f"- [[summaries/{doc_name}]]"
-    if doc_entry not in text:
+    doc_link = f"[[summaries/{doc_name}]]"
+    if doc_link not in text:
+        doc_entry = f"- {doc_link}"
+        if doc_brief:
+            doc_entry += f" — {doc_brief}"
         if "## Documents" in text:
             text = text.replace("## Documents\n", f"## Documents\n{doc_entry}\n", 1)
 
     for name in concept_names:
-        concept_entry = f"- [[concepts/{name}]]"
-        if concept_entry not in text:
+        concept_link = f"[[concepts/{name}]]"
+        if concept_link not in text:
+            concept_entry = f"- {concept_link}"
+            if name in concept_briefs:
+                concept_entry += f" — {concept_briefs[name]}"
             if "## Concepts" in text:
                 text = text.replace("## Concepts\n", f"## Concepts\n{concept_entry}\n", 1)
 

tests/test_compiler.py

@@ -149,30 +149,44 @@ def test_update_concept_appends_source(self, tmp_path):
 
 
 class TestUpdateIndex:
-    def test_appends_entries(self, tmp_path):
+    def test_appends_entries_with_briefs(self, tmp_path):
         wiki = tmp_path / "wiki"
         wiki.mkdir()
         (wiki / "index.md").write_text(
             "# Index\n\n## Documents\n\n## Concepts\n\n## Explorations\n",
             encoding="utf-8",
         )
-        _update_index(wiki, "my-doc", ["attention", "transformer"])
+        _update_index(wiki, "my-doc", ["attention", "transformer"],
+                       doc_brief="Introduces transformers",
+                       concept_briefs={"attention": "Focus mechanism", "transformer": "NN architecture"})
         text = (wiki / "index.md").read_text()
-        assert "[[summaries/my-doc]]" in text
-        assert "[[concepts/attention]]" in text
-        assert "[[concepts/transformer]]" in text
+        assert "[[summaries/my-doc]] — Introduces transformers" in text
+        assert "[[concepts/attention]] — Focus mechanism" in text
+        assert "[[concepts/transformer]] — NN architecture" in text
 
     def test_no_duplicates(self, tmp_path):
         wiki = tmp_path / "wiki"
         wiki.mkdir()
         (wiki / "index.md").write_text(
-            "# Index\n\n## Documents\n- [[summaries/my-doc]]\n\n## Concepts\n",
+            "# Index\n\n## Documents\n- [[summaries/my-doc]] — Old brief\n\n## Concepts\n",
             encoding="utf-8",
         )
-        _update_index(wiki, "my-doc", [])
+        _update_index(wiki, "my-doc", [], doc_brief="New brief")
         text = (wiki / "index.md").read_text()
         assert text.count("[[summaries/my-doc]]") == 1
 
+    def test_backwards_compat_no_briefs(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        wiki.mkdir()
+        (wiki / "index.md").write_text(
+            "# Index\n\n## Documents\n\n## Concepts\n\n## Explorations\n",
+            encoding="utf-8",
+        )
+        _update_index(wiki, "my-doc", ["attention"])
+        text = (wiki / "index.md").read_text()
+        assert "[[summaries/my-doc]]" in text
+        assert "[[concepts/attention]]" in text
+
 
 class TestReadWikiContext:
     def test_empty_wiki(self, tmp_path):
@@ -257,6 +271,28 @@ def test_sorted_alphabetically(self, tmp_path):
         slugs = [line.split(":")[0].lstrip("- ") for line in lines]
         assert slugs == ["apple", "mango", "zebra"]
 
+    def test_reads_brief_from_frontmatter(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        concepts = wiki / "concepts"
+        concepts.mkdir(parents=True)
+        (concepts / "attention.md").write_text(
+            "---\nsources: [paper.pdf]\nbrief: Selective focus mechanism\n---\n\n# Attention\n\nLong content...",
+            encoding="utf-8",
+        )
+        result = _read_concept_briefs(wiki)
+        assert "- attention: Selective focus mechanism" in result
+
+    def test_falls_back_to_body_truncation(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        concepts = wiki / "concepts"
+        concepts.mkdir(parents=True)
+        (concepts / "old.md").write_text(
+            "---\nsources: [paper.pdf]\n---\n\nOld concept without brief field.",
+            encoding="utf-8",
+        )
+        result = _read_concept_briefs(wiki)
+        assert "- old: Old concept without brief field." in result
+
 
 class TestBacklinkSummary:
     def test_adds_missing_concept_links(self, tmp_path):