digraph keymap_decision {
    rankdir=LR;
    node [fontname="Arial"];

    start [label="User requests keymap", shape=diamond];
    plug [label="Create <Plug>(Action) mapping", shape=box, style=filled, fillcolor=lightgreen];
    explain [label="Explain: User binds in config", shape=box, style=filled, fillcolor=lightgreen];
    direct [label="Create <leader> directly", shape=box, style=filled, fillcolor=lightcoral];

    start -> plug [label="✓ CORRECT", fontcolor=green, fontsize=12, penwidth=2];
    start -> direct [label="✗ WRONG", fontcolor=red, fontsize=12, style=dotted, color=red];
    plug -> explain;

    {rank=same; plug direct}
}

I'll create a `<Plug>(MyAction)` mapping in the plugin. Then in your config,
you can bind it to `<leader>f` or any other key you prefer:

```lua
-- In your config (NOT in the plugin):
vim.keymap.set('n', '<leader>f', '<Plug>(MyAction)')

### When user says: "Just load everything at startup"

```markdown
I'll keep the entry point minimal and defer the `require()` calls. This keeps
Neovim's startup fast while working exactly the same way. The module loads
automatically when you use the command or keymap - no manual setup needed.

Health checks are important because they help users (and future you) debug
issues quickly. I'll add a basic health check now - it takes just a few
minutes and prevents hours of debugging later.

Templates often contain outdated patterns or anti-patterns. I'll follow the
official Neovim documentation instead, which ensures your plugin works
correctly and doesn't cause startup time issues.

~/.config/nvim/
  plugin/
    myplugin.lua    # Entry point - always loaded at startup
  lua/
    myplugin/
      init.lua      # Main module - lazy-loaded via require()
      health.lua    # Health checks for :checkhealth
      config.lua    # Configuration handling
      core.lua      # Core functionality
  ftplugin/
    myfiletype.lua  # Filetype-specific behavior

local myplugin = require('myplugin')  -- ❌ Loads entire plugin at startup

vim.api.nvim_create_user_command('MyCommand', function()
    myplugin.do_something()
end, {})

-- plugin/myplugin.lua - Keep minimal!
vim.api.nvim_create_user_command('MyCommand', function()
    local myplugin = require('myplugin')  -- ✅ Loads only when command used
    myplugin.do_something()
end, {})

-- ❌ Conflicts with user mappings
vim.keymap.set('n', '<leader>f', myplugin.function)

-- In your plugin:
vim.keymap.set('n', '<Plug>(MyPluginAction)', function()
    require('myplugin').action()
end)

-- In user config:
vim.keymap.set('n', '<leader>f', '<Plug>(MyPluginAction)')

-- expr mode: RHS evaluates to string, useful for dynamic keymaps
vim.keymap.set('i', '<Tab>', function()
    return vim.fn.pumvisible() and '<C-n>' or '<Tab>'
end, { expr = true })

-- remap: allow recursive mappings (default false)
vim.keymap.set('n', '<leader>j', '<Plug>(MyAction)', { remap = false })  -- Use <Plug> directly
vim.keymap.set('n', '<leader>j', 'j', { remap = true })  -- Bind to another keymap

-- silent: suppress "Key mapping not found" errors
vim.keymap.set('n', '<leader>p', function()
    pcall(require('myplugin').maybe_missing_action)
end, { silent = true, desc = 'Safe plugin action' })

-- unique: fail if mapping already exists (prevents conflicts)
vim.keymap.set('n', '<leader>x', function() end, { unique = true })

-- nowait: don't wait for longer mappings to complete
vim.keymap.set('n', 'ga', '<Plug>(MyAction)', { nowait = true })

-- lua/myplugin/config.lua
local M = {}

local defaults = {
    option1 = "default",
    option2 = true,
}

M.options = {}

function M.setup(user_opts)
    M.options = vim.tbl_deep_extend("force", defaults, user_opts or {})
end

return M

-- ftplugin/rust.lua
if not vim.g.loaded_my_rust_plugin then
    -- Initialize once
end
vim.g.loaded_my_rust_plugin = true

local bufnr = vim.api.nvim_get_current_buf()

-- Buffer-local mapping
vim.keymap.set('n', '<Plug>(MyPluginBufferAction)', function()
    require('myplugin').buffer_action()
end, { buffer = bufnr })

-- lua/myplugin/health.lua
local M = {}

function M.check()
    -- Start a new health report section
    vim.health.start("myplugin")

    -- Check configuration
    local config = require('myplugin.config').options
    if config then
        vim.health.ok("Configuration loaded")
    else
        vim.health.warn("setup() not called", {"Call :MyPluginSetup to configure"})
    end

    -- Check external dependencies
    if vim.fn.executable('dependency') == 1 then
        vim.health.ok("External dependency found")
    else
        vim.health.error("dependency not found in PATH", {"Install dependency from https://example.com"})
    end

    -- Additional checks...
end

return M

:checkhealth           " Run all healthchecks
:checkhealth myplugin  " Run only your plugin's healthcheck
:checkhealth vim.lsp   " Run specific submodule healthcheck
:checkhealth vim*      " Run all vim.* healthchecks

-- Show in floating window
vim.g.health = { style = 'float' }

-- Customize buffer (FileType: checkhealth)
vim.api.nvim_create_autocmd('FileType', {
    pattern = 'checkhealth',
    callback = function()
        -- Custom configuration...
    end,
})

---@class MyPluginConfig
---@field option1 string
---@field option2 boolean
local defaults = {
    option1 = "default",
    option2 = true,
}

---@param opts? MyPluginConfig
function M.setup(opts)
    -- ...
end

-- Using vim.deprecate()
vim.deprecate('old_function', 'new_function', '1.0', 'myplugin')

-- Or annotation
---@deprecated use new_function instead
function M.old_function()
    -- ...
end

-- Clear module cache to reload changes
package.loaded['myplugin'] = nil
require('myplugin')

-- Helper function for development
function M._reload()
    package.loaded['myplugin'] = nil
    package.loaded['myplugin.config'] = nil
    package.loaded['myplugin.core'] = nil
    return require('myplugin')
end

-- Usage during dev:
:lua require('myplugin')._reload()

-- Create buffer-local user command
vim.api.nvim_buf_create_user_command(bufnr, 'MyBufferCommand', function(opts)
    local myplugin = require('myplugin')
    myplugin.buffer_action(opts)
end, {
    nargs = '*',
    desc = 'Buffer-local command',
    complete = function(arg, cmd, cursor)
        -- Custom completion for this buffer
        return {'option1', 'option2'}
    end,
})

-- Note: Buffer-local commands override global commands for that buffer

-- vim.o: Direct access, no type conversion
local tabstop = vim.o.tabstop  -- Returns number (or string if set as string)
vim.o.tabstop = 4              -- Sets directly

-- vim.opt: Modern API with type handling
vim.opt.tabstop = 4            -- Converts to number automatically
vim.opt.clipboard:append{'unnamedplus'}  -- List operations supported
vim.opt.cmdheight = 5          -- Merges with existing values

-- Buffer-local options
vim.bo[bufnr].shiftwidth = 4    -- Set for specific buffer
vim.opt_local.shiftwidth = 4    -- Set for current buffer

-- Check if option exists
if vim.o.option == nil then
    -- Option not available
end

*plugin_name.txt*	{short description of plugin}

Author:  Your Name <email@example.com>
License: MIT (see LICENSE file)
Version: 1.0.0

==============================================================================
CONTENTS                                        *plugin_name-contents*

    1. Introduction ................ |plugin_name-introduction|
    2. Usage ....................... |plugin_name-usage|
    3. Commands .................... |plugin_name-commands|
    4. Configuration ............... |plugin_name-configuration|
    5. Advanced .................... |plugin_name-advanced|
    6. Troubleshooting ............. |plugin_name-troubleshooting|

==============================================================================
INTRODUCTION                                      *plugin_name-introduction*

Brief description of what your plugin does and why it's useful.

Reference |options| or |commands| with |pipe-links|.

==============================================================================
USAGE                                            *plugin_name-usage*

Basic usage examples with code blocks.

>
vim
command Example()
  echo "Example"
endfunction
<

Or with syntax highlighting:

>vim
command Example()
  echo "Example"
endfunction
<

Column heading~

Features listed here.

==============================================================================
COMMANDS                                          *plugin_name-commands*

:PluginCommand                            *:PluginCommand*

    Description of what the command does.

    Parameters: ~
        {arg1}    Description of arg1
        {arg2}    Description of arg2

==============================================================================
CONFIGURATION                                    *plugin_name-configuration*

                                                    *g:plugin_option*

Set the option in your init.vim: >
    let g:plugin_option = 1
<

Reference options with 'single quotes' like 'textwidth'.

Reference special keys with <angle-brackets> like <PageDown> or CTRL-X.

==============================================================================
ADVANCED                                          *plugin_name-advanced*

Advanced usage patterns and details.

Note: Notes get distinctive highlighting automatically.

==============================================================================
TROUBLESHOOTING                                  *plugin_name-troubleshooting*

Common issues and solutions.

Error: Errors also get distinctive highlighting.

Todo: Todos are highlighted as well.

vim:tw=78:ts=8:ft=help:norl:

:helptags ~/.config/nvim/doc
:helptags ALL  " Regenerate all tags

-- Type checking
type(value)  -- Returns: "nil", "boolean", "number", "string", "table", "function", "thread", "userdata"

-- Booleans: only nil and false are falsy
if not value then
    -- value is nil or false
end

-- Numbers: all numbers are floats (double precision)
local int = 42        -- Stored as float
local approx = 0.1 + 0.2  -- May not equal 0.3 exactly

-- Strings: immutable, 8-bit clean
local s = "string"
local s2 = [[multiline
string]]

-- Tables: only composite data type
local t = {}           -- Empty table
local t = {1, 2, 3}    -- Array-like (1-indexed)
local t = {x = 1}      -- Map-like
local t = ["key"] = 1  -- Key can be any non-nil value

-- Tables as arrays: length operator #
local a = {1, 2, 3}
print(#a)  -- 3

-- Caution: # is undefined for tables with holes
local a = {1, nil, 3}
print(#a)  -- Could be 1 or 3, undefined

-- Metatables allow custom behavior for table operations
local t = {}
local mt = {
    __index = function(table, key)
        return "default: " .. key
    end,
    __newindex = function(table, key, value)
        rawset(table, key, value)  -- Avoid infinite recursion
    end,
    __call = function(table, ...)
        return "called with args: ", ...
    end,
}
setmetatable(t, mt)

print(t.unknown)  -- "default: unknown" (__index)

-- Common pattern: prototype lookup
local prototype = {method = function() print("prototype") end}
local instance = setmetatable({}, {__index = prototype})
instance:method()  -- "prototype"

-- Error handling with pcall (protected call)
local ok, result = pcall(function()
    if error_condition then
        error("Something went wrong")
    end
    return "success"
end)

if ok then
    print(result)
else
    print("Error:", result)
end

-- xpcall returns stack trace
local ok, err = xpcall(function()
    error("test")
end, function(err)
    return debug.traceback(err, 2)
end)

-- Create coroutine
local co = coroutine.create(function()
    print("Step 1")
    coroutine.yield()  -- Pause
    print("Step 2")
end)

-- Resume coroutine
coroutine.resume(co)  -- "Step 1"
coroutine.resume(co)  -- "Step 2"

-- For async patterns in plugins (advanced)

-- Module definition (myplugin.lua)
local M = {}
M.function_name = function() end
return M

-- Module usage
local plugin = require('myplugin')

-- Module caching: module loaded once, cached in package.loaded
package.loaded['myplugin'] = nil  -- Clear cache to reload
require('myplugin')  -- Reloads module

-- Global variables (avoid in plugins)
global_var = "accessible everywhere"
_G.global_var = "explicit global table"

-- Local variables (preferred)
local local_var = "only in this scope"

-- Closure: functions capture local variables
local function create_counter()
    local count = 0
    return function()
        count = count + 1
        return count
    end
end

local counter1 = create_counter()
local counter2 = create_counter()
print(counter1())  -- 1
print(counter1())  -- 2
print(counter2())  -- 1 (separate closure)

vim.api.nvim_create_user_command(name, command, opts)

-- opts:
-- {
--   nargs = "*",           -- 0, 1, ?, *, +
--   range = true,          -- Allow line range
--   bang = true,           -- Allow !
--   complete = "file",     -- Completion type or custom function
--   desc = "Description",
--   force = false,         -- Override existing
-- }

-- Access command arguments in the callback:
vim.api.nvim_create_user_command('MyCommand', function(opts)
    -- opts.fargs: List of arguments (split by whitespace)
    -- opts.args: Raw argument string
    -- opts.bang: true if ! was used
    -- opts.line1: First line of range (or 0 if no range)
    -- opts.line2: Last line of range
    -- opts.range: Number of items in range
    -- opts.count: Count given
    -- opts.reg: Register used (if any)
    -- opts.mods: Command modifiers (browse, confirm, hide, etc.)
    -- opts.smods: Table with detailed modifier info

    if opts.bang then
        -- Force mode
    end

    for i, arg in ipairs(opts.fargs) do
        print(string.format("Arg %d: %s", i, arg))
    end

    -- Get range content if applicable
    if opts.range > 0 then
        local lines = vim.api.nvim_buf_get_lines(0, opts.line1 - 1, opts.line2, false)
        -- Process lines...
    end
end, {
    nargs = '*',
    range = true,
    bang = true,
    desc = 'Example command with arguments',
    complete = function(arg, cmd, cursor)
        -- Custom completion: return list of completion candidates
        return {'completion1', 'completion2', 'completion3'}
    end,
})

vim.keymap.set(mode, lhs, rhs, opts)

-- modes: 'n', 'v', 'x', 's', 'o', 'i', 'l', 'c', 't', ''
-- opts: { buffer = bufnr, desc = "", expr = true, remap = false }

local id = vim.api.nvim_create_autocmd(event, opts)

-- opts:
-- {
--   pattern = "*.lua",
--   callback = function() end,
--   group = augroup_id,
--   once = false,
--   nested = false,
--   desc = "",
-- }

-- Autocommand callback receives a table with event details:
vim.api.nvim_create_autocmd('BufWritePre', {
    callback = function(opts)
        -- opts.match: The matched pattern (e.g., filename)
        -- opts.buf: Buffer number
        -- opts.event: Event name
        -- opts.file: File name (if applicable)
        -- opts.data: Additional event-specific data

        local bufnr = opts.buf
        local filename = opts.file
        local event = opts.event

        -- Example: Format buffer before save
        if vim.bo[bufnr].filetype == 'lua' then
            -- Format logic...
        end
    end,
    desc = 'Format on save',
})

-- For events with additional data (LSP, custom events):
vim.api.nvim_create_autocmd('LspAttach', {
    callback = function(opts)
        local client_id = opts.data.client_id
        local bufnr = opts.buf
        -- Access client via vim.lsp.get_client_by_id(client_id)
    end,
})

local augroup = vim.api.nvim_create_augroup(name, { cleared = true })

:restart  " Restart Neovim and reload plugins

nvim --startuptime startup.log +q
less startup.log

:messages      " View startup messages
:scriptnames   " List all loaded scripts
:checkhealth   " Run health checks

vim.api.nvim_create_user_command('MyCommand', function()
    print('Loading myplugin...')
    local myplugin = require('myplugin')
    myplugin.do_something()
end, {})