docs(chat): add documentation for interactive agent mode

- Introduce `--agent` flag for `grokkit chat` as the new primary way to work with Grok on code
- Describe features: tool calling, safety previews, confirmation, persistent sessions
- Note deprecation of old `grokkit agent` command in v0.3.0
- Mention use of fast non-reasoning model for reliability

README.md

@@ -72,6 +72,23 @@ grokkit chat --debug            # Enable debug logging
 - History is saved automatically between sessions
 - Use `--debug` to see API request timing
 
+### 🧠 `grokkit chat --agent`
+
+**Interactive Agent Mode** — the new primary way to work with Grok on code.
+
+Grok can now call tools directly (`edit`, `scaffold`, `testgen`, `lint`, `commit`) while maintaining full conversation history and safety previews.
+
+```bash
+grokkit chat --agent
+```
+- Uses the fast non-reasoning model for tool reliability
+- Every tool action shows a preview and requires explicit confirmation (y/n)
+- Persistent session — you can iterate, reject changes, or give follow-up instructions
+- Normal grokkit chat (without --agent) remains unchanged (full reasoning model for thoughtful conversation)
+
+**Note**: The old `grokkit agent` command is deprecated and will be removed in v0.3.0. Please migrate to chat --agent.
+
+
 ### ✏️ `grokkit edit FILE "instruction"`
 AI-powered file editing with preview.