From 574088ea5593f30998cd5b97e2f432dfe9e576c3 Mon Sep 17 00:00:00 2001
From: KernelDeimos <7225168+KernelDeimos@users.noreply.github.com>
Date: Wed, 1 Oct 2025 16:03:24 -0400
Subject: [PATCH] doc: improve extension documentation

- describe extension events
- link drivers documentation
---
 extensions/exports_something.js      |  6 +++
 extensions/imports_something.js      |  4 ++
 src/backend/doc/extensions/README.md | 55 ++++++++++++++++++++++------
 3 files changed, 54 insertions(+), 11 deletions(-)

diff --git a/extensions/exports_something.js b/extensions/exports_something.js
index 1fa4ca42..78ac7fb4 100644
--- a/extensions/exports_something.js
+++ b/extensions/exports_something.js
@@ -3,3 +3,9 @@ console.log('exporting something...');
 extension.exports = {
     testval: 5
 };
+
+extension.on('init', () => {
+    extension.emit('hello', {
+        from: 'exports_something',
+    });
+});
diff --git a/extensions/imports_something.js b/extensions/imports_something.js
index b402091d..7a2b2470 100644
--- a/extensions/imports_something.js
+++ b/extensions/imports_something.js
@@ -1,3 +1,7 @@
 console.log('importing something...');
 const { testval } = extension.import('exports_something');
 console.log(testval);
+
+extension.on('hello', event => {
+    console.log(`received "hello" from: ${event.from}`);
+});
diff --git a/src/backend/doc/extensions/README.md b/src/backend/doc/extensions/README.md
index b5456cc4..0282ffc1 100644
--- a/src/backend/doc/extensions/README.md
+++ b/src/backend/doc/extensions/README.md
@@ -1,16 +1,5 @@
 # Puter Backend Extensions
 
-## Extension Completion Checklist
-
-Extensions are under refactor currently. This is the checklist:
-- [x] Add RuntimeModule construct for imports and exports
-- [ ] Remove `registry` system added earlier
-      (the same thing can be accomplished with events)
-- [ ] Add the ability to target specific extensions when
-      emitting events
-- [ ] Add event name aliasing and configurable import mapping
-- [ ] Extract extension loading from the core
-
 ## What Are Extensions
 
 Extensions can extend the functionality of Puter's backend by handling specific
@@ -32,6 +21,36 @@ extensions/
     |- main.js
 ```
 
+The location of the extensions directory can be changed in
+[the config file](../../../../doc/self-hosters/config.md)
+by setting `mod_directories` to an array of valid locations.
+The `mod_directories` parameter has the following default value:
+```json
+["{repo}/mods/mods_enabled", "{repo}/extensions"]
+```
+
+### Events
+
+The primary mechanism of communication between extensions and Puter,
+and between different extensions, is through events. The `extension`
+pseudo-global provides `.on(fn)` to add event listemers and
+`.emit('name', { arbitrary: 'data' })` to emit events.
+
+To try working with events, you could make a simple extension that
+emits an event after adding a listener for its own event:
+
+```javascript
+// Listen to a test event called 'test-event'
+extension.on('test-event', event => {
+      console.log(`We got the test event from ${sender}`);
+});
+
+// Listen to init; a good time to emit events
+extension.on('init', event => {
+      extension.emit('test-event', { sender: 'Quinn' });
+});
+```
+
 ### Importing / Exporting
 
 Here are two extensions. One extension has an "extension export" (an export to
@@ -59,3 +78,17 @@ const { test_value } = extension.import('exports-something');
 
 console.log(test_value); // 'Hello, extensions!'
 ```
+
+### Adding Features to Puter
+- [Implementing Drivers](./pages/drivers.md)
+
+## Extensions - Planned Features
+
+Extensions are under refactor currently. This is the checklist:
+- [x] Add RuntimeModule construct for imports and exports
+- [x] Add support to implement drivers in extensions
+- [ ] Add the ability to target specific extensions when
+      emitting events
+- [ ] Add event name aliasing and configurable import mapping
+- [ ] Extract extension loading from the core
+- [ ] List exports in console