From 4f51299f8d0ab2976491e0edc565110986b9d0fa Mon Sep 17 00:00:00 2001
From: "@mrubens" <2600+mrubens@users.noreply.github.com>
Date: Sun, 13 Sep 2026 03:08:27 +0000
Subject: [PATCH] docs: document recent task notification behavior

---
 apps/docs/fast-sessions.mdx |  4 ++--
 apps/docs/tasks.mdx         | 22 +++++++++++++++++-----
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/apps/docs/fast-sessions.mdx b/apps/docs/fast-sessions.mdx
index d06882959..8b07af855 100644
--- a/apps/docs/fast-sessions.mdx
+++ b/apps/docs/fast-sessions.mdx
@@ -187,8 +187,8 @@ result arrives.
 
 Fast sessions can also render presentational widgets such as status cards,
 tables, and plans directly in the transcript. Widget HTML is sanitized and
-sandboxed in the web view. Chat surfaces receive a concise text preview and a
-link to open the rendered widget when both are available.
+sandboxed in the web view. Chat surfaces receive a link to open the rendered
+widget and include a concise text preview when one is available.
 
 Agent replies and delegated reports can also include up to two pie, bar, area,
 or line charts. Roomote renders each chart responsively in the web transcript
diff --git a/apps/docs/tasks.mdx b/apps/docs/tasks.mdx
index 3f8917d86..6743d363e 100644
--- a/apps/docs/tasks.mdx
+++ b/apps/docs/tasks.mdx
@@ -40,6 +40,18 @@ execution count, workspace or pull-request context, aggregate cost, and unread
 state. Use the **Tasks** scope when you only want Sessions containing execution
 work. Board and list choices remain in the URL so views are shareable.
 
+If the task list fails to load, select **Retry** in the error state to fetch it
+again without leaving the page.
+
+## Web task notifications
+
+When a task started from the web dashboard completes, fails, or is canceled
+while its initiator is away from the Session, Roomote sends that person a direct
+notification with a link back to the task. It uses linked Slack, Teams,
+Telegram, and Discord accounts that the deployment can reach; verified Email is
+the fallback when no chat notification is delivered. Roomote skips the
+notification while the initiator is present in the Session.
+
 ## Recover from a failed start
 
 When a task cannot start, select **Try in a new task** to open an editable task
@@ -64,11 +76,11 @@ The task view gives you the working context for a run:
 - previews for running apps
 - task metadata and links back to the surface that started the task
 
-If a task started from Slack, Teams, Telegram, Discord, Linear, or source
-control, use the task view when the chat or provider thread does not show enough
-detail to review the work. Presentational widgets remain available in the task
-transcript; when an agent provides a text fallback, Roomote also sends that
-fallback to the originating Slack, Teams, Telegram, or Discord conversation.
+If a task started from Slack, Teams, Telegram, Discord, Email, Linear, or source
+control, use the task view when the provider thread does not show enough detail
+to review the work. Presentational widgets remain available in the task
+transcript. Supported communication surfaces receive a link to open the widget
+and include the agent's text preview when one is available.
 
 For a Markdown plan artifact, **Build this** starts a Session and delegates the
 plan to a task inside it. Roomote preserves the selected environment, branch,