Set up your system map

Tell Zof each service's tier, owner, domains and tags, so its rules judge your changes correctly. It takes about 10 minutes per repository: a member asks for a draft, and a company admin who is also an admin of your GitHub account accepts it.

Zof drafts the map from what the System Graph found in your code, and from the zof.yaml already in use. Nothing in a draft applies until an admin accepts it. For why it works this way, see How Zof understands your system.

Before you start

• The Zof GitHub App is installed and connected to your company, and isn't suspended. See Connect GitHub.
• Your GitHub account is connected in Integrations. Generating, checking and every change need it. Otherwise the row says "Connect your GitHub account to generate a draft."
• The System Graph has read the repository. Until it has, a draft fails with "The system graph hasn't read this repo yet. Generate again after its next scan."
• You have the right role:
  • Anyone in the company can see the map, its drafts and its history.
  • A member or company admin can generate a draft and check it.
  • Accepting, dismissing, adopting and stopping need a company admin in Zof who is also an admin of the GitHub account the Zof GitHub App is installed on. Zof asks GitHub, so the role in Zof alone isn't enough. See Who can do what.
  • Accepting, adopting and stopping also need GitHub to share your verified email with Zof. Zof records who confirmed each version with your GitHub ID and that email.

Generate a draft

Open the repository from Integrations › GitHub. The repository's System map opens in Integrations › GitHub, on the Configuration tab. It opens an existing draft or automatically generates a draft of zof.yaml if none exists. It shows progress and opens the result for review. Nothing applies until you accept it. If generation fails, the page offers a retry; refreshing does not submit another draft automatically.

If you open a copied map link and no draft starts, click Generate draft on the Review tab.

With no draft open, the Review tab shows how much of the repository the map in use covers. When it suggests services for uncovered folders, click Open a draft to add these to start a draft.

You can also generate from Integrations:

1. In the sidebar, open Integrations, open GitHub, then the Configuration tab.
2. Find the repository's row; with 10 or more repositories, use Find a repository. The System map column shows which map is in use. Open the row for the next action, the branches and the project. See System map fields.
3. If a map is already in use, open Generate another draft. You can tick Also suggest changes to values already set. Without it, AI suggestions only fill values that are empty.
4. Click Generate draft.

The row says "Generating a draft…" and checks again every 5 seconds. When the draft is ready, a Draft ready badge appears beside the source badge, with a Review draft button. If the draft is still being made after 5 minutes, the row says "Still generating after 5 minutes. Refresh to check again.", and you can click Refresh.

If a draft is already open, the card leads to Review draft. To start again, an admin must dismiss that draft first. Dismissing discards its edits.

A repository takes at most 10 drafts that people ask for in any 24 hours. Click Draft history on the row to see each draft, who asked for it and how it ended.

AI suggestions are included by default

Click Generate draft to use AI suggestions. AI drafting is enabled for every company, including existing companies and new GitHub connections. There is no activation toggle or separate agreement step.

The draft starts with what the graph found and the values already in use. AI can suggest tier, owner, domains and tags, each with a reason and the files it read. Review and edit the result before an admin clicks Accept. Generating a draft does not commit a file to GitHub; acceptance stores the version in the System Graph.

If AI is unavailable or stops early, Zof labels the result as a basic draft or partial suggestions on the Review tab. You can edit it or generate again later. For details, see What the AI reads and sends.

Review the draft

Click Review draft. The repository's System map opens on the Review tab. The Applied map line stays separate from the draft result. The result panel explains completed, partial or basic drafts. When the recorded reason is truncation, it says the AI answer was cut off; unknown reasons remain unknown. AI usage & source shows recorded counters and the source commit. Indexed paths are a repository listing, not a count of files read.

• Services lets you search and select one service at a time, or use Previous service and Next service. Services with supported protection changes appear first. Each service has Tier, Owner, Domains, Tags and Environments. Under each value is where it came from: In use, AI suggestion or Edited. An AI suggestion also shows its reason and the files it cited. Each cited file links to GitHub at the commit the graph read.
• Above the form, a line says how much of the repository's files the services cover, for example "Services cover 85% of this repo's 1,200 files." When coverage is low, it warns which folders aren't covered: pull requests that change them are treated as unknown risk and need approval. Expand "Add a service for each app folder (N)" and click Add service to add a suggested service with its path to the draft, then set its tier and owner in the form. A new path needs your acknowledgement before an admin accepts.
• Advanced: YAML and full diff contains YAML, the whole file. The form and the YAML stay in step: edit either one. Other keys, such as path, links, endpoints and agents, are edited in the YAML.
• In Advanced, Found by the graph lists the links the System Graph found in the code. They're shown for reference and aren't written into the file.
• In Advanced, No supported suggestion lists the AI suggestions Zof dropped, and why.
• In Advanced, Changes shows every field that differs from the map in use, with the Text diff against the version in use below it.

Before/proposed values and protection explanations appear beside the relevant field. For an AI suggestion, the Use previous control restores a supported previous value from the original draft comparison through the normal editor; this invalidates checks and confirmations. Ambiguous or explicit empty-list values must be edited in YAML instead.

Every key and value is described in System map fields.

Check and accept

1. Click Check. The System Graph checks the file the way it checks a file before storing it. Problems show beside the field they belong to, or under Problems in the file. Fix them and check again.
2. Under Changes that lower protection, expand the summary and review the service groups. Each row shows its before and after values and explains why it relaxes protection or changes authority. Use the one confirmation for the explained group. A stored-copy takeover, unfamiliar change or change marked as still needing confirmation has its own checkbox. On a repository with no zof.yaml, the stored-copy checkbox reads "Keep this map in Zof, not in a zof.yaml file": nothing is replaced now, but a zof.yaml added later won't apply until you stop using the stored copy. Raw identifiers are available only in the expert details. See Changes that lower protection.
3. Click Accept.

Any edit clears the ticks and the list may be out of date, so check again after you edit, then confirm the current changes. If the screen says "The graph can't check drafts yet; any problems show when you accept.", accept anyway: the System Graph refuses a file with problems, and the draft stays open to fix.

After Accept, the screen says "Storing…", then collapses the review into "Accepted as vN — saving to the system graph", with the accepting login when Zof can confirm it. This usually completes within a minute; a busy graph can take up to an hour. The screen checks automatically with increasing waits, and changes to "Confirmed vN" only when that same version is confirmed for your company and in use. Open History from the summary to inspect the version.

If automatic checks stop after an hour or cannot read the status, the summary says the accepted version is still unconfirmed and offers Refresh. If a newer stored version replaces it, the summary says so. Refresh checks the accepted version again; it never submits the draft a second time.

If you're not a company admin, Accept is off and says "Ask an admin to accept". To drop a draft instead, an admin clicks Dismiss.

If the screen says GitHub didn't share a verified email, click Reconnect GitHub, approve again on GitHub, and accept again. GitHub sends you back to the same screen.

Adopt or stop a stored copy

A stored copy is a map accepted in the Zof console, kept by the System Graph. While one is in use, the repository's own zof.yaml is ignored. Adopting and stopping need a company admin who is also a GitHub admin of the account.

1. On the repository card, click View system map or Open system map. You don't need an open draft.
2. On the Review tab, find the Applied map line. Its actions are beside the status line.
3. Click Adopt or Stop using the stored copy:
   • Adopt shows when the copy in use was confirmed under a previous connection, or outside this company. The badge says "Confirmed vN under a previous connection", and no draft can be made until an admin adopts or stops it. Adopting stores the same text again as this company's, so it stays in use. The map itself doesn't change. Confirm with Adopt.
   • Stop using the stored copy makes the repository's own zof.yaml apply again. Zof shows what changes. Tick each change that lowers protection, then click Stop using it. If the repository has no zof.yaml, it has no map after stopping. The stored versions stay in History.

When Zof drafts by itself

You don't have to ask again after every change. Zof drafts by itself in two cases, and never applies these drafts on its own:

• The structure changed. When the System Graph reads a new commit and the services or links it finds differ from the ones the latest draft here was built on, Zof drafts again. It notices within about an hour of the graph reading the commit. A repository with no draft here yet gets none of these.
• The weekly check. Every Monday at 06:00 UTC, Zof drafts any repository whose structure moved since its latest draft here, and any repository with no map at all that has never had a draft here.

These drafts only fill empty values, and use AI only when it's on. Draft history shows them as requested by "Drift" or "Weekly". Zof holds a structure draft back when:

• it already made one for the repository in the last 24 hours;
• an open draft has the same structure;
• a draft is being made;
• the copy in use was confirmed under a previous connection.

A held change waits for the next commit or the weekly check.

What the bell tells you

Zof tells you in the console's bell, never by email:

• Company admins hear when a draft is ready, including the ones Zof made by itself, with how many services and fields changed and how many changes lower protection. They also hear when a draft Zof started by itself failed.
• The person who accepted, stopped or adopted a map hears when Zof couldn't store it, and why. When Zof can't tell who that was, or that person hasn't linked GitHub in Zof or isn't in this company, company admins hear instead.

Each one opens the repository's System map, on the Configuration tab of Integrations › GitHub. You can turn them off in Notification settings.

Your map on Home

While a new company's repositories are read, Home shows Mapping your services, and Explore your map opens Topology once one is ready. See Get your first report. Viewers are asked to contact a company admin when a draft or confirmation is needed.

Check that it worked

1. Open Integrations › GitHub, then the Configuration tab. Open the repository's row. Under System map, the badge reads "Accepted as vN, applying…".
2. Reload the page later. Once the System Graph has applied it, the badge reads "Confirmed vN", in green.
3. On the repository's System map, open the History tab. Under Stored versions, the new version says "Accepted from a draft" and "In use". Opening a newly accepted version refreshes an earlier list. If the list is delayed or its refresh fails, the known version details stay visible with a refresh message; the page does not claim that no version exists.

If something goes wrong

Other messages say what to do in their own words. A map that couldn't be read never shows as mapped: the badge says "Couldn't check". If a message keeps coming back, email support@zofai.com with the message.