feat(cli): rename remove --keep-empty-concepts → --keep-empty (covers entities too)

This PR wired entity pages into 'openkb remove', so the flag now governs
concept AND entity retention — but the name still said 'concepts'. Make
--keep-empty the canonical name (clear that it covers both), keep
--keep-empty-concepts as a backward-compatible alias, and update the
preview/summary messages, docstring, and README accordingly.

Author: KylinMountain

README.md

@@ -154,7 +154,7 @@ OpenKB commands fall into two layers: the **wiki foundation** (compile + manage
 |---|---|
 | `openkb init` | Initialize a new knowledge base (interactive) |
 | <code>openkb&nbsp;add&nbsp;&lt;file_or_dir_or_URL&gt;</code> | Add documents and compile to wiki. URL ingest auto-detects PDF (saved as `.pdf` → PageIndex / markitdown) vs HTML (trafilatura main-content extract → `.md`) |
-| <code>openkb&nbsp;remove&nbsp;&lt;doc&gt;</code> | Remove a document and clean up its wiki pages, images, registry, and PageIndex state (use `--dry-run` to preview, `--keep-raw` / `--keep-empty-concepts` to retain artifacts) |
+| <code>openkb&nbsp;remove&nbsp;&lt;doc&gt;</code> | Remove a document and clean up its wiki pages, images, registry, and PageIndex state (use `--dry-run` to preview, `--keep-raw` / `--keep-empty` to retain artifacts) |
 | <code>openkb&nbsp;recompile&nbsp;[&lt;doc&gt;]&nbsp;[--all]</code> | Re-run the current compile pipeline on already-indexed docs (e.g. to backfill the `entities/` layer) without re-indexing. Regenerates summaries and rewrites concept pages — manual edits are overwritten. Use `--dry-run` to preview, `--refresh-schema` to also update `wiki/AGENTS.md` |
 | `openkb watch` | Watch `raw/` and auto-compile new files |
 | `openkb lint` | Run structural + knowledge health checks |

openkb/cli.py

@@ -804,28 +804,30 @@ def _resolve_doc_identifier(registry, identifier: str) -> list[tuple[str, dict]]
 @click.argument("identifier")
 @click.option("--keep-raw", is_flag=True, default=False,
               help="Don't delete the original file from raw/.")
-@click.option("--keep-empty-concepts", is_flag=True, default=False,
-              help="Keep concept pages whose only source was the removed doc "
-                   "(with empty sources frontmatter). Useful when replacing "
-                   "the doc with a newer version.")
+@click.option("--keep-empty", "--keep-empty-concepts", "keep_empty",
+              is_flag=True, default=False,
+              help="Keep concept AND entity pages whose only source was the "
+                   "removed doc (leaving an empty sources: [] list). Useful "
+                   "when replacing the doc with a newer version. "
+                   "(--keep-empty-concepts is a backward-compatible alias.)")
 @click.option("--dry-run", is_flag=True, default=False,
               help="Print what would be done without modifying anything.")
 @click.option("--yes", "-y", is_flag=True, default=False,
               help="Skip the confirmation prompt.")
 @click.pass_context
-def remove(ctx, identifier, keep_raw, keep_empty_concepts, dry_run, yes):
+def remove(ctx, identifier, keep_raw, keep_empty, dry_run, yes):
     """Remove a document from the knowledge base.
 
     IDENTIFIER may be the original filename ("paper.pdf"), the doc_name
     slug ("paper-a1b2c3d4e5f6"), or a substring that uniquely matches one.
 
     Deletes the doc's summary and source files, prunes the doc from
-    concept-page frontmatter and Related Documents sections, drops the
-    Documents entry from index.md, removes the hash entry, and finally
-    runs `lint --fix` to clean any dangling wikilinks.
+    concept- and entity-page frontmatter and Related Documents sections,
+    drops the Documents entry from index.md, removes the hash entry, and
+    finally runs `lint --fix` to clean any dangling wikilinks.
 
-    Concept pages whose only source was this doc are deleted by default;
-    use --keep-empty-concepts to retain them.
+    Concept and entity pages whose only source was this doc are deleted by
+    default; use --keep-empty to retain them.
     """
     from openkb.agent.compiler import (
         remove_doc_from_concept_pages,
@@ -894,8 +896,8 @@ def remove(ctx, identifier, keep_raw, keep_empty_concepts, dry_run, yes):
     source_file_marker = f"summaries/{doc_name}.md"
     affected_concepts = _scan_affected_pages(wiki_dir / "concepts", source_file_marker)
 
-    concept_deletes = [s for s, r in affected_concepts if r == 0 and not keep_empty_concepts]
-    concept_edits = [s for s, r in affected_concepts if r > 0 or keep_empty_concepts]
+    concept_deletes = [s for s, r in affected_concepts if r == 0 and not keep_empty]
+    concept_edits = [s for s, r in affected_concepts if r > 0 or keep_empty]
     for slug in concept_deletes:
         actions.append(("DELETE", f"wiki/concepts/{slug}.md  (only source: this doc)"))
     for slug in concept_edits:
@@ -906,8 +908,8 @@ def remove(ctx, identifier, keep_raw, keep_empty_concepts, dry_run, yes):
     # preview/summary truthful about what it will delete vs. edit.
     affected_entities = _scan_affected_pages(wiki_dir / "entities", source_file_marker)
 
-    entity_deletes = [s for s, r in affected_entities if r == 0 and not keep_empty_concepts]
-    entity_edits = [s for s, r in affected_entities if r > 0 or keep_empty_concepts]
+    entity_deletes = [s for s, r in affected_entities if r == 0 and not keep_empty]
+    entity_edits = [s for s, r in affected_entities if r > 0 or keep_empty]
     for slug in entity_deletes:
         actions.append(("DELETE", f"wiki/entities/{slug}.md  (only source: this doc)"))
     for slug in entity_edits:
@@ -953,13 +955,13 @@ def remove(ctx, identifier, keep_raw, keep_empty_concepts, dry_run, yes):
         click.echo(
             f"  {len(concept_deletes)} concept(s) will be DELETED because this is their only source."
         )
-        click.echo("  Pass --keep-empty-concepts to retain them instead.")
+        click.echo("  Pass --keep-empty to retain them instead.")
     if entity_deletes:
         click.echo("")
         click.echo(
             f"  {len(entity_deletes)} entity(s) will be DELETED because this is their only source."
         )
-        click.echo("  Pass --keep-empty-concepts to retain them instead.")
+        click.echo("  Pass --keep-empty to retain them instead.")
     click.echo("")
 
     if dry_run:
@@ -988,11 +990,11 @@ def remove(ctx, identifier, keep_raw, keep_empty_concepts, dry_run, yes):
         shutil.rmtree(images_dir, ignore_errors=True)
 
     concept_result = remove_doc_from_concept_pages(
-        wiki_dir, doc_name, keep_empty=keep_empty_concepts,
+        wiki_dir, doc_name, keep_empty=keep_empty,
     )
 
     entity_result = remove_doc_from_entity_pages(
-        wiki_dir, doc_name, keep_empty=keep_empty_concepts,
+        wiki_dir, doc_name, keep_empty=keep_empty,
     )
 
     remove_doc_from_index(wiki_dir, doc_name, concept_result["deleted"],

tests/test_remove.py

@@ -489,6 +489,7 @@ def test_cli_remove_keep_raw_preserves_file(kb_dir):
 
 
 def test_cli_remove_keep_empty_concepts(kb_dir):
+    """The --keep-empty-concepts alias is still accepted (backward compat)."""
     _seed_two_doc_kb(kb_dir)
     result = _invoke(
         kb_dir, ["remove", "attention.pdf", "--keep-empty-concepts", "--yes"],
@@ -501,6 +502,29 @@ def test_cli_remove_keep_empty_concepts(kb_dir):
     assert "sources: []" in transformer.read_text()
 
 
+def test_cli_remove_keep_empty_retains_concepts_and_entities(kb_dir):
+    """The unified --keep-empty flag retains BOTH concept and entity pages
+    whose only source was the removed doc (not just concepts)."""
+    _seed_two_doc_kb(kb_dir)
+    (kb_dir / "wiki" / "entities").mkdir(parents=True)
+    (kb_dir / "wiki" / "entities" / "vaswani.md").write_text(
+        '---\nsources: ["summaries/attention-h_a.md"]\ntype: person\nbrief: V\n---\n# Vaswani\n',
+        encoding="utf-8",
+    )
+
+    result = _invoke(kb_dir, ["remove", "attention.pdf", "--keep-empty", "--yes"])
+
+    assert result.exit_code == 0, result.output
+    # single-source entity retained (not deleted), with emptied sources
+    vaswani = kb_dir / "wiki" / "entities" / "vaswani.md"
+    assert vaswani.exists()
+    assert "sources: []" in vaswani.read_text()
+    # single-source concept retained too
+    transformer = kb_dir / "wiki" / "concepts" / "transformer.md"
+    assert transformer.exists()
+    assert "sources: []" in transformer.read_text()
+
+
 def test_cli_remove_by_doc_name_slug(kb_dir):
     _seed_two_doc_kb(kb_dir)
     result = _invoke(kb_dir, ["remove", "attention-h_a", "--yes"])