# Uni-Wizard v4 — Quick Reference

## Installation

```bash
# Run setup script
sudo ./scripts/setup-uni-wizard.sh

# Or manual install
cd uni-wizard/v4
pip install -e .
```

## Basic Usage

```python
from uni_wizard import Harness, House, Mode

# Create harness
harness = Harness(house=House.TIMMY, mode=Mode.INTELLIGENT)

# Execute tool
result = harness.execute("git_status", repo_path="/path/to/repo")

# Check prediction
print(f"Predicted success: {result.provenance.prediction:.0%}")

# Get result
if result.success:
    print(result.data)
else:
    print(f"Error: {result.error}")
```

## Command Line

```bash
# Simple execution
uni-wizard execute git_status --repo-path /path

# With specific house
uni-wizard execute git_status --house ezra --mode intelligent

# Batch execution
uni-wizard batch tasks.json

# Check health
uni-wizard health

# View stats
uni-wizard stats
```

## Houses

| House | Role | Best For |
|-------|------|----------|
| `House.TIMMY` | Sovereign | Final decisions, critical ops |
| `House.EZRA` | Archivist | Reading, analysis, documentation |
| `House.BEZALEL` | Artificer | Building, testing, implementation |
| `House.ALLEGRO` | Dispatch | Routing, connectivity, tempo |

## Modes

| Mode | Use When | Features |
|------|----------|----------|
| `Mode.SIMPLE` | Scripts, quick tasks | Direct execution, no overhead |
| `Mode.INTELLIGENT` | Production work | Predictions, learning, adaptation |
| `Mode.SOVEREIGN` | Critical decisions | Full provenance, approval gates |

## Common Tasks

### Check System Status
```python
result = harness.execute("system_info")
print(result.data)
```

### Git Operations
```python
# Status
result = harness.execute("git_status", repo_path="/path")

# Log
result = harness.execute("git_log", repo_path="/path", max_count=10)

# Pull
result = harness.execute("git_pull", repo_path="/path")
```

### Health Check
```python
result = harness.execute("health_check")
print(f"Status: {result.data['status']}")
```

### Batch Operations
```python
tasks = [
    {"tool": "git_status", "params": {"repo_path": "/path1"}},
    {"tool": "git_status", "params": {"repo_path": "/path2"}},
    {"tool": "system_info", "params": {}}
]
results = harness.execute_batch(tasks)
```

## Service Management

```bash
# Start services
sudo systemctl start uni-wizard
sudo systemctl start timmy-health
sudo systemctl start timmy-task-router

# Check status
sudo systemctl status uni-wizard

# View logs
sudo journalctl -u uni-wizard -f
tail -f /opt/timmy/logs/uni-wizard.log

# Restart
sudo systemctl restart uni-wizard
```

## Troubleshooting

### Service Won't Start
```bash
# Check logs
journalctl -u uni-wizard -n 50

# Verify config
cat /opt/timmy/config/uni-wizard.yaml

# Test manually
python -m uni_wizard health
```

### No Predictions
- Check pattern database exists: `ls /opt/timmy/data/patterns.db`
- Verify learning is enabled in config
- Run a few tasks to build patterns

### Gitea Integration Failing
- Verify API token in config
- Check Gitea URL is accessible
- Test: `curl http://143.198.27.163:3000/api/v1/version`

## Configuration

Location: `/opt/timmy/config/uni-wizard.yaml`

```yaml
house: timmy
mode: intelligent
enable_learning: true

pattern_db: /opt/timmy/data/patterns.db
log_level: INFO

gitea:
  url: http://143.198.27.163:3000
  token: YOUR_TOKEN_HERE
  poll_interval: 300

hermes:
  stream_enabled: true
  db_path: /root/.hermes/state.db
```

## API Reference

### Harness Methods

```python
# Execute single tool
harness.execute(tool_name, **params) -> ExecutionResult

# Execute async
await harness.execute_async(tool_name, **params) -> ExecutionResult

# Execute batch
harness.execute_batch(tasks) -> List[ExecutionResult]

# Get prediction
harness.predict(tool_name, params) -> Prediction

# Get stats
harness.get_stats() -> Dict

# Get patterns
harness.get_patterns() -> Dict
```

### ExecutionResult Fields

```python
result.success          # bool
result.data            # Any
result.error           # Optional[str]
result.provenance      # Provenance
result.suggestions     # List[str]
```

### Provenance Fields

```python
provenance.house              # str
provenance.tool               # str
provenance.mode               # str
provenance.prediction         # float
provenance.execution_time_ms  # float
provenance.input_hash         # str
provenance.output_hash        # str
```

---

*For full documentation, see ARCHITECTURE.md*
