diff --git a/docs/PLUGIN_DEVELOPMENT.md b/docs/PLUGIN_DEVELOPMENT.md
index 604a827..b2d0c3c 100644
--- a/docs/PLUGIN_DEVELOPMENT.md
+++ b/docs/PLUGIN_DEVELOPMENT.md
@@ -115,7 +115,7 @@ id = "my-lua-plugin"
 name = "My Lua Plugin"
 version = "0.1.0"
 description = "A custom Lua plugin"
-entry_point = "init.lua"
+entry = "main.lua"
 
 [[providers]]
 id = "myluaprovider"
@@ -126,23 +126,27 @@ type = "static"
 type_id = "mylua"
 ```
 
-Create `~/.config/owlry/plugins/my-lua-plugin/init.lua`:
+Create `~/.config/owlry/plugins/my-lua-plugin/main.lua`:
 ```lua
-local owlry = require("owlry")
-
--- Called once at startup for static providers
-function refresh()
-    return {
-        owlry.item("item-1", "Hello from Lua", "echo 'Hello Lua!'")
-            :description("A Lua greeting")
-            :icon("face-smile"),
-    }
-end
-
--- Called per-keystroke for dynamic providers
-function query(q)
-    return {}
-end
+-- owlry table is pre-registered globally (no require needed)
+owlry.provider.register({
+    name = "myluaprovider",
+    display_name = "My Lua Provider",
+    type_id = "mylua",
+    default_icon = "application-x-executable",
+    prefix = ":mylua",
+    refresh = function()
+        return {
+            {
+                id = "item-1",
+                name = "Hello from Lua",
+                command = "echo 'Hello Lua!'",
+                description = "A Lua greeting",
+                icon = "face-smile",
+            },
+        }
+    end,
+})
 ```
 
 ---
@@ -330,8 +334,8 @@ id = "my-plugin"
 name = "My Plugin"
 version = "1.0.0"
 description = "Plugin description"
-entry_point = "init.lua"
-owlry_version = ">=0.4.0"  # Optional version constraint
+entry = "main.lua"           # Canonical field; entry_point is accepted as an alias
+owlry_version = ">=1.0.0"   # Optional version constraint
 
 [permissions]
 fs = ["read"]       # File system access
@@ -350,14 +354,10 @@ type_id = "shortid"
 ### Lua API
 
 ```lua
-local owlry = require("owlry")
+-- owlry table is pre-registered globally (no require needed)
 
--- Create items
-local item = owlry.item(id, name, command)
-    :description("Description")
-    :icon("icon-name")
-    :terminal(false)
-    :keywords({"tag1", "tag2"})
+-- Items are plain Lua tables returned from refresh/query callbacks:
+-- { id = "...", name = "...", command = "...", description = "...", icon = "...", terminal = false, tags = {"...", "..."} }
 
 -- Notifications
 owlry.notify("Title", "Body")
@@ -388,24 +388,31 @@ local value = owlry.cache.get("key")
 ### Provider Functions
 
 ```lua
--- Static provider: called once at startup
-function refresh()
-    return {
-        owlry.item("id1", "Item 1", "command1"),
-        owlry.item("id2", "Item 2", "command2"),
-    }
-end
+-- Static provider: called once at startup and on reload
+owlry.provider.register({
+    name = "my-provider",
+    display_name = "My Provider",
+    prefix = ":my",
+    refresh = function()
+        return {
+            { id = "id1", name = "Item 1", command = "command1" },
+            { id = "id2", name = "Item 2", command = "command2" },
+        }
+    end,
+})
 
 -- Dynamic provider: called on each keystroke
-function query(q)
-    if q == "" then
-        return {}
-    end
-
-    return {
-        owlry.item("result", "Result for: " .. q, "echo " .. q),
-    }
-end
+owlry.provider.register({
+    name = "my-search",
+    display_name = "My Search",
+    prefix = "?my",
+    query = function(q)
+        if q == "" then return {} end
+        return {
+            { id = "result", name = "Result for: " .. q, command = "echo " .. q },
+        }
+    end,
+})
 ```
 
 ---
@@ -421,7 +428,7 @@ Rune plugins use a Rust-like syntax with memory safety.
 id = "my-rune-plugin"
 name = "My Rune Plugin"
 version = "1.0.0"
-entry_point = "main.rn"
+entry = "main.rn"
 
 [[providers]]
 id = "runeprovider"
@@ -524,6 +531,29 @@ RUST_LOG=debug owlry
 
 ---
 
+## Hot Reload
+
+User plugins in `~/.config/owlry/plugins/` are automatically reloaded when files change.
+The daemon watches the plugins directory and reloads all script runtimes when any file
+is created, modified, or deleted. No daemon restart is needed.
+
+**What triggers a reload:**
+- Creating a new plugin directory with `plugin.toml`
+- Editing a plugin's script files (`main.lua`, `main.rn`, etc.)
+- Editing a plugin's `plugin.toml`
+- Deleting a plugin directory
+
+**What does NOT trigger a reload:**
+- Changes to native plugins (`.so` files) — these require a daemon restart
+- Changes to runtime libraries in `/usr/lib/owlry/runtimes/` — daemon restart needed
+
+**Reload behavior:**
+- All script runtimes (Lua, Rune) are fully reloaded
+- Existing search results may briefly show stale data during reload
+- Errors in plugins are logged but don't affect other plugins
+
+---
+
 ## Publishing to AUR
 
 ### PKGBUILD Template