diff --git a/README.md b/README.md
index 45f8bf4..8bd7cf6 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,414 @@
-# vibeguard
+# VibeGuard
 
-A CLI tool that scans code repositories for anti-patterns commonly introduced by AI coding assistants. Detects magic strings, inconsistent error handling, missing type annotations, and hardcoded values across Python, JavaScript, TypeScript, Go, and Rust.
\ No newline at end of file
+[![CI/CD](https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard/actions)
+[![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.10+-blue.svg)](https://www.python.org/downloads/)
+
+VibeGuard is a CLI tool that scans code repositories for anti-patterns commonly introduced by AI coding assistants. It detects patterns like magic strings without constants, inconsistent error handling, missing type annotations, overly complex one-liners, and hardcoded values.
+
+## Features
+
+- **Multi-language Support**: Analyzes Python, JavaScript, TypeScript, Go, and Rust code
+- **31+ Anti-Patterns**: Detects common AI-generated code issues across all supported languages
+- **Severity Levels**: Categorizes issues by severity (critical, error, warning, info)
+- **CI/CD Integration**: Works with GitHub Actions, GitLab CI, and other CI systems
+- **Multiple Report Formats**: Generates JSON, HTML, and SARIF reports
+- **Fix Suggestions**: Provides actionable suggestions with code examples
+- **Pre-commit Hooks**: Integrates with pre-commit for local scanning
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install vibeguard
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard.git
+cd vibeguard
+pip install -e ".[dev]"
+```
+
+### Using Homebrew
+
+```bash
+brew install vibeguard
+```
+
+## Quick Start
+
+### Basic Analysis
+
+Scan the current directory for AI anti-patterns:
+
+```bash
+vibeguard analyze .
+```
+
+Scan a specific directory:
+
+```bash
+vibeguard analyze /path/to/your/project
+```
+
+### Output Formats
+
+**Console Output (Default):**
+```bash
+vibeguard analyze .
+```
+
+**JSON Output:**
+```bash
+vibeguard analyze . --output json
+# or
+vibeguard analyze . --json
+```
+
+**HTML Report:**
+```bash
+vibeguard analyze . --html report.html
+```
+
+**SARIF Report (for GitHub Code Scanning):**
+```bash
+vibeguard analyze . --sarif results.sarif
+```
+
+### Severity Filtering
+
+Only show issues at or above a certain severity level:
+
+```bash
+vibeguard analyze . --severity error  # Only show errors and critical
+vibeguard analyze . --severity critical  # Only show critical issues
+```
+
+### Verbose Mode
+
+Enable verbose output for detailed information:
+
+```bash
+vibeguard analyze . -v
+# or
+vibeguard analyze . --verbose
+```
+
+## Configuration
+
+VibeGuard can be configured using a `.vibeguard.toml` configuration file in your project root.
+
+### Example Configuration
+
+```toml
+[analyze]
+severity_threshold = "warning"  # Options: critical, error, warning, info
+incremental = true
+workers = 4
+
+[patterns]
+# Enable all patterns
+enabled = ["all"]
+# Disable specific patterns
+disabled = ["PY001", "JS001"]
+
+[ignore]
+paths = [
+    "tests/",
+    "docs/",
+    "*.min.js",
+]
+
+[output]
+theme = "default"
+show_fixes = true
+show_snippets = true
+max_snippet_lines = 5
+
+[github]
+comment_on_pr = true
+create_check_runs = true
+```
+
+### CLI Options Override Configuration
+
+CLI options can override configuration file settings:
+
+```bash
+vibeguard analyze . --config /path/to/custom/config.toml
+vibeguard analyze . --severity error --exit-zero
+```
+
+## Anti-Patterns Detected
+
+### Python
+
+| ID | Name | Severity | Description |
+|----|------|----------|-------------|
+| PY001 | Magic String | Warning | Long string literal without explanation |
+| PY002 | Hardcoded Value | Warning | Hardcoded numeric value that should be a constant |
+| PY003 | Missing Return Type | Info | Function without return type annotation |
+| PY004 | Missing Docstring | Info | Function without docstring |
+| PY005 | Bare Except | Error | Catching all exceptions without specific type |
+| PY006 | Type Check Pattern | Warning | Using type() instead of isinstance() |
+
+### JavaScript
+
+| ID | Name | Severity | Description |
+|----|------|----------|-------------|
+| JS001 | Console Log | Warning | Console.log statement left in code |
+| JS002 | Var Keyword | Warning | Using var instead of const/let |
+| JS003 | Magic String | Warning | Long string literal without explanation |
+| JS004 | Hardcoded Value | Warning | Hardcoded numeric value |
+| JS005 | Inconsistent Error Handling | Info | Generic error variable name |
+| JS006 | Unnecessary Promise Wrapper | Warning | Unnecessary Promise constructor wrapper |
+
+### TypeScript
+
+| ID | Name | Severity | Description |
+|----|------|----------|-------------|
+| TS001 | Any Type Usage | Warning | Using 'any' type defeats TypeScript's purpose |
+| TS002 | Interface Naming | Info | Interface name should use PascalCase |
+| TS003 | Enum Usage | Info | Enum vs const object consideration |
+
+### Go
+
+| ID | Name | Severity | Description |
+|----|------|----------|-------------|
+| GO001 | Ignored Error | Error | Error being ignored with blank identifier |
+| GO002 | Context Background | Warning | Using context.Background() in production code |
+| GO003 | Potential Goroutine Leak | Warning | Goroutine without proper lifetime management |
+| GO004 | Magic String | Warning | Long string literal without explanation |
+| GO005 | Error Wrapping | Warning | Error not wrapped with %w verb |
+| GO006 | Naked Return | Warning | Naked return in function with multiple return values |
+
+### Rust
+
+| ID | Name | Severity | Description |
+|----|------|----------|-------------|
+| RS001 | Unnecessary Clone | Warning | Calling clone() on a Copy type |
+| RS002 | Allow Unused | Info | Allowing unused code instead of removing it |
+| RS003 | Expect Panic | Warning | Using expect() which can panic |
+| RS004 | Magic String | Warning | Long string literal without explanation |
+| RS005 | Unnecessary Boxing | Info | Unnecessary Box::new() usage |
+| RS006 | Into Iterator Consumption | Info | intoiter() consumes the collection |
+
+### General Patterns
+
+| ID | Name | Severity | Description |
+|----|------|----------|-------------|
+| GEN001 | Empty Catch Block | Error | Empty catch/except block that ignores errors |
+| GEN002 | Debug Code | Warning | Debug code left in production |
+| GEN003 | Inconsistent Naming | Info | Inconsistent naming convention in code |
+| GEN004 | Deep Nesting | Warning | Code with excessive nesting depth |
+
+## CI/CD Integration
+
+### GitHub Actions
+
+Create a workflow file at `.github/workflows/vibeguard.yml`:
+
+```yaml
+name: VibeGuard
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  vibeguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install VibeGuard
+        run: pip install vibeguard
+      - name: Run VibeGuard
+        run: vibeguard analyze . --severity error --sarif results.sarif
+      - name: Upload SARIF results
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+          category: "/vibeguard"
+```
+
+### GitLab CI
+
+```yaml
+vibeguard:
+  image: python:3.11-slim
+  script:
+    - pip install vibeguard
+    - vibeguard analyze . --severity error --sarif gl-sarif.json
+  artifacts:
+    when: always
+    paths:
+      - gl-sarif.json
+    reports:
+      sarif: gl-sarif.json
+```
+
+### Pre-commit Hook
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard
+  rev: v0.1.0
+  hooks:
+    - id: vibeguard
+      stages: [pre-commit]
+      args: ['--severity', 'warning']
+```
+
+## Report Formats
+
+### JSON Format
+
+```json
+{
+  "issues": [
+    {
+      "pattern": "PY001",
+      "file": "src/main.py",
+      "line": 42,
+      "severity": "warning",
+      "message": "Magic string detected",
+      "suggestion": "Extract to a named constant"
+    }
+  ],
+  "summary": {
+    "critical": 0,
+    "error": 2,
+    "warning": 15,
+    "info": 8
+  }
+}
+```
+
+### SARIF Format
+
+SARIF (Static Analysis Results Interchange Format) is supported for integration with GitHub Code Scanning and other tools.
+
+```bash
+vibeguard analyze . --sarif results.sarif
+```
+
+### HTML Report
+
+Generates a detailed HTML report with:
+- Summary statistics
+- Issues grouped by severity
+- Code snippets with highlighting
+- Fix suggestions
+
+## Development
+
+### Setting Up Development Environment
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/vibeguard.git
+cd vibeguard
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run unit tests only
+pytest tests/unit/ -v
+
+# Run integration tests only
+pytest tests/integration/ -v
+
+# Run with coverage
+pytest tests/ -v --cov=vibeguard
+```
+
+### Linting and Type Checking
+
+```bash
+# Black formatting
+black vibeguard tests
+
+# Ruff linting
+ruff check .
+
+# Type checking
+mypy vibeguard
+```
+
+### Adding New Patterns
+
+To add a new anti-pattern, extend the pattern definitions in `vibeguard/patterns/manager.py`:
+
+```python
+Pattern(
+    id="PY007",
+    name="Your Pattern Name",
+    description="Description of the pattern",
+    severity=Severity.WARNING,
+    languages=["python"],
+    message="Your message",
+    suggestion="Fix suggestion",
+    category="category-name",
+)
+```
+
+## Architecture
+
+```
+vibeguard/
+├── cli/                    # Command-line interface
+│   ├── commands/          # CLI commands (analyze, init, report)
+│   ├── output/            # Output rendering
+│   ├── main.py            # CLI entry point
+│   └── theme.py           # Rich console theme
+├── analyzers/             # Language-specific analyzers
+│   ├── languages/        # Python, JS, TS, Go, Rust analyzers
+│   ├── base.py           # Base analyzer class
+│   └── factory.py        # Analyzer factory
+├── patterns/              # Anti-pattern definitions
+│   ├── definitions.py    # Pattern and Issue classes
+│   └── manager.py        # Pattern loading and management
+├── reports/               # Report generation
+│   └── generator.py      # JSON, HTML, SARIF generation
+├── integrations/          # CI/CD integrations
+│   └── github.py         # GitHub API integration
+├── utils/                 # Utilities
+│   ├── config.py         # Configuration handling
+│   └── file_finder.py    # File discovery
+├── templates/             # HTML report templates
+├── tests/                 # Test suite
+└── __main__.py           # Package entry point
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Inspired by the growing discussion around AI-generated code quality in open-source projects
+- Built with Click, Rich, and Tree-sitter for robust CLI and parsing capabilities