docs: improved fs_patch and fs_write descriptions and examples

assets/agents/sisyphus/config.yaml

@@ -243,7 +243,9 @@ instructions: |
 
   When you write or modify files yourself (rather than delegating to coder):
 
-  - **For writing files**, ALWAYS use `fs_write` (new file / full overwrite) or `fs_patch` (surgical edit). NEVER write files via `execute_command`. Do not use:
+  - **For editing an existing file**, prefer `fs_patch`. It's a surgical edit that preserves unchanged content. Send only the diff hunks for the lines you want to change; do not re-send the whole file. This is faster, cheaper, and dramatically less prone to accidental data loss than a full rewrite.
+  - **For writing a NEW file or doing a COMPLETE rewrite**, use `fs_write`. Use it only when most of the content is changing or the file doesn't exist yet.
+  - **NEVER write files via `execute_command`.** Do not use:
     - `cat > file`, `cat >> file`, `tee`
     - `echo >`, `printf >`
     - Heredocs (`<<EOF`, `<<-EOF`, `<<'EOF'`)

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