pi-freeflow 1.12.1 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.13.0
+
+### Minor Changes
+
+- 39a06b9: Carry a relay pool between machines: `/freeflow export` saves the relays to a file and `/freeflow import` loads them back, adding to the current pool by default or swapping it whole on confirmation.
+
 ## 1.12.1
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,8 @@
-# pi-freeflow 🌊
+# pi-freeflow
 
-> **26 free models. Up to 1M context. Zero API keys. Infinite scale via your own relay pool.**
+> 26 free models with up to 1M context. No API keys to manage. Add your own relays to spread requests across more IPs.
 
-Thin by design: model list + dumb relay + log. Host `pi-ai` owns thinking, normalization & provider magic. We just make it free, fast, and unbreakable.
+Thin by design: a model list, a relay proxy, and a log. The host (`pi-ai`) handles thinking, normalization, and provider behavior.
 
 [![npm version](https://img.shields.io/npm/v/pi-freeflow?style=flat-square&color=00E5FF)](https://www.npmjs.com/package/pi-freeflow)
 [![npm downloads](https://img.shields.io/npm/dm/pi-freeflow?style=flat-square)](https://www.npmjs.com/package/pi-freeflow)
@@ -10,120 +10,22 @@ Thin by design: model list + dumb relay + log. Host `pi-ai` owns thinking, norma
 [![Pi](https://img.shields.io/badge/Powered%20by-Pi-7c3aed?style=flat-square)](https://github.com/badlogic/pi-ai)
 [![Oh My Pi](https://img.shields.io/badge/Compatible-OMP-black?style=flat-square)](https://github.com/coder/oh-my-pi)
 
-Join devs bypassing rate limits with their own relay pools. BYO, add as many as you need.
-
 ---
 
-### Features at a Glance
-
-| Feature | Description | Value | Cost |
-| :--- | :--- | :--- | :--- |
-| **26 Curated Free Models** | 7 OpenCode Zen + 19 KiloCode Gateway models, up to 1M context & 512K output | Ceiling Unlocked | **$0** |
-| **BYO Relay Pool** | Round-robin load balancing across your Cloudflare Workers & Vercel Edges | Zero Rate Limits | **$0** (your free tiers) |
-| **Adaptive Health & Error Detection** | Auto-cooldown on 429 rate limits, 504 timeouts, and socket drops | 0ms Wasted Latency | **$0** |
-| **Stream Truncation Resilience** | Stateful SSE terminal tracking (`response.failed` / `response.incomplete` injection) | Zero Host Crashes | **$0** |
-| **Smart Model Aliasing** | Clean slash-free & colon-free CLI model names compatible with thinking selectors | DX Optimized | **$0** |
-| **Auto-Enabled on Session** | Relay stays enabled in `auto` mode on session start and model switch | Zero Friction | **$0** |
-| **Interactive CLI Management** | 10+ `/freeflow` subcommands (`status`, `list`, `use`, `add`, `label`, `remove`, `deploy`, `logs`, `debug`) | Full Control | **$0** |
-| **Dumb Proxy That Never Breaks** | `127.0.0.1:28180`, host-normalized, pathname-guarded `/v1/models` | 100% Uptime | **$0** |
-| **Observable Real Logs** | `~/.pi/agent/pi-freeflow.log`, 10MB auto-rotation, real-time debug toggle | Observable | **$0** |
+### What you get
 
-Philosophy: **Thin by design.** We only ship model list + relay proxy + log. Host owns thinking & normalization.
+| Feature | What it does | Cost |
+| :--- | :--- | :--- |
+| **26 free models** | 7 from OpenCode Zen, 19 from KiloCode Gateway, context windows up to 1M. Full list below. | **$0** |
+| **Relay pool** | Route requests through your own Cloudflare Workers and Vercel Edge relays. Requests rotate across the pool. A relay that rate-limits, times out, or drops the connection cools down while healthy ones take its traffic. | **$0** beyond your platforms' free tiers |
+| **Automatic fallback** | When every relay is cooling down, requests go direct to upstream instead of failing. | **$0** |
+| **Short model names** | Every model has a slash-free, colon-free alias, plus an optional `:effort` suffix for thinking depth. You type `freeflow/<name>`. | **$0** |
+| **Shared local proxy** | One daemon on `127.0.0.1:28180` serves every session on the machine, so parallel subagents reuse it instead of opening their own connections. | **$0** |
+| **Logs you can read** | `~/.pi/agent/pi-freeflow.log`, rotated at 10MB. Tail it with `/freeflow logs`. | **$0** |
 
 ---
 
-### 26 Curated Models, One Command
-
-```bash
-/model → freeflow → pick
-```
-
-#### OpenCode Zen (7 Models), Responses & Chat API
-Optimized for deep reasoning, long-horizon coding & autonomous agentic workflows.
-
-| Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| `muse-spark-1.2-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
-| `muse-spark-1.3-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
-| `mimo-v2.5-free` | Xiaomi MiMo | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh`\* | ✅ |
-| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal … xhigh` | ❌ |
-| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal … xhigh` | ❌ |
-| `big-pickle` | Big Pickle | **200K** (200.000) | **32K** (32.000) | `high / max` | ❌ |
-| `ling-3.0-flash-fin-free` | Inclusion AI | **262K** (262.144) | **131K** (131.072) | `minimal … xhigh` | ❌ |
-
-#### KiloCode Gateway (19 Models), OpenRouter Compatible
-Keyless access with `Bearer kilo-free`. Clean slash-free and colon-free CLI aliases supported.
-
-| Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| `dots-3-note-preview` (`dots-studio/...:free`) | Dots Studio | **512K** (512.000) | **512K** (512.000) | `minimal…xhigh`\* | ✅ |
-| `step-3.7-flash` (`stepfun/...:free`) | StepFun | **262K** (262.144) | **262K** (262.144) | `minimal…xhigh`\* | ✅ |
-| `nemotron-3-nano-omni` (`nvidia/...:free`) | NVIDIA | **256K** (256.000) | **131K** (131.072) | `minimal…xhigh`\* | ✅ |
-| `nemotron-3-ultra-550b` (`nvidia/...:free`) | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal…xhigh`\* | ❌ |
-| `nvidia/nemotron-3.5-lightning:free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal…xhigh`\* | ❌ |
-| `nemotron-3-super` (`nvidia/...:free`) | NVIDIA | **262K** (262.144) | **262K** (262.144) | `minimal…xhigh`\* | ❌ |
-| `north-mini-code` (`cohere/...:free`) | Cohere | **256K** (256.000) | **64K** (64.000) | `minimal…xhigh`\* | ❌ |
-| `laguna-s-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
-| `laguna-xs-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
-| `lfm-2.5` (`liquid/lfm-2.5-2.6b:free`) | Liquid AI | **65K** (65.536) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
-| `kilo-auto` (`kilo-auto/free`) | Kilo Gateway Auto | **256K** (256.000) | **10K** (10.000) | `minimal…xhigh`\* | ❌ |
-| `openrouter` (`openrouter/free`) | OpenRouter Free | **200K** (200.000) | **65K** (65.536) | `minimal…xhigh`\* | ✅ |
-| `content-safety` (`nvidia/...:free`) | NVIDIA | **128K** (128.000) | **8K** (8.192) | ❌ *(non-thinking)* | ✅ |
-| `ling-3.0-flash-fin` (`inclusionai/ling-3.0-flash-fin:free`) | Inclusion AI | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
-| `ling-3.0-flash-sante` (`inclusionai/ling-3.0-flash-sante:free`) | Inclusion AI | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
-| `nex-n2.5-pro` (`nex-agi/nex-n2.5-pro:free`) | Nex AGI | **262K** (262.144) | **235K** (235.929) | `minimal…xhigh`\* | ✅ |
-| `nex-n2.5-mini` (`nex-agi/nex-n2.5-mini:free`) | Nex AGI | **262K** (262.144) | **235K** (235.929) | `minimal…xhigh`\* | ✅ |
-| `ling-3.0-flash-vl` (`inclusionai/ling-3.0-flash-vl:free`) | Inclusion AI | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ✅ |
-| `inkling-small` (`thinkingmachines/inkling-small:free`) | Thinking Machines | **1M** (1.048.576) | **262K** (262.144) | `minimal…xhigh`\* | ✅ |
-
-\* Levels are forwarded as-is through the OpenRouter-style nested `reasoning` parameter; effort mapping is decided by each model. MiMo collapses `minimal→low` and `xhigh→high` upstream, so its selector shows 5 labels but only 3 distinct effort values.
-
----
-
-### How It Works: BYO Relays, Zero Rate Limits
-
-```
-You → 127.0.0.1:28180 (dumb proxy, host-normalized) → x-relay-target → N egress IPs (your pool) → opencode.ai / api.kilo.ai
-                                     ↑ host already normalized thinking → proxy just forwards
-```
-
-1. **Per-Request Round-Robin**: 10 parallel subagents hit N different egress IPs (your pool size). No thundering herd.
-2. **Adaptive Health & Error Cooldown**: Relays hitting 429, 504, or socket disconnects enter temporary cooldown (30-90s) and automatically move behind healthy candidates. Healthy relays handle traffic with 0ms wasted delay.
-3. **Seamless 429 Roll**: `429 / 408 / 502 / 503 / 504 / 520-530` → instant roll to next relay, never 429 to agent.
-4. **Stream Truncation Resilience**: Stateful SSE terminal tracking prevents fatal unhandled stream closed errors when connections drop.
-5. **Direct Fallback Safety Net**: If all relays in the pool are exhausted, transparent direct fetch to upstream.
-6. **Zero Subagent Connect Errors**: 24h `DISK_CACHE_ONLY` model catalog avoids subagents hammering remote catalogs.
-
-You bring the relays (free tiers). We bring the rolling.
-
----
-
-### Interactive Commands Reference (`/freeflow`)
-
-Manage your relay pool directly from the OMP / Pi terminal:
-
-```bash
-/freeflow status                  # View active relay, pool status, and candidates
-/freeflow list                    # List all relays with real-time health badges (✓ / ⚠️ [cooling])
-/freeflow use <url|index|label>   # Switch active relay
-/freeflow url <url>               # Set the active relay URL directly
-/freeflow add <url> [label]       # Add new relay to the pool
-/freeflow label <index|url> <name># Assign a friendly label to a relay
-/freeflow remove <index|url|label># Remove a relay from the pool
-/freeflow test <index|url|label>  # Probe a relay for reachability (HTTP 200 + latency)
-/freeflow on | off | auto         # Toggle relay mode (auto = enabled for freeflow)
-/freeflow deploy <platform>       # Guided relay deploy: vercel|cloudflare|deno — token in-memory, auto-adds (Vercel 1M/mo recommended)
-/freeflow logs [lines]            # Inspect recent proxy logs
-/freeflow trace [req-id]          # Tail logs filtered by request correlation ID
-/freeflow refresh                 # Reload the model catalog from live upstreams
-/freeflow update                  # Check for and install a package update
-/freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
-/freeflow kill                    # Stop the shared proxy daemon now (restarts on next use)
-```
-
----
-
-### Quick Start in 30 Seconds
+### Install
 
 **On Oh My Pi (OMP):**
 ```bash
@@ -137,69 +39,61 @@ omp plugin link /path/to/pi-freeflow
 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).
+> 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
+### Pick a model
 
-**OMP — interactive:**
+**OMP, interactive:**
 ```bash
 omp
 /model → freeflow → muse-spark-1.2-contributor-free (1M) → max
 ```
 
-**OMP — one-shot CLI:**
+**OMP, one shot:**
 ```bash
 omp -p --model freeflow/muse-spark-1.2-contributor-free "build me a SaaS"
 omp -p --model freeflow/step-3.7-flash:high "solve this bug"   # alias + thinking level
 ```
 
-**Pi — interactive:**
+**Pi, interactive:**
 ```bash
 pi
 /model → freeflow → pick
 ```
 
-**Pi — one-shot CLI:**
+**Pi, one shot:**
 ```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
-```
+Model IDs accept a full canonical ID, a short alias (see the tables below),
+and an optional `:effort` suffix (`:minimal` through `:xhigh`, `:max` where
+supported). The host resolves the rest.
 
-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)
+### Add relays
 
-Default ships direct. Add relays via `/freeflow add <url> [label]`.
+The default setup talks to upstream directly. Add relays when shared IPs start
+hitting rate limits. The fastest path is guided deploy: run
+`/freeflow deploy cloudflare` (or `deno`, `vercel`), paste your platform token
+once when asked, and the relay is created and added to your pool. The token
+stays in memory and is never written to disk.
 
-**Zero setup?** Run `/freeflow deploy cloudflare` (or `deno`, `vercel`), paste your platform token once, and the relay is created and activated for you. Manual snippets below.
+Manual fallback per platform:
 
-**Option A: Cloudflare Workers (100k req/day, no 25s timeout) — Auto Deploy**
+**Option A: Cloudflare Workers, auto deploy**
 ```bash
 /freeflow deploy cloudflare  # prompts token in-memory, auto-adds to pool
 ```
-*Manual fallback:* `dash.cloudflare.com` → Workers → Create → Deploy → Edit code → paste the canonical worker source (see "Canonical worker source" below) → Deploy → `/freeflow add https://your.workers.dev cf-worker-1`
+Manual fallback: `dash.cloudflare.com` → Workers → Create → Deploy → Edit code → paste the canonical worker source (see below) → Deploy → `/freeflow add https://your.workers.dev cf-worker-1`
 
-**Option B: Vercel Edge Relay (1M req/mo) — Auto Deploy**
+**Option B: Vercel Edge Relay, auto deploy**
 ```bash
 /freeflow deploy vercel  # prompts token in-memory, auto-adds to pool
 # or shorthand: /freeflow deploy
 ```
-*Manual fallback:* Push 2 files (`api/relay.js` + `vercel.json`) to GitHub $\to$ Import on `vercel.com` $\to$ `/freeflow add https://your.vercel.app vercel-relay-1`
+Manual fallback: push 2 files (`api/relay.js` + `vercel.json`) to GitHub, then Import on `vercel.com`, then `/freeflow add https://your.vercel.app vercel-relay-1`
 
 For `api/relay.js`, use the canonical worker source (see below); `vercel.json` stays:
 
@@ -207,20 +101,20 @@ For `api/relay.js`, use the canonical worker source (see below); `vercel.json` s
 { "rewrites": [{ "source": "/(.*)", "destination": "/api/relay" }] }
 ```
 
-**Option C: Deno Deploy (100k req/day) — Auto Deploy**
+**Option C: Deno Deploy, auto deploy**
 ```bash
 /freeflow deploy deno  # prompts token in-memory, auto-adds to pool
 ```
-*Manual fallback:* `dash.deno.com` → New Project → Playground → paste the canonical worker source (see below) → Deploy → `/freeflow add https://your-project.deno.dev deno-relay-1`
+Manual fallback: `dash.deno.com` → New Project → Playground → paste the canonical worker source (see below) → Deploy → `/freeflow add https://your-project.deno.dev deno-relay-1`
 
 **Canonical worker source (all platforms)**
 
-The relay worker template is generated per deployment by `/freeflow deploy` and lives in [`src/deploy.ts`](src/deploy.ts): one hardened core plus thin Vercel / Cloudflare / Deno wrappers. Deployed relays are public by default for seamless migration across proxy tools (such as 9router), while enforcing the target allowlist (`https://opencode.ai`, `https://api.kilo.ai`), SSRF/private-host guard, relay-path validation, and a header denylist.
+The relay worker template is generated per deployment by `/freeflow deploy`, with one shared core adapted for Vercel, Cloudflare, and Deno. Deployed relays accept requests from any pi-freeflow user by default, while only forwarding to an allowlist (`https://opencode.ai`, `https://api.kilo.ai`) with private-host and path checks.
 
 ```js
 // Minimal Cloudflare illustration. Prefer /freeflow deploy: the generated
-// worker (src/deploy.ts) is the signed/hardened source for all three
-// platforms. This example omits the SSRF guard, path validation, and auth.
+// worker is the hardened source for all three platforms.
+// This example omits the private-host guard, path validation, and auth.
 const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
 export default {
   async fetch(req) {
@@ -238,53 +132,141 @@ export default {
 
 **Verify your pool:**
 ```bash
-/freeflow status        # relay-A 1/N (ON) → candidates:N
-/freeflow list          # lists all relays with health status
+/freeflow status        # active relay, pool status, candidates
+/freeflow list          # every relay with health status
 /freeflow logs          # tail -25
-cat ~/.pi/agent/pi-freeflow.log | tail -n 20
+```
+
+### Carry your pool to another machine
+
+```bash
+/freeflow export                        # save pool to ./freeflow-relays.json
+/freeflow export backup/team.json       # save to a path you choose
+/freeflow import backup/team.json       # add its relays to this machine (merge)
+/freeflow import backup/team.json --replace --dry-run  # preview a full swap first
+```
+
+Merge is the default and never deletes anything. Replace swaps the whole pool
+and always asks first. Passwords stay out of the file unless you pass
+`--include-secrets`; a file without passwords still imports, and you re-enter
+each password once afterwards.
+
+---
+
+### Commands reference (`/freeflow`)
+
+The same command set works identically in OMP and Pi:
+
+```bash
+/freeflow status                  # View active relay, pool status, and candidates
+/freeflow list                    # List all relays with real-time health badges
+/freeflow use <url|index|label>   # Switch active relay
+/freeflow url <url>               # Set the active relay URL directly
+/freeflow add <url> [label]       # Add new relay to the pool
+/freeflow label <index|url> <name># Assign a friendly label to a relay
+/freeflow remove <index|url|label># Remove a relay from the pool
+/freeflow test <index|url|label>  # Probe a relay for reachability and latency
+/freeflow on | off | auto         # Toggle relay mode (auto = enabled for freeflow)
+/freeflow deploy <platform>       # Guided relay deploy: vercel|cloudflare|deno, token in-memory, auto-adds
+/freeflow logs [lines]            # Inspect recent proxy logs
+/freeflow trace [req-id]          # Tail logs filtered by request correlation ID
+/freeflow refresh                 # Reload the model catalog from live upstreams
+/freeflow update                  # Check for and install a package update
+/freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
+/freeflow kill                    # Stop the shared proxy daemon now (restarts on next use)
+/freeflow export [path] [--include-secrets]  # Save the relay pool to a file (default freeflow-relays.json; passwords left out unless asked)
+/freeflow import <path> [--merge|--replace] [--dry-run]  # Load a relay pool from a file (merge is default; replace asks first; dry-run previews only)
 ```
 
 ---
 
-### Logs & Debugging
+### 26 models, one command
+
+```bash
+/model → freeflow → pick
+```
+
+#### OpenCode Zen (7 models), Responses and Chat API
+
+Good defaults for long coding sessions and agentic work.
+
+| Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `muse-spark-1.2-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
+| `muse-spark-1.3-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh` | ✅ |
+| `mimo-v2.5-free` | Xiaomi MiMo | **1M** (1.048.576) | **131K** (131.072) | `minimal … xhigh`\* | ✅ |
+| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal … xhigh` | ❌ |
+| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal … xhigh` | ❌ |
+| `big-pickle` | Big Pickle | **200K** (200.000) | **32K** (32.000) | `high / max` | ❌ |
+| `ling-3.0-flash-fin-free` | Inclusion AI | **262K** (262.144) | **131K** (131.072) | `minimal … xhigh` | ❌ |
+
+#### KiloCode Gateway (19 models), OpenRouter compatible
+
+Keyless access. Short aliases work for every row (the full ID is in parentheses).
+
+| Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `dots-3-note-preview` (`dots-studio/...:free`) | Dots Studio | **512K** (512.000) | **512K** (512.000) | `minimal…xhigh`\* | ✅ |
+| `step-3.7-flash` (`stepfun/...:free`) | StepFun | **262K** (262.144) | **262K** (262.144) | `minimal…xhigh`\* | ✅ |
+| `nemotron-3-nano-omni` (`nvidia/...:free`) | NVIDIA | **256K** (256.000) | **131K** (131.072) | `minimal…xhigh`\* | ✅ |
+| `nemotron-3-ultra-550b` (`nvidia/...:free`) | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal…xhigh`\* | ❌ |
+| `nvidia/nemotron-3.5-lightning:free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal…xhigh`\* | ❌ |
+| `nemotron-3-super` (`nvidia/...:free`) | NVIDIA | **262K** (262.144) | **262K** (262.144) | `minimal…xhigh`\* | ❌ |
+| `north-mini-code` (`cohere/...:free`) | Cohere | **256K** (256.000) | **64K** (64.000) | `minimal…xhigh`\* | ❌ |
+| `laguna-s-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `laguna-xs-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `lfm-2.5` (`liquid/lfm-2.5-2.6b:free`) | Liquid AI | **65K** (65.536) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `kilo-auto` (`kilo-auto/free`) | Kilo Gateway Auto | **256K** (256.000) | **10K** (10.000) | `minimal…xhigh`\* | ❌ |
+| `openrouter` (`openrouter/free`) | OpenRouter Free | **200K** (200.000) | **65K** (65.536) | `minimal…xhigh`\* | ✅ |
+| `content-safety` (`nvidia/...:free`) | NVIDIA | **128K** (128.000) | **8K** (8.192) | ❌ *(non-thinking)* | ✅ |
+| `ling-3.0-flash-fin` (`inclusionai/ling-3.0-flash-fin:free`) | Inclusion AI | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `ling-3.0-flash-sante` (`inclusionai/ling-3.0-flash-sante:free`) | Inclusion AI | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ❌ |
+| `nex-n2.5-pro` (`nex-agi/nex-n2.5-pro:free`) | Nex AGI | **262K** (262.144) | **235K** (235.929) | `minimal…xhigh`\* | ✅ |
+| `nex-n2.5-mini` (`nex-agi/nex-n2.5-mini:free`) | Nex AGI | **262K** (262.144) | **235K** (235.929) | `minimal…xhigh`\* | ✅ |
+| `ling-3.0-flash-vl` (`inclusionai/ling-3.0-flash-vl:free`) | Inclusion AI | **262K** (262.144) | **32K** (32.768) | `minimal…xhigh`\* | ✅ |
+| `inkling-small` (`thinkingmachines/inkling-small:free`) | Thinking Machines | **1M** (1.048.576) | **262K** (262.144) | `minimal…xhigh`\* | ✅ |
+
+\* Levels are forwarded as-is through the OpenRouter-style nested `reasoning` parameter; effort mapping is decided by each model. MiMo collapses `minimal→low` and `xhigh→high` upstream, so its selector shows 5 labels but only 3 distinct effort values.
+
+---
+
+### Logs and debugging
 
 ```bash
 /freeflow logs
 cat ~/.pi/agent/pi-freeflow.log | tail -n 50
 
-# debug toggle (full debug is on by default for complete error reports; `off` restores info)
+# full debug logging is on by default; `off` restores info level
 /freeflow debug on
 ```
 
-Log rotation at 10MB. Clean, parseable, real-time HTTP lifecycle tracking.
-
 ---
 
 ### Design
 
-This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step. Zero runtime dependencies — uses native Node.js global fetch. Thinking and prompt normalization stay with the host (`pi-ai`).
+This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step and zero runtime dependencies. Thinking and prompt normalization stay with the host (`pi-ai`).
 
-Current size: about 11.3k lines including tests. The full suite (sandboxed, mocked network) and typecheck pass before every release — see CHANGELOG.md.
+About 19k lines including tests. The full suite (sandboxed, network-mocked) and typecheck pass before every release. See CHANGELOG.md.
 
 ---
 
 ### FAQ
 
 **Do I need API keys?**
-No. Kilo uses `Bearer kilo-free`, OpenCode free models are anonymous (no header needed).
+No. Kilo uses a shared free credential and OpenCode free models need no header. You never paste a key.
 
-**What if all relays are 429?**
-Proxy tries direct. If that is also 429, Pi shows the rate limit. That number is the global upstream cap; without relays you would hit the same wall.
+**What if all relays hit rate limits?**
+The proxy tries direct upstream. If that is also rate-limited, the host shows the limit. That number is the shared upstream cap; without relays you would hit the same wall sooner.
 
-**Can I use without relays?**
-Yes. `/freeflow off` → direct. Add relays later to scale.
+**Can I use it without relays?**
+Yes. `/freeflow off` talks direct. Add relays later when you need them.
 
 **What happens when I update to a new version?**
 The local proxy daemon is shared across sessions on port 28180. On upgrade, the new extension
-detects a stale daemon (mismatched internal version) and replaces it automatically — no manual
-kill, no restart of other sessions required. Replacement only happens when the running daemon is
+detects a stale daemon (an older version still running) and replaces it automatically, with no manual
+kill and no restart of other sessions. Replacement only happens when the running daemon is
 idle: sessions with in-flight requests are never interrupted (busy or newer daemons are reused
-with a log note instead). If a daemon cannot be replaced (e.g. port held by an unrelated process),
+with a log note instead). If a daemon cannot be replaced (for example the port is held by an unrelated process),
 it falls back to reusing it with a warning. To disable replacement entirely, set the no-kill env
 to `1` before starting a session.
 
@@ -293,41 +275,35 @@ Nothing visible to your other sessions. The proxy daemon is a separate backgroun
 process shared by every OMP/Pi session on the machine. Closing one session just
 unregisters it; the daemon keeps serving the rest and retires itself automatically
 once the last client disconnects and no client re-attaches within a short grace window.
-To stop it manually, run `/freeflow kill` — the next freeflow use starts it again.
+To stop it manually, run `/freeflow kill`. The next freeflow use starts it again.
 
-**Why did my session stop with "reasoning `encrypted_content` was not issued to this caller"?**
-Reasoning models on the Responses API sign each thinking block for the upstream backend that produced it, and only that backend can read it back. When a later turn reaches a different backend, the replayed thinking blocks are rejected, and the host keeps re-sending the same history, so the session cannot continue on its own. pi-freeflow now handles this two ways: it keeps each conversation on the relay that issued its reasoning while that relay is healthy, and when the relay must change anyway (rate limit, relay removed or redeployed, direct-mode switch) it sends that turn's history without the signed thinking blocks, so the new backend accepts it immediately instead of rejecting the request. As a last resort it retries once without the blocks, then remembers which blocks were rejected and drops only those on later turns, keeping everything the current backend can read. Messages, tool calls and tool results are always preserved.
+**Why did my long session stop with a "reasoning was not issued to this caller" error?**
+The upstream backend signs each thinking block so only the backend that produced it can read it back. When a later turn reaches a different backend, the old blocks get rejected and the session stalls. pi-freeflow keeps each conversation on the relay that produced its thinking while that relay is healthy. When the relay has to change anyway (rate limit, relay removed, direct-mode switch), that turn is sent without the old thinking blocks so the new backend accepts it, and only the rejected blocks are dropped afterwards. Messages, tool calls, and tool results are always kept.
 
-**Where's the normalizer?**
-Deleted in 1.3.0. If zai/qwen/deepseek thinking broke before, it's fixed now because host handles it.
-
-**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:
+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
+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
+Oh My Pi (OMP) and Pi only. They share the same extension API, so one
+package serves both. Other AI agents (OpenCode, KiloCode, Cursor, and similar) have their
 own plugin systems and do not load this extension.
 
 ---
 
 ### Contributing
 
-Contributions welcome — bug fixes, new relay platforms, model additions, docs improvements.
+Contributions welcome: bug fixes, new relay platforms, model additions, docs improvements.
 
 #### Prerequisites
 
 - **Node.js ≥ 22.19.0** (uses `--experimental-strip-types`, no build step)
 - **pnpm** (package manager)
 
-#### Setup & Verify
+#### Setup and verify
 
 ```bash
 git clone https://github.com/trefeon/pi-freeflow
@@ -335,12 +311,12 @@ cd pi-freeflow
 pnpm install
 
 # run all three before opening a PR
-pnpm test        # full suite; sandboxed + network-mocked
+pnpm test        # full suite; sandboxed and network-mocked
 pnpm typecheck   # tsc --noEmit, must pass clean
 pnpm smoke       # verifies extensions/index.ts loads without crashing
 ```
 
-#### Project Structure
+#### Project structure
 
 ```
 src/
@@ -348,9 +324,9 @@ src/
 ├── models.ts         # 26-model catalog definitions
 ├── catalog.ts        # model catalog cache (24h disk)
 ├── proxy.ts          # local proxy server (127.0.0.1:28180)
-├── relay.ts          # relay selection & round-robin
+├── relay.ts          # relay selection and round-robin
 ├── relay-state.ts    # relay pool state, health tracking
-├── stream-pipe.ts    # SSE stream piping & truncation resilience
+├── stream-pipe.ts    # SSE stream piping and truncation resilience
 ├── commands.ts       # /freeflow CLI subcommands
 ├── deploy.ts         # guided relay deploy (vercel/cloudflare/deno)
 ├── config.ts         # constants, whitelists, paths, and runtime settings
@@ -369,7 +345,7 @@ test/
 - **Keep model IDs clean.** Slash-free, colon-free aliases for CLI compatibility. See existing patterns in `models.ts`.
 - **One concern per PR.** Bug fix? One PR. New relay platform? Separate PR. Easier to review, faster to merge.
 
-#### Reporting Issues
+#### Reporting issues
 
 Found a bug or want a feature? [Open an issue](https://github.com/trefeon/pi-freeflow/issues) with:
 - What happened vs what you expected
@@ -381,4 +357,3 @@ Found a bug or want a feature? [Open an issue](https://github.com/trefeon/pi-fre
 ### License
 
 MIT © trefeon
-

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "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",

package/src/commands.ts

@@ -36,10 +36,16 @@ import {
 } from "./logger.ts";
 import { probeRelay } from "./probe.ts";
 import {
+	buildRelayExport,
 	ensureRelay,
+	EXPORT_DEFAULT_FILENAME,
+	EXPORT_MAX_BYTES,
 	findRelay,
 	getActiveRelayState,
 	getRelayHealth,
+	loadRelayState,
+	parseRelayImport,
+	planRelayImport,
 	removeRelay,
 	setActiveRelayState,
 	setRelayLabel,
@@ -327,7 +333,7 @@ export function createCommandSpec(
 ): Omit<RegisteredCommand, "name"> {
 	return {
 		description:
-			"Relay egress: auto | on | off | hide | show | widget hide/show | status | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | test <target> | logs [level] [n] | debug on|off | refresh | update | deploy vercel | deploy cloudflare | deploy deno | install-startup | uninstall-startup",
+			"Relay egress: auto | on | off | hide | show | widget hide/show | status | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | test <target> | export [path] [--include-secrets] | import <path> [--merge|--replace] [--dry-run] | logs [level] [n] | debug on|off | refresh | update | deploy vercel | deploy cloudflare | deploy deno | install-startup | uninstall-startup",
 		getArgumentCompletions: (prefix: string) =>
 			[
 				"auto",
@@ -344,6 +350,8 @@ export function createCommandSpec(
 				"label",
 				"rename",
 				"remove",
+				"export",
+				"import",
 				"test",
 				"url",
 				"deploy",
@@ -645,6 +653,183 @@ export function createCommandSpec(
 				persist();
 				ctx.ui.notify(`Removed: [${shortRelayLabel(match.url, relayState.relays)}] ${match.url}`, "info");
 			};
+			const classifyImportFailure = (filePath: string, raw: string): string => {
+				let parsed: unknown = null;
+				try {
+					parsed = JSON.parse(raw);
+				} catch (e) {
+					return `Relay file ${filePath} is not valid JSON (${(e as Error).message}). Nothing changed.`;
+				}
+				const version = parsed !== null && typeof parsed === "object" && "version" in parsed
+					? parsed.version
+					: undefined;
+				if (typeof version !== "undefined" && version !== 1) {
+					return `Relay file ${filePath} uses version ${String(version)}, this version understands version 1. Update then try again. Nothing changed.`;
+				}
+				return `Relay file ${filePath} is not a relay export (missing relay list). Nothing changed.`;
+			};
+
+			const runExport = async (pathArg?: string, includeSecrets = false) => {
+				let state: RelayState;
+				try {
+					state = getActiveRelayState();
+				} catch {
+					state = loadRelayState();
+				}
+				const artifact = buildRelayExport(state, { includeSecrets });
+				const count = artifact.state.relays.length;
+				let target = pathArg ? path.resolve(pathArg) : path.resolve(EXPORT_DEFAULT_FILENAME);
+				if (!pathArg) {
+					const choice = await ctx.ui.select("Share relays (export file)", [
+						`Export to ${target}`,
+						"Choose another path…",
+						"Cancel",
+					]);
+					if (!choice || choice === "Cancel") return;
+					if (choice === "Choose another path…") {
+						const picked = (await ctx.ui.input("Export path:", target))?.trim();
+						if (!picked) return;
+						target = path.resolve(picked);
+					}
+				}
+				if (fs.existsSync(target)) {
+					if (typeof ctx.ui.confirm === "function") {
+						const ok = await ctx.ui.confirm(
+							"Export relays",
+							`File already exists: ${target}\nOverwrite it?`,
+						);
+						if (!ok) {
+							ctx.ui.notify("Export cancelled — existing file left alone", "warning");
+							return;
+						}
+					}
+				}
+				try {
+					fs.writeFileSync(target, JSON.stringify(artifact, null, 2));
+				} catch (e) {
+					ctx.ui.notify(`Could not write relay file ${target}: ${(e as Error).message}.`, "error");
+					return;
+				}
+				updateStatusBar(ctx.ui);
+				flash();
+				ctx.ui.notify(
+					includeSecrets
+						? `Exported ${count} relay(s) to ${target} WITH passwords included — keep this file private.`
+						: `Exported ${count} relay(s) to ${target} (passwords stripped — file is safe to share).`,
+					"info",
+				);
+			};
+
+			const runImport = async (
+				pathArg: string | undefined,
+				mode: "merge" | "replace",
+				dryRun: boolean,
+			) => {
+				const filePath = (pathArg || "").trim();
+				if (!filePath) {
+					ctx.ui.notify("Usage: /freeflow import <path> [--merge|--replace] [--dry-run] — path is required.", "warning");
+					return;
+				}
+				let byteSize = 0;
+				try {
+					const st = fs.statSync(filePath);
+					if (!st.isFile()) {
+						ctx.ui.notify(`Could not read relay file ${filePath}: not a regular file.`, "error");
+						return;
+					}
+					byteSize = st.size;
+				} catch (e) {
+					const code = e !== null && typeof e === "object" && "code" in e ? e.code : undefined;
+					if (code === "ENOENT") {
+						ctx.ui.notify(`Relay file not found: ${filePath} — check the path and try again.`, "warning");
+					} else {
+						ctx.ui.notify(`Could not read relay file ${filePath}: ${(e as Error).message}.`, "error");
+					}
+					return;
+				}
+				if (byteSize > EXPORT_MAX_BYTES) {
+					ctx.ui.notify(`Relay file ${filePath} is too large (${byteSize} bytes; limit ${EXPORT_MAX_BYTES} bytes). Nothing changed.`, "warning");
+					return;
+				}
+				let raw: string;
+				try {
+					raw = fs.readFileSync(filePath, "utf8");
+				} catch (e) {
+					ctx.ui.notify(`Could not read relay file ${filePath}: ${(e as Error).message}.`, "error");
+					return;
+				}
+				let fragment: Pick<RelayState, "mode" | "enabled" | "url" | "relays" | "hideWidget">;
+				let parseSkipped: Array<{ index: number; url: string; reason: string }> = [];
+				try {
+					const parsed = parseRelayImport(raw);
+					fragment = parsed.fragment;
+					parseSkipped = parsed.skipped;
+				} catch {
+					ctx.ui.notify(classifyImportFailure(filePath, raw), "warning");
+					return;
+				}
+				if (!fragment || !Array.isArray(fragment.relays) || fragment.relays.length === 0) {
+					if (parseSkipped.length > 0) {
+						ctx.ui.notify(`Relay file ${filePath} holds no usable relay addresses (${parseSkipped.length} skipped: ${parseSkipped[0].reason}). Nothing changed.`, "warning");
+					} else {
+						ctx.ui.notify(`Relay file ${filePath} holds no usable relay addresses (0 skipped). Nothing changed.`, "warning");
+					}
+					return;
+				}
+				const plan = planRelayImport(loadRelayState(), fragment, { mode });
+				const skipped = [...parseSkipped];
+				for (const s of plan.skipped) {
+					if (!skipped.some((x) => x.index === s.index && x.url === s.url)) skipped.push(s);
+				}
+				const skippedCount = skipped.length;
+				const reasons = skippedCount > 0
+					? skipped.map((s) => s.reason).filter((r, i, arr) => arr.indexOf(r) === i).join("; ")
+					: "none";
+				const plannedActive = plan.next.url
+					? `[${shortRelayLabel(plan.next.url, plan.next.relays)}]`
+					: "none";
+				if (dryRun) {
+					if (mode === "replace") {
+						ctx.ui.notify(`DRY RUN — replace from ${filePath}: would install ${plan.added}, would remove ${plan.removed}, would skip ${skippedCount} (${reasons}). Active relay would be ${plannedActive}. Nothing changed.`, "info");
+					} else {
+						ctx.ui.notify(`DRY RUN — merge from ${filePath}: would add ${plan.added}, would update short name on ${plan.updated}, would skip ${skippedCount} (${reasons}). Active and mode unchanged. Nothing changed.`, "info");
+					}
+					return;
+				}
+				if (mode === "replace") {
+					ctx.ui.notify(`Replace from ${filePath}: will install ${plan.added}, remove ${plan.removed}, skip ${skippedCount} (${reasons}). Active relay will be ${plannedActive}.`, "info");
+					if (typeof ctx.ui.confirm === "function") {
+						const ok = await ctx.ui.confirm(
+							"Replace all relays?",
+							`Install ${plan.added} relay(s) from ${filePath} and remove ${plan.removed} existing? This cannot be undone.`,
+						);
+						if (!ok) {
+							ctx.ui.notify("Replace cancelled — relay list unchanged.", "warning");
+							return;
+						}
+					}
+				}
+				applyRelayState((s) => planRelayImport(s, fragment, { mode }).next);
+				persist();
+				flash();
+				if (mode === "replace") {
+					const activeName = relayState.url
+						? `[${shortRelayLabel(relayState.url, relayState.relays)}]`
+						: "none";
+					ctx.ui.notify(`Replaced relay list from ${filePath}: installed ${plan.added}, skipped ${skippedCount}. Active relay is now ${activeName}.`, "info");
+				} else {
+					ctx.ui.notify(`Merge from ${filePath}: added ${plan.added}, updated short name on ${plan.updated}, skipped ${skippedCount}. Relay list now holds ${relayState.relays.length}.`, "info");
+				}
+				const withoutPassword = relayState.relays.filter((r) => !r.auth).length;
+				if (withoutPassword > 0) {
+					ctx.ui.notify(`${withoutPassword} relay(s) have no password — reconnect each one before use.`, "warning");
+				}
+				for (const s of skipped) {
+					const shown = s.url || `#${s.index + 1}`;
+					const reason = s.reason.endsWith(".") ? s.reason : `${s.reason}.`;
+					ctx.ui.notify(`Skipped ${shown}: ${reason}`, "warning");
+				}
+			};
 
 			if (sub === "auto") {
 				applyRelayState((s) => {
@@ -1102,6 +1287,47 @@ export function createCommandSpec(
 				} else {
 					ctx.ui.notify(`✗ ${shortRelayLabel(matched.url, relayState.relays)} failed: ${probe.error || `HTTP ${probe.status}`}`, "error");
 				}
+			} else if (sub === "export") {
+				const tokens = rest.trim() ? rest.trim().split(/\s+/) : [];
+				let target: string | undefined;
+				let includeSecrets = false;
+				for (const t of tokens) {
+					if (t === "--include-secrets") {
+						includeSecrets = true;
+					} else if (t.startsWith("--")) {
+						ctx.ui.notify(`Unknown flag ${t} — usage: /freeflow export [path] [--include-secrets].`, "warning");
+						return;
+					} else if (target === undefined) {
+						target = t;
+					}
+				}
+				await runExport(target, includeSecrets);
+			} else if (sub === "import") {
+				const tokens = rest.trim() ? rest.trim().split(/\s+/) : [];
+				let target: string | undefined;
+				let sawMerge = false;
+				let sawReplace = false;
+				let dryRun = false;
+				for (const t of tokens) {
+					if (t === "--merge") {
+						sawMerge = true;
+					} else if (t === "--replace") {
+						sawReplace = true;
+					} else if (t === "--dry-run") {
+						dryRun = true;
+					} else if (t.startsWith("--")) {
+						ctx.ui.notify(`Unknown flag ${t} — usage: /freeflow import <path> [--merge|--replace] [--dry-run].`, "warning");
+						return;
+					} else if (target === undefined) {
+						target = t;
+					}
+				}
+				if (sawMerge && sawReplace) {
+					ctx.ui.notify("Both --merge and --replace given — showing a merge preview. Nothing changed.", "info");
+					await runImport(target, "merge", true);
+					return;
+				}
+				await runImport(target, sawReplace ? "replace" : "merge", dryRun);
 			} else if (sub === "url") {
 				const input =
 					rest ||
@@ -1152,6 +1378,8 @@ export function createCommandSpec(
 					"Switch active relay…",
 					"Rename / Set relay short name…",
 					"Remove relay…",
+					"Share relays (export file)…",
+					"Load relays from file (import)…",
 					"List saved relays",
 					"Deploy Vercel relay…",
 					"Deploy Cloudflare relay…",
@@ -1170,6 +1398,12 @@ export function createCommandSpec(
 					await editRelayLabelMenu();
 				} else if (choice === "Remove relay…") {
 					await removeRelayMenu();
+				} else if (choice === "Share relays (export file)…") {
+					await runExport(undefined, false);
+				} else if (choice === "Load relays from file (import)…") {
+					const picked = (await ctx.ui.input("Relay file path:", EXPORT_DEFAULT_FILENAME))?.trim();
+					if (!picked) return;
+					await runImport(picked, "merge", false);
 				} else if (choice === "List saved relays") {
 					showList();
 				} else if (choice === "Deploy Vercel relay…") {

package/src/relay-state.ts

@@ -767,3 +767,367 @@ export function updateRelayStatusUi(targetUrl?: string): void {
 	const label = formatRelayStatusLabel(getActiveRelayState(), targetUrl);
 	activeStatusUi.setStatus("freeflow", label ?? undefined);
 }
+
+// ── Relay export/import codec (relay-pool portability) ─────────────────────
+// Pure in-memory codec for `/freeflow export` + `/freeflow import`. These
+// functions never touch disk, never prompt, and never validate the live pool:
+// the command layer parses 100% in memory, then commits via one CAS write.
+
+/** Envelope marker identifying a pi-freeflow relay export file. */
+export const EXPORT_KIND = "pi-freeflow/relay-export" as const;
+/** Current relay export file version. Bump on any envelope breaking change. */
+export const EXPORT_VERSION = 1;
+/** Default file name used by `/freeflow export` when no path is given. */
+export const EXPORT_DEFAULT_FILENAME = "freeflow-relays.json";
+/** Hard cap on accepted import file size (1 MiB). */
+export const EXPORT_MAX_BYTES = 1_048_576;
+
+/** A parsed relay export file envelope. */
+export interface RelayExportArtifact {
+	kind: "pi-freeflow/relay-export";
+	version: 1;
+	exportedAt: string;
+	state: {
+		mode?: RelayMode;
+		enabled: boolean;
+		url: string;
+		relays: KnownRelay[];
+		hideWidget?: boolean;
+	};
+}
+
+/** One import candidate entry that was skipped instead of aborting the file. */
+export interface RelayImportSkipped {
+	index: number;
+	url: string;
+	reason: string;
+}
+
+/** RelayState subset carried by an import file (pool scope only). */
+export type RelayImportFragment = Pick<
+	RelayState,
+	"mode" | "enabled" | "url" | "relays" | "hideWidget"
+>;
+
+/** Result of planning an import against the current pool. */
+export interface RelayImportPlanResult {
+	next: RelayState;
+	added: number;
+	updated: number;
+	removed: number;
+	skipped: RelayImportSkipped[];
+}
+
+/** Alias kept for the cross-slice contract name. */
+export type PlanResult = RelayImportPlanResult;
+
+/**
+ * Build an export artifact from live relay state. Passwords are stripped by
+ * default (the key is absent, not null); pass `{ includeSecrets: true }` to
+ * carry them verbatim.
+ */
+export function buildRelayExport(
+	state: RelayState,
+	opts?: { includeSecrets?: boolean },
+): RelayExportArtifact {
+	const includeSecrets = opts?.includeSecrets === true;
+	return {
+		kind: EXPORT_KIND,
+		version: EXPORT_VERSION,
+		exportedAt: new Date().toISOString(),
+		state: {
+			mode: state.mode,
+			enabled: state.enabled,
+			url: state.url,
+			relays: state.relays.map((r) => {
+				const out: KnownRelay = { url: r.url };
+				if (r.label !== undefined) out.label = r.label;
+				if (r.addedAt !== undefined) out.addedAt = r.addedAt;
+				if (
+					includeSecrets &&
+					typeof r.auth === "string" &&
+					r.auth.length > 0
+				) {
+					out.auth = r.auth;
+				}
+				return out;
+			}),
+			hideWidget: state.hideWidget,
+		},
+	};
+}
+
+/**
+ * Parse raw import file text into a relay fragment. Throws on envelope
+ * failure (oversize, bad JSON, wrong kind/version, missing pool); per-entry
+ * problems fail closed to `skipped` so one bad relay never wipes the pool.
+ */
+export function parseRelayImport(raw: string): {
+	fragment: RelayImportFragment;
+	skipped: RelayImportSkipped[];
+	warnings: string[];
+} {
+	if (raw.length > EXPORT_MAX_BYTES) {
+		throw new Error(
+			`Relay import file too large (${raw.length} bytes, limit ${EXPORT_MAX_BYTES})`,
+		);
+	}
+	let doc: unknown;
+	try {
+		doc = JSON.parse(raw);
+	} catch {
+		throw new Error("Relay import file is not valid JSON");
+	}
+	const envelope =
+		typeof doc === "object" && doc !== null
+			? (doc as Record<string, unknown>)
+			: null;
+	if (envelope?.kind !== EXPORT_KIND) {
+		throw new Error("File is not a relay export (bad kind marker)");
+	}
+	if (
+		typeof envelope.version !== "number" ||
+		!Number.isInteger(envelope.version) ||
+		envelope.version !== EXPORT_VERSION
+	) {
+		throw new Error(
+			`Unsupported relay export version (${String(envelope.version)}); this build reads version ${EXPORT_VERSION}`,
+		);
+	}
+	const rawState =
+		typeof envelope.state === "object" && envelope.state !== null
+			? (envelope.state as Record<string, unknown>)
+			: null;
+	if (!rawState || !Array.isArray(rawState.relays)) {
+		throw new Error("File is not a relay export (state pool is missing)");
+	}
+
+	const warnings: string[] = [];
+	const skipped: RelayImportSkipped[] = [];
+
+	const rawMode = rawState.mode;
+	const mode: RelayMode =
+		rawMode === "on" || rawMode === "off" || rawMode === "auto"
+			? rawMode
+			: "auto";
+	if (rawMode !== "on" && rawMode !== "off" && rawMode !== "auto") {
+		warnings.push("Unknown relay mode in file; using automatic mode.");
+	}
+
+	const rawEnabled = rawState.enabled;
+	const enabled =
+		typeof rawEnabled === "boolean"
+			? rawEnabled
+			: mode === "on"
+				? true
+				: mode === "off"
+					? false
+					: (rawState.relays as unknown[]).length > 0;
+
+	const rawUrl = rawState.url;
+	let url = "";
+	if (typeof rawUrl === "string" && rawUrl.trim()) {
+		const trimmed = rawUrl.trim();
+		if (validateRelayUrl(trimmed).ok) {
+			url = trimmed;
+		} else {
+			warnings.push("Active relay address in file is not usable; ignoring it.");
+		}
+	}
+
+	const hideWidget = rawState.hideWidget === true;
+	const relays: KnownRelay[] = [];
+	const seen = new Set<string>();
+	const entries = rawState.relays as unknown[];
+	for (let index = 0; index < entries.length; index++) {
+		const entry = entries[index];
+		if (typeof entry !== "object" || entry === null) {
+			skipped.push({ index, url: "", reason: "entry is not an object" });
+			continue;
+		}
+		const record = entry as Record<string, unknown>;
+		const trimmedUrl =
+			typeof record.url === "string" ? record.url.trim() : "";
+		if (!trimmedUrl) {
+			skipped.push({ index, url: "", reason: "missing relay address" });
+			continue;
+		}
+		const check = validateRelayUrl(trimmedUrl);
+		if (!check.ok) {
+			skipped.push({ index, url: trimmedUrl, reason: check.reason });
+			continue;
+		}
+		// Exact trimmed-address dedupe (first wins), mirroring ensureRelay.
+		if (seen.has(trimmedUrl)) {
+			skipped.push({ index, url: trimmedUrl, reason: "duplicate relay address" });
+			continue;
+		}
+		seen.add(trimmedUrl);
+		const candidate: KnownRelay = { url: trimmedUrl };
+		if (typeof record.label === "string") {
+			const cleanLabel = record.label.trim();
+			if (cleanLabel && cleanLabel !== "manual") {
+				if (cleanLabel.length > 64) {
+					candidate.label = cleanLabel.slice(0, 64);
+					warnings.push(
+						`Short name for ${trimmedUrl} truncated to 64 characters.`,
+					);
+				} else {
+					candidate.label = cleanLabel;
+				}
+			}
+		}
+		if (
+			typeof record.addedAt === "string" &&
+			Number.isNaN(Date.parse(record.addedAt)) === false
+		) {
+			candidate.addedAt = record.addedAt;
+		}
+		if (
+			typeof record.auth === "string" &&
+			record.auth.length > 0
+		) {
+			candidate.auth = record.auth;
+		} else if (record.auth !== undefined) {
+			warnings.push(`Password for ${trimmedUrl} is not usable; ignoring it.`);
+		}
+		relays.push(candidate);
+	}
+
+	return {
+		fragment: { mode, enabled, url, relays, hideWidget },
+		skipped,
+		warnings,
+	};
+}
+
+function copyRelayEntry(r: KnownRelay): KnownRelay {
+	const out: KnownRelay = { url: r.url };
+	if (r.label !== undefined) out.label = r.label;
+	if (r.addedAt !== undefined) out.addedAt = r.addedAt;
+	if (r.auth !== undefined) out.auth = r.auth;
+	return out;
+}
+
+/**
+ * Plan an import against the current pool without touching disk or prompting.
+ * Merge folds the file pool into the current one via ensureRelay semantics and
+ * keeps the current mode/switch/widget; replace installs the file pool fresh.
+ */
+export function planRelayImport(
+	current: RelayState,
+	fragment: RelayImportFragment,
+	opts: { mode: "merge" | "replace" },
+): RelayImportPlanResult {
+	if (opts.mode === "replace") {
+		const installed: KnownRelay[] = [];
+		const seen = new Set<string>();
+		const skipped: RelayImportSkipped[] = [];
+		const source = fragment.relays ?? [];
+		for (let index = 0; index < source.length; index++) {
+			const entry = source[index];
+			const trimmedUrl =
+				typeof entry?.url === "string" ? entry.url.trim() : "";
+			if (!trimmedUrl || !validateRelayUrl(trimmedUrl).ok) {
+				skipped.push({
+					index,
+					url: trimmedUrl,
+					reason: "relay address is not usable",
+				});
+				continue;
+			}
+			if (seen.has(trimmedUrl)) {
+				skipped.push({
+					index,
+					url: trimmedUrl,
+					reason: "duplicate relay address",
+				});
+				continue;
+			}
+			seen.add(trimmedUrl);
+			installed.push(copyRelayEntry({ ...entry, url: trimmedUrl }));
+		}
+		// Empty file pool installs nothing: fail closed here (not just in the
+		// command handler) so no caller can turn zero usable addresses into a wipe.
+		if (installed.length === 0) {
+			return {
+				next: { ...current, relays: current.relays.map(copyRelayEntry) },
+				added: 0,
+				updated: 0,
+				removed: 0,
+				skipped,
+			};
+		}
+		const installedUrls = new Set(installed.map((r) => r.url));
+		const active =
+			fragment.url && installedUrls.has(fragment.url)
+				? fragment.url
+				: (installed[0]?.url ?? "");
+		return {
+			next: {
+				mode: fragment.mode ?? "auto",
+				enabled: fragment.enabled,
+				url: active,
+				relays: installed,
+				hideWidget: fragment.hideWidget === true,
+			},
+			added: installed.length,
+			updated: 0,
+			removed: current.relays.length - installed.length,
+			skipped,
+		};
+	}
+
+	const next: RelayState = {
+		...current,
+		relays: current.relays.map(copyRelayEntry),
+	};
+	let added = 0;
+	let updated = 0;
+	const skipped: RelayImportSkipped[] = [];
+	const source = fragment.relays ?? [];
+	for (let index = 0; index < source.length; index++) {
+		const entry = source[index];
+		const trimmedUrl =
+			typeof entry?.url === "string" ? entry.url.trim() : "";
+		if (!trimmedUrl) {
+			skipped.push({ index, url: "", reason: "missing relay address" });
+			continue;
+		}
+		let relay: KnownRelay | undefined;
+		try {
+			const already = next.relays.some((r) => r.url === trimmedUrl);
+			relay = ensureRelay(next, trimmedUrl, entry.label);
+			if (already) {
+				updated += 1;
+			} else {
+				added += 1;
+			}
+		} catch (err) {
+			skipped.push({
+				index,
+				url: trimmedUrl,
+				reason: err instanceof Error ? err.message : "relay address rejected",
+			});
+			continue;
+		}
+		// File password overwrites; an absent file password keeps the stored one.
+		if (typeof entry.auth === "string" && entry.auth.length > 0) {
+			relay.auth = entry.auth;
+		}
+		if (
+			typeof entry.addedAt === "string" &&
+			Number.isNaN(Date.parse(entry.addedAt)) === false
+		) {
+			relay.addedAt = entry.addedAt;
+		}
+	}
+	const mergedUrls = new Set(next.relays.map((r) => r.url));
+	if (!mergedUrls.has(next.url)) {
+		next.url =
+			fragment.url && mergedUrls.has(fragment.url)
+				? fragment.url
+				: (next.relays[0]?.url ?? "");
+	}
+	return { next, added, updated, removed: 0, skipped };
+}