docs: prefer branch-first decision examples

[rlippmann]

What changed

• updated the README and API reference to show branch-first Decision handling
• updated the ambiguity and integration examples to branch with is_error(...) / is_update(...) before reading variant payloads
• updated the shared example utility to read decision["message"] and decision["state"] only inside the matching branch

Why

• Decision is now a true discriminated union, so examples and presentation code should teach the natural union-usage pattern
• this keeps get_error_message(...) and get_decision_state(...) available as compatibility conveniences without making them the preferred style

Checklist

• pre-commit run (uv run pre-commit run --all-files)
• tests pass (uv run pytest)