git:20260705.480f0e5 to git:20260830.b19945a

1 added, 1 removed. Audit A to A.

# AGENTS.md — fonds/

Agent documentation for the `fonds/` directory.

---

## Purpose

`fonds/` holds **passive data resource pools** — typed, versioned collections that projects reference but do not modify directly. Agents operating here curate, validate, and augment data assets.

---

## Agent entry points

### Reading a fond

```python

import yaml, pathlib

fond_root = pathlib.Path("fonds/my_bibliography")

manifest = yaml.safe_load((fond_root / "fonds.yaml").read_text())

data_dir = fond_root / "data"

```

### Discovering all fonds

```python

import yaml, pathlib

for manifest_path in pathlib.Path("fonds").glob("*/fonds.yaml"):

manifest = yaml.safe_load(manifest_path.read_text())

print(manifest_path.parent.name, "→", manifest["type"])

```

---

## Workflow conventions

| Operation | Convention |

|---|---|

| **Validate** | Check that `fonds.yaml` exists and parses cleanly before any data operation |

| **Append** | Add new entries to `data/` files; never overwrite existing entries without a version bump |

| **Version bump** | Increment `version` in `fonds.yaml` when schema changes |

| **Deduplication** | Agents are expected to deduplicate on ingest (key: `id` or canonical field) |

| **Dry-run** | Always support a dry-run mode that previews changes without writing |

---

## Fond types and their schemas

### bibliography

- `data/references.bib` — BibTeX source of truth

- `data/references.csv` — derived flat export; columns: `key,type,title,author,year,journal,doi`

- Dedup key: BibTeX cite key (first column in CSV)

### contacts

- `data/contacts.yaml` — YAML list of contact objects

- `data/contacts.json` — JSON mirror (kept in sync)

- Dedup key: `id` field (slug, e.g. `jane-doe`)

### datasets

- `data/datasets.yaml` — YAML list of dataset descriptors

- `data/datasets.json` — JSON mirror

- Dedup key: `id` field (slug, e.g. `mnist-2010`)

---

## Validation checklist

Before committing changes to a fond, verify:

- [ ] `fonds.yaml` is valid YAML and contains `type`, `description`, `version`

- [ ] `data/` contains at least one non-empty file

- [ ] Dedup key is unique across all entries

- [ ] No binary blobs > 1 MB committed without LFS annotation

- [ ] `.gitignore` is present

---

## Creating a new template fond

```bash

# Bibliography

cp -r fonds/templates/template_bibliography fonds/templates/template_<name>

# Edit fonds.yaml, AGENTS.md, README.md, and populate data/

```

---

## Cross-references

- - `projects/AGENTS.md` — how projects reference fonds via `fonds_ref`

+ - `projects/templates/template_pools_rules_tools/` — project exemplar that reads fonds via `src/fonds_reader.py` (no `fonds_ref` front-matter mechanism; projects consume fonds directly from `fonds/templates/`)

- `fonds/templates/` — canonical exemplars for each fond type