Map an existing journey

Statecraft can take a flow that already lives in your codebase — checkout, sign-up, settings, onboarding — and turn it into a Statecraft project. An agent reads the relevant slice of your repo, recreates each screen on the canvas using your real components, and wires the transitions between them. You're prototyping against production reality from minute one.

Before you start

Two things need to be in place:

• A design system imported from the same repo (or a related one). The agent renders states with these components, so they need to be available. See Import your design system.
• The Statecraft GitHub App installed on the account or org that owns the repo you want to read from. Install once via Account → GitHub access → Install GitHub App; after that, any future import from a repo under the same owner is one click.

Starting an import

From the workspace home, click Import from repo → (next to the New project button). The form asks for:

• Repo — owner/name. The dropdown only shows repos visible to a GitHub App install on your account; if the repo you want isn't there, the form offers an Install GitHub App button that deep-links to the right install screen.
• Branch or ref — optional. Defaults to the repo's default branch.
• Framework + design system — the project's framework locks at creation, and the design-system picker is filtered to compatible ones (Vue DSes for Vue projects, etc.).
• Mode — Survey first or Targeted journey. The difference matters; see below.

Survey first (the default)

Survey mode is the right choice when you're new to the codebase, or when you want a map of what's there before committing. The agent scans the repo, proposes a list of candidate journeys — each with a name, a summary, an estimated state count, and the key files it'd read — and hands you a picker.

Tick the journeys you want and click Import N journeys. Statecraft spins up one project per pick, in parallel. The parent run keeps a dashboard view linking out to each child so you can watch the whole batch materialize at once.

Targeted journey

If you already know exactly which flow you want — "the checkout flow", "team-invite acceptance" — pick Targeted journey, name it, and add a one-line description. The agent skips the survey step and goes straight to building one project. Faster, and the framing you give in the description shapes what it pays attention to.

What you see while it runs

The run page shows a live transcript of the agent's progress — which files it's reading, which screens it's committing, the reasoning behind each decision. As soon as the first state lands, a link to the project canvas appears and states materialize there in real time. You can open the canvas and watch the prototype build itself.

Builds usually finish in a few minutes. If the agent gets stuck (an auth-walled file it can't read, an ambiguous layout) it surfaces the error on the run page rather than failing silently.

Refining after the first build

The first build is rarely the last word. On the run page, the chat box stays available — type any follow-up instruction in plain English and the agent re-runs against the existing project, making surgical edits:

• "The success state should show the order ID."
• "Add an empty state for when the cart has no items."
• "The error layout should match the loading layout — right now the header disappears."

Refinements stack — keep iterating until the prototype matches what you have in your head. You can also intervene mid-build: queue a prompt while the agent is still working and it'll pick it up at the next turn boundary.

What's next

Once a journey is on the canvas, the next move is editing it: prototype how you like covers the three editing surfaces (visual, IDE, agent). To send the result to stakeholders, see Share with users and colleagues.