add docs.md and img files from origin/main

docs.md

@@ -0,0 +1,386 @@
+# ChatUI Helper Documentation
+
+Welcome to ChatUI Helper! This tool helps you create customizable AI chat interfaces for deployment on HuggingFace Spaces.
+
+## 📖 Quick Start Guide
+
+### Overview
+
+1. **Configure** your assistant using templates or custom settings
+2. **Preview** your configuration to test it works
+3. **Generate** your deployment package
+4. **Deploy** to HuggingFace Spaces
+
+**Requirements:**
+
+- HuggingFace account (free)
+- OpenRouter API key
+- Basic understanding of AI assistants
+
+<img src="img/march.png" alt="March of Intellect by Robert Seymour" width="500">
+<i>"The March of Intellect" by Robert Seymour (c.1828)</i>
+
+---
+---
+
+## 📝 Step 1: Configure & Preview Your Space
+
+### Configuration Tab Overview
+
+Configure your assistant through various sections in the Configuration tab, then test it in the Preview tab before generating your deployment package.
+
+<details>
+<summary><b>Templates & Identity</b></summary>
+
+**Quick Start Templates**
+
+- Choose from pre-configured academic templates (Socratic Research Chat, STEM Adventure Games, etc.)
+- Or select "None (Custom)" for a blank slate
+
+**Space Identity**
+
+- **Assistant Name**: Give your space a memorable name
+- **Tagline**: Brief description (max 60 characters) for HuggingFace YAML frontmatter
+- **Description**: Full markdown description for the README
+- **Theme**: Select from Gradio themes (Default, Soft, Glass, Monochrome, Base)
+
+<img src="img/identity.png" alt="Space Identity Configuration" width="500">
+
+</details>
+
+<details>
+<summary><b>System Configuration</b></summary>
+
+**System Prompt**
+
+- Define your assistant's role, context, and behavior
+- Set guardrails and creative constraints
+- Specify audience and terms of engagement
+
+**Model Selection**
+
+- Choose from available models (Gemini, Claude, GPT, Mistral, etc.)
+- Or enter a custom model ID
+
+**Language Support**
+
+- Configure language through system prompt instructions
+- Assistant can be instructed to respond exclusively in any language
+- See "Language Learning Partner" template for Italian example
+
+**Sampling Parameters**
+
+- **Temperature** (0-2): Controls response variability
+- **Max Tokens** (50-4096): Limits response length
+
+<img src="img/instructions.png" alt="System Instructions Configuration" width="600">
+
+</details>
+
+<details>
+<summary><b>Example Prompts</b></summary>
+
+**Example Prompts**
+
+- Add 3-5 starter prompts that showcase your assistant's capabilities
+- These appear as quick-start buttons for users
+- Help users understand how to interact with your assistant
+- Use the ➕/➖ buttons to add or remove examples
+
+</details>
+
+<details>
+<summary><b>URL Grounding</b></summary>
+
+**Grounding URLs**
+
+- Add up to 10 reference URLs to provide context
+- **Primary Sources (URLs 1-2)**: Always loaded, up to 8000 characters each
+- **Secondary Sources (URLs 3+)**: Supplementary context, up to 2500 characters each
+- URLs are fetched and included in the system prompt
+- Assistant will cite specific URLs when using grounded information
+- Use the ➕/➖ buttons to manage URLs
+
+<img src="img/grounding.png" alt="URL Grounding Configuration" width="300">
+
+</details>
+
+<details>
+<summary><b>Environment Variables</b></summary>
+
+**Required Secrets**
+
+- **API_KEY** (Required): Your OpenRouter API key (must start with `sk-or-`)
+  - Get from: https://openrouter.ai/keys
+  - Configure in HuggingFace Space settings
+
+- **HF_TOKEN** (Recommended): Enables configuration editor in deployed Space
+  - Get from: https://huggingface.co/settings/tokens
+  - Select "write" permissions when creating
+  - Allows updating configuration without redeployment
+
+- **ACCESS_CODE** (Recommended): Password-protect your Space
+  - Set any password value
+  - Users will need this code to access
+  - Leave unset for public access
+
+<img src="img/settings.png" alt="Navigate to Settings" width="500">
+<img src="img/add-secret-api.png" alt="Variables and Secrets" width="500">
+
+</details>
+
+<details>
+<summary><b>Upload Configuration</b></summary>
+
+**Upload Existing Configuration**
+- Have a previous `config.json` file?
+- Use the "Upload Configuration" accordion
+- Drag and drop or click to upload
+- All settings will be restored automatically
+
+<img src="img/upload.png" alt="Upload Configuration" width="500">
+
+</details>
+
+<details>
+<summary><b>Preview Your Assistant</b></summary>
+
+**Testing in Preview Tab**
+- Click "💬 Preview Configuration" to prepare your assistant
+- Switch to the Preview tab
+- Test with real queries and example prompts
+- Upload files if file upload is enabled
+- Export conversation history as markdown
+
+**Preview Features**
+- Real-time API responses (requires API key in environment)
+- Grounding context from configured URLs
+- Language-specific responses
+- Conversation export
+
+<img src="img/preview-config.png" alt="Preview Configuration" width="500">
+
+</details>
+
+---
+---
+
+## 🗳️ Step 2: Generate & Deploy
+
+### Deployment Package & HuggingFace Space Setup
+
+**Package Contents:** `app.py` (application), `requirements.txt` (dependencies), `config.json` (configuration), `README.md` (overview)
+
+<details>
+<summary><b>Generate & Create Space</b></summary>
+
+**Generate Deployment Package**
+
+1. Click "🗳️ Generate Deployment Package" in Configuration tab
+2. Download the generated ZIP file
+3. Extract files: `app.py`, `config.json`, `requirements.txt`, `README.md`
+
+<img src="img/deployment.png" alt="Deployment Package" width="500">
+
+**Create New Space**
+
+1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
+2. Click "Create new Space"
+3. Name your Space
+4. Add your preferred licensing (e.g. gpl-3, mit)
+5. Select **Gradio** SDK
+6. Choose **Blank** template
+7. Select hardware (CPU Basic is free)
+8. Click "Create Space"
+
+<img src="img/create-space.png" alt="Click Create Space" width="500">
+<img src="img/space.png" alt="Deployed Space" width="500">
+
+</details>
+
+<details>
+<summary><b>Upload Files</b></summary>
+
+**Upload Project Files**
+1. Navigate to the **Files** tab in your new Space
+2. Click "Contribute" → "Upload files"
+3. Unzip the deployment package
+4. Select all 4 files from your extracted package:
+   - `README.md`
+   - `app.py`
+   - `config.json`
+   - `requirements.txt`
+5. Commit directly to main branch, and your Space will start building
+
+<img src="img/drop-files.png" alt="Drag and drop files" width="500">
+
+<img src="img/uploading.png" alt="Commit files to space" width="500">
+
+</details>
+
+<details>
+<summary><b>Configure Secrets</b></summary>
+
+**Navigate to Settings**
+1. Click the **Settings** tab in your Space
+<img src="img/settings.png" alt="Navigate to settings" width="500">
+2. Scroll down to **Variables and secrets** section
+3. Click **New secret**
+<img src="img/add-secret-api.png" alt="Adding API Key Secret" width="500">
+
+**Add Required Secret**
+- **Name**: `API_KEY` (or your configured variable name)
+- **Value**: Your OpenRouter API key
+- Must start with `sk-or-`
+
+**Add Optional Secrets (if desired)**
+- **HF_TOKEN**: Your HuggingFace token with write permissions
+  - Enables the configuration editor in your Space
+  - Get from: https://huggingface.co/settings/tokens
+
+- **ACCESS_CODE**: Any password value
+  - Restricts access to authorized users
+  - Do NOT set an empty value
+  - Either set a code or don't create the secret
+
+</details>
+
+<details>
+<summary><b>Verify & Iterate</b></summary>
+
+**Monitor Build Process**
+1. Return to the **App** tab
+2. Watch for "Building..." status
+3. Check build logs for any errors
+4. Wait 1-3 minutes for completion
+5. Space will show "Running" when ready
+
+**Test Your Deployment**
+1. Try the example prompts
+2. Test different types of queries
+3. Verify grounding URLs are working
+4. Check language responses (if configured)
+
+**Iterate Configuration (with HF_TOKEN)**
+1. Go to ⚙️ Configuration tab in your Space
+2. Enter your HF_TOKEN to authenticate
+3. Modify settings as needed
+4. Click "Save Configuration"
+5. Space will automatically rebuild
+6. Test new configuration
+
+</details>
+
+---
+---
+
+## 🔧 Troubleshooting
+
+### Common Issues and Solutions
+
+Find solutions to common problems organized by category.
+
+<details>
+<summary><b>Build Errors</b></summary>
+
+**Requirements Compatibility**
+- Ensure Gradio version ≥ 5.39.0 in requirements.txt
+- Check all dependencies are spelled correctly
+- Verify version numbers are compatible
+
+**Common Build Failures**
+- Missing dependencies: Add to requirements.txt
+- Import errors: Check module names and casing
+- Syntax errors: Review app.py for Python syntax issues
+
+</details>
+
+<details>
+<summary><b>API Errors</b></summary>
+
+**API Key Issues**
+- Verify API_KEY is set in HuggingFace Secrets
+- Ensure key starts with 'sk-or-' for OpenRouter
+- Check for extra spaces or quotes in the secret value
+
+**API Response Errors**
+- 401 Unauthorized: Invalid API key
+- 402 Payment Required: No API credits remaining
+- 429 Rate Limited: Too many requests, wait and retry
+- 500 Server Error: OpenRouter service issue
+
+</details>
+
+<details>
+<summary><b>Access Control Issues</b></summary>
+
+**ACCESS_CODE Problems**
+- Code must match exactly (case-sensitive)
+- Don't include quotes around the password
+- Check for trailing spaces in the secret
+- To disable: Delete the ACCESS_CODE secret entirely
+
+**Authentication Flow**
+- Users enter code on first visit
+- Code is stored in browser session
+- Clear cookies to re-prompt for code
+
+</details>
+
+<details>
+<summary><b>Preview Tab Not Working</b></summary>
+
+**Preview Issues**
+- Click "💬 Preview Configuration" first
+- Ensure all required fields are filled
+- Try refreshing the page
+
+</details>
+
+<details>
+<summary><b>Configuration Status Shows ❌</b></summary>
+
+**Status Check Failures**
+- Red X means configuration issue detected
+- Usually indicates missing or invalid API key
+
+**Resolution Steps**
+1. Verify secret name matches your configuration
+2. Default is API_KEY, check if you changed it
+3. Regenerate API key at openrouter.ai/keys
+4. Update secret in HuggingFace Space settings
+5. Wait 30 seconds and refresh
+
+</details>
+
+---
+---
+
+## 📚 Additional Resources
+
+### Documentation Links
+
+**HuggingFace**
+
+- [Spaces Overview](https://huggingface.co/docs/hub/spaces-overview)
+- [Gradio on Spaces](https://huggingface.co/docs/hub/spaces-gradio)
+- [Environment Variables](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)
+
+**OpenRouter**
+
+- [API Keys](https://openrouter.ai/keys)
+- [Model Comparison](https://openrouter.ai/models)
+- [Pricing](https://openrouter.ai/docs#models)
+
+**Gradio**
+
+- [Chat Interface](https://gradio.app/docs/chatinterface)
+- [Components](https://gradio.app/docs/)
+- [Sharing Apps](https://gradio.app/sharing-your-app/)
+
+**Community Support**
+
+- [HuggingFace Forums](https://discuss.huggingface.co/)
+- [Gradio Discord](https://discord.gg/feTf9x3ZSB)
+
+</details>