Build instructions: BUILDING.md + make sync-so

Full build/test/run/rebuild instructions, verified by running each command. Adds a make sync-so target that builds the shared library AND copies it to the repo-root build/ dir the ctypes bridge actually loads -- the stale-library trap that broke from_pretrained is now impossible to miss.

.gitattributes

@@ -1,7 +1,2 @@
 *.bin filter=lfs diff=lfs merge=lfs -text
 model/*/substrate.bin filter=lfs diff=lfs merge=lfs -text
-build/libsyfox_core.so filter=lfs diff=lfs merge=lfs -text
-engine/build/libsyfox_core.so filter=lfs diff=lfs merge=lfs -text
-engine/build/rebuild_sem filter=lfs diff=lfs merge=lfs -text
-engine/build/syfox filter=lfs diff=lfs merge=lfs -text
-engine/build/syfox-test filter=lfs diff=lfs merge=lfs -text

BUILDING.md

@@ -0,0 +1,193 @@
+# Building SyFox
+
+The decision engine is **C++17 with no runtime dependencies** beyond a C++
+compiler. There is no neural network, no transformer, and no Python needed for
+inference from the CLI.
+
+```
+engine/    the C++ SI-substrate core (core/*.hpp + src/*.cpp) + its Makefile
+server/    optional HTTP bridge (FastAPI) and the ctypes bridge
+inference.py  thin python wrapper over the bridge
+model/     the fabrics (prebuilt substrates, no training required to use them)
+```
+
+---
+
+## 1. Build the core
+
+```bash
+cd engine
+make all        # -> build/syfox, build/syfox-test, build/libsyfox_core.so,
+                #    build/rebuild_sem
+```
+
+Requires `g++` (C++17) and `make`. On Debian/Ubuntu:
+
+```bash
+sudo apt-get install build-essential
+```
+
+There is **no top-level `Makefile`** — the `cd engine` is required, not optional.
+
+## 2. Run the tests
+
+```bash
+cd engine
+make test              # builds and runs build/syfox-test
+./build/syfox-test     # expected: "all tests passed"
+```
+
+## 3. Build the Python bridge library — **read this**
+
+```bash
+cd engine
+make sync-so           # builds the .so AND copies it to ../build/
+```
+
+`server/syfox_bridge.py` loads the shared library with `ctypes` from the
+**repo-root** `build/` directory:
+
+```python
+_LIB = ... / "build" / "libsyfox_core.so"     # NOT engine/build/
+```
+
+So if you only run `make all`, the CLI and the test suite pass while
+`from inference import SyFox` fails with:
+
+```
+AttributeError: ... undefined symbol: syfox_engine_set_semantics
+```
+
+That happens because the bridge keeps loading an **older** `build/` copy that
+happens to be present. A prebuilt `build/libsyfox_core.so` ships in this repo,
+so it will look like everything works — right up until it silently uses the
+stale core. `make sync-so` exists so this cannot be forgotten.
+
+For a clean environment, delete it first so the failure is loud:
+
+```bash
+rm -f build/libsyfox_core.so && cd engine && make sync-so
+```
+
+## 4. Optional: OpenMP build
+
+Parallel settle, deterministic by construction (fixed reduction order) and
+bit-identical to the sequential build:
+
+```bash
+cd engine && make build/syfox-omp
+```
+
+## 5. Run it
+
+**CLI** — no Python needed:
+
+```bash
+./engine/build/syfox stats --model model/sst2
+
+./engine/build/syfox decide --model model/sst2 \
+  --state "a hollow, inert picture that never risks anything" \
+  --questions '{"q":{"type":"choice","instructions":"sentiment",
+    "criteria":{"negative":"negative","positive":"positive"}}}'
+```
+
+Every response carries `choice`, `confidence`, `deferred`, `probabilities`, and
+a `reason` when it abstains. **`deferred: true` is the engine declining to
+answer, not an error** — see [Abstention](#abstention-is-a-feature).
+
+**Python**:
+
+```bash
+pip install fastapi uvicorn      # only needed for the HTTP server
+python -c "
+from inference import SyFox
+m = SyFox()
+r = m.decide('I was charged twice on my last invoice, please refund.')
+print(r['answers']['domain'])"
+```
+
+**HTTP server** (the HuggingFace Spaces entrypoint):
+
+```bash
+python server/app.py --model model/giant --lang auto --energy-norm \
+                     --host 0.0.0.0 --port 7860
+```
+
+## 6. Docker / Spaces
+
+The `Dockerfile` builds the core in a throwaway stage and copies only the
+stripped `.so` into a slim runtime image — it handles the `sync-so` step for
+you. It serves on port **7860**, which Spaces expects.
+
+```bash
+docker build -t syfox .
+docker run -p 7860:7860 syfox
+```
+
+## 7. Retraining a fabric
+
+Not needed to *use* the models. To train your own:
+
+```bash
+./engine/build/syfox learn     --model my-model --examples train.jsonl \
+                               --energy-norm --ngrams on
+./engine/build/syfox calibrate --model my-model --examples cal.jsonl \
+                               --energy-norm --ngrams on
+```
+
+Always calibrate on a split the model never trained on, and score **once** on a
+held-out split. Fabric size grows with lesson count: ~4,200 rows → ~78k nodes /
+~949k lanes / ~23 MB.
+
+### Admission gate
+
+A model should be checked on handcrafted novel questions before publishing,
+because held-out accuracy shares its generator with training and rewards
+memorising n-grams:
+
+```bash
+python tools/novel_gate.py --sweep path/to/candidate/dir
+```
+
+Probes live in `datasets/novel_probes/`. A model is admitted only if it clears
+both the majority baseline and uniform chance + 0.15, with no single class
+answering more than 60% of probes.
+
+---
+
+## Platform support
+
+**The prebuilt `build/libsyfox_core.so` is linux-x86_64.** On macOS or ARM
+(Apple Silicon, ARM servers) it will not load — rebuild instead:
+
+```bash
+cd engine && make clean && make sync-so
+```
+
+That produces a library for *your* machine. Do not ship it to users on other
+platforms; the repository copy is a convenience for linux-x86_64 only.
+
+## Troubleshooting
+
+| symptom | cause | fix |
+|---|---|---|
+| `undefined symbol: syfox_engine_set_*` on import | bridge loaded a stale `.so` | `cd engine && make sync-so` |
+| `command not found: make` | no toolchain | `apt-get install build-essential` |
+| `make: *** No rule to make target` | wrong directory | you are in the repo root, not `engine/` |
+| CLI and tests pass but Python fails | see row 1 | stale `.so` |
+| every answer has `deferred: true` | honesty gate firing, working as designed | inspect `reason` in the response |
+
+## Abstention is a feature
+
+SyFox returns `deferred: true` with a `reason` rather than guessing. Reported
+accuracy is always meaningless without the paired defer rate — the honest
+metric is `accuracy × answered/total`. See
+[docs/HONEST_TOTAL.md](../docs/HONEST_TOTAL.md) in the upstream project for the
+protocol, and `docs/ENGINE_PORT.md` for what changed in the v3.9.1 port.
+
+## Related
+
+- [`docs/ENGINE_PORT.md`](ENGINE_PORT.md) — the v3.2.0 → v3.9.1 port, ABI
+  verification, and the stale-numbers caveat
+- [`docs/EVALUATION.md`](EVALUATION.md) — measured evaluation
+- [`docs/ZEROSHOT.md`](ZEROSHOT.md) — zero-shot and coverage probes

README.md

@@ -154,6 +154,18 @@ examples/    JSON payloads + curl + python usage
 Dockerfile   HuggingFace Spaces (builds engine, serves on 7860)
 ```
 
+## Build
+
+```bash
+cd engine && make all && make sync-so && cd ..
+```
+
+`make sync-so` is **required** for the Python bridge: it loads
+`build/libsyfox_core.so` from the **repo root**, not `engine/build/`, so a
+plain `make all` leaves a stale library in place and `from inference import
+SyFox` fails with `undefined symbol`. Full instructions, Docker, retraining
+and troubleshooting: **[BUILDING.md](BUILDING.md)**.
+
 ## Usage (python)
 
 ```python

engine/Makefile

@@ -5,6 +5,19 @@ BUILD := build
 
 all: build/syfox build/syfox-test build/libsyfox_core.so build/rebuild_sem
 
+# Copy the shared library to the REPO-ROOT build/ dir, which is where
+# server/syfox_bridge.py looks for it (ctypes: ../build/libsyfox_core.so).
+# Skipping this is the single most common setup failure: the CLI and the tests
+# pass, then `from inference import SyFox` dies with
+#   undefined symbol: syfox_engine_set_*
+# because the bridge silently keeps loading a stale core.
+sync-so: build/libsyfox_core.so
+	mkdir -p ../build
+	cp $< ../build/libsyfox_core.so
+	@echo "synced -> ../build/libsyfox_core.so"
+
+.PHONY: sync-so
+
 build:
 	mkdir -p build