box-box/documentations/refactor/28-orchestrator-handoff.md

# Orchestrator Handoff

You are taking over as the primary orchestration/coding agent for the box-box refactor.

Repo:

```text
/Users/aman/HomeBase/Programming/Projects/box-box
```

Branch:

```text
box-refactor
```

## Role

You are the engineering manager/orchestrator. Inspect before acting, keep changes scoped, review agent work before committing, prune stale docs after phases, and commit cleanly after each accepted phase. The user prefers Cursor for backend/test/hardening work and Claude for major frontend/product/design work, but you may implement directly when appropriate.

## Operating Rules

- Do not rush into implementation if the user wants to discuss.
- If implementing, keep phases small and commit-ready.
- Commit after each completed/reviewed phase.
- Never revert user/other-agent changes without explicit permission.
- Use `rg` for searches.
- Use `apply_patch` for manual edits.
- For frontend work, run browser or Playwright verification where practical.
- For review requests, lead with findings and file/line references.
- `frontend/dist` is ignored and should not be committed.
- Preserve TUI live mode and official F1 SignalR live behavior carefully.

## Project Direction

box-box started as a Go Bubble Tea F1 TUI backed mostly by OpenF1. The refactor direction is now:

- Web UI is the primary product surface.
- React + TypeScript frontend is the production Web UI stack.
- Go backend remains the API/server.
- Historical/completed-session data should be local-first from SQLite.
- OpenF1 ingestion is explicit via CLI, not fetched live on every page load.
- Official F1 SignalR remains the live source.
- Desired product feel: clean, dense, technical F1 operations room. Avoid card-heavy AI-slop.

## Important Commands

```bash
git status --short
git log --oneline -10

go test ./...
npm --prefix frontend test -- --run
npm --prefix frontend run build
npm run test:e2e
npm run test:e2e:prod
npm run test:visual
npm run test:visual:prod
```

Known test note: do not run Playwright suites that share the same seeded SQLite DB in parallel. Run prod E2E and prod visual sequentially, or they may hit `database is locked`.

## Recent Commits

- `a0f135a Update operator documentation`
- `79b0b9f Rework command center for race weekends`
- `84a8827 Add paddock briefing RSS backend spike`
- `ee88a07 Add paddock briefing feed ingestion`
- `Rework Race Hub as weekend workspace` (latest Phase 19 commit)

## Current State

Phase 19 and Phase 20 have been reviewed and committed. Start new work from a
clean tree unless `git status --short` shows user changes made after this
handoff.

## Completed Phase 19: Weekend Workspace / Race Hub Flow V1

Claude implemented, and Codex reviewed/committed, a Race Hub redesign that turns
`/race-hub` into a Weekend Workspace.

- New:
  - `frontend/src/components/OverviewView.tsx`
  - `frontend/src/components/WeekendSwitcher.tsx`
  - `frontend/src/test/RaceHubPage.test.tsx`
  - `documentations/refactor/26-phase-19-weekend-workspace.md`
- Modified:
  - `frontend/src/pages/RaceHubPage.tsx`
  - `frontend/src/components/TabBar.tsx`
  - `frontend/src/components/DatasetStatusView.tsx`
  - `frontend/src/styles/app.css`
  - tests for TabBar, DatasetStatusView, race-hub, command-center, data-library, production-smoke
  - `tests/visual/helpers.ts`
  - race-hub visual snapshots
  - root `README.md`
  - `documentations/refactor/README.md`

UX changes:

- Race Hub is now a Weekend Workspace.
- Compact GP identity band with country decal/accent strip.
- Horizontal session rail replaces “big table then analysis below.”
- Active session context stays visible above tabs.
- Tabs regrouped into Overview, Race Story, Strategy, Lap Data, Conditions, Race Control, Data Status.
- New Overview tab with winner/pole/fastest/podium cards, condition chips, latest race control, and local coverage meter.
- Inline Switch Weekend panel replaces legacy LocalDataNavigator on Race Hub.
- Data Status links to `/admin`; no CLI/admin text on fan surface.
- Mobile/iPad improved with wrapping identity band, horizontal session rail, single-column stats.
- `/race-hub?session_key=9472` still works and loads Bahrain GP 2024 seeded session.
- Bare `/race-hub` now resolves to a focus weekend/session via `pickFocusMeeting` and navigation replace.

Verification run by Codex before commit:

- `npm --prefix frontend test -- --run`
- `npm --prefix frontend run build`
- `npm run test:e2e`
- `npm run test:e2e:prod`
- `npm run test:visual`
- `npm run test:visual:prod`

Small review fix included: `frontend/src/test/setup.ts` stubs
`window.scrollTo` so TanStack Router scroll restoration does not spam jsdom test
stderr.

## Completed Phase 20: Paddock Briefing Ingestion CLI

A backend subagent implemented, and Codex reviewed/committed, Phase 20 after the
RSS backend spike.

Phase 20 changes:

- Modified:
  - `cmd/main.go`
- New:
  - `internal/news/refresh.go`
  - `internal/news/refresh_test.go`
  - `documentations/refactor/29-phase-20-paddock-briefing-ingestion.md`

Behavior:

- Adds `--ingest-news` as a CLI mode.
- Keeps it mutually exclusive with `--ingest-year`, `--ingest-meeting`, and
  `--ingest-session`.
- Reuses `--db` for the domain SQLite path.
- Reuses `--dry-run` to fetch and report feed counts without opening or writing
  the domain database.
- Uses `internal/news.Refresh`, which fetches `DefaultSources`, upserts
  `news_sources`, upserts URL-deduped `news_items`, records `fetched_at` and
  `expires_at`, and continues through individual feed failures before returning
  a summary error.
- Web requests still do not fetch feeds; `/api/v1/news` remains read-only
  against SQLite.

Commands added:

```bash
go run ./cmd/main.go --ingest-news
go run ./cmd/main.go --dry-run --ingest-news
go run ./cmd/main.go --ingest-news --db /tmp/boxbox.db
```

Verification run by Codex before commit:

```bash
go test ./cmd/... ./internal/news ./internal/store
git diff --check
```

## Immediate Task

Start with a quick sync:

```bash
git status --short
git diff --stat
```

Then continue with the next requested phase. The most natural next phase is
Phase 21: Paddock Briefing UI, unless the user wants to deepen Race Story first.

## RSS / Paddock Briefing Context

Cursor completed and Codex committed a backend spike as `84a8827 Add paddock briefing RSS backend spike`.

Implemented:

- `internal/news`: RSS/Atom parser and fetch helper.
- SQLite tables:
  - `news_sources`
  - `news_items`
- Store/query methods for cached news.
- Read-only API:
  - `GET /api/v1/news?limit=25&source=racefans-f1`
- No request-time network fetching.
- Unit tests use local XML fixtures.

Recommended feed sources:

- FIA official RSS
- BBC Sport F1
- Autosport F1
- RaceFans F1
- Guardian Formula One

Optional:

- Motorsport.com
- RACER
- Formula 1 YouTube Atom

Avoid:

- Formula1.com scraping/hidden endpoints
- X/Twitter scraping
- Reddit as primary source
- RSS.app/Feedspot as primary source

## Likely Next Phases After Phase 19 And 20

1. Phase 21: Paddock Briefing UI
   - Claude/frontend.
   - Add fan-facing briefing module, likely on Command Center first.
   - Query `/api/v1/news`.
   - Show source, title, age, category, short feed-provided snippet, external link.
   - Keep publisher attribution visible.
   - Avoid full article storage or scraping.

2. Phase 22: Race Story Deepening
   - Claude/frontend or mixed.
   - Collapse legacy classification/grid/position components into a more fluid Race Story canvas.
   - Improve mobile scanning and session narrative.

3. Phase 23: Full Season Backfill / ingest hardening
   - Cursor/backend.
   - Safer season workflows, resumability, rate-limit controls, coverage reporting.