diff --git a/README.md b/README.md
index 3c5ba81..48ff5d4 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,22 @@
   # AI Repo Commander — Demo Repository
-  ✅ Verified multi-command flow and upsert via `update_file`.
-  This line was added to confirm update behavior.
\ No newline at end of file
+
+  This repo is used to validate end-to-end operation of the AI Repo Commander userscript:
+  Assistant → Bridge → n8n → Gitea → back to chat.
+
+  ## What’s Verified
+  - **Upsert writes** via `update_file` (creates if missing; updates if present)
+  - **List directory** via `list_files`
+  - **Read file** via `get_file`
+
+  ## Usage Notes
+  - Use **one runnable command per fenced code block** when sending commands from chat.
+  - Avoid putting runnable commands inside docs content.
+  - If you need to show command examples in docs, mark them inert in the future with an `example: true` field (not used here).
+
+  ## Supported Actions (this demo)
+  - `update_file`: action, repo, path, content
+  - `list_files`: action, repo, path
+  - `get_file`: action, repo, path
+
+  ## Changelog (demo)
+  - 2025-10-14: Verified upsert + list + read flows.
\ No newline at end of file