jevgrep

Jevgrep — optional remote-agent discovery

When to use this skill

Use only for an explicit Jevgrep request over a chosen source-document root. A
request to find a skill, search a wiki, or trace a graph does not by itself select
Jevgrep or authorize remote transmission.

Keep existing routes authoritative: catalog metadata search for skill selection,
exact search/LSP for definitions and exhaustive matches, zvec-grep for established
workspace retrieval, and Graphify query / path / explain for graph relations.
Jevgrep searches generic UTF-8 source text, including Markdown or JSON; it does not
traverse graph edges, query database binaries, or own graph regeneration.

Instructions

1. Freeze the source and remote boundary

Name the query, existing root, configured provider, exclusions, and request/output
bounds. Obtain separate approval for sending eligible source content and the query
to that provider, with possible charges. Saved credentials are not data consent.
Keep secrets, personal raw sources, generated graphs, and database files outside
the root or explicitly excluded. Use a narrower root before increasing scope.

Choose one source surface:

Surface	Root	Retained authority
Skills	/path/to/jeo-skills/.agent-skills or one skill folder	jeo-skill search, catalog metadata, then the selected SKILL.md
Wiki	/path/to/chosen-vault/wiki or a relevant subtree	Read index.md first; retain vault query/citation/filing rules
Graph sources	/path/to/project/.mex/context or a source tree	Graphify query / path / explain; existing checkpoint/refresh ownership

Do not select .mex/graph.db, graphify-out/graph.json, or a graph-artifact directory
as the default upload surface. A source lookup neither mutates nor rebuilds the
durable graph. Respect project-local graph ownership even when a graph skill's
portable defaults differ.

2. Check installation locally; leave auth to the user

Verify an existing jg binary's version/help without network calls. The approved
manual install for this contract is:

npm install -g @dzhng/jevgrep@0.8.0

Show this action only after installation approval; do not execute it automatically
because a search was requested. The user operates upstream jg auth privately.
Never gather, print, or automate API-key entry. Auth overwrites saved configuration;
search uses that saved provider configuration, not environment API-key/model/endpoint
overrides. jg doctor makes a real provider call and may incur charges: it is not a
local prerequisite or an automatic connectivity check.

3. Preview locally before remote execution

The upstream count preview is provider-free:

jg files -- /path/to/chosen-vault/wiki

It prints file counts and directory groups, not filenames, snippets, a secrets
audit, or an upload-size estimate. It reads ignore configuration. Inspect the root
and sensitive exclusions with native tools before approving the remote boundary.
Selecting .agent-skills or .mex/context explicitly does not need --hidden for
that root; --hidden widens traversal to hidden descendants and needs review.
Repeat --exclude PATTERN for extra exclusions; retain upstream ignore rules.

Use the optional wrapper for an inert execution plan:

jeo-skill explore "Which skill handles vault source citations?" --root /path/to/jeo-skills/.agent-skills --dry-run
jeo-skill explore "Where is the retention decision documented?" --root /path/to/chosen-vault/wiki --dry-run
jeo-skill explore "Which source describes checkpoint ownership?" --root /path/to/project/.mex/context --dry-run

If the linked CLI has not been upgraded, use the source-checkout path instead:

python3 /path/to/jeo-skills/.agent-skills/jeo-skill/scripts/jeo-skill.py explore "Which skill handles vault source citations?" --root /path/to/jeo-skills/.agent-skills --dry-run

Dry-run performs no Jevgrep invocation, auth, installation, or provider check. It
is a plan, not retrieval evidence or confirmation that credentials work.

4. Execute only the approved plan

After explicit source/query/cost approval and existing upstream provider setup:

jeo-skill explore "Which skill handles vault source citations?" --root /path/to/jeo-skills/.agent-skills --exclude '*/raw/**' --allow-remote

Use the same source-checkout Python entrypoint when needed. --allow-remote is a
wrapper gate, not an upstream jg flag or a persistent grant. Defaults are eight
provider requests, 24,000 output bytes, concurrency one, and a 120-second timeout;
the wrapper passes --no-cache to disable upstream answer-cache reads and writes.
Optional wrapper bounds are --max-requests, --max-output-bytes, and --timeout.
--hidden and repeatable --exclude are available only when that wider scope was
approved. Request/time bounds do not guarantee a monetary ceiling; output clipping
and upstream --max-source-bytes bound rendered output, not source upload.

5. Verify snippets against native evidence

Read bounded returned snippets and open only the cited source sections needed to
answer. Verify definitions, exact occurrences, skill metadata, and relationships
through their native routes before asserting them. Empty, truncated, or failed
agent output is not proof of absence or an exhaustive inventory.

On errors, report the command, failure, and unresolved result. Do not silently
switch providers, install/authenticate, broaden roots, retry with new disclosure,
or claim that a fallback answered the original query. If a native route is the
next move, identify it explicitly and preserve its own authorization rules.

References

• Upstream: https://github.com/dzhng/jevgrep
• Pinned release: https://github.com/dzhng/jevgrep/tree/679a0351206a99ef3e4f23e930a8529e78607ecd (v0.8.0, npm @dzhng/jevgrep@0.8.0, MIT)
• Wrapper: ../jeo-skill/scripts/jeo-skill.py explore; upstream has no JSON-output,
  MCP-server, search-stdin, include, or limit flags in this pinned contract.