Skip to content

docs: add a game movement walkthrough - #4567

Closed
TheDesignFounder wants to merge 1 commit into
morluto:mainfrom
TheDesignFounder:docs/relay-garden-community-20261016
Closed

TheDesignFounder wants to merge 1 commit into
morluto:mainfrom
TheDesignFounder:docs/relay-garden-community-20261016

Conversation

@TheDesignFounder

Copy link
Copy Markdown

Summary

Add a playable example built around one question: does moving diagonally make
the player faster?

The walkthrough shows how we used REA to find the movement function in a small
JavaScript reference we wrote. Reading the function explains the movement rule;
comparing a separate implementation with the reference across 2,000 inputs
checks the result.

Play the game ·
Read the article ·
Get the source

Watch the gameplay ·
Watch the guided investigation ·
Read the recording transcript

Related to #778. This adds one example alongside #1704 and leaves the broader
demo collection open.

Problem and expected behavior

Readers of the JavaScript guide would get a small example they can follow from
question to result. It includes the command-line and MCP steps, the source REA
points to, and checks they can run themselves.

It also shows an incomplete result: a search misses a number that is present in
the code. The walkthrough explains why that result does not mean the number is
absent.

Change and scope

Four Markdown files: a walkthrough, a verification record, and links from the
JavaScript guide and documentation index. The example uses existing REA tools.

We wrote the reference and knew its code before the investigation. The example
checks a movement rule; the drones, collectibles and other game rules were added
separately. We added original artwork using Dreamlayer.

Contract and boundary impact

  • Semantic owner and earliest changed stage: documentation; helps readers find
    and follow an example.

  • Contribution scope fit and linked maintainer decision: documentation of
    existing JavaScript analysis tools, related to [Docs] Track reproducible demos across REA reverse-engineering domains #778. A new-capability scope
    decision is not applicable.

  • CLI and MCP/tool-catalog contract: unchanged.

  • Provider, bridge, target-format, or platform compatibility: unchanged. The
    verification record names the versions and computer used.

  • Evidence, artifact, provenance, or reconstruction contract: unchanged. The
    displayed responses are labeled as excerpts; full local records are retained.

  • Target selection, authority, upstream behavior, and cleanup details: REA reads
    our version-pinned reference. Separate tests run the reference and game code.
    The MCP server process exited after the connection was closed.

  • Generated metadata, package, or installation impact: none.

  • Documentation or usability only; no target interaction introduced by this PR.

Evidence and regression coverage

  • Tests added or updated: none in this documentation PR. A separate local fix
    makes the game's browser tests advance time only when instructed.

  • Base reproduction or other evidence: real REA 6.5.0 command-line and MCP runs.
    The caller trace found one relationship and reported eight unresolved facts.
    The search for 180 found no match and reported partial coverage.

  • User-visible CLI/MCP output: the verification record includes exact requests,
    selected responses, and the source location checked against the reference.

  • Remaining proof gaps: the investigation was guided and used a local SDK client.
    Native agent registration, other operating systems, and autonomous discovery
    were not tested. Matching these inputs does not prove a match for every input.

  • Observed, derived, and inferred claims remain distinguishable.

  • Artifact identity, source provenance, and failed attempts remain preserved.

  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

Checks recorded on 16 October 2026:

  • npm ci and npm run investigate: passed with the locked dependencies.
  • npm test: all eight tests passed, including 2,000 movement comparisons.
  • npm run validate:assets: all ten file checksums matched.
  • One MCP connection: analysis and both follow-up queries completed; the queries
    reused the first analysis result. Server shutdown was verified.
  • Browser checks: the original suite failed once, then passed unchanged. A later
    controlled test reproduced a timing problem in the test itself. With the
    separate local fix, all seven browser checks passed; removing the fix made the
    new timing check fail. The public example pinned at b0627c5 does not yet
    contain this fix. The original failure lacked enough timing data to prove its
    exact cause.
  • The four documentation files passed the scoped Oxfmt check, whitespace checks,
    and source, JSON and local-link checks. These checks were repeated after applying
    the documentation changes to the current upstream branch. Both uploaded videos
    were downloaded without authentication and matched the local file checksums.

The full REA runtime and provider suites were not run for these documentation
changes. Website templates and translations are unchanged.

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: macOS 13.1 x86_64, Node 22.23.3,
    REA 6.5.0 and Chrome 155.0.8059.82. No native analysis engine was used.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: public excerpts use generic
    paths and are labeled as excerpts. Raw local records are kept outside the docs.

Author readiness

Human owner: @TheDesignFounder

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants