Show consumers how to configure semantic action-map bindings #61

Goal

Show consumers how to define caller-owned input bindings that dispatch to stable semantic actions through OpenController's existing createActionMap API. Keep the example runnable with the dry-run adapter and make the ownership boundary clear.

Cycle 8 review gate: #57. This candidate is awaiting the Cycle 8 ranking and build-wave decision.

Evidence

• Accessible-Chess #5, 2026-08-14: an accessibility-focused app requested app-owned aliases, conflict handling, and keyboard recovery. This is one issue thread; comments describe implementation and owner follow-up, not independent confirmations. It is adjacent keyboard-accessibility evidence, not a gamepad or OpenController report.
• OpenAI Developer Community game demo, 2026-02-16: the demo author added arrow/space bindings after starting with a WASD-only mapping. This is one project example, not a recurring report or a request for an SDK feature.

These signals give low-to-medium confidence in recurrence. Repository fit is good: createActionMap already maps named semantic actions to command sequences, while the current integration example only demonstrates a fixed action preset. A runnable example can explain how callers supply and validate their own binding definitions without adding a new runtime feature.

Scope

Own the example and documentation under examples/basic-dry-run/ and docs/ai-agent-integration.md. Demonstrate a caller-provided mapping from input identifiers to stable semantic actions (for example, moveLeft, moveRight, and confirm), and show alternate binding sets dispatching to the same semantic action map. Validate binding configuration before dispatch so unknown actions or ambiguous source bindings are reported clearly. Keep execution on the dry-run adapter.

Acceptance criteria

• A runnable TypeScript example defines semantic action IDs independently from input identifiers and uses createActionMap for the controller commands.
• The example demonstrates at least two caller-owned binding sets (such as WASD and arrow/space) that invoke the same semantic actions and produce the expected dry-run controller states.
• Invalid bindings, including unknown action IDs and conflicting source identifiers, fail validation before any controller action is sent.
• The example's smoke check runs without physical hardware and asserts the valid and invalid configuration paths.
• docs/ai-agent-integration.md explains the separation between caller-owned input events, semantic action IDs, and OpenController output commands, and links to the runnable source.
• Documentation states that OpenController does not capture keyboard or physical gamepad input, change OS/Steam remapping, or provide a settings UI or persistent user profile.

Non-goals and limits

• No keyboard/gamepad event listener, device discovery, physical input adapter, or OS-level remapping.
• No consumer settings UI, persistence format, global remapper, or changes to the core action-map API.
• No claim that the sample makes a consuming application accessible by itself; the application still owns its controls, conflict policy, persistence, and recovery UX.
• The dry-run verifies OpenController commands and state only. It does not prove host, browser, Steam, device, or game input behavior.

Likely ownership

• examples/basic-dry-run/ai-agent-integration.ts
• examples/basic-dry-run/check.ts
• docs/ai-agent-integration.md