1 files changed, 34 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/plugins/README.md b/debug/risc-v-gsp-rm-vm/plugins/README.md
new file mode 100644
index 0000000..aa9bc72
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/plugins/README.md
@@ -0,0 +1,34 @@
+# green-eye plugins
+
+A plugin is a Python module exposing `register(ge)`:
+
+```python
+def register(ge):
+    ge.log("my plugin loaded")
+    ge.add_command("mycmd", mycmd, help="does a thing")
+    ge.hook("rpc_sum", on_enter=lambda hit: ge.log(f"sum a0={hit.arg(0):#x}"))
+```
+
+`ge` provides:
+* `session`, `memory`, `symbols`, `recorder` — the live objects;
+* `hook(target, on_enter=, on_leave=)` / `watch(target, size=, kind=, callback=)`;
+* `on_event(kind, callback)` — react to every stop of a kind;
+* `add_command(name, fn, help=)` — new REPL commands (`fn(session, args) -> int`);
+* `log(message, **fields)` — recorded plugin notes.
+
+Discovery: `--plugin PATH` (file or directory), then `GREENEYE_PLUGINS`
+(colon-separated), then the bundled `plugins/` directory. A plugin that raises
+is recorded as `plugin_error` and never breaks the session.
+
+Types of plugins that fit green-eye:
+1. **Runtime RE tools** — new watchpoint strategies, coverage collectors,
+   structure probes, heap/allocator graphs.
+2. **Harnesses** — stimulus drivers that poke mailboxes/rings and assert on
+   recorded events.
+3. **Virtualization-environment updates** — replay/record wrappers, QEMU
+   argument tweaks, device-model shims.
+4. **AI/harness integration** — export sessions to analysis services;
+   **MCP servers are planned as a plugin** (see `docs/08-ROADMAP.md`), not
+   part of v0.1.
+
+The example plugin is `example_plugin.py`.