@comfanion/usethis_search 4.3.0-dev.4 → 4.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comfanion/usethis_search",
-  "version": "4.3.0-dev.4",
-  "description": "OpenCode plugin: semantic search with context-efficient workspace state (v4.3: no injection, each tool returns full state inline, auto-prune history, auto-detect modes, line numbers, LSP memory leak fixed)",
+  "version": "4.3.1",
+  "description": "OpenCode plugin: semantic search with context-efficient workspace state (v4.3.1: improved tool description - chunks contain direct file content, no verification needed)",
   "type": "module",
   "main": "./index.ts",
   "exports": {

package/tools/search.ts

@@ -179,30 +179,52 @@ function parseFilter(filter: string): {
 }
 
 export default tool({
-  description: `Search codebase and automatically attach relevant context to workspace.
-
-Accepts any query - semantic search, file path, or chunk ID:
-- "authentication logic" → finds relevant code
-- "docs/architecture.md" → attaches file
-- "src/auth.ts:chunk-5" → attaches specific chunk
-
-Results are optimized for context - top chunks auto-attached with expanded context 
-(related code, imports, class methods). Returns full workspace state inline.
-Previous search outputs are automatically pruned from history.
-
-IMPORTANT: Workspace has limited token budget. Use workspace_forget() to remove 
-irrelevant files or old searches before adding new context.
-
-Choose index based on what you're looking for:
-- index: "code" → search source code
-- index: "docs" → search documentation  
-- searchAll: true → search everywhere
+  description: `Search the codebase semantically. Use this to find relevant code snippets, functions, or files based on meaning, not just text matching.
+
+Available indexes:
+- "code" (default) - Source code files (*.js, *.ts, *.py, *.go, etc.)
+- "docs" - Documentation files (*.md, *.txt, etc.)
+- "config" - Configuration files (*.yaml, *.json, etc.)
+- searchAll: true - Search across all indexes
+
+Auto-detects query type:
+- Semantic: "authentication logic" → vector search for relevant code
+- File path: "docs/architecture.md" → attaches entire file to workspace
+- Chunk ID: "src/auth.ts:chunk-5" → attaches specific chunk
+
+How workspace works:
+- Top results are AUTO-ATTACHED to workspace with expanded context (class methods, imports, related code via graph)
+- Workspace has a TOKEN BUDGET (~50K tokens, ~100 chunks). When full, oldest chunks are evicted
+- Each search call returns full <workspace_state> with all chunk contents inline
+- Only the LATEST search/workspace output is kept in chat history — older ones are auto-pruned
+- Workspace persists across searches — new results ADD to existing workspace
+
+IMPORTANT: Chunks contain DIRECT file content dumps (raw code/text from files).
+- You DO NOT need to verify chunk content with grep/read tools
+- Chunks are already the actual file content, not summaries or references
+- Trust the chunk content as the source of truth
+- Use Read tool only if you need content OUTSIDE the indexed chunks
+
+Context management:
+- BEFORE searching a new topic, use workspace_forget() to remove irrelevant old context
+- Use workspace_clear() when switching to a completely different task
+- The workspace is your working memory — keep it focused on the current task
+
+Filter narrows results by path or language:
+- "internal/domain/" → only files under that path
+- "*.go" → only Go files
+- "internal/**/*.go" → path + language combined
+- "service" → files containing "service" in path
 
 Examples:
 - search({ query: "authentication logic" })
 - search({ query: "how to deploy", index: "docs" })
-- search({ query: "docs/prd.md" })  // attach file
-- search({ query: "internal/domain/", filter: "*.go" })`,
+- search({ query: "tenant management", filter: "internal/domain/" })
+- search({ query: "event handling", filter: "*.go" })
+- search({ query: "API routes", filter: "internal/**/*.go" })
+- search({ query: "metrics", searchAll: true })
+- search({ query: "docs/prd.md" })
+- search({ query: "src/auth.ts:chunk-5" })`,
 
   args: {
     query: tool.schema.string().describe("What to search: semantic query, file path, or chunk ID"),

package/tools/workspace.ts

@@ -20,7 +20,15 @@ import { buildWorkspaceOutput } from "./workspace-state.ts"
 // ── workspace.list ──────────────────────────────────────────────────────────
 
 export const workspace_list = tool({
-  description: `Show full workspace state with all chunk content. Returns file listing and inline content for every attached chunk.`,
+  description: `Show current workspace contents — all attached code chunks with full source code, line numbers, and metadata.
+
+Use this to:
+- Check what context is currently loaded after compaction or session restore
+- Verify workspace contents before starting implementation
+- See token budget usage (how much space is left for new searches)
+
+Returns <workspace_state> with every chunk's full content. This is the same state appended to every search() call.
+Only the LATEST workspace tool output is kept in chat — older outputs are auto-pruned.`,
 
   args: {},
 
@@ -32,21 +40,26 @@ export const workspace_list = tool({
 // ── workspace.forget ────────────────────────────────────────────────────────
 
 export const workspace_forget = tool({
-  description: `Remove chunks from workspace context to optimize context size and focus.
+  description: `Remove chunks from workspace to free token budget and keep context focused on the current task.
 
-IMPORTANT: Regularly clean up workspace by removing irrelevant files or old search results. 
-This keeps context focused and prevents token budget overflow.
+WHEN TO USE:
+- Before searching a new topic — remove old irrelevant context first
+- When workspace is near budget limit — free space for new results
+- After finishing a subtask — remove code you no longer need
+- When context has stale chunks from files you've since edited
 
-Auto-detects what to remove based on input:
-- Chunk ID: "src/auth.ts:chunk-5"
-- File path: "docs/architecture.md" (removes ALL chunks)
-- Search query: "authentication logic" (removes chunks from this search)
-- Age: "5" (removes chunks older than 5 minutes)
+Auto-detects what to remove based on input format:
+- File path: "docs/architecture.md" → removes ALL chunks from that file
+- Chunk ID: "src/auth.ts:chunk-5" → removes one specific chunk
+- Search query: "authentication logic" → removes all chunks attached by that search
+- Age in minutes: "5" → removes all chunks older than 5 minutes
 
-Examples:
-- workspace_forget({ what: "docs/prd.md" })
-- workspace_forget({ what: "5" })  // older than 5 min
-- workspace_forget({ what: "src/auth.ts:chunk-3" })`,
+Best practices:
+- Remove by file path when done with a file: workspace_forget({ what: "docs/prd.md" })
+- Remove stale context by age: workspace_forget({ what: "10" })
+- Remove results from previous search: workspace_forget({ what: "old query text" })
+
+Returns updated workspace state after removal.`,
 
   args: {
     what: tool.schema.string().describe("What to forget: chunk ID, file path, search query, or age in minutes"),
@@ -110,7 +123,15 @@ Examples:
 // ── workspace.clear ─────────────────────────────────────────────────────────
 
 export const workspace_clear = tool({
-  description: `Remove ALL chunks from workspace context. Use when switching tasks or starting fresh.`,
+  description: `Remove ALL chunks from workspace — complete reset. Frees entire token budget.
+
+Use when:
+- Switching to a completely different task or topic
+- Workspace is cluttered with irrelevant context from many searches
+- Starting a fresh investigation from scratch
+
+Prefer workspace_forget() for selective cleanup. Use workspace_clear() only for full reset.
+Returns empty workspace state.`,
 
   args: {},
 
@@ -126,7 +147,15 @@ export const workspace_clear = tool({
 // ── workspace.restore ───────────────────────────────────────────────────────
 
 export const workspace_restore = tool({
-  description: `Restore workspace from a saved session snapshot. Use after compaction or to switch context.`,
+  description: `Restore workspace from a previously saved session snapshot.
+
+Use when:
+- After compaction — restore the workspace context from before compaction
+- Resuming work on a previous task — switch back to that context
+- After workspace_clear() — if you need the old context back
+
+Call without sessionId to list available snapshots with their chunk counts and token sizes.
+Call with sessionId to restore a specific snapshot. Replaces current workspace entirely.`,
 
   args: {
     sessionId: tool.schema.string().optional().describe("Session ID to restore. If not provided, lists available snapshots."),