Fix shebang recommendation in file-based apps docs

docs/core/sdk/file-based-apps.md

@@ -318,7 +318,7 @@ Enable direct execution of file-based apps on Unix-like systems by using a sheba
 Add a shebang at the top of your file:
 
 ```csharp
-#!/usr/bin/env dotnet
+#!/usr/bin/env -S dotnet --
 #:package Spectre.Console
 
 using Spectre.Console;
@@ -341,6 +341,11 @@ Run directly:
 > [!NOTE]
 > Use `LF` line endings instead of `CRLF` when you add a shebang. Don't include a BOM in the file.
 
+To prevent `dotnet` from consuming arguments that match its own parameters (such as `--help`), the shebang uses `--` as a separator. The `--` separator tells `dotnet` to forward all subsequent command-line arguments directly to your app. The `-S` flag lets `env` split the remaining text into separate arguments so you can include `--` in the shebang.
+
+> [!NOTE]
+> If `-S` isn't supported on your system, use `#!/usr/bin/env dotnet` instead. With this shebang, `dotnet` might consume arguments that match its own CLI parameters.
+
 ## Implicit build files
 
 File-based apps respect MSBuild and NuGet configuration files in the same directory or parent directories. These files affect how the SDK builds your application. Be mindful of these files when organizing your file-based apps.

docs/csharp/fundamentals/tutorials/file-based-programs.md

@@ -10,6 +10,7 @@ ai-usage: ai-assisted
 # Tutorial: Build file-based C# programs
 
 *File-based apps* are programs contained within a single `*.cs` file that you build and run without a corresponding project (`*.csproj`) file. File-based apps are ideal for learning C# because they have less complexity: The entire program is stored in a single file. File-based apps are also useful for building command line utilities. On Unix platforms, you can run file-based apps by using `#!` (shebang) [directives](../../language-reference/preprocessor-directives.md).
+
 In this tutorial, you:
 
 > [!div class="checklist"]
@@ -80,16 +81,13 @@ On Unix, you can execute file-based apps directly using just the source file nam
 1. Add a shebang (`#!`) directive as the first line of the `AsciiArt.cs` file:
 
    ```csharp
-   #!/usr/local/share/dotnet/dotnet
+   #!/usr/bin/env -S dotnet --
    ```
 
-The location of `dotnet` can be different on different Unix installations. Use the command `which dotnet` to locate the `dotnet` host in your environment.
-
-Alternatively, you can use `#!/usr/bin/env dotnet` to resolve the dotnet path from the PATH environment variable automatically:
+   This shebang uses `env` to find `dotnet` in the PATH environment. The `-S` parameter enables `env` to pass `dotnet` and `--` as separate arguments. The `--` ensures that any arguments a user provides are passed directly to your app, preventing `dotnet` from consuming them by mistake.
 
-```csharp
-#!/usr/bin/env dotnet
-```
+   > [!TIP]
+   > If the previous shebang doesn't work, try `#!/usr/bin/env dotnet` or the exact location of `dotnet`, for example `#!/usr/local/share/dotnet/dotnet --`.
 
 After making these two changes, you can run the program directly:
 

docs/csharp/fundamentals/tutorials/snippets/file-based-programs/AsciiArt.cs

@@ -1,4 +1,4 @@
-#!/usr/bin/env dotnet
+#!/usr/bin/env -S dotnet --
 
 // <ColorfulPackage>
 #:package Colorful.Console@1.2.15