docs: Stage 6 Quick Start Guide

- Created STAGE6_QUICKSTART.md with practical examples
- Installation verification (23/23 tests passing)
- CLI usage examples for GNS3 deployment script
- Programmatic API examples
- Troubleshooting guide
- Next steps for real device testing

STAGE6_QUICKSTART.md

@@ -0,0 +1,312 @@
+# Stage 6 - Quick Start Guide
+
+## ✅ Installation Complete
+
+**Libraries Installed:**
+```bash
+pip install netmiko>=4.0.0 napalm>=5.0.0 jinja2>=3.1.0
+```
+
+**Test Results:** ✅ 23/23 tests passing
+
+---
+
+## 🚀 Quick Start Examples
+
+### 1. List Available Devices
+```bash
+python examples/deploy_to_gns3_lab.py --list
+```
+
+### 2. Dry-Run Deployment (Safe Testing)
+```bash
+# Test single device (no changes made)
+python examples/deploy_to_gns3_lab.py --device R1 --dry-run
+
+# Test all devices
+python examples/deploy_to_gns3_lab.py --all --dry-run
+```
+
+### 3. Production Deployment
+```bash
+# Deploy to single device (REAL CHANGES!)
+python examples/deploy_to_gns3_lab.py --device R1 --production
+
+# Deploy to all devices
+python examples/deploy_to_gns3_lab.py --all --production
+```
+
+### 4. Custom Credentials
+```bash
+python examples/deploy_to_gns3_lab.py --device SW1 \
+  --username admin \
+  --password mysecret \
+  --dry-run
+```
+
+---
+
+## 📝 Before First Deployment
+
+### Update Device Inventory
+
+Edit `examples/deploy_to_gns3_lab.py` and update the `GNS3_DEVICES` list with your actual device IPs:
+
+```python
+GNS3_DEVICES = [
+    {
+        'name': 'R1',
+        'hostname': '192.168.1.1',  # ← UPDATE THIS
+        'device_type': DeviceType.CISCO_IOS,
+        'vendor': 'cisco',
+        'model': '7200',
+        'role': 'router',
+        'description': 'Core Router 1'
+    },
+    # ... add more devices
+]
+```
+
+### Find Your GNS3 Device IPs
+
+**Option 1 - From GNS3 Web UI:**
+1. Go to http://lab.grahampaasch.com:3080
+2. Open the "overgrowth" project
+3. Right-click each device → "Console"
+4. Run `show ip interface brief` to get management IP
+
+**Option 2 - Use GNS3 API:**
+```bash
+# List all nodes in project
+curl http://lab.grahampaasch.com:3080/v2/projects
+
+# Get device details
+curl http://lab.grahampaasch.com:3080/v2/projects/<project-id>/nodes
+```
+
+---
+
+## 🧪 Run Tests
+
+```bash
+# Run all Stage 6 tests
+python -m pytest tests/test_deployment_engine.py -v
+
+# Run specific test
+python -m pytest tests/test_deployment_engine.py::TestDeviceDriver::test_cisco_ios_connection -v
+
+# Run with detailed output
+python tests/test_deployment_engine.py
+```
+
+---
+
+## 🔧 Programmatic Usage
+
+### Example 1: Deploy with Template
+```python
+from agent.deployment_engine import DeploymentEngine
+from agent.device_driver import DeviceType
+
+engine = DeploymentEngine(use_napalm=True)
+
+device = {
+    'name': 'SW1',
+    'vendor': 'cisco',
+    'model': 'catalyst',
+    'role': 'switch',
+    'mgmt_ip': '192.168.1.10',
+    'interfaces': []
+}
+
+network_context = {
+    'vlans': [
+        {'id': 10, 'name': 'Data'},
+        {'id': 20, 'name': 'Voice'}
+    ],
+    'domain_name': 'lab.local',
+    'ntp_servers': ['192.168.1.1'],
+    'dns_servers': ['8.8.8.8', '8.8.4.4']
+}
+
+credentials = {
+    'username': 'admin',
+    'password': 'cisco',
+    'device_type': DeviceType.CISCO_IOS
+}
+
+# Generate config from template and deploy
+result = engine.generate_and_deploy(
+    device=device,
+    network_context=network_context,
+    credentials=credentials,
+    dry_run=True,  # Set to False for production
+    pre_checks=['command:show version'],
+    post_checks=['interface:GigabitEthernet0/1']
+)
+
+print(f"Status: {result.status.value}")
+print(f"Config deployed: {len(result.config_deployed)} chars")
+```
+
+### Example 2: Deploy Custom Config
+```python
+from agent.deployment_engine import DeploymentEngine, DeploymentTask
+from agent.device_driver import DeviceType
+
+engine = DeploymentEngine(use_napalm=True)
+
+config = """
+hostname R1
+!
+interface GigabitEthernet0/0
+ ip address 10.0.0.1 255.255.255.252
+ no shutdown
+!
+router ospf 1
+ network 10.0.0.0 0.0.0.3 area 0
+!
+end
+"""
+
+task = DeploymentTask(
+    device_id="R1",
+    device_type=DeviceType.CISCO_IOS,
+    hostname="192.168.1.1",
+    username="admin",
+    password="cisco",
+    config=config,
+    dry_run=False,  # Production deployment
+    pre_checks=["ping:192.168.1.1"],
+    post_checks=["command:show ip interface brief"]
+)
+
+result = engine.deploy_single_device(task)
+```
+
+### Example 3: Deploy to Multiple Devices
+```python
+from agent.deployment_engine import DeploymentEngine, DeploymentTask
+from agent.device_driver import DeviceType
+
+engine = DeploymentEngine(use_napalm=True)
+
+tasks = [
+    DeploymentTask(
+        device_id="R1",
+        device_type=DeviceType.CISCO_IOS,
+        hostname="192.168.1.1",
+        username="admin",
+        password="cisco",
+        config="hostname R1",
+        dry_run=True
+    ),
+    DeploymentTask(
+        device_id="R2",
+        device_type=DeviceType.CISCO_IOS,
+        hostname="192.168.1.2",
+        username="admin",
+        password="cisco",
+        config="hostname R2",
+        dry_run=True
+    ),
+]
+
+results = engine.deploy_multiple_devices(tasks, parallel=False)
+
+for result in results:
+    print(f"{result.device_id}: {result.status.value}")
+```
+
+---
+
+## 📚 Available Templates
+
+1. **cisco_ios_l2_switch** - Cisco IOS L2 access switch
+2. **cisco_ios_l3_router** - Cisco IOS L3 router with routing
+3. **cisco_ios_router** - Basic Cisco IOS router
+4. **arista_eos** - Arista EOS switch/router
+5. **juniper_junos** - Juniper JunOS device
+
+See `DEPLOYMENT_GUIDE.md` for template details and variables.
+
+---
+
+## 🔍 Validation Checks
+
+### Pre-Deployment Checks (before config is applied)
+- `ping:192.168.1.1` - Verify device is reachable
+- `command:show version` - Verify device responds
+- `interface:GigabitEthernet0/1` - Check interface exists
+
+### Post-Deployment Checks (after config is applied)
+- `command:show running-config | include hostname` - Verify config
+- `interface:Vlan10` - Verify new VLAN interface exists
+- `ping:10.0.0.1` - Verify routing works
+
+---
+
+## ⚠️ Troubleshooting
+
+### Connection Timeout
+```
+ERROR - Cannot connect to 192.168.1.1
+```
+**Solution:** 
+- Verify device IP is correct
+- Check device is powered on in GNS3
+- Verify SSH is enabled: `ip ssh version 2`
+- Check firewall/network connectivity
+
+### Authentication Failed
+```
+ERROR - Authentication failed
+```
+**Solution:**
+- Verify username/password are correct
+- Check device AAA configuration
+- Try with enable password: `credentials={'secret': 'enable-password'}`
+
+### Template Not Found
+```
+WARNING - No specific template for vendor model
+```
+**Solution:**
+- Check device vendor/model fields
+- Use explicit template: `engine.render_template('cisco_ios_l2_switch', context)`
+
+### Dry-Run Mode Not Working
+**Solution:** Dry-run is enabled by default for safety. Use `--production` flag to actually deploy.
+
+---
+
+## 📖 Next Steps
+
+1. **Update Device IPs** in `examples/deploy_to_gns3_lab.py`
+2. **Run Dry-Run Test** to verify connectivity
+3. **Deploy to Test Device** (one device first)
+4. **Verify Deployment** via console or SSH
+5. **Deploy to Remaining Devices**
+6. **Setup Rollback Testing** (Todo #4)
+7. **Test Parallel Deployment** (Todo #5)
+
+---
+
+## 🎯 Current Status
+
+✅ **Todo 1:** Install netmiko, napalm, jinja2  
+✅ **Todo 2:** Create test suite (23/23 passing)  
+🔄 **Todo 3:** Test with GNS3 lab devices (ready - need to update IPs)  
+⏳ **Todo 4:** Verify rollback functionality  
+⏳ **Todo 5:** Test parallel deployment  
+
+---
+
+## 📞 Support
+
+- **Full Documentation:** `DEPLOYMENT_GUIDE.md`
+- **Test Suite:** `tests/test_deployment_engine.py`
+- **Example Script:** `examples/deploy_to_gns3_lab.py`
+- **Source Code:** `agent/deployment_engine.py`, `agent/device_driver.py`, `agent/config_templates.py`
+
+**For questions, check the test suite - it demonstrates all features!**