The loop

The whole of Foundry is four commands you run from your product repo.

1. Init

foundry init

Scaffolds a project that already renders:

• spec/ with a starter project.md and one flow file.
• wiresmith.yml and design.md for the rendering side.
• a first screen, flows/home/01-home.desktop.html, so foundry serve shows something on the first run.
• an AGENTS.md that teaches your coding agent the conventions used here.

It never overwrites: run it in an existing project and it adds only what is missing.

2. Author with your agent

You do not write the spec alone. You describe the product to your coding agent, and it writes the spec/ files to the format. The conventions file from init is what keeps it on the rails: the file layout, the single spec: block per file, and the rules the checks enforce. See Working with an agent.

3. Check

foundry check

Runs every coherence check against the spec and exits non zero if any fails. Wire it into CI so a pull request that breaks the spec cannot merge. This is what makes "the spec cannot drift" operational: the spec is reviewed in a pull request like code, and the gate is a machine, not a person.

4. Render and preview

foundry serve [--port <n>]   # live canvas with reload while you author
foundry build [--out <dir>]  # a deployable static site

Foundry renders the flows as labelled lanes on an infinite canvas, each screen an isolated device frame, through the wiresmith renderer. The canvas is spec aware: it flags a rendered screen that is not in the spec (drift), a spec'd screen that renders nothing (a coverage gap), and any check finding, right on the frame. See Wireframes.

5. Share it

foundry build writes a self contained static site, so sharing is whatever you already do with static files: commit it, drop it on any host, or open index.html from disk. The spec travels in the same repository, which is the point.

Versioning is the same answer. The spec is markdown in your repository, so a tag is a version and git diff is the history. Foundry does not add a second system beside git.

A structural diff, in the vocabulary of the spec rather than of the text, is the one thing git cannot express: it cannot tell a reordered YAML block from a change of meaning. It is written and tested, but not wired to a command yet, because the "before" side belongs to a git ref and that plumbing is still to come.

Running from elsewhere

Every command takes the project root as a flag, which is what you want in a monorepo or a CI job:

foundry -C packages/app check

Next

A brief, end to end runs this loop on a real project, from a vague client message to clickable screens.