diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4e9f12b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,73 @@
+# AGENTS.md
+
+## Project Overview
+
+This is the **Bytemalte.de** website — a portfolio/landing page showcasing open source projects by Bytemalte. It's a SvelteKit 2 app with Svelte 5 (Runes), TypeScript, and a dark theme design system.
+
+The site displays projects dynamically loaded from a static JSON file, with a hero section, project cards grid, navbar, and footer.
+
+## Key Directories & Files
+
+```
+src/
+├── app.css                          # Global styles + design system (colors, typography, spacing)
+├── app.html                         # HTML shell (fonts, meta tags)
+├── lib/
+│   ├── assets/favicon.svg           # Favicon
+│   ├── components/                  # All UI components
+│   │   ├── Hero.svelte              # Landing hero with gradient text & CTA buttons
+│   │   ├── Navbar.svelte            # Fixed navbar, transparent→solid on scroll
+│   │   ├── ProjectCard.svelte       # Single project card (image, title, desc, actions)
+│   │   ├── ProjectsSection.svelte   # Grid that fetches & renders ProjectCards
+│   │   └── Footer.svelte            # Site footer with branding & links
+│   └── index.ts                     # $lib barrel export (currently empty)
+├── routes/
+│   ├── +layout.svelte               # Root layout (imports app.css, sets favicon)
+│   └── +page.svelte                 # Single page: Navbar → Hero → ProjectsSection → Footer
+static/
+├── projects.json                    # Project data array (id, title, description, urls)
+└── robots.txt
+BYTEMALTE.md                         # Design system spec (German) — colors, typography, component rules
+```
+
+## Tech Details
+
+- **Svelte 5 Runes** — Components use `$state()`, `$props()`, `$effect()` (not legacy Svelte 4 reactivity)
+- **Scoped CSS** — Each component has its own `<style>` block, global vars in `app.css`
+- **Dynamic data** — Projects loaded client-side via `fetch("/projects.json")` in `ProjectsSection.svelte`
+- **No adapter configured** — Uses `@sveltejs/adapter-auto` (works for Vercel, Netlify, etc.)
+
+## How to Work on This
+
+### Run dev server
+```bash
+pnpm dev
+```
+
+### Add/edit projects
+Edit `static/projects.json`. Each entry needs: `id`, `title`, `description`, `image_url`, `download_url`, `code_url`. Use `"#"` for unused URLs.
+
+### Add a new page
+Create a new file under `src/routes/` (e.g., `about/+page.svelte`). SvelteKit file-based routing handles the rest.
+
+### Modify styling
+- Global design tokens → `src/app.css` (`:root` variables)
+- Component styles → `<style>` block in the respective `.svelte` file
+- Reference → `BYTEMALTE.md` (design spec, in German)
+
+### Type checking
+```bash
+pnpm check
+```
+
+### Build
+```bash
+pnpm build
+```
+
+## Important Notes
+
+- The site is a **single-page layout** — no nested routes besides the root
+- All links to code/repos point to `gitea.malxte.de/Bytemalte/*`
+- The navbar scroll effect uses `window.scrollY` — client-side only logic
+- `ProjectCard.svelte` handles broken images gracefully with a placeholder fallback
diff --git a/README.md b/README.md
index 4b462cd..88cb784 100644
--- a/README.md
+++ b/README.md
@@ -1,42 +1,99 @@
-# sv
+# Bytemalte.de
 
-Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+A modern portfolio website for Bytemalte, showcasing open source projects built with Rust and modern web technologies. Powered by [SvelteKit](https://kit.svelte.dev/) with a clean dark theme design.
 
-## Creating a project
+## Tech Stack
 
-If you're seeing this, you've probably already done this step. Congrats!
+- **Framework:** [SvelteKit 2](https://kit.svelte.dev/) with Svelte 5 (Runes)
+- **Language:** TypeScript
+- **Build Tool:** Vite 7
+- **Package Manager:** pnpm
+- **Styling:** Scoped CSS with CSS custom properties
 
-```sh
-# create a new project
-npx sv create my-app
+## Features
+
+- **Hero Section** — Gradient text, responsive layout, and call-to-action buttons
+- **Project Showcase** — Dynamically loaded from `projects.json` with card-based grid
+- **Responsive Navbar** — Transparent to solid transition on scroll
+- **Dark Theme** — Custom design system with WCAG AA compliant colors
+- **Mobile First** — Fully responsive across all screen sizes
+
+## Project Structure
+
+```
+src/
+├── lib/
+│   ├── assets/
+│   │   └── favicon.svg
+│   ├── components/
+│   │   ├── Footer.svelte
+│   │   ├── Hero.svelte
+│   │   ├── Navbar.svelte
+│   │   ├── ProjectCard.svelte
+│   │   └── ProjectsSection.svelte
+│   └── index.ts
+├── routes/
+│   ├── +layout.svelte
+│   └── +page.svelte
+├── app.css
+├── app.d.ts
+└── app.html
+static/
+├── projects.json
+└── robots.txt
 ```
 
-To recreate this project with the same configuration:
+## Getting Started
 
-```sh
-# recreate this project
-pnpm dlx sv@0.12.7 create --template minimal --types ts --install pnpm bytemalte_de_svelte
+### Prerequisites
+
+- Node.js 18+
+- pnpm
+
+### Installation
+
+```bash
+pnpm install
 ```
 
-## Developing
+### Development
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
-
-```sh
-npm run dev
-
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+```bash
+pnpm dev
 ```
 
-## Building
+Open [http://localhost:5173](http://localhost:5173) in your browser.
 
-To create a production version of your app:
+### Production Build
 
-```sh
-npm run build
+```bash
+pnpm build
 ```
 
-You can preview the production build with `npm run preview`.
+Preview the production build:
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+```bash
+pnpm preview
+```
+
+### Type Checking
+
+```bash
+pnpm check
+```
+
+## Design System
+
+The project uses a consistent design system defined in `app.css` and `BYTEMALTE.md`:
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Primary | `#8888FF` | Buttons, links, branding |
+| Secondary | `#3DDC84` | Accents, gradients |
+| Background | `#0F172A` | Page background |
+| Surface | `#1E293B` | Cards, sections |
+| Font | Inter, system-ui, sans-serif | All typography |
+
+## Links
+
+- **Code Repository:** [gitea.malxte.de/Bytemalte](https://gitea.malxte.de/Bytemalte)