# Dependency notes for Zig

`build.zig.zon` pins each dependency to a URL and a hash, or to a local path. The hash says exactly what was fetched. It says nothing about why, which commit was tested, or what has to be checked before it is replaced.

Pacmon keeps a note for each dependency in `.pacmon/zig/DEPENDENCY-NOTES.md`, beside `build.zig.zon`, and shows it on the dependency's field.

![build.zig.zon in VS Code: the first line of each dependency note at the end of its line, and the note for zbench on hover](https://pacmon.dev/shots/zig.png)

*`build.zig.zon` in VS Code.*

## What Pacmon reads

- **Manifest:** `build.zig.zon`
- **Notes file:** `.pacmon/zig/DEPENDENCY-NOTES.md`
- **Section heading:** the direct dependency field: `## known_folders`

Pacmon reads direct fields of the top-level `.dependencies` struct in `build.zig.zon`, including URL/hash, path and lazy dependencies. `build.zig`, system libraries and transitive dependencies are not evaluated.

Pacmon never runs Zig, so it needs no Zig toolchain.

## Example

```zig
.dependencies = .{
    .known_folders = .{
        .url = "git+https://github.com/ziglibs/known-folders#…",
        .hash = "…",
    },
    .zlib = .{
        .path = "deps/zlib",
    },
},
```

`.pacmon/zig/DEPENDENCY-NOTES.md`:

```md
## known_folders

Finds the config and cache directories on each OS.

### Agent notes

- purpose: finds the user's config and cache directories on Linux, macOS and Windows
- constraint: change `.url` and `.hash` together, with `zig fetch --save`
- verify: `zig build test` on Linux and on Windows
```

The heading is the field name in `.dependencies`: `.known_folders` is `## known_folders`, and an escaped name such as `.@"known-folders"` is `## known-folders`.

## For AI coding agents

An agent reads a dependency's section before it adds, updates or removes it, and logs what it did under `### Agent notes`. See [the rules agents follow](https://pacmon.dev/agents/).