opencode-codebase-index 0.7.0 → 0.8.1

package/README.md

@@ -56,10 +56,32 @@
 3. **Index your codebase**
    Run `/index` or ask the agent to index your codebase. This only needs to be done once — subsequent updates are incremental.
 
+   **Recommended check:** run `/status` after the first index so you can confirm the detected provider/model before you start searching.
+
 4. **Start Searching**
    Ask:
    > "Find the function that handles credit card validation errors"
 
+### Provider selection notes
+
+- **Default auto-detect order:** Ollama → GitHub Copilot → OpenAI → Google
+- **Ollama** is the preferred zero-cost local option and works especially well for large repos:
+
+  ```bash
+  ollama pull nomic-embed-text
+  ```
+
+  ```json
+  {
+    "embeddingProvider": "ollama"
+  }
+  ```
+
+- **GitHub Copilot** is a good default if OpenCode already has Copilot auth and you prefer hosted embeddings.
+- **OpenAI** is a good hosted option when you want predictable API behavior and standard cloud setup.
+- **Google** is available if you prefer Gemini-hosted embeddings.
+- If `/status` reports provider or compatibility problems, follow that guidance before using `/index force`.
+
 ## 🌐 MCP Server (Cursor, Claude Code, Windsurf, etc.)
 
 Use the same semantic search from any MCP-compatible client. Index once, search from anywhere.
@@ -189,7 +211,7 @@ graph TD
 
 1. **Parsing**: We use `tree-sitter` to intelligently parse your code into meaningful blocks (functions, classes, interfaces). JSDoc comments and docstrings are automatically included with their associated code.
 
-**Supported Languages (Tree-sitter semantic parsing)**: TypeScript, JavaScript, Python, Rust, Go, Java, C#, Ruby, PHP, Bash, C, C++, JSON, TOML, YAML
+**Supported Languages (Tree-sitter semantic parsing)**: TypeScript, JavaScript, Python, Rust, Go, Java, C#, Ruby, PHP, Apex, Bash, C, C++, JSON, TOML, YAML, Zig
 
 **Additional Supported Formats (line-based chunking)**: TXT, HTML, HTM, Markdown, Shell scripts
 
@@ -200,7 +222,8 @@ graph TD
 **/*.{rb,php,inc,swift}         **/*.{vue,svelte,astro}
 **/*.{sql,graphql,proto}        **/*.{yaml,yml,toml}
 **/*.{md,mdx}                   **/*.{sh,bash,zsh}
-**/*.{txt,html,htm}
+**/*.{txt,html,htm}              **/*.{cls,trigger}
+**/*.zig
 ```
 
 Use `include` to replace defaults, or `additionalInclude` to extend (e.g. `"**/*.pdf"`, `"**/*.csv"`).
@@ -292,7 +315,7 @@ The plugin exposes these tools to the OpenCode agent:
   ```
   [1] function "validatePayment" at src/billing.ts:45-67 (score: 0.92)
   [2] class "PaymentProcessor" at src/processor.ts:12-89 (score: 0.87)
-  
+
   Use Read tool to examine specific files.
   ```
 - **Workflow**: `codebase_peek` → find locations → `Read` specific files
@@ -315,6 +338,7 @@ Manually trigger indexing.
 
 ### `index_status`
 Checks if the index is ready and healthy.
+- **Recommended workflow**: run this after `/index` to confirm the detected provider/model and whether the index is ready to search.
 
 ### `index_health_check`
 Maintenance tool to remove stale entries from deleted files and orphaned embeddings/chunks from the database.
@@ -328,7 +352,9 @@ Returns recent debug logs with optional filtering.
 - **Parameters**: `category` (optional: `search`, `embedding`, `cache`, `gc`, `branch`), `level` (optional: `error`, `warn`, `info`, `debug`), `limit` (default: 50).
 
 ### `call_graph`
-Query the call graph to find callers or callees of a function/method. Automatically built during indexing for TypeScript, JavaScript, Python, Go, and Rust.
+
+Query the call graph to find callers or callees of a function/method. Automatically built during indexing for TypeScript, JavaScript, Python, Go, Rust, PHP, and Zig.
+
 - **Use for**: Understanding code flow, tracing dependencies, impact analysis.
 - **Parameters**: `name` (function name), `direction` (`callers` or `callees`), `symbolId` (required for `callees`, returned by previous queries).
 - **Example**: Find who calls `validateToken` → `call_graph(name="validateToken", direction="callers")`
@@ -353,10 +379,13 @@ The plugin automatically registers these slash commands:
 
 | Command | Description |
 | ------- | ----------- |
+| `/definition <query>` | **Definition Lookup**. Finds the authoritative implementation site for a symbol or concept. |
+| `/peek <query>` | **Quick Semantic Lookup**. Returns likely locations only, without full code content. |
+| `/reindex` | **Full Rebuild**. Rebuilds the codebase index from scratch. |
 | `/search <query>` | **Pure Semantic Search**. Best for "How does X work?" |
 | `/find <query>` | **Hybrid Search**. Combines semantic search + grep. Best for "Find usage of X". |
 | `/call-graph <query>` | **Call Graph Trace**. Find callers/callees to understand execution flow. |
-| `/index` | **Update Index**. Forces a refresh of the codebase index. |
+| `/index` | **Update Index**. Runs incremental indexing by default; use `/index force` for a full rebuild. |
 | `/status` | **Check Status**. Shows if indexed, chunk count, and provider info. |
 
 ## 📚 Knowledge Base
@@ -804,6 +833,8 @@ ollama pull nomic-embed-text
 
 The built-in `ollama` provider uses Ollama's native `/api/embeddings` endpoint and is the simplest setup when you want to use `nomic-embed-text`.
 
+For the built-in Ollama path, the plugin budgets `nomic-embed-text` against an observed effective input limit of about **2048 tokens**, not the model's higher advertised theoretical context. This keeps batching and chunk text generation aligned with real Ollama embedding runtime behavior.
+
 If you want to use a different Ollama embedding model through its OpenAI-compatible API, use the `custom` provider instead and set `customProvider.baseUrl` to `http://127.0.0.1:11434/v1` so the plugin calls `.../v1/embeddings`.
 
 ## 📈 Performance
@@ -912,7 +943,7 @@ Be aware of these characteristics:
      ]
    }
    ```
-   
+
    This loads directly from your source directory, so changes take effect after rebuilding.
 
 ## 🤝 Contributing
@@ -938,6 +969,7 @@ To ensure release notes reflect all merged work, this repo uses a draft-release
    - PRs are validated by CI (`Release Label Check`) and fail if no release category label is present
 2. **Let Release Drafter build the draft notes** automatically from merged PRs on `main`.
 3. **Before publishing**:
+   - compare `git log --oneline vX.Y.Z..HEAD` (or the previous release tag range) against the draft release notes so the release summary covers the full shipped delta, not just the current `CHANGELOG.md` `Unreleased` section
    - copy/finalize relevant highlights into `CHANGELOG.md`
    - bump `package.json` version
    - run: `npm run build && npm run typecheck && npm run lint && npm run test:run`
@@ -975,7 +1007,7 @@ The Rust native module handles performance-critical operations:
 - **usearch**: High-performance vector similarity search with F16 quantization
 - **SQLite**: Persistent storage for embeddings, chunks, branch catalog, symbols, and call edges
 - **BM25 inverted index**: Fast keyword search for hybrid retrieval
-- **Call graph extraction**: Tree-sitter query-based extraction of function calls, method calls, constructors, and imports (TypeScript/JavaScript, Python, Go, Rust)
+- **Call graph extraction**: Tree-sitter query-based extraction of function calls, method calls, constructors, and imports (TypeScript/JavaScript, Python, Go, Rust, PHP, Zig)
 - **xxhash**: Fast content hashing for change detection
 
 Rebuild with: `npm run build:native` (requires Rust toolchain)

package/commands/index.md

@@ -21,3 +21,7 @@ Examples:
 IMPORTANT: You MUST pass the parsed arguments to `index_codebase`. Do not ignore them.
 
 Show final statistics including files processed, chunks indexed, tokens used, and duration.
+
+If indexing completes but the codebase still is not ready, tell the user to run `/status` next.
+- If `/status` reports failed embedding batches, fix the provider/auth issue and rerun `/index` normally.
+- Use `/index force` only for a full rebuild or when `/status` reports provider/model incompatibility.

package/commands/peek.md

@@ -0,0 +1,24 @@
+---
+description: Quickly find likely code locations without returning full code
+---
+
+Search the codebase using `codebase_peek`.
+
+User input: $ARGUMENTS
+
+The first part is the search query. Look for optional parameters:
+- `limit=N` or "top N" or "first N" → set limit
+- `type=X` or mentions "functions"/"classes"/"methods" → set chunkType
+- `dir=X` or "in folder X" → set directory filter
+- File extensions like ".ts", "typescript", ".py" → set fileType
+
+Call `codebase_peek` with the parsed arguments.
+
+Examples:
+- `/peek authentication logic` → query="authentication logic"
+- `/peek error handling limit=5` → query="error handling", limit=5
+- `/peek validation functions` → query="validation", chunkType="function"
+
+If the index doesn't exist, run `index_codebase` first.
+
+Return results as concise locations with file paths and line numbers. Suggest reading the returned files or using `codebase_search` when the user needs full code context.

package/commands/reindex.md

@@ -0,0 +1,25 @@
+---
+description: Fully rebuild the codebase index from scratch
+---
+
+Run the `index_codebase` tool with `force=true` to rebuild the index from scratch.
+
+User input: $ARGUMENTS
+
+Parse the input and set tool arguments:
+- force=true always
+- estimateOnly=false always
+- verbose=false (default, for token efficiency)
+- verbose=true if input contains "verbose" (for detailed output)
+
+Examples:
+- `/reindex` → force=true, estimateOnly=false, verbose=false
+- `/reindex verbose` → force=true, estimateOnly=false, verbose=true
+
+IMPORTANT: You MUST call `index_codebase` with `force=true`.
+
+Show final statistics including files processed, chunks indexed, tokens used, and duration.
+
+If indexing completes but the codebase still is not ready, tell the user to run `/status` next.
+- If `/status` reports failed embedding batches, fix the provider/auth issue and rerun `/index` normally.
+- If `/status` reports provider/model incompatibility again after a rebuild, surface that clearly as an unexpected issue.

package/commands/status.md

@@ -9,7 +9,11 @@ This shows:
 - Number of indexed chunks
 - Embedding provider and model being used
 - Current git branch
+- Failed embedding batches or compatibility warnings that explain why search is not ready
 
 No arguments needed - just run `index_status`.
 
-If not indexed, suggest running `/index` to create the index.
+If not indexed:
+- suggest running `/index` when no index exists yet
+- if status reports failed embedding batches, tell the user to fix the provider/auth issue and rerun `/index` normally
+- if status reports provider/model incompatibility, tell the user to run `/index force` for a full rebuild