@paradigma-inc/flywheel 0.1.4 → 0.1.9

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

@@ -0,0 +1,151 @@
+# 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.
+
+## [@tensorqt](https://x.com/tensorqt) · [13 Mar 2026, 9:34 pm](https://x.com/tensorqt/status/2032555892399305171)
+
+A really interesting way of using Flywheel is to reproduce papers on a budget: I find this new attention trick interesting, although a little counterintuitive in terms of bitterness of the pill. Now I can simply take my MCP host with Flywheel MCP and turn the paper into a graph like this, asking the model to spend at most $10 doing it:
+
+### 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_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_commit_node` to persist the planned graph structure.
+
+### Image Description
+
+```text
+A tall, minimalist node-link graph on a white background. Near the upper-left-center is a solid black hub node overlaid by the truncated label "Reproduction Graph. Ex...". Thin, light-gray edges radiate outward from this hub into a loose star of small pastel circles. Most intermediate nodes are pale pink, while several terminal leaf nodes are light beige. Around the hub, multiple short branches fan out in different directions, but one branch dominates the composition: it drops almost straight downward through a chain of pink nodes, then splits near the bottom into three short offshoots ending in two pink leaves and one beige leaf. The image contains large areas of empty white space, making the graph feel sparse and schematic, like an execution tree or experiment dependency graph rather than a dense network diagram.
+```
+
+> **Shuangfei Zhai** ([@zhaisf](https://x.com/zhaisf)) · 12 Mar
+>
+> Say hi to Exclusive Self Attention (XSA), a (nearly) free improvement to Transformers for LM. Observation: for y = attn(q, k, v), yi and vi tend to have a very high cosine similarity. Fix: exclude vi from yi via zi = yi - (yiTvi)vi/||vi||². Result: better training/val
+>
+> ### Image Description
+>
+> ```text
+> A compact training-loss chart on a pale gray-lavender grid background. The x-axis is labeled "Training iteration (K)" and runs from 0 to 200; the y-axis is labeled "Training loss" and spans roughly 2.4 to 3.2. Six smooth but slightly noisy curves compare baseline and XSA runs for 0.7b, 1.3b, and 2.7b models, with a legend in the upper-right listing `0.7b_baseline`, `0.7b_xsa`, `1.3b_baseline`, `1.3b_xsa`, `2.7b_baseline`, and `2.7b_xsa`. All curves fall sharply early and then taper into slower improvement. For each model size, the XSA line sits below the corresponding baseline line after the initial drop, visually suggesting better training loss. The 0.7b pair occupies the top of the plot, the 1.3b pair the middle, and the 2.7b pair the bottom, with the best-performing line finishing near the lower-right corner around the mid-2.4s.
+> ```
+
+---
+
+## [@tensorqt](https://x.com/tensorqt) · [13 Mar](https://x.com/tensorqt/status/2032555896014766151)
+
+The model decides to play it safe: it starts by showing self-attention correlation on a small A10 GPU (provisioned via Flywheel).
+
+### 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_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_commit_node` to mark the step as a completed empirical result.
+
+### Image Description
+
+```text
+A wide screenshot of a Flywheel artifact viewer card titled `attn_similarity_by_layer.png`, with a light header bar and a `Collapse` control in the top-right. Inside the card is a line chart titled "Exp 1A: Baseline attention similarity bias signal". The x-axis is "Layer index" from 0 to 7, and the y-axis is "Mean cos(y_i, v_i)" from about 0.18 to 0.50. A single blue line with circular markers starts low at roughly 0.19 for layer 0, jumps above 0.38 at layer 1, peaks around 0.50 at layer 2, stays near 0.40 through layers 3 to 5, dips noticeably to about 0.31 at layer 6, and rebounds to about 0.42 at layer 7. A black dashed horizontal reference line labeled `global=0.377` cuts across the figure, with most points except the first and sixth layer sitting above that average. The surrounding UI is clean and white, making the plot feel like a generated experimental artifact rather than a paper figure.
+```
+
+---
+
+## [@tensorqt](https://x.com/tensorqt) · [13 Mar](https://x.com/tensorqt/status/2032555899424772549)
+
+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_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_commit_node` to finalize the branch.
+
+### Image Description
+
+```text
+A Flywheel artifact screenshot titled `orthogonality_by_layer.png`. The central figure is a two-series line chart labeled "Exp 2A: XSA projection orthogonality by layer". The x-axis is "Layer" from 0 to 7, and the y-axis is "Cosine similarity". A blue series with circular markers, labeled `cos(y, v) baseline direction`, begins around 0.20 at layer 0 and then stays high, roughly in the 0.47 to 0.55 range, across the remaining layers. An orange series with square markers, labeled `cos(z, v) after XSA projection`, lies directly on the zero line for every layer, visually emphasizing that the projected vector has become nearly orthogonal to `v`. Below the chart, a separate text block headed `HYPOTHESIS` states that XSA projection should drive the post-projection inner product toward numerical zero relative to standard self-attention while staying stable within a spend budget of about 100 cents.
+```
+
+---
+
+## [@tensorqt](https://x.com/tensorqt) · [13 Mar](https://x.com/tensorqt/status/2032555903250030762)
+
+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_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_commit_node` to finalize the overhead measurement.
+
+### Image Description
+
+```text
+A Flywheel artifact viewer card titled `efficiency_comparison.png`, again with rounded white panel styling and a `Collapse` control in the upper-right. The main plot is a grouped bar chart titled "Exp 3A: SA vs XSA efficiency comparison". Three category labels run along the x-axis: `Train sec`, `Peak VRAM MB`, and `Tok/sec`. Blue bars represent `SA`, while orange bars represent `XSA-final`. On the shared vertical scale, the train-time bars are so short they are nearly flush with the baseline, indicating very similar runtimes. The peak-VRAM bars are close together around the low twelve-thousand-megabyte range, with XSA appearing only slightly different from SA. The throughput bars dominate the chart, both sitting near roughly 125k tokens per second, with the blue SA bar modestly taller than the orange XSA-final bar. Beneath the plot, a `HYPOTHESIS` note says XSA should add only small runtime and VRAM overhead relative to SA for matched shapes under a budget of roughly 150 cents.
+```
+
+---
+
+## [@tensorqt](https://x.com/tensorqt) · [13 Mar](https://x.com/tensorqt/status/2032555907864039646)
+
+Up to now, no trouble. The agent then decides to train a 50M parameter model with XSA versus a SA baseline, finding that, at this size, there seems to be no improvements:
+
+### 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_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_commit_node` to record that the empirical result did not reproduce the expected gain.
+
+### Image Description
+
+```text
+A cropped Flywheel results page showing text summary and tabular artifacts instead of a chart. At the top, a section label `SUMMARY` is followed by a sentence stating that the main quality-gain claim was not reproduced at this compact budget and scale, and that XSA underperformed SA in both matched pairs. Below that, an `ARTIFACTS` section displays an expanded table card titled `run_metrics.csv`. Four runs are visible: `long_sa`, `long_xsa`, `short_sa`, and `short_xsa`. Visible columns include `RUN_ID`, `VAL_BPB`, `TRAINING_SECONDS`, `TOTAL_SECONDS`, `PEAK_VRAM_MB`, and the beginning of an `MFU_...` column. The values show XSA with slightly worse validation BPB and slightly higher total time and VRAM than the corresponding SA runs. A second table card titled `quality_pairs.csv` compares `short` and `long` matched pairs at sequence lengths 1024 and 2048. Its visible `DELTA_XSA_MINUS_SA` values are positive, approximately 0.00455 for the short pair and 0.00756 for the long pair, and the `XSA_BETTER` indicator is 0 for both rows. Horizontal scroll bars under both tables emphasize that the screenshot is a cropped view into wider result tables.
+```
+
+---
+
+## [@tensorqt](https://x.com/tensorqt) · [13 Mar](https://x.com/tensorqt/status/2032555911999336864)
+
+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_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_commit_node` to persist the analysis.
+
+### Image Description
+
+```text
+A Flywheel artifact card titled `length_trend.png` containing a simple two-point line chart labeled "Step 5: Context-length trend of XSA advantage". The x-axis is "Sequence length" and spans from just above 1000 to just above 2000. The y-axis reads `Delta BPB (XSA - SA, lower is better)`. One blue marker sits near sequence length 1024 with a value around 0.0046, and the second sits near 2048 with a value around 0.0076. A single straight line connects them, slanting upward from left to right. A black dashed horizontal line marks zero across the bottom of the chart, and both measured points remain clearly above it. The visual message is that XSA is worse than SA under this metric at both tested context lengths, and the gap grows as the sequence length increases.
+```
+
+---
+
+## [@tensorqt](https://x.com/tensorqt) · [13 Mar](https://x.com/tensorqt/status/2032555915182789045)
+
+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_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_commit_node` to finalize the robustness verdict.
+
+### Image Description
+
+```text
+A Flywheel artifact screenshot titled `robustness_deltas.png`. The central figure is a vertical bar chart labeled "Exp 6A: Robustness deltas across conditions". The y-axis reads `Delta BPB (XSA - SA, lower is better)`, and the x-axis shows three angled category labels: `default_lr_seq1024`, `low_lr_seq1024`, and `sink_proxy_seq256`. All three bars are blue and all are positive, with heights around 0.0045, 0.0051, and 0.0063 respectively. The rightmost `sink_proxy_seq256` bar is the tallest, while `default_lr_seq1024` is the shortest. Since every bar is above zero, the chart visually indicates that none of the tested robustness conditions produced an XSA win by this metric. Beneath the plot, a `HYPOTHESIS` note says XSA advantage should remain non-negative across a compact learning-rate sweep and one attention-sink perturbation setting under a budget of about 150 cents.
+```

package/skills/flywheel/getting-started/account-access.md

@@ -0,0 +1,8 @@
+# Account Access
+
+You need a Flywheel account to use Flywheel.
+
+- Sign up: [https://flywheel.paradigma.inc/signup](https://flywheel.paradigma.inc/signup)
+- Sign in: [https://flywheel.paradigma.inc/login](https://flywheel.paradigma.inc/login)
+
+If an MCP host uses an OAuth-style connector flow and you do not already have an account, create one first and then continue the authentication flow.

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

@@ -0,0 +1,23 @@
+# Welcome to Flywheel
+
+Install Flywheel in your MCP host with:
+
+```bash
+npx @paradigma-inc/flywheel setup
+```
+
+If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
+
+```bash
+npx @paradigma-inc/flywheel uninstall
+npx @paradigma-inc/flywheel setup
+```
+
+If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.
+
+If your MCP host is not supported by `npx @paradigma-inc/flywheel setup`, use manual host configuration:
+
+- URL: `https://flywheel.paradigma.inc/mcp-server`
+- Header: `Authorization: Bearer <YOUR_MCP_API_KEY>`
+
+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/getting-started/flywheel-tutorial-overview.md

@@ -0,0 +1,30 @@
+# Flywheel Tutorial
+
+> Note: We are constantly iterating, so some aspects of this tutorial may be stale.
+>
+> Psst: you need an account to use Flywheel. See [Account access](./account-access.md) or go directly to [sign up](https://flywheel.paradigma.inc/signup) or [sign in](https://flywheel.paradigma.inc/login).
+
+Welcome to Flywheel. Below we will cover how to install Flywheel and some tips on usage patterns.
+
+## [](https://flywheel.paradigma.inc//#what-is-flywheel)What is Flywheel?
+
+Flywheel's ambition is to serve as the infrastructure upon which autonomous science will run.
+
+In its current iteration, you can think of Flywheel as _"git for research"_, to aide researchers and agents in working on research projects.
+
+While in SWE we use git to manage changes to code, in research we are interested in manipulating ideas. Flywheel provides the DAG structure and operations (branching, merging, etc) to manage this.
+
+## Documentation Sections
+
+- [Account access](./account-access.md)
+- [Setting up Flywheel](../setting-up-flywheel/installation-overview.md)
+- [How to update Flywheel MCP](../setting-up-flywheel/updating-flywheel-mcp.md)
+- [What to do with Flywheel](../usage-and-workflows/what-to-do-with-flywheel.md)
+- [The Flywheel WebUI](../web-ui/the-flywheel-web-ui.md)
+- [Managed Compute](../compute/managed-compute.md)
+- [Credits and billing](../compute/credits-and-billing.md)
+- [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)
+- [Example workflows](../example-workflows/)

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

@@ -0,0 +1,200 @@
+# 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.
+
+### 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_budget_approval` only after the user accepts the design
+4. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed
+5. `mcp__flywheel__flywheel_prepare_artifact_publish`
+6. 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.
+7. `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/reference/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/setting-up-flywheel/claude-code-cli-installation.md

@@ -0,0 +1,16 @@
+# [](https://flywheel.paradigma.inc//#installing-on-claude-code)Installing on Claude Code
+
+Use the setup wizard:
+
+```bash
+npx @paradigma-inc/flywheel setup
+```
+
+If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
+
+```bash
+npx @paradigma-inc/flywheel uninstall
+npx @paradigma-inc/flywheel setup
+```
+
+If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.

package/skills/flywheel/setting-up-flywheel/codex-cli-installation.md

@@ -0,0 +1,16 @@
+# [](https://flywheel.paradigma.inc//#installing-on-codex)Installing on Codex
+
+Use the setup wizard:
+
+```bash
+npx @paradigma-inc/flywheel setup
+```
+
+If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
+
+```bash
+npx @paradigma-inc/flywheel uninstall
+npx @paradigma-inc/flywheel setup
+```
+
+If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.

package/skills/flywheel/setting-up-flywheel/how-can-i-get-an-authorized-client_id-for-the-oauth-flow.md

@@ -0,0 +1,50 @@
+# [](https://flywheel.paradigma.inc//#faq-how-can-i-get-an-authorized-client_id-for-the-oauth-flow)FAQ: How Can I Get an Authorized `client_id` for the OAuth Flow?
+
+We support the standard MCP OAuth flow with dynamic client registration, as documented in the [MCP Authorization spec (dynamic client registration)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration).
+
+First, query our OAuth authorization-server metadata:
+
+```bash
+curl -sS https://flywheel.paradigma.inc/mcp-server/.well-known/oauth-authorization-server | jq
+```
+
+That response includes the OAuth endpoints (`authorization_endpoint`, `token_endpoint`, `registration_endpoint`, and others).
+
+`response_types_supported` is currently `["code"]`, so register with `"response_types":["code"]`.
+
+Then register your OAuth client using the `registration_endpoint`.
+
+## [](https://flywheel-staging.paradigma.inc/tutorial#public-client-default)Public client (default)
+
+This is the default for interactive MCP hosts (for example Claude Code, IDE hosts, local desktop clients). If `token_endpoint_auth_method` is omitted, we default to `none`.
+
+```bash
+curl -sS -X POST https://flywheel.paradigma.inc/mcp-server/register \
+  -H "content-type: application/json" \
+  -d '{
+    "client_name":"Flywheel MCP Host",
+    "redirect_uris":["http://localhost:3333/callback"],
+    "grant_types":["authorization_code","refresh_token"],
+    "response_types":["code"]
+  }' | jq
+```
+
+The response returns a `client_id` and no `client_secret`.
+
+## [](https://flywheel-staging.paradigma.inc/tutorial#confidential-client-optional)Confidential client (optional)
+
+Use this when your app has a trusted backend that can securely store secrets.
+
+```bash
+curl -sS -X POST https://flywheel.paradigma.inc/mcp-server/register \
+  -H "content-type: application/json" \
+  -d '{
+    "client_name":"Flywheel MCP Connector Backend",
+    "redirect_uris":["https://YOUR_CALLBACK_URL"],
+    "grant_types":["authorization_code","refresh_token"],
+    "response_types":["code"],
+    "token_endpoint_auth_method":"client_secret_post"
+  }' | jq
+```
+
+That response returns both `client_id` and `client_secret`. Keep `client_secret` private in your backend.