Document interceptor module boundaries

README.md

@@ -516,6 +516,8 @@ COMFYUI_ROOT=/tmp/comfyui-modal-test/ComfyUI \
 
 For full local development including the remote and Apple-local extras, use `uv sync --extra remote --extra local-apple --group test`.
 
+The prompt interception layer is organized as a compatibility aggregator over focused modules: `remote_plan_types.py` owns planning values, `modal_hardware.py` owns hardware metadata, `intercept_route_paths.py` owns route derivation, `modal_admin_ops.py` owns persistent-object maintenance, and `modal_ui_events.py` owns client event buffering. Root modules support both package imports used by ComfyUI and flat imports used by the Modal container; `tests/test_import_shapes.py` guards both layouts and the stable `comfyui_modal_sync_cloud` surface.
+
 ### Vast.ai API Simulator
 
 Vast development and CI need no live credentials or billable instances. Start the stateful local simulator:

docs/LEARNINGS.md

@@ -13,6 +13,8 @@
 
 - Every module that directly uses the optional Modal SDK owns its own guarded `modal` binding (`try: import modal` / `except ModuleNotFoundError: modal = None`). Do not centralize that binding in a shared compatibility module: local tests and fallback paths need to monkeypatch the exact consumer module without mutating unrelated consumers.
 - Tests must patch `modal` on the module whose function is under test. This remains true after an implementation moves to an extracted module; patching a compatibility re-export on its former module does not change the moved function's globals.
+- Compatibility aggregators may safely re-export functions, immutable value types, and tables whose identity is intentionally shared. Mutable lifecycle state such as locks, queues, and cache dictionaries must have one owner; tests should address that owner directly so clearing or replacing a binding cannot silently affect the wrong module.
+- Import compatibility needs executable coverage rather than inspection. Dynamically importing every root module under both the ComfyUI package identity and the Modal container's flat identity caught four legacy relative-only roots before the first extraction landed.
 
 ## 2026-08-29: Vast publication cost is dominated by stable dependencies