The architecture has been updated

hermes_code/website/docs/developer-guide/cron-internals.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 11
+title: "Cron Internals"
+description: "How Hermes stores, schedules, edits, pauses, skill-loads, and delivers cron jobs"
+---
+
+# Cron Internals
+
+Hermes cron support is implemented primarily in:
+
+- `cron/jobs.py`
+- `cron/scheduler.py`
+- `tools/cronjob_tools.py`
+- `gateway/run.py`
+- `hermes_cli/cron.py`
+
+## Scheduling model
+
+Hermes supports:
+
+- one-shot delays
+- intervals
+- cron expressions
+- explicit timestamps
+
+The model-facing surface is a single `cronjob` tool with action-style operations:
+
+- `create`
+- `list`
+- `update`
+- `pause`
+- `resume`
+- `run`
+- `remove`
+
+## Job storage
+
+Cron jobs are stored in Hermes-managed local state (`~/.hermes/cron/jobs.json`) with atomic write semantics.
+
+Each job can carry:
+
+- prompt
+- schedule metadata
+- repeat counters
+- delivery target
+- lifecycle state (`scheduled`, `paused`, `completed`, etc.)
+- zero, one, or multiple attached skills
+
+Backward compatibility is preserved for older jobs that only stored a legacy single `skill` field or none of the newer lifecycle fields.
+
+## Runtime behavior
+
+The scheduler:
+
+- loads jobs
+- computes due work
+- executes jobs in fresh agent sessions
+- optionally injects one or more skills before the prompt
+- handles repeat counters
+- updates next-run metadata and state
+
+In gateway mode, cron ticking is integrated into the long-running gateway loop.
+
+## Skill-backed jobs
+
+A cron job may attach multiple skills. At runtime, Hermes loads those skills in order and then appends the job prompt as the task instruction.
+
+This gives scheduled jobs reusable guidance without requiring the user to paste full skill bodies into the cron prompt.
+
+## Recursion guard
+
+Cron-run sessions disable the `cronjob` toolset. This prevents a scheduled job from recursively creating or mutating more cron jobs and accidentally exploding token usage or scheduler load.
+
+## Delivery model
+
+Cron jobs can deliver to:
+
+- origin chat
+- local files
+- platform home channels
+- explicit platform/chat IDs
+
+## Locking
+
+Hermes uses lock-based protections so overlapping scheduler ticks do not execute the same due-job batch twice.
+
+## Related docs
+
+- [Cron feature guide](../user-guide/features/cron.md)
+- [Gateway Internals](./gateway-internals.md)