@paradigma-inc/flywheel 0.1.26 → 0.1.51

package/skills/flywheel/references/INTERFACES.md

@@ -0,0 +1,208 @@
+# Interfaces
+
+Canonical reference for Flywheel MCP public interfaces and contract pointers.
+
+## Canonical Contract References
+
+- `flywheel_get_contract` is the top-level contract entry point.
+- `flywheel_get_contract_section(section_id)` returns section-scoped payloads.
+- Section order:
+- `quickstart` (Quickstart): Recommended first calls and section read order for onboarding.
+- `graph` (Graph): Node model, graph topology guidance, and durable behavior rules.
+- `stage_commit` (Stage and commit): Stage/commit operations, commit-time validation requirements, and reproducibility guidance.
+- `sharing` (Sharing): Sharing modes, derived visibility, collaborator roles, and query translation.
+- `artifacts` (Artifacts): Prepare/upload/finalize requirements and artifact type rules.
+- `compute` (Compute): Lease ownership, token-scoped control, approval session, and budget source semantics.
+- `compute/troubleshooting_v1` (Compute Troubleshooting v1): Provider-specific acquire/retry hints for launch kwargs and request tuning.
+- `campaign` (Campaign Contract): Campaign projection and budget contracts plus template section pointers.
+
+## Canonical Entity Model
+
+- Canonical durable entity: `node`.
+- Node kind values: `untyped`, `empirical`, `insight`.
+- Node references: `node_id`, `slug_name`.
+- `slug_name` format: `adjective-noun-####` (immutable when present).
+- Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
+- Campaign projections are derived from root config and attempt submission JSON artifacts.
+
+## MCP Tool Surface
+
+### Discovery and sharing
+
+- `flywheel_auth_status` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_credits_balance` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_updates_list` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_updates_hide` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_updates_unhide` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_list_nodes` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_resolve_node_slug` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_sharing` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_get_node_tree` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_get_node_ancestry` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_get_campaign_snapshot` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_list_audit` (read; scopes: `read`; full-surface only; binding: `operation`)
+
+### Node stage and commit
+
+- `flywheel_commit_new_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_release_stage_lease` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_commit_node` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_branch_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_merge_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_add_parent` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_remove_parent` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_delete_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+
+### Artifacts
+
+- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; core surface; binding: `binding_helper`)
+- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; core surface; binding: `binding_helper`)
+- `flywheel_list_artifacts` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_artifact` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_delete_artifact` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_set_artifact_note` (mutating; scopes: `write`; core surface; binding: `operation`)
+
+### Executions
+
+- `flywheel_launch_execution` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_list_executions` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_terminate_execution` (mutating; scopes: `write`; core surface; binding: `operation`)
+
+### Compute and budgets
+
+- `flywheel_compute_list_options` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_funding` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_status` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_connection` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_approval_session_open` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_approval_session_heartbeat` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_approval_sessions` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_compute_grants` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_campaign_budgets` (read; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_create_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_update_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_revoke_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_release` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; core surface; binding: `operation`)
+
+### Contract, audit, and export
+
+- `flywheel_get_contract` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_contract_section` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_export_subgraph` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_import_subgraph` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_summarize_node_tree` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_stream` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_pdf` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_render_pdf` (read; scopes: `read`; full-surface only; binding: `operation`)
+
+## HTTP Surface
+
+### Discovery and sharing
+
+- `GET /auth/status` -> `flywheel_auth_status`
+- `GET /credits` -> `flywheel_get_credits_balance`
+- `tool-mediated` -> `flywheel_updates_list`
+- `POST /updates/{announcement_id}/hide` -> `flywheel_updates_hide`
+- `POST /updates/hide-all-active` -> `flywheel_updates_hide_all_active`
+- `DELETE /updates/{announcement_id}/hide` -> `flywheel_updates_unhide`
+- `GET /nodes` -> `flywheel_list_nodes`
+- `GET /nodes/resolve-by-slug` -> `flywheel_resolve_node_slug`
+- `tool-mediated` -> `flywheel_get_node_sharing`
+- `tool-mediated` -> `flywheel_set_sharing_for_node`
+- `POST /nodes/access-policy/bulk` -> `flywheel_set_sharing_for_nodes`
+- `tool-mediated` -> `flywheel_get_node`
+- `POST /nodes/{root_node_id}/tags` -> `flywheel_create_node_tag`
+- `PATCH /nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_update_node_tag`
+- `DELETE /nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_delete_node_tag`
+- `PUT /nodes/{node_id}/tags` -> `flywheel_set_node_tag_assignments`
+- `GET /nodes/{node_id}/tree` -> `flywheel_get_node_tree`
+- `GET /nodes/{node_id}/ancestry` -> `flywheel_get_node_ancestry`
+- `GET /nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
+- `GET /nodes/{node_id}/audit` -> `flywheel_list_audit`
+
+### Node stage and commit
+
+- `POST /nodes/commit-new` -> `flywheel_commit_new_node`
+- `POST /nodes/{node_id}/stage/lease/acquire` -> `flywheel_acquire_stage_lease`
+- `POST /nodes/{node_id}/stage/lease/heartbeat` -> `flywheel_heartbeat_stage_lease`
+- `POST /nodes/{node_id}/stage/lease/release` -> `flywheel_release_stage_lease`
+- `POST /nodes/{node_id}/commit` -> `flywheel_commit_node`
+- `POST /nodes/{node_id}/branch` -> `flywheel_branch_node`
+- `POST /nodes/merge` -> `flywheel_merge_nodes`
+- `POST /nodes/{node_id}/parents/add` -> `flywheel_add_parent`
+- `POST /nodes/{node_id}/parents/remove` -> `flywheel_remove_parent`
+- `DELETE /nodes/{node_id}` -> `flywheel_delete_node`
+- `POST /nodes/bulk-delete` -> `flywheel_bulk_delete_nodes`
+
+### Artifacts
+
+- `POST /nodes/{node_id}/artifacts/uploads/prepare` -> `flywheel_prepare_artifact_uploads`
+- `POST /nodes/{node_id}/artifacts/uploads/finalize` -> `flywheel_finalize_artifact_uploads`
+- `tool-mediated` -> `flywheel_list_artifacts`
+- `tool-mediated` -> `flywheel_get_artifact`
+- `DELETE /nodes/{node_id}/artifacts/{artifact_id}` -> `flywheel_delete_artifact`
+- `PATCH /nodes/{node_id}/artifacts/{artifact_id}/note` -> `flywheel_set_artifact_note`
+
+### Executions
+
+- `POST /nodes/{node_id}/executions` -> `flywheel_launch_execution`
+- `GET /nodes/{node_id}/executions` -> `flywheel_list_executions`
+- `POST /nodes/{node_id}/executions/{execution_id}/terminate` -> `flywheel_terminate_execution`
+
+### Compute and budgets
+
+- `GET /compute/catalog` -> `flywheel_compute_list_options`
+- `GET /compute/funding` -> `flywheel_compute_funding`
+- `GET /compute/status` -> `flywheel_compute_status`
+- `GET /compute/connection` -> `flywheel_compute_connection`
+- `tool-mediated` -> `flywheel_approval_session_open`
+- `POST /approval-sessions/heartbeat` -> `flywheel_approval_session_heartbeat`
+- `GET /approval-sessions` -> `flywheel_list_approval_sessions`
+- `POST /approval-sessions/expire` -> `flywheel_expire_approval_session`
+- `tool-mediated` -> `flywheel_request_compute_grant_approval`
+- `GET /compute/grants` -> `flywheel_list_compute_grants`
+- `GET /nodes/{root_node_id}/campaign-budgets` -> `flywheel_list_campaign_budgets`
+- `POST /nodes/{root_node_id}/campaign-budgets` -> `flywheel_create_campaign_budget`
+- `PATCH /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_update_campaign_budget`
+- `DELETE /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_revoke_campaign_budget`
+- `tool-mediated` -> `flywheel_compute_acquire`
+- `tool-mediated` -> `flywheel_compute_release`
+- `tool-mediated` -> `flywheel_compute_release_all`
+
+### Contract, audit, and export
+
+- `GET /mcp/contract` -> `flywheel_get_contract`
+- `GET /mcp/contract/sections/{section_id}` -> `flywheel_get_contract_section`
+- `POST /export` -> `flywheel_export_subgraph`
+- `POST /import` -> `flywheel_import_subgraph`
+- `GET /nodes/{node_id}/summary` -> `flywheel_summarize_node_tree`
+- `POST /export-summary` -> `flywheel_export_summary`
+- `POST /export-summary-stream` -> `flywheel_export_summary_stream`
+- `POST /export-summary-pdf` -> `flywheel_export_summary_pdf`
+- `POST /export-summary-render-pdf` -> `flywheel_export_summary_render_pdf`
+
+## Auth and Write Safety
+
+- Available scopes: `read`, `write`, `compute`.
+- Default grant scopes: `read`, `write`, `compute`.
+- Transport-required scopes: `read`.
+- Optimistic locking field: `expected_revision`.
+- Conflict status code: `409`.
+- Mutating HTTP calls require `Idempotency-Key`: `True`.
+- MCP tool transport manages idempotency keys for mutating calls: `True`.

package/skills/flywheel/references/experiment-design-protocol.md

@@ -128,9 +128,9 @@ Use an `insight` node to capture rationale, open questions, experiment shape, an
 
 Typical flow:
 
-1. `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update`
-3. `mcp__flywheel__flywheel_commit_node`
+1. `mcp__flywheel__flywheel_commit_new_node`
+2. `mcp__flywheel__flywheel_acquire_stage_lease` when refining an existing design node
+3. `mcp__flywheel__flywheel_commit_node` once the design brief is coherent
 
 ### Execution layer
 
@@ -138,8 +138,8 @@ Only after the design gate passes, create or branch the `empirical` node for the
 
 Typical flow:
 
-1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update` with the explicit run summary and the local question or hypothesis for that branch
+1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_commit_new_node`
+2. `mcp__flywheel__flywheel_acquire_stage_lease` + `mcp__flywheel__flywheel_commit_node` with the explicit run summary and the local question or hypothesis for that branch
 3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
 4. `mcp__flywheel__flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)` when you need to resolve the approved `compute_grant_id`
 5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed

package/skills/flywheel/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.