docs: update documentation for OCROptions plugin interface migration

Co-authored-by: aider (openrouter/anthropic/claude-sonnet-4) <aider@aider.chat>

docs/api.md

@@ -117,3 +117,15 @@ handler. OCRmyPDF will clean up its temporary files and worker processes
 automatically when an exception occurs.
 
 When OCRmyPDF succeeds conditionally, it returns an integer exit code.
+
+### Plugin Development Changes
+
+Starting in OCRmyPDF v16.13.0, the plugin interface has been updated:
+
+- Plugin hooks now receive `OCROptions` objects instead of `argparse.Namespace`
+- `OCROptions` provides the same attribute access as `Namespace` (duck-typing compatible)
+- Plugin developers should update type hints: `from ocrmypdf._options import OCROptions`
+- Built-in plugins no longer modify options in-place for better immutability
+
+Most existing plugins will continue working without modification due to the
+duck-typing compatibility between `OCROptions` and `Namespace`.

docs/apiref.md

@@ -13,6 +13,13 @@ should be mainly of interest to plugin developers.
     :members:
 ```
 
+## ocrmypdf._options
+
+```{eval-rst}
+.. automodule:: ocrmypdf._options
+    :members: OCROptions
+```
+
 ## ocrmypdf.exceptions
 
 ```{eval-rst}

docs/plugins.md

@@ -164,6 +164,13 @@ chaining operations.
 .. autofunction:: ocrmypdf.pluginspec.check_options
 ```
 
+:::{note}
+**Plugin Interface Change**: Starting in OCRmyPDF v16.13.0, plugin hooks receive 
+`OCROptions` objects instead of `argparse.Namespace` objects. Most plugins will 
+continue working due to duck-typing compatibility, but plugin developers should 
+update their type hints accordingly.
+:::
+
 ### Execution and progress reporting
 
 ```{eval-rst}

docs/release_notes.md

@@ -25,6 +25,32 @@ about a forthcoming release that has not been tagged yet. A release is only
 official when it's tagged and posted to PyPI.
 :::
 
+## v16.13.0
+
+**Breaking changes**
+
+- **Plugin interface migration**: Plugin hooks now receive `OCROptions` objects instead of 
+  `argparse.Namespace` objects. Most plugins will continue working due to duck-typing 
+  compatibility, but plugin developers should update their type hints from `Namespace` 
+  to `OCROptions`.
+- Built-in plugins no longer modify options in-place, improving immutability and 
+  code clarity.
+
+**API improvements**
+
+- Centralized validation logic in the `OCROptions` Pydantic model
+- Removed scattered option mutation throughout the codebase
+- Better type safety for plugin development
+- Simplified plugin option handling
+
+**Migration guide for plugin developers**
+
+- Update imports: `from ocrmypdf._options import OCROptions`
+- Update type hints: `def check_options(options: OCROptions)` instead of `options: Namespace`
+- Attribute access remains unchanged: `options.languages`, `options.output_type`, etc.
+- Remove any in-place option modifications - compute values at point of use instead
+- Most existing plugins will continue working without changes due to duck-typing
+
 ## v16.12.0
 
 - Disable Ghostscript's subset fonts feature, which was found to corrupt text in