UPDATE_GUIDE.md

# HuggingClaw Update: Verdent Features

**Version**: 2.0 - Multi-Model Planning + Code Review

---

## What's New

### 1. Multi-Model Planning (Verdent-Style)

Get implementation plans from Claude + GPT + Gemini, automatically merged.

**Usage**:
```javascript
const { multiModelPlanner } = require('./scripts/verdant');

const result = await multiModelPlanner('Design authentication system');
console.log(result.mergedPlan);
```

**From ZeroClaw**:
```bash
zeroclaw> /plan-multi Design graph schema for Flow Engineering
```

---

### 2. Multi-Perspective Code Review

Review code from 4 perspectives: correctness, architecture, performance, security.

**Usage**:
```javascript
const { codeReviewer } = require('./scripts/verdant');

const reviews = await codeReviewer(diff, codebaseContext);
console.log(reviews.reviews);
```

**From ZeroClaw**:
```bash
zeroclaw> /review <diff>
```

---

### 3. Graph Viewer (Port 7861)

Simple D3-based graph visualization.

**Access**: `https://your-space.hf.space:7861`

**Features**:
- Real-time graph visualization
- Auto-refresh every 10 seconds
- Zoom and pan
- Node/edge count stats

---

## Files Added

```
HuggingClaw/
├── scripts/
│   ├── verdant.js           ← Multi-model planning + code review
│   └── graph-viewer.js      ← Graph viewer API
├── public/
│   └── index.html           ← Graph viewer UI
├── tests/
│   └── verdant.test.js      ← Test cases
└── UPDATE_GUIDE.md          ← This file
```

---

## Resource Usage

| Component | RAM | Notes |
|-----------|-----|-------|
| ZeroClaw | ~200MB | Unchanged |
| OmniRoute | ~100MB | Unchanged |
| Memgraph | ~500MB | Unchanged |
| **Verdent** | **~100MB** | Just orchestration |
| **Graph Viewer** | **~100MB** | Simple D3 |
| **TOTAL** | **~1GB** | **Well under 16GB!** |

---

## Deployment

### 1. Install Dependencies

```bash
cd HuggingClaw
npm install node-fetch express
```

---

### 2. Run Tests

```bash
npm test
```

**Expected output**:
```
  Verdent Features
    Multi-Model Planning
      ✓ should get plans from multiple models (5.2s)
      ✓ should merge conflicting plans (4.8s)
      ✓ should handle failures gracefully (3.1s)
    Multi-Perspective Code Review
      ✓ should find correctness issues (2.1s)
      ✓ should find architectural issues (2.3s)
      ✓ should trace impact beyond diff (1.9s)
      ✓ should handle multiple perspectives (3.5s)
    Resource Usage
      ✓ should stay under memory limits (0.1s)
```

---

### 3. Update Dockerfile

Add these lines to your existing `Dockerfile`:

```dockerfile
# Add after existing npm installs
RUN npm install node-fetch express

# Copy new scripts
COPY scripts/verdant.js /home/node/app/scripts/verdant.js
COPY scripts/graph-viewer.js /home/node/app/scripts/graph-viewer.js
COPY public/ /home/node/app/public/

# Expose graph viewer port
EXPOSE 7861
```

---

### 4. Update entrypoint.sh

Add graph viewer startup:

```bash
# After existing services start
echo "[entrypoint] Starting Graph Viewer..."
node /home/node/app/scripts/graph-viewer.js &

echo "[entrypoint] All services started"
```

---

### 5. Deploy to HF Space

```bash
git add scripts/verdant.js scripts/graph-viewer.js public/ tests/
git commit -m "Add Verdent multi-model features + graph viewer"
git push
```

**HF Space will auto-deploy** (wait 5-10 minutes).

---

## Usage Examples

### Example 1: Multi-Model Planning

```bash
# From ZeroClaw
zeroclaw> /plan-multi Design Flow Engineering requirement schema

Getting plans from multiple models...
  ✓ claude: 2341 chars
  ✓ gpt: 1987 chars
  ✓ gemini: 2156 chars

Merging plans...
✓ Merged plan created

Result:
## Unified Implementation Plan

### Step 1: Define Requirement Nodes
- id: string (unique identifier)
- statement: string (requirement text)
- status: enum (proposed, verified, failed)
...
```

---

### Example 2: Code Review

```bash
# From ZeroClaw
zeroclaw> /review <<EOF
- const CACHE_TTL = 3600;
+ const CACHE_TTL = 0;
EOF

🔍 Reviewing code (4 perspectives)...
  ✓ correctness: 456 chars
  ✓ architecture: 234 chars
  ✓ performance: 567 chars
  ✓ security: 123 chars

✓ Review complete (4/4 perspectives)

Results:
- performance: High severity - Cache disabled, will impact performance
- architecture: Medium severity - Hardcoded value should be configurable
```

---

### Example 3: Graph Viewer

**Open in browser**: `https://your-space.hf.space:7861`

**Or embed in Obsidian**:
- Custom Frame URL: `https://your-space.hf.space:7861`
- Auto-refreshes every 10 seconds

---

## Configuration

### Environment Variables

Add to your HF Space secrets:

| Variable | Value | Purpose |
|----------|-------|---------|
| `OMNIROUTE_URL` | `http://localhost:20128/v1` | OmniRoute endpoint |
| `GRAPH_VIEWER_PORT` | `7861` | Graph viewer port |

---

## Troubleshooting

### "All models failed to generate plans"

**Problem**: OmniRoute not running or misconfigured

**Fix**:
```bash
# Check OmniRoute status
curl http://localhost:20128/v1/chat/completions

# Restart if needed
pm2 restart omniroute
```

---

### "Graph viewer port already in use"

**Problem**: Port 7861 already bound

**Fix**:
```bash
# Check what's using the port
lsof -i :7861

# Kill the process or change port
export GRAPH_VIEWER_PORT=7862
```

---

### "Memory limit exceeded"

**Problem**: Using too much RAM

**Fix**:
```bash
# Check memory usage
docker stats

# Reduce concurrent operations
export MAX_CONCURRENT_REVIEWS=2
```

---

## Next Steps

1. ✅ Test locally first
2. ✅ Run all tests
3. ✅ Deploy to HF Space
4. ✅ Test in production
5. ✅ Add Custom Frame to Obsidian

---

**Version**: 2.0
**Date**: 2026-03-13
**Author**: Flow Engineering Team