diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7954bac
--- /dev/null
+++ b/README.md
@@ -0,0 +1,298 @@
+# JQuote.nvim
+
+A powerful Neovim plugin for cycling through quote characters with intelligent auto-jump functionality.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Lua](https://img.shields.io/badge/Made%20with-Lua-blueviolet.svg)](https://lua.org)
+[![Neovim](https://img.shields.io/badge/NeoVim-%2357A143.svg?&style=for-the-badge&logo=neovim&logoColor=white)](https://neovim.io)
+
+## ✨ Features
+
+- **🔄 Quote Cycling**: Seamlessly cycle through different quote characters (`'`, `"`, `` ` ``)
+- **🎯 Auto Jump**: Automatically jump to the next quote pair when cursor is not inside quotes
+- **⚙️ Configurable**: Customize quote characters, hotkeys, and jump behavior
+- **🛡️ Enterprise-Grade**: Comprehensive error handling and defensive programming
+- **📊 Health Monitoring**: Built-in health check and diagnostics
+- **🏗️ Version Management**: Dynamic version detection from git tags
+- **🧪 Thoroughly Tested**: Comprehensive unit test suite with 25+ test cases
+
+## 📋 Requirements
+
+- Neovim 0.5.0 or later
+- Lua 5.1+
+
+## 📦 Installation
+
+### Using [lazy.nvim](https://github.com/folke/lazy.nvim)
+
+```lua
+{
+  "your-username/jquote.nvim",
+  config = function()
+    require("jquote").setup({
+      -- Optional configuration
+      hotkey = "<leader>tq",
+      quote_chars = { "'", '"', "`" },
+      jump_behavior = "auto"
+    })
+  end,
+}
+```
+
+### Using [packer.nvim](https://github.com/wbthomason/packer.nvim)
+
+```lua
+use {
+  "your-username/jquote.nvim",
+  config = function()
+    require("jquote").setup()
+  end
+}
+```
+
+### Using [vim-plug](https://github.com/junegunn/vim-plug)
+
+```vim
+Plug 'your-username/jquote.nvim'
+
+lua << EOF
+require("jquote").setup()
+EOF
+```
+
+### Manual Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/jquote.nvim.git ~/.config/nvim/lua/jquote
+
+# Or use the Makefile
+make install
+```
+
+## ⚙️ Configuration
+
+### Default Configuration
+
+```lua
+require("jquote").setup({
+  hotkey = "<leader>tq",              -- Key binding for quote toggle
+  quote_chars = { "'", '"', "`" },    -- Quote characters to cycle through
+  jump_behavior = "auto"              -- "auto" or "manual" jump behavior
+})
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `hotkey` | `string` | `"<leader>tq"` | Key mapping for toggling quotes |
+| `quote_chars` | `table` | `{ "'", '"', "`" }` | List of quote characters to cycle through |
+| `jump_behavior` | `string` | `"auto"` | Jump behavior when cursor is not in quotes (`"auto"` or `"manual"`) |
+
+### Custom Configuration Examples
+
+```lua
+-- Minimal setup with custom hotkey
+require("jquote").setup({
+  hotkey = "<leader>q"
+})
+
+-- Custom quote characters
+require("jquote").setup({
+  quote_chars = { "'", '"' }  -- Only single and double quotes
+})
+
+-- Manual jump behavior
+require("jquote").setup({
+  jump_behavior = "manual"  -- Don't auto-jump, only toggle quotes at cursor
+})
+
+-- Full customization
+require("jquote").setup({
+  hotkey = "<C-q>",
+  quote_chars = { "'", '"', "`", "«", "»" },  -- Including Unicode quotes
+  jump_behavior = "auto"
+})
+```
+
+## 🚀 Usage
+
+### Basic Usage
+
+1. **Toggle Quotes**: Place your cursor inside or on a quoted string and press `<leader>tq` (or your configured hotkey)
+2. **Auto Jump**: When cursor is not inside quotes, the plugin automatically jumps to the next quote pair forward
+
+### Examples
+
+```lua
+-- Before: cursor anywhere in 'hello world'
+'hello world'
+
+-- After pressing <leader>tq
+"hello world"
+
+-- After pressing <leader>tq again
+`hello world`
+
+-- After pressing <leader>tq again (cycles back)
+'hello world'
+```
+
+### Auto Jump Feature
+
+```lua
+-- Before: cursor at beginning of line
+hello 'world' and "test"
+^
+
+-- After pressing <leader>tq (auto-jumps to first quote)
+hello 'world' and "test"
+      ^
+-- And toggles the quotes
+hello "world" and "test"
+```
+
+### Multiple Quote Pairs
+
+```lua
+-- Works with multiple quote pairs on the same line
+print('Hello', "World", `Template`)
+
+-- Handles nested quotes intelligently
+outer "inner 'nested' text" end
+```
+
+## 🔧 Commands and Functions
+
+### Available Functions
+
+```lua
+local jquote = require("jquote")
+
+-- Setup the plugin
+jquote.setup(options)
+
+-- Toggle quotes at cursor position
+jquote.toggle_quotes()
+
+-- Get current plugin version
+local version = jquote.get_version()
+
+-- Get plugin health information
+local health = jquote.health()
+```
+
+### Health Check
+
+Check plugin status and configuration:
+
+```lua
+:lua print(vim.inspect(require("jquote").health()))
+```
+
+Output example:
+```lua
+{
+  hotkey_configured = true,
+  jump_behavior_valid = true,
+  options = { ... },
+  plugin_version = "1.2.0",
+  quote_chars_count = 3
+}
+```
+
+## 🧪 Development
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Check syntax
+make check
+
+# Run development checks (syntax + tests)
+make dev-check
+
+# Quick development workflow
+make quick
+```
+
+### Test Coverage
+
+The plugin includes comprehensive unit tests covering:
+
+- ✅ Plugin initialization and configuration
+- ✅ Quote detection and cycling
+- ✅ Auto jump functionality
+- ✅ Error handling and edge cases
+- ✅ Version management
+- ✅ Health monitoring
+- ✅ Boundary conditions and defensive programming
+
+### Project Structure
+
+```
+jquote.nvim/
+├── lua/
+│   └── jquote/
+│       └── init.lua          # Main plugin code
+├── tests/
+│   ├── init_spec.lua         # Comprehensive test suite
+│   ├── test_runner.lua       # Custom test framework
+│   └── README.md             # Testing documentation
+├── Makefile                  # Development workflow
+└── README.md                 # This file
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please ensure:
+
+1. **Code Quality**: Follow the established corporate clean code standards
+2. **Testing**: Add tests for new features and ensure all tests pass
+3. **Documentation**: Update documentation for any new features or changes
+
+### Development Workflow
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/jquote.nvim.git
+cd jquote.nvim
+
+# Run tests
+make test
+
+# Check code quality
+make check
+
+# Install for local development
+make install
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by the need for efficient quote management in Neovim
+- Built with enterprise-grade reliability and comprehensive testing
+- Designed for developer productivity and workflow optimization
+
+## 📞 Support
+
+If you encounter any issues or have suggestions:
+
+1. Check the [Issues](https://github.com/your-username/jquote.nvim/issues) page
+2. Run the health check: `:lua print(vim.inspect(require("jquote").health()))`
+3. Create a new issue with:
+   - Your configuration
+   - Health check output
+   - Steps to reproduce the problem
+
+---
+
+**Made with ❤️ for the Neovim community**
\ No newline at end of file