docs: clarify common sources of confusion from GitHub discussions

docs/dev-tools/mise-lock.md

@@ -147,6 +147,10 @@ mise settings locked=true
 MISE_LOCKED=1 mise install
 ```
 
+::: warning
+All mise settings are global in scope. Setting `locked = true` in a project's `mise.toml` applies to **all** tool resolution, including tools from your global `~/.config/mise/config.toml`. If you see warnings about global tools missing from the lockfile, run `mise lock -g` to generate a global lockfile.
+:::
+
 When enabled, `mise install` will fail if a tool doesn't have a URL for the current platform in the lockfile. To fix this, first populate the lockfile with URLs:
 
 ```sh

docs/getting-started.md

@@ -16,6 +16,7 @@ curl https://mise.run | sh
 ```
 
 By default, mise installs to `~/.local/bin`, but it can go anywhere.
+
 Verify the installation:
 
 ```shell
@@ -222,6 +223,17 @@ When you ran `mise use --global node@24`, mise updated your global config:
 node = "24"
 ```
 
+### Shell Feature Compatibility {#shell-feature-compatibility}
+
+Not all shells support every mise feature:
+
+| Feature                         | Bash | Zsh | Fish | Nushell | Elvish | Xonsh | PowerShell |
+| ------------------------------- | ---- | --- | ---- | ------- | ------ | ----- | ---------- |
+| `mise activate`                 | Yes  | Yes | Yes  | Yes     | Yes    | Yes   | Yes        |
+| `mise shell`                    | Yes  | Yes | Yes  | Yes     | Yes    | Yes   | Yes        |
+| Shell aliases (`[shell_alias]`) | Yes  | Yes | Yes  | No      | No     | Yes   | No         |
+| `chpwd` hook                    | Yes  | Yes | Yes  | Yes     | Yes    | Yes   | Yes        |
+
 ## 4. Use tools from backends (npm, pipx, core, aqua, github) {#tool-backends}
 
 ```mermaid

docs/shell-aliases.md

@@ -102,6 +102,11 @@ tests = "cd {{config_root}}/tests"
 docs = "cd {{config_root}}/docs"
 ```
 
+## Limitations
+
+- **Not available in tasks**: Shell aliases are only active in interactive shells where `mise activate` is running. They are **not** available inside TOML task `run` blocks or file tasks, since tasks run in non-interactive subshells. Use the underlying command directly in tasks, or add wrapper scripts to your `PATH` via [`env._.path`](/environments/#path).
+- **Shell support**: Only bash, zsh, fish, and xonsh are supported. See the [shell feature compatibility matrix](/getting-started.html#shell-feature-compatibility) for details.
+
 ## Comparison to Tool Aliases
 
 mise has two different alias features that serve different purposes:

docs/tasks/task-configuration.md

@@ -270,7 +270,11 @@ run = "echo my internal task"
 - **Type**: `string`
 
 A message to show before running the task. This is useful for tasks that are destructive or take a long
-time to run. The user will be prompted to confirm before the task is run.
+time to run. The user will be prompted to confirm before the task's own `run` command executes.
+
+::: warning
+`confirm` only guards the task's own `run` command. Dependencies (`depends`) will execute **before** the confirmation prompt appears. If you need confirmation before dependencies run, add `confirm` to the dependency tasks themselves, or use `run = [{ task = "..." }]` instead of `depends`.
+:::
 
 ```mise-toml
 [tasks.release]

schema/mise.json

@@ -1512,7 +1512,7 @@
               "type": "boolean"
             },
             "timeout": {
-              "description": "Default timeout for tasks. Can be overridden by individual tasks.",
+              "description": "Default timeout for tasks.",
               "type": "string"
             },
             "timings": {

settings.toml

@@ -2054,7 +2054,14 @@ env = "MISE_TASK_SOURCE_FRESHNESS_HASH_CONTENTS"
 type = "Bool"
 
 [task.timeout]
-description = "Default timeout for tasks. Can be overridden by individual tasks."
+description = "Default timeout for tasks."
+docs = """
+Sets a global default timeout for all tasks. Individual tasks can also specify their own `timeout`.
+
+When both a global timeout and a per-task timeout are set, the **shorter** of the two always wins—a
+per-task timeout cannot extend beyond the global timeout. The `--timeout` CLI flag overrides this
+global setting.
+"""
 env = "MISE_TASK_TIMEOUT"
 optional = true
 type = "Duration"