@paradigma-inc/flywheel 0.1.60 → 0.1.72

package/README.md

@@ -14,21 +14,40 @@ One-shot installer (macOS and Linux):
 curl -fsSL https://flywheel.paradigma.inc/install | sh
 ```
 
-The script runs `npm install -g @paradigma-inc/flywheel@latest` followed by
-`flywheel setup --mode cli`. You can read the full source at the same URL
-without piping to `sh`.
+The script installs `@paradigma-inc/flywheel@latest` into the managed user
+prefix `${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}`, adds a marked PATH block
+when needed, and then runs guided `flywheel setup` through the installed binary.
+In an interactive terminal, setup asks whether you want MCP host setup or
+CLI-only setup. You can read the full source at the same URL without piping to
+`sh`.
 
 Prefer the two-step npm recipe? It still works:
 
 ```bash
-# --mode cli — installs the flywheel command, used by both you and your AI host
-npm install -g @paradigma-inc/flywheel@latest && flywheel setup --mode cli
+# --mode cli: direct flywheel command setup without MCP host wiring
+FLYWHEEL_INSTALL_PREFIX="${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}"
+npm install -g --prefix "$FLYWHEEL_INSTALL_PREFIX" @paradigma-inc/flywheel@latest
+export PATH="$FLYWHEEL_INSTALL_PREFIX/bin:$PATH"
+"$FLYWHEEL_INSTALL_PREFIX/bin/flywheel" setup --mode cli
 ```
 
-On Windows (PowerShell), use `;` instead of `&&`:
+Persist that PATH line in your shell profile if you use the manual recipe; the
+curl installer does this idempotently with a marked Flywheel-owned block.
+
+On Windows (PowerShell), use a user-owned prefix:
 
 ```powershell
-npm install -g @paradigma-inc/flywheel@latest; flywheel setup --mode cli
+$prefix = "$env:USERPROFILE\.local"
+npm install -g --prefix $prefix @paradigma-inc/flywheel@latest
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+if (($userPath -split ";") -notcontains $prefix) {
+  $nextUserPath = if ($userPath) { "$prefix;$userPath" } else { $prefix }
+  [Environment]::SetEnvironmentVariable("Path", $nextUserPath, "User")
+}
+if (($env:Path -split ";") -notcontains $prefix) {
+  $env:Path = "$prefix;$env:Path"
+}
+& "$prefix\flywheel.cmd" setup --mode cli
 ```
 
 Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
@@ -46,17 +65,19 @@ One-shot uninstaller (macOS and Linux):
 curl -fsSL https://flywheel.paradigma.inc/uninstall | sh
 ```
 
-The script removes Flywheel MCP entries, bundled skills, the global
-`@paradigma-inc/flywheel` package, the `flywheel` binary, default CLI
-config/profiles under `~/.config/flywheel-cli`, and the local runtime cache
-under `~/.flywheel`. It does not delete remote Flywheel account data, nodes,
-artifacts, billing data, GitHub connections, or other remote resources.
+The script removes Flywheel MCP entries, bundled skills, the managed-prefix
+`@paradigma-inc/flywheel` package, the `flywheel` binary, installer-owned PATH
+block, default CLI config/profiles under `~/.config/flywheel-cli`, and the local
+runtime cache under `~/.flywheel`. It does not delete remote Flywheel account
+data, nodes, artifacts, billing data, GitHub connections, or other remote
+resources.
 
 Manual fallback:
 
 ```bash
-npx --yes @paradigma-inc/flywheel@latest uninstall --yes --scope all
-npm uninstall -g @paradigma-inc/flywheel
+FLYWHEEL_INSTALL_PREFIX="${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}"
+"$FLYWHEEL_INSTALL_PREFIX/bin/flywheel" uninstall --yes --scope all
+npm uninstall -g --prefix "$FLYWHEEL_INSTALL_PREFIX" @paradigma-inc/flywheel
 rm -rf "$HOME/.config/flywheel-cli" "$HOME/.flywheel"
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.60",
+  "version": "0.1.72",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [
@@ -25,7 +25,9 @@
     "open": "^10.2.0",
     "ora": "^9.0.0",
     "picocolors": "^1.1.1",
-    "skills": "1.4.7"
+    "skills": "1.4.7",
+    "string-width": "^8.2.0",
+    "wrap-ansi": "^10.0.0"
   },
   "repository": {
     "type": "git",

package/skills/flywheel/SKILL.md

@@ -25,7 +25,7 @@ If the request is ambiguous, default to experiment-design guidance before platfo
 This skill supports both Flywheel install modes:
 
 - **`--mode mcp` install**: route via [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md); tool calls take the form `flywheel_<tool>` (e.g., `flywheel_commit_node`).
-- **`--mode cli` install**: `setup --mode cli` configures runtime credentials, then route via [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md); tool calls take the form `flywheel <command>` (e.g., `flywheel nodes:commit`). Prerequisite for bare-binary routing: `npm install -g @paradigma-inc/flywheel`.
+- **`--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.
 
 When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
 
@@ -67,5 +67,6 @@ Choose one primary file first, then add at most one supporting file only if need
   known leases (leases acquired in the current run or explicitly selected by
   the user).
 - When unknown active leases are present, report and skip by default.
-- Use account-wide release (`flywheel_compute_release_all`) only when the user
-  explicitly asks for account-wide cleanup.
+- Use `flywheel_compute_release_all` for token-scoped bulk cleanup with the
+  active `lease_control_token`; add `force=true` only when the user explicitly
+  asks for account-wide cleanup.

package/skills/flywheel/getting-started/flywheel-quickstart.md

@@ -3,19 +3,19 @@
 Install Flywheel in your MCP host with:
 
 ```bash
-npx @paradigma-inc/flywheel setup
+npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
 If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
 
 ```bash
-npx @paradigma-inc/flywheel uninstall
-npx @paradigma-inc/flywheel setup
+npx --yes @paradigma-inc/flywheel uninstall
+npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
 If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.
 
-If your MCP host is not supported by `npx @paradigma-inc/flywheel setup`, use manual host configuration:
+If your MCP host is not supported by `npx --yes @paradigma-inc/flywheel setup --mode mcp`, use manual host configuration:
 
 - URL: `https://flywheel.paradigma.inc/mcp-server`
 - Header: `Authorization: Bearer <YOUR_MCP_API_KEY>`

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

@@ -29,7 +29,7 @@ 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 filters (owners/writers/visibility) and projection control (`core`, `topology`, `full`).
+- `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.
@@ -38,7 +38,7 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel tags:create` (mutating; scopes: `write`; HTTP: `POST /nodes/{root_node_id}/tags`; MCP equivalent: `flywheel_create_node_tag`): Create a reusable tag on a graph root.
 - `flywheel tags:update` (mutating; scopes: `write`; HTTP: `PATCH /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_update_node_tag`): Update a tag definition.
 - `flywheel tags:delete` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{root_node_id}/tags/{tag_id}`; MCP equivalent: `flywheel_delete_node_tag`): Delete a tag definition from the graph.
-- `flywheel tags:assign` (mutating; scopes: `write`; HTTP: `PUT /nodes/{node_id}/tags`; MCP equivalent: `flywheel_set_node_tag_assignments`): Assign or clear tags on a node (atomic replace; `--tag_ids` accepts a JSON array).
+- `flywheel 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.
@@ -50,18 +50,20 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel nodes:stage:lease:acquire` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/acquire`; MCP equivalent: `flywheel_acquire_stage_lease`): Acquire an edit lease for an existing node.
 - `flywheel nodes:stage:lease:heartbeat` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; MCP equivalent: `flywheel_heartbeat_stage_lease`): Heartbeat an active node stage lease.
 - `flywheel nodes:stage:lease:release` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; MCP equivalent: `flywheel_release_stage_lease`): Release a node stage lease.
-- `flywheel nodes:commit` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; MCP equivalent: `flywheel_commit_node`): Commit staged changes to an existing node under an active stage lease (`--stage_session_id`, `--base_committed_revision`, `--staged_payload` required).
-- `flywheel nodes:branch` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; MCP equivalent: `flywheel_branch_node`): Create a child branch from a node (`--expected_revision` required).
+- `flywheel nodes: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. 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.
+- `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`.
 
 ### 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 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).
@@ -75,7 +77,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. Pass the same `--compute_grant_id` you will use for acquire when using grant-backed compute.
+- `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).
@@ -83,21 +85,21 @@ The families below mirror `flywheel-mcp-tool-map.md` and list the canonical CLI
 - `flywheel approval-sessions:list` (read; scopes: `compute`; HTTP: `GET /approval-sessions`; MCP equivalent: `flywheel_list_approval_sessions`): List approval sessions visible to the current user.
 - `flywheel approval-sessions:expire` (mutating; scopes: `compute`; HTTP: `POST /approval-sessions/expire`; MCP equivalent: `flywheel_expire_approval_session`): Expire the current compute-grant approval session context without releasing active leases.
 - `flywheel compute-grants:request-approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; MCP equivalent: `flywheel_request_compute_grant_approval`): Request compute-grant approval; branch on response status (`already_approved`, `approval_required`, `insufficient_credits`).
-- `flywheel compute-grants:list` (read; scopes: `compute`; HTTP: `GET /compute/grants`; MCP equivalent: `flywheel_list_compute_grants`): List active/exhausted compute grants available to the user. Restrict by `--approval_session_id` to inspect session-bound grants.
+- `flywheel 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 a campaign budget (partial; any `--key=value` becomes a field).
+- `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 all active leases in current `lease_control_token` scope; pass `--force` for explicit account-wide cleanup.
+- `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.
 
 ### Contract, audit, and export
 
 - (no CLI equivalent; MCP equivalent: `flywheel_get_contract`): MCP contract introspection is MCP-only. In `--mode cli` install, treat each command's `flywheel help <command>` output as the canonical per-command contract reference.
 - (no CLI equivalent; MCP equivalent: `flywheel_get_contract_section`): Same as above.
-- `flywheel export:subgraph` (read; scopes: `read`; HTTP: `POST /export`; MCP equivalent: `flywheel_export_subgraph`): Export a subgraph snapshot.
-- `flywheel import:subgraph` (mutating; scopes: `write`; HTTP: `POST /import`; MCP equivalent: `flywheel_import_subgraph`): Import graph JSON into new node records. Pass `--normalize_cycles=true` to drop cycle/self-loop edges; default rejects cyclic payloads.
+- `flywheel 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.
@@ -132,8 +134,8 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 
 ### Compute policy and budgets (CLI-only)
 
-- `flywheel compute:policy:get` (read; scopes: `compute`): Read compute budget policy for a node.
-- `flywheel compute:policy:set` (mutating; scopes: `compute`): Update compute budget policy for a node (partial).
+- `flywheel admin:compute:policy:get` (admin-only read; scopes: `compute`): Read compute budget policy for a node.
+- `flywheel admin:compute:policy:set` (admin-only mutating; scopes: `compute`): Update explicit compute policy fields such as `--hard_cap_cents`, `--managed_compute_enabled`, `--provider_filters`, `--allowed_offer_ids`, `--preferred_offer_ids`, and `--auto_shutdown_idle_seconds`.
 - `flywheel compute:budgets` (read; scopes: `compute`): List budget grants visible for a node context.
 - `flywheel machines:list` (read; scopes: `compute`): List your managed compute leases.
 
@@ -155,13 +157,15 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel account:emails:remove` (mutating; scopes: `write`): Remove an email alias from your account.
 - `flywheel account:emails:set-primary` (mutating; scopes: `write`): Set your primary email address.
 
+Account merge, detach, and email mutation commands are browser-session-bound. API-key-only invocations fail locally with `session_auth_required` and a Web settings deep link (`/app?settings=user`).
+
 ### Credits and billing
 
 - `flywheel credits:transactions` (read; scopes: `read`): View paginated credit transactions.
 - `flywheel credits:usage` (read; scopes: `read`): Feature-based usage breakdown over a window.
-- `flywheel credits:purchase` (mutating; scopes: `write`): Create a Stripe checkout session for a one-time purchase.
-- `flywheel credits:subscribe` (mutating; scopes: `write`): Create a Stripe checkout session for a subscription.
-- `flywheel credits:billing-portal` (mutating; scopes: `write`): Open the Stripe billing portal for the current user.
+- `flywheel credits:purchase` (mutating; scopes: `write`): Create a Stripe checkout session for a one-time purchase and return `browser_flow_required` with the browser URL.
+- `flywheel credits:subscribe` (mutating; scopes: `write`): Create a Stripe checkout session for a subscription and return `browser_flow_required` with the browser URL.
+- `flywheel credits:billing-portal` (mutating; scopes: `write`): Open the Stripe billing portal for the current user and return `browser_flow_required` with the browser URL.
 - `flywheel credits:subscription` (read; scopes: `read`): View your subscription status.
 - `flywheel credits:referral` (read; scopes: `read`): View your referral code and status.
 - `flywheel credits:referral:claim` (mutating; scopes: `write`): Claim referral rewards using a code.
@@ -169,49 +173,49 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 ### Integrations
 
 - `flywheel github:status` (read; scopes: `read`): Check GitHub connection status.
-- `flywheel github:link` (mutating; scopes: `write`): Link a GitHub installation ID to your account.
+- `flywheel github:link` (mutating; scopes: `write`): Start the GitHub App install/link browser flow. Does not accept callback installation parameters.
 - `flywheel github:refresh-repos` (mutating; scopes: `write`): Refresh the list of accessible repositories.
 - `flywheel github:disconnect` (mutating; scopes: `write`): Disconnect GitHub from your account.
 - `flywheel integrations:status` (read; scopes: `read`): Check integration connection status (W&B, Hugging Face).
-- `flywheel integrations:wandb:set` (mutating; scopes: `write`): Store a Weights & Biases API key.
+- `flywheel integrations:wandb:set` (mutating; scopes: `write`): Store a Weights & Biases API key. Prefer `--api_key_env WANDB_API_KEY`.
 - `flywheel integrations:wandb:remove` (mutating; scopes: `write`): Remove your W&B credential.
-- `flywheel integrations:huggingface:set` (mutating; scopes: `write`): Store a Hugging Face access token.
+- `flywheel integrations:huggingface:set` (mutating; scopes: `write`): Store a Hugging Face access token. Prefer `--token_env HF_TOKEN`; the CLI sends it to the API as `access_token`.
 - `flywheel integrations:huggingface:remove` (mutating; scopes: `write`): Remove your Hugging Face credential.
 
 ### API keys
 
-- `flywheel api-keys:list` (read; scopes: `read`): List your API keys.
+- `flywheel api-keys:list` (read; scopes: `read`): List your API keys with bounded pagination (`--limit`, `--offset`); default output is a compact table and `--format=json` preserves the response envelope.
 - `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. -->
+  <!-- FLY-416: removed — device flow replaces legacy /setup-exchange. -->
+  <!-- - `flywheel api-keys:setup-exchange:create` (mutating; scopes: `write`): Start browser-assisted setup exchange. -->
+  <!-- - `flywheel api-keys:setup-exchange:redeem` (mutating; scopes: `write`): Redeem a setup exchange token into a raw API key. -->
 
 ## Practical Command Sequences
 
 ### List Owned Nodes
 
-1. `flywheel nodes:list --owners=me --projection=core`.
+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> --expected_revision=<rev>`: Acquire a session-scoped stage lease.
-3. `flywheel nodes:commit --node_id=<id> --stage_session_id=<sid> --base_committed_revision=<rev> --staged_payload=@payload.json`: Commit once terminal and contract-complete.
+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-grants:request-approval --acquire_node_id=<id> --budget_source=user`: Request budget approval. Branch on response `status` (`already_approved` | `approval_required` | `insufficient_credits`).
-3. If `approval_required`: present `approval_url` to the user, then `flywheel compute-grants:list --status=active --approval_session_id=<sid>` to fetch the active grant.
-4. `flywheel compute:options --node_id=<id> --compute_grant_id=<gid>`: List allowed offers; pick the exact `offer_id`.
+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> --file=results.json`: One-shot upload (or use the prepare/finalize split for streaming).
-10. `flywheel nodes:commit --node_id=<id> ...`: Commit terminal empirical node.
+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.
 
 ## Runtime Guidance
 
@@ -220,8 +224,8 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel nodes:stage:lease:acquire`, `flywheel nodes:stage:lease:heartbeat`, `flywheel nodes:stage:lease:release` coordinate session-scoped local staged edits for an existing node before commit.
 - `flywheel campaign:snapshot` reads the current derived campaign state for a node's root campaign instead of inferring standings from freeform text.
 - `flywheel nodes:sharing:get` verifies sharing state after sharing writes before reporting private/shared/public state.
-- `flywheel tags:assign` accepts `--tag_ids` as a JSON array of strings; omitting `--tag_ids` clears all assignments.
-- `flywheel nodes:list` accepts canonical filters as repeated flags or comma-separated lists for `--owners`, `--writers`, `--visibility`.
+- `flywheel 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 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`).
@@ -235,11 +239,11 @@ These commands have no MCP counterpart. They cover auth/profile management, acco
 - `flywheel artifacts:upload:finalize` finalizes a staged artifact batch and appends all uploaded artifacts in one revision bump.
 - `flywheel artifacts:delete` removes an accidental/obsolete node artifact.
 - `flywheel artifacts:list`, `flywheel artifacts:get` inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
-- `flywheel nodes:commit-new`, `flywheel nodes:commit` publish the caller's full staged payload for an existing node once terminal and contract-complete; commit on an existing node requires an active stage lease and explicit `--base_committed_revision`.
+- `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`.
 
 ## Admin only (FLY-359)
 
-These commands require `FLYWHEEL_ADMIN_KEY` in the environment (forwarded as the `X-Admin-Key` header) or an authenticated `@paradigma.inc` session. The server rejects all other callers with 401/403. 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, 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.
 
 - `flywheel admin:graphs:list` — list every root-node graph across all users. Filters: `--tag-id`, `--kind`, `--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.

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

@@ -57,7 +57,7 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 - `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/heartbeat`; full-surface only): Refresh the active stage lease for the current editing session.
 - `flywheel_release_stage_lease` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/stage/lease/release`; full-surface only): Release the active stage lease for the current editing session.
 - `flywheel_commit_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/commit`; core surface): Commit an existing node by publishing the caller's staged payload under an active stage lease.
-- `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; full-surface only): Create a child branch node with optimistic locking (`expected_revision` required).
+- `flywheel_branch_node` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/branch`; full-surface only): Create a child branch node with optimistic locking (`expected_revision` required); on 409, reread the node and retry with the current revision.
 - `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
 - `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/add`; full-surface only): Attach an additional parent edge to an existing node (keeps node identity, validates against cycles).
 - `flywheel_remove_parent` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/parents/remove`; full-surface only): Detach one parent edge from a node without deleting the node.
@@ -68,6 +68,8 @@ Flywheel is a graph-based system for tracking research work, decisions, and evid
 
 - `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/prepare`; core surface): Prepare one or more raw-file artifact uploads (returns batch token + signed upload URLs). Upload must send raw file bytes to the returned URLs (do not upload JSON metadata wrappers).
 - `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/artifacts/uploads/finalize`; core surface): Finalize a prepared artifact upload batch and append all staged artifacts to the node in one revision bump.
+- `flywheel_resolve_remote_artifact` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/remote-artifacts/resolve`; core surface): Resolve and materialize a public HTTPS JSON remote artifact for a node, using the cached artifact when it is still fresh.
+- `flywheel_refresh_remote_artifact` (mutating; scopes: `write`; HTTP: `POST /nodes/{node_id}/remote-artifacts/refresh`; core surface): Force refresh and materialize a public HTTPS JSON remote artifact for a node.
 - `flywheel_list_artifacts` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): List node artifacts.
 - `flywheel_get_artifact` (read; scopes: `read`; HTTP: `tool-mediated`; core surface): Get one artifact by id.
 - `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
@@ -94,8 +96,9 @@ Hook workflow-if contract (first version):
 - Canonical none-artifact expression: `not: { any_artifact: ... }`.
 - Run cardinality is fixed at one run per `(hook_id, event_id)` (no artifact fanout).
 - Submission-only matching is typically `any_artifact.field=metadata.role` with `eq: submission`.
-- Workflow step types include `flywheel/http_request@v1`, `flywheel/http_poll@v1`, `flywheel/json_extract@v1`, `flywheel/load_artifact@v1`, and `flywheel/upsert_artifact@v1`.
+- Workflow step types include `flywheel/http_request@v1`, `flywheel/http_poll@v1`, `flywheel/json_extract@v1`, `flywheel/load_artifact@v1`, `flywheel/upsert_artifact@v1`, and `flywheel/add_node_tags@v1`.
 - `flywheel/upsert_artifact@v1` selectors are authored under `with.match`; `match.metadata` is subset matching and ambiguous selectors fail terminally.
+- `flywheel/add_node_tags@v1` adds ordinary root graph tags to a target node and preserves existing tag assignments; one-only tags are rejected in v1.
 
 ### Executions
 
@@ -114,20 +117,20 @@ Hook workflow-if contract (first version):
 - `flywheel_list_approval_sessions` (read; scopes: `compute`; HTTP: `GET /approval-sessions`; core surface): List approval sessions visible to the current user.
 - `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /approval-sessions/expire`; core surface): Expire the current compute-grant approval session context without releasing active leases.
 - `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Request budget approval context before managed compute acquisition; branch on response status.
-- `flywheel_list_compute_grants` (read; scopes: `compute`; HTTP: `GET /compute/grants`; core surface): List active/exhausted compute grants available to the current user.
+- `flywheel_list_compute_grants` (read; scopes: `compute`; HTTP: `GET /compute/grants`; core surface): List active/expired compute grants available to the current user.
 - `flywheel_list_campaign_budgets` (read; scopes: `compute`; HTTP: `GET /nodes/{root_node_id}/campaign-budgets`; full-surface only): List campaign compute budgets for a campaign root. Organizer-only management view.
 - `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_release` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Asynchronously release one managed compute lease by lease_id within the current lease_control_token scope.
-- `flywheel_compute_release_all` (mutating; scopes: `compute`; HTTP: `tool-mediated`; core surface): Asynchronously release active managed compute leases in the current lease_control_token scope; set force=true for explicit account-wide cleanup for the current user.
+- `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.
 
 ### Contract, audit, and export
 
 - `flywheel_get_contract` (read; scopes: `read`; HTTP: `GET /mcp/contract`; core surface): Return Flywheel MCP contract overview (scopes, write safety, operation catalog, and section index).
 - `flywheel_get_contract_section` (read; scopes: `read`; HTTP: `GET /mcp/contract/sections/{section_id}`; core surface): Return one contract section by section_id (for example `graph` or `campaign/template_v1`).
-- `flywheel_export_subgraph` (read; scopes: `read`; HTTP: `POST /export`; full-surface only): Export selected graph/subgraph nodes as JSON.
+- `flywheel_export_subgraph` (read; scopes: `read`; HTTP: `POST /export`; full-surface only): Export selected graph/subgraph nodes as JSON. Set `include_descendants=true` to expand each requested root to visible descendants, bounded by `max_nodes`.
 - `flywheel_import_subgraph` (mutating; scopes: `write`; HTTP: `POST /import`; full-surface only): Import graph/subgraph JSON payload into new node IDs. Set normalize_cycles=true to drop cycle/self-loop edges; default rejects cyclic payloads.
 - `flywheel_summarize_node_tree` (read; scopes: `read`; HTTP: `GET /nodes/{node_id}/summary`; full-surface only): Summarize a node tree using node fields only.
 - `flywheel_export_summary` (read; scopes: `read`; HTTP: `POST /export-summary`; full-surface only): Generate markdown summary for selected nodes.

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

@@ -3,14 +3,14 @@
 Use the setup wizard:
 
 ```bash
-npx @paradigma-inc/flywheel setup
+npx --yes @paradigma-inc/flywheel setup --mode mcp --claude
 ```
 
 If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
 
 ```bash
-npx @paradigma-inc/flywheel uninstall
-npx @paradigma-inc/flywheel setup
+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.

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

@@ -3,14 +3,14 @@
 Use the setup wizard:
 
 ```bash
-npx @paradigma-inc/flywheel setup
+npx --yes @paradigma-inc/flywheel setup --mode mcp --codex
 ```
 
 If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
 
 ```bash
-npx @paradigma-inc/flywheel uninstall
-npx @paradigma-inc/flywheel setup
+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.

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

@@ -9,19 +9,20 @@ MCP enables you to natively connect and authenticate Flywheel to any compatible
 Simply run:
 
 ```bash
-npx @paradigma-inc/flywheel setup
+npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
-`setup` defaults to `--mode mcp`, which wires the Flywheel MCP server into the
-selected hosts and installs the bundled Flywheel skills. To install the skills
-without writing any MCP host config, run `setup --mode cli --install-skill`
-instead.
+`--mode mcp` wires the Flywheel MCP server into the selected hosts and installs
+the bundled Flywheel skills. In an interactive terminal, setup can prompt for a
+mode; in non-interactive shells, pass `--mode mcp` or `--mode cli` explicitly.
+To install the skills without writing any MCP host config, run
+`npx --yes @paradigma-inc/flywheel setup --mode cli --install-skill` instead.
 
 If the user is on a remote shell (for example SSH'd into a server), loopback
 callback URLs resolve on the wrong machine. Use device auth instead:
 
 ```bash
-npx @paradigma-inc/flywheel setup --auth-mode device
+npx --yes @paradigma-inc/flywheel setup --mode mcp --auth-mode device
 ```
 
 `--auth-mode device` prints a Flywheel device-auth URL and a short setup code;
@@ -30,8 +31,8 @@ the user approves in a browser and the CLI polls until the API key is issued.
 ## Reinstall / cleanup
 
 ```bash
-npx @paradigma-inc/flywheel setup
-npx @paradigma-inc/flywheel uninstall
+npx --yes @paradigma-inc/flywheel uninstall
+npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
 `uninstall` removes Flywheel MCP entries from host config files.

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

@@ -1,6 +1,6 @@
 # Other MCP hosts
 
-If your host is not currently supported by `npx @paradigma-inc/flywheel setup`, you can still connect manually.
+If your host is not currently supported by `npx --yes @paradigma-inc/flywheel setup --mode mcp`, you can still connect manually.
 
 1. In the Flywheel WebUI, open **Settings**, go to the **User** tab, expand **MCP API keys**, and click **Create key**.
 2. Copy the key immediately (it is shown once).

package/skills/flywheel/setting-up-flywheel/updating-flywheel-mcp.md

@@ -3,8 +3,8 @@
 For most users, reinstall / cleanup is:
 
 ```bash
-npx @paradigma-inc/flywheel setup
-npx @paradigma-inc/flywheel uninstall
+npx --yes @paradigma-inc/flywheel uninstall
+npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
 `uninstall` removes Flywheel MCP entries from host config files.
@@ -22,8 +22,8 @@ npx skills experimental_sync --agent codex -y
 If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
 
 ```bash
-npx @paradigma-inc/flywheel uninstall
-npx @paradigma-inc/flywheel setup
+npx --yes @paradigma-inc/flywheel uninstall
+npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
 If your previous install used a server name different from `flywheel`, pass `--name <old-name>` to uninstall that specific entry.

package/skills/flywheel-auto/SKILL.md

@@ -16,7 +16,7 @@ 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: `npm install -g @paradigma-inc/flywheel`.
+- **`--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.
 
 When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
 
@@ -99,8 +99,9 @@ Before execution, recover or establish these inputs:
    - Route additional viable branches sequentially when there are more than `k` worthwhile directions.
    - After each resolved node, refresh the lookahead so the graph remains `n` hops ahead.
    - Release managed compute when a branch is done. Default to releasing only
-     known leases. Use `flywheel_compute_release_all` (MCP) or `flywheel compute:release-all` (CLI) only when the user
-     explicitly requests account-wide cleanup.
+     known leases. Use release-all with the active `lease_control_token` for
+     token-scoped bulk cleanup; add `force=true` (MCP) or `--force --yes` (CLI)
+     only when the user explicitly requests account-wide cleanup.
    - Stop only when the graph-local terminal condition says to stop, such as: objective met, budget exhausted, or no non-redundant frontier branch is likely to produce enough decision-relevant information to justify the remaining budget and duplication risk.
    - If stopping because no non-redundant frontier branch is worth pursuing, record a per-candidate rejection rationale in control node `content` before termination.
    - Before every termination path, persist `stop_reason` in control node `content` as one of: `budget_exhausted`, `objective_met`, `no_viable_branch`, `user_cancelled`, `runtime_error`.