explain that `vim.api.nvim_set_keymap(mode, ..)` is first char of `:lua print(vim.api.nvim_get_mode().mode)` and hint that there is a minor mode

[matu3ba]

Assume the following snippet be in the init.lua

local opts = { noremap = true, silent = true }
local map = vim.api.nvim_set_keymap
map('nt', '<C-x>j', [[<cmd> lua print("not broken!")<CR>]], opts)
-- prints either nt or n
local add_cmd = vim.api.nvim_create_user_command
add_cmd('Printmode', function() print(vim.api.nvim_get_mode().mode) end, {})

This fails with E5113: Error while calling lua chunk: $USER/.config/nvim/lua/my_keymaps.lua:534: Shortname is too long: nt,
even though nvim_get_mode() provides us with a mode nt.
I would expect that there is somewhere a lua function for the "visual mode in the terminal" such that one can do keybindings there, if there is an api function that tells us we are in a different mode.

see below: "mapping mode is just the first char of nvim_get_mode().mode" info is missing

[matu3ba]

state.c tells us that there is a major and minor mode, but there is also no doc about nvim_get_mode.
Since the docs have entries on normal insertion mode, this looks like neovim core forgot about normal terminal mode.
The test in vim_spec.lua also does not cover all major + minor modes.

And finally, it sounds like a good idea to tell users that there is something like a minor mode and they can not use keybindings to the minor mode.

"mapping mode is just the first char of nvim_get_mode().mode"

UPDATE: removed unrelevant things and added last sentence.

[bfredl]

well, the docs of nvim_set_keymap() does state that a single-letter mode should be used, like "n", "i", "v", "x", "!" or an empty string. The error message could be made more friendly than "shortname is too long" though.