@kurokeita/add-skill 1.20.0 → 1.21.0

package/dist/skills/koreader-plugin-development/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: koreader-plugin-development
+description: This skill should be used when the user asks to "create a KOReader plugin", "write a koplugin", "build a KOReader patch", "userpatch", "modify KOReader behavior", "add a menu item to KOReader", "develop for KOReader", or mentions ".koplugin", "koreader/patches/", `WidgetContainer`, `UIManager`, or KOReader event handlers. Provides plugin and patch development guidance for the KOReader e-reader application (Lua, LuaJIT).
+---
+
+# KOReader Plugin and Patch Development
+
+KOReader is a document viewer for e-ink readers, written in Lua on LuaJIT. It exposes two main extension mechanisms:
+
+- **Plugins** — self-contained `.koplugin/` directories loaded by `pluginloader` from `DEFAULT_PLUGIN_PATH` or `extra_plugin_paths`. Use for new features, menu entries, or background tasks.
+- **Patches** — Lua files in `koreader/patches/` applied at startup by the `userpatch` module. Use for runtime monkey-patching of KOReader internals when a plugin is too heavy or the change must run before plugin load.
+
+Choose plugins when the change is a feature you can ship as a folder. Choose patches for surgical fixes to existing modules, behavior overrides, or hotfixes that target a specific KOReader version.
+
+## Mental Model
+
+KOReader's UI is a tree of `WidgetContainer` instances (subclasses of `EventListener`) managed by a top-level `UIManager`. Communication happens via `Event` objects with a `handler` name and `args`. `WidgetContainer:handleEvent` propagates events to children first; if no child returns `true`, the container's own `on<EventName>` method runs.
+
+Plugins are typically classes built via `WidgetContainer:extend{...}` and returned from `main.lua`; they register themselves to the UI host (`ReaderUI` or `FileManager`) via `addToMainMenu`, dispatcher actions, or by listening to events.
+
+Patches manipulate already-loaded modules (`require("apps.reader.readerui")`, `require("ui.widget.infomessage")`, etc.) to change methods, add hooks, or replace functions before or after the UI is built. Module paths must be the full namespaced form KOReader uses internally — short forms silently no-op.
+
+## Workflow
+
+### To create a plugin
+
+1. Create a directory `MyPlugin.koplugin/` containing at least:
+   - `main.lua` — module returning a `WidgetContainer`-derived class
+   - `_meta.lua` — table with `name`, `fullname`, `description`, optional `version`
+2. Place it under KOReader's `plugins/` directory (or set `extra_plugin_paths`).
+3. Implement the plugin class. Required pieces:
+   - `local MyPlugin = WidgetContainer:extend{ name = "myplugin" }` at the top of `main.lua`, with `return MyPlugin` at the bottom (return the class, not an instance — the loader instantiates it per host)
+   - `function MyPlugin:init() ... end` to wire dispatcher actions and event handlers
+   - `function MyPlugin:addToMainMenu(menu_items) ... end` if the plugin needs a menu entry
+4. Surface UI via `UIManager:show(InfoMessage:new{ text = "..." })` or custom widgets.
+5. React to events via `onEventName(self, ...)` methods. Return `true` to consume.
+6. Restart KOReader (or re-enter file manager) to pick up the plugin.
+
+See `examples/helloworld.lua` for a minimal plugin and `references/plugin-anatomy.md` for full structure rules and lifecycle.
+
+### To create a patch
+
+1. Create `koreader/patches/2-my-fix.lua` (the leading number sets priority; see priorities below).
+2. `require` the target module and replace or wrap methods on it.
+3. Keep the patch small and version-pin it via a header comment that names the KOReader version it targets — patches break across releases.
+4. Restart KOReader. Errors during patch application surface in `crash.log`.
+
+Priority is encoded in the filename prefix passed by `userpatch.applyPatches(priority)`. Common values:
+
+| Prefix | Phase | Use for |
+|--------|-------|---------|
+| `1-` | early-once (very early) | Startup-only configuration, env tweaks |
+| `2-` | early (before UI) | Patch core modules before UI builds |
+| `3-` | late (after UI) | Override running widgets, add menu items |
+
+See `references/patches.md` for monkey-patch idioms, version-guards, and pitfalls.
+
+## Common Tasks
+
+### Add a menu item
+
+Implement `addToMainMenu(self, menu_items)` in a plugin and push an entry into the proper sub-table (`menu_items.tools`, `menu_items.plugins`, etc.). The host UI calls this once when the menu is built.
+
+### Listen for an event
+
+Add `onEventName(self, arg1, arg2)` to the plugin class. Returning `true` stops further propagation; returning `nil`/`false` lets sibling widgets see the event. Common reader events include `PosUpdate`, `UpdatePos`, `PageUpdate`, `ReaderReady`, `CloseDocument`. See `references/events-and-widgets.md` for the wider catalog.
+
+### Show something to the user
+
+Quick info: `UIManager:show(InfoMessage:new{ text = _("Done") })`.
+Transient toast: `Notification:notify("Saved")`.
+Custom UI: subclass `WidgetContainer` (or use `ButtonDialog`, `InputDialog`), then `UIManager:show(self)`. Always pair with `UIManager:close(self)` when dismissing.
+
+### Run code on a schedule
+
+`UIManager:scheduleIn(seconds, function() ... end)` and `UIManager:unschedule(callback)`. For repeating background work, prefer subclassing `BackgroundTaskPlugin` (`ui.plugin.background_task_plugin`).
+
+### Persist plugin state
+
+Use `LuaSettings` (`require("luasettings")`) backed by a file under `DataStorage:getSettingsDir()`. For document-scoped state, write to `self.ui.doc_settings` so it follows the document.
+
+## Debugging
+
+- Enable debug mode (`./kodev run --debug` in dev, or `Settings -> Developer options -> Enable debug logging` on device) to get stack traces for event handlers and `logger.dbg(...)` output.
+- `logger.dbg("label", value)` prints to stdout and to `koreader/crash.log`. Lua arguments evaluate eagerly — guard heavy expressions with `if dbg.is_on then ... end`.
+- Read `crash.log` first when something fails silently; missing menu entries usually trace back to a load-time error in the plugin.
+- Iterate on widget code without booting the reader: `./kodev wbuilder` spins up a minimal UI host. Add `UIManager:show(MyWidget:new{...})` lines to `tools/wbuilder.lua` to preview.
+
+See `references/debugging.md` for emulator setup, asserts, and breakpoint strategies.
+
+## Important Gotchas
+
+- **Module identity:** patches must target the exact module path KOReader uses (`require("apps.reader.readerui")`, not `require("readerui")` from outside the source root). Mismatched paths silently no-op.
+- **Event return contract:** forgetting to `return true` causes events to keep propagating, often manifesting as duplicated actions.
+- **String translation:** wrap user-visible strings in `_(...)` from `gettext` so they participate in translations.
+- **Reader vs. FileManager host:** plugins can run under either. Check `self.ui.name == "ReaderUI"` or use `if self.ui.document then` to branch.
+- **Version drift:** KOReader internals change between releases. Both patches and plugins that touch private fields must declare a target version in the header and degrade gracefully if internals shift.
+- **No pcall around plugin init:** an error during `init` disables the plugin without obvious user feedback. Keep `init` defensive and short; defer heavy work to lazy methods or first-event.
+
+## File Layout Reference
+
+```
+koreader/
+├── plugins/
+│   └── MyPlugin.koplugin/
+│       ├── _meta.lua
+│       ├── main.lua
+│       └── (assets, sub-modules, README.md)
+├── patches/
+│   ├── 2-fix-something.lua
+│   └── 3-override-menu.lua
+└── crash.log
+```
+
+## Source-of-Truth Links
+
+These pages back the rules above. Verify against them when behavior diverges.
+
+- Development guide (frontend layout): <https://koreader.rocks/doc/topics/Development_guide.md.html>
+- Events guide (propagation, builtin events): <https://koreader.rocks/doc/topics/Events.md.html>
+- Hacking guide (debugging, wbuilder): <https://koreader.rocks/doc/topics/Hacking.md.html>
+- `pluginloader` module: <https://koreader.rocks/doc/modules/pluginloader.html>
+- `userpatch` module: <https://koreader.rocks/doc/modules/userpatch.html>
+- HelloWorld example plugin: <https://github.com/koreader/koreader/tree/master/plugins/helloworld.koplugin>
+
+## Additional Resources
+
+### Reference Files
+
+- `references/plugin-anatomy.md` — `_meta.lua`, `main.lua`, lifecycle, `addToMainMenu`, dispatcher integration, plugin disable/enable settings.
+- `references/events-and-widgets.md` — `WidgetContainer` propagation rules, common reader/filemanager events, `UIManager` lifecycle.
+- `references/patches.md` — patch priorities, monkey-patch idioms, version-guard patterns, removal/cleanup.
+- `references/debugging.md` — `logger`, `dbg`, `crash.log`, `wbuilder`, emulator workflow.
+
+### Examples
+
+- `examples/helloworld.lua` — minimal plugin `main.lua` showing menu registration and `InfoMessage`.
+- `examples/_meta.lua` — minimal metadata file.
+- `examples/2-example-patch.lua` — early-phase patch that wraps an existing method.
+
+When information conflicts, the source-of-truth links above take precedence over this skill — verify against them before changing production code.

package/dist/skills/koreader-plugin-development/examples/2-example-patch.lua

@@ -0,0 +1,17 @@
+-- koreader/patches/2-example-patch.lua
+-- Early-phase patch: wrap InfoMessage:init to prefix every message with "[patched]".
+-- Targets KOReader v2025.05+. Remove if upstream changes the InfoMessage API.
+
+local Version = require("version")
+if Version:getCurrentRevision() < "v2025.05" then return end
+
+local InfoMessage = require("ui.widget.infomessage")
+local original_init = InfoMessage.init
+
+function InfoMessage:init()
+    if self.text and not self._patched then
+        self.text = "[patched] " .. self.text
+        self._patched = true
+    end
+    return original_init(self)
+end

package/dist/skills/koreader-plugin-development/examples/_meta.lua

@@ -0,0 +1,6 @@
+local _ = require("gettext")
+return {
+    name = "helloworld",
+    fullname = _("Hello World"),
+    description = _([[A minimal plugin that adds a menu entry showing an InfoMessage.]]),
+}

package/dist/skills/koreader-plugin-development/examples/helloworld.lua

@@ -0,0 +1,36 @@
+-- Minimal KOReader plugin: HelloWorld.koplugin/main.lua
+-- Add to plugins/HelloWorld.koplugin/ alongside _meta.lua, then restart KOReader.
+
+local InfoMessage = require("ui.widget.infomessage")
+local UIManager = require("ui.uimanager")
+local WidgetContainer = require("ui.widget.container.widgetcontainer")
+local logger = require("logger")
+local _ = require("gettext")
+
+local HelloWorld = WidgetContainer:extend{
+    name = "helloworld",
+    is_doc_only = false,
+}
+
+function HelloWorld:init()
+    self.ui.menu:registerToMainMenu(self)
+end
+
+function HelloWorld:addToMainMenu(menu_items)
+    menu_items.helloworld = {
+        text = _("Hello World"),
+        sorting_hint = "tools",
+        callback = function()
+            UIManager:show(InfoMessage:new{
+                text = _("Hello, plugin world."),
+            })
+        end,
+    }
+end
+
+function HelloWorld:onPageUpdate(new_pageno)
+    logger.dbg("HelloWorld saw PageUpdate", new_pageno)
+    -- Do not return true; let other widgets handle the event too.
+end
+
+return HelloWorld

package/dist/skills/koreader-plugin-development/references/debugging.md

@@ -0,0 +1,92 @@
+# Debugging KOReader Plugins and Patches
+
+## Quick logger
+
+```lua
+local logger = require("logger")
+logger.dbg("foo", { a = 1 })  -- prefixed with DEBUG
+logger.info("startup ok")
+logger.warn("recoverable issue")
+logger.err("failure", err)
+```
+
+`logger.dbg` only prints when debug logging is enabled. Lua evaluates arguments eagerly, so wrap heavy work:
+
+```lua
+local dbg = require("dbg")
+if dbg.is_on then
+    logger.dbg("expensive view", buildSnapshot())
+end
+```
+
+## Where logs go
+
+- Desktop emulator: stdout of the `./kodev run` process.
+- On device: `koreader/crash.log`. Lines tagged `04/06/17-21:44:53 DEBUG …`.
+
+`crash.log` is the first place to look when a plugin "doesn't load" or a patch "didn't run". Plugin-load errors land here with the plugin path.
+
+## Enable debug mode
+
+- Dev: `./kodev run --debug`
+- On device: `Settings -> Developer options -> Enable debug logging`. Optionally `Enable verbose debug logging` for finer detail. Restart KOReader for the change to take effect.
+
+In debug mode the loader logs stack traces from event handlers — this is how you find which plugin or patch raised an exception during event dispatch.
+
+## Emulator workflow
+
+`./kodev` is the dev driver. Useful targets:
+
+- `./kodev run` — start the SDL emulator with the bundled plugins.
+- `./kodev run --debug` — same with debug logging.
+- `./kodev wbuilder` — minimal UI host for prototyping a single widget without booting reader/file-manager. Append `UIManager:show(MyWidget:new{...})` lines to `tools/wbuilder.lua`.
+- `./kodev test` — run the unit suite (`busted`).
+- `./kodev clean` / `./kodev fetch-thirdparty` — when builds drift.
+
+For out-of-tree plugin development, point KOReader at your folder via the `extra_plugin_paths` setting (UI: Plugin manager) so you do not have to copy files on each iteration.
+
+## Inspecting state
+
+- `dbg.dump(any_value)` — pretty-prints a Lua table to the log.
+- `require("dump")(any_value)` — alternative dumper used elsewhere in the codebase.
+- `UIManager._window_stack` — the live widget stack, top of stack is the topmost visible widget.
+- `self.ui` from inside a plugin gives access to the host (`ReaderUI` or `FileManager`) and all sibling modules (`self.ui.menu`, `self.ui.document`, `self.ui.dictionary`, etc.).
+
+## Asserts and fail-fast
+
+Plugin `init` errors disable the plugin silently in production; let them propagate during development:
+
+```lua
+function MyPlugin:init()
+    assert(self.ui, "no host UI")
+    -- ...
+end
+```
+
+Wrap the assert in `if dbg.is_on then` if you need a forgiving build.
+
+## Common diagnostics
+
+| Symptom | First check |
+|---------|-------------|
+| Plugin not in plugin manager | `crash.log` for load error; verify `_meta.lua` returns a table |
+| Menu entry missing | `addToMainMenu` actually called? `self.ui.menu:registerToMainMenu(self)` in `init`? |
+| Event handler not firing | Event name typo; `is_doc_only` true while in FileManager; child widget consuming first |
+| Patch silently no-op | Wrong module path passed to `require`; another patch already replaced the same method |
+| UI not redrawing | Missing `UIManager:setDirty(widget, "ui")` after mutating widget state |
+
+## Reproducing on device vs emulator
+
+Emulator runs the same Lua but uses SDL for framebuffer and lacks real Wi-Fi, real e-ink refresh quirks, and some device-specific paths. Behaviors that depend on the framebuffer driver (waveform modes, partial refresh) only repro on hardware. Path-sensitive logic (case-sensitive filesystems, mount points) usually shows up on Linux but not on macOS.
+
+## Reading the source effectively
+
+When the docs are silent (most plugin internals), grep:
+
+```
+git grep "Event:new(\"PageUpdate\""
+git grep "registerToMainMenu"
+git grep "applyPatches"
+```
+
+The KOReader codebase is the authoritative reference; treat upstream code as documentation.

package/dist/skills/koreader-plugin-development/references/events-and-widgets.md

@@ -0,0 +1,102 @@
+# Events and Widgets
+
+## Class hierarchy
+
+```
+EventListener           -- ui.widget.eventlistener (handleEvent)
+└── Widget              -- ui.widget.widget
+    └── WidgetContainer -- ui.widget.container.widgetcontainer
+        ├── FrameContainer, CenterContainer, BottomContainer, ...
+        ├── InputContainer  (gesture handling)
+        ├── ReaderUI / FileManager (top-level hosts)
+        └── any plugin extending WidgetContainer
+```
+
+All widgets inherit `handleEvent`. `WidgetContainer` overrides it to first propagate to children; if no child returns `true`, the container's own `on<EventName>` runs.
+
+## Sending an event
+
+```lua
+widget:handleEvent(Event:new("Timeout"))         -- direct, may be unsafe if widget destroys itself
+UIManager:sendEvent(Event:new("PageUpdate", 5))  -- from topmost widget down
+UIManager:broadcastEvent(Event:new("CloseDocument")) -- to every widget on the stack
+```
+
+`Event:new(name, arg1, arg2, ...)` packs args; the receiver implements `on<Name>(self, arg1, arg2, ...)`.
+
+## The event consumption contract
+
+```lua
+function MyPlugin:onPageUpdate(new_pageno)
+    if not self.enabled then return end   -- do not consume
+    self:doWork(new_pageno)
+    return true                            -- stop propagation
+end
+```
+
+- `return true` — consume; sibling widgets and the container's own handler are skipped.
+- `return nil`/`false` — let propagation continue.
+
+Consumption is the most common source of "my plugin runs but the reader stops responding to taps" bugs. Consume only events whose semantics you fully replace.
+
+## Common reader events
+
+| Event | When | Args |
+|-------|------|------|
+| `ReaderReady` | After document opens and modules initialized | `doc_settings` |
+| `CloseDocument` | Before tearing down ReaderUI | — |
+| `PosUpdate` | Reader rolling module signals scroll position change | `pos` |
+| `UpdatePos` | Typesetting changed; recompute layout | — |
+| `PageUpdate` | Page number changed | `new_pageno` |
+| `PageChangeAnimation` | Animated page turn | `forward` |
+| `BookMetadataChanged` | Metadata edited | `prop_updated` |
+| `Suspend` / `Resume` | Device sleep cycle | — |
+| `NetworkConnected` / `NetworkDisconnected` | Network state | — |
+
+## Common file-manager events
+
+| Event | When |
+|-------|------|
+| `PathChanged` | Directory navigated |
+| `BookmarkAdded` / `BookmarkRemoved` | Bookmark mutated |
+| `SetupShowReader` | About to launch Reader for a file |
+
+For exhaustive coverage, search KOReader source for `Event:new("` — every emit is grep-able.
+
+## UIManager lifecycle for widgets
+
+```lua
+UIManager:show(widget)        -- push onto _window_stack, schedule paint
+UIManager:setDirty(widget, "ui")  -- request redraw
+UIManager:close(widget)       -- pop, schedule repaint of stack below
+UIManager:scheduleIn(0.5, fn) -- run after 500ms
+UIManager:unschedule(fn)
+UIManager:nextTick(fn)        -- defer to next event loop tick
+```
+
+Always pair `show` with `close`. Widgets registered with `is_always_active = true` keep receiving events even when not at the top of the stack.
+
+## Useful built-in widgets
+
+| Widget | Purpose |
+|--------|---------|
+| `InfoMessage` | Modal info text with auto-close |
+| `ConfirmBox` | Yes/no prompt with callbacks |
+| `ButtonDialog` | Multi-button dialog from a 2D grid |
+| `InputDialog` | Text input with buttons |
+| `Notification` | Transient toast (no user dismissal) |
+| `Menu` | Scrollable list of items |
+| `KeyValuePage` | Two-column property display |
+| `TrapWidget` | Block input while a long task runs |
+
+All are under `ui.widget.*` and accept a table of properties to `:new{...}`.
+
+## Draw-page code path (for performance work)
+
+1. `ReaderView:recalculate` flags itself dirty.
+2. UIManager main loop calls `ReaderView:paintTo`.
+3. `ReaderView:paintTo` calls `document:drawPage`.
+4. `document:drawPage` checks the cache; if hit, returns the cached buffer.
+5. On miss, `document:renderPage` calls `_document:openPage`, `page:draw`, then caches the buffer.
+
+Hooking `ReaderView:paintTo` from a plugin can layer custom overlays per page; do it sparingly and never block.

package/dist/skills/koreader-plugin-development/references/patches.md

@@ -0,0 +1,118 @@
+# Patches (`koreader/patches/`)
+
+User patches are arbitrary Lua files in `koreader/patches/` that the `userpatch` module applies during startup. Use them when:
+
+- A plugin would be overkill for a one-line behavior change.
+- The change must run before plugins or before the UI builds.
+- Distributing a hotfix to users who can drop a single file into a directory.
+
+## Priority ordering
+
+`userpatch.applyPatches(priority)` is called multiple times during boot. Each call processes files whose name starts with the matching numeric prefix, sorted lexicographically.
+
+| Filename prefix | Phase | Run point | Typical use |
+|-----------------|-------|-----------|-------------|
+| `1-` | early-once | Very early, before most modules load | Set globals, env vars, monkey-patch core utilities |
+| `2-` | early | After core modules load, before UI | Override module methods that the UI then uses |
+| `3-` | late | After UI is built | Replace running widgets, mutate menus |
+
+A patch named `2-fix-readerfooter.lua` runs in the early phase; `3-add-menu.lua` runs late.
+
+## Patch skeleton
+
+```lua
+-- 2-stay-on-cover.lua
+-- Targets KOReader v2025.05+; remove if behavior is fixed upstream.
+
+local ReaderRolling = require("apps.reader.modules.readerrolling")
+local original_onReadSettings = ReaderRolling.onReadSettings
+
+function ReaderRolling:onReadSettings(config)
+    local res = original_onReadSettings(self, config)
+    if config:nilOrTrue("stay_on_cover") then
+        self:gotoPos(0)
+    end
+    return res
+end
+```
+
+Always:
+
+1. Capture the original function before replacement.
+2. Call the original from inside your override unless the goal is total replacement.
+3. Pass `self` and all args through unchanged.
+
+## Patch idioms
+
+### Add a method
+
+```lua
+local M = require("apps.reader.modules.readerbookmark")
+function M:exportAll()
+    -- ...
+end
+```
+
+### Wrap an existing method
+
+```lua
+local M = require("ui.widget.infomessage")
+local orig = M.init
+function M:init()
+    orig(self)
+    self.text = "[patched] " .. (self.text or "")
+end
+```
+
+### Replace a method
+
+```lua
+local M = require("apps.reader.modules.readerfooter")
+function M:onTapFooter() return false end
+```
+
+### Add a menu entry from a patch
+
+A patch can mutate the menu builder used by the UI — the safer option is to attach to an existing module's `addToMainMenu`:
+
+```lua
+local M = require("apps.reader.modules.readermenu")
+local orig = M.setUpdateItemTable
+function M:setUpdateItemTable()
+    orig(self)
+    self.menu_items.tools.sub_item_table[#self.menu_items.tools.sub_item_table + 1] = {
+        text = "Patched entry",
+        callback = function() end,
+    }
+end
+```
+
+For complex menu work, prefer a plugin.
+
+## Version guarding
+
+KOReader internals shift between releases. A patch that worked on v2025.04 may crash on v2025.07.
+
+```lua
+local Version = require("version")
+local current = Version:getCurrentRevision()
+if current < "v2025.05" then return end  -- skip if older
+```
+
+Always include a target-version comment header so users (and you, six months later) can audit at a glance.
+
+## Removal
+
+To disable a patch, delete it or rename it so the prefix no longer matches a known phase (e.g. `_off-2-foo.lua`). Patches do not auto-clean their effects on next boot — KOReader simply does not reapply them.
+
+Patches that allocate scheduled tasks or register listeners must clean up on `CloseDocument` / `Exit` if the user might disable them mid-session. Easier path: design patches to be idempotent and applied only at startup.
+
+## Failure mode
+
+A patch that errors during application aborts only that patch; remaining patches and the rest of boot continue. The traceback lands in `crash.log` with the patch filename. Always test with debug logging on (`./kodev run --debug`) before shipping.
+
+## When NOT to use a patch
+
+- Adding substantial new UI → write a plugin.
+- Anything users should be able to toggle → write a plugin.
+- Patching something that has an official extension hook → use the hook (events, dispatcher, `addToMainMenu`).

package/dist/skills/koreader-plugin-development/references/plugin-anatomy.md

@@ -0,0 +1,97 @@
+# Plugin Anatomy
+
+## Directory layout
+
+A plugin is a directory whose name matches `.+%.koplugin`. KOReader scans `DEFAULT_PLUGIN_PATH` (the bundled `plugins/` directory) plus any path listed in the `extra_plugin_paths` setting. The user setting `plugins_disabled` is a table of plugin names to skip.
+
+```
+MyPlugin.koplugin/
+├── _meta.lua        # plugin metadata (required for menu integration)
+├── main.lua         # returns the plugin class
+├── README.md        # optional, surfaced in the plugin manager UI
+├── i18n/            # optional Crowdin-style translations
+└── *.lua            # additional sub-modules
+```
+
+## `_meta.lua`
+
+Returns a plain table that pluginloader reads before instantiating `main.lua`. Minimum fields:
+
+```lua
+return {
+    name = "myplugin",            -- internal id, must match WidgetContainer name
+    fullname = _("My Plugin"),    -- shown in plugin manager
+    description = _([[One-paragraph description.]]),
+}
+```
+
+Optional fields recognized by the loader: `version`, `author`. The translation function `_` comes from `gettext` and is available in `_meta.lua` evaluation scope.
+
+## `main.lua` skeleton
+
+```lua
+local WidgetContainer = require("ui.widget.container.widgetcontainer")
+local InfoMessage = require("ui.widget.infomessage")
+local UIManager = require("ui.uimanager")
+local _ = require("gettext")
+
+local MyPlugin = WidgetContainer:extend{
+    name = "myplugin",
+    is_doc_only = false,   -- true: only load inside ReaderUI
+}
+
+function MyPlugin:init()
+    self.ui.menu:registerToMainMenu(self)
+end
+
+function MyPlugin:addToMainMenu(menu_items)
+    menu_items.myplugin = {
+        text = _("My plugin"),
+        sorting_hint = "tools",
+        callback = function()
+            UIManager:show(InfoMessage:new{ text = _("Hello from MyPlugin") })
+        end,
+    }
+end
+
+return MyPlugin
+```
+
+Key conventions:
+
+- `name` must be unique and match the directory stem.
+- `is_doc_only = true` restricts the plugin to ReaderUI; omit for both hosts.
+- `init` runs after the host UI built `self.ui`. Treat it as the plugin's constructor — register menus, dispatcher actions, and event listeners here.
+- Returning the class (not an instance) lets pluginloader instantiate per host.
+
+## Lifecycle and host wiring
+
+`pluginloader` instantiates plugins for the active UI host (`FileManager` or `ReaderUI`). Each instance is appended as a child of that host's `WidgetContainer`, so it receives every event the host receives via standard propagation.
+
+To register hooks beyond the menu:
+
+- Dispatcher actions (gestures, profiles): `Dispatcher:registerAction("my_action", { category = "none", event = "MyAction", title = _("My action"), general = true })` then handle `onMyAction`.
+- Background work: extend `ui.plugin.background_task_plugin`.
+- Toggle behavior: extend `ui.plugin.switch_plugin`.
+
+## Event handlers in plugins
+
+Implement `onFoo(self, ...)` to handle event `Foo`. The host UI broadcasts events down the tree; plugins receive them after host modules. Returning `true` stops propagation. Avoid swallowing events the reader needs (`PageUpdate`, `PosUpdate`) unless that is the goal.
+
+## Persistence
+
+- App-wide settings: `local LuaSettings = require("luasettings"); local s = LuaSettings:open(DataStorage:getSettingsDir() .. "/myplugin.lua")`.
+- Per-document state: `self.ui.doc_settings:saveSetting("myplugin_state", value)`. Saved with the document's metadata.
+- Always handle the case where the file does not yet exist; LuaSettings degrades to an empty table.
+
+## Internationalization
+
+Wrap user-visible strings: `local _ = require("gettext"); _("Save")`. For plurals, `gettext.ngettext("%1 page", "%1 pages", n)`. Translations live under KOReader's main `l10n/` tree; for in-tree plugins, use the project's translation pipeline. For out-of-tree plugins, you may ship strings English-only or vendor your own gettext catalog.
+
+## Loading errors
+
+Errors during plugin load disable the plugin silently for the user but log to `crash.log`. Defensive techniques:
+
+- Wrap optional dependencies (e.g. plugins that integrate with another plugin) in `pcall(require, "...")`.
+- Keep `_meta.lua` side-effect free — it loads in a plain `dofile` context.
+- Avoid top-level `require` of modules that only exist in newer KOReader versions; gate with `pcall` and fall back gracefully.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurokeita/add-skill",
-	"version": "1.20.0",
+	"version": "1.21.0",
 	"description": "CLI to install AI agent skills to various platforms",
 	"type": "module",
 	"bin": {