wp-agentic-writer/docs/SETTINGS_PAGE_FEATURES.md

# 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

1. [Navigation Tabs](#1-navigation-tabs)
2. [Tab: General](#2-tab-general)
3. [Tab: AI Models](#3-tab-ai-models)
4. [Tab: Local Backend](#4-tab-local-backend)
5. [Tab: MEMANTO](#5-tab-memanto)
6. [Tab: OpenRouter Cost Log](#6-tab-openrouter-cost-log)
7. [Tab: Model Guide (Read-Only)](#7-tab-model-guide-read-only)
8. [Global Components](#8-global-components)
9. [AJAX Actions Reference](#9-ajax-actions-reference)
10. [Complete Option Key Index](#10-complete-option-key-index)
11. [Sanitization & Validation Rules](#11-sanitization--validation-rules)
12. [Key Files Reference](#12-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 to `writing_model` during 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_key` from the General tab.
- Provides copy-to-clipboard command for `.env` file, 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`.*