diff --git a/README.md b/README.md
index a026339..555fff2 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,249 @@
-# project-scaffold-cli
+# Project Scaffold CLI
 
-A CLI tool that generates standardized project scaffolding for multiple languages (Python, Node.js, Go, Rust) with intelligent defaults, auto-generated configs, CI/CD templates, and custom template support.
\ No newline at end of file
+A CLI tool that generates standardized project scaffolding for multiple languages (Python, Node.js, Go, Rust) with intelligent defaults, auto-generated configs, CI/CD templates, and custom template support.
+
+[![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.8+-blue.svg)](https://www.python.org/downloads/)
+
+## Features
+
+- **Multi-language templates**: Pre-built templates for Python, Node.js, Go, and Rust projects
+- **Interactive prompts**: Interactive CLI prompts for project configuration
+- **Gitignore generation**: Auto-generate language-specific .gitignore files based on best practices
+- **CI/CD templates**: Generate CI/CD pipeline templates for GitHub Actions and GitLab CI
+- **Custom template support**: Allow users to create, save, and share custom project templates
+- **Configuration file**: Support project.yaml or .project-scaffoldrc for default configurations
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install project-scaffold-cli
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/project-scaffold-cli.git
+cd project-scaffold-cli
+pip install -e .
+```
+
+## Quick Start
+
+### Generate a Python project
+
+```bash
+psc create my-python-project --language python
+```
+
+### Generate a Node.js project
+
+```bash
+psc create my-nodejs-project --language nodejs
+```
+
+### Generate with CI/CD templates
+
+```bash
+psc create my-project --language python --ci github
+```
+
+### Interactive Mode
+
+```bash
+psc create
+```
+
+## Usage
+
+### Commands
+
+#### create
+
+Create a new project scaffold.
+
+```bash
+psc create [OPTIONS] [PROJECT_NAME]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-l, --language TEXT` | Project language (python, nodejs, go, rust) |
+| `-a, --author TEXT` | Author name |
+| `-e, --email TEXT` | Author email |
+| `-d, --description TEXT` | Project description |
+| `-L, --license TEXT` | License (MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, None) |
+| `--ci TEXT` | CI/CD provider (github, gitlab, none) |
+| `-t, --template TEXT` | Custom template path or name |
+| `-c, --config FILE` | Path to configuration file |
+| `--yes` | Skip prompts and use defaults |
+| `--force` | Force overwrite existing directory |
+
+#### template
+
+Manage custom templates.
+
+```bash
+psc template [OPTIONS] COMMAND [ARGS]...
+```
+
+**Subcommands:**
+
+- `list` - List all custom templates
+- `save` - Save a new custom template
+- `delete` - Delete a custom template
+
+#### init-config
+
+Generate a template configuration file.
+
+```bash
+psc init-config --output project.yaml
+```
+
+## Configuration
+
+### Configuration File (project.yaml)
+
+Create a `project.yaml` file in your project root:
+
+```yaml
+project:
+  author: "Your Name"
+  email: "your.email@example.com"
+  license: "MIT"
+  description: "A brief description of your project"
+
+defaults:
+  language: "python"
+  ci: "github"
+  template: null
+
+template_vars:
+  python:
+    version: "3.8+"
+  nodejs:
+    version: "16+"
+```
+
+### User Configuration (~/.config/project-scaffold/config.yaml)
+
+User-level configuration for custom template paths:
+
+```yaml
+template_paths:
+  - ~/.local/share/project-scaffold/templates
+custom_templates_dir: ~/.config/project-scaffold/templates
+```
+
+## Supported Languages
+
+| Language | Files Generated |
+|----------|---------------|
+| Python | setup.py, requirements.txt, README.md, __init__.py, cli.py, test_main.py |
+| Node.js | package.json, index.js, README.md |
+| Go | go.mod, main.go, README.md |
+| Rust | Cargo.toml, src/main.rs, README.md |
+
+## Custom Templates
+
+### Creating Custom Templates
+
+1. Create a template directory with your project structure
+2. Use Jinja2 syntax for variables: `{{ project_name }}`
+3. Save the template using `psc template save`
+
+### Template Variables
+
+Available variables for all templates:
+
+- `{{ project_name }}` - Project directory name
+- `{{ project_slug }}` - kebab-case project name
+- `{{ author }}` - Author name
+- `{{ email }}` - Author email
+- `{{ description }}` - Project description
+- `{{ license }}` - License name
+- `{{ year }}` - Current year
+- `{{ language }}` - Programming language
+
+## CI/CD Support
+
+### GitHub Actions
+
+Generate `.github/workflows/ci.yml` with:
+- Linting
+- Testing
+- Code coverage
+
+### GitLab CI
+
+Generate `.gitlab-ci.yml` with:
+- Build stages
+- Test jobs
+- Deployment steps
+
+## Project Structure
+
+```
+project-scaffold-cli/
+├── project_scaffold_cli/
+│   ├── __init__.py
+│   ├── cli.py              # Main CLI interface
+│   ├── template_engine.py   # Jinja2 template rendering
+│   ├── config.py           # Configuration handling
+│   ├── prompts.py          # Interactive prompts
+│   ├── gitignore.py        # .gitignore generation
+│   └── templates/          # Built-in templates
+│       ├── python/
+│       ├── nodejs/
+│       ├── go/
+│       ├── rust/
+│       └── ci/
+├── tests/                   # Test suite
+├── docs/                    # Documentation
+├── setup.py
+├── setup.cfg
+├── requirements.txt
+├── requirements-dev.txt
+└── README.md
+```
+
+## Development
+
+### Setting up Development Environment
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/project-scaffold-cli.git
+cd project-scaffold-cli
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest -v --cov=project_scaffold_cli --cov-report=term-missing
+```
+
+### Code Formatting
+
+```bash
+ruff check --fix .
+```
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.