@paradigma-inc/flywheel 0.1.25 → 0.1.35

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

@@ -12,6 +12,16 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - Node references include immutable `node_id` and optional immutable `slug_name`; prefer communicating both together for human clarity and disambiguation.
 - Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
 - Graph topology should encode logical/causal relations between concepts and experiments. Avoid defaulting to shallow root-only branching unless work items are truly independent.
+- Node staging is local (non-canonical) and commit is the only canonical persistence boundary (`commit_new_node`, `commit_node`).
+- Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision` or `base_committed_revision` as required, and handle `409 conflict` with explicit reconciliation.
+- Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
+- Existing-node field editing may use a session-scoped stage lease (`flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`) to coordinate local staged state before commit.
+- Existing-node commit publishes a full staged payload under an active stage lease: commit requests require `stage_session_id`, `base_committed_revision`, and `staged_payload`; conflicts on stale committed revisions are surfaced directly and are not transport-retried.
+- Stage/backfill helpers (`stage_backfill_hypothesis`, `stage_backfill_insights`) return non-canonical staged payload patches and explicit status fields (`staged_changes_pending`, `commit_required`, `next_action_hint`).
+- Committed node state must still satisfy strict contract (`summary` required; `empirical` requires hypothesis plus artifacts or `no_artifacts_reason`; `insight` requires non-empty insights).
+- When code is involved, pass `repo_url`/`branch_name`/`head_commit_sha` and align git structure with graph topology where practical (without forcing one-to-one mapping).
+- Summaries, hypotheses, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
+- Empirical workflow is hypothesis-driven: launch execution, inspect outcomes, publish evidence artifacts, and commit only after terminal status.
 - For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
 - Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
 
@@ -21,83 +31,84 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - `flywheel_auth_status` (read; scopes: `read`; HTTP: `GET /auth/status`; core surface): Return Flywheel auth status for the current access token.
 - `flywheel_get_credits_balance` (read; scopes: `read`; HTTP: `GET /credits`; core surface): Return current user credits balance and lifetime counters.
-- `flywheel_updates_list` (read; scopes: `read`; HTTP: `GET /mcp/updates`; core surface): List in-app updates/announcements for the signed-in user.
-- `flywheel_updates_hide` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/{announcement_id}/hide`; core surface): Mark one update as hidden for the current user (Don't show again).
-- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/hide-all-active`; core surface): Hide all active updates for the current user (Don't show all active again).
-- `flywheel_updates_unhide` (mutating; scopes: `write`; HTTP: `DELETE /mcp/updates/{announcement_id}/hide`; core surface): Restore one hidden update for the current user.
-- `flywheel_list_nodes` (read; scopes: `read`; HTTP: `GET /mcp/nodes`; full-surface only): List nodes with optional owners/writers/visibility filters and projection control (`core`, `topology`, `full`).
-- `flywheel_resolve_node_slug` (read; scopes: `read`; HTTP: `GET /mcp/nodes/resolve-by-slug`; core surface): Resolve a node by slug_name with explicit conflict handling (`unique`, `context_resolved`, `ambiguous`, `not_found`).
-- `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/sharing`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
-- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/sharing`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
-- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/sharing/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
-- `flywheel_get_node` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}`; core surface): Get one node by node_id.
-- `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node.
-- `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
-- `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.
-- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/tags`; full-surface only): Set graph tag assignments for one node.
-- `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
-- `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
-- `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
-- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
+- `flywheel_updates_list` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): List in-app updates/announcements for the signed-in user.
+- `flywheel_updates_hide` (mutating; scopes: `write`; HTTP: `POST /updates/{announcement_id}/hide`; core surface): Mark one update as hidden for the current user (Don't show again).
+- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; HTTP: `POST /updates/hide-all-active`; core surface): Hide all active updates for the current user (Don't show all active again).
+- `flywheel_updates_unhide` (mutating; scopes: `write`; HTTP: `DELETE /updates/{announcement_id}/hide`; core surface): Restore one hidden update for the current user.
+- `flywheel_list_nodes` (read; scopes: `read`; HTTP: `GET /nodes`; full-surface only): List nodes with optional owners/writers/visibility filters and projection control (`core`, `topology`, `full`).
+- `flywheel_resolve_node_slug` (read; scopes: `read`; HTTP: `GET /nodes/resolve-by-slug`; core surface): Resolve a node by slug_name with explicit conflict handling (`unique`, `context_resolved`, `ambiguous`, `not_found`).
+- `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `tool-mediated`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
+- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `tool-mediated`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
+- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id.
+- `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node. `track_history` is effective only when `one_only=true`; when `one_only=false`, the effective track_history=false.
+- `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
+- `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.
+- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; HTTP: `PUT /nodes/{node_id}/tags`; full-surface only): Set graph tag assignments for one node (`tag_ids` must be a JSON array of strings; omit `tag_ids` to clear all assignments to `[]`).
+- `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
+- `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
+- `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
+- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
 
 ### Node stage and commit
 
-- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
-- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
-- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
-- `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
-- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
-- `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/branch`; full-surface only): Create a child branch node.
-- `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
-- `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
-- `flywheel_remove_parent` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/parents/remove`; full-surface only): Detach one parent edge from a node without deleting the node.
-- `flywheel_delete_node` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}`; full-surface only): Delete a node subtree.
-- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/bulk-delete`; full-surface only): Delete multiple node subtrees in one operation.
+- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
+- `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; full-surface only): Create a child branch node with optimistic locking (`expected_revision` required).
+- `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
+- `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
+- `flywheel_remove_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/remove`; full-surface only): Detach one parent edge from a node without deleting the node.
+- `flywheel_delete_node` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}`; full-surface only): Delete a node and its descendants. Modes: `cascade` (delete full subtree), `detach_shared` (preserve descendants with surviving parents).
+- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/bulk-delete`; full-surface only): Delete multiple node subtrees in one operation.
 
 ### Artifacts
 
-- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`; core surface): Prepare one or more raw-file artifact uploads (returns batch token + signed upload URLs). Upload must send raw file bytes to the returned URLs (do not upload JSON metadata wrappers).
-- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`; core surface): Finalize a prepared artifact upload batch and append all staged artifacts to the node in one revision bump.
-- `flywheel_list_artifacts` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts`; core surface): List node artifacts.
-- `flywheel_get_artifact` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Get one artifact by id.
-- `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
-- `flywheel_set_artifact_note` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{node_id}/artifacts/{artifact_id}/note`; core surface): Set or clear one artifact note with optimistic locking.
+- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/prepare`; core surface): Prepare one or more raw-file artifact uploads (returns batch token + signed upload URLs). Upload must send raw file bytes to the returned URLs (do not upload JSON metadata wrappers).
+- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/finalize`; core surface): Finalize a prepared artifact upload batch and append all staged artifacts to the node in one revision bump.
+- `flywheel_list_artifacts` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): List node artifacts.
+- `flywheel_get_artifact` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one artifact by id.
+- `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
+- `flywheel_set_artifact_note` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{node_id}/artifacts/{artifact_id}/note`; core surface): Set or clear one artifact note with optimistic locking.
 
 ### Executions
 
-- `flywheel_launch_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions`; core surface): Launch node execution.
-- `flywheel_list_executions` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/executions`; core surface): List node executions.
-- `flywheel_terminate_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate`; core surface): Terminate a node execution.
+- `flywheel_launch_execution` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions`; core surface): Launch node execution.
+- `flywheel_list_executions` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/executions`; core surface): List node executions.
+- `flywheel_terminate_execution` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions/{execution_id}/terminate`; core surface): Terminate a node execution.
 
 ### Compute and budgets
 
-- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /mcp/nodes/{node_id}/compute/options`; core surface): List managed compute options allowed for a node. When using grant-backed compute, pass the same compute_grant_id you will use for acquire.
-- `flywheel_compute_status` (read; scopes: `compute`; HTTP: `GET /mcp/compute/status`; core surface): Read managed compute lease status for the current user and current lease_control_token scope. Lease rows include ownership flags so hosts can distinguish user-owned leases from sponsor-visible campaign leases. When checking a grant-backed lease, reuse the same compute_grant_id passed to acquire.
-- `flywheel_compute_connection` (read; scopes: `compute`; HTTP: `GET /mcp/compute/connection`; core surface): Read SSH connection material for an active managed compute lease once flywheel_compute_status indicates the lease is usable. This tool is token-scoped to lease_control_token and only leases owned by the current user are connectable. Pass lease_id or node_id to disambiguate when needed.
-- `flywheel_approval_session_heartbeat` (read; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/heartbeat`; core surface): Create or refresh a compute-grant approval session for the current MCP host session.
-- `flywheel_list_approval_sessions` (read; scopes: `compute`; HTTP: `GET /mcp/approval-sessions`; core surface): List approval sessions visible to the current user.
-- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/expire`; core surface): Expire the current compute-grant approval session context without releasing active leases.
+- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; core surface): List managed compute options allowed for a node. When using grant-backed compute, pass the same compute_grant_id you will use for acquire.
+- `flywheel_compute_funding` (read; scopes: `compute`; HTTP: `GET /compute/funding`; core surface): Read grant-scoped funding context (`grant_cents`, `remaining_cents`, and backing budget fields) for a `compute_grant_id` before compute acquire.
+- `flywheel_compute_status` (read; scopes: `compute`; HTTP: `GET /compute/status`; core surface): Read managed compute lease status for the current user and current lease_control_token scope. Lease rows include ownership flags so hosts can distinguish user-owned leases from sponsor-visible campaign leases. When checking a grant-backed lease, reuse the same compute_grant_id passed to acquire.
+- `flywheel_compute_connection` (read; scopes: `compute`; HTTP: `GET /compute/connection`; core surface): Read SSH connection material for an active managed compute lease once flywheel_compute_status indicates the lease is usable. This tool is token-scoped to lease_control_token and only leases owned by the current user are connectable. Pass lease_id or node_id to disambiguate when needed.
+- `flywheel_approval_session_heartbeat` (read; scopes: `compute`; HTTP: `POST /approval-sessions/heartbeat`; core surface): Create or refresh a compute-grant approval session for the current MCP host session.
+- `flywheel_list_approval_sessions` (read; scopes: `compute`; HTTP: `GET /approval-sessions`; core surface): List approval sessions visible to the current user.
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /approval-sessions/expire`; core surface): Expire the current compute-grant approval session context without releasing active leases.
 - `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Request budget approval context before managed compute acquisition; branch on response status.
-- `flywheel_list_compute_grants` (read; scopes: `compute`; HTTP: `GET /mcp/compute/grants`; core surface): List active/exhausted compute grants available to the current user.
-- `flywheel_list_campaign_budgets` (read; scopes: `compute`; HTTP: `GET /mcp/nodes/{root_node_id}/campaign-budgets`; full-surface only): List campaign compute budgets for a campaign root. Organizer-only management view.
-- `flywheel_create_campaign_budget` (mutating; scopes: `compute`; HTTP: `POST /mcp/nodes/{root_node_id}/campaign-budgets`; full-surface only): Create an organizer-funded campaign compute budget shared with participants.
-- `flywheel_update_campaign_budget` (mutating; scopes: `compute`; HTTP: `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Update hard caps or metadata for an organizer-funded campaign compute budget.
-- `flywheel_revoke_campaign_budget` (mutating; scopes: `compute`; HTTP: `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Revoke an organizer-funded campaign compute budget.
+- `flywheel_list_compute_grants` (read; scopes: `compute`; HTTP: `GET /compute/grants`; core surface): List active/exhausted compute grants available to the current user.
+- `flywheel_list_campaign_budgets` (read; scopes: `compute`; HTTP: `GET /nodes/{root_node_id}/campaign-budgets`; full-surface only): List campaign compute budgets for a campaign root. Organizer-only management view.
+- `flywheel_create_campaign_budget` (mutating; scopes: `compute`; HTTP: `POST /nodes/{root_node_id}/campaign-budgets`; full-surface only): Create an organizer-funded campaign compute budget shared with participants.
+- `flywheel_update_campaign_budget` (mutating; scopes: `compute`; HTTP: `PATCH /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Update hard caps or metadata for an organizer-funded campaign compute budget.
+- `flywheel_revoke_campaign_budget` (mutating; scopes: `compute`; HTTP: `DELETE /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; full-surface only): Revoke an organizer-funded campaign compute budget.
 - `flywheel_compute_acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Acquire managed compute for a node with explicit SKU + region and required compute_grant_id (returns accepted/completed lease state only; poll flywheel_compute_status for readiness, not SSH key material). This tool forwards approval_session_id.
-- `flywheel_compute_release` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release`; core surface): Asynchronously release one managed compute lease by lease_id within the current lease_control_token scope.
-- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release-all`; core surface): Asynchronously release active managed compute leases in the current lease_control_token scope; set force=true for explicit account-wide cleanup for the current user.
+- `flywheel_compute_release` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Asynchronously release one managed compute lease by lease_id within the current lease_control_token scope.
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Asynchronously release active managed compute leases in the current lease_control_token scope; set force=true for explicit account-wide cleanup for the current user.
 
 ### Contract, audit, and export
 
 - `flywheel_get_contract` (read; scopes: `read`; HTTP: `GET /mcp/contract`; core surface): Return Flywheel MCP contract overview (scopes, write safety, operation catalog, and section index).
 - `flywheel_get_contract_section` (read; scopes: `read`; HTTP: `GET /mcp/contract/sections/{section_id}`; core surface): Return one contract section by section_id (for example `graph` or `campaign/template_v1`).
-- `flywheel_export_subgraph` (read; scopes: `read`; HTTP: `POST /mcp/export`; full-surface only): Export selected graph/subgraph nodes as JSON.
-- `flywheel_import_subgraph` (mutating; scopes: `write`; HTTP: `POST /mcp/import`; full-surface only): Import graph/subgraph JSON payload into new node IDs. Set normalize_cycles=true to drop cycle/self-loop edges; default rejects cyclic payloads.
-- `flywheel_summarize_node_tree` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/summary`; full-surface only): Summarize a node tree using node fields only.
-- `flywheel_export_summary` (read; scopes: `read`; HTTP: `POST /mcp/export-summary`; full-surface only): Generate markdown summary for selected nodes.
-- `flywheel_export_summary_stream` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-stream`; full-surface only): Generate summary stream events for selected nodes.
-- `flywheel_export_summary_pdf` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-pdf`; full-surface only): Generate PDF summary for selected nodes.
-- `flywheel_export_summary_render_pdf` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-render-pdf`; full-surface only): Render provided markdown to PDF and embed export metadata.
+- `flywheel_export_subgraph` (read; scopes: `read`; HTTP: `POST /export`; full-surface only): Export selected graph/subgraph nodes as JSON.
+- `flywheel_import_subgraph` (mutating; scopes: `write`; HTTP: `POST /import`; full-surface only): Import graph/subgraph JSON payload into new node IDs. Set normalize_cycles=true to drop cycle/self-loop edges; default rejects cyclic payloads.
+- `flywheel_summarize_node_tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/summary`; full-surface only): Summarize a node tree using node fields only.
+- `flywheel_export_summary` (read; scopes: `read`; HTTP: `POST /export-summary`; full-surface only): Generate markdown summary for selected nodes.
+- `flywheel_export_summary_stream` (read; scopes: `read`; HTTP: `POST /export-summary-stream`; full-surface only): Generate summary stream events for selected nodes.
+- `flywheel_export_summary_pdf` (read; scopes: `read`; HTTP: `POST /export-summary-pdf`; full-surface only): Generate PDF summary for selected nodes.
+- `flywheel_export_summary_render_pdf` (read; scopes: `read`; HTTP: `POST /export-summary-render-pdf`; full-surface only): Render provided markdown to PDF and embed export metadata.
 
 ## Practical Tool Sequences
 
@@ -133,11 +144,14 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`: coordinate session-scoped local staged edits for an existing node before commit.
 - `flywheel_get_campaign_snapshot`: read the current derived campaign state for this node's root campaign instead of inferring standings from freeform text.
 - `flywheel_get_node_sharing`: after sharing writes, verify with flywheel_get_node_sharing before reporting private/shared/public state.
+- `flywheel_set_node_tag_assignments`: pass `tag_ids` as a JSON array of strings; omitting `tag_ids` clears all assignments (`[]`).
+- `flywheel_list_nodes`: canonical filter inputs for `owners`, `writers`, and `visibility` are arrays; scalar `owners`/`writers` may be normalized by transport compatibility layers, but array form is preferred.
 - `flywheel_compute_status`: check first when work may need managed compute (GPU), using the active lease_control_token from host context (or pass it explicitly).
 - `flywheel_list_compute_grants`: list active compute grants (funded by user/root budgets) and select one `compute_grant_id` for acquisition.
 - `flywheel_request_compute_grant_approval`: request/confirm budget before acquire and choose a budget source (`user` or `root`); branch on status (`already_approved`, `approval_required`, `insufficient_credits`).
 - `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable, scoped by lease_control_token.
-- `flywheel_compute_list_options`: use when a lease is needed and no suitable active lease exists, then select explicit provider-qualified `offer_id` (`provider::offer_id`) and `region`. Consider each option's `availability_mode`: `live_capacity` means provider-reported capacity, `allocation_time` means capacity is confirmed only when `flywheel_compute_acquire` attempts provisioning.
+- `flywheel_compute_list_options`: use when a lease is needed and no suitable active lease exists, then select explicit provider-qualified `offer_id` (`provider::offer_id`) and `region`. This is a catalog-only read and excludes grant/budget money fields.
+- `flywheel_compute_funding`: read grant-scoped funding context (`grant_cents`, `remaining_cents`, backing budget fields) for the selected `compute_grant_id` before acquire.
 - `flywheel_compute_acquire`: provision compute once requirements are clear. This requires a valid `compute_grant_id` and returns lease/provisioning state only (not SSH key material). Capture `compute.lease_control_token` from the response for follow-up lease control tools.
 - `flywheel_compute_release`: release compute when no longer needed, scoped by lease_control_token.
 - `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution status transitions.

package/skills/flywheel-prove/SKILL.md

@@ -13,6 +13,14 @@ Use it when converting theorem-heavy source material into Lean modules, iteratin
 
 ## Prerequisite (Required)
 
+As the very first thing, you MUST use the plan tool to create a task list with checkmarks for all the workflow steps that follow.
+
+- If you are a codex model, use `update_plan`.
+- If you are a claude model, use `TaskCreate`.
+- If you are another model/harness, use an equivalent.
+
+Include the following pre-requisite in the checkmark list.
+
 Before running the pipeline, ensure both `uv` and the Lean toolchain manager `elan` are installed on the local machine.
 
 - If `uv` is missing, bootstrap it by OS:

package/skills/flywheel-reproduce/SKILL.md

@@ -63,8 +63,8 @@ Before execution, recover or establish these inputs:
      branch planning or execution.
 4. 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.
+   - Create a new node with `flywheel_commit_new_node` when needed.
+   - Update an existing node with `flywheel_get_node` + `flywheel_acquire_stage_lease` + `flywheel_commit_node` when continuing work.
 5. Put the primary page markdown or validation 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.
@@ -111,11 +111,11 @@ For the canonical entity model and public contract terminology behind this contr
 
 Use this storage convention:
 
-1. Reuse an existing control node when one already governs the same source or claim family; otherwise create one with `flywheel_stage_node_create`.
+1. Reuse an existing control node when one already governs the same source or claim family; otherwise create one with `flywheel_commit_new_node`.
 2. Put the canonical contract in node `content`.
 3. Put a one-line synopsis in `summary`.
 4. Put the validation rationale, branch-priority logic, or continuation rule in `insights` so the `insight` commit contract is satisfied.
-5. Update the control node with `flywheel_stage_node_update`.
+5. Before committing control-node edits, acquire or refresh the stage lease with `flywheel_acquire_stage_lease` (and `flywheel_heartbeat_stage_lease` for long edits).
 6. Read the control node with `flywheel_get_node` before later passes that need a fresh `expected_revision`.
 7. Commit the control node with `flywheel_commit_node` once the contract is coherent, even if downstream validation branches remain staged or in progress.
 

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

@@ -12,7 +12,7 @@ Canonical artifact upload/finalize contract derived from `mcp_contract.py`.
 - Upload body contract: `raw_file_bytes`.
 - Prepare item required fields: `artifact_type`, `filename`, `media_type`.
 - Prepare item optional fields: `title`, `execution_id`, `metadata`, `note`.
-- Prepare item note: prepare.items[] is structured object input at the tool boundary; stringified JSON payloads are invalid.
+- Prepare item note: prepare.items[] is structured object input. The transport layer may tolerate stringified JSON as a compatibility measure; this tolerance is not contractual and may be removed.
 - Raw upload stage success code: `202`.
 - Stage semantics: `accepted_and_staged`.
 - Finalize appends the batch with a single revision bump: `True`.

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

@@ -82,6 +82,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 ### Compute and budgets
 
 - `flywheel_compute_list_options` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_funding` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_compute_status` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_compute_connection` (read; scopes: `compute`; core surface; binding: `operation`)
 - `flywheel_approval_session_heartbeat` (read; scopes: `compute`; core surface; binding: `operation`)
@@ -115,83 +116,84 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 
 - `GET /auth/status` -> `flywheel_auth_status`
 - `GET /credits` -> `flywheel_get_credits_balance`
-- `GET /mcp/updates` -> `flywheel_updates_list`
-- `POST /mcp/updates/{announcement_id}/hide` -> `flywheel_updates_hide`
-- `POST /mcp/updates/hide-all-active` -> `flywheel_updates_hide_all_active`
-- `DELETE /mcp/updates/{announcement_id}/hide` -> `flywheel_updates_unhide`
-- `GET /mcp/nodes` -> `flywheel_list_nodes`
-- `GET /mcp/nodes/resolve-by-slug` -> `flywheel_resolve_node_slug`
-- `GET /mcp/nodes/{node_id}/sharing` -> `flywheel_get_node_sharing`
-- `PUT /mcp/nodes/{node_id}/sharing` -> `flywheel_set_sharing_for_node`
-- `POST /mcp/nodes/sharing/bulk` -> `flywheel_set_sharing_for_nodes`
-- `GET /mcp/nodes/{node_id}` -> `flywheel_get_node`
-- `POST /mcp/nodes/{root_node_id}/tags` -> `flywheel_create_node_tag`
-- `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_update_node_tag`
-- `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_delete_node_tag`
-- `PUT /mcp/nodes/{node_id}/tags` -> `flywheel_set_node_tag_assignments`
-- `GET /mcp/nodes/{node_id}/tree` -> `flywheel_get_node_tree`
-- `GET /mcp/nodes/{node_id}/ancestry` -> `flywheel_get_node_ancestry`
-- `GET /mcp/nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
-- `GET /mcp/nodes/{node_id}/audit` -> `flywheel_list_audit`
+- `tool-mediated` -> `flywheel_updates_list`
+- `POST /updates/{announcement_id}/hide` -> `flywheel_updates_hide`
+- `POST /updates/hide-all-active` -> `flywheel_updates_hide_all_active`
+- `DELETE /updates/{announcement_id}/hide` -> `flywheel_updates_unhide`
+- `GET /nodes` -> `flywheel_list_nodes`
+- `GET /nodes/resolve-by-slug` -> `flywheel_resolve_node_slug`
+- `tool-mediated` -> `flywheel_get_node_sharing`
+- `tool-mediated` -> `flywheel_set_sharing_for_node`
+- `POST /nodes/access-policy/bulk` -> `flywheel_set_sharing_for_nodes`
+- `tool-mediated` -> `flywheel_get_node`
+- `POST /nodes/{root_node_id}/tags` -> `flywheel_create_node_tag`
+- `PATCH /nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_update_node_tag`
+- `DELETE /nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_delete_node_tag`
+- `PUT /nodes/{node_id}/tags` -> `flywheel_set_node_tag_assignments`
+- `GET /nodes/{node_id}/tree` -> `flywheel_get_node_tree`
+- `GET /nodes/{node_id}/ancestry` -> `flywheel_get_node_ancestry`
+- `GET /nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
+- `GET /nodes/{node_id}/audit` -> `flywheel_list_audit`
 
 ### Node stage and commit
 
-- `POST /mcp/nodes/commit-new` -> `flywheel_commit_new_node`
-- `POST /mcp/nodes/{node_id}/stage/lease/acquire` -> `flywheel_acquire_stage_lease`
-- `POST /mcp/nodes/{node_id}/stage/lease/heartbeat` -> `flywheel_heartbeat_stage_lease`
-- `POST /mcp/nodes/{node_id}/stage/lease/release` -> `flywheel_release_stage_lease`
-- `POST /mcp/nodes/{node_id}/commit` -> `flywheel_commit_node`
-- `POST /mcp/nodes/{node_id}/branch` -> `flywheel_branch_node`
-- `POST /mcp/nodes/merge` -> `flywheel_merge_nodes`
-- `POST /mcp/nodes/{node_id}/parents/add` -> `flywheel_add_parent`
-- `POST /mcp/nodes/{node_id}/parents/remove` -> `flywheel_remove_parent`
-- `DELETE /mcp/nodes/{node_id}` -> `flywheel_delete_node`
-- `POST /mcp/nodes/bulk-delete` -> `flywheel_bulk_delete_nodes`
+- `POST /nodes/commit-new` -> `flywheel_commit_new_node`
+- `POST /nodes/{node_id}/stage/lease/acquire` -> `flywheel_acquire_stage_lease`
+- `POST /nodes/{node_id}/stage/lease/heartbeat` -> `flywheel_heartbeat_stage_lease`
+- `POST /nodes/{node_id}/stage/lease/release` -> `flywheel_release_stage_lease`
+- `POST /nodes/{node_id}/commit` -> `flywheel_commit_node`
+- `POST /nodes/{node_id}/branch` -> `flywheel_branch_node`
+- `POST /nodes/merge` -> `flywheel_merge_nodes`
+- `POST /nodes/{node_id}/parents/add` -> `flywheel_add_parent`
+- `POST /nodes/{node_id}/parents/remove` -> `flywheel_remove_parent`
+- `DELETE /nodes/{node_id}` -> `flywheel_delete_node`
+- `POST /nodes/bulk-delete` -> `flywheel_bulk_delete_nodes`
 
 ### Artifacts
 
-- `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare` -> `flywheel_prepare_artifact_uploads`
-- `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize` -> `flywheel_finalize_artifact_uploads`
-- `GET /mcp/nodes/{node_id}/artifacts` -> `flywheel_list_artifacts`
-- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}` -> `flywheel_get_artifact`
-- `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}` -> `flywheel_delete_artifact`
-- `PATCH /mcp/nodes/{node_id}/artifacts/{artifact_id}/note` -> `flywheel_set_artifact_note`
+- `POST /nodes/{node_id}/artifacts/uploads/prepare` -> `flywheel_prepare_artifact_uploads`
+- `POST /nodes/{node_id}/artifacts/uploads/finalize` -> `flywheel_finalize_artifact_uploads`
+- `tool-mediated` -> `flywheel_list_artifacts`
+- `tool-mediated` -> `flywheel_get_artifact`
+- `DELETE /nodes/{node_id}/artifacts/{artifact_id}` -> `flywheel_delete_artifact`
+- `PATCH /nodes/{node_id}/artifacts/{artifact_id}/note` -> `flywheel_set_artifact_note`
 
 ### Executions
 
-- `POST /mcp/nodes/{node_id}/executions` -> `flywheel_launch_execution`
-- `GET /mcp/nodes/{node_id}/executions` -> `flywheel_list_executions`
-- `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate` -> `flywheel_terminate_execution`
+- `POST /nodes/{node_id}/executions` -> `flywheel_launch_execution`
+- `GET /nodes/{node_id}/executions` -> `flywheel_list_executions`
+- `POST /nodes/{node_id}/executions/{execution_id}/terminate` -> `flywheel_terminate_execution`
 
 ### Compute and budgets
 
-- `GET /mcp/nodes/{node_id}/compute/options` -> `flywheel_compute_list_options`
-- `GET /mcp/compute/status` -> `flywheel_compute_status`
-- `GET /mcp/compute/connection` -> `flywheel_compute_connection`
-- `POST /mcp/approval-sessions/heartbeat` -> `flywheel_approval_session_heartbeat`
-- `GET /mcp/approval-sessions` -> `flywheel_list_approval_sessions`
-- `POST /mcp/approval-sessions/expire` -> `flywheel_expire_approval_session`
+- `GET /compute/catalog` -> `flywheel_compute_list_options`
+- `GET /compute/funding` -> `flywheel_compute_funding`
+- `GET /compute/status` -> `flywheel_compute_status`
+- `GET /compute/connection` -> `flywheel_compute_connection`
+- `POST /approval-sessions/heartbeat` -> `flywheel_approval_session_heartbeat`
+- `GET /approval-sessions` -> `flywheel_list_approval_sessions`
+- `POST /approval-sessions/expire` -> `flywheel_expire_approval_session`
 - `tool-mediated` -> `flywheel_request_compute_grant_approval`
-- `GET /mcp/compute/grants` -> `flywheel_list_compute_grants`
-- `GET /mcp/nodes/{root_node_id}/campaign-budgets` -> `flywheel_list_campaign_budgets`
-- `POST /mcp/nodes/{root_node_id}/campaign-budgets` -> `flywheel_create_campaign_budget`
-- `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_update_campaign_budget`
-- `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_revoke_campaign_budget`
+- `GET /compute/grants` -> `flywheel_list_compute_grants`
+- `GET /nodes/{root_node_id}/campaign-budgets` -> `flywheel_list_campaign_budgets`
+- `POST /nodes/{root_node_id}/campaign-budgets` -> `flywheel_create_campaign_budget`
+- `PATCH /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_update_campaign_budget`
+- `DELETE /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_revoke_campaign_budget`
 - `tool-mediated` -> `flywheel_compute_acquire`
-- `POST /mcp/compute/release` -> `flywheel_compute_release`
-- `POST /mcp/compute/release-all` -> `flywheel_compute_release_all`
+- `tool-mediated` -> `flywheel_compute_release`
+- `tool-mediated` -> `flywheel_compute_release_all`
 
 ### Contract, audit, and export
 
 - `GET /mcp/contract` -> `flywheel_get_contract`
 - `GET /mcp/contract/sections/{section_id}` -> `flywheel_get_contract_section`
-- `POST /mcp/export` -> `flywheel_export_subgraph`
-- `POST /mcp/import` -> `flywheel_import_subgraph`
-- `GET /mcp/nodes/{node_id}/summary` -> `flywheel_summarize_node_tree`
-- `POST /mcp/export-summary` -> `flywheel_export_summary`
-- `POST /mcp/export-summary-stream` -> `flywheel_export_summary_stream`
-- `POST /mcp/export-summary-pdf` -> `flywheel_export_summary_pdf`
-- `POST /mcp/export-summary-render-pdf` -> `flywheel_export_summary_render_pdf`
+- `POST /export` -> `flywheel_export_subgraph`
+- `POST /import` -> `flywheel_import_subgraph`
+- `GET /nodes/{node_id}/summary` -> `flywheel_summarize_node_tree`
+- `POST /export-summary` -> `flywheel_export_summary`
+- `POST /export-summary-stream` -> `flywheel_export_summary_stream`
+- `POST /export-summary-pdf` -> `flywheel_export_summary_pdf`
+- `POST /export-summary-render-pdf` -> `flywheel_export_summary_render_pdf`
 
 ## Auth and Write Safety
 

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

@@ -128,9 +128,9 @@ Use an `insight` node to capture rationale, open questions, experiment shape, an
 
 Typical flow:
 
-1. `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update`
-3. `mcp__flywheel__flywheel_commit_node`
+1. `mcp__flywheel__flywheel_commit_new_node`
+2. `mcp__flywheel__flywheel_acquire_stage_lease` when refining an existing design node
+3. `mcp__flywheel__flywheel_commit_node` once the design brief is coherent
 
 ### Execution layer
 
@@ -138,8 +138,8 @@ Only after the design gate passes, create or branch the `empirical` node for the
 
 Typical flow:
 
-1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update` with the explicit run summary and the local question or hypothesis for that branch
+1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_commit_new_node`
+2. `mcp__flywheel__flywheel_acquire_stage_lease` + `mcp__flywheel__flywheel_commit_node` with the explicit run summary and the local question or hypothesis for that branch
 3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
 4. `mcp__flywheel__flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)` when you need to resolve the approved `compute_grant_id`
 5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed