Tutorial: stand up Alloy on your own repo

This is the centerpiece of the guide. By the end you will have taken a repo Alloy has never seen and turned it into a spoke - a repo that hosts its own knowledge corpus under a portable .alloy/ root, built and validated and stamped in place, specific to your codebase and never shared upstream.

You will do it end to end:

1. Survey your repo - scaffold the .alloy/ frame and let an agent draft the source config for a codebase Alloy has never seen.
2. Review the draft - read what the agent proposed: units, kinds, rule packs, exclusions.
3. Understand the draft - what each artifact means and how to judge it.
4. Adjust - add or exclude units, split a bundled kind, and re-check until green.
5. Commit and install - weave the reviewed draft into .alloy/ on a branch, optionally with self-updating CI.
6. Run a campaign - establish the corpus: document every unit with the generate-author-validate-stamp loop.
7. Add curated docs - hand-written patterns, practices, architecture, and conventions that pass the same gate.

What you need first

• The @engineering11 registry scope configured, per Installation. Every command in this tutorial runs through the published CLI.
• A git repo you want to document, with a clean working tree. The spoke's source is the repo itself, so the repo IS the thing being documented.
• An AI coding agent that can run the alloy-survey, alloy-campaign, and alloy-corpus skills. Most of Alloy is run by agents; you kick off a handful of high-level commands and skills, and the agents do the authoring, validation, and stamping underneath.

A note on the commands

For readability we write alloy <cmd> throughout. That is npx @engineering11/alloy-cli <cmd> - alias it if you like:

alias alloy='npx @engineering11/alloy-cli'

Run every command from anywhere inside your repo; the CLI walks up to the .alloy/ root and resolves paths from there.

The split you should hold in your head

Alloy divides work along a hard line, and the tutorial keeps landing on it:

• The CLI is deterministic. It scaffolds, sniffs, assembles context bundles, validates, computes drift. It never calls an LLM.
• The agent is probabilistic. It reads a repo (or a bundle) and writes prose or drafts config. It only ever produces reviewable output.
• You close the loop. You review, you adjust, you merge. Nothing enters the corpus without a human.

What "done" looks like

• Your repo has a committed .alloy/ corpus with a green alloy validate.
• Every generated doc carries provenance (source_ref and friends), written by alloy stamp.
• alloy status reports coverage with UNKNOWN driven to a decision, not left silent.
• Optionally, spoke CI keeps the corpus honest as the code moves.

Start with step 1 - Survey your repo.