Refactor cockpit to use DockerTmuxController pattern

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>
2026-01-14 10:42:16 -03:00
commit ec33ac1936
265 changed files with 92011 additions and 0 deletions
--- a/docs/HELP_UPDATE_SUMMARY.md
+++ b/docs/HELP_UPDATE_SUMMARY.md
@@ -0,0 +1,189 @@
+# Luzia Help Reference Update - Summary
+
+**Date:** January 9, 2026
+**Status:** ✅ Complete
+
+## What Was Updated
+
+### 1. Main Help Docstring (bin/luzia)
+Updated the Python docstring at the top of the `luzia` script with:
+- Clear "QUICK START" section
+- Organized command categories:
+  - Core Project Commands
+  - Maintenance & System
+  - Failure Management
+  - Knowledge Graph & QA
+  - Research (3-Phase Flow)
+  - Code Analysis
+  - Advanced Reasoning
+  - Queue Management
+  - Low-Level Operations
+- Global flags section
+- Practical examples
+- Reference to full documentation
+
+**File:** `/opt/server-agents/orchestrator/bin/luzia`
+**Lines:** 1-92 (docstring)
+
+### 2. Comprehensive Command Reference (NEW)
+Created detailed markdown documentation with:
+- Overview and quick start
+- All 30+ commands with descriptions
+- Usage patterns and examples
+- Configuration details
+- Troubleshooting guide
+- Exit codes
+
+**File:** `/opt/server-agents/orchestrator/docs/LUZIA_COMMAND_REFERENCE.md`
+
+### 3. Quick Reference Cheat Sheet (NEW)
+Created concise cheat sheet with:
+- Essential commands (4 lines)
+- Troubleshooting patterns
+- System maintenance
+- Project work commands
+- Knowledge base queries
+- Research patterns
+- Code analysis
+- Advanced features
+- Common patterns
+
+**File:** `/opt/server-agents/orchestrator/docs/LUZIA_CHEAT_SHEET.md`
+
+## Testing
+
+✅ Tested help output:
+```bash
+python3 bin/luzia --help
+```
+
+Output is clean, well-organized, and 91 lines of comprehensive documentation.
+
+## Features Documented
+
+### Core Features
+- ✅ Project execution (`<project> <task>`)
+- ✅ Interactive sessions (`work on <project>`)
+- ✅ List/status management
+- ✅ Container management (stop, cleanup)
+
+### Maintenance
+- ✅ Full cleanup (jobs, containers, logs)
+- ✅ Dry-run preview
+- ✅ Job listing and management
+- ✅ Maintenance recommendations
+
+### Failure Management
+- ✅ List failures with exit codes
+- ✅ Show failure details
+- ✅ Summary by exit code
+- ✅ Smart retry (all fixable)
+- ✅ Individual retry
+- ✅ Kill stuck jobs
+
+### Knowledge Graph & QA
+- ✅ QA validation
+- ✅ Code sync to KG
+- ✅ Multi-domain doc search
+- ✅ Entity details
+- ✅ KG statistics
+- ✅ Markdown sync
+
+### Research (3-Phase Flow)
+- ✅ Research initiation (context → search → synthesize)
+- ✅ Research listing
+- ✅ Session details
+- ✅ Knowledge graph display
+- ✅ Phase updates (internal)
+- ✅ KG entity addition (internal)
+
+### Code Analysis
+- ✅ Structure analysis
+- ✅ Project-specific analysis
+- ✅ Subdirectory analysis
+- ✅ JSON output
+- ✅ KG integration control
+
+### Advanced Features
+- ✅ Deep reasoning (`think deep`)
+- ✅ Troubleshooting (`fix`)
+- ✅ Queue management
+- ✅ Notifications
+
+### Low-Level Operations
+- ✅ Raw command execution
+- ✅ File read/write
+- ✅ Context retrieval
+- ✅ JSON output format
+
+### Global Flags
+- ✅ Help (`--help`, `-h`, `help`)
+- ✅ Verbose mode
+- ✅ Foreground execution
+
+## Organization
+
+The help system now has three levels:
+
+1. **Quick Help** (in-command): `luzia --help` (91 lines, well-organized)
+2. **Cheat Sheet**: `/docs/LUZIA_CHEAT_SHEET.md` (practical patterns)
+3. **Full Reference**: `/docs/LUZIA_COMMAND_REFERENCE.md` (complete details)
+
+## Key Improvements
+
+1. **Better Organization**: Commands grouped by category
+2. **Clearer Examples**: Real-world usage patterns
+3. **Exit Codes**: Now documented
+4. **Quick Start**: Easy entry for new users
+5. **Complete Coverage**: All 27 command handlers documented
+6. **Accessibility**: Cheat sheet for quick lookups
+
+## Files Modified/Created
+
+| File | Type | Status |
+|------|------|--------|
+| `bin/luzia` | Modified | ✅ Updated docstring (lines 1-92) |
+| `docs/LUZIA_COMMAND_REFERENCE.md` | New | ✅ Created |
+| `docs/LUZIA_CHEAT_SHEET.md` | New | ✅ Created |
+| `docs/HELP_UPDATE_SUMMARY.md` | New | ✅ Created (this file) |
+
+## Usage
+
+### View Help
+```bash
+luzia --help
+python3 bin/luzia --help
+./bin/luzia --help
+```
+
+### Quick Reference
+```bash
+cat docs/LUZIA_CHEAT_SHEET.md
+```
+
+### Full Documentation
+```bash
+cat docs/LUZIA_COMMAND_REFERENCE.md
+```
+
+## Next Steps
+
+- Commands are now fully documented
+- Users can discover features via `luzia --help`
+- Cheat sheet available for quick lookups
+- Full reference for detailed exploration
+- Help system is discoverable and comprehensive
+
+## Stats
+
+- **Command handlers documented:** 27
+- **Help docstring lines:** 91
+- **Documentation files created:** 2
+- **Total documentation lines:** 500+
+- **Command categories:** 9
+
+---
+
+**Status:** Ready for use
+**Last Updated:** 2026-01-09
+**Next Review:** When new commands are added