diff --git a/Cargo.lock b/Cargo.lock
index 914a1e0a4..e8824be77 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4257,6 +4257,7 @@ dependencies = [
  "puffer-observability",
  "puffer-provider-openai",
  "puffer-provider-registry",
+ "puffer-provider-worldrouter",
  "puffer-resources",
  "puffer-runner-api",
  "puffer-runner-grpc",
@@ -4566,12 +4567,27 @@ dependencies = [
  "reqwest",
  "serde",
  "serde_json",
+ "serde_yaml",
  "sha2 0.10.9",
  "tempfile",
  "toml",
  "uuid",
 ]
 
+[[package]]
+name = "puffer-provider-worldrouter"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "base64",
+ "rand 0.9.4",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "url",
+ "uuid",
+]
+
 [[package]]
 name = "puffer-resources"
 version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index d651127c9..fbc32cdf2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -15,6 +15,7 @@ members = [
     "crates/puffer-observability",
     "crates/puffer-provider-openai",
     "crates/puffer-provider-registry",
+    "crates/puffer-provider-worldrouter",
     "crates/puffer-resources",
     "crates/puffer-runner-api",
     "crates/puffer-runner-local",
diff --git a/apps/puffer-desktop/src-tauri/src/backend.rs b/apps/puffer-desktop/src-tauri/src/backend.rs
index a618a1504..b1b050120 100644
--- a/apps/puffer-desktop/src-tauri/src/backend.rs
+++ b/apps/puffer-desktop/src-tauri/src/backend.rs
@@ -42,10 +42,22 @@ pub(crate) struct BackendState {
     fs_watches: Arc<fs_watch::FsWatchRegistry>,
     browsers: browser::BrowserRegistry,
     turns: Mutex<HashMap<String, Arc<AtomicBool>>>,
+    /// Optional handle to the puffer daemon child so we can forward
+    /// catalog-style RPCs (live `/v1/models`, etc.) to the daemon that owns
+    /// the real ProviderRegistry. None during plain unit tests where no
+    /// daemon was spawned — those code paths fall back to the hardcoded
+    /// descriptors instead.
+    daemon_launcher: Option<Arc<crate::daemon_launcher::DaemonLauncher>>,
 }
 
 impl BackendState {
     pub(crate) fn new() -> Self {
+        Self::new_with_launcher(None)
+    }
+
+    pub(crate) fn new_with_launcher(
+        daemon_launcher: Option<Arc<crate::daemon_launcher::DaemonLauncher>>,
+    ) -> Self {
         let ptys = Arc::new(pty::PtyRegistry::new());
         ptys.spawn_idle_pruner();
         let browser_profile_root = app_home()
@@ -56,6 +68,7 @@ impl BackendState {
             fs_watches: Arc::new(fs_watch::FsWatchRegistry::new()),
             browsers: browser::BrowserRegistry::new(browser_profile_root),
             turns: Mutex::new(HashMap::new()),
+            daemon_launcher,
         }
     }
 
@@ -107,16 +120,50 @@ impl BackendState {
                 ))
             }
             "load_settings_snapshot" => serde_value(self.load_settings_snapshot()?),
-            "login_with_oauth" => serde_value(self.load_settings_snapshot()?),
+            "login_with_oauth" => {
+                let provider_id = string_param(&params, &["providerId", "provider_id"])?;
+                if provider_id == "worldrouter" {
+                    // Detach: OAuth blocks up to 120 s on the localhost
+                    // callback listener, which would freeze the GUI. The
+                    // event emitter lets the spawned reaper thread fire
+                    // `worldrouter:oauth-completed` so the GUI can swap
+                    // the spinner for the "Connected" affordance the
+                    // moment the puffer subprocess exits.
+                    self.run_puffer_cli_auth_subcommand(
+                        &["auth", "login", "worldrouter"],
+                        false,
+                        Some(events.clone()),
+                    )?;
+                }
+                // For other providers (puffer/codex/claude), the existing behavior was a
+                // no-op — keep it as such; native CLI integrations handle their own login.
+                serde_value(self.load_settings_snapshot()?)
+            }
             "login_with_api_key" => {
                 let provider_id = string_param(&params, &["providerId", "provider_id"])?;
                 let api_key = string_param(&params, &["apiKey", "api_key"])?;
-                self.store_api_key(&provider_id, &api_key)?;
+                if provider_id == "worldrouter" {
+                    self.run_puffer_cli_auth_subcommand(
+                        &["auth", "set-api-key", "worldrouter", &api_key],
+                        true,
+                        None,
+                    )?;
+                } else {
+                    self.store_api_key(&provider_id, &api_key)?;
+                }
                 serde_value(self.load_settings_snapshot()?)
             }
             "logout_provider" => {
                 let provider_id = string_param(&params, &["providerId", "provider_id"])?;
-                self.remove_api_key(&provider_id)?;
+                if provider_id == "worldrouter" {
+                    self.run_puffer_cli_auth_subcommand(
+                        &["auth", "clear", "worldrouter"],
+                        true,
+                        None,
+                    )?;
+                } else {
+                    self.remove_api_key(&provider_id)?;
+                }
                 serde_value(self.load_settings_snapshot()?)
             }
             "list_external_credentials" => serde_value(self.list_external_credentials()?),
@@ -197,9 +244,10 @@ impl BackendState {
             "add_mcp_server" => serde_value(json!({"servers": self.list_mcp_servers()?})),
             "list_provider_models" => {
                 let provider_id = string_param(&params, &["providerId", "provider_id"])?;
+                let models = self.resolve_provider_models(&provider_id);
                 serde_value(json!({
                     "providerId": provider_id,
-                    "models": self.provider_models(&provider_id),
+                    "models": models,
                 }))
             }
             "list_permissions" => serde_value(json!({
@@ -515,10 +563,48 @@ impl BackendState {
         })
     }
 
-    fn provider_models(&self, provider_id: &str) -> Vec<Value> {
+    /// Returns the model catalog for `provider_id`. For most providers this
+    /// is just the hardcoded list in the free-function `provider_models`,
+    /// but providers whose catalog is too large to hardcode (currently
+    /// worldrouter — the relay exposes ~66 models discovered via live
+    /// `/v1/models`) are forwarded to the running puffer daemon's
+    /// `list_provider_models` RPC, which holds the merged ProviderRegistry.
+    /// Falls back to the hardcoded seed if the daemon isn't running or the
+    /// call fails — better to show the two seed models than a spinner that
+    /// never resolves.
+    fn resolve_provider_models(&self, provider_id: &str) -> Vec<Value> {
+        let canonical = canonical_backend_provider_id(provider_id);
+        if canonical == "worldrouter" {
+            if let Some(models) = self.fetch_daemon_provider_models(&canonical) {
+                return models;
+            }
+        }
         provider_models(provider_id)
     }
 
+    fn fetch_daemon_provider_models(&self, provider_id: &str) -> Option<Vec<Value>> {
+        let launcher = self.daemon_launcher.as_ref()?;
+        let handshake = launcher.current_handshake()?;
+        match crate::daemon_launcher::query_daemon_rpc(
+            &handshake,
+            "list_provider_models",
+            json!({ "providerId": provider_id }),
+            std::time::Duration::from_secs(8),
+        ) {
+            Ok(result) => result
+                .get("models")
+                .and_then(Value::as_array)
+                .cloned(),
+            Err(error) => {
+                eprintln!(
+                    "corbina: daemon list_provider_models({provider_id}) failed: {error}; \
+                     falling back to descriptor seed"
+                );
+                None
+            }
+        }
+    }
+
     fn provider_auth_statuses(&self) -> Result<Vec<AuthProviderStatusDto>> {
         let credentials = self.load_credentials()?;
         let mut out = Vec::new();
@@ -562,6 +648,31 @@ impl BackendState {
                 });
             }
         }
+        // worldrouter lives in puffer-cli's AuthStore (~/.puffer/auth.json),
+        // not in corbina's own credentials file. Surface it so the GUI shows
+        // "Connected" after a successful `puffer auth login worldrouter`.
+        //
+        // We override `kind` to "oauth" when the stored key is an
+        // `sk-worldrouter-…` token (minted via the /auth/exchange flow),
+        // even though AuthStore tags it as `api_key`. This lets the
+        // LoginView hide the "Paste API key" affordance for OAuth users
+        // and only show "Disconnect".
+        if let Some(entry) = read_puffer_cli_credential("worldrouter") {
+            let surfaced_kind = if entry.oauth_derived {
+                "oauth".to_string()
+            } else {
+                entry.kind
+            };
+            out.push(AuthProviderStatusDto {
+                provider_id: "worldrouter".to_string(),
+                kind: surfaced_kind,
+                email: None,
+                expires_at_ms: None,
+                scopes: Vec::new(),
+                plan_type: Some(entry.summary),
+                organization_name: None,
+            });
+        }
         Ok(out)
     }
 
@@ -1020,6 +1131,110 @@ impl BackendState {
     fn save_sessions(&self, sessions: &[SessionRecord]) -> Result<()> {
         write_json(&sessions_file()?, sessions)
     }
+
+    /// Runs a `puffer auth …` subcommand using the same binary
+    /// `daemon_launcher::resolve_puffer_binary()` would spawn.
+    ///
+    /// `wait = true` blocks until the subcommand exits (with a 30 s
+    /// cap). Inherits stdio so the user sees output in the dev
+    /// terminal. Only safe for fast commands (`set-api-key`, `clear`).
+    ///
+    /// `wait = false` detaches: spawn, return immediately, and tail
+    /// the child's stdout in a background thread. When the child
+    /// prints a `https://…` URL on its own line (puffer's `Open this
+    /// URL in your browser:` block), corbina itself opens the URL via
+    /// macOS `open`. The CLI's own `open` invocation runs in a
+    /// non-GUI context (subprocess of a Tauri host) and on macOS that
+    /// path silently fails to route through LaunchServices; corbina
+    /// itself is a proper GUI app so its `open` call works.
+    ///
+    /// Required for `auth login`, which sits on a localhost listener
+    /// for up to 120 s waiting for the browser callback; blocking the
+    /// Tauri command handler that long freezes the GUI. When `events`
+    /// is supplied with `wait = false`, the reaper thread fires
+    /// `worldrouter:oauth-completed` once the child exits so the
+    /// frontend can clear its "Opening browser…" spinner without
+    /// having to poll `load_settings_snapshot`.
+    fn run_puffer_cli_auth_subcommand(
+        &self,
+        args: &[&str],
+        wait: bool,
+        events: Option<EventEmitter>,
+    ) -> Result<()> {
+        let binary = crate::daemon_launcher::resolve_puffer_binary()
+            .context("failed to resolve puffer binary for auth subcommand")?;
+        let stdio_stdout = if wait {
+            std::process::Stdio::inherit()
+        } else {
+            std::process::Stdio::piped()
+        };
+        let mut child = Command::new(&binary)
+            .args(args)
+            .stdin(std::process::Stdio::null())
+            .stdout(stdio_stdout)
+            .stderr(std::process::Stdio::inherit())
+            .spawn()
+            .with_context(|| format!("failed to spawn {} {:?}", binary.display(), args))?;
+        if !wait {
+            if let Some(stdout) = child.stdout.take() {
+                std::thread::spawn(move || tail_auth_subcommand_stdout(stdout));
+            }
+            // Reap the child in the background so we don't leave a
+            // zombie, and (when we have an emitter) fan out the exit
+            // status as a Tauri event so the GUI can react.
+            let args_label = args.join(" ");
+            std::thread::spawn(move || {
+                let outcome = child.wait();
+                if let Some(events) = events {
+                    let (success, error) = match outcome {
+                        Ok(status) if status.success() => (true, None),
+                        Ok(status) => (
+                            false,
+                            Some(format!("puffer {} exited with {}", args_label, status)),
+                        ),
+                        Err(err) => (
+                            false,
+                            Some(format!("wait failed for puffer {}: {}", args_label, err)),
+                        ),
+                    };
+                    events.emit(
+                        "worldrouter:oauth-completed",
+                        json!({"success": success, "error": error}),
+                    );
+                }
+            });
+            return Ok(());
+        }
+        let started = std::time::Instant::now();
+        let timeout = std::time::Duration::from_secs(30);
+        loop {
+            match child.try_wait() {
+                Ok(Some(status)) => {
+                    if !status.success() {
+                        anyhow::bail!("`puffer {}` exited with {}", args.join(" "), status);
+                    }
+                    return Ok(());
+                }
+                Ok(None) => {
+                    if started.elapsed() >= timeout {
+                        let _ = child.kill();
+                        anyhow::bail!(
+                            "`puffer {}` did not finish within {:?}",
+                            args.join(" "),
+                            timeout
+                        );
+                    }
+                    std::thread::sleep(std::time::Duration::from_millis(100));
+                }
+                Err(error) => {
+                    return Err(anyhow::Error::new(error).context(format!(
+                        "wait failed for `puffer {}`",
+                        args.join(" ")
+                    )));
+                }
+            }
+        }
+    }
 }
 
 fn ensure_session_cwd(cwd: &Path) -> Result<()> {
@@ -1036,6 +1251,34 @@ fn ensure_session_cwd(cwd: &Path) -> Result<()> {
         .with_context(|| format!("failed to create session cwd {}", cwd.display()))
 }
 
+/// Reads the detached `puffer auth login` child's stdout line by
+/// line and, when it sees a URL (puffer's `Open this URL in your
+/// browser:` block emits one `https://…` line followed by an empty
+/// line), opens that URL via macOS `open` from corbina's own
+/// process. Other stdout lines are forwarded to corbina's stderr so
+/// they remain visible in dev logs without contending with the
+/// detached child's own ttyless context.
+fn tail_auth_subcommand_stdout(stdout: std::process::ChildStdout) {
+    let reader = BufReader::new(stdout);
+    let mut opened = false;
+    for line in reader.lines().map_while(Result::ok) {
+        let trimmed = line.trim();
+        if !opened && trimmed.starts_with("https://") {
+            opened = true;
+            let target = trimmed.to_string();
+            eprintln!("[worldrouter oauth] opening browser at {target}");
+            match Command::new("open").arg(&target).spawn() {
+                Ok(_) => {}
+                Err(error) => {
+                    eprintln!("[worldrouter oauth] failed to launch `open`: {error}");
+                }
+            }
+            continue;
+        }
+        eprintln!("[worldrouter oauth] {line}");
+    }
+}
+
 fn run_agent_turn_thread(
     events: EventEmitter,
     browsers: browser::BrowserRegistry,
@@ -1458,6 +1701,20 @@ fn build_provider_command(
                 json_stream: false,
             })
         }
+        "worldrouter" => {
+            let command = ensure_provider_command("puffer")?;
+            Ok(ProviderLaunch {
+                label: "WorldRouter".to_string(),
+                command,
+                args: vec![
+                    "--no-alt-screen".to_string(),
+                    "--provider".to_string(),
+                    "worldrouter".to_string(),
+                    message.to_string(),
+                ],
+                json_stream: false,
+            })
+        }
         other => bail!("unknown provider `{other}`"),
     }
 }
@@ -2200,6 +2457,16 @@ fn provider_summaries() -> Vec<ProviderSummaryDto> {
             source_kind: "builtin".to_string(),
             source_path: None,
         },
+        ProviderSummaryDto {
+            id: "worldrouter".to_string(),
+            display_name: "WorldRouter".to_string(),
+            base_url: "https://inference-api.worldrouter.ai".to_string(),
+            default_api: "openai-completions".to_string(),
+            model_count: provider_models("worldrouter").len(),
+            auth_modes: vec!["oauth".to_string(), "api_key".to_string()],
+            source_kind: "builtin".to_string(),
+            source_path: None,
+        },
     ]
 }
 
@@ -2207,6 +2474,10 @@ fn provider_models(provider_id: &str) -> Vec<Value> {
     match canonical_backend_provider_id(provider_id).as_str() {
         "puffer" => vec![model("default", "Default", "puffer", false)],
         "claude" => claude_models(),
+        "worldrouter" => vec![
+            model("kimi-k2.6", "Kimi K2.6", "worldrouter", true),
+            model("qwen3.5-flash", "Qwen 3.5 Flash", "worldrouter", true),
+        ],
         _ => codex_app_server_models().unwrap_or_default(),
     }
 }
@@ -2355,6 +2626,7 @@ fn default_model_for(provider: &str) -> Option<String> {
     match canonical_backend_provider_id(provider).as_str() {
         "claude" => Some(DEFAULT_CLAUDE_MODEL.to_string()),
         "puffer" => Some(DEFAULT_PUFFER_MODEL.to_string()),
+        "worldrouter" => Some("kimi-k2.6".to_string()),
         _ => codex_app_server_catalog()
             .ok()
             .and_then(|catalog| catalog.default_model),
@@ -2363,7 +2635,7 @@ fn default_model_for(provider: &str) -> Option<String> {
 
 fn validate_provider_id(provider: &str) -> Result<()> {
     match canonical_backend_provider_id(provider).as_str() {
-        "puffer" | "codex" | "claude" => Ok(()),
+        "puffer" | "codex" | "claude" | "worldrouter" => Ok(()),
         other => bail!("unknown provider `{other}`"),
     }
 }
@@ -2374,6 +2646,7 @@ fn canonical_backend_provider_id(provider: &str) -> String {
         "openai" | "codex" => "codex".to_string(),
         "anthropic" | "claude" => "claude".to_string(),
         "puffer" => "puffer".to_string(),
+        "worldrouter" => "worldrouter".to_string(),
         _ => trimmed.to_string(),
     }
 }
@@ -2472,6 +2745,21 @@ fn provider_command(provider: &str) -> String {
             return trimmed.to_string();
         }
     }
+    // For `puffer`, prefer the sibling-aware resolver used by the auth
+    // subcommand path. Packaged corbina ships `puffer` alongside the Tauri
+    // host but typically without adding it to PATH; without this fallback,
+    // chat-turn spawns would error even though OAuth login (which goes
+    // through `resolve_puffer_binary` directly) works. Only use the resolver
+    // result when it points at an actually-existing file, otherwise fall
+    // through to the PATH-based default so the error message in
+    // `ensure_provider_command` stays informative.
+    if provider == "puffer" {
+        if let Ok(path) = crate::daemon_launcher::resolve_puffer_binary() {
+            if path.exists() {
+                return path.display().to_string();
+            }
+        }
+    }
     match provider {
         "claude" => "claude".to_string(),
         "puffer" => "puffer".to_string(),
@@ -2910,3 +3198,57 @@ enum ProcessLine {
     Stdout(String),
     Stderr(String),
 }
+
+struct PufferCliCredentialSummary {
+    /// Raw `kind` field from puffer-cli's AuthStore (`"api_key"` or
+    /// `"oauth"` today). Preserved verbatim for callers that want the
+    /// untouched on-disk value.
+    kind: String,
+    /// Human-friendly one-liner suitable for the GUI's plan-type slot.
+    summary: String,
+    /// True when the stored credential is an `sk-worldrouter-…` token
+    /// minted by the corbina OAuth exchange flow (worldrouter writes
+    /// these into the same `api_key` slot as a manually pasted key).
+    oauth_derived: bool,
+}
+
+fn read_puffer_cli_credential(provider_id: &str) -> Option<PufferCliCredentialSummary> {
+    let path = home_dir().join(".puffer/auth.json");
+    let raw = std::fs::read_to_string(&path).ok()?;
+    let parsed: serde_json::Value = serde_json::from_str(&raw).ok()?;
+    let provider = parsed.get("providers")?.get(provider_id)?;
+    let kind = provider.get("kind")?.as_str()?.to_string();
+    let mut oauth_derived = kind == "oauth";
+    let summary = match kind.as_str() {
+        "api_key" => {
+            let key = provider.get("key").and_then(|v| v.as_str()).unwrap_or("");
+            // worldrouter mints OAuth-exchanged tokens with the
+            // `sk-worldrouter-` prefix and persists them through the
+            // same `api_key` slot as manually pasted keys. Tagging them
+            // as OAuth lets the GUI render the right affordance.
+            if key.starts_with("sk-worldrouter-") {
+                oauth_derived = true;
+            }
+            let tail = key
+                .chars()
+                .rev()
+                .take(4)
+                .collect::<String>()
+                .chars()
+                .rev()
+                .collect::<String>();
+            if oauth_derived {
+                format!("oauth \u{2026}{}", tail)
+            } else {
+                format!("api_key \u{2026}{}", tail)
+            }
+        }
+        "oauth" => "oauth credential stored".to_string(),
+        other => other.to_string(),
+    };
+    Some(PufferCliCredentialSummary {
+        kind,
+        summary,
+        oauth_derived,
+    })
+}
diff --git a/apps/puffer-desktop/src-tauri/src/daemon_launcher.rs b/apps/puffer-desktop/src-tauri/src/daemon_launcher.rs
index 691064ab1..8a53387c3 100644
--- a/apps/puffer-desktop/src-tauri/src/daemon_launcher.rs
+++ b/apps/puffer-desktop/src-tauri/src/daemon_launcher.rs
@@ -6,14 +6,17 @@
 //! opens a local port-forward to the remote WebSocket so the frontend can
 //! continue to connect to `ws://127.0.0.1:<localport>/ws` transparently.
 
-use anyhow::{Context, Result};
+use anyhow::{anyhow, Context, Result};
 use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
 use std::io::{BufRead, BufReader};
 use std::net::{SocketAddr, TcpListener, TcpStream};
 use std::path::{Path, PathBuf};
 use std::process::{Child, Command, Stdio};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
+use tungstenite::{connect, Message};
+use url::Url;
 
 #[derive(Serialize, Deserialize, Debug, Clone)]
 #[serde(rename_all = "camelCase")]
@@ -83,6 +86,15 @@ impl DaemonLauncher {
         Self::default()
     }
 
+    /// Returns the handshake for the currently-running local daemon, if any.
+    /// Unlike `ensure_started`, this never spawns a new daemon — callers that
+    /// just want to talk to the existing daemon (e.g. forwarding a one-off
+    /// RPC) shouldn't trigger a fresh spawn as a side effect.
+    pub(crate) fn current_handshake(&self) -> Option<DaemonHandshake> {
+        let guard = self.child.lock().unwrap();
+        guard.as_ref().map(|child| child.handshake.clone())
+    }
+
     /// Returns the handshake for the local daemon, starting it if needed.
     #[allow(dead_code)]
     pub(crate) fn ensure_started(&self) -> Result<DaemonHandshake> {
@@ -220,6 +232,97 @@ check that sshd allows TCP forwarding and that the remote daemon really bound"
     }
 }
 
+/// Synchronously runs a single JSON-RPC round trip against the puffer
+/// daemon's WebSocket endpoint described by `handshake`. The daemon's wire
+/// protocol is one JSON object per text frame; we send a `{ id, method,
+/// params }` request and wait for the matching `{ id, ok, result | error }`
+/// response (event frames in between are skipped).
+///
+/// This is intentionally narrow: it's used by corbina to forward specific
+/// catalog-style lookups (e.g. worldrouter's live `/v1/models` list) to the
+/// daemon that already holds the live registry, without us having to
+/// re-implement discovery here. Anything more chatty should use the
+/// frontend's persistent DaemonClient instead.
+pub(crate) fn query_daemon_rpc(
+    handshake: &DaemonHandshake,
+    method: &str,
+    params: Value,
+    timeout: Duration,
+) -> Result<Value> {
+    // Bolt the auth token onto the URL the way the frontend client does
+    // (`?token=…`). Without this the daemon returns 401 on upgrade.
+    let mut url = Url::parse(&handshake.url).context("parsing daemon handshake URL")?;
+    if !handshake.token.is_empty() {
+        let has_token = url
+            .query_pairs()
+            .any(|(name, _)| name == "token");
+        if !has_token {
+            url.query_pairs_mut().append_pair("token", &handshake.token);
+        }
+    }
+
+    let (mut socket, _response) =
+        connect(url.as_str()).with_context(|| format!("connecting to daemon at {}", handshake.url))?;
+
+    // Constrain the underlying TCP socket so a hung daemon can't lock the
+    // model picker forever. tungstenite::connect returns a MaybeTlsStream
+    // wrapping the raw stream — best-effort apply read/write timeouts.
+    if let tungstenite::stream::MaybeTlsStream::Plain(stream) = socket.get_ref() {
+        let _ = stream.set_read_timeout(Some(timeout));
+        let _ = stream.set_write_timeout(Some(timeout));
+    }
+
+    let id = uuid::Uuid::new_v4().to_string();
+    let request = json!({
+        "id": id,
+        "method": method,
+        "params": params,
+    });
+    socket
+        .send(Message::Text(request.to_string()))
+        .with_context(|| format!("sending {method} to daemon"))?;
+
+    let deadline = Instant::now() + timeout;
+    loop {
+        if Instant::now() >= deadline {
+            let _ = socket.close(None);
+            return Err(anyhow!("daemon {method} timed out after {:?}", timeout));
+        }
+        let message = socket
+            .read()
+            .with_context(|| format!("reading daemon response for {method}"))?;
+        let text = match message {
+            Message::Text(text) => text,
+            // Pings/Pongs/Binary aren't part of our request/response protocol —
+            // just keep reading until we see our text reply.
+            Message::Ping(payload) => {
+                let _ = socket.send(Message::Pong(payload));
+                continue;
+            }
+            Message::Pong(_) | Message::Binary(_) | Message::Frame(_) => continue,
+            Message::Close(_) => {
+                return Err(anyhow!("daemon closed the WebSocket before responding"))
+            }
+        };
+        let value: Value = serde_json::from_str(&text)
+            .with_context(|| format!("parsing daemon response: {text}"))?;
+        // Server-pushed events have an `event` field and no `id`; skip them.
+        let response_id = value.get("id").and_then(Value::as_str);
+        if response_id != Some(id.as_str()) {
+            continue;
+        }
+        let _ = socket.close(None);
+        if value.get("ok").and_then(Value::as_bool) == Some(false) {
+            let err = value
+                .get("error")
+                .map(|e| e.to_string())
+                .unwrap_or_else(|| "(no error message)".to_string());
+            return Err(anyhow!("daemon {method} failed: {err}"));
+        }
+        return Ok(value.get("result").cloned().unwrap_or(Value::Null));
+    }
+}
+
 // try_wait returns Result<Option<ExitStatus>> — a thin wrapper that ignores
 // ECHILD on platforms where the subprocess has already been reaped.
 #[allow(dead_code)]
@@ -465,7 +568,7 @@ fn shell_quote(s: &str) -> String {
 /// sibling `puffer` binary next to the Tauri process (i.e. `cargo run`'s
 /// target directory); in release builds we fall back to the first `puffer`
 /// on `PATH`.
-fn resolve_puffer_binary() -> Result<PathBuf> {
+pub(crate) fn resolve_puffer_binary() -> Result<PathBuf> {
     let bin_name = if cfg!(windows) { "puffer.exe" } else { "puffer" };
     if let Ok(explicit) = std::env::var("PUFFER_BINARY") {
         let path = PathBuf::from(explicit);
diff --git a/apps/puffer-desktop/src-tauri/src/lib.rs b/apps/puffer-desktop/src-tauri/src/lib.rs
index 2a1d53b27..48384074b 100644
--- a/apps/puffer-desktop/src-tauri/src/lib.rs
+++ b/apps/puffer-desktop/src-tauri/src/lib.rs
@@ -382,8 +382,11 @@ fn cancel_turn(
 }
 
 pub fn run() {
-    let backend = Arc::new(BackendState::new());
     let launcher = Arc::new(DaemonLauncher::new());
+    // Give the backend a handle to the launcher so it can forward
+    // catalog-style RPCs (e.g. worldrouter's live `/v1/models` list) to
+    // the daemon that already holds the merged provider registry.
+    let backend = Arc::new(BackendState::new_with_launcher(Some(launcher.clone())));
     websocket::start_backend_ws(backend.clone());
 
     Builder::default()
diff --git a/apps/puffer-desktop/src/App.svelte b/apps/puffer-desktop/src/App.svelte
index 83670e43c..2d34ea423 100644
--- a/apps/puffer-desktop/src/App.svelte
+++ b/apps/puffer-desktop/src/App.svelte
@@ -3,6 +3,7 @@
 
   import TitleBar from "./lib/shell/TitleBar.svelte";
   import Sidebar, { type ActiveAgent, type UserChip } from "./lib/shell/Sidebar.svelte";
+  import { isTauri } from "./lib/shell/platform";
   import {
     applyTweaksToDocument,
     defaultTweaks,
@@ -185,6 +186,7 @@
   let turnQuestionLookup = $state<Record<string, { turnId: string; requestId: string }>>({});
   let replayTextByTurn: Record<string, string> = {};
   let sessionEventUnlisten: UnlistenFn | null = null;
+  let worldrouterOauthUnsubscribe: (() => void) | null = null;
   let subscribedSessionId: string | null = null;
   let sessionSubscriptionGeneration = 0;
   let liveSidebarSessionEventUnlisteners: Record<string, UnlistenFn> = {};
@@ -1044,6 +1046,10 @@
       window.removeEventListener("blur", armRecapBlurTimer);
       window.removeEventListener("focus", cancelRecapBlurTimer);
       window.removeEventListener("keydown", handleShellKeydown, true);
+      if (worldrouterOauthUnsubscribe) {
+        worldrouterOauthUnsubscribe();
+        worldrouterOauthUnsubscribe = null;
+      }
     };
   });
 
@@ -1067,6 +1073,18 @@
     void ensureLocalDaemonClient()
       .then((client) => {
         attachDaemonClient(client);
+        // Fired by the Rust reaper thread when `puffer auth login
+        // worldrouter` exits. The handler that kicked off the flow
+        // (`handleOauthLogin`) keeps `authBusyProviderId` set so the
+        // GUI shows "Waiting for browser login…" until this event
+        // arrives.
+        if (worldrouterOauthUnsubscribe) worldrouterOauthUnsubscribe();
+        worldrouterOauthUnsubscribe = client.on<{ success?: boolean; error?: string | null }>(
+          "worldrouter:oauth-completed",
+          (payload) => {
+            void handleWorldrouterOauthCompleted(payload);
+          }
+        );
       })
       .catch(() => {
         /* connection may be unavailable (web preview); stay idle */
@@ -1171,6 +1189,16 @@
     authBusyProviderId = providerId;
     authError = null;
     try {
+      if (providerId === "worldrouter" && isTauri()) {
+        // Tauri: the host returns immediately after spawning the
+        // detached `puffer auth login worldrouter` subprocess and emits
+        // `worldrouter:oauth-completed` when the child exits.
+        statusMessage = "Opening browser — finish the login to continue.";
+        await loginWithOauth(providerId, remoteConnection);
+        // Intentionally leave `authBusyProviderId` set; the event
+        // handler will clear it.
+        return;
+      }
       settingsSnapshot = await loginWithOauth(providerId, remoteConnection);
       onboardingCompleted = hasAvailableAgentProvider(settingsSnapshot);
       onboarding = shouldShowOnboarding(settingsSnapshot);
@@ -1182,8 +1210,49 @@
     } catch (error) {
       authError = String(error);
       statusMessage = authError;
+      if (providerId === "worldrouter" && isTauri()) {
+        authBusyProviderId = null;
+      }
     } finally {
-      authBusyProviderId = null;
+      if (!(providerId === "worldrouter" && isTauri())) {
+        authBusyProviderId = null;
+      }
+    }
+  }
+
+  async function handleWorldrouterOauthCompleted(payload: {
+    success?: boolean;
+    error?: string | null;
+  }) {
+    try {
+      if (payload?.success) {
+        statusMessage = "WorldRouter connected.";
+        await refreshSnapshot();
+        if ((settingsSnapshot?.auth?.length ?? 0) > 0) {
+          onboarding = false;
+        }
+        await refreshGroups();
+      } else {
+        const reason = payload?.error?.trim();
+        authError = reason && reason.length > 0
+          ? reason
+          : "WorldRouter login failed. Please try again.";
+        statusMessage = authError;
+      }
+    } finally {
+      // The OAuth flow has reached a terminal state regardless of
+      // success — clear the spinner so the user can retry.
+      if (authBusyProviderId === "worldrouter") {
+        authBusyProviderId = null;
+      }
+    }
+  }
+
+  async function refreshSnapshot() {
+    try {
+      settingsSnapshot = await loadSettingsSnapshot(remoteConnection);
+    } catch (error) {
+      statusMessage = `Failed to refresh settings: ${error}`;
     }
   }
 
diff --git a/apps/puffer-desktop/src/lib/api/daemonClient.ts b/apps/puffer-desktop/src/lib/api/daemonClient.ts
index c5c847b9c..18d05d480 100644
--- a/apps/puffer-desktop/src/lib/api/daemonClient.ts
+++ b/apps/puffer-desktop/src/lib/api/daemonClient.ts
@@ -152,39 +152,50 @@ export class DaemonClient {
   }
 
   on<T = unknown>(event: string, handler: (payload: T) => void): () => void {
+    const cleanups: (() => void)[] = [];
+
     if (this.useWebSocket) {
       const wrapped = handler as (payload: unknown) => void;
       const listeners = this.eventListeners.get(event) ?? new Set();
       listeners.add(wrapped);
       this.eventListeners.set(event, listeners);
       void this.connect().catch(() => {});
-      return () => {
+      cleanups.push(() => {
         listeners.delete(wrapped);
         if (listeners.size === 0) this.eventListeners.delete(event);
-      };
+      });
     }
 
-    let active = true;
-    let unlisten: UnlistenFn | null = null;
-    const pending = listen<BackendEventEnvelope>("corbina:event", (nativeEvent) => {
-      if (!active) return;
-      const payload = nativeEvent.payload;
-      if (payload?.event === event) {
-        handler(payload.payload as T);
-      }
-    });
-    void pending.then((next) => {
-      unlisten = next;
-      if (!active) unlisten();
-    });
+    // Tauri host events (e.g. corbina-emitted `worldrouter:oauth-completed`)
+    // arrive on the `corbina:event` channel and never traverse the daemon's
+    // WebSocket. Subscribe regardless of `useWebSocket` so Tauri-only events
+    // still reach handlers when the daemon happens to be a ws:// endpoint.
+    if (canInvokeTauri()) {
+      let active = true;
+      let unlisten: UnlistenFn | null = null;
+      const pending = listen<BackendEventEnvelope>("corbina:event", (nativeEvent) => {
+        if (!active) return;
+        const payload = nativeEvent.payload;
+        if (payload?.event === event) {
+          handler(payload.payload as T);
+        }
+      });
+      void pending.then((next) => {
+        unlisten = next;
+        if (!active) unlisten();
+      });
+      cleanups.push(() => {
+        active = false;
+        if (unlisten) {
+          unlisten();
+        } else {
+          void pending.then((next) => next());
+        }
+      });
+    }
 
     return () => {
-      active = false;
-      if (unlisten) {
-        unlisten();
-      } else {
-        void pending.then((next) => next());
-      }
+      for (const cleanup of cleanups) cleanup();
     };
   }
 
diff --git a/apps/puffer-desktop/src/lib/components/LoginView.svelte b/apps/puffer-desktop/src/lib/components/LoginView.svelte
index a304b90cf..1e1960e46 100644
--- a/apps/puffer-desktop/src/lib/components/LoginView.svelte
+++ b/apps/puffer-desktop/src/lib/components/LoginView.svelte
@@ -21,6 +21,7 @@
   export let onLoginOauth: (providerId: string) => void = () => {};
   export let onLoginApiKey: (providerId: string, apiKey: string) => void = () => {};
   export let onImportExternal: (providerId: string, source: "claude" | "codex") => void = () => {};
+  export let onLogout: (providerId: string) => void = () => {};
   export let onRefresh: () => void = () => {};
 
   let apiKeys: Record<string, string> = {};
@@ -47,6 +48,11 @@
     onLoginOauth(providerId);
   }
 
+  function submitLogout(providerId: string) {
+    if (busyProviderId) return;
+    onLogout(providerId);
+  }
+
   function supports(provider: ProviderSummary, mode: string): boolean {
     return provider.authModes.includes(mode);
   }
@@ -206,6 +212,8 @@
         {@const candidates = importsByProvider[provider.id] ?? []}
         {@const auth = authForProvider(provider.id)}
         {@const authFree = providerRunsWithoutAuth(provider)}
+        {@const isBusy = busyProviderId === provider.id}
+        {@const pendingKey = (apiKeys[provider.id] ?? "").trim()}
         <article class="provider-card" style="--provider-accent: {visual.accent};">
           <header class="card-head">
             <span class="logo" aria-hidden="true">
@@ -244,11 +252,16 @@
             {#if supports(provider, "oauth")}
               <button
                 class="oauth-btn"
-                disabled={credentialBusy}
+                disabled={credentialBusy || pendingKey.length > 0}
                 on:click={() => submitOauth(provider.id)}
+                title={pendingKey.length > 0
+                  ? "Clear the API key field to use OAuth"
+                  : undefined}
               >
-                {busyProviderId === provider.id
-                  ? "Opening browser…"
+                {isBusy
+                  ? provider.id === "worldrouter"
+                    ? "Waiting for browser login…"
+                    : "Opening browser…"
                   : auth
                     ? remoteEnabled
                       ? "Reconnect with OAuth (remote)"
@@ -275,13 +288,23 @@
                 />
                 <button
                   class="apikey-btn"
-                  disabled={credentialBusy || !(apiKeys[provider.id] ?? "").trim()}
+                  disabled={credentialBusy || pendingKey.length === 0}
                   on:click={() => submitApiKey(provider.id)}
                 >
                   {auth ? "Update key" : "Connect"}
                 </button>
               </div>
             {/if}
+
+            {#if auth}
+              <button
+                class="logout-btn"
+                disabled={isBusy}
+                on:click={() => submitLogout(provider.id)}
+              >
+                {isBusy ? "Disconnecting…" : "Disconnect"}
+              </button>
+            {/if}
           </div>
 
           <p class="hint">
@@ -459,6 +482,26 @@
     align-items: center;
     gap: 0.7rem;
   }
+  .logout-btn {
+    border: 1px solid rgba(111, 101, 89, 0.22);
+    border-radius: 10px;
+    padding: 0.5rem 0.85rem;
+    background: rgba(255, 255, 255, 0.92);
+    color: var(--text);
+    font: inherit;
+    font-weight: 500;
+    cursor: pointer;
+    justify-self: start;
+  }
+  .logout-btn:hover:not(:disabled) {
+    background: rgba(247, 225, 220, 0.45);
+    border-color: rgba(157, 58, 43, 0.3);
+    color: var(--danger, #9d3a2b);
+  }
+  .logout-btn:disabled {
+    opacity: 0.6;
+    cursor: progress;
+  }
   .logo {
     width: 36px;
     height: 36px;
@@ -590,6 +633,10 @@
     outline-offset: 1px;
     border-color: var(--provider-accent);
   }
+  .api-key-row input:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
 
   .hint {
     margin: 0;
diff --git a/apps/puffer-desktop/src/lib/providerIds.ts b/apps/puffer-desktop/src/lib/providerIds.ts
index 6a636e791..817687697 100644
--- a/apps/puffer-desktop/src/lib/providerIds.ts
+++ b/apps/puffer-desktop/src/lib/providerIds.ts
@@ -6,7 +6,7 @@ export function canonicalDaemonProviderId(providerId: string): string {
   return providerId;
 }
 
-const BUILTIN_AGENT_PROVIDER_IDS = new Set(["openai", "anthropic", "puffer"]);
+const BUILTIN_AGENT_PROVIDER_IDS = new Set(["openai", "anthropic", "puffer", "worldrouter"]);
 const NON_AGENT_PROVIDER_IDS = new Set(["github"]);
 const NON_AGENT_APIS = new Set(["", "oauth", "none", "disabled"]);
 
diff --git a/apps/puffer-desktop/src/lib/providerVisuals.ts b/apps/puffer-desktop/src/lib/providerVisuals.ts
index b999603be..e72ef8326 100644
--- a/apps/puffer-desktop/src/lib/providerVisuals.ts
+++ b/apps/puffer-desktop/src/lib/providerVisuals.ts
@@ -23,6 +23,7 @@ const PROVIDER_ACCENTS: Record<string, string> = {
   openrouter: "#06b6d4",
   "vercel-ai-gateway": "#0f172a",
   vllm: "#16a34a",
+  worldrouter: "#1f6feb",
   xai: "#0f172a"
 };
 
@@ -42,6 +43,7 @@ const PROVIDER_ICONS: Record<string, string> = {
   openrouter: "llm",
   "vercel-ai-gateway": "vercel",
   vllm: "llm",
+  worldrouter: "ai",
   xai: "ai"
 };
 
diff --git a/apps/puffer-desktop/src/lib/screens/Settings.svelte b/apps/puffer-desktop/src/lib/screens/Settings.svelte
index d5a69ff64..d6b4a96d7 100644
--- a/apps/puffer-desktop/src/lib/screens/Settings.svelte
+++ b/apps/puffer-desktop/src/lib/screens/Settings.svelte
@@ -694,6 +694,7 @@
         onLoginOauth={props.onLoginOauth ?? (() => {})}
         onLoginApiKey={props.onApiKeyLogin ?? (() => {})}
         onImportExternal={props.onImportExternal ?? (() => {})}
+        onLogout={props.onLogout}
         onRefresh={props.onRefresh}
       />
 
diff --git a/apps/puffer-desktop/src/lib/screens/workspace/NewSessionModal.svelte b/apps/puffer-desktop/src/lib/screens/workspace/NewSessionModal.svelte
index cb362de3a..ffb7e84a4 100644
--- a/apps/puffer-desktop/src/lib/screens/workspace/NewSessionModal.svelte
+++ b/apps/puffer-desktop/src/lib/screens/workspace/NewSessionModal.svelte
@@ -52,6 +52,7 @@
     if (provider.id === "codex" || provider.id === "openai") return "OpenAI Codex CLI";
     if (provider.id === "claude" || provider.id === "anthropic") return "Claude Code CLI";
     if (provider.id === "puffer") return "Puffer CLI";
+    if (provider.id === "worldrouter") return "WorldRouter inference";
     return provider.defaultApi ? `${provider.defaultApi} provider` : "Model provider";
   }
 
diff --git a/apps/puffer-desktop/tests/worldrouter-ui.spec.ts b/apps/puffer-desktop/tests/worldrouter-ui.spec.ts
new file mode 100644
index 000000000..570a56d9a
--- /dev/null
+++ b/apps/puffer-desktop/tests/worldrouter-ui.spec.ts
@@ -0,0 +1,173 @@
+import { expect, test } from "@playwright/test";
+import { FakeDaemon } from "./support/fakeDaemon";
+
+const WORLDROUTER_PROVIDER = {
+  id: "worldrouter",
+  displayName: "WorldRouter",
+  baseUrl: "https://inference-api.worldrouter.ai",
+  defaultApi: "openai-completions",
+  modelCount: 2,
+  authModes: ["api_key", "oauth"],
+  sourceKind: "builtin",
+  sourcePath: "resources/providers/worldrouter.yaml"
+};
+
+const BUILTIN_PROVIDERS = [
+  {
+    id: "openai",
+    displayName: "OpenAI",
+    baseUrl: "https://api.openai.com",
+    defaultApi: "openai-responses",
+    modelCount: 1,
+    authModes: ["oauth", "api_key"],
+    sourceKind: "builtin",
+    sourcePath: "resources/providers/openai.yaml"
+  },
+  {
+    id: "anthropic",
+    displayName: "Anthropic",
+    baseUrl: "https://api.anthropic.com",
+    defaultApi: "anthropic-messages",
+    modelCount: 1,
+    authModes: ["api_key"],
+    sourceKind: "builtin",
+    sourcePath: "resources/providers/anthropic.yaml"
+  },
+  {
+    id: "puffer",
+    displayName: "Puffer",
+    baseUrl: "local-cli://puffer",
+    defaultApi: "cli",
+    modelCount: 1,
+    authModes: ["native", "api_key"],
+    sourceKind: "builtin",
+    sourcePath: "resources/providers/puffer.yaml"
+  },
+  WORLDROUTER_PROVIDER
+];
+
+test("settings provider page shows WorldRouter card with both auth modes", async ({ page }) => {
+  const daemon = new FakeDaemon({
+    auth: [],
+    providers: [WORLDROUTER_PROVIDER]
+  });
+  await daemon.install(page);
+  await daemon.open(page, { allowUnauthenticatedWorkspace: true });
+
+  await page.getByRole("button", { name: "Settings" }).click();
+  await page.getByRole("button", { name: "Providers" }).click();
+
+  const card = page.locator(".provider-card").filter({ hasText: "WorldRouter" });
+  await expect(card).toBeVisible();
+  await expect(card.getByRole("heading", { name: "WorldRouter" })).toBeVisible();
+
+  // Both auth modes should be offered (OAuth button + API key input).
+  await expect(card.getByRole("button", { name: "Connect with OAuth" })).toBeVisible();
+  await expect(card.getByLabel("API key for WorldRouter")).toBeVisible();
+});
+
+test("new agent modal lists WorldRouter alongside the other builtin providers", async ({ page }) => {
+  const daemon = new FakeDaemon({
+    auth: [
+      {
+        providerId: "openai",
+        kind: "oauth",
+        email: "tester@example.com",
+        expiresAtMs: null,
+        scopes: [],
+        planType: "test",
+        organizationName: null
+      },
+      {
+        providerId: "anthropic",
+        kind: "api_key",
+        email: null,
+        expiresAtMs: null,
+        scopes: [],
+        planType: null,
+        organizationName: null
+      },
+      {
+        providerId: "worldrouter",
+        kind: "oauth",
+        email: null,
+        expiresAtMs: null,
+        scopes: [],
+        planType: "WorldRouter OAuth",
+        organizationName: null
+      }
+    ],
+    providers: BUILTIN_PROVIDERS
+  });
+  await daemon.install(page);
+  await daemon.open(page);
+
+  await page.getByRole("button", { name: /^New agent in / }).first().click();
+  const dialog = page.getByRole("dialog", { name: "New agent" });
+  await expect(dialog).toBeVisible();
+
+  const radioGroup = dialog.locator(".pf-provider-choice");
+  await expect(radioGroup.getByRole("radio", { name: /OpenAI/ })).toBeVisible();
+  await expect(radioGroup.getByRole("radio", { name: /Anthropic/ })).toBeVisible();
+  await expect(radioGroup.getByRole("radio", { name: /Puffer/ })).toBeVisible();
+  await expect(radioGroup.getByRole("radio", { name: /WorldRouter/ })).toBeVisible();
+  await expect(radioGroup.locator('input[type="radio"]')).toHaveCount(4);
+
+  const worldrouterLabel = radioGroup.locator("label").filter({ hasText: "WorldRouter" });
+  await expect(worldrouterLabel.locator(".meta")).toHaveText("WorldRouter inference");
+});
+
+test("selecting WorldRouter in the new agent modal toggles the radio without error", async ({ page }) => {
+  const daemon = new FakeDaemon({
+    auth: [
+      {
+        providerId: "openai",
+        kind: "oauth",
+        email: "tester@example.com",
+        expiresAtMs: null,
+        scopes: [],
+        planType: "test",
+        organizationName: null
+      },
+      {
+        providerId: "anthropic",
+        kind: "api_key",
+        email: null,
+        expiresAtMs: null,
+        scopes: [],
+        planType: null,
+        organizationName: null
+      },
+      {
+        providerId: "worldrouter",
+        kind: "oauth",
+        email: null,
+        expiresAtMs: null,
+        scopes: [],
+        planType: "WorldRouter OAuth",
+        organizationName: null
+      }
+    ],
+    providers: BUILTIN_PROVIDERS
+  });
+  await daemon.install(page);
+  await daemon.open(page);
+
+  await page.getByRole("button", { name: /^New agent in / }).first().click();
+  const dialog = page.getByRole("dialog", { name: "New agent" });
+  await expect(dialog).toBeVisible();
+
+  const radioGroup = dialog.locator(".pf-provider-choice");
+  const worldrouterLabel = radioGroup.locator("label").filter({ hasText: "WorldRouter" });
+  const worldrouterRadio = worldrouterLabel.locator('input[type="radio"]');
+
+  await worldrouterLabel.click();
+
+  await expect(worldrouterRadio).toBeChecked();
+  await expect(worldrouterLabel).toHaveAttribute("data-active", "true");
+
+  // No error banner should be raised by simply picking the provider.
+  await expect(dialog.getByRole("alert")).toHaveCount(0);
+  // Start agent should still be enabled (we don't click it: would spawn real session).
+  await expect(dialog.getByRole("button", { name: "Start agent" })).toBeEnabled();
+});
diff --git a/crates/puffer-cli/Cargo.toml b/crates/puffer-cli/Cargo.toml
index 23a0c87ef..7bda0fd45 100644
--- a/crates/puffer-cli/Cargo.toml
+++ b/crates/puffer-cli/Cargo.toml
@@ -24,6 +24,7 @@ puffer-core = { path = "../puffer-core" }
 puffer-mcp-oauth = { path = "../puffer-mcp-oauth" }
 puffer-observability = { path = "../puffer-observability" }
 puffer-provider-openai = { path = "../puffer-provider-openai" }
+puffer-provider-worldrouter = { path = "../puffer-provider-worldrouter" }
 puffer-provider-registry = { path = "../puffer-provider-registry" }
 puffer-resources = { path = "../puffer-resources" }
 puffer-runner-api = { path = "../puffer-runner-api" }
diff --git a/crates/puffer-cli/src/auth_credentials.rs b/crates/puffer-cli/src/auth_credentials.rs
index 1f97756fb..7be5bbdc4 100644
--- a/crates/puffer-cli/src/auth_credentials.rs
+++ b/crates/puffer-cli/src/auth_credentials.rs
@@ -118,6 +118,32 @@ pub(crate) fn store_ready_credential_from_anthropic(
     }
 }
 
+/// Converts worldrouter OAuth credentials into the registry storage shape.
+/// The Auth Station `sub` claim is stored as `account_id` so the
+/// existing AuthStore reuse path (organization_id, plan_type, etc.)
+/// stays untouched. `name` is intentionally not persisted yet — the
+/// existing `OAuthCredential` shape has no slot for it; if the UI
+/// needs the display name later, we can either reuse `email` or
+/// extend the struct.
+pub(crate) fn to_registry_oauth_credential_worldrouter(
+    credential: puffer_provider_worldrouter::WorldRouterOAuthCredentials,
+) -> puffer_provider_registry::OAuthCredential {
+    puffer_provider_registry::OAuthCredential {
+        access_token: credential.access_token,
+        refresh_token: credential.refresh_token,
+        expires_at_ms: credential.expires_at_ms,
+        account_id: credential.sub,
+        organization_id: None,
+        email: credential.email,
+        plan_type: None,
+        rate_limit_tier: None,
+        scopes: Vec::new(),
+        organization_name: None,
+        organization_role: None,
+        workspace_role: None,
+    }
+}
+
 /// Writes a resolved stored credential into the auth store.
 pub(crate) fn set_stored_credential(
     auth_store: &mut AuthStore,
@@ -129,3 +155,27 @@ pub(crate) fn set_stored_credential(
         StoredCredential::OAuth(credential) => auth_store.set_oauth(provider, credential),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use puffer_provider_worldrouter::WorldRouterOAuthCredentials;
+
+    #[test]
+    fn worldrouter_credential_maps_email_and_account_id() {
+        let credential = WorldRouterOAuthCredentials {
+            access_token: "acc".to_string(),
+            refresh_token: "ref".to_string(),
+            expires_at_ms: 42,
+            sub: Some("user_01".to_string()),
+            email: Some("dev@example.com".to_string()),
+            name: Some("Dev".to_string()),
+        };
+        let stored = to_registry_oauth_credential_worldrouter(credential);
+        assert_eq!(stored.access_token, "acc");
+        assert_eq!(stored.refresh_token, "ref");
+        assert_eq!(stored.expires_at_ms, 42);
+        assert_eq!(stored.account_id.as_deref(), Some("user_01"));
+        assert_eq!(stored.email.as_deref(), Some("dev@example.com"));
+    }
+}
diff --git a/crates/puffer-cli/src/auth_provider.rs b/crates/puffer-cli/src/auth_provider.rs
index 21e437524..2df27192d 100644
--- a/crates/puffer-cli/src/auth_provider.rs
+++ b/crates/puffer-cli/src/auth_provider.rs
@@ -14,6 +14,7 @@ use puffer_transport_anthropic::{
 pub(crate) enum OauthFamily {
     Anthropic,
     OpenAi,
+    WorldRouter,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -35,6 +36,14 @@ pub(crate) fn oauth_family_for_provider(
     if !provider.auth_modes.contains(&AuthMode::OAuth) {
         return None;
     }
+    if let Some(family) = provider.oauth_family.as_deref() {
+        return match family {
+            "openai" => Some(OauthFamily::OpenAi),
+            "anthropic" => Some(OauthFamily::Anthropic),
+            "worldrouter" => Some(OauthFamily::WorldRouter),
+            _ => None,
+        };
+    }
     match provider.default_api.as_str() {
         "openai-responses"
         | "openai-completions"
@@ -90,6 +99,17 @@ pub(crate) fn oauth_start_bundle_for_provider(
                 manual_redirect_uri: Some(ANTHROPIC_MANUAL_REDIRECT_URL.to_string()),
             })
         }
+        Some(OauthFamily::WorldRouter) => {
+            let config = puffer_provider_worldrouter::WorldRouterLoginConfig::default();
+            Ok(OauthStartBundle {
+                authorization_url: puffer_provider_worldrouter::build_login_url(&config),
+                automatic_authorization_url: None,
+                verifier: String::new(),
+                state: config.client_state,
+                redirect_uri: config.redirect_uri,
+                manual_redirect_uri: None,
+            })
+        }
         None => Err(anyhow!("oauth is not implemented for {provider_id}")),
     }
 }
@@ -144,6 +164,20 @@ pub(crate) fn oauth_login_bundle_for_provider(
                 manual_redirect_uri: Some(manual.redirect_uri),
             })
         }
+        Some(OauthFamily::WorldRouter) => {
+            let config = puffer_provider_worldrouter::WorldRouterLoginConfig {
+                redirect_uri: redirect_uri.to_string(),
+                ..puffer_provider_worldrouter::WorldRouterLoginConfig::default()
+            };
+            Ok(OauthStartBundle {
+                authorization_url: puffer_provider_worldrouter::build_login_url(&config),
+                automatic_authorization_url: None,
+                verifier: String::new(),
+                state: config.client_state,
+                redirect_uri: config.redirect_uri,
+                manual_redirect_uri: None,
+            })
+        }
         None => Err(anyhow!("oauth is not implemented for {provider_id}")),
     }
 }
@@ -176,6 +210,7 @@ mod tests {
                 cost: None,
             }],
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
@@ -230,4 +265,34 @@ mod tests {
         ));
         assert_eq!(oauth_family_for_provider(&providers, "custom-openai"), None);
     }
+
+    #[test]
+    fn oauth_family_uses_explicit_oauth_family_field() {
+        let mut providers = ProviderRegistry::new();
+        let mut descriptor = provider(
+            "worldrouter",
+            "openai-completions",
+            vec![AuthMode::OAuth, AuthMode::ApiKey],
+        );
+        descriptor.oauth_family = Some("worldrouter".to_string());
+        providers.register(descriptor);
+        assert_eq!(
+            oauth_family_for_provider(&providers, "worldrouter"),
+            Some(OauthFamily::WorldRouter)
+        );
+    }
+
+    #[test]
+    fn oauth_family_falls_back_to_default_api_when_field_unset() {
+        let mut providers = ProviderRegistry::new();
+        providers.register(provider(
+            "custom-openai",
+            "openai-completions",
+            vec![AuthMode::OAuth],
+        ));
+        assert_eq!(
+            oauth_family_for_provider(&providers, "custom-openai"),
+            Some(OauthFamily::OpenAi)
+        );
+    }
 }
diff --git a/crates/puffer-cli/src/authflow.rs b/crates/puffer-cli/src/authflow.rs
index f74f6ffc8..e9d3a8850 100644
--- a/crates/puffer-cli/src/authflow.rs
+++ b/crates/puffer-cli/src/authflow.rs
@@ -32,6 +32,23 @@ impl CallbackListener {
         })
     }
 
+    /// Binds a fixed loopback port. Used for redirect URIs that must
+    /// match an Auth Station allow-list entry exactly (such as the
+    /// worldrouter provider). Returns an error if the port is in use.
+    pub(crate) fn bind_localhost_port(path: &str, port: u16) -> Result<Self> {
+        let listener = TcpListener::bind(("127.0.0.1", port)).with_context(|| {
+            format!("failed to bind callback listener on 127.0.0.1:{port} for {path}")
+        })?;
+        listener.set_nonblocking(true)?;
+        Ok(Self {
+            listener,
+            host: "127.0.0.1".to_string(),
+            port,
+            expected_path: path.to_string(),
+            redirect_uri: format!("http://127.0.0.1:{port}{path}"),
+        })
+    }
+
     /// Returns the automatic redirect URI associated with this listener.
     pub(crate) fn redirect_uri(&self) -> &str {
         &self.redirect_uri
@@ -43,6 +60,13 @@ impl CallbackListener {
         while Instant::now() < deadline {
             match self.listener.accept() {
                 Ok((mut stream, _)) => {
+                    // The listener is nonblocking, which is inherited by the
+                    // accepted stream on some platforms (macOS). Switch the
+                    // stream back to blocking + impose a read timeout so we
+                    // don't hit EAGAIN on the first read just because the
+                    // browser's HTTP request hasn't fully flushed yet.
+                    stream.set_nonblocking(false)?;
+                    stream.set_read_timeout(Some(Duration::from_secs(5)))?;
                     let mut buffer = [0_u8; 4096];
                     let bytes_read = stream.read(&mut buffer)?;
                     let request = String::from_utf8_lossy(&buffer[..bytes_read]).to_string();
@@ -174,4 +198,19 @@ mod tests {
             format!("http://127.0.0.1:{callback_port}/callback?code=test-code&state=test-state");
         assert_eq!(callback.as_deref(), Some(expected.as_str()));
     }
+
+    #[test]
+    fn bind_localhost_port_uses_requested_port() {
+        // Find a free port by binding 0, then drop and rebind on it.
+        let probe = TcpListener::bind(("127.0.0.1", 0)).unwrap();
+        let port = probe.local_addr().unwrap().port();
+        drop(probe);
+        let listener = CallbackListener::bind_localhost_port("/callback", port)
+            .expect("bind_localhost_port succeeds on a free port");
+        let redirect_uri = listener.redirect_uri();
+        assert_eq!(
+            redirect_uri,
+            format!("http://127.0.0.1:{port}/callback")
+        );
+    }
 }
diff --git a/crates/puffer-cli/src/cli_args.rs b/crates/puffer-cli/src/cli_args.rs
index 5ff872aaa..ce7b67634 100644
--- a/crates/puffer-cli/src/cli_args.rs
+++ b/crates/puffer-cli/src/cli_args.rs
@@ -28,6 +28,10 @@ pub(crate) struct Cli {
     /// Disable alternate-screen mode for the TUI.
     #[arg(long = "no-alt-screen", default_value_t = false)]
     pub(crate) no_alt_screen: bool,
+
+    /// Override the active provider for the TUI launch path (also applied to `--resume`/fork).
+    #[arg(long = "provider")]
+    pub(crate) provider: Option<String>,
 }
 
 #[derive(Debug, Subcommand)]
diff --git a/crates/puffer-cli/src/daemon.rs b/crates/puffer-cli/src/daemon.rs
index 1397cf8ff..d29342b95 100644
--- a/crates/puffer-cli/src/daemon.rs
+++ b/crates/puffer-cli/src/daemon.rs
@@ -49,6 +49,11 @@ use puffer_provider_openai::{
 use puffer_provider_registry::{
     AuthStore, ModelDescriptor, ProviderDescriptor, ProviderRegistry, StoredCredential,
 };
+use puffer_provider_worldrouter::{
+    exchange_jwt_for_api_key as exchange_worldrouter_jwt_for_api_key,
+    parse_callback_input as parse_worldrouter_callback_input,
+    WORLDROUTER_CALLBACK_PATH, WORLDROUTER_CALLBACK_PORT,
+};
 use puffer_resources::{load_resources, LoadedResources, McpServerSpec};
 use puffer_session_store::{MessageActor, SessionStore, TranscriptEvent};
 use puffer_transport_anthropic::{
@@ -1092,7 +1097,17 @@ fn handle_login_with_oauth(state: &DaemonState, params: &Value) -> Result<Value>
 
     let mut inputs = state.build_runtime_inputs()?;
     let auth_path = state.paths.user_config_dir.join("auth.json");
-    let listener = crate::authflow::CallbackListener::bind_localhost("/callback")?;
+    let listener = if matches!(
+        oauth_family_for_provider(&inputs.providers, &provider_id),
+        Some(OauthFamily::WorldRouter)
+    ) {
+        crate::authflow::CallbackListener::bind_localhost_port(
+            WORLDROUTER_CALLBACK_PATH,
+            WORLDROUTER_CALLBACK_PORT,
+        )?
+    } else {
+        crate::authflow::CallbackListener::bind_localhost("/callback")?
+    };
     let bundle =
         oauth_login_bundle_for_provider(&inputs.providers, &provider_id, listener.redirect_uri())?;
     let launch_url = bundle
@@ -1144,6 +1159,24 @@ fn handle_login_with_oauth(state: &DaemonState, params: &Value) -> Result<Value>
             )?;
             store_anthropic_credential(&mut inputs.auth_store, &provider_id, credential)?;
         }
+        Some(OauthFamily::WorldRouter) => {
+            let parsed = parse_worldrouter_callback_input(&callback);
+            if let Some(err) = parsed.error.as_deref() {
+                let desc = parsed.error_description.as_deref().unwrap_or("");
+                anyhow::bail!("worldrouter login failed: {err} {desc}");
+            }
+            if parsed.state.as_deref() != Some(bundle.state.as_str()) {
+                anyhow::bail!("oauth state mismatch for worldrouter");
+            }
+            let access_token = parsed
+                .token
+                .ok_or_else(|| anyhow::anyhow!("worldrouter callback missing token"))?;
+            let exchanged = exchange_worldrouter_jwt_for_api_key(&access_token)
+                .context("worldrouter JWT→api_key exchange failed")?;
+            inputs
+                .auth_store
+                .set_api_key(provider_id.to_string(), exchanged.api_key);
+        }
         None => anyhow::bail!("oauth login is not implemented for {provider_id}"),
     }
 
@@ -4224,6 +4257,7 @@ mod tests {
             display_name: id.to_string(),
             base_url: "https://example.invalid".to_string(),
             chat_completions_path: None,
+            oauth_family: None,
             default_api: "openai-responses".to_string(),
             auth_modes: Vec::new(),
             headers: IndexMap::new(),
diff --git a/crates/puffer-cli/src/main.rs b/crates/puffer-cli/src/main.rs
index 6b46f45e6..460e307c1 100644
--- a/crates/puffer-cli/src/main.rs
+++ b/crates/puffer-cli/src/main.rs
@@ -47,6 +47,12 @@ use puffer_provider_openai::{
 use puffer_provider_registry::{
     canonical_provider_id, AuthMode, AuthStore, ProviderRegistry, StoredCredential,
 };
+use puffer_provider_worldrouter::{
+    exchange_jwt_for_api_key as exchange_worldrouter_jwt_for_api_key,
+    parse_callback_input as parse_worldrouter_callback_input,
+    refresh_oauth_token as refresh_worldrouter_oauth_token,
+    WORLDROUTER_CALLBACK_PATH, WORLDROUTER_CALLBACK_PORT,
+};
 use puffer_resources::load_resources;
 use puffer_session_store::{SessionMetadata, SessionStore};
 use puffer_tools::ToolRegistry;
@@ -67,6 +73,7 @@ use crate::auth_credentials::{
     anthropic_refresh_scopes, inferred_anthropic_redirect_uri,
     registry_to_anthropic_oauth_credential, set_stored_credential, store_anthropic_credential,
     store_ready_credential_from_anthropic, to_registry_oauth_credential_openai,
+    to_registry_oauth_credential_worldrouter,
 };
 use crate::auth_provider::{
     oauth_family_for_provider, oauth_login_bundle_for_provider, oauth_start_bundle_for_provider,
@@ -88,7 +95,7 @@ fn main() -> Result<()> {
     let cwd = std::env::current_dir()?;
     let paths = ConfigPaths::discover(&cwd);
     ensure_workspace_dirs(&paths)?;
-    let config = load_config(&paths)?;
+    let mut config = load_config(&paths)?;
     let auth_path = paths.user_config_dir.join("auth.json");
     let mut auth_store = AuthStore::load(&auth_path)?;
     let mut resources = load_resources(&paths, &puffer_runner_local::LocalToolRunner::new())?;
@@ -178,6 +185,20 @@ fn main() -> Result<()> {
         None
     };
 
+    // When the user passes `--provider <id>` on the top-level CLI, override
+    // the configured default for the TUI launch paths (`None`, `Resume`,
+    // `Fork`). This lets the desktop GUI pick which provider to start a chat
+    // session with without persisting a config change.
+    if let Some(provider_override) = cli.provider.as_deref() {
+        if matches!(
+            cli.subcommand,
+            None | Some(Command::Resume { .. }) | Some(Command::Fork { .. })
+        ) {
+            let resolved = resolve_provider_id(&providers, provider_override);
+            config.default_provider = Some(resolved);
+        }
+    }
+
     let result = match cli.subcommand {
         Some(Command::Subscriber { .. }) => {
             // Already handled above; here only to satisfy exhaustiveness.
@@ -963,6 +984,12 @@ fn run_auth_command(
                     )?;
                     store_anthropic_credential(auth_store, &provider, credential)?;
                 }
+                Some(OauthFamily::WorldRouter) => {
+                    anyhow::bail!(
+                        "worldrouter does not use the OAuth code-exchange flow; \
+                         run `puffer auth login worldrouter` instead"
+                    );
+                }
                 None => anyhow::bail!("oauth exchange is not implemented for {provider}"),
             }
             auth_store.save(auth_path)?;
@@ -990,6 +1017,11 @@ fn run_auth_command(
                         Some(&registry_to_anthropic_oauth_credential(existing)),
                     )?)?
                 }
+                Some(OauthFamily::WorldRouter) => {
+                    StoredCredential::OAuth(to_registry_oauth_credential_worldrouter(
+                        refresh_worldrouter_oauth_token(&existing.refresh_token, None)?,
+                    ))
+                }
                 None => anyhow::bail!("oauth refresh is not implemented for {provider}"),
             };
             set_stored_credential(auth_store, provider.clone(), refreshed);
@@ -1028,6 +1060,14 @@ fn run_login_flow(
 ) -> Result<()> {
     let callback_listener = if stdin || value.is_some() {
         None
+    } else if matches!(
+        oauth_family_for_provider(providers, provider),
+        Some(OauthFamily::WorldRouter)
+    ) {
+        Some(authflow::CallbackListener::bind_localhost_port(
+            WORLDROUTER_CALLBACK_PATH,
+            WORLDROUTER_CALLBACK_PORT,
+        )?)
     } else {
         Some(authflow::CallbackListener::bind_localhost("/callback")?)
     };
@@ -1098,6 +1138,22 @@ fn run_login_flow(
             )?;
             store_anthropic_credential(auth_store, provider, credential)?;
         }
+        Some(OauthFamily::WorldRouter) => {
+            let parsed = parse_worldrouter_callback_input(&input);
+            if let Some(err) = parsed.error.as_deref() {
+                let desc = parsed.error_description.as_deref().unwrap_or("");
+                anyhow::bail!("worldrouter login failed: {err} {desc}");
+            }
+            if parsed.state.as_deref() != Some(bundle.state.as_str()) {
+                anyhow::bail!("oauth state mismatch for worldrouter");
+            }
+            let access_token = parsed
+                .token
+                .ok_or_else(|| anyhow::anyhow!("worldrouter callback missing token"))?;
+            let exchanged = exchange_worldrouter_jwt_for_api_key(&access_token)
+                .context("worldrouter JWT→api_key exchange failed")?;
+            auth_store.set_api_key(provider.to_string(), exchanged.api_key);
+        }
         None => anyhow::bail!("oauth login is not implemented for {provider}"),
     }
 
diff --git a/crates/puffer-core/command/tests.rs b/crates/puffer-core/command/tests.rs
index 87634908b..733b5cc2a 100644
--- a/crates/puffer-core/command/tests.rs
+++ b/crates/puffer-core/command/tests.rs
@@ -317,6 +317,7 @@ fn doctor_reports_discovery_and_diagnostics() {
         }),
         models: Vec::new(),
         chat_completions_path: None,
+        oauth_family: None,
     });
     let mut auth_store = AuthStore::default();
     auth_store.set_api_key("anthropic", "sk-ant");
diff --git a/crates/puffer-core/command/tests/context.rs b/crates/puffer-core/command/tests/context.rs
index 4761d57a7..e281218d3 100644
--- a/crates/puffer-core/command/tests/context.rs
+++ b/crates/puffer-core/command/tests/context.rs
@@ -87,6 +87,7 @@ fn context_command_renders_anthropic_context_breakdown() {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
 
     dispatch_command(
@@ -166,6 +167,7 @@ fn context_command_renders_openai_context_breakdown() {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
 
     dispatch_command(
diff --git a/crates/puffer-core/command/tests/doctor.rs b/crates/puffer-core/command/tests/doctor.rs
index ec04b6f1d..238f2ab70 100644
--- a/crates/puffer-core/command/tests/doctor.rs
+++ b/crates/puffer-core/command/tests/doctor.rs
@@ -36,6 +36,7 @@ fn provider(id: &str, auth_modes: Vec<AuthMode>) -> ProviderDescriptor {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
diff --git a/crates/puffer-core/command/tests/login_auth.rs b/crates/puffer-core/command/tests/login_auth.rs
index 6f05c4a4b..551c1a084 100644
--- a/crates/puffer-core/command/tests/login_auth.rs
+++ b/crates/puffer-core/command/tests/login_auth.rs
@@ -30,6 +30,7 @@ fn provider(
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
diff --git a/crates/puffer-core/command/tests/model_scope.rs b/crates/puffer-core/command/tests/model_scope.rs
index c41e2656b..2c56c6bc1 100644
--- a/crates/puffer-core/command/tests/model_scope.rs
+++ b/crates/puffer-core/command/tests/model_scope.rs
@@ -30,6 +30,7 @@ fn provider(id: &str, models: &[&str]) -> puffer_provider_registry::ProviderDesc
             })
             .collect(),
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
diff --git a/crates/puffer-core/command/tests/status.rs b/crates/puffer-core/command/tests/status.rs
index fe6d614cc..2984bbe18 100644
--- a/crates/puffer-core/command/tests/status.rs
+++ b/crates/puffer-core/command/tests/status.rs
@@ -43,6 +43,7 @@ fn status_command_reports_richer_session_and_resource_status() {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
     let mut auth_store = AuthStore::default();
     auth_store.set_api_key("openai".to_string(), "sk-test".to_string());
diff --git a/crates/puffer-core/command/tests/usage_buddy.rs b/crates/puffer-core/command/tests/usage_buddy.rs
index 4d979ef08..990538c95 100644
--- a/crates/puffer-core/command/tests/usage_buddy.rs
+++ b/crates/puffer-core/command/tests/usage_buddy.rs
@@ -51,6 +51,7 @@ fn usage_command_reports_runtime_and_resource_counts() {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
     let mut auth_store = AuthStore::default();
     auth_store.set_api_key("anthropic", "sk-ant");
@@ -382,6 +383,7 @@ fn anthropic_provider() -> ProviderDescriptor {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
@@ -408,6 +410,7 @@ fn openai_provider() -> ProviderDescriptor {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
diff --git a/crates/puffer-core/command_helpers/doctor.rs b/crates/puffer-core/command_helpers/doctor.rs
index 337ec6283..c07efb84b 100644
--- a/crates/puffer-core/command_helpers/doctor.rs
+++ b/crates/puffer-core/command_helpers/doctor.rs
@@ -674,6 +674,7 @@ mod tests {
                 cost: None,
             }],
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
diff --git a/crates/puffer-core/command_helpers/prompt_tests.rs b/crates/puffer-core/command_helpers/prompt_tests.rs
index 107aabe75..a6b1219f6 100644
--- a/crates/puffer-core/command_helpers/prompt_tests.rs
+++ b/crates/puffer-core/command_helpers/prompt_tests.rs
@@ -701,6 +701,7 @@ fn local_provider(base_url: String) -> ProviderDescriptor {
             compat: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
diff --git a/crates/puffer-core/memory.rs b/crates/puffer-core/memory.rs
index 3ab940a13..7472b8131 100644
--- a/crates/puffer-core/memory.rs
+++ b/crates/puffer-core/memory.rs
@@ -985,6 +985,7 @@ mod tests {
                 compat: None,
             }],
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
diff --git a/crates/puffer-core/runtime/agent_runtime_tests.rs b/crates/puffer-core/runtime/agent_runtime_tests.rs
index 53c816408..86d934576 100644
--- a/crates/puffer-core/runtime/agent_runtime_tests.rs
+++ b/crates/puffer-core/runtime/agent_runtime_tests.rs
@@ -35,6 +35,7 @@ fn provider() -> ProviderDescriptor {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
diff --git a/crates/puffer-core/runtime/anthropic.rs b/crates/puffer-core/runtime/anthropic.rs
index 381719ad8..6396230aa 100644
--- a/crates/puffer-core/runtime/anthropic.rs
+++ b/crates/puffer-core/runtime/anthropic.rs
@@ -1087,6 +1087,7 @@ mod thinking_gate_tests {
                 compat: model_compat,
             }],
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
diff --git a/crates/puffer-core/runtime/openai/conversation.rs b/crates/puffer-core/runtime/openai/conversation.rs
index f2b4534ea..7e221359f 100644
--- a/crates/puffer-core/runtime/openai/conversation.rs
+++ b/crates/puffer-core/runtime/openai/conversation.rs
@@ -1879,6 +1879,7 @@ mod tests {
                 cost: None,
             }],
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
diff --git a/crates/puffer-core/runtime/openai/support.rs b/crates/puffer-core/runtime/openai/support.rs
index ae5fd1f00..6c587d282 100644
--- a/crates/puffer-core/runtime/openai/support.rs
+++ b/crates/puffer-core/runtime/openai/support.rs
@@ -577,6 +577,7 @@ mod tests {
             discovery: None,
             models: Vec::new(),
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
diff --git a/crates/puffer-core/runtime/tests.rs b/crates/puffer-core/runtime/tests.rs
index 38e3c3d1a..2dab32209 100644
--- a/crates/puffer-core/runtime/tests.rs
+++ b/crates/puffer-core/runtime/tests.rs
@@ -40,6 +40,7 @@ fn provider() -> ProviderDescriptor {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
@@ -201,6 +202,7 @@ fn openai_provider(base_url: String) -> ProviderDescriptor {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     }
 }
 
diff --git a/crates/puffer-provider-registry/Cargo.toml b/crates/puffer-provider-registry/Cargo.toml
index 06ee19ca4..87bfdc06b 100644
--- a/crates/puffer-provider-registry/Cargo.toml
+++ b/crates/puffer-provider-registry/Cargo.toml
@@ -19,3 +19,4 @@ puffer-config = { path = "../puffer-config" }
 
 [dev-dependencies]
 tempfile.workspace = true
+serde_yaml.workspace = true
diff --git a/crates/puffer-provider-registry/src/discovery.rs b/crates/puffer-provider-registry/src/discovery.rs
index fb6a4332e..89d477fd7 100644
--- a/crates/puffer-provider-registry/src/discovery.rs
+++ b/crates/puffer-provider-registry/src/discovery.rs
@@ -422,9 +422,10 @@ mod tests {
             auth_modes: vec![AuthMode::ApiKey],
             headers: IndexMap::new(),
             query_params: IndexMap::new(),
+            chat_completions_path: None,
+            oauth_family: None,
             discovery: Some(discovery),
             models: Vec::new(),
-            chat_completions_path: None,
         }
     }
 
@@ -654,6 +655,8 @@ mod tests {
             auth_modes: vec![crate::auth::AuthMode::ApiKey],
             headers: IndexMap::new(),
             query_params: IndexMap::new(),
+            chat_completions_path: None,
+            oauth_family: None,
             discovery: Some(ModelDiscoveryConfig {
                 path: "/v1/models".to_string(),
                 response: ModelDiscoveryFormat::AnthropicModels,
@@ -667,7 +670,6 @@ mod tests {
                 headers: IndexMap::new(),
             }),
             models: Vec::new(),
-            chat_completions_path: None,
         };
         let mut auth = AuthStore::default();
         auth.set_api_key("custom-anthropic", "sk-ant-custom");
@@ -773,9 +775,10 @@ mod tests {
             auth_modes: vec![AuthMode::OAuth],
             headers: IndexMap::new(),
             query_params: IndexMap::new(),
+            chat_completions_path: None,
+            oauth_family: None,
             discovery: None,
             models: Vec::new(),
-            chat_completions_path: None,
         };
 
         assert_eq!(
@@ -818,6 +821,8 @@ mod tests {
             auth_modes: vec![AuthMode::ApiKey],
             headers: IndexMap::new(),
             query_params: IndexMap::new(),
+            chat_completions_path: None,
+            oauth_family: None,
             discovery: Some(ModelDiscoveryConfig {
                 path: "/v1/models".to_string(),
                 response: ModelDiscoveryFormat::OpenAiModels,
@@ -831,7 +836,6 @@ mod tests {
                 headers: IndexMap::new(),
             }),
             models: Vec::new(),
-            chat_completions_path: None,
         };
         let mut auth = AuthStore::default();
         auth.set_api_key("openai", "sk-test");
diff --git a/crates/puffer-provider-registry/src/model.rs b/crates/puffer-provider-registry/src/model.rs
index d9b14c1ef..4f55792a4 100644
--- a/crates/puffer-provider-registry/src/model.rs
+++ b/crates/puffer-provider-registry/src/model.rs
@@ -331,6 +331,14 @@ pub struct ProviderDescriptor {
     /// to a free-form string here too.
     #[serde(default)]
     pub chat_completions_path: Option<String>,
+    /// Optional explicit OAuth family for this provider. When `None`,
+    /// callers infer the family from `default_api` (preserving every
+    /// yaml that did not opt in). When `Some`, callers use the named
+    /// family directly. Known values today: `"openai"`, `"anthropic"`,
+    /// `"worldrouter"`. This is the seam that lets a provider whose
+    /// transport is `openai-completions` use a non-OpenAI OAuth flow.
+    #[serde(default)]
+    pub oauth_family: Option<String>,
     #[serde(default)]
     pub discovery: Option<ModelDiscoveryConfig>,
     #[serde(default)]
@@ -351,3 +359,40 @@ fn default_items_field() -> String {
 fn default_id_field() -> String {
     "id".to_string()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_yaml;
+
+    #[test]
+    fn provider_descriptor_deserializes_oauth_family_field() {
+        let yaml = r#"
+id: example
+display_name: Example
+base_url: https://example.invalid
+default_api: openai-completions
+oauth_family: worldrouter
+auth_modes:
+  - oauth
+"#;
+        let provider: ProviderDescriptor =
+            serde_yaml::from_str(yaml).expect("provider yaml parses");
+        assert_eq!(provider.oauth_family.as_deref(), Some("worldrouter"));
+    }
+
+    #[test]
+    fn provider_descriptor_oauth_family_defaults_to_none() {
+        let yaml = r#"
+id: example
+display_name: Example
+base_url: https://example.invalid
+default_api: openai-completions
+auth_modes:
+  - oauth
+"#;
+        let provider: ProviderDescriptor =
+            serde_yaml::from_str(yaml).expect("provider yaml parses");
+        assert!(provider.oauth_family.is_none());
+    }
+}
diff --git a/crates/puffer-provider-registry/src/registry.rs b/crates/puffer-provider-registry/src/registry.rs
index 83f59f029..b3c482453 100644
--- a/crates/puffer-provider-registry/src/registry.rs
+++ b/crates/puffer-provider-registry/src/registry.rs
@@ -485,6 +485,7 @@ mod tests {
                 cost: None,
             }],
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
@@ -619,9 +620,10 @@ mod tests {
             auth_modes: vec![AuthMode::ApiKey, AuthMode::OAuth],
             headers: IndexMap::new(),
             query_params: IndexMap::new(),
+            chat_completions_path: None,
+            oauth_family: None,
             discovery: None,
             models: Vec::new(),
-            chat_completions_path: None,
         });
 
         registry.apply_openai_base_url_override(Some("https://proxy.example/v1"));
@@ -645,9 +647,10 @@ mod tests {
             auth_modes: vec![AuthMode::ApiKey, AuthMode::OAuth],
             headers: IndexMap::new(),
             query_params: IndexMap::new(),
+            chat_completions_path: None,
+            oauth_family: None,
             discovery: None,
             models: Vec::new(),
-            chat_completions_path: None,
         });
 
         registry.set_openai_headers(IndexMap::from([(
@@ -675,9 +678,10 @@ mod tests {
             auth_modes: vec![AuthMode::ApiKey, AuthMode::OAuth],
             headers: IndexMap::new(),
             query_params: IndexMap::new(),
+            chat_completions_path: None,
+            oauth_family: None,
             discovery: None,
             models: Vec::new(),
-            chat_completions_path: None,
         });
 
         registry.set_openai_query_params(IndexMap::from([(
diff --git a/crates/puffer-provider-worldrouter/Cargo.toml b/crates/puffer-provider-worldrouter/Cargo.toml
new file mode 100644
index 000000000..3804bfbaa
--- /dev/null
+++ b/crates/puffer-provider-worldrouter/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "puffer-provider-worldrouter"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+base64.workspace = true
+rand = "0.9.2"
+reqwest.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+url = "2.5.7"
+uuid.workspace = true
diff --git a/crates/puffer-provider-worldrouter/src/auth.rs b/crates/puffer-provider-worldrouter/src/auth.rs
new file mode 100644
index 000000000..2bef2a919
--- /dev/null
+++ b/crates/puffer-provider-worldrouter/src/auth.rs
@@ -0,0 +1,473 @@
+//! Auth Station login URL building, callback parsing, JWT decoding.
+
+use anyhow::{anyhow, Context, Result};
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine as _;
+use rand::RngCore;
+use reqwest::blocking::Client;
+use serde::Deserialize;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Default Auth Station base URL (Production). Sandbox is
+/// `https://auth-worldrouter.vercel.app`. The env var named by
+/// [`WORLDROUTER_AUTH_URL_OVERRIDE_ENV`] overrides this at runtime.
+/// `http://127.0.0.1:1456` must be in the target environment's
+/// `ALLOWED_REDIRECT_ORIGINS` allow-list (confirmed for Production
+/// 2026-05-20).
+pub const WORLDROUTER_AUTH_BASE_URL: &str = "https://auth.worldrouter.ai";
+
+/// Env var name that overrides the Auth Station base URL.
+pub const WORLDROUTER_AUTH_URL_OVERRIDE_ENV: &str = "PUFFER_WORLDROUTER_AUTH_URL";
+
+/// Default WR control-api base URL (Production). Backend's preview
+/// deployment lives at `https://control-api-pre-7f819c.worldrouter.ai`
+/// and supports the same `/auth/exchange` shape — set the env
+/// override [`WORLDROUTER_CONTROL_URL_OVERRIDE_ENV`] to swap.
+///
+/// Important: preview control-api mints keys into a preview
+/// LiteLLM DB that the production `inference-api.worldrouter.ai`
+/// does NOT read; preview keys hit `token_not_found_in_db` 401
+/// against prod inference. Always pair preview-control with the
+/// matching preview-inference (when one exists) or use production
+/// control. Verified 2026-05-21.
+pub const WORLDROUTER_CONTROL_BASE_URL: &str = "https://control-api.worldrouter.ai";
+
+/// Env var name that overrides the control-api base URL.
+pub const WORLDROUTER_CONTROL_URL_OVERRIDE_ENV: &str = "PUFFER_WORLDROUTER_CONTROL_URL";
+
+/// Prefix applied to every generated `key_alias` so backend can
+/// distinguish keys minted for the puffer desktop client.
+pub const WORLDROUTER_KEY_ALIAS_PREFIX: &str = "puffer-";
+
+/// Fixed loopback callback path used by Puffer desktop. The auth
+/// team must allow-list the full URI on both Sandbox and Production.
+pub const WORLDROUTER_CALLBACK_PATH: &str = "/callback";
+
+/// Fixed loopback callback port used by Puffer desktop. See
+/// [`WORLDROUTER_CALLBACK_PATH`] for the path component.
+pub const WORLDROUTER_CALLBACK_PORT: u16 = 1456;
+
+/// Concatenated fixed loopback redirect URI.
+pub const WORLDROUTER_DEFAULT_REDIRECT_URI: &str = "http://127.0.0.1:1456/callback";
+
+/// Parameters needed to build an Auth Station login URL.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WorldRouterLoginConfig {
+    /// Base URL of Auth Station, no trailing slash.
+    pub auth_base_url: String,
+    /// Full redirect URI for the desktop callback listener.
+    pub redirect_uri: String,
+    /// Opaque random value used as the CSRF guard.
+    pub client_state: String,
+}
+
+impl Default for WorldRouterLoginConfig {
+    fn default() -> Self {
+        let auth_base_url = std::env::var(WORLDROUTER_AUTH_URL_OVERRIDE_ENV)
+            .ok()
+            .filter(|value| !value.trim().is_empty())
+            .unwrap_or_else(|| WORLDROUTER_AUTH_BASE_URL.to_string());
+        Self {
+            auth_base_url,
+            redirect_uri: WORLDROUTER_DEFAULT_REDIRECT_URI.to_string(),
+            client_state: generate_client_state(),
+        }
+    }
+}
+
+/// Generates an opaque url-safe random `client_state`.
+pub fn generate_client_state() -> String {
+    let mut bytes = [0_u8; 32];
+    rand::rng().fill_bytes(&mut bytes);
+    URL_SAFE_NO_PAD.encode(bytes)
+}
+
+/// Builds the Auth Station `/login` URL for the given config.
+pub fn build_login_url(config: &WorldRouterLoginConfig) -> String {
+    let trimmed = config.auth_base_url.trim_end_matches('/');
+    let mut url = url::Url::parse(&format!("{trimmed}/login"))
+        .expect("auth_base_url must be a valid URL");
+    url.query_pairs_mut()
+        .append_pair("redirect_uri", &config.redirect_uri)
+        .append_pair("client_state", &config.client_state);
+    url.to_string()
+}
+
+/// Parsed callback fields. Each field is `None` when its parameter
+/// was absent from the callback URL.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct WorldRouterCallback {
+    /// `token` query parameter — the access token JWT.
+    pub token: Option<String>,
+    /// `refresh_token` query parameter — the refresh token JWT.
+    pub refresh_token: Option<String>,
+    /// `state` query parameter — original `client_state` echoed back.
+    pub state: Option<String>,
+    /// `error` query parameter — populated when login failed.
+    pub error: Option<String>,
+    /// `error_description` query parameter — populated on failure.
+    pub error_description: Option<String>,
+}
+
+/// Extracts `token`, `refresh_token`, `state`, `error`, and
+/// `error_description` from a callback URL or raw query string.
+pub fn parse_callback_input(input: &str) -> WorldRouterCallback {
+    let trimmed = input.trim();
+    if trimmed.is_empty() {
+        return WorldRouterCallback::default();
+    }
+    let mut callback = WorldRouterCallback::default();
+    let pairs: Box<dyn Iterator<Item = (String, String)>> =
+        if let Ok(url) = url::Url::parse(trimmed) {
+            Box::new(
+                url.query_pairs()
+                    .into_owned()
+                    .collect::<Vec<_>>()
+                    .into_iter(),
+            )
+        } else {
+            Box::new(
+                url::form_urlencoded::parse(trimmed.as_bytes())
+                    .into_owned()
+                    .collect::<Vec<_>>()
+                    .into_iter(),
+            )
+        };
+    for (key, value) in pairs {
+        match key.as_str() {
+            "token" => callback.token = Some(value),
+            "refresh_token" => callback.refresh_token = Some(value),
+            "state" => callback.state = Some(value),
+            "error" => callback.error = Some(value),
+            "error_description" => callback.error_description = Some(value),
+            _ => {}
+        }
+    }
+    callback
+}
+
+/// Decoded JWT profile fields, best-effort.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct WorldRouterJwtProfile {
+    /// JWT `sub` claim — Auth Station user id (WorkOS user id).
+    pub sub: Option<String>,
+    /// JWT `email` claim.
+    pub email: Option<String>,
+    /// JWT `name` claim — may be an empty string upstream.
+    pub name: Option<String>,
+    /// `default_team_id` claim — used as the path segment for the
+    /// control-api key creation endpoint.
+    pub default_team_id: Option<String>,
+}
+
+/// Decodes `sub` / `email` / `name` from the access token JWT
+/// payload. Any decode/parse failure yields an empty profile.
+pub fn decode_jwt_profile(access_token: &str) -> WorldRouterJwtProfile {
+    let Some(payload_b64) = access_token.split('.').nth(1) else {
+        return WorldRouterJwtProfile::default();
+    };
+    let Ok(payload_bytes) = URL_SAFE_NO_PAD.decode(payload_b64.as_bytes()) else {
+        return WorldRouterJwtProfile::default();
+    };
+    let Ok(value) = serde_json::from_slice::<serde_json::Value>(&payload_bytes) else {
+        return WorldRouterJwtProfile::default();
+    };
+    WorldRouterJwtProfile {
+        sub: value
+            .get("sub")
+            .and_then(serde_json::Value::as_str)
+            .map(ToString::to_string),
+        email: value
+            .get("email")
+            .and_then(serde_json::Value::as_str)
+            .map(ToString::to_string),
+        name: value
+            .get("name")
+            .and_then(serde_json::Value::as_str)
+            .map(ToString::to_string),
+        default_team_id: value
+            .get("default_team_id")
+            .and_then(serde_json::Value::as_str)
+            .map(ToString::to_string),
+    }
+}
+
+/// Persisted Auth Station credentials for the worldrouter provider.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WorldRouterOAuthCredentials {
+    /// Auth Station access token (24h validity per current docs).
+    pub access_token: String,
+    /// Auth Station refresh token (7d validity).
+    pub refresh_token: String,
+    /// Unix epoch milliseconds when the access token expires.
+    pub expires_at_ms: u64,
+    /// `sub` claim from the access token JWT.
+    pub sub: Option<String>,
+    /// `email` claim from the access token JWT.
+    pub email: Option<String>,
+    /// `name` claim from the access token JWT.
+    pub name: Option<String>,
+}
+
+/// Exchanges a stored refresh token for a new access token via
+/// `POST <auth>/token/refresh`. Preserves the existing
+/// `refresh_token` (Auth Station does not rotate refresh tokens, and
+/// `/token/refresh` returns only `{ "token": ... }`).
+pub fn refresh_oauth_token(
+    refresh_token: &str,
+    auth_base_url: Option<&str>,
+) -> Result<WorldRouterOAuthCredentials> {
+    let base = auth_base_url
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToString::to_string)
+        .unwrap_or_else(|| {
+            std::env::var(WORLDROUTER_AUTH_URL_OVERRIDE_ENV)
+                .ok()
+                .filter(|value| !value.trim().is_empty())
+                .unwrap_or_else(|| WORLDROUTER_AUTH_BASE_URL.to_string())
+        });
+    let url = format!("{}/token/refresh", base.trim_end_matches('/'));
+    let response = Client::new()
+        .post(&url)
+        .json(&serde_json::json!({ "refresh_token": refresh_token }))
+        .send()
+        .context("failed to send worldrouter refresh request")?;
+    let status = response.status();
+    let payload: RefreshResponse = response
+        .json()
+        .context("failed to parse worldrouter refresh response")?;
+    if !status.is_success() {
+        return Err(anyhow!(
+            "worldrouter token refresh failed with status {status}: {}",
+            payload.error.unwrap_or_default()
+        ));
+    }
+    let access_token = payload
+        .token
+        .ok_or_else(|| anyhow!("worldrouter refresh response missing token"))?;
+    let profile = decode_jwt_profile(&access_token);
+    Ok(WorldRouterOAuthCredentials {
+        access_token,
+        refresh_token: refresh_token.to_string(),
+        expires_at_ms: worldrouter_access_token_expires_at_ms(),
+        sub: profile.sub,
+        email: profile.email,
+        name: profile.name,
+    })
+}
+
+/// Output of a successful JWT→api_key exchange.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExchangedApiKey {
+    /// The WR api_key to send as `Authorization: Bearer <key>` against
+    /// the inference endpoint.
+    pub api_key: String,
+    /// Server-assigned identifier for the key. Useful for future
+    /// revoke calls.
+    pub token_id: String,
+    /// Client-chosen alias used to create the key.
+    pub key_alias: String,
+}
+
+/// Exchanges an Auth Station JWT for a WorldRouter inference api_key.
+///
+/// Two-hop flow:
+/// 1. `POST {control_base}/auth/exchange` body `{ "access_token": <jwt> }`
+///    → infer-monorepo recognises the Auth Station issuer, verifies
+///    the RS256 signature against the Auth Station JWKS, and returns
+///    `{ session_token, default_team_id, ... }` where `session_token`
+///    is an HS256 Infer Session JWT that the litellm gateway in front
+///    of control-api accepts.
+/// 2. `POST {control_base}/platform/v1/teams/{default_team_id}/keys`
+///    with `Authorization: Bearer <session_token>` and a fresh
+///    `key_alias = "puffer-<uuid>"` body → returns `{ key: "sk-worldrouter-..." }`.
+///
+/// TODO(worldrouter): preview-stage shape. Open questions:
+/// - idempotent get-or-create per (user, device) instead of always
+///   minting a new key (avoid leaking dead keys when user re-logins
+///   on the same machine)
+/// - DELETE/revoke endpoint to call on logout
+/// - production base URL (currently `control-api-pre-7f819c…`)
+/// Re-evaluate when backend lands the stable shape.
+pub fn exchange_jwt_for_api_key(access_token: &str) -> Result<ExchangedApiKey> {
+    let base = std::env::var(WORLDROUTER_CONTROL_URL_OVERRIDE_ENV)
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+        .unwrap_or_else(|| WORLDROUTER_CONTROL_BASE_URL.to_string());
+    let base = base.trim_end_matches('/').to_string();
+    let client = Client::new();
+
+    // Hop 1: Auth Station JWT → Infer Session JWT
+    let exchange_url = format!("{base}/auth/exchange");
+    let exchange_response = client
+        .post(&exchange_url)
+        .json(&serde_json::json!({ "access_token": access_token }))
+        .send()
+        .context("failed to send worldrouter /auth/exchange request")?;
+    let exchange_status = exchange_response.status();
+    let exchange_body = exchange_response
+        .text()
+        .context("failed to read worldrouter /auth/exchange response body")?;
+    if !exchange_status.is_success() {
+        return Err(anyhow!(
+            "worldrouter /auth/exchange failed: POST {exchange_url} -> {exchange_status}\nresponse body: {exchange_body}"
+        ));
+    }
+    let envelope: SessionEnvelopeResponse = serde_json::from_str(&exchange_body).with_context(
+        || format!("failed to parse worldrouter /auth/exchange response body: {exchange_body}"),
+    )?;
+
+    // Hop 2: Infer Session JWT → WR inference api_key
+    let key_url = format!(
+        "{base}/platform/v1/teams/{team_id}/keys",
+        team_id = envelope.default_team_id
+    );
+    let key_alias = format!(
+        "{}{}",
+        WORLDROUTER_KEY_ALIAS_PREFIX,
+        uuid::Uuid::new_v4()
+            .as_hyphenated()
+            .to_string()
+            .to_uppercase()
+    );
+    let key_response = client
+        .post(&key_url)
+        .bearer_auth(&envelope.session_token)
+        .json(&serde_json::json!({ "key_alias": key_alias }))
+        .send()
+        .context("failed to send worldrouter key creation request")?;
+    let key_status = key_response.status();
+    let key_body = key_response
+        .text()
+        .context("failed to read worldrouter key creation response body")?;
+    if !key_status.is_success() {
+        return Err(anyhow!(
+            "worldrouter key creation failed: POST {key_url} -> {key_status}\nresponse body: {key_body}"
+        ));
+    }
+    let payload: KeyCreationResponse = serde_json::from_str(&key_body).with_context(|| {
+        format!("failed to parse worldrouter key creation response body: {key_body}")
+    })?;
+    let api_key = payload
+        .key
+        .ok_or_else(|| anyhow!("worldrouter key creation response missing `key`"))?;
+    let token_id = payload
+        .token_id
+        .ok_or_else(|| anyhow!("worldrouter key creation response missing `token_id`"))?;
+    Ok(ExchangedApiKey {
+        api_key,
+        token_id,
+        key_alias,
+    })
+}
+
+#[derive(Debug, Deserialize)]
+struct SessionEnvelopeResponse {
+    session_token: String,
+    default_team_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct KeyCreationResponse {
+    #[serde(default)]
+    token_id: Option<String>,
+    #[serde(default)]
+    key: Option<String>,
+}
+
+/// Returns the Unix epoch milliseconds at which an Auth Station
+/// access token issued **now** expires. Auth Station access tokens
+/// have a 24-hour lifetime per the public API doc; this helper
+/// centralizes that constant.
+pub fn worldrouter_access_token_expires_at_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_millis() as u64 + 24 * 3600 * 1000)
+        .unwrap_or(24 * 3600 * 1000)
+}
+
+#[derive(Debug, Deserialize)]
+struct RefreshResponse {
+    #[serde(default)]
+    token: Option<String>,
+    #[serde(default)]
+    error: Option<String>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_login_url_contains_redirect_uri_and_client_state() {
+        let config = WorldRouterLoginConfig {
+            auth_base_url: "https://auth-worldrouter.vercel.app".to_string(),
+            redirect_uri: "http://127.0.0.1:1456/callback".to_string(),
+            client_state: "state-xyz".to_string(),
+        };
+        let url = build_login_url(&config);
+        assert!(url.starts_with("https://auth-worldrouter.vercel.app/login?"));
+        assert!(url.contains("redirect_uri=http%3A%2F%2F127.0.0.1%3A1456%2Fcallback"));
+        assert!(url.contains("client_state=state-xyz"));
+    }
+
+    #[test]
+    fn parse_callback_input_extracts_token_refresh_state() {
+        let parsed = parse_callback_input(
+            "http://127.0.0.1:1456/callback?token=acc&refresh_token=ref&state=xyz",
+        );
+        assert_eq!(parsed.token.as_deref(), Some("acc"));
+        assert_eq!(parsed.refresh_token.as_deref(), Some("ref"));
+        assert_eq!(parsed.state.as_deref(), Some("xyz"));
+        assert!(parsed.error.is_none());
+    }
+
+    #[test]
+    fn parse_callback_input_extracts_error() {
+        let parsed = parse_callback_input(
+            "http://127.0.0.1:1456/callback?error=invalid_state&error_description=bad+state&state=xyz",
+        );
+        assert_eq!(parsed.error.as_deref(), Some("invalid_state"));
+        assert_eq!(parsed.error_description.as_deref(), Some("bad state"));
+        assert!(parsed.token.is_none());
+    }
+
+    #[test]
+    fn parse_callback_input_handles_raw_query_string() {
+        let parsed = parse_callback_input("token=acc&state=xyz");
+        assert_eq!(parsed.token.as_deref(), Some("acc"));
+        assert_eq!(parsed.state.as_deref(), Some("xyz"));
+    }
+
+    #[test]
+    fn decode_jwt_profile_reads_sub_email_name() {
+        let payload = serde_json::json!({
+            "sub": "user_01ABC",
+            "email": "dev@example.com",
+            "name": "Dev User",
+            "default_team_id": "team-abc-123",
+        });
+        let encoded = URL_SAFE_NO_PAD.encode(payload.to_string());
+        let token = format!("header.{encoded}.sig");
+        let profile = decode_jwt_profile(&token);
+        assert_eq!(profile.sub.as_deref(), Some("user_01ABC"));
+        assert_eq!(profile.email.as_deref(), Some("dev@example.com"));
+        assert_eq!(profile.name.as_deref(), Some("Dev User"));
+        assert_eq!(profile.default_team_id.as_deref(), Some("team-abc-123"));
+    }
+
+    #[test]
+    fn decode_jwt_profile_handles_malformed_token() {
+        let profile = decode_jwt_profile("not-a-jwt");
+        assert!(profile.sub.is_none());
+        assert!(profile.email.is_none());
+        assert!(profile.name.is_none());
+    }
+
+    // Note: `exchange_jwt_for_api_key` now does two real HTTP hops
+    // (`/auth/exchange` then `/platform/v1/teams/{team_id}/keys`).
+    // Unit tests would need an HTTP mock server; we exercise the
+    // function through the manual e2e probe in `puffer auth login
+    // worldrouter` instead.
+}
diff --git a/crates/puffer-provider-worldrouter/src/lib.rs b/crates/puffer-provider-worldrouter/src/lib.rs
new file mode 100644
index 000000000..9e30df04d
--- /dev/null
+++ b/crates/puffer-provider-worldrouter/src/lib.rs
@@ -0,0 +1,20 @@
+//! Auth Station OAuth helpers for the `worldrouter` provider.
+//!
+//! Auth Station's `/login` flow returns the final `token` and
+//! `refresh_token` directly in the callback URL. There is no PKCE,
+//! no code exchange. This crate owns URL building, callback
+//! parsing, JWT-payload decoding, and refresh.
+
+mod auth;
+
+pub use auth::{
+    build_login_url, decode_jwt_profile, exchange_jwt_for_api_key,
+    generate_client_state, parse_callback_input, refresh_oauth_token,
+    worldrouter_access_token_expires_at_ms,
+    ExchangedApiKey, WorldRouterCallback, WorldRouterJwtProfile, WorldRouterLoginConfig,
+    WorldRouterOAuthCredentials, WORLDROUTER_AUTH_BASE_URL,
+    WORLDROUTER_AUTH_URL_OVERRIDE_ENV, WORLDROUTER_CALLBACK_PATH,
+    WORLDROUTER_CALLBACK_PORT, WORLDROUTER_CONTROL_BASE_URL,
+    WORLDROUTER_CONTROL_URL_OVERRIDE_ENV, WORLDROUTER_DEFAULT_REDIRECT_URI,
+    WORLDROUTER_KEY_ALIAS_PREFIX,
+};
diff --git a/crates/puffer-resources/src/model.rs b/crates/puffer-resources/src/model.rs
index 32b3bf8b9..1ee93425d 100644
--- a/crates/puffer-resources/src/model.rs
+++ b/crates/puffer-resources/src/model.rs
@@ -463,6 +463,10 @@ pub struct ProviderPack {
     /// so we don't double up to `/v4/v1/chat/completions`.
     #[serde(default)]
     pub chat_completions_path: Option<String>,
+    /// OAuth family tag for this provider. See `ProviderDescriptor::oauth_family`
+    /// for the canonical description of this field.
+    #[serde(default)]
+    pub oauth_family: Option<String>,
     #[serde(default)]
     pub discovery: Option<ModelDiscoveryConfig>,
     #[serde(default)]
@@ -481,6 +485,7 @@ impl ProviderPack {
             headers: self.headers,
             query_params: self.query_params,
             chat_completions_path: self.chat_completions_path,
+            oauth_family: self.oauth_family,
             discovery: self.discovery,
             models: self.models,
         }
@@ -553,4 +558,20 @@ mod tests {
             "fallback list should include the current nano model"
         );
     }
+
+    /// Confirms the bundled `worldrouter.yaml` parses as a
+    /// `ProviderPack` and that the `oauth_family` field round-trips
+    /// through `into_descriptor`. Without this end-to-end wiring the
+    /// runtime would silently fall back to OpenAI OAuth.
+    #[test]
+    fn worldrouter_yaml_parses_with_oauth_family() {
+        let yaml = include_str!("../../../resources/providers/worldrouter.yaml");
+        let pack: ProviderPack = serde_yaml::from_str(yaml).expect("worldrouter.yaml parses");
+        assert_eq!(pack.id, "worldrouter");
+        assert_eq!(pack.oauth_family.as_deref(), Some("worldrouter"));
+        let descriptor = pack.into_descriptor();
+        assert_eq!(descriptor.oauth_family.as_deref(), Some("worldrouter"));
+        assert!(descriptor.auth_modes.contains(&AuthMode::ApiKey));
+        assert!(descriptor.auth_modes.contains(&AuthMode::OAuth));
+    }
 }
diff --git a/crates/puffer-tui/src/onboarding/mod.rs b/crates/puffer-tui/src/onboarding/mod.rs
index 2c4548654..498226308 100644
--- a/crates/puffer-tui/src/onboarding/mod.rs
+++ b/crates/puffer-tui/src/onboarding/mod.rs
@@ -729,6 +729,7 @@ mod tests {
                 cost: None,
             }],
             chat_completions_path: None,
+            oauth_family: None,
         }
     }
 
diff --git a/crates/puffer-tui/src/render/tests.rs b/crates/puffer-tui/src/render/tests.rs
index 228b30a9c..358f30ac9 100644
--- a/crates/puffer-tui/src/render/tests.rs
+++ b/crates/puffer-tui/src/render/tests.rs
@@ -846,6 +846,7 @@ pub(super) fn sample_providers() -> ProviderRegistry {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
     registry.register(ProviderDescriptor {
         id: "openai".to_string(),
@@ -869,6 +870,7 @@ pub(super) fn sample_providers() -> ProviderRegistry {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
     registry
 }
diff --git a/crates/puffer-tui/src/tests/support.rs b/crates/puffer-tui/src/tests/support.rs
index 122eae3bd..35f25edc2 100644
--- a/crates/puffer-tui/src/tests/support.rs
+++ b/crates/puffer-tui/src/tests/support.rs
@@ -202,6 +202,7 @@ pub(super) fn openai_provider_resources() -> LoadedResources {
                     cost: None,
                 }],
                 chat_completions_path: None,
+                oauth_family: None,
             },
         )],
         ..LoadedResources::default()
@@ -246,6 +247,7 @@ pub(super) fn sample_providers() -> ProviderRegistry {
             },
         ],
         chat_completions_path: None,
+        oauth_family: None,
     });
     providers.register(ProviderDescriptor {
         id: "openai".to_string(),
@@ -269,6 +271,7 @@ pub(super) fn sample_providers() -> ProviderRegistry {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
     providers.register(ProviderDescriptor {
         id: "ollama".to_string(),
@@ -292,6 +295,7 @@ pub(super) fn sample_providers() -> ProviderRegistry {
             cost: None,
         }],
         chat_completions_path: None,
+        oauth_family: None,
     });
     providers
 }
diff --git a/docs/superpowers/notes/2026-05-20-worldrouter-backend-handoff.md b/docs/superpowers/notes/2026-05-20-worldrouter-backend-handoff.md
new file mode 100644
index 000000000..6f66d9814
--- /dev/null
+++ b/docs/superpowers/notes/2026-05-20-worldrouter-backend-handoff.md
@@ -0,0 +1,260 @@
+# worldrouter 端到端联调 — 待解决问题
+
+Date: 2026-05-20
+Author: sean (with Claude)
+Status: 阻塞中，待 Auth + Infer 后端处理
+
+---
+
+## 背景
+
+puffer 桌面端新增 `worldrouter` provider，OAuth 登录流程：
+
+```
+puffer-cli auth login worldrouter
+  → 浏览器打开 https://auth.worldrouter.ai/login?redirect_uri=http://127.0.0.1:1456/callback&client_state=...
+  → 用户登录（Auth Station + WorkOS AuthKit）
+  → Auth Station 302 回 http://127.0.0.1:1456/callback?token=<JWT>&refresh_token=...&state=...
+  → puffer 监听器抓回调
+  → puffer 用 token JWT 调 control-api 创建 WR api_key
+  → 把 api_key 落本地 AuthStore，worldrouter 就能跑 inference
+```
+
+代码已经实现并 push 到 `feat/worldrouter-provider` 分支（commit `1132c94` 及之前），单测 7/7 通过，workspace 编译干净。下面是**联调时发现的两个上游问题**，puffer 这边已经做不了，需要后端改。
+
+---
+
+## 问题 1：Production Auth Station 没读到 `ALLOWED_REDIRECT_ORIGINS` 的最新值
+
+### 现象
+
+浏览器打开
+`https://auth.worldrouter.ai/login?redirect_uri=http://127.0.0.1:1456/callback&client_state=X`，
+用户登录成功后，Auth Station **没有** 302 回 `127.0.0.1:1456`，而是落到 `https://auth.worldrouter.ai/`（404）。这是 auth-docs §troubleshooting 里写的"**redirect_uri 不在白名单 → 静默忽略 → 落到首页**"。
+
+### 验证（已做）
+
+- `vercel env pull --environment=production` 拉出来 `ALLOWED_REDIRECT_ORIGINS` 的当前值，**包含** `http://127.0.0.1:1456`（格式正确，逗号分隔，与现有 `https://worldrouter.ai` 等条目同行）。
+- `auth/src/lib/sanitize.ts::validateRedirectUri` 的逻辑读 env、`split(',').map(trim)`、`new URL(uri).origin` exact match，完全正确。
+- 关键探活（用 `wangshun+3@tomo.inc` 登录后浏览器拿到的 `__auth_session` cookie）：
+
+  ```bash
+  COOKIE='<__auth_session value>'
+  
+  # 探针 A：我们想要的 redirect_uri
+  curl -i -b "__auth_session=$COOKIE" \
+    'https://auth.worldrouter.ai/session/check?redirect_uri=http%3A%2F%2F127.0.0.1%3A1456%2Fcallback&client_state=probeA'
+  # 结果：HTTP/2 200，没有 Location → 静默拒绝 ❌
+  
+  # 探针 B：白名单里已有的 worldrouter.ai
+  curl -i -b "__auth_session=$COOKIE" \
+    'https://auth.worldrouter.ai/session/check?redirect_uri=https%3A%2F%2Fworldrouter.ai%2Ftest&client_state=probeB'
+  # 结果：HTTP/2 302
+  # location: https://worldrouter.ai/test?state=probeB&token=<Auth Station JWT>&refresh_token=<...>  ✅
+  
+  # 探针 C：明显非法的 URL
+  curl -i -b "__auth_session=$COOKIE" \
+    'https://auth.worldrouter.ai/session/check?redirect_uri=https%3A%2F%2Fnonsense.example.com%2Ftest&client_state=probeC'
+  # 结果：HTTP/2 200，没有 Location → 静默拒绝 ❌
+  ```
+
+  → 证明 cookie / silent SSO / 白名单校验逻辑全都正常。**只是当前运行的 deployment 不认识 `http://127.0.0.1:1456`。**
+
+### 推断（修正版 2026-05-20）
+
+**不是** "Vercel redeploy 复用旧 env snapshot"，**不是** "Vercel 过滤 loopback IP literal"。
+
+真实根因：Vercel UI 上对 env entry 做 **edit + append + save** 时，CLI / `vercel env pull` 能立即读到新值（UI 状态层），但 **deployment build 注入用的是上一个真正持久化版本**（存储层）。前者快、后者慢，两层不同步。
+
+### 修复（已生效）
+
+在 Vercel UI Settings → Environment Variables 找到 `ALLOWED_REDIRECT_ORIGINS` Production → **⋯ Remove** 整条 → 重新 **Add** 同名 entry 写入完整新 value（一次性写全所有条目）→ **Save** → Redeploy 一次。
+
+**仅 edit + 末尾 append + save 不可靠** — `vercel env pull` 能立刻看到新值，但 deployment 注入有同步延迟。
+
+### 当前 Production 状态（2026-05-20 已验）
+
+- Latest deployment: `dpl_CSjGzTPKpUn6aSye3QetZnqLfe9q` (`auth-worldrouter-gsih04aqk-nubit.vercel.app`)
+- `auth.worldrouter.ai` alias 已切到此 deployment
+- `ALLOWED_REDIRECT_ORIGINS` 包含 13 项，其中：
+  - `http://127.0.0.1:1456` ✓ ACCEPTED
+  - `http://localhost:1456` ✓ ACCEPTED（兜底）
+  - 其他 11 项 ✓
+
+### 验证（无需 cookie）
+
+```bash
+curl -sS -o /dev/null -w "%{http_code}\n" \
+  'https://auth.worldrouter.ai/session/check?redirect_uri=http%3A%2F%2F127.0.0.1%3A1456%2Fcallback&client_state=p'
+# 期望: 307（实测通过）
+```
+
+---
+
+## 问题 2：Auth Station JWT 不含 `default_team_id`，但 control-api 路径需要 `team_id`
+
+### 现象
+
+后端给的 control-api 调用方式：
+
+```
+POST https://control-api-pre-7f819c.worldrouter.ai/platform/v1/teams/{team_id}/keys
+Authorization: Bearer <JWT>
+Body:  {"key_alias": "puffer-<uuid>"}
+```
+
+`{team_id}` 必须从 JWT 的 `default_team_id` claim 取。
+
+但**实际从 Auth Station 拿到的 JWT 不带这个字段**。
+
+### 证据
+
+探针 B 拿到的 token JWT decode：
+
+```json
+{
+  "sub": "user_01KRNMV53Y0WTZBPXA2RWNMC06",
+  "email": "wangshun+3@tomo.inc",
+  "name": "shun wang",
+  "picture": null,
+  "iss": "https://auth.worldrouter.ai",
+  "aud": "worldclaw",
+  "iat": 1779275875,
+  "exp": 1779362275
+}
+```
+
+对比之前后端给的 control-api curl 示例里那个 JWT（能跑通的那个）：
+
+```json
+{
+  "iss": "infer-session",      ← 不一样
+  "sub": "cf530f43-...",
+  "user_id": "cf530f43-...",
+  "email": "winterfell0614+7@gmail.com",
+  "default_team_id": "6afdef35-...",   ← 关键字段
+  "user_role": "internal_user",
+  "idp": "workos",
+  "idp_sub": "user_01KRZJFGVE90DCGPP1E16XBJXX",
+  "jti": "...",
+  "iat": 1779266768,
+  "exp": 1779353167
+}
+```
+
+→ 那个能跑通 control-api 的 JWT 不是 Auth Station 签的，而是 **infer-monorepo 内部签发的 session JWT**（HS256，`iss=infer-session`，多了 `default_team_id` / `user_role` / `user_id` 等业务字段）。
+
+### 含义
+
+桌面端只能拿到 Auth Station JWT（OIDC 标准、面向所有接入方）。**桌面端没法直接拿到 infer-session JWT**——那是 worldrouter dashboard / infer BFF 自己签的，浏览器侧只有 cookie，没有原始 JWT。
+
+所以 puffer 现在的实现里 `exchange_jwt_for_api_key()` 第一行 `decode_jwt_profile(jwt).default_team_id.ok_or_else(...)` 会立刻失败，整个流程在那一步炸。
+
+### 修复方案（让后端拍板）
+
+| 方案 | 改动方 | 备注 |
+|---|---|---|
+| **A. control-api 直接接受 Auth Station JWT**（推荐） | infer 后端 | 控制台拿 Authorization header → 用 `https://auth.worldrouter.ai/jwks` 验签（RS256, `aud=worldclaw`, `iss=https://auth.worldrouter.ai`）→ 从 JWT 的 `sub`（即 WorkOS user_id）反查 infer 数据库找用户默认 team。puffer 端代码 0 改动，URL 还是 `POST /platform/v1/teams/{default_team_id}/keys`，但 `{default_team_id}` 由后端从 user 反查得出。或者干脆改成 `POST /platform/v1/keys`（不要 team 路径段），后端自己挑用户默认 team。 |
+| **B. 新增 「Auth Station JWT → Infer Session JWT」交换端点** | infer 后端 | puffer 多走一步 `POST /v1/auth/exchange { authStationToken }` → 拿到 infer-session JWT → 再 `POST /platform/v1/teams/{team_id}/keys`。puffer 代码改一行 `exchange_jwt_for_api_key` 内部多调一次 fetch。这跟 auth-docs §guides/backend.md 的"两层 JWT"模式吻合。 |
+| C. body 里塞 team_id | 任一方 | 让前端 / puffer 自己选 team。但桌面端没法选——它只有一个登录态、不知道用户多 team 怎么处理。除非接口 idempotent "默认 team" 行为。Not great。 |
+
+**推荐方案 A**，因为 puffer 是桌面端、没 BFF，多一跳 latency 没必要；并且 Auth Station JWT 已经是 RS256 + JWKS 签发的标准 OIDC token，外部服务做 JWT 验签是常态。
+
+### 2026-05-20 实测：完整跑通 e2e 流程，得到决定性证据
+
+puffer 端加了 `PUFFER_WORLDROUTER_TEAM_ID` env 兜底（先不依赖 JWT 的 `default_team_id`），实际触发了一次完整 OAuth → control-api 调用：
+
+```
+POST https://control-api-pre-7f819c.worldrouter.ai/platform/v1/teams/6afdef35-ea87-54a9-9662-8b8bf090c0fd/keys
+Authorization: Bearer <Auth Station JWT, RS256, iss=auth.worldrouter.ai, aud=worldclaw>
+Body: {"key_alias":"puffer-<uuid>"}
+
+← 401 Unauthorized
+  {"detail":{"code":"litellm_unauthorized","message":"Invalid Infer session token"}}
+```
+
+→ **决定性证据**：control-api 路径上挂着一个 litellm gateway，它消费的是内部 Infer session token（HS256, `iss=infer-session`），**不消费 Auth Station JWT**（RS256, `iss=auth.worldrouter.ai`）。即使 puffer 提供了正确的 `team_id`，control-api 也会拒签。
+
+→ 上面"修复方案"表里方案 A / B 不只是「JWT 缺字段」的问题，而是「control-api 不认这条 token」的问题。两个方案都还成立，但 **B 在实现上可能更接近现状**：infer-monorepo 已经有自己的 session token 签发机制，加一个 `POST /auth/exchange { authStationToken }` → 复用现有 litellm 验签链路，比改 control-api 验签更小动作。
+
+### 验证修复
+
+修完后 puffer 端 e2e 跑通的判据：
+
+```bash
+cd /Users/shun/Data/Code/tomo/agentenv/puffer
+PUFFER_WORLDROUTER_TEAM_ID=<your team uuid>  # 方案 A 落地后可去掉
+  cargo run -p puffer-cli -- auth login worldrouter
+```
+
+期望 stdout 末行：`stored oauth credentials for worldrouter`；`~/Library/Application Support/com.tomo.puffer/auth.json` 应该包含 `worldrouter → {kind: api_key, key: sk-worldrouter-...}`。
+
+浏览器打开 puffer 打印的 URL → 用一个 Production 已有的账号登录 → puffer 终端打印：
+
+```
+stored oauth credentials for worldrouter       # 或类似 "stored api key for worldrouter"
+```
+
+然后立刻验证 api_key 真能用：
+
+```bash
+cat ~/Library/Application\ Support/com.tomo.puffer/auth.json \
+  | jq '.providers.worldrouter'
+
+# 期望看到 { "kind": "api_key", "key": "sk-worldrouter-..." }
+
+curl -sS https://inference-api.worldrouter.ai/v1/models \
+  -H "Authorization: Bearer <sk-worldrouter-...>"
+
+# 期望返回模型列表 JSON，HTTP 200
+```
+
+---
+
+## 附录 A：相关文件 / commit / endpoint 速查
+
+| 项目 | 位置 |
+|---|---|
+| puffer 实现 | `feat/worldrouter-provider` 分支，head `1132c94`（spec → impl → cleanup） |
+| `exchange_jwt_for_api_key` 实现 | `crates/puffer-provider-worldrouter/src/auth.rs:279`（带 TODO 说明 API 会调整） |
+| 设计文档 | `docs/superpowers/specs/2026-05-20-worldrouter-provider-design.md` |
+| 实现 plan | `docs/superpowers/plans/2026-05-20-worldrouter-provider.md` |
+| Auth Station 源码 | `/Users/shun/Data/Code/tomo/worldclaw/infer-monorepo/auth/` |
+| 白名单校验逻辑 | `auth/src/lib/sanitize.ts::validateRedirectUri` |
+| 白名单 env 读取 | `auth/src/lib/config.ts::allowedRedirectOrigins` |
+| Auth Station Sandbox | `https://auth-worldrouter.vercel.app`（puffer 默认） |
+| Auth Station Production | `https://auth.worldrouter.ai`（联调走这个） |
+| Auth Station JWKS | `https://auth.worldrouter.ai/jwks` — 用于验 puffer 拿到的 token |
+| Inference API（OpenAI 兼容） | `https://inference-api.worldrouter.ai/v1/...` |
+| Control API（创建 key 用） | `https://control-api-pre-7f819c.worldrouter.ai`（预览，会变） |
+| Vercel project | `nubit/auth-worldrouter`，prj id `prj_4Mi7OqkeMQ5bOaNzzMOiLHsPRDGl` |
+| puffer 端 env override | `PUFFER_WORLDROUTER_AUTH_URL`、`PUFFER_WORLDROUTER_CONTROL_URL` |
+
+## 附录 B：puffer 端固定 callback
+
+桌面端写死 loopback callback：`http://127.0.0.1:1456/callback`。
+
+- 必须在 Auth Station `ALLOWED_REDIRECT_ORIGINS` 白名单里（origin 严格匹配，protocol+host+port，路径不参与）
+- 既要在 Production 加（`auth.worldrouter.ai`），也要在 Sandbox 加（`auth-worldrouter.vercel.app`）
+- 加 env 之后**必须 redeploy**，Vercel 不会自动 reload
+
+## 附录 C：一个完整的 Auth Station JWT 真实样本（已脱敏？）
+
+来自探针 B 响应，便于后端测试 JWKS 验签：
+
+```
+header:  {"alg":"RS256","kid":"prod-1","typ":"JWT"}
+payload: {
+  "sub": "user_01KRNMV53Y0WTZBPXA2RWNMC06",
+  "email": "wangshun+3@tomo.inc",
+  "name": "shun wang",
+  "picture": null,
+  "iss": "https://auth.worldrouter.ai",
+  "aud": "worldclaw",
+  "iat": 1779275875,
+  "exp": 1779362275
+}
+signature: <RS256 sig, verifiable via /jwks kid=prod-1>
+```
+
+注：这个 token 是 wangshun+3@tomo.inc 在 2026-05-20 11:17 UTC 登录拿到的，有效期 24h（到 2026-05-21 11:17 UTC）。等过期之后会失效；这里只用于说明 JWT 的形状。
diff --git a/docs/superpowers/plans/2026-05-20-worldrouter-provider.md b/docs/superpowers/plans/2026-05-20-worldrouter-provider.md
new file mode 100644
index 000000000..65f2ea1a8
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-20-worldrouter-provider.md
@@ -0,0 +1,1760 @@
+# worldrouter Provider Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a new `worldrouter` provider entry to Puffer that supports both API-key paste and an Auth-Station OAuth login flow (opens https://auth-worldrouter.vercel.app/login in the system browser, captures token+refresh on a fixed localhost callback, stores credential).
+
+**Architecture:** A new minimal Rust crate `puffer-provider-worldrouter` implements Auth Station's "token-in-redirect" flow (no PKCE, no code exchange). `ProviderDescriptor`/`ProviderPack` gain an optional `oauth_family` field that lets a provider opt into a non-`default_api`-derived OAuth handler. `puffer-cli`'s OAuth dispatch (`auth_provider.rs` + `daemon.rs` + `main.rs`) grows a third arm for `OauthFamily::WorldRouter`. `authflow::CallbackListener` grows a `bind_localhost_port` variant for fixed-port binds. A new `resources/providers/worldrouter.yaml` ships the provider. The desktop Svelte UI registers a visual entry; LoginView is unchanged.
+
+**Tech Stack:** Rust (workspace crates), reqwest blocking client, base64 + serde_json (JWT payload decode), serde_yaml (provider yaml), Svelte 5 + TypeScript (desktop visual entry).
+
+**Spec:** `docs/superpowers/specs/2026-05-20-worldrouter-provider-design.md`
+
+---
+
+## File Structure
+
+**Created:**
+- `crates/puffer-provider-worldrouter/Cargo.toml`
+- `crates/puffer-provider-worldrouter/src/lib.rs`
+- `crates/puffer-provider-worldrouter/src/auth.rs`
+- `resources/providers/worldrouter.yaml`
+- `specs/puffer-provider-worldrouter/00.md`
+- `specs/puffer-provider-registry/06.md`
+- `specs/puffer-cli/<next>.md` — exact filename picked in Task 8
+
+**Modified:**
+- `Cargo.toml` (workspace members + workspace deps)
+- `crates/puffer-provider-registry/src/model.rs` — `oauth_family` field
+- `crates/puffer-resources/src/model.rs` — `ProviderPack.oauth_family` mirror + `into_descriptor` pass-through
+- `crates/puffer-cli/Cargo.toml` — dep on `puffer-provider-worldrouter`
+- `crates/puffer-cli/src/auth_provider.rs` — `OauthFamily::WorldRouter` arm
+- `crates/puffer-cli/src/auth_credentials.rs` — `to_registry_oauth_credential_worldrouter`
+- `crates/puffer-cli/src/authflow.rs` — `bind_localhost_port` helper
+- `crates/puffer-cli/src/main.rs` — login flow + `run_login_flow` arm
+- `crates/puffer-cli/src/daemon.rs` — `handle_login_with_oauth` arm
+- `apps/puffer-desktop/src/lib/providerVisuals.ts` — visual entry for `worldrouter`
+
+---
+
+## Task 1: Add `oauth_family` field to ProviderDescriptor + ProviderPack
+
+**Files:**
+- Modify: `crates/puffer-provider-registry/src/model.rs`
+- Modify: `crates/puffer-resources/src/model.rs`
+
+- [ ] **Step 1: Write the failing test in puffer-provider-registry**
+
+Append to `crates/puffer-provider-registry/src/model.rs` test module (the file already ends with `}` for impls; add a `#[cfg(test)] mod` if absent — currently the file has no test module, add one at the very end):
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_yaml;
+
+    #[test]
+    fn provider_descriptor_deserializes_oauth_family_field() {
+        let yaml = r#"
+id: example
+display_name: Example
+base_url: https://example.invalid
+default_api: openai-completions
+oauth_family: worldrouter
+auth_modes:
+  - oauth
+"#;
+        let provider: ProviderDescriptor =
+            serde_yaml::from_str(yaml).expect("provider yaml parses");
+        assert_eq!(provider.oauth_family.as_deref(), Some("worldrouter"));
+    }
+
+    #[test]
+    fn provider_descriptor_oauth_family_defaults_to_none() {
+        let yaml = r#"
+id: example
+display_name: Example
+base_url: https://example.invalid
+default_api: openai-completions
+auth_modes:
+  - oauth
+"#;
+        let provider: ProviderDescriptor =
+            serde_yaml::from_str(yaml).expect("provider yaml parses");
+        assert!(provider.oauth_family.is_none());
+    }
+}
+```
+
+If `serde_yaml` isn't already a dev-dep, add it. Check first:
+
+```bash
+grep -n "serde_yaml\|serde-yaml" crates/puffer-provider-registry/Cargo.toml
+```
+
+If absent, add to `[dev-dependencies]`:
+
+```toml
+[dev-dependencies]
+serde_yaml = "0.9"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cargo test -p puffer-provider-registry provider_descriptor_deserializes_oauth_family_field
+```
+
+Expected: FAIL — field doesn't exist on `ProviderDescriptor` (unknown field).
+
+- [ ] **Step 3: Add the field to `ProviderDescriptor`**
+
+In `crates/puffer-provider-registry/src/model.rs`, inside the `ProviderDescriptor` struct (around line 309-338), add right after `chat_completions_path`:
+
+```rust
+    /// Optional explicit OAuth family for this provider. When `None`,
+    /// callers infer the family from `default_api` (preserving every
+    /// yaml that did not opt in). When `Some`, callers use the named
+    /// family directly. Known values today: `"openai"`, `"anthropic"`,
+    /// `"worldrouter"`. This is the seam that lets a provider whose
+    /// transport is `openai-completions` use a non-OpenAI OAuth flow.
+    #[serde(default)]
+    pub oauth_family: Option<String>,
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+cargo test -p puffer-provider-registry provider_descriptor
+```
+
+Expected: PASS for both new tests.
+
+- [ ] **Step 5: Mirror the field in `ProviderPack`**
+
+In `crates/puffer-resources/src/model.rs`, find `pub struct ProviderPack` (around line 449) and add right after `chat_completions_path`:
+
+```rust
+    #[serde(default)]
+    pub oauth_family: Option<String>,
+```
+
+Then update `into_descriptor()` (around line 472) — add `oauth_family: self.oauth_family,` in the struct literal:
+
+```rust
+    pub fn into_descriptor(self) -> ProviderDescriptor {
+        ProviderDescriptor {
+            id: self.id,
+            display_name: self.display_name,
+            base_url: self.base_url,
+            default_api: self.default_api,
+            auth_modes: self.auth_modes,
+            headers: self.headers,
+            query_params: self.query_params,
+            chat_completions_path: self.chat_completions_path,
+            oauth_family: self.oauth_family,
+            discovery: self.discovery,
+            models: self.models,
+        }
+    }
+```
+
+- [ ] **Step 6: Run resources build**
+
+```bash
+cargo build -p puffer-resources
+```
+
+Expected: SUCCESS.
+
+- [ ] **Step 7: Verify existing registry callers still compile**
+
+```bash
+cargo build -p puffer-cli
+```
+
+Expected: SUCCESS. Existing yaml that doesn't set the field continues to parse (serde default = `None`).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add crates/puffer-provider-registry/src/model.rs \
+        crates/puffer-provider-registry/Cargo.toml \
+        crates/puffer-resources/src/model.rs
+git commit -m "feat(provider-registry): add optional oauth_family to ProviderDescriptor"
+```
+
+---
+
+## Task 2: Bootstrap the `puffer-provider-worldrouter` crate
+
+**Files:**
+- Create: `crates/puffer-provider-worldrouter/Cargo.toml`
+- Create: `crates/puffer-provider-worldrouter/src/lib.rs`
+- Modify: `Cargo.toml` (workspace `members`)
+
+- [ ] **Step 1: Create the crate Cargo.toml**
+
+`crates/puffer-provider-worldrouter/Cargo.toml`:
+
+```toml
+[package]
+name = "puffer-provider-worldrouter"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+anyhow.workspace = true
+base64.workspace = true
+rand = "0.9.2"
+reqwest.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+url = "2.5.7"
+```
+
+No need to depend on `puffer-provider-registry` — this crate only owns the Auth Station auth helpers; the registry-shape conversion lives in `puffer-cli/src/auth_credentials.rs`.
+
+- [ ] **Step 2: Create a stub lib.rs**
+
+`crates/puffer-provider-worldrouter/src/lib.rs`:
+
+```rust
+//! Auth Station OAuth helpers for the `worldrouter` provider.
+//!
+//! Auth Station's `/login` flow returns the final `token` and
+//! `refresh_token` directly in the callback URL. There is no PKCE,
+//! no code exchange. This crate owns URL building, callback
+//! parsing, JWT-payload decoding, and refresh.
+
+mod auth;
+
+pub use auth::{
+    build_login_url, decode_jwt_profile, exchange_jwt_for_api_key,
+    generate_client_state, parse_callback_input, refresh_oauth_token,
+    WorldRouterCallback, WorldRouterJwtProfile, WorldRouterLoginConfig,
+    WorldRouterOAuthCredentials, WORLDROUTER_AUTH_BASE_URL,
+    WORLDROUTER_AUTH_URL_OVERRIDE_ENV, WORLDROUTER_CALLBACK_PATH,
+    WORLDROUTER_CALLBACK_PORT, WORLDROUTER_DEFAULT_REDIRECT_URI,
+};
+```
+
+- [ ] **Step 3: Create an empty auth.rs so the crate compiles**
+
+`crates/puffer-provider-worldrouter/src/auth.rs`:
+
+```rust
+//! Auth Station login URL building, callback parsing, JWT decoding.
+```
+
+- [ ] **Step 4: Register the crate in the workspace**
+
+In root `Cargo.toml`, find the `members = [` block and add `"crates/puffer-provider-worldrouter",` keeping the list alphabetically grouped (insert right after `"crates/puffer-provider-registry",`).
+
+- [ ] **Step 5: Build empty crate to confirm Cargo wiring**
+
+```bash
+cargo build -p puffer-provider-worldrouter
+```
+
+Expected: builds with "unresolved import" errors because lib.rs re-exports items that don't exist. That's a problem — the next task implements them. For this commit, **temporarily comment out the re-exports** in lib.rs so it builds; we'll restore them in Task 3 step 6.
+
+Replace lib.rs body for now:
+
+```rust
+//! Auth Station OAuth helpers for the `worldrouter` provider.
+//!
+//! Auth Station's `/login` flow returns the final `token` and
+//! `refresh_token` directly in the callback URL. There is no PKCE,
+//! no code exchange. This crate owns URL building, callback
+//! parsing, JWT-payload decoding, and refresh.
+
+#![allow(dead_code)]
+
+mod auth;
+```
+
+```bash
+cargo build -p puffer-provider-worldrouter
+```
+
+Expected: SUCCESS (empty crate).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/puffer-provider-worldrouter Cargo.toml
+git commit -m "feat(provider-worldrouter): bootstrap empty crate"
+```
+
+---
+
+## Task 3: Implement `WorldRouterLoginConfig` + `build_login_url`
+
+**Files:**
+- Modify: `crates/puffer-provider-worldrouter/src/auth.rs`
+- Modify: `crates/puffer-provider-worldrouter/src/lib.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `crates/puffer-provider-worldrouter/src/auth.rs`:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_login_url_contains_redirect_uri_and_client_state() {
+        let config = WorldRouterLoginConfig {
+            auth_base_url: "https://auth-worldrouter.vercel.app".to_string(),
+            redirect_uri: "http://127.0.0.1:1456/callback".to_string(),
+            client_state: "state-xyz".to_string(),
+        };
+        let url = build_login_url(&config);
+        assert!(url.starts_with("https://auth-worldrouter.vercel.app/login?"));
+        assert!(url.contains("redirect_uri=http%3A%2F%2F127.0.0.1%3A1456%2Fcallback"));
+        assert!(url.contains("client_state=state-xyz"));
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cargo test -p puffer-provider-worldrouter build_login_url
+```
+
+Expected: FAIL — `WorldRouterLoginConfig` / `build_login_url` do not exist.
+
+- [ ] **Step 3: Implement the types and function**
+
+Replace the body of `crates/puffer-provider-worldrouter/src/auth.rs` (above the test module) with:
+
+```rust
+//! Auth Station login URL building, callback parsing, JWT decoding.
+
+use anyhow::{anyhow, Context, Result};
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine as _;
+use rand::RngCore;
+use reqwest::blocking::Client;
+use serde::Deserialize;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Default Auth Station base URL (Sandbox). Production is
+/// `https://auth.worldrouter.ai`. The env var named by
+/// [`WORLDROUTER_AUTH_URL_OVERRIDE_ENV`] overrides this at runtime.
+pub const WORLDROUTER_AUTH_BASE_URL: &str = "https://auth-worldrouter.vercel.app";
+
+/// Env var name that overrides the Auth Station base URL.
+pub const WORLDROUTER_AUTH_URL_OVERRIDE_ENV: &str = "PUFFER_WORLDROUTER_AUTH_URL";
+
+/// Fixed loopback callback path used by Puffer desktop. The auth
+/// team must allow-list the full URI on both Sandbox and Production.
+pub const WORLDROUTER_CALLBACK_PATH: &str = "/callback";
+
+/// Fixed loopback callback port used by Puffer desktop. See
+/// [`WORLDROUTER_CALLBACK_PATH`] for the path component.
+pub const WORLDROUTER_CALLBACK_PORT: u16 = 1456;
+
+/// Concatenated fixed loopback redirect URI.
+pub const WORLDROUTER_DEFAULT_REDIRECT_URI: &str = "http://127.0.0.1:1456/callback";
+
+/// Parameters needed to build an Auth Station login URL.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WorldRouterLoginConfig {
+    /// Base URL of Auth Station, no trailing slash.
+    pub auth_base_url: String,
+    /// Full redirect URI for the desktop callback listener.
+    pub redirect_uri: String,
+    /// Opaque random value used as the CSRF guard.
+    pub client_state: String,
+}
+
+impl Default for WorldRouterLoginConfig {
+    fn default() -> Self {
+        let auth_base_url = std::env::var(WORLDROUTER_AUTH_URL_OVERRIDE_ENV)
+            .ok()
+            .filter(|value| !value.trim().is_empty())
+            .unwrap_or_else(|| WORLDROUTER_AUTH_BASE_URL.to_string());
+        Self {
+            auth_base_url,
+            redirect_uri: WORLDROUTER_DEFAULT_REDIRECT_URI.to_string(),
+            client_state: generate_client_state(),
+        }
+    }
+}
+
+/// Generates an opaque url-safe random `client_state`.
+pub fn generate_client_state() -> String {
+    let mut bytes = [0_u8; 32];
+    rand::rng().fill_bytes(&mut bytes);
+    URL_SAFE_NO_PAD.encode(bytes)
+}
+
+/// Builds the Auth Station `/login` URL for the given config.
+pub fn build_login_url(config: &WorldRouterLoginConfig) -> String {
+    let trimmed = config.auth_base_url.trim_end_matches('/');
+    let mut url = url::Url::parse(&format!("{trimmed}/login"))
+        .expect("auth_base_url must be a valid URL");
+    url.query_pairs_mut()
+        .append_pair("redirect_uri", &config.redirect_uri)
+        .append_pair("client_state", &config.client_state);
+    url.to_string()
+}
+```
+
+- [ ] **Step 4: Restore the public re-exports in lib.rs**
+
+Replace `crates/puffer-provider-worldrouter/src/lib.rs`:
+
+```rust
+//! Auth Station OAuth helpers for the `worldrouter` provider.
+//!
+//! Auth Station's `/login` flow returns the final `token` and
+//! `refresh_token` directly in the callback URL. There is no PKCE,
+//! no code exchange. This crate owns URL building, callback
+//! parsing, JWT-payload decoding, and refresh.
+
+mod auth;
+
+pub use auth::{
+    build_login_url, generate_client_state, WorldRouterLoginConfig,
+    WORLDROUTER_AUTH_BASE_URL, WORLDROUTER_AUTH_URL_OVERRIDE_ENV,
+    WORLDROUTER_CALLBACK_PATH, WORLDROUTER_CALLBACK_PORT,
+    WORLDROUTER_DEFAULT_REDIRECT_URI,
+};
+```
+
+(Other re-exports — `parse_callback_input`, `decode_jwt_profile`, `refresh_oauth_token`, `exchange_jwt_for_api_key`, `WorldRouterCallback`, `WorldRouterJwtProfile`, `WorldRouterOAuthCredentials` — are added in later tasks.)
+
+- [ ] **Step 5: Run test**
+
+```bash
+cargo test -p puffer-provider-worldrouter build_login_url
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/puffer-provider-worldrouter/src
+git commit -m "feat(provider-worldrouter): implement build_login_url + config"
+```
+
+---
+
+## Task 4: Implement `parse_callback_input` + `WorldRouterCallback`
+
+**Files:**
+- Modify: `crates/puffer-provider-worldrouter/src/auth.rs`
+- Modify: `crates/puffer-provider-worldrouter/src/lib.rs`
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to the existing test module in `auth.rs`:
+
+```rust
+    #[test]
+    fn parse_callback_input_extracts_token_refresh_state() {
+        let parsed = parse_callback_input(
+            "http://127.0.0.1:1456/callback?token=acc&refresh_token=ref&state=xyz",
+        );
+        assert_eq!(parsed.token.as_deref(), Some("acc"));
+        assert_eq!(parsed.refresh_token.as_deref(), Some("ref"));
+        assert_eq!(parsed.state.as_deref(), Some("xyz"));
+        assert!(parsed.error.is_none());
+    }
+
+    #[test]
+    fn parse_callback_input_extracts_error() {
+        let parsed = parse_callback_input(
+            "http://127.0.0.1:1456/callback?error=invalid_state&error_description=bad+state&state=xyz",
+        );
+        assert_eq!(parsed.error.as_deref(), Some("invalid_state"));
+        assert_eq!(parsed.error_description.as_deref(), Some("bad state"));
+        assert!(parsed.token.is_none());
+    }
+
+    #[test]
+    fn parse_callback_input_handles_raw_query_string() {
+        let parsed = parse_callback_input("token=acc&state=xyz");
+        assert_eq!(parsed.token.as_deref(), Some("acc"));
+        assert_eq!(parsed.state.as_deref(), Some("xyz"));
+    }
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cargo test -p puffer-provider-worldrouter parse_callback_input
+```
+
+Expected: FAIL — function does not exist.
+
+- [ ] **Step 3: Implement the types and function**
+
+Append below `build_login_url` (before the `#[cfg(test)]` block):
+
+```rust
+/// Parsed callback fields. Each field is `None` when its parameter
+/// was absent from the callback URL.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct WorldRouterCallback {
+    pub token: Option<String>,
+    pub refresh_token: Option<String>,
+    pub state: Option<String>,
+    pub error: Option<String>,
+    pub error_description: Option<String>,
+}
+
+/// Extracts `token`, `refresh_token`, `state`, `error`, and
+/// `error_description` from a callback URL or raw query string.
+pub fn parse_callback_input(input: &str) -> WorldRouterCallback {
+    let trimmed = input.trim();
+    if trimmed.is_empty() {
+        return WorldRouterCallback::default();
+    }
+    let mut callback = WorldRouterCallback::default();
+    let pairs: Box<dyn Iterator<Item = (String, String)>> =
+        if let Ok(url) = url::Url::parse(trimmed) {
+            Box::new(
+                url.query_pairs()
+                    .into_owned()
+                    .collect::<Vec<_>>()
+                    .into_iter(),
+            )
+        } else {
+            Box::new(
+                url::form_urlencoded::parse(trimmed.as_bytes())
+                    .into_owned()
+                    .collect::<Vec<_>>()
+                    .into_iter(),
+            )
+        };
+    for (key, value) in pairs {
+        match key.as_str() {
+            "token" => callback.token = Some(value),
+            "refresh_token" => callback.refresh_token = Some(value),
+            "state" => callback.state = Some(value),
+            "error" => callback.error = Some(value),
+            "error_description" => callback.error_description = Some(value),
+            _ => {}
+        }
+    }
+    callback
+}
+```
+
+- [ ] **Step 4: Add re-exports**
+
+In `crates/puffer-provider-worldrouter/src/lib.rs`, extend the `pub use` block:
+
+```rust
+pub use auth::{
+    build_login_url, generate_client_state, parse_callback_input,
+    WorldRouterCallback, WorldRouterLoginConfig,
+    WORLDROUTER_AUTH_BASE_URL, WORLDROUTER_AUTH_URL_OVERRIDE_ENV,
+    WORLDROUTER_CALLBACK_PATH, WORLDROUTER_CALLBACK_PORT,
+    WORLDROUTER_DEFAULT_REDIRECT_URI,
+};
+```
+
+- [ ] **Step 5: Run tests**
+
+```bash
+cargo test -p puffer-provider-worldrouter parse_callback_input
+```
+
+Expected: PASS (3 tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/puffer-provider-worldrouter/src
+git commit -m "feat(provider-worldrouter): parse callback URL into typed fields"
+```
+
+---
+
+## Task 5: Implement `decode_jwt_profile`
+
+**Files:**
+- Modify: `crates/puffer-provider-worldrouter/src/auth.rs`
+- Modify: `crates/puffer-provider-worldrouter/src/lib.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to the test module in `auth.rs`:
+
+```rust
+    #[test]
+    fn decode_jwt_profile_reads_sub_email_name() {
+        let payload = serde_json::json!({
+            "sub": "user_01ABC",
+            "email": "dev@example.com",
+            "name": "Dev User",
+        });
+        let encoded = URL_SAFE_NO_PAD.encode(payload.to_string());
+        let token = format!("header.{encoded}.sig");
+        let profile = decode_jwt_profile(&token);
+        assert_eq!(profile.sub.as_deref(), Some("user_01ABC"));
+        assert_eq!(profile.email.as_deref(), Some("dev@example.com"));
+        assert_eq!(profile.name.as_deref(), Some("Dev User"));
+    }
+
+    #[test]
+    fn decode_jwt_profile_handles_malformed_token() {
+        let profile = decode_jwt_profile("not-a-jwt");
+        assert!(profile.sub.is_none());
+        assert!(profile.email.is_none());
+        assert!(profile.name.is_none());
+    }
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cargo test -p puffer-provider-worldrouter decode_jwt_profile
+```
+
+Expected: FAIL — function does not exist.
+
+- [ ] **Step 3: Implement**
+
+Append below `parse_callback_input` (before the test module):
+
+```rust
+/// Decoded JWT profile fields, best-effort.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct WorldRouterJwtProfile {
+    pub sub: Option<String>,
+    pub email: Option<String>,
+    pub name: Option<String>,
+}
+
+/// Decodes `sub` / `email` / `name` from the access token JWT
+/// payload. Any decode/parse failure yields an empty profile.
+pub fn decode_jwt_profile(access_token: &str) -> WorldRouterJwtProfile {
+    let Some(payload_b64) = access_token.split('.').nth(1) else {
+        return WorldRouterJwtProfile::default();
+    };
+    let Ok(payload_bytes) = URL_SAFE_NO_PAD.decode(payload_b64.as_bytes()) else {
+        return WorldRouterJwtProfile::default();
+    };
+    let Ok(value) = serde_json::from_slice::<serde_json::Value>(&payload_bytes) else {
+        return WorldRouterJwtProfile::default();
+    };
+    WorldRouterJwtProfile {
+        sub: value
+            .get("sub")
+            .and_then(serde_json::Value::as_str)
+            .map(ToString::to_string),
+        email: value
+            .get("email")
+            .and_then(serde_json::Value::as_str)
+            .map(ToString::to_string),
+        name: value
+            .get("name")
+            .and_then(serde_json::Value::as_str)
+            .map(ToString::to_string),
+    }
+}
+```
+
+- [ ] **Step 4: Add re-exports**
+
+Extend the `pub use` block in `lib.rs`:
+
+```rust
+pub use auth::{
+    build_login_url, decode_jwt_profile, generate_client_state,
+    parse_callback_input, WorldRouterCallback, WorldRouterJwtProfile,
+    WorldRouterLoginConfig, WORLDROUTER_AUTH_BASE_URL,
+    WORLDROUTER_AUTH_URL_OVERRIDE_ENV, WORLDROUTER_CALLBACK_PATH,
+    WORLDROUTER_CALLBACK_PORT, WORLDROUTER_DEFAULT_REDIRECT_URI,
+};
+```
+
+- [ ] **Step 5: Run tests**
+
+```bash
+cargo test -p puffer-provider-worldrouter decode_jwt_profile
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/puffer-provider-worldrouter/src
+git commit -m "feat(provider-worldrouter): decode JWT profile (sub/email/name)"
+```
+
+---
+
+## Task 6: Implement `WorldRouterOAuthCredentials` + `refresh_oauth_token` + `exchange_jwt_for_api_key` stub
+
+**Files:**
+- Modify: `crates/puffer-provider-worldrouter/src/auth.rs`
+- Modify: `crates/puffer-provider-worldrouter/src/lib.rs`
+
+- [ ] **Step 1: Write the failing test (for the stub)**
+
+Append to the test module:
+
+```rust
+    #[test]
+    fn exchange_jwt_for_api_key_is_a_placeholder() {
+        let result = exchange_jwt_for_api_key("any.access.token");
+        assert!(result.is_err());
+        let err = format!("{}", result.unwrap_err());
+        assert!(err.contains("not yet implemented"));
+    }
+```
+
+(`refresh_oauth_token` hits the network; we don't write a network-level test in this crate. Coverage of the wire shape lives in the daemon integration smoke test in Task 11.)
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cargo test -p puffer-provider-worldrouter exchange_jwt_for_api_key
+```
+
+Expected: FAIL — function doesn't exist.
+
+- [ ] **Step 3: Implement types + functions**
+
+Append below `decode_jwt_profile`:
+
+```rust
+/// Persisted Auth Station credentials for the worldrouter provider.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WorldRouterOAuthCredentials {
+    pub access_token: String,
+    pub refresh_token: String,
+    pub expires_at_ms: u64,
+    pub sub: Option<String>,
+    pub email: Option<String>,
+    pub name: Option<String>,
+}
+
+/// Exchanges a stored refresh token for a new access token via
+/// `POST <auth>/token/refresh`. Preserves the existing
+/// refresh_token/profile fields when the upstream response does not
+/// return them (Auth Station does not rotate refresh tokens, and
+/// `/token/refresh` returns only `{ "token": ... }`).
+pub fn refresh_oauth_token(
+    refresh_token: &str,
+    auth_base_url: Option<&str>,
+) -> Result<WorldRouterOAuthCredentials> {
+    let base = auth_base_url
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToString::to_string)
+        .unwrap_or_else(|| {
+            std::env::var(WORLDROUTER_AUTH_URL_OVERRIDE_ENV)
+                .ok()
+                .filter(|value| !value.trim().is_empty())
+                .unwrap_or_else(|| WORLDROUTER_AUTH_BASE_URL.to_string())
+        });
+    let url = format!("{}/token/refresh", base.trim_end_matches('/'));
+    let response = Client::new()
+        .post(&url)
+        .json(&serde_json::json!({ "refresh_token": refresh_token }))
+        .send()
+        .context("failed to send worldrouter refresh request")?;
+    let status = response.status();
+    let payload: RefreshResponse = response
+        .json()
+        .context("failed to parse worldrouter refresh response")?;
+    if !status.is_success() {
+        return Err(anyhow!(
+            "worldrouter token refresh failed with status {status}: {}",
+            payload.error.unwrap_or_default()
+        ));
+    }
+    let access_token = payload
+        .token
+        .ok_or_else(|| anyhow!("worldrouter refresh response missing token"))?;
+    let profile = decode_jwt_profile(&access_token);
+    Ok(WorldRouterOAuthCredentials {
+        access_token,
+        refresh_token: refresh_token.to_string(),
+        expires_at_ms: now_ms() + 24 * 3600 * 1000,
+        sub: profile.sub,
+        email: profile.email,
+        name: profile.name,
+    })
+}
+
+/// Exchanges an Auth Station JWT for an inference API key.
+///
+/// **TODO (waiting on worldrouter backend):** the endpoint and
+/// request shape are not yet finalized. Once defined, this function
+/// will `POST <worldrouter>/api/v1/keys/exchange` (or whatever the
+/// backend picks) with `Authorization: Bearer <access_token>` and
+/// return the `api_key` string. The login handler will then upgrade
+/// the stored credential to an `ApiKey { key }` variant.
+pub fn exchange_jwt_for_api_key(_access_token: &str) -> Result<String> {
+    Err(anyhow!(
+        "worldrouter JWT-to-api-key exchange is not yet implemented; \
+         paste your WorldRouter API key for now"
+    ))
+}
+
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+#[derive(Debug, Deserialize)]
+struct RefreshResponse {
+    #[serde(default)]
+    token: Option<String>,
+    #[serde(default)]
+    error: Option<String>,
+}
+```
+
+- [ ] **Step 4: Extend re-exports in lib.rs**
+
+Final `pub use` block:
+
+```rust
+pub use auth::{
+    build_login_url, decode_jwt_profile, exchange_jwt_for_api_key,
+    generate_client_state, parse_callback_input, refresh_oauth_token,
+    WorldRouterCallback, WorldRouterJwtProfile, WorldRouterLoginConfig,
+    WorldRouterOAuthCredentials, WORLDROUTER_AUTH_BASE_URL,
+    WORLDROUTER_AUTH_URL_OVERRIDE_ENV, WORLDROUTER_CALLBACK_PATH,
+    WORLDROUTER_CALLBACK_PORT, WORLDROUTER_DEFAULT_REDIRECT_URI,
+};
+```
+
+- [ ] **Step 5: Run all crate tests**
+
+```bash
+cargo test -p puffer-provider-worldrouter
+```
+
+Expected: PASS (build_login_url, parse_callback_input x3, decode_jwt_profile x2, exchange_jwt_for_api_key — at least 7 tests pass).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/puffer-provider-worldrouter/src
+git commit -m "feat(provider-worldrouter): add credentials + refresh + exchange stub"
+```
+
+---
+
+## Task 7: Add `bind_localhost_port` to `authflow.rs`
+
+**Files:**
+- Modify: `crates/puffer-cli/src/authflow.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to the existing `tests` module in `crates/puffer-cli/src/authflow.rs`:
+
+```rust
+    #[test]
+    fn bind_localhost_port_uses_requested_port() {
+        // Find a free port by binding 0, then drop and rebind on it.
+        let probe = TcpListener::bind(("127.0.0.1", 0)).unwrap();
+        let port = probe.local_addr().unwrap().port();
+        drop(probe);
+        let listener = CallbackListener::bind_localhost_port("/callback", port)
+            .expect("bind_localhost_port succeeds on a free port");
+        let redirect_uri = listener.redirect_uri();
+        assert_eq!(
+            redirect_uri,
+            format!("http://127.0.0.1:{port}/callback")
+        );
+    }
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cargo test -p puffer-cli authflow::tests::bind_localhost_port
+```
+
+Expected: FAIL — method does not exist.
+
+- [ ] **Step 3: Implement**
+
+In `crates/puffer-cli/src/authflow.rs`, inside `impl CallbackListener`, right after `bind_localhost`:
+
+```rust
+    /// Binds a fixed loopback port. Used for redirect URIs that must
+    /// match an Auth Station allow-list entry exactly (such as the
+    /// worldrouter provider). Returns an error if the port is in use.
+    pub(crate) fn bind_localhost_port(path: &str, port: u16) -> Result<Self> {
+        let listener = TcpListener::bind(("127.0.0.1", port)).with_context(|| {
+            format!("failed to bind callback listener on 127.0.0.1:{port} for {path}")
+        })?;
+        listener.set_nonblocking(true)?;
+        Ok(Self {
+            listener,
+            host: "127.0.0.1".to_string(),
+            port,
+            expected_path: path.to_string(),
+            redirect_uri: format!("http://127.0.0.1:{port}{path}"),
+        })
+    }
+```
+
+- [ ] **Step 4: Run test**
+
+```bash
+cargo test -p puffer-cli authflow::tests::bind_localhost_port
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/puffer-cli/src/authflow.rs
+git commit -m "feat(cli/authflow): add bind_localhost_port for fixed-port callbacks"
+```
+
+---
+
+## Task 8: Wire `OauthFamily::WorldRouter` into `auth_provider.rs`
+
+**Files:**
+- Modify: `crates/puffer-cli/Cargo.toml`
+- Modify: `crates/puffer-cli/src/auth_provider.rs`
+
+- [ ] **Step 1: Add `puffer-provider-worldrouter` as a dep of puffer-cli**
+
+In `crates/puffer-cli/Cargo.toml`, find the `[dependencies]` block where the other `puffer-provider-*` entries live and add (alphabetically near `puffer-provider-openai`):
+
+```toml
+puffer-provider-worldrouter = { path = "../puffer-provider-worldrouter" }
+```
+
+- [ ] **Step 2: Write the failing test**
+
+Append to the `tests` module in `crates/puffer-cli/src/auth_provider.rs`:
+
+```rust
+    #[test]
+    fn oauth_family_uses_explicit_oauth_family_field() {
+        let mut providers = ProviderRegistry::new();
+        let mut descriptor = provider(
+            "worldrouter",
+            "openai-completions",
+            vec![AuthMode::OAuth, AuthMode::ApiKey],
+        );
+        descriptor.oauth_family = Some("worldrouter".to_string());
+        providers.register(descriptor);
+        assert_eq!(
+            oauth_family_for_provider(&providers, "worldrouter"),
+            Some(OauthFamily::WorldRouter)
+        );
+    }
+
+    #[test]
+    fn oauth_family_falls_back_to_default_api_when_field_unset() {
+        let mut providers = ProviderRegistry::new();
+        providers.register(provider(
+            "custom-openai",
+            "openai-completions",
+            vec![AuthMode::OAuth],
+        ));
+        assert_eq!(
+            oauth_family_for_provider(&providers, "custom-openai"),
+            Some(OauthFamily::OpenAi)
+        );
+    }
+```
+
+Also update the existing `provider` test helper at the bottom of `auth_provider.rs` to set `oauth_family: None,` in the `ProviderDescriptor` literal. (Without this, the helper won't compile after Task 1 added the field.)
+
+```rust
+            chat_completions_path: None,
+            oauth_family: None,
+```
+
+- [ ] **Step 3: Run test to verify it fails**
+
+```bash
+cargo test -p puffer-cli auth_provider::tests::oauth_family_uses_explicit
+```
+
+Expected: FAIL — `OauthFamily::WorldRouter` does not exist.
+
+- [ ] **Step 4: Add the enum variant and dispatch logic**
+
+In `crates/puffer-cli/src/auth_provider.rs`:
+
+1. Extend `OauthFamily`:
+
+```rust
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum OauthFamily {
+    Anthropic,
+    OpenAi,
+    WorldRouter,
+}
+```
+
+2. Replace the body of `oauth_family_for_provider`:
+
+```rust
+pub(crate) fn oauth_family_for_provider(
+    providers: &ProviderRegistry,
+    provider_id: &str,
+) -> Option<OauthFamily> {
+    let provider = providers.provider(provider_id)?;
+    if !provider.auth_modes.contains(&AuthMode::OAuth) {
+        return None;
+    }
+    if let Some(family) = provider.oauth_family.as_deref() {
+        return match family {
+            "openai" => Some(OauthFamily::OpenAi),
+            "anthropic" => Some(OauthFamily::Anthropic),
+            "worldrouter" => Some(OauthFamily::WorldRouter),
+            _ => None,
+        };
+    }
+    match provider.default_api.as_str() {
+        "openai-responses"
+        | "openai-completions"
+        | "azure-openai-responses"
+        | "openai-codex-responses" => Some(OauthFamily::OpenAi),
+        "anthropic-messages" => Some(OauthFamily::Anthropic),
+        _ => None,
+    }
+}
+```
+
+3. Add a `WorldRouter` arm to both `oauth_start_bundle_for_provider` and `oauth_login_bundle_for_provider`. Insert after the `Anthropic` arm in each:
+
+```rust
+        Some(OauthFamily::WorldRouter) => {
+            let mut config = puffer_provider_worldrouter::WorldRouterLoginConfig::default();
+            // for oauth_login_bundle_for_provider only: override redirect_uri.
+            // For oauth_start_bundle_for_provider, leave the default (the
+            // fixed loopback URI baked into the crate).
+            // …see step 5 for the exact code.
+            Ok(OauthStartBundle {
+                authorization_url: puffer_provider_worldrouter::build_login_url(&config),
+                automatic_authorization_url: None,
+                verifier: String::new(),
+                state: config.client_state,
+                redirect_uri: config.redirect_uri,
+                manual_redirect_uri: None,
+            })
+        }
+```
+
+- [ ] **Step 5: Apply the exact arms**
+
+For `oauth_start_bundle_for_provider` (no explicit redirect_uri):
+
+```rust
+        Some(OauthFamily::WorldRouter) => {
+            let config = puffer_provider_worldrouter::WorldRouterLoginConfig::default();
+            Ok(OauthStartBundle {
+                authorization_url: puffer_provider_worldrouter::build_login_url(&config),
+                automatic_authorization_url: None,
+                verifier: String::new(),
+                state: config.client_state,
+                redirect_uri: config.redirect_uri,
+                manual_redirect_uri: None,
+            })
+        }
+```
+
+For `oauth_login_bundle_for_provider` (caller provides the bound redirect_uri):
+
+```rust
+        Some(OauthFamily::WorldRouter) => {
+            let config = puffer_provider_worldrouter::WorldRouterLoginConfig {
+                redirect_uri: redirect_uri.to_string(),
+                ..puffer_provider_worldrouter::WorldRouterLoginConfig::default()
+            };
+            Ok(OauthStartBundle {
+                authorization_url: puffer_provider_worldrouter::build_login_url(&config),
+                automatic_authorization_url: None,
+                verifier: String::new(),
+                state: config.client_state,
+                redirect_uri: config.redirect_uri,
+                manual_redirect_uri: None,
+            })
+        }
+```
+
+- [ ] **Step 6: Run tests**
+
+```bash
+cargo test -p puffer-cli auth_provider::tests
+```
+
+Expected: PASS (both new tests + the existing two unchanged).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add crates/puffer-cli/Cargo.toml crates/puffer-cli/src/auth_provider.rs
+git commit -m "feat(cli/auth_provider): dispatch worldrouter OAuth family"
+```
+
+---
+
+## Task 9: Add `to_registry_oauth_credential_worldrouter` helper
+
+**Files:**
+- Modify: `crates/puffer-cli/src/auth_credentials.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Append (or create) a `#[cfg(test)] mod tests` block at the bottom of `auth_credentials.rs`:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use puffer_provider_worldrouter::WorldRouterOAuthCredentials;
+
+    #[test]
+    fn worldrouter_credential_maps_email_and_account_id() {
+        let credential = WorldRouterOAuthCredentials {
+            access_token: "acc".to_string(),
+            refresh_token: "ref".to_string(),
+            expires_at_ms: 42,
+            sub: Some("user_01".to_string()),
+            email: Some("dev@example.com".to_string()),
+            name: Some("Dev".to_string()),
+        };
+        let stored = to_registry_oauth_credential_worldrouter(credential);
+        assert_eq!(stored.access_token, "acc");
+        assert_eq!(stored.refresh_token, "ref");
+        assert_eq!(stored.expires_at_ms, 42);
+        assert_eq!(stored.account_id.as_deref(), Some("user_01"));
+        assert_eq!(stored.email.as_deref(), Some("dev@example.com"));
+    }
+}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cargo test -p puffer-cli auth_credentials::tests::worldrouter_credential
+```
+
+Expected: FAIL — function doesn't exist.
+
+- [ ] **Step 3: Implement**
+
+Append (above the test module) in `crates/puffer-cli/src/auth_credentials.rs`:
+
+```rust
+/// Converts worldrouter OAuth credentials into the registry storage shape.
+/// The Auth Station `sub` claim is stored as `account_id` so the
+/// existing AuthStore reuse path (organization_id, plan_type, etc.)
+/// stays untouched. `name` is intentionally not persisted yet — the
+/// existing `OAuthCredential` shape has no slot for it; if the UI
+/// needs the display name later, we can either reuse `email` or
+/// extend the struct.
+pub(crate) fn to_registry_oauth_credential_worldrouter(
+    credential: puffer_provider_worldrouter::WorldRouterOAuthCredentials,
+) -> puffer_provider_registry::OAuthCredential {
+    puffer_provider_registry::OAuthCredential {
+        access_token: credential.access_token,
+        refresh_token: credential.refresh_token,
+        expires_at_ms: credential.expires_at_ms,
+        account_id: credential.sub,
+        organization_id: None,
+        email: credential.email,
+        plan_type: None,
+        rate_limit_tier: None,
+        scopes: Vec::new(),
+        organization_name: None,
+        organization_role: None,
+        workspace_role: None,
+    }
+}
+```
+
+- [ ] **Step 4: Run test**
+
+```bash
+cargo test -p puffer-cli auth_credentials::tests::worldrouter_credential
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/puffer-cli/src/auth_credentials.rs
+git commit -m "feat(cli/auth_credentials): map worldrouter credential into registry shape"
+```
+
+---
+
+## Task 10: Wire worldrouter into `run_login_flow` (CLI path)
+
+**Files:**
+- Modify: `crates/puffer-cli/src/main.rs`
+
+- [ ] **Step 1: Add imports**
+
+Near the existing `use puffer_provider_openai::{…}` and `use puffer_transport_anthropic::{…}` blocks, add:
+
+```rust
+use puffer_provider_worldrouter::{
+    decode_jwt_profile as decode_worldrouter_jwt_profile,
+    parse_callback_input as parse_worldrouter_callback_input,
+    WorldRouterOAuthCredentials, WORLDROUTER_CALLBACK_PATH, WORLDROUTER_CALLBACK_PORT,
+};
+```
+
+And in the `use crate::auth_credentials::{…}` block (around line 65), add:
+
+```rust
+use crate::auth_credentials::to_registry_oauth_credential_worldrouter;
+```
+
+- [ ] **Step 2: Replace the localhost listener bind in `run_login_flow`**
+
+Currently `run_login_flow` always calls
+`authflow::CallbackListener::bind_localhost("/callback")`. Replace
+the listener-creation block (around line 1017–1021) with:
+
+```rust
+    let callback_listener = if stdin || value.is_some() {
+        None
+    } else if matches!(
+        oauth_family_for_provider(providers, provider),
+        Some(OauthFamily::WorldRouter)
+    ) {
+        Some(authflow::CallbackListener::bind_localhost_port(
+            WORLDROUTER_CALLBACK_PATH,
+            WORLDROUTER_CALLBACK_PORT,
+        )?)
+    } else {
+        Some(authflow::CallbackListener::bind_localhost("/callback")?)
+    };
+```
+
+- [ ] **Step 3: Add the `WorldRouter` arm to the outer `match`**
+
+Inside `run_login_flow`, after the `OauthFamily::Anthropic` arm and before the `None =>` bail, insert:
+
+```rust
+        Some(OauthFamily::WorldRouter) => {
+            let parsed = parse_worldrouter_callback_input(&input);
+            if let Some(err) = parsed.error.as_deref() {
+                let desc = parsed.error_description.as_deref().unwrap_or("");
+                anyhow::bail!("worldrouter login failed: {err} {desc}");
+            }
+            if parsed.state.as_deref() != Some(bundle.state.as_str()) {
+                anyhow::bail!("oauth state mismatch for worldrouter");
+            }
+            let access_token = parsed
+                .token
+                .ok_or_else(|| anyhow::anyhow!("worldrouter callback missing token"))?;
+            let refresh_token = parsed.refresh_token.unwrap_or_default();
+            let profile = decode_worldrouter_jwt_profile(&access_token);
+            let credential = WorldRouterOAuthCredentials {
+                access_token,
+                refresh_token,
+                expires_at_ms: now_ms_for_worldrouter_credential(),
+                sub: profile.sub,
+                email: profile.email,
+                name: profile.name,
+            };
+            auth_store.set_oauth(
+                provider.to_string(),
+                to_registry_oauth_credential_worldrouter(credential),
+            );
+        }
+```
+
+Add this helper near the bottom of `main.rs` (sibling of `resolve_provider_id`):
+
+```rust
+fn now_ms_for_worldrouter_credential() -> u64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|duration| duration.as_millis() as u64 + 24 * 3600 * 1000)
+        .unwrap_or(24 * 3600 * 1000)
+}
+```
+
+- [ ] **Step 4: Run cli build + lib tests**
+
+```bash
+cargo build -p puffer-cli
+cargo test -p puffer-cli --lib
+```
+
+Expected: build + tests SUCCESS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add crates/puffer-cli/src/main.rs
+git commit -m "feat(cli): handle worldrouter OAuth in run_login_flow"
+```
+
+---
+
+## Task 11: Wire worldrouter into the desktop daemon `handle_login_with_oauth`
+
+**Files:**
+- Modify: `crates/puffer-cli/src/daemon.rs`
+
+- [ ] **Step 1: Add imports**
+
+Near the top of `daemon.rs`, in the `use puffer_provider_openai::{…}` import block (or wherever the OpenAI/Anthropic imports live), add:
+
+```rust
+use puffer_provider_worldrouter::{
+    decode_jwt_profile as decode_worldrouter_jwt_profile,
+    parse_callback_input as parse_worldrouter_callback_input,
+    WorldRouterOAuthCredentials, WORLDROUTER_CALLBACK_PATH, WORLDROUTER_CALLBACK_PORT,
+};
+```
+
+In the `use crate::auth_credentials::{…}` block:
+
+```rust
+use crate::auth_credentials::to_registry_oauth_credential_worldrouter;
+```
+
+- [ ] **Step 2: Branch the listener bind**
+
+In `handle_login_with_oauth` (around line 1070), replace:
+
+```rust
+    let listener = crate::authflow::CallbackListener::bind_localhost("/callback")?;
+```
+
+with:
+
+```rust
+    let listener = if matches!(
+        oauth_family_for_provider(&inputs.providers, &provider_id),
+        Some(OauthFamily::WorldRouter)
+    ) {
+        crate::authflow::CallbackListener::bind_localhost_port(
+            WORLDROUTER_CALLBACK_PATH,
+            WORLDROUTER_CALLBACK_PORT,
+        )?
+    } else {
+        crate::authflow::CallbackListener::bind_localhost("/callback")?
+    };
+```
+
+- [ ] **Step 3: Add the `WorldRouter` arm to the `match`**
+
+After the `OauthFamily::Anthropic` arm (around line 1101–1121) and before the `None =>` bail:
+
+```rust
+        Some(OauthFamily::WorldRouter) => {
+            let parsed = parse_worldrouter_callback_input(&callback);
+            if let Some(err) = parsed.error.as_deref() {
+                let desc = parsed.error_description.as_deref().unwrap_or("");
+                anyhow::bail!("worldrouter login failed: {err} {desc}");
+            }
+            if parsed.state.as_deref() != Some(bundle.state.as_str()) {
+                anyhow::bail!("oauth state mismatch for worldrouter");
+            }
+            let access_token = parsed
+                .token
+                .ok_or_else(|| anyhow::anyhow!("worldrouter callback missing token"))?;
+            let refresh_token = parsed.refresh_token.unwrap_or_default();
+            let profile = decode_worldrouter_jwt_profile(&access_token);
+            let expires_at_ms = std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .map(|d| d.as_millis() as u64 + 24 * 3600 * 1000)
+                .unwrap_or(24 * 3600 * 1000);
+            let credential = WorldRouterOAuthCredentials {
+                access_token,
+                refresh_token,
+                expires_at_ms,
+                sub: profile.sub,
+                email: profile.email,
+                name: profile.name,
+            };
+            set_stored_credential(
+                &mut inputs.auth_store,
+                provider_id.to_string(),
+                StoredCredential::OAuth(to_registry_oauth_credential_worldrouter(credential)),
+            );
+        }
+```
+
+- [ ] **Step 4: Build the cli**
+
+```bash
+cargo build -p puffer-cli
+```
+
+Expected: SUCCESS.
+
+- [ ] **Step 5: Run all puffer-cli tests**
+
+```bash
+cargo test -p puffer-cli --lib
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/puffer-cli/src/daemon.rs
+git commit -m "feat(cli/daemon): handle worldrouter OAuth in handle_login_with_oauth"
+```
+
+---
+
+## Task 12: Ship the `worldrouter.yaml` provider resource
+
+**Files:**
+- Create: `resources/providers/worldrouter.yaml`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to the test module in `crates/puffer-resources/src/model.rs` (right next to `zhipu_yaml_parses_with_chat_completions_path_override`):
+
+```rust
+    /// Confirms the bundled `worldrouter.yaml` parses as a
+    /// `ProviderPack` and that the `oauth_family` field round-trips
+    /// through `into_descriptor`. Without this end-to-end wiring the
+    /// runtime would silently fall back to OpenAI OAuth.
+    #[test]
+    fn worldrouter_yaml_parses_with_oauth_family() {
+        let yaml = include_str!("../../../resources/providers/worldrouter.yaml");
+        let pack: ProviderPack = serde_yaml::from_str(yaml).expect("worldrouter.yaml parses");
+        assert_eq!(pack.id, "worldrouter");
+        assert_eq!(pack.oauth_family.as_deref(), Some("worldrouter"));
+        let descriptor = pack.into_descriptor();
+        assert_eq!(descriptor.oauth_family.as_deref(), Some("worldrouter"));
+        assert!(descriptor.auth_modes.contains(&AuthMode::ApiKey));
+        assert!(descriptor.auth_modes.contains(&AuthMode::OAuth));
+    }
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+cargo test -p puffer-resources worldrouter_yaml_parses_with_oauth_family
+```
+
+Expected: FAIL — file doesn't exist (`include_str!` won't compile).
+
+- [ ] **Step 3: Create the yaml**
+
+`resources/providers/worldrouter.yaml`:
+
+```yaml
+id: worldrouter
+display_name: WorldRouter
+base_url: https://inference-api.worldrouter.ai
+default_api: openai-completions
+oauth_family: worldrouter
+auth_modes:
+  - api_key
+  - oauth
+discovery:
+  path: /v1/models
+  response: open_ai_models
+  api: openai-completions
+  context_window: 200000
+  max_output_tokens: 8192
+  supports_reasoning: true
+models:
+  - id: gpt-5
+    display_name: GPT-5 (via WorldRouter)
+    provider: worldrouter
+    api: openai-completions
+    context_window: 200000
+    max_output_tokens: 8192
+    supports_reasoning: true
+```
+
+- [ ] **Step 4: Run test**
+
+```bash
+cargo test -p puffer-resources worldrouter_yaml_parses_with_oauth_family
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Build the cli end-to-end and run all tests**
+
+```bash
+cargo build -p puffer-cli
+cargo test --workspace
+```
+
+Expected: SUCCESS / PASS. Note: tests that hit the network (Auth Station, OpenAI, Anthropic) are not added in this plan; the cited `cargo test --workspace` should remain green with no new network calls.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add resources/providers/worldrouter.yaml crates/puffer-resources/src/model.rs
+git commit -m "feat(resources): ship worldrouter provider yaml"
+```
+
+---
+
+## Task 13: Add desktop visual entry for worldrouter
+
+**Files:**
+- Modify: `apps/puffer-desktop/src/lib/providerVisuals.ts`
+
+- [ ] **Step 1: Inspect existing entries**
+
+```bash
+grep -n "openai\|anthropic\|groq\|kimi\|providerVisual\|export" apps/puffer-desktop/src/lib/providerVisuals.ts | head -40
+```
+
+Read the file once to understand the registration shape (icon path, accent color, fallback handling).
+
+- [ ] **Step 2: Add a `worldrouter` entry**
+
+Match the shape used by existing providers. If entries are keyed by provider id in a record, insert (alphabetically):
+
+```typescript
+  worldrouter: {
+    icon: "/icons/providers/worldrouter.svg", // or use the existing generic fallback
+    accent: "#1f6feb",
+    displayName: "WorldRouter",
+  },
+```
+
+If your repo doesn't ship a `worldrouter.svg`, **use the existing fallback icon** rather than fabricating an asset. Pick whatever the file already does for unknown providers (likely a default monogram or a tinted placeholder). Do not create new SVG/PNG files in this task — the design says "designer can replace later".
+
+- [ ] **Step 3: Smoke-build the frontend**
+
+```bash
+cd apps/puffer-desktop
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+Expected: `svelte-check` reports zero errors related to your edit. (Pre-existing warnings unrelated to worldrouter are fine.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/puffer-desktop/src/lib/providerVisuals.ts
+git commit -m "feat(desktop): register worldrouter provider visuals"
+```
+
+---
+
+## Task 14: Write per-component update specs
+
+**Files:**
+- Create: `specs/puffer-provider-worldrouter/00.md`
+- Create: `specs/puffer-provider-registry/06.md`
+- Create: `specs/puffer-cli/<next>.md` (use the next free `NN.md`, list the directory first)
+- Create: `specs/puffer-resources/<next>.md`
+- Create: `specs/puffer-desktop/<next>.md`
+
+- [ ] **Step 1: Determine the next free numeric prefix for each component**
+
+```bash
+ls specs/puffer-cli | tail
+ls specs/puffer-resources | tail
+ls specs/puffer-desktop | tail
+```
+
+Use the next unused two-digit prefix per AGENTS.md ("do not overwrite prior numbered specs").
+
+- [ ] **Step 2: Write each spec**
+
+Each file is ≤ 60 lines, follows the existing terse style (see `specs/puffer-provider-openai/01.md`):
+
+`specs/puffer-provider-worldrouter/00.md`:
+
+```markdown
+# WorldRouter Provider Crate
+
+## Summary
+- New crate `puffer-provider-worldrouter` owning the Auth Station login flow for the `worldrouter` provider.
+- Auth Station returns final `token` and `refresh_token` directly in the callback URL; this crate models that flow (no PKCE, no code exchange).
+
+## Surface
+- `build_login_url(&WorldRouterLoginConfig) -> String`
+- `parse_callback_input(&str) -> WorldRouterCallback`
+- `decode_jwt_profile(&str) -> WorldRouterJwtProfile`
+- `refresh_oauth_token(&str, Option<&str>) -> Result<WorldRouterOAuthCredentials>`
+- `exchange_jwt_for_api_key(&str) -> Result<String>` — TODO stub, waits on worldrouter backend
+
+## Configuration
+- Default Auth Station URL: `https://auth-worldrouter.vercel.app` (Sandbox).
+- Override via env var `PUFFER_WORLDROUTER_AUTH_URL`.
+- Fixed loopback redirect: `http://127.0.0.1:1456/callback`.
+
+## Compatibility
+- The fixed redirect URI must be allow-listed in Auth Station `ALLOWED_REDIRECT_ORIGINS` on both Sandbox and Production.
+- JWT-to-api-key exchange is intentionally a stub; until the backend endpoint lands, the OAuth path does not yield an inference-usable credential. Users still must paste an API key.
+```
+
+`specs/puffer-provider-registry/06.md`:
+
+```markdown
+# Optional `oauth_family` on ProviderDescriptor
+
+## Summary
+- `ProviderDescriptor` gains `oauth_family: Option<String>`.
+- When `None`, callers infer the OAuth family from `default_api` (no behavior change for existing yaml).
+- When `Some`, callers dispatch directly to the named family. Known values today: `openai`, `anthropic`, `worldrouter`.
+
+## Compatibility
+- Default value preserves every existing provider yaml.
+- `ProviderPack` (in `puffer-resources`) mirrors the field and threads it through `into_descriptor`.
+```
+
+`specs/puffer-cli/<next>.md` (worldrouter OAuth dispatch):
+
+```markdown
+# WorldRouter OAuth Dispatch
+
+## Summary
+- `OauthFamily` grows a `WorldRouter` variant.
+- `oauth_family_for_provider` prefers `descriptor.oauth_family` when set, otherwise falls back to `default_api`.
+- `oauth_login_bundle_for_provider` builds the bundle from `WorldRouterLoginConfig`; `verifier` is empty (no PKCE), `automatic_authorization_url` is `None`.
+- `handle_login_with_oauth` (daemon) and `run_login_flow` (cli) both gain a `WorldRouter` arm: parse callback, verify `state`, decode JWT for `sub`/`email`/`name`, store as `StoredCredential::OAuth`.
+- `CallbackListener::bind_localhost_port` lets the daemon bind the fixed `127.0.0.1:1456` Auth-Station-whitelist port.
+
+## Compatibility
+- Existing OpenAI / Anthropic flows are unchanged (`oauth_family` unset → falls back to `default_api` map).
+- `WorldRouterOAuthCredentials.name` is not yet persisted (no slot on `OAuthCredential`); only `sub`/`email` survive into the registry shape.
+```
+
+`specs/puffer-resources/<next>.md`:
+
+```markdown
+# WorldRouter Provider Yaml
+
+## Summary
+- Bundled `resources/providers/worldrouter.yaml` adds the `worldrouter` provider entry.
+- `default_api: openai-completions` (inference goes through the existing OpenAI chat-completions transport).
+- `oauth_family: worldrouter` opts into the new login dispatch.
+- `auth_modes: [api_key, oauth]` exposes both LoginView paths.
+- Model catalog is seeded minimally; `/v1/models` discovery populates the rest at runtime.
+
+## Compatibility
+- Pure addition; no existing yaml is modified.
+```
+
+`specs/puffer-desktop/<next>.md`:
+
+```markdown
+# WorldRouter Visuals
+
+## Summary
+- `providerVisuals.ts` registers a `worldrouter` entry (display name + accent).
+- No bespoke icon ships in this change; the fallback icon is reused until design provides one.
+
+## Compatibility
+- LoginView's generic OAuth / api_key surface needs no component change.
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add specs/puffer-provider-worldrouter specs/puffer-provider-registry \
+        specs/puffer-cli specs/puffer-resources specs/puffer-desktop
+git commit -m "docs(specs): document worldrouter provider integration"
+```
+
+---
+
+## Task 15: Final verification
+
+- [ ] **Step 1: Workspace test**
+
+```bash
+cargo test --workspace
+```
+
+Expected: all tests green, including the new worldrouter tests and the resource yaml parse test.
+
+- [ ] **Step 2: Workspace build**
+
+```bash
+cargo build --workspace
+```
+
+Expected: SUCCESS.
+
+- [ ] **Step 3: Desktop typecheck**
+
+```bash
+cd apps/puffer-desktop
+pnpm check
+```
+
+Expected: no new errors. (Pre-existing warnings are out of scope.)
+
+- [ ] **Step 4: Manual smoke (optional, requires daemon)**
+
+If a daemon is reachable and `http://127.0.0.1:1456/callback` is allow-listed:
+
+1. Start the daemon: `cargo run -p puffer-cli -- daemon`
+2. Open the desktop app, navigate to Login screen.
+3. Find the **WorldRouter** card.
+4. Click "Connect with OAuth".
+5. Verify the browser opens `https://auth-worldrouter.vercel.app/login?redirect_uri=http://127.0.0.1:1456/callback&client_state=...`
+6. Sign in. Browser should redirect to a success page.
+7. Confirm `~/.config/puffer/auth.json` (or equivalent platform path) shows a `worldrouter` entry with `kind: oauth`.
+8. Paste a real WorldRouter API key in the WorldRouter card too — verify the stored credential flips to `kind: api_key`.
+
+If the manual smoke fails because the redirect URI is not allow-listed yet, **that is the expected failure mode** until the auth maintainer adds `http://127.0.0.1:1456/callback` to `ALLOWED_REDIRECT_ORIGINS` on Sandbox + Production. Note the failure mode in the PR description.
+
+- [ ] **Step 5: Final commit (only if any clean-up edits were needed)**
+
+```bash
+git status
+# If no further changes, skip. Otherwise:
+git add -p
+git commit -m "chore(worldrouter): verification follow-ups"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- §3 architecture diagram → Tasks 7, 8, 10, 11
+- §4 provider yaml → Task 12
+- §5 ProviderDescriptor field → Task 1
+- §6 new crate surface → Tasks 2–6
+- §7 daemon login dispatch + `bind_localhost_port` → Tasks 7, 11
+- §8 TODO JWT→api_key + UI banner — Task 6 (stub) + Task 13 (visuals). The visible banner copy described in §8 of the spec is currently surfaced by `statusMessage = "Connected to worldrouter."` plus the user manually pasting an api_key when ready. Adding a worldrouter-specific banner above the OAuth button is **deferred** (it requires LoginView changes, which the spec explicitly said were "no LoginView component change needed"). If the user wants a banner, raise it during plan review.
+- §9 desktop UI → Task 13
+- §10 tests → Tasks 1, 3, 4, 5, 6, 7, 8, 9, 12 each ship the tests they own
+- §11 per-component specs → Task 14
+- §12 pre-shipping checklist → noted in Task 15 step 4
+
+**Placeholder scan:** all code blocks contain literal source; the only "TODO" lives in `exchange_jwt_for_api_key`, which is intentional and tested (asserts the function `bail!`s with "not yet implemented"). The `<next>.md` filename placeholder in Task 14 is resolved at step 1 by listing the directory.
+
+**Type consistency:**
+- `WorldRouterLoginConfig` / `WorldRouterCallback` / `WorldRouterJwtProfile` / `WorldRouterOAuthCredentials` all defined in Task 3/4/5/6 and consumed in Tasks 8/10/11 by the same names.
+- `OauthFamily::WorldRouter` defined in Task 8 and consumed in Tasks 10/11.
+- `to_registry_oauth_credential_worldrouter` defined in Task 9, consumed in Tasks 10/11.
+- `bind_localhost_port` defined in Task 7, consumed in Tasks 10/11.
+- `WORLDROUTER_CALLBACK_PATH` / `WORLDROUTER_CALLBACK_PORT` defined in Task 3, consumed in Tasks 10/11.
+
+No gaps.
diff --git a/docs/superpowers/specs/2026-05-20-worldrouter-provider-design.md b/docs/superpowers/specs/2026-05-20-worldrouter-provider-design.md
new file mode 100644
index 000000000..083bb57c3
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-20-worldrouter-provider-design.md
@@ -0,0 +1,400 @@
+# worldrouter Provider — Design
+
+Date: 2026-05-20
+Status: Draft (awaiting user approval)
+Owner: sean
+
+## 1. Motivation
+
+WorldRouter exposes an OpenAI-compatible inference API at
+`https://inference-api.worldrouter.ai`. Puffer needs a first-class
+provider entry so users can:
+
+1. Paste a WorldRouter API key (same UX as existing OpenAI-compatible
+   relays — kimi-openai, groq, openrouter, etc.).
+2. Click "Connect with OAuth" and authorize via Auth Station
+   (`https://auth.worldrouter.ai` / Sandbox
+   `https://auth-worldrouter.vercel.app`), opening the auth website in
+   the default browser and capturing a callback locally.
+
+Long-term framing (from user): worldrouter is a **brand entry point**.
+The provider role is the minimum-impact form for the current Puffer
+flow (provider + model + routing + auth all reuse existing plumbing).
+Future iterations will let the OAuth session resolve to either a
+`claw` plan or a WorldRouter API key. The current scope keeps both
+paths open: OAuth captures the JWT and stores it; API-key input
+stores a key. The JWT-to-api-key exchange endpoint is **not yet
+defined backend-side** and is a clearly marked TODO in code.
+
+## 2. Non-Goals
+
+- Implementing the JWT → inference API-key exchange. Backend is not
+  ready. We store the JWT as an OAuth credential placeholder; the
+  inference path requires a manually pasted API key for now.
+- Replacing existing OpenAI provider crate functionality.
+- Reworking LoginView UI. The component is already generic over
+  `authModes`.
+- Renaming the provider id (`worldrouter` vs `worldclaw`). Pick one id
+  now and keep it stable; display name can change later via yaml.
+
+## 3. High-level architecture
+
+```
+┌─────────────────────┐    OAuth button       ┌──────────────────┐
+│  puffer-desktop     │  ───────────────────▶ │  daemon          │
+│  (Svelte LoginView) │   login_with_oauth    │  (puffer-cli)    │
+└─────────────────────┘                       └────────┬─────────┘
+                                                       │
+                                                       │ dispatch by oauth_family
+                                                       ▼
+                          ┌────────────────────────────────────────┐
+                          │ puffer-provider-worldrouter             │
+                          │  build_login_url + parse_callback +    │
+                          │  decode_jwt + refresh_token            │
+                          └────────────┬───────────────────────────┘
+                                       │ open browser
+                                       ▼
+                          ┌────────────────────────────────────────┐
+                          │ Auth Station                           │
+                          │  /login → 302 to                       │
+                          │  http://127.0.0.1:1456/callback?token= │
+                          └────────────────────────────────────────┘
+                                       │ daemon waits on CallbackListener
+                                       ▼
+                          ┌────────────────────────────────────────┐
+                          │ AuthStore (OAuth credential)           │
+                          │  access_token / refresh_token /        │
+                          │  email / sub from JWT                  │
+                          └────────────────────────────────────────┘
+```
+
+API-key path is unchanged: LoginView submits api_key → existing
+`store_api_key` plumbing → `StoredCredential::ApiKey` in AuthStore.
+
+## 4. Provider yaml
+
+`resources/providers/worldrouter.yaml`:
+
+```yaml
+id: worldrouter
+display_name: WorldRouter
+base_url: https://inference-api.worldrouter.ai
+default_api: openai-completions
+oauth_family: worldrouter
+auth_modes:
+  - api_key
+  - oauth
+discovery:
+  path: /v1/models
+  response: open_ai_models
+  api: openai-completions
+  context_window: 200000
+  max_output_tokens: 8192
+  supports_reasoning: true
+models:
+  # Seed list — actual catalog comes from /v1/models discovery.
+  - id: gpt-5
+    display_name: GPT-5 (via WorldRouter)
+    provider: worldrouter
+    api: openai-completions
+    context_window: 200000
+    max_output_tokens: 8192
+    supports_reasoning: true
+```
+
+Notes:
+- `default_api: openai-completions` → reuses the existing OpenAI
+  Chat-Completions transport (Bearer api_key, `/v1/chat/completions`).
+- `oauth_family: worldrouter` is a new field (§5). When unset, the
+  registry falls back to the existing API-family inference.
+- The model seed list is intentionally minimal; `discovery` will
+  populate the rest at runtime against `/v1/models`.
+
+## 5. ProviderDescriptor change
+
+`crates/puffer-provider-registry/src/model.rs`:
+
+```rust
+pub struct ProviderDescriptor {
+    // ...existing fields...
+    /// Optional explicit OAuth family. When `None`, callers infer the
+    /// family from `default_api` (existing behavior — preserves
+    /// every yaml that did not opt in). When `Some`, callers use the
+    /// named family directly. This is the seam that lets a single
+    /// provider with `default_api: openai-completions` plug into a
+    /// non-OpenAI OAuth flow.
+    #[serde(default)]
+    pub oauth_family: Option<String>,
+}
+```
+
+`auth_provider.rs::oauth_family_for_provider` is updated to:
+
+1. Read `descriptor.oauth_family` first; map known strings to enum:
+   - `"openai"` → `OauthFamily::OpenAi`
+   - `"anthropic"` → `OauthFamily::Anthropic`
+   - `"worldrouter"` → `OauthFamily::WorldRouter` (new)
+2. If unset, fall back to the existing `default_api` switch (no
+   behavior change for any existing yaml).
+
+`OauthFamily` enum grows one variant: `WorldRouter`.
+
+## 6. New crate: `puffer-provider-worldrouter`
+
+Layout:
+
+```
+crates/puffer-provider-worldrouter/
+├── Cargo.toml
+└── src/
+    ├── lib.rs    — public re-exports
+    └── auth.rs   — login URL / callback parser / JWT decode / refresh
+```
+
+Public surface (`src/auth.rs`):
+
+```rust
+/// Default Auth Station base URL (Sandbox).
+pub const WORLDROUTER_AUTH_BASE_URL: &str = "https://auth-worldrouter.vercel.app";
+
+/// Env var that overrides the Auth Station base URL.
+pub const WORLDROUTER_AUTH_URL_OVERRIDE_ENV: &str = "PUFFER_WORLDROUTER_AUTH_URL";
+
+/// Fixed loopback callback used by Puffer desktop. The auth team
+/// must allow-list this redirect URI on both Sandbox and Production
+/// `ALLOWED_REDIRECT_ORIGINS`.
+pub const WORLDROUTER_CALLBACK_PATH: &str = "/callback";
+pub const WORLDROUTER_CALLBACK_PORT: u16 = 1456;
+pub const WORLDROUTER_DEFAULT_REDIRECT_URI: &str =
+    "http://127.0.0.1:1456/callback";
+
+/// Persisted Auth Station credentials for the worldrouter provider.
+pub struct WorldRouterOAuthCredentials {
+    pub access_token: String,
+    pub refresh_token: String,
+    pub expires_at_ms: u64,
+    pub sub: Option<String>,
+    pub email: Option<String>,
+    pub name: Option<String>,
+}
+
+/// Parameters required to build the Auth Station login URL.
+pub struct WorldRouterLoginConfig {
+    pub auth_base_url: String,
+    pub redirect_uri: String,
+    pub client_state: String,
+}
+
+impl Default for WorldRouterLoginConfig { /* env override + defaults */ }
+
+/// Generate an opaque random client_state.
+pub fn generate_client_state() -> String;
+
+/// Build the GET URL for `<auth>/login?redirect_uri=&client_state=`.
+pub fn build_login_url(config: &WorldRouterLoginConfig) -> String;
+
+/// Parsed callback fields. Each field is `None` when the parameter
+/// was absent from the callback URL.
+pub struct WorldRouterCallback {
+    pub token: Option<String>,
+    pub refresh_token: Option<String>,
+    pub state: Option<String>,
+    pub error: Option<String>,
+    pub error_description: Option<String>,
+}
+
+/// Extract `token`, `refresh_token`, `state`, `error`,
+/// `error_description` from a callback URL.
+pub fn parse_callback_input(input: &str) -> WorldRouterCallback;
+
+/// Decoded JWT profile fields, best-effort.
+pub struct WorldRouterJwtProfile {
+    pub sub: Option<String>,
+    pub email: Option<String>,
+    pub name: Option<String>,
+}
+
+/// Decode `sub`/`email`/`name` from the access token JWT payload
+/// (best-effort; failures yield empty fields).
+pub fn decode_jwt_profile(access_token: &str) -> WorldRouterJwtProfile;
+
+/// Exchange a stored refresh token for a new access token via
+/// `POST <auth>/token/refresh`.
+pub fn refresh_oauth_token(
+    refresh_token: &str,
+    auth_base_url: Option<&str>,
+) -> Result<WorldRouterOAuthCredentials>;
+```
+
+Auth Station's `/login` flow is **simpler than OAuth**: there is no
+PKCE, no code, no token exchange. The callback already contains the
+final tokens. The CSRF guard is `client_state ↔ state`. We honor it.
+
+`auth.rs` stays well under the 1000-line limit (target ~250 lines
+including tests).
+
+## 7. Daemon login dispatch
+
+`crates/puffer-cli/src/daemon.rs::handle_login_with_oauth` gains a
+third arm:
+
+```rust
+Some(OauthFamily::WorldRouter) => {
+    let parsed = parse_callback_input(&callback);
+    if let Some(err) = parsed.error.as_deref() {
+        let desc = parsed.error_description.as_deref().unwrap_or("");
+        bail!("worldrouter login failed: {err} {desc}");
+    }
+    if parsed.state.as_deref() != Some(bundle.state.as_str()) {
+        bail!("oauth state mismatch for worldrouter");
+    }
+    let token = parsed
+        .token
+        .ok_or_else(|| anyhow!("worldrouter callback missing token"))?;
+    let refresh = parsed.refresh_token.unwrap_or_default();
+    let profile = decode_jwt_profile(&token);
+    let credential = WorldRouterOAuthCredentials {
+        access_token: token,
+        refresh_token: refresh,
+        expires_at_ms: now_ms() + 24 * 3600 * 1000, // matches Auth Station spec
+        sub: profile.sub,
+        email: profile.email,
+        name: profile.name,
+    };
+    set_stored_credential(
+        &mut inputs.auth_store,
+        provider_id.to_string(),
+        StoredCredential::OAuth(to_registry_oauth_credential_worldrouter(credential)),
+    );
+}
+```
+
+`oauth_login_bundle_for_provider` (auth_provider.rs) likewise gains a
+`WorldRouter` arm that builds the bundle from
+`WorldRouterLoginConfig`. The bundle's `verifier` is unused for
+worldrouter — we set it to an empty string. `automatic_authorization_url`
+is `None` (single URL, no manual fallback).
+
+`puffer-cli/src/main.rs::run_login_flow` adds the matching arm so the
+CLI path (`puffer auth login worldrouter`) works the same way.
+
+`puffer-cli/src/authflow.rs` is unchanged. The `CallbackListener::bind_localhost`
+helper accepts the fixed port via a new optional binder
+`bind_localhost_port(path, port)` (the existing helper stays the
+default — we only branch when the caller asks for a fixed port).
+
+## 8. TODO: JWT → api_key exchange
+
+A clearly named module placeholder is added in
+`puffer-provider-worldrouter/src/lib.rs`:
+
+```rust
+/// TODO (waiting on worldrouter backend):
+/// Exchange an Auth Station JWT for an inference API key.
+/// Once the endpoint is finalized, this function POSTs the JWT to
+/// `<worldrouter>/api/v1/keys/exchange` (or whatever the backend
+/// settles on) and returns the api_key. The login handler will then
+/// upgrade the stored credential from `OAuth(jwt)` to `ApiKey(...)`
+/// (or store both).
+pub fn exchange_jwt_for_api_key(
+    _access_token: &str,
+) -> Result<String> {
+    anyhow::bail!(
+        "worldrouter JWT-to-api-key exchange is not yet implemented; \
+         paste your WorldRouter API key for now."
+    )
+}
+```
+
+The `handle_login_with_oauth` arm calls this **eagerly** and, on the
+expected `bail!`, stores the OAuth credential anyway and surfaces a
+user-visible message in the SettingsSnapshot:
+`"Logged in as <email>. Paste your WorldRouter API key to enable
+inference (auto-exchange pending backend support)."` The next
+SettingsSnapshot fetch refreshes the UI.
+
+When backend ships the endpoint, only the body of
+`exchange_jwt_for_api_key` and the login handler's branch change.
+
+## 9. Desktop UI
+
+LoginView already supports the API-key + OAuth dual layout. The only
+desktop-side change is:
+
+- `apps/puffer-desktop/src/lib/providerVisuals.ts` — register a
+  `worldrouter` entry (icon path + accent color). A simple text-based
+  monogram icon is acceptable for v1; designer can replace later.
+- A short banner above the OAuth button when the active provider is
+  worldrouter and only an OAuth credential exists (no api_key): "Auto
+  api-key exchange is not yet enabled. Paste a WorldRouter API key
+  to start running models."
+
+No new Tauri commands. No new daemon RPCs beyond reusing
+`login_with_oauth`.
+
+## 10. Tests
+
+- `puffer-provider-worldrouter`:
+  - `build_login_url_contains_redirect_uri_and_client_state`
+  - `parse_callback_input_extracts_token_refresh_state`
+  - `parse_callback_input_returns_error_when_present`
+  - `decode_jwt_profile_reads_sub_email_name`
+  - `default_config_honors_env_override`
+- `puffer-provider-registry`:
+  - `provider_descriptor_deserializes_oauth_family_field`
+  - `oauth_family_field_defaults_to_none`
+- `puffer-cli/auth_provider`:
+  - `oauth_family_uses_explicit_field_when_set`
+  - `oauth_family_falls_back_to_default_api_when_unset`
+  - `oauth_family_recognizes_worldrouter`
+- `puffer-cli/daemon` (with `tokio::test`):
+  - Smoke test for `handle_login_with_oauth` with a fake worldrouter
+    callback URL passed through the bundle path.
+
+`cargo test --workspace` must stay green.
+
+## 11. Resource provenance / file moves
+
+No moves. New files:
+
+- `resources/providers/worldrouter.yaml`
+- `crates/puffer-provider-worldrouter/Cargo.toml`
+- `crates/puffer-provider-worldrouter/src/lib.rs`
+- `crates/puffer-provider-worldrouter/src/auth.rs`
+
+New per-component spec files (per AGENTS.md convention):
+
+- `specs/puffer-provider-worldrouter/00.md` — crate overview
+- `specs/puffer-provider-registry/06.md` — `oauth_family` field
+- `specs/puffer-cli/<next>.md` — auth_provider dispatch + daemon arm
+- `specs/puffer-resources/<next>.md` — worldrouter.yaml entry
+- `specs/puffer-desktop/<next>.md` — providerVisuals entry + banner
+
+Each component spec is concise (≤ 60 lines) per existing style.
+
+## 12. Pre-shipping checklist for the user (out of code)
+
+- File a request with the auth maintainer to allow-list
+  `http://127.0.0.1:1456/callback` on **both** Sandbox and
+  Production `ALLOWED_REDIRECT_ORIGINS`.
+- Confirm `aud=worldclaw` is the correct audience claim for the
+  worldrouter product (the current docs use `worldclaw`; if a
+  separate audience is preferred for this product, surface it now).
+- Confirm the final brand name (`worldrouter` vs `worldclaw`) for the
+  yaml `id`. If you want to switch later, the cost is one yaml
+  rename plus a credentials migration step.
+
+## 13. Future work (post-MVP)
+
+### Done
+- ~~JWT → api_key exchange (waits on backend).~~ Implemented in `exchange_jwt_for_api_key` against the control-api preview endpoint. OAuth login now stores `StoredCredential::ApiKey` (sk-worldrouter-…) directly; JWT is not persisted.
+
+### Remaining
+- Profile UI showing the authenticated email / org from the JWT.
+- Refresh token rotation when access_token expires (one-line cron in
+  daemon: call `refresh_oauth_token` and re-store the credential).
+- "Switch account" button = `puffer auth logout worldrouter` + repeat
+  the OAuth flow.
+- If/when the brand becomes the primary entry point: hoist the
+  worldrouter OAuth flow to the onboarding root, push the
+  raw-OpenAI/Anthropic providers into an "Advanced" sub-screen.
diff --git a/resources/providers/worldrouter.yaml b/resources/providers/worldrouter.yaml
new file mode 100644
index 000000000..0f8a7757b
--- /dev/null
+++ b/resources/providers/worldrouter.yaml
@@ -0,0 +1,33 @@
+id: worldrouter
+display_name: WorldRouter
+base_url: https://inference-api.worldrouter.ai
+default_api: openai-completions
+oauth_family: worldrouter
+auth_modes:
+  - api_key
+  - oauth
+discovery:
+  path: /v1/models
+  response: open_ai_models
+  api: openai-completions
+  context_window: 200000
+  max_output_tokens: 8192
+  supports_reasoning: true
+models:
+  # Seed list — runtime /v1/models discovery overrides at startup.
+  # Pick a couple of reasoning-capable defaults verified live 2026-05-21
+  # (kimi-k2.6 and qwen3.5-flash both return 200 on /v1/chat/completions).
+  - id: kimi-k2.6
+    display_name: Kimi K2.6
+    provider: worldrouter
+    api: openai-completions
+    context_window: 128000
+    max_output_tokens: 8192
+    supports_reasoning: true
+  - id: qwen3.5-flash
+    display_name: Qwen 3.5 Flash
+    provider: worldrouter
+    api: openai-completions
+    context_window: 128000
+    max_output_tokens: 8192
+    supports_reasoning: true
diff --git a/specs/puffer-cli/31.md b/specs/puffer-cli/31.md
index ee48e6df2..f14c70d84 100644
--- a/specs/puffer-cli/31.md
+++ b/specs/puffer-cli/31.md
@@ -1,31 +1,13 @@
-# 31. Non-Interactive Transcript Actor Sync
+# WorldAgent OAuth Dispatch
 
 ## Summary
-
-Updates `puffer non-interactive` transcript writes for the actor-aware
-`TranscriptEvent` schema used by session storage.
-
-## Design
-
-Non-interactive runs still create a normal `AppState` and append normal
-session-store events. User messages now record `state.user_actor()`, assistant
-messages and tool invocations record `state.assistant_actor()`, and tool
-invocations preserve any agent/task subject via `state.tool_subject_actor`.
-
-Loaded JSONL transcripts remain backward-compatible. The replay path ignores
-unknown or newly added event fields when projecting events into `AppState`, then
-re-appends the original structured event to the new session transcript.
-
-## Contracts
-
-- The change is schema sync only; it does not alter command routing, provider
-  execution, permission behavior, or artifact output.
-- Existing transcripts without actor fields continue to deserialize through
-  `puffer-session-store` defaults.
-- Desktop Tauri builds can keep compiling `puffer-cli` as their pre-build step.
-
-## Verification
-
-- `cargo build -p puffer-cli`
-- `cargo build --release -p puffer-cli`
-- `npm run tauri build`
+- `OauthFamily` grows a `WorldAgent` variant.
+- `oauth_family_for_provider` prefers `descriptor.oauth_family` when set, otherwise falls back to `default_api`.
+- `oauth_login_bundle_for_provider` builds the bundle from `WorldAgentLoginConfig`; `verifier` is empty (no PKCE), `automatic_authorization_url` is `None`.
+- `handle_login_with_oauth` (daemon) and `run_login_flow` (cli) both gain a `WorldAgent` arm: parse callback, verify `state`, decode JWT for `sub`/`email`/`name`, store as `StoredCredential::OAuth`.
+- `CallbackListener::bind_localhost_port` lets the daemon bind the fixed `127.0.0.1:1456` Auth-Station-whitelist port.
+- `oauth-refresh` subcommand reuses `puffer_provider_worldagent::refresh_oauth_token` for the `WorldAgent` arm. `oauth-exchange` is unsupported for worldagent (no code-exchange step) and bails with a hint to use `puffer auth login worldagent`.
+
+## Compatibility
+- Existing OpenAI / Anthropic flows are unchanged (`oauth_family` unset → falls back to `default_api` map).
+- `WorldAgentOAuthCredentials.name` is not yet persisted (no slot on `OAuthCredential`); only `sub`/`email` survive into the registry shape.
diff --git a/specs/puffer-desktop/458.md b/specs/puffer-desktop/458.md
new file mode 100644
index 000000000..bfe5d5e7c
--- /dev/null
+++ b/specs/puffer-desktop/458.md
@@ -0,0 +1,8 @@
+# WorldRouter Visuals
+
+## Summary
+- `providerVisuals.ts` registers a `worldrouter` entry (display accent + icon).
+- No bespoke icon ships in this change; the fallback `ai` icon is reused until design provides one.
+
+## Compatibility
+- LoginView's generic OAuth / api_key surface needs no component change.
diff --git a/specs/puffer-provider-registry/06.md b/specs/puffer-provider-registry/06.md
new file mode 100644
index 000000000..0753203aa
--- /dev/null
+++ b/specs/puffer-provider-registry/06.md
@@ -0,0 +1,10 @@
+# Optional `oauth_family` on ProviderDescriptor
+
+## Summary
+- `ProviderDescriptor` gains `oauth_family: Option<String>`.
+- When `None`, callers infer the OAuth family from `default_api` (no behavior change for existing yaml).
+- When `Some`, callers dispatch directly to the named family. Known values today: `openai`, `anthropic`, `worldrouter`.
+
+## Compatibility
+- Default value preserves every existing provider yaml.
+- `ProviderPack` (in `puffer-resources`) mirrors the field and threads it through `into_descriptor`.
diff --git a/specs/puffer-provider-worldrouter/00.md b/specs/puffer-provider-worldrouter/00.md
new file mode 100644
index 000000000..efe78a613
--- /dev/null
+++ b/specs/puffer-provider-worldrouter/00.md
@@ -0,0 +1,22 @@
+# WorldRouter Provider Crate
+
+## Summary
+- New crate `puffer-provider-worldrouter` owning the Auth Station login flow for the `worldrouter` provider.
+- Auth Station returns the final `token` and `refresh_token` directly in the callback URL; this crate models that flow (no PKCE, no code exchange).
+
+## Surface
+- `build_login_url(&WorldRouterLoginConfig) -> String`
+- `parse_callback_input(&str) -> WorldRouterCallback`
+- `decode_jwt_profile(&str) -> WorldRouterJwtProfile`
+- `refresh_oauth_token(&str, Option<&str>) -> Result<WorldRouterOAuthCredentials>`
+- `exchange_jwt_for_api_key(&str) -> Result<ExchangedApiKey>` — two-hop: `POST {control-api}/auth/exchange` trades the Auth Station JWT for an Infer session token (HS256, `iss=infer-session`) and returns the user's `default_team_id`; `POST {control-api}/platform/v1/teams/{default_team_id}/keys` then mints a `sk-worldrouter-…` inference key.
+
+## Configuration
+- Default Auth Station URL: `https://auth.worldrouter.ai` (Production; `http://127.0.0.1:1456` allow-listed on prod as of 2026-05-20). Sandbox `https://auth-worldrouter.vercel.app` is reachable via `PUFFER_WORLDROUTER_AUTH_URL` override.
+- Default control-api URL: `https://control-api.worldrouter.ai` (Production). Preview `https://control-api-pre-7f819c.worldrouter.ai` is reachable via `PUFFER_WORLDROUTER_CONTROL_URL` override — beware that preview-control and production-inference do not share a LiteLLM DB, so keys minted on preview return 401 against `inference-api.worldrouter.ai`.
+- Fixed loopback redirect: `http://127.0.0.1:1456/callback`.
+- `default_team_id` comes from the `/auth/exchange` response envelope; no env-var fallback needed.
+
+## Compatibility
+- The fixed redirect URI must be allow-listed in Auth Station `ALLOWED_REDIRECT_ORIGINS` on both Sandbox and Production. Production confirmed 2026-05-20; Sandbox status to be verified before shipping a Sandbox build.
+- `exchange_jwt_for_api_key` is implemented against the production control-api deployment. The OAuth login path mints a `sk-worldrouter-…` inference key and stores it as `StoredCredential::ApiKey`; the Auth Station JWT is single-use and not persisted. The inference path reuses the standard OpenAI-completions transport with the freshly minted key. Backend explicitly noted the API shape will change — a TODO block in `auth.rs` tracks open questions (idempotency, revoke endpoint, stable production URL).
diff --git a/specs/puffer-resources/01.md b/specs/puffer-resources/01.md
new file mode 100644
index 000000000..347e908c7
--- /dev/null
+++ b/specs/puffer-resources/01.md
@@ -0,0 +1,11 @@
+# WorldRouter Provider Yaml
+
+## Summary
+- Bundled `resources/providers/worldrouter.yaml` adds the `worldrouter` provider entry.
+- `default_api: openai-completions` (inference goes through the existing OpenAI chat-completions transport).
+- `oauth_family: worldrouter` opts into the new login dispatch.
+- `auth_modes: [api_key, oauth]` exposes both LoginView paths.
+- Model catalog is seeded minimally; `/v1/models` discovery populates the rest at runtime.
+
+## Compatibility
+- Pure addition; no existing yaml is modified.