pi-freeflow 1.7.0 → 1.7.1

package/README.md

@@ -123,33 +123,64 @@ Manage your relay pool directly from the OMP / Pi terminal:
 
 ### Quick Start in 30 Seconds
 
-#### 1. Install
-
-**Oh My Pi (Recommended):**
+**On Oh My Pi (OMP):**
 ```bash
 omp plugin install pi-freeflow
-# or local dev
+# or local dev (repo checkout)
 omp plugin link /path/to/pi-freeflow
 ```
 
-**Pi:**
+**On Pi:**
 ```bash
 pi install npm:pi-freeflow
 ```
 
+> Both commands fetch the **same npm package** from the registry — pi-freeflow
+> is an extension loaded by the host, not a standalone CLI. It works on **OMP
+> and Pi only** (they share the extension API).
+
 #### 2. Pick a Model
 
+**OMP — interactive:**
 ```bash
 omp
 /model → freeflow → muse-spark-1.2-contributor-free (1M) → max
+```
 
-# or CLI
+**OMP — one-shot CLI:**
+```bash
 omp -p --model freeflow/muse-spark-1.2-contributor-free "build me a SaaS"
-# or with short alias & thinking level
-omp -p --model freeflow/step-3.7-flash:high "solve this bug"
+omp -p --model freeflow/step-3.7-flash:high "solve this bug"   # alias + thinking level
+```
+
+**Pi — interactive:**
+```bash
+pi
+/model → freeflow → pick
+```
+
+**Pi — one-shot CLI:**
+```bash
+pi -p --model freeflow/step-3.7-flash:high "solve this bug"
+```
+
+> Model IDs accept a full canonical ID, a short alias (see the tables above),
+> and an optional `:effort` suffix (`:minimal` … `:xhigh`, `:max` where
+> supported). The host resolves the rest — you only type `freeflow/<name>`.
+
+#### 3. Manage Your Relay Pool (OMP & Pi both)
+
+```bash
+/freeflow status     # active relay, pool status, candidates
+/freeflow list       # relays with health badges
+/freeflow add <url> [label]
+/freeflow deploy     # guided deploy: vercel|cloudflare|deno
+/freeflow logs [n]   # tail proxy logs
 ```
 
-#### 3. Add Your Free Relays (Scale Infinitely)
+These slash commands work **identically in OMP and Pi** — the extension
+registers the same `/freeflow` command set in both hosts.
+#### 4. Add Your Free Relays (Scale Infinitely)
 
 Default ships direct. Add relays via `/freeflow add <url> [label]`.
 
@@ -231,7 +262,7 @@ Log rotation at 10MB. Clean, parseable, real-time HTTP lifecycle tracking.
 
 This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step. The only runtime dependency is `undici`, which powers the upstream fetch agent. Thinking and prompt normalization stay with the host (`pi-ai`).
 
-Current size: about 11.3k lines including tests. 228 tests pass, typecheck clean.
+Current size: about 11.3k lines including tests. 230 tests pass, typecheck clean.
 
 ---
 
@@ -251,6 +282,18 @@ Deleted in 1.3.0. If zai/qwen/deepseek thinking broke before, it's fixed now bec
 
 **Why is context free?**
 We use OpenCode Zen & Kilo free tiers. You pay only with your own Cloudflare/Vercel free tiers for egress.
+**Why is it installed via npm?**
+The npm package is the **distribution channel** only — both hosts resolve it internally:
+`omp plugin install pi-freeflow` and `pi install npm:pi-freeflow` install the same
+package from the npm registry. pi-freeflow is an **extension, not a standalone CLI** —
+the host (OMP or Pi) loads and runs it. A plain `npm install` just downloads the
+files; it is not a supported way to run the extension.
+
+**Which hosts can use it?**
+Oh My Pi (OMP) and Pi only. They share the same extension API
+(`extensions/index.ts` declares both `omp` and `pi` extension entries), so one
+package serves both. Other AI agents (OpenCode, KiloCode, Cursor, ...) have their
+own plugin systems and do not load this extension.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",