Keep key SDK documentation examples runnable #14

Status

Selected for Cycle 3 build. Issue #16 selected this preventive CI-integrity slice after a repository audit. The audit found that key onboarding examples have no automated execution coverage; it did not establish that OpenController currently publishes a broken snippet.

User and workflow

An SDK integrator follows a quick-start or API example to connect an agent to a game/simulator. If the example uses a stale signature or impossible setup, the user must diagnose whether the mismatch is in their code, the docs, or the external service before making progress.

Direct evidence

• 2026-09-15 — Factorio Learning Environment issue #418: a reporter said four documented agent API examples failed against a live headless server and proposed correcting the signatures. The issue records no working workaround. Direct report

This is one report in a separate project. It demonstrates a concrete failure mode, not how often it occurs. It does not establish a defect in OpenController's examples.

Repository fit and interpretation

A repository audit at main commit ba0529e found that the Getting Started dry-run flow and AI Agent Integration action-map/state-patch examples are not executed by tests. The root test command covers package suites rather than documentation snippets or example packages, and examples/basic-dry-run/index.ts has no test or build script. This is a coverage gap, not a confirmed stale-example defect. A shared executable source or fixture can validate a small set of published onboarding paths with the dry-run adapter, without hardware or a live game.

Proposed outcome

Automate three high-use onboarding paths so API drift and behavior mismatches are caught in CI: the standalone Getting Started dry-run flow, one AI Agent Integration action-map or state-patch flow, and the basic dry-run example. Keep the tested source shared with the documentation so snippets cannot silently drift from their tests.

Acceptance criteria if selected

• Add one CI command that executes the standalone Getting Started dry-run flow, one AI action-map or state-patch flow, and examples/basic-dry-run/index.ts.
• Use shared executable sources or fixtures consumed by the docs; avoid a separately copied test-only version of each example.
• Run without API keys, native permissions, physical hardware, or a live game.
• Assert observable controller state, action, or replay behavior rather than only successful compilation.
• Correct any stale documentation found during implementation.
• Keep live native, OBS, external-game, and physical-hardware paths outside the automated suite and its compatibility claims.

Dependencies

Selected by Cycle 3 research gate #16. The cycle goal issue is blocked by this implementation issue until the selected work is merged.

Non-goals

• No attempt to fix Factorio Learning Environment or other external project APIs.
• No claim that dry-run example checks verify a real OS/game/controller integration.
• No repository-wide rewrite of every historical documentation snippet.