@paradigma-inc/flywheel 0.1.111 → 0.1.134

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

@@ -19,7 +19,7 @@ Help the user clarify what they are trying to learn, shape the work around that
 - Propose defaults for structural choices such as experiment shape, stop condition, or artifact plan. Use questions rather than defaults for epistemic choices such as beliefs, assumptions, and what evidence would matter.
 - When a reasoning or design gap is visible, raise it as a question rather than an assertion.
 - If the core gate is satisfied and the user wants to proceed, stop asking more design questions.
-- Use Flywheel `insight` nodes to preserve design context when it will help across turns or sessions.
+- Use Flywheel nodes to preserve design context when it will help across turns or sessions.
 
 ## Phase 1: Clarify what the user is trying to learn
 
@@ -43,7 +43,7 @@ If the work is exploratory, ask:
 - What is the cheapest or cleanest way to learn that first piece?
 - What signal or pattern are you looking for?
 
-If the user is still fuzzy after this phase, stay in planning mode. If needed, create or update an `insight` node rather than an `empirical` node.
+If the user is still fuzzy after this phase, stay in planning mode. If needed, record planning or exploratory content rather than launching an empirical probe.
 
 ## Phase 2: Shape the work
 
@@ -117,35 +117,42 @@ If the run is expensive or high-risk, ask for explicit confirmation.
 
 ## Phase 5: Drive Flywheel
 
-Use Flywheel in layers when possible.
-
-Before execution, load `references/flywheel-mcp-tool-map.md` and verify the
-exact tool surface exposed by the current MCP host before critical flows.
+Use the active configured interface throughout design, execution, and result
+persistence, following this skill's installation-mode guidance. A skill-only
+MCP install uses a separately configured CLI, not an MCP tool surface; do not
+assume that installing the skill configured the CLI.
+
+1. **Active MCP interface:** verify that the active MCP host exposes the required
+   tool surface, then load this skill's [MCP tool map](flywheel-mcp-tool-map.md).
+   Use its design, empirical, and final-result flows. If that surface is not
+   available, do not substitute CLI commands; configure the intended interface
+   or explain the blocker. Its caller-local new-node payload flow is distinct
+   from its existing-node session-stage-lease and full-payload commit flow; do
+   not recast either as a CLI repository commit.
+2. **Active CLI interface (including skill-only MCP installs):** load this skill's
+   [CLI tool map](flywheel-cli-tool-map.md). First determine the destination:
+   use its Local authoring workflow for an identified local repository
+   (stage, commit locally, and push only when publication is requested), or its
+   direct hosted/Empirical Workflow for an identified hosted repository
+   (immediate hosted commits). If the destination is unknown, ask before
+   writing; a missing local repository is not a reason to switch to hosted
+   storage.
 
 ### Design layer
 
-Use an `insight` node to capture rationale, open questions, experiment shape, and any decomposition needed for exploratory or multi-stage work.
-
-Typical flow:
-
-1. `mcp__flywheel__flywheel_commit_new_node`
-2. `mcp__flywheel__flywheel_acquire_stage_lease` when refining an existing design node
-3. `mcp__flywheel__flywheel_commit_node` once the design brief is coherent
+Persist rationale, open questions, experiment shape, and exploratory or
+multi-stage decomposition through the selected map's matching write flow.
+Preserve the interface and destination choice while refining that design; do
+not mix MCP staged payloads with CLI local or hosted commit semantics.
 
 ### Execution layer
 
-Only after the design gate passes, create or branch the node for the runnable part of the work.
-
-Typical flow:
-
-1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_commit_new_node`
-2. `mcp__flywheel__flywheel_acquire_stage_lease` + `mcp__flywheel__flywheel_commit_node` with the explicit run summary and the local question or hypothesis for that branch
-3. `mcp__flywheel__flywheel_request_compute_grant_approval` only after the user accepts the design
-4. `mcp__flywheel__flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)` when you need to resolve the approved `compute_grant_id`
-5. `mcp__flywheel__flywheel_compute_acquire` and related compute tools only when execution is actually needed
-6. `mcp__flywheel__flywheel_prepare_artifact_uploads`, raw upload to the returned signed URLs, then `mcp__flywheel__flywheel_finalize_artifact_uploads`
-7. Do a brief epistemic check before commit: verify what the evidence actually shows, whether it matches the interpretation rule from the brief, and whether any gap between the data and the hoped-for story needs to be named explicitly in the node summary.
-8. `mcp__flywheel__flywheel_commit_node`
+Only after the design gate passes, create or branch the runnable work through
+the selected map. For managed compute, follow that map's Empirical Workflow
+end-to-end: catalog selection, approval, grant resolution, acquisition,
+execution, evidence artifacts, and the final result persistence path. Before
+that final result write, check that the evidence supports the interpretation
+and name any gap in the summary.
 
 Important notes:
 

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

@@ -4,23 +4,24 @@ 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.
+For MCP routing, see `flywheel-mcp-tool-map.md`. The families below group related capabilities; CLI repository commands and MCP tools do not share the same staging or commit workflow.
 
 ## 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:
+Follow `flywheel-mcp-tool-map.md` for MCP-specific payload and lease workflows. For the CLI:
 
-- 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.
+- Direct `hosted:` graph mutations require `--repository-id <uuid>` and immediately post one hosted repository commit. They accept `--expected-head`; omit it to let the CLI fetch the current head, or pass the last observed head for optimistic locking. Direct hosted mutations are not local repository commits and do not require a clone or initialization.
+- For local repository operations, select an explicit `--repo` path, an explicitly requested `--personal` repository, or a repository found from the current directory and its ancestors. `--repo` and `--personal` conflict. A missing or invalid local selection fails; it does not fall back to hosted storage.
+- Local `repo:` mutations stage operations without network access. `repo:commit` commits the exact staging digest locally. Use `repo:push` only when publication is requested; use `--create-remote` only when that publication must create the hosted repository.
+- 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.
+- Attach an artifact with `flywheel hosted:artifact:attach node <owner-id> --repository-id <uuid> --file <path> --metadata-file artifact.json --format=json`; the CLI prepares the upload, sends raw bytes, and commits the attachment.
 - Mutating commands are subject to per-user write limits: 120 node creates per minute, 2,000 node creates per 24 hours, and 120 graph writes per minute. Graph writes include existing-node commits, edge changes, deletes, merges, tags, sharing, artifact finalization, artifact deletion, and artifact-note updates. On `429`, honor `Retry-After` and retry the same idempotent command after waiting.
 - Run `flywheel help <command>` for canonical per-command flags, types, defaults, examples, and related commands.
 
-## MCP-Equivalent Tool Families
+## CLI Families and 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 group CLI capabilities alongside related MCP tools. A related MCP tool is not a drop-in replacement for a CLI repository command.
 
 ### Discovery and sharing
 
@@ -30,48 +31,46 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `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 hosted:node: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 hosted:node:get` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}`; MCP equivalent: `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`; MCP equivalent: `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`; MCP equivalent: `flywheel_get_node_parents`): Page direct visible parents with `--first`, `--after`, and `--projection`.
+- `flywheel hosted:tag:define` (mutating; scopes: `write`; MCP equivalent: `flywheel_create_node_tag`): Define a reusable tag and commit it immediately.
+- `flywheel hosted:tag:update` (mutating; scopes: `write`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition and commit it immediately.
+- `flywheel hosted:tag:retire` (mutating; scopes: `write`; MCP equivalent: `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`; MCP equivalent: `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`; 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
+### Hosted graph mutations and stage leases
 
-- `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 hosted:node:create` (mutating; scopes: `write`; MCP equivalent: `flywheel_commit_new_node`): Create a node in one hosted commit.
+- `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; MCP equivalent: `flywheel_acquire_stage_lease`): Acquire a session-scoped edit lease for an existing-node MCP staged-payload workflow, not local CLI `repo:` authoring or direct `hosted:` mutations.
 - `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 hosted:node:set` (mutating; scopes: `write`; MCP equivalent: `flywheel_commit_node`): Set one node field in one hosted commit.
+- `flywheel hosted:node:branch` (mutating; scopes: `write`; MCP equivalent: `flywheel_branch_node`): Create a child branch in one hosted commit. Pass `--expected-head` when the caller must reject concurrent hosted changes.
+- `flywheel hosted:node:merge` (mutating; scopes: `write`; MCP equivalent: `flywheel_merge_nodes`): Merge repeated `--source` nodes into one node in one hosted commit.
+- `flywheel hosted:lineage:add` (mutating; scopes: `write`; MCP equivalent: `flywheel_add_parent`): Add a parent-child lineage relation in one hosted commit.
+- `flywheel hosted:lineage:remove` (mutating; scopes: `write`; MCP equivalent: `flywheel_remove_parent`): Remove a parent-child lineage relation in one hosted commit.
+- `flywheel hosted:node:tombstone` (mutating; scopes: `write`; MCP equivalent: `flywheel_delete_node`): Tombstone one node in one hosted 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 hosted:artifact:attach` (mutating; scopes: `write`; related MCP operations: `flywheel_prepare_artifact_uploads`, `flywheel_finalize_artifact_uploads`): Prepare the upload, send raw bytes, and commit the attachment in one CLI invocation. MCP callers separately prepare, upload, and finalize; do not invoke the CLI attachment command twice.
 - `flywheel remote-artifacts:resolve` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/remote-artifacts/resolve`; MCP equivalent: `flywheel_resolve_remote_artifact`): Resolve and materialize a public HTTPS JSON remote artifact for a node, using the cached artifact when it is still fresh.
 - `flywheel remote-artifacts:refresh` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/remote-artifacts/refresh`; MCP equivalent: `flywheel_refresh_remote_artifact`): Force refresh and materialize a public HTTPS JSON remote artifact for a node.
-- `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:list` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/artifacts`; MCP equivalent: `flywheel_list_artifacts`): List artifacts for a node.
+- `flywheel hosted:artifact:get` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/artifacts/{artifact_id}`; MCP equivalent: `flywheel_get_artifact`): Fetch one artifact metadata record.
+- `flywheel hosted:artifact:detach` (mutating; scopes: `write`; MCP equivalent: `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`; MCP equivalent: `flywheel_set_artifact_note`): Set one artifact metadata field in one hosted commit.
 
 ### Executions
 
@@ -81,7 +80,7 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 
 ### 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:options` (read; scopes: `compute`; HTTP: `GET /compute/catalog`; MCP equivalent: `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`; 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).
@@ -94,7 +93,7 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `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:acquire` (mutating; scopes: `compute`; HTTP: `tool-mediated`; MCP equivalent: `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`; 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.
 
@@ -117,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).
@@ -126,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.
@@ -190,69 +185,118 @@ 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`.
+```bash
+flywheel hosted:node:list --page 1 --page_size 20 --format=json
+```
 
 ### 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`.
+Read the hosted node before updating it. Omit `--expected-head` to let the CLI fetch the repository head, or supply a separately observed repository head for optimistic locking; the node read does not return that head.
+
+```bash
+flywheel hosted:node:get "<node-id>" --format=json
+flywheel hosted:node:set "<node-id>" --repository-id "<repository-id>" --field "<field>" --value-file "<value-path>" --format=json
+```
 
 ### 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.
+For an identified hosted repository, create the node as a direct hosted commit,
+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-path>" --metadata-file "<metadata-path>" --format=json
+flywheel hosted:node:set "<node-id>" --repository-id "<repository-id>" --field summary --value-file "<summary-path>" --format=json
+```
+
+Use the node read response's current integer `revision` for
+`<expected-revision>` when launching execution, not the repository commit head.
+
+### Local authoring workflow
+
+`<repository-path>` is a new local repository directory. `<node-title>` and
+`<commit-message>` are user-supplied text, and `<node-id>` comes from the
+preceding create response. Use the push line only when publication is 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
+flywheel repo:status --repo "<repository-path>" --format=json
+flywheel repo:node:get "<node-id>" --repo "<repository-path>" --format=json
+flywheel repo:push --repo "<repository-path>" --create-remote --format=json
+flywheel repo:status --repo "<repository-path>" --format=json
+flywheel hosted:node:get "<node-id>" --format=json
+```
 
 ## 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:attach node <node-id> --repository-id=<repository-id> --file=results.json --metadata-file=metadata.json --format=json` uploads and commits one artifact.
+- `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.
+- `flywheel hosted:node:create --repository-id=<repository-id> --title=<title> --format=json` and `flywheel hosted:node:set <node-id> --repository-id=<repository-id> --field=<field> --value-file=<path> --format=json` publish repository commits directly.
 
 ## Admin only (FLY-359)
 
-These commands require `FLYWHEEL_ADMIN_KEY` in the environment (forwarded as the `X-Admin-Key` header) or an admin browser session. Default help and JSON help hide admin commands unless `FLYWHEEL_ADMIN_KEY` or `FLYWHEEL_CLI_INTERNAL=1` is present, but explicit `flywheel help admin:<command>` still works. API-key-only callers fail locally with `admin_auth_required`. The endpoints are omitted from the public OpenAPI schema and from the API-key allowlist.
+These commands require `FLYWHEEL_ADMIN_KEY` in the environment (forwarded as the `X-Admin-Key` header) or an admin browser session. Default help and JSON help hide admin commands unless `FLYWHEEL_ADMIN_KEY` or `FLYWHEEL_CLI_INTERNAL=1` is present; `admin:<command>` below is generic syntax, not a concrete public command. API-key-only callers fail locally with `admin_auth_required`. The endpoints are omitted from the public OpenAPI schema and from the API-key allowlist.
 
 - `flywheel admin:graphs:list` — list every root-node graph across all users. Filters: `--tag-id`, `--owner-user-id`, `--created-after`, `--created-before`, `--cursor`, `--page-size` (1..200).
 - `flywheel admin:graphs:export --root-node-id=<id>` — export one graph as canonical JSON, bypassing per-caller visibility.
 - `flywheel admin:graphs:export:stream` — stream canonical graph JSON for many graphs as NDJSON (one page per call, `--out=<file>` to write to disk). Filters match `admin:graphs:list`.
+- `flywheel admin:nodes:audit:list --node_id=<node-id>` — list audit events for node-level actions across all users. Use `--limit` to bound the number of events.
 
 ## 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.
+- `flywheel hosted:node:list --format json` — a concrete command with the output-format selector for scripting workflows.

package/skills/flywheel/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.
+- 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.
+- Mutating node writes are optimistic-locking operations: read latest state, pass `expected_revision` or `base_committed_revision` as required, and reconcile a `409 conflict` explicitly.
 - 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.
+- For a new node, call `flywheel_commit_new_node` with caller-local `local_temp_node_id`, `parent_ids`, and the full `staged_payload`; no existing-node lease is acquired. For an existing node, first read its committed revision, acquire a stage lease using the caller's `stage_session_id`, keep the staged body caller-local, then call `flywheel_commit_node` with that `stage_session_id`, `base_committed_revision`, and the full `staged_payload`. Do not translate either flow into a CLI repository commit.
+- Existing-node commit conflicts on stale committed revisions are surfaced directly and are not transport-retried.
 - 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.
@@ -49,7 +49,7 @@ 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
 
@@ -112,7 +112,7 @@ Hook workflow-if contract (first version):
 
 ### 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.
@@ -126,7 +126,7 @@ Hook workflow-if contract (first version):
 - `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.
 
@@ -146,37 +146,50 @@ Hook workflow-if contract (first version):
 
 ### List Owned Nodes
 
-1. `flywheel_list_nodes` with `{'owners': ['me'], 'projection': 'core'}`.
+Ask `flywheel_list_nodes` for the caller's owned nodes with the core projection.
 
 ### Safe 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.
+Read the latest existing node. With the observed committed revision, acquire an
+existing-node stage lease using a caller `stage_session_id`. Keep the complete
+staged body caller-local, then call `flywheel_commit_node` with the same
+`stage_session_id`, `base_committed_revision`, and full `staged_payload`. A
+successful commit releases the lease. On a stale-revision `409`, release the
+caller's stale lease, reread and reconcile the node, then acquire a fresh lease
+at the latest committed 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`.
-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.
+For a new empirical node, call `flywheel_commit_new_node` with a caller-local
+`local_temp_node_id`, intended `parent_ids`, and a full `staged_payload`; do
+not acquire an existing-node lease. For a later update to that canonical node,
+use the existing-node lease and commit flow above.
+
+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. Branch on its status.
+Reuse the returned grant for `already_approved`; present `approval_url` to the
+user and then obtain an active grant scoped to the approval session for
+`approval_required`; ask the user to add credits before retrying for
+`insufficient_credits`. Acquire compute using the same selected offer, grant,
+approval session, and selected region when required, then poll status to
+readiness. Launch and poll execution, prepare uploads, send raw file bytes to
+the signed URLs, and finalize the artifact batch. Then reread the node and
+acquire a fresh stage lease at its latest committed revision. Publish the result
+fields and terminal state together in one full `staged_payload` through
+`flywheel_commit_node`.
 
 ### Hook Automation Workflow
 
-1. `flywheel_create_hook_secret`: Create endpoint credentials if the action needs auth.
-2. `flywheel_create_hook`: Define `workflow_yaml.on`, scope, `workflow_yaml.if`, and `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` or `flywheel_set_sharing_for_node`: Emit `artifact.finalized` on successful finalize writes or `node.published` when an eligible submission node becomes public.
-6. `flywheel_list_hook_runs`: Inspect run outcomes (`queued`, `running`, `succeeded`, `failed`).
+Create a hook secret when the action needs endpoint credentials, then create the
+hook with its trigger, scope, condition, and steps. Enable it once configured,
+verify its scope and enabled state, and inspect hook-run outcomes after the
+triggering artifact finalization or eligible node publication.
 
 ## Runtime Guidance
 
@@ -191,16 +204,13 @@ Hook workflow-if contract (first version):
 - `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`.
 
 ### Admin only (FLY-359)
 

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

@@ -13,4 +13,4 @@ npx --yes @paradigma-inc/flywheel uninstall --claude
 npx --yes @paradigma-inc/flywheel setup --mode mcp --claude
 ```
 
-If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.
+If your previous install used a server name different from `flywheel`, append `--name "<old-name>"` to the uninstall command above to remove that selected entry.

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

@@ -13,4 +13,4 @@ npx --yes @paradigma-inc/flywheel uninstall --codex
 npx --yes @paradigma-inc/flywheel setup --mode mcp --codex
 ```
 
-If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.
+If your previous install used a server name different from `flywheel`, append `--name "<old-name>"` to the uninstall command above to remove that selected entry.