[PR #7258] [CLOSED] docs: pin install commands and clarify @latest as opt-in #7756

Closed
opened 2026-11-03 13:40:10 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7258
Author: @BeqaKs
Created: 10/26/2026
Status: ❌ Closed

Base: main ← Head: docs/pin-install-and-observation-timeouts


📝 Commits (5)

  • 790d293 docs: pin install commands and clarify @latest as opt-in
  • ed334ca docs(i18n): translate pinned-install onboarding strings
  • d881a04 style: format website index after install pin edits
  • fe9a19f docs(i18n): resync catalogs after pin-install rebase onto main
  • 0cf5fed docs(i18n): keep pinned setup example in locales README

📊 Changes

56 files changed (+13272 additions, -11362 deletions)

View changed files

📝 README.md (+16 -12)
📝 docs/installation.md (+49 -41)
📝 docs/readme/README_ar.md (+12 -5)
📝 docs/readme/README_de.md (+12 -5)
📝 docs/readme/README_el.md (+12 -5)
📝 docs/readme/README_es.md (+12 -5)
📝 docs/readme/README_fa.md (+12 -5)
📝 docs/readme/README_fr.md (+12 -5)
📝 docs/readme/README_id.md (+12 -5)
📝 docs/readme/README_it.md (+12 -5)
📝 docs/readme/README_ja.md (+12 -5)
📝 docs/readme/README_ko.md (+12 -5)
📝 docs/readme/README_ml.md (+12 -5)
📝 docs/readme/README_pl.md (+12 -5)
📝 docs/readme/README_pt-BR.md (+12 -5)
📝 docs/readme/README_ro.md (+12 -5)
📝 docs/readme/README_ru.md (+12 -5)
📝 docs/readme/README_th.md (+12 -5)
📝 docs/readme/README_tr.md (+12 -5)
📝 docs/readme/README_uk.md (+12 -5)

...and 36 more files

📄 Description

Summary

Fixes #3423 by preferring version-pinned install/setup commands and a reviewable tagged install.sh path in onboarding docs, with @latest documented as an opt-in for following every publish.

Items 2–5 from the issue are already aligned on current main (passive Debugger pause wording, scenario timeout/event-cap docs, and cache fingerprint completeness); this PR does not change those files.

#7257 was closed as overlap; this PR remains the install-pinning vehicle.

Problem and expected behavior

Onboarding copy still recommended unpinned curl …/main/install.sh | bash and npx …@latest as the default first-run path. Callers who copied those commands, including agents following the install prompt, ran unpinned code before setup later pinned a registration.

Expected: default install examples pin an exact package version (and a tagged installer script for curl), and @latest is described as opt-in.

Change and scope

  • Pin first-run setup/doctor/analysis examples to rea-agents@6.8.0 on the website, README (plus matching translated README shell examples), and docs/installation.md.
  • Pin remaining default entry points Greptile flagged: README header/quick start, global npm install --global rea-agents@6.8.0, and Bun bunx rea-agents@6.8.0 setup.
  • Lead curl install docs with download → review → bash … --version from rea-agents-<version>; demote the main pipe to an opt-in.
  • Keep dry-run preview on the same pin: bash rea-install.sh --version "$rea_version" --dry-run (flags after the filename; the installer rejects a literal -- separator).
  • Keep @latest for intentional update/refresh flows; state that it follows every publish.
  • Fill the six new website catalog strings across locales so previously complete home/setup/FAQ pages stay translated.
  • Out of scope: SECURITY private findings; no code changes; no rewrite of already-correct observation/scenario docs.

Follow the contribution scope.
Unresolved scope, authority, side effects, or required verification block
integration. Link the required maintainer scope decision for new providers or
capabilities involving target execution, injection, mutation, or protection
recovery; ordinary fixes within existing boundaries may state "not applicable".

Contract and boundary impact

  • Semantic owner and earliest changed stage: authored install/onboarding docs and website copy; consumers are human/agent install paths.
  • Contribution scope fit and linked maintainer decision: not applicable (documentation-only).
  • CLI and MCP/tool-catalog contract: none.
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: none.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): none.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: website locale catalogs updated; no package/runtime change.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: none (docs-only).
  • Base reproduction or other evidence: source review of current main against #3423; items 2–5 already fixed in earlier commits; Greptile findings on floating installs, empty/English-identical msgstr, and dry-run version pin addressed in follow-up.
  • User-visible CLI/MCP output (if applicable): none.
  • Remaining proof gaps: did not re-run real package install; version pin 6.8.0 matches package.json at authorship time.

For boundary fixes, identify the applicable boundary regressions
and lifecycle regressions
covered by the evidence above, and explain relevant gaps.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm run docs:check — passed (docs:check:built; tests/conformance/readmeConsistency.test.ts 9/9).
  • npm run check:fast — passed.
  • Confirmed zh-CN/de/el msgstr for the six new install-pinning strings are non-empty and not English-identical.
  • Spot-checked dry-run example keeps --version "$rea_version".

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable.
  • Package or release metadata impact: none (docs/website only; example pin tracks current release string).
  • Security, privacy, process, or containment review: documents unsigned installer scripts and prefers reviewable pins; does not claim signature verification. Does not touch SECURITY private findings from the issue.

Author readiness

Human owner: @BeqaKs

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 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/7258 **Author:** [@BeqaKs](https://github.com/BeqaKs) **Created:** 10/26/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `docs/pin-install-and-observation-timeouts` --- ### 📝 Commits (5) - [`790d293`](https://github.com/morluto/rea/commit/790d2931d59182377ed77fab16f45d3983b0a729) docs: pin install commands and clarify @latest as opt-in - [`ed334ca`](https://github.com/morluto/rea/commit/ed334ca78ba0c028b192e581e0ffbdec4113a9e0) docs(i18n): translate pinned-install onboarding strings - [`d881a04`](https://github.com/morluto/rea/commit/d881a048596c58661116dc6a33b1219a0fe343ce) style: format website index after install pin edits - [`fe9a19f`](https://github.com/morluto/rea/commit/fe9a19fcdff86a6073b0e39f37d14e3f391b03c6) docs(i18n): resync catalogs after pin-install rebase onto main - [`0cf5fed`](https://github.com/morluto/rea/commit/0cf5fedc5a98d18c030e86e3670112779ef07135) docs(i18n): keep pinned setup example in locales README ### 📊 Changes **56 files changed** (+13272 additions, -11362 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+16 -12) 📝 `docs/installation.md` (+49 -41) 📝 `docs/readme/README_ar.md` (+12 -5) 📝 `docs/readme/README_de.md` (+12 -5) 📝 `docs/readme/README_el.md` (+12 -5) 📝 `docs/readme/README_es.md` (+12 -5) 📝 `docs/readme/README_fa.md` (+12 -5) 📝 `docs/readme/README_fr.md` (+12 -5) 📝 `docs/readme/README_id.md` (+12 -5) 📝 `docs/readme/README_it.md` (+12 -5) 📝 `docs/readme/README_ja.md` (+12 -5) 📝 `docs/readme/README_ko.md` (+12 -5) 📝 `docs/readme/README_ml.md` (+12 -5) 📝 `docs/readme/README_pl.md` (+12 -5) 📝 `docs/readme/README_pt-BR.md` (+12 -5) 📝 `docs/readme/README_ro.md` (+12 -5) 📝 `docs/readme/README_ru.md` (+12 -5) 📝 `docs/readme/README_th.md` (+12 -5) 📝 `docs/readme/README_tr.md` (+12 -5) 📝 `docs/readme/README_uk.md` (+12 -5) _...and 36 more files_ </details> ### 📄 Description ## Summary Fixes #3423 by preferring version-pinned install/setup commands and a reviewable tagged `install.sh` path in onboarding docs, with `@latest` documented as an opt-in for following every publish. Items 2–5 from the issue are already aligned on current `main` (passive Debugger pause wording, scenario timeout/event-cap docs, and cache fingerprint completeness); this PR does not change those files. #7257 was closed as overlap; this PR remains the install-pinning vehicle. ## Problem and expected behavior Onboarding copy still recommended unpinned `curl …/main/install.sh | bash` and `npx …@latest` as the default first-run path. Callers who copied those commands, including agents following the install prompt, ran unpinned code before setup later pinned a registration. Expected: default install examples pin an exact package version (and a tagged installer script for curl), and `@latest` is described as opt-in. ## Change and scope - Pin first-run setup/doctor/analysis examples to `rea-agents@6.8.0` on the website, README (plus matching translated README shell examples), and `docs/installation.md`. - Pin remaining default entry points Greptile flagged: README header/quick start, global `npm install --global rea-agents@6.8.0`, and Bun `bunx rea-agents@6.8.0 setup`. - Lead curl install docs with download → review → `bash … --version` from `rea-agents-<version>`; demote the `main` pipe to an opt-in. - Keep dry-run preview on the same pin: `bash rea-install.sh --version "$rea_version" --dry-run` (flags after the filename; the installer rejects a literal `--` separator). - Keep `@latest` for intentional update/refresh flows; state that it follows every publish. - Fill the six new website catalog strings across locales so previously complete home/setup/FAQ pages stay translated. - Out of scope: SECURITY private findings; no code changes; no rewrite of already-correct observation/scenario docs. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries may state "not applicable". ## Contract and boundary impact - Semantic owner and earliest changed stage: authored install/onboarding docs and website copy; consumers are human/agent install paths. - Contribution scope fit and linked maintainer decision: not applicable (documentation-only). - CLI and MCP/tool-catalog contract: none. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details (if applicable): none. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: website locale catalogs updated; no package/runtime change. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: none (docs-only). - Base reproduction or other evidence: source review of current `main` against #3423; items 2–5 already fixed in earlier commits; Greptile findings on floating installs, empty/English-identical msgstr, and dry-run version pin addressed in follow-up. - User-visible CLI/MCP output (if applicable): none. - Remaining proof gaps: did not re-run real package install; version pin `6.8.0` matches `package.json` at authorship time. For boundary fixes, identify the applicable [boundary regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#boundary-regressions) and [lifecycle regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#lifecycle-regressions) covered by the evidence above, and explain relevant gaps. For evidence-bearing changes: - [ ] Observed, derived, and inferred claims remain distinguishable. - [ ] Artifact identity, source provenance, and failed attempts remain preserved. - [ ] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run docs:check` — passed (`docs:check:built`; `tests/conformance/readmeConsistency.test.ts` 9/9). - `npm run check:fast` — passed. - Confirmed zh-CN/de/el msgstr for the six new install-pinning strings are non-empty and not English-identical. - Spot-checked dry-run example keeps `--version "$rea_version"`. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. - Package or release metadata impact: none (docs/website only; example pin tracks current release string). - Security, privacy, process, or containment review: documents unsigned installer scripts and prefers reviewable pins; does not claim signature verification. Does not touch SECURITY private findings from the issue. ## Author readiness Human owner: @BeqaKs - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-11-03 13:40:10 +00:00
Sign in to join this conversation.
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#7756
No description provided.