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

[jdx]

Summary

Analyzed ~3500 messages from the #mise-help Discord channel to identify recurring questions and pain points that aren't well-covered in the docs.

FAQ additions (docs/faq.md):

• mise install vs mise use — one of the most common points of confusion for newcomers
• latest version semantics — clarifies that latest means latest installed in config, but latest available in commands like mise install and mise x
• mise trust issues — covers accidental ignoring, symlinked configs, non-interactive mode silently skipping untrusted configs
• Ignoring .python-version — documents idiomatic_version_file_disable_tools which people frequently ask about (especially uv users)

Troubleshooting additions (docs/troubleshooting.md):

• redact + raw task interaction — known bug where redacted env vars break raw task output
• mise activate in CI/non-interactive shells — consolidates the workarounds people keep asking about

Tips & Tricks additions (docs/tips-and-tricks.md):

• Namespaced task names — people don't realize they need quoted TOML keys for colons
• Running task dependencies in sequence — wait_for is the answer but people keep asking how to do this
• Using [vars] — the vars section is hard to discover, people keep asking about reusable values in tasks

Test plan

• Verify docs build correctly
• Review wording for accuracy

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk: documentation-only changes that clarify existing CLI behavior and common setup/script issues, with no runtime or API impact.

Overview
Adds several new FAQ entries clarifying common points of confusion: how mise install differs from mise use, how latest resolves depending on command/context, how mise trust/ignored configs can cause configs to be skipped, and how/when idiomatic version files are read.

Improves task docs by calling out that namespaced task keys containing : must be quoted in mise.toml.

Expands troubleshooting with guidance for scripts/CI where tools aren’t found immediately after mise install/use (PATH not updated without a prompt), plus notes on ~/.bash_profile overriding ~/.profile, redact interacting with raw task output, and recommended non-interactive activation approaches (shims/mise exec/hook-env).

^{Reviewed by Cursor Bugbot for commit 6a35c1e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request expands the documentation with new FAQ entries, task configuration tips, and troubleshooting advice for CI environments. Key updates include distinguishing between mise install and mise use, explaining version resolution, and detailing task namespacing and dependencies. Feedback highlights the need to account for platform-specific state directories and to provide more generic environment variable examples for CI systems other than GitHub Actions.

[gemini-code-assist]

The path ~/.local/state/mise/ignored-configs/ assumes the default XDG state directory on Unix-like systems. This path will differ on Windows or if the user has customized MISE_STATE_DIR. It would be more robust to mention that this is the default state directory or suggest using mise doctor to find the actual state path.

[gemini-code-assist]

Option 1 uses $GITHUB_PATH, which is specific to GitHub Actions. For a general troubleshooting guide covering CI environments, it would be beneficial to also provide the standard PATH export used in other systems like GitLab CI or Jenkins.

Suggested change

	```bash
	# Option 1: Use shims (recommended for CI)
	# Option 1: Use shims (recommended for CI)
	# For GitHub Actions:
	echo "$HOME/.local/share/mise/shims" >> $GITHUB_PATH
	# For other CI systems:
	export PATH="$HOME/.local/share/mise/shims:$PATH"

References

1. The product name 'GitLab' must be capitalized as 'GitLab', not 'Gitlab'.

[greptile-apps]

Greptile Summary

This documentation-only PR adds several FAQ and troubleshooting entries to mise's docs, derived from analysis of ~3500 Discord #mise-help messages. The additions cover the most commonly recurring newcomer questions around mise install vs mise use, latest version semantics, config trust issues, idiomatic version files, activation methods, and CI/script usage patterns.

• docs/faq.md: Seven new entries clarifying the install/use distinction, latest resolution context (installed vs. remote), trust/ignored-config issues, idiomatic version file opt-in, a comparison table for activate/shims/exec/env, mise exec usage patterns, mise use write target, and a scope note distinguishing mise from system package managers.
• docs/tasks/running-tasks.md: Adds a tip block explaining that TOML keys with colons must be quoted (e.g., [tasks."test:unit"]), placed immediately after the task namespacing paragraph where it is most relevant.
• docs/troubleshooting.md: Four new sections covering tool-not-found after install in a script (with three resolution strategies), ~/.bash_profile vs ~/.profile conflict on Ubuntu/Debian, the redact + raw task output incompatibility, and recommended approaches for mise activate in CI/non-interactive shells.

Confidence Score: 5/5

Safe to merge — documentation-only changes with no runtime code modifications

All content was verified against the codebase (latest semantics in tool_version.rs, hook-env CLI command, mise use --path flag). No P0 or P1 issues found. Previously flagged P1 concerns (contradictory Wrong/Also right examples, misleading idiomatic files section title) have been resolved. The additions are accurate, well-organized, and directly address documented Discord pain points.

No files require special attention

Important Files Changed

Filename	Overview
docs/faq.md	Adds 7 new FAQ entries; content verified accurate against codebase, previous review concerns (contradictory examples, misleading title) are resolved in the current diff
docs/tasks/running-tasks.md	Adds a well-placed tip block on quoting TOML task keys containing colons
docs/troubleshooting.md	Adds 4 new troubleshooting sections with correct workarounds for script/CI environments, bash_profile conflict, and the known redact+raw limitation

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Q[Need mise-managed tools available?] --> A{Context}
    A -->|Interactive terminal| B[mise activate
in ~/.bashrc / ~/.zshrc]
    A -->|Script or CI| C{Preferred approach}
    A -->|IDE / editor| D[mise activate --shims
or shims on PATH]
    B --> E[PATH updated dynamically
on each prompt]
    D --> F[Shims resolve at invocation
no hooks or env support]
    C -->|Recommended for CI| G[export PATH=~/.local/share/mise/shims:$PATH]
    C -->|Single command| H[mise exec -- command]
    C -->|After install in same script| I[eval $(mise hook-env)]
    G --> J[Tools available for
entire job/session]
    H --> K[Env set up for
one invocation only]
    I --> L[PATH updated immediately
in current shell process]

Loading

_{Reviews (2): Last reviewed commit: "docs: address PR review feedback" | Re-trigger Greptile}

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.4 x -- echo	22.1 ± 0.5	21.3	25.1	1.00
mise x -- echo	22.6 ± 0.4	21.6	24.2	1.02 ± 0.03

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.4 env	21.9 ± 0.8	20.8	27.4	1.00
mise env	22.1 ± 0.4	21.3	23.5	1.01 ± 0.04

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.4 hook-env	22.8 ± 0.6	21.5	24.8	1.00
mise hook-env	22.9 ± 0.4	21.9	24.7	1.00 ± 0.03

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.4.4 ls	19.7 ± 0.4	18.8	22.0	1.00
mise ls	20.1 ± 0.5	19.2	25.2	1.03 ± 0.03

xtasks/test/perf

Command	mise-2026.4.4	mise	Variance
install (cached)	150ms	148ms	+1%
ls (cached)	78ms	78ms	+0%
bin-paths (cached)	82ms	81ms	+1%
task-ls (cached)	820ms	801ms	+2%