My/Pref/Dev/mise/Tasks

• strongly prefer mise/Task/File over mise/Task/TOML
  • put tasks in (~/.config/mise/)tasks/<namespace>/<subnamespace>/<executable_name>, almost never inline TOML [tasks."..."] entries in mise/Config/mise.toml, unless they are one-liners.
  • don't make a scripts/ folder. When a task needs a real program, write the task file itself in that language, such as a Python task with a #!/usr/bin/env -S uv run --script shebang and inline script metadata, rather than a shell task that calls a script kept elsewhere.
• be sure to use usageCLI syntax for defining autocompletion parameters
  • Always annotate file tasks with #MISE description="..." and #USAGE directives (flags, args) for autocompletion via usageCLI. See mise docs: file tasks and mise docs: task arguments.
  • install the usage CLI globally so it is available on PATH — mise use -g usage. It is not required to run tasks, but completions of #USAGE-annotated tasks only work when usage is installed. See mise docs: autocompletion.
  • install mise shell completions into the default shell (zsh) so mise run <tab> completes task names and their usage-defined args. Either use the oh-my-zsh mise plugin, or mise completion zsh > "${fpath[1]}/_mise". See mise docs: completion and usage docs: completions.
• see My/Pref/Dev/mise/Tasks/Discussion for rationelle
• Document named jobs as Logseq/Entity/Mise/Task pages under the topic they serve. Task references describe the interface, outputs, side effects, dependencies, and source; linked how-tos describe the sequence of work.