diff --git a/.github/ai-flow.yml b/.github/ai-flow.yml
index a94deff..e3afc4e 100644
--- a/.github/ai-flow.yml
+++ b/.github/ai-flow.yml
@@ -1,8 +1,9 @@
 # ai-flow per-repo configuration (see d3mlabs/ai-flow templates/ai-flow.yml).
 #
 # models: command name => agent model, plus an optional `default` blanket
-# covering unlisted commands. Valid names come from `agent --list-models`
-# on the runner (every ai-flow run also prints the list in its job log).
+# covering unlisted commands. Valid names come from the ACP session
+# catalog, NOT from `agent --list-models` (ai-flow#84); a handle that
+# fails to resolve dumps the catalog (names + modelIds) in the run error.
 # Precedence per command: models.<command> > models.default > CLI default.
 models:
   default: claude-fable-5