@kurokeita/add-skill 1.20.0 → 2.0.0

package/dist/skills/git-commit/SKILL.md

@@ -1,22 +1,95 @@
 ---
 name: git-commit
-description: This skill should be used when the user asks to "commit changes", "commit message", or "follow conventional commits". Provides guidelines for Conventional Commits specification and commit message formatting.
-version: 1.0.0
+description: Use BEFORE running any write-side git or gh command (git commit, git commit --amend, git push --force / --tags, git reset --hard, git rebase, gh pr create, gh pr merge), and whenever the user asks to commit changes, write a commit message, or follow conventional commits. Provides the hard pre-commit protocol (stop, summarize, propose, ask, wait) plus the Conventional Commits format used for the proposed message.
+version: 2.0.0
 ---
 
 # Git Commit
 
-Guide for managing version control commit message formatting following the Conventional Commits specification.
+This skill enforces the pre-commit protocol AND specifies the commit-message format. Both are mandatory before any gated git/gh write operation runs.
 
-## When to Use This Skill
+## When to Use
 
-- Formatting commit messages to follow project standards
-- Learning the Conventional Commits specification
-- Ensuring consistency across the repository's history
+Invoke this skill BEFORE calling Bash for any of:
 
-## Conventional Commits
+- `git commit` (any form, including `-m`, `-am`, no-args, heredoc, chained via `&&`/`;`)
+- `git commit --amend` (any form)
+- `git push --force` / `git push -f` / `git push --force-with-lease`
+- `git push --tags`
+- `git reset --hard`
+- `git rebase` (any form, interactive or non-interactive)
+- `gh pr create`
+- `gh pr merge`
 
-Format commit messages according to the [Conventional Commits](https://www.conventionalcommits.org/) specification to enable automated changelog generation and easier history browsing.
+Also invoke when the user asks to commit changes, write a commit message, or follow conventional commits.
+
+The `permissions.ask` rule in `~/.claude/settings.json` will surface a permission prompt for these commands regardless. This skill ensures the prompt arrives with a proper proposal already presented to the user.
+
+## Pre-Commit Protocol (HARD RULE)
+
+Every gated command, every time. No exceptions for "tiny" or "obvious" changes. Each commit gets its own gate even within the same session. Plan approval, prior "go ahead" signals, and approvals of earlier commits do NOT carry over.
+
+### Step 1 — STOP
+
+Do not retry the command yet. The first attempt is your trigger, not your green light.
+
+### Step 2 — Emit a detailed technical summary
+
+```bash
+### Technical summary
+- Scope: <files added/modified/deleted, one-line purpose each>
+- Behavior change: <user-visible / API-visible effect, or "none" for pure refactors>
+- Architecture/contract impact: <new exports, removed symbols, changed signatures, new dependencies, or "none">
+- Tests: <what was added/updated, what was run, the result>
+- Risk notes: <edge cases, deferred follow-ups, impact-analysis severity>
+```
+
+Fill every bullet. "None" is a valid answer; an omitted bullet is not.
+
+### Step 3 — Propose a commit message
+
+Format per the Conventional Commits section below. No `Co-Authored-By: Claude` trailer. Imperative present tense, no trailing period in the subject. When a body is included, it explains the why.
+
+**Match the message size to the change.** For small commits — single file, trivial scope, narrow type change, doc tweak, small revert, one-line config flip, renamed prop — propose a title-only message. No body, no bullets. The subject alone conveys intent and a body adds friction without value.
+
+```bash
+### Proposed commit message
+<type>(<scope>): <imperative subject>
+```
+
+Reserve the full proposal format (body + bullets) for commits that touch multiple files, change behavior in subtle ways, or introduce risk worth flagging:
+
+```bash
+### Proposed commit message
+<type>(<scope>): <imperative subject>
+
+<body paragraph(s) explaining motivation and behavior change>
+
+- bullet of notable change
+- bullet of notable change
+```
+
+### Step 4 — Ask the user verbatim
+
+Print exactly: **"Commit as-is, edit the message, or skip?"**
+
+### Step 5 — Wait for explicit approval
+
+Only after the user replies with an affirmative answer may you re-attempt the command. The OS permission prompt will then surface for final confirmation.
+
+If the user declines or asks to edit, do not commit. Update the proposal and re-ask.
+
+## Multi-commit work
+
+If you have several logical commits ready, emit one full proposal per commit and gate each independently. Do not batch proposals. Do not commit any of them until each is individually approved.
+
+## Subagent delegation
+
+If you dispatch a subagent that will end in a gated command, you (the orchestrator) own the proposal step. Either instruct the subagent to stop before the command and report back, or require it to wait for an "approved" signal you forward only after the user approves the proposal. A subagent that commits on its own initiative is a rule violation.
+
+## Conventional Commits format
+
+Format the proposed message per the [Conventional Commits](https://www.conventionalcommits.org/) specification.
 
 ### Structure
 
@@ -30,36 +103,27 @@ Format commit messages according to the [Conventional Commits](https://www.conve
 
 ### Types
 
-- `feat`: A new feature
-- `fix`: A bug fix
-- `docs`: Documentation only changes
-- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
-- `refactor`: A code change that neither fixes a bug nor adds a feature
-- `perf`: A code change that improves performance
-- `test`: Adding missing tests or correcting existing tests
-- `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
-- `ci`: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
-- `chore`: Other changes that don't modify src or test files
-- `revert`: Reverts a previous commit
+- `feat`: a new feature
+- `fix`: a bug fix
+- `docs`: documentation only changes
+- `style`: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
+- `refactor`: a code change that neither fixes a bug nor adds a feature
+- `perf`: a code change that improves performance
+- `test`: adding missing tests or correcting existing tests
+- `build`: changes that affect the build system or external dependencies
+- `ci`: changes to CI configuration files and scripts
+- `chore`: other changes that do not modify src or test files
+- `revert`: reverts a previous commit
 
 ### Guidelines
 
-- **Description**: Use the imperative, present tense (e.g., "add", not "added" or "adds").
-- **Case**: The description should be in lower-case or sentence-case.
-- **Scope**: Use a scope to provide additional contextual information (e.g., `feat(auth): add login validation`).
-- **Body**: Use the body to explain the "what" and "why" of the change, not the "how".
-- **Footer**: Use the footer to reference issues (e.g., `Closes #123`) or breaking changes.
-
-## Additional Resources
-
-### Reference Files
-
-For detailed patterns and advanced git workflows, consult:
-
-- **`references/conventional-commits.md`** - Detailed Conventional Commits specification.
-
-### Example Files
+- **Description**: imperative, present tense ("add", not "added" or "adds")
+- **Case**: lower-case or sentence-case, no trailing period
+- **Scope**: noun in parentheses describing a section of the codebase (e.g., `feat(auth): add login validation`)
+- **Body**: explain the what and why, not the how
+- **Footer**: reference issues (`Closes #123`) or breaking changes (`BREAKING CHANGE: ...`)
+- **Breaking changes**: indicate with `!` after the type/scope OR a `BREAKING CHANGE:` footer
 
-Working examples in `examples/`:
+### Reference files
 
-- **`commit-messages.txt`** - Examples of well-formatted commit messages.
+For detailed patterns and edge cases, see `references/conventional-commits.md`.

package/dist/skills/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/dist/skills/init-agents-md/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: init-agents-md
+description: Analyze a codebase to initialize or update its AGENTS.md (or CLAUDE.md) file, extract architectural patterns to docs/architectural_patterns.md, and procedural skills to .agents/skills/. Use when initializing a project's agent instructions, updating CLAUDE.md/AGENTS.md, or documenting project structure and workflows.
+---
+
+# Initialize Agent Instructions & Patterns
+
+Use this skill to analyze a workspace and create or update standard developer onboarding and workflow guidelines.
+
+## Workflow
+
+### 1. Analyze Codebase
+
+Explore the codebase to identify:
+
+- **WHAT**: Core technology stack, languages, frameworks, main libraries.
+- **WHY**: Core business logic or project purpose.
+- **HOW**: Scripts and CLI commands (e.g., in package.json, Makefile, etc.).
+- **Files/Docs**: Existing documentation, configuration files, and key source directories.
+- **Workflows**: Critical operational workflows (specifically: build, test, release).
+
+### 2. Generate or Update AGENTS.md
+
+Create or update the `AGENTS.md` (or `CLAUDE.md`) file in the project root.
+
+- Keep the file **under 150 lines** (optimum is 100–150 lines).
+- Reference [agents_template.md](references/agents_template.md) for the structure.
+- Follow these constraints strictly:
+  1. Cover: WHAT (tech stack), WHY (purpose), and HOW (commands).
+  2. Index all major documentation files or folders using progressive disclosure (one-line description each).
+  3. Use **file:line references** (e.g., `src/main.ts:L42`) instead of embedding code snippets.
+  4. Document exactly 2–3 critical workflows (e.g., build, test, release) as numbered steps.
+  5. Do not include formatting or code styling rules (assume linters handle them).
+  6. Always include these two lines under rules/guidelines:
+     - `Be extremely concise. Sacrifice grammar for concision.`
+     - `At the end of each plan, list unresolved questions.`
+
+### 3. Extract Architectural Patterns
+
+Identify recurring design patterns, folder structure conventions, or key abstractions in the codebase.
+
+- Extract these into `docs/architectural_patterns.md`.
+- Reference [patterns_template.md](references/patterns_template.md) for the structure.
+- Provide file:line references for concrete code examples of these patterns.
+
+### 4. Extract Procedural Know-How
+
+Identify step-by-step procedures, deployment configurations, setup guides, or domain-specific instructions that would clutter the main `AGENTS.md` file.
+
+- Extract these into `.agents/skills/<name>/SKILL.md` under the project scope.
+- Reference the newly created skills in `AGENTS.md` or `docs/architectural_patterns.md` where relevant.

package/dist/skills/init-agents-md/references/agents_template.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+## Purpose & Tech Stack
+
+- **WHAT**: [Tech stack, e.g., Next.js, TypeScript, TailwindCSS]
+- **WHY**: [Core project purpose, target users, problem solved]
+
+## Commands
+
+```bash
+pnpm dev             # Run local dev server
+pnpm build           # Build project for production
+pnpm test            # Run test suite
+pnpm lint            # Check types and linting
+```
+
+## Documentation Index
+
+- [docs/architecture.md](file:///path/to/docs/architecture.md) — One-line overview of architecture
+- [docs/api.md](file:///path/to/docs/api.md) — One-line overview of API design
+
+## Critical Workflows
+
+### 1. Development & Build
+
+1. Run local environment: `command`
+2. Validate changes: `command`
+
+### 2. Testing
+
+1. Run unit tests: `command`
+2. Run integration tests: `command`
+
+### 3. Release/Deployment
+
+1. Build assets: `command`
+2. Deploy command or CI pipeline trigger: `command`
+
+## Guidelines
+
+- Be extremely concise. Sacrifice grammar for concision.
+- At the end of each plan, list unresolved questions.

package/dist/skills/init-agents-md/references/patterns_template.md

@@ -0,0 +1,19 @@
+# Architectural & Design Patterns
+
+This document details the recurring architectural, design, and structural patterns found in this codebase.
+
+## 1. [Pattern Name]
+
+- **Intent**: [What problem does this pattern solve?]
+- **Location/Example**: [e.g., src/utils/paths.ts:L10-L40]
+- **Implementation Details**:
+  - [Key implementation note 1]
+  - [Key implementation note 2]
+
+## 2. [Pattern Name]
+
+- **Intent**: [What problem does this pattern solve?]
+- **Location/Example**: [e.g., src/commands/add.ts:L45-L90]
+- **Implementation Details**:
+  - [Key implementation note 1]
+  - [Key implementation note 2]

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.