Adds AI-powered PRD generation with OpenAI integration

Enhances the issue PRD generator with GPT-4 capabilities for creating comprehensive product requirement documents. Introduces OpenAI API integration with configurable models and temperature settings.

Adds PlantUML diagram generation for visual documentation and automatic PNG export when plantuml is available. Implements force regeneration mode to update existing PRDs and issue bodies.

Updates all existing PRD files with hacktoberfest labels and AI-generated content that provides more detailed technical specifications, implementation approaches, and acceptance criteria.

Includes OpenAI API key configuration in environment setup and comprehensive error handling for AI generation fallbacks.

Author: ralyodio

apps/web/.env.example

@@ -9,6 +9,8 @@ PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
 DATABASE_URL=postgresql://postgres:password@host:5432/postgres
 SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
 
+OPENAI_API_KEY=your-openai-apikey
+
 # Application Settings
 ORIGIN=https://your-service.up.railway.app
 PORT=8080

docs/PLANTUML_SETUP.md

@@ -0,0 +1,162 @@
+# PlantUML Setup Guide
+
+This guide explains how to install PlantUML to enable automatic PNG generation from `.puml` diagram files.
+
+## What is PlantUML?
+
+PlantUML is an open-source tool that allows you to create diagrams from plain text descriptions. The PRD generator creates `.puml` files automatically, and with PlantUML installed, it can also generate `.png` images.
+
+## Installation Options
+
+### Option 1: Using Package Managers (Recommended)
+
+#### macOS (Homebrew)
+```bash
+brew install plantuml
+```
+
+#### Ubuntu/Debian
+```bash
+sudo apt-get update
+sudo apt-get install plantuml
+```
+
+#### Arch Linux
+```bash
+sudo pacman -S plantuml
+```
+
+#### Windows (Chocolatey)
+```bash
+choco install plantuml
+```
+
+### Option 2: Manual Installation
+
+1. **Install Java** (PlantUML requires Java 8 or higher)
+   ```bash
+   # Check if Java is installed
+   java -version
+   
+   # If not installed, install Java
+   # Ubuntu/Debian:
+   sudo apt-get install default-jre
+   
+   # macOS:
+   brew install openjdk
+   ```
+
+2. **Download PlantUML JAR**
+   - Download from: https://plantuml.com/download
+   - Save `plantuml.jar` to a convenient location (e.g., `/usr/local/bin/`)
+
+3. **Create a wrapper script** (optional, for easier usage)
+   ```bash
+   # Create script at /usr/local/bin/plantuml
+   sudo nano /usr/local/bin/plantuml
+   ```
+   
+   Add this content:
+   ```bash
+   #!/bin/bash
+   java -jar /usr/local/bin/plantuml.jar "$@"
+   ```
+   
+   Make it executable:
+   ```bash
+   sudo chmod +x /usr/local/bin/plantuml
+   ```
+
+## Verify Installation
+
+```bash
+plantuml -version
+```
+
+You should see output like:
+```
+PlantUML version 1.2023.XX
+```
+
+## Usage with PRD Generator
+
+Once PlantUML is installed, the PRD generator will automatically:
+
+1. Generate `.puml` source files
+2. Convert them to `.png` images
+3. Save both files to `docs/PRDs/`
+
+### Generate PRDs with Diagrams
+
+```bash
+# With PlantUML installed, this will create both .puml and .png files
+node scripts/generate-issue-prds.mjs --use-ai --diagrams --force
+```
+
+### Manual PNG Generation
+
+If you want to manually convert `.puml` files to PNG:
+
+```bash
+# Convert a single file
+plantuml docs/PRDs/221-demo-workflows.puml
+
+# Convert all .puml files in a directory
+plantuml docs/PRDs/*.puml
+
+# Specify output format
+plantuml -tpng docs/PRDs/221-demo-workflows.puml
+plantuml -tsvg docs/PRDs/221-demo-workflows.puml
+```
+
+## Alternative: Online PlantUML Editor
+
+If you don't want to install PlantUML locally, you can:
+
+1. Open the `.puml` file in a text editor
+2. Copy the content
+3. Paste it into the online editor: http://www.plantuml.com/plantuml/uml/
+4. Download the generated PNG/SVG
+
+## Troubleshooting
+
+### "plantuml: command not found"
+
+This means PlantUML is not installed or not in your PATH. Follow the installation steps above.
+
+### "Java not found"
+
+PlantUML requires Java. Install Java first:
+```bash
+# Check Java version
+java -version
+
+# Install if needed (Ubuntu/Debian)
+sudo apt-get install default-jre
+```
+
+### Diagrams not rendering correctly
+
+1. Check the `.puml` file syntax
+2. Try generating manually: `plantuml yourfile.puml`
+3. Check PlantUML documentation: https://plantuml.com/
+
+## Benefits of PNG Generation
+
+- **Visual Documentation**: Easy to view diagrams without special tools
+- **GitHub Integration**: PNG files display directly in GitHub
+- **Presentations**: Ready-to-use images for documentation and presentations
+- **Accessibility**: Anyone can view the diagrams without PlantUML
+
+## Note
+
+The PRD generator works perfectly fine without PlantUML installed. You'll still get:
+- ✅ Comprehensive PRD markdown files
+- ✅ PlantUML source files (`.puml`)
+- ❌ PNG images (requires PlantUML)
+
+The `.puml` files can be:
+- Viewed in VS Code with PlantUML extensions
+- Converted to PNG later when needed
+- Shared with team members who have PlantUML installed
+- Used in the online PlantUML editor

docs/PRDs/194-contributing-guide.md

@@ -1,176 +1,109 @@
 # PRD: Contributing guide
 
-**Issue:** [#194](https://github.com/profullstack/meshhook/issues/194)  
-**Milestone:** Phase 8: Documentation  
-**Labels:** developer-documentation  
-**Phase:** Phase 8  
-**Section:** Developer Documentation
+**Issue:** [#194](https://github.com/profullstack/meshhook/issues/194)
+**Milestone:** Phase 8: Documentation
+**Labels:** developer-documentation, hacktoberfest
 
 ---
 
-## Overview
-
-This task is part of Phase 8 in the Developer Documentation section of the MeshHook project. 
+# PRD: Contributing Guide
 
-**MeshHook** is a webhook-first, deterministic, Postgres-native workflow engine that delivers n8n's visual simplicity and Temporal's durability without restrictive licensing.
+**Issue:** [#194: Contributing guide](https://github.com/profullstack/meshhook/issues/194)  
+**Milestone:** Phase 8: Documentation  
+**Labels:** developer-documentation, hacktoberfest  
+**Phase:** Phase 8  
+**Section:** Developer Documentation
 
-**Task Objective:** Contributing guide
+## Overview
 
-This implementation should align with the project's core goals of providing:
-- Webhook triggers with signature verification
-- Visual DAG builder using SvelteKit/Svelte 5
-- Durable, replayable runs via event sourcing
-- Live logs via Supabase Realtime
-- Multi-tenant RLS security
+The objective of this task is to develop a comprehensive Contributing Guide for the MeshHook project. This guide aims to standardize the contribution process, making it easier for developers to understand how they can contribute to the project effectively. Aligning with MeshHook's core goals, this document should facilitate contributions that enhance the project's webhook triggers, visual DAG builder, durability, live logging capabilities, and security features.
 
 ## Requirements
 
 ### Functional Requirements
 
-1. Implement the core functionality described in the task: "Contributing guide"
-2. Create reusable Svelte 5 components
-3. Implement responsive design for mobile and desktop
-4. Follow project UI/UX patterns and styling
-5. Document all public APIs and interfaces
-6. Follow project coding standards and best practices
-
+1. **Guide Structure:** Structure the guide to include introduction, setup instructions, contribution process, coding standards, and how to submit a pull request.
+2. **Setup Instructions:** Provide detailed setup instructions for local development, including required software and environment setup.
+3. **Contribution Process:** Outline the steps for making contributions, including branching strategies, commit message conventions, and pull request guidelines.
+4. **Coding Standards:** Document coding standards specific to SvelteKit/Svelte 5, Postgres, and other technologies used in the project.
+5. **Testing Guidelines:** Include guidelines for writing tests, along with how to run and verify them before submission.
+6. **Documentation Standards:** Set expectations for documenting new features or changes to the API and codebase.
 
 ### Non-Functional Requirements
 
-- **Performance:** Maintain sub-second response times for user-facing operations
-- **Reliability:** Ensure 99.9% uptime with proper error handling and recovery
-- **Security:** Follow project security guidelines (RLS, secrets management, audit logging)
-- **Maintainability:** Write clean, well-documented code following project conventions
+- **Usability:** The guide should be clear, concise, and easy to follow for contributors with various levels of experience.
+- **Accessibility:** Ensure the contributing guide is accessible to a diverse group of developers, including those using assistive technologies.
+- **Maintainability:** The guide should be easy to update as project standards and technologies evolve.
 
 ## Technical Specifications
 
 ### Architecture Context
 
-- **SvelteKit (SSR/API)**: webhook intake, workflow CRUD, publish versions, run console.
-- **Supabase**: Postgres (data + queues), Realtime (log streaming), Storage (artifacts), Edge (cron/timers).
-- **Workers**: Orchestrator (state machine + scheduling) and HTTP Executor (robust HTTP with retries/backoff).
+The Contributing Guide does not directly impact the architecture of MeshHook but is crucial for maintaining the project's overall quality and consistency. It should align with the technical stack of MeshHook, including SvelteKit/Svelte 5 for the frontend, Postgres for data storage, and Supabase for real-time capabilities.
 
 ### Implementation Approach
 
-The implementation should follow these steps:
-
-1. **Analysis:** Review existing codebase and identify integration points
-2. **Design:** Create detailed technical design considering:
-   - Data structures and schemas
-   - API contracts and interfaces
-   - Component architecture
-   - Error handling strategies
-3. **Implementation:** Write code following TDD approach:
-   - Write tests first
-   - Implement minimal code to pass tests
-   - Refactor for clarity and performance
-4. **Integration:** Ensure seamless integration with existing components
-5. **Testing:** Comprehensive testing at all levels
-6. **Documentation:** Update relevant documentation
-7. **Review:** Code review and feedback incorporation
-
-**Key Considerations:**
-- Maintain backward compatibility where applicable
-- Follow event sourcing patterns for state changes
-- Use Postgres for durable storage
-- Implement proper error handling and logging
-- Consider rate limiting and resource constraints
+1. **Research:** Review contributing guides from similar open-source projects to identify best practices.
+2. **Drafting:** Start with a basic structure and iteratively add sections focusing on setup, contribution process, coding standards, testing, and documentation.
+3. **Feedback Loop:** Share drafts with the core development team to gather feedback and make adjustments.
+4. **Finalization:** Incorporate all feedback, ensuring the guide is comprehensive and aligns with project goals.
+5. **Publishing:** Make the guide available in the project's repository and ensure it's easily discoverable for new contributors.
 
 ### Data Model
 
-No new data model changes required for this task. If data model changes are needed during implementation, update `schema.sql` and document changes here.
+N/A
 
-### API Endpoints (if applicable)
+### API Endpoints
 
-No new API endpoints required for this task.
+N/A
 
 ## Acceptance Criteria
 
-- [ ] Core functionality implemented and working as described
-- [ ] All tests passing (unit, integration, e2e where applicable)
-- [ ] Code follows project conventions and passes linting
-- [ ] Documentation updated (code comments, README, API docs)
-- [ ] Security considerations addressed (RLS, input validation, etc.)
-- [ ] Performance requirements met (response times, resource usage)
-- [ ] Error handling implemented with clear error messages
-- [ ] Changes reviewed and approved by team
-- [ ] No breaking changes to existing functionality
-- [ ] Database migrations created if schema changes made
-- [ ] Manual testing completed in development environment
-
-**Definition of Done:**
-- Code merged to main branch
-- All CI/CD checks passing
-- Documentation complete and accurate
-- Ready for deployment to production
+- [ ] Contributing guide includes all sections as outlined in the functional requirements.
+- [ ] The guide is reviewed and approved by the project's core development team.
+- [ ] The guide is committed to the project's repository in an easily discoverable location.
+- [ ] The guide meets usability and accessibility standards, ensuring it is clear and easy to follow.
 
 ## Dependencies
 
-### Technical Dependencies
-
-- Existing codebase components
-- Database schema (see schema.sql)
-- External services: Supabase (Postgres, Realtime, Storage)
-
-### Prerequisite Tasks
-
-- Previous phase tasks completed
-- Dependencies installed and configured
-- Development environment ready
-- Access to required services (Supabase, etc.)
+- **Technical Dependencies:** Familiarity with the project's existing documentation structure and standards.
+- **Prerequisite Tasks:** None.
 
 ## Implementation Notes
 
 ### Development Guidelines
 
-1. Follow ESM module system (Node.js 20+)
-2. Use modern JavaScript (ES2024+) features
-3. Implement comprehensive error handling
-4. Write tests before implementation (TDD)
-5. Ensure code passes ESLint and Prettier checks
+- Use Markdown format for the guide to ensure it's readable both in plaintext and rendered on GitHub.
+- Include examples where applicable, especially for complex setup instructions or contribution steps.
+- Ensure all instructions are tested to prevent errors or confusion.
 
 ### Testing Strategy
 
-- **Unit Tests:** Test individual functions and modules
-- **Integration Tests:** Test component interactions
-- **E2E Tests:** Test complete user workflows (where applicable)
+- **Peer Review:** Have multiple project contributors follow the guide to set up their development environment and make a sample contribution.
+- **Iteration:** Use feedback from the testing phase to refine and update the guide.
 
 ### Security Considerations
 
-- RLS by `project_id`.
-- Secrets AES-GCM with KEK rotation.
-- Audit log for admin actions & secret access.
-- PII redaction rules.
+- Highlight security practices contributors should follow, especially regarding handling secrets or sensitive information.
+- Include guidelines for responsible disclosure of security vulnerabilities.
 
 ### Monitoring & Observability
 
-- Add appropriate logging for debugging
-- Track key metrics (response times, error rates)
-- Set up alerts for critical failures
-- Use Supabase Realtime for live updates where needed
+N/A
 
 ## Related Documentation
 
-- [Main PRD](../PRD.md)
+- [MeshHook — PRD](../PRD.md)
 - [Architecture](../Architecture.md)
-- [Security Guidelines](../Security.md)
-- [Operations Guide](../Operations.md)
+- [Security & Multi-Tenancy](../Security.md)
 
 ## Task Details
 
-**Original Task Description:**
-Contributing guide
+**Original Task Description:** Contributing guide
 
-**Full Issue Body:**
-**Phase:** Phase 8
-**Section:** Developer Documentation
-
-**Task:** Contributing guide
-
----
-_Auto-generated from TODO.md_
+*This PRD was carefully crafted to ensure that the Contributing Guide will be an invaluable resource for new and existing contributors, fostering a collaborative and productive development environment for the MeshHook project.*
 
 ---
 
-*This PRD was auto-generated from GitHub issue #194*  
-*Last updated: 2025-10-10*
+*This PRD was AI-generated using gpt-4-turbo-preview from GitHub issue #194*
+*Generated: 2025-10-10*