Document Git LFS runtime bundle workflow

AGENTS.md

@@ -9,10 +9,12 @@ This repository ships `pyro-mcp`, an MCP-compatible package for ephemeral VM lif
 ## Development Workflow
 
 - Use `uv` for all Python environment and command execution.
+- Install Git LFS before cloning or materializing the packaged runtime bundle: `git lfs install`.
 - Run `make setup` after cloning.
 - Run `make check` before opening a PR.
 - Public user-facing CLI is `pyro`.
 - Public Python SDK entrypoint is `from pyro_mcp import Pyro`.
+- The packaged runtime images under `src/pyro_mcp/runtime_bundle/` are stored in Git LFS.
 - Use `make runtime-bundle` to regenerate the packaged runtime bundle from `runtime_sources/`.
 - Use `make runtime-materialize` to build real runtime inputs into `build/runtime_sources/`.
 - Use `make runtime-fetch-binaries`, `make runtime-build-kernel-real`, and `make runtime-build-rootfs-real` if you need to debug the real-source pipeline step by step.
@@ -24,6 +26,8 @@ This repository ships `pyro-mcp`, an MCP-compatible package for ephemeral VM lif
 - Use `make doctor` to inspect bundled runtime integrity and host prerequisites.
 - Network-enabled flows require host privilege for TAP/NAT setup; the current implementation uses `sudo -n` for `ip`, `nft`, and `iptables` when available.
 - If you need full log payloads from the Ollama demo, use `make ollama-demo OLLAMA_DEMO_FLAGS=-v`.
+- After heavy runtime work, reclaim local space with `rm -rf build` and `git lfs prune`.
+- The pre-migration `pre-lfs-*` tag is local backup material only; do not push it or it will keep the old giant blobs reachable.
 
 ## Quality Gates
 

README.md

@@ -26,6 +26,28 @@ pyro mcp serve
 The public user-facing interface is `pyro` and `Pyro`.
 `Makefile` targets are contributor conveniences for this repository and are not the primary product UX.
 
+## Repository Storage
+
+This repository uses Git LFS for the packaged runtime images under
+`src/pyro_mcp/runtime_bundle/`.
+
+Fresh contributor setup:
+
+```bash
+git lfs install
+git clone <repo>
+cd pyro
+git lfs pull
+make setup
+```
+
+The large files tracked through LFS are:
+
+- `src/pyro_mcp/runtime_bundle/**/rootfs.ext4`
+- `src/pyro_mcp/runtime_bundle/**/vmlinux`
+
+If you are working from an older clone created before the LFS migration, reclone or realign your branch to the rewritten history before doing more work.
+
 ## Capabilities
 
 - Firecracker microVM execution with bundled runtime artifacts
@@ -198,3 +220,12 @@ Runtime build and validation helpers remain available through `make`, including:
 - `make runtime-materialize`
 - `make runtime-boot-check`
 - `make runtime-network-check`
+
+Space cleanup after runtime work:
+
+```bash
+rm -rf build
+git lfs prune
+```
+
+Recreating `.venv/` is also a straightforward way to reclaim local disk if needed.

runtime_sources/README.md

@@ -7,6 +7,7 @@ Current state:
 - the checked-in tracked files under `runtime_sources/linux-x86_64/` are build recipes and lock metadata, not the materialized binaries/images.
 - `guest/pyro_guest_agent.py` is the guest agent source artifact that is installed into each built rootfs.
 - real source materialization now writes into `build/runtime_sources/`, not back into the tracked placeholder files.
+- the packaged runtime images under `src/pyro_mcp/runtime_bundle/` are stored via Git LFS, so contributor clones need `git lfs install` and LFS-enabled checkout.
 
 Materialization workflow:
 1. `make runtime-fetch-binaries`