From 097a81fbe762a25584073c94528fc8d3c9ef9d6e Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Fri, 24 Apr 2026 00:31:01 +0100
Subject: [PATCH] docs: document read-only models list

---
 docs/cli/models.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/cli/models.md b/docs/cli/models.md
index 1895bc9a201..b9906327323 100644
--- a/docs/cli/models.md
+++ b/docs/cli/models.md
@@ -44,6 +44,9 @@ Probe rows can come from auth profiles, env credentials, or `models.json`.
 Notes:
 
 - `models set <model-or-alias>` accepts `provider/model` or an alias.
+- `models list` is read-only: it reads config, auth profiles, existing catalog
+  state, and provider-owned catalog rows, but it does not rewrite
+  `models.json`.
 - `models list --all` includes bundled provider-owned static catalog rows even
   when you have not authenticated with that provider yet. Those rows still show
   as unavailable until matching auth is configured.