Update README.md

README.md

@@ -1,162 +1,164 @@
-# Quantum Pi Forge (v6)
-
-This repository powers the Quantum Pi Forge site. It currently ships as a Create React App but includes the scaffolding for a Next.js static export; the Netlify deployment (see below) relies on the Next configuration in `next.config.mjs`.
-
-## Prerequisites
-
-- Node.js 18+ and `corepack` (bundled with Node 18+). `corepack` lets us invoke `pnpm` without a global install.
-- One of the supported package managers (this repo uses `pnpm`).
-
-## Getting started
-
-1. Install dependencies:
-
-```powershell
-corepack pnpm install
-```
-
-1. Start the development server:
-
-```powershell
-corepack pnpm start
-```
-
-1. Build for production (runs the CRA-based compiler that currently drives the site):
-
-```powershell
-corepack pnpm build
-```
-
-## Deploying to Vercel (production)
- 
-The CRA portion still runs via `corepack pnpm build`, but the payment workflow now lives inside Vercel Serverless functions. Configure your site in the Vercel dashboard (or run `vercel --prod`) after the build artifact is ready.
-
-### Vercel configuration
-
-`vercel.json` wires everything together:
-
-```json
-{
-  "version": 3,
-  "routes": [
-    {
-      "src": "/validation-key.txt",
-      "dest": "/public/validation-key.txt",
-      "headers": {
-        "Cache-Control": "public, max-age=0, must-revalidate",
-        "Content-Type": "text/plain; charset=utf-8"
-      }
-    },
-    {
-      "src": "/.well-known/validation-key.txt",
-      "dest": "/public/validation-key.txt",
-      "headers": {
-        "Cache-Control": "public, max-age=0, must-revalidate",
-        "Content-Type": "text/plain; charset=utf-8"
-      }
-    }
-  ],
-  "functions": {
-    "api/**/*.ts": {
-      "memory": 1024,
-      "maxDuration": 30
-    }
-  },
-  "rewrites": [
-    {
-      "source": "/.netlify/functions/(.*)",
-      "destination": "/api/$1"
-    }
-  ],
-  "headers": [
-    {
-      "source": "/api/(.*)",
-      "headers": [
-        { "key": "Access-Control-Allow-Origin", "value": "*" },
-        { "key": "Access-Control-Allow-Headers", "value": "Content-Type, Authorization, X-Signature, X-Timestamp" },
-        { "key": "Access-Control-Allow-Methods", "value": "GET, POST, OPTIONS" }
-      ]
-    }
-  ]
-}
-```
-
-### Pi Mainnet validation bundle
-
-The static `public/validation-key.txt` file exposes the Pi validation key at both `/validation-key.txt` and `/.well-known/validation-key.txt` so that the Pi Developer Portal can immediately confirm `quantumpiforge.com`. The routes above force `text/plain` semantics and disable caching so the validation status is always fresh.
-
-To confirm the file locally before deployment run:
-
-```bash
-curl -s https://quantumpiforge.com/validation-key.txt
-```
-
-Once deployed, rerun the same command or execute the `test-validation.js` helper to ensure the response is `50f70d548675a0db693c46b99c0eff07e2`. Run it with `node test-validation.js` after a short delay to verify the deployment pulls the correct key, then trigger the Pi Developer Console validation flow and expect the domain to turn green automatically. A GitHub Action (`.github/workflows/validation-check.yml`) already runs this same script hourly (and on every `main` push) to detect if the validation key ever becomes unreachable and fail the workflow so it can be investigated.
-
-### Pi Mainnet activation checklist
-
-After the validation key is live, add a Pi App Manifest so the Pi Studio checks the metadata immediately. Create `public/pi-app-manifest.json` with the following content before deploying:
-
-```json
-{
-  "name": "Quantum Pi Forge",
-  "description": "A Sovereign App built on Pi Network.",
-  "url": "https://quantumpiforge.com",
-  "permissions": ["username", "payments"]
-}
-```
-
-Once deployed, confirm these resources return 200 before pressing **Verify Domain** in Pi Studio:
-
-- `https://quantumpiforge.com/pi-app-manifest.json`
-- `https://quantumpiforge.com/validation-key.txt`
-- `https://quantumpiforge.com` loads without TLS issues
-
-Pi Studio will then verify the manifest, call the validation key, and let you submit the app for Pi Mainnet.
-
-The rewrite keeps older webhooks that still call `/.netlify/functions/...` intact; all the logic now executes in `api/*` handlers so you can delete the legacy `netlify/` files once you confirm the new functions behave identically.
-
-## Serverless functions
-
-All backend behavior lives inside `api/*.ts`. Each file imports `lib/tracing.ts` so the OpenTelemetry SDK bootstraps before business logic runs, preserving the existing tracing output in the AI Toolkit Trace Viewer.
-
-| Handler | Responsibility |
-| --- | --- |
-| `api/pi-create-payment.ts` | Accepts POST requests that create Pi payments, enriches metadata, and points the webhook to `api/pi-payment-webhook`. Uses `PI_BACKEND_URL`, `URL`, and `TEAM_TOKEN` to speak to the Pi backend and internal alerts. |
-| `api/pi-payment-webhook.ts` | Validates `x-pi-signature` via `PI_PAYMENT_SECRET`, deduplicates `payment_id`, upserts into Supabase (service key), and triggers `api/ethical-audit.ts` when an ethical audit is due. Alerts and retries go through `api/alert-webhook.ts`. |
-| `api/ethical-audit.ts` | Inserts audit entries into Supabase after verifying `X-Signature` + timestamp signed with `WEBHOOK_SECRET`, and responds with the inserted row ID so downstream UI can surface progress. |
-| `api/alert-webhook.ts` | Lightweight logging endpoint used by the webhook pipeline to capture failure contexts, keeping the same payloads as the prior Netlify handler. |
-| `api/auth-callback.ts` | Supabase auth callback used in the Pi Developer Console; exchanges the OAuth `code` for a session and redirects to `/auth/success`. |
-
-These handlers rely on the same environment secrets you had for Netlify, but the `URL` variable should now point at `https://quantumpiforge.com` (or whichever Vercel domain hosts the functions) so each helper can call its peers via `https://<site>/api/...`.
-
-### Asynchronous Pi payment flow
-
-The Supabase schema remains unchanged – keep the `payments` table defined as before, with indexes on `payment_id` and auditing columns. When `pi-create-payment` responds with a `payment_id`, show `Pending` on the frontend and watch Supabase Realtime for updates to that row. Once `status = 'completed' && audit_completed = true`, display the audit score and mining boost.
-
-### Environment checklist
-
-These values are still required inside Vercel Environment Variables:
-
-1. `PI_PAYMENT_SECRET` – Pi webhook HMAC secret.
-2. `SUPABASE_URL` & `SUPABASE_SERVICE_KEY` – Service key for inserts/updates.
-3. `URL` – Vercel site URL so functions can call each other (e.g., `https://quantumpiforge.com`).
-4. `TEAM_TOKEN` – Internal auth token that gates audit/alert calls.
-5. `PI_BACKEND_URL` – Backend proxy that actually talks to Pi Network.
-6. `WEBHOOK_SECRET` – Signing secret for `ethical-audit`.
-7. `PI_BACKEND_URL` – Keep referencing to talk to the payment backend.
-8. (Optional) `PI_DEVELOPER_REDIRECT` – Keep this aligned with `https://quantumpiforge.com/api/auth-callback` when updating Pi Developer Console redirect URIs.
-
-## Tracing
-
-All Vercel API handlers import `lib/tracing.ts`, so OpenTelemetry spans continue to stream to AI Toolkit. Start tracing locally with `ai-mlstudio.tracing.open` and inspect data in the Trace Viewer the same way you did for Netlify functions:
-
-- **Collector endpoint:** `http://localhost:4318/v1/traces` (override with `OTLP_ENDPOINT`).
-- **Trace scope:** HTTP entry spans, Supabase writes, HMAC validations, and internal fetch calls between functions.
-- **What to watch:** `pi-payment-webhook` spans should show audit calls, alert fallbacks, and Supabase upserts within a single trace.
-
-## Legacy Netlify notes
-
-- `.github/workflows/netlify-guardian.yml` is retained for reference, but it only applies while Netlify still owns the domain. Once `quantumpiforge.com` is fully on Vercel you can remove the workflow and the `netlify/` functions directory.
-- `netlify/functions/*` still exists for history, but all production traffic now hits `api/*` with the same request/response contracts.
-
+---
+sdk: gradio
+---
+# Quantum Pi Forge (v6)
+
+This repository powers the Quantum Pi Forge site. It currently ships as a Create React App but includes the scaffolding for a Next.js static export; the Netlify deployment (see below) relies on the Next configuration in `next.config.mjs`.
+
+## Prerequisites
+
+- Node.js 18+ and `corepack` (bundled with Node 18+). `corepack` lets us invoke `pnpm` without a global install.
+- One of the supported package managers (this repo uses `pnpm`).
+
+## Getting started
+
+1. Install dependencies:
+
+```powershell
+corepack pnpm install
+```
+
+1. Start the development server:
+
+```powershell
+corepack pnpm start
+```
+
+1. Build for production (runs the CRA-based compiler that currently drives the site):
+
+```powershell
+corepack pnpm build
+```
+
+## Deploying to Vercel (production)
+ 
+The CRA portion still runs via `corepack pnpm build`, but the payment workflow now lives inside Vercel Serverless functions. Configure your site in the Vercel dashboard (or run `vercel --prod`) after the build artifact is ready.
+
+### Vercel configuration
+
+`vercel.json` wires everything together:
+
+```json
+{
+  "version": 3,
+  "routes": [
+    {
+      "src": "/validation-key.txt",
+      "dest": "/public/validation-key.txt",
+      "headers": {
+        "Cache-Control": "public, max-age=0, must-revalidate",
+        "Content-Type": "text/plain; charset=utf-8"
+      }
+    },
+    {
+      "src": "/.well-known/validation-key.txt",
+      "dest": "/public/validation-key.txt",
+      "headers": {
+        "Cache-Control": "public, max-age=0, must-revalidate",
+        "Content-Type": "text/plain; charset=utf-8"
+      }
+    }
+  ],
+  "functions": {
+    "api/**/*.ts": {
+      "memory": 1024,
+      "maxDuration": 30
+    }
+  },
+  "rewrites": [
+    {
+      "source": "/.netlify/functions/(.*)",
+      "destination": "/api/$1"
+    }
+  ],
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "Access-Control-Allow-Origin", "value": "*" },
+        { "key": "Access-Control-Allow-Headers", "value": "Content-Type, Authorization, X-Signature, X-Timestamp" },
+        { "key": "Access-Control-Allow-Methods", "value": "GET, POST, OPTIONS" }
+      ]
+    }
+  ]
+}
+```
+
+### Pi Mainnet validation bundle
+
+The static `public/validation-key.txt` file exposes the Pi validation key at both `/validation-key.txt` and `/.well-known/validation-key.txt` so that the Pi Developer Portal can immediately confirm `quantumpiforge.com`. The routes above force `text/plain` semantics and disable caching so the validation status is always fresh.
+
+To confirm the file locally before deployment run:
+
+```bash
+curl -s https://quantumpiforge.com/validation-key.txt
+```
+
+Once deployed, rerun the same command or execute the `test-validation.js` helper to ensure the response is `50f70d548675a0db693c46b99c0eff07e2`. Run it with `node test-validation.js` after a short delay to verify the deployment pulls the correct key, then trigger the Pi Developer Console validation flow and expect the domain to turn green automatically. A GitHub Action (`.github/workflows/validation-check.yml`) already runs this same script hourly (and on every `main` push) to detect if the validation key ever becomes unreachable and fail the workflow so it can be investigated.
+
+### Pi Mainnet activation checklist
+
+After the validation key is live, add a Pi App Manifest so the Pi Studio checks the metadata immediately. Create `public/pi-app-manifest.json` with the following content before deploying:
+
+```json
+{
+  "name": "Quantum Pi Forge",
+  "description": "A Sovereign App built on Pi Network.",
+  "url": "https://quantumpiforge.com",
+  "permissions": ["username", "payments"]
+}
+```
+
+Once deployed, confirm these resources return 200 before pressing **Verify Domain** in Pi Studio:
+
+- `https://quantumpiforge.com/pi-app-manifest.json`
+- `https://quantumpiforge.com/validation-key.txt`
+- `https://quantumpiforge.com` loads without TLS issues
+
+Pi Studio will then verify the manifest, call the validation key, and let you submit the app for Pi Mainnet.
+
+The rewrite keeps older webhooks that still call `/.netlify/functions/...` intact; all the logic now executes in `api/*` handlers so you can delete the legacy `netlify/` files once you confirm the new functions behave identically.
+
+## Serverless functions
+
+All backend behavior lives inside `api/*.ts`. Each file imports `lib/tracing.ts` so the OpenTelemetry SDK bootstraps before business logic runs, preserving the existing tracing output in the AI Toolkit Trace Viewer.
+
+| Handler | Responsibility |
+| --- | --- |
+| `api/pi-create-payment.ts` | Accepts POST requests that create Pi payments, enriches metadata, and points the webhook to `api/pi-payment-webhook`. Uses `PI_BACKEND_URL`, `URL`, and `TEAM_TOKEN` to speak to the Pi backend and internal alerts. |
+| `api/pi-payment-webhook.ts` | Validates `x-pi-signature` via `PI_PAYMENT_SECRET`, deduplicates `payment_id`, upserts into Supabase (service key), and triggers `api/ethical-audit.ts` when an ethical audit is due. Alerts and retries go through `api/alert-webhook.ts`. |
+| `api/ethical-audit.ts` | Inserts audit entries into Supabase after verifying `X-Signature` + timestamp signed with `WEBHOOK_SECRET`, and responds with the inserted row ID so downstream UI can surface progress. |
+| `api/alert-webhook.ts` | Lightweight logging endpoint used by the webhook pipeline to capture failure contexts, keeping the same payloads as the prior Netlify handler. |
+| `api/auth-callback.ts` | Supabase auth callback used in the Pi Developer Console; exchanges the OAuth `code` for a session and redirects to `/auth/success`. |
+
+These handlers rely on the same environment secrets you had for Netlify, but the `URL` variable should now point at `https://quantumpiforge.com` (or whichever Vercel domain hosts the functions) so each helper can call its peers via `https://<site>/api/...`.
+
+### Asynchronous Pi payment flow
+
+The Supabase schema remains unchanged – keep the `payments` table defined as before, with indexes on `payment_id` and auditing columns. When `pi-create-payment` responds with a `payment_id`, show `Pending` on the frontend and watch Supabase Realtime for updates to that row. Once `status = 'completed' && audit_completed = true`, display the audit score and mining boost.
+
+### Environment checklist
+
+These values are still required inside Vercel Environment Variables:
+
+1. `PI_PAYMENT_SECRET` – Pi webhook HMAC secret.
+2. `SUPABASE_URL` & `SUPABASE_SERVICE_KEY` – Service key for inserts/updates.
+3. `URL` – Vercel site URL so functions can call each other (e.g., `https://quantumpiforge.com`).
+4. `TEAM_TOKEN` – Internal auth token that gates audit/alert calls.
+5. `PI_BACKEND_URL` – Backend proxy that actually talks to Pi Network.
+6. `WEBHOOK_SECRET` – Signing secret for `ethical-audit`.
+7. `PI_BACKEND_URL` – Keep referencing to talk to the payment backend.
+8. (Optional) `PI_DEVELOPER_REDIRECT` – Keep this aligned with `https://quantumpiforge.com/api/auth-callback` when updating Pi Developer Console redirect URIs.
+
+## Tracing
+
+All Vercel API handlers import `lib/tracing.ts`, so OpenTelemetry spans continue to stream to AI Toolkit. Start tracing locally with `ai-mlstudio.tracing.open` and inspect data in the Trace Viewer the same way you did for Netlify functions:
+
+- **Collector endpoint:** `http://localhost:4318/v1/traces` (override with `OTLP_ENDPOINT`).
+- **Trace scope:** HTTP entry spans, Supabase writes, HMAC validations, and internal fetch calls between functions.
+- **What to watch:** `pi-payment-webhook` spans should show audit calls, alert fallbacks, and Supabase upserts within a single trace.
+
+## Legacy Netlify notes
+
+- `.github/workflows/netlify-guardian.yml` is retained for reference, but it only applies while Netlify still owns the domain. Once `quantumpiforge.com` is fully on Vercel you can remove the workflow and the `netlify/` functions directory.
+- `netlify/functions/*` still exists for history, but all production traffic now hits `api/*` with the same request/response contracts.