feat(demo): add complete TSYS developer support stack demo implementation

Add full demo environment with 13 services across 4 categories:
- Infrastructure: Homepage, Docker Socket Proxy, Pi-hole, Portainer
- Monitoring: InfluxDB, Grafana
- Documentation: Draw.io, Kroki
- Developer Tools: Atomic Tracker, ArchiveBox, Tube Archivist,
  Wakapi, MailHog, Atuin

Includes:
- Docker Compose templates with dynamic environment configuration
- Deployment orchestration scripts with user ID detection
- Comprehensive test suite (unit, integration, e2e)
- Pre-deployment validation with yamllint, shellcheck
- Full documentation (PRD, AGENTS, README)
- Service configurations for all components

All services configured for demo purposes with:
- Dynamic UID/GID mapping
- Docker socket proxy security
- Health checks and monitoring
- Service discovery via Homepage labels

Ports allocated 4000-4099 range with sequential assignment.

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>

demo/docs/troubleshooting/README.md

@@ -0,0 +1,291 @@
+# TSYS Developer Support Stack - Troubleshooting Guide
+
+## Common Issues and Solutions
+
+### Services Not Starting
+
+#### Issue: Docker daemon not running
+**Symptoms**: `Cannot connect to the Docker daemon`
+**Solution**:
+```bash
+sudo systemctl start docker
+sudo systemctl enable docker
+```
+
+#### Issue: Port conflicts
+**Symptoms**: `Port already in use` errors
+**Solution**:
+```bash
+# Check what's using the port
+netstat -tulpn | grep :4000
+
+# Kill conflicting process
+sudo fuser -k 4000/tcp
+```
+
+#### Issue: Environment variables not set
+**Symptoms**: `Variable not found` errors
+**Solution**:
+```bash
+# Check demo.env exists and is populated
+cat demo.env
+
+# Re-run user detection
+./scripts/demo-stack.sh deploy
+```
+
+### Health Check Failures
+
+#### Issue: Services stuck in "starting" state
+**Symptoms**: Health checks timeout
+**Solution**:
+```bash
+# Check service logs
+docker compose logs [service-name]
+
+# Restart specific service
+docker compose restart [service-name]
+
+# Check resource usage
+docker stats
+```
+
+#### Issue: Network connectivity problems
+**Symptoms**: Services can't reach each other
+**Solution**:
+```bash
+# Check network exists
+docker network ls | grep tsysdevstack
+
+# Recreate network
+docker network create tsysdevstack_supportstack-demo
+
+# Restart stack
+docker compose down && docker compose up -d
+```
+
+### Permission Issues
+
+#### Issue: File ownership problems
+**Symptoms**: `Permission denied` errors
+**Solution**:
+```bash
+# Check current user
+id
+
+# Verify UID/GID detection
+cat demo.env | grep -E "(UID|GID)"
+
+# Fix volume permissions
+sudo chown -R $(id -u):$(id -g) /var/lib/docker/volumes/tsysdevstack_*
+```
+
+#### Issue: Docker group access
+**Symptoms**: `Got permission denied` errors
+**Solution**:
+```bash
+# Add user to docker group
+sudo usermod -aG docker $USER
+
+# Log out and back in, or run:
+newgrp docker
+```
+
+### Service-Specific Issues
+
+#### Pi-hole DNS Issues
+**Symptoms**: DNS resolution failures
+**Solution**:
+```bash
+# Check Pi-hole status
+docker exec tsysdevstack-supportstack-demo-pihole pihole status
+
+# Test DNS resolution
+nslookup google.com localhost
+
+# Restart DNS service
+docker exec tsysdevstack-supportstack-demo-pihole pihole restartdns
+```
+
+#### Grafana Data Source Connection
+**Symptoms**: InfluxDB data source not working
+**Solution**:
+```bash
+# Test InfluxDB connectivity
+curl http://localhost:4008/ping
+
+# Check Grafana logs
+docker compose logs grafana
+
+# Verify data source configuration
+# Navigate to: http://localhost:4009/datasources
+```
+
+#### Portainer Container Access
+**Symptoms**: Can't manage containers
+**Solution**:
+```bash
+# Check Docker socket proxy
+docker compose logs docker-socket-proxy
+
+# Verify proxy permissions
+curl http://localhost:4005/version
+
+# Restart Portainer
+docker compose restart portainer
+```
+
+### Performance Issues
+
+#### Issue: High memory usage
+**Symptoms**: System becomes slow
+**Solution**:
+```bash
+# Check resource usage
+docker stats
+
+# Set memory limits in docker-compose.yml
+# Add to each service:
+deploy:
+  resources:
+    limits:
+      memory: 512M
+
+# Restart with new limits
+docker compose up -d
+```
+
+#### Issue: Slow startup times
+**Symptoms**: Services take >60 seconds to start
+**Solution**:
+```bash
+# Check system resources
+free -h
+df -h
+
+# Pull images in advance
+docker compose pull
+
+# Check for conflicting services
+docker ps -a
+```
+
+## Diagnostic Commands
+
+### System Information
+```bash
+# System info
+uname -a
+free -h
+df -h
+
+# Docker info
+docker version
+docker compose version
+docker system df
+```
+
+### Service Status
+```bash
+# All services status
+docker compose ps
+
+# Service logs
+docker compose logs
+
+# Resource usage
+docker stats
+
+# Network info
+docker network ls
+docker network inspect tsysdevstack_supportstack-demo
+```
+
+### Health Checks
+```bash
+# Test all endpoints
+for port in 4000 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do
+    curl -f -s --max-time 5 "http://localhost:$port" && echo "Port $port: OK" || echo "Port $port: FAIL"
+done
+```
+
+## Getting Additional Help
+
+### Check Logs First
+```bash
+# All service logs
+docker compose logs
+
+# Specific service logs
+docker compose logs [service-name]
+
+# Follow logs in real-time
+docker compose logs -f [service-name]
+```
+
+### Validation Scripts
+```bash
+# Run comprehensive validation
+./scripts/validate-all.sh
+
+# Run test suite
+./scripts/demo-test.sh full
+
+# Run specific test categories
+./scripts/demo-test.sh security
+./scripts/demo-test.sh permissions
+./scripts/demo-test.sh network
+```
+
+### Reset and Restart
+```bash
+# Complete reset (removes all data)
+docker compose down -v
+docker system prune -f
+
+# Fresh deployment
+./scripts/demo-stack.sh deploy
+```
+
+## Known Limitations
+
+### Demo Mode Restrictions
+- No data persistence between restarts
+- Hardcoded demo credentials
+- No external network access
+- No security hardening
+
+### Resource Requirements
+- Minimum 8GB RAM recommended
+- Minimum 10GB disk space
+- Docker daemon must be running
+- User must be in docker group
+
+### Port Requirements
+All ports 4000-4018 must be available:
+- 4000: Homepage
+- 4005: Docker Socket Proxy
+- 4006: Pi-hole
+- 4007: Portainer
+- 4008: InfluxDB
+- 4009: Grafana
+- 4010: Draw.io
+- 4011: Kroki
+- 4012: Atomic Tracker
+- 4013: ArchiveBox
+- 4014: Tube Archivist
+- 4015: Wakapi
+- 4017: MailHog
+- 4018: Atuin
+
+## Contact and Support
+
+If issues persist after trying these solutions:
+
+1. Document the exact error message
+2. Include system information (OS, Docker version)
+3. List steps to reproduce the issue
+4. Include relevant log output
+5. Specify demo vs production context
+
+Remember: This is a demo configuration designed for development and testing purposes only.