docs: add FAQ and troubleshooting entries based on common Discord questions

docs/faq.md

@@ -204,6 +204,76 @@ In VSCode, many extensions will throw an "error spawn EINVAL" due to a [Node.js
 
 The default `exe` shim mode should resolve this. If you're using an older mode, you can change [windows_shim_mode](https://mise.jdx.dev/configuration/settings.html#windows_shim_mode) to `exe`, `hardlink`, or `symlink`.
 
+## What is the difference between `mise install` and `mise use`?
+
+`mise install` downloads and installs a tool version but does **not** add it to any config file.
+The tool won't be automatically activated in your shell unless it's already listed in a `mise.toml` or `.tool-versions`.
+
+`mise use` installs the tool **and** adds it to `mise.toml` (or `~/.config/mise/config.toml` with `-g`), so it will be activated
+automatically when you enter the directory.
+
+If you just want to pin a tool for a project, use `mise use`. If you want to install
+a version that's already listed in config, use `mise install`.
+
+::: tip
+`mise install node` (with no version) will install the **latest** version if node isn't in your config.
+`mise install` (with no arguments) installs only the tools listed in your config files.
+:::
+
+## Does `latest` mean the newest remote version?
+
+It depends on context. In config files and most commands, `latest` resolves to the latest
+**installed** version. This means if you have node 20.0.0 installed and node 22.0.0 is
+available remotely, `latest` will still point to 20.0.0.
+
+However, some commands resolve `latest` to the newest **available** (remote) version:
+
+- `mise install node@latest` — installs the newest available version
+- `mise x node@latest -- node -v` — uses the newest available version
+- `mise latest node` — shows the newest available version
+
+To upgrade to the newest available version and update your config, run:
+
+```sh
+mise upgrade node
+# or to also update mise.toml:
+mise upgrade --bump node
+```
+
+## My config file is being ignored / `mise trust` issues
+
+mise requires you to trust config files that were not created by you. Common issues:
+
+- **Accidentally denied trust**: If mise prompted you to trust a file and you said no, it gets
+  added to the ignore list. Check `ls ~/.local/state/mise/ignored-configs/` and remove the
+  relevant symlink to un-ignore it.
+- **Symlinked configs**: If your config is symlinked (e.g., via GNU Stow), mise may track the
+  symlink target path. Try `mise trust` pointing to the actual file path.
+- **Non-interactive mode**: In non-interactive shells (CI, IDE extensions, scripts), mise will
+  silently skip untrusted configs. Either run `mise trust` beforehand or set
+  [`trusted_config_paths`](/configuration/settings.html#trusted_config_paths) in your global settings.
+- **Global config** (`~/.config/mise/config.toml`) should be auto-trusted. If it's not, run
+  `mise trust ~/.config/mise/config.toml` explicitly.
+
+Run `mise doctor` (`mise dr`) to see if any config files are untrusted — it will list them
+under "problems".
+
+## How do I ignore `.python-version` or other idiomatic version files?
+
+Idiomatic version files (`.python-version`, `.node-version`, `.ruby-version`, etc.) are
+**disabled by default** in mise. They are only read if you explicitly opt in per tool using
+[`idiomatic_version_file_enable_tools`](/configuration/settings.html#idiomatic_version_file_enable_tools):
+
+```sh
+# Enable reading .node-version files
+mise settings add idiomatic_version_file_enable_tools node
+```
+
+If you previously enabled idiomatic files and now want to stop mise from reading them
+(e.g., because `uv` manages `.python-version`), simply don't add that tool to the list.
+
+See [Idiomatic Version Files](/configuration.html#idiomatic-version-files) for more information.
+
 ## How does mise versioning work?
 
 mise uses [Calver](https://calver.org/) versioning (`2024.1.0`).

docs/tips-and-tricks.md

@@ -244,6 +244,51 @@ Path                                    Tools
 
 This is helpful figuring out which order the config files are loaded in to figure out which one is overriding.
 
+## Task tips
+
+### Namespaced task names
+
+Use colons to namespace tasks. Since TOML keys can't contain colons without quoting, use quoted keys:
+
+```toml
+[tasks."packages:build"]
+run = 'echo building packages'
+
+[tasks."packages:clean"]
+run = 'echo cleaning packages'
+```
+
+Then run with `mise run packages:build`.
+
+### Running task dependencies in sequence
+
+By default, task dependencies run in parallel. To enforce ordering, use `wait_for`:
+
+```toml
+[tasks.clean]
+run = 'rm -rf dist'
+
+[tasks.build]
+wait_for = ['clean']  # wait for clean to finish before starting
+run = 'cargo build'
+
+[tasks.test]
+depends = ['clean', 'build']  # both are dependencies, but build waits for clean
+run = 'cargo test'
+```
+
+### Using variables in tasks
+
+The [`[vars]`](/tasks/task-configuration.html#vars) section lets you define reusable values for tasks:
+
+```toml
+[vars]
+docker_cmd = 'docker run --rm -v "$(pwd):/data" pandoc/extra'
+
+[tasks.build-pdf]
+run = '{{vars.docker_cmd}} input.md -o output.pdf'
+```
+
 ## `mise.lock`
 
 When lockfiles are enabled, mise will update `mise.lock` with full versions and tarball checksums (if supported by the backend).

docs/troubleshooting.md

@@ -165,6 +165,35 @@ common running mise in a CI environment like GitHub Actions.
 
 See [GitHub Tokens](/dev-tools/github-tokens.html) for how to configure authentication and avoid rate limits.
 
+## Tasks with `redact` env vars break `raw` output
+
+If you have `redact = true` on any env var in your config, tasks with `raw = true` will appear
+to produce no output. This is because mise intercepts stdout/stderr to perform redaction, which
+conflicts with raw mode.
+
+**Workaround**: Remove `redact` from env vars that don't need it, or accept that raw tasks
+won't produce visible output when redactions are active.
+
+## `mise activate` in CI / non-interactive shells
+
+`mise activate` hooks into the shell prompt to update PATH, so historically it didn't work
+in non-interactive shells. With the addition of `chpwd` support, it does work in more
+situations now, but we still recommend these approaches for CI and scripts:
+
+```bash
+# Option 1: Use shims (recommended for CI)
+echo "$HOME/.local/share/mise/shims" >> $GITHUB_PATH
+
+# Option 2: Use mise exec
+mise exec -- npm test
+
+# Option 3: Manually call hook-env after activate
+eval "$(mise activate bash)"
+eval "$(mise hook-env)"
+```
+
+See also the [CI/CD section](/tips-and-tricks.html#ci-cd) in Tips & Tricks.
+
 ## Auto-install on command not found handler does not work for new tools
 
 If you are expecting mise to automatically install a tool when you run a command that is not found (using the [`not_found_auto_install`](/configuration/settings.html#not_found_auto_install) feature), be aware of an important limitation: