diff --git a/README.md b/README.md
index f9e94756b..01235425e 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 </p>
 
 <h2 align="center">
-  Scriptable interface to a powerful, multi-lingual language server.
+  A natural, intuitive API for code manipulation and analysis
 </h2>
 
 <div align="center">
@@ -22,7 +22,7 @@
 
 <br />
 
-[Codegen](https://docs.codegen.com) is a python library for manipulating codebases.
+[Codegen](https://docs.codegen.com) is a Python library for manipulating and analyzing codebases with a natural, intuitive API.
 
 ```python
 from codegen import Codebase
@@ -41,18 +41,27 @@ for function in codebase.functions:
 
 Write code that transforms code. Codegen combines the parsing power of [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) with the graph algorithms of [rustworkx](https://github.com/Qiskit/rustworkx) to enable scriptable, multi-language code manipulation at scale.
 
+## Features
+
+- **Intuitive API**: Manipulate code with natural operations like `move`, `rename`, and `add_parameter`
+- **Multi-language support**: Works with Python, TypeScript, JavaScript, and React codebases
+- **Comprehensive analysis**: Analyze dependencies, references, and relationships between code elements
+- **Import management**: Automatically handles imports when moving or refactoring code
+- **Scriptable transformations**: Create reusable scripts for common refactoring patterns
+- **Enterprise-ready**: Scales to handle codebases with millions of lines of code
+
 ## Installation and Usage
 
-We support
+We support:
 
 - Running Codegen in Python 3.12 - 3.13 (recommended: Python 3.13+)
 - macOS and Linux
   - macOS is supported
   - Linux is supported on x86_64 and aarch64 with glibc 2.34+
   - Windows is supported via WSL. See [here](https://docs.codegen.com/building-with-codegen/codegen-with-wsl) for more details.
-- Python, Typescript, Javascript and React codebases
+- Python, TypeScript, JavaScript and React codebases
 
-```
+```bash
 # Install inside existing project
 uv pip install codegen
 
@@ -62,7 +71,7 @@ uv tool install codegen --python 3.13
 # Create a codemod for a given repo
 cd path/to/repo
 codegen init
-codegen create test-function
+codegen create PATH test-function
 
 # Run the codemod
 codegen run test-function
@@ -75,8 +84,32 @@ codegen notebook
 
 See [Getting Started](https://docs.codegen.com/introduction/getting-started) for a full tutorial.
 
-```
+```python
 from codegen import Codebase
+
+# Initialize a codebase
+codebase = Codebase("./")
+
+# Find and manipulate functions
+for function in codebase.functions:
+    # Add type hints to parameters
+    if function.name == "process_data" and not function.return_type:
+        function.set_return_type("Dict[str, Any]")
+
+    # Rename variables consistently
+    for variable in function.variables:
+        if variable.name == "data" and function.name.startswith("process_"):
+            variable.rename("input_data")
+
+# Move classes between files
+user_class = codebase.classes.find(name="User")
+if user_class:
+    user_class.move_to_file("models/user.py")
+
+# Add imports where needed
+for py_file in codebase.files(extension=".py"):
+    if "process_data" in py_file.content and "typing" not in py_file.imports:
+        py_file.add_import("from typing import Dict, Any")
 ```
 
 ## Troubleshooting
@@ -91,7 +124,9 @@ If you run into additional issues not listed here, please [join our slack commun
 
 ## Resources
 
-- [Docs](https://docs.codegen.com)
+- [Documentation](https://docs.codegen.com)
+- [API Reference](https://docs.codegen.com/api-reference)
+- [CLI Commands](https://docs.codegen.com/cli)
 - [Getting Started](https://docs.codegen.com/introduction/getting-started)
 - [Contributing](CONTRIBUTING.md)
 - [Contact Us](https://codegen.com/contact)