npm - agentvibes - Versions diffs - 2.12.7 → 2.12.8 - Mend

agentvibes 2.12.7 → 2.12.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (420) hide show

package/docs/stargazer-cms-prd.md DELETED Viewed

@@ -1,1918 +0,0 @@
-# AgentVibes Stargazer CMS - Product Requirements Document (PRD)
-**Version**: 1.1
-**Project**: AgentVibes Stargazer Content Management System
-**Repository**: agentvibes-stargazers (Private)
-**Created**: 2025-01-10
-**Author**: John (PM Agent) with Paul Preibisch
----
-## Goals and Background Context
-### Goals
-- Enable efficient outreach to GitHub stargazers with personalized thank-you emails and feedback requests
-- Track all stargazer interactions, contact status, and engagement history in a centralized system
-- Automate GitHub stargazer synchronization with manual, scheduled (daily cron), and real-time webhook options
-- Provide geographic visualization of stargazer distribution for analytics insights
-- Maintain clean, modular, AI-optimized codebase following strict single-responsibility principles with SonarQube quality gates
-- Support local PostgreSQL deployment with automated daily backups and Docker-based infrastructure
-- Integrate SpaceMail API for semi-automated email workflows with approval-based sending and scheduled follow-ups
-- Enable optional PiperTTS notifications for real-time stargazer events (plugin-based, toggleable with quiet hours)
-### Background Context
-The AgentVibes project has attracted GitHub stargazers, representing potential users, contributors, and community members. Currently, there's no systematic way to thank these supporters or gather valuable feedback from them.
-This PRD defines a comprehensive Stargazer Content Management System (CMS) that will:
-1. **Solve the outreach problem**: Provide a professional interface to manage stargazer relationships, compose personalized emails, and track engagement
-2. **Prevent spam issues**: Implement SpaceMail API integration with proper authentication (SPF, DKIM, DMARC), rate limiting (max 10/hour), and approval workflows
-3. **Maintain code quality**: Enforce strict AI-optimized documentation standards from `/home/fire/claude/AgentVibes/docs/ai-optimized-documentation-standards.md`, single-responsibility principles, and automated SonarQube quality gates
-4. **Enable data-driven decisions**: Offer geographic visualization (integrated Track-Stargazers map) and analytics to understand community distribution
-The system will be deployed locally using Docker Compose with management scripts matching the SoraSage pattern (`up`, `down`, `restart`, `health`, `logs`), with a separate private GitHub repository (`agentvibes-stargazers`) to protect sensitive stargazer data and email credentials.
-### Change Log
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| 2025-01-10 | 1.0 | Initial PRD creation | John (PM Agent) |
-| 2025-01-10 | 1.1 | Updated to use Kysely instead of Prisma | John (PM Agent) |
----
-## Requirements
-### Functional Requirements
-**FR1**: System shall fetch stargazer data from GitHub API using Octokit, including username, email (if public), name, avatar URL, bio, company, location, and starred timestamp
-**FR2**: System shall display stargazers in a TanStack Table with columns: username, email, starred date, contact status, last contacted date, and action buttons
-**FR3**: System shall allow filtering stargazers by contact status (contacted/not contacted), date range, location/country, and text search
-**FR4**: System shall provide individual stargazer profile view showing: GitHub username, name, email, avatar, bio, company, location, country, starred timestamp, contact history, and notes
-**FR5**: System shall support CRUD operations for email templates with template name, subject, body, and variable placeholders ({{name}}, {{username}}, {{repo}})
-**FR6**: System shall compose draft emails using selected template with variable substitution for specific stargazers
-**FR7**: System shall integrate SpaceMail API to send emails with semi-automated workflow requiring user approval before sending
-**FR8**: System shall support scheduling follow-up emails based on engagement status (no reply after X days)
-**FR9**: System shall open default email client with pre-filled template via `mailto:` links as fallback option
-**FR10**: System shall track email send history including: template used, sent timestamp, approval timestamp, status (draft/pending_approval/sent/failed)
-**FR11**: System shall synchronize GitHub stargazers via three methods: manual trigger (UI button), scheduled cron job (daily at 9am), and GitHub webhook (real-time)
-**FR12**: System shall display geographic map visualization of stargazers using integrated Track-Stargazers library (tab in UI)
-**FR13**: System shall perform automated database backups daily at 2am with 7-day retention policy
-**FR14**: System shall provide Docker management scripts: `up` (start), `down` (stop), `restart` (restart services), `health` (check service status), `logs` (view colored logs)
-**FR15**: System shall optionally trigger PiperTTS notifications when new stargazers are detected (configurable with quiet hours 22:00-08:00)
-**FR16**: System shall log all sync operations (manual/cron/webhook) with sync type, status, new stargazer count, and errors
-**FR17**: System shall prevent duplicate stargazers using GitHub ID as unique identifier
-**FR18**: System shall allow bulk selection of stargazers for batch email operations
-**FR19**: System shall provide sidebar navigation with sections: Stargazers (table view), Templates (CRUD), Map (visualization), Settings
-**FR20**: System shall use Chakra UI v2 for consistent, accessible component styling throughout the application
-### Non-Functional Requirements
-**NFR1**: All code shall follow AI-optimized documentation standards defined in `/home/fire/claude/AgentVibes/docs/ai-optimized-documentation-standards.md` including file-level context headers, comprehensive function documentation, AI notes, and cross-reference maps
-**NFR2**: All source files shall be max 200 lines; functions shall be max 50 lines to enforce single-responsibility principle
-**NFR3**: No monolithic files permitted; all code shall be componentized with clear separation of concerns
-**NFR4**: All code shall pass SonarQube quality gates: Code Coverage ≥70%, Duplicated Lines ≤3%, Maintainability Rating A, Cognitive Complexity ≤15 per function, Cyclomatic Complexity ≤10 per function
-**NFR5**: Frontend shall use Vite + React (NOT Next.js) for fast dev server and instant HMR
-**NFR6**: Backend shall use Node.js/Express with TypeScript in strict mode for type safety
-**NFR7**: Database shall use PostgreSQL 16 with Kysely query builder for type-safe database access and manual migration control
-**NFR8**: All services shall run in Docker containers orchestrated by Docker Compose
-**NFR9**: Email sending shall implement anti-spam measures: SPF/DKIM/DMARC authentication, rate limiting (max 10 emails/hour), personalized content, unsubscribe links, gradual warmup
-**NFR10**: System shall store sensitive data (API keys, email credentials) in environment variables, never committed to version control
-**NFR11**: Application shall render quickly with optimal performance (Vite chosen over Next.js for faster load times)
-**NFR12**: All Docker health checks shall complete within 10 seconds with 5 retries
-**NFR13**: Database backups shall complete within 60 seconds and verify successful creation
-**NFR14**: Pre-commit hooks shall run ESLint, TypeScript type-check, SonarQube scan, and unit tests before allowing commits
-**NFR15**: System shall handle GitHub API rate limiting gracefully with exponential backoff and user notifications
----
-## User Interface Design Goals
-### Overall UX Vision
-Clean, efficient content management interface focused on rapid stargazer outreach workflow. Primary user journey: View stargazers → Select individuals → Compose personalized email → Approve and send → Track engagement. Secondary analytics view provides geographic insights via interactive map.
-### Key Interaction Paradigms
-- **Table-centric workflow**: TanStack Table as primary interaction surface with inline actions, sorting, filtering, and bulk selection
-- **Approval-based email flow**: Draft → Preview → Approve → Send (semi-automated, prevents accidental sends)
-- **Template-driven composition**: Reusable templates with variable substitution reduce repetitive writing
-- **Real-time sync feedback**: Toast notifications and progress indicators for GitHub sync operations
-### Core Screens and Views
-1. **Stargazers Table** (Main Screen)
-   - TanStack Table with columns: Avatar, Username, Email, Starred Date, Contact Status, Actions
-   - Filters: Contact status, date range, location, text search
-   - Bulk actions: Select multiple → Compose email
-   - Inline actions: View profile, Send email, Add notes
-2. **Stargazer Profile Modal**
-   - Left panel: Avatar, GitHub link, bio, company, location
-   - Right panel: Contact history timeline, notes textarea
-   - Actions: Send email, Edit notes, View on GitHub
-3. **Email Templates Screen**
-   - Template list (sidebar): Name, subject preview, last used date
-   - Template editor: Name, subject, body textarea with variable hints
-   - Preview mode: Render template with sample data
-   - CRUD operations: Create, Edit, Delete, Duplicate
-4. **Email Composer Modal**
-   - Template selector dropdown
-   - Rendered email preview with substituted variables
-   - Recipient list (for bulk sends)
-   - Schedule options: Send now, Schedule for later
-   - Approval button (sends to SpaceMail API)
-5. **Geographic Map Tab**
-   - Integrated Track-Stargazers interactive world map
-   - Stargazer distribution by country
-   - Hover tooltips with country names and counts
-   - Filter map by contact status
-6. **Settings Screen**
-   - GitHub sync configuration: Auto-sync enabled, webhook URL
-   - SpaceMail API credentials
-   - PiperTTS settings: Enabled, quiet hours
-   - Backup schedule configuration
-### Accessibility
-WCAG AA compliance required:
-- Keyboard navigation for all interactive elements
-- ARIA labels for screen readers
-- Sufficient color contrast ratios (Chakra UI default theme compliant)
-- Focus indicators on all focusable elements
-### Branding
-Minimal, professional aesthetic matching AgentVibes brand:
-- Color palette: Chakra UI default with AgentVibes accent colors
-- Typography: Clean sans-serif (Chakra UI system fonts)
-- Iconography: Consistent icon set (React Icons library)
-- No animated effects except loading spinners and toast notifications
-### Target Device and Platforms
-Web Responsive (desktop-first design):
-- Primary: Desktop browsers (Chrome, Firefox, Safari) at 1920x1080
-- Secondary: Laptop browsers at 1366x768
-- Minimal support for tablets (iPad landscape)
-- Not optimized for mobile phones (local deployment, desktop usage expected)
----
-## Technical Assumptions
-### Repository Structure
-**Monorepo** with clear separation:
-```
-agentvibes-stargazers/
-├── frontend/          # Vite + React
-├── backend/           # Express + TypeScript
-├── docker-compose.yml
-├── up, down, restart, health, logs (scripts)
-└── scripts/           # Helper scripts
-```
-### Service Architecture
-**Monolith with modular structure**:
-- Single backend API server (Express.js)
-- Single frontend SPA (Vite + React)
-- PostgreSQL database (single instance)
-- Optional: SonarQube container for CI/CD integration
-Not microservices - system is small enough that monolith with clean modules is simpler and more maintainable.
-### Testing Requirements
-**Comprehensive testing pyramid**:
-- **Unit tests**: All services, utilities, helpers (70% coverage minimum)
-- **Integration tests**: API endpoints, database operations
-- **E2E tests**: Critical user journeys (stargazer sync, email sending)
-- **Manual testing convenience**: Seeded test data, mock SpaceMail responses
-**Testing tools**:
-- Backend: Jest + Supertest
-- Frontend: Vitest + React Testing Library
-- E2E: Playwright
-### Additional Technical Assumptions
-**Tech Stack**:
-*Frontend*:
-- Vite 5 (build tool - chosen for fast HMR over Next.js)
-- React 18 (UI framework)
-- Chakra UI v2 (component library)
-- TanStack Table v8 (data tables)
-- TanStack Query (data fetching/caching)
-- React Router v6 (routing)
-- Zustand (lightweight state management)
-- Axios (HTTP client)
-*Backend*:
-- Node.js 18 (runtime)
-- Express.js (API framework)
-- TypeScript (strict mode)
-- Kysely (type-safe SQL query builder)
-- pg (PostgreSQL driver)
-- kysely-ctl (migration runner)
-- Octokit (@octokit/rest) (GitHub API client)
-- node-cron (scheduled jobs)
-- Nodemailer or SpaceMail SDK (email sending)
-*Database*:
-- PostgreSQL 16 Alpine (relational database)
-- Kysely migrations (raw SQL, type-safe)
-*Infrastructure*:
-- Docker + Docker Compose (containerization)
-- SonarQube Community (code quality)
-- GitHub Actions (CI/CD, optional)
-**GitHub Sync Strategy**:
-- Rewrite Track-Stargazers Python logic in Node.js/TypeScript for consistency
-- Use @octokit/rest for all GitHub API interactions
-- Implement pagination for repos with >100 stargazers
-- Cache user location → country mapping (reduce geocoding API calls)
-**Map Integration Strategy**:
-- Integrate Track-Stargazers' Datamaps + D3.js visualization as React component
-- Alternative: Use modern React map library (react-simple-maps) if easier integration
-- Map data: JSON export from database (country codes + stargazer counts)
-**SpaceMail Integration**:
-- Use SpaceMail REST API (not SMTP) for better tracking and deliverability
-- Implement rate limiting: max 10 emails/hour, exponential backoff on errors
-- Store email send status: draft, pending_approval, sent, failed
-- Track bounces and remove invalid emails automatically
-**PiperTTS Plugin Architecture**:
-- Notification service checks `ENABLE_TTS` env var
-- Calls `/home/fire/claude/AgentVibes/.claude/hooks/play-tts.sh` for TTS
-- Respects `TTS_QUIET_HOURS` env var (default: 22:00-08:00)
-- Gracefully degrades if TTS fails (logs error, continues operation)
-**Docker Management Scripts** (matching SoraSage pattern):
-Scripts follow exact pattern from `/home/fire/claude/SoraSage/`:
-1. **`./up`** (Main startup orchestrator):
-   - Load environment from `.env`
-   - Display color-coded startup phases
-   - Build/start Docker containers with smart rebuild detection
-   - Run Prisma migrations
-   - Perform service health checks
-   - Display service URLs and credentials
-2. **`./down`** (Clean shutdown):
-   - Stop all Docker Compose services
-   - Kill background processes (cron jobs, monitors)
-   - Clean PID files
-3. **`./restart`** (Restart specific service):
-   - Restart Docker container
-   - Wait for health check
-   - Curl health endpoint to verify
-4. **`./health`** (Comprehensive health checker):
-   - Check each service (frontend, backend, postgres)
-   - Display HOST:PORT → INTERNAL:PORT mappings
-   - Color-coded status (green=up, red=down, yellow=warning)
-   - Service-specific checks (pg_isready, curl /health)
-   - Show restart commands for failed services
-   - Summary: X/Y services running
-5. **`./logs`** (Beautiful log viewer):
-   - Color-code by log level (ERROR=red, WARN=yellow, INFO=blue)
-   - Show last 10 lines per service
-   - Support service filters (`./logs backend`)
-   - Support follow mode (`./logs -f backend`)
-**Code Quality Standards**:
-All code MUST follow `/home/fire/claude/AgentVibes/docs/ai-optimized-documentation-standards.md`:
-- File-level context headers with 7 fields (@fileoverview, @context, @architecture, @dependencies, @entrypoints, @patterns, @related)
-- Function documentation with 9 fields (@function, @intent, @why, @param, @returns, @exitcode, @sideeffects, @edgecases, @calledby, @calls)
-- AI NOTE comments for non-obvious logic
-- Architecture Decision Records (ADRs) for critical design choices
-- Cross-reference maps for complex modules
-- Pattern examples for extensibility
-**SonarQube Integration**:
-- Pre-commit hook runs `npm run sonar` before allowing commits
-- Quality gates block commits if:
-  - Code coverage <70%
-  - Duplicated lines >3%
-  - Maintainability rating <A
-  - Cognitive complexity >15 per function
-  - File length >200 lines
-  - Function length >50 lines
-**Component Structure Examples**:
-```typescript
-// frontend/src/components/stargazers/StargazerTable.tsx (max 150 lines)
-// frontend/src/components/stargazers/StargazerRow.tsx (max 100 lines)
-// frontend/src/components/stargazers/StargazerFilters.tsx (max 100 lines)
-// frontend/src/components/email/EmailComposer.tsx (max 150 lines)
-// frontend/src/hooks/useStargazers.ts (max 100 lines)
-// frontend/src/services/github.service.ts (max 200 lines)
-```
-**Database Schema** (Kysely with TypeScript types):
-```typescript
-// backend/src/db/types.ts - Generated from SQL schema
-export interface Database {
-  stargazer: StargazerTable
-  email_template: EmailTemplateTable
-  email: EmailTable
-  sync_log: SyncLogTable
-}
-export interface StargazerTable {
-  id: Generated<string>              // UUID, auto-generated
-  github_id: number                   // Unique
-  username: string                    // Unique
-  email: string | null
-  name: string | null
-  avatar_url: string | null
-  bio: string | null
-  company: string | null
-  location: string | null
-  country: string | null              // ISO country code
-  starred_at: Date
-  contacted: Generated<boolean>       // Default false
-  contacted_at: Date | null
-  last_email_sent: Date | null
-  response_status: string | null      // none, pending, replied
-  notes: string | null
-  created_at: Generated<Date>
-  updated_at: Generated<Date>
-}
-export interface EmailTemplateTable {
-  id: Generated<string>
-  name: string                        // Unique
-  subject: string
-  body: string
-  variables: string | null            // JSON string
-  created_at: Generated<Date>
-  updated_at: Generated<Date>
-}
-export interface EmailTable {
-  id: Generated<string>
-  stargazer_id: string                // FK to stargazer
-  template_id: string
-  template_name: string
-  subject: string
-  body: string
-  status: string                      // draft, pending_approval, sent, failed
-  scheduled_for: Date | null
-  sent_at: Date | null
-  approved_by: string | null
-  approved_at: Date | null
-  error_message: string | null
-  created_at: Generated<Date>
-}
-export interface SyncLogTable {
-  id: Generated<string>
-  sync_type: string                   // manual, cron, webhook
-  status: string                      // success, failed, partial
-  new_stargazers: Generated<number>   // Default 0
-  total_fetched: Generated<number>    // Default 0
-  errors: string | null               // JSON string
-  duration: number | null             // milliseconds
-  created_at: Generated<Date>
-}
-```
-**SQL Schema** (migrations/001_initial_schema.sql):
-```sql
--- Stargazers table
-CREATE TABLE stargazer (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  github_id INTEGER UNIQUE NOT NULL,
-  username VARCHAR(255) UNIQUE NOT NULL,
-  email VARCHAR(255),
-  name VARCHAR(255),
-  avatar_url TEXT,
-  bio TEXT,
-  company VARCHAR(255),
-  location VARCHAR(255),
-  country VARCHAR(2),
-  starred_at TIMESTAMP NOT NULL,
-  contacted BOOLEAN DEFAULT false,
-  contacted_at TIMESTAMP,
-  last_email_sent TIMESTAMP,
-  response_status VARCHAR(50),
-  notes TEXT,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW()
-);
-CREATE INDEX idx_stargazer_github_id ON stargazer(github_id);
-CREATE INDEX idx_stargazer_username ON stargazer(username);
-CREATE INDEX idx_stargazer_contacted ON stargazer(contacted);
-CREATE INDEX idx_stargazer_starred_at ON stargazer(starred_at);
--- Email templates table
-CREATE TABLE email_template (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  name VARCHAR(255) UNIQUE NOT NULL,
-  subject VARCHAR(500) NOT NULL,
-  body TEXT NOT NULL,
-  variables JSONB,
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW()
-);
--- Emails table
-CREATE TABLE email (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  stargazer_id UUID REFERENCES stargazer(id) ON DELETE CASCADE,
-  template_id UUID NOT NULL,
-  template_name VARCHAR(255) NOT NULL,
-  subject VARCHAR(500) NOT NULL,
-  body TEXT NOT NULL,
-  status VARCHAR(50) NOT NULL,
-  scheduled_for TIMESTAMP,
-  sent_at TIMESTAMP,
-  approved_by VARCHAR(255),
-  approved_at TIMESTAMP,
-  error_message TEXT,
-  created_at TIMESTAMP DEFAULT NOW()
-);
-CREATE INDEX idx_email_stargazer_id ON email(stargazer_id);
-CREATE INDEX idx_email_status ON email(status);
-CREATE INDEX idx_email_scheduled_for ON email(scheduled_for);
--- Sync logs table
-CREATE TABLE sync_log (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  sync_type VARCHAR(50) NOT NULL,
-  status VARCHAR(50) NOT NULL,
-  new_stargazers INTEGER DEFAULT 0,
-  total_fetched INTEGER DEFAULT 0,
-  errors JSONB,
-  duration INTEGER,
-  created_at TIMESTAMP DEFAULT NOW()
-);
-CREATE INDEX idx_sync_log_created_at ON sync_log(created_at);
-CREATE INDEX idx_sync_log_sync_type ON sync_log(sync_type);
-```
-**Environment Variables** (`.env`):
-```bash
-# Project Config
-PROJECT_NAME=stargazer-cms
-NODE_ENV=development
-# Ports
-BACKEND_PORT=3001
-VITE_PORT=5173
-POSTGRES_PORT=5432
-SONAR_PORT=9000
-# Database
-DB_NAME=stargazer_cms
-DB_USER=admin
-DB_PASSWORD=admin
-DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
-# GitHub
-GITHUB_TOKEN=ghp_your_token_here
-GITHUB_REPO_OWNER=paulpreibisch
-GITHUB_REPO_NAME=AgentVibes
-# SpaceMail API
-SPACEMAIL_API_KEY=your_spacemail_key
-SPACEMAIL_DOMAIN=your_domain.com
-SPACEMAIL_FROM_EMAIL=paul@your_domain.com
-SPACEMAIL_FROM_NAME=Paul Preibisch
-# Email Settings
-EMAIL_RATE_LIMIT_PER_HOUR=10
-EMAIL_WARMUP_DAILY_LIMIT=5  # Start low, increase gradually
-# PiperTTS (Optional)
-ENABLE_TTS=true
-TTS_QUIET_HOURS=22:00-08:00
-TTS_SCRIPT_PATH=/home/fire/claude/AgentVibes/.claude/hooks/play-tts.sh
-# Backup
-BACKUP_SCHEDULE=0 2 * * *  # Daily at 2am
-BACKUP_RETENTION_DAYS=7
-# Cron
-SYNC_SCHEDULE=0 9 * * *  # Daily at 9am
-```
-**Error Handling Strategy**:
-- All async operations wrapped in try-catch with specific error types
-- User-friendly error messages in UI (toast notifications)
-- Detailed error logging to backend logs
-- Failed emails retry automatically (max 3 attempts with exponential backoff)
-- GitHub API errors show helpful messages (rate limit, auth failure, network)
-**Security Considerations**:
-- No API keys in code or version control
-- Environment variables for all secrets
-- Input validation on all API endpoints (Zod schemas)
-- SQL injection prevention via Prisma (parameterized queries)
-- XSS prevention via React (automatic escaping)
-- CSRF protection on state-changing operations
-- GitHub webhook signature verification (HMAC SHA256)
----
-## Epic List
-### Epic 1: Foundation & Infrastructure
-**Goal**: Establish project foundation with Docker environment, database, and core API scaffolding. Deliver a functional "health check" system demonstrating all services running and communicating.
-### Epic 2: GitHub Stargazer Sync Engine
-**Goal**: Implement automated GitHub stargazer data collection with manual, cron, and webhook sync options. Store stargazers in PostgreSQL with complete profile data.
-### Epic 3: Stargazer Table & Profile Views
-**Goal**: Build primary UI for viewing, filtering, and managing stargazers. Enable users to explore stargazer profiles and add notes.
-### Epic 4: Email Template Management
-**Goal**: Create CRUD interface for email templates with variable substitution support. Provide template preview and reusable composition.
-### Epic 5: SpaceMail Integration & Email Workflow
-**Goal**: Integrate SpaceMail API for semi-automated email sending with approval workflow. Implement rate limiting and deliverability best practices.
-### Epic 6: Geographic Map Visualization
-**Goal**: Integrate Track-Stargazers map visualization as a tab in the UI, displaying stargazer distribution by country.
-### Epic 7: Automation & Monitoring
-**Goal**: Implement scheduled backups, cron-based sync, optional PiperTTS notifications, and comprehensive logging/monitoring.
----
-## Epic 1: Foundation & Infrastructure
-**Epic Goal**: Establish project foundation with Docker environment, PostgreSQL database, core API scaffolding, and Vite frontend. Deliver a functional "health check" system demonstrating all services running, with management scripts (`up`, `down`, `restart`, `health`, `logs`) following SoraSage patterns.
-### Story 1.1: Project Scaffolding & Repository Setup
-**As a** developer,
-**I want** a properly structured monorepo with frontend/backend separation,
-**so that** I can start building features with clear boundaries and conventions.
-**Acceptance Criteria**:
-1. Create GitHub private repository `agentvibes-stargazers`
-2. Initialize monorepo structure:
-   ```
-   agentvibes-stargazers/
-   ├── frontend/
-   ├── backend/
-   ├── scripts/
-   ├── docs/
-   ├── .env.example
-   ├── .gitignore
-   ├── docker-compose.yml
-   ├── README.md
-   └── up, down, restart, health, logs (scripts)
-   ```
-3. Add `.gitignore` excluding `.env`, `node_modules`, `dist`, `.sonar`
-4. Create `.env.example` with all required environment variables (no values)
-5. Initialize `frontend/` with Vite + React + TypeScript template
-6. Initialize `backend/` with Express + TypeScript boilerplate
-7. Add `README.md` with project overview and quick start instructions
-8. All code follows AI-optimized documentation standards (file headers with 7 fields)
-### Story 1.2: Docker Compose Configuration
-**As a** developer,
-**I want** Docker Compose orchestrating all services (frontend, backend, postgres, sonarqube),
-**so that** the entire stack runs with a single `./up` command.
-**Acceptance Criteria**:
-1. Create `docker-compose.yml` with 4 services: postgres, backend, frontend, sonarqube
-2. PostgreSQL service configuration:
-   - Image: postgres:16-alpine
-   - Container name: stargazer-cms-postgres
-   - Port: ${POSTGRES_PORT:-5432}:5432
-   - Volumes: postgres_data, ./backups
-   - Health check: pg_isready every 10s
-3. Backend service configuration:
-   - Build: ./backend/Dockerfile
-   - Container name: stargazer-cms-backend
-   - Port: ${BACKEND_PORT:-3001}:3000
-   - Depends on postgres (service_healthy condition)
-   - Volumes: ./backend:/app (cached), backend_node_modules
-   - Health check: curl /health every 5s
-4. Frontend service configuration:
-   - Build: ./frontend/Dockerfile
-   - Container name: stargazer-cms-frontend
-   - Port: ${VITE_PORT:-5173}:5173
-   - Depends on backend
-   - Volumes: ./frontend:/app (cached), frontend_node_modules
-   - Command: npm run dev -- --host
-5. SonarQube service configuration:
-   - Image: sonarqube:community
-   - Container name: stargazer-cms-sonar
-   - Port: 9000:9000
-   - Depends on postgres
-   - Volumes: sonarqube_data, sonarqube_logs
-6. All services connected to shared `app-network` bridge network
-7. All volumes named with `stargazer_cms_` prefix
-8. docker-compose.yml includes comments explaining service purposes
-### Story 1.3: Docker Management Scripts
-**As a** developer,
-**I want** SoraSage-style management scripts (`up`, `down`, `restart`, `health`, `logs`),
-**so that** I can easily control the Docker environment with beautiful, color-coded output.
-**Acceptance Criteria**:
-1. Create `./up` script (executable):
-   - Load environment from `.env`
-   - Display color-coded startup header with project name
-   - Check for `--rebuild` flag to force container rebuild
-   - Build/start Docker Compose services
-   - Run Prisma migrations after postgres is healthy
-   - Perform health checks on all services with spinners
-   - Display success summary with service URLs (frontend, backend, SonarQube)
-   - Exit code 0 on success, 1 on failure
-2. Create `./down` script (executable):
-   - Display shutdown header
-   - Stop all Docker Compose services
-   - Clean up PID files if any
-   - Display success message
-3. Create `./restart` script (executable):
-   - Accept service name as argument (backend, frontend, postgres)
-   - Restart specific container via `docker restart`
-   - Wait 5 seconds
-   - Curl health endpoint to verify (if applicable)
-   - Display status
-4. Create `./health` script (executable):
-   - Check status of all services (frontend, backend, postgres)
-   - Display HOST:PORT → INTERNAL:PORT for each service
-   - Color-code status: green=up, red=down, yellow=warning
-   - Show service-specific health info:
-     - Backend: curl /health endpoint
-     - Frontend: check Vite dev server logs for "ready"
-     - PostgreSQL: docker exec pg_isready
-   - Display restart commands for failed services
-   - Summary: X/Y services running
-   - Support `--backend`, `--frontend`, `--db` flags for filtered output
-5. Create `./logs` script (executable):
-   - Show last 10 lines of logs for all services (default)
-   - Accept service name as argument for filtered logs
-   - Color-code log levels: ERROR=red, WARN=yellow, INFO=blue, SUCCESS=green
-   - Support `-f` flag for follow mode
-6. All scripts follow Bash best practices: error handling, proper quoting, shellcheck clean
-7. Scripts include file-level documentation headers per AI standards
-### Story 1.4: Backend API Foundation
-**As a** developer,
-**I want** a minimal Express API with TypeScript, health endpoint, and Prisma setup,
-**so that** I have a solid foundation for building API routes.
-**Acceptance Criteria**:
-1. Initialize TypeScript configuration with strict mode enabled
-2. Install dependencies: express, @types/express, prisma, @prisma/client, dotenv, cors, helmet
-3. Create `backend/src/index.ts`:
-   - Load environment variables from .env
-   - Configure Express app with JSON body parser, CORS, Helmet security headers
-   - Add GET /health endpoint returning: `{status: "ok", timestamp: ISO string, services: {database: "connected"}}`
-   - Start server on port from env (default 3000)
-   - Graceful shutdown on SIGTERM/SIGINT
-4. Create `backend/Dockerfile`:
-   - Base image: node:18-alpine
-   - Set working directory /app
-   - Copy package.json, package-lock.json
-   - Run npm ci
-   - Copy source code
-   - Expose port 3000
-   - Run Prisma generate
-   - Start with `npm run dev`
-5. Add npm scripts: `dev` (tsx watch), `build` (tsc), `start` (node dist/index.js)
-6. Configure ESLint with TypeScript plugin, Airbnb base style
-7. All code follows AI-optimized documentation standards (function comments with 9 fields)
-8. Health endpoint responds with 200 status when database connection is healthy
-### Story 1.5: Database Schema & Kysely Setup
-**As a** developer,
-**I want** Kysely query builder configured with initial SQL schema and type-safe TypeScript definitions,
-**so that** I can perform type-safe database operations with full SQL control.
-**Acceptance Criteria**:
-1. Install Kysely: `npm install kysely pg`
-2. Install dev dependencies: `npm install -D kysely-ctl @types/pg`
-3. Create `backend/src/db/database.ts`:
-   - Initialize Kysely instance with PostgresDialect
-   - Use pg Pool with DATABASE_URL from env
-   - Export singleton db instance
-4. Create `backend/src/db/types.ts`:
-   - Define Database interface with all table interfaces
-   - Define StargazerTable with all fields (snake_case column names)
-   - Define EmailTemplateTable, EmailTable, SyncLogTable
-   - Use Generated<T> for auto-generated fields (id, timestamps, defaults)
-5. Create `backend/migrations/001_initial_schema.sql`:
-   - CREATE TABLE stargazer with all columns, indexes, constraints
-   - CREATE TABLE email_template
-   - CREATE TABLE email with FK to stargazer (CASCADE on delete)
-   - CREATE TABLE sync_log
-   - All tables use UUID primary keys with gen_random_uuid()
-   - Proper indexes on: github_id, username, contacted, starred_at, status
-6. Create migration runner script `backend/scripts/migrate.ts`:
-   - Use kysely-ctl or custom migration runner
-   - Run all .sql files in migrations/ directory alphabetically
-   - Track applied migrations in migrations table
-7. Add npm scripts:
-   - `"migrate": "tsx scripts/migrate.ts"`
-   - `"migrate:create": "kysely-ctl migrate create"`
-8. Create `backend/src/db/index.ts`:
-   - Export db instance
-   - Export all table types
-   - Export helper functions (e.g., selectStargazer, insertEmail)
-9. Update /health endpoint to test database connection using `db.selectFrom('stargazer').limit(1).execute()`
-10. Run migrations in `./up` script after postgres is healthy
-11. All code follows AI-optimized documentation standards
-12. Schema uses snake_case for SQL (database convention), camelCase in TypeScript
-### Story 1.6: Frontend Foundation with Chakra UI
-**As a** developer,
-**I want** a Vite + React app with Chakra UI v2, routing, and basic layout,
-**so that** I can start building the UI.
-**Acceptance Criteria**:
-1. Initialize Vite React TypeScript template in `frontend/`
-2. Install dependencies: @chakra-ui/react, @emotion/react, @emotion/styled, framer-motion, react-router-dom, @tanstack/react-query, @tanstack/react-table, axios, zustand, react-icons
-3. Configure Chakra UI provider in `frontend/src/main.tsx`
-4. Create `frontend/src/components/layout/MainLayout.tsx`:
-   - Chakra Box with Flex layout
-   - Sidebar (left, 250px width): Navigation links (Stargazers, Templates, Map, Settings)
-   - Main content area (right, flex-grow): Outlet for nested routes
-   - Header bar (top): Project title "Stargazer CMS", sync button, user menu
-5. Create `frontend/src/App.tsx` with React Router:
-   - Routes: / → Stargazers, /templates → Templates (placeholder), /map → Map (placeholder), /settings → Settings (placeholder)
-   - Wrap routes in MainLayout
-6. Create `frontend/src/pages/StargazersPage.tsx` (placeholder):
-   - Display heading "Stargazers"
-   - Show "Coming soon..." text
-7. Create `frontend/Dockerfile`:
-   - Base image: node:18-alpine
-   - Set working directory /app
-   - Copy package.json, package-lock.json
-   - Run npm ci
-   - Copy source code
-   - Expose port 5173
-   - Start with `npm run dev -- --host`
-8. Add `frontend/vite.config.ts` with proxy to backend API
-9. All components use Chakra UI primitives (Box, Flex, Text, Button, etc.)
-10. All code follows AI-optimized documentation standards (file headers)
-### Story 1.7: SonarQube Integration & Quality Gates
-**As a** developer,
-**I want** SonarQube configured with strict quality gates,
-**so that** all code meets maintainability standards before commits.
-**Acceptance Criteria**:
-1. SonarQube service running on port 9000 (from docker-compose.yml)
-2. Create `sonar-project.properties` in project root:
-   - Project key: agentvibes-stargazers
-   - Project name: Stargazer CMS
-   - Sources: frontend/src, backend/src
-   - Exclusions: node_modules, dist, coverage
-   - Coverage report paths for Jest/Vitest
-3. Create quality gate profile with thresholds:
-   - Code Coverage: ≥70%
-   - Duplicated Lines: ≤3%
-   - Maintainability Rating: A
-   - Cognitive Complexity: ≤15 per function
-   - Cyclomatic Complexity: ≤10 per function
-   - Lines per File: ≤200
-   - Lines per Function: ≤50
-4. Install SonarQube scanner: `npm install -g sonarqube-scanner`
-5. Add npm script: `"sonar": "sonar-scanner"`
-6. Create `.husky/pre-commit` hook:
-   - Run `npm run lint` (ESLint)
-   - Run `npm run type-check` (TypeScript)
-   - Run `npm run test` (Jest/Vitest with coverage)
-   - Run `npm run sonar` (SonarQube scan)
-   - Block commit if any step fails
-7. Document quality gate rules in `docs/code-quality.md`
-8. Health script shows SonarQube status
----
-## Epic 2: GitHub Stargazer Sync Engine
-**Epic Goal**: Implement automated GitHub stargazer data collection with three sync methods (manual, cron, webhook). Fetch complete stargazer profiles from GitHub API, store in PostgreSQL with country mapping, and log all sync operations.
-### Story 2.1: GitHub API Service Layer
-**As a** backend developer,
-**I want** a GitHub service module using Octokit to fetch stargazers,
-**so that** I can retrieve stargazer data with proper authentication and pagination.
-**Acceptance Criteria**:
-1. Create `backend/src/services/github.service.ts`
-2. Initialize Octokit client with GitHub token from env variable
-3. Implement `fetchStargazers(owner, repo, perPage=100)` function:
-   - Use octokit.rest.activity.listStargazersForRepo
-   - Accept header: application/vnd.github.v3.star+json (includes starred_at timestamp)
-   - Implement automatic pagination to fetch all stargazers
-   - Return array of objects: {githubId, username, starredAt}
-4. Implement `fetchUserDetails(username)` function:
-   - Use octokit.rest.users.getByUsername
-   - Return object: {name, email, avatarUrl, bio, company, location}
-   - Handle rate limiting with exponential backoff
-   - Return null if user not found (404)
-5. Implement `verifyToken()` function:
-   - Test GitHub token validity
-   - Return {valid: boolean, rateLimitRemaining: number}
-6. Add error handling for common GitHub API errors:
-   - 401 Unauthorized: Invalid token
-   - 403 Forbidden: Rate limit exceeded
-   - 404 Not Found: Repo or user not found
-   - Network errors: Timeout, connection refused
-7. All functions include comprehensive JSDoc comments per AI standards
-8. Unit tests with mocked Octokit responses (Jest)
-### Story 2.2: Geocoding & Country Mapping
-**As a** backend developer,
-**I want** to map stargazer locations to country names,
-**so that** I can display geographic distribution on the map.
-**Acceptance Criteria**:
-1. Create `backend/src/services/geocoding.service.ts`
-2. Implement `getCountryFromLocation(location: string)` function:
-   - Parse common location formats: "City, Country", "Country", "City, State, Country"
-   - Use simple country name matching first (fast path)
-   - Fallback: Use geocoding API (OpenStreetMap Nominatim, free tier)
-   - Cache results in-memory Map (location → country) to reduce API calls
-   - Return ISO country code (e.g., "US", "CA", "GB") or null if unknown
-3. Implement `batchGeocode(locations: string[])` function:
-   - Process multiple locations efficiently
-   - Check cache first
-   - Batch API requests (max 10 concurrent)
-   - Return Map<location, countryCode>
-4. Add country code → country name mapping (static JSON file)
-5. Handle edge cases:
-   - Empty location string → null
-   - Ambiguous locations (e.g., "London") → best guess or null
-   - API rate limiting → retry with exponential backoff
-6. Unit tests with sample locations and mocked API responses
-### Story 2.3: Stargazer Sync Core Logic
-**As a** backend developer,
-**I want** core sync logic to fetch stargazers, enrich with user details, and store in database,
-**so that** I can keep the stargazer list up-to-date.
-**Acceptance Criteria**:
-1. Create `backend/src/services/sync.service.ts`
-2. Implement `syncStargazers(syncType: 'manual'|'cron'|'webhook')` function:
-   - Fetch stargazers from GitHub (github.service.fetchStargazers)
-   - For each stargazer:
-     - Check if already in database (by githubId)
-     - If new: Fetch user details (github.service.fetchUserDetails)
-     - Map location to country (geocoding.service.getCountryFromLocation)
-     - Upsert to database (Prisma)
-   - Create SyncLog entry with: syncType, status, newStargazers count, totalFetched, duration
-   - Return {success: boolean, newCount: number, totalCount: number, errors: string[]}
-3. Implement progress tracking:
-   - Emit progress events via EventEmitter
-   - Events: sync_started, user_fetched, user_stored, sync_completed
-   - Allows real-time UI updates via WebSocket (future story)
-4. Add error resilience:
-   - Continue processing if individual user fetch fails
-   - Collect errors in array, log to SyncLog.errors
-   - Mark sync as "partial" if some users failed
-5. Implement deduplication:
-   - Use githubId as unique identifier (not username, which can change)
-   - Update existing stargazers if data changed
-6. Add concurrency control:
-   - Process user details in batches of 10 concurrent requests
-   - Prevents overwhelming GitHub API and database
-7. Unit tests with mocked GitHub service and database
-8. Integration test with test database
-### Story 2.4: Manual Sync API Endpoint
-**As a** user,
-**I want** a "Sync Now" button in the UI that triggers manual stargazer sync,
-**so that** I can update the list on-demand.
-**Acceptance Criteria**:
-1. Create `backend/src/controllers/sync.controller.ts`
-2. Implement POST /api/sync endpoint:
-   - Trigger sync.service.syncStargazers('manual')
-   - Return 202 Accepted immediately (async processing)
-   - Response body: {syncId: string, message: "Sync started"}
-3. Implement GET /api/sync/status/:syncId endpoint:
-   - Query SyncLog by ID
-   - Return {status: 'running'|'completed'|'failed', progress: number, errors: string[]}
-4. Implement GET /api/sync/logs endpoint:
-   - Query recent SyncLog entries (last 50)
-   - Return array with: id, syncType, status, newStargazers, totalFetched, createdAt
-5. Add frontend sync button in header:
-   - Click triggers POST /api/sync
-   - Show toast notification: "Sync started"
-   - Poll GET /api/sync/status every 2 seconds until completed
-   - Show success toast: "Synced X new stargazers"
-   - Refresh stargazers table
-6. Add loading spinner on sync button during active sync
-7. Prevent concurrent syncs (return 409 Conflict if sync already running)
-8. Integration test: POST /api/sync → verify database updated
-### Story 2.5: Scheduled Cron Sync
-**As a** system,
-**I want** daily automated stargazer sync at 9am,
-**so that** the list stays current without manual intervention.
-**Acceptance Criteria**:
-1. Install node-cron: `npm install node-cron @types/node-cron`
-2. Create `backend/src/jobs/sync.job.ts`
-3. Implement cron job:
-   - Schedule: Load from env variable `SYNC_SCHEDULE` (default: "0 9 * * *")
-   - Task: Call sync.service.syncStargazers('cron')
-   - Log start and completion to console
-4. Register cron job in `backend/src/index.ts` after Express app starts
-5. Add graceful shutdown: Stop cron jobs on SIGTERM/SIGINT
-6. Add optional PiperTTS notification on completion (if ENABLE_TTS=true):
-   - Call notification.service.notifySync(newCount)
-   - Respect TTS_QUIET_HOURS (skip if within quiet hours)
-7. Log all cron executions to SyncLog table
-8. Add env variable `ENABLE_CRON_SYNC` (default: true) to disable cron if needed
-9. Create `backend/src/services/notification.service.ts`:
-   - Check ENABLE_TTS env variable
-   - Check current time against TTS_QUIET_HOURS
-   - Execute TTS script with message: "Stargazer sync complete. X new stargazers."
-   - Gracefully handle TTS script failures (log error, don't crash)
-10. Manual test: Set cron to run in 1 minute, verify sync executes and logs created
-### Story 2.6: GitHub Webhook Integration
-**As a** system,
-**I want** real-time notifications when someone stars the repo,
-**so that** I can sync immediately without waiting for daily cron.
-**Acceptance Criteria**:
-1. Create `backend/src/controllers/webhook.controller.ts`
-2. Implement POST /api/webhooks/github endpoint:
-   - Verify GitHub signature (HMAC SHA256 using webhook secret)
-   - Parse event type from X-GitHub-Event header
-   - Handle "star" event (action=created):
-     - Extract stargazer username
-     - Call sync.service.syncStargazers('webhook')
-     - Return 200 OK
-   - Ignore other events
-   - Return 400 Bad Request if signature invalid
-3. Add env variable `GITHUB_WEBHOOK_SECRET` for signature verification
-4. Add optional PiperTTS notification on new star (if ENABLE_TTS=true):
-   - Call notification.service.notifyNewStargazer(username)
-   - Respect TTS_QUIET_HOURS
-5. Create SyncLog entry for each webhook-triggered sync
-6. Add webhook URL to Settings screen in UI
-7. Document GitHub webhook setup in README.md:
-   - Go to GitHub repo settings → Webhooks
-   - Add webhook with URL: http://your-domain/api/webhooks/github
-   - Content type: application/json
-   - Secret: (from GITHUB_WEBHOOK_SECRET env var)
-   - Events: Star
-8. Add rate limiting on webhook endpoint (max 100 requests/minute per IP)
-9. Unit test with mocked GitHub webhook payload
-10. Integration test: Send valid webhook payload, verify sync triggered
----
-## Epic 3: Stargazer Table & Profile Views
-**Epic Goal**: Build the primary UI for viewing, filtering, and managing stargazers. Implement TanStack Table with sorting, filtering, pagination, and inline actions. Enable detailed stargazer profile view with contact history and notes.
-### Story 3.1: Stargazer API Endpoints
-**As a** frontend developer,
-**I want** REST API endpoints to fetch, filter, and update stargazers,
-**so that** I can build the UI with real data.
-**Acceptance Criteria**:
-1. Create `backend/src/controllers/stargazers.controller.ts`
-2. Implement GET /api/stargazers endpoint:
-   - Query params: page (default 1), limit (default 50), sort (field:order), filter (JSON)
-   - Filter support: contacted (boolean), starredAfter (date), starredBefore (date), country (string), search (text search on username/name/email)
-   - Return: {data: Stargazer[], total: number, page: number, limit: number}
-   - Use Prisma pagination (skip/take) and filtering (where)
-3. Implement GET /api/stargazers/:id endpoint:
-   - Return single stargazer with all fields
-   - Include related emails (last 10)
-   - Return 404 if not found
-4. Implement PATCH /api/stargazers/:id endpoint:
-   - Accept body: {notes, contacted, responseStatus}
-   - Update stargazer in database
-   - Return updated stargazer
-   - Validate input with Zod schema
-5. Implement GET /api/stargazers/stats endpoint:
-   - Return: {total, contacted, notContacted, countryCounts: {[country]: count}}
-   - Use Kysely aggregation queries (selectFrom with count, groupBy)
-6. Add input validation middleware using Zod
-7. Add error handling middleware (consistent error responses)
-8. Unit tests for all endpoints
-9. Integration tests with test database
-### Story 3.2: Stargazer Table with TanStack Table
-**As a** user,
-**I want** a data table showing all stargazers with sorting, filtering, and pagination,
-**so that** I can quickly find and manage stargazers.
-**Acceptance Criteria**:
-1. Create `frontend/src/components/stargazers/StargazerTable.tsx` (<150 lines)
-2. Install @tanstack/react-table v8
-3. Configure TanStack Table with columns:
-   - Avatar (image, 40px)
-   - Username (link to GitHub)
-   - Name
-   - Email
-   - Starred Date (formatted: "Jan 10, 2025")
-   - Country (with flag emoji if available)
-   - Contacted (badge: green="Yes", gray="No")
-   - Actions (buttons: "View", "Email")
-4. Implement column sorting (click header to toggle asc/desc)
-5. Implement pagination:
-   - Page size selector: 25, 50, 100
-   - Previous/Next buttons
-   - Page number display: "Page 1 of 10"
-6. Fetch data using TanStack Query:
-   - Query key: ['stargazers', page, limit, sort, filters]
-   - Fetch function: axios.get('/api/stargazers')
-   - Enable query caching (5 minutes staleTime)
-7. Add loading skeleton while fetching
-8. Add empty state: "No stargazers found. Click Sync to fetch from GitHub."
-9. Use Chakra UI Table components for styling
-10. All code follows AI-optimized documentation standards
-11. Component max 150 lines (extract row rendering to StargazerRow.tsx if needed)
-### Story 3.3: Stargazer Filters
-**As a** user,
-**I want** filters above the table to narrow down stargazers,
-**so that** I can find specific users quickly.
-**Acceptance Criteria**:
-1. Create `frontend/src/components/stargazers/StargazerFilters.tsx` (<100 lines)
-2. Render filter bar with Chakra UI components:
-   - Search input (placeholder: "Search username, name, or email")
-   - Contact status filter (dropdown: All, Contacted, Not Contacted)
-   - Date range picker (Starred after, Starred before)
-   - Country filter (multi-select dropdown with top 20 countries)
-   - Clear filters button
-3. Implement filter state with Zustand store:
-   - Store: {search, contactStatus, starredAfter, starredBefore, countries}
-   - Actions: setSearch, setContactStatus, setDateRange, setCountries, clearFilters
-4. Debounce search input (300ms) to prevent excessive API calls
-5. Update TanStack Query when filters change
-6. Persist filters in URL query params (enables sharing filtered views)
-7. Show active filter count badge: "3 filters active"
-8. Add "Reset filters" button if any filters active
-9. All code follows AI standards (<100 lines)
-### Story 3.4: Stargazer Profile Modal
-**As a** user,
-**I want** a detailed profile view when clicking on a stargazer,
-**so that** I can see their full information and contact history.
-**Acceptance Criteria**:
-1. Create `frontend/src/components/stargazers/StargazerProfileModal.tsx` (<150 lines)
-2. Use Chakra UI Modal component (large size)
-3. Modal layout (two columns):
-   - Left column (40%):
-     - Avatar (large, 120px)
-     - Username (link to GitHub profile in new tab)
-     - Name
-     - Email (mailto link)
-     - Company
-     - Location → Country
-     - Bio (italic, gray text)
-     - Starred date
-   - Right column (60%):
-     - Contact history section:
-       - Heading: "Contact History"
-       - Timeline of emails sent (template name, sent date, status)
-       - Empty state: "No emails sent yet"
-     - Notes section:
-       - Heading: "Notes"
-       - Textarea (editable, auto-save on blur)
-       - Character count: "250/1000"
-4. Add action buttons in footer:
-   - "Send Email" (opens EmailComposerModal)
-   - "View on GitHub" (opens new tab)
-   - "Close"
-5. Fetch stargazer details using TanStack Query:
-   - Query key: ['stargazer', id]
-   - Fetch function: axios.get(`/api/stargazers/${id}`)
-6. Implement notes auto-save:
-   - Debounce textarea changes (1 second)
-   - PATCH /api/stargazers/:id with new notes
-   - Show subtle "Saving..." indicator
-   - Show checkmark on successful save
-7. Add loading state while fetching
-8. All code follows AI standards (<150 lines)
-### Story 3.5: Bulk Selection & Actions
-**As a** user,
-**I want** to select multiple stargazers and perform bulk actions,
-**so that** I can send emails to multiple people at once.
-**Acceptance Criteria**:
-1. Add checkbox column to StargazerTable (first column)
-2. Implement TanStack Table row selection:
-   - Header checkbox: Select all on current page
-   - Row checkboxes: Select individual stargazers
-   - Shift+click: Range selection
-3. Add selection state to Zustand store:
-   - Store: {selectedIds: Set<string>}
-   - Actions: selectOne, deselectOne, selectAll, deselectAll, toggleSelection
-4. Display selection count badge above table:
-   - "3 stargazers selected"
-   - Clear selection button (X icon)
-5. Add bulk actions dropdown (enabled only when selections exist):
-   - "Send Email to Selected" → Opens EmailComposerModal with multiple recipients
-   - "Mark as Contacted"
-   - "Export Selected (CSV)"
-6. Implement "Mark as Contacted" action:
-   - PATCH /api/stargazers/bulk with {ids: string[], contacted: true}
-   - Show success toast: "Marked 5 stargazers as contacted"
-   - Refresh table
-7. Implement "Export Selected (CSV)" action:
-   - Generate CSV file with columns: username, name, email, starred_date, country
-   - Trigger browser download
-8. Persist selection across pagination (selection state independent of current page)
-9. Clear selection when filters change
----
-## Epic 4: Email Template Management
-**Epic Goal**: Create CRUD interface for managing email templates with variable substitution support ({{name}}, {{username}}, {{repo}}). Provide template preview with sample data and enable reusable composition.
-### Story 4.1: Email Template API Endpoints
-**As a** frontend developer,
-**I want** REST API endpoints for template CRUD operations,
-**so that** I can build the template management UI.
-**Acceptance Criteria**:
-1. Create `backend/src/controllers/templates.controller.ts`
-2. Implement GET /api/templates endpoint:
-   - Return all templates sorted by name
-   - Include: id, name, subject, body, createdAt, updatedAt
-   - Pagination optional (most users have <20 templates)
-3. Implement GET /api/templates/:id endpoint:
-   - Return single template
-   - Return 404 if not found
-4. Implement POST /api/templates endpoint:
-   - Accept body: {name, subject, body, variables}
-   - Validate: name required (unique), subject required, body required
-   - Create template in database
-   - Return created template with 201 status
-5. Implement PATCH /api/templates/:id endpoint:
-   - Accept body: {name, subject, body, variables}
-   - Update template in database
-   - Return updated template
-6. Implement DELETE /api/templates/:id endpoint:
-   - Delete template from database
-   - Return 204 No Content
-   - Prevent deletion if template is referenced in Email table (return 409 Conflict)
-7. Add input validation using Zod:
-   - Name: 1-100 characters, unique
-   - Subject: 1-200 characters
-   - Body: 1-5000 characters
-   - Variables: array of strings (optional)
-8. Unit tests for all endpoints
-9. Integration tests with test database
-### Story 4.2: Template List Screen
-**As a** user,
-**I want** a screen listing all my email templates,
-**so that** I can view, edit, and delete templates.
-**Acceptance Criteria**:
-1. Create `frontend/src/pages/TemplatesPage.tsx` (<150 lines)
-2. Layout: Two-column design
-   - Left sidebar (30%): Template list
-   - Right panel (70%): Template editor or preview
-3. Template list (sidebar):
-   - Each item shows: template name, subject preview (truncated), last updated date
-   - Click to select and show in right panel
-   - Hover effect (background color change)
-   - Active template highlighted (border)
-   - "Create New Template" button at top
-4. Fetch templates using TanStack Query:
-   - Query key: ['templates']
-   - Fetch function: axios.get('/api/templates')
-   - Enable query caching
-5. Add empty state: "No templates yet. Create your first template to get started."
-6. Add loading skeleton while fetching
-7. Use Chakra UI List and ListItem components
-8. All code follows AI standards (<150 lines)
-### Story 4.3: Template Editor
-**As a** user,
-**I want** to create and edit email templates with variable placeholders,
-**so that** I can reuse templates for multiple stargazers.
-**Acceptance Criteria**:
-1. Create `frontend/src/components/templates/TemplateEditor.tsx` (<150 lines)
-2. Form fields (Chakra UI):
-   - Template name input (required)
-   - Subject line input (required)
-   - Body textarea (required, tall, 300px height)
-   - Variable hints below body: "Available variables: {{name}}, {{username}}, {{repo}}"
-3. Add "Save" and "Cancel" buttons
-4. Implement create/update logic:
-   - If new template: POST /api/templates
-   - If editing: PATCH /api/templates/:id
-   - Show success toast on save
-   - Invalidate templates query cache
-5. Add form validation:
-   - Name required, max 100 characters
-   - Subject required, max 200 characters
-   - Body required, max 5000 characters
-   - Show error messages below fields
-6. Add "Duplicate Template" button (copies current template with " (Copy)" suffix)
-7. Add "Delete Template" button (with confirmation dialog):
-   - Show warning: "Are you sure? This cannot be undone."
-   - DELETE /api/templates/:id
-   - Show success toast: "Template deleted"
-   - Redirect to template list
-8. Disable delete if template has been used (check Email table)
-9. All code follows AI standards (<150 lines)
-### Story 4.4: Template Preview
-**As a** user,
-**I want** to preview how an email template looks with sample data,
-**so that** I can verify formatting before sending.
-**Acceptance Criteria**:
-1. Create `frontend/src/components/templates/TemplatePreview.tsx` (<100 lines)
-2. Render email preview card (Chakra UI):
-   - Header section: "Subject: [rendered subject]"
-   - Body section: [rendered body with variables replaced]
-   - Use sample data: {name: "John Doe", username: "johndoe", repo: "AgentVibes"}
-3. Implement variable substitution logic:
-   - Replace {{name}} with sample name
-   - Replace {{username}} with sample username
-   - Replace {{repo}} with sample repo name
-   - Handle missing variables gracefully (show placeholder)
-4. Add "Preview Mode" toggle button in template editor
-5. Show preview in right panel when preview mode active
-6. Use monospace font for variables in body textarea (syntax highlighting)
-7. Add "Copy Preview" button (copies rendered text to clipboard)
-8. All code follows AI standards (<100 lines)
-### Story 4.5: Default Templates Seeding
-**As a** developer,
-**I want** default email templates created on first run,
-**so that** users have examples to start with.
-**Acceptance Criteria**:
-1. Create `backend/scripts/seed.ts`
-2. Use Kysely insertInto to seed default templates
-3. Define 3 default templates:
-   - **"Initial Thank You"**:
-     - Subject: "Thanks for starring AgentVibes, {{name}}! 🌟"
-     - Body:
-       ```
-       Hi {{name}},
-       I noticed you starred AgentVibes on GitHub – thank you!
-       I'm actively improving it and would love your feedback:
-       - What brought you to AgentVibes?
-       - Any features you'd like to see?
-       Feel free to reply or open an issue. Your input shapes the roadmap.
-       Cheers,
-       Paul Preibisch
-       ---
-       Unsubscribe: [link]
-       ```
-   - **"Feature Feedback Request"**:
-     - Subject: "Quick question about AgentVibes"
-     - Body:
-       ```
-       Hey {{username}},
-       Thanks for being an early supporter of AgentVibes!
-       I'm planning the next release and curious: which feature would be most valuable to you?
-       A) More TTS voices
-       B) Better customization options
-       C) Integration with other tools
-       D) Something else (please tell me!)
-       Reply with your choice or any ideas. Takes 30 seconds and really helps.
-       Thanks,
-       Paul
-       ```
-   - **"Follow-up (No Response)"**:
-     - Subject: "Still interested in AgentVibes?"
-     - Body:
-       ```
-       Hi {{name}},
-       I reached out a few weeks ago but didn't hear back. No worries!
-       If you're still interested in AgentVibes, I'd love to stay in touch. We've added [new features] since you starred the repo.
-       Let me know if you have any questions or feedback.
-       Best,
-       Paul
-       ```
-4. Implement seed logic:
-   - Use Kysely selectFrom('email_template').select(count()).execute()
-   - If count === 0, insert default templates using insertInto
-   - Log: "Seeded 3 default templates"
-5. Add seed script to package.json: `"seed": "tsx backend/scripts/seed.ts"`
-6. Run seed automatically in `./up` script after migrations
-6. All code follows AI standards
----
-## Epic 5: SpaceMail Integration & Email Workflow
-**Epic Goal**: Integrate SpaceMail API for semi-automated email sending with approval workflow, rate limiting, and deliverability best practices. Implement email composer, draft management, scheduled sending, and engagement tracking.
-### Story 5.1: SpaceMail API Service Layer
-**As a** backend developer,
-**I want** a SpaceMail service module to send emails via their API,
-**so that** I can send transactional emails with tracking.
-**Acceptance Criteria**:
-1. Create `backend/src/services/spacemail.service.ts`
-2. Install SpaceMail SDK or use Axios for REST API
-3. Implement `sendEmail(params)` function:
-   - Parameters: {to, subject, body, fromEmail, fromName}
-   - Use SpaceMail API: POST /v1/emails
-   - Headers: Authorization with SPACEMAIL_API_KEY
-   - Body: {from: {email, name}, to: [{email}], subject, html: body}
-   - Return: {success: boolean, messageId: string, error?: string}
-4. Implement rate limiting:
-   - Track emails sent in last hour (store in-memory or Redis)
-   - Reject if count >= EMAIL_RATE_LIMIT_PER_HOUR (env var, default 10)
-   - Return error: "Rate limit exceeded. Try again in X minutes."
-5. Implement retry logic for transient failures:
-   - Retry on 5xx errors (server errors)
-   - Max 3 retries with exponential backoff (1s, 2s, 4s)
-   - Don't retry on 4xx errors (client errors)
-6. Implement `verifyCredentials()` function:
-   - Test API key validity
-   - Return {valid: boolean, domain: string}
-7. Add comprehensive error handling:
-   - Invalid API key → 401 error
-   - Invalid domain → 403 error
-   - Rate limit exceeded → 429 error
-   - Network errors → timeout/connection refused
-8. All functions include JSDoc comments per AI standards
-9. Unit tests with mocked SpaceMail API responses
-### Story 5.2: Email Composition & Draft Management
-**As a** user,
-**I want** to compose an email to a stargazer using a template,
-**so that** I can personalize the message before sending.
-**Acceptance Criteria**:
-1. Create `frontend/src/components/email/EmailComposer.tsx` (<200 lines)
-2. Use Chakra UI Modal (large size, full height)
-3. Modal sections:
-   - Header: "Compose Email to [username]" or "Compose Email to X stargazers"
-   - Template selector: Dropdown of available templates
-   - Subject input: Pre-filled from template, editable
-   - Body textarea: Pre-filled from template with variables replaced, editable
-   - Recipient list (if bulk send): Chip list of stargazers, removable
-4. Implement variable substitution:
-   - Replace {{name}} with stargazer name (or "there" if null)
-   - Replace {{username}} with GitHub username
-   - Replace {{repo}} with "AgentVibes"
-   - Handle multiple recipients: each gets personalized copy
-5. Add action buttons:
-   - "Save Draft" → POST /api/emails/draft
-   - "Send Now" → POST /api/emails/send (approval required)
-   - "Schedule Send" → Opens date picker, POST /api/emails/schedule
-   - "Cancel" → Close modal with confirmation if changes
-6. Add character counter for subject (max 200) and body (max 5000)
-7. Add preview toggle: Switch between edit and preview modes
-8. Persist draft to database (Email table with status="draft")
-9. Load draft if reopening composer for same stargazer
-10. All code follows AI standards (<200 lines, extract sub-components if needed)
-### Story 5.3: Email Approval Workflow
-**As a** user,
-**I want** to review and approve emails before they are sent,
-**so that** I don't accidentally send incorrect emails.
-**Acceptance Criteria**:
-1. Create `backend/src/controllers/emails.controller.ts`
-2. Implement POST /api/emails/draft endpoint:
-   - Accept body: {stargazerId, templateId, subject, body}
-   - Create Email record with status="draft"
-   - Return created email
-3. Implement POST /api/emails/send endpoint:
-   - Accept body: {emailId}
-   - Validate email exists and status="draft"
-   - Update status to "pending_approval"
-   - Return {success: true, message: "Email ready for approval"}
-4. Create `frontend/src/components/email/EmailApprovalModal.tsx` (<150 lines)
-5. Modal sections:
-   - Header: "Approve Email to [username]"
-   - Preview section: Rendered email (subject + body)
-   - Recipient info: Avatar, username, email address
-   - Warning: "This email will be sent via SpaceMail API. Review carefully."
-6. Add action buttons:
-   - "Approve & Send" → POST /api/emails/approve/:id
-   - "Edit" → Reopen EmailComposer
-   - "Cancel" → Close modal
-7. Implement POST /api/emails/approve/:id endpoint:
-   - Validate email exists and status="pending_approval"
-   - Check rate limit (spacemail.service)
-   - Send email via SpaceMail (spacemail.service.sendEmail)
-   - Update Email record: status="sent", sentAt=now, approvedBy="user", approvedAt=now
-   - Update Stargazer: contacted=true, contactedAt=now, lastEmailSent=now
-   - Return {success: boolean, messageId?: string, error?: string}
-8. Show success toast: "Email sent to [username]"
-9. Show error toast if send fails: "Failed to send email: [error message]"
-10. Add loading state during send operation
-11. All code follows AI standards
-### Story 5.4: Scheduled Email Sending
-**As a** user,
-**I want** to schedule emails to be sent at a future time,
-**so that** I can send follow-ups after a delay.
-**Acceptance Criteria**:
-1. Add `scheduledFor` field to Email composer modal
-2. Implement date/time picker (Chakra UI DatePicker or react-datepicker)
-3. Validate scheduled time is in the future (at least 5 minutes from now)
-4. Implement POST /api/emails/schedule endpoint:
-   - Accept body: {emailId, scheduledFor}
-   - Update Email record: scheduledFor timestamp
-   - Return {success: true}
-5. Create `backend/src/jobs/email.job.ts`
-6. Implement cron job to send scheduled emails:
-   - Schedule: Every 5 minutes ("*/5 * * * *")
-   - Query emails where status="pending_approval" and scheduledFor <= now
-   - For each email:
-     - Check rate limit
-     - Send via SpaceMail
-     - Update status to "sent" or "failed"
-   - Log results
-7. Register email job in `backend/src/index.ts`
-8. Add "Cancel Scheduled Send" button in UI:
-   - DELETE /api/emails/scheduled/:id
-   - Update status back to "draft"
-9. Show scheduled emails in Settings screen:
-   - List of upcoming scheduled sends
-   - Columns: Recipient, subject, scheduled time, cancel button
-10. Add notification on scheduled send completion (optional TTS)
-### Story 5.5: Email History & Engagement Tracking
-**As a** user,
-**I want** to see email history for each stargazer,
-**so that** I can track communication and avoid duplicate emails.
-**Acceptance Criteria**:
-1. Implement GET /api/stargazers/:id/emails endpoint:
-   - Return all emails sent to stargazer (sorted by sentAt desc)
-   - Include: id, templateName, subject, status, sentAt, approvedAt
-2. Create `frontend/src/components/stargazers/EmailHistory.tsx` (<100 lines)
-3. Render timeline component (Chakra UI):
-   - Each entry: Template name, subject (truncated), sent date, status badge
-   - Status colors: sent=green, failed=red, pending_approval=yellow, draft=gray
-   - Click to expand: Show full email body
-4. Add to StargazerProfileModal (right column)
-5. Show empty state: "No emails sent to this stargazer yet"
-6. Add filter: "Show only sent" / "Show all"
-7. Implement GET /api/emails/stats endpoint:
-   - Return: {totalSent, totalFailed, averageResponseTime, responseRate}
-   - Use Prisma aggregation
-8. Create `frontend/src/pages/AnalyticsPage.tsx` (placeholder for Epic 6):
-   - Display email stats: Total sent, Success rate, Response rate
-   - Chart: Emails sent over time (last 30 days)
-9. All code follows AI standards
----
-## Epic 6: Geographic Map Visualization
-**Epic Goal**: Integrate Track-Stargazers map visualization library to display stargazer distribution by country. Render interactive world map with country hover tooltips, clickable regions, and filter integration.
-### Story 6.1: Map Data API Endpoint
-**As a** frontend developer,
-**I want** an API endpoint providing stargazer counts by country,
-**so that** I can render the geographic map.
-**Acceptance Criteria**:
-1. Implement GET /api/stargazers/map-data endpoint in `backend/src/controllers/stargazers.controller.ts`
-2. Query stargazers grouped by country:
-   - Use Kysely selectFrom with count() and groupBy('country')
-   - Return: `{country: countryCode, count: number}[]`
-   - Example: `[{country: "US", count: 45}, {country: "CA", count: 12}, ...]`
-3. Filter by contact status (query param: contacted=true/false/all)
-4. Add country name mapping:
-   - Return: `{country: countryCode, countryName: string, count: number}[]`
-   - Use static country code → name mapping (ISO 3166-1 alpha-2)
-5. Handle stargazers with unknown location:
-   - Group as `{country: "UNKNOWN", countryName: "Unknown", count: X}`
-6. Add caching headers: Cache-Control: max-age=300 (5 minutes)
-7. Unit test with sample data
-### Story 6.2: Integrate Track-Stargazers Map Library
-**As a** frontend developer,
-**I want** to integrate Track-Stargazers' Datamaps + D3.js visualization,
-**so that** I can display an interactive world map.
-**Acceptance Criteria**:
-1. Research Track-Stargazers implementation:
-   - Clone repo: https://github.com/kiok46/Track-Stargazers
-   - Review `index.html`, JavaScript files
-   - Identify Datamaps and D3.js dependencies
-2. Install dependencies:
-   - `npm install d3 datamaps`
-   - `npm install @types/d3 --save-dev`
-3. Create `frontend/src/components/map/StargazerMap.tsx` (<150 lines)
-4. Initialize Datamap in React component:
-   - Use useEffect to render map after component mounts
-   - Target: `<div ref={mapRef} style={{height: 600px}} />`
-   - Configure Datamap with world map projection
-5. Load map data from API:
-   - Fetch using TanStack Query: `useQuery(['map-data', filters])`
-   - Transform to Datamaps format: `{USA: {fillKey: 'HIGH'}, ...}`
-6. Configure color scale based on stargazer count:
-   - 0: Light gray
-   - 1-5: Light blue
-   - 6-20: Medium blue
-   - 21-50: Dark blue
-   - 51+: Darkest blue
-7. Add hover tooltips:
-   - Show country name and stargazer count
-   - Example: "United States: 45 stargazers"
-8. Add click handler:
-   - Click on country → Filter stargazers table by that country
-   - Navigate to Stargazers page with country filter applied
-9. Add legend showing color scale
-10. All code follows AI standards (<150 lines)
-### Story 6.3: Map Page UI Integration
-**As a** user,
-**I want** a dedicated Map tab in the sidebar,
-**so that** I can view geographic distribution of stargazers.
-**Acceptance Criteria**:
-1. Create `frontend/src/pages/MapPage.tsx` (<100 lines)
-2. Layout:
-   - Header: "Stargazer Distribution"
-   - Subtitle: "Geographic distribution of AgentVibes stargazers"
-   - Filter bar: Contact status filter (All, Contacted, Not Contacted)
-   - Map component (StargazerMap)
-   - Summary stats below map: "Total: X stargazers across Y countries"
-3. Add Map link to sidebar navigation
-4. Fetch map data based on selected filter
-5. Add loading state while map data loads
-6. Add empty state: "No stargazers yet. Sync from GitHub to get started."
-7. Add "Refresh Map" button to refetch data
-8. Use Chakra UI Box, Heading, Text components
-9. All code follows AI standards (<100 lines)
-### Story 6.4: Alternative React Map Library (Fallback)
-**As a** frontend developer,
-**I want** an alternative map implementation using react-simple-maps,
-**so that** I have a React-native solution if Datamaps integration is difficult.
-**Acceptance Criteria**:
-1. Install react-simple-maps: `npm install react-simple-maps`
-2. Create `frontend/src/components/map/SimpleStargazerMap.tsx` (<150 lines)
-3. Use react-simple-maps ComposableMap component:
-   - Projection: geoMercator
-   - Width: 800, Height: 400
-4. Render Geography components for each country:
-   - Fill color based on stargazer count (same scale as Datamaps)
-   - Stroke color: Light gray borders
-5. Add hover effects:
-   - Brighten color on hover
-   - Show tooltip with country name and count
-6. Add click handler (same as Datamaps version)
-7. Compare performance and UX with Datamaps version
-8. Decide which to use based on:
-   - Ease of integration
-   - Visual appeal
-   - Performance
-   - Bundle size
-9. Document decision in `docs/architecture.md`
-10. All code follows AI standards (<150 lines)
----
-## Epic 7: Automation & Monitoring
-**Epic Goal**: Implement automated database backups with 7-day retention, cron-based sync monitoring, optional PiperTTS notifications, comprehensive logging, and health monitoring dashboards.
-### Story 7.1: Automated Database Backups
-**As a** system administrator,
-**I want** daily automated PostgreSQL backups,
-**so that** I can recover data if the database is corrupted or deleted.
-**Acceptance Criteria**:
-1. Create `scripts/backup-db.sh` (executable)
-2. Implement backup logic:
-   - Load env variables from .env
-   - Create `backups/` directory if not exists
-   - Generate timestamp: `YYYYMMDD_HHMMSS`
-   - Run: `docker exec stargazer-cms-postgres pg_dump -U ${DB_USER} ${DB_NAME} > backups/stargazer_cms_${TIMESTAMP}.sql`
-   - Verify backup file created and non-empty
-   - Log success: "Backup created: backups/stargazer_cms_20250110_020000.sql"
-3. Implement retention policy:
-   - Find backups older than 7 days
-   - Delete old backups: `find backups/ -name "*.sql" -mtime +7 -delete`
-   - Log: "Deleted X old backups"
-4. Add error handling:
-   - Exit 1 if pg_dump fails
-   - Log error message
-   - Send notification (optional TTS or email)
-5. Add to crontab (via Docker or host):
-   - Schedule: `0 2 * * *` (daily at 2am)
-   - Log output to `logs/backup.log`
-6. Create `scripts/restore-db.sh` (manual):
-   - Accept backup file path as argument
-   - Run: `docker exec -i stargazer-cms-postgres psql -U ${DB_USER} ${DB_NAME} < $BACKUP_FILE`
-   - Confirm before restoring (requires user input)
-7. Document backup/restore process in README.md
-8. Test: Run backup script manually, verify file created
-9. All code follows AI standards (Bash documentation headers)
-### Story 7.2: Cron Job Management
-**As a** system administrator,
-**I want** all cron jobs (sync, backups) managed in one place,
-**so that** I can easily enable/disable automation.
-**Acceptance Criteria**:
-1. Create `backend/src/jobs/index.ts` (cron job registry)
-2. Register all cron jobs:
-   - Sync job: `0 9 * * *` (daily at 9am)
-   - Email job: `*/5 * * * *` (every 5 minutes)
-3. Add env variables for enabling/disabling jobs:
-   - `ENABLE_CRON_SYNC` (default: true)
-   - `ENABLE_CRON_EMAIL` (default: true)
-4. Log all cron job executions:
-   - Start: "Cron job [name] started"
-   - End: "Cron job [name] completed in Xms"
-   - Errors: "Cron job [name] failed: [error]"
-5. Add graceful shutdown:
-   - Stop all cron jobs on SIGTERM/SIGINT
-   - Wait for running jobs to complete (max 30 seconds)
-6. Add GET /api/cron/status endpoint:
-   - Return: `{jobs: [{name, schedule, enabled, lastRun, nextRun, status}]}`
-   - Status: idle, running, failed
-7. Create Settings screen section for cron jobs:
-   - List all jobs with enable/disable toggles
-   - Show last run time and status
-   - "Run Now" button for manual trigger
-8. Implement PATCH /api/cron/toggle endpoint:
-   - Accept: {jobName, enabled}
-   - Update env variable (persist to .env file)
-   - Restart job if enabled
-9. All code follows AI standards
-### Story 7.3: PiperTTS Notification Plugin
-**As a** user,
-**I want** optional voice notifications when stargazers are synced,
-**so that** I'm alerted to new supporters in real-time.
-**Acceptance Criteria**:
-1. Verify `backend/src/services/notification.service.ts` exists (from Story 2.5)
-2. Implement `notifyNewStargazer(username: string)` function:
-   - Check `ENABLE_TTS` env variable
-   - Check current time against `TTS_QUIET_HOURS` (e.g., "22:00-08:00")
-   - If within quiet hours, skip notification
-   - Construct message: `"New stargazer: ${username}"`
-   - Execute TTS script: `exec(process.env.TTS_SCRIPT_PATH + ' "' + message + '"')`
-   - Catch errors, log to console, don't crash app
-3. Implement `notifySyncComplete(newCount: number)` function:
-   - Message: `"Stargazer sync complete. ${newCount} new stargazers."`
-   - Same TTS logic as above
-4. Implement quiet hours logic:
-   - Parse `TTS_QUIET_HOURS` env var (format: "HH:MM-HH:MM")
-   - Get current time, check if within range
-   - Return true if quiet, false otherwise
-5. Add env variables to `.env.example`:
-   - `ENABLE_TTS=true`
-   - `TTS_QUIET_HOURS=22:00-08:00`
-   - `TTS_SCRIPT_PATH=/home/fire/claude/AgentVibes/.claude/hooks/play-tts.sh`
-6. Add Settings screen toggle:
-   - "Enable TTS Notifications"
-   - Quiet hours time range picker
-7. Unit tests with mocked exec
-8. Manual test: Trigger sync, verify TTS plays (if enabled)
-9. All code follows AI standards
-### Story 7.4: Comprehensive Logging
-**As a** developer,
-**I want** structured logging for all operations (API requests, sync jobs, emails),
-**so that** I can debug issues and monitor system health.
-**Acceptance Criteria**:
-1. Install winston logger: `npm install winston`
-2. Create `backend/src/utils/logger.ts`
-3. Configure Winston logger:
-   - Transports: Console (dev), File (production: `logs/app.log`)
-   - Format: JSON with timestamp, level, message, metadata
-   - Log levels: error, warn, info, debug
-4. Add request logging middleware:
-   - Log all incoming requests: method, path, IP, user agent
-   - Log response: status code, duration
-5. Add error logging middleware:
-   - Log all errors with stack traces
-   - Include request context (method, path, body)
-6. Update all services to use logger:
-   - github.service: Log API calls, rate limit status
-   - sync.service: Log sync start/end, new stargazers count
-   - email.service: Log email sends, failures
-   - spacemail.service: Log API calls, rate limit hits
-7. Add log rotation (winston-daily-rotate-file):
-   - Max file size: 20MB
-   - Max files: 14 days
-   - Compress old logs
-8. Add GET /api/logs endpoint (admin only):
-   - Return last 100 log entries
-   - Filter by level (error, warn, info)
-   - Search by keyword
-9. Create `frontend/src/pages/LogsPage.tsx`:
-   - Display logs in table
-   - Color-code by level (error=red, warn=yellow)
-   - Real-time updates (poll every 5 seconds)
-10. All code follows AI standards
-### Story 7.5: Health Monitoring Dashboard
-**As a** user,
-**I want** a dashboard showing system health and key metrics,
-**so that** I can monitor the application at a glance.
-**Acceptance Criteria**:
-1. Create `frontend/src/pages/DashboardPage.tsx` (<150 lines)
-2. Implement GET /api/health/full endpoint:
-   - Database: connection status, query time
-   - GitHub API: token valid, rate limit remaining
-   - SpaceMail API: credentials valid, rate limit remaining
-   - Disk space: backups folder size, available space
-   - Cron jobs: last run times, statuses
-   - Return: `{services: {database, github, spacemail, disk, cron}}`
-3. Dashboard layout (Chakra UI Grid):
-   - Row 1: Service status cards (4 columns)
-     - Database (green=connected, red=down)
-     - GitHub API (green=ok, yellow=rate limited)
-     - SpaceMail API (green=ok, red=invalid)
-     - Disk Space (green=>1GB, yellow=<1GB, red=<100MB)
-   - Row 2: Quick stats (4 columns)
-     - Total Stargazers
-     - Contacted (%)
-     - Emails Sent (last 7 days)
-     - Last Sync (time ago)
-   - Row 3: Recent activity timeline (full width)
-     - Last 10 events: sync completed, email sent, stargazer added
-4. Add "Refresh" button to refetch health data
-5. Auto-refresh every 30 seconds
-6. Show alerts for unhealthy services:
-   - Red banner at top: "Database connection failed"
-   - Action button: "View Logs" or "Restart Service"
-7. Add link to Dashboard in sidebar (make it default home page)
-8. All code follows AI standards (<150 lines)
----
-## Checklist Results Report
-*(Will be populated after running `pm-checklist` validation)*
----
-## Next Steps
-### UX Expert Prompt
-"Please review the Stargazer CMS PRD (`docs/stargazer-cms-prd.md`) and create a UX architecture document that details:
-1. Complete user flow diagrams for primary workflows (sync → view → compose → send)
-2. Detailed wireframes for each screen (Stargazers table, Profile modal, Email composer, Map, Settings)
-3. Chakra UI component specifications and design tokens
-4. Accessibility checklist ensuring WCAG AA compliance
-5. Responsive breakpoints and mobile considerations
-Focus on creating an efficient, professional CMS interface optimized for desktop usage with local deployment."
-### Architect Prompt
-"Please review the Stargazer CMS PRD (`docs/stargazer-cms-prd.md`) and create a comprehensive architecture document that specifies:
-1. **System Architecture Diagram**: Docker services, network topology, data flow
-2. **Database Schema**: Detailed Prisma schema with indexes, constraints, relationships
-3. **API Specification**: Complete OpenAPI/Swagger documentation for all endpoints
-4. **Component Architecture**: Frontend component hierarchy, state management, routing
-5. **Infrastructure Setup**: Docker Compose configuration, environment variables, volume mappings
-6. **Code Quality Configuration**: SonarQube rules, ESLint config, TypeScript strict settings, pre-commit hooks
-7. **Testing Strategy**: Unit, integration, E2E test structure and tooling
-8. **Security Architecture**: Authentication, input validation, API key management
-9. **Deployment Guide**: Local setup instructions, backup/restore procedures, troubleshooting
-Ensure all code follows AI-optimized documentation standards defined in `/home/fire/claude/AgentVibes/docs/ai-optimized-documentation-standards.md`. All components must adhere to single-responsibility principle with max 200 lines per file and max 50 lines per function."
----
-## Document Information
-**AgentVibes Stargazer CMS - Product Requirements Document**
-- **Project**: AgentVibes Stargazer Content Management System
-- **Repository**: agentvibes-stargazers (Private)
-- **Co-created by**: John (PM Agent) with Paul Preibisch
-- **Version**: 1.0
-- **Created**: 2025-01-10
-- **License**: Apache-2.0
----
-**DISCLAIMER**: This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND, express or implied. Use at your own risk. See the Apache License for details.