diff --git a/docs/tasks/toml-tasks.md b/docs/tasks/toml-tasks.md
index 2c436953b..4a91a15b1 100644
--- a/docs/tasks/toml-tasks.md
+++ b/docs/tasks/toml-tasks.md
@@ -137,7 +137,7 @@ You can hide a task from the list of available tasks by setting `hide = true`:
 ```toml
 [tasks.cleancache]
 run = "rm -rf .cache"
-hide = true # hide this task from the list
+hide = true # hide this task from mise tasks ls / mise run
 ```
 
 ## alias
@@ -180,12 +180,21 @@ outputs = ['target/debug/mycli']
 
 You can use `sources` alone if with [`mise watch`](/cli/watch.html) to run the task when the sources change.
 
-## Shell / Shebang
+## shell / shebang
 
 Tasks are executed with `set -e` (`set -o erropt`) if the shell is `sh`, `bash`, or `zsh`. This means that the script
 will exit if any command fails. You can disable this by running `set +e` in the script.
 
-You can specify a shell command to run the script with (default is [`sh -c`](/configuration/settings.html#unix_default_inline_shell_args) or [`cmd /c`](/configuration/settings.html#windows_default_inline_shell_args)) or use a shebang:
+```toml
+[tasks.echo]
+run = '''
+set +e
+cd /nonexistent
+echo "This will not fail the task"
+'''
+```
+
+You can specify a `shell` command to run the script with (default is [`sh -c`](/configuration/settings.html#unix_default_inline_shell_args) or [`cmd /c`](/configuration/settings.html#windows_default_inline_shell_args)):
 
 ```toml
 [tasks.lint]
@@ -236,9 +245,10 @@ run = [
 bun = 'latest'
 
 [tasks.bun_shell]
-shell = "bun -e"
 description = "https://bun.sh/docs/runtime/shell"
 run = """
+#!/usr/bin/env bun
+
 import { $ } from "bun";
 const response = await fetch("https://example.com");
 await $`cat < ${response} | wc -c`; // 1256
@@ -282,12 +292,28 @@ ruby = 'latest'
 
 [tasks.ruby_task]
 run = """
+#!/usr/bin/env ruby
 puts 'Hello, ruby!'
 """
 ```
 
 :::
 
+::: details What's a shebang? What's the difference between `#!/usr/bin/env` and `#!/usr/bin/env -S`
+
+A shebang is the character sequence `#!` at the beginning of a script file that tells the system which program should be used to interpret/execute the script.
+The [env command](https://manpages.ubuntu.com/manpages/jammy/man1/env.1.html) comes from GNU Coreutils. `mise` does not use `env` but will behave similarly.
+
+For example, `#!/usr/bin/env python` will run the script with the Python interpreter found in the `PATH`.
+
+The `-S` flag allows passing multiple arguments to the interpreter.
+It treats the rest of the line as a single argument string to be split.
+
+This is useful when you need to specify interpreter flags or options.
+Example: `#!/usr/bin/env -S python -u` will run Python with unbuffered output.
+
+:::
+
 ## file
 
 You can specify a file to run as a task:
diff --git a/docs/tips-and-tricks.md b/docs/tips-and-tricks.md
index e70052cf6..8bfab1be9 100644
--- a/docs/tips-and-tricks.md
+++ b/docs/tips-and-tricks.md
@@ -44,7 +44,9 @@ console.log(`Running node: ${process.version}`);
 This can also be useful in environments where mise isn't activated
 (such as a non-interactive session).
 
-You can also download the <https://mise.run> script to use in a project bootstrap script:
+## Bootstrap script
+
+You can download the <https://mise.run> script to use in a project bootstrap script:
 
 ```sh
 curl https://mise.run > setup-mise.sh