@paradigma-inc/flywheel 0.1.16 → 0.1.25

package/skills/flywheel-to-graph/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-to-graph/references/source-blog.md

@@ -0,0 +1,34 @@
+# Blog Source Reference
+
+Use this reference for blog posts and article-style URLs.
+
+## Source Detection
+
+Match this reference for sources from common blog/article domains or article-like HTML pages.
+
+## Acquisition
+
+- Fetch URL content.
+- Extract main article body and heading structure.
+
+## Decomposition
+
+- Short posts: one node is acceptable.
+- Long posts: parent article node plus section children by top-level headings.
+
+## Content and Artifacts
+
+- Article narrative in node `content`.
+- Summary in `summary`.
+- Supporting media files as artifacts when available.
+
+## Edges
+
+- Use hierarchy edges when section children are created.
+- Avoid lateral interpretive edges by default.
+
+## Failure Behavior
+
+- If fetch or extraction fails, emit explicit failure and stop.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/skills/flywheel-to-graph/references/source-generic.md

@@ -0,0 +1,29 @@
+# Generic Source Reference
+
+Use this fallback when source type cannot be confidently matched to paper, wiki, blog, or notes.
+
+## Fallback Trigger
+
+Activate this reference only after deterministic and natural-language routing fail to produce a confident match.
+
+## Acquisition
+
+- Ask once for missing source location when not recoverable.
+- Perform best-effort extraction from the provided source.
+
+## Decomposition
+
+- If top-level headings are available, create parent and section children.
+- If no structural cues are available, create one node with explicit summary of limitations.
+
+## Content and Artifacts
+
+- Keep extracted narrative in `content`.
+- Attach supporting files as artifacts.
+
+## Failure Behavior
+
+- If extraction fails, emit explicit failure and stop.
+- Do not silently produce an underspecified graph.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/skills/flywheel-to-graph/references/source-notes.md

@@ -0,0 +1,34 @@
+# Notes Source Reference
+
+Use this reference for local note directories such as Obsidian vaults, Logseq exports, or plain markdown note trees.
+
+## Source Detection
+
+Match this reference when source is a local notes corpus with many small markdown files.
+
+## Acquisition
+
+- Enumerate note files in requested scope.
+- Preserve folder and filename context.
+
+## Decomposition
+
+- Default: one note file -> one node.
+- Large note files: split by top-level headings when useful.
+
+## Content and Artifacts
+
+- Note text in `content`.
+- Concise note synopsis in `summary`.
+- Embedded local files become artifacts when relevant.
+
+## Edges
+
+- Add edges only for durable relationships (hierarchy, prerequisite, dependency).
+- Keep casual backlinks inside markdown.
+
+## Failure Behavior
+
+- If note files cannot be read, emit explicit failure with affected paths.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/skills/flywheel-to-graph/references/source-paper.md

@@ -0,0 +1,85 @@
+# Paper Source Reference
+
+Use this reference when the source is a paper PDF, arXiv page, DOI URL, or direct PDF URL.
+
+## Source Detection
+
+Match this reference when any of these are true:
+
+- Local file ends with `.pdf`.
+- URL matches `arxiv.org/abs/`.
+- URL matches `arxiv.org/pdf/`.
+- URL is a DOI resolver link (`doi.org/...`).
+- URL is a direct PDF link.
+
+## Acquisition Rules
+
+Acquire source content in this order:
+
+1. Local PDF path: read local file bytes and preserve original filename.
+2. arXiv HTML URL (`arxiv.org/abs/...` or `arxiv.org/html/...`): fetch page body and parse section structure from HTML.
+3. arXiv PDF URL (`arxiv.org/pdf/...`): download PDF bytes and treat as PDF input.
+4. DOI URL: resolve final landing page; if it exposes a PDF, download it, otherwise fetch the HTML body.
+5. Direct PDF URL: download PDF bytes.
+
+## Parsing Rules
+
+For PDF text extraction, use parser fallback chain exactly:
+
+`PyMuPDF -> pypdfium2 -> pypdf`
+
+- Try one parser at a time in that order.
+- Advance to the next parser only when the previous parser fails to extract usable text.
+- If all parsers fail, emit explicit failure and stop. Do not continue with partial guessed structure.
+- If all parsers fail, do not silently produce a single-summary node with a PDF artifact.
+
+License note:
+
+- PyMuPDF is AGPL-3.0. Artifex offers a commercial license when AGPL terms are not acceptable for downstream distribution.
+
+For arXiv HTML parsing, use LaTeXML selector boundaries:
+
+- Top-level sections: `section.ltx_section`
+- Top-level headings: `h2.ltx_title`
+- Subsections: `section.ltx_subsection`
+- Subsection headings: `h3.ltx_title`
+
+Do not use naive `section` selectors without class filtering.
+
+## Graph Decomposition Contract
+
+Default shape:
+
+- Create one parent paper node under the requested root.
+- Create one child node per detected top-level paper section.
+- Typical section set includes Abstract, Introduction, Methods, Results, Discussion, Conclusion, and Related Work when present.
+
+## Content Placement Contract
+
+- Parent title: paper title.
+- Parent summary: abstract or concise abstract-derived synopsis.
+- Parent content: one-paragraph orientation plus links/references to section children.
+- Child content: narrative for that section only.
+
+## Artifact Contract
+
+- Attach the paper PDF artifact to the parent paper node.
+- Attach extracted figures/tables to the section child where they appear, when extraction is feasible.
+
+## Edge Contract
+
+- Use hierarchy edges for paper parent -> section children.
+- Do not add lateral interpretive edges (`cites`, `builds-on`, `derived-from`) by default.
+
+## Insight Controller Contract
+
+- Single-paper one-shot import: no separate insight control node is created.
+- Multi-paper corpus import: create one insight control node above paper parent nodes.
+
+## Failure Contract
+
+- If acquisition fails, return explicit failure with the failing source variant and stop.
+- If all parsers fail, return explicit failure and stop.
+- Do not silently degrade to one summary node plus artifact-only output.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/skills/flywheel-to-graph/references/source-wiki.md

@@ -0,0 +1,35 @@
+# Wiki Source Reference
+
+Use this reference for markdown wiki-style corpora, README trees, GitHub wiki exports, and Notion markdown exports.
+
+## Source Detection
+
+Match this reference when source material is wiki-like markdown content with multiple linked pages.
+
+## Acquisition
+
+- Collect all relevant markdown pages in scope.
+- Preserve stable page identifiers from file paths or page titles.
+
+## Decomposition
+
+- One stable page or concept maps to one node by default.
+- Large pages may split by top-level headings when that improves readability.
+
+## Content and Artifacts
+
+- Main narrative goes into node `content`.
+- Short synopsis goes into `summary`.
+- Supporting files (images, PDFs, data files, notebooks) are node artifacts.
+
+## Edges
+
+- Promote only durable semantic relationships to graph edges.
+- Keep incidental hyperlinks in markdown body.
+
+## Failure Behavior
+
+- If pages are unreadable or missing, emit explicit failure and stop for that page.
+- Do not silently skip unreadable pages.
+
+These rules apply only when `$flywheel-to-graph` is the active skill.

package/src/cli.mjs

@@ -40,6 +40,7 @@ import {
   listBundledSkills,
   partitionInstallSkillHosts,
   removeInstalledSkillsForHosts,
+  resolveSkillsAgentName,
   SUPPORTED_INSTALL_SKILL_HOSTS,
   resolveInstalledSkillDir,
   resolvePackageRoot,
@@ -403,7 +404,12 @@ async function setupHost(hostName, scope, serverUrl, apiKey, serverName) {
   };
 }
 
-function printSetupResults(results, scope, serverUrl) {
+function printSetupResults(
+  results,
+  scope,
+  serverUrl,
+  { showSkillRefreshGuidance = false, experimentalSyncAgents = [] } = {},
+) {
   log.blank();
   log.plain(pc.green("✔ Flywheel setup complete"));
   log.blank();
@@ -417,9 +423,48 @@ function printSetupResults(results, scope, serverUrl) {
     log.plain(`    ${icon} ${result.status}`);
     log.plain(`      ${pc.dim(result.filePath)}`);
   }
+  if (showSkillRefreshGuidance) {
+    log.blank();
+    log.plain("  Bundled skill refresh guidance");
+    log.plain(
+      `    Preferred: ${pc.bold("npx --yes @paradigma-inc/flywheel@latest setup --install-skill --project")}`,
+    );
+    log.plain(
+      `      ${pc.bold("npm install --save-dev @paradigma-inc/flywheel@latest")}`,
+    );
+    if (experimentalSyncAgents.length === 1) {
+      log.plain("    Optional path via skills experimental_sync:");
+      log.plain(
+        `      ${pc.bold(`npx skills experimental_sync --agent ${experimentalSyncAgents[0]} -y`)}`,
+      );
+    } else if (experimentalSyncAgents.length > 1) {
+      log.plain("    Optional path via skills experimental_sync for selected hosts:");
+      for (const agentName of experimentalSyncAgents) {
+        log.plain(
+          `      ${pc.bold(`npx skills experimental_sync --agent ${agentName} -y`)}`,
+        );
+      }
+    }
+  }
   log.blank();
 }
 
+function resolveExperimentalSyncAgentsForHosts(supportedHosts) {
+  const agentNames = [];
+  const seenAgentNames = new Set();
+
+  for (const hostName of supportedHosts) {
+    const agentName = resolveSkillsAgentName(hostName);
+    if (seenAgentNames.has(agentName)) {
+      continue;
+    }
+    seenAgentNames.add(agentName);
+    agentNames.push(agentName);
+  }
+
+  return agentNames;
+}
+
 async function promptGuidedSkillInstall(
   bundledSkillNames,
   unsupportedHosts,
@@ -658,7 +703,21 @@ async function runSetupCommand(options) {
       const completedCleanupState = cleanupState;
       cleanupState = null;
       await discardInstallSkillCleanupState(completedCleanupState);
-      printSetupResults(setupResults, scope, serverUrl);
+      const showSkillRefreshGuidance =
+        scope === "project" &&
+        skillDecisionMode === "install" &&
+        supportedHosts.length > 0;
+      printSetupResults(
+        setupResults,
+        scope,
+        serverUrl,
+        {
+          showSkillRefreshGuidance,
+          experimentalSyncAgents: showSkillRefreshGuidance
+            ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+            : [],
+        },
+      );
       return;
     }
 
@@ -720,7 +779,14 @@ async function runSetupCommand(options) {
     const completedCleanupState = cleanupState;
     cleanupState = null;
     await discardInstallSkillCleanupState(completedCleanupState);
-    printSetupResults(setupResults, scope, serverUrl);
+    const showSkillRefreshGuidance =
+      scope === "project" && supportedHosts.length > 0;
+    printSetupResults(setupResults, scope, serverUrl, {
+      showSkillRefreshGuidance,
+      experimentalSyncAgents: showSkillRefreshGuidance
+        ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+        : [],
+    });
   } catch (error) {
     if (cleanupState) {
       await cleanupInstalledSkillArtifactsForHosts({