[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_264":265,"_266":267},"routes/_app.x.$handle.$name",{"_98":97,"_32":45,"_106":88,"_27":53,"_13":14,"_107":-5,"_11":108,"_109":110,"_111":112,"_113":114,"_115":116,"_20":-5,"_117":-5,"_118":-5,"_119":25,"_120":121,"_122":25,"_123":-5,"_124":-5,"_125":126},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_43":44,"_32":45,"_38":46,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":81,"_82":83,"_84":85,"_86":25},"version",22,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":20,"_35":37,"_38":39,"_40":14,"_41":42,"_24":25},"previous",{"_30":31,"_32":33,"_34":20,"_35":36},"deleted",false,"deletedHere","path","docs/implementation-spec.md","latestPath","fileId","343e40fa-fa4c-11f0-8f11-42dde27851f2","name","implementation-spec.md","fileType","content","# 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 institution_key TEXT NOT NULL, -- Slugified institution name for matching\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 TEXT NOT NULL, -- Source identifier (e.g., \"choose-chicago\")\n source_url TEXT, -- Where this data was scraped from\n scraped_at TEXT NOT NULL, -- ISO timestamp of scrape\n UNIQUE(institution_key, date) -- Prevent duplicate entries per institution/date\n);\n\nCREATE INDEX idx_scraped_date ON scraped_free_days(date);\nCREATE INDEX idx_scraped_institution_key ON scraped_free_days(institution_key);\nCREATE INDEX idx_scraped_source ON scraped_free_days(source);\n```\n\n### Table: `free_days_overrides`\n\nManual corrections for when scrapers fail or data needs fixing. Can also suppress incorrect scraped data.\n\n```sql\nCREATE TABLE IF NOT EXISTS free_days_overrides (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n institution TEXT NOT NULL,\n institution_key TEXT NOT NULL, -- Slugified institution name for matching\n date TEXT NOT NULL, -- ISO format YYYY-MM-DD\n time TEXT,\n proof_required TEXT,\n notes TEXT,\n is_cancelled INTEGER DEFAULT 0, -- Set to 1 to suppress a scraped entry\n override_reason TEXT, -- Why this override exists\n created_at TEXT NOT NULL, -- When override was added\n UNIQUE(institution_key, date)\n);\n\nCREATE INDEX idx_override_date ON free_days_overrides(date);\nCREATE INDEX idx_override_institution_key ON free_days_overrides(institution_key);\n```\n\n### Query Logic\n\nWhen querying for free days, overrides take precedence over scraped data. Use a LEFT JOIN anti-pattern for deterministic results (the previous GROUP BY approach was non-deterministic in SQLite):\n\n```sql\n-- Get free days for a date range (overrides win, cancelled entries excluded)\nSELECT s.institution, s.date, s.time, s.proof_required, s.notes\nFROM scraped_free_days s\nLEFT JOIN free_days_overrides o\n ON o.institution_key = s.institution_key AND o.date = s.date\nWHERE s.date BETWEEN ? AND ?\n AND o.id IS NULL -- No override exists for this entry\n\nUNION ALL\n\nSELECT o.institution, o.date, o.time, o.proof_required, o.notes\nFROM free_days_overrides o\nWHERE o.date BETWEEN ? AND ?\n AND COALESCE(o.is_cancelled, 0) = 0 -- Exclude cancelled entries\n\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\n- `initDatabase()` - Create tables and indexes\n- `loadToSQLite(data, source)` - Insert scraped data (deletes old entries from same source first)\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- `slugify(name)` - Generate institution_key from institution name\n- `chicagoDate(date?)` - Get ISO date string in America/Chicago timezone\n\n**Implementation:**\n\n```typescript\nimport { sqlite } from \"https://esm.town/v/std/sqlite\";\n\n// Get ISO date string in Chicago timezone (avoids UTC date offset issues)\nexport function chicagoDate(d = new Date()): string {\n const parts = new Intl.DateTimeFormat(\"en-CA\", {\n timeZone: \"America/Chicago\",\n year: \"numeric\",\n month: \"2-digit\",\n day: \"2-digit\",\n }).formatToParts(d);\n const y = parts.find((p) => p.type === \"year\")!.value;\n const m = parts.find((p) => p.type === \"month\")!.value;\n const day = parts.find((p) => p.type === \"day\")!.value;\n return `${y}-${m}-${day}`;\n}\n\n// Generate a stable key for matching institutions across sources/overrides\nexport function slugify(name: string): string {\n return name\n .toLowerCase()\n .replace(/[^a-z0-9]+/g, \"-\")\n .replace(/^-|-$/g, \"\");\n}\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 from same source)\nexport async function loadToSQLite(data: Array, source: string) {\n // Use sqlite.batch() for atomic transaction\n await sqlite.batch([\n { sql: \"DELETE FROM scraped_free_days WHERE source = ?\", args: [source] },\n ...data.map((entry) => ({\n sql: `INSERT INTO scraped_free_days \n (institution, institution_key, date, time, proof_required, notes, source, source_url, scraped_at)\n VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n args: [\n entry.institution,\n slugify(entry.institution),\n entry.date,\n entry.time,\n entry.proof_required,\n entry.notes,\n source,\n entry.source_url,\n new Date().toISOString(),\n ],\n })),\n ]);\n}\n\n// Query with override logic\nexport async function getFreeDays(startDate: string, endDate: string) {\n // LEFT JOIN anti-pattern query as shown above\n}\n\n// Helper for bot (uses Chicago timezone)\nexport async function getUpcomingWeek() {\n const today = chicagoDate();\n const nextWeekDate = new Date();\n nextWeekDate.setDate(nextWeekDate.getDate() + 7);\n const nextWeek = chicagoDate(nextWeekDate);\n return getFreeDays(today, nextWeek);\n}\n```\n\n### Step 2: Scraper (`scrapeChooseChicago` val)\n\n**Dependencies:**\n\n- `cheerio` (HTML parsing)\n\n**Function signature:**\n\n```typescript\nexport interface RawFreeDayData {\n institution: string;\n rawLines: string[]; // All lines from HTML (dates AND eligibility notes mixed)\n url?: string;\n}\n\nexport async function scrapeChooseChicago(): Promise;\n```\n\n**Scraping logic:**\n\n1. Fetch HTML from Choose Chicago (with timeout and User-Agent)\n2. Parse structure:\n - Find H3 headings (institution names)\n - Extract following `

` lists (all text, not just dates)\n3. Return structured data\n\n**Important:** Choose Chicago mixes date info and eligibility notes in the same `
` list. The normalizer will classify each line.\n\n**Example HTML structure to parse:**\n\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\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)\n .nextUntil(\"h3\", \"ul\")\n .find(\"li\")\n .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\n- `chrono-node` (natural language date parsing)\n\n**Functions:**\n\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\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\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\n- `@atproto/api` (Bluesky SDK)\n\n**Logic:**\n\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\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\n- `hono` (lightweight web framework)\n\n**Routes:**\n\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\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\n\n1. Create `db` val\n2. Run `initDatabase()`\n3. Manually insert test data\n4. Verify queries work\n\n### Phase 2: Scraper + Normalizer\n\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\n\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\n\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\n\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\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\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\n- Review scraper logs for failures\n- Check for unparseable dates\n- Add manual overrides as needed\n\n**Quarterly:**\n\n- Audit data quality against official museum sites\n- Update parser for new date formats\n- Review Bluesky engagement metrics\n\n**Annually:**\n\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","# 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 institution_key TEXT NOT NULL, -- Slugified institution name for matching\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 TEXT NOT NULL, -- Source identifier (e.g., \"choose-chicago\")\n source_url TEXT, -- Where this data was scraped from\n scraped_at TEXT NOT NULL, -- ISO timestamp of scrape\n UNIQUE(institution_key, date) -- Prevent duplicate entries per institution/date\n);\n\nCREATE INDEX idx_scraped_date ON scraped_free_days(date);\nCREATE INDEX idx_scraped_institution_key ON scraped_free_days(institution_key);\nCREATE INDEX idx_scraped_source ON scraped_free_days(source);\n```\n\n### Table: `free_days_overrides`\n\nManual corrections for when scrapers fail or data needs fixing. Can also suppress incorrect scraped data.\n\n```sql\nCREATE TABLE IF NOT EXISTS free_days_overrides (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n institution TEXT NOT NULL,\n institution_key TEXT NOT NULL, -- Slugified institution name for matching\n date TEXT NOT NULL, -- ISO format YYYY-MM-DD\n time TEXT,\n proof_required TEXT,\n notes TEXT,\n is_cancelled INTEGER DEFAULT 0, -- Set to 1 to suppress a scraped entry\n override_reason TEXT, -- Why this override exists\n created_at TEXT NOT NULL, -- When override was added\n UNIQUE(institution_key, date)\n);\n\nCREATE INDEX idx_override_date ON free_days_overrides(date);\nCREATE INDEX idx_override_institution_key ON free_days_overrides(institution_key);\n```\n\n### Query Logic\n\nWhen querying for free days, overrides take precedence over scraped data. Use a LEFT JOIN anti-pattern for deterministic results (the previous GROUP BY approach was non-deterministic in SQLite):\n\n```sql\n-- Get free days for a date range (overrides win, cancelled entries excluded)\nSELECT s.institution, s.date, s.time, s.proof_required, s.notes\nFROM scraped_free_days s\nLEFT JOIN free_days_overrides o\n ON o.institution_key = s.institution_key AND o.date = s.date\nWHERE s.date BETWEEN ? AND ?\n AND o.id IS NULL -- No override exists for this entry\n\nUNION ALL\n\nSELECT o.institution, o.date, o.time, o.proof_required, o.notes\nFROM free_days_overrides o\nWHERE o.date BETWEEN ? AND ?\n AND COALESCE(o.is_cancelled, 0) = 0 -- Exclude cancelled entries\n\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\n- `initDatabase()` - Create tables and indexes\n- `loadToSQLite(data, source)` - Insert scraped data (deletes old entries from same source first)\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- `getLatestScrapeTime()` - Get timestamp of most recent scrape (for staleness check)\n- `slugify(name)` - Generate institution_key from institution name\n- `chicagoDate(date?)` - Get ISO date string in America/Chicago timezone\n\n**Implementation:**\n\n```typescript\nimport { sqlite } from \"https://esm.town/v/std/sqlite\";\n\n// Get ISO date string in Chicago timezone (avoids UTC date offset issues)\nexport function chicagoDate(d = new Date()): string {\n const parts = new Intl.DateTimeFormat(\"en-CA\", {\n timeZone: \"America/Chicago\",\n year: \"numeric\",\n month: \"2-digit\",\n day: \"2-digit\",\n }).formatToParts(d);\n const y = parts.find((p) => p.type === \"year\")!.value;\n const m = parts.find((p) => p.type === \"month\")!.value;\n const day = parts.find((p) => p.type === \"day\")!.value;\n return `${y}-${m}-${day}`;\n}\n\n// Generate a stable key for matching institutions across sources/overrides\nexport function slugify(name: string): string {\n return name\n .toLowerCase()\n .replace(/[^a-z0-9]+/g, \"-\")\n .replace(/^-|-$/g, \"\");\n}\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 from same source)\nexport async function loadToSQLite(data: Array
, source: string) {\n // Use sqlite.batch() for atomic transaction\n await sqlite.batch([\n { sql: \"DELETE FROM scraped_free_days WHERE source = ?\", args: [source] },\n ...data.map((entry) => ({\n sql: `INSERT INTO scraped_free_days \n (institution, institution_key, date, time, proof_required, notes, source, source_url, scraped_at)\n VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n args: [\n entry.institution,\n slugify(entry.institution),\n entry.date,\n entry.time,\n entry.proof_required,\n entry.notes,\n source,\n entry.source_url,\n new Date().toISOString(),\n ],\n })),\n ]);\n}\n\n// Query with override logic\nexport async function getFreeDays(startDate: string, endDate: string) {\n // LEFT JOIN anti-pattern query as shown above\n}\n\n// Helper for bot (uses Chicago timezone)\nexport async function getUpcomingWeek() {\n const today = chicagoDate();\n const nextWeekDate = new Date();\n nextWeekDate.setDate(nextWeekDate.getDate() + 7);\n const nextWeek = chicagoDate(nextWeekDate);\n return getFreeDays(today, nextWeek);\n}\n\n// Check data freshness for bot staleness warning\nexport async function getLatestScrapeTime(): Promise
{\n const result = await sqlite.execute(\n \"SELECT MAX(scraped_at) as latest FROM scraped_free_days\",\n );\n return result.rows[0]?.latest ?? null;\n}\n```\n\n### Step 2: Scraper (`scrapeChooseChicago` val)\n\n**Dependencies:**\n\n- `cheerio` (HTML parsing)\n\n**Function signature:**\n\n```typescript\nexport interface RawFreeDayData {\n institution: string;\n rawLines: string[]; // All lines from HTML (dates AND eligibility notes mixed)\n url?: string;\n}\n\nexport async function scrapeChooseChicago(): Promise
;\n```\n\n**Scraping logic:**\n\n1. Fetch HTML from Choose Chicago (with timeout and User-Agent)\n2. Parse structure:\n - Find H3 headings (institution names)\n - Extract following `
` lists (all text, not just dates)\n3. Return structured data\n\n**Important:** Choose Chicago mixes date info and eligibility notes in the same `
` list. The normalizer will classify each line.\n\n**Example HTML structure to parse:**\n\n```html\n
Art Institute of Chicago
\n
\n
January 5 - February 28 (weekdays only, 11am-close)
\n
Illinois residents with ID
\n
\n```\n\n**Pseudocode:**\n\n```typescript\nconst SOURCE_URL =\n \"https://www.choosechicago.com/articles/museums-art/free-museum-days-in-chicago/\";\n\n// Fetch with timeout and polite User-Agent\nconst controller = new AbortController();\nsetTimeout(() => controller.abort(), 15_000);\nconst response = await fetch(SOURCE_URL, {\n signal: controller.signal,\n headers: { \"User-Agent\": \"chicago-free-museum-days-bot/1.0\" },\n});\nconst html = await response.text();\n\nconst $ = cheerio.load(html);\nconst results = [];\n\n$(\"h3\").each((i, el) => {\n const institution = $(el).text().trim();\n const lines = [];\n\n // Find following ul/li elements (contains dates AND eligibility notes)\n $(el)\n .nextUntil(\"h3\", \"ul\")\n .find(\"li\")\n .each((j, li) => {\n lines.push($(li).text().trim());\n });\n\n results.push({ institution, rawLines: lines, url: SOURCE_URL });\n});\n\nreturn results;\n```\n\n### Step 3: Utilities (`utils` val)\n\n**Dependencies:**\n\n- `chrono-node` (natural language date parsing)\n\n**Functions:**\n\n- `classifyLine(line)` - Determine if a line is date-ish or note-ish\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\nChoose Chicago mixes date info and eligibility notes in the same `
` list. The normalizer uses a two-pass approach:\n1. **Classify** each line as date-ish or note-ish\n2. **Aggregate** note-ish lines into `proof_required` / `notes` for the institution\n3. **Expand** date-ish lines into individual `FreeDayEntry` records\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 source_url?: string;\n}\n\n// Patterns that indicate eligibility/requirements rather than dates\nconst NOTE_PATTERNS = [\n /illinois/i,\n /resident/i,\n /\\bID\\b/,\n /required/i,\n /must\\b/i,\n /free for/i,\n /tickets/i,\n /registration/i,\n /zip code/i,\n /proof/i,\n];\n\n// Patterns that indicate date information\nconst DATE_PATTERNS = [\n /january|february|march|april|may|june|july|august|september|october|november|december/i,\n /\\d{1,2}(st|nd|rd|th)?/,\n /every\\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)/i,\n /weekdays?/i,\n /through|to|-/,\n];\n\nfunction classifyLine(line: string): \"date\" | \"note\" {\n const noteScore = NOTE_PATTERNS.filter((p) => p.test(line)).length;\n const dateScore = DATE_PATTERNS.filter((p) => p.test(line)).length;\n\n // If it looks more like a note, classify as note\n if (noteScore > dateScore) return \"note\";\n // If it has date indicators, classify as date\n if (dateScore > 0) return \"date\";\n // Default to note (safer to not generate bad date entries)\n return \"note\";\n}\n\nexport async function normalizeDates(\n rawData: RawFreeDayData[],\n): Promise {\n const results: FreeDayEntry[] = [];\n\n for (const item of rawData) {\n // Pass 1: Classify all lines\n const dateLines: string[] = [];\n const noteLines: string[] = [];\n\n for (const line of item.rawLines) {\n if (classifyLine(line) === \"date\") {\n dateLines.push(line);\n } else {\n noteLines.push(line);\n }\n }\n\n // Aggregate notes for this institution\n const aggregatedNotes = noteLines.join(\"; \") || undefined;\n\n // Pass 2: Parse date lines\n for (const dateLine of dateLines) {\n // Try chrono-node parsing\n const parsed = chrono.parse(dateLine);\n\n if (parsed.length > 0) {\n // Extract date range if present, expand into individual dates\n // Add aggregatedNotes to each entry\n } else if (/every/i.test(dateLine)) {\n // Handle recurring patterns\n const expanded = expandPattern(dateLine, item.institution, aggregatedNotes);\n results.push(...expanded);\n } else {\n // Log unparseable entry for manual review\n console.warn(\"Could not parse date line:\", dateLine);\n }\n }\n }\n\n return results;\n}\n\n// Expand \"every Wednesday\" into next 12 months of Wednesdays\nfunction expandPattern(\n pattern: string,\n institution: string,\n notes?: string,\n): FreeDayEntry[] {\n // Parse day of week\n // Generate dates for next 12 months\n // Return array of entries with notes attached\n}\n```\n\n### Step 4: Scraper Orchestrator (`scraper` cron val)\n\n**Schedule:** Monthly (first Monday of each month)\n\n**Logic:**\n\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\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**Note:** Val Town cron schedules may run in UTC. To run at 8am Central:\n- Standard Time (CST, UTC-6): Use `0 14 * * 1` (14:00 UTC)\n- Daylight Time (CDT, UTC-5): Use `0 13 * * 1` (13:00 UTC)\n- Or check Val Town docs for timezone configuration options\n\n**Dependencies:**\n\n- `@atproto/api` (Bluesky SDK)\n\n**Logic:**\n\n```typescript\nimport { BskyAgent } from \"@atproto/api\";\nimport { getUpcomingWeek, getLatestScrapeTime } 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: Deno.env.get(\"BLUESKY_HANDLE\"),\n password: Deno.env.get(\"BLUESKY_PASSWORD\"),\n });\n\n // Get upcoming free days\n const freeDays = await getUpcomingWeek();\n\n // Guard: Don't post if no data available\n if (freeDays.length === 0) {\n console.warn(\"No free days found for upcoming week - skipping post\");\n return;\n }\n\n // Optional: Check data freshness\n const lastScrape = await getLatestScrapeTime();\n const daysSinceUpdate = lastScrape\n ? Math.floor((Date.now() - new Date(lastScrape).getTime()) / (1000 * 60 * 60 * 24))\n : null;\n\n // Format message\n const message = formatMessage(freeDays, daysSinceUpdate);\n\n // Post to Bluesky\n await agent.post({ text: message });\n}\n\nfunction formatMessage(freeDays: FreeDayEntry[], daysSinceUpdate?: number | null): string {\n // Group by institution\n // Format as readable list\n // Add footer with data source link\n\n let footer = \"Data: github.com/your-repo\";\n if (daysSinceUpdate && daysSinceUpdate > 14) {\n footer = `⚠️ Data last updated ${daysSinceUpdate} days ago\\n` + footer;\n }\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\n${footer}\n `.trim();\n}\n```\n\n**Post format considerations:**\n\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\n- `hono` (lightweight web framework)\n\n**Routes:**\n\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\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\n\n1. Create `db` val\n2. Run `initDatabase()`\n3. Manually insert test data\n4. Verify queries work\n\n### Phase 2: Scraper + Normalizer\n\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\n\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\n\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\n\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\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\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\n- Review scraper logs for failures\n- Check for unparseable dates\n- Add manual overrides as needed\n\n**Quarterly:**\n\n- Audit data quality against official museum sites\n- Update parser for new date formats\n- Review Bluesky engagement metrics\n\n**Annually:**\n\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","createdAt",["D",1769387727886],"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",1789445472057],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_98":97,"_105":101},"org",{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},"branch",{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"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",{"_43":44,"_32":45,"_38":259,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":260,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":261,"_82":262,"_84":263,"_86":25},"tree",[197,199,203,204,205,206,207],"files",[197,198,199,200,201,202,203,204,205,206,207],"counts",{"_186":61,"_187":183,"_188":61,"_189":190,"_191":192},"contents",[127,128,129,130,131,132,133],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_43":180,"_32":181,"_30":182,"_137":-5,"_41":42,"_40":183,"_139":140,"_38":184,"_13":61,"_34":178,"_35":-5,"_24":25,"_143":-5,"_27":185},{"_43":173,"_32":174,"_30":175,"_137":-5,"_41":42,"_40":176,"_139":140,"_38":177,"_13":61,"_34":178,"_35":-5,"_24":25,"_143":-5,"_27":179},{"_43":166,"_32":167,"_30":168,"_137":-5,"_41":42,"_40":169,"_139":140,"_38":170,"_13":61,"_34":20,"_35":171,"_24":25,"_143":-5,"_27":172},{"_43":159,"_32":160,"_30":161,"_137":-5,"_41":42,"_40":162,"_139":140,"_38":163,"_13":61,"_34":20,"_35":164,"_24":25,"_143":-5,"_27":165},{"_43":152,"_32":153,"_30":154,"_137":-5,"_41":42,"_40":155,"_139":140,"_38":156,"_13":61,"_34":20,"_35":157,"_24":25,"_143":-5,"_27":158},{"_43":145,"_32":146,"_30":147,"_137":-5,"_41":42,"_40":148,"_139":140,"_38":149,"_13":61,"_34":20,"_35":150,"_24":25,"_143":-5,"_27":151},{"_43":134,"_32":135,"_30":136,"_137":-5,"_41":42,"_40":138,"_139":140,"_38":141,"_13":61,"_34":20,"_35":142,"_24":25,"_143":-5,"_27":144},"ab92b5d6-fa4d-11f0-88a6-42dde27851f2","deno.json","ab92b680-fa4d-11f0-88a6-42dde27851f2","parentId",7,"latest",true,["D",1769387194639],"{\n\t\"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n\t\"compilerOptions\": {\n\t\t\"lib\": [\n\t\t\t\"dom\",\n\t\t\t\"dom.iterable\",\n\t\t\t\"dom.asynciterable\",\n\t\t\t\"deno.ns\",\n\t\t\t\"deno.unstable\"\n\t\t],\n\t\t\"noImplicitAny\": false,\n\t\t\"strict\": false,\n\t\t\"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n\t},\n\t\"experimental\": {\n\t\t\"unstable-node-globals\": true,\n\t\t\"unstable-sloppy-imports\": true,\n\t\t\"unstable-temporal\": true,\n\t\t\"unstable-worker-options\": true\n\t},\n\t\"imports\": {\n\t\t\"@biomejs/biome\": \"npm:@biomejs/biome@^2.3.12\"\n\t},\n\t\"lint\": {\n\t\t\"files\": {\n\t\t\t\"include\": [\"deno:/https/esm.town/**/*\"]\n\t\t},\n\t\t\"rules\": {\n\t\t\t\"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n\t\t}\n\t},\n\t\"lock\": false,\n\t\"nodeModulesDir\": \"auto\"\n}\n","label",[135],"abb79c84-fa4d-11f0-bd11-42dde27851f2","biome.json","abb79d42-fa4d-11f0-bd11-42dde27851f2",13,["D",1769387194804],"{\n\t\"$schema\": \"https://biomejs.dev/schemas/2.3.12/schema.json\",\n\t\"vcs\": { \"enabled\": true, \"clientKind\": \"git\", \"useIgnoreFile\": true },\n\t\"files\": { \"ignoreUnknown\": false },\n\t\"formatter\": { \"enabled\": true, \"indentStyle\": \"tab\" },\n\t\"linter\": { \"enabled\": true, \"rules\": { \"recommended\": true } },\n\t\"javascript\": { \"formatter\": { \"quoteStyle\": \"double\" } },\n\t\"assist\": {\n\t\t\"enabled\": true,\n\t\t\"actions\": { \"source\": { \"organizeImports\": \"on\" } }\n\t}\n}\n",[146],"d4853b9e-fa4d-11f0-89fe-42dde27851f2","CLAUDE.md","d4853ca2-fa4d-11f0-89fe-42dde27851f2",17,["D",1769387263310],"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\nRead the instructions from AGENTS.md: @AGENTS.md. Confirm you have read the instructions from AGENTS.md before starting your work.\n",[153],"ababd1b0-fa4d-11f0-96ef-42dde27851f2","AGENTS.md","ababd2c8-fa4d-11f0-96ef-42dde27851f2",11,["D",1769387194801],"You are an advanced assistant specialized in generating Val Town code.\n\n## Runtime Environment\n\nVal Town uses **Deno** as its runtime in a serverless context.\n\n### Security Constraints\n\n- **No filesystem access**: Vals cannot read or write local files\n- **No FFI (Foreign Function Interface)**: Cannot call native code\n- **No subprocesses**: Cannot spawn child processes\n- **Network access allowed**: HTTP requests are permitted\n- **Environment variables**: Accessible via `Deno.env.get()`\n\n### Performance Characteristics\n\n- **Cold start time**: 100ms+ for first request (includes dependency installation)\n- **Warm instances**: Subsequent requests are much faster when val stays warm\n- Prefer lightweight packages to reduce cold start time\n\n### Key Differences from Node.js\n\n1. **No `require()`**: Use ES modules (`import/export`) only\n2. **No `__dirname` or `__filename`**: Not available in Deno\n3. **Explicit file extensions**: Must include `.ts`, `.tsx`, or `.js` in relative imports\n4. **Top-level await**: Supported natively\n5. **NPM packages require `npm:` prefix**: Or use `https://esm.sh`\n\n## Core Guidelines\n\n- Ask clarifying questions when requirements are ambiguous\n- Provide complete, functional solutions rather than skeleton implementations\n- Test your logic against edge cases before presenting the final solution\n- Ensure all code follows Val Town's specific platform requirements\n- If a section of code that you're working on is getting too complex, consider\n refactoring it into subcomponents\n\n## Code Standards\n\n- Generate code in TypeScript or TSX\n- Add appropriate TypeScript types and interfaces for all data structures\n- Prefer official SDKs or libraries than writing API calls directly\n- Ask the user to supply API or library documentation if you are at all unsure\n about it\n- **Never bake in secrets into the code** - always use environment variables\n- Include comments explaining complex logic (avoid commenting obvious\n operations)\n- Follow modern ES6+ conventions and functional programming practices if\n possible\n\n## Import Syntax\n\nVal Town supports multiple import methods:\n\n### NPM Packages\n\n```ts\nimport { foo } from \"npm:packagename@version\";\nimport bar from \"npm:another-package@1.0.0\";\n```\n\n### JSR (JavaScript Registry)\n\n```ts\nimport { encodeBase64 } from \"jsr:@std/encoding@1.0.4/base64\";\nimport { escape } from \"jsr:@std/html@1.0.3/entities\";\n```\n\n### esm.sh (CDN)\n\n```ts\nimport React from \"https://esm.sh/react@18\";\n```\n\n### esm.town (Val Town imports)\n\n```ts\nimport { blob } from \"https://esm.town/v/std/blob\";\n```\n\n**Important**: Always specify versions for reproducibility and reliability.\n\n## Types of Vals (fileType)\n\n### 1. HTTP Val (`fileType: \"http\"`)\n\n- Create web APIs and endpoints\n- Handle HTTP requests and responses\n- HTTP vals have a `links.endpoint` field containing the live URL where the val is deployed\n- Example structure:\n\n```ts\nexport default async function (req: Request): Promise {\n return new Response(\"Hello World\", {\n status: 200,\n headers: { \"Content-Type\": \"text/plain\" },\n });\n}\n```\n\nFiles that are HTTP vals have http in their name like `foobar.http.tsx`\n\n### 2. Interval Val (`fileType: \"interval\"`)\n\n- Run on a schedule (cron-like functionality)\n- Example structure:\n\n```ts\nexport default async function () {\n console.log(\"Running scheduled task\", new Date());\n}\n```\n\nFiles that are Interval vals have cron in their name like `foobar.cron.tsx`\n\n### 3. Email Val (`fileType: \"email\"`)\n\n- Process incoming emails\n- Handle email-based workflows\n- Example structure:\n\n```ts\nexport default async function (email: Email) {\n console.log(\"Received email from:\", email.from);\n}\n```\n\nFiles that are Email vals have email in their name like `foobar.email.tsx`\n\n### 4. Script Val (`fileType: \"script\"`)\n\n- General-purpose code that can export functions or values\n- Example structure:\n\n```ts\nexport function greet(name: string): string {\n return `Hello, ${name}!`;\n}\n\nexport const config = {\n version: \"1.0.0\",\n};\n```\n\n## Val Town Standard Library\n\nVal Town provides built-in services:\n\n### SQLite Storage\n\n**For application code in Vals**, use the standard library import:\n\n```typescript\nimport { sqlite } from \"https://esm.town/v/std/sqlite@14-main/main.ts\";\n\n// Create tables idempotently (safe to run multiple times)\nawait sqlite.execute(`\n CREATE TABLE IF NOT EXISTS users (\n id INTEGER PRIMARY KEY,\n name TEXT NOT NULL,\n email TEXT UNIQUE\n )\n`);\n\nconst result = await sqlite.execute(\"SELECT * FROM users\");\n/**\nresult:\n\n ResultSetImpl {\n columns: [ \"id\", \"name\", \"email\" ],\n columnTypes: [ \"INTEGER\", \"TEXT\", \"TEXT\" ],\n rows: [\n { id: 1, name: \"Charlie\", email: \"charlie@example.com\" },\n { id: 2, name: \"Dave\", email: \"dave@example.com\" }\n ],\n rowsAffected: 0,\n lastInsertRowid: undefined\n }\n*/\n\n// Parameterized queries (always use these for user input!)\nawait sqlite.execute({\n sql: \"INSERT INTO users (name, email) VALUES (?, ?)\",\n args: [\"Charlie\", \"charlie@example.com\"],\n});\n\n// Named parameters also supported\nawait sqlite.execute({\n sql: \"SELECT * FROM users WHERE email = :email\",\n args: { email: \"alice@example.com\" },\n});\n\n// Batch operations for atomic multi-statement transactions\n// All succeed together or all fail (rollback on error)\nawait sqlite.batch([\n {\n sql: \"INSERT INTO users (name, email) VALUES (?, ?)\",\n args: [\"Dave\", \"dave@example.com\"],\n },\n { sql: \"UPDATE users SET name = ? WHERE id = ?\", args: [\"David\", 4] },\n]);\n```\n\n**Important notes**:\n\n- Results return as `{columns: string[], rows: any[][]}` - map to objects as needed\n- Always use parameterized queries (`args`) for user input to prevent SQL injection\n- Use `sqlite.batch()` when multiple operations must succeed/fail together\n- Use `CREATE TABLE IF NOT EXISTS` for idempotent table creation\n- MCP tools (sqlite_execute/sqlite_batch) are for debugging; use `std/sqlite` in Val code\n- See https://docs.val.town/reference/std/sqlite/usage/ for complete documentation\n- Existing vals may use https://esm.town/v/std/sqlite for SQLite. Do not change\n this if it is already in place: std/sqlite accesses an SQLite database that is specific\n to the user, std/db accesses one that is specific to the val.\n\n### Blob Storage\n\n```typescript\nimport { blob } from \"@valtown/sdk\";\n\nawait blob.setJSON(\"mykey\", { data: \"value\" });\nconst data = await blob.getJSON(\"mykey\");\n```\n\n### Email Sending\n\n```typescript\nimport { email } from \"@valtown/sdk\";\n\nawait email.send({\n to: \"user@example.com\",\n subject: \"Hello\",\n text: \"Message body\",\n});\n```\n\n### OpenAI\n\n```ts\nimport { OpenAI } from \"https://esm.town/v/std/openai\";\nconst openai = new OpenAI();\nconst completion = await openai.chat.completions.create({\n messages: [{ role: \"user\", content: \"Say hello in a creative way\" }],\n model: \"gpt-4o-mini\",\n max_tokens: 30,\n});\n```\n\n## Val Town Utility Functions\n\nVal Town provides several utility functions to help with common project tasks.\n\n### Importing Utilities\n\nAlways import utilities with version pins to avoid breaking changes:\n\n```ts\nimport {\n parseProject,\n readFile,\n serveFile,\n} from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\n\n#### **serveFile** - Serve project files with proper content types\n\nFor example, in Hono:\n\n```ts\n// serve all files in frontend/ and shared/\napp.get(\"/frontend/*\", (c) => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", (c) => serveFile(c.req.path, import.meta.url));\n```\n\n#### **readFile** - Read files from within the project:\n\n```ts\n// Read a file from the project\nconst fileContent = await readFile(\"/frontend/index.html\", import.meta.url);\n```\n\n#### **listFiles** - List all files in the project\n\n```ts\nconst files = await listFiles(import.meta.url);\n```\n\n#### **parseProject** - Extract information about the current project from import.meta.url\n\nThis is useful for including info for linking back to a val, ie in \"view source\"\nurls:\n\n```ts\nconst projectVal = parseProject(import.meta.url);\nconsole.log(projectVal.username); // Owner of the project\nconsole.log(projectVal.name); // Project name\nconsole.log(projectVal.version); // Version number\nconsole.log(projectVal.branch); // Branch name\nconsole.log(projectVal.links.self.project); // URL to the project page\n```\n\nHowever, it's _extremely importing_ to note that `parseProject` and other\nStandard Library utilities ONLY RUN ON THE SERVER. If you need access to this\ndata on the client, run it in the server and pass it to the client by splicing\nit into the HTML page or by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use\n `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})`\n instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode\n symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use:\n ``\n- **Storage:** DO NOT use the Deno KV module for storage\n- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods\n- **Weather Data:** Use open-meteo for weather data (doesn't require API keys)\n unless otherwise specified\n- **View Source:** Add a view source link by importing & using\n `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the\n client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add\n `` to HTML to capture\n client-side errors\n- **Environment Variables:** Use `Deno.env.get('keyname')` with defensive checks:\n ```ts\n const apiKey = Deno.env.get(\"API_KEY\");\n if (!apiKey) {\n throw new Error(\"API_KEY not configured\");\n }\n ```\n Generally prefer APIs that don't require keys when possible.\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure\n compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer\n simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with\n `?deps=react@18.2.0,react-dom@18.2.0` and start the file with\n `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same\n version\n- **Styling:** Default to using TailwindCSS via\n `` unless otherwise\n specified\n\n### Error Handling\n\nFor HTTP vals, handle errors gracefully and return appropriate status codes:\n\n```ts\nexport default async function (req: Request): Promise {\n try {\n // Your logic here\n return new Response(\"Success\");\n } catch (error) {\n return new Response(`Error: ${error.message}`, { status: 500 });\n }\n}\n```\n\nFor non-HTTP vals, let errors bubble up with full context rather than catching\nand merely logging them.\n\n### CORS Headers\n\nWhen building APIs consumed by browsers, include CORS headers:\n\n```ts\nreturn new Response(JSON.stringify(data), {\n headers: {\n \"Content-Type\": \"application/json\",\n \"Access-Control-Allow-Origin\": \"*\",\n },\n});\n```\n\n## Project Structure and Design Patterns\n\n### Recommended Directory Structure\n\n```\n├── backend/\n│ ├── database/\n│ │ ├── migrations.ts # Schema definitions\n│ │ ├── queries.ts # DB query functions\n│ │ └── README.md\n│ └── routes/ # Route modules\n│ ├── [route].ts\n│ └── static.ts # Static file serving\n│ ├── index.ts # Main entry point\n│ └── README.md\n├── frontend/\n│ ├── components/\n│ │ ├── App.tsx\n│ │ └── [Component].tsx\n│ ├── favicon.svg\n│ ├── index.html # Main HTML template\n│ ├── index.tsx # Frontend JS entry point\n│ ├── README.md\n│ └── style.css\n├── README.md\n└── shared/\n ├── README.md\n └── utils.ts # Shared types and functions\n```\n\n### Backend (Hono) Best Practices\n\n- Hono is the recommended API framework\n- Main entry point should be `backend/index.ts`\n- **Static asset serving:** Use the utility functions to read and serve project\n files:\n\n ```ts\n import {\n readFile,\n serveFile,\n } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n\n // serve all files in frontend/ and shared/\n app.get(\"/frontend/*\", (c) => serveFile(c.req.path, import.meta.url));\n app.get(\"/shared/*\", (c) => serveFile(c.req.path, import.meta.url));\n\n // For index.html, often you'll want to bootstrap with initial data\n app.get(\"/\", async (c) => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n\n // Inject data to avoid extra round-trips\n const initialData = await fetchInitialData();\n const dataScript = ``;\n\n html = html.replace(\"\", `${dataScript}`);\n return c.html(html);\n });\n ```\n\n- Create RESTful API routes for CRUD operations\n- Always include this snippet at the top-level Hono app to re-throwing errors to\n see full stack traces:\n ```ts\n // Unwrap Hono errors to see original error details\n app.onError((err, c) => {\n throw err;\n });\n ```\n\n### Database Patterns\n\n- Run migrations on startup or comment out for performance\n- Change table names when modifying schemas rather than altering\n- Export clear query functions with proper TypeScript typing\n\n## Common Gotchas and Solutions\n\n1. **Environment Limitations:**\n - Val Town runs on Deno in a serverless context, not Node.js\n - Code in `shared/` must work in both frontend and backend environments\n - Cannot use `Deno` keyword in shared code\n - Use `https://esm.sh` for imports that work in both environments\n\n2. **SQLite Peculiarities:**\n - Limited support for ALTER TABLE operations\n - Create new tables with updated schemas and copy data when needed\n - Always run table creation before querying\n\n3. **React Configuration:**\n - All React dependencies must be pinned to 18.2.0\n - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of\n React files\n - Rendering issues often come from mismatched React versions\n\n4. **File Handling:**\n - Val Town only supports text files, not binary\n - Use the provided utilities to read files across branches and forks\n - For files in the project, use `readFile` helpers\n\n5. **API Design:**\n - `fetch` handler is the entry point for HTTP vals\n - Run the Hono app with\n `export default app.fetch // This is the entry point for HTTP vals`\n\n6. **HTTP Endpoint Discovery:**\n - HTTP vals have a `links.endpoint` field with the live deployment URL\n - Use this to test and verify your val is working correctly\n",[160],"abbb6954-fa4d-11f0-9326-42dde27851f2",".vtignore","abbb6a08-fa4d-11f0-9326-42dde27851f2",14,["D",1769387194903],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor",[167],"ab80af6c-fa4d-11f0-96ef-42dde27851f2","docs","ab80b020-fa4d-11f0-96ef-42dde27851f2",6,["D",1769387194518],"directory",[174],"34190a2e-fa4c-11f0-b7e5-42dde27851f2",".claude","34190b14-fa4c-11f0-b7e5-42dde27851f2",1,["D",1769386564671],[181],"pulls","branches","forks","envVars",{"_193":195,"_196":61},"connections",{"_193":61,"_194":61},"count","unfilledCount",2,"emptyCount",{"_43":180,"_32":181,"_30":182,"_137":-5,"_41":42,"_40":183,"_139":140,"_38":256,"_13":61,"_34":178,"_35":-5,"_24":25,"_143":-5,"_209":257,"_27":258},{"_43":249,"_32":250,"_30":251,"_137":182,"_41":42,"_40":195,"_139":140,"_38":252,"_13":61,"_34":20,"_35":253,"_24":25,"_143":-5,"_209":254,"_27":255},{"_43":173,"_32":174,"_30":175,"_137":-5,"_41":42,"_40":176,"_139":140,"_38":246,"_13":61,"_34":178,"_35":-5,"_24":25,"_143":-5,"_209":247,"_27":248},{"_43":237,"_32":238,"_30":239,"_137":175,"_41":42,"_40":240,"_139":140,"_38":241,"_13":242,"_34":20,"_35":243,"_24":25,"_143":-5,"_209":244,"_27":245},{"_43":232,"_32":33,"_30":31,"_137":175,"_41":42,"_40":14,"_139":140,"_38":233,"_13":234,"_34":20,"_35":37,"_24":25,"_143":-5,"_209":235,"_27":236},{"_43":224,"_32":225,"_30":226,"_137":175,"_41":42,"_40":227,"_139":140,"_38":228,"_13":195,"_34":20,"_35":229,"_24":25,"_143":-5,"_209":230,"_27":231},{"_43":166,"_32":167,"_30":168,"_137":-5,"_41":42,"_40":169,"_139":140,"_38":221,"_13":61,"_34":20,"_35":171,"_24":25,"_143":-5,"_209":222,"_27":223},{"_43":159,"_32":160,"_30":161,"_137":-5,"_41":42,"_40":162,"_139":140,"_38":218,"_13":61,"_34":20,"_35":164,"_24":25,"_143":-5,"_209":219,"_27":220},{"_43":152,"_32":153,"_30":154,"_137":-5,"_41":42,"_40":155,"_139":140,"_38":215,"_13":61,"_34":20,"_35":157,"_24":25,"_143":-5,"_209":216,"_27":217},{"_43":145,"_32":146,"_30":147,"_137":-5,"_41":42,"_40":148,"_139":140,"_38":212,"_13":61,"_34":20,"_35":150,"_24":25,"_143":-5,"_209":213,"_27":214},{"_43":134,"_32":135,"_30":136,"_137":-5,"_41":42,"_40":138,"_139":140,"_38":208,"_13":61,"_34":20,"_35":142,"_24":25,"_143":-5,"_209":210,"_27":211},["D",1769387194639],"children",[],[135],["D",1769387194804],[],[146],["D",1769387263310],[],[153],["D",1769387194801],[],[160],["D",1769387194903],[],[167],"d4811c80-fa4d-11f0-8f56-42dde27851f2","research.md","3439c0fc-fa4c-11f0-8dfc-42dde27851f2",16,["D",1769387263304],"# 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",[],[174,225],"e96b2c84-fa4e-11f0-b1ca-42dde27851f2",["D",1769387727886],4,[],[174,33],"b9cd414c-fa4e-11f0-b13f-42dde27851f2","bsky-bot-thesis.md","34474704-fa4c-11f0-98a8-42dde27851f2",20,["D",1769387648002],3,"# 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\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\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)\n\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\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\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\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\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\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\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\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\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\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```\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\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\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\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",[],[174,238],["D",1769387194518],[200,201,202],[174],"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",[],[181,250],["D",1769386564671],[198],[181],["D",1769386563309],["D",1789445472057],{"_98":97,"_105":101},{"_98":97,"_99":-5,"_100":101,"_18":55,"_102":103,"_104":25},{"_13":87,"_32":88,"_43":42,"_89":44,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":45,"_96":97},"ctx",{"_80":-5,"_124":297,"_298":299,"_300":301,"_302":25,"_303":25,"_304":25,"_305":140,"_306":-5,"_307":-7,"_308":-7,"_309":61,"_310":25,"_311":25,"_312":-5,"_313":25,"_314":25,"_315":25,"_316":-5},"ENV",{"_268":269,"_270":271,"_272":88,"_273":274,"_275":276,"_277":278,"_279":280,"_281":282,"_283":284,"_285":286,"_287":288,"_289":290,"_291":292,"_293":294,"_295":296},"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

Art Institute of Chicago

Diff · v22