Update README.md

Document the free model-first ZeroGPU pipeline

README.md

@@ -31,7 +31,7 @@ If a requested role has no deterministic hook, assets are still generated for re
 
 Generated sprites receive automated dimension, alpha-channel, and corner-transparency checks. These checks do not establish semantic or artistic correctness, so every role also has a manual approval control and per-role regeneration.
 
-The UI reports the configured prompt and image pipeline and labels every role with its actual source. Every asset now carries a normalized camera contract (`top_down`, `side_view`, `isometric`, `first_person`, or `front_view`). Top-down background prompts explicitly forbid a sky, horizon, eye-level view, and front-facing facades. The free procedural renderer also routes top-down and isometric backgrounds through dedicated geometry, so camera compliance does not depend only on prompt wording.
+The UI reports the configured prompt and image pipeline and labels every role with its actual source. Every asset carries a normalized camera contract (`top_down`, `side_view`, `isometric`, `first_person`, or `front_view`). Top-down background prompts explicitly forbid a sky, horizon, eye-level view, and front-facing facades.
 
 Procedural generators provide predictable structure and real transparency but have limited open-ended semantic fidelity. Diffusion models provide more visual variety but are more likely to miss perspective, subject, background, or edge constraints; sprite outputs therefore receive alpha post-processing and still require visual approval. Background and sprite diffusion runs use different negative prompts so valid characters and vehicles are not accidentally excluded from sprite generation.
 
@@ -39,17 +39,39 @@ The app combines the game type, perspective, theme, and pasted code into explici
 
 If the Space has an `HF_TOKEN` secret and `USE_HF_PROMPT_PROVIDER=1`, it first uses the text model in `HF_PROMPT_MODEL` to interpret the code, roles, and theme into image prompts. The default prompt model is `Qwen/Qwen2.5-Coder-7B-Instruct`. The camera contract is appended after model interpretation, so the model cannot silently remove it.
 
-## Background generation tiers
+## Default neural image pipeline
 
-The default tier is deliberately free and deterministic:
+The deployed Space is designed for Hugging Face ZeroGPU and uses a real diffusion model for both sprites and backgrounds:
 
 ```text
-camera-aware procedural background
+segmind/SSD-1B + latent-consistency/lcm-lora-ssd-1b
 ```
 
-It runs on CPU Basic and is the active production-safe fallback. It is deterministic drawing code, not a neural image-generation model. The UI reports this explicitly for every role. It fixes camera geometry, but it cannot match the semantic richness of a large image model.
+SSD-1B is an Apache-2.0 distilled SDXL model. The LCM adapter reduces generation to four denoising steps. The weights run inside the Space's ZeroGPU allocation, so the app does not consume Hugging Face Inference Provider credits and does not require a paid image API.
 
-For a GPU Space, enable the production depth-control path:
+Sprites use text-to-image generation followed by transparency extraction. Backgrounds use image-to-image generation from a deterministic, perspective-specific layout guide. This gives the model explicit top-down, side-view, or isometric structure instead of relying on prompt wording alone. Background negative prompts reject characters and generic particle overlays; the procedural lava guide no longer contains the circular effects that previously appeared as repeated particles.
+
+The deployed Space is fail-closed: if the primary neural model cannot run, generation stops with a visible error instead of silently returning procedural art and calling it model output. The procedural renderer remains available for local development and emergency diagnostics only.
+
+ZeroGPU is free for eligible personal accounts, but it is quota-limited rather than unlimited: free accounts currently receive five minutes of GPU time per day. Queueing or a quota message is therefore possible even though no inference credits or payment are required.
+
+The primary pipeline can be configured with:
+
+```text
+USE_PRIMARY_IMAGE_MODEL=1
+REQUIRE_PRIMARY_IMAGE_MODEL=1
+PRIMARY_IMAGE_MODEL=segmind/SSD-1B
+PRIMARY_LORA_MODEL=latent-consistency/lcm-lora-ssd-1b
+PRIMARY_IMAGE_STEPS=4
+PRIMARY_GUIDANCE_SCALE=1.5
+PRIMARY_BACKGROUND_STRENGTH=0.72
+```
+
+`HF_TOKEN` is not required to download these public image models. It remains useful for the optional prompt-model provider and for the UI's token-validity check.
+
+## Optional generation tiers
+
+For a larger dedicated GPU Space, the SDXL Depth ControlNet path remains available:
 
 ```text
 USE_CONTROLNET_FOR_BACKGROUNDS=1
@@ -58,7 +80,7 @@ CONTROLNET_MODEL=diffusers/controlnet-depth-sdxl-1.0-small
 CONTROLNET_STEPS=24
 ```
 
-This constructs a camera-specific depth-like control image and runs SDXL with Depth ControlNet before falling back. It intentionally refuses to run on CPU-only hardware: loading SDXL on CPU Basic is not a credible interactive production configuration. The small ControlNet adapter is experimental, so perspective still needs human review.
+This constructs a camera-specific depth-like control image and runs SDXL with Depth ControlNet after the primary model path. It intentionally refuses to run on CPU-only hardware. The small ControlNet adapter is experimental, so perspective still needs human review.
 
 For an API-backed refinement that works from a CPU Space, enable:
 
@@ -69,10 +91,10 @@ HF_STRUCTURE_PROVIDER=fal-ai
 HF_TOKEN=<Space secret with Inference Providers permission>
 ```
 
-This sends the deterministic background as an image-to-image layout reference, asks the model to preserve its projection and walkable geometry, and falls back safely if the request fails. `FLUX.2-klein-4B` is Apache-2.0 licensed and available through a Hugging Face Inference Provider. It is not unlimited-free infrastructure: a free Hugging Face user currently receives only a small monthly inference credit, after which purchased credits are required. Keep the flag disabled unless paid API usage and token handling are acceptable.
+This sends the deterministic background as an image-to-image layout reference and asks the model to preserve its projection and walkable geometry. `FLUX.2-klein-4B` is available through a Hugging Face Inference Provider. This option is disabled by default because provider calls consume account inference credits; it is not needed for the free ZeroGPU pipeline.
 
 The older text-to-image fallback remains opt-in through `USE_HF_IMAGE_PROVIDER=1` and `HF_IMAGE_MODEL` (default `black-forest-labs/FLUX.1-schnell`). Unlike the structure-refinement tier, text-to-image receives no layout image and is therefore the weakest model option for strict camera compliance.
 
-If every enabled model path fails, the app uses the local style-aware Pillow fallback, which varies watercolor, vector/neon, claymation, oil-painting, anime, pixel-art looks, and common game sprite silhouettes.
+When running locally with `REQUIRE_PRIMARY_IMAGE_MODEL=0`, model failure may fall back to the style-aware Pillow renderer for development. The public Space should keep the requirement enabled so its generated images are provably model-backed.
 
 `black-forest-labs/FLUX.1-Depth-dev` is not configured here. Its gated 12B weights, non-commercial development license, and lack of a Hugging Face Inference Provider make it a poor fit for this Space and impossible to run credibly on CPU Basic. Black Forest Labs offers Depth Pro through its own API, which requires a separate provider account and billing rather than only the current free Hugging Face account.