@xgent-ai/skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,182 @@
+Caching limits
+
+Caching limits [​](#limits)
+
+When mbx cannot model a compilation exactly, it runs the compiler and does not cache the result. A bypass preserves the build; it reduces reuse. Run `mbx explain --last` to identify the reason for a particular action.
+
+| Work | Cache behavior |
+| --- | --- |
+| Rust compilations without a link | Eligible when inputs can be modeled |
+| Rust libraries naming a native library (`-l`) | Eligible; a `-l static` archive is hashed into the key |
+| Native executables, tests, and proc macros | Eligible on described Linux, macOS, and Windows hosts |
+| Built-in self-contained WebAssembly links | Eligible for the targets listed below |
+| Build-script execution | Eligible using Cargo's declared freshness inputs |
+| C and C++ object compilation | Eligible through supported compiler wrappers |
+| GCC/Clang preprocessing to a file | Eligible, with checkout-specific keys |
+| Incremental state | Private to the checkout; never shared |
+| Unknown flags, inputs, or extra outputs | Runs without shared caching |
+
+The sections below spell out the boundaries. For an unexpected result, start with [Troubleshooting](https://mr-boxington.jdx.dev/troubleshooting).
+
+## Build-script execution follows Cargo's freshness inputs [​](#build-script-execution-follows-cargo-s-freshness-inputs)
+
+mbx caches running `build.rs`, not only compiling it. After a successful first run, the script's `cargo:rerun-if-changed` and `cargo:rerun-if-env-changed` directives become the input prediction for later runs. The build-script binary, Cargo's implicit unit environment (target, profile, features, configuration, and package metadata), the recursively hashed declared paths, and the declared environment values form the action key. A hit restores the complete `OUT_DIR` tree and replays the script's stdout directives and stderr without starting the script. Directories and missing paths are inputs too, matching Cargo's directive model.
+
+Set `build_script_execution = false` or `MBX_BUILD_SCRIPT_EXECUTION=0` to turn off this layer while retaining ordinary Rust and C/C++ compilation caching.
+
+A script that emits neither kind of rerun directive uses Cargo's package-wide default. mbx hashes the package tree into the action key, excluding the target directory and version-control metadata. This content key is stricter than Cargo's timestamp check while remaining portable across equivalent checkouts.
+
+Cached directives remap `OUT_DIR`, manifest/workspace and target roots, and `CARGO_HOME` to the restoring environment. Output trees that do not contain the literal output directory path can therefore cross target directories; an output file that embeds that path keeps it in the action key and only reuses the result at the same location. A symlink that may escape `OUT_DIR` makes the execution uncacheable. The launcher left in a target directory is transparent when the build later runs under plain Cargo, outside an mbx session.
+
+## Incremental compilations are not cached [​](#incremental-compilations-are-not-cached)
+
+Incremental compilations bypass the action cache. Dependencies, which Cargo builds non-incrementally, remain cacheable, and they are the bulk of a cold build.
+
+By default mbx forces `CARGO_INCREMENTAL=0` and instead gives a crate whose sources keep changing its own private incremental state; see [learned incremental reuse](https://mr-boxington.jdx.dev/incremental#learned-incremental-reuse). Those compilations are never published to the shared cache. See [incremental builds](https://mr-boxington.jdx.dev/incremental) for the trade `MBX_INCREMENTAL=1` makes.
+
+## Native linking is cached only where the linker can be described [​](#native-linking-is-cached-only-where-the-linker-can-be-described)
+
+Native binaries and dynamic libraries link against an external linker, startup objects, and system libraries that rustc dep-info does not enumerate. mbx caches such a link only when it can put all of that into the key, and bypasses it otherwise.
+
+WebAssembly needs nothing extra: a binary, test, or `cdylib` for one of these built-in targets uses its compiler-bundled self-contained linker, so it is cached on every platform:
+
+- `wasm32-unknown-unknown`
+- `wasm32-wasip1` and `wasm32-wasip1-threads`
+- `wasm32-wasip2`
+- `wasm32v1-none`
+- `wasm64-unknown-unknown`
+
+mbx caches those links because all explicit artifacts are modeled inputs and the linker, CRT objects, and bundled libc are covered by the Rust toolchain identity. Custom target specifications, external WebAssembly toolchains, native libraries, unrecognized custom linkers, disabled WASI CRT bundling, and non-affirmative `link-self-contained` modes remain uncached.
+
+Host test binaries, executables, and proc macros are cached on Linux, macOS, and Windows by putting the rest of the link into the key: the resolved `cc` driver and its version, the linker it selects, the startup objects and libc it resolves (hashed), and on macOS the SDK. On Windows the key identifies `link.exe` or `lld-link`, the MSVC toolset and Windows SDK versions, and the selected VC and Universal CRT libraries. Two hosts that differ in any of those produce different keys and miss. `cache_links` (`MBX_CACHE_LINKS=0`) turns it off.
+
+Some hosts cannot be described. mbx asks the driver to place a startup object and a libc; a host where neither resolves gets no linker identity and no cached links, because two hosts failing the same probe would otherwise agree on a key without either having pinned what it stood for. The same goes for a driver that names no linker or reports no version. Those links appear in `mbx explain` like any other bypass.
+
+Even then, a link bypasses if it names a native library (`-l`, which a build script emits as `cargo:rustc-link-lib`), overrides the linker, or carries a flag that would embed this checkout's paths (`-Crpath`, `-Cprefer-dynamic`) or leave a file beside the binary that mbx does not store (`-Csplit-debuginfo`). On macOS a debug-info link records absolute object paths and their timestamps in the binary's debug map, so the shim passes ld64 `-oso_prefix` for its own output directory, which lets those links cache. An explicit `--target` bypasses too, even when it spells the host triple: rustc without one links for the host, and that is the only linker mbx identifies.
+
+## Native libraries are inputs where nothing links [​](#native-libraries-are-inputs-where-nothing-links)
+
+A library compilation runs no linker, so a `-l` flag on it is not a linker argument. `-sys` crates whose build script emits `cargo:rustc-link-lib` (for example `zstd-sys`, `ring`, `aws-lc-sys`, `libz-sys`, and `openssl-sys` when linking statically) compile their rlib this way, and mbx caches those compilations.
+
+For `-l static=NAME`, rustc reads the archive and bundles it into the rlib. mbx resolves the file the way rustc does, taking the first `-L native` directory in command-line order that holds `libNAME.a` (or `NAME.lib` on Windows MSVC and UEFI targets; the literal name with `+verbatim`), and hashes it into the action key exactly like an `--extern` artifact. A rebuilt archive with the same name therefore gives the library a new key, on a fresh compilation and on a predicted restore alike. If no search directory holds the archive, the compilation bypasses as `missing-native-library`; an archive outside the workspace, target, Cargo, toolchain, and home roots bypasses as `unmapped-absolute-path`, like any other input there. A custom target specification names its archives its own way, so a `-l static` compile for one bypasses as `custom-target-native-library` unless the flag is `+verbatim`. A bare target name counts as one when a specification file for it exists under `RUST_TARGET_PATH` or in the toolchain's `lib/rustlib` directory.
+
+For `-l static:-bundle=NAME`, `-l dylib=NAME`, `-l framework=NAME`, `-l link-arg=...`, and a plain `-l NAME`, rustc reads nothing and records the name in the crate's metadata for a later link, so the flag enters the key as text.
+
+An archive built with debug information usually records the checkout's C source paths. When the build script that produces it reruns in another checkout, the archive differs and so does the library's key; when [build-script execution](#build-script-execution-follows-cargo-s-freshness-inputs) restores the archive from the cache instead, the bytes match and the library hits there too. Either way the library is reused across builds at the same path, including after the target directory is removed. Linked programs, tests, and proc macros that name a native library still bypass, as described above.
+
+## Restored artifacts are equivalent, not always identical [​](#restored-artifacts-are-equivalent-not-always-identical)
+
+On restore, mbx rewrites dep-info and diagnostics to use the current checkout and target paths. Cargo can then read them as if the compilation ran locally.
+
+The compiled artifacts are reused as they were produced, and a few things can make them differ from what a fresh compilation here would have written. rustc records absolute source paths in metadata and debug information, so artifacts built from two checkouts differ even when the sources are identical. A C or C++ object compiled with debug information does the same, recording the directory the compiler ran in.
+
+A C or C++ object also records the absolute include directories it was given, which is how a `-sys` crate whose build script generates headers into `OUT_DIR` used to produce a different object in every target directory. With [`OUT_DIR` sharing](https://mr-boxington.jdx.dev/configuration#share-out-dir) on (the default), mbx passes the compiler `-fdebug-prefix-map` for that directory, so the object records the same placeholder the key does and two target directories produce the same bytes. An object that still embeds a checkout or target path is stored under a checkout-specific key by default. Set `MBX_CC_STORE_PATH_SPECIFIC=0` to skip storing those objects; existing entries remain readable. Windows debug information can also record the object output path.
+
+These path differences can affect debugging and byte-for-byte comparisons. `MBX_VERIFY=1` reports them as divergences, but a divergence alone does not establish its cause. Inspect the named output and mismatch before attributing it to paths, and report unexplained differences. See [Verify mode](https://mr-boxington.jdx.dev/configuration#verify-mode) for a controlled comparison and the [debugger recipe](https://mr-boxington.jdx.dev/cookbook/local-development#debug-a-binary-restored-from-another-checkout) for a build using local source paths.
+
+## C and C++ caching covers the host compiles mbx drives [​](#c-and-c-caching-covers-the-host-compiles-mbx-drives)
+
+mbx caches the C and C++ a Cargo build script compiles for the host through the `cc` crate, and the C and C++ of a command run under [`mbx exec`](https://mr-boxington.jdx.dev/standalone-builds), which puts shims for the plain driver names on `PATH` for that command alone. A compile outside both paths is not reached. Neither are cross compilations the build did not name a compiler for: a Cargo build installs the shims as `HOST_CC` and `HOST_CXX`, which the `cc` crate consults only when host and target agree, and `mbx exec` shims only `cc`, `c++`, `gcc`, `g++`, `clang`, and `clang++` on Unix, plus `cl.exe` on Windows, leaving a versioned toolchain to the build that chose it.
+
+A cross compile is cached when the build names its own compiler through `CC_<target>`, `CXX_<target>`, `TARGET_CC`, or `TARGET_CXX`: mbx wraps what was named. A cross build that names nothing is left alone, because which compiler a target implies lives in the `cc` crate's own tables, and a wrong guess would build the object with the wrong compiler. A value that is a command, such as `ccache gcc`, is left alone for the same reason.
+
+### Supported compiler calls [​](#supported-compiler-calls)
+
+mbx caches single-source object compiles through GCC-, Clang-, and MSVC-style drivers. Preprocessed assembly (`.S` or `-x assembler-with-cpp`) is supported: its includes participate in dependency discovery, and the assembler is part of the GCC toolchain identity. Known assembler options that add no inputs, such as `-Wa,--noexecstack`, are also supported.
+
+GCC/Clang preprocessing with `-E ... -o file` is cached too. The file is restored byte-for-byte, preserving line markers and `__FILE__` values. These entries key literal argument paths, the working directory, and mapped roots, so they cannot be shared across different checkout paths. Header discovery and include-directory invalidation still apply.
+
+With `-E` and `-MD`/`-MMD`, an explicit `-MF` is required. Without it, GCC gives `-o` a different meaning and mbx bypasses the invocation.
+
+### Calls that bypass the cache [​](#calls-that-bypass-the-cache)
+
+The C/C++ adapter leaves these calls uncached:
+
+- Links, multi-source calls, preprocessing to stdout, and dependency output to stdout ( `-MF -`).
+- Assembly without preprocessing ( `.s`), Objective-C, precompiled headers, coverage instrumentation, compiler plugins, and response files.
+- Unmodeled sub-tool options, including `-Wp,`, `-Wl,`, `-Xclang`, and unsupported `-Wa,` options; assembler-time `.include`, `.sinclude`, and `.incbin` inputs.
+- MSVC compiler PDBs, modules, and other unsupported extra outputs.
+- Sources or headers that expand `__DATE__`, `__TIME__`, or `__TIMESTAMP__`: the result depends on when compilation runs.
+- Host CPU tuning such as `-march=native`: the cache key does not identify the host processor.
+- Any other flag or input the adapter cannot model.
+
+Setting `CC`, `CXX`, `HOST_CC`, or `HOST_CXX` leaves the selected host compiler outside mbx's wrappers. Explicit target compilers are handled as described above. `MBX_CC=0` disables C and C++ caching entirely.
+
+## Shadowing is modeled by name, not by content [​](#shadowing-is-modeled-by-name-not-by-content)
+
+An include directory contributes the names in it that could answer an `#include`: headers, sources (`#include "generated.c"` is unusual but legal), names without an extension, and precompiled headers, which GCC prefers over the header they were built from without anything on the command line saying so.
+
+Objects, dependency files, and archives are left out, because they cannot answer an `#include`. A build writes those into the directory a generated header lives in, and counting them would make the key depend on how many sibling compilations had finished.
+
+Manifests are taken once before the compiler runs and again before publishing. If a search directory changed in between, the compilation bypasses: a header that appeared while the compiler ran is one it never saw, and the key would otherwise claim a state that did not produce this object.
+
+System roots are exempt from manifests. Enumerating an SDK on every compile costs more than the risk, and anything read from one is digested like any other input.
+
+## Share compilations that read `OUT_DIR` [​](#out-dir-sharing)
+
+By default, mbx can reuse Rust compilations across checkouts when their build-script output matches. This includes crates that load generated code:
+
+rust
+
+```
+include!(concat!(env!("OUT_DIR"), "/generated.rs"));
+```
+
+Cargo normally places `OUT_DIR` under each checkout's target directory. That path becomes a cache-key input when a crate reads it, causing a miss in a new checkout even if `generated.rs` is identical. mbx copies the output to `out-dirs/v1/<digest>` under its cache and gives rustc that shared path as `OUT_DIR`. The digest covers the directory layout, file names, contents, and executable bits. Matching output trees therefore use the same path and can reuse the compilation when its other inputs also match.
+
+The literal `OUT_DIR` value remains part of the key. Code that stores the path or derives a value from it sees the same value in both checkouts.
+
+### When sharing is unavailable [​](#when-sharing-is-unavailable)
+
+- **Generated output differs.** A build script that embeds a checkout path in its output produces a different tree and cache key for each checkout.
+- **The source scan misses the reference.** mbx scans Rust files beneath the compiler's input file directory. References found only in external sources, skipped directories, or beyond the scan limit may leave rustc using Cargo's original `OUT_DIR`.
+- **The output cannot be copied.** Trees containing symlinks or unsupported entries are left in place. Copy errors also fall back to Cargo's `OUT_DIR`.
+- **Cache locations differ.** Reuse across machines requires the same absolute cache path, as well as matching output and other compilation inputs.
+
+### Compatibility and cleanup [​](#compatibility-and-cleanup)
+
+For eligible compilations, `env!("OUT_DIR")` names the cached copy. Its files and directories are marked read-only; code that needs to modify generated output during compilation should disable sharing. Build scripts still write their output to the directory Cargo gives them before mbx makes the copy.
+
+`mbx cache stats` reports these copies as **generated source trees**. Automatic collection and `mbx gc` remove copies according to `target.max_age`, based on when mbx last used them for a compilation or cache lookup. The copies share `gc.incremental_max_size` with learned incremental state, least recently used first, and the remaining copies count toward `gc.max_total_size`. A compilation holds a lease on the copy it reads until rustc exits, and collection leaves a leased copy in place. A build Cargo considers fresh does not refresh the use timestamp. mbx recreates an evicted copy when a later compilation needs it, so an embedded `OUT_DIR` path should not be treated as permanent runtime storage.
+
+To preserve Cargo's original `OUT_DIR` and literal generated source paths:
+
+sh
+
+```
+MBX_SHARE_OUT_DIR=0 mbx build
+```
+
+Or set `share_out_dir = false` in the workspace's `.mbx.toml`. Rust compilations that read `OUT_DIR` then remain checkout-specific.
+
+The setting also controls generated source path remapping in debug information: `--remap-path-prefix` for Rust and `-fdebug-prefix-map` for C/C++. C and C++ compilations use the original build-script output directory; the shared copy described above is supplied to rustc.
+
+## A rebuilt workspace crate records its checkout [​](#a-rebuilt-workspace-crate-records-its-checkout)
+
+Cargo runs rustc with the crate's own directory as the working directory, and rustc stores that directory in the artifact. Two checkouts of the same commit therefore produce different bytes for the same workspace crate whenever it is actually compiled rather than restored, and every crate above it misses too, because what it consumes differs.
+
+Most builds never see this: a workspace crate that can be restored is restored, byte for byte. It shows up where a crate has to be compiled in each checkout anyway, which is what a compilation keyed to its checkout does. One crate low in the graph that reads `CARGO_MANIFEST_DIR`, or reads `OUT_DIR` without sharing, can cause much of a large workspace to rebuild.
+
+Set `MBX_SHARE_WORKSPACE_ROOT=1` (or `share_workspace_root = true`) to map the workspace root to a placeholder, which leaves the two checkouts producing the same bytes. The compilation that read the value is still keyed to its checkout; what changes is that its dependents stop paying for that. The cost is that source paths under the workspace are recorded as the placeholder, in debug information, `file!()` and panic locations, which is why it is off by default.
+
+## Incremental output reduces sharing [​](#incremental-output-reduces-sharing)
+
+`MBX_INCREMENTAL=1` can improve a local edit/rebuild loop, but an incremental artifact changes the content inputs of dependent crates. Those crates then miss even if another checkout built the same source. CI disables incremental builds.
+
+## Collection is approximate [​](#collection-is-approximate)
+
+Object eviction prefers abandoned checkout data and then older access times. Filesystems using `relatime` coarsen that order; `noatime` removes it. A poor choice costs a recompile, not correctness.
+
+The action-store budget covers action objects and results. Prediction data, checkout records, and temporary downloads add overhead. Managed targets have their own budget and can account for substantial space; use the optional combined budget to bound the action store, managed targets, and learned incremental state together. See [Managed target directories](https://mr-boxington.jdx.dev/managed-targets).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/limits.md)
+
+Last updated:
+
+Pager
+
+[Previous pageHow it works](https://mr-boxington.jdx.dev/how-it-works)
+
+[Next pageHow mbx compares](https://mr-boxington.jdx.dev/compared)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,75 @@
+Managed linkers
+
+Managed linkers [​](#managed-linkers)
+
+The default `system` selection preserves Cargo's linker. Change it when you want to try another linker or share a pinned choice across a workspace. Managed selections require `clang` on `PATH`. Keep `system` on Windows; managed `rust-lld` selection is not supported there.
+
+## Try a linker [​](#try-a-linker)
+
+On Linux, try a pinned mold release for one build:
+
+sh
+
+```
+MBX_LINKER=mold@2.42.0 mbx build
+```
+
+This is an example version, not an automatically updated recommendation. On Linux or macOS, `rust-lld` uses the active Rust toolchain's bundled LLD without a download:
+
+sh
+
+```
+MBX_LINKER=rust-lld mbx build
+```
+
+## Selectors [​](#selectors)
+
+mbx can select a linker by Cargo profile and target triple, install an exact version from its official GitHub releases, and route native Rust links through it. The built-in selectors are:
+
+- `system`, which leaves Cargo's linker selection alone;
+- `rust-lld` or `lld`, which uses the LLD shipped with the active Rust toolchain;
+- `mold@<version>` or `wild@<version>`, which downloads the matching release asset and verifies GitHub's SHA-256 digest; and
+- `path:<executable>`, which selects a linker mbx does not install.
+
+Managed GitHub linkers require an exact version. Downloads are installed once beneath `<cache_dir>/tools`; concurrent builds share the same installation lock. `GITHUB_TOKEN` may authenticate GitHub API and download requests.
+
+Within a profile table, an exact target triple wins over `default`. The top-level `linker.default` applies when the active profile has no entry. Cargo's ordinary profile is `dev`, `--release` selects `release`, `cargo bench` selects `bench`, and `--profile <name>` selects that custom profile.
+
+toml
+
+```
+[linker]
+default = "system"
+
+[linker.profiles.dev]
+x86_64-unknown-linux-gnu = "mold@2.42.0"
+aarch64-unknown-linux-gnu = "wild@0.10.0"
+
+[linker.profiles.release]
+default = "rust-lld"
+```
+
+`MBX_LINKER` overrides every file for one invocation:
+
+sh
+
+```
+MBX_LINKER=mold@2.42.0 cargo build
+MBX_LINKER=system cargo build --release
+```
+
+mold and Wild currently provide managed releases for Linux. Unsupported host platforms fail before Cargo starts rather than silently changing the linker. The selected executable remains part of mbx's native-link cache identity.
+
+Store persistent selections in your [global configuration](https://mr-boxington.jdx.dev/configuration) or in the [workspace policy](https://mr-boxington.jdx.dev/configuration#workspace-policy). The `path:` selector is accepted only outside repository-owned policy. A linker change can change cache keys; compare equivalent builds when measuring it.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/linkers.md)
+
+Last updated:
+
+Pager
+
+[Previous pageIncremental builds](https://mr-boxington.jdx.dev/incremental)
+
+[Next pageWatching builds](https://mr-boxington.jdx.dev/tui)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/managed-targets.md

@@ -0,0 +1,197 @@
+Managed target directories
+
+Managed target directories [​](#managed-target-directories)
+
+Cargo normally writes build outputs to `<workspace>/target`. Deleting a worktree deletes useful outputs, while abandoning a checkout leaves gigabytes behind indefinitely.
+
+Managed targets are enabled by default. For a checkout without an existing `target/`, the first build is enough:
+
+sh
+
+```
+mbx build
+```
+
+mbx places the target directory under its cache root and leaves a symlink at `target`, so familiar paths continue to work:
+
+text
+
+```
+target -> <cache root>/targets/v1/<checkout digest>
+```
+
+Cargo continues to report artifacts through the workspace's `target` path, so debugger launch configurations do not capture the private managed path that collection may later replace. In a Git checkout, mbx also adds the exact link path to `.git/info/exclude` when necessary. A directory-only `target/` pattern does not match a symlink; the local exclude keeps `git status` clean without changing the project's `.gitignore`.
+
+## When mbx leaves a target alone [​](#when-mbx-leaves-a-target-alone)
+
+mbx does not override an explicit target directory supplied by:
+
+- `--target-dir`
+- `CARGO_TARGET_DIR`
+- Cargo's `build.target-dir` configuration
+
+## Change target placement [​](#change-target-placement)
+
+Set `target.root` in your global configuration to place managed targets on another local disk:
+
+toml
+
+```
+[target]
+root = "/path/to/local/build-targets"
+```
+
+After any builds using the old target have finished, the next build can update an mbx-owned `target` link to the new managed location:
+
+- When the old directory can be renamed to the new location, mbx moves it and preserves its outputs.
+- When a rename fails, including across filesystems, mbx creates the destination and removes the old directory. It does not copy the old outputs. Matching compilations can be restored from the shared cache; other work compiles again.
+
+The old collection record is retired after relocation. The target budget scales with the destination disk unless you set it explicitly.
+
+## Adopt existing target directories [​](#existing-target-directories)
+
+Use `mbx adopt` to bring existing `target/` directories under mbx management without deleting their contents. mbx moves each directory under the managed root and leaves a link at its original path. From then on, Cargo continues to use `target/`, while mbx applies the same collection policy as it does to any other managed target.
+
+Adopt the current checkout, name specific checkouts, or search below one or more directories:
+
+sh
+
+```
+mbx adopt                            # the current checkout
+mbx adopt ~/src/project              # one checkout
+mbx adopt --recursive ~/src          # checkouts anywhere below a directory
+mbx adopt --recursive --dry-run ~/src
+```
+
+Use `--dry-run` to see which directories are eligible without moving them. Each adopted result includes the logical size of the directory, a skipped checkout reports only why it was left alone, and runs over multiple checkouts end with a total:
+
+text
+
+```
+adopted /home/me/src/project/target (2.4 GiB logical)
+adopted /home/me/src/other/target (912.0 MiB logical)
+adopted 2 target directories (3.3 GiB logical)
+```
+
+Recursive searches look for directories containing both `Cargo.toml` and a real `target/`. They do not descend into hidden directories, `target/` directories, or symbolic links.
+
+### Adoption during a build [​](#adoption-during-a-build)
+
+An interactive mbx build that finds an existing real `target/` offers the same move:
+
+text
+
+```
+Use a managed target directory?
+mbx can move /path/to/project/target under its managed root and leave a link in its place. The outputs are kept, and the directory is pruned after this checkout is deleted.
+```
+
+“Move target/” is selected by default. Declining leaves every output untouched and continues the Cargo command normally. Non-interactive builds never prompt, move, or remove a directory.
+
+If the managed root is on another filesystem, mbx cannot rename the directory into it. In that case, the build-time prompt retains the previous option to remove the old outputs, with “Keep it” selected by default. The `mbx adopt` command never deletes or copies a target directory.
+
+### Eligibility and recovery [​](#eligibility-and-recovery)
+
+mbx leaves a checkout unchanged and explains why when:
+
+- `--target-dir`, `CARGO_TARGET_DIR`, or Cargo's `build.target-dir` names the target directory;
+- it is a workspace member, whose outputs live in the workspace root's `target/`;
+- managed targets are turned off for it;
+- its `target/` is on a different filesystem from the managed root, where a rename would require copying;
+- `target/` is already a symbolic link.
+
+Set `target.root` to a location on the same filesystem when you want to adopt a directory that would otherwise be skipped. Before moving one, mbx takes its Cargo build locks; if a build is still writing there, mbx refuses the move and asks you to try again later. It then renames the directory into the managed root before creating the link. If the link or collection record cannot be created, mbx moves the directory back. When a user accepts the build-time removal option, mbx deletes the old outputs only after their managed replacement is ready.
+
+Adoption preserves the files already in `target/`, but it does not make every plain Cargo artifact immediately reusable by mbx. Cargo keys builds run through mbx differently, so the first mbx build may compile artifacts that were produced without mbx. A target directory previously built through mbx remains fresh after adoption.
+
+## Collection [​](#collection)
+
+mbx records the checkout associated with each target view. Collection runs after a build, at most once an hour, and needs no configuration. It normally runs in the background once the build has returned, so a walk of every managed directory never holds up the build that happened to come due, and the next build reports what it removed. If the background collector cannot be started, the build collects in the foreground instead. A directory that a build claims or is compiling in while collection runs is left alone until the next sweep. A target directory is removed when any of these is true:
+
+- Its checkout is gone. This happens regardless of the limits below.
+- It has gone unused for `target.max_age`, 30 days by default. The next build in that checkout can restore matching cached outputs. Evicted or unsupported work must compile again.
+- The managed directories together exceed `target.max_size`. The least recently used go first. The most recently used directory is never collected for being over budget; if the budget cannot be met without it, mbx says so and keeps it.
+
+Cached compilations shared with a live checkout remain protected throughout.
+
+### Budgets scale with the disk [​](#budgets-scale-with-the-disk)
+
+All three budgets scale with the disk that holds the data. By default, targets, learned incremental state, and the action store share the cache disk. A custom `target.root` uses its own volume for the target budget:
+
+| Budget | Default | Bounds |
+| --- | --- | --- |
+| `gc.max_size` (action store) | 5% of the disk | 5 GiB to 500 GiB |
+| `target.max_size` (managed targets) | 10% of the disk | 10 GiB to 100 GiB |
+| `gc.incremental_max_size` (learned incremental) | 5% of the disk | 10 GiB to 100 GiB |
+
+Scaled budgets are rounded down to a whole 5 GiB. When the disk cannot be measured, mbx uses 20 GiB, 30 GiB, and 20 GiB respectively. An explicit budget overrides these defaults, and `mbx gc --dry-run` previews the effect of a policy without deleting anything.
+
+### Changing or disabling the limits [​](#changing-or-disabling-the-limits)
+
+toml
+
+```
+[target]
+max_size = "60GiB"
+max_age = "none"   # keep live checkouts' outputs indefinitely
+
+[gc]
+# Optional: one budget covering targets, learned incremental, and the action store.
+max_total_size = "50GiB"
+incremental_max_size = "20GiB"
+incremental_max_age = "30d"
+```
+
+`"none"` turns off `target.max_size`, `target.max_age`, `gc.incremental_max_size`, `gc.incremental_max_age`, or `gc.max_total_size`. Invalid sizes and durations are errors, so a typo cannot disable collection. `gc.max_size` does not accept `"none"`; the action store is always bounded. To stop creating managed targets, see [Disable managed targets](#disable-managed-targets).
+
+## Inspect and clean up [​](#inspect-and-clean-up)
+
+| Command | Effect |
+| --- | --- |
+| `mbx cache stats` | Inspect the action store, managed targets, and learned incremental state |
+| `mbx gc --dry-run` | Preview collection under the configured budgets |
+| `mbx gc` | Collect eligible targets, cached objects, and learned incremental state |
+| `mbx clean` | Remove this workspace's managed target, link, and learned incremental state |
+| `mbx adopt [--recursive] [PATH]...` | Adopt existing `target/` directories without deleting their contents |
+| `mbx cache remove /path/to/workspace` | Remove the target and incremental state, then forget that workspace's cache claims |
+
+`mbx clean` also accepts a workspace path. It keeps shared cached objects and the workspace's cache claims, so a later build can restore matching outputs. `mbx cache remove` forgets those claims as well; objects used by other workspaces remain available and normal garbage collection reclaims unneeded objects.
+
+Cargo's `cargo clean` follows Cargo's own target-directory behavior and does not remove mbx's private incremental state.
+
+## Disable managed targets [​](#disable-managed-targets)
+
+Set `MBX_TARGET_VIEWS=0`, or configure:
+
+toml
+
+```
+[target]
+views = false
+```
+
+Turning placement off does not delete a target directory mbx already manages. The existing `target` link continues to work, and collection can still reclaim the directory after its checkout disappears.
+
+Use the [cleanup commands](#inspect-and-clean-up) to remove existing managed outputs immediately.
+
+Windows
+
+Creating the link requires Developer Mode or a privileged process on Windows. If Windows cannot create it, mbx lets Cargo use its ordinary target directory.
+
+## Collection byte counts [​](#collection-byte-counts)
+
+Collection reports **logical bytes**: the sum of removed file lengths. The `removed_bytes` and `remaining_bytes` fields in `mbx gc --json` use this measure; `byte_accounting: "logical"` identifies it explicitly. The lifetime `savings` object in `mbx stats --json` also carries that marker. Lifetime savings totals and cleanup messages use the same measure. Existing `freed_*_bytes` fields in the saved lifetime tally retain their names for compatibility.
+
+Physical disk space released can differ. Reflinks and hard links may leave data referenced by another file; sparse files may occupy fewer blocks than their length. Filesystem snapshots and delayed allocation also affect reclamation. These counters do not estimate physical space released.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/managed-targets.md)
+
+Last updated:
+
+Pager
+
+[Previous pageLocal development](https://mr-boxington.jdx.dev/cookbook/local-development)
+
+[Next pageParallel builds](https://mr-boxington.jdx.dev/scheduling)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/protocol-compatibility.md

@@ -0,0 +1,103 @@
+Protocol compatibility
+
+Protocol compatibility [​](#protocol-compatibility)
+
+mbx has two wire protocols and a separately versioned Rust API surface.
+
+| Integration | Compatibility rule |
+| --- | --- |
+| Local compiler shim and agent | Exact protocol and application-version match |
+| Remote cache client and server | Versioned HTTP contract with negotiated extensions |
+| Published Rust subcrates | Independent crate versions; embedding APIs remain on `0.x` |
+
+For CLI and JSON output guarantees, see [Stability](https://mr-boxington.jdx.dev/stability). Most mbx users do not need to interact with these protocols directly.
+
+## Shim/agent protocol [​](#shim-agent-protocol)
+
+The shim and its task-scoped agent exchange newline-delimited JSON values over a local socket. The first request and response are always `hello` values carrying `AGENT_PROTOCOL_VERSION` and the mr-boxington package version.
+
+Both versions must match exactly. A shim and agent from different builds fail the handshake and do not exchange cache requests. Adding, removing, or changing a request or response therefore requires incrementing `AGENT_PROTOCOL_VERSION`.
+
+`crates/mbx-cache-core/tests/agent_protocol.rs` exercises every request and response variant against `tests/fixtures/agent-protocol-v9.jsonl`. Its exhaustive matches make a newly added variant fail to compile until the fixture and the protocol-version decision are reviewed together.
+
+### Local protocol history [​](#local-protocol-history)
+
+Every revision still requires exact protocol and application-version equality, including when different applications embed the client and agent.
+
+| Version | Addition |
+| --- | --- |
+| v2 | Compiler-duration accounting for hits and real compilations |
+| v3 | Crate names on hits; `begin_task` and `commit_task` for per-command manifests |
+| v4 | `record_warning` forwards shim diagnostics for the agent to print once |
+| v5 | `find_file_digests` and `record_file_digests` share hashes within a session |
+| v6 | `join_action_promise` and `complete_action_promise` coordinate remote compilations |
+| v7 | `resolve_file_digests` coalesces simultaneous hashing requests |
+| v8 | `pins` on `store_executable_identity` validate cached compiler and linker probes |
+| v9 | `record_debug` and `debug_recorded` forward routine shim logs to the session logger |
+
+Routine debug logs retain their module target and do not consume the warning/error diagnostic allowance.
+
+## Remote cache protocol [​](#remote-cache-protocol)
+
+The dependency-light `mbx-cache-protocol` crate owns the remote wire records, capability schema, media types, headers, and blob-pack framing constants. Both the client and server compile against that crate; transport, authentication, storage, and adapter execution remain implementation details of their respective packages.
+
+Remote cache endpoints live below `/v{PROTOCOL_VERSION}/` and every request carries `mbx-cache-protocol` and `mbx-cache-namespace` headers. The v1 protocol defines these resources; extensions require the capabilities described below:
+
+| Operation | Method and path | Representation |
+| --- | --- | --- |
+| capabilities | `GET /v1/capabilities` | JSON capability document |
+| action result | `GET`/`PUT /v1/action-results/{algorithm}/{hash}/{size}` | `application/vnd.mbx.cache-action-result.v1+json` |
+| action manifest | `GET`/`PUT /v1/action-manifests/{algorithm}/{hash}/{size}` | `application/vnd.mbx.cache-task-action-manifest.v1+json` |
+| action result batch | `POST /v1/action-results:batch` | `application/vnd.mbx.cache-action-result-batch.v1+json` |
+| action promise | `POST`/`PUT /v1/action-promises/{algorithm}/{hash}/{size}` | `application/vnd.mbx.cache-action-promise.v1+json` |
+| blob | `GET`/`PUT /v1/blobs/{algorithm}/{hash}/{size}` | media type requested by the caller |
+| blob pack | `POST /v1/blobs:pack` | `application/vnd.mbx.cache-blob-pack.v1` |
+| blob pack upload | `POST /v1/blobs:pack-upload` | `application/vnd.mbx.cache-blob-pack-receipt.v1+json` |
+
+The batched and packed resources are extensions, each gated on its own capability (`features.action_batch`, `features.blob_packs`, and `features.blob_pack_uploads`) and bounded by `limits.max_batch_items` and `limits.max_pack_bytes`. A client falls back to the single-object resources when a feature is not advertised, and also when an advertised endpoint answers `404`, `405`, or `501`, after which it stops asking for the rest of the session. None of them is required to serve the baseline.
+
+Action promises are gated by `features.action_promises`. `POST` atomically returns a claim token, a bounded retry delay while another lease is live, or a completed `ActionPrediction`. `PUT` presents the claim token and prediction to complete the promise. A server must authorize both operations as writes, expire abandoned claims, refuse a completion whose action result is not already durable, and make the first valid completion immutable. Claim tokens are opaque bearer values and clients cap them at 256 bytes. As with other extensions, `404`, `405`, or `501` disables promises for the rest of the client session.
+
+A batched action-result response carries only the records the service holds, in no order, so each one is bound to its request by the action digest inside it, not by position: a client refuses a batch naming an action it did not ask for. An uploaded pack repeats the `MBXPACK1` framing of a downloaded one and declares its contents in the pack headers. Every blob in it is content-addressed and immutable, so a rejected pack may leave an accepted prefix stored; the client then republishes its blobs individually.
+
+The capabilities endpoint is optional: `404`, `405`, or `501` selects the v1 baseline without extensions. Advertised capabilities must report the same protocol major. Optional response fields may be added only when existing clients ignore them; the canonical persisted records use `#[serde(deny_unknown_fields)]`, so changing their shape or meaning requires a new media type and protocol major.
+
+Content-addressed records are serialized with the JSON Canonicalization Scheme before hashing. The conformance fixture locks their canonical v1 bytes, the protocol constants, and the normalized shape of every local-agent message to prevent accidental drift.
+
+Action manifests are updated conditionally: a `GET` returns a strong `ETag` that the following `PUT` sends back as `If-Match`, and a first write uses `If-None-Match: *`. That entity tag is **opaque**. A client must echo it unchanged and must not read content from it, because a manifest can reach the client through an intermediary. RFC 9110 section 8.8.3.3 requires a proxy that compresses a response to vary the strong tag along with the coding, and Caddy does so by appending the coding name. The body is validated by comparing it against its canonical JSON and checking the task identity it claims, never by the tag. A server may therefore choose any strong tag; a weak one leaves the manifest readable but not updatable.
+
+## Rust API compatibility [​](#rust-api-compatibility)
+
+Published Rust APIs are versioned independently of the wire protocols. The subcrates remain on `0.x`, so their APIs may change in a minor release and CI does not currently enforce API compatibility. Wire format changes still require the protocol-version steps above.
+
+Release-plz chooses version bumps from conventional commits. Declare breaking API changes with `!` and a `BREAKING CHANGE:` footer, and isolate pre-1.0 subcrate breaks from changes to `mbx`: breaking markers apply to every crate touched by a commit, regardless of its scope. [RELEASING.md](https://github.com/jdx/mr-boxington/blob/main/RELEASING.md) covers what that means for contributors.
+
+The published crates do not all share a version, because they do not promise the same things:
+
+| Crate | Version line | What it promises |
+| --- | --- | --- |
+| `mbx` | independent | The command line: subcommands and versioned JSON output. The library target is internal. |
+| `mbx-cache-protocol` | independent | The remote cache wire contract, as described above. Depend on this to speak to an mbx cache. |
+| `mbx-cache-core` | shared `0.x` | Unstable session, store, and agent primitives for coordinated embedding. |
+| `mbx-cache-rustc` | shared `0.x` | Unstable rustc action modeling for coordinated embedding. |
+| `mbx-cache-cc` | shared `0.x` | Unstable C and C++ action modeling for coordinated embedding. |
+| `mbx-cache-cargo` | independent `0.x` | Unstable Cargo invocation and shared-cache-root resolution. |
+| `mbx-cache-store` | independent `0.x` | Unstable checkout claims and disk-bounded shared-store GC. |
+
+The embedding crates stay on `0.x`, where a minor bump is allowed to break. `mbx-cache-core`, `mbx-cache-rustc`, and `mbx-cache-cc` move together; the Cargo and store crates release independently. Pin compatible minors and expect an upgrade to require source changes.
+
+The Rust types mirror which wire records are open to extension and which are not. Capability records are `#[non_exhaustive]`, so a newly advertised feature or limit is a minor release; build them with `Capabilities::new` and assign the fields a service supports. The canonical persisted records are exhaustive, because their shape is covered by a digest and a change to it requires a new media type and protocol major. `BypassReason` is also `#[non_exhaustive]`: the set of uncacheable invocations shifts as the adapter learns to model more of them, so aggregate on `BypassReason::kind` instead of matching every variant.
+
+The same rule sorts the statistics types. `AgentStats` and `CompilerStats` gain counters as sessions measure more, so both are open to extension; build them from `default` or `CompilerStats::new`. `RestoreStats` stays constructible, because the shim reports one on every compilation; it is an input to the crate.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/protocol-compatibility.md)
+
+Last updated:
+
+Pager
+
+[Previous pageStability](https://mr-boxington.jdx.dev/stability)
+
+[Next pageAcknowledgements](https://mr-boxington.jdx.dev/acknowledgements)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)