@paradigma-inc/flywheel 0.1.53 → 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:
@@ -38,6 +57,33 @@ Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:
 npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
 ```
 
+## Uninstall
+
+One-shot uninstaller (macOS and Linux):
+
+```bash
+curl -fsSL https://flywheel.paradigma.inc/uninstall | sh
+```
+
+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
+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"
+```
+
+With `--yes --scope all` and no host selectors, `flywheel uninstall` targets
+every supported host.
+
 ## Setup Modes
 
 ```bash
@@ -156,15 +202,18 @@ npx --yes @paradigma-inc/flywheel setup --mode mcp --install-skill \
 
 ## Host Matrix
 
-| Host         | MCP wiring (`--mode mcp`) | CLI-mode bundled skill install (`--mode cli`) |
-| ------------ | ------------------------- | --------------------------------------------- |
-| Claude Code  | yes                       | yes                                           |
-| OpenCode     | yes                       | yes                                           |
-| Codex        | yes                       | yes                                           |
-| Cursor       | yes                       | yes                                           |
-| Pi (pi-mono) | yes                       | yes                                           |
-| OpenClaw     | yes                       | yes                                           |
-| Hermes Agent | yes                       | no (MCP-only host)                            |
+| Host                          | MCP wiring (`--mode mcp`) | CLI-mode bundled skill install (`--mode cli`) |
+| ----------------------------- | ------------------------- | --------------------------------------------- |
+| Claude Code                   | yes                       | yes                                           |
+| Cursor                        | yes                       | yes                                           |
+| Universal (`.agents/skills`)  | no (skill-only)           | yes                                           |
+| Antigravity (`.agent/skills`) | no (skill-only)           | yes                                           |
+| OpenCode                      | yes                       | yes                                           |
+| Codex                         | yes                       | yes                                           |
+| Gemini CLI                    | yes                       | yes                                           |
+| Pi (pi-mono)                  | yes                       | yes                                           |
+| OpenClaw                      | yes                       | yes                                           |
+| Hermes Agent                  | yes                       | no (MCP-only host)                            |
 
 CLI mode handling for Hermes Agent:
 
@@ -172,6 +221,88 @@ CLI mode handling for Hermes Agent:
 - mixed supported + unsupported selection: command continues for supported
   hosts and reports skipped unsupported hosts
 
+### New flags (ctx7 alignment)
+
+These flags align the `flywheel setup` surface with the `npx ctx7 setup`
+convention while keeping every Flywheel-specific flag intact. They are
+additive: existing invocations continue to behave as before.
+
+#### `--oauth`
+
+Writes an MCP config that omits the `Authorization` header and delegates
+authentication to the IDE's MCP 2.0 OAuth discovery flow. No API key is
+minted, stored, or transmitted by `flywheel setup` itself.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode mcp --claude --oauth --project
+```
+
+The resulting `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "flywheel": {
+      "type": "http",
+      "url": "https://flywheel.paradigma.inc/mcp-server"
+    }
+  }
+}
+```
+
+The IDE must support MCP 2.0 OAuth discovery (Claude Code, Cursor, and
+Gemini CLI currently do). On the first MCP tool call the IDE hits
+`/mcp-server`, follows the `WWW-Authenticate` hint to
+`/.well-known/oauth-protected-resource`, registers itself via
+`/oauth/register`, completes the browser flow, and from then on manages
+its own refresh tokens. No API key ever touches the user's filesystem.
+
+`--api-key` and `--oauth` are mutually exclusive; passing both produces a
+usage error (`exit 2`).
+
+If a previous `flywheel setup` run wrote an MCP entry with an
+`Authorization` header against the same URL, re-running with `--oauth`
+will classify that entry as matching and leave the header in place. To
+rewrite the config to drop the header, first run
+`flywheel uninstall --<host> --project` and then re-run setup with
+`--oauth`.
+
+#### `--gemini`
+
+Registers Flywheel as an MCP server for Gemini CLI at
+`.gemini/settings.json` (project) or `~/.gemini/settings.json` (global).
+Gemini CLI uses the `mcpServers.flywheel.httpUrl` key (not `url`); when
+`--api-key <key>` is supplied, the setup writes a `Bearer <key>`
+`Authorization` header. With `--oauth` the header is omitted.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode mcp --gemini --project --api-key <token>
+```
+
+#### `--universal`
+
+Skill-only target that writes Flywheel's bundled skills into
+`./.agents/skills/<skill-name>/` (project) or `~/.agents/skills/<skill-name>/`
+(global). Writes no MCP server config and no agent-specific rules. Useful
+for toolchains that read the conventional `.agents/skills/` layout without
+needing a Flywheel MCP binding. Requires `--mode cli` explicitly and is
+never auto-detected; opt-in only.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli --universal --project
+```
+
+#### `--antigravity`
+
+Same skill-only shape as `--universal` but targets
+`./.agent/skills/<skill-name>/` (project) or `~/.agent/skills/<skill-name>/`
+(global) — note the singular `.agent` directory. Writes no MCP server
+config. Requires `--mode cli` explicitly and is never auto-detected.
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli --antigravity --project
+```
+
 ## Public Update Flow
 
 After a new release:
@@ -200,7 +331,8 @@ flags.
 
 - `setup`: setup flow with explicit mode routing.
 - `uninstall`: removes Flywheel MCP entries from host configs and removes
-  bundled skills from supported hosts.
+  bundled skills from supported hosts. Use the one-shot uninstaller above for a
+  full local cleanup, including the global npm package and default local state.
 
 ```bash
 npx --yes @paradigma-inc/flywheel uninstall

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.53",
+  "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,7 +239,15 @@ 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 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.
+- `flywheel admin:graphs:export:stream` — stream canonical graph JSON for many graphs as NDJSON (one page per call, `--out=<file>` to write to disk). Filters match `admin:graphs:list`.
 
 ## See Also
 

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.
@@ -194,3 +197,11 @@ Hook workflow-if contract (first version):
 - `flywheel_delete_artifact`: remove an accidental/obsolete node artifact.
 - `flywheel_list_artifacts`, `flywheel_get_artifact`: inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
 - `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.
+
+### Admin only (FLY-359)
+
+These tools require an `@paradigma.inc`-authenticated MCP session **or** a valid `X-Admin-Key` header sent on the MCP HTTP request. The MCP streamable HTTP mount reads `X-Admin-Key` from the inbound request and forwards it through to the in-process `/admin/graphs*` call; on admin paths the proxy also suppresses the session bearer to sidestep the API-key route allowlist check. `require_paradigma_admin` then grants access based on the admin key. The routes are omitted from the public OpenAPI schema and from the API-key allowlist.
+
+- `flywheel_admin_list_graphs`: list every root-node graph across all users. Filters: `tag_id`, `kind`, `owner_user_id`, `created_after`, `created_before`, `cursor`, `page_size` (1..200). Returns `{graphs, has_more, next_cursor}`.
+- `flywheel_admin_export_graph`: export one graph by `root_node_id` as canonical JSON (`{version, exported_at, node_count, nodes}`). Bypasses per-caller node-visibility checks by design.
+- `flywheel_admin_export_graphs_stream`: batch-export one page of canonical graph JSON payloads matching the filter; iterate pages via `next_cursor`. The NDJSON HTTP endpoint (`GET /admin/graphs/export.jsonl`) is the CLI-first streaming surface; the MCP tool materializes a page to fit the RPC model.

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.