feat(codex): rename CodexAdd to CodexMentionFile, add CodexMentionDirectory (#9)

Rename `M.add_file` → `M.mention_file` and `:CodexAdd` → `:CodexMentionFile`
to better reflect the `/mention` payload. Add `M.mention_directory` and
`:CodexMentionDirectory` for mentioning directories. Reassign `<leader>om` to
mention_file, add `<leader>oM` for mention_dir, and remove the default model
keymap.

Reviewed-on: https://codeberg.org/yaadata/codex.nvim/pulls/9
Co-authored-by: Yadi Abdalhalim <abdalhalim.yaadata@gmail.com>
Co-committed-by: Yadi Abdalhalim <abdalhalim.yaadata@gmail.com>

Author: yaadata

README.md

@@ -80,9 +80,9 @@ require("codex").setup({
     focus = "<leader>of",
     close = "<leader>ox",
     send = "<leader>os",
-    add = "<leader>oa",
+    mention_file = "<leader>om",
+    mention_dir = "<leader>oM",
     resume = "<leader>or",
-    model = "<leader>om",
     status = "<leader>oi",
     permissions = "<leader>op",
     compact = "<leader>oc",
@@ -101,7 +101,8 @@ require("codex").setup({
 - `:CodexClose` closes the active Codex terminal session
 - `:CodexClearInput` clears the active Codex terminal input line
 - `:CodexSend` sends selected lines with path and range context.
-- `:CodexAdd [path]` sends `/mention` for a path (or current buffer path).
+- `:CodexMentionFile [path]` sends `/mention` for a file (or current buffer path).
+- `:CodexMentionDirectory [path]` sends `/mention` for a directory (or current buffer's directory).
 - `:CodexResume[!]` resumes in-process or launches `codex resume` (`!` uses
   `--last` when launching).
 - `:CodexModel` sends `/model`
@@ -126,9 +127,9 @@ require("codex").setup({
     focus = "<leader>of",
     close = "<leader>ox",
     send = "<leader>os",
-    add = "<leader>oa",
+    mention_file = "<leader>om",
+    mention_dir = "<leader>oM",
     resume = "<leader>or",
-    model = "<leader>om",
     status = "<leader>oi",
     permissions = "<leader>op",
     compact = "<leader>oc",
@@ -210,7 +211,8 @@ navigation keymaps, or set individual directions to `false`.
 - `require("codex").show_diff()` send `/diff`.
 - `require("codex").resume(opts)` resume (`opts.last` supports `--last`).
 - `require("codex").send_selection(opts)` send visual/range selection.
-- `require("codex").add_file(path)` send `/mention` for a file path.
+- `require("codex").mention_file(path)` send `/mention` for a file path.
+- `require("codex").mention_directory(path)` send `/mention` for a directory path.
 - `require("codex").is_running()` check whether active session is alive.
 - `require("codex").get_config()` return resolved config snapshot.
 

docs/architecture.md

@@ -41,7 +41,7 @@ codex.nvim/
 │                                    # prevents double-loading via vim.g.loaded_codex.
 ├── lua/codex/
 │   ├── init.lua                     # Public API surface (setup, open, close, toggle,
-│   │                                # send, send_selection, add_file, resume, etc.).
+│   │                                # send, send_selection, mention_file, mention_directory, resume, etc.).
 │   │                                # Owns the DI container and session lifecycle.
 │   ├── config.lua                   # Default config table, vim.validate-based
 │   │                                # validation, and deep-merge with user options.
@@ -202,7 +202,7 @@ failures downstream.
 ### Auto-Open
 
 APIs that need an active session (`send`, `send_command`, `focus`,
-`send_selection`, `add_file`) automatically open one when needed. The
+`send_selection`, `mention_file`, `mention_directory`) automatically open one when needed. The
 lower-level `send` API opens without focus, while command-facing flows
 (`:CodexSend`, `:CodexAdd`) ensure the terminal is opened with focus before
 payload dispatch. If the provider handle is not yet ready, payloads are queued

docs/command-interactions.md

@@ -8,23 +8,24 @@ then into provider/session/runtime collaborators.
 
 ## Command Mapping
 
-| User Command                  | Entry Function                   | Primary Path                                          |
-| ----------------------------- | -------------------------------- | ----------------------------------------------------- |
-| `:Codex`                      | `codex.toggle()`                 | Toggle active terminal or open a focused session      |
-| `:Codex!`                     | `codex.open(true)`               | Force-open and focus terminal                         |
-| `:CodexFocus`                 | `codex.focus()`                  | Focus active session or open one                      |
-| `:CodexClose`                 | `codex.close()`                  | Close active session and reset queue                  |
-| `:CodexClearInput`            | `codex.clear_input()`            | Send `<C-c>` to active session                        |
-| `:CodexSend`                  | `codex.send_selection(opts)`     | Collect selection, format, send via queue             |
-| `:CodexAdd [path]`            | `codex.add_file(path)`           | Build `/mention` payload and submit                   |
-| `:CodexResume`                | `codex.resume({ last = false })` | In-process `/resume` or launch `codex resume`         |
-| `:CodexResume!`               | `codex.resume({ last = true })`  | Launch `codex resume --last` when opening new process |
-| `:CodexModel`                 | `codex.set_model()`              | Slash command wrapper (`/model`)                      |
-| `:CodexStatus`                | `codex.show_status()`            | Slash command wrapper (`/status`)                     |
-| `:CodexPermissions`           | `codex.show_permissions()`       | Slash command wrapper (`/permissions`)                |
-| `:CodexCompact`               | `codex.compact()`                | Slash command wrapper (`/compact`)                    |
-| `:CodexReview [instructions]` | `codex.review(instructions)`     | Slash command wrapper (`/review ...`)                 |
-| `:CodexDiff`                  | `codex.show_diff()`              | Slash command wrapper (`/diff`)                       |
+| User Command                    | Entry Function                   | Primary Path                                          |
+| ------------------------------- | -------------------------------- | ----------------------------------------------------- |
+| `:Codex`                        | `codex.toggle()`                 | Toggle active terminal or open a focused session      |
+| `:Codex!`                       | `codex.open(true)`               | Force-open and focus terminal                         |
+| `:CodexFocus`                   | `codex.focus()`                  | Focus active session or open one                      |
+| `:CodexClose`                   | `codex.close()`                  | Close active session and reset queue                  |
+| `:CodexClearInput`              | `codex.clear_input()`            | Send `<C-c>` to active session                        |
+| `:CodexSend`                    | `codex.send_selection(opts)`     | Collect selection, format, send via queue             |
+| `:CodexMentionFile [path]`      | `codex.mention_file(path)`       | Build `/mention` payload for file and submit          |
+| `:CodexMentionDirectory [path]` | `codex.mention_directory(path)`  | Build `/mention` payload for directory and submit     |
+| `:CodexResume`                  | `codex.resume({ last = false })` | In-process `/resume` or launch `codex resume`         |
+| `:CodexResume!`                 | `codex.resume({ last = true })`  | Launch `codex resume --last` when opening new process |
+| `:CodexModel`                   | `codex.set_model()`              | Slash command wrapper (`/model`)                      |
+| `:CodexStatus`                  | `codex.show_status()`            | Slash command wrapper (`/status`)                     |
+| `:CodexPermissions`             | `codex.show_permissions()`       | Slash command wrapper (`/permissions`)                |
+| `:CodexCompact`                 | `codex.compact()`                | Slash command wrapper (`/compact`)                    |
+| `:CodexReview [instructions]`   | `codex.review(instructions)`     | Slash command wrapper (`/review ...`)                 |
+| `:CodexDiff`                    | `codex.show_diff()`              | Slash command wrapper (`/diff`)                       |
 
 ## Setup Registration Flow
 
@@ -145,27 +146,28 @@ init.lua send_selection()
          \- [not ready yet] -> queue + retry loop until ready/timeout
 ```
 
-### `:CodexAdd [path]`
+### `:CodexMentionFile [path]` and `:CodexMentionDirectory [path]`
 
 ```text
-User runs :CodexAdd [path]
+User runs :CodexMentionFile [path] (or :CodexMentionDirectory [path])
     |
     v
-commands.lua -> codex.add_file(path_or_nil)
+commands.lua -> codex.mention_file(path_or_nil) (or codex.mention_directory(path_or_nil))
     |
     v
-init.lua add_file(path)
+init.lua mention_file(path) / mention_directory(path)
     |- ensure_setup()
-    |- resolve path (arg or current buffer absolute path)
-    |- [missing path] -> log + return false, "current buffer has no file path"
+    |- resolve path (arg or current buffer path via %:p / %:p:h)
+    |- [missing path] -> log + return false, "current buffer has no file/directory path"
     |- path.to_relative(...)
-    |- formatter.format_mention(relative_path)
-    |- [active + alive] provider.focus(handle) before prompt capture
-    |- capture_terminal_prompt_input() (best effort)
-    |- mention_payload = clear_line_sequence + mention_text
-    \- dispatch_send(mention_payload, { open_focus=true, pre_focus=true, command_path="/mention", on_sent=... })
-         |- on_sent: submit_with_enter_key("/mention")
-         \- on_sent: restore captured prompt input via delayed dispatch_send(...)
+    \- dispatch_mention(relative_path)
+         |- formatter.format_mention(relative_path)
+         |- [active + alive] provider.focus(handle) before prompt capture
+         |- capture_terminal_prompt_input() (best effort)
+         |- mention_payload = clear_line_sequence + mention_text
+         \- dispatch_send(mention_payload, { open_focus=true, pre_focus=true, command_path="/mention", on_sent=... })
+              |- on_sent: submit_with_enter_key("/mention")
+              \- on_sent: restore captured prompt input via delayed dispatch_send(...)
 ```
 
 ### `:CodexResume` and `:CodexResume!`

lua/codex/config.lua

@@ -53,9 +53,9 @@ M.defaults = {
     focus = "<leader>of",
     close = "<leader>ox",
     send = "<leader>os",
-    add = "<leader>oa",
+    mention_file = "<leader>om",
+    mention_dir = "<leader>oM",
     resume = "<leader>or",
-    model = "<leader>om",
     status = "<leader>oi",
     permissions = "<leader>op",
     compact = "<leader>oc",
@@ -82,17 +82,17 @@ local valid_keymap_actions = {
   focus = true,
   close = true,
   send = true,
-  add = true,
+  mention_file = true,
+  mention_dir = true,
   resume = true,
-  model = true,
   status = true,
   permissions = true,
   compact = true,
   review = true,
   diff = true,
 }
 local valid_keymap_action_list =
-  "toggle, open, focus, close, send, add, resume, model, status, permissions, compact, review, diff"
+  "toggle, open, focus, close, send, mention_file, mention_dir, resume, status, permissions, compact, review, diff"
 
 ---@param source table
 ---@param known table

lua/codex/init.lua

@@ -37,6 +37,7 @@ local state = {
 
 local process_pending_send_item
 local session_is_alive
+local dispatch_mention
 local BRACKETED_PASTE_START = "\27[200~"
 local BRACKETED_PASTE_END = "\27[201~"
 local SLASH_COMMAND_SUBMIT_SEQUENCE = "\n"
@@ -769,25 +770,12 @@ function M.send_selection(opts)
   })
 end
 
----Sends `/mention`, auto-submits it, then restores previously captured prompt input.
----@param path? string Explicit path to mention. When nil, uses current buffer path.
+---Sends `/mention` for an already-resolved relative path, auto-submits, and restores prompt input.
+---@param resolved_path string Relative path to mention.
 ---@return codex.SendResult ok True when mention payload is sent.
 ---@return string|nil err
-function M.add_file(path)
-  ensure_setup()
+dispatch_mention = function(resolved_path)
   local deps = get_deps()
-  local resolved_path = path
-  if resolved_path == nil then
-    resolved_path = deps.vim.fn.expand("%:p")
-  end
-
-  if not resolved_path or resolved_path == "" then
-    local err = "current buffer has no file path"
-    deps.logger.error("failed to add file context: %s", err)
-    return false, err
-  end
-
-  resolved_path = deps.path.to_relative(deps.vim, resolved_path)
   local mention = deps.formatter.format_mention(resolved_path)
 
   local session, provider = get_active_session_and_provider()
@@ -828,6 +816,56 @@ function M.add_file(path)
   })
 end
 
+---Sends `/mention` for a file, auto-submits it, then restores previously captured prompt input.
+---@param path? string Explicit file path to mention. When nil, uses current buffer path.
+---@return codex.SendResult ok True when mention payload is sent.
+---@return string|nil err
+function M.mention_file(path)
+  ensure_setup()
+  local deps = get_deps()
+  local resolved_path = path
+  if resolved_path == nil then
+    resolved_path = deps.vim.fn.expand("%:p")
+  end
+
+  if not resolved_path or resolved_path == "" then
+    local err = "current buffer has no file path"
+    deps.logger.error("failed to mention file: %s", err)
+    return false, err
+  end
+
+  resolved_path = deps.path.to_relative(deps.vim, resolved_path)
+  return dispatch_mention(resolved_path)
+end
+
+---Sends `/mention` for a directory, auto-submits it, then restores previously captured prompt input.
+---@param path? string Explicit directory path to mention. When nil, uses current buffer's directory.
+---@return codex.SendResult ok True when mention payload is sent.
+---@return string|nil err
+function M.mention_directory(path)
+  ensure_setup()
+  local deps = get_deps()
+  local resolved_path = path
+  if resolved_path == nil then
+    local buf_path = deps.vim.fn.expand("%:p")
+    if not buf_path or buf_path == "" then
+      local err = "current buffer has no directory path"
+      deps.logger.error("failed to mention directory: %s", err)
+      return false, err
+    end
+    resolved_path = deps.vim.fn.expand("%:p:h")
+  end
+
+  if not resolved_path or resolved_path == "" then
+    local err = "current buffer has no directory path"
+    deps.logger.error("failed to mention directory: %s", err)
+    return false, err
+  end
+
+  resolved_path = deps.path.to_relative(deps.vim, resolved_path)
+  return dispatch_mention(resolved_path)
+end
+
 ---Returns whether an active Codex session is currently alive.
 ---@return boolean
 function M.is_running()

lua/codex/nvim/commands.lua

@@ -104,19 +104,33 @@ function M.register()
   })
 
   ---@param opts codex.UserCommandOpts
-  vim.api.nvim_create_user_command("CodexAdd", function(opts)
+  vim.api.nvim_create_user_command("CodexMentionFile", function(opts)
     local codex = require("codex")
     local path = opts.args
     if path == "" then
       path = nil
     end
-    codex.add_file(path)
+    codex.mention_file(path)
   end, {
-    desc = "Add file context to Codex via /mention",
+    desc = "Mention a file in Codex via /mention",
     nargs = "?",
     complete = "file",
   })
 
+  ---@param opts codex.UserCommandOpts
+  vim.api.nvim_create_user_command("CodexMentionDirectory", function(opts)
+    local codex = require("codex")
+    local path = opts.args
+    if path == "" then
+      path = nil
+    end
+    codex.mention_directory(path)
+  end, {
+    desc = "Mention a directory in Codex via /mention",
+    nargs = "?",
+    complete = "dir",
+  })
+
   ---@param opts codex.UserCommandOpts
   vim.api.nvim_create_user_command("CodexResume", function(opts)
     local codex = require("codex")

lua/codex/nvim/keymaps.lua

@@ -81,9 +81,23 @@ function M.register(config, vim_api)
   set_mapping(vim_api, "n", maps.open, "<Cmd>Codex!<CR>", "Codex: Open and focus", force)
   set_mapping(vim_api, "n", maps.focus, "<Cmd>CodexFocus<CR>", "Codex: Focus terminal", force)
   set_mapping(vim_api, "n", maps.close, "<Cmd>CodexClose<CR>", "Codex: Close session", force)
-  set_mapping(vim_api, "n", maps.add, "<Cmd>CodexAdd<CR>", "Codex: Add current file", force)
+  set_mapping(
+    vim_api,
+    "n",
+    maps.mention_file,
+    "<Cmd>CodexMentionFile<CR>",
+    "Codex: Mention current file",
+    force
+  )
+  set_mapping(
+    vim_api,
+    "n",
+    maps.mention_dir,
+    "<Cmd>CodexMentionDirectory<CR>",
+    "Codex: Mention current directory",
+    force
+  )
   set_mapping(vim_api, "n", maps.resume, "<Cmd>CodexResume<CR>", "Codex: Resume session", force)
-  set_mapping(vim_api, "n", maps.model, "<Cmd>CodexModel<CR>", "Codex: Set model", force)
   set_mapping(vim_api, "n", maps.status, "<Cmd>CodexStatus<CR>", "Codex: Show status", force)
   set_mapping(
     vim_api,

lua/codex/types.lua

@@ -54,9 +54,9 @@
 ---@field focus string|false
 ---@field close string|false
 ---@field send string|false
----@field add string|false
+---@field mention_file string|false
+---@field mention_dir string|false
 ---@field resume string|false
----@field model string|false
 ---@field status string|false
 ---@field permissions string|false
 ---@field compact string|false