@paradigma-inc/flywheel 0.1.16 → 0.1.25

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

@@ -1,160 +1,148 @@
 # Flywheel MCP Tool Map
 
-This reference describes the Flywheel MCP tool families and the common runtime
-contract expected by the public Flywheel skill.
+Contract-aligned routing guide for Flywheel MCP tool usage.
 
-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.
+Flywheel is a graph-based system for tracking research work, decisions, and evidence over time. Flywheel MCP is the tool interface for reading and updating that graph. You can discover, create, and manage nodes. You can collaborate with other users and use managed compute.
 
 ## 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.
+- Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
+- Node state is canonical durable state; avoid relying on ephemeral transcript state.
+- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- 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.
+- 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`.
 
 ## 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`
+### Discovery and sharing
+
+- `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.
+
+### 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.
 
 ### 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`
+- `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.
 
 ### 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.
+- `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.
+
+### 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_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_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.
+
+### 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.
 
 ## 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.
+### List Owned Nodes
+
+1. `flywheel_list_nodes` with `{'owners': ['me'], 'projection': 'core'}`.
+
+### Safe Node Update
+
+1. `flywheel_get_node`: Read latest node state before mutating fields.
+2. `flywheel_acquire_stage_lease`: Acquire a session-scoped stage lease before editing an existing node locally.
+3. `flywheel_commit_node`: Commit with `stage_session_id`, `base_committed_revision`, and full `staged_payload` once terminal and contract-complete.
+
+### Empirical Workflow
+
+1. `flywheel_commit_new_node`: Commit a local staged new node to canonical storage as the first persistence boundary.
+2. `flywheel_commit_node`: Commit staged empirical fields with `stage_session_id`, `base_committed_revision`, and a full `staged_payload` once the working state is ready to publish.
+3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval context first. Branch on response status.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`).. if `already_approved` then `reuse_compute_grant_id`: Use returned `compute_grant_id` directly for flywheel_compute_acquire.. if `approval_required` then `present_approval_url_to_user`: Present `approval_url` to the user; the user opens it and confirms budget approval.; `flywheel_list_compute_grants`: After approval, list active grants for the current `approval_session_id` and use the returned `compute_grant_id` for acquire.. if `insufficient_credits` then `request_user_credit_top_up`: No `approval_url` is returned. Ask the user to add credits, then retry flywheel_request_compute_grant_approval.
+5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id` from approval response.
+6. `flywheel_compute_status`: Poll until the active lease is ready; follow `recommended_next_action`.
+7. `flywheel_launch_execution`: Launch execution once compute and inputs are ready.
+8. `flywheel_list_executions`: Poll until execution reaches terminal status.
+9. `flywheel_prepare_artifact_uploads`: Prepare signed upload URLs for empirical evidence.
+10. `raw_file_upload`: Upload raw bytes to each signed URL with required headers.
+11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit, or set `no_artifacts_reason` when intentionally artifact-free.
+12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
+
+## Runtime Guidance
+
+- `flywheel_resolve_node_slug`: resolve human-facing slug references. If response status is `ambiguous`, ask the user to confirm the intended node_id before mutating anything.
+- `flywheel_get_node`: read the current node state before writes.
+- `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_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_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.
+- `flywheel_prepare_artifact_uploads`: prepare one or more signed raw-file upload requests for concrete deliverables/evidence produced by the work.
+- `flywheel_finalize_artifact_uploads`: finalize a staged artifact batch and append all uploaded artifacts in one revision bump.
+- `flywheel_delete_artifact`: remove an accidental/obsolete node artifact.
+- `flywheel_list_artifacts`, `flywheel_get_artifact`: inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
+- `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.

package/skills/flywheel-prove/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: flywheel-prove
+description: Local Lean theorem proving and formalization pipeline.
+---
+
+# flywheel-prove
+
+## When To Use
+
+Use this skill when you need to scaffold or run a local Lean theorem proving pipeline in a repo.
+Use it for formalization tasks that require filling `sorry` placeholders and proving statements in Lean.
+Use it when converting theorem-heavy source material into Lean modules, iterating on failed verification, or producing reproducible proof artifacts for review.
+
+## Prerequisite (Required)
+
+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:
+  - macOS/Linux:
+    ```bash
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    ```
+  - Windows (PowerShell):
+    ```powershell
+    irm https://astral.sh/uv/install.ps1 | iex
+    ```
+
+- If `elan` is missing, bootstrap it by OS:
+  - macOS/Linux:
+    ```bash
+    curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh -s -- -y
+    ```
+  - Windows (PowerShell):
+    ```powershell
+    Invoke-WebRequest -Uri https://raw.githubusercontent.com/leanprover/elan/master/elan-init.ps1 -OutFile elan-init.ps1
+    powershell -ExecutionPolicy Bypass -File .\elan-init.ps1
+    ```
+
+Then verify:
+
+```bash
+uv --version
+elan --version
+lean --version
+lake --version
+```
+
+## Workflow
+
+1. Scaffold pipeline into the current repository:
+
+   ```bash
+   python <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
+   cd <repo-root>/theorem_pipeline
+   ```
+
+   `<skill-root>` is the directory that contains this `SKILL.md`.
+   `pypdf` is installed via template dependencies during `uv sync`; do not use `pdftotext`.
+
+2. Move into `<repo-root>/theorem_pipeline` and initialize:
+
+   ```bash
+   uv run -m tproof.cli doctor
+   uv run -m tproof.cli init --build
+   ```
+
+   Warning: `init --build` may take a few minutes on first run (toolchain/dependency fetch + first build). It is typically much faster on later runs when proving multiple artifacts in the same workspace.
+   Requirement: Before executing `uv run -m tproof.cli init --build`, the agent MUST explicitly warn the human user in-chat about this first-run delay.
+
+3. Normalize source context before formalization (conditional by input type).
+   - First, identify the source type from the user request.
+   - If the source is a PDF:
+     - Extract text with `pypdf` (do not use `pdftotext`), enforce UTF-8-safe output, and sanitize mojibake.
+     - Required artifact A (full cached extraction):
+       - `theorem_pipeline/workspace/contexts/<pdf_stem>.txt`
+       - Example: `paper.pdf -> theorem_pipeline/workspace/contexts/paper.txt`
+     - Required artifact B (theorem-focused excerpt):
+       - `theorem_pipeline/workspace/contexts/<theorem_slug>_source_excerpt.txt`
+       - Example: `proposition2_source_excerpt.txt`
+     - Keep both artifacts. The full extraction is a reusable cache for proving multiple theorems from the same paper; do not reconvert the PDF if the cached full extraction already exists and is still valid.
+   - If the source is not a PDF (for example: prompt text, `.txt`, `.md`, `.tex`, or fetched online content):
+     - Skip PDF conversion.
+     - Use the source exactly as requested by the user.
+     - Store the normalized local source artifact under `theorem_pipeline/workspace/contexts/` (for example, `<theorem_slug>_source.txt`), and optionally store a focused excerpt as `<theorem_slug>_source_excerpt.txt` when useful.
+   - Explicit ASCII rewrites of common symbols are allowed (for example: `R-field -> Real`, `norm-notation -> norm x`, `leq -> <=`, `and -> /\\`, `arrow -> ->`).
+
+4. Start a run:
+
+   ```bash
+   uv run -m tproof.cli start-run --prompt-file ./workspace/prompts/fill_sorries.txt
+   ```
+
+5. Formalization contract (required before proving): define
+   - theorem name,
+   - exact assumptions,
+   - target conclusion,
+   - whether corollaries are required (`help` / `match` / `upper-bound`).
+
+6. Use required model routing:
+   - Mathematical proof work: a deep-thinking model suitable for complex mathematical reasoning.
+   - Programming/scripting/reporting work: a smaller coding-oriented model for automation and logs.
+
+7. Artifact destination (mandatory, no exceptions):
+   - Final theorem artifacts MUST live under:
+     - `theorem_pipeline/workspace/lean_project/ProofWorkspace/Final/`
+   - Never write final artifacts under `workspace/staging/` (forbidden).
+   - Lean module files must use Lean-safe filenames (no hyphens), for example:
+     - full formal proof file: `<Name>Full.lean`
+     - human-readable sketch file: `<Name>Sketch.md`
+     - example pair:
+       - `ProofWorkspace/Final/Proposition1Full.lean`
+       - `ProofWorkspace/Final/Proposition1Sketch.md`
+
+8. Fast iteration loop:
+
+   ```bash
+   lake env lean <tmpfile>
+   ```
+
+   Use `<tmpfile>` for quick local iterations, then copy finalized proof into the target module.
+
+9. Sidecar proof sketch (required):
+   - For each produced full proof file `<Name>Full.lean`, create a sibling sketch file `<Name>Sketch.md` in `ProofWorkspace/Final/`.
+   - Keep the sketch human-readable for paper-writing: theorem statement, assumptions, proof idea/structure, and how corollaries follow.
+   - In sketch files, write mathematics using LaTeX formulas with dollar syntax (`$...$` for inline and `$$...$$` for display).
+   - This is safe in the Lean project because the pipeline reindex/verification scans only `*.lean`.
+
+10. Reindex and verify:
+
+    ```bash
+    uv run -m tproof.cli reindex
+    uv run -m tproof.cli verify
+    ```
+
+    `verify` must pass with no unresolved `sorry` and no `.lean`/`.md` final artifacts under `workspace/staging/`.
+
+11. Mark run status:
+
+    ```bash
+    uv run -m tproof.cli set-status <run_id> COMPLETE --note "verified locally"
+    ```
+
+## Completion Checklist
+
+Always report:
+
+- theorem file path,
+- sidecar proof sketch path,
+- final artifact directory path (`theorem_pipeline/workspace/lean_project/ProofWorkspace/Final/`),
+- source context artifact path(s):
+  - if PDF input: full extraction path (`<pdf_stem>.txt`) and excerpt path (`<theorem_slug>_source_excerpt.txt`);
+  - otherwise: normalized source path used (for example `<theorem_slug>_source.txt`) and excerpt path if created,
+- theorem names,
+- verify log path,
+- run id/status.
+- Add one extra final report line (without changing existing format): `SUCCESS` or `FAIL: <reason>`.
+
+## Resources
+
+- Use `scripts/scaffold_pipeline.py` to install the full local pipeline template.
+- Use `references/workflow.md` for detailed run loop guidance.
+- Use `assets/pipeline_template/` as the canonical implementation source copied into each repository.
+- Use `agents/interface.yaml` as the universal skill interface metadata.

package/skills/flywheel-prove/agents/interface.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flywheel Prove"
+  short_description: "Local Lean theorem proving pipeline"
+  default_prompt: "Use $flywheel-prove to scaffold and run a local Lean theorem proving pipeline."

package/skills/flywheel-prove/assets/pipeline_template/bin/tproof

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+set -eu
+uv run -m tproof.cli "$@"

package/skills/flywheel-prove/assets/pipeline_template/bin/tproof.cmd

@@ -0,0 +1,2 @@
+@echo off
+uv run -m tproof.cli %*

package/skills/flywheel-prove/assets/pipeline_template/logs/.gitkeep

@@ -0,0 +1 @@
+

package/skills/flywheel-prove/assets/pipeline_template/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "tproof"
+version = "0.1.0"
+description = "Local Lean theorem proving pipeline"
+requires-python = ">=3.10"
+dependencies = [
+  "typer>=0.24.1",
+  "rich>=14.3.3",
+  "pypdf>=4.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100

package/skills/flywheel-prove/assets/pipeline_template/scripts/smoke_test.cmd

@@ -0,0 +1,2 @@
+@echo off
+uv run -m tproof.cli smoke-test %*

package/skills/flywheel-prove/assets/pipeline_template/scripts/smoke_test.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+set -eu
+uv run -m tproof.cli smoke-test "$@"

package/skills/flywheel-prove/assets/pipeline_template/src/tproof/__init__.py

@@ -0,0 +1 @@
+"""Local Lean theorem proving pipeline."""