docs: completely rewrite README for debugging lab experience

- Transform README into engaging debugging dojo introduction
- Add categorized bug sections (API Issues, UI/UX Bugs, State & Lifecycle, Type Safety)
- Include real bugs found during development with potential causes and consequences
- Add intentional debugging challenges with specific learning goals
- Implement 'How to Think Like a Debugger' section with practical advice
- Add hidden challenge for extra discovery motivation
- Merge related bugs (No Debounce + Overeager Search) for better organization
- Improve narrative flow in UI/UX bug descriptions
- Add learning goal about explaining fixes to others
- Remove formal documentation style in favor of engaging, hands-on lab tone
- Focus on debugging practice rather than production app documentation

README.md

@@ -1,112 +1,109 @@
-# Pokémon Explorer App
+# Pokémon Explorer: Your Frontend Debugging Dojo
 
-A Vite + React + TypeScript application that allows users to search for Pokémon and view their details using the PokeAPI.
+Welcome to the chaos lab where we intentionally break things so you can learn to fix them. This isn't your typical React app—it's a carefully crafted debugging playground designed to sharpen your frontend problem-solving skills.
 
-## Features
+Built with Vite + React + TypeScript, Ant Design, and Atomic Design principles, this app fetches Pokémon data from the PokeAPI. But here's the catch: it's riddled with bugs, both real and intentional, waiting for you to discover and understand.
 
-- Search for Pokémon by name with autocomplete suggestions
+## Bugs (Challenges)
-- Display Pokémon details including:
-  - Name and image
-  - Types
-  - Base stats with progress bars
-  - Height and weight
-- Modern UI built with Ant Design
-- Atomic Design architecture
-- Centralized state management with Zustand
-- API layer with axios for data fetching
 
-## Project Structure
+Your mission: identify them, understand their root causes, and document your findings. There may be one bug we didn't list. If you find it, we owe you bragging rights.
 
-```
+### API Issues
-src/
+- [ ] **Limited Pokémon Access**: Only the first 150 Pokémon load, even though 1300+ exist
-├── api/                # API layer with axios
+  - *Potential cause: API pagination logic or data fetching limits*
-│   ├── config.ts       # Axios configuration
+  - *Consequence: Users miss out on most of the Pokémon universe*
-│   ├── get/            # GET requests
-│   ├── post/           # POST requests
-│   ├── put/            # PUT requests
-│   ├── delete/         # DELETE requests
-│   └── index.ts        # API exports
-├── components/
-│   ├── atoms/          # Basic UI elements (Input, Button, AutoComplete)
-│   ├── molecules/      # Combinations (SearchBar)
-│   ├── organisms/      # Complex components (PokemonDetails)
-│   ├── templates/      # Layout structure (MainLayout)
-│   └── pages/          # Route-level views (Home)
-├── stores/             # Zustand state management
-│   ├── pokemonStore.ts # Pokémon state store
-│   └── index.ts        # Store exports
-├── styles/             # SCSS modules
-│   ├── global.module.scss  # Global styles
-│   ├── app.module.scss     # App-specific styles
-│   └── index.ts            # Style exports
-└── types/              # TypeScript type definitions
-```
 
-## Path Aliases
+- [ ] **Duplicate API Calls**: The app hits the API twice on initial load
+  - *Potential cause: Multiple useEffect hooks or component re-renders*
+  - *Consequence: Unnecessary network traffic and potential rate limiting*
 
-The project uses path aliases for cleaner imports:
+- [ ] **No Debounce + Overeager Search**: API calls trigger on every keystroke instead of waiting for user action (search button or autocomplete selection)
+  - *Potential cause: Missing debounce implementation + autocomplete calling API on input change instead of user selection*
+  - *Consequence: Massive API abuse, poor performance, and potential rate limiting*
 
-- `@/` - Points to `src/`
+### UI/UX Bugs
-- `@components/` - Points to `src/components/`
+- [ ] **Random Error Messages**: Failed searches show confusing, unhelpful messages
-- `@styles/` - Points to `src/styles/`
+  - *Potential cause: Generic error handling or incorrect error mapping*
-- `@pokemonTypes/` - Points to `src/types/`
+  - *Consequence: Poor user experience and debugging confusion*
-- `@api/` - Points to `src/api/`
-- `@stores/` - Points to `src/stores/`
 
-Example usage:
+- [ ] **Silent 404 Failures**: Search for a non-existent Pokémon and watch... nothing happen
-```typescript
+  - *Debugging angle: Error handling, API response processing, state management*
-// Instead of: import { PokemonInput } from '../../components/atoms/PokemonInput';
+  - *Learning goal: Understand how to catch and handle API errors gracefully*
-import { PokemonInput } from '@components/atoms/PokemonInput';
 
-// Instead of: import styles from '../../styles/app.module.scss';
+- [ ] **UI Flicker**: Search for a new Pokémon and see the old one flash briefly
-import styles from '@styles/app.module.scss';
+  - *Debugging angle: Component lifecycle, state transitions, loading states*
+  - *Learning goal: Master the art of smooth UI transitions*
 
-// Instead of: import { getPokemon } from '../../api/get/pokemon';
+### State & Lifecycle
-import { getPokemon } from '@api/get/pokemon';
+- [ ] **Stat Swapping**: Speed and defense stats are mysteriously swapped
+  - *Debugging angle: Data transformation, mapping logic, API response structure*
+  - *Learning goal: Trace data flow from API to UI display*
 
-// Instead of: import { usePokemonStore } from '../../stores/pokemonStore';
+### Type Safety Problems
-import { usePokemonStore } from '@stores/pokemonStore';
+- [ ] **TypeScript Assumptions**: The app assumes optional fields are always present
-```
+  - *Debugging angle: Type definitions, runtime safety, optional chaining*
+  - *Learning goal: Bridge the gap between TypeScript types and runtime reality*
 
-## Intentional Bugs (For Debugging Session)
+## How to Think Like a Debugger
 
-⚠️ **These bugs are intentionally left in the code for debugging practice:**
+### Sharp Practices for Faster Debugging
 
-1. **Silent Failure**: When a Pokémon doesn't exist, no error message is shown - the app silently fails
+**Start with the obvious, not the exotic**
-2. **UI Flickering**: When searching for a new Pokémon, the previous data briefly disappears causing a flicker effect
+- Check the console first. Seriously. Most bugs announce themselves loudly.
-3. **Incorrect Stat Mapping**: Speed and defense stats are swapped in the display
-4. **TypeScript Error**: The `height` field is assumed to always be present when it's actually optional in the API
 
-## Getting Started
+**Reproduce the bug three different ways**
+- If you can't trigger it consistently, you're probably debugging the wrong thing.
+
+**Narrate your debugging process out loud**
+- Your brain catches flawed assumptions when you have to explain them to someone (even if that someone is your rubber duck).
+
+**Debug without logs first**
+- Force yourself to trace the code manually. It builds mental models faster than console.log ever will.
+
+**Question your debugging tools**
+- Don't just use the debugger—understand why it's showing you what it's showing you.
+
+**Keep a debugging journal**
+- Write down your false leads and dead ends. Pattern recognition is your superpower.
+
+## Quick Start
+
+Clone the repo, install dependencies, and fire up the dev server.
 
-1. Install dependencies:
 ```bash
 npm install
-   ```
-
-2. Start the development server:
-   ```bash
 npm run dev
 ```
 
-3. Open your browser and navigate to the URL shown in the terminal
+Open http://localhost:5173 and start breaking things (or rather, finding what's already broken).
 
-## Usage
+## Directory Overview
 
-1. Enter a Pokémon name in the search bar (e.g., "pikachu", "charizard", "bulbasaur")
+```
-2. Click "Search" or press Enter
+src/
-3. View the Pokémon's details including stats, types, and image
+├── api/                # Axios setup and API calls
+├── components/         # Atomic Design structure
+│   ├── atoms/         # Basic UI elements
+│   ├── molecules/     # Component combinations
+│   ├── organisms/     # Complex components
+│   ├── templates/     # Layout structure
+│   └── pages/         # Route-level views
+├── stores/            # Zustand state management
+├── styles/            # SCSS modules
+└── types/             # TypeScript definitions
+```
 
-## Technologies Used
+## Learning Goals
 
-- **Vite** - Build tool and dev server
+By the time you're done with this app, you should be able to:
-- **React** - UI framework
-- **TypeScript** - Type safety
-- **Ant Design** - UI component library
-- **PokeAPI** - Pokémon data source
 
-## Available Scripts
+- **Spot the difference** between real bugs and intentional ones
+- **Trace data flow** from API response to UI display
+- **Debug state management** issues in complex React applications
+- **Handle API errors** gracefully and informatively
+- **Optimize performance** by identifying unnecessary re-renders and API calls
+- **Think systematically** about debugging instead of guessing
+- **Document your debugging process** for future reference
+- **Explain your fix to someone else** to test if you truly understand it
 
-- `npm run dev` - Start development server
+Remember: The goal isn't to fix everything perfectly. It's to build the debugging instincts that will serve you in real-world development. Happy hunting!
-- `npm run build` - Build for production
-- `npm run preview` - Preview production build