docs: describe prompt notifications

A prompt that waits on the human is announced after a grace period, and the
notification can carry the answer: allow / deny / review buttons for a
confirmation, a reply field for an `ask_user_line`. `doc/notifications.md` lays
out the two channels (the optional `desktop-notifier` extra, and OSC 777 / OSC 9
written to `/dev/tty` with no dependency), what each prompt kind offers, why the
reason line stays out by default, and the platform limits — no buttons where a
server does not render them, a reply field only under KDE, kitty left with the
bell.

The example config and the README config block gain the `[notify]` section, and
AGENTS.md documents the three prompt hooks and the rule that only the outermost
prompt of a nested read is announced.

doc/plyngent.example.toml

@@ -42,6 +42,27 @@
 # include_project_roots = true
 # allow_write = false
 
+# Notifications while a prompt waits on the human: a tool confirmation, a
+# directory-access grant, a skill write, an ``ask_user_*`` question, or the
+# limit-continue prompt. A prompt is announced only after `grace_seconds` of
+# waiting, so one you answer at the terminal stays silent; `min_interval_seconds`
+# throttles bursts.
+# channels: "auto" tries the desktop first (needs the `notify` extra:
+# `pip install plyngent[notify]`) and falls back to a terminal escape sequence;
+# "desktop" / "terminal" pin one of them.
+# `actions` offers allow / deny / review as notification buttons; where the
+# platform has none the notification stays text-only.
+# `include_reason` adds the one-line reason — it can name a command or a URL, so
+# it stays off by default (a notification may be mirrored to a lock screen).
+# [notify]
+# enabled = true
+# grace_seconds = 5.0
+# min_interval_seconds = 10.0
+# channels = ["auto"]
+# actions = true
+# include_reason = false
+# protocol = ""            # terminal protocol: "" = detect, or osc777 / osc9 / bell
+
 # MCP (Model Context Protocol) servers exposed as agent tools.
 # Defining a server opts it in; tools appear as mcp__<server>__<tool> with
 # LOCAL tags (confirm flow applies). Names in disable stay disconnected.