fix: update contributing and readme (#127)

Author: meyer9

.github/assets/logo.png

@@ -0,0 +1,37 @@
+# Contributing to Base Benchmark
+
+Thanks for your interest in improving the Base Benchmark tool!
+
+## Ways to Contribute
+
+1. **Report bugs** - Open an issue describing the problem
+2. **Suggest features** - Share ideas for improvements
+3. **Submit pull requests** - Fix bugs or add features
+
+## Submitting a Pull Request
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b my-feature`)
+3. Make your changes following our coding style
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Commit your changes with a clear message
+7. Push to your fork and open a pull request
+
+## Code Style
+
+- Write clear, readable code with comments where needed
+- Keep functions small and focused
+- Use descriptive variable and function names
+- Follow standard Go conventions (`gofmt`, `golint`)
+- Prefer functional programming patterns
+
+## Testing
+
+- Add unit tests for new functions
+- Add integration tests for end-to-end features
+- Ensure existing tests still pass
+
+## Questions?
+
+Open a discussion or issue if you have questions or need help. Join the [Base Discord server](https://discord.gg/WtdUtVsy9A) for additional support.

.github/assets/run-switcher.png

@@ -1,54 +1,125 @@
-<div align="center">
-  <h1 style="font-size:32pt">Base Benchmark</h1>
-  <a href="https://shields.io/"><img src="https://shields.io/badge/status-beta-yellow" alt="Status: Beta"></a>
-  <a href="https://go.dev/"><img src="https://shields.io/badge/language-Go-00ADD8" alt="Language: Go"></a>
-  <a href="https://github.com/base/benchmark/blob/main/LICENSE"><img src="https://shields.io/github/license/base/benchmark" alt="License"></a>
-</div>
+![Base](.github/assets/logo.png)
+
+# Base Benchmark
 
 Base Benchmark is a performance testing framework for Ethereum execution clients. Compare client performance, identify bottlenecks, and ensure reliability before deployment.
 
-## 🚀 Features
+<!-- Badge row 1 - status -->
+
+[![GitHub contributors](https://img.shields.io/github/contributors/base/benchmark)](https://github.com/base/benchmark/graphs/contributors)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/w/base/benchmark)](https://github.com/base/benchmark/graphs/contributors)
+[![GitHub Stars](https://img.shields.io/github/stars/base/benchmark.svg)](https://github.com/base/benchmark/stargazers)
+![GitHub repo size](https://img.shields.io/github/repo-size/base/benchmark)
+[![GitHub](https://img.shields.io/github/license/base/benchmark?color=blue)](https://github.com/base/benchmark/blob/main/LICENSE)
+
+<!-- Badge row 2 - links and profiles -->
+
+[![Website base.org](https://img.shields.io/website-up-down-green-red/https/base.org.svg)](https://base.org)
+[![Blog](https://img.shields.io/badge/blog-up-green)](https://base.mirror.xyz/)
+[![Docs](https://img.shields.io/badge/docs-up-green)](https://docs.base.org/)
+[![Discord](https://img.shields.io/discord/1067165013397213286?label=discord)](https://base.org/discord)
+[![Twitter Base](https://img.shields.io/twitter/follow/Base?style=social)](https://twitter.com/Base)
+
+<!-- Badge row 3 - detailed status -->
+
+[![GitHub pull requests by-label](https://img.shields.io/github/issues-pr-raw/base/benchmark)](https://github.com/base/benchmark/pulls)
+[![GitHub Issues](https://img.shields.io/github/issues-raw/base/benchmark.svg)](https://github.com/base/benchmark/issues)
 
-Base Benchmark provides comprehensive testing capabilities:
+## Features
 
-- **Performance Evaluation** - Test both block building and validation performance across execution clients
-- **Comparative Analysis** - Measure client behavior across various inputs and workloads
-- **Metric Collection** - Track critical metrics including submission times, latency, and throughput
-- **Flexible Workloads** - Configure transaction patterns to match your specific needs
-- **Visual Reports** - Generate interactive HTML dashboards of benchmark results
+- **Performance Evaluation:** Test both block building and validation performance across execution clients (Geth, Reth, and more)
+- **Comparative Analysis:** Measure client behavior across various inputs and workloads
+- **Metric Collection:** Track critical metrics including submission times, latency, and throughput
+- **Flexible Workloads:** Configure transaction patterns to match your specific needs
+- **Interactive Dashboard:** Generate beautiful HTML reports with charts and run comparisons
+- **Import & Merge:** Combine benchmark results from multiple machines with flexible tagging
 
-## 📋 Quick Start
+## Repository Structure
 
-[Install Forge](https://book.getfoundry.sh/getting-started/installation)
+```
+.
+├── Makefile              # Build and development tasks
+├── go.mod                # Go module dependencies
+├── benchmark/            # CLI application
+│   ├── cmd/              # Main entry point
+│   ├── config/           # Configuration types
+│   └── flags/            # CLI flags
+├── runner/               # Core benchmarking logic
+│   ├── benchmark/        # Benchmark execution
+│   ├── clients/          # Client integrations (Geth, Reth)
+│   ├── importer/         # Run import functionality
+│   ├── network/          # Network setup and management
+│   └── payload/          # Transaction payload generation
+├── configs/              # Benchmark configurations
+│   ├── examples/         # Development and testing configs
+│   └── public/           # Production-ready benchmarks
+├── contracts/            # Smart contracts for testing
+│   └── src/              # Solidity source files
+├── report/               # Interactive dashboard
+│   └── src/              # React TypeScript application
+└── clients/              # Client build scripts
+```
+
+## Prerequisites
+
+- **Go:** Version 1.21 or later. Install from [go.dev](https://go.dev/dl/)
+- **Foundry:** For smart contract compilation. See [installation guide](https://book.getfoundry.sh/getting-started/installation)
+- **Node.js:** Version 18+ for the interactive dashboard. Install from [nodejs.org](https://nodejs.org/)
 
-Recursively clone github submodules:
+## Getting Started
+
+### 1. Clone the Repository
 
 ```bash
+git clone https://github.com/base/benchmark.git
+cd benchmark
 git submodule update --init --recursive
 ```
 
+### 2. Build the Application
+
 ```bash
-# Build the application
 make build
+```
+
+The binary will be located at `bin/benchmark`.
 
-# Build the binaries, geth, reth, rbuilder
+### 3. Build Client Binaries (Optional)
+
+To build Geth and Reth from source:
+
+```bash
 make build-binaries
+```
 
-# Run the basic benchmark
+Alternatively, you can specify paths to pre-built binaries when running benchmarks.
+
+### 4. Run Your First Benchmark
+
+```bash
 ./bin/base-bench run \
   --config ./configs/public/basic.yml \
   --root-dir ./data-dir \
-  --reth-bin path_to_reth_bin \
-  --geth-bin path_to_geth_bin \
   --output-dir ./output
+```
 
-# View the interactive dashboard
+To see available options:
+
+```bash
+./bin/base-bench run --help
+```
+
+### 5. View Results in the Interactive Dashboard
+
+```bash
 cd report/
-npm i
+npm install
 npm run dev
 ```
 
-## 📋 Available Benchmarks
+Open your browser to the URL shown (typically `http://localhost:5173`).
+
+## Available Benchmarks
 
 Explore the comprehensive collection of benchmark configurations:
 
@@ -59,7 +130,7 @@ Explore the comprehensive collection of benchmark configurations:
 
 Choose from storage operations, precompile tests, token workloads, mainnet simulations, and more.
 
-## 🏗️ Architecture
+## Architecture
 
 ### Benchmark Structure
 
@@ -99,23 +170,16 @@ Each test executes a standardized workflow:
 
 This approach allows precise measurement of performance characteristics for both block production and validation.
 
-## 🔧 Configuration
-
-### Build
-
-```bash
-make build
-ls ./bin/base-bench
-```
+## Configuration
 
 ### Available Flags
 
 ```
 NAME:
-   base-bench run - run benchmark
+   benchmark run - run benchmark
 
 USAGE:
-   base-bench run [command options]
+   benchmark run [command options]
 
 OPTIONS:
    --config value                  Config Path ($BASE_BENCH_CONFIG)
@@ -140,16 +204,81 @@ OPTIONS:
    --help, -h                      Show help (default: false)
 ```
 
-## 📊 Example Reports
+## Managing Test Runs
+
+### Understanding Runs and Suites
+
+When you view benchmark results in the interactive dashboard, you can switch between different test runs using the run switcher:
 
 <div align="center">
-  <p><i>Performance comparison between Geth and Reth clients</i></p>
+  <img src=".github/assets/run-switcher.png" alt="Run Switcher" width="600">
 </div>
 
-## 🤝 Contributing
+### Creating Test Runs
+
+Running benchmarks adds a new suite by default:
+
+```bash
+./bin/base-bench run --config ./configs/public/basic.yml
+```
+
+Each execution creates a new suite entry in the run list, allowing you to track performance over time or across different configurations.
+
+### Combining Multiple Runs
+
+Use `import-runs` to merge benchmark results from multiple machines or configurations:
+
+```bash
+./bin/base-bench import-runs \
+  --output-dir ./output \
+  ./results-from-server-1/metadata.json
+```
+
+**Two import strategies:**
+
+1. **Add to latest suite with tags** - Merge imported runs into your most recent suite, using tags to differentiate:
+
+   ```bash
+   # Add imported runs to the last suite with tags for differentiation
+   ./bin/base-bench import-runs \
+     --src-tag "instance=server-lg" \
+     --dest-tag "instance=server-md" \
+     --output-dir ./output \
+     ./results-from-server-1/metadata.json
+
+   # --src-tag fills missing tags on existing runs (won't overwrite)
+   # --dest-tag applies to the imported runs
+   # Useful for comparing hardware configurations within the same test run
+   ```
+
+2. **Create new separate suite** - Add imported runs as an independent suite in the list:
+
+   ```bash
+   # Interactive mode (recommended) - prompts you to choose strategy and configure tags
+   ./bin/base-bench import-runs \
+     --output-dir ./output \
+     ./results-from-server-1/metadata.json
+
+   # Creates a new entry differentiated by BenchmarkRun ID
+   # Useful for tracking performance across different code versions or time periods
+   ```
+
+**Interactive Mode:** Without specifying tags, the tool enters interactive mode and guides you through:
+
+- Choosing between adding to last suite or creating new suite
+- Configuring appropriate tags if needed
+- Confirming the import operation
+
+This flexibility lets you organize benchmarks by hardware type, client version, or any dimension relevant to your analysis.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
+
+## License
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 
-## 📜 License
+---
 
-This project is licensed under the [MIT License](LICENSE).
+**Built with ❤️ by [Base](https://base.org)**