diff --git a/README.md b/README.md
index ece3648..ba59b51 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,94 @@
 # Prosjekt 1 - Sangtekster
 
-##
+**Webapp:** _[Lenke legges til når appen er deployet på VM!!]_
+
+En React-applikasjon for å utforske sanger og sangtekster fra Bonnie Tyler. Brukeren kan filtrere sanger etter album, sortere dem alfabetisk, favorittmerke sanger, og lese sangtekster hentet live fra et eksternt API.
+
+## Installasjon og kjøring
+
+### Krav
+
+- Node.js >= 24.6.0
+- npm >= 11.0.0
+
+### Steg
+
+1. Klon repoet:
+
+   ```bash
+   git clone git@git.ntnu.no:IT2810-H26/T28-Project-1.git
+   cd T28-Project-1
+   ```
+
+2. Installer avhengigheter:
+
+   ```bash
+   npm install
+   ```
+
+3. Start utviklingsserveren:
+
+   ```bash
+   npm run dev
+   ```
+
+   Appen kjører deretter på `http://localhost:5173`.
+
+### Andre kommandoer
+
+| Kommando                | Beskrivelse                                      |
+| ------------------------ | ------------------------------------------------- |
+| `npm run build`          | Bygger appen for produksjon (kjører TypeScript-sjekk + Vite build) |
+| `npm run preview`        | Forhåndsviser produksjonsbygget lokalt            |
+| `npm run lint`           | Kjører ESLint på kodebasen                        |
+| `npm run format`         | Formaterer koden med Prettier                     |
+| `npm run format:check`   | Sjekker at koden er formatert riktig, uten å endre |
+| `npm run test`           | Kjører testene med Vitest                         |
+
+## Valgt API og designvalg
+
+### API
+
+Sangtekster hentes fra [lyrics.ovh](https://lyrics.ovh) sitt gratis, nøkkelfrie API (`https://api.lyrics.ovh/v1/{artist}/{title}`). Det ble valgt fordi det er enkelt å bruke uten autentisering, og dekker sangtekster for de fleste av Bonnie Tylers kjente sanger. Ikke alle sanger finnes i API-et, så appen håndterer dette eksplisitt (se under).
+
+Kallet gjøres i den egendefinerte hooken `useLyrics` (`src/hooks/useLyrics.ts`), som bruker **TanStack Query** (`useQuery`) til å hente, cache og holde styr på lasting/feiltilstand for hvert API-kall. Sangdataene selv (tittel, artist, album) ligger statisk i `src/data/songs.ts`, siden dette er informasjon som ikke endrer seg og ikke trenger å hentes fra et eksternt API.
+
+### Designvalg
+
+- **State løftet opp til `App.tsx`**: All state som flere komponenter er avhengig av (valgt sang, filter, sortering, favoritter) eies av `App.tsx` og sendes ned som props. Dette følger Reacts anbefalte mønster for "lifting state up", og gjør datastrømmen i appen enveis og forutsigbar.
+- **Egendefinerte hooks for lagring**: `useLocalStorage` og `useSessionStorage` (`src/hooks/`) er generiske hooks som speiler `useState`s API (`[verdi, settefunksjon]`), men synkroniserer verdien mot nettleserens Web Storage. Favoritter lagres i `localStorage` (skal bestå over tid), mens filter/sortering lagres i `sessionStorage` (skal nullstilles ved ny nettleserøkt).
+- **Kontrollerte komponenter**: Filter- og sorteringsvelgerne i `FilterSortBar` er kontrollerte (`value` + `onChange` styrt av state i `App.tsx`), slik at UI alltid reflekterer den faktiske state, ikke DOM-ens interne tilstand.
+- **Tydelig separasjon av ansvar**: Presentasjonskomponenter (`SongCard`, `SongList`, `FavoriteButton`, `Navigation`, `FilterSortBar`, `LyricsDisplay`) mottar alt de trenger via props, mens all logikk (filtrering, sortering, favoritt-toggling, API-henting) ligger i `App.tsx` eller i egne hooks/utils.
+- **Lasting og feilhåndtering**: `SongCard` viser en lasteindikator mens sangteksten hentes, og en tydelig feilmelding dersom kallet feiler eller sangen ikke finnes i API-et (API-et kan svare med `{ error: ... }` i stedet for tekst).
+
+## Testing
+
+Testene kjøres med **Vitest** og **React Testing Library**, og ligger ved siden av filen de tester.
+
+- `src/test/setup.test.tsx` verifiserer at testoppsettet (Vitest + Testing Library + jsdom) fungerer, ved å rendre en enkel komponent og sjekke at innholdet vises.
+- `src/utils/formatLyrics.test.ts` tester `parseLyrics`-funksjonen, som formaterer rå sangtekst fra API-et til strofer/avsnitt. Testen bekrefter at funksjonen korrekt deler opp en sangtekst i flere strofer selv når API-teksten ikke inneholder tomme linjer mellom vers og refreng.
+
+I tillegg til automatiserte tester er følgende funksjonalitet manuelt testet gjennom utvikling av hvert issue:
+
+- Filtrering av sanger etter album, og at valget nullstiller riktig sang-indeks
+- Sortering av sanger alfabetisk på tittel
+- Favorittmerking av sanger, og at valget består ved sideoppdatering (`localStorage`)
+- At filter- og sorteringsvalg består ved sideoppdatering, men nullstilles i en ny nettleserøkt (`sessionStorage`)
+- Lasteindikator og feilmelding ved henting av sangtekst, inkludert for sanger uten tekst i API-et
+- Responsivt layout på mindre skjermstørrelser
+
+Kjør testene med:
+
+```bash
+npm run test
+```
+
+## Bruk av KI
+
+Vi har brukt Claude Code gjennom utviklingen av prosjektet, hovedsakelig som et hjelpemiddel for de gruppemedlemmene uten særlig erfaring med React. 
+
+Vanlig arbeidsflyt har vært at gruppemedlemmet selv skriver kode for en gitt issue, og at KI-en forklarer relevante React-/TypeScript-konsepter, peker på feil og foreslår rettelser, i stedet for å skrive løsningen direkte. Eksempler på dette er implementasjon av filtrering, sortering, favorittfunksjonalitet, `useLocalStorage`/`useSessionStorage`-hooks og håndtering av lasting/feiltilstand ved henting av sangtekster.
+
+KI er også brukt direkte til enkelte oppgaver som hjelp til løsing av merge-konflikter og oppsett av README.md-filen.
+
+**Erfaring:** Å bruke KI-en til å forklare og gi tilbakemelding på egenskrevet kode, fremfor å generere den, har gjort det lettere å faktisk forstå konseptene, i stedet for å kopiere en ferdig løsning. KI har også vært nyttig for å raskt diagnostisere problemer som ellers ville tatt lang tid å feilsøke manuelt.