[JamBalaya56562]

The problem

not_found_auto_install is documented as only able to install a missing version of a tool that
already has one installed. That stopped being true when the registry gained bins metadata in
#11666 and #11675–#11678.

Measured on v2026.8.3, from an empty data directory, PATH-based (eval "$(mise activate bash)"),
with neither binary present on the system:

$ mise ls --current
ripgrep  14.1.1 (missing)  .../mise.toml  14.1.1
shfmt    3.10.0 (missing)  .../mise.toml  3.10.0

$ shfmt --version
v3.10.0
$ rg --version
ripgrep 14.1.1 (rev 4649aa9700)

Both were installed on first use, and neither had ever been installed. The second case also rules
out name matching: the binary is rg while the tool is ripgrep.

Control — a tool with no registry entry, so no bins:

# "ubi:sharkdp/fd" = "10.2.0", declared and never installed
$ fd --version
bash: command not found: fd     # exit 127, installs dir still absent

So the limitation still exists, but it is a different one: tools mise's registry does not know,
rather than tools never installed. 914 of 956 registry/*.toml files carry bins.

What the code does

install_missing_bin filters list_missing_versions through
REGISTRY.get(short).provides_bin(bin_name) and applies registry override order before falling
back to executable discovery from installed versions — the comment there says so explicitly:
"Registry bin metadata is the only provider signal available before a tool has ever been installed."
src/shims.rs goes through the same function.

The change

Prose only, in the three places that state the old limitation:

• settings.toml — the docs block for not_found_auto_install
• docs/troubleshooting.md — the section, including its heading. It previously led with a
  workaround ("install one version by hand first") that is no longer needed; it is now a short list
  of the reasons the handler genuinely does not fire, with mise x / mise r as the answer for raw
  backend specs.
• docs/dev-tools/index.md — the Limitation bullet

Two claims in that text were checked rather than assumed:

• mise x does install a raw backend spec on demand — mise x -- fd --version with only
  "ubi:sharkdp/fd" = "10.2.0" configured prints ubi:sharkdp/fd@10.2.0 ✓ installed then fd 10.2.0.
• The shim path does not require an interactive terminal, so if the terminal is interactive is
  dropped from that sentence. With stdin and stdout both piped, a shim for a configured-but-missing
  version installs it. src/shims.rs has no interactivity check; the only extra gate is offline
  usage complete-word completion.

No render round-trip

The docs = """…""" field feeds no generated artifact, so mise run render produces no diff:
codegen_settings in build.rs reads only description/env/default/parse_env/
deserialize_with; xtasks/render/schema.ts reads only description; and docs/settings.data.ts
renders props.docs ?? props.description from settings.toml at VitePress build time.

No behaviour changes and no Rust is touched.

Context

Raised while answering #4805, where a user asked whether a
PATH-based setup can install tools on first use. It can — the documentation said otherwise.

Summary by CodeRabbit

• Documentation
  • Clarified automatic installation for missing commands, including configured tools that have never been installed.
  • Documented registry binary metadata requirements and limitations for raw backend specifications.
  • Added guidance for directory-specific configuration, shim behavior, and using mise x or mise r as alternatives.
  • Updated troubleshooting guidance and related settings documentation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: ccefe798-0245-43e6-acd3-512c7541d51a

📥 Commits

Reviewing files that changed from the base of the PR and between 3fa0612 and b56c206.

📒 Files selected for processing (3)

• docs/dev-tools/index.md
• docs/troubleshooting.md
• settings.toml

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/dev-tools/index.md
• settings.toml

---

📝 Walkthrough

Walkthrough

The documentation updates describe registry-based command resolution for command-not-found auto-installation. They document configured-tool requirements, raw backend limitations, configuration scope, shim support, and alternative commands.

Changes

Command-not-found documentation

Layer / File(s)	Summary
Document auto-install behavior docs/dev-tools/index.md, docs/troubleshooting.md, settings.toml	The documentation now describes registry bins metadata, configured-but-uninstalled tools, raw backend limitations, configuration scope, shim support, and alternative commands.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• jdx/mise#11398: Documents configured-tool and registry bins behavior for command-not-found and shim attribution.
• jdx/mise#11666: Documents bins-metadata-based auto-install behavior and its limitations.
• jdx/mise#11668: Documents registry bins metadata and missing-command resolution.

Poem

A rabbit reads the registry bright,
Finds missing tools by bins metadata light.
Raw specs wait for mise x or mise r,
While configured commands hop afar.
Clear docs now guide each troubleshooting trail.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation correction for not-found auto-install behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/troubleshooting.md`:
- Line 393: Update the fallback phrase in the troubleshooting documentation from
“Falling that” to “Failing that,” leaving the rest of the sentence unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 4068be10-6b30-4670-8fb0-740e57879d91

📥 Commits

Reviewing files that changed from the base of the PR and between 6ca9551 and 3fa0612.

📒 Files selected for processing (3)

• docs/dev-tools/index.md
• docs/troubleshooting.md
• settings.toml

[greptile-apps]

Greptile Summary

The PR corrects documentation for command-not-found auto-install behavior and clarifies that registry binary metadata enables first-use installation.

• Explains why raw backend specifications cannot be mapped from command names.
• Recommends mise install or mise x for explicit installation and execution.
• Clarifies that mise run installs configured tools only while running a task.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/dev-tools/index.md	Updates the limitation summary to distinguish registry-backed tools from raw backend specifications.
docs/troubleshooting.md	Replaces the obsolete first-install workaround and accurately qualifies mise run as task-oriented.
settings.toml	Corrects the setting documentation to describe registry bin metadata and non-interactive shim behavior.

_{Reviews (2): Last reviewed commit: "docs: correct what the not-found handler..." | Re-trigger Greptile}