@paradigma-inc/flywheel 0.1.16 → 0.1.19

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

@@ -1,203 +1,200 @@
 # Interfaces
 
-Canonical reference for Flywheel user-facing interfaces and public contracts.
-
-Last updated: 2026-04-08
-
-## Primary Clients
-
-- `project/flywheel-webui` - canonical web product UI
-- `project/flywheel-api` - canonical programmatic client interface (local + HTTP)
-- MCP hosts (Codex/Claude/ChatGPT) via `/mcp-server`
+Canonical reference for Flywheel MCP public interfaces and contract pointers.
+
+## Canonical Contract References
+
+- `flywheel_get_contract` is the top-level contract entry point.
+- `flywheel_get_contract_section(section_id)` returns section-scoped payloads.
+- Section order:
+- `quickstart` (Quickstart): Recommended first calls and section read order for onboarding.
+- `graph` (Graph): Node model, graph topology guidance, and durable behavior rules.
+- `lifecycle` (Lifecycle): Lifecycle operations, commit-time validation requirements, and reproducibility guidance.
+- `sharing` (Sharing): Sharing modes, derived visibility, collaborator roles, and query translation.
+- `artifacts` (Artifacts): Prepare/upload/finalize requirements and artifact type rules.
+- `compute` (Compute): Lease ownership, approval session, and budget source semantics.
+- `compute/troubleshooting_v1` (Compute Troubleshooting v1): Provider-specific acquire/retry hints for launch kwargs and request tuning.
+- `campaign` (Campaign Contract): Campaign projection and budget contracts plus template section pointers.
 
 ## Canonical Entity Model
 
-All interfaces operate on the same core entities:
-
-- node
-- node edge (branch/merge graph links)
-- artifact
-- execution
-- compute lease
-- compute budget
-- compute grant (session-scoped)
-
-Node snapshots are the canonical durable contract for resume, review, and
-cross-client interoperability.
-
-## Core HTTP Surface
-
-### Node lifecycle and graph
-
-- `GET /mcp/nodes`
-- `GET /mcp/nodes/{node_id}`
-- `GET /mcp/nodes/{node_id}/tree`
-- `POST /mcp/nodes/stage/create`
-- `PATCH /mcp/nodes/{node_id}/stage/update`
-- `POST /mcp/nodes/{node_id}/commit`
-- `POST /mcp/nodes/{node_id}/branch`
-- `POST /mcp/nodes/merge`
-- `DELETE /mcp/nodes/{node_id}`
-- `POST /mcp/nodes/bulk-delete`
-
-### Artifact lifecycle
-
-- `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`
-- `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`
-- `GET /mcp/nodes/{node_id}/artifacts`
-- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}`
-- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}/preview`
-- `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}`
-- `PUT /mcp/artifacts/uploads/{upload_id}`
-
-### Execution lifecycle
-
-- `POST /mcp/nodes/{node_id}/executions`
-- `GET /mcp/nodes/{node_id}/executions`
-- `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate`
-
-### Compute catalog
-
-- `GET /compute/providers`
-- `GET /compute/offers`
-- `GET /compute/offers/{provider}`
-
-### Managed compute and budgets
-
-- `GET /mcp/nodes/{node_id}/compute/options`
-- `POST /mcp/nodes/{node_id}/compute/acquire`
-- `GET /mcp/compute/status`
-- `GET /mcp/compute/connection`
-- `POST /mcp/compute/release`
-- `POST /mcp/compute/release-all`
-- `GET /mcp/compute/grants`
-- `GET /mcp/nodes/{node_id}/budgets`
-- `GET /mcp/nodes/{root_node_id}/campaign-budgets`
-- `POST /mcp/nodes/{root_node_id}/campaign-budgets`
-- `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
-- `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}`
-
-### Sharing, tags, and audit
-
-- `GET /mcp/nodes/{node_id}/sharing`
-- `PUT /mcp/nodes/{node_id}/sharing`
-- `POST /mcp/nodes/sharing/bulk`
-- `GET /mcp/nodes/{node_id}/audit`
-- `POST /mcp/nodes/{root_node_id}/tags`
-- `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}`
-- `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}`
-- `PUT /mcp/nodes/{node_id}/tags`
-
-### Export and summaries
-
-- `POST /mcp/export`
-- `POST /mcp/import`
-- `POST /mcp/export-summary`
-- `POST /mcp/export-summary-stream`
-- `POST /mcp/export-summary-pdf`
-- `POST /mcp/export-summary-render-pdf`
-
-### Auth and integrations
-
-- `GET /auth/status`
-- `GET /auth/accounts`
-- `POST /auth/accounts/merge/source-proof`
-- `POST /auth/accounts/merge/preview`
-- `POST /auth/accounts/merge`
-- `POST /auth/accounts/detach`
-- `GET /auth/integrations/status`
-- `PUT /auth/integrations/wandb`
-- `PUT /auth/integrations/huggingface`
-- `DELETE /auth/integrations/wandb`
-- `DELETE /auth/integrations/huggingface`
-
-### Analytics
-
-- `POST /analytics/events`
-- `GET /admin/analytics/kpis`
-- `GET /admin/analytics/overview`
+- Canonical durable entity: `node`.
+- Node kind values: `untyped`, `empirical`, `insight`.
+- Node references: `node_id`, `slug_name`.
+- `slug_name` format: `adjective-noun-####` (immutable when present).
+- Approval sessions and compute grants are distinct entities; approvals are session-scoped bindings.
+- Campaign projections are derived from root config and attempt submission JSON artifacts.
 
 ## MCP Tool Surface
 
-### Discovery and sharing tools
-
-- `flywheel_auth_status`
-- `flywheel_get_credits_balance`
-- `flywheel_list_nodes`
-- `flywheel_get_node`
-- `flywheel_get_node_tree`
-- `flywheel_get_node_sharing`
-- `flywheel_set_node_sharing`
-- `flywheel_bulk_set_node_sharing`
-- `flywheel_create_node_tag`
-- `flywheel_update_node_tag`
-- `flywheel_delete_node_tag`
-- `flywheel_set_node_tag_assignments`
-
-### Node and graph tools
-
-- `flywheel_stage_node_create`
-- `flywheel_stage_node_update`
-- `flywheel_commit_node`
-- `flywheel_branch_node`
-- `flywheel_merge_nodes`
-- `flywheel_delete_node`
-- `flywheel_bulk_delete_nodes`
-
-### Artifact tools
-
-- `flywheel_prepare_artifact_uploads`
-- `flywheel_finalize_artifact_uploads`
-- `flywheel_list_artifacts`
-- `flywheel_get_artifact`
-- `flywheel_get_artifact_preview`
-- `flywheel_delete_artifact`
-
-### Execution tools
-
-- `flywheel_launch_execution`
-- `flywheel_list_executions`
-- `flywheel_terminate_execution`
-
-### Compute lease and budget tools
-
-- `flywheel_compute_list_options`
-- `flywheel_request_compute_grant_approval`
-- `flywheel_list_compute_grants`
-- `flywheel_compute_acquire`
-- `flywheel_compute_status`
-- `flywheel_compute_connection`
-- `flywheel_compute_release`
-- `flywheel_compute_release_all`
-
-### Campaign budget tools
-
-- `flywheel_list_campaign_budgets`
-- `flywheel_create_campaign_budget`
-- `flywheel_update_campaign_budget`
-- `flywheel_revoke_campaign_budget`
-
-### Contract, audit, and export tools
-
-- `flywheel_get_contract`
-- `flywheel_list_audit`
-- `flywheel_summarize_node_tree`
-- `flywheel_export_subgraph`
-- `flywheel_import_subgraph`
-- `flywheel_export_summary`
-- `flywheel_export_summary_stream`
-- `flywheel_export_summary_pdf`
-- `flywheel_export_summary_render_pdf`
-
-## Legacy Archival Export
-
-Experimental settings keep legacy history export available as an archival
-migration aid. This path is read-only and outside canonical node workflows.
-
-## Related Docs
-
-- `docs/flywheel/CONCEPT.md`
-- `docs/flywheel/FLYWHEEL_MCP.md`
-- `docs/flywheel/PROVISIONING.md`
-- `docs/flywheel/ARTIFACTS.md`
-- `docs/flywheel/GIT_INTEGRATION.md`
+### Discovery and sharing
+
+- `flywheel_auth_status` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_credits_balance` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_updates_list` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_updates_hide` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_updates_hide_all_active` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_updates_unhide` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_list_nodes` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_resolve_node_slug` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_node_sharing` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_set_sharing_for_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_set_sharing_for_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_get_node` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_create_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_update_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_delete_node_tag` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_set_node_tag_assignments` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `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`)
+
+### Node lifecycle
+
+- `flywheel_stage_node_create` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_stage_node_update` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_commit_node` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_branch_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_merge_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_add_parent` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_remove_parent` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_delete_node` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_bulk_delete_nodes` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+
+### Artifacts
+
+- `flywheel_prepare_artifact_uploads` (mutating; scopes: `write`; core surface; binding: `binding_helper`)
+- `flywheel_finalize_artifact_uploads` (mutating; scopes: `write`; core surface; binding: `binding_helper`)
+- `flywheel_list_artifacts` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_artifact` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_delete_artifact` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_set_artifact_note` (mutating; scopes: `write`; core surface; binding: `operation`)
+
+### Executions
+
+- `flywheel_launch_execution` (mutating; scopes: `write`; core surface; binding: `operation`)
+- `flywheel_list_executions` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_terminate_execution` (mutating; scopes: `write`; core surface; binding: `operation`)
+
+### Compute and budgets
+
+- `flywheel_compute_list_options` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_status` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_connection` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_approval_session_heartbeat` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_approval_sessions` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_expire_approval_session` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_request_compute_grant_approval` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_compute_grants` (read; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_list_campaign_budgets` (read; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_create_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_update_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_revoke_campaign_budget` (mutating; scopes: `compute`; full-surface only; binding: `operation`)
+- `flywheel_compute_acquire` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_release` (mutating; scopes: `compute`; core surface; binding: `operation`)
+- `flywheel_compute_release_all` (mutating; scopes: `compute`; core surface; binding: `operation`)
+
+### Contract, audit, and export
+
+- `flywheel_get_contract` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_get_contract_section` (read; scopes: `read`; core surface; binding: `operation`)
+- `flywheel_export_subgraph` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_import_subgraph` (mutating; scopes: `write`; full-surface only; binding: `operation`)
+- `flywheel_summarize_node_tree` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_stream` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_pdf` (read; scopes: `read`; full-surface only; binding: `operation`)
+- `flywheel_export_summary_render_pdf` (read; scopes: `read`; full-surface only; binding: `operation`)
+
+## HTTP Surface
+
+### Discovery and sharing
+
+- `GET /auth/status` -> `flywheel_auth_status`
+- `GET /credits` -> `flywheel_get_credits_balance`
+- `GET /mcp/updates` -> `flywheel_updates_list`
+- `POST /mcp/updates/{announcement_id}/hide` -> `flywheel_updates_hide`
+- `POST /mcp/updates/hide-all-active` -> `flywheel_updates_hide_all_active`
+- `DELETE /mcp/updates/{announcement_id}/hide` -> `flywheel_updates_unhide`
+- `GET /mcp/nodes` -> `flywheel_list_nodes`
+- `GET /mcp/nodes/resolve-by-slug` -> `flywheel_resolve_node_slug`
+- `GET /mcp/nodes/{node_id}/sharing` -> `flywheel_get_node_sharing`
+- `PUT /mcp/nodes/{node_id}/sharing` -> `flywheel_set_sharing_for_node`
+- `POST /mcp/nodes/sharing/bulk` -> `flywheel_set_sharing_for_nodes`
+- `GET /mcp/nodes/{node_id}` -> `flywheel_get_node`
+- `POST /mcp/nodes/{root_node_id}/tags` -> `flywheel_create_node_tag`
+- `PATCH /mcp/nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_update_node_tag`
+- `DELETE /mcp/nodes/{root_node_id}/tags/{tag_id}` -> `flywheel_delete_node_tag`
+- `PUT /mcp/nodes/{node_id}/tags` -> `flywheel_set_node_tag_assignments`
+- `GET /mcp/nodes/{node_id}/tree` -> `flywheel_get_node_tree`
+- `GET /mcp/nodes/{node_id}/ancestry` -> `flywheel_get_node_ancestry`
+- `GET /mcp/nodes/{node_id}/campaign/snapshot` -> `flywheel_get_campaign_snapshot`
+- `GET /mcp/nodes/{node_id}/audit` -> `flywheel_list_audit`
+
+### Node lifecycle
+
+- `POST /mcp/nodes/stage/create` -> `flywheel_stage_node_create`
+- `PATCH /mcp/nodes/{node_id}/stage/update` -> `flywheel_stage_node_update`
+- `POST /mcp/nodes/{node_id}/commit` -> `flywheel_commit_node`
+- `POST /mcp/nodes/{node_id}/branch` -> `flywheel_branch_node`
+- `POST /mcp/nodes/merge` -> `flywheel_merge_nodes`
+- `POST /mcp/nodes/{node_id}/parents/add` -> `flywheel_add_parent`
+- `POST /mcp/nodes/{node_id}/parents/remove` -> `flywheel_remove_parent`
+- `DELETE /mcp/nodes/{node_id}` -> `flywheel_delete_node`
+- `POST /mcp/nodes/bulk-delete` -> `flywheel_bulk_delete_nodes`
+
+### Artifacts
+
+- `POST /mcp/nodes/{node_id}/artifacts/uploads/prepare` -> `flywheel_prepare_artifact_uploads`
+- `POST /mcp/nodes/{node_id}/artifacts/uploads/finalize` -> `flywheel_finalize_artifact_uploads`
+- `GET /mcp/nodes/{node_id}/artifacts` -> `flywheel_list_artifacts`
+- `GET /mcp/nodes/{node_id}/artifacts/{artifact_id}` -> `flywheel_get_artifact`
+- `DELETE /mcp/nodes/{node_id}/artifacts/{artifact_id}` -> `flywheel_delete_artifact`
+- `PATCH /mcp/nodes/{node_id}/artifacts/{artifact_id}/note` -> `flywheel_set_artifact_note`
+
+### Executions
+
+- `POST /mcp/nodes/{node_id}/executions` -> `flywheel_launch_execution`
+- `GET /mcp/nodes/{node_id}/executions` -> `flywheel_list_executions`
+- `POST /mcp/nodes/{node_id}/executions/{execution_id}/terminate` -> `flywheel_terminate_execution`
+
+### Compute and budgets
+
+- `GET /mcp/nodes/{node_id}/compute/options` -> `flywheel_compute_list_options`
+- `GET /mcp/compute/status` -> `flywheel_compute_status`
+- `GET /mcp/compute/connection` -> `flywheel_compute_connection`
+- `POST /mcp/approval-sessions/heartbeat` -> `flywheel_approval_session_heartbeat`
+- `GET /mcp/approval-sessions` -> `flywheel_list_approval_sessions`
+- `POST /mcp/approval-sessions/expire` -> `flywheel_expire_approval_session`
+- `tool-mediated` -> `flywheel_request_compute_grant_approval`
+- `GET /mcp/compute/grants` -> `flywheel_list_compute_grants`
+- `GET /mcp/nodes/{root_node_id}/campaign-budgets` -> `flywheel_list_campaign_budgets`
+- `POST /mcp/nodes/{root_node_id}/campaign-budgets` -> `flywheel_create_campaign_budget`
+- `PATCH /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_update_campaign_budget`
+- `DELETE /mcp/nodes/{root_node_id}/campaign-budgets/{compute_budget_id}` -> `flywheel_revoke_campaign_budget`
+- `POST /mcp/nodes/{node_id}/compute/acquire` -> `flywheel_compute_acquire`
+- `POST /mcp/compute/release` -> `flywheel_compute_release`
+- `POST /mcp/compute/release-all` -> `flywheel_compute_release_all`
+
+### Contract, audit, and export
+
+- `GET /mcp/contract` -> `flywheel_get_contract`
+- `GET /mcp/contract/sections/{section_id}` -> `flywheel_get_contract_section`
+- `POST /mcp/export` -> `flywheel_export_subgraph`
+- `POST /mcp/import` -> `flywheel_import_subgraph`
+- `GET /mcp/nodes/{node_id}/summary` -> `flywheel_summarize_node_tree`
+- `POST /mcp/export-summary` -> `flywheel_export_summary`
+- `POST /mcp/export-summary-stream` -> `flywheel_export_summary_stream`
+- `POST /mcp/export-summary-pdf` -> `flywheel_export_summary_pdf`
+- `POST /mcp/export-summary-render-pdf` -> `flywheel_export_summary_render_pdf`
+
+## Auth and Write Safety
+
+- Available scopes: `read`, `write`, `compute`.
+- Default grant scopes: `read`, `write`, `compute`.
+- Transport-required scopes: `read`.
+- Optimistic locking field: `expected_revision`.
+- Conflict status code: `409`.
+- Mutating HTTP calls require `Idempotency-Key`: `True`.
+- MCP tool transport manages idempotency keys for mutating calls: `True`.

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

@@ -0,0 +1,62 @@
+# Autonomous Experiment Design Gate
+
+Use this gate for `$flywheel-auto` runs that must continue autonomously under a
+persisted control contract.
+
+## Goal
+
+Prevent wasted spend and ambiguous stop behavior while keeping the run
+non-interactive after the control contract is coherent.
+
+## Operating Rules
+
+- Treat this gate as deterministic and non-interactive.
+- Do not wait for user acceptance once required contract fields are coherent.
+- Infer missing objective from graph state only when objective is missing and
+  the user refuses to provide one; persist the inferred objective before
+  execution.
+- Derive missing terminal condition as `budget ceiling reached` when budget
+  ceiling and budget unit are present.
+- Persist every derivation in the control node `content` before compute
+  request or acquisition.
+- Require explicit stop recording before any termination.
+
+## Required Gate Checks
+
+The run is gate-ready only when all checks below pass.
+
+1. Objective check
+   - Objective is explicit in the control contract, or inferred and persisted.
+2. Decision criterion check
+   - Decision criterion is explicit and measurable enough to compare branches.
+3. Budget contract check
+   - Budget ceiling and budget unit are explicit.
+   - If user-facing budget uses a non-credit unit, operational compute approval
+     cap is derived and both values are persisted.
+4. Terminal condition check
+   - Terminal condition is explicit.
+   - If missing while budget ceiling and unit are present, set terminal
+     condition to `budget ceiling reached` and persist the derivation.
+5. Continuation/stop recording check
+   - Control contract records continuation rule.
+   - Termination requires persisted `stop_reason` with one of:
+     `budget_exhausted`, `objective_met`, `no_viable_branch`,
+     `user_cancelled`, `runtime_error`.
+
+## Failure Handling
+
+- If any required check fails, repair the control contract from available graph
+  state and previously supplied inputs.
+- Ask only when a required field cannot be recovered from user instructions,
+  conversation, or graph state.
+- Once repaired, continue execution without adding a user-acceptance checkpoint.
+
+## Execution Handoff
+
+When gate-ready, continue with the active `$flywheel-auto` execution workflow:
+
+- persist control node updates,
+- execute or acquire compute within budget,
+- refresh lookahead after each resolved node,
+- stop only on explicit terminal conditions,
+- persist stop reason before exit.