# Dependency notes for Rust

A line in `Cargo.toml` records a crate, a version requirement and a feature list. Why the crate is there, why a feature is off, or which targets an upgrade has to be tested on does not fit on that line — and in a workspace, the same crate turns up in many members.

Pacmon keeps a note for each dependency in `.pacmon/cargo/DEPENDENCY-NOTES.md`, beside `Cargo.toml`, and shows it on the dependency's line. A workspace member without a notes file of its own uses the nearest one above it, so one file at the workspace root can cover every member.

![Cargo.toml in VS Code: a mark before each dependency, the first line of its note at the end of the line, and the whole note for dotenvy on hover](https://pacmon.dev/shots/rust.png)

*`Cargo.toml` in VS Code.*

## What Pacmon reads

- **Manifest:** `Cargo.toml`
- **Notes file:** `.pacmon/cargo/DEPENDENCY-NOTES.md`
- **Section heading:** the dependency key, usually the crate name: `## serde`

Pacmon reads `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` and their `[target.…]` forms. A member's `serde.workspace = true` counts; `[workspace.dependencies]` itself does not.

Pacmon never runs Cargo and does not read `Cargo.lock`.

## Example

```toml
[dependencies]
http = "0.2"
http1 = { package = "http", version = "1" }
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.42", features = ["rt-multi-thread", "macros"] }
```

`.pacmon/cargo/DEPENDENCY-NOTES.md`, two of its sections:

```md
## http1

The http 1.x types, renamed so they can sit next to http 0.2 during the hyper upgrade.

### Agent notes

- purpose: request and response types for the new hyper 1 server
- remove-when: nothing uses http 0.2 any more; then rename this back to http

## tokio

Runtime for the API server and the job workers. Keep the feature list short.

### Agent notes

- purpose: async runtime for the API server and the background job workers
- constraint: no `full` feature — enable only what the code uses
- verify: `cargo test --workspace`
- verified: 1.42.0
```

A renamed dependency is keyed by the name the manifest gives it: `## http1` above, not `## http`.

## For AI coding agents

An agent reads a crate's section before it adds, upgrades or removes the crate, and records what it did under `### Agent notes`. `remove-when:` tells it when a dependency has served its purpose. See [the rules agents follow](https://pacmon.dev/agents/).