feat(FN-2693): merge fusion/fn-2693

README.md

@@ -181,6 +181,8 @@ Fusion is built on top of **Pi** — the minimal, extensible coding-agent CLI. E
 pi install npm:@runfusion/fusion
 ```
 
+> This installs the **Pi extension** — it provides Fusion tools and `/fn` inside pi sessions only. To get the `fn` CLI in your terminal, install globally: `npm install -g @runfusion/fusion`.
+
 <br />
 
 <div align="center">
@@ -255,6 +257,8 @@ npm install -g @runfusion/fusion
 fn dashboard                # or: fusion dashboard
 ```
 
+> **Pi extension (optional):** To use Fusion tools inside Pi chat sessions, also run `pi install npm:@runfusion/fusion`. This adds a `/fn` command and Fusion tools within pi — but does not install the `fn` CLI globally.
+
 **From a clone** (for development):
 
 ```bash

docs/getting-started.md

@@ -6,7 +6,12 @@ This guide gets Fusion running, explains first-run setup, and walks through your
 
 ## Prerequisites
 
-Fusion uses the `pi` agent runtime for AI sessions.
+Fusion and `pi` are separate tools:
+
+- **Pi** is the AI agent runtime (similar to how Node.js is a runtime).
+- **Fusion** is the orchestrator built on top of that runtime (similar to a framework/tooling layer).
+
+Fusion requires `pi` because Fusion agents run through the pi runtime. You can also use pi by itself without Fusion if you prefer.
 
 1. Install pi:
 
@@ -98,18 +103,33 @@ For OpenClaw-specific details, see the [OpenClaw Runtime Plugin documentation](.
 
 ## Install Fusion
 
+Fusion can be installed in two different ways depending on where you want to use it:
+
+### Path A: Global CLI (required for `fn` in your shell)
+
 Install the published CLI package globally:
 
 ```bash
 npm i -g @runfusion/fusion
-```
-
-Then verify install:
-
-```bash
 fn --help
 ```
 
+This gives you the `fn` command in your terminal/shell.
+
+### Path B: Pi extension (optional — adds `/fn` inside pi sessions)
+
+Install Fusion as a pi extension:
+
+```bash
+pi install npm:@runfusion/fusion
+```
+
+This adds Fusion tools (`fn_task_create`, `fn_task_list`, etc.) and a `/fn` command inside pi chat sessions.
+
+> **Important:** `pi install npm:@runfusion/fusion` only provides the `/fn` command and Fusion tools *inside pi sessions*. It does **not** make the `fn` CLI available in your terminal. For that, you must also run `npm i -g @runfusion/fusion`.
+
+> **Windows troubleshooting:** If `fn` is not recognized after `npm install -g @runfusion/fusion`, check that the npm global bin directory is in your PATH. You can find it with `npm config get prefix` — the `fn` binary lives in the `bin` subdirectory of that path. The `fn plugin install` command requires the global CLI to be installed first.
+
 ## Initialize a Project
 
 In each repository you want Fusion to manage, run: