docs: Add comprehensive job submission requirements

Critical Updates:
- Added HuggingFace Pro account requirement (/month with credit card)
- Clarified HF token needs Read + Write + Run Jobs permissions
- Updated all documentation to warn users about requirements

Documentation Screen (SMOLTRACE tab):
- Added prominent Requirements section before job configuration
- Listed HF Pro account requirement with pricing link
- Specified token permissions needed (Read + Write + Run Jobs)
- Added hardware pricing estimates (~/usr/bin/bash.05/hr to ~.00/hr)
- Warned that read-only tokens will NOT work

Settings Screen:
- Updated HF token label to indicate job submission requirement
- Added warning in info text about Pro account requirement
- Expanded HF token documentation with required permissions checklist
- Added links to HF pricing and billing pages

README:
- Split Prerequisites into viewing vs job submission
- Added Requirements for Job Submission section with clear warnings
- Added hardware options and pricing information
- Added step-by-step guide for submitting jobs
- Clarified what happens during job execution
- Updated HF token guidance for both viewing and job submission

Why These Changes:
- Users were not aware HF Pro account is required for jobs
- Many users have read-only tokens which fail silently
- Credit card requirement was not mentioned
- Pricing information was missing, users couldn't estimate costs

Impact:
- Sets clear expectations before users attempt job submission
- Prevents frustration from failed submissions due to permissions
- Helps users budget for compute costs
- Improves transparency about platform requirements

README.md

@@ -81,9 +81,17 @@ TraceMind demonstrates enterprise MCP client usage by connecting to [TraceMind-m
 ## Quick Start
 
 ### Prerequisites
+
+**For Viewing Leaderboard & Analysis:**
 - Python 3.10+
 - HuggingFace account (for authentication)
-- HuggingFace token (optional, for private datasets)
+
+**For Submitting Evaluation Jobs:**
+- ⚠️ **HuggingFace Pro account** ($9/month) with credit card
+- HuggingFace token with **Read + Write + Run Jobs** permissions
+- API keys for model providers (OpenAI, Anthropic, etc.)
+
+> **Note**: Job submission requires a paid HuggingFace Pro account to access compute infrastructure. Viewing existing results is free.
 
 ### Installation
 
@@ -149,13 +157,11 @@ Both APIs have generous free tiers:
 - Click "Get API Key" → Create project → Generate key
 - **Free tier**: 1,500 requests/day (sufficient for evaluation)
 
-**HuggingFace Token**:
+**HuggingFace Token** (for viewing):
 - Visit: https://huggingface.co/settings/tokens
-- Click "New token" → Name it (e.g., "TraceMind Access")
+- Click "New token" → Name it (e.g., "TraceMind Viewer")
 - **Permissions**:
-  - Select "Read" for viewing datasets (sufficient for most features)
-  - Select "Write" if you want to use synthetic dataset generation & push features (via MCP server)
-- **Recommended**: Use "Write" permissions for full functionality
+  - Select "Read" for viewing datasets (sufficient for browsing leaderboard)
 - **Free tier**: No rate limits for public dataset access
 
 ### Default Configuration (Without Your Keys)
@@ -172,6 +178,73 @@ If you don't configure your own keys:
 ✅ **Not exposed via API**: Settings forms use `api_name=False`
 ✅ **HTTPS encryption**: All API calls over secure connections
 
+## 🚀 Submitting Evaluation Jobs
+
+TraceMind-AI allows you to submit evaluation jobs directly from the UI to HuggingFace Jobs infrastructure.
+
+### ⚠️ Requirements for Job Submission
+
+**IMPORTANT**: To submit evaluation jobs, you need:
+
+1. **HuggingFace Pro Account** ($9/month)
+   - Sign up at: https://huggingface.co/pricing
+   - **Credit card required** to pay for compute usage
+   - Free accounts cannot submit jobs
+
+2. **HuggingFace Token with Enhanced Permissions**
+   - Visit: https://huggingface.co/settings/tokens
+   - Create token with these permissions:
+     - ✅ **Read** (view datasets)
+     - ✅ **Write** (upload results)
+     - ✅ **Run Jobs** (submit evaluation jobs)
+   - ⚠️ Read-only tokens will NOT work
+
+3. **Model Provider API Keys**
+   - OpenAI, Anthropic, Google, etc.
+   - Configure in Settings → LLM Provider API Keys
+   - Passed securely as job secrets
+
+### Hardware Options & Pricing
+
+TraceMind auto-selects hardware based on your model:
+
+- **cpu-basic**: API models (OpenAI, Anthropic) - ~$0.05/hr
+- **t4-small**: Small models (4B-8B parameters) - ~$0.60/hr
+- **a10g-small**: Medium models (7B-13B) - ~$1.10/hr
+- **a100-large**: Large models (70B+) - ~$3.00/hr
+
+Full pricing: https://huggingface.co/pricing#spaces-pricing
+
+### How to Submit a Job
+
+1. **Configure API Keys** (Settings tab):
+   - Add HF Token (with Run Jobs permission)
+   - Add Modal API credentials (optional, for Modal execution)
+   - Add LLM provider keys (OpenAI, Anthropic, etc.)
+
+2. **Create Evaluation** (New Evaluation tab):
+   - Select infrastructure: HuggingFace Jobs or Modal
+   - Choose model and agent type
+   - Configure hardware (or use "auto")
+   - Set timeout (default: 1h)
+   - Click "Submit Evaluation"
+
+3. **Monitor Job**:
+   - View job ID and status
+   - Track at: https://huggingface.co/jobs
+   - Results automatically appear in leaderboard when complete
+
+### What Happens During a Job
+
+1. Job starts on HuggingFace infrastructure
+2. SMOLTRACE evaluates your model with OpenTelemetry tracing
+3. Results uploaded to 4 HuggingFace datasets:
+   - Leaderboard entry (summary stats)
+   - Results dataset (test case details)
+   - Traces dataset (OTEL spans)
+   - Metrics dataset (GPU metrics, CO2 emissions)
+4. Results appear in TraceMind leaderboard automatically
+
 ## Configuration
 
 Create a `.env` file with the following variables:

screens/documentation.py

@@ -984,7 +984,29 @@ SMOLTRACE automatically detects available resources:
 
 ## 🏗️ Integration with HuggingFace Jobs
 
-SMOLTRACE works seamlessly with HuggingFace Jobs:
+SMOLTRACE works seamlessly with HuggingFace Jobs for running evaluations on cloud infrastructure.
+
+### ⚠️ Requirements to Submit Jobs
+
+**IMPORTANT**: To submit jobs via TraceMind UI or HF CLI, you must:
+
+1. **🔑 HuggingFace Pro Account**
+   - You must be a HuggingFace Pro user
+   - **Credit card required** to pay for compute usage
+   - Sign up at: https://huggingface.co/pricing
+
+2. **🎫 HuggingFace Token Permissions**
+   - Your HF token needs **Read + Write** permissions
+   - Token must have **"Run Jobs"** permission enabled
+   - Create/update token at: https://huggingface.co/settings/tokens
+   - ⚠️ Read-only tokens will **NOT** work for job submission
+
+3. **💳 Billing**
+   - You will be charged for compute usage
+   - Pricing: https://huggingface.co/pricing#spaces-pricing
+   - Monitor usage at: https://huggingface.co/settings/billing
+
+### Example Job Configuration
 
 ```yaml
 # job.yaml
@@ -1005,15 +1027,21 @@ command: |
     --leaderboard-repo huggingface/smolagents-leaderboard
 ```
 
-**Hardware Selection:**
-- 🔧 **gpu-a10**: Perfect for 7B-13B models (cost-effective)
-- 🚀 **gpu-h200**: Use for 70B+ models (high performance)
-- 💻 **cpu-basic**: API models (OpenAI, Anthropic via LiteLLM)
+### Hardware Selection
+
+- 🔧 **cpu-basic**: API models (OpenAI, Anthropic via LiteLLM) - ~$0.05/hr
+- 🎮 **t4-small**: Small models (4B-8B) - ~$0.60/hr
+- 🔧 **a10g-small**: Medium models (7B-13B) - ~$1.10/hr
+- 🚀 **a100-large**: Large models (70B+) - ~$3.00/hr
+
+**Pricing**: See https://huggingface.co/pricing#spaces-pricing
+
+### Benefits
 
-**Benefits:**
 - 📊 **Automatic Upload**: Results → HuggingFace datasets
 - 🔄 **Reproducible**: Same environment every time
 - ⚡ **Optimized Compute**: Right hardware for your model size
+- 💰 **Pay-per-use**: Only pay for actual compute time
 
 ---
 

screens/settings.py

@@ -78,11 +78,11 @@ def create_settings_screen():
             with gr.Row():
                 with gr.Column(scale=4):
                     hf_token = gr.Textbox(
-                        label="HuggingFace Token",
+                        label="HuggingFace Token (Required for Job Submission)",
                         placeholder="Enter your HF token (starts with 'hf_...')",
                         type="password",
                         value=os.environ.get("HF_TOKEN", ""),
-                        info="Get your token at: https://huggingface.co/settings/tokens"
+                        info="⚠️ Token needs: Read + Write + Run Jobs permissions | Pro account required"
                     )
                 with gr.Column(scale=1):
                     hf_status = gr.Markdown("⚪ Not configured")
@@ -167,13 +167,22 @@ LITELLM_API_KEY=...""",
 
             ### HuggingFace Token
 
+            **For Job Submission (Required):**
+
             1. Go to [HuggingFace Settings](https://huggingface.co/settings/tokens)
             2. Click "New token"
-            3. Give it a name (e.g., "TraceMind Access")
-            4. Select "Read" permissions
+            3. Give it a name (e.g., "TraceMind Job Submission")
+            4. Select these permissions:
+               - ✅ **Read** (view datasets)
+               - ✅ **Write** (upload results)
+               - ✅ **Run Jobs** (submit evaluation jobs)
             5. Create and copy the token (starts with `hf_...`)
 
-            **Note**: Read-only access is sufficient for viewing datasets
+            **⚠️ IMPORTANT Requirements:**
+            - You must have a **HuggingFace Pro account** ($9/month)
+            - **Credit card required** to pay for compute usage
+            - Read-only tokens will NOT work for job submission
+            - Sign up for Pro: https://huggingface.co/pricing
 
             ---