codespine 0.6.3__tar.gz → 0.7.1__tar.gz

{codespine-0.6.3 → codespine-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.6.3
+Version: 0.7.1
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -223,45 +223,134 @@ If the client launches the wrong Python environment, use the absolute binary pat
 }
 ```
 
-Common MCP tools:
+### Agent Onboarding
 
-- `search_hybrid(query, k, project)`
-- `find_symbol(name, kind, project, limit)`
-- `get_symbol_context(query, max_depth, project)`
-- `get_impact(symbol, max_depth, project)`
-- `detect_dead_code(limit, project, strict)`
-- `trace_execution_flows(entry_symbol, max_depth, project)`
-- `get_symbol_community(symbol)`
-- `get_change_coupling(months, min_strength, min_cochanges, project)`
-- `compare_branches(base_ref, head_ref)`
-- `get_codebase_stats()`
+When an agent connects to CodeSpine for the first time, it should call:
 
-## CLI
+1. **`guide()`** — returns a structured catalog of every tool, organized by category, with recommended workflows and tips.
+2. **`get_capabilities()`** — returns what is indexed right now, which features are ready, and what's missing.
 
-Core commands:
+The same information is available from the CLI:
 
 ```bash
-codespine analyse <path>
-codespine analyse <path> --full
-codespine analyse <path> --deep
-codespine analyse <path> --embed
-codespine watch --path .
-codespine watch --path . --overlay-debounce-ms 1500
-codespine search "query"
-codespine context "symbol"
-codespine impact "symbol"
-codespine deadcode
-codespine flow
-codespine community
-codespine coupling
-codespine diff main..feature
-codespine stats
-codespine list
-codespine overlay-status
-codespine overlay-promote
-codespine overlay-clear
-codespine clear-project <project_id>
-codespine clear-index
+codespine guide          # tool catalog, workflows, tips
+codespine guide --json   # structured JSON for tooling
+```
+
+### MCP Tools
+
+**Discovery & Status**
+
+| Tool | Description |
+|------|-------------|
+| `guide()` | Tool catalog, workflows, and tips. Call first if new to CodeSpine. |
+| `get_capabilities()` | What is indexed and which features are available right now. |
+| `list_projects()` | All indexed projects with symbol/file counts. |
+| `get_codebase_stats()` | Per-project stats: files, classes, methods, call edges, embeddings. |
+| `list_packages(project)` | Java packages in the index. |
+| `ping()` | Verify the MCP server is alive. |
+
+**Search & Lookup**
+
+| Tool | Description |
+|------|-------------|
+| `search_hybrid(query, k, project)` | Ranked symbol search (BM25 + vector + fuzzy via RRF). |
+| `find_symbol(name, kind, project, limit)` | Exact/prefix name lookup across all projects. |
+| `get_symbol_context(query, max_depth, project)` | One-shot deep context: search + impact + community + flows. |
+| `get_neighborhood(symbol, project)` | Callers, callees, siblings, and override/implements. |
+
+**Analysis**
+
+| Tool | Description |
+|------|-------------|
+| `get_impact(symbol, max_depth, project)` | Caller-tree impact analysis with confidence scores. |
+| `detect_dead_code(limit, project, strict)` | Methods with no callers (Java-aware exemptions). |
+| `trace_execution_flows(entry_symbol, max_depth, project)` | Execution paths from entry points. |
+| `get_symbol_community(symbol)` | Architectural community cluster for a symbol. |
+| `get_change_coupling(months, min_strength, min_cochanges)` | Files that historically change together. |
+
+**Git**
+
+| Tool | Description |
+|------|-------------|
+| `git_log(file_path, limit, project)` | Recent git commits. |
+| `git_diff(ref, file_path, project)` | Git diff (working tree vs ref, or between refs). |
+| `compare_branches(base_ref, head_ref, project)` | Symbol-level diff between two git refs. |
+
+**Indexing & Watch**
+
+| Tool | Description |
+|------|-------------|
+| `analyse_project(path, full, deep, embed)` | Index a Java project (background job). |
+| `get_analyse_status()` | Poll analysis progress. |
+| `reindex_file(file_path, project)` | Re-index a single `.java` file (<1 s). |
+| `start_watch(path)` | Watch for `.java` changes and update overlay in real time. |
+| `stop_watch()` | Stop the background watch process. |
+| `get_watch_status()` | Watch mode status: running, path, uptime. |
+
+**Overlay**
+
+| Tool | Description |
+|------|-------------|
+| `get_overlay_status(project)` | Uncommitted overlay state by project/module. |
+| `promote_overlay(project)` | Commit dirty overlay into the base index. |
+| `clear_overlay(project)` | Discard dirty overlay without changing the base. |
+
+**Reset**
+
+| Tool | Description |
+|------|-------------|
+| `reset_project(project_id)` | Remove all data for one project. |
+| `reset_index()` | Remove ALL data across every project. |
+| `force_reset_index()` | Emergency: delete data files when normal reset fails. |
+
+**Advanced**
+
+| Tool | Description |
+|------|-------------|
+| `run_cypher(query)` | Run a raw Cypher query against the graph DB. |
+
+## CLI
+
+```bash
+# Indexing
+codespine analyse <path>                     # incremental index
+codespine analyse <path> --full              # full re-index
+codespine analyse <path> --deep              # + communities, flows, dead code, coupling
+codespine analyse <path> --embed             # + vector embeddings
+codespine watch --path .                     # live re-index on file changes
+
+# Search & Analysis
+codespine search "query"                     # hybrid search
+codespine context "symbol"                   # one-shot deep context
+codespine impact "symbol"                    # caller-tree impact
+codespine deadcode                           # dead code candidates
+codespine flow                               # execution flows
+codespine community                          # architectural clusters
+codespine coupling                           # git change coupling
+codespine diff main..feature                 # symbol-level branch diff
+
+# Status & Info
+codespine stats                              # per-project statistics
+codespine list                               # indexed projects
+codespine status                             # service and database status
+codespine guide                              # tool catalog and workflows
+
+# Overlay
+codespine overlay-status                     # dirty overlay state
+codespine overlay-promote                    # commit overlay to base
+codespine overlay-clear                      # discard overlay
+
+# Server Management
+codespine start                              # launch background MCP server
+codespine stop                               # stop background MCP server
+codespine mcp                                # foreground MCP (stdio, for IDE)
+
+# Cleanup & Reset
+codespine clear-project <project_id>         # remove one project
+codespine clear-index                        # remove all indexed data
+codespine force-reset                        # emergency: delete all data files
+codespine setup                              # check dependencies
 ```
 
 `analyse` defaults to incremental mode. Repeat runs are designed to be fast when files have not changed.
@@ -323,8 +412,8 @@ Running `codespine analyse --deep --embed` on one project while querying a diffe
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
 - `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
 - `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
+- `codespine force-reset` is the nuclear option — it deletes all data files without going through the DB engine. Use it when `clear-index` fails due to DB corruption.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
-- The first run after upgrading to v0.5.7 will not have a read replica yet. Run `codespine analyse` once to create it.
 
 ## Project Docs
 

{codespine-0.6.3 → codespine-0.7.1}/README.md

@@ -159,45 +159,134 @@ If the client launches the wrong Python environment, use the absolute binary pat
 }
 ```
 
-Common MCP tools:
-
-- `search_hybrid(query, k, project)`
-- `find_symbol(name, kind, project, limit)`
-- `get_symbol_context(query, max_depth, project)`
-- `get_impact(symbol, max_depth, project)`
-- `detect_dead_code(limit, project, strict)`
-- `trace_execution_flows(entry_symbol, max_depth, project)`
-- `get_symbol_community(symbol)`
-- `get_change_coupling(months, min_strength, min_cochanges, project)`
-- `compare_branches(base_ref, head_ref)`
-- `get_codebase_stats()`
+### Agent Onboarding
 
-## CLI
+When an agent connects to CodeSpine for the first time, it should call:
+
+1. **`guide()`** — returns a structured catalog of every tool, organized by category, with recommended workflows and tips.
+2. **`get_capabilities()`** — returns what is indexed right now, which features are ready, and what's missing.
 
-Core commands:
+The same information is available from the CLI:
 
 ```bash
-codespine analyse <path>
-codespine analyse <path> --full
-codespine analyse <path> --deep
-codespine analyse <path> --embed
-codespine watch --path .
-codespine watch --path . --overlay-debounce-ms 1500
-codespine search "query"
-codespine context "symbol"
-codespine impact "symbol"
-codespine deadcode
-codespine flow
-codespine community
-codespine coupling
-codespine diff main..feature
-codespine stats
-codespine list
-codespine overlay-status
-codespine overlay-promote
-codespine overlay-clear
-codespine clear-project <project_id>
-codespine clear-index
+codespine guide          # tool catalog, workflows, tips
+codespine guide --json   # structured JSON for tooling
+```
+
+### MCP Tools
+
+**Discovery & Status**
+
+| Tool | Description |
+|------|-------------|
+| `guide()` | Tool catalog, workflows, and tips. Call first if new to CodeSpine. |
+| `get_capabilities()` | What is indexed and which features are available right now. |
+| `list_projects()` | All indexed projects with symbol/file counts. |
+| `get_codebase_stats()` | Per-project stats: files, classes, methods, call edges, embeddings. |
+| `list_packages(project)` | Java packages in the index. |
+| `ping()` | Verify the MCP server is alive. |
+
+**Search & Lookup**
+
+| Tool | Description |
+|------|-------------|
+| `search_hybrid(query, k, project)` | Ranked symbol search (BM25 + vector + fuzzy via RRF). |
+| `find_symbol(name, kind, project, limit)` | Exact/prefix name lookup across all projects. |
+| `get_symbol_context(query, max_depth, project)` | One-shot deep context: search + impact + community + flows. |
+| `get_neighborhood(symbol, project)` | Callers, callees, siblings, and override/implements. |
+
+**Analysis**
+
+| Tool | Description |
+|------|-------------|
+| `get_impact(symbol, max_depth, project)` | Caller-tree impact analysis with confidence scores. |
+| `detect_dead_code(limit, project, strict)` | Methods with no callers (Java-aware exemptions). |
+| `trace_execution_flows(entry_symbol, max_depth, project)` | Execution paths from entry points. |
+| `get_symbol_community(symbol)` | Architectural community cluster for a symbol. |
+| `get_change_coupling(months, min_strength, min_cochanges)` | Files that historically change together. |
+
+**Git**
+
+| Tool | Description |
+|------|-------------|
+| `git_log(file_path, limit, project)` | Recent git commits. |
+| `git_diff(ref, file_path, project)` | Git diff (working tree vs ref, or between refs). |
+| `compare_branches(base_ref, head_ref, project)` | Symbol-level diff between two git refs. |
+
+**Indexing & Watch**
+
+| Tool | Description |
+|------|-------------|
+| `analyse_project(path, full, deep, embed)` | Index a Java project (background job). |
+| `get_analyse_status()` | Poll analysis progress. |
+| `reindex_file(file_path, project)` | Re-index a single `.java` file (<1 s). |
+| `start_watch(path)` | Watch for `.java` changes and update overlay in real time. |
+| `stop_watch()` | Stop the background watch process. |
+| `get_watch_status()` | Watch mode status: running, path, uptime. |
+
+**Overlay**
+
+| Tool | Description |
+|------|-------------|
+| `get_overlay_status(project)` | Uncommitted overlay state by project/module. |
+| `promote_overlay(project)` | Commit dirty overlay into the base index. |
+| `clear_overlay(project)` | Discard dirty overlay without changing the base. |
+
+**Reset**
+
+| Tool | Description |
+|------|-------------|
+| `reset_project(project_id)` | Remove all data for one project. |
+| `reset_index()` | Remove ALL data across every project. |
+| `force_reset_index()` | Emergency: delete data files when normal reset fails. |
+
+**Advanced**
+
+| Tool | Description |
+|------|-------------|
+| `run_cypher(query)` | Run a raw Cypher query against the graph DB. |
+
+## CLI
+
+```bash
+# Indexing
+codespine analyse <path>                     # incremental index
+codespine analyse <path> --full              # full re-index
+codespine analyse <path> --deep              # + communities, flows, dead code, coupling
+codespine analyse <path> --embed             # + vector embeddings
+codespine watch --path .                     # live re-index on file changes
+
+# Search & Analysis
+codespine search "query"                     # hybrid search
+codespine context "symbol"                   # one-shot deep context
+codespine impact "symbol"                    # caller-tree impact
+codespine deadcode                           # dead code candidates
+codespine flow                               # execution flows
+codespine community                          # architectural clusters
+codespine coupling                           # git change coupling
+codespine diff main..feature                 # symbol-level branch diff
+
+# Status & Info
+codespine stats                              # per-project statistics
+codespine list                               # indexed projects
+codespine status                             # service and database status
+codespine guide                              # tool catalog and workflows
+
+# Overlay
+codespine overlay-status                     # dirty overlay state
+codespine overlay-promote                    # commit overlay to base
+codespine overlay-clear                      # discard overlay
+
+# Server Management
+codespine start                              # launch background MCP server
+codespine stop                               # stop background MCP server
+codespine mcp                                # foreground MCP (stdio, for IDE)
+
+# Cleanup & Reset
+codespine clear-project <project_id>         # remove one project
+codespine clear-index                        # remove all indexed data
+codespine force-reset                        # emergency: delete all data files
+codespine setup                              # check dependencies
 ```
 
 `analyse` defaults to incremental mode. Repeat runs are designed to be fast when files have not changed.
@@ -259,8 +348,8 @@ Running `codespine analyse --deep --embed` on one project while querying a diffe
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
 - `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
 - `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
+- `codespine force-reset` is the nuclear option — it deletes all data files without going through the DB engine. Use it when `clear-index` fails due to DB corruption.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
-- The first run after upgrading to v0.5.7 will not have a read replica yet. Run `codespine analyse` once to create it.
 
 ## Project Docs
 

{codespine-0.6.3 → codespine-0.7.1}/codespine/__init__.py

@@ -1,4 +1,4 @@
 """CodeSpine package."""
 
 __all__ = ["__version__"]
-__version__ = "0.6.3"
+__version__ = "0.7.1"

{codespine-0.6.3 → codespine-0.7.1}/codespine/cli.py

@@ -852,6 +852,18 @@ def force_reset_cmd(force: bool) -> None:
         click.secho("Nothing to remove — already clean.", fg="yellow")
 
 
+@main.command()
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def guide(as_json: bool) -> None:
+    """Show what CodeSpine can do: tool catalog, workflows, and tips."""
+    from codespine.guide import GUIDE_SECTIONS, format_guide_terminal
+
+    if as_json:
+        _echo_json({"sections": GUIDE_SECTIONS}, as_json=True)
+    else:
+        click.echo(format_guide_terminal())
+
+
 @main.command()
 def setup() -> None:
     """Print local setup checks and next steps."""

codespine-0.7.1/codespine/guide.py

@@ -0,0 +1,169 @@
+"""CodeSpine guide – single source of truth for MCP + CLI."""
+
+from __future__ import annotations
+
+from codespine import __version__
+
+GUIDE_SECTIONS: list[dict] = [
+    {
+        "id": "overview",
+        "title": "What is CodeSpine?",
+        "body": (
+            "CodeSpine is a Java code-intelligence engine. It parses Java source "
+            "into a graph database (Kuzu) and exposes hybrid search, impact analysis, "
+            "dead-code detection, execution-flow tracing, community detection, and "
+            "git change-coupling -- all via MCP tools or CLI commands.\n"
+            "Language: Java. Layouts: single-module, multi-module (Maven/Gradle), workspaces."
+        ),
+    },
+    {
+        "id": "quickstart",
+        "title": "Recommended First Steps",
+        "body": (
+            "1. Call get_capabilities() to see what is indexed and which features are ready.\n"
+            "2. If nothing is indexed: call analyse_project(path) with the Java project root.\n"
+            "   Poll with get_analyse_status() until it finishes.\n"
+            "3. Once indexed: use search_hybrid(query) to find symbols, then drill in with\n"
+            "   get_impact(), get_symbol_context(), or get_neighborhood().\n"
+            "4. For active development: call start_watch(path) to keep the index fresh\n"
+            "   as files change on disk."
+        ),
+    },
+    # ── Tool catalog ──────────────────────────────────────────────
+    {
+        "id": "tools_discovery",
+        "title": "Discovery & Status",
+        "tools": [
+            {"name": "get_capabilities", "one_liner": "What is indexed and which features are available right now. Call this first."},
+            {"name": "list_projects", "one_liner": "All indexed projects with symbol/file counts."},
+            {"name": "get_codebase_stats", "one_liner": "Per-project stats: files, classes, methods, call edges, embeddings."},
+            {"name": "list_packages", "one_liner": "Java packages in the index (optional project= filter)."},
+            {"name": "ping", "one_liner": "Verify the MCP server is alive."},
+        ],
+    },
+    {
+        "id": "tools_search",
+        "title": "Search & Lookup",
+        "tools": [
+            {"name": "search_hybrid", "one_liner": "Ranked symbol search (BM25 + vector + fuzzy via RRF). Start here."},
+            {"name": "find_symbol", "one_liner": "Exact/prefix name lookup. Use to resolve ambiguity or list overloads."},
+            {"name": "get_symbol_context", "one_liner": "One-shot deep context: search + impact + community + flows in one call."},
+            {"name": "get_neighborhood", "one_liner": "Callers, callees, siblings, and override/implements for a symbol."},
+        ],
+    },
+    {
+        "id": "tools_analysis",
+        "title": "Analysis",
+        "body": "Some analyses require 'analyse_project(path, deep=True)' to populate data.",
+        "tools": [
+            {"name": "get_impact", "one_liner": "Caller-tree impact analysis grouped by depth with confidence scores."},
+            {"name": "detect_dead_code", "one_liner": "Methods with no callers (Java-aware exemptions). strict=True for thorough audit."},
+            {"name": "trace_execution_flows", "one_liner": "Execution paths from entry points (main methods, tests, controllers)."},
+            {"name": "get_symbol_community", "one_liner": "Architectural community cluster a symbol belongs to."},
+            {"name": "get_change_coupling", "one_liner": "Files that historically change together (git co-change analysis)."},
+        ],
+    },
+    {
+        "id": "tools_git",
+        "title": "Git Integration",
+        "tools": [
+            {"name": "git_log", "one_liner": "Recent git commits for a project or a specific file."},
+            {"name": "git_diff", "one_liner": "Git diff (working tree vs ref, or between two refs)."},
+            {"name": "compare_branches", "one_liner": "Symbol-level diff between two git refs (branches/tags/commits)."},
+        ],
+    },
+    {
+        "id": "tools_indexing",
+        "title": "Indexing & Watch",
+        "tools": [
+            {"name": "analyse_project", "one_liner": "Index a Java project (background). Poll get_analyse_status() for progress."},
+            {"name": "get_analyse_status", "one_liner": "Status of current/recent background analysis job."},
+            {"name": "reindex_file", "one_liner": "Re-index a single .java file via overlay (<1 s)."},
+            {"name": "start_watch", "one_liner": "Watch a directory for .java changes; updates overlay in real time."},
+            {"name": "stop_watch", "one_liner": "Stop the background watch process."},
+            {"name": "get_watch_status", "one_liner": "Is watch mode running? Path, uptime."},
+        ],
+    },
+    {
+        "id": "tools_overlay",
+        "title": "Overlay (Dirty-State Tracking)",
+        "body": (
+            "The overlay tracks uncommitted file changes separately from the base index.\n"
+            "search_hybrid and find_symbol merge both layers automatically.\n"
+            "Deep analyses (dead code, flows, communities) use the committed base only."
+        ),
+        "tools": [
+            {"name": "get_overlay_status", "one_liner": "Uncommitted overlay state by project/module."},
+            {"name": "promote_overlay", "one_liner": "Commit dirty overlay into the base index immediately."},
+            {"name": "clear_overlay", "one_liner": "Discard dirty overlay without changing the base index."},
+        ],
+    },
+    {
+        "id": "tools_reset",
+        "title": "Index Reset",
+        "tools": [
+            {"name": "reset_project", "one_liner": "Remove all data for one project. Re-index with analyse_project()."},
+            {"name": "reset_index", "one_liner": "Remove ALL data across every project (clean slate)."},
+            {"name": "force_reset_index", "one_liner": "Emergency: delete data files when normal reset fails (OOM/corruption)."},
+        ],
+    },
+    {
+        "id": "tools_advanced",
+        "title": "Advanced",
+        "tools": [
+            {"name": "run_cypher", "one_liner": "Run a raw Cypher query against the graph DB."},
+        ],
+    },
+    # ── Workflows ─────────────────────────────────────────────────
+    {
+        "id": "workflows",
+        "title": "Common Workflows",
+        "body": (
+            "Understand a symbol:\n"
+            "  search_hybrid('PaymentService') -> get_impact('processPayment') -> get_neighborhood('processPayment')\n"
+            "\n"
+            "Find dead code:\n"
+            "  detect_dead_code(strict=True) -> get_impact(candidate) to verify each hit\n"
+            "\n"
+            "Review a branch:\n"
+            "  compare_branches('main', 'feature-x') -> get_impact() on each changed symbol\n"
+            "\n"
+            "Active development:\n"
+            "  analyse_project(path) -> start_watch(path) -> search/analyse as needed\n"
+            "\n"
+            "Explore architecture:\n"
+            "  list_packages() -> get_symbol_community(symbol) -> trace_execution_flows()"
+        ),
+    },
+    {
+        "id": "tips",
+        "title": "Tips",
+        "body": (
+            "- Most tools accept an optional project= parameter to scope results.\n"
+            "  Use list_projects() to see available project IDs.\n"
+            "- Multi-module projects use IDs like 'myapp::core', 'myapp::web'.\n"
+            "- get_symbol_context() is the best single call for understanding any symbol.\n"
+            "- For git tools, pass project= so the correct repo root is resolved.\n"
+            "- BM25 + fuzzy search works without embeddings. Semantic search needs\n"
+            "  'pip install codespine[ml]' and 'analyse_project(path, embed=True)'.\n"
+            "- If community/flow/coupling data is missing, re-run:\n"
+            "  analyse_project(path, deep=True)"
+        ),
+    },
+]
+
+
+def format_guide_terminal() -> str:
+    """Render GUIDE_SECTIONS as formatted terminal text."""
+    lines: list[str] = [f"CodeSpine v{__version__} -- Guide\n"]
+    for section in GUIDE_SECTIONS:
+        lines.append(f"{'=' * 64}")
+        lines.append(f"  {section['title']}")
+        lines.append(f"{'=' * 64}")
+        if "body" in section:
+            lines.append(section["body"])
+        if "tools" in section:
+            for t in section["tools"]:
+                lines.append(f"  {t['name']:<28} {t['one_liner']}")
+        lines.append("")
+    return "\n".join(lines)

{codespine-0.6.3 → codespine-0.7.1}/codespine/mcp/server.py

@@ -362,6 +362,22 @@ def build_mcp_server(store, repo_path_provider):
             "notes": notes,
         }
 
+    # ------------------------------------------------------------------
+    # Guide – static tool catalog + workflows for agents
+    # ------------------------------------------------------------------
+
+    @mcp.tool()
+    def guide():
+        """
+        How to use CodeSpine: system overview, tool catalog, recommended
+        workflows, and tips.  Call this FIRST if you have never used
+        CodeSpine before.  For live index state (what is indexed right now),
+        call get_capabilities() instead.
+        """
+        from codespine.guide import GUIDE_SECTIONS
+
+        return _json({"version": __version__, "sections": GUIDE_SECTIONS})
+
     # ------------------------------------------------------------------
     # Project listing
     # ------------------------------------------------------------------

{codespine-0.6.3 → codespine-0.7.1}/codespine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.6.3
+Version: 0.7.1
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -223,45 +223,134 @@ If the client launches the wrong Python environment, use the absolute binary pat
 }
 ```
 
-Common MCP tools:
+### Agent Onboarding
 
-- `search_hybrid(query, k, project)`
-- `find_symbol(name, kind, project, limit)`
-- `get_symbol_context(query, max_depth, project)`
-- `get_impact(symbol, max_depth, project)`
-- `detect_dead_code(limit, project, strict)`
-- `trace_execution_flows(entry_symbol, max_depth, project)`
-- `get_symbol_community(symbol)`
-- `get_change_coupling(months, min_strength, min_cochanges, project)`
-- `compare_branches(base_ref, head_ref)`
-- `get_codebase_stats()`
+When an agent connects to CodeSpine for the first time, it should call:
 
-## CLI
+1. **`guide()`** — returns a structured catalog of every tool, organized by category, with recommended workflows and tips.
+2. **`get_capabilities()`** — returns what is indexed right now, which features are ready, and what's missing.
 
-Core commands:
+The same information is available from the CLI:
 
 ```bash
-codespine analyse <path>
-codespine analyse <path> --full
-codespine analyse <path> --deep
-codespine analyse <path> --embed
-codespine watch --path .
-codespine watch --path . --overlay-debounce-ms 1500
-codespine search "query"
-codespine context "symbol"
-codespine impact "symbol"
-codespine deadcode
-codespine flow
-codespine community
-codespine coupling
-codespine diff main..feature
-codespine stats
-codespine list
-codespine overlay-status
-codespine overlay-promote
-codespine overlay-clear
-codespine clear-project <project_id>
-codespine clear-index
+codespine guide          # tool catalog, workflows, tips
+codespine guide --json   # structured JSON for tooling
+```
+
+### MCP Tools
+
+**Discovery & Status**
+
+| Tool | Description |
+|------|-------------|
+| `guide()` | Tool catalog, workflows, and tips. Call first if new to CodeSpine. |
+| `get_capabilities()` | What is indexed and which features are available right now. |
+| `list_projects()` | All indexed projects with symbol/file counts. |
+| `get_codebase_stats()` | Per-project stats: files, classes, methods, call edges, embeddings. |
+| `list_packages(project)` | Java packages in the index. |
+| `ping()` | Verify the MCP server is alive. |
+
+**Search & Lookup**
+
+| Tool | Description |
+|------|-------------|
+| `search_hybrid(query, k, project)` | Ranked symbol search (BM25 + vector + fuzzy via RRF). |
+| `find_symbol(name, kind, project, limit)` | Exact/prefix name lookup across all projects. |
+| `get_symbol_context(query, max_depth, project)` | One-shot deep context: search + impact + community + flows. |
+| `get_neighborhood(symbol, project)` | Callers, callees, siblings, and override/implements. |
+
+**Analysis**
+
+| Tool | Description |
+|------|-------------|
+| `get_impact(symbol, max_depth, project)` | Caller-tree impact analysis with confidence scores. |
+| `detect_dead_code(limit, project, strict)` | Methods with no callers (Java-aware exemptions). |
+| `trace_execution_flows(entry_symbol, max_depth, project)` | Execution paths from entry points. |
+| `get_symbol_community(symbol)` | Architectural community cluster for a symbol. |
+| `get_change_coupling(months, min_strength, min_cochanges)` | Files that historically change together. |
+
+**Git**
+
+| Tool | Description |
+|------|-------------|
+| `git_log(file_path, limit, project)` | Recent git commits. |
+| `git_diff(ref, file_path, project)` | Git diff (working tree vs ref, or between refs). |
+| `compare_branches(base_ref, head_ref, project)` | Symbol-level diff between two git refs. |
+
+**Indexing & Watch**
+
+| Tool | Description |
+|------|-------------|
+| `analyse_project(path, full, deep, embed)` | Index a Java project (background job). |
+| `get_analyse_status()` | Poll analysis progress. |
+| `reindex_file(file_path, project)` | Re-index a single `.java` file (<1 s). |
+| `start_watch(path)` | Watch for `.java` changes and update overlay in real time. |
+| `stop_watch()` | Stop the background watch process. |
+| `get_watch_status()` | Watch mode status: running, path, uptime. |
+
+**Overlay**
+
+| Tool | Description |
+|------|-------------|
+| `get_overlay_status(project)` | Uncommitted overlay state by project/module. |
+| `promote_overlay(project)` | Commit dirty overlay into the base index. |
+| `clear_overlay(project)` | Discard dirty overlay without changing the base. |
+
+**Reset**
+
+| Tool | Description |
+|------|-------------|
+| `reset_project(project_id)` | Remove all data for one project. |
+| `reset_index()` | Remove ALL data across every project. |
+| `force_reset_index()` | Emergency: delete data files when normal reset fails. |
+
+**Advanced**
+
+| Tool | Description |
+|------|-------------|
+| `run_cypher(query)` | Run a raw Cypher query against the graph DB. |
+
+## CLI
+
+```bash
+# Indexing
+codespine analyse <path>                     # incremental index
+codespine analyse <path> --full              # full re-index
+codespine analyse <path> --deep              # + communities, flows, dead code, coupling
+codespine analyse <path> --embed             # + vector embeddings
+codespine watch --path .                     # live re-index on file changes
+
+# Search & Analysis
+codespine search "query"                     # hybrid search
+codespine context "symbol"                   # one-shot deep context
+codespine impact "symbol"                    # caller-tree impact
+codespine deadcode                           # dead code candidates
+codespine flow                               # execution flows
+codespine community                          # architectural clusters
+codespine coupling                           # git change coupling
+codespine diff main..feature                 # symbol-level branch diff
+
+# Status & Info
+codespine stats                              # per-project statistics
+codespine list                               # indexed projects
+codespine status                             # service and database status
+codespine guide                              # tool catalog and workflows
+
+# Overlay
+codespine overlay-status                     # dirty overlay state
+codespine overlay-promote                    # commit overlay to base
+codespine overlay-clear                      # discard overlay
+
+# Server Management
+codespine start                              # launch background MCP server
+codespine stop                               # stop background MCP server
+codespine mcp                                # foreground MCP (stdio, for IDE)
+
+# Cleanup & Reset
+codespine clear-project <project_id>         # remove one project
+codespine clear-index                        # remove all indexed data
+codespine force-reset                        # emergency: delete all data files
+codespine setup                              # check dependencies
 ```
 
 `analyse` defaults to incremental mode. Repeat runs are designed to be fast when files have not changed.
@@ -323,8 +412,8 @@ Running `codespine analyse --deep --embed` on one project while querying a diffe
 - `codespine start` launches a background MCP server. Most IDE MCP clients should use `codespine mcp` instead and manage the process themselves.
 - `codespine watch` updates the dirty overlay first; it does not rewrite the committed base index on every save.
 - `codespine clear-index` rebuilds the local index database from scratch. This also removes the read replica; run `analyse` again to republish it.
+- `codespine force-reset` is the nuclear option — it deletes all data files without going through the DB engine. Use it when `clear-index` fails due to DB corruption.
 - For large Spring or JPA-heavy repos, dead-code results should still be reviewed before deletion. The tool is conservative, not authoritative.
-- The first run after upgrading to v0.5.7 will not have a read replica yet. Run `codespine analyse` once to create it.
 
 ## Project Docs
 

{codespine-0.6.3 → codespine-0.7.1}/codespine.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 codespine/__init__.py
 codespine/cli.py
 codespine/config.py
+codespine/guide.py
 codespine.egg-info/PKG-INFO
 codespine.egg-info/SOURCES.txt
 codespine.egg-info/dependency_links.txt

{codespine-0.6.3 → codespine-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codespine"
-version = "0.6.3"
+version = "0.7.1"
 description = "Local Java code intelligence indexer backed by a graph database"
 readme = "README.md"
 requires-python = ">=3.10"