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

assets/functions/tools/fs_write.sh

@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
 set -e
 
-# @describe Write the full file contents to a file at the specified path.
+# @describe Write the FULL file contents to a file at the specified path. Use this for NEW files or COMPLETE rewrites
+# only. For editing an existing file, prefer fs_patch. It's a surgical edit that preserves unchanged content, requires
+# sending less data, and is less prone to accidental data loss.
 
 # @option --path! The path of the file to write to
 # @option --contents! The full contents to write to the file