docs: add token optimization guidance for isolated cron sessions

[ProofOfReach]

Summary

Adds documentation to help users optimize token usage when scheduling recurring tasks with cron jobs.

Key additions:

1. Token optimization section in cron-vs-heartbeat.md explaining:

   • Main session jobs load full conversation history (50-100K+ tokens)
   • Isolated sessions start fresh (10-20K tokens)
   • 80%+ token savings for standalone reports

2. Payload type clarification: Isolated sessions require --message (agentTurn), not --system-event

3. Troubleshooting entry in cron-jobs.md for the common "agentTurn required" error with fix

Why this matters

Users often default to --session main for all cron jobs without realizing the token cost. Standalone reports (weather, summaries, event listings) that do not need conversation history can run isolated and save significant tokens per run.

The CLI already enforces the payload type requirement, but the error message alone does not explain why or what the alternative is. This PR makes the pattern discoverable before users hit the error.

Test plan

• Verified links work with Mintlify anchor format
• Examples are generic (no PII)
• Matches existing doc style

Greptile Overview

Greptile Summary

This PR adds documentation to reduce token usage for scheduled automation by clarifying when to use --session main vs --session isolated, and by explaining the required payload type (--message/agentTurn for isolated sessions). It also adds a troubleshooting entry in cron-jobs.md for the common “payload.kind=agentTurn” error and links readers to the new token optimization section in cron-vs-heartbeat.md.

Confidence Score: 4/5

• This PR is safe to merge; it’s a docs-only change with a minor anchor/heading robustness concern.
• Changes are limited to Markdown documentation and align with existing guidance about main vs isolated cron sessions; the main risk is Mintlify anchor stability due to a quoted heading in Troubleshooting, which could make future deep-links brittle.
• docs/automation/cron-jobs.md (Troubleshooting heading anchor robustness)

_{(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!}

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

[P2] Heading contains quotes, which can produce brittle Mintlify anchors

CLAUDE.md recommends avoiding apostrophes/em dashes in headings because Mintlify anchors can break; quotes can similarly create surprising slugs. Since cron-jobs.md:460 links to /automation/cron-vs-heartbeat#token-optimization-for-standalone-reports, it’s worth making the troubleshooting heading link-friendly (e.g., no quotes / simpler text) so it can be referenced reliably.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/automation/cron-jobs.md
Line: 446:446

Comment:
[P2] Heading contains quotes, which can produce brittle Mintlify anchors

CLAUDE.md recommends avoiding apostrophes/em dashes in headings because Mintlify anchors can break; quotes can similarly create surprising slugs. Since `cron-jobs.md:460` links to `/automation/cron-vs-heartbeat#token-optimization-for-standalone-reports`, it’s worth making the troubleshooting heading link-friendly (e.g., no quotes / simpler text) so it can be referenced reliably.

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[ProofOfReach]

Fixed in fd1841e - removed quotes from heading for stable Mintlify anchors.