docs: add Hugging Face LFS push guidance

AGENTS.md

@@ -14,3 +14,12 @@
 - `uv add <package>` — add a dependency
 - `uv sync` — install all dependencies from lockfile
 - `uv run pytest` — run tests
+
+## Hugging Face Deployment
+
+- `.stl` files must be tracked by Git LFS (`*.stl filter=lfs` in `.gitattributes`)
+- Verify Git LFS is available before push: `git lfs version`
+- Confirm tracked LFS files: `git lfs ls-files`
+- Standard push sequence: `git push origin main` then `git push hf-space main`
+- If Hugging Face rejects binaries, re-check `.gitattributes` and LFS status before retrying
+- `git lfs migrate` rewrites history; only use it intentionally and coordinate with collaborators first

README.md

@@ -10,7 +10,7 @@ short_description: Upload an STL and export a TIFF slice.
 
 # STL to TIFF Gradio App
 
-This project provides a Gradio app that takes an uploaded STL file, shows an interactive 3D viewer, slices it along the Z axis, saves each slice as a TIFF image, and lets you browse the stack inside the UI.
+This project provides a Gradio app that takes up to three uploaded STL files, shows interactive 3D viewers, slices each model along the Z axis, saves slices as TIFF images, and lets you browse each stack inside the UI.
 
 ## Run
 
@@ -23,8 +23,8 @@ Then open the local Gradio URL in your browser, upload an STL file, and generate
 
 ## What the app does
 
-- Uploads a single `.stl` file
-- Shows an interactive 3D viewer for rotating the model
+- Uploads up to three `.stl` files
+- Shows interactive 3D viewers for rotating each model
 - Lets you choose layer height and XY pixel size
 - Produces one `.tif` image per slice
 - Encodes material as black (`0`) and empty space as white (`255`) in each TIFF slice
@@ -36,3 +36,30 @@ Then open the local Gradio URL in your browser, upload an STL file, and generate
 ```powershell
 uv run pytest
 ```
+
+## Hugging Face Deployment
+
+This repository tracks `.stl` files with Git LFS (see `.gitattributes`).
+
+Before your first push on a machine:
+
+```powershell
+git lfs install
+git lfs pull
+```
+
+Recommended push flow:
+
+```powershell
+git push origin main
+git push hf-space main
+```
+
+If Hugging Face rejects a push for binary files, verify LFS setup first:
+
+```powershell
+git lfs version
+git lfs ls-files
+```
+
+Warning: `git lfs migrate` rewrites commit history. Use it only when you intentionally want history rewritten and all collaborators are aligned.