@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mbx/references/github-action.md

@@ -0,0 +1,254 @@
+GitHub Action
+
+GitHub Action [​](#github-action)
+
+[`jdx/mr-boxington-action`](https://github.com/jdx/mr-boxington-action) installs or reuses mbx and configures caching for the job. Start with the default GitHub backend; use a server when you need object sharing across runners. The [action repository](https://github.com/jdx/mr-boxington-action) owns the complete input reference.
+
+## Start with a complete workflow [​](#start-with-a-complete-workflow)
+
+Save this as `.github/workflows/ci.yml`. It uses the runner's Rust toolchain; add your toolchain installation step before the cache action if you pin one.
+
+yaml
+
+```
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: jdx/mr-boxington-action@v1
+      - run: mbx test --workspace
+```
+
+The push to `main` fills the archive for later runs. Pull requests restore it without saving new entries. Most examples below are snippets for an existing job's `steps` list.
+
+## Read the CI summary [​](#read-the-ci-summary)
+
+mbx automatically uses its explanatory CI build summary in GitHub Actions and skips local first-run onboarding. The summary describes mbx's **object cache**; it does not count artifacts Cargo reused directly from the restored target directory or the action's archive downloads and uploads. The action reports archive restore/save results separately. Use `MBX_SUMMARY=short`, `full`, or `off` to override the default; see [build summaries](https://mr-boxington.jdx.dev/configuration#build-summaries).
+
+## GitHub Actions cache [​](#github-actions-cache)
+
+The default backend restores a pruned Cargo target directory and registry from a compatible archive. Cargo can then reuse its own fresh outputs. A new immutable entry is saved after a push to the default branch, or a trusted `workflow_dispatch` run when `save-on-workflow-dispatch` is enabled. Pull requests, including forks, are restore-only.
+
+The action manages target placement for this archive mode. Local defaults for managed targets and link caching may be overridden by the transport; inspect the action's inputs before assuming a local configuration applies unchanged.
+
+yaml
+
+```
+permissions:
+  contents: read
+
+steps:
+  - uses: actions/checkout@v7
+  - uses: jdx/mr-boxington-action@v1
+  - run: mbx test --workspace
+```
+
+Use `github-cache-mode: objects` when several target directories or checkout layouts need to share one entry. This mode exports the actions used or produced by the job and omits the Cargo registry. Cargo may need to download crates again unless you cache those downloads separately.
+
+yaml
+
+```
+- uses: jdx/mr-boxington-action@v1
+  with:
+    github-cache-mode: objects
+```
+
+Change `cache-generation` when a format or policy change should start a new archive series:
+
+yaml
+
+```
+- uses: jdx/mr-boxington-action@v1
+  with:
+    cache-generation: v2
+```
+
+### Match the toolchain [​](#match-the-toolchain)
+
+Generated keys cover the operating system, the architecture, and the identity of the `rustc` on `PATH`, because a store built by one compiler matches nothing under another. Install the toolchain before the action, and name it in the action's `toolchain` input when the build selects its own, as `mbx +1.91 check` does. Advanced workflows can provide complete `cache-key` and `restore-keys` inputs. The `toolchain` input scopes the key; it does not install or select the toolchain for the build.
+
+## Parallel Cargo steps [​](#parallel-cargo-steps)
+
+Run multiple Cargo builds at the same time by starting independent lint or test configurations together using GitHub's [`parallel` step group](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsparallel). mbx gives every compiler they launch one machine-wide CPU and memory budget:
+
+yaml
+
+```
+steps:
+  - uses: actions/checkout@v7
+  - uses: jdx/mr-boxington-action@v1
+  - parallel:
+      - name: Clippy with default features
+        env:
+          CARGO_TARGET_DIR: ${{ runner.temp }}/clippy-default
+        run: mbx clippy --workspace -- -D warnings
+      - name: Clippy with all features and targets
+        env:
+          CARGO_TARGET_DIR: ${{ runner.temp }}/clippy-all
+        run: mbx clippy --workspace --all-features --all-targets -- -D warnings
+```
+
+Each command needs a separate `CARGO_TARGET_DIR`; otherwise Cargo's target directory lock serializes the parallel steps. The mbx store and scheduler stay shared, so the steps run side by side on one CPU and memory budget instead of each Cargo process filling the runner on its own.
+
+Measure the complete job on your workload. See [Parallel builds](https://mr-boxington.jdx.dev/scheduling) for tuning and [Benchmarks](https://mr-boxington.jdx.dev/benchmarks#six-parallel-jobs) for a measured batch.
+
+## Docker builds [​](#docker-builds)
+
+Mount the mbx store and Cargo registry into the container at stable locations. The registry may either be mounted directly at `$CARGO_HOME/registry` or mounted elsewhere and symlinked from there:
+
+sh
+
+```
+docker run --rm \
+  --env CARGO_HOME=/tmp/cargo-home \
+  --env HOME=/tmp/build-home \
+  --mount "type=bind,source=$HOME/.cargo/registry,target=/tmp/host-cargo-registry" \
+  --mount "type=bind,source=$HOME/.cache/mbx,target=/tmp/build-home/.cache/mbx" \
+  builder \
+  sh -c 'mkdir -p "$CARGO_HOME" && ln -s /tmp/host-cargo-registry "$CARGO_HOME/registry" && mbx build'
+```
+
+mbx maps the registry separately from the rest of `CARGO_HOME`, so cached compiler inputs remain portable when that child symlink resolves outside the Cargo home directory.
+
+## Closure bundles for action transports [​](#closure-bundles-for-action-transports)
+
+An action can transport only the cache entries produced or used by its builds, instead of archiving the whole local store. Every completed `mbx` command writes an immutable receipt into the group named by `MBX_CACHE_EXPORT_GROUP`, including commands running in parallel or in different checkouts. `jdx/mr-boxington-action` sets that group itself; another transport assigns a unique opaque value for the job before any build steps run.
+
+A restore phase imports a previously cached bundle:
+
+console
+
+```
+mbx cache import "$RUNNER_TEMP/mbx-cache.tar"
+```
+
+The bundle also carries Cargo's scheduler state for each recorded workspace. When import runs from a matching checkout whose target directory is absent or empty, mbx restores the fingerprints, dep-info, build-script state, and target layout alongside the action closure. Large compiler outputs remain CAS objects and are reflinked or copied into that layout rather than stored twice. Import leaves a non-empty target directory untouched.
+
+A post phase exports the deduplicated closure of every receipt in this job:
+
+console
+
+```
+mbx cache export --group "$MBX_CACHE_EXPORT_GROUP" "$RUNNER_TEMP/mbx-cache.tar"
+```
+
+The group should include the run attempt, job, and matrix identity, or be a fresh random value generated for the run. It identifies builds within one job. It is not the GitHub Actions cache key. A post step should skip saving when no completed build was recorded or when the workflow's trust policy forbids a cache write.
+
+## Manual GitHub cache setup [​](#manual-github-cache-setup)
+
+The equivalent pieces can be assembled directly when Cargo download caches or custom save policies need to share the same entry:
+
+yaml
+
+```
+- uses: actions/cache@v6
+  with:
+    path: |
+      ~/.cargo/registry
+      ~/.cargo/git
+      ~/.cargo/.global-cache
+      ~/.cache/mbx
+    key: ${{ runner.os }}-${{ runner.arch }}-mbx-${{ github.sha }}
+    restore-keys: |
+      ${{ runner.os }}-${{ runner.arch }}-mbx-
+- uses: jdx/mise-action@v4
+  with:
+    cache: false
+    install_args: mr-boxington
+- run: mbx test --workspace
+- run: mbx gc --max-size 3GB
+  if: always()
+```
+
+Use `actions/cache/restore` instead of `actions/cache` in pull requests so the restore action does not also save an entry. Storage permissions and workflow trust still determine what code in the job can access.
+
+Pin actions in production
+
+The examples use major tags for readability. Pin third-party actions to full commit SHAs in a real workflow.
+
+## Cache server [​](#cache-server)
+
+For trusted runners and teams, mbx can talk to a compatible remote server such as the self-hostable [cache server](https://mr-boxington.jdx.dev/cache-server). The action exports the remote configuration for subsequent steps:
+
+yaml
+
+```
+permissions:
+  contents: read
+  id-token: write
+
+steps:
+  - uses: actions/checkout@v7
+  - uses: jdx/mr-boxington-action@v1
+    with:
+      backend: server
+      server-url: https://cache.example.com
+      namespace: acme/backend
+      oidc-audience: mbx-cache
+  - run: mbx build --workspace --all-features
+```
+
+Only a push to a protected branch may write. Pull requests and tag or release builds degrade to read-only. If fork authors must not reach the host, use the GitHub backend for those jobs instead. A bearer token can be supplied with the action's `token` input when OIDC is unavailable.
+
+## S3-compatible bucket [​](#s3-compatible-bucket)
+
+A bucket needs nothing running. [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) exchanges the runner's OIDC token for a role and exports the credentials mbx reads, so no long-lived secret is stored:
+
+yaml
+
+```
+permissions:
+  contents: read
+  id-token: write
+
+env:
+  MBX_REMOTE_URL: s3://acme-build-cache
+  MBX_REMOTE_NAMESPACE: acme/backend
+
+steps:
+  - uses: actions/checkout@v7
+  - uses: aws-actions/configure-aws-credentials@v5
+    with:
+      role-to-assume: arn:aws:iam::111122223333:role/mbx-cache
+      aws-region: us-west-2
+  - uses: jdx/mise-action@v4
+    with:
+      cache: false
+      install_args: mr-boxington
+  - run: mbx build --workspace --all-features
+```
+
+This example installs mbx with `jdx/mise-action` instead of [`jdx/mr-boxington-action`](https://github.com/jdx/mr-boxington-action), because the action's GitHub Actions cache backend would store the same actions a second time. Use one or the other.
+
+mbx still refuses to publish from a pull request. A bucket has no server to authorize anything, so make IAM agree: scope the role's trust policy to the branches allowed to assume it, and give pull request jobs a role that can only read. See [remote cache](https://mr-boxington.jdx.dev/remote-cache#who-may-publish).
+
+## Production releases [​](#production-releases)
+
+Keep published artifacts independent of remote compiler caches
+
+A production release may still use `mbx` and its local cache, but should not use a remote cache so a cache-poisoning attack cannot influence published artifacts. Release jobs should also avoid restoring or saving compiler outputs through `actions/cache` or the GitHub backend. The client's tag/release write restriction does not disable remote reads automatically: remove remote configuration and archive restore steps explicitly.
+
+For a repository that combines both backends, the server for trusted runs and the GitHub cache for fork pull requests, see [CI with fork pull requests](https://mr-boxington.jdx.dev/cookbook/fork-prs).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/github-action.md)
+
+Last updated:
+
+Pager
+
+[Previous pageStandalone C and C++](https://mr-boxington.jdx.dev/standalone-builds)
+
+[Next pageMigrate an existing cache](https://mr-boxington.jdx.dev/cookbook/migrate)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,59 @@
+Documentation
+
+Documentation [​](#documentation)
+
+mbx adds a shared compiler cache and automatic storage management to Cargo. Start with a local build, then add the integrations your workflow needs.
+
+## Start here [​](#start-here)
+
+[Get started](https://mr-boxington.jdx.dev/getting-started) takes you from installation to your first cached build. For platform-specific downloads, see [Installation](https://mr-boxington.jdx.dev/installation). For automatic Cargo wrapping and rust-analyzer, see [Cargo and editor setup](https://mr-boxington.jdx.dev/setup).
+
+## Work locally [​](#work-locally)
+
+| Task | Guide |
+| --- | --- |
+| Use editors, watch loops, or a debugger | [Local development](https://mr-boxington.jdx.dev/cookbook/local-development) |
+| Run tests and Clippy at the same time | [Parallel builds](https://mr-boxington.jdx.dev/scheduling) |
+| Understand what is stored or deleted | [Managed target directories](https://mr-boxington.jdx.dev/managed-targets) |
+| Tune repeated source edits | [Incremental builds](https://mr-boxington.jdx.dev/incremental) |
+| Select a linker by profile and target | [Managed linkers](https://mr-boxington.jdx.dev/linkers) |
+| Watch compiler and cache activity | [Watching builds](https://mr-boxington.jdx.dev/tui) |
+| Cache make or CMake compiler calls | [Standalone C and C++](https://mr-boxington.jdx.dev/standalone-builds) |
+
+## Set up CI and sharing [​](#set-up-ci-and-sharing)
+
+| Task | Guide |
+| --- | --- |
+| Add caching to a GitHub Actions job | [GitHub Action](https://mr-boxington.jdx.dev/github-action) |
+| Replace an existing caching step | [Migrate from rust-cache or sccache](https://mr-boxington.jdx.dev/cookbook/migrate) |
+| Support pull requests from forks | [CI with fork pull requests](https://mr-boxington.jdx.dev/cookbook/fork-prs) |
+| Connect a server or S3-compatible bucket | [Remote cache](https://mr-boxington.jdx.dev/remote-cache) |
+| Operate the reference server | [Cache server](https://mr-boxington.jdx.dev/cache-server) |
+
+## Understand a result [​](#understand-a-result)
+
+Start with [Troubleshooting](https://mr-boxington.jdx.dev/troubleshooting) for an unexpected build. Read [Cache results](https://mr-boxington.jdx.dev/cache-results) to interpret the counters, [How it works](https://mr-boxington.jdx.dev/how-it-works) for the architecture, and [Caching limits](https://mr-boxington.jdx.dev/limits) for invocations mbx bypasses.
+
+Use [Savings and statistics](https://mr-boxington.jdx.dev/stats) for lifetime totals and workspace sharing, or [Watching builds](https://mr-boxington.jdx.dev/tui) to explore live activity and per-build insights.
+
+[Benchmarks](https://mr-boxington.jdx.dev/benchmarks) includes measured results and the method behind them. [How mbx compares](https://mr-boxington.jdx.dev/compared) explains the tradeoffs with other caches and Cargo's incremental compilation.
+
+## Look something up [​](#look-something-up)
+
+- [Configuration](https://mr-boxington.jdx.dev/configuration): file locations, precedence, and every setting.
+- [CLI reference](https://mr-boxington.jdx.dev/cli/): command syntax, flags, and arguments.
+- [Stability](https://mr-boxington.jdx.dev/stability): upgrade behavior and supported output formats.
+- [Protocol compatibility](https://mr-boxington.jdx.dev/protocol-compatibility): local, remote, and Rust API contracts.
+- [FAQ](https://mr-boxington.jdx.dev/faq): common questions and the story behind the name.
+
+To improve these docs or contribute code, read [Contributing](https://github.com/jdx/mr-boxington/blob/main/CONTRIBUTING.md). The [acknowledgements](https://mr-boxington.jdx.dev/acknowledgements) recognize the projects mbx builds on.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/guide.md)
+
+Last updated:
+
+Pager
+
+[Next pageGet started](https://mr-boxington.jdx.dev/getting-started)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/how-it-works.md

@@ -0,0 +1,86 @@
+How it works
+
+How it works [​](#how-it-works)
+
+mbx works at the compiler boundary. Cargo decides which tools need to run; mbx decides whether each eligible invocation can be restored from cached work. An **action** is one modeled invocation and its inputs. The **content-addressed store** (CAS) holds outputs under digests of their content.
+
+Run `mbx build` directly, or use ordinary `cargo build` after [enabling automatic wrapping](https://mr-boxington.jdx.dev/setup). Both follow the same build lifecycle.
+
+## From command to result [​](#from-command-to-result)
+
+1. mbx resolves the workspace and target roots through Cargo metadata.
+2. It starts an in-process cache agent and creates shims for the build.
+3. Cargo runs normally with the rustc shim set as `RUSTC_WRAPPER`, and build scripts inherit `HOST_CC` and `HOST_CXX` pointing at the C and C++ shims.
+4. Each shim analyzes its compiler invocation and derives a content-addressed action key.
+5. A hit restores the action's outputs; a miss runs the real compiler and publishes the result. The compiler's diagnostics and artifact notifications reach Cargo as rustc prints them, so Cargo starts a crate's dependents against its metadata while code generation and publication continue, the same as without mbx. `forward_compiler_notifications = false` ( `MBX_FORWARD_COMPILER_NOTIFICATIONS=0`) holds the output until the result is stored, for diagnosing the shim.
+6. The agent exits with the build, draining any remote uploads it still owes. There is no persistent daemon.
+
+That wrapper boundary also covers multiple Cargo builds running at the same time. Their compiler shims share a machine-wide permit pool and an in-flight-work registry, so those builds do not multiply the machine's CPU and memory budgets or repeat an identical cold compilation. [Machine-wide scheduling](#machine-wide-scheduling) below describes the mechanism, and the [mise task example](https://mr-boxington.jdx.dev/scheduling#run-independent-tasks) and [parallel GitHub Actions example](https://mr-boxington.jdx.dev/github-action#parallel-cargo-steps) are ready-to-use recipes.
+
+## Build-script C and C++ [​](#build-script-c-and-c)
+
+Cargo has no `CC_WRAPPER`, so the shims arrive as compiler variables themselves, resolved to the platform compilers when the session starts. They are set as `HOST_CC` and `HOST_CXX` rather than `CC` and `CXX`: the `cc` crate consults the host pair only when it is not cross-compiling, and these shims wrap the host compiler, so a `cargo build --target` keeps the cross compiler it would have found on its own. An explicit host compiler in `CC`, `CXX`, `HOST_CC`, or `HOST_CXX` is left alone. Explicit target compilers can be wrapped; see the [C and C++ limits](https://mr-boxington.jdx.dev/limits#c-and-c-caching-covers-the-host-compiles-mbx-drives). `MBX_CC=0` turns this caching off.
+
+The C shim requests a private dependency list and keys the compilation on the files it names. A cold call may need to compile before that list is known; the stored result and prediction can serve later builds.
+
+If the build requests its own depfile with `-MD` or `-MMD`, mbx writes one on both a compilation and a cache hit. Depfile formatting flags affect that file without changing the object-cache key.
+
+The key also records include-directory names that could change which header an `#include` resolves to. Adding a header that shadows an existing one must invalidate the result even if every previously read file is unchanged. See [include shadowing](https://mr-boxington.jdx.dev/limits#shadowing-is-modeled-by-name-not-by-content) for the manifest rules.
+
+## Portable keys [​](#portable-keys)
+
+Known workspace, target, Cargo registry, toolchain, and sysroot paths are mapped to stable placeholders before they enter a key. That is what lets equivalent worktrees share an action even though their absolute paths differ.
+
+The key also covers compiler inputs and relevant environment. If mbx cannot model something exactly, it bypasses the action.
+
+## Prediction and dep-info [​](#prediction-and-dep-info)
+
+A rustc action key depends on the files that compilation actually reads. mbx learns that set from Cargo/rustc dep-info left by an earlier build and records a prediction for later invocations. A cold compilation may therefore have no key to look up yet. It still gets stored after compiling and can warm the next build.
+
+Predictions are grouped by the `Cargo.lock` digest. When a dependency update creates a new group, mbx looks for earlier predictions in up to eight lockfile states from Git history, then in recent local store records. Each borrowed prediction is checked against the current inputs: unchanged crates can hit, while changed crates compile and record new predictions.
+
+mbx saves the borrowed record under the new lockfile for subsequent commands, and eligible trusted CI builds publish it remotely. A shallow clone limits which history is available. For GitHub Actions' default pull-request merge checkout, `fetch-depth: 2` includes the base parent; a depth-one checkout relies on local store records.
+
+Hashing those files is shared too. The agent keeps a ledger of every file a shim has hashed, keyed by the file's length, modification time, and change time, so a dependency's rlib is read once however many crates link it. The ledger is saved with the checkout's private state when the build finishes and loaded by its next build, avoiding repeated reads of unchanged dependencies. Reuse depends on the file-identity checks supported by that filesystem; network filesystems receive additional content validation. If an entry cannot be validated, mbx hashes the file again.
+
+## Rustdoc actions [​](#rustdoc-actions)
+
+Cargo invokes rustdoc through a separate shim. Each documentation action keys the rustdoc version and arguments, the package source tree, explicit compiler artifacts, and Cargo's compile-time environment. Rustdoc's mergeable-output mode separates deterministic per-crate pages from files such as the search index that combine every documented crate. mbx caches the former with the crate's merge metadata and runs rustdoc's inexpensive finalization step after restoring them, so cached dependency documentation remains composable and the shared indexes do not depend on restore order.
+
+## Copy-on-write output restoration [​](#copy-on-write-output-restoration)
+
+The cache agent verifies each local CAS blob against its digest before returning it to the rustc wrapper. The wrapper first tries to reflink that verified blob into a staging directory beside Cargo's destination, applies the expected file mode, and atomically renames it into place. A reflink is an ordinary file that shares its data blocks with the CAS until either copy is written, so Cargo sees the complete output immediately without the wrapper re-reading or allocating all of its data after verification. Writes to a restored output cannot change the CAS object.
+
+Reflinks require support from the filesystem and generally require the cache and target directory to be on the same filesystem. When cloning is unavailable, mbx copies the bytes instead. The session summary reports the file count and logical size handled by each path; `MBX_STATS_REPORT` includes the same values as `reflinked_output_files`, `reflinked_output_bytes`, `copied_output_files`, and `copied_output_bytes`.
+
+This is filesystem copy-on-write, not a placeholder or userspace on-demand filesystem. Restored paths retain normal file semantics on every supported platform, including when mbx has to use the copy fallback.
+
+## Machine-wide scheduling [​](#machine-wide-scheduling)
+
+Every compiler mbx starts takes a permit from one pool shared by every build on the machine, so simultaneous builds do not multiply the machine's CPU and memory budgets. Cache hits never wait, Cargo keeps its own dependency scheduling, and permits are released by the kernel if a process dies, so a crashed build cannot wedge its siblings.
+
+Concurrent builds also stop repeating each other. Separate CI jobs with fresh targets can otherwise repeat the same dependency compilations. With mbx, a compilation identical to one already running against the same local cache waits for that one to finish and restores its result from the cache. The finished compilation also leaves its input list behind, so a job arriving after it is already done can build the cache key it would otherwise lack and hit where it would have compiled cold. Both paths rehash every input before trusting anything, so the worst a stale record can do is fall back to compiling.
+
+Permits are weighted by memory. Native links start at two permits, and every compilation is thereafter weighted by what it actually used, so admission uses the estimated memory cost of the running work. This is a scheduling estimate, not an operating-system memory limit. A link that turns out to fit in one permit stops being charged for two, which keeps the link-heavy tail of a build from running at half concurrency. A link mbx has never seen is weighed by the heaviest of this machine's recent links; test binaries each have their own crate name, so a cold `cargo test --no-run` has no per-crate history for the links in front of it. A compilation the Linux OOM killer stops is recorded heavier than it measured, so its retry runs with more room.
+
+The pool size, memory budget, and priority are settings; see [machine-wide compile scheduling](https://mr-boxington.jdx.dev/scheduling#machine-wide-compile-scheduling).
+
+## What remains local [​](#what-remains-local)
+
+Cargo's target state belongs to a workspace. Learned incremental state belongs to a checkout and never enters the shared cache. A configured remote receives eligible shared actions according to the [write policy](https://mr-boxington.jdx.dev/remote-cache#read-and-write-policy). [Managed targets](https://mr-boxington.jdx.dev/managed-targets) and garbage collection control local retention.
+
+## Correctness first [​](#correctness-first)
+
+Unsupported crate types, unmodeled search paths, and incremental compilations bypass the shared action cache. That includes the private incremental state of [learned incremental reuse](https://mr-boxington.jdx.dev/incremental#learned-incremental-reuse), which is never published. A compilation that links nothing is cached whatever its crate type: `cargo check` and clippy compile every binary and test target that way. A native link is admitted only when its linker can be described: host binaries, tests, and proc macros on Linux, macOS, and Windows, where mbx puts the resolved linker, startup objects, C runtime, and SDK into the key, and a fixed allowlist of built-in WebAssembly targets whose default linker and system inputs ship with rustc. Everything else (native libraries, custom linkers, unrecognized toolchains) links as it always did; see [limits](https://mr-boxington.jdx.dev/limits#native-linking-is-cached-only-where-the-linker-can-be-described). A library that names a native library is cached: nothing links, so a `-l static` archive is hashed into its key like an `--extern` artifact, and other `-l` kinds are keyed by name; see [limits](https://mr-boxington.jdx.dev/limits#native-libraries-are-inputs-where-nothing-links). `MBX_VERIFY=1` compiles while also consulting the cache and compares the result, an expensive qualification mode.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/how-it-works.md)
+
+Last updated:
+
+Pager
+
+[Previous pageSavings and statistics](https://mr-boxington.jdx.dev/stats)
+
+[Next pageCaching limits](https://mr-boxington.jdx.dev/limits)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,78 @@
+Incremental builds
+
+Incremental builds [​](#incremental-builds)
+
+mbx automatically keeps private incremental state for crates you edit. Unchanged work remains eligible for the shared cache. Leave the defaults in place for a normal edit/build loop.
+
+| Mode | What is reused | Scope |
+| --- | --- | --- |
+| Shared action cache | Complete matching compiler outputs | Across equivalent builds and checkouts |
+| Learned incremental reuse | Intermediate work from earlier source edits | Private to one checkout |
+| Cargo incremental mode | Cargo-managed incremental state | Private to Cargo's target directory |
+
+## Learned incremental reuse [​](#learned-incremental-reuse)
+
+An edited crate has new source content, so its old shared result cannot match. On the first source edit to a workspace crate, mbx compiles it with private incremental state. A crate outside the workspace switches after three consecutive misses with changed sources. The build reports this work as `incremental`; the result never enters the shared cache.
+
+The trigger is a source change. An unchanged crate in a fresh target or a new checkout still compiles and publishes normally when it misses the cache. Dependents of a crate using private incremental state also keep private state: their inputs contain an artifact other checkouts cannot share. That part of the build can publish again once the edited crate settles. Later edits to a known active crate go directly to its private state.
+
+### Where state lives [​](#where-state-lives)
+
+State and its records live under `incremental/` in the mbx cache directory, separately for each checkout. `cargo clean` does not remove this state. `mbx clean` and `mbx cache remove` remove it for the selected workspace. Garbage collection removes it for deleted, expired, or least-recently-used checkouts; state used by a running build is never removed.
+
+### Bound the storage [​](#bound-the-storage)
+
+`learned_incremental_max_size` limits each crate to `8GiB` by default. Once a crate exceeds that limit, mbx warns and discards its state before the next compilation. Set it in your global configuration:
+
+toml
+
+```
+learned_incremental_max_size = "12GiB"
+```
+
+The environment equivalent is `MBX_LEARNED_INCREMENTAL_MAX_SIZE`; `"none"` disables the limit. rustc normally removes superseded sessions, so the budget is a backstop. A large debug build can need several GiB. If the warning appears on every edit, the limit may be too small to retain useful state: raising it can prevent repeated full recompilations.
+
+Garbage collection also bounds private state across all checkouts with `gc.incremental_max_size`, which defaults to 5% of the cache disk between 10 GiB and 100 GiB. `gc.incremental_max_age` defaults to 30 days. The least-recently-used checkouts are collected first, while mbx keeps the most recent one even when it alone exceeds the aggregate budget:
+
+toml
+
+```
+[gc]
+incremental_max_size = "30GiB" # or "none"
+incremental_max_age = "14d"    # or "none"
+```
+
+`gc.max_total_size`, when set, covers the action store, managed targets, and learned incremental state together.
+
+## Cargo incremental mode [​](#cargo-incremental-mode)
+
+By default, mbx sets `CARGO_INCREMENTAL=0` and uses learned incremental reuse for changing crates. `MBX_INCREMENTAL=1` stops it from forcing Cargo's setting off locally:
+
+sh
+
+```
+MBX_INCREMENTAL=1 mbx build
+```
+
+This lets Cargo manage incremental workspace compilation. Those artifacts remain checkout-specific and bypass the shared cache; their dependents may also miss. Use it only when you want that tradeoff.
+
+## Overrides and CI [​](#overrides-and-ci)
+
+- `MBX_LEARNED_INCREMENTAL=0` disables learned incremental reuse.
+- `MBX_INCREMENTAL=1` supersedes it by handing incremental control to Cargo.
+- `MBX_VERIFY=1` disables it for the build being verified.
+- CI disables both incremental policies because a fresh runner has no earlier edit state to reuse.
+
+Use [Cache results](https://mr-boxington.jdx.dev/cache-results) to distinguish private incremental work from ordinary misses. The [local-edit benchmark](https://mr-boxington.jdx.dev/benchmarks#local-edit) reports both the initial state-building cost and a later edit.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/incremental.md)
+
+Last updated:
+
+Pager
+
+[Previous pageParallel builds](https://mr-boxington.jdx.dev/scheduling)
+
+[Next pageManaged linkers](https://mr-boxington.jdx.dev/linkers)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,57 @@
+A shared cache for Cargo builds
+
+# mr boxingtonA shared cache.<br>A tidier `target/`.
+
+Reuse Cargo builds across worktrees and CI. Keep the workflow you already have.
+
+[Get started](https://mr-boxington.jdx.dev/getting-started)
+
+`mise use --global --tool-option mr_boxington=true rust mr-boxington` Copy
+
+Linux · macOS · Windows [More install options ↗](https://mr-boxington.jdx.dev/installation)
+
+![Mr Boxington, a cardboard cache box wearing a monocle and bow tie](https://mr-boxington.jdx.dev/logo.svg)
+
+Build here. Reuse there.
+
+## A new worktree.<br>A head start.
+
+Build once, then restore matching work from another checkout or CI.
+
+[How the cache travels →](https://mr-boxington.jdx.dev/how-it-works#portable-keys)
+
+● ● ●two worktrees / one storeillustration
+
+First build New worktree
+
+\~/project$ mbx build
+
+Compilinglibcstored for later
+
+Compilingserdestored for later
+
+Compilingyour-appstored for later
+
+Freshly compiled. Safely tucked away.
+
+While Cargo does its work
+
+## A little company for the compile.
+
+![Animated Boxington mascot beside mbx build output showing live and completed crates](https://mr-boxington.jdx.dev/screenshots/cargo-pretty.gif)
+
+*Build output during a rebuild. Pause animation*
+
+Your cache, in plain sight
+
+## Watch the work you don’t have to do.
+
+LiveInsightsStoreExample build data
+
+[![mbx Live dashboard with build activity, hit and miss graphs, store capacity, and compilation savings](https://mr-boxington.jdx.dev/screenshots/tui-live.png)](https://mr-boxington.jdx.dev/screenshots/tui-live.png)
+
+*Follow every build, watch cache traffic, and spot the biggest wins. [ View full size ↗](https://mr-boxington.jdx.dev/screenshots/tui-live.png)*
+
+[Explore the dashboard →](https://mr-boxington.jdx.dev/tui)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,101 @@
+Installation
+
+Installation [​](#installation)
+
+mbx uses your existing Rust toolchain. Install Cargo and rustc before running a build; `mbx doctor` checks which tools are active.
+
+## mise [​](#mise)
+
+sh
+
+```
+mise use --global --tool-option mr_boxington=true rust mr-boxington
+```
+
+Requires mise 2026.9.2 or newer. This installs Rust and mbx and enables Cargo wrapping through mise; no `mbx setup` postinstall hook is needed. `--tool-option` applies to the following tool, so keep it before `rust`. Drop `--global` to enable it only in the current project. Keep an existing Rust version pin by [editing its tool entry](https://mr-boxington.jdx.dev/setup#share-setup-with-a-project).
+
+Use `mise exec -- cargo build`, or open a shell with mise activation or shims on `PATH` and follow [Verify plain Cargo](https://mr-boxington.jdx.dev/setup#verify-plain-cargo). The Rust option does not install a standalone mbx shim or configure rust-analyzer; see [editor setup](https://mr-boxington.jdx.dev/setup#rust-analyzer) if you need that too.
+
+### Older mise versions [​](#older-mise-versions)
+
+With mise 2026.8.16 through 2026.9.1:
+
+sh
+
+```
+mise use --global --postinstall "mbx setup --yes" mr-boxington
+```
+
+This runs standalone setup and writes an explicit `[wrappers.cargo]` entry. Versions older than 2026.8.16 install the standalone shim and print an upgrade warning instead of editing mise configuration.
+
+## Cargo [​](#cargo)
+
+sh
+
+```
+cargo install mbx --locked
+mbx --version
+```
+
+You can now run `mbx build` in a Rust workspace. To make plain `cargo` commands use mbx too, run [`mbx setup`](https://mr-boxington.jdx.dev/setup).
+
+## Release archives [​](#release-archives)
+
+Linux x86-64Linux ARM64macOS Apple SiliconWindows x86-64Windows ARM64
+
+sh
+
+```
+mkdir -p ~/.local/bin
+archive=mbx-x86_64-unknown-linux-gnu.tar.gz
+release=https://github.com/jdx/mr-boxington/releases/latest/download
+curl -fsSLO "$release/$archive" &&
+  curl -fsSLO "$release/SHA256SUMS" &&
+  grep "  $archive$" SHA256SUMS | sha256sum --check --strict - &&
+  tar -xzf "$archive" -C ~/.local/bin
+```
+
+Every release publishes its archives and `SHA256SUMS` on [GitHub Releases](https://github.com/jdx/mr-boxington/releases). Linux also has `-musl` archives for a static binary that does not depend on a host glibc.
+
+After extracting an archive, put its directory on `PATH`, then run `mbx --version` and `mbx doctor`. Run `mbx setup` to enable [automatic Cargo wrapping](https://mr-boxington.jdx.dev/setup).
+
+## Supported platforms [​](#supported-platforms)
+
+Release binaries cover:
+
+- Linux x86-64 and ARM64 (GNU and static musl builds)
+- macOS on Apple Silicon
+- Windows x86-64 and ARM64
+
+Other platforms with a Rust toolchain can build from source with `cargo install mbx --locked`. mbx wraps whichever Cargo and rustc are active, including rustup-managed toolchains. `mbx doctor` reports the pair it found.
+
+Reflinked output restoration needs a filesystem with copy-on-write file cloning: APFS on macOS, btrfs or XFS on Linux, ReFS (Dev Drive) on Windows. mbx probes the cache and target locations and copies bytes where cloning is unavailable. Caching still works on ext4 or NTFS, but the store and restored outputs occupy separate disk space.
+
+### Windows [​](#windows)
+
+Windows is a supported release platform. The differences from Linux and macOS:
+
+- Reflinks need ReFS, which usually means a Dev Drive; on NTFS mbx copies bytes instead.
+- The managed `target` link needs Developer Mode or a privileged process; where Windows refuses to create it, Cargo keeps its ordinary target directory. See [managed target directories](https://mr-boxington.jdx.dev/managed-targets).
+- rustc compilations and native host links are cached; native-link keys bind the selected MSVC/LLVM linker, Windows SDK, and CRT. See [limits](https://mr-boxington.jdx.dev/limits#native-linking-is-cached-only-where-the-linker-can-be-described).
+- MSVC C and C++ compiles from build scripts and `mbx exec` are cached through a conservative `cl.exe` adapter. See [limits](https://mr-boxington.jdx.dev/limits#c-and-c-caching-covers-the-host-compiles-mbx-drives).
+
+## Upgrade or uninstall [​](#upgrade-or-uninstall)
+
+Upgrade using the same installation method: update the mise version, rerun `cargo install mbx --locked`, or replace the binary with a verified release archive. The stable Cargo shim follows upgrades; setup does not need to run again.
+
+Before removing the executable, disable `mr_boxington` in each Rust tool entry where you enabled it. If you also ran standalone setup, run `mbx setup --uninstall` in each scope you enabled. See [Remove automatic wrapping](https://mr-boxington.jdx.dev/setup#remove-automatic-wrapping). Cached work is disposable; use [cache management](https://mr-boxington.jdx.dev/managed-targets) to inspect and reclaim it.
+
+Continue with [your first build](https://mr-boxington.jdx.dev/getting-started#run-a-build).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/installation.md)
+
+Last updated:
+
+Pager
+
+[Previous pageGet started](https://mr-boxington.jdx.dev/getting-started)
+
+[Next pageCargo & editor setup](https://mr-boxington.jdx.dev/setup)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)