Getting oriented

Addressing

One grammar reaches every file, symbol, and line RepoQL indexes — here, in any repository you imported, in the manual inside the binary, and in what the repository has learned about itself. Learn it once and every tool inherits it.

file:///src/**/*.cs#symbol=*Service => structure

Read left to right: where to look, then which part of it, then what comes back. Each of the three is optional, and each composes with the others.

Where to look — the scheme

Scheme	What it addresses
file:///	The repository you are working in.
github://owner/repo	Any repository you imported, at the same fidelity as your own.
help:///	The manual that ships inside the binary — searchable and readable like code.
concept:///	What this repository has learned about itself: invariants, rules, hard-won knowledge.

How wide — globs

The full shell vocabulary, in the path.

Pattern	What it matches
*	One path segment.
**	Any depth.
?	A single character.
{a,b}	Alternatives — `src/{L1,L2}/**` matches either.
[a-z]	A character class.
;	Join addresses — `src/;lib/` matches either side.
!	Exclude — `!/tests/`, applied to every include in the address.

Which part — fragments

A fragment cuts into a file without reading the rest of it.

Fragment	What it narrows to
#symbol=Name	One symbol, matched on its fully qualified name.
#symbol=Name.*	Its direct members.
#symbol=Name.**	Every descendant.
#symbol=*Service	Every match, across every file the glob reached.
#line=42	A single line. Lines are 1-based.
#line=42,60	An inclusive range.

What comes back — modifiers

Append => modifier to decide the shape of the answer: signatures instead of bodies, a directory tree, the commits behind a span, a search inside the scope. There are seventeen of them and they belong to read — the complete set is on its page.

file:///src/** => tree: headlines # one line describing every file file:///src/Auth.cs#symbol=Refresh => history # the commits that built it file:///src/** => find: retry with backoff # search inside the scope

The whole grammar works on both surfaces. When you say “show me the signature of every service class in src, without reading the bodies”, one address carries all of it:

Your agent calls — mcp

read("file:///src/**/*.cs#symbol=*Service => structure")

You call — cli

rql read "file:///src/**/*.cs#symbol=*Service => structure"

This page names what exists. The depth behind every name ships inside the binary at help:///: the bounds, the failure modes, how they compose. It answers to explore and read exactly like your code does. Install it, and your agent has the manual.