geniusrun/docs/superpowers/plans/2026-07-26-improve-first-connection.md

Improve First Connection Page Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make connecting a Garmin account a mandatory, persisted gate during onboarding (and on every subsequent login until it succeeds), instead of an optional step left to the Profile page.

Architecture: Add a nullable garmin_connected_at timestamp to profile, set once on the first successful Garmin authentication (handleGarminAuthLogin/handleGarminAuthMFA). Expose it via GET /api/session/me. LoginGate.tsx becomes a three-way fork (!has_profile → CreateProfile, has_profile && !garmin_connected → new ConnectGarmin, else → App), so a user who abandons the connect step re-enters at ConnectGarmin on their next login rather than skipping straight into the app.

Tech Stack: Go (database/sql via modernc.org/sqlite, chi router), React + TypeScript (Vite), no frontend test framework.

Global Constraints

• internal/store/schema.sql is edited directly, never migrated (pre-production app, see CLAUDE.md).
• Every store/API method touching per-user data takes an explicit userID and filters by it.
• Cross-user isolation is tested adversarially (two real users, real IDs), not just checked for non-collision.
• After the schema.sql change, regenerate docs/DATABASE.md via go run ./cmd/dumpschema (from backend/).
• gofmt -l . must report nothing; go vet ./... and go build ./... must pass.
• No frontend test suite exists — frontend changes are verified via npm run build, npm run lint, and a manual browser check.
• This local dev DB predates schema changes made this session (ON DELETE CASCADE) but was already fixed up in place. A brand-new nullable column (garmin_connected_at TEXT) needs no such fix-up: SQLite's idempotent-skip applySchema never re-applies schema.sql to an existing DB file, but adding a nullable column to profile's Go-side handling doesn't require the on-disk table to already have it selected correctly... actually it does — GetProfile's SELECT will fail against the live dev DB once it lists garmin_connected_at in profileColumns, since that column doesn't exist there yet. Task 1 includes a real ALTER TABLE against the live dev DB (safe, additive, no rebuild needed this time) to keep manual testing working.

---

Task 1: Persist garmin_connected_at in the store layer

Files:

• Modify: backend/internal/store/schema.sql (add column to the profile table)
• Modify: backend/internal/store/profile.go (Profile struct, profileColumns, GetProfile, new MarkGarminConnected)
• Modify: backend/internal/store/profile_test.go (new tests)
• Modify: backend/internal/store/isolation_test.go (new adversarial test)
• Modify: docs/DATABASE.md (regenerated)
• Modify (real DB, not version-controlled): backend/geniusrun.db — additive ALTER TABLE

Interfaces:

• Produces: Profile.GarminConnectedAt *string (nil until first successful Garmin auth); func (db *DB) MarkGarminConnected(ctx context.Context, userID int64) error.

• Step 1: Write the failing tests

Add to backend/internal/store/profile_test.go:

func TestMarkGarminConnected_SetsTimestampOnceOnFirstCall(t *testing.T) {
	db := openTestDB(t)
	ctx := context.Background()
	userID, err := db.ProvisionUser(ctx, "test-sub", "Test")
	if err != nil {
		t.Fatalf("ProvisionUser: %v", err)
	}

	before, err := db.GetProfile(ctx, userID)
	if err != nil {
		t.Fatalf("GetProfile: %v", err)
	}
	if before.GarminConnectedAt != nil {
		t.Fatalf("expected a fresh profile to have nil GarminConnectedAt, got %v", *before.GarminConnectedAt)
	}

	if err := db.MarkGarminConnected(ctx, userID); err != nil {
		t.Fatalf("MarkGarminConnected: %v", err)
	}
	afterFirst, err := db.GetProfile(ctx, userID)
	if err != nil {
		t.Fatalf("GetProfile after first mark: %v", err)
	}
	if afterFirst.GarminConnectedAt == nil {
		t.Fatal("expected GarminConnectedAt to be set after MarkGarminConnected")
	}
	firstValue := *afterFirst.GarminConnectedAt

	// A second call must not change the recorded first-connection time.
	if err := db.MarkGarminConnected(ctx, userID); err != nil {
		t.Fatalf("MarkGarminConnected (second call): %v", err)
	}
	afterSecond, err := db.GetProfile(ctx, userID)
	if err != nil {
		t.Fatalf("GetProfile after second mark: %v", err)
	}
	if afterSecond.GarminConnectedAt == nil || *afterSecond.GarminConnectedAt != firstValue {
		t.Fatalf("GarminConnectedAt changed on second call: first=%q second=%v", firstValue, afterSecond.GarminConnectedAt)
	}
}

Add to backend/internal/store/isolation_test.go:

// TestIsolation_MarkGarminConnectedNeverLeaksAcrossUsers confirms marking
// one user's Garmin connection never sets another user's flag.
func TestIsolation_MarkGarminConnectedNeverLeaksAcrossUsers(t *testing.T) {
	db := openTestDB(t)
	ctx := context.Background()

	userA, err := db.ProvisionUser(ctx, "sub-a", "A")
	if err != nil {
		t.Fatalf("ProvisionUser(a): %v", err)
	}
	userB, err := db.ProvisionUser(ctx, "sub-b", "B")
	if err != nil {
		t.Fatalf("ProvisionUser(b): %v", err)
	}

	if err := db.MarkGarminConnected(ctx, userA); err != nil {
		t.Fatalf("MarkGarminConnected(a): %v", err)
	}

	profileB, err := db.GetProfile(ctx, userB)
	if err != nil {
		t.Fatalf("GetProfile(b): %v", err)
	}
	if profileB.GarminConnectedAt != nil {
		t.Fatal("userA's MarkGarminConnected call leaked into userB's profile")
	}
}

• Step 2: Run tests to verify they fail

Run: cd backend && go test ./internal/store/... -run 'TestMarkGarminConnected|TestIsolation_MarkGarminConnected' -v Expected: FAIL — db.MarkGarminConnected undefined / Profile has no field GarminConnectedAt.

• Step 3: Add the column to schema.sql

In backend/internal/store/schema.sql, in the profile table (right after garmin_password), change:

    garmin_password     TEXT NOT NULL DEFAULT '',
    rolling_window_days INTEGER NOT NULL DEFAULT 90,

to:

    garmin_password     TEXT NOT NULL DEFAULT '',
    -- Set once, the first time this user successfully authenticates with
    -- Garmin (handleAuthLogin/handleAuthMFA). Null means never connected --
    -- the login gate uses this (not the in-memory auth status, which
    -- resets on restart) to decide whether a returning user must
    -- reconnect before entering the app.
    garmin_connected_at TEXT,
    rolling_window_days INTEGER NOT NULL DEFAULT 90,

• Step 4: Update Profile, profileColumns, and GetProfile in profile.go

Change the struct (add the field right after GarminPassword):

	Name              string
	GarminEmail       string
	GarminPassword    string
	// GarminConnectedAt is nil until this user's first successful Garmin
	// authentication (see store.MarkGarminConnected) -- the login gate uses
	// it, not UpdateProfile, so it's deliberately excluded from
	// UpdateProfile's SET clause below and can only ever move from nil to
	// set, never reset by a normal profile save.
	GarminConnectedAt *string
	RollingWindowDays int

Change profileColumns:

const profileColumns = `
	name, garmin_email, garmin_password, garmin_connected_at, rolling_window_days, backfill_horizon_days, max_heart_rate, resting_heart_rate,
	hr_zone1_min_pct, hr_zone1_max_pct, hr_zone2_min_pct, hr_zone2_max_pct,
	hr_zone3_min_pct, hr_zone3_max_pct, hr_zone4_min_pct, hr_zone4_max_pct,
	hr_zone5_min_pct, hr_zone5_max_pct,
	warmup_minutes, cooldown_minutes,
	min_representative_pace_sec_per_km, min_representative_time_seconds,
	pace_color, heart_rate_color, warmup_color, effort_color, recovery_color, cooldown_color,
	main_line_tint_pct, background_darken_pct, target_brighten_pct,
	created_at, updated_at
`

Change GetProfile's Scan call (add &p.GarminConnectedAt right after &p.GarminPassword):

	err := db.QueryRowContext(ctx, `SELECT `+profileColumns+` FROM profile WHERE user_id = ?`, userID).Scan(
		&p.Name, &p.GarminEmail, &p.GarminPassword, &p.GarminConnectedAt, &p.RollingWindowDays, &p.BackfillHorizonDays, &p.MaxHeartRate, &p.RestingHeartRate,
		&p.HRZone1MinPct, &p.HRZone1MaxPct, &p.HRZone2MinPct, &p.HRZone2MaxPct,
		&p.HRZone3MinPct, &p.HRZone3MaxPct, &p.HRZone4MinPct, &p.HRZone4MaxPct,
		&p.HRZone5MinPct, &p.HRZone5MaxPct,
		&p.WarmupMinutes, &p.CooldownMinutes,
		&p.MinRepresentativePaceSecPerKm, &p.MinRepresentativeTimeSeconds,
		&p.PaceColor, &p.HeartRateColor, &p.WarmupColor, &p.EffortColor, &p.RecoveryColor, &p.CooldownColor,
		&p.MainLineTintPct, &p.BackgroundDarkenPct, &p.TargetBrightenPct,
		&p.CreatedAt, &p.UpdatedAt,
	)

Do not touch UpdateProfile — garmin_connected_at must stay out of its SET/args list so a normal Profile-page save can never reset it.

• Step 5: Add MarkGarminConnected

Append to backend/internal/store/profile.go:

// MarkGarminConnected records the first time userID successfully
// authenticates with Garmin. A no-op if already set, so it always reflects
// the first connection, not the most recent one.
func (db *DB) MarkGarminConnected(ctx context.Context, userID int64) error {
	_, err := db.ExecContext(ctx, `UPDATE profile SET garmin_connected_at = datetime('now') WHERE user_id = ? AND garmin_connected_at IS NULL`, userID)
	if err != nil {
		return fmt.Errorf("mark garmin connected for user %d: %w", userID, err)
	}
	return nil
}

• Step 6: Run tests to verify they pass

Run: cd backend && go test ./internal/store/... -run 'TestMarkGarminConnected|TestIsolation_MarkGarminConnected' -v Expected: PASS.

• Step 7: Run the full store test suite

Run: cd backend && go test ./internal/store/... Expected: PASS.

• Step 8: Regenerate docs/DATABASE.md

Run: cd backend && go run ./cmd/dumpschema Expected: docs/DATABASE.md shows the new garmin_connected_at column in profile.

• Step 9: Additively update the live local dev DB

The real backend/geniusrun.db predates this column (schema.sql changes never retrofit an existing DB file — see applySchema's idempotent skip in db.go). Unlike the earlier ON DELETE CASCADE fix, this is purely additive (a new nullable column), so a plain ALTER TABLE is sufficient — no rebuild-and-copy dance needed:

sqlite3 backend/geniusrun.db "ALTER TABLE profile ADD COLUMN garmin_connected_at TEXT;"
sqlite3 backend/geniusrun.db "SELECT sql FROM sqlite_master WHERE type='table' AND name='profile';" | grep garmin_connected_at

Confirm the backend isn't running before touching the file (ps aux | grep geniusrund), same care as before.

• Step 10: Commit

git add backend/internal/store/schema.sql backend/internal/store/profile.go backend/internal/store/profile_test.go backend/internal/store/isolation_test.go docs/DATABASE.md
git commit -m "feat(store): persist garmin_connected_at, set once on first successful auth"

---

Task 2: Wire MarkGarminConnected into the auth handlers and expose it via session/me

Files:

• Modify: ../../../backend/internal/api/garmin.go (recordAuthResult, both call sites)
• Modify: backend/internal/api/session.go (sessionMeResponse, handleSessionMe)
• Modify: backend/internal/api/api_test.go (new tests)
• Modify: backend/internal/api/isolation_test.go (new adversarial test)

Interfaces:

• Consumes: store.DB.MarkGarminConnected(ctx, userID) error (Task 1); store.DB.GetProfile(ctx, userID) (store.Profile, error) (existing).

• Produces: sessionMeResponse.GarminConnected bool (JSON garmin_connected).

• Step 1: Write the failing tests

Append to backend/internal/api/api_test.go:

func TestSessionMe_ReportsGarminConnectedAfterSuccessfulAuth(t *testing.T) {
	s, _, _ := newTestServer(t)
	router := s.Router()

	rec := doJSON(t, router, http.MethodGet, "/api/session/me", nil)
	var before sessionMeResponse
	unmarshalBody(t, rec, &before)
	if before.GarminConnected {
		t.Fatal("expected a fresh account to report garmin_connected=false")
	}

	rec = doJSON(t, router, http.MethodPost, "/api/auth/login", nil) // mock.Client defaults to AuthSuccess
	if rec.Code != http.StatusOK {
		t.Fatalf("auth/login status = %d, body = %s", rec.Code, rec.Body.String())
	}

	rec = doJSON(t, router, http.MethodGet, "/api/session/me", nil)
	var after sessionMeResponse
	unmarshalBody(t, rec, &after)
	if !after.GarminConnected {
		t.Fatal("expected garmin_connected=true after a successful auth")
	}
}

func TestSessionMe_GarminConnectedStaysFalseOnMFARequiredOrFailed(t *testing.T) {
	s, _, userID := newTestServer(t)
	client, err := s.garminFor(context.Background(), userID)
	if err != nil {
		t.Fatalf("garminFor: %v", err)
	}
	mockClient, ok := client.(*mock.Client)
	if !ok {
		t.Fatalf("expected *mock.Client, got %T", client)
	}
	mockClient.AuthResults = []garmin.AuthResult{{Status: garmin.AuthMFARequired, Message: "MFA required"}}

	router := s.Router()
	rec := doJSON(t, router, http.MethodPost, "/api/auth/login", nil)
	if rec.Code != http.StatusOK {
		t.Fatalf("auth/login status = %d, body = %s", rec.Code, rec.Body.String())
	}

	rec = doJSON(t, router, http.MethodGet, "/api/session/me", nil)
	var me sessionMeResponse
	unmarshalBody(t, rec, &me)
	if me.GarminConnected {
		t.Fatal("expected garmin_connected=false after mfa_required")
	}
}

Append to backend/internal/api/isolation_test.go:

// TestIsolation_GarminConnectedNeverLeaksAcrossUsers confirms one user's
// successful Garmin auth never flips garmin_connected for another user.
func TestIsolation_GarminConnectedNeverLeaksAcrossUsers(t *testing.T) {
	s, db, _ := newTestServer(t) // provisions "test-user" (userA)
	if _, err := db.ProvisionUser(newCtx(), "user-b", "B"); err != nil {
		t.Fatalf("ProvisionUser(b): %v", err)
	}

	router := s.Router()
	rec := doJSON(t, router, http.MethodPost, "/api/auth/login", nil) // as userA
	if rec.Code != http.StatusOK {
		t.Fatalf("auth/login status = %d, body = %s", rec.Code, rec.Body.String())
	}

	rec = doJSONAs(t, router, "user-b", http.MethodGet, "/api/session/me", nil)
	var meB sessionMeResponse
	unmarshalBody(t, rec, &meB)
	if meB.GarminConnected {
		t.Fatal("userA's successful Garmin auth leaked into userB's garmin_connected flag")
	}
}

• Step 2: Run tests to verify they fail

Run: cd backend && go test ./internal/api/... -run 'TestSessionMe_ReportsGarminConnected|TestSessionMe_GarminConnectedStaysFalse|TestIsolation_GarminConnected' -v Expected: FAIL — sessionMeResponse has no field GarminConnected.

• Step 3: Update recordAuthResult in garmin.go

Change the imports:

import (
	"context"
	"encoding/json"
	"log"
	"net/http"

	"geniusrun/backend/internal/garmin"
)

Change recordAuthResult and both call sites:

// recordAuthResult updates the in-memory auth status/message for userID,
// and -- on a successful authentication -- persists that this account has
// connected to Garmin at least once (store.MarkGarminConnected), which is
// what the login gate actually checks (session cookie's in-memory auth
// status resets on every backend restart; this doesn't).
func (s *Server) recordAuthResult(ctx context.Context, userID int64, res garmin.AuthResult) {
	s.mu.Lock()
	s.userAuthStatus[userID] = res.Status
	s.userAuthMessage[userID] = res.Message
	s.mu.Unlock()

	if res.Status == garmin.AuthSuccess {
		if err := s.DB.MarkGarminConnected(ctx, userID); err != nil {
			log.Printf("api: mark garmin connected for user %d: %v", userID, err)
		}
	}
}

In handleGarminAuthLogin, change s.recordAuthResult(userID, res) to s.recordAuthResult(r.Context(), userID, res). In handleGarminAuthMFA, change s.recordAuthResult(userID, res) to s.recordAuthResult(r.Context(), userID, res).

• Step 4: Update sessionMeResponse and handleSessionMe in session.go

Change:

type sessionMeResponse struct {
	Name        string `json:"name"`
	Email       string `json:"email"`
	HasProfile  bool   `json:"has_profile"`
	DisplayName string `json:"display_name,omitempty"`
}

to:

type sessionMeResponse struct {
	Name            string `json:"name"`
	Email           string `json:"email"`
	HasProfile      bool   `json:"has_profile"`
	DisplayName     string `json:"display_name,omitempty"`
	GarminConnected bool   `json:"garmin_connected"`
}

Change handleSessionMe:

func (s *Server) handleSessionMe(w http.ResponseWriter, r *http.Request) {
	claims, ok := auth.ClaimsFromContext(r.Context())
	if !ok {
		// Unreachable in practice -- RequireSession already 401s before this
		// handler runs -- but fail closed rather than panic if that ever changes.
		writeError(w, http.StatusUnauthorized, "not authenticated")
		return
	}
	resp := sessionMeResponse{Name: claims.Name, Email: claims.Email}
	if u, found := userFromContext(r.Context()); found {
		resp.HasProfile = true
		resp.DisplayName = u.DisplayName
		profile, err := s.DB.GetProfile(r.Context(), u.ID)
		if err != nil {
			writeError(w, http.StatusInternalServerError, err.Error())
			return
		}
		resp.GarminConnected = profile.GarminConnectedAt != nil
	}
	writeJSON(w, http.StatusOK, resp)
}

• Step 5: Run tests to verify they pass

Run: cd backend && go test ./internal/api/... -run 'TestSessionMe_ReportsGarminConnected|TestSessionMe_GarminConnectedStaysFalse|TestIsolation_GarminConnected' -v Expected: PASS.

• Step 6: Run the full backend test suite

Run: cd backend && go build ./... && go vet ./... && gofmt -l . && go test ./... Expected: gofmt -l . empty; everything else passes.

• Step 7: Commit

git add backend/internal/api/garmin.go backend/internal/api/session.go backend/internal/api/api_test.go backend/internal/api/isolation_test.go
git commit -m "feat(api): persist and expose garmin_connected on successful auth"

---

Task 3: Frontend — three-way login gate and the new ConnectGarmin screen

Files:

• Modify: frontend/src/types/api.ts (SessionInfo)
• Create: frontend/src/ConnectGarmin.tsx
• Modify: frontend/src/CreateProfile.tsx (add Log out link)
• Modify: frontend/src/CreateProfile.css (one new class, shared with ConnectGarmin.tsx)
• Modify: frontend/src/LoginGate.tsx (three-way fork)

Interfaces:

• Consumes: api.getProfile(), api.updateProfile(profile), api.login(), api.submitMFA(code) (all existing, unchanged signatures); SessionInfo.garmin_connected: boolean (new).

• Produces: ConnectGarmin({ onConnected: () => void }), a React component.

• Step 1: Add garmin_connected to SessionInfo

In frontend/src/types/api.ts, change:

export interface SessionInfo {
  name: string;
  email: string;
  has_profile: boolean;
  display_name?: string;
}

to:

export interface SessionInfo {
  name: string;
  email: string;
  has_profile: boolean;
  display_name?: string;
  garmin_connected: boolean;
}

• Step 2: Add a shared status-message class to CreateProfile.css

Append to frontend/src/CreateProfile.css:

.create-profile-message {
  margin: 0;
  color: #9ca3af;
}

.create-profile-mfa {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
  width: 100%;
  max-width: 320px;
}

• Step 3: Create frontend/src/ConnectGarmin.tsx

import { useState } from "react";
import { api, BASE_URL } from "./api/client";
import "./CreateProfile.css";
import type { AuthResponse } from "./types/api";

// Shown after CreateProfile (or on any later login, until it succeeds --
// see LoginGate) since connecting Garmin is mandatory: the account exists
// but this is the last gate before the main app. Deliberately not a reuse
// of GarminConnection.tsx (the Profile page's version), which also renders
// Sync now/Disconnect/Reset all -- none of which make sense here.
export function ConnectGarmin({ onConnected }: { onConnected: () => void }) {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [code, setCode] = useState("");
  const [auth, setAuth] = useState<AuthResponse | null>(null);
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function connect(e: React.FormEvent) {
    e.preventDefault();
    if (!email.trim() || !password) {
      setError("Please enter your Garmin email and password.");
      return;
    }
    setBusy(true);
    setError(null);
    try {
      const profile = await api.getProfile();
      await api.updateProfile({ ...profile, GarminEmail: email.trim(), GarminPassword: password });
      setAuth(await api.login());
    } catch (err) {
      setError(err instanceof Error ? err.message : "Something went wrong, please try again.");
    } finally {
      setBusy(false);
    }
  }

  async function submitMFA() {
    if (!code.trim()) return;
    setBusy(true);
    setError(null);
    try {
      setAuth(await api.submitMFA(code.trim()));
      setCode("");
    } catch (err) {
      setError(err instanceof Error ? err.message : "Something went wrong, please try again.");
    } finally {
      setBusy(false);
    }
  }

  const status = auth?.status;

  return (
    <div className="create-profile">
      <h1>🧞‍♀️ Connect your Garmin account</h1>
      <p>geniusrun needs your Garmin credentials to sync your activities.</p>

      {status !== "authenticated" && status !== "mfa_required" && (
        <form onSubmit={connect}>
          <input
            type="text"
            placeholder="Garmin email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            disabled={busy}
            autoFocus
          />
          <input
            type="password"
            placeholder="Garmin password"
            value={password}
            onChange={(e) => setPassword(e.target.value)}
            disabled={busy}
          />
          <button type="submit" disabled={busy}>
            {busy ? "Connecting…" : "Connect"}
          </button>
        </form>
      )}

      {status === "mfa_required" && (
        <div className="create-profile-mfa">
          <input
            placeholder="MFA code"
            value={code}
            onChange={(e) => setCode(e.target.value)}
            onKeyDown={(e) => e.key === "Enter" && submitMFA()}
            disabled={busy}
            autoFocus
          />
          <button type="button" disabled={busy} onClick={submitMFA}>
            Submit code
          </button>
        </div>
      )}

      {status === "authenticated" && (
        <>
          <p className="create-profile-message">Connected to Garmin.</p>
          <button type="button" onClick={onConnected}>
            Continue to geniusrun
          </button>
        </>
      )}

      {auth?.message && status !== "authenticated" && <p className="create-profile-message">{auth.message}</p>}
      {error && <p className="create-profile-error">{error}</p>}

      <form method="post" action={`${BASE_URL}/api/session/logout`}>
        <button type="submit" className="logout-link">
          Log out
        </button>
      </form>
    </div>
  );
}

• Step 4: Add a Log out link to CreateProfile.tsx

Change:

        {error && <p className="create-profile-error">{error}</p>}
        <button type="submit" disabled={submitting}>
          {submitting ? "Creating…" : "Continue"}
        </button>
      </form>
    </div>
  );
}

to:

        {error && <p className="create-profile-error">{error}</p>}
        <button type="submit" disabled={submitting}>
          {submitting ? "Creating…" : "Continue"}
        </button>
      </form>
      <form method="post" action={`${BASE_URL}/api/session/logout`}>
        <button type="submit" className="logout-link">
          Log out
        </button>
      </form>
    </div>
  );
}

And change the import line at the top of CreateProfile.tsx:

import { api } from "./api/client";

to:

import { api, BASE_URL } from "./api/client";

• Step 5: Wire the three-way fork into LoginGate.tsx

Change the imports:

import { useEffect, useState } from "react";
import { api, BASE_URL } from "./api/client";
import "./LoginGate.css";
import App from "./App";
import { CreateProfile } from "./CreateProfile";
import type { SessionInfo } from "./types/api";

to:

import { useEffect, useState } from "react";
import { api, BASE_URL } from "./api/client";
import "./LoginGate.css";
import App from "./App";
import { ConnectGarmin } from "./ConnectGarmin";
import { CreateProfile } from "./CreateProfile";
import type { SessionInfo } from "./types/api";

Change the final part of the component body:

  if (!session!.has_profile) {
    return (
      <CreateProfile
        onCreated={(displayName) => setSession((s) => (s ? { ...s, has_profile: true, display_name: displayName } : s))}
      />
    );
  }

  return <App session={session!} />;
}

to:

  if (!session!.has_profile) {
    return (
      <CreateProfile
        onCreated={(displayName) => setSession((s) => (s ? { ...s, has_profile: true, display_name: displayName } : s))}
      />
    );
  }

  // Connecting Garmin is mandatory, re-checked on every login (not just
  // right after signup) -- see docs/superpowers/specs/2026-07-26-improve-first-connection-design.md
  // for why this can't be a purely in-session check.
  if (!session!.garmin_connected) {
    return <ConnectGarmin onConnected={() => setSession((s) => (s ? { ...s, garmin_connected: true } : s))} />;
  }

  return <App session={session!} />;
}

Also update the doc comment above the LoginGate function (currently describes only a two-way fork) -- change:

// Wraps App: on mount, asks the backend whether this browser already has a
// valid session (GET /api/session/me). geniusrun has no anonymous view, so
// this is the first fork -- "show the login screen" vs "show the app." A
// second fork, once authenticated, is whether the session's account has a
// provisioned profile yet (session.has_profile) -- a brand-new OIDC login
// sees CreateProfile instead of App until it submits one.

to:

// Wraps App: on mount, asks the backend whether this browser already has a
// valid session (GET /api/session/me). geniusrun has no anonymous view, so
// this is the first fork -- "show the login screen" vs "show the app." A
// second fork, once authenticated, is whether the session's account has a
// provisioned profile yet (session.has_profile) -- a brand-new OIDC login
// sees CreateProfile instead of App until it submits one. A third fork,
// once provisioned, is whether Garmin has ever been successfully connected
// (session.garmin_connected) -- mandatory, and re-checked on every login,
// not just immediately after signup.

• Step 6: Build and lint

Run: cd frontend && npm run build && npm run lint Expected: build succeeds; lint reports no new warnings beyond the 3 pre-existing PaceField.tsx ones.

• Step 7: Manual browser verification

With the backend (cd backend && ./start.sh) and frontend (cd frontend && ./start.sh) running:

1. Delete your profile (or use a fresh OIDC account) so you land on CreateProfile.
2. Submit a display name — confirm you're immediately routed to ConnectGarmin, not the main app.
3. Try an obviously wrong Garmin password — confirm the error shows and the form stays editable.
4. Enter correct credentials (resolve MFA if prompted) — confirm "Connected to Garmin." appears with a "Continue to geniusrun" button, and clicking it lands in the main app.
5. Log out, log back in with the same account — confirm you land straight in the app (not back through ConnectGarmin), proving garmin_connected_at persisted.
6. On the ConnectGarmin screen specifically, confirm the "Log out" link works.

• Step 8: Commit

git add frontend/src/types/api.ts frontend/src/ConnectGarmin.tsx frontend/src/CreateProfile.tsx frontend/src/CreateProfile.css frontend/src/LoginGate.tsx
git commit -m "feat(onboarding): add mandatory ConnectGarmin gate to first login"

---

Task 4: Final verification

Files: none (verification + cleanup only)

• Step 1: Full backend check

Run: cd backend && gofmt -l . && go vet ./... && go build ./... && go test ./... Expected: gofmt -l . empty; everything else passes.

• Step 2: Full frontend check

Run: cd frontend && npm run build && npm run lint Expected: both succeed, no new lint warnings.

• Step 3: Confirm docs/DATABASE.md is current

Run: cd backend && go run ./cmd/dumpschema && git status --short docs/DATABASE.md Expected: no output from git status (already committed in Task 1, unchanged since).

• Step 4: Update docs/IDEAS.md

Remove the now-implemented line from the Backlog section:

- improve first connection page: in CreateProfile.tsx, in addition to the display name, we should directly ask garmin login/password and manage MFA from there, so the synchronization experience in profile page will be easier later on

• Step 5: Commit

git add docs/IDEAS.md
git commit -m "docs: remove improve-first-connection-page from IDEAS backlog (implemented)"