feat: bidirectional backlinks between summaries and concepts

- Add _backlink_summary: ensures summary pages link to all related concepts
- Add _backlink_concepts: ensures concept pages link back to source summaries
- _update_index auto-creates index.md if missing
- Both merge into existing sections instead of duplicating

Author: KylinMountain

openkb/agent/compiler.py

@@ -351,11 +351,68 @@ def _add_related_link(wiki_dir: Path, concept_slug: str, doc_name: str, source_f
     path.write_text(text, encoding="utf-8")
 
 
+def _backlink_summary(wiki_dir: Path, doc_name: str, concept_slugs: list[str]) -> None:
+    """Append missing concept wikilinks to the summary page (no LLM call).
+
+    After all concepts are generated, this ensures the summary page links
+    back to every related concept — closing the bidirectional link that
+    concept pages already have toward the summary.
+
+    If a ``## Related Concepts`` section already exists, new links are
+    appended into it rather than creating a duplicate section.
+    """
+    summary_path = wiki_dir / "summaries" / f"{doc_name}.md"
+    if not summary_path.exists():
+        return
+
+    text = summary_path.read_text(encoding="utf-8")
+    missing = [slug for slug in concept_slugs if f"[[concepts/{slug}]]" not in text]
+    if not missing:
+        return
+
+    new_links = "\n".join(f"- [[concepts/{s}]]" for s in missing)
+    if "## Related Concepts" in text:
+        # Append into existing section
+        text = text.replace("## Related Concepts\n", f"## Related Concepts\n{new_links}\n", 1)
+    else:
+        text += f"\n\n## Related Concepts\n{new_links}\n"
+    summary_path.write_text(text, encoding="utf-8")
+
+
+def _backlink_concepts(wiki_dir: Path, doc_name: str, concept_slugs: list[str]) -> None:
+    """Append missing summary wikilink to each concept page (no LLM call).
+
+    Ensures every concept page links back to the source document's summary,
+    regardless of whether the LLM included the link in its output.
+
+    If a ``## Related Documents`` section already exists, the link is
+    appended into it rather than creating a duplicate section.
+    """
+    link = f"[[summaries/{doc_name}]]"
+    concepts_dir = wiki_dir / "concepts"
+
+    for slug in concept_slugs:
+        path = concepts_dir / f"{slug}.md"
+        if not path.exists():
+            continue
+        text = path.read_text(encoding="utf-8")
+        if link in text:
+            continue
+        if "## Related Documents" in text:
+            text = text.replace("## Related Documents\n", f"## Related Documents\n- {link}\n", 1)
+        else:
+            text += f"\n\n## Related Documents\n- {link}\n"
+        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."""
     index_path = wiki_dir / "index.md"
     if not index_path.exists():
-        return
+        index_path.write_text(
+            "# Knowledge Base Index\n\n## Documents\n\n## Concepts\n\n## Explorations\n",
+            encoding="utf-8",
+        )
 
     text = index_path.read_text(encoding="utf-8")
 
@@ -503,6 +560,12 @@ async def _gen_update(concept: dict) -> tuple[str, str, bool]:
     for slug in related_items:
         _add_related_link(wiki_dir, slug, doc_name, source_file)
 
+    # --- Step 3c: Backlink — summary ↔ concepts (code only) ---
+    all_concept_slugs = concept_names + [s for s in related_items]
+    if all_concept_slugs:
+        _backlink_summary(wiki_dir, doc_name, all_concept_slugs)
+        _backlink_concepts(wiki_dir, doc_name, all_concept_slugs)
+
     # --- Step 4: Update index (code only) ---
     _update_index(wiki_dir, doc_name, concept_names)
 

tests/test_compiler.py

@@ -18,6 +18,8 @@
     _read_wiki_context,
     _read_concept_briefs,
     _add_related_link,
+    _backlink_summary,
+    _backlink_concepts,
 )
 
 
@@ -207,6 +209,114 @@ def test_sorted_alphabetically(self, tmp_path):
         assert slugs == ["apple", "mango", "zebra"]
 
 
+class TestBacklinkSummary:
+    def test_adds_missing_concept_links(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        summaries = wiki / "summaries"
+        summaries.mkdir(parents=True)
+        (summaries / "paper.md").write_text(
+            "---\nsources: [paper.pdf]\n---\n\n# Summary\n\nContent about attention.",
+            encoding="utf-8",
+        )
+        _backlink_summary(wiki, "paper", ["attention", "transformer"])
+        text = (summaries / "paper.md").read_text()
+        assert "[[concepts/attention]]" in text
+        assert "[[concepts/transformer]]" in text
+
+    def test_skips_already_linked(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        summaries = wiki / "summaries"
+        summaries.mkdir(parents=True)
+        (summaries / "paper.md").write_text(
+            "---\nsources: [paper.pdf]\n---\n\n# Summary\n\nSee [[concepts/attention]].",
+            encoding="utf-8",
+        )
+        _backlink_summary(wiki, "paper", ["attention", "transformer"])
+        text = (summaries / "paper.md").read_text()
+        # attention already linked, should not duplicate
+        assert text.count("[[concepts/attention]]") == 1
+        # transformer should be added
+        assert "[[concepts/transformer]]" in text
+
+    def test_no_op_when_all_linked(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        summaries = wiki / "summaries"
+        summaries.mkdir(parents=True)
+        original = "# Summary\n\n[[concepts/attention]] and [[concepts/transformer]]"
+        (summaries / "paper.md").write_text(original, encoding="utf-8")
+        _backlink_summary(wiki, "paper", ["attention", "transformer"])
+        assert (summaries / "paper.md").read_text() == original
+
+    def test_skips_if_file_missing(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        wiki.mkdir()
+        # Should not raise
+        _backlink_summary(wiki, "nonexistent", ["attention"])
+
+    def test_merges_into_existing_section(self, tmp_path):
+        """Second add should merge into existing ## Related Concepts, not duplicate."""
+        wiki = tmp_path / "wiki"
+        summaries = wiki / "summaries"
+        summaries.mkdir(parents=True)
+        (summaries / "paper.md").write_text(
+            "# Summary\n\nContent.\n\n## Related Concepts\n- [[concepts/attention]]\n",
+            encoding="utf-8",
+        )
+        _backlink_summary(wiki, "paper", ["attention", "transformer"])
+        text = (summaries / "paper.md").read_text()
+        assert text.count("## Related Concepts") == 1
+        assert "[[concepts/transformer]]" in text
+        assert text.count("[[concepts/attention]]") == 1
+
+
+class TestBacklinkConcepts:
+    def test_adds_summary_link_to_concept(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        concepts = wiki / "concepts"
+        concepts.mkdir(parents=True)
+        (concepts / "attention.md").write_text(
+            "---\nsources: [paper.pdf]\n---\n\n# Attention\n\nContent.",
+            encoding="utf-8",
+        )
+        _backlink_concepts(wiki, "paper", ["attention"])
+        text = (concepts / "attention.md").read_text()
+        assert "[[summaries/paper]]" in text
+        assert "## Related Documents" in text
+
+    def test_skips_if_already_linked(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        concepts = wiki / "concepts"
+        concepts.mkdir(parents=True)
+        (concepts / "attention.md").write_text(
+            "# Attention\n\nBased on [[summaries/paper]].",
+            encoding="utf-8",
+        )
+        _backlink_concepts(wiki, "paper", ["attention"])
+        text = (concepts / "attention.md").read_text()
+        assert text.count("[[summaries/paper]]") == 1
+        assert "## Related Documents" not in text
+
+    def test_merges_into_existing_section(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        concepts = wiki / "concepts"
+        concepts.mkdir(parents=True)
+        (concepts / "attention.md").write_text(
+            "# Attention\n\n## Related Documents\n- [[summaries/old-paper]]\n",
+            encoding="utf-8",
+        )
+        _backlink_concepts(wiki, "new-paper", ["attention"])
+        text = (concepts / "attention.md").read_text()
+        assert text.count("## Related Documents") == 1
+        assert "[[summaries/old-paper]]" in text
+        assert "[[summaries/new-paper]]" in text
+
+    def test_skips_missing_concept_file(self, tmp_path):
+        wiki = tmp_path / "wiki"
+        (wiki / "concepts").mkdir(parents=True)
+        # Should not raise
+        _backlink_concepts(wiki, "paper", ["nonexistent"])
+
+
 class TestAddRelatedLink:
     def test_adds_see_also_link(self, tmp_path):
         wiki = tmp_path / "wiki"