rig / rules

---
description: Rig MCP usage guide — when to use which tool
alwaysApply: true
---

<!-- GENERATED FILE — DO NOT EDIT.
     Source: .contracts/targets/cursor.contract.ts
     Edit the .contract.ts file(s), then run `bun run gen`. -->

# Rig — Cursor instructions

Rig exposes these MCP tools. Always prefer them over file reads for graph questions.

## light tools

### `rig_aliases`

Return every alias name pointing at a given canonical anchor. Aliases are
alternate names (e.g. `pd` for `pandas`, `useState` for `React.useState`)
that resolve to the same node via FTS5 search. Each carries the actor that
registered it.

### `rig_callees`

Return the set of anchors directly called by the given function/method.
One-hop, structural edges only. Output is NodeRef[].

Use to answer "what does this depend on" or "what does this function
touch". For transitive reach use rig_impact; for general relatedness
use rig_pull.

### `rig_callers`

Return the set of anchors that directly call the given function/method.
One-hop, structural edges only. Output is NodeRef[].

Use to answer "who uses this" or "what will break if I change this".
For transitive impact use rig_impact; for general relatedness use
rig_pull.

### `rig_chain`

Starting at a given waypoint, walk the waypoint_succeeds edges backward
through history up to maxDepth hops. Returns the seed at index 0 followed
by its predecessors in order. Use to reconstruct the reasoning thread
that led to a decision.

### `rig_cold`

Return the anchors that have not been activated within the stale-after
window. last_ts is null when the node has never been touched. Useful for
pruning candidates and identifying dead-weight in the graph.

Default stale-after is 90 days, limit 20.

### `rig_critical_path`

Greedy walk outward from the root anchor, picking the highest-scoring outbound
edge at each step. Score = w_hubness × destination.hubness + w_activation ×
normalized_activation_count + w_kind × edge_kind_weight (contains > references
> calls > imports). Returns an ordered chain — the "main thread" through the
subsystem rooted at this anchor.

Use as a one-shot architecture tour: "what's the spine of this code path"
or "which chain of anchors carries the most traffic from X". For one-hop
neighbors use rig_neighbors; for ranked similarity use rig_pull.

### `rig_dep_conflicts`

Return every dependency name (scoped per ecosystem source) that appears in
two or more manifests with different version specs. Same-name-different-source
(e.g. an npm package and a PyPI package that happen to share a name) is not a
conflict — only intra-ecosystem disagreement is flagged.

Use to spot drift before it bites: pandas at 2.1.4 in requirements.txt and
2.2.0 in pyproject.toml is the classic case.

### `rig_deps`

List the dependencies a project declares in its package manifests (currently
package.json; more formats coming). Each entry has {name, spec, source,
manifest_path, is_dev, is_optional, is_peer}.

Use for "what does this project depend on" and "what version of X does it
declare" questions. For symbol-level lookup of how a package is imported
in code, use rig_search with the package name.

### `rig_drill`

Walk outward from a hub via structural edges (contains > references > calls >
imports), rank descendants by magnetic pull from the hub. Optional name query
filters the returned set. Use after rig_hubs to drill into one part of the
graph instead of dumping the whole neighborhood.

### `rig_files`

List files known to the rig index, optionally filtered by a substring of
the file path. Each entry has {path, language?, node_count,
last_indexed_ts?}.

Use for "what does rig know about" sanity checks and to discover entry
points before searching. For symbol lookup inside a file use rig_search
with a kind filter.

### `rig_hotspots`

Return the anchors that have been activated (queried, expanded, AI-touched)
most often within a sliding window. Count-based ranking — for decay-weighted
relevance use rig_pull.

Use to discover the parts of the graph you have been working in lately,
or to seed a cache-warming pass. Default window is 7 days, limit 20.

### `rig_hub_of`

Walk outward from an anchor via structural edges, return the first hub layer
reached (up to maxDepth hops). Use to answer "what part of the system does
this belong to" without traversing the full graph.

### `rig_hubs`

Return the most "hub-like" anchors in the graph, ranked by hubness. Hubs are
high-fanout structural concentrations (top 5% per anchor type) plus any node
explicitly promoted via rig_promote.

Use as the entry point when navigating a large graph — pick a hub, then call
rig_drill to explore its sub-tree.

### `rig_impact`

Return all anchors reachable as transitive callers of the given anchor
up to the requested depth. Useful for change-impact analysis: "if I
change this function, what tests/callers might break".

Defaults to depth 3. Depth is capped at 6 to keep the result bounded.
For one-hop callers use rig_callers.

### `rig_neighbors`

Return edges incident to the given anchor in both directions, from both
the structural and semantic edge tables. Output is a flat EdgeRef list
with {src, dst, kind, weight?, table, source_urls?}. A semantic edge (an
accepted rig_propose_edge) keeps the kind it was proposed with and its
evidence URLs; the kind filter matches it like any other edge.

Use when you want the raw graph view ("what does this connect to") rather
than a ranked similarity view. For "what's most related" use rig_pull —
it scores by structural distance + semantic similarity + recency.

### `rig_node`

Return metadata for a single anchor: id, name, kind, file_path, qualified
name, signature, docstring, and neighbor counts by edge kind. Does NOT
return the source body — use rig_explore (heavy tier) for full source.

Use as a cheap inspection step after rig_search to decide whether a node
is worth pulling neighbors or callers for.

### `rig_overview`

Start here. Returns a compact markdown map of the repository, about 2,000
tokens by default: project basics (languages, packages, key dependencies),
entry points (manifest exports, bin and index files mapped to source),
module layout with one-line purposes, the most-referenced files and
exported symbols with signatures and file:line, request/handler surfaces
(string-literal unions and enums, handler directories and the functions
that dispatch to them, HTTP verb exports), where tests live and what they
import, and recent decision waypoints. Every line names real paths.

Call it once at the start of a session, before searching, and answer
simple "where is / which file / what version" questions from it directly.
Built from the index alone (no model) and refreshed by `rig index`,
`rig sync` and the file watcher; generated_at says when. budget is in
tokens (default 2000); a larger budget shows more of every section. The
same map is the MCP resource rig://overview.

### `rig_phantom_imports`

Mirror of rig_unused_deps: returns import sites whose target package name
has no matching declared dependency in any manifest. Common causes are a
missing entry in package.json / requirements.txt, a typo, or reliance on a
transitive dep that should be declared directly.

Subpath imports normalize to the parent package (`lodash/get` → `lodash`);
relative + absolute paths are not counted as phantoms.

### `rig_pull`

Rank the top-k anchors most "magnetically attracted" to the given node.
Score combines graph distance (structural: 1/(1+hops) over code edges and
accepted rig_propose_edge links), embedding cosine similarity (semantic),
recent activation decay (recency), and a hub-bias boost so high-fanout
anchors surface first by default. Returns PullResult[] with
{nodeId, score, components: {structural, semantic, recency, hub}}.

Use this for "what's related to X" or "what else should I look at" —
it is strictly better than rig_neighbors when you want a ranked list.
Use rig_neighbors only when you need the raw edge view. To disable the
hub bias (raw neighborhood ranking), pass hub_bias=0.

### `rig_relevant_skills`

Rank the agent's own MCP tools (seeded as 'skill' anchors at startup) by
relevance to a free-text intent. Useful when the agent itself wants to
discover which of its tools to call — "I need to validate this externally"
ranks browser/web tools high; "what is connected to X" ranks
rig_pull/rig_neighbors high.

Same hybrid retrieval as rig_search (names, keywords over the
descriptions, and semantic similarity of the embedded descriptions); this
just narrows to skill anchors and returns the tier+description so the
agent has enough to pick. degraded is "keyword-only" when the embedding
model was unavailable.

### `rig_search`

Find anchors by name or by a plain-language description. Takes a symbol
("AuthStore", "auth_store", "AuthStore.login", a prefix like "authStor")
or a question ("where do we refresh expired sessions?").

Fuses three candidate lists by reciprocal rank: exact name and alias
matches (always first), keyword matches (SQLite FTS5 over names,
identifier words, signatures, docstrings and doc/waypoint text, BM25
ranked; every word must match for symbol-like queries, any word for
questions) and semantic matches (cosine similarity to local embeddings).
Each hit carries score and matched_by. When the embedding model is
unavailable the vector list is left out and degraded is "keyword-only".

For "what's related to this node" use rig_pull instead — search does not
score by graph proximity.

### `rig_session_token`

Read the per-server bearer token from .rig/.runtime and return both the raw
token and a clickable URL the user can paste into their browser to log into
the map. Used when "open the rig map" comes up in chat — the agent fetches the
token (because it has filesystem access to .rig/), the user clicks the URL,
and the cookie gets set.

The URL points at the host and port the web server last bound (ports are
per project; the server records its address in .rig/.web.json), falling
back to 127.0.0.1:7474 only when no server has recorded one. Pass host or
port only to override that.

The map requires this token on loopback too. Returns NO_RUNTIME_TOKEN until
the map has been served once in this project (`rig start` or
`rig serve --web` writes .rig/.runtime).

### `rig_status`

Returns counts of nodes, edges, files, and when the graph was last brought
up to date: last_sync_ts is the last index or sync (`rig index`, `rig sync`
or the file watcher), last_index_ts the last full `rig index` (ms since
the epoch; null until the first one after upgrading).
Use as a smoke test before any other rig_* call to confirm the index is initialized.
`orphans` counts memory (aliases, annotations, promotes, proposed/accepted edges,
waypoint refs) kept from symbols that were deleted; it re-attaches automatically
if the symbol comes back in the same file.

### `rig_unused_deps`

Heuristic: a declared dependency is flagged when its package name never
appears as the target of a bare-specifier import anywhere in the indexed
source. Handles scoped packages (`@types/node`) and subpath imports
(`lodash/get` counts as a use of `lodash`).

Possible false positives: JSX runtimes, bundler-only deps, runtime configs.
Treat the result as "likely removable, verify before deleting", not as an
authoritative dead-code report.

### `rig_waypoints`

List waypoints in newest-first order, or by relevance to query when one is
given (hybrid search over titles, summaries, key terms and rationales;
degraded is "keyword-only" when the embedding model was unavailable).
Optional filters: session_id (pass
"last" to auto-resolve to the most recently active session with waypoints
other than your own — useful at session start to rehydrate the previous
thread, and it keeps finding that thread after you drop waypoints of your
own), kind (decision / observation / constraint / open-question /
principle / dead-end), source (agent: dropped with rig_drop_waypoint;
hook: captured automatically from the conversation — agreed decisions,
corrections, constraints and dead ends, each with a confidence).

Call this on session start, before the first user turn, with
session_id="last" limit=20 to pick up where the previous session ended.

## heavy tools

### `rig_context`

Build a context bundle for a task: runs the same hybrid search as
rig_search on the task text — exact names and aliases first, then
keyword (FTS5, BM25) and semantic (local embeddings) matches fused by
reciprocal rank — over anchors that have source in a file, and returns
the top max_nodes in that order with their source bodies, formatted for
direct LLM consumption (markdown by default; JSON available). A
plain-language task ("fix the login bug") finds anchors as well as a
symbol name does. degraded is "keyword-only" when the embedding model
was unavailable. It does not rank by magnetic pull: call rig_pull on a
hit for the anchors related to it.

Heavy tier — the bundle carries full source bodies, so it costs far more
context than the light tools. Use rig_explore for raw exploration; use
rig_context when you want a single ready-to-prompt block.

The response is capped at about 60,000 characters. Sources cut to fit
end with a "… [truncated: N of M lines shown]" line and truncated is
true; lower max_nodes or narrow the task to get whole bodies.

### `rig_explore`

Search the index for a question and return the top-K anchors with their
source bodies and one-hop related anchors. Anchors come from the same
hybrid search as rig_search (exact names, keywords and semantic
similarity), limited to anchors with source in a file, so a
plain-language question works; degraded is "keyword-only" when the
embedding model was unavailable. Returns full file slices, so
this is token-heavy: navigate with the light tools first and call this
once you know which code you need. For lightweight metadata-only
navigation use rig_pull or rig_neighbors.

The response is capped at about 60,000 characters. Sources cut to fit
end with a "… [truncated: N of M lines shown]" line and truncated is
true; lower max_anchors or narrow the question to get whole bodies.

## write tools

### `rig_add_alias`

Add an alternate name for an anchor so searches for the alias return the
canonical node. Use for AI-discovered or user-asserted alternate names
(e.g. `pd` → `pandas`, `useState` → `React.useState`).

The alias is registered with the caller's provenance. Re-adding the same
(node, alias) pair is a no-op; the second call returns added=false.

### `rig_add_node`

Create a new anchor immediately (nodes are cheaper to add than edges).
Use only when the user has explicitly named a new concept in
conversation; do not invent anchors from inference alone.

### `rig_annotate`

Append a free-text note to a node's annotations. Useful for the AI to
leave a breadcrumb on a node ("this is the auth boundary", "renamed from
FooBar in commit abc1234").

### `rig_cluster`

Create a new node of type 'cluster' with 'contains' edges to each member.
The cluster becomes its own searchable anchor. Use when you spot a
group of related anchors that deserves a name.

### `rig_drop_waypoint`

Record a discrete marker the AI considers worth preserving across context
compaction or session boundaries — a decision, a constraint stated by the
user, a recurring observation, an open question, a principle, or a dead
end (an approach tried or proposed and ruled out). The
waypoint becomes a graph anchor with structured payload; predecessor ids
form a `waypoint_succeeds` chain; constellation refs form
`waypoint_references` edges to other anchors.

Use sparingly. Typical floor: at most one per ~5 turns. Drop one when a
real decision is locked, not as a running summary.

Every id in constellation_refs and predecessors must exist; otherwise the
call fails with NODE_NOT_FOUND listing the unknown ids, and nothing is
written. The rationale is stored with the waypoint; rig_waypoints and
rig_chain return it.

### `rig_focus`

Emit a focus:requested event over WebSocket so the map UI pans and
zooms to the given anchors. No graph mutation; logged in mutation_log
for audit.

### `rig_promote`

Promote any node to hub status regardless of its fanout score. Used when the
user or AI has identified a concept-level anchor that the structural heuristic
missed (a "principle" waypoint, a domain entity, a documentation root).

Hubs surface in rig_hubs results and bias rig_pull rankings.

### `rig_propose_edge`

Write a pending semantic edge that the user must accept before it becomes
canonical. Rationale is shown in the accept popover and stored in the
mutation_log forever.

Prefer rig_propose_edge to creating edges directly — the user accepts
the connection before it solidifies.

### `rig_undo`

Walk back the most recent mutation in the current MCP session that has not
been undone yet; call it again to step further back. A proposal is deleted,
an accept or reject returns the edge to pending, add_node, cluster and
drop_waypoint delete what they created, add_alias and annotate remove the
alias or note, and promote restores the node's previous hub flags. Undos
are themselves logged; the chain is auditable.

undone is the mutation reverted, or null when nothing was. Then reason
says why: "nothing to undo" when the session has no mutation left, or why
the inverse of the mutation named in failed can no longer be applied (its
target is gone, or was changed since). A failed mutation is not retried:
the next call moves on to the one before it.

## live tools

### `rig_subscribe`

Long-poll endpoint for following the user's UI activity from an agent
session. Pass the last next_cursor value you saw; receive every
mutation_log row since then (selections, edges proposed/accepted/
rejected, nodes added). Polling every 2s is a good default.

Use this to inject "user is now looking at <anchor>" context into your
next agent turn without the user typing.

## Context budget

`rig_explore` and `rig_context` return full source bodies, so a call costs far more context than the light tools. Navigate with the light tools first and call a heavy tool once you know which code you need. They work from any session; if you can hand heavy exploration to a sub-agent, doing so keeps the main context lean.

Heavy responses are capped at about 60,000 characters. A source cut to fit ends with a `… [truncated: N of M lines shown]` line and the result has `truncated: true` — lower `max_anchors` / `max_nodes` or narrow the query to get whole bodies.

## Session bootstrap

When you need to get oriented in an unfamiliar part of the repo, call `rig_overview` (also the MCP resource `rig://overview`). In about 2,000 tokens it lists the packages and what they are for, the entry points, the most-referenced files and symbols with `file:line`, route and handler tables, where the tests live, and recent decisions. Don't call it by reflex: for an exact identifier or file name, grep is cheaper.

Before responding to the user in a new conversation, call `rig_waypoints` with `session_id="last"` and `limit=20`. The returned waypoints are the prior session's structured decision/observation markers — read them to reorient on what was decided, what constraints are in play, and what open questions remain. Do not re-derive context the prior session already settled.

Drop a waypoint via `rig_drop_waypoint` when: a real decision is locked, the user states a hard constraint, an observation recurs across turns, or an open question emerges that should outlive context compaction. Aim for at most one waypoint per ~5 turns — they are not a running summary.