Add README.md and AGENTS.md documentation

- README: installation, dev server, gameplay controls, screens, sound
- AGENTS.md: project structure, stack, implementation patterns, git workflow

AGENTS.md

@@ -0,0 +1,71 @@
+# Working in The Clanked Game
+
+## Stack
+
+- **React 19** — UI rendering
+- **Vite 8** — Dev server and build tooling
+- **WebAudio API** — All sound synthesis (no audio files)
+- **pnpm** — Package manager
+
+## Project Layout
+
+```
+src/
+  App.jsx          — Root component, screen state (home/main-menu/game)
+  components/
+    Game.jsx       — Core game loop: canvas rendering, state, collision, input
+  soundEffects.js  — WebAudio sound synthesis functions
+```
+
+## Key Implementation Notes
+
+- The game loop runs in `Game.jsx` via `requestAnimationFrame`. All game logic (`updateStars`, `updatePlayer`, `updateAliens`, `checkCollisions`, etc.) is defined inside the `useEffect` and operates on `gameStateRef.current`.
+- Sound effects use the WebAudio API and are stateless helpers in `soundEffects.js`. Call `getAudioContext()` lazily on first use (browser autoplay policy).
+- Shields are stored as 2D boolean grids (pixel-level destruction without canvas complexity).
+- The canvas renders at **800×600** (`CANVAS_WIDTH`, `CANVAS_HEIGHT`).
+
+## Adding Sound Effects
+
+Functions in `soundEffects.js` follow the same pattern:
+
+```js
+export const playXSound = () => {
+  const ctx = getAudioContext();
+  const currentTime = ctx.currentTime;
+
+  const oscillator = ctx.createOscillator();
+  const gainNode = ctx.createGain();
+
+  oscillator.type = 'square'; // or 'sine', 'sawtooth', or white noise via AudioBuffer
+  // configure frequency...
+  // configure gain envelope...
+  oscillator.connect(gainNode);
+  gainNode.connect(ctx.destination);
+
+  oscillator.start(currentTime);
+  oscillator.stop(currentTime + duration);
+};
+```
+
+For white noise, create an `AudioBuffer` filled with `Math.random() * 2 - 1` values and use a `BufferSourceNode`.
+
+## Adding Gameplay Features
+
+- New game state fields go in `gameStateRef.current` (line ~95).
+- New per-frame update functions follow `updateStars`, `updatePlayer`, etc. pattern and are called in the game loop in order.
+- New draw functions follow `drawStars`, `drawPlayer`, etc. pattern and are called in the render section of `gameLoop()`.
+- Screen transitions happen via `setCurrentScreen()` in `App.jsx` — pass an `onExit` callback from `Game` to return to main menu.
+
+## Git Workflow
+
+- Branch: `develop`
+- Push to `origin/develop` after meaningful changes.
+
+## npm Scripts
+
+| Command | Description |
+|---------|-------------|
+| `pnpm dev` | Start Vite dev server with HMR |
+| `pnpm build` | Production build to `dist/` |
+| `pnpm lint` | Run ESLint |
+| `pnpm preview` | Preview production build locally |

README.md

@@ -1,16 +1,49 @@
-# React + Vite
+# The Clanked Game
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+A Space Invaders-inspired browser game built with React and Vite.
 
-Currently, two official plugins are available:
+## Installation
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+```bash
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+pnpm install
+```
 
-## React Compiler
+## Development
 
-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).
+```bash
+pnpm dev
+```
 
-## Expanding the ESLint configuration
+Runs the Vite dev server. Open the URL shown in your terminal (typically http://localhost:5173/).
 
-If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.
+## Gameplay
+
+### Controls
+
+| Key | Action |
+|-----|--------|
+| Arrow Left / A | Move left |
+| Arrow Right / D | Move right |
+| Space | Fire missile |
+| Escape | Pause / Resume |
+
+### Objective
+
+Destroy all waves of aliens before they reach your position or deplete your lives.
+
+- **Green aliens** (bottom rows): 10 points
+- **Yellow aliens** (middle rows): 20 points  
+- **Red aliens** (top rows): 30 points
+
+### Screens
+
+- **Home** — Landing screen with "Main Menu" button
+- **Main Menu** — Access "Start New Game" and "Options" (Options not yet implemented)
+- **Game** — Canvas-based gameplay with HUD showing Score, Lives, and Round
+- **Pause** — Overlay when Escape is pressed; press Escape again to resume
+
+### Sound
+
+Aliens play the classic four-note descending march throughout gameplay. The tempo accelerates as you destroy more aliens, matching the original 1978 arcade experience. Player fire and alien hits also produce synthesized sound effects.
+
+Lose a life → Game Over → Return to Main Menu or start a New Game.