comedy-cellar-bot

Entry-point system map for comedy-cellar-bot - monorepo layout, SST resource graph, data flow, load-bearing design decisions with rationale, invariants whose violation is an incident, and known weak points with file:line. Use when new to this repo, when planning any change that spans packages/ or infra/, when asking "why is it built this way", or before touching scraping, stages, the shared database, crons, or the reservation path. Also the index to the 14 sibling cellar-* skills.

Catalog of every configuration axis in comedy-cellar-bot - the five SST secrets (and the load-bearing clertPublishableKey typo), the SES Email identity resource, root .env, the Lambda env flags IS_ACTIVE/IS_CRON/STAGE, the per-stage map in infra/config.ts, the frontend VITE_ env chain and generated sst-env.d.ts files, localStorage flags, and cron schedules as config. Use when adding or rotating a secret, adding an env var or a new stage, wiring config into a Lambda or the frontend, or when a deploy crashes at infra/api.ts:23, a cron runs (or refuses to run) in the wrong stage, or import.meta.env comes back undefined.

Operations runbook for comedy-cellar-bot - what sst dev / pnpm deploy:prod actually do, the prod topology (comedycellar.mafz.al domains, crons, Supabase), the three cron jobs' real behavior, the admin-email telemetry decoder, log access, DB ops commands, and health checks. Use when running the app locally with sst dev, deploying or removing a stage, interpreting a "New Show Cron" / "Sync Show Cron" / "new reservation!" / "Show Notification Cron" email, wondering whether a cron actually ran, triggering a manual sync, or looking for logs of a deployed Lambda.

Symptom-to-triage tables, time-costing traps, and discriminating experiments for comedy-cellar-bot. Use when diagnosing a live misbehavior - empty show listings, crons that seem dead, off-by-one dates, duplicate rows from /api/shows/new, /api/shows/scan returning [], 500s from /api/settings, Clerk auth failures, frontend infinite loading, CI/build breakage, "Cannot find name 'sst'" type errors, broken mobile layout, or admin-email floods/silence.

Measure-don't-eyeball diagnostic recipes and runnable probes for comedy-cellar-bot — check-api.sh and freshness-check.sh (read-only health/scraper canary against our own API), plus recipes for token staleness, offline fixture parsing, proving a library behavior with node -e, DB spot checks, log tailing, bundle size, and config-drift greps. Use when you need a NUMBER instead of a guess — "is the scraper still landing shows", "is the API up", "how old is the anti-bot token", "does this show up in prod", "how big is the bundle", "prove this function returns [] not throws" — or before/after any change when you want evidence rather than a hunch.

Chronicle of every settled investigation, dead end, and revert in comedy-cellar-bot, each as Symptom → Root cause → Evidence (SHA/date/path) → Status. Use when a bug looks familiar, before re-attempting something that may have been tried and abandoned (Cognito, Sentry, Slack notifications, multi-day sync), when asked "why is this dead code here" (core/slack.ts, frontier.ts, commented Sentry), or when writing a post-incident entry.

Ranked open problems for comedy-cellar-bot (ship user notifications, scraper self-monitoring, backend test harness, data-quality repairs, multi-venue) each with the specific asset, first file-level steps, and a falsifiable milestone; plus the research discipline for turning a hunch into an accepted result here. Use when asked "what should we build next", "how do we make this self-running", "how do we ship notifications", when planning a new feature or experiment, or when deciding whether an idea is proven enough to promote. Not for live bugs or outages.

Decision-gated recovery runbook for a live scraper outage: show data in comedy-cellar-bot has gone stale, crons are erroring, comedycellar.com returns 403/challenge/garbage, or the site's HTML/JSON changed shape. Use when "the scraper broke", when "Sync Show Cron" failure emails arrive, when the freshness probes show no new shows landing, or when planning/executing an x-code-localize token recapture. Contains numbered phases with exact commands, expected observations, branch playbooks (token recapture, HTML drift, JSON drift, hard blocking), fenced wrong paths, and a numeric definition of "recovered".

From-scratch environment setup for comedy-cellar-bot and its known traps - node/pnpm/corepack prereqs, the two-pnpm-workspace install gotcha, pnpm v10 build-script gates, what works with vs without AWS credentials, why root tsc fails without .sst platform types, and a verified-environment checklist with expected outputs. Use when setting up a fresh clone or sandbox, when pnpm install or lockfiles behave strangely, when root tsc --noEmit says "Cannot find name 'sst'", when frontend tsc errors on dist/assets/*.js, or when sst install fails with HTTP 403.

Change classification, required gates, and approval rules for comedy-cellar-bot. Use BEFORE making any change to decide its class (frontend/backend/scraping/DB-schema/infra), which gates it must pass, and whether it needs owner approval. Also use when asked "can I deploy this", "can I change the cron schedule", "who approves X", when touching packages/core/createReservation.ts, packages/core/requester.ts, infra/cron.ts, migrations/, or secrets, or when coordinating parallel agents on shared files.

Schema reference, id/externalId conventions, per-entity upsert semantics, the roomDictionary, drizzle-kit migration workflow, and shared-database discipline for comedy-cellar-bot's Supabase Postgres. Use when adding or changing a table/column in packages/core/sql/*.sql.ts, writing queries or upserts in packages/core/models/, running pnpm db generate/migrate, debugging duplicate or missing rows (comic name variants, N-plicated shows in /api/shows/new, shows silently not persisting), or bootstrapping/seeding an empty database.

Decision-gated campaign for the KNOWN data-quality defects in comedy-cellar-bot's read/ingest path. Use when /api/shows/new returns duplicate shows or a wrong "total", a comedian's show history looks split or a comic appears twice under near-identical names, /api/shows/scan always returns [], "special" shows are missing from listings, a whole night's shows silently fail to persist, or when planning an ingestion/query-correctness fix. Numbered phases with exact commands, expected numbers at every gate, ranked fix menus with derivation obligations, fenced wrong paths, and a numeric definition of "done".

The "vintage marquee" design system and frontend conventions for packages/frontend - token architecture in src/theme.css, the CONTRACT.md rules (tokens-never-raw-hex, ownership, additive props), Tailwind v4 CSS-first quirks, Preact-not-React compat wiring, the ui/ component kit, and the dark/light theme runtime. Use when styling or adding any frontend screen/component, when colors don't flip in dark mode, when a Tailwind utility mysteriously doesn't exist, when touching theme.css/style.css/CONTRACT.md/authAppearance.ts, or when a react library misbehaves under preact/compat.

Domain-knowledge pack for talking to comedycellar.com from this repo: the three reverse-engineered endpoints (lineup HTML-in-JSON, getShows JSON, addReservation REAL booking) with request/response contracts, the HTML parse contract in parseLineUp.ts, the requester.ts fingerprint (random UA + hardcoded x-code-localize anti-bot token + x-page-creation), the anti-bot/politeness history, NY-timezone doctrine, and unofficial-fan-site positioning. Use when changing or debugging any fetch to comedycellar.com, decoding/recapturing the x-code-localize header, editing parseLineUp / fetchLineUp / fetchShows / createReservation, understanding show-id identity, empty/garbage scrape output, or reservation booking rules. NOT a live-outage runbook — see cellar-scraper-recovery-campaign for that.

What counts as evidence before claiming a change to comedy-cellar-bot works - the honest state of testing (zero automated tests, no backend CI, frontend CI green since PR