# ZABAL Gamez Season 1 > A Farcaster vibe-coding challenge for the ZAO ecosystem - streamer games crossed with a hackathon. June workshops, July open build-a-thon, August Finals. Use any AI coding tool to ship a build that helps the ZAO community. This file is the machine-readable context for ZABAL Gamez builders. Point your AI harness at `https://zabalgamez.com/llms.txt` (Claude Code: save as `CLAUDE.md`; Cursor: `.cursorrules`; Windsurf: `.windsurfrules`; Aider: `CONVENTIONS.md`). Treat sections as menu items - if you are building Empire Builder tooling, focus on that section. For the full long-form context bundle (every detail, every code path) see [docs/research/630-player-context-bundle.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/630-player-context-bundle.md). For the current state of decisions see [docs/research/701-canonical-state.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/701-canonical-state.md). --- ## What ZABAL Gamez is **Not a generic hackathon.** It is a Farcaster-creator onboarding event for the ZAO ecosystem. Bring talented Farcaster builders together, give them deep context on everything the ZAO is building, let them ship something with a ZAO mentor as embedded teammate, and have them earn governance during the event itself. **Three months.** - **June - workshop month.** Builders across the ecosystem record one ~30-min session each on tools they have built. The whole library lands in one Magnetiq portal. Watchable live or after. - **July - open build-a-thon.** Anyone with the chops ships a build for ZABAL, ZAO, or WaveWarZ. **The build IS the application.** Live URL + open-source repo + 60s demo + cast on `/zabal`. Adopt a started ZAO project from the list below, or build from scratch with this context. - **August - the Finals.** The strongest July builds get curated in. Each finalist pairs with a ZAO mentor as embedded teammate for a 24h build + 24h promote + 24h ZAO governance vote + live reveal stream. **Every finalist wins** - the competition is in getting selected, the Finals are a collaboration. **Two surfaces:** - **Magnetiq portal** (Tyler Stambaugh's platform) - workshop library, entry/onboarding, polls, UGC submissions. - **This Farcaster mini app** (zabalgamez.com) - explainer and front door. - **Entry:** collect the Zabal connector NFT on Magnetiq. The connector is the anchor magnet - other ZAO magnets are side channels off it. Collecting it auto-drops the road-to-ZAOstock entry. **Prize:** $500 USDC pool, tiered. Every finalist who ships gets paid. Plus a Hats Protocol role NFT for every finisher (July + August). **Pool sponsor: The ZAO festivals team** - $500 USDC for v0 (Season 1). Looking for more sponsors to grow the v1 prize pool or add support to v0; contact info@thezao.com. --- ## The ZAO ecosystem (brand-by-brand) The umbrella you are building for. Understand which brand your build serves. ### The ZAO (umbrella) - **Full name:** The ZAO (ZTalent Artist Organization). Always written "The ZAO" when standalone. - **What:** Music infrastructure for independent artists using decentralized tools. A guild that teaches indie artists to take back their profit margins, their data, and their IP rights - by learning and building together. - **Tagline:** "Community first, technology second." "Here's how it works - we'll learn it together." - **Audience:** Independent musician, 100-10k monthly listeners, no label, releasing monthly, crypto-curious not crypto-native, owns/controls masters. - **Mission:** Bring the profit margin, the data, and the IP rights back to independent artists. - **Founder:** Zaal Panthaki (@bettercallzaal, FID 19640). BS Electrical Engineering, RIT 2022. Maine-based (Ellsworth area). Background: automation engineer / building automation tech (Jackson Laboratory). 65+ public repos at github.com/bettercallzaal. - **Status:** Live - 100+ member gated Farcaster music community. Founded 2022. Q1 2026 shipped ZAO OS, launched ZABAL, Crypto Magazine feature. - **Proof of work:** ZAO-PALOOZA at NFT NYC 2024 (6-week production, broke even, first member IRL). ZAO-CHELLA at Miami Art Week 2024 (cross-community onchain music). ZAOstock Oct 3 2026 Maine (10 artists, full day + livestream + after-party). - **Sites:** thezao.com (about), zaoos.com (the app, under active development). - **Code:** github.com/bettercallzaal/ZAOOS (MIT). ### ZAO OS - **What:** The platform layer - a gated Farcaster client for ZAO members. - **Stack:** Next.js 16 + Tailwind v4 + Supabase + Neynar + RainbowKit + viem + Base. - **Surfaces:** `/feed`, `/spaces`, `/respect`, `/ecosystem`, `/governance`, `/settings`. - **Reusable modules:** `src/lib/publish/` (10 cross-post platforms), `src/lib/music/`, `src/components/respect/`, `src/components/spaces/`. You don't have write access but can read patterns and replicate SDKs. - **Repo:** github.com/bettercallzaal/ZAOOS. ### $ZABAL + Empire Builder - **What:** Ecosystem token (Base ERC-20) wrapped in an "Empire" on Empire Builder, with leaderboards + boosters. - **Token contract:** `0xbB48f19B0494Ff7C1fE5Dc2032aeEE14312f0b07` on Base. Empire address: `0xe0faa499d6711870211505bd9ae2105206af1462`. - **Multiplier stack:** `totalPoints = pointsWithoutMultiplier * stakingMultiplier * empireMultiplier`. Staking: 2.1x-3.0x via `1 + sqrt(stakeAmount / 250000 SANG)`. Empire: 4.0x-8.6x via boosters. - **API (no auth for reads):** Empire Builder public read endpoints for leaderboards, personal-stats, empires. Docs: empire-builder.gitbook.io/empire-builder-docs. - **Tier stack (V3):** Basic Empire (free, tokenless) = 2 leaderboards / 10 boosters / 250 ranked spots. Ascended Empire (token launch unlocks) = 10 leaderboards / 40 boosters / 500 ranked spots. - **Launched:** 2026-01-01 via Clanker. Co-creators: yerbearserker (Jordan Oram) + Adrian (diviflyy). ### WaveWarZ - **What:** Music-battle prediction markets. Artists battle head-to-head, wallets trade on outcomes, 1% of trade volume goes to the artist, settled on-chain via smart contract (no custody). Snapshot ~2026-05-23: 400+ SOL cumulative volume, hundreds of battles, 40+ artists, ~11 shows/week (5 morning + 5 night Mon-Fri + Sunday-night battles). Current live numbers at wavewarz-intelligence.vercel.app. - **The model proof:** in one early battle, a musician earned ~0.5 SOL in 20 minutes of trade activity alone. Artists earn from engagement, not from streams. - **Top performers (Doc 180 snapshot, dated):** LUI, APORKALYPSE, PROF!T, Kata7yst were the leaders in the snapshot window. Specific stats live on wavewarz-intelligence.vercel.app. - **Status:** v1 LIVE on Solana (Hurric4n3Ike at wavewarz-intelligence.vercel.app). v2 IN BUILD on Base - agentic version Sam is shipping with Arthur (Neynar) reviewing smart contracts. Repo: `~/Documents/wwbase` locally; ZAO research Doc 711. - **Voice:** Loud arena brand - competitive, sports-energy, stats-forward. The deliberate opposite of the warm ZAO-umbrella tone. - **Cross-chain:** WaveWarZ v1 on Solana (Helius free tier for RPC, 1M credits/mo, 10 RPS). v2 on Base (matches ZAO rails). Both surfaces are real ZAO infrastructure now. - **ZABAL Gamez Finals integration:** WaveWarZ-Base is the August Finals voting protocol - each finalist build becomes a battle entry, wallets trade on which wins, smart contract settles placement at T+72h. Respect (The ZAO's soulbound governance signal) has a voice in settlement - exact weight mechanism locked before Finals by Sam + Arthur with the contracts. - **Contact:** X @WaveWarZ (no Farcaster/Discord/Telegram presence). Founders: Hurric4n3Ike + Sam (WaveWarZ-Base co-builder). Arthur (Neynar) on smart contracts for the Base build. ### ZAO Festivals / ZAOstock - **What:** ZAO's IRL festival arm. ZAOstock 2026 is the inaugural festival; ZAO Festivals is the umbrella for future iterations worldwide. - **ZAOstock:** Oct 3 2026, Franklin Street Parklet, Ellsworth Maine. 10 artists (ZAO roster + external bookings - target up to 22 from full roster), full day + livestream + after-party. **14-person team across 4 teams** (Operations, Finance, Design, Music). **172-day build** to Oct 3. Anchor partners: Steve Peer rolodex, Roddy Parklet circle, local Ellsworth venues, Art of Ellsworth, Maine indie press. - **Attendance target:** 500-1,000 people. Free or low-cost ticketing to minimize barrier; potential NFT attendance tokens for memorabilia. - **Format thesis:** A polished music festival FIRST, not a Web3 conference. Anyone attends + enjoys without knowing anything about blockchain. The tech enhances; it doesn't interrupt. Timed against a statewide craft-fair weekend that already draws Maine artists + visitors - rides existing marketing without competing with the craft-fair itself. - **Ops cadence:** Weekly DMAIC retros, `/stock/team` kanban dashboard, `@ZAOstockTeamBot` on Telegram. - **Voice:** "Partiful warmth + Luma competence." First-person, community-rooted. - **Visual:** Maine/local influence - Ellsworth, Art of Ellsworth, Northeast indie. ### ZAO Music (DBA) - **What:** The label arm. Releases tracks via DistroKid + 0xSplits (Base) + BMI without the major-label tax. **Frame externally as "ZAO Music" - NEVER "Web3 record label" or "record label."** Internally framed as "ZAO Artist Support Collective." - **Legal wrapper:** **BetterCallZaal Strategies LLC** is the holding vehicle. DBA "ZAO Music Publishing" registered under it (no new entity cost; ties the collective to the operating consulting entity). - **Stack (locked):** BMI as publisher (one-time $250 LLC fee; BMI collects mechanicals in-house, NO Songtrust needed) + The MLC (free direct registration for US streaming mechanicals, belt-and-suspenders) + DistroKid Musician Plus ($44.99/yr, 100% royalty retention, 24-48h Spotify, unlimited uploads) + 0xSplits on Base for every release. **Skip CD Baby** (acquired by UMG Feb 2026). - **Producer tag:** "thezao.com" - first audio beat of every ZAO Music release. Zero cost branding play, GodCloud produces, DCoop approves. - **Artist contract model:** NO exclusive deals. Per-release participation agreement (90-day termination). Artist keeps 100% master ownership. ZAO Music gets producer tag + publishing admin rights + compilation rights. - **The 25% middleman replacement:** What would've gone to ASCAP/BMI as writer fees instead funds an on-chain multi-sig "ZAO Creator Fund." Net benefit, not a fee. - **First release:** Cipher = #1 (10-artist multi-artist cypher), summer 2026, timed to ZAOstock Oct 3 promo cycle. NO NFT on first release - prove the wallet-payout rails work first, add NFT-per-release starting #2. - **Team:** DCoop (lead music ops), GodCloud (A&R / Drip ambassador / publishing guide), Iman (WaveWarZ Zambia regional lead). - **Voice:** Artist-collective - members making music together, not a label voice. ### COC Concertz - **What:** Virtual concert community - 13+ promoters running streamed shows. - **Stack:** Next.js 16 + Firebase + Cloudinary. - **Surfaces:** `/portal/newsletter`, `/stage`, `/team`. 5 COC Concertz shows produced (COC Concertz #6 going live Sat Jun 13 at Stilo World Spatial). - **Mission:** Give virtual concerts a real home - for the metaverse + streamed shows and the promoters who run them. - **Content pipeline (today, manual):** Record show -> Descript edit -> newsletter builder generates YouTube descriptions (MiniMax AI) -> manual cross-post. Automating the cross-post end is adoptable project #07. - **Recent:** COC Concertz #3 ran March 2026 - metaverse concert with DUO DO, JOSEPH GOATS, STILO WORLD. - **Voice:** Warm, communal, builder-energy - same family as the ZAO umbrella. ### FISHBOWLZ (paused) - **What:** Was audio rooms for music communities. Paused 2026-04-16 - audio-room job is now Juke's (partnership). - **Implication:** Do NOT build "audio rooms for music." Find a different job. FISHBOWLZ failed at the job layer, not the tech layer. ### BetterCallZaal (BCZ) - **What (two things):** (1) Zaal's personal brand + Farcaster mini app at bettercallzaal.com (FID 19640). (2) **BCZ Strategies LLC** - Maine local SMB consulting agency + the legal holding entity for ZAO Music Publishing DBA. Real client work in flight: **Riverside Group** (active), **FarmDrop** (active). - **Stack (personal site):** Pure static HTML, direct push to main = deploy. - **BCZ Strategies job-to-be-done (per Doc 526):** Maine local business with low Google rank, knows they need digital marketing but has been burned by an agency before, owner-operator with under 10 employees. Channels: local Ellsworth/Bar Harbor walk-ins + cold pitch, Maine small-biz Slack/FB groups - NOT Farcaster. - **Win:** Zaal/Zlank won the **Snap category at FarHack 2026** ($1,000 prize). ### Respect + Fractals - **What:** Soulbound, peer-validated, Fibonacci-ranked reputation. Earned in weekly fractal sessions - 6-person groups consensus-rank each other's contribution. Two Respect types: **OG Respect** (ERC-20, one-time grandfathered) + **ZOR** (ERC-1155, weekly consensus, the active mechanism). - **Cadence:** ~90+ weeks running consistently (since August 2024). Mondays 6pm EST + ad-hoc whenever 4+ unplayed members are in the Discord waiting room. - **Distribution:** Fibonacci ranks 1-6 award 110 / 68 / 42 / 26 / 16 / 10 Respect points (2x era - doubled from year 1). - **Bot infrastructure:** `bettercallzaal/fractalbotmarch2026` v2.1, Discord-based (Python 3.10+, discord.py 2.0+), Supabase storage, 52 slash commands. Snapshot integration for proposal + curation voting, onchain auto-submit, Farcaster linking. - **Role tree:** Hats Protocol treeId 226 on **Optimism** (NOT Base - governance roles are on OP; ZABAL Gamez NFTs are on Base, separate Hats deployment). - **Voice:** Ritual, earned, communal. Reputation-with-weight, not gamified-points. - **What it gates:** ZAO governance voting (proposal + curation in fractal sessions), ZABAL Gamez Finals settlement voice (exact weight TBD with WaveWarZ-Base contracts), most ecosystem decisions. Soulbound + illiquid - cannot be sold, transferred, or traded. **During ZABAL Gamez:** up to 1000 Respect points earnable per active participant, with current ZAO holders determining who counts as active (workshop attendance, July submissions, Finals participation, real contribution). **Voter threshold:** 1000+ Respect points = eligible to vote in Finals settlement (threshold may shift as event unfolds). The 1000+ cohort also serves as meta-governance body - can vote 66%+ majority to change the governance system itself. --- ## ZAO ecosystem - the working parts ### Agent stack (LOCKED architecture) Five operating bot surfaces, all running the **Hermes pattern**: spawn the Claude Code CLI as a subprocess, never direct Anthropic API calls. Auth via Claude Code Max plan OAuth (`~/.claude/auth.json`), not via `ANTHROPIC_API_KEY`. System prompt injected per invocation via `--append-system-prompt`. Tool restrictions via `--allowedTools` / `--disallowedTools`. Parse responses via `--output-format json`. **Zero marginal cost, no API billing surprises, stable model quality.** | Surface | Brain | Role | |---------|-------|------| | **ZOE** (`@zaoclaw_bot` on Telegram) | Sonnet (chitchat) + Opus (hard recall) | Concierge - DMs, recall over Bonfire, basic task management | | **Hermes** (PR webhooks only) | Opus (quality-critical) | Coder + Critic dual loop - writes fixes, scores them (target > 80/100 before merge). Allowlist for write paths; npm allowlist + `ignore-scripts=true`. | | **ZAOstock team bot** (`@ZAOstockTeamBot` on Telegram) | Sonnet | Festival ops coordination, weekly DMAIC retros, the cowork action-item tracker | | **Magnetiq bot** | Sonnet | Cross-platform syndication research (Zaal + Tyler dual research stream) | | **AttaBotty** | Sonnet (Opus for stream review) | Twitch + streaming ops, post-stream review | **Secondary brain for low-stakes only:** Ollama `llama3.1:8b` on VPS port `:11434`. Wrapper: `bot/src/zoe/ollama.ts` (`ollamaChat`, `ollamaClassify`, `ollamaHealth`). USE FOR inbox classification, Bonfire entity-class first-pass, audit subagent fact-check. NEVER FOR brand outputs, concierge replies, research sourcing, anything public. **Decommissioned (do NOT reincarnate):** openclaw container + 7-agent squad (workspace nuked 2026-05-05), Composio AO orchestrator (paused), ZOE v2 + Agent Zero migration (skipped - Bonfire eats ZOE's recall role), 10-bot branded fleet (folded into ZOE memory blocks), Hermes-on-Telegram (Hermes runs from PR webhooks only). ### Memory layer - Bonfire ZAO's agent memory partner: **Bonfires** (bonfires.ai). Knowledge graph that ingests cross-platform signals (Farcaster, GitHub, Twitch, ZAO Respect) and produces queryable per-address scores + entity relationships. ZAO has a live bonfire at `zabal.bonfires.ai`. Founded by Joshua.eth / Ryan ("Rskagy" on Telegram, in active ZAO Civilization GC). GitHub org: `NERDDAO` (15+ repos). Genesis NFT minting: 0.1 ETH per bonfire (gates the `$KNOW` token allocation pre-public-launch). SDK: `pip install bonfires`. API base: `tnt-v2.api.bonfires.ai`. Exports kEngrams as Canvas / OWL / Markdown - open standards, no lock-in. ### ZAO repo footprint (65+ public, MIT) The bettercallzaal GitHub org runs ~1 new repo every 6 days. TypeScript dominates (43 repos), Python next (11). Next.js 14-16 / Vercel / Supabase / Neynar is the default stack. Key reusable / referenceable repos: | Repo | What | Reuse value | |------|------|------------| | **ZAOOS** | The main ZAO OS platform (Next.js + Supabase + Neynar). Music-first gated Farcaster client. | Reference patterns for music players, Respect leaderboards, cross-post modules, spaces UI. | | **zabalgames** (this repo) | ZABAL Gamez Season 1 site + docs + Snap + Finals settlement scaffold | The Games surface itself. | | **zlank** | No-code Farcaster Snap builder (zlank.online). 14 block types, polls, multi-page, KV vote tallies. | Make a partner template for any ZAO project; reuse the snap-spec.ts patterns. | | **zaomusicbot** | Discord music bot (discord.js + Lavalink). YouTube/Spotify/SoundCloud/Audius/Bandcamp/Twitch/Vimeo. | Multi-platform music search + queue patterns. Audius integration extractable. | | **ZOUNZ** | Farcaster Music NFT Mini App (React 19, mint.club API, Zora NFT on Base, Attention Markets on Solana, AI music gen + Audius discovery) | Embeddable mini-app for music NFT minting. | | **ZAO-Leaderboard** | Respect Token Leaderboard (Next.js 14 + ethers.js v6 + Airtable + Alchemy RPC) | Reference for any Respect-driven UI. | | **fractalbotmarch2026** | The Discord bot running the weekly fractal sessions (Python + discord.py, Supabase, Snapshot, Hats) | Reference for governance integrations, Hats Protocol bindings, Snapshot voting. | | **bettercallzaalwebsite** | Zaal's personal Farcaster mini-app (pure static HTML) | Reference for the simplest possible Farcaster mini-app pattern. | | **NERDDAO/bonfires-sdk** | Bonfire Python CLI + SDK | Memory + knowledge graph integration for ZAO agents. | Browse the full set at github.com/bettercallzaal - everything is MIT, everything is read-only-friendly. Read patterns; replicate cleanly; don't fork-clone-rebrand wholesale. ### Origin + proof of work ZAO was founded in 2022, started inside another DAO that didn't survive. The remaining builders shut down the parent + refocused on music. The weekly fractal system + Respect token launched ~August 2024 and has run consistently 90+ weeks. ZAO-PALOOZA (NFT NYC 2024) was the first IRL, 6-week production, broke even, first member-IRL contact. ZAO-CHELLA (Miami Art Week 2024) brought multiple onchain-music communities together. WaveWarZ launched on Solana (Hurric4n3Ike + Zaal + Sam) - in one early battle, a musician earned ~0.5 SOL in 20 minutes of trade-activity alone. That moment proved the model: artists earn from engagement, not just streams. Q1 2026 shipped ZAO OS (the platform), launched ZABAL (token, January 1), Crypto Magazine feature. ZAOstock (Oct 3 2026, Maine) is the inaugural festival. --- ## Zabal Data Streams The active sources of raw activity that feed ZABAL Gamez. Each stream keeps three things together - the full raw files, a summary, and the ideas it surfaces - organized chronologically by where it comes from. Everything lands in Bonfire (the ZAO memory layer) so any bot can read it and build on top. Surfaced at zabalgamez.com/streams. **Three layers (reuse the rails the ecosystem already runs on):** 1. **Registry** - `data/data-streams.json`. The source of truth. Each stream declares: id, name, kind, status (live | upcoming | archived), color, summary, ties_to_zabal, links, ideas, a `pull` config (type: `github-content` | `haatz` | `static`), and a raw_dir. 2. **Raw + chronological store** - `data/streams//raw/` holds the full raw captures per stream; `data/streams/timeline.json` is the merged chronological feed across all streams (newest first, deduped by stream + timestamp + title). 3. **Bonfire ingest** - `scripts/pull-data-streams.mjs` fetches each live source, writes raw captures, appends to the timeline, and emits `/tmp/zabal-dispatch-streams-.md`. The existing `scripts/aggregate-dispatches.mjs` merges that dispatch into `data/bonfire-graph.json` (streams land as entities labelled `DataStream` with `FEEDS` edges into ZABAL Gamez), and `scripts/push-to-bonfire.mjs` pushes the graph to the ZABAL Bonfire. ```bash node scripts/pull-data-streams.mjs # pull live + write timeline + emit dispatch node scripts/pull-data-streams.mjs --dry # show what would change, write nothing node scripts/aggregate-dispatches.mjs # merge the dispatch into the graph node scripts/push-to-bonfire.mjs # push the graph to Bonfire ``` **Season 1 streams:** | Stream | Kind | Status | What it feeds | |--------|------|--------|---------------| | BCZ YapZ | interview-archive | live | Zaal's long-form interview show (bczyapz.com, bettercallzaal/bcz-yapz). Already emits `content/bonfire-ingest/` from each transcript - a native Bonfire feeder. Pulled via github-content. | | Farcaster Agentic Bootcamp | bootcamp | archived | Builders Garden + Dev3Pack 2-week program (Mar 30 - Apr 10 2026). The origin thread: fed FarHack, where Zaal/Zlank won the Snap category ($1,000), funding ZAOstock. | | ZAO Festivals $500 Bounty | bounty | live | The Season 1 prize pool ($500 USDC v0) funded by the ZAO festivals team. Grow it: info@thezao.com. | | Farcaster Batches | protocol-feature | upcoming | An upcoming Farcaster protocol feature, being introduced on GM Farcaster X spaces. A new rail to design ZABAL Gamez builds around. | | ZABAL Gamez Workshops | workshop | live | June workshop month - ~30-min builder sessions landing in the Magnetiq portal. Raw recordings + transcripts + summaries are the richest stream. | Adding a stream: drop it in `data/data-streams.json`, run the pull script. Live sources (github-content, haatz) pull automatically; static sources keep curated timeline entries. The github-content + haatz pulls need outbound access to api.github.com / raw.githubusercontent.com / haatz.quilibrium.com - in a sandbox where those are blocked the script logs the miss and continues, still emitting the registry-derived Bonfire entities. --- ## Mini app surfaces + activity The site is a Farcaster Mini App. `assets/miniapp.js` exposes `window.ZABAL`: `getUser`, `viewProfile`, `viewCast`, `share({platform,text,url})`, `track`, `addApp`, `openNewTab`. It auto-injects a profile chip into the nav inside a Mini App, and casts post into `/zabal` with the page embedded. - **/streams** - Zabal Data Streams (see above) with Cast/Share/Add buttons. - **/graph** - searches the Bonfire knowledge graph (`data/bonfire-graph.json`), people + tools + brands + agents + data streams with their edges. - **/leaderboard** - ranks builders by social-action points; also published in Empire Builder `apiLeaderboard` format at `/api/leaderboard`. - **/share** - share-extension target (manifest `castShareUrl`); receives a shared cast and routes it back to the data-streams story. Backend (zero-dep Vercel **edge** functions, no build step): `POST /api/track` (Quick Auth JWT verified server-side -> records cast/share/signup to Vercel KV), `GET /api/activity` (presence feed), `GET /api/leaderboard`, `POST /api/webhook` (manifest `webhookUrl`, stores notification tokens), `POST /api/notify` (admin sender, `NOTIFY_SECRET`). Privacy: only deliberate social actions are recorded, never page views. Env: `KV_REST_API_URL`, `KV_REST_API_TOKEN`, `NOTIFY_SECRET`. Full notes in `api/README.md`. --- ## Tech stack + rails (the defaults) ``` Frontend: Next.js 16 (App Router, Turbopack) Tailwind v4 Farcaster mini-app SDK (@farcaster/miniapp-sdk via esm.sh CDN) wagmi + viem (EVM client) Coinbase Smart Wallet Backend: Next.js API routes (serverless on Vercel) Supabase (Postgres + Auth + Storage) HAATZ (Farcaster reads, free, no key, haatz.quilibrium.com) Neynar (Farcaster writes + signer + trending/for-you only) Onchain: Base (chainId 8453) - primary ZAO chain Solana - only for WaveWarZ reads (Helius free tier) Privy (agent wallets, pre-funded) Streaming / Live: Twitch (your account) StreamElements (free browser overlays) ``` ### Key APIs | Service | What for | Auth | Cost | |---------|----------|------|------| | Empire Builder | Token leaderboards, booster mechanics | X-API-Key (reads free) | Free reads | | HAATZ | Farcaster reads (user, feed, search, bulk) | None | Free, public, Neynar-v2 compatible (haatz.quilibrium.com by Cassie / Quilibrium) | | Neynar | Farcaster writes (cast, signer, follow) + trending feeds | API key | Free dev tier - use ONLY for writes + endpoints HAATZ doesn't cover | | Hats Protocol | Onchain roles on Base | Hats SDK | Gas only (~$5 setup) | | Bonfire | Reputation graph, social signals | SDK / DM relay | Free | | EAS (Base) | Onchain attestations | EAS SDK | Free offchain, gas onchain | | Hypersub (Fabric STP) | Subscription NFTs | Hypersub UI/contracts | ~5% protocol fee | | 0xSplits | Onchain revenue splits | Splits SDK | Gas only | | Coinflow | Fiat to USDC checkout | Merchant key | Coinflow rev share | | Zora | Content coins / creator coins | Zora SDK | 50% trade + LP fee to creator | | Clanker | AI agent token launcher on Farcaster | Cast tag `@clanker` | 0.2% trade fee in WETH; 100% creator fees | | Privy | Embedded + agent wallets | App ID + secret | Free 0-499 MAU | ### Hats contract on Base `0x3bc1A0Ad72417f2d411118085256fC53CBdDd137` ### Identity model Every ZAO member has a Farcaster account with at least one verified Ethereum address (Base preferred). Verified addr is the default "who" identifier - sybil-resistant. Lookup via Neynar: ```ts import { NeynarAPIClient } from '@neynar/nodejs-sdk'; const client = new NeynarAPIClient(process.env.NEYNAR_API_KEY); const user = await client.lookupUserByVerifiedAddress({ address }); ``` --- ## Build paths ### Path 1 - Adopt a started ZAO project A curated list of started / in-progress ZAO projects builders can pick up and run with. Adopt one and ship it forward. (List below is a candidate list pending final confirmation - check Doc 701 Part 4 for current.) 1. **Songjam leaderboard migration** - move the leaderboard off the deprecated X scraper onto an Empire Builder API leaderboard. Frees Adam from scraper maintenance. Spec: Doc 654. 2. **POIDH bounty leaderboard on Empire Builder** - pulls on-chain POIDH bounty submissions; counts unique submitters across all ZABAL bounties. One contract added 2026-05-16; second pending. Spec: Doc 654 + Doc 626. 3. **zlank.online Empire daily-stats Snap template** - one-click cast "Today's Empire Builder Stats." Footy app is the reference. Spec: Doc 654 + Doc 505 + Doc 527. 4. **Twitch -> Empire Builder stream score feed** - StreamElements WebSocket events feed an apiLeaderboard. Spec: Doc 627 + Doc 628. 5. **New ZOE skill(s)** - extend the ZOE concierge bot (Telegram `@zaoclaw_bot`). Backend mirrors the Hermes runtime pattern. Spec: Doc 601 + Doc 600. 6. **The `/zabal` Farcaster mini app itself** - this repo. Extend the workshops calendar, the submissions board, the connector NFT flow. 7. **COC Concertz content-pipeline automation** - record show -> Descript -> newsletter builder generates YouTube descriptions (MiniMax AI) -> manual cross-post. Automate the cross-post. 8. **Streaming auto-clip flywheel** - 24h of stream -> 150+ short clips for TikTok/Reels/YouTube/Farcaster. Spec: Doc 629. ### Path 2 - Build from scratch Build anything that helps the ZAO community. Tie it to existing ZAO rails (Empire Builder, Farcaster, Hats, Bonfire, EAS, Coinflow, Hypersub). Composability is the point - do not reinvent identity, leaderboards, or attestations. Suggestion sparks (non-binding): - A Farcaster mini app for [some specific job-to-be-done in the ZAO ecosystem] - A bot that ingests [some signal] and posts to a ZAO surface - A leaderboard / dashboard for [some metric] - A content-pipeline tool that automates [some manual step] - A wallet / agent flow that [does something onchain] ### What "good" looks like (judging rubric) ZAO members with Respect vote 1-person-1-vote on which build best serves the ecosystem. Implicit criteria: 1. **Does it work?** Deployed, demoable, no crashes. Voters click your link. 2. **Is it ZAO-native?** Plugs into real rails (ZABAL, Empire, Farcaster, Hats, Bonfire, EAS, Coinflow, Hypersub). More rails wired = more votes. 3. **Would I use this?** ZABAL holders vote for things they would open again next week. 4. **Did you ship something thoughtful in 24h?** Velocity beats polish. Voters do NOT care about: how elegant your code is, which AI tool you used, how many features you crammed in, how much you streamed. --- ## Brand guidelines (NON-NEGOTIABLE) ### Naming glossary - ALWAYS use these exact spellings | Correct | Wrong | |---------|-------| | WaveWarZ | Wave Wars, Wavewarz | | COC Concertz | COC Concerts, CocConcertz | | The ZAO | the Zao, Zao | | BetterCallZaal | Bettercallzaal, Better Call Zaal | | Joseph Goats | Jose Goats, Jose | | Huottoja | Waha | | SongJam | Songjam | | ZABAL | Zabal, zabal | | SANG | Sang | | ZOE | Zoe | | ZOLs | Zols, ZOL | | FISHBOWLZ | Fishbowlz | | Stilo World | StiloWorld | | Thy Revolution | The Revolution | | ArDrive | Ardrive | | ZAOstock | Zaostock, ZAO Stock | | ZAO Music | ZAO music, ZaoMusic | | ZAO DEVZ | ZAO Devs, ZAOdevz | ### Writing rules - **NEVER use emojis** - not in code, commits, casts, or UI copy. - **NEVER use em dashes** - use hyphens instead. - **NEVER use decorative Unicode** - no checkmarks, warning triangles, play buttons as text. Use labels like `[MUSIC]`, `OVERDUE`, `DONE`, `IN PROGRESS`. - Plain hyphens or numbered lists for bullets. ### Brand colors (ZAO default palette) ```css :root { --bg: #070709; /* deep almost-black */ --surface: #111115; --surface-2: #16161c; --orange: #ff6b35; /* primary accent */ --cyan: #00e5ff; /* secondary accent */ --gold: #f5c842; /* highlight */ --pink: #ff3d6e; /* alt highlight */ --zabal: #a78bfa; /* ZABAL purple */ --poidh-blue: #2a81d5; --text: #e4e2dd; --text-muted: #8a8895; --text-dim: #4e4c57; --border: #1f1e26; --gradient-main: linear-gradient(135deg, #ff6b35, #ff3d6e, #00e5ff); --gradient-zabal: linear-gradient(135deg, #a78bfa, #00e5ff); } ``` ### Fonts - Headings: **Syne** (700-800) - Body: **Outfit** (300-600) - Mono / numbers: **JetBrains Mono** (400-500) ### Layout - Mobile-first - test at 424px wide (Farcaster mini-app viewport). - Dark background by default. - `8px` button radius. - No popups, no aggressive modals, no autoplay. ### Tone - Direct, not corporate. - Confident but humble. - No marketing fluff ("revolutionary", "game-changing", "transform your X" - avoid). - Write like Zaal - read bettercallzaal.com or his recent /zabal casts for tone calibration. --- ## Submission bar (hit ALL four by T+24h) 1. **Live deployed URL** (working, not 404). Vercel free tier is fine. 2. **Public GitHub repo link** (MIT or similar permissive). Verifiable empty git log at T+0. 3. **60-second demo video link** (Loom, YouTube, or self-hosted). Show the thing working. 4. **Cast on `/zabal` channel** announcing your ship. Tag `@bettercallzaal`. Plus your declared **show-your-work visibility mode** must be active during the build window: - Mode 1: live Twitch stream (archive available) - Mode 2: recorded screen sessions uploaded within 1h - Mode 3: public AI prompt logs every 1-2h - Mode 4: frequent build casts every 1-2h Miss the bar OR fail visibility = no submission. --- ## Voting + judging The August Finals placement is decided by the **WaveWarZ-Base prediction-market protocol** (Doc 720). Each finalist build becomes a battle entry on WaveWarZ-Base. Wallets trade on which build wins. Smart contract settles at T+72h based on volume + win rate per finalist. - **Voter set:** open market - anyone with a Base wallet can trade. PLUS Respect-earning ZAO members have a governance voice in settlement (Respect is soulbound + illiquid - cannot be sold). Exact Respect-weight mechanism in the settlement formula TBD - locked before Finals by Sam + Arthur with the contracts. - **Window:** T+0 to T+72h (the whole Finals window is the trade window; market settles at the end). - **Output:** the WaveWarZ smart contract distributes the prize ($500 USDC pool maps to placement tiers per Doc 701 Part 5) + the 1% trade cut per WaveWarZ economics (flows to the builder forever, post-Finals too) + the Hats Protocol Finisher / Champion NFTs are minted on-chain in the settlement transaction. - **Why the shift:** real economic signal beats a 1p1v poll for "would I actually use this build." Plus the Finals become the V1 launch event for the WaveWarZ-Base agentic build that Sam + Arthur are shipping. - **Fallback:** if WaveWarZ-Base isn't mainnet-ready by August, revert to the original Doc 701 model: Respect-earning 1p1v vote, WaveWarZ on Solana as parallel signal (Doc 646 framing). Judge agents (per Doc 723d + 720): autonomous agents read each finalist's deployed URL + repo + demo, score against the rubric (does it work / is it ZAO-native / would I use this / shipped in 24h), get paid in x402 micropayments. Their scores feed the market as a "fundamental" but do not override it. --- ## Don't build these (anti-patterns) | Don't build | Why | Build instead | |-------------|-----|---------------| | Audio rooms for music communities | FISHBOWLZ tried, paused 2026-04-16. The job belongs to Juke (partnership). Don't compete. | Tools that integrate with Juke, OR a different live-audio job (e.g. agent-only voice spaces). | | Your own Farcaster identity layer | Sybil-resistance is already solved by Neynar verified addresses + $25 stake + linked X/phone/GitHub. | Use Neynar's `lookupUserByVerifiedAddress`. Build on top, not under. | | Your own leaderboard infrastructure | Empire Builder has it. apiLeaderboards pattern is open. | Build a leaderboard that publishes JSON; Empire Builder pulls. Free distribution. | | Token-weighted governance for ZAO matters | ZAO governance is Respect-based (soulbound, peer-validated). Tokens get markets (WaveWarZ Finals), not votes. | Token-weighted markets for prediction / discovery; Respect 1p1v for governance / contribution scoring. | | ZK / privacy-focused builds with no ZAO use case | ZAO is open-by-default - all submissions public, all reps onchain, all builds open-source. ZK adds complexity with no member demand. | Public-by-default flows. Optional opt-in privacy at the user level only if a specific job needs it. | | Token launches inside the submission (without disclosure) | Doc 646: token mechanic is opt-in, must be disclosed at onboarding. Surprise token launches in a build = DQ risk. | Disclose at T-3 onboarding. Use Clanker via Empire Builder UI; volume becomes parallel signal. | | Auth layers that don't accept Farcaster sign-in | Every ZAO member already has a Farcaster identity. Adding email signup = friction with no win. | Sign In With Farcaster (SIWF) + Quick Auth via Neynar / Privy. | | Polished-but-disconnected UI demos | Voters click your link. If it's beautiful but doesn't talk to any real ZAO rail, you don't place. | Plug into Empire Builder, Hats, Bonfire, EAS, Coinflow, Hypersub. More rails wired = more votes. | --- ## Code snippets - the rails Copy-paste-friendly examples for the most-used ZAO rails. Read the linked docs for full SDK depth. ### HAATZ - look up a user by FID (Farcaster identity, free, no key) HAATZ is a free public Neynar-v2-compatible API by Cassandra Heart (Cassie) / Quilibrium. Use for all Farcaster READS - 70-90% cost reduction vs Neynar. Source: ZAO OS research Doc 2027 (farcaster/2027-haatz-farcaster-identity-api). ```ts // Bulk user lookup by FID(s) - the most common read pattern const res = await fetch( `https://haatz.quilibrium.com/v2/farcaster/user/bulk?fids=${fid}`, { signal: AbortSignal.timeout(5000) } ); const data = await res.json(); const user = data.users[0]; // user.fid, user.username, user.display_name, user.pfp_url, user.verified_addresses ``` ### HAATZ + Neynar two-tier failover pattern (production-tested in ZABAL Live Hub) For reads where uptime matters, fall back to Neynar if HAATZ times out: ```ts async function getFarcasterUser(fid: number) { try { const res = await fetch( `https://haatz.quilibrium.com/v2/farcaster/user/bulk?fids=${fid}`, { signal: AbortSignal.timeout(5000) } ); if (res.ok) return (await res.json()).users[0]; } catch (e) { console.warn('[fc] haatz miss, falling back to Neynar', e); } // Failover to Neynar (paid) const { NeynarAPIClient } = await import('@neynar/nodejs-sdk'); const neynar = new NeynarAPIClient(process.env.NEYNAR_API_KEY); return await neynar.lookupUserByFid({ fid }); } ``` When to use Neynar instead of HAATZ: - Trending / for-you feed endpoints (HAATZ times out on these) - Cast posting + signer + follow + any write operation - Webhook subscriptions Live examples of HAATZ usage in our codebase: - ZABAL Live Hub `api/calculate-vote-power.js` lines 43 + 77 (user casts + bulk lookup) - ZABAL Live Hub `api/empire-leaderboard.js` line 53 (FID -> verified addresses) - ZABAL Live Hub `api/neynar.js` (generic proxy fronting HAATZ for v2 read endpoints) Docs: HAATZ has no formal docs - use Neynar v2 docs (https://docs.neynar.com) since the API surface is compatible. ### Empire Builder - publish a JSON leaderboard ```ts // Your endpoint serves an array Empire Builder pulls hourly: // GET https://yourapp.com/leaderboard // returns: // [{ "address": "0xabc...", "score": 42 }, ...] // Then register the URL once via the Empire Builder dashboard: // apiLeaderboards.add({ // empire: '0xZABAL_or_your_empire', // name: 'my-leaderboard', // url: 'https://yourapp.com/leaderboard', // refreshMinutes: 60 // }) ``` Docs: https://empire-builder.gitbook.io/empire-builder-docs ### Hats Protocol - mint a role NFT on Base ```ts import { HatsClient } from '@hatsprotocol/sdk-v1-core'; import { createPublicClient, createWalletClient, http } from 'viem'; import { base } from 'viem/chains'; const hats = new HatsClient({ chainId: 8453, publicClient: createPublicClient({ chain: base, transport: http() }), walletClient: createWalletClient({ chain: base, transport: http(), account: yourAccount }), }); // Mint an existing Hat (e.g. "ZABAL Gamez Finisher") to a wearer await hats.mintHat({ account: yourAccount, hatId, wearer: '0x...' }); ``` Hats contract on Base: `0x3bc1A0Ad72417f2d411118085256fC53CBdDd137` ### Clanker - launch a token via Farcaster cast ``` Cast on Farcaster: @clanker launch $ optional: include image attachment Clanker mints ERC-20 on Base, pairs WETH, locks LP until 2100. v4 charges 0.2% trading fee in WETH; 100% creator-collected fees go to the caster's wallet. Zero gas cost to the caster. ``` Docs: https://clanker.gitbook.io/clanker-documentation ### EAS (Ethereum Attestation Service) - sign an attestation on Base ```ts import { EAS, SchemaEncoder } from '@ethereum-attestation-service/eas-sdk'; const eas = new EAS('0x4200000000000000000000000000000000000021'); // Base EAS eas.connect(signer); const schemaUid = '0x...your-schema-uid'; const encoder = new SchemaEncoder('string event,uint256 timestamp'); const data = encoder.encodeData([ { name: 'event', type: 'string', value: 'zabal-games-finalist' }, { name: 'timestamp', type: 'uint256', value: Date.now() }, ]); const tx = await eas.attest({ schema: schemaUid, data: { recipient: '0x...', expirationTime: 0n, revocable: true, data }, }); ``` Docs: https://docs.attest.org ### Farcaster cast composer (open from a Snap or mini app) ```ts import { sdk } from '@farcaster/miniapp-sdk'; await sdk.actions.composeCast({ text: 'Just shipped at ZABAL Gamez', embeds: ['https://zabalgamez.com/lead'], channelKey: 'zabal', }); ``` Docs: https://miniapps.farcaster.xyz ### Hypersub (Fabric STP) - check if an address has an active subscription ```ts import { createPublicClient, http } from 'viem'; import { base } from 'viem/chains'; const client = createPublicClient({ chain: base, transport: http() }); const balance = await client.readContract({ address: '0xYOUR_HYPERSUB_CONTRACT', abi: hypersubAbi, functionName: 'balanceOf', args: ['0xWALLET'], }); // > 0n means active subscription ``` Docs: https://hypersub.xyz ### Coinflow - generate a fiat-to-USDC checkout link ```ts const checkoutUrl = `https://app.coinflow.cash/checkout/${MERCHANT_ID}` + `?amount=100` + `&subtotal=100` + `&token=USDC` + `&blockchain=base` + `&webhookUrl=${encodeURIComponent('https://yourapp.com/webhook')}`; ``` Docs: https://docs.coinflow.cash ### Bonfire - query reputation score for an address ```ts // Bonfire SDK or DM relay (per Doc 544 in ZAO research). // Bonfire ingests Farcaster activity + GitHub + Twitch + ZAO Respect // and produces a per-address score. const score = await bonfire.getScore({ address: '0x...' }); // score.tier, score.attestations, score.lastUpdated ``` --- ## Building Farcaster Snaps (what works in 2026) If your build involves a Farcaster Snap, save yourself the trap I fell into when building this site's snap endpoint. **The Frames v2 protocol (`fc:frame:button:1`, `fc:frame:button:2`, etc) is deprecated.** Current Farcaster clients ignore those metas and render the cast as a plain link card. What works today: | Pattern | When to use | How | |---------|-------------|-----| | **`fc:miniapp` meta tag** (single JSON in one meta) | Any page you want to embed as a Farcaster Mini App. Cast unfurl shows a "Sign up" launch button -> opens your URL in Farcaster's webview. | Add `` to your HTML head. Also add `fc:frame` with the same JSON for back-compat. | | **Snap JSON via content negotiation** | In-cast interactive UI (poll buttons, forms, multi-page flow) without opening a webview. | Server responds with `Content-Type: application/vnd.farcaster.snap+json` when the request `Accept` header includes the same MIME type. Body = `@farcaster/snap` v2.0 schema: `{version: "2.0", theme: {...}, ui: {root, elements: {...}}}`. Plus `Vary: Accept` header so the CDN caches per-format. | | **zlank.online template (no-code)** | Fastest path - if you can describe the Snap as blocks (header, poll, link, share, chart), you do not need to write code. | Make or pick a template at `zlank.online/builder`, publish, get `/s/[uuid]` URL. Cast that URL. Farcaster auto-recognizes zlank-hosted Snaps. | **Critical detail:** Farcaster's caster does NOT probe arbitrary URLs with `Accept: application/vnd.farcaster.snap+json`. Self-hosted Snaps at custom paths (e.g. `yoursite.com/api/snap/foo`) fall back to the OG link card unless the URL is on a known Snap host's allowlist. **zlank-hosted Snaps work because they sit at `zlank.online/s/[uuid]` - a recognized pattern.** For self-hosted in-cast Snaps, use `fc:miniapp` + launch the mini app instead, OR host through zlank. ### Snap-spec quick reference - **Spec versions:** `1.0` (legacy) and `2.0` (current). Use `2.0`. - **MEDIA_TYPE:** `application/vnd.farcaster.snap+json` - **Max elements:** 64 total in `ui.elements`, max 7 children on root, max 6 per other container, max 4 levels of nesting depth - **Components (16):** badge, button, icon, image, item, progress, separator, text, bar_chart, cell_grid, stack, item_group, input, slider, switch, toggle_group - **Actions (10):** `submit` (POST back to your server), `open_url` (external), `open_snap` (inline), `open_mini_app`, `view_cast`, `view_profile`, `compose_cast`, `view_token`, `send_token`, `swap_token` - **JFS signature verification:** use `@farcaster/snap/server`'s `parseRequest(body)` for production. Skips replay + signature + origin checks. Optional `skipJFSVerification: true` for dev. - **Submit POST payload schema:** `{fid?, inputs: Record, timestamp, audience, user: {fid}, surface: {type: "cast", cast: {hash, author: {fid}}} | {type: "standalone"}}` - **Spec source:** `@farcaster/snap` npm package, see `node_modules/@farcaster/snap/llms.txt` for the full schema docs. ### Hosting Snaps Two real options: 1. **Zlank template (recommended for most cases).** Open-source no-code builder, free hosting at `zlank.online/s/[uuid]`. 14 block types, polls, charts, multi-page, KV-backed vote tallies. Submit a partner template to `bettercallzaal/zlank` to make your Snap reusable by others. 2. **Self-host as a serverless function.** Use Vercel Edge functions (no SDK install needed for the basic shape) or Node functions (install `@farcaster/snap` for `parseRequest` JFS verification). Return Snap JSON on snap+json Accept, HTML fallback otherwise. Add `Vary: Accept` for CDN sanity. See `zabalgamez.com/docs/snap-design.md` for the working pattern + the `/api/snap/signup` reference implementation. ### Don't - Don't ship `fc:frame:button:1` style Frames v2 metas - deprecated, ignored. - Don't hand-roll snap JSON without validating against the SDK schema (max-element, max-depth, max-children traps). - Don't forget `Vary: Accept` when content-negotiating, or the CDN serves the wrong body to half your visitors. - Don't ship without a fallback HTML for browsers + older Farcaster clients - your Snap URL also needs to be human-loadable. --- ## What "good" looks like (quality bar examples) Voters apply the rubric from Part "What good looks like" (above). Concretely: - **Plugs into 3+ ZAO rails:** e.g. uses Neynar for identity + Empire Builder for leaderboard + Hats for credentialing. One rail = thin build. Three or more = ecosystem-native. - **Demoable in 60 seconds:** open URL, see something work, do one action, see a result. Voters click your link first; if your demo is unclear they bounce. - **Has a real first-use:** "today, I can use this to ." Not "imagine if..." or "you could use this for...". - **No emojis, no em dashes, hits the brand palette:** ZAO-native voters spot off-brand builds instantly. The palette + Syne/Outfit fonts + the naming glossary aren't aesthetic preferences - they're a signal of "you actually read the context." - **Open-source MIT, working CI:** the repo runs out-of-the-box. Voters who clone shouldn't hit npm errors. - **Posted on /zabal with the four-thing submission bar:** missing one = no submission, no votes. Counter-examples that lose votes: - Beautiful landing page, broken demo, "coming soon" buttons. - Reinvents identity / leaderboard / governance instead of using the rails. - Heavy crypto-bro framing ("revolutionary onchain", "tokenize everything"). - Solana-only when there is no WaveWarZ-related reason. --- ## Look at these (concrete past builds - the quality bar in code) Real ZAO ecosystem builds you can read for patterns + UI + integration choices. All open-source MIT, all browseable on GitHub. | Build | What | Why look | |-------|------|----------| | **zlank** (zlank.online) | No-code Farcaster Snap builder. 14 block types, polls, multi-page, KV vote tallies. Built by Zaal + kmac.eth. **Won FarHack 2026 Snap category ($1,000).** | The current-best reference for working Farcaster Snap implementations - content negotiation, JFS verification, template patterns. Source: `bettercallzaal/zlank`. | | **ZAOOS feed module** | Music-first gated Farcaster client. Discord-style chat with inline music players, quote casts, reactions, music queue sidebar. | The simplest case of "real ZAO rails composed cleanly" - Neynar + Supabase + Tailwind + music infra in one cohesive flow. Source: `bettercallzaal/ZAOOS`. | | **Hermes Coder/Critic** | Dual-bot loop that takes a PR webhook -> Coder writes a fix -> Critic scores it (target > 80/100 before merge). Claude Code CLI subprocess pattern. | The agent pattern ZAO has actually proven in production - cost-stable, quality-gated, secret-safe. Source: `bot/src/hermes/` on the VPS. | | **fractalbotmarch2026** | The Discord bot running the weekly fractal sessions. 52 slash commands. Snapshot integration, Hats Protocol bindings, on-chain auto-submit, Supabase storage. | The reference for any governance-integration build. How to bind Hats + Snapshot + an off-platform UI (Discord) coherently. Source: `bettercallzaal/fractalbotmarch2026`. | | **ZAO-Leaderboard** | Respect Token Leaderboard, Next.js 14 + ethers.js v6 + Airtable + Alchemy RPC. | Reference for the simplest possible "read tokens, render a table, deploy" build. Good starting point if you are doing project #01 (Songjam migration) or #02 (POIDH leaderboard). Source: `bettercallzaal/ZAO-Leaderboard`. | | **ZOUNZ** | Farcaster Music NFT Mini App. React 19 + Vite + Express + mint.club API + Farcaster SDK + Zora NFT mint on Base + Attention Markets on Solana + AI music gen + Audius discovery. | Cross-chain mini app reference. How to do Base + Solana in one product without it feeling Frankenstein. Source: `bettercallzaal/ZOUNZ`. | | **bettercallzaal.com** | Zaal's personal Farcaster mini app, pure static HTML, no build step, push-to-deploy. | The simplest possible Farcaster mini app pattern. If your build is "explainer + form + Farcaster mini-app embed," start here. Source: `bettercallzaal/bettercallzaalwebsite`. | | **This repo (zabalgames)** | The site you are reading. Static HTML + Vercel functions + a Snap endpoint + JSON-driven dynamic content + Farcaster Mini App manifest. | Reference for a hybrid static + serverless + Snap deploy on Vercel. Source: `ZAODEVZ/zabalgames`. | | **NERDDAO/bonfires-sdk** | Bonfire Python CLI + SDK. `pip install bonfires`. | Reference for integrating Bonfire memory into any ZAO bot. Source: `github.com/NERDDAO/bonfires-sdk`. | The pattern: every one of these is **focused on one job, plugged into 2-4 ZAO rails, ships small, ships open.** That is the bar. --- ## Tools the ZAO actually uses (recurring stack) Not just for ZABAL Gamez builds - this is what's in production across the ZAO ecosystem. If a tool is on this list, the team has either built with it or paid for it, so pick from here over inventing a new dep. | Tool | Used for | Cost | |------|----------|------| | **DistroKid** (Musician Plus) | DSP distribution for ZAO Music releases | $44.99/yr | | **BMI** | Publisher + mechanicals collection | $250 one-time LLC | | **The MLC** | US streaming mechanicals (free belt-and-suspenders to BMI) | $0 | | **0xSplits** | Onchain revenue splits on Base | Gas only | | **Descript** | Audio + video editing (COC Concertz content pipeline) | Subscription | | **MiniMax AI** | YouTube description auto-generation (COC pipeline) | Per-use | | **StreamElements** | Twitch overlays + WebSocket event stream | Free | | **Snapshot.org** | Off-chain governance voting | Free | | **Hats Protocol** | Onchain role NFTs (Optimism for ZAO governance treeId 226; Base for ZABAL Gamez NFTs) | Gas only | | **Neynar** | Farcaster reads + signers + identity | Free dev tier | | **Privy** | Embedded + agent wallets | Free 0-499 MAU | | **Coinflow** | Fiat -> USDC checkout | Coinflow rev share | | **Helius** | Solana RPC for WaveWarZ reads | Free tier (1M credits/mo, 10 RPS) | | **Alchemy** | Base RPC | Free tier | | **Vercel** | Hosting + edge / Node functions | Free tier handles current scale | | **Supabase** | Postgres + Auth + Storage (default DB across ZAO stack) | Free tier | | **Airtable** | Lightweight ops DB (early ZAO-Leaderboard) | Free tier (legacy) | | **Lavalink** | Discord music streaming (zaomusicbot) | Self-hosted | | **mint.club** | Bonding-curve token launcher (ZOUNZ) | Per-launch fee | | **Zora** | Content coins / creator coins / NFT minting on Base | 50% trade + LP fee to creator | | **Hypersub** (Fabric STP) | Subscription NFTs on Base | ~5% protocol fee | | **Bonfires** | Knowledge-graph agent memory | 0.1 ETH Genesis NFT per bonfire | | **Clanker** | AI-agent token launcher on Farcaster (Base) | 0.2% trade fee, 100% creator fees | | **Lu.ma** | Event + workshop calendars | Free | | **Cal.com** | Slot booking (workshop scheduling) | Free / Self-hosted | | **Formspree** | Form submissions (current launch-form backend) | Free tier | | **Magnetiq** | Portal / opt-in / workshop library (Tyler Stambaugh's platform) | Per-customer | | **GitHub** | Code + issues + Actions | Free for public | | **Telegram** | Team coordination + ZOE + ZAOstockTeamBot home | Free | | **Farcaster** | Social + protocol identity + Snaps + mini apps | Free | | **Discord** | Fractal sessions + community channel | Free | | **Twitch** | Live streaming for workshops + builders | Free | | **YouTube** | Long-form video archive | Free | | **Paragraph** | Newsletter distribution | Free | | **Claude Code Max plan** | Hermes + ZOE brain via subprocess OAuth | $200/mo flat | | **Ollama** | Local low-stakes inference (`llama3.1:8b` on VPS port 11434) | Self-hosted | If your build needs something not on this list, that is a real decision - check llms.txt's anti-patterns + ask before adding another dep. --- ## After you ship - amplification + outreach The build is the application; shipping it is the start of the conversation, not the end. ZAO accounts amplify all valid submissions during the promote window (T+24h to T+48h in the August Finals; the equivalent post-cast window in July). Beyond that auto-amplification, the seeded-asks playbook below converts. ### ZAO accounts that auto-amplify - **@bettercallzaal** on Farcaster (Zaal's personal, the host) - reposts and quotes shipped casts - **/zabal Farcaster channel** - the home; all shipped casts land here - **/zao Farcaster channel** - the broader ZAO community feed - **COC Concertz** - virtual-concert promoter audience (13+ promoters) - **@ZAOstockTeamBot** on Telegram - the team chat that runs ZAOstock ops - **@WaveWarZ** on X - the prediction-market audience (Hurric4n3Ike runs this) - **The ZAO newsletter** - published via Paragraph, distributes to subscribers + Farcaster ### Named-targets - who to DM by topic Send a personal DM after shipping. Each one converts a built thing into eyeballs. | Target | Best for | DM angle | |--------|----------|----------| | **Hurric4n3Ike** (X @hurric4n3ike / Farcaster) | WaveWarZ-related builds, music-prediction, Solana | Reposts to his active WaveWarZ arenas, very engaged with builders | | **Jordan Oram / yerbearzerker** | Empire Builder builds, token mechanics, leaderboards | He runs Empire Builder, will boost any Empire-API ship | | **Adrian / diviflyy** | Empire Builder smart-contract / SDK builds | The lead engineer; technical depth, will surface to Jordan | | **Sam** (WaveWarZ-Base co-builder) | WaveWarZ-Base, agentic builds, general ZAO | Core team, multi-surface amplifier | | **Arthur (Neynar)** | Smart contracts on Base, EVM patterns | Will route through Neynar circles + give technical feedback | | **Tyler Stambaugh / Magnetiq** | Magnetiq-portal builds, retention plays, opt-in data | Magnetiq audience + the retention-marketing crowd | | **Adam (SongJam)** | Music-engagement, leaderboards, SongJam integrations | Music-creator audience + $SANG holders | | **kmac.eth** | Snap builds, zlank templates, Farcaster mini-app patterns | The Snap-builder audience | | **Iman** | ZAO Music team builds, ORDAO governance, ZOE skills | Internal ZAO Music distribution | ### DM templates (personalize the [bracketed] bits) **Generic ship cast follow-up:** ``` Yo [name] - just shipped [thing] for ZABAL Gamez. [One-line what it does]. Built on [the ZAO rails you used]. Cast: [farcaster URL] Would love your eyes on it - any feedback or repost very appreciated. ``` **Topic-specific (someone owns the surface you built on):** ``` Hey [name] - [thing] uses [their thing] - thought you should see it. [2-3 lines: what it does, why it matters, link] If it works for you, a quote-cast or repost to [their audience] would mean the world. ``` **Quick ask (very-tight relationship):** ``` [name] - quick - shipped [thing], think it would land with [their audience]. [link] Anything you would change? ``` ### Cross-platform - where the audience lives - **Farcaster (auto):** ZAO accounts repost to /zabal + /zao - **Telegram (manual):** ZAOstock Team Bot chat, WaveWarZ chats (via Hurric4n3Ike), COC promoter Discord - **X / Twitter (manual):** WaveWarZ X account, Neynar circles (via Arthur), your own audience - **Newsletter (planned):** ZAO Paragraph drop covers shipped July builds; submit yours to the next issue --- ## Time + dates > **Status: placeholder structure** - exact dates lock once cohort + mentor availability are confirmed. Pacific Time is the official anchor (per Doc 630). EU / Asia builders coding through their night during the August Finals window is acknowledged; future seasons may run regional variants. ### The three months | Month | What | Status | |-------|------|--------| | **June 2026** | Workshop month - recorded sessions + live spaces | dates TBD; bootcamp opens ~June 1 | | **July 2026** | Open build-a-thon - the build IS the application | dates TBD; opens ~July 1 | | **August 2026** | The Finals - 72-hour window, WaveWarZ-Base settles placement | dates TBD; one week in August, exact week locks when cohort confirms | ### The Finals 72-hour clock (anchored to T+0) - **T-3 days:** 90-minute onboarding call. Mandatory or forfeit. - **T+0:** Thursday 12:00 PT (proposed - to be confirmed). Prompt drops. Voter snapshot. WaveWarZ-Base battle markets open. - **T+24h:** Friday 12:00 PT. Ship deadline. The four required artifacts (URL / repo / demo / cast) must all be in. - **T+48h:** Saturday 12:00 PT. Promote window closes. Market continues trading. - **T+72h:** Sunday 12:00 PT. WaveWarZ-Base smart contract settles. Live reveal stream announces placements + distributes USDC + mints Hats NFTs on-chain. ### Soft launch milestone - **2026-05-30 (~soft launch):** the minimum-viable surface goes live - UGC submission field, volunteer/interest poll, intro video. Not the full Magnetiq portal yet, just a place to land. ### Global accessibility note The Finals are anchored to Pacific Time because the core team is West Coast US + Maine. EU builders will code through their night for the 24h ship window; Asia builders are mid-day to evening through the window. This is acknowledged and accepted for Season 1; future seasons may run multiple regional Finals windows. --- ## How the mentor + finalist pair works Per Doc 630 Part 3 + Doc 701. The mentor is **not a judge**. The mentor is an embedded teammate on your build during the August Finals - present, on-call, contributing to project management + distribution + connections while you code. ### What the mentor commits to - **Live presence during the 24h build window** (T+0 to T+24h). Available in Discord or Google Meet, in DMs, on-call. Not coding for you - but available the whole window. - **Screen-share availability** if you are hardware-limited or stuck on tooling. - **Project management help** during the build (what to ship, what to cut, when to call it done). - **ZAO connections** - mentor introduces you to other ZAO members, partner platforms, mentor-specific networks that strengthen your build. - **Distribution help during the promote window** (T+24h to T+48h). Reposts, quote-casts, intros to relevant audiences. - **Daily check-ins during July** (the build-a-thon month, before Finals) for finalists who got selected early. ### What the finalist commits to - **Show up to the T-3 onboarding call.** 90 minutes. Mandatory. - **Pick + maintain at least one visibility mode** during the 24h build (live Twitch / recorded sessions / public AI prompt logs / frequent build casts). Anti-cheat verification. - **Cast your ship.** No private builds. - **Communicate.** If you are stuck or off-track, tell your mentor. They cannot help if they do not know. ### Comms tools (default) - **Sync:** Discord voice / Google Meet (mentor + finalist pick on the onboarding call) - **Async:** Farcaster DMs OR Telegram (mentor's preference) - **Stream:** Twitch (default) restreamed to /zabal hub - **Code:** GitHub - finalist's repo, mentor has read access for quick reviews ### Mentor pairing curation Mentors claim champions from July submissions (first-come-first-served per mentor). Each mentor defines their own search style ("looking for a streamer with little vibe-coding experience" / "looking for a hard-coder doing smart contracts") before applications open. Mentors are not pooled - the mentor-finalist match is intentional and locked at curation. ### After the Finals The relationship usually keeps going. Many ZAO ecosystem collaborations started as mentor-finalist pairs from prior cohorts. No formal obligation either way; the door is open. --- ## Where to get help | Need | Where | |------|-------| | Stuck on your AI tool | Stream chat + your tool's docs | | ZAO infra question | `/zabal` Farcaster channel, tag `@bettercallzaal` | | Stream tech issue | StreamElements docs + `/zabal` | | Wallet / Empire Builder | DM `@bettercallzaal` on Farcaster | | Real emergency | Text Zaal (number in your onboarding email) | --- ## Bonfire knowledge graph (queryable depth) This file is a static prompt. The Bonfire knowledge graph at `zabal.bonfires.ai` is the queryable version - 444 entities + 655 edges (and growing) you can ask in natural language. Where this file states "WaveWarZ-Base settles Finals voting (Doc 720)", the graph holds the contract addresses, top performer wallets, Sam + Arthur build status, and every linked rail. Two paths: - **Bonfire chat** - DM the ZABAL Bonfire agent on Telegram (or the public Bonfire dashboard) with the entity name. Returns connected entities + edges. - **Raw graph dump** - [data/bonfire-graph.json](https://github.com/ZAODEVZ/zabalgames/blob/main/data/bonfire-graph.json) is the source-of-truth file. Re-pushed to Bonfire any time via `node scripts/push-to-bonfire.mjs` (needs `BONFIRE_API_KEY` env var). Twenty-one kEngrams seeded by parallel research subagents (rounds 1-8, 2026-05-23 to 2026-05-24): | kEngram | Ask the graph about | One-line takeaway | |---|---|---| | `hermes-architecture` | Hermes Coder/Critic | Two Claude Code subprocesses (Opus codes, Sonnet critiques). Loop max 3x, score >=70 ships. Auth via Max plan OAuth. Pre-flight gate (typecheck+lint+test) runs between Coder and Critic. Fleet cap $20/day notional. | | `wavewarz-protocol` | WaveWarZ v1 (Solana, live, hundreds of battles + 400+ SOL volume per ~2026-05-23 snapshot - current at wavewarz-intelligence.vercel.app) + v2 (Base agentic, Sam + Arthur, mainnet July 2026, settles ZABAL Gamez Finals via Doc 720 hybrid Option B). | Top performers (snapshot): LUI, APORKALYPSE, PROF!T. ~11 X Spaces/week. | | `zabal-empire` | $ZABAL token + Empire Builder V3 (Basic tokenless vs Ascended). | Contract `0xbB48f19B0494Ff7C1fE5Dc2032aeEE14312f0b07` on Base, 346 holders, 5 active boosters (4 ERC20 + 1 QUOTIENT). Glonkybot 17-token 5x stack is the reference network-effect pattern. | | `farcaster-snap-2026` | Snap protocol v2.0 (current). | `application/vnd.farcaster.snap+json` MIME + content negotiation on Accept header. Frame v1 buttons dead. `fc:miniapp` meta is for Mini Apps (separate protocol). Caster has a known-hosts whitelist - zlank.online whitelisted, arbitrary custom domains do NOT unfurl as Snaps. Use zlank `/s/[uuid]` template. | | `bounty-payment-rails` | POIDH on Base/Arbitrum/Degen + Empire Builder distribution. | POIDH escrows ETH, claim-NFT serves as proof. 2.5% protocol fee. ZABAL Gamez builders: claim project -> POIDH bounty -> proof -> payout -> Empire Builder pulls submitter feed and airdrops ZABAL. poidh-sentinel agent (open source, 0x94t3z) automates the loop. | | `bonfire-push` | How the graph is built. | Subagent runs produce `/tmp/zabal-dispatch-*.md` reports -> `scripts/aggregate-dispatches.mjs` normalizes + dedupes into `data/bonfire-graph.json` -> `scripts/push-to-bonfire.mjs` POSTs to `https://tnt-v2.api.bonfires.ai` (`/kg/entities` + `/kg/edges`, bearer auth). Idempotent on 409. | | `coinflow-isv` | Coinflow ISV tier - fiat-to-crypto + ACH + payouts for ZAO music, COC Concertz, ZABAL Gamez prize pool. | ISV tier = $0 setup + interchange-plus + instant settlement + named engineer. Solana gas 100% covered, Base supported. USDC settlement. KYC <10s users / 30s KYB 90% auto. 24+ webhook event types. Pay methods: card, ACH, Apple/Google Pay, PIX, SEPA. Custom MSA (no public rate card; industry benchmark 2.5-3.5%). | | `zaostock-sponsor-mechanics` | ZAOstock 2026 (Oct 3, Franklin St Parklet, Ellsworth ME) sponsor tiers + anchors. | Tiers: Small <$1K / Medium $1K-5K / Large $5K+. Confirmed sponsors: Wallace Events (tents/AV), Limone. Anchors: Steve Peer rolodex, Roddy Parklet (venue, <$1K), Art of Ellsworth (co-programming), Maine indie press. Venue locked. WaveWarZ on-chain voting layer optional. 14-person team, 4 sub-teams (Ops/Finance/Design/Music). | | `quotient-booster` | Quotient reputation booster on $ZABAL. | Quotient = Farcaster-native PageRank-variant measuring genuine engagement quality (ignores follower count). Score 0-1 normalized; quality drops below 0.5. QUOTIENT booster type confirmed live in Empire Builder V3. Exact multiplier formula + ZABAL booster config UNKNOWN; ask Adrian. | | `fishbowlz-juke-transition` | Why FISHBOWLZ paused, what Juke is, what ZAO did about it. | FISHBOWLZ paused 2026-04-16 to pivot to Juke (Farcaster-native iOS audio app, built in 3 days by nickysap, announced 2026-03-27). Juke uses LiveKit + native background audio + role-based speaking + novel mute-lockout rule. Missing: demote endpoint, webhooks, recording control. ZAO shipped Juke Path A (iframe embed, prod-ready) + Path B (server-side, awaiting creds). ZAO positions as flagship Juke community. | | `bonfire-revenue-model` | Bonfire's own business - x402 Knowledge Network, HyperBlogs, $KNOW token, Genesis NFT, NERDDAO. | Tiers: Free / Pro / Genesis (custom, 0.1 ETH Genesis NFT mint). x402 = Coinbase's HTTP 402 micropayment protocol; Bonfire uses it for federated query monetization (pay per retrieval across the Knowledge Network). HyperBlogs turn graphs into x402-monetized AI blog posts. $KNOW token utility partially documented (7 unknowns flagged). NERDDAO is the open-source ecosystem org; Joshua.eth founder. BCZ Strategies bought Genesis tier. | | `zoe-telegram-skills` | ZOE bot's command catalog and skill architecture. | 9 explicit commands: `/start`, `/tasks`, `/seed`, `/quest`, `/quests`, `/voicememo`, `/zg`, `note:` prefix, free-form concierge. 5 scheduled crons (morning brief, evening reflection, hourly nudge, post drafting, hourly DevZ tip pending). Bonfire bidirectional integration (writes episodes; vector search read with manual relay fallback). Built on canonical Hermes-style Claude Code subprocess pattern. | | `hats-protocol` | Hats Protocol on Optimism (ZAO governance treeId 226) + Base (ZABAL Gamez Finisher/Champion NFTs). | ERC-1155 non-transferable. Tree 226 has 19 hats (Top Hat = Zaal, Configurator 2/5, Council Members 3/5, 17 project sub-hats). Role-check via `isWearerOfHat` SDK in `lib/hats/gating.ts` + `/api/hats/check`. SDK `@hatsprotocol/sdk-v1-core` v0.12.4 (ZAO has package reference but no live calls yet). ZABAL Gamez plan (June build, August execute): new Base tree, `Hats.batchCreateHats()` for Finisher + Champion definitions, `Hats.batchMintHats()` at T+72h Finals settlement. Cost $0.02-0.20 per mint on Base via EIP-4844 blob savings. Metadata as IPFS JSON CID. POIDH proof-submission tie still open (needs design pass). | | `ardrive-permastorage` | ArDrive + AR.IO + Arweave permanent storage for ZAO Music masters + stems + cover art + release metadata. | AR token ~$1.97 -> $5-12 per GB; typical 50-100 MB WAV master = $0.25-1.20 one-time. Arweave's 200-year endowment model (Kryder+ 0.5% hardware-cost decline) funds storage with no renewals. ArDrive Turbo (preferred, deprecated Irys) batches up to 250 files / 500 MiB per ANS-104 tx -> 40-60% cost savings. AR.IO gateway network (650+ gateways) serves egress; supports x402 payment protocol since Release 54 (Oct 2025), default $0.10/GB configurable to $0.0000000001 USDC/byte. Wayfinder SDK = cryptographic-verified intelligent routing. Drive layout: `///master.wav` + ANS-104 manifest. Metadata schema: ISRC + ISWC + BPM + key + tags. Order of operations: Arweave upload (independent) -> DistroKid distribution (ISRC issued ~4 weeks pre-delivery) -> 0xSplits split contract deploy on Base AFTER Zora 1155 mint (payoutRecipient captures all revenue). Master perm-stored as `ar://` URI referenced in NFT tokenURI. BMI registration needs ISRC + composer/publisher from DistroKid API. Cost-comparison winner long-horizon vs Filecoin ($200-1000/TB/yr recurring) and IPFS pinning ($5-20/mo). | | `music-rights-pipeline` | The full BMI -> MLC -> DistroKid -> 0xSplits chain + post-UMG CD Baby exit + on-chain Creator Fund mechanic. | Registration order LOCKED: (1) BMI publisher $250 one-time + free songwriter affiliation, (2) MLC free composition registration **BEFORE DistroKid upload** (else "unmatched recordings" land in DSP pools and get redistributed to majors by market share - 9 month recovery window only), (3) DistroKid Musician Plus $44.99/yr issues ISRC, (4) ISWC auto-assigned from BMI when composition registered, (5) 0xSplits deploys on Base AFTER Zora 1155 mint (payoutRecipient captures all revenue). 0xSplits Split is IMMUTABLE (security feature for music rights). Pull payment model (recipients withdraw). Default ZAO split: Artist 80% / ZAO Treasury 10% / Curator 10%. "25% middleman replacement" claim unpacked: replaces Songtrust 15-20% publishing-admin commission + ASCAP/BMI 10-15% platform overhead + DistroKid pass-through (free). Why CD Baby skipped: UMG acquisition Feb 20 2026 (Virgin Music Group umbrella) destroyed independence narrative - UMG now sees 4M creators' release schedules + territorial sales. DistroKid won (33% indie weekly upload share, structurally independent). TuneCore Believe-owned, Revelator Warner-acquired Mar 2026. Streaming royalty flow: Spotify/Apple monthly -> DistroKid (30-60d reporting + 2-3mo hold) -> 0xSplits split address on Base -> `distribute()` is permissionless. | | `tip-zols-architecture` | Three-token reconciliation: $ZABAL (real ERC-20 on Base) + ZOLs (off-chain credits) + $TIP (not yet deployed). | $TIP token status UNKNOWN - no on-chain contract found in any ZAO repo, conceptual only. Naming collision: ZOE bot already sends "[ZOE TIP]" messages hourly as Task Insight Prompts (forward nudges to task queue) - if $TIP launches as a token this needs disambiguation. ZOLs = peer-validated reputation credits, not money. One ZOL per volunteer hour at ZAO events (ZAOstock, ZABAL Gamez, COC Concertz) + monthly "ZABAL Opinion Leaders" status to top-3 SongJam leaderboard performers. Storage: hybrid spreadsheets + volunteer profile URLs, NOT on-chain. No documented conversion path from ZOLs to ZABAL or other tokens - pure recognition. $ZABAL is the only freely-tradable layer (0xbB48f19B... on Base, 100B supply, raffle + weighted leaderboard distribution). Three-layer separation recommended (each serves unique function). Codify ZOL-to-payout conversion rules in ZABAL Gamez Finalists logic (e.g. ZOL count -> airdrop share %). | | `tool-stack-deep-dive` | Every tool in production across the ZAO ecosystem, one entity per tool with cost + auth + integration point + category. | Four categories indexed: **music-infra** (DistroKid Musician Plus $44.99/yr + BMI $250 one-time + free MLC + 0xSplits Base zero-fee + ArDrive Turbo + AR.IO + FireWavez UNKNOWN), **agent-infra** (Claude Code Max $200/mo spawns Hermes + ZOE subprocesses via OAuth, Anthropic API rarely-used direct, Ollama self-hosted llama3.1:8b for low-stakes inference on VPS, OpenRouter for testing 25+ free models + fallback parity, Bonfire/NERDDAO Genesis tier 0.1 ETH NFT mint for knowledge-graph), **ops-infra** (Lu.ma Plus $59/mo for API, Cal.com webhooks on free tier, Magnetiq via Tyler Stambaugh, Telegram free, Farcaster free + Neynar, X Spaces free, Riverside $24/mo, Descript $16/mo), **crypto-infra** (Helius 1M Solana credits free, Alchemy 30M Base CUs free, Coinflow ISV custom MSA, x402 Coinbase HTTP 402 micropayments, Empire Builder V3 free tokenless/Ascended-via-Clanker, Clanker Farcaster-native launcher 0.2% WETH fee, Hats Protocol $0.02-0.20/mint on Base, POIDH 2.5% protocol fee). Total stack 32 tools; ~85% free or under $50/mo. | | `calendar-automation` | Lu.ma + Cal.com end-to-end for ZABAL Gamez June workshops. | Lu.ma API needs Plus tier ($59/mo) - REST endpoints `POST /v1/event/create` + `GET /v1/event/get-guests` (filter by approval_status) + 9 webhook event types (Guest Registered, Ticket Registered, Event Updated, ...) with HMAC SHA-256 signature verification. Rate limit 200 req/min calendar-key / 500 org-key. Real-time webhooks replaced polling as of April 2026 v6.0.0. Cal.com webhooks on free tier (BOOKING_CREATED + BOOKING_CANCELLED + BOOKING_RESCHEDULED + 14 more triggers), Bearer auth 120 req/min default, mustache-templated payload, HMAC-SHA256 signing. Event-Type API gates BOOKING_CREATED vs BOOKING_REQUESTED via confirmation flag. ZABAL Gamez end-to-end flow: lead submits /lead.html -> Formspree webhook -> Supabase (planned, currently spreadsheet) -> Zaal approves via DM -> Cal.com event-type booking link sent -> Lu.ma event auto-created on confirm -> Farcaster cast on /zabal -> day-of reminder -> recording auto-uploads to Magnetiq portal (Tyler) -> post-event clipped + cross-posted. Currently Zaal manually handles approvals + booking; automation is the next-week build once W2 + W3 unblock. | | `talent-vs-quotient` | Talent Protocol vs Quotient reputation comparison for ZAO Empire Booster choice. | **Recommendation: Quotient as Empire booster + Respect as governance anchor + Talent Protocol optional for external recruitment visibility.** Quotient = Farcaster-native PageRank-variant (engagement quality + momentum, ignores raw follower count), founded by @amphib0ly, incubated by Skycastle Tokens. Native QUOTIENT booster in Empire Builder V3 (zero-address contractAddress field). Talent Protocol = broader builder reputation, REST `GET /api/v2/passports`, transparent 3-tier credentials (Identity max 20pts + Activity max 40pts + Skills uncapped) drawing from GitHub + Farcaster + on-chain + Twitter + LinkedIn. Talent's explainable buckets vs Quotient's black-box graph analysis. Empire boosters stack additively (2x + 4x = 6x). Why Quotient for ZAO: ZAO is Farcaster-native music community, Quotient measures the exact medium that matters. Talent's 40/100 GitHub-weight makes it secondary signal for a music-first community. ZAO already runs Respect (peer-validated Fibonacci 110/68/42/26/16/10 consensus in 90+ weekly fractal sessions, 2% weekly decay) - that + Quotient compounds the right signals. | | `songjam-x-empire` | SongJam X-scraper -> Empire Builder API migration (adoptable #01). | Why migration: X API v2 went paid-only mid-2026 ($0.005/read + $0.01/write + Basic tier $200/mo). Continuous scraping unsustainable for Adam (SongJam maintainer). New flow: SongJam Music Engagement API -> Empire Builder apiLeaderboards endpoint feeds three slots (Season 1, Season 2 Ep1, Ep2) in ZABAL Empire. JSON shape per leaderboard slot: `{uuid, name, type: tokenHolders|farToken|api|null, rankedCount}`. SANG token = SongJam's native token on Base `0x4ff4d349caa028bd069bbe85fa05253f96176741` (1B supply, thin liquidity). 250k SANG = minimum-stake threshold on ZABAL Empire, multiplier formula `1 + sqrt(stakeAmount / 250k)` yielding 2.1x-3.0x stack on top of Empire Builder boosters (4.0x-8.6x) = up to 25x total scoring. SANG distribution: per-second leaderboard scoring with role multipliers (listener 1x, speaker 2x). Migration unblock: builders can export Empire leaderboard CSVs as airdrop lists for Clanker token launches in August Finals. Frees Adam from scraper hell. | | `africa-cdn-routing` | Why ZAO domains are unreachable from many African networks without a VPN + the fix. | ROOT CAUSE: Vercel has 1 African compute region (Cape Town) and ZERO peering at NAPAfrica. African ISPs (Safaricom, MTN, Airtel, Vodacom) route off-continent through submarine cables to AWS US-East or EU-West and back = 800ms+ TTFB + intermittent drops. Carrier transparent HTTPS proxies + HTTP/3 blocking (Uganda confirms UDP/443 block) + IPv6-only with broken AAAA = silent failures. FIX: put Cloudflare Free in front of Vercel. Cloudflare has 31+ African data center cities (Lagos, Cape Town, Nairobi, Johannesburg, Cairo, Casablanca, etc) and peers at all major African IXPs. 30-min migration: lower TTL at Porkbun 24h pre, create Cloudflare account, add domain, TLS mode Full (strict), enable orange-cloud proxy, swap Porkbun nameservers to Cloudflare's. Near-zero downtime if TTL pre-lowered. Free tier sufficient at ZAO scale. Recommended window Sun May 25 - Tue May 27 (5 days before May 31 launch cast). Full execution plan in [docs/research/730-africa-cdn-routing-fix.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/730-africa-cdn-routing-fix.md). | If you are an agent: query the graph for any entity name above and traverse 1-2 hops. The depth is there; this file only points at it. --- ## Deeper context This file is the lean version. For depth: - [docs/research/630-player-context-bundle.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/630-player-context-bundle.md) - the full player primer (every detail, every code pattern) - [docs/research/701-canonical-state.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/701-canonical-state.md) - the current state of decisions; what is locked, what is open - [docs/research/630-season-1-spec.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/630-season-1-spec.md) - the long-form Season 1 working spec - [docs/research/646-clanker-promote.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/646-clanker-promote.md) - the optional Clanker token mechanic - [docs/research/654-empire-v3-meeting.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/654-empire-v3-meeting.md) - the calendar pivot decisions - [docs/research/714-tyler-call.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/714-tyler-call.md) - Tyler / Magnetiq hosting + Zabal connector decisions - [docs/research/719-jordan-meeting.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/research/719-jordan-meeting.md) - Empire Builder v3 integration follow-up - [docs/brand-context.md](https://github.com/ZAODEVZ/zabalgames/blob/main/docs/brand-context.md) - the brand identity guide per ZAO brand External: - Farcaster: https://farcaster.xyz - Farcaster Mini Apps docs: https://miniapps.farcaster.xyz - Hats Protocol: https://hatsprotocol.xyz - Empire Builder docs: https://empire-builder.gitbook.io/empire-builder-docs - WaveWarZ Intelligence: https://wavewarz-intelligence.vercel.app - BetterCallZaal: https://bettercallzaal.com - ZAO research library (historical, pre-move): https://github.com/bettercallzaal/ZAOOS/tree/main/research --- ## How to use this file with your harness 1. **Claude Code:** save as `CLAUDE.md` at repo root. 2. **Cursor:** save as `.cursorrules` at repo root, OR as `CLAUDE.md` plus reference in `.cursor/rules/`. 3. **Windsurf:** save as `.windsurfrules` at repo root. 4. **Aider:** save as `CONVENTIONS.md` and pass with `--read CONVENTIONS.md`. 5. **Cline / Continue:** add to `.cline/instructions/` or via continue.dev config. 6. **Other harnesses:** check your tool's docs for the project-level context file convention. After loading, tell your tool what you are building. The brand guidelines are non-negotiable - the tool needs to know "no emojis, no em dashes" before it writes a single line. --- *Updated 2026-05-23. Source of truth is this file. Pull requests welcome at https://github.com/ZAODEVZ/zabalgames.*