keep-skill 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

keep/cli.py

@@ -16,24 +16,140 @@ from typing import Optional
 import typer
 from typing_extensions import Annotated
 
-from .api import Keeper
+from .api import Keeper, _text_content_id
+from .document_store import VersionInfo
 from .types import Item
-from .logging_config import configure_quiet_mode
+from .logging_config import configure_quiet_mode, enable_debug_mode
 
 
 # Configure quiet mode by default (suppress verbose library output)
-# Set KEEP_VERBOSE=1 to enable verbose mode for debugging
-_verbose = sys.argv and "--verbose" in sys.argv or os.environ.get("KEEP_VERBOSE") == "1"
-configure_quiet_mode(quiet=not _verbose)
+# Set KEEP_VERBOSE=1 to enable debug mode via environment
+if os.environ.get("KEEP_VERBOSE") == "1":
+    enable_debug_mode()
+else:
+    configure_quiet_mode(quiet=True)
+
+
+def _verbose_callback(value: bool):
+    if value:
+        enable_debug_mode()
+
+
+# Global state for CLI options
+_json_output = False
+_ids_output = False
+
+
+def _json_callback(value: bool):
+    global _json_output
+    _json_output = value
+
+
+def _get_json_output() -> bool:
+    return _json_output
+
+
+def _ids_callback(value: bool):
+    global _ids_output
+    _ids_output = value
+
+
+def _get_ids_output() -> bool:
+    return _ids_output
 
 
 app = typer.Typer(
     name="keep",
     help="Associative memory with semantic search.",
-    no_args_is_help=True,
+    no_args_is_help=False,
+    invoke_without_command=True,
 )
 
 
+def _format_yaml_frontmatter(
+    item: Item,
+    version_nav: Optional[dict[str, list[VersionInfo]]] = None,
+    viewing_version: Optional[int] = None,
+) -> str:
+    """
+    Format item as YAML frontmatter with summary as content.
+
+    Args:
+        item: The item to format
+        version_nav: Optional version navigation info (prev/next lists)
+        viewing_version: If viewing an old version, the version number
+    """
+    lines = ["---", f"id: {item.id}"]
+    if viewing_version is not None:
+        lines.append(f"version: {viewing_version}")
+    if item.tags:
+        lines.append("tags:")
+        for k, v in sorted(item.tags.items()):
+            lines.append(f"  {k}: {v}")
+    if item.score is not None:
+        lines.append(f"score: {item.score:.3f}")
+
+    # Add version navigation if available
+    if version_nav:
+        if version_nav.get("prev"):
+            lines.append("prev:")
+            for v in version_nav["prev"]:
+                # Show version number, date portion, and truncated summary
+                date_part = v.created_at[:10] if v.created_at else "unknown"
+                summary_preview = v.summary[:40].replace("\n", " ")
+                if len(v.summary) > 40:
+                    summary_preview += "..."
+                lines.append(f"  - {v.version}: {date_part} {summary_preview}")
+        if version_nav.get("next"):
+            lines.append("next:")
+            for v in version_nav["next"]:
+                date_part = v.created_at[:10] if v.created_at else "unknown"
+                summary_preview = v.summary[:40].replace("\n", " ")
+                if len(v.summary) > 40:
+                    summary_preview += "..."
+                lines.append(f"  - {v.version}: {date_part} {summary_preview}")
+        elif viewing_version is not None:
+            # Viewing old version and next is empty means current is next
+            lines.append("next:")
+            lines.append("  - current")
+
+    lines.append("---")
+    lines.append(item.summary)  # Summary IS the content
+    return "\n".join(lines)
+
+
+@app.callback(invoke_without_command=True)
+def main_callback(
+    ctx: typer.Context,
+    verbose: Annotated[bool, typer.Option(
+        "--verbose", "-v",
+        help="Enable debug-level logging to stderr",
+        callback=_verbose_callback,
+        is_eager=True,
+    )] = False,
+    output_json: Annotated[bool, typer.Option(
+        "--json", "-j",
+        help="Output as JSON",
+        callback=_json_callback,
+        is_eager=True,
+    )] = False,
+    ids_only: Annotated[bool, typer.Option(
+        "--ids", "-I",
+        help="Output only IDs (for piping to xargs)",
+        callback=_ids_callback,
+        is_eager=True,
+    )] = False,
+):
+    """Associative memory with semantic search."""
+    # If no subcommand provided, show the current context (now)
+    if ctx.invoked_subcommand is None:
+        kp = _get_keeper(None, "default")
+        item = kp.get_now()
+        typer.echo(_format_item(item, as_json=_get_json_output()))
+        if not _get_json_output():
+            typer.echo("\nUse --help for commands.", err=True)
+
+
 # -----------------------------------------------------------------------------
 # Common Options
 # -----------------------------------------------------------------------------
@@ -63,11 +179,12 @@ LimitOption = Annotated[
     )
 ]
 
-JsonOption = Annotated[
-    bool,
+
+SinceOption = Annotated[
+    Optional[str],
     typer.Option(
-        "--json", "-j",
-        help="Output as JSON"
+        "--since",
+        help="Only items updated since (ISO duration: P3D, P1W, PT1H; or date: 2026-01-15)"
     )
 ]
 
@@ -76,20 +193,47 @@ JsonOption = Annotated[
 # Output Helpers
 # -----------------------------------------------------------------------------
 
-def _format_item(item: Item, as_json: bool = False) -> str:
+def _format_item(
+    item: Item,
+    as_json: bool = False,
+    version_nav: Optional[dict[str, list[VersionInfo]]] = None,
+    viewing_version: Optional[int] = None,
+) -> str:
+    """
+    Format an item for display.
+
+    Text format: YAML frontmatter (matches docs/system format)
+    With --ids: just the ID (for piping)
+    """
+    if _get_ids_output():
+        return json.dumps(item.id) if as_json else item.id
+
     if as_json:
-        return json.dumps({
+        result = {
             "id": item.id,
             "summary": item.summary,
             "tags": item.tags,
             "score": item.score,
-        })
-    else:
-        score = f"[{item.score:.3f}] " if item.score is not None else ""
-        return f"{score}{item.id}\n  {item.summary}"
+        }
+        if viewing_version is not None:
+            result["version"] = viewing_version
+        if version_nav:
+            result["version_nav"] = {
+                k: [{"version": v.version, "created_at": v.created_at, "summary": v.summary[:60]}
+                    for v in versions]
+                for k, versions in version_nav.items()
+            }
+        return json.dumps(result)
+
+    return _format_yaml_frontmatter(item, version_nav, viewing_version)
 
 
 def _format_items(items: list[Item], as_json: bool = False) -> str:
+    """Format multiple items for display."""
+    if _get_ids_output():
+        ids = [item.id for item in items]
+        return json.dumps(ids) if as_json else "\n".join(ids)
+
     if as_json:
         return json.dumps([
             {
@@ -116,172 +260,548 @@ def _get_keeper(store: Optional[Path], collection: str) -> Keeper:
         raise typer.Exit(1)
 
 
+def _parse_tags(tags: Optional[list[str]]) -> dict[str, str]:
+    """Parse key=value tag list to dict."""
+    if not tags:
+        return {}
+    parsed = {}
+    for tag in tags:
+        if "=" not in tag:
+            typer.echo(f"Error: Invalid tag format '{tag}'. Use key=value", err=True)
+            raise typer.Exit(1)
+        k, v = tag.split("=", 1)
+        parsed[k] = v
+    return parsed
+
+
+def _timestamp() -> str:
+    """Generate timestamp for auto-generated IDs."""
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")
+
+
+def _parse_frontmatter(text: str) -> tuple[str, dict[str, str]]:
+    """Parse YAML frontmatter from text, return (content, tags)."""
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) >= 3:
+            import yaml
+            frontmatter = yaml.safe_load(parts[1])
+            content = parts[2].lstrip("\n")
+            tags = frontmatter.get("tags", {}) if frontmatter else {}
+            return content, {k: str(v) for k, v in tags.items()}
+    return text, {}
+
+
 # -----------------------------------------------------------------------------
 # Commands
 # -----------------------------------------------------------------------------
 
 @app.command()
 def find(
-    query: Annotated[str, typer.Argument(help="Search query text")],
+    query: Annotated[Optional[str], typer.Argument(help="Search query text")] = None,
+    id: Annotated[Optional[str], typer.Option(
+        "--id",
+        help="Find items similar to this ID (instead of text search)"
+    )] = None,
+    include_self: Annotated[bool, typer.Option(
+        help="Include the queried item (only with --id)"
+    )] = False,
     store: StoreOption = None,
     collection: CollectionOption = "default",
     limit: LimitOption = 10,
-    output_json: JsonOption = False,
+    since: SinceOption = None,
 ):
     """
     Find items using semantic similarity search.
+
+    Examples:
+        keep find "authentication"              # Search by text
+        keep find --id file:///path/to/doc.md   # Find similar to item
     """
+    if id and query:
+        typer.echo("Error: Specify either a query or --id, not both", err=True)
+        raise typer.Exit(1)
+    if not id and not query:
+        typer.echo("Error: Specify a query or --id", err=True)
+        raise typer.Exit(1)
+
     kp = _get_keeper(store, collection)
-    results = kp.find(query, limit=limit)
-    typer.echo(_format_items(results, as_json=output_json))
+
+    if id:
+        results = kp.find_similar(id, limit=limit, since=since, include_self=include_self)
+    else:
+        results = kp.find(query, limit=limit, since=since)
+
+    typer.echo(_format_items(results, as_json=_get_json_output()))
 
 
 @app.command()
-def similar(
-    id: Annotated[str, typer.Argument(help="URI of item to find similar items for")],
+def search(
+    query: Annotated[str, typer.Argument(help="Full-text search query")],
     store: StoreOption = None,
     collection: CollectionOption = "default",
     limit: LimitOption = 10,
-    include_self: Annotated[bool, typer.Option(help="Include the queried item")] = False,
-    output_json: JsonOption = False,
+    since: SinceOption = None,
 ):
     """
-    Find items similar to an existing item.
+    Search item summaries using full-text search.
     """
     kp = _get_keeper(store, collection)
-    results = kp.find_similar(id, limit=limit, include_self=include_self)
-    typer.echo(_format_items(results, as_json=output_json))
+    results = kp.query_fulltext(query, limit=limit, since=since)
+    typer.echo(_format_items(results, as_json=_get_json_output()))
 
 
-@app.command()
-def search(
-    query: Annotated[str, typer.Argument(help="Full-text search query")],
+@app.command("list")
+def list_recent(
     store: StoreOption = None,
     collection: CollectionOption = "default",
-    limit: LimitOption = 10,
-    output_json: JsonOption = False,
+    limit: Annotated[int, typer.Option(
+        "--limit", "-n",
+        help="Number of items to show"
+    )] = 10,
 ):
     """
-    Search item summaries using full-text search.
+    List recent items by update time.
+
+    Shows the most recently updated items, newest first.
     """
     kp = _get_keeper(store, collection)
-    results = kp.query_fulltext(query, limit=limit)
-    typer.echo(_format_items(results, as_json=output_json))
+    results = kp.list_recent(limit=limit)
+    typer.echo(_format_items(results, as_json=_get_json_output()))
 
 
 @app.command()
 def tag(
-    key: Annotated[str, typer.Argument(help="Tag key to search for")],
-    value: Annotated[Optional[str], typer.Argument(help="Tag value (optional)")] = None,
+    query: Annotated[Optional[str], typer.Argument(
+        help="Tag key to list values, or key=value to find docs"
+    )] = None,
+    list_keys: Annotated[bool, typer.Option(
+        "--list", "-l",
+        help="List all distinct tag keys"
+    )] = False,
     store: StoreOption = None,
     collection: CollectionOption = "default",
     limit: LimitOption = 100,
-    output_json: JsonOption = False,
+    since: SinceOption = None,
 ):
     """
-    Find items by tag.
+    List tag values or find items by tag.
+
+    Examples:
+        keep tag --list              # List all tag keys
+        keep tag project             # List values for 'project' tag
+        keep tag project=myapp       # Find docs with project=myapp
     """
     kp = _get_keeper(store, collection)
-    results = kp.query_tag(key, value, limit=limit)
-    typer.echo(_format_items(results, as_json=output_json))
 
+    # List all keys mode
+    if list_keys or query is None:
+        tags = kp.list_tags(None, collection=collection)
+        if _get_json_output():
+            typer.echo(json.dumps(tags))
+        else:
+            if not tags:
+                typer.echo("No tags found.")
+            else:
+                for t in tags:
+                    typer.echo(t)
+        return
 
-@app.command()
-def update(
-    id: Annotated[str, typer.Argument(help="URI of document to index")],
-    store: StoreOption = None,
-    collection: CollectionOption = "default",
+    # Check if query is key=value or just key
+    if "=" in query:
+        # key=value → find documents
+        key, value = query.split("=", 1)
+        results = kp.query_tag(key, value, limit=limit, since=since)
+        typer.echo(_format_items(results, as_json=_get_json_output()))
+    else:
+        # key only → list values
+        values = kp.list_tags(query, collection=collection)
+        if _get_json_output():
+            typer.echo(json.dumps(values))
+        else:
+            if not values:
+                typer.echo(f"No values for tag '{query}'.")
+            else:
+                for v in values:
+                    typer.echo(v)
+
+
+@app.command("tag-update")
+def tag_update(
+    ids: Annotated[list[str], typer.Argument(help="Document IDs to tag")],
     tags: Annotated[Optional[list[str]], typer.Option(
         "--tag", "-t",
-        help="Source tag as key=value (can be repeated)"
+        help="Tag as key=value (empty value removes: key=)"
     )] = None,
-    lazy: Annotated[bool, typer.Option(
-        "--lazy", "-l",
-        help="Fast mode: use truncated summary, queue for later processing"
-    )] = False,
-    output_json: JsonOption = False,
+    remove: Annotated[Optional[list[str]], typer.Option(
+        "--remove", "-r",
+        help="Tag keys to remove"
+    )] = None,
+    store: StoreOption = None,
+    collection: CollectionOption = "default",
 ):
     """
-    Add or update a document in the store.
+    Add, update, or remove tags on existing documents.
 
-    Use --lazy for fast indexing when summarization is slow.
-    Run 'keep process-pending' later to generate real summaries.
+    Does not re-process the document - only updates tags.
+
+    Examples:
+        keep tag-update doc:1 --tag project=myapp
+        keep tag-update doc:1 doc:2 --tag status=reviewed
+        keep tag-update doc:1 --remove obsolete_tag
+        keep tag-update doc:1 --tag temp=  # Remove via empty value
     """
     kp = _get_keeper(store, collection)
 
     # Parse tags from key=value format
-    source_tags = {}
+    tag_changes: dict[str, str] = {}
     if tags:
         for tag in tags:
             if "=" not in tag:
-                typer.echo(f"Error: Invalid tag format '{tag}'. Use key=value", err=True)
+                typer.echo(f"Error: Invalid tag format '{tag}'. Use key=value (or key= to remove)", err=True)
                 raise typer.Exit(1)
             k, v = tag.split("=", 1)
-            source_tags[k] = v
+            tag_changes[k] = v  # Empty v means delete
+
+    # Add explicit removals as empty strings
+    if remove:
+        for key in remove:
+            tag_changes[key] = ""
+
+    if not tag_changes:
+        typer.echo("Error: Specify at least one --tag or --remove", err=True)
+        raise typer.Exit(1)
 
-    item = kp.update(id, source_tags=source_tags or None, lazy=lazy)
-    typer.echo(_format_item(item, as_json=output_json))
+    # Process each document
+    results = []
+    for doc_id in ids:
+        item = kp.tag(doc_id, tags=tag_changes, collection=collection)
+        if item is None:
+            typer.echo(f"Not found: {doc_id}", err=True)
+        else:
+            results.append(item)
+
+    if _get_json_output():
+        typer.echo(_format_items(results, as_json=True))
+    else:
+        for item in results:
+            typer.echo(_format_item(item, as_json=False))
 
 
 @app.command()
-def remember(
-    content: Annotated[str, typer.Argument(help="Content to remember")],
-    store: StoreOption = None,
-    collection: CollectionOption = "default",
+def update(
+    source: Annotated[Optional[str], typer.Argument(
+        help="URI to fetch, text content, or '-' for stdin"
+    )] = None,
     id: Annotated[Optional[str], typer.Option(
         "--id", "-i",
-        help="Custom identifier (default: auto-generated)"
+        help="Document ID (auto-generated for text/stdin modes)"
     )] = None,
+    store: StoreOption = None,
+    collection: CollectionOption = "default",
     tags: Annotated[Optional[list[str]], typer.Option(
         "--tag", "-t",
-        help="Source tag as key=value (can be repeated)"
+        help="Tag as key=value (can be repeated)"
+    )] = None,
+    summary: Annotated[Optional[str], typer.Option(
+        "--summary",
+        help="User-provided summary (skips auto-summarization)"
     )] = None,
     lazy: Annotated[bool, typer.Option(
-        "--lazy", "-l",
+        "--lazy",
         help="Fast mode: use truncated summary, queue for later processing"
     )] = False,
-    output_json: JsonOption = False,
 ):
     """
-    Remember inline content (conversations, notes, insights).
+    Add or update a document in the store.
+
+    Three input modes (auto-detected):
+      keep update file:///path       # URI mode: has ://
+      keep update "my note"          # Text mode: content-addressed ID
+      keep update -                  # Stdin mode: explicit -
+      echo "pipe" | keep update      # Stdin mode: piped input
 
-    Use --lazy for fast indexing when summarization is slow.
-    Run 'keep process-pending' later to generate real summaries.
+    Text mode uses content-addressed IDs for versioning:
+      keep update "my note"           # Creates _text:{hash}
+      keep update "my note" -t done   # Same ID, new version (tag change)
+      keep update "different note"    # Different ID (new doc)
     """
     kp = _get_keeper(store, collection)
+    parsed_tags = _parse_tags(tags)
+
+    # Determine mode based on source content
+    if source == "-" or (source is None and not sys.stdin.isatty()):
+        # Stdin mode: explicit '-' or piped input
+        content = sys.stdin.read()
+        content, frontmatter_tags = _parse_frontmatter(content)
+        parsed_tags = {**frontmatter_tags, **parsed_tags}  # CLI tags override
+        # Use content-addressed ID for stdin text (enables versioning)
+        doc_id = id or _text_content_id(content)
+        item = kp.remember(content, id=doc_id, summary=summary, tags=parsed_tags or None, lazy=lazy)
+    elif source and "://" in source:
+        # URI mode: fetch from URI (ID is the URI itself)
+        item = kp.update(source, tags=parsed_tags or None, summary=summary, lazy=lazy)
+    elif source:
+        # Text mode: inline content (no :// in source)
+        # Use content-addressed ID for text (enables versioning)
+        doc_id = id or _text_content_id(source)
+        item = kp.remember(source, id=doc_id, summary=summary, tags=parsed_tags or None, lazy=lazy)
+    else:
+        typer.echo("Error: Provide content, URI, or '-' for stdin", err=True)
+        raise typer.Exit(1)
 
-    # Parse tags from key=value format
-    source_tags = {}
-    if tags:
-        for tag in tags:
-            if "=" not in tag:
-                typer.echo(f"Error: Invalid tag format '{tag}'. Use key=value", err=True)
-                raise typer.Exit(1)
-            k, v = tag.split("=", 1)
-            source_tags[k] = v
+    typer.echo(_format_item(item, as_json=_get_json_output()))
+
+
+@app.command()
+def now(
+    content: Annotated[Optional[str], typer.Argument(
+        help="Content to set (omit to show current)"
+    )] = None,
+    file: Annotated[Optional[Path], typer.Option(
+        "--file", "-f",
+        help="Read content from file"
+    )] = None,
+    reset: Annotated[bool, typer.Option(
+        "--reset",
+        help="Reset to default from system"
+    )] = False,
+    version: Annotated[Optional[int], typer.Option(
+        "--version", "-V",
+        help="Get specific version (0=current, 1=previous, etc.)"
+    )] = None,
+    history: Annotated[bool, typer.Option(
+        "--history", "-H",
+        help="List all versions"
+    )] = False,
+    store: StoreOption = None,
+    collection: CollectionOption = "default",
+    tags: Annotated[Optional[list[str]], typer.Option(
+        "--tag", "-t",
+        help="Tag as key=value (can be repeated)"
+    )] = None,
+):
+    """
+    Get or set the current working context.
+
+    With no arguments, displays the current context.
+    With content, replaces it.
+
+    Examples:
+        keep now                         # Show current context
+        keep now "What's important now"  # Update context
+        keep now -f context.md           # Read content from file
+        keep now --reset                 # Reset to default from system
+        keep now -V 1                    # Previous version
+        keep now --history               # List all versions
+    """
+    from .api import NOWDOC_ID
 
-    item = kp.remember(content, id=id, source_tags=source_tags or None, lazy=lazy)
-    typer.echo(_format_item(item, as_json=output_json))
+    kp = _get_keeper(store, collection)
+
+    # Handle history listing
+    if history:
+        versions = kp.list_versions(NOWDOC_ID, limit=50, collection=collection)
+        current = kp.get(NOWDOC_ID, collection=collection)
+
+        if _get_json_output():
+            result = {
+                "id": NOWDOC_ID,
+                "current": {
+                    "summary": current.summary if current else None,
+                } if current else None,
+                "versions": [
+                    {
+                        "version": v.version,
+                        "summary": v.summary[:60],
+                        "created_at": v.created_at,
+                    }
+                    for v in versions
+                ],
+            }
+            typer.echo(json.dumps(result, indent=2))
+        else:
+            if current:
+                summary_preview = current.summary[:60].replace("\n", " ")
+                typer.echo(f"Current: {summary_preview}...")
+            if versions:
+                typer.echo(f"\nVersion history ({len(versions)} archived):")
+                for v in versions:
+                    date_part = v.created_at[:10] if v.created_at else "unknown"
+                    summary_preview = v.summary[:50].replace("\n", " ")
+                    if len(v.summary) > 50:
+                        summary_preview += "..."
+                    typer.echo(f"  v{v.version} ({date_part}): {summary_preview}")
+            else:
+                typer.echo("No version history.")
+        return
+
+    # Handle version retrieval
+    if version is not None:
+        offset = version
+        if offset == 0:
+            item = kp.get_now()
+            viewing_version = None
+        else:
+            item = kp.get_version(NOWDOC_ID, offset, collection=collection)
+            versions = kp.list_versions(NOWDOC_ID, limit=1, collection=collection)
+            if versions:
+                viewing_version = versions[0].version - (offset - 1)
+            else:
+                viewing_version = None
+
+        if item is None:
+            typer.echo(f"Version not found (offset {offset})", err=True)
+            raise typer.Exit(1)
+
+        version_nav = kp.get_version_nav(NOWDOC_ID, viewing_version, collection=collection)
+        typer.echo(_format_item(
+            item,
+            as_json=_get_json_output(),
+            version_nav=version_nav,
+            viewing_version=viewing_version,
+        ))
+        return
+
+    # Determine if we're getting or setting
+    setting = content is not None or file is not None or reset
+
+    if setting:
+        if reset:
+            # Reset to default from system (delete first to clear old tags)
+            from .api import _load_frontmatter, SYSTEM_DOC_DIR
+            kp.delete(NOWDOC_ID)
+            try:
+                new_content, default_tags = _load_frontmatter(SYSTEM_DOC_DIR / "now.md")
+                parsed_tags = default_tags
+            except FileNotFoundError:
+                typer.echo("Error: Builtin now.md not found", err=True)
+                raise typer.Exit(1)
+        elif file is not None:
+            if not file.exists():
+                typer.echo(f"Error: File not found: {file}", err=True)
+                raise typer.Exit(1)
+            new_content = file.read_text()
+            parsed_tags = {}
+        else:
+            new_content = content
+            parsed_tags = {}
+
+        # Parse user-provided tags (merge with default if reset)
+        if tags:
+            for tag in tags:
+                if "=" not in tag:
+                    typer.echo(f"Error: Invalid tag format '{tag}'. Use key=value", err=True)
+                    raise typer.Exit(1)
+                k, v = tag.split("=", 1)
+                parsed_tags[k] = v
+
+        item = kp.set_now(new_content, tags=parsed_tags or None)
+        typer.echo(_format_item(item, as_json=_get_json_output()))
+    else:
+        # Get current context with version navigation
+        item = kp.get_now()
+        version_nav = kp.get_version_nav(NOWDOC_ID, None, collection=collection)
+        typer.echo(_format_item(
+            item,
+            as_json=_get_json_output(),
+            version_nav=version_nav,
+        ))
 
 
 @app.command()
 def get(
     id: Annotated[str, typer.Argument(help="URI of item to retrieve")],
+    version: Annotated[Optional[int], typer.Option(
+        "--version", "-V",
+        help="Get specific version (0=current, 1=previous, etc.)"
+    )] = None,
+    history: Annotated[bool, typer.Option(
+        "--history", "-H",
+        help="List all versions"
+    )] = False,
     store: StoreOption = None,
     collection: CollectionOption = "default",
-    output_json: JsonOption = False,
 ):
     """
     Retrieve a specific item by ID.
+
+    Examples:
+        keep get doc:1                  # Current version with prev nav
+        keep get doc:1 -V 1             # Previous version with prev/next nav
+        keep get doc:1 --history        # List all versions
     """
     kp = _get_keeper(store, collection)
-    item = kp.get(id)
-    
+
+    if history:
+        # List all versions
+        versions = kp.list_versions(id, limit=50, collection=collection)
+        current = kp.get(id, collection=collection)
+
+        if _get_json_output():
+            result = {
+                "id": id,
+                "current": {
+                    "summary": current.summary if current else None,
+                    "tags": current.tags if current else {},
+                } if current else None,
+                "versions": [
+                    {
+                        "version": v.version,
+                        "summary": v.summary,
+                        "created_at": v.created_at,
+                    }
+                    for v in versions
+                ],
+            }
+            typer.echo(json.dumps(result, indent=2))
+        else:
+            if current:
+                typer.echo(f"Current: {current.summary[:60]}...")
+            if versions:
+                typer.echo(f"\nVersion history ({len(versions)} archived):")
+                for v in versions:
+                    date_part = v.created_at[:10] if v.created_at else "unknown"
+                    summary_preview = v.summary[:50].replace("\n", " ")
+                    if len(v.summary) > 50:
+                        summary_preview += "..."
+                    typer.echo(f"  v{v.version} ({date_part}): {summary_preview}")
+            else:
+                typer.echo("No version history.")
+        return
+
+    # Get specific version or current
+    offset = version if version is not None else 0
+
+    if offset == 0:
+        item = kp.get(id, collection=collection)
+        viewing_version = None
+    else:
+        item = kp.get_version(id, offset, collection=collection)
+        # Calculate actual version number for display
+        versions = kp.list_versions(id, limit=1, collection=collection)
+        if versions:
+            viewing_version = versions[0].version - (offset - 1)
+        else:
+            viewing_version = None
+
     if item is None:
-        typer.echo(f"Not found: {id}", err=True)
+        if offset > 0:
+            typer.echo(f"Version not found: {id} (offset {offset})", err=True)
+        else:
+            typer.echo(f"Not found: {id}", err=True)
         raise typer.Exit(1)
-    
-    typer.echo(_format_item(item, as_json=output_json))
+
+    # Get version navigation
+    version_nav = kp.get_version_nav(id, viewing_version, collection=collection)
+
+    typer.echo(_format_item(
+        item,
+        as_json=_get_json_output(),
+        version_nav=version_nav,
+        viewing_version=viewing_version,
+    ))
 
 
 @app.command()
@@ -306,15 +826,14 @@ def exists(
 @app.command("collections")
 def list_collections(
     store: StoreOption = None,
-    output_json: JsonOption = False,
 ):
     """
     List all collections in the store.
     """
     kp = _get_keeper(store, "default")
     collections = kp.list_collections()
-    
-    if output_json:
+
+    if _get_json_output():
         typer.echo(json.dumps(collections))
     else:
         if not collections:
@@ -333,58 +852,101 @@ def init(
     Initialize or verify the store is ready.
     """
     kp = _get_keeper(store, collection)
-    
-    # Show actual store path
-    actual_path = kp._store_path if hasattr(kp, '_store_path') else Path(store or ".keep")
-    typer.echo(f"✓ Store ready: {actual_path}")
-    typer.echo(f"✓ Collections: {kp.list_collections()}")
-    
+
+    # Show config and store paths
+    config = kp._config
+    config_path = config.config_path if config else None
+    store_path = kp._store_path
+
+    # Show paths
+    typer.echo(f"Config: {config_path}")
+    if config and config.config_dir and config.config_dir.resolve() != store_path.resolve():
+        typer.echo(f"Store:  {store_path}")
+
+    typer.echo(f"Collections: {kp.list_collections()}")
+
     # Show detected providers
-    try:
-        if hasattr(kp, '_config'):
-            config = kp._config
-            typer.echo(f"\n✓ Detected providers:")
-            typer.echo(f"  Embedding: {config.embedding.name}")
-            typer.echo(f"  Summarization: {config.summarization.name}")
-            typer.echo(f"\nTo customize, edit {actual_path}/keep.toml")
-    except Exception:
-        pass  # Don't fail if provider detection doesn't work
-    
-    # .gitignore reminder
-    typer.echo(f"\n⚠️  Remember to add .keep/ to .gitignore")
+    if config:
+        typer.echo(f"\nProviders:")
+        typer.echo(f"  Embedding: {config.embedding.name}")
+        typer.echo(f"  Summarization: {config.summarization.name}")
 
 
-@app.command("system")
-def list_system(
+
+@app.command()
+def config(
     store: StoreOption = None,
-    output_json: JsonOption = False,
 ):
     """
-    List all system documents (schema as data).
+    Show current configuration and store location.
     """
     kp = _get_keeper(store, "default")
-    docs = kp.list_system_documents()
-    typer.echo(_format_items(docs, as_json=output_json))
+
+    cfg = kp._config
+    config_path = cfg.config_path if cfg else None
+    store_path = kp._store_path
+
+    if _get_json_output():
+        result = {
+            "store": str(store_path),
+            "config": str(config_path) if config_path else None,
+            "collections": kp.list_collections(),
+        }
+        if cfg:
+            result["embedding"] = cfg.embedding.name
+            result["summarization"] = cfg.summarization.name
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        # Show paths
+        typer.echo(f"Config: {config_path}")
+        if cfg and cfg.config_dir and cfg.config_dir.resolve() != store_path.resolve():
+            typer.echo(f"Store:  {store_path}")
+
+        typer.echo(f"Collections: {kp.list_collections()}")
+
+        if cfg:
+            typer.echo(f"\nProviders:")
+            typer.echo(f"  Embedding: {cfg.embedding.name}")
+            typer.echo(f"  Summarization: {cfg.summarization.name}")
 
 
-@app.command("routing")
-def show_routing(
+@app.command("system")
+def list_system(
     store: StoreOption = None,
-    output_json: JsonOption = False,
 ):
     """
-    Show the current routing configuration.
+    List the system documents.
+
+    Shows ID and summary for each. Use `keep get ID` for full details.
     """
     kp = _get_keeper(store, "default")
-    routing = kp.get_routing()
+    docs = kp.list_system_documents()
 
-    if output_json:
-        from dataclasses import asdict
-        typer.echo(json.dumps(asdict(routing), indent=2))
+    # Use --ids flag for pipe-friendly output
+    if _get_ids_output():
+        ids = [doc.id for doc in docs]
+        if _get_json_output():
+            typer.echo(json.dumps(ids))
+        else:
+            for doc_id in ids:
+                typer.echo(doc_id)
+        return
+
+    if _get_json_output():
+        typer.echo(json.dumps([
+            {"id": doc.id, "summary": doc.summary}
+            for doc in docs
+        ], indent=2))
     else:
-        typer.echo(f"Summary: {routing.summary}")
-        typer.echo(f"Private patterns: {routing.private_patterns}")
-        typer.echo(f"Updated: {routing.updated}")
+        if not docs:
+            typer.echo("No system documents.")
+        else:
+            for doc in docs:
+                # Compact summary: collapse whitespace, truncate to 70 chars
+                summary = " ".join(doc.summary.split())[:70]
+                if len(doc.summary) > 70:
+                    summary += "..."
+                typer.echo(f"{doc.id}: {summary}")
 
 
 @app.command("process-pending")
@@ -403,7 +965,6 @@ def process_pending(
         hidden=True,
         help="Run as background daemon (used internally)"
     )] = False,
-    output_json: JsonOption = False,
 ):
     """
     Process pending summaries from lazy indexing.
@@ -452,7 +1013,7 @@ def process_pending(
     pending_before = kp.pending_count()
 
     if pending_before == 0:
-        if output_json:
+        if _get_json_output():
             typer.echo(json.dumps({"processed": 0, "remaining": 0}))
         else:
             typer.echo("No pending summaries.")
@@ -466,11 +1027,11 @@ def process_pending(
             total_processed += processed
             if processed == 0:
                 break
-            if not output_json:
+            if not _get_json_output():
                 typer.echo(f"  Processed {total_processed}...")
 
         remaining = kp.pending_count()
-        if output_json:
+        if _get_json_output():
             typer.echo(json.dumps({
                 "processed": total_processed,
                 "remaining": remaining
@@ -482,7 +1043,7 @@ def process_pending(
         processed = kp.process_pending(limit=limit)
         remaining = kp.pending_count()
 
-        if output_json:
+        if _get_json_output():
             typer.echo(json.dumps({
                 "processed": processed,
                 "remaining": remaining
@@ -496,7 +1057,19 @@ def process_pending(
 # -----------------------------------------------------------------------------
 
 def main():
-    app()
+    try:
+        app()
+    except SystemExit:
+        raise  # Let typer handle exit codes
+    except KeyboardInterrupt:
+        raise SystemExit(130)  # Standard exit code for Ctrl+C
+    except Exception as e:
+        # Log full traceback to file, show clean message to user
+        from .errors import log_exception, ERROR_LOG_PATH
+        log_exception(e, context="keep CLI")
+        typer.echo(f"Error: {e}", err=True)
+        typer.echo(f"Details logged to {ERROR_LOG_PATH}", err=True)
+        raise SystemExit(1)
 
 
 if __name__ == "__main__":