OpenSource/reverse-engineering-anything
1
0 Fork 0
mirror of https://github.com/morluto/rea.git synced 2026-10-26 17:35:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(website): clarify guides and case studies

Browse Source 
Several guides use broad headings and repeat their summaries, making the main example harder to follow. This change names each task directly, keeps Notion's clipboard investigation in the main reading path, and moves the Markdown example and longer provenance into expandable details. The browser guide now opens the hosted example, and the first native CLI query works without a global install.

The existing figures, prompts, source excerpts and comparison controls remain the teaching material. Provider details now fit narrow screens. The repository README links to all Showcases, and the website authoring docs share a signed design principle: a good website is like a good paper—easy to follow, clear and concise, with a clean, refined presentation. A new style guide and scoped AGENTS.md explain how to maintain that approach.

Closes #985.

Validation:

- `python3 scripts/prepare-website.py` and `python3 scripts/verify-website.py`: 12 HTML pages, 183 local references, SVG XML, the six-file ZIP and the sole manual Pages publisher.
- Oxfmt checks and `git diff --check`; `npm run check:fast` with Node.js 24.18.0.
- Browser checks at both `/` and `/rea/`: 24 routes, 68 copy buttons, 20 comparison steps, two CSV exports, two ZIP downloads and eight viewport widths from 320px to 1440px.
- Existing code excerpts, expanded details, keyboard access, no-JavaScript content, continuous cursor animation and reduced motion checked.

Existing analysis and compiler-check evidence is retained; real native-provider verification and compiler replay were not rerun for these copy and layout changes. The homepage content and publication triggers are unchanged.
This commit is contained in:
Ysopwnable authored and GitHub committed 2026-10-07 23:24:15 +08:00
1 parent 0a4caf4a0a
commit 5065fcd520
16 files changed
+509 -300
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+1 -1
View File
@@ -17,7 +17,7 @@
<a href="https://trendshift.io/repositories/82054?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-82054" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/82054" alt="morluto%2Frea | Trendshift" width="250" height="55"/></a>
**[Website](https://morluto.github.io/rea/) · [Guides](https://morluto.github.io/rea/guides/) · [DX-Ball showcase](https://morluto.github.io/rea/showcase/dx-ball/)**
**[Website](https://morluto.github.io/rea/) · [Guides](https://morluto.github.io/rea/guides/) · [Showcases](https://morluto.github.io/rea/showcase/)**
[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [Tool catalog](#tool-catalog-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
website/AGENTS.md
+23
View File
@@ -0,0 +1,23 @@
# Website maintenance
> A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
>
> — N0zoM1z0
Read [README.md](README.md) and [style-guide.md](style-guide.md) before changing
website content, layout or figures. Use [figures.md](figures.md) and `evidence/`
for asset notes and the source of case-study claims.
- Write English, direct headings and concrete instructions. Each paragraph
should explain a new fact or action.
- Reuse the shared styles, prompts, figures and code-step components. Keep a
case study focused on one question, with further examples in native details.
- Show what REA returns and how the agent uses it. Preserve source attribution,
target identity and verification scope.
- Keep personal paths, account data, credentials and raw captures outside the
public assets. Use generic inputs and label shortened display paths.
- Check both local root and `/rea/` paths, mobile layouts, expanded details,
copying and downloads. Run `scripts/prepare-website.py` followed by
`scripts/verify-website.py`.
- Keep `website-pages.yml` as the sole, manual Pages publisher. Follow the
publication procedure in the website README.
website/README.md
+9 -1
View File
@@ -1,10 +1,17 @@
# REA website
> A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
>
> — N0zoM1z0
An English static website with explanatory figures, worked guides and DX-Ball, Notion and TH04 investigations.
The public files are in `website/public/`. The site uses HTML, CSS and a small
script for copying code and following the assembly-to-C comparison. Python
packages the downloadable example; there is no frontend bundler or npm dependency.
[style-guide.md](style-guide.md) explains the writing, page structure, figures,
visual system and review process. Read it before adding or revising a page.
## Local preview
From the repository root:
@@ -78,7 +85,8 @@ code; the scoped lint override admits `require` only in that example directory.
The Notion case follows the same HTML figure style. Its short excerpts explain
the packaged clipboard bridge; separate web-cache probes illustrate the rich
clipboard and Markdown formats. Only selected source details and generic
clipboard format, with Markdown tables available as an additional example in
collapsed details. Only selected source details and generic
example data belong on the site. Machine paths, account identifiers, local
configuration, complete vendor bundles and raw captured results stay outside
the website.
website/figures.md
+8
View File
@@ -1,5 +1,13 @@
# REA website figures
> A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
>
> — N0zoM1z0
Use [style-guide.md](style-guide.md#make-figures-explain-a-relationship) when adding
or revising a figure. The prompts below are historical layout references; use
the current SVG source for published labels.
The published diagrams are SVG source assets:
- `public/assets/figures/rea-investigation-flow.svg` — 1774 × 887 viewBox.
website/public/assets/figures/dx-ball-sound-pan-investigation.svg
+3 -3
View File
@@ -36,11 +36,11 @@
<text x="1547" y="372" font-size="43">Maintained C</text>
<text x="418" y="569" font-size="34">Brick-hit caller</text>
<text x="418" y="615" font-size="28" fill="#5b6570">20 + 30 × tile_x</text>
<text x="1354" y="632" font-size="30">Original-x86</text>
<text x="1354" y="632" font-size="30">Original code</text>
<text x="1354" y="670" font-size="30">comparison</text>
<text x="1354" y="717" font-size="31" fill="#5b6570">3,205 cases</text>
<text x="1625" y="632" font-size="28">VC4.0 compiler</text>
<text x="1625" y="670" font-size="32">replay</text>
<text x="1625" y="632" font-size="28">VC4.0 build</text>
<text x="1625" y="670" font-size="30">comparison</text>
<text x="1625" y="717" font-size="28" fill="#5b6570">63 matching bytes</text>
</g>
</g>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 3.3 KiB

website/public/assets/styles.css
+2 -2
View File
@@ -689,7 +689,7 @@ pre code {
}
.provider {
display: grid;
grid-template-columns: 105px 1fr;
grid-template-columns: 105px minmax(0, 1fr);
gap: 1.3rem;
padding-block: 1.2rem;
border-top: 1px solid var(--line);
@@ -1107,7 +1107,7 @@ pre code {
gap: 1rem;
}
.provider {
grid-template-columns: 1fr;
grid-template-columns: minmax(0, 1fr);
gap: 0.25rem;
}
.guide-entry {
website/public/get-started/index.html
+129 -124
View File
@@ -32,7 +32,7 @@
<main id="main" class="container">
<div class="page-heading">
<p class="breadcrumb"><a href="../">Home</a> / Get started</p>
<h1>Start with a question.</h1>
<h1>Set up REA.</h1>
<p class="lede">
Connect REA to your coding agent, or inspect a local app from your
terminal.
@@ -43,17 +43,17 @@
</div>
<div class="article-layout">
<nav class="contents" aria-label="On this page">
<p>Choose your starting point</p>
<p>Setup options</p>
<ul>
<li><a href="#agent">With your agent</a></li>
<li><a href="#terminal">From the terminal</a></li>
<li><a href="#native">Native binaries</a></li>
<li><a href="#agent">Connect your coding agent</a></li>
<li><a href="#terminal">Use the CLI</a></li>
<li><a href="#native">Set up native analysis</a></li>
<li><a href="#help">Getting help</a></li>
</ul>
</nav>
<article class="article" aria-label="REA getting started guide">
<section class="article-section" id="agent">
<h2>With your agent</h2>
<h2>Connect your coding agent</h2>
<p>
Run setup to connect REA to your coding agent. Client choices
include Claude Code, Codex, Cursor, Gemini CLI, Windsurf and other
@@ -118,19 +118,14 @@
involved, with the source locations for your findings.
</p>
</blockquote>
<p>
Replace the path with your local target. Read the findings, then
ask a narrower follow-up about a function or connection you want
to understand.
</p>
<p>Replace the path with your local target.</p>
</section>
<section class="article-section" id="terminal">
<h2>From the terminal</h2>
<h2>Use the CLI</h2>
<p>
You can start with a JavaScript or Electron application folder or
ASAR archive. This path uses Node.js and npm and reads the app
without running it.
Analyze a JavaScript or Electron application folder or ASAR
archive without running the app:
</p>
<div class="code-block">
<div class="code-header">
@@ -153,10 +148,9 @@
<code>"D:/apps/example"</code> works here.
</p>
<p>
The result includes the application's identity, recovered module
relationships and evidence locations. It also records
relationships that remain unresolved. Use those findings to choose
where to investigate next.
The result identifies the app, shows connections between modules
and gives their source locations. Connections REA cannot resolve
are marked in the result.
</p>
<p>
If you'd like a permanent <code>rea</code> command in your shell:
@@ -183,116 +177,121 @@
</section>
<section class="article-section" id="native">
<h2>Working with native binaries</h2>
<h2>Set up native analysis</h2>
<p>
REA connects your agent to a local analysis provider. Choose the
tool you already use, configure its connection, then ask about
your executable or library.
Native binaries need a local analysis tool. Choose and configure
one below, then give REA your executable or library.
</p>
<div class="provider-list">
<div class="provider">
<h3>Ghidra</h3>
<div>
<p>
Use an existing Ghidra 12.1.x installation and a 64-bit JDK
21 or newer on Linux x64 or macOS x64/arm64. Set the paths
before running setup:
</p>
<details class="evidence-details">
<summary>Connect your Ghidra installation</summary>
<div class="code-block">
<div class="code-header">
<span>Ghidra connection · macOS / Linux</span
><button
class="copy-button"
type="button"
data-copy="ghidra-connect"
aria-label="Copy ghidra connection · macos / linux"
>
Copy
</button>
</div>
<pre><code id="ghidra-connect">export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
<details class="evidence-details">
<summary>Choose a tool: Ghidra, Hopper or IDA</summary>
<div class="provider-list">
<div class="provider">
<h3>Ghidra</h3>
<div>
<p>
Use an existing Ghidra 12.1.x installation and a 64-bit
JDK 21 or newer on Linux x64 or macOS x64/arm64. Set the
paths before running setup:
</p>
<details class="evidence-details">
<summary>Connect your Ghidra installation</summary>
<div class="code-block">
<div class="code-header">
<span>Ghidra connection · macOS / Linux</span
><button
class="copy-button"
type="button"
data-copy="ghidra-connect"
aria-label="Copy ghidra connection · macos / linux"
>
Copy
</button>
</div>
<pre><code id="ghidra-connect">export GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.1.4_PUBLIC
export JAVA_HOME=/absolute/path/to/jdk-21
npx -y rea-agents@latest doctor --provider ghidra --json
npx rea-agents@latest setup</code></pre>
</div>
<p>
Replace both paths with your existing installations. Setup
checks them and records valid settings for your selected
client. On macOS, use a Ghidra package with the native
decompiler matching your host architecture.
</p>
</details>
</div>
</div>
<div class="provider">
<h3>Hopper</h3>
<div>
<p>
Connect Hopper on macOS or Linux. Run the setup command
above; it detects an existing installation or offers an
installation plan for your approval.
</p>
<p>
On macOS, complete Hopper's first-run choice of demo mode or
license activation before an unattended analysis.
</p>
</div>
</div>
<div class="provider">
<h3>IDA</h3>
<div>
<p>
The verified IDA setups use Windows, with an existing MCP
registration for an attached GUI or a headless database.
Linux and macOS headless analysis remains unverified.
</p>
<details class="evidence-details">
<summary>Connect an existing IDA MCP registration</summary>
<p>
Keep the upstream server's working <code>command</code>,
<code>args</code> and optional <code>env</code> in a JSON
file. An existing <code>mcpServers</code> object with an
<code>ida-pro-mcp</code> entry is also accepted. Point REA
at that file before setup:
</p>
<div class="code-block">
<div class="code-header">
<span>IDA connection · Windows PowerShell</span
><button
class="copy-button"
type="button"
data-copy="ida-connect"
aria-label="Copy IDA connection for Windows PowerShell"
>
Copy
</button>
</div>
<pre><code id="ida-connect">$env:REA_IDA_MCP_CONFIG = "C:/analysis/ida-mcp.json"
<p>
Replace both paths with your existing installations.
Setup checks them and records valid settings for your
selected client. On macOS, use a Ghidra package with the
native decompiler matching your host architecture.
</p>
</details>
</div>
</div>
<div class="provider">
<h3>Hopper</h3>
<div>
<p>
Connect Hopper on macOS or Linux. Run the setup command
above; it detects an existing installation or offers an
installation plan for your approval.
</p>
<p>
On macOS, complete Hopper's first-run choice of demo mode
or license activation before an unattended analysis.
</p>
</div>
</div>
<div class="provider">
<h3>IDA</h3>
<div>
<p>
The verified IDA setups use Windows, with an existing MCP
registration for an attached GUI or a headless database.
Linux and macOS headless analysis remains unverified.
</p>
<details class="evidence-details">
<summary>
Connect an existing IDA MCP registration
</summary>
<p>
Keep the upstream server's working <code>command</code>,
<code>args</code> and optional <code>env</code> in a
JSON file. An existing <code>mcpServers</code> object
with an <code>ida-pro-mcp</code> entry is also accepted.
Point REA at that file before setup:
</p>
<div class="code-block">
<div class="code-header">
<span>IDA connection · Windows PowerShell</span
><button
class="copy-button"
type="button"
data-copy="ida-connect"
aria-label="Copy IDA connection for Windows PowerShell"
>
Copy
</button>
</div>
<pre><code id="ida-connect">$env:REA_IDA_MCP_CONFIG = "C:/analysis/ida-mcp.json"
$env:REA_ANALYSIS_PROVIDER = "ida"
npx -y rea-agents@latest doctor --provider ida --json
npx rea-agents@latest setup</code></pre>
</div>
<p>
The attached profile uses upstream legacy 1.4.0 tools with
the original binary already open in IDA. The headless
profile uses the upstream database-supervisor API and a
registration with <code>"mode": "headless"</code>; real
verification covers an IDA 9.3 Windows x64 supervisor.
Doctor checks the registration without starting IDA.
</p>
<p>
Give REA the original executable path, with
<code>--provider ida</code> in a CLI query. For an agent,
include <code>REA_IDA_MCP_CONFIG</code> in the REA
registration's environment and select IDA when opening the
binary.
</p>
</details>
</div>
<p>
The attached profile uses upstream legacy 1.4.0 tools
with the original binary already open in IDA. The
headless profile uses the upstream database-supervisor
API and a registration with
<code>"mode": "headless"</code>; real verification
covers an IDA 9.3 Windows x64 supervisor. Doctor checks
the registration without starting IDA.
</p>
<p>
Give REA the original executable path, with
<code>--provider ida</code> in a CLI query. For an
agent, include <code>REA_IDA_MCP_CONFIG</code> in the
REA registration's environment and select IDA when
opening the binary.
</p>
</details>
</div>
</div>
</div>
</div>
</details>
<p class="small-heading">
For an existing Ghidra setup, inspect a function with:
</p>
@@ -308,15 +307,21 @@ npx rea-agents@latest setup</code></pre>
Copy
</button>
</div>
<pre><code id="native-function">rea function /absolute/path/to/program main \
<pre><code id="native-function">npx -y rea-agents@latest function /absolute/path/to/program main \
--provider ghidra --json</code></pre>
</div>
<p>
Replace <code>main</code> with the function name or address you
want to inspect. Each CLI invocation imports and analyzes the
target in its own session. Your agent's MCP queries reuse the
imported binary while that session is open.
want to inspect.
</p>
<details class="evidence-details">
<summary>How native analysis sessions work</summary>
<p>
Each CLI command imports and analyzes the binary, then closes
its session. Your agent's MCP queries reuse the imported binary
while that session is open.
</p>
</details>
<p>
<a href="../guides/native/">Follow a native analysis example</a>
to see how the function result leads to a recovered calculation.
@@ -327,8 +332,8 @@ npx rea-agents@latest setup</code></pre>
<h2>Getting help</h2>
<h3>If your agent doesn't see REA</h3>
<p>
Restart or reconnect the client after setup. To check its
registration, use a client-scoped report; for Codex:
Restart or reconnect the client after setup. Check its REA
connection with <code>doctor</code>; for Codex:
</p>
<div class="code-block">
<div class="code-header">
website/public/guides/browser/index.html
+14 -15
View File
@@ -49,7 +49,7 @@
<li><a href="#prepare">Open the browser</a></li>
<li><a href="#ask">Ask your agent</a></li>
<li><a href="#capture">Capture from CLI</a></li>
<li><a href="#result">Read and follow</a></li>
<li><a href="#result">Read the request and script</a></li>
</ul>
</nav>
<article class="article" aria-label="Browser observation">
@@ -62,12 +62,8 @@
<code>notes.json</code>, formats the two notes as CSV, and starts
a download.
</p>
<p>
We want to see which request the click makes, then use the script
to understand how the response becomes a file.
</p>
<figure class="workflow-figure">
<p class="figure-title">One action, captured while it happens</p>
<p class="figure-title">From the click to the CSV download</p>
<ol class="flow-steps">
<li>
<span class="flow-label">01 · You</span
@@ -99,16 +95,15 @@
<code>GET notes.json → 200 → notes[] → CSV</code>
</p>
<figcaption>
The request and response metadata come from the capture. CSV
construction is explained by reading the script.
Start the capture before clicking Export notes.
</figcaption>
</figure>
</section>
<section class="article-section" id="prepare">
<h2>Open an observable browser</h2>
<h2>Open Chrome with remote debugging</h2>
<p>
Start a Chrome-family browser with a dedicated profile and a local
debugging port. On Linux, for this site's local preview:
Open the hosted Notes example with a separate browser profile and
a local debugging port. On Linux:
</p>
<div class="code-block">
<div class="code-header">
@@ -125,12 +120,12 @@
<pre><code id="browser-start">google-chrome \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/rea-notes-browser \
http://127.0.0.1:4173/examples/notes-web/</code></pre>
https://morluto.github.io/rea/examples/notes-web/</code></pre>
</div>
<p>
Use your installed browser's executable path on macOS or Windows.
The page URL should point to your local preview or
<a href="../../examples/notes-web/">the hosted Notes example</a>.
You can replace the page URL with another page you want to
inspect.
</p>
<p>
REA connects to this existing browser. You keep control of the
@@ -225,7 +220,7 @@
</p>
</section>
<section class="article-section" id="result">
<h2>Read the result, then follow the code</h2>
<h2>Read the request and export script</h2>
<div class="evidence-table-wrap">
<table class="evidence-table">
<caption>
@@ -260,6 +255,10 @@
</tbody>
</table>
</div>
<p class="caption">
The hosted example's request path includes the site's
<code>/rea/</code> prefix.
</p>
<div class="code-block">
<div class="code-header">
<span>Read the loaded scripts</span
website/public/guides/index.html
+8 -10
View File
@@ -32,10 +32,10 @@
<main id="main" class="container">
<div class="page-heading">
<p class="breadcrumb"><a href="../">Home</a> / Guides</p>
<h1>Start with<br />an example.</h1>
<h1>REA guides.</h1>
<p class="lede">
Follow an example from the first prompt to the evidence. Then use the
same approach with your own app.
Analyze a native function, an Electron export or a browser request.
Each guide includes a prompt, code and results.
</p>
</div>
<div class="guide-index">
@@ -70,7 +70,9 @@
<span>Preload API</span> <b aria-hidden="true">→</b>
<span>IPC</span> <b aria-hidden="true">→</b> <span>CSV file</span>
</div>
<a class="text-link" href="javascript/">Application workflows</a>
<a class="text-link" href="javascript/"
>JavaScript &amp; Electron guide</a
>
<p>
For a larger packaged app, follow
<a href="../showcase/notion/">Notion's clipboard bridge</a>.
@@ -96,12 +98,8 @@
<section class="guide-entry">
<p class="eyebrow">First investigation</p>
<div>
<h2>Connect your agent, then ask.</h2>
<p>
Each guide starts with a plain-language question and follows a
concrete example. If you haven't connected REA yet, setup takes
you through the client and provider choices.
</p>
<h2>Set up REA</h2>
<p>Connect your coding agent or use REA from the terminal.</p>
<a class="text-link" href="../get-started/">Get started with REA</a>
</div>
</section>
website/public/guides/javascript/index.html
+15 -13
View File
@@ -35,10 +35,10 @@
<a href="../../">Home</a> / <a href="../">Guides</a> / JavaScript
&amp; Electron
</p>
<h1>Follow a feature<br />across the app.</h1>
<h1>Trace an Electron<br />CSV export.</h1>
<p class="lede">
Use a CSV export to see how REA connects JavaScript files, exposed
APIs and Electron process boundaries.
Follow a button click from the page API, through Electron IPC, to the
CSV file writer.
</p>
</div>
<div class="article-layout">
@@ -47,9 +47,9 @@
<ul>
<li><a href="#example">The example</a></li>
<li><a href="#ask">Ask your agent</a></li>
<li><a href="#follow">Connect the pieces</a></li>
<li><a href="#follow">Trace the export code</a></li>
<li><a href="#try">Try the example</a></li>
<li><a href="#next">Continue investigating</a></li>
<li><a href="#next">Inspect the CSV writer</a></li>
</ul>
</nav>
<article class="article" aria-label="JavaScript &amp; Electron">
@@ -62,7 +62,9 @@
across several files.
</p>
<figure class="workflow-figure">
<p class="figure-title">A feature across two processes</p>
<p class="figure-title">
The CSV export across Electron processes
</p>
<ol class="flow-steps">
<li>
<span class="flow-label">Renderer → preload</span
@@ -101,7 +103,7 @@
</figure>
</section>
<section class="article-section" id="ask">
<h2>Give your agent one feature</h2>
<h2>Ask about the CSV export</h2>
<p>
<a href="../../get-started/#agent">Connect your agent to REA</a>
and give it the app directory or ASAR file:
@@ -140,7 +142,7 @@
</p>
</section>
<section class="article-section" id="follow">
<h2>Connect the pieces</h2>
<h2>Trace the export code</h2>
<h3>The page calls a small API</h3>
<div class="code-block">
<div class="code-header">
@@ -266,10 +268,10 @@
/absolute/path/to/notes-example --json</code></pre>
</div>
<p>
Replace the path with the folder you unzipped. Look for
<code>normalized_result.summary.ipc</code> and the source
locations in <code>normalized_result.graph</code>. The example has
one channel and one paired invocation.
Replace the path with the folder you unzipped. You should find one
IPC channel and one matching handler in
<code>normalized_result.summary.ipc</code>. Source locations are
in <code>normalized_result.graph</code>.
</p>
<p>
For your own app, use the same command with its directory or ASAR
@@ -278,7 +280,7 @@
</p>
</section>
<section class="article-section" id="next">
<h2>Ask the next question</h2>
<h2>Inspect the CSV writer</h2>
<blockquote class="prompt">
<p>
Follow <code>notes:export</code> to its handler. Which inputs
website/public/guides/native/index.html
+7 -13
View File
@@ -34,10 +34,10 @@
<p class="breadcrumb">
<a href="../../">Home</a> / <a href="../">Guides</a> / Native analysis
</p>
<h1>Recover a calculation.<br />Follow the evidence.</h1>
<h1>Recover DX-Ball's<br />sound-pan calculation.</h1>
<p class="lede">
Use DX-Ball’s sound panning to see how an agent moves from a binary to
an explanation and a checked C function.
Inspect the original instructions, identify the input and constants,
then check the recovered C.
</p>
</div>
<div class="article-layout">
@@ -46,18 +46,17 @@
<ul>
<li><a href="#example">The example</a></li>
<li><a href="#ask">Ask your agent</a></li>
<li><a href="#follow">Follow the evidence</a></li>
<li><a href="#follow">Read the REA results</a></li>
<li><a href="#result">Recover and check</a></li>
<li><a href="#try">Use your own binary</a></li>
</ul>
</nav>
<article class="article" aria-label="Native analysis">
<section class="article-section" id="example">
<h2>A position becomes a sound</h2>
<h2>Calculate left/right sound panning</h2>
<p>
In DX-Ball, a brick hit supplies a horizontal screen position. The
sound code turns it into a left/right panning value. We want to
recover that calculation from the executable.
sound code turns it into a left/right panning value.
</p>
<p>
The starting function, <code>0x00406400</code>, has a short
@@ -138,14 +137,9 @@
Example prompt. Give your agent the path to your local DX-Ball
1.07 executable.
</p>
<p>
You can start with a feature name. Your agent uses REA to locate
relevant functions, then follows the evidence with more focused
queries.
</p>
</section>
<section class="article-section" id="follow">
<h2>Follow what REA returns</h2>
<h2>Read the REA results</h2>
<h3>Read the input</h3>
<div class="code-block">
<div class="code-header">
website/public/showcase/dx-ball/index.html
+4 -18
View File
@@ -85,11 +85,11 @@
</div>
<div>
<dt>45,380</dt>
<dd>original-x86 differential cases</dd>
<dd>comparisons with original code</dd>
</div>
<div>
<dt>33</dt>
<dd>byte-exact functions</dd>
<dd>functions with matching compiled bytes</dd>
</div>
</dl>
<p class="caption">
@@ -112,12 +112,6 @@
game continues with ball and paddle physics, power-up handling and
Windows integration.
</p>
<p>
The analysis starts from the DX-Ball 1.07 executable. REA returns
function code, instructions, callers and state references. These
findings guide the C implementation; execution of the original x86
functions and compiler replay check the result.
</p>
</section>
<section class="article-section" id="sound-pan">
@@ -267,12 +261,6 @@
</p>
</li>
</ol>
<p>
REA exposes these operations through CLI and MCP, with target
identity and Evidence IDs in the results. The agent can follow up
on a caller or data address directly, then use the findings to
write maintained C.
</p>
<h3 class="small-heading">From REA's findings to C</h3>
<p>
@@ -523,10 +511,8 @@
<section class="article-section" id="checking">
<h2>Checking the recovered function</h2>
<p>
The input, caller context and constant values returned through REA
guided the maintained C implementation. The project then checked
it against the original x86 function and the pinned compiler. For
this function, both checks pass.
The recovered function passes two checks: its return values match
the original, and its compiled bytes match the executable.
</p>
<div class="verification">
<div>
website/public/showcase/index.html
+8 -8
View File
@@ -32,17 +32,17 @@
<main id="main" class="container">
<div class="page-heading">
<p class="breadcrumb"><a href="../">Home</a> / Showcases</p>
<h1>Follow the<br />investigation.</h1>
<h1>REA case studies.</h1>
<p class="lede">
Start with a question about a real application. See what REA finds,
follow the code, and understand how the pieces fit together.
Game reconstruction and Electron analysis, with examples from DX-Ball,
Notion and TH04.
</p>
</div>
<div class="guide-index">
<section class="guide-entry">
<p class="eyebrow">Native · Reconstruction</p>
<div>
<h2>Rebuilding DX-Ball</h2>
<h2>DX-Ball's sound-pan calculation</h2>
<p>
Recover a sound-pan calculation from a 1996 Windows game. REA's
instructions, caller references and numeric constants lead to a
@@ -61,7 +61,7 @@
<section class="guide-entry">
<p class="eyebrow">Electron · Feature tracing</p>
<div>
<h2>Following a copy through Notion</h2>
<h2>How Notion copies text and HTML</h2>
<p>
Trace a page-facing API through Notion's packaged JavaScript.
Follow its IPC wrappers to the system clipboard, then see how a
@@ -79,7 +79,7 @@
<section class="guide-entry">
<p class="eyebrow">PC-98 DOS · Reconstruction</p>
<div>
<h2>Understanding TH04's bullet patterns</h2>
<h2>How TH04 aims a ring of bullets</h2>
<p>
Inspect the original 16-bit angle helper with REA. Match its
multiply, divide and coordinate operations to readable C++, then
@@ -96,12 +96,12 @@
</section>
</div>
<section class="article-section">
<h2>Try a smaller example first.</h2>
<h2>Step-by-step guides</h2>
<p>
The guides walk through a native calculation, an Electron export and a
browser request. Each starts with a prompt and a concrete target.
</p>
<a class="text-link" href="../guides/">Explore the worked guides</a>
<a class="text-link" href="../guides/">Read the guides</a>
</section>
</main>
<footer class="site-footer">
website/public/showcase/notion/index.html
+58 -73
View File
@@ -35,11 +35,10 @@
<a href="../../">Home</a> / <a href="../">Showcases</a> / Notion
</p>
<p class="eyebrow">Case study · Electron</p>
<h1>Following a copy<br />through Notion.</h1>
<h1>How Notion copies<br />text and HTML.</h1>
<p class="lede">
A familiar action leads through several files. Follow Notion's
clipboard API from the page, through Electron, to the system
clipboard.
Trace a clipboard call from Notion's page API, through the preload and
main process, to Electron's clipboard writer.
</p>
<p class="page-meta">Notion Desktop 7.6.1 · JavaScript · REA</p>
</div>
@@ -93,8 +92,7 @@
<ul>
<li><a href="#clipboard">Follow the clipboard bridge</a></li>
<li><a href="#rich-clipboard">Keeping a block's structure</a></li>
<li><a href="#markdown">Markdown becomes blocks</a></li>
<li><a href="#continue">Try another question</a></li>
<li><a href="#continue">More examples and sources</a></li>
</ul>
</nav>
<article class="article" aria-label="Notion Electron case study">
@@ -294,14 +292,12 @@ function invokeInMainAndReturnResult(channel, ...args) {
<section class="article-section" id="rich-clipboard">
<h2>How does a copied block keep its structure?</h2>
<p>
The cached web editor adds a small detail to programmatic copies.
It sends text and HTML through
<code>electronApi.clipboard.write</code>, while keeping Notion's
private block data in a local virtual clipboard. An ID in the HTML
connects the two.
Notion's web editor sends text and HTML through
<code>electronApi.clipboard.write</code>. It keeps the block data
locally and puts an ID in the copied HTML to connect them.
</p>
<figure class="workflow-figure">
<p class="figure-title">One copy, two representations</p>
<p class="figure-title">HTML links to saved block data</p>
<div class="notion-clipboard-grid">
<div class="code-block">
<div class="code-header">
@@ -313,7 +309,7 @@ html: "&lt;p&gt;Project notes&lt;/p&gt;"
</div>
<div class="code-block">
<div class="code-header">
<span>Kept in the local virtual clipboard</span>
<span>Saved locally by Notion</span>
</div>
<pre><code>id: <span class="notion-channel">&lt;copy-id&gt;</span>
mimeTypes:
@@ -327,76 +323,59 @@ mimeTypes:
>
<li>Read the HTML ID</li>
<li>Find the same local ID</li>
<li>Restore private formats</li>
<li>Restore Notion block data</li>
</ol>
<figcaption>
Illustrative text and ID. The saved module probe recovered the
private formats when IDs matched; a stale entry left only the
ordinary text and HTML.
Illustrative text and ID. The recorded module test restores the
block data when IDs match; a stale entry returns only text and
HTML.
</figcaption>
</figure>
<p>
On paste, the reader looks for the marker and checks it against
the saved copy. A matching ID reconnects the text to its richer
representation. This explains why the HTML carries more than
visible content.
On paste, Notion looks for the HTML ID and checks it against the
saved copy. Matching IDs restore the block data.
</p>
<p class="caption">
Web assets cached on July 13, 2026. The desktop-package bridge
above and this web-side format are separate pieces of the
investigation.
</p>
</section>
<section class="article-section" id="markdown">
<h2>From Markdown to structured blocks</h2>
<p>
The same investigation also recovered Notion's Markdown
processing. A small table makes the internal format easy to see:
its rows and cells become data that the block renderer can use.
</p>
<figure class="workflow-figure">
<p class="figure-title">
A table through Notion's Markdown parser
</p>
<div class="notion-table-example">
<div class="code-block">
<div class="code-header"><span>Markdown input</span></div>
<pre><code>| A | B |
| - | - |
| 1 | 2 |</code></pre>
</div>
<div class="code-block">
<div class="code-header">
<span>Structured parser output · excerpt</span>
</div>
<pre><code>table · headerRow: true
table_row
cells: ["A"], ["B"]
table_row
cells: ["1"], ["2"]</code></pre>
</div>
</div>
<figcaption>
A saved extracted-module probe of web parser
<code>422457</code>. Both page and chat filters preserve this
table. The tree shows the recorded rows and cell text.
</figcaption>
</figure>
<p>
Finding that transformation required separating the ordinary
paste/import path from the structured Markdown and AI/chat
parsers. Each has its own entry point and intermediate format.
Clipboard format recorded from web assets cached on July 13, 2026.
</p>
</section>
<section class="article-section" id="continue">
<h2>Try another question</h2>
<p>
Start with one feature and follow the code that crosses a process
boundary. A named API, a literal channel and its receiver are
useful places to begin.
</p>
<h2>More examples and sources</h2>
<details class="evidence-details" id="markdown">
<summary>Another example: Markdown tables</summary>
<p>
Notion parses Markdown into block data. This example shows how a
table becomes header and data rows.
</p>
<figure class="workflow-figure">
<p class="figure-title">
A table through Notion's Markdown parser
</p>
<div class="notion-table-example">
<div class="code-block">
<div class="code-header"><span>Markdown input</span></div>
<pre><code>| A | B |
| - | - |
| 1 | 2 |</code></pre>
</div>
<div class="code-block">
<div class="code-header">
<span>Structured parser output · excerpt</span>
</div>
<pre><code>table · headerRow: true
table_row
cells: ["A"], ["B"]
table_row
cells: ["1"], ["2"]</code></pre>
</div>
</div>
<figcaption>
Recorded output from an extracted Markdown parser. The table
becomes rows and cells.
</figcaption>
</figure>
</details>
<details class="evidence-details">
<summary>Another path: the offline SQLite connection</summary>
<p>
@@ -436,6 +415,12 @@ mimeTypes:
matching receiver are connected by reading their wrapper
implementations in the package.
</p>
<p>
The Markdown example uses parser module <code>422457</code>.
Saved module tests show that both page and chat filters preserve
this table. The paste/import, structured Markdown and AI/chat
parsers have separate entry points and intermediate formats.
</p>
</details>
<ul class="reading-list">
<li>
@@ -454,7 +439,7 @@ mimeTypes:
</ul>
<div class="actions">
<a class="button" href="../../get-started/"
>Start with your own target</a
>Analyze your own app</a
>
</div>
</section>
website/public/showcase/th04/index.html
+21 -19
View File
@@ -54,15 +54,15 @@
<span class="flow-label">01 · Original game</span
><strong class="flow-node">MAIN.EXE</strong
><span class="flow-note"
>The PC-98 executable and a reviewed bullet helper.</span
>The PC-98 executable and its bullet-angle helper.</span
>
</li>
<li>
<span class="flow-label">02 · Inspect with REA</span
><strong class="flow-node">Instructions + references</strong
><span class="flow-note"
>Check the loaded image, read the arithmetic and anchor it to file
bytes.</span
>Verify the loaded DOS code and read the angle calculation from
the executable.</span
>
</li>
<li>
@@ -76,8 +76,8 @@
<span class="flow-label">04 · Check the source</span
><strong class="flow-node">2,139 matching bytes</strong
><span class="flow-note"
>Recorded compiler checks cover the containing bullet-add
code.</span
>Recorded compiler checks cover the bullet-generation code that
contains this helper.</span
>
</li>
</ol>
@@ -196,11 +196,10 @@ bullet_template_tune();</code></pre>
<section class="article-section" id="rea">
<h2>What REA returns</h2>
<p>
The project already has a reviewed boundary for
<code>bullet_velocity_and_angle_set()</code>. Inspecting that
original function through REA returns its instructions, pseudocode
and references together. Here are three parts of the result that
explain the pattern.
We inspect <code>bullet_velocity_and_angle_set()</code>, the
function that sets each bullet's velocity and angle. REA returns
its instructions, pseudocode and references. Three parts of that
result explain the pattern.
</p>
<ol class="rea-queries">
<li>
@@ -499,25 +498,23 @@ no_aim:
<section class="article-section" id="checking">
<h2>Checking the maintained source</h2>
<p>
The TH04 project checks this compiler-sensitive C++ with its
pinned Turbo C++ 4.0J toolchain. Recorded checks cover the
complete bullet-add source owner containing this helper.
The TH04 project's recorded checks compile the bullet-generation
code, including this helper, with its pinned Turbo C++ 4.0J
toolchain.
</p>
<div class="verification">
<div>
<h3>2,139 matching bytes</h3>
<p>
The rebuilt code matches the complete original target extent.
The comparison also checks the MAP contribution and
overlapping relocation.
The compiled bullet-generation code matches a 2,139-byte
section of the original executable.
</p>
</div>
<div>
<h3>Two clean builds</h3>
<p>
Two isolated compiler runs produce the same matching result.
The recorded input hashes match the maintained bullet source
shown here.
Two separate builds produce the same matching bytes. The
recorded input hashes match the maintained source shown here.
</p>
</div>
</div>
@@ -555,6 +552,11 @@ no_aim:
</tbody>
</table>
</div>
<p>
Compiler checks cover the complete bullet-add code section,
including this helper. They also compare its MAP contribution
and overlapping relocation.
</p>
<p>
REA verified the static DOS load image at load segment
<code>0x1000</code>. Its addresses describe that analysis image.
website/style-guide.md
+199
View File
@@ -0,0 +1,199 @@
# REA website writing and design guide
> A good website is like a good paper: easy to follow, clear and concise, with a clean, refined presentation.
>
> — N0zoM1z0
For REA, that means a concrete question, a figure that explains the process,
evidence the reader can inspect, and a useful next step. A clean, refined
appearance comes from precise wording, readable figures, consistent typography
and deliberate spacing.
Use this guide for new pages and revisions. Start from an existing page and
reuse `public/assets/styles.css` and `public/assets/main.js`. Local preview and
publication commands are in [README.md](README.md).
## What a reader should understand
A reader scanning for five seconds should see the subject and the result. After
ten seconds, the main figure should explain the sequence. After fifteen seconds,
the prompt or first example should show how to start.
These are reading goals, not a requirement to fit every investigation above the
fold. Keep the main path short and let readers open the supporting details.
## Write the task directly
Name the software, behavior or action in headings. Give the opening paragraph
one job: explain what the page covers. Use concrete verbs such as install, trace,
read, compare and calculate.
| General wording | More useful wording |
| ------------------------------------------------ | ------------------------------------------------------------------ |
| Start with a question. | Set up REA. |
| Follow a feature across the app. | Trace an Electron CSV export. |
| Following a copy through Notion. | How Notion copies text and HTML. |
| A position becomes a sound. | Calculate left/right sound panning. |
| Follow the investigation. | REA case studies. |
| Reviewed boundary / source owner / target extent | The helper / its surrounding code / the code section being checked |
Questions also work when they name a behavior: “Where is the CSV created?” and
“How does a copied block keep its structure?” give the reader something specific
to look for.
Explain necessary terms where they first matter. An IPC channel can be described
as a named message between Electron processes. Keep exact API names, addresses
and JSON paths in the code or result they identify.
Give each paragraph new information. A diagram can summarize a sequence, while
the code below explains individual steps. Repeating that REA supplies
instructions, callers and constants in several surrounding paragraphs adds no
new step. Explain that role once, then show the results.
Use captions for useful context: which values are illustrative, where an excerpt
comes from, or what a check covers. Scope a claim positively and precisely:
“The compiled function matches 63 bytes” is more useful than a broad claim
followed by several qualifications.
## Build a page around one question
### Guides
1. Name the task and introduce a small example.
2. Show a short flow of the relevant files, calls or observations.
3. Provide a copyable agent prompt and its prerequisites.
4. Explain the important code or returned fields.
5. Let the reader try the example, with a command or one ZIP download.
6. State the expected result and where to find it.
7. Offer a specific follow-up question or another relevant guide.
A command should work after the steps immediately before it. Use `npx` for a
first CLI query when global installation is optional. Browser examples should
open the hosted fixture by default; a local URL needs a server-start step. Keep
target paths, debugging endpoints and other required inputs explicit.
### Case studies
1. Introduce the project and the particular feature being examined.
2. Show a figure that explains the investigation or behavior.
3. Give a short example prompt.
4. Pair important REA queries with selected returned evidence.
5. Connect that evidence to readable source or an explanation.
6. Explain how the result was checked.
7. Link the reconstruction repository and supporting sources.
Show REA's useful contribution through a concrete finding: a missing stack
argument, a caller, bytes behind a constant, or source ranges in a packaged
bundle. Explain what the agent does with that finding. Credit source
interpretation, reconstruction and external checks to the work that performed
them.
Keep a second investigation optional. Notion's clipboard path is the main
story; Markdown tables and SQLite are additional examples. Native `<details>`
keeps them available without interrupting the first question.
Keep the explanation on the website. Repository links provide source,
reproduction instructions and further evidence. Use specific links for those
purposes, and immutable commit links for checkpoint-dependent facts.
## Make figures explain a relationship
Each figure should answer a question that a reader can name. Choose the visual
form that fits it:
| Relationship | Existing example | Useful form |
| ----------------------------------------- | ---------------------------------------- | -------------------------------------------------- |
| Analysis and verification steps | DX-Ball sound pan | Flow with separate verification branches |
| Code across process boundaries | Electron CSV export and Notion clipboard | HTML flow with APIs and channel names |
| A mathematical transformation | TH04's fixed and aimed rings | SVG drawn from the angle formula |
| Original instructions and readable source | DX-Ball and TH04 | Selectable HTML code with matching step highlights |
| A request caused by an action | Notes browser export | Flow, observed result table and script excerpt |
Use SVG or semantic HTML for diagrams with exact text, numbers and arrows.
Generated illustrations can help explore a layout, but the published labels,
relationships and values need to be checked. [figures.md](figures.md) records the
existing assets and original layout references.
Keep labels short, align related nodes, and give arrows an explicit direction.
Use color to identify the relevant operation or connection. Add a legend when
the visual encoding needs one. Avoid making the diagram repeat the entire page.
State illustrative inputs in the caption. TH04's diagram uses a count of 16 and
a player direction of 40; its dots are calculated from those values. Give an
image useful alternative text, and keep source code as selectable HTML.
On small screens, HTML flows stack. A wide SVG can have its own horizontal scroll
and an “Open figure” link. A diagram should remain readable at its intended
display size; scaling small labels down is not a mobile layout.
## Use the existing visual system
The shared stylesheet defines the site. Its core colors are:
| Token | Value | Use |
| ---------- | --------- | -------------------------------- |
| `--page` | `#ffffff` | Page background |
| `--ink` | `#20252b` | Main text |
| `--muted` | `#5b6570` | Secondary text |
| `--line` | `#e0e5e9` | Section and component boundaries |
| `--soft` | `#f4f6f8` | Code and supporting surfaces |
| `--accent` | `#294f82` | Links and meaningful highlights |
Use the system sans-serif stack for prose and the shared monospace stack for
code. The current container is at most 1080px wide, with article text limited to
760px. Reuse the existing heading sizes, line heights, section spacing and
component classes.
Whitespace separates ideas. Thin rules identify sections. Headings establish
hierarchy. The blue accent identifies something useful. Keep these elements
consistent rather than adding a new treatment for each page. Decorative
gradients, large shadows and scroll effects do not help explain the examples.
Agent terminals contain short, copyable prompts. Use the existing continuous
cursor animation and reduced-motion behavior. Label an example prompt as an
example; a real recorded result belongs in an evidence block. Copy buttons
should copy only the intended text, without the prompt symbol or cursor.
Use `minmax(0, 1fr)` for grid tracks that contain long commands or nested panels.
Allow code blocks to scroll within their own area. Check expanded details as
well as the default page. Document-level horizontal scrolling usually means a
component needs a width constraint; hiding it can conceal content.
## Keep evidence accurate and public
Preserve target identity, source locations, relevant versions and the scope of
checks. Keep observations, interpretation and unknowns distinguishable in plain
language. Put lengthy provenance in an evidence document or collapsed details.
Label simplified source and selected instruction excerpts. When compiler checks
apply to the maintained project source, say so; a readable summary is a separate
presentation of the calculation. Historical checks and a fresh REA inspection
retain their own dates and attribution.
Use generic example data and display paths. Machine paths, personal account
identifiers, credentials, local configuration, full vendor bundles and raw
captures belong outside the public website. If a path is shortened in a displayed
query, identify that in its caption and keep the original capture separately.
## Review and publish
Before merging a change:
- Read the default page in order. Check that every section advances the task.
- Open details and confirm that sources and extra examples remain usable.
- Verify commands, prerequisites, expected results and downloadable files.
- Keep links and asset paths working at both `/` and `/rea/`.
- Check desktop, intermediate and mobile widths, including 320px.
- Check copying, downloads, code-step selection, keyboard access and reduced
motion. Core content and native details should work without JavaScript.
- Confirm that figures and code excerpts agree with the supporting evidence.
- Run site preparation, verification and formatting checks.
Match verification to the change. Copy edits need page and interaction checks.
New analysis or behavior claims need the real evidence that supports them; a mock
or a page-loading check cannot establish those claims.
Follow the PR review and CI process, then publish using the existing manual
`website-pages.yml` workflow on `main`. Ordinary commits should not publish the
site. After deployment, check the live page and confirm it matches the reviewed
version. The legacy VitePress build remains separate from the Pages publisher.