link-assistant · konard · Jan 31, 2026 · Jan 30, 2026 · Jan 30, 2026 · Jan 30, 2026
diff --git a/README.md b/README.md
@@ -33,13 +33,25 @@ Both implementations aim to be fully compatible with [OpenCode](https://github.c
 The primary implementation, feature-complete and production-ready. Requires [Bun](https://bun.sh) >= 1.0.0.
 
 ```bash
-# Install
+# Step 1: Install Bun (skip if already installed)
+curl -fsSL https://bun.sh/install | bash
+source ~/.bashrc  # Or restart your terminal (use ~/.zshrc for Zsh)
+
+# Step 2: Verify Bun is working
+bun --version
+
+# Step 3: Install the agent globally
 bun install -g @link-assistant/agent
 
-# Usage
+# Step 4: Verify the agent is working
+agent --version
+
+# Step 5: Run it
 echo "hi" | agent
 ```
 
+> **Troubleshooting:** If `bun` or `agent` is not found after installation, run `source ~/.bashrc` (or `source ~/.zshrc` for Zsh) to reload your PATH, or restart your terminal. See [js/README.md](js/README.md#troubleshooting) for more details.
+
 See [js/README.md](js/README.md) for full documentation including:
 
 - Complete CLI options reference
@@ -53,9 +65,15 @@ See [js/README.md](js/README.md) for full documentation including:
 The Rust implementation provides core functionality but is still under active development.
 
 ```bash
-# Build from source
+# Step 1: Install Rust (skip if already installed)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.bashrc  # Or restart your terminal
+
+# Step 2: Build from source
 cd rust
 cargo build --release
+
+# Step 3: Run it
 ./target/release/agent -p "hello"
 ```
 

diff --git a/docs/case-studies/issue-136/README.md b/docs/case-studies/issue-136/README.md
@@ -0,0 +1,172 @@
+# Case Study: Issue #136 - Simplify Installation
+
+## Summary
+
+A user reported that the installation process was confusing — after installing, the system indicated that environment variables needed to be added, but didn't explain how. The user compared this to OpenCode's installer, which automatically adds itself to `$PATH` and confirms with a message like `Successfully added opencode to $PATH in /home/username/.bashrc`. This case study reconstructs the timeline, identifies root causes, and proposes solutions.
+
+## Issue Reference
+
+- **Issue:** https://github.com/link-assistant/agent/issues/136
+- **Reported by:** @andchir
+- **Date:** 2026-01-26
+- **Component:** Installation process for `@link-assistant/agent`
+- **Runtime:** Bun
+
+## Incident Timeline
+
+| Time | Event |
+|---|---|
+| 2026-01-26 (initial report) | @andchir opens issue #136: "Need to simplify installation or provide more detailed information on how to complete it fully. Currently it says you need to add variables to the environment and that's it." References OpenCode's approach: `Successfully added opencode to $PATH in /home/username/.bashrc` |
+| 2026-01-26 09:34 UTC | @konard responds asking for specifics and pointing to existing README installation instructions |
+| 2026-01-26 11:08 UTC | @andchir replies: reinstalled Bun and agent cleanly, everything worked on second attempt. Provides full log showing successful installation |
+| 2026-01-30 23:34 UTC | @konard requests: (1) Update READMEs for all implementations with clearer instructions, (2) Create case study with root cause analysis |
+
+## Root Cause Analysis
+
+### Primary Root Cause: Bun's `$PATH` configuration is a prerequisite that users may miss
+
+When Bun is installed via `curl -fsSL https://bun.sh/install | bash`, it:
+1. Installs `bun` binary to `~/.bun/bin/bun`
+2. Adds `~/.bun/bin` to `$PATH` in the user's shell configuration file (e.g., `~/.bashrc`)
+3. Prints instructions to `source` the shell configuration
+
+**Critical step often missed:** The user must run `source ~/.bashrc` (or restart the terminal) for the `$PATH` changes to take effect. Without this step:
+- `bun` command may not be found
+- Globally installed packages (like `agent`) won't be found because `~/.bun/bin` is not in `$PATH`
+
+This is a well-documented issue in the Bun ecosystem:
+- [Global installation not adding the path (oven-sh/bun#7136)](https://github.com/oven-sh/bun/issues/7136)
+- [`bun add --global` not working on macOS due to PATH (oven-sh/bun#5990)](https://github.com/oven-sh/bun/issues/5990)
+- [Bun "command not found" after install (oven-sh/bun#13404)](https://github.com/oven-sh/bun/issues/13404)
+
+### Contributing Factor: README did not emphasize the `source` step
+
+The existing installation instructions in `js/README.md` included:
+
+```bash
+# Install Bun first if you haven't already
+curl -fsSL https://bun.sh/install | bash
+
+# Install the package globally
+bun install -g @link-assistant/agent
+```
+
+The instructions did not highlight:
+1. The need to run `source ~/.bashrc` (or restart the terminal) after installing Bun
+2. How to verify Bun is properly installed before proceeding
+3. What to do if the `agent` command is not found after installation
+
+### Contributing Factor: Comparison with OpenCode's smoother UX
+
+OpenCode uses a custom install script (`curl -fsSL https://opencode.ai/install | bash`) that:
+- Downloads and installs the binary
+- Automatically adds it to `$PATH` in the shell configuration
+- Prints a clear confirmation: `Successfully added opencode to $PATH in /home/username/.bashrc`
+- Makes the command available immediately (within the same script execution context)
+
+Our agent relies on Bun's global install mechanism, which adds an extra dependency (Bun itself) and an extra `source` step that users may overlook.
+
+Reference: [OpenCode Installation Docs](https://opencode.ai/docs/cli/) | [OpenCode install script PATH issue (#5884)](https://github.com/sst/opencode/issues/5884)
+
+## Sequence of Events (Reconstructed)
+
+```
+User's First Attempt (Failed):
+┌──────────────────────────────┐
+│ 1. curl ... | bash           │  Bun installed to ~/.bun/bin
+│    (Bun installer)           │  PATH updated in ~/.bashrc
+│                              │  BUT current shell not reloaded
+└──────────────┬───────────────┘
+               │
+               ▼ (possibly skipped: source ~/.bashrc)
+┌──────────────────────────────┐
+│ 2. bun install -g agent      │  May have worked (if bun was found)
+│                              │  OR may have failed silently
+└──────────────┬───────────────┘
+               │
+               ▼
+┌──────────────────────────────┐
+│ 3. agent --version           │  "command not found" or
+│                              │  "need to add variables"
+│                              │  (PATH not set in current shell)
+└──────────────────────────────┘
+
+User's Second Attempt (Succeeded):
+┌──────────────────────────────┐
+│ 1. curl ... | bash           │  Fresh Bun install
+│    (Bun installer)           │
+└──────────────┬───────────────┘
+               │
+               ▼
+┌──────────────────────────────┐
+│ 2. source ~/.bashrc          │  ← KEY STEP: reloads PATH
+└──────────────┬───────────────┘
+               │
+               ▼
+┌──────────────────────────────┐
+│ 3. bun --version → 1.3.6    │  Bun confirmed working
+└──────────────┬───────────────┘
+               │
+               ▼
+┌──────────────────────────────┐
+│ 4. bun install -g agent      │  Agent installed successfully
+│    → agent@0.8.11            │
+└──────────────┬───────────────┘
+               │
+               ▼
+┌──────────────────────────────┐
+│ 5. agent --version → 0.8.11  │  Working correctly
+└──────────────────────────────┘
+```
+
+## Proposed Solutions
+
+### Solution 1: Improve README installation instructions (Implemented)
+
+Update all README files with step-by-step instructions that explicitly include:
+1. The `source` step after Bun installation
+2. Verification commands at each step (`bun --version`, `agent --version`)
+3. A troubleshooting section for common PATH issues
+4. Clear numbering of steps to prevent skipping
+
+### Solution 2: Create a custom install script (Future consideration)
+
+Create a `curl -fsSL https://link-assistant.github.io/agent/install | bash` script that:
+- Installs Bun if not present
+- Installs the agent package globally
+- Verifies PATH configuration
+- Prints a confirmation message similar to OpenCode's
+
+**Known existing tools/approaches:**
+- [OpenCode install script](https://opencode.ai/install) - Shell script that handles PATH configuration
+- [Bun install script](https://bun.sh/install) - Already handles adding `~/.bun/bin` to PATH
+- [nvm install script](https://github.com/nvm-sh/nvm) - Another example of proper PATH management in installers
+
+### Solution 3: Provide alternative installation methods (Future consideration)
+
+Offer additional installation methods that don't require Bun as a prerequisite:
+- `npx @link-assistant/agent` (for Node.js users, if Node.js support is added)
+- Pre-built binaries (like the Rust implementation, once complete)
+- Docker image: `docker run -it link-assistant/agent`
+
+## Impact Assessment
+
+- **Severity:** Medium - Installation works, but the process can be confusing for new users
+- **Frequency:** Affects first-time users who haven't used Bun before
+- **Affected users:** New users installing the agent for the first time
+- **Workaround:** Run `source ~/.bashrc` after Bun installation, or restart the terminal
+
+## Files Changed
+
+- `README.md` - Updated main README with clearer installation section
+- `js/README.md` - Updated JavaScript README with step-by-step installation with verification
+- `rust/README.md` - Updated Rust README with clearer prerequisite and installation steps
+
+## References
+
+- [Bun Installation Documentation](https://bun.sh/docs/installation)
+- [Global installation not adding the path (oven-sh/bun#7136)](https://github.com/oven-sh/bun/issues/7136)
+- [`bun add --global` not working on macOS (oven-sh/bun#5990)](https://github.com/oven-sh/bun/issues/5990)
+- [Bun "command not found" after install (oven-sh/bun#13404)](https://github.com/oven-sh/bun/issues/13404)
+- [OpenCode CLI Installation Docs](https://opencode.ai/docs/cli/)
+- [OpenCode install script --no-modify-path request (#5884)](https://github.com/sst/opencode/issues/5884)
diff --git a/js/.changeset/docs-improve-installation-instructions.md b/js/.changeset/docs-improve-installation-instructions.md
@@ -0,0 +1,12 @@
+---
+'@link-assistant/agent': patch
+---
+
+Improve installation instructions with step-by-step guide and troubleshooting
+
+- Add numbered step-by-step installation instructions for JavaScript/Bun version
+- Add explicit `source ~/.bashrc` step to reload shell configuration after Bun installation
+- Add verification commands (`bun --version`, `agent --version`) to confirm successful installation
+- Add comprehensive troubleshooting section covering common installation issues
+- Add Rust installation prerequisites and verification steps
+- Add case study documentation analyzing installation UX improvements (issue #136)
diff --git a/js/README.md b/js/README.md
@@ -46,18 +46,77 @@ This is an MVP implementation of an OpenCode-compatible CLI agent, focused on ma
 
 ## Installation
 
+### Step-by-step (recommended for first-time users)
+
 ```bash
-# Install Bun first if you haven't already
+# Step 1: Install Bun (skip if already installed)
 curl -fsSL https://bun.sh/install | bash
 
-# Install the package globally
+# Step 2: Apply PATH changes (IMPORTANT — required before using bun)
+source ~/.bashrc  # For Bash (default on most Linux systems)
+# source ~/.zshrc  # For Zsh (default on macOS)
+
+# Step 3: Verify Bun is installed
+bun --version
+
+# Step 4: Install the agent globally
+bun install -g @link-assistant/agent
+
+# Step 5: Verify the agent is installed
+agent --version
+
+# Step 6: Run for a test
+echo "hi" | agent
+```
+
+### Quick install (if you already have Bun)
+
+```bash
 bun install -g @link-assistant/agent
+```
 
-# Or install locally in your project
+### Local install (in your project)
+
+```bash
 bun add @link-assistant/agent
 ```
 
-After installation, the `agent` command will be available globally.
+After global installation, the `agent` command will be available in any terminal session.
+
+### Troubleshooting
+
+**`bun: command not found` after installation:**
+
+The Bun installer adds `~/.bun/bin` to your shell configuration file, but the change only takes effect after reloading it. Run:
+
+```bash
+source ~/.bashrc  # or source ~/.zshrc for Zsh
+```
+
+Or restart your terminal.
+
+**`agent: command not found` after `bun install -g`:**
+
+Global packages installed by Bun are placed in `~/.bun/bin`. If this directory is not in your PATH, the `agent` command won't be found. Ensure your shell configuration includes:
+
+```bash
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+```
+
+Then reload with `source ~/.bashrc` (or `~/.zshrc`), or restart your terminal.
+
+**Still not working?**
+
+Try reinstalling Bun from scratch:
+
+```bash
+rm -rf ~/.bun
+curl -fsSL https://bun.sh/install | bash
+source ~/.bashrc
+bun install -g @link-assistant/agent
+agent --version
+```
 
 ## Uninstallation
 

diff --git a/rust/README.md b/rust/README.md
@@ -40,12 +40,22 @@
 
 ## Requirements
 
-- Rust 1.70 or newer
-- Cargo (Rust's package manager)
+- [Rust](https://www.rust-lang.org/tools/install) 1.70 or newer (includes Cargo, Rust's package manager)
 
 ## Installation
 
-### From Source
+### Step 1: Install Rust (skip if already installed)
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.bashrc  # Or restart your terminal (use ~/.zshrc for Zsh)
+
+# Verify Rust is installed
+rustc --version
+cargo --version
+```
+
+### Step 2: Build from source
 
 ```bash
 cd rust