Files

T

Eric Wagoner 2273ac7cf7 Web review UI: bggpipe review --web (FastAPI, localhost, no build step)

One self-contained page (inline CSS/JS, system fonts, works offline):
match cards show source photos, extracted cues, and candidates with
cached-XML thumbnails (placeholder tiles until real fixtures exist);
actions are pick / manual BGG id / reject, plus a skippable editions
pass (pick or unknown). Keyboard-first: j/k navigate, 1-9 pick, r
reject, m manual, u unknown, d dismiss. Every decision writes
matches.csv through the same ReviewSession methods the TUI now shares —
the TUI remains as the no-flag fallback. unidentified.json renders as
visually distinct reshoot work-orders with dismissals persisted in
data/unidentified_dismissed.json (survives extract rebuilds). Progress
tally and a diff-ready done screen; photo serving is allowlisted to
photos/ contents; server binds 127.0.0.1 only. Layout leaves room for
a later games.json browse view.

Provenance guard: fixture generators now write STUB_FIXTURES.marker
into their cache dirs, and CLAUDE.md gains the hard rule that stub-
resolved version_ids are placeholders — upload must refuse to run
while data/bgg_cache/STUB_FIXTURES.marker exists.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-08-01 15:13:29 -04:00

3.6 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

bggpipe — a resumable, idempotent CLI pipeline: shelf photos → Claude vision title + edition-cue extraction → BoardGameGeek ID and version matching → human review → collection diff → upload to BGG via Playwright → metadata enrichment (games.json). Full design: @bgg-shelf-pipeline-spec.md. The repo is greenfield — no code exists yet. Follow the spec's "Suggested Build Order" when scaffolding; re-run /init once code exists.

Stack (decided, not yet scaffolded)

Python 3.12+, deps via uv (uv add, uv run), CLI framework typer, tests pytest, lint/format ruff.
Browser automation: Playwright (not Selenium). Needs uv run playwright install chromium after install.
Vision: Anthropic API, latest Sonnet model.

Hard rules (from spec — never violate)

≤1 request every 2 seconds to any BGG endpoint; jittered backoff on 429/503. Upload stage: 2–4 s randomized delay between games.
Credentials never touch disk or logs. ANTHROPIC_API_KEY, BGG_USERNAME, BGG_PASSWORD, BGG_API_TOKEN come from env vars only. Playwright storage state is credential-adjacent — keep it gitignored.
The XML API requires a registered app token (Authorization: Bearer, from BGG_API_TOKEN) — unregistered requests get 401. Until Eric's registration at boardgamegeek.com/applications is approved, tests run on the stub fixtures in tests/fixtures/bgg_cache/; re-record them with scripts/record_fixtures.py once the token exists.
Every stage is idempotent and resumable — killing mid-run and restarting must lose no work; re-runs skip already-processed items.
Use only the XML API2 and the public website — no undocumented BGG endpoints (BGG tightened access policies in 2025).
BGG has no write API: writes drive the real website with a logged-in Playwright session.
Stub-resolved data is never upload-ready. All version_ids (and some game data) in matches.csv, to_add.csv, and to_update.csv currently come from SYNTHETIC stub fixtures — placeholders until real fixtures exist. When BGG_API_TOKEN arrives: delete both cache dirs, re-record fixtures, resolve --force, re-review. The caches carry a STUB_FIXTURES.marker provenance file (written by the fixture generators); the upload stage MUST refuse to run while data/bgg_cache/STUB_FIXTURES.marker exists.

Domain gotchas

Base game vs. expansion vs. new edition is the top failure mode — bias matching toward ambiguous over auto-match ("Wingspan Europe" must not match base Wingspan).
Editions/versions matter: Eric owns multiple editions of some games — each is a separate collection entry (keyed by collid on BGG). Never guess a version: no legible cues → version_unknown and a version-less collection entry.
Normalize titles (casefold, strip punctuation/articles, special chars like é/&/:) identically on both sides of a match; dedupe across photos but keep source_photos provenance.
Detailed BGG API behavior (202 queueing, collection-endpoint quirks, endpoints): use the bgg-api skill. If the spec's BGG behavior changes, update the bgg-api skill to match — they must not drift.

Git

Remote is self-hosted Gitea 1.26 (git.kestrelsnest.social), not GitHub — gh CLI does not work here.
Commit data/matches.csv, data/to_add.csv, data/upload_log.csv, data/titles.json, data/unidentified.json, data/games.json. Never commit data/bgg_cache/, photos/, Playwright storage state, or .env.

3.6 KiB Raw Blame History Unescape Escape