Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What GitNexus tools are available?", "How do I use GitNexus?"

GitNexus Guide Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema. Always Start Here For any task involving code understanding, debugging, impact analysis, or refactoring: 1. Bind the repository once — use a confirmed registry name/path or configured default; call list repos if unknown. Read hot tool staleness ; use gitnexus://repo/{name}/context when an overview is needed. 2. Match your task to a skill below and read that skill file 3. Follow the skill's workflow and checklist If step 1 warns the index is stale, run node .gitnexus/run.cjs analyze in the terminal first. On query / context / impact / cypher , read staleness.status and staleness.branch / lastCommit before using the answer. Re analyze only for behind or diverged . Skills Task Skill to read Understand architecture / "How does X work?" gitnexus exploring Blast radius / "What breaks if I change X?" gitnexus impact analysis Trace bugs / "Why is X failing?" gitnexus debugging Rename / extract / split / refactor gitnexus refactoring Tools, resources, schema reference gitnexus guide (this file) Index, status, clean, wiki CLI commands gitnexus cli Tools Reference Tool What it gives you query Process grouped code intelligence — execution flows related to a concept context 360 degree symbol view — categorized refs, processes it participates in impact Symbol blast radius — what breaks at depth 1/2/3 with confidence trace Shortest path between two symbols — "how does A reach B?" in one call detect changes Git diff impact — what do your current changes affect rename Semantic rename: previews by default ( dry run omitted/true), applies with dry run: false and the preview's plan token ; inspect application status and failures cypher Raw graph queries (read gitnexus://repo/{name}/schema first) explain Persisted taint findings — source→sink data flows (needs analyze pdg ) pdg query Control/data dependence — what gates X (CDG) / where Y flows (REACHING DEF); needs analyze pdg check Check graph invariants such as circular imports route map API route map — which components/hooks fetch which endpoints, and the handler files that serve them shape check Response shape drift — keys each route returns vs keys its consumers access (flags MISMATCH) api impact Pre change report for an API route — consumers, middleware, shape mismatches, risk level tool map MCP/RPC tool definitions and the files that handle them group list List configured multi repo groups, or one group's config group sync Rebuild a group's Contract Registry (cross repo HTTP contract links); run after group.yaml changes or member re index list repos Discover indexed repos (paginated — limit / offset ) Choose a focused response Use the connected server's schema; older servers may not advertise the new filters. All options below are explicit: omitting them preserves existing output. Use filters for bulky unwanted sections; on an already small response, omission metadata can outweigh the bytes saved. Question Options Which symbols implement this? query : limit: 3 , max symbols: 3 , include content: false , chain depth: 0 , response sections: ["process symbols", "definitions"] Which execution flows match? query : keep processes in response sections ; join its id to process symbols[].process id Who calls this exact symbol? context : uid , response sections: ["incoming"] , relationTypes: ["CALLS"] What does it call, with source? context : uid , include content: true , response sections: ["outgoing"] , relationTypes: ["CALLS"] What is the impact summary? impact : direction: "upstream" , summaryOnly: true ; risk calculation and totals are retained Which affected symbols need inspection? impact : limit: 10 , offset: 0 ; page as indicated by the response How does A reach B? trace : from uid , to uid response sections selects data sections for single repository MCP query or context (not @group routes). Query choices: processes , process symbols , definitions . Context choices: incoming , outgoing , processes , chain , routes , typed properties ; the selected symbol always remains. Context relationTypes accepts uppercase relationship names advertised by its schema and filters only the existing incoming/outgoing categories. It does not change ranking, traversal, source retention or the bounded candidate/reference windows. Filters add response filter with the selection and omitted fields/categories. Warnings, ambiguity, staleness and completeness metadata always remain. An empty filtered view is not proof of absence. Omit filters to expand, and never waive impact checks because a selected category is empty. maxTokens is a byte cutoff, not pagination: it can cut JSON. Prefer these filters, small result counts, and source/chain expansion for a selected symbol rather than a large search result. Stop once enough evidence answers the question; do not run every tool by default. Paginating list repos list repos is paginated so a large registry is not truncated by MCP/LLM token limits. It takes optional limit (default 50 , max 200 ) and offset , and returns: To enumerate every repository, keep calling with offset set to pagination.nextOffset until hasMore is false : Notes: offset ≥ total returns an empty page (with total still reported). Out of range or malformed limit / offset (non integer, limit outside [1, 200] , offset < 0 ) are rejected with a clear error — limit above the max is rejected, not silently capped. The order is deterministic (lower cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged. Inline staleness signal ( query / context / impact / cypher ) These four hot read tools attach a non blocking staleness field to every response, in the shape { status, branch?, lastCommit, indexedAt, measuredAgainst, commitsBehind?, hint? } . It answers two different questions at once: which index answered and how fresh it is . The identity half is why the field is present even when nothing is wrong — an answer computed from a branch pinned index is otherwise indistinguishable from one computed from the default branch ( 3291): status: "current" here means this index is at the HEAD of the clone it was built from — not that it is current with the default branch. measuredAgainst names what commitsBehind is counted against: the checked out HEAD of that clone, never the remote. branch is the branch the index represents; it is absent for a detached HEAD, a non git folder, or a legacy index that never recorded one, so read lastCommit when you need an identifier that is always present. When the index is behind that HEAD, the count and hint ride along: commitsBehind is present only when git counted the gap. When git could not count it but HEAD still resolves to a commit other than the indexed one — usually because the indexed commit is no longer in the clone's history — the index is provably not at HEAD with no countable gap, so no number is reported: So: read status before using commitsBehind , and read branch / lastCommit before assuming which ref the answer describes. status: "unknown" means the freshness check could not run at all (a skip git folder has no history to measure) — the ref is still reported, because which index answered is knowable even when its freshness is not. The field is only ever added to object results — raw array cypher output and error envelopes are returned unchanged. @group targeted calls do not carry it (multi repo staleness is ill defined). Re run analyze only for behind or diverged — those mean the index is not at this clone's HEAD. unknown is unmeasurable, not stale; analyze cannot make it current unless git history exists. list repos and the HTTP repo routes are unchanged: they omit staleness entirely for a current index and report the ref through their own top level branch / lastCommit / indexedAt fields. Taint findings ( explain ) explain returns taint findings recorded by gitnexus analyze pdg — intra procedural TAINTED edges plus cross function TAINT PATH hops where the interprocedural taint phase found a function level source→sink chain. Each finding includes a sink category (command injection, code injection, path traversal, sql injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop. explain {} — enumerate all findings for the repo (bounded by limit , deterministic order) explain { target: "src/vuln.ts" } — findings in a file (suffix path match accepted) explain { target: "runUserCommand" } — findings in a function (resolved like context ; ambiguous names return ranked candidates) A repo indexed without pdg returns a clear "no taint layer" note. Caveats: closure/callback, property/field, and implicit flows are not modeled, and interprocedural findings are function level TAINT PATH hops rather than statement level path proof, so the absence of a finding is not proof of safety. SANITIZES (sanitizer kill) edges are queryable via cypher . Control & data dependence ( pdg query ) pdg query reads the control/data dependence layers gitnexus analyze pdg records (CDG + REACHING DEF, basic block granular) — the control/data analog of explain . It is always anchored (a target file path or symbol, resolved like context ) and has two modes: pdg query { mode: "controls", target: "..." } — CDG: "under what condition does X run?". Each edge is a controlling predicate block → dependent block with the branch sense ( 'T' / 'F' ) in reason ; an edge into an early return / throw is flagged guard: true (guard clause discovery — the sense depends on the predicate, so don't filter guards by a fixed label). pdg query { mode: "flows", target: "...", variable?: "..." } — REACHING DEF def→use edges within the function; pass variable to trace one binding. A repo indexed without pdg returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra procedural only — cross function flow is taint's domain ( explain ). The raw CDG/REACHING DEF edges are also queryable via cypher . See the gitnexus pdg query skill for the full query surface. Shortest path between two symbols ( trace ) trace answers "how does A reach B?" in one call — the shortest directed path over CALLS (plus HAS METHOD , so a class rooted trace descends into its methods) instead of chaining 3–8 context / impact hops by hand. trace { from: "validateUser", to: "executeQuery" } — shortest path between two symbols. Disambiguate common names with from uid / to uid (zero ambiguity) or from file / to file ; an ambiguous name returns ranked candidates. maxDepth (default 10, max 30) bounds the search; includeTests (default false) lets the traversal pass through test file symbols. Returns ordered hops (each { name, filePath, startLine } ) and an aligned edges[] of { relType, confidence } , so call hops and containment ( HAS METHOD ) hops stay distinguishable. When no path exists it reports the furthest reachable node (where the chain breaks) and sets truncated: tru

gitnexus-guide