Upload PromptForge v1.0 — Structured prompt generator for Google AI Studio

.env.example

@@ -1,14 +1,17 @@
-# PromptForge v3.0 — Environment Variables
-# Copy to .env and fill in your values. NEVER commit .env to version control.
+# PromptForge v4.0 — Environment Variables
+# Copy this file to .env and fill in your values.
+# Never commit a filled-in .env to version control.
 
-# ── AI Provider Keys ───────────────────────────────────────────────────────
-# Hugging Face: https://huggingface.co/settings/tokens  (starts with hf_)
-HF_API_KEY=your_huggingface_token_here
+# ── Server ────────────────────────────────────────────────────────────
+PORT=7860
+LOG_DIR=logs
 
-# Google AI Studio: https://aistudio.google.com/app/apikey  (starts with AIza)
-GOOGLE_API_KEY=your_google_api_key_here
+# ── AI Enhancement (optional) ─────────────────────────────────────────
+# Leave blank to use local engine only.
+HF_API_KEY=
+GOOGLE_API_KEY=
 
-# ── Server Settings ────────────────────────────────────────────────────────
-HOST=0.0.0.0
-PORT=7860          # HuggingFace Spaces requires 7860
-LOG_DIR=./logs     # Where to persist prompt/settings JSON files
+# ── Model overrides (optional) ────────────────────────────────────────
+# Override the default model used for each provider.
+# HF_MODEL=mistralai/Mistral-7B-Instruct-v0.2
+# GOOGLE_MODEL=gemini-1.5-flash

README.md

@@ -1,263 +1,245 @@
+# PromptForge v4.0
+
+> **Structured prompt generator for Google AI Studio.**
+> Transform any instruction into a production-ready prompt — with role, constraints, style, safety guardrails, and few-shot examples — via a polished dark-first web UI.
+
 ---
-sdk: docker
-emoji: 🚀
-colorFrom: yellow
-colorTo: yellow
-pinned: true
-thumbnail: >-
-  https://cdn-uploads.huggingface.co/production/uploads/66367933cc7af105efbcd2dc/-oSODSxF1hK7KX-3Rmad3.png
----
-# ⚙️ PromptForge
 
-**PromptForge** is a cloud-ready FastAPI service that converts raw user instructions into
-**structured, ready-to-use prompts** for Google AI Studio. It follows a 5-step guided workflow
-with a clean HTML/JS frontend, optional AI enhancement via Google Gemini or Hugging Face, and
-persistent prompt history.
+## What's New in v4.0
+
+| Feature | Detail |
+|---|---|
+| **2 new personas** | `devops_eng` and `ml_engineer` |
+| **Stats dashboard** | Real-time bar charts, status breakdown, refinement count |
+| **Batch generate** | Up to 10 prompts in a single API call |
+| **Full-text search** | `GET /api/search?q=…` across all stored prompts |
+| **Duplicate setting** | One-click copy of any saved instruction setting |
+| **Favourite / archive** | Star prompts and settings; archive completed work |
+| **API key validation** | Live ✓ key-check endpoint for HF and Google |
+| **Model override** | Use any HF or Gemini model, not just the defaults |
+| **Dark/light theme** | Persistent theme, toggled with `Alt+T` |
+| **Keyboard shortcuts** | Full keyboard navigation (press `?` to see all) |
+| **Retry + backoff** | AI calls now retry up to 3× with exponential backoff |
+| **Word count** | Every generated prompt shows its word count |
+| **Auto-tagging** | Tags are inferred from instruction text automatically |
+| **6 seeded settings** | React, FastAPI, Blog, SQL, Docker/CI, LLM Fine-tuning |
 
 ---
 
-## 📁 Folder Structure
+## Project Structure
 
 ```
-promptforge/
+promptforge_v4/
 ├── backend/
-│   ├── main.py            ← FastAPI server + all routes
-│   ├── schemas.py         ← Pydantic request/response models
-│   ├── prompt_logic.py    ← Core instruction → structured prompt engine
-│   ├── ai_client.py       ← Hugging Face & Google Gemini integration
-│   ├── store.py           ← In-memory store with JSON persistence
-│   ├── requirements.txt
-│   └── tests/
-│       └── test_promptforge.py
+│   ├── main.py               # FastAPI app — all routes
+│   ├── schemas.py            # Pydantic v2 models
+│   ├── prompt_logic.py       # Core generation engine
+│   ├── ai_client.py          # HuggingFace + Google Gemini client
+│   ├── store.py              # Prompt manifest persistence
+│   └── instruction_store.py  # Instruction settings persistence
 ├── frontend/
-│   ├── index.html         ← Single-page UI
-│   ├── client.js          ← Fetch-based API client
-│   └── style.css          ← Dark-mode responsive styling
-├── logs/                  ← Auto-created; stores prompt_history.json
-├── Dockerfile
-├── docker-compose.yml
-├── .env.example           ← Copy to .env and fill API keys
-├── .gitignore
+│   ├── index.html            # Single-page app (4 pages)
+│   ├── style.css             # Dark-first design system
+│   └── client.js             # Vanilla JS — all UI logic
+├── tests/
+│   └── test_promptforge.py   # 60+ pytest tests
+├── logs/                     # Auto-created; holds .json stores
+├── requirements.txt
+├── .env.example
 └── README.md
 ```
 
----
+### File rename table (original → v4.0)
 
-## 🔄 5-Step Workflow
-
-| Step | Endpoint | Description |
-|------|----------|-------------|
-| **0** | `POST /api/generate` | Accept raw instruction → produce JSON manifest |
-| **1** | *(frontend)* | Display manifest for human review |
-| **2** | `POST /api/approve` | Approve (with optional edits) → finalize prompt |
-| **3** | *(frontend)* | Preview plain-text + JSON output |
-| **4** | `POST /api/export` | Download as `.json` or `.txt` |
-| **5** | `POST /api/refine` | Iterate with feedback → new manifest version |
+| Uploaded filename | Correct path |
+|---|---|
+| `deepseek_python_20260217_9f4e5a.py` | `backend/main.py` |
+| `deepseek_python_20260217_2030de.py` | `backend/schemas.py` |
+| `deepseek_python_20260217_5bfa10.py` | `backend/prompt_logic.py` |
+| `deepseek_python_20260217_6a4c4c.py` | `backend/ai_client.py` |
+| `deepseek_python_20260217_eb3ef8.py` | `backend/store.py` |
+| `deepseek_python_20260217_c1c990.py` | `backend/instruction_store.py` |
+| `deepseek_html_20260217_cdc933.html` | `frontend/index.html` |
+| `deepseek_css_20260217_6dc1e7.css`   | `frontend/style.css` |
+| `deepseek_javascript_20260217_99ef58.js` | `frontend/client.js` |
+| `deepseek_txt_20260217_77ef1d.txt`   | `requirements.txt` |
 
 ---
 
-## 🚀 Running Locally
+## Quick Start
 
-### 1. Clone & set up environment
+### 1. Create virtual environment
 
 ```bash
-git clone <your-repo-url>
-cd promptforge
-
-# Create virtual environment
 python -m venv .venv
-source .venv/bin/activate          # Windows: .venv\Scripts\activate
-
-# Install dependencies
-pip install -r backend/requirements.txt
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
 ```
 
-### 2. Configure API keys
+### 2. Set environment variables (optional)
 
 ```bash
 cp .env.example .env
-# Open .env and fill in your keys:
-#   GOOGLE_API_KEY=...
-#   HF_API_KEY=...
+# Edit .env — all variables are optional for local use
 ```
 
-> **Security note:** API keys entered in the frontend are sent only over HTTPS
-> and are never logged or stored. Keys in `.env` are for server-side defaults;
-> frontend keys override them per-request.
-
-### 3. Start the server
+### 3. Run the server
 
 ```bash
 cd backend
-uvicorn main:app --reload --host 0.0.0.0 --port 8000
+uvicorn main:app --reload --host 0.0.0.0 --port 7860
 ```
 
-Open **http://localhost:8000** in your browser.  
-API docs: **http://localhost:8000/docs**
+Open **http://localhost:7860** in your browser.
 
----
-
-## 🐳 Docker Deployment
+### 4. Run tests
 
 ```bash
-# Build and run
-docker-compose up --build
-
-# Or production detached
-docker-compose up -d
+cd backend
+pytest ../tests/test_promptforge.py -v --asyncio-mode=auto
 ```
 
 ---
 
-## ☁️ Cloud Deployment (Google Cloud Run)
+## Environment Variables
 
-```bash
-# Build container
-gcloud builds submit --tag gcr.io/YOUR_PROJECT/promptforge
-
-# Deploy
-gcloud run deploy promptforge \
-  --image gcr.io/YOUR_PROJECT/promptforge \
-  --platform managed \
-  --region us-central1 \
-  --allow-unauthenticated \
-  --set-env-vars "LOG_DIR=/tmp/logs"
-```
-
-For Cloud Run, set secrets via Secret Manager:
-
-```bash
-gcloud secrets create GOOGLE_API_KEY --data-file=- <<< "your-key"
-gcloud secrets create HF_API_KEY --data-file=- <<< "your-key"
-```
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `7860` | Server port |
+| `LOG_DIR` | `logs` | Directory for JSON persistence files |
+| `HF_API_KEY` | _(empty)_ | Hugging Face API key for AI enhancement |
+| `GOOGLE_API_KEY` | _(empty)_ | Google AI Studio API key |
 
 ---
 
-## 🧪 Running Tests
+## 5-Step Workflow
 
-```bash
-cd backend
-pytest tests/ -v
 ```
-
-Expected output: **19 tests passing**.
+1. INPUT     → Enter your instruction (+ persona, style, constraints)
+2. REVIEW    → Edit any generated field in the manifest
+3. FINALISE  → Approve → ready to copy into Google AI Studio
+4. EXPORT    → Download as JSON or plain text
+5. REFINE    → Describe changes → new version is created
+```
 
 ---
 
-## 📡 API Reference
+## API Reference
 
-### `POST /api/generate`
+### System
 
-```json
-{
-  "instruction": "Generate a TypeScript React component with TailwindCSS and unit tests.",
-  "output_format": "both",
-  "provider": "google",
-  "api_key": "YOUR_KEY_HERE",
-  "enhance": true,
-  "extra_context": "Must support dark mode and be accessible."
-}
-```
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/health` | Liveness check |
+| GET | `/api/config` | Env key status + model defaults |
+| GET | `/api/stats` | Dashboard metrics |
+| POST | `/api/check-key` | Validate HF or Google API key |
 
-**Response:** `GenerateResponse` with full `PromptManifest`.
+### Instruction Settings
 
----
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/api/instructions` | Create setting |
+| GET | `/api/instructions` | List (supports `?tag=`, `?q=`, `?favorites_only=true`) |
+| GET | `/api/instructions/tags` | All tag values |
+| GET | `/api/instructions/export` | Export all as JSON |
+| GET | `/api/instructions/{id}` | Get single setting |
+| PATCH | `/api/instructions/{id}` | Update setting |
+| DELETE | `/api/instructions/{id}` | Delete setting |
+| POST | `/api/instructions/{id}/duplicate` | Clone setting |
+| POST | `/api/instructions/{id}/favorite` | Toggle favourite |
+| POST | `/api/instructions/bulk-delete` | Bulk delete |
 
-### `POST /api/approve`
+### Prompts
 
-```json
-{
-  "prompt_id": "<uuid>",
-  "edits": {
-    "role": "Principal Software Engineer",
-    "constraints": ["Use TypeScript strict mode.", "Tests must use Vitest."]
-  }
-}
-```
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/api/generate` | Generate prompt from instruction |
+| POST | `/api/generate/from-settings` | Generate from saved setting |
+| POST | `/api/generate/batch` | Generate up to 10 at once |
+| GET | `/api/explain/{id}` | Explain prompt structure decisions |
+| POST | `/api/approve` | Approve (+ optional field edits) |
+| POST | `/api/export` | Export approved prompt |
+| POST | `/api/refine` | Refine with feedback → new version |
+| POST | `/api/prompts/{id}/favorite` | Toggle prompt favourite |
+| POST | `/api/prompts/{id}/archive` | Archive prompt |
+| GET | `/api/search?q=…` | Full-text search across prompts |
 
----
+### History
 
-### `POST /api/export`
-
-```json
-{ "prompt_id": "<uuid>", "export_format": "json" }
-```
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/api/history` | List all prompts (supports filters) |
+| GET | `/api/history/{id}` | Get full prompt manifest |
+| DELETE | `/api/history/{id}` | Delete prompt |
+| POST | `/api/history/bulk-delete` | Bulk delete |
 
 ---
 
-### `POST /api/refine`
+## Keyboard Shortcuts
 
-```json
-{
-  "prompt_id": "<uuid>",
-  "feedback": "Add ARIA labels and keyboard navigation support.",
-  "provider": "none"
-}
-```
+| Shortcut | Action |
+|---|---|
+| `⌘↵` / `Ctrl+↵` | Generate prompt |
+| `Alt+B` | Toggle sidebar |
+| `Alt+T` | Toggle light/dark theme |
+| `Alt+1–4` | Navigate between pages |
+| `?` | Show shortcuts panel |
+| `Esc` | Close modal / cancel |
 
 ---
 
-### `GET /api/history`
+## Available Personas
 
-Returns all previously generated prompts with status and version info.
+| Value | Description |
+|---|---|
+| `default` | Auto-detects from instruction keywords |
+| `senior_dev` | Senior full-stack Software Engineer |
+| `data_scientist` | ML / statistics / data pipelines |
+| `tech_writer` | Technical documentation specialist |
+| `product_mgr` | User-centric product management |
+| `security_eng` | OWASP, threat modelling, secure-by-design |
+| `devops_eng` | CI/CD, Kubernetes, cloud-native (**new**) |
+| `ml_engineer` | LLM fine-tuning, MLOps, PEFT (**new**) |
+| `custom` | Any free-text persona |
 
 ---
 
-## 🏗️ Example: Full Prompt Output
+## Cloud Deployment
 
-**Instruction:** `"Generate a TypeScript React component with TailwindCSS and unit tests."`
+### Hugging Face Spaces (Dockerfile)
 
-```
-## ROLE
-You are a Senior Frontend Engineer.
-
-## TASK
-Generate a TypeScript React component with TailwindCSS and unit tests.
-
-## INPUT FORMAT
-A plain-text string describing the user's request or the content to process.
-
-## OUTPUT FORMAT
-Source code inside a properly labeled fenced code block. Include a brief
-explanation before and after the block.
-
-## CONSTRAINTS
-1. Use TypeScript with strict mode enabled.
-2. Use TailwindCSS utility classes exclusively; avoid custom CSS unless unavoidable.
-3. Include comprehensive unit tests with >80% coverage.
-
-## STYLE & TONE
-Professional and clear; balance technical accuracy with readability.
-
-## SAFETY GUIDELINES
-1. Do not produce harmful, misleading, or unethical content.
-2. Respect intellectual property; do not reproduce copyrighted material verbatim.
-3. If the request is ambiguous or potentially harmful, ask for clarification.
-4. Adhere to Google AI Studio usage policies and Responsible AI guidelines.
-
-## FEW-SHOT EXAMPLES
-**Input:** Create a Button component.
-**Output:** ```tsx
-interface ButtonProps { label: string; onClick: () => void; }
-export const Button = ({ label, onClick }: ButtonProps) => (
-  <button onClick={onClick} className='px-4 py-2 bg-blue-600 text-white rounded'>{label}</button>
-);
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY backend/ ./backend/
+COPY frontend/ ./frontend/
+EXPOSE 7860
+CMD ["uvicorn", "backend.main:app", "--host", "0.0.0.0", "--port", "7860"]
 ```
 
----
-*Prompt generated by PromptForge — compatible with Google AI Studio.*
+### Railway / Render / Fly.io
+
+```bash
+# Set start command:
+uvicorn backend.main:app --host 0.0.0.0 --port $PORT
 ```
 
+Set `HF_API_KEY` and/or `GOOGLE_API_KEY` as environment variables in your dashboard.
+
 ---
 
-## 🔐 Security Notes
+## Security Notes
 
-- API keys are accepted per-request and **never persisted** in logs or storage.
-- The `store.py` logs contain instruction text and prompt content but strip API keys.
-- For production: add authentication (e.g., FastAPI `Depends` with Bearer tokens), enforce HTTPS, and set `allow_origins` in CORS middleware to your domain only.
+- API keys entered in the UI are **never logged or persisted** server-side.
+- CORS is open (`*`) by default — restrict `allow_origins` for production.
+- All environment variables are read at startup; no secrets in source code.
+- Input lengths are validated via Pydantic; all outputs are HTML-escaped in the UI.
 
 ---
 
-## 📝 License
+## License
 
-MIT — use freely, modify as needed.
+MIT — use freely, contribute back.

backend/ai_client.py

@@ -1,10 +1,11 @@
 """
-PromptForge — AI client interface.
-Supports optional enhancement via:
-  - Hugging Face Inference API (text-generation models)
-  - Google AI Studio / Gemini API (generateContent)
+PromptForge v4.0 — AI enhancement client.
+Upgrades: exponential-backoff retry, configurable model override,
+          token-budget awareness, structured error types, and a
+          health-check helper for each provider.
 """
 from __future__ import annotations
+import asyncio
 import logging
 from typing import Optional
 
@@ -12,126 +13,188 @@ import httpx
 
 logger = logging.getLogger("promptforge.ai_client")
 
-# ---------------------------------------------------------------------------
-# Hugging Face
-# ---------------------------------------------------------------------------
-
-HF_API_BASE = "https://api-inference.huggingface.co/models"
-HF_DEFAULT_MODEL = "mistralai/Mistral-7B-Instruct-v0.2"
+# ── Defaults ──────────────────────────────────────────────────────────────────
+HF_API_BASE        = "https://api-inference.huggingface.co/models"
+HF_DEFAULT_MODEL   = "mistralai/Mistral-7B-Instruct-v0.2"
+GOOGLE_AI_BASE     = "https://generativelanguage.googleapis.com/v1beta"
+GOOGLE_DEFAULT_MODEL = "gemini-1.5-flash"
 
+_SYSTEM_PROMPT = (
+    "You are an expert prompt engineer specialising in Google AI Studio system prompts. "
+    "Given a draft prompt, improve its clarity, specificity, structure, and effectiveness. "
+    "Preserve all section headers (## ROLE, ## TASK, etc.). "
+    "Return ONLY the improved prompt — no commentary, no preamble, no markdown fences."
+)
+
+
+# ── Retry helper ──────────────────────────────────────────────────────────────
+
+async def _post_with_retry(
+    client: httpx.AsyncClient,
+    url: str,
+    payload: dict,
+    headers: Optional[dict] = None,
+    retries: int = 3,
+    base_delay: float = 1.0,
+) -> httpx.Response:
+    """POST with exponential backoff on 429 / 503 responses."""
+    last_exc: Exception = RuntimeError("No attempts made")
+    for attempt in range(retries):
+        try:
+            resp = await client.post(url, json=payload, headers=headers or {})
+            if resp.status_code in (429, 503):
+                wait = base_delay * (2 ** attempt)
+                logger.warning("Rate-limited (%d) — retrying in %.1fs", resp.status_code, wait)
+                await asyncio.sleep(wait)
+                continue
+            return resp
+        except (httpx.ConnectError, httpx.TimeoutException) as exc:
+            last_exc = exc
+            wait = base_delay * (2 ** attempt)
+            logger.warning("Network error on attempt %d: %s — retrying in %.1fs", attempt + 1, exc, wait)
+            await asyncio.sleep(wait)
+    raise last_exc
+
+
+# ── Hugging Face ──────────────────────────────────────────────────────────────
 
 async def enhance_with_huggingface(
     raw_prompt: str,
     api_key: str,
     model: str = HF_DEFAULT_MODEL,
-    max_new_tokens: int = 512,
+    max_new_tokens: int = 1024,
 ) -> str:
-    """
-    Call the Hugging Face Inference API to enhance a raw prompt text.
-    Returns the enhanced prompt string, or the original on failure.
-    """
-    system_instruction = (
-        "You are an expert prompt engineer specializing in Google AI Studio prompts. "
-        "Given a draft prompt, improve its clarity, specificity, and structure. "
-        "Return ONLY the improved prompt text — no commentary."
-    )
     payload = {
-        "inputs": f"<s>[INST] {system_instruction}\n\nDRAFT PROMPT:\n{raw_prompt}\n\nIMPROVED PROMPT: [/INST]",
-        "parameters": {"max_new_tokens": max_new_tokens, "return_full_text": False},
+        "inputs": (
+            f"<s>[INST] {_SYSTEM_PROMPT}\n\n"
+            f"DRAFT PROMPT:\n{raw_prompt}\n\n"
+            f"IMPROVED PROMPT: [/INST]"
+        ),
+        "parameters": {
+            "max_new_tokens": max_new_tokens,
+            "return_full_text": False,
+            "temperature": 0.3,
+            "repetition_penalty": 1.1,
+        },
     }
     headers = {"Authorization": f"Bearer {api_key}"}
-    url = f"{HF_API_BASE}/{model}"
+    url     = f"{HF_API_BASE}/{model}"
 
     try:
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            resp = await client.post(url, json=payload, headers=headers)
+        async with httpx.AsyncClient(timeout=45.0) as client:
+            resp = await _post_with_retry(client, url, payload, headers)
             resp.raise_for_status()
             data = resp.json()
-            # HF returns a list of dicts with "generated_text"
             if isinstance(data, list) and data:
-                return data[0].get("generated_text", raw_prompt).strip()
+                enhanced = data[0].get("generated_text", "").strip()
+                if enhanced and len(enhanced) > 100:
+                    return enhanced
+            logger.warning("HF returned empty or too-short text; using original.")
             return raw_prompt
     except Exception as exc:
         logger.warning("HuggingFace enhancement failed: %s", exc)
         return raw_prompt
 
 
-# ---------------------------------------------------------------------------
-# Google AI Studio / Gemini
-# ---------------------------------------------------------------------------
-
-GOOGLE_AI_BASE = "https://generativelanguage.googleapis.com/v1beta"
-GOOGLE_DEFAULT_MODEL = "gemini-1.5-flash"
-
+# ── Google Gemini ─────────────────────────────────────────────────────────────
 
 async def enhance_with_google(
     raw_prompt: str,
     api_key: str,
     model: str = GOOGLE_DEFAULT_MODEL,
 ) -> str:
-    """
-    Call the Google Generative Language API (Gemini) to enhance a prompt.
-    Returns the enhanced prompt string, or the original on failure.
-    """
     url = f"{GOOGLE_AI_BASE}/models/{model}:generateContent?key={api_key}"
-    system_part = (
-        "You are an expert prompt engineer. "
-        "Improve the following draft prompt for use in Google AI Studio. "
-        "Return ONLY the improved prompt — no preamble or commentary."
-    )
     payload = {
         "contents": [
             {
                 "parts": [
-                    {"text": f"{system_part}\n\nDRAFT PROMPT:\n{raw_prompt}"}
+                    {"text": f"{_SYSTEM_PROMPT}\n\nDRAFT PROMPT:\n{raw_prompt}"}
                 ]
             }
         ],
-        "generationConfig": {"maxOutputTokens": 1024, "temperature": 0.4},
+        "generationConfig": {
+            "maxOutputTokens": 2048,
+            "temperature": 0.3,
+            "topP": 0.9,
+        },
+        "safetySettings": [
+            {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_ONLY_HIGH"},
+        ],
     }
 
     try:
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            resp = await client.post(url, json=payload)
+        async with httpx.AsyncClient(timeout=45.0) as client:
+            resp = await _post_with_retry(client, url, payload)
             resp.raise_for_status()
             data = resp.json()
             candidates = data.get("candidates", [])
             if candidates:
                 parts = candidates[0].get("content", {}).get("parts", [])
                 if parts:
-                    return parts[0].get("text", raw_prompt).strip()
+                    enhanced = parts[0].get("text", "").strip()
+                    if enhanced and len(enhanced) > 100:
+                        return enhanced
+            logger.warning("Google returned empty or too-short text; using original.")
             return raw_prompt
     except Exception as exc:
         logger.warning("Google AI enhancement failed: %s", exc)
         return raw_prompt
 
 
-# ---------------------------------------------------------------------------
-# Dispatcher
-# ---------------------------------------------------------------------------
+# ── Dispatcher ────────────────────────────────────────────────────────────────
 
 async def enhance_prompt(
     raw_prompt: str,
     provider: str,
     api_key: Optional[str],
+    model_override: Optional[str] = None,
 ) -> tuple[str, str]:
     """
-    Dispatch enhancement to the correct provider.
+    Dispatch to the correct provider.
     Returns (enhanced_text, notes_string).
     """
     if not api_key:
         return raw_prompt, "No API key provided — skipping AI enhancement."
 
     if provider == "huggingface":
-        enhanced = await enhance_with_huggingface(raw_prompt, api_key)
-        notes = f"Enhanced via Hugging Face ({HF_DEFAULT_MODEL})."
+        model    = model_override or HF_DEFAULT_MODEL
+        enhanced = await enhance_with_huggingface(raw_prompt, api_key, model=model)
+        notes    = f"Enhanced via Hugging Face ({model})."
     elif provider == "google":
-        enhanced = await enhance_with_google(raw_prompt, api_key)
-        notes = f"Enhanced via Google Gemini ({GOOGLE_DEFAULT_MODEL})."
+        model    = model_override or GOOGLE_DEFAULT_MODEL
+        enhanced = await enhance_with_google(raw_prompt, api_key, model=model)
+        notes    = f"Enhanced via Google Gemini ({model})."
     else:
-        return raw_prompt, "Provider 'none' selected — no enhancement applied."
+        return raw_prompt, "Provider 'none' — no AI enhancement applied."
 
     if enhanced == raw_prompt:
-        notes += " (Enhancement returned unchanged text — possible API issue.)"
+        notes += " (Enhancement returned identical text — possible model or quota issue.)"
 
     return enhanced, notes
+
+
+# ── Provider health-check ─────────────────────────────────────────────────────
+
+async def check_hf_key(api_key: str) -> bool:
+    """Return True if the HF key appears valid (quick whoami probe)."""
+    try:
+        async with httpx.AsyncClient(timeout=8.0) as client:
+            r = await client.get(
+                "https://huggingface.co/api/whoami",
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+            return r.status_code == 200
+    except Exception:
+        return False
+
+
+async def check_google_key(api_key: str) -> bool:
+    """Return True if the Google key appears valid (list models probe)."""
+    try:
+        async with httpx.AsyncClient(timeout=8.0) as client:
+            r = await client.get(
+                f"{GOOGLE_AI_BASE}/models?key={api_key}"
+            )
+            return r.status_code == 200
+    except Exception:
+        return False

backend/client.js

@@ -0,0 +1,926 @@
+/**
+ * PromptForge v4.0 — client.js
+ * Upgrades: sidebar navigation, stats dashboard, full-text search,
+ * favorites/archive, setting duplicate, keyboard shortcuts, theme toggle,
+ * API key validation, char counters, tag suggestions, smooth transitions.
+ */
+
+const API = "";
+let currentPromptId = null;
+let allSettings     = [];
+let favoritesFilter = false;
+
+const $ = id => document.getElementById(id);
+const esc = s => String(s ?? "").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
+const show = el => el?.classList.remove("hidden");
+const hide = el => el?.classList.add("hidden");
+
+/* ── API fetch ──────────────────────────────────────────────────────── */
+async function apiFetch(path, method = "GET", body = null) {
+  const opts = { method, headers: { "Content-Type": "application/json" } };
+  if (body) opts.body = JSON.stringify(body);
+  const r = await fetch(API + path, opts);
+  if (!r.ok) {
+    const e = await r.json().catch(() => ({ detail: r.statusText }));
+    throw new Error(e.detail || "Request failed");
+  }
+  return r.json();
+}
+
+/* ── Toast ──────────────────────────────────────────────────────────── */
+function toast(msg, type = "info", duration = 4200) {
+  const icons = { success:"✅", error:"❌", info:"💡", warn:"⚠️" };
+  const t = document.createElement("div");
+  t.className = `toast ${type}`;
+  t.innerHTML = `<span class="toast-icon">${icons[type]||"💡"}</span><span>${msg}</span>`;
+  $("toast-container").appendChild(t);
+  const remove = () => { t.classList.add("leaving"); t.addEventListener("animationend", () => t.remove(), {once:true}); };
+  const timer = setTimeout(remove, duration);
+  t.addEventListener("click", () => { clearTimeout(timer); remove(); });
+}
+
+/* ── Loading state ──────────────────────────────────────────────────── */
+function setLoading(btn, on) {
+  if (!btn) return;
+  btn.disabled = on;
+  if (!btn._orig) btn._orig = btn.innerHTML;
+  btn.innerHTML = on ? `<span class="spinner"></span> Working…` : btn._orig;
+}
+
+/* ── Sidebar navigation ─────────────────────────────────────────────── */
+document.querySelectorAll(".nav-item").forEach(item => {
+  item.addEventListener("click", () => {
+    document.querySelectorAll(".nav-item").forEach(n => n.classList.remove("active"));
+    document.querySelectorAll(".page").forEach(p => { p.classList.remove("active"); hide(p); });
+    item.classList.add("active");
+    const page = $(`page-${item.dataset.page}`);
+    if (page) { show(page); page.classList.add("active"); }
+    // lazy-load data
+    if (item.dataset.page === "settings") loadSettingsList();
+    if (item.dataset.page === "history")  loadHistory();
+    if (item.dataset.page === "stats")    loadStats();
+  });
+});
+
+/* ── Sidebar collapse ───────────────────────────────────────────────── */
+$("btn-sidebar-toggle")?.addEventListener("click", () => {
+  const sb = $("sidebar");
+  sb.classList.toggle("collapsed");
+  localStorage.setItem("pf_sidebar", sb.classList.contains("collapsed") ? "1" : "0");
+});
+if (localStorage.getItem("pf_sidebar") === "1") $("sidebar")?.classList.add("collapsed");
+
+/* ── Theme toggle ───────────────────────────────────────────────────── */
+function applyTheme(theme) {
+  document.documentElement.dataset.theme = theme;
+  $("btn-theme").textContent = theme === "dark" ? "🌙" : "☀️";
+  localStorage.setItem("pf_theme", theme);
+}
+$("btn-theme")?.addEventListener("click", () => {
+  const cur = document.documentElement.dataset.theme || "dark";
+  applyTheme(cur === "dark" ? "light" : "dark");
+});
+applyTheme(localStorage.getItem("pf_theme") || "dark");
+
+/* ── Keyboard shortcuts ─────────────────────────────────────────────── */
+$("btn-shortcuts")?.addEventListener("click", () => show($("shortcuts-modal")));
+$("btn-shortcuts-close")?.addEventListener("click", () => hide($("shortcuts-modal")));
+$("shortcuts-modal")?.addEventListener("click", e => { if (e.target === $("shortcuts-modal")) hide($("shortcuts-modal")); });
+
+document.addEventListener("keydown", e => {
+  if (e.altKey) {
+    if (e.key === "b" || e.key === "B") { $("sidebar")?.classList.toggle("collapsed"); return; }
+    if (e.key === "t" || e.key === "T") { applyTheme(document.documentElement.dataset.theme === "dark" ? "light" : "dark"); return; }
+    if (e.key === "1") { document.querySelector('[data-page="generate"]')?.click(); return; }
+    if (e.key === "2") { document.querySelector('[data-page="settings"]')?.click(); return; }
+    if (e.key === "3") { document.querySelector('[data-page="history"]')?.click(); return; }
+    if (e.key === "4") { document.querySelector('[data-page="stats"]')?.click(); return; }
+  }
+  if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
+    if ($("page-generate")?.classList.contains("active")) $("btn-generate")?.click();
+    return;
+  }
+  if (e.key === "?" && !["INPUT","TEXTAREA","SELECT"].includes(e.target.tagName)) {
+    show($("shortcuts-modal")); return;
+  }
+  if (e.key === "Escape") {
+    hide($("modal-overlay")); hide($("shortcuts-modal"));
+  }
+});
+
+/* ── Config / env ───────────────────────────────────────────────────── */
+async function loadConfig() {
+  try {
+    const cfg = await apiFetch("/api/config");
+    const dotHF  = $("dot-hf");
+    const dotGG  = $("dot-google");
+    if (cfg.hf_key_set)     dotHF?.classList.add("active");
+    if (cfg.google_key_set) dotGG?.classList.add("active");
+  } catch {}
+}
+
+/* ── API key panel ──────────────────────────────────────────────────── */
+const PROVIDER_INFO = {
+  none:        { hint:"No key needed — local engine only", placeholder:"Not required" },
+  google:      { hint:"google.com/aistudio → Get API key", placeholder:"AIzaSy…" },
+  huggingface: { hint:"huggingface.co/settings/tokens",    placeholder:"hf_…" },
+};
+
+$("btn-api-panel-toggle")?.addEventListener("click", () => {
+  const body    = $("api-panel-body");
+  const chevron = $("api-chevron");
+  body.classList.toggle("open");
+  chevron.classList.toggle("open");
+});
+
+$("provider")?.addEventListener("change", () => {
+  const p = $("provider").value;
+  const info = PROVIDER_INFO[p] || PROVIDER_INFO.none;
+  $("key-hint").textContent = info.hint;
+  const needsKey = p !== "none";
+  $("api-key").disabled    = !needsKey;
+  $("api-key").placeholder = info.placeholder;
+  $("btn-check-key").disabled = !needsKey;
+  $("model-field").style.display = needsKey ? "block" : "none";
+  $("api-panel-status").textContent = needsKey ? "AI Enhancement Available" : "Local Engine Active";
+  if (!needsKey) {
+    $("api-key").value = "";
+    $("key-dot").className = "status-dot";
+    $("key-status-text").textContent = "No key needed";
+  }
+});
+
+$("api-key")?.addEventListener("input", () => {
+  const has = $("api-key").value.trim().length >= 10;
+  $("key-dot").className = "status-dot" + (has ? " ok" : "");
+  $("key-status-text").textContent = has ? "Key entered — click ✓ to validate" : "Enter your API key";
+});
+
+$("btn-toggle-key")?.addEventListener("click", () => {
+  const k = $("api-key");
+  k.type = k.type === "password" ? "text" : "password";
+  $("btn-toggle-key").textContent = k.type === "password" ? "👁" : "🙈";
+});
+
+$("btn-check-key")?.addEventListener("click", async () => {
+  const provider = $("provider").value;
+  const key = $("api-key").value.trim();
+  if (!key) { toast("Enter a key first.", "warn"); return; }
+  const btn = $("btn-check-key");
+  setLoading(btn, true);
+  try {
+    const res = await apiFetch("/api/check-key", "POST", { provider, api_key: key });
+    $("key-dot").className = "status-dot " + (res.valid ? "ok" : "err");
+    $("key-status-text").textContent = res.message;
+    toast(res.message, res.valid ? "success" : "error");
+    if (res.valid) { $("dot-" + (provider === "google" ? "google" : "hf"))?.classList.add("active"); }
+  } catch (e) { toast(`Key check failed: ${e.message}`, "error"); }
+  finally { setLoading(btn, false); }
+});
+
+/* ── Character counters ─────────────────────────────────────────────── */
+function bindCharCounter(textareaId, counterId, max) {
+  const ta = $(textareaId), ct = $(counterId);
+  if (!ta || !ct) return;
+  ta.addEventListener("input", () => {
+    const len = ta.value.length;
+    ct.textContent = len;
+    ct.parentElement.className = "char-counter" + (len > max * .95 ? " over" : len > max * .85 ? " warn" : "");
+  });
+}
+bindCharCounter("instruction", "instr-count", 8000);
+bindCharCounter("s-instruction", "s-instr-count", 8000);
+
+/* ── Persona / custom persona ───────────────────────────────────────── */
+$("gen-persona")?.addEventListener("change", () => {
+  $("custom-persona-field").style.display = $("gen-persona").value === "custom" ? "block" : "none";
+});
+$("s-persona")?.addEventListener("change", () => {
+  $("s-custom-persona-field").style.display = $("s-persona").value === "custom" ? "block" : "none";
+});
+
+/* ── Tag autocomplete for settings form ──────��──────────────────────── */
+const COMMON_TAGS = ["react","typescript","python","frontend","backend","devops","ml","security","testing","database","mobile","writing","docker","api","fastapi","tailwind"];
+function renderTagSugs(inputEl, containerEl) {
+  const cur = inputEl.value.split(",").map(t=>t.trim()).filter(Boolean);
+  const avail = COMMON_TAGS.filter(t => !cur.includes(t));
+  containerEl.innerHTML = avail.slice(0,8).map(t =>
+    `<span class="tag-sug" data-tag="${esc(t)}">${esc(t)}</span>`
+  ).join("");
+  containerEl.querySelectorAll(".tag-sug").forEach(el => {
+    el.addEventListener("click", () => {
+      const existing = inputEl.value.trim();
+      inputEl.value = existing ? `${existing}, ${el.dataset.tag}` : el.dataset.tag;
+      renderTagSugs(inputEl, containerEl);
+    });
+  });
+}
+const tagsInput = $("s-tags"), tagSugs = $("tag-suggestions");
+if (tagsInput && tagSugs) {
+  tagsInput.addEventListener("input", () => renderTagSugs(tagsInput, tagSugs));
+  renderTagSugs(tagsInput, tagSugs);
+}
+
+/* ── Step progress ──────────────────────────────────────────────────── */
+function setStep(n) {
+  document.querySelectorAll(".step").forEach((s, i) => {
+    const idx = parseInt(s.dataset.step);
+    s.classList.remove("active","done");
+    if (idx < n) s.classList.add("done");
+    if (idx === n) s.classList.add("active");
+  });
+  document.querySelectorAll(".step-line").forEach((l, i) => {
+    l.classList.toggle("filled", i + 1 < n);
+  });
+}
+
+/* ── Copy buttons ───────────────────────────────────────────────────── */
+document.addEventListener("click", e => {
+  const btn = e.target.closest(".copy-btn");
+  if (!btn) return;
+  const el = $(btn.dataset.target);
+  if (!el) return;
+  navigator.clipboard.writeText(el.textContent).then(() => {
+    const orig = btn.textContent;
+    btn.textContent = "✅ Copied!";
+    btn.classList.add("copied");
+    setTimeout(() => { btn.classList.remove("copied"); btn.textContent = orig; }, 2000);
+  });
+});
+
+/* ─────────────────────────────────────────────────────────────────────
+   GENERATE PAGE
+───────────────────────────────────────────────────────────────────── */
+
+/* ── STEP 1: Generate ─── */
+$("btn-generate")?.addEventListener("click", doGenerate);
+
+async function doGenerate() {
+  const instruction = $("instruction").value.trim();
+  if (instruction.length < 5) { toast("Enter a meaningful instruction (min 5 chars).", "error"); return; }
+  const btn = $("btn-generate");
+  setLoading(btn, true);
+  try {
+    const provider    = $("provider").value;
+    const apiKey      = $("api-key")?.value.trim() || null;
+    const persona     = $("gen-persona")?.value || "default";
+    const style       = $("gen-style")?.value || "professional";
+    const customPerso = persona === "custom" ? ($("gen-custom-persona")?.value.trim() || null) : null;
+    const constrRaw   = $("gen-constraints")?.value.trim() || "";
+    const constraints = constrRaw ? constrRaw.split("\n").map(s=>s.trim()).filter(Boolean) : [];
+    const modelOvr    = $("provider-model")?.value.trim() || null;
+
+    const data = await apiFetch("/api/generate", "POST", {
+      instruction,
+      output_format: "both",
+      provider, api_key: apiKey,
+      enhance: provider !== "none" && !!apiKey,
+      extra_context: $("extra-context").value.trim() || null,
+      persona, custom_persona: customPerso, style,
+      user_constraints: constraints,
+      provider_model: modelOvr || undefined,
+    });
+    currentPromptId = data.prompt_id;
+    renderManifest(data.manifest);
+    hide($("step-input")); show($("step-manifest"));
+    $("step-manifest").scrollIntoView({ behavior:"smooth", block:"start" });
+    setStep(2);
+    updateBadge("history-badge", null, +1);
+    toast("Manifest generated — review and approve.", "success");
+  } catch (e) { toast(`Error: ${e.message}`, "error"); }
+  finally { setLoading(btn, false); }
+}
+
+/* ── Render manifest fields ─── */
+function renderManifest(manifest) {
+  const sp   = manifest.structured_prompt;
+  const grid = $("manifest-grid");
+  grid.innerHTML = "";
+  const fields = [
+    { key:"role",          label:"Role",          value:sp.role,                   full:false },
+    { key:"style",         label:"Style & Tone",  value:sp.style,                  full:false },
+    { key:"task",          label:"Task",          value:sp.task,                   full:true  },
+    { key:"input_format",  label:"Input Format",  value:sp.input_format,           full:false },
+    { key:"output_format", label:"Output Format", value:sp.output_format,          full:false },
+    { key:"constraints",   label:"Constraints",   value:sp.constraints.join("\n"), full:true  },
+    { key:"safety",        label:"Safety",        value:sp.safety.join("\n"),      full:true  },
+  ];
+  fields.forEach(f => {
+    const d = document.createElement("div");
+    d.className = `manifest-field${f.full?" full":""}`;
+    d.innerHTML = `<label>${esc(f.label)}</label>
+      <textarea id="field-${f.key}" rows="${f.full?3:2}">${esc(f.value)}</textarea>`;
+    grid.appendChild(d);
+  });
+  $("manifest-json").textContent = JSON.stringify(manifest, null, 2);
+  hide($("explanation-panel"));
+
+  // Word count badge
+  const wc = sp.word_count || sp.raw_prompt_text?.split(/\s+/).length || 0;
+  if (!$("wc-badge")) {
+    const b = document.createElement("span");
+    b.id = "wc-badge"; b.className = "step-tag";
+    b.style.marginLeft = "auto";
+    $("step-manifest")?.querySelector(".panel-header")?.appendChild(b);
+  }
+  $("wc-badge").textContent = `~${wc} words`;
+}
+
+/* ── Explain ─── */
+$("btn-explain")?.addEventListener("click", async () => {
+  if (!currentPromptId) return;
+  const btn = $("btn-explain");
+  setLoading(btn, true);
+  try {
+    const data = await apiFetch(`/api/explain/${currentPromptId}`);
+    $("explanation-text").textContent = data.explanation;
+    $("key-decisions").innerHTML = data.key_decisions
+      .map(d => `<div class="decision-chip">${esc(d)}</div>`).join("");
+    const panel = $("explanation-panel");
+    show(panel);
+    panel.scrollIntoView({ behavior:"smooth", block:"nearest" });
+  } catch (e) { toast(`Explanation error: ${e.message}`, "warn"); }
+  finally { setLoading(btn, false); }
+});
+
+/* ── Approve ─── */
+$("btn-approve")?.addEventListener("click", async () => {
+  if (!currentPromptId) return;
+  const edits = {};
+  ["role","style","task","input_format","output_format"].forEach(k => {
+    const el = $(`field-${k}`); if (el) edits[k] = el.value.trim();
+  });
+  const cEl = $("field-constraints"); if (cEl) edits.constraints = cEl.value.trim().split("\n").filter(Boolean);
+  const sEl = $("field-safety");      if (sEl) edits.safety      = sEl.value.trim().split("\n").filter(Boolean);
+  const btn = $("btn-approve");
+  setLoading(btn, true);
+  try {
+    const data = await apiFetch("/api/approve", "POST", { prompt_id: currentPromptId, edits });
+    renderFinalized(data.finalized_prompt);
+    hide($("step-manifest")); show($("step-finalized"));
+    $("step-finalized").scrollIntoView({ behavior:"smooth", block:"start" });
+    setStep(3);
+    toast("Prompt approved! 🎉", "success");
+  } catch (e) { toast(`Approval failed: ${e.message}`, "error"); }
+  finally { setLoading(btn, false); }
+});
+
+function renderFinalized(sp) {
+  $("finalized-text").textContent = sp.raw_prompt_text;
+  $("finalized-json").textContent = JSON.stringify(sp, null, 2);
+}
+
+/* ── Inner tabs (text/json) ─── */
+document.querySelectorAll(".inner-tab").forEach(tab => {
+  tab.addEventListener("click", () => {
+    const group = tab.closest(".panel");
+    group.querySelectorAll(".inner-tab").forEach(t => t.classList.remove("active"));
+    group.querySelectorAll(".inner-panel").forEach(p => hide(p));
+    tab.classList.add("active");
+    const panel = group.querySelector(`#itab-${tab.dataset.tab}`);
+    if (panel) show(panel);
+  });
+});
+
+/* ── Export ─── */
+async function doExport(format) {
+  if (!currentPromptId) return;
+  try {
+    const data = await apiFetch("/api/export", "POST", { prompt_id: currentPromptId, export_format: format });
+    const content = format === "json" ? JSON.stringify(data.data, null, 2) : String(data.data);
+    const blob = new Blob([content], { type: format === "json" ? "application/json" : "text/plain" });
+    const a = Object.assign(document.createElement("a"), {
+      href: URL.createObjectURL(blob),
+      download: `prompt-${currentPromptId.slice(0,8)}.${format === "json" ? "json" : "txt"}`,
+    });
+    a.click(); URL.revokeObjectURL(a.href);
+    setStep(4);
+    toast(`Exported as ${format.toUpperCase()}!`, "success");
+  } catch (e) { toast(`Export failed: ${e.message}`, "error"); }
+}
+$("btn-export-json")?.addEventListener("click", () => doExport("json"));
+$("btn-export-txt")?.addEventListener("click",  () => doExport("text"));
+
+/* ── Favourite prompt ─── */
+$("btn-favorite-prompt")?.addEventListener("click", async () => {
+  if (!currentPromptId) return;
+  try {
+    const r = await apiFetch(`/api/prompts/${currentPromptId}/favorite`, "POST");
+    $("btn-favorite-prompt").textContent = r.is_favorite ? "★ Favourited" : "☆ Favourite";
+    toast(r.is_favorite ? "Added to favourites ★" : "Removed from favourites", "info");
+  } catch (e) { toast("Failed: " + e.message, "error"); }
+});
+
+/* ── Save as Setting ─── */
+$("btn-save-as-setting")?.addEventListener("click", () => {
+  const instruction = $("instruction")?.value.trim() || "";
+  const context     = $("extra-context")?.value.trim() || "";
+  document.querySelector('[data-page="settings"]')?.click();
+  setTimeout(() => {
+    clearSettingsForm();
+    if ($("s-title"))        $("s-title").value       = instruction.slice(0,60) + (instruction.length > 60 ? "…" : "");
+    if ($("s-instruction"))  $("s-instruction").value  = instruction;
+    if ($("s-extra-context")) $("s-extra-context").value = context;
+    $("s-title")?.focus();
+    toast("Pre-filled from prompt — adjust title and save!", "info");
+  }, 150);
+});
+
+/* ── Refine ─── */
+$("btn-refine")?.addEventListener("click", () => {
+  hide($("step-finalized")); show($("step-refine"));
+  $("step-refine").scrollIntoView({ behavior:"smooth", block:"start" });
+  setStep(5);
+});
+$("btn-cancel-refine")?.addEventListener("click", () => {
+  hide($("step-refine")); show($("step-finalized")); setStep(3);
+});
+$("btn-submit-refine")?.addEventListener("click", async () => {
+  const feedback = $("feedback").value.trim();
+  if (!feedback) { toast("Describe what to change.", "error"); return; }
+  const btn = $("btn-submit-refine");
+  setLoading(btn, true);
+  try {
+    const data = await apiFetch("/api/refine", "POST", {
+      prompt_id: currentPromptId, feedback,
+      provider: $("provider").value,
+      api_key:  $("api-key")?.value.trim() || null,
+    });
+    currentPromptId = data.prompt_id;
+    renderManifest(data.manifest);
+    hide($("step-refine")); show($("step-manifest"));
+    $("step-manifest").scrollIntoView({ behavior:"smooth", block:"start" });
+    setStep(2);
+    toast(`Refined to v${data.manifest.version} — review and approve!`, "success");
+  } catch (e) { toast(`Refinement failed: ${e.message}`, "error"); }
+  finally { setLoading(btn, false); }
+});
+
+/* ── Reset / New ─── */
+$("btn-reset")?.addEventListener("click", () => {
+  hide($("step-manifest")); show($("step-input")); setStep(1);
+  $("instruction").value = ""; $("extra-context").value = "";
+  currentPromptId = null; toast("Reset.", "info");
+});
+$("btn-new")?.addEventListener("click", () => {
+  hide($("step-finalized")); show($("step-input")); setStep(1);
+  $("instruction").value = ""; $("extra-context").value = "";
+  $("instr-count").textContent = "0";
+  currentPromptId = null;
+  $("step-input").scrollIntoView({ behavior:"smooth", block:"start" });
+});
+
+/* ── Load-from-settings modal ─── */
+$("btn-load-from-settings")?.addEventListener("click", async () => {
+  await loadSettingsForModal();
+  show($("modal-overlay"));
+});
+$("btn-modal-close")?.addEventListener("click", () => hide($("modal-overlay")));
+$("modal-overlay")?.addEventListener("click", e => { if (e.target === $("modal-overlay")) hide($("modal-overlay")); });
+$("modal-search")?.addEventListener("input", () => {
+  const q = $("modal-search").value.toLowerCase();
+  document.querySelectorAll(".modal-item").forEach(item => {
+    item.style.display = item.dataset.search?.includes(q) ? "" : "none";
+  });
+});
+
+async function loadSettingsForModal() {
+  const list = $("modal-list");
+  try {
+    const data = await apiFetch("/api/instructions");
+    if (!data.items?.length) {
+      list.innerHTML = `<div class="modal-empty">No saved settings. Create some in the Settings page.</div>`;
+      return;
+    }
+    list.innerHTML = data.items.map(s => `
+      <div class="modal-item" data-id="${esc(s.settings_id)}" data-search="${esc((s.title+s.instruction).toLowerCase())}">
+        <div class="modal-item-title">${personaEmoji(s.persona)} ${esc(s.title)}</div>
+        <div class="modal-item-desc">${esc(s.instruction.slice(0,110))}${s.instruction.length > 110 ? "…" : ""}</div>
+      </div>`).join("");
+    document.querySelectorAll(".modal-item").forEach(item => {
+      item.addEventListener("click", async () => {
+        hide($("modal-overlay"));
+        await generateFromSetting(item.dataset.id);
+      });
+    });
+  } catch (e) {
+    list.innerHTML = `<div class="modal-empty">Failed: ${esc(e.message)}</div>`;
+  }
+}
+
+async function generateFromSetting(sid) {
+  const btn = $("btn-generate");
+  setLoading(btn, true);
+  document.querySelector('[data-page="generate"]')?.click();
+  try {
+    const apiKey = $("api-key")?.value.trim() || null;
+    const data = await apiFetch("/api/generate/from-settings", "POST", { settings_id: sid, api_key: apiKey });
+    currentPromptId = data.prompt_id;
+    renderManifest(data.manifest);
+    hide($("step-input")); show($("step-manifest"));
+    $("step-manifest").scrollIntoView({ behavior:"smooth", block:"start" });
+    setStep(2);
+    updateBadge("history-badge", null, +1);
+    toast(`Generated from saved setting! ✨`, "success");
+  } catch (e) { toast(`Error: ${e.message}`, "error"); }
+  finally { setLoading(btn, false); }
+}
+
+/* ─────────────────────────────────────────────────────────────────────
+   SETTINGS PAGE
+────────────────────────���──────────────────────────────────────────── */
+
+$("btn-settings-save")?.addEventListener("click", async () => {
+  const title       = $("s-title").value.trim();
+  const instruction = $("s-instruction").value.trim();
+  if (!title)                  { toast("Title is required.", "error");   $("s-title").focus(); return; }
+  if (instruction.length < 5)  { toast("Instruction too short.", "error"); $("s-instruction").focus(); return; }
+
+  const editId = $("edit-settings-id").value;
+  const persona = $("s-persona").value;
+  const constraints = ($("s-constraints").value.trim() || "").split("\n").map(s=>s.trim()).filter(Boolean);
+  const tags = ($("s-tags").value.trim() || "").split(",").map(s=>s.trim().toLowerCase()).filter(Boolean);
+
+  const payload = {
+    title,
+    description:    $("s-description").value.trim() || null,
+    instruction,
+    extra_context:  $("s-extra-context")?.value.trim() || null,
+    output_format:  $("s-output-format").value,
+    persona,
+    custom_persona: persona === "custom" ? ($("s-custom-persona")?.value.trim() || null) : null,
+    style:          $("s-style").value,
+    constraints, tags,
+    provider:    $("s-provider").value,
+    enhance:     $("s-enhance")?.checked || false,
+    is_favorite: $("s-favorite")?.checked || false,
+  };
+
+  const btn = $("btn-settings-save");
+  setLoading(btn, true);
+  try {
+    if (editId) {
+      await apiFetch(`/api/instructions/${editId}`, "PATCH", payload);
+      toast("Setting updated! ✅", "success");
+    } else {
+      await apiFetch("/api/instructions", "POST", payload);
+      toast("Setting saved! 💾", "success");
+    }
+    clearSettingsForm();
+    await loadSettingsList();
+  } catch (e) { toast(`Save failed: ${e.message}`, "error"); }
+  finally { setLoading(btn, false); }
+});
+
+$("btn-settings-clear")?.addEventListener("click", clearSettingsForm);
+
+$("btn-export-all-settings")?.addEventListener("click", async () => {
+  try {
+    const data = await apiFetch("/api/instructions/export");
+    const blob = new Blob([JSON.stringify(data, null, 2)], { type:"application/json" });
+    const a = Object.assign(document.createElement("a"), {
+      href: URL.createObjectURL(blob), download: "promptforge-settings.json"
+    });
+    a.click(); URL.revokeObjectURL(a.href);
+    toast(`Exported ${data.total} settings.`, "success");
+  } catch (e) { toast("Export failed: " + e.message, "error"); }
+});
+
+function clearSettingsForm() {
+  $("edit-settings-id").value = "";
+  ["s-title","s-description","s-instruction","s-extra-context","s-constraints","s-tags","s-custom-persona"].forEach(id => {
+    const el = $(id); if (el) el.value = "";
+  });
+  $("s-persona").value = "default";
+  $("s-style").value = "professional";
+  $("s-output-format").value = "both";
+  $("s-provider").value = "none";
+  if ($("s-enhance"))   $("s-enhance").checked = false;
+  if ($("s-favorite"))  $("s-favorite").checked = false;
+  if ($("s-custom-persona-field")) $("s-custom-persona-field").style.display = "none";
+  if ($("s-instr-count")) $("s-instr-count").textContent = "0";
+  if ($("settings-form-title")) $("settings-form-title").textContent = "➕ New Setting";
+  const genBtn = $("btn-settings-generate");
+  if (genBtn) { genBtn.classList.add("hidden"); genBtn._orig = null; }
+  document.querySelectorAll(".setting-card").forEach(c => c.classList.remove("editing"));
+  // reset tag suggestions
+  if (tagsInput && tagSugs) renderTagSugs(tagsInput, tagSugs);
+}
+
+/* ── Load settings list ─── */
+async function loadSettingsList() {
+  try {
+    const q   = $("settings-search")?.value.trim() || "";
+    const tag = $("settings-filter-tag")?.value || "";
+    let url = "/api/instructions?";
+    if (q)   url += `q=${encodeURIComponent(q)}&`;
+    if (tag) url += `tag=${encodeURIComponent(tag)}&`;
+    if (favoritesFilter) url += "favorites_only=true&";
+
+    const data = await apiFetch(url);
+    allSettings = data.items || [];
+    renderSettingsList(allSettings);
+    const n = data.total || 0;
+    if ($("settings-total-count")) $("settings-total-count").textContent = n;
+    if ($("settings-badge"))       $("settings-badge").textContent       = n;
+
+    // refresh tag filter
+    const tagData = await apiFetch("/api/instructions/tags");
+    const filterEl = $("settings-filter-tag");
+    if (filterEl) {
+      const cur = filterEl.value;
+      filterEl.innerHTML = `<option value="">All tags</option>` +
+        tagData.tags.map(t => `<option value="${esc(t)}" ${t===cur?"selected":""}>${esc(t)}</option>`).join("");
+    }
+  } catch (e) { toast(`Failed to load settings: ${e.message}`, "error"); }
+}
+
+function renderSettingsList(items) {
+  const container = $("settings-list");
+  if (!items.length) {
+    container.innerHTML = `<div class="empty-state"><div class="empty-icon">📋</div><p>No settings yet.</p></div>`;
+    return;
+  }
+  container.innerHTML = items.map(s => `
+    <div class="setting-card${s.is_favorite?" favorite":""}${$("edit-settings-id").value===s.settings_id?" editing":""}"
+      data-id="${esc(s.settings_id)}">
+      <div class="setting-card-top">
+        <div class="setting-card-title">${personaEmoji(s.persona)} ${esc(s.title)}</div>
+        <span class="s-star">${s.is_favorite?"★":"☆"}</span>
+      </div>
+      ${s.description ? `<div class="setting-card-desc">${esc(s.description)}</div>` : ""}
+      <div class="setting-card-meta">
+        ${(s.tags||[]).slice(0,4).map(t=>`<span class="tag-chip">${esc(t)}</span>`).join("")}
+        <span class="tag-chip style-tag">${esc(s.style)}</span>
+        <span class="use-count">× ${s.use_count||0}</span>
+      </div>
+      <div class="setting-card-actions">
+        <button class="icon-btn" title="Edit" onclick="editSetting('${esc(s.settings_id)}')">✏️</button>
+        <button class="icon-btn" title="Duplicate" onclick="duplicateSetting('${esc(s.settings_id)}')">⧉</button>
+        <button class="icon-btn" title="Favourite" onclick="toggleSettingFav('${esc(s.settings_id)}')">☆</button>
+        <button class="icon-btn btn-danger" title="Delete" onclick="deleteSetting('${esc(s.settings_id)}')">🗑</button>
+        <button class="btn-primary btn-sm" onclick="generateFromSetting('${esc(s.settings_id)}')">⚡</button>
+      </div>
+    </div>`).join("");
+}
+
+/* ── Search / filter ─── */
+let settingsSearchTimer;
+$("settings-search")?.addEventListener("input", () => {
+  clearTimeout(settingsSearchTimer);
+  settingsSearchTimer = setTimeout(loadSettingsList, 250);
+});
+$("settings-filter-tag")?.addEventListener("change", loadSettingsList);
+$("btn-filter-favorites")?.addEventListener("click", () => {
+  favoritesFilter = !favoritesFilter;
+  $("btn-filter-favorites").textContent = favoritesFilter ? "★" : "☆";
+  $("btn-filter-favorites").style.color = favoritesFilter ? "var(--amber)" : "";
+  loadSettingsList();
+});
+
+/* ── Edit setting ─── */
+async function editSetting(sid) {
+  try {
+    const s = await apiFetch(`/api/instructions/${sid}`);
+    $("edit-settings-id").value = s.settings_id;
+    $("s-title").value        = s.title;
+    $("s-description").value  = s.description || "";
+    $("s-instruction").value  = s.instruction;
+    $("s-instruction").dispatchEvent(new Event("input"));
+    $("s-extra-context").value = s.extra_context || "";
+    $("s-output-format").value = s.output_format;
+    $("s-persona").value      = s.persona;
+    $("s-persona").dispatchEvent(new Event("change"));
+    $("s-custom-persona").value = s.custom_persona || "";
+    $("s-style").value        = s.style;
+    $("s-constraints").value  = (s.constraints || []).join("\n");
+    $("s-tags").value         = (s.tags || []).join(", ");
+    $("s-provider").value     = s.provider;
+    if ($("s-enhance"))  $("s-enhance").checked  = s.enhance;
+    if ($("s-favorite")) $("s-favorite").checked = s.is_favorite;
+    if ($("settings-form-title")) $("settings-form-title").textContent = `✏️ Edit: ${s.title}`;
+    const genBtn = $("btn-settings-generate");
+    if (genBtn) { genBtn.classList.remove("hidden"); genBtn._orig = null; }
+    document.querySelectorAll(".setting-card").forEach(c => c.classList.toggle("editing", c.dataset.id === sid));
+    // scroll form into view
+    document.querySelector(".settings-form-col")?.scrollIntoView({ behavior:"smooth", block:"start" });
+    renderTagSugs($("s-tags"), $("tag-suggestions"));
+  } catch (e) { toast(`Failed to load setting: ${e.message}`, "error"); }
+}
+window.editSetting = editSetting;
+
+/* ── Duplicate setting ─── */
+async function duplicateSetting(sid) {
+  try {
+    const s = await apiFetch(`/api/instructions/${sid}/duplicate`, "POST");
+    toast(`Duplicated → "${s.title}"`, "success");
+    await loadSettingsList();
+  } catch (e) { toast("Duplicate failed: " + e.message, "error"); }
+}
+window.duplicateSetting = duplicateSetting;
+
+/* ── Toggle favourite ─── */
+async function toggleSettingFav(sid) {
+  try {
+    const r = await apiFetch(`/api/instructions/${sid}/favorite`, "POST");
+    toast(r.is_favorite ? "Added to favourites ★" : "Removed from favourites", "info");
+    await loadSettingsList();
+  } catch (e) { toast("Failed: " + e.message, "error"); }
+}
+window.toggleSettingFav = toggleSettingFav;
+
+/* ── Delete setting ─── */
+async function deleteSetting(sid) {
+  if (!confirm("Delete this instruction setting? This cannot be undone.")) return;
+  try {
+    await apiFetch(`/api/instructions/${sid}`, "DELETE");
+    toast("Setting deleted.", "success");
+    if ($("edit-settings-id").value === sid) clearSettingsForm();
+    await loadSettingsList();
+  } catch (e) { toast(`Delete failed: ${e.message}`, "error"); }
+}
+window.deleteSetting = deleteSetting;
+
+/* ── Generate now (from edit form) ─── */
+$("btn-settings-generate")?.addEventListener("click", async () => {
+  const sid = $("edit-settings-id").value;
+  if (!sid) return;
+  document.querySelector('[data-page="generate"]')?.click();
+  await generateFromSetting(sid);
+});
+
+/* ─────────────────────────────────────────────────────────────────────
+   HISTORY PAGE
+───────────────────────────────────────────────────────────────────── */
+$("btn-history-refresh")?.addEventListener("click", loadHistory);
+
+let histSearchTimer;
+$("history-search")?.addEventListener("input", () => {
+  clearTimeout(histSearchTimer);
+  histSearchTimer = setTimeout(loadHistory, 300);
+});
+$("history-status-filter")?.addEventListener("change", loadHistory);
+
+async function loadHistory() {
+  const status = $("history-status-filter")?.value || "";
+  const q      = $("history-search")?.value.trim()  || "";
+  let url = "/api/history?";
+  if (status) url += `status_filter=${status}&`;
+
+  try {
+    const data = await apiFetch(url);
+    let entries = data.entries || [];
+
+    // client-side search if q provided
+    if (q) {
+      const ql = q.toLowerCase();
+      entries = entries.filter(e => e.instruction?.toLowerCase().includes(ql) ||
+        e.prompt_id?.toLowerCase().includes(ql) ||
+        (e.tags||[]).join(",").includes(ql));
+    }
+
+    const tbody = $("history-body");
+    const total = entries.length;
+    if ($("history-badge")) $("history-badge").textContent = data.total || 0;
+
+    if (!total) {
+      tbody.innerHTML = `<tr><td class="empty-msg" colspan="8">No prompts found.</td></tr>`;
+      return;
+    }
+
+    tbody.innerHTML = entries.map(e => `
+      <tr>
+        <td><span class="fav-star${e.is_favorite?' active':''}"
+          onclick="toggleHistFav('${esc(e.prompt_id)}')">${e.is_favorite?"★":"☆"}</span></td>
+        <td><code style="font-size:.7rem;color:var(--text-muted)">${esc(e.prompt_id?.slice(0,8))}…</code></td>
+        <td style="max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap"
+          title="${esc(e.instruction)}">${esc(e.instruction?.slice(0,55)||"—")}</td>
+        <td style="font-family:var(--font-mono);font-size:.75rem">v${e.version||1}</td>
+        <td><span class="badge badge-${e.status||'pending'}">${esc(e.status||"pending")}</span></td>
+        <td>${(e.tags||[]).slice(0,3).map(t=>`<span class="tag-chip">${esc(t)}</span>`).join(" ")}</td>
+        <td style="white-space:nowrap;font-size:.74rem;color:var(--text-muted)">${e.created_at?new Date(e.created_at).toLocaleDateString():"—"}</td>
+        <td style="white-space:nowrap;display:flex;gap:4px">
+          <button class="icon-btn btn-sm" title="Archive" onclick="archivePrompt('${esc(e.prompt_id)}')">📦</button>
+          <button class="icon-btn btn-danger btn-sm" title="Delete" onclick="deleteHistory('${esc(e.prompt_id)}')">🗑</button>
+        </td>
+      </tr>`).join("");
+
+    toast(`${total} prompt(s) loaded.`, "info", 2000);
+  } catch (e) { toast(`History error: ${e.message}`, "error"); }
+}
+
+async function toggleHistFav(pid) {
+  try {
+    const r = await apiFetch(`/api/prompts/${pid}/favorite`, "POST");
+    document.querySelectorAll(".fav-star").forEach(el => {
+      if (el.getAttribute("onclick")?.includes(pid)) {
+        el.textContent = r.is_favorite ? "★" : "☆";
+        el.classList.toggle("active", r.is_favorite);
+      }
+    });
+  } catch (e) { toast("Failed: " + e.message, "error"); }
+}
+window.toggleHistFav = toggleHistFav;
+
+async function archivePrompt(pid) {
+  try {
+    await apiFetch(`/api/prompts/${pid}/archive`, "POST");
+    toast("Prompt archived.", "success");
+    loadHistory();
+  } catch (e) { toast("Archive failed: " + e.message, "error"); }
+}
+window.archivePrompt = archivePrompt;
+
+async function deleteHistory(id) {
+  if (!confirm("Delete this prompt permanently?")) return;
+  try {
+    await apiFetch(`/api/history/${id}`, "DELETE");
+    toast("Deleted.", "success");
+    loadHistory();
+  } catch (e) { toast(`Delete failed: ${e.message}`, "error"); }
+}
+window.deleteHistory = deleteHistory;
+
+/* ─────────────────────────────────────────────────────────────────────
+   STATS PAGE
+───────────────────────────────────────────────────────────────────── */
+$("btn-stats-refresh")?.addEventListener("click", loadStats);
+
+async function loadStats() {
+  const grid = $("stats-grid");
+  try {
+    const s = await apiFetch("/api/stats");
+
+    grid.innerHTML = [
+      { val:s.total_prompts,    lbl:"Total Prompts",    sub:"all time",           hi:false },
+      { val:s.total_settings,   lbl:"Saved Settings",   sub:`${s.favorite_settings} favourited`, hi:false },
+      { val:s.total_refinements,lbl:"Refinements",       sub:"iterative improvements",  hi:true },
+      { val:s.avg_constraints,  lbl:"Avg Constraints",  sub:"per prompt",          hi:false },
+    ].map(c => `
+      <div class="stat-card${c.hi?" highlight":""}">
+        <div class="stat-value">${c.val}</div>
+        <div class="stat-label">${c.lbl}</div>
+        <div class="stat-sub">${c.sub}</div>
+      </div>`).join("");
+
+    // Persona bars
+    const maxP = Math.max(1, ...Object.values(s.top_personas));
+    $("stats-personas").innerHTML = Object.entries(s.top_personas).length
+      ? Object.entries(s.top_personas).sort((a,b)=>b[1]-a[1]).map(([k,v]) => `
+          <div class="bar-row">
+            <div class="bar-row-label">${esc(k)}</div>
+            <div class="bar-track"><div class="bar-fill" style="width:${Math.round(v/maxP*100)}%"></div></div>
+            <div class="bar-count">${v}</div>
+          </div>`).join("")
+      : `<p class="muted" style="padding:4px 0">No data yet.</p>`;
+
+    // Style bars
+    const maxS = Math.max(1, ...Object.values(s.top_styles));
+    $("stats-styles").innerHTML = Object.entries(s.top_styles).length
+      ? Object.entries(s.top_styles).sort((a,b)=>b[1]-a[1]).map(([k,v]) => `
+          <div class="bar-row">
+            <div class="bar-row-label">${esc(k)}</div>
+            <div class="bar-track"><div class="bar-fill" style="width:${Math.round(v/maxS*100)}%"></div></div>
+            <div class="bar-count">${v}</div>
+          </div>`).join("")
+      : `<p class="muted" style="padding:4px 0">No data yet.</p>`;
+
+    // Status breakdown
+    $("stats-statuses").innerHTML = [
+      { status:"pending",  count:s.pending_count,  color:"var(--amber)"  },
+      { status:"approved", count:s.approved_count, color:"var(--green)"  },
+      { status:"exported", count:s.exported_count, color:"var(--accent)" },
+      { status:"archived", count:s.archived_count, color:"var(--text-faint)" },
+    ].map(x => `
+      <div class="status-item">
+        <div class="status-item-count" style="color:${x.color}">${x.count}</div>
+        <div class="status-item-label">${x.status}</div>
+      </div>`).join("");
+
+    toast("Stats refreshed.", "info", 2000);
+  } catch (e) {
+    grid.innerHTML = `<div class="stat-card" style="grid-column:1/-1;text-align:center;color:var(--text-muted)">Could not load stats — is the server running?</div>`;
+    toast("Stats error: " + e.message, "error");
+  }
+}
+
+/* ── Utilities ─── */
+function personaEmoji(persona) {
+  const m = { senior_dev:"👨‍💻", data_scientist:"📊", tech_writer:"✍️", product_mgr:"📋",
+              security_eng:"🔒", devops_eng:"🚀", ml_engineer:"🧠", custom:"✏️" };
+  return m[persona] || "🤖";
+}
+
+function updateBadge(id, total, delta) {
+  const el = $(id);
+  if (!el) return;
+  if (total !== null) { el.textContent = total; }
+  else { el.textContent = parseInt(el.textContent || "0") + delta; }
+}
+
+/* ── Init ─── */
+(async () => {
+  await loadConfig();
+  await loadSettingsList();
+  setStep(1);
+})();

backend/instruction_store.py

@@ -1,27 +1,28 @@
 """
-PromptForge — Persistent store for InstructionSettings.
-Separate from prompt_store to keep concerns clean.
+PromptForge v4.0 — Instruction Settings store.
+Upgrades: duplicate setting, export-all-as-JSON, bulk-delete,
+          favorite toggle, and richer seeded defaults.
 """
 from __future__ import annotations
-import json
-import os
-import logging
-import uuid
+import json, os, logging, uuid
 from datetime import datetime
 from pathlib import Path
 from typing import Dict, List, Optional
 
-from schemas import InstructionSettings, InstructionSettingsCreate, InstructionSettingsUpdate
+from schemas import (
+    InstructionSettings, InstructionSettingsCreate, InstructionSettingsUpdate,
+    AIProvider, OutputFormat, PersonaType, StyleType,
+)
 
 logger = logging.getLogger("promptforge.instruction_store")
 
-_DB: Dict[str, InstructionSettings] = {}
-_LOG_DIR = Path(os.getenv("LOG_DIR", "logs"))
+_DB:          Dict[str, InstructionSettings] = {}
+_LOG_DIR     = Path(os.getenv("LOG_DIR", "logs"))
 _LOG_DIR.mkdir(parents=True, exist_ok=True)
 _PERSIST_FILE = _LOG_DIR / "instruction_settings.json"
 
 
-# ── CRUD ────────────────────────────────────────────────────────────────────
+# ── CRUD ─────────────────────────────────────────────────────────────────────
 
 def create(data: InstructionSettingsCreate) -> InstructionSettings:
     sid = str(uuid.uuid4())
@@ -31,11 +32,12 @@ def create(data: InstructionSettingsCreate) -> InstructionSettings:
         created_at=now,
         updated_at=now,
         use_count=0,
+        version=1,
         **data.model_dump(),
     )
     _DB[sid] = setting
     _persist()
-    logger.info("CREATED instruction setting | id=%s title=%r", sid, setting.title)
+    logger.info("CREATED setting | id=%s title=%r", sid, setting.title)
     return setting
 
 
@@ -43,10 +45,19 @@ def get(settings_id: str) -> Optional[InstructionSettings]:
     return _DB.get(settings_id)
 
 
-def list_all(tag: Optional[str] = None) -> List[InstructionSettings]:
-    items = sorted(_DB.values(), key=lambda x: x.updated_at, reverse=True)
+def list_all(
+    tag: Optional[str] = None,
+    favorites_only: bool = False,
+    search_q: Optional[str] = None,
+) -> List[InstructionSettings]:
+    items = sorted(_DB.values(), key=lambda x: (not x.is_favorite, x.updated_at.timestamp() * -1))
     if tag:
         items = [i for i in items if tag in i.tags]
+    if favorites_only:
+        items = [i for i in items if i.is_favorite]
+    if search_q:
+        q = search_q.lower()
+        items = [i for i in items if q in (i.title + i.instruction + (i.description or "")).lower()]
     return items
 
 
@@ -56,10 +67,11 @@ def update(settings_id: str, data: InstructionSettingsUpdate) -> Optional[Instru
         return None
     patch = {k: v for k, v in data.model_dump().items() if v is not None}
     patch["updated_at"] = datetime.utcnow()
+    patch["version"]    = existing.version + 1
     updated = existing.model_copy(update=patch)
     _DB[settings_id] = updated
     _persist()
-    logger.info("UPDATED instruction setting | id=%s", settings_id)
+    logger.info("UPDATED setting | id=%s v%d", settings_id, updated.version)
     return updated
 
 
@@ -67,11 +79,45 @@ def delete(settings_id: str) -> bool:
     if settings_id in _DB:
         del _DB[settings_id]
         _persist()
-        logger.info("DELETED instruction setting | id=%s", settings_id)
+        logger.info("DELETED setting | id=%s", settings_id)
         return True
     return False
 
 
+def bulk_delete(settings_ids: List[str]) -> int:
+    deleted = 0
+    for sid in settings_ids:
+        if sid in _DB:
+            del _DB[sid]
+            deleted += 1
+    if deleted:
+        _persist()
+    return deleted
+
+
+def duplicate(settings_id: str) -> Optional[InstructionSettings]:
+    """Create a copy of an existing setting with '(copy)' suffix."""
+    original = _DB.get(settings_id)
+    if not original:
+        return None
+    data = InstructionSettingsCreate(**{
+        **original.model_dump(),
+        "title": f"{original.title} (copy)",
+        "is_favorite": False,
+    })
+    return create(data)
+
+
+def toggle_favorite(settings_id: str) -> Optional[bool]:
+    s = _DB.get(settings_id)
+    if not s:
+        return None
+    new_val = not s.is_favorite
+    _DB[settings_id] = s.model_copy(update={"is_favorite": new_val, "updated_at": datetime.utcnow()})
+    _persist()
+    return new_val
+
+
 def increment_use_count(settings_id: str) -> None:
     if settings_id in _DB:
         s = _DB[settings_id]
@@ -81,7 +127,17 @@ def increment_use_count(settings_id: str) -> None:
         _persist()
 
 
-# ── Persistence ────────────────────────────────────────��────────────────────
+def export_all() -> List[dict]:
+    """Return all settings as a list of dicts (for bulk JSON export)."""
+    return [s.model_dump(mode="json") for s in sorted(_DB.values(), key=lambda x: x.created_at)]
+
+
+def get_all_tags() -> List[str]:
+    tags = sorted({tag for s in _DB.values() for tag in s.tags})
+    return tags
+
+
+# ── Persistence ───────────────────────────────────────────────────────────────
 
 def _persist() -> None:
     try:
@@ -100,54 +156,92 @@ def load_from_disk() -> None:
         for entry in raw:
             s = InstructionSettings.model_validate(entry)
             _DB[s.settings_id] = s
-        logger.info("Loaded %d instruction settings from disk.", len(_DB))
+        logger.info("Loaded %d settings from disk.", len(_DB))
     except Exception as exc:
         logger.warning("Could not load instruction settings: %s", exc)
         _seed_defaults()
 
 
 def _seed_defaults() -> None:
-    """Create a few useful starter templates on first run."""
-    from schemas import InstructionSettingsCreate, OutputFormat, PersonaType, StyleType, AIProvider
     defaults = [
         InstructionSettingsCreate(
-            title="React Component Generator",
-            description="Generates a TypeScript React component with TailwindCSS and tests.",
-            instruction="Create a reusable TypeScript React component with TailwindCSS styling, proper props interface, and Jest unit tests.",
-            extra_context="Follow React best practices: hooks, memo, accessibility.",
+            title="React TypeScript Component",
+            description="Generates a reusable TypeScript React component with TailwindCSS styling and Jest tests.",
+            instruction="Create a reusable TypeScript React component with TailwindCSS styling, a full props interface with JSDoc comments, and Jest + Testing Library unit tests. Include a Storybook story.",
+            extra_context="Follow React 18 best practices: hooks, memo, forwardRef where needed. Support dark mode via Tailwind dark: prefix.",
             output_format=OutputFormat.both,
             persona=PersonaType.senior_dev,
             style=StyleType.professional,
-            constraints=["Use TypeScript strict mode", "WCAG 2.1 AA accessibility", "Include PropTypes documentation"],
-            tags=["react", "typescript", "frontend"],
+            constraints=["TypeScript strict mode", "WCAG 2.1 AA accessibility", "Include PropTypes documentation", "Responsive design"],
+            tags=["react", "typescript", "frontend", "tailwind"],
             provider=AIProvider.none,
             enhance=False,
+            is_favorite=True,
         ),
         InstructionSettingsCreate(
-            title="Python API Endpoint",
-            description="Generates a FastAPI endpoint with validation and error handling.",
-            instruction="Create a FastAPI endpoint with Pydantic request/response models, input validation, error handling, and docstring.",
-            extra_context="Follow REST best practices. Include OpenAPI tags.",
+            title="FastAPI Endpoint",
+            description="Generates a FastAPI endpoint with Pydantic validation, error handling, and tests.",
+            instruction="Create a FastAPI endpoint with Pydantic v2 request/response models, input validation, structured error handling, OpenAPI metadata (tags, summary, description), and pytest async tests.",
+            extra_context="Follow REST best practices. Use dependency injection. Include an integration test against a test database.",
             output_format=OutputFormat.both,
             persona=PersonaType.senior_dev,
             style=StyleType.detailed,
-            constraints=["Python 3.11+", "PEP-8 compliant", "Type hints everywhere", "Include unit tests"],
-            tags=["python", "fastapi", "backend"],
+            constraints=["Python 3.11+", "PEP-8 compliant", "Type hints everywhere", "Include async tests", "Structured logging"],
+            tags=["python", "fastapi", "backend", "testing"],
             provider=AIProvider.none,
             enhance=False,
+            is_favorite=True,
         ),
         InstructionSettingsCreate(
             title="Technical Blog Post",
-            description="Creates a structured technical article with code examples.",
-            instruction="Write a technical blog post explaining the concept with clear sections, code examples, and actionable takeaways.",
+            description="Creates a structured technical article with code examples and actionable takeaways.",
+            instruction="Write a technical blog post explaining the concept with clear H2/H3 sections, at least two runnable code examples, a TL;DR opener, and concrete actionable takeaways at the end.",
             output_format=OutputFormat.text,
             persona=PersonaType.tech_writer,
             style=StyleType.detailed,
-            constraints=["800-1200 words", "Include at least 2 code examples", "Add a TL;DR section"],
+            constraints=["800–1200 words", "Include ≥2 code examples", "Add a TL;DR section", "Link to further reading"],
             tags=["writing", "technical", "blog"],
             provider=AIProvider.none,
             enhance=False,
         ),
+        InstructionSettingsCreate(
+            title="SQL Query Optimiser",
+            description="Analyses and rewrites slow SQL queries with explanations.",
+            instruction="Analyse the provided SQL query for performance issues, rewrite it with optimisations (indexes, joins, CTEs), and explain every change with Big-O reasoning.",
+            extra_context="Target PostgreSQL 15+. Use EXPLAIN ANALYZE format for before/after comparison.",
+            output_format=OutputFormat.both,
+            persona=PersonaType.data_scientist,
+            style=StyleType.detailed,
+            constraints=["PostgreSQL 15+", "Include EXPLAIN ANALYZE output", "Document index strategy"],
+            tags=["sql", "database", "performance"],
+            provider=AIProvider.none,
+            enhance=False,
+        ),
+        InstructionSettingsCreate(
+            title="Docker + CI/CD Setup",
+            description="Generates multi-stage Dockerfile and GitHub Actions workflow.",
+            instruction="Create a production-ready multi-stage Dockerfile and a GitHub Actions CI/CD pipeline with lint, test, build, and deploy stages. Include security scanning with Trivy.",
+            output_format=OutputFormat.both,
+            persona=PersonaType.devops_eng,
+            style=StyleType.professional,
+            constraints=["Multi-stage build", "Non-root user", "Health checks", "Cache layer optimisation", "Secrets via GitHub Secrets"],
+            tags=["docker", "devops", "ci/cd", "security"],
+            provider=AIProvider.none,
+            enhance=False,
+        ),
+        InstructionSettingsCreate(
+            title="LLM Fine-Tuning Guide",
+            description="Step-by-step guide for fine-tuning an open-source LLM.",
+            instruction="Write a step-by-step guide for fine-tuning an open-source LLM using LoRA/QLoRA on a custom dataset. Cover data preparation, training config, evaluation metrics, and deployment.",
+            extra_context="Target Hugging Face + PEFT + bitsandbytes stack. Assume 1× A100 or equivalent GPU.",
+            output_format=OutputFormat.both,
+            persona=PersonaType.ml_engineer,
+            style=StyleType.detailed,
+            constraints=["Hugging Face ecosystem", "LoRA/QLoRA", "Include evaluation with BLEU/ROUGE", "Deployment section"],
+            tags=["ml", "llm", "fine-tuning", "huggingface"],
+            provider=AIProvider.none,
+            enhance=False,
+        ),
     ]
     for d in defaults:
         create(d)

backend/main.py

@@ -1,19 +1,34 @@
 """
-PromptForge — FastAPI server v3.0
+PromptForge v4.0 — FastAPI application
 Run: uvicorn main:app --reload --host 0.0.0.0 --port 7860
+
+New endpoints vs v3.0:
+  POST /api/generate/batch
+  GET  /api/search?q=…
+  GET  /api/stats
+  POST /api/prompts/{id}/favorite
+  POST /api/prompts/{id}/archive
+  POST /api/history/bulk-delete
+  POST /api/instructions/{id}/duplicate
+  POST /api/instructions/{id}/favorite
+  GET  /api/instructions/export
+  GET  /api/instructions/tags
+  POST /api/check-key
 """
 from __future__ import annotations
 import logging, os
 from pathlib import Path
+from typing import List, Optional
 
-from fastapi import FastAPI, HTTPException, status
+from fastapi import FastAPI, HTTPException, Query, status
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
 
 import store
 import instruction_store
-from ai_client import enhance_prompt
+from ai_client import enhance_prompt, check_hf_key, check_google_key, HF_DEFAULT_MODEL, GOOGLE_DEFAULT_MODEL
 from prompt_logic import (
     build_manifest, build_manifest_from_settings,
     apply_edits, refine_with_feedback, generate_explanation,
@@ -22,26 +37,27 @@ from schemas import (
     ApproveRequest, ApproveResponse,
     ExportRequest, ExportResponse,
     GenerateRequest, GenerateFromSettingsRequest, GenerateResponse,
+    BatchGenerateRequest, BatchGenerateResponse,
     HistoryResponse,
     RefineRequest,
     InstructionSettingsCreate, InstructionSettingsUpdate,
     InstructionSettingsList, InstructionSettings,
-    ExplainResponse, EnvConfigStatus,
+    ExplainResponse, EnvConfigStatus, StatsResponse,
     AIProvider,
 )
 
-# ── Logging ─────────────────────────────────────────────────────────────────
+# ── Logging ───────────────────────────────────────────────────────────────────
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
 )
 logger = logging.getLogger("promptforge.main")
 
-# ── App bootstrap ────────────────────────────────────────────────────────────
+# ── App ───────────────────────────────────────────────────────────────────────
 app = FastAPI(
     title="PromptForge",
-    description="Structured prompt generator for Google AI Studio. v3.0",
-    version="3.0.0",
+    description="Structured prompt generator for Google AI Studio — v4.0",
+    version="4.0.0",
     docs_url="/docs",
     redoc_url="/redoc",
 )
@@ -62,171 +78,229 @@ if _FRONTEND_DIR.exists():
 async def _startup() -> None:
     store.load_from_disk()
     instruction_store.load_from_disk()
-    port = os.environ.get("PORT", "7860")
-    logger.info("PromptForge v3.0 started. Visit http://localhost:%s", port)
+    logger.info("PromptForge v4.0 ready on port %s", os.environ.get("PORT", "7860"))
 
 
-# ── Frontend ─────────────────────────────────────────────────────────────────
+# ── Frontend ──────────────────────────────────────────────────────────────────
 
 @app.get("/", response_class=HTMLResponse, tags=["Frontend"])
 async def serve_frontend() -> HTMLResponse:
     index = _FRONTEND_DIR / "index.html"
     if index.exists():
         return HTMLResponse(content=index.read_text(), status_code=200)
-    return HTMLResponse("<h1>PromptForge API is running.</h1><a href='/docs'>API Docs</a>")
+    return HTMLResponse("<h1>PromptForge v4.0 API</h1><a href='/docs'>Swagger Docs →</a>")
 
 
-# ── Environment Config (read-only) ───────────────────────────────────────────
+# ── System ────────────────────────────────────────────────────────────────────
+
+@app.get("/health", tags=["System"])
+async def health() -> dict:
+    return {
+        "status": "ok", "service": "PromptForge", "version": "4.0.0",
+        "prompts_in_memory":  len(store._DB),
+        "settings_in_memory": len(instruction_store._DB),
+    }
+
 
 @app.get("/api/config", response_model=EnvConfigStatus, tags=["System"])
 async def get_config() -> EnvConfigStatus:
-    """Return which API keys are set in the environment (values never exposed)."""
     return EnvConfigStatus(
         hf_key_set=bool(os.environ.get("HF_API_KEY")),
         google_key_set=bool(os.environ.get("GOOGLE_API_KEY")),
         port=os.environ.get("PORT", "7860"),
-        version="3.0.0",
+        version="4.0.0",
+        hf_model=HF_DEFAULT_MODEL,
+        google_model=GOOGLE_DEFAULT_MODEL,
     )
 
 
-# ── Instruction Settings CRUD ────────────────────────────────────────────────
+@app.get("/api/stats", response_model=StatsResponse, tags=["System"])
+async def get_stats() -> StatsResponse:
+    s = store.get_stats()
+    i = instruction_store._DB
+    return StatsResponse(
+        total_prompts=s["total_prompts"],
+        total_settings=len(i),
+        pending_count=s["pending_count"],
+        approved_count=s["approved_count"],
+        exported_count=s["exported_count"],
+        archived_count=s["archived_count"],
+        favorite_prompts=s["favorite_prompts"],
+        favorite_settings=sum(1 for x in i.values() if x.is_favorite),
+        top_personas=s["top_personas"],
+        top_styles=s["top_styles"],
+        total_refinements=s["total_refinements"],
+        avg_constraints=s["avg_constraints"],
+        uptime_since=s["uptime_since"],
+    )
+
+
+class KeyCheckRequest(BaseModel):
+    provider: str
+    api_key:  str
+
+@app.post("/api/check-key", tags=["System"])
+async def check_api_key(req: KeyCheckRequest) -> dict:
+    """Validate an API key against the provider (no storage, no logging of the key)."""
+    if req.provider == "huggingface":
+        valid = await check_hf_key(req.api_key)
+    elif req.provider == "google":
+        valid = await check_google_key(req.api_key)
+    else:
+        return {"valid": False, "message": "Unknown provider."}
+    return {"valid": valid, "message": "Key is valid." if valid else "Key appears invalid or quota exhausted."}
+
+
+# ── Search ────────────────────────────────────────────────────────────────────
+
+@app.get("/api/search", tags=["Prompts"])
+async def search_prompts(
+    q: str = Query(..., min_length=1, description="Search query"),
+    status_filter: Optional[str] = Query(None),
+) -> dict:
+    results = store.search(q, status_filter=status_filter)
+    return {"total": len(results), "results": results}
+
+
+# ── Instruction Settings ──────────────────────────────────────────────────────
 
 @app.post("/api/instructions", response_model=InstructionSettings,
           status_code=status.HTTP_201_CREATED, tags=["Settings"])
 async def create_instruction(data: InstructionSettingsCreate) -> InstructionSettings:
-    """Save a new instruction setting template."""
-    setting = instruction_store.create(data)
-    logger.info("INSTRUCTION CREATED | id=%s title=%r", setting.settings_id, setting.title)
-    return setting
+    s = instruction_store.create(data)
+    logger.info("SETTING CREATED | id=%s title=%r", s.settings_id, s.title)
+    return s
 
 
 @app.get("/api/instructions", response_model=InstructionSettingsList, tags=["Settings"])
-async def list_instructions(tag: str | None = None) -> InstructionSettingsList:
-    """List all saved instruction settings (optionally filtered by tag)."""
-    items = instruction_store.list_all(tag=tag)
-    return InstructionSettingsList(total=len(items), items=items)
+async def list_instructions(
+    tag: Optional[str] = None,
+    favorites_only: bool = False,
+    q: Optional[str] = Query(None, description="Search in title/instruction/description"),
+) -> InstructionSettingsList:
+    items = instruction_store.list_all(tag=tag, favorites_only=favorites_only, search_q=q)
+    favs  = sum(1 for i in items if i.is_favorite)
+    return InstructionSettingsList(total=len(items), items=items, favorites=favs)
+
+
+@app.get("/api/instructions/tags", tags=["Settings"])
+async def get_all_tags() -> dict:
+    return {"tags": instruction_store.get_all_tags()}
+
+
+@app.get("/api/instructions/export", tags=["Settings"])
+async def export_all_settings() -> dict:
+    return {"total": len(instruction_store._DB), "settings": instruction_store.export_all()}
 
 
 @app.get("/api/instructions/{settings_id}", response_model=InstructionSettings, tags=["Settings"])
 async def get_instruction(settings_id: str) -> InstructionSettings:
-    setting = instruction_store.get(settings_id)
-    if not setting:
-        raise HTTPException(404, f"Instruction setting '{settings_id}' not found.")
-    return setting
+    s = instruction_store.get(settings_id)
+    if not s:
+        raise HTTPException(404, f"Setting '{settings_id}' not found.")
+    return s
 
 
 @app.patch("/api/instructions/{settings_id}", response_model=InstructionSettings, tags=["Settings"])
 async def update_instruction(settings_id: str, data: InstructionSettingsUpdate) -> InstructionSettings:
     updated = instruction_store.update(settings_id, data)
     if not updated:
-        raise HTTPException(404, f"Instruction setting '{settings_id}' not found.")
+        raise HTTPException(404, f"Setting '{settings_id}' not found.")
     return updated
 
 
 @app.delete("/api/instructions/{settings_id}", tags=["Settings"])
 async def delete_instruction(settings_id: str) -> JSONResponse:
-    deleted = instruction_store.delete(settings_id)
-    if not deleted:
-        raise HTTPException(404, f"Instruction setting '{settings_id}' not found.")
+    if not instruction_store.delete(settings_id):
+        raise HTTPException(404, f"Setting '{settings_id}' not found.")
     return JSONResponse({"success": True, "message": f"Setting {settings_id} deleted."})
 
 
-# ── Generate from settings ────────────────────────────────────────────────────
+@app.post("/api/instructions/{settings_id}/duplicate", response_model=InstructionSettings, tags=["Settings"])
+async def duplicate_instruction(settings_id: str) -> InstructionSettings:
+    copy = instruction_store.duplicate(settings_id)
+    if not copy:
+        raise HTTPException(404, f"Setting '{settings_id}' not found.")
+    logger.info("SETTING DUPLICATED | original=%s copy=%s", settings_id, copy.settings_id)
+    return copy
 
-@app.post("/api/generate/from-settings", response_model=GenerateResponse, tags=["Prompts"])
-async def generate_from_settings(req: GenerateFromSettingsRequest) -> GenerateResponse:
-    """
-    Generate a prompt manifest directly from a saved InstructionSettings.
-    API key can be passed in the request OR read from environment variables.
-    """
-    setting = instruction_store.get(req.settings_id)
-    if not setting:
-        raise HTTPException(404, f"Instruction setting '{req.settings_id}' not found.")
-
-    # Resolve API key: request > env var
-    api_key = req.api_key
-    if not api_key and setting.provider == "huggingface":
-        api_key = os.environ.get("HF_API_KEY")
-    elif not api_key and setting.provider == "google":
-        api_key = os.environ.get("GOOGLE_API_KEY")
 
-    manifest = build_manifest_from_settings(setting)
+@app.post("/api/instructions/{settings_id}/favorite", tags=["Settings"])
+async def toggle_setting_favorite(settings_id: str) -> dict:
+    new_val = instruction_store.toggle_favorite(settings_id)
+    if new_val is None:
+        raise HTTPException(404, f"Setting '{settings_id}' not found.")
+    return {"settings_id": settings_id, "is_favorite": new_val}
 
-    if setting.enhance and setting.provider != "none" and api_key:
-        enhanced_text, notes = await enhance_prompt(
-            raw_prompt=manifest.structured_prompt.raw_prompt_text,
-            provider=setting.provider.value,
-            api_key=api_key,
-        )
-        sp = manifest.structured_prompt.model_copy(update={"raw_prompt_text": enhanced_text})
-        manifest = manifest.model_copy(update={"structured_prompt": sp, "enhancement_notes": notes})
 
-    instruction_store.increment_use_count(req.settings_id)
-    store.save(manifest)
-    logger.info("GENERATE_FROM_SETTINGS | settings_id=%s prompt_id=%s", req.settings_id, manifest.prompt_id)
+class BulkDeleteRequest(BaseModel):
+    ids: List[str]
 
-    return GenerateResponse(
-        success=True,
-        prompt_id=manifest.prompt_id,
-        manifest=manifest,
-        message=f"Generated from settings '{setting.title}'.",
-    )
+@app.post("/api/instructions/bulk-delete", tags=["Settings"])
+async def bulk_delete_settings(req: BulkDeleteRequest) -> dict:
+    deleted = instruction_store.bulk_delete(req.ids)
+    return {"deleted": deleted}
 
 
-# ── Standard Generate ─────────────────────────────────────────────────────────
+# ── Generate ──────────────────────────────────────────────────────────────────
 
 @app.post("/api/generate", response_model=GenerateResponse, tags=["Prompts"])
 async def generate_prompt(req: GenerateRequest) -> GenerateResponse:
-    """Generate a structured prompt from a raw instruction."""
-    logger.info("GENERATE | instruction=%r | persona=%s | style=%s | enhance=%s",
-                req.instruction[:80], req.persona, req.style, req.enhance)
-
-    # Resolve API key from env if not provided
-    api_key = req.api_key
-    if not api_key:
-        if req.provider == AIProvider.huggingface:
-            api_key = os.environ.get("HF_API_KEY")
-        elif req.provider == AIProvider.google:
-            api_key = os.environ.get("GOOGLE_API_KEY")
-
+    logger.info("GENERATE | persona=%s style=%s enhance=%s", req.persona, req.style, req.enhance)
+    api_key = _resolve_key(req.api_key, req.provider)
     manifest = build_manifest(
-        instruction=req.instruction,
-        extra_context=req.extra_context,
-        persona=req.persona,
-        custom_persona=req.custom_persona,
-        style=req.style,
-        user_constraints=req.user_constraints,
+        instruction=req.instruction, extra_context=req.extra_context,
+        persona=req.persona, custom_persona=req.custom_persona,
+        style=req.style, user_constraints=req.user_constraints,
         settings_id=req.settings_id,
     )
-
     if req.enhance and req.provider != AIProvider.none and api_key:
-        enhanced_text, notes = await enhance_prompt(
-            raw_prompt=manifest.structured_prompt.raw_prompt_text,
-            provider=req.provider.value,
-            api_key=api_key,
-        )
-        sp = manifest.structured_prompt.model_copy(update={"raw_prompt_text": enhanced_text})
-        manifest = manifest.model_copy(update={"structured_prompt": sp, "enhancement_notes": notes})
-        logger.info("ENHANCED | %s", notes)
-
+        manifest = await _apply_enhancement(manifest, req.provider.value, api_key, req.provider_model)
     store.save(manifest)
     return GenerateResponse(success=True, prompt_id=manifest.prompt_id, manifest=manifest)
 
 
+@app.post("/api/generate/from-settings", response_model=GenerateResponse, tags=["Prompts"])
+async def generate_from_settings(req: GenerateFromSettingsRequest) -> GenerateResponse:
+    setting = instruction_store.get(req.settings_id)
+    if not setting:
+        raise HTTPException(404, f"Setting '{req.settings_id}' not found.")
+    api_key  = _resolve_key(req.api_key, setting.provider)
+    manifest = build_manifest_from_settings(setting)
+    if setting.enhance and setting.provider != AIProvider.none and api_key:
+        manifest = await _apply_enhancement(manifest, setting.provider.value, api_key, setting.provider_model)
+    instruction_store.increment_use_count(req.settings_id)
+    store.save(manifest)
+    logger.info("GEN_FROM_SETTINGS | sid=%s pid=%s", req.settings_id, manifest.prompt_id)
+    return GenerateResponse(
+        success=True, prompt_id=manifest.prompt_id, manifest=manifest,
+        message=f"Generated from '{setting.title}'.",
+    )
+
+
+@app.post("/api/generate/batch", response_model=BatchGenerateResponse, tags=["Prompts"])
+async def batch_generate(req: BatchGenerateRequest) -> BatchGenerateResponse:
+    """Generate up to 10 prompts in a single call."""
+    results, failed = [], 0
+    for gen_req in req.requests:
+        try:
+            r = await generate_prompt(gen_req)
+            results.append(r)
+        except Exception as exc:
+            logger.warning("Batch item failed: %s", exc)
+            failed += 1
+    return BatchGenerateResponse(success=True, total=len(results), results=results, failed=failed)
+
+
 # ── Explain ───────────────────────────────────────────────────────────────────
 
 @app.get("/api/explain/{prompt_id}", response_model=ExplainResponse, tags=["Prompts"])
 async def explain_prompt(prompt_id: str) -> ExplainResponse:
-    """Return a plain-English explanation for why a prompt was structured the way it was."""
     manifest = store.get(prompt_id)
     if not manifest:
         raise HTTPException(404, f"Prompt '{prompt_id}' not found.")
     explanation, decisions = generate_explanation(manifest)
-    return ExplainResponse(
-        prompt_id=prompt_id,
-        explanation=explanation,
-        key_decisions=decisions,
-    )
+    return ExplainResponse(prompt_id=prompt_id, explanation=explanation, key_decisions=decisions)
 
 
 # ── Approve ───────────────────────────────────────────────────────────────────
@@ -238,10 +312,10 @@ async def approve_prompt(req: ApproveRequest) -> ApproveResponse:
         raise HTTPException(404, f"Prompt '{req.prompt_id}' not found.")
     manifest = apply_edits(manifest, req.edits) if req.edits else manifest.model_copy(update={"status": "approved"})
     store.save(manifest)
-    logger.info("APPROVED | prompt_id=%s", manifest.prompt_id)
+    logger.info("APPROVED | pid=%s", manifest.prompt_id)
     return ApproveResponse(
         success=True, prompt_id=manifest.prompt_id,
-        message="Prompt approved and finalized.",
+        message="Prompt approved and finalised.",
         finalized_prompt=manifest.structured_prompt,
     )
 
@@ -262,8 +336,10 @@ async def export_prompt(req: ExportRequest) -> ExportResponse:
     elif req.export_format == "json":
         data = manifest.structured_prompt.model_dump()
     else:
-        data = {"json": manifest.structured_prompt.model_dump(),
-                "text": manifest.structured_prompt.raw_prompt_text}
+        data = {
+            "json": manifest.structured_prompt.model_dump(),
+            "text": manifest.structured_prompt.raw_prompt_text,
+        }
     return ExportResponse(success=True, prompt_id=manifest.prompt_id, data=data)
 
 
@@ -274,33 +350,54 @@ async def refine_prompt(req: RefineRequest) -> GenerateResponse:
     manifest = store.get(req.prompt_id)
     if not manifest:
         raise HTTPException(404, f"Prompt '{req.prompt_id}' not found.")
-    refined = refine_with_feedback(manifest, req.feedback)
-    api_key = req.api_key
-    if not api_key:
-        if req.provider == AIProvider.huggingface:
-            api_key = os.environ.get("HF_API_KEY")
-        elif req.provider == AIProvider.google:
-            api_key = os.environ.get("GOOGLE_API_KEY")
+    refined  = refine_with_feedback(manifest, req.feedback)
+    api_key  = _resolve_key(req.api_key, req.provider)
     if req.provider != AIProvider.none and api_key:
-        enhanced_text, notes = await enhance_prompt(
-            raw_prompt=refined.structured_prompt.raw_prompt_text,
-            provider=req.provider.value, api_key=api_key,
-        )
-        sp = refined.structured_prompt.model_copy(update={"raw_prompt_text": enhanced_text})
-        refined = refined.model_copy(update={"structured_prompt": sp, "enhancement_notes": notes})
+        refined = await _apply_enhancement(refined, req.provider.value, api_key)
     store.save(refined)
-    logger.info("REFINED | prompt_id=%s version=%d", refined.prompt_id, refined.version)
+    logger.info("REFINED | pid=%s v%d", refined.prompt_id, refined.version)
     return GenerateResponse(
         success=True, prompt_id=refined.prompt_id, manifest=refined,
         message=f"Refined to v{refined.version} — awaiting approval.",
     )
 
 
+# ── Favorite / Archive ────────────────────────────────────────────────────────
+
+@app.post("/api/prompts/{prompt_id}/favorite", tags=["Prompts"])
+async def toggle_prompt_favorite(prompt_id: str) -> dict:
+    new_val = store.toggle_favorite(prompt_id)
+    if new_val is None:
+        raise HTTPException(404, f"Prompt '{prompt_id}' not found.")
+    return {"prompt_id": prompt_id, "is_favorite": new_val}
+
+
+@app.post("/api/prompts/{prompt_id}/archive", tags=["Prompts"])
+async def archive_prompt(prompt_id: str) -> dict:
+    if not store.archive(prompt_id):
+        raise HTTPException(404, f"Prompt '{prompt_id}' not found.")
+    return {"prompt_id": prompt_id, "status": "archived"}
+
+
+@app.post("/api/history/bulk-delete", tags=["History"])
+async def bulk_delete_history(req: BulkDeleteRequest) -> dict:
+    deleted = store.bulk_delete(req.ids)
+    return {"deleted": deleted}
+
+
 # ── History ───────────────────────────────────────────────────────────────────
 
 @app.get("/api/history", response_model=HistoryResponse, tags=["History"])
-async def get_history() -> HistoryResponse:
-    entries = store.all_entries()
+async def get_history(
+    status_filter: Optional[str] = Query(None),
+    tag_filter:    Optional[str] = Query(None),
+    favorites_only: bool         = Query(False),
+) -> HistoryResponse:
+    entries = store.all_entries(
+        status_filter=status_filter,
+        tag_filter=tag_filter,
+        favorites_only=favorites_only,
+    )
     return HistoryResponse(total=len(entries), entries=entries)
 
 
@@ -314,20 +411,30 @@ async def get_prompt(prompt_id: str) -> dict:
 
 @app.delete("/api/history/{prompt_id}", tags=["History"])
 async def delete_prompt(prompt_id: str) -> JSONResponse:
-    deleted = store.delete(prompt_id)
-    if not deleted:
+    if not store.delete(prompt_id):
         raise HTTPException(404, f"Prompt '{prompt_id}' not found.")
     return JSONResponse({"success": True, "message": f"Prompt {prompt_id} deleted."})
 
 
-# ── Health ────────────────────────────────────────────────────────────────────
+# ── Helpers ───────────────────────────────────────────────────────────────────
 
-@app.get("/health", tags=["System"])
-async def health() -> dict:
-    return {
-        "status": "ok",
-        "service": "PromptForge",
-        "version": "3.0.0",
-        "prompts_in_memory": len(store._DB),
-        "settings_in_memory": len(instruction_store._DB),
-    }
+def _resolve_key(api_key: Optional[str], provider) -> Optional[str]:
+    if api_key:
+        return api_key
+    provider_val = provider.value if hasattr(provider, "value") else str(provider)
+    if provider_val == "huggingface":
+        return os.environ.get("HF_API_KEY")
+    if provider_val == "google":
+        return os.environ.get("GOOGLE_API_KEY")
+    return None
+
+
+async def _apply_enhancement(manifest, provider: str, api_key: str, model_override=None):
+    enhanced_text, notes = await enhance_prompt(
+        raw_prompt=manifest.structured_prompt.raw_prompt_text,
+        provider=provider,
+        api_key=api_key,
+        model_override=model_override,
+    )
+    sp = manifest.structured_prompt.model_copy(update={"raw_prompt_text": enhanced_text})
+    return manifest.model_copy(update={"structured_prompt": sp, "enhancement_notes": notes})

backend/prompt_logic.py

@@ -1,11 +1,11 @@
 """
-PromptForge — Core prompt generation logic (v3.0).
-Adds persona-aware generation, style variants, user constraints, and explanation.
+PromptForge v4.0 — Core prompt generation engine.
+Upgrades: 2 new personas (devops_eng, ml_engineer), expanded heuristics,
+          richer constraint patterns, word-count tracking, auto-tagging,
+          multi-example support, and improved explanation quality.
 """
 from __future__ import annotations
-import re
-import uuid
-import textwrap
+import re, uuid, textwrap
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -15,71 +15,89 @@ from schemas import (
 )
 
 
-# ── Persona definitions ──────────────────────────────────────────────────────
+# ── Persona role strings ──────────────────────────────────────────────────────
 
 _PERSONA_ROLES: Dict[PersonaType, str] = {
     PersonaType.default:        "General AI Assistant",
-    PersonaType.senior_dev:     "Senior Software Engineer with 10+ years of experience",
-    PersonaType.data_scientist: "Senior Data Scientist specializing in ML/AI pipelines",
-    PersonaType.tech_writer:    "Technical Writer producing clear, precise developer documentation",
-    PersonaType.product_mgr:    "Product Manager focused on user-centric, data-driven decisions",
-    PersonaType.security_eng:   "Security Engineer with expertise in threat modeling and secure coding",
-    PersonaType.custom:         "",  # filled from custom_persona field
+    PersonaType.senior_dev:     "Senior Software Engineer with 10+ years of full-stack experience",
+    PersonaType.data_scientist: "Senior Data Scientist specialising in ML/AI pipelines and statistical analysis",
+    PersonaType.tech_writer:    "Technical Writer producing clear, precise developer documentation and tutorials",
+    PersonaType.product_mgr:    "Product Manager focused on user-centric, data-driven decision making",
+    PersonaType.security_eng:   "Security Engineer with expertise in threat modelling, OWASP, and secure-by-design systems",
+    PersonaType.devops_eng:     "DevOps / Platform Engineer specialising in CI/CD, Kubernetes, and cloud-native infrastructure",
+    PersonaType.ml_engineer:    "Machine Learning Engineer experienced in LLM fine-tuning, model deployment, and MLOps",
+    PersonaType.custom:         "",
 }
 
 _STYLE_DESCRIPTIONS: Dict[StyleType, str] = {
-    StyleType.professional: "Professional and clear; balance technical accuracy with readability. Use precise language.",
-    StyleType.concise:      "Ultra-concise; bullet points preferred; zero filler words. Every sentence must add value.",
-    StyleType.detailed:     "Thoroughly detailed; explain every decision; include rationale, alternatives considered, and trade-offs.",
-    StyleType.beginner:     "Beginner-friendly; avoid jargon; explain acronyms; use analogies and step-by-step breakdowns.",
-    StyleType.formal:       "Formal prose; structured with headings; professional tone suitable for reports or specifications.",
-    StyleType.creative:     "Engaging and vivid; use narrative techniques; make dry content interesting without sacrificing accuracy.",
+    StyleType.professional: "Professional and precise — balance technical accuracy with readability. Use exact terminology.",
+    StyleType.concise:      "Ultra-concise — bullet points preferred, zero filler. Every word must earn its place.",
+    StyleType.detailed:     "Thoroughly detailed — explain every decision, include rationale, alternatives, and trade-offs.",
+    StyleType.beginner:     "Beginner-friendly — avoid jargon, explain every acronym, use analogies and step-by-step breakdowns.",
+    StyleType.formal:       "Formal prose — structured with headings, professional tone suitable for specifications or reports.",
+    StyleType.creative:     "Engaging and vivid — use narrative techniques to make even dry content memorable without sacrificing accuracy.",
 }
 
 _HEURISTIC_ROLES: List[Tuple[List[str], str]] = [
-    (["react", "vue", "angular", "component", "frontend", "ui", "tailwind", "svelte"], "Senior Frontend Engineer"),
-    (["api", "rest", "fastapi", "flask", "django", "backend", "endpoint", "graphql"], "Senior Backend Engineer"),
-    (["sql", "database", "postgres", "mongo", "redis", "query", "schema", "orm"], "Database Architect"),
-    (["test", "unittest", "pytest", "jest", "coverage", "tdd", "bdd", "e2e"], "QA / Test Automation Engineer"),
-    (["devops", "docker", "kubernetes", "ci/cd", "deploy", "cloud", "terraform", "helm"], "DevOps / Cloud Engineer"),
-    (["machine learning", "ml", "model", "training", "dataset", "neural", "pytorch", "tensorflow", "llm"], "Machine Learning Engineer"),
-    (["data analysis", "pandas", "numpy", "visualization", "chart", "plot", "etl", "pipeline"], "Data Scientist"),
-    (["security", "auth", "oauth", "jwt", "encrypt", "pentest", "vulnerability", "cve"], "Security Engineer"),
-    (["write", "blog", "article", "essay", "copy", "content", "documentation", "readme"], "Technical Writer"),
-    (["summarize", "summary", "tldr", "abstract", "extract", "distill"], "Technical Summarizer"),
-    (["translate", "localize", "i18n", "l10n", "language"], "Multilingual Specialist"),
-    (["product", "roadmap", "user story", "backlog", "sprint", "okr", "kpi"], "Product Manager"),
-    (["sql", "bi", "dashboard", "report", "analytics", "metrics"], "Business Intelligence Analyst"),
+    (["react", "vue", "angular", "svelte", "nextjs", "remix", "component", "frontend", "ui", "ux", "tailwind", "css", "html"], "Senior Frontend Engineer"),
+    (["api", "rest", "restful", "fastapi", "flask", "django", "express", "graphql", "grpc", "backend", "server", "endpoint", "microservice"], "Senior Backend Engineer"),
+    (["sql", "database", "postgres", "postgresql", "mysql", "mongo", "mongodb", "redis", "dynamodb", "query", "schema", "orm", "migration"], "Database Architect"),
+    (["test", "unittest", "pytest", "jest", "cypress", "playwright", "coverage", "tdd", "bdd", "e2e", "integration test", "mock"], "QA / Test Automation Engineer"),
+    (["docker", "kubernetes", "k8s", "helm", "terraform", "ansible", "ci/cd", "github actions", "jenkins", "deploy", "cloud", "aws", "gcp", "azure", "infra"], "DevOps / Cloud Engineer"),
+    (["machine learning", "ml", "deep learning", "neural", "train", "fine-tune", "dataset", "pytorch", "tensorflow", "hugging face", "llm", "transformer", "embedding"], "Machine Learning Engineer"),
+    (["data analysis", "pandas", "numpy", "visualization", "matplotlib", "seaborn", "plotly", "chart", "plot", "etl", "pipeline", "spark", "dbt"], "Data Scientist"),
+    (["security", "pentest", "vulnerability", "cve", "owasp", "auth", "oauth", "jwt", "encrypt", "decrypt", "ssl", "tls", "xss", "csrf"], "Security Engineer"),
+    (["write", "blog", "article", "essay", "copy", "content", "documentation", "readme", "wiki", "tutorial", "guide", "how-to"], "Technical Writer"),
+    (["summarize", "summary", "tldr", "abstract", "extract", "distill", "recap"], "Technical Summarizer"),
+    (["translate", "localize", "i18n", "l10n", "language", "multilingual"], "Multilingual Specialist"),
+    (["product", "roadmap", "user story", "backlog", "sprint", "okr", "kpi", "stakeholder", "feature", "discovery"], "Product Manager"),
+    (["sql", "bi", "dashboard", "report", "analytics", "metrics", "tableau", "looker", "powerbi"], "Business Intelligence Analyst"),
+    (["mobile", "ios", "android", "swift", "kotlin", "react native", "flutter", "expo"], "Mobile Engineer"),
+    (["blockchain", "smart contract", "solidity", "ethereum", "web3", "defi", "nft", "dao"], "Blockchain / Web3 Engineer"),
+    (["game", "unity", "unreal", "godot", "shader", "physics", "rendering", "game design"], "Game Developer"),
 ]
 
 _CONSTRAINT_PATTERNS: List[Tuple[str, str]] = [
-    (r"\btypescript\b",                  "Use TypeScript with strict mode enabled."),
-    (r"\bpython\b",                      "Use Python 3.10+; follow PEP-8 style guide."),
-    (r"\btailwind(?:css)?\b",                    "Use TailwindCSS utility classes only; avoid custom CSS unless unavoidable."),
-    (r"\bunit test[s]?\b|\bjest\b|\bpytest\b", "Include comprehensive unit tests with ≥80% coverage."),
-    (r"\bjson\b",                        "All structured data must be valid, parseable JSON."),
-    (r"\baccessib\w+\b",                 "Ensure WCAG 2.1 AA accessibility compliance."),
-    (r"\bresponsive\b",                  "Design must be fully responsive for mobile, tablet, and desktop."),
-    (r"\bdocker\b",                      "Provide a Dockerfile and docker-compose.yml."),
-    (r"\bno comment[s]?\b",              "Do not include inline code comments."),
-    (r"\bcomment[s]?\b",                 "Include clear, concise inline comments explaining non-obvious logic."),
-    (r"\berror handling\b|\bexception\b","Include comprehensive error/exception handling with meaningful messages."),
-    (r"\blogg?ing\b",                    "Add structured logging at appropriate severity levels."),
-    (r"\bpagination\b",                  "Implement cursor- or offset-based pagination."),
-    (r"\bcach(e|ing)\b",                 "Implement caching with appropriate TTL and invalidation."),
-    (r"\bsecurity\b|\bauth\b",           "Follow OWASP security guidelines; validate and sanitize all inputs."),
+    (r"\btypescript\b",                    "Use TypeScript with strict mode enabled (`strict: true` in tsconfig)."),
+    (r"\bpython\b",                        "Use Python 3.11+; follow PEP-8 style guide; include type hints everywhere."),
+    (r"\btailwind(?:css)?\b",              "Use TailwindCSS utility classes exclusively; avoid custom CSS unless unavoidable."),
+    (r"\bunit test[s]?\b|\bjest\b|\bpytest\b|\bvitest\b",
+                                           "Include comprehensive unit tests with ≥80% line coverage."),
+    (r"\bjson\b",                          "All structured data must be valid, parseable JSON; validate with a schema."),
+    (r"\baccessib\w+\b|\bwcag\b|\ba11y\b", "Ensure WCAG 2.1 AA accessibility compliance (ARIA labels, keyboard nav, contrast ≥4.5:1)."),
+    (r"\bresponsive\b",                    "Design must be fully responsive across mobile (320px+), tablet, and desktop."),
+    (r"\bdocker\b",                        "Provide a multi-stage `Dockerfile` and a `docker-compose.yml`."),
+    (r"\bno comment[s]?\b",               "Do not include inline code comments."),
+    (r"\bcomment[s]?\b",                  "Include clear, concise inline comments explaining every non-obvious logic block."),
+    (r"\berror handling\b|\bexception\b", "Include comprehensive error/exception handling with user-friendly messages and structured logging."),
+    (r"\blogg?ing\b",                     "Add structured logging (JSON format preferred) at appropriate severity levels."),
+    (r"\bpagination\b",                   "Implement cursor- or offset-based pagination with configurable page size."),
+    (r"\bcach(e|ing)\b",                  "Implement caching with appropriate TTL, cache-key strategy, and invalidation logic."),
+    (r"\bsecurity\b|\bauth(?:entication|orization)?\b",
+                                          "Follow OWASP Top-10 guidelines; validate and sanitize all inputs; never trust client data."),
+    (r"\bdark ?mode\b",                   "Support both light and dark colour schemes via CSS custom properties or Tailwind dark:."),
+    (r"\bi18n\b|\binternat\w+\b",         "Internationalise all user-facing strings; use i18n library (e.g., react-i18next, Fluent)."),
+    (r"\bperformance\b|\boptimiz\w+\b",   "Profile and optimise for performance; include Big-O analysis where relevant."),
+    (r"\bgit\b|\bversion control\b",      "Include `.gitignore`, conventional commit messages, and branch-naming guidance."),
+    (r"\bwebsocket\b|\breal.?time\b|\bsse\b",
+                                          "Use WebSockets or Server-Sent Events for real-time communication; handle reconnection."),
+    (r"\bci/?cd\b|\bgithub actions\b|\bpipeline\b",
+                                          "Define a CI/CD pipeline (GitHub Actions preferred); include lint, test, and build stages."),
+    (r"\bmigration\b|\bschema change\b",  "Provide reversible database migrations with rollback scripts."),
+    (r"\benv(?:ironment)? var\b|\.env\b", "Document all environment variables in `.env.example`; never hard-code secrets."),
 ]
 
 _SAFETY_DEFAULTS: List[str] = [
     "Do not produce harmful, misleading, or unethical content.",
-    "Respect intellectual property; do not reproduce copyrighted material verbatim.",
-    "If the request is ambiguous or potentially harmful, ask for clarification.",
+    "Respect intellectual property; never reproduce copyrighted material verbatim.",
+    "If the request is ambiguous or potentially harmful, ask for clarification before proceeding.",
     "Adhere to Google AI Studio usage policies and Responsible AI guidelines.",
     "Do not expose sensitive data, API keys, passwords, or PII in any output.",
+    "Prefer established, well-maintained libraries over custom implementations for security-critical code.",
 ]
 
 
-# ── Public API ───────────────────────────────────────────────────────────────
+# ── Public API ────────────────────────────────────────────────────────────────
 
 def build_manifest(
     instruction: str,
@@ -92,18 +110,19 @@ def build_manifest(
     user_constraints: Optional[List[str]] = None,
     settings_id: Optional[str] = None,
 ) -> PromptManifest:
-    """Transform a raw instruction into a full PromptManifest."""
     prompt_id = existing_id or str(uuid.uuid4())
-    lower = instruction.lower()
+    lower     = instruction.lower()
+    now       = datetime.utcnow()
 
-    role = _resolve_role(persona, custom_persona, lower)
-    task = _format_task(instruction)
-    input_fmt  = _infer_input_format(lower)
-    output_fmt = _infer_output_format(lower)
+    role        = _resolve_role(persona, custom_persona, lower)
+    task        = _format_task(instruction)
+    input_fmt   = _infer_input_format(lower)
+    output_fmt  = _infer_output_format(lower)
     constraints = _build_constraints(lower, user_constraints or [])
-    style_desc = _STYLE_DESCRIPTIONS.get(style, _STYLE_DESCRIPTIONS[StyleType.professional])
-    safety = list(_SAFETY_DEFAULTS)
-    examples = _build_examples(lower, role)
+    style_desc  = _STYLE_DESCRIPTIONS.get(style, _STYLE_DESCRIPTIONS[StyleType.professional])
+    safety      = list(_SAFETY_DEFAULTS)
+    examples    = _build_examples(lower, role)
+    auto_tags   = _auto_tag(lower)
 
     raw_text = _render_raw_prompt(
         role=role, task=task, input_fmt=input_fmt, output_fmt=output_fmt,
@@ -114,6 +133,7 @@ def build_manifest(
         role=role, instruction=instruction, constraints=constraints,
         persona=persona, style=style,
     )
+    word_count = len(raw_text.split())
 
     structured = StructuredPrompt(
         role=role, task=task,
@@ -121,12 +141,14 @@ def build_manifest(
         constraints=constraints, style=style_desc,
         safety=safety, examples=examples,
         raw_prompt_text=raw_text,
+        word_count=word_count,
     )
 
     return PromptManifest(
         prompt_id=prompt_id,
         version=version,
-        created_at=datetime.utcnow(),
+        created_at=now,
+        updated_at=now,
         instruction=instruction,
         status="pending",
         structured_prompt=structured,
@@ -134,11 +156,11 @@ def build_manifest(
         settings_id=settings_id,
         persona_used=persona,
         style_used=style,
+        tags=auto_tags,
     )
 
 
 def build_manifest_from_settings(settings: InstructionSettings) -> PromptManifest:
-    """Convenience: build a manifest from a saved InstructionSettings object."""
     return build_manifest(
         instruction=settings.instruction,
         extra_context=settings.extra_context,
@@ -152,24 +174,26 @@ def build_manifest_from_settings(settings: InstructionSettings) -> PromptManifes
 
 def apply_edits(manifest: PromptManifest, edits: Dict[str, Any]) -> PromptManifest:
     sp = manifest.structured_prompt.model_copy(update=edits)
+    new_raw = _render_raw_prompt(
+        role=sp.role, task=sp.task,
+        input_fmt=sp.input_format, output_fmt=sp.output_format,
+        constraints=sp.constraints, style=sp.style,
+        safety=sp.safety, examples=sp.examples,
+    )
     sp = sp.model_copy(update={
-        "raw_prompt_text": _render_raw_prompt(
-            role=sp.role, task=sp.task,
-            input_fmt=sp.input_format, output_fmt=sp.output_format,
-            constraints=sp.constraints, style=sp.style,
-            safety=sp.safety, examples=sp.examples,
-        )
+        "raw_prompt_text": new_raw,
+        "word_count": len(new_raw.split()),
+    })
+    return manifest.model_copy(update={
+        "structured_prompt": sp,
+        "status": "approved",
+        "updated_at": datetime.utcnow(),
     })
-    return manifest.model_copy(update={"structured_prompt": sp, "status": "approved"})
 
 
-def refine_with_feedback(
-    manifest: PromptManifest,
-    feedback: str,
-) -> PromptManifest:
-    """Incorporate textual feedback and bump the version."""
+def refine_with_feedback(manifest: PromptManifest, feedback: str) -> PromptManifest:
     return build_manifest(
-        instruction=manifest.instruction + " " + feedback,
+        instruction=manifest.instruction + "\n\nREFINEMENT REQUEST: " + feedback,
         version=manifest.version + 1,
         existing_id=manifest.prompt_id,
         persona=manifest.persona_used,
@@ -179,7 +203,6 @@ def refine_with_feedback(
 
 
 def generate_explanation(manifest: PromptManifest) -> Tuple[str, List[str]]:
-    """Return (explanation_text, key_decisions[]) for a manifest."""
     explanation = manifest.explanation or _generate_explanation(
         role=manifest.structured_prompt.role,
         instruction=manifest.instruction,
@@ -191,14 +214,13 @@ def generate_explanation(manifest: PromptManifest) -> Tuple[str, List[str]]:
     return explanation, decisions
 
 
-# ── Private helpers ──────────────────────────────────────────────────────────
+# ── Private helpers ───────────────────────────────────────────────────────────
 
 def _resolve_role(persona: PersonaType, custom_persona: Optional[str], lower: str) -> str:
     if persona == PersonaType.custom and custom_persona:
         return custom_persona
     if persona != PersonaType.default:
         return _PERSONA_ROLES.get(persona, "General AI Assistant")
-    # Heuristic fallback
     for keywords, role in _HEURISTIC_ROLES:
         if any(kw in lower for kw in keywords):
             return role
@@ -213,108 +235,163 @@ def _format_task(instruction: str) -> str:
 
 
 def _infer_input_format(lower: str) -> str:
-    if any(k in lower for k in ["json", "object", "dict", "payload"]):
-        return "A JSON object containing the relevant fields described in the task."
-    if any(k in lower for k in ["file", "upload", "csv", "pdf", "spreadsheet"]):
-        return "A file (provide file path, URL, or base64-encoded content)."
-    if any(k in lower for k in ["image", "photo", "screenshot", "diagram", "figure"]):
-        return "An image provided as a URL or base64-encoded string."
-    if any(k in lower for k in ["url", "link", "website", "webpage"]):
-        return "A URL or list of URLs to process."
-    return "A plain-text string describing the user's request or content to process."
+    if any(k in lower for k in ["json", "object", "dict", "payload", "request body"]):
+        return "A JSON object containing the relevant fields described in the task. Validate the schema before processing."
+    if any(k in lower for k in ["file", "upload", "csv", "pdf", "spreadsheet", "xlsx"]):
+        return "A file provided as a path, URL, or base64-encoded string. Include MIME type where relevant."
+    if any(k in lower for k in ["image", "photo", "screenshot", "diagram", "figure", "svg"]):
+        return "An image as a URL or base64-encoded string. Specify width, height, and format metadata."
+    if any(k in lower for k in ["url", "link", "website", "webpage", "endpoint"]):
+        return "A URL or list of URLs. Validate reachability and parse with appropriate scraping/HTTP tools."
+    if any(k in lower for k in ["sql", "query", "database"]):
+        return "A database schema definition plus a natural-language query or set of requirements."
+    return "A plain-text string describing the user's request, requirements, or content to process."
 
 
 def _infer_output_format(lower: str) -> str:
     if any(k in lower for k in ["json", "structured", "object", "dict"]):
-        return "A well-formatted JSON object with clearly named keys. No extra prose outside the JSON block."
+        return "A well-formatted JSON object with clearly named, camelCase keys. No prose outside the JSON block. Include a JSON schema definition."
     if any(k in lower for k in ["markdown", "md", "readme", "documentation", "doc"]):
-        return "A Markdown-formatted document with appropriate headers, code blocks, and lists."
+        return "A Markdown-formatted document with H1/H2/H3 hierarchy, fenced code blocks, and a table of contents."
     if any(k in lower for k in ["code", "script", "function", "class", "component", "snippet"]):
-        return "Source code inside a properly labeled fenced code block. Include a brief explanation before and after."
-    if any(k in lower for k in ["list", "bullet", "steps", "enumerat"]):
-        return "A numbered or bulleted list with concise, actionable items."
-    if any(k in lower for k in ["report", "analysis", "summary"]):
-        return "A structured report with an executive summary, body sections, and key findings."
-    if any(k in lower for k in ["table", "comparison", "matrix"]):
-        return "A Markdown table with clearly labeled columns and rows."
-    return "A clear, well-structured plain-text response."
+        return "Source code in a properly labelled fenced code block. Add a brief explanation before AND a usage example after."
+    if any(k in lower for k in ["list", "bullet", "steps", "enumerat", "checklist"]):
+        return "A numbered or bulleted list with concise, actionable items. Group related items under subheadings."
+    if any(k in lower for k in ["report", "analysis", "summary", "audit"]):
+        return "A structured report: Executive Summary → Findings → Recommendations → Appendix."
+    if any(k in lower for k in ["table", "comparison", "matrix", "grid"]):
+        return "A Markdown table with descriptive column headers, aligned cells, and a summary row."
+    if any(k in lower for k in ["email", "letter", "message", "memo"]):
+        return "Formatted email/letter with Subject, Greeting, Body, Sign-off. Formal register unless instructed otherwise."
+    return "A clear, well-structured plain-text response with logical section breaks."
 
 
 def _build_constraints(lower: str, user_constraints: List[str]) -> List[str]:
     found: List[str] = []
     for pattern, constraint in _CONSTRAINT_PATTERNS:
-        if re.search(pattern, lower):
+        if re.search(pattern, lower, re.IGNORECASE):
             found.append(constraint)
-    # Merge with user-provided constraints (dedup)
+    seen = set(found)
     for uc in user_constraints:
-        if uc.strip() and uc.strip() not in found:
-            found.append(uc.strip())
+        clean = uc.strip()
+        if clean and clean not in seen:
+            found.append(clean)
+            seen.add(clean)
     if not found:
-        found.append("Keep the response concise and directly relevant to the task.")
+        found.append("Keep the response concise and directly relevant to the stated task.")
     return found
 
 
+def _auto_tag(lower: str) -> List[str]:
+    """Infer tags from instruction text for display in history."""
+    candidates = {
+        "react": ["react", "jsx", "tsx"],
+        "typescript": ["typescript", "tsx"],
+        "python": ["python", "fastapi", "flask", "django"],
+        "testing": ["test", "pytest", "jest", "coverage"],
+        "devops": ["docker", "kubernetes", "ci/cd", "terraform"],
+        "security": ["security", "auth", "jwt", "owasp"],
+        "ml": ["machine learning", "llm", "pytorch", "tensorflow"],
+        "frontend": ["css", "html", "tailwind", "ui", "component"],
+        "backend": ["api", "backend", "server", "endpoint"],
+        "database": ["sql", "database", "postgres", "mongo"],
+        "mobile": ["ios", "android", "react native", "flutter"],
+        "writing": ["blog", "article", "documentation", "readme"],
+    }
+    found = []
+    for tag, keywords in candidates.items():
+        if any(kw in lower for kw in keywords):
+            found.append(tag)
+    return found[:6]
+
+
 def _build_examples(lower: str, role: str) -> Optional[List[Dict[str, str]]]:
+    examples = []
     if "react" in lower or "component" in lower:
-        return [{"input": "Create a Button component.",
-                 "output": "```tsx\ninterface ButtonProps { label: string; onClick: () => void; }\nexport const Button = ({ label, onClick }: ButtonProps) => (\n  <button onClick={onClick} className='px-4 py-2 bg-indigo-600 text-white rounded'>{label}</button>\n);\n```"}]
+        examples.append({
+            "input":  "Create a reusable `<Button>` component.",
+            "output": (
+                "```tsx\ninterface ButtonProps {\n  label: string;\n  variant?: 'primary' | 'secondary' | 'danger';\n"
+                "  onClick: () => void;\n  disabled?: boolean;\n}\n\nexport const Button = ({\n  label, variant = 'primary', onClick, disabled = false\n}: ButtonProps) => (\n"
+                "  <button\n    onClick={onClick}\n    disabled={disabled}\n    aria-disabled={disabled}\n"
+                "    className={`px-4 py-2 rounded font-semibold transition ${{\n      primary: 'bg-indigo-600 text-white hover:bg-indigo-700',\n"
+                "      secondary: 'bg-gray-100 text-gray-800 hover:bg-gray-200',\n      danger: 'bg-red-600 text-white hover:bg-red-700',\n    }}[variant]}`}\n  >\n    {label}\n  </button>\n);\n```"
+            ),
+        })
     if "summarize" in lower or "summary" in lower:
-        return [{"input": "Summarize: 'The quick brown fox jumps over the lazy dog.'",
-                 "output": "A fox jumps over a dog."}]
+        examples.append({
+            "input":  "Summarise the following paragraph in one sentence.",
+            "output": "**Original**: 'The Apollo 11 mission…' → **Summary**: 'Apollo 11 was the first crewed mission to land on the Moon, on 20 July 1969.'",
+        })
     if "fastapi" in lower or ("api" in lower and "endpoint" in lower):
-        return [{"input": "Create a GET /users endpoint.",
-                 "output": '```python\n@router.get("/users", response_model=list[UserOut])\nasync def list_users(db: Session = Depends(get_db)):\n    return db.query(User).all()\n```'}]
-    if "sql" in lower or "query" in lower:
-        return [{"input": "Get all users created this month.",
-                 "output": "```sql\nSELECT * FROM users\nWHERE created_at >= DATE_TRUNC('month', NOW());\n```"}]
-    return None
+        examples.append({
+            "input":  "Create a `GET /users` endpoint.",
+            "output": (
+                "```python\nfrom fastapi import APIRouter, Depends, HTTPException, status\n"
+                "from sqlalchemy.orm import Session\nfrom .schemas import UserOut\nfrom .models import User\nfrom .database import get_db\n\n"
+                "router = APIRouter(prefix='/users', tags=['Users'])\n\n"
+                "@router.get('/', response_model=list[UserOut], summary='List all users')\nasync def list_users(\n"
+                "    skip: int = 0, limit: int = 100,\n    db: Session = Depends(get_db),\n) -> list[User]:\n"
+                "    return db.query(User).offset(skip).limit(limit).all()\n```"
+            ),
+        })
+    if ("sql" in lower or "query" in lower) and not examples:
+        examples.append({
+            "input":  "Get all users registered in the last 30 days.",
+            "output": "```sql\nSELECT id, email, created_at\nFROM users\nWHERE created_at >= NOW() - INTERVAL '30 days'\nORDER BY created_at DESC;\n```",
+        })
+    return examples if examples else None
 
 
 def _generate_explanation(
-    role: str,
-    instruction: str,
-    constraints: List[str],
-    persona: PersonaType,
-    style: StyleType,
+    role: str, instruction: str, constraints: List[str],
+    persona: PersonaType, style: StyleType,
 ) -> str:
-    lines = [
-        f"This prompt was engineered to elicit optimal output from a '{role}' persona.",
-        "",
-        f"**Why this role?** The instruction '{instruction[:80]}...' contains terminology "
-        f"most naturally handled by a {role}. Assigning the right role primes the AI's "
-        f"response patterns toward domain-specific knowledge and conventions.",
-        "",
-        f"**Why the '{style.value}' style?** The selected style ({style.value}) ensures the "
-        f"output matches the intended audience — adjusting verbosity, formality, and "
-        f"technical depth accordingly.",
-        "",
-        "**Why these constraints?**",
-    ]
-    for c in constraints[:4]:
-        lines.append(f"- {c}")
-    lines += [
-        "",
-        "**Safety section:** Every prompt includes guardrails aligned with Google AI Studio "
-        "Responsible AI policies. These prevent generation of harmful, misleading, or "
-        "policy-violating content.",
-        "",
-        "**Few-shot examples:** Where applicable, a concrete input→output example is included "
-        "to guide the model's output format and quality level.",
-    ]
-    return "\n".join(lines)
+    instr_preview = instruction[:90].rstrip() + ("…" if len(instruction) > 90 else "")
+    style_desc = _STYLE_DESCRIPTIONS.get(style, "")[:80]
+    constraint_bullets = "\n".join(f"  • {c}" for c in constraints[:5])
+    if len(constraints) > 5:
+        constraint_bullets += f"\n  • … and {len(constraints) - 5} more"
+
+    return textwrap.dedent(f"""\
+        **Role Assignment — why "{role}"?**
+        The instruction "{instr_preview}" contains domain signals that map most precisely to a {role}. \
+        Assigning the correct expert role primes the model to adopt the right vocabulary, \
+        depth conventions, and problem-solving heuristics for this task.
+
+        **Style — "{style.value}"**
+        {style_desc}
+        This style was applied to calibrate verbosity, formality, and technical depth to \
+        the apparent audience and intent of the instruction.
+
+        **Constraints applied ({len(constraints)} total)**
+        These were inferred from keywords in the instruction and merged with any user-defined rules:
+        {constraint_bullets}
+
+        **Safety guardrails**
+        Six default safety rules are always injected, aligned with Google AI Studio's Responsible AI \
+        policies. They prevent harmful content, IP violations, and accidental data exposure.
+
+        **Few-shot examples**
+        Where domain patterns were detected (React, FastAPI, SQL, etc.), concrete input→output \
+        examples are injected to anchor the model's output format and quality expectations.
+    """).strip()
 
 
 def _extract_key_decisions(manifest: PromptManifest) -> List[str]:
     sp = manifest.structured_prompt
     decisions = [
-        f"Role assigned: {sp.role}",
-        f"Style applied: {manifest.style_used.value} — {_STYLE_DESCRIPTIONS[manifest.style_used][:60]}…",
-        f"Output format type: {sp.output_format[:60]}…",
-        f"{len(sp.constraints)} constraint(s) inferred + user-defined",
-        f"{len(sp.safety)} safety guardrail(s) applied",
+        f"Role: {sp.role}",
+        f"Style: {manifest.style_used.value} — {_STYLE_DESCRIPTIONS[manifest.style_used][:55]}…",
+        f"Output type: {sp.output_format[:60]}…",
+        f"{len(sp.constraints)} constraint(s) applied",
+        f"{len(sp.safety)} safety guardrail(s) injected",
+        f"~{sp.word_count} words in generated prompt",
     ]
     if sp.examples:
-        decisions.append(f"{len(sp.examples)} few-shot example(s) injected")
+        decisions.append(f"{len(sp.examples)} few-shot example(s) included")
+    if manifest.tags:
+        decisions.append(f"Auto-tagged: {', '.join(manifest.tags)}")
     return decisions
 
 
@@ -325,24 +402,40 @@ def _render_raw_prompt(
     extra_context: Optional[str] = None,
 ) -> str:
     lines = [
-        f"## ROLE\nYou are a {role}.",
-        f"\n## TASK\n{task}",
-        f"\n## INPUT FORMAT\n{input_fmt}",
-        f"\n## OUTPUT FORMAT\n{output_fmt}",
-        "\n## CONSTRAINTS",
+        f"## ROLE",
+        f"You are a {role}.",
+        "",
+        f"## TASK",
+        task,
+        "",
+        f"## INPUT FORMAT",
+        input_fmt,
+        "",
+        f"## OUTPUT FORMAT",
+        output_fmt,
+        "",
+        "## CONSTRAINTS",
     ]
     for i, c in enumerate(constraints, 1):
         lines.append(f"{i}. {c}")
-    lines.append(f"\n## STYLE & TONE\n{style}")
-    lines.append("\n## SAFETY GUIDELINES")
+    lines += [
+        "",
+        "## STYLE & TONE",
+        style,
+        "",
+        "## SAFETY GUIDELINES",
+    ]
     for i, s in enumerate(safety, 1):
         lines.append(f"{i}. {s}")
     if extra_context:
-        lines.append(f"\n## ADDITIONAL CONTEXT\n{extra_context}")
+        lines += ["", "## ADDITIONAL CONTEXT", extra_context]
     if examples:
-        lines.append("\n## FEW-SHOT EXAMPLES")
+        lines += ["", "## FEW-SHOT EXAMPLES"]
         for ex in examples:
-            lines.append(f"**Input:** {ex['input']}")
-            lines.append(f"**Output:** {ex['output']}\n")
-    lines.append("\n---\n*Prompt generated by PromptForge v3.0 — compatible with Google AI Studio.*")
+            lines += [f"**Input:** {ex['input']}", f"**Expected Output:**\n{ex['output']}", ""]
+    lines += [
+        "",
+        "---",
+        "*Generated by PromptForge v4.0 — optimised for Google AI Studio.*",
+    ]
     return "\n".join(lines)

backend/requirements.txt

@@ -1,8 +1,19 @@
-fastapi>=0.111.0
-uvicorn[standard]>=0.29.0
-pydantic>=2.7.0
-httpx>=0.27.0
+# PromptForge v4.0 — Python dependencies
+# Install: pip install -r requirements.txt
+
+# ── Core framework ────────────────────────────────────────────────────
+fastapi>=0.111.0,<0.120.0
+uvicorn[standard]>=0.29.0,<0.35.0
+pydantic>=2.7.0,<3.0.0
 python-multipart>=0.0.9
+
+# ── HTTP client (AI providers) ────────────────────────────────────────
+httpx>=0.27.0,<0.30.0
+
+# ── Dev / testing ─────────────────────────────────────────────────────
 pytest>=8.2.0
 pytest-asyncio>=0.23.0
-httpx>=0.27.0
+httpx>=0.27.0       # also needed by TestClient
+
+# ── Optional: static file serving ────────────────────────────────────
+aiofiles>=23.2.1

backend/schemas.py

@@ -1,15 +1,16 @@
 """
-PromptForge — Pydantic schemas (v3.0)
-Adds InstructionSettings, ExplainResponse, and EnvVarConfig.
+PromptForge v4.0 — Pydantic schemas
+Upgrades: batch generation, stats endpoint, search/filter, duplicate,
+          tag management, provider model selection, and theme preference.
 """
 from __future__ import annotations
 from typing import Any, Dict, List, Optional
 from datetime import datetime
 from enum import Enum
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 
-# ── Enumerations ────────────────────────────────────────────────────────────
+# ── Enumerations ─────────────────────────────────────────────────────────────
 
 class OutputFormat(str, Enum):
     text = "text"
@@ -17,18 +18,20 @@ class OutputFormat(str, Enum):
     both = "both"
 
 class AIProvider(str, Enum):
-    none = "none"
+    none        = "none"
     huggingface = "huggingface"
-    google = "google"
+    google      = "google"
 
 class PersonaType(str, Enum):
-    default       = "default"
-    senior_dev    = "senior_dev"
-    data_scientist= "data_scientist"
-    tech_writer   = "tech_writer"
-    product_mgr   = "product_mgr"
-    security_eng  = "security_eng"
-    custom        = "custom"
+    default        = "default"
+    senior_dev     = "senior_dev"
+    data_scientist = "data_scientist"
+    tech_writer    = "tech_writer"
+    product_mgr    = "product_mgr"
+    security_eng   = "security_eng"
+    devops_eng     = "devops_eng"
+    ml_engineer    = "ml_engineer"
+    custom         = "custom"
 
 class StyleType(str, Enum):
     professional = "professional"
@@ -38,192 +41,253 @@ class StyleType(str, Enum):
     formal       = "formal"
     creative     = "creative"
 
+class PromptStatus(str, Enum):
+    pending  = "pending"
+    approved = "approved"
+    exported = "exported"
+    archived = "archived"
 
-# ── InstructionSettings (the new core model) ───────────────────────────────
+
+# ── InstructionSettings ───────────────────────────────────────────────────────
 
 class InstructionSettings(BaseModel):
-    settings_id: str = Field(..., description="Unique ID for this saved instruction setting.")
-    title: str = Field(..., min_length=2, max_length=120,
-        description="Human-readable name for this instruction template.")
-    description: Optional[str] = Field(None, max_length=1000,
-        description="Optional context or notes about this setting.")
-    instruction: str = Field(..., min_length=5, max_length=8000,
-        description="The raw instruction/task text.")
-    extra_context: Optional[str] = Field(None, max_length=2000,
-        description="Additional constraints or background info.")
-    output_format: OutputFormat = Field(OutputFormat.both)
-    persona: PersonaType = Field(PersonaType.default,
-        description="The AI persona to use for generation.")
-    custom_persona: Optional[str] = Field(None, max_length=200,
-        description="Custom persona text (when persona=custom).")
-    style: StyleType = Field(StyleType.professional)
-    constraints: List[str] = Field(default_factory=list,
-        description="User-defined constraint strings.")
-    tags: List[str] = Field(default_factory=list,
-        description="Free-form tags for filtering.")
-    provider: AIProvider = Field(AIProvider.none)
-    enhance: bool = Field(False)
-    created_at: datetime = Field(default_factory=datetime.utcnow)
-    updated_at: datetime = Field(default_factory=datetime.utcnow)
-    use_count: int = Field(0, description="How many times this setting was used to generate.")
+    settings_id:   str            = Field(..., description="Unique UUID for this setting.")
+    title:         str            = Field(..., min_length=2, max_length=120)
+    description:   Optional[str] = Field(None, max_length=1000)
+    instruction:   str            = Field(..., min_length=5, max_length=8000)
+    extra_context: Optional[str] = Field(None, max_length=2000)
+    output_format: OutputFormat   = Field(OutputFormat.both)
+    persona:       PersonaType    = Field(PersonaType.default)
+    custom_persona: Optional[str] = Field(None, max_length=200)
+    style:         StyleType      = Field(StyleType.professional)
+    constraints:   List[str]      = Field(default_factory=list)
+    tags:          List[str]      = Field(default_factory=list)
+    provider:      AIProvider     = Field(AIProvider.none)
+    provider_model: Optional[str] = Field(None, max_length=120,
+        description="Override the default model for the selected provider.")
+    enhance:       bool           = Field(False)
+    is_favorite:   bool           = Field(False, description="Starred/pinned setting.")
+    created_at:    datetime       = Field(default_factory=datetime.utcnow)
+    updated_at:    datetime       = Field(default_factory=datetime.utcnow)
+    use_count:     int            = Field(0)
+    version:       int            = Field(1, description="Edit version number.")
+
+    @field_validator("tags", mode="before")
+    @classmethod
+    def normalize_tags(cls, v: List[str]) -> List[str]:
+        return [t.strip().lower() for t in v if t.strip()]
 
 
 class InstructionSettingsCreate(BaseModel):
-    """Request model — subset of InstructionSettings without auto fields."""
-    title: str = Field(..., min_length=2, max_length=120)
-    description: Optional[str] = Field(None, max_length=1000)
-    instruction: str = Field(..., min_length=5, max_length=8000)
-    extra_context: Optional[str] = Field(None, max_length=2000)
-    output_format: OutputFormat = Field(OutputFormat.both)
-    persona: PersonaType = Field(PersonaType.default)
+    title:          str            = Field(..., min_length=2, max_length=120)
+    description:    Optional[str] = Field(None, max_length=1000)
+    instruction:    str            = Field(..., min_length=5, max_length=8000)
+    extra_context:  Optional[str] = Field(None, max_length=2000)
+    output_format:  OutputFormat   = Field(OutputFormat.both)
+    persona:        PersonaType    = Field(PersonaType.default)
     custom_persona: Optional[str] = Field(None, max_length=200)
-    style: StyleType = Field(StyleType.professional)
-    constraints: List[str] = Field(default_factory=list)
-    tags: List[str] = Field(default_factory=list)
-    provider: AIProvider = Field(AIProvider.none)
-    enhance: bool = Field(False)
+    style:          StyleType      = Field(StyleType.professional)
+    constraints:    List[str]      = Field(default_factory=list)
+    tags:           List[str]      = Field(default_factory=list)
+    provider:       AIProvider     = Field(AIProvider.none)
+    provider_model: Optional[str] = Field(None, max_length=120)
+    enhance:        bool           = Field(False)
+    is_favorite:    bool           = Field(False)
 
 
 class InstructionSettingsUpdate(BaseModel):
-    title: Optional[str] = Field(None, max_length=120)
-    description: Optional[str] = None
-    instruction: Optional[str] = Field(None, min_length=5, max_length=8000)
-    extra_context: Optional[str] = None
-    output_format: Optional[OutputFormat] = None
-    persona: Optional[PersonaType] = None
-    custom_persona: Optional[str] = None
-    style: Optional[StyleType] = None
-    constraints: Optional[List[str]] = None
-    tags: Optional[List[str]] = None
-    provider: Optional[AIProvider] = None
-    enhance: Optional[bool] = None
+    title:          Optional[str]        = Field(None, max_length=120)
+    description:    Optional[str]        = None
+    instruction:    Optional[str]        = Field(None, min_length=5, max_length=8000)
+    extra_context:  Optional[str]        = None
+    output_format:  Optional[OutputFormat] = None
+    persona:        Optional[PersonaType]  = None
+    custom_persona: Optional[str]        = None
+    style:          Optional[StyleType]   = None
+    constraints:    Optional[List[str]]  = None
+    tags:           Optional[List[str]]  = None
+    provider:       Optional[AIProvider] = None
+    provider_model: Optional[str]        = None
+    enhance:        Optional[bool]       = None
+    is_favorite:    Optional[bool]       = None
 
 
 class InstructionSettingsList(BaseModel):
-    total: int
-    items: List[InstructionSettings]
+    total:     int
+    items:     List[InstructionSettings]
+    favorites: int = Field(0, description="Count of starred settings.")
 
 
-# ── Existing prompt models (unchanged) ─────────────────────────────────────
+# ── Prompt models ─────────────────────────────────────────────────────────────
 
 class GenerateRequest(BaseModel):
-    instruction: str = Field(..., min_length=5, max_length=8000)
-    output_format: OutputFormat = Field(OutputFormat.both)
-    provider: AIProvider = Field(AIProvider.none)
-    api_key: Optional[str] = Field(None)
-    enhance: bool = Field(False)
-    extra_context: Optional[str] = Field(None, max_length=2000)
-    # New fields from settings
-    persona: PersonaType = Field(PersonaType.default)
-    custom_persona: Optional[str] = Field(None, max_length=200)
-    style: StyleType = Field(StyleType.professional)
-    user_constraints: List[str] = Field(default_factory=list)
-    settings_id: Optional[str] = Field(None,
-        description="If provided, links this generation to a saved settings.")
+    instruction:     str            = Field(..., min_length=5, max_length=8000)
+    output_format:   OutputFormat   = Field(OutputFormat.both)
+    provider:        AIProvider     = Field(AIProvider.none)
+    api_key:         Optional[str] = Field(None)
+    provider_model:  Optional[str] = Field(None)
+    enhance:         bool           = Field(False)
+    extra_context:   Optional[str] = Field(None, max_length=2000)
+    persona:         PersonaType    = Field(PersonaType.default)
+    custom_persona:  Optional[str] = Field(None, max_length=200)
+    style:           StyleType      = Field(StyleType.professional)
+    user_constraints: List[str]    = Field(default_factory=list)
+    settings_id:     Optional[str] = Field(None)
 
 
 class GenerateFromSettingsRequest(BaseModel):
     settings_id: str
-    api_key: Optional[str] = Field(None,
-        description="API key (overrides env var if provided).")
+    api_key:     Optional[str] = Field(None)
+
+
+class BatchGenerateRequest(BaseModel):
+    """Generate multiple prompts in one call."""
+    requests: List[GenerateRequest] = Field(..., min_length=1, max_length=10)
 
 
 class ApproveRequest(BaseModel):
     prompt_id: str
-    edits: Optional[Dict[str, Any]] = None
+    edits:     Optional[Dict[str, Any]] = None
 
 
 class ExportRequest(BaseModel):
-    prompt_id: str
+    prompt_id:     str
     export_format: OutputFormat = Field(OutputFormat.json)
 
 
 class RefineRequest(BaseModel):
-    prompt_id: str
-    feedback: str = Field(..., min_length=3, max_length=2000)
-    provider: AIProvider = Field(AIProvider.none)
-    api_key: Optional[str] = Field(None)
+    prompt_id:  str
+    feedback:   str           = Field(..., min_length=3, max_length=2000)
+    provider:   AIProvider    = Field(AIProvider.none)
+    api_key:    Optional[str] = Field(None)
 
 
-# ── Structured prompt ───────────────────────────────────────────────────────
+class SearchRequest(BaseModel):
+    query:       str           = Field(..., min_length=1, max_length=500)
+    search_in:   List[str]     = Field(default_factory=lambda: ["instruction", "role", "task"])
+    status_filter: Optional[PromptStatus] = None
+
+
+# ── Structured prompt ─────────────────────────────────────────────────────────
 
 class StructuredPrompt(BaseModel):
-    role: str
-    task: str
-    input_format: str
+    role:          str
+    task:          str
+    input_format:  str
     output_format: str
-    constraints: List[str] = Field(default_factory=list)
-    style: str
-    safety: List[str] = Field(default_factory=list)
-    examples: Optional[List[Dict[str, str]]] = None
+    constraints:   List[str]                    = Field(default_factory=list)
+    style:         str
+    safety:        List[str]                    = Field(default_factory=list)
+    examples:      Optional[List[Dict[str, str]]] = None
     raw_prompt_text: str
+    word_count:    int = Field(0, description="Approximate word count of raw_prompt_text.")
 
 
 class PromptManifest(BaseModel):
-    prompt_id: str
-    version: int = 1
-    created_at: datetime = Field(default_factory=datetime.utcnow)
-    instruction: str
-    status: str = "pending"
+    prompt_id:         str
+    version:           int      = 1
+    created_at:        datetime = Field(default_factory=datetime.utcnow)
+    updated_at:        datetime = Field(default_factory=datetime.utcnow)
+    instruction:       str
+    status:            str      = "pending"
     structured_prompt: StructuredPrompt
     enhancement_notes: Optional[str] = None
-    explanation: Optional[str] = Field(None,
-        description="Plain-English explanation of why this prompt was structured this way.")
-    settings_id: Optional[str] = Field(None,
-        description="Linked InstructionSettings ID if generated from settings.")
-    persona_used: PersonaType = Field(PersonaType.default)
-    style_used: StyleType = Field(StyleType.professional)
+    explanation:       Optional[str] = None
+    settings_id:       Optional[str] = None
+    persona_used:      PersonaType   = Field(PersonaType.default)
+    style_used:        StyleType     = Field(StyleType.professional)
+    tags:              List[str]     = Field(default_factory=list)
+    is_favorite:       bool          = Field(False)
 
 
-# ── Response models ─────────────────────────────────────────────────────────
+# ── Response models ───────────────────────────────────────────────────────────
 
 class GenerateResponse(BaseModel):
-    success: bool
+    success:   bool
     prompt_id: str
-    manifest: PromptManifest
-    message: str = "Manifest generated — awaiting approval."
+    manifest:  PromptManifest
+    message:   str = "Manifest generated — awaiting approval."
+
+
+class BatchGenerateResponse(BaseModel):
+    success:   bool
+    total:     int
+    results:   List[GenerateResponse]
+    failed:    int = 0
 
 
 class ApproveResponse(BaseModel):
-    success: bool
-    prompt_id: str
-    message: str
+    success:          bool
+    prompt_id:        str
+    message:          str
     finalized_prompt: StructuredPrompt
 
 
 class ExportResponse(BaseModel):
-    success: bool
+    success:   bool
     prompt_id: str
-    data: Any
+    data:      Any
 
 
 class ExplainResponse(BaseModel):
-    prompt_id: str
-    explanation: str
-    key_decisions: List[str] = Field(default_factory=list,
-        description="Bullet-point list of key structural decisions made.")
+    prompt_id:     str
+    explanation:   str
+    key_decisions: List[str] = Field(default_factory=list)
 
 
 class HistoryEntry(BaseModel):
-    prompt_id: str
-    version: int
-    created_at: datetime
+    prompt_id:   str
+    version:     int
+    created_at:  datetime
+    updated_at:  datetime
     instruction: str
-    status: str
+    status:      str
     settings_id: Optional[str] = None
     explanation: Optional[str] = None
+    tags:        List[str]     = Field(default_factory=list)
+    is_favorite: bool          = False
 
 
 class HistoryResponse(BaseModel):
-    total: int
+    total:   int
     entries: List[HistoryEntry]
 
 
-# ── Env config (for UI-driven key management) ───────────────────────────────
+class SearchResult(BaseModel):
+    prompt_id:   str
+    instruction: str
+    status:      str
+    score:       float
+    snippet:     str
+
+
+class SearchResponse(BaseModel):
+    total:   int
+    results: List[SearchResult]
+
+
+class StatsResponse(BaseModel):
+    total_prompts:       int
+    total_settings:      int
+    pending_count:       int
+    approved_count:      int
+    exported_count:      int
+    archived_count:      int
+    favorite_prompts:    int
+    favorite_settings:   int
+    top_personas:        Dict[str, int]
+    top_styles:          Dict[str, int]
+    total_refinements:   int
+    avg_constraints:     float
+    uptime_since:        datetime
+
+
+# ── Env config ────────────────────────────────────────────────────────────────
 
 class EnvConfigStatus(BaseModel):
-    """Read-only status of which API keys are configured in the environment."""
-    hf_key_set: bool = Field(..., description="True if HF_API_KEY env var is present.")
-    google_key_set: bool = Field(..., description="True if GOOGLE_API_KEY env var is present.")
-    port: str = "7860"
-    version: str = "3.0"
+    hf_key_set:     bool = Field(..., description="True if HF_API_KEY is set.")
+    google_key_set: bool = Field(..., description="True if GOOGLE_API_KEY is set.")
+    port:           str  = "7860"
+    version:        str  = "4.0"
+    hf_model:       str  = "mistralai/Mistral-7B-Instruct-v0.2"
+    google_model:   str  = "gemini-1.5-flash"

backend/store.py

@@ -1,22 +1,28 @@
 """
-PromptForge — In-memory store with JSON persistence for PromptManifests.
+PromptForge v4.0 — Prompt manifest store.
+Upgrades: full-text search, stats aggregation, archive/unarchive,
+          favorite toggle, bulk-delete, and improved persistence.
 """
 from __future__ import annotations
 import json, os, logging
+from collections import Counter
 from datetime import datetime
 from pathlib import Path
 from typing import Dict, List, Optional
 
-from schemas import PromptManifest, HistoryEntry
+from schemas import PromptManifest, HistoryEntry, PromptStatus
 
 logger = logging.getLogger("promptforge.store")
 
-_DB: Dict[str, PromptManifest] = {}
-_LOG_DIR = Path(os.getenv("LOG_DIR", "logs"))
+_DB:          Dict[str, PromptManifest] = {}
+_LOG_DIR     = Path(os.getenv("LOG_DIR", "logs"))
 _LOG_DIR.mkdir(parents=True, exist_ok=True)
 _PERSIST_FILE = _LOG_DIR / "prompt_history.json"
+_STARTED_AT   = datetime.utcnow()
 
 
+# ── CRUD ─────────────────────────────────────────────────────────────────────
+
 def save(manifest: PromptManifest) -> None:
     _DB[manifest.prompt_id] = manifest
     _persist()
@@ -26,18 +32,32 @@ def get(prompt_id: str) -> Optional[PromptManifest]:
     return _DB.get(prompt_id)
 
 
-def all_entries() -> List[HistoryEntry]:
+def all_entries(
+    status_filter: Optional[str] = None,
+    tag_filter: Optional[str] = None,
+    favorites_only: bool = False,
+) -> List[HistoryEntry]:
+    items = sorted(_DB.values(), key=lambda x: x.created_at, reverse=True)
+    if status_filter:
+        items = [m for m in items if m.status == status_filter]
+    if tag_filter:
+        items = [m for m in items if tag_filter in m.tags]
+    if favorites_only:
+        items = [m for m in items if m.is_favorite]
     return [
         HistoryEntry(
             prompt_id=m.prompt_id,
             version=m.version,
             created_at=m.created_at,
+            updated_at=m.updated_at,
             instruction=m.instruction,
             status=m.status,
             settings_id=m.settings_id,
             explanation=m.explanation,
+            tags=m.tags,
+            is_favorite=m.is_favorite,
         )
-        for m in sorted(_DB.values(), key=lambda x: x.created_at, reverse=True)
+        for m in items
     ]
 
 
@@ -49,6 +69,83 @@ def delete(prompt_id: str) -> bool:
     return False
 
 
+def bulk_delete(prompt_ids: List[str]) -> int:
+    deleted = 0
+    for pid in prompt_ids:
+        if pid in _DB:
+            del _DB[pid]
+            deleted += 1
+    if deleted:
+        _persist()
+    return deleted
+
+
+def toggle_favorite(prompt_id: str) -> Optional[bool]:
+    m = _DB.get(prompt_id)
+    if not m:
+        return None
+    new_val = not m.is_favorite
+    _DB[prompt_id] = m.model_copy(update={"is_favorite": new_val, "updated_at": datetime.utcnow()})
+    _persist()
+    return new_val
+
+
+def archive(prompt_id: str) -> bool:
+    m = _DB.get(prompt_id)
+    if not m:
+        return False
+    _DB[prompt_id] = m.model_copy(update={"status": "archived", "updated_at": datetime.utcnow()})
+    _persist()
+    return True
+
+
+def search(query: str, status_filter: Optional[str] = None) -> List[dict]:
+    """Simple full-text search across instruction + role + task fields."""
+    q_lower = query.lower()
+    results = []
+    for m in _DB.values():
+        if status_filter and m.status != status_filter:
+            continue
+        sp     = m.structured_prompt
+        corpus = f"{m.instruction} {sp.role} {sp.task} {' '.join(m.tags)}".lower()
+        if q_lower in corpus:
+            idx     = corpus.find(q_lower)
+            snippet = corpus[max(0, idx - 40): idx + 80].strip()
+            results.append({
+                "prompt_id":   m.prompt_id,
+                "instruction": m.instruction[:120],
+                "status":      m.status,
+                "score":       corpus.count(q_lower) / max(1, len(corpus.split())),
+                "snippet":     f"…{snippet}…",
+            })
+    results.sort(key=lambda x: x["score"], reverse=True)
+    return results
+
+
+def get_stats() -> dict:
+    statuses   = Counter(m.status for m in _DB.values())
+    personas   = Counter(m.persona_used.value for m in _DB.values())
+    styles     = Counter(m.style_used.value for m in _DB.values())
+    refinements = sum(m.version - 1 for m in _DB.values())
+    all_constraints = [c for m in _DB.values() for c in m.structured_prompt.constraints]
+    avg_c = len(all_constraints) / max(1, len(_DB))
+    return {
+        "total_prompts":     len(_DB),
+        "pending_count":     statuses.get("pending", 0),
+        "approved_count":    statuses.get("approved", 0),
+        "exported_count":    statuses.get("exported", 0),
+        "archived_count":    statuses.get("archived", 0),
+        "favorite_prompts":  sum(1 for m in _DB.values() if m.is_favorite),
+        "top_personas":      dict(personas.most_common(5)),
+        "top_styles":        dict(styles.most_common(5)),
+        "total_refinements": refinements,
+        "avg_constraints":   round(avg_c, 1),
+        "uptime_since":      _STARTED_AT,
+    }
+
+
+# ── Persistence ───────────────────────────────────────────────────────────────
+
 def _persist() -> None:
     try:
         data = [m.model_dump(mode="json") for m in _DB.values()]

frontend/client.js

@@ -1,17 +1,21 @@
 /**
- * PromptForge v3.0 — client.js
- * Tab navigation, Generate flow, Instruction Settings CRUD, History.
+ * PromptForge v4.0 — client.js
+ * Upgrades: sidebar navigation, stats dashboard, full-text search,
+ * favorites/archive, setting duplicate, keyboard shortcuts, theme toggle,
+ * API key validation, char counters, tag suggestions, smooth transitions.
  */
 
 const API = "";
 let currentPromptId = null;
-let allSettings = [];
+let allSettings     = [];
+let favoritesFilter = false;
+
 const $ = id => document.getElementById(id);
+const esc = s => String(s ?? "").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
 const show = el => el?.classList.remove("hidden");
 const hide = el => el?.classList.add("hidden");
-const esc  = s  => String(s ?? "").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");
 
-/* ── API Fetch ─────────────────────────────────────────────────────── */
+/* ── API fetch ──────────────────────────────────────────────────────── */
 async function apiFetch(path, method = "GET", body = null) {
   const opts = { method, headers: { "Content-Type": "application/json" } };
   if (body) opts.body = JSON.stringify(body);
@@ -23,161 +27,248 @@ async function apiFetch(path, method = "GET", body = null) {
   return r.json();
 }
 
-/* ── Toast ─────────────────────────────────────────────────────────── */
-function toast(msg, type = "info") {
+/* ── Toast ──────────────────────────────────────────────────────────── */
+function toast(msg, type = "info", duration = 4200) {
   const icons = { success:"✅", error:"❌", info:"💡", warn:"⚠️" };
   const t = document.createElement("div");
   t.className = `toast ${type}`;
-  t.innerHTML = `<div class="toast-icon">${icons[type]||"💡"}</div><span>${msg}</span>`;
+  t.innerHTML = `<span class="toast-icon">${icons[type]||"💡"}</span><span>${msg}</span>`;
   $("toast-container").appendChild(t);
-  setTimeout(() => { t.classList.add("leaving"); t.addEventListener("animationend", () => t.remove()); }, 4200);
+  const remove = () => { t.classList.add("leaving"); t.addEventListener("animationend", () => t.remove(), {once:true}); };
+  const timer = setTimeout(remove, duration);
+  t.addEventListener("click", () => { clearTimeout(timer); remove(); });
 }
 
-/* ── Loading ───────────────────────────────────────────────────────── */
+/* ── Loading state ──────────────────────────────────────────────────── */
 function setLoading(btn, on) {
+  if (!btn) return;
   btn.disabled = on;
-  btn._orig = btn._orig || btn.innerHTML;
+  if (!btn._orig) btn._orig = btn.innerHTML;
   btn.innerHTML = on ? `<span class="spinner"></span> Working…` : btn._orig;
 }
 
-/* ── Main Tab Navigation ───────────────────────────────────────────── */
-document.querySelectorAll(".main-tab").forEach(tab => {
-  tab.addEventListener("click", () => {
-    document.querySelectorAll(".main-tab").forEach(t => t.classList.remove("active"));
-    document.querySelectorAll(".tab-page").forEach(p => p.classList.remove("active").add?.("hidden") || hide(p));
-    tab.classList.add("active");
-    const name = tab.dataset.mainTab;
-    const page = $(`tab-${name}`);
+/* ── Sidebar navigation ─────────────────────────────────────────────── */
+document.querySelectorAll(".nav-item").forEach(item => {
+  item.addEventListener("click", () => {
+    document.querySelectorAll(".nav-item").forEach(n => n.classList.remove("active"));
+    document.querySelectorAll(".page").forEach(p => { p.classList.remove("active"); hide(p); });
+    item.classList.add("active");
+    const page = $(`page-${item.dataset.page}`);
     if (page) { show(page); page.classList.add("active"); }
-    if (name === "settings") { loadSettingsList(); }
-    if (name === "history")  { loadHistory(); }
+    // lazy-load data
+    if (item.dataset.page === "settings") loadSettingsList();
+    if (item.dataset.page === "history")  loadHistory();
+    if (item.dataset.page === "stats")    loadStats();
   });
 });
 
-/* ── Config (env key status) ───────────────────────────────────────── */
+/* ── Sidebar collapse ───────────────────────────────────────────────── */
+$("btn-sidebar-toggle")?.addEventListener("click", () => {
+  const sb = $("sidebar");
+  sb.classList.toggle("collapsed");
+  localStorage.setItem("pf_sidebar", sb.classList.contains("collapsed") ? "1" : "0");
+});
+if (localStorage.getItem("pf_sidebar") === "1") $("sidebar")?.classList.add("collapsed");
+
+/* ── Theme toggle ───────────────────────────────────────────────────── */
+function applyTheme(theme) {
+  document.documentElement.dataset.theme = theme;
+  $("btn-theme").textContent = theme === "dark" ? "🌙" : "☀️";
+  localStorage.setItem("pf_theme", theme);
+}
+$("btn-theme")?.addEventListener("click", () => {
+  const cur = document.documentElement.dataset.theme || "dark";
+  applyTheme(cur === "dark" ? "light" : "dark");
+});
+applyTheme(localStorage.getItem("pf_theme") || "dark");
+
+/* ── Keyboard shortcuts ─────────────────────────────────────────────── */
+$("btn-shortcuts")?.addEventListener("click", () => show($("shortcuts-modal")));
+$("btn-shortcuts-close")?.addEventListener("click", () => hide($("shortcuts-modal")));
+$("shortcuts-modal")?.addEventListener("click", e => { if (e.target === $("shortcuts-modal")) hide($("shortcuts-modal")); });
+
+document.addEventListener("keydown", e => {
+  if (e.altKey) {
+    if (e.key === "b" || e.key === "B") { $("sidebar")?.classList.toggle("collapsed"); return; }
+    if (e.key === "t" || e.key === "T") { applyTheme(document.documentElement.dataset.theme === "dark" ? "light" : "dark"); return; }
+    if (e.key === "1") { document.querySelector('[data-page="generate"]')?.click(); return; }
+    if (e.key === "2") { document.querySelector('[data-page="settings"]')?.click(); return; }
+    if (e.key === "3") { document.querySelector('[data-page="history"]')?.click(); return; }
+    if (e.key === "4") { document.querySelector('[data-page="stats"]')?.click(); return; }
+  }
+  if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
+    if ($("page-generate")?.classList.contains("active")) $("btn-generate")?.click();
+    return;
+  }
+  if (e.key === "?" && !["INPUT","TEXTAREA","SELECT"].includes(e.target.tagName)) {
+    show($("shortcuts-modal")); return;
+  }
+  if (e.key === "Escape") {
+    hide($("modal-overlay")); hide($("shortcuts-modal"));
+  }
+});
+
+/* ── Config / env ───────────────────────────────────────────────────── */
 async function loadConfig() {
   try {
     const cfg = await apiFetch("/api/config");
-    const hfDot = $("env-hf-dot");
-    const ggDot = $("env-google-dot");
-    if (cfg.hf_key_set)     { hfDot?.classList.add("active"); }
-    if (cfg.google_key_set) { ggDot?.classList.add("active"); }
+    const dotHF  = $("dot-hf");
+    const dotGG  = $("dot-google");
+    if (cfg.hf_key_set)     dotHF?.classList.add("active");
+    if (cfg.google_key_set) dotGG?.classList.add("active");
   } catch {}
 }
 
-/* ── API Key Panel ─────────────────────────────────────────────────── */
-const PROVIDER_LABELS = {
-  none:        { hint:"(no key needed)", placeholder:"Not required for local engine" },
-  google:      { hint:"Google Gemini",   placeholder:"AIza…  (aistudio.google.com/apikey)" },
-  huggingface: { hint:"Hugging Face",    placeholder:"hf_…   (huggingface.co/settings/tokens)" },
+/* ── API key panel ──────────────────────────────────────────────────── */
+const PROVIDER_INFO = {
+  none:        { hint:"No key needed — local engine only", placeholder:"Not required" },
+  google:      { hint:"google.com/aistudio → Get API key", placeholder:"AIzaSy…" },
+  huggingface: { hint:"huggingface.co/settings/tokens",    placeholder:"hf_…" },
 };
 
-function updateApiKeyPanel() {
+$("btn-api-panel-toggle")?.addEventListener("click", () => {
+  const body    = $("api-panel-body");
+  const chevron = $("api-chevron");
+  body.classList.toggle("open");
+  chevron.classList.toggle("open");
+});
+
+$("provider")?.addEventListener("change", () => {
   const p = $("provider").value;
-  const info = PROVIDER_LABELS[p] || PROVIDER_LABELS.none;
-  if ($("api-key-hint")) $("api-key-hint").textContent = info.hint;
-  if (p === "none") {
-    $("api-key").disabled    = true;
-    $("api-key").value       = "";
-    $("api-key").placeholder = info.placeholder;
-    $("api-status-dot")?.classList.remove("set");
-    if ($("api-status-text")) $("api-status-text").textContent = "Not needed — local engine";
-  } else {
-    $("api-key").disabled    = false;
-    $("api-key").placeholder = info.placeholder;
-    updateApiStatus();
+  const info = PROVIDER_INFO[p] || PROVIDER_INFO.none;
+  $("key-hint").textContent = info.hint;
+  const needsKey = p !== "none";
+  $("api-key").disabled    = !needsKey;
+  $("api-key").placeholder = info.placeholder;
+  $("btn-check-key").disabled = !needsKey;
+  $("model-field").style.display = needsKey ? "block" : "none";
+  $("api-panel-status").textContent = needsKey ? "AI Enhancement Available" : "Local Engine Active";
+  if (!needsKey) {
+    $("api-key").value = "";
+    $("key-dot").className = "status-dot";
+    $("key-status-text").textContent = "No key needed";
   }
-}
+});
 
-function updateApiStatus() {
-  const key = $("api-key")?.value?.trim() || "";
-  const set = key.length >= 10;
-  $("api-status-dot")?.classList.toggle("set", set);
-  if ($("api-status-text"))
-    $("api-status-text").textContent = set ? "Key set ✓ — AI enhancement enabled" : "No key — AI enhancement disabled";
-}
+$("api-key")?.addEventListener("input", () => {
+  const has = $("api-key").value.trim().length >= 10;
+  $("key-dot").className = "status-dot" + (has ? " ok" : "");
+  $("key-status-text").textContent = has ? "Key entered — click ✓ to validate" : "Enter your API key";
+});
 
-$("provider")?.addEventListener("change", updateApiKeyPanel);
-$("api-key")?.addEventListener("input", updateApiStatus);
 $("btn-toggle-key")?.addEventListener("click", () => {
   const k = $("api-key");
   k.type = k.type === "password" ? "text" : "password";
   $("btn-toggle-key").textContent = k.type === "password" ? "👁" : "🙈";
 });
-updateApiKeyPanel();
 
-/* ── Advanced options toggle ───────────────────────────────────────── */
-$("btn-toggle-advanced")?.addEventListener("click", () => {
-  const panel = $("advanced-options");
-  if (panel.classList.contains("hidden")) {
-    show(panel);
-    $("btn-toggle-advanced").textContent = "⚙️ Hide advanced options";
-  } else {
-    hide(panel);
-    $("btn-toggle-advanced").textContent = "⚙️ Advanced options";
-  }
+$("btn-check-key")?.addEventListener("click", async () => {
+  const provider = $("provider").value;
+  const key = $("api-key").value.trim();
+  if (!key) { toast("Enter a key first.", "warn"); return; }
+  const btn = $("btn-check-key");
+  setLoading(btn, true);
+  try {
+    const res = await apiFetch("/api/check-key", "POST", { provider, api_key: key });
+    $("key-dot").className = "status-dot " + (res.valid ? "ok" : "err");
+    $("key-status-text").textContent = res.message;
+    toast(res.message, res.valid ? "success" : "error");
+    if (res.valid) { $("dot-" + (provider === "google" ? "google" : "hf"))?.classList.add("active"); }
+  } catch (e) { toast(`Key check failed: ${e.message}`, "error"); }
+  finally { setLoading(btn, false); }
 });
 
+/* ── Character counters ─────────────────────────────────────────────── */
+function bindCharCounter(textareaId, counterId, max) {
+  const ta = $(textareaId), ct = $(counterId);
+  if (!ta || !ct) return;
+  ta.addEventListener("input", () => {
+    const len = ta.value.length;
+    ct.textContent = len;
+    ct.parentElement.className = "char-counter" + (len > max * .95 ? " over" : len > max * .85 ? " warn" : "");
+  });
+}
+bindCharCounter("instruction", "instr-count", 8000);
+bindCharCounter("s-instruction", "s-instr-count", 8000);
+
+/* ── Persona / custom persona ───────────────────────────────────────── */
 $("gen-persona")?.addEventListener("change", () => {
-  const show = $("gen-persona").value === "custom";
-  $("custom-persona-field").style.display = show ? "block" : "none";
+  $("custom-persona-field").style.display = $("gen-persona").value === "custom" ? "block" : "none";
+});
+$("s-persona")?.addEventListener("change", () => {
+  $("s-custom-persona-field").style.display = $("s-persona").value === "custom" ? "block" : "none";
 });
 
-/* ── Inner tab switcher ────────────────────────────────────────────── */
-document.querySelectorAll(".tab").forEach(tab => {
-  tab.addEventListener("click", () => {
-    const tabBar = tab.closest(".tab-bar");
-    tabBar.querySelectorAll(".tab").forEach(t => t.classList.remove("active"));
-    tab.classList.add("active");
-    const name = tab.dataset.tab;
-    // find sibling panels
-    const section = tabBar.closest("section");
-    section.querySelectorAll(".tab-panel").forEach(p => hide(p));
-    show(section.querySelector(`#tab-${name}`));
+/* ── Tag autocomplete for settings form ─────────────────────────────── */
+const COMMON_TAGS = ["react","typescript","python","frontend","backend","devops","ml","security","testing","database","mobile","writing","docker","api","fastapi","tailwind"];
+function renderTagSugs(inputEl, containerEl) {
+  const cur = inputEl.value.split(",").map(t=>t.trim()).filter(Boolean);
+  const avail = COMMON_TAGS.filter(t => !cur.includes(t));
+  containerEl.innerHTML = avail.slice(0,8).map(t =>
+    `<span class="tag-sug" data-tag="${esc(t)}">${esc(t)}</span>`
+  ).join("");
+  containerEl.querySelectorAll(".tag-sug").forEach(el => {
+    el.addEventListener("click", () => {
+      const existing = inputEl.value.trim();
+      inputEl.value = existing ? `${existing}, ${el.dataset.tag}` : el.dataset.tag;
+      renderTagSugs(inputEl, containerEl);
+    });
   });
-});
+}
+const tagsInput = $("s-tags"), tagSugs = $("tag-suggestions");
+if (tagsInput && tagSugs) {
+  tagsInput.addEventListener("input", () => renderTagSugs(tagsInput, tagSugs));
+  renderTagSugs(tagsInput, tagSugs);
+}
 
-/* ── Copy buttons ──────────────────────────────────────────────────── */
+/* ── Step progress ──────────────────────────────────────────────────── */
+function setStep(n) {
+  document.querySelectorAll(".step").forEach((s, i) => {
+    const idx = parseInt(s.dataset.step);
+    s.classList.remove("active","done");
+    if (idx < n) s.classList.add("done");
+    if (idx === n) s.classList.add("active");
+  });
+  document.querySelectorAll(".step-line").forEach((l, i) => {
+    l.classList.toggle("filled", i + 1 < n);
+  });
+}
+
+/* ── Copy buttons ───────────────────────────────────────────────────── */
 document.addEventListener("click", e => {
-  const btn = e.target.closest(".btn-copy");
+  const btn = e.target.closest(".copy-btn");
   if (!btn) return;
   const el = $(btn.dataset.target);
   if (!el) return;
   navigator.clipboard.writeText(el.textContent).then(() => {
+    const orig = btn.textContent;
     btn.textContent = "✅ Copied!";
     btn.classList.add("copied");
-    setTimeout(() => { btn.classList.remove("copied"); btn.textContent = "📋 Copy"; }, 2000);
+    setTimeout(() => { btn.classList.remove("copied"); btn.textContent = orig; }, 2000);
   });
 });
 
-/* ── Step Progress ─────────────────────────────────────────────────── */
-function setStep(n) {
-  for (let i = 1; i <= 5; i++) {
-    const s = $(`pstep-${i}`); if (!s) continue;
-    s.classList.remove("active","done");
-    if (i < n) s.classList.add("done");
-    if (i === n) s.classList.add("active");
-  }
-  for (let i = 1; i <= 4; i++) {
-    const l = $(`pline-${i}`); if (!l) continue;
-    l.classList.toggle("filled", i < n);
-  }
-}
+/* ─────────────────────────────────────────────────────────────────────
+   GENERATE PAGE
+───────────────────────────────────────────────────────────────────── */
 
-/* ── STEP 1: Generate ──────────────────────────────────────────────── */
-$("btn-generate")?.addEventListener("click", async () => {
+/* ── STEP 1: Generate ─── */
+$("btn-generate")?.addEventListener("click", doGenerate);
+
+async function doGenerate() {
   const instruction = $("instruction").value.trim();
-  if (instruction.length < 5) { toast("Please enter a meaningful instruction (min 5 chars).", "error"); return; }
+  if (instruction.length < 5) { toast("Enter a meaningful instruction (min 5 chars).", "error"); return; }
   const btn = $("btn-generate");
   setLoading(btn, true);
   try {
-    const provider = $("provider").value;
-    const apiKey   = $("api-key").value.trim() || null;
-    const persona  = $("gen-persona")?.value || "default";
-    const style    = $("gen-style")?.value || "professional";
-    const customPersona = persona === "custom" ? ($("gen-custom-persona")?.value?.trim() || null) : null;
-    const constraintsRaw = $("gen-constraints")?.value?.trim() || "";
-    const userConstraints = constraintsRaw ? constraintsRaw.split("\n").map(s=>s.trim()).filter(Boolean) : [];
+    const provider    = $("provider").value;
+    const apiKey      = $("api-key")?.value.trim() || null;
+    const persona     = $("gen-persona")?.value || "default";
+    const style       = $("gen-style")?.value || "professional";
+    const customPerso = persona === "custom" ? ($("gen-custom-persona")?.value.trim() || null) : null;
+    const constrRaw   = $("gen-constraints")?.value.trim() || "";
+    const constraints = constrRaw ? constrRaw.split("\n").map(s=>s.trim()).filter(Boolean) : [];
+    const modelOvr    = $("provider-model")?.value.trim() || null;
 
     const data = await apiFetch("/api/generate", "POST", {
       instruction,
@@ -185,59 +276,74 @@ $("btn-generate")?.addEventListener("click", async () => {
       provider, api_key: apiKey,
       enhance: provider !== "none" && !!apiKey,
       extra_context: $("extra-context").value.trim() || null,
-      persona, custom_persona: customPersona, style,
-      user_constraints: userConstraints,
+      persona, custom_persona: customPerso, style,
+      user_constraints: constraints,
+      provider_model: modelOvr || undefined,
     });
     currentPromptId = data.prompt_id;
     renderManifest(data.manifest);
     hide($("step-input")); show($("step-manifest"));
     $("step-manifest").scrollIntoView({ behavior:"smooth", block:"start" });
     setStep(2);
-    toast("Manifest generated! Review and approve.", "success");
+    updateBadge("history-badge", null, +1);
+    toast("Manifest generated — review and approve.", "success");
   } catch (e) { toast(`Error: ${e.message}`, "error"); }
   finally { setLoading(btn, false); }
-});
+}
 
+/* ── Render manifest fields ─── */
 function renderManifest(manifest) {
-  const sp = manifest.structured_prompt;
+  const sp   = manifest.structured_prompt;
   const grid = $("manifest-grid");
   grid.innerHTML = "";
-  [
-    { key:"role",         label:"Role",          value:sp.role,                    full:false },
-    { key:"style",        label:"Style & Tone",  value:sp.style,                   full:false },
-    { key:"task",         label:"Task",          value:sp.task,                    full:true  },
-    { key:"input_format", label:"Input Format",  value:sp.input_format,            full:false },
-    { key:"output_format",label:"Output Format", value:sp.output_format,           full:false },
-    { key:"constraints",  label:"Constraints",   value:sp.constraints.join("\n"),  full:true  },
-    { key:"safety",       label:"Safety",        value:sp.safety.join("\n"),       full:true  },
-  ].forEach(f => {
+  const fields = [
+    { key:"role",          label:"Role",          value:sp.role,                   full:false },
+    { key:"style",         label:"Style & Tone",  value:sp.style,                  full:false },
+    { key:"task",          label:"Task",          value:sp.task,                   full:true  },
+    { key:"input_format",  label:"Input Format",  value:sp.input_format,           full:false },
+    { key:"output_format", label:"Output Format", value:sp.output_format,          full:false },
+    { key:"constraints",   label:"Constraints",   value:sp.constraints.join("\n"), full:true  },
+    { key:"safety",        label:"Safety",        value:sp.safety.join("\n"),      full:true  },
+  ];
+  fields.forEach(f => {
     const d = document.createElement("div");
     d.className = `manifest-field${f.full?" full":""}`;
-    d.innerHTML = `<label>${esc(f.label)}</label><textarea id="field-${f.key}" rows="${f.full?3:2}">${esc(f.value)}</textarea>`;
+    d.innerHTML = `<label>${esc(f.label)}</label>
+      <textarea id="field-${f.key}" rows="${f.full?3:2}">${esc(f.value)}</textarea>`;
     grid.appendChild(d);
   });
   $("manifest-json").textContent = JSON.stringify(manifest, null, 2);
   hide($("explanation-panel"));
+
+  // Word count badge
+  const wc = sp.word_count || sp.raw_prompt_text?.split(/\s+/).length || 0;
+  if (!$("wc-badge")) {
+    const b = document.createElement("span");
+    b.id = "wc-badge"; b.className = "step-tag";
+    b.style.marginLeft = "auto";
+    $("step-manifest")?.querySelector(".panel-header")?.appendChild(b);
+  }
+  $("wc-badge").textContent = `~${wc} words`;
 }
 
-/* ── Explain ───────────────────────────────────────────────────────── */
+/* ── Explain ─── */
 $("btn-explain")?.addEventListener("click", async () => {
   if (!currentPromptId) return;
   const btn = $("btn-explain");
   setLoading(btn, true);
   try {
     const data = await apiFetch(`/api/explain/${currentPromptId}`);
-    const panel = $("explanation-panel");
     $("explanation-text").textContent = data.explanation;
-    const kd = $("key-decisions");
-    kd.innerHTML = data.key_decisions.map(d => `<div class="decision-chip">${esc(d)}</div>`).join("");
+    $("key-decisions").innerHTML = data.key_decisions
+      .map(d => `<div class="decision-chip">${esc(d)}</div>`).join("");
+    const panel = $("explanation-panel");
     show(panel);
     panel.scrollIntoView({ behavior:"smooth", block:"nearest" });
-  } catch (e) { toast(`Could not load explanation: ${e.message}`, "warn"); }
+  } catch (e) { toast(`Explanation error: ${e.message}`, "warn"); }
   finally { setLoading(btn, false); }
 });
 
-/* ── STEP 2: Approve ───────────────────────────────────────────────── */
+/* ── Approve ─── */
 $("btn-approve")?.addEventListener("click", async () => {
   if (!currentPromptId) return;
   const edits = {};
@@ -264,7 +370,19 @@ function renderFinalized(sp) {
   $("finalized-json").textContent = JSON.stringify(sp, null, 2);
 }
 
-/* ── STEP 4: Export ────────────────────────────────────────────────── */
+/* ── Inner tabs (text/json) ─── */
+document.querySelectorAll(".inner-tab").forEach(tab => {
+  tab.addEventListener("click", () => {
+    const group = tab.closest(".panel");
+    group.querySelectorAll(".inner-tab").forEach(t => t.classList.remove("active"));
+    group.querySelectorAll(".inner-panel").forEach(p => hide(p));
+    tab.classList.add("active");
+    const panel = group.querySelector(`#itab-${tab.dataset.tab}`);
+    if (panel) show(panel);
+  });
+});
+
+/* ── Export ─── */
 async function doExport(format) {
   if (!currentPromptId) return;
   try {
@@ -283,23 +401,32 @@ async function doExport(format) {
 $("btn-export-json")?.addEventListener("click", () => doExport("json"));
 $("btn-export-txt")?.addEventListener("click",  () => doExport("text"));
 
-/* ── Save current prompt as a Setting ─────────────────────────────── */
+/* ── Favourite prompt ─── */
+$("btn-favorite-prompt")?.addEventListener("click", async () => {
+  if (!currentPromptId) return;
+  try {
+    const r = await apiFetch(`/api/prompts/${currentPromptId}/favorite`, "POST");
+    $("btn-favorite-prompt").textContent = r.is_favorite ? "★ Favourited" : "☆ Favourite";
+    toast(r.is_favorite ? "Added to favourites ★" : "Removed from favourites", "info");
+  } catch (e) { toast("Failed: " + e.message, "error"); }
+});
+
+/* ── Save as Setting ─── */
 $("btn-save-as-setting")?.addEventListener("click", () => {
-  // Switch to settings tab and pre-populate
-  const instruction = $("instruction")?.value?.trim() || "";
-  const context = $("extra-context")?.value?.trim() || "";
-  document.querySelector('[data-main-tab="settings"]')?.click();
+  const instruction = $("instruction")?.value.trim() || "";
+  const context     = $("extra-context")?.value.trim() || "";
+  document.querySelector('[data-page="settings"]')?.click();
   setTimeout(() => {
     clearSettingsForm();
-    if ($("s-title")) $("s-title").value = instruction.slice(0, 60) + "…";
-    if ($("s-instruction")) $("s-instruction").value = instruction;
+    if ($("s-title"))        $("s-title").value       = instruction.slice(0,60) + (instruction.length > 60 ? "…" : "");
+    if ($("s-instruction"))  $("s-instruction").value  = instruction;
     if ($("s-extra-context")) $("s-extra-context").value = context;
     $("s-title")?.focus();
-    toast("Pre-filled from current prompt — adjust and save!", "info");
+    toast("Pre-filled from prompt — adjust title and save!", "info");
   }, 150);
 });
 
-/* ── STEP 5: Refine ────────────────────────────────────────────────── */
+/* ── Refine ─── */
 $("btn-refine")?.addEventListener("click", () => {
   hide($("step-finalized")); show($("step-refine"));
   $("step-refine").scrollIntoView({ behavior:"smooth", block:"start" });
@@ -310,14 +437,14 @@ $("btn-cancel-refine")?.addEventListener("click", () => {
 });
 $("btn-submit-refine")?.addEventListener("click", async () => {
   const feedback = $("feedback").value.trim();
-  if (!feedback) { toast("Please describe what to change.", "error"); return; }
+  if (!feedback) { toast("Describe what to change.", "error"); return; }
   const btn = $("btn-submit-refine");
   setLoading(btn, true);
   try {
     const data = await apiFetch("/api/refine", "POST", {
       prompt_id: currentPromptId, feedback,
       provider: $("provider").value,
-      api_key: $("api-key").value.trim() || null,
+      api_key:  $("api-key")?.value.trim() || null,
     });
     currentPromptId = data.prompt_id;
     renderManifest(data.manifest);
@@ -329,7 +456,7 @@ $("btn-submit-refine")?.addEventListener("click", async () => {
   finally { setLoading(btn, false); }
 });
 
-/* ── Reset / New ───────────────────────────────────────────────────── */
+/* ── Reset / New ─── */
 $("btn-reset")?.addEventListener("click", () => {
   hide($("step-manifest")); show($("step-input")); setStep(1);
   $("instruction").value = ""; $("extra-context").value = "";
@@ -338,18 +465,18 @@ $("btn-reset")?.addEventListener("click", () => {
 $("btn-new")?.addEventListener("click", () => {
   hide($("step-finalized")); show($("step-input")); setStep(1);
   $("instruction").value = ""; $("extra-context").value = "";
+  $("instr-count").textContent = "0";
   currentPromptId = null;
   $("step-input").scrollIntoView({ behavior:"smooth", block:"start" });
 });
 
-/* ── Load from Settings (modal) ────────────────────────────────────── */
+/* ── Load-from-settings modal ─── */
 $("btn-load-from-settings")?.addEventListener("click", async () => {
   await loadSettingsForModal();
   show($("modal-overlay"));
 });
 $("btn-modal-close")?.addEventListener("click", () => hide($("modal-overlay")));
 $("modal-overlay")?.addEventListener("click", e => { if (e.target === $("modal-overlay")) hide($("modal-overlay")); });
-
 $("modal-search")?.addEventListener("input", () => {
   const q = $("modal-search").value.toLowerCase();
   document.querySelectorAll(".modal-item").forEach(item => {
@@ -358,94 +485,75 @@ $("modal-search")?.addEventListener("input", () => {
 });
 
 async function loadSettingsForModal() {
-  const list = $("modal-settings-list");
+  const list = $("modal-list");
   try {
     const data = await apiFetch("/api/instructions");
     if (!data.items?.length) {
-      list.innerHTML = `<div class="modal-empty">No saved settings yet. Create one in the Instruction Settings tab.</div>`;
+      list.innerHTML = `<div class="modal-empty">No saved settings. Create some in the Settings page.</div>`;
       return;
     }
     list.innerHTML = data.items.map(s => `
       <div class="modal-item" data-id="${esc(s.settings_id)}" data-search="${esc((s.title+s.instruction).toLowerCase())}">
-        <div class="modal-item-title">${esc(s.title)}</div>
-        <div class="modal-item-desc">${esc(s.instruction.slice(0, 100))}${s.instruction.length > 100 ? "…" : ""}</div>
+        <div class="modal-item-title">${personaEmoji(s.persona)} ${esc(s.title)}</div>
+        <div class="modal-item-desc">${esc(s.instruction.slice(0,110))}${s.instruction.length > 110 ? "…" : ""}</div>
       </div>`).join("");
     document.querySelectorAll(".modal-item").forEach(item => {
       item.addEventListener("click", async () => {
-        const sid = item.dataset.id;
         hide($("modal-overlay"));
-        await generateFromSetting(sid);
+        await generateFromSetting(item.dataset.id);
       });
     });
   } catch (e) {
-    list.innerHTML = `<div class="modal-empty">Failed to load settings: ${esc(e.message)}</div>`;
+    list.innerHTML = `<div class="modal-empty">Failed: ${esc(e.message)}</div>`;
   }
 }
 
 async function generateFromSetting(sid) {
   const btn = $("btn-generate");
   setLoading(btn, true);
-  // Switch to generate tab
-  document.querySelector('[data-main-tab="generate"]')?.click();
+  document.querySelector('[data-page="generate"]')?.click();
   try {
-    const apiKey = $("api-key")?.value?.trim() || null;
+    const apiKey = $("api-key")?.value.trim() || null;
     const data = await apiFetch("/api/generate/from-settings", "POST", { settings_id: sid, api_key: apiKey });
     currentPromptId = data.prompt_id;
     renderManifest(data.manifest);
     hide($("step-input")); show($("step-manifest"));
     $("step-manifest").scrollIntoView({ behavior:"smooth", block:"start" });
     setStep(2);
-    toast(`Generated from "${data.manifest.settings_id ? "saved setting" : "settings"}"! ✨`, "success");
+    updateBadge("history-badge", null, +1);
+    toast(`Generated from saved setting! ✨`, "success");
   } catch (e) { toast(`Error: ${e.message}`, "error"); }
   finally { setLoading(btn, false); }
 }
 
-/* ══════════════════════════════════════════════════════════════════
-   INSTRUCTION SETTINGS PANEL
-══════════════════════════════════════════════════════════════════ */
-
-/* ── Persona custom field ── */
-$("s-persona")?.addEventListener("change", () => {
-  $("s-custom-persona-field").style.display = $("s-persona").value === "custom" ? "block" : "none";
-});
+/* ─────────────────────────────────────────────────────────────────────
+   SETTINGS PAGE
+───────────────────────────────────────────────────────────────────── */
 
-/* ── Instruction character count ── */
-$("s-instruction")?.addEventListener("input", () => {
-  const len = $("s-instruction").value.length;
-  const note = $("s-instruction-count");
-  if (note) {
-    note.textContent = `${len} / 8000 characters`;
-    note.style.color = len > 7500 ? "var(--red)" : "var(--text-muted)";
-  }
-});
-
-/* ── Save setting ── */
 $("btn-settings-save")?.addEventListener("click", async () => {
-  const title = $("s-title").value.trim();
+  const title       = $("s-title").value.trim();
   const instruction = $("s-instruction").value.trim();
-  if (!title) { toast("Please enter a title.", "error"); $("s-title").focus(); return; }
-  if (instruction.length < 5) { toast("Instruction must be at least 5 characters.", "error"); $("s-instruction").focus(); return; }
+  if (!title)                  { toast("Title is required.", "error");   $("s-title").focus(); return; }
+  if (instruction.length < 5)  { toast("Instruction too short.", "error"); $("s-instruction").focus(); return; }
 
   const editId = $("edit-settings-id").value;
   const persona = $("s-persona").value;
-  const constraintsRaw = $("s-constraints").value.trim();
-  const constraints = constraintsRaw ? constraintsRaw.split("\n").map(s=>s.trim()).filter(Boolean) : [];
-  const tagsRaw = $("s-tags").value.trim();
-  const tags = tagsRaw ? tagsRaw.split(",").map(s=>s.trim().toLowerCase()).filter(Boolean) : [];
+  const constraints = ($("s-constraints").value.trim() || "").split("\n").map(s=>s.trim()).filter(Boolean);
+  const tags = ($("s-tags").value.trim() || "").split(",").map(s=>s.trim().toLowerCase()).filter(Boolean);
 
   const payload = {
     title,
-    description: $("s-description").value.trim() || null,
+    description:    $("s-description").value.trim() || null,
     instruction,
-    extra_context: $("s-extra-context").value.trim() || null,
-    output_format: $("s-output-format").value,
+    extra_context:  $("s-extra-context")?.value.trim() || null,
+    output_format:  $("s-output-format").value,
     persona,
-    custom_persona: persona === "custom" ? ($("s-custom-persona").value.trim() || null) : null,
-    style: $("s-style").value,
-    constraints,
-    tags,
-    provider: $("s-provider").value,
-    enhance: $("s-enhance").checked,
+    custom_persona: persona === "custom" ? ($("s-custom-persona")?.value.trim() || null) : null,
+    style:          $("s-style").value,
+    constraints, tags,
+    provider:    $("s-provider").value,
+    enhance:     $("s-enhance")?.checked || false,
+    is_favorite: $("s-favorite")?.checked || false,
   };
 
   const btn = $("btn-settings-save");
@@ -464,123 +572,166 @@ $("btn-settings-save")?.addEventListener("click", async () => {
   finally { setLoading(btn, false); }
 });
 
-/* ── Clear form ── */
 $("btn-settings-clear")?.addEventListener("click", clearSettingsForm);
 
+$("btn-export-all-settings")?.addEventListener("click", async () => {
+  try {
+    const data = await apiFetch("/api/instructions/export");
+    const blob = new Blob([JSON.stringify(data, null, 2)], { type:"application/json" });
+    const a = Object.assign(document.createElement("a"), {
+      href: URL.createObjectURL(blob), download: "promptforge-settings.json"
+    });
+    a.click(); URL.revokeObjectURL(a.href);
+    toast(`Exported ${data.total} settings.`, "success");
+  } catch (e) { toast("Export failed: " + e.message, "error"); }
+});
+
 function clearSettingsForm() {
   $("edit-settings-id").value = "";
   ["s-title","s-description","s-instruction","s-extra-context","s-constraints","s-tags","s-custom-persona"].forEach(id => {
     const el = $(id); if (el) el.value = "";
   });
-  if ($("s-persona")) $("s-persona").value = "default";
-  if ($("s-style")) $("s-style").value = "professional";
-  if ($("s-output-format")) $("s-output-format").value = "both";
-  if ($("s-provider")) $("s-provider").value = "none";
-  if ($("s-enhance")) $("s-enhance").checked = false;
+  $("s-persona").value = "default";
+  $("s-style").value = "professional";
+  $("s-output-format").value = "both";
+  $("s-provider").value = "none";
+  if ($("s-enhance"))   $("s-enhance").checked = false;
+  if ($("s-favorite"))  $("s-favorite").checked = false;
   if ($("s-custom-persona-field")) $("s-custom-persona-field").style.display = "none";
-  if ($("s-instruction-count")) $("s-instruction-count").textContent = "0 / 8000 characters";
-  if ($("settings-form-title")) $("settings-form-title").textContent = "➕ New Instruction Setting";
-  if ($("btn-settings-generate")) $("btn-settings-generate").style.display = "none";
-  document.querySelectorAll(".setting-card").forEach(c => c.classList.remove("active-edit"));
+  if ($("s-instr-count")) $("s-instr-count").textContent = "0";
+  if ($("settings-form-title")) $("settings-form-title").textContent = "➕ New Setting";
+  const genBtn = $("btn-settings-generate");
+  if (genBtn) { genBtn.classList.add("hidden"); genBtn._orig = null; }
+  document.querySelectorAll(".setting-card").forEach(c => c.classList.remove("editing"));
+  // reset tag suggestions
+  if (tagsInput && tagSugs) renderTagSugs(tagsInput, tagSugs);
 }
 
-/* ── Load settings list ── */
+/* ── Load settings list ─── */
 async function loadSettingsList() {
   try {
-    const data = await apiFetch("/api/instructions");
+    const q   = $("settings-search")?.value.trim() || "";
+    const tag = $("settings-filter-tag")?.value || "";
+    let url = "/api/instructions?";
+    if (q)   url += `q=${encodeURIComponent(q)}&`;
+    if (tag) url += `tag=${encodeURIComponent(tag)}&`;
+    if (favoritesFilter) url += "favorites_only=true&";
+
+    const data = await apiFetch(url);
     allSettings = data.items || [];
     renderSettingsList(allSettings);
-    updateSettingsCount(data.total);
+    const n = data.total || 0;
+    if ($("settings-total-count")) $("settings-total-count").textContent = n;
+    if ($("settings-badge"))       $("settings-badge").textContent       = n;
+
+    // refresh tag filter
+    const tagData = await apiFetch("/api/instructions/tags");
+    const filterEl = $("settings-filter-tag");
+    if (filterEl) {
+      const cur = filterEl.value;
+      filterEl.innerHTML = `<option value="">All tags</option>` +
+        tagData.tags.map(t => `<option value="${esc(t)}" ${t===cur?"selected":""}>${esc(t)}</option>`).join("");
+    }
   } catch (e) { toast(`Failed to load settings: ${e.message}`, "error"); }
 }
 
-function updateSettingsCount(count) {
-  const badge = $("settings-count");
-  if (badge) badge.textContent = count;
-  const total = $("settings-total-count");
-  if (total) total.textContent = count;
-}
-
 function renderSettingsList(items) {
   const container = $("settings-list");
   if (!items.length) {
-    container.innerHTML = `<div class="settings-empty"><div class="empty-icon">📋</div><p>No settings yet. Create your first one!</p></div>`;
+    container.innerHTML = `<div class="empty-state"><div class="empty-icon">📋</div><p>No settings yet.</p></div>`;
     return;
   }
   container.innerHTML = items.map(s => `
-    <div class="setting-card" data-id="${esc(s.settings_id)}">
-      <div class="setting-card-title">
-        ${personaEmoji(s.persona)} ${esc(s.title)}
+    <div class="setting-card${s.is_favorite?" favorite":""}${$("edit-settings-id").value===s.settings_id?" editing":""}"
+      data-id="${esc(s.settings_id)}">
+      <div class="setting-card-top">
+        <div class="setting-card-title">${personaEmoji(s.persona)} ${esc(s.title)}</div>
+        <span class="s-star">${s.is_favorite?"★":"☆"}</span>
       </div>
       ${s.description ? `<div class="setting-card-desc">${esc(s.description)}</div>` : ""}
       <div class="setting-card-meta">
-        ${s.tags.slice(0,4).map(t => `<span class="tag-chip">${esc(t)}</span>`).join("")}
-        <span class="tag-chip style">${esc(s.style)}</span>
-        <span class="use-count">${s.use_count} uses</span>
+        ${(s.tags||[]).slice(0,4).map(t=>`<span class="tag-chip">${esc(t)}</span>`).join("")}
+        <span class="tag-chip style-tag">${esc(s.style)}</span>
+        <span class="use-count">× ${s.use_count||0}</span>
       </div>
       <div class="setting-card-actions">
-        <button class="btn-secondary btn-sm" onclick="editSetting('${esc(s.settings_id)}')">✏️</button>
-        <button class="btn-secondary btn-sm btn-danger" onclick="deleteSetting('${esc(s.settings_id)}')">🗑</button>
+        <button class="icon-btn" title="Edit" onclick="editSetting('${esc(s.settings_id)}')">✏️</button>
+        <button class="icon-btn" title="Duplicate" onclick="duplicateSetting('${esc(s.settings_id)}')">⧉</button>
+        <button class="icon-btn" title="Favourite" onclick="toggleSettingFav('${esc(s.settings_id)}')">☆</button>
+        <button class="icon-btn btn-danger" title="Delete" onclick="deleteSetting('${esc(s.settings_id)}')">🗑</button>
         <button class="btn-primary btn-sm" onclick="generateFromSetting('${esc(s.settings_id)}')">⚡</button>
       </div>
     </div>`).join("");
-
-  // Rebuild tag filter
-  const allTags = [...new Set(items.flatMap(s => s.tags))].sort();
-  const filterEl = $("settings-filter-tag");
-  if (filterEl) {
-    filterEl.innerHTML = `<option value="">All tags</option>` + allTags.map(t => `<option value="${esc(t)}">${esc(t)}</option>`).join("");
-  }
 }
 
-function personaEmoji(persona) {
-  const map = { senior_dev:"👨‍💻", data_scientist:"📊", tech_writer:"✍️", product_mgr:"📋", security_eng:"🔒", custom:"✏️" };
-  return map[persona] || "🤖";
-}
-
-/* ── Search & filter ── */
-$("settings-search")?.addEventListener("input", filterSettings);
-$("settings-filter-tag")?.addEventListener("change", filterSettings);
-
-function filterSettings() {
-  const q = ($("settings-search")?.value || "").toLowerCase();
-  const tag = $("settings-filter-tag")?.value || "";
-  const filtered = allSettings.filter(s => {
-    const matchQ = !q || (s.title + s.instruction + (s.description || "")).toLowerCase().includes(q);
-    const matchTag = !tag || s.tags.includes(tag);
-    return matchQ && matchTag;
-  });
-  renderSettingsList(filtered);
-}
+/* ── Search / filter ─── */
+let settingsSearchTimer;
+$("settings-search")?.addEventListener("input", () => {
+  clearTimeout(settingsSearchTimer);
+  settingsSearchTimer = setTimeout(loadSettingsList, 250);
+});
+$("settings-filter-tag")?.addEventListener("change", loadSettingsList);
+$("btn-filter-favorites")?.addEventListener("click", () => {
+  favoritesFilter = !favoritesFilter;
+  $("btn-filter-favorites").textContent = favoritesFilter ? "★" : "☆";
+  $("btn-filter-favorites").style.color = favoritesFilter ? "var(--amber)" : "";
+  loadSettingsList();
+});
 
-/* ── Edit setting ── */
+/* ── Edit setting ─── */
 async function editSetting(sid) {
   try {
     const s = await apiFetch(`/api/instructions/${sid}`);
     $("edit-settings-id").value = s.settings_id;
-    if ($("s-title")) $("s-title").value = s.title;
-    if ($("s-description")) $("s-description").value = s.description || "";
-    if ($("s-instruction")) { $("s-instruction").value = s.instruction; $("s-instruction").dispatchEvent(new Event("input")); }
-    if ($("s-extra-context")) $("s-extra-context").value = s.extra_context || "";
-    if ($("s-output-format")) $("s-output-format").value = s.output_format;
-    if ($("s-persona")) { $("s-persona").value = s.persona; $("s-persona").dispatchEvent(new Event("change")); }
-    if ($("s-custom-persona")) $("s-custom-persona").value = s.custom_persona || "";
-    if ($("s-style")) $("s-style").value = s.style;
-    if ($("s-constraints")) $("s-constraints").value = (s.constraints || []).join("\n");
-    if ($("s-tags")) $("s-tags").value = (s.tags || []).join(", ");
-    if ($("s-provider")) $("s-provider").value = s.provider;
-    if ($("s-enhance")) $("s-enhance").checked = s.enhance;
+    $("s-title").value        = s.title;
+    $("s-description").value  = s.description || "";
+    $("s-instruction").value  = s.instruction;
+    $("s-instruction").dispatchEvent(new Event("input"));
+    $("s-extra-context").value = s.extra_context || "";
+    $("s-output-format").value = s.output_format;
+    $("s-persona").value      = s.persona;
+    $("s-persona").dispatchEvent(new Event("change"));
+    $("s-custom-persona").value = s.custom_persona || "";
+    $("s-style").value        = s.style;
+    $("s-constraints").value  = (s.constraints || []).join("\n");
+    $("s-tags").value         = (s.tags || []).join(", ");
+    $("s-provider").value     = s.provider;
+    if ($("s-enhance"))  $("s-enhance").checked  = s.enhance;
+    if ($("s-favorite")) $("s-favorite").checked = s.is_favorite;
     if ($("settings-form-title")) $("settings-form-title").textContent = `✏️ Edit: ${s.title}`;
-    if ($("btn-settings-generate")) $("btn-settings-generate").style.display = "inline-flex";
-    document.querySelectorAll(".setting-card").forEach(c => c.classList.toggle("active-edit", c.dataset.id === sid));
-    $("settings-form-card").scrollIntoView({ behavior:"smooth", block:"start" });
+    const genBtn = $("btn-settings-generate");
+    if (genBtn) { genBtn.classList.remove("hidden"); genBtn._orig = null; }
+    document.querySelectorAll(".setting-card").forEach(c => c.classList.toggle("editing", c.dataset.id === sid));
+    // scroll form into view
+    document.querySelector(".settings-form-col")?.scrollIntoView({ behavior:"smooth", block:"start" });
+    renderTagSugs($("s-tags"), $("tag-suggestions"));
   } catch (e) { toast(`Failed to load setting: ${e.message}`, "error"); }
 }
 window.editSetting = editSetting;
 
-/* ── Delete setting ── */
+/* ── Duplicate setting ─── */
+async function duplicateSetting(sid) {
+  try {
+    const s = await apiFetch(`/api/instructions/${sid}/duplicate`, "POST");
+    toast(`Duplicated → "${s.title}"`, "success");
+    await loadSettingsList();
+  } catch (e) { toast("Duplicate failed: " + e.message, "error"); }
+}
+window.duplicateSetting = duplicateSetting;
+
+/* ── Toggle favourite ─── */
+async function toggleSettingFav(sid) {
+  try {
+    const r = await apiFetch(`/api/instructions/${sid}/favorite`, "POST");
+    toast(r.is_favorite ? "Added to favourites ★" : "Removed from favourites", "info");
+    await loadSettingsList();
+  } catch (e) { toast("Failed: " + e.message, "error"); }
+}
+window.toggleSettingFav = toggleSettingFav;
+
+/* ── Delete setting ─── */
 async function deleteSetting(sid) {
-  if (!confirm("Delete this instruction setting?")) return;
+  if (!confirm("Delete this instruction setting? This cannot be undone.")) return;
   try {
     await apiFetch(`/api/instructions/${sid}`, "DELETE");
     toast("Setting deleted.", "success");
@@ -589,48 +740,99 @@ async function deleteSetting(sid) {
   } catch (e) { toast(`Delete failed: ${e.message}`, "error"); }
 }
 window.deleteSetting = deleteSetting;
-window.generateFromSetting = generateFromSetting;
 
-/* ── Generate Now button (in edit mode) ── */
+/* ── Generate now (from edit form) ─── */
 $("btn-settings-generate")?.addEventListener("click", async () => {
   const sid = $("edit-settings-id").value;
   if (!sid) return;
-  document.querySelector('[data-main-tab="generate"]')?.click();
+  document.querySelector('[data-page="generate"]')?.click();
   await generateFromSetting(sid);
 });
 
-/* ── History ────────────────────────────────────────────────────────── */
-$("btn-load-history")?.addEventListener("click", loadHistory);
+/* ─────────────────────────────────────────────────────────────────────
+   HISTORY PAGE
+───────────────────────────────────────────────────────────────────── */
+$("btn-history-refresh")?.addEventListener("click", loadHistory);
+
+let histSearchTimer;
+$("history-search")?.addEventListener("input", () => {
+  clearTimeout(histSearchTimer);
+  histSearchTimer = setTimeout(loadHistory, 300);
+});
+$("history-status-filter")?.addEventListener("change", loadHistory);
 
 async function loadHistory() {
-  const btn = $("btn-load-history");
-  setLoading(btn, true);
+  const status = $("history-status-filter")?.value || "";
+  const q      = $("history-search")?.value.trim()  || "";
+  let url = "/api/history?";
+  if (status) url += `status_filter=${status}&`;
+
   try {
-    const data = await apiFetch("/api/history");
+    const data = await apiFetch(url);
+    let entries = data.entries || [];
+
+    // client-side search if q provided
+    if (q) {
+      const ql = q.toLowerCase();
+      entries = entries.filter(e => e.instruction?.toLowerCase().includes(ql) ||
+        e.prompt_id?.toLowerCase().includes(ql) ||
+        (e.tags||[]).join(",").includes(ql));
+    }
+
     const tbody = $("history-body");
-    if (!data.entries?.length) {
-      tbody.innerHTML = `<tr><td class="empty-msg" colspan="7">No prompts yet. Generate your first one!</td></tr>`;
+    const total = entries.length;
+    if ($("history-badge")) $("history-badge").textContent = data.total || 0;
+
+    if (!total) {
+      tbody.innerHTML = `<tr><td class="empty-msg" colspan="8">No prompts found.</td></tr>`;
       return;
     }
-    tbody.innerHTML = data.entries.map(e => `
+
+    tbody.innerHTML = entries.map(e => `
       <tr>
-        <td><code style="font-size:.72rem;color:var(--text-muted)">${esc(e.prompt_id?.slice(0,8))}…</code></td>
-        <td style="max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${esc(e.instruction)}">${esc(e.instruction?.slice(0,55) || "—")}</td>
-        <td style="font-family:var(--font-mono)">v${e.version||1}</td>
+        <td><span class="fav-star${e.is_favorite?' active':''}"
+          onclick="toggleHistFav('${esc(e.prompt_id)}')">${e.is_favorite?"★":"☆"}</span></td>
+        <td><code style="font-size:.7rem;color:var(--text-muted)">${esc(e.prompt_id?.slice(0,8))}…</code></td>
+        <td style="max-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap"
+          title="${esc(e.instruction)}">${esc(e.instruction?.slice(0,55)||"—")}</td>
+        <td style="font-family:var(--font-mono);font-size:.75rem">v${e.version||1}</td>
         <td><span class="badge badge-${e.status||'pending'}">${esc(e.status||"pending")}</span></td>
-        <td style="font-size:.75rem;color:var(--text-muted)">${e.settings_id ? `<span class="tag-chip">linked</span>` : "—"}</td>
-        <td style="white-space:nowrap;font-size:.75rem">${e.created_at ? new Date(e.created_at).toLocaleDateString() : "—"}</td>
-        <td>
-          <button class="btn-secondary btn-sm btn-danger" onclick="deleteHistory('${esc(e.prompt_id)}')">🗑</button>
+        <td>${(e.tags||[]).slice(0,3).map(t=>`<span class="tag-chip">${esc(t)}</span>`).join(" ")}</td>
+        <td style="white-space:nowrap;font-size:.74rem;color:var(--text-muted)">${e.created_at?new Date(e.created_at).toLocaleDateString():"—"}</td>
+        <td style="white-space:nowrap;display:flex;gap:4px">
+          <button class="icon-btn btn-sm" title="Archive" onclick="archivePrompt('${esc(e.prompt_id)}')">📦</button>
+          <button class="icon-btn btn-danger btn-sm" title="Delete" onclick="deleteHistory('${esc(e.prompt_id)}')">🗑</button>
         </td>
       </tr>`).join("");
-    toast(`Loaded ${data.total} prompt(s).`, "info");
+
+    toast(`${total} prompt(s) loaded.`, "info", 2000);
   } catch (e) { toast(`History error: ${e.message}`, "error"); }
-  finally { setLoading(btn, false); }
 }
 
+async function toggleHistFav(pid) {
+  try {
+    const r = await apiFetch(`/api/prompts/${pid}/favorite`, "POST");
+    document.querySelectorAll(".fav-star").forEach(el => {
+      if (el.getAttribute("onclick")?.includes(pid)) {
+        el.textContent = r.is_favorite ? "★" : "☆";
+        el.classList.toggle("active", r.is_favorite);
+      }
+    });
+  } catch (e) { toast("Failed: " + e.message, "error"); }
+}
+window.toggleHistFav = toggleHistFav;
+
+async function archivePrompt(pid) {
+  try {
+    await apiFetch(`/api/prompts/${pid}/archive`, "POST");
+    toast("Prompt archived.", "success");
+    loadHistory();
+  } catch (e) { toast("Archive failed: " + e.message, "error"); }
+}
+window.archivePrompt = archivePrompt;
+
 async function deleteHistory(id) {
-  if (!confirm("Delete this prompt?")) return;
+  if (!confirm("Delete this prompt permanently?")) return;
   try {
     await apiFetch(`/api/history/${id}`, "DELETE");
     toast("Deleted.", "success");
@@ -639,8 +841,86 @@ async function deleteHistory(id) {
 }
 window.deleteHistory = deleteHistory;
 
-/* ── Init ───────────────────────────────────────────────────────────── */
+/* ─────────────────────────────────────────────────────────────────────
+   STATS PAGE
+───────────────────────────────────────────────────────────────────── */
+$("btn-stats-refresh")?.addEventListener("click", loadStats);
+
+async function loadStats() {
+  const grid = $("stats-grid");
+  try {
+    const s = await apiFetch("/api/stats");
+
+    grid.innerHTML = [
+      { val:s.total_prompts,    lbl:"Total Prompts",    sub:"all time",           hi:false },
+      { val:s.total_settings,   lbl:"Saved Settings",   sub:`${s.favorite_settings} favourited`, hi:false },
+      { val:s.total_refinements,lbl:"Refinements",       sub:"iterative improvements",  hi:true },
+      { val:s.avg_constraints,  lbl:"Avg Constraints",  sub:"per prompt",          hi:false },
+    ].map(c => `
+      <div class="stat-card${c.hi?" highlight":""}">
+        <div class="stat-value">${c.val}</div>
+        <div class="stat-label">${c.lbl}</div>
+        <div class="stat-sub">${c.sub}</div>
+      </div>`).join("");
+
+    // Persona bars
+    const maxP = Math.max(1, ...Object.values(s.top_personas));
+    $("stats-personas").innerHTML = Object.entries(s.top_personas).length
+      ? Object.entries(s.top_personas).sort((a,b)=>b[1]-a[1]).map(([k,v]) => `
+          <div class="bar-row">
+            <div class="bar-row-label">${esc(k)}</div>
+            <div class="bar-track"><div class="bar-fill" style="width:${Math.round(v/maxP*100)}%"></div></div>
+            <div class="bar-count">${v}</div>
+          </div>`).join("")
+      : `<p class="muted" style="padding:4px 0">No data yet.</p>`;
+
+    // Style bars
+    const maxS = Math.max(1, ...Object.values(s.top_styles));
+    $("stats-styles").innerHTML = Object.entries(s.top_styles).length
+      ? Object.entries(s.top_styles).sort((a,b)=>b[1]-a[1]).map(([k,v]) => `
+          <div class="bar-row">
+            <div class="bar-row-label">${esc(k)}</div>
+            <div class="bar-track"><div class="bar-fill" style="width:${Math.round(v/maxS*100)}%"></div></div>
+            <div class="bar-count">${v}</div>
+          </div>`).join("")
+      : `<p class="muted" style="padding:4px 0">No data yet.</p>`;
+
+    // Status breakdown
+    $("stats-statuses").innerHTML = [
+      { status:"pending",  count:s.pending_count,  color:"var(--amber)"  },
+      { status:"approved", count:s.approved_count, color:"var(--green)"  },
+      { status:"exported", count:s.exported_count, color:"var(--accent)" },
+      { status:"archived", count:s.archived_count, color:"var(--text-faint)" },
+    ].map(x => `
+      <div class="status-item">
+        <div class="status-item-count" style="color:${x.color}">${x.count}</div>
+        <div class="status-item-label">${x.status}</div>
+      </div>`).join("");
+
+    toast("Stats refreshed.", "info", 2000);
+  } catch (e) {
+    grid.innerHTML = `<div class="stat-card" style="grid-column:1/-1;text-align:center;color:var(--text-muted)">Could not load stats — is the server running?</div>`;
+    toast("Stats error: " + e.message, "error");
+  }
+}
+
+/* ── Utilities ─── */
+function personaEmoji(persona) {
+  const m = { senior_dev:"👨‍💻", data_scientist:"📊", tech_writer:"✍️", product_mgr:"📋",
+              security_eng:"🔒", devops_eng:"🚀", ml_engineer:"🧠", custom:"✏️" };
+  return m[persona] || "🤖";
+}
+
+function updateBadge(id, total, delta) {
+  const el = $(id);
+  if (!el) return;
+  if (total !== null) { el.textContent = total; }
+  else { el.textContent = parseInt(el.textContent || "0") + delta; }
+}
+
+/* ── Init ─── */
 (async () => {
   await loadConfig();
   await loadSettingsList();
+  setStep(1);
 })();

frontend/index.html

@@ -1,322 +1,328 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="en" data-theme="dark">
 <head>
   <meta charset="UTF-8"/>
   <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
-  <title>PromptForge — Structured Prompt Generator</title>
+  <title>PromptForge v4.0</title>
   <link rel="preconnect" href="https://fonts.googleapis.com"/>
-  <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet"/>
+  <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet"/>
   <link rel="stylesheet" href="/static/style.css"/>
 </head>
 <body>
 
-<!-- Legacy cursor/bg elements (hidden via CSS) -->
-<div id="cursor-dot"></div><div id="cursor-ring"></div>
-<div class="bg-mesh"></div><div class="bg-grid"></div>
-<div class="orb orb-1"></div><div class="orb orb-2"></div><div class="orb orb-3"></div>
-
 <div id="app">
 
-  <!-- ── Header ─────────────────────────────────────────────────────── -->
-  <header>
-    <div class="header-inner">
-      <div class="logo-group">
-        <div class="logo-icon">⚡</div>
-        <span class="logo-text">PromptForge</span>
-        <span class="logo-tag">v3.0</span>
-      </div>
-      <div class="header-meta">
-        <div class="api-env-status" id="env-status-bar">
-          <span class="env-dot" id="env-hf-dot" title="Hugging Face API key status">HF</span>
-          <span class="env-dot" id="env-google-dot" title="Google API key status">GG</span>
-        </div>
-        <div class="status-pill">
-          <div class="status-dot"></div>
-          <span>ONLINE</span>
+  <!-- ── Sidebar ─────────────────────────────────────────────────── -->
+  <aside id="sidebar">
+    <div class="sidebar-top">
+      <div class="brand">
+        <div class="brand-icon">⚡</div>
+        <div class="brand-info">
+          <span class="brand-name">PromptForge</span>
+          <span class="brand-ver">v4.0</span>
         </div>
-        <a class="nav-link" href="/docs" target="_blank">📖 Docs</a>
       </div>
+      <button class="sidebar-toggle" id="btn-sidebar-toggle" title="Toggle sidebar (Alt+B)">‹</button>
     </div>
-    <!-- ── Main Tab Bar ──────────────────────────────────────────────── -->
-    <div class="main-tabs">
-      <div class="tabs-inner">
-        <button class="main-tab active" data-main-tab="generate">
-          <span class="tab-icon">⚡</span> Generate
-        </button>
-        <button class="main-tab" data-main-tab="settings">
-          <span class="tab-icon">⚙️</span> Instruction Settings
-          <span class="settings-count-badge" id="settings-count">0</span>
-        </button>
-        <button class="main-tab" data-main-tab="history">
-          <span class="tab-icon">📜</span> History
-        </button>
+
+    <nav class="sidebar-nav">
+      <button class="nav-item active" data-page="generate">
+        <span class="nav-icon">⚡</span>
+        <span class="nav-label">Generate</span>
+      </button>
+      <button class="nav-item" data-page="settings">
+        <span class="nav-icon">⚙️</span>
+        <span class="nav-label">Settings</span>
+        <span class="nav-badge" id="settings-badge">0</span>
+      </button>
+      <button class="nav-item" data-page="history">
+        <span class="nav-icon">📜</span>
+        <span class="nav-label">History</span>
+        <span class="nav-badge" id="history-badge">0</span>
+      </button>
+      <button class="nav-item" data-page="stats">
+        <span class="nav-icon">📊</span>
+        <span class="nav-label">Stats</span>
+      </button>
+    </nav>
+
+    <div class="sidebar-bottom">
+      <div class="api-status-row" id="api-status-row">
+        <span class="api-dot-sm" id="dot-hf" title="Hugging Face">HF</span>
+        <span class="api-dot-sm" id="dot-google" title="Google Gemini">GG</span>
       </div>
+      <button class="theme-toggle" id="btn-theme" title="Toggle theme (Alt+T)">🌙</button>
+      <a class="sidebar-link" href="/docs" target="_blank" title="API Docs">📖</a>
     </div>
-  </header>
+  </aside>
 
-  <!-- ═══════════════════════════════════════════════════════════════════ -->
-  <!-- TAB 1: GENERATE                                                      -->
-  <!-- ═══════════════════════════════════════════════════════════════════ -->
-  <div id="tab-generate" class="tab-page active">
-    <main>
+  <!-- ── Main content ───────────────────────────────────────────── -->
+  <div id="main-content">
 
-      <!-- API Config Banner -->
-      <div class="api-config-banner">
-        <div class="api-banner-header">
-          <div class="api-banner-icon">🔑</div>
-          <div class="api-banner-title">
-            <h3>AI Enhancement Keys</h3>
-            <p>API keys are read from environment variables first. Enter below to override for this session.</p>
-          </div>
+    <!-- PAGE: GENERATE -->
+    <div class="page active" id="page-generate">
+      <div class="page-header">
+        <div>
+          <h1 class="page-title">Generate Prompt</h1>
+          <p class="page-subtitle">Transform any instruction into a structured, production-ready prompt for Google AI Studio.</p>
         </div>
-        <div class="api-row">
-          <div class="api-field">
-            <label><span class="lbl-dot"></span> AI Provider</label>
-            <select id="provider">
-              <option value="none">⚡ Local Engine (no API key needed)</option>
-              <option value="google">🌐 Google Gemini</option>
-              <option value="huggingface">🤗 Hugging Face</option>
-            </select>
-          </div>
-          <div class="api-field" id="api-key-group">
-            <label>
-              <span class="lbl-dot"></span> API Key
-              <span class="lbl-opt" id="api-key-hint">Select a provider above</span>
-            </label>
-            <div class="api-input-wrap">
-              <input type="password" id="api-key" placeholder="Not required for local engine" disabled/>
-              <button class="api-toggle-btn" id="btn-toggle-key" title="Show/hide">👁</button>
+        <div class="page-header-actions">
+          <button class="btn-ghost btn-sm" id="btn-shortcuts" title="Keyboard shortcuts (?)">⌨️ Shortcuts</button>
+          <button class="btn-secondary" id="btn-load-from-settings">📂 Load Setting</button>
+        </div>
+      </div>
+
+      <!-- API Key Banner -->
+      <div class="panel api-panel" id="api-panel">
+        <div class="api-panel-toggle" id="btn-api-panel-toggle">
+          <span>🔑 AI Enhancement</span>
+          <span class="api-panel-status" id="api-panel-status">Local Engine Active</span>
+          <span class="chevron" id="api-chevron">▾</span>
+        </div>
+        <div class="api-panel-body" id="api-panel-body">
+          <div class="api-grid">
+            <div class="field">
+              <label>Provider</label>
+              <select id="provider">
+                <option value="none">⚡ Local Engine</option>
+                <option value="google">🌐 Google Gemini</option>
+                <option value="huggingface">🤗 Hugging Face</option>
+              </select>
+            </div>
+            <div class="field" id="api-key-group">
+              <label>API Key <span class="key-hint" id="key-hint">Select provider first</span></label>
+              <div class="input-with-action">
+                <input type="password" id="api-key" placeholder="Not required" disabled/>
+                <button class="icon-btn" id="btn-toggle-key" title="Show/hide">👁</button>
+                <button class="icon-btn" id="btn-check-key" title="Validate key" disabled>✓</button>
+              </div>
+              <div class="field-note" id="key-status-note">
+                <span class="status-dot" id="key-dot"></span>
+                <span id="key-status-text">No key entered</span>
+              </div>
             </div>
-            <div class="api-field-note">
-              <span class="api-dot" id="api-status-dot"></span>
-              <span id="api-status-text">No key entered</span>
+            <div class="field" id="model-field" style="display:none">
+              <label>Model Override <span class="lbl-opt">optional</span></label>
+              <input type="text" id="provider-model" placeholder="e.g. gemini-1.5-pro"/>
             </div>
           </div>
         </div>
       </div>
 
       <!-- Step Progress -->
-      <div class="step-progress">
-        <div class="prog-step active" id="pstep-1"><div class="prog-node">1</div><div class="prog-label">Input</div></div>
-        <div class="prog-line" id="pline-1"></div>
-        <div class="prog-step" id="pstep-2"><div class="prog-node">2</div><div class="prog-label">Review</div></div>
-        <div class="prog-line" id="pline-2"></div>
-        <div class="prog-step" id="pstep-3"><div class="prog-node">3</div><div class="prog-label">Finalize</div></div>
-        <div class="prog-line" id="pline-3"></div>
-        <div class="prog-step" id="pstep-4"><div class="prog-node">4</div><div class="prog-label">Export</div></div>
-        <div class="prog-line" id="pline-4"></div>
-        <div class="prog-step" id="pstep-5"><div class="prog-node">5</div><div class="prog-label">Refine</div></div>
+      <div class="stepper" id="stepper">
+        <div class="step active" data-step="1"><div class="step-dot"><span>1</span></div><div class="step-label">Input</div></div>
+        <div class="step-line"></div>
+        <div class="step" data-step="2"><div class="step-dot"><span>2</span></div><div class="step-label">Review</div></div>
+        <div class="step-line"></div>
+        <div class="step" data-step="3"><div class="step-dot"><span>3</span></div><div class="step-label">Finalise</div></div>
+        <div class="step-line"></div>
+        <div class="step" data-step="4"><div class="step-dot"><span>4</span></div><div class="step-label">Export</div></div>
+        <div class="step-line"></div>
+        <div class="step" data-step="5"><div class="step-dot"><span>5</span></div><div class="step-label">Refine</div></div>
       </div>
 
       <!-- STEP 1: Input -->
-      <section id="step-input" class="card">
-        <div class="card-header">
-          <h2>✍️ Enter Your Instruction</h2>
-          <span class="step-badge">STEP 01</span>
-        </div>
-        <div class="info-banner">
-          <span class="info-icon">💡</span>
-          <span>Describe any task. PromptForge transforms it into a fully structured Google AI Studio prompt — with role, constraints, style, safety, and examples.</span>
+      <div class="panel" id="step-input">
+        <div class="panel-header">
+          <h2>✍️ Your Instruction</h2>
+          <span class="step-tag">STEP 01</span>
         </div>
+        <div class="info-note">💡 Describe any task. PromptForge structures it with role, constraints, style, safety guardrails, and examples — ready for Google AI Studio.</div>
         <div class="field">
-          <label><span class="lbl-dot"></span> Instruction</label>
-          <textarea id="instruction" rows="5" placeholder="e.g. Generate a TypeScript React component with TailwindCSS and unit tests."></textarea>
+          <label>Instruction <span class="required">*</span></label>
+          <textarea id="instruction" rows="5" placeholder="e.g. Create a TypeScript React component with TailwindCSS and Jest unit tests." maxlength="8000"></textarea>
+          <div class="char-counter"><span id="instr-count">0</span> / 8000</div>
         </div>
         <div class="field">
-          <label><span class="lbl-dot"></span> Additional Context <span class="lbl-opt">optional</span></label>
-          <textarea id="extra-context" rows="2" placeholder="e.g. Support dark mode, WCAG AA accessibility, React hooks only."></textarea>
-        </div>
-        <div class="advanced-toggle-row">
-          <button class="btn-link" id="btn-toggle-advanced">⚙️ Advanced options</button>
+          <label>Extra Context <span class="lbl-opt">optional</span></label>
+          <textarea id="extra-context" rows="2" placeholder="e.g. Support dark mode, WCAG AA, hooks only." maxlength="2000"></textarea>
         </div>
-        <div id="advanced-options" class="advanced-panel hidden">
+
+        <details class="advanced-block" id="advanced-block">
+          <summary>⚙️ Advanced Options</summary>
           <div class="adv-grid">
             <div class="field">
-              <label><span class="lbl-dot"></span> Persona
-                <span class="tooltip-wrap"><span class="tooltip-icon">?</span><span class="tooltip-text">Sets the AI's role identity, influencing vocabulary, depth, and response style.</span></span>
+              <label>Persona
+                <span class="tip" title="Sets the AI's domain expertise and communication style.">?</span>
               </label>
               <select id="gen-persona">
-                <option value="default">🤖 Auto-detect from instruction</option>
-                <option value="senior_dev">👨‍💻 Senior Software Engineer</option>
+                <option value="default">🤖 Auto-detect</option>
+                <option value="senior_dev">👨‍💻 Senior Dev</option>
                 <option value="data_scientist">📊 Data Scientist</option>
-                <option value="tech_writer">✍️ Technical Writer</option>
+                <option value="tech_writer">✍️ Tech Writer</option>
                 <option value="product_mgr">📋 Product Manager</option>
-                <option value="security_eng">🔒 Security Engineer</option>
-                <option value="custom">✏️ Custom persona…</option>
+                <option value="security_eng">🔒 Security Eng</option>
+                <option value="devops_eng">🚀 DevOps Eng</option>
+                <option value="ml_engineer">🧠 ML Engineer</option>
+                <option value="custom">✏️ Custom…</option>
               </select>
             </div>
             <div class="field">
-              <label><span class="lbl-dot"></span> Style
-                <span class="tooltip-wrap"><span class="tooltip-icon">?</span><span class="tooltip-text">Controls verbosity, formality, and explanation depth.</span></span>
+              <label>Style
+                <span class="tip" title="Controls verbosity, tone, and explanation depth.">?</span>
               </label>
               <select id="gen-style">
                 <option value="professional">💼 Professional</option>
                 <option value="concise">⚡ Concise</option>
                 <option value="detailed">📖 Detailed</option>
-                <option value="beginner">🎓 Beginner-friendly</option>
+                <option value="beginner">🎓 Beginner</option>
                 <option value="formal">📄 Formal</option>
                 <option value="creative">🎨 Creative</option>
               </select>
             </div>
           </div>
           <div class="field" id="custom-persona-field" style="display:none">
-            <label><span class="lbl-dot"></span> Custom Persona Text</label>
+            <label>Custom Persona</label>
             <input type="text" id="gen-custom-persona" placeholder="e.g. Expert Kubernetes architect with CNCF certification"/>
           </div>
           <div class="field">
-            <label><span class="lbl-dot"></span> Additional Constraints <span class="lbl-opt">one per line</span></label>
-            <textarea id="gen-constraints" rows="3" placeholder="e.g. Must use async/await&#10;Rate limiting required&#10;No external dependencies"></textarea>
+            <label>Constraints <span class="lbl-opt">one per line</span></label>
+            <textarea id="gen-constraints" rows="3" placeholder="e.g. Must use async/await&#10;No external dependencies&#10;Rate limiting required"></textarea>
           </div>
-        </div>
+        </details>
+
         <div class="action-row">
-          <button id="btn-generate" class="btn-primary">⚡ Generate Prompt Manifest</button>
-          <button id="btn-load-from-settings" class="btn-secondary">📂 Load from Settings</button>
+          <button class="btn-primary" id="btn-generate">⚡ Generate Manifest <kbd>⌘↵</kbd></button>
         </div>
-      </section>
+      </div>
 
       <!-- STEP 2: Manifest Review -->
-      <section id="step-manifest" class="card hidden fade-in">
-        <div class="card-header">
-          <h2>🔍 Review &amp; Edit Manifest</h2>
-          <span class="step-badge">STEP 02</span>
+      <div class="panel hidden" id="step-manifest">
+        <div class="panel-header">
+          <h2>🔍 Review & Edit</h2>
+          <span class="step-tag">STEP 02</span>
         </div>
-        <p class="muted">Every field is editable. Tweak anything before approving — the final prompt will regenerate from your edits.</p>
-        <div id="manifest-grid" class="manifest-grid"></div>
+        <p class="muted">Every field is editable. Edit anything before approving.</p>
+        <div class="manifest-grid" id="manifest-grid"></div>
         <details>
-          <summary>📋 Raw JSON Manifest</summary>
-          <pre id="manifest-json"></pre>
-        </details>
-        <!-- Explanation panel -->
-        <div id="explanation-panel" class="explanation-panel hidden">
-          <div class="explanation-header">
-            <span class="explanation-icon">🧠</span>
-            <strong>Why was this prompt structured this way?</strong>
+          <summary>Raw JSON manifest</summary>
+          <div class="code-block">
+            <button class="copy-btn" data-target="manifest-json">📋 Copy</button>
+            <pre id="manifest-json"></pre>
           </div>
+        </details>
+        <div class="explanation-panel hidden" id="explanation-panel">
+          <div class="explanation-header">🧠 Why was this structured this way?</div>
           <div id="explanation-text" class="explanation-body"></div>
-          <div id="key-decisions" class="key-decisions"></div>
+          <div id="key-decisions" class="decision-chips"></div>
         </div>
         <div class="action-row">
-          <button id="btn-approve" class="btn-primary">✅ Approve &amp; Finalize</button>
-          <button id="btn-explain" class="btn-secondary">🧠 Explain Structure</button>
-          <button id="btn-reset" class="btn-secondary">↩ Start Over</button>
+          <button class="btn-primary" id="btn-approve">✅ Approve</button>
+          <button class="btn-secondary" id="btn-explain">🧠 Explain</button>
+          <button class="btn-ghost" id="btn-reset">↩ Start Over</button>
         </div>
-      </section>
+      </div>
 
-      <!-- STEP 3: Finalized Prompt -->
-      <section id="step-finalized" class="card hidden fade-in">
-        <div class="card-header">
-          <h2>🎉 Finalized Prompt</h2>
-          <span class="step-badge">STEP 03</span>
+      <!-- STEP 3: Finalised -->
+      <div class="panel hidden" id="step-finalized">
+        <div class="panel-header">
+          <h2>🎉 Finalised Prompt</h2>
+          <span class="step-tag">STEP 03</span>
         </div>
-        <p class="muted">Your structured prompt is ready. Copy it directly into Google AI Studio or export it below.</p>
-        <div class="tab-bar">
-          <button class="tab active" data-tab="text">📄 Plain Text</button>
-          <button class="tab" data-tab="json">{ } JSON</button>
+        <p class="muted">Your prompt is ready. Copy directly into Google AI Studio.</p>
+        <div class="inner-tabs">
+          <button class="inner-tab active" data-tab="text">📄 Plain Text</button>
+          <button class="inner-tab" data-tab="json">{ } JSON</button>
         </div>
-        <div id="tab-text" class="tab-panel">
-          <pre id="finalized-text"></pre>
-          <button class="btn-copy" data-target="finalized-text">📋 Copy</button>
+        <div class="inner-panel active" id="itab-text">
+          <div class="code-block">
+            <button class="copy-btn" data-target="finalized-text">📋 Copy</button>
+            <pre id="finalized-text"></pre>
+          </div>
         </div>
-        <div id="tab-json" class="tab-panel hidden">
-          <pre id="finalized-json"></pre>
-          <button class="btn-copy" data-target="finalized-json">📋 Copy</button>
+        <div class="inner-panel hidden" id="itab-json">
+          <div class="code-block">
+            <button class="copy-btn" data-target="finalized-json">📋 Copy</button>
+            <pre id="finalized-json"></pre>
+          </div>
         </div>
         <div class="divider"></div>
         <div class="action-row">
-          <button id="btn-export-json" class="btn-secondary">⬇ JSON</button>
-          <button id="btn-export-txt" class="btn-secondary">⬇ Text</button>
-          <button id="btn-refine" class="btn-secondary">🔁 Refine</button>
-          <button id="btn-save-as-setting" class="btn-secondary">💾 Save as Setting</button>
-          <button id="btn-new" class="btn-primary">➕ New Prompt</button>
+          <button class="btn-secondary" id="btn-export-json">⬇ Export JSON</button>
+          <button class="btn-secondary" id="btn-export-txt">⬇ Export Text</button>
+          <button class="btn-secondary" id="btn-refine">🔁 Refine</button>
+          <button class="btn-secondary" id="btn-save-as-setting">💾 Save as Setting</button>
+          <button class="btn-ghost" id="btn-favorite-prompt" title="Star this prompt">☆ Favourite</button>
+          <button class="btn-primary" id="btn-new">➕ New Prompt</button>
         </div>
-      </section>
+      </div>
 
       <!-- STEP 5: Refine -->
-      <section id="step-refine" class="card hidden fade-in">
-        <div class="card-header">
+      <div class="panel hidden" id="step-refine">
+        <div class="panel-header">
           <h2>🔁 Refine Prompt</h2>
-          <span class="step-badge">STEP 05</span>
+          <span class="step-tag">STEP 05</span>
         </div>
-        <p class="muted">Describe what to change. PromptForge creates a new version (v+1) for re-approval.</p>
+        <p class="muted">Describe what to change. A new version will be created for approval.</p>
         <div class="field">
-          <label><span class="lbl-dot"></span> Your Feedback</label>
+          <label>Your Feedback</label>
           <textarea id="feedback" rows="3" placeholder="e.g. Add ARIA labels, keyboard navigation, and a dark-mode variant prop."></textarea>
         </div>
         <div class="action-row">
-          <button id="btn-submit-refine" class="btn-primary">🔁 Submit Refinement</button>
-          <button id="btn-cancel-refine" class="btn-secondary">Cancel</button>
+          <button class="btn-primary" id="btn-submit-refine">🔁 Submit Refinement</button>
+          <button class="btn-ghost" id="btn-cancel-refine">Cancel</button>
         </div>
-      </section>
-
-    </main>
-  </div><!-- /tab-generate -->
+      </div>
+    </div><!-- /page-generate -->
 
 
-  <!-- ═══════════════════════════════════════════════════════════════════ -->
-  <!-- TAB 2: INSTRUCTION SETTINGS                                          -->
-  <!-- ═══════════════════════════════════════════════════════════════════ -->
-  <div id="tab-settings" class="tab-page hidden">
-    <main>
+    <!-- PAGE: SETTINGS -->
+    <div class="page hidden" id="page-settings">
+      <div class="page-header">
+        <div>
+          <h1 class="page-title">Instruction Settings</h1>
+          <p class="page-subtitle">Save, manage, and reuse instruction templates.</p>
+        </div>
+        <div class="page-header-actions">
+          <button class="btn-ghost btn-sm" id="btn-export-all-settings" title="Download all settings as JSON">⬇ Export All</button>
+          <button class="btn-secondary btn-sm" id="btn-settings-clear">✕ Clear Form</button>
+        </div>
+      </div>
 
       <div class="settings-layout">
-
-        <!-- ── Left: Settings Form ────────────────────────────────── -->
+        <!-- Form -->
         <div class="settings-form-col">
-          <div class="card" id="settings-form-card">
-            <div class="card-header">
-              <h2 id="settings-form-title">➕ New Instruction Setting</h2>
-              <div style="display:flex;gap:8px">
-                <button class="btn-secondary btn-sm" id="btn-settings-clear">✕ Clear</button>
-              </div>
+          <div class="panel">
+            <div class="panel-header">
+              <h2 id="settings-form-title">➕ New Setting</h2>
             </div>
-
             <input type="hidden" id="edit-settings-id"/>
 
             <div class="field">
-              <label>
-                <span class="lbl-dot"></span> Title *
-                <span class="tooltip-wrap"><span class="tooltip-icon">?</span><span class="tooltip-text">A short, descriptive name for this instruction template.</span></span>
-              </label>
-              <input type="text" id="s-title" placeholder="e.g. React Component Generator" maxlength="120"/>
+              <label>Title <span class="required">*</span></label>
+              <input type="text" id="s-title" maxlength="120" placeholder="e.g. React Component Generator"/>
             </div>
-
             <div class="field">
-              <label><span class="lbl-dot"></span> Description <span class="lbl-opt">optional</span></label>
-              <textarea id="s-description" rows="2" placeholder="Brief notes about when to use this setting…"></textarea>
+              <label>Description <span class="lbl-opt">optional</span></label>
+              <textarea id="s-description" rows="2" placeholder="When to use this setting…"></textarea>
             </div>
-
             <div class="field">
-              <label><span class="lbl-dot"></span> Instruction *</label>
-              <textarea id="s-instruction" rows="5" placeholder="The full instruction or task description that will be used to generate the prompt…"></textarea>
-              <div class="field-note" id="s-instruction-count">0 / 8000 characters</div>
+              <label>Instruction <span class="required">*</span></label>
+              <textarea id="s-instruction" rows="5" maxlength="8000" placeholder="The full task instruction that will drive prompt generation…"></textarea>
+              <div class="char-counter"><span id="s-instr-count">0</span> / 8000</div>
             </div>
-
             <div class="field">
-              <label><span class="lbl-dot"></span> Extra Context <span class="lbl-opt">optional</span></label>
-              <textarea id="s-extra-context" rows="2" placeholder="Additional constraints, background info, or requirements…"></textarea>
+              <label>Extra Context <span class="lbl-opt">optional</span></label>
+              <textarea id="s-extra-context" rows="2" placeholder="Background info, constraints, requirements…"></textarea>
             </div>
-
-            <div class="settings-grid-2">
+            <div class="two-col">
               <div class="field">
-                <label>
-                  <span class="lbl-dot"></span> Persona
-                  <span class="tooltip-wrap"><span class="tooltip-icon">?</span><span class="tooltip-text">The AI persona — sets domain expertise and communication style.</span></span>
-                </label>
+                <label>Persona</label>
                 <select id="s-persona">
                   <option value="default">🤖 Auto-detect</option>
                   <option value="senior_dev">👨‍💻 Senior Dev</option>
                   <option value="data_scientist">📊 Data Scientist</option>
                   <option value="tech_writer">✍️ Tech Writer</option>
                   <option value="product_mgr">📋 Product Manager</option>
-                  <option value="security_eng">🔒 Security Engineer</option>
+                  <option value="security_eng">🔒 Security Eng</option>
+                  <option value="devops_eng">🚀 DevOps Eng</option>
+                  <option value="ml_engineer">🧠 ML Engineer</option>
                   <option value="custom">✏️ Custom…</option>
                 </select>
               </div>
               <div class="field">
-                <label>
-                  <span class="lbl-dot"></span> Style
-                  <span class="tooltip-wrap"><span class="tooltip-icon">?</span><span class="tooltip-text">Controls verbosity, tone, and explanation depth.</span></span>
-                </label>
+                <label>Style</label>
                 <select id="s-style">
                   <option value="professional">💼 Professional</option>
                   <option value="concise">⚡ Concise</option>
@@ -327,147 +333,191 @@
                 </select>
               </div>
             </div>
-
             <div class="field" id="s-custom-persona-field" style="display:none">
-              <label><span class="lbl-dot"></span> Custom Persona Text</label>
+              <label>Custom Persona Text</label>
               <input type="text" id="s-custom-persona" placeholder="e.g. Expert Rust systems programmer"/>
             </div>
-
-            <div class="settings-grid-2">
+            <div class="two-col">
               <div class="field">
-                <label>
-                  <span class="lbl-dot"></span> Output Format
-                </label>
+                <label>Output Format</label>
                 <select id="s-output-format">
-                  <option value="both">📦 Both (Text + JSON)</option>
-                  <option value="text">📄 Text only</option>
-                  <option value="json">{ } JSON only</option>
+                  <option value="both">📦 Both</option>
+                  <option value="text">📄 Text</option>
+                  <option value="json">{ } JSON</option>
                 </select>
               </div>
               <div class="field">
-                <label>
-                  <span class="lbl-dot"></span> AI Enhancement
-                </label>
+                <label>AI Enhancement</label>
                 <select id="s-provider">
-                  <option value="none">⚡ None (local)</option>
-                  <option value="huggingface">🤗 Hugging Face</option>
+                  <option value="none">⚡ None</option>
+                  <option value="huggingface">🤗 HuggingFace</option>
                   <option value="google">🌐 Google Gemini</option>
                 </select>
               </div>
             </div>
-
             <div class="field">
-              <label>
-                <span class="lbl-dot"></span> Constraints
-                <span class="tooltip-wrap"><span class="tooltip-icon">?</span><span class="tooltip-text">Hard rules the AI must follow. One constraint per line.</span></span>
-                <span class="lbl-opt">one per line</span>
-              </label>
-              <textarea id="s-constraints" rows="4" placeholder="Use TypeScript strict mode&#10;Include unit tests&#10;WCAG 2.1 AA accessibility&#10;No external dependencies"></textarea>
+              <label>Constraints <span class="lbl-opt">one per line</span></label>
+              <textarea id="s-constraints" rows="4" placeholder="TypeScript strict mode&#10;WCAG 2.1 AA&#10;Include unit tests"></textarea>
             </div>
-
             <div class="field">
-              <label><span class="lbl-dot"></span> Tags <span class="lbl-opt">comma-separated</span></label>
+              <label>Tags <span class="lbl-opt">comma-separated</span></label>
               <input type="text" id="s-tags" placeholder="react, typescript, frontend"/>
+              <div class="tag-suggestions" id="tag-suggestions"></div>
             </div>
-
-            <div class="field enhance-toggle-row">
+            <div class="toggle-row">
               <label class="toggle-label">
-                <input type="checkbox" id="s-enhance" class="toggle-checkbox"/>
-                <span class="toggle-track">
-                  <span class="toggle-thumb"></span>
-                </span>
-                <span>Enable AI enhancement on generate</span>
+                <input type="checkbox" id="s-enhance" class="toggle-cb"/>
+                <span class="toggle-track"><span class="toggle-thumb"></span></span>
+                Enable AI enhancement on generate
+              </label>
+              <label class="toggle-label">
+                <input type="checkbox" id="s-favorite" class="toggle-cb"/>
+                <span class="toggle-track"><span class="toggle-thumb"></span></span>
+                Favourite / Pin
               </label>
             </div>
-
             <div class="action-row">
-              <button id="btn-settings-save" class="btn-primary">💾 Save Setting</button>
-              <button id="btn-settings-generate" class="btn-secondary" style="display:none">⚡ Generate Now</button>
+              <button class="btn-primary" id="btn-settings-save">💾 Save Setting</button>
+              <button class="btn-secondary hidden" id="btn-settings-generate">⚡ Generate Now</button>
             </div>
           </div>
         </div>
 
-        <!-- ── Right: Saved Settings List ─────────────────────────── -->
+        <!-- List -->
         <div class="settings-list-col">
-          <div class="settings-list-header">
-            <h3>Saved Settings <span id="settings-total-count" class="count-badge">0</span></h3>
-            <div class="settings-list-actions">
-              <input type="text" id="settings-search" placeholder="🔍 Search…" class="search-input"/>
-              <select id="settings-filter-tag" class="filter-select">
-                <option value="">All tags</option>
-              </select>
+          <div class="list-header">
+            <span>Saved <span class="count-badge" id="settings-total-count">0</span></span>
+            <div class="list-controls">
+              <input type="text" id="settings-search" class="search-input" placeholder="🔍 Search…"/>
+              <select id="settings-filter-tag" class="filter-select"><option value="">All tags</option></select>
+              <button class="icon-btn" id="btn-filter-favorites" title="Show favourites only">☆</button>
             </div>
           </div>
-
           <div id="settings-list" class="settings-list">
-            <div class="settings-empty">
+            <div class="empty-state">
               <div class="empty-icon">📋</div>
-              <p>No settings yet. Create your first one!</p>
+              <p>No settings yet — create your first one!</p>
             </div>
           </div>
         </div>
-
-      </div><!-- /settings-layout -->
-    </main>
-  </div><!-- /tab-settings -->
+      </div>
+    </div><!-- /page-settings -->
 
 
-  <!-- ═══════════════════════════════════════════════════════════════════ -->
-  <!-- TAB 3: HISTORY                                                        -->
-  <!-- ═══════════════════════════════════════════════════════════════════ -->
-  <div id="tab-history" class="tab-page hidden">
-    <main>
-      <div class="card">
-        <div class="card-header">
-          <h2>📜 Prompt History</h2>
-          <button id="btn-load-history" class="btn-secondary btn-sm">↺ Refresh</button>
+    <!-- PAGE: HISTORY -->
+    <div class="page hidden" id="page-history">
+      <div class="page-header">
+        <div>
+          <h1 class="page-title">Prompt History</h1>
+          <p class="page-subtitle">All generated prompts with status tracking.</p>
         </div>
+        <div class="page-header-actions">
+          <select id="history-status-filter" class="filter-select">
+            <option value="">All statuses</option>
+            <option value="pending">Pending</option>
+            <option value="approved">Approved</option>
+            <option value="exported">Exported</option>
+            <option value="archived">Archived</option>
+          </select>
+          <input type="text" id="history-search" class="search-input" placeholder="🔍 Search…"/>
+          <button class="btn-ghost btn-sm" id="btn-history-refresh">↺ Refresh</button>
+        </div>
+      </div>
+      <div class="panel">
         <div class="table-wrap">
           <table id="history-table">
             <thead>
               <tr>
+                <th style="width:30px">★</th>
                 <th>ID</th>
                 <th>Instruction</th>
                 <th>Ver</th>
                 <th>Status</th>
-                <th>Settings</th>
+                <th>Tags</th>
                 <th>Date</th>
                 <th>Actions</th>
               </tr>
             </thead>
             <tbody id="history-body">
-              <tr><td class="empty-msg" colspan="7">Click ↺ Refresh to load history.</td></tr>
+              <tr><td class="empty-msg" colspan="8">Click ↺ Refresh to load history.</td></tr>
             </tbody>
           </table>
         </div>
       </div>
-    </main>
-  </div><!-- /tab-history -->
+    </div><!-- /page-history -->
 
-  <!-- ── Footer ─────────────────────────────────────────────────────── -->
-  <footer>
-    <div class="footer-inner">
-      <span class="footer-copy">© 2025 PromptForge v3.0 · Port 7860</span>
-      <div class="footer-links">
-        <a href="/docs" target="_blank">API Docs</a>
-        <a href="/redoc" target="_blank">ReDoc</a>
-        <a href="/health" target="_blank">Health</a>
+
+    <!-- PAGE: STATS -->
+    <div class="page hidden" id="page-stats">
+      <div class="page-header">
+        <div>
+          <h1 class="page-title">Dashboard</h1>
+          <p class="page-subtitle">Overview of your PromptForge activity.</p>
+        </div>
+        <button class="btn-ghost btn-sm" id="btn-stats-refresh">↺ Refresh</button>
+      </div>
+
+      <div class="stats-grid" id="stats-grid">
+        <!-- Populated by JS -->
+        <div class="stat-card skeleton"></div>
+        <div class="stat-card skeleton"></div>
+        <div class="stat-card skeleton"></div>
+        <div class="stat-card skeleton"></div>
+      </div>
+
+      <div class="stats-row">
+        <div class="panel" id="stats-personas-panel">
+          <div class="panel-header"><h2>Top Personas</h2></div>
+          <div id="stats-personas" class="bar-chart"></div>
+        </div>
+        <div class="panel" id="stats-styles-panel">
+          <div class="panel-header"><h2>Style Distribution</h2></div>
+          <div id="stats-styles" class="bar-chart"></div>
+        </div>
       </div>
-    </div>
-  </footer>
 
+      <div class="panel" id="stats-activity-panel">
+        <div class="panel-header"><h2>Status Breakdown</h2></div>
+        <div id="stats-statuses" class="status-breakdown"></div>
+      </div>
+    </div><!-- /page-stats -->
+
+  </div><!-- /main-content -->
 </div><!-- #app -->
 
 <!-- Load-from-settings modal -->
 <div id="modal-overlay" class="modal-overlay hidden">
   <div class="modal-box">
     <div class="modal-header">
-      <h3>📂 Load from Saved Setting</h3>
-      <button class="modal-close" id="btn-modal-close">✕</button>
+      <h3>📂 Load from Setting</h3>
+      <button class="icon-btn" id="btn-modal-close">✕</button>
+    </div>
+    <div class="modal-body">
+      <input type="text" id="modal-search" class="search-input" style="width:100%;margin-bottom:12px" placeholder="🔍 Search settings…"/>
+      <div id="modal-list" class="modal-list"></div>
+    </div>
+  </div>
+</div>
+
+<!-- Keyboard shortcuts modal -->
+<div id="shortcuts-modal" class="modal-overlay hidden">
+  <div class="modal-box" style="max-width:420px">
+    <div class="modal-header">
+      <h3>⌨️ Keyboard Shortcuts</h3>
+      <button class="icon-btn" id="btn-shortcuts-close">✕</button>
     </div>
     <div class="modal-body">
-      <input type="text" id="modal-search" class="modal-search" placeholder="🔍 Search settings…"/>
-      <div id="modal-settings-list" class="modal-list"></div>
+      <table class="shortcuts-table">
+        <tr><td><kbd>⌘↵</kbd> / <kbd>Ctrl+↵</kbd></td><td>Generate prompt</td></tr>
+        <tr><td><kbd>Alt+B</kbd></td><td>Toggle sidebar</td></tr>
+        <tr><td><kbd>Alt+T</kbd></td><td>Toggle theme</td></tr>
+        <tr><td><kbd>Alt+1</kbd></td><td>Go to Generate</td></tr>
+        <tr><td><kbd>Alt+2</kbd></td><td>Go to Settings</td></tr>
+        <tr><td><kbd>Alt+3</kbd></td><td>Go to History</td></tr>
+        <tr><td><kbd>Alt+4</kbd></td><td>Go to Stats</td></tr>
+        <tr><td><kbd>?</kbd></td><td>Show this panel</td></tr>
+        <tr><td><kbd>Esc</kbd></td><td>Close modal / reset</td></tr>
+      </table>
     </div>
   </div>
 </div>

frontend/style.css

@@ -1,278 +1,450 @@
-/* PromptForge v3.0 — Full UI including Instruction Settings Panel */
-@import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap');
+/* PromptForge v4.0 — Dark-first editorial design system */
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap');
 
+/* ── Design tokens ── */
 :root {
-  --bg:#f4f6fb; --surface:#ffffff; --surface-2:#f0f3f9; --surface-3:#e8edf6;
-  --border:#dde3ee; --border-focus:#6366f1;
-  --indigo:#6366f1; --indigo-dk:#4f46e5; --indigo-lt:#eef0ff; --indigo-mid:#c7d2fe;
-  --violet:#8b5cf6; --teal:#0d9488; --teal-lt:#ccfbf1;
-  --green:#10b981; --green-lt:#d1fae5;
-  --amber:#f59e0b; --amber-lt:#fef3c7;
-  --red:#ef4444; --red-lt:#fee2e2;
-  --text:#111827; --text-soft:#374151; --text-muted:#6b7280; --text-faint:#9ca3af;
-  --radius-sm:8px; --radius-md:12px; --radius-lg:16px; --radius-xl:20px;
-  --shadow-sm:0 1px 3px rgba(0,0,0,.08),0 1px 2px rgba(0,0,0,.04);
-  --shadow-md:0 4px 16px rgba(0,0,0,.08),0 2px 6px rgba(0,0,0,.04);
-  --shadow-lg:0 12px 40px rgba(0,0,0,.10),0 4px 12px rgba(0,0,0,.06);
-  --shadow-btn:0 2px 8px rgba(99,102,241,.30);
-  --font-body:'Plus Jakarta Sans',system-ui,sans-serif;
-  --font-mono:'JetBrains Mono','Fira Code',monospace;
+  --font-ui:   'Space Grotesk', system-ui, sans-serif;
+  --font-mono: 'IBM Plex Mono', 'Fira Code', monospace;
+
+  /* Dark theme (default) */
+  --bg:        #0e0f14;
+  --bg-2:      #14151c;
+  --bg-3:      #1c1d27;
+  --border:    rgba(255,255,255,.08);
+  --border-focus: #7c6dfa;
+
+  --text:      #f0f0f8;
+  --text-soft: #b8b9cc;
+  --text-muted:#7c7d96;
+  --text-faint:#4a4b62;
+
+  --accent:    #7c6dfa;
+  --accent-dk: #5a4de8;
+  --accent-lt: rgba(124,109,250,.12);
+  --accent-mid:rgba(124,109,250,.30);
+  --green:     #34d399;
+  --green-lt:  rgba(52,211,153,.12);
+  --red:       #f87171;
+  --red-lt:    rgba(248,113,113,.12);
+  --amber:     #fbbf24;
+  --amber-lt:  rgba(251,191,36,.12);
+  --teal:      #2dd4bf;
+  --violet:    #a78bfa;
+
+  --sidebar-w: 220px;
+  --header-h:  64px;
+  --r-sm: 6px; --r-md: 10px; --r-lg: 14px; --r-xl: 18px;
+  --shadow: 0 4px 24px rgba(0,0,0,.4);
+  --shadow-sm: 0 1px 6px rgba(0,0,0,.3);
+  --transition: 200ms cubic-bezier(.4,0,.2,1);
 }
-*,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
-html{scroll-behavior:smooth}
-body{background:var(--bg);color:var(--text);font-family:var(--font-body);font-size:15px;line-height:1.6;min-height:100vh;-webkit-font-smoothing:antialiased}
-::-webkit-scrollbar{width:5px}::-webkit-scrollbar-thumb{background:var(--border);border-radius:4px}
-::-webkit-scrollbar-thumb:hover{background:var(--indigo-mid)}
-#cursor-dot,#cursor-ring,.bg-mesh,.bg-grid,.orb{display:none!important}
+
+[data-theme="light"] {
+  --bg:        #f5f5f9;
+  --bg-2:      #ffffff;
+  --bg-3:      #eeeef5;
+  --border:    rgba(0,0,0,.10);
+  --border-focus: #7c6dfa;
+  --text:      #111128;
+  --text-soft: #373757;
+  --text-muted:#6b6b8a;
+  --text-faint:#9999b8;
+  --accent-lt: rgba(124,109,250,.10);
+  --accent-mid:rgba(124,109,250,.25);
+  --shadow:    0 4px 24px rgba(0,0,0,.08);
+  --shadow-sm: 0 1px 6px rgba(0,0,0,.06);
+}
+
+/* ── Reset ── */
+*,*::before,*::after { box-sizing:border-box; margin:0; padding:0; }
+html { scroll-behavior:smooth; }
+body { background:var(--bg); color:var(--text); font-family:var(--font-ui); font-size:14px;
+  line-height:1.6; min-height:100vh; -webkit-font-smoothing:antialiased; overflow-x:hidden; }
+::-webkit-scrollbar { width:4px; height:4px; }
+::-webkit-scrollbar-thumb { background:var(--border); border-radius:4px; }
+::-webkit-scrollbar-thumb:hover { background:var(--accent-mid); }
+button { cursor:pointer; font-family:var(--font-ui); }
 
 /* ── App shell ── */
-#app{min-height:100vh;display:flex;flex-direction:column}
-.tab-page{display:none;flex:1}
-.tab-page.active{display:block}
-main{max-width:940px;width:100%;margin:0 auto;padding:24px 20px 80px;display:flex;flex-direction:column;gap:20px}
-
-/* ── Header ── */
-header{position:sticky;top:0;z-index:200;background:rgba(255,255,255,.95);backdrop-filter:blur(16px);border-bottom:1px solid var(--border);box-shadow:0 1px 0 rgba(0,0,0,.04)}
-.header-inner{max-width:940px;margin:0 auto;padding:13px 20px;display:flex;align-items:center;justify-content:space-between;gap:16px}
-.logo-group{display:flex;align-items:center;gap:10px}
-.logo-icon{width:36px;height:36px;background:linear-gradient(135deg,var(--indigo),var(--violet));border-radius:10px;display:grid;place-items:center;font-size:17px;box-shadow:0 2px 10px rgba(99,102,241,.35);flex-shrink:0}
-.logo-text{font-size:1.1rem;font-weight:800;color:var(--text);letter-spacing:-.4px}
-.logo-tag{font-family:var(--font-mono);font-size:.62rem;color:var(--indigo);background:var(--indigo-lt);border:1px solid var(--indigo-mid);padding:2px 8px;border-radius:20px}
-.header-meta{display:flex;align-items:center;gap:10px}
-.api-env-status{display:flex;gap:5px}
-.env-dot{font-size:.62rem;font-family:var(--font-mono);font-weight:700;padding:3px 7px;border-radius:6px;background:var(--surface-3);color:var(--text-faint);border:1px solid var(--border);transition:all .3s;cursor:default}
-.env-dot.active{background:var(--green-lt);color:#065f46;border-color:#6ee7b7}
-.status-pill{display:flex;align-items:center;gap:6px;font-size:.72rem;font-family:var(--font-mono);color:var(--text-muted);background:var(--surface-2);border:1px solid var(--border);padding:5px 11px;border-radius:20px}
-.status-dot{width:6px;height:6px;border-radius:50%;background:var(--green);animation:blink 2.5s ease-in-out infinite}
-@keyframes blink{0%,100%{opacity:1}50%{opacity:.3}}
-.nav-link{font-size:.8rem;font-weight:500;color:var(--text-muted);text-decoration:none;padding:6px 13px;border:1px solid var(--border);border-radius:var(--radius-sm);transition:all .2s;background:var(--surface)}
-.nav-link:hover{color:var(--indigo);border-color:var(--indigo-mid);background:var(--indigo-lt)}
-
-/* ── Main tab bar ── */
-.main-tabs{border-top:1px solid var(--border);background:var(--surface)}
-.tabs-inner{max-width:940px;margin:0 auto;padding:0 20px;display:flex;gap:0}
-.main-tab{display:flex;align-items:center;gap:7px;padding:11px 20px;border:none;background:transparent;font-family:var(--font-body);font-size:.85rem;font-weight:600;color:var(--text-muted);cursor:pointer;border-bottom:2px solid transparent;transition:all .2s;position:relative;white-space:nowrap}
-.main-tab:hover{color:var(--text);background:var(--surface-2)}
-.main-tab.active{color:var(--indigo);border-bottom-color:var(--indigo);background:transparent}
-.tab-icon{font-size:.9rem}
-.settings-count-badge{font-size:.6rem;font-weight:700;background:var(--indigo);color:white;border-radius:10px;padding:1px 6px;min-width:18px;text-align:center;line-height:1.5}
-
-/* ── API Key Panel ── */
-.api-config-banner{background:var(--surface);border:1.5px solid var(--indigo-mid);border-radius:var(--radius-lg);padding:18px 22px;box-shadow:var(--shadow-sm)}
-.api-banner-header{display:flex;align-items:center;gap:12px;margin-bottom:14px}
-.api-banner-icon{width:38px;height:38px;flex-shrink:0;background:var(--indigo-lt);border-radius:var(--radius-md);display:grid;place-items:center;font-size:18px}
-.api-banner-title h3{font-size:.93rem;font-weight:700;color:var(--text)}
-.api-banner-title p{font-size:.78rem;color:var(--text-muted);margin-top:2px}
-.api-row{display:grid;grid-template-columns:1fr 1fr;gap:14px}
-@media(max-width:600px){.api-row{grid-template-columns:1fr}}
-.api-field label{display:flex;align-items:center;gap:6px;font-size:.72rem;font-weight:600;color:var(--text-soft);letter-spacing:.4px;text-transform:uppercase;margin-bottom:7px}
-.api-input-wrap{position:relative}
-.api-input-wrap input{width:100%;padding:10px 38px 10px 13px;background:var(--surface-2);border:1.5px solid var(--border);border-radius:var(--radius-md);font-size:.83rem;font-family:var(--font-mono);color:var(--text);outline:none;transition:border-color .2s,box-shadow .2s,background .2s}
-.api-input-wrap input:focus{border-color:var(--border-focus);background:white;box-shadow:0 0 0 3px rgba(99,102,241,.10)}
-.api-input-wrap input::placeholder{color:var(--text-faint);font-style:italic;font-family:var(--font-body)}
-.api-toggle-btn{position:absolute;right:9px;top:50%;transform:translateY(-50%);background:none;border:none;cursor:pointer;color:var(--text-muted);font-size:14px;padding:3px;transition:color .2s}
-.api-toggle-btn:hover{color:var(--indigo)}
-.api-field-note{font-size:.72rem;color:var(--text-muted);margin-top:5px;display:flex;align-items:center;gap:5px}
-.api-dot{width:6px;height:6px;border-radius:50%;background:var(--text-faint);flex-shrink:0;transition:all .3s}
-.api-dot.set{background:var(--green);box-shadow:0 0 6px var(--green)}
-
-/* ── Step Progress ── */
-.step-progress{display:flex;align-items:center;justify-content:center;padding:8px 0 4px;gap:0}
-.prog-step{display:flex;flex-direction:column;align-items:center;gap:4px}
-.prog-node{width:30px;height:30px;border-radius:50%;border:2px solid var(--border);background:var(--surface);display:grid;place-items:center;font-size:.7rem;font-weight:700;color:var(--text-muted);transition:all .3s cubic-bezier(.34,1.56,.64,1)}
-.prog-step.active .prog-node{border-color:var(--indigo);background:var(--indigo);color:white;box-shadow:0 0 0 4px rgba(99,102,241,.15);transform:scale(1.12)}
-.prog-step.done .prog-node{border-color:var(--green);background:var(--green);color:white;font-size:0}
-.prog-step.done .prog-node::before{content:'✓';font-size:.75rem}
-.prog-label{font-size:.58rem;color:var(--text-faint);font-weight:600;letter-spacing:.4px;text-transform:uppercase}
-.prog-step.active .prog-label{color:var(--indigo)}
-.prog-step.done .prog-label{color:var(--green)}
-.prog-line{width:56px;height:2px;background:var(--border);margin-bottom:20px;border-radius:2px;overflow:hidden}
-.prog-line::after{content:'';display:block;height:100%;width:0;background:linear-gradient(90deg,var(--indigo),var(--green));transition:width .5s ease;border-radius:2px}
-.prog-line.filled::after{width:100%}
-
-/* ── Cards ── */
-.card{background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-xl);padding:26px 28px;box-shadow:var(--shadow-md);animation:cardIn .35s ease both}
-@keyframes cardIn{from{opacity:0;transform:translateY(12px)}to{opacity:1;transform:translateY(0)}}
-.card-header{display:flex;align-items:center;justify-content:space-between;margin-bottom:20px;gap:12px}
-.card-header h2{font-size:1rem;font-weight:700;color:var(--text);letter-spacing:-.2px}
-.step-badge{font-family:var(--font-mono);font-size:.58rem;font-weight:600;letter-spacing:1.2px;text-transform:uppercase;color:var(--indigo);background:var(--indigo-lt);border:1px solid var(--indigo-mid);padding:3px 9px;border-radius:20px;white-space:nowrap}
-
-/* ── Info banner ── */
-.info-banner{display:flex;gap:10px;align-items:flex-start;background:var(--indigo-lt);border:1px solid var(--indigo-mid);border-radius:var(--radius-md);padding:11px 15px;margin-bottom:18px;font-size:.84rem;color:var(--indigo-dk);line-height:1.55}
-.info-icon{font-size:1rem;flex-shrink:0;margin-top:1px}
+#app { display:flex; min-height:100vh; }
+
+/* ── Sidebar ── */
+#sidebar {
+  width:var(--sidebar-w); flex-shrink:0;
+  background:var(--bg-2); border-right:1px solid var(--border);
+  display:flex; flex-direction:column;
+  position:fixed; top:0; left:0; bottom:0;
+  transition:width var(--transition), transform var(--transition);
+  z-index:100; overflow:hidden;
+}
+#sidebar.collapsed { width:56px; }
+#sidebar.collapsed .brand-info,
+#sidebar.collapsed .nav-label,
+#sidebar.collapsed .nav-badge,
+#sidebar.collapsed .api-status-row { opacity:0; pointer-events:none; width:0; overflow:hidden; }
+#sidebar.collapsed .brand-icon { margin:0 auto; }
+#sidebar.collapsed .nav-item { justify-content:center; padding:12px 0; }
+#sidebar.collapsed .sidebar-bottom { justify-content:center; flex-direction:column; gap:8px; }
+
+.sidebar-top { display:flex; align-items:center; justify-content:space-between; padding:18px 14px 14px; gap:10px; }
+.brand { display:flex; align-items:center; gap:10px; text-decoration:none; overflow:hidden; }
+.brand-icon { width:34px; height:34px; flex-shrink:0; background:linear-gradient(135deg,var(--accent),var(--violet));
+  border-radius:var(--r-md); display:grid; place-items:center; font-size:16px; box-shadow:0 2px 10px var(--accent-mid); }
+.brand-name { font-size:.95rem; font-weight:700; color:var(--text); white-space:nowrap; }
+.brand-ver { font-family:var(--font-mono); font-size:.58rem; color:var(--accent); background:var(--accent-lt);
+  border:1px solid var(--accent-mid); padding:1px 6px; border-radius:20px; white-space:nowrap; }
+.sidebar-toggle { background:none; border:1px solid var(--border); border-radius:var(--r-sm); color:var(--text-muted);
+  width:24px; height:24px; display:grid; place-items:center; font-size:12px; flex-shrink:0;
+  transition:all var(--transition); }
+.sidebar-toggle:hover { border-color:var(--accent-mid); color:var(--accent); }
+#sidebar.collapsed .sidebar-toggle { transform:rotate(180deg); }
+
+.sidebar-nav { flex:1; padding:8px 8px; display:flex; flex-direction:column; gap:2px; overflow:hidden; }
+.nav-item { display:flex; align-items:center; gap:10px; padding:9px 10px; border:none; background:transparent;
+  border-radius:var(--r-md); color:var(--text-muted); font-size:.85rem; font-weight:500;
+  width:100%; text-align:left; transition:all var(--transition); white-space:nowrap; overflow:hidden; }
+.nav-item:hover { background:var(--bg-3); color:var(--text); }
+.nav-item.active { background:var(--accent-lt); color:var(--accent); font-weight:600; }
+.nav-icon { font-size:1rem; flex-shrink:0; width:20px; text-align:center; }
+.nav-label { flex:1; overflow:hidden; text-overflow:ellipsis; }
+.nav-badge { font-family:var(--font-mono); font-size:.58rem; font-weight:700; background:var(--accent);
+  color:#fff; border-radius:10px; padding:1px 6px; min-width:18px; text-align:center; }
+
+.sidebar-bottom { display:flex; align-items:center; gap:8px; padding:12px 12px; border-top:1px solid var(--border); overflow:hidden; }
+.api-status-row { display:flex; gap:4px; flex:1; overflow:hidden; }
+.api-dot-sm { font-family:var(--font-mono); font-size:.58rem; font-weight:700; padding:2px 6px;
+  border-radius:4px; background:var(--bg-3); color:var(--text-faint); border:1px solid var(--border);
+  transition:all .3s; cursor:default; white-space:nowrap; }
+.api-dot-sm.active { background:var(--green-lt); color:var(--green); border-color:var(--green); }
+.theme-toggle,.sidebar-link { background:none; border:1px solid var(--border); border-radius:var(--r-sm);
+  color:var(--text-muted); width:28px; height:28px; display:grid; place-items:center; font-size:13px;
+  text-decoration:none; flex-shrink:0; transition:all var(--transition); }
+.theme-toggle:hover,.sidebar-link:hover { border-color:var(--accent-mid); color:var(--accent); background:var(--accent-lt); }
+
+/* ── Main content ── */
+#main-content { margin-left:var(--sidebar-w); flex:1; min-width:0; transition:margin-left var(--transition); }
+#sidebar.collapsed ~ #main-content { margin-left:56px; }
+
+.page { display:none; padding:28px 32px 80px; max-width:960px; }
+.page.active { display:block; }
+@media(max-width:768px){ .page { padding:16px 16px 60px; } }
+
+.page-header { display:flex; align-items:flex-start; justify-content:space-between; gap:16px; margin-bottom:24px; flex-wrap:wrap; }
+.page-title { font-size:1.4rem; font-weight:700; color:var(--text); letter-spacing:-.4px; }
+.page-subtitle { font-size:.82rem; color:var(--text-muted); margin-top:2px; }
+.page-header-actions { display:flex; align-items:center; gap:8px; flex-wrap:wrap; }
+
+/* ── Panels ── */
+.panel { background:var(--bg-2); border:1px solid var(--border); border-radius:var(--r-xl);
+  padding:22px 24px; margin-bottom:16px; animation:fadeUp .3s ease both; }
+.panel-header { display:flex; align-items:center; justify-content:space-between; margin-bottom:18px; gap:12px; }
+.panel-header h2 { font-size:.95rem; font-weight:700; color:var(--text); }
+.step-tag { font-family:var(--font-mono); font-size:.58rem; font-weight:600; letter-spacing:1px;
+  color:var(--accent); background:var(--accent-lt); border:1px solid var(--accent-mid);
+  padding:2px 8px; border-radius:20px; white-space:nowrap; }
+@keyframes fadeUp { from{opacity:0;transform:translateY(10px)} to{opacity:1;transform:translateY(0)} }
+
+/* ── API Panel ── */
+.api-panel { padding:0; overflow:hidden; }
+.api-panel-toggle { display:flex; align-items:center; gap:12px; padding:14px 20px; cursor:pointer;
+  user-select:none; font-size:.85rem; font-weight:600; color:var(--text-soft); }
+.api-panel-toggle:hover { background:var(--bg-3); }
+.api-panel-status { margin-left:auto; font-size:.75rem; font-family:var(--font-mono); color:var(--accent); }
+.chevron { font-size:.7rem; transition:transform var(--transition); }
+.chevron.open { transform:rotate(180deg); }
+.api-panel-body { padding:0 20px 18px; border-top:1px solid var(--border); display:none; }
+.api-panel-body.open { display:block; animation:fadeUp .2s ease both; }
+.api-grid { display:grid; grid-template-columns:1fr 1fr; gap:14px; margin-top:14px; }
+@media(max-width:580px){ .api-grid { grid-template-columns:1fr; } }
+
+/* ── Stepper ── */
+.stepper { display:flex; align-items:center; justify-content:center; margin-bottom:20px; padding:4px 0; }
+.step { display:flex; flex-direction:column; align-items:center; gap:4px; }
+.step-dot { width:28px; height:28px; border-radius:50%; border:2px solid var(--border);
+  display:grid; place-items:center; font-size:.68rem; font-weight:700; color:var(--text-muted);
+  background:var(--bg-2); transition:all .3s cubic-bezier(.34,1.56,.64,1); }
+.step.active .step-dot { border-color:var(--accent); background:var(--accent); color:#fff;
+  box-shadow:0 0 0 4px var(--accent-lt); transform:scale(1.1); }
+.step.done .step-dot { border-color:var(--green); background:var(--green); color:#fff; font-size:0; }
+.step.done .step-dot::before { content:'✓'; font-size:.75rem; }
+.step-label { font-size:.58rem; font-weight:600; letter-spacing:.4px; text-transform:uppercase; color:var(--text-faint); }
+.step.active .step-label { color:var(--accent); }
+.step.done .step-label { color:var(--green); }
+.step-line { width:48px; height:2px; background:var(--border); margin-bottom:18px; border-radius:2px;
+  position:relative; overflow:hidden; }
+.step-line::after { content:''; display:block; position:absolute; inset-y:0; left:0; width:0;
+  background:linear-gradient(90deg,var(--accent),var(--green)); transition:width .5s ease; border-radius:2px; }
+.step-line.filled::after { width:100%; }
 
 /* ── Form elements ── */
-.field{margin-bottom:16px}
-label{display:flex;align-items:center;gap:6px;font-size:.72rem;font-weight:600;letter-spacing:.4px;text-transform:uppercase;color:var(--text-soft);margin-bottom:6px}
-.lbl-dot{width:4px;height:4px;border-radius:50%;background:var(--indigo);flex-shrink:0}
-.lbl-opt{color:var(--text-faint);font-size:.64rem;margin-left:auto;text-transform:none;letter-spacing:0;font-weight:400}
-textarea,input[type="text"],input[type="password"],select{width:100%;background:var(--surface-2);border:1.5px solid var(--border);border-radius:var(--radius-md);color:var(--text);font-family:var(--font-body);font-size:.88rem;padding:10px 13px;outline:none;transition:border-color .2s,box-shadow .2s,background .2s;resize:vertical}
-textarea:focus,input:focus,select:focus{border-color:var(--border-focus);background:white;box-shadow:0 0 0 3px rgba(99,102,241,.09)}
-textarea::placeholder,input::placeholder{color:var(--text-faint);font-style:italic}
-textarea{min-height:90px;line-height:1.65}
-select{appearance:none;cursor:pointer;background-image:url("data:image/svg+xml,%3Csvg width='11' height='7' viewBox='0 0 11 7' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M1 1L5.5 6L10 1' stroke='%236366f1' stroke-width='1.5' stroke-linecap='round'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:right 13px center;padding-right:36px;resize:none}
-.field-note{font-size:.7rem;color:var(--text-muted);margin-top:4px;text-align:right}
-.settings-grid-2{display:grid;grid-template-columns:1fr 1fr;gap:14px}
-@media(max-width:580px){.settings-grid-2{grid-template-columns:1fr}}
-
-/* ── Advanced panel ── */
-.advanced-toggle-row{margin-bottom:10px}
-.btn-link{background:none;border:none;color:var(--indigo);font-size:.83rem;font-weight:600;cursor:pointer;padding:0;font-family:var(--font-body)}
-.btn-link:hover{text-decoration:underline}
-.advanced-panel{background:var(--surface-2);border:1px solid var(--border);border-radius:var(--radius-md);padding:16px;margin-bottom:16px;animation:cardIn .3s ease}
-.adv-grid{display:grid;grid-template-columns:1fr 1fr;gap:14px}
-@media(max-width:580px){.adv-grid{grid-template-columns:1fr}}
-
-/* ── Tooltip ── */
-.tooltip-wrap{position:relative;display:inline-flex;margin-left:4px}
-.tooltip-icon{width:14px;height:14px;border-radius:50%;background:var(--surface-3);border:1px solid var(--border);font-size:.65rem;display:grid;place-items:center;cursor:default;color:var(--text-muted);font-weight:700;font-style:normal}
-.tooltip-text{position:absolute;bottom:calc(100% + 6px);left:50%;transform:translateX(-50%);width:220px;background:#1e1e2e;color:#cdd6f4;font-size:.72rem;padding:8px 10px;border-radius:var(--radius-sm);font-weight:400;text-transform:none;letter-spacing:0;line-height:1.4;opacity:0;pointer-events:none;transition:opacity .2s;z-index:50;box-shadow:var(--shadow-lg)}
-.tooltip-wrap:hover .tooltip-text{opacity:1}
-
-/* ── Toggle switch ── */
-.enhance-toggle-row{margin-top:4px}
-.toggle-label{display:flex;align-items:center;gap:10px;cursor:pointer;font-size:.85rem;font-weight:500;color:var(--text-soft);text-transform:none;letter-spacing:0}
-.toggle-checkbox{display:none}
-.toggle-track{width:40px;height:22px;background:var(--border);border-radius:11px;position:relative;transition:background .25s;flex-shrink:0}
-.toggle-checkbox:checked+.toggle-track{background:var(--indigo)}
-.toggle-thumb{position:absolute;width:16px;height:16px;background:white;border-radius:50%;top:3px;left:3px;transition:left .25s;box-shadow:0 1px 3px rgba(0,0,0,.2)}
-.toggle-checkbox:checked+.toggle-track .toggle-thumb{left:21px}
+.field { margin-bottom:14px; }
+label { display:flex; align-items:center; gap:6px; font-size:.72rem; font-weight:600;
+  letter-spacing:.3px; text-transform:uppercase; color:var(--text-muted); margin-bottom:6px; }
+.required { color:var(--red); font-size:.7rem; }
+.lbl-opt { color:var(--text-faint); font-size:.64rem; text-transform:none; letter-spacing:0; font-weight:400; margin-left:auto; }
+input[type="text"], input[type="password"], textarea, select {
+  width:100%; padding:9px 12px; background:var(--bg-3); border:1.5px solid var(--border);
+  border-radius:var(--r-md); color:var(--text); font-family:var(--font-ui); font-size:.86rem;
+  outline:none; transition:border-color var(--transition), box-shadow var(--transition), background var(--transition);
+  resize:vertical;
+}
+input:focus, textarea:focus, select:focus {
+  border-color:var(--border-focus); background:var(--bg-2);
+  box-shadow:0 0 0 3px var(--accent-lt);
+}
+input::placeholder, textarea::placeholder { color:var(--text-faint); font-style:italic; }
+textarea { min-height:80px; line-height:1.65; }
+select { appearance:none; cursor:pointer; resize:none;
+  background-image:url("data:image/svg+xml,%3Csvg width='10' height='6' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M1 1l4 4 4-4' stroke='%237c6dfa' stroke-width='1.5' stroke-linecap='round'/%3E%3C/svg%3E");
+  background-repeat:no-repeat; background-position:right 12px center; padding-right:32px; }
+.char-counter { font-family:var(--font-mono); font-size:.68rem; color:var(--text-faint); text-align:right; margin-top:3px; }
+.char-counter.warn { color:var(--amber); }
+.char-counter.over  { color:var(--red); }
+.field-note { font-size:.72rem; color:var(--text-muted); margin-top:4px; display:flex; align-items:center; gap:5px; }
+.status-dot { width:6px; height:6px; border-radius:50%; background:var(--text-faint); flex-shrink:0; transition:all .3s; }
+.status-dot.ok  { background:var(--green); box-shadow:0 0 6px var(--green); }
+.status-dot.err { background:var(--red);   box-shadow:0 0 6px var(--red); }
+.input-with-action { display:flex; gap:4px; }
+.input-with-action input { flex:1; }
+.two-col { display:grid; grid-template-columns:1fr 1fr; gap:12px; }
+@media(max-width:540px){ .two-col { grid-template-columns:1fr; } }
+
+/* ── Advanced block ── */
+.advanced-block { background:var(--bg-3); border:1px solid var(--border); border-radius:var(--r-lg); padding:14px 16px; margin-bottom:14px; }
+.advanced-block > summary { font-size:.83rem; font-weight:600; color:var(--text-muted); cursor:pointer; user-select:none; list-style:none; }
+.advanced-block > summary:hover { color:var(--accent); }
+.advanced-block > summary::-webkit-details-marker { display:none; }
+.adv-grid { display:grid; grid-template-columns:1fr 1fr; gap:12px; margin-top:14px; }
+@media(max-width:540px){ .adv-grid { grid-template-columns:1fr; } }
+.tip { width:14px; height:14px; border-radius:50%; background:var(--bg); border:1px solid var(--border);
+  font-size:.62rem; display:inline-grid; place-items:center; cursor:default; color:var(--text-muted); margin-left:4px; }
+.info-note { background:var(--accent-lt); border:1px solid var(--accent-mid); border-radius:var(--r-md);
+  padding:10px 14px; font-size:.82rem; color:var(--text-soft); margin-bottom:16px; line-height:1.5; }
+
+/* ── Toggle ── */
+.toggle-row { display:flex; flex-wrap:wrap; gap:16px; margin-bottom:14px; }
+.toggle-label { display:flex; align-items:center; gap:10px; cursor:pointer; font-size:.83rem;
+  font-weight:500; color:var(--text-soft); text-transform:none; letter-spacing:0; }
+.toggle-cb { display:none; }
+.toggle-track { width:38px; height:21px; background:var(--bg-3); border:1.5px solid var(--border);
+  border-radius:12px; position:relative; transition:all .25s; flex-shrink:0; }
+.toggle-cb:checked + .toggle-track { background:var(--accent); border-color:var(--accent); }
+.toggle-thumb { position:absolute; width:15px; height:15px; background:var(--text-muted);
+  border-radius:50%; top:2px; left:2px; transition:left .25s; }
+.toggle-cb:checked + .toggle-track .toggle-thumb { left:19px; background:#fff; }
 
 /* ── Buttons ── */
-button{cursor:pointer;font-family:var(--font-body)}
-.btn-primary{display:inline-flex;align-items:center;justify-content:center;gap:7px;border:none;border-radius:var(--radius-md);font-size:.88rem;font-weight:700;padding:11px 24px;background:linear-gradient(135deg,var(--indigo) 0%,var(--violet) 100%);color:white;box-shadow:var(--shadow-btn);transition:transform .2s,box-shadow .2s;position:relative;overflow:hidden}
-.btn-primary:hover{transform:translateY(-1px);box-shadow:0 6px 20px rgba(99,102,241,.40)}
-.btn-primary:active{transform:translateY(0)}
-.btn-primary:disabled{opacity:.5;cursor:not-allowed;transform:none}
-.btn-secondary{display:inline-flex;align-items:center;justify-content:center;gap:6px;border:1.5px solid var(--border);border-radius:var(--radius-md);background:var(--surface);color:var(--text-soft);font-size:.85rem;font-weight:500;padding:10px 18px;transition:all .2s}
-.btn-secondary:hover{border-color:var(--indigo-mid);color:var(--indigo);background:var(--indigo-lt)}
-.btn-secondary:active{transform:scale(.98)}
-.btn-danger{color:var(--red)}
-.btn-danger:hover{border-color:var(--red);color:var(--red);background:var(--red-lt)}
-.btn-sm{font-size:.76rem;padding:5px 12px;border-radius:var(--radius-sm)}
-.action-row{display:flex;flex-wrap:wrap;gap:9px;margin-top:18px;align-items:center}
-.spinner{display:inline-block;width:13px;height:13px;border:2px solid rgba(255,255,255,.3);border-top-color:white;border-radius:50%;animation:spin .7s linear infinite;vertical-align:middle}
-@keyframes spin{to{transform:rotate(360deg)}}
+.btn-primary { display:inline-flex; align-items:center; gap:6px; border:none; border-radius:var(--r-md);
+  font-size:.86rem; font-weight:700; padding:10px 20px;
+  background:linear-gradient(135deg,var(--accent),var(--violet)); color:#fff;
+  box-shadow:0 2px 12px var(--accent-mid); transition:transform .2s, box-shadow .2s; }
+.btn-primary:hover { transform:translateY(-1px); box-shadow:0 4px 20px var(--accent-mid); }
+.btn-primary:active { transform:none; }
+.btn-primary:disabled { opacity:.5; cursor:not-allowed; transform:none; }
+.btn-secondary { display:inline-flex; align-items:center; gap:6px; border:1.5px solid var(--border);
+  border-radius:var(--r-md); background:var(--bg-2); color:var(--text-soft);
+  font-size:.84rem; font-weight:500; padding:9px 16px; transition:all var(--transition); }
+.btn-secondary:hover { border-color:var(--accent-mid); color:var(--accent); background:var(--accent-lt); }
+.btn-ghost { display:inline-flex; align-items:center; gap:6px; border:none; background:transparent;
+  color:var(--text-muted); font-size:.82rem; padding:8px 14px; border-radius:var(--r-md);
+  transition:all var(--transition); }
+.btn-ghost:hover { background:var(--bg-3); color:var(--text); }
+.btn-danger { border-color:transparent; color:var(--red); }
+.btn-danger:hover { border-color:var(--red); background:var(--red-lt); }
+.btn-sm { font-size:.76rem; padding:6px 12px; }
+.icon-btn { width:32px; height:32px; border:1.5px solid var(--border); border-radius:var(--r-sm);
+  background:var(--bg-3); color:var(--text-muted); display:grid; place-items:center; font-size:13px;
+  flex-shrink:0; transition:all var(--transition); }
+.icon-btn:hover { border-color:var(--accent-mid); color:var(--accent); background:var(--accent-lt); }
+.icon-btn:disabled { opacity:.4; cursor:not-allowed; }
+.action-row { display:flex; flex-wrap:wrap; gap:8px; margin-top:18px; align-items:center; }
+kbd { font-family:var(--font-mono); font-size:.64rem; background:var(--bg-3); border:1px solid var(--border);
+  border-radius:4px; padding:1px 5px; color:var(--text-muted); }
+.spinner { display:inline-block; width:12px; height:12px; border:2px solid rgba(255,255,255,.3);
+  border-top-color:#fff; border-radius:50%; animation:spin .7s linear infinite; }
+@keyframes spin { to { transform:rotate(360deg); } }
 
 /* ── Manifest grid ── */
-.manifest-grid{display:grid;grid-template-columns:1fr 1fr;gap:13px;margin-bottom:18px}
-.manifest-field label{font-size:.66rem;color:var(--text-muted);text-transform:uppercase}
-.manifest-field textarea{min-height:66px;font-size:.83rem}
-.manifest-field.full{grid-column:1/-1}
-@media(max-width:580px){.manifest-grid{grid-template-columns:1fr}.manifest-field.full{grid-column:auto}}
-
-/* ── Explanation panel ── */
-.explanation-panel{background:linear-gradient(135deg,var(--indigo-lt),#f5f0ff);border:1px solid var(--indigo-mid);border-radius:var(--radius-md);padding:16px 18px;margin-top:16px;animation:cardIn .35s ease}
-.explanation-header{display:flex;align-items:center;gap:8px;margin-bottom:10px}
-.explanation-icon{font-size:1.2rem}
-.explanation-header strong{font-size:.88rem;color:var(--indigo-dk);font-weight:700}
-.explanation-body{font-size:.84rem;color:var(--text-soft);line-height:1.65;white-space:pre-wrap;margin-bottom:12px}
-.key-decisions{display:flex;flex-direction:column;gap:5px}
-.decision-chip{display:inline-flex;align-items:center;gap:6px;background:white;border:1px solid var(--indigo-mid);border-radius:20px;padding:4px 12px;font-size:.75rem;color:var(--indigo-dk);font-weight:500}
-.decision-chip::before{content:'•';color:var(--indigo)}
-
-/* ── Tabs (inner) ── */
-.tab-bar{display:flex;gap:3px;background:var(--surface-2);border:1px solid var(--border);border-radius:var(--radius-md);padding:3px;width:fit-content;margin-bottom:14px}
-.tab{border:none;background:transparent;border-radius:var(--radius-sm);padding:6px 16px;font-size:.8rem;font-weight:500;color:var(--text-muted);cursor:pointer;transition:all .2s}
-.tab.active{background:white;color:var(--indigo);box-shadow:var(--shadow-sm);font-weight:700}
-.tab-panel{display:block}
-.tab-panel.hidden{display:none}
-
-/* ── Code/Pre ── */
-pre{background:#1e1e2e;border-radius:var(--radius-md);padding:14px 16px;overflow-x:auto;font-family:var(--font-mono);font-size:.8rem;line-height:1.7;color:#cdd6f4;white-space:pre-wrap;word-break:break-word;border:1px solid rgba(205,214,244,.06)}
-details{margin-top:10px}
-summary{font-size:.82rem;font-weight:600;color:var(--text-muted);cursor:pointer;padding:9px 0;user-select:none;display:flex;align-items:center;gap:6px;list-style:none}
-summary:hover{color:var(--indigo)}
-summary::before{content:'▶';font-size:.68rem;transition:transform .2s}
-details[open] summary::before{transform:rotate(90deg)}
-.btn-copy{display:inline-flex;align-items:center;gap:5px;border:1px solid var(--border);border-radius:var(--radius-sm);background:var(--surface);color:var(--text-muted);font-family:var(--font-mono);font-size:.72rem;padding:6px 12px;margin-top:8px;cursor:pointer;transition:all .2s}
-.btn-copy:hover{color:var(--indigo);border-color:var(--indigo-mid);background:var(--indigo-lt)}
-.btn-copy.copied{color:var(--green);border-color:var(--green);background:var(--green-lt)}
-.muted{font-size:.86rem;color:var(--text-muted);margin-bottom:16px;line-height:1.6}
-.divider{height:1px;background:var(--border);margin:18px 0}
-
-/* ── Settings layout (two-column) ── */
-.settings-layout{display:grid;grid-template-columns:1fr 380px;gap:20px;max-width:940px;margin:0 auto;padding:24px 20px 80px;align-items:start}
-@media(max-width:780px){.settings-layout{grid-template-columns:1fr;padding:16px 14px 60px}}
-.settings-form-col{}
-.settings-list-col{position:sticky;top:120px}
-.settings-list-header{display:flex;align-items:center;justify-content:space-between;margin-bottom:12px;gap:10px;flex-wrap:wrap}
-.settings-list-header h3{font-size:.95rem;font-weight:700;color:var(--text);display:flex;align-items:center;gap:8px}
-.count-badge{font-size:.62rem;font-weight:700;background:var(--indigo-lt);color:var(--indigo);border:1px solid var(--indigo-mid);border-radius:10px;padding:1px 7px}
-.settings-list-actions{display:flex;gap:8px;flex-wrap:wrap}
-.search-input{padding:7px 12px;border:1.5px solid var(--border);border-radius:var(--radius-md);font-size:.82rem;background:var(--surface);color:var(--text);outline:none;transition:border-color .2s;width:150px}
-.search-input:focus{border-color:var(--border-focus)}
-.filter-select{padding:7px 30px 7px 10px;border:1.5px solid var(--border);border-radius:var(--radius-md);font-size:.78rem;background:var(--surface);color:var(--text-muted);appearance:none;background-image:url("data:image/svg+xml,%3Csvg width='10' height='6' viewBox='0 0 10 6' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M1 1L5 5L9 1' stroke='%236b7280' stroke-width='1.5' stroke-linecap='round'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:right 9px center;cursor:pointer;outline:none;resize:none}
-.settings-list{display:flex;flex-direction:column;gap:10px;max-height:calc(100vh - 280px);overflow-y:auto;padding-right:2px}
+.manifest-grid { display:grid; grid-template-columns:1fr 1fr; gap:12px; margin-bottom:16px; }
+.manifest-field label { font-size:.65rem; }
+.manifest-field textarea { min-height:64px; font-size:.82rem; }
+.manifest-field.full { grid-column:1/-1; }
+@media(max-width:540px){ .manifest-grid { grid-template-columns:1fr; } .manifest-field.full { grid-column:auto; } }
+
+/* ── Code block ── */
+.code-block { position:relative; }
+.copy-btn { position:absolute; top:8px; right:8px; background:var(--bg-3); border:1px solid var(--border);
+  border-radius:var(--r-sm); color:var(--text-muted); font-family:var(--font-mono);
+  font-size:.68rem; padding:4px 10px; cursor:pointer; transition:all var(--transition); z-index:1; }
+.copy-btn:hover { border-color:var(--accent-mid); color:var(--accent); }
+.copy-btn.copied { border-color:var(--green); color:var(--green); background:var(--green-lt); }
+pre { background:var(--bg-3); border:1px solid var(--border); border-radius:var(--r-lg); padding:14px 16px;
+  font-family:var(--font-mono); font-size:.78rem; line-height:1.8; color:var(--text-soft);
+  white-space:pre-wrap; word-break:break-word; overflow-x:auto; }
+details { margin-top:10px; }
+summary { font-size:.8rem; font-weight:600; color:var(--text-muted); cursor:pointer; padding:8px 0;
+  user-select:none; list-style:none; display:flex; align-items:center; gap:6px; }
+summary:hover { color:var(--accent); }
+summary::-webkit-details-marker { display:none; }
+summary::before { content:'▶'; font-size:.65rem; transition:transform .2s; }
+details[open] summary::before { transform:rotate(90deg); }
+
+/* ── Inner tabs ── */
+.inner-tabs { display:flex; gap:2px; background:var(--bg-3); border:1px solid var(--border);
+  border-radius:var(--r-md); padding:3px; width:fit-content; margin-bottom:12px; }
+.inner-tab { border:none; background:transparent; border-radius:var(--r-sm); padding:6px 14px;
+  font-size:.78rem; font-weight:500; color:var(--text-muted); cursor:pointer; transition:all var(--transition); }
+.inner-tab.active { background:var(--bg-2); color:var(--accent); font-weight:700; box-shadow:var(--shadow-sm); }
+.inner-panel { display:block; }
+.inner-panel.hidden { display:none; }
+
+/* ── Explanation ── */
+.explanation-panel { background:linear-gradient(135deg,var(--accent-lt),rgba(167,139,250,.08));
+  border:1px solid var(--accent-mid); border-radius:var(--r-lg); padding:16px 18px; margin-top:14px; animation:fadeUp .3s ease; }
+.explanation-header { font-size:.85rem; font-weight:700; color:var(--accent); margin-bottom:10px; }
+.explanation-body { font-size:.82rem; color:var(--text-soft); line-height:1.7; white-space:pre-wrap; margin-bottom:12px; }
+.decision-chips { display:flex; flex-wrap:wrap; gap:6px; }
+.decision-chip { display:inline-flex; align-items:center; gap:5px; background:var(--bg-2); border:1px solid var(--border);
+  border-radius:20px; padding:3px 10px; font-size:.72rem; color:var(--text-muted); }
+.decision-chip::before { content:'·'; color:var(--accent); font-size:1rem; line-height:1; }
+
+/* ── Settings layout ── */
+.settings-layout { display:grid; grid-template-columns:1fr 360px; gap:16px; align-items:start; }
+@media(max-width:800px){ .settings-layout { grid-template-columns:1fr; } }
+.settings-list-col { position:sticky; top:24px; }
+.list-header { display:flex; align-items:center; justify-content:space-between; margin-bottom:12px; gap:8px;
+  flex-wrap:wrap; font-size:.85rem; font-weight:700; color:var(--text); }
+.list-controls { display:flex; gap:6px; align-items:center; flex-wrap:wrap; }
+.count-badge { font-family:var(--font-mono); font-size:.62rem; font-weight:700; background:var(--accent-lt);
+  color:var(--accent); border:1px solid var(--accent-mid); border-radius:10px; padding:1px 7px; margin-left:6px; }
+.search-input { padding:7px 11px; border:1.5px solid var(--border); border-radius:var(--r-md);
+  font-size:.8rem; background:var(--bg-3); color:var(--text); outline:none; transition:border-color var(--transition); }
+.search-input:focus { border-color:var(--border-focus); }
+.filter-select { padding:6px 26px 6px 9px; border:1.5px solid var(--border); border-radius:var(--r-md);
+  font-size:.76rem; background:var(--bg-3); color:var(--text-soft); outline:none; cursor:pointer;
+  appearance:none; background-image:url("data:image/svg+xml,%3Csvg width='10' height='6' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M1 1l4 4 4-4' stroke='%237c7d96' stroke-width='1.5' stroke-linecap='round'/%3E%3C/svg%3E");
+  background-repeat:no-repeat; background-position:right 8px center; resize:none; }
+.settings-list { display:flex; flex-direction:column; gap:8px; max-height:calc(100vh - 200px); overflow-y:auto; }
 
 /* ── Setting card ── */
-.setting-card{background:var(--surface);border:1.5px solid var(--border);border-radius:var(--radius-lg);padding:14px 16px;cursor:pointer;transition:all .2s;position:relative}
-.setting-card:hover{border-color:var(--indigo-mid);box-shadow:var(--shadow-md);transform:translateY(-1px)}
-.setting-card.active-edit{border-color:var(--indigo);box-shadow:0 0 0 3px rgba(99,102,241,.12)}
-.setting-card-title{font-size:.88rem;font-weight:700;color:var(--text);margin-bottom:4px;display:flex;align-items:center;gap:7px}
-.setting-card-desc{font-size:.76rem;color:var(--text-muted);margin-bottom:9px;line-height:1.5;overflow:hidden;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical}
-.setting-card-meta{display:flex;align-items:center;gap:6px;flex-wrap:wrap}
-.tag-chip{font-size:.63rem;font-weight:600;padding:2px 7px;border-radius:10px;background:var(--indigo-lt);color:var(--indigo-dk);border:1px solid var(--indigo-mid)}
-.tag-chip.style{background:var(--teal-lt);color:var(--teal);border-color:#99f6e4}
-.use-count{font-size:.68rem;color:var(--text-faint);margin-left:auto;font-family:var(--font-mono)}
-.setting-card-actions{position:absolute;top:10px;right:10px;display:flex;gap:4px;opacity:0;transition:opacity .2s}
-.setting-card:hover .setting-card-actions{opacity:1}
-.settings-empty{text-align:center;padding:40px 20px;color:var(--text-muted)}
-.empty-icon{font-size:2.5rem;margin-bottom:10px;opacity:.4}
-.settings-empty p{font-size:.85rem}
-
-/* ── History Table ── */
-.table-wrap{overflow-x:auto;border-radius:var(--radius-md);border:1px solid var(--border)}
-table{width:100%;border-collapse:collapse;font-size:.83rem}
-thead{background:var(--surface-2)}
-th{padding:10px 13px;text-align:left;font-size:.68rem;font-weight:700;text-transform:uppercase;letter-spacing:.5px;color:var(--text-muted);border-bottom:1px solid var(--border);white-space:nowrap}
-td{padding:10px 13px;color:var(--text-soft);border-bottom:1px solid var(--surface-2)}
-tr:last-child td{border-bottom:none}
-tr:hover td{background:var(--surface-2)}
-.empty-msg{color:var(--text-faint);font-style:italic;text-align:center;padding:24px 13px!important}
-.badge{display:inline-block;padding:2px 8px;border-radius:20px;font-size:.68rem;font-weight:700;text-transform:uppercase;letter-spacing:.3px}
-.badge-pending{background:var(--amber-lt);color:#92400e}
-.badge-approved{background:var(--green-lt);color:#065f46}
-.badge-exported{background:var(--indigo-lt);color:var(--indigo-dk)}
+.setting-card { background:var(--bg-2); border:1.5px solid var(--border); border-radius:var(--r-lg);
+  padding:12px 14px; cursor:pointer; transition:all var(--transition); position:relative; }
+.setting-card:hover { border-color:var(--accent-mid); box-shadow:var(--shadow-sm); transform:translateY(-1px); }
+.setting-card.editing { border-color:var(--accent); box-shadow:0 0 0 3px var(--accent-lt); }
+.setting-card.favorite .s-star { color:var(--amber); }
+.setting-card-top { display:flex; align-items:center; gap:8px; margin-bottom:4px; }
+.setting-card-title { font-size:.86rem; font-weight:700; color:var(--text); flex:1; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.s-star { font-size:.85rem; color:var(--text-faint); }
+.setting-card-desc { font-size:.74rem; color:var(--text-muted); margin-bottom:8px; overflow:hidden;
+  display:-webkit-box; -webkit-line-clamp:2; -webkit-box-orient:vertical; line-height:1.4; }
+.setting-card-meta { display:flex; align-items:center; gap:5px; flex-wrap:wrap; }
+.tag-chip { font-size:.62rem; font-weight:600; padding:2px 7px; border-radius:10px;
+  background:var(--accent-lt); color:var(--accent); border:1px solid var(--accent-mid); }
+.tag-chip.style-tag { background:rgba(45,212,191,.1); color:var(--teal); border-color:rgba(45,212,191,.3); }
+.use-count { font-family:var(--font-mono); font-size:.62rem; color:var(--text-faint); margin-left:auto; }
+.setting-card-actions { position:absolute; top:8px; right:8px; display:flex; gap:3px; opacity:0; transition:opacity var(--transition); }
+.setting-card:hover .setting-card-actions { opacity:1; }
+.tag-suggestions { display:flex; flex-wrap:wrap; gap:4px; margin-top:5px; }
+.tag-sug { font-size:.65rem; padding:2px 8px; border-radius:10px; border:1px dashed var(--border);
+  color:var(--text-muted); cursor:pointer; transition:all var(--transition); background:var(--bg-3); }
+.tag-sug:hover { border-color:var(--accent-mid); color:var(--accent); background:var(--accent-lt); }
+
+/* ── History table ── */
+.table-wrap { overflow-x:auto; border-radius:var(--r-lg); border:1px solid var(--border); }
+table { width:100%; border-collapse:collapse; font-size:.81rem; }
+thead { background:var(--bg-3); }
+th { padding:10px 12px; text-align:left; font-size:.65rem; font-weight:700; text-transform:uppercase;
+  letter-spacing:.5px; color:var(--text-muted); border-bottom:1px solid var(--border); white-space:nowrap; }
+td { padding:10px 12px; color:var(--text-soft); border-bottom:1px solid var(--border); }
+tr:last-child td { border-bottom:none; }
+tr:hover td { background:var(--bg-3); }
+.empty-msg { color:var(--text-faint); font-style:italic; text-align:center; padding:24px 12px !important; }
+.badge { display:inline-block; padding:2px 8px; border-radius:20px; font-family:var(--font-mono);
+  font-size:.65rem; font-weight:700; text-transform:uppercase; letter-spacing:.3px; }
+.badge-pending  { background:var(--amber-lt); color:var(--amber); }
+.badge-approved { background:var(--green-lt); color:var(--green); }
+.badge-exported { background:var(--accent-lt); color:var(--accent); }
+.badge-archived { background:var(--bg-3); color:var(--text-faint); }
+.fav-star { color:var(--text-faint); cursor:pointer; font-size:.9rem; transition:all var(--transition); }
+.fav-star.active { color:var(--amber); }
+
+/* ── Stats ── */
+.stats-grid { display:grid; grid-template-columns:repeat(4,1fr); gap:14px; margin-bottom:16px; }
+@media(max-width:720px){ .stats-grid { grid-template-columns:repeat(2,1fr); } }
+@media(max-width:400px){ .stats-grid { grid-template-columns:1fr; } }
+.stat-card { background:var(--bg-2); border:1px solid var(--border); border-radius:var(--r-xl);
+  padding:20px; display:flex; flex-direction:column; gap:6px; transition:border-color var(--transition); }
+.stat-card:hover { border-color:var(--accent-mid); }
+.stat-value { font-size:2rem; font-weight:700; color:var(--text); font-family:var(--font-mono); line-height:1; }
+.stat-label { font-size:.72rem; color:var(--text-muted); font-weight:600; text-transform:uppercase; letter-spacing:.3px; }
+.stat-sub { font-size:.72rem; color:var(--text-faint); }
+.stat-card.highlight { border-color:var(--accent-mid); background:var(--accent-lt); }
+.stat-card.highlight .stat-value { color:var(--accent); }
+.stat-card.skeleton { animation:pulse 1.5s ease infinite; }
+@keyframes pulse { 0%,100%{opacity:.4} 50%{opacity:.7} }
+.stats-row { display:grid; grid-template-columns:1fr 1fr; gap:14px; margin-bottom:16px; }
+@media(max-width:600px){ .stats-row { grid-template-columns:1fr; } }
+.bar-chart { display:flex; flex-direction:column; gap:8px; padding-top:4px; }
+.bar-row { display:flex; align-items:center; gap:10px; }
+.bar-row-label { font-size:.76rem; color:var(--text-soft); width:130px; flex-shrink:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.bar-track { flex:1; height:6px; background:var(--bg-3); border-radius:3px; overflow:hidden; }
+.bar-fill { height:100%; background:linear-gradient(90deg,var(--accent),var(--violet)); border-radius:3px; transition:width 1s ease; }
+.bar-count { font-family:var(--font-mono); font-size:.68rem; color:var(--text-muted); width:24px; text-align:right; }
+.status-breakdown { display:flex; flex-wrap:wrap; gap:10px; padding-top:4px; }
+.status-item { display:flex; align-items:center; gap:8px; background:var(--bg-3); border:1px solid var(--border);
+  border-radius:var(--r-md); padding:10px 14px; flex:1; min-width:120px; }
+.status-item-count { font-size:1.4rem; font-weight:700; font-family:var(--font-mono); line-height:1; }
+.status-item-label { font-size:.7rem; color:var(--text-muted); font-weight:600; text-transform:uppercase; }
 
 /* ── Modal ── */
-.modal-overlay{position:fixed;inset:0;background:rgba(0,0,0,.45);backdrop-filter:blur(4px);z-index:500;display:flex;align-items:center;justify-content:center;padding:20px}
-.modal-overlay.hidden{display:none!important}
-.modal-box{background:var(--surface);border-radius:var(--radius-xl);padding:0;width:100%;max-width:520px;max-height:80vh;display:flex;flex-direction:column;box-shadow:var(--shadow-lg);overflow:hidden;animation:cardIn .25s ease}
-.modal-header{display:flex;align-items:center;justify-content:space-between;padding:18px 22px;border-bottom:1px solid var(--border)}
-.modal-header h3{font-size:.95rem;font-weight:700}
-.modal-close{background:none;border:none;cursor:pointer;color:var(--text-muted);font-size:1rem;padding:4px;transition:color .2s;border-radius:6px}
-.modal-close:hover{color:var(--text);background:var(--surface-2)}
-.modal-body{padding:16px 22px;overflow-y:auto;flex:1}
-.modal-search{width:100%;padding:10px 13px;border:1.5px solid var(--border);border-radius:var(--radius-md);font-size:.87rem;margin-bottom:14px;outline:none;background:var(--surface-2);color:var(--text)}
-.modal-search:focus{border-color:var(--border-focus)}
-.modal-list{display:flex;flex-direction:column;gap:8px}
-.modal-item{padding:12px 14px;border:1.5px solid var(--border);border-radius:var(--radius-md);cursor:pointer;transition:all .2s}
-.modal-item:hover{border-color:var(--indigo);background:var(--indigo-lt)}
-.modal-item-title{font-size:.88rem;font-weight:600;color:var(--text);margin-bottom:3px}
-.modal-item-desc{font-size:.75rem;color:var(--text-muted)}
-.modal-empty{text-align:center;padding:30px;color:var(--text-faint);font-style:italic}
+.modal-overlay { position:fixed; inset:0; background:rgba(0,0,0,.6); backdrop-filter:blur(4px);
+  z-index:500; display:flex; align-items:center; justify-content:center; padding:20px; }
+.modal-overlay.hidden { display:none !important; }
+.modal-box { background:var(--bg-2); border:1px solid var(--border); border-radius:var(--r-xl);
+  width:100%; max-width:540px; max-height:80vh; display:flex; flex-direction:column;
+  box-shadow:var(--shadow); animation:fadeUp .25s ease; overflow:hidden; }
+.modal-header { display:flex; align-items:center; justify-content:space-between;
+  padding:16px 20px; border-bottom:1px solid var(--border); }
+.modal-header h3 { font-size:.9rem; font-weight:700; }
+.modal-body { padding:16px 20px; overflow-y:auto; flex:1; }
+.modal-list { display:flex; flex-direction:column; gap:8px; }
+.modal-item { padding:12px 14px; border:1.5px solid var(--border); border-radius:var(--r-md); cursor:pointer; transition:all var(--transition); }
+.modal-item:hover { border-color:var(--accent); background:var(--accent-lt); }
+.modal-item-title { font-size:.86rem; font-weight:600; color:var(--text); margin-bottom:2px; }
+.modal-item-desc { font-size:.74rem; color:var(--text-muted); }
+.modal-empty { text-align:center; padding:24px; color:var(--text-faint); font-style:italic; }
+.shortcuts-table { width:100%; border-collapse:collapse; }
+.shortcuts-table tr { border-bottom:1px solid var(--border); }
+.shortcuts-table tr:last-child { border-bottom:none; }
+.shortcuts-table td { padding:10px 8px; font-size:.82rem; color:var(--text-soft); }
+.shortcuts-table td:first-child { width:160px; }
 
 /* ── Toast ── */
-#toast-container{position:fixed;bottom:24px;right:24px;display:flex;flex-direction:column;gap:9px;z-index:9999;pointer-events:none}
-.toast{display:flex;align-items:center;gap:10px;background:white;border:1px solid var(--border);border-radius:var(--radius-md);padding:11px 16px;box-shadow:var(--shadow-lg);font-size:.84rem;color:var(--text);pointer-events:all;animation:toastIn .3s cubic-bezier(.34,1.56,.64,1) both;min-width:250px;max-width:360px}
-.toast.leaving{animation:toastOut .3s ease forwards}
-@keyframes toastIn{from{opacity:0;transform:translateX(16px)}to{opacity:1;transform:translateX(0)}}
-@keyframes toastOut{from{opacity:1;transform:translateX(0)}to{opacity:0;transform:translateX(16px)}}
-.toast.success{border-left:4px solid var(--green)}
-.toast.error{border-left:4px solid var(--red)}
-.toast.warn{border-left:4px solid var(--amber)}
-.toast.info{border-left:4px solid var(--indigo)}
-.toast-icon{font-size:1rem;flex-shrink:0}
-
-/* ── Footer ── */
-footer{border-top:1px solid var(--border);background:var(--surface);padding:13px 20px}
-.footer-inner{max-width:940px;margin:0 auto;display:flex;align-items:center;justify-content:space-between;gap:16px;font-size:.76rem;color:var(--text-faint)}
-.footer-links{display:flex;gap:14px}
-.footer-links a{color:var(--text-muted);text-decoration:none;transition:color .2s}
-.footer-links a:hover{color:var(--indigo)}
-
-/* ── Utils ── */
-.hidden{display:none!important}
-.fade-in{animation:cardIn .35s ease both}
-@media(max-width:600px){main{padding:16px 14px 60px}.card{padding:18px 16px}.prog-line{width:28px}.tabs-inner{overflow-x:auto;gap:0;white-space:nowrap}.main-tab{padding:10px 14px;font-size:.78rem}}
+#toast-container { position:fixed; bottom:24px; right:24px; display:flex; flex-direction:column; gap:8px; z-index:9999; pointer-events:none; }
+.toast { display:flex; align-items:center; gap:10px; background:var(--bg-2); border:1px solid var(--border);
+  border-radius:var(--r-md); padding:10px 16px; box-shadow:var(--shadow); font-size:.82rem; color:var(--text);
+  pointer-events:all; animation:slideIn .3s cubic-bezier(.34,1.56,.64,1) both; min-width:240px; max-width:360px; }
+.toast.leaving { animation:slideOut .3s ease forwards; }
+.toast.success { border-left:3px solid var(--green); }
+.toast.error   { border-left:3px solid var(--red); }
+.toast.warn    { border-left:3px solid var(--amber); }
+.toast.info    { border-left:3px solid var(--accent); }
+.toast-icon { font-size:.95rem; flex-shrink:0; }
+@keyframes slideIn { from{opacity:0;transform:translateX(20px)} to{opacity:1;transform:translateX(0)} }
+@keyframes slideOut { from{opacity:1;transform:translateX(0)} to{opacity:0;transform:translateX(20px)} }
+
+/* ── Misc ── */
+.muted { font-size:.84rem; color:var(--text-muted); margin-bottom:14px; line-height:1.6; }
+.divider { height:1px; background:var(--border); margin:16px 0; }
+.empty-state { text-align:center; padding:40px 20px; color:var(--text-muted); }
+.empty-icon { font-size:2.5rem; margin-bottom:10px; opacity:.4; }
+.empty-state p { font-size:.84rem; }
+.hidden { display:none !important; }
+
+/* ── Mobile responsive ── */
+@media(max-width:600px){
+  #sidebar { transform:translateX(-100%); }
+  #sidebar.mobile-open { transform:translateX(0); }
+  #main-content { margin-left:0 !important; }
+  .stepper .step-line { width:24px; }
+}

requirements.txt

@@ -0,0 +1,19 @@
+# PromptForge v4.0 — Python dependencies
+# Install: pip install -r requirements.txt
+
+# ── Core framework ────────────────────────────────────────────────────
+fastapi>=0.111.0,<0.120.0
+uvicorn[standard]>=0.29.0,<0.35.0
+pydantic>=2.7.0,<3.0.0
+python-multipart>=0.0.9
+
+# ── HTTP client (AI providers) ────────────────────────────────────────
+httpx>=0.27.0,<0.30.0
+
+# ── Dev / testing ─────────────────────────────────────────────────────
+pytest>=8.2.0
+pytest-asyncio>=0.23.0
+httpx>=0.27.0       # also needed by TestClient
+
+# ── Optional: static file serving ────────────────────────────────────
+aiofiles>=23.2.1

tests/test_promptforge.py

@@ -0,0 +1,567 @@
+"""
+PromptForge v4.0 — Test suite
+Run: pytest tests/test_promptforge.py -v --asyncio-mode=auto
+
+Coverage:
+  Health / Config (3)   Settings CRUD + extras (16)
+  Generate (8)          Batch (2)
+  Approve (3)           Export (4)
+  Refine (3)            Explain (2)
+  History (6)           Search (2)
+  Stats (1)             Favorite/Archive (4)
+  Unit tests (12)
+"""
+import json, pytest
+from datetime import datetime
+from httpx import AsyncClient, ASGITransport
+from fastapi.testclient import TestClient
+
+import store, instruction_store
+from main import app
+from schemas import (
+    InstructionSettingsCreate, OutputFormat, PersonaType, StyleType, AIProvider
+)
+from prompt_logic import (
+    build_manifest, build_manifest_from_settings, apply_edits,
+    refine_with_feedback, generate_explanation, _resolve_role,
+    _build_constraints, _auto_tag, _infer_output_format,
+)
+
+# ── Helpers ───────────────────────────────────────────────────────────
+
+@pytest.fixture(autouse=True)
+def clean_stores():
+    """Reset both in-memory stores before each test."""
+    store._DB.clear()
+    instruction_store._DB.clear()
+    yield
+    store._DB.clear()
+    instruction_store._DB.clear()
+
+@pytest.fixture
+def client():
+    return TestClient(app)
+
+@pytest.fixture
+def sample_setting_payload():
+    return {
+        "title": "Test Setting",
+        "description": "A test instruction setting for unit tests.",
+        "instruction": "Create a TypeScript React component with TailwindCSS and Jest tests.",
+        "extra_context": "Support dark mode. Use hooks only.",
+        "output_format": "both",
+        "persona": "senior_dev",
+        "style": "professional",
+        "constraints": ["TypeScript strict mode", "WCAG 2.1 AA"],
+        "tags": ["react", "typescript"],
+        "provider": "none",
+        "enhance": False,
+        "is_favorite": False,
+    }
+
+@pytest.fixture
+def created_setting(client, sample_setting_payload):
+    r = client.post("/api/instructions", json=sample_setting_payload)
+    assert r.status_code == 201
+    return r.json()
+
+@pytest.fixture
+def generated_prompt(client):
+    r = client.post("/api/generate", json={
+        "instruction": "Write a Python FastAPI endpoint with Pydantic validation and tests.",
+        "output_format": "both",
+        "provider": "none",
+        "enhance": False,
+        "persona": "senior_dev",
+        "style": "detailed",
+    })
+    assert r.status_code == 200
+    return r.json()
+
+@pytest.fixture
+def approved_prompt(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.post("/api/approve", json={"prompt_id": pid})
+    assert r.status_code == 200
+    return r.json()
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 1. HEALTH / CONFIG
+# ══════════════════════════════════════════════════════════════════════
+
+def test_health(client):
+    r = client.get("/health")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["status"] == "ok"
+    assert data["version"] == "4.0.0"
+
+def test_config(client):
+    r = client.get("/api/config")
+    assert r.status_code == 200
+    data = r.json()
+    assert "hf_key_set" in data
+    assert "google_key_set" in data
+    assert data["version"] == "4.0.0"
+
+def test_stats_empty(client):
+    r = client.get("/api/stats")
+    assert r.status_code == 200
+    s = r.json()
+    assert s["total_prompts"] == 0
+    assert "top_personas" in s
+    assert "uptime_since" in s
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 2. INSTRUCTION SETTINGS CRUD
+# ══════════════════════════════════════════════════════════════════════
+
+def test_create_setting(client, sample_setting_payload):
+    r = client.post("/api/instructions", json=sample_setting_payload)
+    assert r.status_code == 201
+    s = r.json()
+    assert s["title"] == sample_setting_payload["title"]
+    assert s["settings_id"]
+    assert s["use_count"] == 0
+    assert s["version"] == 1
+
+def test_get_setting(client, created_setting):
+    sid = created_setting["settings_id"]
+    r = client.get(f"/api/instructions/{sid}")
+    assert r.status_code == 200
+    assert r.json()["settings_id"] == sid
+
+def test_list_settings(client, created_setting):
+    r = client.get("/api/instructions")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["total"] >= 1
+
+def test_update_setting(client, created_setting):
+    sid = created_setting["settings_id"]
+    r = client.patch(f"/api/instructions/{sid}", json={"title": "Updated Title"})
+    assert r.status_code == 200
+    assert r.json()["title"] == "Updated Title"
+    assert r.json()["version"] == 2
+
+def test_delete_setting(client, created_setting):
+    sid = created_setting["settings_id"]
+    r = client.delete(f"/api/instructions/{sid}")
+    assert r.status_code == 200
+    r2 = client.get(f"/api/instructions/{sid}")
+    assert r2.status_code == 404
+
+def test_404_get_setting(client):
+    r = client.get("/api/instructions/nonexistent-id")
+    assert r.status_code == 404
+
+def test_404_update_setting(client):
+    r = client.patch("/api/instructions/bad-id", json={"title": "X"})
+    assert r.status_code == 404
+
+def test_duplicate_setting(client, created_setting):
+    sid = created_setting["settings_id"]
+    r = client.post(f"/api/instructions/{sid}/duplicate")
+    assert r.status_code == 200
+    copy = r.json()
+    assert "copy" in copy["title"].lower()
+    assert copy["settings_id"] != sid
+
+def test_favorite_setting(client, created_setting):
+    sid = created_setting["settings_id"]
+    r = client.post(f"/api/instructions/{sid}/favorite")
+    assert r.status_code == 200
+    assert r.json()["is_favorite"] is True
+    # toggle again
+    r2 = client.post(f"/api/instructions/{sid}/favorite")
+    assert r2.json()["is_favorite"] is False
+
+def test_export_all_settings(client, created_setting):
+    r = client.get("/api/instructions/export")
+    assert r.status_code == 200
+    data = r.json()
+    assert "settings" in data
+    assert data["total"] >= 1
+
+def test_get_all_tags(client, created_setting):
+    r = client.get("/api/instructions/tags")
+    assert r.status_code == 200
+    data = r.json()
+    assert "tags" in data
+    assert "react" in data["tags"]
+
+def test_list_settings_filter_tag(client, created_setting):
+    r = client.get("/api/instructions?tag=react")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["total"] >= 1
+
+def test_list_settings_search(client, created_setting):
+    r = client.get("/api/instructions?q=TypeScript")
+    assert r.status_code == 200
+    assert r.json()["total"] >= 1
+
+def test_instruction_too_short(client):
+    r = client.post("/api/instructions", json={
+        "title": "Short", "instruction": "hi",
+    })
+    assert r.status_code == 422
+
+def test_title_required(client):
+    r = client.post("/api/instructions", json={"instruction": "Some long instruction here."})
+    assert r.status_code == 422
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 3. GENERATE
+# ══════════════════════════════════════════════════════════════════════
+
+def test_generate_basic(client):
+    r = client.post("/api/generate", json={
+        "instruction": "Create a responsive navbar component.",
+        "output_format": "both", "provider": "none",
+    })
+    assert r.status_code == 200
+    data = r.json()
+    assert data["success"] is True
+    assert data["prompt_id"]
+    sp = data["manifest"]["structured_prompt"]
+    assert len(sp["raw_prompt_text"]) > 50, "raw_prompt_text must be copy-paste ready"
+    assert sp["role"]
+    assert sp["task"]
+    assert sp["constraints"]
+
+def test_generate_copy_paste_ready(client):
+    r = client.post("/api/generate", json={
+        "instruction": "Write a Python function to parse JSON safely.",
+        "output_format": "text",
+    })
+    assert r.status_code == 200
+    raw = r.json()["manifest"]["structured_prompt"]["raw_prompt_text"]
+    assert len(raw) > 100
+    assert "## ROLE" in raw
+    assert "## TASK" in raw
+    assert "## CONSTRAINTS" in raw
+
+def test_generate_with_persona(client):
+    r = client.post("/api/generate", json={
+        "instruction": "Set up a Kubernetes cluster with helm charts.",
+        "persona": "devops_eng",
+    })
+    assert r.status_code == 200
+    role = r.json()["manifest"]["structured_prompt"]["role"].lower()
+    assert any(k in role for k in ["devops","cloud","platform","engineer"])
+
+def test_generate_with_ml_persona(client):
+    r = client.post("/api/generate", json={
+        "instruction": "Fine-tune a BERT model on custom dataset.",
+        "persona": "ml_engineer",
+    })
+    assert r.status_code == 200
+    assert r.json()["success"] is True
+
+def test_generate_with_style(client):
+    r = client.post("/api/generate", json={
+        "instruction": "Explain how garbage collection works in Python.",
+        "style": "beginner",
+    })
+    assert r.status_code == 200
+    assert "beginner" in r.json()["manifest"]["structured_prompt"]["style"].lower()
+
+def test_generate_with_constraints(client):
+    r = client.post("/api/generate", json={
+        "instruction": "Build a REST API.",
+        "user_constraints": ["No external libraries", "Under 50 lines"],
+    })
+    assert r.status_code == 200
+    constraints = r.json()["manifest"]["structured_prompt"]["constraints"]
+    assert any("No external" in c for c in constraints)
+
+def test_generate_instruction_too_short(client):
+    r = client.post("/api/generate", json={"instruction": "hi"})
+    assert r.status_code == 422
+
+def test_generate_from_settings(client, created_setting):
+    sid = created_setting["settings_id"]
+    r = client.post("/api/generate/from-settings", json={"settings_id": sid})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["success"] is True
+    assert data["manifest"]["settings_id"] == sid
+    # use_count should increment
+    s = client.get(f"/api/instructions/{sid}").json()
+    assert s["use_count"] == 1
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 4. BATCH GENERATE
+# ══════════════════════════════════════════════════════════════════════
+
+def test_batch_generate(client):
+    r = client.post("/api/generate/batch", json={"requests": [
+        {"instruction": "Write a Python hello world function."},
+        {"instruction": "Write a SQL query to list all users."},
+    ]})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["total"] == 2
+    assert data["failed"] == 0
+
+def test_batch_single(client):
+    r = client.post("/api/generate/batch", json={"requests": [
+        {"instruction": "Explain what a binary tree is."}
+    ]})
+    assert r.status_code == 200
+    assert r.json()["total"] == 1
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 5. EXPLAIN
+# ══════════════════════════════════════════════════════════════════════
+
+def test_explain(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.get(f"/api/explain/{pid}")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["explanation"]
+    assert isinstance(data["key_decisions"], list)
+    assert len(data["key_decisions"]) >= 3
+
+def test_explain_404(client):
+    r = client.get("/api/explain/nonexistent")
+    assert r.status_code == 404
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 6. APPROVE
+# ══════════════════════════════════════════════════════════════════════
+
+def test_approve_prompt(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.post("/api/approve", json={"prompt_id": pid})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["success"] is True
+    assert data["finalized_prompt"]["raw_prompt_text"]
+
+def test_approve_with_edits(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.post("/api/approve", json={
+        "prompt_id": pid,
+        "edits": {"role": "Custom QA Engineer", "style": "concise style applied"},
+    })
+    assert r.status_code == 200
+    sp = r.json()["finalized_prompt"]
+    assert sp["role"] == "Custom QA Engineer"
+
+def test_approve_404(client):
+    r = client.post("/api/approve", json={"prompt_id": "bad-id"})
+    assert r.status_code == 404
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 7. EXPORT
+# ══════════════════════════════════════════════════════════════════════
+
+def test_export_json(client, approved_prompt):
+    pid = approved_prompt["prompt_id"]
+    r = client.post("/api/export", json={"prompt_id": pid, "export_format": "json"})
+    assert r.status_code == 200
+    data = r.json()
+    assert data["success"] is True
+    export_data = data["data"]
+    for key in ["role","task","input_format","output_format","constraints","safety","raw_prompt_text"]:
+        assert key in export_data, f"Missing key in JSON export: {key}"
+
+def test_export_text(client, approved_prompt):
+    pid = approved_prompt["prompt_id"]
+    r = client.post("/api/export", json={"prompt_id": pid, "export_format": "text"})
+    assert r.status_code == 200
+    assert isinstance(r.json()["data"], str)
+    assert len(r.json()["data"]) > 50
+
+def test_export_both(client, approved_prompt):
+    pid = approved_prompt["prompt_id"]
+    r = client.post("/api/export", json={"prompt_id": pid, "export_format": "both"})
+    assert r.status_code == 200
+    data = r.json()["data"]
+    assert "json" in data and "text" in data
+
+def test_export_requires_approval(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.post("/api/export", json={"prompt_id": pid, "export_format": "json"})
+    assert r.status_code == 400
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 8. REFINE
+# ══════════════════════════════════════════════════════════════════════
+
+def test_refine_prompt(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.post("/api/refine", json={
+        "prompt_id": pid,
+        "feedback": "Add WCAG accessibility constraints and keyboard navigation requirements.",
+    })
+    assert r.status_code == 200
+    data = r.json()
+    assert data["success"] is True
+    assert data["manifest"]["version"] == 2
+
+def test_refine_increments_version(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    for i, fb in enumerate(["Add tests.", "Add logging.", "Add metrics."], 2):
+        r = client.post("/api/refine", json={"prompt_id": pid, "feedback": fb})
+        assert r.status_code == 200
+        assert r.json()["manifest"]["version"] == i
+
+def test_refine_404(client):
+    r = client.post("/api/refine", json={"prompt_id": "bad-id", "feedback": "some feedback"})
+    assert r.status_code == 404
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 9. HISTORY
+# ══════════════════════════════════════════════════════════════════════
+
+def test_history_empty(client):
+    r = client.get("/api/history")
+    assert r.status_code == 200
+    assert r.json()["total"] == 0
+
+def test_history_after_generate(client, generated_prompt):
+    r = client.get("/api/history")
+    assert r.status_code == 200
+    assert r.json()["total"] == 1
+
+def test_history_status_filter(client, generated_prompt, approved_prompt):
+    r = client.get("/api/history?status_filter=pending")
+    entries = r.json()["entries"]
+    assert all(e["status"] == "pending" for e in entries)
+
+def test_delete_history(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.delete(f"/api/history/{pid}")
+    assert r.status_code == 200
+    r2 = client.get("/api/history")
+    assert r2.json()["total"] == 0
+
+def test_favorite_prompt(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.post(f"/api/prompts/{pid}/favorite")
+    assert r.status_code == 200
+    assert r.json()["is_favorite"] is True
+
+def test_archive_prompt(client, generated_prompt):
+    pid = generated_prompt["prompt_id"]
+    r = client.post(f"/api/prompts/{pid}/archive")
+    assert r.status_code == 200
+    assert r.json()["status"] == "archived"
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 10. SEARCH
+# ══════════════════════════════════════════════════════════════════════
+
+def test_search_prompts(client, generated_prompt):
+    r = client.get("/api/search?q=fastapi")
+    assert r.status_code == 200
+    data = r.json()
+    assert data["total"] >= 1
+    assert "snippet" in data["results"][0]
+
+def test_search_no_results(client):
+    r = client.get("/api/search?q=zzznoresults999")
+    assert r.status_code == 200
+    assert r.json()["total"] == 0
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 11. STATS
+# ══════════════════════════════════════════════════════════════════════
+
+def test_stats_after_activity(client, approved_prompt):
+    r = client.get("/api/stats")
+    assert r.status_code == 200
+    s = r.json()
+    assert s["total_prompts"] >= 1
+    assert s["approved_count"] >= 1
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 12. UNIT TESTS — prompt_logic.py
+# ══════════════════════════════════════════════════════════════════════
+
+def test_build_manifest_structure():
+    m = build_manifest("Create a React component")
+    sp = m.structured_prompt
+    assert m.prompt_id
+    assert m.status == "pending"
+    assert sp.role
+    assert sp.task
+    assert sp.input_format
+    assert sp.output_format
+    assert isinstance(sp.constraints, list)
+    assert isinstance(sp.safety, list)
+    assert len(sp.safety) >= 4
+    assert len(sp.raw_prompt_text) > 50
+    assert sp.word_count > 0
+
+def test_build_manifest_heuristic_role():
+    m = build_manifest("Write pytest tests with coverage for a FastAPI app.")
+    assert any(k in m.structured_prompt.role.lower() for k in ["test","qa","backend"])
+
+def test_build_manifest_devops_persona():
+    m = build_manifest("Deploy to Kubernetes", persona=PersonaType.devops_eng)
+    assert "devops" in m.structured_prompt.role.lower() or "platform" in m.structured_prompt.role.lower()
+
+def test_build_manifest_ml_persona():
+    m = build_manifest("Fine-tune GPT-2 on a dataset", persona=PersonaType.ml_engineer)
+    assert "machine learning" in m.structured_prompt.role.lower() or "ml" in m.structured_prompt.role.lower()
+
+def test_build_manifest_custom_persona():
+    m = build_manifest("Do something", persona=PersonaType.custom, custom_persona="Rust Embedded Systems Engineer")
+    assert m.structured_prompt.role == "Rust Embedded Systems Engineer"
+
+def test_auto_tagging():
+    tags = _auto_tag("create a react component with typescript and tailwind css")
+    assert "react" in tags
+    assert "typescript" in tags or "frontend" in tags
+
+def test_constraint_injection():
+    constraints = _build_constraints("use typescript and add unit tests", [])
+    assert any("TypeScript" in c for c in constraints)
+    assert any("test" in c.lower() for c in constraints)
+
+def test_user_constraints_merged():
+    constraints = _build_constraints("simple task", ["Use PostgreSQL", "Limit to 200 lines"])
+    assert any("PostgreSQL" in c for c in constraints)
+    assert any("200 lines" in c for c in constraints)
+
+def test_output_format_inference():
+    assert "JSON" in _infer_output_format("return json with all fields")
+    assert "Markdown" in _infer_output_format("write markdown documentation")
+    assert "code" in _infer_output_format("create a python function").lower() or "code" in _infer_output_format("write code").lower()
+
+def test_apply_edits():
+    m = build_manifest("Write a function in Python")
+    edited = apply_edits(m, {"role": "Overridden Role"})
+    assert edited.structured_prompt.role == "Overridden Role"
+    assert edited.status == "approved"
+
+def test_refine_with_feedback():
+    m = build_manifest("Write a simple API")
+    refined = refine_with_feedback(m, "Add rate limiting and caching.")
+    assert refined.version == 2
+    assert refined.prompt_id == m.prompt_id
+    assert "REFINEMENT REQUEST" in refined.instruction
+
+def test_generate_explanation_returns_content():
+    m = build_manifest("Build a GraphQL server", persona=PersonaType.senior_dev)
+    explanation, decisions = generate_explanation(m)
+    assert explanation
+    assert len(decisions) >= 3
+    assert any("Role" in d for d in decisions)