Why Alloy

Treat knowledge like a build artifact

Everyone has a knowledge corpus - a wiki, a docs folder, a RAG index. What almost nobody has is a corpus that behaves like a build artifact: every document machine-validated before it can merge, stamped with the exact commit and file set it was derived from, mechanically declared stale when that source changes, and served to agents through a versioned contract that consumers pin like a dependency. Alloy treats knowledge the way a compiler treats code, and that is the whole idea.

Install the tooling →   Follow the tutorial →

---

The problem it solves

An AI agent asked to "build a service the way this codebase does" cannot hold a large repo in context, and raw source is a poor teaching medium anyway: it shows what exists but not when to use it, when not to, or what a mistake looks like. The usual answers all fail in known ways.

• Hand-written docs rot silently. Nobody notices a doc is wrong until an agent builds on it.
• RAG over source re-derives everything per query, has no curation gate, and cheerfully retrieves a deprecated pattern next to the current one.
• A wiki has no machine contract. Consumers couple to prose and folder layout; every restructure breaks every consumer, invisibly.
• LLM-generated docs without review measurably hurt agents. Generation has to be gated, not trusted.

Knowledge that agents halt on carries unusual authority. A wrong corpus is worse than no corpus, so Alloy is built around one question: how do you make a body of prose as trustworthy as a passing test suite?

The six properties that make the difference

1. Documents are validated artifacts, not prose. Eight machine-checked quality gates (frontmatter schema, required sections per document kind, structural minimums, lifecycle integrity) run on every doc; a doc that fails cannot merge. Agents rely on structure - every doc of a kind has the same sections.
2. Negative knowledge is mandatory. When NOT to Use and Anti-Patterns sections are enforced with minimum entry counts, because negative knowledge is what agents most lack and what raw source can never show.
3. Honesty is structural. When something cannot be verified against source, an author writes an explicit > ⚠️ GAP: marker instead of guessing. Gaps are surfaced and aggregated - unknowns become a tracked work queue, not a silent hallucination.
4. Staleness is mechanical, not calendrical. Every generated doc records the commit, content hash, and extraction contract it was built from. Drift is the set of files changed since that commit, intersected with the file set the doc actually derives from. Not "this doc is 30 days old" but "these two files this doc was built from changed."
5. The agent boundary is a hard line. Deterministic code decides which files matter; agents write prose; humans merge, always. No part of the pipeline calls an LLM to decide what is true.
6. The corpus is pure and the contract is versioned. The corpus is markdown plus YAML, married to no AI vendor and no tool format. Consumers pin { version, view } in a committed lockfile and resolve structure from a shipped manifest, so a restructure is a major version bump behind a handshake, not a silent breakage.

---

How the pieces fit

Your source repo         - the code Alloy reads
     ⇩ discovered into
Units                     - the documentable things (a service, a library, a module)
     ⇩ extracted into
A context bundle          - the exact files + prompts that feed one doc
     ⇩ authored by
An agent                  - writes prose the bundle supports, gap-marks the rest
     ⇩ gated by
alloy validate            - 8 checks, then a human merges, then alloy stamp
     ⇩ served to
Agent sessions            - through a pinned, versioned contract

You bring the repo. Alloy brings the discipline that turns it into knowledge an agent can trust.

Two ways to run it

• Consume a central corpus. Pin a published version and resolve knowledge from it. Covered in Installation.
• Host your own. A repo can document itself - a portable .alloy/ corpus built, validated, and stamped in place, specific to that repo and never shared upstream. This is the spoke path, and it is what the tutorial walks through end to end. Reference: Host your own corpus.