wp-agentic-writer/docs/SETTINGS_PAGE_SPECIFICATION.md

WP Agentic Writer — Settings Page Specification

Purpose: Complete reference for rebuilding the wp-admin settings page.
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 (for settings_fields()): wp_agentic_writer_settings.
Form action: options.php.

---

Table of Contents

1. Page Layout Overview
2. Tab: General
3. Tab: AI Models
4. Tab: Local Backend
5. Tab: MEMANTO
6. Tab: OpenRouter Cost Log
7. Tab: Model Guide (Read-Only)
8. Global UI Components
9. AJAX Actions Reference
10. Complete Option Key Index
11. Sanitization & Validation Rules

---

1. Page Layout Overview

The settings page uses a sidebar + content pane layout (IDE-style split view).

┌──────────────────┬─────────────────────────────────────┐
│  Sidebar Nav     │  Content Pane (scrollable)          │
│                  │                                     │
│  [Plugin Logo]   │  ┌───────────────────────────────┐  │
│                  │  │ Writing Pipeline Progress Bar  │  │
│  CONFIGURATION   │  └───────────────────────────────┘  │
│  ○ General       │                                     │
│  ○ AI Models     │  ┌───────────────────────────────┐  │
│  ○ Local Backend │  │ Active Tab Content            │  │
│  ○ MEMANTO       │  │                               │  │
│                  │  │                               │  │
│  ANALYTICS&DOCS  │  └───────────────────────────────┘  │
│  ○ Cost Log      │                                     │
│  ○ Model Guide   │  ┌───────────────────────────────┐  │
│                  │  │ [Reset] [Save Settings ⌘+S]   │  │
│                  │  └───────────────────────────────┘  │
└──────────────────┴─────────────────────────────────────┘

• Framework: Bootstrap 5 (loaded by the plugin via CDN or bundled)
• Icons: Bootstrap Icons (bi-*) + WordPress Dashicons
• Theme: Dark theme with accent colors
• Select2: Used for model selection dropdowns (searchable)
• Sticky save bar at the bottom with version display, Reset, and Save buttons
• Toast notifications for save confirmations

Navigation Tabs

Tab ID	Label	Icon	Section
general	General	bi-sliders	Configuration
models	AI Models	bi-stars	Configuration
local-backend	Local Backend	bi-house-fill	Configuration
memanto	MEMANTO	bi-cpu	Configuration
cost-log	OpenRouter Cost Log	bi-graph-up	Analytics & Docs
guide	Model Guide	bi-book	Analytics & Docs

---

2. Tab: General

Description: "Configure global API keys, budget, and content parameters."

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 (marked *)	""	Get from openrouter.ai/keys. Placeholder: sk-or-v1-...
Test Connection	(button)	—	button	—	—	AJAX call to wpaw_test_api_connection. Shows spinner + result badge.

Section 2.2 — OpenRouter Budget & Cost Tracking

Displays a 3-column dashboard before the input fields:

Display Card	Variable	Source
Used This Month	$monthly_used	Cost_Tracker::get_monthly_total()
Budget Usage (progress bar)	$budget_percent	Calculated: (used/budget)*100
Remaining	Calculated	max(0, budget - used)

Progress bar color: success (<70%), warning (70-90%), danger (>90%).

Field	Option Key	Type	Input	Default	Validation	Description
Monthly Budget (USD)	monthly_budget	float	number with $ prefix	600	floatval(), min 0, step 0.01	Maximum spend per month. 0 = unlimited.
Enable Cost Tracking	cost_tracking_enabled	bool	checkbox (switch)	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 (switch)	false	—	Default for new posts. Can also be toggled per-request in editor sidebar.
Search Depth	search_depth	string	select	"medium"	low / medium / high	Controls search depth level.

Two-column sub-section:

Left — 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.

Right — Brave Search API (for Local/Codex):

Field	Option Key	Type	Input	Default	Description
Brave Search API Key	brave_search_api_key	string	password	""	Used automatically when active model is Local Backend or Codex. Placeholder: BSA.... Free at brave.com/search/api (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 (switch)	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 (scrollable box, max-height 200px)	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 grid (2 cols on mobile, 4 on md+)	["auto", "English", "Indonesian"]	Languages shown in the language selector when creating articles.

Available language options (24 total):

Value	Label
auto	Auto-detect
English	English
Indonesian	Indonesian (Bahasa Indonesia)
Javanese	Javanese (Basa Jawa)
Sundanese	Sundanese (Basa Sunda)
Spanish	Spanish (Español)
French	French (Français)
Arabic	Arabic (العربية)
Chinese	Chinese (中文)
Japanese	Japanese (日本語)
Portuguese	Portuguese (Português)
German	German (Deutsch)
Hindi	Hindi (हिंदी)
Korean	Korean (한국어)
Vietnamese	Vietnamese (Tiếng Việt)
Thai	Thai (ไทย)
Tagalog	Tagalog
Malay	Malay (Bahasa Melayu)
Russian	Russian (Русский)
Italian	Italian (Italiano)
Dutch	Dutch (Nederlands)
Polish	Polish (Polski)
Turkish	Turkish (Türkçe)
Swedish	Swedish (Svenska)

Field	Option Key	Type	Input	Default	Description
Custom Languages	custom_languages	array	Dynamic text input list with add/remove buttons	[]	Add any language not listed above (e.g., regional dialects). Placeholder: e.g., Betawi, Minangkabau.

Section 2.6 — Advanced Settings

Field	Option Key	Type	Input	Default	Validation	Description
Enable Automated FAQ Schema	enable_faq_schema	bool	checkbox (switch)	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 (max-width 120px)	20	absint(), capped at 200, min 0	Messages stored per post. 0 = disable chat history.

---

3. Tab: AI Models

Description: "Select logic engines for different stages of the writing pipeline."

Section 3.1 — Quick Presets (3 clickable cards)

These are not saved fields — they populate the 6 model selects below via JavaScript.

Preset	Cost	Chat/Clarity/Planning	Writing	Refinement	Image
Budget	~$0.06/article	Gemini 2.5 Flash	Mistral Small Creative	Gemini 2.5 Flash	FLUX.2 klein
Balanced ⭐	~$0.14/article	Gemini 2.5 Flash	Claude 3.5 Sonnet	Claude 3.5 Sonnet	Riverflow V2 Max
Premium	~$0.31/article	Gemini 3 Flash Preview	GPT-4.1	GPT-4.1	FLUX.2 max

Section 3.2 — OpenRouter Provider Routing (collapsible sub-section)

Field	Option Key	Type	Input	Default	Description
Enable Provider Routing	openrouter_provider_routing_enabled	bool	checkbox (switch)	false	Pin OpenRouter requests to a specific provider for BYOK/routing.
Provider Slug	openrouter_provider_slug	string	text (small)	"auto"	Examples: openai, anthropic, google, z-ai. Sanitized via sanitize_key().
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 use Select2 searchable dropdowns populated via AJAX from the OpenRouter models API. Each has a provider badge (OpenRouter / Local Backend / Codex) showing which provider the model routes through.

Field	Option Key	Badge	Default Model	data-model-type	Description
Chat Model	chat_model	Discussion (info)	google/gemini-2.5-flash	chat	Discussion, research, recommendations
Clarity Model	clarity_model	Analysis (info)	google/gemini-2.5-flash	clarity	Prompt analysis, quiz generation
Planning Model	planning_model	Outline (info)	google/gemini-2.5-flash	planning	Article outline generation
Writing Model	writing_model	Main Writer (primary)	anthropic/claude-3.5-haiku	execution	Article draft generation (2-5k words)
Refinement Model	refinement_model	Editing (info)	anthropic/claude-3.5-sonnet	execution	Paragraph edits, rewrites, polish
Image Model	image_model	Visual (warning)	openai/gpt-4o	image	Image generation

Note: Writing Model has a legacy alias execution_model (mapped to writing_model during sanitization).

Refresh Models button: #wpaw-refresh-models — AJAX call to wpaw_refresh_models.

Section 3.4 — Custom Models

Sub-field	Type	Input	Description
Model ID	string	text	Exact OpenRouter model ID. Placeholder: model-provider/model-name
Display Name	string	text	Optional friendly name. Placeholder: Display Name (optional)
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: #wpaw-add-custom-model — clones from <template id="wpaw-custom-model-template">.
• Remove button: .wpaw-remove-custom-model — removes the row.
• Managed via AJAX: wpaw_save_custom_model / wpaw_delete_custom_model.

Section 3.5 — Estimated Cost Per Article (display only)

A dark box showing:

• 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

Description: "Configure connections to local LM Studio or Ollama instances."

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. Placeholder: http://192.168.1.105:8080. Sanitized via esc_url_raw().
API Key	local_backend_key	string	text	No	"dummy"	Use "dummy" for local backend (ignored by proxy). Placeholder: dummy.
Model	local_backend_model	string	text	No	"claude-local"	Informational only. Proxy uses Claude CLI default. Placeholder: claude-local.
Test Connection	(button)	—	button	—	—	AJAX call to wpaw_test_local_backend. Shows spinner + result.

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

Note: Image task is restricted to OpenRouter only. Text tasks also get Local Backend and Codex options.

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 (Optional / Informational)

This section is mostly informational guidance for setting up Brave Search on the local proxy. It references the brave_search_api_key from the General tab and provides:

• Copy-to-clipboard command for .env file
• Restart proxy command
• Verification steps

Section 4.5 — Troubleshooting (informational)

Static help content with common issues and commands.

---

5. Tab: MEMANTO

Description: "Optional persistent memory for your AI writing assistant. The plugin works perfectly without it."

Fields

Field	Option Key	Type	Input	Default	Description
Enable MEMANTO Integration	memanto_enabled	bool	checkbox (switch)	false	Store and recall memories across sessions. Optional enhancement.
MEMANTO Instance URL	memanto_url	string	url	""	URL of MEMANTO instance. Placeholder: https://your-instance.context.wpagentic.dev. Sanitized via esc_url_raw().
Moorcheh API Key	memanto_moorcheh_key	string	password	""	Get free API key at moorcheh.ai (10K vectors/month). autocomplete="new-password".
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:

• #memanto-status-indicator — badge showing: Not configured / Checking... / 🟢 Connected / 🔴 Error
• #memanto-status-detail — detail text (service version, Moorcheh connection status)

Info box: Static content explaining MEMANTO features (memory across sessions, context loss elimination, 63% token reduction).

---

6. Tab: OpenRouter Cost Log

Description: "Track API token usage and expenses across all generations."

This tab does NOT save settings. It's an analytics dashboard powered entirely by AJAX.

Section 6.1 — Cost Summary Dashboard

Four stat cards (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): Shows 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 (50% width)	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
• Element: #wpaw-pagination

Export CSV button: #wpaw-export-csv — client-side CSV generation from current filter results.

---

7. Tab: Model Guide (Read-Only)

Purely informational — no form fields. Contains three reference sections:

7.1 — How AI Models Are Used

Table mapping each pipeline task → model type → estimated cost → description.

7.2 — Recommended Models

Table of curated model recommendations with cost per 1M tokens and notes.

7.3 — Cost Examples

Three example cards showing real-world costs:

• 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 UI Components

Writing Pipeline Progress Bar (top of content pane)

A visual pipeline showing 5 steps: Context → Planning → Writing → Refinement → Done.
Element: #wpaw-workflow-display. This is a display-only component that reflects real-time writing status.

Fixed Save Bar

Element	Description
Version display	v{WP_AGENTIC_WRITER_VERSION} with plugin icon
Reset Defaults button	#wpaw-reset-settings — restores all settings to defaults
Save Settings button	Form submit with keyboard shortcut indicator (⌘+S on Mac, Ctrl+S on Windows)

Toast Notification

• Element: #wpaw-toast / #wpaw-toast-message
• Bootstrap toast component 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

---

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 (sidebar + content + save bar)
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.