Adopt it as an evidence router, not a search oracle

Zvec-grep is worth adopting when a workspace repeatedly asks questions whose location or wording is unknown, and when a local index can turn that uncertainty into compact, source-linked evidence. It is not automatically worth adopting for every search: exact anchors may be better served by managed ripgrep, and a ranked result is decision-useful only when its scope, representation, freshness, model compatibility, and data permissions are understood. That is the final judgment this series supports.

The distinction matters because the project’s value is often described too broadly. Zvec-grep does not make a workspace omniscient, and it does not remove the need to read source material. It changes the path by which a person or agent reaches that material. Semantic discovery can narrow an unknown search. Lexical ranking can anchor a candidate in recognizable terms. Exact retrieval can check occurrences that must be complete. The right adoption decision follows the interaction among those capabilities.

The route is part of the answer

A workspace question contains an evidence requirement before it contains a search command. “Where is the application’s saved-theme behavior restored during startup?” asks for discovery: the wording describes a relationship, but the relevant file and symbol are unknown. “Where does restoreTheme occur?” asks for exact location. “Which component calls restoreTheme, and does every call handle the fallback?” is mixed: the first part may require relationship discovery, while the second may require source reading and an exhaustive check of a known anchor.

Zvec-grep’s distinctive role is to route these questions without collapsing their standards. Its indexed path stores text, vectors, structural metadata, and source ranges so that a semantic or hybrid query can return a ranked set of entities. Its managed ripgrep path scans the workspace directly for literals, symbols, paths, fragments, and regular expressions. The common zg boundary reduces tool switching, but it does not make a ranked sample exhaustive or make an exact match explain a cross-file relationship.

This is more than a convenient division of labor. It is a way to keep the claim and the retrieval method aligned. If a reader asks for every occurrence of a configuration key, a ranked sample can help locate the relevant area but cannot support the word “every.” If a reader asks why a request is rejected before reaching storage, an exact search for the word “reject” may miss the validation boundary because the implementation uses a different term. The first case needs coverage; the second needs discovery. Zvec-grep is strongest when it recognizes that difference.

The index itself is an evidence router’s memory. The workspace scanner decides which files belong to the semantic scope. The extraction pipeline may preserve a code symbol, its enclosing scope, signature, documentation, and source range; it may organize Markdown by headings; or it may fall back to bounded text. The embedding model turns the resulting fragments into vectors, while full-text fields support lexical ranking. Search then combines candidates and presents a compact result that points back to the source. Each stage determines what the next stage can know.

That chain changes how a result should be interpreted. Suppose a semantic query returns a function whose name suggests startup initialization, with a range that contains a preference read. The result is a strong discovery lead because the entity and its source location fit the question. If the function’s body is split into grouped windows, the relevant window can be read together with the entity’s outline. If the query asks whether a second call site exists, the reader must still search the known symbol or inspect the current source. The index has shortened the path to the evidence; it has not replaced the evidence.

The same model applies to documents. A Markdown heading can make a relevant policy section easier to find, while a plain-text fallback can surface a passage without preserving the document’s hierarchy. A source range can show where the passage came from, but a short preview may omit the qualification that changes its meaning. Structure improves the route to evidence, not the certainty of the conclusion. The reader must carry the representation’s limits into the final claim.

Rank fusion makes the route more effective without changing that boundary. Lexical and vector candidates can reinforce one another, and the search engine can deduplicate grouped fragments and preserve coverage across query groups. A candidate recalled by two signals may deserve earlier attention than one recalled by only one. But agreement is still a relevance signal. Two routes can share the same scope gap or be attracted to the same incidental passage. A fused score tells the recipient how candidates were prioritized, not whether the top candidate owns the answer.

This is why the product is better understood as an evidence router than as a search oracle. An oracle would imply that the system can turn an open question into a complete and authoritative answer. Zvec-grep instead manages transitions: from uncertain wording to likely entities, from likely entities to source ranges, and from source ranges to exact checks when the claim requires them. Its success can be measured by whether those transitions reduce wasted exploration while preserving the reader’s ability to verify.

A ranked result is useful only under conditions

The first condition is scope. An indexed result can only come from material the scanner admitted. Default ignores, repository rules, path and type filters, size limits, binary detection, and format support all shape the semantic evidence surface. Several binary document, archive, compiled, media, and database formats are currently skipped before extraction. Images require explicit selection and a model that accepts image input. Exact ripgrep may still see workspace material that the semantic index does not contain.

This creates a practical adoption test: can the files that matter to the work be represented by the current pipeline?