+ ›Install REA and connect it to this coding agent using npx
+ rea-agents@latest setup. Show me the setup plan for approval,
+ then verify the installation.
+
+
+
Or run this command in your terminal:
+
+ npx rea-agents@latest setup
+
+
+
+ Review the plan, approve the setup, then restart your agent.
+ Already connected? Continue below.
+
+
+
+
2. Ask where the CSV is written
+
+ The example is a six-file Electron app with an
+ Export notes button. Your agent can inspect its
+ code without installing or launching Electron.
+
+
+
+ Your coding agent
+
+
+
+ ›Download https://rea.tools/examples/notes-example.zip into a
+ new example folder and unpack it. Use REA to find what happens
+ when I click Export notes. Show where notes.csv is written,
+ which fields it contains, and the relevant files and
+ lines.
+
+
+
+ Your agent downloads the files and gives the unpacked folder to
+ REA for inspection.
+
+ If your agent can’t download files, unzip this archive yourself.
+ Give it the path to the notes-example folder and the
+ same export question.
+
+
+
+
3. Follow the answer back to the code
+
Look for a short explanation with file and line references:
+
+
+ The button sends a notes:export message. The main
+ process formats the notes as CSV and writes
+ notes.csv in the user’s Downloads folder. The
+ columns are id and title.
+
+ A comma separates CSV columns. What happens when a note title
+ itself contains a comma or quotation marks?
+
+
+
+ Your coding agent
+
+
+
+ ›Predict the CSV for a note with id 1 and title Hello, "REA".
+ Then run the example’s toCsv formatter with Node.js to check
+ it. Show the prediction and actual output.
+
+
+
+
+ Expected formatter output
+
+
id,title
+1,"Hello, ""REA"""
+
+
+ The title stays in one quoted field; each quotation mark is
+ doubled. This checks the formatter directly with Node.js.
+
+
+ Run the check yourself
+
+ Open a terminal in the unpacked
+ notes-example folder:
+
- Use REA with your coding agent to inspect binaries, trace application
- code and observe runtime behavior.
+ REA gives your agent the tools to inspect a program and explain what
+ it does.
// x is the horizontal position
+double pan = (double)x;
+pan *= 1.5625;
+pan -= 500.0;
+pan *= pan_scale;
+return (int)pan;
+
+
+
+
+ Left side
+
+
+
+ x = 0 → pan = −500
+ Sound to the left
+
+
+ Center
+
+
+
+ x = 320 → pan = 0
+ Centered sound
+
+
+ Right side
+
+
+
+ x = 640 → pan = +500
+ Sound to the right
+
+
+
+ Examples of the calculation with the recorded initial scale of 1.
+ The code is a readable summary of the inspected function.
+
+
+
+ To explain this, an analyst identifies the input, follows the caller
+ and reads the values at those addresses.
+
+
+
+
+
+
+
+
+
Do I need to read assembly to get started?
+
No.
+
Ask your agent about the behavior you want to understand.
+
+
+
+
+ Example analysis · DX-Ball
+
+
+
Target · DXBALL.EXE
+
+ ›Use REA to inspect this DX-Ball executable. How does it
+ calculate left/right sound panning? Show the relevant
+ code.
+
+
+
+ Agent · explanation from the findings
+
+
+ This function converts a brick’s horizontal position into a
+ left/right sound value.
+
+
+ At the initial scale of 1, the screen center produces zero.
+ Positions to the left produce negative values; positions to
+ the right produce positive values.
+
+
+
+
+ Example prompt and explanation based on the recorded
+ investigation. Supply the executable to your agent.
+
+
+
+
+
What REA found for the agent
+
+
+ 01 · Inspect the function
+ An integer input
+ The instructions read [EBP + 0x8]. The initial
+ pseudocode had missed this input.
+
+
+ 02 · Follow the caller
+ A brick’s screen position
+ The caller passes 20 + 30 × tile_x, giving the
+ input its meaning.
+
+
+ 03 · Read the stored data
+ The calculation’s constants
+ Byte reads supply 1.5625, 500.0 and
+ the initial scale 1.0.
+
+
+
+ The agent uses these findings to explain the behavior and write
+ readable C.
+
+
+
+ The reconstruction project checked its maintained C function against
+ 3,205 original-x86 input cases and all 63 compiled bytes.
+ See the code and checks.
+
+
+
+
+
+
+
+
Your first investigation
+
Try REA on a small app.
+
+ Find out where an app exports its notes, then check how it formats
+ a title containing commas and quotes.
+
+
We provide the example files, a prompt and a result to check.
+ ›Install REA and connect it to this coding agent using npx
+ rea-agents@latest setup. Show me the setup plan for approval,
+ then verify the installation.
+
+
+
Or run this command in your terminal:
+
+ npx rea-agents@latest setup
-
- ›Install REA and connect it to this coding agent using npx
- rea-agents@latest setup. Show me the setup plan for approval,
- then verify the installation.
+
+ Setup shows a plan for approval. Restart your agent after setup.
-
Or run this command in your terminal:
-
- npx rea-agents@latest setup
-
-
@@ -139,34 +333,6 @@
-
-
-
-
-
-
-
- REA connects your agent to analysis tools. The findings guide the
- next question, explanation or implementation.
- Open figure
-
-
-
-
-
@@ -177,12 +343,6 @@
in C, using REA to inspect the executable and independent tests to
check the recovered behavior.
-
- To recover a sound-pan calculation, the agent used REA to inspect
- the instructions, follow a caller and read the constants. Those
- findings led to a C function checked against the original behavior
- and all 63 compiled bytes.
-
Follow the investigation
Date: Fri, 9 Oct 2026 11:06:05 +0800
Subject: [PATCH 2/6] feat(website): explain REA with Calculator and a playable
dinosaur lab
---
website/README.md | 31 +-
website/evidence/calculator-and-dino.md | 132 ++++
website/evidence/dx-ball-sound-pan.md | 6 -
website/figures.md | 15 +
website/public/assets/dino-demo.js | 235 ++++++
website/public/assets/dino-speed.js | 21 +
website/public/assets/home.js | 56 ++
website/public/assets/licenses/dinosaur.txt | 34 +
website/public/assets/styles.css | 332 ++++++++
website/public/examples/dino-lab/index.html | 332 ++++++++
website/public/first-investigation/index.html | 2 +-
website/public/index.html | 711 +++++++++++++-----
website/style-guide.md | 28 +-
13 files changed, 1716 insertions(+), 219 deletions(-)
create mode 100644 website/evidence/calculator-and-dino.md
create mode 100644 website/public/assets/dino-demo.js
create mode 100644 website/public/assets/dino-speed.js
create mode 100644 website/public/assets/home.js
create mode 100644 website/public/assets/licenses/dinosaur.txt
create mode 100644 website/public/examples/dino-lab/index.html
diff --git a/website/README.md b/website/README.md
index 896dac213..cbe151232 100644
--- a/website/README.md
+++ b/website/README.md
@@ -6,7 +6,8 @@
An English static website with explanatory figures, worked guides and DX-Ball, Notion, TH04 and CTF 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
+scripts for copying code, following code comparisons and playing the dinosaur
+speed reconstruction. 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,
@@ -25,7 +26,8 @@ Open . Refresh the browser after editing a file.
## Pages
-- `public/index.html`: DX-Ball introduction, agent example, setup and case-study overviews.
+- `public/index.html`: compact setup, manual/agent comparison, Calculator percentage example, playable dinosaur reconstruction and case-study overviews.
+- `public/examples/dino-lab/index.html`: adjustable-speed mini-game, recovered rule, original-game check and browser analysis steps.
- `public/first-investigation/index.html`: a guided Notes export investigation, from setup to a checked CSV prediction.
- `public/showcase/index.html`: the case-study index.
- `public/showcase/dx-ball/index.html`: sound-pan investigation and project status.
@@ -95,11 +97,26 @@ Evidence. [evidence/dx-ball-sound-pan.md](evidence/dx-ball-sound-pan.md) records
their provenance and the scope of the validation claims. The original executable
and complete private Evidence records are not website assets.
-The homepage's code comparison, position examples and evidence flow are
-selectable HTML. The pan positions 0, 320 and 640 illustrate the inspected
-calculation at its recorded initial scale of 1; the C panel is a readable
-summary. The linked case study retains the maintained source and its checks.
-The agent response is an example explanation based on those findings.
+The homepage starts with a short installation prompt and the ordinary setup
+command. It compares manual investigation with asking an agent, using the same
+Calculator percentage question. The native excerpt comes from an installed
+model DLL; Microsoft’s public implementation supplies names and a crosscheck.
+The Calculator controls illustrate that rule with generic inputs.
+
+The dinosaur example connects an inspected running script to a new playable
+mini-game. `public/assets/dino-speed.js` owns the recovered speed rule and replay;
+`dino-demo.js` imports it for automatic acceleration. The slider chooses a fixed
+speed instead. Drawing, jumping and collision code are newly authored for this
+teaching game. It starts on input, pauses when hidden or outside the viewport,
+and retains a static SVG when JavaScript is disabled. The lab links the speed
+module and complete game source, and replays the rule against recorded
+original-game values.
+
+[evidence/calculator-and-dino.md](evidence/calculator-and-dino.md) records both
+targets, selected findings, attribution and verification scope. Update the
+speed rule, game, check table and evidence together. The original script excerpt
+and its BSD license are credited on the pages. Prompt responses are example
+explanations based on findings.
The general investigation and DX-Ball overview diagrams are maintained as SVG source. Initial layout references were
created with the built-in image generation tool; [figures.md](figures.md) retains
diff --git a/website/evidence/calculator-and-dino.md b/website/evidence/calculator-and-dino.md
new file mode 100644
index 000000000..67d816014
--- /dev/null
+++ b/website/evidence/calculator-and-dino.md
@@ -0,0 +1,132 @@
+# Calculator and dinosaur beginner examples
+
+Evidence collected on 9 October 2026 with the published REA 4.1.0 package.
+The homepage offers compact setup first, then a manual/agent comparison and
+two familiar behavior questions. Prompts and replies are examples based on the
+findings below. Selected code and generic inputs are public; raw captures stay
+outside the website.
+
+## Windows Calculator
+
+### Inspected artifacts
+
+The installed Windows Calculator package is version `11.2508.4.0`, x64.
+
+| Artifact | SHA-256 |
+| --------------------------- | ------------------------------------------------------------------ |
+| Windows `calc.exe` launcher | `9c2c8a8588fe6db09c09337e78437cb056cd557db1bcf5240112cbfb7b600efb` |
+| Package `CalcViewModel.dll` | `07a1953bbf828a3495662c4b4bde1c80c9075061e0e389eabac5f8c544710df5` |
+
+REA's function dossier for launcher `0x1400019f4` includes the call to
+`ShellExecuteW` with `ms-calculator:`. Evidence:
+`ev_e97a6a1a61bfe63476a13e6285d71dd838101066f7863c9af822861050203ea5`.
+
+The calculation is in the installed app's model DLL. REA inspected function
+`0x1801245d0`, whose body occupies two ranges, totaling 10,656 bytes:
+`0x1801245d0–0x180126f4c` and `0x180126f55–0x180126f77`.
+Evidence:
+`ev_830a710c7fb55a08ac896fb5783c14339480a57a96d6d45c57c024b6a43239d0`.
+
+REA supplied pseudocode, original instructions, calls and references. Its
+`case 0x76` checks the operator field against `0x5c` and `0x5b` and constructs
+the constant 100 in both paths. One path divides the current value by 100;
+the other combines the current value with the previous value divided by 100.
+The published assembly is selected exactly from the returned instruction list.
+
+The binary is stripped. A local instruction scan located candidates using
+operator IDs and the constant 100; REA then produced the complete function
+dossier. Function selection was analyst-assisted. The illustrative agent
+prompt is not a recording of an autonomous end-to-end discovery.
+
+### Source interpretation and check
+
+Microsoft's MIT-licensed source at commit
+`d125246a4e19842ce1332e6c7839cf0e110027d8` supplies the operator meanings and
+an independently readable implementation:
+
+- [Operator IDs](https://github.com/microsoft/calculator/blob/d125246a4e19842ce1332e6c7839cf0e110027d8/src/CalcManager/Header%20Files/CCommand.h): `IDC_DIV = 91`, `IDC_MUL = 92`, `IDC_PERCENT = 118`.
+- [Percentage branch](https://github.com/microsoft/calculator/blob/d125246a4e19842ce1332e6c7839cf0e110027d8/src/CalcManager/CEngine/scifunc.cpp#L98-L111): multiply/divide uses `rat / 100`; other operators use `rat * (m_lastVal / 100)`.
+- [Standard-mode tests](https://github.com/microsoft/calculator/blob/d125246a4e19842ce1332e6c7839cf0e110027d8/src/CalculatorUnitTests/CalculatorManagerTest.cpp#L350-L370): `6 × 6 % = 0.36` and `50 + 20 % = 60`.
+
+These source branches agree with the operator checks and two paths observed
+in the installed DLL. The public source commit is a crosscheck; it is not an
+identified build commit for that installed package. No PDB symbols were loaded.
+
+The homepage's named C-like rule is an explanatory summary. Its `200 + 10%`
+and `200 × 10%` displays are derived from that rule. Browser checks exercise
+both percentage illustrations, their results, operator selection and reset.
+The Microsoft tests were inspected, not executed. A probe-owned Calculator
+window could be inspected, but it was no longer present at the input-check
+step; no completed Windows GUI input result is claimed.
+
+## Dinosaur speed
+
+### Running target and source
+
+REA inspected the HTTP page
+ in an owned Chrome 150.0.7871.124
+session through a loopback debugging connection. This is wayou's
+Chromium-derived browser edition. REA's HTTP(S) page inspection does not
+select `chrome://dino/`; the website identifies the HTTP edition as its target.
+
+The returned `index.js` source contains 90,241 UTF-8 bytes, SHA-256
+`e7a50d337bdbe4299068de034e4564cfe5fd45ca9257ded37b6ada9330cedf0f`.
+Evidence:
+`ev_7a09de570cf6b64907504046485cab69ad444828964106eabc05958799749905`.
+
+This digest also matches `index.js` in repository commit
+`5455bfa408ec6b707c7300ff194b7390733a766d`. Source locations:
+
+- [Settings](https://github.com/wayou/t-rex-runner/blob/5455bfa408ec6b707c7300ff194b7390733a766d/index.js#L106-L135): `ACCELERATION: 0.001`, `MAX_SPEED: 13`, `SPEED: 6`.
+- [Update branch](https://github.com/wayou/t-rex-runner/blob/5455bfa408ec6b707c7300ff194b7390733a766d/index.js#L565-L571): increment speed on a collision-free update while speed is below the threshold.
+
+The source begins with the Chromium Authors' 2014 copyright notice. Selected
+excerpts are credited on the page. The repository's BSD license and the source
+copyright are reproduced in `public/assets/licenses/dinosaur.txt`.
+
+### Controlled original-game check
+
+After the passive REA inspection, a separate Playwright controller called the
+original page's `Runner.update()` repeatedly. It disabled future update
+scheduling and obstacle generation, set the starting speed to 6, and kept the
+game in its playing state. The control is credited separately from REA's
+read-only inspection.
+
+| Update count | Observed speed | Display rounded to 3 decimals |
+| ------------ | ------------------ | ----------------------------- |
+| 0 | 6 | 6.000 |
+| 1,000 | 7.000000000000334 | 7.000 |
+| 4,000 | 9.99999999999956 | 10.000 |
+| 7,000 | 12.999999999997897 | 13.000 |
+| 10,000 | 13.000999999997896 | 13.001 |
+
+The branch compares before adding. Floating-point increments can cross the
+threshold by one increment; the reconstruction preserves this behavior rather
+than introducing a clamp.
+
+### New game and reader experiment
+
+`public/assets/dino-speed.js` contains the reconstructed rule and an update-count
+replay. Its rounded results match the original-game check above. The website's
+mini-game imports this rule. It advances its own simulation at 60 updates per
+second, avoiding a different frame rate changing its demonstration pace.
+
+The canvas drawing, dinosaur shape, jump physics, rectangle collision detection,
+spacing and controls are newly authored teaching code. The reconstruction claim
+is scoped to the speed rule. Changing the slider selects a fixed speed between
+2 and 18; selecting automatic acceleration restores the starting speed of 6.
+
+The new game starts only after user input. It supports Play/Pause, Jump, Restart,
+canvas Space/Up keys and touch. It pauses when hidden or scrolled out of view.
+Without JavaScript, a static SVG, source excerpts and recorded results remain
+available. The downloadable speed module and complete game source are linked
+from the lab.
+
+## Review checks
+
+Website checks cover root and `/rea/` hosting, 320/390/850/1440px layouts,
+expanded evidence, copying, no-JavaScript content, reduced motion, the two
+percentage rules and the game controls. Game checks include speed selection,
+automatic acceleration, a collision, restart, jump height on the rendered
+canvas, pause and the original-rule replay. Existing Notes and DX-Ball pages
+remain part of layout checks.
diff --git a/website/evidence/dx-ball-sound-pan.md b/website/evidence/dx-ball-sound-pan.md
index ec02d2705..60b7e0e61 100644
--- a/website/evidence/dx-ball-sound-pan.md
+++ b/website/evidence/dx-ball-sound-pan.md
@@ -96,12 +96,6 @@ signature, declaration and return.
## Validation scope
-The homepage reuses these observations in a selected seven-instruction excerpt
-and a shortened C summary. Its agent answer is an example explanation, not a
-recorded transcript. Its position figure uses illustrative inputs 0, 320 and
-640 with the recorded initial scale of 1, producing −500, 0 and 500. The checks
-below apply to the maintained project function, not the shortened summary.
-
The reconstruction project's recorded checks establish:
- 3,205 direct original-x86 differential cases: integer positions 0–640 at
diff --git a/website/figures.md b/website/figures.md
index ff8f7bba3..c94db54f9 100644
--- a/website/figures.md
+++ b/website/figures.md
@@ -42,6 +42,21 @@ branches when changing these figures. Match progress claims to the pinned
reconstruction checkpoint. Validate the SVG as XML and inspect its browser
rendering at desktop and mobile widths.
+## Beginner homepage and dinosaur reconstruction
+
+The Calculator role comparison and its percentage controls are semantic HTML.
+The assembly comes from a real installed model DLL; the named calculation is
+a readable summary crosschecked against Microsoft’s public source. See
+[evidence/calculator-and-dino.md](evidence/calculator-and-dino.md).
+
+The dinosaur sequence uses an HTML flow: inspect the loaded script, rebuild the
+speed rule, then change and play. Its canvas mini-game and static SVG fallback
+are authored code, without generated images or copied game sprites. The game
+imports the recovered rule from `public/assets/dino-speed.js`; other mechanics
+are new teaching code. Check that the fallback is visible with JavaScript
+disabled and hidden when the playable canvas loads. Keep the speed settings,
+source excerpt, reconstruction and original-result table consistent.
+
## Original image generation prompts
## Prompt 1
diff --git a/website/public/assets/dino-demo.js b/website/public/assets/dino-demo.js
new file mode 100644
index 000000000..9988e9f52
--- /dev/null
+++ b/website/public/assets/dino-demo.js
@@ -0,0 +1,235 @@
+import { advanceSpeed, simulateSpeed, SPEED_RULE } from "./dino-speed.js";
+
+// A new teaching game around the recovered speed rule. Drawing, jump physics
+// and rectangle collision checks are authored for this demo.
+function initializeDinoDemo(demo) {
+ const canvas = demo.querySelector("canvas");
+ const context = canvas.getContext("2d");
+ if (context === null) return;
+ const start = demo.querySelector("[data-dino-start]");
+ const slider = demo.querySelector("[data-dino-slider]");
+ const auto = demo.querySelector("[data-dino-auto]");
+ const output = demo.querySelector("[data-dino-speed]");
+ const status = demo.querySelector("[data-dino-status]");
+ const ground = 148;
+ const dinosaurX = 52;
+ const dinosaur = new Path2D(
+ "M16 18V2H48V24H35V32H25V43H16V53H8V32H0V23H6V29H16Z M12 47V59H5V54H8V47Z M24 42V54H31V59H20V47Z M34 29H44V35H39V32H34Z",
+ );
+ let speed = SPEED_RULE.start;
+ let height = 0;
+ let velocity = 0;
+ let distance = 0;
+ let obstacles = [];
+ let running = false;
+ let crashed = false;
+ let frame = 0;
+ let lastTime = 0;
+ let elapsed = 0;
+
+ const updateSpeedDisplay = () => {
+ output.value = speed.toFixed(1);
+ slider.value = speed.toFixed(1);
+ };
+
+ const draw = () => {
+ context.clearRect(0, 0, canvas.width, canvas.height);
+ context.strokeStyle = "#b7c0c9";
+ context.beginPath();
+ context.moveTo(0, ground);
+ context.lineTo(canvas.width, ground);
+ for (let x = -(distance % 70); x < canvas.width; x += 70) {
+ context.moveTo(x, ground + 7);
+ context.lineTo(x + 12, ground + 7);
+ }
+ context.stroke();
+ context.fillStyle = "#5b6570";
+ for (const obstacle of obstacles) {
+ context.fillRect(
+ obstacle.x + 6,
+ ground - obstacle.height,
+ 8,
+ obstacle.height,
+ );
+ context.fillRect(obstacle.x, ground - obstacle.height + 12, 6, 7);
+ context.fillRect(obstacle.x, ground - obstacle.height + 3, 5, 15);
+ context.fillRect(obstacle.x + 14, ground - obstacle.height + 19, 7, 6);
+ context.fillRect(obstacle.x + 17, ground - obstacle.height + 8, 4, 17);
+ }
+ context.save();
+ context.translate(dinosaurX, ground - 59 - height);
+ context.fillStyle = crashed ? "#8c4b40" : "#294f82";
+ context.fill(dinosaur);
+ context.fillStyle = "#ffffff";
+ context.fillRect(39, 7, 4, 4);
+ context.restore();
+ context.fillStyle = "#5b6570";
+ context.font = "13px monospace";
+ context.textAlign = "right";
+ context.fillText(
+ `DISTANCE ${String(Math.floor(distance / 100)).padStart(4, "0")}`,
+ 580,
+ 28,
+ );
+ if (!running) {
+ context.textAlign = "center";
+ context.font = "15px system-ui";
+ context.fillText(
+ crashed ? "Hit a cactus. Try another speed." : "Space or Jump ↑",
+ 330,
+ 85,
+ );
+ }
+ };
+
+ const stop = (message) => {
+ running = false;
+ cancelAnimationFrame(frame);
+ start.textContent = crashed ? "Play again" : "Play";
+ if (message) status.textContent = message;
+ draw();
+ };
+
+ const reset = () => {
+ stop();
+ crashed = false;
+ height = 0;
+ velocity = 0;
+ distance = 0;
+ obstacles = [{ x: 550, height: 38 }];
+ if (auto.checked) speed = SPEED_RULE.start;
+ elapsed = 0;
+ start.textContent = "Play";
+ status.textContent = "Press Play, then jump over the cactus.";
+ updateSpeedDisplay();
+ draw();
+ };
+
+ const update = () => {
+ if (auto.checked) speed = advanceSpeed(speed);
+ distance += speed;
+ if (height > 0 || velocity > 0) {
+ height = Math.max(0, height + velocity);
+ velocity -= 0.55;
+ if (height === 0) velocity = 0;
+ }
+ obstacles.forEach((obstacle) => {
+ obstacle.x -= speed;
+ });
+ obstacles = obstacles.filter((obstacle) => obstacle.x > -25);
+ const last = obstacles[obstacles.length - 1];
+ const gap = 400 + speed * 18;
+ if (last === undefined || last.x < 600 - gap) {
+ obstacles.push({ x: 600, height: 38 });
+ }
+ const left = dinosaurX + 8;
+ const right = dinosaurX + 39;
+ const bottom = ground - height;
+ if (
+ obstacles.some(
+ (obstacle) =>
+ right > obstacle.x &&
+ left < obstacle.x + 21 &&
+ bottom > ground - obstacle.height + 4,
+ )
+ ) {
+ crashed = true;
+ stop("Hit a cactus. Press Play again, or change the speed and restart.");
+ }
+ };
+
+ const animate = (time) => {
+ if (!running) return;
+ elapsed += Math.min(time - lastTime, 100);
+ lastTime = time;
+ while (elapsed >= 1000 / 60 && running) {
+ elapsed -= 1000 / 60;
+ update();
+ }
+ updateSpeedDisplay();
+ draw();
+ if (running) frame = requestAnimationFrame(animate);
+ };
+
+ const play = () => {
+ if (crashed) reset();
+ if (running) return;
+ running = true;
+ lastTime = performance.now();
+ elapsed = 0;
+ start.textContent = "Pause";
+ status.textContent = "Running. Space or Jump clears a cactus.";
+ frame = requestAnimationFrame(animate);
+ };
+
+ const jump = () => {
+ if (crashed) reset();
+ play();
+ if (height === 0) velocity = 10.5;
+ };
+
+ start.addEventListener("click", () => {
+ if (running) stop("Paused. Press Play to continue.");
+ else play();
+ });
+ demo.querySelector("[data-dino-jump]").addEventListener("click", jump);
+ demo.querySelector("[data-dino-reset]").addEventListener("click", reset);
+ canvas.addEventListener("keydown", (event) => {
+ if (event.code === "Space" || event.code === "ArrowUp") {
+ event.preventDefault();
+ if (!event.repeat) jump();
+ }
+ });
+ canvas.addEventListener("pointerdown", () => {
+ canvas.focus();
+ jump();
+ });
+ slider.addEventListener("input", () => {
+ auto.checked = false;
+ speed = Number(slider.value);
+ updateSpeedDisplay();
+ status.textContent = running
+ ? `Fixed speed: ${speed.toFixed(1)}. Space or Jump clears a cactus.`
+ : `Fixed speed: ${speed.toFixed(1)}. Press Play to try it.`;
+ draw();
+ });
+ auto.addEventListener("change", () => {
+ if (auto.checked) speed = SPEED_RULE.start;
+ updateSpeedDisplay();
+ status.textContent = auto.checked
+ ? "Recovered rule: start at 6, then increase toward 13."
+ : `Fixed speed: ${speed.toFixed(1)}.`;
+ });
+ document.addEventListener("visibilitychange", () => {
+ if (document.hidden && running) stop("Paused. Press Play to continue.");
+ });
+ if ("IntersectionObserver" in window) {
+ new IntersectionObserver((entries) => {
+ if (!entries[0].isIntersecting && running)
+ stop("Paused. Press Play to continue.");
+ }).observe(demo);
+ }
+ demo.querySelector(".dino-fallback").setAttribute("hidden", "");
+ demo.querySelector(".dino-controls").hidden = false;
+ canvas.hidden = false;
+ reset();
+}
+
+document.querySelectorAll("[data-dino-demo]").forEach(initializeDinoDemo);
+
+const speedCheck = document.querySelector("[data-speed-check]");
+if (speedCheck !== null) speedCheck.hidden = false;
+speedCheck?.addEventListener("click", () => {
+ let matches = true;
+ document.querySelectorAll("[data-speed-updates]").forEach((cell) => {
+ const speed = simulateSpeed(
+ Number(cell.getAttribute("data-speed-updates")),
+ ).toFixed(3);
+ cell.textContent = speed;
+ matches =
+ matches && speed === cell.parentElement.children[1].textContent.trim();
+ });
+ document.querySelector("[data-speed-check-status]").textContent = matches
+ ? "Replayed the recovered rule. All four values match the controlled original-game check when rounded to three decimals."
+ : "The replay differs from the recorded original-game values. Compare the speed rule and settings above.";
+});
diff --git a/website/public/assets/dino-speed.js b/website/public/assets/dino-speed.js
new file mode 100644
index 000000000..df90fcfa4
--- /dev/null
+++ b/website/public/assets/dino-speed.js
@@ -0,0 +1,21 @@
+// Speed rule recovered from wayou's Chromium-derived browser edition.
+// Source and controlled checks: website/evidence/calculator-and-dino.md.
+export const SPEED_RULE = Object.freeze({
+ start: 6,
+ acceleration: 0.001,
+ threshold: 13,
+});
+
+/** Advance one collision-free update using the inspected speed rule. */
+export function advanceSpeed(speed) {
+ return speed < SPEED_RULE.threshold ? speed + SPEED_RULE.acceleration : speed;
+}
+
+/** Replay the recovered rule for a chosen number of updates. */
+export function simulateSpeed(updates) {
+ let speed = SPEED_RULE.start;
+ for (let update = 0; update < updates; update += 1) {
+ speed = advanceSpeed(speed);
+ }
+ return speed;
+}
diff --git a/website/public/assets/home.js b/website/public/assets/home.js
new file mode 100644
index 000000000..61f22231b
--- /dev/null
+++ b/website/public/assets/home.js
@@ -0,0 +1,56 @@
+function initializePercentDemo() {
+ const demo = document.querySelector("[data-percent-demo]");
+ if (demo === null) return;
+ const display = demo.querySelector("[data-percent-display]");
+ const expression = demo.querySelector("[data-percent-expression]");
+ const status = demo.querySelector("[data-percent-status]");
+ const equals = demo.querySelector('[data-percent-key="equals"]');
+ const operations = demo.querySelectorAll("[data-percent-operation]");
+ let operation = "add";
+ let stage = "input";
+
+ const render = () => {
+ const adding = operation === "add";
+ const percent = adding ? 20 : 0.1;
+ const result = adding ? 220 : 20;
+ const operator = adding ? "+" : "×";
+ expression.textContent =
+ stage === "result" ? `200 ${operator} ${percent} =` : `200 ${operator}`;
+ display.textContent = String(
+ stage === "input" ? 10 : stage === "percent" ? percent : result,
+ );
+ equals.disabled = stage !== "percent";
+ status.textContent =
+ stage === "input"
+ ? "Press % to see what happens to 10."
+ : stage === "percent"
+ ? adding
+ ? "10% of 200 is 20. Press = to add it."
+ : "For multiplication, 10 becomes 0.1. Press = to multiply."
+ : `200 ${operator} ${percent} = ${result}.`;
+ };
+
+ operations.forEach((button) => {
+ button.addEventListener("click", () => {
+ operation = button.getAttribute("data-percent-operation");
+ stage = "input";
+ operations.forEach((candidate) => {
+ candidate.setAttribute("aria-pressed", String(candidate === button));
+ });
+ render();
+ });
+ });
+ demo.querySelectorAll("[data-percent-key]").forEach((button) => {
+ button.addEventListener("click", () => {
+ const key = button.getAttribute("data-percent-key");
+ stage =
+ key === "reset" ? "input" : key === "percent" ? "percent" : "result";
+ render();
+ });
+ });
+ demo.querySelector(".percent-operation").hidden = false;
+ demo.querySelector(".percent-controls").hidden = false;
+ render();
+}
+
+initializePercentDemo();
diff --git a/website/public/assets/licenses/dinosaur.txt b/website/public/assets/licenses/dinosaur.txt
new file mode 100644
index 000000000..88ec041e7
--- /dev/null
+++ b/website/public/assets/licenses/dinosaur.txt
@@ -0,0 +1,34 @@
+Selected script excerpts from wayou/t-rex-runner
+Copyright (c) 2014 The Chromium Authors. All rights reserved.
+
+Repository license at commit 5455bfa408ec6b707c7300ff194b7390733a766d:
+
+BSD 3-Clause License
+
+Copyright (c) 2022, 牛さん
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/website/public/assets/styles.css b/website/public/assets/styles.css
index 9a49919cc..54bf52f67 100644
--- a/website/public/assets/styles.css
+++ b/website/public/assets/styles.css
@@ -1218,6 +1218,338 @@ pre code {
border: 0;
}
+.home-start-grid {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+ gap: 3.5rem;
+ align-items: center;
+}
+.home-start-grid h1 {
+ font-size: clamp(2.8rem, 5vw, 4.2rem);
+}
+.home-start-grid .home-setup h2 {
+ font-size: 1.3rem;
+ letter-spacing: -0.02em;
+ margin-bottom: 0.7rem;
+}
+.home-start-grid .home-setup > p {
+ font-size: 0.9rem;
+ color: var(--muted);
+}
+.home-question {
+ margin-block: 0 1.8rem;
+ color: var(--muted);
+}
+.home-question strong {
+ color: var(--ink);
+ font-weight: 500;
+}
+.home-role-comparison {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+ gap: 0 2.5rem;
+ margin: 0;
+}
+.comparison-label {
+ padding-bottom: 0.8rem;
+ border-bottom: 1px solid var(--line);
+ font-size: 0.875rem;
+ font-weight: 600;
+}
+.agent-investigation > .comparison-label {
+ color: var(--accent);
+}
+.manual-steps {
+ display: grid;
+ gap: 1rem;
+ padding: 0;
+ list-style: none;
+}
+.manual-steps li {
+ display: flex;
+ gap: 1rem;
+ margin: 0;
+}
+.manual-steps li > span {
+ padding-top: 0.2rem;
+ color: var(--muted);
+ font:
+ 0.75rem "SFMono-Regular",
+ Consolas,
+ "Liberation Mono",
+ monospace;
+}
+.manual-steps strong,
+.manual-steps small {
+ display: block;
+}
+.manual-steps strong {
+ font-size: 0.95rem;
+ font-weight: 500;
+}
+.manual-steps small {
+ margin-top: 0.15rem;
+ color: var(--muted);
+ font-size: 0.8rem;
+}
+.manual-code {
+ margin-top: 1.3rem;
+ padding: 1rem 1.25rem;
+ border-left: 2px solid var(--line);
+ background: var(--soft);
+ color: var(--muted);
+ font-size: 0.8rem;
+ line-height: 1.65;
+}
+.agent-investigation-note {
+ color: var(--muted);
+ font-size: 0.875rem;
+}
+.home-role-comparison figcaption {
+ grid-column: 1 / -1;
+ margin-top: 1.2rem;
+ font-size: 0.8rem;
+ color: var(--muted);
+}
+.home-example-grid {
+ display: grid;
+ grid-template-columns: minmax(0, 0.85fr) minmax(0, 1.15fr);
+ align-items: start;
+ gap: 3rem;
+}
+.percent-figure,
+.dino-demo {
+ min-width: 0;
+ margin: 0;
+ padding: 1.5rem;
+ border: 1px solid var(--line);
+ border-radius: 5px;
+}
+.percent-operation,
+.percent-controls,
+.dino-buttons {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.5rem;
+}
+.percent-operation button,
+.percent-controls button,
+.dino-buttons button {
+ min-height: 44px;
+ border: 1px solid var(--line);
+ border-radius: 4px;
+ padding: 0.5rem 0.8rem;
+ font: inherit;
+ font-size: 0.85rem;
+ color: var(--ink);
+ background: var(--page);
+ cursor: pointer;
+}
+.percent-operation button[aria-pressed="true"] {
+ color: var(--accent);
+ border-color: var(--accent);
+ background: #edf2f8;
+}
+.percent-display {
+ padding: 1.2rem;
+ margin-block: 1rem;
+ border-radius: 4px;
+ background: var(--soft);
+ text-align: right;
+ font-variant-numeric: tabular-nums;
+}
+.percent-expression {
+ display: block;
+ min-height: 1.5rem;
+ color: var(--muted);
+ font-size: 0.9rem;
+}
+.percent-display strong {
+ font-size: 3rem;
+ font-weight: 500;
+ letter-spacing: -0.04em;
+}
+.percent-controls .percent-key {
+ min-width: 68px;
+ font-size: 1.25rem;
+ color: var(--accent);
+ border-color: #bbcce0;
+}
+.percent-controls button:disabled {
+ opacity: 0.45;
+ cursor: default;
+}
+.percent-controls .percent-reset {
+ margin-left: auto;
+ border-color: transparent;
+ color: var(--muted);
+}
+.percent-status {
+ min-height: 3rem;
+ margin-top: 1rem;
+ font-size: 0.9rem;
+}
+.percent-figure figcaption,
+.dino-demo figcaption {
+ margin-top: 0.8rem;
+ color: var(--muted);
+ font-size: 0.8rem;
+}
+.percent-explanation h3 {
+ font-size: 1.2rem;
+}
+.percent-explanation > p {
+ color: var(--muted);
+}
+.percent-rules {
+ margin-bottom: 0;
+}
+.percent-rules > div {
+ padding-block: 0.55rem;
+}
+.percent-rules dt {
+ font-size: 0.8rem;
+ color: var(--muted);
+ margin-bottom: 0.25rem;
+}
+.percent-rules dd {
+ margin: 0;
+ font-size: 0.9rem;
+}
+.home-evidence-details {
+ margin-top: 2rem;
+ padding-block: 1rem;
+ border-top: 1px solid var(--line);
+ border-bottom: 1px solid var(--line);
+}
+.home-evidence-details > summary {
+ cursor: pointer;
+ font-size: 0.875rem;
+ font-weight: 500;
+}
+.home-evidence-details[open] > summary {
+ margin-bottom: 1.5rem;
+}
+.calculator-trace {
+ margin-block: 1.5rem;
+}
+.dino-example-grid {
+ grid-template-columns: minmax(0, 1fr) minmax(0, 1.15fr);
+ gap: 2.5rem;
+}
+.dino-stage {
+ overflow: hidden;
+ margin-block: 0.8rem;
+ background: var(--soft);
+ border-radius: 4px;
+ color: var(--muted);
+}
+.dino-stage canvas,
+.dino-fallback {
+ display: block;
+ width: 100%;
+ height: auto;
+}
+.dino-stage canvas {
+ touch-action: manipulation;
+}
+.dino-buttons .button {
+ background: var(--ink);
+ border-color: var(--ink);
+ color: white;
+}
+.dino-controls {
+ display: grid;
+ gap: 1.2rem;
+}
+.dino-speed-label {
+ display: grid;
+ grid-template-columns: 1fr auto;
+ gap: 0.5rem;
+ font-size: 0.875rem;
+}
+.dino-speed-label output {
+ font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+ font-variant-numeric: tabular-nums;
+ color: var(--accent);
+}
+.dino-speed-label input {
+ grid-column: 1 / -1;
+ width: 100%;
+ margin: 0;
+ min-height: 30px;
+ accent-color: var(--accent);
+}
+.dino-auto-label {
+ display: flex;
+ align-items: center;
+ gap: 0.6rem;
+ min-height: 36px;
+ font-size: 0.8rem;
+ color: var(--muted);
+}
+.dino-auto-label input {
+ width: 17px;
+ height: 17px;
+ flex-shrink: 0;
+ accent-color: var(--accent);
+}
+.dino-status {
+ min-height: 2.6rem;
+ margin: 1rem 0 0;
+ font-size: 0.8rem;
+ color: var(--muted);
+}
+.dino-rule {
+ color: var(--muted);
+ font-size: 0.95rem;
+}
+.dino-rule strong {
+ color: var(--ink);
+}
+.dino-loop {
+ margin-top: 2rem;
+}
+.dino-lab-demo {
+ margin-block: 2rem;
+}
+.dino-lab-demo .dino-stage {
+ margin-block: 1.5rem;
+}
+.speed-check-table td:last-child,
+.speed-check-table th:last-child {
+ text-align: right;
+}
+[hidden] {
+ display: none !important;
+}
+@media (max-width: 850px) {
+ .home-start-grid,
+ .home-role-comparison,
+ .home-example-grid {
+ grid-template-columns: minmax(0, 1fr);
+ gap: 2rem;
+ }
+ .home-start-grid .home-setup {
+ max-width: 620px;
+ }
+ .home-start-grid h1 {
+ font-size: clamp(2.7rem, 9vw, 4.65rem);
+ }
+ .home-role-comparison figcaption {
+ margin-top: 0;
+ }
+}
+@media (max-width: 640px) {
+ .home-hero {
+ padding-block: 2.8rem;
+ }
+ .percent-figure,
+ .dino-demo {
+ padding: 1.1rem;
+ }
+}
+
@media (max-width: 850px) {
.home-agent-grid,
.home-try-grid {
diff --git a/website/public/examples/dino-lab/index.html b/website/public/examples/dino-lab/index.html
new file mode 100644
index 000000000..a0578a487
--- /dev/null
+++ b/website/public/examples/dino-lab/index.html
@@ -0,0 +1,332 @@
+
+
+
+ REA found how the running game increases its speed. This small
+ reconstruction lets you keep that rule or choose a new speed and play.
+
+
+
+
+
+
+
Play and change the speed
+
+ Press Play, then jump over the cactus. Move the speed slider to
+ try a slower or faster game; it switches to a fixed speed. Select
+ the recovered rule to start at 6 and gradually accelerate again.
+
+
+
Play the reconstruction
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Original rule: start at 6, then increase toward 13.
+
+
+ Move the slider to set your own speed. Space or Jump clears a
+ cactus.
+
+
+
+
+
+
+ The mini-game uses this function for automatic acceleration.
+ Moving the slider supplies a fixed speed instead. Drawing, jump
+ physics and rectangle collision checks are new code for this
+ teaching game; its simulation advances at 60 updates per second.
+
+ We called the original game’s update function with obstacles and
+ automatic scheduling disabled. Compare those recorded speeds with
+ a replay of the recovered rule.
+
+
+
+
+
+
Updates
+
Original game
+
Reconstructed rule
+
+
+
+
+
0
+
6.000
+
6.000
+
+
+
1,000
+
7.000
+
7.000
+
+
+
4,000
+
10.000
+
10.000
+
+
+
10,000
+
13.001
+
13.001
+
+
+
+
+
+
+ Values rounded to three decimals. The branch checks before adding,
+ so the final increment can take speed just above 13.
+
+
+
+
+ ↑ Top
+
+
diff --git a/website/public/first-investigation/index.html b/website/public/first-investigation/index.html
index ed687aa70..3c4828cd2 100644
--- a/website/public/first-investigation/index.html
+++ b/website/public/first-investigation/index.html
@@ -336,7 +336,7 @@ JS
How DX-Ball calculates sound panningContinue from the homepage into the original instructions and
+ >Read the original instructions and the reconstruction’s
checks.
diff --git a/website/public/index.html b/website/public/index.html
index c04b4c6b2..747e1715b 100644
--- a/website/public/index.html
+++ b/website/public/index.html
@@ -12,6 +12,8 @@
+
+
Skip to content
@@ -51,207 +53,22 @@
-
Reverse engineering, with your coding agent
-
Find out how software works.
-
- REA gives your agent the tools to inspect a program and explain what
- it does.
-
// x is the horizontal position
-double pan = (double)x;
-pan *= 1.5625;
-pan -= 500.0;
-pan *= pan_scale;
-return (int)pan;
-
-
-
-
- Left side
-
-
-
- x = 0 → pan = −500
- Sound to the left
-
-
- Center
-
-
-
- x = 320 → pan = 0
- Centered sound
-
-
- Right side
-
-
-
- x = 640 → pan = +500
- Sound to the right
-
-
-
- Examples of the calculation with the recorded initial scale of 1.
- The code is a readable summary of the inspected function.
-
-
-
- To explain this, an analyst identifies the input, follows the caller
- and reads the values at those addresses.
-
-
-
-
-
-
-
-
-
Do I need to read assembly to get started?
-
No.
-
Ask your agent about the behavior you want to understand.
-
-
-
-
- Example analysis · DX-Ball
-
-
-
Target · DXBALL.EXE
-
- ›Use REA to inspect this DX-Ball executable. How does it
- calculate left/right sound panning? Show the relevant
- code.
-
-
-
- Agent · explanation from the findings
-
-
- This function converts a brick’s horizontal position into a
- left/right sound value.
-
-
- At the initial scale of 1, the screen center produces zero.
- Positions to the left produce negative values; positions to
- the right produce positive values.
-
-
-
-
- Example prompt and explanation based on the recorded
- investigation. Supply the executable to your agent.
-
-
-
-
-
What REA found for the agent
-
-
- 01 · Inspect the function
- An integer input
- The instructions read [EBP + 0x8]. The initial
- pseudocode had missed this input.
-
-
- 02 · Follow the caller
- A brick’s screen position
- The caller passes 20 + 30 × tile_x, giving the
- input its meaning.
-
-
- 03 · Read the stored data
- The calculation’s constants
- Byte reads supply 1.5625, 500.0 and
- the initial scale 1.0.
-
-
-
- The agent uses these findings to explain the behavior and write
- readable C.
-
-
-
- The reconstruction project checked its maintained C function against
- 3,205 original-x86 input cases and all 63 compiled bytes.
- See the code and checks.
-
-
-
-
-
-
+
-
Your first investigation
-
Try REA on a small app.
-
- Find out where an app exports its notes, then check how it formats
- a title containing commas and quotes.
+
Reverse engineering, with your coding agent
+
Find out how software works.
+
+ REA gives your agent the tools to inspect a program and explain
+ what it does.
-
We provide the example files, a prompt and a result to check.
+ Inspected with REA 4.1.0: Windows Calculator 11.2508.4.0, x64. The
+ readable summary uses names from Microsoft’s public source to
+ explain the recovered branch.
+
+ Original rule: start at 6, then increase toward 13.
+
+
+ Move the slider to set your own speed. Space or Jump clears a
+ cactus.
+
+
+
+
+
+
From the running game to a new version
+
+
+ 01 · InspectREA returns the loaded scriptThe agent reads the update function and its speed
+ settings.
+
+
+ 02 · RebuildUse the recovered ruleStart at 6 and add 0.001 while speed is below 13.
+
+
+ 03 · Change and playMake speed adjustableKeep the original acceleration, or choose your own
+ pace.
+
+
+
+
+
+ See the script, checks and how to try the analysis
+
+
+ REA inspected the HTTP browser edition through a local debugging
+ connection and returned the loaded index.js,
+ including its source and digest.
+
+
+
+ Selected settings from the inspected script
+
+
ACCELERATION: 0.001,
+MAX_SPEED: 13,
+SPEED: 6
+
+
+ We called the original game’s update function in a controlled
+ browser check, with obstacles and automatic scheduling disabled.
+ After 4,000 updates, speed was 10.0; after 10,000, it was 13.0,
+ rounded to one decimal.
+
+
+ The new mini-game keeps that speed rule. Its drawing, jumping and
+ collision code are a small teaching implementation.
+ Open the lab to see the new code
+ and run the same speed check.
+
+
+ To inspect the target yourself, follow the
+ browser connection steps
+ using
+ the dinosaur page. Give your agent that page URL and your local debugging
+ endpoint, then copy the prompt above.
+
diff --git a/website/style-guide.md b/website/style-guide.md
index 28a007fb5..c322c1acd 100644
--- a/website/style-guide.md
+++ b/website/style-guide.md
@@ -64,8 +64,17 @@ code excerpt with readable logic and a figure that explains the result without
requiring the reader to understand either language. Show a simple agent prompt
and the specific facts REA supplies to answer it.
-Offer a supplied target for the next step. Keep the installation prompt and
-normal setup command visible. A first exercise should take the reader through
+Put compact setup at the beginning of the homepage: a copyable installation
+prompt and the ordinary setup command. Follow it with the beginner examples.
+Show how the reader's task changes using the same question on both sides of a
+manual/agent comparison. Let returned evidence make REA's contribution visible.
+
+When a small reconstruction makes the finding tangible, let readers change an
+input or setting and try the result. Connect inspection, recovered logic,
+reconstruction and the new experiment. Keep the recovered rule distinct from
+new teaching mechanics, and check it against the inspected program.
+
+Offer a supplied target for the next step. A first exercise should take the reader through
setup, a question, an answer with source references, one prediction they can
check, and a follow-up. Introduce specialized prerequisites when the chosen
target requires them.
@@ -114,13 +123,14 @@ purposes, and immutable commit links for checkpoint-dependent facts.
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 |
+| 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 |
+| Recovered behavior and a new experiment | Dinosaur speed reconstruction | Inspected code, playable demo and original-result check |
Use SVG or semantic HTML for diagrams with exact text, numbers and arrows.
Generated illustrations can help explore a layout, but the published labels,
From 19c52f5e3f42fb754fc154bbd16552c5111df0c5 Mon Sep 17 00:00:00 2001
From: N0zoM1z0 <1705004398@qq.com>
Date: Fri, 9 Oct 2026 11:21:18 +0800
Subject: [PATCH 3/6] feat(website): lead with the playable dinosaur example
---
website/README.md | 12 +-
website/evidence/calculator-and-dino.md | 5 +-
website/figures.md | 6 +-
website/public/index.html | 497 +++++++++++++-----------
website/style-guide.md | 2 +
5 files changed, 279 insertions(+), 243 deletions(-)
diff --git a/website/README.md b/website/README.md
index cbe151232..ae758a895 100644
--- a/website/README.md
+++ b/website/README.md
@@ -26,7 +26,7 @@ Open . Refresh the browser after editing a file.
## Pages
-- `public/index.html`: compact setup, manual/agent comparison, Calculator percentage example, playable dinosaur reconstruction and case-study overviews.
+- `public/index.html`: compact setup, playable dinosaur reconstruction, manual/agent comparison, Calculator percentage example and case-study overviews.
- `public/examples/dino-lab/index.html`: adjustable-speed mini-game, recovered rule, original-game check and browser analysis steps.
- `public/first-investigation/index.html`: a guided Notes export investigation, from setup to a checked CSV prediction.
- `public/showcase/index.html`: the case-study index.
@@ -98,10 +98,12 @@ their provenance and the scope of the validation claims. The original executable
and complete private Evidence records are not website assets.
The homepage starts with a short installation prompt and the ordinary setup
-command. It compares manual investigation with asking an agent, using the same
-Calculator percentage question. The native excerpt comes from an installed
-model DLL; Microsoft’s public implementation supplies names and a crosscheck.
-The Calculator controls illustrate that rule with generic inputs.
+command, followed immediately by the playable dinosaur example. Its game
+precedes the prompt and code on small screens. The manual/agent comparison
+then explains the investigation using the same dinosaur speed question.
+Calculator follows as a native example: its excerpt comes from an installed
+model DLL, and Microsoft’s public implementation supplies names and a
+crosscheck. Its controls illustrate the percentage rule with generic inputs.
The dinosaur example connects an inspected running script to a new playable
mini-game. `public/assets/dino-speed.js` owns the recovered speed rule and replay;
diff --git a/website/evidence/calculator-and-dino.md b/website/evidence/calculator-and-dino.md
index 67d816014..e89138d54 100644
--- a/website/evidence/calculator-and-dino.md
+++ b/website/evidence/calculator-and-dino.md
@@ -1,8 +1,9 @@
# Calculator and dinosaur beginner examples
Evidence collected on 9 October 2026 with the published REA 4.1.0 package.
-The homepage offers compact setup first, then a manual/agent comparison and
-two familiar behavior questions. Prompts and replies are examples based on the
+The homepage offers compact setup first, then a playable dinosaur reconstruction,
+a manual/agent comparison of that investigation, and the Calculator example.
+Prompts and replies are examples based on the
findings below. Selected code and generic inputs are public; raw captures stay
outside the website.
diff --git a/website/figures.md b/website/figures.md
index c94db54f9..a87cf7b19 100644
--- a/website/figures.md
+++ b/website/figures.md
@@ -44,9 +44,9 @@ rendering at desktop and mobile widths.
## Beginner homepage and dinosaur reconstruction
-The Calculator role comparison and its percentage controls are semantic HTML.
-The assembly comes from a real installed model DLL; the named calculation is
-a readable summary crosschecked against Microsoft’s public source. See
+The dinosaur role comparison and Calculator percentage controls are semantic
+HTML. Calculator’s assembly comes from a real installed model DLL; the named
+calculation is a readable summary crosschecked against Microsoft’s public source. See
[evidence/calculator-and-dino.md](evidence/calculator-and-dino.md).
The dinosaur sequence uses an HTML flow: inspect the loaded script, rebuild the
diff --git a/website/public/index.html b/website/public/index.html
index 747e1715b..636ade994 100644
--- a/website/public/index.html
+++ b/website/public/index.html
@@ -62,7 +62,7 @@
what it does.
+ 01 · InspectREA returns the loaded scriptThe agent reads the update function and its speed
+ settings.
+
+
+ 02 · RebuildUse the recovered ruleStart at 6 and add 0.001 while speed is below 13.
+
+
+ 03 · Change and playMake speed adjustableKeep the original acceleration, or choose your own
+ pace.
+
+
+
+
+
+ See the script, checks and how to try the analysis
+
+
+ REA inspected the HTTP browser edition through a local debugging
+ connection and returned the loaded index.js,
+ including its source and digest.
+
+
+
+ Selected settings from the inspected script
+
+
ACCELERATION: 0.001,
+MAX_SPEED: 13,
+SPEED: 6
+
+
+ We called the original game’s update function in a controlled
+ browser check, with obstacles and automatic scheduling disabled.
+ After 4,000 updates, speed was 10.0; after 10,000, it was 13.0,
+ rounded to one decimal.
+
+
+ The new mini-game keeps that speed rule. Its drawing, jumping and
+ collision code are a small teaching implementation.
+ Open the lab to see the new code
+ and run the same speed check.
+
+
+ To inspect the target yourself, follow the
+ browser connection steps
+ using
+ the dinosaur page. Give your agent that page URL and your local debugging
+ endpoint, then copy the prompt above.
+
@@ -175,13 +388,13 @@
Example prompt · CalculatorExample prompt · Dinosaur game
@@ -189,8 +402,8 @@
›Use REA to inspect Windows Calculator. Why does 200 + 10%
- give 220? Show the code behind the % button.Use REA to inspect this dinosaur game. Why does it get
+ faster? Show the speed rule.
@@ -198,11 +411,14 @@
Example explanation from the findings
- With addition, % calculates a percentage of the first
- number.
+ It starts at 6. Each update without a collision adds 0.001
+ while speed is below 13.
- 10% of 200 is 20. Then 200 + 20 = 220.
+ After 4,000 updates, speed is 10.
+ You can replay the rule to check it.
@@ -222,7 +438,7 @@
-
Example 01 · Windows Calculator
+
Example 02 · Windows Calculator
What does the % button actually do?
The answer depends on the operator. Compare addition and
@@ -369,6 +585,30 @@
0x64 = 100
+
+
+ Example prompt · Calculator
+
+
+
+ ›Use REA to inspect Windows Calculator. Why does 200 + 10%
+ give 220? Show the code behind the % button.
+
+
Inspected with REA 4.1.0: Windows Calculator 11.2508.4.0, x64. The
readable summary uses names from Microsoft’s public source to
@@ -390,215 +630,6 @@
-
-
-
-
Example 02 · Chrome’s dinosaur game
-
Find the speed rule. Rebuild it. Change it.
-
- Why does the dinosaur game get faster? Use REA to read the running
- page’s script, then turn the answer into a game you can adjust.
-
-
-
-
-
-
- Example prompt · Dinosaur game
-
-
-
- ›Use REA to inspect this dinosaur game. Why does it get
- faster? Show the speed rule, then build a small version with
- an adjustable speed.
-
- Original rule: start at 6, then increase toward 13.
-
-
- Move the slider to set your own speed. Space or Jump clears a
- cactus.
-
-
-
-
-
-
From the running game to a new version
-
-
- 01 · InspectREA returns the loaded scriptThe agent reads the update function and its speed
- settings.
-
-
- 02 · RebuildUse the recovered ruleStart at 6 and add 0.001 while speed is below 13.
-
-
- 03 · Change and playMake speed adjustableKeep the original acceleration, or choose your own
- pace.
-
-
-
-
-
- See the script, checks and how to try the analysis
-
-
- REA inspected the HTTP browser edition through a local debugging
- connection and returned the loaded index.js,
- including its source and digest.
-
-
-
- Selected settings from the inspected script
-
-
ACCELERATION: 0.001,
-MAX_SPEED: 13,
-SPEED: 6
-
-
- We called the original game’s update function in a controlled
- browser check, with obstacles and automatic scheduling disabled.
- After 4,000 updates, speed was 10.0; after 10,000, it was 13.0,
- rounded to one decimal.
-
-
- The new mini-game keeps that speed rule. Its drawing, jumping and
- collision code are a small teaching implementation.
- Open the lab to see the new code
- and run the same speed check.
-
-
- To inspect the target yourself, follow the
- browser connection steps
- using
- the dinosaur page. Give your agent that page URL and your local debugging
- endpoint, then copy the prompt above.
-
diff --git a/website/style-guide.md b/website/style-guide.md
index c322c1acd..d8afc1c00 100644
--- a/website/style-guide.md
+++ b/website/style-guide.md
@@ -66,6 +66,8 @@ and the specific facts REA supplies to answer it.
Put compact setup at the beginning of the homepage: a copyable installation
prompt and the ordinary setup command. Follow it with the beginner examples.
+Put the most immediate result first. An interactive example can precede the
+process explanation; on mobile, show the demo before its supporting code.
Show how the reader's task changes using the same question on both sides of a
manual/agent comparison. Let returned evidence make REA's contribution visible.
From e750c262fbf37100369ab25bf8659daa1a2c4cc7 Mon Sep 17 00:00:00 2001
From: N0zoM1z0 <1705004398@qq.com>
Date: Fri, 9 Oct 2026 11:46:06 +0800
Subject: [PATCH 4/6] feat(website): clarify reverse engineering and showcase
goals
---
website/README.md | 17 +-
website/evidence/calculator-and-dino.md | 9 +-
website/figures.md | 6 +
website/public/assets/home.js | 8 +-
website/public/assets/styles.css | 63 +++
website/public/examples/dino-lab/index.html | 8 +-
website/public/index.html | 400 +++++++++++---------
website/style-guide.md | 11 +-
8 files changed, 323 insertions(+), 199 deletions(-)
diff --git a/website/README.md b/website/README.md
index ae758a895..f0da06ca4 100644
--- a/website/README.md
+++ b/website/README.md
@@ -26,7 +26,7 @@ Open . Refresh the browser after editing a file.
## Pages
-- `public/index.html`: compact setup, playable dinosaur reconstruction, manual/agent comparison, Calculator percentage example and case-study overviews.
+- `public/index.html`: compact setup, reverse-engineering definition and purpose, manual/agent comparison, dinosaur and Calculator examples, and case-study overviews.
- `public/examples/dino-lab/index.html`: adjustable-speed mini-game, recovered rule, original-game check and browser analysis steps.
- `public/first-investigation/index.html`: a guided Notes export investigation, from setup to a checked CSV prediction.
- `public/showcase/index.html`: the case-study index.
@@ -98,12 +98,15 @@ their provenance and the scope of the validation claims. The original executable
and complete private Evidence records are not website assets.
The homepage starts with a short installation prompt and the ordinary setup
-command, followed immediately by the playable dinosaur example. Its game
-precedes the prompt and code on small screens. The manual/agent comparison
-then explains the investigation using the same dinosaur speed question.
-Calculator follows as a native example: its excerpt comes from an installed
-model DLL, and Microsoft’s public implementation supplies names and a
-crosscheck. Its controls illustrate the percentage rule with generic inputs.
+command, then explains what reverse engineering is and why someone would use
+it. The manual/agent comparison introduces REA’s role before the examples.
+Dinosaur is the first example; Calculator follows as the native example.
+Both name the goal and the reason to inspect the program before showing the
+demo. A labeled finding explains what REA returned, and the flow distinguishes
+REA’s inspection from the agent’s interpretation and implementation.
+Its game precedes the prompt and code on small screens. Calculator’s excerpt
+comes from an installed model DLL; Microsoft’s public implementation supplies
+names and a crosscheck. Its controls apply the percentage rule to generic inputs.
The dinosaur example connects an inspected running script to a new playable
mini-game. `public/assets/dino-speed.js` owns the recovered speed rule and replay;
diff --git a/website/evidence/calculator-and-dino.md b/website/evidence/calculator-and-dino.md
index e89138d54..b46d2113e 100644
--- a/website/evidence/calculator-and-dino.md
+++ b/website/evidence/calculator-and-dino.md
@@ -1,8 +1,10 @@
# Calculator and dinosaur beginner examples
Evidence collected on 9 October 2026 with the published REA 4.1.0 package.
-The homepage offers compact setup first, then a playable dinosaur reconstruction,
-a manual/agent comparison of that investigation, and the Calculator example.
+The homepage offers compact setup first, then a reverse-engineering definition,
+purpose and manual/agent comparison. Dinosaur is the first worked example;
+Calculator is the second. Each states its goal, why the program is inspected,
+what REA returned and how the agent uses it.
Prompts and replies are examples based on the
findings below. Selected code and generic inputs are public; raw captures stay
outside the website.
@@ -54,7 +56,8 @@ in the installed DLL. The public source commit is a crosscheck; it is not an
identified build commit for that installed package. No PDB symbols were loaded.
The homepage's named C-like rule is an explanatory summary. Its `200 + 10%`
-and `200 × 10%` displays are derived from that rule. Browser checks exercise
+and `200 × 10%` controls compute those cases from that rule using the fixed
+inputs 200 and 10. Browser checks exercise
both percentage illustrations, their results, operator selection and reset.
The Microsoft tests were inspected, not executed. A probe-owned Calculator
window could be inspected, but it was no longer present at the input-check
diff --git a/website/figures.md b/website/figures.md
index a87cf7b19..e02f894ef 100644
--- a/website/figures.md
+++ b/website/figures.md
@@ -49,6 +49,12 @@ HTML. Calculator’s assembly comes from a real installed model DLL; the named
calculation is a readable summary crosschecked against Microsoft’s public source. See
[evidence/calculator-and-dino.md](evidence/calculator-and-dino.md).
+The homepage explains reverse engineering before the worked examples. Each
+example opens with its goal and reason for inspecting the program. A selected
+highlight marks the intended result; the “REA returned” block identifies the
+evidence. The flows label REA’s inspection and the agent’s interpretation or
+reconstruction explicitly. Preserve this context when moving a demo.
+
The dinosaur sequence uses an HTML flow: inspect the loaded script, rebuild the
speed rule, then change and play. Its canvas mini-game and static SVG fallback
are authored code, without generated images or copied game sprites. The game
diff --git a/website/public/assets/home.js b/website/public/assets/home.js
index 61f22231b..448052cc7 100644
--- a/website/public/assets/home.js
+++ b/website/public/assets/home.js
@@ -11,13 +11,15 @@ function initializePercentDemo() {
const render = () => {
const adding = operation === "add";
- const percent = adding ? 20 : 0.1;
- const result = adding ? 220 : 20;
+ const previous = 200;
+ const current = 10;
+ const percent = adding ? (current * previous) / 100 : current / 100;
+ const result = adding ? previous + percent : previous * percent;
const operator = adding ? "+" : "×";
expression.textContent =
stage === "result" ? `200 ${operator} ${percent} =` : `200 ${operator}`;
display.textContent = String(
- stage === "input" ? 10 : stage === "percent" ? percent : result,
+ stage === "input" ? current : stage === "percent" ? percent : result,
);
equals.disabled = stage !== "percent";
status.textContent =
diff --git a/website/public/assets/styles.css b/website/public/assets/styles.css
index 54bf52f67..55b04ee22 100644
--- a/website/public/assets/styles.css
+++ b/website/public/assets/styles.css
@@ -1244,6 +1244,57 @@ pre code {
color: var(--ink);
font-weight: 500;
}
+.home-purpose {
+ max-width: 850px;
+ margin-bottom: 2rem;
+ color: var(--muted);
+}
+.prose-highlight {
+ padding: 0.04em 0.16em;
+ border-radius: 2px;
+ background: #e4ecf5;
+ color: var(--accent);
+ font-weight: 600;
+ box-decoration-break: clone;
+ -webkit-box-decoration-break: clone;
+}
+.case-brief {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) minmax(0, 1.3fr);
+ gap: 2.5rem;
+ margin: 0 0 2rem;
+ padding-block: 1.2rem;
+ border-top: 1px solid var(--line);
+ border-bottom: 1px solid var(--line);
+}
+.case-brief dt,
+.finding-label {
+ margin-bottom: 0.45rem;
+ font-size: 0.8rem;
+ font-weight: 600;
+ color: var(--accent);
+}
+.case-brief dd {
+ margin: 0;
+ color: var(--muted);
+ font-size: 0.95rem;
+}
+.case-brief dd strong {
+ color: var(--ink);
+}
+.rea-finding {
+ margin-bottom: 1.4rem;
+ padding-left: 1rem;
+ border-left: 2px solid var(--accent);
+}
+.rea-finding > :last-child {
+ margin: 0;
+ font-size: 0.95rem;
+ color: var(--muted);
+}
+.rea-finding strong {
+ color: var(--ink);
+}
.home-role-comparison {
display: grid;
grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
@@ -1416,6 +1467,14 @@ pre code {
margin: 0;
font-size: 0.9rem;
}
+.percent-rules dd strong,
+.percent-rules dd code {
+ display: block;
+}
+.percent-rules dd strong {
+ margin-bottom: 0.25rem;
+ font-weight: 500;
+}
.home-evidence-details {
margin-top: 2rem;
padding-block: 1rem;
@@ -1541,6 +1600,10 @@ pre code {
}
}
@media (max-width: 640px) {
+ .case-brief {
+ grid-template-columns: minmax(0, 1fr);
+ gap: 1.2rem;
+ }
.home-hero {
padding-block: 2.8rem;
}
diff --git a/website/public/examples/dino-lab/index.html b/website/public/examples/dino-lab/index.html
index a0578a487..38038c91d 100644
--- a/website/public/examples/dino-lab/index.html
+++ b/website/public/examples/dino-lab/index.html
@@ -57,8 +57,10 @@
Inspect → rebuild → change
Rebuild the dinosaur’s speed rule.
- REA found how the running game increases its speed. This small
- reconstruction lets you keep that rule or choose a new speed and play.
+ To recreate the game’s acceleration, first find the rule that controls
+ its speed. REA returned the running script;
+ we used its rule to build this mini-game with
+ adjustable speed.
+ Finding out how software works by
+ examining the program itself.
+
+
+
+ The goal: understand a feature well enough to
+ explain it,
+ change it or
+ rebuild it.
+
+
+
+
Before REA · You investigate
+
+
+ 01
+
+ Find the relevant code.Locate the loaded script or the binary function.
+
+
+
+ 02
+
+ Work out its rules.Follow the inputs, calls and settings.
+
+
+
+ 03
+
+ Use and check the result.Explain the behavior, rebuild it or make a change.
+
+
+
+
+
+
With REA · You ask your agent
+
+
+ Example question · Dinosaur game
+
+
+
+ ›Use REA to inspect this dinosaur game. Why does it get
+ faster? Show the speed rule.
+
+
+
+ Example explanation from the findings
+
+
+ The game adds a little speed on each update. Its script sets
+ the starting speed, the increment and the stopping
+ point.
+
+
+
+
+
+ REA supplies code and observations from the program.
+ Your agent uses that evidence to explain, rebuild or test a
+ feature.
+
+
+
+
+
Example 01 · Chrome’s dinosaur game
-
Change the dinosaur’s speed.
-
- Inspect the speed rule with REA, rebuild a small version, then
- change the speed and play.
-
+
Why does the dinosaur get faster?
+
+
+
Goal
+
+ Rebuild the game with
+ adjustable speed.
+
+
+
+
Why reverse engineer it?
+
+ To reproduce its acceleration, we need
+ the rule in the running game: how fast it
+ starts, how much it increases and when it stops.
+
+
+
Play the reconstruction
@@ -193,6 +302,14 @@
>
+
+
REA returned
+
+ The script actually running in the page. The
+ agent reads its update function and speed settings, then uses
+ that rule in a new game.
+
+
-
From the running game to a new version
+
What each part does
- 01 · InspectREA returns the loaded script01 · REARead the running game’s scriptThe agent reads the update function and its speed
- settings.Return its actual code and settings to the agent.
- 02 · RebuildUse the recovered rule02 · Your agentRebuild the rule, add a controlStart at 6 and add 0.001 while speed is below 13.Use the recovered acceleration in a small game with a speed
+ slider.
- 03 · Change and playMake speed adjustable03 · YouChange the speed and playKeep the original acceleration, or choose your own
+ >Try the original acceleration, then choose your own
pace.
@@ -322,129 +439,31 @@ SPEED: 6
-
-
-
-
What is reverse engineering?
-
- Finding out how software works by examining the program.
-
-
-
- In the dinosaur example:
- which code makes the game get faster?
-
-
-
-
Before REA · You investigate
-
-
- 01
-
- Find the script behind the game.Which loaded file controls the dinosaur?
-
-
-
- 02
-
- Find the update function.Where does the game change its speed?
-
-
-
- 03
-
- Recover the speed rule.Follow the starting speed, increment and
- threshold.
-
-
-
- 04
-
- Check the result.Replay the rule and compare it with the game.
-
- ›Use REA to inspect this dinosaur game. Why does it get
- faster? Show the speed rule.
-
-
-
- Example explanation from the findings
-
-
- It starts at 6. Each update without a collision adds 0.001
- while speed is below 13.
-
-
- After 4,000 updates, speed is 10.
- You can replay the rule to check it.
-
-
-
-
- Your agent uses REA to locate and read the code, then connects
- the findings to your question.
-
-
-
- You describe the behavior. The agent carries out the investigation
- with REA.
-
-
-
-
-
Example 02 · Windows Calculator
-
What does the % button actually do?
-
- The answer depends on the operator. Compare addition and
- multiplication.
-
+
Why does 200 + 10% give 220?
+
+
+
Goal
+
+ Explain the result and
+ recreate Calculator’s % rule.
+
+
+
+
Why reverse engineer it?
+
+ The same button uses
+ different rules after + and ×. We inspect the
+ installed app to find which number the percentage is applied to.
+
+
+
Try the calculation
@@ -507,11 +526,45 @@ SPEED: 6
-
REA finds the branch. The agent explains it.
+
+
REA returned
+
+ The % handler’s original instructions and decompiled
+ code.
+ The agent reads the two branches and explains which rule each
+ operator uses.
+
+
- The installed app’s calculation code checks for multiplication
- or division before computing the percentage.
+ For this example, previous = 200 and
+ current = 10.
+
+
+ Example prompt · Calculator
+
+
+
+ ›Use REA to inspect Windows Calculator. Why does 200 + 10%
+ give 220? Show the code behind the % button.
+
+
Readable summary of the % handler
@@ -524,44 +577,54 @@ SPEED: 6
-
Addition
-
200 + 10% → 200 + 20 → 220
+
With +
+
+ Take 10% of the first number.10% of 200 = 20 → 200 + 20 = 220
+
-
Multiplication
-
200 × 10% → 200 × 0.1 → 20
+
With ×
+
+ Turn 10% into 0.1.200 × 0.1 = 20
+
-
- See the real code and how the answer was checked
-
+
+
From the installed app to an explanation
+
- 01 · Inspect calc.exeA launcher01 · REA reads calc.exeIt launches the Calculator appREA finds ShellExecuteW opening
- ms-calculator:.The code opens ms-calculator:. The agent then
+ selects the installed app’s library.
- 02 · Inspect the appCalcViewModel.dll02 · REA reads the libraryReturn the % handler’s codeIts % handler checks two operator IDs and uses the constant
+ >The function checks the operator and uses the constant
100.
- 03 · Interpret and checkTwo percentage rules03 · Your agent interprets itExplain and reproduce the rulesMicrosoft’s public implementation and unit tests explain the
- same distinction.Crosscheck the branch with Microsoft’s source, then try + and
+ × above.
+
+
+ See the real code and how the answer was checked
+
@@ -585,30 +648,7 @@ SPEED: 6
0x64 = 100
-
-
- Example prompt · Calculator
-
-
-
- ›Use REA to inspect Windows Calculator. Why does 200 + 10%
- give 220? Show the code behind the % button.
-
-
+
Inspected with REA 4.1.0: Windows Calculator 11.2508.4.0, x64. The
readable summary uses names from Microsoft’s public source to
diff --git a/website/style-guide.md b/website/style-guide.md
index d8afc1c00..e8c5085d4 100644
--- a/website/style-guide.md
+++ b/website/style-guide.md
@@ -65,9 +65,14 @@ requiring the reader to understand either language. Show a simple agent prompt
and the specific facts REA supplies to answer it.
Put compact setup at the beginning of the homepage: a copyable installation
-prompt and the ordinary setup command. Follow it with the beginner examples.
-Put the most immediate result first. An interactive example can precede the
-process explanation; on mobile, show the demo before its supporting code.
+prompt and the ordinary setup command. Then explain what reverse engineering
+means and what it lets someone do, before the worked examples.
+Begin each example with its goal and the reason to inspect that program.
+Name the actual evidence REA returned and what the agent did with it.
+Use short labels, selective bold text and the shared blue highlight to make
+those facts visible when scanning. Keep source, interpretation and new code
+attributed to their respective roles. On mobile, the demo can precede its
+supporting code once its purpose is clear.
Show how the reader's task changes using the same question on both sides of a
manual/agent comparison. Let returned evidence make REA's contribution visible.
From 291bc6fb70f47d28d23440f03a8a7fa49eb9a391 Mon Sep 17 00:00:00 2001
From: N0zoM1z0 <1705004398@qq.com>
Date: Fri, 9 Oct 2026 12:02:58 +0800
Subject: [PATCH 5/6] feat(website): show manual analysis beside a one-prompt
workflow
---
website/README.md | 9 +
website/evidence/calculator-and-dino.md | 9 +
website/figures.md | 12 +-
.../assets/figures/analyst-thinking.svg | 15 +
website/public/assets/home.js | 8 +
website/public/assets/main.js | 35 ++-
website/public/assets/styles.css | 262 +++++++++++++++---
website/public/index.html | 228 ++++++++++++---
website/style-guide.md | 5 +
9 files changed, 493 insertions(+), 90 deletions(-)
create mode 100644 website/public/assets/figures/analyst-thinking.svg
diff --git a/website/README.md b/website/README.md
index f0da06ca4..0f29bc32b 100644
--- a/website/README.md
+++ b/website/README.md
@@ -100,6 +100,15 @@ and complete private Evidence records are not website assets.
The homepage starts with a short installation prompt and the ordinary setup
command, then explains what reverse engineering is and why someone would use
it. The manual/agent comparison introduces REA’s role before the examples.
+The comparison uses the same Calculator question on both sides: three
+selectable manual steps pair original instructions with an analyst illustration
+and thought bubbles; the agent side begins with “One prompt.” and a copyable
+question. Thoughts illustrate the reasoning behind the findings. The shared
+code-step script selects the initial note on load, so all three notes remain
+readable when JavaScript is disabled.
+The original-instruction panel starts expanded on desktop. On narrow screens,
+the homepage script collapses it; a native disclosure keeps the code available
+while the thought bubble and agent prompt remain close together.
Dinosaur is the first example; Calculator follows as the native example.
Both name the goal and the reason to inspect the program before showing the
demo. A labeled finding explains what REA returned, and the flow distinguishes
diff --git a/website/evidence/calculator-and-dino.md b/website/evidence/calculator-and-dino.md
index b46d2113e..a7e9c093e 100644
--- a/website/evidence/calculator-and-dino.md
+++ b/website/evidence/calculator-and-dino.md
@@ -36,6 +36,15 @@ the constant 100 in both paths. One path divides the current value by 100;
the other combines the current value with the previous value divided by 100.
The published assembly is selected exactly from the returned instruction list.
+The opening manual/agent comparison selects instructions at
+`0x180124945–0x180124992` and `0x180124a14–0x180124a34`, with explicit omissions.
+Its three highlights identify the operator comparisons, construction of 100
+and arithmetic helper calls, and the final multiplication path. The analyst
+thought bubbles illustrate the work of decoding those facts; they are not a
+recorded analyst transcript or a measured comparison of investigation times.
+The same percentage question appears in the agent prompt. Helper meanings and
+operator names are interpretations checked against the public source below.
+
The binary is stripped. A local instruction scan located candidates using
operator IDs and the constant 100; REA then produced the complete function
dossier. Function selection was analyst-assisted. The illustrative agent
diff --git a/website/figures.md b/website/figures.md
index e02f894ef..c0ab93d60 100644
--- a/website/figures.md
+++ b/website/figures.md
@@ -13,6 +13,7 @@ The published diagrams are SVG source assets:
- `public/assets/figures/rea-investigation-flow.svg` — 1774 × 887 viewBox.
- `public/assets/figures/dx-ball-sound-pan-investigation.svg` — 1774 × 887 viewBox.
- `public/assets/figures/th04-bullet-ring.svg` — 1000 × 520 viewBox.
+- `public/assets/figures/analyst-thinking.svg` — 160 × 120 viewBox.
Two original layout references were generated with the built-in image generation
tool and reviewed visually. Their prompts are retained below. The final SVGs
@@ -44,11 +45,20 @@ rendering at desktop and mobile widths.
## Beginner homepage and dinosaur reconstruction
-The dinosaur role comparison and Calculator percentage controls are semantic
+The manual/agent comparison and Calculator percentage controls are semantic
HTML. Calculator’s assembly comes from a real installed model DLL; the named
calculation is a readable summary crosschecked against Microsoft’s public source. See
[evidence/calculator-and-dino.md](evidence/calculator-and-dino.md).
+The introduction pairs selected Calculator instructions with three selectable
+analyst thoughts: decode operator branches, trace arithmetic calls, then name
+the percentage rule. The small analyst illustration is authored SVG; the
+thought bubbles, findings and labels are selectable HTML. The thoughts
+illustrate the analysis rather than reproduce a recorded conversation. The
+agent side asks the same question and separates REA’s evidence from the
+agent’s explanation. Keep those roles and the instruction highlights aligned
+when changing a step.
+
The homepage explains reverse engineering before the worked examples. Each
example opens with its goal and reason for inspecting the program. A selected
highlight marks the intended result; the “REA returned” block identifies the
diff --git a/website/public/assets/figures/analyst-thinking.svg b/website/public/assets/figures/analyst-thinking.svg
new file mode 100644
index 000000000..53a92d5d9
--- /dev/null
+++ b/website/public/assets/figures/analyst-thinking.svg
@@ -0,0 +1,15 @@
+
diff --git a/website/public/assets/home.js b/website/public/assets/home.js
index 448052cc7..27cd1b32f 100644
--- a/website/public/assets/home.js
+++ b/website/public/assets/home.js
@@ -55,4 +55,12 @@ function initializePercentDemo() {
render();
}
+function initializeExpertAssembly() {
+ const excerpt = document.querySelector("[data-expert-assembly]");
+ if (excerpt && window.matchMedia("(max-width: 640px)").matches) {
+ excerpt.open = false;
+ }
+}
+
+initializeExpertAssembly();
initializePercentDemo();
diff --git a/website/public/assets/main.js b/website/public/assets/main.js
index 98751f280..b927dff64 100644
--- a/website/public/assets/main.js
+++ b/website/public/assets/main.js
@@ -39,23 +39,28 @@ initializeCopyButtons();
function initializeStepComparisons() {
document.querySelectorAll("[data-step-comparison]").forEach((comparison) => {
const buttons = comparison.querySelectorAll("[data-select-step]");
- buttons.forEach((button) => {
- button.addEventListener("click", () => {
- const selected = button.getAttribute("data-select-step");
- buttons.forEach((candidate) => {
- candidate.setAttribute("aria-pressed", String(candidate === button));
- });
- comparison.querySelectorAll("[data-step]").forEach((fragment) => {
- fragment.classList.toggle(
- "is-active",
- fragment.getAttribute("data-step") === selected,
- );
- });
- comparison.querySelectorAll("[data-step-note]").forEach((note) => {
- note.hidden = note.getAttribute("data-step-note") !== selected;
- });
+ const selectStep = (button) => {
+ const selected = button.getAttribute("data-select-step");
+ buttons.forEach((candidate) => {
+ candidate.setAttribute("aria-pressed", String(candidate === button));
});
+ comparison.querySelectorAll("[data-step]").forEach((fragment) => {
+ fragment.classList.toggle(
+ "is-active",
+ fragment.getAttribute("data-step") === selected,
+ );
+ });
+ comparison.querySelectorAll("[data-step-note]").forEach((note) => {
+ note.hidden = note.getAttribute("data-step-note") !== selected;
+ });
+ };
+ buttons.forEach((button) => {
+ button.addEventListener("click", () => selectStep(button));
});
+ const initial = Array.from(buttons).find(
+ (button) => button.getAttribute("aria-pressed") === "true",
+ );
+ if (initial) selectStep(initial);
});
}
diff --git a/website/public/assets/styles.css b/website/public/assets/styles.css
index 55b04ee22..3bcc84d9e 100644
--- a/website/public/assets/styles.css
+++ b/website/public/assets/styles.css
@@ -1297,10 +1297,18 @@ pre code {
}
.home-role-comparison {
display: grid;
- grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
- gap: 0 2.5rem;
+ grid-template-columns: minmax(0, 1.65fr) minmax(0, 1fr);
+ gap: 0 2rem;
margin: 0;
}
+.comparison-question {
+ margin-block: 1.8rem 1.2rem;
+ font-size: 1.05rem;
+ color: var(--muted);
+}
+.comparison-question strong {
+ color: var(--ink);
+}
.comparison-label {
padding-bottom: 0.8rem;
border-bottom: 1px solid var(--line);
@@ -1310,47 +1318,204 @@ pre code {
.agent-investigation > .comparison-label {
color: var(--accent);
}
-.manual-steps {
- display: grid;
- gap: 1rem;
- padding: 0;
- list-style: none;
+.expert-step-selector {
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+ margin-block: 1.2rem 1rem;
}
-.manual-steps li {
- display: flex;
- gap: 1rem;
+.expert-step-selector button {
+ min-height: 44px;
+ padding: 0.6rem 0.4rem;
+ font-size: 0.75rem;
+}
+.expert-step-selector button span {
+ font-size: 0.7rem;
+}
+.expert-analysis-grid {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) minmax(0, 0.52fr);
+ align-items: start;
+ gap: 0.9rem;
+}
+.expert-assembly {
+ min-width: 0;
margin: 0;
}
-.manual-steps li > span {
- padding-top: 0.2rem;
+.expert-assembly .code-header {
+ padding: 0.7rem 0.8rem;
+ font-size: 0.7rem;
+ cursor: pointer;
+ list-style: none;
+}
+.expert-assembly summary::-webkit-details-marker {
+ display: none;
+}
+.expert-assembly summary:focus-visible {
+ outline: 2px solid var(--accent);
+ outline-offset: 3px;
+}
+.assembly-disclosure::after {
+ content: "Show +";
+ color: var(--accent);
+ white-space: nowrap;
+}
+.expert-assembly[open] .assembly-disclosure::after {
+ content: "Hide −";
+}
+.expert-assembly pre {
+ margin: 0;
+ padding: 0.8rem;
+ font-size: 0.7rem;
+ line-height: 1.6;
+}
+.assembly-omission {
color: var(--muted);
- font:
- 0.75rem "SFMono-Regular",
- Consolas,
- "Liberation Mono",
- monospace;
}
-.manual-steps strong,
-.manual-steps small {
+.expert-reasoning {
+ min-width: 0;
+ padding-top: 0.1rem;
+}
+.expert-thought {
+ position: relative;
+ padding: 1rem 0.9rem;
+ border: 1px solid var(--line);
+ border-radius: 16px;
+ background: var(--page);
+}
+.expert-thought + .expert-thought {
+ margin-top: 1rem;
+}
+.expert-thought::before,
+.expert-thought::after {
+ content: "";
+ position: absolute;
+ border: 1px solid var(--line);
+ border-radius: 50%;
+ background: var(--page);
+}
+.expert-thought::before {
+ bottom: -18px;
+ right: 38px;
+ width: 12px;
+ height: 12px;
+}
+.expert-thought::after {
+ bottom: -30px;
+ right: 47px;
+ width: 6px;
+ height: 6px;
+}
+.expert-thought > p {
+ margin: 0;
+ font-size: 0.85rem;
+ line-height: 1.65;
+}
+.expert-thought > .thought-label {
+ margin-bottom: 0.6rem;
+ color: var(--accent);
+ font-size: 0.7rem;
+ font-weight: 600;
+}
+.expert-thought > .expert-task {
+ margin-top: 0.8rem;
+ color: var(--muted);
+ font-size: 0.75rem;
+}
+.expert-facts {
+ display: grid;
+ gap: 0.45rem;
+ margin: 0.9rem 0 0;
+ padding-top: 0.8rem;
+ border-top: 1px solid var(--line);
+ font-size: 0.7rem;
+}
+.expert-facts div {
+ display: flex;
+ justify-content: space-between;
+ gap: 0.5rem;
+}
+.expert-facts dt {
+ font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace;
+}
+.expert-facts dd {
+ margin: 0;
+ color: var(--accent);
+}
+.expert-rule {
+ display: grid;
+ gap: 0.3rem;
+ margin-top: 0.9rem;
+ padding-top: 0.8rem;
+ border-top: 1px solid var(--line);
+ font-size: 0.75rem;
+}
+.expert-rule strong {
+ color: var(--accent);
+ font-size: 1.4rem;
+}
+.expert-illustration {
display: block;
+ width: 120px;
+ height: 90px;
+ margin: 2rem 0 0 auto;
}
-.manual-steps strong {
- font-size: 0.95rem;
+.expert-caption {
+ margin: 0.5rem 0 0;
+ color: var(--muted);
+ font-size: 0.65rem;
+ text-align: right;
+}
+.manual-work-summary {
+ margin: 1rem 0 0;
+ color: var(--muted);
+ font-size: 0.85rem;
+}
+.manual-work-summary strong {
font-weight: 500;
}
-.manual-steps small {
- margin-top: 0.15rem;
- color: var(--muted);
- font-size: 0.8rem;
+.agent-one-prompt {
+ margin: 1.2rem 0 0.3rem;
+ color: var(--accent);
+ font-size: clamp(1.8rem, 3vw, 2.5rem);
+ font-weight: 600;
+ letter-spacing: -0.045em;
}
-.manual-code {
- margin-top: 1.3rem;
- padding: 1rem 1.25rem;
- border-left: 2px solid var(--line);
- background: var(--soft);
+.agent-intro {
+ margin: 0 0 1.2rem;
color: var(--muted);
- font-size: 0.8rem;
- line-height: 1.65;
+ font-size: 0.9rem;
+}
+.agent-percent-rule {
+ display: grid;
+ justify-items: start;
+ gap: 0.2rem;
+ margin-top: 0.9rem;
+ color: var(--accent);
+}
+.agent-percent-rule code {
+ color: var(--ink);
+}
+.agent-percent-rule > span {
+ margin-left: 0.4rem;
+ color: var(--muted);
+}
+.agent-percent-rule strong {
+ font-size: 1.2rem;
+}
+.agent-evidence-roles {
+ display: grid;
+ gap: 1rem;
+ margin: 1.2rem 0 0;
+}
+.agent-evidence-roles dt {
+ margin-bottom: 0.25rem;
+ color: var(--accent);
+ font-size: 0.75rem;
+ font-weight: 600;
+}
+.agent-evidence-roles dd {
+ margin: 0;
+ color: var(--muted);
+ font-size: 0.85rem;
}
.agent-investigation-note {
color: var(--muted);
@@ -1600,6 +1765,39 @@ pre code {
}
}
@media (max-width: 640px) {
+ .expert-analysis-grid {
+ grid-template-columns: minmax(0, 1fr);
+ }
+ .expert-reasoning {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) 88px;
+ column-gap: 0.75rem;
+ align-items: end;
+ }
+ .expert-thought::before {
+ right: -18px;
+ bottom: 42px;
+ }
+ .expert-thought::after {
+ right: -30px;
+ bottom: 36px;
+ }
+ .expert-illustration {
+ width: 88px;
+ height: 66px;
+ margin: 0;
+ }
+ .expert-caption {
+ grid-column: 1 / -1;
+ text-align: left;
+ }
+ .expert-step-selector button {
+ font-size: 0.7rem;
+ }
+ .expert-step-selector button span {
+ display: block;
+ margin: 0 0 0.2rem;
+ }
.case-brief {
grid-template-columns: minmax(0, 1fr);
gap: 1.2rem;
diff --git a/website/public/index.html b/website/public/index.html
index 1722767dd..26f8d2b0a 100644
--- a/website/public/index.html
+++ b/website/public/index.html
@@ -128,51 +128,181 @@
change it or
rebuild it.
+
+ One question:
+ why does Calculator give 220 for 200 + 10%?
+
-
+
Before REA · You investigate
-
-
- 01
-
- Find the relevant code.Locate the loaded script or the binary function.
+
›Use REA to inspect this dinosaur game. Why does it get
- faster? Show the speed rule.Use REA to inspect Windows Calculator. Why does 200 + 10%
+ give 220?
- Example explanation from the findings
+ Example answer · based on the findings
- The game adds a little speed on each update. Its script sets
- the starting speed, the increment and the stopping
- point.
+ After +, the % button takes
+ a percentage of the first number.
+
+ 10% of 200 = 20↓200 + 20 = 220
+
+
+
+
REA supplies
+
+ The handler’s instructions, decompiled code and calls.
+
+
+
+
Your agent explains
+
+ Which branch applies, what it calculates and how to rebuild
+ it.
+
+
+
- REA supplies code and observations from the program.
- Your agent uses that evidence to explain, rebuild or test a
- feature.
+ Selected assembly from the installed Calculator DLL. The thoughts
+ and reply illustrate the findings.
+ See the calculation and sources ↓
diff --git a/website/style-guide.md b/website/style-guide.md
index e8c5085d4..e17475d57 100644
--- a/website/style-guide.md
+++ b/website/style-guide.md
@@ -75,6 +75,11 @@ attributed to their respective roles. On mobile, the demo can precede its
supporting code once its purpose is clear.
Show how the reader's task changes using the same question on both sides of a
manual/agent comparison. Let returned evidence make REA's contribution visible.
+When showing manual analysis, use authentic instructions and specific analyst
+questions: what a command ID means, which call performs arithmetic, or which
+operand enters a calculation. Numbered selections can connect the code to
+illustrative thought bubbles. Keep the agent side brief: one visible prompt,
+a concrete answer, and the evidence used to reach it.
When a small reconstruction makes the finding tangible, let readers change an
input or setting and try the result. Connect inspection, recovered logic,
From 761881cec33b18d7228bae5e2093e5d44b96ceb1 Mon Sep 17 00:00:00 2001
From: N0zoM1z0 <1705004398@qq.com>
Date: Fri, 9 Oct 2026 12:19:38 +0800
Subject: [PATCH 6/6] ci(website): publish Cloudflare and Pages from one
artifact
---
.github/workflows/website-pages.yml | 90 ++++++++++++++++++++++++++++-
.gitignore | 1 +
website/AGENTS.md | 5 +-
website/README.md | 44 +++++++++-----
website/style-guide.md | 8 ++-
5 files changed, 127 insertions(+), 21 deletions(-)
diff --git a/.github/workflows/website-pages.yml b/.github/workflows/website-pages.yml
index 52908cd8b..881a66dc8 100644
--- a/.github/workflows/website-pages.yml
+++ b/.github/workflows/website-pages.yml
@@ -19,12 +19,33 @@ jobs:
contents: read
pages: read
steps:
+ - name: Require Cloudflare publishing credentials
+ env:
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+ CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+ run: |
+ if [[ -z "$CLOUDFLARE_API_TOKEN" || -z "$CLOUDFLARE_ACCOUNT_ID" ]]; then
+ echo "::error::Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in repository Actions secrets before publishing."
+ exit 1
+ fi
- name: Check out the repository
uses: actions/checkout@v4
- name: Prepare the example download
run: python3 scripts/prepare-website.py
- name: Check website links and publishing configuration
run: python3 scripts/verify-website.py
+ - name: Record the published commit
+ run: |
+ python3 - <<'PY'
+ import json
+ import os
+ from pathlib import Path
+
+ Path("website/public/deployment.json").write_text(
+ json.dumps({"commit": os.environ["GITHUB_SHA"]}) + "\n",
+ encoding="utf-8",
+ )
+ PY
- name: Configure Pages
uses: actions/configure-pages@v5
- name: Upload the website
@@ -35,14 +56,81 @@ jobs:
deploy:
needs: prepare
runs-on: ubuntu-latest
- timeout-minutes: 5
+ timeout-minutes: 15
permissions:
+ contents: read
+ actions: read
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
+ - name: Check out publishing configuration
+ uses: actions/checkout@v4
+ - name: Set up Node.js for Wrangler
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: .nvmrc
+ - name: Download the verified website
+ uses: actions/download-artifact@v4
+ with:
+ name: github-pages
+ path: ${{ runner.temp }}/website-archive
+ - name: Extract the shared publishing artifact
+ run: |
+ mkdir -p "$RUNNER_TEMP/rea-website-public"
+ tar -xf "$RUNNER_TEMP/website-archive/artifact.tar" -C "$RUNNER_TEMP/rea-website-public"
+ - name: Publish the website to Cloudflare
+ uses: cloudflare/wrangler-action@v4
+ with:
+ apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+ accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+ wranglerVersion: "4.149.0"
+ packageManager: npm
+ command: deploy --cwd website --env production --assets "${{ runner.temp }}/rea-website-public"
- name: Publish to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
+ - name: Verify both published revisions
+ env:
+ PAGES_URL: ${{ steps.deployment.outputs.page_url }}
+ run: |
+ python3 - <<'PY'
+ import json
+ import os
+ import sys
+ import time
+ from urllib.error import URLError
+ from urllib.parse import urljoin
+ from urllib.request import Request, urlopen
+
+ expected = os.environ["GITHUB_SHA"]
+ pages_url = os.environ["PAGES_URL"]
+ if not pages_url:
+ sys.exit("GitHub Pages returned no published URL.")
+ pending = {"Cloudflare": "https://rea.tools/", "GitHub Pages": pages_url}
+ for attempt in range(24):
+ for name, base in list(pending.items()):
+ url = urljoin(base, "deployment.json") + "?commit=" + expected
+ try:
+ request = Request(url, headers={"Cache-Control": "no-cache"})
+ with urlopen(request, timeout=10) as response:
+ actual = json.load(response).get("commit")
+ if actual == expected:
+ print(f"{name} serves {expected}: {base}")
+ del pending[name]
+ else:
+ print(f"Waiting for {name}: observed revision {actual}")
+ except (URLError, TimeoutError, ValueError) as error:
+ print(f"Waiting for {name}: {error}")
+ if not pending:
+ break
+ if attempt < 23:
+ time.sleep(5)
+ if pending:
+ sys.exit("Published revision did not match on: " + ", ".join(pending))
+ with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as summary:
+ summary.write(f"Published commit `{expected}` to [rea.tools](https://rea.tools/) "
+ f"and [GitHub Pages]({pages_url}).\n")
+ PY
diff --git a/.gitignore b/.gitignore
index f8266c11d..daca8832e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,6 +49,7 @@ Thumbs.db
# Generated website download
/website/public/examples/notes-example.zip
+/website/public/deployment.json
# Local Cloudflare development state
/website/.wrangler/
diff --git a/website/AGENTS.md b/website/AGENTS.md
index a4bf9b8dc..47bee247a 100644
--- a/website/AGENTS.md
+++ b/website/AGENTS.md
@@ -19,5 +19,6 @@ for asset notes and the source of case-study claims.
- 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.
+- Keep `website-pages.yml` as the sole, manual production publisher for
+ Cloudflare and Pages. Both hosts must receive the same verified artifact and
+ pass the published-commit check. Follow the website README.
diff --git a/website/README.md b/website/README.md
index 0f29bc32b..92b0be51d 100644
--- a/website/README.md
+++ b/website/README.md
@@ -185,7 +185,7 @@ Wrangler version without adding it to REA's package dependencies.
Cloudflare documents static-asset requests as free and unlimited, with no
additional storage cost. See [billing and limitations](https://developers.cloudflare.com/workers/static-assets/billing-and-limitations/).
-### Preview and deploy
+### Local and hosted previews
Run these commands from the repository root. `--cwd website` makes the build
paths consistent with the website configuration. Preview locally first:
@@ -230,13 +230,7 @@ See Cloudflare's [nameserver setup procedure](https://developers.cloudflare.com/
for the complete migration steps. A CNAME to the preview's `workers.dev` hostname
at the current DNS provider does not configure a Workers Custom Domain.
-Publish to the production Worker:
-
-```sh
-npx wrangler@4.149.0 deploy --cwd website --env production
-```
-
-This creates or updates `rea-website`, attaches `rea.tools`, and lets Cloudflare
+The production environment creates or updates `rea-website`, attaches `rea.tools`, and lets Cloudflare
manage its DNS record and HTTPS certificate. Deployment can succeed while the
zone is pending; verify public HTTPS after activation and certificate issuance.
An existing CNAME at `rea.tools`
@@ -250,15 +244,34 @@ Verify , ,
resolve correctly. The root README and browser guide use `https://rea.tools/`
as the public website URL.
-Deployments are manual. The existing GitHub Pages publisher remains available
-as a separate host; it does not publish to Cloudflare.
+Production publication uses the synchronized GitHub Actions workflow below.
+Local Wrangler commands above publish only the separate preview Worker.
-## GitHub Pages
+## Synchronized production publishing
-`.github/workflows/website-pages.yml` prepares and deploys only `website/public`.
-It is the sole Pages publisher, manually triggered and restricted to `main`;
+`.github/workflows/website-pages.yml` prepares `website/public` once and deploys
+the same artifact to Cloudflare (`rea.tools`) and GitHub Pages. It is the sole
+production publisher, manually triggered and restricted to `main`;
ordinary pushes and pull requests do not publish the site.
+Configure these repository **Actions secrets** before publishing:
+
+- `CLOUDFLARE_API_TOKEN`: a Cloudflare token using the **Edit Cloudflare Workers**
+ template, scoped to the website's account and zone.
+- `CLOUDFLARE_ACCOUNT_ID`: that Cloudflare account's ID.
+
+See Cloudflare's [GitHub Actions authentication instructions](https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/).
+The workflow checks that both secrets are present before preparing a release.
+Cloudflare deploys first; GitHub Pages deploys after that step succeeds.
+
+Preparation adds `deployment.json` with the workflow's commit SHA. Cloudflare
+receives the extracted Pages artifact through Wrangler's explicit assets path;
+the local custom-build output is not the uploaded directory. The workflow then
+checks both public version markers and reports success only when they match
+that commit. A failed publication remains failed; fix its cause and rerun the
+workflow to complete both deployments. The two hosts can update at different
+times while a run is in progress.
+
Website checks run only for pull requests that change `website/`, the verification
script or workflow definitions. They check local links, HTML fragments, SVG XML
and the single Pages publisher without installing npm dependencies. The same
@@ -277,8 +290,9 @@ the old site.
After the site is approved and merged, select **GitHub Actions** under the
repository's **Settings → Pages → Build and deployment**. Then run **Publish REA
-website** from the Actions tab on `main`. The workflow uses the `github-pages`
-environment and the official Pages actions.
+website** from the Actions tab on `main`. This publishes both production hosts.
+The workflow uses the `github-pages` environment, the official Pages actions and
+Cloudflare's Wrangler action.
The equivalent CLI command is:
diff --git a/website/style-guide.md b/website/style-guide.md
index e17475d57..5a05299c6 100644
--- a/website/style-guide.md
+++ b/website/style-guide.md
@@ -233,6 +233,8 @@ New analysis or behavior claims need the real evidence that supports them; a moc
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.
+`website-pages.yml` workflow on `main`. It publishes the same verified artifact
+to Cloudflare and GitHub Pages and checks both published commit markers.
+Ordinary commits should not publish the site. After deployment, check both live
+pages and confirm they match the reviewed version. The legacy VitePress build
+remains separate from the Pages publisher.