From 58b9fc50d2ed12047b6b2f8b29597fa6f83a1123 Mon Sep 17 00:00:00 2001
From: Minsu Lee <1964421+amondnet@users.noreply.github.com>
Date: Sun, 8 Nov 2026 22:22:04 +0900
Subject: [PATCH 1/4] build: add mbx build cache through mise

Pin the mr-boxington CLI in mise.toml and document running Cargo through mbx. The mr_boxington Rust option is not used because a rust entry needs a version, which would override rust-toolchain.toml. Intel macOS has no prebuilt mbx, so mise.macos-x64.toml builds it with the cargo backend.
---
 .miserc.toml        |  2 ++
 CONTRIBUTING.md     | 30 +++++++++++++++++++++++++++---
 mise.macos-x64.toml |  6 ++++++
 mise.toml           |  9 ++++++++-
 4 files changed, 43 insertions(+), 4 deletions(-)
 create mode 100644 .miserc.toml
 create mode 100644 mise.macos-x64.toml

diff --git a/.miserc.toml b/.miserc.toml
new file mode 100644
index 0000000..f6c55d2
--- /dev/null
+++ b/.miserc.toml
@@ -0,0 +1,2 @@
+# Load platform configs such as mise.macos-x64.toml (the default from mise 2027.6).
+auto_env = true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1395ba7..d70de4c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,16 +6,16 @@ By participating, you agree to abide by our [Code of Conduct](./CODE_OF_CONDUCT.
 
 ## Getting started
 
-`csp` is Rust-first (the workspace under `crates/`) with a thin JS toolchain for the npm wrapper and repo tooling. [mise](https://mise.jdx.dev/) pins the tool versions (node, bun, and the `hk` git-hook manager); the Rust toolchain is pinned separately by `rust-toolchain.toml`.
+`csp` is Rust-first (the workspace under `crates/`) with a thin JS toolchain for the npm wrapper and repo tooling. [mise](https://mise.jdx.dev/) pins the tool versions (node, bun, the `hk` git-hook manager, and the `mbx` Cargo build cache); the Rust toolchain is pinned separately by `rust-toolchain.toml`.
 
 ```bash
 git clone https://github.com/pleaseai/code-search.git
 cd code-search
-mise install        # install pinned tool versions (node, bun, hk) and set up git hooks
+mise install        # install pinned tool versions (node, bun, hk, mbx) and set up git hooks
 bun install         # install JS dependencies
 ```
 
-If you do not use mise, install the versions listed in `mise.toml` and `rust-toolchain.toml` manually, then run `bun install`. Rust builds use the standard `cargo` toolchain.
+If you do not use mise, install the versions listed in `mise.toml` and `rust-toolchain.toml` manually, then run `bun install`. Rust builds use the standard `cargo` toolchain; `mbx` is optional (see [Faster local builds](#faster-local-builds-optional)).
 
 ## Development workflow
 
@@ -33,6 +33,30 @@ mise run check       # full pre-commit gate: JS lint/typecheck + Rust fmt/clippy
 
 For Rust changes, also run `cargo fmt --all` and `cargo clippy --all-targets --all-features -- -D warnings` (both are part of `mise run check`).
 
+### Faster local builds (optional)
+
+CI compiles Rust through [mbx (mr boxington)](https://mr-boxington.jdx.dev), a shared Cargo build
+cache, via `jdx/mr-boxington-action`. `mise install` also installs `mbx` locally (pinned in
+`mise.toml`), so a build in one worktree warms every other worktree. Run Cargo through it:
+
+```bash
+mise exec -- mbx build           # or: mbx test --all-features --locked --workspace
+mbx explain --last               # why a build did or did not hit the cache
+```
+
+mise's `mr_boxington` Rust option is deliberately not used: a `rust` entry in `mise.toml`
+needs a version, which would override `rust-toolchain.toml` (the sole owner of the Rust channel).
+So plain `cargo` is not routed through `mbx`; call `mbx` explicitly. Set
+`CARGO_INCREMENTAL=0` for the best hit rate.
+
+There is no prebuilt `mbx` for Intel macOS, so `mise.macos-x64.toml` (loaded through `auto_env` in
+`.miserc.toml`) builds it from crates.io via the `cargo:mbx` backend (Rust 1.91 or newer). Without
+mise, run `cargo install mbx --version 1.29.2 --locked`.
+
+`mbx` wraps `rustc` itself, so it **defers to any `RUSTC_WRAPPER` already set** (for example
+`RUSTC_WRAPPER=sccache` in a shell profile) and then caches nothing. Unset the wrapper before
+using it. The `mbx[cache]` summary line it prints shows the hit count.
+
 ## Commit messages
 
 We follow [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): subject`, where `type` is one of `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, etc. Breaking changes include a `BREAKING CHANGE:` footer. Versioning and the changelog are generated automatically from these messages, so accurate types matter.
diff --git a/mise.macos-x64.toml b/mise.macos-x64.toml
new file mode 100644
index 0000000..4b81b4b
--- /dev/null
+++ b/mise.macos-x64.toml
@@ -0,0 +1,6 @@
+# mr-boxington ships no darwin/x86_64 release archive, so build mbx from crates.io.
+[tools]
+mr-boxington = "1.29.2"
+
+[tool_alias]
+mr-boxington = "cargo:mbx"
diff --git a/mise.toml b/mise.toml
index be1f3f7..0bd3b00 100644
--- a/mise.toml
+++ b/mise.toml
@@ -4,7 +4,10 @@
 # This repo is Rust-first (crates/) with a thin JS toolchain for the npm/ wrapper and SDK.
 # - The Rust toolchain (channel, rustfmt, clippy) is owned solely by rust-toolchain.toml —
 #   do not double-pin it here.
-# - Only node/bun (JS lint + typecheck) and hk (the git hook manager) are pinned via mise.
+# - Only node/bun (JS lint + typecheck), hk (the git hook manager) and mbx (the Cargo build
+#   cache CLI) are pinned via mise. mise's `mr_boxington` Rust option is not used: a `rust`
+#   entry requires a version, which would override rust-toolchain.toml. Run Cargo through
+#   mbx instead (see CONTRIBUTING.md).
 
 [tools]
 node = "24"
@@ -15,6 +18,10 @@ bun = "1.3.14" # matches package.json packageManager
 # Pinned to match the v1.48.0 hk.pkl amends — keep the two in sync on upgrades.
 # Details: dev-tooling → references/git-hooks.md
 "cargo:hk" = "1.48.0"
+# mbx (mr-boxington): shared Cargo build cache. Pinned to the version the CI action uses.
+# No darwin/x86_64 release archive exists, so Intel macOS builds it from source via the
+# cargo backend (~2 min first build, cached afterwards).
+mr-boxington = "1.29.2"
 
 [env]
 # Wrap hooks in `mise x` so the mise-managed node/bun are on PATH

From 0775fcd7ac91586863e301084db4e96f705de851 Mon Sep 17 00:00:00 2001
From: Minsu Lee <1964421+amondnet@users.noreply.github.com>
Date: Sun, 8 Nov 2026 22:22:15 +0900
Subject: [PATCH 2/4] ci: cache Rust builds with mr-boxington-action

Run clippy, tests and llvm-cov through mbx in the Rust and Sonar workflows, installing the pinned toolchain before the cache action so the key hashes the right rustc. Each job gets its own cache generation. codspeed and release workflows are unchanged.
---
 .github/workflows/rust.yml  | 36 +++++++++++++++++++++++++++++++-----
 .github/workflows/sonar.yml | 12 +++++++++++-
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index 6bb87b3..6aeeb9f 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -35,6 +35,10 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    # mbx wraps rustc itself and defers to a preset wrapper (caching nothing),
+    # so no RUSTC_WRAPPER may be set here.
+    env:
+      CARGO_INCREMENTAL: 0
     steps:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
@@ -42,16 +46,27 @@ jobs:
           persist-credentials: false
 
       # The toolchain (and rustfmt/clippy components) is selected by
-      # rust-toolchain.toml via the runner's preinstalled rustup — no
-      # third-party action needed.
+      # rust-toolchain.toml via the runner's preinstalled rustup. Install it
+      # explicitly so the mbx cache key below hashes the pinned `rustc`, not a
+      # lazily-downloaded one.
+      - name: Install pinned toolchain
+        run: rustup show active-toolchain || rustup toolchain install
+
+      # After the toolchain step: the cache key hashes the `rustc` on PATH.
+      - name: Set up mbx cache
+        uses: jdx/mr-boxington-action@88acf2bb50552c7c508cbac13e5f8c576b95b1de # v1.7.3
+        with:
+          version: 1.29.2
+          cache-generation: test-v1
+
       - name: Format check
         run: cargo fmt --all -- --check
 
       - name: Clippy
-        run: cargo clippy --all-targets --all-features -- -D warnings
+        run: mbx clippy --all-targets --all-features -- -D warnings
 
       - name: Test
-        run: cargo test --all-features --locked --workspace
+        run: mbx test --all-features --locked --workspace
 
   ignored-tests:
     # Network-gated: these tests download tree-sitter grammars from GitHub
@@ -60,11 +75,22 @@ jobs:
     # grammar-fetch / parser-compat regressions.
     if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
     runs-on: ubuntu-latest
+    env:
+      CARGO_INCREMENTAL: 0
     steps:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           persist-credentials: false
 
+      - name: Install pinned toolchain
+        run: rustup show active-toolchain || rustup toolchain install
+
+      - name: Set up mbx cache
+        uses: jdx/mr-boxington-action@88acf2bb50552c7c508cbac13e5f8c576b95b1de # v1.7.3
+        with:
+          version: 1.29.2
+          cache-generation: ignored-v1
+
       - name: Test (ignored / network-gated)
-        run: cargo test --all-features --locked --workspace -- --ignored
+        run: mbx test --all-features --locked --workspace -- --ignored
diff --git a/.github/workflows/sonar.yml b/.github/workflows/sonar.yml
index f745133..bb0d36d 100644
--- a/.github/workflows/sonar.yml
+++ b/.github/workflows/sonar.yml
@@ -19,6 +19,9 @@ jobs:
     runs-on: ubuntu-latest
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      # mbx wraps rustc itself and defers to a preset wrapper (caching nothing),
+      # so no RUSTC_WRAPPER may be set here.
+      CARGO_INCREMENTAL: 0
     steps:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
@@ -32,6 +35,13 @@ jobs:
       - name: Add llvm-tools-preview component
         run: rustup component add llvm-tools-preview
 
+      # After the toolchain and llvm-tools steps: the cache key hashes the `rustc` on PATH.
+      - name: Set up mbx cache
+        uses: jdx/mr-boxington-action@88acf2bb50552c7c508cbac13e5f8c576b95b1de # v1.7.3
+        with:
+          version: 1.29.2
+          cache-generation: coverage-v1
+
       - name: Install cargo-llvm-cov
         uses: taiki-e/install-action@9e1e5806d4a4822de933115878265be9aaa786d9 # v2
         with:
@@ -42,7 +52,7 @@ jobs:
         # offline (see ADR-0004). --all-features mirrors the Rust CI gate.
         run: |
           mkdir -p coverage
-          cargo llvm-cov --workspace --locked --all-features --lcov --output-path coverage/rust-lcov.info
+          mbx llvm-cov --workspace --locked --all-features --lcov --output-path coverage/rust-lcov.info
 
       - name: Upload Rust coverage to Codecov
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0

From e18ed847f4bebf6c0fdd3ba4d21f896b5b453696 Mon Sep 17 00:00:00 2001
From: Minsu Lee <1964421+amondnet@users.noreply.github.com>
Date: Sun, 8 Nov 2026 23:08:41 +0900
Subject: [PATCH 3/4] chore: trim comments on the mbx cache setup

---
 .github/workflows/rust.yml  | 6 +-----
 .github/workflows/sonar.yml | 2 --
 .miserc.toml                | 1 -
 mise.toml                   | 6 +-----
 4 files changed, 2 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index 6aeeb9f..5c9f80a 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -35,8 +35,6 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
-    # mbx wraps rustc itself and defers to a preset wrapper (caching nothing),
-    # so no RUSTC_WRAPPER may be set here.
     env:
       CARGO_INCREMENTAL: 0
     steps:
@@ -46,9 +44,7 @@ jobs:
           persist-credentials: false
 
       # The toolchain (and rustfmt/clippy components) is selected by
-      # rust-toolchain.toml via the runner's preinstalled rustup. Install it
-      # explicitly so the mbx cache key below hashes the pinned `rustc`, not a
-      # lazily-downloaded one.
+      # rust-toolchain.toml via the runner's preinstalled rustup.
       - name: Install pinned toolchain
         run: rustup show active-toolchain || rustup toolchain install
 
diff --git a/.github/workflows/sonar.yml b/.github/workflows/sonar.yml
index bb0d36d..517b5eb 100644
--- a/.github/workflows/sonar.yml
+++ b/.github/workflows/sonar.yml
@@ -19,8 +19,6 @@ jobs:
     runs-on: ubuntu-latest
     env:
       SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-      # mbx wraps rustc itself and defers to a preset wrapper (caching nothing),
-      # so no RUSTC_WRAPPER may be set here.
       CARGO_INCREMENTAL: 0
     steps:
       - name: Checkout code
diff --git a/.miserc.toml b/.miserc.toml
index f6c55d2..8f0b74b 100644
--- a/.miserc.toml
+++ b/.miserc.toml
@@ -1,2 +1 @@
-# Load platform configs such as mise.macos-x64.toml (the default from mise 2027.6).
 auto_env = true
diff --git a/mise.toml b/mise.toml
index 0bd3b00..d9628be 100644
--- a/mise.toml
+++ b/mise.toml
@@ -6,8 +6,7 @@
 #   do not double-pin it here.
 # - Only node/bun (JS lint + typecheck), hk (the git hook manager) and mbx (the Cargo build
 #   cache CLI) are pinned via mise. mise's `mr_boxington` Rust option is not used: a `rust`
-#   entry requires a version, which would override rust-toolchain.toml. Run Cargo through
-#   mbx instead (see CONTRIBUTING.md).
+#   entry requires a version, which would override rust-toolchain.toml.
 
 [tools]
 node = "24"
@@ -18,9 +17,6 @@ bun = "1.3.14" # matches package.json packageManager
 # Pinned to match the v1.48.0 hk.pkl amends — keep the two in sync on upgrades.
 # Details: dev-tooling → references/git-hooks.md
 "cargo:hk" = "1.48.0"
-# mbx (mr-boxington): shared Cargo build cache. Pinned to the version the CI action uses.
-# No darwin/x86_64 release archive exists, so Intel macOS builds it from source via the
-# cargo backend (~2 min first build, cached afterwards).
 mr-boxington = "1.29.2"
 
 [env]

From 1ea7f26e40d12afede3181aeb824e7165787c7ee Mon Sep 17 00:00:00 2001
From: Minsu Lee <1964421+amondnet@users.noreply.github.com>
Date: Mon, 9 Nov 2026 00:42:15 +0900
Subject: [PATCH 4/4] chore: apply AI code review suggestions

Run every mbx example in CONTRIBUTING through mise exec, skip
mr-boxington in the JS-only CI job, and install the pinned toolchain
explicitly in the Sonar job.
---
 .github/workflows/ci.yml    | 2 +-
 .github/workflows/sonar.yml | 3 +++
 CONTRIBUTING.md             | 4 ++--
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7ef5fce..0bb2afa 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,7 +19,7 @@ jobs:
     env:
       # CI runs no git hooks, so skip the cargo:hk source build (~3 min on every run).
       # node/bun are still provisioned from mise.toml for parity with local dev.
-      MISE_DISABLE_TOOLS: cargo:hk
+      MISE_DISABLE_TOOLS: cargo:hk,mr-boxington
     steps:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
diff --git a/.github/workflows/sonar.yml b/.github/workflows/sonar.yml
index 517b5eb..d85b276 100644
--- a/.github/workflows/sonar.yml
+++ b/.github/workflows/sonar.yml
@@ -28,6 +28,9 @@ jobs:
           fetch-depth: 0
 
       # --- Rust coverage (coverage/rust-lcov.info) ---
+      - name: Install pinned toolchain
+        run: rustup show active-toolchain || rustup toolchain install
+
       # rust-toolchain.toml uses `profile = "minimal"`, so the llvm-tools-preview
       # component (required by cargo-llvm-cov) is not present by default.
       - name: Add llvm-tools-preview component
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d70de4c..021776b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,8 +40,8 @@ cache, via `jdx/mr-boxington-action`. `mise install` also installs `mbx` locally
 `mise.toml`), so a build in one worktree warms every other worktree. Run Cargo through it:
 
 ```bash
-mise exec -- mbx build           # or: mbx test --all-features --locked --workspace
-mbx explain --last               # why a build did or did not hit the cache
+mise exec -- mbx build           # or: mise exec -- mbx test --all-features --locked --workspace
+mise exec -- mbx explain --last  # why a build did or did not hit the cache
 ```
 
 mise's `mr_boxington` Rust option is deliberately not used: a `rust` entry in `mise.toml`