diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ce7fbb8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,154 @@
+# Typing Chud
+
+A fast-paced typing game built with React and TypeScript. Type falling text before it reaches your ship!
+
+## Features
+
+- **Four Game Modes**: Letters, Words, Sentences, and Paragraphs
+- **Dynamic Mode Switching**: Change game modes at runtime for endless variety
+- **Real-time Score Tracking**: Track correct/incorrect keystrokes and deaths
+- **Visual Effects**: Laser hits, ship explosions, and perspective effects
+- **Platform Integration**: Customize speed, content, and mode switching via options
+- **Independent Content Tracking**: Each mode tracks completion separately
+
+## Installation
+
+```bash
+npm install @vimazing/typing-chud
+```
+
+## Quick Start
+
+```typescript
+import { useGame } from '@vimazing/typing-chud';
+import '@vimazing/typing-chud/game.css';
+
+function App() {
+  const game = useGame({
+    gameMode: 'letters',
+    downwardSpeed: 100,
+  });
+
+  return (
+    <div>
+      <div ref={game.containerRef} />
+      <button onClick={game.startGame}>Start</button>
+      <p>Score: {game.scoreManager.score}</p>
+    </div>
+  );
+}
+```
+
+## Game Modes
+
+### Letters
+Single characters fall one at a time. Type each letter to destroy it.
+
+### Words
+Full words fall from the top. Type each character of the word sequentially.
+
+### Sentences
+Multi-line sentences with perspective effect. Continue typing through line breaks.
+
+### Paragraphs
+4-line paragraphs with advanced perspective and smooth line transitions.
+
+## API
+
+### useGame(options?, platformHook?)
+
+Main hook for initializing the game.
+
+**Options:**
+```typescript
+type GameOptions = {
+  gameMode?: 'letters' | 'words' | 'sentences' | 'paragraphs';
+  downwardSpeed?: number; // pixels per second
+  boardDimensions?: [number, number];
+  wordList?: string[];
+}
+```
+
+**Returns:**
+```typescript
+type GameManager = {
+  containerRef: RefObject<HTMLDivElement>;
+  renderBoard: () => void;
+  gameStatus: 'waiting' | 'started' | 'game-over' | 'game-won';
+  setGameStatus: (status) => void;
+  startGame: () => void;
+  quitGame: () => void;
+  cursor: CursorManager;
+  scoreManager: ScoreManager;
+  keyLog: KeyLogEntry[];
+  clearKeyLog: () => void;
+  getKeyLog: () => KeyLogEntry[];
+  handleTypedLetter: (letter: string) => void;
+  changeGameMode: (options: GameOptions) => void;
+}
+```
+
+### Platform Hook
+
+Pass a function to `useGame` to receive game events:
+
+```typescript
+const platformHook = (gameManager: GameManager) => {
+  // Analytics, custom bindings, monitoring, etc.
+  window.addEventListener('keydown', (e) => {
+    if (e.key === 'h') showHelp();
+  });
+};
+
+const game = useGame(options, platformHook);
+```
+
+## Gameplay Controls
+
+- **Space**: Start/Restart game
+- **Esc**: Quit game
+- **A-Z, 0-9, . , ! ?**: Type characters to destroy falling text
+
+## Score Tracking
+
+Access detailed metrics via `scoreManager`:
+
+```typescript
+game.scoreManager.score         // Current score
+game.scoreManager.correct       // Correct keystrokes
+game.scoreManager.missed        // Incorrect keystrokes
+game.scoreManager.deaths        // Deaths (text hit ship)
+game.scoreManager.currentCount  // Count for current mode
+game.scoreManager.lettersCompleted
+game.scoreManager.wordsCompleted
+game.scoreManager.sentencesCompleted
+game.scoreManager.paragraphsCompleted
+```
+
+## Mode Switching
+
+Request mode changes at runtime:
+
+```typescript
+// Platform can request a mode change anytime
+game.changeGameMode({ gameMode: 'words', downwardSpeed: 75 });
+
+// Mode change applies after current text completes
+// Maintains independent completion counts per mode
+```
+
+## Example
+
+See the `/example` directory for a full implementation with:
+- Test state machines
+- Score-based and count-based transitions
+- Custom platform hook
+- Complete UI
+
+## License
+
+MIT
+
+## Author
+
+André Padez - VIMazing Project
diff --git a/package.json b/package.json
index ff357a0..732ddb0 100755
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@vimazing/typing-chud",
-  "version": "0.1.0",
-  "description": "TODO: Game description",
+  "version": "0.2.0",
+  "description": "A fast-paced typing game with dynamic mode switching. Type falling text (letters, words, sentences, paragraphs) before it reaches your ship.",
   "author": "André Padez <andre.padez@gmail.com>",
   "keywords": [
     "vim",
@@ -9,7 +9,11 @@
     "hooks",
     "game",
     "typescript",
-    "vimazing"
+    "vimazing",
+    "typing-game",
+    "typing-practice",
+    "interactive-game",
+    "mode-switching"
   ],
   "repository": {
     "type": "git",
diff --git a/src/gameInfo.ts b/src/gameInfo.ts
index c92e4c5..1807c01 100644
--- a/src/gameInfo.ts
+++ b/src/gameInfo.ts
@@ -1,36 +1,66 @@
 export const gameInfo = {
   name: 'Typing Chud',
-  description: 'TODO: Game description',
+  description: 'A fast-paced typing game where letters, words, sentences, and paragraphs fall from the top of the screen. Type to destroy them before they reach your ship. Supports dynamic mode switching for endless variety.',
 
   controls: {
-    navigation: [
-      { keys: 'hjkl', description: 'TODO: Navigation controls' },
-    ],
     game: [
-      { keys: 'Space', description: 'Start game' },
-      { keys: 'q', description: 'Quit game' },
+      { keys: 'Space', description: 'Start or restart game' },
+      { keys: 'Esc', description: 'Quit game' },
+      { keys: 'A-Z, 0-9, . , ! ?', description: 'Type characters to destroy falling text' },
     ],
   },
 
   rules: {
-    // TODO: Define game rules
+    gameplay: [
+      'Text falls from the top of the screen at increasing speeds based on game mode',
+      'Type the displayed characters to destroy them before they reach your ship',
+      'Correct keystrokes create green hits; incorrect keystrokes create red misses',
+      'Your ship explodes if text reaches it (death)',
+      'Game continues until you quit with Esc',
+    ],
+    modes: [
+      'Letters: Single characters fall one at a time',
+      'Words: Full words fall and must be typed character by character',
+      'Sentences: Multi-line sentences with perspective effect',
+      'Paragraphs: 4-line paragraphs with advanced perspective and line transitions',
+    ],
   },
 
   scoring: {
-    formula: 'TODO: Scoring formula',
+    formula: 'Base score increases with each correct keystroke, decreases with misses. Affected by mode difficulty and completion time.',
     range: '0 - 1000 points',
-    penalties: [],
-    examples: [],
+    mechanics: [
+      { metric: 'Correct', value: '+1 point per correct character' },
+      { metric: 'Incorrect', value: '-1 point per wrong character' },
+      { metric: 'Death', value: 'Ship explosion resets current text, increments death counter' },
+    ],
   },
 
   gameOver: {
     conditions: [
-      // TODO: Define game over conditions
+      { type: 'Quit', trigger: 'Press Esc during gameplay', message: 'Game paused - press Space to resume' },
     ],
   },
 
-  objective: 'TODO: Game objective',
-  winCondition: 'TODO: Win condition',
+  objective: 'Type falling text as accurately and quickly as possible while accumulating the highest score',
+  winCondition: 'Continuous play - keep going as long as you can. Higher scores indicate better typing speed and accuracy.',
+  
+  features: [
+    'Four game modes: Letters, Words, Sentences, Paragraphs',
+    'Dynamic mode switching for varied gameplay',
+    'Real-time score tracking',
+    'Color-coded feedback (green for hits, red for misses)',
+    'Laser visual effects',
+    'Ship explosion animations',
+    'Perspective effects for sentences and paragraphs',
+  ],
+
+  platformIntegration: {
+    modes: 'Platforms can request mode switches at runtime via changeGameMode()',
+    speed: 'Customize falling speed with downwardSpeed option',
+    content: 'Provide custom word lists for words/sentences/paragraphs modes',
+    tracking: 'Track completion counts per mode independently',
+  },
 } as const;
 
 export type GameInfo = typeof gameInfo;