docs: document writing dialogue state from a custom action (#306)

[chethanuk]

Description

#306 asks how to manage dialogue state from a custom action. The capability exists and works in both Colang versions, but it is not documented anywhere. ActionResult is the mechanism: Colang 1.0 turns context_updates into a ContextUpdate event, and Colang 2.0 merges the same field into state.context. The page that owns return values, Creating Actions, covers Simple, Dictionary and Boolean returns and never mentions ActionResult.

Four files, no new pages, docs/index.yml untouched.

• Creating Actions gets an ActionResult and Context Updates section under Return Values: a field table, and a Colang 2.0 / Colang 1.0 tab pair. events is marked Colang 1.0 only, since Colang 2.0 attaches those events to the action's ActionFinished event and never applies them.
• Extract User-provided Values gets a Store Extracted Values Across Turns section. Extraction only puts the value in a flow variable; this is the missing half. Per-tab notes on how far the state actually carries: Colang 1.0 rebuilds context from the cached event history, Colang 2.0 needs process_events() because generate() returns None for the state and output_vars raises for a 2.0 config. Neither survives a restart.
• Action Parameters and the Colang 2.0 Python actions reference get a pointer each. The reference page also had a wrong line: it said context "can be updated via ContextUpdate event", true of the event in general but not of the path an action controls.

The Colang 1.0 tab warns about returning a module-level mutable object, which is #424. Colang 1.0 stores the action result by reference and re-runs the flow from element 0 on every internal event, so an object mutated in place changes underneath that replay and the if guards reading it flip. Colang 2.0 cannot hit this: it updates the context once per action and does not re-slide over the stored result.

Related Issue(s)

Closes #306

Issue assignee: none yet — filed under label question, not assigned to me. Flagging per CONTRIBUTING rather than assigning it myself.

Verification

Two new tests, both pinning the snippets the pages publish:

$ make test TEST=tests/v2_x/test_run_actions.py
5 passed in 117.03s (0:01:57)      # was 4

The second turn is load-bearing: it asserts the slot outlives the turn that wrote it. Replacing ActionResult(context_updates={"user_name": value}) with a plain return value fails it with Expected 'Hello Ngoc' and received 'Hello None'.

$ make test TEST=tests/test_context_updates.py
2 passed in 191.57s (0:03:11)      # was 1

The #424 warning is reproduced, not inferred: running the reporter's shape with a module-level dict returns an empty assistant message with slots stuck at unknown; returning dict(user_info) instead, one word changed, fills all of them.

$ make test TEST="tests/v2_x tests/test_context_updates.py"
211 passed, 1 skipped in 168.53s (0:02:48)

pre-commit passes on all six changed files. make docs-fern was not run locally (needs network); CI's docs-build.yaml covers docs/** on PRs to develop.

One added snippet does not execute under TestChat: the Colang 2.0 example in Extract User-provided Values follows the activate llm continuation + user said "<prefix>" shape the page's six existing 2.0 examples already use, and that shape doesn't run under the harness today (not a regression — the page's own existing snippets fail the same way at this commit).

AI Assistance

• AI tools were used; a human reviewed and can explain every change (tool: Claude Code).

Checklist

• I've read the CONTRIBUTING guidelines.
• This PR links to a triaged issue assigned to me. (issue is unassigned — see Related Issue(s))
• My PR title follows the project commit convention.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• I've noted any verification beyond CI and any checks I couldn't run.
• I did not update generated changelog files manually.
• I addressed all CodeRabbit, Greptile, and other review comments, or replied with why no change is needed. (CodeAnt flagged creating-actions.mdx:211 typing context_updates as dict instead of Optional[dict]; fixed, see pr-review.md)
• @mentions of the person or team responsible for reviewing proposed changes.