path: root/skills/vfs-content-search.json

{
  "name": "vfs-content-search",
  "description": "Search the WebX11 Virtual File System for content by keyword or semantic concept.",
  "tags": [],
  "category": "general",
  "created": "2026-06-08T20:27:43.111Z",
  "updated": "2026-06-08T20:27:43.111Z",
  "content": "---\nname: vfs-content-search\ndescription: Find files in the VFS by semantic concept (use NVFS) or by content keyword (use grep via run_command).\ncategory: dev\ntags: vfs,search,nvfs,grep,find\n---\n\n# VFS Content Search\n\n## Choose the right tool\n\n| You want to... | Use |\n|---|---|\n| Find files *about* a concept (semantic) | `nvfs_resolve(concept)` |\n| Find files *containing* a word (literal) | `run_command('grep -r \"word\" /')` |\n| List a directory | `list_files(path)` |\n| See index health | `run_command('nvfs-status')` |\n\n## Workflow for \"find files about X\"\n\n1. Check the NVFS index: `run_command('nvfs-status')`.\n   - If index is stale or empty → `run_command('nvfs-index')` to rebuild. (May take seconds.)\n2. Call `nvfs_resolve('X')` — returns matching VFS files by concept, not exact name.\n3. Read the top result with `read_file(path)` to confirm relevance.\n\n## Workflow for \"find files containing the word 'X'\"\n\n1. Prefer `nvfs_resolve` first — it understands semantics.\n2. If NVFS misses, fall back to `run_command('grep -rl \"X\" /')` (recursive, files only).\n3. **Anti-loop note:** If grep returns empty ONCE, do not retry with a different path. Empty means empty.\n\n## Common mistakes\n- ❌ Calling `wpm_install neural-vfs` — NVFS is a CORE module, not a WPM package. Already loaded.\n- ❌ Using `read_file` to \"scan\" files one by one — use `grep` or `nvfs_resolve` instead.\n- ❌ Re-running `nvfs-index` repeatedly — once per session is enough unless files change drastically.\n\n## Rebuild the index\nRun `run_command('nvfs-index')` after:\n- Adding many new files\n- Major project restructure\n- `nvfs_resolve` returns obviously wrong results\n"
}