feat: add AGENTS.md and improve config validation with diff cleanup enhancements

Change-Id: Id68772addfdfaa614de2f9c7896257f6b7234868
Signed-off-by: Thomas Kosiewski <tk@coder.com>

Author: ThomasK33

AGENTS.md

@@ -0,0 +1,46 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `lua/claudecode/`: Core plugin modules (`init.lua`, `config.lua`, `diff.lua`, `terminal/`, `server/`, `tools/`, `logger.lua`, etc.).
+- `plugin/`: Lightweight loader that guards startup and optional auto-setup.
+- `tests/`: Busted test suite (`unit/`, `integration/`, `helpers/`, `mocks/`).
+- `fixtures/`: Minimal Neovim configs for manual and integration testing.
+- `scripts/`: Development helpers; `dev-config.lua` aids local testing.
+
+## Build, Test, and Development Commands
+
+- `make check`: Syntax checks + `luacheck` on `lua/` and `tests/`.
+- `make format`: Format with StyLua (via Nix `nix fmt` in this repo).
+- `make test`: Run Busted tests with coverage (outputs `luacov.stats.out`).
+- `make clean`: Remove coverage artifacts.
+  Examples:
+- Run all tests: `make test`
+- Run one file: `busted -v tests/unit/terminal_spec.lua`
+
+## Coding Style & Naming Conventions
+
+- Lua: 2‑space indent, 120‑column width, double quotes preferred.
+- Formatting: StyLua configured in `.stylua.toml` (require-sort enabled).
+- Linting: `luacheck` with settings in `.luacheckrc` (uses `luajit+busted` std).
+- Modules/files: lower_snake_case; return a module table `M` with documented functions (EmmyLua annotations encouraged).
+- Avoid one-letter names; prefer explicit, testable functions.
+
+## Testing Guidelines
+
+- Frameworks: Busted + Luassert; Plenary used where Neovim APIs are needed.
+- File naming: `*_spec.lua` or `*_test.lua` under `tests/unit` or `tests/integration`.
+- Mocks/helpers: place in `tests/mocks` and `tests/helpers`; prefer pure‑Lua mocks.
+- Coverage: keep high signal; exercise server, tools, diff, and terminal paths.
+- Quick tip: prefer `make test` (it sets `LUA_PATH` and coverage flags).
+
+## Commit & Pull Request Guidelines
+
+- Commits: Use Conventional Commits (e.g., `feat:`, `fix:`, `docs:`, `test:`, `chore:`). Keep messages imperative and scoped.
+- PRs: include a clear description, linked issues, repro steps, and tests. Update docs (`README.md`, `ARCHITECTURE.md`, or `DEVELOPMENT.md`) when behavior changes.
+- Pre-flight: run `make format`, `make check`, and `make test`. Attach screenshots or terminal recordings for UX-visible changes (diff flows, terminal behavior).
+
+## Security & Configuration Tips
+
+- Do not commit secrets or local paths; prefer environment variables. The plugin honors `CLAUDE_CONFIG_DIR` for lock files.
+- Local CLI paths (e.g., `opts.terminal_cmd`) should be configured in user config, not hardcoded in repo files.

lua/claudecode/config.lua

@@ -89,7 +89,10 @@ function M.validate(config)
   assert(is_valid_log_level, "log_level must be one of: " .. table.concat(valid_log_levels, ", "))
 
   assert(type(config.track_selection) == "boolean", "track_selection must be a boolean")
-  assert(type(config.focus_after_send) == "boolean", "focus_after_send must be a boolean")
+  -- Allow absence in direct validate() calls; apply() supplies default
+  if config.focus_after_send ~= nil then
+    assert(type(config.focus_after_send) == "boolean", "focus_after_send must be a boolean")
+  end
 
   assert(
     type(config.visual_demotion_delay_ms) == "number" and config.visual_demotion_delay_ms >= 0,
@@ -131,7 +134,9 @@ function M.validate(config)
   if config.diff_opts.on_new_file_reject ~= nil then
     assert(
       type(config.diff_opts.on_new_file_reject) == "string"
-        and (config.diff_opts.on_new_file_reject == "keep_empty" or config.diff_opts.on_new_file_reject == "close_window"),
+        and (
+          config.diff_opts.on_new_file_reject == "keep_empty" or config.diff_opts.on_new_file_reject == "close_window"
+        ),
       "diff_opts.on_new_file_reject must be 'keep_empty' or 'close_window'"
     )
   end

lua/claudecode/diff.lua

@@ -814,11 +814,20 @@ function M._resolve_diff_as_rejected(tab_name)
   diff_data.status = "rejected"
   diff_data.result_content = result
 
-  -- Do not perform UI cleanup here; wait for explicit close_tab tool call.
   -- Resume the coroutine with the result (for deferred response system)
   if diff_data.resolution_callback then
     diff_data.resolution_callback(result)
   end
+
+  -- For new-file diffs in the current tab, when configured to keep the empty placeholder,
+  -- we eagerly clean up the diff UI and state. This preserves any reused empty buffer.
+  local keep_behavior = nil
+  if config and config.diff_opts then
+    keep_behavior = config.diff_opts.on_new_file_reject
+  end
+  if diff_data.is_new_file and keep_behavior == "keep_empty" and not diff_data.created_new_tab then
+    M._cleanup_diff_state(tab_name, "diff rejected (keep_empty)")
+  end
 end
 
 ---Register autocmds for a specific diff
@@ -930,14 +939,19 @@ function M._create_diff_view_from_window(
     original_window = choice.original_win
   end
 
-  -- For new files, we create an empty buffer for the original side
-  if is_new_file then
-    original_buffer_created_by_plugin = true
+  -- For new files, prefer reusing an existing empty buffer in the chosen window
+  local original_buffer
+  if is_new_file and choice.reused_buf and vim.api.nvim_buf_is_valid(choice.reused_buf) then
+    original_buffer = choice.reused_buf
+    original_buffer_created_by_plugin = false
+  else
+    if is_new_file then
+      original_buffer_created_by_plugin = true
+    end
+    -- Load the original-side buffer into the chosen window
+    original_buffer = load_original_buffer(original_window, old_file_path, is_new_file, existing_buffer)
   end
 
-  -- Load the original-side buffer into the chosen window
-  local original_buffer = load_original_buffer(original_window, old_file_path, is_new_file, existing_buffer)
-
   -- Set up the proposed buffer and finalize the diff layout
   local new_win = setup_new_buffer(
     original_window,