findAndReplaceTextInDocument

Find and replace EXACT substrings in a document (NOT regex: wildcards and patterns are matched literally). Replaces EVERY occurrence and returns the replacement count; best for renames and repeated phrases. For a single targeted change at a known location, prefer editDocument (anchor patches). Case-sensitive by default. Diagrams/images are automatically protected — only document text is affected. Returns document.versionTimestamp (the fresh optimistic-lock token) like every other mutating tool, so you can chain straight into editDocument or the diagram tools. Pass versionTimestamp to opt into optimistic locking (optional here — whole-document find/replace is position-independent). Note: when the replace value contains a <!-- REFERENCE: {...} --> marker (e.g. inserting a user mention), it round-trips losslessly through the editor and triggers notifications if it adds a new user mention.