diff --git a/README.md b/README.md
index 4d4d53b..9f91587 100644
--- a/README.md
+++ b/README.md
@@ -1,68 +1,234 @@
-# Requirements to Gherkin CLI
+# Requirements to Gherkin CLI Converter
 
-Convert natural language requirements into Gherkin feature files (Given-When-Then format).
+[![CI/CD](https://7000pct.gitea.bloupla.net/7000pctAUTO/requirements-to-gherkin-cli/actions/workflows/ci.yml/badge.svg)](https://7000pct.gitea.bloupla.net/7000pctAUTO/requirements-to-gherkin-cli/actions)
+
+A powerful CLI tool that converts natural language project requirements into structured acceptance criteria in Gherkin format (Given-When-Then). Perfect for developers, QA engineers, and product managers who practice Behavior-Driven Development (BDD).
 
 ## Features
 
-- Parse natural language requirements from text files
-- Generate Gherkin feature files automatically
-- Support for multiple requirement formats
-- Configurable output directory
+- **Natural Language to Gherkin Conversion**: Parse user stories and requirements using spaCy NLP to extract actors, actions, and objects
+- **Scenario Outline Generation**: Auto-generate Scenario Outlines with Examples tables from parameterized requirements
+- **Ambiguity Detection**: Analyze requirements for vague language, unclear references, and missing conditions
+- **Multi-Format BDD Export**: Export to Cucumber (JavaScript/TypeScript), Behave (Python), and pytest-bdd (Python)
+- **Interactive CLI Mode**: Enter requirements interactively with history, editing, and inline refinement
+- **Local-Only Execution**: Runs entirely locally with no API dependencies
 
 ## Installation
 
+### From PyPI (Coming Soon)
+
 ```bash
-pip install requirements-to-gherkin-cli
+pip install nl2gherkin
 ```
 
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/requirements-to-gherkin-cli.git
+cd requirements-to-gherkin-cli
+pip install -e .
+```
+
+### Dependencies
+
+The tool requires:
+- Python 3.9+
+- spaCy with `en_core_web_sm` model (downloaded automatically)
+- Gherkin parser
+
 ## Usage
 
+### Convert a Requirements File
+
 ```bash
-python -m src.main input.txt -o output/
+nl2gherkin convert requirements.txt -o features/login.feature
 ```
 
-## Example
+**Options:**
+- `--framework, -f`: BDD framework (cucumber, behave, pytest-bdd)
+- `--output, -o`: Output file path
+- `--validate/--no-validate`: Validate Gherkin syntax (default: True)
+- `--ambiguity-check/--no-ambiguity-check`: Check for ambiguous language (default: True)
 
-Input:
-```
-The system should allow users to login with email and password
-As a registered user
-I want to be able to log into my account
-So that I can access my personalized content
+### Validate Gherkin Syntax
 
-Acceptance Criteria:
-1. User can enter email and password
-2. System validates credentials
-3. On success, user is redirected to dashboard
-4. On failure, error message is shown
+```bash
+nl2gherkin validate features/login.feature
 ```
 
-Output (feature/login.feature):
+### Interactive Mode
+
+```bash
+nl2gherkin interactive --framework behave
+```
+
+Enter requirements interactively, edit generated scenarios, and export when ready.
+
+## Examples
+
+### Input (requirements.txt)
+
+```
+As a user, I want to login so that I can access my account
+As an admin, I want to manage users so that I can control access
+```
+
+### Output (login.feature)
+
 ```gherkin
-Feature: User Login
-  As a registered user
-  I want to be able to log into my account
-  So that I can access my personalized content
+Feature: user login
+  As a user, I want to login so that I can access my account
 
-  Scenario: Successful login
-    Given the user is on the login page
-    When the user enters valid email and password
-    Then the user should be redirected to the dashboard
-
-  Scenario: Failed login
-    Given the user is on the login page
-    When the user enters invalid credentials
-    Then an error message should be displayed
+  Scenario: User login
+    Given a user wants to login
+    When the user login the account
+    Then the account should be logged in
 ```
 
-## Configuration
+### With Variables (Scenario Outline)
 
-Create a `config.yaml` file:
-```yaml
-output_directory: features/
-template: custom.gherkin.j2
+**Input:**
 ```
+As a user, I want to search for <product> so that I can find it
+```
+
+**Output:**
+```gherkin
+Feature: user search
+  As a user, I want to search for <product> so that I can find it
+
+  Scenario Outline: User search product
+    Given a user wants to search
+    When the user search the product
+    Then the product should be displayed
+
+    Examples:
+      | product |
+      | value   |
+```
+
+## Framework Export
+
+### Cucumber (JavaScript/TypeScript)
+
+```bash
+nl2gherkin convert requirements.txt --framework cucumber -o features/
+```
+
+Generates step definition templates for Cucumber.js with configuration files.
+
+### Behave (Python)
+
+```bash
+nl2gherkin convert requirements.txt --framework behave -o features/
+```
+
+Generates Python step definitions for Behave with environment configuration.
+
+### pytest-bdd (Python)
+
+```bash
+nl2gherkin convert requirements.txt --framework pytest-bdd -o features/
+```
+
+Generates pytest fixture-based step definitions with conftest.py.
+
+## Ambiguity Detection
+
+The tool detects ambiguous language in requirements:
+
+| Type | Example | Suggestion |
+|------|---------|------------|
+| Pronouns | "When it is clicked" | Replace with specific noun |
+| Vague quantifiers | "Some users" | Specify exact number |
+| Temporal terms | "Complete soon" | Specify exact deadline |
+| Missing conditions | "User must login" | Add "when" condition |
+| Passive voice | "Was created by" | Use active voice |
+
+**Example warning:**
+```
+[WARNING] Vague quantifier 'some' lacks precision
+  Suggestion: Specify an exact number or range for 'some'
+```
+
+## Development
+
+### Setup
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Download spaCy model
+python -m spacy download en_core_web_sm
+
+# Run tests
+pytest tests/ -v
+
+# Run linting
+black src/ tests/
+mypy src/
+```
+
+### Project Structure
+
+```
+requirements-to-gherkin-cli/
+├── src/nl2gherkin/
+│   ├── cli/           # Command-line interface
+│   │   ├── commands.py
+│   │   └── interactive.py
+│   ├── nlp/           # Natural language processing
+│   │   ├── analyzer.py
+│   │   ├── ambiguity.py
+│   │   └── patterns.py
+│   ├── gherkin/       # Gherkin generation
+│   │   ├── generator.py
+│   │   ├── parser.py
+│   │   └── templates.py
+│   └── exporters/     # BDD framework exporters
+│       ├── base.py
+│       ├── cucumber.py
+│       ├── behave.py
+│       └── pytest_bdd.py
+├── tests/             # Unit tests
+├── pyproject.toml
+└── README.md
+```
+
+## Testing
+
+The project includes comprehensive tests:
+
+```bash
+# Run all tests with coverage
+pytest tests/ -v --cov=src/nl2gherkin --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_analyzer.py -v
+
+# Run with detailed output
+pytest tests/ -vv
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [spaCy](https://spacy.io/) for natural language processing
+- [Gherkin Official](https://github.com/cucumber/gherkin) for Gherkin parsing
+- [Click](https://click.palletsprojects.com/) for CLI functionality