[PR #1676] [CLOSED] docs(website): make the analysis guides easier to start #4748

New issue

Closed

opened 2026-10-31 00:54:39 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:54:39 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1676
Author: @kaoru0822-kitauji
Created: 10/11/2026
Status: ❌ Closed

Base: main ← Head: docs/beginner-friendly-guides

📝 Commits (2)

0ac6832 docs(website): add a step-by-step setup guide for first-time users
c048b85 docs(website): make the analysis guides easier to start

📊 Changes

8 files changed (+1104 additions, -32 deletions)

View changed files

📝 website/README.md (+1 -1)
📝 website/public/assets/styles.css (+151 -0)
📝 website/public/get-started/index.html (+3 -1)
📝 website/public/guides/browser/index.html (+67 -10)
📝 website/public/guides/index.html (+40 -18)
📝 website/public/guides/javascript/index.html (+30 -2)
📝 website/public/guides/native/index.html (+33 -0)
➕ website/public/guides/setup/index.html (+779 -0)

📄 Description

Builds on #1674 (it links to the new guides/setup/ page). Until #1674 merges, this diff also shows that commit. Review only the second commit, docs(website): make the analysis guides easier to start.

Why

Same feedback as #1674: most new visitors have never used an AI tool outside a web browser. The analysis guides assumed a connected coding agent and a Linux terminal, so people hit dead ends early.

What changes

"Before you start" box at the top of the JavaScript, browser and native guides: difficulty, what you need (with a link to the step-by-step setup), what you don't need, and a one-line explanation of an Electron app or a native program.
Browser guide: the Chrome launch step had a Linux command and "use your installed browser's executable path on macOS or Windows." It now has three copyable commands:
- Mac: open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/rea-notes-browser …
- Windows Command Prompt: start chrome --remote-debugging-port=9222 --user-data-dir="%TEMP%\rea-notes-browser" …
- Linux: unchanged, and it keeps its browser-start copy id.
The example prompt now includes the http://127.0.0.1:9222 debugging address, so readers don't have to add it.
Windows note: multi-line commands that use \ don't work in Command Prompt. One caption per guide says to put the command on one line without the backslashes.
Guide hub: guides are ordered from easiest to hardest (JavaScript → browser → native), each with a "Needs …" line. The lede and meta description follow the new order; sharing tags were regenerated with website.py sync.
The JavaScript prompt caption links to the setup page's "copy a path" instructions instead of saying "absolute path".

Verification

python3 scripts/website.py sync --check and scripts/verify-website.py: pass (20 pages, 465 local references).
oxfmt --check website: pass.
Headless Firefox screenshots at 1280 and 320 px for the hub, browser and native guides: no page-level horizontal scroll; the long Windows command scrolls inside its code block.
Not verified locally: the Mac and Windows Chrome launch commands. This Mac has no Chrome or Chromium, and I have no Windows machine. Both use the standard launch forms (open -na … --args, and start chrome through Chrome's App Paths registration) with a separate --user-data-dir, which Chrome requires for remote debugging. A maintainer check on either OS would be welcome. The recorded REA results in the guides are unchanged.

No real Hopper/Ghidra verification was needed (website-only change).

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1676 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/11/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `docs/beginner-friendly-guides` --- ### 📝 Commits (2) - [`0ac6832`](https://github.com/morluto/rea/commit/0ac6832aa6d2a345932c4385379f28e341d20450) docs(website): add a step-by-step setup guide for first-time users - [`c048b85`](https://github.com/morluto/rea/commit/c048b853f8cc5a942c449923c962db7be1c4dc2d) docs(website): make the analysis guides easier to start ### 📊 Changes **8 files changed** (+1104 additions, -32 deletions) <details> <summary>View changed files</summary> 📝 `website/README.md` (+1 -1) 📝 `website/public/assets/styles.css` (+151 -0) 📝 `website/public/get-started/index.html` (+3 -1) 📝 `website/public/guides/browser/index.html` (+67 -10) 📝 `website/public/guides/index.html` (+40 -18) 📝 `website/public/guides/javascript/index.html` (+30 -2) 📝 `website/public/guides/native/index.html` (+33 -0) ➕ `website/public/guides/setup/index.html` (+779 -0) </details> ### 📄 Description Builds on #1674 (it links to the new `guides/setup/` page). Until #1674 merges, this diff also shows that commit. Review only the second commit, `docs(website): make the analysis guides easier to start`. ## Why Same feedback as #1674: most new visitors have never used an AI tool outside a web browser. The analysis guides assumed a connected coding agent and a Linux terminal, so people hit dead ends early. ## What changes - **"Before you start" box** at the top of the JavaScript, browser and native guides: difficulty, what you need (with a link to the step-by-step setup), what you *don't* need, and a one-line explanation of an Electron app or a native program. - **Browser guide**: the Chrome launch step had a Linux command and "use your installed browser's executable path on macOS or Windows." It now has three copyable commands: - Mac: `open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/rea-notes-browser …` - Windows Command Prompt: `start chrome --remote-debugging-port=9222 --user-data-dir="%TEMP%\rea-notes-browser" …` - Linux: unchanged, and it keeps its `browser-start` copy id. The example prompt now includes the `http://127.0.0.1:9222` debugging address, so readers don't have to add it. - **Windows note**: multi-line commands that use `\` don't work in Command Prompt. One caption per guide says to put the command on one line without the backslashes. - **Guide hub**: guides are ordered from easiest to hardest (JavaScript → browser → native), each with a "Needs …" line. The lede and meta description follow the new order; sharing tags were regenerated with `website.py sync`. - The JavaScript prompt caption links to the setup page's "copy a path" instructions instead of saying "absolute path". ## Verification - `python3 scripts/website.py sync --check` and `scripts/verify-website.py`: pass (20 pages, 465 local references). - `oxfmt --check website`: pass. - Headless Firefox screenshots at 1280 and 320 px for the hub, browser and native guides: no page-level horizontal scroll; the long Windows command scrolls inside its code block. - **Not verified locally:** the Mac and Windows Chrome launch commands. This Mac has no Chrome or Chromium, and I have no Windows machine. Both use the standard launch forms (`open -na … --args`, and `start chrome` through Chrome's App Paths registration) with a separate `--user-data-dir`, which Chrome requires for remote debugging. A maintainer check on either OS would be welcome. The recorded REA results in the guides are unchanged. No real Hopper/Ghidra verification was needed (website-only change). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 00:54:39 +00:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#4748

No description provided.

Rows
Columns