Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>

AGENTS.md

@@ -486,36 +486,12 @@ Color.Primary.background
 
 ## Documentation instructions
 
-### Reference documentation before starting work
+- **Always keep documentation up to date** when adding new functionality or making changes that users or developers need to know about.
-
-Before implementing features or making changes, **always read the following files** for context:
-
-- **`README.md`**: User-facing documentation with features, usage instructions, and known limitations
-- **`AI_IMPLEMENTATION.md`**: Technical implementation guide with architecture patterns, code examples, and troubleshooting
-
-These files contain important context about existing patterns, workarounds, and design decisions that should inform your implementation.
-
-### Keep documentation up to date
-
-- **Always update `README.md`** when adding user-facing features, changing usage patterns, or discovering new limitations.
-- **Always update `AI_IMPLEMENTATION.md`** when:
-  - Adding new architectural patterns or components
-  - Implementing workarounds for library limitations
-  - Adding new troubleshooting guidance
-  - Changing how features are implemented
 - Document new features, settings, or behaviors in the appropriate documentation files.
 - Update documentation when modifying existing behavior.
 - Include any configuration options, keyboard shortcuts, or special interactions.
 - Documentation updates should be part of the same commit as the feature/change they document.
 
-### Documentation checklist
-
-When completing a task, verify:
-- [ ] `README.md` reflects any user-facing changes
-- [ ] `AI_IMPLEMENTATION.md` reflects any implementation changes
-- [ ] New workarounds or patterns are documented for future reference
-- [ ] Known limitations are listed if discovered
-
 
 ## PR instructions
 

AI_Implementation.md

@@ -0,0 +1,68 @@
+# AI_Implementation.md
+
+## How This App Was Architected & Built
+
+This project was developed following strict senior-level iOS engineering standards, with guidance from an AI assistant (Grok) acting as a Senior iOS Engineer specializing in SwiftUI and modern Apple frameworks.
+
+### Guiding Principles (from AGENTS.md)
+- **Protocol-Oriented Programming (POP) first**: All shared capabilities defined via protocols before concrete types
+- **MVVM-lite**: Views are "dumb" — all logic lives in `@Observable` view models
+- **No third-party dependencies**: Pure Apple frameworks only (SwiftUI, AVFoundation, StoreKit 2, CoreImage)
+- **No magic numbers**: All dimensions, opacities, durations from centralized `Design` constants
+- **Full accessibility**: Dynamic Type, VoiceOver labels/hints/traits/announcements
+- **Modern Swift & SwiftUI**: Swift 6 concurrency, `@MainActor`, `foregroundStyle`, `clipShape(.rect)`, `NavigationStack`
+- **Testable & reusable design**: Protocols enable mocking and future SPM package extraction
+
+### Architecture Overview
+
+Shared/
+├── DesignConstants.swift             → Semantic design tokens (spacing, radii, sizes, etc.)
+├── Color+Extensions.swift            → Ring light color presets
+├── Protocols/
+│   ├── RingLightConfigurable.swift   → Border, color, brightness, mirror, smoothing
+│   ├── CaptureControlling.swift      → Timer, grid, zoom, capture mode
+│   └── PremiumManaging.swift         → Subscription state & purchase handling
+└── Premium/
+└── PremiumManager.swift          → Native StoreKit 2 implementation
+Features/
+├── Camera/                           → Main UI, preview, capture logic
+├── Settings/                         → Configuration screens
+└── Paywall/                          → Pro subscription flow
+
+
+### Key Implementation Decisions
+
+1. **Ring Light Effect**
+   - Achieved by coloring the safe area background and leaving a centered rectangular window for camera preview
+   - Border width controlled via user setting
+   - Gradient support added for directional "portrait lighting"
+
+2. **Camera System**
+   - `AVCaptureSession` with front camera default
+   - `UIViewRepresentable` wrapper for preview with pinch-to-zoom
+   - Video data output delegate for future real-time filters (skin smoothing placeholder)
+
+3. **Capture Enhancements**
+   - Timer with async countdown and accessibility announcements
+   - Volume button observation via KVO on `AVAudioSession.outputVolume`
+   - Flash burst: temporarily sets brightness to 1.0 on capture
+
+4. **Freemium Model**
+   - Built with pure StoreKit 2 (no RevenueCat)
+   - `PremiumManaging` protocol enables easy testing/mocking
+   - Clean paywall with benefit list and native purchase flow
+
+5. **Reusability Focus**
+   - All shared logic extracted to protocols
+   - Ready for future extraction into SPM packages:
+     - `SelfieCameraKit`
+     - `SelfieRingLightKit`
+     - `SelfiePremiumKit`
+
+### Development Process
+- Iterative feature additions guided by competitive analysis of top App Store selfie apps
+- Each new capability (timer, boomerang, gradient, subscriptions) added with protocol-first design
+- Strict adherence to no magic numbers, full accessibility, and clean separation
+- Final structure optimized for maintainability and future library extraction
+
+This app demonstrates production-quality SwiftUI architecture while delivering a delightful, competitive user experience.

README.md

@@ -0,0 +1,139 @@
+# SelfieRingLight
+
+A modern, professional-grade selfie camera app for iOS that simulates a high-quality ring light using the device's screen. Built entirely with SwiftUI, Swift 6, and AVFoundation.
+
+Perfect for low-light selfies, video calls, makeup checks, or professional portrait lighting on the go.
+
+## Features
+
+### Core Camera & Lighting
+- Full-screen front-camera preview with true mirror option
+- Configurable **screen-based ring light** with adjustable border thickness
+- Multiple color temperature presets (Pure White, Warm Cream, Ice Blue, Rose Pink, etc.)
+- **Directional gradient lighting** for flattering portrait effects
+- Real-time screen brightness control (overrides system brightness while in use)
+- Flash burst on capture for extra fill light
+
+### Capture Modes
+- Photo capture (saved to Photo Library)
+- Video recording
+- **Boomerang** mode (3-second looping short video)
+- 3-second and 10-second self-timer with countdown overlay and VoiceOver announcements
+- Pinch-to-zoom gesture
+- Volume button shutter support (photo or video start/stop)
+- Rule-of-thirds grid overlay (toggleable)
+
+### Premium Features (Freemium Model)
+- All advanced color presets + custom colors
+- Gradient and directional lighting
+- Advanced beauty filters (coming soon)
+- Unlimited boomerang length
+- No watermarks
+- Ad-free experience
+
+### Accessibility & Polish
+- Full VoiceOver support with meaningful labels, hints, and announcements
+- Dynamic Type and ScaledMetric for readable text
+- String Catalog localization ready (`.xcstrings`)
+- Prevents screen dimming during use
+- Restores original brightness on background/app close
+
+## Screenshots
+*(Add App Store-ready screenshots here once built)*
+
+## Requirements
+- iOS 18.0 or later
+- Xcode 16+
+- Swift 6 language mode
+
+## Setup
+
+### 1. Clone the Repository
+```bash
+git clone https://github.com/yourusername/SelfieRingLight.git
+cd SelfieRingLight
+```
+
+### 2. Configure API Keys
+
+This project uses `.xcconfig` files to securely manage API keys. **Never commit your actual API keys to version control.**
+
+1. Copy the template file:
+   ```bash
+   cp SelfieRingLight/Configuration/Secrets.xcconfig.template SelfieRingLight/Configuration/Secrets.xcconfig
+   ```
+
+2. Edit `Secrets.xcconfig` with your actual API key:
+   ```
+   REVENUECAT_API_KEY = appl_your_actual_api_key_here
+   ```
+
+3. The `Secrets.xcconfig` file is gitignored and will never be committed.
+
+### 3. RevenueCat Setup
+
+1. Create an account at [RevenueCat](https://www.revenuecat.com)
+2. Create a new project and connect it to App Store Connect
+3. Create products in App Store Connect (e.g., `com.yourapp.pro.monthly`, `com.yourapp.pro.yearly`)
+4. Configure the products in RevenueCat dashboard
+5. Create an entitlement named `pro`
+6. Create an offering with your subscription packages
+7. Copy your **Public App-Specific API Key** to `Secrets.xcconfig`
+
+### 4. Debug Premium Mode
+
+To test premium features without a real subscription during development:
+
+1. Edit Scheme (⌘⇧<) → Run → Arguments
+2. Add Environment Variable:
+   - **Name:** `ENABLE_DEBUG_PREMIUM`
+   - **Value:** `1`
+
+This unlocks all premium features in DEBUG builds only.
+
+### 5. CI/CD Configuration
+
+For automated builds, set the `REVENUECAT_API_KEY` environment variable in your CI/CD system:
+
+**GitHub Actions:**
+```yaml
+env:
+  REVENUECAT_API_KEY: ${{ secrets.REVENUECAT_API_KEY }}
+```
+
+**Xcode Cloud:**
+Add `REVENUECAT_API_KEY` as a secret in your Xcode Cloud workflow.
+
+## Privacy
+- Camera access required for preview and capture
+- Photo Library access required to save photos/videos
+- Microphone access required for video recording
+- No data collection, no analytics, no tracking
+
+## Monetization
+Freemium model with optional "Pro" subscription:
+- Free: Basic ring light, standard colors, photo/video, timer, zoom
+- Pro: Full color palette, gradients, advanced features, future updates
+
+Implemented with RevenueCat for reliable subscription management.
+
+## Project Structure
+
+```
+SelfieRingLight/
+├── App/                          # App entry point
+├── Features/
+│   ├── Camera/                   # Camera preview, capture, view model
+│   ├── Paywall/                  # Pro subscription flow
+│   └── Settings/                 # Configuration screens
+├── Shared/
+│   ├── Configuration/            # xcconfig files (API keys)
+│   ├── Premium/                  # PremiumManager (RevenueCat)
+│   ├── Protocols/                # Shared protocols
+│   ├── Color+Extensions.swift    # Ring light color presets
+│   └── DesignConstants.swift     # Design tokens
+└── Resources/                    # Assets, localization
+```
+
+## License
+*(Add your license here)*