diff --git a/README.md b/README.md
index a8fde7e..ee9e445 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,12 @@
 
 Repository for team IT2810-H26-T29 in IT2810-H26.
 
+## Running the project
+
+See [`t29-project-1/README.md`](t29-project-1/README.md) for how to install and
+run the project. The VM is not working, so the project must be run locally on
+`localhost`.
+
 ## Working in this repository
 
 `main` is protected — you cannot push to it directly. Work on a branch and
diff --git a/t29-project-1/README.md b/t29-project-1/README.md
index d8cb914..f23a98e 100644
--- a/t29-project-1/README.md
+++ b/t29-project-1/README.md
@@ -1,73 +1,108 @@
-# React + TypeScript + Vite
+# T29 Project 1
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+A cat browser built for IT2810. Browse random cat pictures from
+[The Cat API](https://thecatapi.com/), filter them by breed, and save your
+favorites.
 
-Currently, two official plugins are available:
+- Browse cats with the previous/next buttons.
+- Filter cats by breed with the breed dropdown.
+- Mark cats as favorites (stored in `localStorage`) and view them on the
+  favorites page.
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+Built with React, TypeScript and Vite. A small Express server proxies requests
+to The Cat API, so the API key stays on the server and is never exposed to the
+browser.
 
-## React Compiler
+> **The VM is not working.** The project therefore cannot be accessed there
+> and has to be run locally on `localhost`, as described below.
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+## Prerequisites
 
-## Expanding the ESLint configuration
+- **Node.js** 22.22.2 or newer (24.15 or newer also works), with npm.
+  Older versions may print engine warnings during `npm install`.
+- **A Cat API key.** Get a free one from [thecatapi.com](https://thecatapi.com/).
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+## Setup
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+All commands are run from the `t29-project-1` folder:
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+```bash
+cd t29-project-1
+npm install
+```
+
+Create your own `.env` file from the example:
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-]);
+```bash
+cp .env.example .env
 ```
 
-You can also install [eslint-plugin-react-x](https://npmx.dev/package/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://npmx.dev/package/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x';
-import reactDom from 'eslint-plugin-react-dom';
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-]);
+Open `.env` and replace `your_cat_api_key_here` with your API key. The file is
+git-ignored and must never be committed.
+
+## Run the project
+
+The project has two parts that must both be running: the API server and the
+frontend. Start each in its own terminal, from the `t29-project-1` folder.
+
+**Terminal 1 — API server** (runs on `http://localhost:3001`):
+
+```bash
+npm run start:server
+```
+
+**Terminal 2 — frontend:**
+
+```bash
+npm run dev
 ```
+
+Then open **<http://localhost:5173/project1/>** in your browser (Vite prints the
+exact URL in the terminal). The app is served under the `/project1/` base path,
+so the trailing `/project1/` is required — the bare `http://localhost:5173/`
+will not show the app.
+
+For the available endpoints, request examples, error handling, and how the
+frontend finds the API server, see the API guide:
+[`src/docs/CAT_API.md`](src/docs/CAT_API.md).
+
+## Troubleshooting
+
+- **The breed dropdown says "Could not load breeds", or the browser shows
+  `ERR_CONNECTION_REFUSED`:** the API server is not running. Start it with
+  `npm run start:server`.
+- **Requests fail with 401/403:** `CAT_API_KEY` is missing or invalid in
+  `.env`. The API server does not reload automatically, so restart it after
+  changing `.env`.
+- **The page is blank or not found at `http://localhost:5173/`:** use
+  `http://localhost:5173/project1/` instead.
+- **You changed `PORT` in `.env`:** the frontend expects the API server on port
+  3001 unless `VITE_API_BASE` is set — see `src/docs/CAT_API.md`.
+
+## Other commands
+
+- `npm test` — run all tests once. They do not need an API key or a running
+  server.
+- `npm run test:watch` — run the tests in watch mode.
+- `npm run lint` — run ESLint.
+- `npm run prettier:check` — check formatting (`npm run format` fixes it).
+- `npm run build` — type-check and create a production build in `dist/`.
+- `npm run preview` — serve the production build locally. The API server must
+  still be running.
+
+## Documentation
+
+More detailed guides are in [`src/docs/`](src/docs):
+
+- [`CAT_API.md`](src/docs/CAT_API.md) — the API server and its endpoints.
+- [`CAT_VIEW.md`](src/docs/CAT_VIEW.md) — the cat card, navigation hook, and
+  persisted browsing state.
+- [`BREED_DROPDOWN.md`](src/docs/BREED_DROPDOWN.md) — the breed filter
+  dropdown.
+- [`FILTER_STORAGE.md`](src/docs/FILTER_STORAGE.md) — persisting the selected
+  breed filter.
+- [`FAVORITES_STORAGE.md`](src/docs/FAVORITES_STORAGE.md) — persisting favorite
+  cats.
+- [`TESTING.md`](src/docs/TESTING.md) — how the tests work.
+- [`AI_USAGE.md`](src/docs/AI_USAGE.md) — how AI tools were used in this
+  project.