feat(grid-agent): add embodied behavior controller (#125)

docs/grid-agent-behavior.md

@@ -0,0 +1,19 @@
+# Grid-agent embodied behavior
+
+The embodied controller is the only route from an LLM-authorized action to avatar movement. Its public surface is deliberately high level: face a visible avatar or nearby point, make one small look shift, walk a short distance on a heading, stop, sit, stand, and read the current pose. It exposes no control flags, raw packets, follow/wander primitive, unrestricted autopilot, flight, teleport, touch, or arbitrary animation.
+
+## State and preemption
+
+The observable modes are `offline`, `settling`, `available`, `engaged`, `executing`, `roaming`, `paused`, and `recovering`. Session readiness enters a bounded settling period. Public-response pacing enters `engaged`; authorized actions enter `executing`; timeout, stuck, and native failures pass through `recovering`. Roaming is only a marker for a separately policy-authorized scheduler task—the controller does not invent routes. Operator pause and the global emergency stop preempt movement and send a stop request. Disconnects and region changes cancel in-flight work and invalidate every old target.
+
+Every transition records its trigger. Every action record contains generation and region provenance, action name, trigger, policy authorization class or ID, duration, and outcome without including message text or tool arguments.
+
+## Safety envelope
+
+- Only authenticated IMs, the authenticated local operator, and authorized scheduler grants may invoke behavior tools. Public speaker attention is a fixed built-in response behavior, not a public tool authorization.
+- Face targets must be present in the current avatar cache or be a finite nearby point in the current 256 m region.
+- A short walk is limited by configured distance and duration. Before moving, the native adapter verifies that the target's cached 4 m parcel-map cell has the same nonzero parcel ID as the current position. The controller then faces the target, starts one local movement request, polls pose, and always cancels movement on arrival, timeout, stuck detection, pause, emergency stop, disconnect, or region change.
+- Actions have a global timeout and minimum interval. Idle behavior is one low-frequency look shift; it never moves continuously and never emits chat.
+- Response delay, attention dwell, idle interval, timeouts, distance bounds, and rate limits are validated configuration. Random pacing is injectable so paused-time tests are deterministic.
+
+The live adapter reuses the single native client/manager graph. Turns use `AgentMovement::turn_toward`; bounded walking uses a local autopilot target that is always paired with `auto_pilot_cancel`; sit and stand use the existing agent manager. Native state reads and actions are generation-fenced before use.