Name the Git LFS problem instead of failing inside gzip (the macOS default)

macOS git ships without git-lfs, so a plain clone leaves 132-byte pointer files where docker/bundle/runtime_source.tar.gz, the GGUF and model.safetensors should be. Reproduced: extracting the pointer fails with 'gzip: stdin: not in gzip format', which says nothing about LFS.

docker/start.sh checks both LFS-tracked bundle files before unpacking and stops with the fix spelled out (brew/apt install git-lfs, git lfs install, git lfs pull - or use hf download). docker-train's Dockerfile checks that the ADD actually unpacked the archive, because docker copies a pointer verbatim instead of failing. make_base.py checks model.safetensors the same way.

Docs: both cards and all four container READMEs now say how to get real files (hf download, or git-lfs before cloning). The Korean docker-train README still described the old research-repo flow of unpacking a separately supplied base package; it now uses make_base.py like the English one. The Korean docker README pointed at a research-repo path; it now says docker/.

Verified before publishing: the pointer case prints the message and exits 1 in all three places; with real files docker/ reaches ready and classifies, and docker-train runs make_base -> build -> validate -> train -> export (parity 0.0 / 0.0, 0 disagreements) -> serve. Also checked: no case-insensitive path collisions in the repo or inside the archives, and apple-silicon builds are not blocked by x86 flags (docker/ builds llama.cpp with every x86 extension off).

README.md

@@ -102,6 +102,18 @@ those are visible in the panels above.
 Two stacks, both CPU-only, both with the dedicated no-KV runtime compiled inside the image and
 nothing fetched at run time.
 
+**Getting the files.** The weights and the two runtime archives are stored with Git LFS. A
+`git clone` made without git-lfs — the macOS default — leaves ~130-byte pointer files in their
+place, and both containers stop and say so. Either fetch with the Hub CLI, which needs no git-lfs:
+
+```bash
+hf download mp-juuuns/qwen3.5-4l-vocab40k-en-ko-headless --local-dir qwen3.5-4l
+```
+
+or install git-lfs first (macOS `brew install git-lfs`, Debian/Ubuntu `apt install git-lfs`; Git for
+Windows already includes it), run `git lfs install`, and clone. An existing clone is repaired in
+place with `git lfs pull`.
+
 **[`docker/`](docker/) — see it work now.**
 
 ```bash

README_KO.md

@@ -78,6 +78,18 @@ Qwen3.5-0.8B에서 증류한 **헤드 없는 4계층 텍스트 백본**이며,
 두 개의 스택이며, 둘 다 CPU 전용이고, 둘 다 전용 no-KV 런타임을 이미지 안에서 컴파일하며 실행
 시점에 가져오는 것은 아무것도 없습니다.
 
+**파일 받기.** 가중치와 런타임 압축 파일 두 개는 Git LFS로 저장되어 있습니다. git-lfs 없이
+`git clone`을 하면(맥의 기본 상태가 이렇습니다) 그 자리에 130바이트 정도의 포인터 파일만 받아지고,
+두 컨테이너 모두 그 사실을 알리며 멈춥니다. git-lfs가 필요 없는 Hub CLI로 받으시거나:
+
+```bash
+hf download mp-juuuns/qwen3.5-4l-vocab40k-en-ko-headless --local-dir qwen3.5-4l
+```
+
+git-lfs를 먼저 설치하신 뒤(맥 `brew install git-lfs`, Debian/Ubuntu `apt install git-lfs`, Git for
+Windows에는 이미 들어 있습니다) `git lfs install`을 실행하고 클론하시면 됩니다. 이미 받은 사본은 그
+자리에서 `git lfs pull`로 고칠 수 있습니다.
+
 **[`docker/`](docker/) — 지금 바로 돌아가는 것을 보기.**
 
 ```bash

SHA256SUMS

@@ -1,6 +1,6 @@
 77fd4710def9ec3c0f6225800e0235f15a425abd4a8b03559127fcd782612049  LICENSE
-c3918d4b2392d78da6ce775f5776162079eaa15a97f8eb5eb97758addbabc144  README.md
-40b06feb534ec50c43777b838d378feb6755a47e07ce8b63e93cb22961896aea  README_KO.md
+b901b5be1af24ece943d174566a9c22e55019eef403081f9fc21672100456f50  README.md
+9d99d92cf91bcffa39d794ee8f15b7517695f8f2f67311ae081010e37c153dee  README_KO.md
 bf4073de38c3905effd2dcce6f38894f325c8a0a79bedfb2779f0545c86b9c9f  benchmark/BENCHMARK_CARD.md
 e01bd7ac59a3212e44b77e5fcfbc7c41ec91d74c998306d2438209d6ef1a3aa7  benchmark/arm_summary.csv
 2c544c3907c4f592d724f658850b8c6b9634845cb5b50a66ebd2ea6c5d48ce0b  benchmark/compression_ladder.csv
@@ -83,9 +83,9 @@ d9b135cf5b0adf4bbfc321200395fbd6112e49fd1a027b30262bcff1c4c0b654  distillation/q
 00731ae7838317105f9fff960e3da210b2a55954feb37b3ac793bcfc81fdab2d  distillation/qwen35_distill/schema.py
 4b341db0a133c1398d0bde0fb881991dacaffd8158f6f593aea30fb6486655df  distillation/qwen35_distill/training.py
 42d6a7ff85248c4fadbc022c02dc17909b6484dcea34a20c803e00598bac6063  docker-train/.dockerignore
-b26681c81ad020cd1e85f4a9faed7b8bae37dbcad7b20d1d05ea16284fd5dd0d  docker-train/Dockerfile
-419c3caa21b00da1c2b5cf4a76862e29bbf4559e4c64eafc1ec8f60b83a34991  docker-train/README.md
-e9a07d289b8fc3ac593412faa8a4309e2eadcbe148e22a92f8928a065c18cc42  docker-train/README_KO.md
+0e5ee1f54ef418f71307e60374eae14c1897dd515b123d31b7b45b92bde7827c  docker-train/Dockerfile
+08386d1429b06c3e1c2c2de7d5e0effcae646709d4666073a9721573b7306e9e  docker-train/README.md
+016c7a595525d66be1c016925d5571c32a0104a5c4417627747bf9dedd1403d5  docker-train/README_KO.md
 28c72ebaee31a0cb90175a45d07701951905391131698d227b8c5b959eeb536e  docker-train/VALIDATION_KO.md
 b57039329c8966937707622acab52e791d08777899e901d2248ca95b6e4087b7  docker-train/compose.arm64.yaml
 46328308ba5b45d4fe059b864b918dc7725fdb98c753ef916778f766269ce284  docker-train/compose.yaml
@@ -111,7 +111,7 @@ d67ede61740a3af009c500d7ebf28ee48a14cecff22bd281dd94604a0d184508  docker-train/e
 56cf9f6386e5b9a034d34ee679532d5cc0f686ad0dc913704efdf8264debe91d  docker-train/examples/data/spans-calibration.jsonl
 e6086d3cd9dcbb5e5a7b3acf0c2a20349cd7bf911963e24bee559c8b99477803  docker-train/examples/data/spans-train.jsonl
 f385666b81fe757fb448aadfcd147d80c0ba4f169b9b3d85fe31aa299a7e75be  docker-train/examples/data/train.jsonl
-1ed8e0fb322cea3c1f9ed34003e36166a48b98fa8cd8da4f2d97ede2bd772798  docker-train/make_base.py
+af56c89efa4cda482b40d3b5f6a8e6c11a259346fccf81a1da9d3ad18c4c5fee  docker-train/make_base.py
 666d8b7896a6e347b230314a596b253746c11b180a8903f7abeb09d25634bea5  docker-train/native/gdn_fused.inc
 3c34c2b5e1bf34e0520823524b961c5b30a837a987f2d1e3be6f4bbc51d8a1a5  docker-train/native/patch_runtime.py
 443e8be62adeb7cbafecab8aca13a60e110a7f35c045e2de19fb464e19d847c8  docker-train/native/q8_kernel.inc
@@ -278,8 +278,8 @@ da920e2c62166ec9f30e407e9fb35ec29fda671310ffbf0f8ce856b62f1c70d7  docker-train/v
 7fdb374e511dfe1c0da5b870af83e22bb55c141df4c49f1417cc3b5ca53669f9  docker-train/vendor/runtime_source.tar.gz
 d39d33e360727537d02a2c1cec3ef17de494376477b0edd3013fa7f138d28db1  docker/.dockerignore
 87b1e2dc98c711c6762cd4e9f40d9fc0228ae2b8f6bd8f301334f6830d0f8d88  docker/Dockerfile
-c6e17c6beadaf83d764f4982c4df81a7f83a7ab00c208531c33596c6264718a2  docker/README.md
-016b40c98a2b4a8bd874b8c2b248551c353627c45a3a3da4cabfea71f7bb098e  docker/README_KO.md
+d0938d7b42be376496bc2235b77fb16a8503ae88b4e6db9fd98b9aff7a4aeb30  docker/README.md
+19005d0331a7a0a2aac0008a16f9300d16ca77d0b188c5e8facca56a46eeea05  docker/README_KO.md
 1bb65784297e7f7319099736eb8d2041899c1af5b3731375d6f578ef0f7e92b1  docker/app.js
 3c162659936a2ccc542008e315c0fb5e5778e10808c01bf41e8cbdae7d119b2d  docker/benchmark_reference.json
 e7ab07e36f17d097fd9832d78f25da608eaee69a66b32f80658bd44cfb711da0  docker/bundle/manifest.json
@@ -293,7 +293,7 @@ e54868871ce4c9fe32e4dab10fb1e1abba4bf7c7c61c4925a351e31ad5cd83b9  docker/compose
 f65fac7bd6f881d2ecb0db058db44dbf039b62003171c257bf68a6dd09e70ba7  docker/prepare_bundle.py
 c9411e19fe92451c525d7094b7633a1759b6fdd3ef8c06c2516cbc22392463ad  docker/requirements.lock
 b41d4b7556d3a11f9e2e6c3d0177bbd5dbf0a7afb553087a6dbcb843ca940a82  docker/server.py
-5ed83b7d55bde8ca485e0093bbc22aa975fe6e247efe9593ed8989eb269544f6  docker/start.sh
+e0ed7ce704883241b33d6646d18d892208691dd17da1f83032e47512284dd4f7  docker/start.sh
 295a9fff3000e8f719dfb528f2ca12e2ab1ac3fbc3265a74a999733ddd782f97  docker/telemetry.py
 a78242281be9d6fe52e381db81eeeafddf8c0c34d1b9a36671ae6ebf0037dbcb  docker/test_server.py
 1b6e475b9d7d9af52bb8845de020303b1c6e89646d8e4f9be17dbe4ab2910417  docs/RELEASE_CONTRACT.md

docker-train/Dockerfile

@@ -5,6 +5,7 @@ WORKDIR /src
 COPY vendor/manifest.json vendor/manifest.json
 # docker unpacks a local tarball on ADD, so the bundled runtime source needs no manual step.
 ADD vendor/runtime_source.tar.gz vendor/
+RUN test -f vendor/runtime_source/CMakeLists.txt || { echo 'vendor/runtime_source.tar.gz did not unpack: it is a Git LFS pointer, not the archive. Install git-lfs, run git lfs install and git lfs pull, then build again - or fetch the files with hf download.' >&2; exit 1; }
 COPY vendor/native_live_classifier.cpp vendor/native_live_classifier.cpp
 COPY native native
 COPY tools/build_native.py tools/build_native.py

docker-train/README.md

@@ -10,6 +10,10 @@ the dependencies and the native binaries. The training, validation and export co
 
 ## Run it
 
+The root weights are stored with Git LFS, so fetch with `hf download` or clone with git-lfs installed
+(macOS: `brew install git-lfs`, then `git lfs install`). `make_base.py` and the image build both stop
+with a clear message if they find a pointer file instead of the real one.
+
 ```bash
 python make_base.py                      # assembles base/ from this repository's own weights
 mkdir -p outputs

docker-train/README_KO.md

@@ -8,10 +8,14 @@
 
 ## 준비와 실행
 
-검증된 **별도 베이스 패키지**를 `base/`에 풀고, `outputs/` 폴더를 만든다.
+`python make_base.py`로 이 저장소 루트의 가중치에서 `base/`를 조립하고, `outputs/` 폴더를 만든다.
+루트 가중치는 Git LFS로 저장되어 있으므로 `hf download`로 받거나 git-lfs를 설치한 상태에서 클론한다
+(맥: `brew install git-lfs` 후 `git lfs install`). 실제 파일 대신 포인터 파일이 있으면 `make_base.py`와
+이미지 빌드가 그렇다고 알리며 멈춘다.
 `config/train.yaml`의 라벨·학습/보정 파일·실행 이름을 수정한다. 예제 데이터는 직접 만든 기능 확인용 문장으로, 모델 품질 평가용이 아니다.
 
 ```bash
+python make_base.py
 mkdir -p outputs
 export LOCAL_UID="$(id -u)" LOCAL_GID="$(id -g)"   # Linux/macOS only
 # 윈도우 PowerShell에서는 위 export 줄을 건너뛴다. Docker Desktop에서는 기본값(1000)으로 동작한다.

docker-train/make_base.py

@@ -33,6 +33,14 @@ def main():
     if missing:
         raise FileNotFoundError("run this from docker-train/ inside a full clone; missing: " + ", ".join(missing))
 
+    pointers = [f for f in ("model.safetensors",)
+                if (ROOT / f).read_bytes()[:23] == b"version https://git-lfs"]
+    if pointers:
+        raise SystemExit(
+            f"{', '.join(pointers)} is a Git LFS pointer, not the real file. Install git-lfs "
+            "(macOS: brew install git-lfs), run 'git lfs install' and 'git lfs pull' in the "
+            "repository, then run this again - or fetch the files with 'hf download'.")
+
     DEST.mkdir()
     for rel in PLAIN + PROVENANCE:
         target = DEST / rel

docker/README.md

@@ -6,6 +6,10 @@ time; the weights and the runtime source are in `bundle/`.
 
 Korean version of this page: [`README_KO.md`](README_KO.md).
 
+You need the real files, not Git LFS pointers: fetch with `hf download`, or clone with git-lfs
+installed (macOS: `brew install git-lfs`, then `git lfs install`). A clone made without it is fixed
+in place with `git lfs pull`; the container tells you when this is the problem.
+
 ```bash
 docker compose up --build
 ```

docker/README_KO.md

@@ -7,6 +7,10 @@
 
 ## 빠른 실행
 
+Git LFS 포인터가 아닌 실제 파일이 필요하다. `hf download`로 받거나, git-lfs를 설치한 상태에서
+클론한다(맥: `brew install git-lfs` 후 `git lfs install`). git-lfs 없이 클론했다면 그 자리에서
+`git lfs pull`로 고쳐진다. 이 문제일 때는 컨테이너가 그렇다고 알려준다.
+
 ```bash
 docker compose up --build
 ```
@@ -78,7 +82,7 @@ curl http://127.0.0.1:8787/classify \
 
 ## 다른 PC로 이동
 
-`deployment/qwen35-vocab40k/` 폴더를 `bundle/` 포함해 통째로 옮기고
+이 `docker/` 폴더를 `bundle/` 포함해 통째로 옮기고
 `docker compose up --build`를 실행하면 된다. 원래 프로젝트의 절대경로는 필요 없다.
 bundle에는 코드·모델·토크나이저가 있고 학습/보정/test 데이터셋은 없다.
 `bundle/manifest.json`은 파일 무결성 자료이지 승인 기록이 아니다.

docker/start.sh

@@ -24,6 +24,17 @@ fi
 # Unpack it in place before the manifest is verified, so no manual step stands between a fresh
 # clone and a working container. Already-unpacked bundles are left alone.
 bundle="${MODEL_BUNDLE:-$PWD/bundle}"
+# A clone made without git-lfs (the macOS default) leaves ~130-byte pointer files where the
+# archive and the weights should be. Say that plainly instead of failing inside gzip.
+for lfs_file in "$bundle/runtime_source.tar.gz" "$bundle/model/classifier-q8_0.gguf"; do
+  if [[ -f "$lfs_file" && "$(head -c 23 "$lfs_file" | tr -d '\000')" == "version https://git-lfs" ]]; then
+    echo "ERROR: ${lfs_file#"$bundle"/} is a Git LFS pointer, not the real file." >&2
+    echo "Install git-lfs (macOS: brew install git-lfs, Debian/Ubuntu: apt install git-lfs)," >&2
+    echo "run 'git lfs install' and then 'git lfs pull' in the repository, and start again." >&2
+    echo "Or fetch the files with 'hf download', which does not need git-lfs." >&2
+    exit 1
+  fi
+done
 if [[ ! -f "$bundle/runtime_source/CMakeLists.txt" && -f "$bundle/runtime_source.tar.gz" ]]; then
   echo 'Unpacking the bundled runtime source...'
   tar -xzf "$bundle/runtime_source.tar.gz" -C "$bundle"