From dc04a27d89f5506623233496986b161083f5d752 Mon Sep 17 00:00:00 2001
From: 4ian <1280130+4ian@users.noreply.github.com>
Date: Tue, 28 Apr 2026 09:04:32 +0000
Subject: [PATCH] [Auto] [Update] Document custom toolbar buttons lifecycle
 hooks in gdevelop-settings.yaml

---
 automated_updates_data.json                   |  2 +-
 .../how-to-use-gdevelop-as-a-team/index.md    | 54 ++++++++++++++++++-
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/automated_updates_data.json b/automated_updates_data.json
index 47a68ca543..18f78b58d4 100644
--- a/automated_updates_data.json
+++ b/automated_updates_data.json
@@ -1,5 +1,5 @@
 {
-  "last_automated_updates_commit": "ac476aea35aa6fa8dc517c94524c3ceae211d18e",
+  "last_automated_updates_commit": "e62e15c74bf0c2cead8dd35a07ae478688ef219d",
   "last_improved_things": [
     {
       "date": "2026-02-16",
diff --git a/docs/gdevelop5/tutorials/how-to-use-gdevelop-as-a-team/index.md b/docs/gdevelop5/tutorials/how-to-use-gdevelop-as-a-team/index.md
index 2278c1922d..4d72d30ad1 100644
--- a/docs/gdevelop5/tutorials/how-to-use-gdevelop-as-a-team/index.md
+++ b/docs/gdevelop5/tutorials/how-to-use-gdevelop-as-a-team/index.md
@@ -57,4 +57,56 @@ These settings override personal preferences only while the project is open and
 
 !!! note
 
-    Project-specific settings are only supported in the desktop version of GDevelop.
\ No newline at end of file
+    Project-specific settings are only supported in the desktop version of GDevelop.
+
+## Custom toolbar buttons and npm scripts
+
+If your project has a `package.json` file (with npm scripts defined), you can add custom buttons to the GDevelop toolbar via `gdevelop-settings.yaml`. Each button runs a named npm script from your `package.json` when clicked.
+
+```yaml
+toolbarButtons:
+  - name: "Lint"
+    icon: "🔍"
+    npmScript: "lint"
+  - name: "Build assets"
+    icon: "🏗️"
+    npmScript: "build-assets"
+```
+
+Each button requires:
+
+* `name` - Label shown in the toolbar tooltip
+* `icon` - Emoji or short text used as the button icon
+* `npmScript` - Name of the script to run (must match a key in `package.json`'s `scripts` section)
+
+### Lifecycle hooks
+
+A toolbar button can also be set to run **automatically** at key editor moments by adding a `hook` field:
+
+```yaml
+toolbarButtons:
+  - name: "Sync assets on open"
+    icon: "🔄"
+    npmScript: "sync-assets"
+    hook: "onEditorReady"
+  - name: "Hot-reload watcher"
+    icon: "👁️"
+    npmScript: "watch"
+    hook: "onPreviewStart"
+  - name: "Stop watcher"
+    icon: "⏹️"
+    npmScript: "stop-watch"
+    hook: "onPreviewEnd"
+```
+
+Available hooks:
+
+* `onEditorReady` - Runs once when the project is opened in the editor
+* `onPreviewStart` - Runs each time a preview is launched
+* `onPreviewEnd` - Runs each time a preview is stopped
+
+The first time a hook or button triggers a script, GDevelop will ask for confirmation before running it. You can choose to skip future confirmations for that project.
+
+!!! warning
+
+    Only run npm scripts from projects you created yourself or from sources you fully trust. Scripts execute on your computer and could potentially cause harm if they come from an unknown source.
\ No newline at end of file