Document project setup and usage

Replace the README stub with implementation-grounded documentation covering the project workflow, prerequisites, configuration, local setup, deployment notes, API behavior where applicable, and troubleshooting.

README.md

@@ -9,4 +9,77 @@ app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+> **Note:** This README was generated with assistance from GPT and should be verified against the current implementation.
+
+# Outpaint
+
+Outpaint is a small Gradio application that extends an image in one direction with Google's Gemini image-generation model (`gemini-2.5-flash-image`, nicknamed Nano Banana in the UI).
+
+The app pads the selected edge with chroma-key green, generates an editable instruction describing which region to fill, sends the padded image and prompt to Gemini, and displays the returned image. A generated result can be reused as the next input for iterative expansion.
+
+## Workflow
+
+1. Upload an image.
+2. Choose top, bottom, left, or right and select 50–500 pixels of padding.
+3. Inspect the green padded preview and optionally edit the generated prompt.
+4. Click **Outpaint with Nano Banana**.
+5. Optionally click **Reuse Outpainted Image** and repeat in another direction.
+
+All image state lives in the Gradio session. The application does not implement persistent storage or a separate HTTP API route.
+
+## Project layout
+
+| Path | Purpose |
+| --- | --- |
+| `app.py` | Image padding, Gemini request handling, Gradio UI, and event wiring |
+| `requirements.txt` | Pillow and Google Gen AI SDK dependencies |
+| `README.md` | Hugging Face Space metadata and project documentation |
+
+## Prerequisites
+
+- Python 3.10 or newer
+- A Google Gemini API key with access to `gemini-2.5-flash-image`
+- Network access to Google's Generative AI API
+
+The hosted Space provides Gradio 5.49.1. Install it explicitly for local development because `requirements.txt` does not list Gradio.
+
+## Configuration
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `GEMINI_API_KEY` | Yes | Authenticates `google-genai` requests |
+
+The Gemini client is created when `app.py` is imported, so set the variable before starting Python. Never commit API keys.
+
+## Run locally
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install "gradio==5.49.1"
+
+export GEMINI_API_KEY="..."
+python app.py
+```
+
+Open `http://127.0.0.1:7860` and follow the workflow above. The app starts Gradio with debug logging enabled.
+
+## Hugging Face Space notes
+
+- Repository: `GFHLabs/Outpaint`
+- SDK: Gradio 5.49.1
+- Entry point: `app.py`
+- Add `GEMINI_API_KEY` under **Settings → Variables and secrets** as a secret.
+- Pushing changes to the Space repository triggers a rebuild/restart.
+- The generated image is returned by the model; the code does not preserve source or output files outside Gradio's temporary handling.
+
+## Troubleshooting
+
+- **Authentication or permission error:** confirm `GEMINI_API_KEY` is set before startup and that the key can use `gemini-2.5-flash-image` in the current account/region.
+- **No image is returned:** inspect the runtime logs. When the response contains no inline image data, the app intentionally returns the padded input and labels it as “no result from API.”
+- **Green remains in the result:** make the custom prompt explicitly require the entire green region to be replaced, or reduce the padding and retry.
+- **The extension looks inconsistent:** use a smaller padding amount and describe the expected scene continuation, lighting, perspective, and objects in the custom prompt.
+- **An edit appears to use stale state:** click a direction after uploading or reusing an image; that action refreshes the padded image and direction state.
+- **Local import error for Gradio:** install the metadata-pinned version shown above; it is supplied by Hugging Face but omitted from `requirements.txt`.