docs: improved fs_patch and fs_write descriptions and examples

assets/functions/tools/fs_patch.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 set -e
 
-# @describe Apply a patch to a file at the specified path.
-# This can be used to edit a file without having to rewrite the whole file.
+# @describe Apply a unified-diff patch to a file at the specified path. Use this for editing an existing file. It's the
+# PREFERRED way to modify a file. Prefer this over fs_write whenever the file already exists: it sends less data,
+# preserves unchanged content automatically, and is less prone to accidental data loss from full rewrites.
+# Use fs_write only when you are creating a new file or doing a complete rewrite where most of the content changes.
 
 # @option --path! The path of the file to apply the patch to
 # @option --contents! The patch to apply to the file