first commit all files

2026-01-28 00:26:00 +07:00
parent 65dd207a74
commit 97426d5ab1
72 changed files with 91484 additions and 0 deletions
--- a/brief.md
+++ b/brief.md
@@ -0,0 +1,716 @@
+# WP Agentic Writer - Development Brief
+
+**Product Name:** WP Agentic Writer  
+**Tagline:** Plan-first AI writing workflow for WordPress  
+**Target Users:** Developers, Technical Writers, Content Creators who struggle with blogging  
+**Status:** MVP Development  
+**Date Created:** January 17, 2026
+
+---
+
+## 🎯 Product Overview
+
+**WP Agentic Writer** is a WordPress plugin that transforms how developers and technical writers create blog posts. Instead of the traditional "blank page → write → edit" workflow, it implements a **multi-phase agentic AI workflow**:
+
+```
+Scribble (Ideas) → Research → Plan (Outline) → Execute (Write) → Discussion/Revise
+```
+
+**Key Insight:** Most developers never write articles because writing feels separate from coding. This plugin makes the workflow feel like coding—iterative, phase-based, with revision at every step.
+
+---
+
+## 📋 Core Features (MVP)
+
+### Phase 1: Brainstorm & Scribble
+- **User inputs:** Raw notes, code snippets, PR description, or vague idea
+- **AI does:** Clarifies the angle, suggests what problem this solves
+- **Output:** Structured brainstorm notes
+
+### Phase 2: Research
+- **User inputs:** Confirms the angle or edits AI suggestions
+- **AI does:** Generates research queries, pulls relevant information (optional web search)
+- **Output:** Research notes, citations, key points
+- **Display:** Real-time cost tracking
+- **Web Search:** Optional toggle using OpenRouter's built-in web search (:online models)
+
+### Phase 3: Plan (Outline)
+- **User inputs:** Reviews outline, suggests sections to add/remove/reorganize
+- **AI does:** Structures as JSON with H2 sections, suggests code examples
+- **Output:** Plan JSON (see structure below)
+- **Cost:** Minimal (using fast, cheap model like Gemini Flash)
+
+### Phase 4: Execute (Auto-Write)
+- **User inputs:** Approves plan, clicks "Execute"
+- **AI does:** Generates final article with:
+  - Paragraph blocks
+  - Code blocks (with language detection)
+  - Optional image prompts
+- **Output:** Gutenberg blocks inserted into editor canvas
+- **Cost:** Higher quality model (Claude Opus) for best output
+
+### Phase 5: Discuss & Revise
+- **User inputs:** Click "Regenerate Section" on any block
+- **AI does:** Re-generates just that block based on selected text context
+- **Features:**
+  - Section-level chat
+  - Line-by-line refinement
+  - Change entire paragraphs or code blocks
+
+---
+
+## 💰 Cost Architecture
+
+### Models Strategy
+
+**Planning Model:** `google/gemini-3-flash` (Free on OpenRouter)
+- Cost: ~$0.0007 per planning session
+- Speed: Very fast
+- Quality: Good enough for outlining
+
+**Execution Model:** `anthropic/claude-4-opus` (Paid on OpenRouter)
+- Cost: ~$0.633 per full article write
+- Speed: Medium
+- Quality: Excellent prose, code understanding
+
+**Image Generation Model:** `black-forest-labs/flux-schnell` (via fal.ai free tier or OpenRouter)
+- Cost: ~$0.04 per image (paid option)
+- Cost: $0.00 (free tier fal.ai with 100 credits/month = 25-50 images)
+- Speed: <2 seconds
+- Quality: Excellent for developer blogs
+
+### Cost Breakdown Per Article (2,500 words)
+
+```
+Planning (Gemini Flash):    $0.0007 (free tier alternative: $0.00)
+Research (Web Search):      $0.02 (optional, Exa search)
+Writing (Claude Opus):      $0.633
+Image (Flux Schnell):       $0.04 (free tier alternative: $0.00)
+OpenRouter platform fee:    ~$0.034
+─────────────────────────────────────
+TOTAL:                      ~$0.72 per article (paid tier with research)
+TOTAL (No research):        ~$0.70 per article (paid tier)
+TOTAL (Free tier):          ~$0.00 per article
+```
+
+### User Cost Scenarios
+
+| User Type | Articles/Month | Paid Cost | Free Tier |
+|-----------|---|---|---|
+| **Solo Dev Blogger** | 10 | $7.00 | Free (limited) |
+| **Agency Content** | 50 | $35.00 | Free (limited) |
+| **Company Blog** | 200 | $140.00 | Free (limited) |
+
+---
+
+## 🔌 Integration: OpenRouter
+
+### Why OpenRouter?
+
+✅ **Single API Key** - No juggling Claude + Gemini + GPT
+✅ **Model Flexibility** - Switch models in settings, no code changes
+✅ **Unified Cost Tracking** - OpenRouter returns exact token costs per request
+✅ **25+ Free Models** - Full plugin works without credit card
+✅ **Built-in Web Search** - Add `:online` to any model for real-time research
+✅ **Transparent Pricing** - 5.5% platform fee on all models
+
+### Settings Page (One Simple Input)
+
+```
+WP Agentic Writer Settings
+├─ OpenRouter API Key: [___________________]
+├─ Planning Model: google/gemini-3-flash ▼
+├─ Execution Model: anthropic/claude-4-opus ▼
+├─ Image Model: black-forest-labs/flux-schnell ▼
+├─ Research Phase:
+│  ◉ Enable Web Search (~$0.02 per search)
+│  ○ Disabled (use LLM knowledge only)
+│  └─ Search Engine: [Auto ▼] (Native or Exa fallback)
+│  └─ Search Depth: [Medium ▼] (Low/Medium/High)
+└─ Cost Tracking: ON ✓
+```
+
+---
+
+## 🎨 Gutenberg Integration
+
+### Sidebar Chat Interface
+
+**During Planning:**
+```
+Sidebar shows:
+┌─────────────────────────────┐
+│ WP Agentic Writer            │
+├─────────────────────────────┤
+│                             │
+│ > I built a PHP plugin      │
+│   that handles OAuth...     │
+│                             │
+│ < Agentic AI (Gemini)       │
+│   Planning $0.0007          │
+│   This is really about      │
+│   "Auth abstraction for     │
+│   WordPress", correct?      │
+│                             │
+│ > Yes, exactly!             │
+│                             │
+│ [Regenerate Plan] [Execute] │
+└─────────────────────────────┘
+```
+
+**During Execution:**
+```
+Canvas shows:
+[Paragraph block] ← Regenerate This
+"Here's how OAuth works in WordPress..."
+
+[Code block] ← Regenerate This
+function auth_provider() { ... }
+
+[Paragraph block] ← Regenerate This
+"Notice the abstraction layer..."
+
+Sidebar: "Article generated in 3.5s | Cost: $0.633"
+```
+
+### Block Operations
+
+**Each Gutenberg block gets:**
+- "Regenerate" button (re-runs AI for that section only)
+- "Refine" button (opens sidebar chat for that block)
+- Visual cost indicator per block
+
+---
+
+## 📊 Plan JSON Structure
+
+```json
+{
+  "title": "OAuth Plugin Architecture for WordPress",
+  "meta": {
+    "reading_time": "5 min",
+    "difficulty": "intermediate",
+    "cost_estimate": 0.70
+  },
+  "sections": [
+    {
+      "id": "intro",
+      "type": "section",
+      "heading": "The Problem: Auth Abstraction",
+      "content": [
+        {
+          "type": "paragraph",
+          "content": "Building flexible auth systems..."
+        },
+        {
+          "type": "code",
+          "language": "php",
+          "content": "interface AuthProvider { ... }",
+          "caption": "Provider interface pattern"
+        },
+        {
+          "type": "paragraph",
+          "content": "This pattern allows switching..."
+        }
+      ]
+    },
+    {
+      "id": "implementation",
+      "type": "section",
+      "heading": "Step-by-Step Implementation",
+      "content": [
+        {
+          "type": "ordered_list",
+          "items": [
+            "Define provider interface",
+            "Implement concrete providers",
+            "Create abstraction layer"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "image_section",
+      "type": "section",
+      "image_prompt": "WordPress OAuth architecture diagram with abstraction layers, clean technical aesthetic, light colors",
+      "image_alt": "OAuth architecture flowchart"
+    }
+  ],
+  "citations": [
+    {
+      "id": 1,
+      "text": "OAuth 2.0 specification",
+      "url": "https://..."
+    }
+  ]
+}
+```
+
+---
+
+## 💾 Cost Tracking Display
+
+### Real-Time Sidebar
+
+```
+Today's Usage:
+──────────────────────────
+Planning:      4,700 tokens  $0.0007
+Writing:       7,500 tokens  $0.633
+Images:        1 @ Flux      $0.04
+──────────────────────────
+Session Total:               $0.6737
+
+Monthly Budget:
+Used: $6.74 / $600 (1.1%)
+Remaining: $593.26
+```
+
+### Per-Request Cost
+
+Each API call logs:
+- Model used
+- Tokens in/out
+- Cost (in real-time)
+- Cumulative session cost
+
+---
+
+## 🔍 Web Search Strategy
+
+### OpenRouter Built-in Web Search
+
+**How it works:**
+- Append `:online` to any model slug: `google/gemini-3-flash:online`
+- OpenRouter automatically adds real-time web search results
+- Supports native search (OpenAI, Anthropic, Perplexity, xAI) or Exa fallback
+- Standardized citation format across all providers
+
+### Cost Structure
+
+| Search Type | Cost | Best For |
+|-------------|------|----------|
+| **No Search** | $0.00 | Evergreen topics, general knowledge |
+| **Native Search** | Provider pricing | Premium research (OpenAI, Anthropic models) |
+| **Exa Search** | $4 per 1,000 results = ~$0.02 per search | Most models, cost-effective research |
+
+### Research Provider Options (Via OpenRouter)
+
+| Option | Model | Cost | Quality | Best For |
+|--------|-------|------|---------|----------|
+| **Web Search ON** | `google/gemini-3-flash:online` | ~$0.02 + model cost | Real-time sources | Technical tutorials, recent topics |
+| **Web Search OFF** | `google/gemini-3-flash` | Model cost only | Training data | Evergreen topics |
+| **Premium Search** | `anthropic/claude-4-opus:online` | ~$0.05 + model cost | Best research | Professional articles |
+
+### Implementation
+
+```php
+// Research with web search toggle
+class OpenRouterProvider {
+    private $web_search_enabled;
+    private $search_engine = 'auto'; // native, exa, auto
+    private $search_depth = 'medium'; // low, medium, high
+
+    public function research($query) {
+        $model = $this->planning_model;
+
+        // Add :online suffix if web search enabled
+        if ($this->web_search_enabled) {
+            $model .= ':online';
+        }
+
+        $response = $this->chat([
+            ['role' => 'user', 'content' => "Research this topic: {$query}"]
+        ], [
+            'model' => $model,
+            'web_search_options' => [
+                'search_context_size' => $this->search_depth,
+                'max_results' => 5,
+                'engine' => $this->search_engine
+            ]
+        ]);
+
+        // Parse web search results from response
+        $citations = $this->extractWebSearchResults($response);
+
+        return [
+            'content' => $response['content'],
+            'citations' => $citations,
+            'cost' => $response['cost']
+        ];
+    }
+}
+```
+
+### User Workflow
+
+**Scenario 1: Evergreen Topic**
+```
+User: "Write about basic OOP principles"
+Research: Web Search OFF
+→ Uses LLM's training data
+Cost: $0.00 (no extra cost)
+Time: ~2 seconds
+```
+
+**Scenario 2: Recent Tech Topic**
+```
+User: "Write about WordPress 6.7 new features"
+Research: Web Search ON
+→ Searches: "WordPress 6.7 new features 2025"
+→ Returns: 5 relevant articles with citations
+Cost: ~$0.02 (Exa search) + $0.0007 (model)
+Time: ~5 seconds
+```
+
+### Settings Configuration
+
+**Research Provider Selection:**
+- **Enable Web Search** - Toggle on/off
+- **Search Engine:**
+  - `Auto` - Native if available, Exa fallback (recommended)
+  - `Native` - Force provider's native search
+  - `Exa` - Force Exa search
+- **Search Depth:**
+  - `Low` - Minimal context, basic queries
+  - `Medium` - Moderate context, general queries (default)
+  - `High` - Extensive context, detailed research
+
+---
+
+## 🖼️ Image Generation Strategy
+
+### Recommendation: Multi-Tier Approach
+
+#### **Tier 1: Free for Most Users**
+**Provider:** fal.ai (via Replicate)  
+**Model:** FLUX.1 Schnell (free tier)
+- **Free Credits:** 100 credits/month (= ~25-50 images)
+- **Generation Time:** <2 seconds
+- **Quality:** Excellent for dev blogs
+- **Setup:** Simple API integration
+- **Cost:** $0.00
+
+**When to use:**
+- If user hasn't added OpenRouter key
+- For quick placeholder images
+- Personal/hobby blogs
+
+#### **Tier 2: Premium via OpenRouter**
+**Provider:** OpenRouter  
+**Model:** `black-forest-labs/flux-schnell` or `flux-pro`
+- **Cost:** ~$0.04 per image (schnell), ~$0.25 (pro)
+- **Quality:** Highest quality
+- **Integration:** Same API key as text models
+- **User Control:** Settings dropdown to pick Schnell vs Pro
+
+**When to use:**
+- User has OpenRouter API key
+- Premium blogs/companies
+- High-quality images needed
+
+### Implementation
+
+```javascript
+// Image generation in Execute phase
+
+const imagePrompt = plan.sections
+  .filter(s => s.image_prompt)
+  .map(s => ({
+    section: s.id,
+    prompt: s.image_prompt,
+    model: userSettings.imageModel // schnell or pro
+  }));
+
+// Generate images via OpenRouter or fal.ai
+// Insert as Image blocks into Gutenberg
+```
+
+---
+
+## 🆓 Free Tier Strategy
+
+### What Works for Free (No Credit Card)
+
+**25+ Free Models on OpenRouter:**
+
+**Best for Planning:**
+- `xiaomi/mimo-v2-flash` - Top #1 open-source, Claude Sonnet 4.5 quality
+- `mistralai/mistral-devstral-2` - Excellent agentic coding
+- `deepseek/r1t2-chimera` - Strong reasoning
+
+**Best for Writing:**
+- `meta-llama/llama-3.3-70b` - GPT-4 level quality
+- `qwen/qwen3-coder-480b` - Technical writing excellence
+
+**Best for Images:**
+- fal.ai free tier: 100 credits/month
+- Replicate: 50 free generations/month with FLUX.1
+
+### Free Tier Limitations
+
+```
+✅ No credit card required
+✅ 25+ models available  
+✅ Full plugin functionality
+✅ Rate limits: ~50 requests/day (= 5+ articles)
+❌ Shared infrastructure (queue during peak)
+❌ No premium models (Claude Opus, etc.)
+```
+
+### Upsell Path
+
+**Sidebar messaging:**
+```
+"Using Free Tier (30 requests remaining today)"
+
+"Upgrade to OpenRouter ($0.67/article with premium models)"
+ [Add API Key] [Learn More]
+```
+
+**Settings page:**
+```
+Tier Selection:
+○ Free Tier (25+ models, slow during peak)
+◉ Pro Tier (300+ models, priority queue) - Add OpenRouter Key
+```
+
+---
+
+## 🏗️ Technical Architecture
+
+### WordPress Plugin Structure
+
+```
+wp-agentic-writer/
+├── wp-agentic-writer.php (main plugin file)
+├── includes/
+│   ├── class-openrouter-provider.php (AI provider)
+│   ├── class-gutenberg-sidebar.php (React sidebar)
+│   ├── class-cost-tracker.php (cost display)
+│   └── class-plan-generator.php (plan logic)
+├── assets/
+│   ├── js/
+│   │   ├── sidebar.js (React component)
+│   │   └── blocks.js (Gutenberg integration)
+│   └── css/
+│       └── sidebar.css
+├── admin/
+│   └── settings.php (Settings page with API key input)
+└── tests/
+    └── test-openrouter.php
+```
+
+### Key Classes
+
+**OpenRouterProvider**
+```php
+class OpenRouterProvider {
+  - setApiKey($key)
+  - setModel($type, $model)  // type: "planning" or "execution"
+  - enableWebSearch($enabled, $engine, $depth)
+  - chat($messages, $options)  // returns response + cost
+  - generateImage($prompt)
+  - getModelList()
+  - getCostBreakdown()
+}
+```
+
+**GutenbergSidebar**
+```js
+- useChat()  // maintains conversation history
+- usePlan()  // stores plan JSON
+- useBlockRegen()  // regenerate specific block
+- useCostTracker()  // real-time cost display
+```
+
+**CostTracker**
+```php
+- addRequest($model, $input_tokens, $output_tokens, $cost)
+- getSessionTotal()
+- getMonthlyTotal()
+- formatDisplay()
+```
+
+---
+
+## 📅 Development Roadmap (4 Weeks)
+
+### **Week 1: Core Setup**
+- [ ] OpenRouter integration + cost tracking
+- [ ] Settings page (API key + model selection)
+- [ ] Gutenberg sidebar UI (chat interface)
+- [ ] Phase 1 & 2: Scribble → Research
+
+**Deliverable:** User can chat in sidebar, see costs
+
+### **Week 2: Planning & Execution**
+- [ ] Plan JSON generation from research
+- [ ] Plan editor in sidebar
+- [ ] Execute phase: Convert plan → Gutenberg blocks
+- [ ] Code block insertion with language detection
+
+**Deliverable:** User can generate article blocks automatically
+
+### **Week 3: Refinement & Images**
+- [ ] Block-level regeneration
+- [ ] Section-level chat refinement
+- [ ] Image generation integration (fal.ai + OpenRouter)
+- [ ] Image block insertion
+
+**Deliverable:** Full 5-phase workflow functional
+
+### **Week 4: Polish & Launch**
+- [ ] Cost tracking display (sidebar + settings)
+- [ ] Free tier messaging + upsell
+- [ ] Documentation (README, setup guide)
+- [ ] Testing + bug fixes
+
+**Deliverable:** Production-ready MVP
+
+---
+
+## 🚀 Launch Checklist
+
+### Plugin Preparation
+- [ ] Prefix all functions/classes with `wp_agentic_writer_`
+- [ ] Add proper nonces for security
+- [ ] Sanitize all user inputs
+- [ ] Add error handling + user feedback
+- [ ] Include .pot file for translations
+- [ ] Test on WordPress 6.6+
+- [ ] Test with Gutenberg editor
+
+### Documentation
+- [ ] README.md with setup instructions
+- [ ] Inline code comments
+- [ ] Troubleshooting guide
+- [ ] FAQ for developers
+
+### Distribution
+- [ ] WordPress.org plugin listing
+- [ ] GitHub repository
+- [ ] Demo video showing workflow
+
+---
+
+## 📝 User Workflow Example
+
+### Scenario: Dev Writes OAuth Article
+
+```
+1. Opens WordPress editor
+2. Clicks "Start Agentic Writing" in sidebar
+3. Types: "I built an OAuth provider plugin for WordPress, want to write about it"
+
+4. AI (Planning Model - Free): 
+   "This is about flexible authentication abstraction, yes? 
+    Key angles: Architecture pattern, Step-by-step implementation, 
+    Comparison to built-in WP auth"
+
+5. User confirms: "Yes, but add performance considerations too"
+
+6. AI generates plan in 8 seconds (JSON outline)
+   Cost shown: $0.0007
+
+7. User reviews outline in sidebar
+   - Sees H2 sections, estimated code blocks
+   - Adds "Security Tips" section
+   - Removes redundant section
+
+8. Clicks [Execute Article]
+
+9. AI (Execution Model - Claude):
+   - Generates prose for each section
+   - Pulls code examples
+   - Generates tech blog image
+   
+   Takes 45 seconds, Cost: $0.634
+
+10. Canvas fills with:
+    - Paragraph blocks
+    - Code blocks (highlighted)
+    - Image block (auto-inserted)
+
+11. User reviews in editor:
+    - Reads through blocks
+    - Clicks "Regenerate Section" on intro
+    - Types refinement: "Make it more beginner-friendly"
+    - AI re-writes just that section
+
+12. User publishes
+
+**Total time:** 3 minutes  
+**Total cost:** ~$0.70  
+**User satisfaction:** Very high (finally wrote the article!)
+```
+
+---
+
+## 🎯 Success Metrics
+
+### MVP Success Criteria
+- [ ] Plugin installs without errors
+- [ ] 5-phase workflow completes end-to-end
+- [ ] Cost tracking accurate within 1%
+- [ ] Free tier users can write 1+ articles/month
+- [ ] Paid tier users save 2+ hours per article
+- [ ] Block regeneration works on all content types
+
+### Post-Launch Goals
+- 100+ active installations
+- 4.5+ star rating on WordPress.org
+- Feature requests from real users
+- Revenue from premium features (if applicable)
+
+---
+
+## 🔐 Security & Privacy Notes
+
+### OpenRouter API Key Storage
+- Store in WordPress options (prefixed)
+- Encrypt sensitive data
+- Add warning: "Never share your API key"
+
+### User Data
+- Plan JSON stored in post meta
+- Cost history stored locally (not sent externally)
+- Conversation history stored in post meta
+
+### Compliance
+- GDPR: User controls data, can delete anytime
+- No tracking or analytics
+- No external data collection
+
+---
+
+## 💡 Future Roadmap (Post-MVP)
+
+### Phase 2 Features
+- [ ] Multi-language support (generate in any language)
+- [ ] SEO optimization (auto-generate meta descriptions, keywords)
+- [ ] Social sharing templates
+- [ ] Article scheduling
+- [ ] Team collaboration (multiple editors)
+- [ ] Template library (blog post templates, tutorials, case studies)
+
+### Phase 3 Integration
+- [ ] GitHub integration (auto-convert PR → blog post)
+- [ ] Video script generation
+- [ ] Podcast transcript → blog post
+- [ ] Analytics dashboard
+
+---
+
+## 📚 Resources & References
+
+- OpenRouter Docs: https://openrouter.ai/docs
+- Gutenberg Handbook: https://developer.wordpress.org/block-editor/
+- FLUX Image Generation: https://fal.ai/flux-2
+- WordPress Plugin Development: https://developer.wordpress.org/plugins/
+
+---
+
+**Ready to build?** Start with Week 1 core setup. All tools are free for development with generous free tiers.
+
+**Questions?** Refer to this brief as source of truth throughout development.