# Dependency notes for Gleam

`gleam.toml` lists the packages a project needs and the versions it accepts. It does not say why a package is there, why a range is held back, or what to run after it moves.

Depos keeps a note for each dependency in `.depos/gleam/DEPENDENCY-NOTES.md`, beside `gleam.toml`, and shows it on the dependency's line.

## What Depos reads

- **Manifest:** `gleam.toml`
- **Notes file:** `.depos/gleam/DEPENDENCY-NOTES.md`
- **Section heading:** the dependency key: `## gleam_stdlib`, `## gleeunit`

Depos reads direct keys in `[dependencies]` and `[dev_dependencies]` in `gleam.toml`, including version, Hex, Git and path declarations. `manifest.toml`, transitive packages and other tables are not read.

Depos never runs Gleam, so it needs no Gleam or Erlang installation.

## Example

```toml
[dependencies]
gleam_stdlib = ">= 0.44.0 and < 2.0.0"
wisp = ">= 1.2.0 and < 2.0.0"
mist = ">= 3.0.0 and < 4.0.0"

[dev_dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"
```

`.depos/gleam/DEPENDENCY-NOTES.md`:

```md
## wisp

Web framework for the HTTP API; mist serves it.

### Agent notes

- purpose: routing and middleware for the HTTP API
- bump-with: mist
- verify: `gleam test`
- verified: 1.2.0
```

The heading is the dependency's key in `gleam.toml`, under `[dependencies]` or `[dev_dependencies]` alike: `wisp = ">= 1.2.0 and < 2.0.0"` is `## wisp`.

## Comments in gleam.toml

```toml
[dependencies]
gleam_stdlib = ">= 0.44.0 and < 2.0.0"
# wisp: routing and middleware for the HTTP API
wisp = ">= 1.2.0 and < 2.0.0"
mist = ">= 3.0.0 and < 4.0.0" # bump with wisp
```

`gleam.toml` is TOML: `#` starts a comment that runs to the end of the line. `gleam add` and `gleam remove` edit the file in place, so the comments on other lines stay; `gleam remove` takes the comments above and beside the removed dependency with it.

## Pinning a version

`gleam add` writes a range from the version it resolved up to the next major, `">= 1.2.0 and < 2.0.0"`, even when you name a version: `gleam add wisp@1.2.0` writes the same range. A requirement that is just a version, `"1.2.0"` or `"== 1.2.0"`, accepts that version only, and `"~> 1.2"` means `>= 1.2.0 and < 2.0.0`.

`manifest.toml` locks every package to the version Gleam resolved. `gleam deps update` moves them to the newest versions `gleam.toml` allows without changing `gleam.toml`, and `gleam deps update wisp` unlocks wisp and the packages only it needs. Why a range stops where it does goes in the dependency's note, as `constraint:`.

## For AI coding agents

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