@paradigma-inc/flywheel 0.1.26 → 0.1.51

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.26",
+  "version": "0.1.51",
   "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/example-workflows/organizing-exploring-and-iterating-on-a-research-topic.md

@@ -34,8 +34,8 @@ A clean Flywheel graph screenshot on a white canvas. Near the upper-right is a b
 
 ### Likely Flywheel MCP tools for this step
 
-- `mcp__flywheel__flywheel_stage_node_create` to create the root `scheduled muon` graph.
-- `mcp__flywheel__flywheel_stage_node_update` to describe the overall research question and first branch.
+- `mcp__flywheel__flywheel_commit_new_node` to create the root `scheduled muon` graph.
+- `mcp__flywheel__flywheel_commit_node` to describe the overall research question and first branch.
 - `mcp__flywheel__flywheel_branch_node` to split the root into experiment branches.
 - `mcp__flywheel__flywheel_get_node_tree` to inspect the DAG as it starts to fill out.
 - `mcp__flywheel__flywheel_commit_node` to persist the initial structure.
@@ -55,7 +55,7 @@ as you all know, liches are known for obsessing over muon. i make no exception.
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to open an insight branch for the core muon observation.
-- `mcp__flywheel__flywheel_stage_node_update` to record the singular-value flattening concern as an explicit insight or hypothesis.
+- `mcp__flywheel__flywheel_commit_node` to record the singular-value flattening concern as an explicit insight or hypothesis.
 - `mcp__flywheel__flywheel_commit_node` to preserve that observation as a traceable node.
 
 ---
@@ -73,7 +73,7 @@ in my mind, there must have been a "softer" way to interpolate between nesterov
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to fork a new hypothesis branch from the original muon observation.
-- `mcp__flywheel__flywheel_stage_node_update` to capture the "softer interpolation" idea between SGD and muon.
+- `mcp__flywheel__flywheel_commit_node` to capture the "softer interpolation" idea between SGD and muon.
 - `mcp__flywheel__flywheel_commit_node` to save the refined hypothesis before experimenting.
 
 ---
@@ -90,7 +90,7 @@ so, i decided to spin up my MCP host and do a bunch of experiments. as usual, it
 
 ### Likely Flywheel MCP tools for this step
 
-- `mcp__flywheel__flywheel_stage_node_create` or `mcp__flywheel__flywheel_branch_node` to turn scattered runs into explicit branches instead of an untracked run log.
+- `mcp__flywheel__flywheel_commit_new_node` or `mcp__flywheel__flywheel_branch_node` to turn scattered runs into explicit branches instead of an untracked run log.
 - `mcp__flywheel__flywheel_list_nodes` to enumerate existing branches and runs.
 - `mcp__flywheel__flywheel_get_node_tree` to inspect the structure of the experiment graph.
 - `mcp__flywheel__flywheel_commit_node` to keep the graph auditable as new work is added.
@@ -109,7 +109,7 @@ then, [@thelokasiffers](https://x.com/thelokasiffers) released an early version
 
 ### Likely Flywheel MCP tools for this step
 
-- `mcp__flywheel__flywheel_stage_node_create` to create the root node if it did not already exist.
+- `mcp__flywheel__flywheel_commit_new_node` to create the root node if it did not already exist.
 - `mcp__flywheel__flywheel_branch_node` to fan the work into separate experiment branches.
 - `mcp__flywheel__flywheel_get_node_tree` to inspect the resulting DAG layout.
 - `mcp__flywheel__flywheel_summarize_node_tree` to quickly understand branch progress and outcomes.
@@ -136,7 +136,7 @@ what i did was pretty simple: i started discussing with the models my intuition:
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to create an insight branch for the `US^pV^T` intuition.
-- `mcp__flywheel__flywheel_stage_node_update` to store the proposed fractional-power formulation.
+- `mcp__flywheel__flywheel_commit_node` to store the proposed fractional-power formulation.
 - `mcp__flywheel__flywheel_commit_node` to save the idea before turning it into experiments.
 
 ---
@@ -154,7 +154,7 @@ then i realized: if we use NS to have an iteration that approximates powers of -
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to open a follow-up hypothesis branch around polynomial approximations.
-- `mcp__flywheel__flywheel_stage_node_update` to record the new approximation strategy.
+- `mcp__flywheel__flywheel_commit_node` to record the new approximation strategy.
 - `mcp__flywheel__flywheel_commit_node` to preserve the new line of attack.
 
 ---
@@ -172,7 +172,7 @@ at this point i started testing this out, would i get really the right spectra?
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to create the empirical branch for the spectra sanity check.
-- `mcp__flywheel__flywheel_stage_node_update` to record the hypothesis and evaluation criteria.
+- `mcp__flywheel__flywheel_commit_node` to record the hypothesis and evaluation criteria.
 - `mcp__flywheel__flywheel_request_compute_grant_approval`, `mcp__flywheel__flywheel_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the experiments on managed compute.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach the singular-value plot as an artifact.
 - `mcp__flywheel__flywheel_commit_node` to mark the empirical step as completed.
@@ -198,7 +198,7 @@ at this point, quite a few things were in question, what would happen if i train
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to fork a new investigation around schedule design.
-- `mcp__flywheel__flywheel_stage_node_update` to record the competing schedule hypotheses.
+- `mcp__flywheel__flywheel_commit_node` to record the competing schedule hypotheses.
 - `mcp__flywheel__flywheel_commit_node` to preserve the question before launching more runs.
 
 ---
@@ -216,7 +216,7 @@ but which way should we schedule? not clear. is it sgd first or muon first? how
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to split the root into separate schedule and learning-rate branches.
-- `mcp__flywheel__flywheel_stage_node_update` to encode the hypotheses and sweep definitions.
+- `mcp__flywheel__flywheel_commit_node` to encode the hypotheses and sweep definitions.
 - `mcp__flywheel__flywheel_request_compute_grant_approval` and `mcp__flywheel__flywheel_list_compute_grants` to secure spend before launch.
 - `mcp__flywheel__flywheel_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to provision GPUs and keep them available to the agent.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach result plots and cards as branches finish.

package/skills/flywheel/example-workflows/reproducing-papers-on-a-budget.md

@@ -8,9 +8,9 @@ A really interesting way of using Flywheel is to reproduce papers on a budget: I
 
 ### Likely Flywheel MCP tools for this step
 
-- `mcp__flywheel__flywheel_stage_node_create` to create the root reproduction graph or first node for the paper.
+- `mcp__flywheel__flywheel_commit_new_node` to create the root reproduction graph or first node for the paper.
 - `mcp__flywheel__flywheel_branch_node` to split the paper into parallel validation branches.
-- `mcp__flywheel__flywheel_stage_node_update` to capture the paper claim, reproduction plan, and budget constraint.
+- `mcp__flywheel__flywheel_commit_node` to capture the paper claim, reproduction plan, and budget constraint.
 - `mcp__flywheel__flywheel_request_compute_grant_approval` to enforce the "$10 max" spend before managed compute starts.
 - `mcp__flywheel__flywheel_commit_node` to persist the planned graph structure.
 
@@ -39,7 +39,7 @@ The model decides to play it safe: it starts by showing self-attention correlati
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to open the first empirical branch for the baseline correlation check.
-- `mcp__flywheel__flywheel_stage_node_update` to record the hypothesis and experiment setup.
+- `mcp__flywheel__flywheel_commit_node` to record the hypothesis and experiment setup.
 - `mcp__flywheel__flywheel_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to provision and use the small A10 GPU.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach `attn_similarity_by_layer.png`.
 - `mcp__flywheel__flywheel_commit_node` to mark the step as a completed empirical result.
@@ -59,7 +59,7 @@ Step two is analogous: orthogonality before and after XSA.
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to create the next experimental branch.
-- `mcp__flywheel__flywheel_stage_node_update` to record the orthogonality hypothesis for XSA.
+- `mcp__flywheel__flywheel_commit_node` to record the orthogonality hypothesis for XSA.
 - `mcp__flywheel__flywheel_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the projection check.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach `orthogonality_by_layer.png`.
 - `mcp__flywheel__flywheel_commit_node` to finalize the branch.
@@ -79,7 +79,7 @@ Then, it moves to overhead of the orthogonal projection.
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to fork an efficiency-comparison branch.
-- `mcp__flywheel__flywheel_stage_node_update` to define the runtime and VRAM hypothesis.
+- `mcp__flywheel__flywheel_commit_node` to define the runtime and VRAM hypothesis.
 - `mcp__flywheel__flywheel_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the matched SA vs XSA benchmark.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach `efficiency_comparison.png`.
 - `mcp__flywheel__flywheel_commit_node` to finalize the overhead measurement.
@@ -99,7 +99,7 @@ Up to now, no trouble. The agent then decides to train a 50M parameter model wit
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to create the larger training branch.
-- `mcp__flywheel__flywheel_stage_node_update` to record the 50M-parameter comparison and evaluation criteria.
+- `mcp__flywheel__flywheel_commit_node` to record the 50M-parameter comparison and evaluation criteria.
 - `mcp__flywheel__flywheel_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the longer training jobs.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach `run_metrics.csv` and `quality_pairs.csv`.
 - `mcp__flywheel__flywheel_commit_node` to record that the empirical result did not reproduce the expected gain.
@@ -120,7 +120,7 @@ Also, across sequence length, the trend seems to worsen.
 
 - `mcp__flywheel__flywheel_branch_node` to spin off an analysis branch for context length.
 - `mcp__flywheel__flywheel_get_node` and `mcp__flywheel__flywheel_list_artifacts` to gather results from the completed training branches.
-- `mcp__flywheel__flywheel_stage_node_update` to record the interpretation that the delta worsens at longer context.
+- `mcp__flywheel__flywheel_commit_node` to record the interpretation that the delta worsens at longer context.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach `length_trend.png`.
 - `mcp__flywheel__flywheel_commit_node` to persist the analysis.
 
@@ -139,7 +139,7 @@ At the same time, baseline seems to also win the LR sweeps.
 ### Likely Flywheel MCP tools for this step
 
 - `mcp__flywheel__flywheel_branch_node` to create a robustness branch for LR sweeps and sink-style perturbations.
-- `mcp__flywheel__flywheel_stage_node_update` to capture the robustness hypothesis.
+- `mcp__flywheel__flywheel_commit_node` to capture the robustness hypothesis.
 - `mcp__flywheel__flywheel_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the compact sweep experiments.
 - `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `mcp__flywheel__flywheel_finalize_artifact_uploads` to attach `robustness_deltas.png`.
 - `mcp__flywheel__flywheel_commit_node` to finalize the robustness verdict.

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/ARTIFACTS.md

@@ -0,0 +1,48 @@
+# Flywheel Artifacts
+
+Canonical artifact upload/finalize contract derived from `mcp_contract.py`.
+
+## Upload Contract
+
+- Prepare tool: `flywheel_prepare_artifact_uploads`.
+- Finalize tool: `flywheel_finalize_artifact_uploads`.
+- Raw file upload required between prepare/finalize: `True`.
+- Upload transport step: `PUT` to `prepare.items[].upload_url`.
+- Required headers source: `prepare.items[].upload_headers`.
+- Upload body contract: `raw_file_bytes`.
+- Prepare item required fields: `artifact_type`, `filename`, `media_type`.
+- Prepare item optional fields: `title`, `execution_id`, `metadata`, `note`.
+- Prepare item note: prepare.items[] is structured object input. The transport layer may tolerate stringified JSON as a compatibility measure; this tolerance is not contractual and may be removed.
+- Raw upload stage success code: `202`.
+- Stage semantics: `accepted_and_staged`.
+- Finalize appends the batch with a single revision bump: `True`.
+- Forbidden upload payload kinds: `json_metadata_wrapper`.
+- Optional note field `note` applies to `artifact_metadata_record` (markdown allowed: `True`).
+
+## Supported Artifact Types
+
+- `text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`, `checkpoint`, `binary`, `diff_carousel`
+
+## Metadata Contract
+
+- `title` required non-empty: `True`.
+- Display label field: `title`.
+- Title normalization priority: `explicit_title` -> `payload.title` -> `payload.name` -> `basename(payload.path|payload.filename|payload.file)` -> `basename(filename)` -> `basename(storage_path)` -> `artifact_type` -> `artifact`.
+- Title must not derive from: `storage_url`.
+- `storage_url` purpose: `raw_artifact_byte_read_url`.
+- `storage_url` cannot be used as display label: `True`.
+
+## Preview and Read Contract
+
+- `flywheel_list_artifacts`: List node artifacts.
+- `flywheel_get_artifact`: Get one artifact by id.
+- No dedicated artifact preview tool exists in the current MCP operation catalog.
+- Guidance: use flywheel_prepare_artifact_uploads, raw-file upload, and flywheel_finalize_artifact_uploads to publish experiment evidence before empirical completed commits
+
+## Failure Causes to Handle Explicitly
+
+- Stale `expected_revision` on mutating calls returns `409` and requires explicit reconciliation.
+- Reusing an idempotency key with a different payload hash causes `409_conflict`.
+- Prepare item payloads must be structured objects; stringified JSON item payloads are invalid.
+- Uploading metadata wrappers instead of raw file bytes violates the upload contract.
+- Finalize requires a valid prepared batch token and staged uploads from that batch.