Document how to hand off control to a human

[Excelius-Wang]

Closes #56.

Handing control back to a person is a pattern Burr already supports well, but the mechanics were only discoverable by reading examples/email-assistant and piecing together halt_before from the applications page. This adds a concepts page that states the pattern directly.

Changes

• New page docs/concepts/human-in-the-loop.rst, listed in docs/concepts/index.rst after state-machine.
• Cross-references to it from the Runtime Inputs section of actions.rst and the Step section of state-machine.rst, since those are where a reader is most likely to be when the question comes up.

The page covers: why the person stays outside the graph; the run(halt_before=[...]) / collect / run(inputs=...) loop and the fact that halt_before takes precedence when an action is in both halt lists; a minimal graph with a single approval step; a chat loop where the human action is both entrypoint and halt target; multi-handoff applications via examples/email-assistant; what changes in a web server; and why input() inside an action is CLI-only.

How I tested this

• Ran every code block on the page against the current source and checked the printed output matches what the page claims, including the halt_before precedence behaviour and the resumed-run input handling.
• Checked that .. _human-in-the-loop: resolves from all three referring locations, and that the label sits after the page title to match actions.rst and streaming-actions.rst.

Notes

Docs only, no source changes. The examples referenced (email-assistant, conversational-rag/graph_db_example) are quoted rather than modified.

Happy to shorten the page or move it if you'd rather this live under docs/concepts/actions.rst as a subsection instead of standing on its own.

Checklist

• PR has an informative and human-readable title (this will be pulled into the release notes)
• Changes are limited to a single goal (no scope creep)
• Code passed the pre-commit check & code is left cleaner/nicer than when first encountered.
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future TODOs are captured in comments
• Project documentation has been updated if adding/changing functionality.

Made with Cursor