diff --git a/README.md b/README.md
index e753efd..e904fba 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,151 @@
-# scaffoldforge
+# ScaffoldForge
 
-CLI tool that parses GitHub issues and automatically generates project scaffolds with starter code, file structures, and TODO comments
\ No newline at end of file
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![Status](https://img.shields.io/badge/status-beta-green)](https://github.com/7000pctAUTO/scaffoldforge)
+
+ScaffoldForge is a CLI tool that parses GitHub issues and automatically generates project scaffolds with starter code, file structures, and TODO comments. Developers can point it at a repo and issue, and it creates a development-ready starting point with placeholders for implementation.
+
+## Features
+
+- Parse GitHub issue descriptions, checklists, and comments
+- Generate project structures from templates
+- Create starter files with TODO comments
+- Support multiple languages (Python, JavaScript, Go, Rust)
+- Custom template system
+- Preview mode before generating
+- Interactive mode with prompts
+
+## Installation
+
+```bash
+pip install scaffoldforge
+```
+
+Or from source:
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/scaffoldforge.git
+cd scaffoldforge
+pip install -e .
+```
+
+## Quick Start
+
+1. Set up your GitHub Personal Access Token:
+   ```bash
+export GITHUB_TOKEN=your_github_token_here
+   ```
+
+2. Generate a project from a GitHub issue:
+   ```bash
+scaffoldforge generate https://github.com/owner/repo/issues/123
+   ```
+
+## Usage
+
+### Basic Usage
+
+Generate a project from a GitHub issue URL:
+
+```bash
+scaffoldforge generate https://github.com/owner/repo/issues/123
+```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--language` | `-l` | Programming language (python, javascript, go, rust) |
+| `--template` | `-t` | Template to use |
+| `--output` | `-o` | Output directory for generated project |
+| `--preview` | `-p` | Preview the structure without writing files |
+| `--interactive` | `-i` | Interactive mode with prompts |
+| `--verbose` | `-v` | Enable verbose output |
+
+### Examples
+
+Generate a Python project:
+
+```bash
+scaffoldforge generate https://github.com/owner/repo/issues/123 -l python
+```
+
+Preview what will be generated:
+
+```bash
+scaffoldforge generate https://github.com/owner/repo/issues/123 --preview
+```
+
+Specify custom output directory:
+
+```bash
+scaffoldforge generate https://github.com/owner/repo/issues/123 -o ./my-project
+```
+
+Interactive mode:
+
+```bash
+scaffoldforge generate https://github.com/owner/repo/issues/123 --interactive
+```
+
+List available templates:
+
+```bash
+scaffoldforge list-templates --language python
+```
+
+## Supported Languages
+
+- **Python** - Generates `main.py`, `utils.py`, `models.py`, `pyproject.toml`
+- **JavaScript** - Generates `index.js`, `utils.js`, `package.json`
+- **Go** - Generates `main.go`, `utils.go`, `go.mod`
+- **Rust** - Generates `main.rs`, `lib.rs`, `Cargo.toml`
+
+## Custom Templates
+
+You can create custom templates for ScaffoldForge. Place your templates in a directory and set the `SCAFFOLD_TEMPLATE_DIR` environment variable.
+
+```bash
+SCAFFOLD_TEMPLATE_DIR=./custom_templates scaffoldforge generate <issue_url>
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `GITHUB_TOKEN` | GitHub Personal Access Token for API access | Yes |
+| `SCAFFOLD_TEMPLATE_DIR` | Default template directory path | No |
+| `SCAFFOLD_OUTPUT_DIR` | Default output directory | No |
+
+### Configuration File
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+## How It Works
+
+1. **Issue Parsing**: Fetches the GitHub issue and parses title, description, checklist items, and labels
+2. **Language Detection**: Automatically detects programming language from labels or content
+3. **Template Selection**: Selects appropriate templates based on language
+4. **Context Generation**: Creates template context with issue data
+5. **File Generation**: Renders templates and writes files
+6. **Documentation**: Generates README.md and .gitignore
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Run tests: `pytest tests/ -v`
+6. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.