@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mbx/references/remote-cache.md

@@ -0,0 +1,190 @@
+Remote cache
+
+Remote cache [​](#remote-cache)
+
+A remote cache lets ephemeral runners and teammates restore the compiler actions a build needs. The local content-addressed store remains the working cache; remote objects are downloaded into it and newly completed actions may be uploaded from trusted CI.
+
+Choose a **cache server** for server-side authorization and optional batch transfers, compression, and compilation deduplication. Choose an **S3-compatible bucket** to use object storage directly. The URL scheme selects the backend.
+
+| Backend | Use it when | Credentials |
+| --- | --- | --- |
+| [Cache server](#configure-a-server) | You want server-side grants and negotiated transfer extensions | Bearer token or GitHub OIDC |
+| [S3-compatible bucket](#configure-an-s3-compatible-bucket) | You already operate object storage | Exported AWS credentials |
+| [GitHub Actions cache](https://mr-boxington.jdx.dev/github-action) | You want managed archive storage for GitHub jobs | Handled by the action |
+
+Put `[remote]` settings in your [global configuration](https://mr-boxington.jdx.dev/configuration), or use `MBX_REMOTE_*` environment variables in CI. They are not accepted from a repository's `.mbx.toml`. A configured `read-write` mode is still subject to [the environment's write policy](#read-and-write-policy).
+
+## Configure a server [​](#configure-a-server)
+
+toml
+
+```
+[remote]
+url = "https://cache.example.com"
+namespace = "acme/backend"
+mode = "read-write"
+```
+
+The namespace isolates one project's cache from another. It is required when a remote URL is set. To host your own server, see [cache server](https://mr-boxington.jdx.dev/cache-server).
+
+## Authenticate [​](#authenticate)
+
+For a cache server, choose one authentication method:
+
+- `MBX_REMOTE_TOKEN` for a bearer token.
+- `MBX_REMOTE_TOKEN_FILE` for a file containing the token.
+- `MBX_REMOTE_OIDC_AUDIENCE` for CI-issued OIDC credentials.
+
+Avoid long-lived secrets in pull request workflows. On GitHub Actions, OIDC requires `id-token: write` permission.
+
+These settings are specific to cache servers. For an `s3://` URL, use the [AWS credential variables](#configure-an-s3-compatible-bucket) instead.
+
+## Configure an S3-compatible bucket [​](#configure-an-s3-compatible-bucket)
+
+toml
+
+```
+[remote]
+url = "s3://acme-build-cache"
+namespace = "acme/backend"
+mode = "read-write"
+```
+
+Credentials come from the standard AWS environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` for temporary credentials. `MBX_REMOTE_S3_REGION` names the signing region, falling back to `AWS_REGION` or `AWS_DEFAULT_REGION`.
+
+Export temporary credentials into those variables before starting mbx. On GitHub Actions, [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) can exchange the runner's OIDC token for temporary role credentials. mbx does not directly read EKS IRSA, EC2 or ECS instance roles, `~/.aws/config` profiles, or SSO sessions; export their credentials first.
+
+The URL may carry a prefix, as `s3://acme-build-cache/teams/backend`, to share one bucket between projects. Keys are laid out under `<prefix>/<namespace>/v1/`, so a bucket policy can scope a writer to its own prefix.
+
+Readers need `s3:GetObject` on that prefix. Trusted writers also need `s3:PutObject`. Add `s3:ListBucket` on the bucket as well. mbx never lists anything, but without that permission AWS answers `403` instead of `404` for an absent object, so a miss cannot be told apart from a refusal.
+
+Without it mbx still works: a refused read is treated as a miss, and it says so once. A credential that cannot read the cache then looks the same as a cold one, and only the warning distinguishes them. Credentials that S3 itself rejects, such as a wrong secret or an expired token, are reported as errors either way.
+
+### Cloudflare R2 and MinIO [​](#cloudflare-r2-and-minio)
+
+Set an endpoint, which switches to addressing the bucket in the path:
+
+toml
+
+```
+[remote]
+url = "s3://acme-build-cache"
+namespace = "acme/backend"
+s3_endpoint = "https://<account>.r2.cloudflarestorage.com"
+s3_region = "auto"
+```
+
+For MinIO, use its endpoint and signing region. `http://` is refused for anything but a loopback address, since a signature and the objects it fetches are readable in transit without TLS.
+
+### What a bucket does not do [​](#what-a-bucket-does-not-do)
+
+A cache server verifies every blob against the digest in its URL before storing it. A bucket stores what it is given, so a corrupted object in the local store can be published under a key naming different content. Writes are create-only, so nothing later overwrites it: every machine that downloads it fails verification and recompiles. `mbx cache verify` finds such an object locally.
+
+A bucket also does not coordinate in-flight compilations, answer batched lookups, stream blob packs, or negotiate compression. mbx asks for none of them against S3 and falls back to per-object requests, the same requests it makes against a server without the extensions. Expect more requests for the same build, and no compression on the wire.
+
+The task action manifest that drives [prefetch](#prefetch) is updated in place. Conditional writes prevent concurrent updates from overwriting one another. AWS S3, R2, and current MinIO all implement them. Against a store that does not, mbx says so once and continues without them. Blobs and action results are content-addressed, so writing one twice is harmless, but concurrent manifest updates can then lose each other's predictions, which costs prefetch coverage on later builds. `MBX_REMOTE_S3_CONDITIONAL_WRITES=required` refuses such a store instead.
+
+### Who may publish [​](#who-may-publish)
+
+A cache server enforces namespace grants; a bucket enforces its object-storage permissions. Whatever a bucket credential can write is within reach of code holding that credential. The client-side [write policy](#read-and-write-policy) still applies, so pull requests never publish, but code holding a write credential can bypass mbx and write to the bucket directly. Enforce the same restriction in your storage permissions.
+
+Scope the write credential to the builds you trust. On GitHub Actions, restrict the role's trust policy to the branches that may assume it, and give pull request jobs a read-only role.
+
+## Read and write policy [​](#read-and-write-policy)
+
+Configured mode is constrained by the environment:
+
+| Context | Effective behavior |
+| --- | --- |
+| Protected branch push on GitHub Actions or GitLab CI | Configured mode |
+| Pull request, merge request, local shell, or unprotected branch | Read-only; `write-only` becomes disabled |
+| Tag or release build | Read-only; `write-only` becomes disabled |
+
+This policy prevents untrusted code from publishing objects that later builds would trust. The server should still authenticate and authorize requests; the client-side policy is not an access-control boundary.
+
+## GitLab CI [​](#gitlab-ci)
+
+GitLab CI follows the same write policy as GitHub Actions: a push pipeline on a protected branch may write, merge requests and unprotected branches are read-only, and tag pipelines cannot publish to the remote.
+
+The OIDC flow is GitHub-specific, so authenticate GitLab jobs with a bearer token in a masked, protected CI/CD variable:
+
+yaml
+
+```
+# Install mbx and a Rust toolchain in the job image first.
+build:
+  variables:
+    MBX_REMOTE_URL: https://cache.example.com
+    MBX_REMOTE_NAMESPACE: acme/backend
+    MBX_REMOTE_MODE: read-write
+  script:
+    - mbx build --workspace
+```
+
+Set `MBX_REMOTE_TOKEN` in the project's CI/CD variables, masked and limited to protected branches, not in the YAML.
+
+## Prefetch [​](#prefetch)
+
+After a command has published its action manifest, another machine can warm the same build without running Cargo:
+
+sh
+
+```
+mbx prefetch build --workspace --release
+```
+
+The workspace's `Cargo.lock` and complete Cargo argument list select the same manifest as a normal mbx build. Prefetch requires a configured remote in `read-only` or `read-write` mode, waits for every predicted action, and reports what it pulled:
+
+text
+
+```
+prefetched 161 actions; 214.8 MiB downloaded and 214.8 MiB stored locally
+```
+
+If no manifest has been published for the workspace and command, mbx prints `no recorded actions for this workspace and Cargo command` and exits successfully. There was nothing to fetch, which is normal for a first build. A lockfile that has not been built yet borrows the manifest of the lockfile before it in Git history, so a dependency bump still prefetches the unchanged part of the graph. A shallow checkout needs that history fetched. For GitHub Actions builds of the default pull-request merge commit, `fetch-depth: 2` includes its base parent; builds of a PR head or another ref may need more history. A lookup that fails, such as an unreachable host or refused credentials, is an error, so CI can tell an empty cache from a broken one. A typical place for the command is a runner or devcontainer image's start-up hook, so the store is warm before anyone builds.
+
+## In-flight deduplication [​](#in-flight-deduplication)
+
+When a cache server advertises action promises, read-write runners atomically claim a cold compiler invocation before starting it. One runner compiles and publishes the result; other runners wait for its promise, rebuild the final action key from the promised input prediction, verify every input, and restore the published result. The prediction is only fulfilled after the action result and all referenced blobs are remotely durable.
+
+Claims are keyed by the pre-discovery invocation digest because a cold runner does not yet know the compiler-discovered inputs in the final action key. They are leases: a runner that dies or cannot publish leaves no durable cache record, and the server expires its claim so another runner can compile. Any endpoint error, unsupported server, read-only policy, or expired client wait degrades to an ordinary compilation. Read-only runners never acquire claims.
+
+## Deferred publication [​](#deferred-publication)
+
+Uploads are not on the critical path of the build that produced them. They are queued while the build continues and drained before the session exits. An action result is published only after every blob it references, so a reader never fetches a result whose outputs it cannot restore. A command killed before the queue drains may leave some results only in the local store. Other machines must compile work that was not uploaded.
+
+A failed upload is reported, counted in `remote_failures`, and recovered from; the build keeps its local result either way. The session summary reports what was published and what the drain cost. Where the server accepts them, queued blobs are published several to a request:
+
+text
+
+```
+mbx[cache]: uploads: 143 published (118 of them in 2 packs), 0 not published; 412.0ms waited for after the build
+```
+
+`MBX_STATS_REPORT` carries the same figures as `background_uploads`, `background_upload_failures`, `upload_drain_duration_ns`, `remote_blob_pack_uploads`, and `remote_blob_pack_upload_blobs`.
+
+## Batched lookups [​](#batched-lookups)
+
+Prefetch requests known actions together when the server supports batched lookups, reducing the number of HTTP requests. `remote_action_lookups` counts requests, not actions, so the same build reports far fewer of them against a server with the extension.
+
+Batch lookups and packed uploads are negotiated. A server without them, or one that advertises an endpoint it does not serve, gets the single-object requests every version of mbx has made. Nothing needs configuring either way.
+
+## Transfer behavior [​](#transfer-behavior)
+
+Blobs travel zstd-compressed when the server supports it: the client accepts compressed downloads, and it compresses uploads when the server's capabilities list `zstd` among its compressors. Failed requests are retried according to `MBX_HTTP_RETRIES`, and a stalled attempt is cut short by `MBX_HTTP_TIMEOUT`.
+
+`MBX_HTTP_DOWNLOAD_TIMEOUT` exists separately because artifacts can be much larger than metadata responses. It is a deadline for the whole download and spans every retry and the backoff between them, which bounds how long one blob can hold a build open. A packed request scales the deadline up with the bytes and object count it asks for, since the configured value describes a single blob. Raise it if a slow link makes large artifacts run out of time before their retries are spent.
+
+The download deadline applies per object. `MBX_HTTP_READ_STALL_BUDGET` limits the cumulative time spent on failed reads in a session. Once that budget is exhausted, mbx stops remote reads and compiles locally. Successful reads do not count against the budget, even when slow. Set it to `0` to disable this session-wide limit while retaining the per-download deadline.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/remote-cache.md)
+
+Last updated:
+
+Pager
+
+[Previous pageFork pull requests](https://mr-boxington.jdx.dev/cookbook/fork-prs)
+
+[Next pageCache server](https://mr-boxington.jdx.dev/cache-server)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,65 @@
+Parallel builds
+
+Parallel builds [​](#parallel-builds)
+
+Give independent Cargo commands their own target directories. mbx coordinates their real compiler processes through a shared CPU and memory budget; Cargo continues to plan dependencies within each build.
+
+## Run independent tasks [​](#run-independent-tasks)
+
+Any task runner can start multiple mbx commands at the same time. For example, mise runs these two lint configurations together:
+
+toml
+
+```
+# mise.toml
+[tasks."lint:default"]
+run = "mbx clippy --workspace -- -D warnings"
+env.CARGO_TARGET_DIR = "target/clippy-default"
+
+[tasks."lint:all"]
+run = "mbx clippy --workspace --all-features --all-targets -- -D warnings"
+env.CARGO_TARGET_DIR = "target/clippy-all"
+```
+
+sh
+
+```
+mise run lint:default ::: lint:all
+```
+
+Separate target directories keep Cargo's directory lock from serializing the commands. mbx shares one machine-wide compiler pool and deduplicates identical work in flight without further configuration. See [how it works](https://mr-boxington.jdx.dev/how-it-works#machine-wide-scheduling) for the mechanism and the same shape [inside GitHub Actions](https://mr-boxington.jdx.dev/github-action#parallel-cargo-steps).
+
+## Machine-wide compile scheduling [​](#machine-wide-compile-scheduling)
+
+Each Cargo process sets its own concurrency. Without coordination, several builds can collectively start more compiler processes than the machine can comfortably run. mbx coordinates them through a shared pool under the cache directory. Scheduling is on by default; `MBX_SCHEDULER=0` disables it.
+
+A permit represents a share of the pool's CPU and memory budget. The pool has `scheduler.cpus` permits (default: logical CPUs), minus `scheduler.reserve_cpus` (default: 0), with at least one permit remaining. `scheduler.memory` defaults to 85% of physical memory. In a Linux container, the cgroup's memory limit constrains that budget.
+
+Compiler processes take permits according to their estimated memory use. Unmeasured compilations start at one permit; native links start at two and can use estimates from earlier links. Measurements refine later admissions. Set `scheduler.memory = "none"` to use CPU permits without memory weighting.
+
+Cache hits do not need compiler permits. If a process dies, the kernel releases its permits. For the weighting and recovery details, see [how it works](https://mr-boxington.jdx.dev/how-it-works#machine-wide-scheduling).
+
+Use `scheduler.priority = "low"` (`MBX_SCHEDULER_PRIORITY=low`) for an editor's background check or CI on a shared machine. While normal-priority work is waiting, low-priority builds leave a quarter of the pool available for it.
+
+## Choose the scope of a limit [​](#choose-the-scope-of-a-limit)
+
+| Limit | Affects |
+| --- | --- |
+| `scheduler.cpus`, `scheduler.memory` | The shared compiler pool |
+| `scheduler.reserve_cpus` | Capacity left outside that pool |
+| Cargo `-j` or `CARGO_BUILD_JOBS` | How much of the pool one build may hold |
+| `scheduler.priority = "low"` | Whether a build yields to waiting normal-priority work |
+
+A memory budget schedules work using measurements; it is not an operating-system memory limit. A compiler process can still exceed its estimate. For laptop settings, see [Keep a laptop responsive](https://mr-boxington.jdx.dev/cookbook/local-development#keep-a-laptop-responsive).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/scheduling.md)
+
+Last updated:
+
+Pager
+
+[Previous pageManaged targets](https://mr-boxington.jdx.dev/managed-targets)
+
+[Next pageIncremental builds](https://mr-boxington.jdx.dev/incremental)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,157 @@
+Set up Cargo and your editor
+
+Set up Cargo and your editor [​](#set-up-cargo-and-your-editor)
+
+## Native mise integration [​](#native-mise-integration)
+
+With mise 2026.9.2 or newer:
+
+sh
+
+```
+mise use --global --tool-option mr_boxington=true rust mr-boxington
+```
+
+This enables ordinary Cargo commands through mise without running `mbx setup`. Use `mise exec -- cargo build`, `mise run` tasks, or a shell with mise activation or shims on `PATH`. Rust and mbx remain independently versioned. Drop `--global` for a project-scoped configuration.
+
+## Standalone setup [​](#standalone-setup)
+
+After [installing mbx](https://mr-boxington.jdx.dev/installation), run this to install a stable Cargo shim and configure rust-analyzer:
+
+sh
+
+```
+mbx setup
+mbx setup --status
+```
+
+Setup offers explicit mise wrapper and rust-analyzer integration. It is useful for older mise versions or applications that need an absolute Cargo shim path. To try mbx without changing your setup, run `mbx build` directly.
+
+## Choose a scope [​](#choose-a-scope)
+
+| Command | Scope |
+| --- | --- |
+| `mbx setup` | Prompt for the recommended configuration |
+| `mbx setup --yes` | Accept the recommendation |
+| `mbx setup --global` | Global mise configuration |
+| `mbx setup --local` | Current project's mise configuration |
+
+During `mise use --postinstall`, `mbx setup --yes` adds a `[wrappers.cargo]` entry to the configuration named by `MISE_CONFIG_FILE`. Otherwise, setup only integrates with mise when mise is activated in the current shell. It recommends the config that defines `mr-boxington`, then the nearest project config, and finally the global config. `mbx setup` prompts before using that recommendation; `--yes` accepts it. Without an active mise shell, setup prints the exact shell-specific `PATH` change and never edits a shell startup file. Setup runs `mise reshim` after adding or removing the wrapper.
+
+The explicit wrapper written by `mbx setup` requires mise 2026.8.16 or newer.
+
+## Share setup with a project [​](#share-setup-with-a-project)
+
+With mise 2026.9.2 or newer, commit the tool option in the project's `mise.toml`:
+
+toml
+
+```
+[tools]
+rust = { version = "stable", mr_boxington = true }
+mr-boxington = "latest"
+```
+
+Keep the project's existing Rust version and other options when adding `mr_boxington = true`. Both tools must be configured. Run `mise install`, then use `mise exec -- cargo build`, project tasks with `mise run`, or plain `cargo` with mise activation or shims on `PATH`.
+
+Set `mr_boxington = false` on the project's Rust entry to disable native wrapping there. An explicit `[wrappers.cargo]` takes precedence over the Rust option, including `false`. When migrating from `mbx setup`, remove the old mbx `[wrappers.cargo]` entry and its `postinstall` hook from the applicable config so the Rust option controls wrapping. Run `mise reshim` after migrating.
+
+## Verify plain Cargo [​](#verify-plain-cargo)
+
+Open a new shell after setup and verify that Cargo resolves to mise's command wrapper, a mise shim, or the stable mbx shim, depending on how you activated it. On Unix:
+
+sh
+
+```
+command -v cargo
+# ~/.local/share/mise/command-wrappers/bin/cargo on Linux
+```
+
+On Windows, use PowerShell or `where.exe`:
+
+powershell
+
+```
+(Get-Command cargo).Path
+where.exe cargo
+```
+
+mise activation supplies the command-wrapper path to shells where mise is active. The wrapper invokes `mbx` with Cargo shim mode enabled, then mise removes its dispatch directories before mbx delegates to the configured or system Cargo. Calling `~/.cargo/bin/cargo` directly bypasses mise's integration.
+
+### Desktop applications and non-interactive commands [​](#desktop-applications-and-non-interactive-commands)
+
+For coding agents, SSH commands, and other non-interactive tools, use `mise exec -- cargo build` or put mise's shims directory on their `PATH`. When using shims, `command -v cargo` resolves to the mise shim rather than the command-wrapper directory; both honor the Rust option.
+
+Desktop applications such as Codex may inherit a different `PATH` from an interactive terminal. Check `command -v cargo` from a command run by the application itself. Configure its command environment to include mise's shims, or use `mise exec -- cargo build` for build commands. Restart the application after changing its inherited environment.
+
+If you prefer mbx's standalone launcher, run `mbx setup` and prepend the directory it prints to the environment those processes use. For zsh, `~/.zshenv` applies to interactive and non-interactive shells. For example, the default Linux location is:
+
+sh
+
+```
+export PATH="$HOME/.local/share/mbx/bin:$PATH"
+```
+
+On macOS, the default is different:
+
+sh
+
+```
+export PATH="$HOME/Library/Application Support/mbx/bin:$PATH"
+```
+
+Use the path setup prints if your data directory is customized.
+
+Start a new process and run `command -v cargo` again. Once it resolves to the shim, ordinary `cargo build`, `cargo test`, and `cargo check` commands use mbx automatically. Prefixing a Cargo command with `mbx`, as in `mbx build`, still works.
+
+Outside mise activation, the stable `cargo` launcher uses the setup-time mbx while it exists, then resolves the active `mbx` from `PATH` after an upgrade removes that path. Windows `cargo.exe` resolves the active mbx from `PATH`, with the setup-time path as a fallback. Upgrading a mise-managed mbx does not require running setup again.
+
+## rust-analyzer [​](#rust-analyzer)
+
+The native mise option does not configure editor checks. Run `mbx setup` to configure rust-analyzer's background check. Setup writes the override to rust-analyzer's user configuration file and prints the path, whichever mise scope activation uses. For the TOML integration used by setup, the override belongs in that user file. A `rust-analyzer.toml` beside `Cargo.toml` does not apply the override to the editor's Cargo process.
+
+The editor invokes the stable Cargo shim by its absolute path, so its build shares mbx's cache and machine-wide compiler pool even when the editor did not inherit mise's `PATH`. Its outputs go to `target/rust-analyzer`, separate from terminal builds so the two Cargo processes do not contend on the target-directory lock. When `target` is managed, the editor directory lives inside that view and is collected with it, while the shared store warms both builds. Existing rust-analyzer check settings are left unchanged.
+
+Releases through 1.11.0 wrote the override beside `Cargo.toml` when mbx was activated in a project mise scope, where rust-analyzer never read it. `mbx setup` and `mbx setup --uninstall` take that setting back out and report the file they cleaned.
+
+## Remove automatic wrapping [​](#remove-automatic-wrapping)
+
+For native mise integration, remove `mr_boxington` or set it to `false` in each Rust tool entry where you enabled it, then run `mise reshim`. Keep the Rust version and any unrelated tool options. Do this before removing mr-boxington from `[tools]`.
+
+If you ran standalone setup as well:
+
+sh
+
+```
+mbx setup --uninstall
+```
+
+Use `--global` or `--local` to select a mise scope explicitly. Repeat for each scope you enabled, and remove any mbx `PATH` entry you added manually. Open a new shell and check Cargo's path again. Uninstalling activation does not remove the mbx executable or clear the cache.
+
+One user-level rust-analyzer override serves every scope, so uninstalling a project scope leaves it in place for the others, the way it leaves the Cargo shim. Uninstalling the global scope removes it.
+
+## Shell completions [​](#shell-completions)
+
+Generate a completion script for `bash`, `zsh`, `fish`, or `powershell`:
+
+sh
+
+```
+mbx completion zsh > _mbx
+```
+
+Install the generated file in your shell's completion directory. The script is self-contained. See the [completion reference](https://mr-boxington.jdx.dev/cli/completion).
+
+For watch loops, debugger paths, and laptop budgets, continue to [Local development](https://mr-boxington.jdx.dev/cookbook/local-development).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/setup.md)
+
+Last updated:
+
+Pager
+
+[Previous pageInstallation](https://mr-boxington.jdx.dev/installation)
+
+[Next pageLocal development](https://mr-boxington.jdx.dev/cookbook/local-development)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,43 @@
+Stability
+
+Stability [​](#stability)
+
+The CLI, machine-readable reports, local cache, and embedding APIs have different compatibility rules. Use this page when planning an upgrade or building tooling around mbx.
+
+## The store is disposable [​](#the-store-is-disposable)
+
+The local store is a cache of work mbx can redo. Correctness never depends on its format: an entry a new version cannot read is a miss, and the compilation runs again. The worst case for any upgrade is a colder build, not a wrong one, and cached compilations can be regenerated. Stop builds before manually deleting the whole root: it also contains managed targets and private state. Prefer [`mbx gc`](https://mr-boxington.jdx.dev/managed-targets#inspect-and-clean-up) for routine cleanup.
+
+Managed target directories live under a versioned root (`targets/v1/…`), and the `target` symlink in each checkout keeps working across upgrades.
+
+The store is also not fsynced. Cached objects and action results are published by atomic rename, so a reader sees a whole file or none, but a crash or power cut before the bytes reach disk can leave a file whose content does not match its name. Every object is checked against its content hash the first time a build reads it, and one that fails is a miss: the compilation runs again and its result is republished over the bad bytes. Records that only shortcut work, such as the input list a finished compilation leaves for the next build of the same invocation, are written the same way and ignored when they fail to parse. `mbx cache verify` reads the whole store back and reports any object left in that state.
+
+## JSON output is versioned [​](#json-output-is-versioned)
+
+`mbx doctor --json`, `mbx stats --json`, `mbx cache stats --json`, `mbx gc --json`, and `MBX_STATS_REPORT` emit versioned documents; fields are added compatibly and a shape change bumps the version. Scripts should read the version field and parse the JSON. The `mbx[...]` stderr lines are written for people and may be reworded at any time.
+
+### Session event streams are not a public API [​](#session-event-streams-are-not)
+
+The per-compilation streams under `sessions/v1/` that back [`mbx tui`](https://mr-boxington.jdx.dev/tui) are an implementation detail of that command. Their records carry a version field, but the format may change in any release. Use mbx commands to read them; scripts should consume `MBX_STATS_REPORT` for build statistics.
+
+## Configuration [​](#configuration)
+
+Unknown TOML keys and invalid values are errors, so an upgrade that renames or retires a setting fails instead of ignoring what you wrote.
+
+## Wire protocols and crates [​](#wire-protocols-and-crates)
+
+The local shim/agent protocol requires exact protocol and application-version equality. Embedders can connect to it, but must upgrade their client alongside mbx when that exact-match version changes. The remote cache protocol is versioned under `/v1/` with explicit evolution rules. Published Rust subcrates remain on `0.x`, so their APIs may change in a minor release. See [protocol compatibility](https://mr-boxington.jdx.dev/protocol-compatibility) for the details.
+
+`mbx-cache-cargo`, `mbx-cache-store`, `mbx-cache-core`, `mbx-cache-rustc`, and `mbx-cache-cc` are supported building blocks for coordinated embedding. They stay on `0.x`: their public APIs can change in a new minor release, and embedders should pin a compatible minor. Store and wire formats remain independently versioned and treat unfamiliar records as cache misses.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/stability.md)
+
+Last updated:
+
+Pager
+
+[Previous pageremove](https://mr-boxington.jdx.dev/cli/cache/remove)
+
+[Next pageProtocol compatibility](https://mr-boxington.jdx.dev/protocol-compatibility)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/standalone-builds.md

@@ -0,0 +1,102 @@
+Cache C and C++ builds outside Cargo
+
+Cache C and C++ builds outside Cargo [​](#cache-c-and-c-builds-outside-cargo)
+
+Use `mbx exec` to cache compiler calls made by make, CMake, and other build tools:
+
+sh
+
+```
+mbx exec make -j8
+```
+
+For CMake, run the configure step through `mbx exec` too. CMake chooses a compiler while configuring and reuses that choice when it builds.
+
+sh
+
+```
+mbx exec cmake -S . -B build
+mbx exec cmake --build build
+```
+
+Only the command after `mbx exec` uses these compiler wrappers. There is no daemon or global compiler setup. For C and C++ compiled by Cargo build scripts, use `mbx build`; that integration is [enabled by default](https://mr-boxington.jdx.dev/configuration#build-script-c-and-c).
+
+## What `mbx exec` does [​](#what-mbx-exec-does)
+
+While the command runs, mbx puts wrappers for the common compiler names at the front of `PATH`:
+
+text
+
+```
+cc  c++  gcc  g++  clang  clang++
+```
+
+On Windows it wraps `cl.exe` instead.
+
+When the build tool calls one of those names, mbx checks the cache first. On a hit, it restores the object file. On a miss, it runs the compiler that would normally have been found on `PATH` and saves the result.
+
+The wrappers use the same local and remote cache as Cargo builds. The command's exit status and compiler output are passed through unchanged, and the wrappers go away from `PATH` when the command finishes.
+
+## CMake and other configured builds [​](#cmake-and-other-configured-builds)
+
+Some build systems save the compiler's absolute path during configuration. CMake writes it to `CMakeCache.txt`; autoconf may write it into generated makefiles. If configuration happens outside `mbx exec`, the saved path points straight to the compiler and later `mbx exec` builds cannot intercept it.
+
+For an existing CMake build configured with a direct compiler path, configure a fresh build directory through `mbx exec`. Changing `PATH` during a later build does not replace the compiler saved in `CMakeCache.txt`.
+
+Configure through `mbx exec` so the build system records mbx's wrapper. That path remains valid across later commands. You should still use `mbx exec` for each build you want cached:
+
+sh
+
+```
+# Configure once.
+mbx exec cmake -S . -B build
+
+# Build as often as needed.
+mbx exec cmake --build build
+```
+
+Running `cmake --build build` without `mbx exec` still works, but it calls the real compiler without using the cache.
+
+## What gets cached [​](#what-gets-cached)
+
+mbx caches ordinary gcc-, clang-, and MSVC-style compile commands that compile one C or C++ source file into an object. It also caches GCC/Clang preprocessing to a file (`-E ... -o file`), using checkout-specific keys to preserve literal paths in the output. It does not cache links, multi-source compiler calls, or commands whose behavior it cannot model safely. Those commands still run normally; the session summary counts their bypasses, and `MBX_SUMMARY=full` reports the grouped reasons.
+
+`mbx exec` only intercepts the unversioned compiler names listed above. It leaves commands such as `gcc-13`, absolute compiler paths, and explicitly selected cross-compilers alone.
+
+See [limits](https://mr-boxington.jdx.dev/limits#c-and-c-caching-covers-the-host-compiles-mbx-drives) for the complete list of supported and bypassed invocations.
+
+## Sharing results across checkouts [​](#sharing-results-across-checkouts)
+
+mbx removes the checkout's absolute path from compilation keys, so equivalent checkouts can share cached objects. It normally treats the enclosing Git or Jujutsu checkout as the project root. Outside a checkout, it uses the working directory. Override that choice with `--project-root`:
+
+sh
+
+```
+mbx exec --project-root /path/to/project make -j8
+```
+
+To find the same project in another checkout, mbx uses the `Cargo.lock` digest when one exists, then the Git or Jujutsu `origin` URL, and finally the directory name. If only the directory name is available, matching directory names are required for cross-checkout hits.
+
+## Disabling the cache [​](#disabling-the-cache)
+
+Set `MBX_CC=0` to run the command without C or C++ caching:
+
+sh
+
+```
+MBX_CC=0 mbx exec make
+```
+
+C and C++ compilation is the only work `mbx exec` caches, so this runs the command without compiler caching. For published artifacts, follow the [production release policy](https://mr-boxington.jdx.dev/github-action#production-releases).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/standalone-builds.md)
+
+Last updated:
+
+Pager
+
+[Previous pageWatching builds](https://mr-boxington.jdx.dev/tui)
+
+[Next pageGitHub Action](https://mr-boxington.jdx.dev/github-action)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,49 @@
+Savings and statistics
+
+Savings and statistics [​](#savings-and-statistics)
+
+`mbx stats` shows what sharing builds has saved on this machine, with the date counting began and durations such as `50m 59s` or `2d 4h`.
+
+sh
+
+```
+mbx stats
+mbx stats --json
+```
+
+The report combines lifetime savings with a snapshot of the cache and its recorded workspaces. The **Store** screen in [`mbx tui`](https://mr-boxington.jdx.dev/tui) shows the same savings and sharing figures. `mbx cache stats` remains the smaller report about the action store, managed targets, and learned incremental state currently held.
+
+## What the numbers mean [​](#what-the-numbers-mean)
+
+| Figure | Meaning |
+| --- | --- |
+| Compiler time avoided | Estimated compiler work skipped by cache hits, accumulated across builds. Parallel compilation means this is not elapsed wall-clock time saved. |
+| Cache hits | Compilations served from cache since counting began. |
+| Pruned by mbx | Cumulative bytes collected from managed targets and the cache, including both automatic sweeps and explicit `mbx gc` runs. |
+| Automatically pruned | Bytes collected by automatic sweeps, with a separate start date. Older versions did not distinguish automatic from explicit GC, so their history is not guessed or backfilled. |
+| Requested removals | Bytes removed by confirmed migrations or explicit workspace removals, kept separate from pruning. |
+| Copying avoided | Cumulative output bytes materialized by reflink rather than copying. This is not the amount of disk space currently saved: files may later change or be deleted. |
+| With separate caches | Sum of logical cache bytes reachable by each live recorded workspace, counting shared content once for each workspace. |
+| Duplication avoided | A conservative lower-bound estimate: the separate-cache sum minus the entire shared store, floored at zero. Unclaimed objects in the store make this underestimate sharing. |
+
+The sharing estimate covers logical cache bytes, excludes target directories, and includes independent workspaces as well as worktrees. It does not measure physical filesystem blocks. On an active machine, builds can change the store while the report is being read. Workspace attribution walks cache records and targets; the TUI refreshes it every 30 seconds while the Store screen is open.
+
+Dates use UTC. Missing savings history is shown as unrecorded; reading a report does not start a new ledger. The automatic-pruning period begins with the first ledger update from a version that tracks it separately.
+
+## A little personality [​](#a-little-personality)
+
+With the default `savings = "quips"`, the text report and TUI add a line grounded in the recorded figures, such as “321 compilations served reheated. rustc can finish its coffee.” Set `savings = "plain"` or `savings = "off"` to omit the quip. Explicitly requested statistics are still shown.
+
+The [versioned JSON report](https://mr-boxington.jdx.dev/stability#json-output-is-versioned) includes `version`, `store`, `savings`, `cache`, and `sharing`. It uses integer bytes, nanoseconds, and Unix timestamps; an unknown start time is `null`. Its field names identify estimates and cumulative counters. JSON never contains quips.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/stats.md)
+
+Last updated:
+
+Pager
+
+[Previous pageCache results](https://mr-boxington.jdx.dev/cache-results)
+
+[Next pageHow it works](https://mr-boxington.jdx.dev/how-it-works)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)