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

The server binaries are **C++** (MSVC 2010, x64). See
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the evidence and what is known
about their structure.

## Target runtime environment

The analyzed binaries are expected to run in the following environment. Use
this when interpreting imports, API usage, and database access in decompiled
code.

- **OS**: Windows Server — exact version unknown; assume **2008 or 2012**.
- **Runtime dependencies** (winetricks-style identifiers):
  - `dotnet7` — .NET 7 runtime
  - `dotnetdesktop7` — .NET 7 Desktop runtime
  - `vcrun2010` — Visual C++ 2010 redistributable
  - `d3dx9` — DirectX 9 D3DX libraries
  - `d3dx10` — DirectX 10 D3DX libraries
- **Database**: Microsoft SQL Server, supported up to **SQL Server 2019**.
  Schema files for the backing databases are in `schema/`.

## 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. |
| `docs/` | Project documentation, e.g. `ARCHITECTURE.md` (language/toolchain, libraries, code conventions) | Hand-maintained; update as findings are confirmed. |
| `third-party/` | Upstream sources/headers matched to the shipped support DLLs (OpenSSL 1.0.0d, curl 7.21.4, BugTrap ~1.3, mingw-w64 `dbghelp.h`, TinyXML 2.5.x) | Reference only, not build inputs. Do not edit upstream files; record provenance changes in the doc below. |

**Third-party libraries:** see [`third-party/README.md`](third-party/README.md)
for each support DLL's observed version, matched source and checksums, match
quality (exact vs. closest), libraries with no public source, and acquisition
routes. Consult it before decompiling any support DLL, and use the matched
headers for symbol/struct recovery instead of re-deriving known APIs.
The servers also statically link **ProudNet** (Nettention, proprietary). Its
headers live only in gitignored `third-party/_local/`; never commit them or any
other licence-restricted vendor files.

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