From 4d33d9df8be770c76df29bc29f3805985c47d130 Mon Sep 17 00:00:00 2001
From: Stefan Haller <stefan@haller-berlin.de>
Date: Tue, 7 Jul 2026 15:37:25 +0200
Subject: [PATCH] Mention the `Then` rule in AGENTS.md

---
 AGENTS.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 6aa8f7017..947add510 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -256,6 +256,34 @@ Follow this even when the need for the refactor is only discovered in the middle
 of working on the branch; suggest to the user to rewrite the history to move the
 refactor to an earlier commit (but don't do it without asking first).
 
+## Don't read model state right after a `Refresh`
+
+A `Refresh` (or `RefreshFromWorker`) does its git work on a worker and then
+*enqueues* the model update onto the UI thread. So when `Refresh` returns, the
+model is **not** updated yet — the write is still queued. Reading a field
+synchronously right after refreshing its scope reads the stale, pre-refresh
+value (and this is true even for SYNC refreshes):
+
+```go
+self.c.Refresh(types.RefreshOptions{Scope: []types.RefreshableView{types.FILES}})
+files := self.c.Model().Files // BUG: still the pre-refresh value
+```
+
+Put the read in `RefreshOptions.Then` instead — it's queued after the scope's
+model writes, so it sees the fresh value:
+
+```go
+self.c.Refresh(types.RefreshOptions{
+    Scope: []types.RefreshableView{types.FILES},
+    Then: func() error {
+        files := self.c.Model().Files // fresh
+        return nil
+    },
+})
+```
+
+`Then` is a `func() error` and works with any non-`ASYNC` mode.
+
 ## Integration test conventions
 
 Don't bind views to local variables. Always chain method calls directly from