diff --git a/README.md b/README.md
new file mode 100644
index 0000000..87a4d90
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# test-samurai.nvim
+
+A Neovim plugin to run tests across multiple languages and frameworks with a unified UX and an extensible runner architecture.
+
+## Requirements
+
+- Neovim >= 0.11.4
+- Lua
+- Test runners are provided as separate Lua modules
+
+## Installation (Lazy.nvim)
+
+Use the GitHub repository. The example below shows how to add the Go runner as a dependency and configure it in `setup()`:
+
+```lua
+{
+  "m13r/test-samurai.nvim",
+  dependencies = {
+    "m13r/test-samurai-go-runner",
+    -- furthur samurai runners
+  },
+  config = function()
+    require("test-samurai").setup({
+      runner_modules = {
+        "test-samurai-go-runner",
+        -- furthur samurai runners
+      },
+    })
+  end,
+}
+```
+
+## Configuration
+
+### Runner modules (required)
+
+test-samurai does not ship with any built-in runners. You must explicitly configure the runners you want to use:
+
+```lua
+require("test-samurai").setup({
+  runner_modules = {
+    "my-runners.go",
+    "my-runners.js",
+  },
+})
+```
+
+If no runner matches the current test file, test-samurai will show:
+
+```
+[test-samurai] no runner installed for this kind of test
+```
+
+## Commands and keymaps
+
+- `TSamNearest` -> `<leader>tn`
+- `TSamFile` -> `<leader>tf`
+- `TSamAll` -> `<leader>ta`
+- `TSamLast` -> `<leader>tl`
+- `TSamFailedOnly` -> `<leader>te`
+- `TSamShowOutput` -> `<leader>to`
+
+Additional keymaps:
+
+- `<leader>qn` -> close the testing floats and jump to the first quickfix entry
+- `<leader>nf` -> jump to the next `[ FAIL ]` entry in the Test-Listing-Float (wraps to the first)
+- `<leader>pf` -> jump to the previous `[ FAIL ]` entry in the Test-Listing-Float (wraps to the last)
+
+## Output UI
+
+- Output is shown in a floating container called **Testing-Float**.
+- The **Test-Listing-Float** is the left subwindow and shows the test result list.
+- The **Detail-Float** is the right subwindow and shows detailed output for a selected test.
+- After `TSamNearest`, `TSamFile`, `TSamAll`, `TSamFailedOnly`, etc., the UI opens in listing mode (only **Test-Listing-Float** visible).
+- Press `<cr>` on a `[ FAIL ] ...` line in the listing to open/update the **Detail-Float** as a 20/80 split (left 20% listing, right 80% detail).
+- ANSI color translation is only applied in the **Detail-Float**; the **Test-Listing-Float** shows raw text without ANSI translation.
+- `<esc><esc>` hides the floating window; `TSamShowOutput` reopens it.
+
+## Runner architecture
+
+Runners are standalone Lua modules. All runner modules are expected to implement the full interface so every command and keymap works.
+Required functions:
+
+- `is_test_file`
+- `find_nearest`
+- `build_command`
+- `build_file_command`
+- `build_all_command`
+- `build_failed_command`
+- `collect_failed_locations`
+
+No runner for your environment exists? No problem: use `runners-agents.md` to guide an AI-assisted runner implementation tailored to your stack.
+
+## Known runners
+
+- [`m13r/test-samurai-go-runner`](https://gitea.mschirmer.com/m13r/test-samurai-go-runner)
+- [`m13r/test-samurai-jest-runner`](https://gitea.mschirmer.com/m13r/test-samurai-jest-runner)
+- [`m13r/test-samurai-mocha-runner`](https://gitea.mschirmer.com/m13r/test-samurai-mocha-runner)
+- [`m13r/test-samurai-vitest-runner`](https://gitea.mschirmer.com/m13r/test-samurai-vitest-runner)
+
+## Development
+
+Tests are written with `plenary.nvim` / `busted`. Mocks and stubs are allowed.
+
+Run tests:
+
+```sh
+bash run_test.sh
+```