tcgevents

Build a local-first trading card game event tracker. Single Python project, no accounts, no cloud, no telemetry.

Stack, non negotiable:
- Python 3.11, FastAPI, Jinja2 templates, SQLite via sqlite3 stdlib
- Plain server rendered HTML plus a little vanilla JS, no build step, no npm
- Leaflet from a CDN for the map, OpenStreetMap tiles

Data model (events): id, game (magic, pokemon, yugioh, lorcana, other), title, format, venue_name, address, city, country, lat, lon, starts_at (UTC), ends_at nullable, entry_fee nullable, url nullable, notes, source (manual or paste), created_at, updated_at.
Also a settings row for home_lat, home_lon, default_radius_km.

Features, in scope:
1. Add and edit events through a simple HTML form. Manual entry is the primary path, treat it as first class.
2. A "paste dump" page: textarea where I paste messy text from a store Discord or Facebook post, plus a parser that extracts candidate title, date, time and fee with regex and dateutil, then shows an editable pre-filled form. No LLM call. If parsing fails, say so and let me fill it in.
3. List view: filter by game, date range, city, and distance from home using haversine on stored lat/lon. Sort by starts_at.
4. Map view: pins for filtered events, popup with title, time, venue, link.
5. Calendar: current month grid, events per day.
6. Export: /export.ics returns a valid VCALENDAR of the current filter. Also /export.json.
7. Geocoding: optional. If GEOCODE_PROVIDER and GEOCODE_API_KEY are set in .env, geocode addresses on save; otherwise leave lat/lon null and hide distance filters gracefully.
8. Recurring events: a weekly repeat option that materializes the next 8 occurrences, each editable and cancellable individually.

Out of scope, do not build: user accounts, multi tenancy, scraping any third party site, push notifications, a mobile app, anything that pretends to have nationwide coverage.

Deliverables: app.py, db.py, parse.py, templates/, static/, schema.sql, .env.example, seed.py with 12 fake events across 3 cities, and a README with run instructions (uvicorn, one command). Include pytest tests for the parser and the ICS output. Timezones: store UTC, display in a TZ set in .env, default America/New_York.

# AGENTS.md — Build guide for tcgevents

## Project scope
A local event tracker where you paste or manually add tournaments, then browse them by game, date and distance with calendar and ICS export.

Catalogue verdict: no. The software here is a searchable list with a map and some filters, which an agent can produce before your coffee cools. The product is not the list, it is the fact that events are in it: store owners posting schedules, organizers keeping dates current, players trusting it enough to check it weekly. Scrape it and you own a snapshot that starts rotting the moment a shop moves its Friday night draft. Official publisher locators exist, but they are partial, rate limited, and hostile to bulk use, and the small local scene stuff never appears there at all. Build the personal tracker if you play in two cities, but do not pretend it replaces the directory.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Somewhere to actually get event data: official store locators, store Discords, Facebook pages, or your own typing
- Optional geocoding API key in .env if you want distance filtering
- Ongoing willingness to maintain your own listings, which is the entire catch

## Stack and architecture
- Build a local-first trading card game event tracker. Single Python project, no accounts, no cloud, no telemetry.
- Model the inputs, state transitions, and outputs named in this trading card game event discovery prompt; keep source IDs and timestamps.
- Interface for this trading card game event discovery workflow: a focused trading card game event discovery input, review, and export interface.

## Security and data integrity
- A "paste dump" page: textarea where I paste messy text from a store Discord or Facebook post, plus a parser that extracts candidate title, date, time and fee with regex and dateutil, then shows an editable pre-filled form. No LLM call. If parsing fails, say so and let me fill it in.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: Coverage: every store you did not personally enter is invisible.

## Agent implementation rules
- Project rule, data: Model the inputs, state transitions, and outputs named in this trading card game event discovery prompt; keep source IDs and timestamps.
- Project rule, behavior: Add and edit events through a simple HTML form. Manual entry is the primary path, treat it as first class.
- Project rule, recovery: A "paste dump" page: textarea where I paste messy text from a store Discord or Facebook post, plus a parser that extracts candidate title, date, time and fee with regex and dateutil, then shows an editable pre-filled form. No LLM call. If parsing fails, say so and let me fill it in.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this trading card game event discovery operation with sample or user-owned data: Add and edit events through a simple HTML form. Manual entry is the primary path, treat it as first class.
- Show a concrete result or export: Export: /export.ics returns a valid VCALENDAR of the current filter. Also /export.json.
- State the practical limit: Coverage: every store you did not personally enter is invisible.

## Engineering roadmap
1. Phase 1, architecture and data: Build a local-first trading card game event tracker. Single Python project, no accounts, no cloud, no telemetry. Model the inputs, state transitions, and outputs named in this trading card game event discovery prompt; keep source IDs and timestamps.
2. Phase 2, implement: Add and edit events through a simple HTML form. Manual entry is the primary path, treat it as first class.
3. Phase 3, implement: List view: filter by game, date range, city, and distance from home using haversine on stored lat/lon. Sort by starts_at.
4. Phase 4, review and output: Map view: pins for filtered events, popup with title, time, venue, link. Export: /export.ics returns a valid VCALENDAR of the current filter. Also /export.json.
5. Phase 5, recovery and acceptance: A "paste dump" page: textarea where I paste messy text from a store Discord or Facebook post, plus a parser that extracts candidate title, date, time and fee with regex and dateutil, then shows an editable pre-filled form. No LLM call. If parsing fails, say so and let me fill it in. Verify this invariant with a saved fixture: A removed post must not reappear from a delayed notification; permission checks must apply to every read and write. State the practical limit: Coverage: every store you did not personally enter is invisible.

## Paid-product capabilities outside this build
- Coverage: every store you did not personally enter is invisible
- Freshness: cancellations, venue changes and date shifts arrive nowhere
- Organizer side: shops have no reason to tell your laptop about their new league night
- Discovery for travel: the whole point of a directory is events in cities you do not know
- Whatever normalization the real site does across games, formats and regional naming chaos

## Implementation prompt
Build a local-first trading card game event tracker. Single Python project, no accounts, no cloud, no telemetry.

Stack, non negotiable:
- Python 3.11, FastAPI, Jinja2 templates, SQLite via sqlite3 stdlib
- Plain server rendered HTML plus a little vanilla JS, no build step, no npm
- Leaflet from a CDN for the map, OpenStreetMap tiles

Data model (events): id, game (magic, pokemon, yugioh, lorcana, other), title, format, venue_name, address, city, country, lat, lon, starts_at (UTC), ends_at nullable, entry_fee nullable, url nullable, notes, source (manual or paste), created_at, updated_at.
Also a settings row for home_lat, home_lon, default_radius_km.

Features, in scope:
1. Add and edit events through a simple HTML form. Manual entry is the primary path, treat it as first class.
2. A "paste dump" page: textarea where I paste messy text from a store Discord or Facebook post, plus a parser that extracts candidate title, date, time and fee with regex and dateutil, then shows an editable pre-filled form. No LLM call. If parsing fails, say so and let me fill it in.
3. List view: filter by game, date range, city, and distance from home using haversine on stored lat/lon. Sort by starts_at.
4. Map view: pins for filtered events, popup with title, time, venue, link.
5. Calendar: current month grid, events per day.
6. Export: /export.ics returns a valid VCALENDAR of the current filter. Also /export.json.
7. Geocoding: optional. If GEOCODE_PROVIDER and GEOCODE_API_KEY are set in .env, geocode addresses on save; otherwise leave lat/lon null and hide distance filters gracefully.
8. Recurring events: a weekly repeat option that materializes the next 8 occurrences, each editable and cancellable individually.

Out of scope, do not build: user accounts, multi tenancy, scraping any third party site, push notifications, a mobile app, anything that pretends to have nationwide coverage.

Deliverables: app.py, db.py, parse.py, templates/, static/, schema.sql, .env.example, seed.py with 12 fake events across 3 cities, and a README with run instructions (uvicorn, one command). Include pytest tests for the parser and the ICS output. Timezones: store UTC, display in a TZ set in .env, default America/New_York.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.