diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8b13789..6575f3c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1 +1,197 @@
+# Contributing to ExecuTrace
 
+Thank you for your interest in contributing to **ExecuTrace**! Whether you're fixing a bug, proposing a new feature, improving the docs, or just sharing feedback, every contribution is welcome.
+
+Please take a moment to read this guide before you start.
+
+---
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Ways to Contribute](#ways-to-contribute)
+- [Getting Started](#getting-started)
+- [Project Structure](#project-structure)
+- [Running Tests](#running-tests)
+- [Coding Standards](#coding-standards)
+- [Commit Message Conventions](#commit-message-conventions)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+- [Documentation](#documentation)
+- [Security Vulnerabilities](#security-vulnerabilities)
+- [Hall of Fame](#hall-of-fame)
+
+---
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating you agree to uphold its standards. Please report unacceptable behaviour to **w4nn4d133@gmail.com**.
+
+---
+
+## Ways to Contribute
+
+| Type | How |
+|---|---|
+| 🐛 Bug fix | Open an issue first, then submit a PR |
+| ✨ New feature | Open a feature-request issue to discuss scope |
+| 📖 Documentation | Edit Markdown files or the `website/` source |
+| 🧪 Tests | Add or improve tests in `test_comprehensive.py` |
+| 🔐 Security | See [Security Vulnerabilities](#security-vulnerabilities) |
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.9 or higher
+- `git`
+
+### Fork & clone
+
+```bash
+git clone https://github.com/<your-username>/ExecuTrace.git
+cd ExecuTrace
+```
+
+### Create a virtual environment
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+```
+
+### Install in editable mode
+
+```bash
+pip install -e .
+```
+
+### Verify the installation
+
+```bash
+exectrace --help
+```
+
+---
+
+## Project Structure
+
+```
+ExecuTrace/
+├── exectrace/            # Core library
+│   ├── cli.py            # Command-line interface
+│   ├── core/             # Replayer and workflow models
+│   ├── recorder/         # Session recording logic
+│   ├── storage/          # JSON & XML storage backends
+│   └── utils/            # Logging, interactive prompts
+├── website/              # Documentation website (GitHub Pages)
+│   ├── index.html
+│   └── data/
+│       ├── contributors.json
+│       └── security_hof.json
+├── test_comprehensive.py # Test suite
+├── pyproject.toml        # Build & packaging configuration
+├── CONTRIBUTING.md       # This file
+├── CODE_OF_CONDUCT.md
+├── SECURITY.md
+└── README.md
+```
+
+---
+
+## Running Tests
+
+```bash
+python test_comprehensive.py
+```
+
+All tests must pass before submitting a pull request. If you add new functionality, please add corresponding tests.
+
+---
+
+## Coding Standards
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) for Python code style.
+- Use type annotations for all public functions and methods (Python 3.9+ syntax).
+- Keep functions focused and small — prefer multiple simple functions over one large one.
+- Use the `get_logger` utility from `exectrace.utils.logger` for logging rather than `print` in library code.
+- Do not introduce new dependencies without prior discussion in an issue.
+
+---
+
+## Commit Message Conventions
+
+Use short, imperative messages in the present tense:
+
+```
+fix: handle missing workflow file gracefully
+feat: add --timeout flag to replay command
+docs: add contribution guide
+test: cover XML storage edge cases
+refactor: extract prompt helpers into utils module
+```
+
+Prefix categories: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`.
+
+---
+
+## Pull Request Process
+
+1. **Branch** off `main` with a descriptive name:
+   ```bash
+   git checkout -b fix/replay-dry-run-output
+   ```
+2. **Make your changes** in small, focused commits.
+3. **Run the tests** and confirm everything passes.
+4. **Push** your branch and open a Pull Request against `main`.
+5. Fill in the PR description explaining *what* changed and *why*.
+6. A maintainer will review your PR. Please respond to feedback promptly.
+7. Once approved, the PR will be merged by a maintainer.
+
+> For large changes, open an issue for discussion **before** writing code to avoid wasted effort.
+
+---
+
+## Reporting Bugs
+
+1. Search [existing issues](https://github.com/Stalin-143/ExecuTrace/issues) to check whether the bug has already been reported.
+2. If not, open a new issue and include:
+   - ExecuTrace version (`pip show exectrace-workflow`)
+   - Python version and OS
+   - Steps to reproduce
+   - Expected vs. actual behaviour
+   - Relevant error output or logs
+
+---
+
+## Suggesting Features
+
+1. Search existing issues for similar requests.
+2. Open an issue with the label **enhancement** and describe:
+   - The problem you're trying to solve
+   - Your proposed solution
+   - Any alternatives you've considered
+
+---
+
+## Documentation
+
+The project documentation website lives in `website/`. It is a static HTML site deployed via GitHub Pages.
+
+- To add yourself to the contributors list, update `website/data/contributors.json`.
+- For content changes, edit `website/index.html` and open a PR.
+
+---
+
+## Security Vulnerabilities
+
+Please **do not** open a public issue for security bugs. Follow the responsible-disclosure process described in [SECURITY.md](SECURITY.md).
+
+---
+
+## Hall of Fame
+
+Contributors and responsible security reporters are credited on the project website. Thank you for helping make ExecuTrace better!