docs(status): document the module and record its traps

A FileView fires its own fileChanged on setText, so a handler that writes
in response to a change loops unless it compares first. IdleInhibitor has
no window of its own and does nothing without one, so the singleton is
handed the keepalive window by shell.qml.

Both were read from the documentation while designing and confirmed while
implementing.

1 files changed, 17 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 1b6e8a8..963bda2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -212,6 +212,23 @@ changing that component. The ones that generalise:
   inhibitor it asserts a second, independent one, so idle resumes only when
   both release. Replace it with a `custom/` module reading the owning
   component's state.
+- **A `FileView` that writes the file it watches sees its own write.**
+  `watchChanges` fires `fileChanged` on `setText()` as well as on an external
+  change, so a handler that writes in response to a change loops. The status
+  registry compares the reparsed value against the current one and assigns
+  only on a difference, which makes the self-write a no-op.
+- **`IdleInhibitor` needs a non-null `window`.** It has no window of its own
+  and does nothing without one. A singleton therefore cannot assert an
+  inhibitor unaided: `shell.qml` hands it the keepalive `PanelWindow`, which
+  is the one window that exists for the whole session.
+- **A layer-surface idle inhibitor is not observable via `hyprctl clients` or
+  `hyprctl layers`.** `hyprctl clients | grep -ci inhibit` counts the
+  per-toplevel `inhibitingIdle` field only, and an inhibitor asserted on a
+  `PanelWindow` layer surface appears in neither listing, so the count does not
+  move even when the inhibitor is asserted. Check it behaviorally: run a
+  throwaway `hypridle -c` with a short timeout whose `on-timeout` writes a
+  marker, confirm the marker does not appear while presentation is on, and
+  that it appears within a few seconds of turning presentation off.
 
 ## Theme