# Milestone 11: TUI Dashboard

## Overview

Interactive terminal user interface for browsing, searching, and managing the knowledge graph without leaving the terminal.

## Motivation

- CLI commands require knowing what to type
- Visual browsing aids discovery
- Power users prefer staying in terminal
- Real-time feedback on graph state

## Features

### 11.1 Main Dashboard

```bash
# Launch interactive TUI
cortex tui
cortex ui  # Alias
```

Layout:
```
┌─────────────────────────────────────────────────────────────────┐
│  CORTEX                                              Graph: work│
├────────────────────┬────────────────────────────────────────────┤
│  📚 Recent (5)     │  🔍 Search: ________________________      │
│  ├─ Auth flow...   │                                            │
│  ├─ API design...  │  ┌─────────────────────────────────────┐  │
│  └─ DB schema...   │  │ Auth flow design                     │  │
│                    │  │ ─────────────────────                │  │
│  📋 Tasks (3)      │  │ OAuth2 PKCE flow for SPA            │  │
│  ├─ Fix login bug  │  │                                      │  │
│  └─ Update docs    │  │ Tags: auth, security, oauth          │  │
│                    │  │ Status: active                        │  │
│  🔗 Components (8) │  │                                      │  │
│  ├─ UserService    │  │ ── Connections ──                    │  │
│  └─ AuthService    │  │ → implements: OAuth2 spec            │  │
│                    │  │ → contains: Token refresh logic      │  │
│  🎯 Decisions (4)  │  └─────────────────────────────────────┘  │
│  └─ Use JWT...     │                                            │
├────────────────────┴────────────────────────────────────────────┤
│  [/]Search [n]New [e]Edit [d]Delete [l]Link [q]Quit            │
└─────────────────────────────────────────────────────────────────┘
```

### 11.2 Navigation

- Arrow keys / vim keys (hjkl) to navigate
- Enter to select/expand
- Tab to switch panels
- `/` to search
- `?` for help

### 11.3 Quick Actions

| Key | Action |
|-----|--------|
| `n` | New node |
| `e` | Edit selected |
| `d` | Delete selected |
| `l` | Link to another node |
| `t` | Add tags |
| `s` | Change status |
| `/` | Search |
| `g` | Graph view (ASCII) |
| `q` | Quit |

### 11.4 Search Mode

Real-time search as you type:
```
┌─────────────────────────────────────────────────────────────────┐
│  🔍 Search: auth_                                               │
├─────────────────────────────────────────────────────────────────┤
│  1. [component] AuthService (0.95)                              │
│  2. [decision] Use JWT tokens (0.87)                            │
│  3. [memory] Auth flow design (0.82)                            │
│  4. [task] Fix auth bug (0.75)                                  │
└─────────────────────────────────────────────────────────────────┘
```

### 11.5 Graph View Mode

ASCII visualization of connections:
```
┌─────────────────────────────────────────────────────────────────┐
│  Graph View: AuthService                                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│                    ┌──────────────┐                             │
│        depends_on  │ UserService  │                             │
│           ┌───────►│              │                             │
│           │        └──────────────┘                             │
│  ┌────────┴─────┐                                               │
│  │ AuthService  │                                               │
│  │              │──────────┐                                    │
│  └──────────────┘          │ implements                         │
│           │                ▼                                    │
│           │        ┌──────────────┐                             │
│   contains│        │ OAuth2 spec  │                             │
│           ▼        └──────────────┘                             │
│  ┌──────────────┐                                               │
│  │Token refresh │                                               │
│  └──────────────┘                                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 11.6 Edit Mode

Inline editing with validation:
```
┌─────────────────────────────────────────────────────────────────┐
│  Edit: AuthService                                              │
├─────────────────────────────────────────────────────────────────┤
│  Title:   [AuthService                                    ]     │
│  Kind:    [component ▼]                                         │
│  Status:  [active    ▼]                                         │
│  Tags:    [backend, auth, service                         ]     │
│                                                                 │
│  Content:                                                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Handles all authentication operations including:         │   │
│  │ - Login/logout                                           │   │
│  │ - Token management                                       │   │
│  │ - Session handling                                       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [Tab]Next field  [Ctrl+S]Save  [Esc]Cancel                    │
└─────────────────────────────────────────────────────────────────┘
```

## Implementation

### Technology Choice

Use **Ink** (React for CLI) or **blessed-contrib**:

```typescript
// Using Ink
import React from 'react';
import { render, Box, Text, useInput } from 'ink';
import { useState, useEffect } from 'react';

const Dashboard: React.FC = () => {
  const [nodes, setNodes] = useState<Node[]>([]);
  const [selected, setSelected] = useState(0);
  const [mode, setMode] = useState<'browse' | 'search' | 'edit'>('browse');

  useInput((input, key) => {
    if (key.upArrow || input === 'k') setSelected(s => Math.max(0, s - 1));
    if (key.downArrow || input === 'j') setSelected(s => Math.min(nodes.length - 1, s + 1));
    if (input === '/') setMode('search');
    if (input === 'q') process.exit(0);
  });

  return (
    <Box flexDirection="column">
      <Header graph={activeGraph} />
      <Box flexDirection="row">
        <Sidebar nodes={nodes} selected={selected} />
        <DetailPanel node={nodes[selected]} />
      </Box>
      <StatusBar mode={mode} />
    </Box>
  );
};
```

### Component Structure

```
src/tui/
├── index.tsx           # Entry point
├── components/
│   ├── Dashboard.tsx   # Main layout
│   ├── Sidebar.tsx     # Node list
│   ├── DetailPanel.tsx # Node details
│   ├── SearchBox.tsx   # Search input
│   ├── GraphView.tsx   # ASCII graph
│   ├── EditForm.tsx    # Edit mode
│   └── StatusBar.tsx   # Bottom bar
├── hooks/
│   ├── useNodes.ts     # Node data fetching
│   ├── useSearch.ts    # Search state
│   └── useKeyboard.ts  # Key handling
└── utils/
    └── ascii-graph.ts  # ASCII graph renderer
```

### ASCII Graph Renderer

```typescript
// src/tui/utils/ascii-graph.ts
export function renderAsciiGraph(rootId: string, depth: number = 3): string[] {
  const lines: string[] = [];
  const node = getNode(rootId);
  if (!node) return lines;

  const connections = getConnections(rootId);

  lines.push(`┌${'─'.repeat(node.title.length + 4)}┐`);
  lines.push(`│ ${node.title} │`);
  lines.push(`└${'─'.repeat(node.title.length + 4)}┘`);

  for (const conn of connections.outgoing) {
    lines.push(`    │ ${conn.type}`);
    lines.push(`    ▼`);
    lines.push(`┌${'─'.repeat(conn.node.title.length + 4)}┐`);
    lines.push(`│ ${conn.node.title} │`);
    lines.push(`└${'─'.repeat(conn.node.title.length + 4)}┘`);
  }

  return lines;
}
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `cortex tui` | Launch interactive TUI |
| `cortex ui` | Alias |

## Testing

- [ ] Navigation works smoothly
- [ ] Search updates in real-time
- [ ] Edit mode saves correctly
- [ ] Graph view renders correctly
- [ ] Handles large node lists
- [ ] Vim keybindings work
- [ ] Color scheme readable

## Acceptance Criteria

- [ ] Can browse all nodes visually
- [ ] Search is responsive (<100ms)
- [ ] Edit/create nodes without leaving TUI
- [ ] Graph view shows connections
- [ ] Keyboard-only navigation
- [ ] Works in standard terminals

## Estimated Effort

- Ink/blessed setup: 3 hours
- Sidebar component: 3 hours
- Detail panel: 3 hours
- Search component: 3 hours
- Edit form: 4 hours
- Graph view: 4 hours
- Polish/testing: 4 hours
- **Total: ~24 hours**

## Dependencies

- `ink` or `blessed-contrib`
- `react` (for Ink)

## References

- [Ink - React for CLI](https://github.com/vadimdemedes/ink)
- [blessed-contrib](https://github.com/yaronn/blessed-contrib)
- [Lazygit TUI](https://github.com/jesseduffield/lazygit) for inspiration