server-re/AGENTS.md

AGENTS.md

Project overview

Reverse-engineering project for the Rusty Hearts game server/client binaries (Windows PE32+ x86-64). Analysis is performed with Ghidra (headless or GUI) driven through REA (reverse-engineer-anything skill + rea-agents MCP server). There is no application source code here — the binaries are the primary evidence.

Directory layout

Path	Contents	Mutability
binaries/	Original shipped binaries: server EXEs (GameServer_Release_USA_x64.exe, DungeonServer_..., etc.), DLLs, and game data (maps, Lua scripts, tables, item/character assets)	Read-only. Never modify, move, or delete. Gitignored.
schema/	SQL Server database schema/log files (.mdf / .ldf) for RustyHearts, RustyHearts_Account, RustyHearts_Auth, RustyHearts_Log, GMRustyHearts	Read-only. Never modify. Gitignored.
decomp/	Raw decompilation objects exported from Ghidra/REA (pseudocode, listings, function metadata)	Derived output. Regenerable; created on demand.
.agents/skills/	Installed agent skills, notably reverse-engineer-anything (REA)	Agent configuration.

Tooling

• Ghidra: installed at /opt/ghidra; headless entrypoint /opt/ghidra/support/analyzeHeadless. GHIDRA_INSTALL_DIR=/opt/ghidra.
• REA MCP: registered in opencode.json via npx -y rea-agents@6.5.0 mcp with GHIDRA_INSTALL_DIR and JAVA_HOME set in its environment.
• Runtime versions: managed by mise.toml — Java 21, Node 26.
• REA skill: .agents/skills/reverse-engineer-anything/SKILL.md. Read the relevant reference under .agents/skills/reverse-engineer-anything/references/ before non-trivial workflows (native binaries → native-and-artifacts.md).

Analysis workflow

1. Route the target first: native executables/libraries go through REA open_binary (never pass a Ghidra project file as the target — pass the original binary path under binaries/).
2. Work summary-first: binary_overview / summary detail before drilling into analyze_function or pseudocode. Reuse retained Evidence IDs instead of re-running identical analysis.
3. Export raw decompilation artifacts (pseudocode, listings) into decomp/ using per-binary subdirectories, e.g. decomp/GameServer_Release_USA_x64/. Keep filenames stable and function-address-based so results are reproducible.
4. Track targets, artifact SHA-256 identities, and per-binary status in decomp/INVENTORY.md; keep a per-binary finding ledger in decomp/<name>/evidence.md.
5. Close the REA session (close_binary) when the investigation is complete.

Evidence and claims

• Every conclusion must distinguish observation (from evidence), inference, and unknown. Cite Evidence IDs or file:line-style references to decomp output.
• Static analysis never establishes runtime behavior — say so explicitly.
• Do not infer behavior from filenames, strings, or binary layout alone; corroborate with decompilation or data from schema/.
• Keep a finding ledger for multi-step investigations (conclusion → evidence → remaining gaps).

Ground rules

• Treat binaries/ and schema/ as immutable inputs; all outputs go to decomp/ or a new file, never beside the originals.
• Do not install Ghidra, Java, Node, or REA prerequisites ad hoc — they are provisioned via mise.toml and /opt/ghidra; repair configuration instead.
• Version-pin REA at rea-agents@6.5.0 as declared in opencode.json.
• Do not add npm devEngines/packageManager constraints to package.json — they make npx exit EBADDEVENGINES in this directory and break the REA MCP launch (this happened once; devEngines was removed).
• Keep the REA registration project-local: opencode.json in this repo is the source of truth. Do not write global client config (~/.config/opencode/…) or run rea setup against global paths — rea doctor may report global registration drift; that is accepted here.
• When tooling is missing or an MCP call is blocked, diagnose the specific blocker (registration vs. restart vs. provider) rather than re-running setup wholesale — see the REA skill's connection-and-recovery reference.