Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
docs(website): clarify guides and case studies
Ysopwnable5065fcd5205e
diff --git a/README.md b/README.mdindex 7166c0c96..896bd4277 100644--- a/README.md+++ b/README.md@@ -17,7 +17,7 @@<a href="https://trendshift.io/repositories/82054?utm_source=repository-badge&utm_medium=badge&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)diff --git a/website/AGENTS.md b/website/AGENTS.mdnew file mode 100644index 000000000..a4bf9b8dc--- /dev/null+++ b/website/AGENTS.md@@ -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.diff --git a/website/README.md b/website/README.mdindex 515e77238..b7f8bc668 100644--- a/website/README.md+++ b/website/README.md@@ -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 smallscript for copying code and following the assembly-to-C comparison. Pythonpackages 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 previewFrom 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 explainthe 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 genericexample data belong on the site. Machine paths, account identifiers, localconfiguration, complete vendor bundles and raw captured results stay outsidethe website.diff --git a/website/figures.md b/website/figures.mdindex ddd233677..525c3df1c 100644--- a/website/figures.md+++ b/website/figures.md@@ -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.diff --git a/website/public/assets/figures/dx-ball-sound-pan-investigation.svg b/website/public/assets/figures/dx-ball-sound-pan-investigation.svgindex 103bd751b..b1a2a51bc 100644--- a/website/public/assets/figures/dx-ball-sound-pan-investigation.svg+++ b/website/public/assets/figures/dx-ball-sound-pan-investigation.svg@@ -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>diff --git a/website/public/assets/styles.css b/website/public/assets/styles.cssindex ce65e9ad3..d184cb31e 100644--- a/website/public/assets/styles.css+++ b/website/public/assets/styles.css@@ -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 {diff --git a/website/public/get-started/index.html b/website/public/get-started/index.htmlindex 15314573f..95b530eaf 100644--- a/website/public/get-started/index.html+++ b/website/public/get-started/index.html@@ -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 yourterminal.@@ -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 choicesinclude 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_PUBLICexport JAVA_HOME=/absolute/path/to/jdk-21npx -y rea-agents@latest doctor --provider ghidra --jsonnpx rea-agents@latest setup</code></pre>- </div>+ </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>- 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.+ 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>- </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>+ <p>+ On macOS, complete Hopper's first-run choice of demo mode+ or license activation before an unattended analysis.+ </p>+ </div></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>+ <div class="provider">+ <h3>IDA</h3>+ <div><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:+ 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>- <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"+ <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 --jsonnpx 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">diff --git a/website/public/guides/browser/index.html b/website/public/guides/browser/index.htmlindex 6c643bd0e..5924d31ec 100644--- a/website/public/guides/browser/index.html+++ b/website/public/guides/browser/index.html@@ -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 startsa 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</spandiff --git a/website/public/guides/index.html b/website/public/guides/index.htmlindex 93780a193..8fae41633 100644--- a/website/public/guides/index.html+++ b/website/public/guides/index.html@@ -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 & 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>diff --git a/website/public/guides/javascript/index.html b/website/public/guides/javascript/index.htmlindex f52bb2161..4c56189ba 100644--- a/website/public/guides/javascript/index.html+++ b/website/public/guides/javascript/index.html@@ -35,10 +35,10 @@<a href="../../">Home</a> / <a href="../">Guides</a> / JavaScript& 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 & 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 inputsdiff --git a/website/public/guides/native/index.html b/website/public/guides/native/index.htmlindex 48237b101..bbb1ece47 100644--- a/website/public/guides/native/index.html+++ b/website/public/guides/native/index.html@@ -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-Ball1.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">diff --git a/website/public/showcase/dx-ball/index.html b/website/public/showcase/dx-ball/index.htmlindex 7257c30c5..027547c6d 100644--- a/website/public/showcase/dx-ball/index.html+++ b/website/public/showcase/dx-ball/index.html@@ -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 andWindows 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>diff --git a/website/public/showcase/index.html b/website/public/showcase/index.htmlindex 88bae4637..71f613ba7 100644--- a/website/public/showcase/index.html+++ b/website/public/showcase/index.html@@ -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'sinstructions, 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 itsmultiply, 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 abrowser 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">diff --git a/website/public/showcase/notion/index.html b/website/public/showcase/notion/index.htmlindex bc4d265a6..ae9c70e33 100644--- a/website/public/showcase/notion/index.html+++ b/website/public/showcase/notion/index.html@@ -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: "<p>Project notes</p>"</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"><copy-id></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.+ Clipboard format recorded from web assets cached on July 13, 2026.</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+ <section class="article-section" id="continue">+ <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>- <div class="notion-table-example">- <div class="code-block">- <div class="code-header"><span>Markdown input</span></div>- <pre><code>| A | B |+ <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+ <div class="code-block">+ <div class="code-header">+ <span>Structured parser output · excerpt</span>+ </div>+ <pre><code>table · headerRow: truetable_rowcells: ["A"], ["B"]table_rowcells: ["1"], ["2"]</code></pre>+ </div></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.- </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>+ <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 wrapperimplementations 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>diff --git a/website/public/showcase/th04/index.html b/website/public/showcase/th04/index.htmlindex 07de3370a..a5a27b564 100644--- a/website/public/showcase/th04/index.html+++ b/website/public/showcase/th04/index.html@@ -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.diff --git a/website/style-guide.md b/website/style-guide.mdnew file mode 100644index 000000000..f7154a56b--- /dev/null+++ b/website/style-guide.md@@ -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.