feat: consolidate docs, backend/session infra, and settings updates

2026-05-28 00:58:20 +07:00
parent 2424acf726
commit 44e06eed88
102 changed files with 35423 additions and 11181 deletions
--- a/docs/features/DISTRIBUTION_STRATEGY.md
+++ b/docs/features/DISTRIBUTION_STRATEGY.md
@@ -0,0 +1,506 @@
+# WP Agentic Writer - Distribution Strategy
+
+**Version:** 1.0
+**Date:** 2026-05-17
+**Strategy:** Freemium with Addon Model
+
+---
+
+## Executive Summary
+
+This document outlines a comprehensive strategy for distributing WP Agentic Writer as two distinct versions:
+- **Free Version** - Published on WordPress.org repository for maximum visibility and user acquisition
+- **Pro Version** - Premium addon sold via your own license server with advanced features
+
+**Core Philosophy:** The free version must be a complete, valuable product on its own. Pro features are genuine enhancements that power users will happily pay for.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    WP AGENTIC WRITER                        │
+├─────────────────────────────────────────────────────────────┤
+│  FREE CORE PLUGIN (WordPress.org)                           │
+│  ├── AI Writing Assistant (sidebar)                        │
+│  ├── Context Management                                     │
+│  ├── Planning & Writing Pipeline                           │
+│  ├── Model Selection (OpenRouter)                          │
+│  ├── Basic Refinement                                       │
+│  ├── Cost Tracking                                          │
+│  └── Hook System (for extensibility)                        │
+├─────────────────────────────────────────────────────────────┤
+│  PRO ADDON (License Server)                                 │
+│  ├── License Verification System                           │
+│  ├── Advanced Refinement (multi-pass)                       │
+│  ├── Local Backend Integration (extended)                  │
+│  ├── Brave Search Integration                              │
+│  ├── Image Generation (DALL-E, Stable Diffusion)            │
+│  ├── Custom Model Presets                                  │
+│  ├── Team Collaboration                                     │
+│  ├── Priority Support                                       │
+│  └── Advanced Analytics                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Feature Distribution
+
+### Free Version Features
+
+#### Core Writing Pipeline
+| Feature | Description | Strategic Value |
+|---------|-------------|-----------------|
+| Planning Mode | AI-powered article outline creation | Core value prop |
+| Writing Mode | Generate full articles with context | Core value prop |
+| Chat Mode | Quick AI assistance | Engagement driver |
+| Refinement Mode | Basic content polishing | Entry to refinement |
+| @mention Detection | Link to related posts | Unique capability |
+| Clarification Quiz | Guided topic extraction | User onboarding |
+| Focus Keyword | SEO-first writing | Differentiation |
+
+#### Model Integration
+| Feature | Description | Strategic Value |
+|---------|-------------|-----------------|
+| OpenRouter Integration | Access to 100+ models | Flexibility |
+| Model Selection UI | Easy model switching | Usability |
+| Preset Configurations | Budget/Balanced/Premium | Quick start |
+| Cost Estimation | Real-time cost display | Budget control |
+
+#### Analytics & Tracking
+| Feature | Description | Strategic Value |
+|---------|-------------|-----------------|
+| Cost Log | Basic usage tracking | Transparency |
+| Token Usage | Input/output tracking | Optimization |
+| Daily/Monthly Stats | Usage overview | Awareness |
+
+#### Technical Foundation
+| Feature | Description | Strategic Value |
+|---------|-------------|-----------------|
+| Gutenberg Integration | Block editor sidebar | Core integration |
+| Classic Editor Support | Alternative UI | Coverage |
+| Shortcode Support | Flexible embedding | Versatility |
+| REST API Endpoints | Developer hooks | Ecosystem |
+| WebSocket Status | Real-time updates | Polish |
+
+---
+
+### Pro Addon Features
+
+#### Advanced Refinement (Multi-Pass)
+| Feature | Description | Value |
+|---------|-------------|-------|
+| Multi-Pass Refinement | 3-stage polishing (clarity, SEO, quality) | High |
+| Keyword Density Optimization | Automatic SEO improvement | High |
+| Readability Scoring | Flesch-Kincaid integration | Medium |
+| Plagiarism Check | Integration with Copyscape API | Premium |
+| Brand Voice Training | Learn from existing content | Premium |
+
+#### External Integrations
+| Feature | Description | Value |
+|---------|-------------|-------|
+| Brave Search Integration | Real-time web research | High |
+| Image Generation (DALL-E 3) | AI-generated featured images | High |
+| Image Generation (SDXL) | Stable Diffusion XL | Premium |
+| Unsplash Integration | Stock photo search | Medium |
+| WordPress Media Library | Direct image management | Medium |
+
+#### Local Backend (Extended)
+| Feature | Description | Value |
+|---------|-------------|-------|
+| LM Studio Support (Full) | Complete integration | Medium |
+| Ollama Support (Full) | Complete integration | Medium |
+| Self-Hosted Models | Custom model hosting | Premium |
+| Multi-Instance Support | Multiple backend servers | Premium |
+| Load Balancing | Automatic failover | Premium |
+
+#### Collaboration & Team
+| Feature | Description | Value |
+|---------|-------------|-------|
+| Team Workspaces | Shared configurations | Premium |
+| User Roles & Permissions | Role-based access | Premium |
+| Activity Logs | Audit trails | Medium |
+| Template Sharing | Team templates | Medium |
+| Content Approvals | Workflow integration | Premium |
+
+#### Advanced Analytics
+| Feature | Description | Value |
+|---------|-------------|-------|
+| ROI Calculator | Content performance vs cost | Medium |
+| Content Performance | SEO ranking tracking | Premium |
+| A/B Testing | Headline variations | Premium |
+| Seasonal Trends | Content calendar | Premium |
+
+#### Priority Support
+| Feature | Description | Value |
+|---------|-------------|-------|
+| Email Support | Direct assistance | Medium |
+| Priority Response | 24hr vs 7 days | Medium |
+| Feature Requests | Influence roadmap | Low |
+| Custom Integrations | Bespoke solutions | Premium |
+
+---
+
+## Hook System Architecture
+
+### Purpose
+The free version provides comprehensive hooks that both Pro addon and third-party developers can use to extend functionality.
+
+### Hook Types
+
+#### 1. Action Hooks (Events)
+```php
+// Writing lifecycle
+do_action('wpaw_before_generate', $post_id, $mode);
+do_action('wpaw_after_generate', $post_id, $mode, $content);
+do_action('wpaw_planning_started', $post_id);
+do_action('wpaw_planning_complete', $post_id, $plan);
+do_action('wpaw_writing_started', $post_id, $section_index);
+do_action('wpaw_writing_section_complete', $post_id, $section_index, $content);
+do_action('wpaw_refinement_started', $post_id);
+do_action('wpaw_refinement_complete', $post_id, $refined_content);
+
+// Model interactions
+do_action('wpaw_model_selected', $model_id, $task_type);
+do_action('wpaw_api_request_sent', $model_id, $tokens, $cost);
+do_action('wpaw_api_response_received', $model_id, $response_time);
+
+// Context management
+do_action('wpaw_context_loaded', $post_id, $context_data);
+do_action('wpaw_context_updated', $post_id, $changes);
+
+// Cost tracking
+do_action('wpaw_cost_recorded', $record);
+do_action('wpaw_daily_limit_reached', $total_cost);
+```
+
+#### 2. Filter Hooks (Data Modification)
+```php
+// Context modification
+add_filter('wpaw_context_data', 'modify_context', 10, 2);
+add_filter('wpaw_post_content', 'process_content', 10, 2);
+add_filter('wpaw_planning_prompt', 'customize_planning', 10, 2);
+
+// Model selection
+add_filter('wpaw_model_for_task', 'override_model', 10, 3);
+add_filter('wpaw_model_parameters', 'customize_params', 10, 2);
+
+// Output modification
+add_filter('wpaw_generated_content', 'post_process', 10, 3);
+add_filter('wpaw_refinement_criteria', 'custom_criteria', 10, 2);
+
+// Cost calculations
+add_filter('wpaw_cost_calculation', 'adjust_cost', 10, 2);
+add_filter('wpaw_token_count', 'modify_tokens', 10, 2);
+```
+
+#### 3. REST API Endpoints
+```
+POST /wpaw/v1/generate
+  - Generate content via API
+  - Authentication: API key or OAuth
+
+POST /wpaw/v1/refine
+  - Refine existing content
+  - Parameters: content, criteria, iterations
+
+GET /wpaw/v1/cost-log
+  - Retrieve cost tracking data
+  - Filters: date range, post_id, model
+
+GET /wpaw/v1/models
+  - List available models
+  - Include pricing and capabilities
+
+POST /wpaw/v1/context
+  - Update context for specific post
+```
+
+#### 4. JavaScript Events (Frontend)
+```javascript
+// jQuery / DOM Events
+document.dispatchEvent(new CustomEvent('wpaw:generation-start', {
+  detail: { postId, mode }
+}));
+
+document.dispatchEvent(new CustomEvent('wpaw:generation-complete', {
+  detail: { postId, content, cost }
+}));
+
+document.dispatchEvent(new CustomEvent('wpaw:section-written', {
+  detail: { postId, sectionIndex, content }
+}));
+
+// React component hooks (for sidebar)
+window.wpawHooks = {
+  onBeforeGenerate: (postId, mode) => {},
+  onAfterGenerate: (postId, mode, content) => {},
+  onModelSelected: (modelId, taskType) => {},
+};
+```
+
+---
+
+## Licensing System
+
+### Pro Addon Structure
+
+#### License Types
+| Type | Price Point | Activations | Features |
+|------|-------------|-------------|----------|
+| Personal | $49/year | 1 site | All Pro features |
+| Professional | $99/year | 5 sites | All Pro + priority support |
+| Agency | $199/year | 25 sites | All Pro + team features |
+| Enterprise | Custom | Unlimited | White-label + SLA |
+
+#### License Verification Flow
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   User       │     │  Pro Addon   │     │ License     │
+│   Activates  │────▶│  Checks      │────▶│  Server      │
+└──────────────┘     └──────────────┘     └──────────────┘
+                           │                     │
+                           │ Valid?              │
+                           ▼                     ▼
+                    ┌──────────────┐     ┌──────────────┐
+                    │ Enable Pro   │     │ Response:    │
+                    │ Features     │◀────│ key, expiry, │
+                    └──────────────┘     │ features     │
+                                          └──────────────┘
+```
+
+### License Server Requirements
+
+#### Endpoints
+```
+POST /api/v1/verify
+  - Input: license_key, domain, product_id
+  - Output: { valid: bool, expires: date, features: [] }
+
+POST /api/v1/activate
+  - Input: license_key, domain
+  - Output: { activation_id, sites_used, sites_limit }
+
+POST /api/v1/deactivate
+  - Input: activation_id
+  - Output: { success: bool }
+
+GET /api/v1/status
+  - Input: license_key
+  - Output: { active: bool, sites: [], expires: date }
+```
+
+#### Security Measures
+- License key hashed with SHA-256 before storage
+- Domain binding prevents key sharing
+- Activation limit enforcement
+- Automatic deactivation on payment failure
+- IP-based rate limiting on verification
+
+---
+
+## Migration Path
+
+### Upgrading from Free to Pro
+```
+┌──────────────────────────────────────────────────────────┐
+│  Step 1: User purchases Pro license                       │
+│  └── Receives license key via email                      │
+│                                                           │
+│  Step 2: User installs Pro Addon                         │
+│  └── Upload via WordPress admin                           │
+│  └── Activates alongside free plugin                      │
+│                                                           │
+│  Step 3: User enters license key                         │
+│  └── Addon validates against license server                │
+│  └── Activates on current domain                          │
+│                                                           │
+│  Step 4: Pro features unlocked                           │
+│  └── UI shows Pro indicators                              │
+│  └── New tabs/options become visible                      │
+│  └── Settings synced from free version                    │
+│                                                           │
+│  Step 5: Deactivate/reactivate                           │
+│  └── Can transfer license to new domain                   │
+│  └── Previous site features disabled                      │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Data Migration
+- Settings stored in `wp_options` - shared between free and pro
+- Pro settings prefixed with `wpaw_pro_`
+- Cost tracking uses unified table structure
+- No data loss during upgrade
+
+---
+
+## File Structure
+
+### Free Plugin (WordPress.org)
+```
+wp-agentic-writer/
+├── wp-agentic-writer.php          # Main plugin file
+├── readme.txt                      # WordPress.org readme
+├── uninstall.php                   # Clean uninstall
+├── includes/
+│   ├── class-plugin.php           # Core plugin class
+│   ├── class-settings.php         # Settings page
+│   ├── class-gutenberg-sidebar.php # Sidebar UI
+│   ├── providers/
+│   │   └── class-openrouter-provider.php
+│   └── helpers/
+│       └── class-context-manager.php
+├── assets/
+│   ├── css/
+│   │   ├── agentic-variables.css
+│   │   ├── agentic-components.css
+│   │   └── agentic-workflow.css
+│   └── js/
+│       └── sidebar.js
+├── views/
+│   └── settings/
+└── lang/
+    └── wp-agentic-writer.pot
+```
+
+### Pro Addon
+```
+wp-agentic-writer-pro/
+├── wp-agentic-writer-pro.php     # Main addon file
+├── includes/
+│   ├── class-license-manager.php  # License verification
+│   ├── class-pro-features.php     # Feature toggles
+│   ├── providers/
+│   │   ├── class-brave-search.php
+│   │   └── class-image-generator.php
+│   ├── refinement/
+│   │   └── class-multi-pass-refinement.php
+│   └── analytics/
+│       └── class-pro-analytics.php
+└── admin/
+    └── class-pro-admin.php        # Pro settings UI
+```
+
+---
+
+## Testing Checklist
+
+### Pre-Release Validation
+
+#### Free Version
+- [ ] Works with WordPress 6.0+ (latest stable)
+- [ ] Works with PHP 7.4+ (minimum) and 8.x (recommended)
+- [ ] No PHP errors/warnings in debug mode
+- [ ] All hooks documented and functional
+- [ ] Settings page renders correctly
+- [ ] Sidebar works in Gutenberg and Classic
+- [ ] Uninstall removes all plugin data
+- [ ] Internationalization (i18n) complete
+
+#### Pro Addon
+- [ ] Gracefully fails without license
+- [ ] Shows upgrade prompts for locked features
+- [ ] License verification works offline (cached)
+- [ ] Reactivation works correctly
+- [ ] No errors when free plugin inactive
+- [ ] License expiry handled gracefully
+
+---
+
+## Rollout Strategy
+
+### Phase 1: Preparation (Week 1-2)
+1. Finalize Pro feature set
+2. Set up license server infrastructure
+3. Create Pro addon codebase
+4. Prepare marketing copy
+
+### Phase 2: Soft Launch (Week 3)
+1. Release free plugin to limited beta
+2. Test with 10-20 trusted users
+3. Gather feedback and fix critical issues
+
+### Phase 3: WordPress.org Submission (Week 4)
+1. Prepare WordPress.org assets (banner, icons)
+2. Write compliant readme.txt
+3. Submit for review
+4. Address review feedback (typically 1-2 weeks)
+
+### Phase 4: Pro Launch (Week 6-8)
+1. Launch license server
+2. Create sales page
+3. Set up payment processing
+4. Launch Pro addon
+
+### Phase 5: Marketing (Ongoing)
+1. Blog posts on AI writing tools
+2. Tutorial videos on YouTube
+3. Guest posts on WordPress blogs
+4. Community forum engagement
+
+---
+
+## Pricing Considerations
+
+### Factors for Pricing
+| Factor | Consideration |
+|--------|---------------|
+| Competition | Compare to AI writing plugins ($49-$299/year) |
+| Value Delivered | Pro features save X hours/month |
+| Market Position | Mid-tier vs premium |
+| Support Costs | Personal vs team tier |
+
+### Recommended Pricing
+| Tier | Price | Rationale |
+|------|-------|-----------|
+| Personal | $49/year | ~$4/month - impulse purchase |
+| Professional | $99/year | ~$8/month - small business |
+| Agency | $199/year | ~$8/site/year - good value |
+
+---
+
+## Risk Mitigation
+
+### Technical Risks
+| Risk | Mitigation |
+|------|------------|
+| License server downtime | Cache verification locally (7 days) |
+| Key sharing | Domain binding + monitoring |
+| WordPress.org policy violation | Clear separation of free/pro |
+| Competition | Focus on unique value props |
+
+### Business Risks
+| Risk | Mitigation |
+|------|------------|
+| Low adoption | Start with strong free feature set |
+| Support overload | Tiered support, clear documentation |
+| Piracy | Regular audits, IP monitoring |
+| Negative reviews | Proactive beta testing |
+
+---
+
+## Success Metrics
+
+### Free Version
+| Metric | Target |
+|--------|--------|
+| WordPress.org downloads (6 months) | 5,000+ |
+| Active installations | 2,000+ |
+| 5-star rating | 4.5+ |
+| Support forum engagement | <10% of installs |
+
+### Pro Version
+| Metric | Target |
+|--------|--------|
+| Conversion rate (free→pro) | 2-5% |
+| Monthly revenue (year 1) | $500-$1,000 |
+| License renewals | 60%+ |
+| Customer satisfaction | 4.0+ |
+
+---
+
+**Document Version:** 1.0
+**Last Updated:** 2026-05-17
+**Author:** Claude (AI Assistant)