@xgent-ai/skills 0.1.0 → 0.4.0

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

@@ -0,0 +1,140 @@
+Benchmarks
+
+Benchmarks [​](#benchmarks)
+
+mbx is measured against plain Cargo and [kache](https://github.com/kunobi-ninja/kache) on [jdx/hk](https://github.com/jdx/hk), a mid-size Rust CLI with C dependencies, pinned to one commit and built with `cargo build --locked`. The scenarios cover work a developer or CI runner may repeat. Published results come from GitHub Actions. The page labels a tool fastest only when its lead exceeds the observed variation between trials.
+
+[warm8.1s1.25× faster than kache](#warm) [commit26.2s1.66× faster than Cargo](#commit) [edit6.0slevel with Cargo](#edit) [contention1m 9s23.7s sooner than scheduler off](#contention)
+
+### warm CI rebuilds a commit it has already built
+
+The store is warm from an earlier build of the same commit and target/ is empty. Cargo is left out: with nothing to reuse it would repeat that earlier build.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| mbxfastest |  | 8.1s 7.9–8.6s |
+| kache |  | 10.1s 9.8–10.3s |
+
+mbx fastest, 2.0s ahead of kache. That lead is wider than either tool's own range across 3 runs.
+
+mbx restored 1,560 output files on 722 cache hits.
+
+### commit CI builds the next push
+
+The caches were warmed at the parent commit and build the child. Cargo has no cache to restore, so its row is the uncached build.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| mbxfastest1.66× faster than Cargo |  | 26.2s 25.7–26.5s |
+| kache1.53× faster than Cargo |  | 28.4s 28.3–28.8s |
+| Cargouncached |  | 43.5s 42.5–44.3s |
+
+mbx fastest, 2.2s ahead of kache. That lead is wider than either tool's own range across 3 runs.
+
+mbx restored 1,558 output files on 721 cache hits.
+
+### edit One line changed, rebuilt in place
+
+The local edit loop with incremental compilation on. Cargo's own incremental rebuild is the thing to beat here, not a control.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| Cargoincremental rebuild |  | 5.9s 5.8–5.9s |
+| mbxlevel with Cargo |  | 6.0s 5.9–6.1s |
+| kachelevel with Cargo |  | 6.1s 5.9–6.1s |
+
+Too close to call: Cargo and mbx finished 0.09s apart, inside the 0.2s one of them moved across its own runs.
+
+mbx restored 2 output files on 1 cache hits.
+
+First edit after a build, before the loop settles: Cargo 6.3s, mbx 22.6s, kache 24.8s.
+
+### contention Six CI jobs on one runner
+
+Overlapping check, Clippy, and test-compilation jobs. Run one after another, then all at once with and without mbx's machine-wide compiler limit.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| sequential31 compilers at peak, 63.2 GB free at the low |  | 1m 49s 107.7–109.6s |
+| parallelscheduler off170 compilers at peak, 54.1 GB free at the low |  | 1m 33s 90.7–93.7s |
+| parallelmbx schedulerfastest32 of 32 permits used, 61.7 GB free at the low |  | 1m 9s 60.4–72.3s |
+
+With the scheduler on, the parallel batch finished 23.7s sooner than unscheduled and 39.5s sooner than running the jobs in turn, peaking at 32 compilers instead of 170.
+
+Cache hits over the batch: sequential 8; parallel, scheduler off 12; parallel, mbx scheduler 3,390. The scheduler holds identical compilations until the first finishes, so the other jobs hit the store instead of repeating the work.
+
+Measured on Linux-7.1.4-x86\_64-with-glibc2.39 (nsc-runner-g7llknk0pjtlu) with Rust 1.97.1, building `hk` at `fc29ead` under mbx 1.11.1, cargo 1.97.1 (c980f4866 2026-06-30), rustc 1.97.1 (8bab26f4f 2026-07-14), kache 0.21.0. [The run that produced them](https://github.com/jdx/mr-boxington/actions/runs/34930250982) has the per-build logs.
+
+## Reading the results [​](#reading-the-cards)
+
+Each scenario has three independent trials per tool. A trial starts with a fresh clone and empty store, then performs the scenario's warm-up and measured builds. The bar shows the median; the whisker spans the fastest and slowest trial. A tool is marked fastest only when its lead exceeds both tools' trial ranges. Otherwise, the card reports no clear winner.
+
+The Cargo row means something different in each scenario, so the card tags it. In the commit scenario it is the uncached build CI does without a cache. In the edit scenario it is the incremental rebuild the caches have to keep up with. The warm scenario has no Cargo row, because with an empty `target/` Cargo would repeat the build that warmed the store.
+
+## The scenarios [​](#the-scenarios)
+
+### Warm build [​](#warm-build)
+
+A first build warms the store, then `target/` is wiped and the same commit builds again. This is a runner restoring its cache and building something it has already seen.
+
+### Next commit [​](#next-commit)
+
+The store is warmed at one commit and the build runs at the next. Most of the dependency graph is unchanged and a few crates are not. Cargo's row is a cold build, since with an empty `target/` that is all it can do.
+
+### Local edit [​](#local-edit)
+
+A full build, then one line of hk's own source changed and rebuilt in the same `target/` with incremental compilation on. This measures the edit/build loop, including cache bookkeeping and incremental compilation. Two details make the comparison useful:
+
+- `CI` is unset for every tool. mbx switches [learned incremental reuse](https://mr-boxington.jdx.dev/incremental#learned-incremental-reuse) off in CI because fresh runners have no earlier edit state to reuse.
+- The first edit establishes incremental state; the second supplies the headline timing. Cargo's own build already wrote its incremental state, while mbx builds an edited crate's [private state](https://mr-boxington.jdx.dev/incremental#learned-incremental-reuse) on the first edit and reuses it afterwards. The card shows what that first edit cost, since a developer waits for it once per fresh build.
+
+### Six parallel jobs [​](#six-parallel-jobs)
+
+Six overlapping Rust CI jobs from an empty store: default and all-targets/all-features variants of `cargo check`, Clippy, and test compilation. The sequential row runs them in turn in one `target/`. The two parallel rows give each job its own `target/`, as separate CI steps would, and differ only in whether the [machine-wide scheduler](https://mr-boxington.jdx.dev/scheduling#machine-wide-compile-scheduling) is on. Cargo bounds the compilers it starts itself and knows nothing about the Cargo process beside it; the scheduler gives every process one pool of permits and holds identical compilations until the first finishes. Peak compilers and lowest free memory show whether a faster batch shared the machine or oversubscribed it.
+
+## Keeping it fair [​](#keeping-it-fair)
+
+- The registry is fetched once, before any timed build. No cell is timed while it downloads crates.
+- Every trial starts from a fresh clone, an empty store, and a new `target/`. Nothing carries over between tools or between runs.
+- The toolchain is the runner's, the same as any user's build, and the `toolchain` field in `results.json` records which release produced the numbers. Every trial in a run uses that one compiler, so the tools are compared fairly against each other. A Rust bump between runs changes every cache key at once, which reads as a cache that stopped working, so check that field before treating a drop across runs as a regression.
+- `CARGO_INCREMENTAL=0` matches CI everywhere except the edit scenario. Any inherited `RUSTC_WRAPPER` is cleared, and the run fails if the Cargo baseline turns out to be an mbx shim.
+- Both caches run local-only. A remote would measure the network.
+- Validity checks reject runs that do not exercise the intended cache behavior. That is any run where a warm build restored nothing or was no faster than the build that seeded it, where the edit rebuild compiled nothing, or where the scheduled contention batch went past its permits or the unscheduled one never did.
+
+## Running it yourself [​](#running-it-yourself)
+
+sh
+
+```
+mise run bench
+```
+
+That builds mbx, clones hk, and runs the warm, commit, and edit scenarios once each. kache is included when it is on `PATH` and noted as skipped otherwise. `mise run bench:refresh` is what CI runs: every scenario, three trials each, written to `benchmarks/results.json`.
+
+The [bench-refresh workflow](https://github.com/jdx/mr-boxington/actions/workflows/bench-refresh.yml) checks weekly and reruns when the recorded mbx version differs from the latest release. It measures that released version and opens a pull request with the results. On `main`, a manual run with `force` also opens or updates that PR, even when the recorded version already matches. Set `dry_run` to measure without proposing an update, or `source` to measure the selected source ref instead of the latest release; `source` implies `dry_run`.
+
+## What this does not measure [​](#what-this-does-not-measure)
+
+These results describe the pinned hk workload. A project with a very different dependency shape, such as heavy proc macros, a large C component, or many small leaf crates, will see different ratios. Three trials expose some variation; their ranges are not confidence intervals, and a “fastest” label is a display heuristic, not a statistical significance test. The benchmark is Linux-only, and [limits](https://mr-boxington.jdx.dev/limits) covers what changes on macOS and Windows.
+
+Instruction-counted measurements of mbx's own startup path, and cold and warm correctness runs against this workspace, live in [`benchmarks/`](https://github.com/jdx/mr-boxington/tree/main/benchmarks).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/benchmarks.md)
+
+Last updated:
+
+Pager
+
+[Previous pageHow mbx compares](https://mr-boxington.jdx.dev/compared)
+
+[Next pageFAQ](https://mr-boxington.jdx.dev/faq)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,153 @@
+Cache results
+
+Cache results [​](#cache-results)
+
+Use the build summary to see what mbx restored, compiled, or left uncached. Counts describe compiler actions observed by mbx; they do not include work Cargo skipped because its outputs were already fresh.
+
+sh
+
+```
+mbx explain --last          # inspect the most recent recorded build
+MBX_SUMMARY=full mbx build  # print a detailed report for a new build
+```
+
+| Outcome | Cache lookup? | Result stored? |
+| --- | --- | --- |
+| [Hit](#hit) | Found a result | Already stored |
+| [Miss](#miss) | No matching result | After successful compilation |
+| [Not looked up](#could-not-look-up) | No usable input prediction yet | After successful compilation |
+| [Bypass](#bypass) | Skipped | No shared result |
+
+## Measure cache reuse [​](#measure-cache-reuse)
+
+Running the same command twice in the same target directory often measures Cargo's freshness check: no compiler work is needed. To observe mbx reuse, build equivalent source with the same toolchain, profile, and features into two fresh target directories:
+
+sh
+
+```
+mbx build --target-dir target/cache-demo-first
+mbx build --target-dir target/cache-demo-second
+```
+
+Use directory names that do not already contain build outputs. This keeps your normal target intact and avoids deleting the shared cache. The second build can restore work recorded by the first; unsupported actions still run. These explicit targets are not managed, so remove the two example directories when you finish. For repeatable timings, use the [benchmark harness](https://mr-boxington.jdx.dev/benchmarks).
+
+Compiler time avoided is summed across actions. It is not elapsed time saved; always compare wall-clock build time as well as the counters.
+
+## Hit [​](#hit)
+
+mbx derived an action key, found its result, and restored the outputs. A hit can come from the local store or a configured remote.
+
+## Miss [​](#miss)
+
+mbx derived a key and looked it up, but no result existed. The compilation ran and its successful result was stored.
+
+## Could not look up [​](#could-not-look-up)
+
+mbx did not yet have usable dep-info or a prediction from which to derive the key. This is common on a cold build. The action is still stored after compilation, so calling it a miss would overstate the number of failed lookups. The short summary counts these as `not looked up`; the full summary prints a `could not look up` line with the reason.
+
+## Bypass [​](#bypass)
+
+mbx recognized that it could not model the action exactly and ran the real compiler without caching it. The short summary's `bypassed` count leaves out routine compiler probes (`compiler-query`, `standard-input`, and their `cc-` counterparts). Reasons are grouped in the full summary (`MBX_SUMMARY=full`); set `MBX_BYPASS_LOG` to a file path for the per-action record.
+
+Run a Cargo command through `mbx explain` to collect those records temporarily, group identical causes, and print guidance for every bypass category:
+
+sh
+
+```
+mbx explain build --workspace
+```
+
+text
+
+```
+cache explanation: 8 compilations bypassed the cache
+
+compiler-query (2)
+Expected: Cargo asks rustc for toolchain information; there is no compilation to cache.
+  - rustc invocation is a compiler query, not a compilation (2 times)
+
+incremental (5)
+Cargo compiled this incrementally, which mbx cannot cache. `MBX_INCREMENTAL=0` makes it cacheable again; mbx already gives a crate you are editing its own incremental state without giving up the rest of the cache.
+  - incremental compilation cannot be combined with action caching (5 times)
+
+standard-input (1)
+Expected for Cargo probes: source supplied on standard input cannot be rediscovered later.
+  - rustc invocation reads source from standard input
+```
+
+Categories marked expected are routine compiler probes, with no output to cache; here the `incremental` group is the one the build could act on. The command preserves Cargo's exit status after printing the explanation.
+
+Actionable bypasses carry their remediation with the reason that produced them. For example, links rejected because of `split-debuginfo=packed` point to the active Cargo profile or `RUSTFLAGS`, while C compilations affected by `CPATH` name the environment variable to unset.
+
+`mbx explain` also reports cacheability problems that prevent a compilation from reaching mbx at all. If `CC`, `CXX`, `HOST_CC`, or `HOST_CXX` was already set when the build began, the report names the variable and value and explains that host C and C++ compiles are invisible to the cache. These are warnings, not bypass counts, because mbx never observed the compiler invocations.
+
+## Remote failure [​](#remote-failure)
+
+A remote cache request failed and the build continued without that result: an unreachable host, refused credentials, or an invalid response can all reduce reuse. Build-time transport failures fall back to local compilation. Invalid configuration can still stop startup, and explicit `mbx prefetch` and `mbx doctor` commands report connection failures as errors. The summary counts them because a remote that is failing every request reports the same hits, misses, and bytes as one that was empty. The short summary includes the count inline; the full summary explains it:
+
+text
+
+```
+mbx[cache]: the remote cache failed 4 of its requests; this build ran without what it could not reach, and the warnings above say why
+```
+
+The individual warnings, printed as the build runs, say what failed. The count also appears as `remote_failures` in the JSON statistics report, so CI can alert on a cache that has quietly stopped serving.
+
+## Watching a build instead [​](#watching-a-build-instead)
+
+Everything above describes results reported after a build. To see the same outcomes as they are decided, one row per compilation with the crate it belongs to, run [`mbx tui`](https://mr-boxington.jdx.dev/tui) in another terminal. It reads builds using the same local cache, including ones already running.
+
+## Reading the hit rate [​](#reading-the-hit-rate)
+
+A build can report a high hit rate among attempted lookups while spending most of its time on actions that were not looked up or were bypassed. Read all the summary counts together, and compare wall-clock time when evaluating the cache. Set `MBX_SUMMARY=full` when the one-line counts need a breakdown.
+
+A link mbx cannot describe always runs, so its downstream crates may have work to do on an otherwise warm build. Native executables, tests, and proc macros on Linux, macOS, and Windows, plus binaries, tests, and `cdylib`s for supported self-contained WebAssembly targets, may be restored as hits; see [limits](https://mr-boxington.jdx.dev/limits#native-linking-is-cached-only-where-the-linker-can-be-described).
+
+## Troubleshooting a low hit rate [​](#troubleshooting-a-low-hit-rate)
+
+Run the build through `mbx explain` first. It collects the per-action records, groups identical causes, and prints guidance for each category:
+
+sh
+
+```
+mbx explain build --workspace
+```
+
+The usual causes, roughly in the order they show up:
+
+- The store is cold. A first build has no dep-info to derive keys from, so "could not look up" can dominate. Compare equivalent builds with fresh targets as described [above](#measure-cache-reuse).
+- Incremental builds are enabled. With `MBX_INCREMENTAL=1`, workspace members compile incrementally, those compilations bypass the cache, and the changed artifacts make crates above them miss too. See [limits](https://mr-boxington.jdx.dev/limits#incremental-compilations-are-not-cached).
+- A link could not be described. Native executables, tests, and proc macros are cached on Linux, macOS, and Windows, and self-contained WebAssembly targets everywhere, but native links with custom or unmodeled inputs still run. A rebuilt dylib can also change the keys of its downstream crates. `mbx explain` reports why the link bypassed; see [limits](https://mr-boxington.jdx.dev/limits#native-linking-is-cached-only-where-the-linker-can-be-described).
+- The inputs differ. A different toolchain, feature set, profile, or `RUSTFLAGS` between two checkouts is a different key, and the summary reports it as an ordinary miss. Run `mbx explain --last` to replay the most recent recorded build and list, per missed crate, the key inputs that changed since its last recorded hit. Session history stores hashes, not source contents or environment values.
+- Build-script output that differs. mbx can share Rust compilations that read `OUT_DIR` when the generated output matches across checkouts. A build script that embeds the checkout path in its output prevents that reuse. Sharing also depends on whether mbx can detect the reference and copy the output; `MBX_SHARE_OUT_DIR=0` disables it. See [`OUT_DIR` sharing](https://mr-boxington.jdx.dev/limits#out-dir-sharing).
+- A build chose its own C compiler, or is cross-compiling. Setting `CC`, `HOST_CC`, `CXX`, or `HOST_CXX` leaves host compilations outside mbx. Cross-compilations are cached when the build explicitly names a supported compiler through `CC_<target>`, `CXX_<target>`, `TARGET_CC`, or `TARGET_CXX`. Bypass kinds beginning `cc-` report anything the C adapter declined to model. See [limits](https://mr-boxington.jdx.dev/limits#c-and-c-caching-covers-the-host-compiles-mbx-drives).
+- CI restored nothing. On GitHub Actions, check that the cache step restored an entry; a changed `cache-generation` or a fresh repository starts empty. With a remote cache configured, check the [remote failure](#remote-failure) count too: a remote that is failing every request reports the same zeros as one that is empty.
+
+## Compiler time [​](#compiler-time)
+
+The full summary reports real compiler time by outcome and an estimate of the compiler time avoided by cache hits:
+
+text
+
+```
+mbx[cache]: compiler time: 4m 12s estimated avoided; 38.20s spent (161 miss in 31.00s, 7 unconsulted in 7.20s)
+mbx[cache]: slowest uncached crates: syn 8.90s, regex-syntax 4.90s, serde_derive 3.90s
+```
+
+Times of a minute or more are reported in whole units, as above; shorter ones keep their fraction.
+
+The estimate comes from the duration recorded with the successful compilation that populated the action prediction; older predictions without a timing hint contribute zero. The five crates with the largest cumulative uncached compiler time are listed so you can identify expensive uncached work. Parallel compilations overlap, so this ranking does not directly identify the critical path.
+
+The JSON statistics report exposes the same data in `estimated_compiler_duration_avoided_ns`, `compiler`, and `slow_compilations`.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/cache-results.md)
+
+Last updated:
+
+Pager
+
+[Previous pageTroubleshooting](https://mr-boxington.jdx.dev/troubleshooting)
+
+[Next pageSavings and statistics](https://mr-boxington.jdx.dev/stats)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

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

@@ -0,0 +1,151 @@
+Cache server
+
+Cache server [​](#cache-server)
+
+[`jdx/mr-boxington-cache`](https://github.com/jdx/mr-boxington-cache) is the self-hostable remote cache server. It implements version 1 of the mbx action-cache protocol: immutable blobs, atomic action-result commits, namespace isolation, and streaming blob packs. It also serves [mise](https://mise.jdx.dev)'s task cache. Any server implementing the [protocol](https://mr-boxington.jdx.dev/protocol-compatibility) works with mbx; this page documents the reference implementation.
+
+## Run it [​](#run-it)
+
+Clone the server repository before starting its development stack. It runs the service, PostgreSQL, and MinIO:
+
+sh
+
+```
+git clone https://github.com/jdx/mr-boxington-cache.git
+cd mr-boxington-cache
+docker compose up --build
+```
+
+For a standalone instance with filesystem storage:
+
+sh
+
+```
+cargo install mbx-cache --locked
+mbx-cache \
+  --allow-anonymous \
+  --data-dir ./data \
+  --listen 127.0.0.1:8080
+```
+
+The standalone example binds to loopback and allows anonymous access for local evaluation. Production installations should terminate TLS at an ingress or proxy and configure tokens. The repository ships a Helm chart for horizontally scaled Kubernetes deployments and a Terraform-managed single-host example.
+
+Connect mbx to the local example with this global configuration:
+
+toml
+
+```
+[remote]
+url = "http://127.0.0.1:8080"
+namespace = "example/project"
+mode = "read-only"
+```
+
+Run `mbx doctor` to check connectivity. A local shell is read-only even when `mode` is `read-write`; use [trusted CI](https://mr-boxington.jdx.dev/remote-cache#read-and-write-policy) to populate the remote through mbx. For an authenticated deployment, use HTTPS and add a token or OIDC audience as described in [Remote cache](https://mr-boxington.jdx.dev/remote-cache).
+
+## Configuration [​](#configuration)
+
+Every option has a matching environment variable and CLI flag; run `mbx-cache --help` for the complete list.
+
+| Environment variable | Default | Purpose |
+| --- | --- | --- |
+| `MBX_CACHE_LISTEN` | `0.0.0.0:8080` | Listen address |
+| `MBX_CACHE_STORAGE` | `filesystem` | `filesystem` or `s3` |
+| `MBX_CACHE_DATA_DIR` | `/var/lib/mbx-cache` | Filesystem blob root |
+| `MBX_CACHE_DATABASE_URL` | `memory://` | PostgreSQL URL or development memory store |
+| `MBX_CACHE_S3_BUCKET` | none | Required for S3 storage |
+| `MBX_CACHE_S3_PREFIX` | `v1` | Object-key prefix |
+| `MBX_CACHE_S3_ENDPOINT` | AWS default | S3-compatible endpoint |
+| `MBX_CACHE_S3_REGION` | `us-east-1` | S3 region |
+| `MBX_CACHE_S3_PATH_STYLE` | `false` | Enable for MinIO and similar services |
+| `MBX_CACHE_TOKENS_JSON` | none | Static token grants |
+| `MBX_CACHE_OIDC_PROVIDERS_JSON` | none | Trusted OIDC providers and claim grants |
+| `MBX_CACHE_ALLOW_ANONYMOUS` | `false` | Allow access without configured grants |
+| `MBX_CACHE_MAX_BLOB_BYTES` | `5368709120` | Maximum upload size |
+
+AWS credentials use the standard SDK credential chain, including environment variables, workload identity, ECS, and EC2 roles.
+
+## Authorization [​](#authorization)
+
+Authorization is deny-by-default. Namespace patterns may be an exact name, `*`, or a prefix ending in `/*`.
+
+### Static tokens [​](#static-tokens)
+
+`MBX_CACHE_TOKENS_JSON` is an array of grants:
+
+json
+
+```
+[
+  {
+    "token": "replace-with-a-secret",
+    "read": ["acme/*", "public"],
+    "write": ["acme/project-a"]
+  }
+]
+```
+
+Rotate tokens by deploying the old and new grants together, moving clients to the new token, then removing the old grant. Inject the JSON through a secret, not through deployment configuration.
+
+### OIDC [​](#oidc)
+
+OIDC lets CI use short-lived identity tokens instead of stored secrets. Configure trusted issuers, acceptable audiences, and claim-based grants. This example grants access only to pushes on `acme/backend`'s `main` branch. Replace the numeric owner ID and add separate read-only rules for any other identities that need access:
+
+json
+
+```
+[
+  {
+    "issuer": "https://token.actions.githubusercontent.com",
+    "audiences": ["https://cache.example.com"],
+    "rules": [
+      {
+        "claims": {
+          "repository": "acme/backend",
+          "repository_owner_id": "12345",
+          "ref": "refs/heads/main",
+          "event_name": "push"
+        },
+        "read": ["acme/backend"],
+        "write": ["acme/backend"]
+      }
+    ]
+  }
+]
+```
+
+The server discovers the issuer's JWKS endpoint and verifies the signature, issuer, audience, expiry, not-before time, and subject before applying the first matching rule. Rules are alternatives; every claim within a rule must match exactly. Pin stable identity claims such as GitHub's numeric `repository_owner_id` alongside the repository name, since names can be reclaimed and the ID cannot. Add `ref` or `environment` claims when only a narrower workflow identity should write. Symmetric JWT algorithms are never accepted.
+
+On the client side, mbx acquires the GitHub Actions job token itself: set `MBX_REMOTE_OIDC_AUDIENCE`, or use [`jdx/mr-boxington-action`](https://github.com/jdx/mr-boxington-action) with `backend: server` as shown in [GitHub Action](https://mr-boxington.jdx.dev/github-action#cache-server).
+
+## Operations [​](#operations)
+
+For S3-backed storage, expire blobs with a bucket lifecycle rule. Run a separate metadata sweep to remove old records; this command exits after cleanup without starting the server:
+
+sh
+
+```
+mbx-cache --sweep-metadata-older-than-days 35
+```
+
+Keep the sweep age longer than the storage lifecycle so objects expire first. A dangling reference is never fatal: a client that cannot fetch a blob treats the action as a miss and recompiles.
+
+Multiple stateless replicas can run against the same PostgreSQL database and S3 bucket. Readiness and liveness probes use `/v1/status`, and `/metrics` exposes Prometheus counters for actions, blobs, and blob-pack transfers with fixed, low-cardinality labels. Namespaces, tokens, and digests never appear as labels. The server has no deletion endpoint. Retention and disaster recovery are administrative concerns: back up PostgreSQL, and use bucket versioning or replication as required.
+
+A server advertising action promises can coordinate identical cold compilations across replicas. Claims are short-lived database leases scoped by namespace and invocation digest; completion is accepted only after the named action result is durable. Abandoned claims expire, completed promises are immutable for their retention window, and no promise endpoint bypasses the namespace's write authorization.
+
+## Protocol [​](#protocol)
+
+The wire protocol (endpoints, media types, canonical hashing, and the evolution rules) is documented in [protocol compatibility](https://mr-boxington.jdx.dev/protocol-compatibility). The [repository README](https://github.com/jdx/mr-boxington-cache) covers implementation details beyond it, including blob-pack framing and validation behavior.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/cache-server.md)
+
+Last updated:
+
+Pager
+
+[Previous pageRemote cache](https://mr-boxington.jdx.dev/remote-cache)
+
+[Next pageTroubleshooting](https://mr-boxington.jdx.dev/troubleshooting)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/cli/adopt.md

@@ -0,0 +1,29 @@
+mbx adopt
+
+`mbx adopt` [​](#mbx-adopt)
+
+- **Usage:** `mbx adopt [-r --recursive] [--dry-run] [PATH]…`
+
+Bring existing Cargo target directories under mbx management without deleting their contents.
+
+mbx moves each directory under the managed root and leaves a `target` link in its place. The adopted directory then follows the usual managed-target collection policy.
+
+## Arguments [​](#arguments)
+
+- **`[PATH]…`** — Cargo checkouts to adopt, or directories to search with --recursive. Defaults to the current directory.
+
+## Flags [​](#flags)
+
+- **`-r --recursive`** — Search below each path for Cargo checkouts with a target directory. Hidden directories, target directories, and symbolic links are skipped.
+- **`--dry-run`** — Report what would be adopted without moving anything.
+- **`-h --help`** — Print help
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/crates/mbx/src/cli/adopt.rs)
+
+Last updated:
+
+Pager
+
+[Next pageDocumentation](https://mr-boxington.jdx.dev/guide)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/cli/cache/dir.md

@@ -0,0 +1,24 @@
+mbx cache dir
+
+`mbx cache dir` [​](#mbx-cache-dir)
+
+- **Usage:** `mbx cache dir [--json]`
+
+Print the store directory.
+
+## Flags [​](#flags)
+
+- **`--json`** — Print a stable machine-readable report.
+- **`-h --help`** — Print help
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/crates/mbx/src/cli/cache.rs)
+
+Last updated:
+
+Pager
+
+[Previous pagecache](https://mr-boxington.jdx.dev/cli/cache/)
+
+[Next pagestats](https://mr-boxington.jdx.dev/cli/cache/stats)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/cli/cache/export.md

@@ -0,0 +1,31 @@
+mbx cache export
+
+`mbx cache export` [​](#mbx-cache-export)
+
+- **Usage:** `mbx cache export [--group <GROUP>] [--format <FORMAT>] <ARCHIVE>`
+
+Export the cache closure of this checkout's last build. The export includes Cargo scheduler state for recorded workspaces, with compiler outputs referenced from the content-addressed closure instead of duplicated.
+
+## Arguments [​](#arguments)
+
+- **`<ARCHIVE>`** — Tar archive or directory to write.
+
+## Flags [​](#flags)
+
+- **`--group <GROUP>`** — Export every build that set MBX\_CACHE\_EXPORT\_GROUP to this CI group.
+- **`--format <FORMAT>`** — Bundle layout: tar for a portable archive, or directory for a transport that archives a directory itself, such as the GitHub Actions cache.
+
+  **Default:** `tar`
+- **`-h --help`** — Print help
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/crates/mbx/src/cli/cache.rs)
+
+Last updated:
+
+Pager
+
+[Previous pagetrace](https://mr-boxington.jdx.dev/cli/cache/trace)
+
+[Next pageimport](https://mr-boxington.jdx.dev/cli/cache/import)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/cli/cache/import.md

@@ -0,0 +1,27 @@
+mbx cache import
+
+`mbx cache import` [​](#mbx-cache-import)
+
+- **Usage:** `mbx cache import <ARCHIVE>`
+
+Import a cache export into the local store. A directory export is consumed: its objects are moved into the store and the directory is removed. If the export contains Cargo workspace state and the command runs from a matching checkout with an absent or empty target directory, restore that state as well. A non-empty target directory is never replaced.
+
+## Arguments [​](#arguments)
+
+- **`<ARCHIVE>`** — Tar archive or directory to import.
+
+## Flags [​](#flags)
+
+- **`-h --help`** — Print help
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/crates/mbx/src/cli/cache.rs)
+
+Last updated:
+
+Pager
+
+[Previous pageexport](https://mr-boxington.jdx.dev/cli/cache/export)
+
+[Next pageremove](https://mr-boxington.jdx.dev/cli/cache/remove)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/cli/cache/largest.md

@@ -0,0 +1,26 @@
+mbx cache largest
+
+`mbx cache largest` [​](#mbx-cache-largest)
+
+- **Usage:** `mbx cache largest [--limit <LIMIT>]`
+
+List the largest objects and action-result records.
+
+## Flags [​](#flags)
+
+- **`--limit <LIMIT>`** — Maximum entries to print.
+
+  **Default:** `20`
+- **`-h --help`** — Print help
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/crates/mbx/src/cli/cache.rs)
+
+Last updated:
+
+Pager
+
+[Previous pageprojects](https://mr-boxington.jdx.dev/cli/cache/projects)
+
+[Next pageverify](https://mr-boxington.jdx.dev/cli/cache/verify)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/cli/cache/projects.md

@@ -0,0 +1,23 @@
+mbx cache projects
+
+`mbx cache projects` [​](#mbx-cache-projects)
+
+- **Usage:** `mbx cache projects`
+
+Show cache use attributed to recorded workspaces.
+
+## Flags [​](#flags)
+
+- **`-h --help`** — Print help
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/crates/mbx/src/cli/cache.rs)
+
+Last updated:
+
+Pager
+
+[Previous pagestats](https://mr-boxington.jdx.dev/cli/cache/stats)
+
+[Next pagelargest](https://mr-boxington.jdx.dev/cli/cache/largest)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/cli/cache/remove.md

@@ -0,0 +1,30 @@
+mbx cache remove
+
+`mbx cache remove` [​](#mbx-cache-remove)
+
+- **Usage:** `mbx cache remove [--interactive] [WORKSPACE]`
+
+Remove managed targets, learned incremental state, and cache claims for one workspace or selected workspaces.
+
+Provide exactly one of `<WORKSPACE>` or `--interactive`.
+
+## Arguments [​](#arguments)
+
+- **`[WORKSPACE]`** — Workspace root to forget.
+
+## Flags [​](#flags)
+
+- **`--interactive`** — Select recorded workspaces to remove.
+- **`-h --help`** — Print help
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/crates/mbx/src/cli/cache.rs)
+
+Last updated:
+
+Pager
+
+[Previous pageimport](https://mr-boxington.jdx.dev/cli/cache/import)
+
+[Next pageStability](https://mr-boxington.jdx.dev/stability)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)