docs: detailed documentation of pidog/action_flow.py

[devin-ai-integration]

Summary

Adds docs/action_flow.md, a documentation-only deep dive into pidog/action_flow.py (ActionFlow, Posetures, ActionStatus). No code changes.

Covers: where ActionFlow sits in the stack (app → ActionFlow → preset_actions → Pidog → actions_dictionary), the OPERATIONS recipe schema and every entry, posture/head-pitch compensation, the run() execution order poseture → before → function → after (each stage followed by a blocking wait_all_done()), the worker-thread state machine (STANDBY/THINK/ACTIONS), the public API, and the concurrency model.

It also records concrete findings from reading the code alongside preset_actions.py / pidog.py:

• standby_actions = ['waiting', 'feet_left_right'] — 'feet_left_right' is not a key in OPERATIONS, and run() ignores unknown names silently, so ~23% of idle ticks are no-ops (likely meant 'feet shake').
• enum.StrEnum requires Python ≥ 3.11, but pyproject.toml declares requires-python = ">=3.7".
• The posture guard keys off last_actions (last action name) instead of self.posture, and is only updated for actions that declare poseture, so sit → bark → sit skips the second sit transition.
• self.OPERATIONS[before]["function"] assumes the key exists — KeyError for entries like "stop" (currently unreachable).
• action_queue.get() has no timeout, so stop()/join() can hang if the state is ACTIONS with an empty queue.
• run() relies on random leaking in via from .preset_actions import *.
• Dead code: HEAD_ANGLE, ActionStatus.ACTIONS_DONE, the head_pitch key on "nod"; "stop" is an empty recipe and does not call Pidog.body_stop().

Link to Devin session: https://app.devin.ai/sessions/7111583235ea4084a505cf2a925fd7aa
Requested by: @PascalDesmet

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring