feat: updated docs to make python api clearer

[paul-nechifor]

Problem

The docs for agents for Python API need to be improved.

Closes DIM-841

Solution

• Improve them.

Contributor License Agreement

• I have read and approved the CLA.

[greptile-apps]

Greptile Summary

This PR adds new documentation sections to modules.md and python-api.md to clarify the Python API for sync input handlers, Spec-based side effects, module testing, RPC calls, and hot-restart behavior.

• modules.md gains three new sections: Sync input handlers (with the Counter/Disposable pattern), Triggering side effects via Specs (the Watchdog example), and Testing modules (mocking Spec fields in pytest fixtures).
• python-api.md gains an RPC calls section and expands the hot-restart section with a guide on what changes require a full daemon restart and a list of operational gotchas.

Confidence Score: 5/5

Documentation-only change with no effect on runtime behavior; safe to merge.

All import paths and the Disposable-wrapping pattern for register_disposable were verified against the actual source. No code is modified.

No files require special attention.

Important Files Changed

Filename	Overview
docs/usage/modules.md	Three new documentation sections added (sync input handlers, Spec-based triggers, testing); import paths and code patterns verified against source.
docs/usage/python-api.md	New RPC calls section and expanded hot-restart / operational-gotchas content added; Twist constructor usage and module access patterns verified correct.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Module.__init__] --> B[start]
    B --> C["value.subscribe(handler)\nreturns unsubscribe fn"]
    C --> D["Disposable(unsubscribe_fn)"]
    D --> E["register_disposable(disposable)"]
    E --> F[Module running\nhandler fires on message]
    F --> G[stop]
    G --> H["CompositeDisposable.dispose()\ncalls unsubscribe fn"]
    H --> I[Handler detached]

    subgraph Spec wiring
        J[Coordinator deploy time] --> K["Resolves _notifier: NotifierSpec\nto matching module"]
        K --> L[Proxy bound to field]
        L --> M[Handler calls self._notifier.notify]
    end

Loading

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into paul/feat/claud..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!