rig-constellation 0.1.0

package/generated/installer/cursor.instructions.md

@@ -0,0 +1,345 @@
+<!-- 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}.
+
+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_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), 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 retrieval substrate as rig_search; this just narrows to skill anchors
+and returns the tier+description so the agent has enough to pick.
+
+### `rig_search`
+
+Find anchors by name or qualified name via SQLite FTS5. Returns
+{id, name, kind, file_path?} matches ranked by FTS relevance.
+
+Use this for "where is X defined" or "find a symbol named Y" questions.
+For "what's related to this node" use rig_pull instead — search does not
+score by graph proximity or semantic similarity.
+
+### `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.
+
+Returns 'no_runtime_token' in errors when the server isn't running with auth
+enabled (loopback dev mode skips the token by default).
+
+### `rig_status`
+
+Returns counts of nodes, edges, files, and the last sync timestamp.
+Use as a smoke test before any other rig_* call to confirm the index is initialized.
+
+### `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. Optional filters: session_id (pass
+"last" to auto-resolve to the most-recently-active session — useful at
+session start to rehydrate the previous thread), kind (decision /
+observation / constraint / open-question / principle).
+
+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 of the top-K anchors most relevant to a task,
+formatted for direct LLM consumption (markdown by default; JSON
+available). Uses search + magnetic-pull ranking.
+
+Heavy tier — must be invoked from a sub-agent, not the main session.
+Use rig_explore for raw exploration; use rig_context when you want a
+single ready-to-prompt block.
+
+### `rig_explore`
+
+Search the index for a question and return the top-K anchors with their
+source bodies and one-hop related anchors. Returns full file slices, so
+this is token-heavy.
+
+NEVER call this in the main agent session — spawn a sub-agent. The
+two-tier gate is enforced by the dispatcher (MAIN_SESSION_FORBIDDEN).
+For lightweight metadata-only navigation use rig_pull or rig_neighbors.
+
+## 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 data.annotations array. 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, or a principle. 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.
+
+### `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 — propose
+becomes deleted, accept becomes pending again, reject becomes pending,
+add_node deletes the node. Undos are themselves logged; the chain is
+auditable.
+
+## 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.
+
+## Two-tier gate
+
+NEVER call `rig_explore` or `rig_context` directly in the main session — spawn a sub-agent for these.
+
+## Session bootstrap
+
+At the start of a new conversation, before responding to the user, 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.

package/generated/installer/cursor.permissions.json

@@ -0,0 +1,44 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__rig__rig_add_alias",
+      "mcp__rig__rig_add_node",
+      "mcp__rig__rig_aliases",
+      "mcp__rig__rig_annotate",
+      "mcp__rig__rig_callees",
+      "mcp__rig__rig_callers",
+      "mcp__rig__rig_chain",
+      "mcp__rig__rig_cluster",
+      "mcp__rig__rig_cold",
+      "mcp__rig__rig_critical_path",
+      "mcp__rig__rig_dep_conflicts",
+      "mcp__rig__rig_deps",
+      "mcp__rig__rig_drill",
+      "mcp__rig__rig_drop_waypoint",
+      "mcp__rig__rig_files",
+      "mcp__rig__rig_focus",
+      "mcp__rig__rig_hotspots",
+      "mcp__rig__rig_hub_of",
+      "mcp__rig__rig_hubs",
+      "mcp__rig__rig_impact",
+      "mcp__rig__rig_neighbors",
+      "mcp__rig__rig_node",
+      "mcp__rig__rig_phantom_imports",
+      "mcp__rig__rig_promote",
+      "mcp__rig__rig_propose_edge",
+      "mcp__rig__rig_pull",
+      "mcp__rig__rig_relevant_skills",
+      "mcp__rig__rig_search",
+      "mcp__rig__rig_session_token",
+      "mcp__rig__rig_status",
+      "mcp__rig__rig_subscribe",
+      "mcp__rig__rig_undo",
+      "mcp__rig__rig_unused_deps",
+      "mcp__rig__rig_waypoints"
+    ],
+    "ask": [
+      "mcp__rig__rig_context",
+      "mcp__rig__rig_explore"
+    ]
+  }
+}