Day 02 — Codex Sync (Quiet, Local-First, No Babysitting)

What we set out to build

The problem

The Codex worked… but too much of the experience depended on users knowing when to click the “right” buttons: refresh → rescan → wait → repeat.
A launcher shouldn’t feel like a ritual. It should feel dependable, even when it’s doing a lot.

Ref: ARCH-NOTES

The promise

• Local-first stays non-negotiable
• IGDB keys stay sealed in the backend
• Enrichment happens progressively so the UI stays responsive

Ref: ARCH-NOTES

What shipped today ✅

1) Background Codex sync (quiet by default)

Missing covers + metadata now fill in over time via codex_sync_missing(limit) — no more manual per-game babysitting.

Ref: ARCH-NOTES · TASK-LIST · CHANGELOG

2) A single-flight sync loop with backoff

Frontend triggers sync at the right moments (boot, after setup, after scan), then seals itself once there’s no work left — or if IGDB is unavailable.

Ref: TASK-LIST · ARCH-NOTES

3) Manual “scribe this now” (without command collisions)

We added a gated user command: refresh_game_codex_gated
This avoids Tauri command macro name collisions while still giving a clean “do it now” option.

Ref: TASK-LIST · ARCH-NOTES

4) Backlog Board foundations aligned to canon

Five visible columns, no weird exclusions: Wishlist → Backlog → In Progress → Completed → Abandoned

Ref: BACKLOG-BOARD-SPEC

5) Ordering that doesn’t forget your intent

Stable within-column ordering is backed by sort_index and persisted to SQLite — so the board stays consistent between sessions.

Ref: DB-SCHEMA · CHANGELOG

Behind the curtain 🕯️

The choice: progressive batches over “big sync”

We chose a progressive batch model instead of a single “big sync moment.”

Why? Because a launcher’s first job is to feel safe.

If the UI locks up while the Codex is forging metadata, players assume something’s broken — and on Windows, that “Not Responding” vibe hits at the worst possible time. So now the Codex scribes in small UI-safe batches and reports back a clean summary (igdb_enabled, what was attempted, what changed).

Ref: ARCH-NOTES

The security boundary stays tight

IGDB credentials remain backend-only, injected at build time, never stored in the DB, and never surfaced to React — so background sync doesn’t widen the attack surface.

Ref: ARCH-NOTES · DB-SCHEMA

The cut: no loud progress UI (yet)

No mega progress bar. No spammy toasts. No constant “Syncing…” animations.

That stuff can come later—carefully—because the moment we make it noisy, we also make it suspicious.

For now: the Codex is designed to be quiet by default
It works → it stops when done → it seals itself if IGDB isn’t available
The user shouldn’t have to babysit the Sanctum.

Ref: TASK-LIST

Rough edges / dragons 🐉

• ⚠️ Perception problem: If sync happens fast, players might never notice it exists. That’s good (less friction) and risky (less trust). A subtle Codex badge state (Quiet / Scribing / Sealed) is on the radar.
  Ref: TASK-LIST

• ⚠️ Scanner reality: A beautiful board is only as good as the entries it’s built on. False positives and junk detections still need hardening so the board doesn’t become a landfill.
  Ref: TASK-LIST

• ⚠️ Board polish debt: Drag/drop and ordering are spec-aligned, but the feel (empty states, error handling, DnD satisfaction, column highlighting) needs a dedicated pass.
  Ref: CHANGELOG · BACKLOG-BOARD-SPEC

Next on the path 🔜

• 🔜 Chronicle polish pass: better loading states, clearer failures, and fallback imagery so “missing art” never looks like a bug.
  Ref: TASK-LIST

• 🔜 Scanner cleanup sprint: reduce junk entries and tighten heuristics while staying strictly local + TOS-compliant.
  Ref: TASK-LIST · ARCH-NOTES

• 🔜 Optional Codex presence indicator: low-noise UI badge so users can trust enrichment is happening (or understand why it isn’t).
  Ref: TASK-LIST

• 🔜 Board “feel” polish: empty states, DnD affordances, and error reverts that match “badass mode” without turning neon.
  Ref: BACKLOG-BOARD-SPEC

• 🔜 Doc sync sweep: keep ARCH-NOTES.md, DB-SCHEMA.md, and CHANGELOG.md locked to reality as the Sanctum evolves.
  Ref: ARCH-NOTES · DB-SCHEMA · CHANGELOG

Filed into the Chronicle.