[codex] Clarify Bun install still requires Node

[TabishB]

Summary

• Clarify in the installation guide that Bun can install OpenSpec globally, but OpenSpec still runs on Node.js.
• Add an empty changeset so CI records this as a docs-only change with no package release.

Root Cause

Issue #1019 reports that bun add -g @fission-ai/openspec installs an executable whose shebang invokes node. That is expected for the current package because OpenSpec is a Node CLI and declares node >=20.19.0 in engines. The docs listed Bun as an install option without making the runtime requirement explicit, which could imply Bun alone was sufficient.

Closes #1019

Validation

• pnpm exec changeset status --since=origin/main

No runtime tests were run because this is a docs-only clarification.

Summary by CodeRabbit

• Documentation
  • Updated installation instructions with clarification that Node.js 20.19.0+ is required at runtime when installing via Bun, despite global installation capability.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR creates a Changesets entry file and adds a platform/runtime compatibility clarification to the installation documentation, stating that Node.js 20.19.0+ is required at runtime even when installing via Bun.

Changes

Cohort / File(s)	Summary
Documentation & Metadata .changeset/clarify-bun-node-runtime.md, docs/installation.md	Adds a new changeset entry and updates installation guide with a warning that while Bun can install the package globally, Node.js 20.19.0+ runtime is still required via PATH.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A clarifying note hops into place,
Bun installs it, but Node must race,
Documentation now shows the way,
Runtime requirements, clear as day! 📝✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR documents the issue but does not implement the actual fix—it only adds documentation and a changeset, leaving the shebang problem unresolved.	Either update the shebang to use bun instead of node, or implement a runtime-agnostic solution as suggested in issue #1019.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: clarifying that Bun installation still requires Node.js runtime, which directly addresses issue #1019.
Out of Scope Changes check	✅ Passed	All changes are in-scope: documentation clarification and a changeset entry directly relate to the linked issue objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/clarify-bun-node-runtime

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/installation.md (1)

29-34: ⚡ Quick win

Clarify the runtime reason for the Node.js requirement.

The warning is correct, but it would be more actionable if it also explains why Node is still required (e.g., the globally installed CLI binary uses a node shebang and thus needs Node on PATH). This ties directly back to #1019 and reduces confusion.

🛠️ Proposed docs tweak

-Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js.
-You still need Node.js 20.19.0 or higher available on `PATH`.
+Bun can install OpenSpec globally, but running the installed `openspec` CLI still requires Node.js.
+You still need Node.js 20.19.0 or higher available on `PATH` (the generated CLI is executed with Node).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/installation.md` around lines 29 - 34, Update the paragraph that
currently states "Bun can install OpenSpec globally, but OpenSpec currently runs
on Node.js. You still need Node.js 20.19.0 or higher available on `PATH`." to
explicitly explain why Node is required: mention that the globally installed CLI
binary (the package installed with `bun add -g `@fission-ai/openspec`@latest`)
uses a `node` shebang and therefore requires a compatible `node` executable on
the PATH (Node.js 20.19.0+), so users understand the runtime dependency and the
reason behind the warning.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/installation.md`:
- Around line 29-34: Update the paragraph that currently states "Bun can install
OpenSpec globally, but OpenSpec currently runs on Node.js. You still need
Node.js 20.19.0 or higher available on `PATH`." to explicitly explain why Node
is required: mention that the globally installed CLI binary (the package
installed with `bun add -g `@fission-ai/openspec`@latest`) uses a `node` shebang
and therefore requires a compatible `node` executable on the PATH (Node.js
20.19.0+), so users understand the runtime dependency and the reason behind the
warning.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 334f0194-a737-4154-869d-e8cdd383ae18

📥 Commits

Reviewing files that changed from the base of the PR and between 485c97e and f1a9ec8.

📒 Files selected for processing (2)

• .changeset/clarify-bun-node-runtime.md
• docs/installation.md

[alfred-openspec]

Looks good. Docs-only clarification matches the runtime behavior, and CI is green.