docs: sync README with research-assist tool, judge calibration, and 8-title status - #8
Merged
Merged
Conversation
…-title status - Add the live demo link (was missing entirely) with the documented Render free-tier cold-start/filesystem-reset caveat. - Fix stale '7 hand-researched' counts to 8 (Gone Girl was added to content/researched/ before this sync) across README and DESIGN.md's Pending section; same fix in resolve_tmdb_ids.py's docstring. - Document webapp/research_assist.py (D14): what it does, the best-of-3 design, the sanitize_grounding() safety net, and its current one-title-tested status -- new README section plus a Status/How-it's- built/Roadmap mention. - Add Configuration (.env keys: TMDB_READ_ACCESS_TOKEN, GROQ_API_KEY, ANTHROPIC_API_KEY, UPSTASH_REDIS_REST_URL/TOKEN -- all optional, nothing paid required), Project layout, Roadmap (from CLAUDE.md's Next task), and Limitations sections. - Limitations states the SubstringJudge/LLMJudge recall gap plainly (recall 0.0 / 0.089) instead of leaving it implicit in the results tables further down. - Add Groq and TMDB badges -- both genuinely load-bearing (free baseline generator, LLMJudge calibration, research-assist, browse-tier posters) and previously undocumented in the badge row. Verified before writing: git log, docs/DESIGN.md D1-D14, all CLI commands in evals/run_eval.py's argparse, content/researched/ file count, pytest (8/8 pass), and a local run of webapp/app.py. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCyfwtJ1wiBGdiiscqufRU
serpeigd
marked this pull request as ready for review
August 7, 2026 07:01
This was referenced Aug 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Documentation-sync pass on the README (and two small doc/docstring fixes elsewhere). No code behavior changed;
pytest tests/still 8/8 green.https://twistify.onrender.comwith the already-documented Render free-tier cold-start/filesystem-reset caveat (couldn't independently verify reachability from this sandbox — outbound egress to that host is blocked by the sandbox's network proxy; treat as expected Render free-tier behavior perCLAUDE.md, not a broken link).content/researched/(git log confirms, and the folder has 8 files) before this sync started, but the README, anddocs/DESIGN.md's "Pending" section, andwebapp/resolve_tmdb_ids.py's docstring, still said 7. Fixed all three. (CLAUDE.mditself has the same stale "7 hand-researched films" line in its "What this is" section — left untouched since it wasn't in scope, flagged for the repo owner instead.)webapp/research_assist.py(D14) for the first time in the README: what it does (Wikipedia+TMDB retrieval → draftedContentPack), the best-of-3 generation design, thesanitize_grounding()code-level safety net, and its honest current status (tested end-to-end on one title, Citizen Kane)..envkeys — TMDB/GROQ/ANTHROPIC/UPSTASH, all optional, nothing paid required), Project layout, Roadmap (mirrorsCLAUDE.md's "Next task"), Limitations (states theSubstringJudge/LLMJudgerecall gap plainly up top instead of leaving it implicit further down the page).LLMJudgecalibration, research-assist, browse-tier posters) and previously undocumented.Verified before writing
git log --oneline -30, full repo tree,docs/DESIGN.mdD1–D14.pytest tests/ -v→ 8/8 pass.python webapp/app.pylocally, confirmed it serves and the two existing screenshots still match the UI mechanics shown (spoiler curtain, catalogue sidebar) — the sidebar's "Con contenido" badge count in the screenshots is stale at 7 vs. the real 8 now, a cosmetic one-off discrepancy not worth a screenshot regen per the task's "don't fabricate screenshots of features that don't visually differ" guidance; flagging it here instead.argparse/docstrings inevals/run_eval.py,webapp/prewarm_translations.py,webapp/resolve_tmdb_ids.py,evals/calibrate_*_external.py..gitignoreto confirmcontent/_drafts/(research-assist output) and.envare correctly excluded, matching what the README now claims.Left for the repo owner
LLMJudge/SubstringJudgerecall gap (0.089 / 0.0) is a genuine, unresolved limitation — now stated plainly in a dedicated Limitations section rather than only inside the results tables. PerCLAUDE.md's "Next task", Milestone 1 (retrieval) shouldn't start until this is resolved.CLAUDE.md's own "What this is" section still says "7 hand-researched films" (its "Status" section elsewhere correctly says 8/20) — a small internal inconsistency, not touched sinceCLAUDE.mdwasn't in this task's scope.Generated by Claude Code