feat(entities): shared page-dir constants + surface entities in list/lint/status/skill-gate/linter

Add PAGE_CONTENT_DIRS and INDEX_SEED to openkb/schema.py as the single
source of truth; replace duplicated index-seed literals in cli init and
compiler._update_index with INDEX_SEED.

- openkb list / chat /list: add an Entities section (#2)
- lint.check_index_sync: iterate PAGE_CONTENT_DIRS so entities/ pages
  missing from index.md are flagged (#4)
- skill-new gate: count entities/ as compiled content (#5)
- status last-compile: derive from summaries/concepts/entities mtimes (#12)
- semantic linter: read entities/, check contradictions/redundancy/
  coverage/orphans (#3)

Author: KylinMountain

openkb/agent/compiler.py

@@ -30,7 +30,7 @@
 import yaml
 
 from openkb.lint import list_existing_wiki_targets, strip_ghost_wikilinks
-from openkb.schema import get_agents_md
+from openkb.schema import INDEX_SEED, get_agents_md
 
 logger = logging.getLogger(__name__)
 
@@ -1219,11 +1219,7 @@ def _update_index(
 
     index_path = wiki_dir / "index.md"
     if not index_path.exists():
-        index_path.write_text(
-            "# Knowledge Base Index\n\n## Documents\n\n## Concepts\n\n"
-            "## Entities\n\n## Explorations\n",
-            encoding="utf-8",
-        )
+        index_path.write_text(INDEX_SEED, encoding="utf-8")
 
     lines = index_path.read_text(encoding="utf-8").split("\n")
 

openkb/agent/linter.py

@@ -24,12 +24,16 @@
 4. **Redundancy** — Are there multiple pages that cover the same content and
    could be merged?
 5. **Concept coverage** — Are important themes in the summaries missing concept pages?
+6. **Entity coverage** — Are important named things (people, organizations, places,
+   products, works, events) in the summaries missing entity pages, or are existing
+   entity pages contradictory, redundant, or orphaned (unlinked from any source)?
 
 ## Process
 1. Start with index.md to understand scope.
 2. Read summary pages to understand document content.
 3. Read concept pages to check for contradictions and gaps.
-4. Produce a structured Markdown report listing issues found with references
+4. Read entity pages to check for contradictions, redundancy, coverage, and orphans.
+5. Produce a structured Markdown report listing issues found with references
    to the specific pages where each issue occurs.
 
 Be thorough but concise. If the wiki is small or sparse, say so.
@@ -99,9 +103,9 @@ async def run_knowledge_lint(kb_dir: Path, model: str) -> str:
 
     prompt = (
         "Please audit this knowledge base wiki for semantic quality issues: "
-        "contradictions, gaps, staleness, redundancy, and missing concept pages. "
-        "Start with index.md, then read summaries and concepts as needed. "
-        "Produce a structured Markdown report."
+        "contradictions, gaps, staleness, redundancy, and missing concept and "
+        "entity pages. Start with index.md, then read summaries, concepts, and "
+        "entities as needed. Produce a structured Markdown report."
     )
 
     result = await Runner.run(agent, prompt, max_turns=MAX_TURNS)

openkb/cli.py

@@ -43,7 +43,7 @@ def filter(self, record: logging.LogRecord) -> bool:
 from openkb.config import DEFAULT_CONFIG, load_config, save_config, load_global_config, register_kb
 from openkb.converter import convert_document
 from openkb.log import append_log
-from openkb.schema import AGENTS_MD
+from openkb.schema import AGENTS_MD, INDEX_SEED, PAGE_CONTENT_DIRS
 
 # Suppress warnings after all imports — markitdown overrides filters at import time
 import warnings
@@ -217,7 +217,7 @@ def _preflight_skill_new(kb_dir: Path, name: str) -> str | None:
     Checks (in order):
       * skill name is a valid kebab-case slug
       * ``<kb>/wiki`` exists
-      * ``<kb>/wiki/concepts`` or ``<kb>/wiki/summaries`` has at least
+      * any of ``<kb>/wiki/{summaries,concepts,entities}`` has at least
         one file (i.e. some document has been ingested + compiled)
 
     Returns ``None`` if all gates pass, else a single-line error message
@@ -239,7 +239,7 @@ def _preflight_skill_new(kb_dir: Path, name: str) -> str | None:
 
     has_content = any(
         (wiki / sub).is_dir() and any((wiki / sub).iterdir())
-        for sub in ("concepts", "summaries")
+        for sub in PAGE_CONTENT_DIRS
     )
     if not has_content:
         return (
@@ -542,10 +542,7 @@ def init(model, language):
 
     # Write wiki files
     Path("wiki/AGENTS.md").write_text(AGENTS_MD, encoding="utf-8")
-    Path("wiki/index.md").write_text(
-        "# Knowledge Base Index\n\n## Documents\n\n## Concepts\n\n## Entities\n\n## Explorations\n",
-        encoding="utf-8",
-    )
+    Path("wiki/index.md").write_text(INDEX_SEED, encoding="utf-8")
     Path("wiki/log.md").write_text("# Operations Log\n\n", encoding="utf-8")
 
     # Create .openkb/ state directory
@@ -1288,6 +1285,15 @@ def print_list(kb_dir: Path) -> None:
             for c in concepts:
                 click.echo(f"  - {c}")
 
+    # Display entities
+    entities_dir = kb_dir / "wiki" / "entities"
+    if entities_dir.exists():
+        entities = sorted(p.stem for p in entities_dir.glob("*.md"))
+        if entities:
+            click.echo(f"\nEntities ({len(entities)}):")
+            for e in entities:
+                click.echo(f"  - {e}")
+
     # Display reports
     reports_dir = kb_dir / "wiki" / "reports"
     if reports_dir.exists():
@@ -1343,15 +1349,19 @@ def print_status(kb_dir: Path) -> None:
         hashes = json.loads(hashes_file.read_text(encoding="utf-8"))
         click.echo(f"\n  Total indexed: {len(hashes)} document(s)")
 
-    # Last compile time: newest file in wiki/summaries/
-    summaries_dir = wiki_dir / "summaries"
-    if summaries_dir.exists():
-        summaries = list(summaries_dir.glob("*.md"))
-        if summaries:
-            newest_summary = max(summaries, key=lambda p: p.stat().st_mtime)
-            import datetime
-            mtime = datetime.datetime.fromtimestamp(newest_summary.stat().st_mtime)
-            click.echo(f"  Last compile:  {mtime.strftime('%Y-%m-%d %H:%M:%S')}")
+    # Last compile time: newest compiled page across summaries/, concepts/,
+    # and entities/ (an entity-only compile must still bump the shown time).
+    compiled_pages = [
+        p
+        for sub in PAGE_CONTENT_DIRS
+        for p in (wiki_dir / sub).glob("*.md")
+        if (wiki_dir / sub).exists()
+    ]
+    if compiled_pages:
+        newest_page = max(compiled_pages, key=lambda p: p.stat().st_mtime)
+        import datetime
+        mtime = datetime.datetime.fromtimestamp(newest_page.stat().st_mtime)
+        click.echo(f"  Last compile:  {mtime.strftime('%Y-%m-%d %H:%M:%S')}")
 
     # Last lint time: newest file in wiki/reports/
     reports_dir = wiki_dir / "reports"

openkb/lint.py

@@ -15,6 +15,8 @@
 
 import yaml
 
+from openkb.schema import PAGE_CONTENT_DIRS
+
 # Matches [[wikilink]] or [[subdir/link]]
 _WIKILINK_RE = re.compile(r"\[\[([^\]]+)\]\]")
 
@@ -368,7 +370,7 @@ def check_index_sync(wiki: Path) -> list[str]:
 
     Returns issues for:
     - Links in index.md pointing to non-existent pages
-    - Pages in summaries/ or concepts/ not mentioned in index.md
+    - Pages in summaries/, concepts/, or entities/ not mentioned in index.md
 
     Args:
         wiki: Path to the wiki root directory.
@@ -392,11 +394,11 @@ def check_index_sync(wiki: Path) -> list[str]:
         if lnk_norm not in pages:
             issues.append(f"index.md links to missing page: [[{lnk}]]")
 
-    # Check that summaries and concepts pages are mentioned in index
+    # Check that summaries, concepts, and entities pages are mentioned in index
     index_stems = {Path(lnk.strip()).stem for lnk in index_links}
     index_text_lower = index_text.lower()
 
-    for subdir in ("summaries", "concepts"):
+    for subdir in PAGE_CONTENT_DIRS:
         subdir_path = wiki / subdir
         if not subdir_path.exists():
             continue

openkb/schema.py

@@ -2,6 +2,14 @@
 
 from pathlib import Path
 
+# The compiled page-type subdirectories under wiki/. Shared source of truth
+# for surfaces that enumerate page content (list, lint, status, skill gate).
+PAGE_CONTENT_DIRS = ("summaries", "concepts", "entities")
+
+# Canonical empty index.md seed. Used by `openkb init` and the compiler's
+# lazy-create path so they never drift.
+INDEX_SEED = "# Knowledge Base Index\n\n## Documents\n\n## Concepts\n\n## Entities\n\n## Explorations\n"
+
 AGENTS_MD = """\
 # Wiki Schema
 
@@ -26,9 +34,10 @@
 - **Index Page** (index.md): One-liner summary of every page in the wiki. Auto-maintained.
 
 ## Index Page Format
-index.md lists all documents, concepts, and explorations with metadata:
+index.md lists all documents, concepts, entities, and explorations with metadata:
 - Documents: name, one-liner description, type (short|pageindex), detail access path
 - Concepts: name, one-liner description
+- Entities: name, type, one-liner description
 - Explorations: name, one-liner description
 
 ## Log Format

tests/test_lint.py

@@ -185,6 +185,22 @@ def test_page_not_in_index(self, tmp_path):
 
         assert any("unlisted" in issue for issue in result)
 
+    def test_entity_page_not_in_index(self, tmp_path):
+        wiki = _make_wiki(tmp_path)
+        (wiki / "entities").mkdir()
+        (wiki / "entities" / "ada-lovelace.md").write_text("# Ada Lovelace")
+        # index.md has no mention of the entity
+        (wiki / "index.md").write_text(
+            "# Index\n\n## Documents\n\n## Concepts\n\n## Entities\n"
+        )
+
+        result = check_index_sync(wiki)
+
+        assert any(
+            "entities/ada-lovelace.md not mentioned in index.md" in issue
+            for issue in result
+        )
+
     def test_missing_index_md(self, tmp_path):
         wiki = tmp_path / "wiki"
         wiki.mkdir()

tests/test_list_status.py

@@ -88,6 +88,34 @@ def test_list_no_concepts_section_when_empty(self, tmp_path):
         # No concepts in output since none exist
         assert "Concepts:" not in result.output
 
+    def test_list_shows_entities(self, tmp_path):
+        kb_dir = _setup_kb(tmp_path)
+        hashes = {"abc": {"name": "paper.pdf", "type": "pdf"}}
+        (kb_dir / ".openkb" / "hashes.json").write_text(json.dumps(hashes))
+        (kb_dir / "wiki" / "entities" / "ada-lovelace.md").write_text("# Ada")
+        (kb_dir / "wiki" / "entities" / "openai.md").write_text("# OpenAI")
+
+        runner = CliRunner()
+        with patch("openkb.cli._find_kb_dir", return_value=kb_dir):
+            result = runner.invoke(cli, ["list"])
+
+        assert "Entities (2):" in result.output
+        assert "ada-lovelace" in result.output
+        assert "openai" in result.output
+
+    def test_list_no_entities_section_when_empty(self, tmp_path):
+        kb_dir = _setup_kb(tmp_path)
+        hashes = {"abc": {"name": "paper.pdf", "type": "pdf"}}
+        (kb_dir / ".openkb" / "hashes.json").write_text(json.dumps(hashes))
+
+        runner = CliRunner()
+        with patch("openkb.cli._find_kb_dir", return_value=kb_dir):
+            result = runner.invoke(cli, ["list"])
+
+        assert result.exit_code == 0
+        assert "Entities:" not in result.output
+        assert "Entities (" not in result.output
+
 
 class TestStatusCommand:
     def test_status_no_kb(self, tmp_path):

tests/test_skill_chat_slash.py

@@ -87,6 +87,19 @@ async def test_slash_skill_new_rejects_empty_wiki(tmp_path):
     assert not (kb / "output").exists()
 
 
+def test_preflight_gate_counts_entities(tmp_path):
+    """The wiki-content gate must accept a KB whose only compiled content
+    lives in entities/ (no concept or summary pages yet)."""
+    from openkb.cli import _preflight_skill_new
+
+    kb = tmp_path
+    (kb / "wiki" / "entities").mkdir(parents=True)
+    (kb / "wiki" / "entities" / "ada.md").write_text("# Ada\n")
+
+    # No error means the gate passed.
+    assert _preflight_skill_new(kb, "demo") is None
+
+
 @pytest.mark.asyncio
 async def test_slash_skill_new_rejects_when_target_exists(tmp_path):
     """Chat / slash command must not silently overwrite an existing skill."""