# TUI Session Workflow

Complete walkthrough of using the Cleave TUI for interactive task decomposition.

## Prerequisites

```bash
# Install TUI dependencies
pipx install styrene-cleave[tui]

# Verify installation
cleave --version
cleave config show
```

## Launching the TUI

```bash
# Launch in current directory
cleave tui

# Launch in specific directory
cleave tui /path/to/project

# Launch with custom backend
cleave config set backend ollama
cleave tui
```

## Session Flow

### 1. Start a New Session

When you launch the TUI, you'll see:
- **Chat Panel** (left): Conversation history
- **Control Panel** (right): Session info, status, actions
- **Input Area** (bottom): Multi-line input with history

### 2. Load a Directive

**Option A: Type directly**
```
Add JWT authentication with refresh tokens. Support both access
and refresh token flows. Include token blacklist for logout.
```

**Option B: Load from CALF file**
```
/load auth-migration.calf
```

The TUI will display the loaded directive and begin assessment.

### 3. Assessment Phase

The backend will:
1. Analyze complexity (systems, modifiers)
2. Match against known patterns
3. Determine if cleaving is needed
4. Generate clarifying questions (if needed)

You'll see:
```
Pattern Match: Authentication System (0.85)
Systems: 3 (API, Auth Service, Database)
Modifiers: 2 (Security, State Coordination)
Complexity: 6.0
Decision: Cleave into 2-3 children
```

### 4. Answer Questions

If the assessment identifies ambiguities:

```
Question 1: Should refresh tokens be stored in database or as signed JWTs?
Options:
  a) Database storage (revocable, more secure)
  b) Signed JWTs (stateless, faster)

Your answer: a
```

Use arrow keys to navigate, Enter to submit.

### 5. Review Decomposition

The TUI shows the proposed split:

```
Parent: JWT Authentication Implementation
├── Child 0: Token Infrastructure
│   └── Token generation, validation, refresh flow
├── Child 1: API Integration
│   └── Middleware, endpoints, error handling
└── Child 2: Blacklist & Logout
    └── Token revocation, logout endpoints
```

Approve or refine the decomposition.

### 6. Execution

The TUI executes each child task:
- **Progress indicators** show current child
- **Tool use display** shows file operations
- **Live streaming** of LLM responses

### 7. Reunification

After all children complete:
1. Conflict detection runs automatically
2. `merge.md` generated (if conflicts exist)
3. `review.md` generated (adversarial review)
4. Parent task completes

### 8. Save Session

**Option A: Auto-save on exit**
Sessions are saved to `~/.cleave/sessions/` automatically.

**Option B: Manual save**
```
Ctrl+S or /save session-name
```

### 9. Resume Session

```bash
# List sessions
cleave tui --list-sessions

# Resume session
cleave tui --session session-name
```

## Keyboard Shortcuts

### Input Area
- `Enter` - Submit message
- `Shift+Enter` - New line in input
- `Up/Down` - Navigate input history
- `Ctrl+A` - Start of line
- `Ctrl+E` - End of line
- `Ctrl+K` - Delete to end of line

### Chat Panel
- `Ctrl+L` - Clear chat
- `Escape` - Cancel current operation
- `PgUp/PgDown` - Scroll chat history

### Session Management
- `Ctrl+S` - Save session
- `Ctrl+O` - Open session
- `Ctrl+N` - New session

### Global
- `Tab/Shift+Tab` - Navigate between panels
- `q` - Quit (prompts to save if unsaved changes)
- `Ctrl+C` - Force quit

## TUI Commands

Within the TUI, use slash commands:

- `/load <file>` - Load CALF file
- `/save <name>` - Save session
- `/export` - Export conversation to markdown
- `/clear` - Clear chat
- `/status` - Show session status
- `/help` - Show command help

## Backend Switching

During a session:

```
/backend ollama
```

The TUI will reconnect with the new backend for subsequent messages.

## Debugging

Enable debug logging:

```bash
cleave config set tui.debug true
cleave tui
```

Logs are written to `~/.cleave/tui.log`.

## Example Session Transcript

```
[You]: Add JWT authentication with refresh tokens

[Assistant]: I'll assess this directive for complexity.

[Tool Use: cleave assess]
Pattern: Authentication System (0.85)
Complexity: 6.0
Decision: Cleave

[Assistant]: This requires splitting into 3 children:
1. Token Infrastructure
2. API Integration
3. Blacklist & Logout

Proceeding with decomposition.

[Tool Use: cleave init]
Workspace created: .cleave/

[Assistant]: Executing Child 0: Token Infrastructure

[Tool Use: Write file]
src/auth/tokens.py

[Tool Use: Write file]
tests/test_tokens.py

[Assistant]: Child 0 complete. Status: SUCCESS

[Continuing with Child 1...]

[All children complete]

[Tool Use: cleave reunify]
Conflicts detected: 0
Review generated: .cleave/review.md

[Assistant]: Reunification complete. All tasks succeeded.
JWT authentication implemented with refresh tokens and blacklist.

[You]: /export session.md

[Assistant]: Session exported to session.md
```

## Troubleshooting

### TUI Won't Launch
```bash
# Check dependencies
pip list | grep textual

# Reinstall TUI extras
pipx reinstall styrene-cleave[tui]
```

### Backend Connection Failed
```bash
# Verify backend is running (Ollama example)
curl http://localhost:11434/api/tags

# Check API key (Claude example)
echo $ANTHROPIC_API_KEY
```

### Session Not Saving
```bash
# Check session directory
ls ~/.cleave/sessions/

# Verify permissions
chmod 755 ~/.cleave
chmod 755 ~/.cleave/sessions
```

### Slow Response Times
```bash
# Check backend model size
cleave config show

# Switch to smaller model
cleave config set backends.ollama.default_model qwen2.5-coder:1.5b
```
