docs/storage.md

Git and Xet storage

The Hugging Face remote is git@hf.co:nmarshall/wormz-a (hf). The main branch contains the OpenWA master history with test payloads converted to Git LFS pointers. Original authorship and commit messages are preserved, but migration changes commit IDs. The original upstream history remains on local master and origin/*; publish main to hf, not those original refs.

Source, scripts, manifests and documentation remain ordinary Git text. Test replays, expected logs, snapshots, scheme fixtures, images and other assets use Git LFS backed by Xet, including small textual test payloads. .gitattributes declares this policy; scripts/storage_policy.py enforces it. No original game installation or proprietary game assets are added by this setup.

Set up a checkout

Install Git, Python 3, Git LFS and Git Xet (the local Nix environment already provides Git LFS and Git Xet), then run from the repository root:

python3 scripts/setup-repository.py
git lfs pull hf
python3 scripts/storage_policy.py check --require-setup

For a fresh clone, use:

git clone -o hf git@hf.co:nmarshall/wormz-a
cd wormz-a
python3 scripts/setup-repository.py

Setup is idempotent. It registers the required openwa-code clean filter, Git LFS, the Xet custom transfer agent and .githooks. It refuses to replace an existing local hooks path. The clean filter passes code through unchanged and rejects misplaced payloads, non-UTF-8/binary content and code over 2 MiB. Asset directory rules route even small text payloads through LFS. Documentation and .gitignore files in testdata/ are explicit ordinary-Git exceptions.

Commit and push normally:

git add <paths>
git commit -m "area: short description"
git push hf main

The pre-commit hook validates staged Git blobs and attributes. The pre-push hook validates newly reachable history and then runs git lfs pre-push; Git LFS uses its registered Xet transfer agent when negotiated with Hugging Face. Files remain fully materialized in the working tree, while Git stores only asset pointers. Do not bypass the hooks. If adding a new payload format or directory, update both .gitattributes and the classifier in scripts/storage_policy.py.

Adding attributes affects future staging, not existing history. Do not merge the unmigrated upstream refs into main: that would reintroduce raw historical payloads. Future upstream synchronization needs the corresponding LFS conversion before integration. Do not rewrite published history or force-push implicitly.