MultiverbeBOS

Phase G full · Setup founder · Upstash KV + GitHub PAT + Vercel env

Phase G full BOS · 2026-05-11 · Tempo founder ~20 minuti. Prerequisito: deploy bos.multiverbe.com su Vercel già fatto (vedi deploy-bos-multiverbe-com-setup.md).

Phase G aggiunge: form modal funzionali (4 quick action) · Vercel API endpoints /api/live/* con persistenza Upstash KV · diff renderer polling con animations · SSE push real-time · GitHub commit opt-in per audit trail durable.

✅ File già creati da Claude in questa sessione

File Scope
api/_lib/kv.js Upstash Redis helper (get/set/lpush/lrange/del/ltrim) + in-memory fallback dev
api/_lib/github.js GitHub commit helper opt-in via PAT (zero auto-commit se token mancante)
api/live/sessions.js GET active sessions + POST register/heartbeat + DELETE end
api/live/activity.js GET activity log (KV → static fallback)
api/live/kpi.js GET KPI snapshot derived da clients KV
api/live/action-add.js POST aggiungi action item · KV + commit GitHub opt-in
api/live/decision-add.js POST aggiungi decisione → append decisions-log.md · KV + commit GitHub opt-in
api/live/client-add.js POST nuovo cliente (PII · solo KV, no GitHub commit)
api/live/week-update.js POST update pinned focus + planet_in_build · KV + commit GitHub opt-in
api/live/sse.js Server-Sent Events streaming per push real-time
build/assets/js/main.js Modal system 4 form types con FormData + fetch + optimistic UI
build/assets/js/polling-live.js Diff renderer + auto-fallback API→static + SSE subscription opt-in
build/assets/css/nebula-glass.css Modal CSS Nebula Glass (backdrop blur + slideUp animation + form fields styled)

🛠️ Azioni founder · 20 minuti totali

Step 1 · Upstash Redis signup + database (5 min)

  1. https://upstash.com/ → Sign up con GitHub (zero password)
  2. Console → Create Database → "Redis"
    • Name: multiverbe-bos
    • Region: eu-west-1 (Ireland · low latency da CH)
    • Type: Regional (free tier)
    • Eviction: ALLKEYS_LRU
  3. Database creato → tab REST API → copia 2 valori:
    • UPSTASH_REDIS_REST_URL (es. https://xxx-12345.upstash.io)
    • UPSTASH_REDIS_REST_TOKEN (lungo string base64)
  4. Free tier: 10K commands/day · 256MB · sufficiente per 100+ paganti uso BOS.

Step 2 · Vercel env vars BOS project (5 min)

  1. Vercel → project multiverbe-bos → Settings → Environment Variables
  2. Aggiungi 2 vars (scope: Production + Preview):
    • KV_REST_API_URL = valore di UPSTASH_REDIS_REST_URL step 1
    • KV_REST_API_TOKEN = valore di UPSTASH_REDIS_REST_TOKEN step 1
  3. Save · Vercel triggera auto-redeploy (~2 min)
  4. Verifica: apri https://bos.multiverbe.com/api/live/sessions → deve restituire JSON { active_sessions: [], _description: ... } (NON 503 / 500)

Step 3 · GitHub PAT opt-in per audit trail (5 min · OPZIONALE ma raccomandato)

Se NON setti GITHUB_TOKEN: tutto funziona, ma form submit vivono solo in KV (Upstash è source of truth · backup manuali periodici a tuo carico).

Se setti GITHUB_TOKEN: ogni action/decision/week-update crea anche commit Git per audit trail durable.

  1. https://github.com/settings/tokens?type=beta → Generate new token (fine-grained)
  2. Token name: BOS-Vercel-commit-back
  3. Expiration: 90 days (ricorda di rotare in multiverbe-security-ch skill calendar)
  4. Repository access: Only select repositories → metaverbe-hub/Multiverbe-Business
  5. Repository permissions:
    • Contents: Read and write
    • Metadata: Read-only (auto-include)
  6. Generate token → copia il token (visualizzato 1 sola volta)
  7. Vercel project multiverbe-bos → Settings → Environment Variables → aggiungi 3 vars:
    • GITHUB_TOKEN = il token PAT step 6
    • GITHUB_REPO = metaverbe-hub/Multiverbe-Business
    • GITHUB_BRANCH = main
  8. Save · Redeploy auto

Step 4 · Test end-to-end (5 min)

  1. Apri https://bos.multiverbe.com (basic auth login)
  2. Scroll dashboard live · vedi badge ● LIVE su widget sessions/kpi/activity (era ○ STATIC pre-Step 2)
  3. Click + Add Action → compila form:
    • Cosa fare: "Test Phase G full Phase G live"
    • Owner: G
    • Priority: low
    • Submit
  4. Vedi messaggio ✅ Salvato. ID: ... · modal si chiude in 1.2s
  5. Activity widget mostra immediatamente nuovo evento ➕ gregorio · action_add · Added: Test Phase G full...
  6. Se Step 3 GitHub PAT fatto: vai su https://github.com/metaverbe-hub/Multiverbe-Business/commits/main → vedi commit feat(BOS): + action "Test Phase G full..." via form submit (con [skip ci] per non triggerare rebuild)
  7. Click + Add Decision → test decision creation
  8. Click + New Client → test client (PII solo KV, NO commit GitHub)
  9. Click Update Week → test pinned_focus update

📊 Architettura runtime

┌─────────────────────────────────────────────────────────────────┐
│                  bos.multiverbe.com                             │
│                                                                 │
│  ┌──────────────┐         ┌─────────────────────────────────┐  │
│  │  Static HTML │         │  Vercel Functions (/api/live/*) │  │
│  │  + assets    │         │  - sessions (GET POST DELETE)   │  │
│  │  + polling-  │ ─fetch→ │  - activity (GET)               │  │
│  │  live.js     │         │  - kpi (GET)                    │  │
│  │              │ ←sse──── │  - sse (event-stream)           │  │
│  │              │         │  - action-add (POST)            │  │
│  │              │ ─POST→  │  - decision-add (POST)          │  │
│  │              │         │  - client-add (POST)            │  │
│  │              │         │  - week-update (POST)           │  │
│  └──────────────┘         └────────────┬────────────────────┘  │
│                                        │                       │
└────────────────────────────────────────┼───────────────────────┘
                                         │
              ┌──────────────────────────┴──────────────────────┐
              │                                                 │
              ▼                                                 ▼
    ┌──────────────────┐                          ┌──────────────────────┐
    │  Upstash Redis   │                          │  GitHub Repo (PAT)   │
    │  (KV fast hot)   │                          │  Multiverbe-Business │
    │                  │                          │  (audit trail durab.)│
    │  bos:sessions:*  │                          │                      │
    │  bos:activity:*  │                          │  source/_meta/       │
    │  bos:kpi         │                          │   status.json        │
    │  bos:clients     │                          │  execution/          │
    │  bos:status      │                          │   decisions-log.md   │
    └──────────────────┘                          └──────────────────────┘
                                                  (opt-in: opzionale)

Latenza percepita:

  • Form submit → KV write → optimistic UI: <100ms
  • KV → GitHub commit async: 1-3s (fire-and-forget, non blocca UI)
  • Polling client → KV read: <200ms (Upstash regional eu-west-1)
  • SSE push → instant refresh on KV change: <2.5s (limited by SSE poll interval)

💰 Cost estimate Phase G

Service Tier Costo
Vercel Hobby (con BOS già live) €0
Vercel Functions invocations Hobby (100K/mese gratis) €0 (BOS uso interno = ~5K/mese)
Upstash Redis Free €0 (10K cmd/day = ~2.7M/mese, BOS uso ~50K/mese)
GitHub Actions Free 2000 min/mese €0
GitHub PAT Free €0
Total €0/mese

Upgrade triggers Q3+:

  • Upstash Pro $0.20/100K cmd se >300K cmd/giorno (improbabile con uso interno 3 utenti)
  • Vercel Pro $20/mo per Password Protection nativa (alternativa a middleware basic auth)

🔐 Security checklist

  • [ ] GITHUB_TOKEN scope minimo (contents:write + metadata:read SOLO su Multiverbe-Business)
  • [ ] PAT expiration 90 giorni · auto-reminder in skill multiverbe-security-ch Q3
  • [ ] Upstash REST_TOKEN scope: full (single account, no team mgmt needed pre-Series-A)
  • [ ] BOS basic auth attivo (Vercel Pro Password Protection o middleware Edge)
  • [ ] Form fields validation server-side (in client-add.js es. email regex validation)
  • [ ] Activity log audit ogni form submit (chi ha aggiunto cosa quando)
  • [ ] Rate limit Vercel functions (auto via Vercel infra · pre-DDoS)

🐛 Troubleshooting

Widget mostra ○ STATIC invece di ● LIVE:

  • KV env vars non settate o sbagliate · verifica Step 2
  • Apri devtools console: cerca log [BOS polling] sessions primary failed
  • Test diretto: curl https://bos.multiverbe.com/api/live/sessions → se 500 → KV broken

Form submit ritorna 500 "KV not configured":

  • KV_REST_API_URL o KV_REST_API_TOKEN missing in Vercel env
  • Step 2 incompleto · ricontrolla Settings > Environment Variables

Form submit success ma niente commit su GitHub:

  • GITHUB_TOKEN missing → questa è normale (opt-in)
  • Se vuoi commit → fai Step 3
  • Se hai fatto Step 3 ma niente commit → check Vercel function logs per "GitHub commit failed"

SSE non si attiva (badge resta ● LIVE ma no instant push):

  • SSE Hobby plan ha cycling 10s · client si riconnette auto
  • Polling 5s comunque funziona · differenza solo per "instant" perception
  • Per real-time vero serve Vercel Pro/Edge (60s timeout) o serverful (Railway $5/mo)

📅 Calendar reminder

Founder action: PAT GitHub rotation ogni 90 giorni → aggiunto come secret rotation in skill multiverbe-security-ch:

  • 1° giro scadenza: ~2026-08-11 (90gg da oggi 2026-05-11)
  • Cron: già coperto da slash command /security-monthly 1° del mese review tutti i secrets

Setup data: file Claude 2026-05-11 · azioni founder pending Cross-reference: AGENTS.md + feedback_business_eye_definitive.md memoria + deploy-bos-multiverbe-com-setup.md (prerequisito)