From 0b371845bb617084e819148f981eb0056c6ca785 Mon Sep 17 00:00:00 2001 From: Vatche Isahagian Date: Mon, 6 Apr 2026 15:47:34 -0400 Subject: [PATCH 1/2] docs: improve installation instructions with post-install steps and troubleshooting - Add explicit restart requirement for Bob IDE after installation - Add post-installation verification steps for all platforms - Add comprehensive troubleshooting section for common issues - Clarify what gets installed and where files are located - Add troubleshooting to Hello World tutorial - Address user feedback about unclear installation process Fixes issues reported by users where modes didn't appear after installation because they didn't restart the IDE. --- docs/examples/hello_world/bob.md | 12 ++++- docs/installation/index.md | 78 ++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 1 deletion(-) diff --git a/docs/examples/hello_world/bob.md b/docs/examples/hello_world/bob.md index bfb84731..a0ffc4ff 100644 --- a/docs/examples/hello_world/bob.md +++ b/docs/examples/hello_world/bob.md @@ -24,8 +24,18 @@ Install Evolve by following the [installation instructions →](../../installati curl -fsSL https://raw.githubusercontent.com/AgentToolkit/altk-evolve/main/platform-integrations/install.sh | bash -s -- install --platform bob --mode lite ``` +**Important:** After installation completes, you must **restart Bob IDE** for the new mode to appear. + ## Step 3: Project Setup -Open the project directory in IBM Bob IDE, and switch Bob's mode to `Evolve Lite` +1. **Restart Bob IDE** if you haven't already (close and reopen the application) +2. Open the project directory (`hello-world`) in IBM Bob IDE +3. **Switch Bob's mode to `Evolve Lite`** - Look for the mode selector in Bob's interface and select "Evolve Lite" + +**Troubleshooting:** If "Evolve Lite" doesn't appear in the mode list: +- Verify the installation completed without errors +- Check that `~/.bob/settings/custom_modes.yaml` exists and contains the evolve-lite configuration +- Try restarting Bob IDE again +- Re-run the install script (it's safe to run multiple times) !!! failure "`Evolve Lite` mode not found?" If Bob is running while you install Evolve, the `Evolve Lite` mode will not have been loaded. Try restarting IBM Bob IDE. diff --git a/docs/installation/index.md b/docs/installation/index.md index e1dafdf9..0f3f8601 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -5,6 +5,17 @@ ```bash curl -fsSL https://raw.githubusercontent.com/AgentToolkit/altk-evolve/main/platform-integrations/install.sh | bash -s -- install --platform bob --mode lite ``` + +**What this installs:** +- Evolve Lite mode for IBM Bob +- Custom skills in `~/.bob/skills/` directory +- Custom mode configuration in `~/.bob/custom_modes.yaml` + +**Post-Installation Steps:** +1. **Restart Bob** - Close and reopen IBM Bob IDE to load the new mode +2. **Switch to Evolve Lite mode** - In Bob, select "Evolve Lite" from the mode dropdown +3. **Verify installation** - The mode should appear in `~/.bob/settings/custom_modes.yaml` + Next: [Hello World with IBM Bob](../examples/hello_world/bob.md) ### Claude Code Plugin Marketplace @@ -40,3 +51,70 @@ curl -fsSL https://raw.githubusercontent.com/AgentToolkit/altk-evolve/v1.0.5/pla | `full` | Install all components including UI and CLI | Use `--dry-run` to see what would be installed without making changes. + +## Post-Installation + +### For Bob Users + +After running the install script: + +1. **Restart Bob IDE** - The new mode will not appear until you restart +2. **Locate the mode** - Open Bob and look for "Evolve Lite" in the mode selector +3. **Verify files** - Check that `~/.bob/settings/custom_modes.yaml` contains the Evolve Lite configuration +4. **Test the installation** - Try the [Hello World tutorial](../examples/hello_world/bob.md) + +**Troubleshooting:** +- If the mode doesn't appear after restart, check `~/.bob/settings/custom_modes.yaml` exists +- Ensure the install script completed without errors +- Try running the install script again (it's idempotent) + +### For Claude Code Users + +The Claude plugin system manages installation automatically. After installation: + +1. Verify with: `claude plugin list` +2. The `evolve-lite` plugin should appear in the list + +### For Codex Users + +After installation: + +1. Verify `plugins/evolve-lite/` exists in your project directory +2. Check `.agents/plugins/marketplace.json` contains the evolve-lite entry +3. Enable Codex hooks in `~/.codex/config.toml`: + ```toml + [features] + codex_hooks = true + ``` +4. Restart Codex to load the plugin + +## Common Issues + +### "Instructions didn't work" + +If you encounter issues: + +1. **Check the working directory** - The install script installs to the current directory or `--dir` path +2. **Verify prerequisites** - Ensure Python 3.8+ is installed: `python3 --version` +3. **Run with dry-run first** - See what will be installed: `./install.sh install --platform bob --dry-run` +4. **Check for errors** - Look for error messages in the install output +5. **Restart the IDE** - Many platforms require a restart to load new configurations + +### "No modes showing after install" + +For Bob specifically: +- The mode is installed to `~/.bob/settings/custom_modes.yaml`, not the project directory +- You must restart Bob IDE completely (not just reload) +- Check the file exists and contains the `evolve-lite` mode definition + +### "What am I installing?" + +The install script sets up: +- **Bob Mode**: A custom mode that integrates Evolve learning capabilities +- **Skills**: Pre-built commands for learning and recall operations +- **Configuration**: YAML/JSON files that Bob/Claude/Codex read on startup + +You are NOT installing: +- A separate application +- System-wide changes (everything is in user directories) +- The full Evolve backend (that's optional with `--mode full`) From f7c493ca7c0affb07bf776af4969d2f372f0dfc4 Mon Sep 17 00:00:00 2001 From: Vatche Isahagian Date: Tue, 7 Apr 2026 08:45:37 -0400 Subject: [PATCH 2/2] docs(bob): fix custom mode path references --- docs/examples/hello_world/bob.md | 2 +- docs/installation/index.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/examples/hello_world/bob.md b/docs/examples/hello_world/bob.md index a0ffc4ff..f854ebd0 100644 --- a/docs/examples/hello_world/bob.md +++ b/docs/examples/hello_world/bob.md @@ -33,7 +33,7 @@ curl -fsSL https://raw.githubusercontent.com/AgentToolkit/altk-evolve/main/platf **Troubleshooting:** If "Evolve Lite" doesn't appear in the mode list: - Verify the installation completed without errors -- Check that `~/.bob/settings/custom_modes.yaml` exists and contains the evolve-lite configuration +- Check that `~/.bob/custom_modes.yaml` exists and contains the evolve-lite configuration - Try restarting Bob IDE again - Re-run the install script (it's safe to run multiple times) diff --git a/docs/installation/index.md b/docs/installation/index.md index 0f3f8601..bb882880 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -14,7 +14,7 @@ curl -fsSL https://raw.githubusercontent.com/AgentToolkit/altk-evolve/main/platf **Post-Installation Steps:** 1. **Restart Bob** - Close and reopen IBM Bob IDE to load the new mode 2. **Switch to Evolve Lite mode** - In Bob, select "Evolve Lite" from the mode dropdown -3. **Verify installation** - The mode should appear in `~/.bob/settings/custom_modes.yaml` +3. **Verify installation** - The mode should appear in `~/.bob/custom_modes.yaml` Next: [Hello World with IBM Bob](../examples/hello_world/bob.md) @@ -60,11 +60,11 @@ After running the install script: 1. **Restart Bob IDE** - The new mode will not appear until you restart 2. **Locate the mode** - Open Bob and look for "Evolve Lite" in the mode selector -3. **Verify files** - Check that `~/.bob/settings/custom_modes.yaml` contains the Evolve Lite configuration +3. **Verify files** - Check that `~/.bob/custom_modes.yaml` contains the Evolve Lite configuration 4. **Test the installation** - Try the [Hello World tutorial](../examples/hello_world/bob.md) **Troubleshooting:** -- If the mode doesn't appear after restart, check `~/.bob/settings/custom_modes.yaml` exists +- If the mode doesn't appear after restart, check `~/.bob/custom_modes.yaml` exists - Ensure the install script completed without errors - Try running the install script again (it's idempotent) @@ -103,7 +103,7 @@ If you encounter issues: ### "No modes showing after install" For Bob specifically: -- The mode is installed to `~/.bob/settings/custom_modes.yaml`, not the project directory +- The mode is installed to `~/.bob/custom_modes.yaml`, not the project directory - You must restart Bob IDE completely (not just reload) - Check the file exists and contains the `evolve-lite` mode definition