sustainable-computing-io · sthaha · Aug 17, 2025
diff --git a/README.md b/README.md
@@ -54,33 +54,44 @@ accurate energy consumption monitoring for cloud-native workloads.
 
 ## 🚀 Getting Started
 
-> **📖 For comprehensive installation instructions, troubleshooting, and advanced deployment options, see our [Installation Guide](docs/user/installation.md)**
+**New to Kepler?** Follow our [**📖 Getting Started Guide**](docs/user/getting-started.md) for quick Kubernetes cluster deployment, or see our [**🧑‍💻 Developer Getting Started Guide**](docs/developer/getting-started.md) for local development with dashboards.
 
 ### ⚡ Quick Start
 
 Choose your preferred method:
 
 ```bash
-# 💻 Local Development
-make build && sudo ./bin/kepler
+# 🎯 Deploy to Kubernetes Cluster (Recommended for users)
+helm install kepler manifests/helm/kepler/ --namespace kepler --create-namespace
 
-# ✨ Docker Compose (with Prometheus & Grafana)
-cd compose/dev && docker-compose up -d
+# 🧑‍💻 Local Development with Dashboards
+cd compose/dev && docker compose up -d
+# Access Grafana: http://localhost:23000 (admin/admin)
 
-# 🐳 Kubernetes
-helm install kepler manifests/helm/kepler/ --namespace kepler --create-namespace
+# 🏗️ Local Kubernetes Development
+make cluster-up && make deploy
+
+# 💻 Build from Source
+make build && sudo ./bin/kepler
 ```
 
+> **📖 For detailed installation instructions, troubleshooting, and advanced deployment options, see our [Installation Guide](docs/user/installation.md)**
+
 ## 📖 Documentation
 
 ### User Documentation
 
-- **[Installation Guide](docs/user/installation.md)** - Detailed installation instructions for all deployment methods
-- **[Configuration Guide](docs/user/configuration.md)** - Configuration options and examples
+📋 **[User Guide Index](docs/user/README.md)** - Complete navigation hub for all user documentation
+
+- **[Getting Started Guide](docs/user/getting-started.md)** - Quick Kubernetes cluster deployment
+- **[Installation Guide](docs/user/installation.md)** - Production deployment methods and enterprise integration
+- **[Configuration Guide](docs/user/configuration.md)** - Configuration options and customization examples
+- **[Troubleshooting Guide](docs/user/troubleshooting.md)** - Comprehensive problem-solving and debugging guide
 - **[Metrics Documentation](docs/user/metrics.md)** - Available metrics and their descriptions
 
 ### Developer Documentation
 
+- **[Developer Getting Started Guide](docs/developer/getting-started.md)** - Local development setup with Docker Compose, dashboards, and building from source
 - **[Architecture Documentation](docs/developer/design/architecture/)** - Complete architectural documentation including design principles, system components, data flow, concurrency model, and deployment patterns
 - **[Power Attribution Guide](docs/developer/power-attribution-guide.md)** - How Kepler measures and attributes power consumption
 - **[Developer Documentation](docs/developer/)** - Contributing guidelines and development workflow

diff --git a/docs/index.md → docs/README.md b/docs/index.md → docs/README.md
@@ -8,6 +8,7 @@ Welcome to the Kepler documentation. Kepler is a Prometheus exporter that measur
 
 Documentation for users deploying and operating Kepler:
 
+- [Getting Started Guide](user/getting-started.md) - Quick Kubernetes cluster deployment
 - [Installation Guide](user/installation.md) - How to install and deploy Kepler
 - [Configuration Guide](user/configuration.md) - Configuring Kepler for your environment
 - [Metrics Reference](user/metrics.md) - Available Prometheus metrics exported by Kepler
@@ -22,7 +23,7 @@ Documentation for developers contributing to Kepler:
 
 ## Quick Start
 
-For a quick start, see the [Installation Guide](user/installation.md) and the main project README.
+For a quick start, see the [Getting Started Guide](user/getting-started.md) and the main project README.
 
 ## Contributing
 

diff --git a/docs/developer/index.md → docs/developer/README.md b/docs/developer/index.md → docs/developer/README.md
@@ -24,6 +24,7 @@ This section contains documentation for developers working on Kepler.
 
 ## Development Workflow
 
+- [Developer Getting Started](getting-started.md) - Building from source and setting up development environments
 - [Pre-commit Setup](pre-commit.md) - Setting up pre-commit hooks for code quality
 
 ## Release Management

diff --git a/docs/developer/design/architecture/index.md → docs/developer/design/architecture/README.md b/docs/developer/design/architecture/index.md → docs/developer/design/architecture/README.md
@@ -84,7 +84,7 @@ For specific implementation work:
 ## Related Documentation
 
 - **[Power Attribution Guide](../../power-attribution-guide.md)**: Detailed explanation of power calculation methodology
-- **[Development Setup](../../index.md)**: Setting up the development environment
+- **[Development Setup](../../README.md)**: Setting up the development environment
 - **[User Configuration Guide](../../../user/configuration.md)**: End-user configuration options
 
 ---

diff --git a/docs/developer/proposal/index.md → docs/developer/proposal/README.md b/docs/developer/proposal/index.md → docs/developer/proposal/README.md
diff --git a/docs/user/README.md b/docs/user/README.md
@@ -0,0 +1,198 @@
+# Kepler User Documentation
+
+Welcome to Kepler user documentation! This directory contains everything you need to deploy, configure, and monitor energy consumption with Kepler.
+
+## 🗺️ Documentation Overview
+
+| Guide | Purpose | Target Audience | Time Required |
+|-------|---------|-----------------|---------------|
+| **[Getting Started](getting-started.md)** | Quick Kubernetes deployment | New users, cluster operators | 5-10 minutes |
+| **[Installation](installation.md)** | Production deployment | DevOps, SRE, platform teams | 30-60 minutes |
+| **[Configuration](configuration.md)** | Customize Kepler settings | Advanced users, ops teams | As needed |
+| **[Metrics](metrics.md)** | Understand available metrics | Monitoring teams, developers | Reference |
+| **[Troubleshooting](troubleshooting.md)** | Diagnose and fix issues | All users | As needed |
+
+## 🚀 Quick Start
+
+**New to Kepler?** Start here:
+
+1. **[Getting Started Guide](getting-started.md)** - Deploy Kepler to your Kubernetes cluster in under 10 minutes
+2. **[Access your metrics](getting-started.md#access-metrics)** - Verify energy data collection
+3. **Choose your next step** based on your needs:
+   - Production deployment → [Installation Guide](installation.md)
+   - Customize settings → [Configuration Guide](configuration.md)
+   - Having issues? → [Troubleshooting Guide](troubleshooting.md)
+
+**Want to try Kepler locally first?** See our [**🧑‍💻 Developer Getting Started Guide**](../developer/getting-started.md) for Docker Compose setup with pre-configured dashboards.
+
+## 📋 Choose Your Path
+
+### 🎯 I want to deploy Kepler to my cluster
+
+**→ [Getting Started Guide](getting-started.md)**
+
+- Quick Helm installation (5 minutes)
+- Deploy to existing Kubernetes cluster
+- Verify energy metrics collection
+- Production-ready deployment path
+
+### 🏗️ I need to deploy Kepler in production
+
+**→ [Installation Guide](installation.md)**
+
+- Helm installation (recommended)
+- kubectl/kustomize deployment
+- Enterprise integration (RBAC, network policies)
+- Multi-cluster and high availability setup
+
+### ⚙️ I need to customize Kepler configuration
+
+**→ [Configuration Guide](configuration.md)**
+
+- All configuration options explained
+- Command-line flags vs config file
+- Monitoring, logging, and export settings
+- Kubernetes integration options
+- Development features (fake CPU meter)
+
+### 📊 I want to understand Kepler metrics
+
+**→ [Metrics Reference](metrics.md)**
+
+- Complete metrics catalog
+- Node, container, process, VM, and pod level metrics
+- Metric types and labels
+- Power vs energy measurements
+- Integration with Prometheus
+
+### 🔍 I'm having problems with Kepler
+
+**→ [Troubleshooting Guide](troubleshooting.md)**
+
+- Quick health checks
+- Docker Compose issues
+- Kubernetes deployment problems
+- Configuration and metrics issues
+- Advanced debugging techniques
+
+## 🛤️ Learning Progression
+
+### Beginner Path
+
+1. **[Getting Started](getting-started.md)** - Deploy to Kubernetes cluster
+2. **[Understanding Metrics](metrics.md)** - Learn what you're measuring
+3. **[Basic Configuration](configuration.md#configuration-methods)** - Simple customization
+
+### Local Development Path
+
+1. **[Developer Getting Started Guide](../developer/getting-started.md)** - Docker Compose with dashboards
+2. **[Getting Started](getting-started.md)** - Deploy to cluster when ready
+3. **[Configuration Guide](configuration.md)** - Customize for your needs
+
+### Intermediate Path
+
+1. **[Installation Guide](installation.md)** - Production deployment
+2. **[Advanced Configuration](configuration.md#configuration-options-in-detail)** - Fine-tune settings
+3. **[Troubleshooting](troubleshooting.md)** - Handle common issues
+
+### Advanced Path
+
+1. **[Enterprise Integration](installation.md#enterprise-integration)** - RBAC, security
+2. **[Performance Tuning](configuration.md#monitor-configuration)** - Optimize for scale
+3. **[Advanced Debugging](troubleshooting.md#advanced-debugging)** - Deep troubleshooting
+
+## 🎯 Common Use Cases
+
+### "I want to see energy monitoring in action"
+
+**Solution:** [Developer Getting Started - Docker Compose](../developer/getting-started.md#docker-compose-development-setup)
+
+- Complete monitoring stack with dashboards
+- Local development environment
+- 5-minute setup
+
+### "I need Kepler in my Kubernetes cluster"
+
+**Solution:** [Getting Started - Helm Installation](getting-started.md#quick-installation-with-helm)
+
+- Quick cluster deployment (5 minutes)
+- Then [Installation Guide](installation.md#helm-installation-recommended) for production config
+- Integrates with existing monitoring
+
+### "Power metrics are missing or incorrect"
+
+**Solution:** [Troubleshooting - Metrics Issues](troubleshooting.md#metrics-and-monitoring-issues)
+
+- Hardware support checks
+- Fake CPU meter for testing
+- Attribution troubleshooting
+
+### "I want to customize how Kepler works"
+
+**Solution:** [Configuration Guide](configuration.md)
+
+- All configuration options
+- Environment-specific settings
+- Development vs production configs
+
+### "Kepler isn't working as expected"
+
+**Solution:** [Troubleshooting Guide](troubleshooting.md)
+
+- Quick diagnostics
+- Platform-specific issues
+- Step-by-step problem solving
+
+## 📚 Related Documentation
+
+### Developer Resources
+
+- **[Developer Documentation](../developer/)** - Contributing, development setup
+- **[Architecture Guide](../developer/design/architecture/)** - How Kepler works internally
+- **[API Documentation](../developer/)** - Technical implementation details
+
+### Project Resources
+
+- **[Main README](../../README.md)** - Project overview
+- **[Contributing Guide](../../CONTRIBUTING.md)** - How to contribute
+- **[Governance](../../GOVERNANCE.md)** - Project governance
+
+## 🆘 Getting Help
+
+### Self-Service Resources
+
+1. **[Troubleshooting Guide](troubleshooting.md)** - Most common issues covered
+2. **[Configuration Reference](configuration.md)** - All settings explained
+3. **[Metrics Documentation](metrics.md)** - Understanding the data
+
+### Community Support
+
+- **🐛 GitHub Issues:** [Report bugs or request features](https://github.com/sustainable-computing-io/kepler/issues)
+- **💬 GitHub Discussions:** [Ask questions and share experiences](https://github.com/sustainable-computing-io/kepler/discussions)
+- **🗨️ CNCF Slack:** [Real-time community chat](https://cloud-native.slack.com/archives/C06HYDN4A01)
+
+### Before Asking for Help
+
+1. Check the [Troubleshooting Guide](troubleshooting.md) for your issue
+2. Search [existing issues](https://github.com/sustainable-computing-io/kepler/issues)
+3. Gather logs and configuration (see [troubleshooting checklist](troubleshooting.md#before-asking-for-help))
+
+## 🔄 Documentation Updates
+
+This documentation is actively maintained. If you find:
+
+- **Outdated information** - Please [open an issue](https://github.com/sustainable-computing-io/kepler/issues/new)
+- **Missing content** - Contributions welcome via [pull request](https://github.com/sustainable-computing-io/kepler/pulls)
+- **Unclear instructions** - Let us know in [discussions](https://github.com/sustainable-computing-io/kepler/discussions)
+
+## 📈 What's Next?
+
+After mastering the user guides:
+
+- **[Join the community](https://github.com/sustainable-computing-io/kepler/discussions)** - Share your experiences
+- **[Contribute improvements](../../CONTRIBUTING.md)** - Help make Kepler better
+- **[Try advanced features](../developer/)** - Explore cutting-edge capabilities
+
+---
+
+**Happy energy monitoring with Kepler!** ⚡
diff --git a/docs/user/configuration.md b/docs/user/configuration.md
@@ -299,6 +299,46 @@ dev:
   - `enabled`: Set to `true` to enable fake CPU meter
   - `zones`: Specific zones to enable, empty enables all
 
+## 🔧 Fake CPU Meter Configuration
+
+The fake CPU meter is a development/testing feature that generates synthetic power data
+when real hardware power measurements aren't available.
+
+### When to Use Fake CPU Meter
+
+- **Virtual Machines** - VMs typically don't expose hardware power sensors
+- **Non-Intel Systems** - AMD or ARM systems without RAPL support
+- **Cloud Instances** - Most cloud VMs don't have access to power sensors
+- **Development/Testing** - When you want to see Kepler working without hardware
+- **CI/CD Environments** - Automated testing of Kepler functionality
+
+### Configuration Options
+
+```yaml
+dev:
+  fake-cpu-meter:
+    enabled: true  # Enable synthetic power measurements
+    zones: []      # Zones to simulate (empty = all default zones)
+```
+
+### What Fake CPU Meter Provides
+
+The fake CPU meter generates realistic synthetic data:
+
+- **Simulated CPU power usage** - Based on actual CPU utilization patterns
+- **Consistent metric structure** - All the same metrics as real hardware
+- **Realistic value ranges** - Power values similar to actual hardware (10-200W typical)
+- **Proper workload attribution** - Correctly attributes power to containers/processes
+- **Time-based variation** - Power values change realistically with load
+
+### Limitations and Considerations
+
+⚠️ **Important Limitations:**
+
+- **Not real measurements** - Data is synthetic approximation, not actual power consumption
+- **Development only** - Never use for production monitoring, billing, or real optimization decisions
+- **No hardware insights** - Won't help identify actual hardware-specific power characteristics
+
 ## 📖 Further Reading
 
 For more details see the [config file](../../hack/config.yaml)