# AGENTS.md: Cairn activation
This repository follows **Cairn**, a language- and tool-agnostic convention for keeping a living spec, reviewable change proposals, and an honest history next to the code. The normative format lives in [pimalaya/cairn](https://github.com/pimalaya/cairn) (CAIRN.md for the rules, GUIDE.md for the by-hand procedure). No tooling is required: you create and check the structure by reading and following the rules.
The Cairn root of this repository is [cairn/](./cairn):
- [cairn/spec/](./cairn/spec) current truth, one file per capability. Read it to learn what the crate does today.
- [cairn/changes/](./cairn/changes) proposals for work in flight, one folder per change, archived under `changes/archive/` once landed.
- [cairn/log/](./cairn/log) dated history, one file per landed change, immutable once written.
The src/lib.rs header remains the architecture entry point for the code itself; cairn/spec/ is the behavioural truth behind it. The spec grows by accretion: a capability gets a file the first time a change touches it, so a missing capability means not yet written, not absent.
If you are an agent working in this repository, do the following **by default, without being asked**.
## 1. Before non-trivial work, propose
For anything beyond a trivial fix, create `cairn/changes/<change-id>/` with:
- proposal.md: *why* and *what* (frontmatter: `cairn: change`, `id`, `status: active`, `created`).
- tasks.md: the checklist.
- delta.md: what this changes in the spec, under the three literal headings `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`.
Let the human review intent **before** you write code. Trivial fixes may skip this and go straight to landing.
## 2. After work lands, fold and log (never skip)
- Fold the change's delta into `cairn/spec/<capability>.md` so the spec always reflects current truth (append ADDED, replace MODIFIED, delete REMOVED).
- Append a dated entry `cairn/log/YYYY-MM-DD-<change-id>.md` describing what landed and which capabilities moved.
- Set the change `status: landed` and move its folder to cairn/changes/archive/.
> **The forcing rule:** a change that affects behaviour is not *done* until the spec is updated and the log entry is written.
## 3. Stay conformant
Check the structure yourself against the strict rules (CAIRN.md ยง8): a discoverable root, `spec/ changes/ log/` present, every Cairn file carrying a valid `cairn:` type, each change having proposal.md and tasks.md, kebab-case ids, literal delta headings, and a log entry for every landed change. Everything else (prose, naming, ordering, extra files) is free. cairn/verify.sh runs the same nine checks when a command is wanted.
## 4. Repository conventions
- Run every cargo command through the nix devshell: `nix develop --command cargo <...>`.
- Run `cargo fmt` on the crate after finishing code changes.
- io-msgraph is an I/O-free library: the coroutines take no stream and build on io-http's, and every layer above them sits behind a feature (`client` for the blocking client, `rustls-ring`, `rustls-aws` or `native-tls` for the full client, `ical` and `vcard` for the iCalendar and vCard projections, plus `schemars`). Build both sides of a gate you touch.
- Check the bare core too: `cargo build --no-default-features` must stay no_std, with no std leak.
- The tree follows the API version: the version-agnostic coroutine contract stays at the crate root, everything else lives under `v1`, with one module per Microsoft Graph REST resource under `v1::rest`.
- Public items carry the `Msgraph` domain prefix.
- Never adjust production code to fit a test: adjust the test to match correct behaviour.
- No em dashes in prose, per the Pimalaya guidelines.
- A user-facing change also lands in CHANGELOG.md, which is a release-scoped roll-up over the Cairn log, not a replacement for it.