diff --git a/docs/tasks/task-arguments.md b/docs/tasks/task-arguments.md
index 3a10e412a7..74748ef4b7 100644
--- a/docs/tasks/task-arguments.md
+++ b/docs/tasks/task-arguments.md
@@ -8,6 +8,8 @@ Task arguments allow you to pass parameters to tasks, making them more flexible
 
 The **usage field** is the recommended approach for defining task arguments. It provides a clean, declarative syntax that works with both TOML tasks and file tasks.
 
+See [Complete Usage Specification Reference](#complete-usage-specification-reference) for more details.
+
 #### Quick Example
 
 ```mise-toml [mise.toml]
@@ -85,6 +87,35 @@ Options:
   -h, --help            Print help
 ```
 
+### 2. File Task Headers {#file-task-headers}
+
+For file tasks, you can define arguments directly in the file using special `#MISE` or `#USAGE` comment syntax:
+
+```bash [.mise/tasks/deploy]
+#!/usr/bin/env bash
+#MISE description "Deploy application"
+#USAGE arg "<environment>" help="Deployment environment" {
+#USAGE   choices "dev" "staging" "prod"
+#USAGE }
+#USAGE flag "--dry-run" help="Preview changes without deploying"
+#USAGE flag "--region <region>" help="AWS region" default="us-east-1" env="AWS_REGION"
+
+ENVIRONMENT="${usage_environment?}"
+REGION="${usage_region?}"
+DRY_RUN="${usage_dry_run:-false}"
+
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "DRY RUN: Would deploy to $ENVIRONMENT in $REGION"
+else
+  echo "Deploying to $ENVIRONMENT in $REGION..."
+  ./scripts/deploy.sh "$ENVIRONMENT" "$REGION"
+fi
+```
+
+::: tip Syntax Options
+Use `#MISE` (uppercase, recommended) or `#USAGE` for defining arguments in file tasks. `# [MISE]` or `# [USAGE]` are also accepted as workarounds for formatters.
+:::
+
 ## Complete Usage Specification Reference
 
 ### Positional Arguments (`arg`)
@@ -398,35 +429,6 @@ fi
 '''
 ```
 
-### 2. File Task Headers {#file-task-headers}
-
-For file tasks, you can define arguments directly in the file using special `#MISE` or `#USAGE` comment syntax:
-
-```bash [.mise/tasks/deploy]
-#!/usr/bin/env bash
-#MISE description "Deploy application"
-#USAGE arg "<environment>" help="Deployment environment" {
-#USAGE   choices "dev" "staging" "prod"
-#USAGE }
-#USAGE flag "--dry-run" help="Preview changes without deploying"
-#USAGE flag "--region <region>" help="AWS region" default="us-east-1" env="AWS_REGION"
-
-ENVIRONMENT="${usage_environment?}"
-REGION="${usage_region?}"
-DRY_RUN="${usage_dry_run:-false}"
-
-if [[ "$DRY_RUN" == "true" ]]; then
-  echo "DRY RUN: Would deploy to $ENVIRONMENT in $REGION"
-else
-  echo "Deploying to $ENVIRONMENT in $REGION..."
-  ./scripts/deploy.sh "$ENVIRONMENT" "$REGION"
-fi
-```
-
-::: tip Syntax Options
-Use `#MISE` (uppercase, recommended) or `#USAGE` for defining arguments in file tasks. `# [MISE]` or `# [USAGE]` are also accepted as workarounds for formatters.
-:::
-
 ## Bash Variable Expansion for Usage Variables {#bash-variable-expansion}
 
 When accessing usage-defined variables in bash scripts, use parameter expansion syntax to help [shellcheck](https://www.shellcheck.net/) understand these variables and provide default values for boolean flags.