Qmd Search

qmd-search — optional semantic search over the wiki (dormant until qmd is installed)

What this is

A thin, dormant adapter to qmd. It does not replace index.md (the curated, read-first catalogue); it is the semantic fallback query/output reach for when the catalogue under-covers a question, and the refresh hook that keeps qmd's embeddings current as the wiki changes. qmd retrieves; the wiki governs (compile, cross-link, confidence, conflicts).

Activation — capability detection (the opt-in is installation)

Use qmd only if all three hold; otherwise fall through to the default search silently:

1. command -v qmd succeeds (qmd installed), AND
2. an index exists for this vault (qmd status lists indexed collections), AND
3. there is no .qmd-off marker in the vault root — create that file to force qmd off without uninstalling; its absence means active (installing qmd + building an index is the opt-in).

This is one cheap shell check. If any condition fails, do nothing: the agent uses index.md → grep exactly as normal. A fresh clone or a non-adopter is unaffected, with no prompt to install anything.

When to invoke (opt-in — never on every search)

qmd search is not a default step. Invoke it only when:

1. the user explicitly asks (/qmd-search, "search semantically", "use qmd"), or
2. the agent judges the cheap path insufficient — index.md + grep under-cover the question (it needs semantic recall, or the corpus is too large to scan reliably).

Otherwise answer from index.md → grep and do not call qmd — a qmd query reads passages into the agent's context (real tokens), so it must earn that cost. This gates only the read side; the write side — refreshing embeddings on every page change — always runs when qmd is active (local compute, ≈ no agent tokens).

Search (only when active)

• CLI shell-out by default (no daemon): qmd query "<question>" --json --files --min-score <t> -n <k> over the wiki collection. The CLI inherits the shell environment, sidestepping the MCP-spawn HOME/db-path pitfall (qmd issue #615).
• MCP daemon — an advanced option for heavy users who want warm models (qmd mcp --http --daemon); set QMD_CONFIG_DIR / the db path explicitly so the server opens the real index.
• Confidence-aware ranking: qmd ranks by relevance; then re-order by each page's confidence (down-rank low/very-low, lift high/authoritative) and break ties by newer updated (supersession), per CLAUDE.md §4.6. Then deep-read the top pages and govern as usual.
• Index-first, always: index.md is read first; qmd is the fallback / widener when the catalogue is insufficient or the corpus is large. A qmd hit never bypasses the governing deep-read.

Refresh on write — one-shot, NEVER a resident process

Two signals refresh whenever wiki page(s) are created or updated:

1. confidence — (re)assign / confirm per CLAUDE.md §4.6 for every changed file. Always the agent's job, never a hook's, and never gated on qmd.
2. qmd embedding — qmd update && qmd embed, once per write operation, never per file (incremental per file, not per chunk: qmd keys embeddings on a file's whole-content hash, so an unchanged file is skipped entirely and a changed one re-embeds all of its chunks — which is why wiki/log.md is excluded from the collection, CLAUDE.md §10). A no-op when qmd is dormant.

Enforcement — a turn-end hook, not an agent step. A prose-only refresh duty can be missed, leaving the index stale while later sessions treat it as current. So where the harness supports it, the refresh belongs in a Stop hook — the harness runs it once per turn, so no agent can forget it, and it costs zero agent tokens. The agent then does NOT run the qmd commands inline; it still owns step 1. This is not a daemon, cron job, launchd job or file-watcher: the hook is a one-shot that runs and exits, nothing stays resident, and nothing runs while the vault is idle.