@paradigma-inc/flywheel 0.1.4 → 0.1.9

package/skills/flywheel/setting-up-flywheel/installation-overview.md

@@ -0,0 +1,26 @@
+# [](https://flywheel.paradigma.inc//#setting-up-flywheel)Setting up Flywheel
+
+We are in the business of automating science. As such, our first interface to Flywheel is through autonomous agents, specifically via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro).
+
+MCP enables you to natively connect and authenticate Flywheel to any compatible hosts. We recommend using Flywheel with [Codex](https://github.com/openai/codex) or [Claude code](https://github.com/anthropics/claude-code), but any MCP host should work.
+
+## [](https://flywheel-staging.paradigma.inc/tutorial#one-command-setup-recommended)One-command setup (recommended)
+
+Simply run:
+
+```bash
+npx @paradigma-inc/flywheel setup
+```
+
+## [](https://flywheel-staging.paradigma.inc/tutorial#reinstall--cleanup)Reinstall / cleanup
+
+```bash
+npx @paradigma-inc/flywheel setup
+npx @paradigma-inc/flywheel uninstall
+```
+
+`uninstall` removes Flywheel MCP entries from host config files.
+
+## [](https://flywheel-staging.paradigma.inc/tutorial#web-connector-hosts-chatgptcom--claudeai--etc-)Web connector hosts (ChatGPT.com / Claude.ai / etc. )
+
+Web connector hosts can still use OAuth-style connector flows. Keep using those host-native connector install UIs for ChatGPT.com custom apps, Claude.ai custom connectors, etc. Simply put `https://flywheel.paradigma.inc/mcp-server` as the URL when prompted.

package/skills/flywheel/setting-up-flywheel/other-hosts-installation.md

@@ -0,0 +1,40 @@
+# [](https://flywheel.paradigma.inc//#other-mcp-hosts)Other MCP hosts
+
+If your host is not currently supported by `npx @paradigma-inc/flywheel setup`, you can still connect manually.
+
+1. In the Flywheel WebUI, open **Settings**, go to the **User** tab, expand **MCP API keys**, and click **Create key**.
+2. Copy the key immediately (it is shown once).
+3. Add a Flywheel MCP server entry in your host config with:
+   - URL: `https://flywheel.paradigma.inc/mcp-server`
+   - Header: `Authorization: Bearer <YOUR_MCP_API_KEY>`
+
+Example JSON-style host config:
+
+```json
+{
+  "mcpServers": {
+    "flywheel": {
+      "type": "http",
+      "url": "https://flywheel.paradigma.inc/mcp-server",
+      "headers": {
+        "Authorization": "Bearer <YOUR_MCP_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+Example TOML-style host config:
+
+```toml
+[mcp_servers.flywheel]
+type = "http"
+url = "https://flywheel.paradigma.inc/mcp-server"
+
+[mcp_servers.flywheel.headers]
+Authorization = "Bearer <YOUR_MCP_API_KEY>"
+```
+
+Different hosts use different field names (`mcpServers`, `mcp_servers`, `mcp.servers`, etc.), but the server URL and `Authorization` bearer header are the key pieces.
+
+Alternative: for any host that supports MCP OAuth, you can use its OAuth connector install flow and set the MCP URL to `https://flywheel.paradigma.inc/mcp-server`. Web connector hosts (for example ChatGPT.com, Claude.ai) commonly use this path. It can be convenient, but it may prompt re-authorization more often than the API key route depending on the host token lifecycle and refresh behavior.

package/skills/flywheel/setting-up-flywheel/updating-flywheel-mcp.md

@@ -0,0 +1,21 @@
+# How to Update Flywheel MCP
+
+For most users, reinstall / cleanup is:
+
+```bash
+npx @paradigma-inc/flywheel setup
+npx @paradigma-inc/flywheel uninstall
+```
+
+`uninstall` removes Flywheel MCP entries from host config files.
+
+## FAQ: How Do I Migrate from the Previous OAuth-Based MCP Client 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/usage-and-workflows/using-local-hardware-with-flywheel.md

@@ -0,0 +1,57 @@
+# Using Local Hardware with Flywheel
+
+Yes, you can use Flywheel with your local hardware.
+
+Flywheel does **not** require managed cloud compute for every workflow. If you want to run experiments on your own machine, you can tell your MCP host that you want to use local hardware instead of provisioning managed compute.
+
+This guide is based on direct team clarification:
+
+- local hardware use is supported
+- you should tell your MCP host explicitly that you want to use your local machine
+- if the host refuses or insists on remote provisioning, that is something worth flagging
+
+## What to tell your MCP host
+
+Be explicit. For example:
+
+```text
+Use my local hardware for this experiment.
+Do not provision managed compute.
+Run this on my local GPU / local machine instead.
+```
+
+If you want Flywheel to track the work but not spin up remote machines, say so directly.
+
+## Typical workflow
+
+1. Ask your MCP host to create or use a Flywheel node for the experiment.
+2. State clearly that the experiment should run on your local hardware.
+3. Let the host organize the work in Flywheel while executing locally.
+4. Review the results and attached artifacts in Flywheel as usual.
+
+## When the MCP feels ambiguous
+
+If the contract or tool behavior feels ambiguous, use more explicit wording such as:
+
+```text
+Create a node for this experiment, but keep execution local.
+Do not request budget approval.
+Do not acquire managed compute.
+Use my local machine only.
+```
+
+## If it refuses
+
+If your MCP host refuses to use local hardware, tries to provision remote compute anyway, or acts as if managed compute is mandatory:
+
+- restate the request more explicitly
+- tell it not to request budget approval
+- tell it not to acquire managed compute
+- report the behavior, since the Flywheel team has already said they want to make this contract clearer
+
+## Practical takeaway
+
+- Flywheel can use managed compute
+- Flywheel can also be used with local hardware
+- if you want local execution, say it explicitly
+- if the host refuses, that is likely a tooling or contract clarity problem, not a sign that local hardware is unsupported

package/skills/flywheel/usage-and-workflows/what-to-do-with-flywheel.md

@@ -0,0 +1,34 @@
+# [](https://flywheel.paradigma.inc//#what-to-do-with-flywheel)What to do with Flywheel?
+
+In our experience the best way to get an answer to this question is to ask it to your MCP host:
+
+```console
+$ <your-mcp-host> "tell me about flywheel, what can i do with it?"
+
+In this workspace, Flywheel is a node-based system for organizing and executing
+work (especially research/experiments) with reproducibility and auditability
+built in.
+
+What you can do with it:
+
+- Create work nodes and classify them as insight (thinking/analysis) or empirical (actual experiments).
+- Build a graph of work with branching/merging, not just a linear log.
+- Commit outcomes with required structure (kind, outcome, summary) so results stay consistent.
+- Launch managed compute for a node with budget controls and track execution state.
+- Attach artifacts to nodes (text, tables, JSON, images, HTML/plots, checkpoints, diffs).
+- Collaborate with others by sharing nodes/graphs.
+- Tag nodes, audit changes, and export summaries/PDFs/subgraphs.
+
+Typical use cases:
+
+- Experiment tracking with hypotheses + evidence.
+- Decision logs and technical investigations.
+- Team-shared research graphs with reproducible outputs.
+- Converting a messy exploration into a reviewable, auditable record.
+
+If you want, I can walk you through creating your first node and a minimal workflow for your current project.
+```
+
+Francesco is documenting some example workflows on his [X profile](https://x.com/tensorqt), like [organizing, exploring and iterating on a research topic](https://x.com/tensorqt/status/2032190671281332280?s=20) or [reproducing papers on a budget](https://x.com/tensorqt/status/2032555892399305171).
+
+We'll be sharing more example workflows there and also through our [Discord](https://discord.gg/aFg4zskefj), where we do weekly office hours. You should join!

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

@@ -0,0 +1,28 @@
+# Flywheel Web UI Map
+
+Use this map when a user asks where to find a feature in the web interface.
+
+## Primary Areas
+
+- Graph canvas: browse nodes, branches, and topology for the current workspace.
+- Node panel: inspect node metadata, summaries, hypotheses, outcomes, artifacts,
+  and access state.
+- Artifact views: open uploaded artifacts (plots, tables, JSON, text, HTML).
+- Search and filters: narrow nodes by title, kind, state, and tags.
+- Access and sharing controls: review and update visibility/collaboration policy.
+- Settings: account-level preferences, machines/leases, and credit-related pages.
+
+## Navigation Tips
+
+- If the user is trying to create or mutate nodes, route them to MCP tools first;
+  treat Web UI as visibility and inspection by default.
+- If the user reports a graph mismatch, cross-check node state through MCP reads
+  (`list_nodes`, `get_node`, `get_node_tree`) before assuming UI-only issues.
+- If the user asks about compute cost or lease lifecycle, direct to Settings
+  machine and credit views plus `compute/*` references.
+
+## 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
+  tool capabilities or runtime contract.

package/skills/flywheel/web-ui/the-flywheel-web-ui.md

@@ -0,0 +1,17 @@
+# [](https://flywheel.paradigma.inc//#the-flywheel-webui)The Flywheel WebUI
+
+While most of your write-driven interactions with Flywheel will likely be through your MCP host, you will find the [https://flywheel.paradigma.inc](https://flywheel.paradigma.inc) WebUI useful for visualizing your graph and managing nodes and admin.
+
+The Flywheel WebUI presents itself as a "Canvas" where the directed acylic graph of nodes is visualized. Initially this graph will be empty, but gets populated as you create nodes through your MCP host. With the top right visibility dropdown, you can also view graphs that have been shared with you or have been made public. You can drag the nodes around to organize them, hover over them to preview their content and click on them for more details. You can pan and zoom around the canvas.
+
+![graph view with public view enabled](https://flywheel.paradigma.inc/assets/graph_view_public_enabled-CgB0PCq8.png)
+
+You can also toggle timeline view for a more organized, linear view of the graphs:
+
+![graph view with timeline](https://flywheel.paradigma.inc/assets/graph_view_timeline-BhhC_cS5.png)
+
+You can also shift select some nodes and generate summaries of their content and or export them as PDFs and/or JSON files for others to import. Of course, you can also use your MCP host to generate summaries and overviews of your research graph.
+
+Inside a node, you will be able to see the artifacts attached to it, a summary and possibly the hypothesis and/or insight that was recorded for this node.
+
+![example node view](https://flywheel.paradigma.inc/assets/example_node_view-Xv6mViuc.png)