docs: add comprehensive user documentation

README.md

@@ -191,6 +191,30 @@ The `runner.debug` context is documented in the [GitHub Actions contexts referen
 > [!NOTE]
 > Metrics are displayed with timestamps rather than correlated with specific workflow steps. You can manually correlate metrics with your workflow steps by matching timestamps with the execution times shown in your workflow run logs.
 
+## Documentation
+
+### Quick Links
+
+- **[Quick Reference](docs/quick-reference.md)** - Fast lookup for common configurations and scenarios
+- **[FAQ](docs/faq.md)** - Frequently asked questions and answers
+- **[Troubleshooting Guide](docs/troubleshooting.md)** - Solutions to common issues
+- **[Examples](docs/examples/)** - Real-world usage scenarios:
+  - [Basic Monitoring](docs/examples/basic-monitoring.md) - Simple setup for general workflows
+  - [Debug Mode Only](docs/examples/debug-mode.md) - Conditional metrics collection on demand
+  - [Build Optimization](docs/examples/build-optimization.md) - Identifying and resolving bottlenecks
+  - [Memory-Intensive Workflows](docs/examples/memory-intensive.md) - Handling data processing and ML
+  - [Multi-Job Workflows](docs/examples/multi-job.md) - Comparing metrics across jobs
+- **[Architecture](docs/architecture.md)** - Technical implementation details
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check the [FAQ](docs/faq.md) for common questions
+2. Review the [Troubleshooting Guide](docs/troubleshooting.md) for solutions
+3. Search [existing issues](https://github.com/Garbee/runner-resource-usage/issues)
+4. Open a new issue with details about your problem
+
 ## Development Setup
 
 ### 1. Install Dependencies

docs/README.md

@@ -0,0 +1,204 @@
+# Documentation Index
+
+Complete guide to the runner-resource-usage action documentation.
+
+## Quick Start
+
+New to this action? Start here:
+
+1. **[README](../README.md)** - Overview, features, and basic usage
+2. **[Quick Reference](./quick-reference.md)** - Common configurations at a glance
+3. **[Basic Monitoring Example](./examples/basic-monitoring.md)** - Your first workflow with metrics
+
+## User Guides
+
+### Getting Started
+
+- **[README](../README.md)** - Main documentation with installation and usage
+- **[Quick Reference](./quick-reference.md)** - Fast lookup for configurations and scenarios
+- **[Examples Index](./examples/README.md)** - Overview of all available examples
+
+### Understanding Metrics
+
+- **[FAQ](./faq.md)** - Frequently asked questions
+  - What does this action do?
+  - How do I read the metrics?
+  - How do I correlate metrics with workflow steps?
+  - What are the alert thresholds?
+  - How much overhead does this add?
+
+### Solving Problems
+
+- **[Troubleshooting Guide](./troubleshooting.md)** - Common issues and solutions
+  - No metrics displayed
+  - High resource usage
+  - False positive alerts
+  - Platform-specific issues
+  - Performance problems
+
+## Examples by Use Case
+
+### By Experience Level
+
+**Beginner**:
+- [Basic Monitoring](./examples/basic-monitoring.md) - Simple setup and interpretation
+
+**Intermediate**:
+- [Debug Mode Only](./examples/debug-mode.md) - Conditional metrics collection
+- [Build Optimization](./examples/build-optimization.md) - Using metrics to improve performance
+
+**Advanced**:
+- [Memory-Intensive Workflows](./examples/memory-intensive.md) - Data processing and ML
+- [Multi-Job Workflows](./examples/multi-job.md) - Cross-job analysis
+
+### By Workflow Type
+
+**General CI/CD**:
+- [Basic Monitoring](./examples/basic-monitoring.md) - Standard build/test workflows
+- [Multi-Job Workflows](./examples/multi-job.md) - Multiple jobs in one workflow
+
+**Performance Optimization**:
+- [Build Optimization](./examples/build-optimization.md) - Identifying bottlenecks
+- [Memory-Intensive Workflows](./examples/memory-intensive.md) - High memory usage
+
+**Debugging & Investigation**:
+- [Debug Mode Only](./examples/debug-mode.md) - On-demand metrics collection
+- [Build Optimization](./examples/build-optimization.md) - Performance analysis
+
+### By Technology
+
+**Node.js / JavaScript**:
+- [Basic Monitoring](./examples/basic-monitoring.md)
+- [Build Optimization](./examples/build-optimization.md)
+
+**Python / Data Science**:
+- [Memory-Intensive Workflows](./examples/memory-intensive.md)
+
+**Docker**:
+- [Build Optimization](./examples/build-optimization.md)
+
+**Cross-Platform**:
+- [Multi-Job Workflows](./examples/multi-job.md)
+
+## Technical Documentation
+
+### Architecture & Design
+
+- **[Architecture](./architecture.md)** - Technical implementation details
+  - Execution flow
+  - Data collection mechanism
+  - Storage architecture
+  - Performance considerations
+  - Security model
+
+### Configuration Reference
+
+- **[Quick Reference](./quick-reference.md)** - All configuration options
+  - Input parameters
+  - Default values
+  - Threshold recommendations
+  - Platform-specific notes
+
+## Documentation by Topic
+
+### Resource Monitoring
+
+| Topic | Documents |
+|-------|-----------|
+| Basic setup | [README](../README.md), [Basic Monitoring](./examples/basic-monitoring.md) |
+| CPU metrics | [FAQ](./faq.md), [Build Optimization](./examples/build-optimization.md) |
+| Memory metrics | [FAQ](./faq.md), [Memory-Intensive](./examples/memory-intensive.md) |
+| Disk metrics | [FAQ](./faq.md), [Build Optimization](./examples/build-optimization.md) |
+
+### Configuration & Tuning
+
+| Topic | Documents |
+|-------|-----------|
+| Alert thresholds | [Quick Reference](./quick-reference.md), [FAQ](./faq.md) |
+| Collection interval | [Quick Reference](./quick-reference.md), [FAQ](./faq.md) |
+| Conditional execution | [Debug Mode](./examples/debug-mode.md) |
+| Platform-specific | [Quick Reference](./quick-reference.md), [Multi-Job](./examples/multi-job.md) |
+
+### Problem Solving
+
+| Issue Type | Documents |
+|------------|-----------|
+| No metrics showing | [Troubleshooting](./troubleshooting.md) |
+| Performance problems | [Troubleshooting](./troubleshooting.md), [Build Optimization](./examples/build-optimization.md) |
+| Memory issues | [Troubleshooting](./troubleshooting.md), [Memory-Intensive](./examples/memory-intensive.md) |
+| False alerts | [Troubleshooting](./troubleshooting.md), [FAQ](./faq.md) |
+
+## Learning Paths
+
+### Path 1: Quick Start
+
+For users who want to get started immediately:
+
+1. Read [README](../README.md) → Understand what the action does
+2. Follow [Basic Monitoring](./examples/basic-monitoring.md) → Add to your workflow
+3. Check [Quick Reference](./quick-reference.md) → Adjust settings if needed
+
+**Time required**: 15 minutes
+
+### Path 2: Performance Optimization
+
+For users investigating slow workflows:
+
+1. Add action using [Basic Monitoring](./examples/basic-monitoring.md)
+2. Collect baseline metrics (run workflow 2-3 times)
+3. Follow [Build Optimization](./examples/build-optimization.md)
+4. Check [Troubleshooting](./troubleshooting.md) for specific issues
+
+**Time required**: 1-2 hours
+
+### Path 3: Advanced Usage
+
+For users with complex workflows:
+
+1. Start with [Basic Monitoring](./examples/basic-monitoring.md)
+2. Read [Architecture](./architecture.md) → Understand how it works
+3. Review [Multi-Job Workflows](./examples/multi-job.md)
+4. Check [Memory-Intensive](./examples/memory-intensive.md) if applicable
+5. Set up [Debug Mode](./examples/debug-mode.md) for production
+
+**Time required**: 2-3 hours
+
+### Path 4: Troubleshooting
+
+For users experiencing issues:
+
+1. Check [Troubleshooting Guide](./troubleshooting.md) → Find your issue
+2. Review [FAQ](./faq.md) → Common questions
+3. Check relevant example for your use case
+4. Read [Architecture](./architecture.md) if needed for deeper understanding
+
+**Time required**: 30 minutes - 1 hour
+
+## Contributing Documentation
+
+Have suggestions for improving documentation?
+
+1. Open an issue describing the improvement
+2. Submit a PR with documentation changes
+3. Follow the style and format of existing docs
+
+Good documentation contributions:
+- Fix errors or unclear explanations
+- Add missing examples or use cases
+- Update outdated information
+- Improve navigation or organization
+
+## Getting Help
+
+Can't find what you need?
+
+1. **Search existing documentation**: Use browser search (Ctrl/Cmd+F) in this index
+2. **Check the FAQ**: [FAQ.md](./faq.md) covers many common questions
+3. **Search issues**: [GitHub Issues](https://github.com/Garbee/runner-resource-usage/issues)
+4. **Ask a question**: Open a new issue with the "question" label
+
+---
+
+**Last Updated**: 2026-02-16
+
+**Documentation Version**: 1.0

docs/architecture.md

@@ -28,7 +28,7 @@ sequenceDiagram
     Main-->>User: Exit immediately
 
     Collector->>Collector: Start collection loop
-    loop Every 1 second (default)
+    loop Every 5 seconds (default)
         Collector->>Collector: Collect CPU, Memory, Disk metrics
         Collector->>State: Write metrics to state file
     end
@@ -54,7 +54,7 @@ For accessibility, here is a text description of the execution flow diagram abov
 
 1. **Main Action Execution**: The workflow executes the main action (`dist/main/index.js`), which immediately spawns a collector process as a detached background process and exits.
 
-2. **Collector Process**: The collector process (`dist/main/collector.js`) creates a Metrics instance and starts a collection loop that runs every 1 second (by default). During each cycle, it:
+2. **Collector Process**: The collector process (`dist/main/collector.js`) creates a Metrics instance and starts a collection loop that runs every 5 seconds (by default). During each cycle, it:
    - Collects CPU, memory, and disk usage metrics using the `systeminformation` library
    - Stores the metrics in memory
    - Writes the metrics to state file immediately after collection
@@ -93,7 +93,7 @@ A simple background process that:
 
 The core metrics collection component:
 - **Initialization**: Starts async collection in the constructor
-- **Periodic Collection**: Collects metrics every 1 second (default) using drift-compensated timers
+- **Periodic Collection**: Collects metrics every 5 seconds (default) using drift-compensated timers
 - **Data Collection**: Uses `systeminformation` library to gather:
   - CPU usage (user and system, 0-100%)
   - Memory usage (active and available in MB)
@@ -263,7 +263,7 @@ The action is designed for Node.js 24+ with:
 ### CPU Impact
 - Collection process uses minimal CPU (< 1% typical)
 - `systeminformation` library is efficient
-- 1-second interval provides high-resolution data with minimal overhead
+- 5-second default interval provides good resolution with minimal overhead
 
 ### Disk I/O
 

docs/examples/README.md

@@ -0,0 +1,34 @@
+# Usage Examples
+
+This directory contains real-world examples of using the runner-resource-usage action in different scenarios.
+
+## Available Examples
+
+### By Use Case
+
+- [**Basic Monitoring**](./basic-monitoring.md) - Simple setup for general workflow monitoring
+- [**Build Optimization**](./build-optimization.md) - Identifying bottlenecks in build processes
+- [**Debug Mode Only**](./debug-mode.md) - Conditional metrics collection on demand
+- [**Memory-Intensive Workflows**](./memory-intensive.md) - Handling data processing and machine learning
+- [**Multi-Job Workflows**](./multi-job.md) - Collecting metrics across multiple jobs
+
+### By Workflow Type
+
+- **Node.js Projects**: See [Basic Monitoring](./basic-monitoring.md)
+- **Docker Builds**: See [Build Optimization](./build-optimization.md)
+- **Python/Data Science**: See [Memory-Intensive Workflows](./memory-intensive.md)
+- **Matrix Builds**: See [Multi-Job Workflows](./multi-job.md)
+
+## Quick Start
+
+If you're new to this action, start with [Basic Monitoring](./basic-monitoring.md) to understand the fundamental setup.
+
+## Contributing Examples
+
+Have a useful example? Please submit a PR! Examples should:
+
+- Focus on a specific use case or problem
+- Include complete, working workflow YAML
+- Explain the context and goals
+- Highlight key configuration decisions
+- Show expected output or interpretation