Skip to main content

Handoff — 2026-07-09

Frozen snapshot — do not update. Kept for how a decision was reached, not for what is true now. Current state lives in Architecture → Current State.

Full takeover brief for the next agent. Read this top-to-bottom before touching anything. It captures exact repo state, the one thing blocking production, every decision made this session and why, what still needs the human (Akshay), and how this workspace actually works.

0. TL;DR — the one thing that matters​

A full backlog-clearing wave (6 parallel workstreams) is built, verified, committed, and pushed to git main on 4 repos. But every Firebase deploy is blocked because the Firebase CLI credentials on this machine are expired:

Error: Authentication Error: Your credentials are no longer valid. Please run firebase login --reauth

There is no FIREBASE_TOKEN, no GOOGLE_APPLICATION_CREDENTIALS, and no service-account JSON available. Only Akshay can reauth (firebase login --reauth) — an agent must not attempt interactive login or handle credentials. Until that happens, production still runs the previous code even though git is current.

Do not re-implement anything below thinking it's undone. It's done in git; it's just not deployed.

1. Repo state (as of handoff)​

Product root: /Users/akshaysarode/Desktop/Workspace/RunningProjects/acesense/AcesenseProd/ Firebase project: acesense-prod. All repos on branch main, remote via SSH alias git@github-acesense:Acesense/<repo>.git. Per-repo user.email = akshay.sarode18@gmail.com.

RepoHEADPushed?Deployed to prod?Notes
acesense-frontend649c2e2yesNO — needs hosting:appFlutter web/app. Has unrelated dirty WIP (see §5).
acesense-auth-function732d658yesNO — needs functionsCloud Functions (TS).
acesense-admin20d63dfyesNO — needs hostingVite/React admin console.
acesense-landing6bcf8e6yesNO — needs hosting:landingVite/React marketing site.
acesense-gpu-backendd71b7b5yesYES — auto-deploys on pushRunPod; nothing pending this wave.
acesense-docs3fec7d5yesn/aDocs. Unchanged this wave.
acesense-annotate7515067yesn/aLabelling tool. Unchanged.
acesense-api-hosting6ebd29fyesn/aUnchanged.
acesense-launchpad2c36915yesn/aInvestor bundle server. Unchanged.
acesense-brand91ad284—n/aUntracked play-store/ assets present (not mine).

plan/ at root is not a git repo (scratch).

2. THE DEPLOY SEQUENCE (do after Akshay reauths)​

Order matters: functions must exist before the UIs that call them. From each repo dir:

firebase login --reauth        # Akshay only, once

# 1. Backend first (new callables + AI-consent gate + bootstrapAdminClaims)
cd acesense-auth-function && firebase deploy --only functions
#   codebase is named "functions"; to deploy a single fn use the doubled name:
#   firebase deploy --only "functions:functions:generateSessionInsights"

# 2. Frontend app  (ships consent self-heal so users aren't blocked by the gate)
cd ../acesense-frontend && flutter build web --release && firebase deploy --only hosting:app
#   target app -> site acesense-prod-app  (acesense-prod-app.web.app)

# 3. Admin console (UI now calls the callables from step 1)
cd ../acesense-admin && pnpm build && firebase deploy      # its own firebase.json

# 4. Landing
cd ../acesense-landing && pnpm build && firebase deploy --only hosting:landing
#   target landing -> site acesense-prod  (acesense-prod.web.app)

Deploy-verify pattern used in this project (hosting): after deploy, shasum the deployed main.dart.js (frontend) or a hashed asset and compare to the local build; retry with a Cache-Control: no-cache fetch if the edge hasn't propagated (transient MISMATCH is normal for a minute).

GPU backend: no Firebase — it redeploys automatically on git push. Already pushed.

3. What shipped this wave (per repo)​

Six independent workstreams. All anti-fabrication-clean (real data or gate/hide; never fake numbers/identity/scores — this is a hard product rule; the mock path is kUseMockData in lib/config/build_flags.dart).

acesense-frontend (649c2e2)​

  • Real progression pipeline. New lib/services/progress_service.dart (+ lib/state/progress_provider.dart). Transparent skill score, per session: consistency*0.50 + pace*0.30 + rally*0.20, each term clamped 0–1 (pace = avg_speed_kmh/80, rally = avg_rally_length/8); weights renormalize when a metric is absent; overall = rounded mean of per-session scores; null at 0 sessions. Tiers: Rookie <40, Club 40–64, Competitor 65–84, Elite 85+. Also streakDays, weeklyDelta (null unless two consecutive weeks each have a session), PBs. Snapshot computed once in the provider, shared by 6 surfaces (home, sessions, roadmap, badges, profile, wrapped). Removed fabricated percentile/per-stroke sub-scores/freeze-count/peer-rank.
  • Coach mode -> real backend. lib/services/coach_service.dart rewritten to real callables (listCoachLinks, createCoachLink, respondToCoachLink, addCoachNote); coach_mock.dart deleted. Features with no backend read path (student's full analysis, per-student skill data, drill assignment) are honestly disabled/hidden, not faked.
  • Help/FAQ. New lib/features/help/help_screen.dart + /help route + Settings entry. Body copy is English literals (documented in-file) to avoid a ~40-string x 6-locale balloon.
  • Durable AI consent + migration. ai_consent_service.dart now writes a versioned Firestore record users/{uid}.aiConsent = {version:'v1', acceptedAt:&lt;serverTimestamp&gt;} (via FirestoreService.recordAiConsent) before caching locally. app_flows.dart _ensureAiConsent self-heals existing users: if the local flag is set but no server record exists, it writes the record through (best-effort) on next upload — so the new backend gate (below) doesn't lock out users who consented before this shipped.
  • Tests: 198 pass; flutter analyze clean; flutter build web --release OK.

acesense-auth-function (732d658)​

  • Server-enforced AI consent. video/index.ts: hasAiConsent(userData) predicate + gate in requestUploadPath — rejects with failed-precondition AI_CONSENT_REQUIRED unless the durable record exists. A device-only flag can no longer bypass analysis. Admins are not exempt (privacy, not paywall).
  • 9 audited admin callables in admin/index.ts, each requireAdmin-gated + writes an admin_audit row: adminSetJobStatus, adminDeleteJob (Storage-cleaning), adminRevokeApiKey, adminModerateJob (takedown removes media + flags job), adminImpersonate (mints tagged custom token; needs SA role roles/iam.serviceAccountTokenCreator in prod; bounded by Firebase's fixed 1h token lifetime), adminCreateUser, adminUpdateUser, adminDeleteUser, adminPurgeJobs (batched <=500 + more flag). Exported from repo-root index.ts.
  • bootstrapAdminClaims (pre-existing) grants admin:true to the server email allowlist; the admin UI now relies on it (see §4).
  • Tests: 309 pass (19 files); tsc clean.

acesense-admin (20d63df)​

  • All UI mutations rerouted from raw Firestore/Storage writes to the audited callables above (Jobs, Users, AdminApiKeys, Settings danger-zone, AuditLog moderation). Dashboard shows "Recent Jobs (<=500)" + a live health probe instead of a hardcoded "Operational".
  • Auth gate hardened (see §4): removed the in-bundle email allowlist; gate on the admin custom claim only; self-heal via bootstrapAdminClaims on sign-in. Kept firebase.json COOP same-origin-allow-popups (needed for Google popup sign-in).
  • Tests: 70 pass; build + lint clean.

acesense-landing (6bcf8e6)​

  • Analytics is now true opt-in. PostHog and Firebase Analytics don't initialize until the user accepts in the cookie banner; they enable live on the cookieConsentUpdated event. PostHog added to the privacy sub-processor list.
  • Legal/honesty reconcile. Min age 13->16 (18 in India); deduped Section 7; dropped founder "professional-grade"/"high accuracy" overclaims; removed an internal SEO note; 17->33-point MediaPipe skeleton; plausible NTRP-3.5 serve speeds; refund copy aligned to App Store/Play policy. Reverted the unverified acesense-annotate GitHub link to plain text.
  • Tests: 105 pass; build clean (93 prerendered routes).

4. Key decisions made this session (and why)​

  1. Admin UI gate = custom claim only (not a client email list). A pre-existing working-tree change had hardcoded 4 admin emails (incl. a personal gmail) into the browser bundle and gated the UI on them. That leaks admin identities publicly and violates the "nothing hardcoded" rule. Server requireAdmin is authoritative regardless, so the client list added no security — only risk. Chosen (by Akshay): gate on the admin claim only, and self-heal a genuine admin whose claim isn't set yet by calling bootstrapAdminClaims on sign-in (it's requireAdmin-gated on the server via the verified-email allowlist, so real admins get the claim granted + token force- refreshed; everyone else gets an ignored permission-denied). Caveat for first deploy: Akshay's first sign-in after deploy triggers the grant, then the code force-refreshes the token — one clean sign-in and the admin UI appears.
  2. AI-consent migration = self-heal, not a backfill script. The backend gate is presence-based. Existing users have only the legacy local flag. Rather than run a one-off Firestore backfill (needs prod admin creds we don't have), the frontend writes the durable record through on next upload when the local flag is set. Genuine prior consent, just persisted. No user gets blocked.
  3. Landing legal facts: flag, never invent. Three items can't be fabricated (see §6). Shipped the safe honesty fixes; left the legal items as explicit flags in the commit body.
  4. Deploy order backend->frontend->admin->landing. Callables must exist before the UIs call them; the frontend consent self-heal must be live alongside the backend consent gate.

5. Uncommitted WIP in the tree — DO NOT clobber, decide with Akshay​

  • acesense-frontend (dirty, intentionally left uncommitted):
    • android/app/build.gradle.kts — adds a real Android release signing config reading key.properties (falls back to debug signing if absent). Legit release-prep.
    • pubspec.yaml — version bump 1.0.4+1 -> 1.0.4+2. These are Akshay's Android release work, unrelated to this wave. Committing them touches signing (and key.properties must stay gitignored). Leave for Akshay to commit when doing the store build.
  • acesense-brand — untracked play-store/ directory (store listing assets). Not this session's.

6. Open items that need Akshay (blocking or fact-only)​

  1. Firebase reauth — blocks all 4 deploys (§0/§2).
  2. Landing legal facts (agent refused to invent):
    • Registered legal entity name + physical address (GDPR Art. 13/27). Three conflicting names in the repo (AceSense Technologies, AceSense Inc., "an EU company"); no postal address anywhere.
    • Delaware-Inc (terms.html governs under Delaware law) vs "EU company" (sweden.md) — pick the real incorporation, then terms + marketing get unified.
    • "No data leaves the EU" marketing (~20 pages) vs the privacy policy's US-servers + SCC clause (privacy.html). Founder decides true residency; then either the privacy clause is corrected or the marketing absolutes are softened. Sub-processors RunPod/Resend/Apple/PostHog are US-incorporated even if EU-hosted.
  3. Unverified GitHub link (pre-existing, already live): acesense-annotate link in acesense-landing/.../blog/how-accurate-is-acesense.md — confirm the repo is real/public or neutralize it (I already neutralized the two the agent added in accuracy.md/about.md).
  4. Platform keys for Wave 2 (below): reCAPTCHA v3 site key (App Check) and APNs/VAPID keys (FCM push).

7. Wave 2 — scoped, NOT started​

Akshay asked to "finish the open backlog except payment." Wave 1 (§3) did the fixable-without-keys items. Wave 2 items were scoped but not implemented — some need keys only Akshay can provide:

  • Notifications — in-app Firestore feed + a send-on-analysis-done function (fully buildable now); push needs APNs (iOS) + VAPID (web) keys.
  • Storage retention lifecycle — auto-expire old uploads/artifacts (buildable now).
  • App Check enforcement — code path already inert-wired in admin src/config/firebase.ts (VITE_APPCHECK_SITE_KEY); needs a reCAPTCHA v3 site key + enabling enforcement in console.
  • Full localization — several screens use English literals (e.g. Help screen, coach previews); arb + flutter gen-l10n across 6 locales.

Excluded by Akshay: real payment / IAP integration. Do not implement it.

8. How this workspace works (conventions + gotchas)​

Toolchain (non-negotiable, from user global CLAUDE.md): runtimes via mise; JS via pnpm (never npm/yarn); Python via uv (never raw pip); direnv for env. Clone with the SSH alias git@github-acesense:.... Never edit global git config. Never firebase login globally — per-project service accounts.

Build/test commands:

  • Frontend (Flutter): flutter analyze, flutter test, flutter build web --release. Golden tests: flutter test --update-goldens test/preview/analysis_visual_test.dart. l10n: flutter gen-l10n (generated dir is gitignored).
  • auth-function / admin / landing (TS/Vite): pnpm build, pnpm test (vitest), pnpm lint.
  • GPU backend: uv env; deploys on push.

Anti-fabrication contract (hard rule): never render fake numbers, identity, or scores. Use real data or gate behind kUseMockData / show an honest empty state. Injury-prevention content (the /body screen) must never make medical/diagnosis/injury-probability/"safe to play" claims — educational only.

Gemini / insights function gotcha: the LLM insights + PDF report Cloud Function (acesense-auth-function/insights/) uses a Gemini AQ.-format key that works only via REST generativelanguage.googleapis.com/v1beta/models/{model}:generateContent with the X-goog-api-key header — the @google/genai SDK 401s it (prefers OAuth/ADC). Use fetch, not the SDK. Key lives in acesense-auth-function/secrets/key.json (GEMINI_API_KEY=AQ...); secrets/ is gitignored — never commit or echo it. The function triggers on {sid}_combined.json Storage finalize and writes insightsUrl/pdfReportUrl back to the job doc.

Firebase specifics: project acesense-prod. Hosting targets: app->acesense-prod-app, landing->acesense-prod. Functions codebase is literally named functions, so a single-function deploy is --only "functions:functions:<name>". Region europe-west1 for all callables.

GateGuard hook ("Fact-Forcing Gate"): before Edit/Write/Bash it demands facts (importers, data schema, user instruction verbatim). Present them, then retry the identical call. It also emits a spurious "N files modified this session" scope warning that over-counts — ignore it. To disable for setup/repair: ECC_GATEGUARD=off or add the hook id to ECC_DISABLED_HOOKS.

Deploy mechanics recap: GPU backend auto-deploys on git push; everything else is manual Firebase CLI (currently blocked). Commit per repo; push == the deploy trigger for GPU only.

9. Persistent memory pointers (already written for you)​

Agent memory lives at ~/.claude/projects/-Users-akshaysarode-Desktop-Workspace-RunningProjects-acesense-AcesenseProd/memory/. Relevant files: acesense-fix-sweep-pending-deploy.md (this wave's deploy state — kept current), acesense-video-privesc.md (the paywall-bypass fixed earlier), acesense-insights-report-function.md (Gemini/insights gotcha), acesense-working-style.md (boring/small/verified; commit per repo), acesense-project-map.md (the 10-repo map). MEMORY.md is the index.

10. Suggested first moves for the takeover agent​

  1. Confirm nothing regressed: in each of the 4 changed repos run the test command in §8; all should still be green at the HEADs in §1.
  2. Ask Akshay to reauth Firebase, then run §2 in order and verify each with the hash pattern.
  3. After admin deploy, have Akshay do one clean sign-in to trigger the claim self-heal.
  4. Get the §6 legal facts from Akshay and do the single unifying pass on landing terms/privacy/marketing.
  5. Only then consider Wave 2 (§7) — and never payments.