@paradigma-inc/flywheel 0.1.111 → 0.1.134

package/skills/flywheel/setting-up-flywheel/how-can-i-get-an-authorized-client_id-for-the-oauth-flow.md

@@ -1,8 +1,8 @@
-# FAQ: How Can I Get an Authorized `client_id` for the OAuth Flow?
+# FAQ: How Can I Use a `client_id` for the OAuth Flow?
 
-Flywheel uses [OAuth Client ID Metadata Documents](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents).
-Your public HTTPS metadata-document URL is the OAuth `client_id`; there is no
-separate registration request.
+Flywheel uses [OAuth Client ID Metadata Documents](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration).
+Your public HTTPS metadata-document URL is the OAuth `client_id`. There is no
+Dynamic Client Registration endpoint and no private enrollment or allowlist.
 
 First, query our OAuth authorization-server metadata:
 
@@ -31,3 +31,11 @@ and validates the document during authorization and token exchange. The requeste
 redirect URI must exactly match one listed value; it may be omitted only when the
 document lists exactly one redirect URI. Do not put a client secret in the
 document.
+
+The first connection requires authenticated consent and PKCE. Persist the issued
+access and single-use refresh credentials. Reuse the access credential while it
+is valid and rotate the refresh credential instead of restarting authorization.
+Flywheel skips repeat consent only for the same user, exact client identity and
+selected redirect, active grant, and equal-or-narrower scopes. A new or changed
+client identity or redirect, scope expansion, expiry, revocation, or disconnect
+requires consent again.

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

@@ -12,11 +12,7 @@ Simply run:
 npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
-`--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.
+`--mode mcp` writes the Flywheel MCP server entry for selected supported hosts. In an interactive terminal, setup can prompt for a mode and offers to install the bundled skills, with installation selected by default. In non-interactive shells, pass `--mode mcp` or `--mode cli` explicitly; MCP setup also requires `--install-skill` to install skills or `--skip-skill` to omit them. `--mode cli --install-skill` installs or refreshes the skills and writes CLI runtime TOML unless every selected host is skill-only (for example, Universal or Antigravity); that selection installs only skills and skips CLI authentication and runtime configuration. CLI mode does not write an MCP server entry. A host selection or detection is required for MCP config; skill-only hosts have no MCP configuration.
 
 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:
@@ -35,7 +31,7 @@ npx --yes @paradigma-inc/flywheel uninstall
 npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
-`uninstall` removes Flywheel MCP entries from host config files.
+`uninstall` removes the selected Flywheel host entries and bundled skills. For a nondefault server name, include the relevant host selector and `--name "<old-name>"`.
 
 ## Web connector hosts (ChatGPT.com / Claude.ai / etc. )
 

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

@@ -1,40 +1,67 @@
 # Other MCP hosts
 
-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).
-3. Add a Flywheel MCP server entry in your host config with:
-   - URL: `https://flywheel.paradigma.inc/mcp-server`
-   - Header: `Authorization: Bearer <YOUR_MCP_API_KEY>`
-
-Example JSON-style host config:
-
-```json
-{
-  "mcpServers": {
-    "flywheel": {
-      "type": "http",
-      "url": "https://flywheel.paradigma.inc/mcp-server",
-      "headers": {
-        "Authorization": "Bearer <YOUR_MCP_API_KEY>"
-      }
-    }
-  }
-}
+For a supported host, let setup write its own configuration:
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode mcp
 ```
 
-Example TOML-style host config:
+Select a supported host with its documented setup option (for example `--codex`, `--claude`, `--cursor`, `--opencode`, `--gemini`, `--pi-mono`, `--hermes-agent`, or `--openclaw`) instead of copying another host's configuration shape.
+
+## Current Codex TOML host configuration
+
+Codex is the supported host with the documented TOML MCP entry. Setup writes it
+to `.codex/config.toml` for project scope or `~/.codex/config.toml` globally:
 
 ```toml
 [mcp_servers.flywheel]
 type = "http"
 url = "https://flywheel.paradigma.inc/mcp-server"
 
-[mcp_servers.flywheel.headers]
+[mcp_servers.flywheel.http_headers]
 Authorization = "Bearer <YOUR_MCP_API_KEY>"
 ```
 
-Different hosts use different field names (`mcpServers`, `mcp_servers`, `mcp.servers`, etc.), but the server URL and `Authorization` bearer header are the key pieces.
+Other supported hosts use their own current JSON or YAML writer; do not infer
+their file path, key names, or entry shape from this Codex example.
+
+## CLI runtime configuration
+
+The runtime CLI uses schema-version-1 TOML at
+`$XDG_CONFIG_HOME/flywheel/config.toml`, or
+`~/.config/flywheel/config.toml` when `XDG_CONFIG_HOME` is unset
+(`%APPDATA%\Flywheel\config.toml` on native Windows). The required top-level
+key is `schema_version = 1`; the other supported configuration is
+`repositories.personal`, `profiles`, and `active_profile`. This is separate
+from MCP host configuration.
+
+For an unsupported MCP host, follow that host's own manual-configuration
+documentation. The Flywheel endpoint is
+`https://flywheel.paradigma.inc/mcp-server`; do not present a guessed
+Flywheel-owned config schema as a portable host contract.
+
+### HTTP hosts without MCP OAuth
+
+For an unsupported host that can use remote HTTP MCP but cannot complete MCP
+OAuth, sign in to the Flywheel web UI, open **Settings → User → MCP API keys**,
+create an MCP API key, and copy its one-time value. Keep that value in the
+host's secret facility when it has one; do not put it in prompts, chat, or logs.
+
+Use the host's documentation for its server-entry and secret/configuration
+shape. Its Flywheel entry needs the endpoint above and this HTTP header:
+
+```text
+Authorization: Bearer <MCP_API_KEY>
+```
+
+Do not infer any other key, transport, file location, or nesting convention
+from the supported-host examples.
 
-Alternative: for any host that supports MCP OAuth, you can use its OAuth connector install flow and set the MCP URL to `https://flywheel.paradigma.inc/mcp-server`. Web connector hosts (for example ChatGPT.com, Claude.ai) commonly use this path. It can be convenient, but it may prompt re-authorization more often than the API key route depending on the host token lifecycle and refresh behavior.
+Alternative: for any host that supports MCP OAuth, use its OAuth connector
+install flow and set the MCP URL to
+`https://flywheel.paradigma.inc/mcp-server`. Web connector hosts (for example
+ChatGPT.com and Claude.ai) commonly use this path. A host that persists access
+and refresh credentials should authorize once, reuse the access credential, and
+rotate the refresh credential without another browser prompt. Reauthorization
+is needed when the host loses its credentials or the grant expires, is revoked,
+or requests changed authority.

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

@@ -1,29 +1,52 @@
 # How to Update Flywheel MCP
 
-For most users, reinstall / cleanup is:
+Update the managed Flywheel package and refresh its discovered local MCP and
+skill artifacts with:
 
 ```bash
-npx --yes @paradigma-inc/flywheel uninstall
-npx --yes @paradigma-inc/flywheel setup --mode mcp
+flywheel update --yes
 ```
 
-`uninstall` removes Flywheel MCP entries from host config files.
+Use `flywheel update --dry-run` to preview the package and local refresh steps,
+or `flywheel update --check` to compare installed and available versions without
+changing files.
+
+If setup was run only through `npx` and there is no persistent `flywheel`
+binary, rerun the latest setup to refresh the selected MCP setup. Choose the
+explicit skill decision that matches the selected host:
 
-If you choose to refresh via `skills experimental_sync` instead of rerunning
-setup, install Flywheel locally in that project first:
+For a host that supports bundled skills, opt in to their refresh:
 
 ```bash
-npm install --save-dev @paradigma-inc/flywheel@latest
-npx skills experimental_sync --agent codex -y
+npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --force --install-skill
 ```
 
-## FAQ: How Do I Migrate from the Previous OAuth-Based MCP Client Setup?
+For a host that supports MCP setup but not this package's skill installer,
+such as Hermes Agent, skip bundled-skill installation:
 
-If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:
+```bash
+npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --force --skip-skill --hermes-agent
+```
+
+For either recipe, pass the existing host selector and scope flags, such as
+`--claude --project` for a project-scoped Claude Code setup, and preserve any
+nondefault server name with `--name`. Without a host selector,
+`--install-skill` uses all detected hosts. This refreshes the selected setup
+without installing a persistent binary.
+
+To remove and recreate MCP setup instead, use:
 
 ```bash
 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.
+`uninstall` removes selected Flywheel MCP entries and bundled skills. For a
+nondefault server name, include the relevant host selector and
+`--name "<old-name>"`; for example, `uninstall --codex --name "<old-name>"`.
+
+## FAQ: How Do I Migrate from the Previous OAuth-Based MCP Client Setup?
+
+For an MCP installation from before April 2026, use the remove-and-recreate
+sequence above to migrate from the previous OAuth setup to API key
+authentication, including the same host, scope, and nondefault-name flags.

package/skills/flywheel-auto/SKILL.md

@@ -15,12 +15,33 @@ If exact tool or field semantics are unclear, load [references/flywheel-mcp-tool
 
 This skill supports both Flywheel install modes:
 
-- **`--mode mcp` install**: route via [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md); tool calls take the form `flywheel_<tool>` (e.g., `flywheel_commit_node`).
-- **`--mode cli` install**: `setup --mode cli` configures runtime credentials, then route via [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md); tool calls take the form `flywheel <command>` (e.g., `flywheel nodes:commit`). Prerequisite for bare-binary routing: run the curl installer with `--mode cli` or use the managed-prefix npm install recipe from the README.
+- **`--mode mcp` install on an MCP-capable host:** setup writes host-specific
+  MCP configuration; use [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md)
+  and the host's `flywheel_<tool>` surface.
+- **`--mode mcp` install on a skill-only host:** setup installs the skill but
+  skips MCP configuration, so no `flywheel_<tool>` surface exists. Route work
+  through a separately configured CLI, subject to the CLI caveat below.
+- **`--mode cli` install:** setup installs skills and writes runtime TOML unless every selected host is skill-only (for example, Universal or Antigravity). A skill-only selection skips CLI authentication and runtime configuration. Use [references/flywheel-cli-tool-map.md](references/flywheel-cli-tool-map.md) and the `flywheel <command>` surface only with a configured CLI.
+
+Configure CLI mode independently. This command prompts for a host in an interactive terminal:
+
+```bash
+npx --yes @paradigma-inc/flywheel setup --mode cli
+```
+
+For noninteractive setup, pass the active host's selector from `npx --yes @paradigma-inc/flywheel setup --help` (for example, `--claude` for Claude Code). Without a selector, prompt-free setup uses all detected hosts. Match the existing project/global scope.
+
+Running setup through `npx` configures settings and skills; it does not install a persistent `flywheel` binary. If `flywheel` is not on `PATH`, replace `flywheel` with `npx --yes @paradigma-inc/flywheel` in every CLI example below and in the linked tool map.
+
+When switching an already configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+
+Pick the route from both install mode and intended destination:
 
-When switching an already-configured host between modes, rerun setup with `--force` (or uninstall first) so prior-mode artifacts are reconciled explicitly.
+- For an identified local repository, select it with `--repo <path>`, `--personal`, or working-directory discovery; use `repo:` operations, local `repo:commit`, and `repo:push` only when publication is requested.
+- For an identified hosted graph, use supported `hosted:` operations directly; do not require a clone or local initialization merely to edit it.
+- If the destination is unknown, ask before writing. A failed local selection never permits a hosted fallback.
 
-The Workflow below cites both the MCP tool name and its CLI equivalent inline at each imperative step. Pick the one matching your install mode.
+MCP payloads and leases are not interchangeable with CLI commits. Follow this skill's [MCP tool map](references/flywheel-mcp-tool-map.md) for the distinct new-node and existing-node requirements. For hosted CLI writes, resolve `<repository-id>` to the intended hosted graph; hosted reads take node selectors, not `--repository-id`.
 
 ## Input Contract
 
@@ -69,15 +90,14 @@ Before execution, recover or establish these inputs:
    - Run the design gate from [references/experiment-design-protocol-autonomous.md](references/experiment-design-protocol-autonomous.md) before the first compute request: confirm objective, decision criterion, evidence plan, budget readiness, and stop-reason recording requirements, even though later continuation decisions become graph-local.
 3. Map each stable page, claim, or concept to a node.
    - For exact node-mutation shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md).
-   - Create a new node with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI) when needed.
-   - Update an existing node with `flywheel_get_node` + `flywheel_acquire_stage_lease` + `flywheel_commit_node` (MCP) or `flywheel nodes:get` + `flywheel nodes:stage:lease:acquire` + `flywheel nodes:commit` (CLI) when continuing work.
+   - On MCP, persist a new canonical node with `flywheel_commit_new_node` and its caller-local ID, parent IDs, and full staged payload. On CLI, follow the selected destination: use `hosted:node:create` only for an identified hosted graph, or `repo:node:create` for an identified local repository.
+   - On MCP, update an existing canonical node by reading it, acquiring the stage lease, then committing the same session/revision with full staged payload. On CLI, use `hosted:node:set` only for an identified hosted graph; local edits remain `repo:` operations until the separate local commit.
 4. Put the primary page markdown or plan rationale in the node body/readme field (`content`).
    - Put claims, rationale, methods, outcomes, and continuation notes in `content`; keep `summary` concise.
 5. Publish supporting files with the artifact upload flow.
    - For exact artifact contract details, load [references/ARTIFACTS.md](references/ARTIFACTS.md).
-   - Use `flywheel_prepare_artifact_uploads` (MCP) or `flywheel artifacts:upload:prepare` (CLI).
-   - Upload raw file bytes to the returned signed URLs.
-   - Call `flywheel_finalize_artifact_uploads` (MCP) or `flywheel artifacts:upload:finalize` (CLI) once all uploads in the batch are staged.
+   - MCP mode uses `flywheel_prepare_artifact_uploads`, uploads raw bytes to the returned signed URLs, then calls `flywheel_finalize_artifact_uploads`.
+   - The direct-hosted CLI artifact helper prepares, uploads, and appends an attachment in one hosted repository commit. It is related to, but does not replace or share, MCP's prepare → raw upload → finalize contract.
    - Keep the artifact filename stable enough to reference from markdown when inline rendering matters.
 6. Add graph structure sparingly.
    - Promote only decision-relevant relationships to edges.
@@ -87,11 +107,11 @@ Before execution, recover or establish these inputs:
    - Depth `n` means plan `n` hops ahead from the currently resolved frontier. Default `n=1`.
    - Width `k` means plan up to `k` distinct non-redundant frontier directions. Default `k=1`.
    - In the flywheel-auto skill, the same `k` also caps concurrent workers pursuing executable frontier nodes.
-   - Keep unresolved plan nodes staged until the corresponding work is resolved.
+   - Persist each frontier node before relying on it for later replanning. Caller-local MCP staging is not durable; commit a new node or commit an existing node's staged payload before treating it as graph state.
 8. Execute and replan continuously.
    - For exact execution and compute request shapes, load [references/flywheel-mcp-tool-map.md](references/flywheel-mcp-tool-map.md) and [references/experiment-design-protocol-autonomous.md](references/experiment-design-protocol-autonomous.md).
    - Use `flywheel_launch_execution` (MCP) or `flywheel executions:launch` (CLI) when the branch can run as a Flywheel node execution without a separate leased machine, and inspect terminal status before commit.
-   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. In MCP mode use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants(status=active, approval_session_id=<session_id>)`, call `flywheel_compute_list_options`, recommend one offer deterministically and present up to two alternatives, wait for explicit user confirmation (or explicit user override offer id), then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready. In CLI mode use the parallel `flywheel compute-grants:request-approval` → `flywheel compute-grants:list` → `flywheel compute:options` → `flywheel compute:acquire` → `flywheel compute:status` → `flywheel compute:connection` sequence.
+   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. Follow the [MCP](references/flywheel-mcp-tool-map.md#empirical-workflow) or [CLI](references/flywheel-cli-tool-map.md#empirical-workflow) empirical workflow. Inspect the full catalog, filter to allowed offers, and select the offer and region first. Recommend one offer deterministically and present up to two alternatives; wait for explicit user confirmation or an explicit allowed-offer override before requesting approval. Then follow the map's approval-status branches, grant resolution, acquisition, readiness polling, and connection steps.
    - Spawn up to `k` workers for distinct executable frontier nodes.
    - For `k > 1`, apply the list-options -> recommendation -> explicit confirmation boundary per worker before each worker-specific acquire call.
    - Route additional viable branches sequentially when there are more than `k` worthwhile directions.
@@ -104,16 +124,16 @@ Before execution, recover or establish these inputs:
    - 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`.
 
-9. Commit after the node snapshot is coherent with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI).
-   - Commit resolved nodes once `content`, `summary`, artifacts, tags, executions, and graph edges make the snapshot coherent.
-   - Leave unresolved plan nodes staged.
+9. Persist each coherent node snapshot.
+   - For MCP, commit existing nodes with their active lease session, current base revision, and full staged payload; new nodes use `flywheel_commit_new_node` with their caller-local ID and parent IDs.
+   - For CLI, direct hosted mutations already post repository commits, while local `repo:` edits require the separate local `repo:commit` and optional user-requested `repo:push`.
 
 ## Result Contract
 
 When the skill completes a pass, it should leave behind:
 
 - One persisted control node containing the canonical run contract.
-- Zero or more staged frontier nodes up to the current `n` and `k` limits.
+- Zero or more persisted frontier nodes up to the current `n` and `k` limits.
 - Zero or more committed resolved nodes, once their durable content and artifacts are coherent.
 - Uploaded artifacts for completed empirical work when evidence exists, or an explicit artifact-free rationale in node content when artifacts are absent by design.
 - Released managed compute if any lease was acquired during the pass.
@@ -130,16 +150,13 @@ controller, load [references/INTERFACES.md](references/INTERFACES.md).
 
 Use this storage convention:
 
-1. Reuse an existing control node when one already governs the same frontier;
-   otherwise create one with `flywheel_commit_new_node` (MCP) or `flywheel nodes:commit-new` (CLI).
+1. Reuse an existing control node when one already governs the same frontier; otherwise persist a new MCP node with `flywheel_commit_new_node` or, for CLI, use the destination-appropriate hosted or local repository workflow.
 2. Put the canonical contract in node `content`.
 3. Put a one-line synopsis in `summary`.
 4. Put the run rationale, continuation rule, or prioritization logic in `content`.
-5. Before committing control-node edits, acquire or refresh the stage lease with `flywheel_acquire_stage_lease` (and `flywheel_heartbeat_stage_lease` for long edits) — or in CLI mode, `flywheel nodes:stage:lease:acquire` and `flywheel nodes:stage:lease:heartbeat`.
-6. Read the control node with `flywheel_get_node` (MCP) or `flywheel nodes:get` (CLI) before later replans that need
-   a fresh `expected_revision` revision token for optimistic-locking writes.
-7. Commit the control node with `flywheel_commit_node` (MCP) or `flywheel nodes:commit` (CLI) once the contract is
-   coherent, even if executable frontier nodes remain staged or in progress.
+5. For an existing MCP control node, read current state, acquire or refresh the lease with its session ID and base revision, then commit the same values with full staged payload. A direct hosted CLI mutation is an immediate repository commit; a local CLI edit must complete its separate local commit lifecycle.
+6. Before later replans, read the control node from the destination where it was persisted: `flywheel_get_node` for MCP, `flywheel repo:node:get` with the same local repository selected for local CLI, or `flywheel hosted:node:get` for hosted CLI.
+7. Persist the coherent control node before proceeding. Do not treat caller-local MCP staging or uncommitted local CLI operations as durable control state.
 
 Canonical contract shape:
 
@@ -171,4 +188,4 @@ approval cap from node state alone.
 - Keep the flywheel-auto skill graph-local: future continuation and stopping decisions should be derivable from the persisted node state rather than from fresh chat context.
 - Do not ask follow-up questions after the control contract is coherent unless a contradiction, missing required approval, or tool/runtime failure makes autonomous continuation impossible.
 
-See also: invoke `$flywheel-to-graph` to port source material into Flywheel without implicit execution, invoke `$flywheel-reproduce` to graphify claim-bearing sources and run budgeted validation branches, and invoke `$flywheel-lookahead` to stage next-step frontier nodes from existing graph state without execution.
+See also: invoke `$flywheel-to-graph` to port source material into Flywheel without implicit execution, invoke `$flywheel-reproduce` to graphify claim-bearing sources and run budgeted validation branches, and invoke `$flywheel-lookahead` to persist next-step frontier nodes from existing graph state without execution.

package/skills/flywheel-auto/evals/evals.json

@@ -2,7 +2,7 @@
   {
     "id": "continuation-from-existing-frontier",
     "prompt": "Use $flywheel-auto to continue a Flywheel frontier that already has a persisted control node. Keep going under the existing credit cap and do not ask again for the objective or budget unless the control node is missing or contradictory.",
-    "expected_output": "Read the persisted contract from the control node content before replanning, continue from that stored objective and budget, avoid re-asking for the objective or budget when the control node is coherent, and leave behind an updated control node plus staged or committed frontier work.",
+    "expected_output": "Read the persisted contract from the control node content before replanning, continue from that stored objective and budget, avoid re-asking for the objective or budget when the control node is coherent, and leave behind an updated control node plus persisted or committed frontier work.",
     "files": []
   },
   {

package/skills/flywheel-auto/references/INTERFACES.md

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

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

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