docs(tasks): add bash shebang to conditional-dependencies example

[JamBalaya56562]

Summary

The "Conditional Dependencies" example in docs/tasks/architecture.md
uses bash test syntax inside an inline run block:

[tasks.test]
depends = ["build"]
run = '''
if [ "$1" = "--with-lint" ]; then
  mise run lint
fi
npm test
'''

Without a shebang, mise runs the script under the platform default
inline shell — sh -c -o errexit on Unix, cmd /c on Windows.
cmd cannot parse [ "$1" = ... ], so a Windows host running this
verbatim fails immediately:

[test] $ if [ "$1" = "--with-lint" ]; then
"$1" was unexpected at this time.
[test] ERROR task failed

That happens before the conditional is even evaluated, so the example
is essentially non-functional on Windows as written.

This patch adds #!/usr/bin/env bash to the example so it is portable
across Linux, macOS, and Windows hosts, and follows the recommendation
in docs/tasks/task-configuration.md
to "use a shebang instead" of the shell field.

It also adds a short paragraph pointing readers toward the
usage field for richer argument handling, since positional
parameters in inline run blocks have subtle cross-platform caveats
(see e.g. discussion #9355
about Windows quoting, and the comment at
e2e/tasks/test_task_raw_args:48-50
noting that real positional parameters are only guaranteed for
file-based shebang scripts, not inline TOML scripts).

Verification

Reproduced the failing case and the fix on a fresh mise.toml on
Windows 11 + mise 2026.5.2:

Before (verbatim from current docs, called from PowerShell or bash):

[test] $ if [ "$1" = "--with-lint" ]; then
"$1" was unexpected at this time.
[test] ERROR task failed

After (with the shebang added):

$ mise run test --with-lint
[build] $ echo build done
build done
[test] $ #!/usr/bin/env bash
running lint
running npm test
Finished in 137.5ms

Existing Linux/macOS behavior is unchanged: the shebang takes
precedence over the platform default inline shell, and bash
behaves the same way the previous example assumed.

Scope

Documentation only. No code or test changes.

[greptile-apps]

Greptile Summary

This documentation-only PR fixes the "Conditional Dependencies" example in docs/tasks/architecture.md by adding a #!/usr/bin/env bash shebang to the inline TOML script so it works on Windows (where the default cmd /c shell cannot parse [ ... ] test syntax).

• Adds #!/usr/bin/env bash as the first line of the multi-line run block so mise selects bash over the platform default shell.
• Adds a follow-up paragraph explaining the platform-default-shell behaviour and pointing readers to the usage field for more robust argument handling.

Confidence Score: 5/5

Safe to merge — single doc file change with no code or test impact.

The change is confined to one documentation file and corrects a real cross-platform failure in the example. The shebang placement inside the TOML triple-quoted string is the established pattern used by the very next example in the same file, confirming it is handled correctly by mise.

No files require special attention.

Important Files Changed

Filename	Overview
docs/tasks/architecture.md	Adds #!/usr/bin/env bash shebang to the conditional-dependencies TOML example and adds a short explanatory paragraph about platform behavior and the usage field.

_{Reviews (1): Last reviewed commit: "docs(tasks): add bash shebang to archite..." | Re-trigger Greptile}

[gemini-code-assist]

Code Review

This pull request updates the architecture documentation to include a shebang in task examples, ensuring cross-platform compatibility. It also adds guidance on using the usage field for argument handling. A review comment suggests using relative links instead of site-absolute paths to ensure documentation links function correctly when viewed on GitHub.

[gemini-code-assist]

The link uses a site-absolute path (/tasks/task-arguments) which will not resolve correctly when viewing the documentation on GitHub. Using a relative link to the markdown file ensures that the link works both on the documentation website and when browsing the repository directly.

Suggested change

	[`usage` field](/tasks/task-arguments#usage-field) instead of positional
	[usage field](./task-arguments.md#usage-field) instead of positional

[JamBalaya56562]

Thanks for the review! I'd like to push back on this one — I believe the site-absolute path is actually the established convention in this repo and the suggested change would be inconsistent with the surrounding docs.

A few data points from docs/tasks/:

• docs/tasks/toml-tasks.md already links to the same target with the same anchor in exactly the form this PR uses:

  See the Task Arguments page for complete documentation.

• docs/tasks/file-tasks.md, docs/tasks/task-configuration.md, and docs/tasks/toml-tasks.md all use [Task Arguments](/tasks/task-arguments).
• A quick count under docs/tasks/: 27 site-absolute (/tasks/...) links vs. 0 (./xxx.md) links and 1 (./xxx#anchor) link.

The docs are published via VitePress to mise.jdx.dev, where site-absolute paths resolve correctly without the .md extension; the live site appears to be the canonical browsing target rather than GitHub's markdown viewer.

Given that, I'd prefer to keep the link in the form used elsewhere in this directory so it stays consistent. Happy to change it if a maintainer prefers the relative-path style — in that case it might be worth converting the other 27 occurrences in the same pass for consistency.