feat: v0.0.1 release (#1)

* feat: implement v0.0.1 Spotify Pomodoro MVP

- Add Effect-based services for Spotify auth (PKCE flow), playback, and timer
- Create React components: Timer, Settings, Playlist selector, Login
- Implement configurable focus/break durations with overtime counting
- Add Web Audio notification sound when timer ends
- Disable tracer propagation to fix CORS issues with Spotify API
- Add shadcn/ui components (Card, Input, Label, Select, Slider)
- Configure HTTPS for local development (Spotify requirement)

* feat: redesign UI with lofi aesthetic

- Add warm, cozy color palette with soft purples, pinks, and sage greens
- Implement LofiTimer with integrated duration editing (click minutes to edit)
- Add VinylPlayer component with spinning record and album art
- Include duration presets, phase-based glow effects, and noise texture overlay
- Use Lexend and Space Mono fonts for distinctive typography

* feat: add light/dark theme toggle and improve layout

- Add light mode with warm paper/cream aesthetic
- Theme toggle button in top-right corner with sun/moon icons
- Much larger timer display (2-3x) using responsive clamp() sizing
- Move vinyl player below timer, now horizontal and more compact
- Add footer attribution with GitHub link to David L Bowman
- Use CSS custom properties for theme-aware colors

* refactor: streamline UI with larger elements and keyboard controls

- Consolidate into single centered App component
- Remove LofiTimer and VinylPlayer separate components
- Remove "READY", "click minutes to edit", and preset buttons
- Add keyboard controls: space/enter start/pause, r reset, s switch
- Display contextual keyboard hints below timer
- Increase timer size 50% (clamp 6-15rem)
- Increase vinyl 30% (w-14 -> w-[4.5rem])
- Increase playlist selector 30% with wider dropdown
- Footer links to spotify-pomodoro repo instead of author

* refactor: streamline UI and remove phase indicator

- Consolidate into single centered App component
- Remove LofiTimer and VinylPlayer separate components
- Remove phase indicator, presets, and verbose hints
- Add keyboard controls: space/enter start/pause, r reset, s switch
- Increase timer size 50%, vinyl 30%, playlist selector 30%
- Footer links to spotify-pomodoro repo

* style: improve light mode readability and fix timer sizing

- Darken light mode colors for better contrast and readability
- Add light mode vinyl color (warm taupe instead of dark)
- Remove blinking colon animation
- Fix button font-size inheritance so minutes/seconds match

* feat: add phase badges, Spotify shuffle/repeat, and louder notifications

- Add FOCUS/BREAK/OVERTIME badges above timer display
- Auto-enable shuffle and repeat when selecting a playlist
- Increase notification sound volume 3x for better audibility

* docs: add JSDoc comments following kavita-to-obsidian style

- Add @module, @SInCE, @category tags to all files
- Document services, schemas, errors, hooks, and components
- Use inline /** comments */ for schema fields
- Remove all non-JSDoc comments

* docs: add release documentation and CI workflow

- Update README with detailed Spotify setup instructions
- Add CONTRIBUTING.md with JSDoc and Effect-TS conventions
- Update CLAUDE.md with project structure and code conventions
- Add GitHub issue templates (bug report, feature request)
- Add CI workflow for lint and typecheck

* docs: add CHANGELOG for v0.0.1

Author: davidlbowman

.env.example

@@ -0,0 +1,4 @@
+# Spotify App Credentials
+# Create an app at https://developer.spotify.com/dashboard
+PUBLIC_SPOTIFY_CLIENT_ID=your_client_id_here
+PUBLIC_SPOTIFY_REDIRECT_URI=http://localhost:4321/callback

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- Browser: [e.g., Chrome 120]
+- OS: [e.g., Windows 11]
+- Spotify account type: [Free/Premium]
+
+## Screenshots
+
+If applicable, add screenshots.
+
+## Additional Context
+
+Any other relevant information.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+Describe the problem or limitation you're facing.
+
+## Proposed Solution
+
+Describe what you'd like to happen.
+
+## Alternatives Considered
+
+Any alternative solutions you've considered.
+
+## Additional Context
+
+Any other relevant information or screenshots.

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Typecheck
+        run: bun run typecheck

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2025-12-07
+
+### Added
+
+- Pomodoro timer with configurable focus and break durations
+- Overtime mode - timer counts up after completion so you decide when to take a break
+- Spotify OAuth integration (PKCE flow)
+- Playlist selection with auto-shuffle and repeat
+- Phase badges (FOCUS/BREAK/OVERTIME) above timer display
+- Light/dark theme toggle
+- Keyboard controls (Space/Enter to start/pause, R to reset, S to switch phase)
+- Audio notification when timer ends
+- Lofi aesthetic UI design
+
+### Technical
+
+- Built with Astro, React, Tailwind CSS v4, and shadcn/ui
+- State management with Effect-TS services
+- Spotify Web API integration for playback control
+- JSDoc documentation throughout codebase

CLAUDE.md

@@ -1,32 +1,89 @@
 # Spotify Pomodoro
 
-A Spotify-integrated pomodoro timer app.
+A Spotify-integrated pomodoro timer app with a lofi aesthetic.
 
 ## Tech Stack
 
 - **Runtime**: Bun
 - **Framework**: Astro with React
 - **Styling**: Tailwind CSS v4 + shadcn/ui
+- **State Management**: Effect-TS
 - **Linting/Formatting**: Biome
 
 ## Commands
 
-- `bun run dev` - Start development server
-- `bun run build` - Build for production
-- `bun run preview` - Preview production build
-- `bun run lint` - Check linting
-- `bun run lint:fix` - Fix linting issues
-- `bun run typecheck` - Run type checking
+| Command | Description |
+|---------|-------------|
+| `bun run dev` | Start development server |
+| `bun run build` | Build for production |
+| `bun run preview` | Preview production build |
+| `bun run lint` | Check linting |
+| `bun run lint:fix` | Fix linting issues |
+| `bun run typecheck` | Run type checking |
 
 ## Project Structure
 
-- `src/pages/` - Astro pages
-- `src/components/ui/` - shadcn/ui components
-- `src/styles/` - Global CSS with Tailwind
-- `src/lib/` - Utility functions
+```
+src/
+├── pages/              # Astro pages
+├── components/         # React components
+│   └── ui/             # shadcn/ui components
+├── hooks/              # React hooks (useTimer, useSpotify)
+├── effect/
+│   ├── services/       # Effect services (Timer, SpotifyClient, etc.)
+│   ├── schema/         # Effect Schema definitions
+│   └── errors/         # Tagged error types
+├── lib/                # Utility functions
+└── styles/             # Global CSS with Tailwind
+```
 
-## Notes
+## Code Conventions
+
+### Comments
+
+**Use JSDoc only.** No inline comments (`//`) or block comments (`/* */`).
+
+```typescript
+/**
+ * Service description.
+ * @since 0.0.1
+ * @category Services
+ */
+export class MyService extends Effect.Service<MyService>()("MyService", {
+  // ...
+}) {}
+```
+
+Required JSDoc tags:
+- `@module` at file level
+- `@since` version tag on all exports
+- `@category` to group related exports (Services, Errors, Schemas, Components, Hooks)
+
+### Effect-TS Services
+
+All services use `Effect.Service` pattern:
+- Include `accessors: true` (except config services using `sync`)
+- Declare dependencies explicitly in `dependencies` array
+- Use `Schema.TaggedError` for error types
+
+### Imports
 
 - Use `@/` path alias for imports from `src/`
+- Group imports: effect libs, third-party, local
+
+### Astro/React
+
 - React components need `client:load` directive in Astro for interactivity
+- Keep components focused and composable
+
+## Environment Variables
+
+Required for Spotify integration:
+- `PUBLIC_SPOTIFY_CLIENT_ID` - Spotify app client ID
+- `PUBLIC_SPOTIFY_REDIRECT_URI` - OAuth callback URL
+
+## Notes
+
 - Biome is configured to skip Tailwind CSS files (global.css)
+- Timer uses countdown then overtime behavior (counts up after hitting zero)
+- Spotify playback requires an active device