diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1945a98
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# 🐰 coderabbit.nvim
+
+[![CI](https://github.com/smnatale/coderabbit.nvim/actions/workflows/ci.yml/badge.svg)](https://github.com/smnatale/coderabbit.nvim/actions/workflows/ci.yml) [![Neovim](https://img.shields.io/badge/Neovim-0.10%2B-green?logo=neovim&logoColor=white)](https://neovim.io)
+
+The first Neovim integration for [CodeRabbit](https://coderabbit.link/sam-natale) — bringing the AI code reviewing assistant to your favorite editor!
+
+> Not affiliated with CodeRabbit — just a fan. If you sign up, using the [link above](https://coderabbit.link/sam-natale) helps me out.
+
+## Getting Started
+
+Requires Neovim >= 0.10 and the [CodeRabbit CLI](https://cli.coderabbit.ai):
+
+```sh
+curl -fsSL https://cli.coderabbit.ai/install.sh | sh
+cr auth login
+```
+
+Install the plugin and call setup:
+
+```lua
+-- vim.pack (nvim 0.12)
+vim.pack.add({"https://github.com/smnatale/coderabbit.nvim"})
+require("coderabbit").setup()
+
+-- lazy.nvim
+{ "smnatale/coderabbit.nvim", opts = {} }
+```
+
+Run `:checkhealth coderabbit` to verify everything is wired up.
+
+## Usage
+
+`:CodeRabbitReview` to kick off a review. Findings show up as diagnostics with virtual text, signs, and code actions (`vim.lsp.buf.code_action()`).
+
+| Command | |
+| --- | --- |
+| `:CodeRabbitReview [type]` | Run a review. Defaults to `all`, or pass `committed`/`uncommitted` |
+| `:CodeRabbitStop` | Cancel a running review |
+| `:CodeRabbitClear` | Clear diagnostics |
+| `:CodeRabbitShow [id]` | View results in a split. Defaults to the latest review |
+| `:CodeRabbitHistory` | Browse past reviews |
+
+For your statusline:
+
+```lua
+require("coderabbit").status()  -- spinner while reviewing, nil when idle
+```
+
+## Config
+
+Defaults — everything is optional:
+
+```lua
+require("coderabbit").setup({
+  cli = {
+    binary = "cr",
+    timeout = 0,
+    extra_args = {},
+  },
+  review = {
+    type = "all",  -- "all", "committed", or "uncommitted"
+    base = nil,
+    base_commit = nil,
+  },
+  diagnostics = {
+    enabled = true,
+    severity_map = {
+      critical = vim.diagnostic.severity.ERROR,
+      major = vim.diagnostic.severity.WARN,
+      minor = vim.diagnostic.severity.INFO,
+    },
+    virtual_text = true,
+    signs = true,
+    underline = true,
+  },
+  on_review_complete = nil,
+})
+```
diff --git a/doc/coderabbit.txt b/doc/coderabbit.txt
new file mode 100644
index 0000000..08e7dfc
--- /dev/null
+++ b/doc/coderabbit.txt
@@ -0,0 +1,123 @@
+*coderabbit.txt*    Neovim plugin for CodeRabbit AI code reviews
+
+==============================================================================
+CONTENTS                                                  *coderabbit-contents*
+
+  1. Introduction ............................ |coderabbit-introduction|
+  2. Setup ................................... |coderabbit-setup|
+  3. Configuration ........................... |coderabbit-configuration|
+  4. Commands ................................ |coderabbit-commands|
+  5. Lua API ................................. |coderabbit-api|
+
+==============================================================================
+INTRODUCTION                                          *coderabbit-introduction*
+
+Run CodeRabbit AI code reviews from Neovim. Findings appear as native
+|vim.diagnostic| entries with virtual text, signs, and code actions.
+
+Requirements:
+- Neovim >= 0.10
+- CodeRabbit CLI (`cr`): https://cli.coderabbit.ai
+
+==============================================================================
+SETUP                                                        *coderabbit-setup*
+
+>lua
+    require("coderabbit").setup({})
+<
+
+Run `:checkhealth coderabbit` to verify CLI installation and auth.
+
+==============================================================================
+CONFIGURATION                                        *coderabbit-configuration*
+
+All options are optional. Defaults: >lua
+    require("coderabbit").setup({
+      cli = {
+        binary = "cr",
+        timeout = 0,
+        extra_args = {},
+      },
+      review = {
+        type = "all",
+        base = nil,
+        base_commit = nil,
+      },
+      diagnostics = {
+        enabled = true,
+        severity_map = {
+          critical = vim.diagnostic.severity.ERROR,
+          major = vim.diagnostic.severity.WARN,
+          minor = vim.diagnostic.severity.INFO,
+        },
+        virtual_text = true,
+        signs = true,
+        underline = true,
+      },
+      on_review_complete = nil,
+    })
+<
+
+cli.binary          Path to the CodeRabbit CLI. Default: `"cr"`
+cli.timeout         Timeout in ms. `0` = no timeout.
+cli.extra_args      Extra arguments for `cr review`.
+
+review.type         `"all"`, `"committed"`, or `"uncommitted"`.
+review.base         Base branch for comparison.
+review.base_commit  Base commit SHA for comparison.
+
+diagnostics.enabled     Populate |vim.diagnostic| with findings.
+diagnostics.severity_map  Map CodeRabbit severities to |vim.diagnostic.severity|.
+diagnostics.virtual_text  Show inline virtual text.
+diagnostics.signs         Show sign column indicators.
+diagnostics.underline     Underline diagnostic ranges.
+
+on_review_complete  Callback receiving the findings table when a review
+                    finishes.
+
+==============================================================================
+COMMANDS                                                  *coderabbit-commands*
+
+:CodeRabbitReview [type]                                  *:CodeRabbitReview*
+    Start a review. Optional: `all`, `committed`, `uncommitted`.
+
+:CodeRabbitStop                                             *:CodeRabbitStop*
+    Cancel a running review.
+
+:CodeRabbitClear                                           *:CodeRabbitClear*
+    Clear all CodeRabbit diagnostics.
+
+:CodeRabbitShow [id]                                        *:CodeRabbitShow*
+    Open review results in a vertical split. Pass an `id` from
+    `:CodeRabbitHistory` to view a saved review. Press `q` to close.
+
+:CodeRabbitHistory                                       *:CodeRabbitHistory*
+    Browse saved reviews via |vim.ui.select|.
+
+==============================================================================
+LUA API                                                       *coderabbit-api*
+
+require("coderabbit").setup({opts})                       *coderabbit.setup()*
+    Configure the plugin.
+
+require("coderabbit").review({opts})                     *coderabbit.review()*
+    Start a review. Accepts `{ type, base, base_commit }`.
+
+require("coderabbit").stop()                               *coderabbit.stop()*
+    Cancel the running review.
+
+require("coderabbit").clear()                             *coderabbit.clear()*
+    Clear diagnostics and reset state.
+
+require("coderabbit").show({id})                           *coderabbit.show()*
+    Open the review buffer. `nil` = current, number = saved.
+
+require("coderabbit").history()                         *coderabbit.history()*
+    Open the review history picker.
+
+require("coderabbit").status()                           *coderabbit.status()*
+    Returns `"⠋ CodeRabbit (12s)"` while reviewing, `nil` when idle.
+    Designed for statusline use.
+
+==============================================================================
+vim:tw=78:ts=8:ft=help:norl: