huge refactor of the entire codebase, with the goal of improving maintainability, readability, and extensibility. This commit includes changes to almost every file in the project, including:

plugins/README.md

@@ -0,0 +1,39 @@
+# External Plugins
+
+Drop user plugins in this folder to make them available to the app without editing the built-in `Provider/` package.
+
+Supported discovery paths:
+- `plugins/` in the repo root
+- `plugins/` in the current working directory
+- Any directory listed in `MM_PLUGIN_PATH`
+- Any directory listed in `MEDEIA_PLUGIN_PATH`
+
+Plugin module rules:
+- A plugin can be a single `.py` file or a package directory with `__init__.py`.
+- Define a class that inherits from `ProviderCore.base.Provider`.
+- Give it a stable name using `PLUGIN_NAME` or the class name.
+
+Example skeleton:
+
+```python
+from ProviderCore.base import Provider, SearchResult
+
+
+class MyPlugin(Provider):
+    PLUGIN_NAME = "myplugin"
+    URL_DOMAINS = ("example.com",)
+
+    def search(self, query, limit=50, filters=None, **kwargs):
+        text = str(query or "").strip()
+        if not text:
+            return []
+        return [
+            SearchResult(
+                table="myplugin",
+                title=f"Result for {text}",
+                path=f"https://example.com/{text}",
+            )
+        ]
+```
+
+Built-in plugins still live in `Provider/`.