init geek calc

specs/001-build-a-single/quickstart.md

@@ -0,0 +1,64 @@
+# Quickstart: Geek Calculator
+
+## Running the Calculator
+1. Open `index.html` in any modern web browser
+2. The calculator will load with a dark terminal-themed UI
+3. Begin typing calculations or use mouse/touch to operate
+
+## Basic Operations
+- **Addition**: `5 + 3 =` → displays `8`
+- **Subtraction**: `10 - 4 =` → displays `6`
+- **Multiplication**: `6 * 7 =` → displays `42`
+- **Division**: `15 / 3 =` → displays `5`
+- **Parentheses**: `(2 + 3) * 4 =` → displays `20`
+- **Percentage**: `100 + 10% =` → displays `110`
+- **Sign Toggle**: Enter number then press `±` or `+/-` button
+
+## RPN Mode
+1. Toggle RPN mode using the RPN button
+2. Enter numbers followed by operators
+3. Example: To calculate `4 + 6`: `4 ENTER 6 +`
+4. Use `ENTER` to push numbers onto the RPN stack
+5. Available operations: `+`, `-`, `*`, `/`
+
+## Keyboard Controls
+- **Numbers**: 0-9 keys
+- **Operators**: `+`, `-`, `*`, `/` keys
+- **Equals**: `=` or `Enter` key
+- **Clear**: `Escape` or `C` key
+- **All Clear**: `Shift + C` or `Double Escape`
+- **Decimal Point**: `.` key
+- **Backspace**: `Backspace` key
+- **RPN Enter**: `Enter` key in RPN mode
+- **Toggle RPN**: `R` key
+- **Command Palette**: `@` key
+- **History**: `↑` and `↓` arrow keys
+- **Help/Shortcuts**: `?` key
+
+## Command Palette
+- Press `@` to open the command palette
+- Type commands like "clear", "history", "theme", etc.
+- Provides quick access to calculator functions
+
+## History Feature
+- Previous calculations appear in history panel
+- Use `↑` and `↓` arrow keys to navigate
+- Click on history items to re-run calculations
+- Limited to 50 most recent entries
+
+## Accessibility Features
+- Full keyboard navigation
+- ARIA labels on all controls
+- High contrast mode
+- Screen reader compatible
+- Visible focus indicators
+
+## Troubleshooting
+- If you see "Error", check your expression syntax
+- For division by zero, the result will show "Infinity"
+- If calculator doesn't respond, try clearing with `Escape`
+- For offline use, ensure service worker is enabled in your browser
+
+## Testing
+- Unit tests for core math operations: Run `tests/index.html` in browser
+- Tests cover basic arithmetic, RPN operations, and error conditions