@paradigma-inc/flywheel 0.1.11 → 0.1.13

package/package.json

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

package/skills/flywheel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flywheel
-description: Use for Flywheel experiment design, turning source material into Flywheel graphs, staged frontier planning with `/lookahead`, budgeted autonomous research with `/fsd`, MCP-assisted execution, and platform setup/troubleshooting across supported hosts.
+description: General Flywheel guidance for experiment design, MCP/tool-contract questions, and setup or troubleshooting across supported hosts. Use for platform support or cross-cutting guidance, not concrete graph-authoring tasks covered by the specialized Flywheel skills.
 ---
 
 # Flywheel Skill
@@ -12,9 +12,6 @@ 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
-- turning source material into a Flywheel graph
-- using command-like Flywheel workflows such as `/to-graph`, `/reproduce`,
-  `/lookahead`, or `/fsd`
 - running or interpreting empirical work in Flywheel
 - choosing between `insight` and `empirical` nodes
 - setting up, updating, authenticating, or troubleshooting Flywheel MCP
@@ -26,24 +23,18 @@ If the request is ambiguous, default to experiment-design guidance before platfo
 
 1. Classify the request as research guidance, platform support, or mixed.
 2. Load only the minimum files needed for the current task.
-3. If the user is using command-like language such as `/to-graph`,
-   `/reproduce`, `/lookahead`, or `/fsd`, load
-   `reference/command-presets.md` first.
-4. For research requests, run a short design pass before execution:
+3. For research requests, run a short design pass before execution:
    ask 1-2 questions to clarify objective, assumptions, and decision criteria.
-5. If design is solid and the user wants to proceed, shift to execution support.
-6. Use Flywheel MCP tools for live behavior/contract checks when available.
-7. Summarize evidence and propose the most likely next branch.
+4. If design is solid and the user wants to proceed, shift to execution support.
+5. Use Flywheel MCP tools for live behavior/contract checks when available.
+6. Summarize evidence and propose the most likely next branch.
 
 ## Routing Map
 
 Choose one primary file first, then add at most one supporting file only if needed:
 
-- `reference/experiment-design-protocol.md` for structured experiment design and readiness checks
-- `reference/command-presets.md` for `/to-graph`, `/reproduce`, `/lookahead`,
-  and `/fsd`
-- `reference/wiki-porting.md` when the user asks to port a markdown/wiki corpus
-- `reference/flywheel-mcp-tool-map.md` for exact tool surface and contract behavior
+- `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
 - `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
@@ -59,12 +50,3 @@ Choose one primary file first, then add at most one supporting file only if need
 - Prefer concrete steps and decision points over long narrative explanations.
 - Do not run broad document reads; load only what is required by the current request.
 - Do not start compute-heavy execution before design intent is clear.
-- Keep `/reproduce` narrow: validate existing knowledge claims rather than
-  expanding an open-ended research frontier.
-- Treat `/lookahead` as planning only and `/fsd` as budgeted autonomous
-  frontier advancement.
-
-## Wiki Porting
-
-When asked to port a markdown wiki, load `reference/wiki-porting.md` before
-acting.

package/skills/flywheel/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Flywheel"
-  short_description: "Guide Flywheel graph planning, research, and setup"
-  default_prompt: "Use $flywheel to answer Flywheel experiment, graph, setup, MCP tool, compute, campaign, or Web UI questions. Treat /to-graph as graph construction only, /reproduce as budgeted validation of existing knowledge, /lookahead as staged frontier planning, and /fsd as budgeted autonomous frontier advancement that stays n steps ahead."
+  short_description: "Guide Flywheel experiment design, setup, tools, and workflows"
+  default_prompt: "Use $flywheel to answer Flywheel experiment, setup, MCP tool, compute, campaign, or Web UI questions."
 
 dependencies:
   tools:

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](../reference/flywheel-mcp-tool-map.md). They are likely tool sequences for each step, not verbatim execution logs.
+> 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.
 
 ## Image Description
 
@@ -173,8 +173,8 @@ at this point i started testing this out, would i get really the right spectra?
 
 - `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_request_budget_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_publish` to attach the singular-value plot as an artifact.
+- `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.
 
 ### Image Description
@@ -217,9 +217,9 @@ but which way should we schedule? not clear. is it sgd first or muon first? how
 
 - `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_request_budget_approval` and `mcp__flywheel__flywheel_list_budget_grants` to secure spend before launch.
+- `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_publish` to attach result plots and cards as branches finish.
+- `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.
 
@@ -249,7 +249,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_set_node_access_policy` to share the graph with co-authors or make it public.
-- `mcp__flywheel__flywheel_bulk_set_node_access_policy` to apply the same policy across many branches.
-- `mcp__flywheel__flywheel_get_node_access_policy` to verify that the sharing settings are correct.
+- `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.

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](../reference/flywheel-mcp-tool-map.md). They are likely tool sequences for each step, not verbatim execution logs.
+> 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.
 
 ## [@tensorqt](https://x.com/tensorqt) · [13 Mar 2026, 9:34 pm](https://x.com/tensorqt/status/2032555892399305171)
 
@@ -11,7 +11,7 @@ A really interesting way of using Flywheel is to reproduce papers on a budget: I
 - `mcp__flywheel__flywheel_stage_node_create` 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_request_budget_approval` to enforce the "$10 max" spend before managed compute starts.
+- `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.
 
 ### Image Description
@@ -41,7 +41,7 @@ The model decides to play it safe: it starts by showing self-attention correlati
 - `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_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_publish` to attach `attn_similarity_by_layer.png`.
+- `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.
 
 ### Image Description
@@ -61,7 +61,7 @@ Step two is analogous: orthogonality before and after XSA.
 - `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_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the projection check.
-- `mcp__flywheel__flywheel_prepare_artifact_publish` to attach `orthogonality_by_layer.png`.
+- `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.
 
 ### Image Description
@@ -81,7 +81,7 @@ Then, it moves to overhead of the orthogonal projection.
 - `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_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_publish` to attach `efficiency_comparison.png`.
+- `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.
 
 ### Image Description
@@ -101,7 +101,7 @@ Up to now, no trouble. The agent then decides to train a 50M parameter model wit
 - `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_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the longer training jobs.
-- `mcp__flywheel__flywheel_prepare_artifact_publish` to attach `run_metrics.csv` and `quality_pairs.csv`.
+- `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.
 
 ### Image Description
@@ -121,7 +121,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_prepare_artifact_publish` to attach `length_trend.png`.
+- `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.
 
 ### Image Description
@@ -141,7 +141,7 @@ At the same time, baseline seems to also win the LR sweeps.
 - `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_compute_acquire`, `mcp__flywheel__flywheel_compute_status`, and `mcp__flywheel__flywheel_compute_connection` to run the compact sweep experiments.
-- `mcp__flywheel__flywheel_prepare_artifact_publish` to attach `robustness_deltas.png`.
+- `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.
 
 ### Image Description

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

@@ -26,5 +26,5 @@ While in SWE we use git to manage changes to code, in research we are interested
 - [Using local hardware with Flywheel](../usage-and-workflows/using-local-hardware-with-flywheel.md)
 - [Participating in a Campaign](../campaigns/participating-in-a-campaign.md)
 - [OAuth client registration FAQ](../setting-up-flywheel/how-can-i-get-an-authorized-client_id-for-the-oauth-flow.md)
-- [Flywheel MCP tool map](../reference/flywheel-mcp-tool-map.md)
+- [Flywheel MCP tool map](../references/flywheel-mcp-tool-map.md)
 - [Example workflows](../example-workflows/)

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

@@ -0,0 +1,204 @@
+# Experiment Design Protocol
+
+Use this when the user needs help turning research intent into a well-formed experiment or exploration before spending compute.
+
+## Goal
+
+Help the user clarify what they are trying to learn, shape the work around that question, and avoid wasting compute before the design is solid.
+
+## Operating rules
+
+- Treat design and execution as separate phases.
+- Optimize for clarity of experimental purpose, not speed to a first run.
+- Adapt depth to the user's experience and the clarity already present in the conversation.
+- Apply epistemic discipline: separate what is known from what is assumed, and name uncertainty instead of smoothing it over.
+- Support both hypothesis-driven and exploratory work.
+- Support simple runs and complex shapes such as multi-stage pipelines, sweep-then-deep-dive, multi-arm comparisons, and custom structures.
+- Keep all 10 brief fields, but allow exploratory fields to be marked `exploratory` or `TBD` rather than fabricated.
+- Use quick Socratic questioning to surface assumptions, confidence, and what would change the user's mind. Keep it to 1-2 short questions per turn.
+- 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.
+
+## Phase 1: Clarify what the user is trying to learn
+
+Start with:
+
+1. What are you trying to learn or decide?
+2. Is this mainly hypothesis-driven or exploratory right now?
+
+Keep this phase quick. Ask 1-2 short questions per turn, and use light Socratic questioning as an epistemic check after the user states the learning goal: briefly surface what seems known versus assumed before moving on.
+
+If the work is hypothesis-driven, ask:
+
+- What is the hypothesis?
+- Compared to what baseline or alternative?
+- What result would matter?
+
+If the work is exploratory, ask:
+
+- What is the big question?
+- What would you need to learn first before tackling it?
+- 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.
+
+## Phase 2: Shape the work
+
+Choose or define the experiment shape through quick Socratic questioning:
+
+- single focused run
+- multi-stage pipeline
+- sweep then deep-dive
+- multi-arm comparison
+- custom shape
+
+If the user is unsure about structure, propose a default shape, stop condition, or artifact plan instead of extending the question loop.
+
+Then fill the experiment brief:
+
+- `question`: the decision or learning goal
+- `hypothesis`: the claim being tested
+- `comparator`: the baseline or alternative
+- `unit_of_work`: what one run, branch, or stage actually changes
+- `primary_metric`: the main number or observable to inspect
+- `artifact_plan`: which artifact will help interpret the result
+- `budget_cap`: max spend or runtime for the current stage
+- `stop_condition`: when to stop rather than letting the run expand
+- `interpretation`: what would count as signal, no signal, or ambiguity
+- `next_branch_if_inconclusive`: the follow-up branch if the result is unclear
+
+For exploratory work, `hypothesis` or `comparator` may be marked `exploratory` or `TBD`, but the learning goal still needs to be explicit.
+
+## Phase 3: Run the adaptive design gate
+
+Frame the gate as preventing waste, not enforcing bureaucracy.
+
+Always check:
+
+- the question or goal is explicit
+- at least one metric or observable is defined
+- a budget cap or stop condition exists
+
+For hypothesis-driven work, also check:
+
+- there is a falsifiable hypothesis
+- there is a comparator or baseline
+
+For exploratory work, instead check:
+
+- the user can say what they are looking for
+- the first learning step is scoped well enough to run
+
+Additional checks when relevant:
+
+- an artifact plan or `no_artifacts_reason` exists
+- the run shape matches the question and is not changing too many important things without purpose
+- an interpretation rule or next branch is defined
+
+If the core gate passes and the user wants to proceed, let them run even if some non-core details are still `TBD`.
+
+When blocked, ask only the next necessary question instead of reopening the whole brief.
+
+## Phase 4: Confirm the plan
+
+Before any compute request or training launch, restate:
+
+- what we are trying to learn
+- the experiment shape
+- the metric or observable
+- the artifact plan
+- the budget or stop condition
+- what result would change the next step
+
+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.
+
+### 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_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. `mcp__flywheel__flywheel_commit_node`
+
+### Execution layer
+
+Only after the design gate passes, create or branch the `empirical` node for the runnable part of the work.
+
+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
+3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
+4. `mcp__flywheel__flywheel_list_compute_grants` or `mcp__flywheel__flywheel_list_approval_sessions` 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`
+
+Important notes:
+
+- Exploratory work can stay in `insight` nodes until a specific empirical probe is ready.
+- Because `empirical` commits require a non-empty `hypothesis`, turn each runnable exploratory probe into a concrete local question or hypothesis for that branch.
+- For multi-stage or multi-arm work, use branches to represent stages or arms and keep summaries clear about how each branch feeds the next.
+- Completed empirical work needs artifacts or a `no_artifacts_reason`.
+
+## Adaptive question flow
+
+Ask in short batches of 1-2 questions per turn. Keep the flow light, Socratic, and epistemic rather than exhaustive.
+
+1. What are you trying to learn or decide?
+2. Is this hypothesis-driven or exploratory?
+3. Briefly separate what the user seems to know from what they seem to be assuming before locking the design.
+4. If hypothesis-driven: what is the hypothesis and compared to what?
+5. If exploratory: what is the first thing you need to learn and what is the cheapest way to learn it?
+6. What experiment shape fits this work?
+7. What metric or observable and artifact will you inspect?
+8. What budget or stop condition keeps this from wasting compute?
+9. What interpretation rule will distinguish evidence from expectation?
+10. If the result is ambiguous, what is the next branch?
+
+## Output template
+
+Use this shape when turning a vague request into an executable plan:
+
+```md
+Experiment brief
+
+- Question:
+- Hypothesis:
+- Comparator:
+- Unit of work:
+- Primary metric or observable:
+- Artifact plan:
+- Budget/time cap:
+- Stop condition:
+- Interpretation rule:
+- Next branch if inconclusive:
+
+Experiment type: hypothesis-driven | exploratory
+Design gate: ready | blocked
+Remaining gap:
+Recommended next action:
+```
+
+## Generalization rule
+
+Reuse the same protocol across domains by changing the unit of work and artifact type:
+
+- model training -> metrics tables, loss curves, checkpoints
+- benchmark comparisons -> score tables, latency plots, error slices
+- prompt evaluations -> rubric tables, failure examples, sampled outputs
+- product experiments -> funnels, event tables, user-segment slices
+- scientific workflows -> figures, logs, result tables, notebooks

package/skills/flywheel/references/flywheel-mcp-tool-map.md

@@ -0,0 +1,160 @@
+# Flywheel MCP Tool Map
+
+This reference describes the Flywheel MCP tool families and the common runtime
+contract expected by the public Flywheel skill.
+
+Use it as a routing guide, not as a session snapshot. Always verify the exact
+tool surface exposed by your current MCP host before executing critical flows.
+
+## Core Contract Expectations
+
+- Node lifecycle and graph-mutation flows use optimistic locking
+  (`expected_revision`).
+- Node commits require `kind`, `outcome`, and `summary`.
+- `kind` is typically `insight` or `empirical`.
+- `insight` commits require non-empty `insights`.
+- `empirical` commits require a non-empty `hypothesis`; completed empirical
+  commits also require artifacts or a `no_artifacts_reason`.
+- Artifact publish is a two-step flow:
+  prepare upload, upload raw bytes to returned signed URLs, then finalize
+  the upload batch.
+
+## Tool Families
+
+### Session, Auth, and Contract
+
+- `mcp__flywheel__flywheel_auth_status`
+- `mcp__flywheel__flywheel_get_contract`
+- `mcp__flywheel__flywheel_get_contract_section`
+- `mcp__flywheel__flywheel_get_credits_balance`
+
+### Node Discovery and Read
+
+- `mcp__flywheel__flywheel_list_nodes`
+- `mcp__flywheel__flywheel_get_node`
+- `mcp__flywheel__flywheel_get_node_tree`
+- `mcp__flywheel__flywheel_get_node_ancestry`
+- `mcp__flywheel__flywheel_summarize_node_tree`
+- `mcp__flywheel__flywheel_get_campaign_snapshot`
+- `mcp__flywheel__flywheel_list_audit`
+
+### Node Mutation, Branching, and Commit
+
+- `mcp__flywheel__flywheel_stage_node_create`
+- `mcp__flywheel__flywheel_stage_node_update`
+- `mcp__flywheel__flywheel_commit_node`
+- `mcp__flywheel__flywheel_branch_node`
+- `mcp__flywheel__flywheel_merge_nodes`
+- `mcp__flywheel__flywheel_add_parent`
+- `mcp__flywheel__flywheel_remove_parent`
+- `mcp__flywheel__flywheel_delete_node`
+- `mcp__flywheel__flywheel_bulk_delete_nodes`
+
+### Access Policy and Collaboration
+
+- `mcp__flywheel__flywheel_get_node_sharing`
+- `mcp__flywheel__flywheel_set_sharing_for_node`
+- `mcp__flywheel__flywheel_set_sharing_for_nodes`
+
+### Tags and Graph Annotation
+
+- `mcp__flywheel__flywheel_create_node_tag`
+- `mcp__flywheel__flywheel_update_node_tag`
+- `mcp__flywheel__flywheel_delete_node_tag`
+- `mcp__flywheel__flywheel_set_node_tag_assignments`
+
+### Artifacts
+
+- `mcp__flywheel__flywheel_list_artifacts`
+- `mcp__flywheel__flywheel_get_artifact`
+- `mcp__flywheel__flywheel_get_artifact_preview`
+- `mcp__flywheel__flywheel_prepare_artifact_uploads`
+- `mcp__flywheel__flywheel_finalize_artifact_uploads`
+- `mcp__flywheel__flywheel_set_artifact_note`
+- `mcp__flywheel__flywheel_delete_artifact`
+
+Common artifact types include:
+`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
+`checkpoint`, and `diff_carousel`.
+
+### Export and Import
+
+- `mcp__flywheel__flywheel_export_subgraph`
+- `mcp__flywheel__flywheel_import_subgraph`
+- `mcp__flywheel__flywheel_export_summary`
+- `mcp__flywheel__flywheel_export_summary_stream`
+- `mcp__flywheel__flywheel_export_summary_pdf`
+- `mcp__flywheel__flywheel_export_summary_render_pdf`
+
+### Executions
+
+- `mcp__flywheel__flywheel_launch_execution`
+- `mcp__flywheel__flywheel_list_executions`
+- `mcp__flywheel__flywheel_terminate_execution`
+
+### Managed Compute
+
+- `mcp__flywheel__flywheel_approval_session_heartbeat`
+- `mcp__flywheel__flywheel_list_approval_sessions`
+- `mcp__flywheel__flywheel_expire_approval_session`
+- `mcp__flywheel__flywheel_request_compute_grant_approval`
+- `mcp__flywheel__flywheel_list_compute_grants`
+- `mcp__flywheel__flywheel_compute_list_options`
+- `mcp__flywheel__flywheel_compute_acquire`
+- `mcp__flywheel__flywheel_compute_status`
+- `mcp__flywheel__flywheel_compute_connection`
+- `mcp__flywheel__flywheel_compute_release`
+- `mcp__flywheel__flywheel_compute_release_all`
+
+### Campaign Budgets (Organizer Flows)
+
+- `mcp__flywheel__flywheel_list_campaign_budgets`
+- `mcp__flywheel__flywheel_create_campaign_budget`
+- `mcp__flywheel__flywheel_update_campaign_budget`
+- `mcp__flywheel__flywheel_revoke_campaign_budget`
+
+### Migration Helpers
+
+Some installations may expose migration-only helper tools with hashed names.
+Treat these as specialized one-off tools, not part of day-to-day research
+workflows.
+
+## Practical Tool Sequences
+
+### Insight Node Flow
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. `mcp__flywheel__flywheel_commit_node`
+
+### Empirical Node With Artifacts
+
+1. `mcp__flywheel__flywheel_stage_node_create`
+2. `mcp__flywheel__flywheel_stage_node_update`
+3. Run experiment or compute steps
+4. `mcp__flywheel__flywheel_prepare_artifact_uploads`
+5. Upload artifact bytes to signed URLs
+6. `mcp__flywheel__flywheel_finalize_artifact_uploads`
+7. `mcp__flywheel__flywheel_commit_node`
+
+### Managed Compute Flow
+
+1. `mcp__flywheel__flywheel_approval_session_heartbeat`
+2. `mcp__flywheel__flywheel_request_compute_grant_approval`
+3. `mcp__flywheel__flywheel_list_compute_grants` (if needed)
+4. `mcp__flywheel__flywheel_compute_acquire`
+5. `mcp__flywheel__flywheel_compute_status` until ready
+6. `mcp__flywheel__flywheel_compute_connection`
+7. `mcp__flywheel__flywheel_compute_release` (or `..._release_all`)
+
+### Share a Graph With Collaborators
+
+1. `mcp__flywheel__flywheel_get_node_sharing`
+2. `mcp__flywheel__flywheel_set_sharing_for_node` (or `..._for_nodes`)
+3. `mcp__flywheel__flywheel_export_summary` or `..._export_subgraph` for handoff
+
+## Safety Notes
+
+- Prefer `get_contract` before implementing strict assumptions in automation.
+- Avoid call-order assumptions not mandated by contract.
+- Keep checks bounded: list/read first, then mutate only the intended nodes.

package/skills/flywheel/web-ui/flywheel-webui-map.md

@@ -24,5 +24,5 @@ Use this map when a user asks where to find a feature in the web interface.
 ## Pairing With Other Docs
 
 - Start with `web-ui/the-flywheel-web-ui.md` for overview behavior.
-- Use `reference/flywheel-mcp-tool-map.md` when the answer depends on exact MCP
+- Use `references/flywheel-mcp-tool-map.md` when the answer depends on exact MCP
   tool capabilities or runtime contract.