diff --git a/README.md b/README.md
index bf3a5fd..6194043 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,145 @@
-# dependency-freshness-checker
+# Dependency Freshness Checker CLI
 
-A CLI tool that monitors outdated dependencies across npm, pip, go, cargo with security CVE scanning
\ No newline at end of file
+A CLI tool that monitors outdated dependencies across multiple package managers (npm, pip, go, cargo) with security vulnerability context.
+
+## Features
+
+- **Multi-package manager support**: Parse and analyze dependency files for npm, pip, go, and cargo
+- **Security CVE scanning**: Bundled CVE knowledge base with severity levels
+- **Interactive terminal UI**: Color-coded output using Rich
+- **CI/CD integration**: JSON output and proper exit codes
+- **Configuration system**: YAML-based configuration
+- **Upgrade recommendations**: Suggest minimal safe upgrades
+
+## Installation
+
+```bash
+pip install depcheck
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Basic Usage
+
+Scan the current directory for outdated dependencies:
+
+```bash
+depcheck scan
+```
+
+Scan a specific file:
+
+```bash
+depcheck scan package.json
+depcheck scan requirements.txt
+```
+
+### Options
+
+- `--json`: Output in JSON format
+- `--ci`: CI/CD mode with proper exit codes
+- `--fail-level`: Set severity threshold for failures (critical, high, medium, low)
+- `--exclude-dev`: Exclude dev dependencies
+- `--verbose`: Enable verbose output
+- `--quiet`: Suppress non-essential output
+
+### Exit Codes
+
+- `0`: All dependencies are fresh
+- `1`: Outdated or vulnerable dependencies found
+- `2`: Error occurred during scan
+
+## Configuration
+
+Create a `.depcheck.yaml` file in your project root:
+
+```yaml
+ignore_patterns:
+  - "test/"
+  - "example/"
+
+ignore_packages:
+  - "@types/*"
+
+fail_level: medium
+
+output:
+  format: terminal
+  verbose: false
+
+include_dev: true
+
+package_managers:
+  - npm
+  - pip
+```
+
+Configuration is also read from `~/.config/depcheck/.depcheck.yaml`.
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+- name: Check dependencies
+  run: depcheck scan --ci --fail-level high
+```
+
+### GitLab CI Example
+
+```yaml
+dependency_check:
+  script:
+    - depcheck scan --ci --json > dependency-report.json
+  artifacts:
+    paths:
+      - dependency-report.json
+```
+
+## Supported Package Managers
+
+| Package Manager | Files |
+|----------------|-------|
+| npm | package.json |
+| pip | requirements.txt, pyproject.toml |
+| go | go.mod |
+| cargo | Cargo.toml |
+
+## Security
+
+The tool includes a bundled CVE database with known vulnerabilities for common packages. It checks your dependencies against this database and reports any matches with severity levels.
+
+## Development
+
+### Running Tests
+
+```bash
+pytest -q --cov=src --cov-report=term
+pytest -q tests/integration/
+```
+
+### Project Structure
+
+```
+depcheck/
+├── src/depcheck/
+│   ├── parsers/       # Package manager parsers
+│   ├── analyzers/     # CVE and version analyzers
+│   ├── reporters/     # Output formatters
+│   ├── config.py      # Configuration handling
+│   └── cli.py         # CLI entry point
+├── tests/
+│   ├── unit/          # Unit tests
+│   └── integration/   # Integration tests
+└── data/              # Bundled CVE database
+```
+
+## License
+
+MIT License