@paradigma-inc/flywheel 0.1.35 → 0.1.52

package/README.md

@@ -1,25 +1,65 @@
 # flywheel setup CLI
 
 This package configures Flywheel MCP for supported AI coding hosts and can
-install or refresh all bundled Flywheel skills during setup.
+install or refresh bundled Flywheel skills.
 
-## Public Guided Install (Primary Human Flow)
+`@paradigma-inc/flywheel` is the only user-facing Flywheel CLI install path and
+owns the public `flywheel` binary surface.
+
+## Install
+
+One-shot installer (macOS and Linux):
+
+```bash
+curl -fsSL https://flywheel.paradigma.inc/install | sh
+```
+
+The script runs `npm install -g @paradigma-inc/flywheel@latest` followed by
+`flywheel setup --mode cli`. You can read the full source at the same URL
+without piping to `sh`.
+
+Prefer the two-step npm recipe? It still works:
+
+```bash
+# --mode cli — installs the flywheel command, used by both you and your AI host
+npm install -g @paradigma-inc/flywheel@latest && flywheel setup --mode cli
+```
+
+On Windows (PowerShell), use `;` instead of `&&`:
+
+```powershell
+npm install -g @paradigma-inc/flywheel@latest; flywheel setup --mode cli
+```
+
+Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 
 ```bash
-npx --yes @paradigma-inc/flywheel setup
+# --mode mcp — your AI host calls Flywheel over MCP
+npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
-Guided flow:
+## Setup Modes
 
-1. Flywheel MCP setup runs first.
-2. If at least one selected host supports bundled skill install, setup asks
-   one of these prompts:
-   - `Also install or refresh the bundled Flywheel skill?`
-   - `Also install or refresh the bundled Flywheel skills?`
-3. The prompt default is yes.
+```bash
+# canonical
+npx --yes @paradigma-inc/flywheel setup --mode <mcp|cli>
+
+# aliases
+npx --yes @paradigma-inc/flywheel setup --mcp
+npx --yes @paradigma-inc/flywheel setup --cli
+```
 
-If you accept the default, the run completes with MCP plus bundled skill setup
-for supported hosts.
+Mode behavior:
+
+- `--mode mcp` / `--mcp`: MCP config setup path (plus optional bundled skill
+  install path).
+- `--mode cli` / `--cli`: bundled skill install path only, no MCP config writes,
+  no shell mutation.
+
+If mode is omitted:
+
+- interactive TTY: prompt for `mcp` or `cli` (default `mcp`)
+- non-interactive: fails with usage error (`exit 2`)
 
 ## Public Base URL Rules
 
@@ -33,23 +73,27 @@ Use public origins such as:
 Do not pass backend Fly machine hostnames (for example `*.fly.dev`) to
 `--base-url`.
 
-## Explicit Automation Flows
+## Non-Interactive Flows
 
-Prompt-free combined MCP plus skill setup:
+MCP setup (without bundled skill installation):
 
 ```bash
-npx --yes @paradigma-inc/flywheel setup --install-skill
+npx --yes @paradigma-inc/flywheel setup --mode mcp --skip-skill
 ```
 
-Prompt-free MCP-only setup:
+MCP setup (with bundled skill installation):
 
 ```bash
-npx --yes @paradigma-inc/flywheel setup --skip-skill
+npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill
 ```
 
-`--install-skill` and `--skip-skill` are mutually exclusive.
+CLI-only bundled skill setup:
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli
+```
 
-Non-interactive setup requires one of those flags.
+`--install-skill` and `--skip-skill` are mutually exclusive.
 
 ## Auth Modes And Remote Shells
 
@@ -64,72 +108,84 @@ Remote/headless example:
 
 ```bash
 npx --yes @paradigma-inc/flywheel setup \
+  --mode mcp \
   --auth-mode device \
+  --skip-skill \
   --base-url https://flywheel.paradigma.inc
 ```
 
+## Runtime Config Bootstrap
+
+`setup --mode mcp` now also provisions the runtime CLI config so that
+post-setup runtime commands (`flywheel auth:status`, `flywheel nodes:list`,
+etc.) work immediately without manual steps.
+
+On successful authentication, the setup writes a JSON config at:
+
+- `FLYWHEEL_CLI_CONFIG_PATH` (when set)
+- `$HOME/.config/flywheel-cli/config.json` (default)
+
+The resolved runtime base URL always includes the `/api` suffix
+(for example `https://flywheel.paradigma.inc/api`), matching the runtime
+API mount point. The runtime command surface is documented in
+`project/flywheel-cli/README.md`.
+
+## Argument Syntax (Runtime Commands)
+
+Runtime commands (`auth:*`, `nodes:*`, `artifacts:*`, `compute:*`,
+`export:*`) use GNU-style long flags: `--key value`, `--key=value`, or
+`--boolean_flag`. JSON payload commands accept `--payload_json=@path.json`
+to load payloads from disk. See `project/flywheel-cli/README.md` for
+full details.
+
 ## Scope Rules
 
-- Default scope (no `--project`) is user-level/global:
-  MCP config is written to the host's global config path and bundled skill
-  install targets user-level skill directories.
-- `--project` is the explicit repo-local override:
-  MCP config and bundled skill install both target project-local paths.
+- Default scope (no `--project`) is user-level/global.
+- `--project` is the explicit repo-local override.
 
 Examples:
 
 ```bash
 # Global default
-npx --yes @paradigma-inc/flywheel setup --install-skill --codex --api-key <token>
+npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill --codex --api-key <token>
 
 # Project-local override
-npx --yes @paradigma-inc/flywheel setup --install-skill \
+npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill \
   --project --codex --api-key <token>
 ```
 
-## Public Update Flow
-
-After a new release:
+## Host Matrix
 
-- Human-guided update:
+| Host         | MCP wiring (`--mode mcp`) | CLI-mode bundled skill install (`--mode cli`) |
+| ------------ | ------------------------- | --------------------------------------------- |
+| Claude Code  | yes                       | yes                                           |
+| OpenCode     | yes                       | yes                                           |
+| Codex        | yes                       | yes                                           |
+| Cursor       | yes                       | yes                                           |
+| Pi (pi-mono) | yes                       | yes                                           |
+| OpenClaw     | yes                       | yes                                           |
+| Hermes Agent | yes                       | no (MCP-only host)                            |
 
-```bash
-npx --yes @paradigma-inc/flywheel@latest setup
-```
+CLI mode handling for Hermes Agent:
 
-- Automation update:
+- unsupported-only selection: command fails with usage error (`exit 2`)
+- mixed supported + unsupported selection: command continues for supported
+  hosts and reports skipped unsupported hosts
 
-```bash
-npx --yes @paradigma-inc/flywheel@latest setup --install-skill
-```
-
-Reruns refresh every already-installed bundled skill in place and install any
-newly bundled skills from the updated package. They do not create side-by-side
-copies for the same scope and agent location.
+## Public Update Flow
 
-If you choose to refresh via `skills experimental_sync` instead of rerunning
-setup, install Flywheel locally in that project first:
+After a new release:
 
 ```bash
-npm install --save-dev @paradigma-inc/flywheel@latest
-npx skills experimental_sync --agent codex -y
+npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
-## Supported Hosts For Bundled Skill Install
-
-- Claude Code
-- Codex
-- OpenCode
-- Cursor
-- OpenClaw
-- Pi (pi-mono)
-
-Hermes Agent remains MCP-only in phase 1.
+Reruns are idempotent and should be used as the primary recovery path for setup
+and update issues.
 
 ## Troubleshooting
 
 Advanced troubleshooting (optional): inspect installed skill state directly.
-Normal users do not need to run these commands for install/update.
 
 ```bash
 npx --yes skills ls -a codex
@@ -137,13 +193,14 @@ npx --yes skills ls -a claude-code
 npx --yes skills ls -a cursor
 ```
 
-If any bundled skill is missing, rerun setup using either guided `setup` or
-explicit `setup --install-skill`.
+If bundled skills are missing, rerun setup with explicit mode and desired skill
+flags.
 
 ## Other Commands
 
-- `setup`: guided setup-centric flow.
-- `uninstall`: removes Flywheel MCP entries from host configs only.
+- `setup`: setup flow with explicit mode routing.
+- `uninstall`: removes Flywheel MCP entries from host configs and removes
+  bundled skills from supported hosts.
 
 ```bash
 npx --yes @paradigma-inc/flywheel uninstall

package/bin/flywheel.js

@@ -1,9 +1,16 @@
 #!/usr/bin/env node
 
-import { runCli } from "../src/cli.mjs";
+import { runUnifiedCli } from "../src/unified-cli.mjs";
 
-runCli(process.argv).catch((error) => {
+runUnifiedCli(process.argv.slice(2)).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   console.error(`flywheel: ${message}`);
-  process.exitCode = 1;
+  const exitCode =
+    error &&
+    typeof error === "object" &&
+    "exitCode" in error &&
+    Number.isInteger(error.exitCode)
+      ? error.exitCode
+      : 1;
+  process.exitCode = exitCode;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.35",
+  "version": "0.1.52",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [
@@ -13,12 +13,16 @@
     "flywheel": "bin/flywheel.js"
   },
   "scripts": {
+    "sync:runtime": "node scripts/sync-runtime-cli.mjs",
+    "pretest": "npm run sync:runtime",
+    "prepack": "npm run sync:runtime",
     "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
     "commander": "^14.0.1",
     "js-yaml": "^4.1.0",
+    "open": "^10.2.0",
     "ora": "^9.0.0",
     "picocolors": "^1.1.1",
     "skills": "1.4.7"

package/skills/flywheel/SKILL.md

@@ -15,10 +15,22 @@ Use this skill when the conversation is about any of the following:
 - running or interpreting empirical work in Flywheel
 - choosing between `insight` and `empirical` nodes
 - setting up, updating, authenticating, or troubleshooting Flywheel MCP
+- configuring hooks, hook secrets, and hook-run monitoring
 - managed compute, local hardware, campaigns, or Flywheel Web UI navigation
 
 If the request is ambiguous, default to experiment-design guidance before platform mechanics.
 
+## Modes
+
+This skill supports both Flywheel install modes:
+
+- **`--mode mcp` install**: route via [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md); tool calls take the form `flywheel_<tool>` (e.g., `flywheel_commit_node`).
+- **`--mode cli` install**: `setup --mode cli` configures runtime credentials, then route via [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md); tool calls take the form `flywheel <command>` (e.g., `flywheel nodes:commit`). Prerequisite for bare-binary routing: `npm install -g @paradigma-inc/flywheel`.
+
+When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+
+The Workflow and Routing Map below cite both the MCP tool name and its CLI equivalent inline at each imperative step. Pick the one matching your install mode.
+
 ## Workflow
 
 1. Classify the request as research guidance, platform support, or mixed.
@@ -34,7 +46,7 @@ If the request is ambiguous, default to experiment-design guidance before platfo
 Choose one primary file first, then add at most one supporting file only if needed:
 
 - `references/experiment-design-protocol.md` for structured experiment design and readiness checks
-- `references/flywheel-mcp-tool-map.md` for exact tool surface and contract behavior
+- `references/flywheel-mcp-tool-map.md` (MCP) or `references/flywheel-cli-tool-map.md` (CLI) for exact tool surface and contract behavior in the matching install mode
 - `getting-started/flywheel-tutorial-overview.md` for orientation and learning path
 - `getting-started/flywheel-quickstart.md` for fastest first-use setup and auth recovery
 - `setting-up-flywheel/` for host-specific installation and update procedures

package/skills/flywheel/campaigns/participating-in-a-campaign.md

@@ -1,4 +1,4 @@
-# [](https://flywheel.paradigma.inc//#participating-in-a-campaign)Participating in a Campaign
+# Participating in a Campaign
 
 Campaigns are challenge-style Flywheel graphs where an organizer shares a root graph, defines the objective and submission contract, and may fund participant compute through campaign budgets.
 
@@ -12,7 +12,7 @@ To participate in a campaign:
 
 The practical rule is simple: the campaign root tells you the contract, and your graph is how you show your work.
 
-## [](https://flywheel.paradigma.inc//#coming-soon)Coming Soon
+## Coming Soon
 
 - A dedicated tutorial section for setting up a campaign as an organizer.
 - A dedicated tutorial section for sponsoring or funding a campaign.

package/skills/flywheel/compute/managed-compute.md

@@ -1,8 +1,8 @@
-# [](https://flywheel.paradigma.inc//#managed-compute)Managed Compute
+# Managed Compute
 
-Flywheel can provision managed GPU instances for you from providers like Lambda Labs, Modal, Vast.ai, and Prime Intellect — directly from your agent conversation. You don't need to leave your workflow to spin up machines.
+Flywheel can provision managed GPU instances for you from providers like Lambda Labs, Modal, Vast.ai, Prime Intellect, Nebius, and RunPod — directly from your agent conversation. You don't need to leave your workflow to spin up machines.
 
-## [](https://flywheel.paradigma.inc//#how-it-works)How it works
+## How it works
 
 1. **Ask your agent for compute.** When you need a GPU for an experiment, just say so:
 
@@ -23,7 +23,7 @@ For autonomous runs, agents should default to releasing only known leases
 unknown active leases are detected, agents should report and skip those leases
 by default. Use account-wide release only when the user explicitly requests it.
 
-## [](https://flywheel.paradigma.inc//#managing-machines-in-the-webui)Managing machines in the WebUI
+## Managing machines in the WebUI
 
 In **Settings > Machines**, you can see all GPU leases across your account — including the provider, state, hourly rate, total spend, and the acquire context that originally launched each lease. You can release individual leases or all at once.
 
@@ -31,7 +31,7 @@ In **Settings > Machines**, you can see all GPU leases across your account — i
 
 Inside a node, the node view focuses on compute policy and budget tracking (spent vs. hard cap). Active machines themselves are managed from the account level **Settings > Machines** view.
 
-## [](https://flywheel.paradigma.inc//#credits-and-billing)Credits and billing
+## Credits and billing
 
 Compute is billed against your Flywheel credits balance, which is separate from your subscription.
 
@@ -129,6 +129,7 @@ Never display more than three total options.
 ### Step 8 - Require confirmation and handle acquire failure
 
 - Wait for explicit user confirmation (or explicit user override offer id) before `flywheel_compute_acquire`.
+- When acquiring, `requested_sku` must equal the exact selected `options[].offer_id` from `flywheel_compute_list_options` (copy verbatim, including provider prefixes like `nebius::...`; never use display names).
 - On acquire failure due to capacity:
   1. pick next-best candidate from the active candidate set (excluding failed offer),
   2. same provider -> retry immediately without re-confirmation,
@@ -147,12 +148,30 @@ Fixed numeric defaults for this flow:
 - Always show the recommended offer first with rationale.
 - Then show up to two alternatives.
 - Always wait for explicit user confirmation before calling `flywheel_compute_acquire`.
-- If the user provides an explicit offer-id override, Treat as first-class and proceed with that selected offer after confirmation.
+- If the user provides an explicit offer-id override, treat it as first-class only if it exactly matches one of the current `options[].offer_id` values; then proceed after confirmation.
 
 For persistent preference, set `preferred_offer_ids` in the node compute policy.
 
-## [](https://flywheel.paradigma.inc//#tips)Tips
+## Tips
 
 - Provisioning takes a few minutes — the agent polls automatically, so you don't need to babysit it.
 - You can walk away; Flywheel continues while the machine spins up.
 - Release leases when you're done to save credits.
+
+## Provider Setup (Operators)
+
+Managed compute providers are enabled by backend environment variables. For Nebius, configure:
+
+- `NEBIUS_SERVICE_ACCOUNT_ID`
+- `NEBIUS_SERVICE_ACCOUNT_PUBLIC_KEY_ID`
+- `NEBIUS_SERVICE_ACCOUNT_PRIVATE_KEY_PEM`
+- `NEBIUS_PARENT_ID`
+- `NEBIUS_SUBNET_ID`
+- one of `NEBIUS_BOOT_IMAGE_ID` or `NEBIUS_BOOT_IMAGE_FAMILY`
+- optional: `NEBIUS_BOOT_IMAGE_FAMILY_PARENT_ID`, `NEBIUS_SECURITY_GROUP_IDS`
+
+Deploy preflight treats Nebius as a valid standalone provider bundle when all required Nebius keys are present.
+
+NEBIUS_BOOT_IMAGE_FAMILY_PARENT_ID and NEBIUS_SECURITY_GROUP_IDS are optional runtime defaults and are not validated by deploy preflight.
+
+These secrets must be injected via your deployment secret manager (for Fly.io backend apps, use `flyctl secrets set`). Do not commit provider secrets in repository files.

package/skills/flywheel/getting-started/flywheel-tutorial-overview.md

@@ -6,7 +6,7 @@
 
 Welcome to Flywheel. Below we will cover how to install Flywheel and some tips on usage patterns.
 
-## [](https://flywheel.paradigma.inc//#what-is-flywheel)What is Flywheel?
+## What is Flywheel?
 
 Flywheel's ambition is to serve as the infrastructure upon which autonomous science will run.
 
@@ -20,6 +20,7 @@ While in SWE we use git to manage changes to code, in research we are interested
 - [Setting up Flywheel](../setting-up-flywheel/installation-overview.md)
 - [How to update Flywheel MCP](../setting-up-flywheel/updating-flywheel-mcp.md)
 - [What to do with Flywheel](../usage-and-workflows/what-to-do-with-flywheel.md)
+- [Hooks: node event automations](../usage-and-workflows/what-to-do-with-flywheel.md#configure-hooks-node-automations)
 - [The Flywheel WebUI](../web-ui/the-flywheel-web-ui.md)
 - [Managed Compute](../compute/managed-compute.md)
 - [Credits and billing](../compute/credits-and-billing.md)

package/skills/flywheel/references/INTERFACES.md

@@ -85,6 +85,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `flywheel_compute_funding` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_compute_status` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_compute_connection` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_approval_session_open` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_approval_session_heartbeat` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_list_approval_sessions` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_expire_approval_session` (mutating; scopes: `compute`; core surface; binding: `operation`)
@@ -170,6 +171,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `GET /compute/funding` -> `flywheel_compute_funding`
 - `GET /compute/status` -> `flywheel_compute_status`
 - `GET /compute/connection` -> `flywheel_compute_connection`
+- `tool-mediated` -> `flywheel_approval_session_open`
 - `POST /approval-sessions/heartbeat` -> `flywheel_approval_session_heartbeat`
 - `GET /approval-sessions` -> `flywheel_list_approval_sessions`
 - `POST /approval-sessions/expire` -> `flywheel_expire_approval_session`