@paradigma-inc/flywheel 0.1.115 → 0.1.134

package/README.md

@@ -15,7 +15,7 @@ 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.
+install Node.js 24.15+ within 24.x or 25.7+ 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.
@@ -202,22 +202,26 @@ Do not pass backend Fly machine hostnames (for example `*.fly.dev`) to
 
 ## Non-Interactive Flows
 
+These examples select Codex explicitly. `npx --yes` confirms package execution;
+the separate setup `--yes` disables setup prompts. Device authentication still
+requires browser approval.
+
 MCP setup (without bundled skill installation):
 
 ```bash
-npx --yes @paradigma-inc/flywheel setup --mode mcp --skip-skill
+npx --yes @paradigma-inc/flywheel setup --mode mcp --codex --yes --skip-skill
 ```
 
 MCP setup (with bundled skill installation):
 
 ```bash
-npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill
+npx --yes @paradigma-inc/flywheel setup --mode mcp --codex --yes --install-skill
 ```
 
 CLI-only bundled skill setup:
 
 ```bash
-npx --yes @paradigma-inc/flywheel setup --mode cli
+npx --yes @paradigma-inc/flywheel setup --mode cli --codex --yes
 ```
 
 `--install-skill` and `--skip-skill` are mutually exclusive.
@@ -239,27 +243,80 @@ Remote/headless example:
 ```bash
 npx --yes @paradigma-inc/flywheel setup \
   --mode mcp \
+  --codex --yes \
   --auth-mode device \
   --skip-skill \
   --base-url https://flywheel.paradigma.inc
 ```
 
+For an authorized controller that already has an API key, the installed
+`flywheel setup --mode <cli|mcp> --api-key-stdin` command accepts one private
+stdin stream without browser/device authentication. It rejects terminal input,
+empty or multiline values, surrounding whitespace, more than 4096 bytes, and
+conflicts with `--api-key`, `--oauth`, or an explicit `--auth-mode`. One final LF
+is optional. Do not capture the key in arguments, environment variables, logs,
+or temporary files, and do not pipe it through package-download commands.
+
+CLI mode requires a credential-consuming host such as Codex; empty or
+skill-only selections fail rather than leaving the supplied key unused. It
+writes the supplied key to the runtime credential file, not to an OS credential
+store: `$XDG_CONFIG_HOME/flywheel/credentials.json` when XDG is absolute,
+otherwise `$HOME/.config/flywheel/credentials.json` on POSIX, or
+`%APPDATA%\Flywheel\credentials.json` on native Windows. The file contains a
+plaintext API key and is private to the user account, but applications running
+as that user can read it; it does not provide Keychain-style per-application
+access controls. File storage does not change the key's server-side expiry,
+permissions, or revocation.
+
+CLI login/setup persists the credential before its non-secret runtime TOML. If
+that later TOML save fails, repair the configuration path and reconcile the
+retained credential before retrying; do not expect Flywheel to delete it or
+issue another key automatically.
+
+`auth:credentials:clear` removes only its local profile entry; generic
+uninstall retains the credential file and does not revoke the key. Existing
+keychain-only profiles must sign in once per profile (`flywheel auth:login` or
+`flywheel auth:login --env <profile>`); setup never reads or deletes their old
+keychain entries. Stdin-enabled MCP setup supports only Codex in the home
+directory (`--codex`, without `--project` or other hosts). It atomically writes
+its persistent mode-0600 config in an owner-only directory.
+It refuses an existing different credential unless explicitly authorized with
+`--force`. A post-rename durability failure is an uncertain commit: reconcile
+the config and revoke that issued key before retrying. Internal staging
+controllers should follow the `create-flywheel-accounts` and
+`flywheel-installer` operator skills for receipt-based cleanup and installer
+stdin ownership.
+
 ## 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.
+`setup --mode cli` provisions runtime configuration. MCP-only and skill-only
+setup paths leave runtime configuration untouched.
 
-On successful authentication, the setup writes a JSON config at:
+On successful CLI-mode authentication, setup writes a versioned TOML config at:
 
-- `FLYWHEEL_CLI_CONFIG_PATH` (when set)
-- `$HOME/.config/flywheel-cli/config.json` (default)
+- `FLYWHEEL_CLI_CONFIG_PATH` (when set; relative values resolve from the current directory)
+- `$XDG_CONFIG_HOME/flywheel/config.toml` when XDG is absolute
+- `$HOME/.config/flywheel/config.toml` (POSIX fallback)
+- `%APPDATA%\Flywheel\config.toml` (native Windows)
 
 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`.
 
+Runtime configuration stays in TOML while runtime credentials use the separate
+credential file. `FLYWHEEL_CLI_CONFIG_PATH` changes only the TOML path; it never
+relocates credentials. The [installation guide](../flywheel-docs/content/docs/install.mdx)
+documents the credential schema, legacy migration and partial-state recovery,
+ownership-aware uninstall, and the platform matrix. Native Windows supports
+hosted commands but not local repository commands. Local repositories support
+macOS and Linux on arm64/x64, including WSL and Alpine Linux, using the bundled
+filesystem helper and the installed Node.js runtime.
+
+Direct-copy `universal` and `antigravity` setup does not create
+`skills-lock.json`; that file belongs only to hosts installed through the
+`skills` package.
+
 ## Argument Syntax (Runtime Commands)
 
 Runtime commands (`auth:*`, `nodes:*`, `artifacts:*`, `compute:*`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.115",
+  "version": "0.1.134",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [
@@ -22,13 +22,17 @@
     "@inquirer/prompts": "^8.2.0",
     "commander": "^14.0.1",
     "js-yaml": "^4.1.0",
-    "open": "^10.2.0",
+    "node-gyp-build": "4.8.4",
+    "open": "^11.0.1",
     "ora": "^9.0.0",
     "picocolors": "^1.1.1",
     "semver": "^7.8.0",
     "skills": "1.4.7",
-    "string-width": "^8.2.0",
-    "wrap-ansi": "^10.0.0"
+    "smol-toml": "1.8.0",
+    "string-width": "^8.2.2",
+    "wrap-ansi": "^10.0.1",
+    "yauzl": "3.4.0",
+    "yazl": "3.3.1"
   },
   "repository": {
     "type": "git",
@@ -36,7 +40,11 @@
     "directory": "project/flywheel-setup"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^24.15.0 || >=25.7.0"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "acorn": "^8.18.0",
+    "unbash": "file:scripts/vendor/unbash-4.0.10-patched.tgz"
+  }
 }

package/skills/flywheel/SKILL.md

@@ -11,9 +11,9 @@ Use this skill to structure research work and to route setup/support questions t
 
 Use this skill when the conversation is about any of the following:
 
-- planning experiments, hypotheses, comparisons, or next-branch decisions
+- planning exploratory or empirical work, hypotheses, comparisons, or next-branch decisions
 - running or interpreting empirical work in Flywheel
-- choosing between `insight` and `empirical` nodes
+- recording research context with node titles, content, summaries, tags, or artifacts
 - 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
@@ -24,12 +24,15 @@ If the request is ambiguous, default to experiment-design guidance before platfo
 
 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: run the curl installer with `--mode cli` or use the managed-prefix npm install recipe from the README.
+- **`--mode mcp` install on an MCP-capable host:** setup writes host-specific MCP configuration; route via [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and use the host's `flywheel_<tool>` surface.
+- **`--mode mcp` install on a skill-only host:** setup skips MCP configuration, so no `flywheel_<tool>` surface exists. Route work through a separately configured CLI, subject to the CLI caveat below.
+- **`--mode cli` install**: route via [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md); direct CLI calls take the form `flywheel <command>` (for example, `flywheel hosted:node:set`). `setup --mode cli` installs or refreshes bundled skills and writes CLI runtime TOML; it does not write an MCP host entry. If every selected host is skill-only (for example, Universal or Antigravity), setup installs only skills and skips CLI authentication and runtime configuration; do not assume the CLI is configured.
 
-When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+Running setup through `npx` configures settings and skills; it does not install a persistent `flywheel` binary. If `flywheel` is not on `PATH`, replace `flywheel` with `npx --yes @paradigma-inc/flywheel` in every CLI example below and in the linked tool map.
+
+For CLI writes, choose the destination explicitly. Use `repo:` only for an explicit `--repo` repository, an explicitly requested `--personal` repository, or a repository found from the current directory. Local `repo:` mutations stage changes; `repo:commit` creates the local commit; `repo:push` publishes only when requested. If no valid local repository is selected, stop and ask rather than falling back to hosted storage. For an identified hosted graph, use `hosted:` mutations with `--repository-id <uuid>`; each posts a hosted commit immediately. For MCP, keep the staged body caller-local: create nodes with `flywheel_commit_new_node` using `local_temp_node_id`, `parent_ids`, and the staged payload; update existing nodes by reading, acquiring a stage lease with the observed committed revision, then calling `flywheel_commit_node` with `stage_session_id`, `base_committed_revision`, and the full staged payload. Reconcile a `409` before retrying.
 
-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.
+When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
 
 ## Workflow
 

package/skills/flywheel/example-workflows/organizing-exploring-and-iterating-on-a-research-topic.md

@@ -1,6 +1,6 @@
 # Organizing, Exploring, and Iterating on a Research Topic
 
-> The tool lists below are inferred from the current [Flywheel MCP tool map](../references/flywheel-mcp-tool-map.md). They are likely tool sequences for each step, not verbatim execution logs.
+> The tool lists below use canonical Flywheel MCP names from the current [Flywheel MCP tool map](../references/flywheel-mcp-tool-map.md). Host wrappers vary; use the exposed canonical tool. `flywheel_commit_new_node` takes caller-local `local_temp_node_id`, `parent_ids`, and a staged payload without a lease. Every `flywheel_commit_node` reference means the existing-node flow: read, acquire a lease with a caller `stage_session_id` and observed committed revision, then commit the full staged payload with `stage_session_id` and `base_committed_revision`.
 
 ## Image Description
 
@@ -34,11 +34,10 @@ 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_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.
+- `flywheel_commit_new_node` to create the root `scheduled muon` graph.
+- `flywheel_commit_node` to describe the overall research question and first branch.
+- `flywheel_branch_node` to split the root into experiment branches.
+- `flywheel_get_node_tree` to inspect the DAG as it starts to fill out.
 
 ---
 
@@ -54,9 +53,8 @@ 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_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.
+- `flywheel_branch_node` to open an insight branch for the core muon observation.
+- `flywheel_commit_node` to record the singular-value flattening concern as an explicit insight or hypothesis.
 
 ---
 
@@ -72,9 +70,8 @@ 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_commit_node` to capture the "softer interpolation" idea between SGD and muon.
-- `mcp__flywheel__flywheel_commit_node` to save the refined hypothesis before experimenting.
+- `flywheel_branch_node` to fork a new hypothesis branch from the original muon observation.
+- `flywheel_commit_node` to capture the "softer interpolation" idea between SGD and muon.
 
 ---
 
@@ -90,10 +87,9 @@ 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_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.
+- `flywheel_commit_new_node` or `flywheel_branch_node` to turn scattered runs into explicit branches instead of an untracked run log.
+- `flywheel_list_nodes` to enumerate existing branches and runs.
+- `flywheel_get_node_tree` to inspect the structure of the experiment graph.
 
 ---
 
@@ -109,11 +105,10 @@ then, [@thelokasiffers](https://x.com/thelokasiffers) released an early version
 
 ### Likely Flywheel MCP tools for this step
 
-- `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.
-- `mcp__flywheel__flywheel_commit_node` to preserve the graph state.
+- `flywheel_commit_new_node` to create the root node if it did not already exist.
+- `flywheel_branch_node` to fan the work into separate experiment branches.
+- `flywheel_get_node_tree` to inspect the resulting DAG layout.
+- `flywheel_summarize_node_tree` to quickly understand branch progress and outcomes.
 
 ### Image Description
 
@@ -135,9 +130,8 @@ 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_commit_node` to store the proposed fractional-power formulation.
-- `mcp__flywheel__flywheel_commit_node` to save the idea before turning it into experiments.
+- `flywheel_branch_node` to create an insight branch for the `US^pV^T` intuition.
+- `flywheel_commit_node` to store the proposed fractional-power formulation.
 
 ---
 
@@ -153,9 +147,8 @@ 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_commit_node` to record the new approximation strategy.
-- `mcp__flywheel__flywheel_commit_node` to preserve the new line of attack.
+- `flywheel_branch_node` to open a follow-up hypothesis branch around polynomial approximations.
+- `flywheel_commit_node` to record the new approximation strategy.
 
 ---
 
@@ -171,11 +164,11 @@ 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_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.
+- `flywheel_branch_node` to create the empirical branch for the spectra sanity check.
+- `flywheel_commit_node` to record the hypothesis and evaluation criteria.
+- `flywheel_request_compute_grant_approval`, `flywheel_compute_acquire`, `flywheel_compute_status`, and `flywheel_compute_connection` to run the experiments on managed compute.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach the singular-value plot as an artifact.
+- `flywheel_commit_node` to mark the empirical step as completed.
 
 ### Image Description
 
@@ -197,9 +190,8 @@ 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_commit_node` to record the competing schedule hypotheses.
-- `mcp__flywheel__flywheel_commit_node` to preserve the question before launching more runs.
+- `flywheel_branch_node` to fork a new investigation around schedule design.
+- `flywheel_commit_node` to record the competing schedule hypotheses.
 
 ---
 
@@ -215,13 +207,13 @@ 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_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.
-- `mcp__flywheel__flywheel_get_node_tree` or `mcp__flywheel__flywheel_list_executions` to monitor the graph as the runs progress.
-- `mcp__flywheel__flywheel_commit_node` to finalize each completed empirical branch.
+- `flywheel_branch_node` to split the root into separate schedule and learning-rate branches.
+- `flywheel_commit_node` to encode the hypotheses and sweep definitions.
+- `flywheel_request_compute_grant_approval` and `flywheel_list_compute_grants` to secure spend before launch.
+- `flywheel_compute_acquire`, `flywheel_compute_status`, and `flywheel_compute_connection` to provision GPUs and keep them available to the agent.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach result plots and cards as branches finish.
+- `flywheel_get_node_tree` or `flywheel_list_executions` to monitor the graph as the runs progress.
+- `flywheel_commit_node` to finalize each completed empirical branch.
 
 ### Image Description
 
@@ -249,7 +241,7 @@ i won't spoil for you how this ends. because this will soon be a public graph in
 
 ### Likely Flywheel MCP tools for this step
 
-- `mcp__flywheel__flywheel_get_node_sharing` to inspect the current sharing state before changing it.
-- `mcp__flywheel__flywheel_set_sharing_for_node` or `mcp__flywheel__flywheel_set_sharing_for_nodes` to share the graph with co-authors or make it public.
-- `mcp__flywheel__flywheel_get_node_sharing` again to verify that the sharing settings are correct.
-- `mcp__flywheel__flywheel_export_summary` or `mcp__flywheel__flywheel_export_subgraph` to package the graph for outside review or reuse.
+- `flywheel_get_node_sharing` to inspect the current sharing state before changing it.
+- `flywheel_set_sharing_for_node` or `flywheel_set_sharing_for_nodes` to share the graph with co-authors or make it public.
+- `flywheel_get_node_sharing` again to verify that the sharing settings are correct.
+- `flywheel_export_summary` or `flywheel_export_subgraph` to package the graph for outside review or reuse.

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

@@ -1,6 +1,6 @@
 # Reproducing Papers on a Budget
 
-> The tool lists below are inferred from the current [Flywheel MCP tool map](../references/flywheel-mcp-tool-map.md). They are likely tool sequences for each step, not verbatim execution logs.
+> The tool lists below use canonical Flywheel MCP names from the current [Flywheel MCP tool map](../references/flywheel-mcp-tool-map.md). Host wrappers vary; use the exposed canonical tool. `flywheel_commit_new_node` takes caller-local `local_temp_node_id`, `parent_ids`, and a staged payload without a lease. Every `flywheel_commit_node` reference means the existing-node flow: read, acquire a lease with a caller `stage_session_id` and observed committed revision, then commit the full staged payload with `stage_session_id` and `base_committed_revision`.
 
 ## [@tensorqt](https://x.com/tensorqt) · [13 Mar 2026, 9:34 pm](https://x.com/tensorqt/status/2032555892399305171)
 
@@ -8,11 +8,10 @@ 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_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_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.
+- `flywheel_commit_new_node` to create the root reproduction graph or first node for the paper.
+- `flywheel_branch_node` to split the paper into parallel validation branches.
+- `flywheel_commit_node` to capture the paper claim, reproduction plan, and budget constraint.
+- `flywheel_request_compute_grant_approval` to enforce the "$10 max" spend before managed compute starts.
 
 ### Image Description
 
@@ -38,11 +37,11 @@ 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_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.
+- `flywheel_branch_node` to open the first empirical branch for the baseline correlation check.
+- `flywheel_commit_node` to record the hypothesis and experiment setup.
+- `flywheel_compute_acquire`, `flywheel_compute_status`, and `flywheel_compute_connection` to provision and use the small A10 GPU.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach `attn_similarity_by_layer.png`.
+- `flywheel_commit_node` to mark the step as a completed empirical result.
 
 ### Image Description
 
@@ -58,11 +57,11 @@ 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_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.
+- `flywheel_branch_node` to create the next experimental branch.
+- `flywheel_commit_node` to record the orthogonality hypothesis for XSA.
+- `flywheel_compute_acquire`, `flywheel_compute_status`, and `flywheel_compute_connection` to run the projection check.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach `orthogonality_by_layer.png`.
+- `flywheel_commit_node` to finalize the branch.
 
 ### Image Description
 
@@ -78,11 +77,11 @@ 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_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.
+- `flywheel_branch_node` to fork an efficiency-comparison branch.
+- `flywheel_commit_node` to define the runtime and VRAM hypothesis.
+- `flywheel_compute_acquire`, `flywheel_compute_status`, and `flywheel_compute_connection` to run the matched SA vs XSA benchmark.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach `efficiency_comparison.png`.
+- `flywheel_commit_node` to finalize the overhead measurement.
 
 ### Image Description
 
@@ -98,11 +97,11 @@ 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_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.
+- `flywheel_branch_node` to create the larger training branch.
+- `flywheel_commit_node` to record the 50M-parameter comparison and evaluation criteria.
+- `flywheel_compute_acquire`, `flywheel_compute_status`, and `flywheel_compute_connection` to run the longer training jobs.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach `run_metrics.csv` and `quality_pairs.csv`.
+- `flywheel_commit_node` to record that the empirical result did not reproduce the expected gain.
 
 ### Image Description
 
@@ -118,11 +117,10 @@ Also, across sequence length, the trend seems to worsen.
 
 ### Likely Flywheel MCP tools for this step
 
-- `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_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.
+- `flywheel_branch_node` to spin off an analysis branch for context length.
+- `flywheel_get_node` and `flywheel_list_artifacts` to gather results from the completed training branches.
+- `flywheel_commit_node` to record the interpretation that the delta worsens at longer context.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach `length_trend.png`.
 
 ### Image Description
 
@@ -138,11 +136,11 @@ 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_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.
+- `flywheel_branch_node` to create a robustness branch for LR sweeps and sink-style perturbations.
+- `flywheel_commit_node` to capture the robustness hypothesis.
+- `flywheel_compute_acquire`, `flywheel_compute_status`, and `flywheel_compute_connection` to run the compact sweep experiments.
+- `flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, and `flywheel_finalize_artifact_uploads` to attach `robustness_deltas.png`.
+- `flywheel_commit_node` to finalize the robustness verdict.
 
 ### Image Description
 

package/skills/flywheel/getting-started/flywheel-quickstart.md

@@ -13,11 +13,8 @@ npx --yes @paradigma-inc/flywheel uninstall
 npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
-If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.
+If your previous install used a server name different from `flywheel`, use the matching host's selected-entry cleanup command in the [host installation guides](../setting-up-flywheel/); it must include both the host selector and `--name "<old-name>"`.
 
-If your MCP host is not supported by `npx --yes @paradigma-inc/flywheel setup --mode mcp`, use manual host configuration:
-
-- URL: `https://flywheel.paradigma.inc/mcp-server`
-- Header: `Authorization: Bearer <YOUR_MCP_API_KEY>`
+For manual configuration, see [Other MCP hosts](../setting-up-flywheel/other-hosts-installation.md). It documents the supported current Codex TOML form; use `setup --mode mcp --<host>` for the other supported hosts rather than guessing a host-config shape.
 
 For hosts that support MCP OAuth connector installs, you can also use the host-native OAuth connector flow with `https://flywheel.paradigma.inc/mcp-server`.

package/skills/flywheel/references/INTERFACES.md

@@ -58,7 +58,7 @@ direct-neighbor traversal.
 - `flywheel_get_node_tree` (read; scopes: `read`; full-surface only; binding: `operation`)
 - `flywheel_get_node_ancestry` (read; scopes: `read`; full-surface only; binding: `operation`)
 - `flywheel_get_campaign_snapshot` (read; scopes: `read`; core surface; binding: `operation`)
-- `flywheel_list_audit` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_admin_nodes_audit_list` (admin-only read; scopes: `read`; full-surface only; binding: `operation`)
 
 ### Node stage and commit
 
@@ -145,7 +145,7 @@ direct-neighbor traversal.
 - `GET /nodes/{node_id}/tree` -> `flywheel_get_node_tree`
 - `GET /nodes/{node_id}/ancestry` -> `flywheel_get_node_ancestry`
 - `GET /nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
-- `GET /nodes/{node_id}/audit` -> `flywheel_list_audit`
+- `GET /admin/nodes/{node_id}/audit` -> `flywheel_admin_nodes_audit_list` (admin only)
 
 ### Node stage and commit
 

package/skills/flywheel/references/experiment-design-protocol.md

@@ -19,7 +19,7 @@ Help the user clarify what they are trying to learn, shape the work around that
 - Propose defaults for structural choices such as experiment shape, stop condition, or artifact plan. Use questions rather than defaults for epistemic choices such as beliefs, assumptions, and what evidence would matter.
 - When a reasoning or design gap is visible, raise it as a question rather than an assertion.
 - If the core gate is satisfied and the user wants to proceed, stop asking more design questions.
-- Use Flywheel `insight` nodes to preserve design context when it will help across turns or sessions.
+- Use Flywheel nodes to preserve design context when it will help across turns or sessions.
 
 ## Phase 1: Clarify what the user is trying to learn
 
@@ -43,7 +43,7 @@ If the work is exploratory, ask:
 - What is the cheapest or cleanest way to learn that first piece?
 - What signal or pattern are you looking for?
 
-If the user is still fuzzy after this phase, stay in planning mode. If needed, create or update an `insight` node rather than an `empirical` node.
+If the user is still fuzzy after this phase, stay in planning mode. If needed, record planning or exploratory content rather than launching an empirical probe.
 
 ## Phase 2: Shape the work
 
@@ -117,35 +117,42 @@ If the run is expensive or high-risk, ask for explicit confirmation.
 
 ## Phase 5: Drive Flywheel
 
-Use Flywheel in layers when possible.
-
-Before execution, load `references/flywheel-mcp-tool-map.md` and verify the
-exact tool surface exposed by the current MCP host before critical flows.
+Use the active configured interface throughout design, execution, and result
+persistence, following this skill's installation-mode guidance. A skill-only
+MCP install uses a separately configured CLI, not an MCP tool surface; do not
+assume that installing the skill configured the CLI.
+
+1. **Active MCP interface:** verify that the active MCP host exposes the required
+   tool surface, then load this skill's [MCP tool map](flywheel-mcp-tool-map.md).
+   Use its design, empirical, and final-result flows. If that surface is not
+   available, do not substitute CLI commands; configure the intended interface
+   or explain the blocker. Its caller-local new-node payload flow is distinct
+   from its existing-node session-stage-lease and full-payload commit flow; do
+   not recast either as a CLI repository commit.
+2. **Active CLI interface (including skill-only MCP installs):** load this skill's
+   [CLI tool map](flywheel-cli-tool-map.md). First determine the destination:
+   use its Local authoring workflow for an identified local repository
+   (stage, commit locally, and push only when publication is requested), or its
+   direct hosted/Empirical Workflow for an identified hosted repository
+   (immediate hosted commits). If the destination is unknown, ask before
+   writing; a missing local repository is not a reason to switch to hosted
+   storage.
 
 ### Design layer
 
-Use an `insight` node to capture rationale, open questions, experiment shape, and any decomposition needed for exploratory or multi-stage work.
-
-Typical flow:
-
-1. `mcp__flywheel__flywheel_commit_new_node`
-2. `mcp__flywheel__flywheel_acquire_stage_lease` when refining an existing design node
-3. `mcp__flywheel__flywheel_commit_node` once the design brief is coherent
+Persist rationale, open questions, experiment shape, and exploratory or
+multi-stage decomposition through the selected map's matching write flow.
+Preserve the interface and destination choice while refining that design; do
+not mix MCP staged payloads with CLI local or hosted commit semantics.
 
 ### Execution layer
 
-Only after the design gate passes, create or branch the node for the runnable part of the work.
-
-Typical flow:
-
-1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_commit_new_node`
-2. `mcp__flywheel__flywheel_acquire_stage_lease` + `mcp__flywheel__flywheel_commit_node` with the explicit run summary and the local question or hypothesis for that branch
-3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
-4. `mcp__flywheel__flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)` when you need to resolve the approved `compute_grant_id`
-5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed
-6. `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, then `mcp__flywheel__flywheel_finalize_artifact_uploads`
-7. Do a brief epistemic check before commit: verify what the evidence actually shows, whether it matches the interpretation rule from the brief, and whether any gap between the data and the hoped-for story needs to be named explicitly in the node summary.
-8. `mcp__flywheel__flywheel_commit_node`
+Only after the design gate passes, create or branch the runnable work through
+the selected map. For managed compute, follow that map's Empirical Workflow
+end-to-end: catalog selection, approval, grant resolution, acquisition,
+execution, evidence artifacts, and the final result persistence path. Before
+that final result write, check that the evidence supports the interpretation
+and name any gap in the summary.
 
 Important notes: