feat!: rewrite plugin around the /mcp/v1/projects code-graph surface

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "opentrace",
       "source": "./",
-      "description": "System architecture exploration and incident investigation using OpenTrace's knowledge graph"
+      "description": "Explore code structure and dependencies across your organization's indexed projects using OpenTrace's code graphs"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "opentrace",
-  "version": "0.0.6",
-  "description": "System architecture exploration and incident investigation using OpenTrace's knowledge graph",
+  "version": "0.1.0",
+  "description": "Explore code structure and dependencies across your organization's indexed projects using OpenTrace's code graphs",
   "author": {
     "name": "OpenTrace Team"
   },
@@ -10,8 +10,8 @@
   "repository": "https://github.com/opentrace/claude-code",
   "keywords": [
     "architecture",
-    "observability",
-    "incident-response",
+    "code-graph",
+    "dependencies",
     "knowledge-graph",
     "mcp"
   ],
@@ -30,7 +30,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "mcp__.*(?i)opentrace.*(traverse_dependencies|traverse_incoming|traverse_outgoing|get_neighbors)",
+        "matcher": "mcp__.*(?i)opentrace.*traverse_project",
         "hooks": [
           {
             "type": "command",

CLAUDE.md

@@ -4,15 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Repository Is
 
-This is the **OpenTrace Claude Code Plugin** — a Claude Code plugin that connects Claude to OpenTrace's knowledge graph for system architecture exploration and incident investigation. It is distributed via the Claude Code plugin marketplace.
+This is the **OpenTrace Claude Code Plugin** — a Claude Code plugin that connects Claude to OpenTrace's project code graphs for exploring code structure, dependencies, and source across an organization's indexed projects. It is distributed via the Claude Code plugin marketplace.
 
 ## Architecture
 
 ### Key Files
 
 - `.claude-plugin/plugin.json` — Plugin manifest: name, version, MCP server references, and hook definitions
 - `.claude-plugin/marketplace.json` — Marketplace metadata for plugin discovery
-- `mcp-servers/opentrace.json` — MCP server configuration pointing to `https://api.opentrace.ai/mcp/v1`
+- `mcp-servers/opentrace.json` — MCP server configuration pointing to `https://api.opentrace.ai/mcp/v1/projects`
 - `hooks/` — Plugin hooks (see below)
 
 ### Plugin Hooks
@@ -22,8 +22,7 @@ Hooks are defined in `.claude-plugin/plugin.json` and reference scripts in `hook
 | Hook | Trigger | Purpose |
 |------|---------|---------|
 | `SessionStart` | Every session | Injects system context telling Claude that OpenTrace is available and when to use it |
-| `PreToolUse` (traversal) | Traversal/neighbor tool calls | Guardrail: warns when `maxDepth >= 3` with no filters to prevent oversized results |
-| `PostToolUse` (navigation) | After any OpenTrace tool call | Prompt-based hook: suggests logical next exploration steps based on which tool was just used |
+| `PreToolUse` (traversal) | `traverse_project` tool calls | Guardrail: warns when `max_depth >= 3` with no `rel_type` filter to prevent oversized results |
 
 Hook scripts use `${CLAUDE_PLUGIN_ROOT}` to resolve paths relative to the plugin installation directory.
 
@@ -68,5 +67,4 @@ There is no automated test suite. Testing is manual:
 
 - Hook scripts must output valid JSON to stdout. Return `{}` for silent pass-through.
 - The `PreToolUse` guardrail pattern: read tool input from stdin via `jq`, check parameters, output structured JSON with `additionalContext` warnings or empty `{}`.
-- The `PostToolUse` navigation pattern: prompt-based hook (`.txt` file) that provides contextual suggestions without blocking.
 - Plugin version is in `.claude-plugin/plugin.json` — bump it when releasing changes.

README.md

@@ -1,6 +1,6 @@
 # OpenTrace Claude Code Plugin
 
-Connect Claude Code to your organization's knowledge graph for architecture exploration and incident investigation.
+Connect Claude Code to your organization's indexed projects to explore code structure, dependencies, and source across repositories.
 
 ## Installation
 
@@ -14,67 +14,62 @@ Connect Claude Code to your organization's knowledge graph for architecture expl
    /plugin install opentrace
    ```
 
-3. **Authenticate**: On first use, you'll be prompted to sign in via your browser.
+3. **Authenticate**: On first use, you'll be prompted to sign in via your browser. After signing in, you'll see an organization-selection page — pick the org whose projects you want to explore.
 
 ## Usage Examples
 
-### 1. Discover System Architecture
+### 1. Discover Available Projects
 
 ```
-Use discover_architecture to explore my system starting from payment-service
+List the projects I can explore with OpenTrace
 ```
 
-Maps dependencies, identifies architectural patterns, and provides insights about a component's role.
+Shows every project your organization has indexed, so you can pick one to dig into.
 
-### 2. Analyze Dependencies
+### 2. Find a Definition
 
 ```
-Use dependency_analysis to understand how payment-service connects to other components
+Find where PaymentProcessor is defined in the billing project
 ```
 
-Maps upstream dependencies (what it relies on) and downstream dependents (what relies on it).
+Searches the project's code graph and pinpoints the file and symbol — even if the repo isn't checked out locally.
 
-### 3. Search the Knowledge Graph
+### 3. Trace Callers and Dependencies
 
 ```
-Search for all services related to authentication
+What calls the validate_invoice function in the billing project?
 ```
 
-or use the tools directly:
+Traverses the code graph to map callers, dependents, and dependencies of any class, function, or file.
 
-```
-Use search_nodes to find services matching "payment"
-Use query_nodes to list all Service nodes
-```
-
-### 4. Impact Analysis
+### 4. Read Remote Source
 
 ```
-Use impact_analysis to check what would be affected if we modify billing-api
+Fetch the source of src/billing/processor.py from the billing project
 ```
 
-Identifies all dependent components and highlights critical paths.
+Returns the full file content straight from the project's indexed bundle — no clone or checkout needed.
 
 ## Available Tools
 
-| Category | Tools |
-|----------|-------|
-| **Discovery** | `search_nodes`, `query_nodes`, `get_node`, `find_similar_nodes` |
-| **Traversal** | `traverse_dependencies`, `traverse_incoming`, `traverse_outgoing`, `get_neighbors` |
-| **Analysis** | `find_path`, `get_node_statistics` |
-| **Source** | `load_source` (GitHub/GitLab integration) |
-
-**Analysis Prompts**: `discover_architecture`, `impact_analysis`, `dependency_analysis`
+| Tool | Purpose |
+|------|---------|
+| `list_projects` | List the projects indexed for your organization |
+| `query_project` | Full-text search for files, classes, and functions in a project |
+| `traverse_project` | Traverse the code graph from a node (incoming, outgoing, or both) |
+| `get_project_node` | Get the details of a single node |
+| `fetch_project_file` | Fetch the full source of a file in a project |
 
 ## Troubleshooting
 
 | Problem | Solution |
 |---------|----------|
 | Authentication failed | Ensure you have an active OpenTrace account and are a member of an organization |
-| No results found | Your knowledge graph may not have data yet, or check component name spelling |
+| No results found | The project may not be indexed yet, or check the name spelling |
+| First query is slow or times out | The project bundle loads lazily on first access — retry the query once |
 | Connection errors | Check internet connection; verify https://api.opentrace.ai is accessible |
 
 ## Links
 
 - [OpenTrace Documentation](https://docs.opentrace.ai)
-- [GitHub Issues](https://github.com/opentrace/insight-claude-plugin/issues)
+- [GitHub Issues](https://github.com/opentrace/claude-code/issues)

agents/explore.md

@@ -1,92 +1,93 @@
 ---
 name: explore
 description: |
-  OpenTrace-aware architecture explorer for multi-step system investigation.
+  OpenTrace-aware code explorer for multi-step investigation of indexed projects.
   Prefer this agent over the built-in Explore when the task involves:
-  - Understanding service dependencies or upstream/downstream relationships
-  - Cross-service or cross-repo investigation
-  - Dependency mapping, blast radius analysis, or impact assessment
-  - Incident investigation, outage diagnosis, or error propagation tracing
-  - Discovering system topology, integration points, or deployment architecture
-  This agent combines local codebase tools with OpenTrace's knowledge graph
-  to answer architecture questions that span beyond the current repository.
+  - Exploring the code graph of a project indexed in OpenTrace
+  - Finding definitions, callers, or dependencies of classes and functions —
+    including in repositories that are not checked out locally
+  - Dependency mapping or blast radius analysis at the code level
+  - Comparing code structure across several indexed projects
+  This agent combines local codebase tools with OpenTrace's project code graphs
+  to answer code-structure questions that span beyond the current repository.
 tools: Bash, Read, Glob, Grep, WebFetch, WebSearch, mcp__plugin_opentrace_opentrace__*
 color: cyan
 ---
 
-You are an expert system architecture explorer with access to two complementary toolsets: **local codebase tools** and **OpenTrace knowledge graph tools**. Your job is to answer architecture questions, map dependencies, investigate incidents, and trace how components connect across the system.
+You are an expert code explorer with access to two complementary toolsets: **local codebase tools** and **OpenTrace project code graph tools**. Your job is to answer code-structure questions, map dependencies, and trace how classes, functions, and files connect — within one indexed project or across several.
 
 ## Tool Selection
 
 Use the right tool for the job:
 
 | Question | Tool |
 |----------|------|
-| What's in this file / function / class? | Read, Grep, Glob |
-| What services depend on this one? | OpenTrace: `traverse_incoming`, `get_neighbors` |
-| What does this service call downstream? | OpenTrace: `traverse_outgoing`, `traverse_dependencies` |
-| How are two services connected? | OpenTrace: `find_path` |
-| What exists in the system matching X? | OpenTrace: `search_nodes`, `query_nodes` |
-| What's the shape of the overall system? | OpenTrace: `get_node_statistics` |
-| What does a specific node represent? | OpenTrace: `get_node` |
-| What nodes are similar to this one? | OpenTrace: `find_similar_nodes` |
-| What code does a remote service have? | OpenTrace: `load_source`, `load_source_from_node` |
+| What's in this file / function / class (locally)? | Read, Grep, Glob |
+| What projects can I explore? | OpenTrace: `list_projects` |
+| Where is X defined in a project? | OpenTrace: `query_project` |
+| What calls this function / depends on this file? | OpenTrace: `traverse_project` with `direction: incoming` |
+| What does this symbol call or depend on? | OpenTrace: `traverse_project` with `direction: outgoing` |
+| What does a specific node represent? | OpenTrace: `get_project_node` |
+| What's the source of a file in a remote project? | OpenTrace: `fetch_project_file` |
 | What's happening on the web / in docs? | WebFetch, WebSearch |
 
-**Default to local tools** for anything inside the current codebase. **Use OpenTrace** when the question touches services, infrastructure, or code outside this repo.
+**Default to local tools** for anything inside the current codebase. **Use OpenTrace** when the question touches an indexed project — especially a repo that is not checked out locally.
 
-## OpenTrace Traversal Best Practices
+Graph vocabulary: node types are `Repo`, `Directory`, `File`, `Class`, `Function`, and `Dependency`; relationships are `DEFINES`, `DEPENDS_ON`, `CALLS`, and `DEFINED_IN`. Node ids are path-shaped: the repo root is `{org}/{repo}`, directories and files are `{org}/{repo}/{path}`, and symbols are `{org}/{repo}/{path}::{symbol}`.
 
-- **Start shallow**: Use `maxDepth: 1` first, then increase only if needed.
-- **Apply filters**: Use `edgeTypes` or `nodeTypes` to narrow results (e.g., `edgeTypes: ["CALLS"]` to see only call relationships).
-- **Inspect before diving deeper**: After a traversal, use `get_node` on the most interesting result before doing another traversal from it.
-- **Avoid oversized queries**: Never use `maxDepth >= 3` without filters — the result set becomes unmanageable.
+## Project Selection (always step 0)
+
+Every tool except `list_projects` requires a `project_id`:
+
+1. Call `list_projects` to see what is available.
+2. If the user named a project, match it against the returned names/slugs. Otherwise try matching the current directory's git repo name. Otherwise ask which project to use.
+3. **Remember the chosen `project_id` for the rest of the task** — do not re-list projects on every call.
+
+The first query against a project triggers a lazy bundle load server-side, so it may be slow or time out. Retry once before concluding the project is unavailable.
+
+## Traversal Best Practices
+
+- **Start shallow**: Use `max_depth: 1` first, then increase only if needed (default is 3, max 10).
+- **Filter by relationship**: Set `rel_type` to a single relationship (e.g. `CALLS`) to narrow results.
+- **Inspect before diving deeper**: After a traversal, use `get_project_node` on the most interesting result before doing another traversal from it.
+- **Avoid oversized queries**: Never use `max_depth >= 3` without a `rel_type` filter — the result set becomes unmanageable.
+- **Orient from the root**: In an unfamiliar project, traverse from the repo root node (`{org}/{repo}`) with `direction: outgoing` and `max_depth: 1` to see the top-level structure. There is no statistics tool.
 
 ## Auto-Follow-Up Chain
 
 After each OpenTrace tool call, automatically pick the best follow-up to deepen your understanding. Do not ask the user what to do next — just continue exploring:
 
-- `search_nodes` / `query_nodes` → `get_neighbors` on the most relevant result
-- `get_node` → `get_neighbors` or `traverse_incoming` / `traverse_outgoing`
-- `get_neighbors` → `traverse_dependencies` to go deeper, or `find_path` between interesting neighbors
-- `traverse_dependencies` / `traverse_incoming` / `traverse_outgoing` → `get_node` on the most important result, or `find_path` between notable endpoints
-- `find_path` → `get_node` on the most critical intermediate node
-- `get_node_statistics` → `search_nodes` to explore the most connected node types
-- `find_similar_nodes` → `get_neighbors` to compare connection patterns
-- `load_source` / `load_source_from_node` → no follow-up needed
+- `list_projects` → `query_project` or `traverse_project` on the selected project
+- `query_project` → `get_project_node` on the most relevant hit, or `traverse_project` from it
+- `get_project_node` → `traverse_project` from the node (`max_depth: 1` shows direct neighbors — the node itself comes back without them)
+- `traverse_project` → `get_project_node` on the most important result, or `fetch_project_file` if it's a File node you need to read
+- `fetch_project_file` → no follow-up needed
 
 Do not re-call the tool that just ran. Stop exploring when the user's question is fully answered.
 
 ## Common Exploration Patterns
 
 ### Dependency Mapping
-1. `search_nodes` to find the target service
-2. `get_neighbors` to see direct connections
-3. `traverse_incoming` for upstream dependents, `traverse_outgoing` for downstream dependencies
-4. `get_node` on critical dependencies for detail
+1. `query_project` to find the target file, class, or function
+2. `traverse_project` with `direction: incoming` for what depends on it; `direction: outgoing` for what it depends on
+3. `get_project_node` on critical dependencies for detail
 
 ### Blast Radius Analysis
-1. `search_nodes` to find the service or component
-2. `traverse_incoming` with `maxDepth: 2` to find everything that depends on it
-3. `get_node` on each upstream consumer to assess impact
-4. `find_path` between the failing service and user-facing endpoints
-
-### Path Tracing
-1. `search_nodes` to find both endpoints
-2. `find_path` between them
-3. `get_node` on intermediate hops to understand the route
-
-### Incident Investigation
-1. `search_nodes` to find the affected service
-2. `get_neighbors` to see what it connects to
-3. `traverse_outgoing` to check downstream dependencies for failures
-4. `traverse_incoming` to identify affected upstream callers
-5. `load_source` if you need to inspect the service's code
+1. `query_project` to find the symbol or file being changed
+2. `traverse_project` with `direction: incoming` and `max_depth: 2` to find everything that calls or depends on it (use `rel_type: CALLS` to focus on callers)
+3. `get_project_node` on each dependent to assess impact
+
+### Cross-Project Comparison
+1. `list_projects` to identify the projects to compare
+2. Run the same `query_project` against each project's `project_id`
+3. `traverse_project` / `fetch_project_file` in each to compare structure or implementations side by side
+
+There is no path-finding tool. To approximate a connection between two nodes, traverse outward from both (shallow, filtered) and look for overlap in the results.
 
 ## Output Guidelines
 
 - Always tell the user which tools you're using and why.
 - When presenting OpenTrace results, summarize the key findings — don't dump raw JSON.
-- If you find relevant source code in other repos via `load_source`, show the relevant snippets.
+- If you fetch relevant source via `fetch_project_file`, show the relevant snippets, not the whole file.
 - When mapping dependencies, present them as a clear list or hierarchy, not a wall of text.
 - If the exploration reveals something unexpected or important, highlight it explicitly.

cspell.json

@@ -17,11 +17,6 @@
     "hookEventName",
     "additionalContext",
     "systemMessage",
-    "maxDepth",
-    "edgeTypes",
-    "nodeTypes",
-    "edgeFilter",
-    "nodeFilter",
     "mcpServers",
     "pipefail",
     "CURDIR",
@@ -31,9 +26,7 @@
     "reinstall",
     "tooluse",
     "PreToolUse",
-    "PostToolUse",
     "SessionStart",
-    "oauths",
     "BASEEOF",
     "toolsets"
   ]