codespine 0.7.0__tar.gz → 0.7.2__tar.gz

{codespine-0.7.0 → codespine-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.7.0
+Version: 0.7.2
 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.7.0 → codespine-0.7.2}/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.7.0 → codespine-0.7.2}/codespine/__init__.py

@@ -1,4 +1,4 @@
 """CodeSpine package."""
 
 __all__ = ["__version__"]
-__version__ = "0.7.0"
+__version__ = "0.7.2"

{codespine-0.7.0 → codespine-0.7.2}/codespine/analysis/coupling.py

@@ -9,7 +9,7 @@ from codespine.config import SETTINGS
 from codespine.indexer.symbol_builder import file_id
 
 
-def _git_changed_file_sets(repo_path: str, months: int) -> list[set[str]]:
+def _git_changed_file_sets(repo_path: str, days: int) -> list[set[str]]:
     cmd = [
         "git",
         "-C",
@@ -17,7 +17,7 @@ def _git_changed_file_sets(repo_path: str, months: int) -> list[set[str]]:
         "log",
         "--name-only",
         "--pretty=format:__COMMIT__",
-        f"--since={months}.months",
+        f"--since={days}.days",
     ]
     proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
     if proc.returncode != 0:
@@ -43,7 +43,7 @@ def compute_coupling(
     store,
     repo_path: str,
     project_id: str,
-    months: int = SETTINGS.default_coupling_months,
+    days: int = SETTINGS.default_coupling_days,
     min_strength: float = SETTINGS.default_min_coupling_strength,
     min_cochanges: int = SETTINGS.default_min_cochanges,
     progress=None,
@@ -53,7 +53,7 @@ def compute_coupling(
             progress(msg)
 
     _ping("reading git history")
-    changesets = _git_changed_file_sets(repo_path, months)
+    changesets = _git_changed_file_sets(repo_path, days)
     if not changesets:
         return []
 
@@ -77,7 +77,7 @@ def compute_coupling(
 
         aid = file_id(project_id, a)
         bid = file_id(project_id, b)
-        store.upsert_coupling(aid, bid, strength, pair_count, months)
+        store.upsert_coupling(aid, bid, strength, pair_count, days)
         results.append(
             {
                 "file_a": a,
@@ -91,7 +91,7 @@ def compute_coupling(
     return results
 
 
-def get_coupling(store, symbol: str | None = None, months: int = 6, min_strength: float = 0.3, min_cochanges: int = 3) -> dict:
+def get_coupling(store, symbol: str | None = None, days: int = 5, min_strength: float = 0.3, min_cochanges: int = 3) -> dict:
     if symbol:
         recs = store.query_records(
             """
@@ -113,13 +113,13 @@ def get_coupling(store, symbol: str | None = None, months: int = 6, min_strength
     recs = store.query_records(
         """
         MATCH (f:File)-[r:CO_CHANGED_WITH]-(f2:File)
-        WHERE r.months = $months AND r.strength >= $min_strength AND r.cochanges >= $min_cochanges
+        WHERE r.days = $days AND r.strength >= $min_strength AND r.cochanges >= $min_cochanges
         RETURN f.path as file, f2.path as coupled_file, r.strength as strength, r.cochanges as cochanges
         ORDER BY strength DESC, cochanges DESC
         LIMIT 500
         """,
         {
-            "months": months,
+            "days": days,
             "min_strength": min_strength,
             "min_cochanges": min_cochanges,
         },

{codespine-0.7.0 → codespine-0.7.2}/codespine/cli.py

@@ -314,7 +314,7 @@ def analyse(path: str, full: bool, deep: bool, embed: bool, allow_running: bool)
             store,
             coupling_root,
             coupling_project,
-            months=SETTINGS.default_coupling_months,
+            days=SETTINGS.default_coupling_days,
             min_strength=SETTINGS.default_min_coupling_strength,
             min_cochanges=SETTINGS.default_min_cochanges,
             progress=lambda s: _live_phase(coup_label, s),
@@ -467,20 +467,20 @@ def community(symbol: str | None, as_json: bool) -> None:
 
 
 @main.command()
-@click.option("--months", default=6, show_default=True, type=int)
+@click.option("--days", default=5, show_default=True, type=int)
 @click.option("--min-strength", default=0.3, show_default=True, type=float)
 @click.option("--min-cochanges", default=3, show_default=True, type=int)
 @click.option("--json", "as_json", is_flag=True)
-def coupling(months: int, min_strength: float, min_cochanges: int, as_json: bool) -> None:
+def coupling(days: int, min_strength: float, min_cochanges: int, as_json: bool) -> None:
     """Compute and query git change coupling."""
     store = GraphStore(read_only=False)
     project = store.query_records("MATCH (p:Project) RETURN p.id as id LIMIT 1")
     project_id = project[0]["id"] if project else os.path.basename(os.getcwd())
-    compute_coupling(store, os.getcwd(), project_id, months=months, min_strength=min_strength, min_cochanges=min_cochanges)
+    compute_coupling(store, os.getcwd(), project_id, days=days, min_strength=min_strength, min_cochanges=min_cochanges)
     result = get_coupling(
         store,
         symbol=None,
-        months=months,
+        days=days,
         min_strength=min_strength,
         min_cochanges=min_cochanges,
     )

{codespine-0.7.0 → codespine-0.7.2}/codespine/config.py

@@ -18,7 +18,7 @@ class Settings:
     write_batch_size: int = 500
     index_file_batch_size: int = 20
     edge_write_batch_size: int = 500
-    default_coupling_months: int = 6
+    default_coupling_days: int = 5
     default_min_coupling_strength: float = 0.3
     default_min_cochanges: int = 3
     default_global_interval_s: int = 30

{codespine-0.7.0 → codespine-0.7.2}/codespine/db/store.py

@@ -648,18 +648,18 @@ class GraphStore:
                     )
             self._recycle_conn()
 
-    def upsert_coupling(self, file_a: str, file_b: str, strength: float, cochanges: int, months: int) -> None:
+    def upsert_coupling(self, file_a: str, file_b: str, strength: float, cochanges: int, days: int) -> None:
         self.execute(
             """
             MATCH (a:File {id: $a}), (b:File {id: $b})
-            MERGE (a)-[:CO_CHANGED_WITH {strength: $strength, cochanges: $cochanges, months: $months}]->(b)
+            MERGE (a)-[:CO_CHANGED_WITH {strength: $strength, cochanges: $cochanges, days: $days}]->(b)
             """,
             {
                 "a": file_a,
                 "b": file_b,
                 "strength": strength,
                 "cochanges": int(cochanges),
-                "months": int(months),
+                "days": int(days),
             },
         )
 

{codespine-0.7.0 → codespine-0.7.2}/codespine/guide.py

@@ -60,7 +60,7 @@ GUIDE_SECTIONS: list[dict] = [
             {"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)."},
+            {"name": "get_change_coupling", "one_liner": "Files that changed together in the last N days (default 5). git co-change analysis."},
         ],
     },
     {

{codespine-0.7.0 → codespine-0.7.2}/codespine/mcp/server.py

@@ -522,15 +522,15 @@ def build_mcp_server(store, repo_path_provider):
     @mcp.tool()
     def get_change_coupling(
         symbol: str | None = None,
-        months: int = 6,
+        days: int = 5,
         min_strength: float = 0.3,
         min_cochanges: int = 3,
     ):
         """
-        Files that historically change together (git co-change coupling).
+        Files that changed together in the last N days (git co-change coupling).
         Requires 'codespine analyse --deep' to have been run.
         """
-        result = get_coupling(store, symbol=symbol, months=months, min_strength=min_strength, min_cochanges=min_cochanges)
+        result = get_coupling(store, symbol=symbol, days=days, min_strength=min_strength, min_cochanges=min_cochanges)
         if not result:
             return {
                 "available": False,

{codespine-0.7.0 → codespine-0.7.2}/codespine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.7.0
+Version: 0.7.2
 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.7.0 → codespine-0.7.2}/pyproject.toml

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