From 79f5f3c2c838af976e1e3823fdeb1aa1d0617ec1 Mon Sep 17 00:00:00 2001
From: Ogulcan Celik <ogulcancelik@gmail.com>
Date: Tue, 31 Mar 2026 14:26:54 +0300
Subject: [PATCH] docs: clarify release process

---
 AGENTS.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index a5afa393..e27cdab8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,4 +37,13 @@ Integration tests are markdown specs in `tests/integration/specs/`. A pi agent e
 
 ## Releases
 
-`just release 0.x.y` — bumps Cargo.toml, runs tests, commits, tags, pushes. GitHub Actions builds binaries.
+Before cutting a release, draft the upcoming notes under `## Unreleased` in `CHANGELOG.md`. The release script promotes that section into the versioned entry.
+
+Default release flow:
+
+```bash
+just check
+just release 0.x.y
+```
+
+`just release 0.x.y` prepares the changelog entry, bumps `Cargo.toml`, runs tests, commits, tags, and pushes. GitHub Actions builds the binaries after the tag is pushed.