From 15e3f53d84ddada3ea9a7e31a10a9c4dc9ed99c7 Mon Sep 17 00:00:00 2001
From: unless <unlessgames@gmail.com>
Date: Wed, 23 Sep 2026 14:53:55 +0200
Subject: [PATCH 1/2] add summary for song lifetime

---
 docs/guide/song.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/guide/song.md b/docs/guide/song.md
index db669ca..7a59118 100644
--- a/docs/guide/song.md
+++ b/docs/guide/song.md
@@ -397,4 +397,29 @@ local selected_device = song.selected_track_device
 if selected_device then
   print("Selected device: " .. selected_device.display_name)
 end
-```
\ No newline at end of file
+```
+
+## Lifetime of a Song
+
+Below is a timeline of the different events that happen regarding songs while Renoise is running with your tool enabled. Tools that want to keep some context around based on the current song will want to manage it by listening to some or all of the listed observables for changes.
+
+### Initialization
+
+1. Renoise boots up
+2. Your tool's `main.lua` is executed
+3. Two things happen without a strict order
+	* A `Song` is loaded and [`app_new_document`](../API/renoise/renoise.ScriptingTool.md#app_new_document_observable--renoisedocumentobservable) fires
+	* The user's saved preferences are loaded for your `Tool` and [`tool_finished_loading`](../API/renoise/renoise.ScriptingTool.md#tool_finished_loading_observable) fires
+
+### User loads a new song
+
+1. If the user saves the previous song (`A`) before loading a new song (`B`) these save related notifier trigger
+	1. [`app_will_save_document`](../API/renoise/renoise.ScriptingTool.md#app_will_save_document_observable) fires with song `A`
+	2. [`app_saved_document`](../API/renoise/renoise.ScriptingTool.md#app_saved_document_observable) fires with song `A` (if saving was successful)
+2. [`app_release_document`](../API/renoise/renoise.ScriptingTool.md#app_release_document_observable) fires with song `A`
+3. [`app_new_document`](../API/renoise/renoise.ScriptingTool.md#app_new_document_observable) fires with song `B`
+
+### User quits Renoise
+
+1. Step 1 and 2 happens from above (1 only if the song was saved)
+2. [`tool_will_unload`](../API/renoise/renoise.ScriptingTool.md#tool_will_unload_observable) fires

From e5a44ea8462d53938390ffa54f8d555e51a4707e Mon Sep 17 00:00:00 2001
From: unless <unlessgames@gmail.com>
Date: Wed, 23 Sep 2026 15:31:34 +0200
Subject: [PATCH 2/2] add link to tool.md

---
 docs/guide/tool.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/guide/tool.md b/docs/guide/tool.md
index 4cac880..8fae9e2 100644
--- a/docs/guide/tool.md
+++ b/docs/guide/tool.md
@@ -370,6 +370,8 @@ Some important notifiers include:
 *   `app_will_save_document_observable` Fired just before the song is saved.
 *   `app_idle_observable`: Fired periodically, useful for low-priority background tasks.
 
+See a detailed timeline for these notifiers in [Lifetime of a Song](./song.md#lifetime-of-a-song)
+
 ## Preferences
 
 Tools can have preferences that are saved and loaded by Renoise. To use them, we first need to create a [`renoise.Document`](../API/renoise/renoise.Document.md) object which holds the options that we want to store.