@paradigma-inc/flywheel 0.1.35 → 0.1.52

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.

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

@@ -73,6 +73,30 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
 - `flywheel_set_artifact_note` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{node_id}/artifacts/{artifact_id}/note`; core surface): Set or clear one artifact note with optimistic locking.
 
+### Hooks
+
+- `flywheel_create_hook` (mutating; scopes: `write`; HTTP: `POST /nodes/{owner_node_id}/hooks`; core surface): Create a durable hook definition on the owner node.
+- `flywheel_update_hook` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{owner_node_id}/hooks/{hook_id}`; core surface): Update an existing hook definition.
+- `flywheel_set_hook_enabled` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{owner_node_id}/hooks/{hook_id}/enabled`; core surface): Enable/disable a hook without deleting it.
+- `flywheel_delete_hook` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{owner_node_id}/hooks/{hook_id}`; core surface): Delete a hook definition.
+- `flywheel_list_hooks` (read; scopes: `read`; HTTP: `GET /nodes/{owner_node_id}/hooks`; core surface): List hooks configured on the owner node.
+- `flywheel_create_hook_secret` (mutating; scopes: `write`; HTTP: `POST /nodes/{owner_node_id}/hook-secrets`; core surface): Create a hook secret (plaintext is write-only).
+- `flywheel_update_hook_secret` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{owner_node_id}/hook-secrets/{secret_id}`; core surface): Update hook secret metadata/value.
+- `flywheel_delete_hook_secret` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{owner_node_id}/hook-secrets/{secret_id}`; core surface): Delete a hook secret.
+- `flywheel_list_hook_secrets` (read; scopes: `write`; HTTP: `GET /nodes/{owner_node_id}/hook-secrets`; core surface): List hook secret metadata (no plaintext values).
+- `flywheel_list_hook_runs` (read; scopes: `read`; HTTP: `GET /nodes/{owner_node_id}/hook-runs`; core surface): List async hook execution runs for observability.
+
+Hook workflow-if contract (first version):
+
+- Author matching filters with `workflow_yaml.if` on `flywheel_create_hook` / `flywheel_update_hook`.
+- Read/list surfaces return canonical `workflow` plus normalized `workflow_yaml`.
+- Workflow-if operators: `all`, `any`, `not`, `event`, `any_artifact`; predicate operators: `eq`, `in`, `exists`.
+- Canonical none-artifact expression: `not: { any_artifact: ... }`.
+- Run cardinality is fixed at one run per `(hook_id, event_id)` (no artifact fanout).
+- Submission-only matching is typically `any_artifact.field=metadata.role` with `eq: submission`.
+- Workflow step types include `flywheel/http_request@v1`, `flywheel/http_poll@v1`, `flywheel/json_extract@v1`, `flywheel/load_artifact@v1`, and `flywheel/upsert_artifact@v1`.
+- `flywheel/upsert_artifact@v1` selectors are authored under `with.match`; `match.metadata` is subset matching and ambiguous selectors fail terminally.
+
 ### Executions
 
 - `flywheel_launch_execution` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions`; core surface): Launch node execution.
@@ -85,7 +109,8 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `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_heartbeat` (read; scopes: `compute`; HTTP: `POST /approval-sessions/heartbeat`; core surface): Create or refresh a compute-grant approval session for the current MCP host session.
+- `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.
@@ -94,7 +119,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `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.
+- `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.
 
@@ -128,7 +153,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 2. `flywheel_commit_node`: Commit staged empirical fields with `stage_session_id`, `base_committed_revision`, and a full `staged_payload` once the working state is ready to publish.
 3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval context first. Branch on response status.
 4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`).. if `already_approved` then `reuse_compute_grant_id`: Use returned `compute_grant_id` directly for flywheel_compute_acquire.. if `approval_required` then `present_approval_url_to_user`: Present `approval_url` to the user; the user opens it and confirms budget approval.; `flywheel_list_compute_grants`: After approval, list active grants for the current `approval_session_id` and use the returned `compute_grant_id` for acquire.. if `insufficient_credits` then `request_user_credit_top_up`: No `approval_url` is returned. Ask the user to add credits, then retry flywheel_request_compute_grant_approval.
-5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id` from approval response.
+5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id` from approval response and set `requested_sku` to the exact selected `options[].offer_id`.
 6. `flywheel_compute_status`: Poll until the active lease is ready; follow `recommended_next_action`.
 7. `flywheel_launch_execution`: Launch execution once compute and inputs are ready.
 8. `flywheel_list_executions`: Poll until execution reaches terminal status.
@@ -137,6 +162,15 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit, or set `no_artifacts_reason` when intentionally artifact-free.
 12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
 
+### Hook Automation Workflow
+
+1. `flywheel_create_hook_secret`: Create endpoint credentials if the action needs auth.
+2. `flywheel_create_hook`: Define trigger + scope + `workflow_yaml` (`if` + `jobs.main.steps`).
+3. `flywheel_set_hook_enabled`: Enable hook once configuration is complete.
+4. `flywheel_list_hooks`: Confirm the hook is enabled and scoped correctly.
+5. `flywheel_finalize_artifact_uploads`: Emit `artifact.finalized` on successful finalize writes.
+6. `flywheel_list_hook_runs`: Inspect run outcomes (`queued`, `running`, `succeeded`, `failed`).
+
 ## Runtime Guidance
 
 - `flywheel_resolve_node_slug`: resolve human-facing slug references. If response status is `ambiguous`, ask the user to confirm the intended node_id before mutating anything.
@@ -150,9 +184,9 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_list_compute_grants`: list active compute grants (funded by user/root budgets) and select one `compute_grant_id` for acquisition.
 - `flywheel_request_compute_grant_approval`: request/confirm budget before acquire and choose a budget source (`user` or `root`); branch on status (`already_approved`, `approval_required`, `insufficient_credits`).
 - `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable, scoped by lease_control_token.
-- `flywheel_compute_list_options`: use when a lease is needed and no suitable active lease exists, then select explicit provider-qualified `offer_id` (`provider::offer_id`) and `region`. This is a catalog-only read and excludes grant/budget money fields.
+- `flywheel_compute_list_options`: use when a lease is needed and no suitable active lease exists, then select the exact provider-qualified `offer_id` from `options[].offer_id` (`provider::offer_id`) and `region`. Copy `offer_id` verbatim; do not strip prefixes or substitute display names. This is a catalog-only read and excludes grant/budget money fields.
 - `flywheel_compute_funding`: read grant-scoped funding context (`grant_cents`, `remaining_cents`, backing budget fields) for the selected `compute_grant_id` before acquire.
-- `flywheel_compute_acquire`: provision compute once requirements are clear. This requires a valid `compute_grant_id` and returns lease/provisioning state only (not SSH key material). Capture `compute.lease_control_token` from the response for follow-up lease control tools.
+- `flywheel_compute_acquire`: provision compute once requirements are clear. This requires a valid `compute_grant_id`; set `requested_sku` to the exact selected `options[].offer_id`; and returns lease/provisioning state only (not SSH key material). Capture `compute.lease_control_token` from the response for follow-up lease control tools.
 - `flywheel_compute_release`: release compute when no longer needed, scoped by lease_control_token.
 - `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution status transitions.
 - `flywheel_prepare_artifact_uploads`: prepare one or more signed raw-file upload requests for concrete deliverables/evidence produced by the work.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/skills/flywheel-auto/SKILL.md

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

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

@@ -85,6 +85,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `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`)
@@ -170,6 +171,7 @@ Canonical reference for Flywheel MCP public interfaces and contract pointers.
 - `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`