@paradigma-inc/flywheel 0.1.11 → 0.1.13

package/skills/flywheel-auto/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: flywheel-auto
+description: Advance a Flywheel frontier autonomously with Flywheel MCP under an explicit budget by persisting control state, executing branches, and replanning after each resolution. Use for autonomous research continuation, not planning-only lookahead, claim validation, or source-to-graph authoring.
+---
+
+# flywheel-auto
+
+## When To Use
+
+Use this skill when the task is to shape information inside Flywheel rather than only discuss it. Use the flywheel-auto skill when the user wants Flywheel to keep advancing a research frontier autonomously under a specified budget. Flywheel MCP is a node-first durable system of record for research work: nodes hold durable state, artifacts hold supporting files, executions record runs, and compute leases provide managed hardware. Conceptually, the flywheel-auto skill is what you get when you invoke `$flywheel-lookahead`, then execute and replan after each resolution: persist the run contract in the graph, keep the plan `n` hops ahead, and spend only within an explicit measured budget.
+
+If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/INTERFACES.md](references/INTERFACES.md) before mutating nodes or acquiring compute.
+
+## Input Contract
+
+Before execution, recover or establish these inputs:
+
+- Required before execution: start nodes, objective, budget ceiling, budget unit, and an explicit terminal condition.
+- Optional with defaults: `lookahead_depth` defaults to `n=1`; `frontier_width` defaults to `k=1` and also caps concurrent executable branches.
+- Recovery rules:
+  - Ask only when a required execution input cannot be recovered from explicit user instructions, current conversational context, or recent graph state.
+  - If start nodes cannot be recovered from explicit ids/slugs, named current context, or recent graph context, ask once.
+  - If the objective is missing, ask once; if the user refuses, infer it from graph context and persist it before execution.
+  - If budget ceiling, budget unit, or terminal condition is missing, ask once before execution. If the budget contract remains incomplete, keep planning but do not request compute approval or acquire compute.
+  - If the user gives a non-credit budget unit, persist that exact user-facing unit and derive the operational compute approval cap before acquisition.
+
+## Working Terms
+
+- `frontier`: the current unresolved next-step nodes or candidate branches worth planning or executing next.
+- `resolved frontier`: the latest resolved nodes from which the next frontier should be expanded, not the original source corpus again.
+- `graph-local`: continuation and stopping decisions should be recoverable from persisted node state alone, not from chat memory.
+- `control node`: the dedicated `insight` node that stores the canonical run contract for the current frontier.
+
+## Core Rules
+
+- Treat the main page body as the node readme/body field (`content` on modern Flywheel surfaces).
+- Use artifacts for supporting files and evidence, not as a substitute for the node's main narrative.
+- Only create graph edges for durable semantic relationships, because graphifying every wiki link floods the graph with noise that hides decision-relevant structure.
+- Treat the flywheel-auto skill as graph-local autonomous research: persist the run contract in the graph, keep the plan `n` hops ahead, and spend only within an explicit measured budget.
+- Ask only the minimum clarification questions needed to establish a coherent control contract, and ask none when the required answers are already recoverable from user instructions, conversational context, or graph state.
+- Planned nodes that are expected to produce evidence or artifacts should be typed `empirical`; planned nodes that only encode synthesis, decomposition, or decision structure should be typed `insight`.
+- Keep the control node typed `insight` and keep its `insights` non-empty so the insight commit contract stays valid.
+- Do not rely on fresh user feedback to decide whether the flywheel-auto skill should continue, so later replans can resume from node state alone in a fresh chat.
+
+## Workflow
+
+1. Resolve the starting context.
+   - Resolve starting nodes in this order: explicit node ids/slugs, explicitly named current context, focused or recently referenced nodes, then ask the user if nothing stable is recoverable.
+2. Resolve the objective and budget contract.
+   - Recover required execution inputs from the current conversation and graph first. Ask only for inputs that remain genuinely missing after that recovery pass.
+   - The flywheel-auto skill requires a measurable objective and an explicit terminal condition. Ask once for missing prerequisites; if the user refuses to specify an objective, infer it from the available graph context and state it explicitly before continuing.
+   - The budget contract must be explicit before execution starts. Ask once for any missing budget ceiling, budget unit, or terminal condition. If those inputs remain unavailable after one clarification round, keep planning but do not request compute approval or acquire compute.
+   - Managed compute spend is billed in Flywheel credits. If the user gives dollars, hours, or another measurable budget semantic, persist that user-facing cap explicitly and derive the operational compute approval cap before acquisition.
+   - Persist the run contract in a dedicated `insight` control node for this frontier. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief run rationale in `insights` so the commit contract stays valid.
+   - The control contract must name: objective, decision criterion, start nodes, budget ceiling and unit, lookahead depth `n`, frontier width `k`, and an explicit terminal condition.
+   - Later flywheel-auto replans must read the control node `content` first and continue from that persisted contract rather than from chat memory.
+   - Run the design gate from [references/experiment-design-protocol.md](references/experiment-design-protocol.md) before the first compute request: confirm objective, decision criterion, evidence plan, and budget readiness, even though later continuation decisions become graph-local.
+3. Map each stable page, claim, or concept to a node.
+   - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
+   - Create a new node with `flywheel_stage_node_create` when needed.
+   - Update an existing node with `flywheel_get_node` + `flywheel_stage_node_update` when continuing work.
+4. Put the primary page markdown or plan rationale in the node body/readme field (`content`).
+   - Keep `summary` concise.
+   - Populate `hypothesis`, `insights`, `outcome`, and similar fields only when the source actually supports them.
+5. Publish supporting files with the artifact upload flow.
+   - For exact artifact contract details, load [references/ARTIFACTS.md](references/ARTIFACTS.md).
+   - Use `flywheel_prepare_artifact_uploads`.
+   - Upload raw file bytes to the returned signed URLs.
+   - Call `flywheel_finalize_artifact_uploads` once all uploads in the batch are staged.
+   - Keep the artifact filename stable enough to reference from markdown when inline rendering matters.
+6. Add graph structure sparingly.
+   - Promote only decision-relevant relationships to edges.
+   - Leave ordinary cross-links inside the markdown body.
+7. Expand the frontier deliberately.
+   - Expand from the resolved frontier rather than mirroring the source corpus again.
+   - Depth `n` means plan `n` hops ahead from the currently resolved frontier. Default `n=1`.
+   - Width `k` means plan up to `k` distinct non-redundant frontier directions. Default `k=1`.
+   - In the flywheel-auto skill, the same `k` also caps concurrent workers pursuing executable frontier nodes.
+   - Keep unresolved plan nodes staged until the corresponding work is resolved.
+8. Execute and replan continuously.
+   - For exact execution and compute request shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/experiment-design-protocol.md](references/experiment-design-protocol.md).
+   - Use `flywheel_launch_execution` when the branch can run as a Flywheel node execution without a separate leased machine, and inspect terminal status before commit.
+   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. In that case use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants` or `flywheel_list_approval_sessions`, then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
+   - Spawn up to `k` workers for distinct executable frontier nodes.
+   - Route additional viable branches sequentially when there are more than `k` worthwhile directions.
+   - After each resolved node, refresh the lookahead so the graph remains `n` hops ahead.
+   - Release managed compute with `flywheel_compute_release` or `flywheel_compute_release_all` when a branch is done.
+   - Stop only when the graph-local terminal condition says to stop, such as: objective met, budget exhausted, or no non-redundant frontier branch is likely to produce enough decision-relevant information to justify the remaining budget and duplication risk.
+9. Commit after the node snapshot is coherent with `flywheel_commit_node`.
+   - Commit resolved insight nodes only when they have non-empty `insights`.
+   - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
+   - Leave unresolved plan nodes staged.
+
+## Result Contract
+
+When the skill completes a pass, it should leave behind:
+
+- One persisted `insight` control node containing the canonical run contract.
+- Zero or more staged frontier nodes up to the current `n` and `k` limits.
+- Zero or more committed resolved nodes, but only when their commit contracts are satisfied.
+- Uploaded artifacts for completed empirical work, or an explicit `no_artifacts_reason` when artifacts are absent by design.
+- Released managed compute if any lease was acquired during the pass.
+- An explicit stop reason, continuation rule, or next action recorded in node state so a later pass can resume graph-locally.
+
+## Persisted Control Contract
+
+Use a dedicated `insight` node as the durable run controller for the current
+frontier. Do not rely on unstated product fields or fresh chat context.
+
+For the canonical entity model and public contract terminology behind this
+controller, load [references/INTERFACES.md](references/INTERFACES.md).
+
+Use this storage convention:
+
+1. Reuse an existing control node when one already governs the same frontier;
+   otherwise create one with `flywheel_stage_node_create`.
+2. Put the canonical contract in node `content`.
+3. Put a one-line synopsis in `summary`.
+4. Put the run rationale, continuation rule, or prioritization logic in
+   `insights` so the `insight` commit contract is satisfied.
+5. Update the control node with `flywheel_stage_node_update`.
+6. Read the control node with `flywheel_get_node` before later replans that need
+   a fresh `expected_revision` revision token for optimistic-locking writes.
+7. Commit the control node with `flywheel_commit_node` once the contract is
+   coherent, even if executable frontier nodes remain staged or in progress.
+
+Canonical contract shape:
+
+```md
+## Run contract
+
+- Objective:
+- Decision criterion:
+- Start nodes:
+- Budget ceiling:
+- Budget unit:
+- Compute approval cap:
+- Lookahead depth:
+- Frontier width:
+- Terminal condition:
+```
+
+Use `Compute approval cap` for the operational cap that will govern managed
+compute acquisition. If the user already budgets directly in credits, it can
+match `Budget ceiling`. If the user budgets in another unit, keep both values so
+later continuations can recover the user-facing constraint and the executable
+approval cap from node state alone.
+
+## Guardrails
+
+- Do not blur `$flywheel-reproduce` and the flywheel-auto skill, because `$flywheel-reproduce` validates existing claims under budget while the flywheel-auto skill expands the frontier to create new knowledge.
+- Build the graph explicitly with nodes, artifacts, and selected edges.
+- Keep the flywheel-auto skill graph-local: future continuation and stopping decisions should be derivable from the persisted node state rather than from fresh chat context.
+- Do not ask follow-up questions after the control contract is coherent unless a contradiction, missing required approval, or tool/runtime failure makes autonomous continuation impossible.
+
+See also: invoke `$flywheel-to-graph` to port source material into Flywheel without implicit execution, invoke `$flywheel-reproduce` to graphify claim-bearing sources and run budgeted validation branches, and invoke `$flywheel-lookahead` to stage next-step frontier nodes from existing graph state without execution.

package/skills/flywheel-auto/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "flywheel-auto"
+  short_description: "Run budgeted autonomous Flywheel research"
+  default_prompt: "Use $flywheel-auto to advance this Flywheel frontier autonomously under an explicit budget."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "flywheel"
+      description: "Flywheel MCP server"
+      transport: "streamable_http"
+      url: "https://flywheel.paradigma.inc/mcp-server"

package/skills/flywheel-auto/evals/evals.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "continuation-from-existing-frontier",
+    "prompt": "Use $flywheel-auto at /Users/g.f.g.f./Documents/GitHub/paradigma/project/flywheel-setup/skills/flywheel-auto to continue a Flywheel frontier that already has a persisted control node. Keep going under the existing credit cap and do not ask again for the objective or budget unless the control node is missing or contradictory.",
+    "expected_output": "Read the persisted contract from the control node content before replanning, continue from that stored objective and budget, avoid re-asking for the objective or budget when the control node is coherent, and leave behind an updated control node plus staged or committed frontier work.",
+    "files": []
+  },
+  {
+    "id": "cold-start-with-non-credit-budget",
+    "prompt": "Use $flywheel-auto at /Users/g.f.g.f./Documents/GitHub/paradigma/project/flywheel-setup/skills/flywheel-auto to explore this frontier autonomously with at most $25 of managed-compute spend. Persist the dollar-denominated cap verbatim and derive whatever operational compute approval cap is needed before acquisition.",
+    "expected_output": "Persist the dollar-denominated budget ceiling and unit verbatim in the control node, derive an operational compute approval cap before acquisition, record both values before any compute request is made, and leave a coherent run contract behind for later continuation.",
+    "files": []
+  },
+  {
+    "id": "cold-start-with-no-objective",
+    "prompt": "Use $flywheel-auto at /Users/g.f.g.f./Documents/GitHub/paradigma/project/flywheel-setup/skills/flywheel-auto to go autonomous on this Flywheel graph until you find something interesting. If I refuse to specify an objective, infer one from the graph context and make it explicit before you execute.",
+    "expected_output": "Ask for an objective first, infer one from graph context if the user refuses, write that objective explicitly into the control node, and only then proceed toward execution with a coherent control node and frontier plan.",
+    "files": []
+  }
+]

package/skills/flywheel-auto/references/ARTIFACTS.md

@@ -0,0 +1,218 @@
+# Flywheel Artifacts
+
+Canonical reference for node artifact publishing in Flywheel MCP 0.9.
+
+Legacy note:
+
+- historical `run_artifacts` rows are retained for backward reads.
+- new artifact writes must use the MCP batch upload workflow:
+  `flywheel_prepare_artifact_uploads` -> raw file upload(s) ->
+  `flywheel_finalize_artifact_uploads`.
+
+## Node MCP Contract
+
+Artifacts are managed through node MCP tools:
+
+- `flywheel_prepare_artifact_uploads` prepares one or more signed raw-file
+  upload requests for a node.
+- The caller executes each returned upload request with raw bytes.
+- `flywheel_finalize_artifact_uploads` appends all staged uploads in that batch
+  to the node and bumps node revision once.
+- `flywheel_list_artifacts` and `flywheel_get_artifact` return artifact
+  metadata.
+- `flywheel_get_artifact_preview` reads persisted preview payload content by
+  artifact id.
+- `flywheel_commit_node` commits/finalizes node state after terminal fields are
+  already staged.
+
+Contract rules:
+
+- `flywheel_prepare_artifact_uploads` requires `expected_revision` and enforces
+  optimistic locking before issuing upload tickets.
+- Upload uses the signed one-time ticket in each returned `upload_url`;
+  client-supplied path/reference fields are not part of this contract.
+- Raw upload only stages payloads. It does not mutate node state or bump node
+  revision.
+- `flywheel_finalize_artifact_uploads` is the single node mutation point for an
+  artifact batch.
+- `flywheel_commit_node` is finalize-only:
+  - request shape is `expected_revision` with optional `summary` override.
+  - node kind/outcome/hypothesis/insights/no_artifacts_reason must already be
+    staged.
+  - commit transitions lifecycle to `committed`.
+- committed node contract rules remain strict:
+  - `kind=empirical` + `outcome=completed` requires artifacts or
+    `no_artifacts_reason`.
+  - `kind=insight` requires non-empty `insights`.
+  - `kind=empirical` requires empty `insights`.
+- MCP mutating calls require idempotency:
+  - tool transport auto-manages idempotency keys for tool calls.
+  - direct HTTP callers must provide `Idempotency-Key` on mutating MCP
+    endpoints.
+
+`artifact_type=banner` is supported for campaign root visuals. It follows the
+same raw image upload validation path as `artifact_type=image` and is intended
+for zoomed-out canvas visibility.
+
+## Prepare Request Shape
+
+`POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`
+
+```json
+{
+  "expected_revision": 7,
+  "items": [
+    {
+      "artifact_type": "image",
+      "title": "Loss curve",
+      "execution_id": "optional-execution-id",
+      "metadata": {
+        "source": "training-run"
+      },
+      "filename": "loss_curve.png",
+      "media_type": "image/png"
+    }
+  ]
+}
+```
+
+Notes:
+
+- `items` must contain at least one structured object item.
+- String or JSON-encoded item payloads are invalid at the tool boundary.
+- `filename` and `media_type` are required for each item.
+- `metadata` is caller-defined JSON.
+
+## Prepare Response Shape
+
+```json
+{
+  "batch": {
+    "batch_token": "uuid",
+    "expires_at": "2026-03-09T16:00:00+00:00",
+    "max_upload_bytes": 10485760,
+    "items": [
+      {
+        "upload_id": "uuid",
+        "upload_url": "https://.../mcp/artifacts/uploads/{upload_id}?ticket=...",
+        "method": "PUT",
+        "headers": {
+          "Content-Type": "image/png",
+          "X-Flywheel-Artifact-Filename": "loss_curve.png"
+        },
+        "curl_command": "curl -sS -X PUT '...' -H 'Content-Type: image/png' -H 'X-Flywheel-Artifact-Filename: loss_curve.png' --data-binary @/absolute/path/to/file"
+      }
+    ]
+  }
+}
+```
+
+## Raw Upload Step
+
+Execute each returned request exactly:
+
+- Method: `PUT`
+- URL: `batch.items[i].upload_url`
+- Body: raw file bytes
+- Headers:
+  - `Content-Type` (media type)
+  - `X-Flywheel-Artifact-Filename` (filename hint)
+
+A successful upload:
+
+- validates the uploaded bytes against the requested artifact type
+- stages canonical payload JSON in blob storage
+- returns `202 Accepted`
+- does not yet append an artifact record to the node
+
+## Finalize Request and Response
+
+`POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`
+
+```json
+{
+  "batch_token": "uuid"
+}
+```
+
+Successful finalize:
+
+- validates the batch is complete and still revision-compatible
+- appends all staged artifacts to the node
+- persists canonical payload JSON to `artifacts/nodes/{node_id}/{artifact_id}.json`
+- bumps node revision once
+- returns `{ "node": ..., "artifacts": [...] }`
+
+## Artifact Preview Behavior
+
+Artifact preview endpoint:
+`GET /mcp/nodes/{node_id}/artifacts/{artifact_id}/preview`.
+MCP tool: `flywheel_get_artifact_preview`.
+
+- Preview reads canonical persisted payload blob (`storage_path`) only.
+- No workspace dependency or local-file fallback is required.
+- `data_url` in preview responses is render output only; never upload JSON
+  metadata wrappers.
+- Preview-normalized types:
+  - `image` -> image payload with `data_url`
+  - `html` / `plotly_html` -> HTML payload
+  - `json` -> JSON payload
+  - `text` / `diff_carousel` and common text/code extensions -> text payload
+
+## WebUI Artifact Payload Reads
+
+When artifacts are projected through node responses, the server returns
+normalized storage references for each artifact payload:
+
+- `storage_path`: canonical blob path (for example
+  `artifacts/nodes/{node_id}/{artifact_id}.json`).
+- `storage_url`: the single client/host read URL for that payload.
+  - All blob backends: `/blobs/{storage_path}` authenticated byte-serving
+    proxy after access checks.
+
+Clients should read artifact bytes from `storage_url` only. `storage_path`
+remains metadata/debug context and must not be reconstructed into fetch URLs by
+clients. Payload loads are coordinated through a shared loader with in-flight
+deduplication, cache reuse, and bounded fetch concurrency to avoid bursty
+request storms and `429` backpressure under artifact-heavy nodes.
+
+The node overview panel additionally avoids eager load spikes by defaulting to
+collapsed mode for artifact-heavy nodes and deferring artifact rendering until
+cards approach the viewport.
+
+## Artifact Load Telemetry
+
+The WebUI emits a batched first-party product analytics event,
+`web_artifact_payload_batch`, through `POST /analytics/events`.
+
+This event is intended for aggregate artifact read-path observability and
+includes fields such as:
+
+- load volume (`loads_started`, `loads_completed`, `loads_failed`)
+- rate-limit incidence (`loads_429`)
+- queue/load latency aggregates
+- source mix (`/blobs/*` authenticated proxy)
+- top per-node load/failure summaries in the batch window
+
+## File Inventory Surfaces
+
+Artifacts and attachments are exposed through two HTTP inventory endpoints:
+
+- `GET /users/me/files` for account-wide browsing in Settings.
+- `GET /nodes/{node_id}/files` for node lineage-scoped browsing in the node
+  details panel.
+
+Inventory entries include source context (`node_id`, `execution_id`) so the UI
+can jump directly to the originating node or execution.
+
+## Common Invalid Payload Causes
+
+- stale `expected_revision` at prepare or finalize time
+- missing/invalid upload ticket
+- expired upload ticket or batch
+- upload body exceeds configured size limit
+- uploaded bytes do not match requested artifact format (for example invalid
+  JSON)
+- finalize called before every prepared upload is staged
+- commit contract violations (for example empirical `completed` without
+  artifacts or `no_artifacts_reason`)

package/skills/flywheel-auto/references/INTERFACES.md

@@ -0,0 +1,201 @@
+# Interfaces
+
+Canonical reference for Flywheel user-facing interfaces and public contracts.
+
+Last updated: 2026-03-21
+
+## Primary Clients
+
+- `project/flywheel-webui` - canonical web product UI
+- `project/flywheel-api` - canonical programmatic client interface (local + HTTP)
+- MCP hosts (Codex/Claude/ChatGPT) via `/mcp-server`
+
+## Canonical Entity Model
+
+All interfaces operate on the same core entities:
+
+- node
+- node edge (branch/merge graph links)
+- artifact
+- execution
+- compute lease
+- budget grant
+
+Node snapshots are the canonical durable contract for resume, review, and
+cross-client interoperability.
+
+## Core HTTP Surface
+
+### Node lifecycle and graph
+
+- `GET /mcp/nodes`
+- `GET /mcp/nodes/{node_id}`
+- `GET /mcp/nodes/{node_id}/tree`
+- `POST /mcp/nodes/stage/create`
+- `PATCH /mcp/nodes/{node_id}/stage/update`
+- `POST /mcp/nodes/{node_id}/commit`
+- `POST /mcp/nodes/{node_id}/branch`
+- `POST /mcp/nodes/merge`
+- `DELETE /mcp/nodes/{node_id}`
+- `POST /mcp/nodes/bulk-delete`
+
+### Artifact lifecycle
+
+- `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`
+- `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`
+- `GET /mcp/nodes/{node_id}/artifacts`
+- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}`
+- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}/preview`
+- `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}`
+- `PUT /mcp/artifacts/uploads/{upload_id}`
+
+### Execution lifecycle
+
+- `POST /mcp/nodes/{node_id}/executions`
+- `GET /mcp/nodes/{node_id}/executions`
+- `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate`
+
+### Compute catalog
+
+- `GET /compute/providers`
+- `GET /compute/offers`
+- `GET /compute/offers/{provider}`
+
+### Managed compute and budgets
+
+- `GET /mcp/nodes/{node_id}/compute/options`
+- `POST /mcp/nodes/{node_id}/compute/acquire`
+- `GET /mcp/compute/status`
+- `GET /mcp/compute/connection`
+- `POST /mcp/compute/release`
+- `POST /mcp/compute/release-all`
+- `GET /mcp/nodes/{node_id}/budget/grants`
+- `GET /mcp/nodes/{node_id}/budget/campaign-grants`
+- `POST /mcp/nodes/{node_id}/budget/campaign-grants`
+- `PATCH /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+- `DELETE /mcp/nodes/{node_id}/budget/campaign-grants/{budget_grant_id}`
+
+### Sharing, tags, and audit
+
+- `GET /mcp/nodes/{node_id}/sharing`
+- `PUT /mcp/nodes/{node_id}/sharing`
+- `POST /mcp/nodes/sharing/bulk`
+- `GET /mcp/nodes/{node_id}/audit`
+- `POST /mcp/nodes/{root_node_id}/tags`
+- `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}`
+- `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}`
+- `PUT /mcp/nodes/{node_id}/tags`
+
+### Export and summaries
+
+- `POST /mcp/export`
+- `POST /mcp/import`
+- `POST /mcp/export-summary`
+- `POST /mcp/export-summary-stream`
+- `POST /mcp/export-summary-pdf`
+- `POST /mcp/export-summary-render-pdf`
+
+### Auth and integrations
+
+- `GET /auth/status`
+- `GET /auth/accounts`
+- `POST /auth/accounts/merge/source-proof`
+- `POST /auth/accounts/merge/preview`
+- `POST /auth/accounts/merge`
+- `POST /auth/accounts/detach`
+- `GET /auth/integrations/status`
+- `PUT /auth/integrations/wandb`
+- `PUT /auth/integrations/huggingface`
+- `DELETE /auth/integrations/wandb`
+- `DELETE /auth/integrations/huggingface`
+
+### Analytics
+
+- `POST /analytics/events`
+- `GET /admin/analytics/kpis`
+- `GET /admin/analytics/overview`
+
+## MCP Tool Surface
+
+### Discovery and sharing tools
+
+- `flywheel_auth_status`
+- `flywheel_get_credits_balance`
+- `flywheel_list_nodes`
+- `flywheel_get_node`
+- `flywheel_get_node_tree`
+- `flywheel_get_node_sharing`
+- `flywheel_set_node_sharing`
+- `flywheel_bulk_set_node_sharing`
+- `flywheel_create_node_tag`
+- `flywheel_update_node_tag`
+- `flywheel_delete_node_tag`
+- `flywheel_set_node_tag_assignments`
+
+### Node and graph tools
+
+- `flywheel_stage_node_create`
+- `flywheel_stage_node_update`
+- `flywheel_commit_node`
+- `flywheel_branch_node`
+- `flywheel_merge_nodes`
+- `flywheel_delete_node`
+- `flywheel_bulk_delete_nodes`
+
+### Artifact tools
+
+- `flywheel_prepare_artifact_uploads`
+- `flywheel_finalize_artifact_uploads`
+- `flywheel_list_artifacts`
+- `flywheel_get_artifact`
+- `flywheel_get_artifact_preview`
+- `flywheel_delete_artifact`
+
+### Execution tools
+
+- `flywheel_launch_execution`
+- `flywheel_list_executions`
+- `flywheel_terminate_execution`
+
+### Compute lease and budget tools
+
+- `flywheel_compute_list_options`
+- `flywheel_request_compute_grant_approval`
+- `flywheel_list_compute_grants`
+- `flywheel_compute_acquire`
+- `flywheel_compute_status`
+- `flywheel_compute_connection`
+- `flywheel_compute_release`
+- `flywheel_compute_release_all`
+
+### Campaign budget tools
+
+- `flywheel_list_campaign_budgets`
+- `flywheel_create_campaign_budget`
+- `flywheel_update_campaign_budget`
+- `flywheel_revoke_campaign_budget`
+
+### Contract, audit, and export tools
+
+- `flywheel_get_contract`
+- `flywheel_list_audit`
+- `flywheel_summarize_node_tree`
+- `flywheel_export_subgraph`
+- `flywheel_import_subgraph`
+- `flywheel_export_summary`
+- `flywheel_export_summary_stream`
+- `flywheel_export_summary_pdf`
+- `flywheel_export_summary_render_pdf`
+
+## Legacy Archival Export
+
+Experimental settings keep legacy history export available as an archival
+migration aid. This path is read-only and outside canonical node workflows.
+
+## Related Docs
+
+- `docs/flywheel/CONCEPT.md`
+- `docs/flywheel/FLYWHEEL_MCP.md`
+- `docs/flywheel/PROVISIONING.md`
+- `docs/flywheel/ARTIFACTS.md`
+- `docs/flywheel/GIT_INTEGRATION.md`

package/skills/{flywheel/reference → flywheel-auto/references}/experiment-design-protocol.md

@@ -119,6 +119,9 @@ If the run is expensive or high-risk, ask for explicit confirmation.
 
 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.
@@ -137,11 +140,12 @@ 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`
+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: