Skip to content

chore: agent-legibility sweep — repo map, doc truth pass, dead-code deletion #796

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
njrini99-code merged 2 commits into from
Jul 10, 2026
Merged

chore: agent-legibility sweep — repo map, doc truth pass, dead-code deletion #796

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4cf220
chore: agent-legibility sweep — repo map, doc status headers, dead-co…
Jul 10, 2026
3cd8fca
Merge main into legibility sweep — honor dead-code deletions
Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 21 additions & 9 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,20 @@ SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
# Application Configuration (REQUIRED)
# -----------------------------------------------------------------------------
NEXT_PUBLIC_APP_URL=http://localhost:3000
# RESERVED — not read anywhere in src/ today (verified 2026-07-09). Safe to
# set, has no effect until a call site is added.
NEXT_PUBLIC_APP_NAME=Helm Sports Labs

# Development Mode (Disable in production!)
# RESERVED — not read anywhere in src/ today (verified 2026-07-09). There is
# no dev-mode gate in the app; this var currently does nothing.
NEXT_PUBLIC_DEV_MODE=false

# -----------------------------------------------------------------------------
# Tambo AI (for GolfHelm generative UI)
# -----------------------------------------------------------------------------
# RESERVED — aspirational. No `tambo` package.json dependency and zero Tambo
# references anywhere in src/ (verified 2026-07-09); the generative-UI
# integration this section name implies has not been built.
NEXT_PUBLIC_TAMBO_API_KEY=your-tambo-api-key-here

# -----------------------------------------------------------------------------
Expand Down Expand Up @@ -146,7 +152,10 @@ GMAIL_DAILY_CAP=50
FROM_EMAIL=Helm Sports <notifications@helmsportslabs.com>
# From address for the weekly coach digest email (resend-client.ts).
RESEND_COACH_DIGEST_FROM=Helm Sports <notifications@helmsportslabs.com>
# From address for team-invite emails (team-invite.ts).
# RESERVED — not read anywhere in src/ today (verified 2026-07-09). No
# team-invite.ts file exists; only RESEND_COACH_DIGEST_FROM is currently
# read by src/lib/email/resend-client.ts. Safe to set, has no effect until
# a team-invite send path is built.
RESEND_TEAM_INVITE_FROM=Helm Sports <notifications@helmsportslabs.com>

# -----------------------------------------------------------------------------
Expand Down Expand Up @@ -238,14 +247,17 @@ GITHUB_PR_AUTHOR_LOGINS=your-github-username
# INNGEST_SIGNING_KEY=signkey-prod-your-key

# -----------------------------------------------------------------------------
# Mapbox (Maps — courses, travel, recruiting heat-maps)
# Mapbox (Maps — courses, travel, recruiting heat-maps) — RESERVED, NOT BUILT
# -----------------------------------------------------------------------------
# Free tier: 50K map loads/month for Web SDK, 25K monthly active users
# on Mobile (Capacitor). Sign up at https://account.mapbox.com → tokens
# page → create a public token scoped to styles:read, fonts:read,
# tilesets:read. The public token ships to the browser — fine since
# scoping prevents abuse. Restrict by URL (helmsportslabs.com, *.vercel.app)
# in the Mapbox dashboard.
# No `mapbox` package.json dependency and zero Mapbox references anywhere in
# src/ (verified 2026-07-09) — src/lib/mapbox/client.ts and
# src/components/maps/CourseMap.tsx do not exist. This section documents the
# intended future setup, not a live integration: free tier would be 50K map
# loads/month for Web SDK, 25K monthly active users on Mobile (Capacitor).
# If/when built: sign up at https://account.mapbox.com → tokens page →
# create a public token scoped to styles:read, fonts:read, tilesets:read.
# The public token ships to the browser — fine since scoping prevents abuse.
# Restrict by URL (helmsportslabs.com, *.vercel.app) in the Mapbox dashboard.
# NEXT_PUBLIC_MAPBOX_TOKEN=pk.your-mapbox-public-token

# ---- GolfHelm UI Screenshots ----
Expand Down
14 changes: 14 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,19 @@
# AGENTS.md

## Repo map

- `docs/REPO_MAP.md` is the structural map of this repo for agents: the
resolved route atlas for BaseballHelm/GolfHelm/Lift Lab/Admin (route
groups resolved, per-role rails), the canonical idioms table (action
wrappers, toast, data access, design tokens per product, nav
registries, error-boundary pattern — each with a file:line anchor),
the known traps list, and a before-you-write-code checklist.
- Read it before adding a new route, a new action wrapper/toast/data-access
call, or a new design-token consumer — it exists so you don't have to
re-derive these conventions by grepping from scratch.
- It maps *shape and convention*, not feature behavior — for feature
behavior, use the Feature awareness routing below.

## Feature awareness

- Treat `memory/registry.yml` as the feature routing table for AI work.
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ For large changes or PR reviews, read `/tmp/helmv3-context-pack.md` after genera
| **CoachHelm AI** (insights, patterns, predictions, reviews, philosophy) | `memory/context/coachhelm-ai.md` — V2 engine architecture, pipeline, components |
| **Routes, actions, or file locations** ("where is the code for X?") | `memory/projects/golfhelm.md` — All routes, all action files, component directories |
| **Baseball features** | `memory/context/baseballhelm-features.md` — feature-by-feature data flow, files, tables, gaps; `docs/audits/BASEBALLHELM_CANONICAL_SPEC.md` — canonical spec (source of truth for what baseball should be) |
| **Cross-product structure** (route trees, canonical action-wrapper/toast/data-access/design-token/nav-registry/error-boundary idioms, known traps) | `docs/REPO_MAP.md` — resolved route atlas for BaseballHelm/GolfHelm/Lift Lab/Admin, idioms table with file:line anchors, 7 traps, pre-code checklist |

### By Role Context

Expand Down
7 changes: 7 additions & 0 deletions docs/ADMIN_DASHBOARD_UPGRADE_PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Dated 2026-03-13. Prescribes a "bg-white/65 backdrop-blur-[16px]" glass pattern now explicitly banned by eslint-rules/no-arbitrary-bg-white.mjs. Superseded in spirit by the unified /admin Helm Bridge command center (docs/superpowers/plans/2026-07-01-helm-bridge-command-center.md).
KEPT FOR HISTORY -- do not delete this file.
-->

# Admin Dashboard Upgrade Plan

> Compiled from 11 parallel research agents analyzing UI/UX design + data pipelines across all 5 admin tabs.
Expand Down
7 changes: 7 additions & 0 deletions docs/APPSTORE_MASTER_REMEDIATION_PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Committed 2026-03-05 ("comprehensive app stability overhaul"), iOS App Store submission scope. Not confirmed against current App Store Connect status in the 2026-07-10 sweep — re-verify before relying on this; treat as historical if the submission has since moved forward.
KEPT FOR HISTORY -- do not delete this file.
-->

# App Store Master Remediation Plan

**App:** Helm Sports Labs (com.helmsportslabs.golfhelm)
Expand Down
7 changes: 7 additions & 0 deletions docs/APPSTORE_REQUIREMENTS_CHECKLIST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Committed 2026-03-05 ("comprehensive app stability overhaul"), iOS App Store submission scope. Not confirmed against current App Store Connect status in the 2026-07-10 sweep — re-verify before relying on this; treat as historical if the submission has since moved forward.
KEPT FOR HISTORY -- do not delete this file.
-->

# Apple App Store Requirements Checklist

**App:** Helm Sports Labs (com.helmsportslabs.golfhelm)
Expand Down
7 changes: 7 additions & 0 deletions docs/BASEBALL_DASHBOARD_AUDIT_REPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Generated "February 2025" (likely meant 2026) — long predates docs/audits/BASEBALLHELM_CANONICAL_SPEC.md, docs/audits/BASEBALLHELM_PRODUCTION_VERDICT.md, and docs/audits/DB_FORENSIC_AUDIT_2026-07-08.md, which cover identical ground with current data.
KEPT FOR HISTORY -- do not delete this file.
-->

# BaseballHelm Dashboard Audit Report
## Comprehensive Analysis: UI, UX, Features, Database, and Wiring

Expand Down
7 changes: 7 additions & 0 deletions docs/BASEBALL_RLS_SECURITY_AUDIT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Generated 2026-02-21 — long predates docs/audits/BASEBALLHELM_CANONICAL_SPEC.md and docs/audits/DB_FORENSIC_AUDIT_2026-07-08.md, which cover identical ground with current data.
KEPT FOR HISTORY -- do not delete this file.
-->

# BaseballHelm RLS Security Audit

**Generated:** 2026-02-21
Expand Down
7 changes: 7 additions & 0 deletions docs/CLEANSLATE_JOB_LIST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: 2026-07-01 parallel job list sourced from docs/audits/HELMV3_ISSUE_LEDGER_2026-06-30.md §4. The clean-slate train it tracked has concluded (project memory: "lint 0 locked; graveyard 16 tables"), and the underlying issue ledger has a later iteration, docs/audits/ISSUE_LEDGER_2026-07-03.md.
KEPT FOR HISTORY -- do not delete this file.
-->

# BaseballHelm Clean-Slate — Parallel Job List

> Hand each **GROUP** below to a separate Claude session. Each group is file-disjoint from the others,
Expand Down
7 changes: 7 additions & 0 deletions docs/COACHHELM_STATE_2026-05-26.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: CoachHelm state-snapshot doc dated 2026-05-26, superseded by later, more comprehensive passes: docs/audits/COACHHELM_FULL_VALIDITY_AND_FACET_AUDIT_2026-06-06.md and COACHHELM_MASTER_ENGINE_FEATURE_REMEDIATION_AUDIT_2026-06-21.md.
KEPT FOR HISTORY -- do not delete this file.
-->

# CoachHelm — Complete State, Plan, and Build Reference

> **Snapshot date:** 2026-05-26
Expand Down
7 changes: 7 additions & 0 deletions docs/CODEBASE_MAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Front-matter says last_mapped: 2026-01-13, total_files: 1752. Actual current counts (2026-07-10): `find src -type f` = 3103, `git ls-files` = 6477 — the map understates the codebase by ~1.8-3.7x. Content was never regenerated after that date.
KEPT FOR HISTORY -- do not delete this file.
-->

---
last_mapped: 2026-01-13T00:00:00Z
total_files: 1752
Expand Down
7 changes: 7 additions & 0 deletions docs/CoachHelm UI Audit Future.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: CoachHelm UI/data-mapping doc dated 2026-05-29, superseded by later, more comprehensive passes: docs/audits/COACHHELM_FULL_VALIDITY_AND_FACET_AUDIT_2026-06-06.md and COACHHELM_MASTER_ENGINE_FEATURE_REMEDIATION_AUDIT_2026-06-21.md.
KEPT FOR HISTORY -- do not delete this file.
-->

# CoachHelm UI Audit — Future

> **What this is:** every CoachHelm UI surface mapped to its **real production data** (prod `qmnssrrolpinvwjjnufo`), plus a prioritized "what to fix / build next" plan.
Expand Down
7 changes: 7 additions & 0 deletions docs/DATABASE_FIXES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: PARKED
DATE: 2026-07-10
PARKING DECISION: Committed 2026-02-16 ("docs: add overnight build reports") — an accurately-dated point-in-time fix log, not a current-state claim. Parked as historical record.
KEPT FOR HISTORY -- do not delete this file.
-->

# Database & Backend Fixes Report

> **Generated**: 2026-02-17 00:10 EST
Expand Down
7 changes: 7 additions & 0 deletions docs/END-OF-RUN-2026-05-26.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: PARKED
DATE: 2026-07-10
PARKING DECISION: Self-described session/continuation report ("save Part 2 continuation report before computer restart") — an accurately-dated point-in-time log, not a live-state claim. Parked as historical record.
KEPT FOR HISTORY -- do not delete this file.
-->

# GolfHelm v3 — End-of-run review (2026-05-26)

> **Comprehensive map of every wave shipped tonight.** Generated after merging the last PR; mirrors the live state of prod + the codebase as of 2026-05-26 23:30 UTC.
Expand Down
7 changes: 7 additions & 0 deletions docs/ERROR_HANDLING_FIXES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: PARKED
DATE: 2026-07-10
PARKING DECISION: Committed 2026-02-16 ("docs: add overnight build reports") — an accurately-dated point-in-time fix log, not a current-state claim. Parked as historical record.
KEPT FOR HISTORY -- do not delete this file.
-->

# Error Handling Fixes Report

> **Generated**: 2026-02-17 00:20 EST
Expand Down
7 changes: 7 additions & 0 deletions docs/FEATURE_AUDIT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Committed 2026-03-05 ("comprehensive app stability overhaul"), iOS App Store submission scope. Not confirmed against current App Store Connect status in the 2026-07-10 sweep — re-verify before relying on this; treat as historical if the submission has since moved forward.
KEPT FOR HISTORY -- do not delete this file.
-->

# Feature & Functionality Audit for App Store Readiness

**Date:** 2026-03-05
Expand Down
7 changes: 7 additions & 0 deletions docs/HELM_DATABASE_VERCEL_COACHHELM_DEEP_DIVE_2026-05-27.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: Deep-dive doc dated 2026-05-27, superseded by later, more comprehensive passes: docs/audits/COACHHELM_FULL_VALIDITY_AND_FACET_AUDIT_2026-06-06.md and docs/audits/DB_FORENSIC_AUDIT_2026-07-08.md.
KEPT FOR HISTORY -- do not delete this file.
-->

# Helm Database, Vercel, Supabase, and CoachHelm Deep Dive

Date: 2026-05-27
Expand Down
7 changes: 7 additions & 0 deletions docs/IOS_NATIVE_AUDIT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Committed 2026-03-05 ("comprehensive app stability overhaul"), iOS App Store submission scope. Not confirmed against current App Store Connect status in the 2026-07-10 sweep — re-verify before relying on this; treat as historical if the submission has since moved forward.
KEPT FOR HISTORY -- do not delete this file.
-->

# iOS Native Integration & Capacitor Audit

**Date:** 2026-03-05
Expand Down
7 changes: 7 additions & 0 deletions docs/LANDING_ENTRY_WORLD_DESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: PARKED
DATE: 2026-07-10
PARKING DECISION: REJECTED — parked, see #650. The Entry World / First Light landing design was rejected in favor of #650's flush-diamond login. src/app/page.tsx uses @/components/landing/{Hero,Footer}, not the Entry-World scene system this doc specs.
KEPT FOR HISTORY -- do not delete this file.
-->

# HELM — The Entry World
### Landing · Login · Onboarding as one continuous experience
*Fable's design spec · 2026-07-02 · synthesized from 4-stream research (cinematic patterns / real-glass cookbook / art direction / scroll narrative) + Nick's brief + his 4 references. Companion doc: docs/baseball/ENTRY_SCENES_DESIGN.md (the painterly SVG scenes).*
Expand Down
7 changes: 7 additions & 0 deletions docs/OVERNIGHT_BUILD_REPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: PARKED
DATE: 2026-07-10
PARKING DECISION: Committed 2026-02-16 ("docs: add overnight build reports") — an accurately-dated point-in-time fix log, not a current-state claim. Parked as historical record.
KEPT FOR HISTORY -- do not delete this file.
-->

# BaseballHelm Overnight Build Report

> **Build Date**: 2026-02-17
Expand Down
7 changes: 7 additions & 0 deletions docs/PERFORMANCE_FIX_PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: 2026-02-20 perf plan. Performance work has continued well past this point (CI OOM fixes, the ui-performance-profiler skill, docs/perf-analysis-dashboard-timeouts-2026-03-09.md as a later, more current pass).
KEPT FOR HISTORY -- do not delete this file.
-->

# GolfHelm Performance Fix Architecture Plan

**Created:** 2026-02-20
Expand Down
7 changes: 7 additions & 0 deletions docs/PRIVACY_AUDIT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Committed 2026-03-05 ("comprehensive app stability overhaul"), iOS App Store submission scope. Not confirmed against current App Store Connect status in the 2026-07-10 sweep — re-verify before relying on this; treat as historical if the submission has since moved forward.
KEPT FOR HISTORY -- do not delete this file.
-->

# Privacy & Data Compliance Audit Report

**App:** Helm Sports Labs (GolfHelm / BaseballHelm)
Expand Down
7 changes: 7 additions & 0 deletions docs/PUSH_NOTIFICATION_AUDIT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: STALE
DATE: 2026-07-10
SUPERSEDED BY / WHY: Committed 2026-03-05 ("comprehensive app stability overhaul"), iOS App Store submission scope. Not confirmed against current App Store Connect status in the 2026-07-10 sweep — re-verify before relying on this; treat as historical if the submission has since moved forward.
KEPT FOR HISTORY -- do not delete this file.
-->

# Push Notification Audit Report

**Date:** March 5, 2026
Expand Down
7 changes: 7 additions & 0 deletions docs/RECON_REPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: Feb/March 2026 point-in-time report; the ground it covers has since had a dedicated, later remediation pass (project memory: "Golf stats correctness audit", "Shot-tracking unit audit — feet/yards blend corrupts proximity").
KEPT FOR HISTORY -- do not delete this file.
-->
Comment on lines +1 to +6

@coderabbitai coderabbitai Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Supersession rationale doesn't match this file's content.

This file is entirely about BaseballHelm route completion status (2026-02-16). The SUPERSEDED BY / WHY text cites "Golf stats correctness audit" and "Shot-tracking unit audit — feet/yards blend corrupts proximity" — neither topic appears anywhere in this document. This looks like the header block was copy-pasted from a different (golf-related) file in the same PR.

Suggested fix 
-SUPERSEDED BY / WHY: Feb/March 2026 point-in-time report; the ground it covers has since had a dedicated, later remediation pass (project memory: "Golf stats correctness audit", "Shot-tracking unit audit — feet/yards blend corrupts proximity").
+SUPERSEDED BY / WHY: Feb 2026 point-in-time BaseballHelm route/build report; superseded by later BaseballHelm audits (docs/BASEBALL_DASHBOARD_AUDIT_REPORT.md, docs/audits/HELMV3_ISSUE_LEDGER_2026-06-30.md).
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: Feb/March 2026 point-in-time report; the ground it covers has since had a dedicated, later remediation pass (project memory: "Golf stats correctness audit", "Shot-tracking unit audit — feet/yards blend corrupts proximity").
KEPT FOR HISTORY -- do not delete this file.
-->
<!--
STATUS: SUPERSEDED
DATE: 2026-07-10
SUPERSEDED BY / WHY: Feb 2026 point-in-time BaseballHelm route/build report; superseded by later BaseballHelm audits (docs/BASEBALL_DASHBOARD_AUDIT_REPORT.md, docs/audits/HELMV3_ISSUE_LEDGER_2026-06-30.md).
KEPT FOR HISTORY -- do not delete this file.
-->
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/RECON_REPORT.md` around lines 1 - 6, Correct the top status comment in
RECON_REPORT.md so its SUPERSEDED BY / WHY rationale accurately references the
BaseballHelm route completion report and its later replacement, removing the
unrelated golf audit references while retaining the historical-file notice.


# BaseballHelm Overnight Build - Reconnaissance Report

> **Generated**: 2026-02-16 22:10 EST
Expand Down
Loading
Loading