# Luzia Help & Documentation

Welcome to the Luzia command help system. This directory contains comprehensive documentation for using Luzia.

## Quick Start

Get help immediately:
```bash
luzia --help
luzia help
luzia -h
```

This displays a comprehensive overview of all available commands with examples.

## Documentation Files

### 1. **In-Command Help** (Immediate)
```bash
luzia --help
```
- **91 lines** of well-organized command categories
- Quick start examples
- All command syntax
- Global flags
- **Best for:** Quick reference while using CLI

### 2. **Cheat Sheet** (Quick Lookup)
📄 **[LUZIA_CHEAT_SHEET.md](./LUZIA_CHEAT_SHEET.md)**
- Essential commands (4 lines)
- Troubleshooting patterns
- Common workflows
- Exit codes
- **Best for:** Finding common patterns quickly

```bash
cat docs/LUZIA_CHEAT_SHEET.md
```

### 3. **Full Command Reference** (Complete)
📄 **[LUZIA_COMMAND_REFERENCE.md](./LUZIA_COMMAND_REFERENCE.md)**
- All 30+ commands with descriptions
- Detailed usage examples
- Pattern explanations
- Configuration guide
- Troubleshooting section
- **Best for:** Understanding all features thoroughly

```bash
cat docs/LUZIA_COMMAND_REFERENCE.md
```

### 4. **Update Summary**
📄 **[HELP_UPDATE_SUMMARY.md](./HELP_UPDATE_SUMMARY.md)**
- What was changed
- Testing results
- Feature coverage
- Files modified/created
- **Best for:** Understanding recent updates

## Command Categories

### 🚀 Quick Start (4 essential commands)
```bash
luzia --help              # Show help
luzia list                # List projects
luzia status              # Check status
luzia <project> <task>    # Run task
```

### 💼 Core Project Commands
- Execute tasks in Docker containers
- Interactive sessions
- Manage project containers
- View project history

### 🔧 Maintenance & System
- Full cleanup with preview
- Job and container management
- System recommendations
- Log viewing

### 🔄 Failure Management
- List failures by exit code
- Show detailed error information
- Smart retry (single or batch)
- Kill stuck jobs

### 📚 Knowledge Graph & QA
- QA validation
- Documentation search (multi-domain)
- Entity lookup
- Statistics
- Sync capabilities

### 🔍 Research (3-Phase Flow)
- Research initiation
- Session management
- Knowledge graph display
- Context → search → synthesize

### 🏗️ Code Analysis
- Structure analysis
- Project-specific analysis
- Subdirectory analysis
- JSON output

### 🧠 Advanced Features
- Deep reasoning (Zen + Gemini 3)
- Troubleshooting assistant
- Queue management
- Notifications

### 🔨 Low-Level Operations
- Raw command execution
- File read/write
- Context retrieval
- JSON output

## Common Workflows

### Check System Health
```bash
luzia list          # See all projects
luzia status        # Overall status
luzia maintenance   # System recommendations
```

### Run a Task
```bash
luzia <project> <task> [args]
```

### Troubleshoot Failures
```bash
luzia failures              # See what failed
luzia failures --summary    # Breakdown by error code
luzia retry <job_id>        # Retry one
luzia failures --auto-retry # Retry all fixable
```

### Research a Topic
```bash
luzia research musica "your question"
luzia research-show <session_id>
luzia research-knowledge musica
```

### Analyze Code
```bash
luzia structure dss --json
luzia docs "search term"
luzia qa --sync
```

### Clean Up
```bash
luzia cleanup --dry-run    # Preview
luzia cleanup              # Execute
```

## Help System Organization

```
┌─ QUICK HELP (In-Command)
│  └─ luzia --help (91 lines, organized by category)
│
├─ CHEAT SHEET (Quick Patterns)
│  └─ Common workflows, quick lookups
│
├─ FULL REFERENCE (Complete Details)
│  └─ All commands, examples, patterns
│
└─ UPDATE SUMMARY (Change Log)
   └─ What changed, testing, coverage
```

## Finding What You Need

**I want to...**
- ✅ See all commands → `luzia --help` or `LUZIA_CHEAT_SHEET.md`
- ✅ Find a command → `LUZIA_COMMAND_REFERENCE.md`
- ✅ See examples → `LUZIA_CHEAT_SHEET.md` (patterns) or `LUZIA_COMMAND_REFERENCE.md` (details)
- ✅ Understand a feature → `LUZIA_COMMAND_REFERENCE.md`
- ✅ Troubleshoot → `LUZIA_COMMAND_REFERENCE.md` (troubleshooting section)
- ✅ Know what changed → `HELP_UPDATE_SUMMARY.md`
- ✅ Work interactively → `luzia --help` (in-command reference)

## Global Flags

Available with any command:
```bash
luzia --help              # Show this help
luzia --verbose           # Detailed output
luzia --fg                # Run in foreground (don't background)
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Project not found |
| 4 | Container error |

## Getting Help

1. **Immediate Help:** `luzia --help`
2. **Quick Patterns:** `cat docs/LUZIA_CHEAT_SHEET.md`
3. **Full Details:** `cat docs/LUZIA_COMMAND_REFERENCE.md`
4. **Recent Changes:** `cat docs/HELP_UPDATE_SUMMARY.md`

## Contributing

When adding new commands to Luzia:

1. Update the main help docstring in `bin/luzia` (lines 1-92)
2. Add examples to `LUZIA_CHEAT_SHEET.md`
3. Add full documentation to `LUZIA_COMMAND_REFERENCE.md`
4. Update this README if significant changes

## File Locations

```
/opt/server-agents/orchestrator/
├── bin/
│   └── luzia                          # Main script (help in docstring)
└── docs/
    ├── README_HELP.md                 # This file
    ├── LUZIA_CHEAT_SHEET.md          # Quick reference
    ├── LUZIA_COMMAND_REFERENCE.md    # Full documentation
    ├── HELP_UPDATE_SUMMARY.md        # Recent changes
    └── ...
```

## Support

For issues or questions:
1. Check `luzia --help` for command syntax
2. Read `LUZIA_COMMAND_REFERENCE.md` for usage patterns
3. See `LUZIA_CHEAT_SHEET.md` for common workflows
4. Review `HELP_UPDATE_SUMMARY.md` for recent changes

---

**Last Updated:** January 9, 2026
**Help System Version:** 2.0
**Coverage:** 27 command handlers, 9 categories, 90+ examples