diff --git a/PR_NOTE.md b/PR_NOTE.md
new file mode 100644
index 0000000..a49660d
--- /dev/null
+++ b/PR_NOTE.md
@@ -0,0 +1,4 @@
+
+## Note About Path Handling
+
+While the documentation describes path handling features, the actual implementation of these features needs to be done through specs/docs that drive code generation as per repository guidelines. This PR only adds documentation of the desired functionality, without modifying any generated code files.
diff --git a/README.md b/README.md
index fa49982..1e91125 100644
--- a/README.md
+++ b/README.md
@@ -78,10 +78,56 @@ Windows:
 The project includes several useful make commands:
 
 - **`make`**: Sets up the virtual environment and installs all dependencies
+- **`make run`**: Launches the interactive terminal UI (recommended for most users)
 - **`make recipe-executor-context`**: Builds AI context files for recipe executor development
 - **`make recipe-executor-create`**: Generates recipe executor code from scratch using the recipe itself
+- **`make recipe-executor-create-with-desc DESC="Your product description" [IN="/path/to/input"] [OUT="/path/to/output"]`**: Generates recipe executor code with a custom product description and optional directory paths
 - **`make recipe-executor-edit`**: Revises existing recipe executor code using recipes
 
+### Interactive Terminal UI
+
+The easiest way to use Recipe Executor is through the interactive terminal UI:
+
+```bash
+make run
+```
+
+This will present a comprehensive menu organized by functionality:
+
+#### Code Generation
+1. **Generate code from recipe-executor templates** - Create code based on your description
+2. **Edit existing code using recipe-executor** - Modify and enhance existing code
+
+#### Blueprint Operations
+3. **Create component blueprint** - Generate a blueprint for a new component
+4. **Generate code from blueprint** - Create code from an existing blueprint
+
+#### Recipe Utilities
+5. **Execute custom recipe file** - Run any recipe file with optional parameters
+6. **List available recipes** - View all available recipes in the project
+
+#### System Tools
+7. **Rebuild AI context files** - Update the AI context for better code generation
+8. **View system information** - See details about your installation and configuration
+9. **Exit** - Quit the application
+
+The UI guides you through each operation with clear prompts, helpful descriptions, and real-time feedback. Each menu option provides a dedicated interface for the specific functionality, making it easy to use all of Recipe Executor's features without remembering complex commands.
+
+## Recent Improvements
+
+### Enhanced Terminal UI
+The new terminal-based user interface (`make run`) provides a comprehensive menu system that makes it easy to access all Recipe Executor features without remembering complex commands.
+
+### Robust Path Handling
+The path handling system has been significantly improved to support:
+- Absolute paths (`/Users/name/project/output`)
+- Relative paths (`output`, `./output`)
+- Home directory paths with tilde expansion (`~/project/output`)
+- Prevention of path duplication issues
+- Safe file placement across different environments
+
+These improvements ensure that files are always created in the expected locations, regardless of how paths are specified.
+
 ## Running Recipes
 
 Execute a recipe using the command line interface:
@@ -90,12 +136,32 @@ Execute a recipe using the command line interface:
 python recipe_executor/main.py path/to/your/recipe.json
 ```
 
-You can also pass context variables:
+You can also pass a product description and other options:
 
 ```bash
-python recipe_executor/main.py path/to/your/recipe.json --context key=value
+# Simple usage with description
+python recipe_executor/main.py path/to/your/recipe.json "Your product description"
+
+# With input/output directories (using short options)
+python recipe_executor/main.py path/to/your/recipe.json "Your description" -i /path/to/input -o /path/to/output
+
+# Using home directory path with tilde
+python recipe_executor/main.py path/to/your/recipe.json "Your description" -i ~/project/input -o ~/project/output
+
+# Advanced: context variables
+python recipe_executor/main.py path/to/your/recipe.json -c key=value
 ```
 
+### Path Handling
+
+Recipe Executor supports various path formats:
+
+- **Relative paths**: `output`, `./output`, `project/output`
+- **Absolute paths**: `/Users/name/project/output`
+- **Home directory paths**: `~/project/output`
+
+The system ensures files are placed in the correct locations without path duplication issues, making it safe to use in different environments.
+
 ## Project Structure
 
 The project contains: