luzia/docs/LUZIA_COMMAND_REFERENCE.md

# Luzia Command Reference

**Luzia** is the unified access point for managing all tasks and projects in the server agents infrastructure.

## Quick Start

```bash
luzia --help                    # Show all commands
luzia list                      # List all available projects
luzia status                    # Show current system status
luzia <project> <task>          # Run a task in a project
```

---

## Core Commands

### Project Execution

| Command | Description |
|---------|-------------|
| `luzia <project> <task>` | Execute a task in a project's Docker container |
| `luzia work on <project>` | Start interactive session for a project (delegates to subagent) |
| `luzia list` | List all available projects with their status |
| `luzia status [project]` | Show overall status or specific project status |
| `luzia stop <project>` | Stop a running container |
| `luzia history <project>` | View recent changes in a project |

**Examples:**
```bash
luzia musica analyze logs
luzia work on overbits
luzia list
luzia status dss
```

---

## Maintenance & System Commands

### Cleanup Operations

| Command | Description |
|---------|-------------|
| `luzia cleanup` | Full maintenance (jobs + containers + logs) |
| `luzia cleanup jobs` | Clean old job directories only |
| `luzia cleanup containers` | Stop stale containers only |
| `luzia cleanup --dry-run` | Preview cleanup without deleting |

**Examples:**
```bash
luzia cleanup --dry-run
luzia cleanup containers
luzia cleanup jobs
```

### System Status

| Command | Description |
|---------|-------------|
| `luzia maintenance` | Show maintenance status and recommendations |
| `luzia jobs [job_id]` | List all jobs or show details for a specific job |
| `luzia logs [project]` | View project execution logs |

**Examples:**
```bash
luzia maintenance
luzia jobs
luzia jobs abc123def
luzia logs dss
```

---

## Job Management

### Failure Management (Smart Retry)

| Command | Description |
|---------|-------------|
| `luzia failures` | List recent failures with exit codes |
| `luzia failures <job_id>` | Show detailed failure information |
| `luzia failures --summary` | Summary breakdown by exit code |
| `luzia failures --auto-retry` | Auto-retry all fixable failures |
| `luzia retry <job_id>` | Retry a specific failed job |
| `luzia kill <job_id>` | Kill a running agent job |

**Examples:**
```bash
luzia failures
luzia failures abc123def
luzia failures --summary
luzia failures --auto-retry
luzia retry abc123def
luzia kill abc123def
```

---

## Knowledge Graph & Documentation

### QA & Validation

| Command | Description |
|---------|-------------|
| `luzia qa` | Run QA validation checks |
| `luzia qa --sync` | Sync code to knowledge graph |

**Examples:**
```bash
luzia qa
luzia qa --sync
```

### Documentation Search

| Command | Description |
|---------|-------------|
| `luzia docs <query>` | Search all knowledge graphs |
| `luzia docs sysadmin <query>` | Search sysadmin domain |
| `luzia docs --show <entity>` | Show entity details from KG |
| `luzia docs --stats` | Show knowledge graph statistics |
| `luzia docs --sync` | Sync .md files to knowledge graph |

**Examples:**
```bash
luzia docs docker setup
luzia docs sysadmin nginx
luzia docs --show nginx
luzia docs --stats
luzia docs --sync
```

---

## Research & Analysis

### Research Commands (3-Phase Flow)

| Command | Description |
|---------|-------------|
| `luzia research [project] <topic>` | Start research (context → search → synthesize) |
| `luzia deep research [project] <topic>` | Same as research (alias) |
| `luzia web research [project] <topic>` | Same as research (alias) |
| `luzia research-list [project]` | List research sessions |
| `luzia research-show <session_id>` | Show research session details |
| `luzia research-knowledge [project]` | Show project knowledge graph |

**Examples:**
```bash
luzia research musica database optimization
luzia deep research dss performance tuning
luzia web research overbits authentication
luzia research-list dss
luzia research-show sess_abc123
luzia research-knowledge musica
```

### Internal Research Operations (Called During Flow)

| Command | Description |
|---------|-------------|
| `luzia research-update <id> <phase> <json>` | Update research phase (internal) |
| `luzia research-graph <id> <json>` | Add entities to knowledge graph (internal) |

---

## Code Analysis & Intelligence

### Structural Analysis

| Command | Description |
|---------|-------------|
| `luzia structure` | Analyze current orchestrator structure |
| `luzia structure <project>` | Analyze a specific project |
| `luzia structure . path/src` | Analyze specific subdirectory |
| `luzia structure --json` | Output analysis as JSON |
| `luzia structure --no-kg` | Don't save to knowledge graph |

**Examples:**
```bash
luzia structure
luzia structure dss
luzia structure . lib/docker_bridge.py
luzia structure --json > analysis.json
luzia structure --no-kg
```

---

## Advanced Features

### Deep Reasoning

| Command | Description |
|---------|-------------|
| `luzia think deep <topic>` | Deep reasoning via Zen + Gemini 3 |

**Examples:**
```bash
luzia think deep "how to optimize docker image size"
```

### Troubleshooting

| Command | Description |
|---------|-------------|
| `luzia fix <issue>` | Troubleshooting assistant |

**Examples:**
```bash
luzia fix "container not starting"
```

### Notifications

| Command | Description |
|---------|-------------|
| `luzia notify` | View notifications |
| `luzia notifications` | Alias for notify |

---

## Queue Management (Advanced)

| Command | Description |
|---------|-------------|
| `luzia queue` | Show queue status |
| `luzia dispatch <job>` | Dispatch a job to the queue |

**Examples:**
```bash
luzia queue
luzia dispatch research_agent
```

---

## Low-Level Operations

These are primarily for internal use:

| Command | Description |
|---------|-------------|
| `luzia --exec <project> <command>` | Execute raw command (JSON output) |
| `luzia --read <project> <path>` | Read file contents (JSON output) |
| `luzia --write <project> <path> <content>` | Write to file (JSON output) |
| `luzia --context <project>` | Get project context (JSON output) |

**Examples:**
```bash
luzia --exec musica ls -la
luzia --read dss /workspace/config.json
luzia --write overbits /workspace/test.txt "content here"
luzia --context librechat
```

---

## Global Flags

| Flag | Description |
|------|-------------|
| `--help`, `-h`, `help` | Show this help message |
| `--verbose` | Enable verbose output |
| `--fg` | Run in foreground (don't background) |

**Examples:**
```bash
luzia --help
luzia --verbose status
luzia --fg musica analyze data
```

---

## Exit Codes

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

---

## Common Patterns

### 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>
```

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

### Research a Topic
```bash
luzia research musica "how to optimize queries"
luzia research-show <session_id>
luzia research-knowledge musica
```

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

---

## Configuration

Configuration is loaded from `/opt/server-agents/orchestrator/config.json`:

```json
{
  "projects": {
    "musica": {
      "image": "musica:latest",
      "port": 3000
    },
    ...
  }
}
```

---

## Troubleshooting

### "Unknown: <command>"
The command wasn't recognized. Use `luzia --help` to see valid commands.

### "Permission denied"
You may not have permission to run commands in that project. Check your user permissions.

### Container errors
Run `luzia cleanup containers` to stop stale containers, then try again.

### Job failures
Use `luzia failures` to see what went wrong, then `luzia retry <job_id>`.

---

## See Also

- `/opt/server-agents/orchestrator/docs/` - Full documentation
- `/opt/server-agents/CLAUDE.md` - Project instructions
- `/etc/claude/GLOBAL.md` - Global server rules