+ Brave Search API. Free tier: 2,000 queries/month.', 'wp-agentic-writer' ) ), + 'https://brave.com/search/api/' + ); ?> +
+Reuses search results for identical queries. Can save 40-60% on costs.
+How long to keep cached search results (1-90 days).
+Stop searches when monthly cost exceeds this amount.
+([\s\S]*?)<\/code>/i);
@@ -1924,7 +2054,7 @@
.replace(/"/g, '"');
}
}
-
+
// Handle table blocks - extract head and body from innerHTML
if (block.blockName === 'core/table' && block.innerHTML) {
const headMatch = block.innerHTML.match(/([\s\S]*?)<\/thead>/i);
@@ -1932,7 +2062,7 @@
if (headMatch || bodyMatch) {
attrs.head = [];
attrs.body = [];
-
+
// Parse thead rows
if (headMatch) {
const headRows = headMatch[1].match(/([\s\S]*?)<\/tr>/gi) || [];
@@ -1946,7 +2076,7 @@
if (cells.length > 0) attrs.head.push({ cells });
});
}
-
+
// Parse tbody rows
if (bodyMatch) {
const bodyRows = bodyMatch[1].match(/ ([\s\S]*?)<\/tr>/gi) || [];
@@ -1962,7 +2092,7 @@
}
}
}
-
+
// Handle button blocks from [CTA:...] syntax
if (block.blockName === 'core/buttons' || block.blockName === 'core/button') {
if (block.blockName === 'core/button') {
@@ -1971,7 +2101,7 @@
]);
}
}
-
+
if (block.innerBlocks && block.innerBlocks.length > 0) {
const innerBlocks = block.innerBlocks.map((innerBlock) => (
createBlocksFromSerialized(innerBlock)
@@ -3030,13 +3160,13 @@
// Check for Writing mode notes warning
if (agentMode === 'writing' && currentPlanRef.current) {
setInput('');
- setMessages(prev => [...prev,
- { role: 'user', content: userMessage },
- {
- role: 'system',
- type: 'info',
- content: '💡 Note: Messages in Writing mode are for discussion only. To modify the outline, switch to Planning mode.'
- }
+ setMessages(prev => [...prev,
+ { role: 'user', content: userMessage },
+ {
+ role: 'system',
+ type: 'info',
+ content: '💡 Note: Messages in Writing mode are for discussion only. To modify the outline, switch to Planning mode.'
+ }
]);
return;
}
@@ -3086,6 +3216,8 @@
setMessages([...messages, { role: 'user', content: userMessage }]);
setIsLoading(true);
+ // User message is NOT an AI suggestion - don't extract from user input
+
// Store for retry
lastChatRequestRef.current = { message: userMessage };
@@ -3173,24 +3305,37 @@
return newMessages;
});
}
- } else if (data.type === 'complete' && data.totalCost) {
- setCost({ ...cost, session: cost.session + data.totalCost });
+ } else if (data.type === 'complete') {
+ if (data.totalCost) {
+ setCost({ ...cost, session: cost.session + data.totalCost });
+ }
+ // Extract ALL focus keyword suggestions from AI response
+ setMessages(prev => {
+ const lastAssistantMsg = prev.filter(m => m.role === 'assistant').pop();
+ if (lastAssistantMsg && lastAssistantMsg.content) {
+ const suggestions = extractFocusKeywordSuggestions(lastAssistantMsg.content);
+ if (suggestions.length > 0) {
+ addFocusKeywordSuggestions(suggestions);
+ }
+ }
+ return prev;
+ });
}
} catch (parseError) {
console.error('Failed to parse streaming data:', line, parseError);
}
}
}
-
+
// Detect intent after chat completes
try {
const intentResult = await detectUserIntent(userMessage);
-
+
// Track intent detection cost
if (intentResult.cost > 0) {
setCost(prev => ({ ...prev, session: prev.session + intentResult.cost }));
}
-
+
if (intentResult.intent && intentResult.intent !== 'continue_chat') {
setMessages(prev => {
const newMessages = [...prev];
@@ -3210,7 +3355,7 @@
setMessages(prev => [...prev, {
role: 'system',
type: 'error',
- content: isRateLimit
+ content: isRateLimit
? 'Rate limit exceeded. Please wait a moment and try again.'
: 'Error: ' + errorMsg,
canRetry: true,
@@ -3525,12 +3670,12 @@
} else if (data.type === 'error') {
clearTimeout(timeout);
setMessages(prev => [...prev, {
- role: 'system',
- type: 'error',
- content: data.message || 'An error occurred during article generation',
- canRetry: true
- }]);
- setIsLoading(false);
+ role: 'system',
+ type: 'error',
+ content: data.message || 'An error occurred during article generation',
+ canRetry: true
+ }]);
+ setIsLoading(false);
}
} catch (parseError) {
console.error('Failed to parse streaming data:', line, parseError);
@@ -3754,14 +3899,27 @@
return newMessages;
});
- // Trigger duplicate cleanup
- setTimeout(() => {
- const allBlocks = select('core/block-editor').getBlocks();
- const cleanedBlocks = removeDuplicateHeadings(allBlocks);
- if (cleanedBlocks.length < allBlocks.length) {
- dispatch('core/block-editor').resetBlocks(cleanedBlocks);
- }
- }, 500);
+ // Check for image placeholders and open modal if found
+ if (agentMode !== 'planning') {
+ setTimeout(() => {
+ const blocks = select('core/block-editor').getBlocks();
+ const imagePlaceholders = blocks.filter(
+ block => block.name === 'core/image' &&
+ block.attributes['data-agent-image-id']
+ );
+
+ if (imagePlaceholders.length > 0) {
+ window.dispatchEvent(
+ new CustomEvent('wpaw:open-image-review-modal', {
+ detail: {
+ postId: postId,
+ imageCount: imagePlaceholders.length
+ }
+ })
+ );
+ }
+ }, 500);
+ }
} else if (data.type === 'error') {
throw new Error(data.message);
}
@@ -3808,7 +3966,7 @@
if (answers.config_all) {
try {
const configData = JSON.parse(answers.config_all);
-
+
// Apply config to post config
if (configData.web_search !== undefined) {
updatePostConfig('web_search', configData.web_search);
@@ -4182,7 +4340,7 @@
configData = {};
}
}
-
+
// Set defaults from field definitions if not already set
const fields = currentQuestion.fields || [];
fields.forEach(field => {
@@ -4208,7 +4366,7 @@
}
return wp.element.createElement('div', { key: idx, className: 'wpaw-config-field' },
- field.type === 'toggle' ?
+ field.type === 'toggle' ?
wp.element.createElement(React.Fragment, null,
wp.element.createElement('label', { className: 'wpaw-config-label' },
wp.element.createElement('span', { className: 'wpaw-config-label-text' }, field.label),
@@ -4229,26 +4387,26 @@
wp.element.createElement('span', { className: 'wpaw-toggle-slider' })
)
)
- : wp.element.createElement(React.Fragment, null,
- wp.element.createElement('label', { className: 'wpaw-config-label' },
- wp.element.createElement('span', { className: 'wpaw-config-label-text' }, field.label),
- field.description && wp.element.createElement('span', { className: 'wpaw-config-description' }, field.description)
- ),
- wp.element.createElement('input', {
- type: 'text',
- className: 'wpaw-config-text-input',
- placeholder: field.placeholder || '',
- value: fieldValue || '',
- maxLength: field.max_length || 200,
- onChange: (e) => {
- const newConfig = { ...configData };
- newConfig[field.id] = e.target.value;
- const newAnswers = { ...answers };
- newAnswers[currentQuestion.id] = JSON.stringify(newConfig);
- setAnswers(newAnswers);
- }
- })
- )
+ : wp.element.createElement(React.Fragment, null,
+ wp.element.createElement('label', { className: 'wpaw-config-label' },
+ wp.element.createElement('span', { className: 'wpaw-config-label-text' }, field.label),
+ field.description && wp.element.createElement('span', { className: 'wpaw-config-description' }, field.description)
+ ),
+ wp.element.createElement('input', {
+ type: 'text',
+ className: 'wpaw-config-text-input',
+ placeholder: field.placeholder || '',
+ value: fieldValue || '',
+ maxLength: field.max_length || 200,
+ onChange: (e) => {
+ const newConfig = { ...configData };
+ newConfig[field.id] = e.target.value;
+ const newAnswers = { ...answers };
+ newAnswers[currentQuestion.id] = JSON.stringify(newConfig);
+ setAnswers(newAnswers);
+ }
+ })
+ )
);
})
);
@@ -4288,40 +4446,84 @@
wp.element.createElement('h4', null, currentQuestion.question),
answerInput,
wp.element.createElement('div', { className: 'wpaw-quiz-actions' },
- // Previous button
- currentQuestionIndex > 0 && wp.element.createElement(Button, {
- isSecondary: true,
- onClick: () => setCurrentQuestionIndex(currentQuestionIndex - 1),
- disabled: isLoading,
- }, 'Previous'),
- // Skip button for optional questions
- wp.element.createElement(Button, {
- isSecondary: true,
- onClick: () => {
- const newAnswers = { ...answers };
- newAnswers[currentQuestion.id] = '__skipped__';
- setAnswers(newAnswers);
- if (currentQuestionIndex === questions.length - 1) {
- submitAnswers();
- } else {
- setCurrentQuestionIndex(currentQuestionIndex + 1);
+ // Previous button
+ currentQuestionIndex > 0 && wp.element.createElement(Button, {
+ isSecondary: true,
+ onClick: () => setCurrentQuestionIndex(currentQuestionIndex - 1),
+ disabled: isLoading,
+ }, 'Previous'),
+ // Skip button for optional questions
+ wp.element.createElement(Button, {
+ isSecondary: true,
+ onClick: () => {
+ const newAnswers = { ...answers };
+ newAnswers[currentQuestion.id] = '__skipped__';
+ setAnswers(newAnswers);
+ if (currentQuestionIndex === questions.length - 1) {
+ submitAnswers();
+ } else {
+ setCurrentQuestionIndex(currentQuestionIndex + 1);
+ }
+ },
+ disabled: isLoading,
+ }, 'Skip'),
+ // Continue/Finish button
+ wp.element.createElement(Button, {
+ isPrimary: true,
+ onClick: () => {
+ if (currentQuestionIndex === questions.length - 1) {
+ submitAnswers();
+ } else {
+ setCurrentQuestionIndex(currentQuestionIndex + 1);
+ }
+ },
+ disabled: isLoading || (!currentAnswer.trim() && currentAnswer !== '__custom__'),
+ }, currentQuestionIndex === questions.length - 1 ? 'Finish' : 'Next')
+ )
+ )
+ );
+ };
+
+ // Render Welcome Screen (chatty, friendly)
+ const renderWelcomeScreen = () => {
+ return wp.element.createElement('div', { className: 'wpaw-welcome-screen' },
+ wp.element.createElement('div', { className: 'wpaw-welcome-content' },
+ wp.element.createElement('span', {
+ className: 'wpaw-welcome-icon',
+ dangerouslySetInnerHTML: { __html: '' }
+ }),
+ wp.element.createElement('h2', { className: 'wpaw-welcome-title' }, 'Welcome to Agentic Writer'),
+ wp.element.createElement('p', { className: 'wpaw-welcome-subtitle' }, "What's your concern today?"),
+ // Focus keyword input
+ wp.element.createElement('input', {
+ type: 'text',
+ className: 'wpaw-welcome-input',
+ placeholder: 'Your focus keyword (optional)',
+ value: welcomeKeywordInput,
+ onChange: (e) => setWelcomeKeywordInput(e.target.value),
+ onKeyDown: (e) => {
+ if (e.key === 'Enter') {
+ handleWelcomeStart();
}
- },
- disabled: isLoading,
- }, 'Skip'),
- // Continue/Finish button
+ }
+ }),
+ // Mode pills
+ wp.element.createElement('div', { className: 'wpaw-welcome-pills' },
+ wp.element.createElement('button', {
+ className: 'wpaw-welcome-pill' + (welcomeStartMode === 'chat' ? ' active' : ''),
+ onClick: () => setWelcomeStartMode('chat')
+ }, '💬 Chat First'),
+ wp.element.createElement('button', {
+ className: 'wpaw-welcome-pill' + (welcomeStartMode === 'planning' ? ' active' : ''),
+ onClick: () => setWelcomeStartMode('planning')
+ }, '📝 Make an Outline')
+ ),
+ // Start button
wp.element.createElement(Button, {
isPrimary: true,
- onClick: () => {
- if (currentQuestionIndex === questions.length - 1) {
- submitAnswers();
- } else {
- setCurrentQuestionIndex(currentQuestionIndex + 1);
- }
- },
- disabled: isLoading || (!currentAnswer.trim() && currentAnswer !== '__custom__'),
- }, currentQuestionIndex === questions.length - 1 ? 'Finish' : 'Next')
- )
+ onClick: handleWelcomeStart,
+ className: 'wpaw-welcome-start-btn'
+ }, 'Start')
)
);
};
@@ -4330,12 +4532,12 @@
const renderWritingEmptyState = () => {
return wp.element.createElement('div', { className: 'wpaw-writing-empty-state' },
wp.element.createElement('div', { className: 'wpaw-empty-state-content' },
- wp.element.createElement('span', {
+ wp.element.createElement('span', {
className: 'wpaw-empty-state-icon',
- dangerouslySetInnerHTML: { __html: '' }
- }),
- wp.element.createElement('h3', null, 'No Outline Yet'),
- wp.element.createElement('p', null, 'Writing mode requires an outline to structure your article.'),
+ dangerouslySetInnerHTML: { __html: '' }
+ }),
+ wp.element.createElement('h3', null, 'Create an Outline First'),
+ wp.element.createElement('p', null, 'Before writing, you need to create an outline to structure your article. This ensures better content organization and prevents wasted costs.'),
wp.element.createElement(Button, {
isPrimary: true,
onClick: () => setAgentMode('planning'),
@@ -4359,70 +4561,148 @@
d: "M16 5H3m13 7H3m8 7H3m12-1l2 2l4-4"
})
),
- 'Create Outline First'
+ 'Switch to Planning Mode'
)
),
- wp.element.createElement('p', { className: 'wpaw-empty-state-hint' },
- 'Or switch to ',
- wp.element.createElement('button', {
- onClick: () => setAgentMode('chat'),
- className: 'wpaw-link-button'
- }, 'Chat mode'),
- ' to discuss your ideas.'
+ wp.element.createElement('p', { className: 'wpaw-empty-state-hint', style: { marginTop: '16px', fontSize: '13px', color: '#a7aaad' } },
+ '💡 Tip: Planning mode helps you brainstorm and structure your content before writing.'
)
)
);
};
- // Render context indicator
- const renderContextIndicator = () => {
- const chatMessages = messages.filter(m => m.role !== 'system');
- const messageCount = chatMessages.length;
- const estimatedTokens = messageCount * 500;
-
- // if (messageCount === 0) return null;
-
- return wp.element.createElement('div', { className: 'wpaw-context-indicator' },
- wp.element.createElement('div', { className: 'wpaw-context-info' },
- wp.element.createElement('span', { className: 'wpaw-context-count' },
- `💬 ${messageCount} messages`
+ // Render Focus Keyword Bar (replaces context indicator)
+ const renderFocusKeywordBar = () => {
+ const hasKeyword = selectedFocusKeyword && selectedFocusKeyword.length > 0;
+
+ // Expanded mode
+ if (isTextareaExpanded) {
+ return wp.element.createElement('div', { className: 'wpaw-focus-keyword-bar wpaw-expanded' },
+ // Header
+ wp.element.createElement('div', { className: 'wpaw-fk-header' },
+ wp.element.createElement('span', null, '🎯 FOCUS KEYWORD'),
+ wp.element.createElement('button', {
+ className: 'wpaw-fk-collapse',
+ onClick: () => setIsTextareaExpanded(false),
+ title: 'Collapse'
+ }, '↓')
),
- wp.element.createElement('span', { className: 'wpaw-context-tokens' },
- `~${estimatedTokens} tokens`
+ // Main input - always show input field in expanded mode
+ wp.element.createElement('div', { className: 'wpaw-fk-main-input' },
+ wp.element.createElement('input', {
+ type: 'text',
+ className: 'wpaw-fk-custom-input',
+ placeholder: hasKeyword ? 'Edit focus keyword...' : 'Enter focus keyword...',
+ value: selectedFocusKeyword || '',
+ onChange: (e) => {
+ const value = e.target.value;
+ setSelectedFocusKeyword(value);
+ },
+ onBlur: (e) => {
+ // Save on blur
+ if (e.target.value !== postConfig.focus_keyword) {
+ handleFocusKeywordChange(e.target.value);
+ }
+ },
+ onKeyDown: (e) => {
+ if (e.key === 'Enter' && e.target.value.trim()) {
+ handleFocusKeywordChange(e.target.value.trim());
+ e.target.blur();
+ }
+ }
+ })
),
- wp.element.createElement('span', { className: 'wpaw-context-cost' },
- `💰 $${cost.session.toFixed(4)}`
+ // Suggestions list
+ focusKeywordSuggestions.length > 0 && wp.element.createElement('div', { className: 'wpaw-fk-suggestions' },
+ wp.element.createElement('div', { className: 'wpaw-fk-suggestions-label' }, '📝 AI Suggestions:'),
+ focusKeywordSuggestions.map((kw, i) =>
+ wp.element.createElement('div', {
+ key: i,
+ className: 'wpaw-fk-suggestion-item' + (kw === selectedFocusKeyword ? ' selected' : ''),
+ onClick: () => handleFocusKeywordChange(kw)
+ },
+ wp.element.createElement('span', { className: 'wpaw-fk-radio' },
+ kw === selectedFocusKeyword ? '●' : '○'
+ ),
+ wp.element.createElement('span', { className: 'wpaw-fk-suggestion-text' }, kw),
+ wp.element.createElement('span', { className: 'wpaw-fk-suggestion-source' },
+ `(#${i + 1})`
+ )
+ )
+ )
+ ),
+ // Stats
+ wp.element.createElement('div', { className: 'wpaw-fk-stats' },
+ wp.element.createElement('span', null, `💰 $${(cost.session || 0).toFixed(4)}`),
+ wp.element.createElement('span', { className: 'wpaw-fk-divider' }, '│'),
+ wp.element.createElement('span', null, `📊 ~${messages.filter(m => m.role !== 'system').length * 500} tokens`)
)
+ );
+ }
+
+ // Compact mode (default) - use input instead of dropdown
+ return wp.element.createElement('div', { className: 'wpaw-focus-keyword-bar wpaw-compact' },
+ wp.element.createElement('div', { className: 'wpaw-fk-left' },
+ wp.element.createElement('span', { className: 'wpaw-fk-icon' }, '🎯'),
+ wp.element.createElement('input', {
+ type: 'text',
+ className: 'wpaw-fk-input',
+ placeholder: 'Enter focus keyword...',
+ value: selectedFocusKeyword || '',
+ onChange: (e) => {
+ const value = e.target.value;
+ setSelectedFocusKeyword(value);
+ // Debounce save to config
+ if (configSaveTimeoutRef.current) {
+ clearTimeout(configSaveTimeoutRef.current);
+ }
+ configSaveTimeoutRef.current = setTimeout(() => {
+ handleFocusKeywordChange(value);
+ }, 500);
+ },
+ onBlur: (e) => {
+ // Save immediately on blur
+ if (e.target.value !== postConfig.focus_keyword) {
+ handleFocusKeywordChange(e.target.value);
+ }
+ },
+ disabled: isLoading
+ })
+ ),
+ wp.element.createElement('span', { className: 'wpaw-fk-cost' },
+ `$${(cost.session || 0).toFixed(4)}`
),
wp.element.createElement('button', {
- className: 'wpaw-context-toggle',
- onClick: () => setIsTextareaExpanded(!isTextareaExpanded),
- title: isTextareaExpanded ? 'Collapse textarea' : 'Expand textarea'
+ className: 'wpaw-fk-expand',
+ onClick: () => setIsTextareaExpanded(true),
+ title: 'Expand'
},
wp.element.createElement('svg', {
xmlns: "http://www.w3.org/2000/svg",
- width: "18",
- height: "18",
- viewBox: "0 0 24 24",
- style: { verticalAlign: 'middle', marginBottom: '0' }
+ width: "16",
+ height: "16",
+ viewBox: "0 0 24 24"
},
wp.element.createElement('path', {
fill: "none",
stroke: "currentColor",
strokeLinecap: "round",
strokeLinejoin: "round",
- strokeWidth: "1",
- d: isTextareaExpanded ? "m7 20l5-5l5 5M7 4l5 5l5-5" : "m7 15l5 5l5-5M7 9l5-5l5 5"
+ strokeWidth: "1.5",
+ d: "m7 15l5 5l5-5M7 9l5-5l5 5"
})
)
)
);
};
+ // Keep old function name for backward compatibility
+ const renderContextIndicator = renderFocusKeywordBar;
+
// Render contextual action card
const renderContextualAction = (intent) => {
if (!intent || intent === 'continue_chat') return null;
-
+
const actions = {
create_outline: {
icon: '📝',
@@ -4430,18 +4710,205 @@
description: 'I\'ll generate a structured outline based on our conversation.',
button: 'Create Outline Now',
onClick: async () => {
- // Switch to planning mode first
+ // Switch to planning mode
setAgentMode('planning');
-
- // Set the input message
- const outlineMessage = 'Create an outline based on our discussion';
- setInput(outlineMessage);
-
- // Trigger the send message function directly with planning mode
- // This ensures proper flow through detect_intent -> clarity_check -> generate_plan
- setTimeout(() => {
- sendMessage();
- }, 100);
+
+ // Get topic from focus keyword or chat history
+ const focusKw = selectedFocusKeyword || postConfig.focus_keyword || postConfig.seo_focus_keyword;
+ const firstUserMsg = messages.find(m => m.role === 'user');
+ const topic = focusKw || (firstUserMsg ? firstUserMsg.content.substring(0, 100) : '');
+
+ // Don't add any user message - directly trigger outline generation
+ setInput('');
+ setIsLoading(true);
+
+ // Add timeline entry
+ setMessages(prev => [...deactivateActiveTimelineEntries(prev), {
+ role: 'system',
+ type: 'timeline',
+ status: 'checking',
+ message: 'Analyzing request...',
+ timestamp: new Date()
+ }]);
+
+ // Call clarity check - MANDATORY before outline generation
+ try {
+ console.log('[WPAW] Calling clarity check with topic:', topic);
+ const clarityResponse = await fetch(wpAgenticWriter.apiUrl + '/check-clarity', {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ 'X-WP-Nonce': wpAgenticWriter.nonce,
+ },
+ body: JSON.stringify({
+ topic: topic || 'article outline',
+ answers: [],
+ postId: postId,
+ mode: 'generation',
+ postConfig: postConfig,
+ chatHistory: messages.filter(m => m.role === 'user' || m.role === 'assistant').slice(-10),
+ }),
+ });
+
+ console.log('[WPAW] Clarity response status:', clarityResponse.status);
+
+ if (!clarityResponse.ok) {
+ const errorText = await clarityResponse.text();
+ console.error('[WPAW] Clarity check failed:', errorText);
+ throw new Error('Clarity check failed: ' + errorText);
+ }
+
+ const clarityData = await clarityResponse.json();
+ const clarityResult = clarityData.result;
+ console.log('[WPAW] Clarity result:', clarityResult);
+
+ if (clarityResult.detected_language) {
+ setDetectedLanguage(clarityResult.detected_language);
+ }
+
+ // MANDATORY: Always show quiz if questions exist
+ if (clarityResult.questions && clarityResult.questions.length > 0) {
+ console.log('[WPAW] Showing quiz with', clarityResult.questions.length, 'questions');
+ setQuestions(clarityResult.questions);
+ setInClarification(true);
+ setCurrentQuestionIndex(0);
+ setAnswers([]);
+ setIsLoading(false);
+
+ setMessages(prev => {
+ const newMessages = [...prev];
+ const lastTimelineIndex = findLastActiveTimelineIndex(newMessages);
+ if (lastTimelineIndex !== -1) {
+ newMessages[lastTimelineIndex] = {
+ ...newMessages[lastTimelineIndex],
+ status: 'waiting',
+ message: 'Waiting for clarification...'
+ };
+ }
+ return newMessages;
+ });
+ return; // Stop here - quiz must be completed first
+ } else {
+ console.warn('[WPAW] No questions returned from clarity check!');
+ }
+ } catch (clarityError) {
+ console.error('[WPAW] Clarity check error:', clarityError);
+ // Show error to user instead of silently proceeding
+ setMessages(prev => [...prev, {
+ role: 'system',
+ type: 'error',
+ content: 'Clarity check failed. Please try again.',
+ canRetry: true
+ }]);
+ setIsLoading(false);
+ return; // Don't proceed without clarity check
+ }
+
+ // Proceed with plan generation
+ setMessages(prev => {
+ const newMessages = [...prev];
+ const lastTimelineIndex = findLastActiveTimelineIndex(newMessages);
+ if (lastTimelineIndex !== -1) {
+ newMessages[lastTimelineIndex] = {
+ ...newMessages[lastTimelineIndex],
+ status: 'starting',
+ message: 'Creating outline...'
+ };
+ }
+ return newMessages;
+ });
+
+ try {
+ const response = await fetch(wpAgenticWriter.apiUrl + '/generate-plan', {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ 'X-WP-Nonce': wpAgenticWriter.nonce,
+ },
+ body: JSON.stringify({
+ topic: topic || 'article outline',
+ context: '',
+ postId: postId,
+ answers: [],
+ autoExecute: false,
+ stream: true,
+ articleLength: postConfig.article_length,
+ detectedLanguage: detectedLanguage,
+ postConfig: postConfig,
+ chatHistory: messages.filter(m => m.role === 'user' || m.role === 'assistant').slice(-10),
+ }),
+ });
+
+ if (!response.ok) {
+ const error = await response.json();
+ setMessages(prev => [...prev, {
+ role: 'system',
+ type: 'error',
+ content: 'Error: ' + (error.message || 'Failed to generate outline'),
+ canRetry: true
+ }]);
+ setIsLoading(false);
+ return;
+ }
+
+ // Handle streaming response
+ streamTargetRef.current = null;
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder();
+
+ while (true) {
+ const { done, value } = await reader.read();
+ if (done) break;
+
+ const chunk = decoder.decode(value, { stream: true });
+ const lines = chunk.split('\n');
+
+ for (const line of lines) {
+ if (line.startsWith('data: ')) {
+ try {
+ const data = JSON.parse(line.slice(6));
+
+ if (data.type === 'plan') {
+ setCost(prev => ({ ...prev, session: prev.session + (data.cost || 0) }));
+ if (data.plan) {
+ updateOrCreatePlanMessage(data.plan);
+ }
+ } else if (data.type === 'status') {
+ if (data.status === 'complete') {
+ continue;
+ }
+ setMessages(prev => {
+ const newMessages = [...prev];
+ const lastTimelineIndex = findLastActiveTimelineIndex(newMessages);
+ if (lastTimelineIndex !== -1) {
+ newMessages[lastTimelineIndex] = {
+ ...newMessages[lastTimelineIndex],
+ status: data.status,
+ message: data.message,
+ icon: data.icon
+ };
+ }
+ return newMessages;
+ });
+ }
+ } catch (parseError) {
+ console.error('Failed to parse streaming data:', parseError);
+ }
+ }
+ }
+ }
+
+ setIsLoading(false);
+ } catch (error) {
+ const errorMsg = error.message || 'Failed to generate outline';
+ setMessages(prev => [...prev, {
+ role: 'system',
+ type: 'error',
+ content: 'Error: ' + errorMsg,
+ canRetry: true
+ }]);
+ setIsLoading(false);
+ }
}
},
start_writing: {
@@ -4457,22 +4924,22 @@
}
}
};
-
- const action = actions[intent];
- if (!action) return null;
-
- return wp.element.createElement('div', { className: 'wpaw-contextual-action' },
- wp.element.createElement('div', { className: 'wpaw-action-icon' }, action.icon),
- wp.element.createElement('div', { className: 'wpaw-action-content' },
- wp.element.createElement('h4', null, action.title),
- wp.element.createElement('p', null, action.description),
- wp.element.createElement(Button, {
- isPrimary: true,
- onClick: action.onClick
- }, action.button)
- )
- );
- };
+
+ const action = actions[intent];
+ if (!action) return null;
+
+ return wp.element.createElement('div', { className: 'wpaw-contextual-action' },
+ wp.element.createElement('div', { className: 'wpaw-action-icon' }, action.icon),
+ wp.element.createElement('div', { className: 'wpaw-action-content' },
+ wp.element.createElement('h4', null, action.title),
+ wp.element.createElement('p', null, action.description),
+ wp.element.createElement(Button, {
+ isPrimary: true,
+ onClick: action.onClick
+ }, action.button)
+ )
+ );
+ };
// Render chat messages with timeline
const renderMessages = () => {
@@ -4797,8 +5264,16 @@
wp.element.createElement('span', null, 'Processing updates…')
),
!showProcessing && isLoading && isLastGroup && isLastItem && wp.element.createElement('div', {
- className: 'wpaw-streaming-indicator',
- }, streamingLabel)
+ className: 'wpaw-typing-indicator',
+ 'aria-label': 'Agent is typing',
+ },
+ streamingLabel,
+ wp.element.createElement('span', { className: 'wpaw-typing-dots' },
+ wp.element.createElement('span', null),
+ wp.element.createElement('span', null),
+ wp.element.createElement('span', null)
+ )
+ )
)
);
}
@@ -4821,13 +5296,13 @@
// Build config summary
const configSummary = [];
- const languageLabel = postConfig.language === 'auto' ? 'Auto-detect' :
+ const languageLabel = postConfig.language === 'auto' ? 'Auto-detect' :
postConfig.language.charAt(0).toUpperCase() + postConfig.language.slice(1);
configSummary.push(`🌍 Language: ${languageLabel}`);
-
+
const lengthLabels = { short: 'Short (~800 words)', medium: 'Medium (~1500 words)', long: 'Long (~2500 words)' };
configSummary.push(`📏 Length: ${lengthLabels[postConfig.article_length] || 'Medium'}`);
-
+
if (postConfig.audience) {
configSummary.push(`👥 Audience: ${postConfig.audience}`);
}
@@ -4988,8 +5463,16 @@
},
wp.element.createElement('div', { className: 'wpaw-response-content' }, renderMessageContent(message.content, true)),
isLoading && isLastGroup && isLastItem && wp.element.createElement('div', {
- className: 'wpaw-streaming-indicator',
- }, streamingLabel),
+ className: 'wpaw-typing-indicator',
+ 'aria-label': 'Agent is typing',
+ },
+ streamingLabel,
+ wp.element.createElement('span', { className: 'wpaw-typing-dots' },
+ wp.element.createElement('span', null),
+ wp.element.createElement('span', null),
+ wp.element.createElement('span', null)
+ )
+ ),
message.detectedIntent && renderContextualAction(message.detectedIntent),
message.showResumeActions && wp.element.createElement('div', { className: 'wpaw-resume-actions' },
wp.element.createElement(Button, {
@@ -5051,53 +5534,53 @@
),
wp.element.createElement('div', { className: 'wpaw-config-section' },
wp.element.createElement('label', null, 'ARTICLE LENGTH'),
- wp.element.createElement('select', {
- value: postConfig.article_length,
- onChange: (e) => updatePostConfig('article_length', e.target.value),
- disabled: isConfigDisabled,
- className: 'wpaw-select'
- },
- wp.element.createElement('option', { value: 'short' }, 'Short (500-800 words)'),
- wp.element.createElement('option', { value: 'medium' }, 'Medium (800-1500 words)'),
- wp.element.createElement('option', { value: 'long' }, 'Long (1500-2500 words)')
- )
- ),
- wp.element.createElement('div', { className: 'wpaw-config-section' },
- wp.element.createElement('label', null, 'Language'),
- wp.element.createElement('select', {
- value: postConfig.language,
- onChange: (e) => updatePostConfig('language', e.target.value),
- disabled: isConfigDisabled,
- className: 'wpaw-select'
- },
- (() => {
- const preferredLanguages = settings.preferred_languages || ['auto', 'English', 'Indonesian'];
- const customLanguages = settings.custom_languages || [];
- const allLanguages = [...preferredLanguages, ...customLanguages];
- return allLanguages.map((lang) => {
- const langLower = lang.toLowerCase();
- const displayName = lang === 'auto' ? 'Auto-detect' : lang;
- return wp.element.createElement('option', { key: langLower, value: langLower }, displayName);
- });
- })()
+ wp.element.createElement('select', {
+ value: postConfig.article_length,
+ onChange: (e) => updatePostConfig('article_length', e.target.value),
+ disabled: isConfigDisabled,
+ className: 'wpaw-select'
+ },
+ wp.element.createElement('option', { value: 'short' }, 'Short (500-800 words)'),
+ wp.element.createElement('option', { value: 'medium' }, 'Medium (800-1500 words)'),
+ wp.element.createElement('option', { value: 'long' }, 'Long (1500-2500 words)')
+ )
),
- wp.element.createElement('p', { className: 'description' },
- 'Overrides the detected language when writing or refining.'
- )
- ),
- wp.element.createElement('div', { className: 'wpaw-config-section' },
- wp.element.createElement(TextControl, {
- label: 'Tone',
- value: postConfig.tone,
- onChange: (value) => updatePostConfig('tone', value),
- disabled: isConfigDisabled,
- placeholder: 'e.g., Friendly, persuasive, professional',
- }),
- wp.element.createElement('p', { className: 'description' },
- 'Use this to consistently guide the writing tone.'
- )
- ),
- wp.element.createElement('div', { className: 'wpaw-config-section' },
+ wp.element.createElement('div', { className: 'wpaw-config-section' },
+ wp.element.createElement('label', null, 'Language'),
+ wp.element.createElement('select', {
+ value: postConfig.language,
+ onChange: (e) => updatePostConfig('language', e.target.value),
+ disabled: isConfigDisabled,
+ className: 'wpaw-select'
+ },
+ (() => {
+ const preferredLanguages = settings.preferred_languages || ['auto', 'English', 'Indonesian'];
+ const customLanguages = settings.custom_languages || [];
+ const allLanguages = [...preferredLanguages, ...customLanguages];
+ return allLanguages.map((lang) => {
+ const langLower = lang.toLowerCase();
+ const displayName = lang === 'auto' ? 'Auto-detect' : lang;
+ return wp.element.createElement('option', { key: langLower, value: langLower }, displayName);
+ });
+ })()
+ ),
+ wp.element.createElement('p', { className: 'description' },
+ 'Overrides the detected language when writing or refining.'
+ )
+ ),
+ wp.element.createElement('div', { className: 'wpaw-config-section' },
+ wp.element.createElement(TextControl, {
+ label: 'Tone',
+ value: postConfig.tone,
+ onChange: (value) => updatePostConfig('tone', value),
+ disabled: isConfigDisabled,
+ placeholder: 'e.g., Friendly, persuasive, professional',
+ }),
+ wp.element.createElement('p', { className: 'description' },
+ 'Use this to consistently guide the writing tone.'
+ )
+ ),
+ wp.element.createElement('div', { className: 'wpaw-config-section' },
wp.element.createElement('label', null, 'Experience Level'),
wp.element.createElement('select', {
value: postConfig.experience_level,
@@ -5183,7 +5666,7 @@
rows: 3,
}),
wp.element.createElement('div', { className: 'wpaw-meta-info' },
- wp.element.createElement('span', {
+ wp.element.createElement('span', {
className: (postConfig.seo_meta_description?.length || 0) >= 120 && (postConfig.seo_meta_description?.length || 0) <= 160 ? 'good' : 'warning'
}, `${postConfig.seo_meta_description?.length || 0}/160 chars`),
wp.element.createElement(Button, {
@@ -5191,30 +5674,30 @@
isSmall: true,
onClick: () => generateMetaDescription(),
disabled: isConfigDisabled || isGeneratingMeta,
- },
- isGeneratingMeta ?
- wp.element.createElement('span', {
- style: { display: 'flex', alignItems: 'center', gap: '5px' }
- },
+ },
+ isGeneratingMeta ?
wp.element.createElement('span', {
- className: 'wpaw-spinning-icon',
- dangerouslySetInnerHTML: {
- __html: ''
- }
- }),
- ' Generating...'
- ) :
- wp.element.createElement('span', {
- style: { display: 'flex', alignItems: 'center', gap: '5px' }
- },
+ style: { display: 'flex', alignItems: 'center', gap: '5px' }
+ },
+ wp.element.createElement('span', {
+ className: 'wpaw-spinning-icon',
+ dangerouslySetInnerHTML: {
+ __html: ''
+ }
+ }),
+ ' Generating...'
+ ) :
wp.element.createElement('span', {
- className: 'wpaw-svg-wrapper',
- dangerouslySetInnerHTML: {
- __html: ''
- }
- }),
- ' Generate'
- )
+ style: { display: 'flex', alignItems: 'center', gap: '5px' }
+ },
+ wp.element.createElement('span', {
+ className: 'wpaw-svg-wrapper',
+ dangerouslySetInnerHTML: {
+ __html: ''
+ }
+ }),
+ ' Generate'
+ )
)
)
),
@@ -5228,34 +5711,34 @@
isSmall: true,
onClick: () => runSeoAudit(),
disabled: isConfigDisabled || isSeoAuditing,
- },
- isSeoAuditing ?
- wp.element.createElement('span', {
- style: { display: 'flex', alignItems: 'center', gap: '5px' }
- },
+ },
+ isSeoAuditing ?
wp.element.createElement('span', {
- className: 'wpaw-spinning-icon',
- style: { display: 'inline-flex', lineHeight: '0' },
- dangerouslySetInnerHTML: {
- // Icon Loader/Circle-slashed untuk kesan analyzing
- __html: ''
- }
- }),
- ' Analyzing...'
- ) :
- wp.element.createElement('span', {
- style: { display: 'flex', alignItems: 'center', gap: '5px' }
- },
+ style: { display: 'flex', alignItems: 'center', gap: '5px' }
+ },
+ wp.element.createElement('span', {
+ className: 'wpaw-spinning-icon',
+ style: { display: 'inline-flex', lineHeight: '0' },
+ dangerouslySetInnerHTML: {
+ // Icon Loader/Circle-slashed untuk kesan analyzing
+ __html: ''
+ }
+ }),
+ ' Analyzing...'
+ ) :
wp.element.createElement('span', {
- className: 'wpaw-svg-wrapper',
- style: { display: 'inline-flex', lineHeight: '0' },
- dangerouslySetInnerHTML: {
- // Icon Bar-Chart untuk "Run Audit"
- __html: ''
- }
- }),
- ' Run Audit'
- )
+ style: { display: 'flex', alignItems: 'center', gap: '5px' }
+ },
+ wp.element.createElement('span', {
+ className: 'wpaw-svg-wrapper',
+ style: { display: 'inline-flex', lineHeight: '0' },
+ dangerouslySetInnerHTML: {
+ // Icon Bar-Chart untuk "Run Audit"
+ __html: ''
+ }
+ }),
+ ' Run Audit'
+ )
)
),
seoAudit && wp.element.createElement('div', { className: 'wpaw-seo-audit-results' },
@@ -5276,7 +5759,7 @@
seoAudit.checks && wp.element.createElement('div', { className: 'wpaw-seo-checks' },
seoAudit.checks.map((check, idx) => {
const isPassed = check.status === 'good' || check.status === 'ok';
- return wp.element.createElement('div', {
+ return wp.element.createElement('div', {
key: idx,
className: 'wpaw-seo-check ' + (isPassed ? 'passed' : 'failed')
},
@@ -5324,7 +5807,7 @@
renderClarification(),
!inClarification && wp.element.createElement('div', { className: 'wpaw-chat-container' },
// Status Bar
- wp.element.createElement('div', { className: 'wpaw-status-bar' },
+ wp.element.createElement('div', { className: 'wpaw-status-bar', role: 'status', 'aria-live': 'polite' },
wp.element.createElement('div', { className: 'wpaw-status-indicator' },
wp.element.createElement('span', { className: 'wpaw-status-dot ' + agentStatus }),
wp.element.createElement('span', { className: 'wpaw-status-label' }, statusLabels[agentStatus])
@@ -5338,9 +5821,9 @@
disabled: isLoading
}, '↩️'),
// Cost Label
- wp.element.createElement('span', { className: 'wpaw-status-cost' },
- 'Session: $' + cost.session.toFixed(4)
- ),
+ // wp.element.createElement('span', { className: 'wpaw-status-cost' },
+ // 'Session: $' + cost.session.toFixed(4)
+ // ),
// Config Icon Button
wp.element.createElement('button', {
className: 'wpaw-status-icon-btn',
@@ -5359,39 +5842,41 @@
),
// Editor Lock Banner
isEditorLocked && wp.element.createElement('div', { className: 'wpaw-editor-lock-banner' },
- 'Writing in progress — please wait until the article finishes.'
- ),
- // Writing Mode Empty State
- shouldShowWritingEmptyState() && renderWritingEmptyState(),
- // Activity Log
- !shouldShowWritingEmptyState() && wp.element.createElement('div', { className: 'wpaw-messages wpaw-activity-log' },
- wp.element.createElement('div', { className: 'wpaw-messages-inner', ref: messagesContainerRef },
- renderMessages(),
- wp.element.createElement('div', { ref: messagesEndRef })
- )
- ),
- // Context Indicator (moved above textarea)
- renderContextIndicator(),
- // Command Input Area
- wp.element.createElement('div', { className: 'wpaw-command-area', style: { position: 'relative' } },
- // Removed Toolbar from Top
- wp.element.createElement('div', {
- className: 'wpaw-command-input-wrapper' + (isTextareaExpanded ? ' expanded' : '')
- },
- wp.element.createElement('span', { className: 'wpaw-command-prefix' }, '>'),
- wp.element.createElement(TextareaControl, {
- ref: inputRef,
- value: input,
- onChange: handleInputChange,
- onKeyDown: handleKeyDown,
- rows: isTextareaExpanded ? 20 : 3,
- placeholder: agentMode === 'planning'
- ? 'Describe what you want to write about...'
- : agentMode === 'chat'
- ? 'Ask me anything about your content...'
- : 'Tell me what to write. Use @block to refine.'
- })
+ 'Writing in progress — please wait until the article finishes.'
),
+ // Welcome Screen (first time)
+ showWelcome && !isEditorLocked && renderWelcomeScreen(),
+ // Writing Mode Empty State
+ !showWelcome && shouldShowWritingEmptyState() && renderWritingEmptyState(),
+ // Activity Log
+ !showWelcome && !shouldShowWritingEmptyState() && wp.element.createElement('div', { className: 'wpaw-messages wpaw-activity-log' },
+ wp.element.createElement('div', { className: 'wpaw-messages-inner', ref: messagesContainerRef },
+ renderMessages(),
+ wp.element.createElement('div', { ref: messagesEndRef })
+ )
+ ),
+ // Context Indicator (moved above textarea) - hide when showing empty state or welcome
+ !showWelcome && !shouldShowWritingEmptyState() && renderContextIndicator(),
+ // Command Input Area - hide when showing empty state or welcome
+ !showWelcome && !shouldShowWritingEmptyState() && wp.element.createElement('div', { className: 'wpaw-command-area', style: { position: 'relative' } },
+ // Removed Toolbar from Top
+ wp.element.createElement('div', {
+ className: 'wpaw-command-input-wrapper' + (isTextareaExpanded ? ' expanded' : '')
+ },
+ wp.element.createElement('span', { className: 'wpaw-command-prefix' }, '>'),
+ wp.element.createElement(TextareaControl, {
+ ref: inputRef,
+ value: input,
+ onChange: handleInputChange,
+ onKeyDown: handleKeyDown,
+ rows: isTextareaExpanded ? 20 : 3,
+ placeholder: agentMode === 'planning'
+ ? 'Describe what you want to write about...'
+ : agentMode === 'chat'
+ ? 'Ask me anything about your content...'
+ : 'Tell me what to write. Use @block to refine.'
+ })
+ ),
showMentionAutocomplete && mentionOptions.length > 0 && wp.element.createElement('div', {
className: 'wpaw-mention-autocomplete',
style: {
@@ -5467,7 +5952,7 @@
wp.element.createElement('div', { className: 'wpaw-command-actions' },
wp.element.createElement('div', { className: 'wpaw-command-actions-group' },
-
+
// Mode Selector (Bottom Left)
wp.element.createElement('div', { className: 'wpaw-command-mode-wrapper' },
wp.element.createElement('span', { className: 'wpaw-command-label' }, 'MODE:'),
@@ -5485,22 +5970,44 @@
),
// Web Search Toggle (next to mode)
- wp.element.createElement('label', {
- className: 'wpaw-web-search-toggle',
- title: 'Enable web search for current data (costs ~$0.02/search)',
- },
- wp.element.createElement('input', {
- type: 'checkbox',
- checked: postConfig.web_search || false,
- onChange: (e) => updatePostConfig('web_search', e.target.checked),
- disabled: isLoading,
- }),
- wp.element.createElement('span', {
- className: 'wpaw-web-search-icon',
- dangerouslySetInnerHTML: { __html: '' }
- }),
- wp.element.createElement('span', { className: 'wpaw-web-search-label' }, 'Search')
- ),
+ (() => {
+ // Determine if web search is available for the current provider
+ const taskProviders = settings.task_providers || {};
+ const currentProvider = taskProviders[agentMode] || 'openrouter';
+ const isNonOpenRouter = currentProvider === 'local_backend' || currentProvider === 'codex';
+ const hasBraveKey = Boolean(settings.brave_search_api_key);
+ const searchBlocked = isNonOpenRouter && !hasBraveKey;
+ const tooltipText = searchBlocked
+ ? 'Web Search unavailable — Brave API Key required for ' + currentProvider.replace('_', ' ') + '. Configure in Settings > General.'
+ : isNonOpenRouter
+ ? 'Web search via Brave Search API (free tier: 2,000 req/mo)'
+ : 'Web search via OpenRouter (~$0.02/search)';
+
+ return wp.element.createElement('label', {
+ className: 'wpaw-web-search-toggle' + (searchBlocked ? ' wpaw-search-blocked' : ''),
+ title: tooltipText,
+ onClick: searchBlocked ? (e) => {
+ e.preventDefault();
+ alert('Web Search for ' + currentProvider.replace('_', ' ') + ' requires a Brave Search API Key.\n\nGet a free key (2,000 requests/month) and configure it in:\nWP Agentic Writer Settings → General → Brave Search API Key');
+ } : undefined,
+ },
+ wp.element.createElement('input', {
+ type: 'checkbox',
+ checked: searchBlocked ? false : (postConfig.web_search || false),
+ onChange: searchBlocked ? () => { } : (e) => {
+ updatePostConfig('web_search', e.target.checked);
+ },
+ disabled: isLoading || searchBlocked,
+ }),
+ wp.element.createElement('span', {
+ className: 'wpaw-web-search-icon',
+ dangerouslySetInnerHTML: { __html: '' }
+ }),
+ wp.element.createElement('span', { className: 'wpaw-web-search-label' },
+ searchBlocked ? 'Search ✕' : 'Search'
+ )
+ );
+ })(),
),
wp.element.createElement('div', { className: 'wpaw-command-actions-group' },
@@ -5535,6 +6042,11 @@
}
})
)
+ ),
+ wp.element.createElement('div', { className: 'wpaw-keyboard-hints', 'aria-hidden': 'true' },
+ wp.element.createElement('span', { className: 'wpaw-kbd' }, wp.element.createElement('kbd', null, /Mac|iPod|iPhone|iPad/.test(navigator.platform) ? '⌘' : 'Ctrl'), '+', wp.element.createElement('kbd', null, '↵'), ' Send'),
+ wp.element.createElement('span', { className: 'wpaw-kbd' }, wp.element.createElement('kbd', null, '@'), ' Blocks'),
+ wp.element.createElement('span', { className: 'wpaw-kbd' }, wp.element.createElement('kbd', null, '/'), ' Commands')
)
)
)
@@ -5581,7 +6093,7 @@
className: 'wpaw-back-btn',
onClick: () => setActiveTab('chat')
}, '← Back'),
- wp.element.createElement('h3', null, 'COST TRACKING'),
+ wp.element.createElement('h3', null, 'OPENROUTER COST'),
wp.element.createElement('button', {
className: 'wpaw-refresh-btn',
dangerouslySetInnerHTML: { __html: '' },
@@ -5625,7 +6137,7 @@
className: 'wpaw-budget-warning ' + budgetStatus,
}, budgetPercent >= 100 ? '⚠️ Budget exceeded!' : '⚠️ Approaching budget limit'),
costHistory.length > 0 && wp.element.createElement('div', { className: 'wpaw-cost-history' },
- wp.element.createElement('h4', null, 'Cost History'),
+ wp.element.createElement('h4', null, 'OpenRouter Cost History'),
wp.element.createElement('div', { className: 'wpaw-cost-table-wrapper' },
wp.element.createElement('table', { className: 'wpaw-cost-table' },
wp.element.createElement('thead', null,
@@ -5634,7 +6146,7 @@
wp.element.createElement('th', null, 'Action'),
wp.element.createElement('th', null, 'Model'),
wp.element.createElement('th', null, 'Tokens'),
- wp.element.createElement('th', null, 'Cost')
+ wp.element.createElement('th', null, 'Cost(US$)')
)
),
wp.element.createElement('tbody', null,
@@ -5659,7 +6171,7 @@
href: settings.settings_url || '/wp-admin/options-general.php?page=wp-agentic-writer',
target: '_blank',
className: 'wpaw-cost-settings-link'
- },
+ },
wp.element.createElement('span', {
dangerouslySetInnerHTML: { __html: ' Manage Budget Settings' }
}),
@@ -5669,8 +6181,8 @@
};
// Main render.
- return wp.element.createElement(PluginSidebar, {
- name: 'wp-agentic-writer',
+ return wp.element.createElement(PluginSidebar, {
+ name: 'wp-agentic-writer',
title: wp.element.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: '8px' } },
wp.element.createElement('img', {
src: wpAgenticWriter.pluginUrl + '/assets/img/icon.svg',
diff --git a/brave_search_integration.md b/brave_search_integration.md
new file mode 100644
index 0000000..aeeb45a
--- /dev/null
+++ b/brave_search_integration.md
@@ -0,0 +1,1220 @@
+# WP Agentic Writer: Brave Search API Integration Guide
+
+## Executive Summary
+
+This document defines the **complete integration** of **Brave Search API** into WP Agentic Writer to enhance article generation with real-time web research, citations, and fact-grounding.
+
+**Key principle:** During article generation, the writing agent calls Brave Search API to fetch current data, verify facts, gather citations, and ground responses in real sources. All search results are logged, cached, and attributed.
+
+---
+
+## Table of Contents
+
+1. [Overview & Architecture](#overview--architecture)
+2. [Brave Search API Fundamentals](#brave-search-api-fundamentals)
+3. [Data Model & Database Schema](#data-model--database-schema)
+4. [Flow 1: Agent Research Planning](#flow-1-agent-research-planning)
+5. [Flow 2: Brave Search API Integration](#flow-2-brave-search-api-integration)
+6. [Flow 3: Citation Management](#flow-3-citation-management)
+7. [Flow 4: Search Result Caching](#flow-4-search-result-caching)
+8. [Flow 5: Admin Dashboard & Analytics](#flow-5-admin-dashboard--analytics)
+9. [REST API Endpoints](#rest-api-endpoints)
+10. [Configuration & Settings](#configuration--settings)
+11. [Cost Optimization & Budget Management](#cost-optimization--budget-management)
+12. [Implementation Checklist](#implementation-checklist)
+
+---
+
+## Overview & Architecture
+
+### Core Concept
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ USER: "Write article about N8n automation workflows" │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ WRITING AGENT receives request │
+│ - Analyzes: topic, target audience, depth needed │
+│ - Plans research: "Need current N8n features, pricing, users" │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ AGENT → Brave Search API (Multiple searches) │
+│ │
+│ Search 1: "N8n automation platform 2024" │
+│ Search 2: "N8n pricing plans features" │
+│ Search 3: "N8n vs Zapier Make comparison" │
+│ Search 4: "N8n self-hosted deployment guide" │
+│ │
+│ Each search: Get 10-15 results with snippets + URLs │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ BACKEND: Store searches in DB │
+│ │
+│ wp_agentic_searches table: │
+│ - post_id, search_query, results (serialized), cost │
+│ - cache_enabled (reuse for 30 days) │
+│ │
+│ wp_agentic_citations table: │
+│ - post_id, citation_text, url, source_title, position │
+│ - [1], [2], [3] numbered references │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ AGENT: Generates article WITH research │
+│ │
+│ "N8n is an open-source workflow automation platform[1] │
+│ enabling teams to automate tasks[2]. In 2024, N8n added[3]... │
+│ │
+│ Key features include visual workflow builder[1], │
+│ 500+ integrations[2], and self-hosting options[3]." │
+│ │
+│ Returns: Article blocks + citations (with sources) │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PLUGIN: Create Gutenberg post with: │
+│ - Article content │
+│ - Inline citations [1], [2], [3] │
+│ - References section at end (with URLs) │
+│ - Search context sidebar (optional) │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ ADMIN DASHBOARD: "Generated Searches" │
+│ │
+│ Show: │
+│ - All searches per post + results count │
+│ - Cost per search ($0.009 per query for AI tier) │
+│ - Cache status (reusable until expiry) │
+│ - Citation coverage (% of facts cited) │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Brave Search API Fundamentals
+
+### API Plans & Pricing (2024)
+
+**Free Tier (for testing):**
+- 1 query/second
+- 2,000 queries/month (~$0)
+- Great for development & testing
+
+**Data for AI - Base ($5 per 1,000 requests):**
+- 20 queries/second
+- Up to 20M queries/month
+- Up to 5 snippets per result
+- Extra alternate snippets for AI
+- Rights to use in AI apps
+
+**Data for AI - Pro ($9 per 1,000 requests):**
+- 50 queries/second
+- Unlimited queries/month
+- Same features as Base + schema-enriched results
+- Recommended for production AI apps
+
+### Key Advantages Over Alternatives
+
+| Feature | Brave Search | Google Search | Bing Search |
+|---------|-----------|---------|---------|
+| **Cost** | $3-9 CPM | ~$20 CPM | ~$15 CPM |
+| **Independent Index** | Yes (30B+ pages) | No (proprietary) | No (proprietary) |
+| **Privacy** | Yes (no tracking) | No | No |
+| **AI Rights** | Explicit in plan | Unclear | Unclear |
+| **Fresh Data** | 100M updates/day | Daily | Daily |
+| **Latency** | ~2-3s average | Fast | Fast |
+
+---
+
+## Data Model & Database Schema
+
+### Table: `wp_agentic_searches`
+
+Stores all Brave Search API calls made during article generation.
+
+```sql
+CREATE TABLE wp_agentic_searches (
+ id BIGINT AUTO_INCREMENT PRIMARY KEY,
+ post_id BIGINT NOT NULL,
+
+ -- Search details
+ search_query VARCHAR(500) NOT NULL, -- "N8n automation features"
+ search_number INT, -- 1st, 2nd, 3rd search
+ total_searches_for_post INT, -- "Need 3 searches for this post"
+
+ -- Brave API response
+ results_count INT, -- How many results returned
+ results_json LONGTEXT, -- Serialized JSON from Brave
+ top_result_title VARCHAR(255), -- First result title
+ top_result_url VARCHAR(500), -- First result URL
+
+ -- Cost tracking
+ cost DECIMAL(10, 4), -- $0.009 per query (AI Base)
+ api_tier VARCHAR(50), -- 'free', 'base_ai', 'pro_ai'
+
+ -- Caching
+ cache_enabled TINYINT DEFAULT 1, -- Can this be reused?
+ cache_expires_at TIMESTAMP, -- Expires in 30 days
+ cache_hit TINYINT DEFAULT 0, -- 1 if used cached result
+
+ -- Metadata
+ search_category VARCHAR(100), -- 'features', 'pricing', 'competitors', 'news'
+ agent_decision TEXT, -- Why agent chose this search
+ relevance_score DECIMAL(3,2), -- Agent rating 0-1.0 of relevance
+ status VARCHAR(30) DEFAULT 'completed', -- completed, failed, rate_limited
+ error_message TEXT, -- If failed
+
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+ KEY idx_post (post_id),
+ KEY idx_query (search_query),
+ KEY idx_cache_expires (cache_expires_at),
+ KEY idx_status (status),
+ KEY idx_created (created_at)
+);
+```
+
+### Table: `wp_agentic_citations`
+
+Tracks every citation [1], [2], [3]... in the article with source URL.
+
+```sql
+CREATE TABLE wp_agentic_citations (
+ id BIGINT AUTO_INCREMENT PRIMARY KEY,
+ post_id BIGINT NOT NULL,
+
+ -- Citation numbering
+ citation_number INT NOT NULL, -- [1], [2], [3]...
+ citation_text VARCHAR(500), -- Text that was cited
+ context_excerpt TEXT, -- Sentence containing citation
+
+ -- Source information
+ search_id BIGINT, -- Reference to wp_agentic_searches
+ source_url VARCHAR(500) NOT NULL, -- Full URL of source
+ source_title VARCHAR(255), -- "N8n Pricing | Official Website"
+ source_domain VARCHAR(100), -- "n8n.io"
+ source_type VARCHAR(50), -- 'official_website', 'blog', 'news', 'doc'
+
+ -- Citation credibility
+ source_authority INT, -- 1-100 (domain authority estimate)
+ result_position INT, -- Was this the 1st, 5th, 10th result?
+ snippet_match_score DECIMAL(3,2), -- % match with snippet
+
+ -- Article placement
+ article_section VARCHAR(100), -- "Introduction", "Features", "Pricing"
+ paragraph_number INT, -- Which paragraph in section
+ sentence_number INT, -- Which sentence in paragraph
+ inline_position INT, -- Position of [N] in sentence
+
+ -- Metadata
+ added_by VARCHAR(50), -- 'agent_automatic' or 'user_manual'
+ verified TINYINT DEFAULT 0, -- User confirmed source is correct
+ is_required TINYINT DEFAULT 1, -- Essential citation vs optional
+
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+ KEY idx_post (post_id),
+ KEY idx_citation_number (post_id, citation_number),
+ KEY idx_source_domain (source_domain),
+ KEY idx_created (created_at)
+);
+```
+
+### Table: `wp_agentic_search_cache`
+
+Cache layer for frequently searched topics.
+
+```sql
+CREATE TABLE wp_agentic_search_cache (
+ id BIGINT AUTO_INCREMENT PRIMARY KEY,
+
+ -- Cache key
+ search_query_normalized VARCHAR(500) NOT NULL, -- Lowercase, trimmed
+ search_category VARCHAR(100), -- Optional: 'news', 'trends'
+ cache_key VARCHAR(64), -- SHA1 hash of query
+
+ -- Cached data
+ results_json LONGTEXT, -- Complete Brave response
+ result_count INT,
+ cached_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ expires_at TIMESTAMP, -- 30 days from creation
+
+ -- Usage tracking
+ hit_count INT DEFAULT 0, -- Times this cache was used
+ cost_saved DECIMAL(10, 4), -- Cumulative cost avoided
+
+ -- Quality
+ quality_score DECIMAL(3,2), -- 0-1.0 relevance rating
+
+ UNIQUE KEY unique_query_category (search_query_normalized, search_category),
+ KEY idx_expires (expires_at),
+ KEY idx_hit_count (hit_count)
+);
+```
+
+---
+
+## Flow 1: Agent Research Planning
+
+### How the Agent Decides What to Search
+
+```php
+ "$topic what is",
+ 'category' => 'definition',
+ 'priority' => 'critical',
+ 'intent' => 'Define what N8n is, core features'
+ ];
+
+ if ($depth === 'medium' || $depth === 'deep') {
+ // Tier 2: Current state & news
+ $searches[] = [
+ 'query' => "$topic latest news 2024",
+ 'category' => 'news',
+ 'priority' => 'high',
+ 'intent' => 'Recent developments, updates'
+ ];
+
+ // Tier 3: Pricing & comparison
+ $searches[] = [
+ 'query' => "$topic pricing plans features",
+ 'category' => 'pricing',
+ 'priority' => 'high',
+ 'intent' => 'Current pricing, plan comparison'
+ ];
+
+ // Tier 4: Alternatives & comparison
+ $searches[] = [
+ 'query' => "$topic vs alternatives competitors",
+ 'category' => 'comparison',
+ 'priority' => 'medium',
+ 'intent' => 'How does it compare to Zapier, Make, etc'
+ ];
+ }
+
+ if ($depth === 'deep') {
+ // Tier 5: Use cases & case studies
+ $searches[] = [
+ 'query' => "$topic use cases examples case studies",
+ 'category' => 'examples',
+ 'priority' => 'medium',
+ 'intent' => 'Real-world examples and success stories'
+ ];
+
+ // Tier 6: Technical implementation
+ $searches[] = [
+ 'query' => "$topic documentation api integration",
+ 'category' => 'technical',
+ 'priority' => 'medium',
+ 'intent' => 'How to implement, API docs, guides'
+ ];
+ }
+
+ return $searches;
+ }
+}
+```
+
+---
+
+## Flow 2: Brave Search API Integration
+
+### Backend: Brave Search Client
+
+```php
+api_key = $api_key ?? get_option('agentic_brave_api_key');
+ $this->rate_limiter = new RateLimiter();
+ }
+
+ /**
+ * Main search method
+ * Handles caching, rate limiting, cost tracking
+ */
+ public function search($query, $options = []) {
+ // 1. Check cache first
+ $cached = $this->check_cache($query, $options['category'] ?? null);
+ if ($cached) {
+ return [
+ 'results' => $cached['results_json'],
+ 'from_cache' => true,
+ 'cache_age_hours' => $cached['age']
+ ];
+ }
+
+ // 2. Rate limit check
+ if (!$this->rate_limiter->allow_request($this->api_key)) {
+ return new WP_Error(
+ 'rate_limit_exceeded',
+ 'Brave Search API rate limit exceeded. Try again in ' .
+ $this->rate_limiter->get_reset_time() . ' seconds'
+ );
+ }
+
+ // 3. Call Brave API
+ $start_time = microtime(true);
+ $response = $this->call_brave_api($query, $options);
+ $execution_time = microtime(true) - $start_time;
+
+ if (is_wp_error($response)) {
+ return $response;
+ }
+
+ // 4. Store search in database
+ $cost = $this->calculate_cost($this->get_tier());
+ $search_id = $this->store_search(
+ $query,
+ $response,
+ $cost,
+ $options
+ );
+
+ // 5. Cache the results
+ $this->cache_results($query, $response, $options);
+
+ // 6. Track cost
+ update_option(
+ 'agentic_brave_total_cost',
+ (float)get_option('agentic_brave_total_cost', 0) + $cost
+ );
+
+ return [
+ 'results' => $response,
+ 'from_cache' => false,
+ 'search_id' => $search_id,
+ 'cost' => $cost,
+ 'execution_time' => $execution_time,
+ 'result_count' => count($response['web']['results'] ?? [])
+ ];
+ }
+
+ /**
+ * Call Brave Search API
+ */
+ private function call_brave_api($query, $options = []) {
+ $endpoint = $this->api_base . '/web/search';
+
+ $params = [
+ 'q' => $query,
+ 'count' => $options['count'] ?? 10,
+ 'safesearch' => 'moderate',
+ 'search_lang' => $options['language'] ?? 'en',
+ 'country' => $options['country'] ?? 'US',
+ ];
+
+ // Optional: Use Search Goggles for custom ranking
+ if (!empty($options['goggle'])) {
+ $params['goggles_id'] = $options['goggle'];
+ }
+
+ $response = wp_remote_get(
+ add_query_arg($params, $endpoint),
+ [
+ 'headers' => [
+ 'X-Subscription-Token' => $this->api_key,
+ 'Accept' => 'application/json'
+ ],
+ 'timeout' => 30
+ ]
+ );
+
+ if (is_wp_error($response)) {
+ return new WP_Error(
+ 'api_request_failed',
+ 'Brave Search API request failed: ' . $response->get_error_message()
+ );
+ }
+
+ $status = wp_remote_retrieve_response_code($response);
+ $body = json_decode(wp_remote_retrieve_body($response), true);
+
+ // Handle API errors
+ if ($status === 429) {
+ // Rate limited
+ return new WP_Error('rate_limited', 'API rate limit hit');
+ } elseif ($status === 401) {
+ return new WP_Error('invalid_api_key', 'Invalid Brave API key');
+ } elseif ($status !== 200) {
+ return new WP_Error(
+ 'api_error',
+ 'Brave API returned status ' . $status,
+ ['response_body' => $body]
+ );
+ }
+
+ return $body;
+ }
+
+ /**
+ * Check if results are cached
+ */
+ private function check_cache($query, $category = null) {
+ global $wpdb;
+
+ $cache_key = sha1(strtolower(trim($query)));
+
+ $cached = $wpdb->get_row($wpdb->prepare(
+ "SELECT * FROM {$wpdb->prefix}agentic_search_cache
+ WHERE cache_key = %s
+ AND expires_at > NOW()
+ AND (search_category = %s OR %s IS NULL)
+ ORDER BY hit_count DESC",
+ $cache_key,
+ $category,
+ $category
+ ));
+
+ if ($cached) {
+ // Update cache stats
+ $wpdb->update(
+ $wpdb->prefix . 'agentic_search_cache',
+ [
+ 'hit_count' => $cached->hit_count + 1,
+ 'cost_saved' => $cached->cost_saved + 0.009
+ ],
+ ['id' => $cached->id]
+ );
+
+ $age_seconds = strtotime('now') - strtotime($cached->cached_at);
+ return [
+ 'results_json' => json_decode($cached->results_json, true),
+ 'age' => ceil($age_seconds / 3600)
+ ];
+ }
+
+ return null;
+ }
+
+ /**
+ * Store search in database
+ */
+ private function store_search($query, $response, $cost, $options = []) {
+ global $wpdb;
+
+ $top_result = null;
+ if (!empty($response['web']['results'])) {
+ $top_result = $response['web']['results'][0];
+ }
+
+ $wpdb->insert(
+ $wpdb->prefix . 'agentic_searches',
+ [
+ 'post_id' => $options['post_id'] ?? 0,
+ 'search_query' => $query,
+ 'search_number' => $options['search_number'] ?? 1,
+ 'total_searches_for_post' => $options['total_searches'] ?? 1,
+ 'results_count' => count($response['web']['results'] ?? []),
+ 'results_json' => wp_json_encode($response),
+ 'top_result_title' => $top_result['title'] ?? null,
+ 'top_result_url' => $top_result['url'] ?? null,
+ 'cost' => $cost,
+ 'api_tier' => $this->get_tier(),
+ 'search_category' => $options['category'] ?? 'general',
+ 'status' => 'completed'
+ ]
+ );
+
+ return $wpdb->insert_id;
+ }
+
+ /**
+ * Cache search results for 30 days
+ */
+ private function cache_results($query, $response, $options = []) {
+ global $wpdb;
+
+ $cache_key = sha1(strtolower(trim($query)));
+
+ $wpdb->insert(
+ $wpdb->prefix . 'agentic_search_cache',
+ [
+ 'search_query_normalized' => strtolower(trim($query)),
+ 'search_category' => $options['category'] ?? null,
+ 'cache_key' => $cache_key,
+ 'results_json' => wp_json_encode($response),
+ 'result_count' => count($response['web']['results'] ?? []),
+ 'expires_at' => gmdate('Y-m-d H:i:s', strtotime('+30 days')),
+ 'quality_score' => 0.9 // Agent can rate later
+ ],
+ ['%s', '%s', '%s', '%s', '%d', '%s', '%f']
+ );
+ }
+
+ /**
+ * Get current API tier
+ */
+ private function get_tier() {
+ return get_option('agentic_brave_api_tier', 'base_ai');
+ }
+
+ /**
+ * Calculate cost per request
+ */
+ private function calculate_cost($tier) {
+ $tiers = [
+ 'free' => 0,
+ 'base_ai' => 0.005, // $5 per 1000
+ 'pro_ai' => 0.009 // $9 per 1000
+ ];
+
+ return $tiers[$tier] ?? 0;
+ }
+}
+```
+
+---
+
+## Flow 3: Citation Management
+
+### Agent: Extract and Number Citations
+
+```php
+ $citation_number,
+ 'source' => $source_info
+ ];
+
+ $citation_number++;
+ }
+
+ // 5. Add References section to article
+ $references_section = self::generate_references_section($citations);
+ $article_content .= $references_section;
+
+ return [
+ 'content' => $article_content,
+ 'citations' => $citations,
+ 'citation_count' => count($citations)
+ ];
+ }
+
+ /**
+ * Find source in search results by marker
+ */
+ private static function find_source_by_marker($marker, $search_results) {
+ // Examples:
+ // "n8n_official_docs" → Find URL from n8n.io/docs search
+ // "zapier_pricing" → Find from "N8n vs Zapier" search result
+
+ // Parse marker to understand what it's looking for
+ $parts = explode('_', $marker);
+ $topic = $parts[0];
+ $type = $parts[1] ?? null;
+
+ foreach ($search_results as $search) {
+ if (empty($search['results']['web']['results'])) {
+ continue;
+ }
+
+ foreach ($search['results']['web']['results'] as $result) {
+ $domain = parse_url($result['url'], PHP_URL_HOST);
+
+ // Match: does URL match the topic?
+ if (stripos($domain, $topic) !== false ||
+ stripos($result['title'], $topic) !== false) {
+
+ return [
+ 'url' => $result['url'],
+ 'title' => $result['title'],
+ 'domain' => $domain,
+ 'snippet' => $result['snippet'] ?? '',
+ 'description' => $result['description'] ?? '',
+ 'position' => array_search($result, $search['results']['web']['results'])
+ ];
+ }
+ }
+ }
+
+ return null;
+ }
+
+ /**
+ * Store citation in database
+ */
+ private static function store_citation(
+ $post_id,
+ $citation_number,
+ $source_info,
+ $source_marker
+ ) {
+ global $wpdb;
+
+ // Detect source type
+ $source_type = self::detect_source_type($source_info['domain']);
+
+ $wpdb->insert(
+ $wpdb->prefix . 'agentic_citations',
+ [
+ 'post_id' => $post_id,
+ 'citation_number' => $citation_number,
+ 'source_url' => $source_info['url'],
+ 'source_title' => $source_info['title'],
+ 'source_domain' => $source_info['domain'],
+ 'source_type' => $source_type,
+ 'result_position' => $source_info['position'],
+ 'added_by' => 'agent_automatic',
+ 'created_at' => current_time('mysql')
+ ]
+ );
+
+ return $wpdb->insert_id;
+ }
+
+ /**
+ * Generate References section
+ */
+ private static function generate_references_section($citations) {
+ $html = 'References
';
+
+ foreach ($citations as $citation) {
+ $source = $citation['source'];
+ $html .= sprintf(
+ '- %s - %s
',
+ esc_url($source['url']),
+ esc_html($source['title']),
+ esc_html($source['domain'])
+ );
+ }
+
+ $html .= '
';
+
+ return $html;
+ }
+
+ /**
+ * Classify source credibility
+ */
+ private static function detect_source_type($domain) {
+ if (stripos($domain, 'docs.') === 0 || stripos($domain, '.io') === 0) {
+ return 'official_documentation';
+ } elseif (stripos($domain, 'blog.') === 0) {
+ return 'official_blog';
+ } elseif (in_array($domain, ['medium.com', 'dev.to', 'hashnode.com'])) {
+ return 'tech_blog';
+ } elseif (in_array($domain, ['techcrunch.com', 'theverge.com', 'forbes.com'])) {
+ return 'news';
+ } elseif (stripos($domain, 'github.com') === 0) {
+ return 'github';
+ } else {
+ return 'general_web';
+ }
+ }
+}
+```
+
+---
+
+## Flow 4: Search Result Caching
+
+### Cache Strategy
+
+**Why caching is critical:**
+- A single article generation might trigger 3-5 searches
+- Multiple articles on similar topics (e.g., "Automation tools") will search same keywords
+- Brave API charges per query: **$5-9 per 1,000 queries**
+- Caching can reduce costs by 40-60%
+
+**Cache rules:**
+- Cache all successful searches for **30 days**
+- Reuse cache for identical queries (case-insensitive, trimmed)
+- Group by category (pricing, news, features) for better relevance
+- Track cache hits for analytics
+
+### Cache Implementation
+
+```php
+ 'cache',
+ 'results' => $cached,
+ 'age_days' => self::get_cache_age_days($cached)
+ ];
+ }
+
+ // Fetch fresh
+ $client = new BraveSearchClient();
+ $fresh = $client->search($query, $options);
+
+ return [
+ 'source' => 'api',
+ 'results' => $fresh
+ ];
+ }
+
+ /**
+ * Cleanup expired cache entries
+ * Run daily via cron
+ */
+ public static function cleanup_expired_cache() {
+ global $wpdb;
+
+ $deleted = $wpdb->query(
+ "DELETE FROM {$wpdb->prefix}agentic_search_cache
+ WHERE expires_at < NOW()"
+ );
+
+ error_log("Cleaned up $deleted expired search cache entries");
+ }
+
+ /**
+ * Manual cache invalidation (if search results become stale)
+ */
+ public static function invalidate_cache($query, $category = null) {
+ global $wpdb;
+
+ $cache_key = self::generate_cache_key($query, $category);
+
+ $wpdb->update(
+ $wpdb->prefix . 'agentic_search_cache',
+ ['expires_at' => current_time('mysql')], // Set to now (expired)
+ ['cache_key' => $cache_key]
+ );
+
+ return true;
+ }
+
+ private static function generate_cache_key($query, $category = null) {
+ $normalized = strtolower(trim($query));
+ return sha1($normalized . ($category ? "_$category" : ''));
+ }
+}
+
+// Schedule cache cleanup daily
+if (!wp_next_scheduled('agentic_search_cache_cleanup')) {
+ wp_schedule_event(
+ time(),
+ 'daily',
+ 'agentic_search_cache_cleanup'
+ );
+}
+
+add_action('agentic_search_cache_cleanup', [
+ 'SearchCacheManager',
+ 'cleanup_expired_cache'
+]);
+```
+
+---
+
+## Flow 5: Admin Dashboard & Analytics
+
+### Search Analytics Tab
+
+```
+Plugin Settings → Research & Citations → Search Analytics
+
+┌────────────────────────────────────────────────────────┐
+│ Search Performance & Cost Analytics │
+├────────────────────────────────────────────────────────┤
+│ │
+│ COST SUMMARY │
+│ ───────────────────────────────────────────────────── │
+│ Total searches: 156 │
+│ Cached hits: 89 (57%) │
+│ Fresh API calls: 67 (43%) │
+│ Total cost: $0.60 (would be $1.40 without cache) │
+│ Monthly budget: $50.00 │
+│ Budget used: 1.2% ✓ │
+│ │
+│ TOP SEARCHES (by frequency) │
+│ ───────────────────────────────────────────────────── │
+│ 1. "n8n automation features" → 23 hits (13 cached) │
+│ Cost: $0.09 | Last: Jan 28, 2:30 PM │
+│ │
+│ 2. "workflow automation comparison" → 18 hits (11 cache│
+│ Cost: $0.09 | Last: Jan 27, 5:15 PM │
+│ │
+│ 3. "zapier pricing 2024" → 12 hits (7 cached) │
+│ Cost: $0.05 | Last: Jan 27, 1:20 PM │
+│ │
+│ CACHE PERFORMANCE │
+│ ───────────────────────────────────────────────────── │
+│ Cache hit rate: 57% │
+│ Cache age (avg): 8 days │
+│ Cost saved by cache: $0.80 (57% reduction) │
+│ │
+│ [Clear Cache] [Invalidate > 30 days] [Download Report] │
+│ │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## REST API Endpoints
+
+### Public REST Endpoints
+
+```php
+/**
+ * POST /wp-json/agentic-writer/v1/search
+ * Perform a web search using Brave API
+ *
+ * Request:
+ * {
+ * "query": "N8n automation features",
+ * "category": "features",
+ * "count": 10,
+ * "country": "US"
+ * }
+ *
+ * Response:
+ * {
+ * "success": true,
+ * "results": [...],
+ * "from_cache": false,
+ * "cost": 0.009,
+ * "result_count": 10
+ * }
+ */
+
+register_rest_route('agentic-writer/v1', '/search', [
+ 'methods' => 'POST',
+ 'callback' => 'agentic_writer_rest_search',
+ 'permission_callback' => 'is_user_logged_in',
+ 'args' => [
+ 'query' => ['required' => true, 'type' => 'string'],
+ 'category' => ['type' => 'string'],
+ 'count' => ['type' => 'integer', 'default' => 10]
+ ]
+]);
+
+function agentic_writer_rest_search($request) {
+ $query = $request->get_param('query');
+ $client = new BraveSearchClient();
+
+ return $client->search($query, [
+ 'category' => $request->get_param('category'),
+ 'count' => $request->get_param('count'),
+ 'post_id' => $request->get_param('post_id')
+ ]);
+}
+
+/**
+ * GET /wp-json/agentic-writer/v1/searches?post_id=123
+ * List all searches for a post with citations
+ */
+
+register_rest_route('agentic-writer/v1', '/searches', [
+ 'methods' => 'GET',
+ 'callback' => 'agentic_writer_rest_list_searches',
+ 'permission_callback' => 'is_user_logged_in',
+ 'args' => ['post_id' => ['required' => true, 'type' => 'integer']]
+]);
+
+function agentic_writer_rest_list_searches($request) {
+ global $wpdb;
+
+ $post_id = $request->get_param('post_id');
+
+ if (!current_user_can('edit_post', $post_id)) {
+ return new WP_Error('unauthorized', 'Not allowed', ['status' => 403]);
+ }
+
+ $searches = $wpdb->get_results($wpdb->prepare(
+ "SELECT * FROM {$wpdb->prefix}agentic_searches
+ WHERE post_id = %d
+ ORDER BY created_at DESC",
+ $post_id
+ ));
+
+ $citations = $wpdb->get_results($wpdb->prepare(
+ "SELECT * FROM {$wpdb->prefix}agentic_citations
+ WHERE post_id = %d
+ ORDER BY citation_number ASC",
+ $post_id
+ ));
+
+ return [
+ 'searches' => $searches,
+ 'citations' => $citations,
+ 'total_cost' => array_sum(array_map(function($s) {
+ return floatval($s->cost);
+ }, $searches))
+ ];
+}
+```
+
+---
+
+## Configuration & Settings
+
+### Settings Panel Integration
+
+Add new tab to WP Agentic Writer settings:
+
+```php
+'brave_search_settings' => [
+ 'brave_api_key' => '', // Required
+ 'brave_api_tier' => 'base_ai', // free, base_ai, pro_ai
+ 'brave_search_enabled' => true, // Toggle feature on/off
+ 'enable_search_caching' => true, // Cache results
+ 'cache_duration_days' => 30, // How long to keep cache
+ 'auto_search_enabled' => true, // Auto-search during generation
+ 'search_count_per_article' => 3, // How many searches per article
+ 'include_citations' => true, // Add [1], [2]... to article
+ 'include_references_section' => true, // Add References section
+ 'monthly_budget_limit' => 50.00, // Dollar limit per month
+ 'budget_alert_threshold' => 75, // Alert at 75% of budget
+ 'auto_invalidate_cache_older_than_days' => 45, // Auto-cleanup old cache
+ 'search_result_quality_threshold' => 0.6, // Minimum relevance score
+]
+```
+
+---
+
+## Cost Optimization & Budget Management
+
+### Real-time Cost Tracking
+
+```php
+= floatval(get_option('agentic_brave_budget_alert', 75))) {
+ do_action('agentic_brave_budget_alert', [
+ 'monthly_cost' => $new_cost,
+ 'budget_limit' => $budget_limit,
+ 'percentage' => $percentage
+ ]);
+ }
+
+ // Block searches if over budget
+ if ($new_cost >= $budget_limit) {
+ return new WP_Error(
+ 'budget_exceeded',
+ sprintf(
+ 'Monthly budget of $%.2f exceeded (current: $%.2f)',
+ $budget_limit,
+ $new_cost
+ )
+ );
+ }
+
+ return true;
+ }
+
+ /**
+ * Get current month's total cost
+ */
+ private static function get_monthly_cost() {
+ global $wpdb;
+
+ $result = $wpdb->get_var(
+ "SELECT COALESCE(SUM(cost), 0) FROM {$wpdb->prefix}agentic_searches
+ WHERE MONTH(created_at) = MONTH(NOW())
+ AND YEAR(created_at) = YEAR(NOW())"
+ );
+
+ return floatval($result);
+ }
+
+ /**
+ * Generate cost report
+ */
+ public static function get_cost_report() {
+ global $wpdb;
+
+ return [
+ 'today' => self::get_period_cost('today'),
+ 'week' => self::get_period_cost('week'),
+ 'month' => self::get_period_cost('month'),
+ 'all_time' => self::get_all_time_cost(),
+ 'top_searches' => self::get_top_searches_by_cost(),
+ 'cache_savings' => self::get_cache_savings()
+ ];
+ }
+
+ /**
+ * Calculate how much cache saved
+ */
+ private static function get_cache_savings() {
+ global $wpdb;
+
+ return $wpdb->get_var(
+ "SELECT COALESCE(SUM(cost_saved), 0) FROM {$wpdb->prefix}agentic_search_cache"
+ );
+ }
+}
+
+// Hook for budget alerts
+add_action('agentic_brave_budget_alert', function($data) {
+ // Send admin email
+ wp_mail(
+ get_option('admin_email'),
+ 'WP Agentic Writer: Budget Alert',
+ sprintf(
+ "Brave Search API budget is at %.0f%% ($%.2f / $%.2f)\n\nGo to Settings to adjust limits.",
+ $data['percentage'],
+ $data['monthly_cost'],
+ $data['budget_limit']
+ )
+ );
+});
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Core Integration (Week 1-2)
+- [ ] Create database tables: `wp_agentic_searches`, `wp_agentic_citations`, `wp_agentic_search_cache`
+- [ ] Build BraveSearchClient class with API authentication
+- [ ] Implement basic search → cache → cost tracking flow
+- [ ] Create REST endpoint: POST `/search`
+- [ ] Add settings panel for API key & tier selection
+- [ ] Test with sample searches
+
+### Phase 2: Agent Integration (Week 2-3)
+- [ ] Build ResearchPlanner (automatic search strategy)
+- [ ] Integrate searches into article generation workflow
+- [ ] Build CitationManager (extract, number, reference)
+- [ ] Add citations to generated articles ([1], [2]... References)
+- [ ] Test end-to-end: Topic → Searches → Article with Citations
+
+### Phase 3: Caching & Optimization (Week 3-4)
+- [ ] Implement SearchCacheManager with 30-day expiry
+- [ ] Add cache hit tracking & cost savings calculation
+- [ ] Build cache cleanup cron job
+- [ ] Implement cache invalidation endpoint
+- [ ] Test cache reuse scenarios
+
+### Phase 4: Admin & Analytics (Week 4-5)
+- [ ] Build admin dashboard with Search Analytics tab
+- [ ] Add cost tracking & monthly budget management
+- [ ] Create search performance reports
+- [ ] Add budget alert system (email)
+- [ ] Build cache management UI (view, invalidate, cleanup)
+
+### Phase 5: Security & Polish (Week 5)
+- [ ] Add rate limiting per user
+- [ ] Sanitize search queries
+- [ ] Add audit logging (who searched what, when)
+- [ ] Implement permission checks
+- [ ] Add error handling for API failures
+- [ ] Test with high volume searches
+
+---
+
+## Next Steps
+
+1. Set up Brave Search API account (free tier first)
+2. Create database migrations for the three new tables
+3. Begin Phase 1 implementation (BraveSearchClient)
+4. Test API connectivity and response parsing
+5. Move to Phase 2 once API is reliable
diff --git a/downloads/.gitignore b/downloads/.gitignore
new file mode 100644
index 0000000..7ffb7c3
--- /dev/null
+++ b/downloads/.gitignore
@@ -0,0 +1,7 @@
+# Ignore node_modules in local backend package
+agentic-writer-local-backend/node_modules/
+agentic-writer-local-backend/proxy.log
+agentic-writer-local-backend/proxy.pid
+
+# Keep the distributable ZIP
+!agentic-writer-local-backend.zip
diff --git a/downloads/agentic-writer-local-backend.zip b/downloads/agentic-writer-local-backend.zip
new file mode 100644
index 0000000..62f40a3
Binary files /dev/null and b/downloads/agentic-writer-local-backend.zip differ
diff --git a/downloads/agentic-writer-local-backend/README.md b/downloads/agentic-writer-local-backend/README.md
new file mode 100644
index 0000000..67f122d
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/README.md
@@ -0,0 +1,170 @@
+# Agentic Writer Local Backend
+
+Run unlimited AI content generation on your own machine using your Claude CLI + Z.ai/Anthropic account.
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- ✅ **Claude CLI** installed and configured
+ - Get it: [https://claude.ai/code](https://claude.ai/code) or [https://z.ai](https://z.ai)
+ - Verify: `claude --version` or `which claude`
+- ✅ **Node.js 18+** installed
+ - Download: [https://nodejs.org](https://nodejs.org)
+ - Verify: `node --version`
+- ✅ **Z.ai Coding Plan** or **Anthropic API key** configured in Claude CLI
+
+## Quick Start
+
+### 1. Extract Package
+
+```bash
+unzip agentic-writer-local-backend.zip
+cd agentic-writer-local-backend
+```
+
+### 2. Start the Proxy
+
+```bash
+chmod +x *.sh
+./start-proxy.sh
+```
+
+You'll see:
+
+```
+═══════════════════════════════════════════════════
+✅ Local Backend Running!
+═══════════════════════════════════════════════════
+
+Your Configuration:
+ Base URL: http://192.168.1.105:8080
+ API Key: dummy
+ Model: claude-local
+```
+
+### 3. Configure WordPress Plugin
+
+1. Open **WP Admin** → **Agentic Writer** → **Settings** → **Local Backend**
+2. Paste the **Base URL** shown above
+3. API Key: `dummy`
+4. Click **Test Connection** → should show ✅
+5. Start generating content!
+
+## Commands
+
+```bash
+./start-proxy.sh # Start proxy (runs in background)
+./stop-proxy.sh # Stop proxy
+./test-connection.sh # Test if proxy responds
+./get-local-ip.sh # Find your local IP address
+tail -f proxy.log # View real-time logs
+```
+
+## Firewall Setup
+
+The proxy needs to accept connections from your WordPress site.
+
+### macOS
+
+1. **System Settings** → **Network** → **Firewall**
+2. Click **Options** → **Add** → Select `node`
+3. Set to **Allow incoming connections**
+
+### Linux (ufw)
+
+```bash
+sudo ufw allow 8080/tcp
+sudo ufw reload
+```
+
+### Windows
+
+1. **Windows Defender Firewall** → **Advanced Settings**
+2. **Inbound Rules** → **New Rule**
+3. **Port** → TCP **8080** → **Allow**
+
+## How It Works
+
+```
+WordPress Plugin → HTTP POST → Local Proxy (port 8080)
+ ↓
+ Spawns Claude CLI
+ ↓
+ Returns AI Response
+```
+
+**Benefits:**
+- 🆓 **Free**: Uses your existing Z.ai/Anthropic subscription
+- 🔒 **Private**: Content never leaves your network
+- ⚡ **Fast**: LAN latency (~50-200ms)
+- 🚀 **Unlimited**: No rate limits, no token counting
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions.
+
+### Quick Fixes
+
+**"Connection failed" in plugin:**
+```bash
+# Check proxy is running
+ps aux | grep claude-proxy
+
+# Restart if needed
+./stop-proxy.sh && ./start-proxy.sh
+```
+
+**"Claude CLI not found":**
+```bash
+# Verify Claude is installed
+which claude
+claude --version
+
+# Test Claude works
+echo "Hello" | claude
+```
+
+**"Wrong IP address":**
+```bash
+# Find your correct IP
+./get-local-ip.sh
+
+# Or manually:
+# macOS: ipconfig getifaddr en0
+# Linux: ip route get 1 | awk '{print $7}'
+```
+
+**Port 8080 already in use:**
+```bash
+# Find what's using it
+lsof -i :8080
+
+# Change port (edit claude-proxy.js)
+PORT=9000 node claude-proxy.js
+# Update plugin Base URL to: http://your-ip:9000
+```
+
+## Security Notes
+
+- Proxy binds to `0.0.0.0` (all network interfaces) for LAN access
+- No authentication by design (LAN trust model)
+- All request prompts are logged to `proxy.log`
+- For internet exposure, use ngrok/reverse proxy with authentication
+
+## Environment Variables
+
+```bash
+PORT=9000 ./start-proxy.sh # Use different port
+NODE_ENV=production # Production mode
+```
+
+## Support
+
+- **Documentation**: [Plugin Docs](https://github.com/your/plugin)
+- **Issues**: [GitHub Issues](https://github.com/your/plugin/issues)
+- **Community**: [Discord](https://discord.gg/your-server)
+
+## License
+
+GPL-2.0+ - Same as WP Agentic Writer plugin
diff --git a/downloads/agentic-writer-local-backend/TROUBLESHOOTING.md b/downloads/agentic-writer-local-backend/TROUBLESHOOTING.md
new file mode 100644
index 0000000..41e822d
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/TROUBLESHOOTING.md
@@ -0,0 +1,339 @@
+# Troubleshooting Guide
+
+Common issues and solutions for Agentic Writer Local Backend.
+
+## Connection Issues
+
+### "Connection timeout" in Plugin
+
+**Symptoms:**
+- Plugin shows "Connection timeout" error
+- Test connection fails
+
+**Solutions:**
+
+1. **Check proxy is running:**
+ ```bash
+ ps aux | grep claude-proxy
+ ```
+
+2. **Restart proxy:**
+ ```bash
+ ./stop-proxy.sh
+ ./start-proxy.sh
+ ```
+
+3. **Check logs:**
+ ```bash
+ tail -f proxy.log
+ ```
+
+4. **Verify IP address:**
+ ```bash
+ ./get-local-ip.sh
+ ```
+
+### "Connection refused"
+
+**Cause:** Proxy not running or wrong IP
+
+**Solutions:**
+
+1. **Start proxy:**
+ ```bash
+ ./start-proxy.sh
+ ```
+
+2. **Check firewall:**
+ - macOS: System Settings → Network → Firewall → Allow Node.js
+ - Linux: `sudo ufw allow 8080/tcp`
+ - Windows: Defender Firewall → Allow port 8080
+
+3. **Test locally first:**
+ ```bash
+ curl http://localhost:8080/ping
+ # Should return: pong
+ ```
+
+## Claude CLI Issues
+
+### "Claude CLI not found"
+
+**Verify installation:**
+```bash
+which claude
+# macOS: /opt/homebrew/bin/claude or /usr/local/bin/claude
+# Linux: ~/.local/bin/claude or /usr/bin/claude
+```
+
+**Fix PATH:**
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export PATH="/opt/homebrew/bin:$PATH"
+source ~/.zshrc
+```
+
+**Reinstall Claude CLI:**
+- Visit: [https://claude.ai/code](https://claude.ai/code)
+- Follow installation instructions
+
+### "No response from Claude"
+
+**Test Claude manually:**
+```bash
+echo "Hello, reply with: Test successful" | claude
+```
+
+**Check authentication:**
+```bash
+claude --version
+# Should show version and auth status
+```
+
+**Reconfigure Claude:**
+- Check Z.ai account: [https://z.ai](https://z.ai)
+- Or Anthropic API key setup
+
+## Network Issues
+
+### Wrong IP Address Detected
+
+**Find correct IP:**
+```bash
+# macOS
+ipconfig getifaddr en0 # WiFi
+ipconfig getifaddr en1 # Ethernet
+
+# Linux
+ip route get 1 | awk '{print $7}'
+hostname -I
+
+# Windows
+ipconfig
+# Look for "IPv4 Address" under active adapter
+```
+
+**Update plugin settings:**
+- Use the correct IP in Base URL: `http://CORRECT-IP:8080`
+
+### Port 8080 Already in Use
+
+**Find what's using it:**
+```bash
+lsof -i :8080
+# or
+netstat -anp | grep 8080
+```
+
+**Change port:**
+
+1. Edit `claude-proxy.js`:
+ ```javascript
+ const PORT = process.env.PORT || 9000; // Change 8080 to 9000
+ ```
+
+2. Restart proxy:
+ ```bash
+ ./stop-proxy.sh
+ PORT=9000 ./start-proxy.sh
+ ```
+
+3. Update plugin Base URL: `http://your-ip:9000`
+
+## Performance Issues
+
+### Slow Response Times
+
+**Normal latency:**
+- Local network: 50-200ms
+- Claude CLI processing: 2-30 seconds depending on prompt
+
+**If consistently slow:**
+
+1. **Check network:**
+ ```bash
+ ping 192.168.1.105 # Your proxy IP
+ ```
+
+2. **Monitor logs:**
+ ```bash
+ tail -f proxy.log
+ ```
+
+3. **Check machine resources:**
+ - CPU usage: Claude CLI is CPU-intensive
+ - Memory: Ensure sufficient RAM available
+
+### Proxy Crashes
+
+**Check logs:**
+```bash
+cat proxy.log | tail -50
+```
+
+**Common causes:**
+- Out of memory: Close other applications
+- Claude CLI timeout: Increase timeout in `claude-proxy.js`
+- Malformed requests: Check plugin version compatibility
+
+**Restart with clean state:**
+```bash
+./stop-proxy.sh
+rm proxy.log
+./start-proxy.sh
+```
+
+## Plugin Integration Issues
+
+### "Invalid response format"
+
+**Cause:** Claude response doesn't match expected JSON format
+
+**Debug:**
+1. Check `proxy.log` for actual Claude output
+2. Test manually:
+ ```bash
+ curl -X POST http://localhost:8080/v1/messages \
+ -H "Content-Type: application/json" \
+ -d '{"messages":[{"role":"user","content":"Hello"}]}'
+ ```
+
+3. Update Claude CLI if outdated:
+ ```bash
+ claude --version
+ # Upgrade if needed
+ ```
+
+### Cost Tracking Shows $0
+
+**Expected behavior:** Local backend is free, plugin should show `$0.00 (Local)`
+
+**If concerned:**
+- This is correct - local backend has no API costs
+- Dashboard should show "X requests local (free)"
+
+## Advanced Troubleshooting
+
+### Enable Debug Logging
+
+Edit `claude-proxy.js`:
+```javascript
+const DEBUG = true; // Add at top of file
+
+// In /v1/messages handler:
+if (DEBUG) {
+ console.log('Full request:', JSON.stringify(req.body, null, 2));
+ console.log('Full response:', output);
+}
+```
+
+### Test with curl
+
+**Ping:**
+```bash
+curl http://localhost:8080/ping
+# Expected: pong
+```
+
+**Inference:**
+```bash
+curl -X POST http://localhost:8080/v1/messages \
+ -H "Content-Type: application/json" \
+ -d '{
+ "messages": [
+ {"role": "user", "content": "Reply with: Test successful"}
+ ]
+ }'
+```
+
+**Expected response:**
+```json
+{
+ "id": "local-1234567890",
+ "object": "chat.completion",
+ "model": "claude-local",
+ "choices": [{
+ "message": {
+ "content": "Test successful"
+ }
+ }]
+}
+```
+
+### Permissions Issues (macOS)
+
+**Make scripts executable:**
+```bash
+chmod +x start-proxy.sh stop-proxy.sh test-connection.sh get-local-ip.sh
+```
+
+**If "permission denied":**
+```bash
+# Check file permissions
+ls -la *.sh
+
+# Reset if needed
+chmod 755 *.sh
+```
+
+## Still Having Issues?
+
+1. **Check system requirements:**
+ - Node.js 18+: `node --version`
+ - Claude CLI installed: `which claude`
+ - Sufficient disk space: `df -h`
+
+2. **Collect diagnostic info:**
+ ```bash
+ echo "Node version:" $(node --version)
+ echo "Claude path:" $(which claude)
+ echo "Local IP:" $(./get-local-ip.sh)
+ echo "Proxy status:" $(ps aux | grep claude-proxy)
+ tail -20 proxy.log
+ ```
+
+3. **Reset everything:**
+ ```bash
+ ./stop-proxy.sh
+ rm -rf node_modules proxy.log proxy.pid
+ npm install
+ ./start-proxy.sh
+ ```
+
+4. **Get help:**
+ - GitHub Issues: [Report Bug](https://github.com/your/plugin/issues)
+ - Discord Community: [Join Chat](https://discord.gg/your-server)
+ - Include: OS, Node version, Claude CLI version, error logs
+
+## Environment-Specific Notes
+
+### macOS
+
+- Default Claude path: `/opt/homebrew/bin/claude`
+- Firewall: System Settings → Network → Firewall
+- IP detection: `ipconfig getifaddr en0`
+
+### Linux
+
+- Default Claude path: `~/.local/bin/claude`
+- Firewall: `sudo ufw allow 8080/tcp`
+- IP detection: `ip route get 1 | awk '{print $7}'`
+
+### Windows
+
+- Claude path varies, check `where claude`
+- Firewall: Windows Defender → Allow port 8080
+- IP detection: `ipconfig` (look for IPv4)
+- Scripts: Use Git Bash or WSL to run `.sh` scripts
+
+## Security Best Practices
+
+1. **LAN only:** Don't expose proxy to internet without authentication
+2. **Firewall:** Restrict to specific IPs if on shared network
+3. **Logs:** `proxy.log` contains all prompts - review periodically
+4. **Updates:** Keep Node.js and Claude CLI updated
+
+---
+
+**Last Updated:** 2025-02-27
+**Version:** 1.0.0
diff --git a/downloads/agentic-writer-local-backend/claude-proxy.js b/downloads/agentic-writer-local-backend/claude-proxy.js
new file mode 100644
index 0000000..0c7ff37
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/claude-proxy.js
@@ -0,0 +1,122 @@
+const express = require('express');
+const { spawn } = require('child_process');
+const app = express();
+
+app.use(express.json());
+
+// Health check endpoint
+app.get('/ping', (req, res) => {
+ res.send('pong');
+});
+
+// Main inference endpoint (OpenAI-compatible format)
+app.post('/v1/messages', async (req, res) => {
+ const { messages } = req.body;
+
+ if (!messages || !Array.isArray(messages) || messages.length === 0) {
+ return res.status(400).json({
+ error: {
+ message: 'Invalid request: messages array required'
+ }
+ });
+ }
+
+ // Extract the last user message as the prompt
+ const lastMessage = messages[messages.length - 1];
+ const prompt = lastMessage.content;
+
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+ console.log('Request from:', req.ip);
+ console.log('Prompt length:', prompt.length, 'chars');
+ console.log('Prompt preview:', prompt.substring(0, 150) + '...');
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+ // Spawn Claude CLI process
+ const claude = spawn('claude', [], {
+ stdio: ['pipe', 'pipe', 'pipe']
+ });
+
+ let output = '';
+ let errorOutput = '';
+
+ claude.stdout.on('data', (data) => {
+ output += data.toString();
+ process.stdout.write('.');
+ });
+
+ claude.stderr.on('data', (data) => {
+ errorOutput += data.toString();
+ console.error('Claude stderr:', data.toString());
+ });
+
+ claude.on('close', (code) => {
+ console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+ console.log('Claude exit code:', code);
+ console.log('Response length:', output.length, 'chars');
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+ if (code !== 0 || !output.trim()) {
+ return res.status(500).json({
+ error: {
+ message: 'Claude CLI error',
+ details: errorOutput || 'No response from Claude'
+ }
+ });
+ }
+
+ // Return OpenAI-compatible response format
+ res.json({
+ id: 'local-' + Date.now(),
+ object: 'chat.completion',
+ created: Math.floor(Date.now() / 1000),
+ model: 'claude-local',
+ choices: [{
+ index: 0,
+ message: {
+ role: 'assistant',
+ content: output.trim()
+ },
+ finish_reason: 'stop'
+ }],
+ usage: {
+ prompt_tokens: 0,
+ completion_tokens: 0,
+ total_tokens: 0
+ }
+ });
+ });
+
+ claude.on('error', (err) => {
+ console.error('Failed to spawn Claude CLI:', err);
+ res.status(500).json({
+ error: {
+ message: 'Failed to spawn Claude CLI',
+ details: err.message
+ }
+ });
+ });
+
+ // Send prompt to Claude after brief pause
+ setTimeout(() => {
+ claude.stdin.write(prompt + '\n');
+ claude.stdin.end();
+ }, 100);
+});
+
+const PORT = process.env.PORT || 8080;
+app.listen(PORT, '0.0.0.0', () => {
+ console.log('═══════════════════════════════════════════════════');
+ console.log('🚀 Agentic Writer Local Backend Started!');
+ console.log('═══════════════════════════════════════════════════');
+ console.log(`Local: http://localhost:${PORT}`);
+ console.log(`Network: http://YOUR-IP:${PORT}`);
+ console.log('');
+ console.log('Plugin Configuration:');
+ console.log(` Base URL: http://YOUR-IP:${PORT}`);
+ console.log(` API Key: dummy`);
+ console.log(` Model: claude-local`);
+ console.log('');
+ console.log('Health check: GET /ping');
+ console.log('Inference: POST /v1/messages');
+ console.log('═══════════════════════════════════════════════════');
+});
diff --git a/downloads/agentic-writer-local-backend/get-local-ip.sh b/downloads/agentic-writer-local-backend/get-local-ip.sh
new file mode 100644
index 0000000..62b3c08
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/get-local-ip.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+
+echo "Detecting your local IP address..."
+echo ""
+
+# Detect local IP based on OS
+if [[ "$OSTYPE" == "darwin"* ]]; then
+ # macOS - try en0 (WiFi) then en1 (Ethernet)
+ IP=$(ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null || echo "")
+ INTERFACE=$(ifconfig en0 &>/dev/null && echo "en0 (WiFi)" || echo "en1 (Ethernet)")
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+ # Linux
+ IP=$(ip route get 1 | awk '{print $7;exit}' 2>/dev/null || hostname -I | awk '{print $1}')
+ INTERFACE="default"
+else
+ # Windows or unknown
+ IP=$(hostname -I 2>/dev/null | awk '{print $1}' || echo "")
+ INTERFACE="unknown"
+fi
+
+if [ -z "$IP" ]; then
+ echo "❌ Could not detect IP address automatically"
+ echo ""
+ echo "Manual detection:"
+ echo " macOS: ipconfig getifaddr en0"
+ echo " Linux: ip route get 1 | awk '{print \$7}'"
+ echo " Windows: ipconfig (look for IPv4 Address)"
+ exit 1
+fi
+
+echo "✅ Your local IP: $IP ($INTERFACE)"
+echo ""
+echo "Use this in your plugin settings:"
+echo " Base URL: http://$IP:8080"
diff --git a/downloads/agentic-writer-local-backend/package.json b/downloads/agentic-writer-local-backend/package.json
new file mode 100644
index 0000000..af80dad
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "agentic-writer-local-backend",
+ "version": "1.0.0",
+ "description": "Local backend proxy for WP Agentic Writer using Claude CLI",
+ "main": "claude-proxy.js",
+ "scripts": {
+ "start": "node claude-proxy.js",
+ "test": "curl http://localhost:8080/ping"
+ },
+ "keywords": [
+ "wordpress",
+ "ai",
+ "claude",
+ "proxy"
+ ],
+ "author": "WP Agentic Writer",
+ "license": "GPL-2.0+",
+ "dependencies": {
+ "express": "^4.18.2"
+ }
+}
diff --git a/downloads/agentic-writer-local-backend/start-proxy.sh b/downloads/agentic-writer-local-backend/start-proxy.sh
new file mode 100644
index 0000000..b4fc7e0
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/start-proxy.sh
@@ -0,0 +1,77 @@
+#!/bin/bash
+
+echo "🚀 Starting Agentic Writer Local Backend..."
+echo ""
+
+# Check dependencies
+if ! command -v node &> /dev/null; then
+ echo "❌ Node.js not found. Install from https://nodejs.org/"
+ exit 1
+fi
+
+if ! command -v claude &> /dev/null; then
+ echo "❌ Claude CLI not found. Install and configure first."
+ echo " Check: https://claude.ai/code or https://z.ai"
+ exit 1
+fi
+
+# Auto-install express if needed
+if [ ! -d "node_modules" ]; then
+ echo "📦 Installing dependencies..."
+ npm install
+fi
+
+# Detect local IP
+if [[ "$OSTYPE" == "darwin"* ]]; then
+ # macOS
+ LOCAL_IP=$(ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null || echo "127.0.0.1")
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+ # Linux
+ LOCAL_IP=$(ip route get 1 | awk '{print $7;exit}' 2>/dev/null || echo "127.0.0.1")
+else
+ # Windows/other
+ LOCAL_IP="127.0.0.1"
+fi
+
+echo "✅ Dependencies OK"
+echo "✅ Claude CLI found: $(which claude)"
+echo ""
+echo "Starting proxy server..."
+echo ""
+
+# Start server in background
+nohup node claude-proxy.js > proxy.log 2>&1 &
+PID=$!
+echo $PID > proxy.pid
+
+# Wait for server to boot
+sleep 2
+
+# Test if running
+if kill -0 $PID 2>/dev/null; then
+ echo "═══════════════════════════════════════════════════"
+ echo "✅ Local Backend Running!"
+ echo "═══════════════════════════════════════════════════"
+ echo ""
+ echo "Your Configuration:"
+ echo " Base URL: http://$LOCAL_IP:8080"
+ echo " API Key: dummy"
+ echo " Model: claude-local"
+ echo ""
+ echo "Next Steps:"
+ echo " 1. Open your WordPress Admin"
+ echo " 2. Go to Agentic Writer → Settings → Local Backend"
+ echo " 3. Paste the Base URL above"
+ echo " 4. Click 'Test Connection'"
+ echo ""
+ echo "Commands:"
+ echo " Logs: tail -f proxy.log"
+ echo " Stop: ./stop-proxy.sh"
+ echo " Test: ./test-connection.sh"
+ echo "═══════════════════════════════════════════════════"
+else
+ echo "❌ Failed to start. Check proxy.log for errors."
+ cat proxy.log
+ rm -f proxy.pid
+ exit 1
+fi
diff --git a/downloads/agentic-writer-local-backend/stop-proxy.sh b/downloads/agentic-writer-local-backend/stop-proxy.sh
new file mode 100644
index 0000000..2327056
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/stop-proxy.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+
+if [ -f proxy.pid ]; then
+ PID=$(cat proxy.pid)
+ if kill -0 $PID 2>/dev/null; then
+ kill $PID
+ rm proxy.pid
+ echo "🛑 Local Backend stopped (PID: $PID)"
+ else
+ echo "⚠️ No process found with PID: $PID"
+ rm proxy.pid
+ fi
+else
+ # Fallback: kill by process name
+ pkill -f claude-proxy.js
+ if [ $? -eq 0 ]; then
+ echo "🛑 Stopped all claude-proxy processes"
+ else
+ echo "ℹ️ No claude-proxy processes running"
+ fi
+fi
diff --git a/downloads/agentic-writer-local-backend/test-connection.sh b/downloads/agentic-writer-local-backend/test-connection.sh
new file mode 100644
index 0000000..cf51782
--- /dev/null
+++ b/downloads/agentic-writer-local-backend/test-connection.sh
@@ -0,0 +1,42 @@
+#!/bin/bash
+
+echo "Testing local backend connection..."
+echo ""
+
+# Test /ping endpoint
+echo "1. Testing health check..."
+PING_RESPONSE=$(curl -s http://localhost:8080/ping 2>&1)
+
+if [ "$PING_RESPONSE" = "pong" ]; then
+ echo " ✅ Health check passed"
+else
+ echo " ❌ Health check failed"
+ echo " Response: $PING_RESPONSE"
+ echo ""
+ echo "Is the proxy running? Check: ps aux | grep claude-proxy"
+ exit 1
+fi
+
+# Test /v1/messages endpoint
+echo "2. Testing inference..."
+RESPONSE=$(curl -s -X POST http://localhost:8080/v1/messages \
+ -H "Content-Type: application/json" \
+ -d '{"messages":[{"role":"user","content":"Reply with exactly: Test successful"}]}' 2>&1)
+
+echo " Response: $RESPONSE"
+
+if echo "$RESPONSE" | grep -q "choices"; then
+ echo " ✅ Inference endpoint working"
+ echo ""
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+ echo "✅ Local Backend is working correctly!"
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+else
+ echo " ❌ Inference test failed"
+ echo ""
+ echo "Troubleshooting:"
+ echo " 1. Check Claude CLI: echo 'test' | claude"
+ echo " 2. Check logs: tail -f proxy.log"
+ echo " 3. Restart proxy: ./stop-proxy.sh && ./start-proxy.sh"
+ exit 1
+fi
diff --git a/hybrid-local-cloud-ai-provider-b09890.md b/hybrid-local-cloud-ai-provider-b09890.md
new file mode 100644
index 0000000..a76f294
--- /dev/null
+++ b/hybrid-local-cloud-ai-provider-b09890.md
@@ -0,0 +1,556 @@
+# Local Backend + Codex Provider System with Cloud Fallback
+
+Implement a provider system allowing text generation via Local Backend (Claude CLI proxy) and Codex API, while keeping image generation on OpenRouter's cloud API.
+
+## Architecture Overview (Based on local-backend-feature.md)
+
+**Current State:**
+- Plugin uses `WP_Agentic_Writer_OpenRouter_Provider` for all AI tasks
+- All requests go to cloud APIs (OpenRouter)
+- Costs per token, rate limits apply
+- 23+ files directly call provider singleton
+
+**New State:**
+- **Local Backend**: User runs Node.js proxy on their machine (Claude CLI)
+- **Codex Provider**: Direct integration with OpenAI Codex API
+- **OpenRouter**: Fallback + image generation only
+- **Provider Manager**: Routes tasks to appropriate provider
+
+**Flow:**
+```
+WordPress Plugin → Provider Manager → Local Backend (http://user-ip:8080)
+ → Codex API (https://api.openai.com)
+ → OpenRouter (images + fallback)
+```
+
+## Provider Architecture
+
+### 1. Provider Interface (Common Contract)
+
+```php
+interface WP_Agentic_Writer_AI_Provider_Interface {
+ public function chat($messages, $options, $type);
+ public function chat_stream($messages, $options, $type, $callback);
+ public function generate_image($prompt, $model, $options);
+ public function is_configured();
+ public function test_connection();
+ public function supports_task_type($type);
+}
+```
+
+### 2. Provider Manager (Router)
+
+```php
+class WP_Agentic_Writer_Provider_Manager {
+ public static function get_provider_for_task($type) {
+ $settings = get_option('wp_agentic_writer_settings');
+ $task_providers = $settings['task_providers'] ?? [];
+
+ $provider_name = $task_providers[$type] ?? 'openrouter';
+
+ switch ($provider_name) {
+ case 'local_backend':
+ return new WP_Agentic_Writer_Local_Backend_Provider();
+ case 'codex':
+ return new WP_Agentic_Writer_Codex_Provider();
+ case 'openrouter':
+ default:
+ return WP_Agentic_Writer_OpenRouter_Provider::get_instance();
+ }
+ }
+}
+```
+
+### 3. Provider Implementations
+
+**A. Local Backend Provider** (Primary for text tasks)
+- **File**: `includes/class-local-backend-provider.php`
+- **Endpoint**: `http://192.168.x.x:8080` (user's machine)
+- **Protocol**: HTTP POST to `/v1/messages` (OpenAI-compatible)
+- **Backend**: Node.js proxy → Claude CLI
+- **Supports**: `chat`, `clarity`, `planning`, `writing`, `refinement`
+- **Cost**: $0 (uses user's Claude CLI + Z.ai/Anthropic)
+
+**B. Codex Provider** (Alternative text provider)
+- **File**: `includes/class-codex-provider.php`
+- **Endpoint**: `https://api.openai.com/v1/chat/completions`
+- **Protocol**: Standard OpenAI API
+- **Supports**: `chat`, `clarity`, `planning`, `writing`, `refinement`
+- **Cost**: Per OpenAI pricing
+
+**C. OpenRouter Provider** (Existing, for images + fallback)
+- **File**: `includes/class-openrouter-provider.php` (existing)
+- **Endpoint**: `https://openrouter.ai/api/v1/chat/completions`
+- **Supports**: ALL task types (fallback when local unavailable)
+- **Primary use**: `image` generation only in hybrid mode
+
+### Configuration Strategy
+
+#### Settings Structure
+
+```php
+'wp_agentic_writer_settings' => [
+ // Provider routing
+ 'provider_mode' => 'hybrid', // 'cloud', 'local', 'hybrid'
+ 'task_providers' => [
+ 'chat' => 'local_backend',
+ 'clarity' => 'local_backend',
+ 'planning' => 'local_backend',
+ 'writing' => 'local_backend',
+ 'refinement' => 'codex', // Or local_backend
+ 'image' => 'openrouter' // Always OpenRouter
+ ],
+
+ // Local Backend settings
+ 'local_backend_url' => 'http://192.168.1.105:8080',
+ 'local_backend_key' => 'dummy',
+ 'local_backend_model' => 'claude-via-cli',
+ 'local_backend_enabled' => true,
+
+ // Codex settings
+ 'codex_api_key' => 'sk-...',
+ 'codex_model' => 'gpt-4',
+ 'codex_enabled' => true,
+
+ // OpenRouter (existing)
+ 'openrouter_api_key' => 'sk-or-...',
+ 'image_model' => 'black-forest-labs/flux-1.1-pro',
+]
+```
+
+#### Recommended Configuration
+
+**Optimal Hybrid Setup:**
+```
+chat → Local Backend (free, private, fast)
+clarity → Local Backend (free, fast)
+planning → Local Backend (free, fast)
+writing → Local Backend (free, unlimited)
+refinement → Codex (cloud quality when needed)
+image → OpenRouter (only option for FLUX/Recraft)
+```
+
+**Benefits:**
+- 80%+ requests via Local Backend = $0 cost
+- Privacy for all text content
+- Codex as quality alternative
+- Images via best models (OpenRouter)
+
+## Implementation Components
+
+### 1. Local Backend Package (Separate Distribution)
+
+**Package:** `agentic-writer-local-backend.zip`
+
+**Contents:**
+```
+agentic-writer-local-backend/
+├── claude-proxy.js # Node.js HTTP server
+├── start-proxy.sh # Launch with IP detection
+├── stop-proxy.sh # Clean shutdown
+├── test-connection.sh # Verify proxy works
+├── get-local-ip.sh # Find machine IP
+├── package.json # Express dependency
+├── README.md # Setup guide
+└── TROUBLESHOOTING.md # Common issues
+```
+
+**Proxy Server (`claude-proxy.js`):**
+- Spawns user's Claude CLI for each request
+- OpenAI-compatible `/v1/messages` endpoint
+- Health check `/ping` endpoint
+- Binds to `0.0.0.0:8080` for LAN access
+- Logs requests for debugging
+
+**User Flow:**
+1. Download ZIP from plugin settings
+2. Extract and run `./start-proxy.sh`
+3. Copy displayed Base URL (e.g., `http://192.168.1.105:8080`)
+4. Paste into plugin settings
+5. Test connection → generate content
+
+### 2. Plugin Integration Files
+
+**New Files:**
+```
+includes/class-local-backend-provider.php
+includes/class-codex-provider.php
+includes/class-provider-manager.php
+includes/interface-ai-provider.php
+views/settings/tab-local-backend.php
+admin/js/test-local-backend.js
+downloads/agentic-writer-local-backend.zip
+```
+
+**Modified Files:**
+```
+includes/class-openrouter-provider.php
+ → Implement WP_Agentic_Writer_AI_Provider_Interface
+ → No behavior changes
+
+includes/class-gutenberg-sidebar.php
+ → Replace: WP_Agentic_Writer_OpenRouter_Provider::get_instance()
+ → With: WP_Agentic_Writer_Provider_Manager::get_provider_for_task($type)
+
++ 20 other files with provider calls
+```
+
+### 3. Settings UI
+
+**New Tab:** "Local Backend"
+- Download local backend package
+- Base URL input
+- API Key input (dummy)
+- Model selector
+- "Test Connection" button
+- Connection status indicator
+- Troubleshooting guide
+
+**Per-Task Routing (Advanced):**
+- Simple mode: Enable/Disable Local Backend (uses for all text)
+- Advanced mode: Task routing matrix
+
+### 4. Migration & Backwards Compatibility
+
+**Phase 1: Abstraction (Non-Breaking)**
+- Create `interface-ai-provider.php`
+- Create `class-provider-manager.php`
+- OpenRouter implements interface
+- All calls route through manager → defaults to OpenRouter
+- **100% backwards compatible, no settings changes**
+
+**Phase 2: Local Backend Provider**
+- Implement `class-local-backend-provider.php`
+- Create proxy package (claude-proxy.js + scripts)
+- Add "Local Backend" settings tab
+- Implement connection test handler
+- Test with user's local setup
+
+**Phase 3: Codex Provider**
+- Implement `class-codex-provider.php`
+- Add Codex API key to settings
+- Add Codex as task routing option
+- Test Codex integration
+
+**Phase 4: Update All Provider Calls**
+- Update 23+ files to use Provider Manager
+- Test all task types (chat, clarity, planning, writing, refinement, image)
+- Ensure streaming works with all providers
+- Verify cost tracking
+
+## Key Technical Decisions
+
+### Local Backend Protocol
+
+**Why OpenAI-compatible format:**
+- Plugin already uses message-based format
+- Easy to proxy to Claude CLI
+- Future-proof for other local models
+
+**Request Format:**
+```json
+POST http://192.168.1.105:8080/v1/messages
+{
+ "messages": [
+ {"role": "user", "content": "Write about AI"}
+ ]
+}
+```
+
+**Response Format:**
+```json
+{
+ "id": "local-1234567890",
+ "object": "chat.completion",
+ "model": "claude-local",
+ "choices": [{
+ "message": {
+ "role": "assistant",
+ "content": "Article content..."
+ },
+ "finish_reason": "stop"
+ }]
+}
+```
+
+### Codex Integration
+
+**Direct API Calls:**
+- Use OpenAI PHP library or `wp_remote_post`
+- Standard chat completions endpoint
+- Same format as OpenRouter
+
+**Why Codex:**
+- High quality for coding/technical content
+- Alternative to Local Backend
+- Cloud-based when user's machine offline
+
+## Cost Tracking Integration
+
+**Challenge:** Local Backend = $0, Codex/OpenRouter = cost
+
+**Solution:**
+```php
+// Provider returns cost data
+$result = $provider->chat($messages, $options, $type);
+$cost = $result['cost'] ?? 0;
+
+if ($cost > 0 && $post_id > 0) {
+ do_action('wp_aw_after_api_request',
+ $post_id,
+ $result['model'] ?? 'unknown',
+ $type,
+ $result['input_tokens'] ?? 0,
+ $result['output_tokens'] ?? 0,
+ $cost
+ );
+}
+```
+
+**Dashboard Display:**
+```
+Session Cost: $0.15
+ - Local Backend: 12 requests (free)
+ - Codex: 3 requests ($0.10)
+ - OpenRouter: 2 images ($0.05)
+
+Today: $2.40
+Month: $45.00
+```
+
+## Error Handling & Fallbacks
+
+### Local Backend Unreachable
+
+```php
+$local_provider = new WP_Agentic_Writer_Local_Backend_Provider();
+
+if (!$local_provider->is_available()) {
+ // Fallback to OpenRouter
+ error_log('Local Backend unavailable, using OpenRouter fallback');
+ return WP_Agentic_Writer_OpenRouter_Provider::get_instance();
+}
+```
+
+**Admin Notice:**
+"⚠️ Local Backend unreachable. Using OpenRouter fallback. Check proxy: `./start-proxy.sh`"
+
+### Connection Test Results
+
+```
+✅ Connected! Proxy responding correctly.
+❌ Connection timeout. Is proxy running? Check: ps aux | grep claude-proxy
+❌ Connection refused. Start proxy: ./start-proxy.sh
+❌ Wrong IP. Find correct IP: ./get-local-ip.sh
+❌ Claude CLI not responding. Test: echo "test" | claude
+```
+
+## UI/UX Considerations
+
+### Settings Page Flow
+
+1. **Tab: Local Backend**
+ - Big download button for proxy package
+ - Prerequisites checklist
+ - Base URL input (pre-filled from clipboard?)
+ - Test connection button
+ - Status: 🟢 Connected / 🔴 Offline
+
+2. **Tab: Providers**
+ - Simple mode: "Use Local Backend" toggle
+ - Advanced mode: Task routing matrix
+ - Provider status indicators
+
+3. **Tab: Models** (existing)
+ - Add Codex models
+ - Show provider per model
+
+### Sidebar Indicators
+
+**Provider Badge:**
+```
+🏠 Local (Free)
+🔗 Codex ($0.02)
+☁️ OpenRouter ($0.05)
+```
+
+**Connection Status:**
+```
+🟢 Local Backend: Connected
+🔴 Local Backend: Offline (using OpenRouter)
+```
+
+## Testing Strategy
+
+**Test Cases:**
+1. Cloud-only mode (existing behavior)
+2. Local-only mode (Ollama for all text)
+3. Hybrid mode (recommended config)
+4. Fallback when Ollama unavailable
+5. Streaming works with both providers
+6. Cost tracking accurate
+7. Model selection per provider
+
+## Performance Implications
+
+**Local Backend:**
+- **Latency**: ~50-200ms LAN vs ~500-2000ms cloud
+- **Throughput**: Limited by Claude CLI (~20-30 tokens/sec)
+- **Concurrency**: One request at a time (spawn per request)
+- **Quality**: Same as cloud Claude (uses same models)
+
+**Codex:**
+- **Latency**: Standard OpenAI API latency
+- **Quality**: High for technical/coding content
+- **Cost**: Per-token pricing
+
+**OpenRouter:**
+- **Image Generation**: Only option for FLUX/Recraft
+- **Fallback**: When local backend offline
+- **Cost**: Per-token pricing
+
+## Deployment Scenarios
+
+### Scenario 1: Local Development (User's Machine)
+
+**Setup:**
+- WordPress on Local by Flywheel (bricks.local)
+- Node.js proxy on same machine (localhost:8080)
+- Claude CLI configured with Z.ai
+
+**Config:**
+```
+Local Backend URL: http://localhost:8080
+All text tasks: Local Backend
+Images: OpenRouter
+Cost: ~$0 for text, ~$0.05/image
+```
+
+### Scenario 2: Local Dev + Cloud Production
+
+**Dev:**
+- Use Local Backend for free development
+- Test with real Claude quality
+
+**Production:**
+- Auto-switch to OpenRouter when local unavailable
+- Seamless fallback
+
+### Scenario 3: Agency with Shared Local Backend
+
+**Setup:**
+- One machine runs proxy on LAN
+- Multiple WordPress sites connect to it
+- All sites share one Z.ai account
+
+**Config:**
+```
+Local Backend URL: http://192.168.1.50:8080
+Cost: Free for entire team
+```
+
+## Implementation Phases
+
+### Phase 1: Core Infrastructure (Week 1)
+- [ ] Create provider interface
+- [ ] Create provider manager
+- [ ] OpenRouter implements interface
+- [ ] Update 3-5 files to use manager (test)
+- [ ] Verify backwards compatibility
+
+### Phase 2: Local Backend Package (Week 1)
+- [ ] Create `claude-proxy.js` with `/v1/messages` endpoint
+- [ ] Create startup/shutdown scripts
+- [ ] Test with actual Claude CLI
+- [ ] Package as ZIP
+- [ ] Write README with setup guide
+
+### Phase 3: Local Backend Provider (Week 2)
+- [ ] Implement `class-local-backend-provider.php`
+- [ ] Add settings tab UI
+- [ ] Implement connection test
+- [ ] Add ZIP download from settings
+- [ ] Test end-to-end flow
+
+### Phase 4: Codex Provider (Week 2)
+- [ ] Implement `class-codex-provider.php`
+- [ ] Add Codex API key to settings
+- [ ] Test Codex integration
+- [ ] Add to task routing options
+
+### Phase 5: Full Rollout (Week 3)
+- [ ] Update all 23+ files to use provider manager
+- [ ] Test all task types
+- [ ] Verify streaming works
+- [ ] Test cost tracking
+- [ ] Documentation
+
+### Phase 6: Polish (Week 3)
+- [ ] Connection status widget
+- [ ] Auto-fallback logic
+- [ ] Error messages with actionable guidance
+- [ ] Video tutorial
+- [ ] Troubleshooting guide
+
+## Implementation Estimate
+
+**Phase 1 (Infrastructure):** 4-5 hours
+- Provider interface, manager, OpenRouter refactor
+- Test with 3-5 files
+
+**Phase 2 (Local Backend Package):** 6-8 hours
+- Node.js proxy development
+- Scripts (start, stop, test)
+- ZIP packaging
+- Documentation
+
+**Phase 3 (Local Backend Integration):** 8-10 hours
+- Provider class
+- Settings UI
+- Connection test
+- End-to-end testing
+
+**Phase 4 (Codex):** 4-6 hours
+- Provider implementation
+- Settings integration
+- Testing
+
+**Phase 5 (Full Rollout):** 8-10 hours
+- Update 23+ files
+- Test all scenarios
+- Cost tracking
+- Documentation
+
+**Phase 6 (Polish):** 4-6 hours
+- UI improvements
+- Error handling
+- Video tutorial
+- Troubleshooting docs
+
+**Total:** 34-45 hours (~1-1.5 weeks)
+
+## Success Criteria
+
+✅ User can download local backend package
+✅ User can start proxy on their machine
+✅ Plugin connects to local backend successfully
+✅ All text tasks work via local backend ($0 cost)
+✅ Images work via OpenRouter
+✅ Codex works as alternative provider
+✅ Automatic fallback to OpenRouter when local offline
+✅ Cost tracking shows local = $0, cloud = actual cost
+✅ Streaming works with all providers
+✅ 100% backwards compatible (defaults to OpenRouter)
+
+## Ready to Implement
+
+This plan matches `local-backend-feature.md` requirements:
+- ✅ Claude CLI proxy via Node.js
+- ✅ HTTP-based local backend
+- ✅ Codex integration
+- ✅ OpenRouter for images
+- ✅ Provider abstraction system
+- ✅ Fallback logic
+- ✅ Complete UI/UX flow
+
+Confirm to proceed with implementation.
diff --git a/image-best-flow-recommendation.md b/image-best-flow-recommendation.md
new file mode 100644
index 0000000..ba5fb13
--- /dev/null
+++ b/image-best-flow-recommendation.md
@@ -0,0 +1,363 @@
+# WP Agentic Writer: Recommended Best Flow for Images (Cost-Optimized)
+
+## The Challenge You Asked About
+
+**Your question:**
+> "After article generation, how do we get image placement with alt by writing agent, then generate recommended images? Need to be cost-efficient with image prompts."
+
+**The answer:** Use the **writing agent itself** to analyze placement + generate prompts (tiny cost), then show user a preview before spending on image generation.
+
+---
+
+## Table of Contents
+
+1. [Recommended Best Flow (Option A - SAFEST)](#recommended-best-flow-option-a---safest)
+2. [Alternative Flows (B & C)](#alternative-flows-b--c)
+3. [Your Configuration (from screenshot)](#your-configuration-from-screenshot)
+4. [Cost Breakdown](#cost-breakdown)
+5. [Implementation Priority](#implementation-priority)
+
+---
+
+## Recommended Best Flow (Option A - SAFEST)
+
+This is the flow I recommend for **maximum cost control + quality** based on your plugin's design.
+
+### Step-by-Step
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ USER ACTION: Generate Article │
+│ (Using Writing Model: Claude 3.5 Sonnet from preset) │
+└─────────────────┬────────────────────────────────────────┘
+ ↓
+┌──────────────────────────────────────────────────────────┐
+│ PLUGIN AUTOMATIC (Backend) │
+├──────────────────────────────────────────────────────────┤
+│ Step 1: ANALYZE PLACEMENT │
+│ • Model: Same Writing Model (Claude 3.5 Sonnet) │
+│ • Input: Full article markdown │
+│ • Output: JSON with placement points │
+│ • Cost: $0.0008 (tiny token call) │
+│ │
+│ Step 2: GENERATE IMAGE PROMPTS │
+│ • Model: Same Writing Model │
+│ • Input: Article + placement points │
+│ • Output: 3 image specs (prompt + alt + placement) │
+│ • Cost: $0.0015 (tiny token call) │
+│ │
+│ Status: "Analyzing images..." → "Ready to review" │
+└─────────────────┬────────────────────────────────────────┘
+ ↓
+┌──────────────────────────────────────────────────────────┐
+│ MODAL: IMAGE PREVIEW (User Review - $0 cost) │
+├──────────────────────────────────────────────────────────┤
+│ │
+│ "3 images planned for your article" │
+│ │
+│ ╔════════════════════════════════════════════════════╗ │
+│ ║ IMAGE 1: HERO (After Introduction) ║ │
+│ ║ ║ │
+│ ║ Placement: After intro, before "Getting Started" ║ │
+│ ║ Type: Hero/Dashboard ║ │
+│ ║ ║ │
+│ ║ Prompt (EDITABLE): ║ │
+│ ║ "N8n workflow automation dashboard screenshot, ║ │
+│ ║ showing colorful nodes on blue background, ║ │
+│ ║ modern minimalist SaaS interface" ║ │
+│ ║ ║ │
+│ ║ Alt Text: "N8n automation dashboard with nodes" ║ │
+│ ║ ║ │
+│ ║ [Edit Prompt ✎] [Generate $0.03] [Skip] ║ │
+│ ╚════════════════════════════════════════════════════╝ │
+│ │
+│ ╔════════════════════════════════════════════════════╗ │
+│ ║ IMAGE 2: DIAGRAM (After Section 1) ║ │
+│ ║ ║ │
+│ ║ Placement: After "Understanding Workflows" ║ │
+│ ║ Type: Technical Diagram ║ │
+│ ║ ║ │
+│ ║ Prompt (EDITABLE): ║ │
+│ ║ "Workflow architecture diagram showing trigger, ║ │
+│ ║ condition, action components with arrows, ║ │
+│ ║ technical line-art style, blue palette" ║ │
+│ ║ ║ │
+│ ║ Alt Text: "Workflow trigger-condition-action flow" ║ │
+│ ║ ║ │
+│ ║ [Edit Prompt ✎] [Generate $0.03] [Skip] ║ │
+│ ╚════════════════════════════════════════════════════╝ │
+│ │
+│ ╔════════════════════════════════════════════════════╗ │
+│ ║ IMAGE 3: SCREENSHOT (Before Conclusion) ║ │
+│ ║ ║ │
+│ ║ Placement: Before "Conclusion" ║ │
+│ ║ Type: Product Screenshot ║ │
+│ ║ ║ │
+│ ║ Prompt (EDITABLE): ║ │
+│ ║ "N8n real-time monitoring dashboard showing ║ │
+│ ║ workflow execution logs, status indicators, ║ │
+│ ║ professional SaaS product design" ║ │
+│ ║ ║ │
+│ ║ Alt Text: "N8n real-time monitoring interface" ║ │
+│ ║ ║ │
+│ ║ [Edit Prompt ✎] [Generate $0.03] [Skip] ║ │
+│ ╚════════════════════════════════════════════════════╝ │
+│ │
+│ ───────────────────────────────────────────────────── │
+│ Cost Estimate: Individual generation │
+│ • Generate all 3: $0.09–0.21 (based on image tier) │
+│ • Generate 2: $0.06–0.14 │
+│ • Generate 1: $0.03–0.07 │
+│ │
+│ [Generate All 3] [Generate Selected] [Skip Images] │
+│ [Cancel] │
+└──────────────────┬───────────────────────────────────────┘
+ ↓
+ USER CHOOSES (examples):
+ • Click [Generate All 3] → All images generated now
+ • Click [Generate] on Image 1 only → Hero only
+ • Edit Image 1 prompt, then [Generate] → Custom prompt
+ • Click [Skip Images] → No images, save cost
+ ↓
+┌──────────────────────────────────────────────────────────┐
+│ AUTOMATIC IMAGE INSERTION │
+├──────────────────────────────────────────────────────────┤
+│ For each generated image: │
+│ 1. Download image from FLUX.2/image model │
+│ 2. Upload to WordPress media library │
+│ 3. Insert into article at placement point │
+│ 4. Add alt text automatically │
+│ │
+│ Status: "Inserting images..." → "Done!" │
+└─────────────────┬────────────────────────────────────────┘
+ ↓
+┌──────────────────────────────────────────────────────────┐
+│ FINAL RESULT: Article with Images │
+├──────────────────────────────────────────────────────────┤
+│ │
+│ # Getting Started with N8n Automation │
+│ │
+│ Introduction paragraph... │
+│ │
+│  │
+│ │
+│ ## Getting Started │
+│ Content... │
+│ │
+│ ## Understanding Workflows │
+│ Content... │
+│ │
+│  │
+│ │
+│ ## Advanced Monitoring │
+│ Content... │
+│ │
+│  │
+│ │
+│ [Preview in Gutenberg] [Publish] [Download MD] │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Key Features of Option A
+
+✅ **Cost control:** User sees cost before spending
+✅ **Quality control:** Can edit prompts before generation
+✅ **Flexibility:** Generate 0, 1, 2, or 3 images
+✅ **User review:** Know exactly what images they'll get
+✅ **Selective generation:** Generate only what matters
+✅ **Smart placement:** Analyzed by writing agent (best understanding)
+✅ **Efficient prompts:** Precise, contextual, no trial-and-error
+
+### Costs with Option A
+
+| Scenario | Analysis | Prompts | Images | Total |
+|----------|----------|---------|--------|-------|
+| User generates all 3 | $0.0008 | $0.0015 | $0.09–0.21 | $0.092–0.212 |
+| User generates 2 | $0.0008 | $0.0015 | $0.06–0.14 | $0.063–0.142 |
+| User generates 1 (hero) | $0.0008 | $0.0015 | $0.03–0.07 | $0.032–0.072 |
+| User skips images | $0.0008 | $0.0015 | $0 | $0.0023 |
+
+**Best case:** User generates 1 hero = **$0.032–0.072/article** (vs $0.21–0.70 with trial-and-error)
+
+---
+
+## Alternative Flows (B & C)
+
+### Option B: Automatic Full Generation (FASTEST)
+
+```
+Article generated
+ ↓
+Plugin automatically generates ALL images without review
+ ↓
+"Article + images ready!" (1-2 minutes total)
+```
+
+**Pros:** One-click, minimal user interaction
+**Cons:** Always costs full image budget (no user control)
+**Cost:** Full $0.12–0.35 (analysis + all images always generated)
+
+**Use when:** User has unlimited budget OR you offer it as "premium fast mode"
+
+---
+
+### Option C: Smart Selective with Recommendations (BALANCED)
+
+```
+Similar to Option A, but plugin recommends:
+- "Hero image has best impact/cost ratio" [Generate hero]
+- "Diagrams help understanding" [Generate diagram?]
+- "Screenshot is optional" [Generate?]
+```
+
+**Pros:** Guides user toward cost-effective choices
+**Cons:** Slightly more UI complexity
+**Cost:** User-controlled (guided)
+
+**Use when:** You want to educate users about cost-benefit tradeoffs
+
+---
+
+## Your Configuration (from screenshot)
+
+Based on your current model configuration:
+
+```
+Chat Model: Google: Gemini 2.5 Flash
+Clarity Model: Google: Gemini 2.5 Flash
+Planning Model: Google: Gemini 2.5 Flash
+Writing Model: Anthropic: Claude 3.5 Sonnet
+Refinement Model: Anthropic: Claude 3.5 Sonnet
+Image Model: Gpt 4o (or FLUX.2 from preset)
+```
+
+### Recommended Implementation
+
+```php
+// Option A implementation (safest, recommended)
+
+// 1. After article generation, automatically:
+$placement_data = analyze_article_for_images(
+ $article,
+ 'anthropic/claude-3.5-sonnet' // Use same writing model
+);
+
+// 2. Generate prompts
+$image_specs = generate_image_prompts(
+ $article,
+ $placement_data,
+ 'anthropic/claude-3.5-sonnet' // Same model
+);
+
+// 3. Show UI (don't generate images yet)
+show_image_review_modal($image_specs);
+
+// 4. User clicks [Generate All] or individual [Generate]
+// 5. Only then call image generation
+
+// Cost so far: $0.0023 (tiny)
+// User controls image generation cost: $0.03–0.21
+```
+
+---
+
+## Cost Breakdown
+
+### Analysis + Prompt Generation (Automatic, Non-Optional)
+
+| Task | Tokens In | Tokens Out | Cost |
+|------|-----------|------------|------|
+| Placement analysis | 2,000 | 800 | $0.0008 |
+| Prompt generation | 3,000 | 1,000 | $0.0015 |
+| **Total** | **5,000** | **1,800** | **$0.0023** |
+
+**This is already paid by article generation (uses writing model already called).**
+
+### Image Generation (User-Controlled)
+
+**Per image (based on model tier):**
+
+| Image Model | Cost/Image | 3 Images |
+|------------|-----------|----------|
+| FLUX.2 klein (Budget) | $0.03–0.05 | $0.09–0.15 |
+| Riverflow/FLUX.2 Pro (Balanced) | $0.06–0.10 | $0.18–0.30 |
+| FLUX.2 max (Premium) | $0.07–0.21 | $0.21–0.63 |
+
+### Total Article Cost
+
+| Scenario | Text | Analysis | Prompts | Images | Total |
+|----------|------|----------|---------|--------|-------|
+| Article only | $0.03–0.07 | $0.0008 | $0.0015 | $0 | **$0.032–0.072** |
+| Article + 1 hero | $0.03–0.07 | $0.0008 | $0.0015 | $0.03–0.21 | **$0.062–0.292** |
+| Article + 2 images | $0.03–0.07 | $0.0008 | $0.0015 | $0.06–0.42 | **$0.092–0.492** |
+| Article + 3 images | $0.03–0.07 | $0.0008 | $0.0015 | $0.09–0.63 | **$0.122–0.702** |
+
+---
+
+## Implementation Priority
+
+### Phase 1: Core Logic (3-4 hours)
+
+```php
+✓ analyze_article_for_images() // Identify placements
+✓ generate_image_prompts() // Create specs
+✓ generate_image_from_prompt() // Call image model
+✓ insert_images_into_article() // Embed in markdown
+```
+
+### Phase 2: User Interface (4-5 hours)
+
+```php
+✓ Image review modal UI // Show 3 specs
+✓ [Generate] button per image // Individual generation
+✓ [Generate All] button // Batch generation
+✓ [Edit Prompt] capability // Let users customize
+✓ Cost calculator display // Show estimated cost
+```
+
+### Phase 3: Polish (2-3 hours)
+
+```php
+✓ Image preview before insertion // Show user the image
+✓ Error handling + retry logic // Handle failures
+✓ Success notifications // Feedback
+✓ Progress indicators // "Generating image 2/3..."
+```
+
+---
+
+## Why Option A is Best for Your Plugin
+
+1. **User controls costs** → They see preview before spending
+2. **Respects budgets** → Budget tier users generate 1 image
+3. **Quality focus** → Users can edit prompts if needed
+4. **Flexible** → Some users skip images entirely (saves costs)
+5. **Educational** → Users learn what good prompts look like
+6. **Smart prompts** → Using writing agent (best context understanding)
+
+---
+
+## Summary: Recommended Best Flow
+
+```
+AUTOMATIC (Backend):
+1. Analyze article for placement → $0.0008
+2. Generate image specs/prompts → $0.0015
+3. Show user preview modal → $0 (free review)
+
+MANUAL (User Selects):
+4. User clicks [Generate] on images → User controls cost
+5. Plugin inserts into article → Automatic
+
+RESULT:
+- Article + images ready for Gutenberg
+- User spent only what they wanted
+- Total cost: $0.032–0.702 (user-controlled)
+- Quality: High (smart placement + customizable prompts)
+```
+
+---
+
+**Document version:** 1.0
+**Date:** January 27, 2026
+**Status:** Ready for Implementation
diff --git a/image-gen-flow.md b/image-gen-flow.md
new file mode 100644
index 0000000..40f2f79
--- /dev/null
+++ b/image-gen-flow.md
@@ -0,0 +1,1345 @@
+# WP Agentic Writer: Image Generation & Selection Flow
+
+## Executive Summary
+
+This document defines the **complete lifecycle** of images from agent recommendation → generation → variant management → final WordPress Media upload.
+
+**Key principle:** Regenerate creates NEW variants (doesn't delete old ones). All temp images belong to a post. Users see variants in modal, select one, and commit to WordPress Media with recommended alt text.
+
+---
+
+## Table of Contents
+
+1. [Overview & Architecture](#overview--architecture)
+2. [Data Model](#data-model)
+3. [Flow 1: Article Generation & Image Recommendations](#flow-1-article-generation--image-recommendations)
+4. [Flow 2: Image Block Toolbar & Modal](#flow-2-image-block-toolbar--modal)
+5. [Flow 3: Image Generation (Variants)](#flow-3-image-generation-variants)
+6. [Flow 4: Variant Selection & Media Upload](#flow-4-variant-selection--media-upload)
+7. [Flow 5: Temp Image Management](#flow-5-temp-image-management)
+8. [Admin Page: Image Library](#admin-page-image-library)
+9. [REST API Endpoints](#rest-api-endpoints)
+10. [Implementation Checklist](#implementation-checklist)
+
+---
+
+## Overview & Architecture
+
+### Core concept
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ WRITING AGENT generates article + 3 image recommendations │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ Plugin converts recommendations → 3 core/image blocks │
+│ Each block has: data-agent-image-id="img_X" │
+│ Stores recommendations in wp_agentic_images table │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ USER EDITS IN GUTENBERG EDITOR │
+│ │
+│ [Image block] [Image block] [Image block] │
+│ ↓ Generate ↓ Generate ↓ Generate │
+│ ↓ (Toolbar btn) ↓ (Toolbar btn) ↓ (Toolbar btn) │
+│ │
+│ Each opens YOUR modal with prompt + alt editable │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ USER ACTIONS IN MODAL │
+│ │
+│ [View Prompt] [Edit Prompt] │
+│ [View Alt] [Edit Alt] │
+│ [Generate] → generates 1-3 variants │
+│ stores ALL in /wp-content/agentic-writer-temp/ │
+│ │
+│ [Regenerate] → generates MORE variants (doesn't delete old) │
+│ adds to same image_id pool │
+│ │
+│ [Use Media Library] → opens core media modal │
+│ with pre-filled alt suggestion │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ USER SELECTS A VARIANT │
+│ │
+│ [Variant 1] [Variant 2] [Variant 3] [Variant 4] │
+│ [Select] [Select] [Select] [Select] │
+│ │
+│ Other variants stay in temp folder + DB │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ BACKEND: Commit Selected Variant to WP Media │
+│ │
+│ 1. media_handle_sideload(temp_image_path) │
+│ 2. Set attachment alt → recommended alt (or user-edited) │
+│ 3. Update wp_agentic_images: status='committed' │
+│ attachment_id=123 │
+│ 4. Return attachment ID + URL │
+└────────────────────┬────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ FRONTEND: Update Gutenberg Image Block │
+│ │
+│ updateBlockAttributes(block.clientId, { │
+│ id: attachment_id, │
+│ url: attachment_url, │
+│ alt: recommended_alt │
+│ }) │
+│ │
+│ Remove data-agent-image-id (no longer a placeholder) │
+└────────────────────────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ TEMP IMAGE CLEANUP (Manual + Auto) │
+│ │
+│ Admin page "Generated Images" tab shows: │
+│ - All temp images (by post, by status) │
+│ - [Delete selected] [Auto-cleanup old (>7 days)] │
+│ │
+│ Cron job: wp_schedule_event() → delete temps > 7 days │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Data Model
+
+### Table: `wp_agentic_images`
+
+Stores recommendations + generation history for each image per post.
+
+```sql
+CREATE TABLE wp_agentic_images (
+ id BIGINT AUTO_INCREMENT PRIMARY KEY,
+ post_id BIGINT NOT NULL,
+
+ -- Recommendation from agent
+ agent_image_id VARCHAR(50) NOT NULL, -- e.g., "img_hero_1"
+ placement VARCHAR(100), -- "intro_hero", "after_section_2"
+ section_title VARCHAR(255), -- "Introduction to n8n"
+
+ -- Original recommendation
+ prompt_initial TEXT NOT NULL, -- Agent's initial prompt
+ alt_text_initial TEXT, -- Agent's suggested alt
+
+ -- User edits (nullable)
+ prompt_edited TEXT, -- Null if user didn't edit
+ alt_text_edited TEXT, -- Null if user didn't edit
+
+ -- Committed image (when user selects a variant)
+ attachment_id BIGINT, -- WP attachment ID (null until committed)
+ status VARCHAR(30) DEFAULT 'pending', -- pending, generating, committed, discarded
+
+ -- Cost tracking
+ cost_estimate DECIMAL(10, 4), -- Based on image model pricing
+ cost_actual DECIMAL(10, 4), -- Updated after generation
+ image_model VARCHAR(100), -- Which model was used
+
+ -- Metadata
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+ KEY idx_post (post_id),
+ KEY idx_agent_image_id (post_id, agent_image_id),
+ KEY idx_status (status),
+ KEY idx_created (created_at)
+);
+```
+
+### Table: `wp_agentic_images_variants`
+
+Tracks all generated variants (temp images) for each agent_image_id.
+
+```sql
+CREATE TABLE wp_agentic_images_variants (
+ id BIGINT AUTO_INCREMENT PRIMARY KEY,
+
+ -- Reference to main image record
+ agentic_image_id BIGINT NOT NULL,
+ post_id BIGINT NOT NULL,
+ agent_image_id VARCHAR(50) NOT NULL, -- e.g., "img_hero_1"
+
+ -- Variant details
+ variant_number INT DEFAULT 1, -- 1st, 2nd, 3rd generation attempt
+ temp_file_path VARCHAR(500) NOT NULL, -- /wp-content/agentic-writer-temp/xxx.jpg
+ temp_file_url VARCHAR(500) NOT NULL, -- URL to temp image
+ file_size INT, -- In bytes
+
+ -- Generation details
+ prompt_used TEXT, -- Exact prompt sent to image model
+ image_model_used VARCHAR(100), -- Which model generated this
+ generation_time INT, -- Seconds to generate
+ cost DECIMAL(10, 4), -- Cost of this generation
+
+ -- Selection status
+ is_selected TINYINT DEFAULT 0, -- 1 if user selected this variant
+ selected_at TIMESTAMP NULL,
+
+ -- Lifecycle
+ status VARCHAR(30) DEFAULT 'temp', -- temp, selected, discarded, auto_deleted
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ deleted_at TIMESTAMP NULL,
+
+ KEY idx_agentic_image (agentic_image_id),
+ KEY idx_post (post_id),
+ KEY idx_status (status),
+ KEY idx_created (created_at)
+);
+```
+
+### File system: Temp images
+
+```
+/wp-content/agentic-writer-temp/
+├── post_/
+│ ├── img_hero_1/
+│ │ ├── variant_1.jpg
+│ │ ├── variant_2.jpg
+│ │ └── variant_3.jpg
+│ ├── img_diag_1/
+│ │ └── variant_1.jpg
+│ └── img_section_2/
+│ ├── variant_1.jpg
+│ └── variant_2.jpg
+└── [cleanup cron removes files 7+ days old]
+```
+
+---
+
+## Flow 1: Article Generation & Image Recommendations
+
+### What the agent returns
+
+After writing article, agent provides JSON response:
+
+```json
+{
+ "status": "article_complete",
+ "article_blocks": [
+ {
+ "blockName": "core/paragraph",
+ "attrs": {},
+ "innerBlocks": [],
+ "innerHTML": "Introduction text...
"
+ },
+ {
+ "blockName": "core/image",
+ "attrs": {
+ "id": null,
+ "url": null,
+ "alt": "",
+ "data-agent-image-id": "img_hero_1"
+ }
+ }
+ ],
+ "images": [
+ {
+ "agent_image_id": "img_hero_1",
+ "placement": "intro_hero",
+ "section_title": "Introduction",
+ "prompt": "N8n workflow automation dashboard...",
+ "alt": "N8n automation dashboard with workflow nodes",
+ "image_model": "sourceful/riverflow-v2-max"
+ },
+ {
+ "agent_image_id": "img_diag_1",
+ "placement": "after_section_2",
+ "section_title": "How Workflows Run",
+ "prompt": "Workflow architecture diagram...",
+ "alt": "Workflow trigger-condition-action diagram",
+ "image_model": "sourceful/riverflow-v2-max"
+ },
+ {
+ "agent_image_id": "img_section_4",
+ "placement": "before_conclusion",
+ "section_title": "Real-world Example",
+ "prompt": "Developer using N8n dashboard...",
+ "alt": "Developer working with N8n automation dashboard",
+ "image_model": "sourceful/riverflow-v2-max"
+ }
+ ]
+}
+```
+
+### Backend handling
+
+```php
+ $post_id,
+ 'post_content' => $post_content,
+ 'post_status' => 'draft'
+ ]);
+
+ // 2. Save each image recommendation
+ foreach ( $agent_response['images'] as $image_spec ) {
+ self::save_image_recommendation(
+ $post_id,
+ $image_spec
+ );
+ }
+
+ // 3. Return success message for chat
+ return [
+ 'status' => 'article_complete',
+ 'post_id' => $post_id,
+ 'message' => sprintf(
+ 'Article created. %d image suggestions ready in the Images panel.',
+ count( $agent_response['images'] )
+ )
+ ];
+}
+
+/**
+ * Store individual image recommendation
+ */
+private static function save_image_recommendation( $post_id, $image_spec ) {
+ global $wpdb;
+
+ $wpdb->insert(
+ $wpdb->prefix . 'agentic_images',
+ [
+ 'post_id' => $post_id,
+ 'agent_image_id' => $image_spec['agent_image_id'],
+ 'placement' => $image_spec['placement'],
+ 'section_title' => $image_spec['section_title'],
+ 'prompt_initial' => $image_spec['prompt'],
+ 'alt_text_initial' => $image_spec['alt'],
+ 'image_model' => $image_spec['image_model'],
+ 'status' => 'pending'
+ ],
+ [ '%d', '%s', '%s', '%s', '%s', '%s', '%s', '%s' ]
+ );
+}
+```
+
+---
+
+## Flow 2: Image Block Toolbar & Modal
+
+### Block toolbar button
+
+In Gutenberg, each `core/image` block with `data-agent-image-id` gets a toolbar button:
+
+```jsx
+// registerPlugin('agentic-image-toolbar', {
+// render() {
+// return
+ openImageModal(agentImageId, block)}
+ icon="image"
+ />
+
+ );
+}
+
+/**
+ * Opens YOUR custom modal (not WP media modal)
+ */
+function openImageModal(agentImageId, block) {
+ wp.data.dispatch('agentic-writer').openImageGenerationModal({
+ agentImageId,
+ blockClientId: block.clientId,
+ postId: wp.data.select('core/editor').getCurrentPostId()
+ });
+}
+```
+
+### Your custom modal
+
+```jsx
+function ImageGenerationModal({ agentImageId, blockClientId, postId }) {
+ const [prompt, setPrompt] = useState(initialPrompt);
+ const [alt, setAlt] = useState(initialAlt);
+ const [variants, setVariants] = useState([]);
+ const [isGenerating, setIsGenerating] = useState(false);
+ const [step, setStep] = useState('edit'); // 'edit' | 'generating' | 'select'
+
+ const handleGenerate = async () => {
+ setIsGenerating(true);
+ setStep('generating');
+
+ try {
+ const response = await fetch('/wp-json/agentic-writer/v1/generate-image', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ post_id: postId,
+ agent_image_id: agentImageId,
+ prompt: prompt, // User-edited if changed
+ alt: alt // User-edited if changed
+ })
+ });
+
+ const result = await response.json();
+ setVariants(result.variants);
+ setStep('select');
+ } catch (error) {
+ console.error('Generation failed:', error);
+ } finally {
+ setIsGenerating(false);
+ }
+ };
+
+ const handleRegenerate = async () => {
+ // Re-generate: creates MORE variants
+ // Does NOT delete existing ones
+ await handleGenerate();
+ };
+
+ const handleSelect = async (variantId) => {
+ // Commit this variant to WP Media
+ const response = await fetch('/wp-json/agentic-writer/v1/commit-image', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ post_id: postId,
+ agent_image_id: agentImageId,
+ variant_id: variantId,
+ alt: alt // Final alt text
+ })
+ });
+
+ const result = await response.json();
+
+ // Update Gutenberg block
+ wp.data.dispatch('core/block-editor').updateBlockAttributes(
+ blockClientId,
+ {
+ id: result.attachment_id,
+ url: result.attachment_url,
+ alt: result.alt,
+ 'data-agent-image-id': undefined // Remove placeholder marker
+ }
+ );
+
+ // Close modal
+ wp.data.dispatch('agentic-writer').closeImageGenerationModal();
+ };
+
+ if (step === 'edit') {
+ return (
+
+
+
+
+