Glossary
The vocabulary the tutorial and concepts pages assume. Skim it once; come back when a term bites.
Source
A repo (or a subtree) that Alloy reads to produce docs. A source is addressed as { repo, ref } so its provenance means the same thing on every machine. In the spoke path, the source is the repo itself - a self: true source whose referent is the repo's own git HEAD.
Unit
One documentable thing inside a source - a service, a library, a module, an SDK. A unit is what one doc (or one small set of docs) is about. Units are not folders: one unit can span several packages, and one folder can hold several units.
Kind
The type of a unit - service, lib, adapter, and so on. A kind fixes the doc shape (which sections are required) and the rule pack (which files feed the doc). Two units of the same kind get the same treatment.
Rule pack
The YAML that says which files feed a unit kind's doc, paired with the extraction prompt for each. The union of a rule pack's globs is the unit's extraction surface - the declared input set that drift is later measured against.
Context bundle
The deterministic package the CLI assembles for one unit: the exact source files, the extraction prompts, the required sections, and the doc template. The authoring agent writes only what the bundle supports. Built by alloy generate (or alloy regenerate for an existing doc).
Provenance
The frontmatter that records what a generated doc was derived from: source, source_ref (the exact commit), source_hash (a hash over the matched input files), and source_contract (a hash of the extraction contract). Written only by alloy stamp, and only after the gate passes.
Drift
Mechanical staleness. A doc is drifted when files changed between its source_ref and the source's tracked tip, intersected with its extraction surface. A change outside that surface never marks drift. States: fresh, drifted, contract-drift, hash-drift, pinned, unverified.
The gate
The eight validators alloy validate runs on every doc: frontmatter schema, per-kind required sections, imports, type signatures, negative-knowledge minimums, gap-marker surfacing, lifecycle integrity, curated governance. Errors block a merge; a passing doc is why an agent can trust structure.
Coverage
The accounting that puts every source element into exactly one of three states: EXTRACTED (a rule covers it), EXCLUDED (a recorded decision with a written rationale), or UNKNOWN (a surfaced gap demanding one of the other two). UNKNOWN is remaining work, not a silent omission.
View
A named set of sources plus a supersession-visibility rule, declared in the manifest. A consuming repo pins one view, and every query passes it through, so one agent draws on the right knowledge and never sees knowledge that does not apply to it.
Spoke
A consumer repo that hosts its own corpus under a portable .alloy/ root, rather than only consuming a central one. Scaffolded by alloy init --spoke. Its source is self: true, and its corpus never enters the central tree. The federated model.
Curated doc
A hand-written shared/ document - a pattern, a practice, an architectural note, a convention - that passes the same gate as a generated doc. Scaffolded by alloy new curated, governed from birth with an owner and either a review_after date or code referents.
Stamp
The command (alloy stamp) that writes provenance. It re-runs the gate first and refuses to write anything if it fails. It is the only writer of last_verified and the provenance fields, and it is what makes a doc's freshness claim honest.