@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/working-with-mbx/references/troubleshooting.md

@@ -0,0 +1,136 @@
+Troubleshooting
+
+Troubleshooting [​](#troubleshooting)
+
+Start with the symptom, then inspect a specific build before clearing any cached work.
+
+| Symptom | First check |
+| --- | --- |
+| Plain Cargo does not use mbx | [Check Cargo's path](https://mr-boxington.jdx.dev/setup#verify-plain-cargo); for standalone setup, also run `mbx setup --status` |
+| A build restores little or nothing | `mbx explain --last`, then [read the results](https://mr-boxington.jdx.dev/cache-results#troubleshooting-a-low-hit-rate) |
+| Cargo waits for a target lock | Give simultaneous builds [separate targets](https://mr-boxington.jdx.dev/scheduling) |
+| Cargo metadata fails before a build | [Check workspace discovery](#workspace-discovery-fails) |
+| Build storage is on NFS | Move outputs to [local storage](https://mr-boxington.jdx.dev/configuration#local-build-storage) |
+| Remote requests fail | `mbx doctor`, then [check authentication](https://mr-boxington.jdx.dev/remote-cache#authenticate) |
+| Build storage is larger than expected | `mbx cache stats` and `mbx gc --dry-run`; review [budgets](https://mr-boxington.jdx.dev/managed-targets#budgets-scale-with-the-disk) |
+| Breakpoints point at an old checkout | Use the [debugger recipe](https://mr-boxington.jdx.dev/cookbook/local-development#debug-a-binary-restored-from-another-checkout) |
+
+## Diagnose the installation [​](#diagnose-the-installation)
+
+sh
+
+```
+mbx doctor
+```
+
+Example output (versions, paths, and budgets depend on your machine):
+
+text
+
+```
+  ok  cargo        cargo 1.98.0 (797e8a9bc 2026-08-05)
+  ok  rustc        rustc 1.98.0 (88d9e12ae 2026-08-18)
+  ok  cache        /home/you/.cache/mbx is writable
+  ok  session      Unix-domain listeners are available
+  ok  config       50.0 GiB budget, automatic gc enabled, managed targets enabled at /home/you/.cache/mbx/targets
+  ok  reflink      supported by the cache filesystem
+  ok  setup        mise Cargo wrapper is active and the fallback shim is current at /home/you/.local/share/mbx/bin/cargo
+  ok  remote       not configured; using the local cache
+
+0 failures, 0 warnings
+```
+
+Doctor's setup check currently recognizes explicit mise wrappers and the standalone shim installed by `mbx setup`, but not the native Rust tool option. Its setup warning alone does not mean native wrapping is inactive; [check Cargo's path](https://mr-boxington.jdx.dev/setup#verify-plain-cargo).
+
+For standalone setup, doctor checks that mise's Cargo wrapper is active, or that the installed fallback shim matches the running mbx and is the first `cargo` on `PATH`. It also checks the Cargo and rustc executables, cache write access, the local build-session listener, filesystem reflink support, effective remote policy, and remote protocol connectivity. Warnings describe setup problems, optional features, or fallbacks; failures make the command exit unsuccessfully.
+
+Build sessions normally communicate over a Unix-domain socket. When a sandbox blocks Unix socket listeners but permits filesystem FIFOs, mbx automatically uses FIFO transport and keeps caching enabled. If neither transport is available, mbx warns and runs Cargo without caching instead of preventing the build from starting.
+
+## Workspace discovery fails [​](#workspace-discovery-fails)
+
+Managed Cargo builds need a successful metadata probe to locate the workspace and verify output storage. If the probe fails, mbx stops before compilation. Run the probe directly with the same manifest and configuration options:
+
+sh
+
+```
+cargo metadata --no-deps --format-version 1
+```
+
+Resolve the reported Cargo error, then retry the build. Help, cleanup, and explicitly disabled shim invocations still pass through without this probe.
+
+Outside a project, commands such as `cargo binstall` pass through to Cargo. `cargo build` in a directory with no manifest reports Cargo's own missing-manifest error. An alias that names a local package still requires verified build storage:
+
+toml
+
+```
+[alias]
+i = ["install", "--path", "/path/to/project with spaces"]
+```
+
+mbx reads alias arguments from Cargo configuration, preserving array elements, and retries workspace discovery for the package they name. It supports aliases from the configuration hierarchy, `CARGO_HOME`, and `CARGO_ALIAS_*` variables, including recursive aliases and Cargo's built-in shorthand commands.
+
+When metadata fails, alias recovery does not support configuration `include` files, aliases with `--config` overrides, directory-changing options, or unstable Cargo options. An alias mbx cannot read in full is refused rather than guessed when its storage cannot be verified; spell out the build command with its manifest or path instead of the alias to diagnose it. Commands that are not aliases keep passing through, so an `include` in your configuration does not stop `cargo binstall` working outside a project. mbx never reconstructs alias arguments from `cargo --list`, which loses the boundaries of arguments containing whitespace.
+
+## Inspect a build [​](#inspect-a-build)
+
+sh
+
+```
+mbx explain --last                 # read the last recorded session
+mbx explain build --workspace      # run a build with diagnostics
+```
+
+The first command does not run Cargo. The second preserves Cargo's exit status. If Cargo considers every output fresh, there may be no compiler invocations to explain. See [Measure cache reuse](https://mr-boxington.jdx.dev/cache-results#measure-cache-reuse) for a controlled comparison with fresh targets.
+
+## Bypass mbx for one command [​](#bypass-mbx-for-one-command)
+
+In a POSIX shell:
+
+sh
+
+```
+MBX_DISABLE=1 cargo build
+```
+
+In PowerShell:
+
+powershell
+
+```
+$env:MBX_DISABLE = "1"
+try { cargo build } finally { Remove-Item Env:MBX_DISABLE }
+```
+
+This keeps Cargo's existing outputs. To investigate an artifact that may have been restored earlier, use a separate target directory as shown in the [debugger recipe](https://mr-boxington.jdx.dev/cookbook/local-development#debug-a-binary-restored-from-another-checkout).
+
+## Reporting a problem [​](#reporting-a-problem)
+
+Three things describe almost any mbx problem:
+
+sh
+
+```
+mbx doctor --json
+MBX_LOG=debug mbx build
+MBX_BYPASS_LOG=bypass.log mbx build
+```
+
+The doctor report describes the environment; `MBX_LOG` records build diagnostics and `MBX_BYPASS_LOG` records per-compilation bypass reasons.
+
+All three describe your machine: `mbx doctor --json` reports absolute cache paths and the URL and namespace of any configured remote, and the logs name the crates you build. Credentials are never printed. Remove anything else you would rather not publish before posting.
+
+`MBX_LOG` takes an [env\_logger](https://docs.rs/env_logger) filter, so `debug`, `trace`, or a per-module filter such as `mbx=trace` all work; it defaults to `info,portable_pty=off`. It filters logs in the `mbx` process that drives the build, including routine shim diagnostics forwarded to the session. Use `MBX_BYPASS_LOG` for per-compilation bypass records, or `mbx explain` for a grouped summary. See [Cache results](https://mr-boxington.jdx.dev/cache-results).
+
+Report a problem in [Q&A discussions](https://github.com/jdx/mr-boxington/discussions/categories/q-a), and propose a change in [Ideas](https://github.com/jdx/mr-boxington/discussions/categories/ideas). A suspected vulnerability goes through [private advisory reporting](https://github.com/jdx/mr-boxington/security/advisories/new); see [SECURITY.md](https://github.com/jdx/mr-boxington/blob/main/SECURITY.md).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/troubleshooting.md)
+
+Last updated:
+
+Pager
+
+[Previous pageCache server](https://mr-boxington.jdx.dev/cache-server)
+
+[Next pageCache results](https://mr-boxington.jdx.dev/cache-results)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/tui.md

@@ -0,0 +1,163 @@
+Watching builds
+
+Watching builds [​](#watching-builds)
+
+`mbx tui` shows live and recent builds using the same local cache. Open it in a second terminal while a build runs:
+
+sh
+
+```
+mbx tui
+```
+
+[![Live dashboard showing build activity, cache traffic, capacity, and compilation savings](https://mr-boxington.jdx.dev/screenshots/tui-live.png)](https://mr-boxington.jdx.dev/screenshots/tui-live.png)
+
+*Live, with example build data. Open any screenshot at full size to read the details.*
+
+`mbx tui` shows one row per compilation, with its crate name and cache outcome. For the end-of-build summary, see [Cache results](https://mr-boxington.jdx.dev/cache-results).
+
+The TUI reads local session files; it does not need a daemon or cache server. Each build appends its decisions to a stream under the cache, and the dashboard reads those streams. It shows builds in other terminals, builds that started before you opened it, and any number of builds at once.
+
+## Screens [​](#screens)
+
+**Live** lists recorded builds and, for the selected one, the compilations as they are decided. Outcomes are colored: green for a hit, red for a miss, grey when no lookup was possible, yellow for a bypass, cyan for a successful verification, and magenta for a verification mismatch.
+
+The selected build stays visible as you move through the list. The activity panel follows the newest compilations by default. Use `Page Up` and `Page Down` to read older activity, and `End` to return to the latest. New events keep arriving while you read history, without shifting the rows you are inspecting. Narrow terminals show fewer build columns; the selected build's counts also appear above its activity.
+
+On wider terminals, Live adds a sidebar with lookup traffic, the selected build's cache-hit gauge, and its biggest compilation savings. The hit and miss graphs share a scale and cover the last five minutes observed by the TUI; idle intervals stay empty. The header groups compiler time saved, store capacity, and evictions into separate metric panels.
+
+The hit rate shown is over *attempted lookups*, the same as the summary's. A cold build that looked nothing up shows `-`, not `0%`, because those are different facts.
+
+**Sessions** lists finished builds with the totals each one ended with, the same numbers `MBX_STATS_REPORT` would have written.
+
+**Store** shows what the store holds and what mbx has saved on this machine since it started counting, with a date and human-readable compiler time. It also shows pruning totals, reflinked bytes, and estimated workspace sharing; [`mbx stats`](https://mr-boxington.jdx.dev/stats) explains the figures and prints them without opening the TUI. Use `↑`/`↓` or `Page Up`/`Page Down` to scroll the Store screen. On larger terminals, inventory, lifetime savings, and workspace sharing each get a panel. Reports that need more room use the scrollable layout.
+
+[![Store dashboard showing lifetime savings, automatic pruning, and estimated workspace sharing](https://mr-boxington.jdx.dev/screenshots/tui-store.png)](https://mr-boxington.jdx.dev/screenshots/tui-store.png)
+
+*Store, with example build data. Sharing and compiler savings are estimates.*
+
+**Insights** explains the build selected in Live. It shows:
+
+- An outcome chart over all recorded actions, alongside the lookup-only hit rate. Bypassed and unconsulted work are visible without lowering that rate.
+- A strip of recent outcomes, ordered oldest to newest. Each letter represents one action, not a fixed interval of time. On wider terminals a duration graph below the strip shows which of those actions took the longest.
+- Bypass reasons ranked by frequency, with each reason's share of bypasses.
+- The slowest recorded actions, with their outcomes. A hit's duration measures restoring outputs; other durations measure compiler work.
+- The biggest cache wins, ranked by estimated compiler time avoided, plus total estimated compiler time saved and bytes restored for the build.
+
+[![Insights dashboard showing outcome bars, action durations, bypass reasons, and the biggest cache wins](https://mr-boxington.jdx.dev/screenshots/tui-insights.png)](https://mr-boxington.jdx.dev/screenshots/tui-insights.png)
+
+*Insights, with example build data. Action durations measure recorded work, not elapsed build time.*
+
+Use `j`/`k` or `↑`/`↓` to inspect another build without leaving Insights, and `Page Up`/`Page Down` to scroll. Rankings cover the most recent 2,000 retained actions. Charts count recorded actions even after they leave that window; if the stream hits its recording cap, Insights marks its data as incomplete. Compiler time saved is cumulative work avoided, not elapsed wall-clock time: compilations can run in parallel.
+
+With enough room, Insights arranges its charts and rankings in a dashboard. `Page Down` opens the full detail view; `Page Up` returns to the dashboard.
+
+A build's state is one of:
+
+| State | Meaning |
+| --- | --- |
+| `live` | a build is running and still appending |
+| `finished` | the build ended and recorded its totals |
+| `abandoned` | the build died before it could record them |
+
+`abandoned` is not an error mbx reports; it is what a stream looks like when the process writing it is gone. A build killed mid-compile shows up this way instead of appearing to run forever.
+
+## Store pressure [​](#store-pressure)
+
+The header shows store bytes against the configured `gc.max_size` budget with an inline usage bar. It turns yellow at 90% and red at or above 100%; a store can temporarily exceed its budget between sweeps. This is the action-store budget, not free disk space. A configured combined target/store/incremental budget can reduce the actual allowance further. Automatic collection being off is shown explicitly.
+
+Evicted bytes are shown for the last five minutes of observation and for the lifetime of the savings ledger. These count cache-store collection, including explicit `mbx gc`, and exclude target-directory cleanup. The recent counter starts when the TUI opens; it does not treat old ledger totals as new evictions. Resuming after a pause starts a new observation period.
+
+A **POSSIBLE CACHE THRASHING** banner appears on every screen when all of these hold within the last five minutes:
+
+- The eviction counter increased in at least three separate observations.
+- Evicted bytes total at least 25% of the configured store budget.
+- At least 20 new lookups were observed, with a miss rate of 50% or more.
+
+The banner alternates red and yellow once per second while keeping its text visible. The Store screen gives the evidence and suggests inspecting misses and the cache budget. This is a warning heuristic, not proof that specific misses were caused by eviction. A single cleanup, a cold build without repeated eviction, and a reset ledger do not trigger it. It clears as the observations leave the five-minute window. Counter observations are not an exact count of GC runs; several runs may fall between reads.
+
+## Keys [​](#keys)
+
+| Key | Action |
+| --- | --- |
+| `q`, `Esc`, `Ctrl-C` | quit |
+| `Tab`, `→` | next screen |
+| `Shift-Tab`, `←` | previous screen |
+| `1`, `2`, `3`, `4` | jump to Live, Sessions, Store, Insights |
+| `j`, `k`, `↓`, `↑` | select a build in Live or Insights; scroll Sessions or Store |
+| `Page Up`, `Page Down` | browse activity history in Live; scroll Insights or Store |
+| `End` | follow the latest activity in Live |
+| `p` | pause and resume reading |
+
+Click a tab to switch screens. Click a build in Live to select it, or a row in Sessions to open that build in Live. The mouse wheel selects builds over the Live build list, browses history over Activity, and scrolls the Sessions, Store, and Insights reports. Scrolling up in Activity shows older events; scrolling down returns toward the latest events.
+
+## Without a terminal [​](#without-a-terminal)
+
+`mbx tui --once` prints one plain-text snapshot and exits, for a pipe, a CI log, or a quick look that does not take over the terminal.
+
+sh
+
+```
+mbx tui --once
+```
+
+text
+
+```
+store: /home/you/.cache/mbx/actions
+objects: 44 (8.6 MiB); action results: 7 (2.5 KiB)
+
+command                             state         hit   miss  unconsulted  bypass
+mbx check --workspace               live            0      0            4       3
+mbx build                           finished        3      0            0       3
+mbx build                           finished        0      0            3       3
+```
+
+## Recording [​](#recording)
+
+Recording is on by default. A build appends one short line per compilation directly to its stream, with no buffering, so the dashboard is live. The cost is one small append against a compilation measured in milliseconds. Turn it off with `events = false` or `MBX_EVENTS=0` to disable session event recording. Cache entries and other build state are still stored.
+
+Streams live beside the rest of the store's bookkeeping:
+
+text
+
+```
+<store>/sessions/v1/<session>.jsonl   one line per decision
+<store>/sessions/v1/<session>.lock    held for as long as the build runs
+```
+
+The lock is how a stream says it is still being written. Whoever can take it is looking at a build that has ended, however it ended, because the operating system releases the lock with the process either way.
+
+Collection bounds them without any configuration: a stream is dropped once it is a week old or once it is not among the newest 256, and a single build stops adding rows after 16 MiB by default, though its totals are still recorded. Change that cap with [`events_max_size`](https://mr-boxington.jdx.dev/configuration#events-max-size). A stream a build is still writing is never collected. `mbx gc --dry-run` reports what it would drop alongside everything else.
+
+Session history does not affect cache keys or count against the action-store size budget. Deleting finished session files removes their rows from the TUI and the history available to `mbx explain --last`, without removing compiled artifacts.
+
+Not a stable format
+
+The event files are an implementation detail of `mbx tui` and may change in any release. Scripts should read `MBX_STATS_REPORT`, which is [versioned](https://mr-boxington.jdx.dev/stability#json-output-is-versioned).
+
+## Wrapper phase traces [​](#wrapper-phase-traces)
+
+Rustc and C/C++ cache attempts also record startup, key construction, cache lookup, blob transfer, restore, store, prediction recording, compiler execution, and scheduler waits. `MBX_STATS_REPORT` includes these as `wrapper_phases_ns`. The durations are cumulative across wrappers and exclusive: nested work is subtracted from its parent phase. They do not add up to build wall time because compilers run in parallel. Work without a phase is reported as `unattributed`.
+
+To inspect a saved build in Perfetto, export its session file:
+
+sh
+
+```
+mbx cache trace "$(mbx cache dir)/sessions/v1/<session>.jsonl" > trace.json
+```
+
+Open `trace.json` in [Perfetto](https://ui.perfetto.dev). Each wrapper process has its own lane, with nested phases under the invocation. Trace spans are bounded to 512 per wrapper; totals continue accumulating after that limit. Telemetry delivery itself is excluded. A declined cache attempt ends before the transparent compiler fallback, and rustdoc is not instrumented.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/tui.md)
+
+Last updated:
+
+Pager
+
+[Previous pageManaged linkers](https://mr-boxington.jdx.dev/linkers)
+
+[Next pageStandalone C and C++](https://mr-boxington.jdx.dev/standalone-builds)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/update-docs.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Update mbx (Mr. Boxington) documentation
+# This script fetches the latest docs from mr-boxington.jdx.dev and converts them to markdown
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REFS_DIR="${SCRIPT_DIR}/references"
+TEMP_OUTPUT="${SCRIPT_DIR}/.temp-output"
+
+echo "=== Updating mbx Documentation ==="
+
+# Clean up previous temp output
+rm -rf "${TEMP_OUTPUT}"
+
+# Fetch the whole doc set from mr-boxington.jdx.dev.
+# The site is small (~50 pages) and publishes a complete sitemap.xml, so sitemap
+# discovery is used instead of --skip-sitemap: it is faster and finds every page.
+echo "Fetching docs from mr-boxington.jdx.dev..."
+npx @mdream/crawl \
+  "https://mr-boxington.jdx.dev/**" \
+  --output "${TEMP_OUTPUT}" \
+  --artifacts "markdown"
+
+if [ ! -d "${TEMP_OUTPUT}" ]; then
+  echo "Crawl produced no output" >&2
+  exit 1
+fi
+
+# Mirror the crawled tree into references/ so reference paths match doc URLs:
+#   https://mr-boxington.jdx.dev/cli/explain -> references/cli/explain.md
+echo "Copying documentation to references/..."
+rm -rf "${REFS_DIR}"
+mkdir -p "${REFS_DIR}"
+cp -R "${TEMP_OUTPUT}/." "${REFS_DIR}/"
+
+# Clean up temp output
+rm -rf "${TEMP_OUTPUT}"
+
+echo "=== Update complete ==="
+echo "Documentation updated in: ${REFS_DIR}"
+echo ""
+echo "Pages: $(find "${REFS_DIR}" -name "*.md" | wc -l | tr -d ' ')"
+for dir in "${REFS_DIR}"/*/; do
+  if [ -d "$dir" ]; then
+    count=$(find "$dir" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    echo "  $(basename "$dir")/: $count files"
+  fi
+done

package/skills/working-with-mise/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: working-with-mise
+description: Use when adding, configuring, or troubleshooting mise-managed tools - ensures proper CLI usage, detects existing config files, and diagnoses PATH/activation issues when commands aren't found
+---
+
+# Working with mise
+
+## Overview
+
+mise is a polyglot tool version manager. Use this skill when:
+- Adding tools to a project via mise
+- Troubleshooting "command not found" when mise should have tools available
+- Deciding whether mise is the right choice for a dependency
+
+## The Iron Rules
+
+1. **Use `mise use` to add tools** - never manually edit config files
+2. **Detect existing config files first** - don't create new ones when one exists
+3. **Fix the shell, don't workaround** - if tools aren't on PATH, diagnose the activation issue rather than using `mise exec` as a permanent workaround
+
+## When to Use mise vs Alternatives
+
+### Use mise when version matters per-project
+
+Tools where different projects need different versions:
+- Language runtimes: node, python, ruby, go, rust
+- Infrastructure tools: terraform, kubectl, helm
+- Tools with breaking changes between versions
+
+```bash
+# Good mise candidates - version sensitivity
+mise use node@20      # Projects may need different Node versions
+mise use terraform@1.5  # IaC often pins specific versions
+mise use ruby@3.2     # Gemfiles often require specific Ruby
+```
+
+### Use Homebrew/system when version rarely matters
+
+Stable CLIs with consistent interfaces across versions:
+- jq, yq - query languages are stable
+- gh, hub - GitHub CLI
+- ripgrep, fd - search tools
+- tree, htop - system utilities
+
+```bash
+# Better as Homebrew - version doesn't matter
+brew install jq gh ripgrep
+```
+
+### Decision checklist
+
+Ask yourself:
+1. Does this project's README/docs specify a version? → mise
+2. Could different team members need different versions? → mise
+3. Does the tool have breaking changes between versions? → mise
+4. Is it a stable CLI you use the same way everywhere? → Homebrew
+
+## Adding Tools with mise
+
+### 1. Check for existing config files first
+
+Before adding tools, detect what config format the project uses:
+
+```bash
+# Check for existing mise config
+ls -la mise.toml .mise.toml .mise.local.toml .tool-versions 2>/dev/null
+```
+
+Config file precedence (mise uses the first it finds):
+- `mise.toml` or `.mise.toml` - standard mise config
+- `.mise.local.toml` - local overrides (usually gitignored)
+- `.tool-versions` - legacy asdf format
+
+**If a config file exists, use that format.** Don't create a new one.
+
+### 2. Use `mise use` to add tools
+
+**Always use the CLI** - it validates the tool exists and works:
+
+```bash
+# Add to project config (mise.toml or existing format)
+mise use node@20
+
+# Add to global config (~/.config/mise/config.toml)
+mise use -g python@3.12
+
+# Dry run to see what would happen
+mise use --dry-run terraform@1.5
+```
+
+**Never manually edit config files** - `mise use` ensures:
+- The tool/version exists in the registry
+- The tool installs correctly
+- The config syntax is valid
+
+### 3. Verify the tool is available
+
+```bash
+# Check mise sees the tool
+mise ls
+
+# Check the tool is on PATH
+which node
+node --version
+
+# Compare with mise's view
+mise which node
+```
+
+## Troubleshooting "Command Not Found"
+
+When a tool should be available but isn't found:
+
+### Diagnostic workflow
+
+```bash
+# 1. Check mise installation health
+mise doctor
+
+# 2. Check what tools mise knows about
+mise ls                    # All installed tools
+mise ls --current          # Tools for current directory
+
+# 3. Compare which vs mise which
+which node                 # What shell finds
+mise which node            # What mise thinks it should be
+
+# 4. Check if tool would work via mise exec
+mise exec -- node --version  # If this works, it's an activation issue
+```
+
+### Common causes and fixes
+
+#### Shell activation not set up
+
+**Symptom**: `mise exec -- node` works, but `node` doesn't
+
+**Diagnose**:
+```bash
+mise doctor  # Look for activation warnings
+```
+
+**Fix** - add to shell rc file:
+
+```bash
+# For zsh (~/.zshrc)
+eval "$(mise activate zsh)"
+
+# For bash (~/.bashrc)
+eval "$(mise activate bash)"
+
+# For fish (~/.config/fish/config.fish)
+mise activate fish | source
+```
+
+Then restart your shell or `source` the rc file.
+
+#### Config file not trusted
+
+**Symptom**: mise shows trust warning, tools not activated
+
+**Fix**:
+```bash
+mise trust
+```
+
+#### Tool not installed for current directory
+
+**Symptom**: `mise ls` shows tool globally but not in `mise ls --current`
+
+**Diagnose**:
+```bash
+# Check what config file applies
+mise config
+
+# Check if there's a local config overriding global
+cat mise.toml .mise.toml .tool-versions 2>/dev/null
+```
+
+**Fix**: Add the tool to the project config:
+```bash
+mise use node@20  # Adds to project config
+```
+
+#### Shims vs PATH activation confusion
+
+**Symptom**: Tools work in terminal but not in IDE/scripts
+
+See [references/dev-tools/shims-html.md](references/dev-tools/shims-html.md) for detailed explanation.
+
+**Quick fix** for non-interactive contexts:
+```bash
+# In ~/.zprofile or ~/.bash_profile (non-interactive)
+eval "$(mise activate zsh --shims)"
+
+# In ~/.zshrc or ~/.bashrc (interactive)
+eval "$(mise activate zsh)"
+```
+
+### When to use `mise exec` (legitimately)
+
+`mise exec` is appropriate for:
+- One-off commands with specific versions: `mise exec node@18 -- npm test`
+- CI/CD scripts where activation isn't available
+- Testing a different version temporarily
+
+`mise exec` is NOT a fix for:
+- Tools not being on PATH in your terminal (fix activation instead)
+- "It works with mise exec" as a permanent solution
+
+## Troubleshooting GitHub 401 / Token Errors
+
+**Symptom**: `mise install` or `mise use` fails with `401 Unauthorized` while fetching a tool from GitHub.
+
+An expired token in a higher-priority source silently shadows every source below it. A bad token is *worse* than no token: GitHub answers invalid credentials with 401, while anonymous requests succeed (subject to rate limits).
+
+### 1. Find which source mise picked
+
+```bash
+mise token github    # masked output - safe to paste into logs
+# github.com: gho_…tSoC (source: gh CLI (hosts.yml))
+```
+
+### 2. Token priority - first match wins
+
+1. `MISE_GITHUB_TOKEN`
+2. `GITHUB_API_TOKEN`
+3. `GITHUB_TOKEN`
+4. `github.credential_command`
+5. native GitHub OAuth
+6. `~/.config/mise/github_tokens.toml`
+7. **gh CLI `hosts.yml`** - enabled by default, and the usual culprit
+8. `git credential fill` - opt-in
+
+Two traps in that list:
+
+- **`GH_TOKEN` is not a mise token source.** It is gh's own variable, so exporting it changes nothing. Use `GITHUB_TOKEN` or `MISE_GITHUB_TOKEN`.
+- **Empty means unset.** `GITHUB_TOKEN= mise install` falls straight back to `hosts.yml`. No env var in that family makes mise go anonymous.
+
+### 3. The gh CLI trap
+
+mise reads `~/.config/gh/hosts.yml` **directly - it never shells out to `gh`**. gh's own expiry handling therefore never runs, and a stale `oauth_token` keeps returning 401 indefinitely.
+
+**Fix** - re-authenticate:
+
+```bash
+gh auth login -h github.com
+```
+
+**Or bypass the gh integration** - cleaner than pointing `GH_CONFIG_DIR` at an empty directory:
+
+```bash
+MISE_GITHUB_GH_CLI_TOKENS=0 mise install    # mise token github -> (none)
+```
+
+Permanently, in `~/.config/mise/config.toml`:
+
+```toml
+[settings.github]
+gh_cli_tokens = false
+```
+
+See [references/dev-tools/github-tokens-html.md](references/dev-tools/github-tokens-html.md) for GitHub Enterprise, `credential_command`, and keyring-stored tokens.
+
+## Validation Commands
+
+After configuration changes, verify everything works:
+
+```bash
+# Full health check
+mise doctor
+
+# Verify specific tool
+mise which node && node --version
+
+# Verify PATH includes mise tools
+echo $PATH | tr ':' '\n' | grep mise
+```
+
+## Available References
+
+- [references/cli/use-html.md](references/cli/use-html.md) - Full `mise use` documentation
+- [references/cli/doctor-html.md](references/cli/doctor-html.md) - Diagnostic commands
+- [references/cli/activate-html.md](references/cli/activate-html.md) - Shell activation
+- [references/cli/which-html.md](references/cli/which-html.md) - Path resolution
+- [references/dev-tools/shims-html.md](references/dev-tools/shims-html.md) - Shims vs PATH activation
+- [references/dev-tools/github-tokens-html.md](references/dev-tools/github-tokens-html.md) - GitHub token sources and priority
+- [references/guides/getting-started.md](references/guides/getting-started.md) - Setup guide
+
+## Red Flags - You're About to Violate
+
+- "Let me just add this to mise.toml manually" → Use `mise use` instead
+- "I'll use mise exec as a workaround" → Diagnose why activation isn't working
+- "Let me create a .mise.toml" → Check if config already exists first
+- Adding jq/gh/ripgrep to mise → Consider if version actually matters
+- Assuming mise is activated → Run `mise doctor` to verify
+- Exporting `GH_TOKEN` to fix a mise 401 → mise doesn't read it; run `mise token github` first