Imported from serpapi/world-cup-loop-engineering (AGENTS.md). Install upstream with npx skills add serpapi/world-cup-loop-engineering. Copyright stays with the author.

World Cup Fan Journey: Codex Build Instructions

Product Goal

Build World Cup Fan Journey, a fan-facing demo that visualizes Loop Engineering through a 2026 World Cup discovery experience.

This is built with Codex, SerpApi, and an optional runtime LLM for natural-language parsing and fan analysis. Do not describe the product as a Claude Code demo.

The demo should feel like a cute football product, not an engineering dashboard.

One-Line Pitch

Start with one World Cup match. Follow a player. Let the journey expand until you generate your personal football graph.

Core Loop Engineering Idea

The loop is not shown as technical panels. The loop is shown through user behavior:

User searches a match
-> AI parses the request
-> SerpApi fetches sports/video/social/news context
-> App renders a fan page
-> User follows a player
-> That click becomes the next trigger
-> AI changes the next goal
-> SerpApi fetches that player's recent match trail
-> App expands the page
-> User follows another player
-> Loop continues
-> User clicks "Generate my football graph"

The strongest product claim:

The user's next click changes the agent's next goal.

This must not feel like a fixed pipeline:

Sports -> YouTube -> Instagram -> Trends -> Summary

A pipeline would build one page. This demo should grow a personalized journey.

Primary Demo Scenario

Use this as the default demo path:

Show me Norway vs France

or:

我的天哪，我想看挪威对法国的比赛

The runtime LLM should parse either input as:

{
  "homeTeam": "Norway",
  "awayTeam": "France"
}

Then the app should build the first fan page for:

Norway vs France

Required Product Name and Copy

Use:

World Cup Fan Journey

Use this badge or nearby copy:

SerpApi + Codex

Do not use:

Rabbit Hole
Claude Code
Claude Runtime Loop
Developer dashboard

It is acceptable for internal file names or API routes to still contain old names, but the user-facing UI and documentation should not.

SerpApi Requirements

Use SerpApi by purpose, not just because an API exists.

Mandatory First Tool

Google Sports API must be the first external data source for a match or player expansion.

Use it to establish:

• match existence
• teams
• score/result
• status
• date/time
• competition/stage
• upcoming fixtures when available

The app should not start a match page by searching YouTube first.

Required Fan Content APIs

Use these after sports facts are established:

• YouTube Search API for highlights, replays, shorts, meme/fan-reaction videos.
• Google News API for hot discussion topics and controversy headlines.
• Google Trends API for rising discussion queries.
• Instagram Profile API for player profile cards and avatar images.
• Google Sports API again for upcoming World Cup matches and countdown cards.

Recommended Fallbacks

When live APIs fail or return too little:

• Keep the page usable with fixture data.
• Clearly keep fan-facing fallback copy natural, not technical.
• Ensure video cards and discussion cards still link somewhere useful.
• Keep the loop moving unless the user explicitly stops.

Data Quality Requirements

YouTube and Shorts

The "Watch the best bits" panel must show exactly 3 clickable video cards.

Each card must include:

• real video title when available
• real YouTube URL or useful YouTube search URL
• real YouTube thumbnail when available
• fallback thumbnail only if the API does not return one

Prefer thumbnails from SerpApi YouTube fields such as:

• thumbnail
• thumbnail.static
• thumbnail.rich
• thumbnails
• YouTube fallback: https://i.ytimg.com/vi/{video_id}/hqdefault.jpg

Trending Discussions

The "Fans are arguing about" panel must show 3 clickable discussion cards.

Each card must link to:

• the original news result URL, or
• a Google Search URL for the trend/topic fallback.

Do not render non-clickable discussion bubbles.

Instagram Player Cards

Player cards must show real Instagram avatar/profile images when available.

Use SerpApi Instagram Profile API with:

engine=instagram_profile
profile_id=<instagram handle without @>

Prefer avatar fields:

• serpapi_profile_pic_url_hd
• serpapi_profile_pic_url
• profile_pic_url_hd
• profile_pic_url

Example handles:

• Haaland: @erling
• Mbappe: @k.mbappe
• Odegaard: @odegaard.98
• Griezmann: @antogriezmann

If the profile API fails, render a playful fallback sticker avatar, but keep the Instagram link clickable.

Upcoming World Cup Matches

Add a fan-facing section for upcoming World Cup matches.

It should show:

• 3 upcoming matches
• country flags
• stage/competition
• venue when available
• kickoff time
• live countdown

The countdown should update every second on the client.

If live Google Sports results do not provide enough upcoming matches, use believable fixture fallback data for the demo.

User-Facing UI Rules

The default UI must not look technical.

Do not show these words in the normal fan UI:

• Loop State
• Tool Calls
• Validator
• Persistent Memory
• Budget
• Attempt limit
• Degraded
• Fixture fallback

Those concepts may exist only in a hidden presenter/debug panel.

The design should feel:

• cute
• meme-friendly
• World Cup themed
• flag-heavy
• social-media friendly
• easy to understand
• playful but still useful

Use:

• big Google-like natural-language search box
• prompt chips in English, Chinese, Spanish, and German
• country flags
• World Cup trophy visuals
• player face/profile images
• sticker-like player cards
• YouTube thumbnail cards
• clickable discussion cards
• follow buttons
• live loading state while data is being fetched
• final football graph

Avoid:

• dark industrial dashboard aesthetic
• dense technical tables
• tiny status chips everywhere
• developer-first explanations

Main Screens

Screen 1: Search

Show:

World Cup Fan Journey
Start with one match. Follow a player. Build your football graph.

Include a large natural-language search input.

Prompt examples:

• English: Show me Norway vs France
• Chinese: 我的天哪，我想看挪威对法国的比赛
• Spanish: Quiero ver Noruega contra Francia
• German: Ich will Norwegen gegen Frankreich sehen

Screen 2: Match Page

After the initial search, render:

• Match snapshot: teams, flags, score/status/date.
• Watch the best bits: 3 clickable YouTube/Shorts cards with thumbnails.
• Fans are arguing about: 3 clickable News/Trends discussion cards.
• Upcoming World Cup: 3 upcoming matches with countdowns.
• Players to follow: Instagram-style player cards with images and follow buttons.
• AI fan take: short fan-facing analysis.

Screen 3: Player Trail

When the user clicks "Follow to expand" on a player:

1. Treat the click as the next trigger.
2. Use the LLM to create a new goal:

Find this player's recent/trending 3 football matches and expand the fan journey.

3. Call SerpApi again:

   • Google Sports first
   • YouTube Search for highlights/replays
   • YouTube Search or Short Videos-style queries for memes/shorts
   • Google News and Trends for discussions
   • Instagram Profile API for related players

4. Render:

   • the followed player
   • 3 match cards
   • videos for each match
   • discussions for each match
   • related players with follow buttons

The page should expand visibly. Do not replace the whole app with a plain report.

Screen 4: Final Graph

The stop condition is user-driven:

Generate my football graph

When clicked, render a playful graph showing:

• user
• initial match
• followed players
• discovered matches
• related teams/clubs/national teams
• related players
• discussion/video nodes when useful

Do not make the graph look like a database table.

Loading and Error UX

Every data-fetching action must show a loading UI.

For example:

Parsing your request, checking Google Sports, and building the first match page...

or:

Following Haaland: planning 3 recent games, fetching results, videos, memes, discussions, and related players...

If an API fails:

• keep the app usable
• show useful fallback content
• do not expose stack traces
• do not show technical failure language to normal users

Environment Variables

Use:

SERPAPI_API_KEY=
ANTHROPIC_API_KEY=

SERPAPI_API_KEY is required for live sports/video/news/trends/Instagram data.

ANTHROPIC_API_KEY is optional runtime LLM support for:

• natural-language match parsing
• player expansion planning
• short AI fan analysis

Even if Anthropic is used at runtime, do not call the product a Claude Code demo.

Suggested Technical Stack

Use:

• Next.js App Router
• TypeScript
• React
• Tailwind CSS
• shadcn/ui style primitives if already present
• SerpApi JavaScript SDK or a thin fetch wrapper around SerpApi
• server API routes for SerpApi/LLM calls
• client components for interactive journey UI
• Vitest for focused tests

Do not expose API keys to client components.

Implementation Notes for Codex

When implementing:

1. Read the existing codebase before editing.
2. Preserve user-facing cuteness over developer-dashboard clarity.
3. Keep Google Sports as the first tool in each loop.
4. Make every card clickable when it represents external content.
5. Keep at least 3 cards in the main video/discussion/upcoming sections.
6. Use real thumbnails and profile images whenever SerpApi returns them.
7. Add deterministic fallback data only to keep the demo stable.
8. Run npm run build and npm test.
9. If a dev server is running, verify the page in a browser.

Demo Success Checklist

The demo is acceptable when:

• Search input parses multilingual natural-language intent.
• Norway vs France page renders.
• YouTube section has 3 cards with thumbnails.
• Discussion section has 3 clickable cards.
• Player cards show Instagram avatars when available.
• Clicking Haaland expands into 3 recent/trending matches.
• Expanded matches include videos, discussions, and related players.
• Upcoming World Cup matches show countdowns.
• Loading UI appears while fetching.
• Final graph button stops the journey and renders the graph.
• User-facing UI says World Cup Fan Journey and SerpApi + Codex.
• User-facing UI does not mention Claude Code or Rabbit Hole.