1  # Autocomplete & Explain Command Guide
  2  
  3  ## Overview
  4  
  5  Kamaji TUI now features intelligent autocomplete and an `explain` command to make the interface more discoverable and user-friendly!
  6  
  7  ---
  8  
  9  ## Autocomplete Features
 10  
 11  ### 1. **Live Suggestions Panel**
 12  
 13  As you type, a suggestions panel appears showing matching commands:
 14  
 15  ```
 16  You type: "@r"
 17  
 18  ┌─ Suggestions ─────────────────────────────┐
 19  │ @review     Code review specialist agent  │
 20  │ @docs       Documentation specialist       │
 21  └───────────────────────────────────────────┘
 22  ```
 23  
 24  ### 2. **Tab Completion**
 25  
 26  Press `Tab` to autocomplete to the best matching command:
 27  
 28  ```
 29  You type: "@r" + Tab
 30  → Autocompletes to: "@review"
 31  
 32  You type: "exp" + Tab
 33  → Autocompletes to: "explain"
 34  ```
 35  
 36  ### 3. **Command Discovery**
 37  
 38  Just start typing and see what's available:
 39  
 40  ```
 41  Type "@" → See all agent commands
 42  Type "/" → See all file commands
 43  Type "e" → See explain, clear, etc.
 44  ```
 45  
 46  ---
 47  
 48  ## Available Commands
 49  
 50  ### Agent Commands
 51  - `@review` - Code review specialist agent
 52  - `@docs` - Documentation specialist agent
 53  - `@help` - Show available agents
 54  
 55  ### Meta Commands
 56  - `explain [topic]` - Show documentation for a topic
 57  - `clear` - Clear conversation history
 58  
 59  ### File Commands
 60  - `/files` - Show loaded files
 61  - `/add [file]` - Add a file to context
 62  - `/pwd` - Show current directory
 63  - `/ls` - List files in current directory
 64  - `/loadpy` - Load all Python files
 65  
 66  ### History Commands
 67  - `/history` - Show command history
 68  - `/clearhistory` - Clear command history
 69  
 70  ---
 71  
 72  ## The `explain` Command
 73  
 74  ### What It Does
 75  
 76  Shows Kamaji documentation formatted as readable English (no markdown syntax clutter).
 77  
 78  ### Usage
 79  
 80  ```
 81  explain [topic]
 82  ```
 83  
 84  ### Available Topics
 85  
 86  | Topic | Documentation |
 87  |-------|---------------|
 88  | `agents` | Multi-agent system guide |
 89  | `architecture` | System architecture overview |
 90  | `integration` | Integration examples |
 91  | `usage` | Complete usage guide |
 92  | `multi agent` | Same as "agents" |
 93  | `code review` | Code review agent details |
 94  | `documentation agent` | Documentation agent details |
 95  | `routing` | Agent routing information |
 96  
 97  ### Examples
 98  
 99  #### Example 1: Learn About Agents
100  
101  ```
102  You: explain agents
103  
104  Kamaji: 📚 Documentation: Agents
105  
106  MULTI-AGENT SYSTEM GUIDE
107  ========================
108  
109  Quick Start: Using Multiple Agents
110  
111  In Chat Mode
112  
113  kamaji chat
114  
115  Then use @agent_name prefix:
116  
117    You: @review Check auth.py
118    → Uses code review agent
119  
120    You: @docs Write README for the project
121    → Uses documentation agent
122  
123  [... continues with formatted, readable content ...]
124  ```
125  
126  #### Example 2: Understand Architecture
127  
128  ```
129  You: explain architecture
130  
131  Kamaji: 📚 Documentation: Architecture
132  
133  KAMAJI ARCHITECTURE GUIDE
134  =========================
135  
136  Current Architecture Overview
137  
138  1. Commands vs Agents vs Tools
139  
140  Commands (CLI entry points):
141    - kamaji chat - Interactive chat with agent tools
142    - kamaji tui - Beautiful TUI interface
143    - kamaji ask - One-shot question answering
144  
145  [... etc ...]
146  ```
147  
148  #### Example 3: Topic Not Found
149  
150  ```
151  You: explain foobar
152  
153  Kamaji: ⚠️ Not Found
154  
155  ❌ Topic 'foobar' not found.
156  
157  Available topics:
158    • agents
159    • architecture
160    • code review
161    • documentation agent
162    • integration
163    • multi agent
164    • routing
165    • usage
166  ```
167  
168  ---
169  
170  ## Markdown Formatting
171  
172  The `explain` command converts markdown to clean, readable English:
173  
174  ### Headers
175  
176  ```markdown
177  # Header
178  ```
179  →
180  ```
181  HEADER
182  ======
183  ```
184  
185  ### Bold Text
186  
187  ```markdown
188  **important**
189  ```
190  →
191  ```
192  important (context makes it clear)
193  ```
194  
195  ### Inline Code
196  
197  ```markdown
198  `code_example`
199  ```
200  →
201  ```
202  'code_example'
203  ```
204  
205  ### Lists
206  
207  ```markdown
208  - Item one
209  - Item two
210  ```
211  →
212  ```
213    - Item one
214    - Item two
215  ```
216  
217  ### Code Blocks
218  
219  ```markdown
220  ```python
221  def hello():
222      pass
223  ```
224  ```
225  →
226  ```
227    def hello():
228        pass
229  ```
230  
231  ---
232  
233  ## Tips & Tricks
234  
235  ### Tip 1: Explore Commands
236  
237  Type a single character and see what comes up:
238  
239  ```
240  @  → All agent commands
241  /  → All file/path commands
242  e  → explain, etc.
243  c  → clear
244  ```
245  
246  ### Tip 2: Use Tab Liberally
247  
248  Don't type the whole command - Tab is your friend:
249  
250  ```
251  "@r" + Tab = "@review"
252  "exp" + Tab = "explain"
253  "/f" + Tab = "/files"
254  ```
255  
256  ### Tip 3: Quick Help
257  
258  ```
259  explain usage    → Comprehensive usage guide
260  @help            → Available agents
261  /files           → See what files are loaded
262  ```
263  
264  ### Tip 4: Learn As You Go
265  
266  Whenever you want to know more about a feature:
267  
268  ```
269  explain agents        → Learn about multi-agent system
270  explain architecture  → Understand how it works
271  explain integration   → See code examples
272  ```
273  
274  ---
275  
276  ## Technical Details
277  
278  ### How Autocomplete Works
279  
280  1. **Character-by-character matching**: As you type, the system searches for commands that start with your input
281  2. **Best match selection**: Tab completes to the shortest matching command
282  3. **Live updates**: Suggestions panel updates in real-time
283  4. **Smart ranking**: Results sorted by length (shortest first) then alphabetically
284  
285  ### How Explain Works
286  
287  1. **Topic matching**: Case-insensitive search through topic dictionary
288  2. **File lookup**: Finds corresponding .md documentation file
289  3. **Markdown parsing**: Line-by-line conversion to readable English
290  4. **Clean formatting**: Removes markdown syntax, preserves structure
291  
292  ### Adding New Commands
293  
294  To add a new autocomplete command, edit `kamaji/autocomplete.py`:
295  
296  ```python
297  self.commands: Dict[str, Tuple[str, str]] = {
298      "your_command": ("Description here", "category"),
299      # ...
300  }
301  ```
302  
303  ### Adding New Explain Topics
304  
305  To add a new explanation topic:
306  
307  ```python
308  self.explain_topics: Dict[str, str] = {
309      "your topic": "YOUR_DOC_FILE.md",
310      # ...
311  }
312  ```
313  
314  ---
315  
316  ## Summary
317  
318  **Autocomplete**:
319  - Type and see suggestions
320  - Tab to complete
321  - Discover commands as you type
322  
323  **Explain**:
324  - `explain [topic]` to learn
325  - Readable English formatting
326  - All documentation accessible
327  
328  This makes Kamaji much more discoverable and user-friendly! No more guessing what commands are available or digging through README files.
329  
330  Try it: `kamaji tui` then type `@` or `explain usage`!