[PR #1674] [CLOSED] docs(website): add a step-by-step setup guide for first-time users #4744

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

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

Base: main ← Head: docs/beginner-setup-guide

📝 Commits (1)

0ac6832 docs(website): add a step-by-step setup guide for first-time users

📊 Changes

5 files changed (+930 additions, -10 deletions)

View changed files

📝 website/README.md (+1 -1)
📝 website/public/assets/styles.css (+125 -0)
📝 website/public/get-started/index.html (+3 -1)
📝 website/public/guides/index.html (+22 -8)
➕ website/public/guides/setup/index.html (+779 -0)

📄 Description

Why

Feedback from new users: the current setup "looks like dark magic to people who have never used any AI model other than web-browser chat." Most people arrive from YouTube or social media and have never opened a terminal. This PR adds a beginner path that explains each step in plain words, with pictures.

What changes

New page guides/setup/ ("Set up REA, one step at a time"):
- How the pieces fit: you → AI app → REA, plus a collapsed glossary (terminal, command, path, MCP).
- 1. Get an AI app: Claude Desktop for Claude users, Codex for ChatGPT users, or keep an existing agent.
- 1. Install Node.js (LTS installer); 3. open the terminal on Mac, Windows (Command Prompt) and Linux, then check node -v.
- 4–7. Run npx rea-agents@latest setup, answer npm's download question, tick an app with ↓/Space/Enter, review the plan, then quit and reopen the app.
- 1. Ask a first question about the supplied Notes example ZIP, including how to copy a folder path on Mac and Windows.
- If something goes wrong: npx not found, PowerShell's "running scripts is disabled", an unsupported Node.js version, an app that doesn't see REA (doctor --client …, look for healthy: true), and adding another app.
Pictures: terminal and chat screens are selectable HTML (no screenshots to go stale). Highlighted parts show what to press or look for. Captions mark what is recorded, shortened or illustrative.
Guide hub: starts with a "Start here" entry for this page. The old "Set up REA" entry at the bottom is replaced; experienced users get a link to the short setup.
Get started: the requirements line links beginners to the new page.
Shared CSS: kbd keys, step labels, a glossary list and the screen/chat components, with mobile rules.

Evidence for the setup screens

All terminal screens were recorded by driving the released rea-agents 6.3.0 setup in a pseudo-terminal with a throwaway HOME and npm cache, so no real configuration was touched:

npm's Need to install the following packages … Ok to proceed? (y) prompt
the agent list (◻/◼, "Not detected · configuration is still available")
the Hopper question, the "Ready to review" plan for Claude Desktop and the skill, and the final "Restart Claude Desktop to load REA."
a rerun showing already-connected apps stay ticked

doctor --client claude_desktop prints healthy: true first for that registration. analyze-javascript-application (6.3.0) finds notes:export in both the Mac unzip layout (notes-example/) and the Windows "Extract All" nested layout.

Verification

python3 scripts/website.py sync --check and scripts/verify-website.py: pass (20 HTML pages, 457 local references, metadata and sitemap).
scripts/test-website.py fails 4 maintenance regressions locally in a git worktree on clean main too (environmental); CI's Website checks job runs the full command.
oxfmt --check website: pass.
Visual check with headless Firefox at 1280, 390 and 320 px: no page-level horizontal scroll; terminal screens scroll inside their own frame.
Not verified: the Claude Desktop and Codex app UIs themselves (sign-in, tool-approval dialogs), Windows Command Prompt screens, and the Linux Hopper prompt. The page describes these in general terms only.

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/1674 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/11/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `docs/beginner-setup-guide` --- ### 📝 Commits (1) - [`0ac6832`](https://github.com/morluto/rea/commit/0ac6832aa6d2a345932c4385379f28e341d20450) docs(website): add a step-by-step setup guide for first-time users ### 📊 Changes **5 files changed** (+930 additions, -10 deletions) <details> <summary>View changed files</summary> 📝 `website/README.md` (+1 -1) 📝 `website/public/assets/styles.css` (+125 -0) 📝 `website/public/get-started/index.html` (+3 -1) 📝 `website/public/guides/index.html` (+22 -8) ➕ `website/public/guides/setup/index.html` (+779 -0) </details> ### 📄 Description ## Why Feedback from new users: the current setup "looks like dark magic to people who have never used any AI model other than web-browser chat." Most people arrive from YouTube or social media and have never opened a terminal. This PR adds a beginner path that explains each step in plain words, with pictures. ## What changes - **New page `guides/setup/`** ("Set up REA, one step at a time"): - *How the pieces fit*: you → AI app → REA, plus a collapsed glossary (terminal, command, path, MCP). - 1. Get an AI app: Claude Desktop for Claude users, Codex for ChatGPT users, or keep an existing agent. - 2. Install Node.js (LTS installer); 3. open the terminal on Mac, Windows (Command Prompt) and Linux, then check `node -v`. - 4–7. Run `npx rea-agents@latest setup`, answer npm's download question, tick an app with ↓/Space/Enter, review the plan, then quit and reopen the app. - 8. Ask a first question about the supplied Notes example ZIP, including how to copy a folder path on Mac and Windows. - *If something goes wrong*: `npx` not found, PowerShell's "running scripts is disabled", an unsupported Node.js version, an app that doesn't see REA (`doctor --client …`, look for `healthy: true`), and adding another app. - **Pictures**: terminal and chat screens are selectable HTML (no screenshots to go stale). Highlighted parts show what to press or look for. Captions mark what is recorded, shortened or illustrative. - **Guide hub**: starts with a "Start here" entry for this page. The old "Set up REA" entry at the bottom is replaced; experienced users get a link to the short setup. - **Get started**: the requirements line links beginners to the new page. - Shared CSS: `kbd` keys, step labels, a glossary list and the screen/chat components, with mobile rules. ## Evidence for the setup screens All terminal screens were recorded by driving the released **rea-agents 6.3.0** setup in a pseudo-terminal with a throwaway `HOME` and npm cache, so no real configuration was touched: - npm's `Need to install the following packages … Ok to proceed? (y)` prompt - the agent list (`◻`/`◼`, "Not detected · configuration is still available") - the Hopper question, the "Ready to review" plan for Claude Desktop and the skill, and the final "Restart Claude Desktop to load REA." - a rerun showing already-connected apps stay ticked `doctor --client claude_desktop` prints `healthy: true` first for that registration. `analyze-javascript-application` (6.3.0) finds `notes:export` in both the Mac unzip layout (`notes-example/`) and the Windows "Extract All" nested layout. ## Verification - `python3 scripts/website.py sync --check` and `scripts/verify-website.py`: pass (20 HTML pages, 457 local references, metadata and sitemap). - `scripts/test-website.py` fails 4 maintenance regressions locally in a git worktree on clean `main` too (environmental); CI's Website checks job runs the full command. - `oxfmt --check website`: pass. - Visual check with headless Firefox at 1280, 390 and 320 px: no page-level horizontal scroll; terminal screens scroll inside their own frame. - Not verified: the Claude Desktop and Codex app UIs themselves (sign-in, tool-approval dialogs), Windows Command Prompt screens, and the Linux Hopper prompt. The page describes these in general terms only. 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:35 +00:00