@paradigma-inc/flywheel 0.1.104 → 0.1.107

package/README.md

@@ -14,6 +14,12 @@ One-shot installer (macOS and Linux):
 curl -fsSL https://flywheel.paradigma.inc/install | sh
 ```
 
+Windows users running their AI coding host from WSL should open the WSL distro,
+install Node.js 20+ and npm inside WSL, and run the same installer there.
+Flywheel then writes WSL-side config, so launch the host from that same WSL
+environment. If browser auth does not open from WSL, copy the printed approval
+URL and setup code into your Windows browser.
+
 The script installs `@paradigma-inc/flywheel@latest` into the managed user
 prefix `${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}`, adds a marked PATH block
 when needed, and then runs guided `flywheel setup` through the installed binary.
@@ -47,9 +53,17 @@ if (($userPath -split ";") -notcontains $prefix) {
 if (($env:Path -split ";") -notcontains $prefix) {
   $env:Path = "$prefix;$env:Path"
 }
-& "$prefix\flywheel.cmd" setup --mode cli
+
+# MCP host wiring for native Windows hosts
+& "$prefix\flywheel.cmd" setup --mode mcp
 ```
 
+Use the PowerShell path when Codex, Claude Code, Cursor, or another AI coding
+host runs as a native Windows process. Use `--mode cli` instead when you only
+want direct `flywheel` binary setup without MCP host wiring. Do not install in
+both WSL and native Windows unless you intentionally want separate Flywheel
+setups.
+
 Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 
 ```bash
@@ -57,6 +71,12 @@ Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
+In native PowerShell, the equivalent command is:
+
+```powershell
+npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
+```
+
 ## Shell Completion
 
 `flywheel completion <shell>` generates shell completion scripts from the public
@@ -200,12 +220,15 @@ npx --yes @paradigma-inc/flywheel setup --mode cli
 
 ## Auth Modes And Remote Shells
 
-`setup --auth-mode auto|loopback|device` controls authentication behavior:
+`setup --auth-mode <mode>` controls authentication behavior. Supported values
+are:
 
-- `loopback`: opens `/auth/mcp/setup` and waits for a localhost callback.
+- `auto` (default): uses the active device approval flow.
 - `device`: opens `/auth/mcp/setup/device`, confirms a setup code in browser,
   and CLI polls for approval.
-- `auto` (default): uses `device` on SSH shells and `loopback` otherwise.
+- `loopback`: retired legacy mode. The parser still accepts it so explicit
+  requests receive the deterministic FLY-416 remediation, which tells users to
+  use `--auth-mode device` or `--auth-mode auto`.
 
 Remote/headless example:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.104",
+  "version": "0.1.107",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/src/cli.mjs

@@ -1369,7 +1369,8 @@ Configure the Flywheel CLI, MCP host entries, and bundled skills without changin
     .optionsGroup("Advanced:")
     .option(
       "--auth-mode <mode>",
-      "API-key mint flow: auto | loopback | device (default: auto)",
+      "Device approval flow; default auto. " +
+        "Explicit loopback is retired and returns FLY-416 guidance",
       normalizeAuthMode,
       "auto",
     )

package/src/public-command-metadata.mjs

@@ -296,7 +296,8 @@ export const USAGE_EXTRAS = [
         name: "auth-mode",
         type: "string",
         usage: "--auth-mode <MODE>",
-        description: "API-key mint flow: auto | loopback | device",
+        description:
+          "Device approval flow; retired legacy mode returns FLY-416 guidance; default auto",
         default: "auto",
         choices: ["auto", "loopback", "device"],
       },

package/src/setup-auth.mjs

@@ -358,7 +358,7 @@ export async function acquireApiKeyViaBrowserBridge(_args) {
   throw new Error(
     "FLY-416: loopback (browser-bridge) auth has been removed. " +
       "Re-run with --auth-mode device (or --auth-mode auto) to use the " +
-      "RFC 8628 device flow. See docs/flywheel/CLI_STAGING_ACCESS.md for " +
+      "RFC 8628 device flow. Run flywheel setup --help for " +
       "the full CLI auth contract.",
   );
 }