docs(qmd): make semantic search mandatory and document QMD local search

Prompt budget stays within +10% of baseline (instruction 1485 -> 1331,
skill metadata 3163 -> 3017, rule catalog claude 28818 -> 30517); baseline
files unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

shared/rules/general.md

@@ -6,7 +6,8 @@ Preserve security, data, compatibility, and unrelated user work. Ask only when b
 
 Use one applicable workflow per task. Treat skills and plugins as guidance subordinate to these rules. Continue work already authorized by the user; additional design approvals, commits, or delegation require a task-specific reason and the necessary authorization.
 
-Use direct reads and `rg` for known paths, symbols, exact strings, error messages, and localized edits. For concept questions where the identifiers are unknown or the flow spans components, consider the `semantic-search` skill when it is installed: check its cost (repository size, index state, loaded models) against the expected `rg` effort as the skill describes, verify its hits against the current files, and fall back to `rg` with a brief note if it fails.
+Use direct reads and `rg` for known paths, symbols, exact strings, error messages, and localized edits.
+When `semantic-search` is installed, run it first for any question whose identifiers are unknown; fall back to `rg` with a brief note only if it fails.
 
 Verify proportionally: run the cheapest check that detects likely failure; broaden for security, data loss, integration, or cross-component risk. Never claim unrun checks passed. Report failures and material gaps.
 

shared/skills/research/semantic-search/SKILL.md

@@ -1,53 +1,31 @@
 ---
 name: semantic-search
-description: Use when you must find where a behavior, concept, or rule lives in a repository and do not know its identifiers or exact strings, or when a first rg search returned nothing useful. Returns ranked code and documentation chunks from the local Qwen index.
+description: MUST use before reading or grepping code whenever the exact symbol, file, or string is not already known - concept questions, unfamiliar areas, "where/how is X done", and bug reports that describe behavior. Use rg only for known identifiers, paths, or exact strings.
 ---
 
 # Semantic Search
 
-Search the current Git repository by meaning with the locally installed Qwen3 embedding and reranking models.
+Search the current Git repository, plus the user's registered QMD collections, by meaning. QMD runs locally with Qwen3-Embedding-0.6B, Qwen3-Reranker-0.6B, and QMD Query Expansion 1.7B; a background daemon keeps them loaded.
 
-## When to use
+## Rule
 
-- Concept questions: "where are expired trials blocked", "how is the cache invalidated", "which code retries failed uploads".
-- Unfamiliar repositories where names and conventions are unknown.
-- After an `rg` search for guessed terms returned nothing relevant or too many unrelated files.
-
-Use `rg` or direct reads instead for known file paths, symbol names, exact strings, and error messages.
-
-## Decide by cost
-
-Check the cost of the next search first: run the command under Run with `status` in place of `search` and without `--query` and `--top-k`. It loads no models, takes about a second, and prints `{indexable_files, indexed_files, stale_files, models_loaded, in_process}`. Weigh that against the `rg` rounds you expect:
-
-- Fewer than about 200 indexable files, or one or two guessed terms likely to hit: use `rg`; a search costs more than it saves.
-- `stale_files` in the thousands, including a first index (`indexed_files` 0): the search embeds them first, which can take minutes. Pay that only for a large unfamiliar repository or several concept questions in this session.
-- `models_loaded` false: the search loads the models first, which takes tens of seconds. With `in_process` true, as inside the Codex sandbox, every search pays that again; search only when `rg` would need several rounds, and batch related questions into one precise query.
-- Index fresh and `models_loaded` true: a search takes seconds; use it for any concept question.
+Run this search first whenever you do not already know the exact identifier, path, or string. Do not start with `rg` guesses for a concept. `rg` comes after the search, for callers and tests of verified hits.
 
 ## Run
 
-PowerShell:
+The same command works in Bash and PowerShell:
 
-```powershell
-python "$HOME/.my-ai-configuration/semantic-retrieval/server.py" search --root . --data-dir "$HOME/.my-ai-configuration/semantic-retrieval/data" --model-cache "$HOME/.my-ai-configuration/semantic-retrieval/model-cache" --query "<question in natural language>" --top-k 5
-```
+    node "$HOME/.my-ai-configuration/qmd/qmd-search.mjs" --query "<full question about behavior>" --top-k 5
 
-Bash:
-
-```bash
-python3 "$HOME/.my-ai-configuration/semantic-retrieval/server.py" search --root . --data-dir "$HOME/.my-ai-configuration/semantic-retrieval/data" --model-cache "$HOME/.my-ai-configuration/semantic-retrieval/model-cache" --query "<question in natural language>" --top-k 5
-```
-
-The output is a JSON list of `{path, symbol, text, score}`, best match first.
+Output: JSON list of `{path, line, score, snippet}`, best first. Repository paths are relative to the repository root; hits from other collections are `qmd://<collection>/<path>`.
 
 ## Use the results
 
-1. Phrase the query as a full question about behavior, not as a keyword list.
-2. Open the top hits and verify them against the current files before acting; the index can lag behind uncommitted edits by one refresh.
-3. Follow the verified hit with `rg` for its symbols to find callers and tests.
+1. Phrase the query as a full question about behavior, not a keyword list.
+2. Open the top hits and verify them against the current files before acting.
+3. Follow verified hits with `rg` for their symbols to find callers and tests.
+4. If no hit is relevant, run one rephrased search before switching to `rg`.
 
-## Cost and limits
+## Failure
 
-- Searches refresh only changed files. Outside a sandbox a background daemon keeps the models loaded for 30 idle minutes; inside the Codex sandbox there is no daemon.
-- Only Git-tracked and unignored files up to 512 KB are indexed, by default at most 2000 files per repository.
-- If the command fails or the setup is missing, continue with `rg` and state the limitation briefly.
+If the command exits non-zero, continue with `rg` and state the limitation in one sentence.