System map fields

Every zof.yaml key the System map review shows, what Zof does with it, and which values it accepts. Also the words the screens use: where a value came from, the source badges, the changes that need a tick, and what the AI did.

To set up a map, see Set up your system map. For the ideas behind it, see How Zof understands your system.

The file

A system map is one zof.yaml document with up to four top-level keys:

When you check or accept, the System Graph refuses any other top-level key. A service the graph doesn't already know needs a path, or the graph refuses it.

Service keys

The review form shows Tier, Owner, Domains, Tags and Environments. The other keys are edited in the YAML view. Only the first four can come from an AI suggestion.

The graph's own links show under Found by the graph on the review screen. They aren't written into the file, so a link the code stops showing doesn't live on in it.

Where a value came from

Under each value on the review form, and in the Origin column of Changes:

Source badges

The System map column on the Configuration tab of the GitHub page says which map is in use. A map Zof couldn't read never shows as mapped.

Changes that lower protection

These changes make Zof less strict, or move authority. Each one is listed under Changes that lower protection. In draft review, the explained changes are grouped by service with before and after values; one informed confirmation acknowledges every row in that group. Takeovers, unfamiliar changes and changes explicitly flagged by the server retain individual checkboxes. Stopping a stored copy retains a checkbox per change. Zof still refuses the operation unless every required change is acknowledged:

• a higher tier number, such as 0 to 2, or a tier other than 0 on a service that had none (no tier counts as the strictest);
• a tag removed;
• tags set (even an empty list) on a service whose tags were unknown, because tag rules that applied to it may stop applying;
• a service removed;
• a calls, reads, writes or depends_on link removed;
• an owner added, changed or removed, because an owner can approve and take over changes;
• a path added, changed or removed, because it moves files between services;
• an endpoints entry added, changed or removed, because it moves an env var's calls between services;
• any change to agents, because it changes who a bot acts for;
• a key in the map in use that Zof can't keep, so it would be lost;
• a stored copy put in use where none was. Its row reads "Use a stored copy instead of the repo's own zof.yaml": from then on the repository's own zof.yaml stops applying, until an admin stops using the stored copy. When the repository has no zof.yaml, as on a first map, the row reads "Keep this map in Zof, not in a zof.yaml file": nothing is replaced now, but a zof.yaml added later doesn't apply until an admin stops using the stored copy.

Lowering a tier number, adding a link and changing domains need no tick. Adding a tag needs none when the service already had tags. A new service needs acknowledgement for each owner, path, tags list, or tier other than 0 it gets. Any edit clears the ticks, so check again after you edit. A row Zof still wants after you accept is marked "Still needs a tick".

The same rules judge Stop using the stored copy: Zof compares the stored copy with the repository's own zof.yaml, and an absent file means every value becomes unset.

AI status

The line under the status on the review screen says what the AI did for the draft:

Whatever the status, the draft still carries what the graph found and the values in use. Zof runs the AI once per draft and never retries it, so to try again, generate a new draft.

Why a suggestion was dropped

Zof checks every AI suggestion before it reaches the draft. One that fails a check is left out, and the field keeps its earlier value, or stays empty. The dropped ones are listed under No supported suggestion: