docs: update build and CI docs for the CPM flow

- README drops the submodule bootstrap and `build.sh setup` for the trilogy.
- ci-architecture documents the shared ~/.cache/moqx cache and how it is keyed.
- release replaces the `.moxygen-release` tag file with the MOXYGEN_REV pin, so a
  release/* branch must freeze on a v*-tagged rev.
- Repo paths are linked from the root so they resolve wherever they are rendered.

Author: michalhosna

README.md

@@ -6,7 +6,7 @@
 
 [![ci main](https://github.com/openmoq/moqx/actions/workflows/ci-main.yml/badge.svg)](https://github.com/openmoq/moqx/actions/workflows/ci-main.yml)
 [![Latest release](https://img.shields.io/github/v/release/openmoq/moqx?display_name=tag&sort=semver&logo=github)](https://github.com/openmoq/moqx/releases/latest)
-[![License](https://img.shields.io/github/license/openmoq/moqx)](LICENSE)
+[![License](https://img.shields.io/github/license/openmoq/moqx)](/LICENSE)
 [![Last commit](https://img.shields.io/github/last-commit/openmoq/moqx)](https://github.com/openmoq/moqx/commits/main)
 [![Open issues](https://img.shields.io/github/issues/openmoq/moqx)](https://github.com/openmoq/moqx/issues)
 [![Open PRs](https://img.shields.io/github/issues-pr/openmoq/moqx)](https://github.com/openmoq/moqx/pulls)
@@ -22,66 +22,55 @@ The OpenMOQ Relay — a MoQT relay server based on
 
 ## Architecture
 
-For the underlying moxygen library architecture (session model, data plane,
-threading, transport abstraction), see
-[deps/moxygen/ARCHITECTURE.md](deps/moxygen/ARCHITECTURE.md).
+`MoqxRelay` is a hard fork of moxygen's
+[`MoQRelay`](https://github.com/openmoq/moxygen/blob/main/moxygen/relay/MoQRelay.h),
+so the relay core can evolve independently while the lower-level moxygen pieces
+stay libraries:
 
-`MoqxRelay` is a hard fork of moxygen's `MoQRelay`. We copy the relay core into
-moqx so we can evolve it independently (threading model, custom cache miss
-handling, chained caches, etc.) while still using moxygen's lower-level
-building blocks as libraries:
+- **MoQForwarder** — fan-out engine
+- **MoqxCache** — object cache
+- **MoQSession / MoQServer / MoQRelaySession** — session/server infrastructure.
 
-- **MoQForwarder** — fan-out engine, used as-is from moxygen for now. May need
-  to fork in the future to accommodate threading model differences.
-- **MoqxCache** — object cache, hard-forked from moxygen. Customizable for moqx-specific functionality.
-  and chained cache support may be upstreamed to openmoq/moxygen or maintained
-  in our fork.
-- **MoQSession / MoQServer / MoQRelaySession** — session and server
-  infrastructure, used as libraries.
+`MoqxRelayServer` extends `MoQServer` to wire `MoqxRelay` in as the
+publish/subscribe handler. For moxygen's own architecture, see its
+[ARCHITECTURE.md](https://github.com/openmoq/moxygen/blob/main/ARCHITECTURE.md).
 
-`MoqxRelayServer` extends `MoQServer` to wire up `MoqxRelay` as the publish/subscribe
-handler and create `MoQRelaySession` instances for incoming connections.
+## Quick Start
 
-## Documentation
+Standard CMake preset build (CMake 3.23+, C++20, Ninja).
 
-- [docs/metrics.md](docs/metrics.md) — Prometheus metrics reference
+```bash
+scripts/install-system-deps.sh                         # toolchain + system libs
+scripts/configure.sh --moxygen prebuilt-with-fallback  # get a moxygen, configure
+scripts/build.sh                                       # cmake --build build/default
+scripts/test.sh                                        # ctest over build/default
+```
 
-## Design Documents
+`build.sh` and `test.sh` are thin wrappers that add a job count derived from
+cores and free RAM ([/scripts/lib/jobs.sh](/scripts/lib/jobs.sh)).
 
-- [design/ci-architecture.md](design/ci-architecture.md) — CI pipelines, upstream sync, auto-deploy
-- [design/configuration.md](design/configuration.md) — relay config file reference
-- [design/gummy-bear.md](design/gummy-bear.md) — cache and forwarding design
-- [design/hot-reloading.md](design/hot-reloading.md) — hot config reload
-- [design/miss-handler.md](design/miss-handler.md) — cache miss handling
+Profiles (`default` | `san` | `tsan`) are each script's first argument and map to
+`build/<profile>`. `--moxygen` picks where moxygen comes from:
 
-## Quick Start
+| Goal | Command |
+|------|---------|
+| Build it | `scripts/configure.sh --moxygen prebuilt-with-fallback && scripts/build.sh` |
+| Download only, never compile moxygen | `scripts/configure.sh --moxygen prebuilt && scripts/build.sh` |
+| Compile moxygen / any rev or platform | `scripts/configure.sh --moxygen from-source && scripts/build.sh` |
+| Local moxygen checkout | `scripts/configure.sh --moxygen from-source --moxygen-dir /path && scripts/build.sh` |
 
-> **Prerequisite: CMake 3.22+ is required.** All current targets ship a
-> new-enough version out of the box: Ubuntu 22.04+, Debian 12+, recent
-> macOS Homebrew. Verify with `cmake --version`. `build.sh` aborts early
-> if cmake is missing or too old (override with `MOQX_SKIP_CMAKE_CHECK=1`
-> if you know what you're doing).
+The three modes, the raw-cmake equivalents, and how to pick:
+[/BUILD.md](/BUILD.md#how-dependencies-work).
 
-```bash
-git clone https://github.com/openmoq/moqx.git && cd moqx
-git submodule update --init --recursive
-sudo deps/moxygen/standalone/install-system-deps.sh   # system libs (both modes)
+Pins live in [/cmake/dependencies.cmake](/cmake/dependencies.cmake).
 
-./scripts/build.sh setup     # download prebuilt deps (~1 min)
-./scripts/build.sh           # build
-./scripts/build.sh test      # test
-```
+`ccache` is used automatically when it is on `PATH`.
 
-System libraries are needed in **both** dependency modes — the moxygen
-tarball ships folly/fizz/mvfst/proxygen statically, but its CMake config
-still does `find_dependency(fmt, Glog, ...)` and folly itself transitively
-needs OpenSSL/Boost. `build.sh setup`'s system-dep check only fires when
-falling back to source, but the build step needs the libs regardless.
+## Docs
 
-See [BUILD.md](BUILD.md) for full build and test instructions (dependency
-modes, sanitizer profiles, Docker), and [RUNNING.md](RUNNING.md) for relay
-operations.
+- Build [/BUILD.md](/BUILD.md) · Run [/RUNNING.md](/RUNNING.md) · Metrics [/docs/metrics.md](/docs/metrics.md)
+- Design: [/design/](/design)
 
 ## License
 
-Apache 2.0 — see [LICENSE](LICENSE).
+Apache 2.0 — see [/LICENSE](/LICENSE).

docs/ci-architecture.md

@@ -1,7 +1,8 @@
 # CI and Automation
 
-This document describes the CI pipelines, upstream sync, submodule management,
-artifact publishing, and relay deployment across the openmoq organization.
+This document describes the CI pipelines, upstream sync, dependency-revision
+management, artifact publishing, and relay deployment across the openmoq
+organization.
 
 ## Cross-Repo Dependency
 
@@ -12,7 +13,7 @@ artifact publishing, and relay deployment across the openmoq organization.
 │  ci main ──► snapshot-latest release (tarballs, all platforms)
 │                         │                                   │
 └─────────────────────────┼───────────────────────────────────┘
-                          │  submodule SHA pins which tarball
+                          │  MOXYGEN_REV (cmake/dependencies.cmake) pins the rev
                           ▼
 ┌─────────────────────────────────────────────────────────────┐
 │  moqx (application)                                        │
@@ -23,8 +24,25 @@ artifact publishing, and relay deployment across the openmoq organization.
 └─────────────────────────────────────────────────────────────┘
 ```
 
-moqx's `deps/moxygen` submodule pins a moxygen commit. `setup-deps-release.sh`
-downloads the matching pre-built tarball from moxygen's release.
+moqx pins a moxygen commit via `MOXYGEN_REV` in
+[`cmake/dependencies.cmake`](/cmake/dependencies.cmake). At configure time CPM
+fetches that moxygen source and [`cmake/FetchMoxygenPrebuilt.cmake`](/cmake/FetchMoxygenPrebuilt.cmake)
+downloads the matching prebuilt install tarball from moxygen's release.
+
+Build and test lanes run `configure.sh --moxygen prebuilt-with-fallback`, so a pin
+with no published tarball costs a slow from-source lane rather than a red one. The
+modes themselves are in [/BUILD.md](/BUILD.md#how-dependencies-work).
+
+The images do the same, in [`docker/Dockerfile`](/docker/Dockerfile)'s `moxygen`
+stage. That stage copies the pin and the build system but not `src/`, so its layer
+key changes only on a `MOXYGEN_REV` bump, and a registry-backed buildx cache makes
+a source-only push reuse it.
+
+Both image targets, `relay` and `interop-client`, take their moxygen from that one
+stage, so they cannot disagree about which moxygen they carry.
+
+`version release` is the exception and stays strict: a versioned artifact must
+ship a published, digest-verified dependency, not whatever a runner compiled.
 
 ## End-to-End Flow
 
@@ -118,10 +136,13 @@ Promotes `snapshot-latest` artifacts to a versioned `vX.Y.Z` release (no rebuild
 | Job | Runner | Purpose |
 |-----|--------|---------|
 | check-format | ubuntu-latest (trixie) | clang-format-19 check |
-| linux | ubuntu-22.04 | Build + test (from-release tarball) |
-| asan debug | self-hosted (linode) | ASAN/UBSAN build + test |
+| linux | ubuntu-22.04 | Build + test (prebuilt tarball, from-source fallback) |
+| asan (moqx TUs, prebuilt deps) | self-hosted (linode) | ASan/UBSan on moqx TUs, build + test |
 
-Format check must pass before build runs.
+Format check must pass before build runs. The fully-instrumented from-source
+san/tsan stacks build nightly in the `sanitizers` workflow
+([sanitizers.yml](/.github/workflows/sanitizers.yml), also manually
+dispatchable against any branch).
 
 ### 2. `ci main` — Build, Publish, Release, Deploy, Notify
 
@@ -136,12 +157,12 @@ check-format + build ──► publish (Docker) ──► release ──► depl
 - Deploy automatically updates moqx-main.ci.openmoq.org with the new image
 - Notify sends Slack + email with per-job status
 
-### 3. `moxygen sync` — Automated submodule update
+### 3. `moxygen sync` — Automated dependency-revision update
 
 **Trigger:** `repository_dispatch` from moxygen + manual | **Time:** <1 min
 
 - Checks for blocking `sync-moxygen/*` PR (one at a time)
-- Updates `deps/moxygen` submodule to dispatched SHA
+- Bumps `MOXYGEN_REV` in `cmake/dependencies.cmake` to the dispatched SHA
 - Creates PR with dual identity (bot creates, PAT approves)
 - Notifies on block or failure
 
@@ -218,3 +239,11 @@ All build jobs use ccache:
 - **~35-50%** hit rate after upstream sync (many changed files)
 - **~65-80%** on incremental builds (typical PR or small change)
 - Warm cache cuts moxygen build time roughly in half
+
+Build jobs also cache `~/.cache/moqx` (CPM source clones + the prebuilt moxygen
+install, ~680 MB of downloads per configure otherwise), keyed on the dependency
+pins — a pin bump refetches once, every other run configures offline.
+
+The from-source fallback prefix is not cached: it is multiple GB per lane against a
+10 GB LRU budget, and `actions/cache` saves at job end, so the run that triggers the
+fallback would miss anyway. ccache absorbs the repeat cost instead.

docs/perf-tracking.md

@@ -15,7 +15,7 @@ surfaced via:
 - **PR comments** — comparison table, optionally posted to a PR when a run sets
   the `pr` input (otherwise the same report lives in the step summary)
 
-Primary workflow: [`.github/workflows/perf-test.yml`](../.github/workflows/perf-test.yml)
+Primary workflow: [`.github/workflows/perf-test.yml`](/.github/workflows/perf-test.yml)
 
 ## Triggering
 
@@ -169,13 +169,13 @@ The workflow stages a Pages artifact (`perf-out/`) and deploys it with
 
 | File | Purpose |
 |------|---------|
-| `scripts/perf/perf-test-ci.sh` | CI orchestration (deploy, run, collect) |
-| `scripts/perf/perf-results-to-json.sh` | Parse client output → JSON |
-| `scripts/perf/perf-compare.py` | Regression detection + markdown |
-| `scripts/perf/perf-test.sh` | Underlying test runner (unchanged) |
-| `scripts/perf/perf-metrics.sh` | Prometheus metrics poller (unchanged) |
-| `.github/workflows/perf-test.yml` | Standalone perf workflow (run, compare, stage, deploy) |
-| `status/index.html` | Dashboard shell (copied to Pages artifact root) |
+| [`scripts/perf/perf-test-ci.sh`](/scripts/perf/perf-test-ci.sh) | CI orchestration (deploy, run, collect) |
+| [`scripts/perf/perf-results-to-json.sh`](/scripts/perf/perf-results-to-json.sh) | Parse client output → JSON |
+| [`scripts/perf/perf-compare.py`](/scripts/perf/perf-compare.py) | Regression detection + markdown |
+| [`scripts/perf/perf-test.sh`](/scripts/perf/perf-test.sh) | Underlying test runner |
+| [`scripts/perf/perf-metrics.sh`](/scripts/perf/perf-metrics.sh) | Prometheus metrics poller |
+| [`.github/workflows/perf-test.yml`](/.github/workflows/perf-test.yml) | Standalone perf workflow (run, compare, stage, deploy) |
+| [`status/index.html`](/status/index.html) | Dashboard shell (copied to Pages artifact root) |
 | `perf-out/perf/index.json` | Generated run manifest in Pages artifact |
 | `perf-out/perf/run-*.json` | Generated per-run result files |