690991c526
Major refactoring cleanup: - Add new controller architecture (class-controller-*.php) - Add new settings-v2 UI (views/settings-v2/) - Add new CSS architecture (agentic-sidebar.css, tokens) - Add esbuild build pipeline (scripts/build.js, package.json) - Add composer dependencies (vendor/) - Add frontend src directory (assets/js/src/index.jsx) - Add documentation files - Remove old/obsolete files (class-settings.php, old CSS) This commits all pending changes from previous refactoring efforts.
23 KiB
23 KiB
WP Agentic Writer — Settings Page Features & Fields
Plugin option key:
wp_agentic_writer_settings(single serialized option).
Active settings class:WP_Agentic_Writer_Settings_V2(includes/class-settings-v2.php).
Settings group:wp_agentic_writer_settings.
Form action:options.php.
Table of Contents
- Navigation Tabs
- Tab: General
- Tab: AI Models
- Tab: Local Backend
- Tab: MEMANTO
- Tab: OpenRouter Cost Log
- Tab: Model Guide (Read-Only)
- Global Components
- AJAX Actions Reference
- Complete Option Key Index
- Sanitization & Validation Rules
- Key Files Reference
1. Navigation Tabs
The settings page is organized into 6 tabs grouped under two sections:
Configuration: General, AI Models, Local Backend, MEMANTO
Analytics & Docs: OpenRouter Cost Log, Model Guide
| Tab ID | Label | Section |
|---|---|---|
general |
General | Configuration |
models |
AI Models | Configuration |
local-backend |
Local Backend | Configuration |
memanto |
MEMANTO | Configuration |
cost-log |
OpenRouter Cost Log | Analytics & Docs |
guide |
Model Guide | Analytics & Docs |
2. Tab: General
Section 2.1 — API Configuration
| Field | Option Key | Type | Input | Required | Default | Description |
|---|---|---|---|---|---|---|
| OpenRouter API Key | openrouter_api_key |
string |
password (with show/hide toggle) |
Yes | "" |
Get from openrouter.ai/keys. |
| Test Connection | (button) | — | button |
— | — | AJAX call to wpaw_test_api_connection. |
Section 2.2 — OpenRouter Budget & Cost Tracking
Display data (read-only, fetched from backend):
| Data | Variable | Source |
|---|---|---|
| Used This Month | $monthly_used |
Cost_Tracker::get_monthly_total() |
| Budget Usage % | $budget_percent |
Calculated: (used / budget) * 100 |
| Remaining | Calculated | max(0, budget - used) |
Fields:
| Field | Option Key | Type | Input | Default | Validation | Description |
|---|---|---|---|---|---|---|
| Monthly Budget (USD) | monthly_budget |
float |
number |
600 |
floatval(), min 0, step 0.01 |
Maximum spend per month. 0 = unlimited. |
| Enable Cost Tracking | cost_tracking_enabled |
bool |
checkbox |
true |
Boolean | Show cost tracking in editor sidebar. |
Section 2.3 — Research & Web Search
| Field | Option Key | Type | Input | Default | Options | Description |
|---|---|---|---|---|---|---|
| Enable Web Search | web_search_enabled |
bool |
checkbox |
false |
— | Default for new posts; also toggleable per-request in editor sidebar. |
| Search Depth | search_depth |
string |
select |
"medium" |
low / medium / high |
Controls search depth level. |
OpenRouter Search Engine:
| Field | Option Key | Type | Input | Default | Options | Description |
|---|---|---|---|---|---|---|
| Search Engine | search_engine |
string |
select |
"auto" |
auto (Native → Exa fallback) / native (Free, built-in) / exa (Paid, ~$0.02/search) |
Used when active model routes through OpenRouter. |
Brave Search API (for Local/Codex):
| Field | Option Key | Type | Input | Default | Description |
|---|---|---|---|---|---|
| Brave Search API Key | brave_search_api_key |
string |
password |
"" |
Used when active model is Local Backend or Codex. Free tier: 2,000 requests/month. |
Section 2.4 — Clarification Quiz
| Field | Option Key | Type | Input | Default | Options | Description |
|---|---|---|---|---|---|---|
| Enable Clarification Quiz | enable_clarification_quiz |
bool |
checkbox |
true |
— | Ask clarifying questions when context is missing. |
| Confidence Threshold | clarity_confidence_threshold |
string |
select |
"0.6" |
0.5 (Very Sensitive) / 0.6 (Sensitive - Recommended) / 0.7 (Balanced) / 0.8 (Strict) / 0.9 (Very Strict) |
When to trigger the quiz. |
| Context Categories | required_context_categories |
array |
multi-checkbox | All 7 checked | target_outcome / target_audience / tone / content_depth / expertise_level / content_type / pov |
Which context dimensions to ask about. |
Section 2.5 — Content Settings (Language)
| Field | Option Key | Type | Input | Default | Description |
|---|---|---|---|---|---|
| Preferred Languages | preferred_languages |
array |
multi-checkbox | ["auto", "English", "Indonesian"] |
Languages shown in the language selector when creating articles. |
| Custom Languages | custom_languages |
array |
dynamic text input list with add/remove | [] |
Add languages not in the predefined list. |
Available predefined languages (24):
auto (Auto-detect), English, Indonesian (Bahasa Indonesia), Javanese (Basa Jawa), Sundanese (Basa Sunda), Spanish (Español), French (Français), Arabic (العربية), Chinese (中文), Japanese (日本語), Portuguese (Português), German (Deutsch), Hindi (हिंदी), Korean (한국어), Vietnamese (Tiếng Việt), Thai (ไทย), Tagalog, Malay (Bahasa Melayu), Russian (Русский), Italian (Italiano), Dutch (Nederlands), Polish (Polski), Turkish (Türkçe), Swedish (Svenska)
Section 2.6 — Advanced Settings
| Field | Option Key | Type | Input | Default | Validation | Description |
|---|---|---|---|---|---|---|
| Enable Automated FAQ Schema | enable_faq_schema |
bool |
checkbox |
false |
Boolean | Auto-inject FAQPage JSON-LD. Compatible with Yoast/RankMath. Disable if SEO plugin handles it. |
| Chat History Limit | chat_history_limit |
int |
number |
20 |
absint(), capped at 200, min 0 |
Messages stored per post. 0 = disable chat history. |
3. Tab: AI Models
Section 3.1 — Quick Presets
Three presets that populate the 6 model selectors below via JavaScript (not saved fields):
| Preset | Chat/Clarity/Planning | Writing | Refinement | Image | Est. Cost |
|---|---|---|---|---|---|
| Budget | Gemini 2.5 Flash | Mistral Small Creative | Gemini 2.5 Flash | FLUX.2 klein | ~$0.06/article |
| Balanced | Gemini 2.5 Flash | Claude 3.5 Sonnet | Claude 3.5 Sonnet | Riverflow V2 Max | ~$0.14/article |
| Premium | Gemini 3 Flash Preview | GPT-4.1 | GPT-4.1 | FLUX.2 max | ~$0.31/article |
Section 3.2 — OpenRouter Provider Routing
| Field | Option Key | Type | Input | Default | Description |
|---|---|---|---|---|---|
| Enable Provider Routing | openrouter_provider_routing_enabled |
bool |
checkbox |
false |
Pin OpenRouter requests to a specific provider for BYOK/routing. |
| Provider Slug | openrouter_provider_slug |
string |
text |
"auto" |
Examples: openai, anthropic, google, z-ai. |
| Only Use This Provider | openrouter_provider_only |
bool |
checkbox |
false |
Prevents Azure or other providers when slug is openai. |
| Allow Fallback Providers | openrouter_allow_provider_fallbacks |
bool |
checkbox |
false |
Leave off for BYOK-only behavior. |
Section 3.3 — AI Model Configuration (6 model selectors)
All selectors are populated via AJAX from the OpenRouter models API. Each selector shows which provider the model routes through.
| Field | Option Key | Default Model | data-model-type | Description |
|---|---|---|---|---|
| Chat Model | chat_model |
google/gemini-2.5-flash |
chat |
Discussion, research, recommendations |
| Clarity Model | clarity_model |
google/gemini-2.5-flash |
clarity |
Prompt analysis, quiz generation |
| Planning Model | planning_model |
google/gemini-2.5-flash |
planning |
Article outline generation |
| Writing Model | writing_model |
anthropic/claude-3.5-haiku |
execution |
Article draft generation (2-5k words) |
| Refinement Model | refinement_model |
anthropic/claude-3.5-sonnet |
execution |
Paragraph edits, rewrites, polish |
| Image Model | image_model |
openai/gpt-4o |
image |
Image generation |
- Writing Model has a legacy alias
execution_model(mapped towriting_modelduring sanitization). - Refresh Models button: AJAX call to
wpaw_refresh_models.
Section 3.4 — Custom Models
| Sub-field | Type | Input | Description |
|---|---|---|---|
| Model ID | string |
text |
Exact OpenRouter model ID. |
| Display Name | string |
text |
Optional friendly name. |
| Model Type | string |
select |
text or image |
| Remove | — | button |
Delete row. |
Stored in separate option: wp_agentic_writer_custom_models (array of {id, name, type} objects).
- Add button clones from a
<template>element. - Managed via AJAX:
wpaw_save_custom_model/wpaw_delete_custom_model.
Section 3.5 — Estimated Cost Per Article (read-only)
- Estimated cost calculated client-side based on selected models.
- Based on ~2K planning tokens, ~4K execution tokens, and 1 image.
- Updated dynamically when model selections change.
4. Tab: Local Backend
Section 4.1 — Step 1: Download (informational)
- Download link:
https://downloads.wpagentic.dev/wp-agentic-writer/agentic-writer-local-backend.zip - Expandable prerequisites section (Claude CLI, Node.js 18+, Z.ai Coding Plan)
Section 4.2 — Step 2: Configure Connection
| Field | Option Key | Type | Input | Required | Default | Description |
|---|---|---|---|---|---|---|
| Base URL | local_backend_url |
string |
url |
Yes | "" |
URL from Local Backend startup message. Sanitized via esc_url_raw(). |
| API Key | local_backend_key |
string |
text |
No | "dummy" |
Use "dummy" for local backend (ignored by proxy). |
| Model | local_backend_model |
string |
text |
No | "claude-local" |
Informational only. Proxy uses Claude CLI default. |
| Test Connection | (button) | — | button |
— | — | AJAX call to wpaw_test_local_backend. |
Section 4.3 — Step 3: Provider Routing (Advanced)
A table with 6 task types, each with a provider select:
| Task | Option Key Path | Available Providers | Default |
|---|---|---|---|
| Chat & Discussion | task_providers[chat] |
OpenRouter, Local Backend, Codex | openrouter |
| Clarity Check & Quiz | task_providers[clarity] |
OpenRouter, Local Backend, Codex | openrouter |
| Outline Planning | task_providers[planning] |
OpenRouter, Local Backend, Codex | openrouter |
| Article Writing | task_providers[writing] |
OpenRouter, Local Backend, Codex | openrouter |
| Content Refinement | task_providers[refinement] |
OpenRouter, Local Backend, Codex | openrouter |
| Image Generation | task_providers[image] |
OpenRouter only | openrouter |
Image task is restricted to OpenRouter only.
| Field | Option Key | Type | Input | Default | Description |
|---|---|---|---|---|---|
| Allow OpenRouter Fallback | allow_openrouter_fallback |
bool |
checkbox |
false |
Auto-fallback to OpenRouter when selected provider fails. Off by default to prevent unexpected charges. |
Section 4.4 — Step 4: Enable Web Search (informational)
- Guidance for setting up Brave Search on the local proxy.
- References
brave_search_api_keyfrom the General tab. - Provides copy-to-clipboard command for
.envfile, restart proxy command, and verification steps.
Section 4.5 — Troubleshooting (informational)
Static help content with common issues and commands.
5. Tab: MEMANTO
Description: Optional persistent memory for the AI writing assistant. The plugin works without it.
| Field | Option Key | Type | Input | Default | Description |
|---|---|---|---|---|---|
| Enable MEMANTO Integration | memanto_enabled |
bool |
checkbox |
false |
Store and recall memories across sessions. |
| MEMANTO Instance URL | memanto_url |
string |
url |
"" |
URL of MEMANTO instance. Sanitized via esc_url_raw(). |
| Moorcheh API Key | memanto_moorcheh_key |
string |
password |
"" |
Free API key at moorcheh.ai (10K vectors/month). |
| Test Connection | (button) | — | button |
— | AJAX call to wpaw_test_memanto. Disabled until both URL and key are filled. Auto-triggers on page load if both fields are filled. |
Connection status indicator:
- Shows: Not configured / Checking... / Connected / Error
- Displays detail text (service version, Moorcheh connection status)
6. Tab: OpenRouter Cost Log
This tab does NOT save settings. It is an analytics dashboard powered entirely by AJAX.
Section 6.1 — Cost Summary Dashboard
Four stats populated by AJAX wpaw_get_header_stats:
| Stat | Element ID | Description |
|---|---|---|
| All Time | #wpaw-stat-all-time |
Total OpenRouter cost ever |
| This Month | #wpaw-stat-monthly |
Current month's cost |
| Today | #wpaw-stat-today |
Today's cost |
| Avg Per Post | #wpaw-stat-avg |
All-time cost / total posts with usage |
Action Summary Table (#wpaw-action-summary-table): Cost breakdown per action type (Planning, Writing, Refinement, etc.) with columns: Action, Calls, Total Cost, Avg/Call.
Section 6.2 — Filters
| Filter | Element ID | Type | Options |
|---|---|---|---|
| Post ID | #wpaw-filter-post |
number |
Any post ID |
| Model | #wpaw-filter-model |
select |
Populated dynamically |
| Type | #wpaw-filter-type |
select |
Populated dynamically |
| Date From | #wpaw-filter-date-from |
date |
— |
| Date To | #wpaw-filter-date-to |
date |
— |
| Apply | #wpaw-apply-filters |
button |
— |
| Clear | #wpaw-clear-filters |
button |
— |
Section 6.3 — Detailed Cost Log Table
| Column | Description |
|---|---|
| Post Title | Linked post title with edit link |
| API Calls | Count of API calls for this post |
| Total OpenRouter Cost | Dollar amount |
Pagination: Server-side via AJAX wpaw_get_cost_log_data.
Per page selector: 10 / 25 (default) / 50 / 100.
Export CSV button: Client-side CSV generation from current filter results.
7. Tab: Model Guide (Read-Only)
Purely informational — no form fields.
7.1 — How AI Models Are Used
Table mapping each pipeline task to model type, estimated cost, and description.
7.2 — Recommended Models
Table of curated model recommendations with cost per 1M tokens and notes.
7.3 — Cost Examples
Three real-world cost examples:
- Single Article (Balanced): ~$0.10-0.15
- 10 Articles/Month (Balanced): ~$1.50-2.00
- With Web Search: ~$0.02-0.04 extra
8. Global Components
Writing Pipeline Progress Bar
- 5-step visual pipeline: Context → Planning → Writing → Refinement → Done
- Display-only component reflecting real-time writing status
- Element:
#wpaw-workflow-display
Save Bar
- Version display:
v{WP_AGENTIC_WRITER_VERSION} - Reset Defaults button:
#wpaw-reset-settings— restores all settings to defaults - Save Settings button: Form submit with keyboard shortcut (⌘+S / Ctrl+S)
Toast Notification
- Element:
#wpaw-toast/#wpaw-toast-message - For save/error notifications
9. AJAX Actions Reference
| Action | Method | Purpose | Tab |
|---|---|---|---|
wpaw_test_api_connection |
POST | Test OpenRouter API key validity | General |
wpaw_refresh_models |
POST | Fetch latest models from OpenRouter API | AI Models |
wpaw_save_custom_model |
POST | Save a custom model entry | AI Models |
wpaw_delete_custom_model |
POST | Delete a custom model entry | AI Models |
wpaw_get_cost_log_data |
POST | Paginated cost log data (server-side) | Cost Log |
wpaw_get_header_stats |
POST | Summary stats for cost dashboard | Cost Log |
wpaw_debug_models |
POST | Debug model configuration | AI Models |
wpaw_test_local_backend |
POST | Test local backend proxy connection | Local Backend |
wpaw_test_memanto |
POST | Test MEMANTO service connection | MEMANTO |
All AJAX calls use wpawSettingsV2.ajaxUrl and wpawSettingsV2.nonce.
10. Complete Option Key Index
All stored under wp_agentic_writer_settings unless noted.
| Option Key | Type | Default | Tab | Section |
|---|---|---|---|---|
openrouter_api_key |
string |
"" |
General | API Configuration |
brave_search_api_key |
string |
"" |
General | Research & Web Search |
monthly_budget |
float |
600 |
General | Budget & Cost Tracking |
cost_tracking_enabled |
bool |
true |
General | Budget & Cost Tracking |
web_search_enabled |
bool |
false |
General | Research & Web Search |
search_engine |
string |
"auto" |
General | Research & Web Search |
search_depth |
string |
"medium" |
General | Research & Web Search |
enable_clarification_quiz |
bool |
true |
General | Clarification Quiz |
clarity_confidence_threshold |
string |
"0.6" |
General | Clarification Quiz |
required_context_categories |
array |
All 7 categories | General | Clarification Quiz |
preferred_languages |
array |
["auto","English","Indonesian"] |
General | Content Settings |
custom_languages |
array |
[] |
General | Content Settings |
enable_faq_schema |
bool |
false |
General | Advanced Settings |
chat_history_limit |
int |
20 |
General | Advanced Settings |
chat_model |
string |
"google/gemini-2.5-flash" |
AI Models | Model Configuration |
clarity_model |
string |
"google/gemini-2.5-flash" |
AI Models | Model Configuration |
planning_model |
string |
"google/gemini-2.5-flash" |
AI Models | Model Configuration |
writing_model |
string |
"anthropic/claude-3.5-haiku" |
AI Models | Model Configuration |
refinement_model |
string |
"anthropic/claude-3.5-sonnet" |
AI Models | Model Configuration |
image_model |
string |
"openai/gpt-4o" |
AI Models | Model Configuration |
openrouter_provider_routing_enabled |
bool |
false |
AI Models | Provider Routing |
openrouter_provider_slug |
string |
"auto" |
AI Models | Provider Routing |
openrouter_provider_only |
bool |
false |
AI Models | Provider Routing |
openrouter_allow_provider_fallbacks |
bool |
false |
AI Models | Provider Routing |
local_backend_url |
string |
"" |
Local Backend | Connection |
local_backend_key |
string |
"dummy" |
Local Backend | Connection |
local_backend_model |
string |
"claude-local" |
Local Backend | Connection |
task_providers |
array |
[] (all default to openrouter) |
Local Backend | Provider Routing |
allow_openrouter_fallback |
bool |
false |
Local Backend | Provider Routing |
memanto_enabled |
bool |
false |
MEMANTO | Integration |
memanto_url |
string |
"" |
MEMANTO | Integration |
memanto_moorcheh_key |
string |
"" |
MEMANTO | Integration |
Separate option: wp_agentic_writer_custom_models — array of {id: string, name: string, type: "text"|"image"}.
11. Sanitization & Validation Rules
| Field | Sanitization | Validation |
|---|---|---|
openrouter_api_key |
trim() |
— |
brave_search_api_key |
trim() |
— |
chat_model |
sanitize_text_field() |
Falls back to Model_Registry::get_default_model('chat') |
clarity_model |
sanitize_text_field() |
Falls back to registry default |
planning_model |
sanitize_text_field() |
Falls back to registry default |
writing_model |
sanitize_text_field() |
Falls back to registry default; also maps legacy execution_model |
refinement_model |
sanitize_text_field() |
Falls back to registry default |
image_model |
sanitize_text_field() |
Falls back to registry default |
web_search_enabled |
Boolean check === "1" |
— |
cost_tracking_enabled |
Boolean check === "1" |
— |
enable_clarification_quiz |
Boolean check === "1" |
— |
enable_faq_schema |
Boolean, defaults false |
— |
allow_openrouter_fallback |
Boolean check === "1" |
— |
openrouter_provider_routing_enabled |
Boolean check === "1" |
— |
openrouter_provider_only |
Boolean check === "1" |
— |
openrouter_allow_provider_fallbacks |
Boolean check === "1" |
— |
openrouter_provider_slug |
sanitize_key(), empty → "auto" |
— |
search_engine |
Whitelist: auto, native, exa |
Invalid → "auto" |
search_depth |
Whitelist: low, medium, high |
Invalid → "medium" |
monthly_budget |
floatval() |
Default 600 if not set |
chat_history_limit |
absint(), capped at 200 |
Default 20 if not set |
clarity_confidence_threshold |
Whitelist: 0.5, 0.6, 0.7, 0.8, 0.9 |
Invalid → "0.6" |
required_context_categories |
array_intersect() with 7 valid values |
Defaults to all 7 |
preferred_languages |
array_map('sanitize_text_field') |
Default ["auto","English","Indonesian"] |
custom_languages |
array_map('sanitize_text_field') + array_filter() |
Default [] |
local_backend_url |
esc_url_raw(trim()) |
— |
local_backend_key |
sanitize_text_field(trim()) |
— |
local_backend_model |
sanitize_text_field(trim()) |
— |
memanto_enabled |
Boolean check === "1" |
— |
memanto_url |
esc_url_raw(trim()) |
— |
memanto_moorcheh_key |
sanitize_text_field(trim()) |
— |
task_providers |
Nested sanitization | Task must be in whitelist, provider must be in whitelist, image restricted to openrouter |
12. Key Files Reference
| File | Purpose |
|---|---|
includes/class-settings-v2.php |
Active settings controller (registration, sanitization, AJAX, view data prep) |
includes/class-model-registry.php |
Centralized model defaults, labels, and fallbacks |
includes/class-settings.php |
Legacy settings class (deprecated, kept for reference) |
views/settings/layout.php |
Main layout wrapper |
views/settings/tab-general.php |
General tab view |
views/settings/tab-models.php |
AI Models tab view |
views/settings/tab-local-backend.php |
Local Backend tab view |
views/settings/tab-memanto.php |
MEMANTO tab view |
views/settings/tab-cost-log.php |
Cost Log tab view |
views/settings/tab-guide.php |
Model Guide tab view (read-only) |
Generated from codebase analysis on 2026-06-08. Plugin version as defined by WP_AGENTIC_WRITER_VERSION.