@tecet/ollm 0.1.3

package/docs/Hooks/VisualGuide.md

@@ -0,0 +1,598 @@
+# Hooks Panel - Visual Guide
+
+**Visual examples and screenshots of the Hooks Panel UI**
+
+---
+
+## Table of Contents
+
+1. [Panel Overview](#panel-overview)
+2. [Navigation States](#navigation-states)
+3. [Hook States](#hook-states)
+4. [Dialogs](#dialogs)
+5. [Visual Indicators](#visual-indicators)
+6. [Common Scenarios](#common-scenarios)
+
+---
+
+## Panel Overview
+
+### Full Panel Layout
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ 🎣 Hooks Configuration        ↑↓:Nav ➕A:Add ✏️E:Edit 🗑️D:Del 🧪T:Test ⬅️0/Esc:Exit │
+├──────────────────────┬──────────────────────────────────────────────────────┤
+│                      │                                                      │
+│  ⬅️ Exit             │  🎯 format-on-save                                   │
+│                      │                                                      │
+│  ─────────────────   │  ID: format-on-save                                  │
+│                      │                                                      │
+│  📝 File Events      │  ────────────────────────────────────                │
+│    ● format-on-save  │                                                      │
+│    ○ lint-on-save    │  💻 Command:                                         │
+│    ● test-on-change  │    prettier                                          │
+│                      │                                                      │
+│  💬 Prompt Events    │  📋 Arguments:                                       │
+│    ○ validate-input  │    --write {file}                                    │
+│    ● log-prompt      │                                                      │
+│                      │  ────────────────────────────────────                │
+│  👤 User Triggered   │                                                      │
+│    ● custom-hook-1   │  📦 Source: user                                     │
+│    ○ custom-hook-2   │                                                      │
+│                      │  ────────────────────────────────────                │
+│  ▼ More below        │                                                      │
+│                      │  ┌────────────────┐                                  │
+│                      │  │  ✓ Enabled     │                                  │
+│                      │  └────────────────┘                                  │
+│                      │                                                      │
+└──────────────────────┴──────────────────────────────────────────────────────┘
+```
+
+### Panel Components
+
+**Left Column (30%):**
+
+- Exit item at top
+- Category headers with icons
+- Hook items with status indicators
+- Scroll indicators (when needed)
+
+**Right Column (70%):**
+
+- Hook name (bold, yellow)
+- Hook ID
+- Command and arguments
+- Source information
+- Status box (enabled/disabled)
+
+---
+
+## Navigation States
+
+### Browse Mode (Panel Not Focused)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Chat  Tools  [Hooks]  Settings                              │  ← Navigation bar
+└─────────────────────────────────────────────────────────────┘
+```
+
+- "Hooks" is highlighted in navigation bar
+- Press **Enter** to activate panel
+
+### Active Mode (Panel Focused)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🎣 Hooks Configuration                    ↑↓:Nav Enter:Toggle│  ← Panel header
+├──────────────────────┬──────────────────────────────────────┤
+│                      │                                      │
+│  ⬅️ Exit             │  Hook Details                        │  ← Cyan border
+│                      │                                      │
+│  📝 File Events      │                                      │
+│    ● format-on-save  │  (when focused)                      │
+│                      │                                      │
+└──────────────────────┴──────────────────────────────────────┘
+```
+
+- Panel border is cyan
+- Selected hook is highlighted in yellow
+- Keyboard shortcuts active
+
+### Exit Item Selected
+
+```
+┌──────────────────────┐
+│                      │
+│  ⬅️ Exit             │  ← Yellow highlight
+│                      │
+│  ─────────────────   │
+│                      │
+│  📝 File Events      │
+│    ● format-on-save  │
+└──────────────────────┘
+```
+
+- Exit item highlighted in yellow
+- Press **Enter** to exit panel
+- Or press **Esc** or **0**
+
+---
+
+## Hook States
+
+### Enabled Hook
+
+```
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │  ← Green ● indicator
+│    ○ lint-on-save    │
+└──────────────────────┘
+```
+
+- Green ● indicator
+- Hook will execute on trigger
+- Status box shows "✓ Enabled"
+
+### Disabled Hook
+
+```
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │
+│    ○ lint-on-save    │  ← Gray ○ indicator
+└──────────────────────┘
+```
+
+- Gray ○ indicator
+- Hook won't execute
+- Status box shows "✗ Disabled"
+
+### Selected Hook (Focused)
+
+```
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │  ← Yellow highlight
+│    ○ lint-on-save    │
+└──────────────────────┘
+```
+
+- Yellow text highlight
+- Bold text
+- Details shown in right panel
+
+### Selected Hook (Not Focused)
+
+```
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │  ← Normal text
+│    ○ lint-on-save    │
+└──────────────────────┘
+```
+
+- Normal text color
+- Not bold
+- Panel border is not cyan
+
+---
+
+## Dialogs
+
+### Add Hook Dialog
+
+```
+                    ┌────────────────────────────────────┐
+                    │  Add New Hook                      │
+                    ├────────────────────────────────────┤
+                    │                                    │
+                    │  Name: [________________]          │
+                    │                                    │
+                    │  Command: [________________]       │
+                    │                                    │
+                    │  Arguments: [________________]     │
+                    │                                    │
+                    │  ┌──────┐  ┌──────┐               │
+                    │  │ Save │  │Cancel│               │
+                    │  └──────┘  └──────┘               │
+                    │                                    │
+                    │  S:Save  C/Esc:Cancel              │
+                    └────────────────────────────────────┘
+```
+
+- Centered on screen
+- Form fields for hook details
+- Save (S) and Cancel (C/Esc) buttons
+
+### Edit Hook Dialog
+
+```
+                    ┌────────────────────────────────────┐
+                    │  Edit Hook: format-on-save         │
+                    ├────────────────────────────────────┤
+                    │                                    │
+                    │  Name: [format-on-save____]        │
+                    │                                    │
+                    │  Command: [prettier_______]        │
+                    │                                    │
+                    │  Arguments: [--write {file}]       │
+                    │                                    │
+                    │  ┌──────┐  ┌──────┐               │
+                    │  │ Save │  │Cancel│               │
+                    │  └──────┘  └──────┘               │
+                    │                                    │
+                    │  S:Save  C/Esc:Cancel              │
+                    └────────────────────────────────────┘
+```
+
+- Pre-populated with current values
+- Same layout as Add dialog
+- Only available for user hooks
+
+### Delete Confirmation Dialog
+
+```
+                    ┌────────────────────────────────────┐
+                    │  Delete Hook?                      │
+                    ├────────────────────────────────────┤
+                    │                                    │
+                    │  Are you sure you want to delete   │
+                    │  "format-on-save"?                 │
+                    │                                    │
+                    │  ⚠️  This action cannot be undone. │
+                    │                                    │
+                    │  ┌──────┐  ┌──────┐               │
+                    │  │Delete│  │Cancel│               │
+                    │  └──────┘  └──────┘               │
+                    │                                    │
+                    │  D:Delete  C/Esc:Cancel            │
+                    └────────────────────────────────────┘
+```
+
+- Warning message
+- Confirmation required
+- Only available for user hooks
+
+### Test Hook Dialog
+
+```
+                    ┌────────────────────────────────────┐
+                    │  Test Hook: format-on-save         │
+                    ├────────────────────────────────────┤
+                    │                                    │
+                    │  ⏳ Testing hook...                │
+                    │                                    │
+                    │  Simulating: fileEdited event      │
+                    │  Pattern: *.ts                     │
+                    │                                    │
+                    │  ✓ Test passed                     │
+                    │                                    │
+                    │  Hook executed successfully        │
+                    │                                    │
+                    │  ┌──────┐                          │
+                    │  │Close │                          │
+                    │  └──────┘                          │
+                    │                                    │
+                    │  Enter/Esc:Close                   │
+                    └────────────────────────────────────┘
+```
+
+- Shows test progress
+- Displays results (success/failure)
+- Close button to dismiss
+
+---
+
+## Visual Indicators
+
+### Status Indicators
+
+```
+● Green   = Enabled hook
+○ Gray    = Disabled hook
+🎯 Yellow = Selected hook name
+⬅️ Icon   = Exit item
+```
+
+### Category Icons
+
+```
+📝 File Events       - Hooks for file changes
+💬 Prompt Events     - Hooks for prompt submission
+👤 User Triggered    - Manually triggered hooks
+🔄 Session Events    - Session lifecycle hooks
+🤖 Agent Events      - Agent operation hooks
+🧠 Model Events      - Model operation hooks
+🔧 Tool Events       - Tool execution hooks
+📦 Compression Events - Context compression hooks
+🔔 Notifications     - Notification hooks
+```
+
+### Action Icons
+
+```
+➕ A = Add new hook
+✏️ E = Edit hook
+🗑️ D = Delete hook
+🧪 T = Test hook
+🔄 Enter = Toggle hook
+⬅️ 0/Esc = Exit panel
+```
+
+### Scroll Indicators
+
+```
+┌──────────────────────┐
+│  ▲ More above        │  ← Scroll up indicator
+│                      │
+│  📝 File Events      │
+│    ● hook-1          │
+│    ● hook-2          │
+│                      │
+│  ▼ More below        │  ← Scroll down indicator
+└──────────────────────┘
+```
+
+### Border Colors
+
+```
+Cyan border   = Panel has focus
+Gray border   = Panel not focused
+Yellow text   = Selected item
+Green text    = Enabled status
+Red text      = Disabled status
+```
+
+---
+
+## Common Scenarios
+
+### Scenario 1: Browsing Hooks
+
+```
+Step 1: Navigate to Hooks
+┌─────────────────────────────────────┐
+│ Chat  Tools  [Hooks]  Settings      │  ← Press Tab
+└─────────────────────────────────────┘
+
+Step 2: Enter Panel
+┌─────────────────────────────────────┐
+│ 🎣 Hooks Configuration              │  ← Press Enter
+├──────────────────────┬──────────────┤
+│  ⬅️ Exit             │              │
+│                      │              │
+│  📝 File Events      │              │
+└──────────────────────┴──────────────┘
+
+Step 3: Navigate Hooks
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │  ← Press ↓
+│    ○ lint-on-save    │
+└──────────────────────┘
+```
+
+### Scenario 2: Toggling a Hook
+
+```
+Step 1: Select Hook
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │  ← Selected (yellow)
+│    ○ lint-on-save    │
+└──────────────────────┘
+
+Step 2: Toggle
+┌──────────────────────┐
+│  📝 File Events      │
+│    ○ format-on-save  │  ← Press Enter (now disabled)
+│    ○ lint-on-save    │
+└──────────────────────┘
+
+Step 3: Verify Status
+┌────────────────────────────────┐
+│  Status:                       │
+│  ┌────────────────┐            │
+│  │  ✗ Disabled    │            │
+│  └────────────────┘            │
+└────────────────────────────────┘
+```
+
+### Scenario 3: Adding a Hook
+
+```
+Step 1: Open Add Dialog
+Press A
+                    ┌────────────────────────────────────┐
+                    │  Add New Hook                      │
+                    ├────────────────────────────────────┤
+                    │  Name: [________________]          │
+                    │  Command: [________________]       │
+                    │  Arguments: [________________]     │
+                    └────────────────────────────────────┘
+
+Step 2: Fill Form
+                    ┌────────────────────────────────────┐
+                    │  Add New Hook                      │
+                    ├────────────────────────────────────┤
+                    │  Name: [lint-on-save____]          │
+                    │  Command: [eslint_______]          │
+                    │  Arguments: [--fix {file}]         │
+                    └────────────────────────────────────┘
+
+Step 3: Save
+Press S
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │
+│    ● lint-on-save    │  ← New hook added
+└──────────────────────┘
+```
+
+### Scenario 4: Testing a Hook
+
+```
+Step 1: Select Hook
+┌──────────────────────┐
+│  📝 File Events      │
+│    ● format-on-save  │  ← Selected
+│    ○ lint-on-save    │
+└──────────────────────┘
+
+Step 2: Open Test Dialog
+Press T
+                    ┌────────────────────────────────────┐
+                    │  Test Hook: format-on-save         │
+                    ├────────────────────────────────────┤
+                    │  ⏳ Testing hook...                │
+                    └────────────────────────────────────┘
+
+Step 3: View Results
+                    ┌────────────────────────────────────┐
+                    │  Test Hook: format-on-save         │
+                    ├────────────────────────────────────┤
+                    │  ✓ Test passed                     │
+                    │  Hook executed successfully        │
+                    └────────────────────────────────────┘
+```
+
+### Scenario 5: Scrolling Long Lists
+
+```
+Top of List
+┌──────────────────────┐
+│  ⬅️ Exit             │
+│                      │
+│  📝 File Events      │
+│    ● hook-1          │
+│    ● hook-2          │
+│    ● hook-3          │
+│                      │
+│  ▼ More below        │  ← Scroll indicator
+└──────────────────────┘
+
+Middle of List
+┌──────────────────────┐
+│  ▲ More above        │  ← Scroll indicator
+│                      │
+│  💬 Prompt Events    │
+│    ● hook-10         │
+│    ● hook-11         │
+│    ● hook-12         │
+│                      │
+│  ▼ More below        │  ← Scroll indicator
+└──────────────────────┘
+
+Bottom of List
+┌──────────────────────┐
+│  ▲ More above        │  ← Scroll indicator
+│                      │
+│  👤 User Triggered   │
+│    ● hook-48         │
+│    ● hook-49         │
+│    ● hook-50         │
+└──────────────────────┘
+```
+
+---
+
+## Error States
+
+### Corrupted Hooks Warning
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🎣 Hooks Configuration                                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  ⚠️  2 corrupted hook(s) found                       │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                              │
+├──────────────────────┬──────────────────────────────────────┤
+│  ⬅️ Exit             │                                      │
+│                      │                                      │
+│  📝 File Events      │                                      │
+└──────────────────────┴──────────────────────────────────────┘
+```
+
+### No Hooks Available
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🎣 Hooks Configuration                                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│                                                              │
+│                  ┌──────────────────────┐                   │
+│                  │  📭 No hooks available│                   │
+│                  └──────────────────────┘                   │
+│                                                              │
+│              Press A to add a new hook                       │
+│                                                              │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Loading State
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🎣 Hooks Configuration                                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│                                                              │
+│                  ┌──────────────────────┐                   │
+│                  │  ⏳ Loading hooks... │                   │
+│                  └──────────────────────┘                   │
+│                                                              │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tips for Visual Navigation
+
+### Color Coding
+
+- **Yellow** = Current selection (where you are)
+- **Green** = Enabled (will execute)
+- **Gray** = Disabled (won't execute)
+- **Cyan** = Panel focus (active)
+- **Red** = Error or disabled status
+
+### Icon Recognition
+
+Learn the category icons to quickly find hooks:
+
+- 📝 = Files
+- 💬 = Prompts
+- 👤 = User actions
+- 🔄 = Sessions
+
+### Layout Memory
+
+Remember the layout:
+
+- Left = List (what's available)
+- Right = Details (what's selected)
+- Top = Exit (quick way out)
+- Bottom = Scroll indicator (more content)
+
+---
+
+## See Also
+
+- [Keyboard Shortcuts](keyboard-shortcuts.md) - Quick reference for all shortcuts
+- [User Guide](3%20projects/OLLM%20CLI/Hooks/user-guide.md) - Complete hooks documentation
+- [Troubleshooting](3%20projects/OLLM%20CLI/Hooks/user-guide.md#troubleshooting) - Common issues and solutions
+
+---
+
+**Last Updated:** 2026-01-18  
+**Version:** 0.1.0  
+**Feature:** Hooks Panel UI