@paradigma-inc/flywheel 0.1.16 → 0.1.19

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

@@ -1,160 +1,153 @@
 # 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.
+- Node lifecycle semantics are interface-agnostic (`stage_node_create`, `stage_node_update`, `commit_node`); MCP tools are one projection of this shared contract.
+- Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision`, and handle `409 conflict` with explicit reconciliation.
+- Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
+- Commit is finalize-only: commit requests require `expected_revision` and may optionally override `summary`; committed node state must still satisfy strict contract (`summary`/`outcome`, `empirical+completed` requires 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`.
 
 ## 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 lifecycle
+
+- `flywheel_stage_node_create` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/stage/create`; full-surface only): Stage creation of a new Flywheel node.
+- `flywheel_stage_node_update` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{node_id}/stage/update`; core surface): Stage mutable node fields, including content/readme text, with optimistic locking; use `no_artifacts_reason` when empirical completed nodes intentionally have no artifacts.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/commit`; core surface): Commit a node with contract validation.
+- `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. 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. 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. Optionally include grant approval bindings for each session.
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/expire`; core surface): Expire the current compute-grant approval session and release its active leases.
+- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Request budget approval and return approval_url + request_id for user confirmation before managed compute acquisition.
+- `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: `POST /mcp/nodes/{node_id}/compute/acquire`; 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 heartbeats and 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.
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release-all`; core surface): Asynchronously release all active managed compute leases 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_stage_node_update`: Stage changes with fresh expected_revision and resolve 409 conflicts explicitly.
+3. `flywheel_commit_node`: Commit once terminal and contract-complete.
+
+### Empirical Workflow
+
+1. `flywheel_stage_node_create`: Create a staged node, then set empirical fields before execution.
+2. `flywheel_stage_node_update`: Set `kind=empirical`, `hypothesis`, and summary fields with fresh `expected_revision`.
+3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval first. Response status is `approval_required`.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status. `approval_required` is a response state, not a request parameter.. 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_approval_sessions`: After approval, list approval sessions with include_approvals=true and use the active `compute_grant_id` for the current approval_session_id.
+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_stage_node_update`: update in-progress node fields (title/content/summary, kind/outcome/hypothesis/insights/no_artifacts_reason), always with fresh `expected_revision`.
+- `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), to detect any active user lease state.
+- `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`); this returns `approval_url` + `request_id` when interactive approval is needed.
+- `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable.
+- `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).
+- `flywheel_compute_release`: release compute when no longer needed.
+- `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution lifecycle.
+- `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_node`: finalize staged node state once terminal and contract-complete (optional summary override only).

package/skills/flywheel-lookahead/SKILL.md

@@ -141,5 +141,6 @@ The `Start nodes` line is the recovery anchor for later replans. If multiple fro
 
 - Build the graph explicitly with nodes, artifacts, and selected edges.
 - Do not request compute approval, acquire managed compute, or launch execution just to do planning.
+- These planning-only execution prohibitions apply only when $flywheel-lookahead is the active skill.
 
 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-auto` to advance a frontier autonomously under an explicit budget and persisted stop condition.

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

@@ -1,218 +1,49 @@
 # 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`)
+Canonical artifact upload/finalize contract derived from `mcp_contract.py`.
+
+## Upload Contract
+
+- Prepare tool: `flywheel_prepare_artifact_uploads`.
+- Finalize tool: `flywheel_finalize_artifact_uploads`.
+- Raw file upload required between prepare/finalize: `True`.
+- Upload transport step: `PUT` to `prepare.items[].upload_url`.
+- Required headers source: `prepare.items[].upload_headers`.
+- 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.
+- Raw upload stage success code: `202`.
+- Stage semantics: `accepted_and_staged`.
+- Finalize appends the batch with a single revision bump: `True`.
+- Forbidden upload payload kinds: `json_metadata_wrapper`.
+- Optional note field `note` applies to `artifact_metadata_record` (markdown allowed: `True`).
+
+## Supported Artifact Types
+
+- `text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`, `checkpoint`, `binary`, `diff_carousel`
+
+## Metadata Contract
+
+- `title` required non-empty: `True`.
+- Display label field: `title`.
+- Title normalization priority: `explicit_title` -> `payload.title` -> `payload.name` -> `basename(payload.path|payload.filename|payload.file)` -> `basename(filename)` -> `basename(storage_path)` -> `artifact_type` -> `artifact`.
+- Title must not derive from: `storage_url`.
+- `storage_url` purpose: `raw_artifact_byte_read_url`.
+- `storage_url` cannot be used as display label: `True`.
+
+## Preview and Read Contract
+
+- `flywheel_list_artifacts`: List node artifacts.
+- `flywheel_get_artifact`: Get one artifact by id.
+- No dedicated artifact preview tool exists in the current MCP operation catalog.
+- Guidance: use flywheel_prepare_artifact_uploads, raw-file upload, and flywheel_finalize_artifact_uploads to publish experiment evidence before empirical completed commits
+
+## Failure Causes to Handle Explicitly
+
+- Stale `expected_revision` on mutating calls returns `409` and requires explicit reconciliation.
+- Reusing an idempotency key with a different payload hash causes `409_conflict`.
+- Empirical `completed` commits must satisfy one of: `artifacts_non_empty`, `no_artifacts_reason_non_empty`.
+- Prepare item payloads must be structured objects; stringified JSON item payloads are invalid.
+- Uploading metadata wrappers instead of raw file bytes violates the upload contract.
+- Finalize requires a valid prepared batch token and staged uploads from that batch.