@@ -52,7 +52,7 @@
 
 #### Temperature and Provider Options
 - `temperature` is only used for LLM translation providers. It controls the creativity of AI-generated translations. If omitted, the provider's default is used.
-- `providerOptions` is a JSON object for advanced, provider-specific settings (such as enabling special modes or features). If provided, these options override any built-in defaults for the provider. See the [Vercel AI SDK documentation](https://ai-sdk.dev/providers/ai-sdk-providers) or your provider's official docs for supported options.
+- `providerOptions` is a JSON object for advanced, provider-specific settings (such as enabling special modes or features). Empty provider options (`{}`) explicitly means "no options" rather than falling back to any defaults. See the [Vercel AI SDK documentation](https://ai-sdk.dev/providers/ai-sdk-providers) or your provider's official docs for supported options.
 
 ### Referencing Providers
 Providers are referenced by their `id` (not `name`) in each feature's configuration. Each feature (translate, selection toolbar, input translation, video subtitles, vocabulary insight) independently selects its own provider, for example:
@@ -110,7 +110,8 @@
 - **Feature assignment badge:** Each provider card displays a badge showing the number of features assigned to it (e.g., "2 features") using the i18n key `options.apiProviders.badges.featureCount`. Hovering over the badge displays a tooltip listing all assigned features by their localized names. The badge count includes Language Detection assignments (when mode is LLM and the provider is selected). This badge replaces the previous "Translate" badge that indicated the default translation provider.
 - **Configure advanced options for LLM translation providers:** For providers that support LLM-based translation, an "Advanced Options" collapsible section is available in the provider config form. This section includes:
   - **Temperature**: A numeric input controlling the randomness/creativity of AI-generated translations. Lower values (e.g., 0) are more deterministic; higher values are more creative. Leave empty to use the provider's default.
-  - **Provider Options**: A JSON code editor for entering provider-specific advanced options (such as enabling special API features). The editor supports syntax highlighting, validation, and shows provider-specific defaults as placeholder text. A link to the Vercel AI SDK documentation is provided for reference. Invalid JSON is highlighted and an error message is shown.
+  - **Provider Options**: A JSON code editor for entering provider-specific advanced options (such as enabling special API features). The editor supports syntax highlighting and validation. Invalid JSON is highlighted and an error message is shown. A link to the Vercel AI SDK documentation is provided for reference.
+  - **Provider Options Recommendations**: For models that have recommended provider options, a sparkles icon appears next to the model selector. Clicking this icon opens a popover showing the recommended JSON configuration for the selected model. Users can review the recommendation and manually click "Apply" to apply these options to their configuration. The sparkles icon briefly highlights when a model is first selected that matches a recommendation. Empty provider options remain empty unless the user explicitly applies a recommendation—the system does not auto-apply recommended options.
 
 Configuration changes are managed reactively using Jotai atoms, ensuring that updates in the UI are immediately reflected in the underlying configuration. **All configuration changes, including drag-and-drop reordering, are applied optimistically in the UI and are written to storage in a serialized, race-condition-safe manner. The scroll position remains stable after reordering.**
 
@@ -154,7 +155,8 @@
 5. Select the desired model from the dropdown, or toggle "use custom model" and enter a custom model name. **For custom (OpenAI-compatible) providers, you can click the "Fetch available models" button next to the custom model input to retrieve and select a model from the provider's `/models` endpoint.** This requires both a valid baseURL and API key. The available models will be shown in a popover; selecting one will auto-fill the custom model field. For MiniMax, select from `MiniMax-M2` or `MiniMax-M2-Stable`. For Alibaba Cloud, available models include `qwen3-max`, `qwen3.5-plus`, `qwen3.5-flash`, and others. For Moonshot AI, available models include `kimi-k2`, `kimi-k2.5`, and various thinking models. For Hugging Face, popular models include `Qwen/Qwen3-32B`, `meta-llama/Llama-3.3-70B-Instruct`, `deepseek-ai/DeepSeek-V3.1`, and others. (Note: Edge TTS does not use models; it uses voice configurations instead.)
 6. **(For LLM translation providers only)**: Expand the **Advanced Options** section to configure:
     - **Temperature**: Enter a value to control the randomness/creativity of AI-generated translations. Lower values (e.g., 0) are more deterministic; higher values are more creative. Leave empty to use the provider's default.
-    - **Provider Options**: Enter provider-specific advanced options as JSON. The editor validates your input and shows provider-specific defaults as a placeholder. A link to the Vercel AI SDK documentation is provided for reference.
+    - **Provider Options**: Enter provider-specific advanced options as JSON. The editor validates your input. A link to the Vercel AI SDK documentation is provided for reference.
+    - **Recommendations**: If your selected model has recommended provider options, a sparkles icon appears next to the model selector. Click it to preview the recommended configuration, then manually click "Apply" to use these options.
 7. **(Optional)**: Expand the **Feature Providers** section to assign features to this provider. Toggle ON any feature you want to use with this provider. Toggles that are disabled indicate features already assigned to this provider.
 8. **Click the "Test Connection" button to verify connectivity.**
     - For most providers, if the API key is empty, the button is disabled.

@@ -13,6 +13,30 @@
 - `apiKeyRequired`: Prompt to add an API key before fetching models
 - `searchModels`: Placeholder for the model search input (added for the searchable combobox)
 - `noModelsFound`: Message shown when no models match the search (added for the searchable combobox)
+
+#### Provider Options Recommendation Keys
+Provider configuration forms include a recommendation feature for model-specific provider options. These keys appear next to the model selector and enable users to preview and manually apply recommended options. The keys are under `options.apiProviders.form`:
+
+- **`providerOptionsRecommendationTrigger`**: Tooltip for the sparkles button that opens the recommendation popover (appears next to model selector)
+- **`providerOptionsRecommendationTitle`**: Title of the recommendation dialog/popover
+- **`providerOptionsRecommendationDescription`**: Description text explaining what the recommended options are for
+- **`providerOptionsRecommendationApply`**: Label for the "Apply" button to apply recommended options
+- **`providerOptionsRecommendationApplied`**: Label for the button after recommendations have been applied (applied state)
+
+**Example:**
+
+```yaml
+options:
+  apiProviders:
+    form:
+      providerOptionsRecommendationTrigger: View recommended provider options
+      providerOptionsRecommendationTitle: Recommended provider options detected
+      providerOptionsRecommendationDescription: Review and manually apply the recommended configuration.
+      providerOptionsRecommendationApply: Apply
+      providerOptionsRecommendationApplied: Applied
+```
+
+These keys support the manual provider options recommendation feature introduced in PR #1152, which replaced automatic runtime application with a user-controlled preview and apply workflow.
 
 When adding a new translation mode, add a new key under `options.translation.translationMode.mode` in every locale file, with a localized label for each mode.
 
@@ -943,6 +967,7 @@
 - **PR #1121**: Updated improve writing template prompt with {{originLanguage}} detection, 4-point language policy (previously 3 points), and revised example format with language annotations; replaced Example B with Japanese original text demonstrating verb conjugation errors
 - **PR #1127**: Added localized provider descriptions for three new AI providers (alibaba, moonshotai, huggingface) across all 8 supported languages
 - **PR #1126**: Added selection toolbar opacity configuration with 2 new keys under `options.floatingButtonAndToolbar.selectionToolbar.opacity` to control transparency of the toolbar and popovers
+- **PR #1152**: Added provider options recommendation keys with 5 new keys under `options.apiProviders.form.providerOptionsRecommendation*` to support manual preview and application of recommended provider options
 
 ### Example: Adding a New Provider Group
 **English:**