@paradigma-inc/flywheel 0.1.26 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.26",
+  "version": "0.1.35",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "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/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.

package/skills/flywheel/references/INTERFACES.md

@@ -0,0 +1,206 @@
+# Interfaces
+
+Canonical reference for Flywheel MCP public interfaces and contract pointers.
+
+## Canonical Contract References
+
+- `flywheel_get_contract` is the top-level contract entry point.
+- `flywheel_get_contract_section(section_id)` returns section-scoped payloads.
+- Section order:
+- `quickstart` (Quickstart): Recommended first calls and section read order for onboarding.
+- `graph` (Graph): Node model, graph topology guidance, and durable behavior rules.
+- `stage_commit` (Stage and commit): Stage/commit operations, commit-time validation requirements, and reproducibility guidance.
+- `sharing` (Sharing): Sharing modes, derived visibility, collaborator roles, and query translation.
+- `artifacts` (Artifacts): Prepare/upload/finalize requirements and artifact type rules.
+- `compute` (Compute): Lease ownership, token-scoped control, approval session, and budget source semantics.
+- `compute/troubleshooting_v1` (Compute Troubleshooting v1): Provider-specific acquire/retry hints for launch kwargs and request tuning.
+- `campaign` (Campaign Contract): Campaign projection and budget contracts plus template section pointers.
+
+## Canonical Entity Model
+
+- Canonical durable entity: `node`.
+- Node kind values: `untyped`, `empirical`, `insight`.
+- Node references: `node_id`, `slug_name`.
+- `slug_name` format: `adjective-noun-####` (immutable when present).
+- Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
+- Campaign projections are derived from root config and attempt submission JSON artifacts.
+
+## MCP Tool Surface
+
+### Discovery and sharing
+
+- `flywheel_auth_status` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_credits_balance` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_updates_list` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_updates_hide` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_updates_unhide` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_list_nodes` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_resolve_node_slug` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_sharing` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `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`)
+
+### Node stage and commit
+
+- `flywheel_commit_new_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_commit_node` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_branch_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_merge_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_add_parent` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_remove_parent` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_delete_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+
+### Artifacts
+
+- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; core surface; binding: `binding_helper`)
+- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; core surface; binding: `binding_helper`)
+- `flywheel_list_artifacts` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_artifact` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_delete_artifact` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_set_artifact_note` (mutating; scopes: `write`; core surface; binding: `operation`)
+
+### Executions
+
+- `flywheel_launch_execution` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_list_executions` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_terminate_execution` (mutating; scopes: `write`; core surface; binding: `operation`)
+
+### Compute and budgets
+
+- `flywheel_compute_list_options` (read; scopes: `compute`; core surface; binding: `operation`)
+- `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_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`)
+- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_compute_grants` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_campaign_budgets` (read; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_create_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_update_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_revoke_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_release` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; core surface; binding: `operation`)
+
+### Contract, audit, and export
+
+- `flywheel_get_contract` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_contract_section` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_export_subgraph` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_import_subgraph` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_summarize_node_tree` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_stream` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_pdf` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_render_pdf` (read; scopes: `read`; full-surface only; binding: `operation`)
+
+## HTTP Surface
+
+### Discovery and sharing
+
+- `GET /auth/status` -> `flywheel_auth_status`
+- `GET /credits` -> `flywheel_get_credits_balance`
+- `tool-mediated` -> `flywheel_updates_list`
+- `POST /updates/{announcement_id}/hide` -> `flywheel_updates_hide`
+- `POST /updates/hide-all-active` -> `flywheel_updates_hide_all_active`
+- `DELETE /updates/{announcement_id}/hide` -> `flywheel_updates_unhide`
+- `GET /nodes` -> `flywheel_list_nodes`
+- `GET /nodes/resolve-by-slug` -> `flywheel_resolve_node_slug`
+- `tool-mediated` -> `flywheel_get_node_sharing`
+- `tool-mediated` -> `flywheel_set_sharing_for_node`
+- `POST /nodes/access-policy/bulk` -> `flywheel_set_sharing_for_nodes`
+- `tool-mediated` -> `flywheel_get_node`
+- `POST /nodes/{root_node_id}/tags` -> `flywheel_create_node_tag`
+- `PATCH /nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_update_node_tag`
+- `DELETE /nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_delete_node_tag`
+- `PUT /nodes/{node_id}/tags` -> `flywheel_set_node_tag_assignments`
+- `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`
+
+### Node stage and commit
+
+- `POST /nodes/commit-new` -> `flywheel_commit_new_node`
+- `POST /nodes/{node_id}/stage/lease/acquire` -> `flywheel_acquire_stage_lease`
+- `POST /nodes/{node_id}/stage/lease/heartbeat` -> `flywheel_heartbeat_stage_lease`
+- `POST /nodes/{node_id}/stage/lease/release` -> `flywheel_release_stage_lease`
+- `POST /nodes/{node_id}/commit` -> `flywheel_commit_node`
+- `POST /nodes/{node_id}/branch` -> `flywheel_branch_node`
+- `POST /nodes/merge` -> `flywheel_merge_nodes`
+- `POST /nodes/{node_id}/parents/add` -> `flywheel_add_parent`
+- `POST /nodes/{node_id}/parents/remove` -> `flywheel_remove_parent`
+- `DELETE /nodes/{node_id}` -> `flywheel_delete_node`
+- `POST /nodes/bulk-delete` -> `flywheel_bulk_delete_nodes`
+
+### Artifacts
+
+- `POST /nodes/{node_id}/artifacts/uploads/prepare` -> `flywheel_prepare_artifact_uploads`
+- `POST /nodes/{node_id}/artifacts/uploads/finalize` -> `flywheel_finalize_artifact_uploads`
+- `tool-mediated` -> `flywheel_list_artifacts`
+- `tool-mediated` -> `flywheel_get_artifact`
+- `DELETE /nodes/{node_id}/artifacts/{artifact_id}` -> `flywheel_delete_artifact`
+- `PATCH /nodes/{node_id}/artifacts/{artifact_id}/note` -> `flywheel_set_artifact_note`
+
+### Executions
+
+- `POST /nodes/{node_id}/executions` -> `flywheel_launch_execution`
+- `GET /nodes/{node_id}/executions` -> `flywheel_list_executions`
+- `POST /nodes/{node_id}/executions/{execution_id}/terminate` -> `flywheel_terminate_execution`
+
+### Compute and budgets
+
+- `GET /compute/catalog` -> `flywheel_compute_list_options`
+- `GET /compute/funding` -> `flywheel_compute_funding`
+- `GET /compute/status` -> `flywheel_compute_status`
+- `GET /compute/connection` -> `flywheel_compute_connection`
+- `POST /approval-sessions/heartbeat` -> `flywheel_approval_session_heartbeat`
+- `GET /approval-sessions` -> `flywheel_list_approval_sessions`
+- `POST /approval-sessions/expire` -> `flywheel_expire_approval_session`
+- `tool-mediated` -> `flywheel_request_compute_grant_approval`
+- `GET /compute/grants` -> `flywheel_list_compute_grants`
+- `GET /nodes/{root_node_id}/campaign-budgets` -> `flywheel_list_campaign_budgets`
+- `POST /nodes/{root_node_id}/campaign-budgets` -> `flywheel_create_campaign_budget`
+- `PATCH /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_update_campaign_budget`
+- `DELETE /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_revoke_campaign_budget`
+- `tool-mediated` -> `flywheel_compute_acquire`
+- `tool-mediated` -> `flywheel_compute_release`
+- `tool-mediated` -> `flywheel_compute_release_all`
+
+### Contract, audit, and export
+
+- `GET /mcp/contract` -> `flywheel_get_contract`
+- `GET /mcp/contract/sections/{section_id}` -> `flywheel_get_contract_section`
+- `POST /export` -> `flywheel_export_subgraph`
+- `POST /import` -> `flywheel_import_subgraph`
+- `GET /nodes/{node_id}/summary` -> `flywheel_summarize_node_tree`
+- `POST /export-summary` -> `flywheel_export_summary`
+- `POST /export-summary-stream` -> `flywheel_export_summary_stream`
+- `POST /export-summary-pdf` -> `flywheel_export_summary_pdf`
+- `POST /export-summary-render-pdf` -> `flywheel_export_summary_render_pdf`
+
+## Auth and Write Safety
+
+- Available scopes: `read`, `write`, `compute`.
+- Default grant scopes: `read`, `write`, `compute`.
+- Transport-required scopes: `read`.
+- Optimistic locking field: `expected_revision`.
+- Conflict status code: `409`.
+- Mutating HTTP calls require `Idempotency-Key`: `True`.
+- MCP tool transport manages idempotency keys for mutating calls: `True`.

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

@@ -128,9 +128,9 @@ Use an `insight` node to capture rationale, open questions, experiment shape, an
 
 Typical flow:
 
-1. `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update`
-3. `mcp__flywheel__flywheel_commit_node`
+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
 
 ### Execution layer
 
@@ -138,8 +138,8 @@ Only after the design gate passes, create or branch the `empirical` node for the
 
 Typical flow:
 
-1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update` with the explicit run summary and the local question or hypothesis for that branch
+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