docs: add explanation about shebang

docs/tasks/toml-tasks.md

@@ -137,7 +137,13 @@ 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 / mise run
+```
+
+Note that if you want to see hidden tasks, you can use the `--hidden` flag:
+
+```shell
+mise tasks ls --hidden
 ```
 
 ## alias
@@ -180,20 +186,29 @@ 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]
 shell = 'bash -c'
 run = "cargo clippy"
 ```
 
-or use a shebang:
+or use a `shebang`:
 
 ```toml
 [tasks.lint]
@@ -236,9 +251,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 +298,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.
+
+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:

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