Document nested @cycles decorator behavior and best practices

[amavashev]

Summary

Added documentation to the README explaining how nested @cycles decorators behave and providing guidance on recommended usage patterns.

Changes

• Added new section "Nested @cycles Calls" that explains:

  • Nested @cycles-decorated functions are allowed and won't raise errors
  • Each decorator creates independent reservations that deduct budget separately
  • This results in double-counting of budget when nesting occurs
  • Provided a concrete example showing the budget deduction behavior (600 total instead of 500)

• Documented recommended pattern:

  • Place @cycles decorator only at the outermost entry point
  • Inner functions should remain plain functions without their own @cycles guard
  • Provided example code showing the recommended approach with single reservation

Details

This is a documentation-only change that clarifies an important behavioral characteristic of the @cycles decorator. The documentation helps users understand potential budget management issues when using nested decorated functions and provides clear guidance on the best practice to avoid unintended budget deductions.

https://claude.ai/code/session_012fx4F3BKF7QHZ5WMN1Jaua