[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_198":199,"_200":201},"routes/_app.x.$handle.$name",{"_96":95,"_32":43,"_104":86,"_26":51,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":24,"_118":119,"_120":24,"_121":-5,"_122":-5,"_123":124},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_41":42,"_32":43,"_36":44,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":24},"version",5,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":-7,"_23":24,"_25":24,"_26":27,"_28":29},"file",{"_30":31,"_32":27,"_33":20,"_34":35,"_36":37,"_38":14,"_39":40,"_23":24},"previous","deleted",false,"deletedHere","path","BLUESKY_BOT_THESIS.md","latestPath","docs/bsky-bot-thesis.md","fileId","34474704-fa4c-11f0-98a8-42dde27851f2","name","fileType","content","# Chicago Free Museum Days Bluesky Bot\n\n## The Opportunity\n\nThere's a clear gap in the Chicago cultural information ecosystem: **no Bluesky bot exists to notify residents about free museum days.**\n\nThe information aggregation problem is largely solved by existing websites (Choose Chicago, Upparent, Do312), but the distribution/discoverability problem is not.\n\nA Bluesky bot would:\n- Passively surface free days to people who already use the platform\n- Fill a civic information niche that's underserved on Bluesky\n- Require minimal code and maintenance\n- Generate reusable data for other formats (ICS feed, embeddable widget)\n\n## Existing Landscape\n\n### Web Aggregators\n\n| Site | Format | Calendar | ICS/Subscribe | Filtering | Strengths | Gaps |\n|------|--------|----------|---------------|-----------|-----------|------|\n| [Choose Chicago](https://www.choosechicago.com/articles/museums-art/free-museum-days-in-chicago/) | Editorial | ✗ | ✗ | ✗ | Official, comprehensive | Static, no interactivity |\n| [Upparent](https://www.upparent.com/lists/free-museum-days-chicago) | Interactive list | ✓ Date picker | Newsletter | ✓ Sort/filter | Calendar view, ratings | Parent-focused, no ICS |\n| [Do312](https://do312.com/p/chicago-free-museum-days) | Long-form guide | ✗ | Newsletter | ✗ | Rich descriptions | Must manually parse |\n| [My Kid List](https://mykidlist.com/museum-free-days/) | Editorial list | ✗ | Daily/weekly email | ✗ | Comprehensive, updated | Static layout |\n| [Loop Chicago](https://loopchicago.com/in-the-loop/2025-free-museum-days/) | Blog post | ✗ | ✗ | ✗ | Clean layout | Annual refresh only |\n\n### Existing Social Bot\n\n**[@FreeMuseumDay](https://twitter.com/FreeMuseumDay)** on Twitter\n- Covers: Portland, SF, Boston, Chicago, LA, NYC, Seattle\n- Links to freemuseumday.org for details\n- Status: Appears dormant or minimally active on Chicago posts\n\n### Bluesky Bot Space\n\n- **No free museum days bot exists on Bluesky**\n- Bluesky is growing rapidly but has fewer bots than Twitter\n- Civic information niche is underserved\n- Lower noise/competition for attention\n\n---\n\n## What Needs to Be Scraped\n\n### Data Sources (Priority Order)\n\n#### 1. **Aggregator Sites** (Recommended Primary)\nThese do the heavy lifting of compiling from individual institutions. Scrape these instead of hitting each museum:\n\n- **[Choose Chicago](https://www.choosechicago.com/articles/museums-art/free-museum-days-in-chicago/)**\n - Format: H3 headings per museum + bulleted date lists\n - Structure: Clean semantic HTML (`

`)\n - Update frequency: Periodic (2-3x per year)\n - Scraping strategy: Parse H3 for institution name, extract `
` dates\n\n- **[Loop Chicago](https://loopchicago.com/in-the-loop/2025-free-museum-days/)**\n - Format: Museum section + free day listings\n - Structure: Similar semantic HTML layout\n - Update frequency: Annual refresh (early January)\n - Scraping strategy: Same as above\n\n#### 2. **Individual Museum Sites** (Fallback/Supplement)\n\n**Recurring patterns** (no scraping needed, hardcode rules):\n- Field Museum: Every Wednesday\n- DuSable Black History Museum: Every Wednesday\n- Peggy Notebaert Nature Museum: Every Thursday\n- MCA Chicago: Every Tuesday 5-9pm (year-round)\n- Lincoln Park Zoo: Every day (always free)\n- National Museum of Mexican Art: Every day (always free)\n- Chicago Cultural Center: Every day (always free)\n\n**Scattered/seasonal dates** (need scraping):\n- Art Institute: Seasonal weekday windows (Jan-Feb, etc.)\n- Shedd Aquarium: Specific date ranges, varies by month\n- Griffin MSI: 15-20 specific dates scattered across year\n- Chicago History Museum: Mix of holidays + promotional dates\n- Adler Planetarium: Scattered dates + seasonal Tuesday nights\n- Chicago Botanic Garden: Specific dates, requires registration\n\n**Scraping challenges:**\n- Some sites use JavaScript rendering (need Playwright/Puppeteer)\n- Some return 403 on direct fetches (Shedd)\n- Date formats inconsistent within and across sites\n- Eligibility rules embedded in prose\n\n#### 3. **City/Civic Data Sources** (Low Priority)\n- Checked [data.cityofchicago.org](https://data.cityofchicago.org/) — no dedicated museum free days API\n- Not likely to exist in the near future\n\n### Data Normalization Challenge\n\nFree days fall into two categories that need different handling:\n\n**Recurring patterns:**\n```yaml\n- institution: \"Field Museum\"\n free_day_type: \"recurring\"\n pattern: \"every Wednesday\"\n time: \"9am-5pm\"\n proof_of_residency: \"Illinois ID required\"\n```\n\n**Scattered/seasonal dates:**\n```yaml\n- institution: \"Art Institute\"\n free_day_type: \"dated\"\n dates:\n - start: \"2026-01-05\"\n end: \"2026-02-28\"\n pattern: \"weekdays only\"\n time: \"11am-close\"\n proof_of_residency: \"ZIP code verification\"\n```\n\n**Normalization needs:**\n- Convert prose patterns (\"January 19-23, 27-30\") → actual date lists\n- Standardize time formats\n- Document proof-of-residency requirements consistently\n- Flag when scraping source becomes stale\n\n---\n\n## Why a Bluesky Bot is the Right First Step\n\n### Advantages\n\n1. **Minimal code required**\n - ~100 lines of TypeScript/JavaScript\n - Bluesky SDK is simple and well-documented\n - GitHub Actions handles scheduling\n\n2. **Zero infrastructure cost**\n - GitHub Actions is free\n - No database (data lives in git)\n - No hosting fees\n\n3. **Low maintenance burden**\n - Monthly or quarterly scrape updates\n - GitHub Actions logs for monitoring\n - Community PRs can help maintain data\n\n4. **Proven format for Bluesky**\n - Simple daily/weekly posts work well on platform\n - Civic information is valued by Bluesky community\n - Low friction to follow and engage\n\n5. **Reusable data pipeline**\n - Scraper output feeds bot, ICS feed, future embeddable widget\n - Single source of truth in version control\n - Easy to validate and review changes\n\n### Why NOT a Website\n\n- Aggregator sites already solve this problem adequately\n- Users are fragmented across multiple platforms (email, calendar, social)\n- Web traffic for this niche is low\n- Maintenance burden higher than a bot\n\n### Why NOT an Email Newsletter\n\n- Lower engagement than social platform for casual discovery\n- Requires email list building and maintenance\n- Subject to spam filters\n- Already exists in limited form (My Kid List offers daily/weekly emails)\n\n### Why Bluesky Specifically\n\n- **No competition.** Twitter has @FreeMuseumDay (dormant). Bluesky has nothing.\n- **Growing audience.** Bluesky is experiencing rapid adoption, especially among civic-minded users.\n- **Civic information is valued.** Bluesky users appreciate local information, mutual aid bots, etc.\n- **Easier to build bot culture.** Fewer bots total = less noise, more discovery.\n- **Lower barrier to entry.** Small bots can find their audience; don't need millions of followers.\n\n---\n\n## Technical Approach\n\n### Data Pipeline\n\n```bash\nChoose Chicago / Loop Chicago (web)\n ↓\nScraper (Node.js + cheerio or similar)\n ↓\nNormalize to YAML (recutils format)\n ↓\nGitHub repo with git history\n ↓\n[Branch 1] Bluesky Bot (posts daily/weekly)\n[Branch 2] ICS Feed Generator (for calendar apps)\n[Branch 3] Future: Embeddable widget\n```\n\n### Minimal Bot Implementation\n\n**Stack:**\n- Node.js + TypeScript (or Python)\n- Bluesky SDK (`@atproto/api`)\n- GitHub Actions (cron schedule)\n- Data: YAML files in git\n\n**Posting schedule:**\n- Monday morning: \"Here's what's free this week\"\n- Could also do: Daily post, weekly digest, or real-time alerts\n\n**Example bot post:**\n```\n🏛️ What's free in Chicago this week:\n\n• Art Institute: Mon-Fri (weekdays only)\n• Field Museum: Wednesday\n• MCA: Tuesday evenings 5-9pm\n\n+ 3 more (thread 🧵)\n\nData source: github.com/your-repo\n```\n\n### Data Storage Format\n\nUse YAML or recutils (your prior research interest):\n\n**YAML approach:**\n```yaml\ninstitutions:\n - id: \"art-institute\"\n name: \"Art Institute of Chicago\"\n address: \"111 S Michigan Ave\"\n website: \"artic.edu\"\n free_days:\n - type: \"seasonal\"\n periods:\n - name: \"Winter Weekdays\"\n start: \"2026-01-05\"\n end: \"2026-02-28\"\n pattern: \"Mon, Wed, Thu, Fri\"\n time: \"11am-close\"\n proof_of_residency: \"ZIP code verification\"\n - type: \"permanent\"\n eligibility:\n - \"Children under 14 (always free)\"\n - \"Chicago residents under 18 (always free)\"\n\n - id: \"field-museum\"\n name: \"Field Museum\"\n address: \"1400 S Lake Shore Dr\"\n website: \"fieldmuseum.org\"\n free_days:\n - type: \"recurring\"\n pattern: \"every Wednesday\"\n time: \"9am-5pm\"\n proof_of_residency: \"Illinois ID required\"\n```\n\n**Recutils approach:**\n```\nid: art-institute\nname: Art Institute of Chicago\naddress: 111 S Michigan Ave\nwebsite: artic.edu\nfree_day_type: seasonal\nfree_period_start: 2026-01-05\nfree_period_end: 2026-02-28\nfree_pattern: Mon,Wed,Thu,Fri\nfree_time: 11am-close\nproof_of_residency: ZIP code verification\n```\n\nEither format works; choose based on preference.\n\n---\n\n## First Steps to Validate\n\n1. **Audit the scraping targets** (Done ✓)\n - Choose Chicago and Loop Chicago are primary targets\n - Both have semantic HTML suitable for scraping\n - Update frequency: 2-3x per year\n\n2. **Build a minimal scraper**\n - Extract one institution's data from Choose Chicago\n - Test date normalization logic\n - Validate against official museum sites\n\n3. **Create test data file**\n - Manually enter ~15 institutions with current free days\n - Structure in YAML/recutils\n - This becomes the seed for bot posts\n\n4. **Build minimal bot**\n - Post hardcoded message to test Bluesky SDK\n - Schedule with GitHub Actions\n - Verify it works\n\n5. **Automate scraper → data**\n - Hook scraper into GitHub Actions workflow\n - Run weekly/monthly, commit changes as PRs\n - Review diffs before merging\n\n6. **Launch bot**\n - Post sample messages for next week\n - Seed with followers (share in Chicago communities)\n - Monitor engagement\n\n---\n\n## Success Metrics\n\n- **Low bar for success:**\n - Bot posts on schedule without errors\n - Data stays in sync with institution calendars\n - Minimal manual maintenance (<1hr/month)\n\n- **Bonus outcomes:**\n - Community contributions (PRs with new institutions or corrections)\n - ICS feed reuse (users subscribe in calendar apps)\n - Potential expansion to other cities\n\n- **Failure case:**\n - Requires more than 2-3 hours of maintenance per month\n - Museums change data format too frequently\n - Bluesky account gets no engagement (unlikely, but acceptable)\n\nEven failure is low-cost: you've proven the concept and built reusable data/code.\n\n---\n\n## Risks & Mitigations\n\n| Risk | Likelihood | Mitigation |\n|------|------------|-----------|\n| Scraper breaks when site changes | Medium | Monitor scraper logs, pin HTML selectors to institutions, accept manual updates |\n| Date format inconsistencies | High | Build robust date parser, test against 2-3 years of historical data |\n| Proof-of-residency rules change | Low | Version control, document changes in git history |\n| Low bot engagement | Low (civic info is valued) | Share in Chicago subreddits, tag museums, local journalists |\n| Maintenance burden grows | Medium | Keep data structure simple, automate everything possible |\n\n---\n\n## Next: The ICS Feed\n\nOnce the bot is stable, generating an ICS calendar feed is trivial:\n\n```javascript\n// Pseudocode\ninstitutions.forEach(inst => {\n inst.free_days.forEach(day => {\n const event = {\n summary: `Free: ${inst.name}`,\n date: day.date,\n description: `Address: ${inst.address}\\nProof: ${day.proof_of_residency}`,\n };\n calendar.addEvent(event);\n });\n});\n\nfs.writeFileSync(\"chicago-free-days.ics\", calendar.toICS());\n```\n\nUsers could subscribe in Google Calendar, Apple Calendar, Outlook. This is Direction 2 from your research.\n\n---\n\n## Conclusion\n\n**Building a Bluesky bot is the highest-ROI first step** because it:\n- Validates the data collection and normalization process\n- Fills a genuine gap on the platform\n- Requires minimal code and infrastructure\n- Generates reusable data for ICS feed and future formats\n- Is low-cost to maintain or abandon\n\nThe bar for success is low. The potential upside is genuine (civic value + community engagement). The learning is high (data pipeline, scraping, bot APIs, git workflows).\n\nWorth building.\n","createdAt",["D",1769386564906],"branchVersion","branchId","33471352-fa4c-11f0-8dfc-42dde27851f2","id","3346c51e-fa4c-11f0-8dfc-42dde27851f2","chicago-resident-days",["D",1769386563309],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","3346c51efa4c11f08dfc42dde27851f2","tursoHostname","3346c51efa4c11f08dfc42dde27851f2-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789532458193],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},"branch",{"_13":85,"_32":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"isOwned",51,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_41":42,"_32":43,"_36":193,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":-5,"_55":24,"_56":-5,"_57":-5,"_58":59,"_60":61,"_62":63,"_64":65,"_66":194,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":195,"_80":196,"_82":197,"_84":24},"tree",[168,170,171,172],"files",[168,169,170,171,172],"counts",{"_157":59,"_158":152,"_159":59,"_160":161,"_162":163},"contents",[125,126,127,128],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_41":149,"_32":150,"_30":151,"_132":-5,"_39":40,"_38":152,"_134":153,"_36":154,"_13":59,"_33":155,"_34":-5,"_23":24,"_137":-5,"_26":156},{"_41":146,"_32":27,"_30":31,"_132":-5,"_39":40,"_38":14,"_134":24,"_36":147,"_13":59,"_33":20,"_34":35,"_23":24,"_137":-5,"_26":148},{"_41":139,"_32":140,"_30":141,"_132":-5,"_39":40,"_38":142,"_134":24,"_36":143,"_13":59,"_33":20,"_34":144,"_23":24,"_137":-5,"_26":145},{"_41":129,"_32":130,"_30":131,"_132":-5,"_39":40,"_38":133,"_134":24,"_36":135,"_13":59,"_33":20,"_34":136,"_23":24,"_137":-5,"_26":138},"3439c070-fa4c-11f0-8dfc-42dde27851f2","research.md","3439c0fc-fa4c-11f0-8dfc-42dde27851f2","parentId",3,"latest",["D",1769386564908],"# Chicago Free Resident Days App - Exploration\n\n## Core Insight Deconstruction\n\nThe underlying insight here is threefold:\n\n1. **Information asymmetry creates missed value** - Chicago offers numerous free admission days at museums, zoos, gardens, and cultural institutions for residents, but this information is fragmented across dozens of websites, each with their own calendars, eligibility rules, and update schedules.\n\n2. **Temporal relevance is key** - A static list is nearly useless. The value comes from knowing what's free _today_, _this weekend_, or _when I'm actually free_. This is a calendar problem disguised as a directory problem.\n\n3. **Civic benefit meets personal planning** - These programs exist to increase cultural access, but friction in discovery undermines that goal. Reducing friction serves both individual users and the broader civic intent.\n\n## Directions to Explore\n\n### Direction 1: Pure Scraper + Static Site\n\n- **Description:** Build scrapers for each institution's calendar, aggregate into a single JSON feed, publish as a minimal static site (perhaps using the recutils format from your prior research for the data layer). No accounts, no backend, just a daily-updated list.\n- **Why it could work:** Extremely low maintenance cost, can be run on GitHub Actions for free, no infrastructure to manage. Fits the \"tools, not products\" ethos.\n- **Risks:** Scraping is brittle—sites change, some use JavaScript rendering, anti-bot measures. Could break silently. Also, no personalization.\n- **First step:** Audit 5-10 major Chicago institutions (Art Institute, Field Museum, Shedd, MSI, Lincoln Park Zoo, etc.) and catalog their calendar URL structures and data formats.\n\n### Direction 2: Calendar Subscription Feed (ICS)\n\n- **Description:** Instead of (or in addition to) a website, generate an ICS calendar feed that users can subscribe to in their existing calendar apps. Each free day becomes an all-day event with the institution name, address, and any eligibility notes.\n- **Why it could work:** Meets users where they already live—their calendar. Zero app switching. Passive discovery. Could reference your minimalist AI calendar research for sync patterns.\n- **Risks:** ICS feeds are pull-based and cache unpredictably. Users might see stale data. Also limited in richness—no images, no deep linking.\n- **First step:** Generate a sample ICS file manually with 10 upcoming free days and test subscription behavior across Google Calendar, Apple Calendar, and Outlook.\n\n### Direction 3: SMS/Push Notification Service\n\n- **Description:** Let users subscribe to alerts (SMS, email, or push) based on preferences: \"Tell me about any free days in the next 7 days\" or \"Alert me when the Art Institute has a free day.\" Proactive nudges rather than passive discovery.\n- **Why it could work:** Solves the \"I forgot to check\" problem. High engagement potential for time-sensitive info.\n- **Risks:** Requires user accounts, preferences storage, notification infrastructure. Much more complex. Potential cost at scale (SMS fees, push services).\n- **First step:** Define 3-5 notification \"recipes\" that would cover most use cases and sketch the preference UI.\n\n### Direction 4: Civic Data Partnership\n\n- **Description:** Instead of scraping, reach out to Choose Chicago, the Chicago Cultural Alliance, or individual institutions to get official data feeds or partnership. Position as a civic tech project that amplifies their programs.\n- **Why it could work:** Clean data, no scraping fragility, potential for co-promotion. Some cities have official APIs for this kind of civic info.\n- **Risks:** Slow—requires relationship building, likely bureaucratic. Might never materialize. Also removes the \"just build it\" energy.\n- **First step:** Research whether Chicago has any existing open data portals covering cultural events. Check data.cityofchicago.org.\n\n### Direction 5: Community-Sourced Corrections\n\n- **Description:** Accept that scrapers will break. Build a lightweight community layer—maybe just a GitHub repo where anyone can submit corrections, add new institutions, or flag outdated info. Use GitHub Actions to merge validated changes into the live feed.\n- **Why it could work:** Distributes the maintenance burden. Creates investment from users. Aligns with open-source ethos.\n- **Risks:** Requires critical mass of contributors. Could become a ghost town. Also, spam/vandalism potential (though low for this niche).\n- **First step:** Design the contribution format—perhaps a simple YAML or recutils file per institution, with schema validation on PR.\n\n### Direction 6: \"Free Day Trip Planner\" with Context\n\n- **Description:** Go beyond listing free days—help users plan around them. Show nearby free parking, CTA routes, nearby restaurants with lunch specials, estimated crowd levels, what exhibits are currently showing. Turn a free museum day into a complete outing.\n- **Why it could work:** Dramatically higher value per visit. Differentiates from a simple calendar. Could integrate Schema.org data (your prior research).\n- **Risks:** Scope explosion. Each additional data source is another scraping target. Could become unwieldy.\n- **First step:** Pick one institution and manually assemble a \"complete outing\" data package to see what's actually useful.\n\n### Direction 7: Embeddable Widget for Local Media\n\n- **Description:** Build an embeddable widget that local news sites, blogs, or community organizations could drop into their pages. \"This week's free days\" as a reusable component.\n- **Why it could work:** Distribution through existing trusted channels. Could drive organic traffic back to main site. Serves local journalism's community mission.\n- **Risks:** Requires polished, reliable widget. Support burden if widely adopted. Also, modern sites might have CSP restrictions on embeds.\n- **First step:** Build a simple iframe-based widget and test embedding in a personal blog.\n\n### Direction 8: Hyperlocal Expansion Framework\n\n- **Description:** Design the architecture so the Chicago scraper is just the first instance. Build it as a framework where someone could fork and adapt for NYC, LA, or any city with similar programs. Parameterized by city + institution list.\n- **Why it could work:** Multiplies impact. Attracts contributors who want it for their city. Could become a mini-movement.\n- **Risks:** Premature generalization before proving value in one city. Different cities have wildly different program structures.\n- **First step:** Identify 2-3 other cities known for free museum days (NYC has culture pass, many cities have \"first Sunday free\" patterns) and assess structural similarities.\n\n## Unexpected Connections\n\n- **Recutils as data layer** - Your prior research on recutils could be perfect here. Each institution is a record, each free day is a record linked to it. Human-readable, git-diffable, no database needed.\n\n- **Card game generator logic** - The constraint-based generation from your card game research could apply here: \"Generate a weekend plan given: 2 free museums, 1 outdoor activity, must include lunch, budget $40.\" Combinatorial planning on top of the calendar data.\n\n- **Bookmarking app's \"surfacing\" problem** - Your bookmarking research was about re-surfacing saved items at the right moment. Same core problem: these free days are \"bookmarked\" by the city, but users need them surfaced when relevant.\n\n- **Weather integration** - A free day at Lincoln Park Zoo is very different in January vs. June. Layering weather data could help users decide which free days are actually worth taking.\n\n- **Proof of residency angle** - Many free days require proof of Chicago residency (utility bill, ID). The app could include \"what to bring\" reminders—a small but high-value detail.\n\n## Questions Worth Answering\n\n1. **What's the complete list of Chicago institutions offering free resident days?** This seems knowable but I've never seen a canonical list. Is it 15 places? 50?\n\n2. **How often do the free day schedules change?** Are they set annually, quarterly, or do they shift month-to-month? This determines scraping frequency.\n\n3. **Are there legal/ToS concerns with scraping these calendars?** Most are public info, but some sites have aggressive ToS. Worth reviewing before investing heavily.\n\n4. **What's the actual user journey today?** How do Chicagoans currently discover free days? Word of mouth? Googling per-institution? Is there a subreddit or Facebook group serving this need already?\n\n5. **Would a \"free day\" notification feel like a gift or like spam?** User psychology matters—is this delightful or annoying? Probably depends on frequency and relevance.\n\n6. **Is there a sustainable model here, or is this purely a public good project?** Not that it needs to make money, but understanding the long-term maintenance commitment is important.\n","label",[130],"343e401e-fa4c-11f0-8f11-42dde27851f2","implementation-spec.md","343e40fa-fa4c-11f0-8f11-42dde27851f2",4,["D",1769386564928],"# Chicago Free Museum Days - Val Town Implementation Spec\n\n## Overview\n\nA Bluesky bot that posts weekly updates about free museum days in Chicago, built on Val Town with SQLite storage, automated scraping, and a public API.\n\n## Architecture\n\n### Val Town Structure\n\n```\nVals:\n├── scrapeChooseChicago (function - extracts data from Choose Chicago)\n├── scraper (cron - orchestrates all scraper functions)\n├── utils (function - normalizeDates, date expansion helpers)\n├── db (function - loadToSQLite, query functions)\n├── bot (cron - postToBluesky, runs Monday mornings)\n└── api (HTTP - Hono API for data access)\n\nSQLite Database:\n├── scraped_free_days (auto-populated by scrapers)\n├── free_days_overrides (manual corrections/additions)\n└── Union query merges both (overrides win on conflicts)\n```\n\n### Data Flow\n\n```\nChoose Chicago (HTML)\n ↓\nscrapeChooseChicago() → [{name, rawDates[], url, notes}]\n ↓\nnormalizeDates() → [{institution, date, time, proof_required, notes}]\n ↓\nloadToSQLite() → scraped_free_days table\n ↓\nQuery (union with overrides)\n ↓\n[Branch 1] postToBluesky() → Bluesky post\n[Branch 2] API endpoint → JSON response\n```\n\n## Database Schema\n\n### Table: `scraped_free_days`\n\nAuto-populated by scrapers. Replaced on each scraper run.\n\n```sql\nCREATE TABLE IF NOT EXISTS scraped_free_days (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n institution TEXT NOT NULL,\n date TEXT NOT NULL, -- ISO format YYYY-MM-DD\n time TEXT, -- e.g., \"9am-5pm\", \"11am-close\"\n proof_required TEXT, -- e.g., \"Illinois ID required\", \"ZIP code verification\"\n notes TEXT, -- Additional info (holidays, registration required, etc.)\n source_url TEXT, -- Where this data was scraped from\n scraped_at TEXT NOT NULL, -- ISO timestamp of scrape\n UNIQUE(institution, date) -- Prevent duplicate entries\n);\n\nCREATE INDEX idx_date ON scraped_free_days(date);\nCREATE INDEX idx_institution ON scraped_free_days(institution);\n```\n\n### Table: `free_days_overrides`\n\nManual corrections for when scrapers fail or data needs fixing.\n\n```sql\nCREATE TABLE IF NOT EXISTS free_days_overrides (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n institution TEXT NOT NULL,\n date TEXT NOT NULL, -- ISO format YYYY-MM-DD\n time TEXT,\n proof_required TEXT,\n notes TEXT,\n override_reason TEXT, -- Why this override exists\n created_at TEXT NOT NULL, -- When override was added\n UNIQUE(institution, date)\n);\n\nCREATE INDEX idx_override_date ON free_days_overrides(date);\n```\n\n### Query Logic\n\nWhen querying for free days, always union both tables with overrides taking precedence:\n\n```sql\n-- Get free days for a date range\nSELECT institution, date, time, proof_required, notes\nFROM (\n SELECT institution, date, time, proof_required, notes, 1 as priority\n FROM free_days_overrides\n WHERE date BETWEEN ? AND ?\n\n UNION ALL\n\n SELECT institution, date, time, proof_required, notes, 2 as priority\n FROM scraped_free_days\n WHERE date BETWEEN ? AND ?\n)\nGROUP BY institution, date\nHAVING priority = MIN(priority)\nORDER BY date, institution;\n```\n\n## Implementation Steps\n\n### Step 1: Database Setup (`db` val)\n\nCreate the `db` val with:\n\n**Functions:**\n- `initDatabase()` - Create tables and indexes\n- `loadToSQLite(data, source)` - Insert scraped data\n- `getFreeDays(startDate, endDate)` - Query with override logic\n- `addOverride(institution, date, details)` - Manual correction helper\n- `getUpcomingWeek()` - Helper for bot (next 7 days from today)\n\n**Implementation:**\n```typescript\nimport { sqlite } from \"https://esm.town/v/std/sqlite\";\n\n// Initialize tables\nexport async function initDatabase() {\n // Create scraped_free_days table\n // Create free_days_overrides table\n // Create indexes\n}\n\n// Load scraped data (replaces old scraped data)\nexport async function loadToSQLite(data: Array
, source: string) {\n // Begin transaction\n // Delete old entries from same source\n // Insert new entries\n // Commit\n}\n\n// Query with override logic\nexport async function getFreeDays(startDate: string, endDate: string) {\n // Union query as shown above\n}\n\n// Helper for bot\nexport async function getUpcomingWeek() {\n const today = new Date().toISOString().split('T')[0];\n const nextWeek = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)\n .toISOString().split('T')[0];\n return getFreeDays(today, nextWeek);\n}\n```\n\n### Step 2: Scraper (`scrapeChooseChicago` val)\n\n**Dependencies:**\n- `cheerio` (HTML parsing)\n\n**Function signature:**\n```typescript\nexport interface RawFreeDayData {\n institution: string;\n rawDates: string[]; // Unparsed date strings from HTML\n url?: string;\n notes?: string;\n}\n\nexport async function scrapeChooseChicago(): Promise
\n```\n\n**Scraping logic:**\n1. Fetch HTML from Choose Chicago\n2. Parse structure:\n - Find H3 headings (institution names)\n - Extract following `
- ` lists (date strings)\n3. Return structured data\n\n**Example HTML structure to parse:**\n```html\n
  Art Institute of Chicago
  \n
  - January 5 - February 28 (weekdays only, 11am-close)
  - Illinois residents with ID
  \n```\n\n**Pseudocode:**\n```typescript\nconst $ = cheerio.load(html);\nconst results = [];\n\n$('h3').each((i, el) => {\n const institution = $(el).text().trim();\n const dates = [];\n\n // Find following ul/li elements\n $(el).nextUntil('h3', 'ul').find('li').each((j, li) => {\n dates.push($(li).text().trim());\n });\n\n results.push({ institution, rawDates: dates });\n});\n\nreturn results;\n```\n\n### Step 3: Utilities (`utils` val)\n\n**Dependencies:**\n- `chrono-node` (natural language date parsing)\n\n**Functions:**\n- `normalizeDates(rawData)` - Parse raw strings into structured dates\n- `expandPattern(pattern, startDate, endDate)` - Expand \"every Wednesday\" into dates\n- `parseTimeRange(timeStr)` - Normalize time formats\n\n**Key logic:**\n\n```typescript\nexport interface FreeDayEntry {\n institution: string;\n date: string; // ISO YYYY-MM-DD\n time?: string;\n proof_required?: string;\n notes?: string;\n}\n\nexport async function normalizeDates(\n rawData: RawFreeDayData[]\n): Promise {\n const results: FreeDayEntry[] = [];\n\n for (const item of rawData) {\n for (const rawDate of item.rawDates) {\n // Try chrono-node parsing\n const parsed = chrono.parse(rawDate);\n\n if (parsed.length > 0) {\n // Extract date range if present\n // Expand into individual dates\n // Add to results\n } else if (rawDate.includes('every')) {\n // Handle recurring patterns\n const expanded = expandPattern(rawDate);\n results.push(...expanded);\n } else {\n // Log unparseable entry for manual review\n console.warn('Could not parse:', rawDate);\n }\n }\n }\n\n return results;\n}\n\n// Expand \"every Wednesday\" into next 12 months of Wednesdays\nfunction expandPattern(pattern: string): FreeDayEntry[] {\n // Parse day of week\n // Generate dates for next 12 months\n // Return array of entries\n}\n```\n\n### Step 4: Scraper Orchestrator (`scraper` cron val)\n\n**Schedule:** Monthly (first Monday of each month)\n\n**Logic:**\n```typescript\nimport { scrapeChooseChicago } from \"./scrapeChooseChicago\";\nimport { normalizeDates } from \"./utils\";\nimport { loadToSQLite } from \"./db\";\n\nexport default async function() {\n try {\n // Run all scrapers\n const rawData = await scrapeChooseChicago();\n\n // Normalize dates\n const normalized = await normalizeDates(rawData);\n\n // Load to SQLite\n await loadToSQLite(normalized, 'choose-chicago');\n\n console.log(`Scraped ${normalized.length} free day entries`);\n } catch (error) {\n console.error('Scraper failed:', error);\n // Optional: send alert/email\n }\n}\n```\n\n**Future expansion:**\n- Add more scraper functions (Loop Chicago, individual museums)\n- Call them all in sequence\n- Each writes to same `scraped_free_days` table with different `source_url`\n\n### Step 5: Bluesky Bot (`bot` cron val)\n\n**Schedule:** Every Monday at 8am Central Time\n\n**Dependencies:**\n- `@atproto/api` (Bluesky SDK)\n\n**Logic:**\n```typescript\nimport { BskyAgent } from '@atproto/api';\nimport { getUpcomingWeek } from './db';\n\nconst agent = new BskyAgent({ service: 'https://bsky.social' });\n\nexport default async function() {\n // Login to Bluesky\n await agent.login({\n identifier: process.env.BLUESKY_HANDLE,\n password: process.env.BLUESKY_PASSWORD\n });\n\n // Get upcoming free days\n const freeDays = await getUpcomingWeek();\n\n // Format message\n const message = formatMessage(freeDays);\n\n // Post to Bluesky\n await agent.post({ text: message });\n}\n\nfunction formatMessage(freeDays: FreeDayEntry[]): string {\n // Group by institution\n // Format as readable list\n // Add footer with data source link\n\n return `\n🏛️ Free museums in Chicago this week:\n\n• Art Institute: Mon-Fri (weekdays, 11am-close)\n• Field Museum: Wednesday\n• MCA: Tuesday evenings 5-9pm\n\n+${freeDays.length - 3} more → [link to API]\n\nData: github.com/your-repo\n `.trim();\n}\n```\n\n**Post format considerations:**\n- Keep under 300 characters for main post\n- Use thread if >5 museums\n- Link to full calendar/API\n- Emoji for visual interest\n\n### Step 6: API Endpoint (`api` HTTP val)\n\n**Dependencies:**\n- `hono` (lightweight web framework)\n\n**Routes:**\n```typescript\nimport { Hono } from 'hono';\nimport { getFreeDays, getUpcomingWeek } from './db';\n\nconst app = new Hono();\n\n// Get free days for date range\napp.get('/free-days', async (c) => {\n const start = c.req.query('start'); // YYYY-MM-DD\n const end = c.req.query('end'); // YYYY-MM-DD\n\n if (!start || !end) {\n return c.json({ error: 'start and end dates required' }, 400);\n }\n\n const data = await getFreeDays(start, end);\n return c.json({ data, count: data.length });\n});\n\n// Get upcoming week (convenience endpoint)\napp.get('/upcoming', async (c) => {\n const data = await getUpcomingWeek();\n return c.json({ data, count: data.length });\n});\n\n// Get all institutions (for filtering)\napp.get('/institutions', async (c) => {\n // Query distinct institutions from both tables\n return c.json({ institutions: [...] });\n});\n\nexport default app.fetch;\n```\n\n**Future additions:**\n- `/ics` endpoint to generate iCal feed\n- `/institution/:name` to filter by museum\n- `/today` for current day only\n\n## Environment Variables\n\nSet these in Val Town secrets:\n\n```\nBLUESKY_HANDLE=your-handle.bsky.social\nBLUESKY_PASSWORD=your-app-password\n```\n\n## Testing Strategy\n\n### Phase 1: Database\n1. Create `db` val\n2. Run `initDatabase()`\n3. Manually insert test data\n4. Verify queries work\n\n### Phase 2: Scraper + Normalizer\n1. Run `scrapeChooseChicago()` manually\n2. Inspect raw output\n3. Pass to `normalizeDates()`\n4. Verify date parsing quality\n5. Check for unparseable entries (aim for <20% failure rate)\n\n### Phase 3: Integration\n1. Run full scraper → normalizer → loader pipeline\n2. Query database, verify data looks correct\n3. Add manual overrides for failed parsing\n4. Re-query, confirm overrides work\n\n### Phase 4: Bot\n1. Test Bluesky post with hardcoded message\n2. Test with real database query\n3. Verify formatting looks good on Bluesky\n4. Enable cron schedule\n\n### Phase 5: API\n1. Test each endpoint locally\n2. Verify JSON responses\n3. Test date range edge cases\n4. Deploy and test public URL\n\n## Success Criteria\n\n### Minimum Viable Product (MVP)\n- ✅ Scraper runs monthly without errors\n- ✅ Database contains ≥15 Chicago institutions\n- ✅ Bot posts every Monday at 8am\n- ✅ API returns valid JSON for date ranges\n- ✅ Manual intervention <1 hour/month\n\n### Stretch Goals\n- Add Loop Chicago scraper\n- Add individual museum scrapers for missing institutions\n- Implement ICS calendar feed endpoint\n- Support filtering by neighborhood/museum type\n- Community contributions (PR process for corrections)\n\n## Known Limitations & Mitigations\n\n| Limitation | Impact | Mitigation |\n|------------|--------|------------|\n| Choose Chicago updates irregularly | Stale data | Run scraper monthly, add manual overrides |\n| Date parsing ~80% accurate | Missing/incorrect dates | Manual review process, improve parser over time |\n| Proof-of-residency rules change | Incorrect info | Version in git, add notes field |\n| Bluesky API rate limits | Posting failures | Respect rate limits, add retry logic |\n| SQLite size limits | Unlikely (450 rows/year) | Monitor, could archive old dates if needed |\n\n## Maintenance Schedule\n\n**Monthly:**\n- Review scraper logs for failures\n- Check for unparseable dates\n- Add manual overrides as needed\n\n**Quarterly:**\n- Audit data quality against official museum sites\n- Update parser for new date formats\n- Review Bluesky engagement metrics\n\n**Annually:**\n- Update recurring patterns (if museums change schedules)\n- Archive old dates (optional)\n- Expand to new data sources if successful\n\n## Future Enhancements\n\n1. **Multi-city support**: Expand to other cities with free museum programs\n2. **ICS calendar feed**: Users can subscribe in Google/Apple Calendar\n3. **Embeddable widget**: Iframe for community sites\n4. **SMS notifications**: Text alerts for favorite museums\n5. **Accessibility filters**: Filter by wheelchair access, sensory-friendly hours\n6. **Community contributions**: GitHub repo for data corrections/additions\n\n## Technical Debt to Avoid\n\n- ❌ Don't pre-optimize date parsing - start simple, improve as needed\n- ❌ Don't build complex admin UI - Val Town console + SQLite tool is enough\n- ❌ Don't add authentication to API - keep it open (rate limit if abused)\n- ❌ Don't overthink schema - simple tables work fine at this scale\n\n## Resources\n\n- [Val Town Docs](https://docs.val.town)\n- [Bluesky API](https://atproto.com)\n- [Choose Chicago Source](https://www.choosechicago.com/articles/museums-art/free-museum-days-in-chicago/)\n- [Cheerio Docs](https://cheerio.js.org/)\n- [Chrono Node](https://github.com/wanasit/chrono)\n- [Hono Framework](https://hono.dev)\n\n## Next Steps\n\nStart with **Step 1: Database Setup** - create the `db` val and initialize the schema. Once tables exist, you can test the entire pipeline with manual data before building the scraper.\n",[140],"3447463c-fa4c-11f0-98a8-42dde27851f2",["D",1769386564906],[27],"34190a2e-fa4c-11f0-b7e5-42dde27851f2",".claude","34190b14-fa4c-11f0-b7e5-42dde27851f2",1,true,["D",1769386564671],"directory",[150],"pulls","branches","forks","envVars",{"_164":166,"_167":59},"connections",{"_164":59,"_165":59},"count","unfilledCount",2,"emptyCount",{"_41":149,"_32":150,"_30":151,"_132":-5,"_39":40,"_38":152,"_134":153,"_36":190,"_13":59,"_33":155,"_34":-5,"_23":24,"_137":-5,"_174":191,"_26":192},{"_41":183,"_32":184,"_30":185,"_132":151,"_39":40,"_38":166,"_134":153,"_36":186,"_13":59,"_33":20,"_34":187,"_23":24,"_137":-5,"_174":188,"_26":189},{"_41":146,"_32":27,"_30":31,"_132":-5,"_39":40,"_38":14,"_134":24,"_36":180,"_13":59,"_33":20,"_34":35,"_23":24,"_137":-5,"_174":181,"_26":182},{"_41":139,"_32":140,"_30":141,"_132":-5,"_39":40,"_38":142,"_134":24,"_36":177,"_13":59,"_33":20,"_34":144,"_23":24,"_137":-5,"_174":178,"_26":179},{"_41":129,"_32":130,"_30":131,"_132":-5,"_39":40,"_38":133,"_134":24,"_36":173,"_13":59,"_33":20,"_34":136,"_23":24,"_137":-5,"_174":175,"_26":176},["D",1769386564908],"children",[],[130],["D",1769386564928],[],[140],["D",1769386564906],[],[27],"3432d6a2-fa4c-11f0-8dfc-42dde27851f2","settings.local.json","3432d7ba-fa4c-11f0-8dfc-42dde27851f2",["D",1769386564860],"{\n \"permissions\": {\n \"allow\": [\n \"WebSearch\",\n \"WebFetch(domain:www.sheddaquarium.org)\",\n \"WebFetch(domain:www.fieldmuseum.org)\",\n \"WebFetch(domain:www.artic.edu)\",\n \"WebFetch(domain:www.msichicago.org)\",\n \"WebFetch(domain:www.griffinmsi.org)\",\n \"WebFetch(domain:visit.mcachicago.org)\",\n \"WebFetch(domain:www.choosechicago.com)\",\n \"WebFetch(domain:loopchicago.com)\",\n \"WebFetch(domain:www.chicagohistory.org)\",\n \"WebFetch(domain:naturemuseum.org)\",\n \"WebFetch(domain:www.upparent.com)\",\n \"WebFetch(domain:do312.com)\",\n \"WebFetch(domain:freemuseumday.org)\"\n ]\n }\n}\n",[],[150,184],["D",1769386564671],[169],[150],["D",1769386563309],["D",1789532458193],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":53,"_100":101,"_102":24},{"_13":85,"_32":86,"_41":40,"_87":42,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":43,"_94":95},"ctx",{"_78":-5,"_122":231,"_232":233,"_234":235,"_236":24,"_237":24,"_238":24,"_239":153,"_240":-5,"_241":-7,"_242":-7,"_243":59,"_244":24,"_245":24,"_246":-5,"_247":24,"_248":24,"_249":24,"_250":-5},"ENV",{"_202":203,"_204":205,"_206":86,"_207":208,"_209":210,"_211":212,"_213":214,"_215":216,"_217":218,"_219":220,"_221":222,"_223":224,"_225":226,"_227":228,"_229":230},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Art Institute of Chicago

Diff · v5