dwindown/wp-agentic-writer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Cleanup git state - commit all staged changes

Browse Source 
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.
This commit is contained in:
Dwindi Ramadhana
2026-06-17 05:27:58 +07:00
parent d3f142222c
commit 690991c526
7963 changed files with 941566 additions and 67372 deletions
Download Patch File Download Diff File Expand all files Collapse all files

515
docs/SETTINGS_PAGE_SPECIFICATION.md Normal file
View File

@@ -0,0 +1,515 @@
# 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](#1-page-layout-overview)
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 UI Components](#8-global-ui-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)
---
## 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](https://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](https://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](https://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`.*