[Docs] Document lazy loading incompatibility

[sghng]

• OS: macOS Tahoe Public Beta
• Neovim Version: v0.12.0-dev-1145+g9898327bd7
• Python Version: 3.13
• Python is installed with: uv venv
• Health checks

`:checkhealth molten`

==============================================================================
molten:                                                                     ✅
molten-nvim ~
- ✅ OK NeoVim >=0.9
- ✅ OK Python >=3.10
- ✅ OK Python module pynvim found
- ✅ OK Python module jupyter-client found
- ✅ OK Python module cairosvg found
- ✅ OK Python module pnglatex found
- ✅ OK Python module plotly found
- ✅ OK Python module kaleido found
- ✅ OK Python module pyperclip found
- ✅ OK Python module nbformat found
- ✅ OK Python module pillow found

`:checkhealth provider` (the python parts)

Python 3 provider (optional) ~
- Using: g:python3_host_prog = "~/venvs/nvim/bin/python3"
- Executable: /Users/sghuang/venvs/nvim/bin/python3
- Python version: 3.13.7
- pynvim version: 0.5.2
- ✅ OK Latest pynvim is installed.
Python virtualenv ~

✅ OK no $VIRTUAL_ENV

Description

This plugins has a few unexpected behaviors when loaded through Lazy.nvim.

• All commands show up in cmd line completion, though molten-nvim is not loaded in the Lazy dashboard, i.e. Molten doesn't respect Lazy.nvim loading sequence.
• If a command is specified in the cmd field in LazySpec, that command will emit an error: E492: Not an editor command: MolteXXX (not just for the first time, it remains broken). After the command is attempted for the first time, Molten remains unloaded in the Lazy dashboard.
• User can't use require("molten").setup(opts) to load this plugin.

Reproduction Steps

My molten config is as follows:

{
  "benlubas/molten-nvim",
  build = ":UpdateRemotePlugins",
  cmd = { "MoltenInit", "MoltenInfo" }, -- comment/uncomment this line, compare what happens
  init = function()
    vim.g.molten_image_provider = "image.nvim"
    vim.g.molten_virt_text_output = true -- output always shown
  end,
},

Comment and uncomment the line specified, and see what happens when calling these two commands, and run :Lazy to examine the status of molten-nvim.

Expected Behavior

• No command completion should be available before Molten is loaded, if cmd key is not specified.
• Only the commands specified in cmd should show up in completion before Molten is loaded.
• The commands specified in cmd should function normally, i.e. first invocation will load molten, and immediately handover the command execution to Molten.
• Users should be able to use require("molten").setup(opts) to load this plugin, this is quite conventional.

[benlubas]

I'm not really sure that remote plugins can be lazy loaded...

[benlubas]

as for

Users should be able to use require("molten").setup(opts) to load this plugin, this is quite conventional

I would point you to this. https://github.com/lumen-oss/nvim-best-practices#zap-initialization

forcing a setup call is generally not desirable. Having an optional one to set options is fine. But this would amount to a function that maps a table of values to globals b/c we can't break current users.

[sghng]

as for

Users should be able to use require("molten").setup(opts) to load this plugin, this is quite conventional

I would point you to this. https://github.com/lumen-oss/nvim-best-practices#zap-initialization

forcing a setup call is generally not desirable. Having an optional one to set options is fine. But this would amount to a function that maps a table of values to globals b/c we can't break current users.

Thanks for pointing this out. What I meant is allowing users to manually setup the plugin in the config function in Lazy spec, if needed. For example, my config above would be rewritten as:

{
  ...
  opts = {
    ...
  },
  config = function(_, opts)
    -- setting up auto cmds, any prep work, logging, etc...
    require("molten-nvim").setup(opts)
  end,
  ...
}

This should be optional and is only reserved for users who know what they're doing.

[sghng]

I need to correct my description of the bug:

• If a command is specified in cmd key in LazySpec
• The first invocation of that command will work.
• The subsequent invocations will emit error "Not a command"

Since it's not likely that the plugin can be lazy loaded at all, there's probably no need to put anything into the cmd key, so this issue is probably not of importance...

[sghng]

I'm not really sure that remote plugins can be lazy loaded...

I just did more search about remote plugins and realize that it's true that this can't be lazy loaded like regular lua plugins. This behavior should be included int he docs, i.e. "there's no need and no way to lazy load this plugin".