diff --git a/app/README.md b/app/README.md
new file mode 100644
index 0000000..836b16e
--- /dev/null
+++ b/app/README.md
@@ -0,0 +1,300 @@
+# Confgen
+
+A CLI tool that generates, validates, and manages environment-specific configuration files from templates with schema validation, secrets interpolation, diff preview, and interactive editing.
+
+## Features
+
+- **Template-based config generation**: Define templates with Jinja2-style variable placeholders
+- **Multi-environment support**: Generate configs for dev, staging, and prod environments
+- **Schema validation**: Validate generated configs against JSON Schema definitions
+- **Secrets interpolation**: Replace secret placeholders with values from env vars or vault backends
+- **Diff preview**: Show colored diff between current and generated config before applying
+- **Interactive TUI editor**: Edit config values interactively in the terminal
+- **Output with secret masking**: Mask secret values in output with *** pattern
+
+## Installation
+
+### From Source
+
+```bash
+pip install -e .
+```
+
+### Using pip
+
+```bash
+pip install confgen
+```
+
+## Quick Start
+
+1. Create a template file (e.g., `config.yaml.j2`):
+
+```yaml
+app_name: {{APP_NAME}}
+database:
+  host: {{DB_HOST}}
+  port: {{DB_PORT}}
+  password: {{env.SECRET_DB_PASSWORD}}
+```
+
+2. Create a `confgen.yaml` configuration:
+
+```yaml
+templates:
+  config:
+    path: config.yaml.j2
+    format: yaml
+
+environments:
+  dev:
+    variables:
+      APP_NAME: myapp-dev
+      DB_HOST: localhost
+      DB_PORT: 5432
+  prod:
+    variables:
+      APP_NAME: myapp
+      DB_HOST: db.example.com
+      DB_PORT: 5432
+```
+
+3. Generate a config:
+
+```bash
+confgen generate --template config --environment dev --output config.dev.yaml
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CONFGEN_TEMPLATES_DIR` | Directory containing template files | `~/.confgen/templates` |
+| `CONFGEN_CONFIG_DIR` | Directory for generated configs | `~/.confgen/output` |
+| `CONFGEN_ENV` | Default environment (dev/staging/prod) | `dev` |
+| `CONFGEN_VAULT_URL` | Vault backend URL (optional) | `` |
+| `CONFGEN_VAULT_TOKEN` | Vault authentication token (optional) | `` |
+
+### confgen.yaml
+
+The main configuration file defining templates, environments, and schema:
+
+```yaml
+templates:
+  my_config:
+    path: templates/config.yaml.j2
+    format: yaml
+    schema: schemas/config.json
+
+environments:
+  dev:
+    variables:
+      VAR1: value1
+  staging:
+    variables:
+      VAR1: value2
+  prod:
+    variables:
+      VAR1: value3
+```
+
+## Commands
+
+### generate
+
+Generate a configuration file from a template.
+
+```bash
+confgen generate [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--template, -t` | Template name (required) |
+| `--environment, -e` | Environment name (default: dev) |
+| `--output, -o` | Output file path |
+| `--format, -f` | Output format (json/yaml/toml) |
+| `--validate` | Validate generated config against schema |
+| `--diff` | Show diff before applying |
+| `--edit` | Open interactive editor |
+
+### list
+
+List available templates and environments.
+
+```bash
+confgen list [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--templates` | List available templates |
+| `--environments` | List available environments |
+| `--env` | Show variables for specific environment |
+
+### validate
+
+Validate a configuration file against a schema.
+
+```bash
+confgen validate [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--config, -c` | Config file to validate |
+| `--schema, -s` | Schema file path |
+| `--template, -t` | Template name to use its schema |
+
+### edit
+
+Open interactive editor for editing config values.
+
+```bash
+confgen edit [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--template, -t` | Template name (required) |
+| `--environment, -e` | Environment name |
+| `--output, -o` | Output file path |
+
+## Template Syntax
+
+### Variables
+
+Use Jinja2-style syntax for variable substitution:
+
+```yaml
+app_name: {{APP_NAME}}
+port: {{PORT}}
+debug: {{DEBUG_MODE}}
+```
+
+### Environment Variables
+
+Access environment variables with `env.` prefix:
+
+```yaml
+password: {{env.SECRET_PASSWORD}}
+database_url: {{env.DATABASE_URL}}
+```
+
+### Secrets (with masking)
+
+Secrets are automatically masked in output:
+
+```yaml
+api_key: {{vault.SECRET_API_KEY}}
+db_password: {{env.SECRET_DB_PASSWORD}}
+```
+
+### Conditionals
+
+Use Jinja2 conditionals:
+
+```yaml
+{% if USE_CACHE %}
+cache:
+  enabled: true
+  ttl: {{CACHE_TTL}}
+{% endif %}
+```
+
+### Loops
+
+Use Jinja2 loops:
+
+```yaml
+services:
+{% for service in SERVICES %}
+  - name: {{service.name}}
+    port: {{service.port}}
+{% endfor %}
+```
+
+## Secrets Management
+
+### Environment Variables
+
+Secrets from environment variables:
+
+```yaml
+password: {{env.SECRET_PASSWORD}}
+```
+
+### Vault Backend
+
+Secrets from a vault backend:
+
+```yaml
+api_key: {{vault.SECRET_API_KEY}}
+```
+
+Configure vault with environment variables:
+- `CONFGEN_VAULT_URL`: Vault server URL
+- `CONFGEN_VAULT_TOKEN`: Authentication token
+
+## Schema Validation
+
+Validate your configurations against JSON Schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "app_name": {"type": "string"},
+    "port": {"type": "integer", "minimum": 1, "maximum": 65535},
+    "debug": {"type": "boolean"}
+  },
+  "required": ["app_name", "port"]
+}
+```
+
+## Interactive Editor
+
+Launch an interactive terminal UI to edit config values:
+
+```bash
+confgen edit --template my_config --environment dev
+```
+
+The editor provides:
+- Type-aware input validation
+- Default values from template
+- Secret field masking
+- Environment-specific editing
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=src/confgen --cov-report=term-missing
+
+# Format code
+black src/confgen tests/
+
+# Lint code
+ruff check src/confgen tests/
+```
+
+## Examples
+
+See the `examples/` directory for complete examples:
+- `simple.yaml`: Basic template example
+- `complex.yaml`: Template with secrets and conditionals
+- `schema.json`: JSON Schema for validation
+- `confgen.yaml`: Complete configuration example
+
+## License
+
+MIT