From e9d9c5c365427bbdb30c527ee68dd51424e2a1aa Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Sat, 2 May 2026 14:56:06 +0000
Subject: [PATCH 1/5] docs: clarify registry backend acceptance policy

Multiple docs gave conflicting signals about which backends are accepted
for new registry entries. Align them on a single policy:

- aqua (preferred) and github are the routinely accepted backends.
- New asdf and vfox plugins are not accepted (supply-chain security).
- ubi is deprecated and is not accepted for new registry entries.
- Other backends (npm, pipx, cargo, gem, go, dotnet, etc.) have a very
  high bar and require prior agreement.

Updates docs/contributing.md (the requirements list now mentions vfox
and ubi, not just asdf), docs/registry.md, and the warning banners in
docs/asdf-legacy-plugins.md and docs/dev-tools/backends/asdf.md (which
previously steered users toward vfox for new tools, contradicting the
registry policy). Also extends CLAUDE.md / AGENTS.md so AI agents apply
the same rules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                       | 12 +++++++++++-
 docs/asdf-legacy-plugins.md     |  4 +++-
 docs/contributing.md            | 12 ++++++++++--
 docs/dev-tools/backends/asdf.md |  4 +++-
 docs/registry.md                |  2 +-
 5 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 79b0f94f57..5e82f5ed15 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,7 +38,17 @@ Before touching `registry/`, ALWAYS do the following:
 5. **If the tool is borderline or numbers are low, warn the user clearly** that the PR is likely to be rejected without reason, and ask if they still want to proceed. Do not soften this — users have repeatedly been surprised when their PR was closed, and the agent should have warned them up front.
 6. **Suggest the alternative:** users can install any tool themselves via explicit backend syntax (`mise use aqua:owner/repo`, `mise use github:owner/repo`, `mise use cargo:name`, `mise use npm:name`, etc.) or by writing a [tool plugin](https://mise.en.dev/tool-plugin-development.html). The registry is *only* for shorthand convenience for popular tools — not for enabling installation.
 
-New asdf plugins are also not accepted; use aqua/github backends.
+### Backend choice: aqua (preferred) or github
+
+For registry entries, **only `aqua:` and `github:` are routinely accepted.** Every other backend (`vfox:`, `asdf:`, `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, `ubi:`, etc.) has an **extremely high** bar — these are rarely accepted into the registry and submitting one without prior agreement from @jdx is almost certain to be rejected.
+
+- **Prefer `aqua:`** when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry). It has better UX, SLSA verification, and per-version logic. This is the recommended default.
+- **Use `github:`** when the tool isn't in the aqua registry but ships GitHub releases.
+- **New `asdf:` plugins are not accepted** — supply-chain security. Use aqua/github instead.
+- **New `vfox:` plugins are not accepted either** — same reason. Use aqua/github instead.
+- **`ubi:` is deprecated and will not be accepted** under any circumstances. Use aqua/github instead.
+- **Do not reach for `npm:`/`pipx:`/`cargo:`/`go:`/etc.** for a registry PR unless the user has explicitly confirmed @jdx wants it that way for this specific tool. Even very popular tools have been rejected when proposed with one of these backends.
+- Users can still install via any backend themselves with explicit syntax (`mise use vfox:...`, `mise use cargo:...`, etc.) — they just don't get a registry shorthand for it.
 
 ## Development Commands
 
diff --git a/docs/asdf-legacy-plugins.md b/docs/asdf-legacy-plugins.md
index 1c9376d44d..68b0eb88e0 100644
--- a/docs/asdf-legacy-plugins.md
+++ b/docs/asdf-legacy-plugins.md
@@ -1,7 +1,9 @@
 # asdf (Legacy) Plugins
 
 ::: warning
-asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules. See the [feature comparison](/dev-tools/backends/asdf.html#feature-comparison-asdf-vs-vfox) and [hook migration table](/dev-tools/backends/asdf.html#hook-migration-asdf-to-vfox) for details.
+asdf plugins are considered legacy. **New asdf and vfox plugins are not accepted into the [mise registry](https://github.com/jdx/mise/blob/main/registry/) for supply-chain security reasons** — for registry submissions use the [aqua](/dev-tools/backends/aqua.html) (preferred) or [github](/dev-tools/backends/github.html) backend instead.
+
+If you are writing a private/custom plugin (not for registry submission), prefer [vfox plugins](/dev-tools/backends/vfox.html) over asdf — they're written in Lua, work cross-platform (including Windows), and have access to built-in modules. See the [feature comparison](/dev-tools/backends/asdf.html#feature-comparison-asdf-vs-vfox) and [hook migration table](/dev-tools/backends/asdf.html#hook-migration-asdf-to-vfox) for details.
 :::
 
 mise maintains compatibility with the asdf plugin ecosystem through its asdf backend. These plugins are considered legacy because they have limitations compared to mise's modern plugin system.
diff --git a/docs/contributing.md b/docs/contributing.md
index ac3e83dbd6..4cb45617be 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -624,13 +624,21 @@ of the full backend specification.
 When adding a new tool, the following requirements apply (automatically
 enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.github/workflows/registry_comment.yml)):
 
-- **New asdf plugins are not accepted** - Use aqua/github instead
+- **New asdf and vfox plugins are not accepted** - Use [aqua](dev-tools/backends/aqua.md)
+  (preferred) or [github](dev-tools/backends/github.md) instead. This is a supply-chain
+  security policy.
+- **The `ubi` backend is deprecated and will not be accepted** for new registry entries.
+  Use aqua/github instead.
+- **Other backends (`npm`, `pipx`, `cargo`, `gem`, `go`, `dotnet`, etc.) have a very high
+  bar** for new registry entries. They are accepted only when no aqua/github option exists
+  and the tool is widely used. Discuss with @jdx before submitting.
 - **A test is required in `registry/`** - Must include a `test` field to
   verify installation
 - **Tools may be rejected if they are not notable** - The tool should be
   reasonably popular and well-maintained. There are no specific guidelines for this and
   a lot of factors are taken into account. @jdx won't explain why a given tool wasn't
-  accepted.
+  accepted. Include a brief popularity summary (stars, downloads, recent release date) in
+  the PR description so the policy can be applied without re-doing the research.
 
 ### Registry Format
 
diff --git a/docs/dev-tools/backends/asdf.md b/docs/dev-tools/backends/asdf.md
index 746f5e76a4..c94ea39201 100644
--- a/docs/dev-tools/backends/asdf.md
+++ b/docs/dev-tools/backends/asdf.md
@@ -1,7 +1,9 @@
 # asdf Backend
 
 ::: warning
-asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules for HTTP, JSON, HTML parsing, and more.
+asdf plugins are considered legacy. **New asdf and vfox plugins are not accepted into the [mise registry](https://github.com/jdx/mise/blob/main/registry/) for supply-chain security reasons** — for registry submissions use the [aqua](/dev-tools/backends/aqua.html) (preferred) or [github](/dev-tools/backends/github.html) backend instead.
+
+If you are writing a private/custom plugin (not for registry submission), prefer [vfox plugins](/dev-tools/backends/vfox.html) over asdf — they're written in Lua, work cross-platform (including Windows), and have access to built-in modules for HTTP, JSON, HTML parsing, and more.
 :::
 
 `asdf` is the original backend for mise.
diff --git a/docs/registry.md b/docs/registry.md
index fa1015912d..4b7b7542ce 100644
--- a/docs/registry.md
+++ b/docs/registry.md
@@ -39,7 +39,7 @@ In general, the preferred [backend](/dev-tools/backends/) to use for new tools i
 - [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires rust to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred.
 - [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires dotnet to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred.
 
-New vfox and asdf tools are almost never accepted for supply-chain security reasons.
+New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead. The `ubi` backend is deprecated and is not accepted for new registry entries.
 
 ### Backends Priority
 

From 472a5e873daf87ef637684cd69de39ee969a7bb7 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Sat, 2 May 2026 15:06:32 +0000
Subject: [PATCH 2/5] docs: note conda backend has a high (but lower) bar for
 registry entries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous docs lumped conda in with npm/cargo/etc. as "almost never
accepted." That's too strict — for tools that genuinely can't be supported
via aqua/github (e.g. conda-native scientific packages only distributed
through conda-forge), conda is the legitimate distribution channel. The
bar is still high, but lower than the language-specific backends.

Updates docs/contributing.md, docs/registry.md, and CLAUDE.md so the
registry policy describes three tiers: aqua/github (preferred), conda
(high bar, but lower), language-specific backends (extremely high bar).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md            | 22 +++++++++++++---------
 docs/contributing.md |  5 +++++
 docs/registry.md     |  1 +
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5e82f5ed15..098854b7c1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,15 +40,19 @@ Before touching `registry/`, ALWAYS do the following:
 
 ### Backend choice: aqua (preferred) or github
 
-For registry entries, **only `aqua:` and `github:` are routinely accepted.** Every other backend (`vfox:`, `asdf:`, `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, `ubi:`, etc.) has an **extremely high** bar — these are rarely accepted into the registry and submitting one without prior agreement from @jdx is almost certain to be rejected.
-
-- **Prefer `aqua:`** when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry). It has better UX, SLSA verification, and per-version logic. This is the recommended default.
-- **Use `github:`** when the tool isn't in the aqua registry but ships GitHub releases.
-- **New `asdf:` plugins are not accepted** — supply-chain security. Use aqua/github instead.
-- **New `vfox:` plugins are not accepted either** — same reason. Use aqua/github instead.
-- **`ubi:` is deprecated and will not be accepted** under any circumstances. Use aqua/github instead.
-- **Do not reach for `npm:`/`pipx:`/`cargo:`/`go:`/etc.** for a registry PR unless the user has explicitly confirmed @jdx wants it that way for this specific tool. Even very popular tools have been rejected when proposed with one of these backends.
-- Users can still install via any backend themselves with explicit syntax (`mise use vfox:...`, `mise use cargo:...`, etc.) — they just don't get a registry shorthand for it.
+For registry entries the backend tiers are:
+
+- **Tier 1 — preferred:** `aqua:` and `github:`. These are the routinely accepted backends.
+  - **Prefer `aqua:`** when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry). Better UX, SLSA verification, and per-version logic.
+  - **Use `github:`** when the tool isn't in aqua but ships GitHub releases.
+- **Tier 2 — high bar, but lower than tier 3:** `conda:`. Potentially acceptable when the tool genuinely can't be supported via aqua/github (e.g. it's a conda-native scientific package only distributed through conda-forge). Still requires a popular, well-maintained tool — but the bar is meaningfully lower than `npm:`/`cargo:`/etc., because for some ecosystems conda is the legitimate distribution channel.
+- **Tier 3 — extremely high bar, almost never accepted:** `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, `dotnet:`. Don't reach for these for a registry PR unless the user has explicitly confirmed @jdx wants it that way for this specific tool. Even very popular tools have been rejected when proposed with one of these backends.
+- **Not accepted at all:**
+  - **New `asdf:` plugins** — supply-chain security. Use aqua/github instead.
+  - **New `vfox:` plugins** — same reason. Use aqua/github instead.
+  - **`ubi:`** is deprecated and will not be accepted under any circumstances.
+
+Users can still install via any backend themselves with explicit syntax (`mise use vfox:...`, `mise use cargo:...`, etc.) — they just don't get a registry shorthand for it.
 
 ## Development Commands
 
diff --git a/docs/contributing.md b/docs/contributing.md
index 4cb45617be..5c6086b7b2 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -629,6 +629,11 @@ enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.git
   security policy.
 - **The `ubi` backend is deprecated and will not be accepted** for new registry entries.
   Use aqua/github instead.
+- **The `conda` backend has a high bar but is potentially accepted** for tools that
+  genuinely cannot be supported via aqua/github — for example, conda-native scientific
+  packages that are only distributed through conda-forge. The bar is lower than
+  `npm`/`cargo`/etc. because for some ecosystems conda is the legitimate distribution
+  channel, but the tool still needs to be popular and well-maintained.
 - **Other backends (`npm`, `pipx`, `cargo`, `gem`, `go`, `dotnet`, etc.) have a very high
   bar** for new registry entries. They are accepted only when no aqua/github option exists
   and the tool is widely used. Discuss with @jdx before submitting.
diff --git a/docs/registry.md b/docs/registry.md
index 4b7b7542ce..8a0cb694d0 100644
--- a/docs/registry.md
+++ b/docs/registry.md
@@ -38,6 +38,7 @@ In general, the preferred [backend](/dev-tools/backends/) to use for new tools i
 - [go](./dev-tools/backends/go.html) - only for go tools, requires go to be installed to compile. Because go tools can be distributed as a single binary, aqua/github are definitely preferred.
 - [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires rust to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred.
 - [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires dotnet to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred.
+- [conda](./dev-tools/backends/conda.html) - potentially accepted (with a high bar, lower than the language-specific backends above) for tools that genuinely cannot be supported via aqua/github, e.g. conda-native scientific packages only distributed through conda-forge.
 
 New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead. The `ubi` backend is deprecated and is not accepted for new registry entries.
 

From 92f598c5fbbfde62237fd3a776ee0259c72158dc Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Sat, 2 May 2026 15:09:47 +0000
Subject: [PATCH 3/5] docs: explain why conda has a lower bar than
 npm/pipx/gem/cargo/go
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous wording leaned on "conda is the legitimate distribution
channel for some ecosystems," but the load-bearing reason is simpler:
mise's conda backend downloads and extracts packages directly from
anaconda.org via rattler — it does not require conda/mamba/micromamba on
PATH.

By contrast, npm/pipx/gem/cargo/go/dotnet all depend on a separately-
installed runtime or toolchain being present on the user's PATH, which is
fragile. npm/pipx/gem in particular silently bind tools to whichever
node/python/ruby was on PATH at install time, which breaks when versions
change or the runtime isn't installed at all.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md            |  4 ++--
 docs/contributing.md | 18 +++++++++++-------
 docs/registry.md     |  2 +-
 3 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 098854b7c1..d06d7dfd4a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,8 +45,8 @@ For registry entries the backend tiers are:
 - **Tier 1 — preferred:** `aqua:` and `github:`. These are the routinely accepted backends.
   - **Prefer `aqua:`** when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry). Better UX, SLSA verification, and per-version logic.
   - **Use `github:`** when the tool isn't in aqua but ships GitHub releases.
-- **Tier 2 — high bar, but lower than tier 3:** `conda:`. Potentially acceptable when the tool genuinely can't be supported via aqua/github (e.g. it's a conda-native scientific package only distributed through conda-forge). Still requires a popular, well-maintained tool — but the bar is meaningfully lower than `npm:`/`cargo:`/etc., because for some ecosystems conda is the legitimate distribution channel.
-- **Tier 3 — extremely high bar, almost never accepted:** `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, `dotnet:`. Don't reach for these for a registry PR unless the user has explicitly confirmed @jdx wants it that way for this specific tool. Even very popular tools have been rejected when proposed with one of these backends.
+- **Tier 2 — high bar, but lower than tier 3:** `conda:`. Potentially acceptable when the tool can't be supported via aqua/github. The bar is lower than tier 3 because **the conda backend in mise does not require a separately-installed package manager** — mise downloads and extracts packages directly from anaconda.org via rattler, so users don't need conda/mamba on PATH. Still requires a popular, well-maintained tool.
+- **Tier 3 — extremely high bar, almost never accepted:** `npm:`, `pipx:`, `gem:`, `cargo:`, `go:`, `dotnet:`. These all rely on a separately-installed runtime/toolchain being present on PATH (`node`, `python`, `ruby`, `cargo`, `go`, `dotnet`), which is fragile — the wrong version, a missing install, or PATH ordering quirks all break them. `npm:`/`pipx:`/`gem:` are particularly painful because tools installed via them silently bind to whichever `node`/`python`/`ruby` was on PATH at install time. Don't reach for these for a registry PR unless the user has explicitly confirmed @jdx wants it that way for this specific tool.
 - **Not accepted at all:**
   - **New `asdf:` plugins** — supply-chain security. Use aqua/github instead.
   - **New `vfox:` plugins** — same reason. Use aqua/github instead.
diff --git a/docs/contributing.md b/docs/contributing.md
index 5c6086b7b2..c5d5a833de 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -630,13 +630,17 @@ enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.git
 - **The `ubi` backend is deprecated and will not be accepted** for new registry entries.
   Use aqua/github instead.
 - **The `conda` backend has a high bar but is potentially accepted** for tools that
-  genuinely cannot be supported via aqua/github — for example, conda-native scientific
-  packages that are only distributed through conda-forge. The bar is lower than
-  `npm`/`cargo`/etc. because for some ecosystems conda is the legitimate distribution
-  channel, but the tool still needs to be popular and well-maintained.
-- **Other backends (`npm`, `pipx`, `cargo`, `gem`, `go`, `dotnet`, etc.) have a very high
-  bar** for new registry entries. They are accepted only when no aqua/github option exists
-  and the tool is widely used. Discuss with @jdx before submitting.
+  cannot be supported via aqua/github. The bar is lower than `npm`/`pipx`/`cargo`/etc.
+  because mise's conda backend downloads and extracts packages directly from
+  anaconda.org — it does not require conda/mamba/micromamba to be installed on the
+  user's PATH. The tool still needs to be popular and well-maintained.
+- **Other backends (`npm`, `pipx`, `gem`, `cargo`, `go`, `dotnet`, etc.) have a very
+  high bar** for new registry entries. These all depend on a separately-installed
+  runtime or toolchain being present on the user's PATH (`node`, `python`, `ruby`,
+  `cargo`, `go`, `dotnet`), which is fragile: tools installed via them silently bind
+  to whichever runtime happens to be on PATH at install time, breaking when versions
+  change or the runtime isn't installed. They are accepted only when no aqua/github
+  option exists and the tool is widely used. Discuss with @jdx before submitting.
 - **A test is required in `registry/`** - Must include a `test` field to
   verify installation
 - **Tools may be rejected if they are not notable** - The tool should be
diff --git a/docs/registry.md b/docs/registry.md
index 8a0cb694d0..9ece604eed 100644
--- a/docs/registry.md
+++ b/docs/registry.md
@@ -38,7 +38,7 @@ In general, the preferred [backend](/dev-tools/backends/) to use for new tools i
 - [go](./dev-tools/backends/go.html) - only for go tools, requires go to be installed to compile. Because go tools can be distributed as a single binary, aqua/github are definitely preferred.
 - [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires rust to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred.
 - [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires dotnet to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred.
-- [conda](./dev-tools/backends/conda.html) - potentially accepted (with a high bar, lower than the language-specific backends above) for tools that genuinely cannot be supported via aqua/github, e.g. conda-native scientific packages only distributed through conda-forge.
+- [conda](./dev-tools/backends/conda.html) - potentially accepted (with a high bar, but lower than the language-specific backends above) for tools that cannot be supported via aqua/github. Unlike `npm`/`pipx`/`gem`/`cargo`/`go`/`dotnet`, mise's conda backend does not require a separately-installed package manager on PATH — packages are fetched and extracted directly from anaconda.org.
 
 New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead. The `ubi` backend is deprecated and is not accepted for new registry entries.
 

From 2f8857b3b7fee525197cc061603024783f631caf Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Sat, 2 May 2026 15:12:13 +0000
Subject: [PATCH 4/5] docs: restructure registry backend policy as explicit
 tiers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Promote the tier framing from CLAUDE.md into the user-facing docs:

- Tier 1 (preferred, routinely accepted): aqua, github, gitlab
- Tier 2 (high bar, but lower than tier 3): conda — does not require a
  separately-installed package manager
- Tier 3 (very high bar, rarely accepted): pipx, npm, gem, go, cargo,
  dotnet — all depend on a runtime/toolchain on PATH
- Not accepted: new asdf/vfox plugins, deprecated ubi

Updates docs/contributing.md and docs/registry.md so contributors see
the same structure the AGENTS.md guidance uses.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/contributing.md | 59 ++++++++++++++++++++++++++++++--------------
 docs/registry.md     | 34 ++++++++++++++++++-------
 2 files changed, 66 insertions(+), 27 deletions(-)

diff --git a/docs/contributing.md b/docs/contributing.md
index c5d5a833de..b37cc638ef 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -624,31 +624,54 @@ of the full backend specification.
 When adding a new tool, the following requirements apply (automatically
 enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.github/workflows/registry_comment.yml)):
 
-- **New asdf and vfox plugins are not accepted** - Use [aqua](dev-tools/backends/aqua.md)
-  (preferred) or [github](dev-tools/backends/github.md) instead. This is a supply-chain
-  security policy.
-- **The `ubi` backend is deprecated and will not be accepted** for new registry entries.
-  Use aqua/github instead.
-- **The `conda` backend has a high bar but is potentially accepted** for tools that
-  cannot be supported via aqua/github. The bar is lower than `npm`/`pipx`/`cargo`/etc.
-  because mise's conda backend downloads and extracts packages directly from
-  anaconda.org — it does not require conda/mamba/micromamba to be installed on the
-  user's PATH. The tool still needs to be popular and well-maintained.
-- **Other backends (`npm`, `pipx`, `gem`, `cargo`, `go`, `dotnet`, etc.) have a very
-  high bar** for new registry entries. These all depend on a separately-installed
-  runtime or toolchain being present on the user's PATH (`node`, `python`, `ruby`,
-  `cargo`, `go`, `dotnet`), which is fragile: tools installed via them silently bind
-  to whichever runtime happens to be on PATH at install time, breaking when versions
-  change or the runtime isn't installed. They are accepted only when no aqua/github
-  option exists and the tool is widely used. Discuss with @jdx before submitting.
 - **A test is required in `registry/`** - Must include a `test` field to
-  verify installation
+  verify installation.
 - **Tools may be rejected if they are not notable** - The tool should be
   reasonably popular and well-maintained. There are no specific guidelines for this and
   a lot of factors are taken into account. @jdx won't explain why a given tool wasn't
   accepted. Include a brief popularity summary (stars, downloads, recent release date) in
   the PR description so the policy can be applied without re-doing the research.
 
+#### Backend acceptance tiers
+
+Which backend you choose for a registry entry matters as much as which tool you
+add. Backends fall into the following tiers:
+
+**Tier 1 — preferred, routinely accepted:** [`aqua`](dev-tools/backends/aqua.md)
+and [`github`](dev-tools/backends/github.md).
+
+- Prefer `aqua` when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry) —
+  it has better UX, SLSA verification, and per-version logic.
+- Use `github` when the tool isn't in aqua but ships GitHub releases.
+
+**Tier 2 — high bar, but lower than tier 3:** [`conda`](dev-tools/backends/conda.md).
+
+Potentially accepted for tools that can't reasonably be supported via aqua/github.
+The bar is lower than tier 3 because **mise's conda backend does not require a
+separately-installed package manager** — packages are downloaded and extracted
+directly from anaconda.org, with no `conda`/`mamba`/`micromamba` needed on the
+user's PATH. The tool still needs to be popular and well-maintained.
+
+**Tier 3 — very high bar, rarely accepted:** `npm`, `pipx`, `gem`, `cargo`, `go`,
+`dotnet`.
+
+These all depend on a separately-installed runtime or toolchain being present on
+the user's PATH (`node`, `python`, `ruby`, `cargo`, `go`, `dotnet`), which is
+fragile — `npm`/`pipx`/`gem` in particular silently bind tools to whichever
+`node`/`python`/`ruby` happened to be on PATH at install time, which breaks when
+versions change or the runtime isn't installed. Accepted only when no aqua/github
+option exists and the tool is widely used. Discuss with @jdx before submitting.
+
+**Not accepted:** `asdf`, `vfox`, `ubi`.
+
+- **New `asdf` plugins** — supply-chain security. Use aqua/github instead.
+- **New `vfox` plugins** — same reason. Use aqua/github instead.
+- **`ubi`** is deprecated and is not accepted for new registry entries.
+
+Users can still install via any backend themselves with explicit syntax
+(`mise use vfox:owner/repo`, `mise use cargo:name`, etc.) — they just don't get
+a registry shorthand for it.
+
 ### Registry Format
 
 The `registry/` file uses this format:
diff --git a/docs/registry.md b/docs/registry.md
index 9ece604eed..75eddfdec3 100644
--- a/docs/registry.md
+++ b/docs/registry.md
@@ -28,19 +28,35 @@ If a tool is not available in the registry, you can install it by its full name.
 
 In addition to built-in [core tools](/core-tools.html), `mise` supports a variety of [backends](/dev-tools/backends/) to install tools.
 
-In general, the preferred [backend](/dev-tools/backends/) to use for new tools is the following:
+Backends fall into the following acceptance tiers for new registry entries:
+
+**Tier 1 — preferred, routinely accepted:**
 
 - [aqua](./dev-tools/backends/aqua.html) - offers the most features and security while not requiring plugins
 - [github](./dev-tools/backends/github.html) - for tools that are not available in the aqua registry, but are available on GitHub
 - [gitlab](./dev-tools/backends/gitlab.html) - for tools that are not available in the aqua registry, but are available on GitLab
-- [pipx](./dev-tools/backends/pipx.html) - only for python tools, requires python to be installed but this generally would always be the case for python tools
-- [npm](./dev-tools/backends/npm.html) - only for node tools, requires node to be installed but this generally would always be the case for node tools
-- [go](./dev-tools/backends/go.html) - only for go tools, requires go to be installed to compile. Because go tools can be distributed as a single binary, aqua/github are definitely preferred.
-- [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires rust to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred.
-- [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires dotnet to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred.
-- [conda](./dev-tools/backends/conda.html) - potentially accepted (with a high bar, but lower than the language-specific backends above) for tools that cannot be supported via aqua/github. Unlike `npm`/`pipx`/`gem`/`cargo`/`go`/`dotnet`, mise's conda backend does not require a separately-installed package manager on PATH — packages are fetched and extracted directly from anaconda.org.
-
-New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead. The `ubi` backend is deprecated and is not accepted for new registry entries.
+
+**Tier 2 — high bar, but lower than tier 3:**
+
+- [conda](./dev-tools/backends/conda.html) - potentially accepted for tools that can't reasonably be supported via aqua/github. The bar is lower than tier 3 because mise's conda backend does not require a separately-installed package manager — packages are fetched and extracted directly from anaconda.org with no `conda`/`mamba`/`micromamba` needed on PATH.
+
+**Tier 3 — very high bar, rarely accepted:**
+
+- [pipx](./dev-tools/backends/pipx.html) - only for python tools, requires `python` on PATH
+- [npm](./dev-tools/backends/npm.html) - only for node tools, requires `node` on PATH
+- [gem](./dev-tools/backends/gem.html) - only for ruby tools, requires `ruby` on PATH
+- [go](./dev-tools/backends/go.html) - only for go tools, requires `go` to be installed to compile. Because go tools can be distributed as a single binary, aqua/github are definitely preferred.
+- [cargo](./dev-tools/backends/cargo.html) - only for rust tools, requires `cargo` to be installed to compile. Because rust tools can be distributed as a single binary, aqua/github are definitely preferred.
+- [dotnet](./dev-tools/backends/dotnet.html) - only for dotnet tools, requires `dotnet` to be installed to compile. Because dotnet tools can be distributed as a single binary, aqua/github are definitely preferred.
+
+These all depend on a separately-installed runtime/toolchain on PATH, which is fragile — `npm`/`pipx`/`gem` in particular silently bind tools to whichever `node`/`python`/`ruby` happened to be on PATH at install time.
+
+**Not accepted:**
+
+- New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead.
+- The `ubi` backend is deprecated and is not accepted for new registry entries.
+
+Users can still install via any backend themselves with explicit syntax (`mise use vfox:owner/repo`, `mise use cargo:name`, etc.) — they just don't get a registry shorthand for it.
 
 ### Backends Priority
 

From 80ad13c435020f21448a34e9724b4234adc11537 Mon Sep 17 00:00:00 2001
From: jdx <216188+jdx@users.noreply.github.com>
Date: Sat, 2 May 2026 15:27:00 +0000
Subject: [PATCH 5/5] =?UTF-8?q?docs:=20address=20review=20feedback=20?=
 =?UTF-8?q?=E2=80=94=20add=20gitlab=20to=20tier=201,=20fix=20link=20format?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add gitlab to Tier 1 in docs/contributing.md and CLAUDE.md so it
  matches docs/registry.md (Greptile finding).
- Convert docs/contributing.md backend links from `dev-tools/backends/X.md`
  to root-relative `/dev-tools/backends/X.html` so they render correctly,
  matching the convention used elsewhere in docs/ (gemini-code-assist
  finding).
- Add aqua/github links in the "Not accepted" section of docs/registry.md
  for parity with the rest of the page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md            | 3 ++-
 docs/contributing.md | 9 +++++----
 docs/registry.md     | 2 +-
 3 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index d06d7dfd4a..2c05ac36c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,9 +42,10 @@ Before touching `registry/`, ALWAYS do the following:
 
 For registry entries the backend tiers are:
 
-- **Tier 1 — preferred:** `aqua:` and `github:`. These are the routinely accepted backends.
+- **Tier 1 — preferred:** `aqua:`, `github:`, and `gitlab:`. These are the routinely accepted backends.
   - **Prefer `aqua:`** when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry). Better UX, SLSA verification, and per-version logic.
   - **Use `github:`** when the tool isn't in aqua but ships GitHub releases.
+  - **Use `gitlab:`** for tools released through GitLab.
 - **Tier 2 — high bar, but lower than tier 3:** `conda:`. Potentially acceptable when the tool can't be supported via aqua/github. The bar is lower than tier 3 because **the conda backend in mise does not require a separately-installed package manager** — mise downloads and extracts packages directly from anaconda.org via rattler, so users don't need conda/mamba on PATH. Still requires a popular, well-maintained tool.
 - **Tier 3 — extremely high bar, almost never accepted:** `npm:`, `pipx:`, `gem:`, `cargo:`, `go:`, `dotnet:`. These all rely on a separately-installed runtime/toolchain being present on PATH (`node`, `python`, `ruby`, `cargo`, `go`, `dotnet`), which is fragile — the wrong version, a missing install, or PATH ordering quirks all break them. `npm:`/`pipx:`/`gem:` are particularly painful because tools installed via them silently bind to whichever `node`/`python`/`ruby` was on PATH at install time. Don't reach for these for a registry PR unless the user has explicitly confirmed @jdx wants it that way for this specific tool.
 - **Not accepted at all:**
diff --git a/docs/contributing.md b/docs/contributing.md
index b37cc638ef..31c5c4b07e 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -637,14 +637,15 @@ enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.git
 Which backend you choose for a registry entry matters as much as which tool you
 add. Backends fall into the following tiers:
 
-**Tier 1 — preferred, routinely accepted:** [`aqua`](dev-tools/backends/aqua.md)
-and [`github`](dev-tools/backends/github.md).
+**Tier 1 — preferred, routinely accepted:** [`aqua`](/dev-tools/backends/aqua.html),
+[`github`](/dev-tools/backends/github.html), and [`gitlab`](/dev-tools/backends/gitlab.html).
 
 - Prefer `aqua` when the tool is in the [aqua registry](https://github.com/aquaproj/aqua-registry) —
   it has better UX, SLSA verification, and per-version logic.
 - Use `github` when the tool isn't in aqua but ships GitHub releases.
+- Use `gitlab` for tools released through GitLab.
 
-**Tier 2 — high bar, but lower than tier 3:** [`conda`](dev-tools/backends/conda.md).
+**Tier 2 — high bar, but lower than tier 3:** [`conda`](/dev-tools/backends/conda.html).
 
 Potentially accepted for tools that can't reasonably be supported via aqua/github.
 The bar is lower than tier 3 because **mise's conda backend does not require a
@@ -664,7 +665,7 @@ option exists and the tool is widely used. Discuss with @jdx before submitting.
 
 **Not accepted:** `asdf`, `vfox`, `ubi`.
 
-- **New `asdf` plugins** — supply-chain security. Use aqua/github instead.
+- **New `asdf` plugins** — supply-chain security. Use [aqua](/dev-tools/backends/aqua.html) or [github](/dev-tools/backends/github.html) instead.
 - **New `vfox` plugins** — same reason. Use aqua/github instead.
 - **`ubi`** is deprecated and is not accepted for new registry entries.
 
diff --git a/docs/registry.md b/docs/registry.md
index 75eddfdec3..7e40c55285 100644
--- a/docs/registry.md
+++ b/docs/registry.md
@@ -53,7 +53,7 @@ These all depend on a separately-installed runtime/toolchain on PATH, which is f
 
 **Not accepted:**
 
-- New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use `aqua` (preferred) or `github` instead.
+- New `vfox` and `asdf` tools are not accepted for supply-chain security reasons — use [`aqua`](./dev-tools/backends/aqua.html) (preferred) or [`github`](./dev-tools/backends/github.html) instead.
 - The `ubi` backend is deprecated and is not accepted for new registry entries.
 
 Users can still install via any backend themselves with explicit syntax (`mise use vfox:owner/repo`, `mise use cargo:name`, etc.) — they just don't get a registry shorthand for it.