RAGRAF Operations: Choice and Boundaries

Reference for the ragraf-core skill. The task is to choose an operation instead of reading files — and to know what an operation does not show.

1. The full set

The facade declares 38 operations of the form op_* (src/ragraf/facade.py). The agent tool surface is 40 tools with the ragraf_ prefix (src/ragraf/mcp_server.py). The difference is not an error, and it is not one-to-one. Five tools have no facade operation of their own — context, ensure, task, usage, use_project: they manage the corpus and the session rather than operate on a repository. Three facade operations are not exposed as tools: calibrate, gate, task_set. (Counts measured against the sources on 2026-10-16.)

2. By question type

Question	Operation	Shows	Does not show
Where is a symbol defined	symbol	file, lines, kind, signature, parsed parameters	the function body
Where else is it used	references	all sites with references	execution order
Who calls it	callers	callers with evidence	calls through a string or a data reference
What does it call	callees	callees	same
What will an edit affect	impact	places reachable in the graph	branch conflicts and runtime
Structural slice	slice	context without bodies, only on a full CPG build	nothing at capability=degraded
A symbol's body	code	the exact text	the meaning of the places calling it
Repository map	repo_map	files and volumes within a budget	the links between them
Search by meaning and words	search	chunks with paths and lines	link evidence — this is search, not the graph
What is in a table	schema	columns and relations parsed from migrations	the actual state of a live database
Who reads or writes a table	table_usage	read and write sites	database access rights
Is this write valid	write_check	the write plan checked against the schema before execution	value types and constraints
Who gets a permission and why	policy_trace	decision branches, refusal points	the user's actual role
Styling classes	class_usage	whether a rule exists, where the class is applied	the final look in the browser, the cascade
Routes and handlers	routes	HTTP routes and their handlers	behavior behind the handler
Index currency	freshness	checksum divergence, reindexing when needed	the quality of the facts themselves
Index state	index_status	revision, parse completeness, coverage, stages	nothing beyond the state
Divergence ledger	drift_report	what changed after the revision	the bodies of the changes
Live reading	live_read	the file's current content with difference marks	links and the graph
Call statistics	usage	calls, facts, savings	the meaning of the facts
Development registry	catalog	what is registered and with which numbers	the index contents

3. Choice rules

1. Navigation is an operation; content is reading. «Where» is answered by an operation; «how exactly it works» requires reading the fragment the operation pointed to.
2. A write plan is always write_check. It is the only check that catches a nonexistent column before the code runs.
3. Permission decisions are always policy_trace. Reading a large branch set with the eyes is useless: an unknown action left allowed by default is visible only statically.
4. Before editing markup — class_usage. A missing rule in the styles is not an error: the page renders with browser defaults and works.
5. slice only on a full build. Otherwise the operation refuses with code 3 — that is expected behavior, not breakage.
6. live_read — when the file definitely changed after the revision. Otherwise the index suffices, and it is cheaper.

4. How to read an answer

Mandatory envelope fields: op (operation), index_rev (which revision answered), capability (full or degraded), drift (whether unclosed divergences exist), provenance (where the data came from: index, live read, or mixed), limits, result, stale_warnings, found. Additionally there may be error and freshness.

• found=false at exit code 0 is «not found», not a failure.
• Non-empty stale_warnings means the fact may have been touched by edits after the revision; such a fact must not be served as current without the mark.
• provenance=live means the data was obtained by reading the file, not from the index: its evidence is the file itself, not the revision.

5. What the project does not have

• There is no graph query language. Fixed operations only; text resembling a graph query is rejected with a call error.
• There is no standard dependency version-check command, although requirements.txt promises one.
• There is no unified test runner: there is no pytest configuration, and the files in the tests directory run individually.