Docs

docs/usage.md

@@ -661,6 +661,34 @@ The action takes no options, its presence is what enables remote OCR for a match
 If the remote engine is not configured, or does not support the document's file type, the document is
 processed locally instead and a warning is written to the log.
 
+##### Apply AI Suggestions {#workflow-action-apply-ai-suggestions}
+
+"Apply AI Suggestions" actions ask the configured AI service for title and metadata suggestions,
+the same as the AI suggestions shown on the document detail page, except applied automatically and in bulk.
+It requires [AI features](configuration.md#ai) to be enabled. You can specify:
+
+- Which suggestions to apply: title, tags, correspondent, document type, storage path and / or created
+  date. Suggestions for fields you did not select are discarded.
+- Whether to create missing items. By default only tags, correspondents and document types that
+  already exist are assigned and any other suggestion is dropped. With this enabled, suggested items
+  that do not exist are created. Storage paths are never created.
+- Whether to overwrite existing values. By default a field is only filled in if it is currently empty.
+  Note that documents almost always already have a title and created date, so if you select those you
+  will usually want to enable this too. Tags are an exception: suggested tags are always added and
+  never replace the document's existing tags.
+
+The action works with every trigger **except Consumption Started**, because suggestions are made from
+the document's text, which does not exist until after the document has been processed.
+
+Because the query to the AI service is slow, the action is queued and runs in the background rather
+than as part of the workflow run itself. The document is updated once the suggestions come back.
+
+!!! warning
+
+    Every matching document results in a query to the AI service, which may incur costs and have privacy
+    implications. Be careful when adding this action to a workflow with a **Scheduled** trigger or a
+    broad filter that could run over a large quantity of documents.
+
 #### Workflow placeholders
 
 Titles and webhook payloads can be generated by workflows using [Jinja templates](https://jinja.palletsprojects.com/en/3.1.x/templates/).