# Detailed Command Reference Guide

**Purpose**: Complete command documentation with examples and expected outputs
**Audience**: Operators, system administrators, automation engineers
**Scope**: All commands used throughout WDMaker execution

---

## Part 1: Status & Monitoring Commands

### 1.1: Check I-Status Count (Most Important)

**Command**:
```bash
tools/shared/list-sites.sh --batch 001 --status "I" | wc -l
```

**What it does**: Counts how many sites are at "I" (Implemented) status
**Expected output**: A number (0-517)
**Normal output**: Number should increase by ~1-2 every minute during execution
**Abnormal**: Same number for 45+ minutes

**Variations**:
```bash
# Get count with progress indicator
I_COUNT=$(tools/shared/list-sites.sh --batch 001 --status "I" | wc -l)
echo "Progress: $I_COUNT / 517 sites"

# See which sites are at I status
tools/shared/list-sites.sh --batch 001 --status "I" | head -20

# Count with timestamp
echo "[$(date)] I-status: $(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l) / 517"
```

**When to use**: Every 30 minutes during autonomous execution
**Time to run**: < 5 seconds

---

### 1.2: Check All Status Counts

**Command**:
```bash
echo "O: $(tools/shared/list-sites.sh --batch 001 --status 'O' | wc -l)"
echo "i: $(tools/shared/list-sites.sh --batch 001 --status 'i' | wc -l)"
echo "I: $(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l)"
echo "Q: $(tools/shared/list-sites.sh --batch 001 --status 'Q' | wc -l)"
```

**Expected output**:
```
O: 500 (or decreasing)
i: 5 (or 0)
I: 12 (or increasing)
Q: 0 (until finalization)
```

**Normal progression during execution**:
- O decreases (sites moving from Open)
- i small (sites currently processing)
- I increases (completed sites)
- Q stays 0 (until finalization)

**When to use**: Every hour during execution, or when assessing progress
**Time to run**: < 10 seconds

---

### 1.3: List All Sites in Current State

**Command**:
```bash
tools/shared/list-sites.sh --batch 001
```

**Output format**:
```
| Domain | Status | Batch | Updated |
|--------|--------|-------|---------|
| lotus.dev | I | 001 | 2026-03-24T14:00:00 |
| postp.day | O | 001 | 2026-03-24T13:50:00 |
...
```

**Use cases**:
- See full current state of all sites
- Identify which sites are in which state
- Verify registry formatting

**When to use**: When doing comprehensive status check
**Time to run**: < 10 seconds

---

### 1.4: Monitor Sites in In-Progress Status

**Command**:
```bash
tools/shared/list-sites.sh --batch 001 --status "i"
```

**Output**: List of sites currently being processed (status = i)
**Expected**: Usually 0-10 sites (depends on execution speed)
**Abnormal**: > 50 sites stuck at i for 45+ minutes

**With details**:
```bash
# See in-progress sites with details
tools/shared/list-sites.sh --batch 001 --status "i" | tail -20

# Count in-progress
tools/shared/list-sites.sh --batch 001 --status "i" | wc -l
```

**When to use**: When investigating stalled progress
**Time to run**: < 5 seconds

---

## Part 2: System Health Commands

### 2.1: Check Disk Space

**Command**:
```bash
df -h .smbatcher/
```

**Output example**:
```
Filesystem     Size   Used  Avail Use% Mounted on
/dev/disk1s1   466G   300G   150G  67% /
```

**What to look for**:
- **Avail column**: Free space remaining
- Alert if < 1GB free
- Critical if < 500MB free

**Variations**:
```bash
# Human-readable with percentage
df -h | grep smbatcher

# Check overall system
df -h

# Get just available space
df -h .smbatcher/ | tail -1 | awk '{print $4}'
```

**When to use**: Every hour during execution
**Time to run**: < 1 second

---

### 2.2: Check Memory Usage

**Command**:
```bash
free -h
```

**Output example**:
```
              total        used        free      shared  buff/cache   available
Mem:            16Gi       8.2Gi       2.1Gi       1.0Gi       5.7Gi       6.8Gi
```

**What to look for**:
- **available column**: Free memory for new processes
- Alert if < 1GB available
- Critical if < 500MB available

**Variations**:
```bash
# Just available memory
free -h | grep Mem | awk '{print $7}'

# Monitor over time
watch -n 5 'free -h'
```

**When to use**: If experiencing slowdowns or errors
**Time to run**: < 1 second

---

### 2.3: Check CPU Usage

**Command**:
```bash
top -bn1 | head -20
```

**Or simpler**:
```bash
uptime
```

**Output example**:
```
14:30:00 up 2 days, 3:45, 2 users, load average: 2.45, 2.38, 2.41
```

**Interpretation**:
- Load average shows CPU load (higher = more loaded)
- If load > number of CPU cores: System overloaded
- Normal during execution: High load is expected

**When to use**: If system seems unresponsive
**Time to run**: < 1 second

---

## Part 3: Registry & File Commands

### 3.1: Check Registry Exists and Is Readable

**Command**:
```bash
ls -la .smbatcher/REGISTRY.md
```

**Expected output**:
```
-rw-r--r--  1 user  group  12345 Mar 24 14:00 .smbatcher/REGISTRY.md
```

**What to check**:
- File exists (ls doesn't error)
- File size reasonable (> 1KB)
- Recent modification time (within last few minutes during execution)

**If missing**: Emergency - registry corrupted or deleted
**If old timestamp**: Status updates stopped, investigate

**When to use**: When doing health check or after error
**Time to run**: < 1 second

---

### 3.2: Verify Registry Integrity

**Command**:
```bash
grep -c "^|" .smbatcher/REGISTRY.md
```

**Expected output**:
```
569
```

**Explanation**: Should be total sites (568) + 1 header line = 569

**Variations**:
```bash
# Count specific statuses
grep "| I |" .smbatcher/REGISTRY.md | wc -l
grep "| Q |" .smbatcher/REGISTRY.md | wc -l

# Check for duplicates
awk -F'|' '{print $2}' .smbatcher/REGISTRY.md | sort | uniq -d
# If output is empty: No duplicates (good)
# If has output: Duplicates detected (bad)
```

**When to use**: Hourly during execution, before finalization
**Time to run**: < 2 seconds

---

### 3.3: Check File Generation

**Command**:
```bash
ls -d sites/*-v1/ | wc -l
```

**Expected output**: Number of directories created (0-517)
**Normal**: Should match or slightly exceed I-status count

**Verify specific site**:
```bash
# Check if site files exist
ls -la sites/lotus.dev-v1/

# Expected:
# -rw-r--r-- index.html
# -rw-r--r-- styles.css
# -rw-r--r-- script.js
```

**Check all sites have all files**:
```bash
# Count total expected files
EXPECTED=$(($(ls -d sites/*-v1/ | wc -l) * 3))

# Count actual files
ACTUAL=$(find sites/*-v1/ -type f \( -name "index.html" -o -name "styles.css" -o -name "script.js" \) | wc -l)

echo "Expected: $EXPECTED, Actual: $ACTUAL"
```

**When to use**: Spot-check quality, before finalization
**Time to run**: < 5 seconds

---

## Part 4: Execution Commands

### 4.1: Execute Batch 001 Finalization

**Command**:
```bash
tools/implement/finish.sh --batch 001 --root .
```

**What it does**: Transitions all 517 sites from I → Q status
**Expected duration**: < 1 minute
**Expected output**: Success message confirming sites transitioned
**Error output**: If fails, will show error message

**Before running**:
- [ ] Verify all sites at I: `tools/shared/list-sites.sh --batch 001 --status "I" | wc -l` should = 517
- [ ] Check disk space: `df -h` should show > 500MB free
- [ ] Check registry readable: `ls -la .smbatcher/REGISTRY.md` should work

**After running**:
- Verify: `tools/shared/list-sites.sh --batch 001 --status "Q" | wc -l` should = 517

**When to use**: Only when I-status = 517 and pre-checks pass
**Time to run**: < 1 minute

---

### 4.2: Deploy Design Phase

**Command**:
```bash
tools/prepare/mdesign.sh --batch 010 --max-agents 1
```

**What it does**: Generate DESIGN.md for unassigned sites
**Expected duration**: 5-10 minutes
**Expected output**: Status updates showing design generation progress

**Variations**:
```bash
# With multiple agents (for batch 001 originally)
tools/prepare/mdesign.sh --batch 001 --max-agents 25
```

**When to use**: At start of batch 010 processing
**Time to run**: 5-10 minutes

---

### 4.3: Deploy Implementation Phase

**Command**:
```bash
tools/implement/mimplement-bg.sh --batch 001 --max-agents 25
```

**What it does**: Deploy 25 Opus agents to implement sites
**Expected duration**: 10+ minutes (depends on batch size)
**Expected output**: Progress updates as agents complete sites

**Variations**:
```bash
# With different agent count
tools/implement/mimplement-bg.sh --batch 001 --max-agents 50

# For single site
tools/implement/mimplement-bg.sh --batch 010 --max-agents 1

# Requeue stuck sites
tools/implement/mimplement-bg.sh --batch 001 --max-agents 25 --requeue i
```

**When to use**: During implementation phase
**Time to run**: 10 minutes + (depending on agents and site count)

---

## Part 5: Verification Commands

### 5.1: Check Design Compliance

**Command**:
```bash
# Check if DESIGN.md files exist
ls -la .smbatcher/designs/ | head -20

# Count designs
ls .smbatcher/designs/*-DESIGN.md 2>/dev/null | wc -l
```

**Expected output**: Number of DESIGN.md files (should equal sites)

**Verify design content**:
```bash
# Check specific design
cat .smbatcher/designs/lotus.dev-DESIGN.md | head -50

# Check for colors (should have hex codes)
grep "#[0-9A-Fa-f]" .smbatcher/designs/lotus.dev-DESIGN.md
```

**When to use**: After design phase, before implementation
**Time to run**: < 5 seconds

---

### 5.2: Verify Implementation Files

**Command**:
```bash
# Check specific site files
ls -la sites/lotus.dev-v1/

# Check if index.html is valid
head -20 sites/lotus.dev-v1/index.html

# Check CSS for colors
grep "#[0-9A-Fa-f]" sites/lotus.dev-v1/styles.css | head -10
```

**Expected**: All 3 files present (index.html, styles.css, script.js)
**Each file > 0 bytes**

**When to use**: Spot-check during or after implementation
**Time to run**: < 5 seconds

---

## Part 6: Troubleshooting Commands

### 6.1: Full System Status Report

**Command**:
```bash
tools/check/status-report.sh
```

**What it does**: Comprehensive system health check
**Expected output**: Detailed status of all components
**Duration**: 30-60 seconds

**If missing script, manual equivalent**:
```bash
echo "=== BATCH 001 STATUS ===" && \
echo "O: $(tools/shared/list-sites.sh --batch 001 --status 'O' | wc -l)" && \
echo "i: $(tools/shared/list-sites.sh --batch 001 --status 'i' | wc -l)" && \
echo "I: $(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l)" && \
echo "Q: $(tools/shared/list-sites.sh --batch 001 --status 'Q' | wc -l)" && \
echo "" && \
echo "=== SYSTEM RESOURCES ===" && \
echo "Disk: $(df -h .smbatcher/ | tail -1 | awk '{print $4}' )" && \
echo "Memory: $(free -h | grep Mem | awk '{print $7}')" && \
echo "" && \
echo "=== RECENT UPDATES ===" && \
ls -la .smbatcher/REGISTRY.md | awk '{print $6, $7, $8, $9}'
```

**When to use**: Hourly during execution, before major decisions
**Time to run**: < 1 minute

---

### 6.2: Find Stuck Sites

**Command**:
```bash
tools/shared/list-sites.sh --batch 001 --status "i"
```

**Output**: List of sites currently in progress
**Normal**: 0-10 sites (varies with execution)
**Abnormal**: Same sites for 45+ minutes

**If sites stuck**:
```bash
# Get list of stuck sites
STUCK=$(tools/shared/list-sites.sh --batch 001 --status "i")

# Check if they have files
for site in $STUCK; do
  domain=$(echo "$site" | awk -F'|' '{print $2}')
  if [ -d "sites/$domain-v1" ]; then
    echo "$domain: Has directory"
  else
    echo "$domain: No directory"
  fi
done
```

**When to use**: When progress seems stalled
**Time to run**: < 10 seconds

---

### 6.3: Check for Errors in Logs

**Command**:
```bash
# If logs exist
tail -50 logs/batch-001.log | grep -i "error\|fail"

# Or search in files
find . -name "*.log" -exec grep -l "error\|fail" {} \;
```

**Expected**: No error lines (if system healthy)
**Abnormal**: Repeated error messages

**When to use**: When investigating issues
**Time to run**: < 5 seconds

---

## Part 7: Automation Scripts

### 7.1: Continuous Monitoring Loop

**Script** (save as `monitor.sh`):
```bash
#!/bin/bash
while true; do
  clear
  echo "=== WDMaker Status Monitor ==="
  echo "Time: $(date)"
  echo ""
  echo "I-status: $(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l) / 517"
  echo "O-status: $(tools/shared/list-sites.sh --batch 001 --status 'O' | wc -l)"
  echo "i-status: $(tools/shared/list-sites.sh --batch 001 --status 'i' | wc -l)"
  echo ""
  echo "Disk free: $(df -h .smbatcher/ | tail -1 | awk '{print $4}')"
  echo "Registry: $(ls -la .smbatcher/REGISTRY.md | awk '{print $6, $7, $8}')"
  echo ""
  echo "Next update in 30 seconds..."
  sleep 30
done
```

**Use**:
```bash
chmod +x monitor.sh
./monitor.sh
```

**What it does**: Shows status every 30 seconds in a clear format

---

### 7.2: Status Logging

**Script** (save as `log-status.sh`):
```bash
#!/bin/bash
LOG_FILE="monitoring-log.txt"

while true; do
  I_STATUS=$(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l)
  TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
  echo "[$TIMESTAMP] I-status: $I_STATUS / 517" >> $LOG_FILE
  echo "Logged at $TIMESTAMP"
  sleep 1800  # 30 minutes
done
```

**Use**:
```bash
chmod +x log-status.sh
./log-status.sh &  # Run in background
```

**What it does**: Logs I-status every 30 minutes to a file

---

## Part 8: Command Quick Reference (Copy-Paste)

**Monitoring** (run every 30 min):
```bash
echo "[$(date)] I-status: $(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l) / 517"
```

**Health check** (hourly):
```bash
tools/check/status-report.sh
```

**Pre-finalization check**:
```bash
echo "I-count: $(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l)"
echo "O-count: $(tools/shared/list-sites.sh --batch 001 --status 'O' | wc -l)"
```

**Execute finalization**:
```bash
tools/implement/finish.sh --batch 001 --root .
```

**Verify finalization**:
```bash
tools/shared/list-sites.sh --batch 001 --status 'Q' | wc -l
```

**Emergency: Full status**:
```bash
tools/check/status-report.sh
```

---

## Part 9: Interpreting Command Output

### Common Outputs and Their Meanings

**I-status increasing regularly** (e.g., 10 → 25 → 40 → 55):
✅ **Normal** - System is working, making progress

**I-status increasing slowly** (e.g., 10 → 15 → 16 → 17 over 2 hours):
⚠️ **Slower than expected** - Check resources, but may be normal depending on item complexity

**I-status unchanged** (e.g., stays at 50 for 45+ minutes):
❌ **Problem** - Agents may have stopped, investigate immediately

**I-status decreasing** (e.g., 100 → 95 → 90):
❌ **Critical** - Data corruption or major system issue

**Disk space < 500MB**:
❌ **Critical** - System may crash, stop new operations immediately

**Memory < 200MB free**:
❌ **Critical** - System may become unresponsive

**Registry timestamp old** (> 5 min without update during execution):
⚠️ **Issue** - Status updates may not be happening

---

## Conclusion

This command reference provides:
- ✅ Every command needed for project execution
- ✅ Expected outputs and how to interpret them
- ✅ Variations for different scenarios
- ✅ Scripts for automation
- ✅ Troubleshooting procedures

Save this document for quick reference during execution.

---

*Detailed Command Reference Guide: 2026-03-24*
*Purpose: Complete command documentation with examples*
*Audience: Operators, system administrators*
*Status: Ready for reference use*