Files

admin ec33ac1936 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

5.9 KiB

Raw Blame History

Luzia Help & Documentation

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

Quick Start

Get help immediately:

luzia --help
luzia help
luzia -h

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

Documentation Files

1. In-Command Help (Immediate)

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

Essential commands (4 lines)
Troubleshooting patterns
Common workflows
Exit codes
Best for: Finding common patterns quickly

cat docs/LUZIA_CHEAT_SHEET.md

3. Full Command Reference (Complete)

📄 LUZIA_COMMAND_REFERENCE.md

All 30+ commands with descriptions
Detailed usage examples
Pattern explanations
Configuration guide
Troubleshooting section
Best for: Understanding all features thoroughly

cat docs/LUZIA_COMMAND_REFERENCE.md

4. Update Summary

📄 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)

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

luzia list          # See all projects
luzia status        # Overall status
luzia maintenance   # System recommendations

Run a Task

luzia <project> <task> [args]

Troubleshoot Failures

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

luzia research musica "your question"
luzia research-show <session_id>
luzia research-knowledge musica

Analyze Code

luzia structure dss --json
luzia docs "search term"
luzia qa --sync

Clean Up

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:

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

Immediate Help: luzia --help
Quick Patterns: cat docs/LUZIA_CHEAT_SHEET.md
Full Details: cat docs/LUZIA_COMMAND_REFERENCE.md
Recent Changes: cat docs/HELP_UPDATE_SUMMARY.md

Contributing

When adding new commands to Luzia:

Update the main help docstring in bin/luzia (lines 1-92)
Add examples to LUZIA_CHEAT_SHEET.md
Add full documentation to LUZIA_COMMAND_REFERENCE.md
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:

Check luzia --help for command syntax
Read LUZIA_COMMAND_REFERENCE.md for usage patterns
See LUZIA_CHEAT_SHEET.md for common workflows
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

5.9 KiB Raw Blame History