docs: FileView.setText writes nothing for empty text on an unloaded path

Found from use: a note saved with an empty body got an index entry and no
file, because setText with an empty string on a path the view has not loaded
creates nothing and reports no error, with or without atomicWrites.

While confirming that, the neighbouring note turned out to be wrong too:
blockLoading does not make reload() synchronous. Measured on a regular file
and on /proc/stat, reload() then text() returned the contents from before
the reload, and only waitForJob() between them returned the new ones. The
FileView docs say the same. Perf.qml reloads and reads without waitForJob,
so a sample reads the previous interval; not changed here.

1 files changed, 15 insertions, 5 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 4d7b35c..7569df5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -166,6 +166,12 @@ changing that component. The ones that generalise:
   has no mkdir step. `Quickshell.stateDir` is a per-shell hashed directory
   (`by-shell/<hash>`), not `~/.local/state/quickshell`, which is why the
   preferences path is built from `XDG_STATE_HOME` instead.
+- **`FileView.setText("")` on a path that view has not loaded writes no file at
+  all and reports no error**, with or without `atomicWrites` (measured).
+  `Prefs.qml` never hits it because JSON is never empty; a note body can be, and
+  one landed in `db.json` with no file beside it. Content that may be empty goes
+  through a `Process` running `cat > <file>` with the text on stdin, whose exit
+  code is the outcome; `notes` writes bodies that way.
 - **khal 0.11 has no JSON output**, which is why the calendar reads the vdir
   itself through `desktop/island/calendar/calctl` rather than parsing `khal
   list -f`. A month list over the 281 live event files measured 0.11s. khal
@@ -176,11 +182,15 @@ changing that component. The ones that generalise:
 - **Use `/usr/bin/python3` for calctl and its test.** `python3` on PATH is a
   pyenv shim without `icalendar`; the system interpreter has it, for
   cal-notif.
-- **`FileView` reads `/proc` and `/sys` fine, but only on `reload()`.** With
-  `blockLoading: true`, `text()` straight after `reload()` is the fresh
-  contents, which is how `Perf.qml` samples `/proc/stat` and hwmon every 2s
-  without a subprocess. hwmon numbers move across boots; look chips up by
-  their `name` file.
+- **`FileView` reads `/proc` and `/sys` fine, but only on `reload()`.** The
+  reload is what matters, not `blockLoading`: measured, `reload()` then `text()`
+  returned the contents from *before* the reload, for a regular file and for
+  `/proc/stat` alike, and only `waitForJob()` between them returned the new ones
+  (the docs agree: `reload()` will not block if `blockLoading` is set, only
+  `blockAllReads` will). `Perf.qml` reloads and reads without it, so a sample
+  reads the previous interval's numbers; `notes` writes `reload()` +
+  `waitForJob()`. hwmon numbers move across boots; look chips up by their `name`
+  file.
 - **A hot reload does not resize an existing layer surface.** Raising the
   island's `implicitHeight` from 360 to 480 reloaded cleanly while `hyprctl
   layers` still reported `h: 360` and the performance panel stayed cut off;