deepvista-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepvista-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: CLI for DeepVista — chat, notes, skills, and memory from your terminal.
 Project-URL: Homepage, https://deepvista.ai
 Project-URL: Repository, https://github.com/DeepVista-AI/deepvista-cli
@@ -31,10 +31,12 @@ Description-Content-Type: text/markdown
   <img src="https://raw.githubusercontent.com/DeepVista-AI/deepvista-cli/main/docs/assets/deepvista-banner.png" alt="DeepVista" width="600">
 </p>
 
-<h1 align="center">Your Second Brain, from the Terminal</h1>
+<h1 align="center">Turn Your Agents into a Self-Evolving Team</h1>
 
 <p align="center">
-  <strong>CLI for DeepVista — chat, notes, skills, and knowledge base from your terminal.<br>Designed for both humans and AI agents.</strong>
+  <strong>DeepVista CLI connects your coding agents to a shared knowledge base —<br>
+    so they don’t just execute, but learn, remember, and build on past work.
+  </strong>
 </p>
 
 <div align="center">
@@ -52,7 +54,7 @@ Description-Content-Type: text/markdown
 <br>
 
 <p align="center">
-  ⭐ If this is useful, drop a star — it helps us grow!
+⭐ If this direction resonates, consider <b>starring the repo</b> — it helps more people discover it.
 </p>
 
 <br>
@@ -62,6 +64,27 @@ Description-Content-Type: text/markdown
 
 ---
 
+## Who this is for
+
+- Builders working with coding agents (Claude Code, Cursor, OpenCode)
+- People experimenting with agent workflows and skills
+- Anyone trying to turn scattered interactions into compounding knowledge
+
+## What this enables
+
+Modern coding agents are powerful — but each interaction is stateless and isolated.
+
+DeepVista changes that.
+
+- Agents **remember** past work
+- Agents **share context** through a common knowledge base
+- Agents **build on previous decisions and insights**
+
+Over time, this turns isolated executions into a:
+
+→ **a self-evolving team of agents that compound knowledge over time**
+
+
 ## Why DeepVista CLI?
 
 Most knowledge tools trap your data in a GUI. DeepVista CLI gives you **full access to your knowledge base from the terminal** — and lets your AI agents use it too.
@@ -73,6 +96,17 @@ Most knowledge tools trap your data in a GUI. DeepVista CLI gives you **full acc
 - 💬 **Chat** — talk to the DeepVista AI agent in your terminal
 - 🖥️ **Full TUI** — four-panel terminal UI for chat, notes, skills, and memory
 
+## Related Ideas
+
+This repo is part of a broader exploration of how agent skills are structured and executed.
+
+If you're interested in:
+- how different types of skills should be modeled
+- how to handle stateless vs stateful execution
+- how to make agent workflows more reliable
+
+→ Read more: https://go.deepvista.ai/agent-skills-2d
+
 ---
 
 ## Quick Start

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/README.md

@@ -2,10 +2,12 @@
   <img src="https://raw.githubusercontent.com/DeepVista-AI/deepvista-cli/main/docs/assets/deepvista-banner.png" alt="DeepVista" width="600">
 </p>
 
-<h1 align="center">Your Second Brain, from the Terminal</h1>
+<h1 align="center">Turn Your Agents into a Self-Evolving Team</h1>
 
 <p align="center">
-  <strong>CLI for DeepVista — chat, notes, skills, and knowledge base from your terminal.<br>Designed for both humans and AI agents.</strong>
+  <strong>DeepVista CLI connects your coding agents to a shared knowledge base —<br>
+    so they don’t just execute, but learn, remember, and build on past work.
+  </strong>
 </p>
 
 <div align="center">
@@ -23,7 +25,7 @@
 <br>
 
 <p align="center">
-  ⭐ If this is useful, drop a star — it helps us grow!
+⭐ If this direction resonates, consider <b>starring the repo</b> — it helps more people discover it.
 </p>
 
 <br>
@@ -33,6 +35,27 @@
 
 ---
 
+## Who this is for
+
+- Builders working with coding agents (Claude Code, Cursor, OpenCode)
+- People experimenting with agent workflows and skills
+- Anyone trying to turn scattered interactions into compounding knowledge
+
+## What this enables
+
+Modern coding agents are powerful — but each interaction is stateless and isolated.
+
+DeepVista changes that.
+
+- Agents **remember** past work
+- Agents **share context** through a common knowledge base
+- Agents **build on previous decisions and insights**
+
+Over time, this turns isolated executions into a:
+
+→ **a self-evolving team of agents that compound knowledge over time**
+
+
 ## Why DeepVista CLI?
 
 Most knowledge tools trap your data in a GUI. DeepVista CLI gives you **full access to your knowledge base from the terminal** — and lets your AI agents use it too.
@@ -44,6 +67,17 @@ Most knowledge tools trap your data in a GUI. DeepVista CLI gives you **full acc
 - 💬 **Chat** — talk to the DeepVista AI agent in your terminal
 - 🖥️ **Full TUI** — four-panel terminal UI for chat, notes, skills, and memory
 
+## Related Ideas
+
+This repo is part of a broader exploration of how agent skills are structured and executed.
+
+If you're interested in:
+- how different types of skills should be modeled
+- how to handle stateless vs stateful execution
+- how to make agent workflows more reliable
+
+→ Read more: https://go.deepvista.ai/agent-skills-2d
+
 ---
 
 ## Quick Start

deepvista_cli-0.1.4/deepvista_cli/commands/lint.py

@@ -0,0 +1,190 @@
+"""deepvista lint — LLM health checks over the vistabase.
+
+Invokes the DeepVista agent with a curated prompt asking it to audit the
+knowledge base for: duplicates, contradictions, stale claims, orphan pages,
+missing cross-references, and data gaps that could be filled with a web search.
+
+Inspired by karpathy's "LLM health checks" over the wiki:
+https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
+
+Streams the agent's response as NDJSON (same format as `chat +send`).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+
+from deepvista_cli.client.http import DeepVistaClient
+from deepvista_cli.output.formatter import format_output
+
+LINT_CHECKS = [
+    "duplicates",
+    "contradictions",
+    "stale",
+    "orphans",
+    "missing-refs",
+    "gaps",
+    "all",
+]
+
+_CHECK_INSTRUCTIONS = {
+    "duplicates": (
+        "Find duplicate or near-duplicate cards in the vistabase. "
+        "Use `find_similar_cards` to detect semantic duplicates. "
+        "For each pair, report which one is canonical and why."
+    ),
+    "contradictions": (
+        "Find cards that contradict each other — claims on one card that "
+        "newer cards or sources have superseded. Cite both card IDs."
+    ),
+    "stale": (
+        "Find stale claims: cards whose content is likely out of date relative "
+        "to newer cards or general knowledge. Suggest updates."
+    ),
+    "orphans": (
+        "Find orphan cards — cards with no inbound references from other cards "
+        "and no relationships in the knowledge graph. Suggest where they could "
+        "be linked."
+    ),
+    "missing-refs": (
+        "Find concepts mentioned in card content that lack their own card, "
+        "or that are not cross-referenced where they should be. List candidate "
+        "new cards to create."
+    ),
+    "gaps": (
+        "Find data gaps that could be filled with a web search — important "
+        "entities or topics that are mentioned but under-described. Suggest "
+        "search queries."
+    ),
+}
+
+_FIX_INSTRUCTION = (
+    "\n\nAfter identifying issues, FIX them: merge duplicates by calling "
+    "`upsert_context_card` on the canonical card and deleting the loser, "
+    "update stale cards with current info, and link orphans. Confirm each "
+    "change as you go."
+)
+
+_REPORT_INSTRUCTION = (
+    "\n\nReport findings only — do NOT modify, merge, or delete any cards. "
+    "List each issue with card IDs and a recommended action."
+)
+
+
+def _resolve_checks(checks: tuple[str, ...]) -> list[str]:
+    """Expand "all" to the full check set. "all" + others => all (with a warning)."""
+    if not checks or "all" in checks:
+        explicit = [c for c in checks if c not in ("all", "")]
+        if explicit:
+            click.echo(
+                f"warning: --check all supersedes {', '.join(explicit)}; running the full check set.",
+                err=True,
+            )
+        return [k for k in _CHECK_INSTRUCTIONS if k != "all"]
+    # Preserve caller order; de-dup while keeping first occurrence.
+    seen: set[str] = set()
+    return [c for c in checks if not (c in seen or seen.add(c))]
+
+
+def _build_prompt(selected: list[str], fix: bool) -> str:
+    lines = [
+        "Run an LLM health check over the vistabase. For each check below, "
+        "use your search and graph tools to investigate, then produce a "
+        "numbered list of findings with card IDs."
+    ]
+    for i, key in enumerate(selected, 1):
+        lines.append(f"{i}. [{key}] {_CHECK_INSTRUCTIONS[key]}")
+
+    lines.append(_FIX_INSTRUCTION if fix else _REPORT_INSTRUCTION)
+    return "\n".join(lines)
+
+
+def _client(ctx: click.Context) -> DeepVistaClient:
+    return ctx.obj._client
+
+
+@click.command("lint")
+@click.option(
+    "--check",
+    "checks",
+    type=click.Choice(LINT_CHECKS, case_sensitive=False),
+    multiple=True,
+    default=("all",),
+    help="Which checks to run. Repeatable. Default: all.",
+)
+@click.option(
+    "--fix",
+    is_flag=True,
+    default=False,
+    help="Let the agent apply fixes (merge duplicates, etc.) instead of only reporting.",
+)
+@click.option(
+    "--yes",
+    "-y",
+    "assume_yes",
+    is_flag=True,
+    default=False,
+    help="Skip the --fix confirmation prompt. Use only in scripts/cron.",
+)
+@click.option("--chat-id", default=None, help="Continue an existing lint session.")
+@click.option("--dry-run", is_flag=True, default=False, help="Preview the prompt without calling the agent.")
+@click.pass_context
+def lint_command(
+    ctx: click.Context,
+    checks: tuple[str, ...],
+    fix: bool,
+    assume_yes: bool,
+    chat_id: str | None,
+    dry_run: bool,
+) -> None:
+    """Health-check the vistabase with the DeepVista agent.
+
+    Checks for duplicates, contradictions, stale claims, orphan cards, missing
+    cross-references, and web-fillable data gaps. Reports by default; pass
+    `--fix` to let the agent merge/update/link cards.
+
+    > [!CAUTION] With `--fix`, this is a write command — the agent may merge,
+    > update, or delete cards. Confirm with the user before executing.
+    """
+    selected = _resolve_checks(checks)
+    prompt = _build_prompt(selected, fix)
+    body: dict[str, Any] = {"user_instruction": prompt}
+    if chat_id:
+        body["chat_id"] = chat_id
+
+    if dry_run:
+        format_output(
+            {
+                "dry_run": True,
+                "would": "send lint prompt to DeepVista agent",
+                "checks": selected,
+                "fix": fix,
+                "payload": body,
+            },
+            ctx.obj.output_format,
+            entity_type="chat",
+            base_url=ctx.obj.auth_url,
+        )
+        return
+
+    if fix and not assume_yes:
+        click.confirm(
+            "--fix lets the agent merge, update, and delete cards. Continue?",
+            abort=True,
+        )
+
+    try:
+        for event in _client(ctx).stream_sse("/imagine", body):
+            click.echo(json.dumps(event, default=str))
+    except (KeyboardInterrupt, click.Abort):
+        click.echo(json.dumps({"type": "interrupted", "message": "lint stream aborted by user"}), err=True)
+        raise
+    except Exception as exc:
+        click.echo(
+            json.dumps({"type": "error", "message": f"lint stream failed: {exc}"}),
+            err=True,
+        )
+        raise

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/deepvista_cli/commands/notes.py

@@ -2,11 +2,13 @@
 
 Notes are a special case of context cards with type="note".
 The +quick helper creates a note from a single text argument.
+The index command triggers entity extraction on notes not yet processed.
 """
 
 from __future__ import annotations
 
 import json as _json
+from typing import Any
 
 import click
 
@@ -182,6 +184,78 @@ def notes_delete(ctx: click.Context, note_id: str, dry_run: bool) -> None:
     format_output(data, ctx.obj.output_format, entity_type="note", base_url=ctx.obj.auth_url)
 
 
+# ---------------------------------------------------------------------------
+# index — trigger entity extraction on notes
+# ---------------------------------------------------------------------------
+
+
+@notes_group.command("index")
+@click.option(
+    "--limit",
+    type=click.IntRange(1, 500),
+    default=50,
+    help="Max notes to re-index (default 50, max 500).",
+)
+@click.option("--note-id", "note_ids", multiple=True, help="Index specific note(s) by ID. Repeatable.")
+@click.option(
+    "--all",
+    "include_enriched",
+    is_flag=True,
+    default=False,
+    help=(
+        "Re-enrich every note up to --limit, not just those with a null embedding. "
+        "Ignored when --note-id is set (explicit IDs always re-enrich)."
+    ),
+)
+@click.option("--dry-run", is_flag=True, default=False, help="Preview what would happen without making any changes.")
+@click.pass_context
+def notes_index(
+    ctx: click.Context,
+    limit: int,
+    note_ids: tuple[str, ...],
+    include_enriched: bool,
+    dry_run: bool,
+) -> None:
+    """Trigger entity extraction on notes that need processing.
+
+    Calls the server-side `/index_notes` route. By default, finds notes that
+    have never been enriched (null embedding) and enqueues the DeepVista
+    agent to extract entities, create graph relationships, and refresh
+    embeddings. Pass `--note-id` (repeatable) to target specific cards, or
+    `--all` to re-enrich everything up to `--limit`.
+
+    > [!CAUTION] This is a write command — it kicks off background agent runs
+    > that may create/update related cards. Confirm before executing.
+    """
+    # Explicit IDs always bypass the unenriched filter — the user asked for those cards specifically.
+    only_unenriched = not include_enriched and not note_ids
+    body: dict[str, Any] = {
+        "card_type": "note",
+        "limit": limit,
+        "only_unenriched": only_unenriched,
+    }
+    if note_ids:
+        body["card_ids"] = list(note_ids)
+
+    if dry_run:
+        format_output(
+            {"dry_run": True, "would": "POST /index_notes", "payload": body},
+            ctx.obj.output_format,
+            entity_type="note",
+            base_url=ctx.obj.auth_url,
+        )
+        return
+
+    data = _client(ctx).post("/index_notes", body)
+    format_output(
+        data,
+        ctx.obj.output_format,
+        title="Indexed Notes",
+        entity_type="note",
+        base_url=ctx.obj.auth_url,
+    )
+
+
 # ---------------------------------------------------------------------------
 # Helper: +quick
 # ---------------------------------------------------------------------------

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/deepvista_cli/commands/skill.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import json
 import re
+from typing import Any
 
 import click
 
@@ -19,6 +20,10 @@ from deepvista_cli.output.formatter import format_output, output_error
 
 SKILL_COLUMNS = ["id", "title", "display_status", "updated_at"]
 
+SKILL_KINDS = ("persona", "workflow")
+
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+
 
 def _client(ctx: click.Context) -> DeepVistaClient:
     return ctx.obj._client
@@ -95,7 +100,6 @@ def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, dry_run
 
     Output is NDJSON (one JSON object per line) as the agent streams its response.
     """
-    _UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
     if not _UUID_RE.match(skill_id):
         output_error(3, "Invalid skill ID", f"Expected UUID format, got: {skill_id!r}")
 
@@ -226,3 +230,165 @@ def skill_install(ctx: click.Context, skill_id: str, dry_run: bool) -> None:
         click.echo(json.dumps({"status": "already_installed", "card": data.get("card", {})}, indent=2, default=str))
     else:
         click.echo(json.dumps({"status": "installed", "card": data.get("card", {})}, indent=2, default=str))
+
+
+# ---------------------------------------------------------------------------
+# create-from-note — synthesize skills from a source note via the agent
+# ---------------------------------------------------------------------------
+
+
+_CREATE_FROM_NOTE_INSTRUCTIONS = {
+    "persona": (
+        "A **persona skill** named `persona-<interviewee-slug>` that captures the "
+        "interviewee's philosophy, voice, and decision-making lens. When loaded, "
+        "the agent should respond in their voice and apply their frameworks. "
+        "Include: who they are, core mental models drawn from the note, voice/"
+        "tone rules, and a 3-5 phase advising sequence using <accordion>/<nli> "
+        "shortcodes."
+    ),
+    "workflow": (
+        "A **workflow skill** named `workflow-<topic-slug>` that turns the "
+        "interviewee's frameworks or steps into an executable workflow. The user "
+        "provides inputs; the workflow classifies, recommends, and returns a "
+        "prioritized plan. Include: purpose, **a `## Workflow` section with a "
+        "`mermaid` flowchart diagram that visualises the decision graph — "
+        "ALWAYS open the fence with the `mermaid` info string (```mermaid) "
+        "and use `flowchart TD`**, input schema, 4-6 phases using "
+        "<accordion>/<nli> shortcodes, cheat sheet, and output format template. "
+        "**Mermaid animation is REQUIRED, not optional.** For every edge in "
+        "the flowchart, give it an ID using mermaid v11 syntax "
+        "(`A e1@--> B`, `B e2@--> C`, …) and turn animation on with "
+        "`e1@{ animation: slow }` for happy-path edges and "
+        "`e1@{ animation: fast }` for tight loops. Every edge must have an "
+        "ID and every ID must have an animation directive — a static "
+        "diagram is a rendering bug, not an acceptable output. "
+        "**Node-label rules (critical for rendering): every node label must "
+        "be a single short line, ≤ 30 characters. Do NOT use `<br/>`, "
+        "`\\n`, `<b>`, `<i>`, or any HTML tags inside `[ ... ]`, `( ... )`, "
+        "or `{ ... }`. If you need a sub-description, chain a second node "
+        "below instead of stuffing two lines into one node — mermaid's "
+        "HTML-label sizing clips wrapped text and multi-line content will "
+        "render cut off.** Keep the diagram under ~15 nodes — split into "
+        "multiple diagrams if the workflow is larger."
+    ),
+}
+
+
+def _build_create_from_note_prompt(note_id: str, kinds: tuple[str, ...]) -> str:
+    lines = [
+        f'Look up the note with id "{note_id}" using `read_context_card`. Read '
+        "its full content. From that note, generate the skill(s) listed below. "
+        "Ground every detail in the note — do not invent frameworks or advice "
+        "the note doesn't contain.",
+        "",
+        "Skills to generate:",
+    ]
+    for i, kind in enumerate(kinds, 1):
+        lines.append(f"{i}. {_CREATE_FROM_NOTE_INSTRUCTIONS[kind]}")
+    lines.append("")
+    lines.append(
+        "**You MUST persist each skill by calling `upsert_context_card` with "
+        '`card_type="skill"`.** Do not write the skill content to a local '
+        "file, do not paste it in the chat response, do not skip the tool "
+        "call. One `upsert_context_card` invocation per skill."
+    )
+    lines.append("")
+    lines.append(
+        "For each `upsert_context_card` call: set `title` to the skill name, "
+        "put the full SKILL.md body in `description`, add relevant `tags` "
+        "including the kind (`persona` or `workflow`), and link the source "
+        f'note via `related_context_card_ids=["{note_id}"]`. After each call, '
+        "confirm the returned card id in the chat response."
+    )
+    return "\n".join(lines)
+
+
+@skill_group.command("create-from-note")
+@click.argument("note_id")
+@click.option(
+    "--kind",
+    "kinds",
+    type=click.Choice(SKILL_KINDS, case_sensitive=False),
+    multiple=True,
+    default=SKILL_KINDS,
+    help="Which skill kinds to synthesize. Repeatable. Default: persona and workflow.",
+)
+@click.option("--chat-id", default=None, help="Continue an existing synthesis session.")
+@click.option(
+    "--yes",
+    "-y",
+    "assume_yes",
+    is_flag=True,
+    default=False,
+    help="Skip the write confirmation prompt. Use only in scripts/batch conversion.",
+)
+@click.option("--dry-run", is_flag=True, default=False, help="Preview the prompt without calling the agent.")
+@click.pass_context
+def skill_create_from_note(
+    ctx: click.Context,
+    note_id: str,
+    kinds: tuple[str, ...],
+    chat_id: str | None,
+    assume_yes: bool,
+    dry_run: bool,
+) -> None:
+    """Synthesize skill card(s) from a note via the DeepVista agent.
+
+    Reads the note identified by `note_id` and invokes the agent with a curated
+    prompt that produces one `persona` skill (interviewee's voice + frameworks)
+    and/or one `workflow` skill (executable steps), grounded in the note's
+    content. Each generated skill is stored as a context card of `type=skill`.
+
+    Designed for batch-converting podcast / interview notes into reusable
+    skills. Streams NDJSON identical to `chat +send` and `skill run`.
+
+    > [!CAUTION] This is a write command — the agent creates skill cards in
+    > the user's project. Confirm before executing.
+    """
+    if not _UUID_RE.match(note_id):
+        output_error(3, "Invalid note ID", f"Expected UUID format, got: {note_id!r}")
+
+    # Empty tuple shouldn't happen with default, but guard anyway.
+    selected = kinds or SKILL_KINDS
+    # De-dup while preserving order.
+    seen: set[str] = set()
+    selected = tuple(k for k in selected if not (k in seen or seen.add(k)))
+
+    prompt = _build_create_from_note_prompt(note_id, selected)
+    body: dict[str, Any] = {"user_instruction": prompt}
+    if chat_id:
+        body["chat_id"] = chat_id
+
+    if dry_run:
+        format_output(
+            {
+                "dry_run": True,
+                "would": "synthesize skills from note via DeepVista agent",
+                "note_id": note_id,
+                "kinds": list(selected),
+                "payload": body,
+            },
+            ctx.obj.output_format,
+            entity_type="skill",
+            base_url=ctx.obj.auth_url,
+        )
+        return
+
+    if not assume_yes:
+        click.confirm(
+            f"The agent will create {len(selected)} skill card(s) from note {note_id}. Continue?",
+            abort=True,
+        )
+
+    try:
+        for event in _client(ctx).stream_sse("/imagine", body):
+            click.echo(json.dumps(event, default=str))
+    except (KeyboardInterrupt, click.Abort):
+        click.echo(json.dumps({"type": "interrupted", "message": "skill synthesis aborted by user"}), err=True)
+        raise
+    except Exception as exc:
+        click.echo(
+            json.dumps({"type": "error", "message": f"skill synthesis stream failed: {exc}"}),
+            err=True,
+        )
+        raise

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/deepvista_cli/main.py

@@ -28,6 +28,7 @@ from deepvista_cli.commands.auth import auth_group
 from deepvista_cli.commands.card import card_group
 from deepvista_cli.commands.chat import chat_group
 from deepvista_cli.commands.config import config_group
+from deepvista_cli.commands.lint import lint_command
 from deepvista_cli.commands.memory import vistabase_group
 from deepvista_cli.commands.notes import notes_group
 from deepvista_cli.commands.skill import skill_group
@@ -89,6 +90,7 @@ cli.add_command(agents_group)
 cli.add_command(auth_group)
 cli.add_command(config_group)
 cli.add_command(upgrade_command)
+cli.add_command(lint_command)
 
 # Legacy aliases for backward compatibility
 cli.add_command(notes_group)  # notes = cards with type=note (explicit knowledge layer)

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/install.sh

@@ -361,6 +361,5 @@ fi
 echo ""
 echo "DeepVista is ready. Open your AI agent and say:"
 echo ""
-echo '  Load skill: deepvista'
 echo '  Help me get started with DeepVista.'
 echo ""

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepvista-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "CLI for DeepVista — chat, notes, skills, and memory from your terminal."
 readme = "README.md"
 license = { text = "Apache-2.0" }

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/skills/deepvista/SKILL.md

@@ -4,15 +4,15 @@ name: deepvista
 description: |
   DeepVista CLI — knowledge base, notes, chat, skills, and memory from the terminal.
   One skill for the full `deepvista` CLI. Load when the user wants to: take a note, jot
-  this down, save / remember a fact, or list and edit notes; create, search, pin, archive,
-  edit, or grep knowledge-base cards of any type (person, topic, file, note, todo…);
-  view or semantic-search implicit memory ("vistabase" / "memory"); chat with the AI agent
-  or manage chat sessions; list, run, export, install, or discover Skills (structured
-  workflow checklists); research the knowledge base then run a Skill with synthesized
-  context; analyze / summarize / find patterns across notes; recursively import a local
-  folder as file cards; run a knowledge-worker daily loop (check pinned cards, capture,
-  run a Skill, ask for synthesis); or auto-capture notable facts without confirmation
-  (OpenClaw). Pick the matching reference file in `reference/` for the subcommand.
+  this down, save a fact, or list and edit notes; create, search, pin, archive, edit,
+  or grep knowledge-base cards of any type (person, topic, file, note, todo…); view or
+  semantic-search implicit memory ("vistabase" / "memory"); chat with the AI agent or
+  manage sessions; list, run, export, install, or discover Skills; research then run a
+  Skill with synthesized context; analyze / summarize notes; import a folder as file
+  cards; run a knowledge-worker daily loop; auto-capture facts (OpenClaw); periodically
+  lint the vistabase for duplicates / contradictions / stale claims / orphans / missing
+  refs / gaps; or re-index notes to trigger entity extraction. Pick the matching
+  reference file in `reference/` for the subcommand.
 metadata:
   openclaw:
     category: service
@@ -43,7 +43,8 @@ other reference file assumes you know it.
 | Subcommand | Use when | Reference |
 |---|---|---|
 | `deepvista auth` / `agents` / `config` / `upgrade` / `ui` | authenticating, registering an agent, switching profiles, checking for updates | [shared.md](reference/shared.md) |
-| `deepvista notes` | taking a note, jotting something down, listing / updating / deleting notes, quick-capture of a single-line fact | [notes.md](reference/notes.md) |
+| `deepvista notes` | taking a note, jotting something down, listing / updating / deleting notes, quick-capture of a single-line fact, re-indexing notes for entity extraction | [notes.md](reference/notes.md) |
+| `deepvista lint` | periodic LLM health check over the vistabase — duplicates, contradictions, stale claims, orphans, missing cross-references, data gaps | [lint.md](reference/lint.md) |
 | `deepvista card` | creating / searching / pinning / archiving / grepping knowledge base cards across any type (person, topic, file, note, todo, etc.) | [vistabase-card.md](reference/vistabase-card.md) |
 | `deepvista vistabase` (alias: `memory`) | viewing or semantic-searching implicit memory accumulated from chat | [vistabase.md](reference/vistabase.md) · [memory.md](reference/memory.md) |
 | `deepvista chat` | sending a message to the AI agent, listing / deleting chat sessions, continuing a conversation | [chat.md](reference/chat.md) |
@@ -51,6 +52,7 @@ other reference file assumes you know it.
 | — analyze notes | searching → reading → synthesizing notes to surface themes / patterns | [skill-analyze-notes.md](reference/skill-analyze-notes.md) |
 | — research → run | finding context in the knowledge base, then running a Skill with synthesized input | [skill-research-to-skill.md](reference/skill-research-to-skill.md) |
 | — export | exporting a DeepVista Skill as a portable `SKILL.md` file for another agent | [skill-export-knowledge.md](reference/skill-export-knowledge.md) |
+| — create from note | synthesizing a persona + workflow skill from a podcast / interview / book note; batch-converting a corpus | [skill-create-from-note.md](reference/skill-create-from-note.md) |
 | — import files | recursively importing a local folder as `type=file` cards | [skill-import-files.md](reference/skill-import-files.md) |
 | persona: knowledge worker | daily workflow — check pinned cards, capture insights, run a Skill, ask the agent to synthesize | [persona-knowledge-worker.md](reference/persona-knowledge-worker.md) |
 | auto-capture for OpenClaw | automatically saving notable facts from conversations without confirmation | [openclaw.md](reference/openclaw.md) |

deepvista_cli-0.1.4/skills/deepvista/reference/lint.md

@@ -0,0 +1,107 @@
+# Lint — LLM health checks over the vistabase
+
+`deepvista lint` asks the DeepVista agent to audit the knowledge base for
+quality issues: duplicates, contradictions, stale claims, orphan cards,
+missing cross-references, and data gaps. Inspired by
+[karpathy's LLM health-check idea](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
+
+The agent uses `find_similar_cards`, `chat_cypher_search`, and `exa_search`
+to investigate, then streams a numbered findings list back as NDJSON
+(same format as `chat +send`).
+
+## Command
+
+### `lint` — write (agent invocation)
+
+> [!CAUTION] Calls the DeepVista agent. With `--fix`, the agent may merge,
+> update, or delete cards. Confirm with the user before executing.
+
+```bash
+deepvista lint [--check KIND]... [--fix] [--chat-id ID] [--dry-run]
+```
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--check KIND` | `all` | Scope: `duplicates`, `contradictions`, `stale`, `orphans`, `missing-refs`, `gaps`, `all`. Repeatable. |
+| `--fix` | off | Let the agent apply fixes (merge duplicates, update stale cards, link orphans). Default is report-only. |
+| `--chat-id ID` | — | Continue an existing lint session. |
+| `--dry-run` | — | Print the prompt that would be sent to the agent without calling it. |
+
+## Checks
+
+| Check | What it looks for |
+|---|---|
+| `duplicates` | Near-duplicate cards (semantic). Canonical vs. loser. |
+| `contradictions` | Cards whose claims conflict — newer source supersedes older. |
+| `stale` | Content likely out of date relative to newer cards or general knowledge. |
+| `orphans` | Cards with no inbound refs or graph relationships. |
+| `missing-refs` | Concepts mentioned but lacking their own card. |
+| `gaps` | Under-described entities that could be filled with a web search. |
+
+## Examples
+
+```bash
+# Full health check, report only
+deepvista lint
+
+# Just duplicates
+deepvista lint --check duplicates
+
+# Duplicates + contradictions, let the agent fix
+deepvista lint --check duplicates --check contradictions --fix
+
+# Preview the prompt
+deepvista lint --dry-run
+```
+
+## Scheduling (periodic linting)
+
+The whole point of lint is to run it periodically so the vistabase stays
+clean as it grows. Two good cadences:
+
+- **Every 4 hours:** catch freshly-added cards before they drift.
+- **Weekly:** full `--fix` pass.
+
+### Claude Code — background /loop
+
+```bash
+# In a Claude Code session, kick off a self-pacing loop.
+# /loop without an explicit interval runs indefinitely — stop it with /stop.
+/loop deepvista lint --check duplicates
+```
+
+Or schedule it persistently with the `schedule` skill (survives session end):
+
+```bash
+/schedule "every 4 hours" deepvista lint --check duplicates
+/schedule "weekly" deepvista lint --fix --yes
+```
+
+`--fix` normally prompts for confirmation; scheduled runs must pass `--yes`
+to accept the write blast radius non-interactively.
+
+### Cursor Agent — cron
+
+Cursor doesn't ship a native scheduler. Use system cron. Log into the
+existing CLI config directory so logs live next to credentials and respect
+`DEEPVISTA_CONFIG_DIR`:
+
+```cron
+# One-time setup: mkdir -p ~/.config/deepvista/logs
+#
+# Every 4 hours: lint + re-index notes.
+0 */4 * * *  deepvista lint --check duplicates >> ~/.config/deepvista/logs/lint.log 2>&1
+15 */4 * * * deepvista notes index --limit 50  >> ~/.config/deepvista/logs/index.log 2>&1
+```
+
+### Any agent — `at` / launchd / systemd
+
+`deepvista lint` is stdout-friendly (NDJSON), so pipe it into whatever job
+runner you already have.
+
+## See also
+
+- [notes.md](notes.md) — `deepvista notes index` triggers entity extraction
+  on individual notes; often paired with `lint --check missing-refs`.
+- [chat.md](chat.md) — `lint` is a curated variant of `chat +send`; the
+  NDJSON event format is identical.

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/skills/deepvista/reference/notes.md

@@ -60,6 +60,28 @@ Same content rules as `create`. Only provided fields are changed.
 deepvista notes delete <note_id>
 ```
 
+### `index` — write
+
+> [!CAUTION] Queues the DeepVista agent to run entity extraction + graph
+> linking + embedding refresh on unprocessed notes. Confirm first.
+
+```bash
+deepvista notes index [--limit N] [--note-id ID]... [--all] [--dry-run]
+```
+
+| Flag | When |
+|---|---|
+| `--limit N` | Max notes to process (default 50, max 500, newest first) |
+| `--note-id ID` | Target specific note(s). Repeatable. Implies re-enrichment — the unenriched filter is dropped for explicit IDs, and `--all` is redundant. |
+| `--all` | Re-enrich every note up to `--limit`, not just those with a null embedding. Ignored when `--note-id` is set. |
+| `--dry-run` | Preview the request without calling the backend |
+
+Posts to the server-side `/index_notes` route, which enqueues one chat task
+per card using the same pipeline `create_context_card` uses. Use after
+bulk-importing notes, after a long offline period, or when entities appear
+missing from the graph. Pair with `deepvista lint --check missing-refs` to
+find concepts that still need their own card.
+
 ### `+quick` — write
 
 > [!CAUTION] Writes a new note. Confirm first (or skip confirmation if the agent is

deepvista_cli-0.1.4/skills/deepvista/reference/skill-create-from-note.md

@@ -0,0 +1,93 @@
+# Create skills from a note
+
+`deepvista skill create-from-note <note_id>` asks the DeepVista agent to read
+a source note (podcast episode, interview transcript, book chapter, research
+summary) and synthesize one or more skill cards grounded in the note's
+content. Two kinds are produced by default:
+
+- **`persona`** — captures the interviewee/author's voice, philosophy, and
+  decision-making lens. When loaded, the agent responds in their voice and
+  applies their frameworks.
+- **`workflow`** — turns the frameworks or steps they shared into an
+  executable workflow (inputs → phases → output template).
+
+Streams NDJSON identical to `chat +send` and `skill run`. Each generated
+skill is stored as a context card of `type=skill` in the user's project.
+
+## Command
+
+> [!CAUTION] Write — the agent creates skill cards in the user's project.
+> Confirm before executing, or pass `--yes` for scripted/batch use.
+
+```bash
+deepvista skill create-from-note <note_id> \
+  [--kind persona|workflow]... [--chat-id ID] [--yes] [--dry-run]
+```
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `<note_id>` | required | UUID of the source note. Must exist in the caller's project. |
+| `--kind KIND` | `persona` + `workflow` | Repeatable. Restrict to one kind, e.g. `--kind persona`. |
+| `--chat-id ID` | — | Continue an existing synthesis session (iterate on the skills). |
+| `--yes` / `-y` | off | Skip the confirmation prompt. Required for scripts and cron. |
+| `--dry-run` | — | Print the prompt without calling the agent. |
+
+## When to use
+
+- You've captured a podcast episode / interview / book chapter as a note.
+- You want a reusable persona or workflow skill extracted from it.
+- You want to batch-convert a corpus (e.g. every Lenny's Podcast note tagged
+  `lenny`, every FounderCoHo note tagged `foundercoho`) into installable
+  skills.
+
+## Batch pattern
+
+There's no built-in bulk flag — use a shell loop. The `--yes` flag avoids
+per-note confirmation prompts:
+
+```bash
+# Every note tagged "lenny" → persona + workflow skills
+deepvista notes list --limit 100 \
+  | jq -r '.notes[] | select(.tags | index("lenny")) | .id' \
+  | while read -r note_id; do
+      deepvista skill create-from-note "$note_id" --yes \
+        >> ~/.config/deepvista/logs/skill-synthesis.log 2>&1
+    done
+```
+
+For a narrower pass (only the workflow):
+
+```bash
+deepvista skill create-from-note <note_id> --kind workflow --yes
+```
+
+## After creation
+
+Generated skills land with `status=unconfirmed`. Inspect each with
+[`deepvista card get <card_id>`](vistabase-card.md) and verify the SKILL.md
+body before running or exporting. See [skill-export-knowledge.md](skill-export-knowledge.md)
+for turning a stored skill into a portable `SKILL.md` file.
+
+## Examples
+
+```bash
+# Both kinds, interactive confirm
+deepvista skill create-from-note 0d5d1fb2-7414-4593-abc4-fb74984f4b2f
+
+# Persona only, scripted
+deepvista skill create-from-note 0d5d1fb2-... --kind persona --yes
+
+# Preview prompt
+deepvista skill create-from-note 0d5d1fb2-... --dry-run
+
+# Iterate on a prior synthesis
+deepvista skill create-from-note 0d5d1fb2-... --chat-id gmrpoqqw
+```
+
+## See also
+
+- [notes.md](notes.md) — capturing the source note (`deepvista notes create`
+  with `--content-file`) and re-indexing.
+- [skill.md](skill.md) — listing, running, exporting the generated skills.
+- [skill-research-to-skill.md](skill-research-to-skill.md) — broader pattern
+  (search → synthesize → run) when the source material spans multiple cards.

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/skills/deepvista/reference/skill.md

@@ -20,6 +20,19 @@ deepvista skill get <skill_id>
 
 Returns the full Skill definition including every phase and step.
 
+### `create-from-note` — write
+
+> [!CAUTION] The agent creates skill cards grounded in a source note.
+> Confirm first (or pass `--yes` in batch scripts).
+
+```bash
+deepvista skill create-from-note <note_id> [--kind persona|workflow]... [--yes] [--dry-run]
+```
+
+Synthesizes one `persona` skill and/or one `workflow` skill from a source
+note (podcast, interview, book chapter, research summary). Full guide:
+[skill-create-from-note.md](skill-create-from-note.md).
+
 ### `run` — write
 
 > [!CAUTION] Starts a new Skill run and creates a chat session. Confirm first.

{deepvista_cli-0.1.2 → deepvista_cli-0.1.4}/uv.lock

@@ -56,7 +56,7 @@ wheels = [
 
 [[package]]
 name = "deepvista-cli"
-version = "0.1.2"
+version = "0.1.4"
 source = { editable = "." }
 dependencies = [
     { name = "click" },