Rewrite the card in the house style with durable facts only

README.md

@@ -1,161 +1,46 @@
+---
+license: apache-2.0
+---
 # motion-bricks.cpp
 
-A C++23/GGML port of NVIDIA MotionBricks for CPU and Vulkan inference, with a
-stable C ABI suitable for PureGo.
+A C++23/GGML port of NVIDIA MotionBricks for CPU and Vulkan inference, with a stable C ABI for PureGo.
 
-The released batch-one G1 inference path is implemented end to end: strict
-GGUF loading, root/duration planning, pose-token prediction, VQ decoding,
-418/414/413 feature conversion, style alignment, and skeletal animation
-output. CPU and Vulkan use the same public API and preserve the same duration
-and pose-token decisions in the reference suite.
+## What it is for
 
-## Build
+The repo holds the C++ source, a C header and C++ wrapper, a PureGo binding, a Go/Three.js demo, conversion scripts and parity tests.
+It implements the batch-one G1 inference path end to end: strict GGUF loading, root and duration planning, pose-token prediction, VQ decoding, feature conversion, style alignment and skeletal animation output.
+CPU and Vulkan use the same public API and make the same duration and pose-token decisions in the reference suite.
+The C API uses only fixed-width scalars, pointers and opaque heap handles. No C++ exception crosses the ABI boundary.
+At runtime a caller loads one model and one or more `.mbstyle` assets, creates an agent, sets movement, facing and style, then calls `mb_agent_plan` and `mb_agent_advance`.
+The bundle loader checks the upstream revision, checkpoint identities, tensor and parameter counts and the joint topology before it accepts a model.
 
-The normal build uses CMake and does not depend on Nix:
+## Provenance
 
-```sh
-cmake --preset debug
-cmake --build --preset debug
-ctest --preset debug
-```
+- Upstream source: NVIDIA MotionBricks in [NVlabs/GR00T-WholeBodyControl](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/a0732b642c0333077e127a2f56ab0014c196bca4/motionbricks), at revision `a0732b642c0333077e127a2f56ab0014c196bca4`.
+- Converted weights and style primitives: [LocalAI-io/MotionBricks-G1-GGML](https://huggingface.co/LocalAI-io/MotionBricks-G1-GGML). The default build pins Hugging Face commit `cc2a47603dbc203a4f18f35dd06ed3611833f506`.
+- Fork notes are in `FORK_PROVENANCE.md`. The pinned upstream reference is in `reference/README.md`.
 
-Configuration downloads and SHA-256-verifies the published 0.73 GB G1 F32
-GGUF and style bundles into `generated/` when they are not already present.
-The same operation can be run explicitly:
+## Build and run
 
 ```sh
-python scripts/download_gguf_weights.py
-```
-
-For an offline or source-only build, preserve an existing local bundle or use
-`cmake --preset debug -DMOTIONBRICKS_DOWNLOAD_MODELS=OFF`. The repository and
-revision are configurable with `MOTIONBRICKS_MODEL_REPOSITORY` and
-`MOTIONBRICKS_MODEL_REVISION`.
-
-On NixOS, enter the reproducible development shell first:
-
-```sh
-nix develop
 cmake --preset debug
 cmake --build --preset debug
 ctest --preset debug
+./build/debug/bin/motionbricks-cli abi
 ```
 
-When the pinned `ggml/` submodule is present, it is included automatically.
-The non-neural ABI and validation subset can also be built without GGML:
-
-```sh
-cmake -S . -B build/debug -G Ninja -DMOTIONBRICKS_ENABLE_GGML=OFF
-```
-
-The Go binding and demo use PureGo to load `libmotionbricks` at runtime; they
-do not use cgo or `import "C"`. Once the native shared library has been built,
-the Go components therefore need no C compiler and can be built with cgo
-explicitly disabled:
+Configuration downloads and SHA-256-verifies the G1 F32 GGUF and style bundles into `generated/`. Use `-DMOTIONBRICKS_DOWNLOAD_MODELS=OFF` for an offline build. On NixOS, run `nix develop` first.
+The Go binding and demo load `libmotionbricks` at runtime with PureGo, so they build with `CGO_ENABLED=0`:
 
 ```sh
 cd demo
 CGO_ENABLED=0 go build -o ../build/debug/bin/motionbricks-demo .
 ```
 
-`CGO_ENABLED=0` is optional but recommended for making this property explicit
-in builds and CI. It affects only the Go build—the native C++ library is still
-built separately with CMake.
-
-The sanitizer lane is:
-
-```sh
-cmake --preset asan-ubsan
-cmake --build --preset asan-ubsan
-ctest --preset asan-ubsan
-```
-
-## Current ABI
-
-The installed C API uses only fixed-width scalars, pointers, and opaque heap
-handles. Callers never reproduce a C or C++ structure layout. All constructors
-have matching free functions, and no C++ exception crosses the ABI boundary.
-
-The current CLI can report ABI information:
-
-```sh
-./build/debug/bin/motionbricks-cli abi
-```
-
-After producing the trusted safetensors intermediates described in
-`reference/README.md`, build and inspect an F32 runtime bundle with:
-
-```sh
-python scripts/convert_to_gguf.py \
-  --safe-directory generated/safe \
-  --output generated/g1-f32
-./build/debug/bin/motionbricks-cli inspect generated/g1-f32
-```
-
-The released G1 inference path contains exactly **183,148,382 learned F32
-parameters**. The bundle loader validates the upstream revision, source
-checkpoint identities, component roles, tensor counts, parameter counts,
-anchor shapes, and the 34-joint parent topology before accepting a model.
-
-Convert the 15 original demo styles with:
-
-```sh
-python scripts/convert_styles.py \
-  --safe-directory generated/safe \
-  --output generated/styles
-```
-
-At runtime the high-level flow is: load one immutable model, load one or more
-`.mbstyle` assets, create an agent, reset it from an initial style (or supply
-at least four frames of G1 context), set movement/facing/style on a command,
-then call `mb_agent_plan`. The returned motion owns row-major F32 root
-translations `[frames,3]` and local XYZW rotations `[frames,34,4]`. Call
-`mb_agent_advance` as playback progresses so replanning uses the generated
-motion as its next context.
-
-The current implementation covers original preprocessed G1 styles. Direct
-Kimodo GLB-to-`.mbstyle` conversion remains subsequent integration work.
-
-## Weights
-
-Ready-to-run native weights and all 15 upstream style primitives are published
-as [MotionBricks-G1-GGML](https://huggingface.co/LocalAI-io/MotionBricks-G1-GGML)
-under the Hugging Face `LocalAI-io` organisation. NVIDIA currently distributes
-MotionBricks checkpoints through Git LFS in
-[`NVlabs/GR00T-WholeBodyControl`](https://github.com/NVlabs/GR00T-WholeBodyControl/tree/a0732b642c0333077e127a2f56ab0014c196bca4/motionbricks),
-not a separate Hugging Face model repository, so the model card links to that
-pinned upstream revision. The downloader verifies the version-controlled
-distribution manifest before accepting any file.
-
-The default build is pinned to Hugging Face commit
-`cc2a47603dbc203a4f18f35dd06ed3611833f506` rather than the mutable `main`
-branch.
-
-## Interactive demo
-
-The initial Go/Three.js demo renders the model's 34-joint skeleton alongside
-the four actual placed target-keyframe ghosts. It lets you steer with W/A/S/D,
-turn facing with the arrow keys, orbit/zoom the camera, and switch among the
-converted upstream styles. It uses the reusable PureGo binding and the same
-stateful native agent as other applications. See the
-[demo guide](docs/DEMO.md) for build, run, architecture, and headless-Chromium
-test instructions.
-
-## Design
-
-- [Human-led design](docs/motions-bricks.md)
-- [Implementation sketch and plan](docs/IMPLEMENTATION.md)
-- [Versioned formats](docs/FORMATS.md)
-- [Go/Three.js demo](docs/DEMO.md)
-- [Pinned upstream reference](reference/README.md)
+See `docs/DEMO.md` for the demo, `docs/FORMATS.md` for the file formats and `docs/IMPLEMENTATION.md` for the design.
 
-## License
+## Licence
 
-motion-bricks.cpp source code is licensed under the
-[Apache License 2.0](LICENSE). NVIDIA's original model weights and converted
-GGUF/style distributions remain under the NVIDIA Open Model License reproduced
-with the published model. It permits derivative models and redistribution with
-conditions including retention of the agreement and attribution, Trustworthy
-AI terms, and trade compliance. Bundled third-party components retain their own
-licenses; the vendored Three.js files are covered by
-`demo/web/vendor/THREE-LICENSE.txt`.
+The source code is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) (`LICENSE`).
+NVIDIA's model weights and the converted GGUF and style distributions stay under the NVIDIA Open Model License, reproduced with [LocalAI-io/MotionBricks-G1-GGML](https://huggingface.co/LocalAI-io/MotionBricks-G1-GGML) and in `scripts/hf/MotionBricks-G1-GGML/UPSTREAM_LICENSE`.
+Bundled third-party parts keep their own licences. The vendored Three.js files are covered by `demo/web/vendor/THREE-LICENSE.txt`.