@paradigma-inc/flywheel 0.1.16 → 0.1.25

package/README.md

@@ -107,6 +107,14 @@ Reruns refresh every already-installed bundled skill in place and install any
 newly bundled skills from the updated package. They do not create side-by-side
 copies for the same scope and agent location.
 
+If you choose to refresh via `skills experimental_sync` instead of rerunning
+setup, install Flywheel locally in that project first:
+
+```bash
+npm install --save-dev @paradigma-inc/flywheel@latest
+npx skills experimental_sync --agent codex -y
+```
+
 ## Supported Hosts For Bundled Skill Install
 
 - Claude Code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.16",
+  "version": "0.1.25",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/skills/flywheel/SKILL.md

@@ -50,6 +50,7 @@ Choose one primary file first, then add at most one supporting file only if need
 - Prefer concrete steps and decision points over long narrative explanations.
 - Do not run broad document reads; load only what is required by the current request.
 - Do not start compute-heavy execution before design intent is clear.
+- When another specialized Flywheel skill is explicitly invoked, this skill provides background guidance only and must not override that skill's workflow rules.
 - For managed compute cleanup in autonomous runs, default to releasing only
   known leases (leases acquired in the current run or explicitly selected by
   the user).

package/skills/flywheel/compute/managed-compute.md

@@ -14,8 +14,9 @@ Flywheel can provision managed GPU instances for you from providers like Lambda
    ```
 
 2. **Approve a budget.** Flywheel opens an approval page in your browser where you set a spending cap for managed compute acquisition.
-3. **The agent handles the rest.** It acquires a machine, waits for it to become ready, and gets SSH access automatically. Provisioning typically takes a few minutes — the agent polls for readiness in the background.
-4. **Release when done.** When you're finished, the agent releases the lease. You can also release leases from the WebUI at any time.
+3. **Review and choose a GPU.** The agent lists current offers, recommends one option with rationale, presents alternatives, and waits for your explicit confirmation before acquiring.
+4. **The agent acquires and connects.** After explicit confirmation, the agent acquires a machine, waits for it to become ready, and gets SSH access automatically. Provisioning typically takes a few minutes — the agent polls for readiness in the background.
+5. **Release when done.** When you're finished, the agent releases the lease. You can also release leases from the WebUI at any time.
 
 For autonomous runs, agents should default to releasing only known leases
 (leases acquired in the current run or explicitly selected by the user). If
@@ -42,6 +43,114 @@ Compute is billed against your Flywheel credits balance, which is separate from
 
 For a focused reference, see `compute/credits-and-billing.md`.
 
+## Recommendation procedure
+
+### Step 1 - Filter to allowed options
+
+- Input: `options` from `flywheel_compute_list_options`.
+- Keep only entries where `allowed == true`.
+- If empty, return "empty option list" failure mode and stop.
+
+### Step 2 - Extract task signals from node text
+
+- Read `node.content`, `node.hypothesis`, `node.summary`.
+- Extract:
+  - `weight_class` in `{light, medium, heavy, unknown}`
+  - `expected_runtime_hours`
+  - `min_vram_gb`
+- Defaults:
+  - `expected_runtime_hours`: `1` for light, `3` for medium, `8` for heavy, `unknown` when weight is unknown.
+  - `min_vram_gb`: `0` for light, `24` for medium, `40` for heavy.
+- If any signal is `unknown`, ask exactly one clarifying question:
+  - "Roughly what size model and how long do you expect to run?"
+- LLM judgment is allowed only in this step.
+
+### Step 3 - Apply affordability filter
+
+- Compute `runway_hours = budget_remaining_cents / price_cents_per_hour` for each option.
+- Drop options where `runway_hours < expected_runtime_hours * 1.25`.
+- `1.25` is fixed in this issue; do not change it.
+- If empty, return "all options over cap" failure mode and stop.
+
+### Step 4 - Apply minimum VRAM filter
+
+- Drop options where `gpu_memory_gb < min_vram_gb`.
+- If this would empty the set, keep the Step 3 set and mark `VRAM-constrained fallback`.
+- Use the Step 4-qualified set for subsequent ranking, alternatives, and retries.
+- Use the Step 3 survivors for those later decisions only when `VRAM-constrained fallback` is active.
+
+### Step 5 - Rank and pick recommendation
+
+Evaluate buckets in this order and stop at the first non-empty bucket:
+
+1. Preferred + affordable + VRAM-met (`offer_id` in `preferred_offer_ids`)
+2. Affordable + VRAM-met
+3. Affordable fallback (when `VRAM-constrained fallback` is active)
+
+Sorting rules:
+
+- Buckets 1 and 2 primary sort: cheapest `price_cents_per_hour`.
+- Bucket 3 primary sort: largest `gpu_memory_gb`, then cheapest on tie.
+
+Tie-breakers (only when primary sort values are exactly equal):
+
+1. `availability_mode == live_capacity` before `allocation_time`
+2. `price_kind == provider_reported` before `estimate`
+3. more `regions` entries first
+4. lexicographic `offer_id`
+
+### Step 6 - Build recommendation rationale
+
+Include:
+
+- GPU identity: `{gpu_model} ({gpu_memory_gb}GB)`
+- Hourly rate in dollars per hour
+- Estimate suffix when `price_kind == estimate`
+- Runway statement using `budget_remaining_cents`
+- Weight-class match statement
+- Availability note only when non-default
+- Provenance tag for preferred-list pick or VRAM fallback
+
+### Step 7 - Select up to two alternatives
+
+From the active candidate set (Step 4-qualified set by default; Step 3 survivors only when `VRAM-constrained fallback` is active), fill at most two slots in this order:
+
+1. Reliability alternative (only if recommendation is `allocation_time`): cheapest `live_capacity`
+2. Cheaper alternative: strictly cheaper than recommendation
+3. Headroom alternative: strictly higher `gpu_memory_gb` than recommendation
+
+Display order:
+
+1. recommendation first
+2. filled alternatives in slot order
+
+Never display more than three total options.
+
+### Step 8 - Require confirmation and handle acquire failure
+
+- Wait for explicit user confirmation (or explicit user override offer id) before `flywheel_compute_acquire`.
+- On acquire failure due to capacity:
+  1. pick next-best candidate from the active candidate set (excluding failed offer),
+  2. same provider -> retry immediately without re-confirmation,
+  3. different provider -> ask user to re-confirm before retry,
+  4. cap retries at 3 total acquire attempts per user confirmation,
+  5. for `flywheel-auto` with `k > 1`, apply retry cap and confirmation boundary per worker.
+
+Fixed numeric defaults for this flow:
+
+- `1`, `3`, `8` runtime defaults
+- affordability multiplier `1.25`
+- acquire retry cap `3`
+
+## Presenting the options
+
+- Always show the recommended offer first with rationale.
+- Then show up to two alternatives.
+- Always wait for explicit user confirmation before calling `flywheel_compute_acquire`.
+- If the user provides an explicit offer-id override, Treat as first-class and proceed with that selected offer after confirmation.
+
+For persistent preference, set `preferred_offer_ids` in the node compute policy.
+
 ## [](https://flywheel.paradigma.inc//#tips)Tips
 
 - Provisioning takes a few minutes — the agent polls automatically, so you don't need to babysit it.

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

@@ -141,7 +141,7 @@ Typical flow:
 1. `mcp__flywheel__flywheel_branch_node` or `mcp__flywheel__flywheel_stage_node_create`
 2. `mcp__flywheel__flywheel_stage_node_update` 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` or `mcp__flywheel__flywheel_list_approval_sessions` when you need to resolve the approved `compute_grant_id`
+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.

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

@@ -1,160 +1,148 @@
 # Flywheel MCP Tool Map
 
-This reference describes the Flywheel MCP tool families and the common runtime
-contract expected by the public Flywheel skill.
+Contract-aligned routing guide for Flywheel MCP tool usage.
 
-Use it as a routing guide, not as a session snapshot. Always verify the exact
-tool surface exposed by your current MCP host before executing critical flows.
+Flywheel is a graph-based system for tracking research work, decisions, and evidence over time. Flywheel MCP is the tool interface for reading and updating that graph. You can discover, create, and manage nodes. You can collaborate with other users and use managed compute.
 
 ## Core Contract Expectations
 
-- Node lifecycle and graph-mutation flows use optimistic locking
-  (`expected_revision`).
-- Node commits require `kind`, `outcome`, and `summary`.
-- `kind` is typically `insight` or `empirical`.
-- `insight` commits require non-empty `insights`.
-- `empirical` commits require a non-empty `hypothesis`; completed empirical
-  commits also require artifacts or a `no_artifacts_reason`.
-- Artifact publish is a two-step flow:
-  prepare upload, upload raw bytes to returned signed URLs, then finalize
-  the upload batch.
+- Use `flywheel_get_contract` + `flywheel_get_contract_section` as canonical contract references.
+- Node state is canonical durable state; avoid relying on ephemeral transcript state.
+- Node kind (`untyped`, `empirical`, `insight`) is an explicit durable field.
+- Node references include immutable `node_id` and optional immutable `slug_name`; prefer communicating both together for human clarity and disambiguation.
+- Insight nodes should represent conceptual observations (theoretical insights, intuitions, motivations, decision-relevant framing); empirical nodes should represent experiments with explicit hypotheses and measured outcomes.
+- Graph topology should encode logical/causal relations between concepts and experiments. Avoid defaulting to shallow root-only branching unless work items are truly independent.
+- For empirical work, publish evidence with `flywheel_prepare_artifact_uploads`, upload raw file bytes, then `flywheel_finalize_artifact_uploads` before commit.
+- Artifact metadata records expose a non-empty `title` suitable for display labels; title normalization must never derive from `storage_url`.
 
 ## Tool Families
 
-### Session, Auth, and Contract
-
-- `mcp__flywheel__flywheel_auth_status`
-- `mcp__flywheel__flywheel_get_contract`
-- `mcp__flywheel__flywheel_get_contract_section`
-- `mcp__flywheel__flywheel_get_credits_balance`
-
-### Node Discovery and Read
-
-- `mcp__flywheel__flywheel_list_nodes`
-- `mcp__flywheel__flywheel_get_node`
-- `mcp__flywheel__flywheel_get_node_tree`
-- `mcp__flywheel__flywheel_get_node_ancestry`
-- `mcp__flywheel__flywheel_summarize_node_tree`
-- `mcp__flywheel__flywheel_get_campaign_snapshot`
-- `mcp__flywheel__flywheel_list_audit`
-
-### Node Mutation, Branching, and Commit
-
-- `mcp__flywheel__flywheel_stage_node_create`
-- `mcp__flywheel__flywheel_stage_node_update`
-- `mcp__flywheel__flywheel_commit_node`
-- `mcp__flywheel__flywheel_branch_node`
-- `mcp__flywheel__flywheel_merge_nodes`
-- `mcp__flywheel__flywheel_add_parent`
-- `mcp__flywheel__flywheel_remove_parent`
-- `mcp__flywheel__flywheel_delete_node`
-- `mcp__flywheel__flywheel_bulk_delete_nodes`
-
-### Access Policy and Collaboration
-
-- `mcp__flywheel__flywheel_get_node_sharing`
-- `mcp__flywheel__flywheel_set_sharing_for_node`
-- `mcp__flywheel__flywheel_set_sharing_for_nodes`
-
-### Tags and Graph Annotation
-
-- `mcp__flywheel__flywheel_create_node_tag`
-- `mcp__flywheel__flywheel_update_node_tag`
-- `mcp__flywheel__flywheel_delete_node_tag`
-- `mcp__flywheel__flywheel_set_node_tag_assignments`
+### Discovery and sharing
+
+- `flywheel_auth_status` (read; scopes: `read`; HTTP: `GET /auth/status`; core surface): Return Flywheel auth status for the current access token.
+- `flywheel_get_credits_balance` (read; scopes: `read`; HTTP: `GET /credits`; core surface): Return current user credits balance and lifetime counters.
+- `flywheel_updates_list` (read; scopes: `read`; HTTP: `GET /mcp/updates`; core surface): List in-app updates/announcements for the signed-in user.
+- `flywheel_updates_hide` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/{announcement_id}/hide`; core surface): Mark one update as hidden for the current user (Don't show again).
+- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; HTTP: `POST /mcp/updates/hide-all-active`; core surface): Hide all active updates for the current user (Don't show all active again).
+- `flywheel_updates_unhide` (mutating; scopes: `write`; HTTP: `DELETE /mcp/updates/{announcement_id}/hide`; core surface): Restore one hidden update for the current user.
+- `flywheel_list_nodes` (read; scopes: `read`; HTTP: `GET /mcp/nodes`; full-surface only): List nodes with optional owners/writers/visibility filters and projection control (`core`, `topology`, `full`).
+- `flywheel_resolve_node_slug` (read; scopes: `read`; HTTP: `GET /mcp/nodes/resolve-by-slug`; core surface): Resolve a node by slug_name with explicit conflict handling (`unique`, `context_resolved`, `ambiguous`, `not_found`).
+- `flywheel_get_node_sharing` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/sharing`; full-surface only): Get node sharing for one node (owner/collaborators/visibility).
+- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/sharing`; full-surface only): Set sharing for one owned node (collaborators/private-unlisted-public visibility).
+- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/sharing/bulk`; full-surface only): Apply one sharing configuration across multiple owned nodes in bulk.
+- `flywheel_get_node` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}`; core surface): Get one node by node_id.
+- `flywheel_create_node_tag` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{root_node_id}/tags`; full-surface only): Create one graph tag from a root node.
+- `flywheel_update_node_tag` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Update one graph tag from a root node.
+- `flywheel_delete_node_tag` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}`; full-surface only): Delete one graph tag from a root node.
+- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; HTTP: `PUT /mcp/nodes/{node_id}/tags`; full-surface only): Set graph tag assignments for one node.
+- `flywheel_get_node_tree` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/tree`; full-surface only): Get a root-aware bounded tree/DAG projection for an anchor node.
+- `flywheel_get_node_ancestry` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/ancestry`; full-surface only): Get ordered ancestry metadata from an anchor node to root boundaries.
+- `flywheel_get_campaign_snapshot` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/campaign/snapshot`; core surface): Read the current campaign snapshot for a node's root campaign, including configured views and derived records.
+- `flywheel_list_audit` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/audit`; full-surface only): List node MCP audit events.
+
+### Node stage and commit
+
+- `flywheel_commit_new_node` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/commit-new`; full-surface only): Commit a locally staged new node into canonical storage and return the persisted node.
+- `flywheel_acquire_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/stage/lease/acquire`; full-surface only): Acquire a session-scoped stage lease for an existing node before local staged edits.
+- `flywheel_heartbeat_stage_lease` (mutating; scopes: `write`; HTTP: `POST /mcp/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 /mcp/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 /mcp/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 /mcp/nodes/{node_id}/branch`; full-surface only): Create a child branch node.
+- `flywheel_merge_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/merge`; full-surface only): Merge nodes with caller-resolved node payload.
+- `flywheel_add_parent` (mutating; scopes: `write`; HTTP: `POST /mcp/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 /mcp/nodes/{node_id}/parents/remove`; full-surface only): Detach one parent edge from a node without deleting the node.
+- `flywheel_delete_node` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}`; full-surface only): Delete a node subtree.
+- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/bulk-delete`; full-surface only): Delete multiple node subtrees in one operation.
 
 ### Artifacts
 
-- `mcp__flywheel__flywheel_list_artifacts`
-- `mcp__flywheel__flywheel_get_artifact`
-- `mcp__flywheel__flywheel_get_artifact_preview`
-- `mcp__flywheel__flywheel_prepare_artifact_uploads`
-- `mcp__flywheel__flywheel_finalize_artifact_uploads`
-- `mcp__flywheel__flywheel_set_artifact_note`
-- `mcp__flywheel__flywheel_delete_artifact`
-
-Common artifact types include:
-`text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`,
-`checkpoint`, and `diff_carousel`.
-
-### Export and Import
-
-- `mcp__flywheel__flywheel_export_subgraph`
-- `mcp__flywheel__flywheel_import_subgraph`
-- `mcp__flywheel__flywheel_export_summary`
-- `mcp__flywheel__flywheel_export_summary_stream`
-- `mcp__flywheel__flywheel_export_summary_pdf`
-- `mcp__flywheel__flywheel_export_summary_render_pdf`
+- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; HTTP: `POST /mcp/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 /mcp/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_list_artifacts` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts`; core surface): List node artifacts.
+- `flywheel_get_artifact` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Get one artifact by id.
+- `flywheel_delete_artifact` (mutating; scopes: `write`; HTTP: `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}`; core surface): Delete one artifact by id with optimistic locking.
+- `flywheel_set_artifact_note` (mutating; scopes: `write`; HTTP: `PATCH /mcp/nodes/{node_id}/artifacts/{artifact_id}/note`; core surface): Set or clear one artifact note with optimistic locking.
 
 ### Executions
 
-- `mcp__flywheel__flywheel_launch_execution`
-- `mcp__flywheel__flywheel_list_executions`
-- `mcp__flywheel__flywheel_terminate_execution`
-
-### Managed Compute
-
-- `mcp__flywheel__flywheel_approval_session_heartbeat`
-- `mcp__flywheel__flywheel_list_approval_sessions`
-- `mcp__flywheel__flywheel_expire_approval_session`
-- `mcp__flywheel__flywheel_request_compute_grant_approval`
-- `mcp__flywheel__flywheel_list_compute_grants`
-- `mcp__flywheel__flywheel_compute_list_options`
-- `mcp__flywheel__flywheel_compute_acquire`
-- `mcp__flywheel__flywheel_compute_status`
-- `mcp__flywheel__flywheel_compute_connection`
-- `mcp__flywheel__flywheel_compute_release`
-- `mcp__flywheel__flywheel_compute_release_all`
-
-### Campaign Budgets (Organizer Flows)
-
-- `mcp__flywheel__flywheel_list_campaign_budgets`
-- `mcp__flywheel__flywheel_create_campaign_budget`
-- `mcp__flywheel__flywheel_update_campaign_budget`
-- `mcp__flywheel__flywheel_revoke_campaign_budget`
-
-### Migration Helpers
-
-Some installations may expose migration-only helper tools with hashed names.
-Treat these as specialized one-off tools, not part of day-to-day research
-workflows.
+- `flywheel_launch_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions`; core surface): Launch node execution.
+- `flywheel_list_executions` (read; scopes: `read`; HTTP: `GET /mcp/nodes/{node_id}/executions`; core surface): List node executions.
+- `flywheel_terminate_execution` (mutating; scopes: `write`; HTTP: `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate`; core surface): Terminate a node execution.
+
+### Compute and budgets
+
+- `flywheel_compute_list_options` (read; scopes: `compute`; HTTP: `GET /mcp/nodes/{node_id}/compute/options`; core surface): List managed compute options allowed for a node. When using grant-backed compute, pass the same compute_grant_id you will use for acquire.
+- `flywheel_compute_status` (read; scopes: `compute`; HTTP: `GET /mcp/compute/status`; core surface): Read managed compute lease status for the current user and current lease_control_token scope. Lease rows include ownership flags so hosts can distinguish user-owned leases from sponsor-visible campaign leases. When checking a grant-backed lease, reuse the same compute_grant_id passed to acquire.
+- `flywheel_compute_connection` (read; scopes: `compute`; HTTP: `GET /mcp/compute/connection`; core surface): Read SSH connection material for an active managed compute lease once flywheel_compute_status indicates the lease is usable. This tool is token-scoped to lease_control_token and only leases owned by the current user are connectable. Pass lease_id or node_id to disambiguate when needed.
+- `flywheel_approval_session_heartbeat` (read; scopes: `compute`; HTTP: `POST /mcp/approval-sessions/heartbeat`; core surface): Create or refresh a compute-grant approval session for the current MCP host session.
+- `flywheel_list_approval_sessions` (read; scopes: `compute`; HTTP: `GET /mcp/approval-sessions`; core surface): List approval sessions visible to the current user.
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; HTTP: `POST /mcp/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 /mcp/compute/grants`; core surface): List active/exhausted compute grants available to the current user.
+- `flywheel_list_campaign_budgets` (read; scopes: `compute`; HTTP: `GET /mcp/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 /mcp/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 /mcp/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 /mcp/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.
+- `flywheel_compute_release` (mutating; scopes: `compute`; HTTP: `POST /mcp/compute/release`; 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: `POST /mcp/compute/release-all`; 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.
+
+### 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 /mcp/export`; full-surface only): Export selected graph/subgraph nodes as JSON.
+- `flywheel_import_subgraph` (mutating; scopes: `write`; HTTP: `POST /mcp/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 /mcp/nodes/{node_id}/summary`; full-surface only): Summarize a node tree using node fields only.
+- `flywheel_export_summary` (read; scopes: `read`; HTTP: `POST /mcp/export-summary`; full-surface only): Generate markdown summary for selected nodes.
+- `flywheel_export_summary_stream` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-stream`; full-surface only): Generate summary stream events for selected nodes.
+- `flywheel_export_summary_pdf` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-pdf`; full-surface only): Generate PDF summary for selected nodes.
+- `flywheel_export_summary_render_pdf` (read; scopes: `read`; HTTP: `POST /mcp/export-summary-render-pdf`; full-surface only): Render provided markdown to PDF and embed export metadata.
 
 ## Practical Tool Sequences
 
-### Insight Node Flow
-
-1. `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update`
-3. `mcp__flywheel__flywheel_commit_node`
-
-### Empirical Node With Artifacts
-
-1. `mcp__flywheel__flywheel_stage_node_create`
-2. `mcp__flywheel__flywheel_stage_node_update`
-3. Run experiment or compute steps
-4. `mcp__flywheel__flywheel_prepare_artifact_uploads`
-5. Upload artifact bytes to signed URLs
-6. `mcp__flywheel__flywheel_finalize_artifact_uploads`
-7. `mcp__flywheel__flywheel_commit_node`
-
-### Managed Compute Flow
-
-1. `mcp__flywheel__flywheel_approval_session_heartbeat`
-2. `mcp__flywheel__flywheel_request_compute_grant_approval`
-3. `mcp__flywheel__flywheel_list_compute_grants` (if needed)
-4. `mcp__flywheel__flywheel_compute_acquire`
-5. `mcp__flywheel__flywheel_compute_status` until ready
-6. `mcp__flywheel__flywheel_compute_connection`
-7. `mcp__flywheel__flywheel_compute_release` (or `..._release_all`)
-
-### Share a Graph With Collaborators
-
-1. `mcp__flywheel__flywheel_get_node_sharing`
-2. `mcp__flywheel__flywheel_set_sharing_for_node` (or `..._for_nodes`)
-3. `mcp__flywheel__flywheel_export_summary` or `..._export_subgraph` for handoff
-
-## Safety Notes
-
-- Prefer `get_contract` before implementing strict assumptions in automation.
-- Avoid call-order assumptions not mandated by contract.
-- Keep checks bounded: list/read first, then mutate only the intended nodes.
+### List Owned Nodes
+
+1. `flywheel_list_nodes` with `{'owners': ['me'], 'projection': 'core'}`.
+
+### Safe Node Update
+
+1. `flywheel_get_node`: Read latest node state before mutating fields.
+2. `flywheel_acquire_stage_lease`: Acquire a session-scoped stage lease before editing an existing node locally.
+3. `flywheel_commit_node`: Commit with `stage_session_id`, `base_committed_revision`, and full `staged_payload` once terminal and contract-complete.
+
+### Empirical Workflow
+
+1. `flywheel_commit_new_node`: Commit a local staged new node to canonical storage as the first persistence boundary.
+2. `flywheel_commit_node`: Commit staged empirical fields with `stage_session_id`, `base_committed_revision`, and a full `staged_payload` once the working state is ready to publish.
+3. `flywheel_request_compute_grant_approval`: If compute is needed, request budget approval context first. Branch on response status.
+4. Branch on `flywheel_request_compute_grant_approval.status`: Branch by response status (`already_approved`, `approval_required`, `insufficient_credits`).. if `already_approved` then `reuse_compute_grant_id`: Use returned `compute_grant_id` directly for flywheel_compute_acquire.. if `approval_required` then `present_approval_url_to_user`: Present `approval_url` to the user; the user opens it and confirms budget approval.; `flywheel_list_compute_grants`: After approval, list active grants for the current `approval_session_id` and use the returned `compute_grant_id` for acquire.. if `insufficient_credits` then `request_user_credit_top_up`: No `approval_url` is returned. Ask the user to add credits, then retry flywheel_request_compute_grant_approval.
+5. `flywheel_compute_acquire`: Acquire lease with `compute_grant_id`; include `approval_session_id` from approval response.
+6. `flywheel_compute_status`: Poll until the active lease is ready; follow `recommended_next_action`.
+7. `flywheel_launch_execution`: Launch execution once compute and inputs are ready.
+8. `flywheel_list_executions`: Poll until execution reaches terminal status.
+9. `flywheel_prepare_artifact_uploads`: Prepare signed upload URLs for empirical evidence.
+10. `raw_file_upload`: Upload raw bytes to each signed URL with required headers.
+11. `flywheel_finalize_artifact_uploads`: Finalize prepared uploads before commit, or set `no_artifacts_reason` when intentionally artifact-free.
+12. `flywheel_commit_node`: Commit terminal empirical node once contract requirements are satisfied.
+
+## Runtime Guidance
+
+- `flywheel_resolve_node_slug`: resolve human-facing slug references. If response status is `ambiguous`, ask the user to confirm the intended node_id before mutating anything.
+- `flywheel_get_node`: read the current node state before writes.
+- `flywheel_acquire_stage_lease`, `flywheel_heartbeat_stage_lease`, `flywheel_release_stage_lease`: coordinate session-scoped local staged edits for an existing node before commit.
+- `flywheel_get_campaign_snapshot`: read the current derived campaign state for this node's root campaign instead of inferring standings from freeform text.
+- `flywheel_get_node_sharing`: after sharing writes, verify with flywheel_get_node_sharing before reporting private/shared/public state.
+- `flywheel_compute_status`: check first when work may need managed compute (GPU), using the active lease_control_token from host context (or pass it explicitly).
+- `flywheel_list_compute_grants`: list active compute grants (funded by user/root budgets) and select one `compute_grant_id` for acquisition.
+- `flywheel_request_compute_grant_approval`: request/confirm budget before acquire and choose a budget source (`user` or `root`); branch on status (`already_approved`, `approval_required`, `insufficient_credits`).
+- `flywheel_compute_connection`: read SSH connection material for the active user lease once status indicates the lease is usable, scoped by lease_control_token.
+- `flywheel_compute_list_options`: use when a lease is needed and no suitable active lease exists, then select explicit provider-qualified `offer_id` (`provider::offer_id`) and `region`. Consider each option's `availability_mode`: `live_capacity` means provider-reported capacity, `allocation_time` means capacity is confirmed only when `flywheel_compute_acquire` attempts provisioning.
+- `flywheel_compute_acquire`: provision compute once requirements are clear. This requires a valid `compute_grant_id` and returns lease/provisioning state only (not SSH key material). Capture `compute.lease_control_token` from the response for follow-up lease control tools.
+- `flywheel_compute_release`: release compute when no longer needed, scoped by lease_control_token.
+- `flywheel_launch_execution`, `flywheel_list_executions`, `flywheel_terminate_execution`: manage execution status transitions.
+- `flywheel_prepare_artifact_uploads`: prepare one or more signed raw-file upload requests for concrete deliverables/evidence produced by the work.
+- `flywheel_finalize_artifact_uploads`: finalize a staged artifact batch and append all uploaded artifacts in one revision bump.
+- `flywheel_delete_artifact`: remove an accidental/obsolete node artifact.
+- `flywheel_list_artifacts`, `flywheel_get_artifact`: inspect node artifact metadata (`title` is the display label) and consume `storage_url` for raw artifact bytes only.
+- `flywheel_commit_new_node`, `flywheel_commit_node`: publish the caller's full staged payload for an existing node once terminal and contract-complete; requires an active stage lease and explicit `base_committed_revision`.

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

@@ -9,6 +9,14 @@ npx @paradigma-inc/flywheel uninstall
 
 `uninstall` removes Flywheel MCP entries from host config files.
 
+If you choose to refresh via `skills experimental_sync` instead of rerunning
+setup, install Flywheel locally in that project first:
+
+```bash
+npm install --save-dev @paradigma-inc/flywheel@latest
+npx skills experimental_sync --agent codex -y
+```
+
 ## FAQ: How Do I Migrate from the Previous OAuth-Based MCP Client Setup?
 
 If you installed Flywheel MCP before April 2026, migrate to the newer, more stable API key authentication setup with:

package/skills/flywheel-auto/SKILL.md

@@ -21,7 +21,8 @@ Before execution, recover or establish these inputs:
   - Ask only when a required execution input cannot be recovered from explicit user instructions, current conversational context, or recent graph state.
   - If start nodes cannot be recovered from explicit ids/slugs, named current context, or recent graph context, ask once.
   - If the objective is missing, ask once; if the user refuses, infer it from graph context and persist it before execution.
-  - If budget ceiling, budget unit, or terminal condition is missing, ask once before execution. If the budget contract remains incomplete, keep planning but do not request compute approval or acquire compute.
+  - If budget ceiling or budget unit is missing, ask once before execution.
+  - If budget ceiling and budget unit are present but terminal condition is missing, set `terminal_condition: "budget ceiling reached"` and persist that derivation in the control node `content` before compute request or acquisition.
   - If the user gives a non-credit budget unit, persist that exact user-facing unit and derive the operational compute approval cap before acquisition.
 
 ## Working Terms
@@ -37,6 +38,7 @@ Before execution, recover or establish these inputs:
 - Use artifacts for supporting files and evidence, not as a substitute for the node's main narrative.
 - Only create graph edges for durable semantic relationships, because graphifying every wiki link floods the graph with noise that hides decision-relevant structure.
 - Treat the flywheel-auto skill as graph-local autonomous research: persist the run contract in the graph, keep the plan `n` hops ahead, and spend only within an explicit measured budget.
+- When guidance from flywheel, flywheel-lookahead, flywheel-reproduce, or flywheel-to-graph conflicts during an active $flywheel-auto run, flywheel-auto rules take precedence for compute, questioning, and stop decisions.
 - Ask only the minimum clarification questions needed to establish a coherent control contract, and ask none when the required answers are already recoverable from user instructions, conversational context, or graph state.
 - Planned nodes that are expected to produce evidence or artifacts should be typed `empirical`; planned nodes that only encode synthesis, decomposition, or decision structure should be typed `insight`.
 - Keep the control node typed `insight` and keep its `insights` non-empty so the insight commit contract stays valid.
@@ -49,12 +51,12 @@ Before execution, recover or establish these inputs:
 2. Resolve the objective and budget contract.
    - Recover required execution inputs from the current conversation and graph first. Ask only for inputs that remain genuinely missing after that recovery pass.
    - The flywheel-auto skill requires a measurable objective and an explicit terminal condition. Ask once for missing prerequisites; if the user refuses to specify an objective, infer it from the available graph context and state it explicitly before continuing.
-   - The budget contract must be explicit before execution starts. Ask once for any missing budget ceiling, budget unit, or terminal condition. If those inputs remain unavailable after one clarification round, keep planning but do not request compute approval or acquire compute.
+   - The budget contract must be explicit before execution starts. Ask once for missing budget ceiling or budget unit. When budget ceiling and budget unit are present but terminal condition is missing, derive `terminal_condition: "budget ceiling reached"` and persist that derivation into the control node `content` before any compute request or acquisition.
    - Managed compute spend is billed in Flywheel credits. If the user gives dollars, hours, or another measurable budget semantic, persist that user-facing cap explicitly and derive the operational compute approval cap before acquisition.
    - Persist the run contract in a dedicated `insight` control node for this frontier. Put the canonical contract in node `content`, keep a one-line synopsis in `summary`, and keep brief run rationale in `insights` so the commit contract stays valid.
    - The control contract must name: objective, decision criterion, start nodes, budget ceiling and unit, lookahead depth `n`, frontier width `k`, and an explicit terminal condition.
    - Later flywheel-auto replans must read the control node `content` first and continue from that persisted contract rather than from chat memory.
-   - Run the design gate from [references/experiment-design-protocol.md](references/experiment-design-protocol.md) before the first compute request: confirm objective, decision criterion, evidence plan, and budget readiness, even though later continuation decisions become graph-local.
+   - 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_stage_node_create` when needed.
@@ -78,16 +80,20 @@ Before execution, recover or establish these inputs:
    - 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.
 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.md](references/experiment-design-protocol.md).
+   - 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` 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 that case use `flywheel_request_compute_grant_approval`, resolve the approved `compute_grant_id` with `flywheel_list_compute_grants` or `flywheel_list_approval_sessions`, then `flywheel_compute_acquire`, poll `flywheel_compute_status`, and use `flywheel_compute_connection` when the lease is ready.
+   - Use managed compute when the branch needs provider or SKU choice, SSH access, a custom runtime, or longer-lived hardware. In that case 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.
    - 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.
    - 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` 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`.
+
 9. Commit after the node snapshot is coherent with `flywheel_commit_node`.
    - Commit resolved insight nodes only when they have non-empty `insights`.
    - Commit resolved empirical nodes only when outcome and artifact rules are satisfied.
@@ -102,7 +108,8 @@ When the skill completes a pass, it should leave behind:
 - Zero or more committed resolved nodes, but only when their commit contracts are satisfied.
 - Uploaded artifacts for completed empirical work, or an explicit `no_artifacts_reason` when artifacts are absent by design.
 - Released managed compute if any lease was acquired during the pass.
-- An explicit stop reason, continuation rule, or next action recorded in node state so a later pass can resume graph-locally.
+- An explicit `stop_reason` recorded in node state so a later pass can resume graph-locally.
+- If the no-branch stop clause is used, a per-candidate rejection log recorded in control node `content`.
 
 ## Persisted Control Contract
 
@@ -140,6 +147,7 @@ Canonical contract shape:
 - Lookahead depth:
 - Frontier width:
 - Terminal condition:
+- Stop reason:
 ```
 
 Use `Compute approval cap` for the operational cap that will govern managed

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

@@ -11,6 +11,12 @@
     "expected_output": "Persist the dollar-denominated budget ceiling and unit verbatim in the control node, derive an operational compute approval cap before acquisition, record both values before any compute request is made, and leave a coherent run contract behind for later continuation.",
     "files": []
   },
+  {
+    "id": "cold-start-budget-only-auto-exhaustion",
+    "prompt": "Use $flywheel-auto to continue autonomously under a budget ceiling when only the budget contract is explicit at cold start.",
+    "expected_output": "When terminal condition is missing but budget ceiling and budget unit are explicit, derive terminal condition as budget ceiling reached, continue autonomously without premature user handoff, and persist stop_reason in the committed control contract before termination.",
+    "files": []
+  },
   {
     "id": "cold-start-with-no-objective",
     "prompt": "Use $flywheel-auto to go autonomous on this Flywheel graph until you find something interesting. If I refuse to specify an objective, infer one from the graph context and make it explicit before you execute.",