From 2bad853445f6259206a654b593ddea52ed4daf71 Mon Sep 17 00:00:00 2001
From: Juan Castro <jfcastro9208@gmail.com>
Date: Mon, 28 Sep 2026 17:29:21 -0400
Subject: [PATCH] docs: add a playground example per operation in the perms
 recipe

One runnable example for each section: request a folder, request the
email address, request apps or subdomains, and check before prompting.
---
 src/docs/src/examples.js                      | 24 +++++++++++++++++
 .../examples/perms-ask-for-access-apps.html   | 20 ++++++++++++++
 .../examples/perms-ask-for-access-check.html  | 27 +++++++++++++++++++
 .../examples/perms-ask-for-access-email.html  | 14 ++++++++++
 .../examples/perms-ask-for-access-folder.html | 23 ++++++++++++++++
 5 files changed, 108 insertions(+)
 create mode 100644 src/docs/src/playground/examples/perms-ask-for-access-apps.html
 create mode 100644 src/docs/src/playground/examples/perms-ask-for-access-check.html
 create mode 100644 src/docs/src/playground/examples/perms-ask-for-access-email.html
 create mode 100644 src/docs/src/playground/examples/perms-ask-for-access-folder.html

diff --git a/src/docs/src/examples.js b/src/docs/src/examples.js
index 4a9776700..4c8aedbbb 100644
--- a/src/docs/src/examples.js
+++ b/src/docs/src/examples.js
@@ -945,6 +945,30 @@ const examples = [
                 slug: 'perms-request-permission',
                 source: '/playground/examples/perms-request-permission.html',
             },
+            {
+                title: 'Recipe: ask for a folder',
+                description: 'Ask the user for write access to Documents and save a file with Puter.js permissions API. Run and experiment with this example in the playground.',
+                slug: 'perms-ask-for-access-folder',
+                source: '/playground/examples/perms-ask-for-access-folder.html',
+            },
+            {
+                title: 'Recipe: ask for the email address',
+                description: "Ask the user for their email address with Puter.js permissions API. Run and modify this example instantly in your browser.",
+                slug: 'perms-ask-for-access-email',
+                source: '/playground/examples/perms-ask-for-access-email.html',
+            },
+            {
+                title: 'Recipe: ask about apps or subdomains',
+                description: 'Ask for read or write access to the user apps and subdomains with Puter.js permissions API. Run and experiment with this example in the playground.',
+                slug: 'perms-ask-for-access-apps',
+                source: '/playground/examples/perms-ask-for-access-apps.html',
+            },
+            {
+                title: 'Recipe: check before you prompt',
+                description: 'Check whether access is already held before showing an opt-in with Puter.js permissions API. Run and modify this example directly in your browser.',
+                slug: 'perms-ask-for-access-check',
+                source: '/playground/examples/perms-ask-for-access-check.html',
+            },
         ],
     },
     {
diff --git a/src/docs/src/playground/examples/perms-ask-for-access-apps.html b/src/docs/src/playground/examples/perms-ask-for-access-apps.html
new file mode 100644
index 000000000..6861040c2
--- /dev/null
+++ b/src/docs/src/playground/examples/perms-ask-for-access-apps.html
@@ -0,0 +1,20 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="apps">Read my apps</button>
+    <button id="subdomains">Publish subdomains</button>
+    <script>
+        // These two resolve to a plain boolean, unlike 'folder' and 'email'.
+        document.getElementById('apps').addEventListener('click', async () => {
+            const granted = await puter.perms.request('apps');
+            puter.print(granted ? 'Can read apps' : 'Declined');
+        });
+
+        document.getElementById('subdomains').addEventListener('click', async () => {
+            // access defaults to 'read'; 'write' covers reading too.
+            const granted = await puter.perms.request('subdomains', { access: 'write' });
+            puter.print(granted ? 'Can manage subdomains' : 'Declined');
+        });
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/perms-ask-for-access-check.html b/src/docs/src/playground/examples/perms-ask-for-access-check.html
new file mode 100644
index 000000000..7000ac621
--- /dev/null
+++ b/src/docs/src/playground/examples/perms-ask-for-access-check.html
@@ -0,0 +1,27 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="go">Save to Documents</button>
+    <script>
+        const details = { name: 'Documents', access: 'write' };
+
+        (async () => {
+            // check() never prompts, so it can decide what the UI offers.
+            const held = await puter.perms.check('folder', details);
+            document.getElementById('go').textContent = held
+                ? 'Save to Documents'
+                : 'Allow access, then save';
+        })();
+
+        document.getElementById('go').addEventListener('click', async () => {
+            const path = await puter.perms.request('folder', details);
+            if (!path) {
+                puter.print('Access declined');
+                return;
+            }
+            await puter.fs.write(`${path}/notes.txt`, 'Saved!');
+            puter.print('Saved');
+        });
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/perms-ask-for-access-email.html b/src/docs/src/playground/examples/perms-ask-for-access-email.html
new file mode 100644
index 000000000..feafd3298
--- /dev/null
+++ b/src/docs/src/playground/examples/perms-ask-for-access-email.html
@@ -0,0 +1,14 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="go">Show my email address</button>
+    <script>
+        document.getElementById('go').addEventListener('click', async () => {
+            // Resolves to the address itself, not a boolean.
+            const email = await puter.perms.request('email');
+
+            puter.print(email ? email : 'Declined');
+        });
+    </script>
+</body>
+</html>
diff --git a/src/docs/src/playground/examples/perms-ask-for-access-folder.html b/src/docs/src/playground/examples/perms-ask-for-access-folder.html
new file mode 100644
index 000000000..6a01ee681
--- /dev/null
+++ b/src/docs/src/playground/examples/perms-ask-for-access-folder.html
@@ -0,0 +1,23 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="go">Save a note to Documents</button>
+    <script>
+        document.getElementById('go').addEventListener('click', async () => {
+            // Resolves to the folder's path, or undefined when declined.
+            const path = await puter.perms.request('folder', {
+                name: 'Documents',
+                access: 'write',
+            });
+
+            if (!path) {
+                puter.print('Access declined');
+                return;
+            }
+
+            await puter.fs.write(`${path}/notes.txt`, 'Saved!');
+            puter.print(`Wrote to ${path}/notes.txt`);
+        });
+    </script>
+</body>
+</html>