FIZZ & FIZZ DEV — by RANEDDIE

This repository contains:

Folder	What it is
static-site/	The website: public pages, RANEDDIE ID sign-up/sign-in, FIZZ chat (chat.html) and FIZZ DEV (dev.html)
netlify/	Server functions: OAuth for GitHub, Vercel & Canva, GitHub/Vercel APIs, and the FIZZ AI proxy
src/, prisma/	The full Next.js + PostgreSQL platform (alternative, server-rendered version)

Two ways to deploy

1. Netlify Drop (no server). Drag deploy/fizz-netlify-drop.zip onto https://app.netlify.com/drop. Everything in the browser works — accounts, chats, projects, editor, terminal, preview, ZIP export, and AI with each user's own OpenRouter or Anthropic key. GitHub, Vercel, Canva, Google and the included FIZZ AI show "Not available yet", because Drop can't run server functions.

2. Netlify from GitHub (recommended — enables everything).

1. app.netlify.com → Add new site → Import an existing project → GitHub → pick this repo/branch. netlify.toml already sets the publish folder, functions and edge functions.
2. Add the environment variables below (Site configuration → Environment variables), then redeploy.

3. Vercel (also enables everything). Import the repo in Vercel. vercel.json already sets the output folder (static-site), skips the Next.js build and runs the same server code from api/. Add the environment variables below under Settings → Environment Variables and redeploy. For a reliable FIZZ AI daily quota, add Storage → Upstash Redis to the project (it sets KV_REST_API_URL/KV_REST_API_TOKEN); without it the quota is kept per server instance.

FIZZ DEV setup — environment variables

Never put secrets in code or in chat. Set them only in Netlify or Vercel (Vercel: choose Sensitive for every secret).

Variable	Required for	Where to get it
FIZZ_SECRET	All connections	Any random string of 32+ characters (e.g. openssl rand -base64 48). Encrypts the connection cookies.
OPENROUTER_API_KEY	Included FIZZ AI	openrouter.ai → Keys
GEMINI_API_KEY	Included FIZZ AI (alternative)	aistudio.google.com → Get API key. Used when OPENROUTER_API_KEY isn't set; default model gemini-3.8-flash
FIZZ_DEFAULT_MODEL	optional	OpenRouter model ID, default z-ai/glm-4.6 (check openrouter.ai/models)
FIZZ_FALLBACK_MODELS	optional	Comma-separated backup models tried when the main one is busy
FIZZ_DAILY_LIMIT	optional	Free messages per visitor per day, default 50
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET	GitHub sign-in button (optional)	github.com → Settings → Developer settings → OAuth Apps. Without them users connect with a personal token (scopes repo + workflow) in Settings → Connections.
VERCEL_CLIENT_ID, VERCEL_CLIENT_SECRET	Vercel sign-in button (optional)	vercel.com → Team settings → Sign in with Vercel / Apps. Users can always connect with a Vercel token (vercel.com/account/settings/tokens) instead — the most reliable way to deploy.
CANVA_CLIENT_ID, CANVA_CLIENT_SECRET	Canva OAuth connection (optional)	Canva Developers → your integration → OAuth settings. Add redirect URL https://YOUR-SITE/api/oauth/canva/callback. Optional CANVA_SCOPES overrides the default design:content:read design:content:write; use scopes enabled for your integration.
GOOGLE_CLIENT_ID	Google Workspace (Gmail, Calendar, Docs, Sheets, Slides, Drive, Tasks, Contacts)	console.cloud.google.com: turn on the Gmail, Calendar, Docs, Sheets, Slides, Drive, Tasks and People APIs; Google Auth Platform → External, add test users; Clients → Web application with your site as an Authorized JavaScript origin. No client secret needed.

Provider settings (replace YOUR-SITE with your Netlify or Vercel domain, e.g. fizzbrowser.vercel.app)

• GitHub OAuth App — Homepage URL https://YOUR-SITE, Authorization callback URL https://YOUR-SITE/api/oauth/github/callback. Scopes requested: repo workflow read:user (workflow lets FIZZ add the app-build workflows; people who connected earlier reconnect once).
• Canva integration — Redirect URL https://YOUR-SITE/api/oauth/canva/callback. OAuth uses PKCE (S256); keep the client secret in Vercel/Netlify environment variables, never in browser code.
• Vercel app — Redirect URL https://YOUR-SITE/api/oauth/vercel/callback. In the app's Permissions, allow creating/reading Deployments. Scopes: openid email profile offline_access.
• Google OAuth client (Web application) — Authorized JavaScript origin https://YOUR-SITE. Enable the Google Drive API in the project. Configure the OAuth consent screen and add yourself as a test user (scope drive.readonly requires Google verification before public launch). FIZZ uses Google Identity Services in the browser, so no Google client secret is needed; the access token lasts about an hour and stays in the browser tab.

Security notes

• GitHub and Vercel tokens are kept in AES-256-GCM encrypted, HttpOnly cookies scoped to /api — page JavaScript can never read them. All POST endpoints reject cross-site requests.
• MCP servers are stored the same way (Upstash when connected, otherwise the same sealed cookie) and every hop — including redirects — is checked against private and internal addresses. The Authorization header a user pastes never reaches the browser and is redacted from tool results. The first call to each server asks for permission; calls that send, post or delete always ask.
• If any credential was ever shared in chat or email, rotate it in the provider's dashboard.
• The included FIZZ AI enforces a per-visitor daily quota (Upstash or Netlify Blobs) to protect your OpenRouter budget.
• Web reading refuses private and internal addresses (also through redirects). Search, the cloud browser and the sandbox need a signed-in RanEddie ID user and have daily limits per user.
• Cloud browser sessions live in an encrypted cookie; Fizz Code is told to treat page text as information, not instructions, and can't type into password or card fields.

RanEddie ID (required sign-in)

FIZZ uses the same Clerk instance as RanEddie ID, so it's the same account as every RanEddie product. signin.html has the RanEddie ID forms (sign in with a new-device email code, sign up with email verification and a minimum age of 13, forgot password), built on clerk-js pinned in assets/raneddie-id.js. FIZZ and FIZZ DEV require a RanEddie ID: visitors are sent to sign in and back (only a deployment without the Clerk keys lets guests in). Only a few small settings (≤ 500 bytes) are saved under privateMetadata.fizz through /api/account, which verifies the Clerk session token and merges only that key — other products' metadata (e.g. Snake Brawl) is never touched. Chats and projects are linked to the account on first sign-in; with Upstash connected, cloud sync (/api/sync) keeps them per Clerk user id in Upstash (never in metadata), so they appear on every device. Images and PDFs stay in the browser that made them.

One app, instant switching

FIZZ and FIZZ DEV are a single page (scripts/app-shell.html, written out as chat.html and dev.html). The FIZZ / FIZZ DEV switch in the sidebar — or Ctrl+. — swaps between them instantly in the same tab, with no reload: chats keep streaming, the editor and terminal keep their state, and Back/Forward work. Any FIZZ answer that contains code has Build in FIZZ DEV, which hands the answer over as an attachment.

FIZZ chat searches the web: when the deployment has search (any of Browserbase, Brave, Tavily, or the built-in Wikipedia fallback), FIZZ looks up current facts mid-answer — it writes a search or a page read, gets the results back, and continues with sources cited. What you see stays a normal answer; the tool rounds aren't saved to the chat, and search results are treated as data, never as instructions.

FIZZ DEV features

• Agent chat: a live task list, one activity line per reply (click to see each diff, command and result), Build / Plan / Ask modes, questions with answer buttons, review-before-apply, restore to any reply, @file mentions, project memory (FIZZ.md), slash commands and Skills (assets/skills.js).
• Do mode — a personal agent: next to Build / Plan / Ask, Do has Fizz get things done for you instead of writing code — sign-ups and API keys in the cloud browser, Gmail, Calendar, Docs, Drive, YouTube uploads, and the apps you connected — with its own handbook (assets/brain-assistant.js). Sending, posting, publishing, deleting and buying always wait for your OK. Each chat shows whether it's working, waiting for you or stopped.
• Memory: <fizz-remember> saves lasting facts and preferences (never passwords or keys); Settings → General lists and edits them, and every mode sees them.
• Apps connected with a token (Settings → Connections → Apps): Notion, Trello, Linear, Airtable, Figma, Netlify, Cloudflare, Discord, Telegram, Slack and Supabase. The token is checked once and sealed in an HttpOnly cookie; <fizz-api> calls go through /api/connector, which only talks to that app's API and never returns the token.
• MCP servers (Settings → Connections → MCP servers): add any MCP server by its URL — data sources, browsers, GitHub, Notion, your own services — and Fizz Code gets its tools as <fizz-mcp>. Both transports work (Streamable HTTP and the older HTTP+SSE). The handshake lists the tools; the address and its Authorization header stay encrypted on the server (never in the browser, redacted from results). The first call to a server asks for permission; sending, posting and deleting always ask (Settings → Tools → Ask before every MCP call to ask always). Daily limit FIZZ_MCP_LIMIT (default 400 tool calls per user). A local npx … server needs a public URL first (a tunnel or a hosted endpoint) — this server can't reach your computer.
• Telegram updates (Settings → Tools): a message when Fizz finishes or needs you.
• Fizz Code's handbook (assets/fizz-brain.js + brain-design.js, brain-code.js, brain-platforms.js): a long engineering guide — how to plan, structure a project into many focused files, write complete code, verify, debug and report — plus deep sections on design, components, JavaScript, games, data, servers, Python, mobile, documents, extensions, deployment and more. Every request gets the core and the craft sections, plus the topics that fit the task and the project (a game gets the game sections, and so on). Each section is plain text you can edit.

Development

python3 scripts/build-static-pages.py     # regenerate public pages after editing content
node tests/netlify/functions.test.mjs     # server function tests (fake credentials)
node tests/netlify/tools.test.mjs         # web, sync, sandbox and GitHub Actions functions
CDP_URL=ws://… node tests/netlify/browser.test.mjs   # cloud browser actions, against a local Chrome
node scripts/build-browser-agent.mjs      # after editing netlify/lib/browser-agent.js
cd static-site && python3 -m http.server  # preview the static site locally

The full Next.js platform: npm install, create .env (DATABASE_URL, SESSION_SECRET, ENCRYPTION_KEY, ANTHROPIC_API_KEY), npx prisma migrate deploy && npm run db:seed, npm run dev.