@paradigma-inc/flywheel 0.1.26 → 0.1.51

package/skills/flywheel-to-graph/references/flywheel-cli-tool-map.md

@@ -0,0 +1,244 @@
+# Flywheel CLI Tool Map
+
+Contract-aligned routing guide for the Flywheel runtime CLI.
+
+The Flywheel CLI (`flywheel <command>`) is the runtime command surface shipped by `@paradigma-inc/flywheel`. It wraps the canonical Flywheel HTTP API and is the parallel surface to Flywheel MCP. Use this map when the host install is `--mode cli` (skills installed without an MCP server entry) or whenever scripted / direct-API workflows are preferable to MCP tool calls.
+
+For the MCP routing, see `flywheel-mcp-tool-map.md`. Every entry in the "MCP-equivalent" families below maps one-to-one to an MCP tool there. The "CLI-only" family at the end contains commands with no MCP counterpart.
+
+## Core Contract Expectations
+
+The CLI respects the same contracts the MCP surface enforces. See `flywheel-mcp-tool-map.md`'s "Core Contract Expectations" section for the canonical statements; the additions below are CLI-specific:
+
+- Mutating commands enforce optimistic locking via flags like `--expected_revision`; pass the latest revision token read from `flywheel nodes:get` and handle `409 conflict` with explicit reconciliation.
+- Stage-lease coordination mirrors the MCP stage-lease tools: `flywheel nodes:stage:lease:acquire` → `flywheel nodes:stage:lease:heartbeat` (during long edits) → `flywheel nodes:commit` → `flywheel nodes:stage:lease:release`.
+- Inline JSON payloads can be supplied with `--payload_json=<json>` or read from a file with `--payload_json=@path/to/file.json`.
+- Output format is controlled by `--format json|tsv|csv|table` (default: `json`). Pipe-friendly forms (`tsv`, `csv`) are useful for scripting.
+- For artifact uploads, the CLI offers a one-shot `flywheel artifacts:upload` that internally runs prepare + raw PUT + finalize. The split commands (`flywheel artifacts:upload:prepare`, `flywheel artifacts:upload:finalize`) are available for streaming or chunked uploads.
+- Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
+
+## MCP-Equivalent Tool Families
+
+The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI equivalent of each MCP tool.
+
+### Discovery and sharing
+
+- `flywheel auth:status` (read; scopes: `read`; HTTP: `GET /auth/status`; MCP equivalent: `flywheel_auth_status`): Show authentication status for the current client context.
+- `flywheel credits:balance` (read; scopes: `read`; HTTP: `GET /credits`; MCP equivalent: `flywheel_get_credits_balance`): View credit balance and totals.
+- `flywheel updates:list` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_updates_list`): List in-app announcements relevant to your account.
+- `flywheel updates:hide` (mutating; scopes: `write`; HTTP: `POST /updates/{announcement_id}/hide`; MCP equivalent: `flywheel_updates_hide`): Hide a specific announcement.
+- `flywheel updates:hide-all-active` (mutating; scopes: `write`; HTTP: `POST /updates/hide-all-active`; MCP equivalent: `flywheel_updates_hide_all_active`): Hide all currently active announcements.
+- `flywheel updates:unhide` (mutating; scopes: `write`; HTTP: `DELETE /updates/{announcement_id}/hide`; MCP equivalent: `flywheel_updates_unhide`): Restore a previously hidden announcement.
+- `flywheel nodes:list` (read; scopes: `read`; HTTP: `GET /nodes`; MCP equivalent: `flywheel_list_nodes`): List nodes with optional filters (owners/writers/visibility) and projection control (`core`, `topology`, `full`).
+- `flywheel nodes:resolve-slug` (read; scopes: `read`; HTTP: `GET /nodes/resolve-by-slug`; MCP equivalent: `flywheel_resolve_node_slug`): Resolve a slug to a node ID with explicit conflict handling (`unique`, `context_resolved`, `ambiguous`, `not_found`).
+- `flywheel nodes:sharing:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node_sharing`): Get sharing (access policy) for a node.
+- `flywheel nodes:sharing:set` (mutating; scopes: `write`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_set_sharing_for_node`): Replace sharing (access policy) for a node.
+- `flywheel nodes:sharing:set-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; MCP equivalent: `flywheel_set_sharing_for_nodes`): Apply one sharing policy to multiple nodes.
+- `flywheel nodes:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_node`): Fetch one node by identifier.
+- `flywheel tags:create` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; MCP equivalent: `flywheel_create_node_tag`): Create a reusable tag on a graph root.
+- `flywheel tags:update` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition.
+- `flywheel tags:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_delete_node_tag`): Delete a tag definition from the graph.
+- `flywheel tags:assign` (mutating; scopes: `write`; HTTP: `PUT /nodes/{node_id}/tags`; MCP equivalent: `flywheel_set_node_tag_assignments`): Assign or clear tags on a node (atomic replace; `--tag_ids` accepts a JSON array).
+- `flywheel nodes:render:tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/tree`; MCP equivalent: `flywheel_get_node_tree`): Render a bounded tree projection for a node.
+- `flywheel nodes:render:ancestry` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/ancestry`; MCP equivalent: `flywheel_get_node_ancestry`): Render ancestry (roots-ward lineage) for a node.
+- `flywheel campaign:snapshot` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/campaign/snapshot`; MCP equivalent: `flywheel_get_campaign_snapshot`): Resolve campaign root snapshot for a node.
+- `flywheel nodes:audit:list` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/audit`; MCP equivalent: `flywheel_list_audit`): List audit events for node-level actions.
+
+### Node stage and commit
+
+- `flywheel nodes:commit-new` (mutating; scopes: `write`; HTTP: `POST /nodes/commit-new`; MCP equivalent: `flywheel_commit_new_node`): Create and commit a new node in one request.
+- `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; MCP equivalent: `flywheel_acquire_stage_lease`): Acquire an edit lease for an existing node.
+- `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; MCP equivalent: `flywheel_heartbeat_stage_lease`): Heartbeat an active node stage lease.
+- `flywheel nodes:stage:lease:release` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; MCP equivalent: `flywheel_release_stage_lease`): Release a node stage lease.
+- `flywheel nodes:commit` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; MCP equivalent: `flywheel_commit_node`): Commit staged changes to an existing node under an active stage lease (`--stage_session_id`, `--base_committed_revision`, `--staged_payload` required).
+- `flywheel nodes:branch` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; MCP equivalent: `flywheel_branch_node`): Create a child branch from a node (`--expected_revision` required).
+- `flywheel nodes:merge` (mutating; scopes: `write`; HTTP: `POST /nodes/merge`; MCP equivalent: `flywheel_merge_nodes`): Merge multiple nodes into one resolved node.
+- `flywheel nodes:add-parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/add`; MCP equivalent: `flywheel_add_parent`): Add a parent-child edge.
+- `flywheel nodes:remove-parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/remove`; MCP equivalent: `flywheel_remove_parent`): Remove a parent-child edge.
+- `flywheel nodes:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}`; MCP equivalent: `flywheel_delete_node`): Delete a node by identifier. Modes: `cascade` (delete subtree), `detach_shared` (preserve descendants with surviving parents).
+- `flywheel nodes:delete-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/bulk-delete`; MCP equivalent: `flywheel_bulk_delete_nodes`): Delete multiple node subtrees.
+
+### Artifacts
+
+- `flywheel artifacts:upload:prepare` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/prepare`; MCP equivalent: `flywheel_prepare_artifact_uploads`): Create upload batch with signed per-item upload tickets. Upload raw file bytes to the returned URLs (no JSON metadata wrappers).
+- `flywheel artifacts:upload:finalize` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/finalize`; MCP equivalent: `flywheel_finalize_artifact_uploads`): Finalize prepared artifact uploads and attach all staged artifacts in one revision bump.
+- `flywheel artifacts:list` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_list_artifacts`): List artifacts for a node.
+- `flywheel artifacts:get` (read; scopes: `read`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_get_artifact`): Fetch one artifact metadata record.
+- `flywheel artifacts:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}/artifacts/{artifact_id}`; MCP equivalent: `flywheel_delete_artifact`): Delete an artifact from a node (optimistic locking).
+- `flywheel artifacts:note:set` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{node_id}/artifacts/{artifact_id}/note`; MCP equivalent: `flywheel_set_artifact_note`): Add, update, or clear an artifact note (optimistic locking).
+
+### Executions
+
+- `flywheel executions:launch` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions`; MCP equivalent: `flywheel_launch_execution`): Start an execution for a node.
+- `flywheel executions:list` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/executions`; MCP equivalent: `flywheel_list_executions`): List executions for a node.
+- `flywheel executions:terminate` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions/{execution_id}/terminate`; MCP equivalent: `flywheel_terminate_execution`): Stop an execution for a node.
+
+### Compute and budgets
+
+- `flywheel compute:options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; MCP equivalent: `flywheel_compute_list_options`): List allowed compute catalog options for a node. Pass the same `--compute_grant_id` you will use for acquire when using grant-backed compute.
+- `flywheel compute:funding` (read; scopes: `compute`; HTTP: `GET /compute/funding`; MCP equivalent: `flywheel_compute_funding`): Read grant-scoped funding context (`grant_cents`, `remaining_cents`, backing budget fields) before compute acquire.
+- `flywheel compute:status` (read; scopes: `compute`; HTTP: `GET /compute/status`; MCP equivalent: `flywheel_compute_status`): Return compute lease status. Lease rows include ownership flags so hosts can distinguish user-owned leases from sponsor-visible campaign leases.
+- `flywheel compute:connection` (read; scopes: `compute`; HTTP: `GET /compute/connection`; MCP equivalent: `flywheel_compute_connection`): Get SSH connection material for a usable lease (token-scoped to `lease_control_token`; only owned leases are connectable).
+- `flywheel approval-sessions:heartbeat` (read; scopes: `compute`; HTTP: `POST /approval-sessions/heartbeat`; MCP equivalents: `flywheel_approval_session_open`, `flywheel_approval_session_heartbeat`): Create or refresh a compute approval session for the current host context.
+- `flywheel approval-sessions:list` (read; scopes: `compute`; HTTP: `GET /approval-sessions`; MCP equivalent: `flywheel_list_approval_sessions`): List approval sessions visible to the current user.
+- `flywheel approval-sessions:expire` (mutating; scopes: `compute`; HTTP: `POST /approval-sessions/expire`; MCP equivalent: `flywheel_expire_approval_session`): Expire the current compute-grant approval session context without releasing active leases.
+- `flywheel compute-grants:request-approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_request_compute_grant_approval`): Request compute-grant approval; branch on response status (`already_approved`, `approval_required`, `insufficient_credits`).
+- `flywheel compute-grants:list` (read; scopes: `compute`; HTTP: `GET /compute/grants`; MCP equivalent: `flywheel_list_compute_grants`): List active/exhausted compute grants available to the user. Restrict by `--approval_session_id` to inspect session-bound grants.
+- `flywheel campaign-budgets:list` (read; scopes: `compute`; HTTP: `GET /nodes/{root_node_id}/campaign-budgets`; MCP equivalent: `flywheel_list_campaign_budgets`): List campaign compute budgets for a root. Organizer-only management view.
+- `flywheel campaign-budgets:create` (mutating; scopes: `compute`; HTTP: `POST /nodes/{root_node_id}/campaign-budgets`; MCP equivalent: `flywheel_create_campaign_budget`): Create a campaign compute budget grant.
+- `flywheel campaign-budgets:update` (mutating; scopes: `compute`; HTTP: `PATCH /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; MCP equivalent: `flywheel_update_campaign_budget`): Update a campaign budget (partial; any `--key=value` becomes a field).
+- `flywheel campaign-budgets:revoke` (mutating; scopes: `compute`; HTTP: `DELETE /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; MCP equivalent: `flywheel_revoke_campaign_budget`): Revoke a campaign budget grant.
+- `flywheel compute:acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_compute_acquire`): Acquire managed compute for a node. Set `--requested_sku` to the exact `offer_id` returned by `flywheel compute:options` (`options[].offer_id`), including provider prefixes (e.g., `nebius::...`); do not pass display names or partial IDs. Returns lease state only; poll `flywheel compute:status` for readiness.
+- `flywheel compute:release` (mutating; scopes: `compute`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_compute_release`): Release one active compute lease (async; use `--wait` to block).
+- `flywheel compute:release-all` (mutating; scopes: `compute`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_compute_release_all`): Release all active leases in current `lease_control_token` scope; pass `--force` for explicit account-wide cleanup.
+
+### Contract, audit, and export
+
+- (no CLI equivalent; MCP equivalent: `flywheel_get_contract`): MCP contract introspection is MCP-only. In `--mode cli` install, treat each command's `flywheel help <command>` output as the canonical per-command contract reference.
+- (no CLI equivalent; MCP equivalent: `flywheel_get_contract_section`): Same as above.
+- `flywheel export:subgraph` (read; scopes: `read`; HTTP: `POST /export`; MCP equivalent: `flywheel_export_subgraph`): Export a subgraph snapshot.
+- `flywheel import:subgraph` (mutating; scopes: `write`; HTTP: `POST /import`; MCP equivalent: `flywheel_import_subgraph`): Import graph JSON into new node records. Pass `--normalize_cycles=true` to drop cycle/self-loop edges; default rejects cyclic payloads.
+- `flywheel nodes:render:summary` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/summary`; MCP equivalent: `flywheel_summarize_node_tree`): Render a compact summary of a node subtree.
+- `flywheel export:summary` (read; scopes: `read`; HTTP: `POST /export-summary`; MCP equivalent: `flywheel_export_summary`): Generate a markdown summary export.
+- `flywheel export:summary:stream` (read; scopes: `read`; HTTP: `POST /export-summary-stream`; MCP equivalent: `flywheel_export_summary_stream`): Stream summary generation as NDJSON events.
+- `flywheel export:summary:pdf` (read; scopes: `read`; HTTP: `POST /export-summary-pdf`; MCP equivalent: `flywheel_export_summary_pdf`): Render summary as PDF; requires `--out`.
+- `flywheel export:summary:render-pdf` (read; scopes: `read`; HTTP: `POST /export-summary-render-pdf`; MCP equivalent: `flywheel_export_summary_render_pdf`): Render caller-provided markdown as PDF; requires `--out`.
+
+## CLI-Only Tool Families
+
+These commands have no MCP counterpart. They cover auth/profile management, account administration, billing flows, integrations, and bulk file operations that the CLI exposes directly through the canonical HTTP API.
+
+### Auth and profiles
+
+- `flywheel auth:login` (mutating; scopes: `write`): Bootstrap API key auth via RFC 8628 device flow (FLY-416: replaces legacy /setup-exchange redeem).
+- `flywheel auth:keychain:set` (local): Store an API key in the OS keychain for a profile. Reads the key from stdin.
+- `flywheel auth:keychain:clear` (local): Remove an API key from the OS keychain for a profile.
+- `flywheel profile:list` (local): List configured CLI profiles.
+- `flywheel profile:show` (local): Show a profile definition.
+- `flywheel profile:set` (local): Create or update a CLI profile (never stores plaintext keys).
+- `flywheel profile:unset` (local): Delete a CLI profile.
+
+### Node helpers (CLI-only)
+
+- `flywheel nodes:create` (mutating; scopes: `write`): Create a minimal node (title only) and emit graph-change event.
+- `flywheel nodes:files` (read; scopes: `read`): List files attached to a node.
+- `flywheel nodes:sharing:summaries` (read; scopes: `read`): Read access summaries for multiple nodes in one batch.
+- `flywheel nodes:stage:backfill:hypothesis` (mutating; scopes: `write`): Derive hypothesis from staged node content.
+- `flywheel nodes:stage:backfill:insights` (mutating; scopes: `write`): Extract structured insights from staged node content.
+
+### Artifact helpers (CLI-only)
+
+- `flywheel artifacts:upload` (mutating; scopes: `write`): One-shot upload — runs prepare + raw PUT + finalize from a single invocation. Use this in scripts; the prepare/finalize split is for streaming or chunked uploads.
+
+### Compute policy and budgets (CLI-only)
+
+- `flywheel compute:policy:get` (read; scopes: `compute`): Read compute budget policy for a node.
+- `flywheel compute:policy:set` (mutating; scopes: `compute`): Update compute budget policy for a node (partial).
+- `flywheel compute:budgets` (read; scopes: `compute`): List budget grants visible for a node context.
+- `flywheel machines:list` (read; scopes: `compute`): List your managed compute leases.
+
+### Files, blobs, graph, history (CLI-only)
+
+- `flywheel blobs:get` (read; scopes: `read`): Download a raw blob by storage key.
+- `flywheel files:list` (read; scopes: `read`): List all your files across nodes.
+- `flywheel graph:get` (read; scopes: `read`): Read the graph projection for navigation and topology workflows.
+- `flywheel export:history` (read; scopes: `read`): Export node history as JSONL.
+
+### Account
+
+- `flywheel account:get` (read; scopes: `read`): View account snapshot and linked identities.
+- `flywheel account:merge:proof` (mutating; scopes: `write`): Mint a merge proof token from a source session token.
+- `flywheel account:merge:preview` (read; scopes: `read`): Preview what an account merge will do.
+- `flywheel account:merge` (mutating; scopes: `write`): Execute an account merge. Requires `--confirm=MERGE`.
+- `flywheel account:detach` (mutating; scopes: `write`): Detach a linked alias account. Requires `--confirm=DETACH`.
+- `flywheel account:emails:add` (mutating; scopes: `write`): Add an email alias to your account.
+- `flywheel account:emails:remove` (mutating; scopes: `write`): Remove an email alias from your account.
+- `flywheel account:emails:set-primary` (mutating; scopes: `write`): Set your primary email address.
+
+### Credits and billing
+
+- `flywheel credits:transactions` (read; scopes: `read`): View paginated credit transactions.
+- `flywheel credits:usage` (read; scopes: `read`): Feature-based usage breakdown over a window.
+- `flywheel credits:purchase` (mutating; scopes: `write`): Create a Stripe checkout session for a one-time purchase.
+- `flywheel credits:subscribe` (mutating; scopes: `write`): Create a Stripe checkout session for a subscription.
+- `flywheel credits:billing-portal` (mutating; scopes: `write`): Open the Stripe billing portal for the current user.
+- `flywheel credits:subscription` (read; scopes: `read`): View your subscription status.
+- `flywheel credits:referral` (read; scopes: `read`): View your referral code and status.
+- `flywheel credits:referral:claim` (mutating; scopes: `write`): Claim referral rewards using a code.
+
+### Integrations
+
+- `flywheel github:status` (read; scopes: `read`): Check GitHub connection status.
+- `flywheel github:link` (mutating; scopes: `write`): Link a GitHub installation ID to your account.
+- `flywheel github:refresh-repos` (mutating; scopes: `write`): Refresh the list of accessible repositories.
+- `flywheel github:disconnect` (mutating; scopes: `write`): Disconnect GitHub from your account.
+- `flywheel integrations:status` (read; scopes: `read`): Check integration connection status (W&B, Hugging Face).
+- `flywheel integrations:wandb:set` (mutating; scopes: `write`): Store a Weights & Biases API key.
+- `flywheel integrations:wandb:remove` (mutating; scopes: `write`): Remove your W&B credential.
+- `flywheel integrations:huggingface:set` (mutating; scopes: `write`): Store a Hugging Face access token.
+- `flywheel integrations:huggingface:remove` (mutating; scopes: `write`): Remove your Hugging Face credential.
+
+### API keys
+
+- `flywheel api-keys:list` (read; scopes: `read`): List your API keys.
+- `flywheel api-keys:create` (mutating; scopes: `write`): Create a new API key and return the raw material once.
+- `flywheel api-keys:delete` (mutating; scopes: `write`): Delete an API key (refuses to delete the active one unless `--allow-self`).
+- `flywheel api-keys:rotate` (mutating; scopes: `write`): Rotate an API key (refuses to rotate the active one unless `--allow-self`).
+<!-- FLY-416: removed — device flow replaces legacy /setup-exchange. -->
+<!-- - `flywheel api-keys:setup-exchange:create` (mutating; scopes: `write`): Start browser-assisted setup exchange. -->
+<!-- - `flywheel api-keys:setup-exchange:redeem` (mutating; scopes: `write`): Redeem a setup exchange token into a raw API key. -->
+
+## Practical Command Sequences
+
+### List Owned Nodes
+
+1. `flywheel nodes:list --owners=me --projection=core`.
+
+### Safe Node Update
+
+1. `flywheel nodes:get --node_id=<id>`: Read latest node state and capture `revision`.
+2. `flywheel nodes:stage:lease:acquire --node_id=<id> --expected_revision=<rev>`: Acquire a session-scoped stage lease.
+3. `flywheel nodes:commit --node_id=<id> --stage_session_id=<sid> --base_committed_revision=<rev> --staged_payload=@payload.json`: Commit once terminal and contract-complete.
+
+### Empirical Workflow
+
+1. `flywheel nodes:commit-new --payload_json=@new-node.json`: Commit a local staged new node to canonical storage as the first persistence boundary.
+2. `flywheel compute-grants:request-approval --acquire_node_id=<id> --budget_source=user`: Request budget approval. Branch on response `status` (`already_approved` | `approval_required` | `insufficient_credits`).
+3. If `approval_required`: present `approval_url` to the user, then `flywheel compute-grants:list --status=active --approval_session_id=<sid>` to fetch the active grant.
+4. `flywheel compute:options --node_id=<id> --compute_grant_id=<gid>`: List allowed offers; pick the exact `offer_id`.
+5. `flywheel compute:acquire --node_id=<id> --compute_grant_id=<gid> --requested_sku=<offer_id> --approval_session_id=<sid>`: Acquire lease.
+6. `flywheel compute:status --lease_control_token=<tok>`: Poll until the lease is ready.
+7. `flywheel executions:launch --node_id=<id>`: Launch execution.
+8. `flywheel executions:list --node_id=<id>`: Poll until execution reaches terminal status.
+9. `flywheel artifacts:upload --node_id=<id> --file=results.json`: One-shot upload (or use the prepare/finalize split for streaming).
+10. `flywheel nodes:commit --node_id=<id> ...`: Commit terminal empirical node.
+
+## Runtime Guidance
+
+- `flywheel nodes:resolve-slug` resolves human-facing slug references. If response status is `ambiguous`, ask the user to confirm the intended `node_id` before mutating anything.
+- `flywheel nodes:get` reads the current node state before writes; capture `revision` for optimistic-locking writes.
+- `flywheel nodes:stage:lease:acquire`, `flywheel nodes:stage:lease:heartbeat`, `flywheel nodes:stage:lease:release` coordinate session-scoped local staged edits for an existing node before commit.
+- `flywheel campaign:snapshot` reads the current derived campaign state for a node's root campaign instead of inferring standings from freeform text.
+- `flywheel nodes:sharing:get` verifies sharing state after sharing writes before reporting private/shared/public state.
+- `flywheel tags:assign` accepts `--tag_ids` as a JSON array of strings; omitting `--tag_ids` clears all assignments.
+- `flywheel nodes:list` accepts canonical filters as repeated flags or comma-separated lists for `--owners`, `--writers`, `--visibility`.
+- `flywheel compute:status` checks first when work may need managed compute (GPU), using the active `--lease_control_token` from prior acquire (or pass it explicitly).
+- `flywheel compute-grants:list` lists active compute grants and selects one `--compute_grant_id` for acquisition.
+- `flywheel compute-grants:request-approval` requests/confirms budget before acquire and chooses a budget source (`user` or `root`); branch on status (`already_approved`, `approval_required`, `insufficient_credits`).
+- `flywheel compute:connection` reads SSH connection material for the active user lease once status indicates the lease is usable, scoped by `--lease_control_token`.
+- `flywheel compute:options` is used when a lease is needed and no suitable active lease exists; copy the exact provider-qualified `offer_id` (`provider::offer_id`) and `region` from `options[].offer_id` verbatim. Catalog-only read; excludes grant/budget money fields.
+- `flywheel compute:funding` reads grant-scoped funding context (`grant_cents`, `remaining_cents`, backing budget fields) for the selected `--compute_grant_id` before acquire.
+- `flywheel compute:acquire` provisions compute once requirements are clear. Requires a valid `--compute_grant_id`; set `--requested_sku` to the exact selected `options[].offer_id`; returns lease/provisioning state only (not SSH key material). Capture `compute.lease_control_token` from the response for follow-up lease control commands.
+- `flywheel compute:release` releases compute when no longer needed, scoped by `--lease_control_token`. Use `--wait` to block until release completes.
+- `flywheel executions:launch`, `flywheel executions:list`, `flywheel executions:terminate` manage execution status transitions.
+- `flywheel artifacts:upload:prepare` prepares one or more signed raw-file upload requests for concrete deliverables/evidence produced by the work. `flywheel artifacts:upload` is the one-shot convenience wrapper for typical scripts.
+- `flywheel artifacts:upload:finalize` finalizes a staged artifact batch and appends all uploaded artifacts in one revision bump.
+- `flywheel artifacts:delete` removes an accidental/obsolete node artifact.
+- `flywheel artifacts:list`, `flywheel artifacts:get` inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
+- `flywheel nodes:commit-new`, `flywheel nodes:commit` publish the caller's full staged payload for an existing node once terminal and contract-complete; commit on an existing node requires an active stage lease and explicit `--base_committed_revision`.
+
+## See Also
+
+- `flywheel-mcp-tool-map.md` — the matching MCP routing reference.
+- `flywheel help <command>` — canonical per-command flags, types, defaults, examples, and related commands.
+- `flywheel --format json|tsv|csv|table` — output format selector for scripting workflows.

package/skills/flywheel-to-graph/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,85 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - `flywheel_auth_status` (read; scopes: `read`; HTTP: `GET /auth/status`; core surface): Return Flywheel auth status for the current access token.
 - `flywheel_get_credits_balance` (read; scopes: `read`; HTTP: `GET /credits`; core surface): Return current user credits balance and lifetime counters.
-- `flywheel_updates_list` (read; scopes: `read`; HTTP: `GET /mcp/updates`; core surface): List in-app updates/announcements for the signed-in user.
-- `flywheel_updates_hide` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/{announcement_id}/hide`; core surface): Mark one update as hidden for the current user (Don't show again).
-- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/hide-all-active`; core surface): Hide all active updates for the current user (Don't show all active again).
-- `flywheel_updates_unhide` (mutating; scopes: `write`; HTTP: `DELETE /mcp/updates/{announcement_id}/hide`; core surface): Restore one hidden update for the current user.
-- `flywheel_list_nodes` (read; scopes: `read`; HTTP: `GET /mcp/nodes`; full-surface only): List nodes with optional owners/writers/visibility filters and projection control (`core`, `topology`, `full`).
-- `flywheel_resolve_node_slug` (read; scopes: `read`; HTTP: `GET /mcp/nodes/resolve-by-slug`; core surface): Resolve a node by slug_name with explicit conflict handling (`unique`, `context_resolved`, `ambiguous`, `not_found`).
-- `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/sharing`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
-- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/sharing`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
-- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/sharing/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
-- `flywheel_get_node` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}`; core surface): Get one node by node_id.
-- `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node.
-- `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
-- `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.
-- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/tags`; full-surface only): Set graph tag assignments for one node.
-- `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
-- `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
-- `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
-- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
+- `flywheel_updates_list` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): List in-app updates/announcements for the signed-in user.
+- `flywheel_updates_hide` (mutating; scopes: `write`; HTTP: `POST /updates/{announcement_id}/hide`; core surface): Mark one update as hidden for the current user (Don't show again).
+- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; HTTP: `POST /updates/hide-all-active`; core surface): Hide all active updates for the current user (Don't show all active again).
+- `flywheel_updates_unhide` (mutating; scopes: `write`; HTTP: `DELETE /updates/{announcement_id}/hide`; core surface): Restore one hidden update for the current user.
+- `flywheel_list_nodes` (read; scopes: `read`; HTTP: `GET /nodes`; full-surface only): List nodes with optional owners/writers/visibility filters and projection control (`core`, `topology`, `full`).
+- `flywheel_resolve_node_slug` (read; scopes: `read`; HTTP: `GET /nodes/resolve-by-slug`; core surface): Resolve a node by slug_name with explicit conflict handling (`unique`, `context_resolved`, `ambiguous`, `not_found`).
+- `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `tool-mediated`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
+- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `tool-mediated`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
+- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/access-policy/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one node by node_id.
+- `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node. `track_history` is effective only when `one_only=true`; when `one_only=false`, the effective track_history=false.
+- `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
+- `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.
+- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; HTTP: `PUT /nodes/{node_id}/tags`; full-surface only): Set graph tag assignments for one node (`tag_ids` must be a JSON array of strings; omit `tag_ids` to clear all assignments to `[]`).
+- `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
+- `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
+- `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
+- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
 
 ### Node stage and commit
 
-- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
-- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
-- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
-- `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
-- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
-- `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/branch`; full-surface only): Create a child branch node.
-- `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
-- `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
-- `flywheel_remove_parent` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/parents/remove`; full-surface only): Detach one parent edge from a node without deleting the node.
-- `flywheel_delete_node` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}`; full-surface only): Delete a node subtree.
-- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/bulk-delete`; full-surface only): Delete multiple node subtrees in one operation.
+- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
+- `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; full-surface only): Create a child branch node with optimistic locking (`expected_revision` required).
+- `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
+- `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
+- `flywheel_remove_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/remove`; full-surface only): Detach one parent edge from a node without deleting the node.
+- `flywheel_delete_node` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}`; full-surface only): Delete a node and its descendants. Modes: `cascade` (delete full subtree), `detach_shared` (preserve descendants with surviving parents).
+- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/bulk-delete`; full-surface only): Delete multiple node subtrees in one operation.
 
 ### Artifacts
 
-- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`; core surface): Prepare one or more raw-file artifact uploads (returns batch token + signed upload URLs). Upload must send raw file bytes to the returned URLs (do not upload JSON metadata wrappers).
-- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`; core surface): Finalize a prepared artifact upload batch and append all staged artifacts to the node in one revision bump.
-- `flywheel_list_artifacts` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts`; core surface): List node artifacts.
-- `flywheel_get_artifact` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Get one artifact by id.
-- `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
-- `flywheel_set_artifact_note` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{node_id}/artifacts/{artifact_id}/note`; core surface): Set or clear one artifact note with optimistic locking.
+- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/prepare`; core surface): Prepare one or more raw-file artifact uploads (returns batch token + signed upload URLs). Upload must send raw file bytes to the returned URLs (do not upload JSON metadata wrappers).
+- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/finalize`; core surface): Finalize a prepared artifact upload batch and append all staged artifacts to the node in one revision bump.
+- `flywheel_list_artifacts` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): List node artifacts.
+- `flywheel_get_artifact` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one artifact by id.
+- `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
+- `flywheel_set_artifact_note` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{node_id}/artifacts/{artifact_id}/note`; core surface): Set or clear one artifact note with optimistic locking.
 
 ### Executions
 
-- `flywheel_launch_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions`; core surface): Launch node execution.
-- `flywheel_list_executions` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/executions`; core surface): List node executions.
-- `flywheel_terminate_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate`; core surface): Terminate a node execution.
+- `flywheel_launch_execution` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions`; core surface): Launch node execution.
+- `flywheel_list_executions` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/executions`; core surface): List node executions.
+- `flywheel_terminate_execution` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions/{execution_id}/terminate`; core surface): Terminate a node execution.
 
 ### Compute and budgets
 
-- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /mcp/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 +129,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.
@@ -134,13 +145,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-tree/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: flywheel-tree
+description: Render Flywheel DAGs as terminal tree views.
+---
+
+# Flywheel Tree
+
+## When To Use
+
+Use this skill when the user wants a Flywheel graph shown in classical CLI tree format from a node id or slug.
+Use it to inspect structure, compare branch topology, or audit parent-child relationships in read-only mode.
+Always print the descendant subgraph rooted at the user-provided node; print the full DAG only when that provided node is the actual DAG root.
+This skill uses one local wrapper command (selector -> MCP resolve/get_node_tree -> in-process render) to keep output deterministic and latency low.
+
+## Modes
+
+This skill supports both Flywheel install modes, with an MCP-first execution path:
+
+- **`--mode mcp` install**: preferred for this skill because `scripts/render_tree_via_mcp.py` resolves and calls MCP directly.
+- **`--mode cli` install**: `setup --mode cli` configures runtime credentials for CLI routing; prerequisite for bare-binary routing is `npm install -g @paradigma-inc/flywheel`. This skill's wrapper still reads through MCP, so keep MCP wiring available for the host that runs the script.
+
+When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+
+## Input Contract
+
+Accept any of these as the root selector:
+
+- Node id (UUID-like string)
+- Slug name (for example `quiet-snow-3839`)
+- Natural-language root reference in the user message (for example "DAG whose root is quiet-snow-3839")
+
+If no node id or slug is explicitly provided:
+
+- Infer the root from user wording.
+- If inference is not possible, ask one concise question requesting the root id or slug.
+
+## Workflow
+
+1. Follow [workflow.md](references/workflow.md) end-to-end.
+2. Use `scripts/render_tree_via_mcp.py` as the only execution path:
+   - The script resolves slug selectors via `flywheel_resolve_node_slug` when needed.
+   - The script fetches topology via `flywheel_get_node_tree`.
+   - The script renders in-process with `render_tree.py`.
+   - Run it via `uv run --quiet --with mcp python ...` so the skill does not depend on any repository layout and keeps stdout clean.
+   - The script auto-discovers MCP config from `--codex-config`/`--mcp-config`, `CODEX_CONFIG`, `CODEX_HOME/config.toml`, nearest project `.codex/config.toml`, `~/.codex/config.toml`, nearest project `.mcp.json`, then `~/.claude.json`, and tries candidates until one resolves the requested alias.
+   - Default MCP alias is `flywheel`; when missing, the script auto-resolves a compatible `flywheel*` alias.
+   - Do not pipe full tree JSON through shell here-strings.
+   - Do not write temporary JSON files.
+3. Preserve renderer output formatting exactly:
+   - In chat responses, wrap renderer stdout in a fenced `text` code block.
+   - Do not alter indentation or rewrite line prefixes.
+4. Keep visual conventions produced by the renderer:
+   - Node label: `name [kind] | slugname` when slug exists.
+   - Omit `| slugname` entirely when slug is missing.
+   - `[insight]` is pastel red, `[empirical]` is pastel yellow, `[untyped]` is gray.
+   - `slugname` is always gray.
+
+## Result Contract
+
+- Do not edit the graph.
+- Use read-only analysis only.
+- Do not mutate nodes, tags, artifacts, parents, sharing, or executions.
+- If data retrieval or script execution fails, report the failure reason and stop.
+
+## Resources
+
+- `scripts/render_tree.py`: deterministic tree renderer for raw `flywheel_get_node_tree` JSON.
+- `scripts/render_tree_via_mcp.py`: one-command MCP wrapper (resolve selector -> get tree -> render).
+- `references/workflow.md`: full operational workflow and invocation commands.
+- `assets/ansi_palette.json`: color palette used by the renderer.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Flywheel Tree"
+  short_description: "Render Flywheel DAGs as terminal tree views with low-latency MCP wrapper"
+  default_prompt: "Resolve a Flywheel node id or slug, then run scripts/render_tree_via_mcp.py once using auto-discovered MCP config/alias (Codex or Claude) (selector -> MCP resolve/get_node_tree -> in-process render) and return stdout exactly."

package/skills/flywheel-tree/assets/ansi_palette.json

@@ -0,0 +1,29 @@
+{
+  "colors": [
+    "\u001b[38;5;224m",
+    "\u001b[38;5;217m",
+    "\u001b[38;5;210m",
+    "\u001b[38;5;223m",
+    "\u001b[38;5;216m",
+    "\u001b[38;5;209m",
+    "\u001b[38;5;230m",
+    "\u001b[38;5;229m",
+    "\u001b[38;5;228m",
+    "\u001b[38;5;157m",
+    "\u001b[38;5;150m",
+    "\u001b[38;5;114m",
+    "\u001b[38;5;159m",
+    "\u001b[38;5;116m",
+    "\u001b[38;5;73m",
+    "\u001b[38;5;153m",
+    "\u001b[38;5;111m",
+    "\u001b[38;5;75m",
+    "\u001b[38;5;183m",
+    "\u001b[38;5;147m",
+    "\u001b[38;5;141m",
+    "\u001b[38;5;225m",
+    "\u001b[38;5;218m",
+    "\u001b[38;5;211m"
+  ],
+  "reset": "\u001b[0m"
+}