docs: add documentation URL structure guidance to CLAUDE.md#7740
Merged
Conversation
Add a new Documentation section with URL structure guidance to prevent incorrect URL generation. Claude was generating URLs like `mise.jdx.dev/backends/s3.html` instead of the correct `mise.jdx.dev/dev-tools/backends/s3.html`. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds documentation URL structure guidance to CLAUDE.md to prevent Claude from generating incorrect documentation URLs. The guidance ensures that Claude uses the correct path structure that matches the actual docs/ directory layout, with examples of the proper format for different documentation sections.
Changes:
- Added a new "Documentation" section with URL structure guidelines
- Specified correct path patterns for dev tools/backends, configuration, tasks, environments, and CLI reference
- Explicitly warned against using shortened paths
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Hyperfine Performance
|
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.1.4 x -- echo |
21.1 ± 0.3 | 20.2 | 23.8 | 1.00 |
mise x -- echo |
22.2 ± 0.6 | 21.0 | 29.7 | 1.05 ± 0.03 |
mise env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.1.4 env |
20.7 ± 0.5 | 19.8 | 25.2 | 1.00 |
mise env |
21.5 ± 0.4 | 20.5 | 22.8 | 1.04 ± 0.03 |
mise hook-env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.1.4 hook-env |
20.9 ± 0.6 | 19.8 | 27.8 | 1.00 |
mise hook-env |
21.9 ± 0.4 | 20.5 | 23.4 | 1.05 ± 0.04 |
mise ls
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2026.1.4 ls |
19.6 ± 0.5 | 18.6 | 24.1 | 1.00 |
mise ls |
20.6 ± 0.6 | 19.7 | 28.5 | 1.05 ± 0.04 |
xtasks/test/perf
| Command | mise-2026.1.4 | mise | Variance |
|---|---|---|---|
| install (cached) | 116ms | 118ms | -1% |
| ls (cached) | 69ms | 71ms | -2% |
| bin-paths (cached) | 73ms | 75ms | -2% |
| task-ls (cached) | 289ms | 299ms | -3% |
jdx
pushed a commit
that referenced
this pull request
Jan 19, 2026
### 🚀 Features - **(complete)** add PowerShell completion support by @jdx in [#7746](#7746) - **(release)** add LLM-generated prose summary to release notes by @jdx in [#7737](#7737) - **(vfox)** add semver Lua module for version sorting by @jdx in [#7739](#7739) - **(vfox)** add rolling release support with checksum tracking by @jdx in [#7757](#7757) - dry filetask parsing and validation by @makp0 in [#7738](#7738) ### 🐛 Bug Fixes - **(completions)** bump usage-cli to 2.13.1 for PowerShell support by @jdx in [#7756](#7756) - schema missing env required string variant by @vadimpiven in [#7734](#7734) - validate unknown fields in filetask headers by @makp0 in [#7733](#7733) - disable schemacrawler test by @jdx in [#7743](#7743) - replace double forward slash with single slash in get_task_lists by @collinstevens in [#7744](#7744) - require LLM for release notes and include aqua section by @jdx in [#7745](#7745) - preserve {{ version }} in tool options during config load by @jdx in [#7755](#7755) ### 📚 Documentation - add documentation URL structure guidance to CLAUDE.md by @jdx in [#7740](#7740) - add pitchfork promotion by @jdx in [#7747](#7747) ### 📦️ Dependency Updates - relax version constraints and update dependencies by @jdx in [#7736](#7736) - lock file maintenance by @renovate[bot] in [#7749](#7749) ### Chore - bump xx to 2.3.1 by @jdx in [#7753](#7753) ### New Contributors - @collinstevens made their first contribution in [#7744](#7744) - @makp0 made their first contribution in [#7738](#7738) - @vadimpiven made their first contribution in [#7734](#7734) ## 📦 Aqua Registry Updates #### New Packages (2) - [`F1bonacc1/process-compose`](https://github.com/F1bonacc1/process-compose) - [`kkinnear/zprint`](https://github.com/kkinnear/zprint) #### Updated Packages (1) - [`theryangeary/choose`](https://github.com/theryangeary/choose)
netbsd-srcmastr
pushed a commit
to NetBSD/pkgsrc
that referenced
this pull request
Jan 22, 2026
## [2026.1.5](https://github.com/jdx/mise/compare/v2026.1.4..v2026.1.5) - 2026-01-19 ### 🚀 Features - **(complete)** add PowerShell completion support by @jdx in [#7746](jdx/mise#7746) - **(release)** add LLM-generated prose summary to release notes by @jdx in [#7737](jdx/mise#7737) - **(vfox)** add semver Lua module for version sorting by @jdx in [#7739](jdx/mise#7739) - **(vfox)** add rolling release support with checksum tracking by @jdx in [#7757](jdx/mise#7757) - dry filetask parsing and validation by @makp0 in [#7738](jdx/mise#7738) ### 🐛 Bug Fixes - **(completions)** bump usage-cli to 2.13.1 for PowerShell support by @jdx in [#7756](jdx/mise#7756) - schema missing env required string variant by @vadimpiven in [#7734](jdx/mise#7734) - validate unknown fields in filetask headers by @makp0 in [#7733](jdx/mise#7733) - disable schemacrawler test by @jdx in [#7743](jdx/mise#7743) - replace double forward slash with single slash in get_task_lists by @collinstevens in [#7744](jdx/mise#7744) - require LLM for release notes and include aqua section by @jdx in [#7745](jdx/mise#7745) - preserve {{ version }} in tool options during config load by @jdx in [#7755](jdx/mise#7755) ### 📚 Documentation - add documentation URL structure guidance to CLAUDE.md by @jdx in [#7740](jdx/mise#7740) - add pitchfork promotion by @jdx in [#7747](jdx/mise#7747) ### 📦️ Dependency Updates - relax version constraints and update dependencies by @jdx in [#7736](jdx/mise#7736) - lock file maintenance by @renovate[bot] in [#7749](jdx/mise#7749) ### Chore - bump xx to 2.3.1 by @jdx in [#7753](jdx/mise#7753) ### New Contributors - @collinstevens made their first contribution in [#7744](jdx/mise#7744) - @makp0 made their first contribution in [#7738](jdx/mise#7738) - @vadimpiven made their first contribution in [#7734](jdx/mise#7734) ## [2026.1.4](https://github.com/jdx/mise/compare/v2026.1.3..v2026.1.4) - 2026-01-17 ### 🚀 Features - **(conda)** add dependency locking for reproducible installations by @jdx in [#7708](jdx/mise#7708) - **(http)** add JSON filter syntax for version extraction by @jdx in [#7707](jdx/mise#7707) - **(http)** add version_expr support and Tera templating by @jdx in [#7723](jdx/mise#7723) - **(task)** add [monorepo].config_roots for explicit config root listing by @jdx in [#7705](jdx/mise#7705) - **(task)** support env vars in task dependencies by @jdx in [#7724](jdx/mise#7724) ### 🐛 Bug Fixes - **(conda)** fix hardcoded library paths in conda packages by @jdx in [#7713](jdx/mise#7713) - **(env)** avoid venv/go backend deadlock during env resolution by @stk0vrfl0w in [#7696](jdx/mise#7696) - **(locked)** exempt tool stubs from lockfile requirements by @jdx in [#7729](jdx/mise#7729) - **(python)** sort CPython versions at end of ls-remote output by @jdx in [#7721](jdx/mise#7721) - **(task)** resolve remote task files before display and validation commands by @yannrouillard in [#7681](jdx/mise#7681) - **(task)** support monorepo paths in `mise tasks deps` by @chadxz in [#7699](jdx/mise#7699) - **(task)** resolve all monorepo path hints in deps by @chadxz in [#7698](jdx/mise#7698) ### 📚 Documentation - remove outdated roadmap page by @jdx in [#7726](jdx/mise#7726) ### ⚡ Performance - **(task)** fix task-ls cached performance regression by @jdx in [#7716](jdx/mise#7716) ### 📦️ Dependency Updates - replace dependency @tsconfig/node22 with @tsconfig/node24 by @renovate[bot] in [#7618](jdx/mise#7618) ### 📦 Registry - add aqua backend for smithy by @jdx in [#7661](jdx/mise#7661) - remove low-usage asdf plugins by @jdx in [#7701](jdx/mise#7701) - disable mirrord test by @jdx in [#7703](jdx/mise#7703) - use vfox-dotnet as default backend by @jdx in [#7704](jdx/mise#7704) - use vfox-lua as default lua backend by @jdx in [#7706](jdx/mise#7706) - add vfox backend for redis by @jdx in [#7709](jdx/mise#7709) - use vfox-postgres as default postgres backend by @jdx in [#7710](jdx/mise#7710) - use github backend for kotlin by @jdx in [#7711](jdx/mise#7711) - add vfox backend for leiningen by @jdx in [#7714](jdx/mise#7714) - use pipx backend for meson by @jdx in [#7712](jdx/mise#7712) - use github backend for crystal by @jdx in [#7715](jdx/mise#7715) - use conda backend for sqlite by @jdx in [#7718](jdx/mise#7718) - use conda backend for make by @jdx in [#7719](jdx/mise#7719) - swift-package-list use github backend by @jdx in [#7720](jdx/mise#7720) ### Chore - increase macos release build timeout to 90 minutes by @jdx in [#7725](jdx/mise#7725) ### New Contributors - @yannrouillard made their first contribution in [#7681](jdx/mise#7681) - @stk0vrfl0w made their first contribution in [#7696](jdx/mise#7696) ## [2026.1.3](https://github.com/jdx/mise/compare/v2026.1.2..v2026.1.3) - 2026-01-16 ### 🚀 Features - **(s3)** add S3 backend for private artifact storage by @jdx in [#7668](jdx/mise#7668) - **(upgrade)** use installed_tool completer for mise upgrade by @jdx in [#7670](jdx/mise#7670) - **(upgrade)** add --exclude flag to mise upgrade command by @jdx in [#7669](jdx/mise#7669) - add no hooks and no env flags by @aacebedo in [#7560](jdx/mise#7560) ### 🐛 Bug Fixes - **(backend)** allow upgrading vfox backend tools with symlinked installations by @TyceHerrman in [#7012](jdx/mise#7012) - **(backend)** reject architecture mismatches in asset selection by @jdx in [#7672](jdx/mise#7672) - **(backend)** canonicalize symlink target before installs check by @jdx in [#7671](jdx/mise#7671) - **(npm)** avoid circular dependency when npm is in dependencies by @AprilNEA in [#7644](jdx/mise#7644) - **(self-update)** skip update when already at latest version by @jdx in [#7666](jdx/mise#7666) - fall back to GITHUB_TOKEN for github.com by @subdigital in [#7667](jdx/mise#7667) - GitHub token fallback by @subdigital in [#7673](jdx/mise#7673) - inherit tasks from parent configs in monorepos by @chadxz in [#7643](jdx/mise#7643) ### 📚 Documentation - **(contributing)** update registry examples by @scop in [#7660](jdx/mise#7660) - **(contributing)** update registry PR title rule by @scop in [#7663](jdx/mise#7663) - remove 404 link from contributing by @opswole in [#7692](jdx/mise#7692) - clarify that backend plugins should sort the version list by @ofalvai in [#7680](jdx/mise#7680) ### 📦️ Dependency Updates - update ghcr.io/jdx/mise:alpine docker digest to 11f659e by @renovate[bot] in [#7685](jdx/mise#7685) - update ghcr.io/jdx/mise:copr docker digest to 3adaea4 by @renovate[bot] in [#7686](jdx/mise#7686) - update ghcr.io/jdx/mise:deb docker digest to 8bbca53 by @renovate[bot] in [#7687](jdx/mise#7687) - update ghcr.io/jdx/mise:rpm docker digest to de81415 by @renovate[bot] in [#7688](jdx/mise#7688) - update mcr.microsoft.com/devcontainers/rust:1 docker digest to 282e805 by @renovate[bot] in [#7690](jdx/mise#7690) - update rust docker digest to bed2d7f by @renovate[bot] in [#7691](jdx/mise#7691) ### 📦 Registry - add oh-my-posh by @scop in [#7659](jdx/mise#7659) - add bibtex-tidy (npm:bibtex-tidy) by @3w36zj6 in [#7677](jdx/mise#7677) - remove misconfigured bin_path option from kscript by @risu729 in [#7693](jdx/mise#7693) ### New Contributors - @AprilNEA made their first contribution in [#7644](jdx/mise#7644) - @opswole made their first contribution in [#7692](jdx/mise#7692) - @subdigital made their first contribution in [#7673](jdx/mise#7673) - @aacebedo made their first contribution in [#7560](jdx/mise#7560)
netbsd-srcmastr
pushed a commit
to NetBSD/pkgsrc
that referenced
this pull request
Jan 25, 2026
## [2026.1.5](https://github.com/jdx/mise/compare/v2026.1.4..v2026.1.5) - 2026-01-19 ### 🚀 Features - **(complete)** add PowerShell completion support by @jdx in [#7746](jdx/mise#7746) - **(release)** add LLM-generated prose summary to release notes by @jdx in [#7737](jdx/mise#7737) - **(vfox)** add semver Lua module for version sorting by @jdx in [#7739](jdx/mise#7739) - **(vfox)** add rolling release support with checksum tracking by @jdx in [#7757](jdx/mise#7757) - dry filetask parsing and validation by @makp0 in [#7738](jdx/mise#7738) ### 🐛 Bug Fixes - **(completions)** bump usage-cli to 2.13.1 for PowerShell support by @jdx in [#7756](jdx/mise#7756) - schema missing env required string variant by @vadimpiven in [#7734](jdx/mise#7734) - validate unknown fields in filetask headers by @makp0 in [#7733](jdx/mise#7733) - disable schemacrawler test by @jdx in [#7743](jdx/mise#7743) - replace double forward slash with single slash in get_task_lists by @collinstevens in [#7744](jdx/mise#7744) - require LLM for release notes and include aqua section by @jdx in [#7745](jdx/mise#7745) - preserve {{ version }} in tool options during config load by @jdx in [#7755](jdx/mise#7755) ### 📚 Documentation - add documentation URL structure guidance to CLAUDE.md by @jdx in [#7740](jdx/mise#7740) - add pitchfork promotion by @jdx in [#7747](jdx/mise#7747) ### 📦️ Dependency Updates - relax version constraints and update dependencies by @jdx in [#7736](jdx/mise#7736) - lock file maintenance by @renovate[bot] in [#7749](jdx/mise#7749) ### Chore - bump xx to 2.3.1 by @jdx in [#7753](jdx/mise#7753) ### New Contributors - @collinstevens made their first contribution in [#7744](jdx/mise#7744) - @makp0 made their first contribution in [#7738](jdx/mise#7738) - @vadimpiven made their first contribution in [#7734](jdx/mise#7734) ## [2026.1.4](https://github.com/jdx/mise/compare/v2026.1.3..v2026.1.4) - 2026-01-17 ### 🚀 Features - **(conda)** add dependency locking for reproducible installations by @jdx in [#7708](jdx/mise#7708) - **(http)** add JSON filter syntax for version extraction by @jdx in [#7707](jdx/mise#7707) - **(http)** add version_expr support and Tera templating by @jdx in [#7723](jdx/mise#7723) - **(task)** add [monorepo].config_roots for explicit config root listing by @jdx in [#7705](jdx/mise#7705) - **(task)** support env vars in task dependencies by @jdx in [#7724](jdx/mise#7724) ### 🐛 Bug Fixes - **(conda)** fix hardcoded library paths in conda packages by @jdx in [#7713](jdx/mise#7713) - **(env)** avoid venv/go backend deadlock during env resolution by @stk0vrfl0w in [#7696](jdx/mise#7696) - **(locked)** exempt tool stubs from lockfile requirements by @jdx in [#7729](jdx/mise#7729) - **(python)** sort CPython versions at end of ls-remote output by @jdx in [#7721](jdx/mise#7721) - **(task)** resolve remote task files before display and validation commands by @yannrouillard in [#7681](jdx/mise#7681) - **(task)** support monorepo paths in `mise tasks deps` by @chadxz in [#7699](jdx/mise#7699) - **(task)** resolve all monorepo path hints in deps by @chadxz in [#7698](jdx/mise#7698) ### 📚 Documentation - remove outdated roadmap page by @jdx in [#7726](jdx/mise#7726) ### ⚡ Performance - **(task)** fix task-ls cached performance regression by @jdx in [#7716](jdx/mise#7716) ### 📦️ Dependency Updates - replace dependency @tsconfig/node22 with @tsconfig/node24 by @renovate[bot] in [#7618](jdx/mise#7618) ### 📦 Registry - add aqua backend for smithy by @jdx in [#7661](jdx/mise#7661) - remove low-usage asdf plugins by @jdx in [#7701](jdx/mise#7701) - disable mirrord test by @jdx in [#7703](jdx/mise#7703) - use vfox-dotnet as default backend by @jdx in [#7704](jdx/mise#7704) - use vfox-lua as default lua backend by @jdx in [#7706](jdx/mise#7706) - add vfox backend for redis by @jdx in [#7709](jdx/mise#7709) - use vfox-postgres as default postgres backend by @jdx in [#7710](jdx/mise#7710) - use github backend for kotlin by @jdx in [#7711](jdx/mise#7711) - add vfox backend for leiningen by @jdx in [#7714](jdx/mise#7714) - use pipx backend for meson by @jdx in [#7712](jdx/mise#7712) - use github backend for crystal by @jdx in [#7715](jdx/mise#7715) - use conda backend for sqlite by @jdx in [#7718](jdx/mise#7718) - use conda backend for make by @jdx in [#7719](jdx/mise#7719) - swift-package-list use github backend by @jdx in [#7720](jdx/mise#7720) ### Chore - increase macos release build timeout to 90 minutes by @jdx in [#7725](jdx/mise#7725) ### New Contributors - @yannrouillard made their first contribution in [#7681](jdx/mise#7681) - @stk0vrfl0w made their first contribution in [#7696](jdx/mise#7696) ## [2026.1.3](https://github.com/jdx/mise/compare/v2026.1.2..v2026.1.3) - 2026-01-16 ### 🚀 Features - **(s3)** add S3 backend for private artifact storage by @jdx in [#7668](jdx/mise#7668) - **(upgrade)** use installed_tool completer for mise upgrade by @jdx in [#7670](jdx/mise#7670) - **(upgrade)** add --exclude flag to mise upgrade command by @jdx in [#7669](jdx/mise#7669) - add no hooks and no env flags by @aacebedo in [#7560](jdx/mise#7560) ### 🐛 Bug Fixes - **(backend)** allow upgrading vfox backend tools with symlinked installations by @TyceHerrman in [#7012](jdx/mise#7012) - **(backend)** reject architecture mismatches in asset selection by @jdx in [#7672](jdx/mise#7672) - **(backend)** canonicalize symlink target before installs check by @jdx in [#7671](jdx/mise#7671) - **(npm)** avoid circular dependency when npm is in dependencies by @AprilNEA in [#7644](jdx/mise#7644) - **(self-update)** skip update when already at latest version by @jdx in [#7666](jdx/mise#7666) - fall back to GITHUB_TOKEN for github.com by @subdigital in [#7667](jdx/mise#7667) - GitHub token fallback by @subdigital in [#7673](jdx/mise#7673) - inherit tasks from parent configs in monorepos by @chadxz in [#7643](jdx/mise#7643) ### 📚 Documentation - **(contributing)** update registry examples by @scop in [#7660](jdx/mise#7660) - **(contributing)** update registry PR title rule by @scop in [#7663](jdx/mise#7663) - remove 404 link from contributing by @opswole in [#7692](jdx/mise#7692) - clarify that backend plugins should sort the version list by @ofalvai in [#7680](jdx/mise#7680) ### 📦️ Dependency Updates - update ghcr.io/jdx/mise:alpine docker digest to 11f659e by @renovate[bot] in [#7685](jdx/mise#7685) - update ghcr.io/jdx/mise:copr docker digest to 3adaea4 by @renovate[bot] in [#7686](jdx/mise#7686) - update ghcr.io/jdx/mise:deb docker digest to 8bbca53 by @renovate[bot] in [#7687](jdx/mise#7687) - update ghcr.io/jdx/mise:rpm docker digest to de81415 by @renovate[bot] in [#7688](jdx/mise#7688) - update mcr.microsoft.com/devcontainers/rust:1 docker digest to 282e805 by @renovate[bot] in [#7690](jdx/mise#7690) - update rust docker digest to bed2d7f by @renovate[bot] in [#7691](jdx/mise#7691) ### 📦 Registry - add oh-my-posh by @scop in [#7659](jdx/mise#7659) - add bibtex-tidy (npm:bibtex-tidy) by @3w36zj6 in [#7677](jdx/mise#7677) - remove misconfigured bin_path option from kscript by @risu729 in [#7693](jdx/mise#7693) ### New Contributors - @AprilNEA made their first contribution in [#7644](jdx/mise#7644) - @opswole made their first contribution in [#7692](jdx/mise#7692) - @subdigital made their first contribution in [#7673](jdx/mise#7673) - @aacebedo made their first contribution in [#7560](jdx/mise#7560)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mise.jdx.dev/backends/s3.htmlinstead of the correctmise.jdx.dev/dev-tools/backends/s3.htmlTest plan
docs/directory structure🤖 Generated with Claude Code
Note
Adds a new documentation section in
CLAUDE.mddetailing correct mise docs URL structure and path patterns.dev-tools/backends,configuration,tasks,environments, andclimise.jdx.dev/backends/...) in favor of fulldocs/-aligned URLsWritten by Cursor Bugbot for commit a44c315. This will update automatically on new commits. Configure here.