ec33ac1936
Based on claude-code-tools TmuxCLIController, this refactor: - Added DockerTmuxController class for robust tmux session management - Implements send_keys() with configurable delay_enter - Implements capture_pane() for output retrieval - Implements wait_for_prompt() for pattern-based completion detection - Implements wait_for_idle() for content-hash-based idle detection - Implements wait_for_shell_prompt() for shell prompt detection Also includes workflow improvements: - Pre-task git snapshot before agent execution - Post-task commit protocol in agent guidelines Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
251 lines
5.9 KiB
Markdown
251 lines
5.9 KiB
Markdown
# 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
|