myaidev-method 0.2.22 → 0.2.24-1

package/USER_GUIDE.md

@@ -7,6 +7,7 @@ This guide covers everything you need to know about using, customizing, and exte
 ## 📋 Table of Contents
 
 - [Quick Start](#quick-start)
+- [System Configuration](#-system-configuration)
 - [Updating MyAIDev Method](#-updating-myaidev-method)
 - [Understanding the Structure](#understanding-the-structure)
 - [👤 User Pathways](#-user-pathways)
@@ -19,6 +20,8 @@ This guide covers everything you need to know about using, customizing, and exte
 - [Managing Commands](#managing-commands)
 - [WordPress Integration](#wordpress-integration)
 - [PayloadCMS Integration](#payloadcms-integration)
+- [Visual Generation](#-visual-generation)
+- [Content Rules & Brand Voice](#-content-rules--brand-voice)
 - [SSH Configuration](#ssh-configuration)
 - [Agent Management](#agent-management)
 - [Troubleshooting](#troubleshooting)
@@ -79,6 +82,24 @@ You'll have a `.claude` folder in your project:
 └── CLAUDE.md         # Project configuration
 ```
 
+### First-Time Setup
+
+Use the interactive configuration command to set up your environment—no manual `.env` editing required:
+
+```bash
+# Configure WordPress integration
+/myai-configure wordpress
+
+# Configure OpenStack (if using VM management)
+/myai-configure openstack
+
+# Configure default content settings
+/myai-configure defaults
+
+# Set up content rules for brand voice
+/myai-content-rules-setup
+```
+
 ### Immediate Usage
 
 ```bash
@@ -99,6 +120,101 @@ You'll have a `.claude` folder in your project:
 /myai-configure agents --list
 ```
 
+## ⚙️ System Configuration
+
+MyAIDev Method uses the `/myai-configure` command for interactive setup—**no manual `.env` file editing required**. This is the recommended way to configure all integrations.
+
+### Available Configuration Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/myai-configure wordpress` | Set up WordPress publishing integration |
+| `/myai-configure openstack` | Configure OpenStack VM management |
+| `/myai-configure defaults` | Set default content settings, visual generation API keys |
+| `/myai-configure agents` | List, validate, backup, and manage agents |
+| `/myai-content-rules-setup` | Interactive brand voice and content rules setup |
+
+### WordPress Configuration
+
+```bash
+/myai-configure wordpress
+```
+
+**What it does:**
+- Prompts for WordPress URL and validates connectivity
+- Guides you through Application Password creation step-by-step
+- Tests the connection before saving
+- Automatically creates `.env` with secure permissions (600)
+- Optionally configures SSH for advanced administration
+
+### OpenStack Configuration
+
+```bash
+/myai-configure openstack
+```
+
+**What it does:**
+- Can import settings from an existing `openrc` file
+- Or prompts for each credential manually
+- Tests connection with `openstack token issue`
+- Optionally sets up default cloud-init scripts
+- Saves all credentials securely to `.env`
+
+### Visual Generation & Defaults
+
+```bash
+/myai-configure defaults
+```
+
+**What it does:**
+- Configures visual generation API keys (Gemini, OpenAI, Replicate)
+- Sets your preferred default visual service
+- Configures default content settings (word count, tone, audience)
+
+### Agent Management
+
+```bash
+# List all agents
+/myai-configure agents --list
+
+# Check agent health
+/myai-configure agents --status
+
+# Validate specific agent
+/myai-configure agents --validate content-writer
+
+# Create backup before editing
+/myai-configure agents --backup content-writer
+
+# Show agent capabilities
+/myai-configure agents --tools wordpress-admin
+```
+
+### Manual Configuration (Alternative)
+
+If you prefer manual setup, create a `.env` file in your project root:
+
+```bash
+# WordPress
+WORDPRESS_URL=https://your-site.com
+WORDPRESS_USERNAME=your-username
+WORDPRESS_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
+
+# Visual Generation (at least one required)
+GEMINI_API_KEY=your-gemini-key
+OPENAI_API_KEY=your-openai-key
+REPLICATE_API_TOKEN=your-replicate-token
+VISUAL_DEFAULT_SERVICE=gemini
+
+# OpenStack (optional)
+OS_AUTH_URL=https://cloud.example.com:5000/v3
+OS_USERNAME=your-username
+OS_PASSWORD=your-password
+OS_PROJECT_ID=your-project-id
+```
+
+> ⚠️ **Security**: The `.env` file contains sensitive credentials. Never commit it to version control. The `/myai-configure` commands automatically set secure file permissions (600).
+
 ## 🔄 Updating MyAIDev Method
 
 The MyAIDev Method package receives regular updates with new features, bug fixes, and improved agents. Keep your installation up to date to access the latest capabilities.
@@ -389,11 +505,20 @@ done
 
 #### Publishing Configuration
 
-Set up your publishing credentials once:
+Set up your publishing credentials once using the interactive configuration:
+
+```bash
+# Configure WordPress (recommended - no manual .env editing)
+/myai-configure wordpress
+
+# Configure default content settings
+/myai-configure defaults
+```
+
+**Or manually configure `.env`:**
 
 **WordPress**:
 ```bash
-# .env configuration
 WORDPRESS_URL=https://yoursite.com
 WORDPRESS_USERNAME=your-username
 WORDPRESS_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
@@ -401,7 +526,6 @@ WORDPRESS_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
 
 **PayloadCMS**:
 ```bash
-# .env configuration
 PAYLOADCMS_URL=https://cms.yoursite.com
 PAYLOADCMS_EMAIL=your-email@example.com
 PAYLOADCMS_PASSWORD=your-password
@@ -1060,11 +1184,11 @@ cat .claude/commands/myai-content-writer.md
 **Best Practice:** Use `content-rules.md` for content customization instead of editing agents directly.
 
 ```bash
-# Copy the example template
-cp content-rules.example.md content-rules.md
+# Use interactive setup (recommended)
+/myai-content-rules-setup
 
-# Edit with your preferences
-nano content-rules.md
+# Or copy the example template
+cp content-rules.example.md content-rules.md
 ```
 
 **Why use content-rules.md?**
@@ -1074,41 +1198,7 @@ nano content-rules.md
 - ✅ Project-specific customization
 - ✅ Works even if file doesn't exist
 
-**Example content-rules.md:**
-
-```markdown
-# Content Generation Rules
-
-## Brand Voice
-- Use conversational, friendly tone
-- Avoid jargon unless explaining technical concepts
-- Include real-world examples
-
-## Formatting Preferences
-- Keep paragraphs under 3 sentences
-- Use numbered lists for sequential steps
-- Include code examples for technical content
-
-## SEO Guidelines
-- Target keyword density: 1-2%
-- Include FAQ section for articles over 1000 words
-- Add "Related Resources" section at the end
-
-## Required Elements
-- Author bio at the end
-- Call-to-action in conclusion
-- Technical accuracy verification
-```
-
-**What you can customize:**
-- Brand voice and tone
-- Writing style preferences
-- Formatting guidelines
-- SEO requirements
-- Required/optional content elements
-- Topics to avoid
-- Company-specific terminology
-- Content structure preferences
+> 📖 **See [Content Rules & Brand Voice](#-content-rules--brand-voice)** for comprehensive documentation on setting up brand voice, writing style, SEO guidelines, and more.
 
 ### Customizing Commands (Advanced)
 
@@ -1172,18 +1262,25 @@ Save as markdown with:
 
 ### Initial Setup
 
-Use the interactive configuration command to set up WordPress:
+**Option 1: Interactive Setup (Recommended)**
+
+Use the interactive configuration command—no manual `.env` editing required:
 
 ```bash
 /myai-configure wordpress
 ```
 
-This will guide you through:
-- WordPress site URL
-- Username  
-- Application Password creation
+This guided wizard will:
+1. Prompt for your WordPress site URL and validate connectivity
+2. Collect your WordPress username
+3. Walk you through creating an Application Password with step-by-step instructions
+4. Test the connection and verify everything works
+5. Automatically save credentials to `.env` with secure permissions (600)
+6. Optionally set up SSH for advanced administration features
+
+**Option 2: Manual `.env` Setup**
 
-**Alternative manual setup**:
+If you prefer manual configuration:
 1. Create `.env` file in your project root
 2. Add your WordPress credentials:
    ```bash
@@ -1280,6 +1377,314 @@ Content goes here...
 /myai-configure defaults
 ```
 
+## 🎨 Visual Generation
+
+MyAIDev Method includes AI-powered visual generation capabilities for creating images and videos to accompany your content.
+
+### Available Services
+
+| Service | Provider | Best For | API Key Required |
+|---------|----------|----------|------------------|
+| **Gemini Nano Banana** | Google | General images, diagrams, infographics | `GEMINI_API_KEY` |
+| **GPT Image 1.5** | OpenAI | Realistic images, text rendering | `OPENAI_API_KEY` |
+| **FLUX 2 Pro** | Replicate | Artistic images, creative styles | `REPLICATE_API_TOKEN` |
+| **Veo 3** | Google | Video generation | `GEMINI_API_KEY` |
+
+### Model Strengths & Use Cases
+
+**Gemini Nano Banana (Google)**
+- ✅ Excellent text rendering in images
+- ✅ Great for infographics and data visualizations
+- ✅ Good balance of quality and speed
+- ✅ Cost-effective for high volume
+- Best for: Technical diagrams, infographics, educational content
+
+**GPT Image 1.5 (OpenAI)**
+- ✅ Excellent text rendering accuracy
+- ✅ High-quality realistic images
+- ✅ Strong prompt following
+- ✅ Good for complex scenes with text
+- Best for: Marketing materials, product visuals, detailed illustrations
+
+**FLUX 2 Pro (Replicate)**
+- ✅ Exceptional artistic quality
+- ✅ Unique creative styles
+- ✅ Great for abstract and artistic imagery
+- ❌ Less reliable for text in images
+- Best for: Creative content, artistic blog headers, brand imagery
+
+**Veo 3 (Google)**
+- ✅ Video generation capability
+- ✅ Good for short promotional clips
+- Best for: Social media videos, product demos, animated content
+
+### Service Selection
+
+The visual generation system automatically selects which service to use based on:
+
+1. **Available API Keys**: Only services with valid API keys are considered
+2. **User Preference**: Your `VISUAL_DEFAULT_SERVICE` setting takes priority
+3. **Fallback**: Uses the first available service if no preference is set
+
+### Configuration
+
+**Option 1: Interactive Setup (Recommended)**
+
+Use the configure command for guided setup:
+
+```bash
+/myai-configure defaults
+```
+
+This will prompt you to configure:
+- Visual generation API keys
+- Default visual service preference
+- Output directory settings
+
+**Option 2: Manual `.env` Configuration**
+
+Add API keys directly to your `.env` file:
+
+```bash
+# Required: At least one of these
+GEMINI_API_KEY=your-gemini-api-key
+OPENAI_API_KEY=your-openai-api-key
+REPLICATE_API_TOKEN=your-replicate-token
+
+# Optional: Set your preferred default service
+VISUAL_DEFAULT_SERVICE=gemini  # Options: gemini, gpt-image-1.5, flux
+
+# Optional: Custom output directory (default: ./generated-visuals)
+VISUAL_OUTPUT_DIR=./my-custom-output-path
+```
+
+### Usage Examples
+
+```bash
+# Generate image using default/preferred service
+/myai-content-writer "Blog post about Docker" --generate_visual true
+
+# Generate specific visual type
+node .myaidev-method/scripts/generate-visual-cli.js --type infographic-data "Cloud Cost Comparison"
+
+# Generate with specific service
+node .myaidev-method/scripts/generate-visual-cli.js --service gpt-image-1.5 "Product feature diagram"
+
+# Generate video (uses Veo 3)
+node .myaidev-method/scripts/generate-visual-cli.js --type video "Product demo animation"
+```
+
+### Visual Types
+
+| Type | Description | Recommended Service |
+|------|-------------|---------------------|
+| `hero` | Blog post header images | Gemini or GPT Image 1.5 |
+| `infographic-data` | Data visualization | Gemini or GPT Image 1.5 |
+| `infographic-comparison` | Comparison charts | Gemini or GPT Image 1.5 |
+| `diagram` | Technical diagrams | Gemini |
+| `product` | Product imagery | GPT Image 1.5 |
+| `video` | Short video clips | Veo 3 |
+
+### Troubleshooting Visual Generation
+
+**No services available**:
+```bash
+# Check your API keys are set
+cat .env | grep -E "(GEMINI|OPENAI|REPLICATE)"
+
+# Test a specific service
+node .myaidev-method/scripts/generate-visual-cli.js --service gemini "Test image"
+```
+
+**Service selection not working**:
+```bash
+# Set explicit default service
+echo "VISUAL_DEFAULT_SERVICE=gemini" >> .env
+```
+
+## 📝 Content Rules & Brand Voice
+
+The `content-rules.md` file is a powerful customization system that controls how AI-generated content matches your brand voice, style, and requirements—without modifying agent files.
+
+### Why Content Rules Matter
+
+Content rules provide a **non-destructive** way to customize all content generation:
+
+| Benefit | Description |
+|---------|-------------|
+| **Preserves Updates** | Customize without editing agents—your rules survive package updates |
+| **Brand Consistency** | Define voice, tone, and style once, apply everywhere |
+| **Project-Specific** | Each project can have its own content rules |
+| **Easy to Share** | Version control your brand guidelines with your project |
+| **Fallback Safe** | Works even if the file doesn't exist (uses sensible defaults) |
+
+### Setting Up Content Rules
+
+**Option 1: Interactive Setup (Recommended)**
+
+Use the content rules setup command for guided configuration:
+
+```bash
+/myai-content-rules-setup
+```
+
+This interactive wizard will guide you through:
+1. **Brand Identity**: Company name, values, mission
+2. **Voice & Tone**: Personality, communication style
+3. **Writing Style**: Formality, sentence structure, vocabulary
+4. **SEO Guidelines**: Keyword density, meta requirements
+5. **Formatting**: Structure preferences, visual elements
+6. **Audience**: Target demographics and expertise level
+
+**Option 2: Copy Template**
+
+```bash
+# Copy the example template
+cp content-rules.example.md content-rules.md
+
+# Edit with your preferences
+nano content-rules.md
+```
+
+### What You Can Customize
+
+**1. Brand Voice**
+```markdown
+## Brand Voice
+- **Personality**: Professional yet approachable
+- **Values**: Innovation, reliability, simplicity
+- **Tone**: Confident, helpful, forward-thinking
+- **Language Style**: Clear, jargon-free unless technical audience
+```
+
+**2. Writing Style**
+```markdown
+## Writing Style
+- **Formality**: Semi-formal (conversational but professional)
+- **Person**: Second person ("you") for tutorials, first plural ("we") for company
+- **Sentence Length**: Varied, average 15-20 words
+- **Paragraph Length**: Maximum 3-4 sentences
+- **Active Voice**: Preferred over passive
+```
+
+**3. SEO Requirements**
+```markdown
+## SEO Guidelines
+- **Keyword Density**: 1-2% of total word count
+- **Meta Description**: 150-160 characters, include primary keyword
+- **Headers**: Include keywords in H1 and at least one H2
+- **Internal Links**: Minimum 2-3 per 1000 words
+- **External Links**: 1-2 authoritative sources per article
+```
+
+**4. Formatting Preferences**
+```markdown
+## Formatting Rules
+- **Lists**: Use bullet points for features, numbered for steps
+- **Code Blocks**: Always include language identifier
+- **Images**: Include alt text and captions
+- **Callouts**: Use blockquotes for important notes
+- **Tables**: Use for comparisons and data presentation
+```
+
+**5. Content Structure**
+```markdown
+## Structure Guidelines
+- **Introduction**: Hook + context + article overview (150-200 words)
+- **Body**: Clear sections with descriptive headers
+- **Conclusion**: Summary + call-to-action
+- **FAQ Section**: Include for articles over 1500 words
+```
+
+**6. Topics & Restrictions**
+```markdown
+## Content Boundaries
+### Topics to Emphasize
+- Product benefits and use cases
+- Industry best practices
+- Customer success stories
+
+### Topics to Avoid
+- Competitor comparisons (unless specifically requested)
+- Speculative pricing
+- Unverified claims
+```
+
+### Content Rules in Action
+
+When you run any content generation command, the system:
+
+1. **Checks for `content-rules.md`** in your project root
+2. **Parses your customizations** and applies them to generation
+3. **Falls back to defaults** for any unspecified settings
+
+**Example with content rules**:
+```bash
+# With content-rules.md specifying technical voice
+/myai-content-writer "Docker Container Best Practices"
+
+# Output will follow your defined:
+# - Brand voice (e.g., professional, technically accurate)
+# - Structure (e.g., code examples required)
+# - SEO guidelines (e.g., specific keyword density)
+# - Formatting (e.g., numbered steps for procedures)
+```
+
+### Example content-rules.md
+
+```markdown
+# Content Generation Rules
+
+## Brand Identity
+- **Company**: TechStartup Inc.
+- **Mission**: Simplifying cloud infrastructure for developers
+- **Values**: Transparency, developer experience, reliability
+
+## Voice & Tone
+- Professional yet friendly
+- Technical but accessible
+- Confident without being arrogant
+- Helpful and educational
+
+## Writing Style
+- Use "you" when addressing the reader
+- Keep sentences concise (max 25 words)
+- Explain jargon on first use
+- Use analogies for complex concepts
+
+## SEO Guidelines
+- Primary keyword in title and first 100 words
+- Include 3-5 related secondary keywords
+- Meta description: 155 characters max
+- Add FAQ section for articles 1500+ words
+
+## Formatting
+- Start with a compelling hook
+- Use headers every 300-400 words
+- Include code examples for technical topics
+- End with clear call-to-action
+
+## Required Elements
+- Author attribution
+- Last updated date
+- Related articles section
+- Share buttons callout
+
+## Restrictions
+- No competitor mentions by name
+- No pricing information in blog posts
+- No unverified performance claims
+```
+
+### Best Practices for Content Rules
+
+1. **Start with the template**: Use `/myai-content-rules-setup` to generate a starting point
+2. **Iterate gradually**: Start with basic rules, refine based on output
+3. **Be specific**: Vague rules produce inconsistent results
+4. **Include examples**: Show what good vs. bad looks like
+5. **Version control**: Track changes to your content rules over time
+6. **Team alignment**: Share content rules across your team for consistency
+
 ## 💻 SSH Configuration
 
 ### Setup Options