diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..680bf063
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,68 @@
+# Project guide
+
+`copilot.lua` provides a pure `Lua` replacement for `github/copilot.vim`
+and integrates GitHub Copilot with Neovim's built-in language server
+protocol client.
+
+## Overview
+
+- **Purpose:** efficient, modular GitHub Copilot support for Neovim.
+- **Runtime:** Neovim 0.10+ (`Lua` 5.1 or `LuaJIT`); Neovim 0.11+
+  recommended.
+- **Server:** GitHub Copilot language server, powered by Node.js v20+.
+- **Tests:**
+  [`mini.test`](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-test.md).
+
+## Architecture
+
+- `lua/copilot/init.lua`: plugin entry point and setup.
+- `lua/copilot/client/`: language server lifecycle and buffer
+  attachment.
+- `lua/copilot/suggestion/`: ghost text suggestions and key mappings.
+- `lua/copilot/panel/`: suggestion preview split window.
+- `lua/copilot/auth/`: GitHub authentication.
+- `lua/copilot/nes/`: experimental Next Edit Suggestion support.
+
+## Usage
+
+Initialize the plugin in `init.lua`:
+
+```lua
+require("copilot").setup({
+  suggestion = { enabled = true },
+  panel = { enabled = true },
+})
+```
+
+Commands:
+
+- `:Copilot auth`: start authentication.
+- `:Copilot panel`: open the suggestions panel.
+- `:Copilot suggestion`: manage ghost text suggestions.
+- `:Copilot status`: inspect Copilot status.
+
+## Quality
+
+Commands:
+
+- `make test`: run all tests.
+- `make test_file FILE=tests/test_suggestion.lua`: run one test file.
+- `luacheck lua/ --globals vim`: lint `Lua`.
+- `stylua --check lua/ --config-path=.stylua.toml`: check formatting.
+
+Testing notes:
+
+- Tests use `mini.test` under `tests/`.
+- `tests/scripts/minimal_init.lua` provides a clean headless setup.
+- `tests/stubs/` contains Node.js and language server stubs.
+
+## Conventions
+
+- Follow `.stylua.toml`: 2-space indentation, 120-character line width,
+  double quotes.
+- Keep feature modules under `lua/copilot/`.
+- Prefer standard Neovim language server protocol interfaces.
+- Use `lua/copilot/logger/` for logging; configure levels through
+  `setup`.
+- Use concise Conventional Commit prefixes: `feat:`, `fix:`,
+  `refactor:`, `docs:`.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..43c994c2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/lua/copilot/keymaps/init.lua b/lua/copilot/keymaps/init.lua
index e2cba9ef..e4eeeddd 100644
--- a/lua/copilot/keymaps/init.lua
+++ b/lua/copilot/keymaps/init.lua
@@ -60,27 +60,24 @@ function M.register_keymap_with_passthrough(mode, key, action, desc)
   end
 
   vim.keymap.set(mode, key, function()
-    logger.trace("Keymap triggered for " .. keymap_key)
-
     if action() then
-      logger.trace("Action handled the keymap for " .. keymap_key)
       return "<Ignore>"
     else
       local prev = previous_keymaps[keymap_key]
 
       if prev then
         if prev.type == "rhs" then
-          logger.trace("Passing through to previous keymap for " .. keymap_key .. ": " .. prev.value)
           vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes(prev.value, true, false, true), mode, true)
         elseif prev.type == "callback" then
-          logger.trace("Passing through to previous keymap callback for " .. keymap_key)
           prev.value()
         end
-        return "<Ignore>"
       end
-      logger.trace("No previous keymap to pass through for " .. keymap_key)
 
-      return key
+      if mode == "i" and string.lower(key) == "<esc>" then
+        vim.cmd.stopinsert()
+      end
+
+      return "<Ignore>"
     end
   end, {
     desc = desc,