Function _update_index

openkb/agent/compiler.py:1484–1554

Append document and concept entries to index.md. When ``doc_brief`` or entries in ``concept_briefs`` are provided, entries are written as ``- [[link]] (type) — brief text``. Existing entries are detected within their own section by exact entry prefix and skipped to avoid duplicates.

(
    wiki_dir: Path,
    doc_name: str,
    concept_names: list[str],
    doc_brief: str = "",
    concept_briefs: dict[str, str] | None = None,
    doc_type: str = "short",
    entity_names: list[str] | None = None,
    entity_meta: dict[str, tuple[str, str]] | None = None,
)

def _update_index(
    wiki_dir: Path,
    doc_name: str,
    concept_names: list[str],
    doc_brief: str = "",
    concept_briefs: dict[str, str] | None = None,
    doc_type: str = "short",
    entity_names: list[str] | None = None,
    entity_meta: dict[str, tuple[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]] (type) — brief text``. Existing entries are
    detected within their own section by exact entry prefix and skipped to
    avoid duplicates.
    ``doc_type`` is ``"short"`` or ``"pageindex"`` — shown in the entry so the
    query agent knows how to access detailed content.
    """
    if concept_briefs is None:
        concept_briefs = {}

    index_path = wiki_dir / "index.md"
    if not index_path.exists():
        atomic_write_text(index_path, INDEX_SEED)

    lines = index_path.read_text(encoding="utf-8").split("\n")

    _ensure_h2_section(lines, "## Documents")
    if concept_names:
        _ensure_h2_section(lines, "## Concepts")

    doc_link = f"[[summaries/{doc_name}]]"
    if not _section_contains_link(lines, "## Documents", doc_link):
        doc_entry = f"- {doc_link} ({doc_type})"
        if doc_brief:
            doc_entry += f" — {doc_brief}"
        _insert_section_entry(lines, "## Documents", doc_entry)

    for name in concept_names:
        concept_link = f"[[concepts/{name}]]"
        concept_entry = f"- {concept_link}"
        if name in concept_briefs:
            concept_entry += f" — {concept_briefs[name]}"
        if _section_contains_link(lines, "## Concepts", concept_link):
            if name in concept_briefs:
                _replace_section_entry(lines, "## Concepts", concept_link, concept_entry)
        else:
            _insert_section_entry(lines, "## Concepts", concept_entry)

    entity_names = entity_names or []
    entity_meta = entity_meta or {}
    if entity_names:
        # Keep canonical order: Entities sits before Explorations. On an older
        # index.md that predates the Entities section, plain ``_ensure_h2_section``
        # would append it after Explorations.
        _ensure_h2_section_before(lines, "## Entities", "## Explorations")
    for name in entity_names: