From 92f98a93b47b36cb22ed2e6d2d9fdc1153fbad96 Mon Sep 17 00:00:00 2001
From: Tony <68118705+Legend-Master@users.noreply.github.com>
Date: Wed, 1 Oct 2025 17:24:04 +0800
Subject: [PATCH] docs(fs): `fs:scope` usage (#2969)

* docs(fs): `fs:scope` usage

* Use APPDATA for the example instead

* `/**/*`
---
 .../fs/permissions/autogenerated/reference.md | 22 ++++++++++++++++
 plugins/fs/permissions/schemas/schema.json    |  4 +--
 plugins/fs/permissions/scope.toml             | 25 ++++++++++++++++++-
 3 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/plugins/fs/permissions/autogenerated/reference.md b/plugins/fs/permissions/autogenerated/reference.md
index c1a603194..7f021a7f3 100644
--- a/plugins/fs/permissions/autogenerated/reference.md
+++ b/plugins/fs/permissions/autogenerated/reference.md
@@ -3748,6 +3748,28 @@ This enables all index or metadata related commands without any pre-configured a
 
 An empty permission you can use to modify the global scope.
 
+## Example
+
+```json
+{
+  "identifier": "read-documents",
+  "windows": ["main"],
+  "permissions": [
+    "fs:allow-read",
+    {
+      "identifier": "fs:scope",
+      "allow": [
+        "$APPDATA/documents/**/*"
+      ],
+      "deny": [
+        "$APPDATA/documents/secret.txt"
+      ]
+    }
+  ]
+}
+```
+
+
 </td>
 </tr>
 
diff --git a/plugins/fs/permissions/schemas/schema.json b/plugins/fs/permissions/schemas/schema.json
index 54c6798b3..e1c051f70 100644
--- a/plugins/fs/permissions/schemas/schema.json
+++ b/plugins/fs/permissions/schemas/schema.json
@@ -2005,10 +2005,10 @@
           "markdownDescription": "This enables all index or metadata related commands without any pre-configured accessible paths."
         },
         {
-          "description": "An empty permission you can use to modify the global scope.",
+          "description": "An empty permission you can use to modify the global scope.\n\n## Example\n\n```json\n{\n  \"identifier\": \"read-documents\",\n  \"windows\": [\"main\"],\n  \"permissions\": [\n    \"fs:allow-read\",\n    {\n      \"identifier\": \"fs:scope\",\n      \"allow\": [\n        \"$APPDATA/documents/**/*\"\n      ],\n      \"deny\": [\n        \"$APPDATA/documents/secret.txt\"\n      ]\n    }\n  ]\n}\n```\n",
           "type": "string",
           "const": "scope",
-          "markdownDescription": "An empty permission you can use to modify the global scope."
+          "markdownDescription": "An empty permission you can use to modify the global scope.\n\n## Example\n\n```json\n{\n  \"identifier\": \"read-documents\",\n  \"windows\": [\"main\"],\n  \"permissions\": [\n    \"fs:allow-read\",\n    {\n      \"identifier\": \"fs:scope\",\n      \"allow\": [\n        \"$APPDATA/documents/**/*\"\n      ],\n      \"deny\": [\n        \"$APPDATA/documents/secret.txt\"\n      ]\n    }\n  ]\n}\n```\n"
         },
         {
           "description": "This enables all write related commands without any pre-configured accessible paths.",
diff --git a/plugins/fs/permissions/scope.toml b/plugins/fs/permissions/scope.toml
index 7e945aa8b..03ba275a4 100644
--- a/plugins/fs/permissions/scope.toml
+++ b/plugins/fs/permissions/scope.toml
@@ -2,4 +2,27 @@
 
 [[permission]]
 identifier = "scope"
-description = "An empty permission you can use to modify the global scope."
+description = """
+An empty permission you can use to modify the global scope.
+
+## Example
+
+```json
+{
+  "identifier": "read-documents",
+  "windows": ["main"],
+  "permissions": [
+    "fs:allow-read",
+    {
+      "identifier": "fs:scope",
+      "allow": [
+        "$APPDATA/documents/**/*"
+      ],
+      "deny": [
+        "$APPDATA/documents/secret.txt"
+      ]
+    }
+  ]
+}
+```
+"""