Repo cleanup & dependency refresh

[holden]

The repo has gone ~3 months without a commit (last: 8ba50a6 on 2026-01-22) and accumulated significant doc clutter and dependency drift. Treat this as a cleanup epic — four sequential PRs, each independently mergeable. Order matters: docs first (no risk), CI second (so later PRs are validated), then deps.

---

PR 1 — Doc cleanup

No runtime behavior change. Mechanical deletion. Git history preserves the files; do not archive to docs/archive/.

Root has 30 .md files. Keep README.md and AGENTS.md. Delete the other 28:

AUDIT_SUMMARY.md                 PAGE_AUDIT_REPORT.md
CACHE_AUDIT_PHASE1.md            PERFORMANCE_OPTIMIZATION.md
CITY_PAGE_IMPROVEMENTS.md        ROUTE_AUDIT_REPORT.md
COMPREHENSIVE_AUDIT_REPORT.md    SEARCH_IMPLEMENTATION_ISSUE.md
COUNTRY_PAGE_UI_IMPROVEMENTS.md  SITE_FUNCTIONALITY_COMPARISON.md
DATABASE_INDEXES.md              SITEMAP_ANALYSIS_ISSUE_37.md
GITHUB_ISSUE.md                  SITEMAP_V1_V2_COMPARISON.md
HOMEPAGE_AUDIT_ISSUE.md          SITEMAP_VERIFICATION_SUMMARY.md
LOCALIZATION_MIGRATION_ISSUE.md  SMART_404_HANDLER_ISSUE_39.md
LOCALIZATION_TIME_CURRENCY.md    SMART_404_SUMMARY.md
URGENT_ACTION_PLAN.md            URL_ANALYSIS_GITHUB_ISSUE.md
URL_MAPPING_REFERENCE.md         URL_PATTERN_MATCHING_ANALYSIS.md
VENUE_CARD_IMAGE_FALLBACK.md     VENUE_PAGE_IMPROVEMENTS_ISSUE.md
VENUE_PAGE_IMPROVEMENTS.md       VENUE_SITEMAP_AUDIT.md

.claude/ directory — keep these four, delete the rest:

• CLAUDE.md (project instructions)
• DEPLOYMENT.md (active reference)
• project-context.md (active reference)
• settings.local.json (gitignored anyway)

Delete from .claude/: CODERABBIT_REVIEW_FIXES.md, MAP_CODE_EXAMPLES.md, MAP_IMPLEMENTATION_RESEARCH.md, MAP_QUICK_REFERENCE.txt, MAP_RESEARCH_INDEX.md, MIGRATION_ROADMAP.md, migration-plan.md, PHASE_0_FINDINGS.md, PHASE_3_FLAT_URL_TESTING.md, PHASE_5_SEO_VALIDATION.md, PHASE_6_PRODUCTION_CONFIG.md, PHASE_7_SUMMARY.md, PHASE_7_TESTING_GUIDE.md, PRODUCTION_READINESS.md, SITEMAP_BASELINE.md, SLUG_GENERATION_GUIDE.md.

Delete .github/ISSUE_MIGRATE_FROM_PLANETSCALE_TO_FLY_POSTGRES.md — should be a closed GH issue, not a file.

Acceptance: root contains only README.md + AGENTS.md; .claude/ contains only the four files listed above.

---

PR 2 — CI workflow

Lands before dep bumps so they run through CI automatically.

Currently the only workflow is .github/workflows/fly-deploy.yml (confirmed). Add .github/workflows/ci.yml running mix precommit on push + PR. The precommit alias already exists in mix.exs:

precommit: ["compile --warning-as-errors", "deps.unlock --unused", "format", "test"]

Acceptance: CI runs on every push and PR; green on main before merging PR 3.

Out of scope (separate future issue): adding credo / dialyxir. Don't expand this PR into tooling-policy work.

---

PR 3 — Safe dependency bumps

Run mix deps.update for the patch/minor list below, then mix precommit and a manual smoke test.

Package	Current	Latest
phoenix	1.8.1	1.8.5
phoenix_live_view	1.1.16	1.1.28
phoenix_live_reload	1.6.1	1.6.2
bandit	1.8.0	1.10.4
ecto_sql	3.13.2	3.13.5
postgrex	0.21.1	0.22.0
req	0.5.15	0.5.17
swoosh	1.19.8	1.25.0
castore	1.0.17	1.0.18
ex_cldr	2.44.0	2.47.2
ex_cldr_dates_times	2.21.0	2.25.6
ex_cldr_numbers	2.36.0	2.38.1
lazy_html (test)	0.1.8	0.1.11

Acceptance: mix hex.outdated shows no "Update possible" rows for non-major bumps; CI green.

---

PR 4 — Major-version dep decisions (investigation, not implementation)

This PR is gated on a written decision per package before any code lands. Each needs a brief evaluation: upgrade now, pin with a comment explaining why, or defer.

• gettext 0.26.2 → 1.0.2 — Phoenix gen templates assume 1.0+. Likely a straight upgrade, but check generated gettext macros still compile.
• ex_cldr_calendars 1.26.4 → 2.4.2 — major bump, touches i18n surface.
• hackney 1.25.0 → 4.0.0 — verify whether req still pulls it as a transitive; it may be safe to remove from direct deps entirely.

Acceptance: each package has a tracked decision (upgrade or pin-with-comment) in mix.exs; CI green.

---

Verification

ls *.md            # PR 1: should show 2 files
ls .claude/        # PR 1: should show 4 entries
gh workflow list   # PR 2: should show ci.yml
mix hex.outdated   # PR 3: no "Update possible" for safe list

[holden]

PR 4 investigation results

All four PRs are now committed locally on separate branches. Decisions per major-version dep:

Dep	Decision	Reason
ex_cldr_calendars 1.26.4 → 2.4.2	upgrade	Single CLDR usage (Cldr.Calendar provider in lib/trivia_advisor_web/helpers/localization_helpers.ex); compiles clean with --warnings-as-errors.
ex_cldr_dates_times 2.21.0 → 2.25.6	upgrade (bonus)	Was held back by ex_cldr_calendars 1.x. Moves together. Originally on PR 3's safe-bump list but turned out not to be safe in isolation.
hackney direct dep	remove from mix.exs	Not used directly anywhere — the only Hackney strings in the repo are the London borough name in a venue normalization comment and a Swoosh-adapter comment. Still pulled in transitively by swoosh and tzdata, so runtime behavior is unchanged. Avoids the 4.0.0 rewrite churn entirely.
gettext 0.26.2 → 1.0.2	defer	Application code is already 1.0-style (use Gettext, backend: ...). The blocker is timex 3.7.13, which still requires gettext ~> 0.26. Wait for timex to update, or open a follow-up issue to migrate off timex (modern Elixir's DateTime/Calendar cover most needs).

After the four PRs land:

• mix hex.outdated will show only gettext as "Update not possible".
• The hackney "Update not possible" row disappears — it's no longer a direct dep.

Branches ready to push

PR	Branch	SHA
1	cleanup/docs	da5c373
2	cleanup/ci	bd18732
3	cleanup/deps-safe	7a82d36
4	cleanup/deps-major	a6b1c6d

Notes on PR 2

• mix test is intentionally not in the CI workflow yet. The test suite boots the full app and queries Postgres with a schema owned by Eventasaurus — CI can't reproduce it without seeded fixtures. There's a TODO comment in ci.yml tracking this. Worth a follow-up issue.
• One pre-existing format drift in lib/trivia_advisor_web/live/venue_show_live.ex was fixed in the same commit so the new --check-formatted step passes on first run.

Notes on PR 3

• 12 packages bumped, not 13 — ex_cldr_dates_times was reclassified to PR 4 mid-flight (its 2.25.x release requires ex_cldr_calendars ~> 2.4).