docs: clarify heartbeat versus cron delivery

2026-06-27 11:04:08 +08:00
parent 06d5495b60
commit 9ce9d2235a
7 changed files with 25 additions and 11 deletions
@@ -5,7 +5,9 @@ description: Schedule reminders and recurring tasks.

 # Cron

-Use the `cron` tool to schedule reminders or recurring tasks.
+Use the `cron` tool to schedule reminders or recurring tasks that should report back to the originating chat/session when they run.
+
+Do not use `cron` for periodic background checks that should stay quiet when there is nothing useful to report. For those, update `HEARTBEAT.md`; the protected heartbeat job runs those checks and only delivers results that pass the notification gate.

 ## Three Modes

@@ -9,6 +9,7 @@ Use this file for project-specific preferences, recurring workflow conventions,
 - Before scheduling reminders, check available skills and follow skill guidance first.
 - Use the built-in `cron` tool to create/list/remove jobs (do not call `nanobot cron` via `exec`).
 - Get USER_ID and CHANNEL from the current session (e.g., `8281248569` and `telegram` from `telegram:8281248569`).
+- Cron jobs run as scheduled turns in the origin chat/session and normally deliver the result back to that channel. Do not use cron for background checks that should stay silent when there is nothing useful to report; use `HEARTBEAT.md` instead.

 **Do NOT just write reminders to MEMORY.md** — that won't trigger actual notifications.

@@ -20,4 +21,4 @@ Use this file for project-specific preferences, recurring workflow conventions,
 - Use `edit_file` only for small exact replacements copied from the current `HEARTBEAT.md`.
 - Use `write_file` for first creation or intentional full-file rewrites.

-When the user asks for a recurring/periodic heartbeat task, update `HEARTBEAT.md` instead of creating a one-time reminder. Use the built-in `cron` tool for separate reminders or custom schedules that should not be part of the heartbeat task list.
+When the user asks for a recurring/periodic heartbeat task, or for a periodic background check that should only notify on actionable changes, update `HEARTBEAT.md` instead of creating a one-time reminder. Use the built-in `cron` tool for explicit reminders, scheduled tasks that should report every run, or custom schedules that should not be part of the heartbeat task list.
@@ -3,7 +3,9 @@
 <!--
 This file is checked periodically by your nanobot agent. When nanobot gateway starts with gateway.heartbeat.enabled=true, it automatically registers a protected heartbeat cron job that reads this file.

-If this file has no tasks (only headers and comments), the agent will skip it. Completed tasks should be deleted, not kept — heartbeat only reads "Active Tasks".
+Use this file for recurring background checks that should stay quiet unless there is something useful to report. Regular cron jobs are different: they normally deliver each run's result back to the chat/session where they were created.
+
+If this file has no tasks (only headers and comments), the agent will skip it. Completed tasks should be deleted, not kept - heartbeat only reads "Active Tasks".
 -->

 ## Active Tasks