Docs: Add Git LFS troubleshooting notes to README

README.md

@@ -9,4 +9,38 @@ app_file: app.py
 pinned: false
 license: apache-2.0
 ---
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## Git LFS Troubleshooting Notes
+
+This repository encountered several Git LFS issues during setup. Here's a summary for future reference:
+
+1.  **Missing LFS Objects in History:** Initial pushes failed because the branch history contained references to LFS objects (specifically `a11f8941...` related to `db5/.../data_level0.bin`) that were no longer available locally or on the remote LFS store. Attempts to rewrite history using `git filter-branch` also failed because the rewrite process itself required fetching *other* missing LFS objects.
+    *   **Resolution:** We created a clean base branch (`fresh-start`) with no history (`git checkout --orphan fresh-start`), committed a placeholder file, and pushed it forcefully to the remote (`git push -u space3 fresh-start:main --force`). This reset the remote `main` branch.
+
+2.  **Importing State & Untracked Binaries:** We copied the desired file state from the old branch (`git checkout <old-branch> -- .`) into the clean `fresh-start` branch. However, the subsequent push failed because some binary files (e.g., `.png`) were included but weren't tracked by LFS according to the `.gitattributes` file *at that time*.
+    *   **Resolution:**
+        *   Added the necessary file patterns (e.g., `*.png filter=lfs ...`) to `.gitattributes`.
+        *   Crucially, we had to ensure the commit correctly reflected this change. Amending wasn't sufficient. We used:
+            ```bash
+            # Reset the commit but keep files in working dir
+            git reset HEAD~1
+            # Re-stage files, forcing re-evaluation based on current .gitattributes
+            git add --renormalize .
+            # Commit the properly processed files
+            git commit -m "Commit message"
+            # Force push the corrected commit
+            git push --force
+            ```
+
+3.  **Ignoring Necessary Directories:** A required directory (`vector-databases-deployed`) was unintentionally ignored via `.gitignore`.
+    *   **Resolution:**
+        *   Removed the corresponding line from `.gitignore`.
+        *   Staged the `.gitignore` file and the previously ignored directory (`git add .gitignore vector-databases-deployed/`).
+        *   Committed and pushed the changes.
+
+**Key Takeaways:**
+
+*   Pushing branches with problematic LFS history to a fresh remote can fail. Starting the remote with a clean, history-free branch is a workaround.
+*   When adding LFS tracking for existing binary files via `.gitattributes`, ensure the commit correctly converts files to LFS pointers. `git add --renormalize .` after updating `.gitattributes` and *before* committing is often necessary.
+*   Double-check `.gitignore` if expected files or directories are missing after a `git add .`.