From bfffdfdc368dc25c17a2cc0cfb4d8efe9a5f74a8 Mon Sep 17 00:00:00 2001
From: KernelDeimos <7225168+KernelDeimos@users.noreply.github.com>
Date: Wed, 1 Oct 2025 16:47:56 -0400
Subject: [PATCH] doc(extensions): exports not front-and-center

The extension documentation mentions imports and exports together very
early on, but extension exports should be used sparingly. I suspect most
extensions with exports will be among Puter's builtin extensions.
---
 src/backend/doc/extensions/README.md          | 28 ++++---------------
 .../doc/extensions/pages/import-and-export.md | 28 +++++++++++++++++++
 2 files changed, 34 insertions(+), 22 deletions(-)
 create mode 100644 src/backend/doc/extensions/pages/import-and-export.md

diff --git a/src/backend/doc/extensions/README.md b/src/backend/doc/extensions/README.md
index 0282ffc1..96cb8fb7 100644
--- a/src/backend/doc/extensions/README.md
+++ b/src/backend/doc/extensions/README.md
@@ -51,33 +51,17 @@ extension.on('init', event => {
 });
 ```
 
-### Importing / Exporting
+### Imports
 
-Here are two extensions. One extension has an "extension export" (an export to
-other extensions) and an "extension import" (an import from another extension).
-This is different from regular `import` or `require()` because it resolves to
-a Puter extension loaded at runtime rather than an `npm` module.
+Your extensions may need to invoke specific actions in Puter's backend
+in response to an event. Puter provides libraries at runtime which you
+can access via `extension.imports`:
 
-To import and export in Puter extensions, we use `extension.import()` and `extension.exports`.
-
-`exports-something.js`
 ```javascript
-//@puter priority -1
-// ^ setting load priority to "-1" allows other extensions to import
-//   this extension's exports before the initialization event occurs
-
-// Just like "module.exports", but for extensions!
-extension.exports = {
-    test_value: 'Hello, extensions!,
-};
+const { kv } = extension.imports('data');
+kv.set('some-key', 'some value');
 ```
 
-`imports-something.js`
-```javascript
-const { test_value } = extension.import('exports-something');
-
-console.log(test_value); // 'Hello, extensions!'
-```
 
 ### Adding Features to Puter
 - [Implementing Drivers](./pages/drivers.md)
diff --git a/src/backend/doc/extensions/pages/import-and-export.md b/src/backend/doc/extensions/pages/import-and-export.md
new file mode 100644
index 00000000..09b15e3e
--- /dev/null
+++ b/src/backend/doc/extensions/pages/import-and-export.md
@@ -0,0 +1,28 @@
+## Extensions - Importing & Exporting
+
+Here are two extensions. One extension has an "extension export" (an export to
+other extensions) and an "extension import" (an import from another extension).
+This is different from regular `import` or `require()` because it resolves to
+a Puter extension loaded at runtime rather than an `npm` module.
+
+To import and export in Puter extensions, we use `extension.import()` and `extension.exports`.
+
+`exports-something.js`
+```javascript
+//@puter priority -1
+// ^ setting load priority to "-1" allows other extensions to import
+//   this extension's exports before the initialization event occurs
+
+// Just like "module.exports", but for extensions!
+extension.exports = {
+    test_value: 'Hello, extensions!,
+};
+```
+
+`imports-something.js`
+```javascript
+const { test_value } = extension.import('exports-something');
+
+console.log(test_value); // 'Hello, extensions!'
+```
+