# 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. 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`.
- 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.