@paradigma-inc/flywheel 0.1.115 → 0.1.134

package/skills/flywheel-lookahead/references/flywheel-cli-tool-map.md

@@ -2,110 +2,112 @@
 
 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.
+The Flywheel CLI (`flywheel <command>`) is the runtime command surface shipped by `@paradigma-inc/flywheel`. It wraps the canonical Flywheel HTTP API. 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.
+CLI operations and MCP tools are related routes, not interchangeable payloads or commit lifecycles. This map documents the CLI route; use `flywheel-mcp-tool-map.md` for MCP-specific requests.
 
 ## 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:
+The CLI has its own destination and commit lifecycle:
 
-- 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.
+- **Identified local repository:** select it with explicit `--repo <path>`, explicit `--personal`, or working-directory discovery. Use `repo:` operations, then a local `repo:commit`; only `repo:push` when the user requests publication.
+- **Identified hosted graph:** use `hosted:` operations directly with its repository ID. Do not clone or initialize a local repository merely to edit that graph.
+- **Unknown destination:** ask before a write. A missing or invalid local repository selection is an error, not permission to fall back to hosted storage.
+- Local `repo:` mutations stage operations without network access. Local commit and hosted publication are separate: the first remote publication needs `repo:push --create-remote`; an already attached repository uses `repo:push` without that flag.
+- Hosted graph mutations build and post immediate repository commits with `--expected-head`; omit it to let the CLI fetch the current head, or pass the last observed head for optimistic locking.
+- Every hosted graph mutation requires `--repository-id <uuid>`. For an associated local workspace, read `repository_id` from `flywheel repo:status --repo <path> --format=json`.
+- Node values, tag definitions, edge content, and artifact metadata use the file flags documented by each graph command.
+- `repo:` and `hosted:` commands default to human output. Pass `--format=json` explicitly for scripts; other available formats are listed by command help.
 - Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
 
-## MCP-Equivalent Tool Families
+## Related MCP Operations
 
-The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI equivalent of each MCP tool.
+The families below identify related MCP operations for discovery and terminology. Read operations often have parallel results, but mutations use distinct payloads and persistence boundaries: `hosted:` posts an immediate repository commit, while `repo:` stages locally until local commit and optional push.
 
 ### 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 pagination, status, and archive filters.
-- `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. Relationship arrays are not guaranteed complete; use relationship paging commands for traversal.
-- `flywheel nodes:children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; MCP equivalent: `flywheel_get_node_children`): Page direct visible children with `--first`, `--after`, and `--projection`.
-- `flywheel nodes:parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; MCP equivalent: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
-- `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 comma-separated IDs; `--expected_revision` is required).
-- `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 with a full `--payload_json` body.
-- `flywheel nodes:branch` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; MCP equivalent: `flywheel_branch_node`): Create a child branch from a node. Preflight with `flywheel nodes:get --format=json` and pass `--expected_revision` for optimistic locking.
-- `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. Requires `--yes`. 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. Requires `--yes`.
+- `flywheel auth:status` (read; scopes: `read`; HTTP: `GET /auth/status`; related MCP operation: `flywheel_auth_status`): Show authentication status for the current client context.
+- `flywheel credits:balance` (read; scopes: `read`; HTTP: `GET /credits`; related MCP operation: `flywheel_get_credits_balance`): View credit balance and totals.
+- `flywheel updates:list` (read; scopes: `read`; HTTP: `tool-mediated`; related MCP operation: `flywheel_updates_list`): List in-app announcements relevant to your account.
+- `flywheel updates:hide` (mutating; scopes: `write`; HTTP: `POST /updates/{announcement_id}/hide`; related MCP operation: `flywheel_updates_hide`): Hide a specific announcement.
+- `flywheel updates:hide-all-active` (mutating; scopes: `write`; HTTP: `POST /updates/hide-all-active`; related MCP operation: `flywheel_updates_hide_all_active`): Hide all currently active announcements.
+- `flywheel updates:unhide` (mutating; scopes: `write`; HTTP: `DELETE /updates/{announcement_id}/hide`; related MCP operation: `flywheel_updates_unhide`): Restore a previously hidden announcement.
+- `flywheel hosted:node:list` (read; scopes: `read`; HTTP: `GET /nodes`; related MCP operation: `flywheel_list_nodes`): List nodes with optional pagination, status, and archive filters.
+- `flywheel nodes:resolve-slug` (read; scopes: `read`; HTTP: `GET /nodes/resolve-by-slug`; related MCP operation: `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`; related MCP operation: `flywheel_get_node_sharing`): Get sharing (access policy) for a node.
+- `flywheel nodes:sharing:set` (mutating; scopes: `write`; HTTP: `tool-mediated`; related MCP operation: `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`; related MCP operation: `flywheel_set_sharing_for_nodes`): Apply one sharing policy to multiple nodes.
+- `flywheel hosted:node:get` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}`; related MCP operation: `flywheel_get_node`): Read current hosted node state before writes; it does not return the repository commit head. Relationship arrays are not guaranteed complete; use `hosted:lineage:list` for traversal.
+- `flywheel hosted:lineage:list <node_id> --direction children` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/children`; related MCP operation: `flywheel_get_node_children`): Page direct visible children with `--first`, `--after`, and `--projection`.
+- `flywheel hosted:lineage:list <node_id> --direction parents` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/parents`; related MCP operation: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
+- `flywheel hosted:tag:define` (mutating; scopes: `write`; related MCP operation: `flywheel_create_node_tag`): Define a reusable tag and commit it immediately.
+- `flywheel hosted:tag:update` (mutating; scopes: `write`; related MCP operation: `flywheel_update_node_tag`): Update a tag definition and commit it immediately.
+- `flywheel hosted:tag:retire` (mutating; scopes: `write`; related MCP operation: `flywheel_delete_node_tag`): Retire a tag definition and commit it immediately.
+- `flywheel hosted:node-tag:assign` and `flywheel hosted:node-tag:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_set_node_tag_assignments`): Add or remove one tag assignment per hosted commit.
+- `flywheel nodes:render:tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/tree`; related MCP operation: `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`; related MCP operation: `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`; related MCP operation: `flywheel_get_campaign_snapshot`): Resolve campaign root snapshot for a node.
+- `flywheel admin:nodes:audit:list` (admin-only read; scopes: `read`; HTTP: `GET /admin/nodes/{node_id}/audit`; related MCP operation: `flywheel_admin_nodes_audit_list`): List audit events for node-level actions across all users.
+
+### Hosted graph mutations and stage leases
+
+- `flywheel hosted:node:create` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_new_node`): Create a node in one hosted repository commit; it is not an MCP staged-payload commit.
+- `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; related MCP operation: `flywheel_acquire_stage_lease`): Acquire a session-scoped edit lease for an existing MCP node workflow.
+- `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; related MCP operation: `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`; related MCP operation: `flywheel_release_stage_lease`): Release a node stage lease.
+- `flywheel hosted:node:set` (mutating; scopes: `write`; related MCP operation: `flywheel_commit_node`): Set one node field in one hosted repository commit; it is not an MCP staged-payload commit.
+- `flywheel hosted:node:branch` (mutating; scopes: `write`; related MCP operation: `flywheel_branch_node`): Create a child branch in one hosted repository commit. Pass `--expected-head` when the caller must reject concurrent hosted changes.
+- `flywheel hosted:node:merge` (mutating; scopes: `write`; related MCP operation: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one hosted repository commit.
+- `flywheel hosted:lineage:add` (mutating; scopes: `write`; related MCP operation: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted repository commit.
+- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; related MCP operation: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted repository commit.
+- `flywheel hosted:node:tombstone` (mutating; scopes: `write`; related MCP operation: `flywheel_delete_node`): Tombstone one node in one hosted repository commit.
+- There is no hosted bulk-tombstone command; run `flywheel hosted:node:tombstone` once per node.
 
 ### 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:delete-bulk` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/bulk-delete`; MCP equivalent: `flywheel_bulk_delete_artifacts`): Delete multiple artifacts from one node. Requires `--yes`.
-- `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).
+- `flywheel hosted:artifact:attach` (mutating; scopes: `write`): Direct-hosted helper that prepares the object upload, uploads required raw bytes, and appends the attachment in one hosted repository commit. It is related to, but does not replace or share the MCP two-call `flywheel_prepare_artifact_uploads` → raw upload → `flywheel_finalize_artifact_uploads` contract.
+- `flywheel hosted:artifact:list` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/artifacts`; related MCP operation: `flywheel_list_artifacts`): List artifacts for a node.
+- `flywheel hosted:artifact:get` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/artifacts/{artifact_id}`; related MCP operation: `flywheel_get_artifact`): Fetch one artifact metadata record.
+- `flywheel hosted:artifact:detach` (mutating; scopes: `write`; related MCP operation: `flywheel_delete_artifact`): Detach one artifact in one hosted commit.
+- There is no hosted bulk-detach command; run `flywheel hosted:artifact:detach` once per artifact.
+- `flywheel hosted:artifact:set-metadata` (mutating; scopes: `write`; related MCP operation: `flywheel_set_artifact_note`): Set one artifact metadata field in one hosted commit.
 
 ### 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.
+- `flywheel executions:launch` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions`; related MCP operation: `flywheel_launch_execution`): Start an execution for a node.
+- `flywheel executions:list` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/executions`; related MCP operation: `flywheel_list_executions`): List executions for a node.
+- `flywheel executions:terminate` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/executions/{execution_id}/terminate`; related MCP operation: `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. Use `--node_id`; optionally add `--provider`, `--limit`, or `--detail compact|full`.
-- `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/expired compute grants available to the user. Filter with `--status` and 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 explicit campaign budget fields such as `--hard_cap_cents`, `--per_user_hard_cap_cents`, `--name`, and `--description`.
-- `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 active leases in the current `lease_control_token` scope; `--force --yes` still requires `--lease_control_token` and explicitly broadens cleanup to all current-user active leases.
+- `flywheel compute:options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; related MCP operation: `flywheel_compute_list_options`): List compute catalog options for a node, including policy `allowed` flags. Use it only when a lease is needed and no suitable active lease exists. Use `--node_id`; optionally add `--provider`, `--limit`, or `--detail compact|full` (`full` exposes `region_selection_mode`). Filter `compute.options` to `allowed=true`, then select the offer and region as described in the empirical workflow. Catalog-only read; excludes grant/budget money fields.
+- `flywheel compute:funding` (read; scopes: `compute`; HTTP: `GET /compute/funding`; related MCP operation: `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`; related MCP operation: `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`; related MCP operation: `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`; related MCP operations: `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`; related MCP operation: `flywheel_list_approval_sessions`): List approval sessions visible to the current user.
+- `flywheel approval-sessions:expire` (mutating; scopes: `compute`; HTTP: `POST /approval-sessions/expire`; related MCP operation: `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`; related MCP operation: `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`; related MCP operation: `flywheel_list_compute_grants`): List active/expired compute grants available to the user. Filter with `--status` and 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`; related MCP operation: `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`; related MCP operation: `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}`; related MCP operation: `flywheel_update_campaign_budget`): Update explicit campaign budget fields such as `--hard_cap_cents`, `--per_user_hard_cap_cents`, `--name`, and `--description`.
+- `flywheel campaign-budgets:revoke` (mutating; scopes: `compute`; HTTP: `DELETE /nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`; related MCP operation: `flywheel_revoke_campaign_budget`): Revoke a campaign budget grant.
+- `flywheel compute:acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; related MCP operation: `flywheel_compute_acquire`): Acquire managed compute for a node once requirements are clear. Requires a valid `--compute_grant_id`; set `--requested_sku` to the exact `offer_id` from an `allowed=true` option returned by `flywheel compute:options` (`compute.options[].offer_id`), including provider prefixes (e.g., `nebius::...`); do not pass display names or partial IDs. Returns lease/provisioning state only (not SSH key material); capture `compute.lease_control_token` from the response for follow-up lease control commands, then poll `flywheel compute:status` for readiness.
+- `flywheel compute:release` (mutating; scopes: `compute`; HTTP: `tool-mediated`; related MCP operation: `flywheel_compute_release`): Release one active compute lease (async; use `--wait` to block).
+- `flywheel compute:release-all` (mutating; scopes: `compute`; HTTP: `tool-mediated`; related MCP operation: `flywheel_compute_release_all`): Release active leases in the current `lease_control_token` scope; `--force --yes` still requires `--lease_control_token` and explicitly broadens cleanup to all current-user active leases.
 
 ### 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. Pass `--include_descendants true` to expand roots to visible descendants, bounded by `--max_nodes`.
-- `flywheel import:subgraph` (mutating; scopes: `write`; HTTP: `POST /import`; MCP equivalent: `flywheel_import_subgraph`): Import graph JSON into new node records. Responses include `root_node_ids`, `imported_node_ids`, and `id_mapping`. 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`.
+- (no CLI equivalent; related MCP operation: `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; related MCP operation: `flywheel_get_contract_section`): Same as above.
+- `flywheel export:subgraph` (read; scopes: `read`; HTTP: `POST /export`; related MCP operation: `flywheel_export_subgraph`): Export a subgraph snapshot. Pass `--include_descendants true` to expand roots to visible descendants, bounded by `--max_nodes`.
+- `flywheel import:subgraph` (mutating; scopes: `write`; HTTP: `POST /import`; related MCP operation: `flywheel_import_subgraph`): Import graph JSON into new node records. Responses include `root_node_ids`, `imported_node_ids`, and `id_mapping`. 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`; related MCP operation: `flywheel_summarize_node_tree`): Render a compact summary of a node subtree.
+- `flywheel export:summary` (read; scopes: `read`; HTTP: `POST /export-summary`; related MCP operation: `flywheel_export_summary`): Generate a markdown summary export.
+- `flywheel export:summary:stream` (read; scopes: `read`; HTTP: `POST /export-summary-stream`; related MCP operation: `flywheel_export_summary_stream`): Stream summary generation as NDJSON events.
+- `flywheel export:summary:pdf` (read; scopes: `read`; HTTP: `POST /export-summary-pdf`; related MCP operation: `flywheel_export_summary_pdf`): Render summary as PDF; requires `--out`.
+- `flywheel export:summary:render-pdf` (read; scopes: `read`; HTTP: `POST /export-summary-render-pdf`; related MCP operation: `flywheel_export_summary_render_pdf`): Render caller-provided markdown as PDF; requires `--out`.
 
 ## CLI-Only Tool Families
 
@@ -114,8 +116,8 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 ### 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 auth:credentials:set [--profile <name>]` (local): Store an API key in the user credential file for a profile. Reads the key from stdin. Omitted `--profile` means `default`, not the active profile.
+- `flywheel auth:credentials:clear [--profile <name>]` (local): Remove only that profile's local API-key entry from the user credential file. Omitted `--profile` means `default`, not the active 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).
@@ -123,14 +125,10 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 
 ### Node helpers (CLI-only)
 
-- `flywheel nodes:create` (mutating; scopes: `write`): Create a minimal node (title only) and emit graph-change event.
+- `flywheel repo:node:create` (mutating; scopes: `write`): Create and stage a minimal node in the local repository.
 - `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.
 
-### 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 admin:compute:policy:get` (admin-only read; scopes: `compute`): Read compute budget policy for a node.
@@ -187,61 +185,108 @@ Account merge, detach, and email mutation commands are browser-session-bound. AP
 - `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 --page 1 --page_size 20`.
-
-### 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> --stage_session_id=<sid> --base_committed_revision=<rev>`: Acquire a session-scoped stage lease.
-3. `flywheel nodes:commit --node_id=<id> --payload_json=@payload.json`: Commit once terminal and contract-complete; the payload file includes `stage_session_id`, `base_committed_revision`, and `staged_payload`.
-
-### 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:options --node_id=<id> --detail compact`: List allowed offers; pick the exact `offer_id`.
-3. `flywheel compute-grants:request-approval --purpose "train" --requested_sku=<offer_id> --budget_source=user --acquire_node_id=<id>`: Request budget approval. Branch on response `status` (`already_approved` | `approval_required` | `insufficient_credits`).
-4. 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.
-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> --expected_revision=<rev> --items=@items.json`: One-shot upload using an upload item array, for example `[{"local_path":"results.json","artifact_type":"json"}]` (or use the prepare/finalize split for streaming).
-10. `flywheel nodes:commit --node_id=<id> --payload_json=@payload.json`: Commit terminal empirical node.
+### Local authoring workflow
+
+For a selected local destination, run the full sequence only for a new
+repository. For an existing repository, skip `repo:init` and first inspect
+`flywheel repo:status --repo "<repository-path>" --format=json`. If unrelated
+work is staged, stop and reconcile it with the user before continuing:
+`repo:commit` includes all staged operations. Push only when requested.
+
+```bash
+flywheel repo:init "<repository-path>" --format=json
+flywheel repo:node:create --repo "<repository-path>" --title "<node-title>" --format=json
+flywheel repo:status --repo "<repository-path>" --format=json
+flywheel repo:commit --repo "<repository-path>" --message "<commit-message>" --format=json
+# Only when the user requests publication; required for a first remote.
+flywheel repo:push --repo "<repository-path>" --create-remote --format=json
+```
+
+For an already attached repository, use:
+
+```bash
+flywheel repo:push --repo "<repository-path>" --format=json
+```
+
+### Direct hosted workflow
+
+Use this only after the destination is an identified hosted graph.
+
+```bash
+flywheel hosted:node:create --repository-id "<repository-id>" --title "<node-title>" --format=json
+flywheel hosted:node:get "<node-id>" --format=json
+flywheel hosted:node:set "<node-id>" --repository-id "<repository-id>" \
+  --field content --value-file "<content-file>" --format=json
+```
+
+### Empirical workflow
+
+For command-specific requirements, consult `flywheel help <command>`. The
+following CLI route has immediate hosted commits and should not be substituted
+for an MCP staged-payload flow. Create the node, choose the exact offered SKU,
+request approval, and retain the response's `approval_session_id`:
+
+```bash
+flywheel hosted:node:create --repository-id "<repository-id>" --title "<node-title>" --format=json
+flywheel compute:options --node_id "<node-id>" --detail full --format=json
+flywheel compute-grants:request-approval --purpose "train" --requested_sku "<offer-id>" --region "<region>" --budget_source user --acquire_node_id "<node-id>" --format=json
+```
+
+Filter `compute.options` to `allowed=true`, then use the selected option's exact
+`offer_id` and choose `<region>` from its `regions` list when
+`region_selection_mode` is `required_from_list`. Pass the same offer and region
+to approval and acquisition. For `provider_validated` offers, region is optional;
+omit `--region` from both commands when not selecting one.
+
+Branch on the approval response before acquiring compute:
+
+- `already_approved`: retain `approval_session_id` and use the returned
+  `compute_grant_id` directly.
+- `approval_required`: present `approval_url` to the user and wait for their
+  confirmation. Then list active grants scoped to the returned session and use
+  `grants[].compute_grant_id`:
+
+```bash
+flywheel compute-grants:list --status active --approval_session_id "<approval-session-id-from-response>" --format=json
+```
+
+- `insufficient_credits`: stop; do not list grants or acquire compute. The user
+  must add credits before submitting a new approval request.
+
+Once a valid grant is available for that session, acquire compute and continue:
+
+```bash
+flywheel compute:acquire --node_id "<node-id>" --compute_grant_id "<compute-grant-id>" --requested_sku "<offer-id>" --region "<region>" --approval_session_id "<approval-session-id>" --format=json
+flywheel compute:status --lease_control_token "<lease-control-token>" --format=json
+flywheel hosted:node:get "<node-id>" --format=json
+flywheel executions:launch --node_id "<node-id>" --expected_revision "<expected-revision>" --format=json
+flywheel executions:list --node_id "<node-id>" --format=json
+flywheel hosted:artifact:attach node "<node-id>" --repository-id "<repository-id>" --file "results.json" --metadata-file "metadata.json" --format=json
+flywheel hosted:node:set "<node-id>" --repository-id "<repository-id>" --field summary --value-file "summary.txt" --format=json
+```
+
+Use the node read response's current integer `revision` for
+`<expected-revision>` when launching execution, not the repository commit head.
 
 ## 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 t1,t2`; use `--tag_ids ""` to clear all assignments and always include `--expected_revision`.
-- `flywheel nodes:list` accepts pagination plus status/archive filters such as `--page`, `--page_size`, `--status`, and `--include_archived`.
+- `flywheel hosted:node-tag:assign <scope-node-id> <node-id> <tag-id> --repository-id=<repository-id> --expected-head=<head> --format=json` assigns one tag with optimistic locking; use `flywheel hosted:node-tag:remove` to remove one.
+- `flywheel hosted:node:list --page 1 --page_size 20 --format=json` accepts the preserved pagination and status/archive filters.
 - `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 once terminal and contract-complete; commit on an existing node requires an active stage lease and a `--payload_json` body with explicit `base_committed_revision`.
+- `flywheel hosted:artifact:detach node <node-id> <artifact-id> --repository-id=<repository-id> --format=json` removes an accidental or obsolete node artifact.
+- `flywheel hosted:artifact:list --node_id=<id> --format=json` and `flywheel hosted:artifact:get --node_id=<id> --artifact_id=<artifact-id> --format=json` inspect node artifact metadata and expose `storage_url` for raw artifact bytes.
 
 ## 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-lookahead/references/flywheel-mcp-tool-map.md

@@ -11,11 +11,11 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - Node body state is `title`, Markdown `content`, and optional `summary`; represent observations, decisions, experiments, and evidence with Markdown structure, tags, artifacts, and executions.
 - Node references include immutable `node_id` and optional immutable `slug_name`; prefer communicating both together for human clarity and disambiguation.
 - Graph topology should encode logical/causal relations between concepts and experiments. Avoid defaulting to shallow root-only branching unless work items are truly independent.
-- Node staging is local (non-canonical) and commit is the only canonical persistence boundary (`commit_new_node`, `commit_node`).
-- Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision` or `base_committed_revision` as required, and handle `409 conflict` with explicit reconciliation.
-- Mutating operations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
-- Existing-node field editing may use a session-scoped stage lease (`flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`) to coordinate local staged state before commit.
-- Existing-node commit publishes a full staged payload under an active stage lease: commit requests require `stage_session_id`, `base_committed_revision`, and `staged_payload`; conflicts on stale committed revisions are surfaced directly and are not transport-retried.
+- Node-body staging for `flywheel_commit_new_node` and `flywheel_commit_node` is caller-local until commit. Topology mutations such as `flywheel_branch_node`, `flywheel_merge_nodes`, `flywheel_add_parent`, and `flywheel_remove_parent` become canonical immediately when they succeed.
+- A new-node commit uses caller-local `local_temp_node_id`, `parent_ids`, and a full `staged_payload`; on success it returns the persisted canonical node. The correlation ID is not a canonical node ID and the operation does not use an existing-node stage lease or `base_committed_revision`.
+- An existing-node commit starts by reading the node, then acquiring `flywheel_acquire_stage_lease` with its `node_id`, caller-chosen `stage_session_id`, and current `base_committed_revision`. Commit with that same session ID/revision and a full `staged_payload`. A successful commit releases the lease; acquire a fresh lease before another commit.
+- MCP mutations are idempotent; MCP tool transport auto-manages `Idempotency-Key` on mutating tool calls.
+- Existing-node stage leases (`flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`) coordinate caller-local staged state before commit.
 - Committed node state uses the same canonical body fields for every node; `summary` may be empty when the node body is intentionally represented by content, artifacts, tags, or executions.
 - When code is involved, pass `repo_url`/`branch_name`/`head_commit_sha` and align git structure with graph topology where practical (without forcing one-to-one mapping).
 - Content, summaries, and artifacts should be reproduction-grade: enough setup, method, evidence, and interpretation for another reader to reproduce or audit results.
@@ -48,15 +48,15 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
 - `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
 - `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
-- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
+- `flywheel_admin_nodes_audit_list` (admin-only read; scopes: `read`; HTTP: `GET /admin/nodes/{node_id}/audit`; full-surface only): List audit events from every actor on the node; requires admin authorization.
 
 ### Node stage and commit
 
-- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
-- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
+- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /nodes/commit-new`; full-surface only): Commit a caller-local new node to canonical storage with `local_temp_node_id`, `parent_ids`, and full `staged_payload`; no existing-node stage lease or base revision applies.
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire an existing-node session-scoped stage lease with `node_id`, caller-chosen `stage_session_id`, and current `base_committed_revision`.
 - `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
 - `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
-- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
+- `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; core surface): Commit an existing node with the acquired `stage_session_id`, its current `base_committed_revision`, and full `staged_payload`.
 - `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; full-surface only): Create a child branch node with optimistic locking (`expected_revision` required); on 409, reread the node and retry with the current revision.
 - `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
 - `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
@@ -82,7 +82,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 ### Compute and budgets
 
-- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; core surface): List managed compute options allowed for a node. When using grant-backed compute, pass the same compute_grant_id you will use for acquire.
+- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; core surface): List managed compute catalog options and their policy `allowed` flags for a node when no suitable active lease exists; no compute grant is required. This catalog-only read excludes grant/budget money fields. Filter `compute.options` to `allowed=true`; copy the exact provider-qualified `compute.options[].offer_id` (`provider::offer_id`) verbatim (not a display name or partial ID), and select region as described in the empirical workflow.
 - `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.
@@ -96,7 +96,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. 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_acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Acquire managed compute for a node with explicit SKU, a region when the selected offer requires one, 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` from an `allowed=true` option returned by `flywheel_compute_list_options` (`compute.options[].offer_id`), including provider prefixes (for example `nebius::...`); do not pass display names or partial IDs. Capture `compute.lease_control_token` from the response for follow-up lease-control tools.
 - `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` with `lease_control_token` for explicit account-wide cleanup for the current user.
 
@@ -118,26 +118,27 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 1. `flywheel_list_nodes` with `{'owners': ['me'], 'projection': 'core'}`.
 
-### Safe Node Update
+### Existing-node update
 
-1. `flywheel_get_node`: Read latest node state before mutating fields.
-2. `flywheel_acquire_stage_lease`: Acquire a session-scoped stage lease before editing an existing node locally.
-3. `flywheel_commit_node`: Commit with `stage_session_id`, `base_committed_revision`, and full `staged_payload` once terminal and contract-complete.
+1. `flywheel_get_node`: Read the current canonical node and revision.
+2. `flywheel_acquire_stage_lease`: Acquire with the node ID, caller-chosen `stage_session_id`, and that current `base_committed_revision`.
+3. `flywheel_commit_node`: Commit with the same session ID/revision and the full `staged_payload`.
+4. If commit returns a stale-revision `409`, release the caller's stale lease, reread and reconcile the node, then acquire a fresh lease at the latest revision before retrying.
 
 ### Empirical Workflow
 
-1. `flywheel_commit_new_node`: Commit a local staged new node to canonical storage as the first persistence boundary.
-2. `flywheel_commit_node`: Commit staged empirical fields with `stage_session_id`, `base_committed_revision`, and a full `staged_payload` once the working state is ready to publish.
-3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval context first. Branch on response status.
-4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`).. if `already_approved` then `reuse_compute_grant_id`: Use returned `compute_grant_id` directly for flywheel_compute_acquire.. if `approval_required` then `present_approval_url_to_user`: Present `approval_url` to the user; the user opens it and confirms budget approval.; `flywheel_list_compute_grants`: After approval, list active grants for the current `approval_session_id` and use the returned `compute_grant_id` for acquire.. if `insufficient_credits` then `request_user_credit_top_up`: No `approval_url` is returned. Ask the user to add credits, then retry flywheel_request_compute_grant_approval.
-5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id` from approval response and set `requested_sku` to the exact selected `options[].offer_id`.
+1. `flywheel_commit_new_node`: Persist the caller-local new empirical node with `local_temp_node_id`, `parent_ids`, and full `staged_payload`.
+2. For an existing empirical node: `flywheel_get_node`, then `flywheel_acquire_stage_lease` with node ID, caller-chosen session ID, and current base revision; then `flywheel_commit_node` with that same session ID/revision and full `staged_payload`.
+3. If compute is needed, call `flywheel_compute_list_options` with `detail="full"`, filter `compute.options` to `allowed=true`, and select the exact `offer_id`. For `region_selection_mode` `required_from_list`, choose `region` from the selected option's `regions`. For `provider_validated`, pass `region=""` to `flywheel_request_compute_grant_approval`, then omit `region` from acquisition. Call approval with the selected option's `provider`, that `requested_sku`, the selected region or empty string, the intended `grant_action`, purpose, and budget source.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`). If `already_approved`, use the returned `compute_grant_id` directly for `flywheel_compute_acquire`. If `approval_required`, present `approval_url` to the user; after approval, `flywheel_list_compute_grants` for the current `approval_session_id` and use its `compute_grant_id`. If `insufficient_credits`, 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`, set `requested_sku` to the exact selected `compute.options[].offer_id`, and include the selected `region` when `region_selection_mode` is `required_from_list`.
 6. `flywheel_compute_status`: Poll until the active lease is ready; follow `recommended_next_action`.
 7. `flywheel_launch_execution`: Launch execution once compute and inputs are ready.
 8. `flywheel_list_executions`: Poll until execution reaches terminal status.
 9. `flywheel_prepare_artifact_uploads`: Prepare signed upload URLs for empirical evidence.
 10. `raw_file_upload`: Upload raw bytes to each signed URL with required headers.
 11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit when the work produced evidence artifacts.
-12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
+12. Re-read the node and acquire a fresh stage lease at its latest committed revision. Use `flywheel_commit_node` to publish the result fields and terminal state together in one full `staged_payload`.
 
 ## Runtime Guidance
 
@@ -152,13 +153,10 @@ 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 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`; 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.
 - `flywheel_finalize_artifact_uploads`: finalize a staged artifact batch and append all uploaded artifacts in one revision bump.
 - `flywheel_delete_artifact`: remove an accidental/obsolete node artifact.
 - `flywheel_list_artifacts`, `flywheel_get_artifact`: inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
-- `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.

package/skills/flywheel-prove/SKILL.md

@@ -67,7 +67,7 @@ lake --version
 1. Scaffold pipeline into the current repository:
 
    ```bash
-   python <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
+   uv run --no-project <skill-root>/scripts/scaffold_pipeline.py --repo-root <repo-root> --setup-env
    cd <repo-root>/theorem_pipeline
    ```
 
@@ -149,7 +149,7 @@ lake --version
     uv run -m tproof.cli verify
     ```
 
-    `verify` must pass with no unresolved `sorry` and no `.lean`/`.md` final artifacts under `workspace/staging/`.
+    `verify` must pass with no unresolved `sorry` and no `.lean` or `.md` artifacts anywhere under `workspace/staging/`.
 
 11. Mark run status: