diff --git a/README.md b/README.md
index 614e5d5..82208cc 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,233 @@
-# confdoc
+# ConfDoc - Configuration Validation and Documentation Generator
 
-A CLI tool that validates JSON/YAML/TOML configuration files against a schema and auto-generates human-readable documentation
\ No newline at end of file
+A powerful CLI tool for validating JSON/YAML/TOML configuration files against a schema with clear error messages, and auto-generating human-readable markdown documentation from your schemas.
+
+## Features
+
+- **Multi-format Support**: Parse and validate JSON, YAML, and TOML configuration files
+- **Schema Validation**: Validate configurations against JSON Schema with detailed, actionable error messages
+- **Auto-generated Documentation**: Generate clean markdown documentation from your schemas
+- **Environment Profiles**: Built-in development, staging, and production profiles with validation rules
+- **Type Inference**: Automatically infer schema from existing configurations
+- **CLI Interface**: Easy-to-use commands for validation, documentation, and schema initialization
+
+## Installation
+
+```bash
+# Install from PyPI
+pip install confdoc
+
+# Or install with development dependencies
+pip install confdoc[dev]
+```
+
+## Quick Start
+
+### Validate a Configuration File
+
+```bash
+confdoc validate config.json --schema schema.json
+```
+
+### Generate Documentation
+
+```bash
+confdoc doc schema.json --output CONFIGURATION.md
+```
+
+### Initialize a New Schema
+
+```bash
+# Create a starter schema
+confdoc init schema.json
+
+# Or infer schema from existing config
+confdoc init schema.json --config config.yaml
+```
+
+## Usage
+
+### validate Command
+
+Validate a configuration file against a schema:
+
+```bash
+confdoc validate <config-file> [OPTIONS]
+```
+
+Options:
+- `--schema, -s`: Path to schema file (default: schema.json)
+- `--format, -f`: Config format: json, yaml, toml, auto (default: auto)
+- `--profile, -p`: Profile to apply (development, staging, production)
+- `--output, -o`: Output format: text, json (default: text)
+
+Example:
+```bash
+confdoc validate config.yaml --schema schema.json --profile development
+```
+
+### doc Command
+
+Generate markdown documentation from a schema:
+
+```bash
+confdoc doc <schema-file> [OPTIONS]
+```
+
+Options:
+- `--output, -o`: Output file path
+- `--title, -t`: Document title
+- `--format, -f`: Output format (default: markdown)
+
+Example:
+```bash
+confdoc doc schema.json --output docs/configuration.md --title "My App Config"
+```
+
+### init Command
+
+Initialize a new schema file:
+
+```bash
+confdoc init [output-file] [OPTIONS]
+```
+
+Options:
+- `--config, -c`: Generate schema from existing config file
+
+Example:
+```bash
+# Create a starter schema
+confdoc init
+
+# Infer schema from config
+confdoc init schema.json --config config.toml
+```
+
+## Examples
+
+### Example Configuration (config.json)
+
+```json
+{
+  "app": {
+    "name": "myapp",
+    "version": "1.0.0",
+    "debug": true
+  },
+  "database": {
+    "host": "localhost",
+    "port": 5432,
+    "name": "mydb"
+  }
+}
+```
+
+### Example Schema (schema.json)
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Application Configuration",
+  "type": "object",
+  "properties": {
+    "app": {
+      "type": "object",
+      "properties": {
+        "name": {"type": "string", "description": "Application name"},
+        "version": {"type": "string", "description": "Application version"},
+        "debug": {"type": "boolean", "description": "Enable debug mode", "default": false}
+      },
+      "required": ["name"]
+    },
+    "database": {
+      "type": "object",
+      "properties": {
+        "host": {"type": "string", "description": "Database host"},
+        "port": {"type": "integer", "description": "Database port", "minimum": 1, "maximum": 65535},
+        "name": {"type": "string", "description": "Database name"}
+      }
+    }
+  },
+  "required": ["app", "database"]
+}
+```
+
+## Schema Reference
+
+ConfDoc uses JSON Schema for validation. Supported keywords:
+
+- `type`: string, integer, number, boolean, object, array, null
+- `required`: Array of required property names
+- `properties`: Object defining each property's schema
+- `enum`: List of allowed values
+- `minimum`, `maximum`: Numeric constraints
+- `minLength`, `maxLength`: String length constraints
+- `pattern`: Regular expression pattern
+- `default`: Default value for the property
+- `description`: Human-readable description
+
+## Environment Profiles
+
+ConfDoc includes built-in profiles:
+
+| Profile | Description |
+|---------|-------------|
+| development | Lenient validation, allows extra properties |
+| staging | Strict validation, no extra properties |
+| production | Strict validation, no extra properties |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CONFDOC_CONFIG_PATH` | Default config path |
+| `CONFDOC_DEFAULT_SCHEMA` | Default schema file |
+
+### Programmatic Usage
+
+```python
+from confdoc.parsers import ConfigParserFactory
+from confdoc.validator import SchemaValidator
+from confdoc.docs import DocGenerator
+
+# Parse a config file
+factory = ConfigParserFactory()
+parser = factory.get_parser_for_file("config.json")
+config = parser.parse(content)
+
+# Validate against schema
+validator = SchemaValidator()
+is_valid, errors = validator.validate(config, schema)
+
+# Generate documentation
+doc_gen = DocGenerator()
+docs = doc_gen.generate(schema, "My Config")
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/confdoc.git
+cd confdoc
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=confdoc --cov-report=term-missing
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.