teecup/CLAUDE.md

# CLAUDE.md — arbeidsinstruks for TeeCup

Les dette først i hver økt. Det koder hva vi har bestemt og hvordan vi jobber.

## Autoritative kilder (les før du gjør noe)
- `ARCHITECTURE_DECISIONS.md` — hva som er bestemt og hvorfor (ADR-001…). Fasit.
- `FEATURE_BACKLOG.md` — hva som gjenstår, hva som er utsatt, hva som mangler.
- `CHANGELOG.md` — kronologisk arbeidslogg (hva som er bygget, når, hvordan
  det ble verifisert, kjente fallgruver funnet underveis). IKKE noe å lese
  i sin helhet hver økt — les den ved regresjon-feilsøking, eller når du
  trenger å vite hvordan/hvorfor noe konkret ble bygget som det ble (grep
  etter filnavn/ADR-nummer/feature-navn). Se filens egen header for full
  bruksanvisning.
- Endres en beslutning: legg til en ny ADR, ikke slett historikk. Hold
  disse filene oppdatert når noe avgjøres.
- **Regelverk for HCP/slagfordeling — tre PDF-er lastet opp av brukeren
  2026-07-19** (ikke innsjekket i git, kun lokale filer på serveren, flyttet
  fra prosjektroten til `Temp-uploads/` 2026-08-07 — se eget notat om denne
  mappen lenger ned): `Temp-uploads/spilletyper-og-spilleformer-2023.pdf`,
  `Temp-uploads/Live Tourney _ A Guide to Handicap Scoring in Golf for
  Tournaments.pdf`, `Temp-uploads/SCGA Club Digest.pdf`. Brukeren: disse tre
  gir til sammen en tydelig
  beskrivelse av hvordan HCP og mottatte/tildelte slag skal beregnes/
  fordeles. Les disse FØR videre arbeid med `handicap_engine.py`,
  `app/handicap.py`, allowance-strategier (ADR-005/014) eller
  slagfordeling (ADR-008) for NYE turneringsformater. **Rettelse
  2026-08-05:** de opprinnelige fire (Københavner/High-low-high/Robbins/
  Try all) er ikke lenger de aktuelle — Københavner, High-low-high og
  Try all (Chapman/Pinehurst) er alle bygget og live (se
  FEATURE_BACKLOG.md), Robbins ble droppet av bruker. Gjelder nå enhver
  FREMTIDIG ny turneringsform (f.eks. asymmetriske lag-vs-individuell-
  formater) — les PDF-ene før slagfordelingen designes for slike.
- **Design-dokumentasjon, to filer med bevisst motsatt retning (2026-07-27):**
  `DESIGN_SYSTEM.md` (innsjekket i git) er DESKRIPTIV — hva som faktisk ER i
  koden i dag (farger/typografi/komponentmønstre/golfscore-språket), avledet
  direkte fra `globals.css`/`components/ui/*`. `teecup-scorekort-og-entry-
  spec.md` (lastet opp av brukeren til prosjektroten, IKKE innsjekket i git)
  er PRESKRIPTIV — hva scorekort-/score-entry-skjermene BØR bli, basert på en
  sammenligning mot fem etablerte golf-apper. Der de to avviker vinner
  kildekoden (DESIGN_SYSTEM.md beskriver den), men spec-dokumentets §3
  "Compliance-pass" er en konkret sjekkliste over kjente avvik — les den FØR
  videre visuelt arbeid på scorekort-/score-entry-skjermene.
- **`Temp-uploads/`-mappen (opprettet av bruker 2026-08-07, gitignored)**
  er der brukeren laster opp støttefiler — skjermdumper, videoer, PDF-er,
  V0-eksport-zip-er og lignende — ment som illustrasjon/kildemateriale til
  Claude, ikke som permanente prosjektfiler. Sjekk denne mappen når
  brukeren nevner at de "har lastet opp" noe uten å oppgi full sti. Flytt
  nye støttefiler dit etter hvert som de dukker opp i prosjektroten,
  fremfor å la dem hope seg opp løst i roten.

## Sikkerhetsregler (ufravikelige)
- Rør ALDRI `teeoff`-databasen eller den ekte `teecup_db` uten at brukeren
  eksplisitt har bekreftet det i samme økt. Test alltid migrasjoner mot en egen
  scratch-database først, og rydd opp etterpå.
- Vis planen (hvilke kommandoer, mot hvilken database) FØR du kjører noe som
  skriver, migrerer eller sletter. Vent på bekreftelse.
- Hemmeligheter (passord, secrets) bor i `.env` (filrettigheter 600), dekkes av
  `.gitignore`, committes aldri, og skrives aldri i klartekst i chatten eller i
  SQL-filer. Generer dem på serveren (`openssl rand -base64 32`).
- Kjør appen som databaserollen `teecup_app` (NOSUPERUSER, NOBYPASSRLS) — aldri
  som `teeoff_admin`/superuser i runtime.

## Arkitektur-invarianter (ikke bryt uten en ny ADR)
- Tenant = organisasjon. `organization_id` på alle domenetabeller, håndhevet av
  RLS. App-koden setter `app.current_org` med `SET LOCAL` per transaksjon.
- Verifiser at brukeren er medlem av organisasjonen FØR org-konteksten settes.
  RLS stoler blindt på `app.current_org`.
- Egen innlogging (uavhengig av teeoff). Banedata hentes fra teeoff via lesende
  API, ikke delt database.
- v1 = nøyaktig to lag (Ryder Cup-format), håndhevet i app-laget. Match-modellen
  holdes generell (to sider) så knockout/flere lag kan komme senere.
- Handicap-/matchlogikk skal ligge i `handicap_engine.py` (rent, testet, uten
  db/API-avhengigheter). Allowances er konfig, ikke hardkodet.
- Media (bilder/video) skal i objektlagring (MinIO), ikke i Postgres. Postgres
  holder bare metadata + nøkkel.

## Tilgjengelighet — frontend (ufravikelig, gjelder ALT, eksisterende og fremtidig)
- Brukeren instruerte eksplisitt 2026-07-22: ALL frontend — det som
  allerede finnes OG alt som designes med V0 fremover — skal være
  lesbart, forståelig og betjenbart for noen med noe redusert syn UTEN
  briller, så langt det praktisk lar seg gjøre. Dette er en STÅENDE
  forventning til alt fremtidig UI-arbeid, ikke en engangsting for én
  skjerm.
- Praktisk konsekvens: god kontrast, stor nok skrift, store nok
  trykkflater, ikke ikon-only uten tekst-label for viktige handlinger,
  ikke avhengig av finmotorikk/skarpt syn for å bruke appen.
- Gjelder begge retninger: (a) ta dette eksplisitt med som krav når en ny
  V0-prompt skrives eller en V0-eksport gjennomgås, og (b) rett
  opportunistisk opp eksisterende skjermer når de likevel røres i en
  annen runde — ingen egen stor retrofit-runde er igangsatt eller bedt
  om ennå.

## Navneformat (ufravikelig, gjelder ALT, eksisterende og fremtidig)
- Brukeren instruerte eksplisitt 2026-07-26: når TeeCup kommuniserer
  DIREKTE TIL brukeren (adresserer dem, "snakker til" dem) — f.eks. en
  dashbord-hilsen ("God morgen Erol") eller en e-post/varsel rettet til
  mottakeren selv — skal KUN FORNAVN brukes, aldri fullt navn.
- Til vanlig (lister, roster, chat-forfatter, "fjern X"-bekreftelser,
  administrasjonsvisninger, alt som IKKE er direkte adressering) brukes
  fortsatt fullt navn, eller initial(er)+etternavn, eller annet som er
  nødvendig for å skille personer fra hverandre — ikke fornavn alene der.
- Samme STÅENDE forventning som tilgjengelighetsregelen over: gjelder
  fremtidig arbeid direkte, og rettes opportunistisk når en skjerm
  likevel røres — ingen egen retrofit-runde igangsatt.
- **✅ FIKSET 2026-07-26** (samme dag, i "fiks alle kjente små bugs"-
  runden): dashbordets hilsen brukte fullt navn — rettet til
  `me.first_name ?? me.display_name` (`/auth/me` eksponerte allerede
  `first_name` separat, ingen backend-endring nødvendig). Se
  CHANGELOG.md for full detalj.

## Turneringsoppsett — stor skjerm først (ufravikelig, gjelder ALT, eksisterende og fremtidig)
- Brukeren instruerte eksplisitt 2026-08-17: turneringsOPPSETT (opprette
  turnering, sette opp lag/tropper, importere/administrere spillere,
  runder, klasser, baneoppsett, alt organisator-arbeid FØR/RUNDT selve
  spillingen) skal designes "stor skjerm først", IKKE "mobil først" —
  organisatoren sitter som regel foran en PC når dette gjøres, ikke på
  mobil på banen. Dette er en STÅENDE forventning til alt fremtidig
  UI-arbeid på denne typen skjermer, ikke en engangsting.
- Gjelder KUN oppsett-/administrasjonsskjermer. Skjermer SPILLEREN bruker
  UNDER selve rundens gang (scorekort/slag-registrering/rangefinder/
  leaderboard-under-spilling) forblir mobil-først som før — de brukes på
  banen, på mobil, ikke ved en PC. Grensen følger hvem som sitter hvor,
  ikke en fast liste — vurder per skjerm hvem som faktisk bruker den og
  fra hvilken enhet.
- Praktisk konsekvens: layout/typografi/tett-vs-luftig-avstand
  optimaliseres for et bredt skjermbilde som førstevalg (f.eks. tabeller
  med flere synlige kolonner samtidig i stedet for kortstabler, sidepanel-
  layout i stedet for full-bredde-modaler, hover-tilstander som en reell
  interaksjon), men skal FORTSATT fungere og være betjenbart på smal
  skjerm (samme STÅENDE tilgjengelighetsregel over gjelder uansett
  skjermbredde) — "stor skjerm først" er en prioritering av hvilket
  format som designes FOR primært, ikke en unnskyldning for å la mobil
  forfalle.
- Gjelder begge retninger: (a) ta dette eksplisitt med som krav når en ny
  V0-prompt skrives for et oppsett-/administrasjonsskjermer, og (b) rett
  opportunistisk opp eksisterende oppsett-skjermer når de likevel røres i
  en annen runde — ingen egen stor retrofit-runde er igangsatt eller bedt
  om ennå.

## Arbeidsmåte
- Inkrementelt. Ingenting tas for gitt før det er testet. Bekreft hvert steg før
  du går videre.
- Bruk git (remote: brukerens Forgejo). Commit i logiske steg med tydelige
  meldinger.
- Er du usikker på omfang eller en beslutning: spør heller enn å gjette.
- Kommuniser på norsk i chatten som standard (brukerens eksplisitte
  instruks, notert her 2026-08-23 siden det ikke sto skriftlig fra før).
  Kode, commit-meldinger og identifikatorer følger fortsatt vanlig
  engelsk konvensjon — dette gjelder kun samtalen med brukeren.

## Status og neste steg
Den detaljerte, kronologiske statusloggen (hva som er ferdig, verifisert
og rullet ut, runde for runde) flyttet til `CHANGELOG.md` 2026-08-02 —
denne filen ble for stor til å injiseres i sin helhet hver økt uten å
fortrenge de faktiske reglene over. `CHANGELOG.md` sin egen "Neste
steg"-seksjon nederst har den ferskeste, mest detaljerte punktlisten over
åpne tråder; `FEATURE_BACKLOG.md` har det bredere, mindre ferske bildet
av hva som gjenstår/er utsatt. Oppdater `CHANGELOG.md` (ikke denne filen)
når noe bygges, verifiseres og rulles ut — samme format og disiplin som
før: dato, hva som ble gjort, hvordan det ble verifisert, hva som ble
rullet ut og hvordan.