Step 1 - Survey your repo

Goal: scaffold the spoke frame, then let the survey agent draft a source config for a repo Alloy has never seen.

Scaffold the frame

From the root of the repo you want to document:

alloy init --spoke

This writes a portable .alloy/ root and refuses to clobber an existing one:

.alloy/alloy.config.yaml                    a self: true source (this repo IS the source; referent = local HEAD)
.alloy/ecosystems.yaml                      standard ecosystem profiles - trim to what your repo needs
.alloy/rulepacks/templates/                 survey-drafted packs and templates land here
.alloy/corpus/meta/corpus-manifest.yaml     the spoke corpus manifest (categories land via survey)
.gitignore                                  .alloy-output/ added

The scaffolded config carries a placeholder discovery block - a valid frame, not yet a working ontology. The survey fills it in. It looks like this:

corpusRoot: .alloy/corpus
sources:
  your-repo:
    self: true # this repo is the source; referent = local HEAD
    # TODO(survey): scanners / units / ecosystems / coverage from the draft.
    scanners: [inventory]

self: true is what makes this a spoke: the source is the enclosing repo, and its drift referent is the repo's own HEAD, so docs and code share one commit history. There is no repo/ref to pin.

Sniff and write the brief

alloy survey . --name your-repo

survey does the deterministic half: it sniffs your repo's ecosystem markers (a pnpm-workspace.yaml, a .sln, a Cargo.toml, and so on) and writes a survey brief for the drafting agent. It invokes no agent and commits nothing - all output lands under the gitignored .alloy-output/:

.alloy-output/survey/your-repo/survey-brief.md

The --name keeps the output path predictable as .alloy-output/survey/<name>/; the draft in the next step lands beside the brief in the same folder. If your repo has no ecosystem markers at all, the sniff says so - that is fine, the agent classifies units by content instead.

Let the agent draft the config

Now hand off to the alloy-survey skill. In your agent:

survey . into alloy

The skill is the probabilistic half. It reads the brief and the real source tree, then drafts the source config as reviewable YAML into:

.alloy-output/survey/your-repo/draft/

It works to a discipline worth knowing about, because it is what keeps the draft honest:

• It reads your repo before it looks at any existing ontology, so it describes what your populations actually are in your repo's vocabulary, rather than pattern-matching onto categories that do not fit.
• It never invents units the tree does not support. Where paths do not predict units, it classifies files by content.
• It triages every candidate to a state. Anything it cannot justify as a unit becomes an exclusion with a written rationale, or it stays UNKNOWN as remaining work - never a silent omission.
• It runs every command; your only acts are review and commit. It never commits anything itself.

When the skill finishes it reports the draft location, a per-file summary, the decompositions it considered and the one it chose, and the final check output. That report is your entry into step 2.

What you did and did not do

You scaffolded a frame and produced a draft under .alloy-output/ - gitignored, uncommitted, disposable. Nothing has touched .alloy/ beyond the scaffold, and nothing is in your corpus yet. The draft is a proposal for you to judge next.

Next: step 2 - Review the draft.