🎲 What Should We Do?

data/whatdo/preferences.json:

{
  "last_updated": "2026-01-15",

  "dietary": ["vegetarian"],
  "alcohol": "yes",
  "energy_default": "active",
  "favorite_vibes": ["adventurous", "weird"],
  "favorite_categories": ["outdoor", "food"],
  "location_notes": "splits time between AZ desert and ID mountains",
  "notes": ["has a truck — road trips are always an option", "likes trying new cuisines"],

  "streaming_services": ["netflix", "hulu", "disney_plus", "hbo_max", "prime_video", "peacock", "paramount_plus", "apple_tv"],

  "board_games": ["Catan", "Ticket to Ride", "Codenames", "Wingspan"],
  "card_games": ["Cards Against Humanity", "Exploding Kittens", "Uno"],
  "video_games": {
    "console": "PS5",
    "games": ["Mario Kart", "It Takes Two"]
  },
  "game_preferences": ["strategy", "party", "cooperative"],

  "favorite_places": [
    {"name": "Ichiban Ramen", "type": "restaurant", "notes": "best tonkotsu in town"}
  ],
  "blacklist_places": [
    {"name": "Applebees on Main", "reason": "terrible service"}
  ],
  "favorite_activities": ["escape rooms", "hiking"],
  "disliked_activities": ["karaoke"],

  "min_rating": 4.0,

  "groups": {
    "game_night_crew": {
      "members": {
        "Scott": {"telegram": "@scotttfo", "email": "[email protected]"},
        "Mike": {"telegram": "@mikehandle", "phone": "+15551234567"},
        "Sarah": {"telegram": "@sarah", "email": "[email protected]"},
        "Dave": {"phone": "+15559876543"}
      },
      "size": 4,
      "preferences": ["board games", "beer", "pizza"],
      "dietary": {"Sarah": "vegetarian"},
      "alcohol": {"Dave": "no"}
    },
    "date_night": {
      "members": {
        "Scott": {"telegram": "@scotttfo"},
        "Partner": {}
      },
      "size": 2,
      "preferences": ["quiet", "good food", "no chains"],
      "dietary": {},
      "alcohol": {}
    }
  },

  "routines": [
    {"name": "Taco Tuesday", "day": "tuesday", "activity": "tacos", "frequency": "weekly"},
    {"name": "First Friday Art Walk", "day": "first_friday", "activity": "gallery walk", "frequency": "monthly"}
  ]
}

Quick Reference

Quick Mode (Default)

When someone says "what should we do?" with no other context, don't ask questions — just GO.

Quick Mode Logic

1. Check the clock — day of week, time of day
2. Check the calendar — any planned events today/tonight? Conflicts? (see Calendar Integration)
3. Check the weather — use web_search for current conditions at user's location (read location from USER.md)
4. Check routines — is it Taco Tuesday? First Friday? A seasonal tradition?
5. Check history — what have they done recently? What's overdue?
6. Check preferences — known favorites, group profiles, game library
7. Generate ONE confident suggestion with the full output format

Examples:

• Saturday night + nice weather + usually goes out → "Hit up that new cocktail bar downtown — patio weather!"
• Tuesday night + rainy + usually stays in → "You've got Catan and it's been a while — game night?"
• It's Tuesday → "Taco Tuesday! Want the usual spot or mix it up?"
• October + weekend → "It's spooky season — haunted house time?"
• Haven't done an escape room in 3 months → "You're overdue for an escape room — there's a new one downtown"

If preferences are too thin to make a confident Quick Mode suggestion, fall back to the full question flow.

The Flow (Full Mode)

When Quick Mode doesn't have enough context, or the user wants to explore options, run through these questions. Keep it conversational and snappy — this is NOT a survey. It's a fun back-and-forth. Use inline buttons when available, or quick-fire options.

If the platform supports inline buttons, present each question with tappable options. Otherwise, list them conversationally.

The Questions

Ask these in order, but be flexible. If someone says "date night, something fancy, we want dinner" — that answers questions 1, 2, and 4 in one shot. Don't re-ask what you already know.

1. Who's coming? 🧑‍🤝‍🧑

• Solo adventure
• Date night 💕
• Friends hangout
• Family time
• Whoever shows up
• [Show saved group names if they exist: "Game night crew (4)?", "Date night?"]

2. Vibe check? ✨

• Chill 😌
• Adventurous 🏔️
• Fancy 🥂
• Weird 🦑
• Wild 🔥
• Surprise me 🎰

3. In or out? 🏠↔️🌎

• Stay home → triggers Stay Home Deep Mode
• Go out
• Either works
• Include weather context: "It's 72° and clear — great night to be outside!" or "It's pouring — staying in might be the move"

4. Fuel? 🍕

• Eating
• Drinking
• Both
• Neither
• Just coffee ☕

5. Booze? 🍺

• Yes please
• Nah
• Optional
• Skip if preferences say "no alcohol" or group profile indicates

6. Budget? 💰

• Free (best things in life!)
• Cheap ($)
• Moderate ($$)
• Splurge ($$$)
• Money is no object 💎

7. Energy level? ⚡

• Couch potato 🛋️
• Light activity
• Active 🏃
• Full send 🚀

8. Time? ⏰

• Right now
• Tonight
• This weekend
• Planning ahead

Smart Shortcuts

If you already know things from preferences.json or context, skip questions you can infer. For example:

• If preferences say "doesn't drink" → skip the booze question
• If it's 11pm → probably "right now" or "tonight" and lower energy
• If they said "date night" → that answers who's coming, load the date_night group profile
• If a group profile has dietary info → factor it in automatically
• If weather is terrible → lean toward indoor suggestions without asking

Live Weather Integration

Before generating suggestions, always check the weather at the user's location.

How to Check Weather

1. Read USER.md for the user's current location
2. Use web_search to search for current weather: "weather [city] today" or "current weather [city]"
3. Parse the temperature, conditions (sunny/rainy/cloudy/etc.), and forecast

Weather Decision Logic

Weather in Output

Always include weather in the suggestion output:

🌤️ Weather: 72°F, clear skies — great night to be outside!

or

🌧️ Weather: 58°F, rain expected tonight — indoor vibes!

Local Movie Showtimes

When suggesting movies (going out to a theater), find real showtimes.

How to Find Showtimes

1. Use web_search: "movies playing near [user's city] tonight" or "movie showtimes [city] today"
2. Parse results for: theater names, movie titles, showtimes
3. If Google Places API is available: search for nearby movie theaters to get ratings and hours
4. Present with full details:

🎬 Now Playing Near You:
• "Dune: Part Three" — AMC Scottsdale 101 (⭐ 4.3) — 7:15pm, 9:45pm
• "The Return of the King" (re-release) — Harkins Camelview — 7:00pm, 10:00pm
• "Comedy Special" — Alamo Drafthouse Tempe (⭐ 4.6) — 8:30pm

No TMDB API needed — web search gets current showtimes. Google Places adds ratings and hours if available.

Business Hours & Ratings

Business Hours

When suggesting places to go, always check if they're open.

With Google Places API:

• Request the currentOpeningHours field in every query
• Filter out closed businesses — never suggest somewhere that's closed
• Show hours in output: "Open until 11pm" or "Closes in 2 hours"
• If closing soon (<1 hour), warn: "⚠️ Closes at 10pm — hustle!"

Without Google Places API:

• Add a note: "Check hours on Google Maps before heading out"
• Use web_search as a fallback to find hours for specific venues

Ratings Floor

With Google Places API:

• Default minimum rating: 4.0 stars (configurable via min_rating in preferences)
• Sort suggestions by rating, highest first
• Show rating in output: ⭐ 4.6 (2,341 reviews)
• If very few results above the floor, mention: "Slim pickings above 4 stars — here's the best of what's available"

User can adjust:

• "min_rating": 4.0 in data/whatdo/preferences.json
• "Lower my ratings floor to 3.5" → update preferences

Streaming Service Preferences

Setup

If streaming_services isn't in preferences yet, ask during:

• First-time setup
• Any "stay home" or "movie night" suggestion
• "What streaming services do you have?"

Store in data/whatdo/preferences.json:

{
  "streaming_services": ["netflix", "hulu", "disney_plus", "hbo_max", "prime_video"]
}

Valid service keys: netflix, hulu, disney_plus, hbo_max, prime_video, peacock, paramount_plus, apple_tv, crunchyroll, youtube_premium, tubi, pluto_tv

Using Streaming Preferences

When suggesting TV/movies at home:

1. Use web_search to find what's trending on their specific services:
   • "trending on Netflix this week" or "best new shows on HBO Max right now"
2. Present with service context:
   • "Trending on your Netflix right now: The Thursday Murder Club — mystery comedy, 97% on RT"
   • "New on your HBO Max: White Lotus Season 3 just dropped"
3. Mix services — don't just pick one

Game Library

Setup

If game library fields are empty, ask:

• "What board games do you own?"
• "Any card games? Video games?"
• "What kind of games do you like? (strategy, party, cooperative, competitive)"

Game Knowledge

Know player counts for popular games and suggest based on group size:

Smart Game Suggestions

• Match games to group size: "You have 4 people and Catan — perfect for a tournament night"
• Match games to preferences: "You like strategy games and own Catan — you'd probably love Terraforming Mars"
• Suggest pairings: "Catan + homemade pizza + a beer flight = perfect Saturday night"
• Suggest new games based on owned collection:
  • Owns Catan + likes strategy → suggest Terraforming Mars, Spirit Island
  • Owns Codenames + likes party → suggest Wavelength, Just One
  • Owns Wingspan + likes relaxed → suggest Everdell, Parks

Favorites & Blacklist

How It Works

• Favorites — places and activities the user loves. Resurface them periodically:
  • "You loved Ichiban Ramen — haven't been in a while!"
  • "You always have a great time at escape rooms — there's a new one in town"
• Blacklist — places and activities to NEVER suggest:
  • Blacklisted places are invisible. Period. Don't mention them.
  • Disliked activities are filtered out entirely.
• Building the lists — after every suggestion, offer:
  • "👍👎 How'd we do? (helps me learn your taste)"
  • Thumbs up → ask if they want to add it to favorites
  • Thumbs down → ask what went wrong, add to blacklist if appropriate
  • Track in preferences.json

Checking Before Suggesting

Before presenting any suggestion:

1. Check blacklist_places — if a suggested place is on the list, skip it
2. Check disliked_activities — if the activity type is disliked, skip it
3. Check favorite_places — if a favorite is relevant to the current request, prioritize it
4. Check favorite_activities — lean into known loves

Group Profiles

Loading a Group

When the user mentions a group by name ("game night with the crew", "date night"):

1. Load the matching profile from preferences.json → groups
2. Apply all group preferences automatically:
   • Dietary restrictions → filter restaurant suggestions
   • Alcohol preferences → adjust drink suggestions
   • Group size → match to activities and games
   • Group preferences → weight categories accordingly
   • Member contacts → enable invites and reminders (see Group Invites & Reminders)

Member Contact Format

Members can be stored in two formats for backward compatibility:

New format (with contacts):

"members": {
  "Mike": {"telegram": "@mikehandle", "phone": "+15551234567"},
  "Sarah": {"telegram": "@sarah", "email": "[email protected]"},
  "Dave": {"phone": "+15559876543"}
}

Legacy format (still supported):

"members": ["Scott", "Mike", "Sarah", "Dave"]

Handling: If members is an array of strings, treat it as names-only (no contact info available). All group features work either way — contact info just enables invites and reminders. When the user adds contact details, migrate the member entry from the list to the object format.

Supported contact fields:

• telegram — Telegram handle (e.g., "@mikehandle")
• email — Email address
• phone — Phone number (E.164 format preferred)

Smart Group Logic

• "Sarah is vegetarian — skip the BBQ joints" (automatically filter based on dietary)
• "Dave doesn't drink — suggesting places with good mocktails or non-bar options"
• Group of 4 + game preferences → suggest games from library that work at 4 players
• Date night + "no chains" preference → filter out chain restaurants

Managing Groups

• "Add a new group called poker night" → create new group profile
• "Add Lisa to game night crew" → update existing group
• "Sarah is gluten-free now" → update dietary restrictions
• "Add Mike's telegram: @mikehandle" → update member contact info
• "Mike's email is [email protected]" → add/update contact field
• "Add Sarah's phone: +15551234567" → add/update contact field
• "Show me the game night crew" → display group profile with contacts

Routines & Traditions

Automatic Triggers

When generating suggestions, check routines first:

1. Weekly routines: Check what day it is
   • Tuesday → "It's Taco Tuesday! Want the usual or mix it up?"
   • Friday → Check for "First Friday" if it's the first Friday of the month
2. Monthly routines: Check date
   • First Friday → "First Friday Art Walk tonight — the galleries are calling!"
3. Seasonal traditions: Check month/season
   • October → "It's spooky season — haunted houses, horror movies, pumpkin patches"
   • December → "Holiday market season — any you haven't hit yet?"
   • Summer → "Long days = sunset hikes, outdoor movies, patio nights"
4. Overdue activities: Check history
   • Favorite activity not done in 3+ months → "You haven't done an escape room in 3 months — overdue!"
   • Favorite place not visited in 2+ months → "It's been a while since Ichiban Ramen..."

Managing Routines

• "Add Taco Tuesday as a weekly thing" → save to routines
• "We do game night every other Thursday" → save with biweekly frequency
• "Cancel Taco Tuesday" → remove routine

Calendar Integration

After a plan is locked in (user accepts a suggestion and sets a time), offer to add it to the calendar. This turns "what should we do?" from a suggestion engine into a full planning assistant.

The Calendar Flow

1. User accepts a suggestion → "That sounds perfect, let's do it Saturday at 7"
2. Offer calendar → "Want me to put this on the calendar?"
3. If yes → Create calendar event + set up reminders
4. Offer invites → "Want me to send the crew a heads up?" (see Group Invites & Reminders)
5. Confirm → "Game night is locked in — Saturday at 7, Scott's RV. Reminders set. The crew has been notified. 🎲"

Pre-Suggestion Calendar Check

Before generating suggestions, check the calendar for conflicts:

1. Check data/whatdo/history.json for any planned: true entries on the requested date
2. If Google Calendar API is available, query for events on the target date/time
3. Report findings naturally:
   • "You're free Saturday night — wide open!"
   • "Heads up, you've got something at 7pm Saturday. Want to plan around it? Earlier afternoon or later night?"
   • "You already have game night planned for Saturday — want to pick a different day?"

Creating Calendar Events

With Google Calendar API

If GOOGLE_CALENDAR_API_KEY or Google Calendar OAuth credentials are available, create events via the API:

# Create a calendar event via Google Calendar API (REST)
curl -s -X POST 'https://www.googleapis.com/calendar/v3/calendars/primary/events' \
  -H "Authorization: Bearer $GOOGLE_CALENDAR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Game Night — Catan Tournament 🎲",
    "location": "Scott'\''s RV",
    "description": "Game night with the crew. Bring beer (not Dave). Sarah gets veggie pizza.",
    "start": {
      "dateTime": "2026-01-28T19:00:00-07:00",
      "timeZone": "America/Phoenix"
    },
    "end": {
      "dateTime": "2026-01-28T23:00:00-07:00",
      "timeZone": "America/Phoenix"
    },
    "attendees": [
      {"email": "[email protected]"},
      {"email": "[email protected]"}
    ],
    "reminders": {
      "useDefault": false,
      "overrides": [
        {"method": "popup", "minutes": 120},
        {"method": "popup", "minutes": 30}
      ]
    }
  }'

Event creation details:

• Summary: Activity name + emoji for fun
• Location: From the suggestion or user-specified
• Description: Include group context, what to bring, dietary notes
• Attendees: Pull email addresses from group member contacts (only those with email field)
• Reminders: Default to 2 hours and 30 minutes before
• Duration: Default 4 hours for group activities, 3 hours for date night, 2 hours for casual
• Store the returned event_id in history.json as calendar_event_id

Without Google Calendar API (Cron Fallback)

If no calendar API is configured, use Clawdbot's cron tool to schedule reminders:

# Schedule a 2-hour-before reminder via cron
clawdbot cron add --at "2026-01-28T17:00:00" \
  --message "🎲 Game night with the crew in 2 hours — don't forget the beer! Scott's RV at 7pm" \
  --channel telegram

# Schedule a 30-minute-before reminder
clawdbot cron add --at "2026-01-28T18:30:00" \
  --message "🎲 Game night in 30 minutes! Heading to Scott's RV" \
  --channel telegram

# Schedule a day-of morning reminder
clawdbot cron add --at "2026-01-28T10:00:00" \
  --message "🎲 Game night tonight at 7 — Scott's RV. Pizza is on Scott, Sarah gets veggie." \
  --channel telegram

Always offer the fallback:

"No calendar hooked up? No worries — I can just send you reminders via cron so you don't forget."

Store the cron job IDs in history.json as reminder_cron_id (or an array if multiple).

Reminder Schedule

For planned events, set up these reminders by default:

Customize reminder messages with:

• Activity name and time
• Location
• What to bring (based on group preferences)
• Fun/personality — not robotic calendar alerts
• Dietary reminders: "Remember Sarah's veggie pizza"

Canceling / Rescheduling

• "Cancel game night" → Remove calendar event (if API), cancel cron reminders, update history entry, optionally notify the group
• "Move game night to 8pm" → Update calendar event, reschedule cron reminders, notify the group
• "What's on the calendar?" → List all planned: true entries from history with upcoming dates

Group Invites & Reminders

When a plan is locked in with a group, offer to send invites to the crew. This turns whatdo from a personal suggestion engine into a group coordination tool.

The Invite Flow

1. Plan is set → "Want me to send the crew a heads up?"
2. If yes → Compose a fun invite message and send via available channels
3. Track invites → Record who was invited and via which channel
4. Track RSVPs → Monitor responses and report status

Composing Invite Messages

Craft invite messages that are fun, informative, and on-brand:

Template:

🎲 PLAN ALERT!

What: Game Night — Catan Tournament
When: Saturday Jan 28 at 7pm
Where: Scott's RV
Bring: Your A-game (and beer, unless you're Dave)

Sarah: veggie pizza is covered 🌱
Who's in? 🙋

Rules for invite messages:

• Lead with an emoji and energy
• Include: what, when, where
• Add "bring this" notes based on group preferences
• Mention dietary accommodations so people feel included
• End with a call to action ("Who's in?")
• Keep it short — this isn't an essay, it's a text to your friends

Sending Invites

Send via the best available channel for each member:

Telegram (Primary)

# Use the message tool to send to a Telegram handle
message tool: action=send, target=@mikehandle, message="🎲 PLAN ALERT! Game night Saturday at 7..."

For each member with a telegram field in their contact info, use:

• message tool with action=send
• target = the member's Telegram handle (e.g., @mikehandle)
• message = the composed invite message

Other Channels

• Email: If only email is available, note it for the user: "I don't have a direct email tool — want me to draft the invite so you can send it?"
• Phone/SMS: Same approach — draft the message, user sends it
• No contact info: "I don't have contact info for Dave — want to add his Telegram? Say 'add Dave's telegram: @davehandle'"

Channel Priority

1. Telegram handle → send directly via message tool
2. Email → draft message for user to send
3. Phone → draft message for user to send
4. No contact → prompt user to add contact info

Tracking Invites

After sending, update the history entry:

{
  "invites_sent": true,
  "invited_via": {
    "Mike": "telegram",
    "Sarah": "telegram",
    "Dave": "no_contact"
  }
}

RSVP Tracking

After invites go out, track who's coming:

"rsvp": {
  "Mike": "yes",
  "Sarah": "pending",
  "Dave": "no"
}

RSVP States:

• "yes" — confirmed attending
• "no" — can't make it
• "pending" — invited but hasn't responded
• "maybe" — tentative

Updating RSVPs:

• User says "Mike's in" → set Mike to "yes"
• User says "Dave can't make it" → set Dave to "no"
• User says "Sarah said maybe" → set Sarah to "maybe"
• "Who's coming?" → report current RSVP status

RSVP Status Report:

🎲 Game Night — Saturday at 7pm

✅ Mike — in!
❓ Sarah — hasn't responded yet
❌ Dave — can't make it

2 of 4 confirmed. Want me to ping Sarah?

Smart RSVP Actions:

• If someone hasn't responded 24h before the event: "Sarah still hasn't RSVP'd for game night tomorrow — want me to send a nudge?"
• Before the event: "3 of 4 confirmed for game night tonight"
• If too many "no" responses: "Only 2 people confirmed — still want to do this or reschedule?"

Group Reminders

Send reminders to the whole group (not just the user) for planned events:

Day-of reminder (sent to all confirmed attendees):

🎲 Game night TONIGHT at 7 — Scott's RV. Pizza is on Scott! 🍕

Using cron for group reminders: Set up individual cron jobs for each group member with a Telegram handle:

# Reminder for Mike
clawdbot cron add --at "2026-01-28T17:00:00" \
  --message "🎲 Game night in 2 hours — Scott's RV at 7pm. Bring your A-game!" \
  --target @mikehandle --channel telegram

# Reminder for Sarah
clawdbot cron add --at "2026-01-28T17:00:00" \
  --message "🎲 Game night in 2 hours — Scott's RV at 7pm. Veggie pizza is covered! 🌱" \
  --target @sarah --channel telegram

Personalize reminders:

• Include dietary notes per person: "Veggie pizza is covered, Sarah!"
• Include role-specific notes: "Don't forget to bring the extra Catan expansion, Mike"
• Keep the fun tone — these should feel like texts from a friend, not calendar alerts

Managing Contacts

Prompt users to fill in contact info when it's missing and useful:

• When invites are requested but contacts are missing: "I don't have Telegram handles for Dave — want to add them? Say 'add Dave's telegram: @davehandle'"
• During group setup: "Want to add contact info for the crew? That way I can send invites and reminders directly"
• After a successful invite round: "That went smooth! Want to add contacts for the people I couldn't reach?"

Complete Planning Flow Example

Here's how all the pieces fit together:

User: "what should we do Saturday night with the crew?"

[Load game_night_crew profile]
[Check weather for Saturday]
[Check calendar — Saturday is free]

Bot: "You're free Saturday night and it's going to be 55°F and clear.

🎲 TONIGHT'S PLAY

🌤️ Weather: 55°F, clear — bonfire weather!

🥇 Top Pick: Catan Tournament Night
   📍 Scott's RV
   🍕 Homemade pizza + beer (veggie for Sarah, no booze for Dave)
   🎲 You haven't played Catan with the crew in 6 weeks — overdue!

🥈 Also Great: Bonfire + card games (Exploding Kittens is perfect for 4)

🎰 Wild Card: Thrift store challenge then dinner — $10 budget, best outfit wins

👍👎 How'd we do?"

User: "Catan night, let's do it at 7"

Bot: "Locked in! 🎲 Game night — Saturday at 7, Scott's RV.

📅 Want me to put this on the calendar?
📨 Want me to send the crew a heads up?"

User: "yeah do both"

[Create calendar event or cron reminders]
[Send invites to Mike (@mikehandle), Sarah (@sarah) via Telegram]
[Note: Dave has no Telegram — flag it]

Bot: "Done! ✅

📅 Calendar event created — reminders set for 2 hours and 30 minutes before
📨 Invites sent to Mike and Sarah via Telegram
⚠️ I don't have a Telegram handle for Dave — want to add it? Say 'add Dave's telegram: @handle'

Reminder schedule:
• Saturday 10am: Morning heads-up
• Saturday 5pm: 2-hour warning
• Saturday 6:30pm: 30-minute heads-up

Game night is ON. 🎲🍕"

User: "Mike's in, Dave can't make it"

Bot: "Updated!

✅ Mike — in!
❓ Sarah — hasn't responded yet
❌ Dave — can't make it

2 of 4 confirmed. Want me to ping Sarah?"

Stay Home Deep Mode

When the user wants to stay in, don't just say "watch a movie." Go deep.

Streaming Night 🍿

• Search trending content on their specific streaming services (via web_search)
• Present with context: "Just dropped on your Netflix: [show] — critics are calling it the best thing since Breaking Bad"
• Themed marathon suggestions: "80s movie marathon with period-appropriate snacks (Pop Rocks, Tab soda, Jiffy Pop)"
• "Foreign film roulette — spin the wheel: Korean thriller, French romance, or Japanese animation?"

Game Night 🎲

• Pick from their actual game library based on who's there
• Suggest pairings: "Catan + homemade pizza + craft beer flight"
• Tournament format: "Round-robin Catan tournament — loser does dishes"
• New game recommendations based on what they already love

Cooking Night 🍳

• Themed cook-offs: "Iron Chef night — secret ingredient revealed at 7pm"
• Recipe challenges: "Everyone picks a cuisine they've never cooked"
• "Around the world dinner — each course from a different country (apps: Japanese gyoza → mains: Indian butter chicken → dessert: French crème brûlée)"
• Bake-off: "Great British Bake-Off challenge — same recipe, best presentation wins"

DIY & Creative Night 🛠️

• Craft projects: "Candle making kit + wine = surprisingly fun evening"
• Home improvement: "That shelf you've been meaning to build? Tonight's the night"
• Creative builds: "Lego night — everyone gets a set and builds simultaneously"
• Art night: "Bob Ross along — YouTube + canvas + cheap acrylics"

Themed Nights 🎭

• "80s night: Ferris Bueller + synth playlist + neon accessories"
• "Around the world: each course from a different country, matching drinks, Spotify playlist by region"
• "Murder mystery dinner party — print a kit, assign characters, cook the menu"
• "Nostalgia night: childhood favorite movie + snacks you ate as a kid"
• "Spa night: face masks, ambient music, fancy bath stuff, cucumber water"

Generating Suggestions

After gathering answers (or in Quick Mode), generate specific, actionable, exciting suggestions.

Context Awareness

Before generating suggestions, check ALL of these:

1. Calendar conflicts — Check for existing plans (see Calendar Integration section)

   • Check data/whatdo/history.json for planned: true entries on the target date
   • If Google Calendar API is available, query for events
   • Report: "You're free Saturday night!" or "You've got something at 7 — plan around it?"

2. Weather — Check live weather (see Weather Integration section)

   • Outdoor-friendly? Push outdoor options
   • Bad weather? Auto-pivot indoor
   • Include weather in output

3. Time awareness — What day/time is it?

   • Tuesday night → lower-key suggestions, things that work on weeknights + check routines
   • Friday/Saturday night → go bigger, more options are open
   • Sunday afternoon → brunch, outdoor stuff, chill activities
   • Late night → 24-hour spots, home activities, stargazing

4. Routines — Is today a routine day?

   • Match day of week to saved routines
   • Check for monthly/seasonal traditions
   • Check for overdue favorite activities

5. Location awareness — Read USER.md for where the user is

   • Urban → more venue-based options
   • Rural/outdoor → nature-focused, scenic drives, stargazing
   • Traveling → "tourist in a new town" suggestions

6. Group context — Is a group mentioned?

   • Load group profile, apply dietary/alcohol/preference filters
   • Match game suggestions to group size
   • Check member contacts for invite capability

7. History check — Read data/whatdo/history.json

   • Don't suggest the same thing within 2 weeks
   • If they've been doing lots of indoor stuff, nudge outdoors (and vice versa)
   • "Last time you did [X] and seemed to love it — want to try [related Y]?"

8. Favorites & blacklist — Check before presenting

   • Never suggest blacklisted places or disliked activities
   • Resurface favorites when relevant

9. Preference check — Read data/whatdo/preferences.json

   • Respect dietary restrictions, alcohol preferences, physical limitations
   • Lean into known interests
   • Occasionally challenge them with something outside their usual picks

The Idea Well

Draw from these categories, mixing and matching based on answers:

🍕 Food & Drink

• Restaurant adventures: "Find a hole-in-the-wall ramen spot you've never tried and sit at the bar"
• Food experiences: food truck rally, cooking class, farmers market, progressive dinner (appetizers at one place, mains at another, dessert at a third)
• Drink experiences: cocktail bar with no menu (tell the bartender what you like), brewery tour, wine tasting, speakeasy hunt, mocktail night
• At-home food: cook a cuisine you've never attempted, blind taste test, homemade pizza night with weird toppings competition, "Chopped" challenge with random ingredients

🎬 Movies & Entertainment

• Local showtimes: search for what's actually playing nearby tonight (see Movie Showtimes section)
• Drive-in theater, outdoor screening, themed movie marathon
• Streaming: trending on their services, curated picks (see Streaming section)
• Live music: local band at a dive bar, open mic night, jazz club, surprise concert
• Comedy: comedy club, improv show, stand-up open mic
• Games: board game cafe, escape room, laser tag, retro arcade, bowling, axe throwing, mini golf, go-karts
• Arts: gallery walk (first Friday events), museum, pottery class, paint night, glassblowing demo

🏔️ Outdoor/Active (weather-dependent — check conditions first!)

• Hiking a trail you've never done, mountain biking, kayaking, paddleboarding
• Geocaching, urban exploring, photo walk with a theme ("only shoot reflections")
• Stargazing — drive to the nearest dark sky area with blankets and hot drinks
• Sunrise/sunset spots, scenic drives with no destination
• Sports: pick-up basketball, disc golf, rock climbing gym, driving range

🛋️ Chill/Home (see Stay Home Deep Mode for full treatment)

• Game night: suggest from their library matched to group size
• Streaming: trending on their specific services
• Cook-off / bake-off challenge
• Build something: Lego set, massive puzzle, DIY project
• Themed nights: "80s movie marathon with period-appropriate snacks"

🦑 Unique/Weird

• Thrift store challenge: $10 budget, best outfit wins
• Random road trip: pick a direction, drive 1 hour, explore whatever you find
• Tourist in your own town: do ALL the tourist stuff you've never bothered with
• Learn something random: pick a YouTube rabbit hole topic (lock picking, bonsai, blacksmithing)
• Photo scavenger hunt around town
• "Yes Night" — take turns suggesting things, nobody can say no (within reason!)
• Attend a meetup or event for something you know nothing about

💕 Date Night Specials

• Recreate your first date
• Cook a fancy meal together with candles and music
• Take a class: dancing, pottery, cooking, mixology
• No-phone dinner challenge at a restaurant neither of you has tried
• Surprise evening: one person plans everything, the other knows nothing
• Progressive dinner: walk to 3 different spots for courses
• "Travel" night: cook food from a country, watch a film from there, learn 5 phrases

👥 Group Specials (load group profile if available)

• Trivia night at a bar
• Potluck with a theme: "dishes from countries you've never visited"
• Karaoke (bonus: everyone picks songs for someone else) (skip if disliked_activities includes karaoke)
• Tournament night: from their game library, matched to group size
• Murder mystery dinner
• Bonfire + storytelling night
• Group cooking challenge: teams of 2, same ingredients, best dish wins

Output Format

Standard Output

Present suggestions in this format:

🎲 TONIGHT'S PLAY

🌤️ Weather: 72°F, clear skies — great night to be outside!

🥇 Top Pick: [Specific suggestion with real details]
   📍 [Place name] — ⭐ 4.6 (1,200 reviews) — Open until 11pm
   🔗 [Google Maps link]
   💰 $$

🥈 Also Great: [Alternative with details]

🎰 Wild Card: [Something unexpected they'd never think of]

💡 Pro tip: [Relevant tip for the activity]

👍👎 How'd we do? (helps me learn your taste)

Rules:

• Always include weather line
• Always give 2-3 options plus a wild card
• If Google Places is available: include ratings, hours, price level, Maps links
• If Google Places is NOT available: describe the type of place, add "Search Google Maps for '[type] near me'"
• Always include the thumbs up/down prompt to build preferences
• Make every suggestion specific and actionable — not "go to a restaurant" but "Find the highest-rated Ethiopian restaurant within 20 minutes that you've never tried — order the combination platter and eat with your hands"

Stay Home Output

🎲 TONIGHT'S PLAY (Home Edition)

🍿 Main Event: [Curated home activity with specifics]
   📺 [Streaming picks if relevant — from their services]
   🎲 [Game picks if relevant — from their library]

🍕 Pair It With: [Food/drink pairing suggestion]

🎰 Wild Card: [Creative home activity they wouldn't think of]

💡 Pro tip: [Make it special — ambiance, snacks, themes]

👍👎 How'd we do? (helps me learn your taste)

Surprise Me Output

🎰 SURPRISE PLAY!

🌤️ Weather: [current conditions]

🎯 DO THIS: [Bold, specific, exciting suggestion with full details]
   📍 [Place/details]

🪂 Too wild? Try this instead: [Slightly tamer alternative]

⏰ Go. Now. Stop reading and start doing.

👍👎 How'd we do? (helps me learn your taste)

Google Places Integration (Optional Enhancement)

If the environment variable GOOGLE_PLACES_API_KEY is available, use it to enhance suggestions with real, nearby places.

How to Use

Text Search (best for specific types):

curl -s -X POST 'https://places.googleapis.com/v1/places:searchText' \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: $GOOGLE_PLACES_API_KEY" \
  -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.rating,places.userRatingCount,places.priceLevel,places.googleMapsUri,places.types,places.currentOpeningHours" \
  -d '{
    "textQuery": "best ramen restaurant in Scottsdale AZ",
    "maxResultCount": 5
  }'

Nearby Search (best for "near me" suggestions):

curl -s -X POST 'https://places.googleapis.com/v1/places:searchNearby' \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: $GOOGLE_PLACES_API_KEY" \
  -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.rating,places.userRatingCount,places.priceLevel,places.googleMapsUri,places.types,places.currentOpeningHours" \
  -d '{
    "includedTypes": ["restaurant"],
    "maxResultCount": 5,
    "locationRestriction": {
      "circle": {
        "center": {"latitude": 33.8303, "longitude": -111.9258},
        "radius": 16000
      }
    }
  }'

Places Processing Rules

1. Always request currentOpeningHours — filter out places that are currently closed
2. Apply ratings floor — default 4.0 stars, or min_rating from preferences
3. Sort by rating — highest first
4. Include userRatingCount — show as "⭐ 4.6 (2,341 reviews)"
5. Show hours — "Open until 11pm" or calculate "Closes in 2 hours"
6. If closing soon (<1 hour) — add warning: "⚠️ Closes at 10pm — hustle!"
7. Always include googleMapsUri — direct link for navigation
8. Show price level — translate to $ symbols

Without Places API

• Still give amazing suggestions — just describe the type of place
• Add: "Search Google Maps for '[type of place] near me' to find the perfect spot"
• Suggest checking hours: "Make sure to check hours on Google Maps before heading out"
• The skill works great either way; Places just adds a cherry on top

"Surprise Me" Mode

When someone says "surprise me" or wants you to skip the questions:

1. Check the current day/time for context
2. Check weather — web_search for current conditions
3. Read preferences.json for known likes/dislikes/favorites
4. Read history.json to avoid repeats
5. Check USER.md for location context
6. Check routines for today
7. Generate ONE bold, specific suggestion with maximum enthusiasm
8. Make it something they probably wouldn't pick for themselves
9. Add a "if that's too wild" backup option
10. Include the 👍👎 prompt

Saving Preferences

When you learn something about the user's preferences — either explicitly ("remember I don't drink") or implicitly (they always pick outdoor stuff) — save it to data/whatdo/preferences.json.

Preference Triggers

Tracking History

After suggesting activities, log them in data/whatdo/history.json:

{
  "suggestions": [
    {
      "date": "2026-01-15",
      "day": "Wednesday",
      "context": "date night, adventurous, going out, moderate budget",
      "group": "date_night",
      "weather": "65°F, clear",
      "top_pick": "Ethiopian restaurant — eat with your hands, order the combo platter",
      "also_suggested": ["cocktail bar with no menu", "late-night taco crawl"],
      "wild_card": "Attend a random meetup for a hobby neither of you has tried",
      "feedback": null,
      "planned": false
    }
  ]
}

Planned Event History Entry

When a suggestion is accepted and scheduled, upgrade the entry with planning fields:

{
  "date": "2026-01-28",
  "day": "Saturday",
  "context": "game night with the crew",
  "group": "game_night_crew",
  "weather": "55°F, clear",
  "top_pick": "Game night — Catan tournament + homemade pizza",
  "also_suggested": [],
  "wild_card": null,
  "feedback": null,
  "planned": true,
  "time": "19:00",
  "activity": "Game night",
  "location": "Scott's RV",
  "calendar_event_id": "abc123",
  "reminder_cron_id": "xyz789",
  "invites_sent": true,
  "invited_via": {
    "Mike": "telegram",
    "Sarah": "telegram",
    "Dave": "cron_reminder"
  },
  "rsvp": {
    "Mike": "yes",
    "Sarah": "pending",
    "Dave": "no"
  }
}

If the user says "that was awesome" or "we didn't end up doing that," update the feedback field. Use feedback to improve future suggestions.

Tone Guide

• Enthusiastic but not annoying — "oh this is gonna be good" energy
• Specific — never vague. Paint a picture.
• Slightly pushy — "you should absolutely do this" not "you might consider"
• Funny when natural — don't force it, but don't be a robot
• Encouraging — "you won't regret this" vibes
• Anti-couch — your job is to get people OFF the couch and INTO life (unless they want to stay home, then make staying home incredible)
• Weather-aware — weave conditions into your enthusiasm: "It's 72° and clear tonight — you'd be insane to stay inside"

Example Tone

❌ "You could perhaps visit a local dining establishment." ✅ "There's a tiny ramen shop with 12 seats and a line out the door — that's the one. Get the spicy miso and don't you dare skip the soft-boiled egg."

❌ "Consider an outdoor activity." ✅ "Grab a headlamp, lace up your boots, and hit that trail at golden hour. The last mile before sunset? That's the stuff Instagram wishes it could capture."

❌ "Maybe watch something on TV." ✅ "Just dropped on your Netflix: The Thursday Murder Club — think cozy British mystery meets Ocean's Eleven. Critics are losing their minds. Pair it with takeout curry and a blanket fort."

First-Time Setup

If data/whatdo/preferences.json doesn't exist:

1. Create data/whatdo/ directory
2. Initialize preferences.json with empty defaults:

{
  "last_updated": "",
  "dietary": [],
  "alcohol": "yes",
  "energy_default": "moderate",
  "favorite_vibes": [],
  "favorite_categories": [],
  "location_notes": "",
  "notes": [],
  "streaming_services": [],
  "board_games": [],
  "card_games": [],
  "video_games": {"console": "", "games": []},
  "game_preferences": [],
  "favorite_places": [],
  "blacklist_places": [],
  "favorite_activities": [],
  "disliked_activities": [],
  "min_rating": 4.0,
  "groups": {},
  "routines": []
}

3. Initialize history.json with empty suggestions array
4. Read USER.md for any context you can pre-populate (location, interests, etc.)
5. Ask the essentials (keep it fun, not bureaucratic):
   • "Quick setup so I can nail these suggestions:"
   • "What streaming services do you have?" (list common ones as buttons if possible)
   • "Any board games, card games, or video games you own?"
   • "Any dietary restrictions I should know about?"
   • "Do you have regular crews? Give me a name and who's in it (like 'game night crew: Mike, Sarah, Dave')"
   • "Any places you love or places I should NEVER suggest?"
6. Save whatever they give you — don't force all questions
7. Jump right into the fun — "Alright, we're locked in. What should we do tonight?"