update local and mpv plugins, add file cmdlet, update docs

SYS/cmdlet_catalog.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from importlib import import_module, reload as reload_module
+from pathlib import Path
 from types import ModuleType
 from typing import Any, Dict, List, Optional
 import logging
@@ -71,17 +72,76 @@ def _normalize_mod_name(mod_name: str) -> str:
     return normalized
 
 
+def _nested_cmdlet_modules(normalized: str) -> List[str]:
+    """Return nested cmdlet module candidates for names like search_file."""
+    if not normalized:
+        return []
+
+    try:
+        cmdlet_dir = Path(__file__).resolve().parent.parent / "cmdlet"
+    except Exception:
+        return []
+
+    if not cmdlet_dir.is_dir():
+        return []
+
+    candidates: List[str] = []
+    seen: set[str] = set()
+    parts = normalized.split("_", 1)
+
+    try:
+        children = sorted(cmdlet_dir.iterdir(), key=lambda path: path.name.lower())
+    except Exception:
+        return []
+
+    for child in children:
+        if not child.is_dir() or not (child / "__init__.py").is_file():
+            continue
+
+        direct_file = child / f"{normalized}.py"
+        if direct_file.is_file():
+            module_name = f"cmdlet.{child.name}.{normalized}"
+            if module_name not in seen:
+                seen.add(module_name)
+                candidates.append(module_name)
+
+        if len(parts) != 2:
+            continue
+
+        left, right = parts
+        if child.name == right and (child / f"{left}.py").is_file():
+            module_name = f"cmdlet.{right}.{left}"
+            if module_name not in seen:
+                seen.add(module_name)
+                candidates.append(module_name)
+
+        if child.name == left and (child / f"{right}.py").is_file():
+            module_name = f"cmdlet.{left}.{right}"
+            if module_name not in seen:
+                seen.add(module_name)
+                candidates.append(module_name)
+
+    return candidates
+
+
 def import_cmd_module(mod_name: str, *, reload_loaded: bool = False):
     """Import a cmdlet/command module from legacy or plugin-owned packages."""
     normalized = _normalize_mod_name(mod_name)
     if not normalized:
         return None
-    for qualified in (
+    qualified_names = [
         f"plugins.{normalized}.commands",
         f"cmdnat.{normalized}",
         f"cmdlet.{normalized}",
+        *_nested_cmdlet_modules(normalized),
         normalized,
-    ):
+    ]
+
+    seen: set[str] = set()
+    for qualified in qualified_names:
+        if qualified in seen:
+            continue
+        seen.add(qualified)
         try:
             # When attempting a bare import (package is None), prefer the repo-local
             # `MPV` package for the `mpv` module name so we don't accidentally