docs: detailed documentation of pidog/preset_actions.py

[devin-ai-integration]

Summary

Adds docs/preset_actions.md, completing the trio with docs/pidog.md and docs/action_flow.md. Documentation only, no code changes.

Starts with the conventions that make every routine readable — the 8-value leg frame layout ([LF hip, LF knee, RF hip, RF knee, LH hip, LH knee, RH hip, RH knee], mirrored left/right, most frames being perturbations of sit = [30, 60, -30, -60, 80, -45, -80, 45]), head_move vs head_move_raw (gimbal blend vs servo space), and why the placement of wait_all_done() between queued legs_move/head_move calls is the actual choreography (both before one wait ⇒ simultaneous; a wait between ⇒ sequential). Then walks all 24 routines, grouped: front-paw tricks, full-body motions, the bark/alert family, idle, procedural sin/cos head animations, expressive poses, and sound-led sequences.

Things that are hard to see from the code alone:

• # Note 1 decodes as: leg index 7 is dropped 45 → 38 in scratch/hand_shake/high_five to brace the right hind leg against the tipping moment of a raised front paw.
• nod uses amplitude*cos(...) − amplitude, which maps the cosine into [-2A, 0] — the head only ever dips, never rises above neutral. relax_neck phase 1 puts pitch 90° out of phase (sin(x − π/2)) with yaw/roll, which is what traces a cone rather than a line.
• bark_action/attack_posture are the only routines using foot coordinates through legs_angle_calculation IK instead of hand-tuned joint angles.
• sit_2_stand's L1 brace pose exists because a direct sit→stand interpolation slips; stand_angles is computed, so it respects ActionDict.set_height()/set_barycenter().
• Audio sync is by construction, not measurement: sleep(2.34) in howling and the 6-iteration loop in pant are tuned to the mp3 lengths.

Also records 14 issues, e.g. fluster computes current_legs/L1/L2/leg1 and discards them (leg half commented out), waiting() declares global last_wait for a variable that doesn't exist, sit_2_stand fetches unused sit_angles, howling never restores the RGB strip mode, the 4-frame hand_down_angs block is duplicated verbatim three times, and the missing __all__ means action_flow.py depends on random leaking in via from .preset_actions import *.

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