@paradigma-inc/flywheel 0.1.115 → 0.1.134

package/skills/flywheel-to-graph/SKILL.md

@@ -15,12 +15,33 @@ If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool
 
 This skill supports both Flywheel install modes:
 
-- **`--mode mcp` install**: route via [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md); tool calls take the form `flywheel_<tool>` (e.g., `flywheel_commit_node`).
-- **`--mode cli` install**: `setup --mode cli` configures runtime credentials, then route via [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md); tool calls take the form `flywheel <command>` (e.g., `flywheel nodes:commit`). Prerequisite for bare-binary routing: run the curl installer with `--mode cli` or use the managed-prefix npm install recipe from the README.
+- **`--mode mcp` install on an MCP-capable host:** setup writes host-specific
+  MCP configuration; use [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md)
+  and the host's `flywheel_<tool>` surface.
+- **`--mode mcp` install on a skill-only host:** setup installs the skill but
+  skips MCP configuration, so no `flywheel_<tool>` surface exists. Route work
+  through a separately configured CLI, subject to the CLI caveat below.
+- **`--mode cli` install:** setup installs skills and writes runtime TOML unless every selected host is skill-only (for example, Universal or Antigravity). A skill-only selection skips CLI authentication and runtime configuration. Use [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md) and the `flywheel <command>` surface only with a configured CLI.
+
+Configure CLI mode independently. This command prompts for a host in an interactive terminal:
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli
+```
+
+For noninteractive setup, pass the active host's selector from `npx --yes @paradigma-inc/flywheel setup --help` (for example, `--claude` for Claude Code). Without a selector, prompt-free setup uses all detected hosts. Match the existing project/global scope.
+
+Running setup through `npx` configures settings and skills; it does not install a persistent `flywheel` binary. If `flywheel` is not on `PATH`, replace `flywheel` with `npx --yes @paradigma-inc/flywheel` in every CLI example below and in the linked tool map.
+
+When switching an already configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+
+Pick the route from both install mode and intended destination:
 
-When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+- For an identified local repository, select it with `--repo <path>`, `--personal`, or working-directory discovery; use `repo:` operations, local `repo:commit`, and `repo:push` only when publication is requested.
+- For an identified hosted graph, use supported `hosted:` operations directly; do not require a clone or local initialization merely to edit it.
+- If the destination is unknown, ask before writing. A failed local selection never permits a hosted fallback.
 
-The Workflow below cites both the MCP tool name and its CLI equivalent inline at each imperative step. Pick the one matching your install mode.
+MCP payloads and leases are not interchangeable with CLI commits. Follow this skill's [MCP tool map](references/flywheel-mcp-tool-map.md) for the distinct new-node and existing-node requirements. For hosted CLI writes, resolve `<repository-id>` to the intended hosted graph; hosted reads take node selectors, not `--repository-id`.
 
 ## Input Contract
 
@@ -38,7 +59,7 @@ Before authoring, recover or establish these inputs:
 - `source corpus`: the input material to port, such as papers, blog posts, READMEs, markdown wikis, or research notes.
 - `normalized Flywheel graph export`: already-structured Flywheel node JSON with DAG-safe edges, suitable for `flywheel_import_subgraph`.
 - `durable edge`: a graph relationship that carries stable semantic meaning, not just a navigational hyperlink.
-- `authoring pass`: one pass that reads source material and stages or commits the corresponding node/artifact updates.
+- `authoring pass`: one pass that reads source material and persists the corresponding node/artifact updates.
 - `graph-native import`: an import that preserves the source's substantive ideas, procedures, evidence, and durable relationships in a graph-friendly form, without needing to mirror the original prose order, headings, or layout.
 - `expected_revision`: the node's current revision token used for optimistic-locking writes.
 
@@ -84,8 +105,8 @@ This means:
 3. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
    - Choose node boundaries by conceptual cohesion and durable relationships first, then use file or heading boundaries as secondary hints.
-   - Create a new node with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI) when needed.
-   - Update an existing node with `flywheel_get_node` + `flywheel_acquire_stage_lease` + `flywheel_commit_node` (MCP) or `flywheel nodes:get` + `flywheel nodes:stage:lease:acquire` + `flywheel nodes:commit` (CLI) when continuing work.
+   - On MCP, persist a new canonical node with `flywheel_commit_new_node` and its caller-local ID, parent IDs, and full staged payload. On CLI, follow the selected destination: use `hosted:node:create` only for an identified hosted graph, or `repo:node:create` for an identified local repository.
+   - On MCP, update an existing canonical node by reading it, acquiring the stage lease, then committing the same session/revision with full staged payload. On CLI, use `hosted:node:set` only for an identified hosted graph; local edits remain `repo:` operations until the separate local commit.
    - If the source layout hides the real structure, regroup material into concept, procedure, claim, dataset, baseline, result, comparison, decision, or dependency nodes.
    - If a section would become a shallow stub, split it into more graph-native nodes until the imported graph preserves the underlying logic.
 4. Put a graph-native narrative in the node body/readme field (`content`).
@@ -97,16 +118,15 @@ This means:
    - Do not stop at "this section describes X"; include what X actually says and how it connects to neighboring nodes.
 5. Publish supporting files with the artifact upload flow.
    - For exact artifact contract details, load [references/ARTIFACTS.md](references/ARTIFACTS.md).
-   - Use `flywheel_prepare_artifact_uploads` (MCP) or `flywheel artifacts:upload:prepare` (CLI).
-   - Upload raw file bytes to the returned signed URLs.
-   - Call `flywheel_finalize_artifact_uploads` (MCP) or `flywheel artifacts:upload:finalize` (CLI) once all uploads in the batch are staged.
+   - MCP mode uses `flywheel_prepare_artifact_uploads`, uploads raw bytes to the returned signed URLs, then calls `flywheel_finalize_artifact_uploads`.
+   - The direct-hosted CLI artifact helper prepares, uploads, and appends an attachment in one hosted repository commit. It is related to, but does not replace or share, MCP's prepare → raw upload → finalize contract.
    - Keep the artifact filename stable enough to reference from markdown when inline rendering matters.
 6. Add graph structure sparingly.
    - Promote only durable semantic relationships to edges.
    - Prefer relationships such as defines, depends-on, compares-with, evaluates, produces, supports, contradicts, decomposes-into, or derived-from when the source supports them.
    - Leave ordinary cross-links inside the markdown body.
-7. Commit after the node snapshot is coherent with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI).
-   - Commit once the source narrative, artifact attachments, and selected graph structure agree with each other.
+7. Persist each coherent node snapshot.
+   - For MCP, commit existing nodes with their active lease session, current base revision, and full staged payload; new nodes use `flywheel_commit_new_node` with their caller-local ID and parent IDs. For CLI, direct hosted mutations already post repository commits, while local `repo:` edits require the separate local `repo:commit` and optional user-requested `repo:push`.
 
 ## Result Contract
 
@@ -127,13 +147,13 @@ For the canonical entity model and public contract terminology behind this contr
 
 Use this storage convention:
 
-1. Reuse an existing authoring control node when one already governs the same corpus; otherwise create one with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI).
+1. Reuse an existing authoring control node when one already governs the same corpus; otherwise persist a new MCP node with `flywheel_commit_new_node` or use the destination-appropriate hosted or local CLI workflow.
 2. Put the canonical authoring contract in node `content`.
 3. Put a one-line synopsis in `summary`.
 4. Put the current mapping rationale or continuation note in `content`.
-5. Before committing control-node edits, acquire or refresh the stage lease with `flywheel_acquire_stage_lease` (and `flywheel_heartbeat_stage_lease` for long edits) — or in CLI mode, `flywheel nodes:stage:lease:acquire` and `flywheel nodes:stage:lease:heartbeat`.
-6. Read the control node with `flywheel_get_node` (MCP) or `flywheel nodes:get` (CLI) before later passes that need a fresh `expected_revision`.
-7. Commit the control node with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI) once the contract is coherent, even if downstream source nodes remain staged or in progress.
+5. For an existing MCP control node, read current state, acquire or refresh the lease with its session ID and base revision, then commit the same values with full staged payload. A direct hosted CLI mutation is an immediate repository commit; a local CLI edit must complete its separate local commit lifecycle.
+6. Before later passes, read the control node from the destination where it was persisted: `flywheel_get_node` for MCP, `flywheel repo:node:get` with the same local repository selected for local CLI, or `flywheel hosted:node:get` for hosted CLI.
+7. Persist the coherent control node before proceeding. Do not treat caller-local MCP staging or uncommitted local CLI operations as durable control state.
 
 Canonical contract shape:
 
@@ -235,4 +255,4 @@ Guidelines:
 - Do not confuse graphifying the source with empirically validating it: preserve enough detail for later reuse, but do not execute or test claims inside `$flywheel-to-graph`.
 - These source-to-graph authoring-only rules apply only when $flywheel-to-graph is the active skill.
 
-See also: invoke `$flywheel-reproduce` to graphify claim-bearing sources and run budgeted validation branches, invoke `$flywheel-lookahead` to stage next-step frontier nodes from existing graph state without execution, and invoke `$flywheel-auto` to advance a frontier autonomously under an explicit budget and persisted stop condition.
+See also: invoke `$flywheel-reproduce` to graphify claim-bearing sources and run budgeted validation branches, invoke `$flywheel-lookahead` to persist next-step frontier nodes from existing graph state without execution, and invoke `$flywheel-auto` to advance a frontier autonomously under an explicit budget and persisted stop condition.

package/skills/flywheel-to-graph/references/INTERFACES.md

@@ -58,7 +58,7 @@ direct-neighbor traversal.
 - `flywheel_get_node_tree` (read; scopes: `read`; full-surface only; binding: `operation`)
 - `flywheel_get_node_ancestry` (read; scopes: `read`; full-surface only; binding: `operation`)
 - `flywheel_get_campaign_snapshot` (read; scopes: `read`; core surface; binding: `operation`)
-- `flywheel_list_audit` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_admin_nodes_audit_list` (admin-only read; scopes: `read`; full-surface only; binding: `operation`)
 
 ### Node stage and commit
 
@@ -145,7 +145,7 @@ direct-neighbor traversal.
 - `GET /nodes/{node_id}/tree` -> `flywheel_get_node_tree`
 - `GET /nodes/{node_id}/ancestry` -> `flywheel_get_node_ancestry`
 - `GET /nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
-- `GET /nodes/{node_id}/audit` -> `flywheel_list_audit`
+- `GET /admin/nodes/{node_id}/audit` -> `flywheel_admin_nodes_audit_list` (admin only)
 
 ### Node stage and commit
 

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