@paradigma-inc/flywheel 0.1.26 → 0.1.51

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

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

package/skills/flywheel/setting-up-flywheel/claude-code-cli-installation.md

@@ -1,4 +1,4 @@
-# [](https://flywheel.paradigma.inc//#installing-on-claude-code)Installing on Claude Code
+# Installing on Claude Code
 
 Use the setup wizard:
 

package/skills/flywheel/setting-up-flywheel/codex-cli-installation.md

@@ -1,4 +1,4 @@
-# [](https://flywheel.paradigma.inc//#installing-on-codex)Installing on Codex
+# Installing on Codex
 
 Use the setup wizard:
 

package/skills/flywheel/setting-up-flywheel/how-can-i-get-an-authorized-client_id-for-the-oauth-flow.md

@@ -1,4 +1,4 @@
-# [](https://flywheel.paradigma.inc//#faq-how-can-i-get-an-authorized-client_id-for-the-oauth-flow)FAQ: How Can I Get an Authorized `client_id` for the OAuth Flow?
+# FAQ: How Can I Get an Authorized `client_id` for the OAuth Flow?
 
 We support the standard MCP OAuth flow with dynamic client registration, as documented in the [MCP Authorization spec (dynamic client registration)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration).
 
@@ -14,7 +14,7 @@ That response includes the OAuth endpoints (`authorization_endpoint`, `token_end
 
 Then register your OAuth client using the `registration_endpoint`.
 
-## [](https://flywheel.paradigma.inc/tutorial#public-client-default)Public client (default)
+## Public client (default)
 
 This is the default for interactive MCP hosts (for example Claude Code, IDE hosts, local desktop clients). If `token_endpoint_auth_method` is omitted, we default to `none`.
 
@@ -31,7 +31,7 @@ curl -sS -X POST https://flywheel.paradigma.inc/mcp-server/register \
 
 The response returns a `client_id` and no `client_secret`.
 
-## [](https://flywheel.paradigma.inc/tutorial#confidential-client-optional)Confidential client (optional)
+## Confidential client (optional)
 
 Use this when your app has a trusted backend that can securely store secrets.
 

package/skills/flywheel/setting-up-flywheel/installation-overview.md

@@ -1,10 +1,10 @@
-# [](https://flywheel.paradigma.inc//#setting-up-flywheel)Setting up Flywheel
+# Setting up Flywheel
 
 We are in the business of automating science. As such, our first interface to Flywheel is through autonomous agents, specifically via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro).
 
 MCP enables you to natively connect and authenticate Flywheel to any compatible hosts. We recommend using Flywheel with [Codex](https://github.com/openai/codex) or [Claude code](https://github.com/anthropics/claude-code), but any MCP host should work.
 
-## [](https://flywheel.paradigma.inc/tutorial#one-command-setup-recommended)One-command setup (recommended)
+## One-command setup (recommended)
 
 Simply run:
 
@@ -12,7 +12,22 @@ Simply run:
 npx @paradigma-inc/flywheel setup
 ```
 
-## [](https://flywheel.paradigma.inc/tutorial#reinstall--cleanup)Reinstall / cleanup
+`setup` defaults to `--mode mcp`, which wires the Flywheel MCP server into the
+selected hosts and installs the bundled Flywheel skills. To install the skills
+without writing any MCP host config, run `setup --mode cli --install-skill`
+instead.
+
+If the user is on a remote shell (for example SSH'd into a server), loopback
+callback URLs resolve on the wrong machine. Use device auth instead:
+
+```bash
+npx @paradigma-inc/flywheel setup --auth-mode device
+```
+
+`--auth-mode device` prints a Flywheel device-auth URL and a short setup code;
+the user approves in a browser and the CLI polls until the API key is issued.
+
+## Reinstall / cleanup
 
 ```bash
 npx @paradigma-inc/flywheel setup
@@ -21,6 +36,6 @@ npx @paradigma-inc/flywheel uninstall
 
 `uninstall` removes Flywheel MCP entries from host config files.
 
-## [](https://flywheel.paradigma.inc/tutorial#web-connector-hosts-chatgptcom--claudeai--etc-)Web connector hosts (ChatGPT.com / Claude.ai / etc. )
+## Web connector hosts (ChatGPT.com / Claude.ai / etc. )
 
 Web connector hosts can still use OAuth-style connector flows. Keep using those host-native connector install UIs for ChatGPT.com custom apps, Claude.ai custom connectors, etc. Simply put `https://flywheel.paradigma.inc/mcp-server` as the URL when prompted.

package/skills/flywheel/setting-up-flywheel/other-hosts-installation.md

@@ -1,4 +1,4 @@
-# [](https://flywheel.paradigma.inc//#other-mcp-hosts)Other MCP hosts
+# Other MCP hosts
 
 If your host is not currently supported by `npx @paradigma-inc/flywheel setup`, you can still connect manually.
 

package/skills/flywheel/usage-and-workflows/what-to-do-with-flywheel.md

@@ -1,4 +1,4 @@
-# [](https://flywheel.paradigma.inc//#what-to-do-with-flywheel)What to do with Flywheel?
+# What to do with Flywheel?
 
 In our experience the best way to get an answer to this question is to ask it to your MCP host:
 
@@ -16,6 +16,7 @@ What you can do with it:
 - Commit outcomes with required structure (kind, outcome, summary) so results stay consistent.
 - Launch managed compute for a node with budget controls and track execution state.
 - Attach artifacts to nodes (text, tables, JSON, images, HTML/plots, checkpoints, diffs).
+- Configure hooks that call external HTTP endpoints when events occur.
 - Collaborate with others by sharing nodes/graphs.
 - Tag nodes, audit changes, and export summaries/PDFs/subgraphs.
 
@@ -32,3 +33,29 @@ If you want, I can walk you through creating your first node and a minimal workf
 Francesco is documenting some example workflows on his [X profile](https://x.com/tensorqt), like [organizing, exploring and iterating on a research topic](https://x.com/tensorqt/status/2032190671281332280?s=20) or [reproducing papers on a budget](https://x.com/tensorqt/status/2032555892399305171).
 
 We'll be sharing more example workflows there and also through our [Discord](https://discord.gg/aFg4zskefj), where we do weekly office hours. You should join!
+
+## Configure Hooks (Node Automations)
+
+Hooks are event-driven automations:
+
+- **Event**: a durable "something happened" record (currently `artifact.finalized`).
+- **Hook**: a durable rule configured on a node (trigger + scope + action).
+- **Run**: one execution record when a hook reacts to an event.
+- Hooks are dispatched by `worker-projection` and executed by ephemeral Fly Machines runners.
+- Each hook run launches `python -m server.run_hook_runner` in the same Fly app (`FLYWHEEL_HOOK_RUNNER_FLY_APP`).
+- Deployments roll out `worker-projection`; runner launches require `FLYWHEEL_HOOK_RUNNER_FLY_API_TOKEN` and `FLYWHEEL_HOOK_RUNNER_FLY_APP`.
+
+Typical setup:
+
+1. Create secrets for endpoint credentials:
+   `flywheel_create_hook_secret`.
+2. Create the hook:
+   `flywheel_create_hook` (trigger `artifact.finalized`, choose scope, define
+   HTTP action).
+3. Turn it on:
+   `flywheel_set_hook_enabled`.
+4. Verify behavior:
+   `flywheel_list_hook_runs`.
+
+WebUI path: open a node and use the **Hooks** panel in the right-side node
+panel area.

package/skills/flywheel/web-ui/the-flywheel-web-ui.md

@@ -1,4 +1,4 @@
-# [](https://flywheel.paradigma.inc//#the-flywheel-webui)The Flywheel WebUI
+# The Flywheel WebUI
 
 While most of your write-driven interactions with Flywheel will likely be through your MCP host, you will find the [https://flywheel.paradigma.inc](https://flywheel.paradigma.inc) WebUI useful for visualizing your graph and managing nodes and admin.
 

package/skills/flywheel-auto/SKILL.md

@@ -11,6 +11,17 @@ Use this skill when the task is to shape information inside Flywheel rather than
 
 If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/INTERFACES.md](references/INTERFACES.md) before mutating nodes or acquiring compute.
 
+## Modes
+
+This skill supports both Flywheel install modes:
+
+- **`--mode mcp` install**: route via [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md); tool calls take the form `flywheel_<tool>` (e.g., `flywheel_commit_node`).
+- **`--mode cli` install**: `setup --mode cli` configures runtime credentials, then route via [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md); tool calls take the form `flywheel <command>` (e.g., `flywheel nodes:commit`). Prerequisite for bare-binary routing: `npm install -g @paradigma-inc/flywheel`.
+
+When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+
+The Workflow below cites both the MCP tool name and its CLI equivalent inline at each imperative step. Pick the one matching your install mode.
+
 ## Input Contract
 
 Before execution, recover or establish these inputs:
@@ -59,16 +70,16 @@ Before execution, recover or establish these inputs:
    - Run the design gate from [references/experiment-design-protocol-autonomous.md](references/experiment-design-protocol-autonomous.md) before the first compute request: confirm objective, decision criterion, evidence plan, budget readiness, and stop-reason recording requirements, even though later continuation decisions become graph-local.
 3. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
-   - Create a new node with `flywheel_stage_node_create` when needed.
-   - Update an existing node with `flywheel_get_node` + `flywheel_stage_node_update` when continuing work.
+   - Create a new node with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI) when needed.
+   - Update an existing node with `flywheel_get_node` + `flywheel_acquire_stage_lease` + `flywheel_commit_node` (MCP) or `flywheel nodes:get` + `flywheel nodes:stage:lease:acquire` + `flywheel nodes:commit` (CLI) when continuing work.
 4. Put the primary page markdown or plan rationale in the node body/readme field (`content`).
    - Keep `summary` concise.
    - Populate `hypothesis`, `insights`, `outcome`, and similar fields only when the source actually supports them.
 5. Publish supporting files with the artifact upload flow.
    - For exact artifact contract details, load [references/ARTIFACTS.md](references/ARTIFACTS.md).
-   - Use `flywheel_prepare_artifact_uploads`.
+   - Use `flywheel_prepare_artifact_uploads` (MCP) or `flywheel artifacts:upload:prepare` (CLI).
    - Upload raw file bytes to the returned signed URLs.
-   - Call `flywheel_finalize_artifact_uploads` once all uploads in the batch are staged.
+   - Call `flywheel_finalize_artifact_uploads` (MCP) or `flywheel artifacts:upload:finalize` (CLI) once all uploads in the batch are staged.
    - Keep the artifact filename stable enough to reference from markdown when inline rendering matters.
 6. Add graph structure sparingly.
    - Promote only decision-relevant relationships to edges.
@@ -81,20 +92,20 @@ Before execution, recover or establish these inputs:
    - Keep unresolved plan nodes staged until the corresponding work is resolved.
 8. Execute and replan continuously.
    - For exact execution and compute request shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/experiment-design-protocol-autonomous.md](references/experiment-design-protocol-autonomous.md).
-   - Use `flywheel_launch_execution` when the branch can run as a Flywheel node execution without a separate leased machine, and inspect terminal status before commit.
-   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. In that case use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)`, call `flywheel_compute_list_options`, recommend one offer deterministically and present up to two alternatives, wait for explicit user confirmation (or explicit user override offer id), then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
+   - Use `flywheel_launch_execution` (MCP) or `flywheel executions:launch` (CLI) when the branch can run as a Flywheel node execution without a separate leased machine, and inspect terminal status before commit.
+   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. In MCP mode use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)`, call `flywheel_compute_list_options`, recommend one offer deterministically and present up to two alternatives, wait for explicit user confirmation (or explicit user override offer id), then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready. In CLI mode use the parallel `flywheel compute-grants:request-approval` → `flywheel compute-grants:list` → `flywheel compute:options` → `flywheel compute:acquire` → `flywheel compute:status` → `flywheel compute:connection` sequence.
    - Spawn up to `k` workers for distinct executable frontier nodes.
    - For `k > 1`, apply the list-options -> recommendation -> explicit confirmation boundary per worker before each worker-specific acquire call.
    - Route additional viable branches sequentially when there are more than `k` worthwhile directions.
    - After each resolved node, refresh the lookahead so the graph remains `n` hops ahead.
    - Release managed compute when a branch is done. Default to releasing only
-     known leases. Use `flywheel_compute_release_all` only when the user
+     known leases. Use `flywheel_compute_release_all` (MCP) or `flywheel compute:release-all` (CLI) only when the user
      explicitly requests account-wide cleanup.
    - Stop only when the graph-local terminal condition says to stop, such as: objective met, budget exhausted, or no non-redundant frontier branch is likely to produce enough decision-relevant information to justify the remaining budget and duplication risk.
    - If stopping because no non-redundant frontier branch is worth pursuing, record a per-candidate rejection rationale in control node `content` before termination.
    - Before every termination path, persist `stop_reason` in control node `content` as one of: `budget_exhausted`, `objective_met`, `no_viable_branch`, `user_cancelled`, `runtime_error`.
 
-9. Commit after the node snapshot is coherent with `flywheel_commit_node`.
+9. Commit after the node snapshot is coherent with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI).
    - Commit resolved insight nodes only when they have non-empty `insights`.
    - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
    - Leave unresolved plan nodes staged.
@@ -122,15 +133,15 @@ controller, load [references/INTERFACES.md](references/INTERFACES.md).
 Use this storage convention:
 
 1. Reuse an existing control node when one already governs the same frontier;
-   otherwise create one with `flywheel_stage_node_create`.
+   otherwise create one with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI).
 2. Put the canonical contract in node `content`.
 3. Put a one-line synopsis in `summary`.
 4. Put the run rationale, continuation rule, or prioritization logic in
    `insights` so the `insight` commit contract is satisfied.
-5. Update the control node with `flywheel_stage_node_update`.
-6. Read the control node with `flywheel_get_node` before later replans that need
+5. Before committing control-node edits, acquire or refresh the stage lease with `flywheel_acquire_stage_lease` (and `flywheel_heartbeat_stage_lease` for long edits) — or in CLI mode, `flywheel nodes:stage:lease:acquire` and `flywheel nodes:stage:lease:heartbeat`.
+6. Read the control node with `flywheel_get_node` (MCP) or `flywheel nodes:get` (CLI) before later replans that need
    a fresh `expected_revision` revision token for optimistic-locking writes.
-7. Commit the control node with `flywheel_commit_node` once the contract is
+7. Commit the control node with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI) once the contract is
    coherent, even if executable frontier nodes remain staged or in progress.
 
 Canonical contract shape:

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

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