Integrate with agents

You have a corpus. The last question is how an agent session actually reads it during a task - pulling the right doc, citing it, and failing loudly when a query resolves to nothing.

That read path is a solved problem, and it is documented in one place rather than two: Foundry's knowledge layer. Foundry ships the retriever skill that resolves query keys against the repo's scope (its own knowledge base plus its locked dependencies) or halts loudly, and Alloy publishes the manifest and MCP contract that skill reads. Re-documenting the query mechanism here would just be a second copy to drift; instead, this page points you at the authoritative one.

Start here

• Query Alloy directly - the recipe for resolving corpus knowledge from an agent: the query-key grammar, how to cite what you resolve, and how to wire it into a task.
• The knowledge layer - the concept: how the retriever resolves keys, how it honors a pinned { version, view }, and how a miss becomes measured telemetry rather than a silent guess.

What you already have from this guide

Everything the retriever needs is what the walkthrough produced:

• A corpus it can resolve against - your repo's own knowledge base under .alloy/, or a declared dependency from Installation.
• The MCP server as the canonical access path - the pinned alloy-corpus entry alloy init (or alloy mcp register) writes into each editor's MCP file (see Installation).
• A committed .alloy/corpus.lock where you draw on a shared knowledge base, so every query is deterministic - see Add shared knowledge.

What an agent physically sees

Whichever door an agent uses - the MCP server, the knowledge skill, or alloy query - it gets the same four things. The full rules are in the read-path contract; this is the shape of what comes back.

The roots it reads from. Scope is composed from the open roots, detected in a fixed order: the roots the editor or MCP client reports (or explicit --root <dir> flags, repeatable on alloy query) win outright; otherwise the nearest knowledge-base ancestor of the working directory; otherwise the immediate child directories that hold one. The root holding the working directory is primary. Each root contributes its own knowledge base plus the referenced sources its manifest declares and its .alloy/corpus.lock pins - nothing ambient, nothing fetched at read time.

The scope line. Every answer, resolved or not, ends with one line saying what was considered:

[scope] primary=<root> peers=<other open roots|-> deps=<name@version|commit,…|-> unavailable=<names|-> override=<names|->

An unavailable entry is a declared source the machine cannot serve yet (the fix is alloy sync); override names a source served from an ALLOY_DEP_PATH_<NAME> local path.

Qualified keys and citations. A key may name the source it means: <source>/<category>:<unit>. Unqualified, your own categories win, and a category exactly one referenced source declares resolves there on its own. A resolved doc is cited as alloy://<path> when it is your own and alloy://<source>/<path> when it came from a referenced source - so a citation always says where knowledge came from.

Exactly three not-found reasons. A miss is never a shrug; it is one of:

• ambiguous - two or more sources in scope declare the category; the qualified candidates are listed. Qualify the key.
• out-of-scope - no source in scope answers; the message names what is in scope and the alloy add that would bring the source in.
• absent - the category is in scope but the unit is not there. Terminal: no other source is tried.

How to declare a referenced source, what alloy add writes, and how a fresh clone restores it is covered in Add shared knowledge; what your own knowledge base is, in Your repo's knowledge base. Beyond that, the two Foundry pages above are the whole story.